Walkthrough: Receiving You Can Trust

This walkthrough traces FLOW-0004 — Receiving You Can Trust — a dock capture that keeps what the order expected, what the vendor stated, and what was actually counted as three separate numbers, freezes them into a permanent record, and lets the order’s received amounts maintain themselves. The flow splits cleanly down the middle: every dock-side step (the capture, the four separately recorded facts, the freeze) belongs to the Receiving module, which is specified but not yet built, while the reconciliation half — Demand’s production-delivery ledger and Orders’ self-healing received amounts — is fully implemented and tested. Inventory Items supplies the pool the freeze would birth.

See the walkthroughs index for the shared call shape and the built-vs-designed legend used throughout.

Capture — claims and facts, separately

#	Business step	API call	What changes	Refusals you can hit	Evidence
1	Vera’s delivery arrives at the dock with its packing slip	— (physical step)	—	—	Narrative only
2	Keisha creates a receiver and captures against the order	designed — Receiving	—	—	Module absence
3	Add a line from an order line — born attributed, expected amount frozen at attach	designed — Receiving	—	—	Module absence; the read it would consume already exists, `order-line.functional.test.ts:300-302`
4	Receiving reads the order line’s open quantity and never writes to it	designed — Receiving. The read it would use is real: `GET /v1/procurement/order/order-line/by-order/{orderId}?asOf=`	Nothing (read) — the read is built, the caller that would invoke it isn’t	404 on a tombstoned or unknown line	`order-line-client.ts:153-166`; live example `order-line.functional.test.ts:300-302`
5	Record the vendor’s stated quantity from the packing slip — kept as an inert claim	designed — Receiving	—	—	Module absence; no implemented payload holds a vendor-stated quantity either — `order-line-client.ts:42-55`
6	Capture the carrier that delivered, pinning the carrier’s current version — deliberately ungated	designed — Receiving	—	—	Module absence; the comparable gated pin on the order side is `order.functional.test.ts:136-162`

The freeze makes the record permanent

#	Business step	API call	What changes	Refusals you can hit	Evidence
7	Receive — the freeze. In one act: accepted/rejected counts, reason, captured facts, and attribution actuals become the permanent record	designed — Receiving	—	—	Module absence
8	The accepted goods are born as an inventory pool located at the dock, in the line’s custody until it releases them	`POST /v1/resources/inventory/inventory-pool/create` — the pool birth is real and callable, but nothing births one from a receipt	Inventory Items: new pool; `content` keyed-zero or seed. No custodian or location field on the wire	None at genesis	`inventory-pool.functional.test.ts:21-31`
9	The attribution’s actual is written exactly once, by the freeze itself — receiving never posts to the order	See Fidelity notes — this is inverted today	—	—	Manual route `order-line-client.ts:131-139`; listener wiring `Module.kt:98-100`
10	Corrections after the freeze ride the record’s correction mechanism — never quietly undone	designed — Receiving. Analogue: `POST /v1/operations/demand/demand-item/revoke-delivery` and `POST /v1/procurement/order/order-line/reverse-receipt`	Demand: `ProductionDelivery` CREATED → REVOKED. Orders: `received` decrements pairwise	`RDeliveryClosed` — not live	`demand-item.functional.test.ts:194-216`; `order-receipt.functional.test.ts:46-59`
11	Vera’s slip says ten, the count says eight — the frozen record holds both	designed — Receiving	—	—	Module absence; the payload survey at step 5

The order reconciles itself

The one part of this flow that is fully implemented.

#	Business step	API call	What changes	Refusals you can hit	Evidence
12	Record the production delivery as material moves onward	`POST /v1/operations/demand/demand-item/record-production`	Demand: delivery pool folded into the holding pool; a `ProductionDelivery` row reified, server-side eId, `status = CREATED`. Demand item stays IN_PROCESS	`RTargetNotInProcess`, `RWrongItem`, `RForeignRef` (403)	`demand-item.functional.test.ts:148-192`
13	Delivery announced (notification)	— (system notification — wired)	Demand emits `ProductionRecorded` post-commit on every committed record-production	—	`DemandNotification.kt:20-38`; emission `DemandServiceImpl.kt:86`
14	Orders listens and accrues the amount to every line that demand item services	— (system notification — wired)	Orders / order-line: `received` accrues pairwise; idempotency keyed on `(notification_id, kind)` using the `ProductionDelivery`’s eId	`RNoDemand`, `RLineClosed`	Subscription `Module.kt:98-100`; idempotency query `OrderLineUniverse.kt:41-65`
15	The same wire in reverse: a revoked delivery decrements the line	— (system notification — wired)	Orders / order-line: `received` decrements pairwise; dedup is kind-scoped	`RNoDemand`, `RLineClosed`	`DemandNotification.kt:40-55`; manual twin `order-receipt.functional.test.ts:46-59`
16	Manual repair when a notification was missed — self-healing	`POST /v1/procurement/order/order-line/record-receipt` / `.../reverse-receipt`	Orders / order-line: `received` `+=` / `-=` the quantity, pairwise. Manual route carries no `notificationId` — deliberately outside the idempotency scheme	`RNoDemand` — free-form line has no received tracking	`order-receipt.functional.test.ts:26-43, 46-59, 62-82`
17	An automatic self-heal sweeps for missed announcements	— (system — a runtime law probe on a ticker, default-off)	Orders / order-line: `received` converges on the demand-side ledger	—	`Module.kt:102-121`
18	David reviews the order — received amounts current, nothing re-keyed	`GET /v1/procurement/order/order-line/by-order/{orderId}?asOf=`, `GET /v1/procurement/order/order/{eId}/readings?asOf=`	Nothing (read)	404 on a missing order	Readings coverage `order-submit-settle.functional.test.ts:179-195`
19	”The delivery list only grows” — appended, never edited	`GET /v1/operations/demand/demand-item/{eId}/deliveries?asOf=`	Nothing (read). Returns both `CREATED` and `REVOKED` rows	404 on a missing demand item	`demand-item.functional.test.ts:186-191, 204-215`

Fidelity notes

What the tests witness today versus what the narrative claims:

The narrative’s own “not yet wired” caveat is out of date, and this walkthrough already reflects the fix. Steps 13–14 are marked as live, wired system notifications rather than gaps: demand emits, the order module subscribes, idempotency keys on the ProductionDelivery eId, and a runtime probe (step 17) repairs drift. A stale source comment still agrees with the old claim and should be corrected in the same pass as the doc.
Step 9’s “receiving never posts to the order” is inverted today. Because Receiving does not exist, the only human-driveable path to a received amount is the manual record-receipt POST — literally typing a received quantity onto the order line. The claim becomes true once Receiving ships; today the manual route is the sole non-notification path.
The four separately recorded facts (steps 3, 5, 6, 11 — expected, stated, accepted, rejected-with-reason) have zero counterparts in any implemented payload. The order line’s quantity / received pair is the closest structure, and it’s a requested-versus-accrued pair, not an expected-versus-counted one.
Custody and the one-custodian rule (step 8) are unrepresented on the wire. The pool payload has no custodian or location field; the only pool relationships that exist are demand’s holdingRef and memberPools.
No test walks record-production → notification → received in one arc (steps 12–14). The suite covers the two halves separately — demand’s ledger, and the order’s accrual arithmetic via the manual route — and the order-side test file says so explicitly: the listener’s idempotency and missed-window legs are witnessed at the container tier, not the api-test tier.