Confirmation — executor to planner

Confirmation is the authoritative path. It arrives at end-of-shift, end-of-wave, or on a scheduled cadence, and carries the executor’s cumulative truth for the window. The planner’s accounting close, EDI 947 generation, and audit posture depend on confirmation, not on the realtime stream.

Endpoints

Endpoint

Carries

POST /wes/v1/confirmation/shift-summary

Cumulative movement totals for a (warehouse_id, window_start, window_end).

POST /wes/v1/confirmation/cycle-count

Authoritative cycle-count results: counted quantities per (SKU, location).

POST /wes/v1/confirmation/inventory-snapshot

Full or partial point-in-time inventory snapshot.

Window keying

Every confirmation payload is keyed by:

  • partner_id

  • warehouse_id

  • window_start (RFC 3339 timestamp, inclusive)

  • window_end (RFC 3339 timestamp, exclusive)

  • correlation_id

A second confirmation for the same (partner_id, warehouse_id, window_start, window_end) is a replay — it returns 200 OK with replay: true and does not modify state.

A second confirmation with a different correlation_id for an already-RECONCILED window returns 409 Conflict. To correct a closed window, supervisors must use the discrepancy resolution workflow described below.

Window cadence

Three common cadences:

Cadence

When to use

Shift close

Operations close on shifts (e.g. 06:00 / 14:00 / 22:00). Most common for human-operated warehouses.

Wave close

Operations close on picking waves rather than clock time. Common for high-throughput e-commerce DCs.

Fixed periodic

A simple wall-clock cadence (e.g. every hour on the hour). Good for highly automated facilities with continuous flow.

Pick the cadence the operation actually closes on. Mixing cadences within one warehouse will frustrate supervisors during discrepancy resolution — they cannot easily compare windows of different shapes.

Reconciliation

On confirmation arrival, the planner runs the reconciler. It compares the realtime stream sum for the same (warehouse_id, window_start, window_end) against the confirmation summary:

Result

Planner behavior

Exact match (within tolerance)

Mark window RECONCILED. Emit wes.window.reconciled.v1 event for downstream audit, EDI, GL.

Divergence

Mark window DISCREPANCY. Emit wes.window.discrepancy.v1. Create supervisor queue entry. Fire URGENT notification. Wait for human resolution.

Confirmation never arrives by SLA

Mark window CONFIRMATION_OVERDUE. Fire alert. Supervisors may manually trigger reconciliation against realtime-only data.

The tolerance defaults to zero for serial-tracked SKUs and to a configurable per-warehouse delta for non-tracked SKUs (typical: 0.1% by quantity). Tolerance is set on the planner side per partner-warehouse pair.

Supervisor resolution

A DISCREPANCY is resolved by a supervisor through one of three actions:

  1. Accept confirmation — overwrite the realtime stream’s contribution to inventory for that window with the confirmation totals.

  2. Accept realtime — discard the confirmation deltas.

  3. Manual adjustment — create compensating ADJUST movements that explain the delta in the ledger.

This must be exposed as an explicit operations workflow with a clear audit trail. Silent automatic overwrites are not acceptable for production audit posture — every resolution must be attributable to a named supervisor with a timestamp and reason.

Cycle counts

POST /wes/v1/confirmation/cycle-count carries authoritative counted quantities per (SKU, location). On receipt, the planner:

  1. Compares the counted quantity to the current ledger position.

  2. If equal, marks the count RECONCILED and records the audit trail.

  3. If not equal, creates compensating ADJUST movements automatically when the variance is within auto-reconcile tolerance, or routes to a supervisor for manual approval when it is not.

The auto-reconcile threshold is a per-warehouse, per-SKU-class setting on the planner; the executor does not need to know it.

Inventory snapshots

A snapshot is either:

  • Full — every (warehouse_id, SKU, location, lot?, serial?) position the executor believes is on hand at as_of. The planner uses this as the baseline.

  • Partial — a scoped subset (e.g. one zone, one SKU class). The planner uses it to verify a subset of positions without replacing the whole ledger.

Snapshots are heavy and should be sent at cutover, after major exceptions, or on a scheduled cadence — not as a substitute for /realtime/movements.

Late-arriving corrections

A confirmation may include corrections — adjustments to a previously-confirmed window. The executor sends them as a fresh confirmation payload referencing the corrected window in corrects_window and providing the delta in the payload body. The planner re-opens the prior window, reapplies reconciliation with the delta included, and either re-closes it as RECONCILED or escalates to DISCREPANCY.

Corrections are bounded by retention — windows past the retention horizon (default: 90 days) cannot be corrected through the contract and must be handled out-of-band.