@openlup/platform 0.20.0 → 0.22.0

package/dist/fulfillment/providerDispatchWorker.d.ts

@@ -0,0 +1,31 @@
+import type { DispatchRecord, FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentStorePort } from "./contracts/index.js";
+export declare function runFulfillmentDispatchWorker(input: {
+    store: FulfillmentStorePort;
+    provider: FulfillmentDispatchPort | null;
+    listCandidates(limit: number): Promise<readonly FulfillmentDispatchRequest[]>;
+    /** Return the original host key bytes, without a new package prefix. */
+    keys: {
+        request(candidate: FulfillmentDispatchRequest): string;
+        mappedAttempt(requestKey: string, mappedAttemptIndex: number): string;
+        acceptance(fulfillmentRef: string): {
+            providerAttemptKey: string;
+            labelKey: string;
+        };
+    };
+    config: {
+        mode: DispatchRecord["mode"];
+        batchLimit: number;
+    };
+    now?: () => Date;
+}): Promise<{
+    ok: boolean;
+    skipped: boolean;
+    checked: number;
+    updated: number;
+    failures: number;
+    mode: "shadow" | "stage" | "live";
+    replayed: number;
+    providerCalls: number;
+    readBacks: number;
+    reason: string | undefined;
+}>;

package/dist/fulfillment/providerDispatchWorker.js

