@openlup/platform 0.22.0 → 0.24.0

package/dist/fulfillment/providerReconciliationWorker.js

@@ -1,10 +1,13 @@
+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";
 import { enrichTrackingReference, trackingReferenceComplete, uniqueTrackingReferences } from "./providerTrackingReferences.js";
 export async function reconcileFulfillmentObservations(input) {
+    const privacy = durableStrings();
+    const failure = (stage, error) => localFailureReason(stage, error, privacy);
     const result = {
         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,
@@ -12,9 +15,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, reason) => {
         const evidence = await input.lifecycle.recordQuarantine(observation, reason);
@@ -30,32 +30,39 @@ 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 = 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)) {
+                const localState = await input.localPersistence.readLocalFulfillmentStatus(ref.fulfillmentRef);
+                if (isOffTrackFulfillmentStatus(localState)) {
                     result.offTrackSkips += 1;
                     continue;
                 }
@@ -71,14 +78,17 @@ 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) {
@@ -90,9 +100,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)
+                if (!offTrack && input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef))
                     await invoice(ref.fulfillmentRef);
                 continue;
             }
@@ -109,7 +120,7 @@ export async function reconcileFulfillmentObservations(input) {
                 if (exception.replayed)
                     result.replayed += 1;
                 result.exceptions += exception.replayed ? 0 : 1;
-                if (input.lifecycle.issueAccountingInvoice && state.handedOverAt)
+                if (input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef))
                     await invoice(ref.fulfillmentRef);
                 continue;
             }
@@ -119,7 +130,13 @@ export async function reconcileFulfillmentObservations(input) {
                 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 });
                 }
             }
@@ -144,8 +161,47 @@ export async function reconcileFulfillmentObservations(input) {
                 continue;
             result.ok = false;
             result.failures += 1;
-            result.reason ??= "reconciliation_local_operation_failed";
+            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) {
+    if (!Number.isSafeInteger(input.pageSize) || input.pageSize <= 0)
+        throw new Error("reconciliation_page_size_invalid");
+    const isPage = (value) => Number.isSafeInteger(value) && value >= 0;
+    const checkpoint = input.checkpoint;
+    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;
+    let pageRead = false;
+    const empty = () => ({ 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 : 502, ledgerStatus: result.ok ? "succeeded" : "failed", result,
+        metadata: { reconciliationPagination: { version: 1, page, pageSize: input.pageSize, nextPage } } };
 }

package/dist/fulfillment/providerStockSyncWorker.d.ts

@@ -1,4 +1,4 @@
-import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider } from "./contracts/index.js";
+import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, SyncCursor } from "./contracts/index.js";
 type Threshold = Parameters<FulfillmentStockSyncPort["resolveLowStockEvidence"]>[0]["activeThresholdKinds"][number];
 interface StockSyncResult {
     ok: boolean;
@@ -17,6 +17,10 @@ interface StockSyncResult {
     syncRunId: string;
     lastMovementOccurredAt: string | null;
     reason?: string;
+    rejected: number;
+    items: NonNullable<SyncCursor["items"]>[number][];
+    providerError?: NonNullable<SyncCursor["error"]>["providerError"];
+    refusal?: NonNullable<SyncCursor["refusal"]>;
 }
 export declare function runFulfillmentStockSyncWorker(input: {
     port: FulfillmentStockSyncPort;

package/dist/fulfillment/providerStockSyncWorker.js

@@ -7,6 +7,8 @@ export async function runFulfillmentStockSyncWorker(input) {
     const syncRunId = input.compatibility.syncRunId(now);
     const result = {
         ok: true,
+        rejected: 0,
+        items: [],
         checked: 0,
         updated: 0,
         mismatches: 0,
@@ -22,143 +24,219 @@ export async function runFulfillmentStockSyncWorker(input) {
         syncRunId,
         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,
-            syncRunId,
-        });
-    }
-    await input.port.recordCursor({
-        status: "running",
-        lastStockSyncedAt: null,
-        lastMovementOccurredAt: null,
-        continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
-        coverageGapSkus: [], refusal: null,
-    });
-    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 = [];
+    const alerts = [];
+    let stage = "cursor_read_failed";
+    let operationalReason;
+    let staleSync;
+    let recoverStaleSync = false;
+    let previousCursor = null;
+    let rejectedStockResponse = false;
     const currentCoverageGapSkus = new Set();
-    const packagingSkus = new Set();
-    const previousCoverageGapSkus = previousCursor?.status === "succeeded"
-        ? readStringSet(previousCursor.coverageGapSkus)
-        : new Set();
-    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,
+    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,
             });
-            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);
+        }
+        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 = [];
+        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 = [];
+        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);
             }
         }
-        catch (error) {
+        if (rejectedStockResponse || (result.rejected > 0 && stockItems.length + movements.length === 0)) {
             result.ok = false;
-            result.failures += 1;
-            result.reason = result.reason ?? "stock_sync_operation_failed";
+            result.reason = "invalid_sku_ref";
         }
-    }
-    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 = lowStockSignals.map((signal) => signal.thresholdKind);
-            if (currentCoverageGapSkus.has(stock.skuRef) && !activeThresholdKinds.includes("reservation_coverage")) {
-                activeThresholdKinds.push("reservation_coverage");
-            }
-            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,
+        result.movements = movements.length;
+        result.lastMovementOccurredAt = latestOccurredAt(movements);
+        const localBySku = aggregateAtpCompatibleStock(localStock, now);
+        const coverageCandidates = [];
+        const packagingSkus = new Set();
+        const previousCoverageGapSkus = previousCursor?.status === "succeeded"
+            ? readStringSet(previousCursor.coverageGapSkus)
+            : new Set();
+        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,
                 });
-                if (evidence.replayed)
+                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;
-                result.lowStock += evidence.replayed ? 0 : 1;
-                if (signal.thresholdKind === "reservation_coverage")
-                    result.reservationCoverage += 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 });
             }
-            await input.port.resolveLowStockEvidence({
-                skuRef: stock.skuRef,
-                activeThresholdKinds,
-                syncRunId,
-            });
         }
-        for (const sku of packagingSkus) {
-            await input.port.resolveLowStockEvidence({
-                skuRef: sku,
-                activeThresholdKinds: [],
-                syncRunId,
-            });
+        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 = 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",
+        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;
 }
@@ -184,3 +262,34 @@ function latestOccurredAt(movements) {
         .filter((value) => 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, operation) {
+    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) {
+    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) {
+    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/dist/fulfillment/providerTrackingReferences.d.ts

@@ -1,10 +1,11 @@
-import type { FulfillmentTrackingReference } from "./contracts/index.js";
+import type { FulfillmentTrackingReference, FulfillmentObservationCodecs } from "./contracts/index.js";
 export declare function trackingReferenceComplete(ref: FulfillmentTrackingReference): boolean;
 /** Provider evidence wins as a unit; private carrier/URL codecs stay injected. */
 export declare function enrichTrackingReference(ref: FulfillmentTrackingReference, deliveryCarrier: {
     carrierRef: string | null;
     serviceRef: string | null;
-} | null, codecs: {
+} | null, codecs: FulfillmentObservationCodecs & {
+    approveTrackingUrl?(url: string): boolean;
     normalizeCarrier(input: {
         carrierRef: string | null;
         serviceRef: string | null;