@openlup/platform 0.25.0 → 0.27.0

package/src/commerce/adapters/managed/commerceOmsPort.ts

@@ -0,0 +1,158 @@
+import type { OmsActionAvailabilityFlags } from "../../model/omsReadModelHelpers.js";
+import type {
+AdminCommerceOrderCancelRequest,
+AdminCommerceOrderDetailRequest,
+AdminCommerceOrderDetailResponse,
+AdminCommerceOrderHoldRequest,
+AdminCommerceOrderHoldResponse,
+AdminCommerceOrderMarkRefundedRequest,
+AdminCommerceOrderMarkRefundedResponse,
+AdminCommerceOrderNoteRequest,
+AdminCommerceOrderNoteResponse,
+AdminCommerceOrderReleaseHoldRequest,
+AdminCommerceOrderRequestReplacementShipmentRequest,
+AdminCommerceOrderRequestReplacementShipmentResponse,
+AdminCommerceOrderUpdateShippingAddressRequest,
+AdminCommerceOrderUpdateShippingAddressResponse,
+AdminCommerceOrdersListRequest,
+AdminCommerceOrdersListResponse,
+} from "../../oms/omsContracts.js";
+import {
+CommerceOmsConflictError,
+CommerceOmsPersistenceError,
+readOmsReplacementRefusal,
+type CommerceOmsHoldPort,
+type CommerceOmsReadPort,
+} from "../../oms/omsPorts.js";
+import {
+addCommerceOmsNote,
+callOmsRpc,
+updateCommerceOmsShippingAddress,
+} from "./commerceOmsMutations.js";
+import type { OmsManagedReadProjections } from "./oms/readProjections.js";
+import {
+getCommerceOmsOrderDetail,
+listCommerceOmsOrders,
+} from "./oms/readQueries.js";
+import type { CommerceOmsRpcClient,CommerceOmsStore,RpcError } from "./oms/types.js";
+
+export type { CommerceOmsRpcClient } from "./oms/types.js";
+
+export function createManagedCommerceOmsPort(
+  client: CommerceOmsRpcClient,
+  options: { actionFlags?: OmsActionAvailabilityFlags; queries?: Pick<CommerceOmsStore, "query">; projections?: OmsManagedReadProjections } = {},
+): CommerceOmsReadPort & CommerceOmsHoldPort {
+  function readStore(): CommerceOmsStore {
+    if (!options.queries) throw new CommerceOmsPersistenceError("Commerce OMS query capability is required");
+    return { rpc: client.rpc.bind(client), query: options.queries.query.bind(options.queries) };
+  }
+  return {
+    listOrders(request: AdminCommerceOrdersListRequest): Promise<AdminCommerceOrdersListResponse> {
+      return listCommerceOmsOrders(readStore(), request, options);
+    },
+
+    getOrderDetail(request: AdminCommerceOrderDetailRequest): Promise<AdminCommerceOrderDetailResponse | null> {
+      return getCommerceOmsOrderDetail(readStore(), request, options);
+    },
+
+    async createHold(request: AdminCommerceOrderHoldRequest & { actorUserId: string }): Promise<AdminCommerceOrderHoldResponse> {
+      return callOmsRpc<AdminCommerceOrderHoldResponse>(client, "commerce_oms_create_hold", {
+        p_idempotency_key: request.idempotencyKey,
+        p_order_id: request.orderId,
+        p_reason: request.reason,
+        p_note: request.note ?? null,
+        p_actor_user_id: request.actorUserId,
+        p_metadata: request.metadata ?? {},
+      });
+    },
+
+    async releaseHold(request: AdminCommerceOrderReleaseHoldRequest & { actorUserId: string }): Promise<AdminCommerceOrderHoldResponse> {
+      return callOmsRpc<AdminCommerceOrderHoldResponse>(client, "commerce_oms_release_hold", {
+        p_idempotency_key: request.idempotencyKey,
+        p_hold_id: request.holdId,
+        p_note: request.note ?? null,
+        p_actor_user_id: request.actorUserId,
+        p_metadata: request.metadata ?? {},
+      });
+    },
+
+    addNote(request: AdminCommerceOrderNoteRequest & { actorUserId: string }): Promise<AdminCommerceOrderNoteResponse> {
+      return addCommerceOmsNote(readStore(), request);
+    },
+
+    updateShippingAddress(
+      request: AdminCommerceOrderUpdateShippingAddressRequest & { actorUserId: string },
+    ): Promise<AdminCommerceOrderUpdateShippingAddressResponse> {
+      return updateCommerceOmsShippingAddress(client, request);
+    },
+
+    async markRefunded(
+      request: AdminCommerceOrderMarkRefundedRequest & { actorUserId: string },
+    ): Promise<AdminCommerceOrderMarkRefundedResponse> {
+      return callOmsRpc<AdminCommerceOrderMarkRefundedResponse>(client, "commerce_order_mark_refunded_manual", {
+        p_idempotency_key: request.idempotencyKey,
+        p_order_id: request.orderId,
+        p_reason: request.reason,
+        p_actor_user_id: request.actorUserId,
+        p_metadata: request.metadata ?? {},
+      });
+    },
+
+    async requestReplacementShipment(
+      request: AdminCommerceOrderRequestReplacementShipmentRequest & { actorUserId: string },
+    ): Promise<AdminCommerceOrderRequestReplacementShipmentResponse> {
+      // Deliberately not `callOmsRpc`: that helper classifies through the shared
+      // `mapRpcError`, whose catch-all would collapse thirteen distinct refusals
+      // into one anonymous "hold conflict". This command's whole operator value is
+      // being told *which* refusal it hit, so the raw error is read here.
+      const { data, error } = await client.rpc("commerce_oms_request_replacement_shipment", {
+        p_idempotency_key: request.idempotencyKey,
+        p_order_id: request.orderId,
+        p_reason: request.reason,
+        p_actor_user_id: request.actorUserId,
+        p_metadata: request.metadata ?? {},
+      });
+      if (error) throw mapReplacementRefusal(error);
+      return data as AdminCommerceOrderRequestReplacementShipmentResponse;
+    },
+
+    async cancelOrder(
+      request: AdminCommerceOrderCancelRequest & { actorUserId: string },
+    ): Promise<AdminCommerceOrderMarkRefundedResponse> {
+      return callOmsRpc<AdminCommerceOrderMarkRefundedResponse>(client, "commerce_oms_cancel_unpaid_order", {
+        p_idempotency_key: request.idempotencyKey,
+        p_order_id: request.orderId,
+        p_reason: request.reason,
+        p_actor_user_id: request.actorUserId,
+        p_metadata: request.metadata ?? {},
+      });
+    },
+  };
+}
+
+/**
+ * Two outcomes, and the split is the honest one. An error naming a refusal this command can
+ * reach - its own `commerce_oms_replacement_*` names, or the reservation vocabulary raised
+ * through `inventory_reserve_order` while it mints the replacement's stock generation - is
+ * something the operator caused and can answer: it becomes a conflict carrying only the
+ * stable reason, not the SQLSTATE and not the message, because that reason is the single
+ * field the operator surface renders from. Anything else never reached a refusal at all
+ * (transport, permissions, a dead connection) and stays an upstream failure keyed by
+ * SQLSTATE, which is diagnostic and never shown as a refusal.
+ *
+ * The reservation half is the one this wave added, and it is the most likely legitimate
+ * refusal in production: the command reserves through an external stock authority, so a
+ * stockout arrives as `inventory_external_provider_insufficient_available_stock`. It carries
+ * no `commerce_oms_replacement_` prefix, matched nothing, and the operator was told to check
+ * holds that were not there. The vocabulary itself lives in
+ * `src/domains/commerce/omsPorts.ts` so the surface renders from the same list.
+ */
+export function mapReplacementRefusal(error: RpcError): Error {
+  const reason = readOmsReplacementRefusal(
+    [error.message, error.details, error.hint].filter(Boolean).join(" "),
+  );
+  if (!reason) {
+    return new CommerceOmsPersistenceError("Commerce OMS replacement request failed", { code: error.code });
+  }
+  return new CommerceOmsConflictError("Commerce OMS replacement request refused", { reason });
+}

