@openlup/platform 0.17.0 → 0.19.0

package/src/catalog/mediaSourcePack.ts

@@ -0,0 +1,219 @@
+/** Local, bounded source-resource transfer. Uploading bytes never activates associations. */
+import { constants, promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve, sep } from "node:path";
+import { resolveProductMedia } from "./contracts/resolveProductMedia.js";
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+import {
+  validateProductMediaManifest,
+  PRODUCT_MEDIA_LIMITS,
+  type ProductMediaManifest,
+  type ProductMediaAsset,
+} from "./contracts/productMediaContracts.js";
+
+export const SOURCE_PACK_LIMITS = PRODUCT_MEDIA_LIMITS;
+export interface CatalogMediaSourcePack {
+  schemaVersion: "catalog.media-source-pack.v1";
+  manifest: ProductMediaManifest;
+}
+export class CatalogMediaSourcePackError extends Error {
+  constructor(public readonly code: string, public readonly reference?: string) {
+    super(reference ? `${code}:${reference}` : code);
+    this.name = "CatalogMediaSourcePackError";
+  }
+}
+const refuse = (code: string, reference?: string): never => {
+  throw new CatalogMediaSourcePackError(code, reference);
+};
+const digest = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+const extensions: Record<string, string> = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" };
+const keyFor = (asset: ProductMediaAsset): string => `assets/${asset.sha256}.${extensions[asset.contentType]}`;
+
+function normalized(manifest: ProductMediaManifest): ProductMediaManifest {
+  return {
+    schemaVersion: manifest.schemaVersion,
+    products: manifest.products.map(({ productId, variantIds, primaryVariantId }) => ({ productId, variantIds: [...variantIds], primaryVariantId })),
+    assets: manifest.assets.map(({ assetRef, source, contentType, byteLength, sha256, artworkLocale }) => ({ assetRef, source, contentType, byteLength, sha256, artworkLocale })),
+    associations: manifest.associations.map(({ itemId, assetRef, productId, scope, variantId, locale, role, viewKey, order, label }) => ({
+      itemId, assetRef, productId, scope, ...(variantId === undefined ? {} : { variantId }),
+      locale, role, ...(viewKey === undefined ? {} : { viewKey }), order, label,
+    })),
+  };
+}
+function checkedManifest(value: unknown): ProductMediaManifest {
+  const manifest = normalized(validateProductMediaManifest(value));
+  const envelope = { schemaVersion: "catalog.media-source-pack.v1", manifest: {
+    ...manifest, assets: manifest.assets.map((asset) => ({ ...asset, source: keyFor(asset) })),
+  } };
+  if (Buffer.byteLength(JSON.stringify(manifest)) > SOURCE_PACK_LIMITS.manifestBytes ||
+      Buffer.byteLength(JSON.stringify(envelope, null, 2) + "\n") > SOURCE_PACK_LIMITS.manifestBytes) refuse("pack_limit_exceeded");
+  const checks = manifest.products.map((product) => {
+    const items = manifest.associations.filter((item) => item.productId === product.productId);
+    const locales = new Set(items.flatMap((item) => item.locale === null ? [] : [item.locale]));
+    let neutralIndex = 0;
+    while (locales.has(`source-pack-neutral-${neutralIndex}`)) neutralIndex++;
+    locales.add(`source-pack-neutral-${neutralIndex}`);
+    return { product, locales };
+  });
+  // Bound processing before any full resolver pass, resource read or upload.
+  const expandedChecks = checks.reduce((total, { product, locales }) => total + product.variantIds.length * locales.size, 0);
+  if (expandedChecks > SOURCE_PACK_LIMITS.associations) refuse("pack_limit_exceeded");
+  const urls = Object.fromEntries(manifest.assets.map((asset) => [asset.assetRef, asset.source]));
+  for (const { product, locales } of checks) {
+    for (const variantId of product.variantIds) for (const locale of locales) {
+      resolveProductMedia(manifest, { productId: product.productId, variantId, locale }, urls);
+    }
+  }
+  return manifest;
+}
+
+async function contained(root: string, key: string, reference?: string): Promise<string> {
+  if (!key || isAbsolute(key) || key.includes("\\") || key.includes(":" ) || key.includes("%") ||
+      key.split("/").some((part) => !part || part === "." || part === "..")) refuse("unsafe_path", reference);
+  try {
+    const canonicalRoot = await fs.realpath(root);
+    const target = await fs.realpath(resolve(canonicalRoot, key));
+    if (!target.startsWith(canonicalRoot + sep)) refuse("unsafe_path", reference);
+    return target;
+  } catch (error) {
+    if (error instanceof CatalogMediaSourcePackError) throw error;
+    return refuse("missing_resource", reference);
+  }
+}
+/** Open only contained regular files, allocate a fixed bound and read at most limit + 1. */
+async function boundedRead(path: string, limit: number, reference?: string): Promise<Buffer> {
+  const handle = await fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => refuse("missing_resource", reference));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) refuse("unsafe_path", reference);
+    if (stat.size > limit) refuse("pack_limit_exceeded", reference);
+    const bytes = Buffer.alloc(limit + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > limit) refuse("pack_limit_exceeded", reference);
+    return bytes.subarray(0, length);
+  } finally { await handle.close(); }
+}
+function matchesMime(bytes: Buffer, mime: string): boolean {
+  if (mime === "image/png") return bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  if (mime === "image/jpeg") return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+  return bytes.length >= 16 && bytes.toString("ascii", 0, 4) === "RIFF" &&
+    bytes.toString("ascii", 8, 12) === "WEBP" && bytes.readUInt32LE(4) + 8 === bytes.length &&
+    ["VP8 ", "VP8L", "VP8X"].includes(bytes.toString("ascii", 12, 16));
+}
+async function loadResources(manifest: ProductMediaManifest, root: string): Promise<Map<string, Buffer>> {
+  const paths = new Map<string, string>();
+  // Stat every resource before reading any payload; declared and actual totals are bounded.
+  for (const asset of manifest.assets) {
+    const path = await contained(root, asset.source, asset.assetRef);
+    const stat = await fs.stat(path);
+    if (!stat.isFile()) refuse("unsafe_path", asset.assetRef);
+    if (stat.size > SOURCE_PACK_LIMITS.imageBytes) refuse("pack_limit_exceeded", asset.assetRef);
+    if (stat.size !== asset.byteLength) refuse("size_mismatch", asset.assetRef);
+    paths.set(asset.assetRef, path);
+  }
+  const resources = new Map<string, Buffer>();
+  for (const asset of manifest.assets) {
+    const bytes = await boundedRead(paths.get(asset.assetRef)!, asset.byteLength, asset.assetRef);
+    if (bytes.length !== asset.byteLength) refuse("size_mismatch", asset.assetRef);
+    if (!matchesMime(bytes, asset.contentType)) refuse("mime_mismatch", asset.assetRef);
+    if (digest(bytes) !== asset.sha256) refuse("digest_mismatch", asset.assetRef);
+    resources.set(asset.assetRef, bytes);
+  }
+  return resources;
+}
+
+export async function readCatalogMediaSourceManifest(path: string): Promise<unknown> {
+  const bytes = await boundedRead(path, SOURCE_PACK_LIMITS.manifestBytes);
+  try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); }
+  catch { return refuse("invalid_schema"); }
+}
+async function checkInventory(root: string, manifest: ProductMediaManifest) {
+  const expected = new Set(manifest.assets.map((asset) => keyFor(asset).slice(7)));
+  const rootEntries = await fs.opendir(root);
+  let rootCount = 0;
+  for await (const entry of rootEntries) {
+    if (++rootCount > 2 || !["assets", "manifest.json"].includes(entry.name)) refuse("reference_mismatch");
+  }
+  const assetRoot = await contained(root, "assets");
+  const entries = await fs.opendir(assetRoot);
+  let count = 0;
+  for await (const entry of entries) {
+    if (++count > SOURCE_PACK_LIMITS.assets) refuse("pack_limit_exceeded");
+    if (!expected.delete(entry.name)) refuse("reference_mismatch");
+  }
+  if (expected.size) refuse("missing_resource");
+}
+export async function validateCatalogMediaSourcePack(root: string) {
+  const input = await readCatalogMediaSourceManifest(await contained(root, "manifest.json"));
+  if (!input || typeof input !== "object" || (input as CatalogMediaSourcePack).schemaVersion !== "catalog.media-source-pack.v1") return refuse("invalid_schema");
+  if (Object.keys(input).some((key) => !["schemaVersion", "manifest"].includes(key))) refuse("invalid_schema");
+  const manifest = checkedManifest((input as CatalogMediaSourcePack).manifest);
+  for (const asset of manifest.assets) if (asset.source !== keyFor(asset)) refuse("unsafe_path", asset.assetRef);
+  await checkInventory(root, manifest);
+  const resources = await loadResources(manifest, root);
+  return { pack: { schemaVersion: "catalog.media-source-pack.v1", manifest } as CatalogMediaSourcePack, resources };
+}
+async function writeNewPack(pack: CatalogMediaSourcePack, resources: Map<string, Buffer>, targetRoot: string) {
+  const encoded = JSON.stringify(pack, null, 2) + "\n";
+  if (Buffer.byteLength(encoded) > SOURCE_PACK_LIMITS.manifestBytes) refuse("pack_limit_exceeded");
+  // mkdir without recursive is the atomic no-overwrite boundary.
+  await fs.mkdir(targetRoot).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "EEXIST") refuse("target_exists");
+    refuse("dependency_unavailable");
+  });
+  const root = await fs.realpath(targetRoot);
+  await fs.mkdir(resolve(root, "assets"));
+  const written = new Set<string>();
+  for (const asset of pack.manifest.assets) {
+    if (written.has(asset.source)) continue;
+    await fs.writeFile(resolve(root, asset.source), resources.get(asset.assetRef)!, { flag: "wx" });
+    written.add(asset.source);
+  }
+  await fs.writeFile(resolve(root, "manifest.json"), encoded, { flag: "wx" });
+  return pack;
+}
+export async function exportCatalogMediaSourcePack(options: { manifest: unknown; sourceRoot: string; targetRoot: string }) {
+  const manifest = checkedManifest(options.manifest);
+  const resources = await loadResources(manifest, options.sourceRoot);
+  const portable = { ...manifest, assets: manifest.assets.map((asset) => ({ ...asset, source: keyFor(asset) })) };
+  return writeNewPack({ schemaVersion: "catalog.media-source-pack.v1", manifest: portable }, resources, options.targetRoot);
+}
+export async function restoreCatalogMediaSourcePack(packRoot: string, targetRoot: string) {
+  const { pack, resources } = await validateCatalogMediaSourcePack(packRoot);
+  return writeNewPack(pack, resources, targetRoot);
+}
+export type CatalogMediaImportOutcome =
+  | { status: "complete"; successfulKeys: string[]; assets: Array<{ assetRef: string; key: string; url: string }> }
+  | { status: "validation_refusal"; code: string; reference?: string }
+  | { status: "dependency_unavailable" | "partial_upload"; successfulKeys: string[]; failedAssetRef: string; failedKey: string };
+export async function importCatalogMediaSourcePack(root: string, storage: BlobStoragePort): Promise<CatalogMediaImportOutcome> {
+  let validated: Awaited<ReturnType<typeof validateCatalogMediaSourcePack>>;
+  try { validated = await validateCatalogMediaSourcePack(root); }
+  catch (error) {
+    const refusal = error as { code?: string; reference?: string };
+    return { status: "validation_refusal", code: refusal.code ?? "invalid_schema", ...(refusal.reference ? { reference: refusal.reference } : {}) };
+  }
+  const successfulKeys: string[] = [];
+  const assets: Array<{ assetRef: string; key: string; url: string }> = [];
+  const urlsByKey = new Map<string, string>();
+  for (const asset of validated.pack.manifest.assets) {
+    const key = keyFor(asset);
+    try {
+      if (!urlsByKey.has(key)) {
+        const result = await storage.upload(key, validated.resources.get(asset.assetRef)!, { contentType: asset.contentType });
+        if (result.pathname !== key) refuse("storage_path_mismatch", asset.assetRef);
+        successfulKeys.push(key);
+        urlsByKey.set(key, storage.urlFor(key));
+      }
+      assets.push({ assetRef: asset.assetRef, key, url: urlsByKey.get(key)! });
+    } catch {
+      return { status: successfulKeys.length ? "partial_upload" : "dependency_unavailable", successfulKeys, failedAssetRef: asset.assetRef, failedKey: key };
+    }
+  }
+  return { status: "complete", successfulKeys, assets };
+}

