@openlup/platform 0.25.0 → 0.27.0

package/dist/inventory/postgresStockAvailability.js

@@ -1,16 +1,4 @@
-function object(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new Error("inventory_stock_response_invalid");
-    return value;
-}
-function quantity(value) {
-    if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "")
-        throw new Error("inventory_stock_quantity_invalid");
-    const n = Number(value);
-    if (!Number.isSafeInteger(n) || n < 0)
-        throw new Error("inventory_stock_quantity_invalid");
-    return n;
-}
+import { parseStockReadResponse, stockObject as object, stockQuantity as quantity } from "./stockReadResponse.js";
 /** Native read-only ATP. The fixed 14-day priority cannot be waived by a new
  * purchase caller. Only the fenced native SQL allocator uses the renewal exemption. */
 export function createPostgresStockAvailability(executor, options) {
@@ -30,18 +18,7 @@ export function createPostgresStockAvailability(executor, options) {
                     return new Map();
                 const value = (await executor.query(`SELECT public.inventory_new_purchase_stock_read(
           $1::text,$2::jsonb,$3::timestamptz) AS response`, [options.sourceKey, JSON.stringify(input.skus), options.now()])).rows[0]?.response;
-                if (!Array.isArray(value))
-                    throw new Error("inventory_stock_response_invalid");
-                return new Map(value.map(value => {
-                    const row = object(value);
-                    if (typeof row.sku !== "string" || !["provider", "missing"].includes(String(row.source)) || typeof row.stale !== "boolean")
-                        throw new Error("inventory_stock_response_invalid");
-                    const result = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
-                        source: row.source, providerForSale: row.providerForSale == null ? null : quantity(row.providerForSale),
-                        activeHolds: quantity(row.activeHolds), safetyStock: quantity(row.safetyStock), available: quantity(row.available), stale: row.stale,
-                        renewalDemand: quantity(row.renewalDemand), availableForNewPurchases: quantity(row.availableForNewPurchases), excludedOrderHolds: quantity(row.excludedOrderHolds) };
-                    return [result.sku, result];
-                }));
+                return parseStockReadResponse(value);
             },
         },
     };

package/dist/inventory/schemas.d.ts

@@ -106,8 +106,8 @@ export declare function createInventorySubscriptionForecastResponseSchema(provid
         providerStockLastSyncedAt: z.ZodNullable<z.ZodString>;
         providerStockStaleAfter: z.ZodNullable<z.ZodString>;
         stockStatus: z.ZodEnum<{
-            stale: "stale";
             missing: "missing";
+            stale: "stale";
             fresh: "fresh";
         }>;
         openHardReservations: z.ZodNumber;

package/dist/inventory/stockReadResponse.d.ts

@@ -0,0 +1,4 @@
+import type { NewPurchaseStockRow } from "./contracts/newPurchaseStock.js";
+export declare function stockObject(value: unknown): Record<string, unknown>;
+export declare function stockQuantity(value: unknown): number;
+export declare function parseStockReadResponse(value: unknown): Map<string, NewPurchaseStockRow>;

package/dist/inventory/stockReadResponse.js

@@ -0,0 +1,27 @@
+export function stockObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("inventory_stock_response_invalid");
+    return value;
+}
+export function stockQuantity(value) {
+    if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "")
+        throw new Error("inventory_stock_quantity_invalid");
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new Error("inventory_stock_quantity_invalid");
+    return n;
+}
+export function parseStockReadResponse(value) {
+    if (!Array.isArray(value))
+        throw new Error("inventory_stock_response_invalid");
+    return new Map(value.map(value => {
+        const row = stockObject(value);
+        if (typeof row.sku !== "string" || !["provider", "missing"].includes(String(row.source)) || typeof row.stale !== "boolean")
+            throw new Error("inventory_stock_response_invalid");
+        const result = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
+            source: row.source, providerForSale: row.providerForSale == null ? null : stockQuantity(row.providerForSale),
+            activeHolds: stockQuantity(row.activeHolds), safetyStock: stockQuantity(row.safetyStock), available: stockQuantity(row.available), stale: row.stale,
+            renewalDemand: stockQuantity(row.renewalDemand), availableForNewPurchases: stockQuantity(row.availableForNewPurchases), excludedOrderHolds: stockQuantity(row.excludedOrderHolds) };
+        return [result.sku, result];
+    }));
+}

