@openlup/platform 0.17.0 → 0.19.0

package/dist/catalog/draftSchemas.js

@@ -0,0 +1,89 @@
+import { z } from "./validation.js";
+import { CATALOG_DRAFT_MAX_PAGE, canonicalCatalogDraftJson } from "./contracts/draft.js";
+export { CATALOG_DRAFT_MAX_BYTES, CATALOG_DRAFT_MAX_PAGE, canonicalCatalogDraftJson } from "./contracts/draft.js";
+import { catalogDocumentRevisionRefSchema } from "./foundationSchemas.js";
+import { catalogDimensionKeySchema, catalogNamespacedKeySchema, catalogOptionValueSchema, catalogProductTypeRefSchema, catalogQuantitySchema, } from "./productTypeSchemas.js";
+const id = z.guid().refine((value) => value === value.toLowerCase(), "UUID must be lowercase");
+const reference = z.string().min(1).max(240).refine((value) => value.trim() === value);
+const code = z.string().min(1).max(160).regex(/^[A-Za-z0-9._:-]+$/u);
+const revision = z.number().int().min(0).max(2_147_483_646);
+const persistedRevision = z.number().int().positive().max(2_147_483_647);
+const commandKey = reference;
+const jsonContent = z.unknown().refine((value) => value !== undefined, "content must be JSON");
+export const catalogDraftPayloadSchema = z.object({
+    schemaVersion: z.literal(1),
+    product: z.object({
+        id, type: catalogProductTypeRefSchema, slug: code.optional(), primarySkuId: id.optional(),
+        dimensions: z.array(catalogDimensionKeySchema).max(16),
+        sharedContent: jsonContent.optional(), documentRevision: catalogDocumentRevisionRefSchema.optional(),
+    }).strict(),
+    skus: z.array(z.object({
+        id, productId: id, code: code.optional(),
+        options: z.record(catalogDimensionKeySchema, catalogOptionValueSchema),
+        netContent: catalogQuantitySchema.optional(),
+        identifiers: z.array(z.object({
+            scheme: catalogNamespacedKeySchema, issuer: reference, value: z.string().min(1).max(128),
+            packagingLevel: z.enum(["unit", "case"]), quantity: z.number().int().min(1).max(2_147_483_647).optional(),
+        }).strict()).max(32).optional(),
+        assetRefs: z.array(reference).max(32).optional(), grossMass: catalogQuantitySchema.optional(),
+        priceRef: reference.optional(), logisticsRef: reference.optional(),
+    }).strict()).max(10_000),
+}).strict().superRefine((payload, context) => {
+    try {
+        canonicalCatalogDraftJson(payload);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "payload must be bounded safe JSON" });
+    }
+    if (payload.product.documentRevision && payload.product.documentRevision.productId !== payload.product.id) {
+        context.addIssue({ code: "custom", path: ["product", "documentRevision", "productId"], message: "document must belong to product" });
+    }
+    if (payload.product.primarySkuId && !payload.skus.some((sku) => sku.id === payload.product.primarySkuId)) {
+        context.addIssue({ code: "custom", path: ["product", "primarySkuId"], message: "primary must belong to product" });
+    }
+    payload.skus.forEach((sku, index) => {
+        if (sku.productId !== payload.product.id)
+            context.addIssue({ code: "custom", path: ["skus", index, "productId"], message: "SKU must belong to product" });
+    });
+});
+export const catalogDraftCommandSchema = z.object({
+    schemaVersion: z.literal(1), action: z.enum(["create", "revise", "abandon"]),
+    draftId: id, commandKey, expectedRevision: revision, payload: catalogDraftPayloadSchema.optional(),
+}).strict().superRefine((command, context) => {
+    if ((command.action === "abandon") === (command.payload !== undefined)) {
+        context.addIssue({ code: "custom", path: ["payload"], message: "payload is required only for create and revise" });
+    }
+    if ((command.action === "create") !== (command.expectedRevision === 0)) {
+        context.addIssue({ code: "custom", path: ["expectedRevision"], message: "create starts at revision zero; other commands require a persisted revision" });
+    }
+});
+export const catalogDraftGetQuerySchema = z.object({
+    draftId: id, revision: persistedRevision.optional(), commandKey: commandKey.optional(),
+}).strict().refine((query) => query.revision === undefined || query.commandKey === undefined, "selectors are mutually exclusive");
+export const catalogDraftListQuerySchema = z.object({
+    afterDraftId: id.optional(), limit: z.number().int().min(1).max(CATALOG_DRAFT_MAX_PAGE),
+}).strict();
+export const catalogDraftSummarySchema = z.object({
+    draftId: id, productId: id, revision: persistedRevision, status: z.enum(["open", "abandoned"]),
+    commandKey, fingerprint: z.string().regex(/^[a-f0-9]{64}$/u), actorId: reference,
+    createdAt: z.string().datetime({ offset: true }),
+}).strict();
+export const catalogDraftRecordSchema = catalogDraftSummarySchema.extend({ payload: catalogDraftPayloadSchema }).strict()
+    .refine((record) => record.productId === record.payload.product.id, "record product must own payload");
+export const catalogDraftPageSchema = z.object({
+    items: z.array(catalogDraftSummarySchema).max(CATALOG_DRAFT_MAX_PAGE), nextCursor: id.nullable(),
+}).strict().superRefine((page, context) => {
+    const ids = page.items.map((item) => item.draftId);
+    if (ids.some((value, index) => index > 0 && value <= ids[index - 1])
+        || (page.nextCursor !== null && page.nextCursor !== ids[ids.length - 1])) {
+        context.addIssue({ code: "custom", message: "page must have ordered unique heads and a matching cursor" });
+    }
+});
+export const catalogDraftRefusalSchema = z.object({
+    outcome: z.enum(["conflict", "validation_issue", "unauthorized", "dependency_unavailable"]),
+    reason: z.string().min(1).max(160).regex(/^[a-z][a-z0-9_]*$/u), currentRevision: z.number().int().min(0).max(2_147_483_647).optional(),
+}).strict();
+export const catalogDraftApplyResultSchema = z.union([
+    z.object({ outcome: z.enum(["committed", "replayed"]), record: catalogDraftRecordSchema }).strict(),
+    catalogDraftRefusalSchema,
+]);

