@openlup/platform 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -8,6 +8,149 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [0.19.0]
+
+- Publishable on the npm `latest` dist-tag as `0.19.0`, from tag
+  `openlup-platform-v0.19.0`.
+
+### 0.18.0 → 0.19.0 set scope
+
+- Prepare the complete development-preview minor set at `0.19.0`, including everything on main since `0.18.0`; core and outbox are unchanged republications, and UI stays private `0.0.0`.
+- M05 parity adds opt-in shipping-promise consent, post-discount threshold shipping and acquisition orchestration to the experimental pricing, promotions and shipping entries; financial policy and acquisition capability remain host supplied.
+- M05 parity adds effective native bundle selection and an authoritative preview hook, optional resolved-target/detail/feed context fields and `selectEffectiveBundleTargetPrice`; effective feeds require unambiguous gross unit anchors and whole-BOM readiness.
+- Add `createConcurrentCommercePriceAuthorityPort` with concurrent history scheduling, selected-list identity and base-refusal precedence; browser additions are type-only.
+- Catalog/contracts draft canonical JSON detects lone surrogates without regex lookbehind so it loads in Safari before 16.4, with unchanged behavior.
+- M06 P5a adds explicit inventory store/provider bindings and structural inventory contribution, keeping reference catalog-stock composition inert and managed authorization intact; native new-purchase stock reads remain unsupported pending an owner decision and native adjustment still refuses.
+- M06 P5a retains focused installed-consumer, runtime-role, managed FEFO/adjustment and consume/refund replay evidence with unproved parity gates retained in the M06 ledger.
+- M06 P5b adds opt-in shipping selection, address and flat-rate bindings with injected validation and authority; native address writes remain unsupported and refuse required readiness.
+- M06 P5b adds the final isolated installed inventory/shipping consumer, preserving incumbent selection errors and flat-rate behavior.
+- M06 in progress: inventory and shipping entries are early surfaces; module not complete
+- Supporting main changes sort platform registration lists one item per line and use the database clock in the M05 P7 quote witness; neither adds runtime behavior.
+
+Migration: upgrade the complete `@openlup/*` set from `0.18.0` to `0.19.0` for exact internal pins; existing bindings need no change and new module adoption remains explicit and experimental. Hosts selecting shipping promises must forward `shippingTerms` through both acceptance callbacks and use a context schema that preserves the selected terms. Bind `resolveQuoteShippingPromotions` to the promotions factory to select the bounded two-pass threshold path; financial policy and acquisition capability remain host supplied. The additive APIs require a minor set and introduce no activation. For both M05 24b and M06 P5b, the pricing and promotions API reports reorder existing enum/union members because declaration emit order changed (24b follows the catalog-to-pricing import); no member is added, removed or changed and callers need no migration for that reorder. Install the complete canonical migration catalogue, never sparse package projections as an installation chain; this preparation adds no SQL migration.
+
+### Known limitations
+
+- D8-1: native advisory v2 promo-code candidates and rejection details are not supported on the native backend.
+- D8-2: native mounted v2 code issue/honor/fallback is not supported on the native backend.
+- D8-3: acquisition-only mounted issuance/honor is not supported on the native backend.
+- D8-4: full native/managed eligibility equivalence is not supported on the native backend.
+- Bundle-1: independent database human-only actor-kind enforcement is not supported on the native backend and is the first item of a future native-backend parity round.
+- Bundle-2: managed-equivalent actor-kind/email history is not supported on the native backend.
+- Bundle-3 remains closed for M05 mounted admin/feed readback with an injected stock reader, while native new-purchase stock reads remain unsupported despite P5a's installed native inventory-store read proof.
+- Bundle-4 establishes only incumbent real-PostgreSQL contention characterization and provides no exactly-once guarantee.
+- The managed baseline schema and its pgTAP tests retain the incumbent legacy value `44.404`; removing it needs a forward migration and an owner decision, while reference composition supplies that value to application code.
+- A1 evidence is offline only: account verification, hosted-time behaviour and owner TEST certification are not claimed, and the `communications/klaviyo` adapter's capabilities stay verification-pending.
+- M05 parity seams are opt-in and omitted bindings preserve incumbent defaults, outputs, read order, scheduling, refusals, acceptance-token bytes and exported SQL.
+- Native inventory adjustment remains unsupported; native address writes and flat-rate saves refuse required-capability readiness.
+- M06 managed host ATP/forecast/supply/pagination, remaining compensation/concurrency/lock-order, exact-prefix upgrade/ledger, address idempotency/conflict/readback and runtime rate authority remain pending in the M06 ledger.
+- M06 adopter stock-wait lifecycle, durable subscription timing and staging control observations retain their separate C5/C6 evidence gates.
+
+### Size note
+
+Only platform `pack.docs.maxPackedBytes` rises from 40,960 to 49,152 B; all other caps and budgets remain unchanged. All three baselines use integrity-verified published `0.18.0` tarballs.
+
+Question (2026-10-21): "The platform package's root docs (README + CHANGELOG) will exceed their 40,960 B gzip cap at the next release. What should we do?"
+Owner's answer: "Raise to 49,152 B (Recommended)"
+Option description shown to the owner: "Same figure as core. Unblocks the next few releases; the CHANGELOG grows every release, so this cap would otherwise block each one."
+Recorded as an owner decision taken through the coordinator's question on 2026-10-21.
+
+## [0.18.0]
+
+- Publishable on the npm `latest` dist-tag as `0.18.0`, from tag
+  `openlup-platform-v0.18.0`.
+
+- M06 P4: retain named compatibility shims, restrict inventory smoke evidence to package-owned tests, neutralize synthetic transport fixtures and clarify inventory documentation; no runtime or API change.
+
+### 0.17.0 → 0.18.0 set scope
+
+- Prepare the complete development-preview set at `0.18.0`: core and outbox are
+  unchanged republications; platform includes every change on main in this set.
+- M05 adds catalog foundation/contracts, draft validation, product/lifecycle DTOs,
+  authority/GTIN/quantity helpers, media and source-pack operations,
+  fixed-bundle read/admin/feed logic, native envelope/draft stores and an inert
+  catalog contribution; pricing adds the neutral quote foundation, authority,
+  subscription policy and assignment token, quote/offer projection, opt-in
+  acquisition terms and promise consent; promotions includes advisory, preview, acceptance,
+  admin/native reads and sweep with explicit host bindings; lifecycle/publication
+  contracts alone do not provide a publisher or native lifecycle writes.
+- M05 P6: pricing and bundle comments are corrected, VAT arithmetic delegates to the
+  existing helper and moved test fixtures are neutral with assertions unchanged;
+  no API change.
+- Reference-application source: opt-in catalog, product, basket, builder and admin UI consumes explicit
+  data/locale/media/lifecycle inputs; basket edits invalidate promise consent and
+  minor-money display uses the currency exponent.
+- Shipped catalog SQL projects unchanged canonical positions 1/8/16/19/58/59/61,
+  promotions projects 47/48 and inventory projects 27/33; native catalog factories
+  retain the existing store bodies and references preserve their named exports.
+- A1 adds 17 neutral marketing/consent declarations, the three-function `communications/resend`
+  entry, the `communications/klaviyo` marketing adapter and lazy opt-in reference bindings with
+  invocation-time admission; default routes, schedules and handlers stay empty.
+  Existing providers remain assignable; existing neutral entries keep their runtime
+  behaviour (the declarations above are additive), and the maintained reference
+  adapter and default wiring are unchanged.
+  Authenticated raw webhooks and GET-only delivery reconciliation retain host
+  ownership of persistence and admission; no SDK or default sender is added.
+  `communications/klaviyo` profile projection, negative consent readback,
+  account-wide deletion acknowledgement and authoritative consent push stay
+  verification-pending until the host supplies owner TEST verification.
+  Audience-scoped deletion and deletion status are unsupported; newsletter sync
+  refuses. No flow control, historical import, suppression edits or automatic
+  mutation retry is added.
+- Consent push grants stay audience-scoped; only withdrawals may be account-wide.
+  The capability declares `grantEffect`; accepted/acknowledged results require
+  `reconcileRequired`. Conformance keeps grants unsettled until settlement and
+  fresh readback. Withdrawals bypass grant-caused fences/quarantine but retain
+  same-key withdrawal fences and account cooling. No push factory, activation,
+  callback, retry or subpath is added.
+- M06 in progress: inventory and shipping entries are early surfaces; module not complete
+- The merged M06 surfaces include inventory contracts/admin/native reads, injected
+  new-purchase availability, reservation policy/maintenance and dated forecast
+  calculation with required provider injection, plus shipping selection, address
+  and rate handlers with required host validation.
+- @openlup/platform size growth: added M05 catalog, pricing and promotions implementations, native stores and SQL projections, A1 communications adapters and consent contracts, and the merged early M06 inventory/shipping surfaces with their declarations and documentation.
+
+Migration: upgrade the entire `@openlup/*` set from `0.17.0` to `0.18.0` for exact
+core peer pins; new module adoption remains explicit and experimental.
+Catalog and promotions server entries are adapters: their declarations require
+selected optional `pg` peers, while runtime imports and injected executors work
+without them and their contracts entries remain non-adapters. Supply host schemas, authorization,
+responders and policies through the documented bindings. Acquisition requires
+an explicit `AcquisitionFinancialPolicy` with no default; absence refuses with
+`acquisition_terms_policy_unconfigured`, and reference activation remains off.
+Bind resolved terms from the final optional issue/honor callback argument for
+acquisition-aware acceptance; existing callbacks remain assignable. Stop
+assigning `NegativeFeedback.kind` or `.outcome`, now readonly. Reference-application
+source threshold classifiers require the host's explicit threshold. Generated enum declaration
+ordering changes preserve member values and runtime behavior. Catalog adds
+`createPostgresBundleCatalogStore`, `createPostgresCatalogDraftStore` and
+`createPostgresCatalogSkuEnvelopeReadPort`, plus `BUNDLE_MIGRATIONS` (16/19) and
+`CATALOG_MIGRATIONS` (1/8/58/59/61); composition adds
+`createCatalogContribution` and `CatalogContributionInput`, with no public export
+removed or renamed. Existing named reference imports remain compatibility paths.
+The native writer, pooled transaction binding and transport remain reference-owned;
+browser schemas stay local. Core remains the promotions evaluator; no claim writer
+is added, and claim writing and mounted acceptance retain their owners. Reference
+shipping selection, pickup and stock UI mechanics and browser validation stay local.
+Install the complete canonical migration manifest, never sparse package SQL
+projections as an installation chain; this preparation adds no new SQL migration.
+A1 hosts retain credentials, identity/authority, atomic storage, environment,
+egress and schedule ownership; acknowledged/accepted does not establish remote
+effect and local consent remains authoritative.
+
+### Known limitations
+
+- D8-1: native advisory v2 promo-code candidates and rejection details are not supported on the native backend.
+- D8-2: native mounted v2 code issue/honor/fallback is not supported on the native backend.
+- D8-3: acquisition-only mounted issuance/honor is not supported on the native backend.
+- D8-4: full native/managed eligibility equivalence is not supported on the native backend.
+- Bundle-1: independent database human-only actor-kind enforcement is not supported on the native backend and is the first item of a future native-backend parity round.
+- Bundle-2: managed-equivalent actor-kind/email history is not supported on the native backend.
+- Bundle-3 is closed for M05 mounted admin/feed readback through the merged availability builder with an injected stock reader; the real native stock read remains M06 P5a work.
+- Bundle-4 establishes only incumbent real-PostgreSQL contention characterization and provides no exactly-once guarantee.
+- The managed baseline schema and its pgTAP tests retain the incumbent legacy value `44.404`; removing it needs a forward migration and an owner decision, while reference composition supplies that value to application code.
+- A1 evidence is offline only: account verification, hosted-time behaviour and owner TEST certification are not claimed, and the `communications/klaviyo` adapter's capabilities stay verification-pending.
+
 ## [0.17.0]
 
 - Publishable on the npm `latest` dist-tag as `0.17.0`, from tag

