--- id: WF-COM-ORD-016 title: Value stock movements after receipt trigger: 'Shipping, receiving or inventory movement calls the corresponding cost boundary.' product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b implements: - CAP-COM-ORD-018 crosses: - SVC-COM-ORD-purchasing - SVC-COM-ORD-orders idempotency: >- Movement and source references identify cost effects. Repeated keyed movement work retains its previous layers, reliefs and posting facts. concurrency: >- Cost writes share their originating movement transaction and lock the relevant layers. FIFO or LIFO ordering controls which remaining acquisition value is relieved. hops: - 'n': 1 actor_or_service: Shipping handoff (fulfilment module) action: Consume layer quantities for shipped units and record the resulting relief and cost-of-goods fact. anchor: 'services-commerce:modules/purchasing/services/cost/cost-accounting.ts:relieveUnits' seam: sync on_failure: Cost failure rolls back the shipment handoff transaction. left_inconsistent: Units without acquisition layers carry zero-cost relief and an operational exception. observer: Observed through observed through inventory exceptions; valuation. provenance: test source: >- services-commerce:modules/purchasing/tests/integration/services/receiving/purchasing-flow.integration.spec.js#relieves units no layer covers at cost zero under no layer and raises uncosted_relief, so the books say so - 'n': 2 actor_or_service: Return restock action: >- Restore shipment relief newest first at its recorded cost and original acquisition date, with a restoration fact. anchor: 'services-commerce:modules/purchasing/services/cost/cost-accounting.ts:restoreUnits' seam: sync on_failure: Failure rolls back the receiving transaction. left_inconsistent: No separate cost restoration commits. observer: Observed through observed through cost relief list; valuation. provenance: test source: >- services-commerce:modules/purchasing/tests/integration/services/receiving/purchasing-flow.integration.spec.js#restores the LIFO relief at its recorded costs and places: each relief reversed, the layers dated with the originals, a restore_cogs of 14000 - 'n': 3 actor_or_service: Staff movements and counts (inventory module) action: >- Value gains from last receipt cost, relieve losses or scrap by the selected method and produce adjustment facts; quarantine and damage do not change costing. anchor: 'services-commerce:modules/purchasing/services/cost/costed-inventory-operations.ts' seam: sync on_failure: Failure rolls back the originating movement. left_inconsistent: No partial cost effect commits outside its movement. observer: Observed through inventory valuation shows the result. provenance: test source: >- services-commerce:modules/purchasing/tests/integration/services/receiving/purchasing-flow.integration.spec.js#values a count gain at the last receipt cost (adjustment_gain) and relieves a count loss (adjustment_loss), each fact naming the count line - 'n': 4 actor_or_service: Transfers (inventory module) action: >- Relieve source layers and create destination layers at weighted cost, splitting any rounding remainder into a layer one minor unit higher without a posting fact. anchor: 'services-commerce:modules/purchasing/services/cost/transfer-cost.ts:costTransfer' seam: sync on_failure: Failure rolls back the stock transfer. left_inconsistent: Destination stock preserves any source quantity lacking cost layers. observer: Observed through inventory valuation shows the result. provenance: observed source: 'services-commerce:modules/purchasing/services/cost/transfer-cost.ts' - 'n': 5 actor_or_service: Staff action: Move a layer's unused remainder into a corrected-cost layer and create an adjustment fact. anchor: 'services-commerce:modules/purchasing/services/cost/cost-accounting.ts:correctLayerCost' seam: sync on_failure: Exhausted layers and invalid costs are refused. left_inconsistent: The original cost remainder stands on refusal. observer: Observed through observed through staff; posting facts. provenance: test source: >- services-commerce:modules/purchasing/tests/integration/services/receiving/purchasing-flow.integration.spec.js#moves the unconsumed remainder to a layer at the corrected cost, leaves the original consumed, and writes the cost_adjustment of the difference - 'n': 6 actor_or_service: Valuation read action: >- Compare remaining acquisition value with on-hand quantity and expose method, mismatch and missing-relief results. anchor: 'services-commerce:modules/purchasing/services/valuation/inventory-valuation.ts:readInventoryValuation' seam: sync on_failure: Read failure returns no valuation and changes no cost records. left_inconsistent: The read reports discrepancies without repairing them. observer: Observed through observed through staff reading valuation. provenance: test source: >- services-commerce:modules/purchasing/tests/integration/services/receiving/purchasing-flow.integration.spec.js#raises valuation_mismatch on stock no layer costs, relief_missing on a shipment movement no relief followed, and nothing on the reconciled items branches: [] waits: [] evidence: - >- services-commerce at c8b66a98: modules/purchasing/services/cost/*.ts; services/valuation/inventory-valuation.ts; modules/shipping/services/cost/cost-relief-port.ts; tests/integration/services/cost/lifo-costing.integration.spec.js. controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-CRY-001, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003, TC-PRV-001, TC-PRV-002] --- # Value stock movements after receipt ## What It Does Costing records the value consumed or returned by later stock movements. It supports shipment relief, returns, adjustments, transfers, corrections and a valuation read without revising earlier cost history. ## The Flow ```mermaid sequenceDiagram participant M as Movement (shipment, return, count, transfer) participant C as Purchasing cost rules participant L as Cost layers participant F as Posting facts M->>C: inside the movement's transaction C->>L: draw or create layers by the business unit's method C->>F: one fact of the event's kind (none for a transfer) ``` ## When Something Fails Movement failures roll back their corresponding cost writes. Uncovered stock produces zero-cost relief and an exception. Transfers preserve cost shortfalls and rounded totals rather than manufacturing a financial value. ## Open Design Questions The purchasing boundary with inventory remains open. Valuation reveals mismatches but does not repair them.