@openlup/platform 0.20.0 → 0.22.0

package/src/fulfillment/paidFulfillmentRecovery.ts

@@ -0,0 +1,252 @@
+const COMMERCE_ORDER_PAID_EVENT_TYPE = "commerce.order.paid";
+
+type PaidFulfillmentRecoveryAction =
+  | "wait_for_outbox" | "requeue_discarded_order_paid_outbox" | "inspect_processed_without_effect"
+  | "inspect_missing_order_paid_outbox"
+  | "monitor_dispatch" | "inspect_missing_dispatch_ref" | "inspect_stale_dispatch_submission"
+  | "inspect_uncertain_dispatch" | "inspect_failed_dispatch"
+  | "inspect_created_dispatch_without_provider_order_id" | "inspect_terminal_dispatch"
+  | "inspect_unknown_dispatch_status";
+
+type PaidFulfillmentRecoveryReason =
+  | "paid_order_without_fulfillment_order" | "order_paid_outbox_missing" | "order_paid_outbox_discarded"
+  | "order_paid_outbox_processed_without_fulfillment" | "provider_dispatch_in_progress"
+  | "provider_fulfillment_without_dispatch_ref" | "provider_dispatch_submission_stale"
+  | "provider_dispatch_outcome_uncertain" | "provider_dispatch_failed"
+  | "provider_dispatch_created_without_provider_order_id"
+  | "provider_dispatch_terminal_without_progress" | "provider_dispatch_status_unknown";
+
+type PaidFulfillmentRecoveryPosture =
+  | "automatic_local_requeue_safe" | "wait_for_existing_automation" | "operator_review_required";
+
+type PaidFulfillmentOrderRow = Record<string, unknown> & {
+  id: string; status?: string | null; mode?: string | null;
+  created_at?: string | null; updated_at?: string | null;
+};
+
+type PaidFulfillmentOrderEvidenceRow = Record<string, unknown> & {
+  id: string; order_id: string; provider_kind?: string | null; status?: string | null;
+  created_at?: string | null; updated_at?: string | null;
+};
+
+type PaidFulfillmentDispatchRefRow = Record<string, unknown> & {
+  id?: string | null; fulfillment_order_id: string; provider_order_id?: string | null;
+  status?: string | null; created_at?: string | null; updated_at?: string | null;
+};
+
+type PaidFulfillmentOutboxEventRow = Record<string, unknown> & {
+  id: string; event_type: string; status: string; aggregate_id?: string | null;
+  created_at?: string | null; updated_at?: string | null; available_at?: string | null;
+  attempts?: number | null;
+};
+
+type PaidFulfillmentRecoveryCandidate = {
+  orderId: string; orderStatus: string; orderMode: string | null;
+  fulfillmentOrderId: string | null; providerKind: string | null;
+  dispatchRefId: string | null; dispatchStatus: string | null;
+  outboxEventId: string | null; outboxStatus: string | null; outboxAttempts: number | null;
+  reason: PaidFulfillmentRecoveryReason;
+  recommendedAction: PaidFulfillmentRecoveryAction;
+  recoveryPosture: PaidFulfillmentRecoveryPosture;
+  ageSeconds: number;
+};
+
+type PaidFulfillmentRecoveryPlan = { checkedOrders: number; candidates: PaidFulfillmentRecoveryCandidate[] };
+
+export function collectPaidFulfillmentRecoveryCandidates(input: {
+  providerRef: string;
+  orders: PaidFulfillmentOrderRow[];
+  fulfillmentOrders: PaidFulfillmentOrderEvidenceRow[];
+  dispatchRefs?: PaidFulfillmentDispatchRefRow[];
+  orderPaidOutboxEvents: PaidFulfillmentOutboxEventRow[];
+  now: Date;
+  minimumAgeSeconds?: number;
+  dispatchSubmissionStaleSeconds?: number;
+}): PaidFulfillmentRecoveryPlan {
+  const minimumAgeSeconds = input.minimumAgeSeconds ?? 30 * 60;
+  const minimumAgeMs = minimumAgeSeconds * 1000;
+  const dispatchSubmissionStaleSeconds = input.dispatchSubmissionStaleSeconds ?? 5 * 60;
+  const fulfillmentByOrder = groupBy(input.fulfillmentOrders, (row) => row.order_id);
+  const dispatchRefsByFulfillment = groupBy(
+    input.dispatchRefs ?? [],
+    (row) => row.fulfillment_order_id,
+  );
+  const outboxByOrder = latestBy(
+    input.orderPaidOutboxEvents.filter((row) => row.event_type === COMMERCE_ORDER_PAID_EVENT_TYPE),
+    (row) => row.aggregate_id ?? "",
+  );
+  const candidates: PaidFulfillmentRecoveryCandidate[] = [];
+  let checkedOrders = 0;
+
+  for (const order of input.orders) {
+    const status = clean(order.status);
+    if (!["paid", "fulfillment_pending"].includes(status)) continue;
+    const ageSeconds = secondsSince(order.updated_at ?? order.created_at ?? "", input.now);
+    if (ageSeconds * 1000 < minimumAgeMs) continue;
+    checkedOrders += 1;
+
+    const outbox = outboxByOrder.get(order.id);
+    const fulfillments = fulfillmentByOrder.get(order.id) ?? [];
+    if (fulfillments.length === 0) {
+      candidates.push(candidateForMissingFulfillment(order, outbox, ageSeconds));
+      continue;
+    }
+
+    for (const fulfillment of fulfillments) {
+      const providerKind = clean(fulfillment.provider_kind);
+      if (providerKind !== input.providerRef) continue;
+      const latestDispatchRef = latestBy(
+        dispatchRefsByFulfillment.get(fulfillment.id) ?? [],
+        (row) => row.fulfillment_order_id,
+      ).get(fulfillment.id);
+      const decision = dispatchRecoveryDecision({
+        dispatchRef: latestDispatchRef,
+        fulfillmentCreatedAt: fulfillment.updated_at ?? fulfillment.created_at,
+        now: input.now,
+        missingRefGraceSeconds: minimumAgeSeconds,
+        staleSeconds: dispatchSubmissionStaleSeconds,
+      });
+      if (!decision) continue;
+      candidates.push({
+        ...baseCandidate(order, outbox, ageSeconds),
+        fulfillmentOrderId: fulfillment.id,
+        providerKind: input.providerRef,
+        dispatchRefId: latestDispatchRef?.id ?? null,
+        dispatchStatus: clean(latestDispatchRef?.status) || null,
+        ...decision,
+      });
+    }
+  }
+
+  candidates.sort((a, b) => b.ageSeconds - a.ageSeconds || a.orderId.localeCompare(b.orderId));
+  return { checkedOrders, candidates };
+}
+
+function candidateForMissingFulfillment(
+  order: PaidFulfillmentOrderRow,
+  outbox: PaidFulfillmentOutboxEventRow | undefined,
+  ageSeconds: number,
+): PaidFulfillmentRecoveryCandidate {
+  const outboxStatus = clean(outbox?.status);
+  const decision = !outbox
+    ? recoveryDecision("order_paid_outbox_missing", "inspect_missing_order_paid_outbox")
+    : outboxStatus === "discarded"
+      ? recoveryDecision("order_paid_outbox_discarded", "requeue_discarded_order_paid_outbox", "automatic_local_requeue_safe")
+      : outboxStatus === "processed"
+        ? recoveryDecision("order_paid_outbox_processed_without_fulfillment", "inspect_processed_without_effect")
+        : recoveryDecision("paid_order_without_fulfillment_order", "wait_for_outbox", "wait_for_existing_automation");
+  return { ...baseCandidate(order, outbox, ageSeconds), ...decision };
+}
+
+function baseCandidate(
+  order: PaidFulfillmentOrderRow,
+  outbox: PaidFulfillmentOutboxEventRow | undefined,
+  ageSeconds: number,
+): Omit<PaidFulfillmentRecoveryCandidate, "reason" | "recommendedAction" | "recoveryPosture"> {
+  return {
+    orderId: order.id,
+    orderStatus: clean(order.status),
+    orderMode: clean(order.mode) || null,
+    fulfillmentOrderId: null,
+    providerKind: null,
+    dispatchRefId: null,
+    dispatchStatus: null,
+    outboxEventId: outbox?.id ?? null,
+    outboxStatus: clean(outbox?.status) || null,
+    outboxAttempts: typeof outbox?.attempts === "number" ? outbox.attempts : null,
+    ageSeconds,
+  };
+}
+
+function dispatchRecoveryDecision(input: {
+  dispatchRef: PaidFulfillmentDispatchRefRow | undefined;
+  fulfillmentCreatedAt: string | null | undefined;
+  now: Date;
+  missingRefGraceSeconds: number;
+  staleSeconds: number;
+}): Pick<PaidFulfillmentRecoveryCandidate, "reason" | "recommendedAction" | "recoveryPosture"> | null {
+  const { dispatchRef, now, staleSeconds } = input;
+  if (!dispatchRef) {
+    if (!isAtLeastAgeOrUnknown(input.fulfillmentCreatedAt, now, input.missingRefGraceSeconds)) return null;
+    return recoveryDecision("provider_fulfillment_without_dispatch_ref", "inspect_missing_dispatch_ref");
+  }
+  const status = clean(dispatchRef.status);
+  if (status === "draft") {
+    return recoveryDecision("provider_dispatch_in_progress", "monitor_dispatch", "wait_for_existing_automation");
+  }
+  if (status === "submitting") {
+    return isAtLeastAgeOrUnknown(dispatchRef.updated_at ?? dispatchRef.created_at, now, staleSeconds)
+      ? recoveryDecision("provider_dispatch_submission_stale", "inspect_stale_dispatch_submission")
+      : recoveryDecision("provider_dispatch_in_progress", "monitor_dispatch", "wait_for_existing_automation");
+  }
+  if (status === "uncertain") {
+    return recoveryDecision("provider_dispatch_outcome_uncertain", "inspect_uncertain_dispatch");
+  }
+  if (status === "failed") {
+    return recoveryDecision("provider_dispatch_failed", "inspect_failed_dispatch");
+  }
+  if (status === "created") {
+    return dispatchRef.provider_order_id?.trim()
+      ? null
+      : recoveryDecision(
+        "provider_dispatch_created_without_provider_order_id",
+        "inspect_created_dispatch_without_provider_order_id",
+      );
+  }
+  if (["cancel_requested", "cancelled"].includes(status)) {
+    return recoveryDecision("provider_dispatch_terminal_without_progress", "inspect_terminal_dispatch");
+  }
+  return recoveryDecision("provider_dispatch_status_unknown", "inspect_unknown_dispatch_status");
+}
+
+function recoveryDecision(
+  reason: PaidFulfillmentRecoveryReason,
+  recommendedAction: PaidFulfillmentRecoveryAction,
+  recoveryPosture: PaidFulfillmentRecoveryPosture = "operator_review_required",
+) {
+  return { reason, recommendedAction, recoveryPosture };
+}
+
+function latestBy<T extends { created_at?: string | null; updated_at?: string | null }>(
+  rows: T[],
+  key: (row: T) => string,
+): Map<string, T> {
+  const result = new Map<string, T>();
+  for (const row of rows) {
+    const rowKey = key(row);
+    if (!rowKey) continue;
+    const current = result.get(rowKey);
+    if (!current || timestamp(row.updated_at ?? row.created_at) >= timestamp(current.updated_at ?? current.created_at)) {
+      result.set(rowKey, row);
+    }
+  }
+  return result;
+}
+
+function groupBy<T>(rows: T[], key: (row: T) => string): Map<string, T[]> {
+  const groups = new Map<string, T[]>();
+  for (const row of rows) {
+    const rowKey = key(row);
+    const group = groups.get(rowKey);
+    if (group) group.push(row);
+    else groups.set(rowKey, [row]);
+  }
+  return groups;
+}
+
+function clean(value: string | null | undefined): string {
+  return value?.trim().toLowerCase() ?? "";
+}
+function timestamp(value: string | null | undefined): number {
+  const parsed = value ? Date.parse(value) : 0;
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function secondsSince(value: string, now: Date): number {
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) return 0;
+  return Math.max(0, Math.floor((now.getTime() - parsed) / 1000));
+}
+function isAtLeastAgeOrUnknown(value: string | null | undefined, now: Date, seconds: number): boolean {
+  const parsed = timestamp(value);
+  return parsed <= 0 || now.getTime() - parsed > seconds * 1000;
+}