package/README.md

@@ -4,9 +4,16 @@ Development preview. This package joins core and outbox in the publishable set f
 
 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.19.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0190) before selecting the opt-in M05 parity seams or
+M06 composition bindings. M06 in progress: inventory and shipping entries are early surfaces; module not complete
+The size gate compares this candidate with the published `0.18.0` tarball;
+preparation, offline adapter evidence and a passing size cap grant no publication
+or provider-account certification.
+
 ## Package surface
 
-`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its thirteen experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
+`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its twenty-five experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
 
 | Export | Contents |
 | --- | --- |
@@ -23,6 +30,285 @@ It holds the runnable server substrate an OpenLup application composes: the Node
 | `./identity/contracts` | Experimental capability: browser-safe customer auth port, value types and provider parser |
 | `./communications` | Experimental existing public consent/status, newsletter sync, Auth email hook, transport contracts/capture, observation/polling orchestration, standard webhook verification and delivery receipts; host-selected rendering, egress, protocol mapping and control policy |
 | `./communications/contracts` | Pure renderer, block builders, copy-injected commerce/subscription factories and email/newsletter/Auth/intake/receipt types; no Zod, Node or provider runtime imports |
+| `./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 |
+| `./pricing` | Experimental price authority, quote computation/handlers, offer projection/cache, readiness and policy tokens |
+| `./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 and evidence |
+| `./shipping/contracts` | Type-only delivery, pickup-point, summary and evidence DTOs |
+
+## Shipping
+
+Shipping handlers require injected host schemas; contracts are type-only with opaque provider/carrier strings.
+No vendor code, inventory import, activation or parity claim.
+
+## 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.
+
+`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).
+
+## Promotions
+
+`./promotions` owns the existing automatic/legacy and code quote application,
+benefit interpretation, advisory read ports, preview proofs, public-money binding,
+acceptance tokens and passive telemetry. It calls `@openlup/core/promo`; it does
+not contain another evaluator. Each factory receives the host facts it needs:
+`createQuotePromoDiscounts` takes a customer classifier;
+`createQuotePromotionV2` also takes the product floor and bound legacy application;
+`createQuoteAutomaticPromotions` takes an email eligibility resolver and the bound
+applications. `createQuotePromotionCodeAdjustments` and `createPromotionCodePreview`
+require the floor. No factory supplies a default financial policy.
+
+`createPromotionQuoteAcceptance<Request>` requires `projectRequest`, which returns
+the host's exact request-binding projection; `promoCodes` also binds separately.
+Its four issue/verify functions retain public-money projection, section diagnostics,
+TTL and rotation. Explicit `acquisitionTerms` binds the full server-selected promise.
+The pricing quote handler passes resolved acquisition terms to both
+acceptance callbacks. An opt-in shipping binding appends shipping terms. A host must forward them to the acceptance helper. With no
+acquisition configuration, terms are absent and historical token bytes stay equal.
+This opt-in signature addition does not activate acquisition-only mounted issuance.
+
+`recordPromotionAcceptanceOutcome` requires a recorder and swallows recorder
+failure. The reference wrapper retains its existing sanitized operational recorder.
+Reference wrappers also retain startup floor resolution, customer classification,
+email/contact precedence and the rich request projection. Quote reads never reserve
+capacity. Pricing receives application callbacks and has no import back to promotions.
+
+`createAdminPromotionsHandlers` and `createAdminPromotionCodesHandlers` receive
+the relevant members of `PromotionAdminBindings`: existing host admin-kit factories, authorization
+resolver, response writers, exact RPC-error constructor/mapper and bound preview
+helpers. The package does not copy or relocate that kit. The reference wrappers
+bind these same objects, preserving human-only writes, required audit, signed
+activation previews, validity-window checks and revision-aware replay delegation.
+`createAdminPromotionSchemas` also requires the host currency schema. Its list
+DTOs preserve system-managed read-only rows and valid status-only mirror handles;
+the managed adapter retains the underlying write fences. Adjacent shipping,
+catalog-price and subscription-band schemas and managed adapters remain reference-owned.
+
+`createPostgresCommercePromoDataPort` and `createPostgresPromotionClaimSweepPort`
+use an injected `PgQueryExecutor` from `./data`. They retain four evaluator reads
+and bounded stale-claim sweep; they add no claim writer or reservation path.
+`PROMOTIONS_MIGRATIONS` identifies the byte-identical projections of canonical
+units 47/48 with paths, positions and hashes. These sparse units are not an
+installation chain: use the complete canonical catalogue. No migration or
+manifest identity changes in this move.
+
+The server entry is classified as an adapter because its executor declaration
+reaches the data entry and optional pg types. It imports at runtime without pg
+and works with an injected executor; selecting the data gateway retains its
+named missing-pg refusal. Its declarations compile after peer selection. The
+contracts entry remains a non-adapter, imports no other module and compiles
+without optional peers in NodeNext and Bundler modes.
+
+The [promotion suites](test/promotions/) retain existing assertions. The
+[real PostgreSQL witness](../../tests/postgres/promotionsNative.test.ts) installs
+the full canonical chain, checks projection hashes and validated constraints,
+and proves reads without durable writes, paid/released lifecycle, bounded
+sweep, receipt/outbox fences, replay, lock/settlement skips and explicit invoker
+grants. This is existing native lifecycle/read evidence only. Native code
+candidates, mounted issue/honor, acquisition-only mounted acceptance and the
+full native/managed eligibility matrix are accepted native-backend capability
+gaps, without a parity claim, in the
+[module ledger](../../docs/platform/plans/oss-m05-catalog-offers-pricing.md#d8-pending-outcome-ledger).
+
+Opt-in `shippingTerms` also binds shipping-only promises. `createQuoteShippingPromotions`
+resolves post-discount thresholds; optional `acquisition` bindings select host policy.
+Omission preserves incumbent behavior. See [parity seams](../../docs/platform/CANONICAL_CONTRACTS.md#m05-parity-seams).
+
+## Pricing
+
+`./pricing` provides the existing OpenLup strict commerce price authority,
+subscription-price-policy schemas, canonical digest and integer math, signed
+pricing-policy assignment tokens and safe refusal mapping. Hosts inject exact
+price-list, base-entry, legacy-entry and policy-history reads. The authority
+validates the base before reading history and uses the observed base's
+`priceListId` for that lookup. History excludes legacy fallback even when no
+revision is currently effective. Digest, interval, ambiguity and amount-kind
+refusals retain their existing identities and precedence. The opt-in
+`createConcurrentCommercePriceAuthorityPort` instead schedules history alongside
+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
+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.
+Reference paths use named exports of the same functions and error classes;
+the browser keeps its existing policy schema binding locally.
+
+The quote foundation also owns neutral money/tax/quote DTOs, promotion evidence
+and rejection details, bounded catalog facts, provenance creation/public stripping
+and the supported-tax-profile guard. `createCommerceQuoteSchemas` requires the
+host's currency, product-slug and context schemas; `createCommerceQuotePrimitives`
+requires currency validation. No settlement default or catalog policy is installed.
+The original line, currency, VAT, discount and shipping equations and v1/v2
+provenance refusals are preserved. Quote ports accept host request/response types.
+The reference keeps its rich browser request/context validation and catalog bridge;
+server compatibility paths export the same error classes and provenance/tax functions.
+The portable schema counterparts stay server-side; binding tests compare their
+results and diagnostics with browser validation.
+
+`createDbBackedCommerceQuotePort` owns the existing quote computation and price,
+tax and component helpers. Hosts supply bounded catalog/price reads, settlement
+values, a flat shipping read, promotion application and context callbacks. The
+reference binds `getShippingFlatMinor`, industry context and existing promotion
+implementation. Shipping is read before promotion application; the original VAT
+helper and both discount lanes are preserved. Snapshot comparison accepts injected
+response validation and request reconstruction, so rich context stays local.
+
+Quote, ordered batch and offer handlers take the host's schemas and BFF responder;
+the reference binds its observed request context. Their error identities, refusal
+mapping, promotion acceptance/fallback and public evidence refusal are unchanged.
+Offer projection requires roster, representative-request, unit-count, floor and
+wire-scope policy. It retains v1/v2 responses, partial degradation only for a
+missing configured price, and the first successfully priced representative.
+The offer cache bounds success freshness from load start and retains its separate
+failure TTL; readiness keeps its 60-second positive and 5-second negative caps.
+The additive experimental acquisition API is off by default. `selectAcquisitionTerms`
+and `filterAcquisitionPromotions` require an `AcquisitionFinancialPolicy<Row>`:
+row facts, classification, metadata validation, pair matching, initial rate and
+unconfigured terms all come from the host. Omission refuses with
+`acquisition_terms_policy_unconfigured`, even with no rows; no financial policy
+or schedule is bundled. Selection preserves row identity, validates the whole
+tagged schedule and uses half-open windows with the next future boundary.
+
+`createAcquisitionQuoteSchemas` composes separate capability/context/resolved-terms
+schemas with the host's validators. `projectAcquisitionOfferPricing` pins the
+observation time and capability for every representative request; its v3 output
+contains public terms and expires by the next boundary or 60 seconds.
+`createAcquisitionOfferPricingSchema` retains the injected v2 settlement and scope
+rules. The opt-in handler delegates absent acquisition headers to an incumbent
+handler; negotiated responses require v3, paired v2 policy and private no-store
+headers. The incumbent handler continues ignoring acquisition headers.
+`createAcquisitionReadinessCache` requires an explicit policy configuration,
+validates acquisition evidence, clamps positive cache expiry and rereads once
+after crossing a boundary. The existing shared readiness cache remains unchanged.
+
+Promise comparison is independent of money. Explicit server-selected resolved
+terms can join the existing acceptance money projection and totals section;
+absence contributes no property. Quote/batch refusal mapping and unsigned-terms
+fallback checks require explicit acquisition configuration. Reference composition
+supplies none: existing schemas, headers, reads, error details and token bytes
+are preserved. Threshold shipping is supplied by the separate
+[parity seam](../../docs/platform/CANONICAL_CONTRACTS.md#m05-parity-seams).
+Checkout admission, claims, finalization,
+promotion implementation, stores, SQL, routes and activation remain outside
+this API.
+
+The package witnesses in `test/pricing/` move the incumbent authority, policy,
+token, quote, snapshot, handler, offer, cache and readiness assertions. Currency
+fixtures use synthetic identifiers while preserving the same arithmetic and
+refusals. Reference schemas, rich catalog/context policy and composition remain
+in the application. The existing cold consumer exercises both entries and
+compiles installed declarations without optional provider peers.
+
+## Catalog
+Opt-in `priceAuthority: "effective"` on the native bundle store and the admin
+`effectiveTarget` hook provide [effective bundle parity](../../docs/platform/CANONICAL_CONTRACTS.md#m05-parity-seams);
+`selectEffectiveBundleTargetPrice` is exported. Omitted seams preserve defaults.
+
+The native envelope and dark draft adapters now live in this entry as
+`createPostgresCatalogSkuEnvelopeReadPort` and `createPostgresCatalogDraftStore`.
+They accept an injected executor and retain the existing mapping, errors and SQL
+semantics. The mapper remains internal to the package. `CATALOG_MIGRATIONS`
+projects canonical positions 1, 8, 58, 59 and 61 byte for byte; these assets are
+sparse references, never a standalone install chain. No canonical migration or
+manifest entry changes.
+
+The composition entry adds `createCatalogContribution` and its structural input
+interface. It describes actual catalog, pricing and promotions callables under
+those existing module identities, with no environment discovery, client creation
+or registration. It imports only readiness types: composition gains no catalog
+edge, and catalog keeps its type-only data edge plus one pricing value edge for
+the effective-window selector. Package boundary
+checks pin those imports and peer-free composition declarations. The packed
+consumer exercises both new stores and the descriptor without optional peers;
+its synthetic executor proves named refusal, not durable storage behavior.
+
+
+`./catalog` is an experimental capability for the existing neutral catalog
+foundation, installed product types, draft validation/use cases, active SKU
+selection, resolved SKU projection and sellable reference reads. Hosts supply
+the read/store ports, verified operator authorizer, product-type registry and
+BFF responder. Draft commands retain the original canonical bytes, receipt-first
+replay, actor binding and named refusals. Read projections carry opaque
+product-scoped document references; they do not interpret document payloads.
+
+Fixed-bundle application/admin now uses this same server entry: rules, read/write
+ports, batched stock derivation, nine mutations, four reads/price preview and the
+public sellable-feed factory. Named reference wrappers inject lifecycle and stock
+helpers, existing admin kit/spec/flags, validators, responder, wire versions and
+the reference-owned RPC error constructor. The read error has one package identity.
+`createPostgresBundleCatalogStore` now accepts the data entry's injected
+`PgQueryExecutor`; it renders the incumbent list/detail/feed/history SELECTs
+without constructing a pool or switching roles. The writer, pooled transaction
+binding and transport adapters remain reference-owned. `BUNDLE_MIGRATIONS`
+projects canonical units 16 and 19 with their original paths, positions, hashes
+and byte-identical SQL. These sparse projections are not an installation chain:
+apply the complete canonical manifest. No new migration or activation is added.
+Preview target selection remains the existing first active matching-mode row.
+
+`./catalog/contracts` carries dependency-free DTOs, the shared authority error,
+GTIN/authority helpers, quantity/option helpers and the existing draft JSON
+canonicalizer. It imports no Zod, Node runtime or server barrel. Runtime schemas
+use the server entry with jitless Zod; the reference browser keeps its sellable
+schemas locally. Media manifest validation and `resolveProductMedia` are also
+browser exports: declared product/variant/locale associations resolve to supplied
+URLs with deterministic ordering and neutral fallback, without filename inference.
+The server entry adds bounded source-pack export/validation/restore/import;
+`BlobStoragePort` comes from the existing `@openlup/core/platform-runtime` entry.
+Import validates every resource before uploading immutable digest keys, deduplicates
+shared keys and never activates associations. No upload route is mounted.
+
+Read and draft behavior is supplied by the existing use cases and host ports.
+`publicationRead`, `publish` and `lifecycleWrite` remain explicitly unsupported
+in the neutral reference binding. Lifecycle DTOs and server validation/publication
+ports are types only, with an opaque publisher brand and no constructor or default
+binding. A missing authority is `unsupported`; an unavailable configured authority
+is `dependency_unavailable`, never an absent receipt. Successful readback requires
+real publication lineage; existing active rows cannot invent a head. History pages
+are bounded to 100 receipts with stable revision ordering and opaque cursors.
+Existing SKU `draft`/`active`/`archived` and draft receipt `open`/`abandoned` wire
+statuses remain unchanged. `withdrawn` may map from `archived` only where an
+authority establishes withdrawal; abandoning a draft does not withdraw a variant.
+Neither entry installs SQL. Rich application catalog interpretation remains
+reference-owned. The [M05 plan](../../docs/platform/plans/oss-m05-catalog-offers-pricing.md)
+records the cut, its exclusions and the witness ledger.
+The moved characterization suites are under `test/catalog/`; the required cold
+consumer imports both entries without optional peers and checks installed
+canonicalization, authority identity, selection and unauthorized draft refusal.
+Three synthetic media conformance cases and one lifecycle type case complement
+those moved suites; the existing package boundary tests cover browser closure.
+Bundle browser schemas remain locally defined by the reference, preserving
+parse/default/strictness behavior; the package contracts add plain DTO types only.
+Installed callers inject validators into server factories. Five package suites
+retain 44 bundle cases; two root binding suites retain 18. Four neutral W4 cases
+and one binding/browser-closure case add five required cases. The cold consumer
+also checks bundle composition refusal, unknown stock and exact allocation;
+catalog server is deliberately classified as an adapter because its declarations
+reach optional pg types through the executor. Its runtime still imports and reads
+through an injected executor with optional peers absent. Catalog contracts remains
+a non-adapter and compiles without peers. Server declarations compile after peer
+selection. Five real-PostgreSQL cases characterize full-chain replay, complete
+ordered reads with unchanged data, whole-set rollback/refusals/dry runs, price
+history, sequential key recognition and explicit invoker grants. Native routines
+have no independent human-only actor-kind gate; the handler supplies that gate.
+This does not close the bundle parity ledger.
+The complete contracts entry measures 3,281 B minified+gzip against its 4,096 B
+budget; other entry and aggregate caps are unchanged.
+
+Moved catalog, pricing and promotion fixtures use synthetic identities, regions,
+currencies and host-defined context fields. Their assertions retain the original
+operators and case counts. Reference classifiers receive the legacy threshold
+from their host composition; only the immutable managed baseline predicates
+await an owner decision. Pricing VAT calculation retains
+both exported helpers and their signatures: `calculateIncludedVat` delegates to
+`splitIncludedVat` through a distinct named wrapper using the same arithmetic.
 
 ## Scheduled jobs
 
@@ -149,7 +435,7 @@ phase redirects npm to an empty temporary cache.
 
 The composition declarations describe the injected Supabase factory structurally;
 they do not import the data entry or its PostgreSQL types. The cold proof still
-requires all six nonadapter entries (including `./identity/contracts`) to import in fresh processes and compile
+requires all declared non-adapter entries (including `./identity/contracts`) to import in fresh processes and compile
 in both resolution modes with all three optional peers absent.
 
 <!-- openlup-doc-impact {"unit":"platform-substrate","digest":"sha256-00994d288cfec0c8dc0ae9aeae2ff542e2e9af2fedcb4dd2dfeb6c99523be92d","reason":"The manifest moves to the 0.15.0 set version with the exact @openlup/core 0.15.0 peer pin. The package surface, settings and verification described here are unchanged by this preparation delta."} -->
@@ -506,8 +792,10 @@ The maintained mail transport, credentials, callback verification/mapping,
 poll read/mapping, timeline and send-ledger adapters remain in reference source.
 B1 changes only the four raw-injection guard sites in the reference delivery
 adapters and the approved invoice test fixture; the concrete client and all
-other vendor-directory files retain the comparison-base bytes. The package exposes
-transport/result contracts and capture without a concrete mail factory.
+other vendor-directory files retain the comparison-base bytes. The neutral
+`./communications` entry exposes transport/result contracts and capture without
+concrete mail wiring. The platform ships opt-in vendor adapter subpaths;
+default wiring includes none, and adopters choose or replace them.
 The type-only `CommunicationProvider<Provider>` and `EmailMessageReadModel<Provider>`
 accept host vocabulary; reference types retain their original literal.
 
@@ -517,8 +805,9 @@ whole decision and enters the sender only for a coherent `production`,
 `sandbox_direct` or `sandbox_sink` decision. The sender receives the effective
 recipient and a frozen context with intended recipient, host-selected credential,
 mode, reason and environment tag. It must consume that context when selecting
-credentials and emitting provider metadata. The package reads no environment and
-contains no provider client. Missing/throwing policy, unknown modes, mismatched
+credentials and emitting provider metadata. The neutral entry reads no environment
+and contains no provider client. Opt-in adapters consume this same guard and
+host-selected context. Missing/throwing policy, unknown modes, mismatched
 recipients/tags, blank credentials or unsupported fields fail with status zero,
 no identifier and bounded error codes. Reasons are lower-case token codes up to
 80 characters. One unadorned `local@domain.example` recipient mailbox is required;
@@ -751,3 +1040,7 @@ Core readiness, explicit provider ports and host-supplied schedules. Native
 readback and signed-token bridges do not promise managed frequency caps, legacy
 tester-source parity, a send-time fence or a full native network sender. The
 opt-in browser profile adds no npm entry or UI package export.
+
+Source contributors record notable changes in package changelog fragments;
+release preparation assembles the shipped CHANGELOG. Follow the
+[public contribution guide](https://github.com/openlup/openlup/blob/main/CONTRIBUTING.md#development-preview-checks).

package/dist/catalog/activeSkuSelection.d.ts

@@ -0,0 +1,2 @@
+/** Shares exact-code parsing with detail reads; omission alone keeps discovery broad. */
+export declare function parseCatalogActiveSkuSelection(value: unknown): readonly string[] | undefined;

package/dist/catalog/activeSkuSelection.js

@@ -0,0 +1,20 @@
+import { catalogSkuEnvelopeSelectorSchema } from "./foundationSchemas.js";
+/** Shares exact-code parsing with detail reads; omission alone keeps discovery broad. */
+export function parseCatalogActiveSkuSelection(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length < 1 || value.length > 100) {
+        throw new RangeError("catalog_active_sku_selection_invalid");
+    }
+    const codes = [];
+    const seen = new Set();
+    for (const skuCode of value) {
+        const parsed = catalogSkuEnvelopeSelectorSchema.safeParse({ kind: "sku_code", skuCode });
+        if (!parsed.success || parsed.data.kind !== "sku_code" || seen.has(parsed.data.skuCode)) {
+            throw new RangeError("catalog_active_sku_selection_invalid");
+        }
+        codes.push(parsed.data.skuCode);
+        seen.add(parsed.data.skuCode);
+    }
+    return codes;
+}

package/dist/catalog/adminBindings.d.ts

@@ -0,0 +1,72 @@
+import type { ZodType } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+/** Structural inputs to the reference admin kit. Authorization and parsing stay with the host. */
+export type AuthorizeAdmin = () => Promise<{
+    ok: true;
+    userId: string;
+    role: "admin" | "distributor";
+    isMachineActor: boolean;
+} | {
+    ok: false;
+    code: "UNAUTHORIZED" | "FORBIDDEN";
+    message: string;
+    identityCode?: string;
+}>;
+export interface AgentDomainQuerySpec<T> {
+    readonly key: string;
+    readonly requestSchema: ZodType<T, unknown>;
+    readonly gate: "read";
+    readonly allowedActorKinds: readonly ("human" | "machine")[];
+}
+export interface AgentDomainMutationSpec<T> extends Omit<AgentDomainQuerySpec<T>, "gate"> {
+    readonly gate: "mutation" | "activation";
+    readonly lifecycleMarkers: readonly ("LIFECYCLE_ACTIVATE" | "LIFECYCLE_DEACTIVATE" | "HARD_DELETE")[];
+}
+export type BundleMutationKey = "create" | "update" | "setComposition" | "setTargetPrice" | "archive" | "restore" | "cloneDraft" | "activate" | "deactivate";
+export type BundleQueryKey = "list" | "get" | "history" | "previewPrice";
+export interface BundleResponseSchema {
+    safeParse(value: unknown): {
+        success: boolean;
+        data?: unknown;
+    };
+}
+type Handler = (req: HttpRequest, res: HttpResponse) => Promise<void>;
+interface CommonOptions<T> {
+    authorizeAdmin: AuthorizeAdmin;
+    flagName?: string;
+    enabled?: boolean;
+    toResponse(value: T): Record<string, unknown>;
+    disabledMessage?: string;
+    invalidRequestMessage: string;
+    failureMessage: string;
+}
+export interface BundleAdminBindings {
+    bundleSpec: {
+        readonly mutations: Readonly<Record<string, AgentDomainMutationSpec<unknown>>>;
+        readonly queries?: Readonly<Record<string, AgentDomainQuerySpec<unknown>>>;
+        readonly mutationFlag: `${string}_MUTATIONS_ENABLED`;
+        readonly activationFlag: `${string}_ACTIVATION_ENABLED`;
+        readonly readFlag?: `${string}_READ_ENABLED`;
+    };
+    COMMERCE_CONTRACT_VERSION: "commerce.v0";
+    /** Passed by identity: instanceof and shared SQLSTATE mapping retain their owner. */
+    BundleRpcError: new (sqlstate: string | undefined, message: string) => Error & {
+        sqlstate: string | undefined;
+        pgMessage: string;
+    };
+    createAdminMutationHandler<Request, Result>(options: CommonOptions<Result> & {
+        mutation: AgentDomainMutationSpec<Request>;
+        invoke(actorId: string, request: Request): Promise<Result>;
+    }): Handler;
+    createAdminParameterizedReadHandler<Request, Result>(options: CommonOptions<Result> & {
+        query: AgentDomainQuerySpec<Request>;
+        load(actorId: string, request: Request): Promise<Result>;
+        responseSchema: BundleResponseSchema;
+        invalidResponseMessage: string;
+    }): Handler;
+    bundleHistoryResponseSchema: BundleResponseSchema;
+    getBundleResponseSchema: BundleResponseSchema;
+    listBundlesResponseSchema: BundleResponseSchema;
+    previewBundlePriceResponseSchema: BundleResponseSchema;
+}
+export {};

package/dist/catalog/adminBindings.js

@@ -0,0 +1 @@
+export {};

package/dist/catalog/adminBundleHandler.d.ts

@@ -0,0 +1,26 @@
+import type { BundleAdminBindings, AuthorizeAdmin } from "./adminBindings.js";
+import type { CompositionRulesPort } from "@openlup/core/bundle";
+import type { AdminBundleWritePort } from "./adminBundleWritePort.js";
+export interface AdminBundleHandlerDeps {
+    writePort: AdminBundleWritePort;
+    authorizeAdmin: AuthorizeAdmin;
+    mutationsEnabled: boolean;
+    activationEnabled: boolean;
+    /**
+     * The adopter's composition rules. Supplied only where a composition constraint
+     * can be attached; when absent, a non-empty envelope is stored unvalidated, which
+     * is what "the platform never interprets it" means.
+     */
+    compositionRules?: CompositionRulesPort;
+}
+export declare function createAdminBundleHandlers({ bundleSpec, BundleRpcError, COMMERCE_CONTRACT_VERSION, createAdminMutationHandler }: Pick<BundleAdminBindings, "bundleSpec" | "BundleRpcError" | "COMMERCE_CONTRACT_VERSION" | "createAdminMutationHandler">): {
+    createAdminBundleCreateDraftHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleUpdateDraftHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleSetCompositionHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleSetTargetPriceHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleArchiveHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleRestoreHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleCloneDraftHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleActivateHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleDeactivateHandler: (deps: AdminBundleHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+};