@@ -0,0 +1,172 @@
+import { acceptedProviderProof, dispatchEvidence, dispatchResult } from "./dispatchProjection.js";
+import { acknowledgeAcceptedDispatch, recoverDispatchAcceptanceWrite } from "./providerDispatchAcceptance.js";
+import { unknownDispatchFailure } from "./providerDispatchError.js";
+export async function runFulfillmentDispatchWorker(input) {
+    const result = { ok: true, skipped: false, checked: 0, updated: 0, failures: 0,
+        mode: input.config.mode, replayed: 0, providerCalls: 0, readBacks: 0, reason: undefined };
+    if (input.config.mode !== "shadow") {
+        try {
+            await input.store.markStaleSubmissionsUncertain(new Date((input.now?.() ?? new Date()).getTime() - 5 * 60_000).toISOString());
+        }
+        catch {
+            return { ...result, ok: false, failures: 1, reason: "dispatch_stale_submission_sweep_failed" };
+        }
+    }
+    const candidates = await input.listCandidates(input.config.batchLimit);
+    result.checked = candidates.length;
+    candidateLoop: for (const candidate of candidates) {
+        const requestKey = input.keys.request(candidate);
+        try {
+            let readBack = await input.store.read(requestKey);
+            if (readBack)
+                result.readBacks += 1;
+            if (acceptedProviderProof(readBack)) {
+                const ack = await acknowledgeAcceptedDispatch({ store: input.store, record: readBack, keys: input.keys.acceptance(candidate.fulfillmentRef) });
+                if (ack.replayed)
+                    result.replayed += 1;
+                result.updated += ack.replayed ? 0 : 1;
+                continue;
+            }
+            const preparation = await input.store.prepare(candidate.fulfillmentRef);
+            if (preparation.disposition === "withheld")
+                continue;
+            const preparedCandidate = await input.store.readCandidate(candidate.fulfillmentRef);
+            if (!preparedCandidate)
+                throw new Error("dispatch_prepared_candidate_missing");
+            if (input.config.mode !== "shadow" && !input.provider) {
+                result.ok = false;
+                result.failures += 1;
+                result.reason ??= "provider_not_configured";
+                continue;
+            }
+            // Shadow needs command preparation too, but never calls dispatch.
+            if (!input.provider)
+                throw new Error("provider_command_preparation_not_configured");
+            let mappedCandidate = preparedCandidate;
+            let dispatchRef;
+            let evidence;
+            let mappedAttemptCount = 0;
+            for (let remapCount = 0;; remapCount += 1) {
+                const request = { ...mappedCandidate, requestKey };
+                const prepared = await input.provider.prepare(request);
+                if (prepared.kind === "refused") {
+                    result.ok = false;
+                    result.failures += 1;
+                    result.reason ??= prepared.refusal.reason;
+                    continue candidateLoop;
+                }
+                evidence = dispatchEvidence(prepared.evidence);
+                const claim = await input.store.claim({ requestKey, fulfillmentRef: mappedCandidate.fulfillmentRef,
+                    orderRef: mappedCandidate.orderRef, parcelRef: mappedCandidate.parcelRef, mode: input.config.mode, evidence });
+                if (claim.kind === "refused") {
+                    if (remapCount === 0 && claim.refusal.reason === "contact_stale") {
+                        const refreshed = await input.store.readCandidate(candidate.fulfillmentRef);
+                        if (!refreshed)
+                            throw new Error("dispatch_contact_remap_candidate_missing");
+                        mappedCandidate = refreshed;
+                        continue;
+                    }
+                    result.ok = false;
+                    result.failures += 1;
+                    result.reason ??= claim.refusal.reason;
+                    continue candidateLoop;
+                }
+                dispatchRef = claim.record;
+                if (dispatchRef.replayed)
+                    result.replayed += 1;
+                // Re-claim may refresh a correctable draft atomically; readback is authoritative.
+                readBack = await input.store.read(requestKey);
+                if (readBack)
+                    result.readBacks += 1;
+                if (!readBack || readBack.fulfillmentRef !== mappedCandidate.fulfillmentRef)
+                    throw new Error("dispatch_readback_failed");
+                await input.store.recordProviderAttempt(input.keys.mappedAttempt(requestKey, mappedAttemptCount), mappedCandidate.fulfillmentRef, evidence, input.config.mode, "recorded");
+                mappedAttemptCount += 1;
+                if (input.config.mode === "shadow") {
+                    result.updated += dispatchRef.replayed ? 0 : 1;
+                    continue candidateLoop;
+                }
+                if (readBack.status !== "draft") {
+                    result.ok = false;
+                    result.failures += 1;
+                    result.reason ??= `dispatch_not_safe_to_submit:${readBack.status}`;
+                    continue candidateLoop;
+                }
+                const submission = await input.store.begin({ dispatchRef: dispatchRef.dispatchRef, commandFingerprint: evidence.commandFingerprint });
+                if (submission.kind === "refused") {
+                    if (remapCount === 0 && submission.refusal.reason === "contact_stale") {
+                        const refreshed = await input.store.readCandidate(candidate.fulfillmentRef);
+                        if (!refreshed)
+                            throw new Error("dispatch_contact_remap_candidate_missing");
+                        mappedCandidate = refreshed;
+                        continue;
+                    }
+                    result.ok = false;
+                    result.failures += 1;
+                    result.reason ??= submission.refusal.reason;
+                    continue candidateLoop;
+                }
+                if (!submission.begun) {
+                    const concurrent = await input.store.read(requestKey);
+                    if (concurrent)
+                        result.readBacks += 1;
+                    if (acceptedProviderProof(concurrent)) {
+                        const ack = await acknowledgeAcceptedDispatch({ store: input.store, record: concurrent, keys: input.keys.acceptance(mappedCandidate.fulfillmentRef) });
+                        if (ack.replayed)
+                            result.replayed += 1;
+                        result.updated += ack.replayed ? 0 : 1;
+                    }
+                    else {
+                        result.replayed += 1;
+                    }
+                    continue candidateLoop;
+                }
+                if (submission.record.status !== "submitting")
+                    throw new Error("dispatch_submission_state_invalid");
+                break;
+            }
+            result.providerCalls += 1;
+            let response;
+            try {
+                response = dispatchResult(await input.provider.dispatch({ ...mappedCandidate, requestKey }, evidence));
+            }
+            catch {
+                response = unknownDispatchFailure();
+            }
+            if (response.kind !== "accepted") {
+                await input.store.finalize({ dispatchRef: dispatchRef.dispatchRef, result: response });
+                result.ok = false;
+                result.failures += 1;
+                result.reason ??= response.refusal.reason;
+                continue;
+            }
+            // All ACK paths use the original host keys, ignoring adapter key fields.
+            const acceptance = { ...response, ...input.keys.acceptance(mappedCandidate.fulfillmentRef) };
+            try {
+                const ack = await input.store.acknowledge({ dispatchRef: dispatchRef.dispatchRef, acceptance });
+                if (ack.replayed)
+                    result.replayed += 1;
+            }
+            catch {
+                const recovery = await recoverDispatchAcceptanceWrite({ store: input.store, requestKey, dispatchRef: dispatchRef.dispatchRef, acceptance });
+                result.readBacks += recovery.readBacks;
+                if (recovery.committed) {
+                    result.updated += 1;
+                    continue;
+                }
+                result.ok = false;
+                result.failures += 1;
+                result.reason ??= "dispatch_proof_write_failed_after_provider_acceptance";
+                break;
+            }
+            result.updated += 1;
+        }
+        catch {
+            // Exception messages may contain raw provider bodies or credentials.
+            result.ok = false;
+            result.failures += 1;
+            result.reason ??= "dispatch_local_operation_failed";
+        }
+    }
+    return result;
+}

