@openlup/platform 0.17.0 → 0.19.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/effectiveBundleCatalogQueries.ts

@@ -0,0 +1,80 @@
+/** Effective-authority SQL is isolated from the incumbent exported statements. */
+const ANCHORS = `SELECT pe.unit_price_minor FROM public.price_entries pe
+  WHERE pe.variant_id = s.id AND pe.price_list_id = %LIST% AND pe.active
+    AND pe.min_qty = 1 AND pe.amount_kind = 'gross'
+    AND pe.valid_from <= $3::timestamptz AND (pe.valid_to IS NULL OR pe.valid_to > $3::timestamptz)
+    AND (pe.mode = $4::text OR (pe.mode = 'any' AND NOT EXISTS (
+      SELECT 1 FROM public.price_entries exact WHERE exact.variant_id = s.id
+        AND exact.price_list_id = pe.price_list_id AND exact.active AND exact.min_qty = 1
+        AND exact.amount_kind = 'gross' AND exact.mode = $4::text
+        AND exact.valid_from <= $3::timestamptz AND (exact.valid_to IS NULL OR exact.valid_to > $3::timestamptz))))`;
+const FACTS = `s.status AS sku_status, s.sellable_standalone, s.sellable_in_subscription,
+  s.net_weight_g, pr.status AS product_status,
+  (pr.primary_sku_id IS NOT NULL AND revision.id IS NOT NULL) AS document_ready,
+  COALESCE((SELECT jsonb_agg(jsonb_build_object('issuer', identifier.issuer, 'normalizedValue', identifier.normalized_value,
+    'kind', identifier.identifier_kind, 'packKind', identifier.pack_kind, 'packQuantity', identifier.quantity, 'isPrimary', identifier.is_primary))
+    FROM public.catalog_sku_identifiers identifier WHERE identifier.catalog_sku_id = s.id), '[]'::jsonb) AS identifiers`;
+const REFERENCE = `(SELECT (array_agg(candidate.unit_price_minor))[1] FROM (${ANCHORS}) candidate)`;
+const COUNT = `(SELECT count(*) FROM (${ANCHORS}) candidate)`;
+export const COMPONENT_SQL = `
+  SELECT c.bundle_id, s.sku, s.title, pr.slug AS product_slug, s.id AS variant_id,
+    c.quantity, c.is_addon, c.sort_order, ${FACTS},
+    ${REFERENCE.replace("%LIST%", "$2::uuid")} AS reference_unit_price_minor,
+    ${COUNT.replace("%LIST%", "$2::uuid")} AS reference_price_count
+  FROM public.catalog_bundle_components c
+  JOIN public.catalog_skus s ON s.id = c.catalog_sku_id
+  JOIN public.catalog_products pr ON pr.id = s.product_id
+  LEFT JOIN public.catalog_product_document_revisions revision ON revision.id = pr.current_document_revision_id AND revision.product_id = pr.id
+  WHERE c.bundle_id = $1::uuid ORDER BY c.sort_order, s.sku`;
+export const FEED_COMPONENT_SQL = `
+  SELECT c.bundle_id, s.sku, s.title, pr.slug AS product_slug, s.id AS variant_id,
+    c.quantity, c.is_addon, c.sort_order, ${FACTS},
+    ${REFERENCE.replace("%LIST%", "selected.price_list_id")} AS reference_unit_price_minor,
+    ${COUNT.replace("%LIST%", "selected.price_list_id")} AS reference_price_count
+  FROM unnest($1::uuid[], $2::uuid[]) AS selected(bundle_id, price_list_id)
+  JOIN public.catalog_bundle_components c ON c.bundle_id = selected.bundle_id
+  JOIN public.catalog_skus s ON s.id = c.catalog_sku_id
+  JOIN public.catalog_products pr ON pr.id = s.product_id
+  LEFT JOIN public.catalog_product_document_revisions revision ON revision.id = pr.current_document_revision_id AND revision.product_id = pr.id
+  ORDER BY c.bundle_id, c.sort_order, s.sku`;
+export const PRICE_SQL = `
+  SELECT p.mode, p.price_list_id, p.target_price_minor, list.currency, p.amount_kind, p.active, p.valid_from, p.valid_to
+  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id
+  WHERE p.bundle_id = $1::uuid ORDER BY p.valid_from DESC`;
+export const OWN_LIST_SQL = `
+  SELECT list.id, list.currency, list.region_code, p.mode
+  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id
+  WHERE p.bundle_id = $1::uuid AND p.active AND p.amount_kind = 'gross'
+    AND (p.mode = $2::text OR p.mode = 'any') AND list.status = 'active'
+    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)
+    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)
+  ORDER BY p.valid_from DESC`;
+export const CURRENCY_LIST_SQL = `
+  SELECT id, currency, region_code FROM public.price_lists
+  WHERE currency = $1::text AND status = 'active' AND ($2::text IS NULL OR region_code = $2::text)
+    AND valid_from <= $3::timestamptz AND (valid_to IS NULL OR valid_to > $3::timestamptz)`;
+export const FEED_SQL = `
+  SELECT b.id, b.code, b.title, b.fulfillment_mode, p.mode, p.target_price_minor, p.price_list_id, list.currency, list.region_code
+  FROM public.catalog_bundles b
+  JOIN public.catalog_bundle_prices p ON p.bundle_id = b.id AND p.active
+  JOIN public.price_lists list ON list.id = p.price_list_id
+  WHERE b.status = 'active' AND p.amount_kind = 'gross' AND p.target_price_minor > 0
+    AND list.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)
+    AND ($2::text IS NULL OR list.region_code = $2::text) AND (p.mode = $4::text OR p.mode = 'any')
+    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)
+    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)
+  ORDER BY b.code, p.valid_from DESC`;
+
+const SUMMARY_COLUMNS = `b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,
+  b.composition_constraint, b.metadata,
+  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id) AS component_count,
+  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id
+    WHERE p.bundle_id = b.id AND p.active AND p.amount_kind = 'gross' AND p.target_price_minor > 0
+      AND p.mode IN ('one_time', 'any') AND list.status = 'active'
+      AND p.valid_from <= CURRENT_TIMESTAMP AND (p.valid_to IS NULL OR p.valid_to > CURRENT_TIMESTAMP)
+      AND list.valid_from <= CURRENT_TIMESTAMP AND (list.valid_to IS NULL OR list.valid_to > CURRENT_TIMESTAMP)) AS has_active_target_price`;
+export const DETAIL_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b WHERE b.code = $1`;
+export const LIST_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b
+  WHERE ($1::text = 'all' OR b.status = $1::text)
+    AND ($2::text IS NULL OR b.code ILIKE '%' || $2 || '%' OR b.title ILIKE '%' || $2 || '%')
+  ORDER BY b.code LIMIT $3 OFFSET $4`;

