@openlup/platform 0.22.0 → 0.23.0

package/src/fulfillment/dispatchProjection.ts

@@ -1,18 +1,103 @@
-import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchResult } from "./contracts/index.js";
+import { createHash } from "node:crypto";
+import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentOperationError } from "./contracts/index.js";
 
+/** Machine identities only: arbitrary exception prose, URLs and credentials are omitted. */
+export function safeDiagnosticCode(value: unknown): string | null {
+  return reference(value) && typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_]{0,95}$/u.test(value) ? value : null;
+}
+export function localFailureReason(stage: string, error: unknown, privacy = durableStrings()): string {
+  if (!error || typeof error !== "object") return stage;
+  const fields = error as { code?: unknown; causeCode?: unknown; causeMessage?: unknown; message?: unknown };
+  const diagnostic = (value: unknown) => typeof value === "string" ? privacy.token(value, safeDiagnosticCode) : null;
+  const ownCode = diagnostic(fields.code), causeCode = diagnostic(fields.causeCode), causeMessage = diagnostic(fields.causeMessage);
+  const messagePattern = /^([A-Za-z][A-Za-z0-9_]*)(?::([A-Z0-9]{5}))?$/u;
+  const safeMessage = typeof fields.message === "string" ? privacy.token(fields.message, value => messagePattern.test(value) ? value : null) : null;
+  const message = safeMessage?.match(messagePattern);
+  const cause = causeMessage ?? (message && (message[2] || /_(?:failed|down|missing|invalid|conflict|not_found)$/u.test(message[1]!)) ? safeDiagnosticCode(message[1]) : null);
+  const code = causeCode ?? ownCode ?? message?.[2];
+  return [stage, cause, code].filter(Boolean).join(":");
+}
+export function operationError(error: Omit<FulfillmentOperationError, "cause"> & { cause?: unknown }): FulfillmentOperationError {
+  const privacy = durableStrings(error.redactedFieldCount);
+  const code = privacy.token(error.code, safeDiagnosticCode) ?? "operation_failed";
+  const cause = typeof error.cause === "string" ? privacy.token(error.cause,
+    value => /^ack(?::[A-Za-z0-9_]{1,96}){0,2}$/u.test(value) ? value.slice(0,180) : null) : null;
+  return { code, status: Number.isInteger(error.status) && error.status! >= 100 && error.status! <= 599 ? error.status : null,
+    retryable: error.retryable === true, mayHaveSucceeded: error.mayHaveSucceeded === true,
+    ...(cause ? { cause } : {}), ...(privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}) };
+}
+// The fulfillment opaque-ID rule; never accept free-form metadata as a reference.
+export const reference = (value: unknown): string | null => typeof value === "string"
+  && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) ? value : null;
+/** Opaque by default; an explicit allowlist can admit wider incumbent references. */
+export function admittedReference(value: string | null | undefined, approve?: (value: string) => boolean): string | null {
+  if (typeof value !== "string" || /[\p{Cc}\p{Cf}]/u.test(value)) return null;
+  const admitted = approve ? approve(value) : reference(value) !== null;
+  const text = value.trim();
+  return admitted && text && text.length <= 256 && !/[@]|[a-z][a-z0-9+.-]*:\/\//iu.test(text) ? text : null;
+}
+const isoDate = (value: string | null | undefined): string | null => typeof value === "string"
+  && /^\d{4}-\d\d-\d\d$/u.test(value) && Number.isFinite(Date.parse(value))
+  && new Date(value).toISOString().slice(0, 10) === value ? value : null;
+/** One counted sanitizer for durable projections; codecs are explicit host policy. */
+export function durableStrings(priorCount = 0) {
+  let count = Number.isSafeInteger(priorCount) && priorCount > 0 ? priorCount : 0;
+  return {
+    token(value: string | null | undefined, codec: (value: string) => string | null = reference) {
+      if (value == null) return null;
+      const safe = codec(value);
+      if (safe === null) count += 1;
+      return safe;
+    },
+    get redactedFieldCount() { return count; },
+  };
+}
 /** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
 export function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence {
+  const privacy = durableStrings(evidence.redactedFieldCount ?? evidence.transcript?.redactedFieldCount);
+  const sanitize = privacy.token;
+  const commandFingerprint = evidence.commandFingerprint;
+  const source = evidence.contactRevision.source;
+  const providerRef = sanitize(evidence.providerRef) ?? "redacted", carrierRef = sanitize(evidence.carrierRef), serviceRef = sanitize(evidence.serviceRef);
+  const mode = evidence.mapping ? (sanitize(evidence.mapping.mode) ?? "shadow") as NonNullable<DispatchEvidence["mapping"]>["mode"] : null;
+  const transcript = evidence.transcript ? {
+    itemCount: evidence.transcript.items.length,
+    items: evidence.transcript.items.map(item => ({ skuRef: sanitize(item.skuRef) ?? "redacted", quantity: Number.isSafeInteger(item.quantity) && item.quantity > 0 ? item.quantity : 0,
+      lotRef: sanitize(item.lotRef), expirationDate: sanitize(item.expirationDate, isoDate) })),
+    deliveryKind: evidence.transcript.deliveryKind === "parcel-locker" ? "parcel-locker" as const : "courier" as const,
+    pickupPointRef: sanitize(evidence.transcript.pickupPointRef),
+    ...(privacy.redactedFieldCount > 0 ? { redactedFieldCount: privacy.redactedFieldCount } : {}),
+  } : null;
   return {
-    commandFingerprint: evidence.commandFingerprint,
-    contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source: evidence.contactRevision.source, revision: evidence.contactRevision.revision },
-    providerRef: evidence.providerRef, carrierRef: evidence.carrierRef, serviceRef: evidence.serviceRef,
+    commandFingerprint,
+    contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source, revision: evidence.contactRevision.revision },
+    providerRef, carrierRef, serviceRef,
+    ...(transcript ? { transcript } : privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}),
+    ...(evidence.mapping ? { mapping: { source: "dispatch_worker" as const, mode: mode!, shadowMode: evidence.mapping.mode === "shadow" } } : {}),
   };
 }
+/** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
+export function shadowDispatchEvidence(request: FulfillmentDispatchRequest): DispatchEvidence {
+  if (!request.selection.providerRef || !request.lines.length || request.lines.some(line => !Number.isSafeInteger(line.quantity) || line.quantity <= 0)) throw new Error("dispatch_shadow_command_invalid");
+  return dispatchEvidence({ commandFingerprint: createHash("sha256").update(JSON.stringify(request)).digest("hex"),
+    contactRevision: request.contactRevision, providerRef: request.selection.providerRef,
+    carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef,
+    transcript: { itemCount: request.lines.length, items: request.lines.map(line => ({ skuRef: line.skuRef, quantity: line.quantity,
+      lotRef: line.lotRef ?? null, expirationDate: line.expirationDate ?? null })),
+      deliveryKind: request.selection.deliveryKind, pickupPointRef: request.selection.pickupPoint?.id ?? null } });
+}
 export function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult {
+  const privacy = durableStrings(result.redactedFieldCount);
+  const externalRef = result.kind === "accepted" ? privacy.token(result.externalRef) ?? "redacted" : null;
+  const refusal = result.kind !== "accepted" ? { reason: (privacy.token(result.refusal.reason) ?? "malformed") as typeof result.refusal.reason,
+    phase: (privacy.token(result.refusal.phase) ?? "normalize") as typeof result.refusal.phase, retryable: result.refusal.retryable } : null;
+  const redactions = privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {};
+  const error = result.error ? { error: operationError({ ...result.error, mayHaveSucceeded: result.kind !== "not_dispatched" }) } : {};
   switch (result.kind) {
-    case "accepted": return { kind: "accepted", externalRef: result.externalRef, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, evidence: dispatchEvidence(result.evidence) };
-    case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
-    case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: { reason: result.refusal.reason, phase: result.refusal.phase, retryable: result.refusal.retryable } };
+    case "accepted": return { kind: "accepted", externalRef: externalRef!, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, ...redactions, evidence: dispatchEvidence(result.evidence), ...error,
+      ...(result.recovery ? { recovery: { source: "persisted_acceptance", proof: "persisted_external_ref", noProviderPost: true } } : {}) };
+    case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal!, ...redactions, ...error };
+    case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: refusal!, ...redactions, ...error };
   }
 }
 export function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & { externalRef: string } {

package/src/fulfillment/index.ts

@@ -5,9 +5,10 @@ export { createOutboxOrderPaidFulfillmentHandler } from "./paidHandoff.js";
 export { collectPaidFulfillmentRecoveryCandidates } from "./paidFulfillmentRecovery.js";
 export { runFulfillmentDispatchWorker } from "./providerDispatchWorker.js";
 export { createFulfillmentCommandLedger } from "./providerCommandLedger.js";
-export { verifyAndNormalizeFulfillmentObservation } from "./verifiedIngress.js";
+export type { FulfillmentIngressCounts, FulfillmentIngressResult } from "./verifiedIngress.js";
+export { verifyAndNormalizeFulfillmentObservation, fulfillmentIngressHttpResult } from "./verifiedIngress.js";
 export { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
-export { reconcileFulfillmentObservations } from "./providerReconciliationWorker.js";
+export { reconcileFulfillmentObservations, runFulfillmentReconciliationPage } from "./providerReconciliationWorker.js";
 export { runFulfillmentStockSyncWorker } from "./providerStockSyncWorker.js";
 export { runFulfillmentProductSyncWorker } from "./providerProductSyncWorker.js";
 export { createFulfillmentLowStockEvidenceHandler } from "./lowStockEvidenceHandler.js";

package/src/fulfillment/migrations.ts

@@ -5,4 +5,5 @@ export const FULFILLMENT_MIGRATIONS = [
   { position: 51, catalogPath: "db/platform/migrations/20260819150000_fulfillment_shipment_sequence.sql", sha256: "906706cf66a6a555aa1219b12eb674d937eaa099abde6da18766310af43aaa9f", url: new URL("../../sql/20260819150000_fulfillment_shipment_sequence.sql", import.meta.url) },
   { position: 73, catalogPath: "db/platform/migrations/20261022080000_fulfillment_command_ledger.sql", sha256: "c6806906cdb0b6931b29f7a5c7c800016e98d04e6ea956f3c1e219a6cdb7e9d1", url: new URL("../../sql/20261022080000_fulfillment_command_ledger.sql", import.meta.url) },
   { position: 74, catalogPath: "db/platform/migrations/20261022090000_fulfillment_delivery_alignment.sql", sha256: "d9966ae79fe77a0feae8317dc5b46ef2d8196dd0790b1cd0ee1b06ab58061499", url: new URL("../../sql/20261022090000_fulfillment_delivery_alignment.sql", import.meta.url) },
+  { position: 76, catalogPath: "db/platform/migrations/20261022165000_fulfillment_stock_evidence_replay_reopen.sql", sha256: "6d132dec2820047f4e337bcf752b3d884600ccc12de03887fe6d6aa5575bc1db", url: new URL("../../sql/20261022165000_fulfillment_stock_evidence_replay_reopen.sql", import.meta.url) },
 ] as const;

package/src/fulfillment/observationProjection.ts

@@ -1,32 +1,83 @@
-import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation } from "./contracts/index.js";
+import { z } from "zod";
+import type { CanonicalLocalFulfillmentStatus, FulfillmentObservation, FulfillmentObservationCodecs } from "./contracts/index.js";
 import { parseFulfillmentFact } from "./normalizedFulfillmentFacts.js";
+import { admittedReference, durableStrings, reference } from "./dispatchProjection.js";
 import { FULFILLMENT_STATUS_MAP } from "./statusMap.js";
 
-export function projectCorrelation(value: FulfillmentObservation["correlation"]): FulfillmentObservation["correlation"] {
-  const { orderRef, fulfillmentRef, externalRef, orderNumber, providerFulfillmentRef, parcelRef } = value;
-  return { orderRef, fulfillmentRef, externalRef, orderNumber, providerFulfillmentRef, parcelRef };
+type Privacy = ReturnType<typeof durableStrings>;
+const timestamp = z.iso.datetime({ offset: true });
+export function projectCorrelation(value: FulfillmentObservation["correlation"], privacy = durableStrings(), codecs: FulfillmentObservationCodecs = {}): FulfillmentObservation["correlation"] {
+  const token = (value: string | null) => privacy.token(value, text => admittedReference(text, codecs.approveReference));
+  return { orderRef: value.orderRef, fulfillmentRef: value.fulfillmentRef, externalRef: token(value.externalRef),
+    orderNumber: token(value.orderNumber), providerFulfillmentRef: token(value.providerFulfillmentRef), parcelRef: value.parcelRef };
+}
+
+export function projectProviderStatus(value: NonNullable<FulfillmentObservation["providerStatus"]>, privacy = durableStrings()): NonNullable<FulfillmentObservation["providerStatus"]> {
+  return { primary: privacy.token(value.primary), subStatus: privacy.token(value.subStatus) };
+}
+export type PollEvidence = Pick<FulfillmentObservation, "correlation" | "eventKey" | "providerStatus" | "diagnostics">;
+function pollEvidence(value: PollEvidence, privacy: Privacy, codecs: FulfillmentObservationCodecs = {}): PollEvidence {
+  // Host identities and keys composed from admitted parts are already authoritative.
+  return { eventKey: value.eventKey, correlation: projectCorrelation(value.correlation, privacy, codecs),
+    ...(value.providerStatus ? { providerStatus: projectProviderStatus(value.providerStatus, privacy) } : {}) };
+}
+/** Unknown-status quarantine/ACK evidence has the same privacy boundary as observations. */
+export function projectPollEvidence(value: PollEvidence): PollEvidence {
+  const privacy = durableStrings(value.diagnostics?.redactedFieldCount);
+  const safe = pollEvidence(value, privacy);
+  return { ...safe, ...(privacy.redactedFieldCount ? { diagnostics: { redactedFieldCount: privacy.redactedFieldCount } } : {}) };
+}
+
+/** One URL policy: strict default, optional adopter codec, and approval at every sink. */
+export function publicTrackingUrl(value: string, approve?: (url: string) => boolean, codec?: (url: string) => string | null): string | null {
+  try {
+    const candidate = codec ? codec(value) : value;
+    if (!candidate) return null;
+    const url = new URL(candidate);
+    return url.protocol === "https:" && !url.username && !url.password && (codec || (!url.search && !url.hash)) && approve?.(url.href) ? url.href : null;
+  } catch { return null; }
+}
+export function projectTrackingReference(value: FulfillmentObservation["trackingRefs"][number], privacy = durableStrings(), approveTrackingUrl?: (url: string) => boolean, codecs: FulfillmentObservationCodecs = {}) {
+  const token = (value: string | null) => privacy.token(value, text => admittedReference(text, codecs.approveReference));
+  const trackingNumber = token(value.trackingNumber);
+  if (trackingNumber === null) return null;
+  const serviceRef = token(value.serviceRef);
+  // Even an opaque-looking derived carrier is unsafe when its service was refused.
+  const carrierRef = privacy.token(value.carrierRef, text => value.serviceRef !== null && serviceRef === null ? null : reference(text));
+  return { trackingNumber, carrierRef, serviceRef,
+    publicUrl: privacy.token(value.publicUrl, url => publicTrackingUrl(url, approveTrackingUrl, codecs.trackingUrl)) };
 }
 
 /** New boundary projection: arbitrary adapter properties are never durable. */