package/dist/fulfillment/providerProductSyncWorker.d.ts

@@ -0,0 +1,28 @@
+import type { FulfillmentProductSyncPort, FulfillmentProductSyncProvider } from "./contracts/index.js";
+type ReconciliationConflict = Parameters<FulfillmentProductSyncPort["recordReconciliationEvidence"]>[0]["conflictKind"];
+type SyncIdentity = Parameters<FulfillmentProductSyncPort["recordReconciliationEvidence"]>[0]["identity"];
+interface ProductSyncResult {
+    ok: boolean;
+    pushedProducts: number;
+    pushedPacks: number;
+    skippedProducts: number;
+    pulledSkus: number;
+    ingestedPacks: number;
+    reconciliations: number;
+    replayed: number;
+    failures: number;
+    providerCalls: number;
+    syncRunId: string;
+    reason?: string;
+}
+export declare function runFulfillmentProductSyncWorker(input: {
+    port: FulfillmentProductSyncPort;
+    provider: FulfillmentProductSyncProvider;
+    mode?: "push" | "pull" | "both";
+    now?: () => Date;
+    compatibility: {
+        identity(now: Date): SyncIdentity;
+        evidenceKey(sku: string, ean: string, kind: ReconciliationConflict): string;
+    };
+}): Promise<ProductSyncResult>;
+export {};

package/dist/fulfillment/providerProductSyncWorker.js

@@ -0,0 +1,122 @@
+function packKindForQuantity(quantity) {
+    return quantity > 1 ? "collective" : "unit";
+}
+function reconciliationKindFor(conflict) {
+    switch (conflict) {
+        case "sku_not_found":
+            return "unknown_sku";
+        case "ean_owned_by_other_sku":
+            return "ean_conflict";
+        case "local_locked_mismatch":
+            return "kind_quantity_conflict";
+        default:
+            return null;
+    }
+}
+export async function runFulfillmentProductSyncWorker(input) {
+    const now = input.now?.() ?? new Date();
+    const mode = input.mode ?? "both";
+    const identity = input.compatibility.identity(now);
+    const syncRunId = identity.syncRunId;
+    const result = {
+        ok: true,
+        pushedProducts: 0,
+        pushedPacks: 0,
+        skippedProducts: 0,
+        pulledSkus: 0,
+        ingestedPacks: 0,
+        reconciliations: 0,
+        replayed: 0,
+        failures: 0,
+        providerCalls: 0,
+        syncRunId,
+    };
+    if (mode === "push" || mode === "both")
+        await runPush(input, result);
+    if (mode === "pull" || mode === "both")
+        await runPull(input, result, identity);
+    return result;
+}
+async function runPush(input, result) {
+    const localProducts = await input.port.listLocalProductPacks();
+    for (const product of localProducts) {
+        try {
+            const ensured = await input.provider.ensureProduct(product.sku);
+            result.providerCalls += 1;
+            if (ensured === null) {
+                result.skippedProducts += 1;
+                continue;
+            }
+            result.pushedProducts += ensured.replayed ? 0 : 1;
+            if (ensured.replayed)
+                result.replayed += 1;
+            const existingEans = new Set((await input.provider.getProductPacks(product.sku)).map((pack) => pack.ean));
+            result.providerCalls += 1;
+            for (const pack of product.packs) {
+                if (existingEans.has(pack.ean))
+                    continue;
+                await input.provider.addProductPack(product.sku, { ean: pack.ean, quantity: pack.quantity });
+                result.providerCalls += 1;
+                await input.port.markPackSynced({ sku: product.sku, ean: pack.ean });
+                result.pushedPacks += 1;
+            }
+        }
+        catch (error) {
+            result.ok = false;
+            result.failures += 1;
+            result.reason = result.reason ?? "product_sync_operation_failed";
+        }
+    }
+}
+async function runPull(input, result, identity) {
+    const syncRunId = identity.syncRunId;
+    const skus = await input.provider.listStockedSkus();
+    result.providerCalls += 1;
+    for (const sku of skus.filter((value) => value.trim())) {
+        try {
+            const providerPacks = await input.provider.getProductPacks(sku);
+            result.providerCalls += 1;
+            result.pulledSkus += 1;
+            const activeConflicts = new Set();
+            for (const pack of providerPacks.filter((entry) => entry.ean.trim())) {
+                const upsert = await input.port.upsertPulledPack({
+                    sku,
+                    ean: pack.ean,
+                    quantity: pack.quantity,
+                    kind: packKindForQuantity(pack.quantity),
+                });
+                const conflictKind = reconciliationKindFor(upsert.conflict);
+                if (conflictKind === null) {
+                    if (!upsert.replayed)
+                        result.ingestedPacks += 1;
+                    else
+                        result.replayed += 1;
+                    continue;
+                }
+                activeConflicts.add(conflictKind);
+                const evidence = await input.port.recordReconciliationEvidence({
+                    requestKey: input.compatibility.evidenceKey(sku, pack.ean, conflictKind),
+                    sku,
+                    ean: pack.ean,
+                    conflictKind,
+                    providerQuantity: pack.quantity,
+                    identity, refusal: null,
+                });
+                if (evidence.replayed)
+                    result.replayed += 1;
+                else
+                    result.reconciliations += 1;
+            }
+            await input.port.resolveReconciliationEvidence({
+                sku,
+                activeConflictKinds: [...activeConflicts],
+                syncRunId,
+            });
+        }
+        catch (error) {
+            result.ok = false;
+            result.failures += 1;
+            result.reason = result.reason ?? "product_sync_operation_failed";
+        }
+    }
+}

