--- id: DOM-COM-FUL-005 title: Stock realises: CON-COM-FUL-005 product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-FUL-inventory readable_by: - SVC-COM-FUL-shipping - SVC-COM-FUL-data-operations lifecycle: STATE-COM-FUL-009 custom_fields: none identity: >- Warehouses and locations retain stable configuration identities. Location codes are unique within a warehouse; items are unique by product, SKU and location, movements by workspace key, and order allocations by line and unit. attributes: - name: warehouse kind: collection required: true computed: false notes: >- Retains the warehouse address, active status and allocation priority, sorting unset priority last. - name: location kind: collection required: true computed: false notes: >- Retains the owning warehouse, stable code, place kind and pick priority; bins, zones and receiving are sellable. - name: stock item kind: collection required: true computed: false notes: >- Retains one location SKU with item settings and its six ledger-controlled balances. - name: available kind: computed required: true computed: true notes: >- Derives availability by subtracting quarantine, damage, holds and allocation from on-hand. - name: movements kind: collection required: true computed: false notes: >- Retains immutable signed stock changes with source, cost where applicable, actor, reason and key. - name: allocations kind: collection required: true computed: false notes: >- Retains one promised unit with checkout or order ownership, state, expiry, fences and delivery or shipment links. - name: transfers kind: computed required: false computed: true notes: Reads the paired outgoing and incoming movement facts as one transfer. - name: counts kind: collection required: false computed: false notes: Retains warehouse observations and their eventual ledger corrections. - name: stock findings kind: collection required: false computed: false notes: >- Retains standing stock and warehouse diagnoses, including carrier and cost problems, with recurrence counts. - name: availability kind: computed required: false computed: true notes: >- Combines sellable stock and product policy into storefront availability and console quantities. relationships: - to: DOM-COM-FUL-004 cardinality: Allocation units are carried by at most one live shipment line. ownership: The allocation names the shipment line. cross_service: true - to: DOM-COM-FUL-001 cardinality: One committed unit is picked under one unit obligation. ownership: The allocation names the obligation. cross_service: true invariants: - id: INV-DOM-COM-FUL-005-01 statement: >- Database triggers derive balances from movements and allocations, while grants prevent direct application balance writes. enforced_at: - database provenance: observed source: >- services-commerce:modules/inventory/db/inventory-items.table.ts (column grants, apply_inventory_movement, apply_inventory_allocation) - id: INV-DOM-COM-FUL-005-02 statement: Database checks refuse negative on-hand or available stock. enforced_at: - database provenance: observed source: >- services-commerce:modules/inventory/db/inventory-items.table.ts:inventory_items_balances_check - id: INV-DOM-COM-FUL-005-03 statement: >- Movement history cannot be rewritten, and quantity signs must match the movement type. enforced_at: - database provenance: observed source: >- services-commerce:modules/inventory/db/inventory-movements.table.ts:inventory_movements_quantity_sign_check - id: INV-DOM-COM-FUL-005-04 statement: >- Repeated movement keys return the existing movement only when its type, quantity and item agree. enforced_at: - database - service provenance: documented source: 'services-commerce:docs/migrations/inventory/README.md#D-P8I-22' - id: INV-DOM-COM-FUL-005-05 statement: >- Allocation constraints retain one-unit rows, fixed item references and the required state-specific identities. enforced_at: - database provenance: observed source: 'services-commerce:modules/inventory/db/inventory-allocations.table.ts' - id: INV-DOM-COM-FUL-005-06 statement: >- Concurrent claims for insufficient final stock refuse the losing placement without retaining its order. enforced_at: - database - service provenance: documented source: 'services-commerce:docs/migrations/inventory/README.md#D-P8I-21' - id: INV-DOM-COM-FUL-005-07 statement: >- Shipping accepts picked allocations and separately validates matching delivery obligations. enforced_at: - service provenance: observed source: >- services-commerce:modules/inventory/services/persistence/inventory-allocations.ts:shipUnits - id: INV-DOM-COM-FUL-005-08 statement: >- Transfer writes both movement halves and carries available stock and cost together. enforced_at: - service provenance: observed source: 'services-commerce:modules/inventory/services/stock/transfer-stock.ts' - id: INV-DOM-COM-FUL-005-09 statement: >- Incoming sellable stock commits waiting backorders in oldest-order order within the movement transaction. enforced_at: - service provenance: observed source: 'services-commerce:modules/inventory/services/stock/staff-movements.ts' - id: INV-DOM-COM-FUL-005-10 statement: >- Count completion writes keyed corrections against current on-hand and prevents changes to terminal counts. enforced_at: - service - database provenance: observed source: >- services-commerce:modules/inventory/services/persistence/inventory-counts.ts:completeCount - id: INV-DOM-COM-FUL-005-11 statement: >- A partial unique index permits one standing inventory finding per kind and subject. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/inventory/db/inventory-exceptions.table.ts:inventory_exceptions_open_uidx - id: INV-DOM-COM-FUL-005-12 statement: >- Dependent locations, items and counts prevent deleting their place, while inactive places refuse receipt and allocation. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/inventory/services/persistence/warehouses.ts; inventory-locations.ts physical: - warehouses - inventory_locations - inventory_items - inventory_movements - inventory_allocations - inventory_counts - inventory_count_lines - inventory_exceptions evidence: - >- services-commerce at c8b66a98: modules/inventory/db/*.table.ts; services/persistence/*.ts; services/stock/*.ts; services/reconciliation/nightly-inventory.ts; db/migrations/20261018024147_merchandise_and_inventory.sql, 20261018194937_inventory_transfers.sql; docs/migrations/inventory/README.md. --- # Stock ## What It Models Stock records both physical goods and promises to buyers. Warehouses and locations organize items; movement and allocation ledgers explain balances. Counts and findings support investigation when the shelf and the records disagree. ## Identity and Attributes A stock item identifies a product and SKU at one location. Movements retain stable request keys and signed quantities. Allocations represent single units held for checkout, committed to an order, picked, shipped, backordered or released. Available stock is derived from the stored balances. ## Relationships Shipment lines refer to allocation units. Handoff and return disposition call the stock services rather than editing balances directly. Placement and cancellation participate through claim functions, and cost layers remain in the separately registered purchasing boundary. ## Invariants Database constraints prevent negative balances and restrict direct application writes. Transfers retain both ledger halves together. Counts use movements to correct differences, while reconciliation reports discrepancies rather than replacing balances. ## How It Is Stored and Shared Inventory owns warehouse, location, item, ledger, count and finding records. Shipping and the merchandise participant use its persistence for their work. Data operations introduces migrated opening stock through ledger entries. No custom fields are declared. ## Open Design Questions Product must settle purchasing and costing ownership and the staff surface for inventory findings. The pinned console provides no complete stock-management workspace.