package/src/catalog/productTypeSchemas.ts

@@ -0,0 +1,70 @@
+import { z } from "./validation.js";
+import type { CatalogProductTypeDefinition, CatalogProductTypeRegistry } from "./contracts/productTypes.js";
+export { canonicalCatalogOption, validateCatalogQuantity } from "./contracts/productTypes.js";
+export type { CatalogQuantity, CatalogOptionValue, CatalogDraftIssue, CatalogProductTypeDefinition, CatalogProductTypeRegistry } from "./contracts/productTypes.js";
+
+export const catalogNamespacedKeySchema = z.string().max(120).regex(/^[a-z][a-z0-9.-]*:[a-z][a-z0-9._-]*$/u);
+export const catalogDimensionKeySchema = z.string().max(64).regex(/^[a-z][a-z0-9_-]*$/u)
+  .refine((key) => !["__proto__", "constructor", "prototype"].includes(key));
+export const catalogQuantityDimensionSchema = z.enum(["mass", "volume", "count"]);
+export const catalogQuantitySchema = z.object({
+  dimension: catalogQuantityDimensionSchema,
+  unscaled: z.string().regex(/^[1-9][0-9]{0,39}$/u),
+  scale: z.number().int().min(0).max(12),
+  unit: catalogNamespacedKeySchema,
+}).strict();
+export const catalogOptionValueSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("choice"), value: z.string().min(1).max(120) }).strict(),
+  z.object({ kind: z.literal("quantity"), value: catalogQuantitySchema }).strict(),
+  z.object({ kind: z.literal("boolean"), value: z.boolean() }).strict(),
+]);
+export const catalogProductTypeRefSchema = z.object({
+  key: catalogNamespacedKeySchema,
+  version: z.number().int().positive().max(2_147_483_647),
+}).strict();
+const unitSchema = z.object({
+  code: catalogNamespacedKeySchema,
+  dimension: catalogQuantityDimensionSchema,
+  integral: z.boolean(),
+}).strict();
+const dimensionSchema = z.discriminatedUnion("kind", [
+  z.object({ key: catalogDimensionKeySchema, kind: z.literal("choice"), values: z.array(z.string().min(1).max(120)).min(1).max(1000) }).strict(),
+  z.object({ key: catalogDimensionKeySchema, kind: z.literal("quantity"), dimension: catalogQuantityDimensionSchema,
+    units: z.array(catalogNamespacedKeySchema).min(1).max(32), role: z.literal("net_content").optional() }).strict(),
+  z.object({ key: catalogDimensionKeySchema, kind: z.literal("boolean") }).strict(),
+]);
+const definitionSchema = catalogProductTypeRefSchema.extend({
+  units: z.array(unitSchema).max(64),
+  netContentUnits: z.array(catalogNamespacedKeySchema).min(1).max(64),
+  dimensions: z.array(dimensionSchema).max(16),
+}).strict();
+/** Definitions are installed by composition, never supplied as executable draft data. */
+export function createCatalogProductTypeRegistry(definitions: readonly CatalogProductTypeDefinition[]): CatalogProductTypeRegistry {
+  const installed = new Map<string, CatalogProductTypeDefinition>();
+  for (const definition of definitions) {
+    const { validateContent, ...metadata } = definition;
+    const parsed = definitionSchema.parse(metadata);
+    const units = new Map(parsed.units.map((unit) => [unit.code, unit]));
+    const identity = `${parsed.key}@${parsed.version}`;
+    if (typeof validateContent !== "function" || installed.has(identity)
+      || units.size !== parsed.units.length
+      || new Set(parsed.dimensions.map(({ key }) => key)).size !== parsed.dimensions.length
+      || new Set(parsed.netContentUnits).size !== parsed.netContentUnits.length
+      || parsed.netContentUnits.some((code) => !units.has(code))) throw new Error("invalid_catalog_type_definition");
+    for (const dimension of parsed.dimensions) {
+      if (dimension.kind === "choice" && new Set(dimension.values).size !== dimension.values.length) throw new Error("invalid_catalog_type_definition");
+      if (dimension.kind === "quantity" && (new Set(dimension.units).size !== dimension.units.length
+        || dimension.units.some((code) => units.get(code)?.dimension !== dimension.dimension)
+        || (dimension.role === "net_content" && dimension.units.some((code) => !parsed.netContentUnits.includes(code))))) throw new Error("invalid_catalog_type_definition");
+    }
+    if (parsed.dimensions.filter((dimension) => dimension.kind === "quantity" && dimension.role === "net_content").length > 1) throw new Error("invalid_catalog_type_definition");
+    function freeze(value: object): void {
+      for (const child of Object.values(value)) if (child && typeof child === "object") freeze(child);
+      Object.freeze(value);
+    }
+    freeze(parsed);
+    installed.set(identity, Object.freeze({ ...parsed, validateContent }));
+  }
+  return Object.freeze({ resolve: (ref: z.infer<typeof catalogProductTypeRefSchema>) => installed.get(`${ref.key}@${ref.version}`) });
+}
+

