apps/inventory and runs locally through Portless at
https://inventory.tuturuuu.localhost. Production is intended for
https://inventory.tuturuuu.com.
Web sale item picker
Record sale remembers the last explicitly selected sales period in the current browser session, separately for each workspace and signed-in actor. Completing a sale, Keep open, reopening the dialog and reloading do not replace that selection with the workspace default. An explicit No period selection is also remembered. Archived or removed periods are not selected; the existing workspace default and period-choice rules apply instead. If browser storage is blocked, the selection still survives consecutive sales while the dialog remains mounted.sale-period-selection.test.ts covers persistence and scope isolation;
season-sale-integration.test.tsx covers two consecutive Keep open sales.
Creating a sales period does not change the workspace default unless the
workspace has saved the choice to set new sales periods as the default. That
choice is off when no value is stored. Sales defaults settings and the sales
period creation screen show the same saved choice. Only the existing
sales-defaults permission can change it, and a create request cannot turn it
on. If the period is created and the default update fails, the period remains
and the failure is reported separately. A period remembered in this browser
stays selected.
Record sale shows one selectable row per product, unit and warehouse identity.
Overlapping loaded pages and repeated stock entries do not create duplicate rows
or add stock quantities. The later provided complete product snapshot supplies
amounts, prices and archived status; page position does not guarantee chronological
freshness, so server sale validation remains authoritative. Distinct products
with the same name and distinct unit/warehouse variants remain separate. Equal name or price
sort results use stock identity as a stable tie-breaker. Season eligibility and
scheduled pricing continue to apply after catalog normalization, and server
permissions and checkout validation remain authoritative.
The item list occupies the space remaining beneath the search/filter controls
and above the pinned sale footer. It scrolls within that space on mobile and
desktop, rather than stopping at a fixed list height. This behavior is covered
by sale-create-items.test.ts, sale-product-picker.test.ts and the mounted
sale-product-picker-layout.test.tsx regression; DOM checks do not establish
browser layout or customer-flow success.
Web Record sale uses two tabs: Items and Checkout. Checkout combines editable
cart, revenue details and review in compact accordions; collapsed headers retain
item counts, selected revenue targets and confirmation readiness. Missing revenue
or sale-name details open the Revenue section on entry. Going back to Items keeps
those edits and quantities. Confirmation remains an explicit action and retains
current season-price validation, required revenue fields, in-flight submission
protection, and the same request ID when retrying an uncertain response.
The Items list loads another page when its end is within 200 pixels of the
actual list viewport, including when the initial list is shorter than that
viewport. Raw page progress rearms loading even when filters/season eligibility
hide every new item. Only one page request starts at a time. A thrown or resolved
query error stops automatic loading and leaves a localized manual Load more
retry. Filters and tab/dialog closure disconnect the old observer; manual loading
also works when IntersectionObserver is unavailable. Regression evidence lives
in sale-picker-pagination.test.tsx and season-sale-integration.test.tsx;
these mounted tests do not establish live browser/provider success.
Browser offline behavior
Inventory web keeps service-worker registration disabled. Its layout explicitly usesOfflineProvider register={false} because Inventory has no worker source or
/serwist/sw.js route. Moving its routes onto the shared Start bridge does not
enable a worker or add precaching. Mobile offline storage is a separate surface.
The existing inventory-offline-create-v1 mutation endpoint retains its contract
header, stable operation identity, current actor/workspace permissions on every
retry, HTTP 201 for a first commit and HTTP 200 for a receipt replay. Missing
contract support returns its existing error; the bridge must not retry with a
legacy create request. Offline or stale checkout stays blocked, and season-merge
recovery retains its actor/workspace-scoped original request across reloads.
The bridge route-port regression is src/start-bridge/offline-handler.test.ts;
its domain and proxy boundaries use fixtures. The shared inventory-core offline
tests, season-sale-prices.test.tsx, use-season-merge-recovery.test.tsx and the
missing-worker registration regression remain required. These tests do not
substitute for an emitted Worker and browser offline acceptance.
Storefront checkout return locations
Cash receipts, Square Terminal receipts, Square POS fallback links and Polar return flows use the shopper’s Storefront mount. On the apex this ishttps://tuturuuu.com/storefront; a Storefront subdomain retains its origin.
The bridge request context supplies the current origin and mount. API forwarding
also preserves the canonical apex shopper’s Origin; unrelated Origin values
cannot select a return host.
An explicit NEXT_PUBLIC_STOREFRONT_APP_URL takes precedence, followed by
STOREFRONT_APP_URL. These configured URLs retain their path and continue to
override request-derived mounts. route-return-urls.test.ts covers each payment
flow, configuration precedence, forwarded requests and the cash receipt returned
after a completed payment’s enrichment fails.
Native Inventory presentation
The Flutter mini-app keeps Overview, Products, Sales, Manage and Storefront destinations in the established floating navigation. Overview retains Sell and Create product as visible workflows; it does not repeat the dock destinations. Manage keeps every setup collection and its permitted add action visible without a second counter dashboard. Season selection, creation, editing and archiving remain visible on Sales. Products is a scan-and-search item list. The shell navbar owns search (serverq, which matches product names) and, on iOS and Android, a scan action. Each
row shows the name, the category, an Archived label when relevant, and up to three
locations as “warehouse · unit” with the quantity at the trailing edge, then
“N more locations”. Prices, manufacturer, owner and Finance category stay in the
item editor. Quantities across different units are not summed. A null quantity
means unlimited stock and must never display as zero or a low-stock warning.
Low stock (amount <= min_amount) uses the warning tone and zero or less uses
the destructive tone. An absent stock row is shown as “No stock configured” only
when the actor may view stock; otherwise the row says “Stock hidden”, because
the products API omits stock without view-stock or create-sales permission.
Active, Archived and All pills map to the API status parameter. There are no
count chips: totals and loaded-page low-stock counts were removed as noise.
Catalog managers open the editor on tap and get Edit and Delete on long-press;
other actors have no row action until read-only item detail ships.
Products have no barcode or SKU field. A scanned Tuturuuu product link
(https://tuturuuu.com/{ws}/inventory/products/{uuid}) is fetched in the current
workspace under normal server authorization. It opens the item editor only for
catalog managers; other actors get a name search for that product, widened to
all statuses when the product is archived. A plain code without a URI scheme, up
to the API’s 500-character search limit, becomes the name search, shown as
“Name matches for …” with a Clear action. Every other payload, including other
links, product links without a UUID, Wi-Fi credentials, otpauth:, mailto:,
tel:, app intents and custom schemes, is reported as an unusable code and is
never sent to the server or shown as a query. Barcode lookup needs a schema
field and API filter and is not implied by this scanner.
Switching the status filter or query never shows rows from the previous filter:
a slow or failed load starts empty. A failed first load shows an error with
Retry rather than an empty catalog, and a failed next page shows a retry footer
instead of retrying on every scroll.
Native presentation does not change server permissions, mutation authorization,
or canonical workspace membership. Existing pending-sync indicators remain
attached to their owning rows. Regression evidence: inventory_items_page_test.dart,
inventory_items_states_test.dart, inventory_scan_test.dart, and the
compact/fractional stock widget tests.
Native Overview analytics describe the loaded sample, not workspace-wide totals.
Receipt activity groups unique dated receipts by device-local day for the selected
7- or 30-day view and reports records without dates separately. Loaded revenue
keeps currencies separate, excludes pending receipts and duplicate IDs, and
reports receipts without an explicit currency. Stock summaries keep incompatible
units separate and preserve unlimited versus unconfigured stock. These rules are
covered by inventory_analytics_redesign_test.dart.
Manage opens dedicated catalog, sales-period and audit destinations. The native
product and checkout forms retain their primary actions while options refresh;
queued deletion rows retain their existing retry or manual-conflict controls.
Verified permission hints remain isolated by account and workspace and are
revalidated online; an online denial revokes them. Server authorization remains
authoritative. inventory_access_scope_test.dart,
workspace_permissions_offline_test.dart and the Inventory editor tests cover
scope changes, revocation and pending writes.
Products, Sales and searchable forms submit through native search actions. An
empty or whitespace-only submission closes search and clears the filter. A
nonempty submission keeps results visible and dismisses the keyboard. Old shell
search callbacks cannot replace the current query or update an unmounted owner.
inventory_search_submit_test.dart covers mounted shell and standalone form
submissions; the shared Apps search policy uses the same empty-query behavior.
The product editor preserves unlimited stock when an unrelated field is edited.
Leave quantity empty to represent unlimited stock; finite zero remains zero.
Manage clears previous rows and add controls when the authenticated account or
selected workspace changes. An open setup sheet cannot submit into a different
account/workspace scope. These UI safeguards supplement server authorization.
Native Inventory writes accept pending setup selections. The dependency queue
creates referenced owners, manufacturers, categories, units, warehouses and
Finance categories before product writes, then applies their authoritative IDs.
The earlier sync-first guard is replaced by automatic prerequisite handling.
Repository regressions in inventory_setup_dependencies_test.dart cover both
product writes, all six pending references, nullable optional fields and
resource-scoped mappings. Legacy already-completed setup creates whose old API
returned no ID cannot retroactively recover local-ID provenance; that historical
limitation remains tracked in issue #5737.
This compact presentation does not establish parity for web commerce checkout,
payment providers, stock ledgers, scoped analytics, costing or effective season
pricing. Those require their existing authorized API contracts and separate
verification; today’s catalog price must not replace historical sold prices.
Automatic offline dependency sync implementation
Native period-sale creation omits optional notes when none were entered; it does not send JSON null to the non-nullable optional server field. Empty entered notes remain an empty string. A confirmed invoice remains a successful sale if local cache invalidation fails; the client attempts scoped resource-cache eviction without repeating the financial write. Server validation and authorization failures still propagate. The native HTTP regressions ininventory_api_mutation_contract_test.dart cover omitted, empty and populated
notes, durable receipts and post-acknowledgment cache failure. Read contracts are
covered by inventory_api_read_contract_test.dart. These client safeguards do
not change server permissions, season pricing or stock accounting.
Native create and supported Inventory mutations persist their operation identity
before any HTTP request, including successful online creates. Online callers
receive the authoritative acknowledged resource; offline or temporarily blocked
callers keep their optimistic representation. This source behavior becomes
available after the matching mobile/API/database release has passed its gates.
A queued product write must wait for referenced Inventory owners, manufacturers,
categories, units, warehouses and Finance categories to be created, regardless
of enqueue order. Dependencies and mappings belong to the authenticated account,
workspace and resource type. Related mutations retain their per-entity order;
independent ready writes can progress. Missing prerequisites and dependency
cycles remain visible without deleting queued work.
Account/workspace purges serialize with durable pending writes. Malformed encrypted
pending records remain visible as conflicts while independent valid records can
continue; corrupt reference metadata cannot abort the entire replay pass. Online
sale-period clearing preserves the nullable server response. These boundaries are
covered by offline_inventory_review_regression_test.dart and the foreground
verification regressions in offline_inventory_verification_test.dart.
Product create permits at most 500 stock rows. Stock quantity and minimum quantity
must be integers, matching their database columns; unit prices preserve fractional
major currency amounts. offline-create-schema.test.ts and
inventory-offline-create.sql cover these limits for the offline create contract.
The dedicated setup/product/period create contract returns authoritative IDs and
deduplicates the original operation identity before the client retries an uncertain
create. The client never falls back to a legacy create route when this contract is
missing.
After acknowledgment, the queue persists the mapping and rewrites dependent
paths/payload references. An acknowledged create must not be sent again because
mapping storage or cache refresh failed. Automatic sync must preserve user data
across account switches, restart, retry and temporary network loss.
A missing endpoint or RPC retains the mutation and retries with bounded backoff,
connectivity, authentication and app-resume wakeups. Permission/domain failures,
canceled/deleted prerequisites, malformed payloads, ambiguous creators and cycles
remain stored with localized diagnostics; they cannot block unrelated ready work.
Confirmed create and write acknowledgments survive restart before mapping/dequeue.
Successful deletions persist resource-scoped tombstones, preventing stale mappings
from restoring deleted resources. Automatic replay never invents a replacement
for a canceled/deleted prerequisite. Typed references never rewrite free text,
workspace path segments or query parameters.
The dedicated online scheduled-sale journal keeps its existing receipt recovery
contract. Legacy invoices without an inventory period do not gain retry safety;
an uncertain legacy invoice remains retained for review, rather than duplicating
its financial effects. Wallets retain their existing stable client-ID contract.
Regression evidence is in offline_inventory_replay_test.dart,
offline_dependency_graph_test.dart, offline_inventory_mutation_test.dart,
finance_repository_inventory_dependency_test.dart and
offline_changes_sheet_test.dart; these synthetic tests do not establish native
airplane-mode or authenticated production acceptance.
The app is a registered Tuturuuu satellite app. It uses Tuturuuu app-session
auth for targetApp: 'inventory', exposes local /verify-token and
/api/auth/verify-app-token handoff routes, and forwards fallback /api/*
traffic to centralized apps/web APIs. Keep protected inventory, payment,
Stripe Connect, checkout, Square Terminal, and audit mutations behind apps/web so provider
secrets, bot protection, request logging, and Observability stay centralized.
Workspace-scoped Inventory APIs in apps/web must authorize through
authorizeInventoryWorkspace, which accepts the Inventory app-session cookie
and then performs workspace membership and permission checks. Authenticated
dashboard and workspace API access is permission-driven; do not hide these
routes behind the ENABLE_INVENTORY workspace config. Keep public storefront
delivery separate, since published storefront behavior may still apply
storefront-specific rollout gates. Do not use resolveAuthenticatedSessionUser,
supabase.auth.getUser(), or request-scoped Supabase clients as the primary auth
gate for these routes, because the satellite clears local Supabase cookies and
forwards app-session cookies instead.
The operator console uses the same collapsible Tuturuuu satellite workspace
structure as the Tasks, Finance, Calendar, and CMS apps: dashboard layouts should
keep server work to auth/workspace gating, then render client-side views backed
by TanStack Query and @tuturuuu/internal-api. Do not reintroduce a separate
Inventory-only app shell or direct client Supabase reads for protected workspace
data.
The local token verifier must call the central Web verifier with
verificationBaseUrl: WEB_APP_URL; Inventory protected routes require both the
host-only Inventory app-session cookie and the Web-issued app-session cookie
used by rewritten apps/web API requests. Local-only token validation will
create a redirect loop back to platform login. Current-user bootstrap APIs such
as /api/v1/users/me/default-workspace and /api/v1/users/me/profile must keep
inventory in their app-session audience allowlist, or /dashboard will accept
the local handoff cookies and then bounce back to Web auth after the bootstrap
request returns 401.
Public storefront routes live at /store/[storeSlug] inside apps/inventory
and are intentionally exempt from the operator auth proxy. They should only
read published storefront data through apps/web public APIs and should create
checkout reservations through the central apps/web RPC wrapper. Do not add
storefront CRUD, reservation writes, invoice finalization, or settlement writes
directly to apps/inventory.
Local Development
Use:dev script runs Portless. For direct port debugging, run
apps/inventory with bun dev:app, which falls back to port 7815.
Product Boundary
Inventory starts with workspace-scoped surfaces for:- product catalog categorization by type, owner, manufacturer, talent, supplier, channel, and fulfillment policy
- stock movement and reservation ledgers
- bundle and promotion availability controls
- checkout fee visibility for processing fees, Tuturuuu platform fees, conversion fees, settlement estimates, and net payout
- payment and inventory audit streams
- Stripe Connect readiness for B2B2C sellers who link their own Stripe account
- operator routes for overview, catalog, stock, bundles, storefronts, checkouts, sales, setup readiness, and audits
- public routes for
/store/[storeSlug],/store/[storeSlug]/products/[listingId], cart, checkout, and order status - private-schema tables for storefronts, listings, bundles, checkout sessions, checkout lines, reservations, Square connection state, terminal checkout identifiers, and settlement ledger entries
- commerce money (listing/bundle prices, checkout amounts, settlement, and
costing) stored in integer minor units of the row currency (cents for USD,
whole units for JPY/VND); convert with
@tuturuuu/utils/moneyand enter with the sharedMoneyInput. See the Polar storefront and Square Terminal integration runbooks. - Square Terminal settings for workspace app credentials, OAuth/manual tokens, location selection, device pairing, webhook verification, and commerce actions that send, cancel, and reconcile terminal payments after local stock is reserved. The same settings surface provides guarded Square catalog and stock import, additive publish, and conflict-aware two-way sync. Provider deletion is deliberately unsupported.
- service-role-only RPCs for creating reservations, releasing or expiring
reservations, materializing checkout TTL expiry, and linking a completed
checkout to a
finance_invoice - private sales periods that group both invoice-backed and completed checkout sales into seasons, conventions, campaigns, or other operating windows. A sale has at most one period assignment, while archived periods keep their historical assignments and remain available for reporting.
- durable Finance source entries for every completed real-provider checkout, refund, Square chargeback hold/release, and audited provider-unavailable adjustment. Simulated checkouts are excluded. Manual Inventory sales continue using their existing Finance invoice path.
private schema, not public. Public and
satellite clients must go through Inventory-owned apps/inventory APIs plus
@tuturuuu/internal-api; direct Supabase client access to these tables is not
part of the contract. Protected workspace routes must authenticate and normalize
the workspace with the request-scoped client before any private-table read or
write, then use server-only database access or service-role RPCs behind
apps/inventory.
Convention selling uses an explicit sales period. The sale dialog defaults to an
in-range configured period, otherwise the sole current scheduled period. An intentionally configured current
legacy default is honored; legacy-only implicit selection requires a choice. Overlapping
or absent current periods require a choice. Operators can explicitly choose the
legacy unassigned workflow; it is never an automatic fallback.
New periods default to effective season pricing with explicit dates and an IANA
timezone. Prices are major currency units, scoped to product, unit, warehouse and
period. Price intervals start at local midnight; end dates are inclusive. A new
later interval closes an earlier interval without replacing its amount. Price
history does not alter stock quantity, legacy catalog prices or completed invoice
snapshots. Existing periods remain in legacy pricing mode until deliberately
changed; the migration performs no price backfill. Priced period dates, timezone
and pricing mode are immutable. Use another period to change those boundaries.
Scheduled selling filters eligible active products and requires a current price
in the workspace currency. Gaps and missing prices prevent checkout; another
season’s prices are never borrowed. Price controls require catalog-management
permissions. Managers can preview upcoming selected-season prices in the price
history, labeled with effective dates and the season timezone. Viewing a future
price does not make it eligible for checkout at the current sale time.
Offline/stale carts require refresh and review, with no silently
changed total. Period-linked invoice creation validates the quote and eligibility
and captures line amounts, stock changes and period assignment in one private
transaction after the existing Finance authorization checks. Historical invoices,
reports and completed commerce orders continue using their saved amounts. Price
receipts survive invoice deletion as durable idempotency tombstones: deleted
requests cannot recreate a canceled sale, and restored invoices retain the same
receipt and captured prices. Legacy manual periods keep six-decimal major-unit
precision, existing currency fallback and existing finite overselling behavior.
Provider listings/promotions and their minor-unit prices are intentionally
unchanged. Scheduled manual sales keep the existing custom-price workflow’s
no-promotion semantics and require a matching wallet currency.
The additive migration must be installed before scheduled controls can be used.
Missing tables/RPCs fail closed; never apply production migrations manually.
Sales-period clients use the Inventory-owned routes below. Keep these paths in
the Flutter API mapping check whenever the mobile catalog changes:
GET/POST /api/v1/workspaces/:wsId/inventory/sales-periodsPATCH/DELETE /api/v1/workspaces/:wsId/inventory/sales-periods/:periodIdGET/POST /api/v1/workspaces/:wsId/inventory/sales-periods/:periodId/pricesPUT /api/v1/workspaces/:wsId/inventory/sales/:saleId/periodGET /api/v1/workspaces/:wsId/inventory/sales?period_id=:periodId
private.inventory_products, private.inventory_units,
private.inventory_warehouses, private.inventory_suppliers,
private.inventory_batches, private.inventory_batch_products,
private.inventory_owners, private.inventory_audit_logs, and
private.inventory_manufacturers. Dashboard pages and APIs should access them
through server-owned apps/web routes. Prefer private-schema RPCs for product
catalog, low-stock, and other repeated join-heavy reads; call them with
createAdminClient().schema('private').rpc(...) from server code.
Manufacturers are a normalized workspace setup entity matching the
supplier-style management model. Products store only
workspace_products.manufacturer_id; API responses may still include
manufacturer as a display name for older clients. Legacy imports that send
package/product manufacturer text should upsert the trimmed name into
private.inventory_manufacturers, assign the resulting manufacturer_id, and
avoid writing manufacturer text back to workspace_products.
Bundle components are a workspace-scoped stock contract. When creating or
updating a bundle, every component’s product, unit, warehouse, and stock row
must belong to the same workspace as the bundle. The database trigger on
private.inventory_bundle_components enforces that invariant for direct writes,
and the checkout reservation RPC re-checks the same workspace before locking
stock. Do not trust stored bundle component UUIDs as already authorized input.
Do not hardcode Stripe fee schedules as durable truth. The checkout estimator is
for quoting and operator review; production reconciliation should persist the
estimate shown to the seller and then reconcile it against actual Stripe balance
transaction fee rows after settlement.
Deployment
Inventory has dedicated Vercel workflows:.github/workflows/vercel-preview-inventory.yaml.github/workflows/vercel-production-inventory.yaml
VERCEL_INVENTORY_PROJECT_ID. Add that secret before
enabling hosted deployments for inventory.tuturuuu.com.
Price history references durable product/unit/warehouse identities instead of the
replaceable stock tuple. Combined product edits and dedicated stock edits for
priced products commit metadata, tuple changes and movement history together;
a failed edit leaves no partial metadata or phantom stock movement. Scheduled
period scope/rule replacement takes the same period lock as checkout in a single
transaction. Search filters never invalidate cart quotes; selecting the current
period is a no-op. Price authoring forwards the scoped catalog pagination so
products after the first page can be selected without preloading another dialog.
Atomic pricing-aware edit routing also applies before a product has its first authored price and while a legacy period is being converted. The database transaction resolves current state under its locks; routing never relies on an earlier mode or price-existence read. Checkout, stock editing and price authoring acquire stock tuples before the product row to avoid mixed legacy/scheduled lock inversion. If price support is installed but its edit transaction is unavailable, edits fail closed instead of falling back to separate writes.
On native mobile, an active user Save may open the existing verification dialog
for that record only. Background replay never opens verification dialogs or
persists verification tokens. Canceling that dialog leaves the already-requested
Save queued: the editor closes and the item keeps its existing Waiting to sync
indicator, rather than claiming server completion or creating another operation
on a repeated Save. The original operation identity is reused on later replay.
Explicitly discarding the queued change cancels unsent work; canceling verification
does not discard it. Account changes and real membership or permission denials
retain their original error behavior. Regression coverage lives in
offline_inventory_verification_test.dart and the mounted product editor tests.
Transactional offline create validation
Automatic dependency sync uses a separate deduplicated create contract. Its private receipt and all resource, stock, history and audit effects commit together. Reusing an operation identity with different input is rejected. The service authorizes the captured account, workspace and resource permission before invoking this contract; customers cannot read receipts or forge actors..github/workflows/inventory-offline-contract.yaml validates the exact PR head
by applying the complete schema in a disposable hosted database, running strict
inventory-offline-create.sql pgTAP assertions, and generating
packages/types/src/supabase.ts as an artifact. A queued workflow is not schema
or type parity evidence. The native scheduler persists operation identities before
sending, orders prerequisites, and rewrites acknowledged references automatically.
An unavailable server contract retains queued work and retries automatically; it
never falls back to an unsafe legacy create. Release readiness still requires the
exact-source database, generated-type, native, and owning-app CI gates.
The new /api/v1/workspaces/:wsId/inventory/offline-mutations POST route
accepts an operation identity, an explicit create kind and a strictly validated
payload. Current workspace membership and the owning kind permission are checked
on every retry, even when a prior receipt exists; a revoked grant denies the
request. Inventory stock initialization additionally requires stock permission.
Finance categories use create_transactions and accept Inventory or Finance
app sessions. Receipt identities have no TTL or automatic pruning.
Recognized responses carry X-Tuturuuu-Offline-Contract. Missing RPC/schema
returns OFFLINE_CONTRACT_UNAVAILABLE with 503; an unknown route on an older
deployment has no contract header. These rollout gaps must retain the operation
and retry automatically, while a marked domain 404 or permission 403 is permanent.
The native implementation must never fall back to an undeduplicated create POST.
Offline catalog create receipts intentionally have no time-based expiry. Their
private storage lasts for the owning actor/workspace lifetime and is removed by
those owners’ deletion cascades. The mobile outbox has no maximum retry age, so
pruning a receipt could replay an old successful create as a new resource.
Changing this default requires a coordinated client/server operation expiry and
server rejection of expired operation IDs before receipt deletion is enabled.
This rule covers inventory catalog/setup create receipts, including stored
request/response data; it does not introduce a financial transaction retention
policy. The private table is inaccessible to ordinary client roles. Receipt
replay and payload-identity checks in inventory-offline-create.sql guard the
current behavior; lifecycle pruning remains intentionally disabled.
An offline create RPC that completes with a malformed receipt or a different
resource returns sanitized HTTP 500 OFFLINE_CONTRACT_RESPONSE_MISMATCH.
No row IDs are exposed, and the same operation remains retained for operator
review. A missing RPC function/schema remains HTTP 503
OFFLINE_CONTRACT_UNAVAILABLE. These distinguish a server receipt defect from
contract availability; the client must not blindly resend a new create identity.
offline-create-route.test.ts covers malformed receipts and resource mismatches.
Merge products and warehouses
The Inventory web operator exposes Merge products above the product table and Merge warehouses in Setup. Select a source and destination, review the current stock/reference preview, choose which metadata and overlapping price, minimum-stock and revenue-share configuration to keep, then acknowledge the destination before confirming. Both update/manage access, inventory deletion permission, and stock adjustment permission are required. This is ordinary authenticated inventory work; it is not an offline bulk download and must not require download-protection setup. Product selectors search active products independently of catalog filters and the currently loaded table page. Each selector supports loading more results. Warehouse stock reviews resolve product names by identity; confirmation waits for those names and offers a retry when they cannot load. On narrow screens the dialog fills the viewport, keeps its actions pinned, and scrolls the review body; long record names wrap rather than push conflict details outside the screen. Failed previews and failed merges retain the dialog and require a fresh acknowledgment before retrying. Regression coverage:inventory-merge-dialog.test.tsx and
inventory-merge-product-options.test.tsx.
Different unit structures are supported: separate units remain separate stock rows
and quantities are never converted between units. Matching finite stock quantities
are added exactly once. Two unlimited rows remain unlimited. Mixed unlimited and
finite rows are blocked until the operator explicitly adjusts that stock outside
the merge. Active reservations and active/upcoming scheduled source prices block the operation. Duplicate provider mappings,
storefront variants, bundle identities and other live unique identities are shown
as conflicts and must be resolved in their owning editor before merging; no provider
objects or conflicting records are silently deleted. The global price policy also
chooses the associated minimum stock and revenue-share settings together.
The merge is one database transaction with a current preview version and a durable
receipt. Concurrent stock/reference changes invalidate the preview; retries of the
same source, destination, version and policies do not add stock again. Live references
move to the destination while invoices, movement history, scheduled price quotes and
checkout snapshots keep their original IDs and values. Source products are archived;
source warehouses are removed from new selectors. Their durable rows remain available
for historical detail. Future writes using a merged source identity, including stale
web/mobile/offline/provider writes, reject atomically with a refresh-and-select-the-
destination message. Historical updates that do not change their identity remain
allowed. Authorized invoice recovery is the narrow exception for historical inserts:
it restores only exact saved invoice lines with their original product and warehouse
IDs, after invoice recovery permissions and workspace checks. A private transaction
capability restricts this exception to the restoration RPC; new sales and stale writes
cannot use it, including by setting a restoration flag. Restoring history does not
consume the combined stock again.
New merge preview and apply require the final schema readiness RPC and the active
warehouse view, restoration guard and writer guards. During deployment before gated
migrations, ordinary warehouse reads may use the legacy table only after the existing
product-form-options RPC successfully returns a valid warehouse array without an
inventoryMergeSchema marker. Alias-table creation atomically replaces that RPC to
return aliases-v1; marker presence and a missing active view fail closed. Cached
PostgREST metadata cannot substitute an older server function body, and a missing-table
API error alone cannot establish legacy schema. Merge actions remain unavailable
until readiness succeeds.
Merge transactions reserve the buckets containing the source and destination identities.
Identity coordination uses 16 stable buckets per resource kind and workspace, so
large imports and stock/reference updates acquire at most 32 identity keys within
one workspace instead of one advisory lock per record. Product/warehouse parents
supply the authoritative workspace for all writers; a child row cannot choose a
different namespace. Different workspaces have separate bucket namespaces. Two
unrelated identities in the same workspace can share a bucket: when a merge holds
it exclusively, that unrelated write safely returns retryable 55P03 rather than
waiting or bypassing guards. Retry after the merge finishes. Actual workspace
removal exempts its deletion cascades because that workspace can no longer merge;
ordinary deletes in a live workspace retain all identity and merged-source guards.
Reference inserts, updates, deletes and checkout state changes coordinate with those
identities; unrelated workspace CRUD and other buckets remain available. Contention fails
fast and requires refresh/retry. Row-lock waits are limited separately; this does not
establish a deadline for the entire RPC. New reference tables must install both the
merged-reference guard and the identity writer coordination trigger before merging
can use them.
Offline creation receipts retain their original identity rather than creating
a replacement resource; operators must refresh and select the destination for new work.
The feature does not execute automatic background merges, convert units, merge external
provider objects, or delete historical identities. New tables that reference inventory
identities must install the merged-reference guard as part of their migration; the
preview enumerates current foreign keys and fails closed for unsupported composite
relationships. Regression evidence lives in inventory-merge.sql, inventory-merge-restoration.sql,
inventory-merge-concurrency.mjs, inventory-merge-readiness.sql, the merge API route
tests, internal API transport tests, and Inventory merge-dialog tests. Deployment needs
the additive merge and repair migrations before execution becomes available; missing merge
RPCs return a temporary-unavailable response while existing warehouse lists continue
working on an older schema.
The existing inventory-offline-contract.yaml CI lane applies the full isolated
schema and runs offline create plus merge, alias pagination, restoration and
readiness pgTAP fixtures. Its testing phase also runs the three-client
inventory-merge-concurrency.mjs executor; SQL or concurrent-writer failures
fail the gate and still pass through owned-stack cleanup.
Merge sales seasons and periods
The Inventory web operator can merge two sales periods using an explicit, paged review. Both preview and apply require workspace membership,update_invoices
and delete_invoices, plus manage_inventory_catalog or legacy
update_inventory. The Rust migration source mirrors this contract; Web remains
the live API. The sales page derives the merge action from this complete role
contract on the server; missing or failed permission lookup hides the action.
Catalog management alone does not expose it. Regression coverage includes
sales/page.test.tsx and sales-periods-panel.test.tsx. Flutter has no
season-merge action in this change.
The destination keeps its name, dates, time zone and pricing mode. Description
and the complete product eligibility rule set each require a source/destination
choice. With live or upcoming source prices, calendar or pricing-mode differences
block merging. Without those prices, calendar differences are reviewable and the
destination calendar remains unchanged. Chosen eligibility rules must allow every
source price product; the review displays excluded-price counts before approval.
Overlapping schedules require either blocking the merge or explicitly keeping
the destination overlap. The latter imports only uncovered source intervals with
fresh price IDs, clipped to merge time. Every original price, captured invoice
quote and invoice line stays intact; stock and movement history are unchanged.
Reporting assignments move to the destination, with their original classification
stored relationally. Replaced destination product rules retain every original
rule identity, label and timestamp in the receipt, including rules beyond the first
preview page. The source is archived as a durable alias, excluded from new
selectors, and cannot be edited, restored or newly referenced. Trusted invoice
recovery and offline request replay continue to use the original durable quote.
Prices, overlap conflicts and product rules are paged at 50 rows per section.
Confirmation requires explicit policies, resolved human labels and review of all
pages. A server token binds actor, workspace, both periods and a frozen cutoff,
and expires after five minutes. Its fingerprint hashes affected mutable planning
rows and retained-history ownership counts without aggregating historical
payloads. Refresh after expiry, concurrent changes, unresolved conflicts or a
retryable readiness failure; acknowledgment is invalidated before retry.
Merge apply and child writers coordinate on only the selected period rows.
Assignment/price writers recheck aliases after waiting; unrelated periods and
workspaces remain available. Missing schema/guards return 503 and perform no
merge. Historical provenance foreign keys are deferred until transaction end,
allowing whole-workspace cascade ordering while rejecting standalone removal of
referenced periods and original/imported quotes.
Regression coverage: inventory-season-merge.sql exercises actual migration,
history, trusted recovery and transaction-boundary constraints;
inventory-season-merge-concurrency.mjs uses independent PostgreSQL clients for
writer rejection and unrelated CRUD. Both run in the existing Inventory contract
CI lifecycle, including official type generation and owned cleanup. Route,
internal API transport and dialog tests cover authorization, tokens, errors,
policies, expiry and pagination. App builds and Rust tests require exact-commit CI;
source and mocked UI checks do not establish browser or production behavior.
The season test’s cascade control retains quote tombstones after trusted invoice
deletion. Deletion of a workspace that still contains a live invoice has a separate
parent-schema defect: the invoice product unit foreign key attempts a null default
against a non-null column. An isolated parent-schema control reproduced that
error before applying the new season migrations. The expected-defect control is
retained as local validation evidence, outside the passing season CI contract. Season merging does not alter that existing schema.
Season merge previews and review pages are scoped to the authenticated Inventory
actor and workspace. Switching accounts resets the visible review and prevents
late responses from completing another account’s dialog. Before submitting,
Inventory saves one immutable actor/workspace-bound request (original source,
destination, policies and preview token) in the current tab’s session storage.
Storage failure prevents sending. Closing/reopening or reloading that tab
restores an unresolved request; it is never replaced by a fresh preview.
For an ambiguous response or authentication pause, Check original merge replays
the exact saved request. The existing apply RPC checks its committed receipt
before preview expiry or merged-source validation, so a lost success response
can be reconciled after the token expires or source is archived. A conflict or
validation response allows fresh review only for a first known attempt. Once
uncertainty exists, even a retry 409 retains the original request: a lock timeout
can occur while its earlier transaction still commits. Recovery is manual and
per tab; it does not claim a cross-tab journal or new offline navigation support.
Mounted regressions in use-season-merge-recovery.test.tsx and
use-inventory-season-merge-review.test.tsx cover scope changes, late responses,
remount recovery, storage failures and lost-response/conflict/receipt sequences
with synthetic transport. Existing isolated SQL receipt replay coverage remains
the database evidence; browser/device and exact-CI evidence remain separate.
Cleared checkout search
The web Inventory sale dialog restores its loaded product catalog immediately when product search is cleared. Category and warehouse choices and scheduled price eligibility derive from those restored products. A previous empty response or in-flight response cannot replace the unfiltered catalog. During a new search, loaded products remain searchable while the server query settles. This changes search selection only; current season price validation and existing cart snapshots remain authoritative. Mounted regressions inseason-sale-integration.test.tsx cover settled empty search, clearing an in-flight
search, restored category/warehouse choices, and the original scheduled prices in
the submitted sale.
The checkout category and warehouse pickers use the full authorized workspace
form options, independent of product search, pagination, or season price coverage.
Selecting a category queries its products across pages; search results have their
own pagination. Categories with no currently eligible stock remain selectable and
show an empty product result rather than disappearing from the picker. The
mounted unloaded-category regression uses synthetic data outside the initial
catalog page and verifies searchable choices, category-scoped requests, and the
second page. This does not imply every product has a current scheduled price.
Merge concurrency lock boundary
The independent-client cascade fixture requires zero unexpected advisory locks. It permits only the bigint key computed byhashtextextended('employee-address-reservations', 0) in ShareLock mode and
objsubid=1. This shared employee-admission lock protects a separate boundary:
workspace deletion invokes the profile default-workspace FK’s SET DEFAULT
update, whose statement-level admission trigger runs even for an empty update.
The full-schema PostgreSQL failure classified that lock separately from the
cascade warehouse’s inventory identity key.
The fixture explicitly accounts for the permitted lock. Every other key, mode,
and two-integer namespace remains forbidden, including real inventory identity
locks held alongside permitted admission. Its 28-check plan preserves the original
22 cases and adds six disposable PostgreSQL controls: a zero-row profile update
that takes shared admission, a real inventory lock beside it, an unexpected shared
key, exclusive employee admission, the same key halves in the two-integer
namespace, and rollback cleanup of all control locks. Controls roll back without
changing profile rows or weakening employee admission.
An unexpected lock retains a bounded failure-only TAP diagnostic: the tested
unexpected count, disposable backend PID/assigned transaction ID, and at most
32 granted advisory tuples with truncation and barrier/permitted/forbidden labels.
A later snapshot never replaces the tested count; diagnostic errors cannot hide
the boundary assertion. Passing the boundary adds no diagnostic query or wait.
Require the exact candidate’s Inventory offline create database contract workflow
to pass all 28 checks plus season concurrency, strict SQL packets, generated types
and owned cleanup. Local source and mock checks do not establish PostgreSQL
acceptance. Compare the retained same-schema failing count with the new candidate
before declaring the fixture repair verified.