@openlup/platform 0.26.0 → 0.28.0

package/README.md

@@ -10,19 +10,31 @@ 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.26.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0260) 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 `20261025090100` for attributed
-dunning attempt replay. `openDunningCase` requires nullable
-`failedPaymentAttemptId`; pass the durable applied attempt through renewal failure
-propagation, including replay. Fresh missing attribution refuses; never substitute
-a current or prepared attempt. Read the migration notes for the new overloads
-and existing donor schema/backfill mapping. Native attempt-replay parity remains
-registered and these managed forwards authorize no host activation.
+For the prepared `0.28.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0280) before selecting optional services. Experimental
+account/support APIs use `./account-support` and the type-only
+`./account-support/contracts`; reference bindings remain inert and default-off.
+Apply the M12 support-authority forwards after complete same-rail predecessors
+and follow the email-correction admission, claim, identity-commit and settlement
+migration notes before replacing retired callers. 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 the M12 support-authority forward
+(`20261026120000_account_support_operator_authority.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 `20261026120100`, including
+the current support-authority forward and 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,
@@ -38,7 +50,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.25.0` tarball. Preparation and offline
+Size comparison uses the published `0.27.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).
@@ -81,13 +93,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.
@@ -101,7 +309,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).
 
@@ -188,7 +396,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.
@@ -828,3 +1044,103 @@ 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.
+
+## Account and support contracts
+
+Experimental `@openlup/platform/account-support` supplies `createAccountReadFacade`
+and the unchanged account-read diagnostic helpers. Inject account and order owner
+ports; delegation preserves their arguments, receivers, results, nulls and thrown
+failures. Authentication, authorization and private profile/market projection stay
+with the host. Importing this entry selects no driver or capability.
+
+`account-support/contracts` is type-only and browser-safe. It declares account,
+Customer 360, self-service command, operator recovery and invoice-access envelopes
+with explicit capability flags. These declarations do not install their services.
+The [account/support reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#account-and-support-contracts)
+owns the available boundary and later-phase limits.
+
+R2 adds `readAccountSnapshot` with the two-stage fan-out and a store-level recent
+20-order request, stored-money order history/detail, Customer 360 projections
+and M09 invoice history/PDF delegation. `createInvoiceAccess` checks the requested
+document against the owned account/order history before resolving its ticket or
+reading PDF bytes; foreign or unknown documents return `{ kind: "denied" }`. Select pricing, captured line
+presentation, private extensions and fulfillment evidence through typed host
+ports. Missing evidence stays unknown; owner refusals retain their distinctions.
+The default-off reference selections and host-fed read views are unmounted.
+Native Customer 360 uses the existing authorized PostgreSQL support reader;
+account/history/invoice drivers still require explicit host selection.
+Subscription pointer enrichment preserves optional nullable `paymentMethodKind`:
+selected-empty evidence is null, while unread evidence is omitted. Reference
+line presentation explicitly picks the declared display keys before projection.
+
+`createCustomer360ReadFacade({ authorize, journey, summary, diagnostics })`
+requires `authorize(): Promise<boolean>` before every method's source read.
+Refused callers receive `{ kind: "denied" }`; authorized delegates preserve
+arguments, results, nulls and thrown failures. The reference binding supplies
+that authorization once per call, before opening either support scope.
+
+The [account/support reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#account-and-support-contracts)
+owns the available R1 boundary and later-phase limits.
+
+
+R3 adds `createSelfServiceCommandFacade({ context, capabilities, ...lanes })`,
+returning `SelfServiceCommandFacade` with required host capabilities and every
+managedSubscription, nativeLegacySubscription, subscriptionControl, typed/raw,
+profile, paymentMethod, commerce and recovery output lane. Input lanes are optional.
+Unselected methods return `{ supported: false, refusalCode }`; paymentMethod uses
+the host paymentMethodSetup refusal by identity, commerce uses commerceRecovery,
+and other lanes use a frozen host_binding_required refusal. Every lane guards
+the principal; typed/raw lanes require a supplied clientId equal to context.clientId.
+The trailing `ControlSnapshot = unknown` generic retains the control snapshot type.
+Native legacy routing preserves
+explicit pause and ownership before bundle quote validation. Owner results,
+refusals and nulls retain identity. Supported paymentMethodSetup requires a
+paymentMethod lane; supported commerceRecovery/configuredPurchase require commerce.
+Supported genericBundleCommands/commandBoundReceipts require a selected subscription
+command lane. Missing required lanes refuse customer_self_service_lane_configuration_required.
+`encodeNativeSubscriptionCommand`, `decodeNativeSubscriptionPreview` and
+`createNativeSubscriptionDriver` retain the raw owner protocol and apply key;
+apply never previews. `createPaymentMethodComposition` adapts generic M07
+setupMethod to paymentMethod.execute without owner imports. Native repair is a
+[registered follow-up](../../docs/platform/plans/oss-m12-account-support.md#follow-up-register).
+The default-off reference binding mounts nothing; browser key retention and
+native profile/start remain unselected.
+
+
+R4 adds `createOperatorRecovery`, `createManagedOperatorAuthority`,
+`createPostgresOperatorAuthority`, `operatorAuthorityCapabilities`,
+`moveIdentityForEmailCorrection`, `executeOperatorAccountLink`, `linkThenApply`
+and `ACCOUNT_SUPPORT_MIGRATIONS`. The host injects its transaction/RPC and identity
+ports, verified human operator and recovery-path policy. Recovery token generation
+and SHA-256 hashing use the runtime Web Crypto API without a Node import; the
+host may still inject its opaque-token generator. Managed email admission
+and claim precede identity mutation and settlement. Native lifecycle commands
+delegate to M10, with actual optional owner receipts and named unavailable
+subcases. Link-then-action reports a completed link separately when the second
+command refuses or fails. The reference binding is default-off and unmounted;
+no import provisions authority or activates a route.
+
+R5a adds `createAccountSupportBindings` and `createAccountSupportServices` here,
+and `createAccountSupportContribution` in `/composition`. Supply already bound
+R1–R4/owner operations for one explicit managed/native graph, host capabilities
+and a readiness observer. Each distinct callable receives one guard shared by
+its service, port and route aliases; each entrance re-observes readiness. Disabled
+construction calls no observer. Refusals are `disabled`, `schema_unknown` and
+`schema_unsatisfied`; owner results and thrown failures pass through unchanged.
+A null selected operation remains a required port without an executable binding.
+The separate injected commerce record uses `commerce(key, ...args)` and returns
+`{ kind: "unsupported", code: "host_binding_required" }` for a null record/member.
+The reference host may select real M11 checkout/recovery, ATP and existing effect
+descriptors by supplying its already-built selection through `commerceOwner`
+and its existing registry through `commerceRegistry`. R5b does not construct M11
+or import its adapters; the host supplies the complete account/M11/ATP schema
+and matching enablement/readiness. Keep capability flags unsupported until
+their owner callables are bound. This adds no package export or owner import to
+account-support contracts. One M11 result is forwarded without rewrapping its
+guarded services; unknown stock, unsupported options and handler outcomes retain
+their owner meaning. Contribution descriptors install no routes, handlers,
+schedules or workers. See the
+[reference recipe](../../docs/platform/RUNTIME_AND_SELF_HOSTING.md#opt-in-disposable-subscription-reference)
+for the host's schema and transport obligations.

package/dist/account-support/accountReadFacade.d.ts

@@ -0,0 +1,8 @@
+import type { AccountReadPort } from "./contracts/index.js";
+/** Pure delegation to selected owner reads. Authorization, defaults, diagnostics,
+ * private fields and transport refusal mapping remain with the injected owners.
+ */
+export declare function createAccountReadFacade<Account, OrderList, OrderDetail>(ports: {
+    account: Pick<AccountReadPort<Account, OrderList, OrderDetail>, "getAccount">;
+    orders: Pick<AccountReadPort<Account, OrderList, OrderDetail>, "listOrders" | "getOrderDetail">;
+}): AccountReadPort<Account, OrderList, OrderDetail>;

package/dist/account-support/accountReadFacade.js

@@ -0,0 +1,10 @@
+/** Pure delegation to selected owner reads. Authorization, defaults, diagnostics,
+ * private fields and transport refusal mapping remain with the injected owners.
+ */
+export function createAccountReadFacade(ports) {
+    return {
+        getAccount(userId) { return ports.account.getAccount(userId); },
+        listOrders(userId, input) { return ports.orders.listOrders(userId, input); },
+        getOrderDetail(userId, orderId) { return ports.orders.getOrderDetail(userId, orderId); },
+    };
+}

package/dist/account-support/accountReadModels.d.ts

@@ -0,0 +1,69 @@
+import type { AccountActionRequired, AccountSnapshot, AccountSubscription, AccountSubscriptionLine, AccountOrderSummary } from "./contracts/account.js";
+import type { SubscriptionPaymentMethodStatus } from "./contracts/commands.js";
+export declare const CUSTOMER_ACCOUNT_V2_CONTRACT_VERSION: "customer.account.v3";
+type Row = Record<string, unknown>;
+export interface CustomerSubscriptionEligibilityInput {
+    subscriptionId: string;
+    status: AccountSubscription["status"];
+    nextCycleAt: string | null;
+    editCutoffAt: string | null;
+    paymentMethodKind: string | null;
+    paymentMethodRefPresent: boolean;
+    paymentMethodStatus?: SubscriptionPaymentMethodStatus;
+}
+export interface CustomerSubscriptionEligibility {
+    canEdit: boolean;
+    reason: AccountSubscription["editBlockedReason"];
+}
+export interface SubscriptionActionState {
+    subscriptionId: string;
+    orderId: string | null;
+    blockedReason: AccountActionRequired["blockedReason"];
+    failureCause: AccountActionRequired["failureCause"];
+    recoveryEligible: boolean;
+    dueAt: string | null;
+    nextRetryAt: string | null;
+}
+export interface AccountReadSources<Extension, ChargeEvidence = AccountSubscription["nextCharge"], PaymentEvidence = unknown> {
+    readExtension(clientId: string): Promise<Extension>;
+    /** The selected store applies the bound BEFORE visibility filtering. */
+    readSubscriptionRows(clientId: string, limit: number): Promise<Row[]>;
+    readAddresses(clientId: string): Promise<AccountSnapshot["addresses"]>;
+    readOrdererProfiles(clientId: string): Promise<AccountSnapshot["ordererProfiles"]>;
+    readPaymentPreferences(clientId: string): Promise<AccountSnapshot["paymentPreferences"]>;
+    readDeliveryPreferences(clientId: string): Promise<AccountSnapshot["deliveryPreferences"]>;
+    readOrders(clientId: string, limit: number): Promise<{
+        orders: AccountOrderSummary[];
+    }>;
+    readEvents(clientId: string): Promise<AccountSnapshot["events"]>;
+    readSubscriptionLines(ids: string[]): Promise<Map<string, AccountSubscriptionLine[]>>;
+    readSubscriptionBlockers(ids: string[], nextCycles: Map<string, string | null>): Promise<Map<string, NonNullable<AccountSubscription["editBlockedReason"]>>>;
+    readPauseWindows(ids: string[]): Promise<Map<string, Pick<AccountSubscription, "pausePreset" | "pauseStartedAt" | "pauseEndsAt">>>;
+    readPaymentEvidence(ids: string[]): Promise<Map<string, PaymentEvidence>>;
+    /** Owner interprets M08 refusal; unsupported MUST throw, never return an empty Map. */
+    readDeliveryAlignments(nextCycles: Map<string, string | null>): Promise<Map<string, {
+        state: "protected" | "aligned";
+    }>>;
+    readNextCharges(rows: Row[]): Promise<Map<string, ChargeEvidence>>;
+    readActionStates(ids: string[]): Promise<Map<string, SubscriptionActionState>>;
+}
+export interface AccountReadProjectionPolicy<ChargeEvidence = AccountSubscription["nextCharge"], PaymentEvidence = unknown> {
+    paymentMethodStatus(input: {
+        clientId: string;
+        clientEmail: string | null;
+        row: Row;
+        evidence: PaymentEvidence | undefined;
+    }): SubscriptionPaymentMethodStatus;
+    canUsePaymentMethodForRenewal(status: SubscriptionPaymentMethodStatus): boolean;
+    packageSummary(lines: AccountSubscriptionLine[], constraint: unknown): string | null;
+    /** Pricing authority selects payable-cycle/acquisition shipping precedence. */
+    withNextCharge(recurring: AccountSubscription["recurringPrice"], next: ChargeEvidence | undefined): Pick<AccountSubscription, "recurringPrice" | "nextCharge">;
+}
+/** Two observation stages, including the original nested subscription fan-out. Auth/ownership precedes this call. */
+export declare function readAccountSnapshot<Extension, ChargeEvidence, PaymentEvidence>(sources: AccountReadSources<Extension, ChargeEvidence, PaymentEvidence>, policy: AccountReadProjectionPolicy<ChargeEvidence, PaymentEvidence>, client: Row): Promise<AccountSnapshot<Extension>>;
+export declare function isCustomerVisibleSubscription(row: Row): boolean;
+export declare function recurringPrice(lines: AccountSubscriptionLine[]): AccountSubscription["recurringPrice"];
+export declare function editCutoff(nextCycleAt: string | null, editWindowHours: number | null): string | null;
+export declare function computeEditState(input: CustomerSubscriptionEligibilityInput, blockers: ReadonlyMap<string, NonNullable<AccountSubscription["editBlockedReason"]>>, canUse: AccountReadProjectionPolicy["canUsePaymentMethodForRenewal"]): CustomerSubscriptionEligibility;
+export declare function buildActionRequired(subscriptions: AccountSubscription[], orders: AccountOrderSummary[], states: Map<string, SubscriptionActionState> | undefined, canUse: AccountReadProjectionPolicy["canUsePaymentMethodForRenewal"]): AccountActionRequired[];
+export {};