@openlup/platform 0.17.0 → 0.19.0

package/src/catalog/adminBundleHandler.ts

@@ -0,0 +1,165 @@
+import type { BundleAdminBindings, AuthorizeAdmin, AgentDomainMutationSpec, BundleMutationKey } from "./adminBindings.js";
+import type { CompositionRulesPort } from "@openlup/core/bundle";
+import { evaluateBundleComposition, evaluateBundleCompositionConstraint, evaluateBundleFulfillmentMode } from "./bundleRules.js";
+import type { AdminBundleWritePort, BundleWriteResult } from "./adminBundleWritePort.js";
+import type { CreateBundleDraftRequest, SetBundleCompositionRequest, SetBundleTargetPriceRequest, UpdateBundleDraftRequest, ActivateBundleRequest, ArchiveBundleRequest, CloneBundleDraftRequest, DeactivateBundleRequest, RestoreBundleRequest } from "./contracts/bundleAdmin.js";
+
+export interface AdminBundleHandlerDeps {
+  writePort: AdminBundleWritePort;
+  authorizeAdmin: AuthorizeAdmin;
+  mutationsEnabled: boolean;
+  activationEnabled: boolean;
+  /**
+   * The adopter's composition rules. Supplied only where a composition constraint
+   * can be attached; when absent, a non-empty envelope is stored unvalidated, which
+   * is what "the platform never interprets it" means.
+   */
+  compositionRules?: CompositionRulesPort;
+}
+
+export function createAdminBundleHandlers({ bundleSpec, BundleRpcError, COMMERCE_CONTRACT_VERSION, createAdminMutationHandler }: Pick<BundleAdminBindings, "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: BundleWriteResult): Record<string, unknown> {
+  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: readonly string[]): InstanceType<BundleAdminBindings["BundleRpcError"]> {
+  return new BundleRpcError("P0001", violations.join(","));
+}
+
+function buildBundleHandler<TReq>(
+  deps: AdminBundleHandlerDeps,
+  mutationKey: BundleMutationKey,
+  invoke: (port: AdminBundleWritePort, actorId: string, input: TReq) => Promise<BundleWriteResult>,
+) {
+  const mutation = bundleSpec.mutations[mutationKey] as AgentDomainMutationSpec<TReq>;
+  const isActivation = mutation.gate === "activation";
+  return createAdminMutationHandler<TReq, BundleWriteResult>({
+    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: AdminBundleHandlerDeps) {
+  return buildBundleHandler<CreateBundleDraftRequest>(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: AdminBundleHandlerDeps) {
+  return buildBundleHandler<UpdateBundleDraftRequest>(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: AdminBundleHandlerDeps) {
+  return buildBundleHandler<SetBundleCompositionRequest>(
+    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: AdminBundleHandlerDeps) {
+  return buildBundleHandler<SetBundleTargetPriceRequest>(
+    deps,
+    "setTargetPrice",
+    (port, actorId, input) => port.setTargetPrice(actorId, input),
+  );
+}
+
+function createAdminBundleArchiveHandler(deps: AdminBundleHandlerDeps) {
+  return buildBundleHandler<ArchiveBundleRequest>(deps, "archive", (port, actorId, input) =>
+    port.archive(actorId, input),
+  );
+}
+
+function createAdminBundleRestoreHandler(deps: AdminBundleHandlerDeps) {
+  return buildBundleHandler<RestoreBundleRequest>(deps, "restore", (port, actorId, input) =>
+    port.restore(actorId, input),
+  );
+}
+
+function createAdminBundleCloneDraftHandler(deps: AdminBundleHandlerDeps) {
+  return buildBundleHandler<CloneBundleDraftRequest>(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: AdminBundleHandlerDeps) {
+  return buildBundleHandler<ActivateBundleRequest>(deps, "activate", (port, actorId, input) =>
+    port.activate(actorId, input),
+  );
+}
+
+/** Deactivate (unpublish) — HUMAN-ONLY, gated identically to activate. */
+function createAdminBundleDeactivateHandler(deps: AdminBundleHandlerDeps) {
+  return buildBundleHandler<DeactivateBundleRequest>(deps, "deactivate", (port, actorId, input) =>
+    port.deactivate(actorId, input),
+  );
+}
+
+return { createAdminBundleCreateDraftHandler, createAdminBundleUpdateDraftHandler, createAdminBundleSetCompositionHandler, createAdminBundleSetTargetPriceHandler, createAdminBundleArchiveHandler, createAdminBundleRestoreHandler, createAdminBundleCloneDraftHandler, createAdminBundleActivateHandler, createAdminBundleDeactivateHandler };
+}

package/src/catalog/adminBundleReadHandler.ts

@@ -0,0 +1,263 @@
+import type { BundleAdminBindings, AuthorizeAdmin, AgentDomainQuerySpec, BundleQueryKey } from "./adminBindings.js";
+import { allocateBundleTargetPrice, type BundleAllocationFailure } from "@openlup/core/pricing";
+import type { BundleHistoryRequest, BundlePricePreview, GetBundleRequest, ListBundlesRequest, PreviewBundlePriceRequest } from "./contracts/bundleRead.js";
+import type { BundleAvailabilityRow, BundleAvailabilityService } from "./bundleAvailabilityService.js";
+import type { BundleCatalogReadPort, BundleDetail, BundleHistoryResult, BundleTargetPriceRow, ListBundlesResult } from "./bundleCatalogReadPort.js";
+
+export interface AdminBundleReadHandlerDeps {
+  effectiveTarget?: (bundle: BundleDetail) => BundleTargetPriceRow | null;
+  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 function createAdminBundleReadHandlers({ bundleSpec, BundleRpcError, COMMERCE_CONTRACT_VERSION, createAdminParameterizedReadHandler, bundleHistoryResponseSchema, getBundleResponseSchema, listBundlesResponseSchema, previewBundlePriceResponseSchema }: Pick<BundleAdminBindings, "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<TReq>(key: BundleQueryKey): AgentDomainQuerySpec<TReq> {
+  const spec = bundleSpec.queries?.[key];
+  if (!spec) throw new Error(`bundleSpec.queries.${key} is not defined`);
+  return spec as AgentDomainQuerySpec<TReq>;
+}
+
+function gate<TReq, TData>(
+  deps: AdminBundleReadHandlerDeps,
+  key: BundleQueryKey,
+  load: (port: BundleCatalogReadPort, input: TReq) => Promise<TData>,
+  toResponse: (data: TData) => Record<string, unknown>,
+  responseSchema: { safeParse: (value: unknown) => { success: boolean; data?: unknown } },
+  invalidResponseMessage: string,
+) {
+  return createAdminParameterizedReadHandler<TReq, TData>({
+    query: query<TReq>(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: AdminBundleReadHandlerDeps) {
+  return gate<ListBundlesRequest, ListBundlesResult>(
+    deps,
+    "list",
+    (port, input) => port.listBundles(input),
+    (data) => ({
+      contractVersion: COMMERCE_CONTRACT_VERSION,
+      bundles: data.bundles,
+      total: data.total,
+    }),
+    listBundlesResponseSchema,
+    "Invalid bundle list response",
+  );
+}
+
+interface BundleDetailWithStock {
+  bundle: BundleDetail;
+  stock: BundleAvailabilityRow | null;
+}
+
+function createAdminBundleGetHandler(deps: AdminBundleReadHandlerDeps) {
+  return gate<GetBundleRequest, BundleDetailWithStock>(
+    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: AdminBundleReadHandlerDeps,
+  bundle: BundleDetail,
+): Promise<BundleAvailabilityRow | null> {
+  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: AdminBundleReadHandlerDeps) {
+  return gate<BundleHistoryRequest, BundleHistoryResult>(
+    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: AdminBundleReadHandlerDeps) {
+  return gate<PreviewBundlePriceRequest, BundlePricePreview>(
+    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, 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. */
+function toDetailView(bundle: BundleDetail, stock: BundleAvailabilityRow | null): Record<string, unknown> {
+  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: BundleDetail,
+  input: PreviewBundlePriceRequest,
+  effectiveTarget?: (bundle: BundleDetail) => BundleTargetPriceRow | null,
+): BundlePricePreview {
+  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 = 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");
+
+  const allocation = allocateBundleTargetPrice({
+    components: counted.map((component) => ({
+      sku: component.sku,
+      quantity: component.quantity,
+      unitPriceMinor: component.referenceUnitPriceMinor as number,
+    })),
+    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 as BundleAllocationFailure).code);
+
+  return {
+    bundleCode: bundle.code,
+    priceListId: bundle.resolvedPriceListId,
+    mode: input.mode ?? activePrice?.mode ?? (effectiveTarget ? "one_time" : "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/src/catalog/adminBundleWritePort.ts

@@ -0,0 +1,102 @@
+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/src/catalog/bundleAvailability.ts

@@ -0,0 +1,129 @@
+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 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 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 function createBundleAvailability({ offerAvailabilityReasonCode, offerAvailabilityStatusFor }: Pick<BundleRuleBindings, "offerAvailabilityReasonCode" | "offerAvailabilityStatusFor">) {
+function deriveBundleAvailability(
+  input: DeriveBundleAvailabilityInput,
+): BundleAvailability {
+  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: BundleAvailabilityComponent): number {
+  return Math.floor((component.sellableNow ?? 0) / component.quantity);
+}
+
+function lowestSku(components: readonly BundleAvailabilityComponent[]): string {
+  return components.reduce(
+    (lowest, component) => (component.sku < lowest ? component.sku : lowest),
+    components[0].sku,
+  );
+}