@openlup/platform 0.17.0 → 0.18.0

package/dist/catalog/adminBundleHandler.js

@@ -0,0 +1,111 @@
+import { evaluateBundleComposition, evaluateBundleCompositionConstraint, evaluateBundleFulfillmentMode } from "./bundleRules.js";
+export function createAdminBundleHandlers({ bundleSpec, BundleRpcError, COMMERCE_CONTRACT_VERSION, createAdminMutationHandler }) {
+    /**
+     * Bundle write handlers — each is the generic kit factory
+     * `createAdminMutationHandler` driven by one operation of `bundleSpec`. The
+     * factory owns the shared spine (POST-only, flag gate, admin authz, DB-derived
+     * actor-kind gate, contract parse, error map, success envelope); this module only
+     * injects the request-scoped port call, the envelope shape and the two pure rule
+     * passes that are decidable before the write.
+     */
+    const BUNDLE_DISABLED = "Bundle writes are disabled";
+    const BUNDLE_INVALID = "Invalid bundle write request";
+    const BUNDLE_FAILURE = "Bundle write failed";
+    /** Bundle success envelope; only the fields the operation actually produced. */
+    function bundleResponse(result) {
+        return {
+            contractVersion: COMMERCE_CONTRACT_VERSION,
+            dryRun: result.dryRun,
+            idempotent: result.idempotent,
+            ...(result.code ? { code: result.code } : {}),
+            ...(result.bundleId ? { bundleId: result.bundleId } : {}),
+            ...(result.componentCount === undefined ? {} : { componentCount: result.componentCount }),
+        };
+    }
+    /** A request-layer rule refusal, mapped onto the same envelope the boundary uses. */
+    function ruleRefusal(violations) {
+        return new BundleRpcError("P0001", violations.join(","));
+    }
+    function buildBundleHandler(deps, mutationKey, invoke) {
+        const mutation = bundleSpec.mutations[mutationKey];
+        const isActivation = mutation.gate === "activation";
+        return createAdminMutationHandler({
+            mutation,
+            flagName: isActivation ? bundleSpec.activationFlag : bundleSpec.mutationFlag,
+            enabled: isActivation ? deps.activationEnabled : deps.mutationsEnabled,
+            authorizeAdmin: deps.authorizeAdmin,
+            invoke: (actorId, input) => invoke(deps.writePort, actorId, input),
+            toResponse: bundleResponse,
+            disabledMessage: BUNDLE_DISABLED,
+            invalidRequestMessage: BUNDLE_INVALID,
+            failureMessage: BUNDLE_FAILURE,
+        });
+    }
+    function createAdminBundleCreateDraftHandler(deps) {
+        return buildBundleHandler(deps, "create", (port, actorId, input) => {
+            const mode = evaluateBundleFulfillmentMode(input.bundle.fulfillmentMode);
+            if (!mode.ok)
+                return Promise.reject(ruleRefusal(mode.violations));
+            return port.upsertDraft(actorId, input);
+        });
+    }
+    function createAdminBundleUpdateDraftHandler(deps) {
+        return buildBundleHandler(deps, "update", (port, actorId, input) => {
+            const requested = input.updates.fulfillmentMode;
+            if (requested !== undefined) {
+                const mode = evaluateBundleFulfillmentMode(requested);
+                if (!mode.ok)
+                    return Promise.reject(ruleRefusal(mode.violations));
+            }
+            return port.updateDraft(actorId, input);
+        });
+    }
+    /**
+     * Whole-set composition replace. Two pure passes run before the write: the set
+     * rules that are decidable from the request alone (at least one component, at
+     * least one non-add-on, no unit twice), and — when the bundle carries a non-empty
+     * constraint envelope — the adopter's own `CompositionRulesPort`. The write
+     * boundary re-derives everything it can see and refuses independently.
+     */
+    function createAdminBundleSetCompositionHandler(deps) {
+        return buildBundleHandler(deps, "setComposition", async (port, actorId, input) => {
+            const composition = evaluateBundleComposition(input.components);
+            if (!composition.ok)
+                throw ruleRefusal(composition.violations);
+            const constraint = await evaluateBundleCompositionConstraint(deps.compositionRules, {
+                components: input.components,
+                constraint: await port.loadCompositionConstraint(input.code),
+            });
+            if (!constraint.ok)
+                throw ruleRefusal(constraint.violations);
+            return port.setComposition(actorId, input);
+        });
+    }
+    function createAdminBundleSetTargetPriceHandler(deps) {
+        return buildBundleHandler(deps, "setTargetPrice", (port, actorId, input) => port.setTargetPrice(actorId, input));
+    }
+    function createAdminBundleArchiveHandler(deps) {
+        return buildBundleHandler(deps, "archive", (port, actorId, input) => port.archive(actorId, input));
+    }
+    function createAdminBundleRestoreHandler(deps) {
+        return buildBundleHandler(deps, "restore", (port, actorId, input) => port.restore(actorId, input));
+    }
+    function createAdminBundleCloneDraftHandler(deps) {
+        return buildBundleHandler(deps, "cloneDraft", (port, actorId, input) => port.cloneDraft(actorId, input));
+    }
+    /**
+     * Activate (publish) — HUMAN-ONLY. The mutation's gate is `activation`, so the
+     * factory wires it to the activation flag and refuses a machine actor (403) from
+     * `allowedActorKinds` before the write is ever reached. The managed write routine
+     * also RAISEs 42501 as a second layer; the native routine has no independent
+     * actor-kind gate and relies on this handler gate.
+     */
+    function createAdminBundleActivateHandler(deps) {
+        return buildBundleHandler(deps, "activate", (port, actorId, input) => port.activate(actorId, input));
+    }
+    /** Deactivate (unpublish) — HUMAN-ONLY, gated identically to activate. */
+    function createAdminBundleDeactivateHandler(deps) {
+        return buildBundleHandler(deps, "deactivate", (port, actorId, input) => port.deactivate(actorId, input));
+    }
+    return { createAdminBundleCreateDraftHandler, createAdminBundleUpdateDraftHandler, createAdminBundleSetCompositionHandler, createAdminBundleSetTargetPriceHandler, createAdminBundleArchiveHandler, createAdminBundleRestoreHandler, createAdminBundleCloneDraftHandler, createAdminBundleActivateHandler, createAdminBundleDeactivateHandler };
+}

