Interface principles
PlannedA REST-oriented HTTP interface is the proposed default, served from the Rust core. Resources mirror the domain: loads, stops, events, documents. Writes accept idempotency keys so that partner retries never duplicate records.
- Idempotency keys on every mutating request
- Explicit external references alongside internal IDs
- Organization scope enforced on every query
- Versioned, documented contracts before release
Event subscriptions
PlannedChanges are written to a transactional outbox and delivered to subscribers with at-least-once semantics. Consumers deduplicate by event ID. Signed webhook deliveries are a planned option; streaming transports remain research.
// illustrative event envelope — not an implemented contract
{
"id": "evt_01J…",
"type": "shipment.arrived",
"load": "LD-EXAMPLE-001",
"occurred_at": "2026-01-01T14:05:00Z",
"source": { "kind": "device", "id": "dock-gate-04" },
"sequence": 7
}Provenance and ordering
Each event records who or what produced it and when it was observed versus recorded. Out-of-order arrivals are expected from partners and devices, so ordering uses per-load sequences rather than wall-clock assumptions.
