@openlup/platform 0.21.0 → 0.22.0

package/src/fulfillment/nativeUnsupported.ts

@@ -0,0 +1,23 @@
+import type { FulfillmentCommerceReadPort, FulfillmentShipmentsOverviewPort } from './contracts/read.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+import type { FulfillmentOperatorMutationPort } from './contracts/operator.js';
+import type { FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+export const FULFILLMENT_NATIVE_UNSUPPORTED: FulfillmentNativeUnsupported = Object.freeze({ kind: 'native_unsupported', reason: 'host_binding_required', retryable: false });
+/** Deliberately has no executor: unsupported native parity can never make a partial write. */
+export function createNativeUnsupportedFulfillmentPorts(): FulfillmentReplacementPort & FulfillmentOperatorMutationPort & FulfillmentCommerceReadPort & FulfillmentShipmentsOverviewPort & { readCustomerAlignmentRows: FulfillmentCustomerAlignmentRowsReader } {
+  const unsupported = async () => FULFILLMENT_NATIVE_UNSUPPORTED;
+  return {
+    requestReplacementShipment: unsupported,
+    createCommerceFulfillmentOrder: unsupported,
+    recordCommerceFulfillmentProviderAttempt: unsupported,
+    recordCommerceFulfillmentLabel: unsupported,
+    handOffCommerceFulfillmentOrder: unsupported,
+    recordCommerceFulfillmentTrackingEvent: unsupported,
+    cancelCommerceFulfillmentOrder: unsupported,
+    readCustomerAlignmentRows: unsupported,
+    listCommerceFulfillmentOrders: unsupported,
+    getCommerceFulfillmentOrderDetail: unsupported,
+    getShipmentsOverview: unsupported,
+  };
+}

package/src/fulfillment/normalizedFulfillmentFacts.ts

@@ -0,0 +1,2 @@
+export { isCanonicalLocalFulfillmentStatus, parseFulfillmentFact, parseFulfillmentTransitionConflict } from "@openlup/core/fulfillment";
+export type { CanonicalNormalizedFulfillmentFact as NormalizedFulfillmentFact, CanonicalNormalizedFulfillmentFactV1 as NormalizedFulfillmentFactV1, CanonicalNormalizedFulfillmentFactV0 as NormalizedFulfillmentFactV0, CanonicalCompatibleNormalizedFulfillmentFact as CompatibleNormalizedFulfillmentFact, CanonicalFulfillmentTransitionSnapshot as FulfillmentTransitionSnapshot, CanonicalTransitionConflict as TransitionConflict } from "@openlup/core/fulfillment";

package/src/fulfillment/observationProjection.ts

@@ -0,0 +1,41 @@
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation } from "./contracts/index.js";
+import { parseFulfillmentFact } from "./normalizedFulfillmentFacts.js";
+import { FULFILLMENT_STATUS_MAP } from "./statusMap.js";
+
+export function projectCorrelation(value: FulfillmentObservation["correlation"]): FulfillmentObservation["correlation"] {
+  const { orderRef, fulfillmentRef, externalRef, orderNumber, providerFulfillmentRef, parcelRef } = value;
+  return { orderRef, fulfillmentRef, externalRef, orderNumber, providerFulfillmentRef, parcelRef };
+}
+
+/** New boundary projection: arbitrary adapter properties are never durable. */
+export function projectObservation(value: FulfillmentObservation): FulfillmentObservation {
+  const diagnostics: NonNullable<FulfillmentObservation["diagnostics"]> = {};
+  if (value.diagnostics?.refusal) {
+    const { reason, phase, retryable } = value.diagnostics.refusal;
+    diagnostics.refusal = { reason, phase, retryable };
+  }
+  if (value.diagnostics?.stockContention) diagnostics.stockContention = { sqlState: "55P03", phase: "provider_stock_consumed", retryable: true };
+  if (value.diagnostics?.annotation) diagnostics.annotation = value.diagnostics.annotation;
+  if (value.diagnostics?.recoveredPickedReceipt) {
+    const { receiptRef, closed } = value.diagnostics.recoveredPickedReceipt;
+    diagnostics.recoveredPickedReceipt = { receiptRef, closed };
+  }
+  return {
+    fact: parseFulfillmentFact(value.fact), eventKind: value.eventKind, eventKey: value.eventKey,
+    firstReceivedAt: value.firstReceivedAt,
+    correlation: projectCorrelation(value.correlation),
+    trackingRefs: value.trackingRefs.map(({ trackingNumber, carrierRef, serviceRef, publicUrl }) => ({ trackingNumber, carrierRef, serviceRef, publicUrl })),
+    ...(Object.keys(diagnostics).length ? { diagnostics } : {}),
+  };
+}
+
+const HANDOVER_STATUSES: ReadonlySet<string> = new Set(
+  FULFILLMENT_STATUS_MAP.stages.filter(stage => stage.effects.handover).flatMap(stage => stage.localStatus),
+);
+/** Donor finished-picking boundary is narrower than the coarse packing stage. */
+export const observationStatusPolicy = {
+  consumesStock: (status: CanonicalLocalFulfillmentStatus) => ["packed", "in_transit", "delivered"].includes(status),
+  handsOver: (status: CanonicalLocalFulfillmentStatus) => HANDOVER_STATUSES.has(status),
+  suppressDispatched: (status: CanonicalLocalFulfillmentStatus) => status === "delivered",
+  trackingStatus: (status: CanonicalLocalFulfillmentStatus) => status as "in_transit" | "delivered",
+};

