@openlup/platform 0.21.0 → 0.23.0

package/dist/fulfillment/providerReconciliationWorker.js

@@ -0,0 +1,207 @@
+import { durableStrings, localFailureReason, safeDiagnosticCode, operationError } from "./dispatchProjection.js";
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.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,
+        invoiceIssueRefusals: [], providerCalls: 0, readBacks: 0, skipped: false,
+    };
+    const page = await input.readPage({ page: input.page ?? 0, size: input.batchSize });
+    result.providerCalls += 1;
+    result.checked = page.length;
+    const quarantine = async (observation, reason) => {
+        const evidence = await input.lifecycle.recordQuarantine(observation, reason);
+        if (evidence.replayed)
+            result.replayed += 1;
+        result.quarantined += evidence.replayed ? 0 : 1;
+    };
+    const invoice = async (ref) => {
+        try {
+            await input.lifecycle.issueAccountingInvoice?.(ref);
+        }
+        catch (error) {
+            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, 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 ??= 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 = projectPollEvidence(readback.evidence);
+                const ref = await input.lifecycle.findDispatchRef(evidence);
+                if (!ref) {
+                    await quarantine(evidence, "missing_correlation");
+                    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");
+                continue;
+            }
+            if (readback.kind !== "found") {
+                // Neither unsupported nor a provider absence is a local transition.
+                continue;
+            }
+            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 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;
+                }
+                await input.lifecycle.acknowledgeDispatchAcceptance(ref, observation);
+            }
+            const occurredAt = normalizeReconciliationTimestamp(readback.updatedAt);
+            const localStatus = observation.fact.canonicalStatus;
+            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 && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef))
+                    await invoice(ref.fulfillmentRef);
+                continue;
+            }
+            // The normalized fact carries the same nullable occurrence used by dedupe.
+            observation = { ...observation, fact: { ...observation.fact, occurredAt } };
+            const status = await input.lifecycle.recordStatusEvidence(ref, observation);
+            if (status.replayed)
+                result.replayed += 1;
+            if (offTrack)
+                continue;
+            result.updated += status.replayed ? 0 : 1;
+            if (localStatus === "exception") {
+                const exception = await input.lifecycle.recordProviderException(ref, observation);
+                if (exception.replayed)
+                    result.replayed += 1;
+                result.exceptions += exception.replayed ? 0 : 1;
+                if (input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef))
+                    await invoice(ref.fulfillmentRef);
+                continue;
+            }
+            const trackingRefs = [];
+            if (observationStatusPolicy.handsOver(localStatus)) {
+                let carrier;
+                for (const tracking of uniqueTrackingReferences(observation.trackingRefs)) {
+                    if (!trackingReferenceComplete(tracking) && carrier === undefined)
+                        carrier = await input.lifecycle.readDeliveryCarrier(ref.fulfillmentRef);
+                    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 });
+                }
+            }
+            await applyFulfillmentObservationEffects({
+                port: input.lifecycle.effects, localStatus, ids: { orderId: ref.orderRef, fulfillmentOrderId: ref.fulfillmentRef }, observation,
+                trackingRefs, 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 ? () => invoice(ref.fulfillmentRef) : undefined,
+                onReplayed: () => { result.replayed += 1; },
+                onTrackingRecorded: tracking => {
+                    if (tracking.replayed)
+                        result.replayed += 1;
+                    if (tracking.readBack)
+                        result.readBacks += 1;
+                    result.trackingRefs += tracking.replayed ? 0 : 1;
+                },
+            }, observationStatusPolicy);
+        }
+        catch (caught) {
+            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 ??= 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) };
+    }
+    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/providerStockAvailability.d.ts

@@ -0,0 +1,13 @@
+import type { FulfillmentStockSyncPort, LocalStock } from "./contracts/index.js";
+type StockLine = Awaited<ReturnType<FulfillmentStockSyncPort["readLocalInventoryStock"]>>[number];
+export declare function aggregateAtpCompatibleStock(lines: readonly StockLine[], now: Date): Map<string, LocalStock>;
+/** Cap the host-local movement window at UTC today, preserving donor overlap. */
+export declare function stockMovementWindow(cursor: {
+    lastMovementOccurredAt: string | null;
+    lastStockSyncedAt: string | null;
+} | null, now: Date, timeZone: string): {
+    startLocalDate: string;
+    endLocalDate: string;
+};
+export declare function emptyLocal(sku: string): LocalStock;
+export {};

package/dist/fulfillment/providerStockAvailability.js