package/src/fulfillment/paidHandoff.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerOutcome,
+} from "@openlup/core/outbox";
+import type { OrderPaidFulfillmentPort } from "./paidHandoffPorts.js";
+
+const COMMERCE_ORDER_PAID_EVENT_TYPE = "commerce.order.paid";
+const HANDLER_TIMEOUT_MS = 15_000;
+
+const outboxOrderPaidFulfillmentDescriptor = Object.freeze({
+  eventType: COMMERCE_ORDER_PAID_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+
+// Risk seam (optional): assess a paid order BEFORE fulfillment. Declared here so
+// this handler stays independent of the host's risk implementation, which can
+// supply a structurally compatible port.
+interface OrderPaidRiskAssessmentPort {
+  assessPaidOrder(input: {
+    orderUuid: string;
+    outboxEventId: string;
+    signal: AbortSignal;
+  }): Promise<
+    | { kind: "allow"; detail?: Record<string, unknown> }
+    | { kind: "review" | "block"; detail?: Record<string, unknown> }
+    | { kind: "retryable"; reason: string }
+    | { kind: "fatal"; reason: string }
+  >;
+}
+
+// Frozen minimal parse: validate only the orderUuid forwarded to the fulfillment
+// port. This handler owns the subset schema so a producer-side payload change
+// does not send otherwise valid in-flight events to the dead-letter queue.
+const payloadSubsetSchema = z
+  .object({
+    orderUuid: z.guid(),
+  })
+  .passthrough();
+
+export function createOutboxOrderPaidFulfillmentHandler(deps: {
+  fulfillmentPort: OrderPaidFulfillmentPort;
+  // Optional risk seam. When set AND enabled, a paid order is risk-assessed
+  // before fulfillment; a review/block holds the order (no dispatch).
+  riskPort?: OrderPaidRiskAssessmentPort;
+  isRiskEnabled?: () => boolean;
+}): OutboxHandler<AbortSignal> {
+  return {
+    ...outboxOrderPaidFulfillmentDescriptor,
+    async handle(row: OutboxEventRow, signal: AbortSignal): Promise<OutboxHandlerOutcome> {
+      const parsed = parseOutboxPayload(payloadSubsetSchema, row.payload);
+      if (parsed.ok === false) {
+        return parsed.outcome;
+      }
+
+      // Risk gate (flag-OFF by default): assess the paid order before any
+      // fulfillment work. review/block → hold (ack without dispatch, the case is
+      // persisted for manual review); retryable/fatal map to the worker ladder.
+      if (deps.riskPort && deps.isRiskEnabled?.()) {
+        const risk = await deps.riskPort.assessPaidOrder({
+          orderUuid: parsed.data.orderUuid,
+          outboxEventId: row.id,
+          signal,
+        });
+        switch (risk.kind) {
+          case "allow":
+            break;
+          case "review":
+          case "block":
+            return {
+              kind: "processed",
+              detail: { skipped: "risk_review_hold", risk: risk.detail ?? {} },
+            };
+          case "retryable":
+            return { kind: "retry", reason: truncateReason(risk.reason) };
+          case "fatal":
+            return { kind: "discard", reason: truncateReason(risk.reason) };
+        }
+      }
+
+      const result = await deps.fulfillmentPort.ensureFulfilledFromPaidOrder({
+        orderUuid: parsed.data.orderUuid,
+        outboxEventId: row.id,
+        signal,
+      });
+
+      switch (result.kind) {
+        case "completed":
+        case "skipped":
+          return { kind: "processed", detail: result.detail };
+        case "manual_review":
+          // Terminal but NOT a silent discard: the port already placed the
+          // durable observable signal (an active fulfillment_exception hold).
+          // Settle the event as processed so it is not parked in the discard/
+          // error queue, and record why in the outbox metadata.
+          return {
+            kind: "processed",
+            detail: {
+              ...result.detail,
+              outcome: "manual_review",
+              reason: truncateReason(result.reason),
+            },
+          };
+        case "retryable":
+          return { kind: "retry", reason: truncateReason(result.reason) };
+        case "snooze":
+          return { kind: "snooze", reason: truncateReason(result.reason) };
+        case "fatal":
+          return { kind: "discard", reason: truncateReason(result.reason) };
+      }
+    },
+  };
+}
+
+function truncateReason(value: string): string { return value.length <= 300 ? value : `${value.slice(0, 300)}…`; }
+function parseOutboxPayload<T>(schema: import("zod").ZodType<T>, payload: unknown):
+  { ok: true; data: T } | { ok: false; outcome: OutboxHandlerOutcome } {
+  const parsed = schema.safeParse(payload);
+  if (parsed.success) return { ok: true, data: parsed.data };
+  const detail = parsed.error.issues.map(issue => `${issue.path.join(".") || "payload"}: ${issue.message}`).join("; ");
+  return { ok: false, outcome: { kind: "discard", reason: `contract_parse_failed: ${truncateReason(detail)}` } };
+}

package/src/fulfillment/paidHandoffPorts.ts

@@ -0,0 +1,21 @@
+// Neutral port owned by the commerce.order.paid dispatch handler. Concrete
+// persistence and provider adapters belong to the host composition.
+
+export type OrderPaidFulfillmentResult =
+  | { kind: "completed" | "skipped"; detail?: Record<string, unknown> }
+  | { kind: "retryable"; reason: string }
+  | { kind: "snooze"; reason: string }
+  | { kind: "fatal"; reason: string }
+  // Paid order that cannot be auto-fulfilled and was routed to an observable
+  // manual-review state (an active fulfillment_exception hold). Terminal but
+  // NOT a silent discard: the hold is the durable signal. No fulfillment order
+  // or label is created for this outcome.
+  | { kind: "manual_review"; reason: string; detail?: Record<string, unknown> };
+
+export interface OrderPaidFulfillmentPort {
+  ensureFulfilledFromPaidOrder(input: {
+    orderUuid: string;
+    outboxEventId: string;
+    signal: AbortSignal;
+  }): Promise<OrderPaidFulfillmentResult>;
+}

package/src/fulfillment/postgresDeliveryAlignment.ts

@@ -0,0 +1,14 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import { nativeCall, type PgExecutor } from './postgresDispatchStore.js';
+import { readDeliveryAlignment } from './deliveryAlignmentReadModel.js';
+
+/** Trusted arrival ingestion only. Operator replacement attestation has no caller here. */
+export function createPostgresDeliveryAlignmentPort(db: PgExecutor): DeliveryAlignmentPort {
+  return {
+    read: ref => readDeliveryAlignment(db, ref),
+    async recordArrival(v) {
+      const receipt = await nativeCall<{ replayed: boolean }>(db, 'fulfillment_record_alignment_arrival', [v.requestKey, v.parcelRef, v.deliveredAt, v.evidenceRef]);
+      return { ...await readDeliveryAlignment(db, v.parcelRef), replayed: receipt.replayed };
+    },
+  };
+}

package/src/fulfillment/postgresDispatchStore.ts

@@ -0,0 +1,55 @@
+import type { DispatchRecord, FulfillmentDispatchRequest, FulfillmentStorePort } from './contracts/index.js';
+import { dispatchEvidence, dispatchResult } from './dispatchProjection.js';
+import type { createFulfillmentCommandLedger } from './providerCommandLedger.js';
+
+/** Caller supplies a driver and its selected host preparation/data boundary. */
+export interface PgExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+export async function nativeCall<T>(db: PgExecutor, name: string, values: unknown[]): Promise<T> {
+  const result = await db.query(`SELECT public.${name}(${values.map((_, index) => `$${index + 1}`).join(',')}) AS response`, values);
+  if (!result.rows[0] || result.rows[0].response === undefined) throw new Error('fulfillment_native_response_missing');
+  return result.rows[0].response as T;
+}
+
+export function createPostgresFulfillmentDispatchStore(db: PgExecutor, host: {
+  /** Synchronize authoritative withholding/contact revision on prepare and every source edit. */
+  prepare(fulfillmentRef: string): ReturnType<FulfillmentStorePort['prepare']>;
+  readCandidate(fulfillmentRef: string): Promise<FulfillmentDispatchRequest | null>;
+}): FulfillmentStorePort & { commandLedger: ReturnType<typeof createFulfillmentCommandLedger> } {
+  return {
+    readCandidate: ref => host.readCandidate(ref),
+    prepare: ref => host.prepare(ref),
+    async read(key) {
+      const result = await db.query('SELECT public.fulfillment_dispatch_read(ref) AS response FROM public.fulfillment_dispatch_refs ref WHERE request_key=$1', [key]);
+      return result.rows[0]?.response as DispatchRecord | undefined ?? null;
+    },
+    claim: input => nativeCall(db, 'fulfillment_dispatch_claim', [input.requestKey, input.fulfillmentRef, input.orderRef, input.parcelRef, input.mode, JSON.stringify(dispatchEvidence(input.evidence))]),
+    recordProviderAttempt: (key, ref, evidence, mode) => nativeCall(db, 'fulfillment_record_provider_attempt', [key, ref, JSON.stringify(dispatchEvidence(evidence)), mode]),
+    begin: input => nativeCall(db, 'fulfillment_dispatch_begin', [input.dispatchRef, input.commandFingerprint]),
+    finalize: input => nativeCall(db, 'fulfillment_dispatch_finish', [input.dispatchRef, JSON.stringify(dispatchResult(input.result)), false]),
+    acknowledge: input => nativeCall(db, 'fulfillment_dispatch_finish', [input.dispatchRef, JSON.stringify(dispatchResult(input.acceptance)), true]),
+    async markStaleSubmissionsUncertain(staleBefore) {
+      const result = await db.query("UPDATE public.fulfillment_dispatch_refs SET status='uncertain',updated_at=now() WHERE status='submitting' AND updated_at<$1 RETURNING id", [staleBefore]);
+      return result.rows.length;
+    },
+    commandLedger: commandLedger(db),
+  };
+}
+function commandLedger(db: PgExecutor): ReturnType<typeof createFulfillmentCommandLedger> {
+  const fence = (v: { commandId: string; claimToken: string; claimGeneration: number; expectedVersion: number }) => [v.commandId, v.claimToken, v.claimGeneration, v.expectedVersion];
+  return {
+    enqueue: v => nativeCall(db, 'commerce_fulfillment_enqueue_provider_command', [v.fulfillmentRef, v.providerRef, v.commandKind, v.contractVersion, v.idempotencyKey, v.commandKeyFingerprint, v.commandPayloadFingerprint, v.providerIdempotencyKeyFingerprint, v.routingFingerprint, v.configurationFingerprint, v.correlationKeyFingerprint, v.retryBudget]),
+    async claim(v) {
+      const result = await db.query('SELECT public.commerce_fulfillment_claim_provider_commands($1,$2,$3,$4,$5) AS response', [v.providerRef, v.commandKind, v.limit, v.claimOwnerFingerprint, v.leaseSeconds]);
+      return result.rows.map(row => row.response) as Awaited<ReturnType<ReturnType<typeof createFulfillmentCommandLedger>['claim']>>;
+    },
+    markSubmitting: v => nativeCall(db, 'commerce_fulfillment_mark_command_submitting', [...fence(v), v.providerAttemptRef]),
+    applyWriteOutcome: v => nativeCall(db, 'commerce_fulfillment_apply_command_write_outcome', [...fence(v), v.identityFingerprint, v.kind, v.reason, v.kind === 'rejected' ? v.retryNotBefore : null, v.kind === 'accepted' ? v.providerReferenceFingerprint : null, v.providerAttemptRef, v.kind === 'rejected' ? v.proof.kind : null, v.kind === 'rejected' ? v.proof.fingerprint : null, v.kind === 'rejected' ? v.proof.observedAt : null, v.kind === 'rejected' ? v.proof.source : null]),
+    confirm: v => nativeCall(db, 'commerce_fulfillment_confirm_provider_command', [...fence(v), v.identityFingerprint, v.providerAttemptRef, v.proof.kind, v.proof.fingerprint, v.proof.observedAt, v.proof.source]),
+    reconcile: v => nativeCall(db, 'commerce_fulfillment_reconcile_provider_command', [v.commandId, v.expectedVersion, v.identityFingerprint, v.proof.kind, v.proof.fingerprint, v.proof.observedAt, v.proof.source]),
+    resolve: v => nativeCall(db, 'commerce_fulfillment_resolve_uncertain_command', [v.commandId, v.expectedVersion, v.identityFingerprint, v.decision, v.reason, v.proof.kind, v.proof.fingerprint, v.proof.observedAt, v.proof.source, v.decision === 'retry_wait' ? v.retryNotBefore : null]),
+    release: v => nativeCall(db, 'commerce_fulfillment_release_or_cancel_command', [...fence(v), v.action, v.reason]),
+    recoverExpired: v => nativeCall(db, 'commerce_fulfillment_recover_expired_provider_commands', [v.limit]),
+  };
+}

package/src/fulfillment/postgresEvidenceReadPort.ts

@@ -0,0 +1,59 @@
+import type { PgExecutor as PgQueryExecutor } from './postgresDispatchStore.js';
+interface AdminLowStockEvidenceItem {
+ id: string; sku: string; thresholdKind: string; severity: string; status: string;
+ providerForSaleQuantity: number | null; localAvailableQuantity: number | null;
+ forecastDays: null; firstSeenAt: string | null; lastSeenAt: string | null; resolvedAt: string | null;
+}
+interface FulfillmentLowStockEvidencePort {
+ getLowStockEvidence(input: { statusFilter: 'all' | 'open' | 'resolved' }): Promise<{ statusFilter: string; openCount: number; items: AdminLowStockEvidenceItem[] }>;
+}
+const READ = `SELECT id, sku, threshold_kind, severity, status,
+    provider_for_sale_quantity, local_available_quantity,
+    first_seen_at, last_seen_at, resolved_at
+  FROM public.fulfillment_stock_evidence
+  WHERE source_key = $1::text AND ($2::text = 'all' OR status = $2::text)
+  ORDER BY last_seen_at DESC, id ASC`;
+const COUNT = `SELECT count(*)::integer AS count
+  FROM public.fulfillment_stock_evidence
+  WHERE source_key = $1::text AND status = 'open'`;
+
+export function createPostgresFulfillmentLowStockEvidencePort(
+  executor: PgQueryExecutor,
+  sourceKey: string,
+): FulfillmentLowStockEvidencePort {
+  const key = sourceKey.trim();
+  if (!key) throw new Error("fulfillment_stock_source_key_required");
+  return { async getLowStockEvidence({ statusFilter }) {
+    const [rows, count] = await Promise.all([
+      executor.query(READ, [key, statusFilter]),
+      executor.query(COUNT, [key]),
+    ]);
+    return {
+      statusFilter,
+      openCount: integer(count.rows[0]?.count),
+      items: rows.rows.map(mapItem),
+    };
+  } };
+}
+
+function mapItem(row: Record<string, unknown>): AdminLowStockEvidenceItem {
+  return {
+    id: String(row.id),
+    sku: String(row.sku),
+    thresholdKind: row.threshold_kind as AdminLowStockEvidenceItem["thresholdKind"],
+    severity: row.severity as AdminLowStockEvidenceItem["severity"],
+    status: row.status as AdminLowStockEvidenceItem["status"],
+    providerForSaleQuantity: nullableInteger(row.provider_for_sale_quantity),
+    localAvailableQuantity: nullableInteger(row.local_available_quantity),
+    forecastDays: null,
+    firstSeenAt: nullableText(row.first_seen_at),
+    lastSeenAt: nullableText(row.last_seen_at),
+    resolvedAt: nullableText(row.resolved_at),
+  };
+}
+
+function integer(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+function nullableInteger(value: unknown): number | null { return value === null ? null : integer(value); }
+function nullableText(value: unknown): string | null { return value instanceof Date ? value.toISOString() : typeof value === "string" && value ? value : null; }

package/src/fulfillment/postgresPaidFulfillmentRecovery.ts

@@ -0,0 +1,29 @@
+import type { collectPaidFulfillmentRecoveryCandidates } from './paidFulfillmentRecovery.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+type RecoveryInput = Parameters<typeof collectPaidFulfillmentRecoveryCandidates>[0];
+
+/** Read the selected native port's local obligations; never infer external absence. */
+export function createPostgresPaidFulfillmentRecoveryOpsPort(db: PgExecutor, selection: { portKey: string; providerRef: string }) {
+  return {
+    async readRecoveryInputs(input: { minimumAgeSeconds: number; limit: number; now: Date; orderIds?: string[] }): Promise<Pick<RecoveryInput,'orders' | 'fulfillmentOrders' | 'dispatchRefs' | 'orderPaidOutboxEvents'>> {
+      const ids=[...new Set(input.orderIds ?? [])];
+      const orders=(await db.query(`SELECT id,status,metadata->>'mode' AS mode,created_at::text,updated_at::text FROM public.commerce_orders
+        WHERE status=ANY($1::text[]) AND updated_at<=$2 AND ($4::uuid[]='{}'::uuid[] OR id=ANY($4::uuid[])) ORDER BY updated_at ASC LIMIT $3`,
+      [['paid','fulfillment_pending'],new Date(input.now.getTime()-input.minimumAgeSeconds*1000),input.limit,ids])).rows as RecoveryInput['orders'];
+      const orderIds=orders.map(row => row.id);
+      if (!orderIds.length) return {orders:[],fulfillmentOrders:[],dispatchRefs:[],orderPaidOutboxEvents:[]};
+      const [shipments,refs,events]=await Promise.all([
+        db.query('SELECT id,order_id,$3::text AS provider_kind,status,created_at::text,updated_at::text FROM public.fulfillment_shipments WHERE order_id=ANY($1::uuid[]) AND port_key=$2 ORDER BY created_at DESC',[orderIds,selection.portKey,selection.providerRef]),
+        db.query('SELECT ref.id,ref.shipment_id AS fulfillment_order_id,ref.external_ref AS provider_order_id,ref.status,ref.updated_at::text FROM public.fulfillment_dispatch_refs ref JOIN public.fulfillment_shipments shipment ON shipment.id=ref.shipment_id WHERE ref.order_id=ANY($1::uuid[]) AND shipment.port_key=$2',[orderIds,selection.portKey]),
+        db.query("SELECT id,event_type,status,aggregate_id,created_at::text,available_at::text,attempts,metadata->>'updatedAt' AS updated_at FROM public.outbox_events WHERE event_type=$1 AND aggregate_id=ANY($2::uuid[]) ORDER BY created_at DESC",['commerce.order.paid',orderIds]),
+      ]);
+      return {orders,fulfillmentOrders:shipments.rows as RecoveryInput['fulfillmentOrders'],dispatchRefs:refs.rows as RecoveryInput['dispatchRefs'],orderPaidOutboxEvents:events.rows as RecoveryInput['orderPaidOutboxEvents']};
+    },
+    async requeueDiscardedOrderPaidOutboxEvents(input: { eventIds: string[]; limit?: number; requeuedBy: string; reason: string }) {
+      const ids=[...new Set(input.eventIds.filter(Boolean))];
+      if (!ids.length) return {requeuedCount:0,eventIds:[]};
+      const result=await db.query('SELECT id FROM public.outbox_requeue_discarded(p_event_ids=>$1::uuid[],p_event_type=>$2,p_limit=>$3,p_requeued_by=>$4,p_reason=>$5)',[ids,'commerce.order.paid',input.limit ?? ids.length,input.requeuedBy,input.reason]);
+      return {requeuedCount:result.rows.length,eventIds:result.rows.map(row => String(row.id))};
+    },
+  };
+}

package/src/fulfillment/postgresPaidHandoffStore.ts

@@ -0,0 +1,11 @@
+import type { FulfillmentPaidHandoffPort } from './contracts/index.js';
+import { nativeCall, type PgExecutor } from './postgresDispatchStore.js';
+
+/** Select an existing native port explicitly; never route by a private provider default. */
+export function createPostgresPaidFulfillmentHandoffStore(db: PgExecutor, portKey: string): FulfillmentPaidHandoffPort {
+  if (!portKey.trim()) throw new Error('fulfillment_port_key_required');
+  return {
+    ensureObligation: v => nativeCall(db, 'fulfillment_ensure_paid_handoff', [v.requestKey, v.orderRef, v.paidFactRef, portKey]),
+    acknowledge: v => nativeCall(db, 'fulfillment_ack_paid_handoff', [v.requestKey, v.fulfillmentRef]),
+  };
+}