package/src/fulfillment/omnipack/capabilities.ts

@@ -0,0 +1,18 @@
+import type { FulfillmentCapabilityDescriptor } from "../contracts/index.js";
+
+/** Offline protocol capabilities; selection and account readiness belong to the host. */
+export const omnipackFulfillmentCapabilities: Readonly<FulfillmentCapabilityDescriptor> = Object.freeze<FulfillmentCapabilityDescriptor>({
+  providerRef: "omnipack", role: "warehouse", defaultOff: true, selected: false,
+  readiness: Object.freeze({ ready: false, refusal: Object.freeze({ reason: "not_ready", phase: "selection", retryable: false }) }),
+  operations: Object.freeze({
+    dispatch: Object.freeze({ supported: true }), readback: Object.freeze({ supported: true }),
+    exactAbsence: Object.freeze({ supported: false, reason: "not_exposed" }), verifyObservation: Object.freeze({ supported: true }),
+    syncStock: Object.freeze({ supported: true }), syncProducts: Object.freeze({ supported: true }),
+    labelCreate: Object.freeze({ supported: false, reason: "not_exposed" }), labelRead: Object.freeze({ supported: false, reason: "host_only" }),
+    labelVoid: Object.freeze({ supported: false, reason: "not_exposed" }), cancel: Object.freeze({ supported: false, reason: "not_exposed" }),
+    pickupPoint: Object.freeze({ supported: true }), courierPickup: Object.freeze({ supported: false, reason: "not_exposed" }),
+  }),
+  authentication: "token", freshness: "not_available", ownsDeliveredNotification: false,
+  stockAuthority: "external_stock_master_with_local_reservations", labelReadOwner: "host_storage",
+  actionPolicy: Object.freeze({ providerSpecificAdminActions: false, genericAdminActions: true, mutationSurface: "provider_adapter" }),
+});

package/src/fulfillment/omnipack/client.ts

