@openlup/platform 0.16.0 → 0.18.0

package/dist/catalog/bundleAvailabilityService.d.ts

@@ -0,0 +1,65 @@
+import type { BundleAvailability, BundleAvailabilityComponent } from "./bundleAvailability.js";
+import type { BundleStockPort as CommerceOfferAvailabilityPort } from "./bundleBindings.js";
+import type { ActiveBundleComposition, BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
+/**
+ * Derived bundle stock, composed from the two ports that already know the halves:
+ * the bundle read port knows the bill of materials, the EXISTING commerce offer
+ * availability port knows what a unit's stock is. Nothing here re-derives stock and
+ * nothing here opens a database handle.
+ *
+ * ONE BATCHED CALL, ALWAYS. Every component of every bundle in the request is
+ * asked for in a single `getAvailability`, deduplicated by sku, because the
+ * underlying port answers a set in three queries — asking per bundle would turn a
+ * catalogue listing into a query storm and would let two bundles sharing a unit
+ * disagree about its stock inside one response.
+ *
+ * A sku the availability port does not answer for is a MISSING figure, not zero:
+ * it is folded in as `sellableNow: null`, so the pure kernel reports the bundle as
+ * unknown and names the component rather than quietly overselling or hiding it.
+ */
+export interface BundleAvailabilityServiceDeps {
+    bundleCatalogReadPort: BundleCatalogReadPort;
+    offerAvailabilityPort: CommerceOfferAvailabilityPort;
+    /** Threshold handed to the pure kernel; its own default applies when omitted. */
+    lowStockThreshold?: number;
+    includeAddonsInStock?: boolean;
+}
+export interface BundleAvailabilityRow {
+    composition: ActiveBundleComposition;
+    availability: BundleAvailability;
+    /**
+     * The EXACT rows the kernel was given, carried out again rather than recomputed.
+     *
+     * The bundle-level answer names one limiting component; an operator staring at a bundle that
+     * cannot ship needs to know how far off every OTHER component is too, so they can tell "order one
+     * more of this" from "this bundle is months away". These rows are the only place that figure
+     * exists — the kernel folds them into a single number and the sellable feed's components carry
+     * price, never stock. Returning them costs nothing here and is the alternative to a second stock
+     * derivation somewhere that can disagree with this one.
+     */
+    components: readonly BundleAvailabilityComponent[];
+}
+export interface BundleAvailabilityService {
+    /** Fold stock into a set of compositions the caller already holds. */
+    describeCompositions(compositions: readonly ActiveBundleComposition[]): Promise<BundleAvailabilityRow[]>;
+    /** Read the live sellable set and fold stock into it. */
+    describeActiveBundles(input?: {
+        currency?: string;
+    }): Promise<BundleAvailabilityRow[]>;
+}
+export declare function createBundleAvailabilityServices({ deriveBundleAvailability }: {
+    deriveBundleAvailability: (input: import("./bundleAvailability.js").DeriveBundleAvailabilityInput) => BundleAvailability;
+}): {
+    createBundleAvailabilityService: (deps: BundleAvailabilityServiceDeps) => BundleAvailabilityService;
+};
+/**
+ * The port to use where no stock source is bound at all.
+ *
+ * It answers every item with `sellableNow: null`, which the kernel reads as
+ * unknown — so a deployment without an inventory rail publishes bundles whose
+ * price is exact and whose stock is honestly unstated. The alternative, omitting
+ * the availability block, would have made "we do not know" indistinguishable from
+ * "we did not ask", and the alternative to THAT — defaulting to available —
+ * oversells on a deployment that never counted anything.
+ */
+export declare function createUnknownOfferAvailabilityPort(): CommerceOfferAvailabilityPort;

package/dist/catalog/bundleAvailabilityService.js

@@ -0,0 +1,89 @@
+export function createBundleAvailabilityServices({ deriveBundleAvailability }) {
+    function createBundleAvailabilityService(deps) {
+        async function describeCompositions(compositions) {
+            if (compositions.length === 0)
+                return [];
+            const items = requestItems(compositions);
+            const stock = items.length === 0
+                ? new Map()
+                : sellableBySku(await deps.offerAvailabilityPort.getAvailability({ items }));
+            return compositions.map((composition) => {
+                const components = composition.components.map((component) => ({
+                    sku: component.sku,
+                    quantity: component.quantity,
+                    isAddon: component.isAddon,
+                    // `has` distinguishes "answered null" from "never answered"; both fold to
+                    // null, and neither is allowed to become a number here.
+                    sellableNow: stock.has(component.sku) ? (stock.get(component.sku) ?? null) : null,
+                }));
+                return {
+                    composition,
+                    components,
+                    availability: deriveBundleAvailability({
+                        components,
+                        lowStockThreshold: deps.lowStockThreshold,
+                        includeAddonsInStock: deps.includeAddonsInStock,
+                    }),
+                };
+            });
+        }
+        return {
+            describeCompositions,
+            async describeActiveBundles(input = {}) {
+                return describeCompositions(await deps.bundleCatalogReadPort.listActiveBundleCompositions(input));
+            },
+        };
+    }
+    return { createBundleAvailabilityService };
+}
+/**
+ * The port to use where no stock source is bound at all.
+ *
+ * It answers every item with `sellableNow: null`, which the kernel reads as
+ * unknown — so a deployment without an inventory rail publishes bundles whose
+ * price is exact and whose stock is honestly unstated. The alternative, omitting
+ * the availability block, would have made "we do not know" indistinguishable from
+ * "we did not ask", and the alternative to THAT — defaulting to available —
+ * oversells on a deployment that never counted anything.
+ */
+export function createUnknownOfferAvailabilityPort() {
+    return {
+        getAvailability({ items }) {
+            return Promise.resolve(items.map((item) => ({
+                sku: item.sku,
+                productSlug: item.productSlug,
+                variantId: item.variantId,
+                status: "unknown",
+                visibleInConfigurator: true,
+                sellableNow: null,
+                reasonCode: "stock_unknown",
+                source: "unbound",
+            })));
+        },
+    };
+}
+/**
+ * One request item per distinct sku across every bundle. `requestedQuantity` stays
+ * at the port's own default of one: the question asked is "how many units exist",
+ * and the multiplication by the bill of materials belongs to the pure kernel,
+ * which is the only place that knows how many bundles a figure buys.
+ */
+function requestItems(compositions) {
+    const bySku = new Map();
+    for (const composition of compositions) {
+        for (const component of composition.components) {
+            if (!bySku.has(component.sku))
+                bySku.set(component.sku, component);
+        }
+    }
+    return [...bySku.values()].map((component) => ({
+        sku: component.sku,
+        productSlug: component.productSlug,
+        variantId: component.variantId,
+        requestedQuantity: 1,
+        checkoutMode: "one_time",
+    }));
+}
+function sellableBySku(answers) {
+    return new Map(answers.map((answer) => [answer.sku, answer.sellableNow ?? null]));
+}

package/dist/catalog/bundleBindings.d.ts

@@ -0,0 +1,33 @@
+import type { BundleActorKind } from "./bundleRuleCodes.js";
+/** The host's normalized stock seam; no inventory implementation is owned here. */
+export type BundleStockStatus = "available" | "low_stock" | "out_of_stock" | "unknown";
+export interface BundleStockRequestItem {
+    sku: string;
+    productSlug: string;
+    variantId: string;
+    requestedQuantity: number;
+    checkoutMode: "one_time" | "subscription";
+}
+export interface BundleStockAvailability {
+    sku: string;
+    productSlug: string;
+    variantId: string;
+    status: BundleStockStatus;
+    visibleInConfigurator: boolean;
+    sellableNow: number | null;
+    reasonCode: string;
+    source: string;
+}
+export interface BundleStockPort {
+    getAvailability(input: {
+        items: readonly BundleStockRequestItem[];
+    }): Promise<BundleStockAvailability[]>;
+}
+export interface BundleRuleBindings {
+    assertActivateNotMachineActor(input: {
+        operation: string;
+        actorKind: BundleActorKind;
+    }): "DRAFT_ONLY_FOR_MACHINE" | null;
+    offerAvailabilityStatusFor(sellableNow: number | null, lowStockThreshold?: number): BundleStockStatus;
+    offerAvailabilityReasonCode(status: BundleStockStatus): string;
+}

package/dist/catalog/bundleBindings.js

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

package/dist/catalog/bundleCatalogQueries.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The statements the direct-Postgres bundle read adapter renders.
+ *
+ * They live beside the adapter rather than inside it because they are the part a
+ * reader comes here to check — which relations are touched, which columns are
+ * asked for, and how a component's reference price is resolved — and reading them
+ * should not mean scrolling past the row marshalling that consumes them.
+ */
+export declare const SUMMARY_COLUMNS = "\n  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)\n    AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p WHERE p.bundle_id = b.id AND p.active)\n    AS has_active_target_price";
+export declare const LIST_FILTER = "\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 || '%')";
+export declare const LIST_SQL = "SELECT \n  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)\n    AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p WHERE p.bundle_id = b.id AND p.active)\n    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";
+export declare const COUNT_SQL = "SELECT count(*) AS total 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 || '%')";
+export declare const DETAIL_SQL = "SELECT \n  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)\n    AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p WHERE p.bundle_id = b.id AND p.active)\n    AS has_active_target_price FROM public.catalog_bundles b WHERE b.code = $1";
+/**
+ * The unit's reference price in ONE named list: the lowest tier that is active,
+ * newest window first. A unit the list prices nothing for resolves to NULL rather
+ * than dropping the component, so a caller sees an unpriced part instead of a
+ * shorter bill of materials.
+ */
+export declare const REFERENCE_PRICE = "(\n  SELECT pe.unit_price_minor FROM public.price_entries pe\n   WHERE pe.variant_id = s.id AND pe.price_list_id = %LIST% AND pe.active\n   ORDER BY pe.min_qty ASC, pe.valid_from DESC LIMIT 1)";
+export declare const COMPONENT_SQL: string;
+export declare const FEED_COMPONENT_SQL: string;
+export declare const PRICE_SQL = "\n  SELECT p.mode, p.target_price_minor, list.currency, p.amount_kind, p.active,\n         p.valid_from, p.valid_to\n    FROM public.catalog_bundle_prices p\n    JOIN public.price_lists AS list ON list.id = p.price_list_id\n   WHERE p.bundle_id = $1::uuid\n   ORDER BY p.valid_from DESC";
+export declare const OWN_LIST_SQL = "\n  SELECT list.id, list.currency\n    FROM public.catalog_bundle_prices p\n    JOIN public.price_lists AS list ON list.id = p.price_list_id\n   WHERE p.bundle_id = $1::uuid AND p.active AND ($2::text IS NULL OR p.mode = $2::text)\n   ORDER BY p.valid_from DESC LIMIT 1";
+export declare const CURRENCY_LIST_SQL = "\n  SELECT id, currency FROM public.price_lists\n   WHERE currency = $1::text AND status = 'active'\n   ORDER BY created_at DESC LIMIT 1";
+export declare const FEED_SQL = "\n  SELECT b.id, b.code, b.title, b.fulfillment_mode, p.mode, p.target_price_minor,\n         p.price_list_id, list.currency\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 AS list ON list.id = p.price_list_id\n   WHERE b.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)\n   ORDER BY b.code, p.valid_from DESC";
+export declare const HISTORY_SQL = "\n  SELECT id, bundle_code, action, before_state, after_state, created_at\n    FROM public.catalog_bundle_write_events\n   WHERE bundle_code = $1::text\n   ORDER BY created_at DESC LIMIT $2 OFFSET $3";
+export declare const HISTORY_COUNT_SQL = "\n  SELECT count(*) AS total FROM public.catalog_bundle_write_events WHERE bundle_code = $1::text";

package/dist/catalog/bundleCatalogQueries.js

@@ -0,0 +1,84 @@
+/**
+ * The statements the direct-Postgres bundle read adapter renders.
+ *
+ * They live beside the adapter rather than inside it because they are the part a
+ * reader comes here to check — which relations are touched, which columns are
+ * asked for, and how a component's reference price is resolved — and reading them
+ * should not mean scrolling past the row marshalling that consumes them.
+ */
+export 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 WHERE p.bundle_id = b.id AND p.active)
+    AS has_active_target_price`;
+export const LIST_FILTER = `
+  WHERE ($1::text = 'all' OR b.status = $1::text)
+    AND ($2::text IS NULL OR b.code ILIKE '%' || $2 || '%' OR b.title ILIKE '%' || $2 || '%')`;
+export const LIST_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b ${LIST_FILTER}
+  ORDER BY b.code LIMIT $3 OFFSET $4`;
+export const COUNT_SQL = `SELECT count(*) AS total FROM public.catalog_bundles b ${LIST_FILTER}`;
+export const DETAIL_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b WHERE b.code = $1`;
+/**
+ * The unit's reference price in ONE named list: the lowest tier that is active,
+ * newest window first. A unit the list prices nothing for resolves to NULL rather
+ * than dropping the component, so a caller sees an unpriced part instead of a
+ * shorter bill of materials.
+ */
+export const REFERENCE_PRICE = `(
+  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
+   ORDER BY pe.min_qty ASC, pe.valid_from DESC LIMIT 1)`;
+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,
+         ${REFERENCE_PRICE.replace("%LIST%", "$2::uuid")} AS reference_unit_price_minor
+    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
+   WHERE c.bundle_id = $1::uuid
+   ORDER BY c.sort_order, s.sku`;
+// One statement for the whole feed: each bundle carries its own price list, so the
+// per-bundle list is zipped in rather than looped over.
+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,
+         ${REFERENCE_PRICE.replace("%LIST%", "selected.price_list_id")} AS reference_unit_price_minor
+    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
+   ORDER BY c.bundle_id, c.sort_order, s.sku`;
+export const PRICE_SQL = `
+  SELECT p.mode, 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 AS 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
+    FROM public.catalog_bundle_prices p
+    JOIN public.price_lists AS list ON list.id = p.price_list_id
+   WHERE p.bundle_id = $1::uuid AND p.active AND ($2::text IS NULL OR p.mode = $2::text)
+   ORDER BY p.valid_from DESC LIMIT 1`;
+export const CURRENCY_LIST_SQL = `
+  SELECT id, currency FROM public.price_lists
+   WHERE currency = $1::text AND status = 'active'
+   ORDER BY created_at DESC LIMIT 1`;
+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
+    FROM public.catalog_bundles b
+    JOIN public.catalog_bundle_prices p ON p.bundle_id = b.id AND p.active
+    JOIN public.price_lists AS list ON list.id = p.price_list_id
+   WHERE b.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)
+   ORDER BY b.code, p.valid_from DESC`;
+export const HISTORY_SQL = `
+  SELECT id, bundle_code, action, before_state, after_state, created_at
+    FROM public.catalog_bundle_write_events
+   WHERE bundle_code = $1::text
+   ORDER BY created_at DESC LIMIT $2 OFFSET $3`;
+export const HISTORY_COUNT_SQL = `
+  SELECT count(*) AS total FROM public.catalog_bundle_write_events WHERE bundle_code = $1::text`;

