Realtime — executor to planner¶

Realtime endpoints carry continuous, best-effort feedback from the floor. The expected latency budget is sub-second to a few seconds, but the contract tolerates eventual consistency — corrections may arrive later through the confirmation path.

Endpoints¶

Endpoint	What the executor posts
`POST /wes/v1/realtime/movements`	One or more completed inventory movements (`PICK`, `PUT`, `MOVE`, `ADJUST`, `CONSUME`, `PRODUCE`, `RECEIVE`, `SHIP`).
`POST /wes/v1/realtime/exceptions`	Short-pick, damaged product, wrong SKU, robot stuck, worker unavailable, device fault, subsystem offline.
`POST /wes/v1/realtime/work-status`	Task lifecycle transitions: `ASSIGNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELLED`, `FAILED`. Optional.
`POST /wes/v1/realtime/capacity`	Periodic floor / fleet capacity snapshot for dashboards: active workers, idle robots, conveyor utilization, zone WIP. Optional.

movements and exceptions are the required minimum for a useful executor implementation. work-status enables document-detail visibility on the planner side. capacity exists for dashboards only — it must never feed inventory or accounting.

What the planner does with each stream¶

Stream	Planner behavior
Movements	Apply to the inventory ledger immediately. Tag with `source = 'WES'`, `executor_partner_id`, and `executor_correlation_id` so later reconciliation can recognize this contribution.
Exceptions	Surface in a supervisor queue. Trigger the planner’s notification model with severity (`LOW`, `MEDIUM`, `HIGH`, `URGENT`).
Work-status	Persist as task lifecycle. Drives the planner’s document-detail UI; no ledger impact.
Capacity	Dashboards and trend charts only. Never used for inventory math or accounting.

Movement kinds¶

Kind	Meaning
`PICK`	Take from a source location toward outbound staging.
`PUT`	Place into a destination location.
`MOVE`	Relocate within the warehouse (not tied to a document line).
`ADJUST`	Compensating adjustment from cycle count or discrepancy resolution.
`CONSUME`	Work order input consumed.
`PRODUCE`	Work order output produced.
`RECEIVE`	Inbound receipt.
`SHIP`	Outbound shipment.

When the SKU is lot- or serial-tracked, the executor sends lot or serial (or both) alongside the quantity. The planner remains authoritative for SKU, UoM, and location validation; a payload referencing an unknown SKU or location is rejected with 422. See Data mapping for the full envelope.

Idempotency¶

Every realtime call carries a correlation_id. A retry with the same (partner_id, correlation_id) returns 200 OK with replay: true and produces no additional ledger movement, exception, work-status, or capacity record. See Idempotency and ordering for the full rules.

Batching¶

Each endpoint accepts either a single record or an array. Batching is the recommended steady-state mode for executors with high movement rates — pack movements into batches of 10–200 per call to amortize TLS handshake and authentication cost. Each item in a batch carries its own correlation_id; the planner reports per-item results.

Backpressure¶

If the planner returns 429 Too Many Requests, the executor must honor Retry-After and back off. Realtime is best-effort; missing one second of realtime is fine because the confirmation path is authoritative. Do not retry-storm on 429.