@openlup/platform 0.25.0 → 0.27.0

package/README.md

@@ -10,14 +10,27 @@ Development preview. This package is part of the publishable set with core and o
 
 It holds the runnable server substrate an OpenLup application composes: the Node HTTP runtime, BFF dispatch, scheduling and job leases, blob storage, data gateways, the node-postgres migration runner and bundle composition. Ports and their contracts stay in `@openlup/core/platform-runtime`.
 
-For the prepared `0.25.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0250) before selecting optional services.
-Install the complete native chain through position 86, including N2 commands,
-N3 stock wait, the ATP seam/allocator and late-payment/retry-selection forwards;
-sparse SQL projections are not an install chain. Native runtime roles need the
-ATP/exposure EXECUTE and underlying SELECT grants described in the release notes.
-Managed hosts apply the complete prefix through `20261024185100` for stock-wait
-and refund-evidence functions. Preserve captured obligations and receipts on rollback.
+For the prepared `0.27.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0270) before selecting optional services. Experimental
+commerce schemas and ports use `./commerce` and `./commerce/contracts`;
+handlers, adapters and checkout engines use the Node-only `./commerce/server`.
+The commerce contribution and reference binding remain inert and default-off.
+Install the complete native chain through position 86
+(`20261024184600_subscription_retry_candidate_payment_filter.sql`); M11 adds no
+native SQL. Sparse SQL projections are not an install chain. Native runtime
+roles need the ATP/exposure EXECUTE and underlying SELECT grants described in
+the release notes.
+Managed hosts apply the complete prefix through `20261025110000`, including
+M11's nine forwards for preference/return ownership, operator receipts,
+acquisition/finalize admission, ATP preview and starter graduation. Legacy
+omitted-country input uses the configured settlement region; neutral commands
+require explicit country. Starter graduation admits 14, 21 or 28 days; rollback
+below that forward with a 21-day marker is unsupported, so roll forward.
+The service-only ATP preview uses owner privileges and a fixed search path.
+Retain exact applied failure-attempt attribution for the existing managed
+dunning overloads; native attempt-replay parity remains registered. These
+managed forwards authorize no host activation.
+Preserve captured obligations and receipts on rollback.
 M10 subscription services and contributions remain **EXPERIMENTAL and DEFAULT-OFF**.
 Hosts explicitly supply readiness, execution, commands, mandatory G23 admission,
 a population lease and M04 delivery. Factories activate no serving work. The inert
