@openlup/platform 0.22.0 → 0.24.0

package/dist/fulfillment/omnipack/reconciliation.js

@@ -0,0 +1,55 @@
+import { operationError } from "../dispatchProjection.js";
+import { projectPollEvidence, projectObservation } from "../observationProjection.js";
+import { normalizeReconciliationTimestamp } from "../providerReconciliationTimestamp.js";
+import { OmnipackProviderError } from "./client.js";
+import { digest, observation, reference, refusal, timestamp } from "./observation.js";
+import { localStatusFor, normalizeStatus } from "./omnipackStatusVocabulary.js";
+export function reconciliationObservation(row, config, fulfillmentRef) {
+    const providerStatus = { primary: row.status, subStatus: row.subStatus };
+    // Original status and occurrence bytes remain part of identity, even for aliases
+    // mapping to the same canonical event. Received time never changes that identity.
+    const eventKey = digest(JSON.stringify([row.providerOrderId, row.fulfilmentNumber, row.orderNumber, row.status, row.subStatus, row.updatedAt]));
+    const correlation = { orderRef: null, fulfillmentRef: fulfillmentRef ?? null, externalRef: reference(row.providerOrderId),
+        orderNumber: reference(row.orderNumber), providerFulfillmentRef: reference(row.fulfilmentNumber), parcelRef: null };
+    const normalized = normalizeStatus(row.status);
+    if (!normalized)
+        return { kind: "unmapped", externalRef: correlation.externalRef, evidence: projectPollEvidence({ eventKey, correlation: { ...correlation, externalRef: row.providerOrderId, orderNumber: row.orderNumber, providerFulfillmentRef: row.fulfilmentNumber }, providerStatus }) };
+    const status = localStatusFor(normalized);
+    const event = { provider_received: "shipment.accepted", picking: "order.processing_started", packed: "order.picked", in_transit: "order.shipped", delivered: "order.delivered", exception: "parcel.exception" }[status];
+    const occurredAt = normalizeReconciliationTimestamp(row.updatedAt);
+    const evidence = { provider: "omnipack", event, providerOrderId: row.providerOrderId, orderNumber: row.orderNumber,
+        fulfilmentNumber: row.fulfilmentNumber, occurredAt, trackingNumbers: row.trackingNumbers,
+        trackingReferences: row.trackingReferences, shippingMethods: [] };
+    const mapped = observation({ evidence, event, status, fulfillmentRef, receivedAt: config.clock(),
+        rawDigest: digest(JSON.stringify({ ...evidence, providerStatus })), evidenceRef: config.mintEvidenceReference(), source: "provider_reconciliation", approveTrackingUrl: config.approveTrackingUrl, observationCodecs: config.observationCodecs });
+    return { kind: "found", externalRef: row.providerOrderId ?? "", createdAt: timestamp(row.createdAt), updatedAt: timestamp(occurredAt),
+        observation: projectObservation({ ...mapped, eventKey, fact: { ...mapped.fact, factId: eventKey }, providerStatus }, config.approveTrackingUrl, config.observationCodecs) };
+}
+export function createReconciliationPagePort(client, config, ready) {
+    return {
+        async readPage(input) {
+            const inactive = ready();
+            if (inactive)
+                return { kind: "failed", refusal: inactive };
+            if (!Number.isSafeInteger(input.page) || input.page < 0 || !Number.isSafeInteger(input.size) || input.size <= 0)
+                return { kind: "failed", refusal: refusal("malformed", "readback") };
+            try {
+                const rows = await client.getFulfilments(input);
+                return { kind: "page", rows: rows.map(row => {
+                        try {
+                            return reconciliationObservation(row, config);
+                        }
+                        catch {
+                            return { kind: "unknown", refusal: refusal("malformed", "normalize") };
+                        }
+                    }) };
+            }
+            catch (error) {
+                if (error instanceof OmnipackProviderError && error.status === 400 && error.code === "ERR_PAGE_MUST_BE_LESS_THAN_TOTAL_PAGES")
+                    return { kind: "page_exhausted" };
+                return { kind: "failed", refusal: refusal("io_failure", "readback", error instanceof OmnipackProviderError && error.retryable),
+                    error: operationError(error instanceof OmnipackProviderError ? error : { code: "provider_read_failed", status: null, retryable: false, mayHaveSucceeded: false }) };
+            }
+        },
+    };
+}

package/dist/fulfillment/postgresDispatchStore.js