package/dist/fulfillment/providerReconciliationError.d.ts

@@ -0,0 +1,9 @@
+import type { FulfillmentObservation } from "./contracts/index.js";
+/** Host decoding supplies known domain reasons, never a raw provider error message. */
+export declare function quarantineReconciliationStateConflict(error: unknown, observation: FulfillmentObservation, classify: (error: unknown) => "fulfillment_not_found" | "stock_consumed_requires_label" | null, record: (observation: FulfillmentObservation, reason: "state_conflict", detail: "fulfillment_not_found" | "stock_consumed_requires_label") => Promise<{
+    replayed: boolean;
+}>, result: {
+    quarantined: number;
+    replayed: number;
+    stateConflicts: number;
+}): Promise<unknown | null>;

package/dist/fulfillment/providerReconciliationError.js

@@ -0,0 +1,17 @@
+/** Host decoding supplies known domain reasons, never a raw provider error message. */
+export async function quarantineReconciliationStateConflict(error, observation, classify, record, result) {
+    const reason = classify(error);
+    if (!reason)
+        return error;
+    try {
+        const quarantine = await record(observation, "state_conflict", reason);
+        if (quarantine.replayed)
+            result.replayed += 1;
+        result.quarantined += quarantine.replayed ? 0 : 1;
+        result.stateConflicts += 1;
+        return null;
+    }
+    catch (quarantineError) {
+        return quarantineError;
+    }
+}

package/dist/fulfillment/providerReconciliationTerminalSkip.d.ts

@@ -0,0 +1,2 @@
+/** Off-track rows still write evidence; acceptance and all effects must skip. */
+export declare function isOffTrackFulfillmentStatus(status: string | null | undefined): boolean;

package/dist/fulfillment/providerReconciliationTerminalSkip.js

@@ -0,0 +1,6 @@
+import { FULFILLMENT_STATUS_MAP } from "./statusMap.js";
+const OFF_TRACK_FULFILLMENT_STATUSES = new Set(FULFILLMENT_STATUS_MAP.stages.filter(stage => !stage.onTrack).flatMap(stage => stage.omsFulfillmentStatus));
+/** Off-track rows still write evidence; acceptance and all effects must skip. */
+export function isOffTrackFulfillmentStatus(status) {
+    return status !== null && status !== undefined && OFF_TRACK_FULFILLMENT_STATUSES.has(status);
+}

package/dist/fulfillment/providerReconciliationTimestamp.d.ts

@@ -0,0 +1 @@
+export declare function normalizeReconciliationTimestamp(value: string | null | undefined): string | null;

