@openlup/platform 0.16.0 → 0.18.0

package/dist/catalog/mediaSourcePack.js

@@ -0,0 +1,247 @@
+/** 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 { validateProductMediaManifest, PRODUCT_MEDIA_LIMITS, } from "./contracts/productMediaContracts.js";
+export const SOURCE_PACK_LIMITS = PRODUCT_MEDIA_LIMITS;
+export class CatalogMediaSourcePackError extends Error {
+    code;
+    reference;
+    constructor(code, reference) {
+        super(reference ? `${code}:${reference}` : code);
+        this.code = code;
+        this.reference = reference;
+        this.name = "CatalogMediaSourcePackError";
+    }
+}
+const refuse = (code, reference) => {
+    throw new CatalogMediaSourcePackError(code, reference);
+};
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const extensions = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" };
+const keyFor = (asset) => `assets/${asset.sha256}.${extensions[asset.contentType]}`;
+function normalized(manifest) {
+    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) {
+    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, key, reference) {
+    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, limit, reference) {
+    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, mime) {
+    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, root) {
+    const paths = new Map();
+    // 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();
+    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) {
+    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, manifest) {
+    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) {
+    const input = await readCatalogMediaSourceManifest(await contained(root, "manifest.json"));
+    if (!input || typeof input !== "object" || input.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.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 }, resources };
+}
+async function writeNewPack(pack, resources, targetRoot) {
+    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) => {
+        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();
+    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) {
+    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, targetRoot) {
+    const { pack, resources } = await validateCatalogMediaSourcePack(packRoot);
+    return writeNewPack(pack, resources, targetRoot);
+}
+export async function importCatalogMediaSourcePack(root, storage) {
+    let validated;
+    try {
+        validated = await validateCatalogMediaSourcePack(root);
+    }
+    catch (error) {
+        const refusal = error;
+        return { status: "validation_refusal", code: refusal.code ?? "invalid_schema", ...(refusal.reference ? { reference: refusal.reference } : {}) };
+    }
+    const successfulKeys = [];
+    const assets = [];
+    const urlsByKey = new Map();
+    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/dist/catalog/productTypeSchemas.d.ts

@@ -0,0 +1,46 @@
+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 declare const catalogNamespacedKeySchema: z.ZodString;
+export declare const catalogDimensionKeySchema: z.ZodString;
+export declare const catalogQuantityDimensionSchema: z.ZodEnum<{
+    count: "count";
+    mass: "mass";
+    volume: "volume";
+}>;
+export declare const catalogQuantitySchema: z.ZodObject<{
+    dimension: z.ZodEnum<{
+        count: "count";
+        mass: "mass";
+        volume: "volume";
+    }>;
+    unscaled: z.ZodString;
+    scale: z.ZodNumber;
+    unit: z.ZodString;
+}, z.core.$strict>;
+export declare const catalogOptionValueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"choice">;
+    value: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"quantity">;
+    value: z.ZodObject<{
+        dimension: z.ZodEnum<{
+            count: "count";
+            mass: "mass";
+            volume: "volume";
+        }>;
+        unscaled: z.ZodString;
+        scale: z.ZodNumber;
+        unit: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"boolean">;
+    value: z.ZodBoolean;
+}, z.core.$strict>], "kind">;
+export declare const catalogProductTypeRefSchema: z.ZodObject<{
+    key: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+/** Definitions are installed by composition, never supplied as executable draft data. */
+export declare function createCatalogProductTypeRegistry(definitions: readonly CatalogProductTypeDefinition[]): CatalogProductTypeRegistry;

package/dist/catalog/productTypeSchemas.js

@@ -0,0 +1,72 @@
+import { z } from "./validation.js";
+export { canonicalCatalogOption, validateCatalogQuantity } 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) {
+    const installed = new Map();
+    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) {
+            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) => installed.get(`${ref.key}@${ref.version}`) });
+}

package/dist/catalog/publicationPorts.d.ts

@@ -0,0 +1,42 @@
+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;
+}
+export {};

package/dist/catalog/publicationPorts.js

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

package/dist/catalog/readPorts.d.ts

@@ -0,0 +1,51 @@
+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/dist/catalog/readPorts.js

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

