@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/model/omsReadModel.ts

@@ -0,0 +1,302 @@
+import { parcelSequenceNo } from "@openlup/core/fulfillment";
+import type { SubscriptionCycleStatus } from "@openlup/core/subscription";
+import {
+resolveDeliverySelectionEvidence,
+summarizeDeliverySelection,
+} from "../../shipping/index.js";
+import {
+adminCommerceOrderDetailResponseSchema,
+type AdminCommerceOrderDetailResponse,
+type OmsDeliveryContactResolution,
+type OmsOrderDetail,
+} from "../oms/omsContracts.js";
+import { enrichBillingWithInvoiceBuyer } from "./omsBillingInvoiceBuyer.js";
+import {
+buildOmsFulfillmentDebug,
+type OmsFulfillmentProviderStockCurrentRow,
+type OmsInboundProviderEventRow,
+} from "./omsFulfillmentDebug.js";
+import {
+type OmsFulfillmentOperationRow,
+type OmsFulfillmentOrderRow,
+type OmsProviderAttemptRow,
+type OmsProviderDispatchRefRow,
+type OmsProviderStatusEvidenceRow,
+type OmsReleasedProviderExceptionHoldRow,
+type OmsShipmentExternalRefRow,
+} from "./omsFulfillmentSummary.js";
+import { mapOmsOrderLine } from "./omsOrderLineMoney.js";
+import { mapCommunicationDelivery } from "./omsReadModelCommunication.js";
+import {
+actionEligibility,
+mapAddress,
+mapCustomer,
+type OmsActionAvailabilityFlags,
+} from "./omsReadModelHelpers.js";
+import { deriveOmsOrderMoney } from "./omsReadModelPricing.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import { buildCurrentDeliveryContact,buildOmsOrderRowCore } from "./omsReadModelRowCore.js";
+import type { OmsAccountingInvoiceRow,OmsAccountingOutboxRow,OmsAddressRow,OmsCommunicationDeliveryRow,OmsCustomerRow,OmsHoldRow,OmsInventoryReservationRow,OmsOperationRow,OmsOrderItemRow,OmsOrderRow,OmsPaymentAttemptRow,OmsPaymentIntentRow,OmsPaymentTransitionRow } from "./omsReadModelRows.js";
+import { COMMERCE_CONTRACT_VERSION } from "../../pricing/contracts/index.js";
+
+export { buildOmsOrderListResponse } from "./omsReadModelList.js";
+export type { OmsAccountingInvoiceRow,OmsAccountingOutboxRow,OmsAddressRow,OmsCommunicationDeliveryRow,OmsCustomerRow,OmsHoldRow,OmsInventoryReservationRow,OmsOperationRow,OmsOrderItemRow,OmsOrderRow,OmsPaymentAttemptRow,OmsPaymentIntentRow,OmsPaymentTransitionRow } from "./omsReadModelRows.js";
+
+export function buildOmsOrderDetailResponse(input: {
+  order: OmsOrderRow;
+  identityExtras?: Record<string, unknown>;
+  projections?: OmsReadModelProjections;
+  paymentIntent: OmsPaymentIntentRow | null;
+  paymentAttempts: OmsPaymentAttemptRow[];
+  paymentTransitions: OmsPaymentTransitionRow[];
+  holds: OmsHoldRow[];
+  operations: OmsOperationRow[];
+  customer?: OmsCustomerRow | null;
+  shippingAddress?: OmsAddressRow | null;
+  billingAddress?: OmsAddressRow | null;
+  accountingInvoice?: OmsAccountingInvoiceRow | null;
+  accountingOutbox?: OmsAccountingOutboxRow[];
+  communicationDeliveries?: OmsCommunicationDeliveryRow[];
+  orderItems?: OmsOrderItemRow[];
+  inventoryReservations?: OmsInventoryReservationRow[];
+  fulfillmentOrders?: OmsFulfillmentOrderRow[]; fulfillmentOperations?: OmsFulfillmentOperationRow[];
+  supersededFulfillmentOrders?: OmsFulfillmentOrderRow[];
+  shipmentExternalRefs?: OmsShipmentExternalRefRow[]; providerAttempts?: OmsProviderAttemptRow[];
+  providerDispatchRefs?: OmsProviderDispatchRefRow[]; providerStatusEvidence?: OmsProviderStatusEvidenceRow[];
+  releasedProviderExceptionHolds?: OmsReleasedProviderExceptionHoldRow[];
+  fulfillmentHealth?: OmsOrderDetail["fulfillmentHealth"];
+  inboundProviderEvents?: OmsInboundProviderEventRow[];
+  providerStockCurrent?: OmsFulfillmentProviderStockCurrentRow[];
+  subscriptionCycleStatus: SubscriptionCycleStatus | null;
+  subscriptionCyclePaidAt?: string | null;
+  subscriptionNextCycleAt?: string | null;
+  actionFlags?: OmsActionAvailabilityFlags;
+  deliveryContactResolution?: OmsDeliveryContactResolution;
+}): AdminCommerceOrderDetailResponse {
+  const activeHoldCount = input.holds.filter((hold) => hold.status === "active").length;
+  const orderItems = input.orderItems;
+  const orderMoney = deriveOmsOrderMoney(input.order, orderItems);
+  const {
+    row: order,
+    paymentStatus,
+    inventory,
+    fulfillment,
+    accounting,
+    fulfillmentEligibility,
+  } = buildOmsOrderRowCore({
+    projections: input.projections,
+    order: input.order,
+    activeHoldCount,
+    paymentIntents: input.paymentIntent ? [input.paymentIntent] : [],
+    paymentAttempts: input.paymentAttempts,
+    identity: { customer: mapCustomer(input.customer ?? null), ...input.identityExtras },
+    orderItems,
+    inventoryReservations: input.inventoryReservations ?? [],
+    fulfillmentOrders: input.fulfillmentOrders ?? [],
+    fulfillmentOperations: input.fulfillmentOperations ?? [],
+    shipmentExternalRefs: input.shipmentExternalRefs ?? [],
+    providerAttempts: input.providerAttempts ?? [],
+    dispatchRefs: input.providerDispatchRefs ?? [],
+    statusEvidence: input.providerStatusEvidence ?? [],
+    releasedProviderExceptionHolds: input.releasedProviderExceptionHolds,
+    accountingInvoice: input.accountingInvoice ?? null,
+    accountingOutbox: input.accountingOutbox ?? [],
+    subscriptionCycleStatus: input.subscriptionCycleStatus,
+    orderMoney,
+  });
+  const fulfillmentHealth = buildOmsFulfillmentHealth({ orderId: input.order.id, fulfillmentHealth: input.fulfillmentHealth });
+  const { deliveryContact, effectiveShippingAddress } = buildCurrentDeliveryContact({
+    resolution: input.deliveryContactResolution ?? { resolutionVersion: 1, scope: "missing", baseline: null, contact: null, contactDigest: null },
+    shippingAddressId: input.order.shipping_address_id,
+    fulfillmentOrders: input.fulfillmentOrders ?? [],
+    dispatchRefs: input.providerDispatchRefs ?? [],
+  });
+  const detail: OmsOrderDetail = {
+    ...order,
+    ...input.projections?.detailFields?.({ order: input.order, orderItems, orderMoney }),
+    activeHoldReasons: [...new Set(input.holds.filter((hold) => hold.status === "active").map((hold) => hold.reason))],
+    fulfillmentHealthDigest: { healthStatus: fulfillmentHealth.healthStatus, attentionReasons: fulfillmentHealth.attentionReasons },
+    shippingAddress: deliveryContact.scope === "missing"
+      ? mapAddress(input.shippingAddress ?? null)
+      : effectiveShippingAddress,
+    deliveryContact,
+    billingAddress: enrichBillingWithInvoiceBuyer(
+      mapAddress(input.billingAddress ?? input.shippingAddress ?? null),
+      input.order.metadata,
+    ),
+    deliverySelection: (() => {
+      const evidence = resolveDeliverySelectionEvidence({ orderMetadata: input.order.metadata });
+      const summary = summarizeDeliverySelection(evidence.selection, evidence.source);
+      return summary ? { ...summary, source: summary.source ?? null } : null;
+    })(),
+    lines: (orderItems ?? []).map((item, index) =>
+      mapOmsOrderLine(item, input.order.currency, orderMoney.lines[index]!),
+    ),
+    subscription: {
+      subscriptionId: input.order.subscription_id,
+      subscriptionCycleId: input.order.subscription_cycle_id,
+      subscriptionCycleStatus: input.subscriptionCycleStatus,
+      nextCycleAt: input.subscriptionNextCycleAt ?? null,
+      cyclePaidAt: input.subscriptionCyclePaidAt ?? null,
+    },
+    fulfillmentEligibility,
+    inventory,
+    fulfillment,
+    replacementChain: buildOmsReplacementChain({
+      currentParcel: (input.fulfillmentOrders ?? [])[0] ?? null,
+      supersededParcels: input.supersededFulfillmentOrders ?? [],
+      shipmentExternalRefs: input.shipmentExternalRefs ?? [],
+    }),
+    fulfillmentHealth,
+    fulfillmentDebug: buildOmsFulfillmentDebug({
+      projections: input.projections,
+      paymentStatus,
+      inventory,
+      fulfillment,
+      reservations: input.inventoryReservations ?? [],
+      communicationDeliveries: input.communicationDeliveries ?? [],
+      providerAttempts: input.providerAttempts ?? [],
+      providerDispatchRefs: input.providerDispatchRefs ?? [],
+      providerStatusEvidence: input.providerStatusEvidence ?? [],
+      inboundProviderEvents: input.inboundProviderEvents ?? [],
+      providerStockCurrent: input.providerStockCurrent ?? [],
+    }),
+    accounting,
+    actionEligibility: actionEligibility({
+      fulfillmentEligibility,
+      activeHoldCount,
+      fulfillmentStatus: fulfillment.status,
+      hasFulfillmentOrder: Boolean(fulfillment.fulfillmentOrderId),
+      hasShippingAddress: Boolean(input.order.shipping_address_id),
+      deliveryContact,
+      orderStatus: input.order.status,
+      orderMode: input.order.mode,
+      providerCancellationConfirmed: hasLatestProviderCancellation(
+        input.providerStatusEvidence ?? [],
+        fulfillment.fulfillmentOrderId,
+      ),
+      flags: input.actionFlags,
+    }),
+    holds: input.holds.map((hold) => ({
+      id: hold.id,
+      orderId: hold.order_id,
+      status: hold.status,
+      reason: hold.reason,
+      note: hold.note,
+      createdAt: hold.created_at,
+      releasedAt: hold.released_at,
+    })),
+    operations: input.operations.map((operation) => ({
+      id: operation.id,
+      orderId: operation.order_id,
+      type: operation.operation_type,
+      holdId: operation.hold_id,
+      actorUserId: operation.actor_user_id,
+      occurredAt: operation.occurred_at,
+      payload: operation.payload,
+    })),
+    payment: {
+      intentId: input.paymentIntent?.id ?? null,
+      paymentId: input.paymentIntent?.payment_id ?? null,
+      status: paymentStatus,
+      activeAttemptId: input.paymentIntent?.active_attempt_id ?? null,
+      providerPaymentId: input.paymentIntent?.provider_payment_id ?? null,
+      updatedAt: input.paymentIntent?.updated_at ?? null,
+    },
+    paymentAttempts: input.paymentAttempts.map((attempt) => ({
+      id: attempt.id,
+      status: attempt.status,
+      provider: attempt.provider,
+      providerAttemptId: attempt.provider_attempt_id,
+      nextActionKind: attempt.next_action_kind,
+      updatedAt: attempt.updated_at,
+    })),
+    paymentTransitions: input.paymentTransitions.map((transition) => ({
+      id: transition.id,
+      transitionKind: transition.transition_kind,
+      fromStatus: transition.from_status,
+      toStatus: transition.to_status,
+      reason: transition.reason,
+      occurredAt: transition.occurred_at,
+    })),
+    communicationDeliveries: (input.communicationDeliveries ?? []).map(mapCommunicationDelivery),
+  };
+
+  return (input.projections?.parseDetail ?? (value => adminCommerceOrderDetailResponseSchema.parse(value)))({
+    contractVersion: COMMERCE_CONTRACT_VERSION,
+    order: detail,
+  });
+}
+
+function hasLatestProviderCancellation(
+  evidence: OmsProviderStatusEvidenceRow[],
+  fulfillmentOrderId: string | null,
+): boolean {
+  if (!fulfillmentOrderId) return false;
+  const latest = evidence
+    .filter((row) => row.fulfillment_order_id === fulfillmentOrderId)
+    .sort((left, right) => evidenceTimestamp(right) - evidenceTimestamp(left))[0];
+  return latest?.provider_status?.trim().toUpperCase() === "CANCELLED";
+}
+
+function evidenceTimestamp(row: OmsProviderStatusEvidenceRow): number {
+  const raw = row.occurred_at ?? row.created_at;
+  const parsed = raw ? Date.parse(raw) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * The order's replacement chain, from rows the detail read already holds.
+ *
+ * ⛔ Attribution here is STRICT, unlike `rowsForParcel`: a tracking reference that names no
+ * parcel belongs to whichever parcel is asking, which is right for the current parcel and
+ * wrong here - it would print one legacy reference under every superseded parcel as if the
+ * carrier had issued it several times. A superseded parcel shows only references that name it.
+ */
+function buildOmsReplacementChain(input: {
+  currentParcel: OmsFulfillmentOrderRow | null;
+  supersededParcels: OmsFulfillmentOrderRow[];
+  shipmentExternalRefs: OmsShipmentExternalRefRow[];
+}): OmsOrderDetail["replacementChain"] {
+  return {
+    sequenceNo: input.currentParcel ? parcelSequenceNo(input.currentParcel) : 0,
+    replacesFulfillmentOrderId: input.currentParcel?.replaces_fulfillment_order_id ?? null,
+    replacementReason: input.currentParcel?.replacement_reason ?? null,
+    supersededParcels: input.supersededParcels.map((parcel) => ({
+      fulfillmentOrderId: parcel.id,
+      sequenceNo: parcelSequenceNo(parcel),
+      status: parcel.status ?? null,
+      replacementReason: parcel.replacement_reason ?? null,
+      handedOverAt: parcel.handed_over_at ?? null,
+      deliveredAt: parcel.delivered_at ?? null,
+      trackingReferences: input.shipmentExternalRefs
+        .filter((ref) => ref.fulfillment_order_id === parcel.id && ref.active !== false && Boolean(ref.provider_tracking_id))
+        .map((ref) => ({
+          providerKind: ref.provider_kind ?? "unknown",
+          trackingNumber: ref.provider_tracking_id,
+          trackingUrl: ref.tracking_url ?? null,
+          carrierKind: ref.carrier_kind ?? ref.provider_kind ?? null,
+          service: ref.service ?? null,
+          updatedAt: ref.updated_at ?? ref.created_at ?? null,
+        })),
+    })),
+  };
+}
+
+function buildOmsFulfillmentHealth(input: {
+  orderId: string;
+  fulfillmentHealth?: OmsOrderDetail["fulfillmentHealth"];
+}): OmsOrderDetail["fulfillmentHealth"] {
+  return input.fulfillmentHealth ?? {
+    healthStatus: "ok",
+    attentionReasons: [],
+    oldestAgeSeconds: null,
+    opaqueIds: {
+      orderId: input.orderId,
+      fulfillmentOrderId: null,
+      outboxEventId: null,
+      dispatchRefFulfillmentOrderId: null,
+      latestEvidenceFulfillmentOrderId: null,
+    },
+  };
+}

package/src/commerce/model/omsReadModelCommunication.ts

@@ -0,0 +1,32 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsCommunicationDeliveryRow } from "./omsReadModelRows.js";
+
+export function mapCommunicationDelivery(row: OmsCommunicationDeliveryRow): OmsOrderDetail["communicationDeliveries"][number] {
+  return {
+    id: row.id,
+    purpose: row.purpose,
+    templateSlug: row.template_slug,
+    triggerSource: row.trigger_source,
+    triggerEvent: row.trigger_event,
+    aggregateType: row.aggregate_type,
+    aggregateId: row.aggregate_id,
+    dedupeKey: row.dedupe_key,
+    status: row.status,
+    providerKind: row.provider_kind,
+    providerMessageId: row.provider_message_id,
+    scheduledDueAt: row.scheduled_due_at,
+    expectedSendAt: row.expected_send_at,
+    queuedAt: row.queued_at,
+    firstAttemptAt: row.first_attempt_at,
+    sentAt: row.sent_at,
+    deliveredAt: row.delivered_at,
+    terminalAt: row.terminal_at,
+    lastErrorCode: row.last_error_code,
+    outboxEventId: row.outbox_event_id,
+    platformJobRunId: row.platform_job_run_id,
+    emailSendId: row.email_send_id,
+    metadata: row.metadata ?? {},
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}

package/src/commerce/model/omsReadModelHelpers.ts

@@ -0,0 +1,279 @@
+import type { OmsActionAvailabilityFlags,OmsOrderIdentity } from "../contracts/omsTypes.js";
+import type {
+OmsAccountingStatus,
+OmsInventoryStatus,
+OmsOrderDetail,
+OmsOrderPaymentStatus,
+} from "../oms/omsContracts.js";
+import { canCancelFulfillment } from "./fulfillmentCancellationEligibility.js";
+import { resolveOmsOperationalState } from "./omsOperationalLadder.js";
+import type { OmsPaymentMethodSummary } from "./omsPaymentMethodSummary.js";
+import { pricingSummaryForOrder } from "./omsReadModelPricing.js";
+import type {
+OmsAddressRow,
+OmsCustomerRow,
+OmsInventoryReservationRow,
+OmsOrderItemRow,
+OmsOrderRow,
+OmsPaymentIntentRow,
+} from "./omsReadModelRows.js";
+import type { CanonicalOrderMoney } from "../orderMoney.js";
+import { mapOmsPaymentStatus } from "../fulfillmentEligibility.js";
+export type { OmsActionAvailabilityFlags,OmsOrderIdentity } from "../contracts/omsTypes.js";
+export { buildOmsDeliveryContactProjection,deliveryContactAddress } from "./omsReadModelRowCore.js";
+// Who the row is about. One pair rather than two loose fields, so the row core
+// forwards it untouched and neither builder can supply half of it.
+
+export function findCustomer(order: OmsOrderRow, customers: OmsCustomerRow[]): OmsOrderDetail["customer"] {
+  return mapCustomer(customers.find((customer) => customer.id === order.client_id) ?? null);
+}
+export function mapCustomer(row: OmsCustomerRow | null): OmsOrderDetail["customer"] {
+  if (!row) return null;
+  return {
+    id: row.id,
+    email: row.email,
+    firstName: row.first_name,
+    lastName: row.last_name,
+    phone: row.phone,
+    lifecycleStage: row.lifecycle_stage,
+  };
+}
+export function mapAddress(row: OmsAddressRow | null): OmsOrderDetail["shippingAddress"] {
+  if (!row) return null;
+  return {
+    id: row.id,
+    label: row.label ?? null,
+    line1: row.line1 ?? null,
+    line2: row.line2 ?? null,
+    city: row.city ?? null,
+    postalCode: row.postal_code ?? null,
+    country: row.country ?? null,
+    recipientName: row.recipient_name ?? null,
+    contactPhone: row.contact_phone ?? null,
+    companyName: row.company_name ?? null,
+    taxId: row.tax_id ?? null,
+    deliveryNotes: row.delivery_notes ?? null,
+    courierInstructions: row.courier_instructions ?? null,
+  };
+}
+export function evaluateOperationalState(input: {
+  order: OmsOrderRow;
+  paymentStatus: OmsOrderPaymentStatus;
+  activeHoldCount: number;
+  inventoryStatus: OmsInventoryStatus;
+  fulfillmentStatus: OmsOrderDetail["fulfillmentStatus"];
+  fulfillmentEligibility?: { allowed: boolean; reason: string | null };
+  accountingStatus: OmsAccountingStatus;
+}): Pick<OmsOrderDetail, "attentionReason" | "nextAction"> {
+  // The rungs themselves live in omsOperationalLadder.ts, next to the live SQL
+  // arms they mirror, so the parity test can compare the two ladders directly.
+  // This function only adapts the row shapes onto the ladder's flat input.
+  return resolveOmsOperationalState({
+    orderStatus: input.order.status,
+    activeHoldCount: input.activeHoldCount,
+    paymentStatus: input.paymentStatus,
+    hasShippingAddress: Boolean(input.order.shipping_address_id),
+    inventoryStatus: input.inventoryStatus,
+    fulfillmentStatus: input.fulfillmentStatus,
+    // An absent eligibility evaluation never blocked: the old cascade consulted
+    // it only when it was supplied. `true` reproduces that exactly.
+    fulfillmentAllowed: input.fulfillmentEligibility ? input.fulfillmentEligibility.allowed : true,
+    accountingStatus: input.accountingStatus,
+  });
+}
+export function actionEligibility(input: {
+  fulfillmentEligibility: { allowed: boolean; reason: string | null };
+  activeHoldCount: number;
+  fulfillmentStatus: OmsOrderDetail["fulfillmentStatus"];
+  hasFulfillmentOrder: boolean;
+  hasShippingAddress: boolean;
+  deliveryContact?: NonNullable<OmsOrderDetail["deliveryContact"]>;
+  orderStatus: OmsOrderDetail["status"];
+  orderMode: "one_time" | "subscription_cycle";
+  providerCancellationConfirmed?: boolean;
+  flags?: OmsActionAvailabilityFlags;
+}): OmsOrderDetail["actionEligibility"] {
+  const flags = {
+    holdMutationsEnabled: true,
+    supportMutationsEnabled: true,
+    fulfillmentMutationsEnabled: true,
+    refundMutationsEnabled: true,
+    orderCancellationEnabled: true,
+    ...input.flags,
+  };
+  const canCreateFulfillment = input.fulfillmentEligibility.allowed && !input.hasFulfillmentOrder;
+  const canRecordLabel = input.fulfillmentStatus === "created" || input.fulfillmentStatus === "packed" || input.fulfillmentStatus === "label_pending";
+  const base: OmsOrderDetail["actionEligibility"] = {
+    addNote: { allowed: true, reason: null },
+    createHold: input.activeHoldCount > 0 ? { allowed: false, reason: "order_already_on_hold" } : { allowed: true, reason: null },
+    releaseHold: input.activeHoldCount > 0 ? { allowed: true, reason: null } : { allowed: false, reason: "no_active_hold" },
+    createFulfillment: canCreateFulfillment ? { allowed: true, reason: null } : { allowed: false, reason: input.fulfillmentEligibility.reason ?? "fulfillment_order_exists" },
+    updateShippingAddress: input.deliveryContact
+      ? !input.deliveryContact.effective
+        ? { allowed: false, reason: "missing_shipping_address" }
+        : input.deliveryContact.correctionAllowed
+          ? { allowed: true, reason: null }
+          : { allowed: false, reason: deliveryContactRefusalReason(input.deliveryContact) }
+      : !input.hasShippingAddress
+        ? { allowed: false, reason: "missing_shipping_address" }
+        : canUpdateShippingAddress(input.fulfillmentStatus)
+          ? { allowed: true, reason: null }
+          : { allowed: false, reason: "address_locked_after_label" },
+    recordLabel: canRecordLabel ? { allowed: true, reason: null } : { allowed: false, reason: "fulfillment_not_ready_for_label" },
+    handOff: input.fulfillmentStatus === "label_created" ? { allowed: true, reason: null } : { allowed: false, reason: "label_required_before_handoff" },
+    recordTrackingEvent: canRecordTrackingEvent(input.fulfillmentStatus) ? { allowed: true, reason: null } : { allowed: false, reason: "tracking_not_ready" },
+    cancelFulfillment: input.fulfillmentStatus
+      ? canCancelFulfillment(input.fulfillmentStatus, {
+          activeHoldCount: input.activeHoldCount,
+          orderMode: input.orderMode,
+          orderStatus: input.orderStatus,
+          providerCancellationConfirmed: input.providerCancellationConfirmed ?? false,
+        })
+        ? { allowed: true, reason: null }
+        : { allowed: false, reason: "fulfillment_not_cancellable" }
+      : { allowed: false, reason: "no_fulfillment_order" },
+    cancelOrder: input.orderStatus === "pending_payment"
+      ? { allowed: true, reason: null }
+      : { allowed: false, reason: "order_not_pending_payment" },
+    markRefunded: input.orderStatus === "paid"
+      ? { allowed: true, reason: null }
+      : input.orderStatus === "refunded"
+        ? { allowed: false, reason: "already_refunded" }
+        : { allowed: false, reason: "order_not_paid" },
+  };
+  return {
+    addNote: flagGate(base.addNote, flags.supportMutationsEnabled, "oms_support_mutations_disabled"),
+    createHold: flagGate(base.createHold, flags.holdMutationsEnabled, "oms_hold_mutations_disabled"),
+    releaseHold: flagGate(base.releaseHold, flags.holdMutationsEnabled, "oms_hold_mutations_disabled"),
+    createFulfillment: flagGate(base.createFulfillment, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+    updateShippingAddress: flagGate(base.updateShippingAddress, flags.supportMutationsEnabled, "oms_support_mutations_disabled"),
+    recordLabel: flagGate(base.recordLabel, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+    handOff: flagGate(base.handOff, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+    recordTrackingEvent: flagGate(base.recordTrackingEvent, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+    cancelFulfillment: flagGate(base.cancelFulfillment, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+    cancelOrder: flagGate(base.cancelOrder, flags.orderCancellationEnabled, "oms_order_cancellation_disabled"),
+    markRefunded: flagGate(base.markRefunded, flags.refundMutationsEnabled, "oms_refund_mutations_disabled"),
+  };
+}
+function deliveryContactRefusalReason(
+  projection: NonNullable<OmsOrderDetail["deliveryContact"]>,
+): string {
+  return ["submitting", "created", "uncertain", "failed", "cancel_requested", "cancelled", "unknown"]
+    .includes(projection.providerSubmissionState)
+    ? "delivery_contact_submission_started"
+    : "address_locked_after_label";
+}
+export function inventorySummary(
+  reservations: OmsInventoryReservationRow[],
+  orderItems: OmsOrderItemRow[],
+): OmsOrderDetail["inventory"] {
+  const reservation = reservations[0] ?? null;
+  if (!reservation) return emptyInventory();
+  const base = {
+    reservationId: reservation.id,
+    reservationStatus: reservation.status,
+    expiresAt: reservation.expires_at,
+    locationId: reservation.location_id,
+    locationCode: reservation.inventory_locations?.code ?? null,
+  };
+  if (orderItems.length > 0 && !hasCoverageReservation(reservations) && reservation.status !== "consumed") {
+    return { status: reservation.status === "reserved" ? "reserved" : reservation.status, ...base };
+  }
+  if (orderItems.length > 0 && !allOrderItemsCovered(orderItems, reservations)) return { status: "missing", ...base };
+  return { status: reservation.status === "reserved" ? "reserved" : reservation.status, ...base };
+}
+export function baseOrder(input: {
+  order: OmsOrderRow;
+  paymentStatus: OmsOrderPaymentStatus;
+  paymentMethod: OmsPaymentMethodSummary;
+  activeHoldCount: number;
+  identity: OmsOrderIdentity;
+  inventoryStatus: OmsInventoryStatus;
+  fulfillmentStatus: OmsOrderDetail["fulfillmentStatus"];
+  customerFulfillmentStep: OmsOrderDetail["customerFulfillmentStep"];
+  accountingStatus: OmsAccountingStatus;
+  providerOpsStatus: OmsOrderDetail["providerOpsStatus"];
+  providerOpsSla: OmsOrderDetail["providerOpsSla"];
+  providerOrderId: OmsOrderDetail["providerOrderId"];
+  attentionReason: OmsOrderDetail["attentionReason"];
+  nextAction: OmsOrderDetail["nextAction"];
+  orderItems?: OmsOrderItemRow[];
+  orderMoney?: CanonicalOrderMoney;
+}) {
+  const pricingSummary = pricingSummaryForOrder(
+    input.order,
+    input.orderItems,
+    input.orderMoney,
+  );
+  return {
+    orderId: input.order.id,
+    orderNumber: input.order.order_number,
+    clientId: input.order.client_id,
+    ...input.identity,
+    status: input.order.status,
+    mode: input.order.mode,
+    // undefined, not null: "no source axis read" is not "storefront order".
+    sourceKind: input.order.source_kind ?? undefined,
+    sourceChannelSlug: input.order.sales_channels?.slug ?? undefined,
+    sourceOrderRef: input.order.source_order_ref ?? undefined,
+    paymentMethodLabel: input.paymentMethod.label,
+    paymentProvider: input.paymentMethod.provider,
+    paymentStatus: input.paymentStatus,
+    fulfillmentStatus: input.fulfillmentStatus,
+    customerFulfillmentStep: input.customerFulfillmentStep,
+    inventoryStatus: input.inventoryStatus,
+    accountingStatus: input.accountingStatus,
+    providerOpsStatus: input.providerOpsStatus,
+    providerOpsSla: input.providerOpsSla,
+    providerOrderId: input.providerOrderId,
+    attentionReason: input.attentionReason,
+    nextAction: input.nextAction,
+    activeHoldCount: input.activeHoldCount,
+    total: pricingSummary.finalTotal,
+    pricingSummary,
+    createdAt: input.order.created_at,
+    updatedAt: input.order.updated_at,
+  };
+}
+export function paymentStatusForOrder(orderId: string, paymentIntents: OmsPaymentIntentRow[]) {
+  const intent = paymentIntents.find((candidate) => candidate.id && candidate.order_id === orderId);
+  return mapOmsPaymentStatus(intent?.status ?? null) as OmsOrderPaymentStatus;
+}
+function canUpdateShippingAddress(status: OmsOrderDetail["fulfillmentStatus"]): boolean {
+  return !status || status === "created" || status === "packed" || status === "label_pending";
+}
+function canRecordTrackingEvent(status: OmsOrderDetail["fulfillmentStatus"]): boolean {
+  return status === "handed_over" || status === "in_transit";
+}
+
+function flagGate(
+  eligibility: OmsOrderDetail["actionEligibility"]["addNote"],
+  enabled: boolean | undefined,
+  reason: string,
+): OmsOrderDetail["actionEligibility"]["addNote"] {
+  return enabled ? eligibility : { allowed: false, reason };
+}
+
+function allOrderItemsCovered(orderItems: OmsOrderItemRow[], reservations: OmsInventoryReservationRow[]): boolean {
+  const reservedQtyByItem = new Map<string, number>();
+  for (const reservation of reservations) {
+    if ((reservation.status !== "reserved" && reservation.status !== "consumed") || !reservation.order_item_id) continue;
+    reservedQtyByItem.set(reservation.order_item_id, (reservedQtyByItem.get(reservation.order_item_id) ?? 0) + reservation.quantity);
+  }
+  return orderItems.every((item) => (reservedQtyByItem.get(item.id) ?? 0) >= item.quantity);
+}
+
+function hasCoverageReservation(reservations: OmsInventoryReservationRow[]): boolean {
+  return reservations.some((reservation) => reservation.status === "reserved" || reservation.status === "consumed");
+}
+
+function emptyInventory(): OmsOrderDetail["inventory"] {
+  return {
+    status: "missing",
+    reservationId: null,
+    reservationStatus: null,
+    expiresAt: null,
+    locationId: null,
+    locationCode: null,
+  };
+}