package/src/commerce/adapters/managed/oms/accounting.ts

@@ -0,0 +1,18 @@
+import type { OmsAccountingInvoiceRow,OmsAccountingOutboxRow } from "../../../model/omsReadModel.js";
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+import type { CommerceOmsStore } from "./types.js";
+
+export async function readAccountingOutbox(
+  client: CommerceOmsStore,
+  invoices: OmsAccountingInvoiceRow[],
+): Promise<OmsAccountingOutboxRow[]> {
+  const result = invoices.length
+    ? await client
+      .query("accounting_invoice_issue_outbox")
+      .select("invoice_id, status, attempt_count, next_attempt_at, last_error, created_at")
+      .in("invoice_id", invoices.map((invoice) => invoice.id))
+      .order("created_at", { ascending: false })
+    : { data: [], error: null };
+  if (result.error) throw new CommerceOmsPersistenceError("Commerce OMS accounting outbox list read failed");
+  return (result.data ?? []) as OmsAccountingOutboxRow[];
+}

package/src/commerce/adapters/managed/oms/fulfillmentReads.ts

@@ -0,0 +1,82 @@
+import { currentParcelFirst,type FulfillmentParcelRow } from "@openlup/core/fulfillment";
+import type { CommerceOmsStore,RpcError } from "./types.js";
+
+const SHIPMENT_EXTERNAL_REF_BASE_COLUMNS = "order_id, provider_tracking_id, active";
+// `fulfillment_order_id` rides the rich list: it is what narrows an order's references to the
+// parcel currently representing it, and a deployment that predates the column falls back to the
+// base list, where every reference answers for every parcel exactly as it did before.
+const SHIPMENT_EXTERNAL_REF_COLUMNS = `${SHIPMENT_EXTERNAL_REF_BASE_COLUMNS}, fulfillment_order_id, provider_kind, tracking_url, carrier_kind, service, created_at, updated_at`;
+// Kept out of the shared provider-evidence matcher on purpose: that one also guards the
+// fulfillment-order reads, and `fulfillment_order_id` is a column half the schema carries, so
+// folding it in there would silently downgrade an unrelated read on any error naming it.
+function isMissingParcelAttributionError(error: RpcError | null): boolean {
+  if (!error) return false;
+  return `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase().includes("fulfillment_order_id");
+}
+
+function shipmentRefReadDegrades(error: RpcError | null): boolean {
+  return isOptionalProviderEvidenceColumnError(error) || isMissingParcelAttributionError(error);
+}
+
+export async function readShipmentRefsByOrderIds(client: CommerceOmsStore, orderIds: string[]) {
+  if (!orderIds.length) return { data: [], error: null };
+  const result = await client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_COLUMNS).in("order_id", orderIds).eq("active", true);
+  if (!shipmentRefReadDegrades(result.error)) return result;
+  return client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_BASE_COLUMNS).in("order_id", orderIds).eq("active", true);
+}
+
+export async function readShipmentRefsByOrderId(client: CommerceOmsStore, orderId: string) {
+  const result = await client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_COLUMNS).eq("order_id", orderId).eq("active", true);
+  if (!shipmentRefReadDegrades(result.error)) return result;
+  return client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_BASE_COLUMNS).eq("order_id", orderId).eq("active", true);
+}
+
+// `sequence_no` rides the BASE list, not the rich one: it is what resolves which parcel
+// currently represents an order, so the degraded read that drops provider evidence must still
+// be able to answer that question deterministically.
+const FULFILLMENT_ORDER_BASE_COLUMNS = "id, order_id, sequence_no, status, shipping_address_snapshot, handed_over_at, delivered_at, created_at, updated_at";
+// `handed_over_at` rides the query that already reads the row, and is the only durable witness of
+// which side of handover a provider exception happened on - the FSM's `exception` no longer says.
+// `replaces_fulfillment_order_id` and `replacement_reason` ride the rich list with
+// `provider_kind`: they are what tells an operator that the parcel on their screen IS a
+// replacement and why, and a deployment that predates them degrades to the base list, where
+// every parcel reads as the original exactly as it did before the columns existed.
+const FULFILLMENT_ORDER_COLUMNS = `${FULFILLMENT_ORDER_BASE_COLUMNS}, provider_kind, replaces_fulfillment_order_id, replacement_reason`;
+
+// A deployment that predates the optional provider-evidence columns answers the rich select with
+// a missing-column error; every read here retries on the base list rather than failing.
+export function isOptionalProviderEvidenceColumnError(error: { code?: string; message?: string; details?: string; hint?: string } | null): boolean {
+  if (!error) return false;
+  const text = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase();
+  return ["fulfillment_provider_stock_current", "provider_kind", "tracking_url", "carrier_kind", "service", "replaces_fulfillment_order_id", "replacement_reason"].some((column) => text.includes(column)); // Only columns the BASE list OMITS belong here: created_at/updated_at are in it, so they could never be recovered - they only widened the silent downgrade.
+}
+
+// Deliberately no `.maybeSingle()`: PostgREST *errors* (PGRST116) when a single-object read
+// matches two rows, and an order carrying a replacement parcel holds two.
+//
+// ⚠️ This returns EVERY parcel of the order, current one first, where it used to return the
+// current one alone. That is what stopped the original parcel's tracking from vanishing from
+// the operator's screen the moment a replacement existed. Callers that need exactly one row
+// take `[0]`, which `currentParcelFirst` guarantees is the current parcel; nothing downstream
+// widens its attribution, because the provider-evidence reads are still keyed on that one id.
+export async function readFulfillmentParcelsByOrderId(client: CommerceOmsStore, orderId: string): Promise<{ data: unknown[]; error: RpcError | null }> {
+  const rich = await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_COLUMNS).eq("order_id", orderId);
+  const result = isOptionalProviderEvidenceColumnError(rich.error)
+    ? await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_BASE_COLUMNS).eq("order_id", orderId)
+    : rich;
+  if (result.error) return { data: [], error: result.error };
+  return { data: currentParcelFirst((result.data ?? []) as FulfillmentParcelRow[]), error: null };
+}
+
+// The list read hands every order's rows to one builder, which narrows per order and then takes
+// the first of what is left (`omsReadModelList.ts` filter -> `omsFulfillmentSummary.ts` [0]), so
+// each order's rows must arrive with its current parcel first.
+export async function readFulfillmentOrdersByOrderIds(client: CommerceOmsStore, orderIds: string[]): Promise<{ data: unknown[]; error: RpcError | null }> {
+  if (!orderIds.length) return { data: [], error: null };
+  const rich = await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_COLUMNS).in("order_id", orderIds);
+  const result = isOptionalProviderEvidenceColumnError(rich.error)
+    ? await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_BASE_COLUMNS).in("order_id", orderIds)
+    : rich;
+  if (result.error) return { data: [], error: result.error };
+  return { data: currentParcelFirst((result.data ?? []) as FulfillmentParcelRow[]), error: null };
+}

package/src/commerce/adapters/managed/oms/inboundEvents.ts

@@ -0,0 +1,45 @@
+import type { OmsInboundProviderEventRow } from "../../../model/omsFulfillmentDebug.js";
+import type { OmsProviderDispatchRefRow } from "../../../model/omsFulfillmentSummary.js";
+import type { OmsOrderRow } from "../../../model/omsReadModel.js";
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+import { distinctIds,type CommerceOmsStore } from "./types.js";
+
+const INBOUND_EVENT_COLUMNS = "id, provider, provider_event_id, event_type, processing_status, payload, error, created_at, processed_at";
+
+export async function readOmsInboundEvents(
+  client: CommerceOmsStore,
+  input: { order: OmsOrderRow; dispatchRefs: OmsProviderDispatchRefRow[]; providerKind: string },
+): Promise<OmsInboundProviderEventRow[]> {
+  const needles = distinctIds([
+    input.order.order_number,
+    input.order.id,
+    ...input.dispatchRefs.map((row) => row.provider_order_id ?? null),
+  ]);
+  if (!needles.length) return [];
+  const result = await client
+    .query("inbound_provider_events")
+    .select(INBOUND_EVENT_COLUMNS)
+    .eq("provider", input.providerKind)
+    .order("created_at", { ascending: false })
+    .range(0, 49);
+  if (isOptionalInboundEventError(result.error)) return [];
+  if (result.error) throw new CommerceOmsPersistenceError("Commerce OMS provider inbound events read failed");
+  return ((result.data ?? []) as OmsInboundProviderEventRow[]).filter((row) => matchesNeedle(row, needles));
+}
+
+function matchesNeedle(row: OmsInboundProviderEventRow, needles: string[]): boolean {
+  const haystack = JSON.stringify({
+    providerEventId: row.provider_event_id,
+    eventType: row.event_type,
+    payload: row.payload,
+    error: row.error,
+  });
+  return needles.some((needle) => haystack.includes(needle));
+}
+
+function isOptionalInboundEventError(error: { code?: string; message?: string; details?: string; hint?: string } | null): boolean {
+  if (!error) return false;
+  if (error.code === "42P01" || error.code === "42703") return true;
+  const text = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase();
+  return text.includes("inbound_provider_events");
+}

package/src/commerce/adapters/managed/oms/outboxEvents.ts

@@ -0,0 +1,30 @@
+import { COMMERCE_ORDER_PAID_EVENT_TYPE } from "../../../outboxEventSchemas.js";
+import type { CommerceOmsStore } from "./types.js";
+
+const ORDER_PAID_OUTBOX_COLUMNS = "id,event_type,status,aggregate_id,created_at,available_at,attempts";
+const ORDER_PAID_OUTBOX_BASE_COLUMNS = "id,event_type,status,aggregate_id,created_at,available_at";
+
+export async function readOrderPaidOutboxEvents(client: CommerceOmsStore, orderId: string) {
+  const primary = await selectOrderPaidOutboxEvents(client, orderId, ORDER_PAID_OUTBOX_COLUMNS);
+  if (!isMissingAttemptsColumn(primary.error)) return primary;
+  return selectOrderPaidOutboxEvents(client, orderId, ORDER_PAID_OUTBOX_BASE_COLUMNS);
+}
+
+function selectOrderPaidOutboxEvents(
+  client: CommerceOmsStore,
+  orderId: string,
+  columns: string,
+) {
+  return client
+    .query("outbox_events")
+    .select(columns)
+    .eq("event_type", COMMERCE_ORDER_PAID_EVENT_TYPE)
+    .eq("aggregate_id", orderId)
+    .order("created_at", { ascending: false });
+}
+
+function isMissingAttemptsColumn(error: { message?: string; details?: string; hint?: string } | null): boolean {
+  if (!error) return false;
+  const text = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase();
+  return text.includes("attempts");
+}

package/src/commerce/adapters/managed/oms/paymentAttempts.ts

@@ -0,0 +1,19 @@
+import type { OmsPaymentAttemptRow,OmsPaymentIntentRow } from "../../../model/omsReadModel.js";
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+import type { CommerceOmsStore } from "./types.js";
+
+export async function readActivePaymentAttempts(
+  client: CommerceOmsStore,
+  paymentIntents: OmsPaymentIntentRow[],
+): Promise<OmsPaymentAttemptRow[]> {
+  const attemptIds = paymentIntents
+    .map((intent) => intent.active_attempt_id)
+    .filter((id): id is string => Boolean(id));
+  if (attemptIds.length === 0) return [];
+  const result = await client
+    .query("commerce_payment_attempts")
+    .select("id, payment_intent_id, status, provider, provider_attempt_id, next_action_kind, updated_at")
+    .in("id", attemptIds);
+  if (result.error) throw new CommerceOmsPersistenceError("Commerce OMS payment attempt list read failed");
+  return (result.data ?? []) as OmsPaymentAttemptRow[];
+}

package/src/commerce/adapters/managed/oms/queueSelection.ts

@@ -0,0 +1,132 @@
+import type { OmsManagedReadProjections } from "../../../contracts/omsTypes.js";
+type MatchSchema = NonNullable<OmsManagedReadProjections["queueMatchSchema"]>;
+import type { QueueSelection } from "../../../contracts/omsTypes.js";
+import { neutralOmsCurrencyPolicy,type OmsCurrencyPolicy } from "../../../model/omsCurrency.js";
+import type {
+AdminCommerceOrdersListRequest,
+AdminOmsOrderListSummaryCounts,
+AdminOmsOrderSearchMatch
+} from "../../../oms/omsContracts.js";
+import { omsOrderListSummaryCountsSchema,omsOrderListSummaryTotalsSchema,omsOrderSearchMatchSchema } from "../../../oms/omsContracts.js";
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+import type { CommerceOmsStore,RpcError } from "./types.js";
+export type { QueueSelection } from "../../../contracts/omsTypes.js";
+
+/** The refusal the queue RPC raises when the paid set spans several currencies. */
+const MIXED_CURRENCY_REFUSAL = "commerce_oms_summary_mixed_currency";
+
+export async function readQueueSelection(
+  client: CommerceOmsStore,
+  request: AdminCommerceOrdersListRequest,
+  options: { currency?: OmsCurrencyPolicy; matchSchema?: MatchSchema; projectResult?(data: unknown): unknown } = {},
+): Promise<QueueSelection> {
+  const { data, error } = await client.rpc("commerce_oms_admin_list_queue", {
+    p_page: request.page,
+    p_page_size: request.pageSize,
+    p_search: request.search ?? null,
+    p_status: request.status ?? null,
+    p_mode: request.mode ?? null,
+    p_payment_status: request.paymentStatus ?? null,
+    p_fulfillment_status: request.fulfillmentStatus ?? null,
+    p_inventory_status: request.inventoryStatus ?? null,
+    p_accounting_status: request.accountingStatus ?? null,
+    p_provider_ops_status: request.providerOpsStatus ?? null,
+    p_attention_reason: request.attentionReason ?? null,
+    p_attention_only: request.attentionOnly ?? false,
+    p_next_action: request.nextAction ?? null,
+    p_from: request.from ?? null,
+    p_to: request.to ?? null,
+    p_sort: request.sort,
+    // Default false: the queue hides withdrawn rows unless the operator asks.
+    // The RPC declares no parameter defaults, so this must always be sent.
+    p_include_withdrawn: request.includeWithdrawn ?? false,
+  });
+  if (error) throw queueSelectionError(error);
+  return parseQueueSelection(options.projectResult?.(data) ?? data, options.currency ?? neutralOmsCurrencyPolicy, options.matchSchema);
+}
+
+// A cross-currency paid set is a refusal the RPC raises on purpose, not a
+// generic read failure: it names an operator-visible condition (two currencies
+// in one dashboard total) that a retry will not clear. Keep it distinguishable.
+function queueSelectionError(error: RpcError): CommerceOmsPersistenceError {
+  const raised = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`;
+  if (raised.includes(MIXED_CURRENCY_REFUSAL)) {
+    return new CommerceOmsPersistenceError(
+      "Commerce OMS queue summary spans more than one currency",
+      { reason: MIXED_CURRENCY_REFUSAL },
+    );
+  }
+  return new CommerceOmsPersistenceError("Commerce OMS queue selection read failed");
+}
+
+function parseQueueSelection(data: unknown, currency: OmsCurrencyPolicy, matchSchema: MatchSchema = omsOrderSearchMatchSchema): QueueSelection {
+  const record = isRecord(data) ? data : {};
+  const orderIds = Array.isArray(record.orderIds)
+    ? record.orderIds.filter((id): id is string => typeof id === "string")
+    : [];
+  const totalCount = Number(record.totalCount ?? 0);
+  const summaryCounts = omsOrderListSummaryCountsSchema.parse({
+    ...ZERO_SUMMARY_COUNTS,
+    ...(isRecord(record.summaryCounts) ? record.summaryCounts : {}),
+  });
+  const summaryTotals = omsOrderListSummaryTotalsSchema.parse({
+    gmv: { amountMinor: 0, currency: currency.defaultCurrency },
+    aov: { amountMinor: 0, currency: currency.defaultCurrency },
+    orderCount: 0, paidSubscriptionCycleCount: 0,
+    ...normalizeSummaryTotals(isRecord(record.summaryTotals) ? record.summaryTotals : {}, currency),
+  });
+  const matches = parseMatches(record.matches, matchSchema);
+  if (!Number.isInteger(totalCount) || totalCount < 0) {
+    throw new CommerceOmsPersistenceError("Commerce OMS queue selection count invalid");
+  }
+  return { orderIds, totalCount, matches, summaryCounts, summaryTotals };
+}
+
+function parseMatches(value: unknown, schema: MatchSchema): Record<string, AdminOmsOrderSearchMatch> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([orderId, match]) => {
+      const parsed = schema.safeParse(match);
+      return parsed.success ? [[orderId, parsed.data]] : [];
+    }),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+// The queue RPC still emits the legacy `newSubscriptionCount` JSON key. It counts
+// PAID subscription cycles (the initial checkout cycle #1 plus every paid renewal),
+// so map it onto the accurately-named `paidSubscriptionCycleCount` contract field.
+// The new key is accepted too, so a future RPC rename is a no-op here.
+function normalizeSummaryTotals(raw: Record<string, unknown>, currency: OmsCurrencyPolicy): Record<string, unknown> {
+  const { newSubscriptionCount, gmv, aov, ...rest } = raw;
+  const normalized: Record<string, unknown> = { ...rest };
+  if (gmv !== undefined) normalized.gmv = withDefaultCurrency(gmv, currency);
+  if (aov !== undefined) normalized.aov = withDefaultCurrency(aov, currency);
+  if (newSubscriptionCount !== undefined) {
+    normalized.paidSubscriptionCycleCount = normalized.paidSubscriptionCycleCount ?? newSubscriptionCount;
+  }
+  return normalized;
+}
+
+// The queue RPC no longer names a currency: `min(currency)` over an EMPTY paid
+// set is NULL by design, so the schema stays currency-agnostic. Labelling a
+// zero total is a platform-policy decision, and policy has exactly one home.
+function withDefaultCurrency(money: unknown, currency: OmsCurrencyPolicy): unknown {
+  if (!isRecord(money) || money.currency != null) return money;
+  return { ...money, currency: currency.defaultCurrency };
+}
+
+const ZERO_SUMMARY_COUNTS: AdminOmsOrderListSummaryCounts = {
+  needsAttention: 0,
+  activeHold: 0,
+  readyForFulfillment: 0,
+  paymentIssues: 0,
+  inventoryRisk: 0,
+  fulfillmentBlocked: 0,
+  fulfillmentExceptions: 0,
+  invoiceIssues: 0,
+  providerDispatchedNotPicked: 0,
+};