package/dist/catalog/bundleCatalogReadPort.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The semantic READ port for bundles.
+ *
+ * This file names the CAPABILITY, never the storage: no table, no routine, no
+ * data-client type and no vendor appears here, and the domain layer opens no
+ * database handle of its own. Both shipped read adapters implement exactly this
+ * interface and are proved against ONE shared scenario table, so a caller cannot
+ * tell them apart. It is the same shape the write port
+ * (`adminBundleWritePort.ts`) established in the previous wave.
+ *
+ * Reads are plain SELECTs rather than security-definer routines: the write
+ * boundary is where authority lives, and a read that re-implemented it would be a
+ * second place for the same rules to be written down. The admin surface reads the
+ * whole lifecycle (draft, active, archived); the sellable feed asks a separate
+ * question and gets only what is live.
+ *
+ * COMPONENT PRICES ARE RESOLVED, NOT STORED. A bundle stores one target price for
+ * the whole set; a component's REFERENCE unit price is whatever the selected
+ * price list says today. The adapters therefore join the catalogue and the price
+ * list themselves, and hand back a resolved figure (or `null` when the list
+ * prices nothing for that unit) so the allocator upstream never re-reads storage.
+ */
+/**
+ * A read that FAILED, as opposed to a read that found nothing.
+ *
+ * Both adapters raise this rather than returning an empty page, because the two
+ * outcomes are opposite: an empty catalogue is a fact a storefront may cache and
+ * show, and a failed query is not. The class lives on the port so neither chain
+ * owns the distinction.
+ */
+export declare class BundleCatalogReadError extends Error {
+    constructor(message: string);
+}
+/** Which lifecycle rows an admin list asks for. `all` is the admin default. */
+export type BundleListStatusFilter = "draft" | "active" | "archived" | "all";
+export interface ListBundlesInput {
+    status: BundleListStatusFilter;
+    /** Free-text match over code and title; absent means no narrowing. */
+    query?: string;
+    limit: number;
+    offset: number;
+}
+export interface BundleSummary {
+    code: string;
+    title: string;
+    status: string;
+    fulfillmentMode: string;
+    componentCount: number;
+    hasActiveTargetPrice: boolean;
+    updatedAt: string;
+}
+export interface ListBundlesResult {
+    bundles: BundleSummary[];
+    total: number;
+}
+/**
+ * One line of the bill of materials, already joined to the catalogue.
+ *
+ * `productSlug` and `variantId` are carried because the availability port
+ * addresses stock by all three coordinates; a caller that had only the sku would
+ * have to re-open the catalogue to ask about stock, which is exactly the
+ * round-trip this DTO exists to remove.
+ */
+export interface BundleComponentRow {
+    sku: string;
+    title: string | null;
+    productSlug: string;
+    variantId: string;
+    quantity: number;
+    isAddon: boolean;
+    sortOrder: number;
+    /** Resolved from the selected price list; `null` when it prices no such unit. */
+    referenceUnitPriceMinor: number | null;
+}
+export interface BundleTargetPriceRow {
+    mode: string;
+    targetPriceMinor: number;
+    currency: string;
+    amountKind: string;
+    active: boolean;
+    validFrom: string;
+    validTo: string | null;
+}
+export interface BundleDetail extends BundleSummary {
+    /** The opaque `{kind, version, data}` envelope; `null` for an unconstrained bundle. */
+    compositionConstraint: {
+        kind: string;
+        version: number;
+        data: Record<string, unknown>;
+    } | null;
+    metadata: Record<string, unknown>;
+    components: BundleComponentRow[];
+    prices: BundleTargetPriceRow[];
+    /** The currency whose list resolved `referenceUnitPriceMinor`; `null` if none did. */
+    resolvedCurrency: string | null;
+    /**
+     * The price list those reference figures came from. Carried because a price
+     * preview has to name the list it priced against — an amount without the list
+     * that gave it meaning is not reproducible.
+     */
+    resolvedPriceListId: string | null;
+}
+export interface GetBundleInput {
+    code: string;
+    /**
+     * Price the components against THIS currency's active list. Omitted means "the
+     * list this bundle's own active target price is written into", which is the
+     * only currency an operator has actually chosen for it.
+     */
+    currency?: string;
+    /** Narrow the target price whose list is selected; omitted means any mode. */
+    mode?: string;
+}
+/**
+ * One live, sellable bundle: active status, an active target price, and its
+ * components priced in that price's own currency. This is the feed's row, and it
+ * is deliberately a different question from `getBundle` — the storefront must
+ * never be able to see a draft by asking the read port nicely.
+ */
+export interface ActiveBundleComposition {
+    code: string;
+    title: string;
+    fulfillmentMode: string;
+    currency: string;
+    targetPriceMinor: number;
+    mode: string;
+    components: BundleComponentRow[];
+}
+export interface BundleHistoryEvent {
+    id: string;
+    action: string;
+    actorKind: string | null;
+    actorEmail: string | null;
+    entityId: string | null;
+    oldValue: unknown;
+    newValue: unknown;
+    occurredAt: string;
+}
+export interface BundleHistoryInput {
+    code: string;
+    limit: number;
+    offset: number;
+}
+export interface BundleHistoryResult {
+    events: BundleHistoryEvent[];
+    total: number;
+}
+export interface BundleCatalogReadPort {
+    /** Admin list across the whole lifecycle, newest-agnostic and code-ordered. */
+    listBundles(input: ListBundlesInput): Promise<ListBundlesResult>;
+    /** Full admin detail, or `null` when no bundle carries that code. */
+    getBundle(input: GetBundleInput): Promise<BundleDetail | null>;
+    /**
+     * Every bundle a storefront may sell right now. Never returns a draft or an
+     * archived bundle, and never a bundle without an active target price.
+     */
+    listActiveBundleCompositions(input?: {
+        currency?: string;
+    }): Promise<ActiveBundleComposition[]>;
+    /**
+     * The operator trail for one bundle. The two chains answer from different
+     * ledgers — a managed audit table and the platform's neutral write-event
+     * relation — which is why this is a port method rather than a shared query.
+     */
+    listBundleHistory(input: BundleHistoryInput): Promise<BundleHistoryResult>;
+}

