@openlup/platform 0.25.0 → 0.27.0

package/src/commerce/fulfillmentEligibility.ts

@@ -0,0 +1,32 @@
+import type { CommerceFulfillmentEligibilityInput, OmsFulfillmentBlockReason } from "./contracts/state.js";
+
+export function evaluateCommerceFulfillmentEligibility(
+  input: CommerceFulfillmentEligibilityInput,
+): { allowed: boolean; reason: OmsFulfillmentBlockReason | null } {
+  if (input.activeHoldCount > 0) return { allowed: false, reason: "active_hold" };
+  if (!input.hasShippingAddress) return { allowed: false, reason: "missing_shipping_address" };
+  if (input.riskReviewRequired) return { allowed: false, reason: "risk_review" };
+  if (!["paid", "fulfillment_pending", "fulfilled"].includes(input.orderStatus)) {
+    return { allowed: false, reason: "order_not_paid" };
+  }
+  if (input.paymentStatus !== "succeeded") {
+    return { allowed: false, reason: "payment_not_succeeded" };
+  }
+  if (input.orderMode === "subscription_cycle" && input.subscriptionCycleStatus !== "paid") {
+    return { allowed: false, reason: "subscription_cycle_not_paid" };
+  }
+  if (
+    input.inventoryReviewRequired ||
+    ["missing", "released", "expired", "review_required"].includes(input.inventoryStatus ?? "not_checked")
+  ) {
+    return { allowed: false, reason: "inventory_review" };
+  }
+  return { allowed: true, reason: null };
+}
+
+export function mapOmsPaymentStatus(status: string | null): string {
+  if (!status) return "not_started";
+  if (status === "pending") return "processing";
+  if (status === "paid") return "succeeded";
+  return status as string;
+}

package/src/commerce/index.ts

