@openlup/platform 0.26.0 → 0.27.0

package/dist/commerce/model/omsFulfillmentDebug.js

@@ -0,0 +1,122 @@
+import { parseTimestampOrZero, } from "./omsFulfillmentSummary.js";
+export function buildOmsFulfillmentDebug(input) {
+    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("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) {
+    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, stock, stale) {
+    if (!usesExternalStock)
+        return "ok";
+    if (!stock)
+        return "missing";
+    return stale ? "warning" : "ok";
+}
+function step(key, status, label, value, extra = {}) {
+    return { key, status, label, value: value ?? null, evidenceAt: extra.evidenceAt ?? null, details: extra.details ?? [] };
+}
+function statusFromDispatch(row) {
+    if (row.error || row.status === "failed")
+        return "warning";
+    return row.status ? "ok" : "pending";
+}
+function mailStatus(row) {
+    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, slug) {
+    return newest(rows.filter((row) => row.template_slug === slug || row.purpose === "shipment_dispatched"), (row) => row.updated_at ?? row.created_at);
+}
+function newest(rows, time) {
+    return [...rows].sort((a, b) => parseTimestampOrZero(time(b)) - parseTimestampOrZero(time(a)))[0] ?? null;
+}
+function summaryFor(action) {
+    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) {
+    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) {
+    return values.filter((value) => Boolean(value && value.trim()));
+}

package/dist/commerce/model/omsFulfillmentSummary.d.ts

@@ -0,0 +1,16 @@
+import type { OmsFulfillmentOperationRow, OmsFulfillmentOrderRow, OmsProviderAttemptRow, OmsProviderDispatchRefRow, OmsProviderStatusEvidenceRow, OmsReleasedProviderExceptionHoldRow, OmsShipmentExternalRefRow } from "../contracts/omsTypes.js";
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import { type CustomerFulfillmentStep } from "./customerFulfillmentRecovery.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+export type { OmsFulfillmentOperationRow, OmsFulfillmentOrderRow, OmsProviderAttemptRow, OmsProviderDispatchRefRow, OmsProviderStatusEvidenceRow, OmsReleasedProviderExceptionHoldRow, OmsShipmentExternalRefRow } from "../contracts/omsTypes.js";
+export declare function buildOmsFulfillmentSummary(input: {
+    projections?: OmsReadModelProjections;
+    fulfillmentOrders: OmsFulfillmentOrderRow[];
+    fulfillmentOperations: OmsFulfillmentOperationRow[];
+    shipmentExternalRefs: OmsShipmentExternalRefRow[];
+    providerAttempts?: OmsProviderAttemptRow[];
+    providerDispatchRefs?: OmsProviderDispatchRefRow[];
+    providerStatusEvidence?: OmsProviderStatusEvidenceRow[];
+}): OmsOrderDetail["fulfillment"];
+export declare function deriveOmsCustomerFulfillmentStep(orderStatus: string | null | undefined, fulfillment: OmsOrderDetail["fulfillment"], deliveredAt?: string | null, releasedProviderExceptionHolds?: OmsReleasedProviderExceptionHoldRow[], providerStatusEvidence?: OmsProviderStatusEvidenceRow[], activeHoldCount?: number, projections?: OmsReadModelProjections): CustomerFulfillmentStep;
+export declare function parseTimestampOrZero(value: string | null | undefined): number;

package/dist/commerce/model/omsFulfillmentSummary.js

@@ -0,0 +1,189 @@
+import { rowsForParcel } from "@openlup/core/fulfillment";
+import { customerSafeEvidenceToken, customerStepFromTimedSignals, resolveProviderExceptionRecovery, stepForToken } from "./customerFulfillmentRecovery.js";
+export function buildOmsFulfillmentSummary(input) {
+    const fulfillmentOrder = input.fulfillmentOrders[0] ?? null;
+    if (!fulfillmentOrder) {
+        return {
+            fulfillmentOrderId: null,
+            status: null,
+            providerKind: null,
+            latestOperationType: null,
+            latestOperationAt: null,
+            providerTrackingId: null,
+            trackingUrl: null,
+            carrierKind: null,
+            service: null,
+            trackingReferences: [],
+            trackingTimeline: [],
+            providerEvidence: [],
+        };
+    }
+    // Every other companion below is already narrowed to this parcel by `fulfillment_order_id`;
+    // tracking references only joined them once the column existed. An unattributed row still
+    // answers for any parcel, so a one-parcel order reads exactly as it did before.
+    const parcelRefs = rowsForParcel(input.shipmentExternalRefs, fulfillmentOrder.id);
+    const trackingReferences = parcelRefs
+        .filter((row) => row.active !== false)
+        .filter((row) => Boolean(row.provider_tracking_id))
+        .map((row) => ({
+        providerKind: row.provider_kind ?? "unknown",
+        trackingNumber: row.provider_tracking_id,
+        trackingUrl: row.tracking_url ?? null,
+        carrierKind: row.carrier_kind ?? row.provider_kind ?? null,
+        service: row.service ?? null,
+        updatedAt: row.updated_at ?? row.created_at ?? null,
+    }))
+        .sort((a, b) => parseTimestampOrZero(b.updatedAt) - parseTimestampOrZero(a.updatedAt));
+    const fulfillmentTimeline = input.fulfillmentOperations
+        .filter((operation) => operation.fulfillment_order_id === fulfillmentOrder.id)
+        .map((operation) => ({
+        eventType: operation.operation_type,
+        label: labelForOperation(operation.operation_type, input.projections),
+        occurredAt: operation.occurred_at,
+        source: "fulfillment",
+    }));
+    const providerStatusTimeline = (input.providerStatusEvidence ?? [])
+        .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+        .map((row) => {
+        const eventType = row.customer_status ?? row.local_status ?? row.provider_status ?? "provider_status";
+        return {
+            eventType,
+            label: labelForOperation(eventType, input.projections),
+            occurredAt: row.occurred_at ?? null,
+            source: sourceForEvidenceKind(row.evidence_kind),
+        };
+    });
+    const dispatchTimeline = (input.providerDispatchRefs ?? [])
+        .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+        .map((row) => ({
+        eventType: `dispatch_${row.status ?? "recorded"}`,
+        label: input.projections?.dispatchLabel?.(row.status) ?? "Provider dispatch recorded",
+        occurredAt: row.updated_at ?? row.created_at ?? null,
+        source: "dispatch",
+    }));
+    const trackingTimeline = [...fulfillmentTimeline, ...providerStatusTimeline, ...dispatchTimeline]
+        .sort((a, b) => parseTimestampOrZero(b.occurredAt) - parseTimestampOrZero(a.occurredAt))
+        .slice(0, 12);
+    const providerEvidence = [
+        ...(input.providerDispatchRefs ?? [])
+            .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+            .map((row) => ({
+            evidenceType: "dispatch_ref",
+            status: row.status ?? null,
+            providerStatus: null,
+            providerOrderId: row.provider_order_id ?? null,
+            evidenceKind: row.dispatch_mode ?? null,
+            occurredAt: row.created_at ?? null,
+            updatedAt: row.updated_at ?? row.created_at ?? null,
+            summary: row.error ? "dispatch_error_present" : null,
+        })),
+        ...(input.providerAttempts ?? [])
+            .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+            .map((row) => ({
+            evidenceType: "provider_attempt",
+            status: row.status ?? null,
+            providerStatus: row.provider_kind ?? null,
+            providerOrderId: null,
+            evidenceKind: "provider_attempt",
+            occurredAt: row.created_at ?? null,
+            updatedAt: row.created_at ?? null,
+            summary: row.error ? "provider_attempt_error_present" : null,
+        })),
+        ...(input.providerStatusEvidence ?? [])
+            .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+            .map((row) => ({
+            evidenceType: "status_evidence",
+            status: row.local_status ?? null,
+            providerStatus: row.provider_status ?? null,
+            providerOrderId: null,
+            evidenceKind: row.evidence_kind ?? null,
+            occurredAt: row.occurred_at ?? null,
+            updatedAt: row.created_at ?? null,
+            summary: row.provider_sub_status ?? null,
+        })),
+    ].sort((a, b) => parseTimestampOrZero(b.updatedAt ?? b.occurredAt) - parseTimestampOrZero(a.updatedAt ?? a.occurredAt));
+    const latestOperation = input.fulfillmentOperations
+        .find((operation) => operation.fulfillment_order_id === fulfillmentOrder.id) ?? null;
+    const tracking = parcelRefs.find((ref) => ref.order_id === fulfillmentOrder.order_id && ref.active) ?? null;
+    return {
+        fulfillmentOrderId: fulfillmentOrder.id,
+        status: fulfillmentOrder.status,
+        providerKind: trackingReferences[0]?.providerKind ?? fulfillmentOrder.provider_kind ?? null,
+        latestOperationType: latestOperation?.operation_type ?? null,
+        latestOperationAt: latestOperation?.occurred_at ?? null,
+        providerTrackingId: trackingReferences[0]?.trackingNumber ?? tracking?.provider_tracking_id ?? null,
+        trackingUrl: trackingReferences[0]?.trackingUrl ?? null,
+        carrierKind: trackingReferences[0]?.carrierKind ?? null,
+        service: trackingReferences[0]?.service ?? null,
+        trackingReferences,
+        trackingTimeline,
+        providerEvidence,
+    };
+}
+export function deriveOmsCustomerFulfillmentStep(orderStatus, fulfillment, deliveredAt, releasedProviderExceptionHolds = [], providerStatusEvidence = [], activeHoldCount = 0, projections) {
+    if (activeHoldCount > 0)
+        return "exception";
+    const recovery = resolveProviderExceptionRecovery({
+        automaticHoldSource: projections?.automaticExceptionHoldSource,
+        automaticReleaseSource: projections?.automaticExceptionReleaseSource,
+        fulfillmentOrderId: fulfillment.fulfillmentOrderId,
+        releasedHolds: releasedProviderExceptionHolds.map(toReleasedProviderExceptionHold),
+        statusEvidence: providerStatusEvidence.map((row) => ({
+            id: row.id,
+            fulfillmentOrderId: row.fulfillment_order_id,
+            providerStatus: row.provider_status,
+            localStatus: row.local_status,
+            occurredAt: row.occurred_at,
+            token: customerSafeEvidenceToken(row.local_status, row.provider_status),
+        })),
+    });
+    return customerStepFromTimedSignals([orderStatus, fulfillment.status], [
+        ...(deliveredAt ? [{ token: "delivered", occurredAt: deliveredAt }] : []),
+        ...providerStatusEvidence
+            .filter((row) => row.fulfillment_order_id === fulfillment.fulfillmentOrderId)
+            .map((row) => ({
+            id: row.id,
+            token: customerSafeEvidenceToken(row.local_status, row.provider_status),
+            occurredAt: row.occurred_at,
+        })),
+        ...fulfillment.trackingTimeline
+            .filter((event) => event.source === "fulfillment")
+            .map((event) => ({
+            token: event.eventType,
+            occurredAt: event.occurredAt,
+        })),
+    ], recovery);
+}
+function toReleasedProviderExceptionHold(row) {
+    return {
+        orderId: row.order_id,
+        status: row.status ?? null,
+        reason: row.reason ?? null,
+        createdBy: row.created_by ?? null,
+        releasedBy: row.released_by ?? null,
+        metadata: row.metadata,
+    };
+}
+/** Resolve the same canonical step as the customer timeline, without choosing
+ * a locale. Hosts supply presentation through the existing projection; the
+ * neutral default is the step key, with the generic fallback for unknown tokens.
+ * This is not another status-to-label table. */
+function labelForOperation(operationType, projections) {
+    const step = stepForToken(operationType);
+    return projections?.timelineLabel?.(step) ?? step ?? "Delivery status updated";
+}
+function sourceForEvidenceKind(kind) {
+    if (kind === "webhook")
+        return "webhook";
+    if (kind === "reconciliation")
+        return "reconciliation";
+    return "provider";
+}
+// Shared with the two sibling read-model modules that sorted the same evidence
+// rows through a byte-identical private copy of this function. Not merged with
+// omsAccountingVisibility's `timestampOrNull`: that one answers null for a
+// missing instant so the outbox comparator can rank "unknown" apart from the
+// epoch, which this zero-defaulting sort must not do.
+export function parseTimestampOrZero(value) {
+    return value ? Date.parse(value) || 0 : 0;
+}

package/dist/commerce/model/omsListTotals.d.ts

@@ -0,0 +1,13 @@
+import type { AdminCommerceOrdersListResponse } from "../oms/omsContracts.js";
+import { type OmsCurrencyPolicy } from "./omsCurrency.js";
+/**
+ * A paid set that spans more than one currency has no single GMV and no single
+ * average order value. Adding the minor units across currencies produces a
+ * figure that is money in none of them, and labelling it with one of the codes
+ * makes it look actionable. The operator gets a named refusal instead.
+ */
+export declare class CommerceOmsMixedCurrencyTotalsError extends Error {
+    readonly currencies: readonly string[];
+    constructor(currencies: readonly string[]);
+}
+export declare function summarizeOmsListTotals(orders: AdminCommerceOrdersListResponse["orders"], policy?: OmsCurrencyPolicy): AdminCommerceOrdersListResponse["summaryTotals"];

package/dist/commerce/model/omsListTotals.js

@@ -0,0 +1,32 @@
+import { neutralOmsCurrencyPolicy } from "./omsCurrency.js";
+/**
+ * A paid set that spans more than one currency has no single GMV and no single
+ * average order value. Adding the minor units across currencies produces a
+ * figure that is money in none of them, and labelling it with one of the codes
+ * makes it look actionable. The operator gets a named refusal instead.
+ */
+export class CommerceOmsMixedCurrencyTotalsError extends Error {
+    currencies;
+    constructor(currencies) {
+        super("commerce_oms_summary_mixed_currency");
+        this.name = "CommerceOmsMixedCurrencyTotalsError";
+        this.currencies = currencies;
+    }
+}
+export function summarizeOmsListTotals(orders, policy = neutralOmsCurrencyPolicy) {
+    const paidOrders = orders.filter((order) => order.paymentStatus === "succeeded");
+    const currencies = [...new Set(paidOrders.map((order) => order.total.currency))].sort();
+    if (currencies.length > 1)
+        throw new CommerceOmsMixedCurrencyTotalsError(currencies);
+    const amountMinor = paidOrders.reduce((sum, order) => sum + order.total.amountMinor, 0);
+    const orderCount = paidOrders.length;
+    // No paid order means no order named a currency, so the platform default is
+    // the only honest label for a zero total - and it is read from one module.
+    const currency = currencies[0] ?? policy.defaultCurrency;
+    return {
+        gmv: { amountMinor, currency },
+        aov: { amountMinor: orderCount > 0 ? Math.round(amountMinor / orderCount) : 0, currency },
+        orderCount,
+        paidSubscriptionCycleCount: paidOrders.filter((order) => order.mode === "subscription_cycle").length,
+    };
+}

package/dist/commerce/model/omsOperationalLadder.d.ts

@@ -0,0 +1,51 @@
+import type { OmsOperationalLadderInput, OmsOperationalRung } from "../contracts/omsTypes.js";
+import type { AdminOmsAttentionReason, AdminOmsNextAction } from "../oms/omsContracts.js";
+export type { OmsOperationalLadderInput, OmsOperationalRung } from "../contracts/omsTypes.js";
+/**
+ * The operator attention/next-action ladder, declared once.
+ *
+ * The same ladder is implemented a second time in SQL, inside the live queue
+ * RPC `public.commerce_oms_admin_list_queue`
+ * (the live queue migration `20260903190000_oms_queue_hides_withdrawn_checkout_rows`,
+ * the `operational` CTE and the `attention_priority_desc` rank arm). Both run on
+ * the same admin request: SQL decides which orders are selected, what the
+ * summary counters say and in what order the rows arrive; this module labels the
+ * rows that come back. Nothing in the type system makes them agree.
+ *
+ * So the agreement is written down instead: every rung carries the live SQL
+ * CASE-arm condition it mirrors, verbatim modulo whitespace, and
+ * `omsOperationalLadder.test.ts` parses those arms out of the migration and
+ * compares them rung for rung, in order. Editing one side without the other
+ * turns that test red, which is the only thing standing between the two
+ * implementations and a silent divergence.
+ *
+ * ⛔ Changing a rung here is a behaviour change to the OMS queue. It must be
+ * made on both sides in the same change, or not at all.
+ */
+/** The facts the ladder reads. Flat on purpose: it is the join between the row
+ * shapes this codebase carries and the columns the SQL `operational` CTE has. */
+export declare const OMS_OPERATIONAL_LADDER: readonly OmsOperationalRung[];
+/** The `ELSE` of both SQL CASE expressions, and the fall-through of the loop. */
+export declare const OMS_OPERATIONAL_LADDER_FALLBACK: {
+    readonly attentionReason: AdminOmsAttentionReason;
+    readonly nextAction: AdminOmsNextAction;
+};
+/**
+ * The `attention_priority_desc` sort ranks, in SQL arm order. Lower sorts first.
+ *
+ * Nothing in TypeScript consumes this today - the queue arrives pre-sorted from
+ * SQL, and the fixture bundle does not offer that sort. It is declared here
+ * because the ranking is part of the same ladder: an attention reason added
+ * above without a rank silently sorts to the bottom of the operator's queue.
+ * The parity test binds it to the live migration arm for arm.
+ */
+export declare const OMS_ATTENTION_PRIORITY_LADDER: readonly {
+    readonly attentionReason: AdminOmsAttentionReason;
+    readonly rank: number;
+}[];
+export declare const OMS_ATTENTION_PRIORITY_FALLBACK_RANK = 99;
+/** Walks the ladder once and returns the first rung that matches. */
+export declare function resolveOmsOperationalState(input: OmsOperationalLadderInput): {
+    attentionReason: AdminOmsAttentionReason;
+    nextAction: AdminOmsNextAction;
+};

package/dist/commerce/model/omsOperationalLadder.js

@@ -0,0 +1,158 @@
+/**
+ * The operator attention/next-action ladder, declared once.
+ *
+ * The same ladder is implemented a second time in SQL, inside the live queue
+ * RPC `public.commerce_oms_admin_list_queue`
+ * (the live queue migration `20260903190000_oms_queue_hides_withdrawn_checkout_rows`,
+ * the `operational` CTE and the `attention_priority_desc` rank arm). Both run on
+ * the same admin request: SQL decides which orders are selected, what the
+ * summary counters say and in what order the rows arrive; this module labels the
+ * rows that come back. Nothing in the type system makes them agree.
+ *
+ * So the agreement is written down instead: every rung carries the live SQL
+ * CASE-arm condition it mirrors, verbatim modulo whitespace, and
+ * `omsOperationalLadder.test.ts` parses those arms out of the migration and
+ * compares them rung for rung, in order. Editing one side without the other
+ * turns that test red, which is the only thing standing between the two
+ * implementations and a silent divergence.
+ *
+ * ⛔ Changing a rung here is a behaviour change to the OMS queue. It must be
+ * made on both sides in the same change, or not at all.
+ */
+/** The facts the ladder reads. Flat on purpose: it is the join between the row
+ * shapes this codebase carries and the columns the SQL `operational` CTE has. */
+export const OMS_OPERATIONAL_LADDER = [
+    {
+        id: "terminal_order",
+        sqlPredicate: "order_status IN ('refunded', 'cancelled')",
+        attentionReason: "none",
+        nextAction: "none",
+        // A refunded/cancelled order is done, even though its payment_status is no
+        // longer 'succeeded'. Without this rung the payment rung below would flag
+        // every refunded order as needing payment review.
+        matches: (input) => input.orderStatus === "refunded" || input.orderStatus === "cancelled",
+    },
+    {
+        id: "active_hold",
+        sqlPredicate: "active_hold_count > 0",
+        attentionReason: "active_hold",
+        nextAction: "release_hold",
+        matches: (input) => input.activeHoldCount > 0,
+    },
+    {
+        id: "payment_not_succeeded",
+        sqlPredicate: "payment_status <> 'succeeded'",
+        attentionReason: "payment_required",
+        nextAction: "review_payment",
+        matches: (input) => input.paymentStatus !== "succeeded",
+    },
+    {
+        id: "missing_shipping_address",
+        sqlPredicate: "EXISTS ( SELECT 1 FROM base_orders orders WHERE orders.id = derived.id AND orders.shipping_address_id IS NULL )",
+        attentionReason: "missing_shipping_address",
+        nextAction: "review_address",
+        matches: (input) => !input.hasShippingAddress,
+    },
+    {
+        id: "inventory_not_held",
+        sqlPredicate: "inventory_status NOT IN ('reserved', 'consumed')",
+        attentionReason: "inventory_missing",
+        nextAction: "review_inventory",
+        matches: (input) => input.inventoryStatus !== "reserved" && input.inventoryStatus !== "consumed",
+    },
+    {
+        id: "fulfillment_absent_and_blocked",
+        sqlPredicate: "fulfillment_status IS NULL AND fulfillment_allowed = false",
+        attentionReason: "fulfillment_blocked",
+        nextAction: "review_fulfillment",
+        matches: (input) => !input.fulfillmentStatus && !input.fulfillmentAllowed,
+    },
+    {
+        id: "fulfillment_absent",
+        sqlPredicate: "fulfillment_status IS NULL",
+        attentionReason: "fulfillment_pending",
+        nextAction: "create_fulfillment",
+        matches: (input) => !input.fulfillmentStatus,
+    },
+    {
+        id: "fulfillment_before_label",
+        sqlPredicate: "fulfillment_status IN ('created', 'packed', 'label_pending')",
+        attentionReason: "fulfillment_pending",
+        nextAction: "record_label",
+        matches: (input) => input.fulfillmentStatus === "created" ||
+            input.fulfillmentStatus === "packed" ||
+            input.fulfillmentStatus === "label_pending",
+    },
+    {
+        id: "fulfillment_label_created",
+        sqlPredicate: "fulfillment_status = 'label_created'",
+        attentionReason: "fulfillment_pending",
+        nextAction: "hand_off",
+        matches: (input) => input.fulfillmentStatus === "label_created",
+    },
+    {
+        id: "fulfillment_exception",
+        sqlPredicate: "fulfillment_status = 'exception'",
+        attentionReason: "fulfillment_exception",
+        nextAction: "review_tracking",
+        matches: (input) => input.fulfillmentStatus === "exception",
+    },
+    // The three accounting rungs carry three distinct attention reasons but one
+    // shared next action. The SQL next-action ladder therefore collapses them into
+    // a single arm over the union of their literals; the parity test asserts that
+    // collapse explicitly rather than letting the arm counts differ unremarked.
+    {
+        id: "accounting_missing",
+        sqlPredicate: "accounting_status = 'missing'",
+        attentionReason: "invoice_missing",
+        nextAction: "review_invoice",
+        matches: (input) => input.accountingStatus === "missing",
+    },
+    {
+        id: "accounting_blocked",
+        sqlPredicate: "accounting_status = 'blocked'",
+        attentionReason: "invoice_buyer_data_invalid",
+        nextAction: "review_invoice",
+        matches: (input) => input.accountingStatus === "blocked",
+    },
+    {
+        id: "accounting_issue_failed",
+        sqlPredicate: "accounting_status IN ('rejected', 'outbox_failed')",
+        attentionReason: "invoice_issue_failed",
+        nextAction: "review_invoice",
+        matches: (input) => input.accountingStatus === "rejected" || input.accountingStatus === "outbox_failed",
+    },
+];
+/** The `ELSE` of both SQL CASE expressions, and the fall-through of the loop. */
+export const OMS_OPERATIONAL_LADDER_FALLBACK = { attentionReason: "none", nextAction: "none" };
+/**
+ * The `attention_priority_desc` sort ranks, in SQL arm order. Lower sorts first.
+ *
+ * Nothing in TypeScript consumes this today - the queue arrives pre-sorted from
+ * SQL, and the fixture bundle does not offer that sort. It is declared here
+ * because the ranking is part of the same ladder: an attention reason added
+ * above without a rank silently sorts to the bottom of the operator's queue.
+ * The parity test binds it to the live migration arm for arm.
+ */
+export const OMS_ATTENTION_PRIORITY_LADDER = [
+    { attentionReason: "active_hold", rank: 1 },
+    { attentionReason: "payment_required", rank: 2 },
+    { attentionReason: "missing_shipping_address", rank: 3 },
+    { attentionReason: "inventory_missing", rank: 4 },
+    { attentionReason: "fulfillment_blocked", rank: 5 },
+    { attentionReason: "fulfillment_exception", rank: 6 },
+    { attentionReason: "invoice_issue_failed", rank: 7 },
+    { attentionReason: "invoice_buyer_data_invalid", rank: 8 },
+    { attentionReason: "invoice_missing", rank: 9 },
+    // Deliberately the same rank as invoice_missing in the live body.
+    { attentionReason: "fulfillment_pending", rank: 9 },
+];
+export const OMS_ATTENTION_PRIORITY_FALLBACK_RANK = 99;
+/** Walks the ladder once and returns the first rung that matches. */
+export function resolveOmsOperationalState(input) {
+    for (const rung of OMS_OPERATIONAL_LADDER) {
+        if (rung.matches(input))
+            return { attentionReason: rung.attentionReason, nextAction: rung.nextAction };
+    }
+    return { ...OMS_OPERATIONAL_LADDER_FALLBACK };
+}

package/dist/commerce/model/omsOrderLineMoney.d.ts

@@ -0,0 +1,4 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsOrderItemRow } from "./omsReadModelRows.js";
+import type { CanonicalOrderMoneyLine } from "../orderMoney.js";
+export declare function mapOmsOrderLine(item: OmsOrderItemRow, currency: OmsOrderDetail["total"]["currency"], moneyLine: CanonicalOrderMoneyLine): OmsOrderDetail["lines"][number];