package/src/catalog/publicationPorts.ts

@@ -0,0 +1,44 @@
+import type {
+  CatalogHeadRef, CatalogHistoryResult, CatalogPublicationReadResult,
+  CatalogPublicationReceipt, CatalogPublicationReceiptResult,
+  CatalogPublicationRefusal, CatalogPublishCommand,
+} from "./contracts/lifecycle.js";
+
+declare const verifiedCatalogPublisher: unique symbol;
+/** Server authorization result. P1 exposes no constructor or actor-string conversion. */
+export interface VerifiedCatalogPublisher {
+  readonly [verifiedCatalogPublisher]: true;
+}
+
+export interface CatalogValidationPort {
+  validate(candidateRef: string): Promise<{
+    candidateDigest: string;
+    issues: readonly { code: string; path: string }[];
+  }>;
+}
+
+/** No default binding: missing authority is unsupported; configured outage is dependency_unavailable. */
+export interface CatalogPublicationReadPort {
+  current(productId: string): Promise<CatalogPublicationReadResult>;
+  readback(head: CatalogHeadRef): Promise<CatalogPublicationReadResult>;
+  receipt(scope: { productId: string; commandKey: string }): Promise<CatalogPublicationReceiptResult>;
+  /** Null starts a bounded history page; cursors retain the authority's stable ordering. */
+  history(productId: string, cursor: string | null): Promise<CatalogHistoryResult>;
+}
+
+/** Types only: proposal submission does not implement publication or lifecycle writes. */
+export interface CatalogPublicationPort {
+  publish(command: CatalogPublishCommand, actor: VerifiedCatalogPublisher): Promise<
+    | { outcome: "committed" | "replayed"; receipt: CatalogPublicationReceipt }
+    | CatalogPublicationRefusal
+  >;
+}
+
+/** Describes a host's actual support; exporting ports supplies no capabilities. */
+export interface CatalogCapabilityDescriptor {
+  read: boolean;
+  draft: boolean;
+  publicationRead: boolean;
+  publish: boolean;
+  lifecycleWrite: boolean;
+}

