@openlup/platform 0.22.0 → 0.23.0

package/src/fulfillment/omnipack/observation.ts

@@ -1,16 +1,22 @@
+import { admittedReference, reference } from "../dispatchProjection.js";
+import { projectObservation, publicTrackingUrl } from "../observationProjection.js";
+export { reference } from "../dispatchProjection.js";
 import { createHash } from "node:crypto";
 import { parseNormalizedFulfillmentFact } from "@openlup/core/fulfillment";
-import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentRefusal } from "../contracts/index.js";
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentRefusal } from "../contracts/index.js";
 import type { OmnipackWebhookEvidence } from "./mappers.js";
 import type { OmnipackTrackingReferenceEvidence } from "./trackingReferences.js";
-import { EVENT_TO_STATUS, type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
+import { buildProviderEventId, EVENT_TO_STATUS, type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
 import { localStatusFor } from "./omnipackStatusVocabulary.js";
 
 export const refusal = (reason: FulfillmentRefusal["reason"], phase: FulfillmentRefusal["phase"], retryable = false): FulfillmentRefusal => ({ reason, phase, retryable });
 export const digest = (bytes: string | Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
-/** References are opaque identifiers, never arbitrary provider prose or URLs. */
-export function reference(value: string | null | undefined): string | null {
-  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) ? value : null;
+/** Share admission with the durable sink, including explicit deny allowlists. */
+export function correlationReference(value: string | null | undefined, codecs: OmnipackObservationCodecs = {}): string | null {
+  return admittedReference(value, codecs.approveReference);
+}
+export interface OmnipackObservationCodecs extends FulfillmentObservationCodecs {
+  normalizeCarrier?(input: { carrierRef: string | null; serviceRef: string | null }): string | null;
 }
 export function timestamp(value: string | null): string | null {
   return value && /^\d{4}-\d\d-\d\dT/u.test(value) && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
@@ -18,44 +24,56 @@ export function timestamp(value: string | null): string | null {
 export function eventKind(value: string): OmnipackWebhookRouteEvent | null {
   return Object.hasOwn(EVENT_TO_STATUS, value) ? value as OmnipackWebhookRouteEvent : null;
 }
-export function publicUrl(value: string | null, approve: (url: string) => boolean): string | null {
-  if (!value) return null;
-  try {
-    const url = new URL(value);
-    // Query-free URLs only: signing tokens and credentials never enter durable tracking.
-    return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash && approve(url.href) ? url.href : null;
-  } catch { return null; }
-}
-function tracking(refs: OmnipackTrackingReferenceEvidence[], approve: (url: string) => boolean): FulfillmentObservation["trackingRefs"] {
-  return refs.flatMap(item => {
-    const trackingNumber = reference(item.trackingNumber);
-    return trackingNumber ? [{ trackingNumber, carrierRef: reference(item.carrier), serviceRef: reference(item.service), publicUrl: publicUrl(item.trackingUrl, approve) }] : [];
-  });
+function tracking(refs: OmnipackTrackingReferenceEvidence[], codecs: OmnipackObservationCodecs, approve: (url: string) => boolean) {
+  let rejectedTrackingRefs = 0, rejectedServices = 0, rejectedTrackingUrls = 0;
+  const trackingRefs: FulfillmentObservation["trackingRefs"][number][] = [];
+  for (const item of refs) {
+    if (item.service !== null && !correlationReference(item.service, codecs)) rejectedServices++;
+    if (item.trackingUrl !== null && !publicTrackingUrl(item.trackingUrl, approve, codecs.trackingUrl)) rejectedTrackingUrls++;
+    const trackingNumber = correlationReference(item.trackingNumber, codecs);
+    if (!trackingNumber) { rejectedTrackingRefs++; continue; }
+    // Service admission precedes any derivation. A refused service cannot leak a prefix.
+    const serviceRef = correlationReference(item.service, codecs);
+    const carrierRef = item.service !== null && !serviceRef ? null : reference(codecs.normalizeCarrier
+      ? codecs.normalizeCarrier({ carrierRef: item.carrier, serviceRef })
+      : serviceRef?.split("_")[0]?.toLowerCase());
+    trackingRefs.push({ trackingNumber, carrierRef, serviceRef: item.service, publicUrl: item.trackingUrl });
+  }
+  return { trackingRefs, rejectedTrackingRefs, rejectedServices, rejectedTrackingUrls };
 }
 export function observation(input: {
   evidence: OmnipackWebhookEvidence; event: FulfillmentObservation["eventKind"]; status?: CanonicalLocalFulfillmentStatus;
   receivedAt: string; rawDigest: string; evidenceRef: `evidence:${string}`;
   source: "provider_webhook" | "provider_reconciliation"; fulfillmentRef?: string;
   approveTrackingUrl: (url: string) => boolean;
+  observationCodecs?: OmnipackObservationCodecs;
 }): FulfillmentObservation {
   const evidence = input.evidence;
-  const externalRef = reference(evidence.providerOrderId);
-  const providerFulfillmentRef = reference(evidence.fulfilmentNumber);
-  const orderNumber = reference(evidence.orderNumber);
+  const codecs = input.observationCodecs ?? {};
+  const externalRef = correlationReference(evidence.providerOrderId, codecs);
+  const providerFulfillmentRef = correlationReference(evidence.fulfilmentNumber, codecs);
+  const orderNumber = correlationReference(evidence.orderNumber, codecs);
   const fulfillmentRef = reference(input.fulfillmentRef) ?? providerFulfillmentRef ?? externalRef ?? orderNumber;
-  if (!fulfillmentRef) throw refusal("missing_correlation", "normalize");
+  if (!fulfillmentRef || input.source === "provider_webhook" && [evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => value !== null && !correlationReference(value, codecs))) throw refusal("missing_correlation", "normalize");
   const occurredAt = timestamp(evidence.occurredAt);
   if (evidence.occurredAt && !occurredAt) throw refusal("malformed", "normalize");
-  const key = digest(JSON.stringify([input.event, externalRef ?? orderNumber, providerFulfillmentRef, occurredAt]));
+  // Compose the key with the provider's
+  // original bytes, including minute precision and offsets, rather than the UTC fact.
+  const key = buildProviderEventId(evidence);
+  const normalizedTracking = tracking(evidence.trackingReferences, codecs, input.approveTrackingUrl);
+  const rejectedTrackingRefs = normalizedTracking.rejectedTrackingRefs + (evidence.rejectedTrackingRefs ?? 0)
+    + (evidence.rejectedServices ?? normalizedTracking.rejectedServices);
   const status = input.status ?? localStatusFor(EVENT_TO_STATUS[input.event as OmnipackWebhookRouteEvent]);
   const fact = parseNormalizedFulfillmentFact({
-    schemaVersion: 1, mapperVersion: "1", factId: key, providerKind: "omnipack", fulfillmentReference: fulfillmentRef,
+    schemaVersion: 1, mapperVersion: "1", factId: digest(key), providerKind: "omnipack", fulfillmentReference: reference(fulfillmentRef) ?? digest(fulfillmentRef),
     canonicalStatus: status, provenance: { source: input.source, authority: "provider_asserted" },
     occurredAt, receivedAt: input.receivedAt,
     rawEvent: { reference: input.evidenceRef, digestAlgorithm: "sha256", digest: input.rawDigest },
   }, { isCanonicalStatus: (value): value is CanonicalLocalFulfillmentStatus =>
     ["provider_received", "picking", "packed", "in_transit", "delivered", "exception", "cancelled"].includes(value) });
-  return { fact, eventKind: input.event, eventKey: key, firstReceivedAt: input.receivedAt,
-    correlation: { orderRef: null, fulfillmentRef: reference(input.fulfillmentRef), externalRef, orderNumber, providerFulfillmentRef, parcelRef: null },
-    trackingRefs: tracking(evidence.trackingReferences, input.approveTrackingUrl) };
+  return projectObservation({ fact, eventKind: input.event, eventKey: key, firstReceivedAt: input.receivedAt,
+    correlation: { orderRef: null, fulfillmentRef: reference(input.fulfillmentRef), externalRef: evidence.providerOrderId, orderNumber: evidence.orderNumber, providerFulfillmentRef: evidence.fulfilmentNumber, parcelRef: null },
+    trackingRefs: normalizedTracking.trackingRefs, diagnostics: { admission: {
+      rejectedTrackingRefs, rejectedTrackingUrls: evidence.rejectedTrackingUrls ?? normalizedTracking.rejectedTrackingUrls,
+    } } }, input.approveTrackingUrl, codecs);
 }

package/src/fulfillment/omnipack/reconciliation.ts

@@ -0,0 +1,56 @@
+import type { FulfillmentObservationPagePort, FulfillmentReconciliationObservation } from "../contracts/index.js";
+import { operationError } from "../dispatchProjection.js";
+import { projectPollEvidence, projectObservation } from "../observationProjection.js";
+import { normalizeReconciliationTimestamp } from "../providerReconciliationTimestamp.js";
+import type { OmnipackClient } from "./client.js";
+import { OmnipackProviderError } from "./client.js";
+import type { OmnipackFulfilmentEvidence } from "./mappers.js";
+import { digest, observation, reference, refusal, timestamp, type OmnipackObservationCodecs } from "./observation.js";
+import { localStatusFor, normalizeStatus } from "./omnipackStatusVocabulary.js";
+
+type Config = {
+  observationCodecs?: OmnipackObservationCodecs;
+  clock(): string; mintEvidenceReference(): `evidence:${string}`; approveTrackingUrl(url: string): boolean;
+};
+export function reconciliationObservation(row: OmnipackFulfilmentEvidence, config: Config, fulfillmentRef?: string): Extract<FulfillmentReconciliationObservation, { kind: "found" | "unmapped" }> {
+  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) as "provider_received" | "picking" | "packed" | "in_transit" | "delivered" | "exception";
+  const event = ({ provider_received: "shipment.accepted", picking: "order.processing_started", packed: "order.picked", in_transit: "order.shipped", delivered: "order.delivered", exception: "parcel.exception" } as const)[status];
+  const occurredAt = normalizeReconciliationTimestamp(row.updatedAt);
+  const evidence = { provider: "omnipack" as const, 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: OmnipackClient, config: Config, ready: () => ReturnType<typeof refusal> | null): FulfillmentObservationPagePort {
+  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" as const, 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/src/fulfillment/postgresDispatchStore.ts

@@ -21,7 +21,7 @@ export function createPostgresFulfillmentDispatchStore(db: PgExecutor, 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 as DispatchRecord | undefined ?? null;
     },
     claim: input => nativeCall(db, 'fulfillment_dispatch_claim', [input.requestKey, input.fulfillmentRef, input.orderRef, input.parcelRef, input.mode, JSON.stringify(dispatchEvidence(input.evidence))]),

package/src/fulfillment/postgresShipmentSpine.ts

@@ -1,3 +1,5 @@
+import type { FulfillmentObservationCodecs } from "./contracts/index.js";
+import { safeDiagnosticCode } from "./dispatchProjection.js";
 import { nativeCall } from './postgresDispatchStore.js';
 import { projectObservation } from './observationProjection.js';
 import type { PgExecutor as PgQueryExecutor } from './postgresDispatchStore.js';
@@ -64,6 +66,8 @@ const RAISE_EXCEPTION_SQL = `
 
 export interface PostgresFulfillmentShipmentSpineOptions {
   portKey: string;
+  approveTrackingUrl?(url: string): boolean;
+  observationCodecs?: FulfillmentObservationCodecs;
   evidenceChannel?: "poll" | "push";
   requiredProviderType?: "simulator";
 }
@@ -115,7 +119,7 @@ export function createPostgresFulfillmentShipmentSpinePort(
   };
 
   return {
-    localPersistence: localPersistence(executor),
+    localPersistence: localPersistence(executor, options.approveTrackingUrl, options.observationCodecs),
     createShipment(request) {
       return callCreate(executor, portKey, [
         request.idempotencyKey,
@@ -296,7 +300,7 @@ function asRecord(value: unknown): Record<string, unknown> | null {
 }
 
 /** G17 native local persistence, composed on the same injected executor. */
-function localPersistence(executor: PgQueryExecutor) {
+function localPersistence(executor: PgQueryExecutor, approveTrackingUrl?: (url: string) => boolean, observationCodecs?: FulfillmentObservationCodecs) {
   return {
     async readLocalFulfillmentState(ref: string) {
       const result = await executor.query(`SELECT shipment.status,shipment.handed_over_at,
@@ -305,15 +309,28 @@ function localPersistence(executor: PgQueryExecutor) {
       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: string) {
+      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: string) {
+      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: string) {
+      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: import('./contracts/index.js').FulfillmentObservation) {
-      const safe = projectObservation(observation);
+      const safe = projectObservation(observation, approveTrackingUrl, observationCodecs);
       return nativeCall<{ replayed: boolean }>(executor,'fulfillment_record_observation',[safe.eventKey,safe.correlation.fulfillmentRef,JSON.stringify(safe),safe.firstReceivedAt]);
     },
     async recordStatusEvidence(ref: { fulfillmentRef: string }, observation: import('./contracts/index.js').FulfillmentObservation) {
       return nativeCall<{ replayed: boolean }>(executor,'fulfillment_record_status_evidence',[observation.eventKey,ref.fulfillmentRef]);
     },
-    async markProcessed(eventKey: string, outcome: { status: 'processed' | 'ignored'; refusal?: import('./contracts/index.js').FulfillmentRefusal }) {
+    async markProcessed(eventKey: string, outcome: { status: 'processed' | 'ignored'; refusal?: import('./contracts/index.js').FulfillmentRefusal; supersededCause?: string }) {
       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/src/fulfillment/postgresStockSyncPort.ts

@@ -17,14 +17,14 @@ export function createPostgresFulfillmentStockSyncPort(db: PgExecutor, options:
       const row = result.rows[0];
       if (!row) return null;
       const cursor = row.cursor as Partial<SyncCursor>;
-      return { status: row.status as SyncCursor['status'], lastStockSyncedAt: timestamp(row.last_stock_synced_at), lastMovementOccurredAt: timestamp(row.last_movement_occurred_at),
+      return { ...cursor, status: row.status as SyncCursor['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]);
+      [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) return new Map();
@@ -52,7 +52,10 @@ export function createPostgresFulfillmentStockSyncPort(db: PgExecutor, 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/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";
 
@@ -16,16 +16,20 @@ export async function runFulfillmentDispatchWorker(input: {
   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 { 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 +39,35 @@ 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";
+        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 ??= 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 +76,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 +95,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 +103,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 +120,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;
 }