Orders and fulfilment as shared state

The problem#

An ordinary “order” is often reconstructed from database rows, payment callbacks, shipment records, customer messages, and agent memory. Each organization sees a different reconstruction. Reconciliation becomes the architecture.

The Blue pattern#

The Order is a typed shared document with participants, current state, offered and accepted terms, operations, Messages, and links to provider-backed facts. It can expose operations such as request, accept, confirm, schedule, dispatch, deliver, cancel, dispute, and close.

The exact operation catalog belongs to the Order type or profile. An agent does not infer authority from a UI button or free-text instruction.

Fulfilment providers contribute facts#

A merchant can confirm readiness. A courier can provide tracking and delivery evidence. A product verifier can report an inspection. A customer can acknowledge receipt or open a dispute. Each fact arrives through the provider or participant channel appropriate to the claim.

The Order's contracts determine what consequence follows. A courier Response does not directly mutate a PayNote or Agreement in another Root; it can cause a typed event or subscription update that the related document processes independently.

Embedded or separate?#

Embed a child process when the Order unambiguously owns it, its participants and retention align, and atomic state is valuable. Use a separate document when the object is independently shared, governed, retained, transferred, or scaled.

A PayNote is normally separate because it has its own guarantor, transaction lifecycle, evidence, and visibility. A local risk policy may be embedded.

Agents in the Order#

A customer agent may choose among offered options, schedule delivery, or answer routine Requests under a Mandate. A merchant agent may coordinate capacity. Principal-only operations can reserve final approvals, material substitutions, settlement changes, or termination.

Explainable history#

A user should be able to select a final state and follow the causal path: original Timeline Entry, provider and actor, eligibility, operation, patch, emitted event, connected-document update, and resulting state identity.