package/dist/pricing/browser/index.d.ts

@@ -0,0 +1,6 @@
+export { createCommerceQuotePrimitives } from "../quotePrimitives.js";
+export { acquisitionCapabilitySchema, acquisitionTermsExpectationSchema } from "../acquisitionTermsSchemas.js";
+/** @consumer src/domains/commerce/quoteContracts.ts */
+export { resolvedAcquisitionTermsSchema } from "../acquisitionTermsSchemas.js";
+/** @consumer src/domains/commerce/quoteContracts.ts */
+export { shippingTermsSchema } from "../../shipping/thresholdPolicy.js";

package/dist/pricing/browser/index.js

@@ -0,0 +1,6 @@
+export { createCommerceQuotePrimitives } from "../quotePrimitives.js";
+export { acquisitionCapabilitySchema, acquisitionTermsExpectationSchema } from "../acquisitionTermsSchemas.js";
+/** @consumer src/domains/commerce/quoteContracts.ts */
+export { resolvedAcquisitionTermsSchema } from "../acquisitionTermsSchemas.js";
+/** @consumer src/domains/commerce/quoteContracts.ts */
+export { shippingTermsSchema } from "../../shipping/thresholdPolicy.js";

package/dist/promotions/adminPromotionsContracts.d.ts

@@ -42,8 +42,8 @@ export declare function createAdminPromotionSchemas({ currencySchema: platformCu
         code: z.ZodNullable<z.ZodString>;
         name: z.ZodString;
         triggerType: z.ZodEnum<{
-            automatic: "automatic";
             coupon_code: "coupon_code";
+            automatic: "automatic";
             referral: "referral";
         }>;
         discountType: z.ZodEnum<{
@@ -116,8 +116,8 @@ export declare function createAdminPromotionSchemas({ currencySchema: platformCu
             code: z.ZodNullable<z.ZodString>;
             name: z.ZodString;
             triggerType: z.ZodEnum<{
-                automatic: "automatic";
                 coupon_code: "coupon_code";
+                automatic: "automatic";
                 referral: "referral";
             }>;
             discountType: z.ZodEnum<{

package/dist/subscriptions/contracts/renewal.d.ts

@@ -129,9 +129,11 @@ export interface CycleChargeFailurePropagationPort {
         };
     }): Promise<{
         replayed: boolean;
+        paymentAttemptId?: string | null;
     }>;
     readCycleRetryState(cycleId: string): Promise<CycleRetryState>;
     openDunningCase(input: {
+        failedPaymentAttemptId: string | null;
         idempotencyKey: string;
         cycleId: string;
         subscriptionId: string;

package/dist/subscriptions/index.d.ts

@@ -39,8 +39,9 @@ export { createPostgresSubscriptionCommandStore, createPostgresSubscriptionComma
 export type { NativeSubscriptionCommand, NativeSubscriptionCommandBinding } from "./postgresCommandStore.js";
 export { createPostgresStockWaitStore } from "./postgresStockWaitStore.js";
 export type { NativeStockWaitBinding, NativeStockWaitAdmission } from "./postgresStockWaitStore.js";
-/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort or
- * NewPurchaseStockReadPort TypeScript adapter is composed for this graph.
+/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort
+ * TypeScript adapter is composed for this graph. A NewPurchaseStockReadPort
+ * adapter is available in ../inventory for managed service-role hosts.
  * SQL behavior is proved by the managed pgTAP/real-PostgreSQL witnesses.
  */
 export declare const MANAGED_SUBSCRIPTION_STOCK_CAPABILITIES: Readonly<{

package/dist/subscriptions/index.js

@@ -19,8 +19,9 @@ export { createPostgresRetryStore } from "./postgresRetryStore.js";
 export { createPostgresRetryLifecycleBinding } from "./postgresRetryStore.js";
 export { createPostgresSubscriptionCommandStore, createPostgresSubscriptionCommands } from "./postgresCommandStore.js";
 export { createPostgresStockWaitStore } from "./postgresStockWaitStore.js";
-/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort or
- * NewPurchaseStockReadPort TypeScript adapter is composed for this graph.
+/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort
+ * TypeScript adapter is composed for this graph. A NewPurchaseStockReadPort
+ * adapter is available in ../inventory for managed service-role hosts.
  * SQL behavior is proved by the managed pgTAP/real-PostgreSQL witnesses.
  */
 export const MANAGED_SUBSCRIPTION_STOCK_CAPABILITIES = Object.freeze({

package/dist/subscriptions/renewalCycleFailureMechanism.js

@@ -25,7 +25,7 @@ export async function propagateRenewalFailure(port, ctx, policy) {
     });
     const cycleSnapshot = await port.readCycleRetryState(ctx.cycleId);
     return {
-        ...await openDunningCase(port, ctx, cycleSnapshot, occurredAt, policy),
+        ...await openDunningCase(port, ctx, cycleSnapshot, occurredAt, policy, applied.paymentAttemptId ?? null),
         applyReplayed: applied.replayed,
     };
 }
@@ -37,7 +37,7 @@ async function resolveDurableOccurredAt(port, ctx, policy) {
     });
     return durable !== null && durable.length > 0 ? durable : ctx.occurredAt;
 }
-async function openDunningCase(port, ctx, cycle, occurredAt, policy) {
+async function openDunningCase(port, ctx, cycle, occurredAt, policy, failedPaymentAttemptId) {
     const retryAttempt = cycle.retryAttempt ?? 1;
     // Resolve again after the retry read: original context evidence remains dynamic.
     const failureClass = policy.resolveClassification(ctx.failureClassification, ctx.failureReason).failureClass;
@@ -52,6 +52,7 @@ async function openDunningCase(port, ctx, cycle, occurredAt, policy) {
         ? cycle.nextRetryAt
         : nextRetryAttemptAt(occurredAt, retryAttempt, undefined, failureClass);
     const outcome = await port.openDunningCase({
+        failedPaymentAttemptId,
         idempotencyKey: policy.dunningKey(ctx.executionIdempotencyKey, retryAttempt),
         cycleId: ctx.cycleId,
         subscriptionId: ctx.subscriptionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.25.0",
+    "@openlup/core": "0.27.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"
@@ -106,6 +106,21 @@
       "import": "./dist/identity/contracts/index.js",
       "default": "./dist/identity/contracts/index.js"
     },
+    "./commerce": {
+      "types": "./dist/commerce/index.d.ts",
+      "import": "./dist/commerce/index.js",
+      "default": "./dist/commerce/index.js"
+    },
+    "./commerce/contracts": {
+      "types": "./dist/commerce/contracts/index.d.ts",
+      "import": "./dist/commerce/contracts/index.js",
+      "default": "./dist/commerce/contracts/index.js"
+    },
+    "./commerce/server": {
+      "types": "./dist/commerce/server/index.d.ts",
+      "import": "./dist/commerce/server/index.js",
+      "default": "./dist/commerce/server/index.js"
+    },
     "./communications": {
       "types": "./dist/communications/index.d.ts",
       "import": "./dist/communications/index.js",
@@ -131,6 +146,11 @@
       "import": "./dist/pricing/index.js",
       "default": "./dist/pricing/index.js"
     },
+    "./pricing/browser": {
+      "types": "./dist/pricing/browser/index.d.ts",
+      "import": "./dist/pricing/browser/index.js",
+      "default": "./dist/pricing/browser/index.js"
+    },
     "./pricing/contracts": {
       "types": "./dist/pricing/contracts/index.d.ts",
       "import": "./dist/pricing/contracts/index.js",

package/release-gates.json

@@ -66,6 +66,46 @@
       "entrypoint": "dist/catalog/contracts/index.d.ts",
       "snapshot": "api/catalog-contracts.api.md"
     },
+    "./commerce": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/commerce/portFit.test.ts",
+        "test/commerce/ports.test.ts",
+        "test/commerce/recoveryDestinationPolicy.test.ts",
+        "test/commerce/commerceQuoteCompositionCharacterization.test.ts"
+      ],
+      "entrypoint": "dist/commerce/index.d.ts",
+      "snapshot": "api/commerce.api.md"
+    },
+    "./commerce/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/commerce/portFit.test.ts",
+        "test/commerce/ports.test.ts",
+        "test/commerce/recoveryDestinationPolicy.test.ts",
+        "test/commerce/commerceQuoteCompositionCharacterization.test.ts"
+      ],
+      "entrypoint": "dist/commerce/contracts/index.d.ts",
+      "snapshot": "api/commerce-contracts.api.md"
+    },
+    "./commerce/server": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/commerce/browserBoundary.test.ts",
+        "test/commerce/browserSafety.test.ts"
+      ],
+      "entrypoint": "dist/commerce/server/index.d.ts",
+      "snapshot": "api/commerce-server.api.md"
+    },
     "./communications": {
       "role": "capability",
       "maturity": "experimental",
@@ -266,6 +306,19 @@
       "entrypoint": "dist/pricing/index.d.ts",
       "snapshot": "api/pricing.api.md"
     },
+    "./pricing/browser": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/commerce/browserBoundary.test.ts",
+        "test/pricing/quoteContracts.test.ts",
+        "test/pricing/acquisition.test.ts"
+      ],
+      "entrypoint": "dist/pricing/browser/index.d.ts",
+      "snapshot": "api/pricing-browser.api.md"
+    },
     "./pricing/contracts": {
       "role": "capability",
       "maturity": "experimental",
@@ -524,19 +577,19 @@
   },
   "pack": {
     "code": {
-      "maxPackedBytes": 1228800,
-      "maxFiles": 2000
+      "maxPackedBytes": 1648000,
+      "maxFiles": 2520
     },
     "docs": {
       "maxPackedBytes": 57344,
       "maxFiles": 10
     },
-    "maxPackedBytes": 1474560,
-    "maxUnpackedBytes": 6553600,
-    "maxFiles": 2100,
+    "maxPackedBytes": 1925000,
+    "maxUnpackedBytes": 8970000,
+    "maxFiles": 2580,
     "baseline": {
-      "version": "0.24.0",
-      "packedBytes": 1355949
+      "version": "0.26.0",
+      "packedBytes": 1388257
     },
     "browserEntries": {
       "./catalog/contracts": 4096,
@@ -549,7 +602,9 @@
       "./payments/contracts": 32,
       "./fulfillment/contracts": 32,
       "./subscriptions/contracts": 32,
-      "./invoicing/contracts": 32
+      "./invoicing/contracts": 32,
+      "./commerce/contracts": 32,
+      "./pricing/browser": 25600
     }
   }
 }

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

@@ -0,0 +1,80 @@
+import type { AdminOmsOrderListItem } from "../../oms/omsContracts.js";
+import {
+OMS_CONTROL_PLANE_VERSION,
+omsControlPlaneActions,
+omsControlPlaneDetailResponseSchema,
+omsControlPlaneListResponseSchema,
+type CommerceOmsControlPlanePort,
+type OmsControlPlaneOrder,
+} from "../../oms/omsControlPlane.js";
+import type { CommerceOmsReadPort } from "../../oms/omsPorts.js";
+
+export function createManagedCommerceOmsControlPlanePort(
+  managedPort: CommerceOmsReadPort,
+): CommerceOmsControlPlanePort {
+  return {
+    async listOrders(request) {
+      const result = await managedPort.listOrders({
+        page: request.page,
+        pageSize: request.pageSize,
+        status: request.status,
+        sort: "created_desc",
+      });
+      return omsControlPlaneListResponseSchema.parse({
+        contractVersion: OMS_CONTROL_PLANE_VERSION,
+        orders: result.orders.map(mapOrder),
+        totalCount: result.totalCount,
+        page: result.page,
+        pageSize: result.pageSize,
+      });
+    },
+    async getOrderDetail(request) {
+      const result = await managedPort.getOrderDetail({ orderId: request.orderId });
+      if (!result) return null;
+      const operation = (type: string) => {
+        if (type === "hold_created" || type === "hold_released") return type;
+        if (type === "order_cancelled_manual") return "order_cancelled" as const;
+        if (type === "order_marked_refunded") return "order_refunded" as const;
+        return null;
+      };
+      return omsControlPlaneDetailResponseSchema.parse({
+        contractVersion: OMS_CONTROL_PLANE_VERSION,
+        order: mapOrder(result.order),
+        holds: result.order.holds.map((hold) => ({
+          id: hold.id,
+          status: hold.status,
+          reason: hold.reason,
+          note: hold.note,
+          createdAt: hold.createdAt,
+          releasedAt: hold.releasedAt,
+        })),
+        operations: result.order.operations.flatMap((entry) => {
+          const action = operation(entry.type);
+          return action ? [{
+            id: entry.id,
+            action,
+            holdId: entry.holdId,
+            actorId: entry.actorUserId,
+            occurredAt: entry.occurredAt,
+          }] : [];
+        }),
+      });
+    },
+  };
+}
+
+function mapOrder(order: AdminOmsOrderListItem): OmsControlPlaneOrder {
+  return {
+    orderId: order.orderId,
+    status: order.status,
+    sourceKind: order.sourceKind ?? "storefront",
+    sourceOrderRef: order.sourceOrderRef ?? null,
+    money: order.total,
+    shipmentStatus: order.fulfillmentStatus,
+    activeHoldCount: order.activeHoldCount,
+    activeHoldReasons: order.activeHoldReasons,
+    actions: omsControlPlaneActions(order.status, order.activeHoldCount),
+    createdAt: order.createdAt,
+    updatedAt: order.updatedAt,
+  };
+}

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

@@ -0,0 +1,145 @@
+import type { OmsOperationRow } from "../../model/omsReadModel.js";
+import { COMMERCE_CONTRACT_VERSION } from "../../../pricing/contracts/index.js";
+import type {
+AdminCommerceOrderNoteRequest,
+AdminCommerceOrderNoteResponse,
+AdminCommerceOrderUpdateShippingAddressRequest,
+AdminCommerceOrderUpdateShippingAddressResponse,
+} from "../../oms/omsContracts.js";
+import {
+CommerceOmsConflictError,
+CommerceOmsPersistenceError,
+} from "../../oms/omsPorts.js";
+import type { CommerceOmsRpcClient,CommerceOmsStore,RpcError } from "./oms/types.js";
+
+const OPERATION_COLUMNS = "id, order_id, operation_type, hold_id, actor_user_id, occurred_at, payload";
+
+export async function addCommerceOmsNote(
+  client: CommerceOmsStore,
+  request: AdminCommerceOrderNoteRequest & { actorUserId: string },
+): Promise<AdminCommerceOrderNoteResponse> {
+  const insertResult = await client
+    .query("commerce_order_operations")
+    .insert({
+      order_id: request.orderId,
+      actor_user_id: request.actorUserId,
+      operation_type: "support_note",
+      idempotency_key: request.idempotencyKey,
+      payload: { note: request.note, metadata: request.metadata ?? {}, source: "commerce.oms.v0" },
+    })
+    .select(OPERATION_COLUMNS)
+    .maybeSingle();
+
+  if (insertResult.error) {
+    if (insertResult.error.code === "23505") {
+      const replayResult = await client
+        .query("commerce_order_operations")
+        .select(OPERATION_COLUMNS)
+        .eq("idempotency_key", request.idempotencyKey)
+        .maybeSingle();
+      if (replayResult.error || !replayResult.data) throw mapRpcError(insertResult.error);
+      return noteResponse(replayResult.data as OmsOperationRow, true);
+    }
+    throw mapRpcError(insertResult.error);
+  }
+  return noteResponse(insertResult.data as OmsOperationRow, false);
+}
+
+export async function updateCommerceOmsShippingAddress(
+  client: CommerceOmsRpcClient,
+  request: AdminCommerceOrderUpdateShippingAddressRequest & { actorUserId: string },
+): Promise<AdminCommerceOrderUpdateShippingAddressResponse> {
+  return callOmsRpc<AdminCommerceOrderUpdateShippingAddressResponse>(client, "commerce_oms_update_shipping_address", {
+    p_idempotency_key: request.idempotencyKey,
+    p_order_id: request.orderId,
+    p_address: request.address,
+    p_actor_user_id: request.actorUserId,
+    p_metadata: {
+      ...(request.metadata ?? {}),
+      _deliveryContactExpectedRevision: request.expectedRevision,
+      _deliveryContactExpectedDigest: request.expectedContactDigest,
+    },
+  });
+}
+
+// Every OMS control RPC answers the same way: the function's own jsonb response,
+// or a Postgres error this module already knows how to classify. The cast is not
+// a validation step and never was - it is recorded here once instead of at each
+// call site, so tightening it later is one edit.
+export async function callOmsRpc<T>(
+  client: CommerceOmsRpcClient,
+  functionName: string,
+  args: Record<string, unknown>,
+): Promise<T> {
+  const { data, error } = await client.rpc(functionName, args);
+  if (error) throw mapRpcError(error);
+  return data as T;
+}
+
+/**
+ * SQLSTATE 55P03. A routine here gave up waiting for a lock another writer holds
+ * and returned before touching anything - not a failure, a refusal, and the same
+ * request may be sent again unchanged.
+ *
+ * It is read from the code rather than the message because the server's text for
+ * it ("canceling statement due to lock timeout") names no routine of ours, so
+ * there is nothing for `readShippingAddressReason` to match on. The reason stays
+ * routine-neutral for the same span the mapper covers: today only the shipping
+ * address correction bounds its waits, but this classification is true of any OMS
+ * routine that later does, and a `delivery_contact_` prefix would be a lie the
+ * day one of the hold routines raises it.
+ */
+const LOCK_TIMEOUT_SQLSTATE = "55P03";
+
+export function mapRpcError(error: RpcError): Error {
+  const text = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+  if (error.code === LOCK_TIMEOUT_SQLSTATE) {
+    return new CommerceOmsConflictError("Commerce OMS request could not take its locks", {
+      code: error.code,
+      reason: "lock_timeout",
+    });
+  }
+  const shippingAddressReason = readShippingAddressReason(text);
+  if (shippingAddressReason) {
+    return new CommerceOmsConflictError("Commerce OMS shipping address update blocked", {
+      code: error.code,
+      reason: shippingAddressReason,
+    });
+  }
+  if (
+    error.code === "23505" ||
+    /(?:commerce_oms_|commerce_order_).*(?:conflict|already|not_found|invalid_status)/.test(text)
+  ) {
+    return new CommerceOmsConflictError("Commerce OMS hold conflict", { code: error.code });
+  }
+  return new CommerceOmsPersistenceError("Commerce OMS RPC failed", { code: error.code });
+}
+
+function noteResponse(operation: OmsOperationRow, replayed: boolean): AdminCommerceOrderNoteResponse {
+  return {
+    contractVersion: COMMERCE_CONTRACT_VERSION,
+    operation: operationResponse(operation),
+    replayed,
+  };
+}
+
+function operationResponse(operation: OmsOperationRow): AdminCommerceOrderNoteResponse["operation"] {
+  return {
+    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,
+  };
+}
+
+function readShippingAddressReason(text: string): string | null {
+  if (text.includes("commerce_oms_delivery_contact_stale_revision")) return "delivery_contact_stale_revision";
+  if (text.includes("commerce_oms_delivery_contact_submission_started")) return "delivery_contact_submission_started";
+  if (text.includes("commerce_oms_shipping_address_missing_shipping_address")) return "missing_shipping_address";
+  if (text.includes("commerce_oms_shipping_address_locked_after_label")) return "address_locked_after_label";
+  if (text.includes("commerce_oms_shipping_address_idempotency_conflict")) return "idempotency_conflict";
+  return null;
+}