-export function projectObservation(value: FulfillmentObservation): FulfillmentObservation {
+export function projectObservation(value: FulfillmentObservation, approveTrackingUrl?: (url: string) => boolean, codecs: FulfillmentObservationCodecs = {}): FulfillmentObservation {
+  const privacy = durableStrings(value.diagnostics?.redactedFieldCount), token = privacy.token;
   const diagnostics: NonNullable<FulfillmentObservation["diagnostics"]> = {};
+  if (value.diagnostics?.admission) {
+    const count = (value: number) => Number.isSafeInteger(value) && value > 0 ? value : 0;
+    diagnostics.admission = { rejectedTrackingRefs: count(value.diagnostics.admission.rejectedTrackingRefs), rejectedTrackingUrls: count(value.diagnostics.admission.rejectedTrackingUrls) };
+  }
   if (value.diagnostics?.refusal) {
     const { reason, phase, retryable } = value.diagnostics.refusal;
-    diagnostics.refusal = { reason, phase, retryable };
+    diagnostics.refusal = { reason: token(reason) as typeof reason, phase: token(phase) as typeof phase, retryable };
   }
   if (value.diagnostics?.stockContention) diagnostics.stockContention = { sqlState: "55P03", phase: "provider_stock_consumed", retryable: true };
-  if (value.diagnostics?.annotation) diagnostics.annotation = value.diagnostics.annotation;
+  if (value.diagnostics?.annotation) diagnostics.annotation = token(value.diagnostics.annotation) as typeof value.diagnostics.annotation;
   if (value.diagnostics?.recoveredPickedReceipt) {
     const { receiptRef, closed } = value.diagnostics.recoveredPickedReceipt;
     diagnostics.recoveredPickedReceipt = { receiptRef, closed };
   }
-  return {
-    fact: parseFulfillmentFact(value.fact), eventKind: value.eventKind, eventKey: value.eventKey,
-    firstReceivedAt: value.firstReceivedAt,
-    correlation: projectCorrelation(value.correlation),
-    trackingRefs: value.trackingRefs.map(({ trackingNumber, carrierRef, serviceRef, publicUrl }) => ({ trackingNumber, carrierRef, serviceRef, publicUrl })),
-    ...(Object.keys(diagnostics).length ? { diagnostics } : {}),
+  const fact = parseFulfillmentFact(value.fact);
+  const safe = {
+    ...pollEvidence(value, privacy, codecs),
+    fact: { ...fact, mapperVersion: token(fact.mapperVersion) ?? "redacted" }, eventKind: (token(value.eventKind) ?? "redacted") as FulfillmentObservation["eventKind"],
+    firstReceivedAt: timestamp.parse(value.firstReceivedAt),
+    trackingRefs: value.trackingRefs.flatMap(ref => {
+      const projected = projectTrackingReference(ref, privacy, approveTrackingUrl, codecs);
+      return projected ? [projected] : [];
+    }),
   };
+  if (privacy.redactedFieldCount) diagnostics.redactedFieldCount = privacy.redactedFieldCount;
+  return { ...safe, ...(Object.keys(diagnostics).length ? { diagnostics } : {}) };
 }
 
 const HANDOVER_STATUSES: ReadonlySet<string> = new Set(

package/src/fulfillment/omnipack/client.ts

@@ -45,7 +45,7 @@ export interface OmnipackClient {
   createProduct(payload: Record<string, unknown>, sku: string): Promise<OmnipackProductCreatedEvidence>;
   getProduct(sku: string): Promise<OmnipackProductEvidence>;
   createProductPack(sku: string, payload: Record<string, unknown>, ean: string): Promise<OmnipackProductPackCreatedEvidence>;
-  getStock(): Promise<OmnipackStockEvidence[]>;
+  getStock(options?: { refuseRedirectRetry: boolean }): Promise<OmnipackStockEvidence[]>;
   getStockMovements(params?: OmnipackQueryParams): Promise<OmnipackStockMovementEvidence[]>;
   getFulfilmentsPage(params?: OmnipackQueryParams): Promise<{ rows: OmnipackFulfilmentEvidence[]; complete: boolean }>;
   getFulfilments(params?: OmnipackQueryParams): Promise<OmnipackFulfilmentEvidence[]>;
@@ -87,8 +87,8 @@ export function createOmnipackClient(
       return mapOmnipackProductPackCreatedResponse(body, sku, ean);
     },
 
-    async getStock() {
-      return mapOmnipackStockResponse(await requestJson(fetchImpl, config, "getStock", "/stock", { method: "GET" }));
+    async getStock(options) {
+      return mapOmnipackStockResponse(await requestJson(fetchImpl, config, "getStock", "/stock", { method: "GET" }, options?.refuseRedirectRetry));
     },
 
     async getStockMovements(params) {
@@ -98,6 +98,7 @@ export function createOmnipackClient(
         "getStockMovements",
         withQuery("/stock-movements", params),
         { method: "GET" },
+        true,
       ));
     },
 
@@ -141,10 +142,14 @@ async function requestJson(
   operation: string,
   path: string,
   init: RequestInit,
+  refuseRedirectRetry = false,
 ): Promise<unknown> {
   const method = (init.method ?? "GET").toUpperCase();
   const attempts = method === "GET" ? config.safeReadRetries + 1 : 1;
-  let lastError: unknown = null;
+  // Dispatch/readback diagnostics must not change product-sync or stock retry policy.
+  const diagnoseRedirectFailure = refuseRedirectRetry || operation === "createOrder"
+    || operation === "getFulfilments" || operation === "getFulfilmentRequests";
+  let lastError: OmnipackProviderError | null = null;
 
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     let submitted = false;
@@ -161,7 +166,7 @@ async function requestJson(
       lastError = new OmnipackProviderError({
         operation,
         status: response.status,
-        code: readProviderErrorCode(body) ?? `http_${response.status}`,
+        code: refuseRedirectRetry && response.status >= 300 && response.status < 400 ? "redirect_refused" : readProviderErrorCode(body) ?? `http_${response.status}`,
         retryable,
         mayHaveSucceeded: mayPostHaveSucceeded(method, response.status),
       });
@@ -173,11 +178,11 @@ async function requestJson(
         : new OmnipackProviderError({
           operation,
           status: null,
-          code: "network_error",
+          code: diagnoseRedirectFailure && isRedirectRefusal(error) ? "redirect_refused" : "network_error",
           retryable,
           mayHaveSucceeded: submitted && mayPostHaveSucceeded(method, null),
         });
-      if (!retryable) throw lastError;
+      if (!retryable || (refuseRedirectRetry && lastError.code === "redirect_refused")) throw lastError;
     }
   }
 
@@ -256,3 +261,10 @@ function readProviderErrorCode(body: unknown): string | null {
 function isRetryableStatus(status: number): boolean {
   return status === 408 || status === 429 || status >= 500;
 }
+
+// Fetch implementations expose redirect refusal as an exception, sometimes through cause.
+// Inspect it only to select a closed diagnostic; no exception text leaves this adapter.
+function isRedirectRefusal(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return /redirect/i.test(error.message) || (error.cause instanceof Error && /redirect/i.test(error.cause.message));
+}

package/src/fulfillment/omnipack/index.ts

@@ -1,14 +1,46 @@
+import { z } from "zod";
+import { publicTrackingUrl } from "../observationProjection.js";
 import type { DispatchEvidence, FulfillmentCapabilityDescriptor, FulfillmentDispatchPort, FulfillmentDispatchRequest,
-  FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider } from "../contracts/index.js";
+  FulfillmentLabelPort, FulfillmentObservationPort, FulfillmentReadbackPort, FulfillmentObservationPagePort, FulfillmentStockSyncProvider, FulfillmentProductSyncProvider, FulfillmentRefusal } from "../contracts/index.js";
 import { createOmnipackClient, OmnipackProviderError } from "./client.js";
 import { omnipackFulfillmentCapabilities } from "./capabilities.js";
 import { buildOmnipackDispatchCommand, serializeOmnipackDispatchPayload, stableDispatchHash } from "./omnipackDispatchPayload.js";
 import { mapOmnipackWebhookPayload } from "./mappers.js";
 import { verifyOmnipackWebhookToken, type OmnipackWebhookRouteEvent } from "./omnipackWebhookPayload.js";
-import { localStatusFor, normalizeStatus } from "./omnipackStatusVocabulary.js";
-import { digest, eventKind, observation, reference, refusal, timestamp } from "./observation.js";
+import { createReconciliationPagePort, reconciliationObservation } from "./reconciliation.js";
+import { dispatchEvidence, operationError } from "../dispatchProjection.js";
+import { correlationReference, digest, eventKind, observation, reference, refusal, timestamp, type OmnipackObservationCodecs } from "./observation.js";
 export { omnipackFulfillmentCapabilities } from "./capabilities.js";
 
+// Internal error projection: retain diagnostics without exposing a provider payload or cause.
+class OmnipackSyncError extends Error implements FulfillmentRefusal {
+  readonly phase = "sync";
+  readonly retryable: boolean;
+  readonly providerFailure: boolean;
+  readonly status: number | null;
+  readonly code: string | null;
+
+  constructor(readonly reason: FulfillmentRefusal["reason"], operation: string, error?: unknown) {
+    super(reason === "io_failure" ? `OmniPack request failed: ${operation}` : `OmniPack sync refused: ${reason}`);
+    this.name = "OmnipackSyncError";
+    this.providerFailure = reason === "io_failure";
+    this.retryable = error instanceof OmnipackProviderError ? error.retryable : false;
+    this.status = error instanceof OmnipackProviderError ? error.status : null;
+    this.code = error instanceof OmnipackProviderError ? error.code : null;
+  }
+}
+function syncFailure(operation: string, error: unknown): OmnipackSyncError {
+  return error instanceof OmnipackSyncError ? error : new OmnipackSyncError("io_failure", operation, error);
+}
+function requireProductSku(sku: string): void {
+  // URL resolution collapses dot segments; encodeURIComponent rejects lone surrogates.
+  // Keep these SKUs in the listing so the worker counts a visible per-SKU failure.
+  try {
+    if (!sku.trim() || sku === "." || sku === "..") throw Error();
+    encodeURIComponent(sku);
+  } catch { throw new OmnipackSyncError("malformed", "getProduct"); }
+}
+
 /** Node-only, explicit construction. Secrets are supplied per call, never retained as values. */
 export interface OmnipackFulfillmentAdapterConfig {
   http: {
@@ -27,6 +59,7 @@ export interface OmnipackFulfillmentAdapterConfig {
   mintEvidenceReference: () => `evidence:${string}`;
   mintSyncRunId: () => string;
   approveTrackingUrl: (url: string) => boolean;
+  observationCodecs?: OmnipackObservationCodecs;
   /** Writes occur only through deliberate calls; scheduled composition must remain pull-only. */
   product?: { resolvePushMetadata: (sku: string) => Promise<Record<string, unknown> | null> };
 }
@@ -38,6 +71,7 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
   label: FulfillmentLabelPort;
   observation: FulfillmentObservationPort;
   readback: FulfillmentReadbackPort;
+  reconciliation: FulfillmentObservationPagePort;
   stockSync: FulfillmentStockSyncProvider;
   productSync: FulfillmentProductSyncProvider;
 } {
@@ -72,12 +106,12 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
     return null;
   };
   const requireSync = () => {
-    if (!capabilities.selected || !capabilities.readiness.ready) throw refusal(capabilities.selected ? "not_ready" : "disabled", "sync");
+    if (!capabilities.selected || !capabilities.readiness.ready) throw new OmnipackSyncError(capabilities.selected ? "not_ready" : "disabled", "selection");
   };
   const syncIdentity = () => {
     const syncRunId = reference(config.mintSyncRunId());
     const collectedAt = timestamp(config.clock());
-    if (!syncRunId || !collectedAt) throw refusal("malformed", "sync");
+    if (!syncRunId || !collectedAt) throw new OmnipackSyncError("malformed", "sync");
     return { providerRef: capabilities.providerRef, syncRunId, collectedAt, sourceRevision: null, revisionSource: "collection" as const };
   };
   // Shared computation: host metadata and serialized bytes live only for this call.
@@ -101,9 +135,12 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
         selectedDelivery: { providerKind: capabilities.providerRef, carrierKind: request.selection.carrierRef,
           serviceCode: request.selection.serviceRef, deliveryKind: request.selection.deliveryKind, pickupPoint: request.selection.pickupPoint } }, lines,
     });
-    const evidence: DispatchEvidence = { commandFingerprint: command.requestFingerprint,
+    const evidence: DispatchEvidence = dispatchEvidence({ commandFingerprint: command.requestFingerprint,
       contactRevision: { schemaVersion: request.contactRevision.schemaVersion, source: request.contactRevision.source, revision: request.contactRevision.revision },
-      providerRef: capabilities.providerRef, carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef };
+      providerRef: capabilities.providerRef, carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef,
+      transcript: { itemCount: command.providerPayload.items.length,
+        items: command.providerPayload.items.map(item => ({ skuRef: item.sku, quantity: item.quantity, lotRef: item.lotNumber ?? null, expirationDate: item.expirationDate ?? null })),
+        deliveryKind: request.selection.deliveryKind, pickupPointRef: request.selection.pickupPoint?.id ?? null } });
     return { body: command.body, evidence };
   };
   return {
@@ -122,7 +159,7 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
         let requestCommandDigest: string;
         try {
           // Validate the closed evidence and its request-bound values without consulting preparation state.
-          if (Object.keys(evidence).length !== 5 || Object.keys(evidence.contactRevision).length !== 3
+          if (Object.keys(evidence).length !== 6 || Object.keys(evidence.contactRevision).length !== 3
             || typeof evidence.commandFingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(evidence.commandFingerprint)
             || !reference(evidence.providerRef)
             || !reference(evidence.carrierRef) || !reference(evidence.serviceRef)
@@ -135,6 +172,7 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
             || evidence.providerRef !== request.selection.providerRef
             || evidence.carrierRef !== request.selection.carrierRef || evidence.serviceRef !== request.selection.serviceRef) throw Error();
           evidenceKey = serializeOmnipackDispatchPayload(evidence).body;
+          if (serializeOmnipackDispatchPayload(dispatchEvidence(evidence)).body !== evidenceKey) throw Error();
           requestCommandDigest = commandDigest(request);
           const submitted = submissions.get(evidence.commandFingerprint);
           if (submitted) {
@@ -151,7 +189,7 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
           let command;
           try {
             command = await buildCommand(commandRequest);
-            if (command.evidence.commandFingerprint !== fingerprint) throw Error();
+            if (command.evidence.commandFingerprint !== fingerprint || serializeOmnipackDispatchPayload(command.evidence).body !== evidenceKey) throw Error();
           } catch {
             // A stale or unresolved command has never reached credentials or HTTP.
             submissions.delete(fingerprint);
@@ -166,9 +204,10 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
             return { kind: "accepted" as const, externalRef, evidence: structuredClone(command.evidence),
               providerAttemptKey: `attempt:${proof}`, labelKey: `label:${proof}` };
           } catch (error) {
-            return error instanceof OmnipackProviderError && !error.mayHaveSucceeded
-              ? { kind: "not_dispatched" as const, effectMayHaveSucceeded: false as const, refusal: refusal("io_failure", "dispatch") }
-              : { kind: "unknown" as const, effectMayHaveSucceeded: true as const, refusal: refusal("io_failure", "dispatch") };
+            const detail = operationError(error instanceof OmnipackProviderError ? error : { code: "provider_dispatch_failed", status: null, retryable: true, mayHaveSucceeded: true });
+            return !detail.mayHaveSucceeded
+              ? { kind: "not_dispatched" as const, effectMayHaveSucceeded: false as const, refusal: refusal("io_failure", "dispatch", detail.retryable), error: detail }
+              : { kind: "unknown" as const, effectMayHaveSucceeded: true as const, refusal: refusal("io_failure", "dispatch", detail.retryable), error: detail };
           } finally {
             command.body = "";
             submissions.get(fingerprint)!.completed = true;
@@ -198,13 +237,27 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
           if (!payload || typeof payload !== "object" || Array.isArray(payload)) return { kind: "refused", refusal: refusal("malformed", "normalize") };
           if ("event" in payload && (typeof payload.event !== "string" || !eventKind(payload.event)))
             return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
-          const evidence = mapOmnipackWebhookPayload(payload, config.notification.expectedEvent);
+          const original = payload as Record<string, unknown>;
+          // Validate calendar fields here only; keep compact offsets and local
+          // timestamps accepted by the base parser, without rewriting key bytes.
+          if (original.occurredAt !== undefined && original.occurredAt !== null
+            && (typeof original.occurredAt !== "string" || !timestamp(original.occurredAt)
+              || !z.iso.datetime({ offset: true, local: true }).safeParse(original.occurredAt.replace(/([+-]\d{2})(\d{2})$/u, "$1:$2")).success))
+            return { kind: "refused", refusal: refusal("malformed", "normalize"), diagnostics: { invalidTimestamp: true } };
+          const rejectedCorrelationRefs = [original.orderId, original.providerOrderId, original.orderNumber, original.fulfilmentNumber]
+            .filter(value => value !== undefined && value !== null && (typeof value !== "string" || !correlationReference(value, config.observationCodecs))).length;
+          if (rejectedCorrelationRefs)
+            return { kind: "refused", refusal: refusal("missing_correlation", "normalize"), diagnostics: { rejectedCorrelationRefs } };
+          const evidence = mapOmnipackWebhookPayload(payload, config.notification.expectedEvent, value => correlationReference(value, config.observationCodecs) !== null, {
+            service: value => correlationReference(value, config.observationCodecs) !== null,
+            url: value => publicTrackingUrl(value, config.approveTrackingUrl, config.observationCodecs?.trackingUrl) !== null,
+          });
           const event = eventKind(evidence.event);
           if (!event || event !== config.notification.expectedEvent) return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
-          if (![evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => reference(value)))
+          if (![evidence.providerOrderId, evidence.orderNumber, evidence.fulfilmentNumber].some(value => correlationReference(value, config.observationCodecs)))
             return { kind: "refused", refusal: refusal("missing_correlation", "normalize") };
           return { kind: "verified", observation: observation({ evidence, event, receivedAt: input.receivedAt,
-            rawDigest: digest(rawBody), evidenceRef: config.mintEvidenceReference(), source: "provider_webhook", approveTrackingUrl: config.approveTrackingUrl }) };
+            rawDigest: digest(rawBody), evidenceRef: config.mintEvidenceReference(), source: "provider_webhook", approveTrackingUrl: config.approveTrackingUrl, observationCodecs: config.observationCodecs }) };
         } catch { return { kind: "refused", refusal: refusal("malformed", "normalize") }; }
       },
     },
@@ -219,44 +272,37 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
           const matches = collection.rows.filter(row => input.mode === "parcel"
             ? row.fulfilmentNumber === input.externalRef : row.providerOrderId === input.externalRef);
           if (matches.length !== 1) return { kind: "unknown", refusal: refusal("local_missing", "readback") };
-          const row = matches[0]!;
-          const normalized = normalizeStatus(row.status);
-          if (!normalized) return { kind: "unknown", refusal: refusal("unsupported_event", "readback") };
-          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 evidence = { provider: "omnipack" as const, event, providerOrderId: row.providerOrderId, orderNumber: row.orderNumber,
-            fulfilmentNumber: row.fulfilmentNumber, occurredAt: row.updatedAt, trackingNumbers: row.trackingNumbers,
-            trackingReferences: row.trackingReferences, shippingMethods: [] };
-          return { kind: "found", externalRef: input.externalRef!, createdAt: timestamp(row.createdAt), updatedAt: timestamp(row.updatedAt),
-            observation: observation({ evidence, event, status, fulfillmentRef: input.fulfillmentRef, receivedAt: config.clock(),
-              rawDigest: digest(JSON.stringify(evidence)), evidenceRef: config.mintEvidenceReference(), source: "provider_reconciliation", approveTrackingUrl: config.approveTrackingUrl }) };
+          const mapped = reconciliationObservation(matches[0]!, config, input.fulfillmentRef);
+          return mapped.kind === "unmapped" ? { kind: "unknown", refusal: refusal("unsupported_event", "readback") } : { ...mapped, externalRef: input.externalRef! };
         } catch { return { kind: "unknown", refusal: refusal("io_failure", "readback") }; }
       },
     },
