@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/providerStockSyncWorker.ts

@@ -0,0 +1,318 @@
+import { aggregateAtpCompatibleStock, emptyLocal, stockMovementWindow } from "./providerStockAvailability.js";
+import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, LocalStock, StockSnapshot, StockMovement, SyncCursor } from "./contracts/index.js";
+type Threshold = Parameters<FulfillmentStockSyncPort["resolveLowStockEvidence"]>[0]["activeThresholdKinds"][number];
+interface StockSyncResult {
+  ok: boolean; checked: number; updated: number; mismatches: number; reservationCoverage: number;
+  unclassified: number; lowStock: number; movements: number; replayed: number; failures: number;
+  providerCalls: number; readBacks: number; skipped: boolean; syncRunId: string;
+  lastMovementOccurredAt: string | null; reason?: string;
+  rejected: number; items: NonNullable<SyncCursor["items"]>[number][];
+  providerError?: NonNullable<SyncCursor["error"]>["providerError"];
+  refusal?: NonNullable<SyncCursor["refusal"]>;
+}
+export async function runFulfillmentStockSyncWorker(input: {
+  port: FulfillmentStockSyncPort;
+  provider: FulfillmentStockSyncProvider;
+  movementBatchSize: number;
+  staleSyncThresholdHours?: number;
+  now?: () => Date;
+  compatibility: {
+    syncRunId(now: Date): string; staleEvidenceSku: string; timeZone: string;
+    currentKey(run: string, sku: string): string; snapshotKey(run: string, sku: string): string;
+    lowStockKey(sku: string, threshold: Threshold): string; staleKey(lastSyncedAt: string): string;
+  };
+}): Promise<StockSyncResult> {
+  const now = input.now?.() ?? new Date();
+  const staleThresholdHours = input.staleSyncThresholdHours && input.staleSyncThresholdHours > 0
+    ? input.staleSyncThresholdHours
+    : 6;
+  const syncRunId = input.compatibility.syncRunId(now);
+  const result: StockSyncResult = {
+    ok: true,
+    rejected: 0,
+    items: [],
+    checked: 0,
+    updated: 0,
+    mismatches: 0,
+    reservationCoverage: 0,
+    unclassified: 0,
+    lowStock: 0,
+    movements: 0,
+    replayed: 0,
+    failures: 0,
+    providerCalls: 0,
+    readBacks: 0,
+    skipped: false,
+    syncRunId,
+    lastMovementOccurredAt: null,
+  };
+
+  const alerts: NonNullable<SyncCursor["alerts"]>[number][] = [];
+  let stage = "cursor_read_failed";
+  let operationalReason: string | undefined;
+  let staleSync: SyncCursor["staleSync"];
+  let recoverStaleSync = false;
+  let previousCursor: SyncCursor | null = null;
+  let rejectedStockResponse = false;
+  const currentCoverageGapSkus = new Set<string>();
+  try {
+    previousCursor = await input.port.readCursor();
+
+    // Stale-sync alert: if the last successful sync aged past the threshold, open a stale_sync
+    // low-stock evidence row (evidence/warn — never blocks sales); a healthy run resolves it
+    // below. A never-synced state (no prior cursor) is not "stale".
+    const lastSyncedMs = previousCursor?.lastStockSyncedAt ? Date.parse(previousCursor.lastStockSyncedAt) : null;
+    const staleGapHours =
+      lastSyncedMs !== null && !Number.isNaN(lastSyncedMs) ? (now.getTime() - lastSyncedMs) / 3_600_000 : null;
+    const syncIsStale = staleGapHours !== null && staleGapHours >= staleThresholdHours;
+    recoverStaleSync = !syncIsStale;
+    if (syncIsStale) {
+      staleSync = { gapHours: Math.round(staleGapHours! * 10) / 10, thresholdHours: staleThresholdHours, detectedAt: now.toISOString() };
+      stage = "stock_evidence_write_failed";
+      alerts.push({ skuRef: input.compatibility.staleEvidenceSku, thresholdKind: "stale_sync", severity: "warning",
+        providerForSaleQuantity: 0, localAvailableQuantity: 0, ...staleSync });
+      await input.port.recordLowStockEvidence({
+        requestKey: input.compatibility.staleKey(previousCursor!.lastStockSyncedAt!),
+        skuRef: input.compatibility.staleEvidenceSku,
+        thresholdKind: "stale_sync",
+        severity: "warning",
+        providerForSaleQuantity: 0,
+        localAvailableQuantity: 0,
+        syncRunId,
+      });
+    }
+
+    stage = "cursor_write_failed";
+    await input.port.recordCursor({
+      syncRunId,
+      status: "running",
+      lastStockSyncedAt: null,
+      lastMovementOccurredAt: null,
+      continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+      coverageGapSkus: previousCursor?.coverageGapSkus ?? [], refusal: null,
+    });
+
+    stage = "stock_read_failed";
+    result.providerCalls += 1;
+    const [localStock, providerStock] = await Promise.all([
+      input.port.readLocalInventoryStock(now.toISOString()),
+      input.provider.getStock(),
+    ]);
+    const stockItems: { stock: StockSnapshot; itemIndex: number }[] = [];
+    for (const [itemIndex, item] of providerStock.entries()) {
+      if ("kind" in item && item.kind === "rejected") {
+        result.rejected += 1;
+        result.failures += 1;
+        result.items.push({ kind: "stock", itemIndex: item.itemIndex, skuRef: null, status: "rejected", reason: item.reason });
+      } else if ("skuRef" in item && item.skuRef.trim()) {
+        stockItems.push({ stock: item, itemIndex });
+      }
+    }
+    const skus = [...new Set(stockItems.map(({ stock }) => stock.skuRef))];
+    rejectedStockResponse = providerStock.length > 0 && stockItems.length === 0;
+    stage = "stock_inventory_read_failed";
+    const [inventoryClasses, activeReservations] = await Promise.all([
+      input.port.readSkuInventoryClasses(skus),
+      input.port.readActiveReservations(skus, now.toISOString()),
+    ]);
+
+    stage = "stock_movements_read_failed";
+    result.providerCalls += 1;
+    const movementRows = await input.provider.getStockMovements({ ...stockMovementWindow(previousCursor, now, input.compatibility.timeZone), size: input.movementBatchSize });
+    const movements: StockMovement[] = [];
+    for (const item of movementRows) {
+      if ("kind" in item && item.kind === "rejected") {
+        result.rejected += 1;
+        result.failures += 1;
+        result.items.push({ kind: "movement", itemIndex: item.itemIndex, skuRef: null, status: "rejected", reason: item.reason });
+      } else if ("skuRef" in item) {
+        movements.push(item);
+      }
+    }
+    if (rejectedStockResponse || (result.rejected > 0 && stockItems.length + movements.length === 0)) {
+      result.ok = false;
+      result.reason = "invalid_sku_ref";
+    }
+    result.movements = movements.length;
+    result.lastMovementOccurredAt = latestOccurredAt(movements);
+
+    const localBySku = aggregateAtpCompatibleStock(localStock, now);
+    const coverageCandidates: Array<{
+      stock: StockSnapshot;
+      local: LocalStock;
+      activeReserved: number;
+    }> = [];
+    const packagingSkus = new Set<string>();
+    const previousCoverageGapSkus = previousCursor?.status === "succeeded"
+      ? readStringSet(previousCursor.coverageGapSkus)
+      : new Set<string>();
+
+    for (const { stock, itemIndex } of stockItems) {
+      try {
+        const local = localBySku.get(stock.skuRef) ?? emptyLocal(stock.skuRef);
+        const inventoryClass = inventoryClasses.get(stock.skuRef) ?? null;
+        const activeReserved = activeReservations.get(stock.skuRef) ?? 0;
+        const staleAfter = new Date(now.getTime() + staleThresholdHours * 3_600_000).toISOString();
+        stage = "stock_current_write_failed";
+        const current = await input.port.recordProviderStockCurrent({
+          requestKey: input.compatibility.currentKey(syncRunId, stock.skuRef),
+          snapshot: stock, inventoryClass, lastSyncedAt: now.toISOString(), staleAfter,
+        });
+        stage = "snapshot_write_failed";
+        const snapshot = await input.port.recordStockSnapshot({
+          requestKey: input.compatibility.snapshotKey(syncRunId, stock.skuRef),
+          snapshot: stock, local, mismatchKind: "none", inventoryClass,
+        });
+
+        result.items.push({ itemIndex, skuRef: stock.skuRef, status: "recorded", activeReserved,
+          sellableNow: inventoryClass === "sellable" ? Math.max(0, stock.forSaleQuantity - activeReserved - local.safetyStock) : null,
+          coverageGapQuantity: Math.max(0, activeReserved - stock.forSaleQuantity) });
+        result.checked += 1;
+        result.updated += (snapshot.replayed ? 0 : 1) + (current.replayed ? 0 : 1);
+        if (snapshot.replayed) result.replayed += 1;
+        if (current.replayed) result.replayed += 1;
+        if (snapshot.readBack) result.readBacks += 1;
+        if (current.readBack) result.readBacks += 1;
+        if (inventoryClass === null) result.unclassified += 1;
+        if (inventoryClass === "packaging") packagingSkus.add(stock.skuRef);
+        if (inventoryClass === "sellable") {
+          coverageCandidates.push({ stock, local, activeReserved });
+          if (activeReserved > stock.forSaleQuantity) currentCoverageGapSkus.add(stock.skuRef);
+        }
+      } catch (error) {
+        result.ok = false;
+        result.failures += 1;
+        const reason = safeReason(error, stage);
+        operationalReason ??= reason;
+        result.items.push({ itemIndex, skuRef: stock.skuRef, status: "failed", reason });
+      }
+    }
+
+    if (result.ok) {
+      for (const { stock, local, activeReserved } of coverageCandidates) {
+        const localAvailable = availableQuantity(local);
+        const confirmedCoverageGap = currentCoverageGapSkus.has(stock.skuRef) && previousCoverageGapSkus.has(stock.skuRef);
+        const lowStockSignals = lowStockSignalsFor(stock, local, activeReserved, confirmedCoverageGap);
+        const activeThresholdKinds: Threshold[] = lowStockSignals.map((signal) => signal.thresholdKind);
+        if (currentCoverageGapSkus.has(stock.skuRef) && !activeThresholdKinds.includes("reservation_coverage")) {
+          activeThresholdKinds.push("reservation_coverage");
+        }
+        for (const signal of lowStockSignals) {
+          alerts.push({ skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
+            providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, detectedAt: now.toISOString(),
+            activeReserved, coverageGapQuantity: Math.max(0, activeReserved - stock.forSaleQuantity) });
+          stage = "stock_evidence_write_failed";
+          const evidence = await input.port.recordLowStockEvidence({
+            requestKey: input.compatibility.lowStockKey(stock.skuRef, signal.thresholdKind),
+            skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
+            providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, syncRunId,
+          });
+          if (evidence.replayed) result.replayed += 1;
+          result.lowStock += evidence.replayed ? 0 : 1;
+          if (signal.thresholdKind === "reservation_coverage") result.reservationCoverage += 1;
+        }
+        stage = "stock_evidence_resolve_failed";
+        await input.port.resolveLowStockEvidence({
+          skuRef: stock.skuRef,
+          activeThresholdKinds,
+          syncRunId,
+        });
+      }
+      for (const sku of packagingSkus) {
+        stage = "stock_evidence_resolve_failed";
+        await input.port.resolveLowStockEvidence({
+          skuRef: sku,
+          activeThresholdKinds: [],
+          syncRunId,
+        });
+      }
+    }
+  } catch (error) {
+    result.ok = false;
+    result.failures += 1;
+    result.providerError = providerDiagnostic(error);
+    if (stage === "stock_read_failed" || stage === "stock_movements_read_failed") result.refusal = admissionRefusal(error);
+    operationalReason ??= result.providerError ? `provider_${result.providerError.operation}_failed:${result.providerError.code}` : result.refusal?.reason ?? safeReason(error, stage);
+  }
+
+  result.reason = operationalReason ?? result.reason;
+  if (!result.ok) result.refusal ??= { reason: result.failures === result.rejected ? "malformed" : "io_failure", phase: "sync", retryable: result.providerError?.retryable ?? result.failures > result.rejected };
+  await input.port.recordCursor({
+    status: result.ok ? "succeeded" : "failed", syncRunId,
+    lastStockSyncedAt: result.ok ? now.toISOString() : null,
+    lastMovementOccurredAt: result.lastMovementOccurredAt,
+    continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+    coverageGapSkus: result.ok ? [...currentCoverageGapSkus].sort() : rejectedStockResponse ? previousCursor?.coverageGapSkus ?? [] : [],
+    refusal: result.refusal ?? null,
+    error: result.ok ? null : { reason: result.reason!, ...(result.providerError ? { providerError: result.providerError } : {}) },
+    counts: { checked: result.checked, updated: result.updated, movements: result.movements, rejected: result.rejected,
+      failures: result.failures, providerCalls: result.providerCalls, readBacks: result.readBacks },
+    items: result.items, alerts, staleSync,
+  });
+  // Recovery follows the durable succeeded cursor; a failed cleanup leaves the completed run intact.
+  if (result.ok && recoverStaleSync) {
+    try {
+      await input.port.resolveLowStockEvidence({
+        skuRef: input.compatibility.staleEvidenceSku,
+        activeThresholdKinds: [],
+        syncRunId,
+      });
+    } catch { /* Best-effort cleanup must not undo the completed run. */ }
+  }
+  return result;
+}
+
+function lowStockSignalsFor(
+  stock: StockSnapshot,
+  local: LocalStock,
+  activeReserved: number,
+  confirmedCoverageGap: boolean,
+): Array<{ thresholdKind: "safety_stock" | "reservation_coverage"; severity: "warning" | "critical" }> {
+  const signals: Array<{ thresholdKind: "safety_stock" | "reservation_coverage"; severity: "warning" | "critical" }> = [];
+  const remainingAfterReservations = Math.max(0, stock.forSaleQuantity - activeReserved);
+  if (local.safetyStock > 0 && remainingAfterReservations <= local.safetyStock) {
+    signals.push({ thresholdKind: "safety_stock", severity: remainingAfterReservations <= 0 ? "critical" : "warning" });
+  }
+  if (confirmedCoverageGap) signals.push({ thresholdKind: "reservation_coverage", severity: "critical" });
+  return signals;
+}
+
+function readStringSet(value: unknown): Set<string> {
+  return new Set(Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0) : []);
+}
+
+function availableQuantity(balance: LocalStock): number {
+  return Math.max(0, balance.onHand - balance.reserved - balance.unavailable - balance.safetyStock);
+}
+
+function latestOccurredAt(movements: StockMovement[]): string | null {
+  return movements
+    .map((movement) => movement.occurredAt)
+    .filter((value): value is string => Boolean(value))
+    .sort((a, b) => Date.parse(b) - Date.parse(a))[0] ?? null;
+}
+
+/** Keep the operation's closed identity and SQLSTATE only, never arbitrary exception prose. */
+function safeReason(error: unknown, operation: string): string {
+  const code = error && typeof error === "object" && "code" in error ? error.code : null;
+  if (typeof code === "string" && /^[0-9A-Z]{5}$/.test(code)) return `${operation}:${code}`;
+  const known = error instanceof Error ? error.message.match(new RegExp(`^${operation}:([0-9A-Z]{5})$`)) : null;
+  return known ? `${operation}:${known[1]}` : operation;
+}
+function providerDiagnostic(error: unknown): StockSyncResult["providerError"] {
+  if (!error || typeof error !== "object" || !("providerError" in error)) return undefined;
+  const detail = error.providerError;
+  if (!detail || typeof detail !== "object" || !("operation" in detail) || !("code" in detail) || !("status" in detail) || !("retryable" in detail)) return undefined;
+  if (detail.operation !== "get_stock" && detail.operation !== "get_stock_movements") return undefined;
+  if (typeof detail.code !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(detail.code)) return undefined;
+  return { operation: detail.operation, code: detail.code,
+    status: typeof detail.status === "number" && Number.isInteger(detail.status) && detail.status >= 100 && detail.status <= 599 ? detail.status : null,
+    retryable: detail.retryable === true };
+}
+
+function admissionRefusal(error: unknown): StockSyncResult["refusal"] {
+  if (!error || typeof error !== "object" || !("reason" in error) || !("phase" in error) || !("retryable" in error)) return undefined;
+  if (error.phase !== "sync" || typeof error.retryable !== "boolean") return undefined;
+  if (error.reason !== "disabled" && error.reason !== "not_ready" && error.reason !== "malformed") return undefined;
+  return { reason: error.reason, phase: error.phase, retryable: error.retryable };
+}

