@openlup/platform 0.22.0 → 0.24.0

package/src/fulfillment/providerStockSyncWorker.ts

@@ -1,11 +1,14 @@
 import { aggregateAtpCompatibleStock, emptyLocal, stockMovementWindow } from "./providerStockAvailability.js";
-import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, LocalStock, StockSnapshot, StockMovement } from "./contracts/index.js";
+import type { FulfillmentStockSyncPort, FulfillmentStockSyncProvider, LocalStock, StockSnapshot, StockMovement, SyncCursor } from "./contracts/index.js";
 type Threshold = Parameters<FulfillmentStockSyncPort["resolveLowStockEvidence"]>[0]["activeThresholdKinds"][number];
 interface StockSyncResult {
   ok: boolean; checked: number; updated: number; mismatches: number; reservationCoverage: number;
   unclassified: number; lowStock: number; movements: number; replayed: number; failures: number;
   providerCalls: number; readBacks: number; skipped: boolean; syncRunId: string;
   lastMovementOccurredAt: string | null; reason?: string;
+  rejected: number; items: NonNullable<SyncCursor["items"]>[number][];
+  providerError?: NonNullable<SyncCursor["error"]>["providerError"];
+  refusal?: NonNullable<SyncCursor["refusal"]>;
 }
 export async function runFulfillmentStockSyncWorker(input: {
   port: FulfillmentStockSyncPort;
@@ -26,6 +29,8 @@ export async function runFulfillmentStockSyncWorker(input: {
   const syncRunId = input.compatibility.syncRunId(now);
   const result: StockSyncResult = {
     ok: true,
+    rejected: 0,
+    items: [],
     checked: 0,
     updated: 0,
     mismatches: 0,
@@ -42,152 +47,218 @@ export async function runFulfillmentStockSyncWorker(input: {
     lastMovementOccurredAt: null,
   };
 
-  const previousCursor = await input.port.readCursor();
-
-  // Stale-sync alert: if the last successful sync aged past the threshold, open a stale_sync
-  // low-stock evidence row (evidence/warn — never blocks sales); a healthy run resolves it
-  // below. A never-synced state (no prior cursor) is not "stale".
-  const lastSyncedMs = previousCursor?.lastStockSyncedAt ? Date.parse(previousCursor.lastStockSyncedAt) : null;
-  const staleGapHours =
-    lastSyncedMs !== null && !Number.isNaN(lastSyncedMs) ? (now.getTime() - lastSyncedMs) / 3_600_000 : null;
-  const syncIsStale = staleGapHours !== null && staleGapHours >= staleThresholdHours;
-  if (syncIsStale) {
-    await input.port.recordLowStockEvidence({
-      requestKey: input.compatibility.staleKey(previousCursor!.lastStockSyncedAt!),
-      skuRef: input.compatibility.staleEvidenceSku,
-      thresholdKind: "stale_sync",
-      severity: "warning",
-      providerForSaleQuantity: 0,
-      localAvailableQuantity: 0,
+  const alerts: NonNullable<SyncCursor["alerts"]>[number][] = [];
+  let stage = "cursor_read_failed";
+  let operationalReason: string | undefined;
+  let staleSync: SyncCursor["staleSync"];
+  let recoverStaleSync = false;
+  let previousCursor: SyncCursor | null = null;
+  let rejectedStockResponse = false;
+  const currentCoverageGapSkus = new Set<string>();
+  try {
+    previousCursor = await input.port.readCursor();
+
+    // Stale-sync alert: if the last successful sync aged past the threshold, open a stale_sync
+    // low-stock evidence row (evidence/warn — never blocks sales); a healthy run resolves it
+    // below. A never-synced state (no prior cursor) is not "stale".
+    const lastSyncedMs = previousCursor?.lastStockSyncedAt ? Date.parse(previousCursor.lastStockSyncedAt) : null;
+    const staleGapHours =
+      lastSyncedMs !== null && !Number.isNaN(lastSyncedMs) ? (now.getTime() - lastSyncedMs) / 3_600_000 : null;
+    const syncIsStale = staleGapHours !== null && staleGapHours >= staleThresholdHours;
+    recoverStaleSync = !syncIsStale;
+    if (syncIsStale) {
+      staleSync = { gapHours: Math.round(staleGapHours! * 10) / 10, thresholdHours: staleThresholdHours, detectedAt: now.toISOString() };
+      stage = "stock_evidence_write_failed";
+      alerts.push({ skuRef: input.compatibility.staleEvidenceSku, thresholdKind: "stale_sync", severity: "warning",
+        providerForSaleQuantity: 0, localAvailableQuantity: 0, ...staleSync });
+      await input.port.recordLowStockEvidence({
+        requestKey: input.compatibility.staleKey(previousCursor!.lastStockSyncedAt!),
+        skuRef: input.compatibility.staleEvidenceSku,
+        thresholdKind: "stale_sync",
+        severity: "warning",
+        providerForSaleQuantity: 0,
+        localAvailableQuantity: 0,
+        syncRunId,
+      });
+    }
+
+    stage = "cursor_write_failed";
+    await input.port.recordCursor({
       syncRunId,
+      status: "running",
+      lastStockSyncedAt: null,
+      lastMovementOccurredAt: null,
+      continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
+      coverageGapSkus: previousCursor?.coverageGapSkus ?? [], refusal: null,
     });
-  }
 
-  await input.port.recordCursor({
-    status: "running",
-    lastStockSyncedAt: null,
-    lastMovementOccurredAt: null,
-    continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
-    coverageGapSkus: [], refusal: null,
-  });
+    stage = "stock_read_failed";
+    result.providerCalls += 1;
+    const [localStock, providerStock] = await Promise.all([
+      input.port.readLocalInventoryStock(now.toISOString()),
+      input.provider.getStock(),
+    ]);
+    const stockItems: { stock: StockSnapshot; itemIndex: number }[] = [];
+    for (const [itemIndex, item] of providerStock.entries()) {
+      if ("kind" in item && item.kind === "rejected") {
+        result.rejected += 1;
+        result.failures += 1;
+        result.items.push({ kind: "stock", itemIndex: item.itemIndex, skuRef: null, status: "rejected", reason: item.reason });
+      } else if ("skuRef" in item && item.skuRef.trim()) {
+        stockItems.push({ stock: item, itemIndex });
+      }
+    }
+    const skus = [...new Set(stockItems.map(({ stock }) => stock.skuRef))];
+    rejectedStockResponse = providerStock.length > 0 && stockItems.length === 0;
+    stage = "stock_inventory_read_failed";
+    const [inventoryClasses, activeReservations] = await Promise.all([
+      input.port.readSkuInventoryClasses(skus),
+      input.port.readActiveReservations(skus, now.toISOString()),
+    ]);
 
-  const [localStock, providerStock] = await Promise.all([
-    input.port.readLocalInventoryStock(now.toISOString()),
-    input.provider.getStock(),
-  ]);
-  result.providerCalls += 1;
-
-  const stockItems = providerStock.filter((item) => item.skuRef.trim());
-  const skus = [...new Set(stockItems.map((item) => item.skuRef))];
-  const [inventoryClasses, activeReservations] = await Promise.all([
-    input.port.readSkuInventoryClasses(skus),
-    input.port.readActiveReservations(skus, now.toISOString()),
-  ]);
-
-  const movements = await input.provider.getStockMovements({ ...stockMovementWindow(previousCursor, now, input.compatibility.timeZone), size: input.movementBatchSize });
-  result.providerCalls += 1;
-  result.movements = movements.length;
-  result.lastMovementOccurredAt = latestOccurredAt(movements);
-
-  const localBySku = aggregateAtpCompatibleStock(localStock, now);
-  const coverageCandidates: Array<{
-    stock: StockSnapshot;
-    local: LocalStock;
-    activeReserved: number;
-  }> = [];
-  const currentCoverageGapSkus = new Set<string>();
-  const packagingSkus = new Set<string>();
-  const previousCoverageGapSkus = previousCursor?.status === "succeeded"
-    ? readStringSet(previousCursor.coverageGapSkus)
-    : new Set<string>();
+    stage = "stock_movements_read_failed";
+    result.providerCalls += 1;
+    const movementRows = await input.provider.getStockMovements({ ...stockMovementWindow(previousCursor, now, input.compatibility.timeZone), size: input.movementBatchSize });
+    const movements: StockMovement[] = [];
+    for (const item of movementRows) {
+      if ("kind" in item && item.kind === "rejected") {
+        result.rejected += 1;
+        result.failures += 1;
+        result.items.push({ kind: "movement", itemIndex: item.itemIndex, skuRef: null, status: "rejected", reason: item.reason });
+      } else if ("skuRef" in item) {
+        movements.push(item);
+      }
+    }
+    if (rejectedStockResponse || (result.rejected > 0 && stockItems.length + movements.length === 0)) {
+      result.ok = false;
+      result.reason = "invalid_sku_ref";
+    }
+    result.movements = movements.length;
+    result.lastMovementOccurredAt = latestOccurredAt(movements);
 
-  for (const stock of stockItems) {
-    try {
-      const local = localBySku.get(stock.skuRef) ?? emptyLocal(stock.skuRef);
-      const inventoryClass = inventoryClasses.get(stock.skuRef) ?? null;
-      const activeReserved = activeReservations.get(stock.skuRef) ?? 0;
-      const staleAfter = new Date(now.getTime() + staleThresholdHours * 3_600_000).toISOString();
-      const current = await input.port.recordProviderStockCurrent({
-        requestKey: input.compatibility.currentKey(syncRunId, stock.skuRef),
-        snapshot: stock, inventoryClass, lastSyncedAt: now.toISOString(), staleAfter,
-      });
-      const snapshot = await input.port.recordStockSnapshot({
-        requestKey: input.compatibility.snapshotKey(syncRunId, stock.skuRef),
-        snapshot: stock, local, mismatchKind: "none", inventoryClass,
-      });
+    const localBySku = aggregateAtpCompatibleStock(localStock, now);
+    const coverageCandidates: Array<{
+      stock: StockSnapshot;
+      local: LocalStock;
+      activeReserved: number;
+    }> = [];
+    const packagingSkus = new Set<string>();
+    const previousCoverageGapSkus = previousCursor?.status === "succeeded"
+      ? readStringSet(previousCursor.coverageGapSkus)
+      : new Set<string>();
+
+    for (const { stock, itemIndex } of stockItems) {
+      try {
+        const local = localBySku.get(stock.skuRef) ?? emptyLocal(stock.skuRef);
+        const inventoryClass = inventoryClasses.get(stock.skuRef) ?? null;
+        const activeReserved = activeReservations.get(stock.skuRef) ?? 0;
+        const staleAfter = new Date(now.getTime() + staleThresholdHours * 3_600_000).toISOString();
+        stage = "stock_current_write_failed";
+        const current = await input.port.recordProviderStockCurrent({
+          requestKey: input.compatibility.currentKey(syncRunId, stock.skuRef),
+          snapshot: stock, inventoryClass, lastSyncedAt: now.toISOString(), staleAfter,
+        });
+        stage = "snapshot_write_failed";
+        const snapshot = await input.port.recordStockSnapshot({
+          requestKey: input.compatibility.snapshotKey(syncRunId, stock.skuRef),
+          snapshot: stock, local, mismatchKind: "none", inventoryClass,
+        });
 
-      result.checked += 1;
-      result.updated += (snapshot.replayed ? 0 : 1) + (current.replayed ? 0 : 1);
-      if (snapshot.replayed) result.replayed += 1;
-      if (current.replayed) result.replayed += 1;
-      if (snapshot.readBack) result.readBacks += 1;
-      if (current.readBack) result.readBacks += 1;
-      if (inventoryClass === null) result.unclassified += 1;
-      if (inventoryClass === "packaging") packagingSkus.add(stock.skuRef);
-      if (inventoryClass === "sellable") {
-        coverageCandidates.push({ stock, local, activeReserved });
-        if (activeReserved > stock.forSaleQuantity) currentCoverageGapSkus.add(stock.skuRef);
+        result.items.push({ itemIndex, skuRef: stock.skuRef, status: "recorded", activeReserved,
+          sellableNow: inventoryClass === "sellable" ? Math.max(0, stock.forSaleQuantity - activeReserved - local.safetyStock) : null,
+          coverageGapQuantity: Math.max(0, activeReserved - stock.forSaleQuantity) });
+        result.checked += 1;
+        result.updated += (snapshot.replayed ? 0 : 1) + (current.replayed ? 0 : 1);
+        if (snapshot.replayed) result.replayed += 1;
+        if (current.replayed) result.replayed += 1;
+        if (snapshot.readBack) result.readBacks += 1;
+        if (current.readBack) result.readBacks += 1;
+        if (inventoryClass === null) result.unclassified += 1;
+        if (inventoryClass === "packaging") packagingSkus.add(stock.skuRef);
+        if (inventoryClass === "sellable") {
+          coverageCandidates.push({ stock, local, activeReserved });
+          if (activeReserved > stock.forSaleQuantity) currentCoverageGapSkus.add(stock.skuRef);
+        }
+      } catch (error) {
+        result.ok = false;
+        result.failures += 1;
+        const reason = safeReason(error, stage);
+        operationalReason ??= reason;
+        result.items.push({ itemIndex, skuRef: stock.skuRef, status: "failed", reason });
       }
-    } catch (error) {
-      result.ok = false;
-      result.failures += 1;
-      result.reason = result.reason ?? "stock_sync_operation_failed";
     }
-  }
 
-  if (result.ok) {
-    for (const { stock, local, activeReserved } of coverageCandidates) {
-      const localAvailable = availableQuantity(local);
-      const confirmedCoverageGap = currentCoverageGapSkus.has(stock.skuRef) && previousCoverageGapSkus.has(stock.skuRef);
-      const lowStockSignals = lowStockSignalsFor(stock, local, activeReserved, confirmedCoverageGap);
-      const activeThresholdKinds: Threshold[] = lowStockSignals.map((signal) => signal.thresholdKind);
-      if (currentCoverageGapSkus.has(stock.skuRef) && !activeThresholdKinds.includes("reservation_coverage")) {
-        activeThresholdKinds.push("reservation_coverage");
+    if (result.ok) {
+      for (const { stock, local, activeReserved } of coverageCandidates) {
+        const localAvailable = availableQuantity(local);
+        const confirmedCoverageGap = currentCoverageGapSkus.has(stock.skuRef) && previousCoverageGapSkus.has(stock.skuRef);
+        const lowStockSignals = lowStockSignalsFor(stock, local, activeReserved, confirmedCoverageGap);
+        const activeThresholdKinds: Threshold[] = lowStockSignals.map((signal) => signal.thresholdKind);
+        if (currentCoverageGapSkus.has(stock.skuRef) && !activeThresholdKinds.includes("reservation_coverage")) {
+          activeThresholdKinds.push("reservation_coverage");
+        }
+        for (const signal of lowStockSignals) {
+          alerts.push({ skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
+            providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, detectedAt: now.toISOString(),
+            activeReserved, coverageGapQuantity: Math.max(0, activeReserved - stock.forSaleQuantity) });
+          stage = "stock_evidence_write_failed";
+          const evidence = await input.port.recordLowStockEvidence({
+            requestKey: input.compatibility.lowStockKey(stock.skuRef, signal.thresholdKind),
+            skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
+            providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, syncRunId,
+          });
+          if (evidence.replayed) result.replayed += 1;
+          result.lowStock += evidence.replayed ? 0 : 1;
+          if (signal.thresholdKind === "reservation_coverage") result.reservationCoverage += 1;
+        }
+        stage = "stock_evidence_resolve_failed";
+        await input.port.resolveLowStockEvidence({
+          skuRef: stock.skuRef,
+          activeThresholdKinds,
+          syncRunId,
+        });
       }
-      for (const signal of lowStockSignals) {
-        const evidence = await input.port.recordLowStockEvidence({
-          requestKey: input.compatibility.lowStockKey(stock.skuRef, signal.thresholdKind),
-          skuRef: stock.skuRef, thresholdKind: signal.thresholdKind, severity: signal.severity,
-          providerForSaleQuantity: stock.forSaleQuantity, localAvailableQuantity: localAvailable, syncRunId,
+      for (const sku of packagingSkus) {
+        stage = "stock_evidence_resolve_failed";
+        await input.port.resolveLowStockEvidence({
+          skuRef: sku,
+          activeThresholdKinds: [],
+          syncRunId,
         });
-        if (evidence.replayed) result.replayed += 1;
-        result.lowStock += evidence.replayed ? 0 : 1;
-        if (signal.thresholdKind === "reservation_coverage") result.reservationCoverage += 1;
       }
-      await input.port.resolveLowStockEvidence({
-        skuRef: stock.skuRef,
-        activeThresholdKinds,
-        syncRunId,
-      });
-    }
-    for (const sku of packagingSkus) {
-      await input.port.resolveLowStockEvidence({
-        skuRef: sku,
-        activeThresholdKinds: [],
-        syncRunId,
-      });
     }
+  } catch (error) {
+    result.ok = false;
+    result.failures += 1;
+    result.providerError = providerDiagnostic(error);
+    if (stage === "stock_read_failed" || stage === "stock_movements_read_failed") result.refusal = admissionRefusal(error);
+    operationalReason ??= result.providerError ? `provider_${result.providerError.operation}_failed:${result.providerError.code}` : result.refusal?.reason ?? safeReason(error, stage);
   }
 
+  result.reason = operationalReason ?? result.reason;
+  if (!result.ok) result.refusal ??= { reason: result.failures === result.rejected ? "malformed" : "io_failure", phase: "sync", retryable: result.providerError?.retryable ?? result.failures > result.rejected };
   await input.port.recordCursor({
-    status: result.ok ? "succeeded" : "failed",
+    status: result.ok ? "succeeded" : "failed", syncRunId,
     lastStockSyncedAt: result.ok ? now.toISOString() : null,
     lastMovementOccurredAt: result.lastMovementOccurredAt,
     continuation: { nextRef: null, startLocalDate: null, endLocalDate: null },
-    coverageGapSkus: result.ok ? [...currentCoverageGapSkus].sort() : [],
-    refusal: result.ok ? null : { reason: "io_failure", phase: "sync", retryable: true },
+    coverageGapSkus: result.ok ? [...currentCoverageGapSkus].sort() : rejectedStockResponse ? previousCursor?.coverageGapSkus ?? [] : [],
+    refusal: result.refusal ?? null,
+    error: result.ok ? null : { reason: result.reason!, ...(result.providerError ? { providerError: result.providerError } : {}) },
+    counts: { checked: result.checked, updated: result.updated, movements: result.movements, rejected: result.rejected,
+      failures: result.failures, providerCalls: result.providerCalls, readBacks: result.readBacks },
+    items: result.items, alerts, staleSync,
   });
-
-  // Recovery: a healthy run (succeeded, not itself stale) closes any open stale_sync row.
-  if (result.ok && !syncIsStale) {
-    await input.port.resolveLowStockEvidence({
-      skuRef: input.compatibility.staleEvidenceSku,
-      activeThresholdKinds: [],
-      syncRunId,
-
-    });
+  // Recovery follows the durable succeeded cursor; a failed cleanup leaves the completed run intact.
+  if (result.ok && recoverStaleSync) {
+    try {
+      await input.port.resolveLowStockEvidence({
+        skuRef: input.compatibility.staleEvidenceSku,
+        activeThresholdKinds: [],
+        syncRunId,
+      });
+    } catch { /* Best-effort cleanup must not undo the completed run. */ }
   }
-
   return result;
 }
 
@@ -220,3 +291,28 @@ function latestOccurredAt(movements: StockMovement[]): string | null {
     .filter((value): value is string => Boolean(value))
     .sort((a, b) => Date.parse(b) - Date.parse(a))[0] ?? null;
 }
+
+/** Keep the operation's closed identity and SQLSTATE only, never arbitrary exception prose. */
+function safeReason(error: unknown, operation: string): string {
+  const code = error && typeof error === "object" && "code" in error ? error.code : null;
+  if (typeof code === "string" && /^[0-9A-Z]{5}$/.test(code)) return `${operation}:${code}`;
+  const known = error instanceof Error ? error.message.match(new RegExp(`^${operation}:([0-9A-Z]{5})$`)) : null;
+  return known ? `${operation}:${known[1]}` : operation;
+}
+function providerDiagnostic(error: unknown): StockSyncResult["providerError"] {
+  if (!error || typeof error !== "object" || !("providerError" in error)) return undefined;
+  const detail = error.providerError;
+  if (!detail || typeof detail !== "object" || !("operation" in detail) || !("code" in detail) || !("status" in detail) || !("retryable" in detail)) return undefined;
+  if (detail.operation !== "get_stock" && detail.operation !== "get_stock_movements") return undefined;
+  if (typeof detail.code !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(detail.code)) return undefined;
+  return { operation: detail.operation, code: detail.code,
+    status: typeof detail.status === "number" && Number.isInteger(detail.status) && detail.status >= 100 && detail.status <= 599 ? detail.status : null,
+    retryable: detail.retryable === true };
+}
+
+function admissionRefusal(error: unknown): StockSyncResult["refusal"] {
+  if (!error || typeof error !== "object" || !("reason" in error) || !("phase" in error) || !("retryable" in error)) return undefined;
+  if (error.phase !== "sync" || typeof error.retryable !== "boolean") return undefined;
+  if (error.reason !== "disabled" && error.reason !== "not_ready" && error.reason !== "malformed") return undefined;
+  return { reason: error.reason, phase: error.phase, retryable: error.retryable };
+}

package/src/fulfillment/providerTrackingReferences.ts

@@ -1,4 +1,4 @@
-import type { FulfillmentTrackingReference } from "./contracts/index.js";
+import type { FulfillmentTrackingReference, FulfillmentObservationCodecs } from "./contracts/index.js";
 
 export function trackingReferenceComplete(ref: FulfillmentTrackingReference): boolean {
   return Boolean(ref.carrierRef && ref.publicUrl && ref.serviceRef);
@@ -7,7 +7,8 @@ export function trackingReferenceComplete(ref: FulfillmentTrackingReference): bo
 export function enrichTrackingReference(
   ref: FulfillmentTrackingReference,
   deliveryCarrier: { carrierRef: string | null; serviceRef: string | null } | null,
-  codecs: {
+  codecs: FulfillmentObservationCodecs & {
+    approveTrackingUrl?(url: string): boolean;
     normalizeCarrier(input: { carrierRef: string | null; serviceRef: string | null }): string | null;
     publicUrl(carrierRef: string | null, trackingNumber: string): string | null;
   },

package/src/fulfillment/verifiedIngress.ts

@@ -1,20 +1,35 @@
-import type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import type { FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import { safeDiagnosticCode } from "./dispatchProjection.js";
 import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
 import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
 import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
 
 type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
 type DispatchRef = { orderRef: string; fulfillmentRef: string; dispatchRef: string; externalRef: string | null };
+export interface FulfillmentIngressCounts { invalidTimestamps: number; rejectedCorrelationRefs: number; rejectedTrackingRefs: number; rejectedTrackingUrls: number }
+export type FulfillmentIngressResult = { counts: FulfillmentIngressCounts } & (
+  | { kind: "refused"; receiptId: null; refusal: FulfillmentRefusal; diagnostics?: { invalidTimestamp?: true; rejectedCorrelationRefs?: number } }
+  | { kind: "processed" | "ignored" | "superseded"; receiptId: string; observation: FulfillmentObservation; replayed: boolean; trackingRefs: number; trackingReadBacks: number; supersededCause?: string });
+/** Safe response classes only; the host owns HTTP and localized message text. */
+export function fulfillmentIngressHttpResult(result: FulfillmentIngressResult): { status: 200 | 400 | 403 | 503; messageClass: "accepted" | "bad_request" | "forbidden" | "upstream_unavailable" } {
+  if (result.kind !== "refused") return { status: 200, messageClass: "accepted" };
+  if (result.refusal.reason === "untrusted") return { status: 403, messageClass: "forbidden" };
+  if (result.refusal.reason === "disabled" || result.refusal.reason === "not_ready" || result.refusal.retryable)
+    return { status: 503, messageClass: "upstream_unavailable" };
+  return { status: 400, messageClass: "bad_request" };
+}
 /** Adapter verification owns auth-before-parse; the host owns durable replay. */
 export async function verifyAndNormalizeFulfillmentObservation(input: {
   enabled: boolean;
+  approveTrackingUrl?(url: string): boolean;
+  observationCodecs?: FulfillmentObservationCodecs;
   provider: FulfillmentObservationPort;
   verification: Parameters<FulfillmentObservationPort["verifyAndNormalize"]>[0];
   localPersistence: {
     /** G17: atomic insert by eventKey; retries keep the first stored firstReceivedAt. */
-    recordObservation(observation: FulfillmentObservation): Promise<{ replayed: boolean }>;
+    recordObservation(observation: FulfillmentObservation): Promise<{ replayed: boolean; receiptId?: string }>;
     /** Idempotent; only called after completion or a classified superseding conflict. */
-    markProcessed(eventKey: string, outcome: { status: "processed" | "ignored"; refusal?: FulfillmentRefusal }): Promise<void>;
+    markProcessed(eventKey: string, outcome: { status: "processed" | "ignored"; refusal?: FulfillmentRefusal; supersededCause?: string }): Promise<void>;
   };
   lifecycle: {
     findDispatchRef(observation: FulfillmentObservation): Promise<DispatchRef | null>;
@@ -23,19 +38,34 @@ export async function verifyAndNormalizeFulfillmentObservation(input: {
     effects: EffectInput["port"];
     keys: { stock(ref: string): string; handoff(ref: string): string; tracking(eventKey: string, number: string): string };
     issueAccountingInvoice?(ref: string): Promise<void>;
+    /** Return a machine identity, never exception prose. */
+    supersededCause?(error: unknown): string | null;
     classifyFailure(error: unknown): "stock_contention" | "state_conflict" | "other";
     annotateStockContention?(eventKey: string, fulfillmentRef: string): Promise<void>;
   };
-}): Promise<{ kind: "refused"; refusal: FulfillmentRefusal } | { kind: "processed" | "ignored" | "superseded"; observation: FulfillmentObservation; replayed: boolean; trackingRefs: number; trackingReadBacks: number }> {
-  if (!input.enabled) return { kind: "refused", refusal: { reason: "disabled", phase: "verify", retryable: false } };
+}): Promise<FulfillmentIngressResult> {
+  const counts: FulfillmentIngressCounts = { invalidTimestamps: 0, rejectedCorrelationRefs: 0, rejectedTrackingRefs: 0, rejectedTrackingUrls: 0 };
+  if (!input.enabled) return { kind: "refused", receiptId: null, counts, refusal: { reason: "disabled", phase: "verify", retryable: false } };
   const verified = await input.provider.verifyAndNormalize(input.verification);
-  if (verified.kind === "refused") return verified;
-  const observation = projectObservation(verified.observation);
+  if (verified.kind === "refused") {
+    if (verified.diagnostics?.invalidTimestamp) counts.invalidTimestamps++;
+    const rejected = verified.diagnostics?.rejectedCorrelationRefs;
+    if (typeof rejected === "number" && Number.isSafeInteger(rejected) && rejected > 0) counts.rejectedCorrelationRefs = rejected;
+    return { kind: "refused", receiptId: null, refusal: verified.refusal, counts,
+      ...(counts.invalidTimestamps || counts.rejectedCorrelationRefs ? { diagnostics: {
+        ...(counts.invalidTimestamps ? { invalidTimestamp: true as const } : {}),
+        ...(counts.rejectedCorrelationRefs ? { rejectedCorrelationRefs: counts.rejectedCorrelationRefs } : {}),
+      } } : {}) };
+  }
+  const observation = projectObservation(verified.observation, input.approveTrackingUrl, input.observationCodecs);
+  counts.rejectedTrackingRefs = observation.diagnostics?.admission?.rejectedTrackingRefs ?? 0;
+  counts.rejectedTrackingUrls = observation.diagnostics?.admission?.rejectedTrackingUrls ?? 0;
   const inbound = await input.localPersistence.recordObservation(observation);
+  const receiptId = inbound.receiptId ?? observation.eventKey;
   const ref = await input.lifecycle.findDispatchRef(observation);
   if (!ref) {
     await input.localPersistence.markProcessed(observation.eventKey, { status: "ignored", refusal: { reason: "local_missing", phase: "apply", retryable: false } });
-    return { kind: "ignored", observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+    return { kind: "ignored", receiptId, counts, observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
   }
   const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
   if (!externalRef) throw new TypeError("fulfillment_dispatch_acceptance_external_ref_missing");
@@ -71,10 +101,13 @@ export async function verifyAndNormalizeFulfillmentObservation(input: {
     try { await applyFulfillmentObservationEffects(effects, observationStatusPolicy); }
     catch (error) {
       if (input.lifecycle.classifyFailure(error) !== "state_conflict") throw error;
-      await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
-      return { kind: "superseded", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+      const cause = input.lifecycle.supersededCause ? input.lifecycle.supersededCause(error)
+        : error && typeof error === "object" && "reason" in error ? error.reason : null;
+      const supersededCause = safeDiagnosticCode(cause) ?? "fulfillment_state_conflict";
+      await input.localPersistence.markProcessed(observation.eventKey, { status: "processed", supersededCause });
+      return { kind: "superseded", receiptId, counts, supersededCause, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
     }
   }
   await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
-  return { kind: "processed", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+  return { kind: "processed", receiptId, counts, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
 }