package/src/catalog/effectiveBundleCatalogStore.ts

@@ -0,0 +1,208 @@
+import type { PgQueryExecutor } from "../data/index.js";
+import { assertPrimaryUnitGtinAuthority, type CatalogSkuIdentifier } from "./contracts/foundation.js";
+import { BundleCatalogReadError, type BundleCatalogReadPort, type BundleComponentRow, type BundleSummary, type GetBundleInput } from "./bundleCatalogReadPort.js";
+import { uniqueBundlePrice, selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";
+import { COUNT_SQL } from "./bundleCatalogQueries.js";
+import { LIST_SQL, DETAIL_SQL, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL } from "./effectiveBundleCatalogQueries.js";
+
+interface BundleRow {
+  id: string;
+  code: string;
+  title: string;
+  status: string;
+  fulfillment_mode: string;
+  updated_at: string;
+  component_count: string | number;
+  has_active_target_price: boolean;
+  composition_constraint: Record<string, unknown> | null;
+  metadata: Record<string, unknown> | null;
+}
+
+interface ComponentRow {
+  bundle_id: string;
+  sku: string;
+  title: string | null;
+  product_slug: string;
+  variant_id: string;
+  quantity: number;
+  is_addon: boolean;
+  sort_order: number;
+  reference_unit_price_minor: number | null;
+  reference_price_count: number | string;
+  sku_status: string;
+  product_status: string;
+  net_weight_g: number;
+  sellable_standalone: boolean;
+  sellable_in_subscription: boolean;
+  document_ready: boolean;
+  identifiers: CatalogSkuIdentifier[];
+}
+
+interface PriceRow {
+  price_list_id: string;
+  mode: string;
+  target_price_minor: number;
+  currency: string;
+  amount_kind: string;
+  active: boolean;
+  valid_from: string;
+  valid_to: string | null;
+}
+
+interface ActiveBundleRow {
+  id: string;
+  code: string;
+  title: string;
+  fulfillment_mode: string;
+  mode: string;
+  target_price_minor: number;
+  price_list_id: string;
+  currency: string;
+  region_code: string;
+}
+
+
+/** Selected only by the explicit effective-authority option. */
+export function createEffectiveBundleCatalogStore(executor: PgQueryExecutor, incumbent: BundleCatalogReadPort): BundleCatalogReadPort {
+  async function rows<T>(sql: string, values: unknown[]): Promise<T[]> {
+    const result = await executor.query(sql, values).catch((error: unknown) => {
+      throw new BundleCatalogReadError(error instanceof Error ? error.message : String(error));
+    });
+    return (result.rows ?? []) as unknown as T[];
+  }
+  async function selectPriceList(bundleId: string, input: GetBundleInput): Promise<{ id: string; currency: string } | null> {
+    const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+    const own = input.currency ? [] : await rows<{ id: string; currency: string; region_code: string; mode: string }>(OWN_LIST_SQL, [bundleId, mode, atTime]);
+    const chosenPrice = uniqueBundlePrice(own, mode), chosen = chosenPrice ? [chosenPrice] : [];
+    const currency = input.currency ?? chosen[0]?.currency;
+    if (!currency) return null;
+    const candidates = await rows<{ id: string; currency: string }>(CURRENCY_LIST_SQL, [currency, input.regionCode ?? chosen[0]?.region_code ?? null, atTime]);
+    if (candidates.length > 1) throw new BundleCatalogReadError("bundle_price_list_ambiguous");
+    if (chosen[0] && candidates[0] && chosen[0].id !== candidates[0].id) throw new BundleCatalogReadError("bundle_price_list_changed");
+    return candidates[0] ?? null;
+  }
+  return {
+    ...incumbent,
+    async listBundles(input) {
+      const filter = [input.status, input.query ?? null];
+      const [page, counted] = await Promise.all([
+        rows<BundleRow>(LIST_SQL, [...filter, input.limit, input.offset]),
+        rows<{ total: string | number }>(COUNT_SQL, filter),
+      ]);
+      return { bundles: page.map(toSummary), total: Number(counted[0]?.total ?? page.length) };
+    },
+    async getBundle(input) {
+      const bundle = (await rows<BundleRow>(DETAIL_SQL, [input.code]))[0];
+      if (!bundle) return null;
+      const atTime = input.atTime ?? new Date().toISOString();
+      const list = await selectPriceList(bundle.id, { ...input, atTime });
+      const [componentRows, priceRows] = await Promise.all([
+        rows<ComponentRow>(COMPONENT_SQL, [bundle.id, list?.id ?? null, atTime, input.mode ?? "one_time"]).then(rows => rows.map(toComponent)),
+        rows<PriceRow>(PRICE_SQL, [bundle.id]),
+      ]);
+      return {
+        ...toSummary(bundle), compositionConstraint: toConstraint(bundle.composition_constraint), metadata: bundle.metadata ?? {},
+        components: componentRows, prices: priceRows.map(toPrice),
+        resolvedTargetPrice: selectEffectiveBundleTargetPrice(priceRows.map(row => ({ price: toPrice(row), priceListId: row.price_list_id })),
+          { priceListId: list?.id ?? null, currency: list?.currency ?? null, mode: input.mode ?? "one_time", atTime }),
+        resolvedCurrency: list?.currency ?? null, resolvedPriceListId: list?.id ?? null,
+      };
+    },
+    async listActiveBundleCompositions(input = {}) {
+      const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+      const feed = await rows<ActiveBundleRow>(FEED_SQL, [input.currency ?? null, input.regionCode ?? null, atTime, mode]);
+      const selected = new Map<string, ActiveBundleRow>();
+      const listReads = new Map<string, Promise<{ id: string }[]>>();
+      for (const row of feed) {
+        const same = feed.filter(candidate => candidate.id === row.id);
+        const candidate = uniqueBundlePrice(same, mode)!;
+        const key = `${row.currency}:${row.region_code}`;
+        if (!listReads.has(key)) listReads.set(key, rows<{ id: string }>(CURRENCY_LIST_SQL, [row.currency, row.region_code ?? null, atTime]));
+        const lists = await listReads.get(key)!;
+        if (lists.length > 1) throw new BundleCatalogReadError("bundle_price_list_ambiguous");
+        if (lists[0]?.id !== row.price_list_id) throw new BundleCatalogReadError("bundle_price_list_changed");
+        selected.set(row.id, candidate);
+      }
+      if (!selected.size) return [];
+      const chosen = [...selected.values()];
+      const source = await rows<ComponentRow>(FEED_COMPONENT_SQL, [chosen.map(row => row.id), chosen.map(row => row.price_list_id), atTime, mode]);
+      const byBundle = groupComponents(source);
+      const sellable = chosen.filter(row => {
+        const components = source.filter(component => component.bundle_id === row.id);
+        return components.length > 0 && components.every(component => componentReady(component, mode));
+      });
+      return sellable.map(row => ({ code: row.code, title: row.title, fulfillmentMode: row.fulfillment_mode,
+        currency: row.currency, targetPriceMinor: row.target_price_minor, mode: row.mode, components: byBundle.get(row.id) ?? [] }));
+    },
+  };
+}
+
+function groupComponents(rows: readonly ComponentRow[]): Map<string, BundleComponentRow[]> {
+  const grouped = new Map<string, BundleComponentRow[]>();
+  for (const row of rows) {
+    const bucket = grouped.get(row.bundle_id) ?? [];
+    bucket.push(toComponent(row));
+    grouped.set(row.bundle_id, bucket);
+  }
+  return grouped;
+}
+
+function toComponent(row: ComponentRow): BundleComponentRow {
+  if (Number(row.reference_price_count) > 1) throw new BundleCatalogReadError("bundle_price_ambiguous");
+  return {
+    sku: row.sku,
+    title: row.title ?? null,
+    productSlug: row.product_slug,
+    variantId: row.variant_id,
+    quantity: Number(row.quantity),
+    isAddon: row.is_addon === true,
+    sortOrder: Number(row.sort_order),
+    referenceUnitPriceMinor:
+      row.reference_unit_price_minor === null || row.reference_unit_price_minor === undefined
+        ? null
+        : Number(row.reference_unit_price_minor),
+  };
+}
+
+function toSummary(row: BundleRow): BundleSummary {
+  return {
+    code: row.code,
+    title: row.title,
+    status: row.status,
+    fulfillmentMode: row.fulfillment_mode,
+    componentCount: Number(row.component_count ?? 0),
+    hasActiveTargetPrice: row.has_active_target_price === true,
+    updatedAt: row.updated_at,
+  };
+}
+
+function toPrice(row: PriceRow) {
+  return {
+    mode: row.mode,
+    targetPriceMinor: Number(row.target_price_minor),
+    currency: row.currency,
+    amountKind: row.amount_kind,
+    active: row.active === true,
+    validFrom: row.valid_from,
+    validTo: row.valid_to ?? null,
+  };
+}
+
+/** An empty envelope is stored as `{}`; that is "unconstrained", not a constraint. */
+function toConstraint(value: Record<string, unknown> | null) {
+  if (!value || typeof value.kind !== "string" || value.kind.trim() === "") return null;
+  return {
+    kind: value.kind,
+    version: typeof value.version === "number" ? value.version : 0,
+    data: (value.data ?? {}) as Record<string, unknown>,
+  };
+}
+
+function componentReady(row: ComponentRow, mode: string): boolean {
+  try { assertPrimaryUnitGtinAuthority(row.identifiers); } catch { return false; }
+  return row.sku_status === "active" && row.product_status === "active" && row.document_ready === true
+    && Number.isSafeInteger(row.net_weight_g) && row.net_weight_g > 0
+    && (mode === "subscription" ? row.sellable_in_subscription : row.sellable_standalone)
+    && row.reference_unit_price_minor !== null && Number.isSafeInteger(Number(row.reference_unit_price_minor))
+    && Number(row.reference_unit_price_minor) > 0;
+}

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,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";