@openlup/platform 0.22.0 → 0.24.0

package/src/fulfillment/contracts/sync.ts

@@ -19,13 +19,24 @@ export interface SyncCursor {
   /** G15: successful sellable coverage gaps; legacy absent values read as []. */
   coverageGapSkus?: readonly string[];
   refusal: FulfillmentRefusal | null;
+  /** Per-entry bounded diagnostics and run evidence in the existing cursor JSON, never raw errors. */
+  syncRunId?: string;
+  counts?: { checked: number; updated: number; movements: number; rejected: number; failures: number; providerCalls: number; readBacks: number };
+  items?: readonly { kind?: "stock" | "movement"; itemIndex: number; skuRef: string | null; status: "recorded" | "failed" | "rejected"; reason?: string;
+    activeReserved?: number; sellableNow?: number | null; coverageGapQuantity?: number }[];
+  alerts?: readonly { skuRef: string; thresholdKind: Exclude<Threshold, "forecast">; severity: "info" | "warning" | "critical";
+    providerForSaleQuantity: number; localAvailableQuantity: number; detectedAt: string;
+    activeReserved?: number; coverageGapQuantity?: number; gapHours?: number; thresholdHours?: number }[];
+  staleSync?: { gapHours: number; thresholdHours: number; detectedAt: string };
+  error?: { reason: string; providerError?: { operation: "get_stock" | "get_stock_movements"; status: number | null; code: string; retryable: boolean } } | null;
 }
 export interface LocalStock { skuRef: string; onHand: number; reserved: number; unavailable: number; safetyStock: number }
 type Threshold = "safety_stock" | "reservation_coverage" | "forecast" | "stale_sync";
 type Conflict = "unknown_sku" | "ean_conflict" | "kind_quantity_conflict";
 export interface FulfillmentStockSyncProvider {
-  getStock(): Promise<StockSnapshot[]>;
-  getStockMovements(input?: { startLocalDate?: string; endLocalDate?: string; size?: number }): Promise<StockMovement[]>;
+  /** Rejected rows carry only their input index and a closed reason, never an unsafe reference. */
+  getStock(): Promise<(StockSnapshot | { kind: "rejected"; itemIndex: number; reason: "invalid_sku_ref" })[]>;
+  getStockMovements(input?: { startLocalDate?: string; endLocalDate?: string; size?: number }): Promise<(StockMovement | { kind: "rejected"; itemIndex: number; reason: "invalid_sku_ref" })[]>;
 }
 export interface FulfillmentStockSyncPort {
   readCursor(): Promise<SyncCursor | null>;

package/src/fulfillment/dispatchProjection.ts

@@ -1,18 +1,105 @@
-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,
+    ...(typeof error.submissionAttempted === "boolean" ? { submissionAttempted: error.submissionAttempted } : {}),
+    ...(typeof error.responseBodyRead === "boolean" ? { responseBodyRead: error.responseBodyRead } : {}),
+    ...(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, commandFingerprint?: string): 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: 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,43 +142,54 @@ 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;
+    let responseBodyRead: boolean | undefined;
+    const dispatchFacts = () => operation === "createOrder" ? { submissionAttempted: submitted,
+      ...(responseBodyRead !== undefined ? { responseBodyRead } : {}) } : {};
     try {
       const base = new URL(config.baseUrl);
       const url = new URL(path, base);
       if (url.origin !== base.origin || url.username || url.password || url.protocol !== "https:") throw new Error("Invalid fulfillment path");
       const response = await fetchWithTimeout(fetchImpl, url, config, init, () => { submitted = true; });
-      if (response.ok) return await readJsonBody(response);
+      responseBodyRead = false;
+      const body = await readJsonBody(response).then(value => { responseBodyRead = true; return value; }).catch(error => {
+        if (response.ok) throw error;
+        return null;
+      });
+      if (response.ok) return body;
 
       const retryable = method === "GET" && isRetryableStatus(response.status);
       // A failed body read cannot erase the rejection status already received.
-      const body = await readJsonBody(response).catch(() => null);
-      lastError = new OmnipackProviderError({
+      lastError = Object.assign(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),
-      });
+      }), dispatchFacts());
       if (!retryable || attempt === attempts) throw lastError;
     } catch (error) {
       const retryable = method === "GET" && attempt < attempts;
       lastError = submitted && error instanceof OmnipackProviderError
         ? error
-        : new OmnipackProviderError({
+        : Object.assign(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;
+        }), dispatchFacts());
+      if (!retryable || (refuseRedirectRetry && lastError.code === "redirect_refused")) throw lastError;
     }
   }
 
@@ -256,3 +268,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));
+}