@@ -10,7 +10,7 @@ export function createPostgresFulfillmentDispatchStore(db, host) {
         readCandidate: ref => host.readCandidate(ref),
         prepare: ref => host.prepare(ref),
         async read(key) {
-            const result = await db.query('SELECT public.fulfillment_dispatch_read(ref) AS response FROM public.fulfillment_dispatch_refs ref WHERE request_key=$1', [key]);
+            const result = await db.query("SELECT public.fulfillment_dispatch_read(ref) || jsonb_build_object('acceptance',ref.acceptance) AS response FROM public.fulfillment_dispatch_refs ref WHERE request_key=$1", [key]);
             return result.rows[0]?.response ?? null;
         },
         claim: input => nativeCall(db, 'fulfillment_dispatch_claim', [input.requestKey, input.fulfillmentRef, input.orderRef, input.parcelRef, input.mode, JSON.stringify(dispatchEvidence(input.evidence))]),

package/dist/fulfillment/postgresShipmentSpine.d.ts

@@ -1,3 +1,4 @@
+import type { FulfillmentObservationCodecs } from "./contracts/index.js";
 import type { PgExecutor as PgQueryExecutor } from './postgresDispatchStore.js';
 interface ShipmentSpineResult {
     shipmentId: string;
@@ -33,6 +34,8 @@ interface ShipmentSpineMutationPort {
 }
 export interface PostgresFulfillmentShipmentSpineOptions {
     portKey: string;
+    approveTrackingUrl?(url: string): boolean;
+    observationCodecs?: FulfillmentObservationCodecs;
     evidenceChannel?: "poll" | "push";
     requiredProviderType?: "simulator";
 }
@@ -41,12 +44,15 @@ export declare function createPostgresFulfillmentShipmentSpinePort(executor: PgQ
     localPersistence: ReturnType<typeof localPersistence>;
 };
 /** G17 native local persistence, composed on the same injected executor. */
-declare function localPersistence(executor: PgQueryExecutor): {
+declare function localPersistence(executor: PgQueryExecutor, approveTrackingUrl?: (url: string) => boolean, observationCodecs?: FulfillmentObservationCodecs): {
     readLocalFulfillmentState(ref: string): Promise<{
         status: string | null;
         latestStatusOccurredAt: string | null;
         handedOverAt: string | null;
     }>;
+    readLocalFulfillmentStatus(ref: string): Promise<string | null>;
+    latestStatusOccurredAt(ref: string): Promise<string | null>;
+    readHandedOverAt(ref: string): Promise<string | null>;
     recordObservation(observation: import("./contracts/index.js").FulfillmentObservation): Promise<{
         replayed: boolean;
     }>;
@@ -58,6 +64,7 @@ declare function localPersistence(executor: PgQueryExecutor): {
     markProcessed(eventKey: string, outcome: {
         status: "processed" | "ignored";
         refusal?: import("./contracts/index.js").FulfillmentRefusal;
+        supersededCause?: string;
     }): Promise<void>;
 };
 export {};

package/dist/fulfillment/postgresShipmentSpine.js

@@ -1,3 +1,4 @@
+import { safeDiagnosticCode } from "./dispatchProjection.js";
 import { nativeCall } from './postgresDispatchStore.js';
 import { projectObservation } from './observationProjection.js';
 class CommerceFulfillmentConflictError extends Error {
@@ -83,7 +84,7 @@ export function createPostgresFulfillmentShipmentSpinePort(executor, options) {
         ]);
     };
     return {
-        localPersistence: localPersistence(executor),
+        localPersistence: localPersistence(executor, options.approveTrackingUrl, options.observationCodecs),
         createShipment(request) {
             return callCreate(executor, portKey, [
                 request.idempotencyKey,
@@ -207,7 +208,7 @@ function asRecord(value) {
         : null;
 }
 /** G17 native local persistence, composed on the same injected executor. */
-function localPersistence(executor) {
+function localPersistence(executor, approveTrackingUrl, observationCodecs) {
     return {
         async readLocalFulfillmentState(ref) {
             const result = await executor.query(`SELECT shipment.status,shipment.handed_over_at,
@@ -216,8 +217,20 @@ function localPersistence(executor) {
             const row = result.rows[0];
             return { status: typeof row?.status === 'string' ? row.status : null, latestStatusOccurredAt: date(row?.latest_status_occurred_at), handedOverAt: date(row?.handed_over_at) };
         },
+        async readLocalFulfillmentStatus(ref) {
+            const result = await executor.query('SELECT status FROM public.fulfillment_shipments WHERE id=$1::uuid', [ref]);
+            return typeof result.rows[0]?.status === 'string' ? result.rows[0].status : null;
+        },
+        async latestStatusOccurredAt(ref) {
+            const result = await executor.query("SELECT max((observation#>>'{fact,occurredAt}')::timestamptz) AS latest_status_occurred_at FROM public.fulfillment_observations WHERE shipment_id=$1::uuid AND status_recorded", [ref]);
+            return date(result.rows[0]?.latest_status_occurred_at);
+        },
+        async readHandedOverAt(ref) {
+            const result = await executor.query('SELECT handed_over_at FROM public.fulfillment_shipments WHERE id=$1::uuid', [ref]);
+            return date(result.rows[0]?.handed_over_at);
+        },
         async recordObservation(observation) {
-            const safe = projectObservation(observation);
+            const safe = projectObservation(observation, approveTrackingUrl, observationCodecs);
             return nativeCall(executor, 'fulfillment_record_observation', [safe.eventKey, safe.correlation.fulfillmentRef, JSON.stringify(safe), safe.firstReceivedAt]);
         },
         async recordStatusEvidence(ref, observation) {
@@ -225,6 +238,7 @@ function localPersistence(executor) {
         },
         async markProcessed(eventKey, outcome) {
             await nativeCall(executor, 'fulfillment_mark_observation_processed', [eventKey, JSON.stringify({ status: outcome.status,
+                    ...(outcome.supersededCause ? { supersededCause: safeDiagnosticCode(outcome.supersededCause) ?? 'fulfillment_state_conflict' } : {}),
                     ...(outcome.refusal ? { refusal: { reason: outcome.refusal.reason, phase: outcome.refusal.phase, retryable: outcome.refusal.retryable } } : {}) })]);
         },
     };

package/dist/fulfillment/postgresStockSyncPort.js

@@ -13,13 +13,13 @@ export function createPostgresFulfillmentStockSyncPort(db, options) {
             if (!row)
                 return null;
             const cursor = row.cursor;
-            return { status: row.status, lastStockSyncedAt: timestamp(row.last_stock_synced_at), lastMovementOccurredAt: timestamp(row.last_movement_occurred_at),
+            return { ...cursor, status: row.status, lastStockSyncedAt: timestamp(row.last_stock_synced_at), lastMovementOccurredAt: timestamp(row.last_movement_occurred_at),
                 continuation: cursor.continuation ?? { nextRef: null, startLocalDate: null, endLocalDate: null }, coverageGapSkus: cursor.coverageGapSkus ?? [], refusal: cursor.refusal ?? null };
         },
         async recordCursor(v) {
             await db.query(`INSERT INTO public.fulfillment_stock_sync_cursors(source_key,status,last_stock_synced_at,last_movement_occurred_at,cursor,error_code,updated_at)
         VALUES($1,$2,$3,$4,$5::jsonb,$6,now()) ON CONFLICT(source_key) DO UPDATE SET status=EXCLUDED.status,
-        last_stock_synced_at=EXCLUDED.last_stock_synced_at,last_movement_occurred_at=EXCLUDED.last_movement_occurred_at,cursor=EXCLUDED.cursor,error_code=EXCLUDED.error_code,updated_at=now()`, [source, v.status, v.lastStockSyncedAt, v.lastMovementOccurredAt, JSON.stringify({ continuation: { nextRef: v.continuation.nextRef, startLocalDate: v.continuation.startLocalDate, endLocalDate: v.continuation.endLocalDate }, coverageGapSkus: [...(v.coverageGapSkus ?? [])], refusal: v.refusal }), v.refusal?.reason ?? null]);
+        last_stock_synced_at=EXCLUDED.last_stock_synced_at,last_movement_occurred_at=EXCLUDED.last_movement_occurred_at,cursor=EXCLUDED.cursor,error_code=EXCLUDED.error_code,updated_at=now()`, [source, v.status, v.lastStockSyncedAt, v.lastMovementOccurredAt, JSON.stringify({ syncRunId: v.syncRunId, counts: v.counts, items: v.items, alerts: v.alerts, staleSync: v.staleSync, error: v.error, continuation: { nextRef: v.continuation.nextRef, startLocalDate: v.continuation.startLocalDate, endLocalDate: v.continuation.endLocalDate }, coverageGapSkus: [...(v.coverageGapSkus ?? [])], refusal: v.refusal }), v.error?.reason ?? v.refusal?.reason ?? null]);
         },
         async readSkuInventoryClasses(skus) {
             if (!skus.length)
@@ -48,7 +48,10 @@ export function createPostgresFulfillmentStockSyncPort(db, options) {
             const movement = { providerRef, syncRunId, collectedAt, sourceRevision, revisionSource, skuRef, quantityKind, quantity, occurredAt, operationType, documentRef, lotRef, expirationDate };
             return nativeCall(db, 'fulfillment_record_stock_movement', [source, v.requestKey, fingerprint({ requestKey: v.requestKey, movement }), JSON.stringify(movement)]);
         },
-        recordLowStockEvidence: v => nativeCall(db, 'fulfillment_record_stock_evidence', [source, v.requestKey, fingerprint(v), v.skuRef, v.thresholdKind, v.severity, v.providerForSaleQuantity, v.localAvailableQuantity]),
+        recordLowStockEvidence: v => nativeCall(db, 'fulfillment_record_stock_evidence', [source, v.requestKey,
+            // Quantities, severity and run evidence are observations of the same alert identity.
+            fingerprint({ requestKey: v.requestKey, skuRef: v.skuRef, thresholdKind: v.thresholdKind }),
+            v.skuRef, v.thresholdKind, v.severity, v.providerForSaleQuantity, v.localAvailableQuantity]),
         resolveLowStockEvidence: v => nativeCall(db, 'fulfillment_resolve_stock_evidence', [source, v.skuRef, v.activeThresholdKinds, v.syncRunId]),
     };
 }

package/dist/fulfillment/providerDispatchAcceptance.d.ts

@@ -20,6 +20,7 @@ export declare function recoverDispatchAcceptanceWrite(input: {
     acceptance: Extract<FulfillmentDispatchResult, {
         kind: "accepted";
     }>;
+    error: unknown;
 }): Promise<{
     committed: boolean;
     readBacks: number;

package/dist/fulfillment/providerDispatchAcceptance.js

@@ -1,6 +1,8 @@
-import { dispatchEvidence } from "./dispatchProjection.js";
+import { durableStrings, dispatchEvidence, dispatchResult, localFailureReason } from "./dispatchProjection.js";
 export function acknowledgeAcceptedDispatch(input) {
     return input.store.acknowledge({ dispatchRef: input.record.dispatchRef, acceptance: {
+            ...(input.record.acceptance ? dispatchResult(input.record.acceptance) : {}),
+            ...(input.record.status === "uncertain" ? { recovery: { source: "persisted_acceptance", proof: "persisted_external_ref", noProviderPost: true } } : {}),
             kind: "accepted", externalRef: input.record.externalRef, evidence: dispatchEvidence(input.record.evidence), ...input.keys,
         } });
 }
@@ -10,10 +12,14 @@ export async function recoverDispatchAcceptanceWrite(input) {
     const committed = () => record?.status === "created" && record.externalRef === input.acceptance.externalRef;
     if (committed())
         return { committed: true, readBacks };
+    const privacy = durableStrings();
+    const cause = localFailureReason("ack", input.error, privacy);
     try {
         // Accepted proof survives a failed atomic ACK; finalization records uncertainty,
         // and the next worker repairs the ACK locally without another provider call.
-        record = await input.store.finalize({ dispatchRef: input.dispatchRef, result: input.acceptance });
+        record = await input.store.finalize({ dispatchRef: input.dispatchRef, result: { ...input.acceptance, error: {
+                    code: "dispatch_acceptance_write_failed", cause, ...(privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}), status: null, retryable: false, mayHaveSucceeded: true,
+                } } });
         readBacks += 1;
     }
     catch {

package/dist/fulfillment/providerDispatchWorker.d.ts

@@ -16,8 +16,59 @@ export declare function runFulfillmentDispatchWorker(input: {
         mode: DispatchRecord["mode"];
         batchLimit: number;
     };
+    /** Pure local shadow fingerprint: a lowercase 64-hex SHA-256 digest of the adopter's canonical command bytes. Invalid output or a throw refuses before evidence writes. Never return raw command/PII. Used across shadow claim/readback/attempt; shadow never begins, and live preparation must produce the same identity. */
+    shadowCommandFingerprint?: (request: FulfillmentDispatchRequest) => string;
     now?: () => Date;
 }): Promise<{
+    redactedFieldCount: number;
+    ok: boolean;
+    failures: number;
+    reason: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    refusal: {
+        reason: "malformed";
+        phase: "prepare";
+        retryable: false;
+        cause: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    };
+    skipped: boolean;
+    checked: number;
+    updated: number;
+    mode: "shadow" | "stage" | "live";
+    replayed: number;
+    providerCalls: number;
+    readBacks: number;
+} | {
+    redactedFieldCount?: undefined;
+    ok: boolean;
+    failures: number;
+    reason: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    refusal: {
+        reason: "malformed";
+        phase: "prepare";
+        retryable: false;
+        cause: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    };
+    skipped: boolean;
+    checked: number;
+    updated: number;
+    mode: "shadow" | "stage" | "live";
+    replayed: number;
+    providerCalls: number;
+    readBacks: number;
+} | {
+    redactedFieldCount: number;
+    ok: boolean;
+    skipped: boolean;
+    checked: number;
+    updated: number;
+    failures: number;
+    mode: "shadow" | "stage" | "live";
+    replayed: number;
+    providerCalls: number;
+    readBacks: number;
+    reason: string | undefined;
+} | {
+    redactedFieldCount?: undefined;
     ok: boolean;
     skipped: boolean;
     checked: number;

package/dist/fulfillment/providerDispatchWorker.js

@@ -1,21 +1,25 @@
-import { acceptedProviderProof, dispatchEvidence, dispatchResult } from "./dispatchProjection.js";
+import { durableStrings, acceptedProviderProof, dispatchEvidence, dispatchResult, localFailureReason, shadowDispatchEvidence } from "./dispatchProjection.js";
 import { acknowledgeAcceptedDispatch, recoverDispatchAcceptanceWrite } from "./providerDispatchAcceptance.js";
 import { unknownDispatchFailure } from "./providerDispatchError.js";
 export async function runFulfillmentDispatchWorker(input) {
+    const privacy = durableStrings();
+    const failure = (stage, error) => localFailureReason(stage, error, privacy);
+    const diagnostics = () => privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {};
     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" };
+        catch (error) {
+            return { ...result, ok: false, failures: 1, reason: failure("dispatch_stale_submission_sweep_failed", error), ...diagnostics() };
         }
     }
     const candidates = await input.listCandidates(input.config.batchLimit);
     result.checked = candidates.length;
     candidateLoop: for (const candidate of candidates) {
         const requestKey = input.keys.request(candidate);
+        let stage = "dispatch_read_failed";
         try {
             let readBack = await input.store.read(requestKey);
             if (readBack)
@@ -27,9 +31,11 @@ export async function runFulfillmentDispatchWorker(input) {
                 result.updated += ack.replayed ? 0 : 1;
                 continue;
             }
+            stage = "dispatch_prepare_failed";
             const preparation = await input.store.prepare(candidate.fulfillmentRef);
             if (preparation.disposition === "withheld")
                 continue;
+            stage = "dispatch_candidate_read_failed";
             const preparedCandidate = await input.store.readCandidate(candidate.fulfillmentRef);
             if (!preparedCandidate)
                 throw new Error("dispatch_prepared_candidate_missing");
@@ -39,23 +45,48 @@ export async function runFulfillmentDispatchWorker(input) {
                 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 providerEvidence;
             let mappedAttemptCount = 0;
             for (let remapCount = 0;; remapCount += 1) {
                 const request = { ...mappedCandidate, requestKey };
-                const prepared = await input.provider.prepare(request);
+                stage = "dispatch_command_prepare_failed";
+                let shadowFingerprint;
+                if (input.config.mode === "shadow" && input.shadowCommandFingerprint) {
+                    let value;
+                    let cause;
+                    try {
+                        value = input.shadowCommandFingerprint(request);
+                    }
+                    catch {
+                        cause = "adopter_fingerprint_failed";
+                    }
+                    if (!cause && typeof value === "string" && /^[a-f0-9]{64}$/.test(value))
+                        shadowFingerprint = value;
+                    else
+                        cause ??= "adopter_fingerprint_invalid";
+                    if (cause)
+                        return { ...result, ok: false, failures: result.failures + 1, reason: cause,
+                            refusal: { reason: "malformed", phase: "prepare", retryable: false, cause }, ...diagnostics() };
+                }
+                const prepared = input.config.mode === "shadow"
+                    ? { kind: "prepared", evidence: shadowDispatchEvidence(request, shadowFingerprint) }
+                    : await input.provider.prepare(request);
                 if (prepared.kind === "refused") {
                     result.ok = false;
                     result.failures += 1;
-                    result.reason ??= prepared.refusal.reason;
+                    result.reason ??= privacy.token(prepared.refusal.reason) ?? "redacted";
                     continue candidateLoop;
                 }
-                evidence = dispatchEvidence(prepared.evidence);
+                providerEvidence = dispatchEvidence(prepared.evidence);
+                evidence = { ...providerEvidence, mapping: { source: "dispatch_worker", mode: input.config.mode, shadowMode: input.config.mode === "shadow" } };
+                // Native claims count any JSON change as a remap; attempts compare
+                // the whole JSON. Enrichment must not rewrite an existing identity.
+                if (readBack && sameCommandIdentity(readBack.evidence, evidence))
+                    evidence = dispatchEvidence(readBack.evidence);
+                stage = "dispatch_claim_failed";
                 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") {
@@ -68,18 +99,20 @@ export async function runFulfillmentDispatchWorker(input) {
                     }
                     result.ok = false;
                     result.failures += 1;
-                    result.reason ??= claim.refusal.reason;
+                    result.reason ??= privacy.token(claim.refusal.reason) ?? "redacted";
                     continue candidateLoop;
                 }
                 dispatchRef = claim.record;
                 if (dispatchRef.replayed)
                     result.replayed += 1;
                 // Re-claim may refresh a correctable draft atomically; readback is authoritative.
+                stage = "dispatch_readback_failed";
                 readBack = await input.store.read(requestKey);
                 if (readBack)
                     result.readBacks += 1;
                 if (!readBack || readBack.fulfillmentRef !== mappedCandidate.fulfillmentRef)
                     throw new Error("dispatch_readback_failed");
+                stage = "dispatch_attempt_write_failed";
                 await input.store.recordProviderAttempt(input.keys.mappedAttempt(requestKey, mappedAttemptCount), mappedCandidate.fulfillmentRef, evidence, input.config.mode, "recorded");
                 mappedAttemptCount += 1;
                 if (input.config.mode === "shadow") {
@@ -92,6 +125,7 @@ export async function runFulfillmentDispatchWorker(input) {
                     result.reason ??= `dispatch_not_safe_to_submit:${readBack.status}`;
                     continue candidateLoop;
                 }
+                stage = "dispatch_begin_failed";
                 const submission = await input.store.begin({ dispatchRef: dispatchRef.dispatchRef, commandFingerprint: evidence.commandFingerprint });
                 if (submission.kind === "refused") {
                     if (remapCount === 0 && submission.refusal.reason === "contact_stale") {
@@ -103,10 +137,11 @@ export async function runFulfillmentDispatchWorker(input) {
                     }
                     result.ok = false;
                     result.failures += 1;
-                    result.reason ??= submission.refusal.reason;
+                    result.reason ??= privacy.token(submission.refusal.reason) ?? "redacted";
                     continue candidateLoop;
                 }
                 if (!submission.begun) {
+                    stage = "dispatch_concurrent_read_failed";
                     const concurrent = await input.store.read(requestKey);
                     if (concurrent)
                         result.readBacks += 1;
@@ -128,27 +163,32 @@ export async function runFulfillmentDispatchWorker(input) {
             result.providerCalls += 1;
             let response;
             try {
-                response = dispatchResult(await input.provider.dispatch({ ...mappedCandidate, requestKey }, evidence));
+                response = dispatchResult(await input.provider.dispatch({ ...mappedCandidate, requestKey }, providerEvidence));
             }
             catch {
                 response = unknownDispatchFailure();
             }
+            if (response.kind === "accepted" && JSON.stringify(response.evidence) !== JSON.stringify(providerEvidence)) {
+                response = { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: "malformed", phase: "acknowledge", retryable: false },
+                    error: { code: "dispatch_acceptance_evidence_mismatch", status: null, retryable: false, mayHaveSucceeded: true } };
+            }
             if (response.kind !== "accepted") {
+                stage = "dispatch_finalize_failed";
                 await input.store.finalize({ dispatchRef: dispatchRef.dispatchRef, result: response });
                 result.ok = false;
                 result.failures += 1;
-                result.reason ??= response.refusal.reason;
+                result.reason ??= response.error?.code ?? response.refusal.reason;
                 continue;
             }
             // All ACK paths use the original host keys, ignoring adapter key fields.
-            const acceptance = { ...response, ...input.keys.acceptance(mappedCandidate.fulfillmentRef) };
+            const acceptance = { ...response, evidence, ...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 });
+            catch (error) {
+                const recovery = await recoverDispatchAcceptanceWrite({ store: input.store, requestKey, dispatchRef: dispatchRef.dispatchRef, acceptance, error });
                 result.readBacks += recovery.readBacks;
                 if (recovery.committed) {
                     result.updated += 1;
@@ -161,12 +201,17 @@ export async function runFulfillmentDispatchWorker(input) {
             }
             result.updated += 1;
         }
-        catch {
-            // Exception messages may contain raw provider bodies or credentials.
+        catch (error) {
             result.ok = false;
             result.failures += 1;
-            result.reason ??= "dispatch_local_operation_failed";
+            result.reason ??= failure(stage, error);
         }
     }
-    return result;
+    return { ...result, ...diagnostics() };
+}
+function sameCommandIdentity(a, b) {
+    return a.commandFingerprint === b.commandFingerprint && a.providerRef === b.providerRef
+        && a.carrierRef === b.carrierRef && a.serviceRef === b.serviceRef
+        && a.contactRevision.schemaVersion === b.contactRevision.schemaVersion
+        && a.contactRevision.source === b.contactRevision.source && a.contactRevision.revision === b.contactRevision.revision;
 }

package/dist/fulfillment/providerReconciliationWorker.d.ts

@@ -1,12 +1,9 @@
-import type { FulfillmentObservation, FulfillmentReadbackResult } from "./contracts/index.js";
+import type { FulfillmentObservation, FulfillmentObservationPagePort, FulfillmentReconciliationObservation, FulfillmentOperationError } 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 {
+type PollEvidence = Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics"> | FulfillmentObservation;
+export interface ReconciliationResult {
     ok: boolean;
     checked: number;
     updated: number;
@@ -17,6 +14,7 @@ interface ReconciliationResult {
     stale: number;
     offTrackSkips: number;
     replayed: number;
+    redactedFieldCount?: number;
     failures: number;
     invoiceIssueFailures: number;
     invoiceIssueRefused: number;
@@ -30,29 +28,21 @@ interface ReconciliationResult {
     readBacks: number;
     skipped: boolean;
     reason?: string;
+    providerError?: FulfillmentOperationError;
 }
 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;
-    })[]>;
+    }): Promise<readonly FulfillmentReconciliationObservation[]>;
     batchSize: number;
     page?: number;
     localPersistence: {
         /** G17: local persisted chronology, never inferred from dispatch or provider state. */
-        readLocalFulfillmentState(ref: string): Promise<{
-            status: string | null;
-            latestStatusOccurredAt: string | null;
-            handedOverAt: string | null;
-        }>;
+        readLocalFulfillmentStatus(ref: string): Promise<string | null>;
+        latestStatusOccurredAt(ref: string): Promise<string | null>;
+        readHandedOverAt(ref: string): Promise<string | null>;
     };
     lifecycle: Pick<Ingress["lifecycle"], "recordStatusEvidence" | "effects" | "keys"> & {
         findDispatchRef(evidence: PollEvidence): Promise<DispatchRef | null>;
@@ -79,4 +69,22 @@ export declare function reconcileFulfillmentObservations(input: {
         classifyStateConflict(error: unknown): "fulfillment_not_found" | "stock_consumed_requires_label" | null;
     };
 }): Promise<ReconciliationResult>;
+/** Host owns scheduling, HTTP and durable job-ledger writes. This operation only projects them. */
+export declare function runFulfillmentReconciliationPage(input: Omit<Parameters<typeof reconcileFulfillmentObservations>[0], "readPage" | "batchSize" | "page"> & {
+    provider: FulfillmentObservationPagePort;
+    pageSize: number;
+    checkpoint: unknown;
+}): Promise<{
+    status: 200 | 502;
+    ledgerStatus: "failed" | "succeeded";
+    result: ReconciliationResult;
+    metadata: {
+        reconciliationPagination: {
+            version: number;
+            page: number;
+            pageSize: number;
+            nextPage: number;
+        };
+    };
+}>;
 export {};