@openlup/platform 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -8,6 +8,53 @@ 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

package/README.md

@@ -4,10 +4,10 @@ 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.18.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0180) before selecting M05 catalog/pricing/promotions
-or A1 communications adapters. M06 in progress: inventory and shipping entries are early surfaces; module not complete.
-The size gate compares this candidate with the published `0.17.0` tarball;
+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.
 
@@ -47,6 +47,8 @@ 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
@@ -65,8 +67,8 @@ require the floor. No factory supplies a default financial policy.
 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 its resolved terms as the last argument to both
-acceptance callbacks. A host must forward them to the acceptance helper. With no
+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.
 
@@ -113,6 +115,10 @@ 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,
@@ -122,7 +128,9 @@ 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.
+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
@@ -186,7 +194,9 @@ 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. Checkout admission, claims, finalization, threshold shipping,
+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.
 
@@ -198,6 +208,10 @@ 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
@@ -210,7 +224,8 @@ 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 retains its existing type-only data edge. Package boundary
+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.

package/dist/catalog/adminBundleReadHandler.d.ts

@@ -1,7 +1,8 @@
 import type { BundleAdminBindings, AuthorizeAdmin } from "./adminBindings.js";
 import type { BundleAvailabilityService } from "./bundleAvailabilityService.js";
-import type { BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
+import type { BundleCatalogReadPort, BundleDetail, BundleTargetPriceRow } from "./bundleCatalogReadPort.js";
 export interface AdminBundleReadHandlerDeps {
+    effectiveTarget?: (bundle: BundleDetail) => BundleTargetPriceRow | null;
     readPort: BundleCatalogReadPort;
     authorizeAdmin: AuthorizeAdmin;
     readsEnabled: boolean;

package/dist/catalog/adminBundleReadHandler.js

@@ -107,7 +107,7 @@ export function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMM
             });
             if (!bundle)
                 throw new BundleRpcError("P0002", "bundle_not_found");
-            return previewBundlePrice(bundle, input);
+            return previewBundlePrice(bundle, input, deps.effectiveTarget);
         }, (preview) => ({ contractVersion: COMMERCE_CONTRACT_VERSION, preview }), previewBundlePriceResponseSchema, "Invalid bundle price preview response");
     }
     /** The detail the transport carries: the port's internal variant id stays server-side. */
@@ -140,7 +140,7 @@ export function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMM
      * no priced list (P0002), an unpriced component or an empty set (P0001), and the
      * kernel's own three failure codes (P0001).
      */