package/dist/catalog/bundleCatalogReadPort.js

@@ -0,0 +1,36 @@
+/**
+ * The semantic READ port for bundles.
+ *
+ * This file names the CAPABILITY, never the storage: no table, no routine, no
+ * data-client type and no vendor appears here, and the domain layer opens no
+ * database handle of its own. Both shipped read adapters implement exactly this
+ * interface and are proved against ONE shared scenario table, so a caller cannot
+ * tell them apart. It is the same shape the write port
+ * (`adminBundleWritePort.ts`) established in the previous wave.
+ *
+ * Reads are plain SELECTs rather than security-definer routines: the write
+ * boundary is where authority lives, and a read that re-implemented it would be a
+ * second place for the same rules to be written down. The admin surface reads the
+ * whole lifecycle (draft, active, archived); the sellable feed asks a separate
+ * question and gets only what is live.
+ *
+ * COMPONENT PRICES ARE RESOLVED, NOT STORED. A bundle stores one target price for
+ * the whole set; a component's REFERENCE unit price is whatever the selected
+ * price list says today. The adapters therefore join the catalogue and the price
+ * list themselves, and hand back a resolved figure (or `null` when the list
+ * prices nothing for that unit) so the allocator upstream never re-reads storage.
+ */
+/**
+ * A read that FAILED, as opposed to a read that found nothing.
+ *
+ * Both adapters raise this rather than returning an empty page, because the two
+ * outcomes are opposite: an empty catalogue is a fact a storefront may cache and
+ * show, and a failed query is not. The class lives on the port so neither chain
+ * owns the distinction.
+ */
+export class BundleCatalogReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BundleCatalogReadError";
+    }
+}

