@openlup/platform 0.17.0 → 0.19.0

package/dist/catalog/foundationSchemas.js

@@ -0,0 +1,110 @@
+import { z } from "./validation.js";
+import { CATALOG_FOUNDATION_CONTRACT_VERSION, isValidGtin } from "./contracts/foundation.js";
+export { CATALOG_FOUNDATION_CONTRACT_VERSION, CatalogSkuAuthorityError, isValidGtin, assertPrimaryUnitGtinAuthority, requireCurrentCatalogDocumentAuthority } from "./contracts/foundation.js";
+/**
+ * Portable, payload-free catalog shape. Document interpretation remains an
+ * adopter concern; this module can only carry immutable document references.
+ */
+const entityIdSchema = z.guid();
+const opaqueReferenceSchema = z.string().trim().min(1).max(240);
+const codeSchema = z.string().trim().min(1).max(160).regex(/^[A-Za-z0-9._:-]+$/);
+const sha256DigestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const currencyCodeSchema = z.string().regex(/^[A-Z]{3}$/u);
+export const catalogFixedPointSchema = z.object({
+    /** SKU net content is a physical, positive quantity; signed values need a distinct contract. */
+    unscaled: z.number().int().positive().safe(),
+    scale: z.number().int().min(0).max(12).safe(),
+    unit: z.string().trim().min(1).max(64).regex(/^[A-Z][A-Z0-9_]*$/),
+}).strict();
+export const catalogDocumentRevisionRefSchema = z.object({
+    id: entityIdSchema,
+    productId: entityIdSchema,
+    revisionNo: z.number().int().positive(),
+    schemaId: opaqueReferenceSchema,
+    documentRef: opaqueReferenceSchema,
+    sourceRef: opaqueReferenceSchema,
+    digest: sha256DigestSchema,
+}).strict();
+export const catalogSkuIdentifierSchema = z.object({
+    issuer: opaqueReferenceSchema,
+    normalizedValue: z.string().trim().min(1).max(128),
+    kind: z.enum(["gtin", "other"]),
+    packKind: z.enum(["unit", "collective"]),
+    packQuantity: z.number().int().positive(),
+    isPrimary: z.boolean(),
+}).strict();
+/** Stable, payload-free detail selectors shared by both catalog adapters. */
+export const catalogSkuEnvelopeSelectorSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("sku_code"),
+        skuCode: codeSchema,
+    }).strict(),
+    z.object({
+        kind: z.literal("primary_product_slug"),
+        productSlug: codeSchema,
+    }).strict(),
+]);
+export const neutralSkuEnvelopeV1Schema = z.object({
+    contractVersion: z.literal(CATALOG_FOUNDATION_CONTRACT_VERSION),
+    product: z.object({
+        id: entityIdSchema,
+        slug: codeSchema,
+        primarySkuId: entityIdSchema,
+    }).strict(),
+    sku: z.object({
+        id: entityIdSchema,
+        productId: entityIdSchema,
+        code: codeSchema,
+        netContent: catalogFixedPointSchema,
+        sellability: z.object({
+            status: z.enum(["draft", "active", "archived"]),
+            oneTime: z.boolean(),
+            subscription: z.boolean(),
+        }).strict(),
+        /** Structural SKU classification shared by both bundle schemas. */
+        isAddon: z.boolean(),
+        assetRef: opaqueReferenceSchema.nullable(),
+    }).strict(),
+    documentRevision: catalogDocumentRevisionRefSchema,
+    identifiers: z.array(catalogSkuIdentifierSchema).max(32),
+}).strict().superRefine((envelope, context) => {
+    if (envelope.product.id !== envelope.sku.productId) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["sku", "productId"], message: "sku must belong to envelope product" });
+    }
+    if (envelope.product.id !== envelope.documentRevision.productId) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["documentRevision", "productId"], message: "document revision must belong to envelope product" });
+    }
+    const seen = new Set();
+    let primaryGtinCount = 0;
+    envelope.identifiers.forEach((identifier, index) => {
+        const identity = `${identifier.issuer}\u0000${identifier.normalizedValue}`;
+        if (seen.has(identity)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["identifiers", index], message: "identifier issuer/value pairs must be unique" });
+        }
+        seen.add(identity);
+        if (identifier.packKind === "unit" && identifier.packQuantity !== 1) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["identifiers", index, "packQuantity"], message: "unit identifiers require pack quantity 1" });
+        }
+        if (identifier.packKind === "collective" && identifier.packQuantity <= 1) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["identifiers", index, "packQuantity"], message: "collective identifiers require pack quantity above 1" });
+        }
+        if (identifier.isPrimary) {
+            primaryGtinCount += 1;
+            if (identifier.kind !== "gtin"
+                || identifier.packKind !== "unit"
+                || !isValidGtin(identifier.normalizedValue)) {
+                context.addIssue({ code: z.ZodIssueCode.custom, path: ["identifiers", index], message: "a primary identifier must be a unit GTIN" });
+            }
+        }
+    });
+    if (primaryGtinCount > 1) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["identifiers"], message: "a SKU may have at most one primary GTIN" });
+    }
+});
+export const catalogPriceContextSchema = z.object({
+    priceListId: entityIdSchema,
+    regionCode: z.string().regex(/^[A-Z]{2,3}$/u),
+    currency: currencyCodeSchema,
+    channel: z.string().trim().min(1).max(64).regex(/^[A-Za-z0-9._:-]+$/),
+    atTime: z.string().datetime({ offset: true }),
+}).strict();

