Conceptual specifications
Shipment events & lifecycle
Expected versus actual milestones, source provenance, corrections and auditable freight state transitions.
Educational / conceptual specification · Not a released implementation contract
An event describes an observation
A pickup window expresses an expectation. An arrival event expresses an observation. A useful ShipmentEvent should carry related load / stop context, occurrence time, recording time and its source. Human-entered and integration-sourced observations need provenance so an operator can decide how much confidence to place in them.
Loaded, departed, delivered and POD received are not interchangeable. A document can arrive after physical delivery, and a vehicle can be at a facility before any freight moves. The timeline should preserve those differences rather than collapse them into a single operational truth.
{
"loadRef": "ILLUSTRATION-LOAD-A",
"type": "stop.departed",
"occurredAt": "2026-01-15T10:00:00Z",
"recordedAt": "2026-01-15T10:02:00Z",
"source": { "kind": "operator", "reference": "EXAMPLE-ACTOR" },
"note": "Conceptual event example only"
}Late events and corrections
An integration may deliver an old observation after a dispatcher records a newer one. Processing order should not be mistaken for business occurrence order. A repeated source message needs deduplication; a genuine correction needs a relationship to prior evidence and a reason.
The architecture direction is an auditable history alongside current relational state, not an assertion that Kaporeal implements full event sourcing. Transition rules, concurrency and review behavior still need implementation. A late pickup observation should not automatically regress a confirmed delivery.
The exception is part of the shipment story
A short load, damaged unit, missed appointment or incomplete POD needs a responsible review owner and associated evidence. A completed physical movement can still have an unresolved commercial or document exception. Closure should preserve that distinction.
Future alerts and subscriptions can act on trusted events, but are not released. The illustrative shipment page demonstrates intended operator responsibilities and exception paths without suggesting that a live tracking workflow exists.