Walkthrough: Reality at the Dock

This walkthrough traces FLOW-0005 — Reality at the Dock — a blind receipt with no order behind it, goods rejected outright for a retired or unknown item, and an off-manifest assertion — to API calls. Every dock step is designed — the Receiving module is fully specified on its module page but not yet built — so this page shows what the API surface will owe the flow once Receiving ships, rather than what it delivers today. Where the flow’s underlying principle (“gates sit at the point of choice, never at propagation”) already exists elsewhere in the system, this page points to the nearest built analogue — Demand’s retirement gate at create, and Orders’ deliberate non-gating on propagation — clearly marked as such. Of the flow’s eleven narrative steps, one is physical and the other ten have no callable counterpart: the weakest API coverage of the four flows.

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

A box with no order — the blind line

#	Business step	API call	What changes	Refusals you can hit	Evidence
1	Goods arrive with no order behind them	— (physical step)	—	—	Narrative only
2	Keisha captures a blind line for the item — adding the line is the moment the shop decides to accept these goods	designed — Receiving	—	—	Module absence
3	The blind-line gate: read the item’s current version; Live → the line opens	designed — Receiving. Nearest built analogue: POST /v1/operations/demand/demand-item/create	Analogue — Demand: new demand item, status = OPEN, holding a full ItemReference pin	Analogue: RRetiredRef — the item is retired. RForeignRef (403)	DemandServiceImpl.kt:137-147 (the guard); DemandReason.kt:76-79; demand-item-client.ts:68-73
4	”Blind is the benign default” — the line opens for capture	designed — Receiving	—	—	Module absence

Goods for a retired item — refused at the door

#	Business step	API call	What changes	Refusals you can hit	Evidence
5	A blind line naming a retired item is refused outright; the goods are rejected, as for an item that never existed	designed — Receiving	—	—	Module absence — none of “unreceivable, unorderable, unrequestable” has a receiving-side witness
6	A line riding an order is honored without re-gating, even if its item retired since — it was vetted when the order was committed	designed — Receiving for the receiving line itself. Nearest built analogue: POST /v1/procurement/order/order-line/add-line (mode: FROM_DEMAND)	Analogue — Orders / order-line: the line’s item pin carries retired: true where applicable; the line still commits	Analogue: no retirement refusal on this arm, by design	OrderLineServiceImpl.kt:154-155 — “PROPAGATION arm (cut 8): NO retirement gate — a retired item on a live demand is grandfathered”
7	The asymmetry — gates sit at the point of choice, never at propagation	— (design principle — see Fidelity notes)	—	—	Witnessed on the order/demand pair (steps 3 and 6 above), not the receiving/order pair the narrative draws

Off-manifest is an explicit assertion

#	Business step	API call	What changes	Refusals you can hit	Evidence
8	Keisha asserts the goods were off-manifest — a recorded, attributable statement, distinct from the vendor’s stated quantities	designed — Receiving	—	—	Module absence. The closest recorded-statement shape anywhere is the order line’s confirmation:{disposition, confirmedQuantity} — but that’s the vendor’s answer to an order, not the operator’s assertion at a dock: order-line-client.ts:29-35, 42-55
9	Receive the line — the assertion is frozen into the permanent record with the line’s facts	designed — Receiving	—	—	Module absence

The blind birth

#	Business step	API call	What changes	Refusals you can hit	Evidence
10	Receive the accepted blind line — the pool is born at the dock, with no attributions to write	POST /v1/resources/inventory/inventory-pool/create — the pool birth itself is real and callable, but nothing births one from a blind line	Inventory Items: new pool; content keyed-zero or seed. No location or custodian field on the wire	None at genesis; later RForeignPool (403), ROverdraw, RIncomparable	inventory-pool.functional.test.ts:21-31, 62-71, 73-81, 83-91
11	The permanent record	designed — Receiving	—	—	Module absence

Fidelity notes

What the tests witness today versus what the narrative claims:

• Not one narrative step in this flow is callable. Of the eleven steps above, one is physical, eight have no API at all, and two (3 and 6) are represented only by analogues in other modules — the weakest of the four flows by API coverage, weaker even than receiving-trust, which at least has a fully implemented downstream half.
• The flow’s central principle is implemented, in the wrong pair of modules. “Gates sit at the point of choice, never at propagation” (step 7) is real and load-bearing on this branch — Demand refuses RRetiredRef when a new reference is introduced, and the Order module’s FROM_DEMAND arm deliberately declines to re-gate what demand already vetted. This page demonstrates the principle honestly on that pair while stating plainly that the dock-side instance isn’t built.
• RRetiredRef for the demand slice (step 3’s analogue) is credited to a test that doesn’t exercise it. The generated coverage matrix maps demand’s RRetiredRef to two order tests that both retire a vendor, not an item. No api-test creates a demand item against a retired item, so the item-retirement gate this whole flow rests on is unwitnessed at the API tier despite showing green in the matrix.
• The Item module has no retirement test either. Nothing in the suite retires an item and asserts a downstream consequence, so the “unreceivable, unorderable, unrequestable” rule (step 5) has no direct witness anywhere in the api-test suite.
• The “blind” concept (steps 2, 4) has no data shape. No discriminator anywhere in the implemented payloads distinguishes a line born from an order from a line born blind. The nearest structural echo is the order line’s FREE_FORM arm — but a free-form order line carries less information than a blind receiving line, the opposite of what an analogue needs.

Read next

• FLOW-0005 — Reality at the Dock — the narrative this walkthrough traces.
• Receiving, Item, Inventory Items, Demand, Orders — the module pages that specify the built analogues and the unbuilt receiving behavior.