-    function previewBundlePrice(bundle, input) {
+    function previewBundlePrice(bundle, input, effectiveTarget) {
         if (!bundle.resolvedPriceListId || !bundle.resolvedCurrency) {
             throw new BundleRpcError("P0002", "no_active_price_list");
         }
@@ -151,7 +151,7 @@ export function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMM
         if (unpriced.length > 0) {
             throw new BundleRpcError("P0001", `component_unpriced:${unpriced[0].sku}`);
         }
-        const activePrice = bundle.prices.find((price) => price.active && (!input.mode || price.mode === input.mode));
+        const activePrice = effectiveTarget ? effectiveTarget(bundle) : bundle.prices.find((price) => price.active && (!input.mode || price.mode === input.mode));
         const targetPriceMinor = input.targetPriceMinor ?? activePrice?.targetPriceMinor;
         if (targetPriceMinor === undefined)
             throw new BundleRpcError("P0002", "no_active_target_price");
@@ -170,7 +170,7 @@ export function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMM
         return {
             bundleCode: bundle.code,
             priceListId: bundle.resolvedPriceListId,
-            mode: input.mode ?? activePrice?.mode ?? "any",
+            mode: input.mode ?? activePrice?.mode ?? (effectiveTarget ? "one_time" : "any"),
             currency: bundle.resolvedCurrency,
             referenceTotalMinor: allocation.referenceTotalMinor,
             targetPriceMinor: allocation.targetPriceMinor,

package/dist/catalog/bundleCatalogReadPort.d.ts

@@ -91,6 +91,8 @@ export interface BundleDetail extends BundleSummary {
     metadata: Record<string, unknown>;
     components: BundleComponentRow[];
     prices: BundleTargetPriceRow[];
+    /** Present only when the host selects effective price authority. */
+    resolvedTargetPrice?: BundleTargetPriceRow | null;
     /** The currency whose list resolved `referenceUnitPriceMinor`; `null` if none did. */
     resolvedCurrency: string | null;
     /**
@@ -108,8 +110,10 @@ export interface GetBundleInput {
      * only currency an operator has actually chosen for it.
      */
     currency?: string;
-    /** Narrow the target price whose list is selected; omitted means any mode. */
+    /** Narrow the target price whose list is selected; omitted means any mode (the opt-in effective store defaults to one_time). */
     mode?: string;
+    regionCode?: string;
+    atTime?: string;
 }
 /**
  * One live, sellable bundle: active status, an active target price, and its
@@ -156,6 +160,9 @@ export interface BundleCatalogReadPort {
      */
     listActiveBundleCompositions(input?: {
         currency?: string;
+        regionCode?: string;
+        mode?: "one_time" | "subscription";
+        atTime?: string;
     }): Promise<ActiveBundleComposition[]>;
     /**
      * The operator trail for one bundle. The two chains answer from different

package/dist/catalog/bundleCatalogStore.d.ts

@@ -1,3 +1,5 @@
 import type { BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
 import type { PgQueryExecutor } from "../data/index.js";
-export declare function createPostgresBundleCatalogStore(executor: PgQueryExecutor): BundleCatalogReadPort;
+export declare function createPostgresBundleCatalogStore(executor: PgQueryExecutor, options?: {
+    priceAuthority?: "effective";
+}): BundleCatalogReadPort;

package/dist/catalog/bundleCatalogStore.js

@@ -1,6 +1,10 @@
+import { createEffectiveBundleCatalogStore } from "./effectiveBundleCatalogStore.js";
 import { BundleCatalogReadError, } from "./bundleCatalogReadPort.js";
 import { LIST_SQL, COUNT_SQL, DETAIL_SQL, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL, HISTORY_SQL, HISTORY_COUNT_SQL, } from "./bundleCatalogQueries.js";
-export function createPostgresBundleCatalogStore(executor) {
+export function createPostgresBundleCatalogStore(executor, options) {
+    if (options?.priceAuthority === "effective") {
+        return createEffectiveBundleCatalogStore(executor, createPostgresBundleCatalogStore(executor));
+    }
     async function rows(sql, values) {
         // A driver failure becomes the port's own read error, so a caller sees the
         // same distinction between "found nothing" and "could not ask" on both chains.

package/dist/catalog/bundlePriceSelection.d.ts

@@ -0,0 +1,13 @@
+import { type BundleTargetPriceRow } from "./bundleCatalogReadPort.js";
+export declare function uniqueBundlePrice<T extends {
+    mode: string;
+}>(rows: readonly T[], mode: string): T | null;
+export declare function selectEffectiveBundleTargetPrice(rows: readonly {
+    price: BundleTargetPriceRow;
+    priceListId: string;
+}[], context: {
+    priceListId: string | null;
+    currency: string | null;
+    mode: string;
+    atTime: string;
+}): BundleTargetPriceRow | null;

package/dist/catalog/bundlePriceSelection.js

@@ -0,0 +1,26 @@
+import { selectUniqueEffectivePriceList } from "../pricing/index.js";
+import { BundleCatalogReadError } from "./bundleCatalogReadPort.js";
+/** Half-open windows share the price authority's effective-time rule. */
+function bundlePriceEffective(row, atTime) {
+    try {
+        selectUniqueEffectivePriceList([{ value: "row", ...row }], atTime);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function uniqueBundlePrice(rows, mode) {
+    const exact = rows.filter(row => row.mode === mode);
+    const candidates = exact.length ? exact : rows.filter(row => row.mode === "any");
+    if (candidates.length > 1)
+        throw new BundleCatalogReadError("bundle_price_ambiguous");
+    return candidates[0] ?? null;
+}
+export function selectEffectiveBundleTargetPrice(rows, context) {
+    if (context.priceListId === null || context.currency === null)
+        return null;
+    return uniqueBundlePrice(rows.filter(row => row.priceListId === context.priceListId
+        && row.price.currency === context.currency && row.price.active && row.price.amountKind === "gross"
+        && row.price.targetPriceMinor > 0 && bundlePriceEffective(row.price, context.atTime)).map(row => row.price), context.mode);
+}

package/dist/catalog/contracts/bundleRead.d.ts

@@ -65,6 +65,15 @@ export type GetBundleResponse = {
             validFrom: string;
             validTo: string | null;
         }[];
+        resolvedTargetPrice?: {
+            mode: string;
+            targetPriceMinor: number;
+            currency: string;
+            amountKind: string;
+            active: boolean;
+            validFrom: string;
+            validTo: string | null;
+        } | null;
         resolvedCurrency: string | null;
         availability: {
             sellableNow: number | null;
@@ -113,6 +122,15 @@ export type BundleDetailView = {
         validFrom: string;
         validTo: string | null;
     }[];
+    resolvedTargetPrice?: {
+        mode: string;
+        targetPriceMinor: number;
+        currency: string;
+        amountKind: string;
+        active: boolean;
+        validFrom: string;
+        validTo: string | null;
+    } | null;
     resolvedCurrency: string | null;
     availability: {
         sellableNow: number | null;

package/dist/catalog/contracts/draft.js

@@ -7,7 +7,7 @@ export function canonicalCatalogDraftJson(input) {
         if (depth > 48)
             throw new Error("draft_json_depth");
         if (typeof value === "string") {
-            if (value.includes("\u0000") || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value))
+            if (value.includes("\u0000") || /[\uD800-\uDFFF]/u.test(value))
                 throw new Error("draft_json_invalid");
             return value;
         }

package/dist/catalog/effectiveBundleCatalogQueries.d.ts

@@ -0,0 +1,8 @@
+export declare const COMPONENT_SQL: string;
+export declare const FEED_COMPONENT_SQL: string;
+export declare const PRICE_SQL = "\n  SELECT p.mode, p.price_list_id, p.target_price_minor, list.currency, p.amount_kind, p.active, p.valid_from, p.valid_to\n  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n  WHERE p.bundle_id = $1::uuid ORDER BY p.valid_from DESC";
+export declare const OWN_LIST_SQL = "\n  SELECT list.id, list.currency, list.region_code, p.mode\n  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n  WHERE p.bundle_id = $1::uuid AND p.active AND p.amount_kind = 'gross'\n    AND (p.mode = $2::text OR p.mode = 'any') AND list.status = 'active'\n    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)\n    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)\n  ORDER BY p.valid_from DESC";
+export declare const CURRENCY_LIST_SQL = "\n  SELECT id, currency, region_code FROM public.price_lists\n  WHERE currency = $1::text AND status = 'active' AND ($2::text IS NULL OR region_code = $2::text)\n    AND valid_from <= $3::timestamptz AND (valid_to IS NULL OR valid_to > $3::timestamptz)";
+export declare const FEED_SQL = "\n  SELECT b.id, b.code, b.title, b.fulfillment_mode, p.mode, p.target_price_minor, p.price_list_id, list.currency, list.region_code\n  FROM public.catalog_bundles b\n  JOIN public.catalog_bundle_prices p ON p.bundle_id = b.id AND p.active\n  JOIN public.price_lists list ON list.id = p.price_list_id\n  WHERE b.status = 'active' AND p.amount_kind = 'gross' AND p.target_price_minor > 0\n    AND list.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)\n    AND ($2::text IS NULL OR list.region_code = $2::text) AND (p.mode = $4::text OR p.mode = 'any')\n    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)\n    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)\n  ORDER BY b.code, p.valid_from DESC";
+export declare const DETAIL_SQL = "SELECT b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,\n  b.composition_constraint, b.metadata,\n  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id) AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n    WHERE p.bundle_id = b.id AND p.active AND p.amount_kind = 'gross' AND p.target_price_minor > 0\n      AND p.mode IN ('one_time', 'any') AND list.status = 'active'\n      AND p.valid_from <= CURRENT_TIMESTAMP AND (p.valid_to IS NULL OR p.valid_to > CURRENT_TIMESTAMP)\n      AND list.valid_from <= CURRENT_TIMESTAMP AND (list.valid_to IS NULL OR list.valid_to > CURRENT_TIMESTAMP)) AS has_active_target_price FROM public.catalog_bundles b WHERE b.code = $1";
+export declare const LIST_SQL = "SELECT b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,\n  b.composition_constraint, b.metadata,\n  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id) AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n    WHERE p.bundle_id = b.id AND p.active AND p.amount_kind = 'gross' AND p.target_price_minor > 0\n      AND p.mode IN ('one_time', 'any') AND list.status = 'active'\n      AND p.valid_from <= CURRENT_TIMESTAMP AND (p.valid_to IS NULL OR p.valid_to > CURRENT_TIMESTAMP)\n      AND list.valid_from <= CURRENT_TIMESTAMP AND (list.valid_to IS NULL OR list.valid_to > CURRENT_TIMESTAMP)) AS has_active_target_price FROM public.catalog_bundles b\n  WHERE ($1::text = 'all' OR b.status = $1::text)\n    AND ($2::text IS NULL OR b.code ILIKE '%' || $2 || '%' OR b.title ILIKE '%' || $2 || '%')\n  ORDER BY b.code LIMIT $3 OFFSET $4";

package/dist/catalog/effectiveBundleCatalogQueries.js

@@ -0,0 +1,79 @@
+/** Effective-authority SQL is isolated from the incumbent exported statements. */
+const ANCHORS = `SELECT pe.unit_price_minor FROM public.price_entries pe
+  WHERE pe.variant_id = s.id AND pe.price_list_id = %LIST% AND pe.active
+    AND pe.min_qty = 1 AND pe.amount_kind = 'gross'
+    AND pe.valid_from <= $3::timestamptz AND (pe.valid_to IS NULL OR pe.valid_to > $3::timestamptz)
+    AND (pe.mode = $4::text OR (pe.mode = 'any' AND NOT EXISTS (
+      SELECT 1 FROM public.price_entries exact WHERE exact.variant_id = s.id
+        AND exact.price_list_id = pe.price_list_id AND exact.active AND exact.min_qty = 1
+        AND exact.amount_kind = 'gross' AND exact.mode = $4::text
+        AND exact.valid_from <= $3::timestamptz AND (exact.valid_to IS NULL OR exact.valid_to > $3::timestamptz))))`;
+const FACTS = `s.status AS sku_status, s.sellable_standalone, s.sellable_in_subscription,
+  s.net_weight_g, pr.status AS product_status,
+  (pr.primary_sku_id IS NOT NULL AND revision.id IS NOT NULL) AS document_ready,
+  COALESCE((SELECT jsonb_agg(jsonb_build_object('issuer', identifier.issuer, 'normalizedValue', identifier.normalized_value,
+    'kind', identifier.identifier_kind, 'packKind', identifier.pack_kind, 'packQuantity', identifier.quantity, 'isPrimary', identifier.is_primary))
+    FROM public.catalog_sku_identifiers identifier WHERE identifier.catalog_sku_id = s.id), '[]'::jsonb) AS identifiers`;
+const REFERENCE = `(SELECT (array_agg(candidate.unit_price_minor))[1] FROM (${ANCHORS}) candidate)`;
+const COUNT = `(SELECT count(*) FROM (${ANCHORS}) candidate)`;
+export const COMPONENT_SQL = `
+  SELECT c.bundle_id, s.sku, s.title, pr.slug AS product_slug, s.id AS variant_id,
+    c.quantity, c.is_addon, c.sort_order, ${FACTS},
+    ${REFERENCE.replace("%LIST%", "$2::uuid")} AS reference_unit_price_minor,
+    ${COUNT.replace("%LIST%", "$2::uuid")} AS reference_price_count
+  FROM public.catalog_bundle_components c
+  JOIN public.catalog_skus s ON s.id = c.catalog_sku_id
+  JOIN public.catalog_products pr ON pr.id = s.product_id
+  LEFT JOIN public.catalog_product_document_revisions revision ON revision.id = pr.current_document_revision_id AND revision.product_id = pr.id
+  WHERE c.bundle_id = $1::uuid ORDER BY c.sort_order, s.sku`;
+export const FEED_COMPONENT_SQL = `
+  SELECT c.bundle_id, s.sku, s.title, pr.slug AS product_slug, s.id AS variant_id,
+    c.quantity, c.is_addon, c.sort_order, ${FACTS},
+    ${REFERENCE.replace("%LIST%", "selected.price_list_id")} AS reference_unit_price_minor,
+    ${COUNT.replace("%LIST%", "selected.price_list_id")} AS reference_price_count
+  FROM unnest($1::uuid[], $2::uuid[]) AS selected(bundle_id, price_list_id)
+  JOIN public.catalog_bundle_components c ON c.bundle_id = selected.bundle_id
+  JOIN public.catalog_skus s ON s.id = c.catalog_sku_id
+  JOIN public.catalog_products pr ON pr.id = s.product_id
+  LEFT JOIN public.catalog_product_document_revisions revision ON revision.id = pr.current_document_revision_id AND revision.product_id = pr.id
+  ORDER BY c.bundle_id, c.sort_order, s.sku`;
+export const PRICE_SQL = `
+  SELECT p.mode, p.price_list_id, p.target_price_minor, list.currency, p.amount_kind, p.active, p.valid_from, p.valid_to
+  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id
+  WHERE p.bundle_id = $1::uuid ORDER BY p.valid_from DESC`;
+export const OWN_LIST_SQL = `
+  SELECT list.id, list.currency, list.region_code, p.mode
+  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id
+  WHERE p.bundle_id = $1::uuid AND p.active AND p.amount_kind = 'gross'
+    AND (p.mode = $2::text OR p.mode = 'any') AND list.status = 'active'
+    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)
+    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)
+  ORDER BY p.valid_from DESC`;
+export const CURRENCY_LIST_SQL = `
+  SELECT id, currency, region_code FROM public.price_lists
+  WHERE currency = $1::text AND status = 'active' AND ($2::text IS NULL OR region_code = $2::text)
+    AND valid_from <= $3::timestamptz AND (valid_to IS NULL OR valid_to > $3::timestamptz)`;
+export const FEED_SQL = `
+  SELECT b.id, b.code, b.title, b.fulfillment_mode, p.mode, p.target_price_minor, p.price_list_id, list.currency, list.region_code
+  FROM public.catalog_bundles b
+  JOIN public.catalog_bundle_prices p ON p.bundle_id = b.id AND p.active
+  JOIN public.price_lists list ON list.id = p.price_list_id
+  WHERE b.status = 'active' AND p.amount_kind = 'gross' AND p.target_price_minor > 0
+    AND list.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)
+    AND ($2::text IS NULL OR list.region_code = $2::text) AND (p.mode = $4::text OR p.mode = 'any')
+    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)
+    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)
+  ORDER BY b.code, p.valid_from DESC`;
+const SUMMARY_COLUMNS = `b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,
+  b.composition_constraint, b.metadata,
+  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id) AS component_count,
+  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id
+    WHERE p.bundle_id = b.id AND p.active AND p.amount_kind = 'gross' AND p.target_price_minor > 0
+      AND p.mode IN ('one_time', 'any') AND list.status = 'active'
+      AND p.valid_from <= CURRENT_TIMESTAMP AND (p.valid_to IS NULL OR p.valid_to > CURRENT_TIMESTAMP)
+      AND list.valid_from <= CURRENT_TIMESTAMP AND (list.valid_to IS NULL OR list.valid_to > CURRENT_TIMESTAMP)) AS has_active_target_price`;
+export const DETAIL_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b WHERE b.code = $1`;
+export const LIST_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b
+  WHERE ($1::text = 'all' OR b.status = $1::text)
+    AND ($2::text IS NULL OR b.code ILIKE '%' || $2 || '%' OR b.title ILIKE '%' || $2 || '%')
+  ORDER BY b.code LIMIT $3 OFFSET $4`;

package/dist/catalog/effectiveBundleCatalogStore.d.ts

@@ -0,0 +1,4 @@
+import type { PgQueryExecutor } from "../data/index.js";
+import { type BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
+/** Selected only by the explicit effective-authority option. */
+export declare function createEffectiveBundleCatalogStore(executor: PgQueryExecutor, incumbent: BundleCatalogReadPort): BundleCatalogReadPort;

package/dist/catalog/effectiveBundleCatalogStore.js

@@ -0,0 +1,156 @@
+import { assertPrimaryUnitGtinAuthority } from "./contracts/foundation.js";
+import { BundleCatalogReadError } from "./bundleCatalogReadPort.js";
+import { uniqueBundlePrice, selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";
+import { COUNT_SQL } from "./bundleCatalogQueries.js";
+import { LIST_SQL, DETAIL_SQL, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL } from "./effectiveBundleCatalogQueries.js";
+/** Selected only by the explicit effective-authority option. */
+export function createEffectiveBundleCatalogStore(executor, incumbent) {
+    async function rows(sql, values) {
+        const result = await executor.query(sql, values).catch((error) => {
+            throw new BundleCatalogReadError(error instanceof Error ? error.message : String(error));
+        });
+        return (result.rows ?? []);
+    }
+    async function selectPriceList(bundleId, input) {
+        const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+        const own = input.currency ? [] : await rows(OWN_LIST_SQL, [bundleId, mode, atTime]);
+        const chosenPrice = uniqueBundlePrice(own, mode), chosen = chosenPrice ? [chosenPrice] : [];
+        const currency = input.currency ?? chosen[0]?.currency;
+        if (!currency)
+            return null;
+        const candidates = await rows(CURRENCY_LIST_SQL, [currency, input.regionCode ?? chosen[0]?.region_code ?? null, atTime]);
+        if (candidates.length > 1)
+            throw new BundleCatalogReadError("bundle_price_list_ambiguous");
+        if (chosen[0] && candidates[0] && chosen[0].id !== candidates[0].id)
+            throw new BundleCatalogReadError("bundle_price_list_changed");
+        return candidates[0] ?? null;
+    }
+    return {
+        ...incumbent,
+        async listBundles(input) {
+            const filter = [input.status, input.query ?? null];
+            const [page, counted] = await Promise.all([
+                rows(LIST_SQL, [...filter, input.limit, input.offset]),
+                rows(COUNT_SQL, filter),
+            ]);
+            return { bundles: page.map(toSummary), total: Number(counted[0]?.total ?? page.length) };
+        },
+        async getBundle(input) {
+            const bundle = (await rows(DETAIL_SQL, [input.code]))[0];
+            if (!bundle)
+                return null;
+            const atTime = input.atTime ?? new Date().toISOString();
+            const list = await selectPriceList(bundle.id, { ...input, atTime });
+            const [componentRows, priceRows] = await Promise.all([
+                rows(COMPONENT_SQL, [bundle.id, list?.id ?? null, atTime, input.mode ?? "one_time"]).then(rows => rows.map(toComponent)),
+                rows(PRICE_SQL, [bundle.id]),
+            ]);
+            return {
+                ...toSummary(bundle), compositionConstraint: toConstraint(bundle.composition_constraint), metadata: bundle.metadata ?? {},
+                components: componentRows, prices: priceRows.map(toPrice),
+                resolvedTargetPrice: selectEffectiveBundleTargetPrice(priceRows.map(row => ({ price: toPrice(row), priceListId: row.price_list_id })), { priceListId: list?.id ?? null, currency: list?.currency ?? null, mode: input.mode ?? "one_time", atTime }),
+                resolvedCurrency: list?.currency ?? null, resolvedPriceListId: list?.id ?? null,
+            };
+        },
+        async listActiveBundleCompositions(input = {}) {
+            const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+            const feed = await rows(FEED_SQL, [input.currency ?? null, input.regionCode ?? null, atTime, mode]);
+            const selected = new Map();
+            const listReads = new Map();
+            for (const row of feed) {
+                const same = feed.filter(candidate => candidate.id === row.id);
+                const candidate = uniqueBundlePrice(same, mode);
+                const key = `${row.currency}:${row.region_code}`;
+                if (!listReads.has(key))
+                    listReads.set(key, rows(CURRENCY_LIST_SQL, [row.currency, row.region_code ?? null, atTime]));
+                const lists = await listReads.get(key);
+                if (lists.length > 1)
+                    throw new BundleCatalogReadError("bundle_price_list_ambiguous");
+                if (lists[0]?.id !== row.price_list_id)
+                    throw new BundleCatalogReadError("bundle_price_list_changed");
+                selected.set(row.id, candidate);
+            }
+            if (!selected.size)
+                return [];
+            const chosen = [...selected.values()];
+            const source = await rows(FEED_COMPONENT_SQL, [chosen.map(row => row.id), chosen.map(row => row.price_list_id), atTime, mode]);
+            const byBundle = groupComponents(source);
+            const sellable = chosen.filter(row => {
+                const components = source.filter(component => component.bundle_id === row.id);
+                return components.length > 0 && components.every(component => componentReady(component, mode));
+            });
+            return sellable.map(row => ({ code: row.code, title: row.title, fulfillmentMode: row.fulfillment_mode,
+                currency: row.currency, targetPriceMinor: row.target_price_minor, mode: row.mode, components: byBundle.get(row.id) ?? [] }));
+        },
+    };
+}
+function groupComponents(rows) {
+    const grouped = new Map();
+    for (const row of rows) {
+        const bucket = grouped.get(row.bundle_id) ?? [];
+        bucket.push(toComponent(row));
+        grouped.set(row.bundle_id, bucket);
+    }
+    return grouped;
+}
+function toComponent(row) {
+    if (Number(row.reference_price_count) > 1)
+        throw new BundleCatalogReadError("bundle_price_ambiguous");
+    return {
+        sku: row.sku,
+        title: row.title ?? null,
+        productSlug: row.product_slug,
+        variantId: row.variant_id,
+        quantity: Number(row.quantity),
+        isAddon: row.is_addon === true,
+        sortOrder: Number(row.sort_order),
+        referenceUnitPriceMinor: row.reference_unit_price_minor === null || row.reference_unit_price_minor === undefined
+            ? null
+            : Number(row.reference_unit_price_minor),
+    };
+}
+function toSummary(row) {
+    return {
+        code: row.code,
+        title: row.title,
+        status: row.status,
+        fulfillmentMode: row.fulfillment_mode,
+        componentCount: Number(row.component_count ?? 0),
+        hasActiveTargetPrice: row.has_active_target_price === true,
+        updatedAt: row.updated_at,
+    };
+}
+function toPrice(row) {
+    return {
+        mode: row.mode,
+        targetPriceMinor: Number(row.target_price_minor),
+        currency: row.currency,
+        amountKind: row.amount_kind,
+        active: row.active === true,
+        validFrom: row.valid_from,
+        validTo: row.valid_to ?? null,
+    };
+}
+/** An empty envelope is stored as `{}`; that is "unconstrained", not a constraint. */
+function toConstraint(value) {
+    if (!value || typeof value.kind !== "string" || value.kind.trim() === "")
+        return null;
+    return {
+        kind: value.kind,
+        version: typeof value.version === "number" ? value.version : 0,
+        data: (value.data ?? {}),
+    };
+}
+function componentReady(row, mode) {
+    try {
+        assertPrimaryUnitGtinAuthority(row.identifiers);
+    }
+    catch {
+        return false;
+    }
+    return row.sku_status === "active" && row.product_status === "active" && row.document_ready === true
+        && Number.isSafeInteger(row.net_weight_g) && row.net_weight_g > 0
+        && (mode === "subscription" ? row.sellable_in_subscription : row.sellable_standalone)
+        && row.reference_unit_price_minor !== null && Number.isSafeInteger(Number(row.reference_unit_price_minor))
+        && Number(row.reference_unit_price_minor) > 0;
+}

package/dist/catalog/index.d.ts

@@ -41,3 +41,4 @@ export { BUNDLE_MIGRATIONS, CATALOG_MIGRATIONS } from "./sql.js";
 export { SUMMARY_COLUMNS, LIST_FILTER, LIST_SQL, COUNT_SQL, DETAIL_SQL, REFERENCE_PRICE, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL, HISTORY_SQL, HISTORY_COUNT_SQL } from "./bundleCatalogQueries.js";
 export { createPostgresCatalogSkuEnvelopeReadPort } from "./catalogSkuEnvelope.js";
 export { createPostgresCatalogDraftStore } from "./catalogDraftStore.js";
+export { selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";

package/dist/catalog/index.js

@@ -23,3 +23,4 @@ export { BUNDLE_MIGRATIONS, CATALOG_MIGRATIONS } from "./sql.js";
 export { SUMMARY_COLUMNS, LIST_FILTER, LIST_SQL, COUNT_SQL, DETAIL_SQL, REFERENCE_PRICE, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL, HISTORY_SQL, HISTORY_COUNT_SQL } from "./bundleCatalogQueries.js";
 export { createPostgresCatalogSkuEnvelopeReadPort } from "./catalogSkuEnvelope.js";
 export { createPostgresCatalogDraftStore } from "./catalogDraftStore.js";
+export { selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";

package/dist/composition/index.d.ts

@@ -2,3 +2,5 @@ export { createBundleComposer, type ComposeBundle, type PlatformBundle, type Pla
 export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
 export { createNodeHost, type NodeHost, type NodeHostAdmission, type NodeHostDependencies, type NodeSchedulerProfile, type ServeNodeOptions, type ServeNodeResult, } from "./nodeHost.js";
 export { createCatalogContribution, type CatalogContributionInput } from "./catalogContribution.js";
+export { createInventoryContribution } from "./inventoryContribution.js";
+export { createShippingContribution } from "./shippingContribution.js";

package/dist/composition/index.js

@@ -2,3 +2,5 @@ export { createBundleComposer, } from "./composeBundle.js";
 export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
 export { createNodeHost, } from "./nodeHost.js";
 export { createCatalogContribution } from "./catalogContribution.js";
+export { createInventoryContribution } from "./inventoryContribution.js";
+export { createShippingContribution } from "./shippingContribution.js";

package/dist/composition/inventoryContribution.d.ts

@@ -0,0 +1,16 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Structural selected callables keep inventory and catalog declarations independent. */
+export declare function createInventoryContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    inventory: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+    routes: Contribution["routes"];
+}): {
+    contributions: Contribution[];
+    ports: {
+        [k: string]: ((...args: never[]) => unknown) | null;
+    };
+    routes: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+};