package/src/fulfillment/providerTrackingReferences.ts

@@ -0,0 +1,32 @@
+import type { FulfillmentTrackingReference, FulfillmentObservationCodecs } from "./contracts/index.js";
+
+export function trackingReferenceComplete(ref: FulfillmentTrackingReference): boolean {
+  return Boolean(ref.carrierRef && ref.publicUrl && ref.serviceRef);
+}
+/** Provider evidence wins as a unit; private carrier/URL codecs stay injected. */
+export function enrichTrackingReference(
+  ref: FulfillmentTrackingReference,
+  deliveryCarrier: { carrierRef: string | null; serviceRef: string | null } | null,
+  codecs: FulfillmentObservationCodecs & {
+    approveTrackingUrl?(url: string): boolean;
+    normalizeCarrier(input: { carrierRef: string | null; serviceRef: string | null }): string | null;
+    publicUrl(carrierRef: string | null, trackingNumber: string): string | null;
+  },
+): FulfillmentTrackingReference {
+  const providerCarrier = ref.carrierRef ?? codecs.normalizeCarrier(ref);
+  const carrierRef = providerCarrier ?? codecs.normalizeCarrier({ carrierRef: deliveryCarrier?.carrierRef ?? null, serviceRef: deliveryCarrier?.serviceRef ?? null });
+  return { trackingNumber: ref.trackingNumber, publicUrl: ref.publicUrl ?? codecs.publicUrl(carrierRef, ref.trackingNumber),
+    carrierRef, serviceRef: ref.serviceRef ?? (providerCarrier ? null : deliveryCarrier?.serviceRef ?? null) };
+}
+/** First occurrence wins, including its selection, after trimming the number. */
+export function uniqueTrackingReferences(refs: readonly FulfillmentTrackingReference[]): FulfillmentTrackingReference[] {
+  const seen = new Set<string>();
+  const result: FulfillmentTrackingReference[] = [];
+  for (const ref of refs) {
+    const trackingNumber = ref.trackingNumber.trim();
+    if (!trackingNumber || seen.has(trackingNumber)) continue;
+    seen.add(trackingNumber);
+    result.push({ trackingNumber, publicUrl: ref.publicUrl ?? null, carrierRef: ref.carrierRef ?? null, serviceRef: ref.serviceRef ?? null });
+  }
+  return result;
+}