package/dist/commerce/model/omsOrderLineMoney.js

@@ -0,0 +1,25 @@
+export function mapOmsOrderLine(item, currency, moneyLine) {
+    const productSnapshot = item.product_snapshot ?? {};
+    const variantSnapshot = item.variant_snapshot ?? null;
+    return {
+        id: item.id,
+        skuId: item.sku_id ?? null,
+        sku: item.sku ?? readSnapshotText(productSnapshot, "sku"),
+        title: item.title
+            ?? readSnapshotText(productSnapshot, "title")
+            ?? readSnapshotText(productSnapshot, "name"),
+        quantity: item.quantity,
+        unitPrice: { amountMinor: moneyLine.catalogUnit, currency },
+        total: { amountMinor: moneyLine.catalogTotal, currency },
+        discountAllocated: { amountMinor: moneyLine.discountAllocated, currency },
+        effectiveTotal: { amountMinor: moneyLine.effectiveGross, currency },
+        effectiveNet: { amountMinor: moneyLine.effectiveNet, currency },
+        vatRateBps: moneyLine.vatRateBps,
+        productSnapshot,
+        variantSnapshot,
+    };
+}
+function readSnapshotText(snapshot, key) {
+    const value = snapshot[key];
+    return typeof value === "string" && value.trim() ? value : null;
+}