package/src/catalog/readPorts.ts

@@ -0,0 +1,61 @@
+import type { SellableCatalogItem, SellableCatalogProfile, CatalogSkuEnvelopeSelector, NeutralSkuEnvelopeV1 } from "./contracts/index.js";
+
+/**
+ * Minimal neutral catalog seam used by the local reference storefront. It is
+ * independent of richer application catalog read ports.
+ */
+export interface SellableCatalogPort {
+  getStorefrontProfile(): Promise<SellableCatalogProfile>;
+  listSellableItems(): Promise<SellableCatalogItem[]>;
+}
+
+/**
+ * Dark W2a read seam. Its row-safe return value deliberately contains document
+ * references, never a document payload or a SKU-level document override.
+ */
+export interface CatalogSkuEnvelopeReadPort {
+  listSkuEnvelopes(query: CatalogSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage>;
+  /**
+   * Page only active trade items that are sellable in at least one commerce
+   * channel. This is intentionally distinct from the neutral inventory-style
+   * listing above: consumers such as compatibility must not discover dormant
+   * SKUs and then try to filter them with a second authority.
+   */
+  listActiveSkuEnvelopes(query: CatalogActiveSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage>;
+  getSkuEnvelope(selector: CatalogSkuEnvelopeSelector): Promise<NeutralSkuEnvelopeV1 | null>;
+  /** Compatibility lookup for callers that already persist the neutral SKU UUID. */
+  getSkuEnvelopeById(skuId: string): Promise<NeutralSkuEnvelopeV1 | null>;
+}
+
+/**
+ * Additive discovery capability. Existing commerce consumers remain typed to
+ * {@link CatalogSkuEnvelopeReadPort} and therefore cannot accidentally use it.
+ */
+export interface PublicCatalogSkuEnvelopeReadPort extends CatalogSkuEnvelopeReadPort {
+  /**
+   * Public discovery's active-only page. Unlike the commerce method above it
+   * intentionally includes temporarily unsellable active variants.
+   */
+  listPublicActiveSkuEnvelopes(query: CatalogSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage>;
+  /** Active-only cursor page restricted to one already-authoritative product. */
+  listPublicActiveProductSkuEnvelopes(
+    productId: string,
+    query: CatalogSkuEnvelopeListQuery,
+  ): Promise<CatalogSkuEnvelopePage>;
+}
+
+export interface CatalogSkuEnvelopeListQuery {
+  cursor: string | null;
+  limit: number;
+}
+
+export interface CatalogActiveSkuEnvelopeListQuery extends CatalogSkuEnvelopeListQuery {
+  /** Optional server-selected scope; supplied selections contain 1–100 unique SKU codes. */
+  skuCodes?: readonly string[];
+}
+
+export interface CatalogSkuEnvelopePage {
+  items: NeutralSkuEnvelopeV1[];
+  nextCursor: string | null;
+}
+

package/src/catalog/referenceCatalogHandler.ts

@@ -0,0 +1,39 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import {
+  SELLABLE_CATALOG_CONTRACT_VERSION,
+  sellableCatalogListResponseSchema,
+} from "./sellableSchemas.js";
+import type { SellableCatalogPort } from "./readPorts.js";
+
+export function createReferenceCatalogItemsHandler({
+  catalogPort, responder,
+}: {
+  catalogPort: SellableCatalogPort;
+  responder: BffResponder;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    try {
+      const response = sellableCatalogListResponseSchema.safeParse({
+        contractVersion: SELLABLE_CATALOG_CONTRACT_VERSION,
+        profile: await catalogPort.getStorefrontProfile(),
+        items: await catalogPort.listSellableItems(),
+      });
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Reference catalog returned invalid items");
+        return;
+      }
+      sendBffSuccess(res, response.data, { contractVersion: SELLABLE_CATALOG_CONTRACT_VERSION }, {
+        cacheControl: "no-store",
+      });
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Reference catalog is unavailable");
+    }
+  };
+}

package/src/catalog/resolvedSkuProjection.ts

@@ -0,0 +1,76 @@
+import { z } from "./validation.js";
+import {
+  CatalogSkuAuthorityError,
+  assertPrimaryUnitGtinAuthority,
+  neutralSkuEnvelopeV1Schema,
+  type NeutralSkuEnvelopeV1,
+} from "./foundationSchemas.js";
+
+const uuidSchema = z.guid();
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const currencySchema = z.string().regex(/^[A-Z]{3}$/u);
+const moneyMinorSchema = z.number().int().nonnegative();
+
+/**
+ * Server-only, read-safe projection. It intentionally composes opaque document
+ * references with resolved prices and never selects or exposes document payload.
+ */
+export const RESOLVED_SKU_PROJECTION_VERSION = "catalog.resolved-sku.v1";
+
+export const resolvedSkuProjectionSchema = z.object({
+  contractVersion: z.literal(RESOLVED_SKU_PROJECTION_VERSION),
+  envelope: neutralSkuEnvelopeV1Schema,
+  priceContext: z.object({
+    priceListId: uuidSchema,
+    regionCode: z.string().regex(/^[A-Z]{2,3}$/u),
+    currency: currencySchema,
+    channel: z.string().trim().min(1).max(64),
+    atTime: z.string().datetime({ offset: true }),
+  }).strict(),
+  pricing: z.object({
+    base: z.object({
+      priceEntryId: uuidSchema,
+      amountMinor: moneyMinorSchema,
+    }).strict(),
+    subscription: z.object({
+      policyRevisionId: uuidSchema,
+      policyDigest: digestSchema,
+      amountMinor: moneyMinorSchema,
+    }).strict().nullable(),
+  }).strict(),
+}).strict().superRefine((projection, context) => {
+  try {
+    assertPrimaryUnitGtinAuthority(projection.envelope.identifiers);
+  } catch (error) {
+    if (!(error instanceof CatalogSkuAuthorityError)) throw error;
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["envelope", "identifiers"],
+      message: error.code,
+    });
+  }
+  const subscriptionSellable = projection.envelope.sku.sellability.subscription;
+  if (subscriptionSellable && projection.pricing.subscription === null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["pricing", "subscription"], message: "subscription-sellable SKUs require a subscription price" });
+  }
+  if (!subscriptionSellable && projection.pricing.subscription !== null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["pricing", "subscription"], message: "one-time-only SKUs must not carry a subscription price" });
+  }
+});
+
+export type ResolvedSkuProjection = z.infer<typeof resolvedSkuProjectionSchema>;
+
+/** Row-safe constructor boundary for adapters; it accepts no raw document row/payload. */
+export interface ResolvedSkuProjectionInput {
+  envelope: NeutralSkuEnvelopeV1;
+  priceContext: ResolvedSkuProjection["priceContext"];
+  pricing: ResolvedSkuProjection["pricing"];
+}
+
+export function buildResolvedSkuProjection(input: ResolvedSkuProjectionInput): ResolvedSkuProjection {
+  assertPrimaryUnitGtinAuthority(input.envelope.identifiers);
+  return resolvedSkuProjectionSchema.parse({
+    contractVersion: RESOLVED_SKU_PROJECTION_VERSION,
+    ...input,
+  });
+}

