@openlup/platform 0.21.0 → 0.22.0

package/dist/fulfillment/postgresShipmentSpine.js

@@ -0,0 +1,232 @@
+import { nativeCall } from './postgresDispatchStore.js';
+import { projectObservation } from './observationProjection.js';
+class CommerceFulfillmentConflictError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.detail = detail;
+    }
+}
+class CommerceFulfillmentPersistenceError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.detail = detail;
+    }
+}
+const CONTRACT_VERSION = "platform.fulfillment.shipment.v1";
+const CREATE_SHIPMENT_SQL = `
+  WITH existing_operation AS (
+    SELECT 1 AS found
+    FROM public.fulfillment_shipment_operations
+    WHERE idempotency_key = $1::text || ':operation'
+  ), configured_port AS (
+    SELECT port_key
+    FROM public.fulfillment_ports
+    WHERE port_key = $3::text
+      AND routable IS TRUE
+      AND ($6::text IS NULL OR provider_type = $6::text)
+  )
+  SELECT
+    CASE WHEN configured_port.port_key IS NULL AND existing_operation.found IS NULL THEN NULL
+      ELSE public.fulfillment_create_shipment(
+        $1::text, $2::uuid, $3::text, $4::jsonb, COALESCE($5::timestamptz, now())
+      )
+    END AS response,
+    configured_port.port_key IS NOT NULL OR existing_operation.found IS NOT NULL AS port_ready
+  FROM (SELECT (SELECT port_key FROM configured_port LIMIT 1) AS port_key) configured_port
+  CROSS JOIN (SELECT (SELECT found FROM existing_operation LIMIT 1) AS found) existing_operation`;
+const ADVANCE_SHIPMENT_SQL = `
+  SELECT public.fulfillment_advance_shipment(
+    $1::text, $2::uuid, $3::text, $4::jsonb, COALESCE($5::timestamptz, now())
+  ) AS response`;
+const RECORD_EVIDENCE_SQL = `
+  SELECT public.fulfillment_record_evidence(
+    $1::text, $2::uuid, $3::text, $4::text, $5::text, $6::jsonb,
+    COALESCE($7::timestamptz, now())
+  ) AS response`;
+const CANCEL_SHIPMENT_SQL = `
+  SELECT public.fulfillment_cancel_shipment(
+    $1::text, $2::uuid, $3::text, $4::jsonb, COALESCE($5::timestamptz, now())
+  ) AS response`;
+const RAISE_EXCEPTION_SQL = `
+  SELECT public.fulfillment_raise_shipment_exception(
+    $1::text, $2::uuid, $3::text, $4::jsonb, COALESCE($5::timestamptz, now())
+  ) AS response`;
+/** Direct node-postgres adapter for the provider-neutral public shipment rail. */
+export function createPostgresFulfillmentShipmentSpinePort(executor, options) {
+    const portKey = options.portKey.trim();
+    if (!portKey)
+        throw new Error("fulfillment_shipment_spine_port_key_required");
+    const evidenceChannel = options.evidenceChannel;
+    if (evidenceChannel !== undefined && evidenceChannel !== "poll" && evidenceChannel !== "push") {
+        throw new Error("fulfillment_shipment_spine_evidence_channel_invalid");
+    }
+    const advance = (idempotencyKey, shipmentId, status, metadata, requestedAt) => call(executor, ADVANCE_SHIPMENT_SQL, [
+        idempotencyKey,
+        shipmentId,
+        status,
+        metadata ?? {},
+        requestedAt ?? null,
+    ]);
+    const evidence = (idempotencyKey, shipmentId, role, externalRef, metadata, requestedAt) => {
+        if (!evidenceChannel || !externalRef)
+            return null;
+        return call(executor, RECORD_EVIDENCE_SQL, [
+            idempotencyKey,
+            shipmentId,
+            evidenceChannel,
+            role,
+            externalRef,
+            metadata ?? {},
+            requestedAt ?? null,
+        ]);
+    };
+    return {
+        localPersistence: localPersistence(executor),
+        createShipment(request) {
+            return callCreate(executor, portKey, [
+                request.idempotencyKey,
+                request.orderId,
+                portKey,
+                request.metadata ?? {},
+                request.requestedAt ?? null,
+                options.requiredProviderType ?? null,
+            ]);
+        },
+        async recordLabel(request) {
+            await advance(`${request.idempotencyKey}:packed`, request.shipmentId, "packed", request.metadata, request.requestedAt);
+            await advance(`${request.idempotencyKey}:label-pending`, request.shipmentId, "label_pending", request.metadata, request.requestedAt);
+            const labelled = await advance(`${request.idempotencyKey}:label-created`, request.shipmentId, "label_created", request.metadata, request.requestedAt);
+            return await evidence(`${request.idempotencyKey}:label-evidence`, request.shipmentId, "label", request.externalRef, request.metadata, request.requestedAt) ?? labelled;
+        },
+        handOff(request) {
+            return advance(request.idempotencyKey, request.shipmentId, "handed_over", request.metadata, request.requestedAt);
+        },
+        async recordTracking(request) {
+            // Evidence precedes the transition because the public rail correctly
+            // closes evidence ingestion once a shipment reaches `delivered`.
+            await evidence(`${request.idempotencyKey}:tracking-evidence`, request.shipmentId, "tracking", request.externalRef, request.metadata, request.requestedAt);
+            return advance(request.idempotencyKey, request.shipmentId, request.status, request.metadata, request.requestedAt);
+        },
+        cancel(request) {
+            return call(executor, CANCEL_SHIPMENT_SQL, [
+                request.idempotencyKey,
+                request.shipmentId,
+                request.reason,
+                request.metadata ?? {},
+                request.requestedAt ?? null,
+            ]);
+        },
+        raiseException(request) {
+            return call(executor, RAISE_EXCEPTION_SQL, [
+                request.idempotencyKey,
+                request.shipmentId,
+                request.reason,
+                request.metadata ?? {},
+                request.requestedAt ?? null,
+            ]);
+        },
+    };
+}
+async function callCreate(executor, portKey, values) {
+    try {
+        const result = await executor.query(CREATE_SHIPMENT_SQL, values);
+        const row = asRecord(result.rows[0]);
+        if (row?.port_ready !== true) {
+            throw new CommerceFulfillmentConflictError("fulfillment_port_not_ready", {
+                reason: "fulfillment_port_not_ready",
+                portKey,
+            });
+        }
+        return parseResponse(row.response);
+    }
+    catch (error) {
+        if (error instanceof CommerceFulfillmentConflictError
+            || error instanceof CommerceFulfillmentPersistenceError)
+            throw error;
+        throw mapPostgresError(error);
+    }
+}
+async function call(executor, sql, values) {
+    try {
+        const result = await executor.query(sql, values);
+        return parseResponse(asRecord(result.rows[0])?.response);
+    }
+    catch (error) {
+        if (error instanceof CommerceFulfillmentPersistenceError)
+            throw error;
+        throw mapPostgresError(error);
+    }
+}
+function parseResponse(input) {
+    const response = asRecord(input);
+    const shipment = asRecord(response?.shipment);
+    if (response?.contractVersion !== CONTRACT_VERSION
+        || typeof shipment?.id !== "string"
+        || typeof shipment.orderId !== "string"
+        || typeof shipment.status !== "string"
+        || typeof response.replayed !== "boolean") {
+        throw new CommerceFulfillmentPersistenceError("Fulfillment shipment spine response invalid");
+    }
+    return {
+        shipmentId: shipment.id,
+        orderId: shipment.orderId,
+        status: shipment.status,
+        replayed: response.replayed,
+    };
+}
+function mapPostgresError(error) {
+    const value = asRecord(error);
+    const code = typeof value?.code === "string" ? value.code : undefined;
+    const message = typeof value?.message === "string" ? value.message : "";
+    if (code === "22023" || code === "23505") {
+        return new CommerceFulfillmentConflictError("Fulfillment shipment spine conflict", {
+            code,
+            reason: classifyConflictReason(message),
+        });
+    }
+    return new CommerceFulfillmentPersistenceError("Fulfillment shipment spine persistence failed", { code });
+}
+function classifyConflictReason(message) {
+    if (message.includes("fulfillment_create_shipment_order_not_fulfillable"))
+        return "order_not_fulfillable";
+    if (message.includes("fulfillment_advance_shipment_archetype_forbids_handover"))
+        return "handover_without_label";
+    if (message.includes("fulfillment_advance_shipment_invalid_transition"))
+        return "invalid_transition";
+    if (message.includes("fulfillment_cancel_shipment_invalid_status"))
+        return "cancel_after_label";
+    if (message.includes("idempotency_conflict"))
+        return "idempotency_conflict";
+    return "fulfillment_conflict";
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** G17 native local persistence, composed on the same injected executor. */
+function localPersistence(executor) {
+    return {
+        async readLocalFulfillmentState(ref) {
+            const result = await executor.query(`SELECT shipment.status,shipment.handed_over_at,
+        (SELECT max((observation#>>'{fact,occurredAt}')::timestamptz) FROM public.fulfillment_observations WHERE shipment_id=shipment.id AND status_recorded) AS latest_status_occurred_at
+        FROM public.fulfillment_shipments shipment WHERE shipment.id=$1::uuid`, [ref]);
+            const row = result.rows[0];
+            return { status: typeof row?.status === 'string' ? row.status : null, latestStatusOccurredAt: date(row?.latest_status_occurred_at), handedOverAt: date(row?.handed_over_at) };
+        },
+        async recordObservation(observation) {
+            const safe = projectObservation(observation);
+            return nativeCall(executor, 'fulfillment_record_observation', [safe.eventKey, safe.correlation.fulfillmentRef, JSON.stringify(safe), safe.firstReceivedAt]);
+        },
+        async recordStatusEvidence(ref, observation) {
+            return nativeCall(executor, 'fulfillment_record_status_evidence', [observation.eventKey, ref.fulfillmentRef]);
+        },
+        async markProcessed(eventKey, outcome) {
+            await nativeCall(executor, 'fulfillment_mark_observation_processed', [eventKey, JSON.stringify({ status: outcome.status,
+                    ...(outcome.refusal ? { refusal: { reason: outcome.refusal.reason, phase: outcome.refusal.phase, retryable: outcome.refusal.retryable } } : {}) })]);
+        },
+    };
+}
+function date(value) { return value instanceof Date ? value.toISOString() : typeof value === 'string' ? value : null; }

package/dist/fulfillment/postgresStockSyncPort.d.ts

@@ -0,0 +1,8 @@
+import type { FulfillmentStockSyncPort } from './contracts/index.js';
+import { type PgExecutor } from './postgresDispatchStore.js';
+/** The native catalogue has observed stock, not adopter inventory balances. */
+export declare function createPostgresFulfillmentStockSyncPort(db: PgExecutor, options: {
+    sourceKey: string;
+    inventoryClasses?: ReadonlyMap<string, 'sellable' | 'packaging' | null>;
+    readLocalInventoryStock: FulfillmentStockSyncPort['readLocalInventoryStock'];
+}): FulfillmentStockSyncPort;

package/dist/fulfillment/postgresStockSyncPort.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { nativeCall } from './postgresDispatchStore.js';
+/** The native catalogue has observed stock, not adopter inventory balances. */
+export function createPostgresFulfillmentStockSyncPort(db, options) {
+    const source = options.sourceKey.trim();
+    if (!source)
+        throw new Error('fulfillment_stock_source_key_required');
+    return {
+        readLocalInventoryStock: at => options.readLocalInventoryStock(at),
+        async readCursor() {
+            const result = await db.query('SELECT status,last_stock_synced_at,last_movement_occurred_at,cursor FROM public.fulfillment_stock_sync_cursors WHERE source_key=$1', [source]);
+            const row = result.rows[0];
+            if (!row)
+                return null;
+            const cursor = row.cursor;
+            return { status: row.status, lastStockSyncedAt: timestamp(row.last_stock_synced_at), lastMovementOccurredAt: timestamp(row.last_movement_occurred_at),
+                continuation: cursor.continuation ?? { nextRef: null, startLocalDate: null, endLocalDate: null }, coverageGapSkus: cursor.coverageGapSkus ?? [], refusal: cursor.refusal ?? null };
+        },
+        async recordCursor(v) {
+            await db.query(`INSERT INTO public.fulfillment_stock_sync_cursors(source_key,status,last_stock_synced_at,last_movement_occurred_at,cursor,error_code,updated_at)
+        VALUES($1,$2,$3,$4,$5::jsonb,$6,now()) ON CONFLICT(source_key) DO UPDATE SET status=EXCLUDED.status,
+        last_stock_synced_at=EXCLUDED.last_stock_synced_at,last_movement_occurred_at=EXCLUDED.last_movement_occurred_at,cursor=EXCLUDED.cursor,error_code=EXCLUDED.error_code,updated_at=now()`, [source, v.status, v.lastStockSyncedAt, v.lastMovementOccurredAt, JSON.stringify({ continuation: { nextRef: v.continuation.nextRef, startLocalDate: v.continuation.startLocalDate, endLocalDate: v.continuation.endLocalDate }, coverageGapSkus: [...(v.coverageGapSkus ?? [])], refusal: v.refusal }), v.refusal?.reason ?? null]);
+        },
+        async readSkuInventoryClasses(skus) {
+            if (!skus.length)
+                return new Map();
+            const rows = (await db.query('SELECT sku FROM public.catalog_skus WHERE sku=ANY($1::text[])', [skus])).rows;
+            const known = new Set(rows.map(row => row.sku));
+            return new Map(skus.map(sku => [sku, options.inventoryClasses?.has(sku) ? options.inventoryClasses.get(sku) : known.has(sku) ? 'sellable' : null]));
+        },
+        async readActiveReservations(skus, at) {
+            const result = await db.query(`SELECT line.sku,sum(line.quantity)::integer AS quantity FROM public.fulfillment_inventory_reservation_lines line
+        JOIN public.fulfillment_inventory_reservations reservation ON reservation.id=line.reservation_id
+        WHERE reservation.source_key=$1 AND line.sku=ANY($2::text[]) AND reservation.status IN ('held','committed')
+        AND (reservation.status='committed' OR reservation.expires_at>$3::timestamptz) GROUP BY line.sku`, [source, skus, at]);
+            return new Map(result.rows.map(row => [String(row.sku), Number(row.quantity)]));
+        },
+        recordStockSnapshot(v) {
+            const s = v.snapshot, l = v.local;
+            return nativeCall(db, 'fulfillment_record_stock_snapshot', [source, v.requestKey, fingerprint(v), s.skuRef, s.totalQuantity, s.forSaleQuantity, s.reservedOrUnavailableQuantity, l.onHand, l.reserved, l.unavailable, l.safetyStock, v.inventoryClass, s.syncRunId]);
+        },
+        recordProviderStockCurrent(v) {
+            const s = v.snapshot;
+            return nativeCall(db, 'fulfillment_record_stock_current', [source, v.requestKey, fingerprint(v), s.skuRef, s.totalQuantity, s.forSaleQuantity, s.reservedOrUnavailableQuantity, v.inventoryClass, v.lastSyncedAt, v.staleAfter, s.syncRunId]);
+        },
+        recordMovement(v) {
+            const { providerRef, syncRunId, collectedAt, sourceRevision, revisionSource, skuRef, quantityKind, quantity, occurredAt, operationType, documentRef, lotRef, expirationDate } = v.movement;
+            const movement = { providerRef, syncRunId, collectedAt, sourceRevision, revisionSource, skuRef, quantityKind, quantity, occurredAt, operationType, documentRef, lotRef, expirationDate };
+            return nativeCall(db, 'fulfillment_record_stock_movement', [source, v.requestKey, fingerprint({ requestKey: v.requestKey, movement }), JSON.stringify(movement)]);
+        },
+        recordLowStockEvidence: v => nativeCall(db, 'fulfillment_record_stock_evidence', [source, v.requestKey, fingerprint(v), v.skuRef, v.thresholdKind, v.severity, v.providerForSaleQuantity, v.localAvailableQuantity]),
+        resolveLowStockEvidence: v => nativeCall(db, 'fulfillment_resolve_stock_evidence', [source, v.skuRef, v.activeThresholdKinds, v.syncRunId]),
+    };
+}
+function timestamp(value) { return value instanceof Date ? value.toISOString() : typeof value === 'string' ? value : null; }
+function fingerprint(value) { return createHash('sha256').update(stable(value)).digest('hex'); }
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stable(item)}`).join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}

package/dist/fulfillment/productReconciliationEvidenceHandler.d.ts

@@ -0,0 +1,36 @@
+/** Read-only evidence boundary; parsing remains with the owning host schema. */
+export declare function createProductReconciliationEvidenceHandler<Request extends {
+    method?: string;
+    query: Record<string, string | string[] | undefined>;
+}, Response, Query, Result>({ evidencePort, authorizeAdmin, requestSchema, responseSchema, respond }: {
+    evidencePort: {
+        getProductReconciliationEvidence(query: Query): Promise<unknown>;
+    };
+    authorizeAdmin(request: Request): Promise<boolean>;
+    requestSchema: {
+        safeParse(input: unknown): {
+            success: true;
+            data: Query;
+        } | {
+            success: false;
+            error: {
+                flatten(): unknown;
+            };
+        };
+    };
+    responseSchema: {
+        safeParse(input: unknown): {
+            success: true;
+            data: Result;
+        } | {
+            success: false;
+        };
+    };
+    respond: {
+        sendBffError(res: Response, code: "UPSTREAM_UNAVAILABLE" | "UNAUTHORIZED" | "BAD_REQUEST" | "INVALID_RESPONSE", message: string, options?: {
+            details: unknown;
+        }): void;
+        sendBffSuccess(res: Response, data: Result): void;
+        sendMethodNotAllowed(res: Response, methods: readonly string[]): void;
+    };
+}): (req: Request, res: Response) => Promise<void>;

package/dist/fulfillment/productReconciliationEvidenceHandler.js

@@ -0,0 +1,50 @@
+/** Read-only evidence boundary; parsing remains with the owning host schema. */
+export function createProductReconciliationEvidenceHandler({ evidencePort, authorizeAdmin, requestSchema, responseSchema, respond }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        let authorized = false;
+        try {
+            authorized = await authorizeAdmin(req);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed", {
+                details: { reason: "product_reconciliation_authorization_unavailable" },
+            });
+            return;
+        }
+        if (!authorized) {
+            sendBffError(res, "UNAUTHORIZED", "Admin session required");
+            return;
+        }
+        const request = requestSchema.safeParse({
+            statusFilter: scalarQuery(req.query.statusFilter),
+        });
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid product reconciliation request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await evidencePort.getProductReconciliationEvidence(request.data);
+            const response = responseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Product reconciliation returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Product reconciliation read failed", {
+                details: { reason: "product_reconciliation_read_unavailable" },
+            });
+        }
+    };
+}
+function scalarQuery(value) {
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/fulfillment/providerCapabilities.d.ts

@@ -0,0 +1,9 @@
+import type { FulfillmentCapabilityDescriptor, FulfillmentRefusal, FulfillmentSelection } from "./contracts/index.js";
+/** Injected profiles replace the private registry. Support never activates a provider. */
+export declare function readFulfillmentCapabilities(profiles: readonly FulfillmentCapabilityDescriptor[], selection: FulfillmentSelection | null | undefined): {
+    kind: "selected";
+    descriptor: FulfillmentCapabilityDescriptor;
+} | {
+    kind: "refused";
+    refusal: FulfillmentRefusal;
+};

package/dist/fulfillment/providerCapabilities.js

@@ -0,0 +1,17 @@
+/** Injected profiles replace the private registry. Support never activates a provider. */
+export function readFulfillmentCapabilities(profiles, selection) {
+    const refuse = (reason) => ({ kind: "refused", refusal: { reason, phase: "selection", retryable: false } });
+    const provider = selection?.providerRef?.trim().toLowerCase() || null;
+    if (!provider)
+        return refuse("selection_required");
+    const descriptor = profiles.find(profile => profile.providerRef === provider);
+    if (!descriptor)
+        return refuse("provider_mismatch");
+    if (descriptor.role === "warehouse" && (!selection?.carrierRef || !selection.serviceRef))
+        return refuse("carrier_service_required");
+    if (!descriptor.selected)
+        return refuse("disabled");
+    if (!descriptor.readiness.ready)
+        return { kind: "refused", refusal: descriptor.readiness.refusal };
+    return { kind: "selected", descriptor };
+}

package/dist/fulfillment/providerCommandLedger.d.ts

@@ -0,0 +1,143 @@
+/** Structural protocol for the contributed durable ledger. Each operation must
+ * be one atomic store transaction, including its transition evidence. P4 owns SQL.
+ * This factory holds no leases, retry counters, commands or persistence in memory.
+ */
+type CommandStatus = "queued" | "claimed" | "submitting" | "accepted" | "confirmed" | "retry_wait" | "uncertain" | "manual_review" | "terminal_rejected" | "cancelled";
+type CommandResult = {
+    commandId: string;
+    status: CommandStatus;
+    version: number;
+    applied: boolean;
+};
+type Fence = {
+    commandId: string;
+    claimToken: string;
+    claimGeneration: number;
+    expectedVersion: number;
+};
+type Proof = {
+    kind: "provider_reference" | "correlation_key" | "provider_idempotency_key";
+    fingerprint: string;
+    observedAt: string;
+    source: "provider_lookup" | "provider_webhook" | "operator_verified";
+};
+type ClaimedCommand = {
+    commandId: string;
+    fulfillmentRef: string;
+    orderRef: string;
+    providerRef: string;
+    commandKind: "dispatch_create";
+    contractVersion: "1";
+    status: "claimed";
+    version: number;
+    commandKeyFingerprint: string;
+    commandPayloadFingerprint: string;
+    providerIdempotencyKeyFingerprint: string | null;
+    routingFingerprint: string;
+    configurationFingerprint: string;
+    correlationKeyFingerprint: string;
+    retryBudget: number;
+    retryCount: number;
+    claimToken: string;
+    claimGeneration: number;
+    leaseExpiresAt: string;
+};
+type LedgerStore = {
+    enqueue(input: {
+        fulfillmentRef: string;
+        providerRef: string;
+        commandKind: "dispatch_create";
+        contractVersion: "1";
+        idempotencyKey: string;
+        commandKeyFingerprint: string;
+        commandPayloadFingerprint: string;
+        providerIdempotencyKeyFingerprint: string | null;
+        routingFingerprint: string;
+        configurationFingerprint: string;
+        correlationKeyFingerprint: string;
+        retryBudget: number;
+    }): Promise<CommandResult>;
+    claim(input: {
+        providerRef: string;
+        commandKind: "dispatch_create";
+        limit: number;
+        claimOwnerFingerprint: string;
+        leaseSeconds: number;
+    }): Promise<readonly ClaimedCommand[]>;
+    markSubmitting(input: Fence & {
+        providerAttemptRef: string | null;
+    }): Promise<CommandResult>;
+    applyWriteOutcome(input: Fence & {
+        identityFingerprint: string;
+        providerAttemptRef: string | null;
+    } & ({
+        kind: "accepted";
+        reason: "provider_accepted";
+        providerReferenceFingerprint: string;
+    } | {
+        kind: "uncertain";
+        reason: "write_uncertain";
+    } | {
+        kind: "rejected";
+        reason: "safe_rejection" | "terminal_rejection";
+        retryNotBefore: string | null;
+        proof: {
+            kind: "definitive_provider_rejection";
+            fingerprint: string;
+            observedAt: string;
+            source: "provider_response";
+        };
+    })): Promise<CommandResult>;
+    confirm(input: Fence & {
+        identityFingerprint: string;
+        providerAttemptRef: string | null;
+        proof: Proof;
+    }): Promise<CommandResult>;
+    reconcile(input: {
+        commandId: string;
+        expectedVersion: number;
+        identityFingerprint: string;
+        proof: Proof;
+    }): Promise<CommandResult & {
+        proofRecorded: boolean;
+    }>;
+    resolve(input: {
+        commandId: string;
+        expectedVersion: number;
+        identityFingerprint: string;
+    } & ({
+        decision: "manual_review";
+        reason: "effect_unknown" | "identity_mismatch" | "invalid_contract" | "unsafe_retry";
+        proof: Proof;
+    } | {
+        decision: "retry_wait";
+        reason: "authoritative_absence";
+        retryNotBefore: string;
+        proof: {
+            kind: "authoritative_absence";
+            fingerprint: string;
+            observedAt: string;
+            source: "provider_lookup";
+        };
+    })): Promise<CommandResult & {
+        proofRecorded: boolean;
+    }>;
+    release(input: Fence & ({
+        action: "release";
+        reason: "command_enqueued";
+    } | {
+        action: "cancel";
+        reason: "operator_cancelled";
+    })): Promise<CommandResult>;
+    recoverExpired(input: {
+        limit: number;
+    }): Promise<readonly CommandResult[]>;
+};
+/** Bind the durable protocol without substituting a local state machine.
+ * Store fences compare token, generation, version and unexpired lease together.
+ * Expired claimed work becomes queued; expired submitting/accepted work becomes
+ * uncertain. Only authoritative scoped absence may admit uncertain work to retry.
+ * Claim respects availability/retry budget; finalization cannot invent absence.
+ */
+export declare function createFulfillmentCommandLedger(store: LedgerStore): LedgerStore;
+export {};

package/dist/fulfillment/providerCommandLedger.js

@@ -0,0 +1,14 @@
+/** Bind the durable protocol without substituting a local state machine.
+ * Store fences compare token, generation, version and unexpired lease together.
+ * Expired claimed work becomes queued; expired submitting/accepted work becomes
+ * uncertain. Only authoritative scoped absence may admit uncertain work to retry.
+ * Claim respects availability/retry budget; finalization cannot invent absence.
+ */
+export function createFulfillmentCommandLedger(store) {
+    return {
+        enqueue: input => store.enqueue(input), claim: input => store.claim(input),
+        markSubmitting: input => store.markSubmitting(input), applyWriteOutcome: input => store.applyWriteOutcome(input),
+        confirm: input => store.confirm(input), reconcile: input => store.reconcile(input),
+        resolve: input => store.resolve(input), release: input => store.release(input), recoverExpired: input => store.recoverExpired(input),
+    };
+}

package/dist/fulfillment/providerDispatchAcceptance.d.ts

@@ -0,0 +1,26 @@
+import type { DispatchRecord, FulfillmentDispatchResult, FulfillmentStorePort } from "./contracts/index.js";
+export declare function acknowledgeAcceptedDispatch(input: {
+    store: FulfillmentStorePort;
+    record: DispatchRecord & {
+        externalRef: string;
+    };
+    keys: {
+        providerAttemptKey: string;
+        labelKey: string;
+    };
+}): Promise<{
+    acknowledged: boolean;
+    replayed: boolean;
+    record: DispatchRecord;
+}>;
+export declare function recoverDispatchAcceptanceWrite(input: {
+    store: FulfillmentStorePort;
+    requestKey: string;
+    dispatchRef: string;
+    acceptance: Extract<FulfillmentDispatchResult, {
+        kind: "accepted";
+    }>;
+}): Promise<{
+    committed: boolean;
+    readBacks: number;
+}>;

package/dist/fulfillment/providerDispatchAcceptance.js

@@ -0,0 +1,23 @@
+import { dispatchEvidence } from "./dispatchProjection.js";
+export function acknowledgeAcceptedDispatch(input) {
+    return input.store.acknowledge({ dispatchRef: input.record.dispatchRef, acceptance: {
+            kind: "accepted", externalRef: input.record.externalRef, evidence: dispatchEvidence(input.record.evidence), ...input.keys,
+        } });
+}
+export async function recoverDispatchAcceptanceWrite(input) {
+    let record = await input.store.read(input.requestKey).catch(() => null);
+    let readBacks = record ? 1 : 0;
+    const committed = () => record?.status === "created" && record.externalRef === input.acceptance.externalRef;
+    if (committed())
+        return { committed: true, readBacks };
+    try {
+        // Accepted proof survives a failed atomic ACK; finalization records uncertainty,
+        // and the next worker repairs the ACK locally without another provider call.
+        record = await input.store.finalize({ dispatchRef: input.dispatchRef, result: input.acceptance });
+        readBacks += 1;
+    }
+    catch {
+        // Submitting remains fenced; the stale sweep moves it to uncertain.
+    }
+    return { committed: committed(), readBacks };
+}

package/dist/fulfillment/providerDispatchError.d.ts

@@ -0,0 +1,6 @@
+import type { FulfillmentDispatchResult } from "./contracts/index.js";
+/** Adapters translate structured provider failures into the port result before returning.
+ * An unclassified throw after invoking dispatch can follow a successful POST. */
+export declare function unknownDispatchFailure(): Extract<FulfillmentDispatchResult, {
+    kind: "unknown";
+}>;

package/dist/fulfillment/providerDispatchError.js

@@ -0,0 +1,5 @@
+/** Adapters translate structured provider failures into the port result before returning.
+ * An unclassified throw after invoking dispatch can follow a successful POST. */
+export function unknownDispatchFailure() {
+    return { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: "io_failure", phase: "dispatch", retryable: true } };
+}