@@ -0,0 +1,258 @@
+import {
+  mapOmnipackFulfilmentRequestsResponse,
+  mapOmnipackFulfilmentsResponse,
+  mapOmnipackOrderCreatedResponse,
+  mapOmnipackProductCreatedResponse,
+  mapOmnipackStockMovementsResponse,
+  mapOmnipackStockResponse,
+  sanitizeOmnipackPayload,
+  type OmnipackFulfilmentEvidence,
+  type OmnipackFulfilmentRequestEvidence,
+  type OmnipackOrderCreatedEvidence,
+  type OmnipackProductCreatedEvidence,
+  type OmnipackStockEvidence,
+  type OmnipackStockMovementEvidence,
+} from "./mappers.js";
+import {
+  mapOmnipackProductPackCreatedResponse,
+  mapOmnipackProductResponse,
+  type OmnipackProductEvidence,
+  type OmnipackProductPackCreatedEvidence,
+} from "./productSyncMappers.js";
+import { mayPostHaveSucceeded, OmnipackProviderError } from "./providerError.js";
+
+export {
+  OmnipackProviderError,
+  sanitizeOmnipackProviderError,
+  type SanitizedOmnipackProviderError,
+} from "./providerError.js";
+
+const PRODUCT_PACKS_SEGMENT = "packs";
+
+export interface OmnipackClientConfig {
+  baseUrl: string;
+  credentials: () => { username: string; password: string } | Promise<{ username: string; password: string }>;
+  timeoutMs: number;
+  safeReadRetries: number;
+  productPath: string;
+}
+
+export interface OmnipackClient {
+  createOrder(body: string): Promise<OmnipackOrderCreatedEvidence>;
+  // Product sync. createProduct/createProductPack are POST, so
+  // requestJson does NOT retry them (mutations must not be silently re-sent). getProduct is a
+  // GET (retried) reading the SKU's packs[] — one SKU ↔ many EANs.
+  createProduct(payload: Record<string, unknown>, sku: string): Promise<OmnipackProductCreatedEvidence>;
+  getProduct(sku: string): Promise<OmnipackProductEvidence>;
+  createProductPack(sku: string, payload: Record<string, unknown>, ean: string): Promise<OmnipackProductPackCreatedEvidence>;
+  getStock(): Promise<OmnipackStockEvidence[]>;
+  getStockMovements(params?: OmnipackQueryParams): Promise<OmnipackStockMovementEvidence[]>;
+  getFulfilmentsPage(params?: OmnipackQueryParams): Promise<{ rows: OmnipackFulfilmentEvidence[]; complete: boolean }>;
+  getFulfilments(params?: OmnipackQueryParams): Promise<OmnipackFulfilmentEvidence[]>;
+  getFulfilmentRequests(params?: OmnipackQueryParams): Promise<OmnipackFulfilmentRequestEvidence[]>;
+}
+
+export interface OmnipackQueryParams {
+  startLocalDate?: string;
+  endLocalDate?: string;
+  page?: number;
+  size?: number;
+}
+
+export function createOmnipackClient(
+  config: OmnipackClientConfig,
+  fetchImpl: typeof fetch,
+): OmnipackClient {
+  return {
+    async createOrder(body) {
+      return mapOmnipackOrderCreatedResponse(await requestJson(fetchImpl, config, "createOrder", "/orders", {
+        method: "POST",
+        body,
+      }));
+    },
+
+    async createProduct(payload, sku) {
+      const body = await requestJson(fetchImpl, config, "createProduct", config.productPath, post(payload));
+      return mapOmnipackProductCreatedResponse(body, sku);
+    },
+
+    async getProduct(sku) {
+      const path = productResourcePath(config.productPath, sku);
+      return mapOmnipackProductResponse(await requestJson(fetchImpl, config, "getProduct", path, { method: "GET" }), sku);
+    },
+
+    async createProductPack(sku, payload, ean) {
+      const path = `${productResourcePath(config.productPath, sku)}/${PRODUCT_PACKS_SEGMENT}`;
+      const body = await requestJson(fetchImpl, config, "createProductPack", path, post(payload));
+      return mapOmnipackProductPackCreatedResponse(body, sku, ean);
+    },
+
+    async getStock() {
+      return mapOmnipackStockResponse(await requestJson(fetchImpl, config, "getStock", "/stock", { method: "GET" }));
+    },
+
+    async getStockMovements(params) {
+      return mapOmnipackStockMovementsResponse(await requestJson(
+        fetchImpl,
+        config,
+        "getStockMovements",
+        withQuery("/stock-movements", params),
+        { method: "GET" },
+      ));
+    },
+
+    async getFulfilmentsPage(params) {
+      const body = await requestJson(fetchImpl, config, "getFulfilments", withQuery("/fulfilments", params), { method: "GET" });
+      const rows = mapOmnipackFulfilmentsResponse(body);
+      // Only explicit single-page totals establish whole-collection uniqueness.
+      const record = body as { page?: { number?: unknown; size?: unknown; totalPages?: unknown; totalElements?: unknown }; _links?: { next?: unknown }; incomplete?: unknown; partial?: unknown } | null;
+      const page = record?.page;
+      const complete = page?.number === 0 && page.totalPages === 1 && page.totalElements === rows.length
+        && typeof page.size === "number" && Number.isSafeInteger(page.size) && page.size >= rows.length && page.size > 0
+        && !record?._links?.next && !record?.incomplete && !record?.partial;
+      return { rows, complete };
+    },
+
+    async getFulfilments(params) {
+      return mapOmnipackFulfilmentsResponse(await requestJson(
+        fetchImpl,
+        config,
+        "getFulfilments",
+        withQuery("/fulfilments", params),
+        { method: "GET" },
+      ));
+    },
+
+    async getFulfilmentRequests(params) {
+      return mapOmnipackFulfilmentRequestsResponse(await requestJson(
+        fetchImpl,
+        config,
+        "getFulfilmentRequests",
+        withQuery("/fulfilment-requests", params),
+        { method: "GET" },
+      ));
+    },
+  };
+}
+
+async function requestJson(
+  fetchImpl: typeof fetch,
+  config: OmnipackClientConfig,
+  operation: string,
+  path: string,
+  init: RequestInit,
+): Promise<unknown> {
+  const method = (init.method ?? "GET").toUpperCase();
+  const attempts = method === "GET" ? config.safeReadRetries + 1 : 1;
+  let lastError: unknown = null;
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    let submitted = false;
+    try {
+      const base = new URL(config.baseUrl);
+      const url = new URL(path, base);
+      if (url.origin !== base.origin || url.username || url.password || url.protocol !== "https:") throw new Error("Invalid fulfillment path");
+      const response = await fetchWithTimeout(fetchImpl, url, config, init, () => { submitted = true; });
+      if (response.ok) return await readJsonBody(response);
+
+      const retryable = method === "GET" && isRetryableStatus(response.status);
+      // A failed body read cannot erase the rejection status already received.
+      const body = await readJsonBody(response).catch(() => null);
+      lastError = new OmnipackProviderError({
+        operation,
+        status: response.status,
+        code: readProviderErrorCode(body) ?? `http_${response.status}`,
+        retryable,
+        mayHaveSucceeded: mayPostHaveSucceeded(method, response.status),
+      });
+      if (!retryable || attempt === attempts) throw lastError;
+    } catch (error) {
+      const retryable = method === "GET" && attempt < attempts;
+      lastError = submitted && error instanceof OmnipackProviderError
+        ? error
+        : new OmnipackProviderError({
+          operation,
+          status: null,
+          code: "network_error",
+          retryable,
+          mayHaveSucceeded: submitted && mayPostHaveSucceeded(method, null),
+        });
+      if (!retryable) throw lastError;
+    }
+  }
+
+  throw lastError;
+}
+
+async function fetchWithTimeout(
+  fetchImpl: typeof fetch,
+  url: URL,
+  config: OmnipackClientConfig,
+  init: RequestInit,
+  onSubmit: () => void,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+  try {
+    const credentials = await config.credentials();
+    const requestInit: RequestInit = {
+      ...init,
+      signal: controller.signal,
+      redirect: "error",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        Authorization: `Basic ${Buffer.from(`${credentials.username}:${credentials.password}`).toString("base64")}`,
+        ...(init.headers ?? {}),
+      },
+    };
+    new Request(url, requestInit); // Validate construction before crossing the submission boundary.
+    controller.signal.throwIfAborted();
+    onSubmit();
+    return await fetchImpl(url, requestInit);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function readJsonBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return sanitizeOmnipackPayload(JSON.parse(text) as Record<string, unknown>);
+  } catch {
+    return {};
+  }
+}
+
+// A non-retried JSON POST init (mutations must not be silently re-sent — requestJson keys retry
+// off the GET method).
+function post(payload: Record<string, unknown>): RequestInit {
+  return { method: "POST", body: JSON.stringify(payload) };
+}
+
+// Per-product resource path (GET /products/{sku}, base for /packs). sku is percent-encoded; the
+// product path is right-trimmed so a trailing-slash path override does not double the slash.
+function productResourcePath(productPath: string, sku: string): string {
+  return `${productPath.replace(/\/+$/, "")}/${encodeURIComponent(sku)}`;
+}
+
+function withQuery(path: string, params: OmnipackQueryParams | undefined): string {
+  const url = new URL(path, "https://example.test");
+  if (params?.startLocalDate) url.searchParams.set("startLocalDate", params.startLocalDate);
+  if (params?.endLocalDate) url.searchParams.set("endLocalDate", params.endLocalDate);
+  if (typeof params?.page === "number") url.searchParams.set("page", String(params.page));
+  if (typeof params?.size === "number") url.searchParams.set("size", String(params.size));
+  return `${url.pathname}${url.search}`;
+}
+
+function readProviderErrorCode(body: unknown): string | null {
+  return typeof body === "object" && body !== null && "code" in body && typeof body.code === "string"
+    && /^[A-Z][A-Z0-9_]{0,63}$/.test(body.code)
+    ? body.code
+    : null;
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 408 || status === 429 || status >= 500;
+}

