Receiving Module

Status: Designed — build pending. The design described here is complete and verified in the formal model; it is not yet built into the runtime. The receiving capabilities in the live system today are the lightweight receiving flows described in the canonical use cases: Receiving Behaviors. Linear initiative: Product / Receiving / Receivers.

Purpose

Receiving is where material actually arrives. A Receiver is the capture document a dock clerk builds for one arrival — a truck, a parcel, a handoff — recording what showed up, in what condition, and in what quantities. It is the moment inventory is born into the system: accepted goods become inventory holdings located at the receiving dock, and receipts are attributed to the open order lines they satisfy.

Receiving separates two concerns that meet at the dock:

• Capture — writing down the facts of the arrival: what was expected, what the vendor claimed, what was accepted, what was rejected and why. Capture ends with an explicit freeze: once a line is received, its facts are the permanent record.
• Distribution — moving the born inventory onward to the shop floor. Distribution continues after capture is frozen, against the frozen record.

Context

Receiving sits at the top of the domain map: nothing builds on it, and it builds on five modules. Clients sit to the left of the servers they depend on; every arrow is a dependency the client calls, and together they form a DAG.

What this module consumes:

• Orders — order lines, as attribution targets: a line’s receipt satisfies an order line, with the expected amount frozen at attach. Receiving reads orders and never writes to them.
• Demand — the production-deliveries endpoint, called as received material distributes onward; the order’s received amounts maintain themselves through demand’s accrual wire, without receiving’s involvement.
• Inventory Items — pool and inventory-item birth at the line’s freeze, located at the dock, with custody held until the line releases it.
• Item — lines pin the item they receive; blind lines are gated on retired items at the door.
• Business Affiliate — the delivering carrier, captured as a carrier-role version pin.

What its clients consume from it:

• Nothing — no module depends on Receiving.

Functional decomposition

The module is one service with three endpoints, one per entity of the capture document.

• Receiver service — owns the whole capture document. It provides the Receivers API (create the document at a dock, capture header facts, complete it), the Receiving lines API (add and update lines, Receive — the freeze — record deliveries, complete lines), and the Attributions API (attach and detach the links tying a line’s receipt to order lines). The three surfaces operate one document: the line operations run under their receiver’s window, and the attribution operations under their line’s — the gates in Lifecycle.

Main entities

A receiver owns its lines; each line may carry attributions tying its receipt to order lines.

• Receiver — the capture document for one arrival, anchored to a locator: the physical place this dock is. The locator is the receiver’s identity — every piece of inventory born from its lines starts life located there. The header captures the bill of lading, the operator, and the carrier that delivered — held as a carrier version pin into Business Affiliate, frozen with the captured facts. Internal notes stay editable at any time, even after completion.
• Receiving line — one kind of thing received. A line records what was expected (an item version pin and quantity — or nothing, for a blind line), what the vendor stated on their paperwork (kept as an inert claim, never trusted arithmetic), what was accepted, and what was rejected with the reason why. At its freeze the line births the pool of inventory its accepted count becomes.
• Order attribution — the commercial link: this line’s receipt satisfies that order line, with the expected amount frozen when the link is made and the actual amount written exactly once, at the moment the line is received.

Lifecycle

The receiver and its lines each move forward only — capture ends in an explicit, deliberate freeze, never an automatic one.

Receiver

Completing the receiver requires every line finalized. The gate refuses while any line is still open for capture. Distribution may continue after the receiver completes — the capture record is closed, the material keeps moving. The one exemption from the closed record is the internal notes, editable at any time by design.

Receiving line

• Receive is the freeze. In one act the line’s accepted and rejected counts, the rejection reason, the captured facts, and the attribution actuals are written and frozen — and the accepted goods are born as an inventory pool located at the receiver’s dock. Corrections after the freeze ride the record’s correction mechanism; the freeze is never quietly undone.
• Blind receipts are legal — and gated. A line with no order behind it (goods simply showed up) is an ordinary case. But a blind line is the acceptance decision, so it is vetted at the door: a blind line naming a retired item is refused — the goods are rejected, exactly as goods for an unknown item would be. A line riding an order is never re-gated: the order’s commitment was vetted when it was made, and it is honored even if its item has since retired.

