@openlup/platform 0.21.0 → 0.23.0

package/src/fulfillment/providerDispatchWorker.ts

@@ -0,0 +1,159 @@
+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";
+
+export async 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;
+}) {
+  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 (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;
+      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;
+      }
+      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;
+      }
+      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 };
+        stage = "dispatch_command_prepare_failed";
+        const prepared = input.config.mode === "shadow"
+          ? { kind: "prepared" as const, evidence: shadowDispatchEvidence(request) }
+          : await input.provider!.prepare(request);
+        if (prepared.kind === "refused") {
+          result.ok = false; result.failures += 1; result.reason ??= privacy.token(prepared.refusal.reason) ?? "redacted"; continue candidateLoop;
+        }
+        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") {
+          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 ??= 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") {
+          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;
+        }
+        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") {
+            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 ??= 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)) {
+            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: 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.error?.code ?? response.refusal.reason; continue;
+      }
+      // All ACK paths use the original host keys, ignoring adapter key fields.
+      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 (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 (error) {
+      result.ok = false; result.failures += 1; result.reason ??= failure(stage, error);
+    }
+  }
+  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/providerProductSyncWorker.ts

@@ -0,0 +1,154 @@
+import type { FulfillmentProductSyncPort, FulfillmentProductSyncProvider } from "./contracts/index.js";
+type PackKind = "unit" | "collective";
+type PackUpsertConflict = Awaited<ReturnType<FulfillmentProductSyncPort["upsertPulledPack"]>>["conflict"];
+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;
+}
+
+function packKindForQuantity(quantity: number): PackKind {
+  return quantity > 1 ? "collective" : "unit";
+}
+
+function reconciliationKindFor(conflict: PackUpsertConflict): ReconciliationConflict | null {
+  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: {
+  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> {
+  const now = input.now?.() ?? new Date();
+  const mode = input.mode ?? "both";
+  const identity = input.compatibility.identity(now);
+  const syncRunId = identity.syncRunId;
+  const result: ProductSyncResult = {
+    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: { port: FulfillmentProductSyncPort; provider: FulfillmentProductSyncProvider },
+  result: ProductSyncResult,
+): Promise<void> {
+  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: Pick<Parameters<typeof runFulfillmentProductSyncWorker>[0], "port" | "provider" | "compatibility">,
+  result: ProductSyncResult,
+  identity: SyncIdentity,
+): Promise<void> {
+  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<ReconciliationConflict>();
+
+      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/src/fulfillment/providerReconciliationError.ts

@@ -0,0 +1,20 @@
+import type { FulfillmentObservation } from "./contracts/index.js";
+
+/** Host decoding supplies known domain reasons, never a raw provider error message. */
+export async 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> {
+  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/src/fulfillment/providerReconciliationTerminalSkip.ts

@@ -0,0 +1,8 @@
+import { FULFILLMENT_STATUS_MAP } from "./statusMap.js";
+const OFF_TRACK_FULFILLMENT_STATUSES: ReadonlySet<string> = 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: string | null | undefined): boolean {
+  return status !== null && status !== undefined && OFF_TRACK_FULFILLMENT_STATUSES.has(status);
+}

package/src/fulfillment/providerReconciliationTimestamp.ts

@@ -0,0 +1,34 @@
+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: string | null | undefined,
+): string | null {
+  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/src/fulfillment/providerReconciliationWorker.ts

@@ -0,0 +1,206 @@
+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, projectObservation, projectPollEvidence, projectTrackingReference } from "./observationProjection.js";
+import { quarantineReconciliationStateConflict } from "./providerReconciliationError.js";
+import { isOffTrackFulfillmentStatus } from "./providerReconciliationTerminalSkip.js";
+import { normalizeReconciliationTimestamp } from "./providerReconciliationTimestamp.js";
+import { enrichTrackingReference, trackingReferenceComplete, uniqueTrackingReferences } from "./providerTrackingReferences.js";
+
+type Ingress = Parameters<typeof import("./verifiedIngress.js").verifyAndNormalizeFulfillmentObservation>[0];
+type DispatchRef = NonNullable<Awaited<ReturnType<Ingress["lifecycle"]["findDispatchRef"]>>>;
+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;
+  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; 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 FulfillmentReconciliationObservation[]>;
+  batchSize: number; page?: number;
+  localPersistence: {
+    /** G17: local persisted chronology, never inferred from dispatch or provider state. */
+    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>;
+    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> {
+  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,
+    invoiceIssueRefusals: [], providerCalls: 0, readBacks: 0, skipped: false,
+  };
+  const page = await input.readPage({ page: input.page ?? 0, size: input.batchSize });
+  result.providerCalls += 1;
+  result.checked = page.length;
+  const quarantine = async (observation: PollEvidence | null, reason: Parameters<typeof input.lifecycle.recordQuarantine>[1]) => {
+    const evidence = await input.lifecycle.recordQuarantine(observation, reason);
+    if (evidence.replayed) result.replayed += 1;
+    result.quarantined += evidence.replayed ? 0 : 1;
+  };
+  const invoice = async (ref: string) => {
+    try { await input.lifecycle.issueAccountingInvoice?.(ref); }
+    catch (error) {
+      const refusal = input.lifecycle.invoiceFailure(error);
+      if (refusal.permanent) {
+        result.invoiceIssueRefused += 1;
+        const identifier = privacy.token(refusal.identifier, safeDiagnosticCode), sqlstate = privacy.token(refusal.sqlstate, safeDiagnosticCode);
+        if (result.invoiceIssueRefusals.length < 10) result.invoiceIssueRefusals.push({ fulfillmentRef: ref,
+          identifier, sqlstate: sqlstate ?? "22023", benign: refusal.benign });
+        result.reason ??= failure("reconciliation_invoice_issue_refused", { causeMessage: identifier, causeCode: sqlstate, message: error instanceof Error ? error.message : undefined });
+        return;
+      }
+      result.ok = false; result.failures += 1; result.invoiceIssueFailures += 1;
+      result.reason ??= failure("reconciliation_invoice_issue_failed", error);
+    }
+  };
+  for (const readback of page) {
+    let observation: 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 = projectPollEvidence(readback.evidence);
+        const ref = await input.lifecycle.findDispatchRef(evidence);
+        if (!ref) { await quarantine(evidence, "missing_correlation"); continue; }
+        const localState = await input.localPersistence.readLocalFulfillmentStatus(ref.fulfillmentRef);
+        if (isOffTrackFulfillmentStatus(localState)) { result.offTrackSkips += 1; continue; }
+        if (!(readback.externalRef?.trim() || ref.externalRef?.trim())) { await quarantine(evidence, "missing_external_ref"); continue; }
+        await input.lifecycle.acknowledgeDispatchAcceptance(ref, evidence);
+        await quarantine(evidence, "unknown_status");
+        continue;
+      }
+      if (readback.kind !== "found") {
+        // Neither unsupported nor a provider absence is a local transition.
+        continue;
+      }
+      observation = projectObservation(readback.observation, input.lifecycle.trackingCodecs.approveTrackingUrl, input.lifecycle.trackingCodecs);
+      if (observation.diagnostics?.redactedFieldCount) {
+        result.redactedFieldCount = (result.redactedFieldCount ?? 0) + observation.diagnostics.redactedFieldCount;
+      }
+      const ref = await input.lifecycle.findDispatchRef(observation);
+      if (!ref) { await quarantine(observation, "missing_correlation"); continue; }
+      const localState = await input.localPersistence.readLocalFulfillmentStatus(ref.fulfillmentRef);
+      const offTrack = isOffTrackFulfillmentStatus(localState);
+      if (offTrack) result.offTrackSkips += 1;
+      if (!offTrack) {
+        if (!(readback.externalRef.trim() || ref.externalRef?.trim())) { await quarantine(observation, "missing_external_ref"); continue; }
+        await input.lifecycle.acknowledgeDispatchAcceptance(ref, observation);
+      }
+      const occurredAt = normalizeReconciliationTimestamp(readback.updatedAt);
+      const localStatus = observation.fact.canonicalStatus;
+      const latest = await input.localPersistence.latestStatusOccurredAt(ref.fulfillmentRef);
+      if (latest && occurredAt && Date.parse(occurredAt) < Date.parse(latest)) {
+        result.stale += 1;
+        if (!offTrack && input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef)) await invoice(ref.fulfillmentRef);
+        continue;
+      }
+      // The normalized fact carries the same nullable occurrence used by dedupe.
+      observation = { ...observation, fact: { ...observation.fact, occurredAt } };
+      const status = await input.lifecycle.recordStatusEvidence(ref, observation);
+      if (status.replayed) result.replayed += 1;
+      if (offTrack) continue;
+      result.updated += status.replayed ? 0 : 1;
+      if (localStatus === "exception") {
+        const exception = await input.lifecycle.recordProviderException(ref, observation);
+        if (exception.replayed) result.replayed += 1;
+        result.exceptions += exception.replayed ? 0 : 1;
+        if (input.lifecycle.issueAccountingInvoice && await input.localPersistence.readHandedOverAt(ref.fulfillmentRef)) await invoice(ref.fulfillmentRef);
+        continue;
+      }
+      const trackingRefs = [];
+      if (observationStatusPolicy.handsOver(localStatus)) {
+        let carrier: 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 codecs = input.lifecycle.trackingCodecs;
+          const candidate = enrichTrackingReference(tracking, carrier ?? null, { ...codecs, publicUrl: () => null });
+          const enriched = projectTrackingReference(candidate, privacy, codecs.approveTrackingUrl, codecs);
+          if (!enriched) continue;
+          // Host-built links use admitted parts and pass through unchanged, including queries.
+          enriched.publicUrl ??= codecs.publicUrl(enriched.carrierRef, enriched.trackingNumber);
+          trackingRefs.push({ trackingNumber: enriched.trackingNumber, trackingUrl: enriched.publicUrl, carrierKind: enriched.carrierRef, service: enriched.serviceRef });
+        }
+      }
+      await applyFulfillmentObservationEffects({
+        port: input.lifecycle.effects, localStatus, ids: { orderId: ref.orderRef, fulfillmentOrderId: ref.fulfillmentRef }, observation,
+        trackingRefs, stockIdempotencyKey: input.lifecycle.keys.stock(ref.fulfillmentRef), handoffIdempotencyKey: input.lifecycle.keys.handoff(ref.fulfillmentRef),
+        trackingIdempotencyKey: number => input.lifecycle.keys.tracking(observation!.eventKey, number),
+        issueAccountingInvoice: input.lifecycle.issueAccountingInvoice ? () => invoice(ref.fulfillmentRef) : undefined,
+        onReplayed: () => { result.replayed += 1; },
+        onTrackingRecorded: tracking => {
+          if (tracking.replayed) result.replayed += 1;
+          if (tracking.readBack) result.readBacks += 1;
+          result.trackingRefs += tracking.replayed ? 0 : 1;
+        },
+      }, observationStatusPolicy);
+    } catch (caught) {
+      const error = observation ? await quarantineReconciliationStateConflict(caught, observation,
+        input.lifecycle.classifyStateConflict, input.lifecycle.recordQuarantine, result) : caught;
+      if (error === null) continue;
+      result.ok = false; result.failures += 1; result.reason ??= failure("reconciliation_local_operation_failed", error);
+    }
+  }
+  return { ...result, ...(privacy.redactedFieldCount ? { redactedFieldCount: (result.redactedFieldCount ?? 0) + privacy.redactedFieldCount } : {}) };
+}
+
+
+/** Host owns scheduling, HTTP and durable job-ledger writes. This operation only projects them. */
+export async function runFulfillmentReconciliationPage(input: 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) };
+  }
+  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 } } };
+}

package/src/fulfillment/providerStockAvailability.ts

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