@@ -0,0 +1,82 @@
+export type * from "./contracts/index.js";
+export { createOfferAvailabilitySchemas, offerAvailabilityRequestItems } from "./offerAvailabilitySchemas.js";
+export { hasSubscriptionRecoveryContext, resolveRecoveryDestination } from "./recoveryDestination.js";
+export * from "./errors.js";
+export * from "./orderDraftErrors.js";
+export { buildOrderDeliveryContact, uuidFromOrderRef, messageOf } from "./checkoutHelpers.js";
+export type { OrderDeliveryContactInput } from "./checkoutHelpers.js";
+export { CART_STATUSES, CHECKOUT_STATUSES, ORDER_DRAFT_STATUSES, ORDER_STATUSES, PAYMENT_STATUSES, OMS_FULFILLMENT_BLOCK_REASONS, OMS_INVENTORY_STATUSES } from "./contracts/state.js";
+export { evaluateCommerceFulfillmentEligibility, mapOmsPaymentStatus } from "./fulfillmentEligibility.js";
+export * from "./contractPrimitives.js";
+export { createCommerceSchemas } from "./schemas.js";
+export * from "./checkoutResumeSchemas.js";
+export * from "./customerDefaultsSnapshotSchemas.js";
+export * from "./configuratorIntentSchemas.js";
+export * from "./configuratorIntentPersistenceSchemas.js";
+export { CHECKOUT_CONTRACT_VERSION, ASYNC_CHECKOUT_STATUSES, checkoutKindSchema, checkoutActivationStatusSchema, asyncCheckoutStatusSchema, subscriptionActivationStatusSchema, invoiceBuyerSnapshotAddressCoreSchema, checkoutRequestCoreSchema, createCheckoutResponseSchemas, createCheckoutQuoteSchemas } from "./checkoutSchemas.js";
+export * from "./runtimeErrors.js";
+export type { CreateQuoteOptions, CommerceQuotePort } from "./ports.js";
+export * from "./orderMoney.js";
+export * from "./outboxEventSchemas.js";
+
+// M11 K3a OMS runtime surface.
+export * from "./model/omsAccountingVisibility.js";
+export * from "./model/omsBillingInvoiceBuyer.js";
+export * from "./model/omsOrderLineMoney.js";
+export * from "./model/omsPaymentMethodSummary.js";
+export * from "./model/omsReadModelCommunication.js";
+export * from "./model/omsReadModelHelpers.js";
+export * from "./model/omsReadModelList.js";
+export * from "./model/omsReadModelListSummary.js";
+export * from "./model/omsReadModelPricing.js";
+export * from "./model/omsReadModelRows.js";
+export * from "./model/omsFulfillmentDebug.js";
+export * from "./model/omsOperationalLadder.js";
+export * from "./model/omsFulfillmentSummary.js";
+export * from "./model/omsListTotals.js";
+export * from "./model/omsReadModelRowCore.js";
+export * from "./model/fulfillmentCancellationEligibility.js";
+export * from "./oms/omsContractBase.js";
+export * from "./oms/omsContractReadAuxSchemas.js";
+export * from "./oms/omsContractReadSchemas.js";
+export * from "./oms/omsContractRequests.js";
+export * from "./oms/omsContracts.js";
+export * from "./oms/omsFulfillmentContractSchemas.js";
+export * from "./oms/omsFulfillmentDebugSchemas.js";
+export * from "./oms/omsFulfillmentHealthSchemas.js";
+export * from "./oms/omsProviderEvidenceSchemas.js";
+export * from "./oms/omsControlPlane.js";
+export * from "./oms/omsPorts.js";
+export * from "./model/omsReadModelProjections.js";
+export * from "./model/omsCurrency.js";
+import { COMMERCE_CONTRACT_VERSION as contractVersion } from "../pricing/contracts/index.js";
+export const COMMERCE_CONTRACT_VERSION = contractVersion;
+export * from "./model/customerFulfillmentRecovery.js";
+
+
+export * from "./commerceReturnsPort.js";
+export * from "./orderReviewContracts.js";
+export type * from "./orderReviewPorts.js";
+export * from "./orderFeedbackContracts.js";
+
+// Experimental browser-safe event contracts, projections and ports.
+export * from "./salesChannelEnvelope.js";
+export * from "./orderEmailEligibility.js";
+export * from "./orderEmailLines.js";
+export * from "./outboxDispatchContracts.js";
+export * from "./outboxOrderDraftEmailPorts.js";
+
+/** @consumer src/domains/commerce/checkoutCommandContracts.ts */
+export { createCheckoutCommandSchemas, CHECKOUT_COMMAND_V1, REFERENCE_CHECKOUT_V1 } from "./checkoutCommandSchemas.js";
+export type { CheckoutCommandPersistenceResult } from "./checkoutCommandSchemas.js";
+/** @consumer src/domains/commerce/paymentContinuationContracts.ts */
+export { checkoutContinuationJourneyIdSchema, CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS } from "./paymentContinuation.js";
+
+/** @consumer server/domains/commerce/checkoutOfferPolicyPort.ts */
+export { commerceOfferEvidenceSchema } from "./offerEvidenceSchemas.js";
+export type { CommerceOfferEvidence } from "./offerEvidenceSchemas.js";
+
+/** @consumer src/domains/commerce/offerAvailability.ts */
+export { DEFAULT_LOW_STOCK_THRESHOLD, deriveOfferAvailability, defaultOfferAvailability, availabilityBySku, statusForSellableNow, reasonCodeFor } from "./offerAvailability.js";
+/** @consumer src/domains/commerce/offerAvailability.ts */
+export type { DeriveOfferAvailabilityInput } from "./offerAvailability.js";

package/src/commerce/model/customerFulfillmentRecovery.ts