package/dist/catalog/bundleCatalogStore.d.ts

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

package/dist/catalog/bundleCatalogStore.js

@@ -0,0 +1,152 @@
+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) {
+    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.
+        const result = await executor.query(sql, values).catch((error) => {
+            throw new BundleCatalogReadError(error instanceof Error ? error.message : String(error));
+        });
+        return (result.rows ?? []);
+    }
+    async function components(bundleId, priceListId) {
+        return (await rows(COMPONENT_SQL, [bundleId, priceListId])).map(toComponent);
+    }
+    async function selectPriceList(bundleId, input) {
+        const list = input.currency
+            ? await rows(CURRENCY_LIST_SQL, [input.currency])
+            : await rows(OWN_LIST_SQL, [bundleId, input.mode ?? null]);
+        return list[0] ?? null;
+    }
+    return {
+        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 list = await selectPriceList(bundle.id, input);
+            const [componentRows, priceRows] = await Promise.all([
+                components(bundle.id, list?.id ?? null),
+                rows(PRICE_SQL, [bundle.id]),
+            ]);
+            return {
+                ...toSummary(bundle),
+                compositionConstraint: toConstraint(bundle.composition_constraint),
+                metadata: bundle.metadata ?? {},
+                components: componentRows,
+                prices: priceRows.map(toPrice),
+                resolvedCurrency: list?.currency ?? null,
+                resolvedPriceListId: list?.id ?? null,
+            };
+        },
+        async listActiveBundleCompositions(input = {}) {
+            // A bundle may carry several active prices (a scheduled successor); the feed
+            // takes the newest window per bundle, which is what the ORDER BY already put first.
+            const selected = new Map();
+            for (const row of await rows(FEED_SQL, [input.currency ?? null])) {
+                if (!selected.has(row.id))
+                    selected.set(row.id, row);
+            }
+            if (selected.size === 0)
+                return [];
+            const chosen = [...selected.values()];
+            const byBundle = groupComponents(await rows(FEED_COMPONENT_SQL, [
+                chosen.map((row) => row.id),
+                chosen.map((row) => row.price_list_id),
+            ]));
+            return chosen.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) ?? [],
+            }));
+        },
+        async listBundleHistory(input) {
+            const [page, counted] = await Promise.all([
+                rows(HISTORY_SQL, [input.code, input.limit, input.offset]),
+                rows(HISTORY_COUNT_SQL, [input.code]),
+            ]);
+            return {
+                // This chain has no operator registry, so it can record WHICH principal
+                // wrote but never what kind of actor it was; both fields stay null rather
+                // than being invented from the principal id.
+                events: page.map((row) => ({
+                    id: row.id,
+                    action: row.action,
+                    actorKind: null,
+                    actorEmail: null,
+                    entityId: row.bundle_code,
+                    oldValue: row.before_state ?? null,
+                    newValue: row.after_state ?? null,
+                    occurredAt: row.created_at,
+                })),
+                total: Number(counted[0]?.total ?? page.length),
+            };
+        },
+    };
+}
+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) {
+    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 ?? {}),
+    };
+}