@openlup/platform 0.22.0 → 0.23.0

package/src/fulfillment/providerReconciliationWorker.ts

@@ -1,6 +1,7 @@
-import type { FulfillmentObservation, FulfillmentReadbackResult } from "./contracts/index.js";
+import type { FulfillmentObservation, FulfillmentObservationPagePort, FulfillmentReconciliationObservation, FulfillmentOperationError } from "./contracts/index.js";
+import { durableStrings, localFailureReason, safeDiagnosticCode, operationError } from "./dispatchProjection.js";
 import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
-import { observationStatusPolicy, projectCorrelation, projectObservation } from "./observationProjection.js";
+import { observationStatusPolicy, projectObservation, projectPollEvidence, projectTrackingReference } from "./observationProjection.js";
 import { quarantineReconciliationStateConflict } from "./providerReconciliationError.js";
 import { isOffTrackFulfillmentStatus } from "./providerReconciliationTerminalSkip.js";
 import { normalizeReconciliationTimestamp } from "./providerReconciliationTimestamp.js";
@@ -8,22 +9,24 @@ import { enrichTrackingReference, trackingReferenceComplete, uniqueTrackingRefer
 
 type Ingress = Parameters<typeof import("./verifiedIngress.js").verifyAndNormalizeFulfillmentObservation>[0];
 type DispatchRef = NonNullable<Awaited<ReturnType<Ingress["lifecycle"]["findDispatchRef"]>>>;
-type PollEvidence = FulfillmentObservation | { correlation: FulfillmentObservation["correlation"]; eventKey: string };
-interface ReconciliationResult {
+type PollEvidence = Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics"> | FulfillmentObservation;
+export interface ReconciliationResult {
   ok: boolean; checked: number; updated: number; trackingRefs: number; quarantined: number;
   stateConflicts: number; exceptions: number; stale: number; offTrackSkips: number; replayed: number;
-  failures: number; invoiceIssueFailures: number; invoiceIssueRefused: number;
+  redactedFieldCount?: number; failures: number; invoiceIssueFailures: number; invoiceIssueRefused: number;
   invoiceIssueRefusals: { fulfillmentRef: string; identifier: string | null; sqlstate: string; benign: boolean }[];
-  providerCalls: number; readBacks: number; skipped: boolean; reason?: string;
+  providerCalls: number; readBacks: number; skipped: boolean; reason?: string; providerError?: FulfillmentOperationError;
 }
 
 export async function reconcileFulfillmentObservations(input: {
   /** Adapter/host maps the private page into typed readback, preserving unknowns. */
-  readPage(input: { page: number; size: number }): Promise<readonly (FulfillmentReadbackResult | { kind: "unmapped"; evidence: { correlation: FulfillmentObservation["correlation"]; eventKey: string }; externalRef: string | null })[]>;
+  readPage(input: { page: number; size: number }): Promise<readonly FulfillmentReconciliationObservation[]>;
   batchSize: number; page?: number;
   localPersistence: {
     /** G17: local persisted chronology, never inferred from dispatch or provider state. */
-    readLocalFulfillmentState(ref: string): Promise<{ status: string | null; latestStatusOccurredAt: string | null; handedOverAt: string | null }>;
+    readLocalFulfillmentStatus(ref: string): Promise<string | null>;
+    latestStatusOccurredAt(ref: string): Promise<string | null>;
+    readHandedOverAt(ref: string): Promise<string | null>;
   };
   lifecycle: Pick<Ingress["lifecycle"], "recordStatusEvidence" | "effects" | "keys"> & {
     findDispatchRef(evidence: PollEvidence): Promise<DispatchRef | null>;
@@ -38,6 +41,8 @@ export async function reconcileFulfillmentObservations(input: {
     classifyStateConflict(error: unknown): "fulfillment_not_found" | "stock_consumed_requires_label" | null;
   };
 }): Promise<ReconciliationResult> {
+  const privacy = durableStrings();
+  const failure = (stage: string, error: unknown) => localFailureReason(stage, error, privacy);
   const result: ReconciliationResult = {
     ok: true, checked: 0, updated: 0, trackingRefs: 0, quarantined: 0, stateConflicts: 0, exceptions: 0,
     stale: 0, offTrackSkips: 0, replayed: 0, failures: 0, invoiceIssueFailures: 0, invoiceIssueRefused: 0,
@@ -45,8 +50,6 @@ export async function reconcileFulfillmentObservations(input: {
   };
   const page = await input.readPage({ page: input.page ?? 0, size: input.batchSize });
   result.providerCalls += 1;
-  // A failed provider read cannot become a successful unknown-status quarantine.
-  if (page.some(readback => readback.kind === "unknown")) throw new Error("fulfillment_reconciliation_provider_read_failed");
   result.checked = page.length;
   const quarantine = async (observation: PollEvidence | null, reason: Parameters<typeof input.lifecycle.recordQuarantine>[1]) => {
     const evidence = await input.lifecycle.recordQuarantine(observation, reason);
@@ -59,26 +62,31 @@ export async function reconcileFulfillmentObservations(input: {
       const refusal = input.lifecycle.invoiceFailure(error);
       if (refusal.permanent) {
         result.invoiceIssueRefused += 1;
+        const identifier = privacy.token(refusal.identifier, safeDiagnosticCode), sqlstate = privacy.token(refusal.sqlstate, safeDiagnosticCode);
         if (result.invoiceIssueRefusals.length < 10) result.invoiceIssueRefusals.push({ fulfillmentRef: ref,
-          identifier: refusal.identifier, sqlstate: refusal.sqlstate ?? "22023", benign: refusal.benign });
-        result.reason ??= "reconciliation_invoice_issue_refused";
+          identifier, sqlstate: sqlstate ?? "22023", benign: refusal.benign });
+        result.reason ??= failure("reconciliation_invoice_issue_refused", { causeMessage: identifier, causeCode: sqlstate, message: error instanceof Error ? error.message : undefined });
         return;
       }
       result.ok = false; result.failures += 1; result.invoiceIssueFailures += 1;
-      result.reason ??= "reconciliation_invoice_issue_failed";
+      result.reason ??= failure("reconciliation_invoice_issue_failed", error);
     }
   };
   for (const readback of page) {
     let observation: FulfillmentObservation | null = null;
     try {
+      if (readback.kind === "unknown") {
+        result.ok = false; result.failures += 1; result.reason ??= "fulfillment_reconciliation_provider_read_failed";
+        continue;
+      }
       if (readback.kind === "unmapped") {
         // An unknown primary status still correlates/ACKs, but an off-track row
         // must never trade a benign skip for a quarantine alarm.
-        const evidence = { eventKey: readback.evidence.eventKey, correlation: projectCorrelation(readback.evidence.correlation) };
+        const evidence = projectPollEvidence(readback.evidence);
         const ref = await input.lifecycle.findDispatchRef(evidence);
         if (!ref) { await quarantine(evidence, "missing_correlation"); continue; }
-        const state = await input.localPersistence.readLocalFulfillmentState(ref.fulfillmentRef);
-        if (isOffTrackFulfillmentStatus(state.status)) { result.offTrackSkips += 1; continue; }
+        const localState = await input.localPersistence.readLocalFulfillmentStatus(ref.fulfillmentRef);
+        if (isOffTrackFulfillmentStatus(localState)) { result.offTrackSkips += 1; continue; }
         if (!(readback.externalRef?.trim() || ref.externalRef?.trim())) { await quarantine(evidence, "missing_external_ref"); continue; }
         await input.lifecycle.acknowledgeDispatchAcceptance(ref, evidence);
         await quarantine(evidence, "unknown_status");
@@ -88,11 +96,14 @@ export async function reconcileFulfillmentObservations(input: {
         // Neither unsupported nor a provider absence is a local transition.
         continue;
       }
-      observation = projectObservation(readback.observation);
+      observation = projectObservation(readback.observation, input.lifecycle.trackingCodecs.approveTrackingUrl, input.lifecycle.trackingCodecs);
+      if (observation.diagnostics?.redactedFieldCount) {
+        result.redactedFieldCount = (result.redactedFieldCount ?? 0) + observation.diagnostics.redactedFieldCount;
+      }
       const ref = await input.lifecycle.findDispatchRef(observation);
       if (!ref) { await quarantine(observation, "missing_correlation"); continue; }
-      const state = await input.localPersistence.readLocalFulfillmentState(ref.fulfillmentRef);
-      const offTrack = isOffTrackFulfillmentStatus(state.status);
+      const localState = await input.localPersistence.readLocalFulfillmentStatus(ref.fulfillmentRef);
+      const offTrack = isOffTrackFulfillmentStatus(localState);
       if (offTrack) result.offTrackSkips += 1;
       if (!offTrack) {
         if (!(readback.externalRef.trim() || ref.externalRef?.trim())) { await quarantine(observation, "missing_external_ref"); continue; }
@@ -100,9 +111,10 @@ export async function reconcileFulfillmentObservations(input: {
       }
       const occurredAt = normalizeReconciliationTimestamp(readback.updatedAt);
       const localStatus = observation.fact.canonicalStatus;
-      if (state.latestStatusOccurredAt && occurredAt && Date.parse(occurredAt) < Date.parse(state.latestStatusOccurredAt)) {
+      const latest = await input.localPersistence.latestStatusOccurredAt(ref.fulfillmentRef);
+      if (latest && occurredAt && Date.parse(occurredAt) < Date.parse(latest)) {
         result.stale += 1;
-        if (!offTrack && input.lifecycle.issueAccountingInvoice && state.handedOverAt) await invoice(ref.fulfillmentRef);
+        if (!offTrack && input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef)) await invoice(ref.fulfillmentRef);
         continue;
       }
       // The normalized fact carries the same nullable occurrence used by dedupe.
@@ -115,7 +127,7 @@ export async function reconcileFulfillmentObservations(input: {
         const exception = await input.lifecycle.recordProviderException(ref, observation);
         if (exception.replayed) result.replayed += 1;
         result.exceptions += exception.replayed ? 0 : 1;
-        if (input.lifecycle.issueAccountingInvoice && state.handedOverAt) await invoice(ref.fulfillmentRef);
+        if (input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef)) await invoice(ref.fulfillmentRef);
         continue;
       }
       const trackingRefs = [];
@@ -123,7 +135,12 @@ export async function reconcileFulfillmentObservations(input: {
         let carrier: Awaited<ReturnType<typeof input.lifecycle.readDeliveryCarrier>> | undefined;
         for (const tracking of uniqueTrackingReferences(observation.trackingRefs)) {
           if (!trackingReferenceComplete(tracking) && carrier === undefined) carrier = await input.lifecycle.readDeliveryCarrier(ref.fulfillmentRef);
-          const enriched = enrichTrackingReference(tracking, carrier ?? null, input.lifecycle.trackingCodecs);
+          const codecs = input.lifecycle.trackingCodecs;
+          const candidate = enrichTrackingReference(tracking, carrier ?? null, { ...codecs, publicUrl: () => null });
+          const enriched = projectTrackingReference(candidate, privacy, codecs.approveTrackingUrl, codecs);
+          if (!enriched) continue;
+          // Host-built links use admitted parts and pass through unchanged, including queries.
+          enriched.publicUrl ??= codecs.publicUrl(enriched.carrierRef, enriched.trackingNumber);
           trackingRefs.push({ trackingNumber: enriched.trackingNumber, trackingUrl: enriched.publicUrl, carrierKind: enriched.carrierRef, service: enriched.serviceRef });
         }
       }
@@ -143,8 +160,47 @@ export async function reconcileFulfillmentObservations(input: {
       const error = observation ? await quarantineReconciliationStateConflict(caught, observation,
         input.lifecycle.classifyStateConflict, input.lifecycle.recordQuarantine, result) : caught;
       if (error === null) continue;
-      result.ok = false; result.failures += 1; result.reason ??= "reconciliation_local_operation_failed";
+      result.ok = false; result.failures += 1; result.reason ??= failure("reconciliation_local_operation_failed", error);
+    }
+  }
+  return { ...result, ...(privacy.redactedFieldCount ? { redactedFieldCount: (result.redactedFieldCount ?? 0) + privacy.redactedFieldCount } : {}) };
+}
+
+
+/** Host owns scheduling, HTTP and durable job-ledger writes. This operation only projects them. */
+export async function runFulfillmentReconciliationPage(input: Omit<Parameters<typeof reconcileFulfillmentObservations>[0], "readPage" | "batchSize" | "page"> & {
+  provider: FulfillmentObservationPagePort; pageSize: number; checkpoint: unknown;
+}) {
+  if (!Number.isSafeInteger(input.pageSize) || input.pageSize <= 0) throw new Error("reconciliation_page_size_invalid");
+  const isPage = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) >= 0;
+  const checkpoint = input.checkpoint as { reconciliationPagination?: { version?: unknown; pageSize?: unknown; page?: unknown; nextPage?: unknown } } | null;
+  const saved = checkpoint?.reconciliationPagination;
+  const page = saved?.version === 1 && saved.pageSize === input.pageSize && isPage(saved.page) && isPage(saved.nextPage)
+    && (saved.nextPage === 0 || saved.nextPage === saved.page || saved.page < Number.MAX_SAFE_INTEGER && saved.nextPage === saved.page + 1) ? saved.nextPage : 0;
+  const privacy = durableStrings();
+  let result: ReconciliationResult;
+  let pageRead = false;
+  const empty = (): ReconciliationResult => ({ ok: true, checked: 0, updated: 0, trackingRefs: 0, quarantined: 0, stateConflicts: 0, exceptions: 0,
+    stale: 0, offTrackSkips: 0, replayed: 0, failures: 0, invoiceIssueFailures: 0, invoiceIssueRefused: 0, invoiceIssueRefusals: [], providerCalls: 1, readBacks: 0, skipped: false });
+  try {
+    const response = await input.provider.readPage({ page, size: input.pageSize });
+    if (response.kind === "page_exhausted") result = { ...empty(), reason: "page_exhausted" };
+    else if (response.kind === "failed") {
+      const providerError = response.error ? operationError(response.error) : undefined;
+      result = { ...empty(), ok: false, failures: 1, ...(providerError ? { providerError } : {}),
+        reason: providerError?.code ?? privacy.token(response.refusal.reason) ?? "redacted" };
+    }
+    else {
+      pageRead = true;
+      result = await reconcileFulfillmentObservations({ ...input, batchSize: input.pageSize, page, readPage: async () => response.rows });
     }
+  } catch (error) {
+    result = { ...empty(), ok: false, failures: 1, reason: localFailureReason(pageRead ? "reconciliation_page_failed" : "reconciliation_provider_read_failed", error, privacy) };
   }
-  return result;
+  if (privacy.redactedFieldCount) result.redactedFieldCount = (result.redactedFieldCount ?? 0) + privacy.redactedFieldCount;
+  // A pre-traversal abort must not skip a page. Item failures return normally.
+  const nextPage = pageRead && result.checked === 0 && !result.ok ? page
+    : result.checked === input.pageSize && page < Number.MAX_SAFE_INTEGER ? page + 1 : 0;
+  return { status: result.ok ? 200 as const : 502 as const, ledgerStatus: result.ok ? "succeeded" as const : "failed" as const, result,
+    metadata: { reconciliationPagination: { version: 1, page, pageSize: input.pageSize, nextPage } } };
 }

package/src/fulfillment/providerStockSyncWorker.ts

@@ -1,11 +1,14 @@
 import { aggregateAtpCompatibleStock, emptyLocal, stockMovementWindow } from "./providerStockAvailability.js";
-import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, LocalStock, StockSnapshot, StockMovement } from "./contracts/index.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;
@@ -26,6 +29,8 @@ export async function runFulfillmentStockSyncWorker(input: {
   const syncRunId = input.compatibility.syncRunId(now);
   const result: StockSyncResult = {
     ok: true,
+    rejected: 0,
+    items: [],
     checked: 0,
     updated: 0,
     mismatches: 0,
@@ -42,152 +47,218 @@ export async function runFulfillmentStockSyncWorker(input: {
     lastMovementOccurredAt: null,
   };
 
-  const 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;
-  if (syncIsStale) {
-    await input.port.recordLowStockEvidence({
-      requestKey: input.compatibility.staleKey(previousCursor!.lastStockSyncedAt!),
-      skuRef: input.compatibility.staleEvidenceSku,
-      thresholdKind: "stale_sync",
-      severity: "warning",
-      providerForSaleQuantity: 0,
-      localAvailableQuantity: 0,
+  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,
     });
-  }
 
-  await input.port.recordCursor({
-    status: "running",
-    lastStockSyncedAt: null,
-    lastMovementOccurredAt: null,
-    continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
-    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()),
+    ]);
 
-  const [localStock, providerStock] = await Promise.all([
-    input.port.readLocalInventoryStock(now.toISOString()),
-    input.provider.getStock(),
-  ]);
-  result.providerCalls += 1;
-
-  const stockItems = providerStock.filter((item) => item.skuRef.trim());
-  const skus = [...new Set(stockItems.map((item) => item.skuRef))];
-  const [inventoryClasses, activeReservations] = await Promise.all([
-    input.port.readSkuInventoryClasses(skus),
-    input.port.readActiveReservations(skus, now.toISOString()),
-  ]);
-
-  const movements = await input.provider.getStockMovements({ ...stockMovementWindow(previousCursor, now, input.compatibility.timeZone), size: input.movementBatchSize });
-  result.providerCalls += 1;
-  result.movements = movements.length;
-  result.lastMovementOccurredAt = latestOccurredAt(movements);
-
-  const localBySku = aggregateAtpCompatibleStock(localStock, now);
-  const coverageCandidates: Array<{
-    stock: StockSnapshot;
-    local: LocalStock;
-    activeReserved: number;
-  }> = [];
-  const currentCoverageGapSkus = new Set<string>();
-  const packagingSkus = new Set<string>();
-  const previousCoverageGapSkus = previousCursor?.status === "succeeded"
-    ? readStringSet(previousCursor.coverageGapSkus)
-    : new Set<string>();
+    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);
 
-  for (const stock 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();
-      const current = await input.port.recordProviderStockCurrent({
-        requestKey: input.compatibility.currentKey(syncRunId, stock.skuRef),
-        snapshot: stock, inventoryClass, lastSyncedAt: now.toISOString(), staleAfter,
-      });
-      const snapshot = await input.port.recordStockSnapshot({
-        requestKey: input.compatibility.snapshotKey(syncRunId, stock.skuRef),
-        snapshot: stock, local, mismatchKind: "none", inventoryClass,
-      });
+    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.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);
+        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 });
       }
-    } catch (error) {
-      result.ok = false;
-      result.failures += 1;
-      result.reason = result.reason ?? "stock_sync_operation_failed";
     }
-  }
 
-  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");
+    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 signal of lowStockSignals) {
-        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,
+      for (const sku of packagingSkus) {
+        stage = "stock_evidence_resolve_failed";
+        await input.port.resolveLowStockEvidence({
+          skuRef: sku,
+          activeThresholdKinds: [],
+          syncRunId,
         });
-        if (evidence.replayed) result.replayed += 1;
-        result.lowStock += evidence.replayed ? 0 : 1;
-        if (signal.thresholdKind === "reservation_coverage") result.reservationCoverage += 1;
       }
-      await input.port.resolveLowStockEvidence({
-        skuRef: stock.skuRef,
-        activeThresholdKinds,
-        syncRunId,
-      });
-    }
-    for (const sku of packagingSkus) {
-      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",
+    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() : [],
-    refusal: result.ok ? null : { reason: "io_failure", phase: "sync", retryable: true },
+    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: a healthy run (succeeded, not itself stale) closes any open stale_sync row.
-  if (result.ok && !syncIsStale) {
-    await input.port.resolveLowStockEvidence({
-      skuRef: input.compatibility.staleEvidenceSku,
-      activeThresholdKinds: [],
-      syncRunId,
-
-    });
+  // 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;
 }
 
@@ -220,3 +291,28 @@ function latestOccurredAt(movements: StockMovement[]): string | null {
     .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

@@ -1,4 +1,4 @@
-import type { FulfillmentTrackingReference } from "./contracts/index.js";
+import type { FulfillmentTrackingReference, FulfillmentObservationCodecs } from "./contracts/index.js";
 
 export function trackingReferenceComplete(ref: FulfillmentTrackingReference): boolean {
   return Boolean(ref.carrierRef && ref.publicUrl && ref.serviceRef);
@@ -7,7 +7,8 @@ export function trackingReferenceComplete(ref: FulfillmentTrackingReference): bo
 export function enrichTrackingReference(
   ref: FulfillmentTrackingReference,
   deliveryCarrier: { carrierRef: string | null; serviceRef: string | null } | null,
-  codecs: {
+  codecs: FulfillmentObservationCodecs & {
+    approveTrackingUrl?(url: string): boolean;
     normalizeCarrier(input: { carrierRef: string | null; serviceRef: string | null }): string | null;
     publicUrl(carrierRef: string | null, trackingNumber: string): string | null;
   },