package/dist/fulfillment/providerReconciliationTimestamp.js

@@ -0,0 +1,27 @@
+const ISO_TIMESTAMP_WITH_EXPLICIT_ZONE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):?(\d{2}))$/;
+export function normalizeReconciliationTimestamp(value) {
+    const occurredAt = value?.trim();
+    if (!occurredAt)
+        return null;
+    const match = ISO_TIMESTAMP_WITH_EXPLICIT_ZONE.exec(occurredAt);
+    if (!match || !Number.isFinite(Date.parse(occurredAt)))
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    const offsetHour = match[7] === undefined ? 0 : Number(match[7]);
+    const offsetMinute = match[8] === undefined ? 0 : Number(match[8]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = month === 2
+        ? leapYear ? 29 : 28
+        : [4, 6, 9, 11].includes(month) ? 30 : 31;
+    if (month < 1 || month > 12
+        || day < 1 || day > daysInMonth
+        || hour > 23 || minute > 59 || second > 59
+        || offsetHour > 23 || offsetMinute > 59)
+        return null;
+    return occurredAt;
+}

package/dist/fulfillment/providerReconciliationWorker.d.ts

@@ -0,0 +1,82 @@
+import type { FulfillmentObservation, FulfillmentReadbackResult } from "./contracts/index.js";
+import { enrichTrackingReference } from "./providerTrackingReferences.js";
+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 {
+    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;
+    invoiceIssueRefusals: {
+        fulfillmentRef: string;
+        identifier: string | null;
+        sqlstate: string;
+        benign: boolean;
+    }[];
+    providerCalls: number;
+    readBacks: number;
+    skipped: boolean;
+    reason?: string;
+}
+export declare 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;
+    })[]>;
+    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;
+        }>;
+    };
+    lifecycle: Pick<Ingress["lifecycle"], "recordStatusEvidence" | "effects" | "keys"> & {
+        findDispatchRef(evidence: PollEvidence): Promise<DispatchRef | null>;
+        acknowledgeDispatchAcceptance(ref: DispatchRef, evidence: PollEvidence): Promise<void>;
+        recordQuarantine(observation: PollEvidence | null, reason: "missing_correlation" | "missing_external_ref" | "unknown_status" | "state_conflict", detail?: "fulfillment_not_found" | "stock_consumed_requires_label"): Promise<{
+            replayed: boolean;
+        }>;
+        recordProviderException(ref: DispatchRef, observation: FulfillmentObservation): Promise<{
+            replayed: boolean;
+        }>;
+        readDeliveryCarrier(ref: string): Promise<{
+            carrierRef: string | null;
+            serviceRef: string | null;
+        } | null>;
+        trackingCodecs: Parameters<typeof enrichTrackingReference>[2];
+        issueAccountingInvoice?(ref: string): Promise<void>;
+        /** Private RPC decoding retains permanent/benign distinction and safe refusal identity. */
+        invoiceFailure(error: unknown): {
+            permanent: boolean;
+            identifier: string | null;
+            sqlstate: string | null;
+            benign: boolean;
+        };
+        classifyStateConflict(error: unknown): "fulfillment_not_found" | "stock_consumed_requires_label" | null;
+    };
+}): Promise<ReconciliationResult>;
+export {};

package/dist/fulfillment/providerReconciliationWorker.js

@@ -0,0 +1,151 @@
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+import { observationStatusPolicy, projectCorrelation, projectObservation } 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 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;
+    // 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);
+        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;
+                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";
+                return;
+            }
+            result.ok = false;
+            result.failures += 1;
+            result.invoiceIssueFailures += 1;
+            result.reason ??= "reconciliation_invoice_issue_failed";
+        }
+    };
+    for (const readback of page) {
+        let observation = null;
+        try {
+            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 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;
+                }
+                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);
+            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);
+            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;
+            if (state.latestStatusOccurredAt && occurredAt && Date.parse(occurredAt) < Date.parse(state.latestStatusOccurredAt)) {
+                result.stale += 1;
+                if (!offTrack && input.lifecycle.issueAccountingInvoice && state.handedOverAt)
+                    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 && state.handedOverAt)
+                    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 enriched = enrichTrackingReference(tracking, carrier ?? null, input.lifecycle.trackingCodecs);
+                    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 ??= "reconciliation_local_operation_failed";
+        }
+    }
+    return result;
+}