@openlup/platform 0.20.0 → 0.22.0

package/dist/fulfillment/omnipack/client.d.ts

@@ -0,0 +1,37 @@
+import { type OmnipackFulfilmentEvidence, type OmnipackFulfilmentRequestEvidence, type OmnipackOrderCreatedEvidence, type OmnipackProductCreatedEvidence, type OmnipackStockEvidence, type OmnipackStockMovementEvidence } from "./mappers.js";
+import { type OmnipackProductEvidence, type OmnipackProductPackCreatedEvidence } from "./productSyncMappers.js";
+export { OmnipackProviderError, sanitizeOmnipackProviderError, type SanitizedOmnipackProviderError, } from "./providerError.js";
+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>;
+    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 declare function createOmnipackClient(config: OmnipackClientConfig, fetchImpl: typeof fetch): OmnipackClient;

package/dist/fulfillment/omnipack/client.js

@@ -0,0 +1,162 @@
+import { mapOmnipackFulfilmentRequestsResponse, mapOmnipackFulfilmentsResponse, mapOmnipackOrderCreatedResponse, mapOmnipackProductCreatedResponse, mapOmnipackStockMovementsResponse, mapOmnipackStockResponse, sanitizeOmnipackPayload, } from "./mappers.js";
+import { mapOmnipackProductPackCreatedResponse, mapOmnipackProductResponse, } from "./productSyncMappers.js";
+import { mayPostHaveSucceeded, OmnipackProviderError } from "./providerError.js";
+export { OmnipackProviderError, sanitizeOmnipackProviderError, } from "./providerError.js";
+const PRODUCT_PACKS_SEGMENT = "packs";
+export function createOmnipackClient(config, fetchImpl) {
+    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;
+            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, config, operation, path, init) {
+    const method = (init.method ?? "GET").toUpperCase();
+    const attempts = method === "GET" ? config.safeReadRetries + 1 : 1;
+    let lastError = 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, url, config, init, onSubmit) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const credentials = await config.credentials();
+        const 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) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return sanitizeOmnipackPayload(JSON.parse(text));
+    }
+    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) {
+    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, sku) {
+    return `${productPath.replace(/\/+$/, "")}/${encodeURIComponent(sku)}`;
+}
+function withQuery(path, params) {
+    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) {
+    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) {
+    return status === 408 || status === 429 || status >= 500;
+}

package/dist/fulfillment/omnipack/index.d.ts

@@ -0,0 +1,52 @@
+import type { FulfillmentCapabilityDescriptor, FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider } from "../contracts/index.js";
+import { type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.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 declare function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdapterConfig): {
+    capabilities: FulfillmentCapabilityDescriptor;
+    dispatch: FulfillmentDispatchPort;
+    label: FulfillmentLabelPort;
+    observation: FulfillmentObservationPort;
+    readback: FulfillmentReadbackPort;
+    stockSync: FulfillmentStockSyncProvider;
+    productSync: FulfillmentProductSyncProvider;
+};

package/dist/fulfillment/omnipack/index.js

@@ -0,0 +1,349 @@
+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 } from "./omnipackWebhookPayload.js";
+import { localStatusFor, normalizeStatus } from "./omnipackStatusVocabulary.js";
+import { digest, eventKind, observation, reference, refusal, timestamp } from "./observation.js";
+export { omnipackFulfillmentCapabilities } from "./capabilities.js";
+/** No route, schedule, environment reader or default binding is installed. */
+export function createOmnipackFulfillmentAdapter(config) {
+    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 = 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();
+    const evictCompleted = () => {
+        for (const [fingerprint, submission] of submissions) {
+            if (submissions.size <= maxRetainedSubmissions)
+                break;
+            if (submission.completed)
+                submissions.delete(fingerprint);
+        }
+    };
+    const selectionFailure = (request) => {
+        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" };
+    };
+    // Shared computation: host metadata and serialized bytes live only for this call.
+    const buildCommand = async (request) => {
+        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 = { 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;
+                let fingerprint;
+                let evidenceKey;
+                let requestCommandDigest;
+                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", effectMayHaveSucceeded: false, refusal: refusal("not_dispatchable", "dispatch") };
+                    }
+                    try {
+                        const result = await client.createOrder(command.body);
+                        const externalRef = reference(result.providerOrderId);
+                        if (!externalRef)
+                            return { kind: "unknown", effectMayHaveSucceeded: true, 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", externalRef, evidence: structuredClone(command.evidence),
+                            providerAttemptKey: `attempt:${proof}`, labelKey: `label:${proof}` };
+                    }
+                    catch (error) {
+                        return error instanceof OmnipackProviderError && !error.mayHaveSucceeded
+                            ? { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal("io_failure", "dispatch") }
+                            : { kind: "unknown", effectMayHaveSucceeded: true, 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 = 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);
+                    const event = { provider_received: "shipment.accepted", picking: "order.processing_started", packed: "order.picked", in_transit: "order.shipped", delivered: "order.delivered", exception: "parcel.exception" }[status];
+                    const evidence = { provider: "omnipack", 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", 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", 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) {
+    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 },
+    });
+}