package/dist/catalog/draftValidation.d.ts

@@ -0,0 +1,21 @@
+import type { CatalogDraftPayload } from "./draftSchemas.js";
+import { 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 declare function validateCatalogDraft(payload: CatalogDraftPayload, registry: CatalogProductTypeRegistry): CatalogDraftValidation;

package/dist/catalog/draftValidation.js

@@ -0,0 +1,125 @@
+import { isValidGtin } from "./foundationSchemas.js";
+import { canonicalCatalogOption, validateCatalogQuantity, } from "./productTypeSchemas.js";
+/** Supplied facts must be true; absent publish-time facts remain draft readiness issues. */
+export function validateCatalogDraft(payload, registry) {
+    const issues = [];
+    const publication = [];
+    const commercial = [];
+    const add = (path, code) => issues.push({ path, code });
+    const missing = (path, code) => 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();
+    const skuCodes = new Set();
+    const combinations = new Set();
+    const identifiers = new Set();
+    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/dist/catalog/effectiveBundleCatalogQueries.d.ts

@@ -0,0 +1,8 @@
+export declare const COMPONENT_SQL: string;
+export declare const FEED_COMPONENT_SQL: string;
+export declare const PRICE_SQL = "\n  SELECT p.mode, p.price_list_id, p.target_price_minor, list.currency, p.amount_kind, p.active, p.valid_from, p.valid_to\n  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n  WHERE p.bundle_id = $1::uuid ORDER BY p.valid_from DESC";
+export declare const OWN_LIST_SQL = "\n  SELECT list.id, list.currency, list.region_code, p.mode\n  FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n  WHERE p.bundle_id = $1::uuid AND p.active AND p.amount_kind = 'gross'\n    AND (p.mode = $2::text OR p.mode = 'any') AND list.status = 'active'\n    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)\n    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)\n  ORDER BY p.valid_from DESC";
+export declare const CURRENCY_LIST_SQL = "\n  SELECT id, currency, region_code FROM public.price_lists\n  WHERE currency = $1::text AND status = 'active' AND ($2::text IS NULL OR region_code = $2::text)\n    AND valid_from <= $3::timestamptz AND (valid_to IS NULL OR valid_to > $3::timestamptz)";
+export declare const FEED_SQL = "\n  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\n  FROM public.catalog_bundles b\n  JOIN public.catalog_bundle_prices p ON p.bundle_id = b.id AND p.active\n  JOIN public.price_lists list ON list.id = p.price_list_id\n  WHERE b.status = 'active' AND p.amount_kind = 'gross' AND p.target_price_minor > 0\n    AND list.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)\n    AND ($2::text IS NULL OR list.region_code = $2::text) AND (p.mode = $4::text OR p.mode = 'any')\n    AND p.valid_from <= $3::timestamptz AND (p.valid_to IS NULL OR p.valid_to > $3::timestamptz)\n    AND list.valid_from <= $3::timestamptz AND (list.valid_to IS NULL OR list.valid_to > $3::timestamptz)\n  ORDER BY b.code, p.valid_from DESC";
+export declare const DETAIL_SQL = "SELECT b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,\n  b.composition_constraint, b.metadata,\n  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id) AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n    WHERE p.bundle_id = b.id AND p.active AND p.amount_kind = 'gross' AND p.target_price_minor > 0\n      AND p.mode IN ('one_time', 'any') AND list.status = 'active'\n      AND p.valid_from <= CURRENT_TIMESTAMP AND (p.valid_to IS NULL OR p.valid_to > CURRENT_TIMESTAMP)\n      AND list.valid_from <= CURRENT_TIMESTAMP AND (list.valid_to IS NULL OR list.valid_to > CURRENT_TIMESTAMP)) AS has_active_target_price FROM public.catalog_bundles b WHERE b.code = $1";
+export declare const LIST_SQL = "SELECT b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,\n  b.composition_constraint, b.metadata,\n  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id) AS component_count,\n  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p JOIN public.price_lists list ON list.id = p.price_list_id\n    WHERE p.bundle_id = b.id AND p.active AND p.amount_kind = 'gross' AND p.target_price_minor > 0\n      AND p.mode IN ('one_time', 'any') AND list.status = 'active'\n      AND p.valid_from <= CURRENT_TIMESTAMP AND (p.valid_to IS NULL OR p.valid_to > CURRENT_TIMESTAMP)\n      AND list.valid_from <= CURRENT_TIMESTAMP AND (list.valid_to IS NULL OR list.valid_to > CURRENT_TIMESTAMP)) AS has_active_target_price FROM public.catalog_bundles b\n  WHERE ($1::text = 'all' OR b.status = $1::text)\n    AND ($2::text IS NULL OR b.code ILIKE '%' || $2 || '%' OR b.title ILIKE '%' || $2 || '%')\n  ORDER BY b.code LIMIT $3 OFFSET $4";

package/dist/catalog/effectiveBundleCatalogQueries.js

@@ -0,0 +1,79 @@
+/** 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/dist/catalog/effectiveBundleCatalogStore.d.ts

@@ -0,0 +1,4 @@
+import type { PgQueryExecutor } from "../data/index.js";
+import { type BundleCatalogReadPort } from "./bundleCatalogReadPort.js";
+/** Selected only by the explicit effective-authority option. */
+export declare function createEffectiveBundleCatalogStore(executor: PgQueryExecutor, incumbent: BundleCatalogReadPort): BundleCatalogReadPort;

package/dist/catalog/effectiveBundleCatalogStore.js

@@ -0,0 +1,156 @@
+import { assertPrimaryUnitGtinAuthority } from "./contracts/foundation.js";
+import { BundleCatalogReadError } 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";
+/** Selected only by the explicit effective-authority option. */
+export function createEffectiveBundleCatalogStore(executor, incumbent) {
+    async function rows(sql, values) {
+        const result = await executor.query(sql, values).catch((error) => {
+            throw new BundleCatalogReadError(error instanceof Error ? error.message : String(error));
+        });
+        return (result.rows ?? []);
+    }
+    async function selectPriceList(bundleId, input) {
+        const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+        const own = input.currency ? [] : await rows(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(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(LIST_SQL, [...filter, input.limit, input.offset]),
+                rows(COUNT_SQL, filter),
+            ]);
+            return { bundles: page.map(toSummary), total: Number(counted[0]?.total ?? page.length) };
+        },
+        async getBundle(input) {
+            const bundle = (await rows(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(COMPONENT_SQL, [bundle.id, list?.id ?? null, atTime, input.mode ?? "one_time"]).then(rows => rows.map(toComponent)),
+                rows(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(FEED_SQL, [input.currency ?? null, input.regionCode ?? null, atTime, mode]);
+            const selected = new Map();
+            const listReads = new Map();
+            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(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(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) {
+    const grouped = new Map();
+    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) {
+    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) {
+    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) {
+    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) {
+    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 ?? {}),
+    };
+}
+function componentReady(row, mode) {
+    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/dist/catalog/foundationSchemas.d.ts

@@ -0,0 +1,98 @@
+import { z } from "./validation.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";
+export declare const catalogFixedPointSchema: z.ZodObject<{
+    unscaled: z.ZodNumber;
+    scale: z.ZodNumber;
+    unit: z.ZodString;
+}, z.core.$strict>;
+export declare const catalogDocumentRevisionRefSchema: z.ZodObject<{
+    id: z.ZodGUID;
+    productId: z.ZodGUID;
+    revisionNo: z.ZodNumber;
+    schemaId: z.ZodString;
+    documentRef: z.ZodString;
+    sourceRef: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+export declare const catalogSkuIdentifierSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    normalizedValue: z.ZodString;
+    kind: z.ZodEnum<{
+        gtin: "gtin";
+        other: "other";
+    }>;
+    packKind: z.ZodEnum<{
+        unit: "unit";
+        collective: "collective";
+    }>;
+    packQuantity: z.ZodNumber;
+    isPrimary: z.ZodBoolean;
+}, z.core.$strict>;
+/** Stable, payload-free detail selectors shared by both catalog adapters. */
+export declare const catalogSkuEnvelopeSelectorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"sku_code">;
+    skuCode: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"primary_product_slug">;
+    productSlug: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const neutralSkuEnvelopeV1Schema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"catalog.foundation.v1">;
+    product: z.ZodObject<{
+        id: z.ZodGUID;
+        slug: z.ZodString;
+        primarySkuId: z.ZodGUID;
+    }, z.core.$strict>;
+    sku: z.ZodObject<{
+        id: z.ZodGUID;
+        productId: z.ZodGUID;
+        code: z.ZodString;
+        netContent: z.ZodObject<{
+            unscaled: z.ZodNumber;
+            scale: z.ZodNumber;
+            unit: z.ZodString;
+        }, z.core.$strict>;
+        sellability: z.ZodObject<{
+            status: z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                archived: "archived";
+            }>;
+            oneTime: z.ZodBoolean;
+            subscription: z.ZodBoolean;
+        }, z.core.$strict>;
+        isAddon: z.ZodBoolean;
+        assetRef: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    documentRevision: z.ZodObject<{
+        id: z.ZodGUID;
+        productId: z.ZodGUID;
+        revisionNo: z.ZodNumber;
+        schemaId: z.ZodString;
+        documentRef: z.ZodString;
+        sourceRef: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    identifiers: z.ZodArray<z.ZodObject<{
+        issuer: z.ZodString;
+        normalizedValue: z.ZodString;
+        kind: z.ZodEnum<{
+            gtin: "gtin";
+            other: "other";
+        }>;
+        packKind: z.ZodEnum<{
+            unit: "unit";
+            collective: "collective";
+        }>;
+        packQuantity: z.ZodNumber;
+        isPrimary: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const catalogPriceContextSchema: z.ZodObject<{
+    priceListId: z.ZodGUID;
+    regionCode: z.ZodString;
+    currency: z.ZodString;
+    channel: z.ZodString;
+    atTime: z.ZodString;
+}, z.core.$strict>;