@@ -0,0 +1,185 @@
+import type { CustomerFulfillmentStep } from "@openlup/core/fulfillment";
+import { canonicalStatusToken,customerStepFromSignals,stepForToken } from "@openlup/core/fulfillment";
+import type { ProviderStatusEvidence,ReleasedProviderExceptionHold,ResolvedProviderExceptionRecovery,TimedFulfillmentSignal } from "../contracts/fulfillmentRecovery.js";
+export { stepForToken } from "@openlup/core/fulfillment";
+export type { CustomerFulfillmentStep } from "@openlup/core/fulfillment";
+export type { ProviderStatusEvidence,ReleasedProviderExceptionHold,ResolvedProviderExceptionRecovery,TimedFulfillmentSignal } from "../contracts/fulfillmentRecovery.js";
+
+/** Server-only shape read from a released automatic provider-exception hold. */
+
+/**
+ * Finds only database-authored, trigger-created recovery links. The returned IDs
+ * stay server-side: the browser receives the resulting Layer C step, never hold
+ * metadata or provider evidence identifiers.
+ */
+export function resolveProviderExceptionRecovery(input: {
+  automaticHoldSource?: string;
+  automaticReleaseSource?: string;
+  fulfillmentOrderId: string | null | undefined;
+  releasedHolds: ReleasedProviderExceptionHold[];
+  statusEvidence: ProviderStatusEvidence[];
+}): ResolvedProviderExceptionRecovery {
+  const clearedExceptionEvidenceIds = new Set<string>();
+  const recoveryEvidenceIds = new Set<string>();
+  const fulfillmentOrderId = text(input.fulfillmentOrderId);
+  if (!fulfillmentOrderId) return { clearedExceptionEvidenceIds, recoveryEvidenceIds };
+
+  const evidenceById = new Map(
+    input.statusEvidence
+      .map((row) => [text(row.id), row] as const)
+      .filter(([id]) => Boolean(id)),
+  );
+
+  for (const hold of input.releasedHolds) {
+    if (
+      hold.status !== "released"
+      || hold.reason !== "fulfillment_exception"
+      || hold.createdBy !== null
+      || hold.releasedBy !== null
+    ) {
+      continue;
+    }
+    const metadata = record(hold.metadata);
+    const recovery = record(metadata.autoReleaseEvidence);
+    if (
+      (!input.automaticHoldSource || metadata.source !== input.automaticHoldSource)
+      || metadata.autoReleased !== true
+      || (!input.automaticReleaseSource || metadata.autoReleaseSource !== input.automaticReleaseSource)
+      || (metadata.autoReleaseProof !== "provider_recovered" && metadata.autoReleaseProof !== "delivered")
+      || recovery.fulfillmentOrderId !== fulfillmentOrderId
+    ) {
+      continue;
+    }
+
+    const cleared = evidenceById.get(text(recovery.clearedStatusEvidenceId));
+    const recovered = evidenceById.get(text(recovery.statusEvidenceId));
+    if (!cleared || !recovered || text(cleared.fulfillmentOrderId) !== fulfillmentOrderId || text(recovered.fulfillmentOrderId) !== fulfillmentOrderId) {
+      continue;
+    }
+
+    const clearedStatus = canonicalStatusToken(cleared.providerStatus);
+    const recoveryStatus = canonicalStatusToken(recovered.localStatus);
+    if (
+      canonicalStatusToken(cleared.localStatus) !== "exception"
+      || (clearedStatus !== "suspended" && clearedStatus !== "shipping_failed")
+      || !sameInstant(recovery.clearedOccurredAt, cleared.occurredAt)
+      || !sameInstant(recovery.occurredAt, recovered.occurredAt)
+      || !isStrictlyNewer(recovered.occurredAt, cleared.occurredAt)
+      || canonicalStatusToken(text(recovery.clearedProviderStatus)) !== clearedStatus
+      || canonicalStatusToken(text(recovery.localStatus)) !== recoveryStatus
+      || !isApprovedRecovery(clearedStatus, recoveryStatus, metadata.autoReleaseProof)
+    ) {
+      continue;
+    }
+
+    const clearedId = text(cleared.id);
+    const recoveredId = text(recovered.id);
+    if (!clearedId || !recoveredId) continue;
+    clearedExceptionEvidenceIds.add(clearedId);
+    recoveryEvidenceIds.add(recoveredId);
+  }
+
+  return { clearedExceptionEvidenceIds, recoveryEvidenceIds };
+}
+
+/**
+ * The customer step for an order that is terminal BY OUR OWN DECISION
+ * (`cancelled` / `refunded`), or `null` when normal rank resolution applies.
+ *
+ * Rank alone is not enough here: `delivered` (7) outranks `cancelled` (6), so a
+ * single provider `DELIVERED` evidence row on an order we cancelled would tell
+ * the customer "delivered". Carrier evidence is a fact and stays recorded, but
+ * it cannot un-cancel our own order, so the terminal order status wins.
+ *
+ * This is a ceiling, not a new opinion: `delivered` is the ONLY step ranking
+ * above `cancelled`, and the order's own status already contributes `cancelled`
+ * to the ranked signals, so every non-delivered outcome is unchanged. The canon's
+ * ranks stay untouched — they are shared with OMS health, observability and the
+ * admin timeline, where provider-versus-local divergence must remain visible.
+ * Single owner of this rule: the customer read model and the browser fallback
+ * resolver both call it instead of each keeping a copy.
+ */
+export function customerStepForTerminalOrder(
+  orderStatus: string | null | undefined,
+): CustomerFulfillmentStep | null {
+  return stepForToken(orderStatus) === "cancelled" ? "cancelled" : null;
+}
+
+/** Resolve rank normally; only a uniquely newer canonical timed exception may cover delivered. */
+export function customerStepFromTimedSignals(
+  baseTokens: Array<string | null | undefined>,
+  evidence: TimedFulfillmentSignal[],
+  recovery?: ResolvedProviderExceptionRecovery,
+): CustomerFulfillmentStep {
+  const recovered = recovery?.clearedExceptionEvidenceIds.size;
+  const effectiveBaseTokens = recovered
+    ? baseTokens.filter((token) => stepForToken(token) !== "exception")
+    : baseTokens;
+  const effectiveEvidence = recovery
+    ? evidence.filter((signal) => !recovery.clearedExceptionEvidenceIds.has(text(signal.id)))
+    : evidence;
+  const ranked = customerStepFromSignals([...effectiveBaseTokens, ...effectiveEvidence.map((signal) => signal.token)]);
+  if (ranked !== "delivered") return ranked;
+  const timedOccurrences = effectiveEvidence
+    .map((signal) => ({ step: stepForToken(signal.token), time: validTimestamp(signal.occurredAt) }))
+    .filter((signal): signal is { step: CustomerFulfillmentStep | null; time: number } => signal.time !== null);
+  const timed = [...new Map(timedOccurrences.map((signal) => [
+    `${signal.step ?? "unknown"}:${signal.time}`,
+    signal,
+  ])).values()];
+  const latestTime = Math.max(...timed.map((signal) => signal.time));
+  const latest = timed.filter((signal) => signal.time === latestTime);
+  const deliveryTimes = timed.filter((signal) => signal.step === "delivered").map((signal) => signal.time);
+  const latestDeliveryTime = deliveryTimes.length ? Math.max(...deliveryTimes) : null;
+  return latest.length === 1 && latest[0].step === "exception"
+    && latestDeliveryTime !== null && latestTime > latestDeliveryTime ? "exception" : ranked;
+}
+
+/** Keep legacy/provider-only Provider CANCELLED evidence customer-safe. */
+export function customerSafeEvidenceToken(
+  localStatus: string | null | undefined,
+  providerStatus: string | null | undefined,
+): string | null {
+  const local = canonicalStatusToken(localStatus);
+  const provider = canonicalStatusToken(providerStatus);
+  if (provider === "cancelled" && (local === null || local === "cancelled")) return "exception";
+  return local ?? provider;
+}
+
+function validTimestamp(value: string | null | undefined): number | null {
+  if (!value || !/(?:[Zz]|[+-]\d{2}:\d{2})$/.test(value)) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function isApprovedRecovery(
+  clearedStatus: "suspended" | "shipping_failed",
+  recoveryStatus: string | null,
+  proof: unknown,
+): boolean {
+  if (proof === "delivered") return recoveryStatus === "delivered";
+  return clearedStatus === "suspended"
+    && proof === "provider_recovered"
+    && ["provider_received", "picking", "packed", "in_transit"].includes(recoveryStatus ?? "");
+}
+
+function isStrictlyNewer(candidate: string | null | undefined, previous: string | null | undefined): boolean {
+  const candidateTime = validTimestamp(candidate);
+  const previousTime = validTimestamp(previous);
+  return candidateTime !== null && previousTime !== null && candidateTime > previousTime;
+}
+
+function sameInstant(metadataValue: unknown, evidenceValue: string | null | undefined): boolean {
+  if (typeof metadataValue !== "string") return false;
+  const metadataTime = validTimestamp(metadataValue);
+  const evidenceTime = validTimestamp(evidenceValue);
+  return metadataTime !== null && evidenceTime !== null && metadataTime === evidenceTime;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}

package/src/commerce/model/fulfillmentCancellationEligibility.ts

@@ -0,0 +1,18 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+
+export function canCancelFulfillment(
+  status: OmsOrderDetail["fulfillmentStatus"],
+  providerCancellation: {
+    activeHoldCount: number;
+    orderMode: "one_time" | "subscription_cycle";
+    orderStatus: OmsOrderDetail["status"];
+    providerCancellationConfirmed: boolean;
+  },
+): boolean {
+  if (status === "created" || status === "packed" || status === "label_pending") return true;
+  return status === "exception"
+    && providerCancellation.activeHoldCount === 0
+    && providerCancellation.orderMode === "one_time"
+    && (providerCancellation.orderStatus === "paid" || providerCancellation.orderStatus === "fulfillment_pending")
+    && providerCancellation.providerCancellationConfirmed;
+}

package/src/commerce/model/omsAccountingVisibility.ts

@@ -0,0 +1,135 @@
+import type { OmsAccountingRecoveryGuidance } from "../contracts/omsTypes.js";
+import type { OmsAccountingStatus,OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type {
+OmsAccountingInvoiceRow,
+OmsAccountingOutboxRow,
+} from "./omsReadModelRows.js";
+export type { OmsAccountingRecoveryGuidance } from "../contracts/omsTypes.js";
+
+export function accountingSummary(
+  invoice: OmsAccountingInvoiceRow | null,
+  outboxRows: OmsAccountingOutboxRow[],
+  projections?: OmsReadModelProjections,
+): OmsOrderDetail["accounting"] {
+  if (!invoice) {
+    return {
+      status: "missing",
+      invoiceId: null,
+      invoiceRef: null,
+      providerKind: null,
+      providerInvoiceNumber: null,
+      fiscalStatus: null,
+      outboxStatus: null,
+      outboxAttemptCount: null,
+      outboxNextAttemptAt: null,
+      outboxLastError: null,
+      recoveryGuidance: "not_requested",
+      updatedAt: null,
+    };
+  }
+  const outbox = selectAccountingOutbox(invoice.id, outboxRows);
+  return {
+    status: outbox?.status === "failed" ? "outbox_failed" : normalizeAccountingStatus(invoice.status, projections?.additionalAccountingStatuses),
+    invoiceId: invoice.id,
+    invoiceRef: invoice.invoice_ref,
+    providerKind: invoice.provider_kind,
+    providerInvoiceNumber: invoice.provider_invoice_number,
+    fiscalStatus: invoice.fiscal_status,
+    outboxStatus: outbox?.status ?? null,
+    outboxAttemptCount: outbox?.attempt_count ?? null,
+    outboxNextAttemptAt: outbox?.next_attempt_at ?? null,
+    outboxLastError: sanitizeAccountingLastError(outbox?.last_error),
+    recoveryGuidance: accountingRecoveryGuidance(outbox?.status ?? null, invoice.status),
+    updatedAt: invoice.updated_at,
+  };
+}
+
+function selectAccountingOutbox(
+  invoiceId: string,
+  outboxRows: OmsAccountingOutboxRow[],
+): OmsAccountingOutboxRow | null {
+  return outboxRows
+    .filter((row) => row.invoice_id === invoiceId)
+    .sort(compareAccountingOutboxRows)[0] ?? null;
+}
+
+function compareAccountingOutboxRows(a: OmsAccountingOutboxRow, b: OmsAccountingOutboxRow): number {
+  const priority = outboxStatusPriority(a.status) - outboxStatusPriority(b.status);
+  if (priority !== 0) return priority;
+  const aCreatedAt = timestampOrNull(a.created_at);
+  const bCreatedAt = timestampOrNull(b.created_at);
+  if (aCreatedAt !== null && bCreatedAt !== null && aCreatedAt !== bCreatedAt) {
+    return bCreatedAt - aCreatedAt;
+  }
+  if (aCreatedAt !== null && bCreatedAt === null) return -1;
+  if (aCreatedAt === null && bCreatedAt !== null) return 1;
+  return 0;
+}
+
+function timestampOrNull(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function outboxStatusPriority(status: string): number {
+  if (status === "failed") return 0;
+  if (status === "processing") return 1;
+  if (status === "pending" || status === "queued") return 2;
+  if (status === "succeeded") return 3;
+  if (status === "cancelled") return 4;
+  return 5;
+}
+
+export function accountingRecoveryGuidance(
+  outboxStatus: string | null,
+  invoiceStatus: string | null = null,
+): OmsAccountingRecoveryGuidance {
+  if (outboxStatus === "failed") return "review_and_retry";
+  if (outboxStatus === "pending" || outboxStatus === "processing" || outboxStatus === "queued") {
+    return "wait_for_retry";
+  }
+  if (invoiceStatus === "blocked" || invoiceStatus === "rejected") return "review_and_retry";
+  if (invoiceStatus === "issued" || invoiceStatus === "accepted" || invoiceStatus === "corrected" || invoiceStatus === "voided") {
+    return "none";
+  }
+  return outboxStatus ? "none" : "not_requested";
+}
+
+export function sanitizeAccountingLastError(value: unknown) {
+  if (!isRecord(value)) return null;
+  const code =
+    readSafeText(value, "code", 80) ??
+    readSafeText(value, "errorCode", 80) ??
+    readSafeText(value, "reason", 80) ??
+    readSafeText(value, "type", 80);
+  const message =
+    readSafeText(value, "operatorMessage", 240) ??
+    readSafeText(value, "message", 240);
+  const retryable = typeof value.retryable === "boolean" ? value.retryable : null;
+  if (!code && !message && retryable === null) return null;
+  return { code, message, retryable };
+}
+
+function readSafeText(record: Record<string, unknown>, key: string, maxLength: number): string | null {
+  const value = record[key];
+  if (typeof value !== "string") return null;
+  const normalized = redactSensitiveText(value.trim().replace(/\s+/g, " "));
+  return normalized ? normalized.slice(0, maxLength) : null;
+}
+
+function redactSensitiveText(value: string): string {
+  return value
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted-email]")
+    .replace(/\b(?:bearer|token|secret|api[_-]?key|authorization)\s*[:=]?\s+[A-Za-z0-9._~+/=-]{8,}/gi, "[redacted-secret]");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeAccountingStatus(status: string, additional: readonly string[] = []): OmsAccountingStatus {
+  const valid: OmsAccountingStatus[] = ["draft", "issue_requested", "blocked", "issued", "accepted", "rejected", "correction_requested", "corrected", "voided"];
+  return [...valid, ...additional].includes(status as OmsAccountingStatus) ? (status as OmsAccountingStatus) : "missing";
+}

package/src/commerce/model/omsBillingInvoiceBuyer.ts

@@ -0,0 +1,20 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+
+export function enrichBillingWithInvoiceBuyer(
+  billing: OmsOrderDetail["billingAddress"],
+  orderMetadata: Record<string, unknown> | null,
+): OmsOrderDetail["billingAddress"] {
+  if (!billing) return billing;
+  const snapshot =
+    orderMetadata && typeof orderMetadata === "object"
+      ? (orderMetadata as { invoiceBuyerSnapshot?: unknown }).invoiceBuyerSnapshot
+      : null;
+  if (!snapshot || typeof snapshot !== "object") return billing;
+  const buyer = snapshot as { companyName?: unknown; taxId?: unknown };
+  const companyName =
+    billing.companyName ?? (typeof buyer.companyName === "string" && buyer.companyName.trim() ? buyer.companyName : null);
+  const taxId =
+    billing.taxId ?? (typeof buyer.taxId === "string" && buyer.taxId.trim() ? buyer.taxId : null);
+  if (companyName === billing.companyName && taxId === billing.taxId) return billing;
+  return { ...billing, companyName, taxId };
+}

package/src/commerce/model/omsCurrency.ts

@@ -0,0 +1,8 @@
+import type { OmsCurrencyPolicy } from "../contracts/omsTypes.js";
+export type { OmsCurrencyPolicy } from "../contracts/omsTypes.js";
+/** Settlement policy is supplied by the host; the neutral default checks format only. */
+
+export const neutralOmsCurrencyPolicy: OmsCurrencyPolicy = {
+  defaultCurrency: "XXX",
+  accepts: currency => /^[A-Z]{3}$/.test(currency),
+};

package/src/commerce/model/omsFulfillmentDebug.ts

@@ -0,0 +1,157 @@
+import type { OmsFulfillmentProviderStockCurrentRow,OmsInboundProviderEventRow } from "../contracts/omsTypes.js";
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import {
+parseTimestampOrZero,
+type OmsProviderAttemptRow,
+type OmsProviderDispatchRefRow,
+type OmsProviderStatusEvidenceRow,
+} from "./omsFulfillmentSummary.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsCommunicationDeliveryRow,OmsInventoryReservationRow } from "./omsReadModelRows.js";
+export type { OmsFulfillmentProviderStockCurrentRow,OmsInboundProviderEventRow } from "../contracts/omsTypes.js";
+
+type Debug = OmsOrderDetail["fulfillmentDebug"];
+type Step = Debug["steps"][number];
+
+export function buildOmsFulfillmentDebug(input: {
+  projections?: OmsReadModelProjections;
+  paymentStatus: OmsOrderDetail["paymentStatus"];
+  inventory: OmsOrderDetail["inventory"];
+  fulfillment: OmsOrderDetail["fulfillment"];
+  reservations: OmsInventoryReservationRow[];
+  communicationDeliveries: OmsCommunicationDeliveryRow[];
+  providerAttempts: OmsProviderAttemptRow[];
+  providerDispatchRefs: OmsProviderDispatchRefRow[];
+  providerStatusEvidence: OmsProviderStatusEvidenceRow[];
+  inboundProviderEvents: OmsInboundProviderEventRow[];
+  providerStockCurrent?: OmsFulfillmentProviderStockCurrentRow[];
+}): Debug {
+  const latestDispatch = newest(input.providerDispatchRefs, (row) => row.updated_at ?? row.created_at);
+  const latestAttempt = newest(input.providerAttempts, (row) => row.created_at);
+  const latestProvider = newest(input.providerStatusEvidence, (row) => row.occurred_at ?? row.created_at);
+  const latestInbound = newest(input.inboundProviderEvents, (row) => row.processed_at ?? row.created_at);
+  const dispatchedMail = latestMail(input.communicationDeliveries, "commerce-shipment-dispatched");
+  const providerProblem = latestInbound?.processing_status === "ignored" || latestInbound?.processing_status === "failed" ||
+    Boolean(latestDispatch?.error) || Boolean(latestAttempt?.error) || ["failed", "error"].includes(latestAttempt?.status ?? "");
+  const shippedWithoutTracking = Boolean(latestProvider && ["shipped", "delivered"].includes(latestProvider.provider_status ?? "")) &&
+    input.fulfillment.trackingReferences.length === 0;
+  const latestProviderStock = newest(input.providerStockCurrent ?? [], (row) => row.last_synced_at);
+  const providerStockStale = latestProviderStock ? Date.parse(latestProviderStock.stale_after) <= Date.now() : false;
+
+  const steps: Step[] = [
+    step("payment", input.paymentStatus === "succeeded" ? "ok" : "blocked", "Payment", input.paymentStatus),
+    step("stock", ["reserved", "consumed"].includes(input.inventory.status) ? "ok" : "missing", "Stock", input.inventory.status, {
+      details: input.reservations.map((row) => `${row.status}:${row.quantity}`),
+      evidenceAt: input.inventory.expiresAt,
+    }),
+    step(
+      "provider_stock",
+      providerStockStatus(Boolean(input.projections?.usesExternalStock?.(input.fulfillment.providerKind)), latestProviderStock, providerStockStale),
+      "Provider stock",
+      latestProviderStock ? `${latestProviderStock.provider_kind}:${latestProviderStock.sku}` : null,
+      {
+        details: latestProviderStock
+          ? [
+              `forSale ${latestProviderStock.provider_for_sale_quantity}`,
+              `total ${latestProviderStock.provider_total_quantity}`,
+              `authority ${input.projections?.usesExternalStock?.(input.fulfillment.providerKind) ? "external_stock_master" : "local_atp"}`,
+            ]
+          : [],
+        evidenceAt: latestProviderStock?.last_synced_at ?? null,
+      },
+    ),
+    step("fulfillment", input.fulfillment.fulfillmentOrderId ? "ok" : "missing", "Fulfillment order", input.fulfillment.status),
+    step("dispatch", latestDispatch ? statusFromDispatch(latestDispatch) : "pending", input.projections?.dispatchStepLabel ?? "Provider dispatch", latestDispatch?.status ?? null, {
+      details: compact([latestDispatch?.provider_order_id ? `providerOrderId ${latestDispatch.provider_order_id}` : null, latestAttempt?.status ? `attempt ${latestAttempt.status}` : null]),
+      evidenceAt: latestDispatch?.updated_at ?? latestDispatch?.created_at ?? null,
+    }),
+    step("provider", providerProblem ? "warning" : latestProvider ? "ok" : "pending", "Provider evidence", latestProvider?.provider_status ?? latestInbound?.processing_status ?? null, {
+      details: compact([latestProvider?.provider_sub_status, latestInbound?.event_type, latestAttempt?.status ? `attempt ${latestAttempt.status}` : null, errorSummary(latestInbound?.error), errorSummary(latestAttempt?.error)]),
+      evidenceAt: latestProvider?.occurred_at ?? latestProvider?.created_at ?? latestInbound?.created_at ?? null,
+    }),
+    step("tracking", shippedWithoutTracking ? "missing" : input.fulfillment.trackingReferences.length > 0 ? "ok" : "pending", "Tracking refs", input.fulfillment.providerTrackingId, {
+      details: input.fulfillment.trackingReferences.map((ref) => compact([ref.trackingNumber, ref.carrierKind, ref.service]).join(" / ")),
+      evidenceAt: input.fulfillment.trackingReferences[0]?.updatedAt ?? null,
+    }),
+    step("communication", mailStatus(dispatchedMail), "Customer e-mail", dispatchedMail?.status ?? null, {
+      details: dispatchedMail ? compact([dispatchedMail.template_slug, dispatchedMail.last_error_code]) : [],
+      evidenceAt: dispatchedMail?.updated_at ?? dispatchedMail?.created_at ?? null,
+    }),
+  ];
+  const nextAction = chooseNextAction({ input, latestDispatch, providerProblem, shippedWithoutTracking });
+  const blockers = steps.filter((entry) => entry.status === "blocked" || entry.status === "missing" || entry.status === "warning").map((entry) => entry.label);
+  return {
+    summary: input.projections?.debugSummary?.(nextAction) ?? summaryFor(nextAction),
+    severity: blockers.length ? "action_required" : steps.some((entry) => entry.status === "pending") ? "watch" : "ok",
+    nextAction,
+    blockers,
+    steps,
+  };
+}
+
+function chooseNextAction(input: {
+  input: Parameters<typeof buildOmsFulfillmentDebug>[0];
+  latestDispatch: OmsProviderDispatchRefRow | null;
+  providerProblem: boolean;
+  shippedWithoutTracking: boolean;
+}): Debug["nextAction"] {
+  if (input.input.paymentStatus !== "succeeded") return "review_payment";
+  if (!["reserved", "consumed"].includes(input.input.inventory.status)) return "review_stock";
+  const latestProviderStock = newest(input.input.providerStockCurrent ?? [], (row) => row.last_synced_at);
+  if (input.input.projections?.usesExternalStock?.(input.input.fulfillment.providerKind) && !latestProviderStock) return "review_stock";
+  if (latestProviderStock && Date.parse(latestProviderStock.stale_after) <= Date.now()) return "review_stock";
+  if (!input.input.fulfillment.fulfillmentOrderId) return "create_fulfillment";
+  if (input.providerProblem) return "review_provider";
+  if (!input.latestDispatch && input.input.projections?.usesExternalStock?.(input.input.fulfillment.providerKind)) return "retry_dispatch";
+  if (input.shippedWithoutTracking) return "reconcile";
+  return "wait";
+}
+
+function providerStockStatus(
+  usesExternalStock: boolean,
+  stock: OmsFulfillmentProviderStockCurrentRow | null,
+  stale: boolean,
+): Step["status"] {
+  if (!usesExternalStock) return "ok";
+  if (!stock) return "missing";
+  return stale ? "warning" : "ok";
+}
+
+function step(key: Step["key"], status: Step["status"], label: string, value: string | null | undefined, extra: Partial<Step> = {}): Step {
+  return { key, status, label, value: value ?? null, evidenceAt: extra.evidenceAt ?? null, details: extra.details ?? [] };
+}
+
+function statusFromDispatch(row: OmsProviderDispatchRefRow): Step["status"] {
+  if (row.error || row.status === "failed") return "warning";
+  return row.status ? "ok" : "pending";
+}
+
+function mailStatus(row: OmsCommunicationDeliveryRow | null): Step["status"] {
+  if (!row) return "pending";
+  if (["bounced", "complained", "missed", "blocked", "delivery_delayed"].includes(row.status)) return "warning";
+  if (["sent", "delivered"].includes(row.status)) return "ok";
+  return "pending";
+}
+
+function latestMail(rows: OmsCommunicationDeliveryRow[], slug: string): OmsCommunicationDeliveryRow | null {
+  return newest(rows.filter((row) => row.template_slug === slug || row.purpose === "shipment_dispatched"), (row) => row.updated_at ?? row.created_at);
+}
+
+function newest<T>(rows: T[], time: (row: T) => string | null | undefined): T | null {
+  return [...rows].sort((a, b) => parseTimestampOrZero(time(b)) - parseTimestampOrZero(time(a)))[0] ?? null;
+}
+
+function summaryFor(action: Debug["nextAction"]): string {
+  return { wait: "Monitor the next event.", create_fulfillment: "Create a fulfillment order.", retry_dispatch: "Review or retry provider dispatch.", reconcile: "Reconcile tracking and status.", review_payment: "Review payment first.", review_stock: "Review stock reservations first.", review_provider: "Review provider evidence.", contact_support: "Contact technical support." }[action];
+}
+
+function errorSummary(value: unknown): string | null {
+  if (!value) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "object" && "reason" in value && typeof value.reason === "string") return value.reason;
+  return "error_present";
+}
+
+function compact(values: Array<string | null | undefined>): string[] {
+  return values.filter((value): value is string => Boolean(value && value.trim()));
+}