@openlup/platform 0.22.0 → 0.24.0

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,30 @@ 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 and minute precision 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 })
+                .or(z.iso.datetime({ offset: true, local: true, precision: -1 }))
+                .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 +275,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 +316,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 +360,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),

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]),
   };
 }