package/dist/catalog/adminBundleReadHandler.d.ts

@@ -0,0 +1,20 @@
+import type { BundleAdminBindings, AuthorizeAdmin } from "./adminBindings.js";
+import type { BundleAvailabilityService } from "./bundleAvailabilityService.js";
+import type { BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
+export interface AdminBundleReadHandlerDeps {
+    readPort: BundleCatalogReadPort;
+    authorizeAdmin: AuthorizeAdmin;
+    readsEnabled: boolean;
+    /**
+     * Derived stock for the detail response. OPTIONAL, and absence is reported as a null
+     * `availability` rather than as an omitted field or a zero: a deployment with no stock rail has
+     * not counted anything, and saying so is different from saying nothing can ship.
+     */
+    availabilityService?: BundleAvailabilityService;
+}
+export declare function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMMERCE_CONTRACT_VERSION, createAdminParameterizedReadHandler, bundleHistoryResponseSchema, getBundleResponseSchema, listBundlesResponseSchema, previewBundlePriceResponseSchema }: Pick<BundleAdminBindings, "bundleSpec" | "BundleRpcError" | "COMMERCE_CONTRACT_VERSION" | "createAdminParameterizedReadHandler" | "bundleHistoryResponseSchema" | "getBundleResponseSchema" | "listBundlesResponseSchema" | "previewBundlePriceResponseSchema">): {
+    createAdminBundleListHandler: (deps: AdminBundleReadHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleGetHandler: (deps: AdminBundleReadHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundleHistoryHandler: (deps: AdminBundleReadHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminBundlePreviewPriceHandler: (deps: AdminBundleReadHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+};

package/dist/catalog/adminBundleReadHandler.js

@@ -0,0 +1,185 @@
+import { allocateBundleTargetPrice } from "@openlup/core/pricing";
+export function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMMERCE_CONTRACT_VERSION, createAdminParameterizedReadHandler, bundleHistoryResponseSchema, getBundleResponseSchema, listBundlesResponseSchema, previewBundlePriceResponseSchema }) {
+    /**
+     * Bundle READ handlers — each is the generic kit factory
+     * `createAdminParameterizedReadHandler` driven by one query of `bundleSpec`. The
+     * factory owns the shared spine (GET-only, flag gate, admin authz, DB-derived
+     * actor-kind gate, query parse, error map, response validation, success
+     * envelope); this module only injects the read-port call and the response shape.
+     * It mirrors `adminBundleHandler.ts`, and the catalog reference
+     * (`server/domains/commerce/adminCatalogReadHandler.ts`) is the shape both follow.
+     *
+     * The price preview is the one read that computes: it runs the SAME pricing kernel
+     * the write boundary refuses against (`allocateBundleTargetPrice`) over TODAY's
+     * component prices, so an operator can see the money before committing to it. Its
+     * three refusal codes are mapped onto the same envelope a refused write produces,
+     * because they are the same three decisions.
+     */
+    const BUNDLE_READ_DISABLED = "Bundle reads are disabled";
+    const BUNDLE_READ_INVALID = "Invalid bundle read request";
+    const BUNDLE_READ_FAILURE = "Bundle read failed";
+    function query(key) {
+        const spec = bundleSpec.queries?.[key];
+        if (!spec)
+            throw new Error(`bundleSpec.queries.${key} is not defined`);
+        return spec;
+    }
+    function gate(deps, key, load, toResponse, responseSchema, invalidResponseMessage) {
+        return createAdminParameterizedReadHandler({
+            query: query(key),
+            flagName: bundleSpec.readFlag,
+            enabled: deps.readsEnabled,
+            authorizeAdmin: deps.authorizeAdmin,
+            load: (_actorId, input) => load(deps.readPort, input),
+            toResponse,
+            responseSchema,
+            disabledMessage: BUNDLE_READ_DISABLED,
+            invalidRequestMessage: BUNDLE_READ_INVALID,
+            invalidResponseMessage,
+            failureMessage: BUNDLE_READ_FAILURE,
+        });
+    }
+    function createAdminBundleListHandler(deps) {
+        return gate(deps, "list", (port, input) => port.listBundles(input), (data) => ({
+            contractVersion: COMMERCE_CONTRACT_VERSION,
+            bundles: data.bundles,
+            total: data.total,
+        }), listBundlesResponseSchema, "Invalid bundle list response");
+    }
+    function createAdminBundleGetHandler(deps) {
+        return gate(deps, "get", async (port, input) => {
+            const bundle = await port.getBundle(input);
+            // Absent is NOT an empty detail: the same P0002 the write boundary raises,
+            // so a missing bundle answers 404 through one map rather than two.
+            if (!bundle)
+                throw new BundleRpcError("P0002", "bundle_not_found");
+            return { bundle, stock: await describeStock(deps, bundle) };
+        }, ({ bundle, stock }) => ({
+            contractVersion: COMMERCE_CONTRACT_VERSION,
+            bundle: toDetailView(bundle, stock),
+        }), getBundleResponseSchema, "Invalid bundle detail response");
+    }
+    /**
+     * Fold stock into ONE bundle, through the same service the public feed uses.
+     *
+     * The service takes compositions and this is a detail, but the two carry the identical component
+     * row type, so the adaptation is a rename rather than a translation — and routing this read through
+     * the shared service is the point: `deriveBundleAvailability` stays the single place that folds
+     * units into bundles, so an operator's detail page and a shopper's feed can never disagree about
+     * the same bundle.
+     *
+     * A bundle whose status is not live is NOT skipped here. That is the whole gain over the feed: the
+     * feed is live-only by construction, so a draft had no derived stock anywhere, and an operator
+     * about to activate one could not see whether it would ship.
+     */
+    async function describeStock(deps, bundle) {
+        if (!deps.availabilityService)
+            return null;
+        const [row] = await deps.availabilityService.describeCompositions([
+            {
+                code: bundle.code,
+                title: bundle.title,
+                fulfillmentMode: bundle.fulfillmentMode,
+                // Stated from what the detail resolved. Neither reaches the stock question — the service
+                // asks the availability port for units, never for money — but the shape is the contract and
+                // inventing a currency here would be a lie in a field somebody may later read.
+                currency: bundle.resolvedCurrency ?? "",
+                targetPriceMinor: 0,
+                mode: "any",
+                components: bundle.components,
+            },
+        ]);
+        return row ?? null;
+    }
+    function createAdminBundleHistoryHandler(deps) {
+        return gate(deps, "history", (port, input) => port.listBundleHistory(input), (data) => ({
+            contractVersion: COMMERCE_CONTRACT_VERSION,
+            events: data.events,
+            total: data.total,
+        }), bundleHistoryResponseSchema, "Invalid bundle history response");
+    }
+    function createAdminBundlePreviewPriceHandler(deps) {
+        return gate(deps, "previewPrice", async (port, input) => {
+            const bundle = await port.getBundle({
+                code: input.code,
+                currency: input.currency,
+                mode: input.mode,
+            });
+            if (!bundle)
+                throw new BundleRpcError("P0002", "bundle_not_found");
+            return previewBundlePrice(bundle, input);
+        }, (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. */
+    function toDetailView(bundle, stock) {
+        const { components, resolvedPriceListId: _priceListId, ...rest } = bundle;
+        return {
+            ...rest,
+            components: components.map(({ variantId: _variantId, ...component }) => component),
+            availability: stock
+                ? {
+                    sellableNow: stock.availability.sellableNow,
+                    status: stock.availability.status,
+                    reasonCode: stock.availability.reasonCode,
+                    limitingSku: stock.availability.limitingSku,
+                    components: stock.components.map((component) => ({
+                        sku: component.sku,
+                        quantity: component.quantity,
+                        isAddon: component.isAddon,
+                        sellableNow: component.sellableNow,
+                    })),
+                }
+                : null,
+        };
+    }
+    /**
+     * Run the pricing kernel over the bundle's live component prices.
+     *
+     * Every refusal is stated as the same rule violation a write would produce, so an
+     * operator previewing a price and an operator setting it are told the same thing:
+     * 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) {
+        if (!bundle.resolvedPriceListId || !bundle.resolvedCurrency) {
+            throw new BundleRpcError("P0002", "no_active_price_list");
+        }
+        const counted = bundle.components;
+        if (counted.length === 0)
+            throw new BundleRpcError("P0001", "min_components");
+        const unpriced = counted.filter((component) => component.referenceUnitPriceMinor === null);
+        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 targetPriceMinor = input.targetPriceMinor ?? activePrice?.targetPriceMinor;
+        if (targetPriceMinor === undefined)
+            throw new BundleRpcError("P0002", "no_active_target_price");
+        const allocation = allocateBundleTargetPrice({
+            components: counted.map((component) => ({
+                sku: component.sku,
+                quantity: component.quantity,
+                unitPriceMinor: component.referenceUnitPriceMinor,
+            })),
+            targetPriceMinor,
+        });
+        // The narrowing is written out rather than relied upon: the Node tsconfig runs
+        // without strictNullChecks, where a discriminated union does not narrow on `ok`.
+        if (!allocation.ok)
+            throw new BundleRpcError("P0001", allocation.code);
+        return {
+            bundleCode: bundle.code,
+            priceListId: bundle.resolvedPriceListId,
+            mode: input.mode ?? activePrice?.mode ?? "any",
+            currency: bundle.resolvedCurrency,
+            referenceTotalMinor: allocation.referenceTotalMinor,
+            targetPriceMinor: allocation.targetPriceMinor,
+            discountTotalMinor: allocation.discountTotalMinor,
+            discountBps: allocation.discountBps,
+            floorApplied: allocation.floorApplied,
+            componentTargets: allocation.components,
+            allocatedLines: allocation.lines,
+        };
+    }
+    return { createAdminBundleListHandler, createAdminBundleGetHandler, createAdminBundleHistoryHandler, createAdminBundlePreviewPriceHandler };
+}

package/dist/catalog/adminBundleWritePort.d.ts

@@ -0,0 +1,85 @@
+import type { CreateBundleDraftRequest, SetBundleCompositionRequest, SetBundleTargetPriceRequest, UpdateBundleDraftRequest } from "./contracts/bundleAdmin.js";
+import type { ActivateBundleRequest, ArchiveBundleRequest, CloneBundleDraftRequest, DeactivateBundleRequest, RestoreBundleRequest } from "./contracts/bundleAdmin.js";
+/**
+ * The semantic write port for the admin/agent bundle surface.
+ *
+ * This file names the CAPABILITY, never the storage. Both shipped write adapters
+ * implement exactly this interface and are proved against ONE shared scenario table, so a caller cannot
+ * tell them apart and neither can a rule. No data-client type, table name or
+ * routine name appears here; the domain layer opens no database handle of its own.
+ *
+ * Each method is one atomic operation on the security boundary: the boundary takes
+ * the actor explicitly; the managed chain re-derives actor kind, while native
+ * relies on the handler human-only gate. Each boundary writes its ledger row in the same transaction, short-circuits a replayed
+ * idempotency key, and validates a dry run without durable writes.
+ */
+/** Shape every bundle write returns. */
+export interface BundleWriteResult {
+    idempotent: boolean;
+    dryRun: boolean;
+    code?: string;
+    bundleId?: string;
+    componentCount?: number;
+}
+/** The opaque rules envelope a bundle carries, as the boundary hands it back. */
+export interface BundleCompositionConstraintEnvelope {
+    kind: string;
+    version: number;
+    data: Record<string, unknown>;
+}
+export interface AdminBundleWritePort {
+    /**
+     * Read the bundle's stored composition constraint. This is a WRITE-path read: the
+     * whole-set replace must be validated against the envelope the bundle already
+     * carries before anything is written, and the adopter's `CompositionRulesPort` is
+     * the only thing that can decide it. Returns `null` for an unconstrained bundle.
+     * Raises P0002 when the bundle does not exist.
+     */
+    loadCompositionConstraint(code: string): Promise<BundleCompositionConstraintEnvelope | null>;
+    /** Create or edit a DRAFT bundle from a full structural payload. */
+    upsertDraft(actorId: string, input: CreateBundleDraftRequest): Promise<BundleWriteResult>;
+    /**
+     * Partial structural edit of a DRAFT bundle. The upsert is full-payload, so this
+     * reads the current bundle, overlays the supplied fields and replays the merged
+     * payload through the same boundary. Raises NOT_FOUND (P0002) when the bundle
+     * does not exist.
+     */
+    updateDraft(actorId: string, input: UpdateBundleDraftRequest): Promise<BundleWriteResult>;
+    /**
+     * Replace the bill of materials as a WHOLE SET, atomically. Raises P0002 when the
+     * bundle or a named unit is missing, and P0001 when a unit is not sellable on its
+     * own or is priced in another currency.
+     */
+    setComposition(actorId: string, input: SetBundleCompositionRequest): Promise<BundleWriteResult>;
+    /**
+     * Append a new active target price and close the previous one. Never mutates an
+     * existing row. Raises P0001 when the target sits above the sum of the parts or
+     * below the floor every component must clear.
+     */
+    setTargetPrice(actorId: string, input: SetBundleTargetPriceRequest): Promise<BundleWriteResult>;
+    /** Remove a bundle from sale (status flip, never a hard delete). P0002 when missing. */
+    archive(actorId: string, input: ArchiveBundleRequest): Promise<BundleWriteResult>;
+    /**
+     * Restore an archived bundle to draft. Raises P0002 when missing and P0001
+     * (`restore_requires_archived`) when the bundle is not archived.
+     */
+    restore(actorId: string, input: RestoreBundleRequest): Promise<BundleWriteResult>;
+    /**
+     * Clone any bundle into a NEW draft under a new code, including its composition.
+     * Raises P0002 (`clone_source_not_found`) when the source is missing and P0001
+     * when the target code is already taken.
+     */
+    cloneDraft(actorId: string, input: CloneBundleDraftRequest): Promise<BundleWriteResult>;
+    /**
+     * Publish (draft -> active). HUMAN-ONLY: the managed chain raises 42501
+     * (`publish_requires_human`) for machine actors; native relies on the handler gate. Raises P0001 when the bundle has
+     * no composition or no active target price.
+     */
+    activate(actorId: string, input: ActivateBundleRequest): Promise<BundleWriteResult>;
+    /**
+     * Unpublish (active -> draft). HUMAN-ONLY: the managed chain uses the same
+     * 42501 refusal; native relies on the handler gate. Raises P0001
+     * (`deactivate_requires_active`) when the bundle is not live.
+     */
+    deactivate(actorId: string, input: DeactivateBundleRequest): Promise<BundleWriteResult>;
+}

package/dist/catalog/adminBundleWritePort.js

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

package/dist/catalog/bundleAvailability.d.ts

@@ -0,0 +1,63 @@
+import type { BundleRuleBindings, BundleStockStatus as CommerceOfferAvailabilityStatus } from "./bundleBindings.js";
+/**
+ * Derived stock for a composed bundle — the pure kernel that folds many component
+ * stock figures into ONE answer about the bundle.
+ *
+ * A bundle is only as sellable as its scarcest counted part: with a bill of
+ * materials of `quantity` units per component, the number of whole bundles that
+ * can ship is `min(floor(component.sellableNow / component.quantity))`. That
+ * component is named (`limitingSku`) so an operator learns WHICH part is the
+ * constraint instead of only that there is one.
+ *
+ * FAIL TO UNKNOWN, NEVER GUESS. If any counted component's stock is itself
+ * unknown, the bundle's stock is unknown — not the minimum of the parts that did
+ * answer. Treating a missing figure as unlimited oversells; treating it as zero
+ * hides a sellable bundle. Both are decisions this module refuses to make, so it
+ * reports `unknown` and names the component whose figure is missing.
+ *
+ * The status ladder and the reason-code vocabulary are IMPORTED from the commerce
+ * domain's PUBLIC port seam rather than restated, so a bundle and a single unit
+ * can never disagree about what `low_stock` means.
+ *
+ * Pure: integer arithmetic, no clock, no randomness, no I/O.
+ */
+/**
+ * Threshold below which a bundle reads as `low_stock`. Deliberately far under the
+ * single-unit default: a bundle consumes several units per sale, so the same raw
+ * stock represents far fewer bundles and a unit-scale threshold would report
+ * nearly every bundle as low.
+ */
+export declare const DEFAULT_BUNDLE_LOW_STOCK_THRESHOLD = 3;
+/** A counted component answered with no figure at all. */
+export declare const BUNDLE_COMPONENT_STOCK_UNKNOWN = "component_stock_unknown";
+/** Nothing was counted — no non-add-on component to derive an answer from. */
+export declare const BUNDLE_COMPOSITION_EMPTY = "bundle_composition_empty";
+export interface BundleAvailabilityComponent {
+    sku: string;
+    /** Units of this component consumed by ONE bundle; always positive. */
+    quantity: number;
+    isAddon: boolean;
+    /** Sellable units of the component, or `null` when the figure is unknown. */
+    sellableNow: number | null;
+}
+export interface BundleAvailability {
+    /** Whole bundles that can ship now, or `null` when any counted part is unknown. */
+    sellableNow: number | null;
+    status: CommerceOfferAvailabilityStatus;
+    reasonCode: string;
+    /** The component that decided the answer; `null` only when nothing was counted. */
+    limitingSku: string | null;
+}
+export interface DeriveBundleAvailabilityInput {
+    components: readonly BundleAvailabilityComponent[];
+    lowStockThreshold?: number;
+    /**
+     * Add-ons are excluded by default: an add-on is priced into the bundle but
+     * optional in composition, so its stock must not make the bundle unsellable.
+     * An operator who sells the add-on as mandatory opts in here.
+     */
+    includeAddonsInStock?: boolean;
+}
+export declare function createBundleAvailability({ offerAvailabilityReasonCode, offerAvailabilityStatusFor }: Pick<BundleRuleBindings, "offerAvailabilityReasonCode" | "offerAvailabilityStatusFor">): {
+    deriveBundleAvailability: (input: DeriveBundleAvailabilityInput) => BundleAvailability;
+};

package/dist/catalog/bundleAvailability.js

@@ -0,0 +1,78 @@
+/**
+ * Derived stock for a composed bundle — the pure kernel that folds many component
+ * stock figures into ONE answer about the bundle.
+ *
+ * A bundle is only as sellable as its scarcest counted part: with a bill of
+ * materials of `quantity` units per component, the number of whole bundles that
+ * can ship is `min(floor(component.sellableNow / component.quantity))`. That
+ * component is named (`limitingSku`) so an operator learns WHICH part is the
+ * constraint instead of only that there is one.
+ *
+ * FAIL TO UNKNOWN, NEVER GUESS. If any counted component's stock is itself
+ * unknown, the bundle's stock is unknown — not the minimum of the parts that did
+ * answer. Treating a missing figure as unlimited oversells; treating it as zero
+ * hides a sellable bundle. Both are decisions this module refuses to make, so it
+ * reports `unknown` and names the component whose figure is missing.
+ *
+ * The status ladder and the reason-code vocabulary are IMPORTED from the commerce
+ * domain's PUBLIC port seam rather than restated, so a bundle and a single unit
+ * can never disagree about what `low_stock` means.
+ *
+ * Pure: integer arithmetic, no clock, no randomness, no I/O.
+ */
+/**
+ * Threshold below which a bundle reads as `low_stock`. Deliberately far under the
+ * single-unit default: a bundle consumes several units per sale, so the same raw
+ * stock represents far fewer bundles and a unit-scale threshold would report
+ * nearly every bundle as low.
+ */
+export const DEFAULT_BUNDLE_LOW_STOCK_THRESHOLD = 3;
+/** A counted component answered with no figure at all. */
+export const BUNDLE_COMPONENT_STOCK_UNKNOWN = "component_stock_unknown";
+/** Nothing was counted — no non-add-on component to derive an answer from. */
+export const BUNDLE_COMPOSITION_EMPTY = "bundle_composition_empty";
+export function createBundleAvailability({ offerAvailabilityReasonCode, offerAvailabilityStatusFor }) {
+    function deriveBundleAvailability(input) {
+        const counted = input.components.filter((component) => input.includeAddonsInStock === true || !component.isAddon);
+        if (counted.length === 0) {
+            return {
+                sellableNow: null,
+                status: "unknown",
+                reasonCode: BUNDLE_COMPOSITION_EMPTY,
+                limitingSku: null,
+            };
+        }
+        // Unknown wins over every figure that did answer, and the named component is the
+        // lowest sku among the unknown ones, so the same set always names the same part.
+        const unknown = counted.filter((component) => component.sellableNow === null);
+        if (unknown.length > 0) {
+            return {
+                sellableNow: null,
+                status: "unknown",
+                reasonCode: BUNDLE_COMPONENT_STOCK_UNKNOWN,
+                limitingSku: lowestSku(unknown),
+            };
+        }
+        let limiting = counted[0];
+        let sellableNow = wholeBundles(counted[0]);
+        for (const component of counted.slice(1)) {
+            const candidate = wholeBundles(component);
+            // Strictly lower wins; an exact tie is broken by ascending sku code units, so
+            // the named component never depends on the order the composition was read in.
+            if (candidate < sellableNow || (candidate === sellableNow && component.sku < limiting.sku)) {
+                limiting = component;
+                sellableNow = candidate;
+            }
+        }
+        const status = offerAvailabilityStatusFor(sellableNow, input.lowStockThreshold ?? DEFAULT_BUNDLE_LOW_STOCK_THRESHOLD);
+        return { sellableNow, status, reasonCode: offerAvailabilityReasonCode(status), limitingSku: limiting.sku };
+    }
+    return { deriveBundleAvailability };
+}
+/** Whole bundles this component alone can carry. */
+function wholeBundles(component) {
+    return Math.floor((component.sellableNow ?? 0) / component.quantity);
+}
+function lowestSku(components) {
+    return components.reduce((lowest, component) => (component.sku < lowest ? component.sku : lowest), components[0].sku);
+}

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;