@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/omnipack/client.ts

@@ -0,0 +1,270 @@
+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(options?: { refuseRedirectRetry: boolean }): 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(options) {
+      return mapOmnipackStockResponse(await requestJson(fetchImpl, config, "getStock", "/stock", { method: "GET" }, options?.refuseRedirectRetry));
+    },
+
+    async getStockMovements(params) {
+      return mapOmnipackStockMovementsResponse(await requestJson(
+        fetchImpl,
+        config,
+        "getStockMovements",
+        withQuery("/stock-movements", params),
+        { method: "GET" },
+        true,
+      ));
+    },
+
+    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,
+  refuseRedirectRetry = false,
+): Promise<unknown> {
+  const method = (init.method ?? "GET").toUpperCase();
+  const attempts = method === "GET" ? config.safeReadRetries + 1 : 1;
+  // Dispatch/readback diagnostics must not change product-sync or stock retry policy.
+  const diagnoseRedirectFailure = refuseRedirectRetry || operation === "createOrder"
+    || operation === "getFulfilments" || operation === "getFulfilmentRequests";
+  let lastError: OmnipackProviderError | null = 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: refuseRedirectRetry && response.status >= 300 && response.status < 400 ? "redirect_refused" : 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: diagnoseRedirectFailure && isRedirectRefusal(error) ? "redirect_refused" : "network_error",
+          retryable,
+          mayHaveSucceeded: submitted && mayPostHaveSucceeded(method, null),
+        });
+      if (!retryable || (refuseRedirectRetry && lastError.code === "redirect_refused")) 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;
+}
+
+// Fetch implementations expose redirect refusal as an exception, sometimes through cause.
+// Inspect it only to select a closed diagnostic; no exception text leaves this adapter.
+function isRedirectRefusal(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return /redirect/i.test(error.message) || (error.cause instanceof Error && /redirect/i.test(error.cause.message));
+}

package/src/fulfillment/omnipack/index.ts

