FG.AI WMS ↔ WES Integration Contract (1.2.0)

Used by executors that cannot consume Kafka and cannot receive webhooks (e.g. air-gapped LANs that allow only outbound HTTPS). The executor polls this endpoint with a cursor; the planner returns dispatch events the executor has not yet acknowledged.

Cursor semantics — since is an opaque server-issued token from the prior page's next_cursor. On the first call, omit since to receive the oldest unacked events.

Ack semantics — after processing a page, call POST /dispatch/ack (separately) with the next_cursor from the response to advance the cursor and release the events.

Per-partner ordering is preserved; per-warehouse FIFO is guaranteed.

Advances the per-partner cursor. Pages whose cursor is at or below the acked value will not be returned to this partner again.

Idempotent on (partner_id, cursor).

This endpoint is not implemented by the planner. It is documented here as the payload shape the executor must accept at its own configured webhook_url when the partner registry records dispatch_transport=webhook.

The planner POSTs one DispatchEvent per webhook call. The executor must respond with HTTP 2xx within 5 seconds to confirm receipt; non-2xx triggers exponential-backoff retry (0s → 5s → 30s → 2m → 10m → 1h, up to 24h, then DLQ).

Webhook calls are at-least-once — the executor MUST be idempotent on (planner_id, correlation_id).

Posted by the executor each time one or more inventory movements complete on the warehouse floor (pick, put, move, adjust, consume, produce).

Movements created from this endpoint are written to the planner's movement log with source='WES', wes_partner_id, and wes_correlation_id. Inventory state is updated immediately via the planner's existing async pattern.

Idempotency — replays of the same (partner_id, correlation_id) for any movement in the batch return HTTP 200 with replay: true; no duplicate movement is persisted.

Batching — up to 500 movements per request. For higher throughput, open multiple parallel connections rather than increasing batch size.

Posted by the executor each time an exception is detected on the warehouse floor: short-pick, damaged product, location empty, wrong SKU, robot stuck, worker unavailable, etc.

Creates a supervisor queue entry on the planner side and fires a NOTIF alert keyed by severity.

Idempotency — replays of the same (partner_id, correlation_id) return HTTP 200 with replay: true.

Optional. Posted by the executor at task lifecycle transitions (ASSIGNED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED, FAILED).

Persisted as WorkAssignment rows on the planner side and surfaced in document detail views; not used for inventory accounting (movements are).

Optional. Posted by the executor periodically (every 30s – 5min recommended) with current floor capacity figures — active pickers, idle robots, conveyor utilization, zone-level WIP counts.

Used for planner-side dashboards; not used for accounting or reconciliation. Discardable.

Posted by the executor at shift / window close. Carries the authoritative cumulative state for the window keyed by (warehouse_id, window_start, window_end, partner_id).

Triggers planner-side reconciliation against the realtime stream sum for the same window:

• Sums match (within tolerance) → window flips to RECONCILED; planner emits wes.window.reconciled.v1.
• Sums diverge → window flips to DISCREPANCY; planner emits wes.window.discrepancy.v1, places an entry in the supervisor queue, fires a NOTIF alert. Supervisor resolves via accept-confirmation / accept-realtime / manual-adjustment.

Posted by the executor on completion of a cycle-count cycle. Treated as definitive for the items / locations covered: the planner's inventory state is adjusted to the counted figures (via compensating ADJUST movements with source='WES').

Divergence from prior planner state beyond the configurable tolerance triggers the discrepancy resolution flow.

Posted by the executor as a point-in-time snapshot of inventory it observes — partial (a subset of locations) or full (whole warehouse). Definitive for the items / locations covered.

Use cases: nightly full-warehouse reconciliation; partial sweeps after a power-loss / network-outage recovery; an AS/RS that snapshots its bay contents on demand.

Cheap, partner-callable health check. No auth required for liveness; readiness includes downstream dependency state and so may require auth depending on tenant config.

Returns the capability matrix this endpoint supports — which realtime / confirmation / dispatch event types are accepted, which auth schemes are honored, which transports are available, and the contract semver this side implements.

Both planner and executor implementations of the contract should expose this; it enables partner adapters to detect feature drift at startup.