@@ -0,0 +1,51 @@
+export function aggregateAtpCompatibleStock(lines, now) {
+    const requestedAt = now.toISOString();
+    const balances = new Map();
+    for (const line of lines.filter((item) => isAtpUsable(item, requestedAt))) {
+        const current = balances.get(line.skuRef) ?? emptyLocal(line.skuRef);
+        current.onHand += line.quantity.onHand;
+        current.reserved += line.quantity.reserved;
+        current.unavailable += line.quantity.unavailable;
+        current.safetyStock += line.quantity.safetyStock;
+        balances.set(line.skuRef, current);
+    }
+    return balances;
+}
+/** Cap the host-local movement window at UTC today, preserving donor overlap. */
+export function stockMovementWindow(cursor, now, timeZone) {
+    const startAt = new Date(cursor?.lastMovementOccurredAt ?? cursor?.lastStockSyncedAt ?? now.toISOString());
+    const safeStartAt = Number.isNaN(startAt.getTime()) ? now : startAt;
+    const endLocalDate = minDate(localDate(now, timeZone), utcDate(now));
+    return {
+        startLocalDate: minDate(localDate(safeStartAt, timeZone), endLocalDate),
+        endLocalDate,
+    };
+}
+function utcDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+function minDate(a, b) {
+    return a <= b ? a : b;
+}
+function isAtpUsable(line, requestedAt) {
+    if (!line.fulfillable || line.locationStatus !== "active")
+        return false;
+    if (line.lotStatus && line.lotStatus !== "available")
+        return false;
+    if (line.expiresAt && Date.parse(line.expiresAt) <= Date.parse(requestedAt))
+        return false;
+    return true;
+}
+export function emptyLocal(sku) {
+    return { skuRef: sku, onHand: 0, reserved: 0, unavailable: 0, safetyStock: 0 };
+}
+function localDate(date, timeZone) {
+    const parts = new Intl.DateTimeFormat("en", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(date);
+    const byType = new Map(parts.map((part) => [part.type, part.value]));
+    return `${byType.get("year")}-${byType.get("month")}-${byType.get("day")}`;
+}

package/dist/fulfillment/providerStockSyncWorker.d.ts

@@ -0,0 +1,41 @@
+import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, 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 declare 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>;
+export {};

package/dist/fulfillment/providerStockSyncWorker.js

@@ -0,0 +1,295 @@
+import { aggregateAtpCompatibleStock, emptyLocal, stockMovementWindow } from "./providerStockAvailability.js";
+export async function runFulfillmentStockSyncWorker(input) {
+    const now = input.now?.() ?? new Date();
+    const staleThresholdHours = input.staleSyncThresholdHours && input.staleSyncThresholdHours > 0
+        ? input.staleSyncThresholdHours
+        : 6;
+    const syncRunId = input.compatibility.syncRunId(now);
+    const result = {
+        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 = [];
+    let stage = "cursor_read_failed";
+    let operationalReason;
+    let staleSync;
+    let recoverStaleSync = false;
+    let previousCursor = null;
+    let rejectedStockResponse = false;
+    const currentCoverageGapSkus = new Set();
+    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 = [];
+        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);
+            }
+        }
+        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 = [];
+        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,
+                });
+                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 = 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, local, activeReserved, confirmedCoverageGap) {
+    const signals = [];
+    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) {
+    return new Set(Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : []);
+}
+function availableQuantity(balance) {
+    return Math.max(0, balance.onHand - balance.reserved - balance.unavailable - balance.safetyStock);
+}
+function latestOccurredAt(movements) {
+    return movements
+        .map((movement) => movement.occurredAt)
+        .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

@@ -0,0 +1,16 @@
+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: FulfillmentObservationCodecs & {
+    approveTrackingUrl?(url: string): boolean;
+    normalizeCarrier(input: {
+        carrierRef: string | null;
+        serviceRef: string | null;
+    }): string | null;
+    publicUrl(carrierRef: string | null, trackingNumber: string): string | null;
+}): FulfillmentTrackingReference;
+/** First occurrence wins, including its selection, after trimming the number. */
+export declare function uniqueTrackingReferences(refs: readonly FulfillmentTrackingReference[]): FulfillmentTrackingReference[];

package/dist/fulfillment/providerTrackingReferences.js

@@ -0,0 +1,23 @@
+export function trackingReferenceComplete(ref) {
+    return Boolean(ref.carrierRef && ref.publicUrl && ref.serviceRef);
+}
+/** Provider evidence wins as a unit; private carrier/URL codecs stay injected. */
+export function enrichTrackingReference(ref, deliveryCarrier, codecs) {
+    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) {
+    const seen = new Set();
+    const result = [];
+    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/dist/fulfillment/replacementRefusals.d.ts

@@ -0,0 +1,5 @@
+export declare const FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS: readonly ["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"];
+export declare const FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS: readonly ["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"];
+export declare const UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL = "unspecified_refusal";
+export declare const FULFILLMENT_REPLACEMENT_REFUSALS: readonly ["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", "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", "unspecified_refusal"];
+export type FulfillmentReplacementRefusal = (typeof FULFILLMENT_REPLACEMENT_REFUSALS)[number];