+    reconciliation: createReconciliationPagePort(client, config, () => !capabilities.selected || !capabilities.readiness.ready
+      ? refusal(capabilities.selected ? "not_ready" : "disabled", "readback") : null),
     stockSync: {
       async getStock() {
         requireSync();
         try {
           const identity = syncIdentity();
-          return (await client.getStock()).map(row => {
+          return (await client.getStock({ refuseRedirectRetry: true })).map((row, itemIndex) => {
             const skuRef = reference(row.sku);
-            if (!skuRef) throw refusal("malformed", "sync");
+            if (!skuRef) return { kind: "rejected" as const, itemIndex, reason: "invalid_sku_ref" as const };
             return { ...identity, skuRef, quantityKind: "snapshot" as const, totalQuantity: row.totalQuantity,
               forSaleQuantity: row.forSaleQuantity, reservedOrUnavailableQuantity: row.reservedOrUnavailableQuantity };
           });
-        } catch { throw refusal("io_failure", "sync"); }
+        } catch (error) { throw stockFailure(error, "get_stock"); }
       },
       async getStockMovements(input) {
         requireSync();
         try {
           const identity = syncIdentity();
-          return (await client.getStockMovements(input)).map(row => {
+          return (await client.getStockMovements(input)).map((row, itemIndex) => {
             const skuRef = reference(row.sku);
-            if (!skuRef) throw refusal("malformed", "sync");
+            if (!skuRef) return { kind: "rejected" as const, itemIndex, reason: "invalid_sku_ref" as const };
             return { ...identity, skuRef, quantityKind: "movement" as const, quantity: row.quantity, occurredAt: timestamp(row.occurredAt),
               operationType: reference(row.operationType), documentRef: reference(row.warehouseDocumentNumber), lotRef: reference(row.lotNumber), expirationDate: /^\d{4}-\d\d-\d\d$/u.test(row.expirationDate ?? "") ? row.expirationDate : null };
           });
-        } catch { throw refusal("io_failure", "sync"); }
+        } catch (error) { throw stockFailure(error, "get_stock_movements"); }
       },
     },
     productSync: {
@@ -267,23 +313,24 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
           if (!metadata) return null;
           await client.createProduct(metadata, sku);
           return { replayed: false };
-        } catch { throw refusal("io_failure", "sync"); }
+        } catch (error) { throw syncFailure("createProduct", error); }
       },
       async getProductPacks(sku) {
         requireSync();
-        try { return (await client.getProduct(sku)).packs.filter(pack => /^\d{8,14}$/u.test(pack.ean) && Number.isSafeInteger(pack.quantity) && pack.quantity > 0).map(pack => ({ ean: pack.ean, quantity: pack.quantity })); }
-        catch { throw refusal("io_failure", "sync"); }
+        requireProductSku(sku);
+        try { return (await client.getProduct(sku)).packs.map(pack => ({ ean: pack.ean, quantity: pack.quantity })); }
+        catch (error) { throw syncFailure("getProduct", error); }
       },
       async addProductPack(sku, pack) {
         requireSync();
-        if (!/^\d{8,14}$/u.test(pack.ean) || !Number.isSafeInteger(pack.quantity) || pack.quantity <= 0) throw refusal("malformed", "sync");
+        if (!/^\d{8,14}$/u.test(pack.ean) || !Number.isSafeInteger(pack.quantity) || pack.quantity <= 0) throw new OmnipackSyncError("malformed", "sync");
         try { await client.createProductPack(sku, { ean: pack.ean, quantity: pack.quantity }, pack.ean); }
-        catch { throw refusal("io_failure", "sync"); }
+        catch (error) { throw syncFailure("createProductPack", error); }
       },
       async listStockedSkus() {
         requireSync();
-        try { return [...new Set((await client.getStock()).flatMap(row => reference(row.sku) ? [row.sku] : []))]; }
-        catch { throw refusal("io_failure", "sync"); }
+        try { return [...new Set((await client.getStock()).flatMap(row => row.sku.trim() ? [row.sku] : []))]; }
+        catch (error) { throw syncFailure("getStock", error); }
       },
     },
   };