package/dist/catalog/referenceCatalogHandler.d.ts

@@ -0,0 +1,7 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { SellableCatalogPort } from "./readPorts.js";
+export declare function createReferenceCatalogItemsHandler({ catalogPort, responder, }: {
+    catalogPort: SellableCatalogPort;
+    responder: BffResponder;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/catalog/referenceCatalogHandler.js

@@ -0,0 +1,27 @@
+import { SELLABLE_CATALOG_CONTRACT_VERSION, sellableCatalogListResponseSchema, } from "./sellableSchemas.js";
+export function createReferenceCatalogItemsHandler({ catalogPort, responder, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        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/dist/catalog/resolvedSkuProjection.d.ts

@@ -0,0 +1,88 @@
+import { z } from "./validation.js";
+import { type NeutralSkuEnvelopeV1 } from "./foundationSchemas.js";
+/**
+ * Server-only, read-safe projection. It intentionally composes opaque document
+ * references with resolved prices and never selects or exposes document payload.
+ */
+export declare const RESOLVED_SKU_PROJECTION_VERSION = "catalog.resolved-sku.v1";
+export declare const resolvedSkuProjectionSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"catalog.resolved-sku.v1">;
+    envelope: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"catalog.foundation.v1">;
+        product: z.ZodObject<{
+            id: z.ZodGUID;
+            slug: z.ZodString;
+            primarySkuId: z.ZodGUID;
+        }, z.core.$strict>;
+        sku: z.ZodObject<{
+            id: z.ZodGUID;
+            productId: z.ZodGUID;
+            code: z.ZodString;
+            netContent: z.ZodObject<{
+                unscaled: z.ZodNumber;
+                scale: z.ZodNumber;
+                unit: z.ZodString;
+            }, z.core.$strict>;
+            sellability: z.ZodObject<{
+                status: z.ZodEnum<{
+                    draft: "draft";
+                    active: "active";
+                    archived: "archived";
+                }>;
+                oneTime: z.ZodBoolean;
+                subscription: z.ZodBoolean;
+            }, z.core.$strict>;
+            isAddon: z.ZodBoolean;
+            assetRef: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        documentRevision: z.ZodObject<{
+            id: z.ZodGUID;
+            productId: z.ZodGUID;
+            revisionNo: z.ZodNumber;
+            schemaId: z.ZodString;
+            documentRef: z.ZodString;
+            sourceRef: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>;
+        identifiers: z.ZodArray<z.ZodObject<{
+            issuer: z.ZodString;
+            normalizedValue: z.ZodString;
+            kind: z.ZodEnum<{
+                gtin: "gtin";
+                other: "other";
+            }>;
+            packKind: z.ZodEnum<{
+                unit: "unit";
+                collective: "collective";
+            }>;
+            packQuantity: z.ZodNumber;
+            isPrimary: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    priceContext: z.ZodObject<{
+        priceListId: z.ZodGUID;
+        regionCode: z.ZodString;
+        currency: z.ZodString;
+        channel: z.ZodString;
+        atTime: z.ZodString;
+    }, z.core.$strict>;
+    pricing: z.ZodObject<{
+        base: z.ZodObject<{
+            priceEntryId: z.ZodGUID;
+            amountMinor: z.ZodNumber;
+        }, z.core.$strict>;
+        subscription: z.ZodNullable<z.ZodObject<{
+            policyRevisionId: z.ZodGUID;
+            policyDigest: z.ZodString;
+            amountMinor: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+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 declare function buildResolvedSkuProjection(input: ResolvedSkuProjectionInput): ResolvedSkuProjection;

package/dist/catalog/resolvedSkuProjection.js

@@ -0,0 +1,60 @@
+import { z } from "./validation.js";
+import { CatalogSkuAuthorityError, assertPrimaryUnitGtinAuthority, neutralSkuEnvelopeV1Schema, } 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 function buildResolvedSkuProjection(input) {
+    assertPrimaryUnitGtinAuthority(input.envelope.identifiers);
+    return resolvedSkuProjectionSchema.parse({
+        contractVersion: RESOLVED_SKU_PROJECTION_VERSION,
+        ...input,
+    });
+}