package/src/fulfillment/replacementRefusals.ts

@@ -0,0 +1,43 @@
+export const FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS = [
+  "invalid_input",
+  "idempotency_conflict",
+  "order_not_found",
+  "order_not_replaceable",
+  "missing_client",
+  "missing_shipping_address",
+  "shipping_address_not_found",
+  "payment_not_succeeded",
+  "subscription_cycle_not_paid",
+  "no_parcel_to_replace",
+  "undispatched_replacement_exists",
+  "missing_order_items",
+  "missing_catalog_sku",
+  "missing_inventory_reservation",
+  "blocked_by_payment_not_succeeded_hold",
+  "blocked_by_inventory_review_hold",
+  "blocked_by_risk_review_hold",
+  "blocked_by_address_review_hold",
+  "blocked_by_manual_support_hold",
+] as const;
+
+export const FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS = [
+  "inventory_external_provider_insufficient_available_stock",
+  "inventory_external_provider_stock_stale",
+  "inventory_external_provider_stock_missing",
+  "inventory_external_provider_sku_not_found",
+  "inventory_external_provider_location_missing",
+  "inventory_reservation_insufficient_available_stock",
+  "inventory_reservation_allocation_incomplete",
+  "inventory_reservation_payment_status_not_reservable",
+  "inventory_reservation_invalid_quantity",
+] as const;
+
+export const UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL = "unspecified_refusal";
+
+export const FULFILLMENT_REPLACEMENT_REFUSALS = [
+  ...FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS,
+  ...FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS,
+  UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL,
+] as const;
+
+export type FulfillmentReplacementRefusal = (typeof FULFILLMENT_REPLACEMENT_REFUSALS)[number];