Order attribution

An order attribution deliberately stores no status of its own — its phase is readable from the facts it carries:

• Attached — created (with the line, for an order-connected line; or by an explicit attach) with its expected amount frozen from that moment.
• Actual recorded — the line’s Receive writes the attribution’s actual exactly once, in the same act that freezes the line.
• Detached — an attribution removed while its line was still open for capture; pre-freeze it carries no information of its own, so remove-and-recreate is the sanctioned correction.

Every transition is paired atomically with its owning line’s own record — an attribution never changes independently of the line whose receipt it explains.

Notifications

Every action recorded here is observable to the rest of the system — see how modules stay in sync. Beyond that, this module announces nothing and listens for nothing, by design: every cross-module interaction receiving takes part in is a direct call the caller drives to completion, never a fire-and-forget announcement. In particular, an order’s received amounts maintain themselves through the Demand module’s accrual wire — receiving is not a party to it.

Scenarios

Three moments show capture, birth, and distribution end to end; the clerk is whoever operates the dock.

A line created from an order line is born already attributed, and the freeze writes the actuals across both records in one act.

Goods that arrive with no order behind them are captured blind — and vetted at the door, because the blind line is itself the acceptance decision.

Distribution moves the born inventory onward against the frozen record, and the receiver closes only when every line’s capture is finalized.

These scenarios are verified against the formal model.

Operations

Action	What it does	When it is allowed
Create receiver	Opens a capture document at a dock (its locator).	Any time.
Update receiver	Captures header facts — bill of lading, carrier (pinned), operator.	While Editing.
Add line	Opens a line — from an order line (born attributed) or blind. A blind line naming a retired item is refused.	While the receiver is Editing.
Update line	Adjusts expected/stated facts, or asserts the goods were off-manifest. Re-pinning a blind line to a retired item is refused.	While the line is Receiving.
Attach / detach attribution	Links or unlinks the line’s receipt to an order line, with the expected amount frozen at attach.	While the line is Receiving.
Receive	The freeze: writes accepted and rejected counts (with the reason), frozen facts, attribution actuals — and births the accepted goods as an inventory pool at the dock.	Line still Receiving; the pool must match the line’s item; allocations bounded by the accepted count.
Record delivery	Appends a production delivery to the line as material moves onward.	Line Received (or later, until released).
Complete line	Releases the line — custody of the pool ends.	Line Received.
Complete receiver	Closes the capture document.	No line still Receiving.
Annotate	Internal notes on the receiver — the one field editable at any time, even after completion.	Any time.

Guarantees

• Captured facts are frozen from Receive on. Counts, the rejection reason, the receiving note, the carrier pin, and the attribution membership are the permanent record once the line freezes.
• Accepted and rejected are explicit. What the vendor claimed, what was accepted, and what was refused (and why) are separate recorded facts — nothing is inferred.
• Attribution actuals are written exactly once, by the freeze itself — never edited afterward.
• Delivery lists only grow. Distribution appends; it never rewrites capture.
• Lines never move backward. Receiving → Received → Distributed, in that order, with no regressions.
• A completed receiver is closed — except its internal notes, which remain editable by design.
• Born inventory has exactly one custodian. A pool born at receiving is held by its line until release, and by nothing else — never by two lines, never simultaneously by the replenishment or production machinery.
• Refusals are specific. A disallowed action returns a typed, actionable reason (wrong item for the pool, allocation over the accepted count, lines still open, retired item on a blind line), not a generic error.

How it relates to its neighbors

• Orders — attributions tie receipts to order lines; receiving reads orders and never writes to them.
• Demand — production deliveries record distribution; the order’s received amounts maintain themselves through demand’s accrual wire.
• Inventory Item — accepted goods are born here as inventory pools, located at the dock.
• Item — lines pin the item they receive; blind lines are gated on retired items.
• Business Affiliate — the delivering carrier is captured as a carrier-role version pin, frozen with the receiver’s facts.