@openlup/platform 0.17.0 → 0.18.0

package/src/catalog/draftValidation.ts

@@ -0,0 +1,100 @@
+import { isValidGtin } from "./foundationSchemas.js";
+import type { CatalogDraftPayload } from "./draftSchemas.js";
+import {
+  canonicalCatalogOption, validateCatalogQuantity,
+  type CatalogDraftIssue, type CatalogProductTypeRegistry,
+} from "./productTypeSchemas.js";
+
+export interface CatalogDraftReadiness {
+  publication: { status: "incomplete" | "not_assessed"; issues: CatalogDraftIssue[] };
+  commercial: { status: "inactive"; issues: CatalogDraftIssue[] };
+}
+export type CatalogDraftValidation =
+  | { valid: false; issues: CatalogDraftIssue[] }
+  | { valid: true; readiness: CatalogDraftReadiness };
+
+/** Supplied facts must be true; absent publish-time facts remain draft readiness issues. */
+export function validateCatalogDraft(payload: CatalogDraftPayload, registry: CatalogProductTypeRegistry): CatalogDraftValidation {
+  const issues: CatalogDraftIssue[] = [];
+  const publication: CatalogDraftIssue[] = [];
+  const commercial: CatalogDraftIssue[] = [];
+  const add = (path: string, code: string) => issues.push({ path, code });
+  const missing = (path: string, code: string) => publication.push({ path, code });
+  const { product, skus } = payload;
+  const definition = registry.resolve(product.type);
+  if (!definition) return { valid: false, issues: [{ path: "product.type", code: "type_not_installed" }] };
+  const dimensions = new Map(definition.dimensions.map((dimension) => [dimension.key, dimension]));
+  const netContentKey = definition.dimensions.find((dimension) => dimension.kind === "quantity" && dimension.role === "net_content")?.key;
+  if (new Set(product.dimensions).size !== product.dimensions.length) add("product.dimensions", "duplicate_dimension");
+  product.dimensions.forEach((key) => { if (!dimensions.has(key)) add(`product.dimensions.${key}`, "dimension_not_installed"); });
+  if (product.sharedContent !== undefined) {
+    issues.push(...definition.validateContent(product.sharedContent).map((issue) => ({ ...issue, path: `product.sharedContent${issue.path ? `.${issue.path}` : ""}` })));
+  } else if (!product.documentRevision) missing("product.sharedContent", "content_missing");
+  if (product.documentRevision && product.documentRevision.productId !== product.id) add("product.documentRevision.productId", "foreign_product_reference");
+  if (product.primarySkuId && !skus.some((sku) => sku.id === product.primarySkuId)) add("product.primarySkuId", "primary_sku_not_in_product");
+  if (!product.primarySkuId) missing("product.primarySkuId", "primary_sku_missing");
+  if (!product.slug) missing("product.slug", "slug_missing");
+  if (!skus.length) missing("skus", "sku_missing");
+  const skuIds = new Set<string>();
+  const skuCodes = new Set<string>();
+  const combinations = new Set<string>();
+  const identifiers = new Set<string>();
+  skus.forEach((sku, index) => {
+    const path = `skus.${index}`;
+    if (sku.productId !== product.id) add(`${path}.productId`, "foreign_product_reference");
+    if (skuIds.has(sku.id)) add(`${path}.id`, "duplicate_sku_id");
+    skuIds.add(sku.id);
+    if (sku.code) {
+      if (skuCodes.has(sku.code)) add(`${path}.code`, "duplicate_sku_code");
+      skuCodes.add(sku.code);
+    } else missing(`${path}.code`, "sku_code_missing");
+    const optionKeys = Object.keys(sku.options);
+    for (const key of optionKeys) {
+      const option = sku.options[key];
+      const dimension = dimensions.get(key);
+      if (!product.dimensions.includes(key) || !dimension) { add(`${path}.options.${key}`, "dimension_not_declared"); continue; }
+      if (dimension.kind !== option.kind) { add(`${path}.options.${key}`, "option_type_invalid"); continue; }
+      if (dimension.kind === "choice" && option.kind === "choice" && !dimension.values.includes(option.value)) add(`${path}.options.${key}`, "option_value_invalid");
+      if (dimension.kind === "quantity" && option.kind === "quantity"
+        && (option.value.dimension !== dimension.dimension || !dimension.units.includes(option.value.unit)
+          || !validateCatalogQuantity(option.value, definition))) add(`${path}.options.${key}`, "option_quantity_invalid");
+    }
+    const absent = product.dimensions.filter((key) => !Object.prototype.hasOwnProperty.call(sku.options, key));
+    absent.forEach((key) => missing(`${path}.options.${key}`, "option_missing"));
+    if (!absent.length && optionKeys.length === product.dimensions.length) {
+      const combination = JSON.stringify([...product.dimensions].sort().map((key) => [key, canonicalCatalogOption(sku.options[key])]));
+      if (combinations.has(combination)) add(`${path}.options`, "duplicate_option_combination");
+      combinations.add(combination);
+    }
+    if (sku.netContent) {
+      if (!validateCatalogQuantity(sku.netContent, definition) || !definition.netContentUnits.includes(sku.netContent.unit)) add(`${path}.netContent`, "net_content_invalid");
+    } else missing(`${path}.netContent`, "net_content_missing");
+    const netContentOption = netContentKey === undefined ? undefined : sku.options[netContentKey];
+    if (netContentOption?.kind === "quantity" && sku.netContent
+      && canonicalCatalogOption(netContentOption) !== canonicalCatalogOption({ kind: "quantity", value: sku.netContent })) add(`${path}.options.${netContentKey}`, "net_content_option_mismatch");
+    if (sku.grossMass && (sku.grossMass.dimension !== "mass" || !validateCatalogQuantity(sku.grossMass, definition))) add(`${path}.grossMass`, "gross_mass_invalid");
+    (sku.identifiers ?? []).forEach((identifier, identifierIndex) => {
+      const at = `${path}.identifiers.${identifierIndex}`;
+      // One GTIN is one identity in any 8-, 12-, 13- or 14-digit spelling, whatever its issuer text.
+      const gtin = identifier.scheme === "gs1:gtin" && isValidGtin(identifier.value) ? identifier.value.padStart(14, "0") : null;
+      const identity = JSON.stringify(gtin === null ? [identifier.scheme, identifier.issuer, identifier.value] : [identifier.scheme, gtin]);
+      if (identifiers.has(identity)) add(at, "duplicate_trade_identifier");
+      identifiers.add(identity);
+      if (identifier.scheme === "gs1:gtin" && gtin === null) add(at, "trade_identifier_invalid");
+      if (identifier.scheme !== "gs1:gtin" && identifier.scheme.startsWith("gs1:")) add(at, "trade_identifier_scheme_unsupported");
+      // Checked here, not in the wire schema, so a stored revision without a quantity stays readable.
+      if (identifier.packagingLevel === "case" ? (identifier.quantity ?? 0) < 2 : (identifier.quantity ?? 1) !== 1) add(`${at}.quantity`, "trade_identifier_quantity_invalid");
+    });
+    if (!sku.identifiers?.length) commercial.push({ path: `${path}.identifiers`, code: "channel_identity_not_assessed" });
+    if (!sku.identifiers?.some((identifier) => identifier.scheme === "gs1:gtin" && identifier.packagingLevel === "unit")) commercial.push({ path: `${path}.identifiers`, code: "unit_trade_identifier_missing" });
+    if (!sku.priceRef) commercial.push({ path: `${path}.priceRef`, code: "price_reference_missing" });
+    if (!sku.logisticsRef) commercial.push({ path: `${path}.logisticsRef`, code: "logistics_reference_missing" });
+  });
+  if (issues.length) return { valid: false, issues };
+  // Opaque references are not current pricing, stock, logistics or publication proof.
+  commercial.push({ path: "skus", code: "commercial_activation_not_assessed" });
+  return { valid: true, readiness: {
+    publication: { status: publication.length ? "incomplete" : "not_assessed", issues: publication },
+    commercial: { status: "inactive", issues: commercial },
+  } };
+}

package/src/catalog/foundationSchemas.ts

@@ -0,0 +1,123 @@
+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";
+export type { CatalogDocumentRevisionRef, CatalogSkuIdentifier, CatalogSkuEnvelopeSelector, NeutralSkuEnvelopeV1, CatalogPriceContext, CatalogSkuAuthorityRefusal } 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<string>();
+  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/src/catalog/index.ts

@@ -0,0 +1,43 @@
+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";

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