@@ -0,0 +1,369 @@
+import { z } from "zod";
+import { publicTrackingUrl } from "../observationProjection.js";
+import type { DispatchEvidence, FulfillmentCapabilityDescriptor, FulfillmentDispatchPort, FulfillmentDispatchRequest,
+  FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentObservationPagePort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider, FulfillmentRefusal } 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 { createReconciliationPagePort, reconciliationObservation } from "./reconciliation.js";
+import { dispatchEvidence, operationError } from "../dispatchProjection.js";
+import { correlationReference, digest, eventKind, observation, reference, refusal, timestamp, type OmnipackObservationCodecs } from "./observation.js";
+export { omnipackFulfillmentCapabilities } from "./capabilities.js";
+
+// Internal error projection: retain diagnostics without exposing a provider payload or cause.
+class OmnipackSyncError extends Error implements FulfillmentRefusal {
+  readonly phase = "sync";
+  readonly retryable: boolean;
+  readonly providerFailure: boolean;
+  readonly status: number | null;
+  readonly code: string | null;
+
+  constructor(readonly reason: FulfillmentRefusal["reason"], operation: string, error?: unknown) {
+    super(reason === "io_failure" ? `OmniPack request failed: ${operation}` : `OmniPack sync refused: ${reason}`);
+    this.name = "OmnipackSyncError";
+    this.providerFailure = reason === "io_failure";
+    this.retryable = error instanceof OmnipackProviderError ? error.retryable : false;
+    this.status = error instanceof OmnipackProviderError ? error.status : null;
+    this.code = error instanceof OmnipackProviderError ? error.code : null;
+  }
+}
+function syncFailure(operation: string, error: unknown): OmnipackSyncError {
+  return error instanceof OmnipackSyncError ? error : new OmnipackSyncError("io_failure", operation, error);
+}
+function requireProductSku(sku: string): void {
+  // URL resolution collapses dot segments; encodeURIComponent rejects lone surrogates.
+  // Keep these SKUs in the listing so the worker counts a visible per-SKU failure.
+  try {
+    if (!sku.trim() || sku === "." || sku === "..") throw Error();
+    encodeURIComponent(sku);
+  } catch { throw new OmnipackSyncError("malformed", "getProduct"); }
+}
+
+/** 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;
+  observationCodecs?: OmnipackObservationCodecs;
+  /** 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;
+  reconciliation: FulfillmentObservationPagePort;
+  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 new OmnipackSyncError(capabilities.selected ? "not_ready" : "disabled", "selection");
+  };
+  const syncIdentity = () => {
+    const syncRunId = reference(config.mintSyncRunId());
+    const collectedAt = timestamp(config.clock());
+    if (!syncRunId || !collectedAt) throw new OmnipackSyncError("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 = 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,
+      transcript: { itemCount: command.providerPayload.items.length,
+        items: command.providerPayload.items.map(item => ({ skuRef: item.sku, quantity: item.quantity, lotRef: item.lotNumber ?? null, expirationDate: item.expirationDate ?? null })),
+        deliveryKind: request.selection.deliveryKind, pickupPointRef: request.selection.pickupPoint?.id ?? null } });
+    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 !== 6 || 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;
+          if (serializeOmnipackDispatchPayload(dispatchEvidence(evidence)).body !== evidenceKey) throw Error();
+          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 || serializeOmnipackDispatchPayload(command.evidence).body !== evidenceKey) 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) {
+            const detail = operationError(error instanceof OmnipackProviderError ? error : { code: "provider_dispatch_failed", status: null, retryable: true, mayHaveSucceeded: true });
+            return !detail.mayHaveSucceeded
+              ? { kind: "not_dispatched" as const, effectMayHaveSucceeded: false as const, refusal: refusal("io_failure", "dispatch", detail.retryable), error: detail }
+              : { kind: "unknown" as const, effectMayHaveSucceeded: true as const, refusal: refusal("io_failure", "dispatch", detail.retryable), error: detail };
+          } 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 original = payload as Record<string, unknown>;
+          // Validate calendar fields here only; keep compact offsets and local
+          // timestamps accepted by the base parser, without rewriting key bytes.
+          if (original.occurredAt !== undefined && original.occurredAt !== null
+            && (typeof original.occurredAt !== "string" || !timestamp(original.occurredAt)
+              || !z.iso.datetime({ offset: true, local: true }).safeParse(original.occurredAt.replace(/([+-]\d{2})(\d{2})$/u, "$1:$2")).success))
+            return { kind: "refused", refusal: refusal("malformed", "normalize"), diagnostics: { invalidTimestamp: true } };
+          const rejectedCorrelationRefs = [original.orderId, original.providerOrderId, original.orderNumber, original.fulfilmentNumber]
+            .filter(value => value !== undefined && value !== null && (typeof value !== "string" || !correlationReference(value, config.observationCodecs))).length;
+          if (rejectedCorrelationRefs)
+            return { kind: "refused", refusal: refusal("missing_correlation", "normalize"), diagnostics: { rejectedCorrelationRefs } };
+          const evidence = mapOmnipackWebhookPayload(payload, config.notification.expectedEvent, value => correlationReference(value, config.observationCodecs) !== null, {
+            service: value => correlationReference(value, config.observationCodecs) !== null,
+            url: value => publicTrackingUrl(value, config.approveTrackingUrl, config.observationCodecs?.trackingUrl) !== null,
+          });
+          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 => correlationReference(value, config.observationCodecs)))
+            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, observationCodecs: config.observationCodecs }) };
+        } 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 mapped = reconciliationObservation(matches[0]!, config, input.fulfillmentRef);
+          return mapped.kind === "unmapped" ? { kind: "unknown", refusal: refusal("unsupported_event", "readback") } : { ...mapped, externalRef: input.externalRef! };
+        } catch { return { kind: "unknown", refusal: refusal("io_failure", "readback") }; }
+      },
+    },
+    reconciliation: createReconciliationPagePort(client, config, () => !capabilities.selected || !capabilities.readiness.ready
+      ? refusal(capabilities.selected ? "not_ready" : "disabled", "readback") : null),
+    stockSync: {
+      async getStock() {
+        requireSync();
+        try {
+          const identity = syncIdentity();
+          return (await client.getStock({ refuseRedirectRetry: true })).map((row, itemIndex) => {
+            const skuRef = reference(row.sku);
+            if (!skuRef) return { kind: "rejected" as const, itemIndex, reason: "invalid_sku_ref" as const };
+            return { ...identity, skuRef, quantityKind: "snapshot" as const, totalQuantity: row.totalQuantity,
+              forSaleQuantity: row.forSaleQuantity, reservedOrUnavailableQuantity: row.reservedOrUnavailableQuantity };
+          });
+        } catch (error) { throw stockFailure(error, "get_stock"); }
+      },
+      async getStockMovements(input) {
+        requireSync();
+        try {
+          const identity = syncIdentity();
+          return (await client.getStockMovements(input)).map((row, itemIndex) => {
+            const skuRef = reference(row.sku);
+            if (!skuRef) return { kind: "rejected" as const, itemIndex, reason: "invalid_sku_ref" as const };
+            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 (error) { throw stockFailure(error, "get_stock_movements"); }
+      },
+    },
+    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 (error) { throw syncFailure("createProduct", error); }
+      },
+      async getProductPacks(sku) {
+        requireSync();
+        requireProductSku(sku);
+        try { return (await client.getProduct(sku)).packs.map(pack => ({ ean: pack.ean, quantity: pack.quantity })); }
+        catch (error) { throw syncFailure("getProduct", error); }
+      },
+      async addProductPack(sku, pack) {
+        requireSync();
+        if (!/^\d{8,14}$/u.test(pack.ean) || !Number.isSafeInteger(pack.quantity) || pack.quantity <= 0) throw new OmnipackSyncError("malformed", "sync");
+        try { await client.createProductPack(sku, { ean: pack.ean, quantity: pack.quantity }, pack.ean); }
+        catch (error) { throw syncFailure("createProductPack", error); }
+      },
+      async listStockedSkus() {
+        requireSync();
+        try { return [...new Set((await client.getStock()).flatMap(row => row.sku.trim() ? [row.sku] : []))]; }
+        catch (error) { throw syncFailure("getStock", error); }
+      },
+    },
+  };
+}
+
+// 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 },
+  });
+}
+
+/** Translate only the contributed client's typed error; never copy a message or payload. */
+function stockFailure(error: unknown, operation: "get_stock" | "get_stock_movements") {
+  const failure = syncFailure(operation === "get_stock" ? "getStock" : "getStockMovements", error);
+  if (!(error instanceof OmnipackProviderError)) return failure;
+  const retryable = error.code !== "redirect_refused" && (error.retryable || error.code === "network_error");
+  return Object.assign(failure, { retryable, providerError: {
+    operation, status: error.status, code: error.code, retryable,
+  } });
+}