@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/postgresShipmentSpine.ts

@@ -0,0 +1,338 @@
+import type { FulfillmentObservationCodecs } from "./contracts/index.js";
+import { safeDiagnosticCode } from "./dispatchProjection.js";
+import { nativeCall } from './postgresDispatchStore.js';
+import { projectObservation } from './observationProjection.js';
+import type { PgExecutor as PgQueryExecutor } from './postgresDispatchStore.js';
+interface ShipmentSpineResult { shipmentId: string; orderId: string; status: string; replayed: boolean }
+interface ShipmentRequest { idempotencyKey: string; shipmentId: string; metadata?: Record<string, unknown>; requestedAt?: string; externalRef?: string }
+interface ShipmentSpineMutationPort {
+ createShipment(input: { idempotencyKey: string; orderId: string; metadata?: Record<string, unknown>; requestedAt?: string }): Promise<ShipmentSpineResult>;
+ recordLabel(input: ShipmentRequest): Promise<ShipmentSpineResult>;
+ handOff(input: ShipmentRequest): Promise<ShipmentSpineResult>;
+ recordTracking(input: ShipmentRequest & { status: 'in_transit' | 'delivered' }): Promise<ShipmentSpineResult>;
+ cancel(input: ShipmentRequest & { reason: string }): Promise<ShipmentSpineResult>;
+ raiseException(input: ShipmentRequest & { reason: string }): Promise<ShipmentSpineResult>;
+}
+class CommerceFulfillmentConflictError extends Error {
+ constructor(message: string, readonly detail?: Record<string, unknown>) { super(message); }
+}
+class CommerceFulfillmentPersistenceError extends Error {
+ constructor(message: string, readonly detail?: Record<string, unknown>) { super(message); }
+}
+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`;
+
+export interface PostgresFulfillmentShipmentSpineOptions {
+  portKey: string;
+  approveTrackingUrl?(url: string): boolean;
+  observationCodecs?: FulfillmentObservationCodecs;
+  evidenceChannel?: "poll" | "push";
+  requiredProviderType?: "simulator";
+}
+
+/** Direct node-postgres adapter for the provider-neutral public shipment rail. */
+export function createPostgresFulfillmentShipmentSpinePort(
+  executor: PgQueryExecutor,
+  options: PostgresFulfillmentShipmentSpineOptions,
+): ShipmentSpineMutationPort & { localPersistence: ReturnType<typeof localPersistence> } {
+  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: string,
+    shipmentId: string,
+    status: string,
+    metadata: Record<string, unknown> | undefined,
+    requestedAt: string | undefined,
+  ) => call(executor, ADVANCE_SHIPMENT_SQL, [
+    idempotencyKey,
+    shipmentId,
+    status,
+    metadata ?? {},
+    requestedAt ?? null,
+  ]);
+
+  const evidence = (
+    idempotencyKey: string,
+    shipmentId: string,
+    role: "label" | "tracking",
+    externalRef: string | undefined,
+    metadata: Record<string, unknown> | undefined,
+    requestedAt: string | undefined,
+  ): Promise<ShipmentSpineResult> | null => {
+    if (!evidenceChannel || !externalRef) return null;
+    return call(executor, RECORD_EVIDENCE_SQL, [
+      idempotencyKey,
+      shipmentId,
+      evidenceChannel,
+      role,
+      externalRef,
+      metadata ?? {},
+      requestedAt ?? null,
+    ]);
+  };
+
+  return {
+    localPersistence: localPersistence(executor, options.approveTrackingUrl, options.observationCodecs),
+    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: PgQueryExecutor,
+  portKey: string,
+  values: unknown[],
+): Promise<ShipmentSpineResult> {
+  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: PgQueryExecutor,
+  sql: string,
+  values: unknown[],
+): Promise<ShipmentSpineResult> {
+  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: unknown): ShipmentSpineResult {
+  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: unknown): 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: string): string {
+  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: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+/** G17 native local persistence, composed on the same injected executor. */
+function localPersistence(executor: PgQueryExecutor, approveTrackingUrl?: (url: string) => boolean, observationCodecs?: FulfillmentObservationCodecs) {
+  return {
+    async readLocalFulfillmentState(ref: string) {
+      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 readLocalFulfillmentStatus(ref: string) {
+      const result = await executor.query('SELECT status FROM public.fulfillment_shipments WHERE id=$1::uuid', [ref]);
+      return typeof result.rows[0]?.status === 'string' ? result.rows[0].status : null;
+    },
+    async latestStatusOccurredAt(ref: string) {
+      const result = await executor.query("SELECT max((observation#>>'{fact,occurredAt}')::timestamptz) AS latest_status_occurred_at FROM public.fulfillment_observations WHERE shipment_id=$1::uuid AND status_recorded", [ref]);
+      return date(result.rows[0]?.latest_status_occurred_at);
+    },
+    async readHandedOverAt(ref: string) {
+      const result = await executor.query('SELECT handed_over_at FROM public.fulfillment_shipments WHERE id=$1::uuid', [ref]);
+      return date(result.rows[0]?.handed_over_at);
+    },
+    async recordObservation(observation: import('./contracts/index.js').FulfillmentObservation) {
+      const safe = projectObservation(observation, approveTrackingUrl, observationCodecs);
+      return nativeCall<{ replayed: boolean }>(executor,'fulfillment_record_observation',[safe.eventKey,safe.correlation.fulfillmentRef,JSON.stringify(safe),safe.firstReceivedAt]);
+    },
+    async recordStatusEvidence(ref: { fulfillmentRef: string }, observation: import('./contracts/index.js').FulfillmentObservation) {
+      return nativeCall<{ replayed: boolean }>(executor,'fulfillment_record_status_evidence',[observation.eventKey,ref.fulfillmentRef]);
+    },
+    async markProcessed(eventKey: string, outcome: { status: 'processed' | 'ignored'; refusal?: import('./contracts/index.js').FulfillmentRefusal; supersededCause?: string }) {
+      await nativeCall(executor,'fulfillment_mark_observation_processed',[eventKey,JSON.stringify({ status: outcome.status,
+        ...(outcome.supersededCause ? { supersededCause: safeDiagnosticCode(outcome.supersededCause) ?? 'fulfillment_state_conflict' } : {}),
+        ...(outcome.refusal ? { refusal: { reason: outcome.refusal.reason,phase: outcome.refusal.phase,retryable: outcome.refusal.retryable } } : {}) })]);
+    },
+  };
+}
+function date(value: unknown): string | null { return value instanceof Date ? value.toISOString() : typeof value === 'string' ? value : null; }

package/src/fulfillment/postgresStockSyncPort.ts

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import type { FulfillmentStockSyncPort, SyncCursor } from './contracts/index.js';
+import { nativeCall, type PgExecutor } from './postgresDispatchStore.js';
+
+/** The native catalogue has observed stock, not adopter inventory balances. */
+export function createPostgresFulfillmentStockSyncPort(db: PgExecutor, options: {
+  sourceKey: string;
+  inventoryClasses?: ReadonlyMap<string, 'sellable' | 'packaging' | null>;
+  readLocalInventoryStock: FulfillmentStockSyncPort['readLocalInventoryStock'];
+}): FulfillmentStockSyncPort {
+  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 as Partial<SyncCursor>;
+      return { ...cursor, status: row.status as SyncCursor['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({ syncRunId: v.syncRunId, counts: v.counts, items: v.items, alerts: v.alerts, staleSync: v.staleSync, error: v.error, continuation: { nextRef: v.continuation.nextRef, startLocalDate: v.continuation.startLocalDate, endLocalDate: v.continuation.endLocalDate }, coverageGapSkus: [...(v.coverageGapSkus ?? [])], refusal: v.refusal }),v.error?.reason ?? 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' as const : 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,
+      // Quantities, severity and run evidence are observations of the same alert identity.
+      fingerprint({ requestKey: v.requestKey, skuRef: v.skuRef, thresholdKind: v.thresholdKind }),
+      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: unknown): string | null { return value instanceof Date ? value.toISOString() : typeof value === 'string' ? value : null; }
+function fingerprint(value: unknown): string { return createHash('sha256').update(stable(value)).digest('hex'); }
+function stable(value: unknown): string {
+  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/src/fulfillment/productReconciliationEvidenceHandler.ts

@@ -0,0 +1,64 @@
+/** Read-only evidence boundary; parsing remains with the owning host schema. */
+export 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;
+  };
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: Request, res: Response): Promise<void> {
+    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: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}

package/src/fulfillment/providerCapabilities.ts

@@ -0,0 +1,18 @@
+import type { FulfillmentCapabilityDescriptor, FulfillmentRefusal, FulfillmentSelection } from "./contracts/index.js";
+
+/** Injected profiles replace the private registry. Support never activates a provider. */
+export function readFulfillmentCapabilities(
+  profiles: readonly FulfillmentCapabilityDescriptor[],
+  selection: FulfillmentSelection | null | undefined,
+): { kind: "selected"; descriptor: FulfillmentCapabilityDescriptor } | { kind: "refused"; refusal: FulfillmentRefusal } {
+  const refuse = (reason: FulfillmentRefusal["reason"]): { kind: "refused"; refusal: FulfillmentRefusal } =>
+    ({ 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/src/fulfillment/providerCommandLedger.ts

@@ -0,0 +1,53 @@
+/** 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 function createFulfillmentCommandLedger(store: LedgerStore): LedgerStore {
+  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/src/fulfillment/providerDispatchAcceptance.ts

@@ -0,0 +1,37 @@
+import type { DispatchRecord, FulfillmentDispatchResult, FulfillmentStorePort } from "./contracts/index.js";
+import { durableStrings, dispatchEvidence, dispatchResult, localFailureReason } from "./dispatchProjection.js";
+
+export function acknowledgeAcceptedDispatch(input: {
+  store: FulfillmentStorePort;
+  record: DispatchRecord & { externalRef: string };
+  keys: { providerAttemptKey: string; labelKey: string };
+}) {
+  return input.store.acknowledge({ dispatchRef: input.record.dispatchRef, acceptance: {
+    ...(input.record.acceptance ? dispatchResult(input.record.acceptance) : {}),
+    ...(input.record.status === "uncertain" ? { recovery: { source: "persisted_acceptance" as const, proof: "persisted_external_ref" as const, noProviderPost: true as const } } : {}),
+    kind: "accepted", externalRef: input.record.externalRef, evidence: dispatchEvidence(input.record.evidence), ...input.keys,
+  } });
+}
+
+export async function recoverDispatchAcceptanceWrite(input: {
+  store: FulfillmentStorePort; requestKey: string; dispatchRef: string;
+  acceptance: Extract<FulfillmentDispatchResult, { kind: "accepted" }>; error: unknown;
+}): Promise<{ committed: boolean; readBacks: number }> {
+  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 };
+  const privacy = durableStrings();
+  const cause = localFailureReason("ack", input.error, privacy);
+  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, error: {
+      code: "dispatch_acceptance_write_failed", cause, ...(privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}), status: null, retryable: false, mayHaveSucceeded: true,
+    } } });
+    readBacks += 1;
+  } catch {
+    // Submitting remains fenced; the stale sweep moves it to uncertain.
+  }
+  return { committed: committed(), readBacks };
+}

package/src/fulfillment/providerDispatchError.ts

@@ -0,0 +1,7 @@
+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 function unknownDispatchFailure(): Extract<FulfillmentDispatchResult, { kind: "unknown" }> {
+  return { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: "io_failure", phase: "dispatch", retryable: true } };
+}