package/dist/commerce/model/omsPaymentMethodSummary.d.ts

@@ -0,0 +1,5 @@
+import type { OmsPaymentMethodSummary } from "../contracts/omsTypes.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsPaymentAttemptRow, OmsPaymentIntentRow } from "./omsReadModelRows.js";
+export type { OmsPaymentMethodSummary } from "../contracts/omsTypes.js";
+export declare function paymentMethodForOrder(orderId: string, paymentIntents: OmsPaymentIntentRow[], paymentAttempts: OmsPaymentAttemptRow[], projections?: OmsReadModelProjections): OmsPaymentMethodSummary;

package/dist/commerce/model/omsPaymentMethodSummary.js

@@ -0,0 +1,11 @@
+export function paymentMethodForOrder(orderId, paymentIntents, paymentAttempts, projections) {
+    const intent = paymentIntents.find((candidate) => candidate.id && candidate.order_id === orderId) ?? null;
+    if (!intent)
+        return { provider: null, label: null };
+    const attempt = paymentAttempts.find((candidate) => candidate.id === intent.active_attempt_id)
+        ?? paymentAttempts.find((candidate) => candidate.payment_intent_id === intent.id)
+        ?? null;
+    if (!attempt)
+        return { provider: null, label: null };
+    return { provider: attempt.provider, label: projections?.paymentMethodLabel?.(attempt) ?? attempt.provider };
+}