package/src/commerce/adapters/managed/oms/readProjections.ts

@@ -0,0 +1,22 @@
+import type { OmsManagedReadProjections } from "../../../contracts/omsTypes.js";
+export type { OmsManagedReadProjections } from "../../../contracts/omsTypes.js";
+import type { OmsReadModelProjections } from "../../../model/omsReadModelProjections.js";
+import type { OmsOrderDetail } from "../../../oms/omsContracts.js";
+import type { OmsOrderRow, OmsOrderItemRow, OmsPaymentIntentRow, OmsAccountingInvoiceRow } from "../../../model/omsReadModelRows.js";
+import type { OmsFulfillmentOperationRow, OmsFulfillmentOrderRow, OmsProviderDispatchRefRow, OmsProviderStatusEvidenceRow, OmsProviderAttemptRow, OmsReleasedProviderExceptionHoldRow } from "../../../model/omsFulfillmentSummary.js";
+import type { OmsInboundProviderEventRow, OmsFulfillmentProviderStockCurrentRow } from "../../../model/omsFulfillmentDebug.js";
+import type { CommerceOmsStore } from "./types.js";
+
+export const emptyOmsManagedReadProjections = {
+  readIdentity: async (): Promise<Record<string, Record<string, unknown>>> => ({}),
+  mapInvoice: (value: unknown) => value as OmsAccountingInvoiceRow,
+  readFulfillmentOperations: async () => [],
+  readProviderDispatchRefs: async () => [],
+  readProviderStatusEvidence: async () => [],
+  readProviderAttempts: async () => [],
+  readReleasedProviderExceptionHolds: async () => [],
+  readProviderStockCurrent: async () => [],
+  readInboundEvents: async () => [],
+  buildHealth: (input: { order: OmsOrderRow }): OmsOrderDetail["fulfillmentHealth"] => ({ healthStatus: "ok", attentionReasons: [], oldestAgeSeconds: null, opaqueIds: { orderId: input.order.id, fulfillmentOrderId: null, outboxEventId: null, dispatchRefFulfillmentOrderId: null, latestEvidenceFulfillmentOrderId: null } }),
+  buildHealthDigests: () => ({}),
+};