@@ -32,7 +45,7 @@ Adopters must not activate unselected or unready invoicing; installation and
 inert contributions register no runner, worker, route or schedule.
 M06 managed-host proof classes remain pending in the
 [M06 parity ledger](../../docs/platform/plans/oss-m06-stock-reservations-delivery.md#parity-pending-rows).
-Size comparison uses the published `0.24.0` tarball. Preparation and offline
+Size comparison uses the published `0.26.0` tarball. Preparation and offline
 adapter evidence grant no publication or provider-account certification.
 
 Longer module recipes live in the [platform package reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md).
@@ -75,13 +88,209 @@ timestamp used in the webhook's idempotency key.
 | `./inventory` | Experimental schemas/ports, handlers, native stores, projection, injected forecast and SQL descriptor; `./inventory/contracts` DTOs. |
 | `./catalog` | Experimental neutral catalog schemas, drafts, reads, media source packs and publication ports |
 | `./catalog/contracts` | Dependency-free catalog DTOs, media resolver, authority and canonicalization helpers |
+| `./commerce`, `./commerce/contracts` | Browser-safe neutral commerce schema cores, generic ports and pure contract helpers |
+| `./commerce/server` | Node-only OMS, returns, native reviews/media and hosted-feedback handlers/adapters and order-detail composition, email consumers, dispatch registry, paid-fulfillment binding and checkout compensation, checkout handlers, runtime and shared paid-order saga |
 | `./pricing` | Experimental price authority, quote computation/handlers, offer projection/cache, readiness and policy tokens |
+| `./pricing/browser` | Existing quote primitives, acquisition validators and shipping-terms validator, browser-safe |
 | `./pricing/contracts` | Dependency-free authority, money, quote and offer DTOs and version constants |
 | `./promotions` | Experimental promotion application, admin handlers, native read/sweep, SQL projections and acceptance |
 | `./promotions/contracts` | Dependency-free preview and admin DTOs |
 | `./shipping` | Experimental delivery ports, injected-schema handlers, summary/evidence; native flat-rate port + Core schema readiness |
 | `./shipping/contracts` | Type-only delivery, pickup-point, summary and evidence DTOs |
 
+## Commerce contracts
+
+`./composition` exports the inert `createCommerceContribution` for the installed
+commerce entries and selected callables. Duplicate descriptor identities refuse;
+the [composition recipe](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#contributions-seams-and-readiness)
+and [reference binding](../../docs/platform/RUNTIME_AND_SELF_HOSTING.md#opt-in-disposable-subscription-reference)
+describe host readiness, one executor per operation and native recovery limits.
+
+`./commerce` stays browser-safe. `./commerce/server` is the separate Node-only
+entry for checkout engines, handlers, stores and adapters. It exports
+`tryCompensate` and `CheckoutCompensationPort`: release the selected order's
+reservations, attempt unstarted-promotion cancellation, then cancel the abandoned
+order only when promotion cleanup did not succeed. Existing keys, reasons,
+warning messages and swallowed cleanup failures are preserved. The reference
+facade delegates to the same function; composition still owns the cleanup ports.
+The package boundary test bundles the browser entry without Node built-ins or
+the server subtree, and the cold consumer exercises installed compensation.
+Starter declaration types are inferred from the `createStarterOfferGuard`
+binding signature; the declaration interface stays internal to the engine.
+
+The Node-only entry owns the checkout admission/quote/resume/failure sequence,
+neutral command adapter, runtime and one paid-order saga. Composition injects
+HTTP schemas/responder, quote and persistence ports, subject/metadata projections
+and the existing prepared-payment execution callables. Provider roles, flow
+selection and trusted provider-evidence classification are reference inputs.
+Saved-method alias and recurring-mode strings are host-defined generics passed
+unchanged through resolver, saga and runtime; the evidence schema owns its internal JSON-length bound. The reference retains
+locale, fiscal, profile, starter-policy, request observation and status-link
+bindings. Acquisition expectations and accepted shipping terms require quote
+acceptance; offer asks require a bound policy. A matching owned saved epoch can
+resume; edited or incomplete state re-quotes. Stock refusal compensates only a
+proved pre-dispatch draft; scoped contention and uncertain dispatch carry no
+cleanup capability. A synchronous decline stays failed and is never auto-settled.
+Neutral finalize and one-time reservation conformance tests use recording ports;
+atomic acquisition/finalize SQL still requires integration with its migration chain.
+
+The server entry also owns generic order-draft, runtime-finalize, intent-persistence
+and resume stores, cancellation adapters and reservation sweeps. Structural clients
+retain the incumbent RPC/table calls; composition supplies frozen snapshot schemas,
+ordered finalize arguments, response decoders and fail-open phone normalization.
+Use `createCommerceOrderDraftRpcPort`, `createCheckoutCompensationRpcAdapter`,
+`createCommerceCheckoutResumeQueryPort` and `createConfiguratorIntentPersistenceRpcPort`
+with structural clients, including `ConfiguratorIntentRpcQueryClient` for intent
+persistence. Reference bindings retain their incumbent exported factory names.
+Verified identity overwrites submitted identity after normalization. Draft retries
+supersede only once after an idempotency conflict; catalog refusals do not supersede.
+Recovery classifiers inject subject admission, compare shipping terms as well as
+money, and separate continuation, expiry policy and refused token states. Application
+recovery projection, routes and destinations stay in the host. SQL atomicity and
+active-subscription guards require real PostgreSQL integration; the C2 handoff
+release check is **to be released**.
+
+`./commerce/contracts` is a type-only, browser-safe entry for commerce-owned
+records and generic persistence, checkout/runtime, availability, recovery and
+offer-policy ports. It imports no pricing module. Consume pricing DTOs from
+`./pricing/contracts` directly. Commerce does not re-export pricing DTOs; its runtime
+reuses the version constant through `./pricing/contracts`. Quote ports take the
+host request, response and existing options as type parameters; the reference
+binds the existing pricing definitions, adding only the server-bound offer.
+
+`./commerce/server` supplies the Node-only OMS handlers, managed adapters and
+order-detail composition.
+`./commerce` remains browser-safe, including its full runtime import closure.
+It also owns canonical order-money validation and commerce event payload schemas.
+The latter reuse the core outbox envelope and inject host quote/draft validators,
+without importing an outbox worker or storage implementation.
+The same entry owns `deriveOfferAvailability`, `defaultOfferAvailability`,
+`availabilityBySku`, `statusForSellableNow`, `reasonCodeFor` and the low-stock
+threshold. Their reference facades preserve function identity. The server entry's
+`createOfferAvailabilityPort` runs the existing physical-table projection over
+an `OfferAvailabilityQueryClient` and an injected `isStockProvider` predicate.
+It preserves active-hold subtraction, lot/location eligibility and provider
+missing/stale refusals. SDK narrowing and provider selection stay host-owned.
+M06 owns normalized new-purchase reads and reservation TTL policy; the reference
+composition passes its selected read port through unchanged. With `dataKind: "postgres"`,
+the host supplies `stockSourceKey` to bind the native ATP reader; omission reports
+`inventory_stock_source_key_required`. Managed composition prefers an injected
+reader, then binds `stockRpc` over `inventory_new_purchase_stock_read`; without
+either it reports `inventory_new_purchase_stock_reader_required`.
+W2 conformance distinguishes reads, fallback and one-time allocation; real SQL
+atomicity and consumption remain integration obligations.
+
+`./commerce` provides neutral cart/order/read, checkout, intent, persistence,
+resume and customer-default schema cores and factories. Bind existing pricing
+schemas and explicit host vocabulary, then extend the object cores with local
+locale, profile, sizing, fiscal and provider policy. The reference retains those
+extensions; it does not publish that policy into the package.
+The intent factory accepts a SKU schema with string input and output, preserving
+string SKU inputs when hosts infer request types. Resume and availability bindings
+also preserve string SKU and product-slug inputs. When composing host fields,
+retain their legacy positions: object key order also determines validation issue
+order, including nested variants and checkout requests.
+Offer tokens are opaque; `minimumUnits` is an untrusted ask with an injected default, never an
+admission grant. The server entry executes the offer binding and bounds its server-minted evidence.
+The starter guard receives terms, basket/discount functions and its plan schema
+from the host. These entries install no store, route,
+migration or provider.
+
+Required root discovery includes `test/commerce/`: schema refusal/replay and
+port-fit tests join recovery/error/helper witnesses, compensation and neutral W4 composition.
+The unchanged reference suites and a pre-extraction parse transcript protect
+host bindings. The cold consumer imports both installed entries and checks
+availability projection/refusal, opaque offers, injected minimums and snapshot
+refusal without optional peers. This establishes contract proof only.
+
+OMS schemas and pure operational builders export from browser-safe `./commerce`.
+Order-money derivation and paid-event constants reuse the existing commerce
+owners. `OmsOrderPaymentStatus` binds the existing generic
+`OmsPaymentStatus<PaymentIntentStatus>` to the core payment states; the generic
+K1 contract remains available unchanged.
+Node-only `./commerce/server` owns the generic handlers, managed RPC/query store
+and detail composition that uses the shipping runtime. DTOs and structural ports
+remain in the type-only contracts entry. Inject settlement,
+identity/presentation and provider read projections at composition. The managed
+client requires only `rpc`; table reads and note persistence receive a separate
+query capability, including the `is(column, value)` filter required by hydration.
+Unprojected timeline labels use canonical step keys; hosts supply localized copy
+through `timelineLabel`. Refund marking remains an operator mark. Replacement creation
+uses the existing fulfillment handler and never confirms arrival or interrupts
+an active subscription. W5/W6 tests pin replay tuples and forbidden effects.
+
+Returns expose request, approve and reject only: `CommerceReturnsPort` and
+its schemas are at `./commerce`; the three handler factories and
+`createSupabaseCommerceReturnsPort` are at `./commerce/server`. `restockDisposition`, `refundMode` and
+`refundAmountCents` record intent. Receive, restock and refund execution do not
+exist. The host supplies authorization and a `BffResponder`; the request adapter
+forwards the authenticated principal as `p_requested_by` to the database's owner,
+idempotency-key and fingerprint checks.
+The package request schema defaults to neutral reason codes. Bind a host set with
+`createCommerceReturnsSchemas(reasonCodes)` and supply its request schema to the
+customer handler's `requestSchema` dependency; the reference binding retains its
+legacy set and unchanged request/refusal envelopes.
+
+Native order-review contracts and the type-only `OrderReviewLifecyclePort` stay
+at `./commerce`. Customer/admin handler factories, PostgreSQL lifecycle/media
+adapters and raw uploads are exported from `./commerce/server`. Strict schemas keep
+pending declarations distinct from stored/confirmed observed media and keep
+storage locators out of public results. The raw upload handler accepts an
+`OrderReviewRawUploadBinding`; metadata finalization holds its transaction across
+the host's promotion callback. The reference host retains its private filesystem
+object store, lease composition and reconciliation. M02 `BlobStoragePort` is not a
+drop-in binding: it has no private read, inspection, temporary write or promotion
+operations. K3b preserves that host seam and adds no M02 storage bridge.
+
+Hosted feedback has its own contracts at `./commerce` and injected Supabase
+submit/token-check ports at `./commerce/server`. This tokenized public post-delivery lifecycle is distinct from native order
+reviews. It requires the adopter's database to provide `submit_order_feedback`
+and `check_order_feedback_token`; native `db/platform` supplies neither RPC.
+These ports add no route or native binding. Review-delay policy remains host-owned
+SQL (class (b) retention): native uses 14 days and the contributed managed profile
+uses 21 days. There is no TypeScript delay parameter or SQL change.
+The reference browser contract facades initialize their shared Zod instance in
+jitless mode before loading package schemas, preserving CSP-safe construction.
+The package contracts add no global Zod configuration side effect. Browser
+conformance bundles the complete commerce entry and both reference facades
+without externals; the raw-upload source is a failing browser control, while
+the complete server entry bundles for Node.
+
+Neutral producer event contracts are exported from `./commerce`;
+`createCommerceOutboxEventSchemas` binds the host's exact quote/draft snapshots.
+Event-type literals and host payload behavior are preserved.
+
+## Commerce domain effects
+
+The experimental Node-only `./commerce/server` entry provides the transactional email
+consumer factories, their descriptors and dispatch registry. Compose explicit
+`uniqueRegistry` composition from `@openlup/outbox` and
+`CommerceEmailRuntime` bindings for the fulfillment payload parser, communications
+transactional scaffold and send-outcome mapping, plus locale, money, generic
+line labels, paid-order presentation and tracking/notification policy. The
+package selects no provider, country, commercial offer or environment policy.
+Neutral email ports take the host locale as a type parameter and carry `contextName` and
+`messageId`; the reference maps its existing extension/provider field names.
+
+Draft, paid-email and paid-fulfillment consumers register by separate flags.
+Fulfillment reuses M08's existing handoff and risk seam. This registry adds no
+emitter, dispatcher, invoice executor, schedule, migration or subscription
+mutation. Cancellation email stays unregistered; `extraHandlers` can bind the
+independent accounting consumer. The refund consumer trusts amounts only with
+`provider-refund.v2` evidence. Return approved/rejected are separate notices.
+The live channel-comms policy suppresses the same buyer-facing handlers at
+handle time, settling them as processed with `channel_owns_buyer_comms`.
+
+The browser-safe `./commerce` entry provides event contracts, email DTOs and pure
+projections; it never imports `./commerce/server`.
+`projectCommerceSalesChannelEnvelope` retains opaque source identity without
+normalization. `CommerceChannelExposureReadPort` is only a host-injected read;
+no inventory exposure SQL or default implementation is supplied. Producer event
+schemas bind exact host quote/draft snapshots through a factory; email consumers
+retain frozen minimal subsets for in-flight compatibility. W8/W9 package
+conformance and the rebound reference suites cover this boundary. UI extraction
+and any artifact-cap change require their own approved scope.
+
 ## Shipping
 
 Shipping handlers require injected host schemas; contracts are type-only with opaque provider/carrier strings.
@@ -95,7 +304,7 @@ caller-declared schema requirements. Missing proof keeps the named refusal.
 
 ## Inventory
 
-`createInventoryBindings` selects one store with exact host provider validation. Native new-purchase reads refuse as `inventory_native_new_purchase_stock_read_unsupported`; `createInventoryContribution` declares selected callables without activation.
+`createInventoryBindings` selects one store with exact host provider validation. With `dataKind: "postgres"`, supply `stockSourceKey` to bind the existing native ATP new-purchase reader; without it, `unsupported.newPurchaseStockRead` reports `inventory_stock_source_key_required`. Admin reads remain ready. Preview availability subtracts all live holds, remaining subscription demand inside 14 days and channel exposure, clamped at zero. The native reader refuses a different horizon or an own-order exclusion as `native_stock_read_options_unsupported`. For managed reads, an injected reader wins; otherwise supply `stockRpc` to bind `createManagedStockAvailability` with the managed forward `20261025109000_inventory_new_purchase_stock_read.sql`. Without either dependency, the reason remains `inventory_new_purchase_stock_reader_required`. Managed previews retain provider-tagged ATP accounting and refuse other horizons or exclusions as `managed_stock_read_options_unsupported`. The managed SQL reader refuses a NULL as-of timestamp as `inventory_stock_as_of_invalid` (SQLSTATE `22023`). Their conservative stale flag is true if any provider row for the SKU is stale; ATP quantities and allocator freshness checks are unchanged. `createInventoryContribution` declares selected callables without activation.
 
 `INVENTORY_MIGRATIONS` projects canonical units 27/33 byte-for-byte; install the full catalogue. Store support and pending proof: [M06 parity](../../docs/platform/plans/oss-m06-stock-reservations-delivery.md#parity-pending-rows).
 
@@ -182,7 +391,15 @@ base reads using the selected list ID, with base-refusal precedence.
 
 `./pricing/contracts` contains dependency-free authority observations, policy
 DTOs and version constants; its only external type comes from the exact
-`@openlup/core/pricing` entry. Zod schemas, Web Crypto hashing and Node HMAC token
+`@openlup/core/pricing` entry. `./pricing/browser` directly re-exports exactly
+`createCommerceQuotePrimitives`, `acquisitionCapabilitySchema` and
+`acquisitionTermsExpectationSchema`, `resolvedAcquisitionTermsSchema` and
+`shippingTermsSchema`. Acquisition schemas come from their defining file; shipping
+re-exports its pure validator owner through an exact linted edge, preserving identity
+without handlers or Node HTTP declarations. The reference
+quote context admits both terms as optional fields and retains its existing strict
+fields and refusals. The complete browser bundle contains no Node imports or
+pricing server root. Other schemas, Web Crypto hashing and Node HMAC token
 operations stay in the server entry. Tokens retain assignment binding, the
 72-hour default compatibility window and rollback behavior. Secret selection,
 feature flags and readiness remain reference composition responsibilities.
@@ -822,3 +1039,5 @@ transport or query projection is host-owned. No executor is installed.
 store seller binding and managed wrappers persist its first-ever claim revision;
 legacy fallback and forward-only migration limits are owned by the
 [M09 migration section](../../docs/platform/DATA_AND_MIGRATIONS.md#m09-invoicing-forward-design-and-control-approval).
+
+OMS read projections are optional. Omitting the host health classifier preserves the original unprojected empty health snapshot (`ok`, no reasons or evidence IDs); it does not evaluate provider health. The reference composition injects its existing classifier and evidence readers.

package/dist/commerce/adapters/managed/commerceOmsControlPlane.d.ts

@@ -0,0 +1,3 @@
+import { type CommerceOmsControlPlanePort } from "../../oms/omsControlPlane.js";
+import type { CommerceOmsReadPort } from "../../oms/omsPorts.js";
+export declare function createManagedCommerceOmsControlPlanePort(managedPort: CommerceOmsReadPort): CommerceOmsControlPlanePort;

package/dist/commerce/adapters/managed/commerceOmsControlPlane.js

@@ -0,0 +1,71 @@
+import { OMS_CONTROL_PLANE_VERSION, omsControlPlaneActions, omsControlPlaneDetailResponseSchema, omsControlPlaneListResponseSchema, } from "../../oms/omsControlPlane.js";
+export function createManagedCommerceOmsControlPlanePort(managedPort) {
+    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) => {
+                if (type === "hold_created" || type === "hold_released")
+                    return type;
+                if (type === "order_cancelled_manual")
+                    return "order_cancelled";
+                if (type === "order_marked_refunded")
+                    return "order_refunded";
+                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) {
+    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/dist/commerce/adapters/managed/commerceOmsMutations.d.ts

@@ -0,0 +1,10 @@
+import type { AdminCommerceOrderNoteRequest, AdminCommerceOrderNoteResponse, AdminCommerceOrderUpdateShippingAddressRequest, AdminCommerceOrderUpdateShippingAddressResponse } from "../../oms/omsContracts.js";
+import type { CommerceOmsRpcClient, CommerceOmsStore, RpcError } from "./oms/types.js";
+export declare function addCommerceOmsNote(client: CommerceOmsStore, request: AdminCommerceOrderNoteRequest & {
+    actorUserId: string;
+}): Promise<AdminCommerceOrderNoteResponse>;
+export declare function updateCommerceOmsShippingAddress(client: CommerceOmsRpcClient, request: AdminCommerceOrderUpdateShippingAddressRequest & {
+    actorUserId: string;
+}): Promise<AdminCommerceOrderUpdateShippingAddressResponse>;
+export declare function callOmsRpc<T>(client: CommerceOmsRpcClient, functionName: string, args: Record<string, unknown>): Promise<T>;
+export declare function mapRpcError(error: RpcError): Error;

package/dist/commerce/adapters/managed/commerceOmsMutations.js

@@ -0,0 +1,119 @@
+import { COMMERCE_CONTRACT_VERSION } from "../../../pricing/contracts/index.js";
+import { CommerceOmsConflictError, CommerceOmsPersistenceError, } from "../../oms/omsPorts.js";
+const OPERATION_COLUMNS = "id, order_id, operation_type, hold_id, actor_user_id, occurred_at, payload";
+export async function addCommerceOmsNote(client, request) {
+    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, true);
+        }
+        throw mapRpcError(insertResult.error);
+    }
+    return noteResponse(insertResult.data, false);
+}
+export async function updateCommerceOmsShippingAddress(client, request) {
+    return callOmsRpc(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(client, functionName, args) {
+    const { data, error } = await client.rpc(functionName, args);
+    if (error)
+        throw mapRpcError(error);
+    return data;
+}
+/**
+ * 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) {
+    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, replayed) {
+    return {
+        contractVersion: COMMERCE_CONTRACT_VERSION,
+        operation: operationResponse(operation),
+        replayed,
+    };
+}
+function operationResponse(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) {
+    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;
+}

package/dist/commerce/adapters/managed/commerceOmsPort.d.ts

@@ -0,0 +1,28 @@
+import type { OmsActionAvailabilityFlags } from "../../model/omsReadModelHelpers.js";
+import { type CommerceOmsHoldPort, type CommerceOmsReadPort } from "../../oms/omsPorts.js";
+import type { OmsManagedReadProjections } from "./oms/readProjections.js";
+import type { CommerceOmsRpcClient, CommerceOmsStore, RpcError } from "./oms/types.js";
+export type { CommerceOmsRpcClient } from "./oms/types.js";
+export declare function createManagedCommerceOmsPort(client: CommerceOmsRpcClient, options?: {
+    actionFlags?: OmsActionAvailabilityFlags;
+    queries?: Pick<CommerceOmsStore, "query">;
+    projections?: OmsManagedReadProjections;
+}): CommerceOmsReadPort & CommerceOmsHoldPort;
+/**
+ * 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 declare function mapReplacementRefusal(error: RpcError): Error;

package/dist/commerce/adapters/managed/commerceOmsPort.js

@@ -0,0 +1,101 @@
+import { CommerceOmsConflictError, CommerceOmsPersistenceError, readOmsReplacementRefusal, } from "../../oms/omsPorts.js";
+import { addCommerceOmsNote, callOmsRpc, updateCommerceOmsShippingAddress, } from "./commerceOmsMutations.js";
+import { getCommerceOmsOrderDetail, listCommerceOmsOrders, } from "./oms/readQueries.js";
+export function createManagedCommerceOmsPort(client, options = {}) {
+    function readStore() {
+        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) {
+            return listCommerceOmsOrders(readStore(), request, options);
+        },
+        getOrderDetail(request) {
+            return getCommerceOmsOrderDetail(readStore(), request, options);
+        },
+        async createHold(request) {
+            return callOmsRpc(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) {
+            return callOmsRpc(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) {
+            return addCommerceOmsNote(readStore(), request);
+        },
+        updateShippingAddress(request) {
+            return updateCommerceOmsShippingAddress(client, request);
+        },
+        async markRefunded(request) {
+            return callOmsRpc(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) {
+            // 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;
+        },
+        async cancelOrder(request) {
+            return callOmsRpc(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) {
+    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/dist/commerce/adapters/managed/oms/accounting.d.ts

@@ -0,0 +1,3 @@
+import type { OmsAccountingInvoiceRow, OmsAccountingOutboxRow } from "../../../model/omsReadModel.js";
+import type { CommerceOmsStore } from "./types.js";
+export declare function readAccountingOutbox(client: CommerceOmsStore, invoices: OmsAccountingInvoiceRow[]): Promise<OmsAccountingOutboxRow[]>;

package/dist/commerce/adapters/managed/oms/accounting.js

@@ -0,0 +1,13 @@
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+export async function readAccountingOutbox(client, invoices) {
+    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 ?? []);
+}