@@ -310,3 +357,13 @@ function commandDigest(request: FulfillmentDispatchRequest): string {
       pickupPointId: request.selection.pickupPoint?.id ?? null },
   });
 }
+
+/** Translate only the contributed client's typed error; never copy a message or payload. */
+function stockFailure(error: unknown, operation: "get_stock" | "get_stock_movements") {
+  const failure = syncFailure(operation === "get_stock" ? "getStock" : "getStockMovements", error);
+  if (!(error instanceof OmnipackProviderError)) return failure;
+  const retryable = error.code !== "redirect_refused" && (error.retryable || error.code === "network_error");
+  return Object.assign(failure, { retryable, providerError: {
+    operation, status: error.status, code: error.code, retryable,
+  } });
+}

package/src/fulfillment/omnipack/mappers.ts

@@ -58,6 +58,9 @@ export interface OmnipackFulfilmentRequestEvidence {
 }
 
 export interface OmnipackWebhookEvidence {
+  rejectedTrackingRefs?: number;
+  rejectedServices?: number;
+  rejectedTrackingUrls?: number;
   provider: "omnipack";
   event: string;
   providerOrderId: string | null;
@@ -177,13 +180,31 @@ export function mapOmnipackFulfilmentRequestsResponse(body: unknown): OmnipackFu
   });
 }
 