package/src/catalog/sellableBundleHandler.ts

@@ -0,0 +1,133 @@
+import { allocateBundleTargetPrice } from "@openlup/core/pricing";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { BundleResponseSchema } from "./adminBindings.js";
+import type { SellableBundle } from "./contracts/bundleAvailability.js";
+import type { BundleAvailability } from "./bundleAvailability.js";
+import type { ActiveBundleComposition } from "./bundleCatalogReadPort.js";
+import type { BundleAvailabilityService } from "./bundleAvailabilityService.js";
+
+
+/**
+ * The public sellable-bundle feed handler, shaped after the reference catalog
+ * handler: GET-only, one
+ * port call, validate the body before sending, and never serve an unvalidated
+ * shape.
+ *
+ * It composes rather than computes twice: the availability service already folds
+ * one batched stock answer into the live compositions, and the pricing kernel
+ * turns the stored target price into per-component money. This module only decides
+ * what a storefront is allowed to see.
+ *
+ * A bundle whose money cannot be derived is DROPPED from the feed, not published
+ * with a guessed figure. Three cases reach that door — an unpriced component, an
+ * empty composition, and a target price the kernel refuses — and all three mean
+ * the same thing to a storefront: this is not sellable today. Publishing it with a
+ * partial price would put a number on a shelf that no order line could reproduce.
+ */
+
+export interface SellableBundleHandlerDeps {
+  availabilityService: BundleAvailabilityService;
+  /** Narrow the feed to one currency; omitted means every currency an operator priced. */
+  currency?: string;
+  enabled: boolean;
+}
+
+export function createSellableBundleHandlers({ responder, sellableBundleListResponseSchema, SELLABLE_BUNDLE_CONTRACT_VERSION }: { responder: BffResponder; sellableBundleListResponseSchema: BundleResponseSchema; SELLABLE_BUNDLE_CONTRACT_VERSION: "catalog.sellable-bundle.v1" }) {
+const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+function createSellableBundleHandler(deps: SellableBundleHandlerDeps) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+    if (!deps.enabled) {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Bundle reads are disabled", {
+        details: { reason: "feature_flag_disabled", featureFlag: "COMMERCE_BUNDLE_READ_ENABLED" },
+      });
+      return;
+    }
+
+    try {
+      const rows = await deps.availabilityService.describeActiveBundles(
+        deps.currency ? { currency: deps.currency } : {},
+      );
+      const response = sellableBundleListResponseSchema.safeParse({
+        contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION,
+        bundles: rows
+          .map((row) => toSellableBundle(row.composition, row.availability))
+          .filter((bundle): bundle is SellableBundle => bundle !== null),
+      });
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Sellable bundle feed returned an invalid shape");
+        return;
+      }
+      sendBffSuccess(
+        res,
+        response.data,
+        { contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION },
+        { cacheControl: "no-store" },
+      );
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Sellable bundles are unavailable");
+    }
+  };
+}
+
+return { createSellableBundleHandler };
+}
+
+/**
+ * Derive the row a storefront sees, or `null` when the money cannot be stated.
+ *
+ * The allocator emits TWO lines for a quantity whose subtotal does not divide
+ * evenly, which is exactly why the feed carries lines rather than a unit price per
+ * component: `unitPrice x quantity === lineSubtotal` holds on every line, and the
+ * lines sum to the bundle's price with no remainder.
+ */
+export function toSellableBundle(
+  composition: ActiveBundleComposition,
+  availability: BundleAvailability,
+): SellableBundle | null {
+  if (composition.components.length === 0) return null;
+  if (composition.components.some((component) => component.referenceUnitPriceMinor === null)) {
+    return null;
+  }
+
+  const allocation = allocateBundleTargetPrice({
+    components: composition.components.map((component) => ({
+      sku: component.sku,
+      quantity: component.quantity,
+      unitPriceMinor: component.referenceUnitPriceMinor as number,
+    })),
+    targetPriceMinor: composition.targetPriceMinor,
+  });
+  if (!allocation.ok) return null;
+
+  // Basis points come from the per-component allocation, so a component split
+  // across two lines reports the same discount on both halves rather than two
+  // rounded figures that disagree.
+  const discountBpsBySku = new Map(
+    allocation.components.map((component) => [component.sku, component.discountBps]),
+  );
+
+  return {
+    code: composition.code,
+    title: composition.title,
+    fulfillmentMode: composition.fulfillmentMode,
+    price: { amountMinor: composition.targetPriceMinor, currency: composition.currency },
+    components: allocation.lines.map((line) => ({
+      sku: line.sku,
+      quantity: line.quantity,
+      effectiveUnitPriceMinor: line.effectiveUnitPriceMinor,
+      lineSubtotalMinor: line.lineSubtotalMinor,
+      discountBps: discountBpsBySku.get(line.sku) ?? 0,
+    })),
+    availability: {
+      status: availability.status,
+      sellableNow: availability.sellableNow,
+      limitingSku: availability.limitingSku,
+      reasonCode: availability.reasonCode,
+    },
+  };
+}