package/src/fulfillment/replacementShipmentHandler.ts

@@ -0,0 +1,47 @@
+import { adminCommerceOrderRequestReplacementShipmentRequestSchema, adminCommerceOrderRequestReplacementShipmentResponseSchema } from './handlerSchemas.js';
+import { authorize, CommerceFulfillmentConflictError, isNativeUnsupported, type BaseDeps, type FulfillmentHandlerRequest, type FulfillmentHandlerResponder } from './handlerSupport.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+export function createAdminCommerceOrderRequestReplacementShipmentHandler<Response>({
+  authorizeAdmin,
+  respond,
+  omsPort,
+}: BaseDeps<Response> & {
+  omsPort: FulfillmentReplacementPort;
+}) {
+  const { sendMethodNotAllowed } = respond;
+  return async function handler(req: FulfillmentHandlerRequest, res: Response): Promise<void> {
+    if (req.method !== "POST") return sendMethodNotAllowed(res, ["POST"]);
+    const auth = await authorize(req, res, authorizeAdmin, respond);
+    if (!auth) return;
+
+    const request = parseOmsRequest(res, respond, adminCommerceOrderRequestReplacementShipmentRequestSchema, req.body ?? {}, "Invalid admin commerce replacement shipment request");
+    if (request === undefined) return;
+
+    await sendOmsMutationResponse(
+      res,
+      respond,
+      () => omsPort.requestReplacementShipment({ ...request, actorUserId: auth.userId }),
+      adminCommerceOrderRequestReplacementShipmentResponseSchema,
+      "Admin commerce replacement shipment returned invalid response",
+      "Admin commerce replacement shipment failed",
+    );
+  };
+}
+
+function parseOmsRequest<Response, T>(res: Response, respond: FulfillmentHandlerResponder<Response>, schema: { safeParse(input: unknown): { success: true; data: T } | { success: false; error: { flatten(): unknown } } }, input: unknown, message: string): T | undefined {
+  const request = schema.safeParse(input);
+  if (!request.success) { respond.sendBffError(res, 'BAD_REQUEST', message, { details: request.error.flatten() }); return undefined; }
+  return request.data;
+}
+async function sendOmsMutationResponse<Response>(res: Response, respond: FulfillmentHandlerResponder<Response>, action: () => Promise<unknown>, schema: typeof adminCommerceOrderRequestReplacementShipmentResponseSchema, invalidMessage: string, failureMessage: string) {
+  try {
+    const result = await action();
+    if (isNativeUnsupported(result)) { respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', 'Native fulfillment operation unsupported', { details: result }); return; }
+    const response = schema.safeParse(result);
+    if (!response.success) { respond.sendBffError(res, 'INVALID_RESPONSE', invalidMessage); return; }
+    respond.sendBffSuccess(res, response.data);
+  } catch (error) {
+    if (error instanceof CommerceFulfillmentConflictError) { respond.sendBffError(res, 'CONFLICT', error.message, { details: error.details }); return; }
+    respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', failureMessage);
+  }
+}

package/src/fulfillment/schemaCapabilities.ts

@@ -0,0 +1,7 @@
+/** Sparse projections require the full canonical graph and a trusted native binding. */
+export const FULFILLMENT_NATIVE_CAPABILITIES = {
+  shipment: 'supported', commandFence: 'supported', deliveryAlignment: 'supported',
+  stockEvidence: 'supported', observationPersistence: 'supported',
+  localInventoryBalances: 'host_required', dispatchContactPreparation: 'host_required',
+  productPacks: 'unsupported', providerAccess: 'unsupported', automaticReplacementConfirmation: 'unsupported',
+} as const;

package/src/fulfillment/shipmentsOverviewHandler.ts

@@ -0,0 +1,73 @@
+import { isNativeUnsupported, type FulfillmentHandlerRequest, type FulfillmentHandlerResponder } from './handlerSupport.js';
+import { z } from 'zod';
+import type { FulfillmentShipmentsOverviewPort, FulfillmentShipmentsOverviewResponse } from './contracts/read.js';
+
+const adminShipmentsOverviewRequestSchema = z.object({
+  shippedFilter: z.enum(['today', '7d', '30d', 'all']).default('7d'),
+});
+
+export interface FulfillmentShipmentsOverviewHandlerDeps<Response> {
+  respond: FulfillmentHandlerResponder<Response>;
+  overviewPort: FulfillmentShipmentsOverviewPort;
+  responseSchema: { safeParse(input: unknown): { success: true; data: FulfillmentShipmentsOverviewResponse } | { success: false } };
+  authorizeAdmin: (req: FulfillmentHandlerRequest) => Promise<boolean>;
+}
+
+export function createFulfillmentShipmentsOverviewHandler<Response>({
+  respond,
+  overviewPort,
+  responseSchema: adminShipmentsOverviewResponseSchema,
+  authorizeAdmin,
+}: FulfillmentShipmentsOverviewHandlerDeps<Response>) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: FulfillmentHandlerRequest, 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");
+      return;
+    }
+
+    if (!authorized) {
+      sendBffError(res, "UNAUTHORIZED", "Admin session required");
+      return;
+    }
+
+    const request = adminShipmentsOverviewRequestSchema.safeParse({
+      shippedFilter: scalarQuery(req.query.shippedFilter),
+    });
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid shipments overview request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await overviewPort.getShipmentsOverview(request.data);
+      if (isNativeUnsupported(result)) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+        return;
+      }
+      const response = adminShipmentsOverviewResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Shipments overview returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Shipments overview read failed");
+    }
+  };
+}
+
+function scalarQuery(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}