-export function mapOmnipackWebhookPayload(body: unknown, fallbackEvent = ""): OmnipackWebhookEvidence {
+export function mapOmnipackWebhookPayload(body: unknown, fallbackEvent = "", admitTrackingNumber?: (value: string) => boolean,
+  admitMetadata?: { service(value: string): boolean; url(value: string): boolean }): OmnipackWebhookEvidence {
   const payload = asRecord(body);
   const shipments = readArray(payload.shipments).map(asRecord);
-  const trackingReferences = trackingReferencesFrom({ shipments });
+  let rejectedTrackingRefs = 0, rejectedServices = 0, rejectedTrackingUrls = 0;
+  // Count every supplied spelling before extraction, tracking refusal or first-wins deduplication.
+  if (admitMetadata) for (const row of shipments) {
+    for (const value of [row.shippingMethod, row.service]) {
+      if (value != null && (typeof value !== "string" || !admitMetadata.service(value))) rejectedServices++;
+    }
+    for (const value of [row.trackingUrl, row.trackingURL, row.trackingLink, row.publicTrackingUrl]) {
+      if (value != null && (typeof value !== "string" || !admitMetadata.url(value))) rejectedTrackingUrls++;
+    }
+  }
+  // Admit and count original entries before the contributed extractor trims/deduplicates.
+  const admitted = admitTrackingNumber ? shipments.filter(row => {
+    if (admitTrackingNumber(readString(row.trackingNo) || readString(row.trackingNumber))) return true;
+    rejectedTrackingRefs++; return false;
+  }) : shipments;
+  const trackingReferences = trackingReferencesFrom({ shipments: admitted });
   return {
     provider: "omnipack",
     event: readString(payload.event) || fallbackEvent,
+    ...(rejectedTrackingRefs ? { rejectedTrackingRefs } : {}),
+    ...(admitMetadata ? { rejectedServices, rejectedTrackingUrls } : {}),
     providerOrderId: readNullableString(payload.orderId) ?? readNullableString(payload.providerOrderId),
     orderNumber: readNullableString(payload.orderNumber),
     fulfilmentNumber: readNullableString(payload.fulfilmentNumber),