package/dist/catalog/index.d.ts

@@ -0,0 +1,44 @@
+export * from "./contracts/index.js";
+export { parseCatalogActiveSkuSelection } from "./activeSkuSelection.js";
+export { createCatalogDraftHandler } from "./draftHandler.js";
+export type { CatalogDraftHandlerDeps, CatalogDraftCommandResult } from "./draftHandler.js";
+export { CatalogDraftStoreError } from "./draftPorts.js";
+export type { CatalogDraftOperator, CatalogDraftStorePort } from "./draftPorts.js";
+export { catalogDraftPayloadSchema, catalogDraftCommandSchema, catalogDraftGetQuerySchema, catalogDraftListQuerySchema, catalogDraftSummarySchema, catalogDraftRecordSchema, catalogDraftPageSchema, catalogDraftRefusalSchema, catalogDraftApplyResultSchema } from "./draftSchemas.js";
+export { validateCatalogDraft } from "./draftValidation.js";
+export type { CatalogDraftReadiness, CatalogDraftValidation } from "./draftValidation.js";
+export { catalogFixedPointSchema, catalogDocumentRevisionRefSchema, catalogSkuIdentifierSchema, catalogSkuEnvelopeSelectorSchema, neutralSkuEnvelopeV1Schema, catalogPriceContextSchema } from "./foundationSchemas.js";
+export { catalogNamespacedKeySchema, catalogDimensionKeySchema, catalogQuantityDimensionSchema, catalogQuantitySchema, catalogOptionValueSchema, catalogProductTypeRefSchema, createCatalogProductTypeRegistry } from "./productTypeSchemas.js";
+export type { SellableCatalogPort, CatalogSkuEnvelopeReadPort, PublicCatalogSkuEnvelopeReadPort, CatalogSkuEnvelopeListQuery, CatalogActiveSkuEnvelopeListQuery, CatalogSkuEnvelopePage } from "./readPorts.js";
+export { createReferenceCatalogItemsHandler } from "./referenceCatalogHandler.js";
+export { RESOLVED_SKU_PROJECTION_VERSION, resolvedSkuProjectionSchema, buildResolvedSkuProjection } from "./resolvedSkuProjection.js";
+export type { ResolvedSkuProjection, ResolvedSkuProjectionInput } from "./resolvedSkuProjection.js";
+export { sellableCatalogItemSchema, sellableCatalogProfileSchema, sellableCatalogListResponseSchema } from "./sellableSchemas.js";
+export { SOURCE_PACK_LIMITS, CatalogMediaSourcePackError, readCatalogMediaSourceManifest, validateCatalogMediaSourcePack, exportCatalogMediaSourcePack, restoreCatalogMediaSourcePack, importCatalogMediaSourcePack } from "./mediaSourcePack.js";
+export type { CatalogMediaSourcePack, CatalogMediaImportOutcome } from "./mediaSourcePack.js";
+export type { CatalogValidationPort, CatalogPublicationReadPort, CatalogPublicationPort, VerifiedCatalogPublisher, CatalogCapabilityDescriptor } from "./publicationPorts.js";
+export { SUPPORTED_BUNDLE_FULFILLMENT_MODES, createBundleWriteRules, evaluateBundleComposition, evaluateBundleFulfillmentMode, evaluateBundleTargetPrice, isEmptyCompositionConstraint, evaluateBundleCompositionConstraint } from "./bundleRules.js";
+export type { BundleCompositionEntry, SupportedBundleFulfillmentMode } from "./bundleRules.js";
+export { BUNDLE_RULE_CODES, BUNDLE_ALLOCATION_RULE_CODE, BUNDLE_RULE_ENFORCEMENT } from "./bundleRuleCodes.js";
+export type { BundleRuleCode, BundleActorKind, BundleWriteOperation, BundleRuleResult } from "./bundleRuleCodes.js";
+export { DEFAULT_BUNDLE_LOW_STOCK_THRESHOLD, BUNDLE_COMPONENT_STOCK_UNKNOWN, BUNDLE_COMPOSITION_EMPTY, createBundleAvailability } from "./bundleAvailability.js";
+export type { BundleAvailabilityComponent, BundleAvailability, DeriveBundleAvailabilityInput } from "./bundleAvailability.js";
+export { BundleCatalogReadError } from "./bundleCatalogReadPort.js";
+export type { BundleListStatusFilter, ListBundlesInput, BundleSummary, ListBundlesResult, BundleComponentRow, BundleTargetPriceRow, BundleDetail, GetBundleInput, ActiveBundleComposition, BundleHistoryEvent, BundleHistoryInput, BundleHistoryResult, BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
+export { createBundleAvailabilityServices, createUnknownOfferAvailabilityPort } from "./bundleAvailabilityService.js";
+export type { BundleAvailabilityServiceDeps, BundleAvailabilityRow, BundleAvailabilityService } from "./bundleAvailabilityService.js";
+export type { BundleWriteResult, BundleCompositionConstraintEnvelope, AdminBundleWritePort } from "./adminBundleWritePort.js";
+export { createAdminBundleHandlers } from "./adminBundleHandler.js";
+export type { AdminBundleHandlerDeps } from "./adminBundleHandler.js";
+export { createAdminBundleReadHandlers } from "./adminBundleReadHandler.js";
+export type { AdminBundleReadHandlerDeps } from "./adminBundleReadHandler.js";
+export { createSellableBundleHandlers, toSellableBundle } from "./sellableBundleHandler.js";
+export type { SellableBundleHandlerDeps } from "./sellableBundleHandler.js";
+export type { BundleStockStatus, BundleStockRequestItem, BundleStockAvailability, BundleStockPort, BundleRuleBindings } from "./bundleBindings.js";
+export type { AuthorizeAdmin, AgentDomainQuerySpec, AgentDomainMutationSpec, BundleMutationKey, BundleQueryKey, BundleResponseSchema, BundleAdminBindings } from "./adminBindings.js";
+export { createPostgresBundleCatalogStore } from "./bundleCatalogStore.js";
+export { BUNDLE_MIGRATIONS, CATALOG_MIGRATIONS } from "./sql.js";
+export { SUMMARY_COLUMNS, LIST_FILTER, LIST_SQL, COUNT_SQL, DETAIL_SQL, REFERENCE_PRICE, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL, HISTORY_SQL, HISTORY_COUNT_SQL } from "./bundleCatalogQueries.js";
+export { createPostgresCatalogSkuEnvelopeReadPort } from "./catalogSkuEnvelope.js";
+export { createPostgresCatalogDraftStore } from "./catalogDraftStore.js";
+export { selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";

package/dist/catalog/index.js

@@ -0,0 +1,26 @@
+export * from "./contracts/index.js";
+export { parseCatalogActiveSkuSelection } from "./activeSkuSelection.js";
+export { createCatalogDraftHandler } from "./draftHandler.js";
+export { CatalogDraftStoreError } from "./draftPorts.js";
+export { catalogDraftPayloadSchema, catalogDraftCommandSchema, catalogDraftGetQuerySchema, catalogDraftListQuerySchema, catalogDraftSummarySchema, catalogDraftRecordSchema, catalogDraftPageSchema, catalogDraftRefusalSchema, catalogDraftApplyResultSchema } from "./draftSchemas.js";
+export { validateCatalogDraft } from "./draftValidation.js";
+export { catalogFixedPointSchema, catalogDocumentRevisionRefSchema, catalogSkuIdentifierSchema, catalogSkuEnvelopeSelectorSchema, neutralSkuEnvelopeV1Schema, catalogPriceContextSchema } from "./foundationSchemas.js";
+export { catalogNamespacedKeySchema, catalogDimensionKeySchema, catalogQuantityDimensionSchema, catalogQuantitySchema, catalogOptionValueSchema, catalogProductTypeRefSchema, createCatalogProductTypeRegistry } from "./productTypeSchemas.js";
+export { createReferenceCatalogItemsHandler } from "./referenceCatalogHandler.js";
+export { RESOLVED_SKU_PROJECTION_VERSION, resolvedSkuProjectionSchema, buildResolvedSkuProjection } from "./resolvedSkuProjection.js";
+export { sellableCatalogItemSchema, sellableCatalogProfileSchema, sellableCatalogListResponseSchema } from "./sellableSchemas.js";
+export { SOURCE_PACK_LIMITS, CatalogMediaSourcePackError, readCatalogMediaSourceManifest, validateCatalogMediaSourcePack, exportCatalogMediaSourcePack, restoreCatalogMediaSourcePack, importCatalogMediaSourcePack } from "./mediaSourcePack.js";
+export { SUPPORTED_BUNDLE_FULFILLMENT_MODES, createBundleWriteRules, evaluateBundleComposition, evaluateBundleFulfillmentMode, evaluateBundleTargetPrice, isEmptyCompositionConstraint, evaluateBundleCompositionConstraint } from "./bundleRules.js";
+export { BUNDLE_RULE_CODES, BUNDLE_ALLOCATION_RULE_CODE, BUNDLE_RULE_ENFORCEMENT } from "./bundleRuleCodes.js";
+export { DEFAULT_BUNDLE_LOW_STOCK_THRESHOLD, BUNDLE_COMPONENT_STOCK_UNKNOWN, BUNDLE_COMPOSITION_EMPTY, createBundleAvailability } from "./bundleAvailability.js";
+export { BundleCatalogReadError } from "./bundleCatalogReadPort.js";
+export { createBundleAvailabilityServices, createUnknownOfferAvailabilityPort } from "./bundleAvailabilityService.js";
+export { createAdminBundleHandlers } from "./adminBundleHandler.js";
+export { createAdminBundleReadHandlers } from "./adminBundleReadHandler.js";
+export { createSellableBundleHandlers, toSellableBundle } from "./sellableBundleHandler.js";
+export { createPostgresBundleCatalogStore } from "./bundleCatalogStore.js";
+export { BUNDLE_MIGRATIONS, CATALOG_MIGRATIONS } from "./sql.js";
+export { SUMMARY_COLUMNS, LIST_FILTER, LIST_SQL, COUNT_SQL, DETAIL_SQL, REFERENCE_PRICE, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL, HISTORY_SQL, HISTORY_COUNT_SQL } from "./bundleCatalogQueries.js";
+export { createPostgresCatalogSkuEnvelopeReadPort } from "./catalogSkuEnvelope.js";
+export { createPostgresCatalogDraftStore } from "./catalogDraftStore.js";
+export { selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";

package/dist/catalog/mediaSourcePack.d.ts

@@ -0,0 +1,51 @@
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+import { type ProductMediaManifest } from "./contracts/productMediaContracts.js";
+export declare const SOURCE_PACK_LIMITS: Readonly<{
+    assets: 512;
+    products: 256;
+    variants: 1024;
+    associations: 8192;
+    imageBytes: 358400;
+    totalBytes: number;
+    manifestBytes: number;
+    resolvedItems: 32;
+}>;
+export interface CatalogMediaSourcePack {
+    schemaVersion: "catalog.media-source-pack.v1";
+    manifest: ProductMediaManifest;
+}
+export declare class CatalogMediaSourcePackError extends Error {
+    readonly code: string;
+    readonly reference?: string | undefined;
+    constructor(code: string, reference?: string | undefined);
+}
+export declare function readCatalogMediaSourceManifest(path: string): Promise<unknown>;
+export declare function validateCatalogMediaSourcePack(root: string): Promise<{
+    pack: CatalogMediaSourcePack;
+    resources: Map<string, Buffer<ArrayBufferLike>>;
+}>;
+export declare function exportCatalogMediaSourcePack(options: {
+    manifest: unknown;
+    sourceRoot: string;
+    targetRoot: string;
+}): Promise<CatalogMediaSourcePack>;
+export declare function restoreCatalogMediaSourcePack(packRoot: string, targetRoot: string): Promise<CatalogMediaSourcePack>;
+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 declare function importCatalogMediaSourcePack(root: string, storage: BlobStoragePort): Promise<CatalogMediaImportOutcome>;

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 {};