package/src/fulfillment/statusMap.ts

@@ -0,0 +1,2 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "@openlup/core/fulfillment";
+export type { FulfillmentStatusStage, FulfillmentStatusMap } from "@openlup/core/fulfillment";

package/src/fulfillment/trackingProgress.ts

@@ -0,0 +1 @@
+export { fulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/src/fulfillment/verifiedIngress.ts

@@ -0,0 +1,113 @@
+import type { FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import { safeDiagnosticCode } from "./dispatchProjection.js";
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
+import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
+
+type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
+type DispatchRef = { orderRef: string; fulfillmentRef: string; dispatchRef: string; externalRef: string | null };
+export interface FulfillmentIngressCounts { invalidTimestamps: number; rejectedCorrelationRefs: number; rejectedTrackingRefs: number; rejectedTrackingUrls: number }
+export type FulfillmentIngressResult = { counts: FulfillmentIngressCounts } & (
+  | { kind: "refused"; receiptId: null; refusal: FulfillmentRefusal; diagnostics?: { invalidTimestamp?: true; rejectedCorrelationRefs?: number } }
+  | { kind: "processed" | "ignored" | "superseded"; receiptId: string; observation: FulfillmentObservation; replayed: boolean; trackingRefs: number; trackingReadBacks: number; supersededCause?: string });
+/** Safe response classes only; the host owns HTTP and localized message text. */
+export function fulfillmentIngressHttpResult(result: FulfillmentIngressResult): { status: 200 | 400 | 403 | 503; messageClass: "accepted" | "bad_request" | "forbidden" | "upstream_unavailable" } {
+  if (result.kind !== "refused") return { status: 200, messageClass: "accepted" };
+  if (result.refusal.reason === "untrusted") return { status: 403, messageClass: "forbidden" };
+  if (result.refusal.reason === "disabled" || result.refusal.reason === "not_ready" || result.refusal.retryable)
+    return { status: 503, messageClass: "upstream_unavailable" };
+  return { status: 400, messageClass: "bad_request" };
+}
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export async function verifyAndNormalizeFulfillmentObservation(input: {
+  enabled: boolean;
+  approveTrackingUrl?(url: string): boolean;
+  observationCodecs?: FulfillmentObservationCodecs;
+  provider: FulfillmentObservationPort;
+  verification: Parameters<FulfillmentObservationPort["verifyAndNormalize"]>[0];
+  localPersistence: {
+    /** G17: atomic insert by eventKey; retries keep the first stored firstReceivedAt. */
+    recordObservation(observation: FulfillmentObservation): Promise<{ replayed: boolean; receiptId?: string }>;
+    /** Idempotent; only called after completion or a classified superseding conflict. */
+    markProcessed(eventKey: string, outcome: { status: "processed" | "ignored"; refusal?: FulfillmentRefusal; supersededCause?: string }): Promise<void>;
+  };
+  lifecycle: {
+    findDispatchRef(observation: FulfillmentObservation): Promise<DispatchRef | null>;
+    acknowledgeDispatchAcceptance(ref: DispatchRef, observation: FulfillmentObservation): Promise<void>;
+    recordStatusEvidence(ref: DispatchRef, observation: FulfillmentObservation): Promise<{ replayed: boolean }>;
+    effects: EffectInput["port"];
+    keys: { stock(ref: string): string; handoff(ref: string): string; tracking(eventKey: string, number: string): string };
+    issueAccountingInvoice?(ref: string): Promise<void>;
+    /** Return a machine identity, never exception prose. */
+    supersededCause?(error: unknown): string | null;
+    classifyFailure(error: unknown): "stock_contention" | "state_conflict" | "other";
+    annotateStockContention?(eventKey: string, fulfillmentRef: string): Promise<void>;
+  };
+}): Promise<FulfillmentIngressResult> {
+  const counts: FulfillmentIngressCounts = { invalidTimestamps: 0, rejectedCorrelationRefs: 0, rejectedTrackingRefs: 0, rejectedTrackingUrls: 0 };
+  if (!input.enabled) return { kind: "refused", receiptId: null, counts, refusal: { reason: "disabled", phase: "verify", retryable: false } };
+  const verified = await input.provider.verifyAndNormalize(input.verification);
+  if (verified.kind === "refused") {
+    if (verified.diagnostics?.invalidTimestamp) counts.invalidTimestamps++;
+    const rejected = verified.diagnostics?.rejectedCorrelationRefs;
+    if (typeof rejected === "number" && Number.isSafeInteger(rejected) && rejected > 0) counts.rejectedCorrelationRefs = rejected;
+    return { kind: "refused", receiptId: null, refusal: verified.refusal, counts,
+      ...(counts.invalidTimestamps || counts.rejectedCorrelationRefs ? { diagnostics: {
+        ...(counts.invalidTimestamps ? { invalidTimestamp: true as const } : {}),
+        ...(counts.rejectedCorrelationRefs ? { rejectedCorrelationRefs: counts.rejectedCorrelationRefs } : {}),
+      } } : {}) };
+  }
+  const observation = projectObservation(verified.observation, input.approveTrackingUrl, input.observationCodecs);
+  counts.rejectedTrackingRefs = observation.diagnostics?.admission?.rejectedTrackingRefs ?? 0;
+  counts.rejectedTrackingUrls = observation.diagnostics?.admission?.rejectedTrackingUrls ?? 0;
+  const inbound = await input.localPersistence.recordObservation(observation);
+  const receiptId = inbound.receiptId ?? observation.eventKey;
+  const ref = await input.lifecycle.findDispatchRef(observation);
+  if (!ref) {
+    await input.localPersistence.markProcessed(observation.eventKey, { status: "ignored", refusal: { reason: "local_missing", phase: "apply", retryable: false } });
+    return { kind: "ignored", receiptId, counts, observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+  }
+  const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
+  if (!externalRef) throw new TypeError("fulfillment_dispatch_acceptance_external_ref_missing");
+  await input.lifecycle.acknowledgeDispatchAcceptance(ref, observation);
+  const statusEvidence = await input.lifecycle.recordStatusEvidence(ref, observation);
+  let trackingRefs = 0;
+  let trackingReadBacks = 0;
+  const effectPort: EffectInput["port"] = {
+    ...input.lifecycle.effects,
+    async markProviderStockConsumed(request) {
+      try { return await input.lifecycle.effects.markProviderStockConsumed(request); }
+      catch (error) {
+        if (input.lifecycle.classifyFailure(error) === "stock_contention") {
+          try {
+            await input.lifecycle.annotateStockContention?.(observation.eventKey, ref.fulfillmentRef);
+          } catch { /* Annotation is best-effort; preserve the original stock failure. */ }
+        }
+        throw error;
+      }
+    },
+  };
+  const localStatus = observation.fact.canonicalStatus;
+  const effects: EffectInput = {
+    port: effectPort, localStatus, ids: { orderId: ref.orderRef, fulfillmentOrderId: ref.fulfillmentRef }, observation,
+    trackingRefs: uniqueTrackingReferences(observation.trackingRefs).map(tracking => ({ trackingNumber: tracking.trackingNumber, trackingUrl: tracking.publicUrl, carrierKind: tracking.carrierRef, service: tracking.serviceRef })),
+    stockIdempotencyKey: input.lifecycle.keys.stock(ref.fulfillmentRef), handoffIdempotencyKey: input.lifecycle.keys.handoff(ref.fulfillmentRef),
+    trackingIdempotencyKey: number => input.lifecycle.keys.tracking(observation.eventKey, number),
+    issueAccountingInvoice: input.lifecycle.issueAccountingInvoice ? () => input.lifecycle.issueAccountingInvoice!(ref.fulfillmentRef) : undefined,
+    onTrackingRecorded: result => { trackingRefs += result.replayed ? 0 : 1; trackingReadBacks += result.readBack ? 1 : 0; },
+  };
+  if (!observationStatusPolicy.handsOver(localStatus)) await applyFulfillmentObservationEffects({ ...effects, trackingRefs: [] }, observationStatusPolicy);
+  else {
+    try { await applyFulfillmentObservationEffects(effects, observationStatusPolicy); }
+    catch (error) {
+      if (input.lifecycle.classifyFailure(error) !== "state_conflict") throw error;
+      const cause = input.lifecycle.supersededCause ? input.lifecycle.supersededCause(error)
+        : error && typeof error === "object" && "reason" in error ? error.reason : null;
+      const supersededCause = safeDiagnosticCode(cause) ?? "fulfillment_state_conflict";
+      await input.localPersistence.markProcessed(observation.eventKey, { status: "processed", supersededCause });
+      return { kind: "superseded", receiptId, counts, supersededCause, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+    }
+  }
+  await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+  return { kind: "processed", receiptId, counts, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+}

package/src/invoicing/capabilities.ts

@@ -0,0 +1,9 @@
+import type { InvoiceCapabilities, InvoiceCapabilitySelection } from "./contracts/capabilities.js";
+/** @consumer Host readiness / installed cold consumer. Default off and explicit
+ * provider selection precede capability use; construction never selects a provider.
+ */
+export function readInvoiceCapabilities(input: { readonly enabled?: boolean; readonly selection: { readonly providerRef: string } | null; readonly capability: InvoiceCapabilities | null }): InvoiceCapabilitySelection {
+  if (input.enabled !== true) return { kind: "refused", code: "disabled", retryable: false, effectMayHaveSucceeded: false };
+  if (!input.selection || !input.capability || input.selection.providerRef !== input.capability.providerRef) return { kind: "refused", code: "selection_required", retryable: false, effectMayHaveSucceeded: false };
+  return { kind: "ready", capability: input.capability };
+}