package/src/fulfillment/omnipack/index.ts

@@ -0,0 +1,312 @@
+import type { DispatchEvidence, FulfillmentCapabilityDescriptor, FulfillmentDispatchPort, FulfillmentDispatchRequest,
+  FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider } from "../contracts/index.js";
+import { createOmnipackClient, OmnipackProviderError } from "./client.js";
+import { omnipackFulfillmentCapabilities } from "./capabilities.js";
+import { buildOmnipackDispatchCommand, serializeOmnipackDispatchPayload, stableDispatchHash } from "./omnipackDispatchPayload.js";
+import { mapOmnipackWebhookPayload } from "./mappers.js";
+import { verifyOmnipackWebhookToken, type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
+import { localStatusFor, normalizeStatus } from "./omnipackStatusVocabulary.js";
+import { digest, eventKind, observation, reference, refusal, timestamp } from "./observation.js";
+export { omnipackFulfillmentCapabilities } from "./capabilities.js";
+
+/** Node-only, explicit construction. Secrets are supplied per call, never retained as values. */
+export interface OmnipackFulfillmentAdapterConfig {
+  http: {
+    baseUrl: string; credentials: () => { username: string; password: string } | Promise<{ username: string; password: string }>;
+    fetchImpl: typeof fetch; timeoutMs: number; safeReadRetries: number; productPath: string;
+  };
+  selected?: boolean;
+  /** Per-instance retention target; default 10,000. Evicts oldest completed submissions, never in-flight. */
+  maxRetainedSubmissions?: number;
+  /** Host account evidence, independent of credentials. Omission remains not ready. */
+  readiness?: FulfillmentCapabilityDescriptor["readiness"];
+  /** Called in prepare and again for new dispatches; return identical metadata for the same request or dispatch refuses. */
+  resolveProduct: (line: FulfillmentDispatchRequest["lines"][number]) => Promise<{ lotNumber?: string; expirationDate?: string } | null>;
+  notification: { token: () => string | undefined | Promise<string | undefined>; expectedEvent: OmnipackWebhookRouteEvent };
+  clock: () => string;
+  mintEvidenceReference: () => `evidence:${string}`;
+  mintSyncRunId: () => string;
+  approveTrackingUrl: (url: string) => boolean;
+  /** Writes occur only through deliberate calls; scheduled composition must remain pull-only. */
+  product?: { resolvePushMetadata: (sku: string) => Promise<Record<string, unknown> | null> };
+}
+
+/** No route, schedule, environment reader or default binding is installed. */
+export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdapterConfig): {
+  capabilities: FulfillmentCapabilityDescriptor;
+  dispatch: FulfillmentDispatchPort;
+  label: FulfillmentLabelPort;
+  observation: FulfillmentObservationPort;
+  readback: FulfillmentReadbackPort;
+  stockSync: FulfillmentStockSyncProvider;
+  productSync: FulfillmentProductSyncProvider;
+} {
+  const maxRetainedSubmissions = config.maxRetainedSubmissions === undefined ? 10_000 : config.maxRetainedSubmissions;
+  const base = new URL(config.http.baseUrl);
+  if (base.protocol !== "https:" || base.username || base.password || base.search || base.hash
+    || !Number.isSafeInteger(maxRetainedSubmissions) || maxRetainedSubmissions <= 0
+    || typeof config.http.fetchImpl !== "function" || typeof config.http.credentials !== "function"
+    || !Number.isSafeInteger(config.http.timeoutMs) || config.http.timeoutMs <= 0
+    || !Number.isSafeInteger(config.http.safeReadRetries) || config.http.safeReadRetries < 0
+    || !/^\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*\/?$/u.test(config.http.productPath)
+    || !eventKind(config.notification.expectedEvent)) throw new Error("Invalid fulfillment configuration");
+  const client = createOmnipackClient({ ...config.http }, config.http.fetchImpl);
+  // Copy the profile so host selection never mutates the exported default-off descriptor.
+  const capabilities: FulfillmentCapabilityDescriptor = structuredClone(omnipackFulfillmentCapabilities);
+  capabilities.selected = config.selected === true;
+  capabilities.readiness = config.readiness?.ready === true ? { ready: true }
+    : { ready: false, refusal: refusal("not_ready", "selection") };
+  const submissions = new Map<string, { evidenceKey: string; commandDigest: string; completed: boolean; result: ReturnType<FulfillmentDispatchPort["dispatch"]> }>();
+  const evictCompleted = () => {
+    for (const [fingerprint, submission] of submissions) {
+      if (submissions.size <= maxRetainedSubmissions) break;
+      if (submission.completed) submissions.delete(fingerprint);
+    }
+  };
+  const selectionFailure = (request: FulfillmentDispatchRequest) => {
+    if (!request.selection?.providerRef?.trim()) return refusal("selection_required", "selection");
+    if (request.selection.providerRef !== capabilities.providerRef) return refusal("provider_mismatch", "selection");
+    if (!reference(request.selection.carrierRef) || !reference(request.selection.serviceRef)) return refusal("carrier_service_required", "selection");
+    if (!capabilities.selected) return refusal("disabled", "selection");
+    if (!capabilities.readiness.ready) return refusal("not_ready", "selection");
+    return null;
+  };
+  const requireSync = () => {
+    if (!capabilities.selected || !capabilities.readiness.ready) throw refusal(capabilities.selected ? "not_ready" : "disabled", "sync");
+  };
+  const syncIdentity = () => {
+    const syncRunId = reference(config.mintSyncRunId());
+    const collectedAt = timestamp(config.clock());
+    if (!syncRunId || !collectedAt) throw refusal("malformed", "sync");
+    return { providerRef: capabilities.providerRef, syncRunId, collectedAt, sourceRevision: null, revisionSource: "collection" as const };
+  };
+  // Shared computation: host metadata and serialized bytes live only for this call.
+  const buildCommand = async (request: FulfillmentDispatchRequest) => {
+    const requestDigest = stableDispatchHash(request);
+    if (!Number.isSafeInteger(request.contactRevision.schemaVersion) || request.contactRevision.schemaVersion < 1
+      || !reference(request.contactRevision.source) || !Number.isSafeInteger(request.contactRevision.revision)
+      || request.contactRevision.revision < 0) throw Error();
+    const lines = [];
+    for (const line of request.lines) {
+      const metadata = await config.resolveProduct(line);
+      if (!metadata) throw Error();
+      lines.push({ sku: line.skuRef, quantity: line.quantity, productSnapshot: { lotNumber: metadata.lotNumber, expirationDate: metadata.expirationDate } });
+    }
+    if (stableDispatchHash(request) !== requestDigest) throw Error();
+    const command = buildOmnipackDispatchCommand({
+      orderId: request.orderRef, orderNumber: request.orderNumber,
+      deliveryContact: { revision: request.contactRevision.revision, recipientName: request.recipient.name,
+        contactEmail: request.recipient.email, contactPhone: request.recipient.phone, line1: request.recipient.line1,
+        city: request.recipient.city, postalCode: request.recipient.postalCode, country: request.recipient.country,
+        selectedDelivery: { providerKind: capabilities.providerRef, carrierKind: request.selection.carrierRef,
+          serviceCode: request.selection.serviceRef, deliveryKind: request.selection.deliveryKind, pickupPoint: request.selection.pickupPoint } }, lines,
+    });
+    const evidence: DispatchEvidence = { commandFingerprint: command.requestFingerprint,
+      contactRevision: { schemaVersion: request.contactRevision.schemaVersion, source: request.contactRevision.source, revision: request.contactRevision.revision },
+      providerRef: capabilities.providerRef, carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef };
+    return { body: command.body, evidence };
+  };
+  return {
+    capabilities,
+    dispatch: {
+      async prepare(request) {
+        const failed = selectionFailure(request);
+        if (failed) return { kind: "refused", refusal: failed };
+        try { return { kind: "prepared", evidence: (await buildCommand(request)).evidence }; }
+        catch { return { kind: "refused", refusal: refusal("not_dispatchable", "prepare") }; }
+      },
+      async dispatch(request, evidence) {
+        let commandRequest: FulfillmentDispatchRequest;
+        let fingerprint: string;
+        let evidenceKey: string;
+        let requestCommandDigest: string;
+        try {
+          // Validate the closed evidence and its request-bound values without consulting preparation state.
+          if (Object.keys(evidence).length !== 5 || Object.keys(evidence.contactRevision).length !== 3
+            || typeof evidence.commandFingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(evidence.commandFingerprint)
+            || !reference(evidence.providerRef)
+            || !reference(evidence.carrierRef) || !reference(evidence.serviceRef)
+            || !Number.isSafeInteger(evidence.contactRevision.schemaVersion) || evidence.contactRevision.schemaVersion < 1
+            || !reference(evidence.contactRevision.source) || !Number.isSafeInteger(evidence.contactRevision.revision)
+            || evidence.contactRevision.revision < 0
+            || evidence.contactRevision.schemaVersion !== request.contactRevision.schemaVersion
+            || evidence.contactRevision.source !== request.contactRevision.source
+            || evidence.contactRevision.revision !== request.contactRevision.revision
+            || evidence.providerRef !== request.selection.providerRef
+            || evidence.carrierRef !== request.selection.carrierRef || evidence.serviceRef !== request.selection.serviceRef) throw Error();
+          evidenceKey = serializeOmnipackDispatchPayload(evidence).body;
+          requestCommandDigest = commandDigest(request);
+          const submitted = submissions.get(evidence.commandFingerprint);
+          if (submitted) {
+            // Replay is bound to this submission's evidence and command, never replaceable preparation.
+            if (submitted.evidenceKey !== evidenceKey || submitted.commandDigest !== requestCommandDigest) throw Error();
+            return structuredClone(await submitted.result);
+          }
+          if (selectionFailure(request)) throw Error();
+          commandRequest = structuredClone(request);
+          fingerprint = evidence.commandFingerprint;
+        } catch { return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal("not_dispatchable", "dispatch") }; }
+        // Reserve before host resolution too, so concurrent dispatches join the rebuild.
+        const result = Promise.resolve().then(async () => {
+          let command;
+          try {
+            command = await buildCommand(commandRequest);
+            if (command.evidence.commandFingerprint !== fingerprint) throw Error();
+          } catch {
+            // A stale or unresolved command has never reached credentials or HTTP.
+            submissions.delete(fingerprint);
+            return { kind: "not_dispatched" as const, effectMayHaveSucceeded: false as const, refusal: refusal("not_dispatchable", "dispatch") };
+          }
+          try {
+            const result = await client.createOrder(command.body);
+            const externalRef = reference(result.providerOrderId);
+            if (!externalRef) return { kind: "unknown" as const, effectMayHaveSucceeded: true as const, refusal: refusal("malformed", "acknowledge") };
+            // Opaque provider proof; the worker replaces these with authoritative host keys.
+            const proof = digest(JSON.stringify([externalRef, command.evidence.commandFingerprint]));
+            return { kind: "accepted" as const, externalRef, evidence: structuredClone(command.evidence),
+              providerAttemptKey: `attempt:${proof}`, labelKey: `label:${proof}` };
+          } catch (error) {
+            return error instanceof OmnipackProviderError && !error.mayHaveSucceeded
+              ? { kind: "not_dispatched" as const, effectMayHaveSucceeded: false as const, refusal: refusal("io_failure", "dispatch") }
+              : { kind: "unknown" as const, effectMayHaveSucceeded: true as const, refusal: refusal("io_failure", "dispatch") };
+          } finally {
+            command.body = "";
+            submissions.get(fingerprint)!.completed = true;
+            evictCompleted();
+          }
+        });
+        submissions.set(fingerprint, { evidenceKey, commandDigest: requestCommandDigest, completed: false, result });
+        evictCompleted();
+        return structuredClone(await result);
+      },
+    },
+    label: {
+      async create() { return { kind: "refused", refusal: refusal("unsupported", "dispatch") }; },
+      async read() { return { kind: "refused", refusal: refusal("unsupported", "dispatch") }; },
+      async void() { return { providerDeletion: "unconfirmed", labelDeleted: false, canProceed: false, refusal: refusal("unsupported", "dispatch") }; },
+    },
+    observation: {
+      async verifyAndNormalize(input) {
+        // Token check precedes every read of rawBody and every parse.
+        try {
+          if (!verifyOmnipackWebhookToken({ headers: { ...input.headers } }, await config.notification.token()))
+            return { kind: "refused", refusal: refusal("untrusted", "verify") };
+        } catch { return { kind: "refused", refusal: refusal("untrusted", "verify") }; }
+        try {
+          const rawBody = Buffer.from(input.rawBody);
+          const payload: unknown = JSON.parse(rawBody.toString("utf8"));
+          if (!payload || typeof payload !== "object" || Array.isArray(payload)) return { kind: "refused", refusal: refusal("malformed", "normalize") };
+          if ("event" in payload && (typeof payload.event !== "string" || !eventKind(payload.event)))
+            return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
+          const evidence = mapOmnipackWebhookPayload(payload, config.notification.expectedEvent);
+          const event = eventKind(evidence.event);
+          if (!event || event !== config.notification.expectedEvent) return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
+          if (![evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => reference(value)))
+            return { kind: "refused", refusal: refusal("missing_correlation", "normalize") };
+          return { kind: "verified", observation: observation({ evidence, event, receivedAt: input.receivedAt,
+            rawDigest: digest(rawBody), evidenceRef: config.mintEvidenceReference(), source: "provider_webhook", approveTrackingUrl: config.approveTrackingUrl }) };
+        } catch { return { kind: "refused", refusal: refusal("malformed", "normalize") }; }
+      },
+    },
+    readback: {
+      async read(input) {
+        if (input.providerRef !== capabilities.providerRef) return { kind: "unsupported", refusal: refusal("provider_mismatch", "readback") };
+        if (!capabilities.selected || !capabilities.readiness.ready) return { kind: "unsupported", refusal: refusal(capabilities.selected ? "not_ready" : "disabled", "readback") };
+        if (!reference(input.externalRef)) return { kind: "unsupported", refusal: refusal("unsupported", "readback") };
+        try {
+          const collection = await client.getFulfilmentsPage({ page: 0, size: 100 });
+          if (!collection.complete) return { kind: "unknown", refusal: refusal("local_missing", "readback") };
+          const matches = collection.rows.filter(row => input.mode === "parcel"
+            ? row.fulfilmentNumber === input.externalRef : row.providerOrderId === input.externalRef);
+          if (matches.length !== 1) return { kind: "unknown", refusal: refusal("local_missing", "readback") };
+          const row = matches[0]!;
+          const normalized = normalizeStatus(row.status);
+          if (!normalized) return { kind: "unknown", refusal: refusal("unsupported_event", "readback") };
+          const status = localStatusFor(normalized) as "provider_received" | "picking" | "packed" | "in_transit" | "delivered" | "exception";
+          const event = ({ provider_received: "shipment.accepted", picking: "order.processing_started", packed: "order.picked", in_transit: "order.shipped", delivered: "order.delivered", exception: "parcel.exception" } as const)[status];
+          const evidence = { provider: "omnipack" as const, event, providerOrderId: row.providerOrderId, orderNumber: row.orderNumber,
+            fulfilmentNumber: row.fulfilmentNumber, occurredAt: row.updatedAt, trackingNumbers: row.trackingNumbers,
+            trackingReferences: row.trackingReferences, shippingMethods: [] };
+          return { kind: "found", externalRef: input.externalRef!, createdAt: timestamp(row.createdAt), updatedAt: timestamp(row.updatedAt),
+            observation: observation({ evidence, event, status, fulfillmentRef: input.fulfillmentRef, receivedAt: config.clock(),
+              rawDigest: digest(JSON.stringify(evidence)), evidenceRef: config.mintEvidenceReference(), source: "provider_reconciliation", approveTrackingUrl: config.approveTrackingUrl }) };
+        } catch { return { kind: "unknown", refusal: refusal("io_failure", "readback") }; }
+      },
+    },
+    stockSync: {
+      async getStock() {
+        requireSync();
+        try {
+          const identity = syncIdentity();
+          return (await client.getStock()).map(row => {
+            const skuRef = reference(row.sku);
+            if (!skuRef) throw refusal("malformed", "sync");
+            return { ...identity, skuRef, quantityKind: "snapshot" as const, totalQuantity: row.totalQuantity,
+              forSaleQuantity: row.forSaleQuantity, reservedOrUnavailableQuantity: row.reservedOrUnavailableQuantity };
+          });
+        } catch { throw refusal("io_failure", "sync"); }
+      },
+      async getStockMovements(input) {
+        requireSync();
+        try {
+          const identity = syncIdentity();
+          return (await client.getStockMovements(input)).map(row => {
+            const skuRef = reference(row.sku);
+            if (!skuRef) throw refusal("malformed", "sync");
+            return { ...identity, skuRef, quantityKind: "movement" as const, quantity: row.quantity, occurredAt: timestamp(row.occurredAt),
+              operationType: reference(row.operationType), documentRef: reference(row.warehouseDocumentNumber), lotRef: reference(row.lotNumber), expirationDate: /^\d{4}-\d\d-\d\d$/u.test(row.expirationDate ?? "") ? row.expirationDate : null };
+          });
+        } catch { throw refusal("io_failure", "sync"); }
+      },
+    },
+    productSync: {
+      async ensureProduct(sku) {
+        requireSync();
+        try {
+          const metadata = await config.product?.resolvePushMetadata(sku);
+          if (!metadata) return null;
+          await client.createProduct(metadata, sku);
+          return { replayed: false };
+        } catch { throw refusal("io_failure", "sync"); }
+      },
+      async getProductPacks(sku) {
+        requireSync();
+        try { return (await client.getProduct(sku)).packs.filter(pack => /^\d{8,14}$/u.test(pack.ean) && Number.isSafeInteger(pack.quantity) && pack.quantity > 0).map(pack => ({ ean: pack.ean, quantity: pack.quantity })); }
+        catch { throw refusal("io_failure", "sync"); }
+      },
+      async addProductPack(sku, pack) {
+        requireSync();
+        if (!/^\d{8,14}$/u.test(pack.ean) || !Number.isSafeInteger(pack.quantity) || pack.quantity <= 0) throw refusal("malformed", "sync");
+        try { await client.createProductPack(sku, { ean: pack.ean, quantity: pack.quantity }, pack.ean); }
+        catch { throw refusal("io_failure", "sync"); }
+      },
+      async listStockedSkus() {
+        requireSync();
+        try { return [...new Set((await client.getStock()).flatMap(row => reference(row.sku) ? [row.sku] : []))]; }
+        catch { throw refusal("io_failure", "sync"); }
+      },
+    },
+  };
+}
+
+// buildOmnipackDispatchPayloadFromCandidate forwards only name/email/phone and
+// line1/city/postalCode/country to buildOmnipackOutboundOrderPayload; neither
+// codec reads line titles, recipient line2/deliveryInstructions/courierInstructions,
+// or pickup-point provider/name/address (readPickUpPoint reads only its id).
+// Exclude those descriptions; retain host request/order/fulfillment/parcel and
+// product/pack identities as well as all wire/evidence-bearing request values.
+// The submission retains only this SHA-256 hash in memory, never the raw values.
+function commandDigest(request: FulfillmentDispatchRequest): string {
+  return stableDispatchHash({
+    requestKey: request.requestKey, fulfillmentRef: request.fulfillmentRef,
+    orderRef: request.orderRef, orderNumber: request.orderNumber, parcelRef: request.parcelRef,
+    contactRevision: { schemaVersion: request.contactRevision.schemaVersion,
+      source: request.contactRevision.source, revision: request.contactRevision.revision },
+    recipient: { name: request.recipient.name, email: request.recipient.email, phone: request.recipient.phone,
+      line1: request.recipient.line1, city: request.recipient.city, postalCode: request.recipient.postalCode, country: request.recipient.country },
+    lines: request.lines.map(line => ({ skuRef: line.skuRef, productRef: line.productRef, packRef: line.packRef, quantity: line.quantity })),
+    selection: { providerRef: request.selection.providerRef, carrierRef: request.selection.carrierRef,
+      serviceRef: request.selection.serviceRef, deliveryKind: request.selection.deliveryKind,
+      pickupPointId: request.selection.pickupPoint?.id ?? null },
+  });
+}