@openlup/platform 0.22.0 → 0.24.0

package/src/fulfillment/providerDispatchAcceptance.ts

@@ -1,5 +1,5 @@
 import type { DispatchRecord, FulfillmentDispatchResult, FulfillmentStorePort } from "./contracts/index.js";
-import { dispatchEvidence } from "./dispatchProjection.js";
+import { durableStrings, dispatchEvidence, dispatchResult, localFailureReason } from "./dispatchProjection.js";
 
 export function acknowledgeAcceptedDispatch(input: {
   store: FulfillmentStorePort;
@@ -7,22 +7,28 @@ export function acknowledgeAcceptedDispatch(input: {
   keys: { providerAttemptKey: string; labelKey: string };
 }) {
   return input.store.acknowledge({ dispatchRef: input.record.dispatchRef, acceptance: {
+    ...(input.record.acceptance ? dispatchResult(input.record.acceptance) : {}),
+    ...(input.record.status === "uncertain" ? { recovery: { source: "persisted_acceptance" as const, proof: "persisted_external_ref" as const, noProviderPost: true as const } } : {}),
     kind: "accepted", externalRef: input.record.externalRef, evidence: dispatchEvidence(input.record.evidence), ...input.keys,
   } });
 }
 
 export async function recoverDispatchAcceptanceWrite(input: {
   store: FulfillmentStorePort; requestKey: string; dispatchRef: string;
-  acceptance: Extract<FulfillmentDispatchResult, { kind: "accepted" }>;
+  acceptance: Extract<FulfillmentDispatchResult, { kind: "accepted" }>; error: unknown;
 }): Promise<{ committed: boolean; readBacks: number }> {
   let record = await input.store.read(input.requestKey).catch(() => null);
   let readBacks = record ? 1 : 0;
   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 {
     // Submitting remains fenced; the stale sweep moves it to uncertain.

package/src/fulfillment/providerDispatchWorker.ts

@@ -1,5 +1,5 @@
-import type { DispatchRecord, FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentStorePort } from "./contracts/index.js";
-import { acceptedProviderProof, dispatchEvidence, dispatchResult } from "./dispatchProjection.js";
+import type { DispatchRecord, FulfillmentDispatchPort, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentStorePort } from "./contracts/index.js";
+import { durableStrings, acceptedProviderProof, dispatchEvidence, dispatchResult, localFailureReason, shadowDispatchEvidence } from "./dispatchProjection.js";
 import { acknowledgeAcceptedDispatch, recoverDispatchAcceptanceWrite } from "./providerDispatchAcceptance.js";
 import { unknownDispatchFailure } from "./providerDispatchError.js";
 
@@ -14,18 +14,24 @@ export async function runFulfillmentDispatchWorker(input: {
     acceptance(fulfillmentRef: string): { providerAttemptKey: string; labelKey: string };
   };
   config: { 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;
 }) {
+  const privacy = durableStrings();
+  const failure = (stage: string, error: unknown) => 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 as string | 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) result.readBacks += 1;
@@ -35,26 +41,46 @@ 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");
       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: DispatchRecord;
       let evidence: DispatchRecord["evidence"];
+      let providerEvidence: DispatchRecord["evidence"];
       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: string | undefined;
+        if (input.config.mode === "shadow" && input.shadowCommandFingerprint) {
+          let value: unknown;
+          let cause: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed" | undefined;
+          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" as const, phase: "prepare" as const, retryable: false as const, cause }, ...diagnostics() };
+        }
+        const prepared = input.config.mode === "shadow"
+          ? { kind: "prepared" as const, evidence: shadowDispatchEvidence(request, shadowFingerprint) }
+          : await input.provider!.prepare(request);
         if (prepared.kind === "refused") {
-          result.ok = false; result.failures += 1; result.reason ??= prepared.refusal.reason; continue candidateLoop;
+          result.ok = false; result.failures += 1; 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") {
@@ -63,14 +89,16 @@ export async function runFulfillmentDispatchWorker(input: {
             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;
+          result.ok = false; result.failures += 1; 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;
@@ -80,6 +108,7 @@ export async function runFulfillmentDispatchWorker(input: {
         if (readBack.status !== "draft") {
           result.ok = false; result.failures += 1; 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") {
@@ -87,9 +116,10 @@ export async function runFulfillmentDispatchWorker(input: {
             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;
+          result.ok = false; result.failures += 1; 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;
           if (acceptedProviderProof(concurrent)) {
@@ -103,29 +133,40 @@ export async function runFulfillmentDispatchWorker(input: {
         break;
       }
       result.providerCalls += 1;
-      let response;
-      try { response = dispatchResult(await input.provider.dispatch({ ...mappedCandidate, requestKey }, evidence)); }
+      let response: FulfillmentDispatchResult;
+      try { 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; continue;
+        result.ok = false; result.failures += 1; 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; 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";
+    } catch (error) {
+      result.ok = false; result.failures += 1; result.reason ??= failure(stage, error);
     }
   }
-  return result;
+  return { ...result, ...diagnostics() };
+}
+
+function sameCommandIdentity(a: DispatchRecord["evidence"], b: DispatchRecord["evidence"]): boolean {
+  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/src/fulfillment/providerReconciliationWorker.ts

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