@openlup/platform 0.16.0 → 0.18.0

package/dist/catalog/bundleRuleCodes.d.ts

@@ -0,0 +1,41 @@
+import type { BundleAllocationFailureCode } from "@openlup/core/pricing";
+/**
+ * Bundle write rules — the named, enforced invariants of the agent-operable
+ * bundle write path. These codes are the single vocabulary shared by the request
+ * contracts, the pure rule predicates (`bundleRules.ts`), managed write routines
+ * and the over-the-wire error taxonomy. Managed routines re-derive state rules;
+ * native actor-kind enforcement relies on the handler, not an independent
+ * database gate.
+ *
+ * The catalog rules use this same shape; the lifecycle subset is expressed
+ * through the host lifecycle kit, and the codes stay here as
+ * this domain's registry.
+ */
+export declare const BUNDLE_RULE_CODES: readonly ["DRAFT_ONLY_FOR_MACHINE", "MIN_COMPONENTS", "ADDON_ONLY_COMPOSITION", "DUPLICATE_COMPONENT", "CODE_TAKEN", "COMPONENT_NOT_FOUND", "COMPONENT_NOT_SELLABLE", "COMPONENT_CURRENCY_MISMATCH", "TARGET_ABOVE_COMPONENT_SUM", "TARGET_BELOW_FLOOR", "PRICE_REQUIRED_TO_SELL", "COMPOSITION_REQUIRED_TO_SELL", "APPEND_ONLY_PRICE", "NO_HARD_DELETE", "RESTORE_REQUIRES_ARCHIVED", "DEACTIVATE_REQUIRES_ACTIVE", "FULFILLMENT_MODE_UNSUPPORTED", "CONSTRAINT_VALIDATION_FAILED", "CLONE_SOURCE_NOT_FOUND"];
+export type BundleRuleCode = (typeof BUNDLE_RULE_CODES)[number];
+/**
+ * The two target-price codes are NOT re-derived here — they are the kernel
+ * allocator's own failure vocabulary, projected onto this domain's registry.
+ *
+ * Declared as an exhaustive `Record` over `BundleAllocationFailureCode` on
+ * purpose: when `@openlup/core/pricing` learns a new failure code, this object
+ * stops compiling until the domain decides which rule it is. `REFERENCE_TOTAL_ZERO`
+ * means the composition weighed nothing, which is the same condition
+ * `MIN_COMPONENTS` names from the request side.
+ */
+export declare const BUNDLE_ALLOCATION_RULE_CODE: Record<BundleAllocationFailureCode, BundleRuleCode>;
+/**
+ * Which rules are decidable from the request alone (pure, pre-flight) and which
+ * are state-dependent and authoritatively enforced by the write routine. This
+ * documents intent and keeps the handler honest about what it can decide before
+ * the write. `CONSTRAINT_VALIDATION_FAILED` is `port`: it is decided by the
+ * injected `CompositionRulesPort`, which is neither the request nor the database.
+ */
+export declare const BUNDLE_RULE_ENFORCEMENT: Record<BundleRuleCode, "request" | "port" | "rpc">;
+export type BundleActorKind = "human" | "machine";
+export type BundleWriteOperation = "create_draft" | "update_draft" | "set_composition" | "set_target_price" | "archive" | "restore" | "clone_draft" | "activate" | "deactivate";
+/** The domain's rule result, projected from the generic kit `RuleResult`. */
+export type BundleRuleResult = {
+    ok: boolean;
+    violations: BundleRuleCode[];
+};

package/dist/catalog/bundleRuleCodes.js

@@ -0,0 +1,110 @@
+/**
+ * Bundle write rules — the named, enforced invariants of the agent-operable
+ * bundle write path. These codes are the single vocabulary shared by the request
+ * contracts, the pure rule predicates (`bundleRules.ts`), managed write routines
+ * and the over-the-wire error taxonomy. Managed routines re-derive state rules;
+ * native actor-kind enforcement relies on the handler, not an independent
+ * database gate.
+ *
+ * The catalog rules use this same shape; the lifecycle subset is expressed
+ * through the host lifecycle kit, and the codes stay here as
+ * this domain's registry.
+ */
+export const BUNDLE_RULE_CODES = [
+    // Machine (agent) actors compose, price and archive drafts, but may NOT
+    // activate or deactivate. Enforced by the handler (allowedActorKinds); the
+    // managed activate/deactivate routines also re-derive and RAISE it, while the
+    // native routines rely on the handler gate.
+    "DRAFT_ONLY_FOR_MACHINE",
+    // A bundle with no components is not a bill of materials. Request-decidable on
+    // the whole-set composition replace.
+    "MIN_COMPONENTS",
+    // Every component being an add-on leaves nothing that is always in the box.
+    // At least one non-addon component is required. Request-decidable.
+    "ADDON_ONLY_COMPOSITION",
+    // One row per unit per bundle: multiplicity is the quantity, never a repeated
+    // component. Request-decidable on the whole-set replace.
+    "DUPLICATE_COMPONENT",
+    // Creating a bundle whose code is already used is rejected (unique code).
+    "CODE_TAKEN",
+    // A composition entry naming a unit that does not exist is rejected.
+    "COMPONENT_NOT_FOUND",
+    // A component must itself be sellable: active AND sellable on its own. A bundle
+    // must not become the only way an unsellable unit reaches a customer.
+    "COMPONENT_NOT_SELLABLE",
+    // Every component must be priced in the currency of the bundle's price list;
+    // a mixed-currency bill of materials has no single reference total.
+    "COMPONENT_CURRENCY_MISMATCH",
+    // A bundle is never priced above the sum of its parts. Hard refusal, not a
+    // warning: the discount framing is the product, and the kernel allocator
+    // returns the same decision as one comparison.
+    "TARGET_ABOVE_COMPONENT_SUM",
+    // The target cannot cover every component's minimum payable amount.
+    "TARGET_BELOW_FLOOR",
+    // Activation requires an active target price on the bundle.
+    "PRICE_REQUIRED_TO_SELL",
+    // Activation requires a non-empty composition.
+    "COMPOSITION_REQUIRED_TO_SELL",
+    // Target-price changes INSERT a new price row and deactivate the old one; an
+    // existing row is never mutated in place.
+    "APPEND_ONLY_PRICE",
+    // A bundle referenced by an order or a subscription is never hard-deleted;
+    // removal is an archive (status flip).
+    "NO_HARD_DELETE",
+    // Restore is the inverse of archive: it applies only to an ARCHIVED bundle.
+    "RESTORE_REQUIRES_ARCHIVED",
+    // Deactivate (unpublish) applies only to a LIVE bundle.
+    "DEACTIVATE_REQUIRES_ACTIVE",
+    // Only the exploded fulfillment mode has a runtime. The stored column admits
+    // the pre-packed mode so it never has to be widened; the refusal lives here.
+    "FULFILLMENT_MODE_UNSUPPORTED",
+    // A non-empty composition constraint is validated by the injected
+    // CompositionRulesPort; its refusal surfaces under this code.
+    "CONSTRAINT_VALIDATION_FAILED",
+    // Clone reads its source before replaying a fresh draft; a missing source is
+    // rejected before the replay.
+    "CLONE_SOURCE_NOT_FOUND",
+];
+/**
+ * The two target-price codes are NOT re-derived here — they are the kernel
+ * allocator's own failure vocabulary, projected onto this domain's registry.
+ *
+ * Declared as an exhaustive `Record` over `BundleAllocationFailureCode` on
+ * purpose: when `@openlup/core/pricing` learns a new failure code, this object
+ * stops compiling until the domain decides which rule it is. `REFERENCE_TOTAL_ZERO`
+ * means the composition weighed nothing, which is the same condition
+ * `MIN_COMPONENTS` names from the request side.
+ */
+export const BUNDLE_ALLOCATION_RULE_CODE = {
+    REFERENCE_TOTAL_ZERO: "MIN_COMPONENTS",
+    TARGET_ABOVE_COMPONENT_SUM: "TARGET_ABOVE_COMPONENT_SUM",
+    TARGET_BELOW_FLOOR: "TARGET_BELOW_FLOOR",
+};
+/**
+ * Which rules are decidable from the request alone (pure, pre-flight) and which
+ * are state-dependent and authoritatively enforced by the write routine. This
+ * documents intent and keeps the handler honest about what it can decide before
+ * the write. `CONSTRAINT_VALIDATION_FAILED` is `port`: it is decided by the
+ * injected `CompositionRulesPort`, which is neither the request nor the database.
+ */
+export const BUNDLE_RULE_ENFORCEMENT = {
+    DRAFT_ONLY_FOR_MACHINE: "request",
+    MIN_COMPONENTS: "request",
+    ADDON_ONLY_COMPOSITION: "request",
+    DUPLICATE_COMPONENT: "request",
+    FULFILLMENT_MODE_UNSUPPORTED: "request",
+    CONSTRAINT_VALIDATION_FAILED: "port",
+    CODE_TAKEN: "rpc",
+    COMPONENT_NOT_FOUND: "rpc",
+    COMPONENT_NOT_SELLABLE: "rpc",
+    COMPONENT_CURRENCY_MISMATCH: "rpc",
+    TARGET_ABOVE_COMPONENT_SUM: "rpc",
+    TARGET_BELOW_FLOOR: "rpc",
+    PRICE_REQUIRED_TO_SELL: "rpc",
+    COMPOSITION_REQUIRED_TO_SELL: "rpc",
+    APPEND_ONLY_PRICE: "rpc",
+    NO_HARD_DELETE: "rpc",
+    RESTORE_REQUIRES_ARCHIVED: "rpc",
+    DEACTIVATE_REQUIRES_ACTIVE: "rpc",
+    CLONE_SOURCE_NOT_FOUND: "rpc",
+};

package/dist/catalog/bundleRules.d.ts

@@ -0,0 +1,69 @@
+import type { BundleComponentInput } from "@openlup/core/pricing";
+import type { CompositionConstraint, CompositionRulesPort } from "@openlup/core/bundle";
+import type { BundleRuleBindings } from "./bundleBindings.js";
+import { type BundleActorKind, type BundleRuleResult } from "./bundleRuleCodes.js";
+/**
+ * Pure, request-checkable bundle write rules.
+ *
+ * Only what is decidable from the request alone lives here. The state-dependent
+ * rules (code uniqueness, component existence/sellability/currency, the target
+ * price against real component prices, the activation preconditions, append-only
+ * pricing, archive-not-delete) are re-derived by the managed write routines.
+ * This layer fast-fails request-checkable violations without replacing those
+ * state checks. Actor-kind enforcement is separate: managed publication routines
+ * independently check it, while native publication relies on the handler gate.
+ */
+/** The composition shape the request-layer rules can reason about. */
+export interface BundleCompositionEntry {
+    readonly sku: string;
+    readonly quantity: number;
+    readonly isAddon: boolean;
+}
+/** The only fulfillment mode with a runtime. The column admits more; this does not. */
+export declare const SUPPORTED_BUNDLE_FULFILLMENT_MODES: readonly ["virtual"];
+export type SupportedBundleFulfillmentMode = (typeof SUPPORTED_BUNDLE_FULFILLMENT_MODES)[number];
+/**
+ * The lifecycle/actor gate every operation passes. Machine actors are confined to
+ * drafts: they may compose, price, archive, restore and clone, but neither
+ * activate nor deactivate.
+ */
+export declare function createBundleWriteRules({ assertActivateNotMachineActor }: Pick<BundleRuleBindings, "assertActivateNotMachineActor">): {
+    evaluateBundleWriteRules: (input: {
+        operation: string;
+        actorKind: BundleActorKind;
+    }) => BundleRuleResult;
+};
+/**
+ * Whole-set composition rules, decidable from the replacement set alone: it must
+ * carry at least one entry, at least one entry that is not an add-on, and no unit
+ * twice (multiplicity is the quantity, never a repeated row).
+ */
+export declare function evaluateBundleComposition(components: readonly BundleCompositionEntry[]): BundleRuleResult;
+/** The runtime refusal of every fulfillment mode the stored column admits but no code honours. */
+export declare function evaluateBundleFulfillmentMode(mode: string): BundleRuleResult;
+/**
+ * Project the kernel allocator's decision onto this domain's rule vocabulary.
+ *
+ * The allocator (`@openlup/core/pricing`) owns the arithmetic and the two
+ * refusals a target price can earn; this maps its failure code through the
+ * exhaustive `BUNDLE_ALLOCATION_RULE_CODE` table so the codes cannot drift apart.
+ * It is pure: the caller supplies the component reference prices it already holds.
+ * The authority for a committed write remains the write routine, which holds the
+ * live prices.
+ */
+export declare function evaluateBundleTargetPrice(input: {
+    components: readonly BundleComponentInput[];
+    targetPriceMinor: number;
+    minimumUnitPayableMinor?: number;
+}): BundleRuleResult;
+/** An empty envelope means "unconstrained"; there is nothing for the port to decide. */
+export declare function isEmptyCompositionConstraint(constraint: CompositionConstraint | null | undefined): boolean;
+/**
+ * Delegate a non-empty composition constraint to the injected rules port. The
+ * platform stores the envelope and never interprets it, so this domain does not
+ * either: it asks the adopter's port and reports the refusal under one code.
+ */
+export declare function evaluateBundleCompositionConstraint(port: CompositionRulesPort | undefined, input: {
+    readonly components: readonly BundleCompositionEntry[];
+    readonly constraint: CompositionConstraint | null | undefined;
+}): Promise<BundleRuleResult>;

package/dist/catalog/bundleRules.js

@@ -0,0 +1,102 @@
+import { allocateBundleTargetPrice } from "@openlup/core/pricing";
+import { BUNDLE_ALLOCATION_RULE_CODE, } from "./bundleRuleCodes.js";
+/** The only fulfillment mode with a runtime. The column admits more; this does not. */
+export const SUPPORTED_BUNDLE_FULFILLMENT_MODES = ["virtual"];
+function isSupportedFulfillmentMode(mode) {
+    return SUPPORTED_BUNDLE_FULFILLMENT_MODES.includes(mode);
+}
+/**
+ * The lifecycle/actor gate every operation passes. Machine actors are confined to
+ * drafts: they may compose, price, archive, restore and clone, but neither
+ * activate nor deactivate.
+ */
+export function createBundleWriteRules({ assertActivateNotMachineActor }) {
+    function evaluateBundleWriteRules(input) {
+        const violations = [];
+        const activateViolation = assertActivateNotMachineActor(input);
+        if (activateViolation)
+            violations.push(activateViolation);
+        // `assertActivateNotMachineActor` only knows the publish direction it was written
+        // for. Unpublish is the same class of transition and carries the same code.
+        if (input.operation === "deactivate" && input.actorKind === "machine") {
+            violations.push("DRAFT_ONLY_FOR_MACHINE");
+        }
+        return { ok: violations.length === 0, violations };
+    }
+    return { evaluateBundleWriteRules };
+}
+/**
+ * Whole-set composition rules, decidable from the replacement set alone: it must
+ * carry at least one entry, at least one entry that is not an add-on, and no unit
+ * twice (multiplicity is the quantity, never a repeated row).
+ */
+export function evaluateBundleComposition(components) {
+    const violations = [];
+    if (components.length === 0)
+        violations.push("MIN_COMPONENTS");
+    else if (components.every((component) => component.isAddon))
+        violations.push("ADDON_ONLY_COMPOSITION");
+    const seen = new Set();
+    for (const component of components) {
+        if (seen.has(component.sku)) {
+            violations.push("DUPLICATE_COMPONENT");
+            break;
+        }
+        seen.add(component.sku);
+    }
+    return { ok: violations.length === 0, violations };
+}
+/** The runtime refusal of every fulfillment mode the stored column admits but no code honours. */
+export function evaluateBundleFulfillmentMode(mode) {
+    return isSupportedFulfillmentMode(mode)
+        ? { ok: true, violations: [] }
+        : { ok: false, violations: ["FULFILLMENT_MODE_UNSUPPORTED"] };
+}
+/**
+ * Project the kernel allocator's decision onto this domain's rule vocabulary.
+ *
+ * The allocator (`@openlup/core/pricing`) owns the arithmetic and the two
+ * refusals a target price can earn; this maps its failure code through the
+ * exhaustive `BUNDLE_ALLOCATION_RULE_CODE` table so the codes cannot drift apart.
+ * It is pure: the caller supplies the component reference prices it already holds.
+ * The authority for a committed write remains the write routine, which holds the
+ * live prices.
+ */
+export function evaluateBundleTargetPrice(input) {
+    const outcome = allocateBundleTargetPrice({
+        components: input.components,
+        targetPriceMinor: input.targetPriceMinor,
+        ...(input.minimumUnitPayableMinor === undefined
+            ? {}
+            : { minimumUnitPayableMinor: input.minimumUnitPayableMinor }),
+    });
+    // Narrowed by presence rather than by the `ok` literal: the app compiler runs
+    // without strictNullChecks, where a boolean-literal discriminant does not narrow.
+    if (!("code" in outcome))
+        return { ok: true, violations: [] };
+    return { ok: false, violations: [BUNDLE_ALLOCATION_RULE_CODE[outcome.code]] };
+}
+/** An empty envelope means "unconstrained"; there is nothing for the port to decide. */
+export function isEmptyCompositionConstraint(constraint) {
+    return !constraint || constraint.kind.trim() === "";
+}
+/**
+ * Delegate a non-empty composition constraint to the injected rules port. The
+ * platform stores the envelope and never interprets it, so this domain does not
+ * either: it asks the adopter's port and reports the refusal under one code.
+ */
+export async function evaluateBundleCompositionConstraint(port, input) {
+    if (isEmptyCompositionConstraint(input.constraint) || !port)
+        return { ok: true, violations: [] };
+    const constraint = input.constraint;
+    const outcome = await port.validateComposition({
+        coreLines: input.components
+            .filter((component) => !component.isAddon)
+            .map((component) => ({ variantId: component.sku, qty: component.quantity, isAddon: false })),
+        addonLines: input.components
+            .filter((component) => component.isAddon)
+            .map((component) => ({ variantId: component.sku, qty: component.quantity, isAddon: true })),
+        constraint,
+    });
+    return outcome.ok ? { ok: true, violations: [] } : { ok: false, violations: ["CONSTRAINT_VALIDATION_FAILED"] };
+}

package/dist/catalog/catalogDraftStore.d.ts

@@ -0,0 +1,4 @@
+import { type CatalogDraftStorePort } from "./draftPorts.js";
+import type { PgQueryExecutor } from "../data/index.js";
+/** Dark owner-only storage. Composition must verify the operator before use. */
+export declare function createPostgresCatalogDraftStore(client: PgQueryExecutor): CatalogDraftStorePort;

package/dist/catalog/catalogDraftStore.js

@@ -0,0 +1,63 @@
+import { catalogDraftApplyResultSchema, catalogDraftGetQuerySchema, catalogDraftListQuerySchema, catalogDraftPageSchema, catalogDraftRecordSchema, } from "./draftSchemas.js";
+import { CatalogDraftStoreError } from "./draftPorts.js";
+/** Dark owner-only storage. Composition must verify the operator before use. */
+export function createPostgresCatalogDraftStore(client) {
+    async function call(sql, values) {
+        try {
+            const { rows } = await client.query(sql, values);
+            if (rows.length !== 1 || !("result" in rows[0])) {
+                throw new CatalogDraftStoreError({ outcome: "dependency_unavailable", reason: "invalid_store_response" });
+            }
+            return rows[0].result;
+        }
+        catch (error) {
+            if (error instanceof CatalogDraftStoreError)
+                throw error;
+            throw new CatalogDraftStoreError(refusal(error));
+        }
+    }
+    return {
+        async apply(request) {
+            try {
+                const result = await call("SELECT public.catalog_draft_apply($1::text, $2::text, $3::text) AS result", [request.canonicalCommand, request.fingerprint, request.actorId]);
+                const parsed = catalogDraftApplyResultSchema.safeParse(result);
+                if (!parsed.success)
+                    return { outcome: "dependency_unavailable", reason: "invalid_store_response" };
+                return parsed.data;
+            }
+            catch (error) {
+                return error instanceof CatalogDraftStoreError ? error.refusal : refusal(error);
+            }
+        },
+        async get(query) {
+            const input = catalogDraftGetQuerySchema.safeParse(query);
+            if (!input.success)
+                throw new CatalogDraftStoreError({ outcome: "validation_issue", reason: "invalid_get_query" });
+            const result = await call("SELECT public.catalog_draft_get($1::uuid, $2::integer, $3::text) AS result", [input.data.draftId, input.data.revision ?? null, input.data.commandKey ?? null]);
+            const parsed = catalogDraftRecordSchema.nullable().safeParse(result);
+            if (!parsed.success)
+                throw new CatalogDraftStoreError({ outcome: "dependency_unavailable", reason: "invalid_store_response" });
+            return parsed.data;
+        },
+        async list(query) {
+            const input = catalogDraftListQuerySchema.safeParse(query);
+            if (!input.success)
+                throw new CatalogDraftStoreError({ outcome: "validation_issue", reason: "invalid_list_query" });
+            const result = await call("SELECT public.catalog_draft_list($1::uuid, $2::integer) AS result", [input.data.afterDraftId ?? null, input.data.limit]);
+            const parsed = catalogDraftPageSchema.safeParse(result);
+            if (!parsed.success)
+                throw new CatalogDraftStoreError({ outcome: "dependency_unavailable", reason: "invalid_store_response" });
+            return parsed.data;
+        },
+    };
+}
+function refusal(error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : null;
+    if (code === "42501")
+        return { outcome: "unauthorized", reason: "operator_required" };
+    if (code === "22023")
+        return { outcome: "validation_issue", reason: "invalid_store_request" };
+    if (code === "23505")
+        return { outcome: "conflict", reason: "identity_reserved" };
+    return { outcome: "dependency_unavailable", reason: "store_unavailable" };
+}

package/dist/catalog/catalogSkuEnvelope.d.ts

@@ -0,0 +1,7 @@
+import type { PublicCatalogSkuEnvelopeReadPort } from "./readPorts.js";
+import type { PgQueryExecutor } from "../data/index.js";
+/**
+ * Portable W2a envelope reader. It reads only product/SKU/revision references
+ * and neutral identifiers; application document content never crosses this seam.
+ */
+export declare function createPostgresCatalogSkuEnvelopeReadPort(executor: PgQueryExecutor): PublicCatalogSkuEnvelopeReadPort;

package/dist/catalog/catalogSkuEnvelope.js

@@ -0,0 +1,142 @@
+import { CatalogSkuAuthorityError, catalogSkuEnvelopeSelectorSchema, } from "./foundationSchemas.js";
+import { parseCatalogActiveSkuSelection } from "./activeSkuSelection.js";
+import { mapPostgresCatalogSkuEnvelope, readPostgresCatalogSkuIdentifiers, requirePostgresCatalogSkuEnvelopeRow, } from "./catalogSkuEnvelopeMapper.js";
+const ENVELOPE_COLUMNS_SQL = `
+    product.id AS product_id,
+    product.slug AS product_slug,
+    product.primary_sku_id,
+    product.current_document_revision_id,
+    sku.id AS sku_id,
+    sku.product_id AS sku_product_id,
+    sku.sku AS sku_code,
+    sku.net_weight_g AS net_content_unscaled,
+    sku.status AS sku_status,
+    sku.sellable_standalone AS sellable_one_time,
+    sku.sellable_in_subscription AS sellable_subscription,
+    sku.is_addon,
+    sku.asset_ref,
+    revision.id AS document_revision_id,
+    revision.product_id AS document_product_id,
+    revision.revision_no AS document_revision_no,
+    revision.schema_id AS document_schema_id,
+    revision.document_ref AS document_ref,
+    revision.source_ref AS document_source_ref,
+    revision.digest AS document_digest`;
+const SKU_ENVELOPE_FROM_SQL = `
+  SELECT ${ENVELOPE_COLUMNS_SQL}
+  FROM public.catalog_skus AS sku
+  JOIN public.catalog_products AS product
+    ON product.id = sku.product_id
+  LEFT JOIN public.catalog_product_document_revisions AS revision
+    ON revision.id = product.current_document_revision_id`;
+const LIST_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE ($1::uuid IS NULL OR sku.id > $1::uuid)
+  ORDER BY sku.id
+  LIMIT $2::integer`;
+const LIST_ACTIVE_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.status = 'active'
+    AND (sku.sellable_standalone OR sku.sellable_in_subscription)
+    AND ($3::text[] IS NULL OR sku.sku = ANY($3::text[]))
+    AND ($1::uuid IS NULL OR sku.id > $1::uuid)
+  ORDER BY sku.id
+  LIMIT $2::integer`;
+const LIST_PUBLIC_ACTIVE_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.status = 'active'
+    AND ($1::uuid IS NULL OR sku.id > $1::uuid)
+  ORDER BY sku.id
+  LIMIT $2::integer`;
+const LIST_PUBLIC_ACTIVE_PRODUCT_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.product_id = $1::uuid
+    AND sku.status = 'active'
+    AND ($2::uuid IS NULL OR sku.id > $2::uuid)
+  ORDER BY sku.id
+  LIMIT $3::integer`;
+const DETAIL_ENVELOPE_BY_ID_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.id = $1::uuid`;
+const DETAIL_ENVELOPE_BY_SKU_CODE_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.sku = $1
+  LIMIT 2`;
+const DETAIL_ENVELOPE_BY_PRIMARY_PRODUCT_SLUG_SQL = `
+  SELECT ${ENVELOPE_COLUMNS_SQL}
+  FROM public.catalog_products AS product
+  LEFT JOIN public.catalog_skus AS sku
+    ON sku.id = product.primary_sku_id
+  LEFT JOIN public.catalog_product_document_revisions AS revision
+    ON revision.id = product.current_document_revision_id
+  WHERE product.slug = $1
+  LIMIT 2`;
+/**
+ * Portable W2a envelope reader. It reads only product/SKU/revision references
+ * and neutral identifiers; application document content never crosses this seam.
+ */
+export function createPostgresCatalogSkuEnvelopeReadPort(executor) {
+    return {
+        async listSkuEnvelopes(query) {
+            return listEnvelopes(executor, query, LIST_ENVELOPES_SQL);
+        },
+        async listActiveSkuEnvelopes(query) {
+            const skuCodes = parseCatalogActiveSkuSelection(query.skuCodes);
+            return listEnvelopes(executor, query, LIST_ACTIVE_ENVELOPES_SQL, [], [skuCodes ?? null]);
+        },
+        async listPublicActiveSkuEnvelopes(query) {
+            return listEnvelopes(executor, query, LIST_PUBLIC_ACTIVE_ENVELOPES_SQL);
+        },
+        async listPublicActiveProductSkuEnvelopes(productId, query) {
+            return listEnvelopes(executor, query, LIST_PUBLIC_ACTIVE_PRODUCT_ENVELOPES_SQL, [productId]);
+        },
+        async getSkuEnvelope(selector) {
+            const parsed = catalogSkuEnvelopeSelectorSchema.parse(selector);
+            const rows = await readRows(executor, parsed.kind === "sku_code"
+                ? DETAIL_ENVELOPE_BY_SKU_CODE_SQL
+                : DETAIL_ENVELOPE_BY_PRIMARY_PRODUCT_SLUG_SQL, [parsed.kind === "sku_code" ? parsed.skuCode : parsed.productSlug]);
+            const row = uniqueDetailRow(rows, parsed.kind === "sku_code"
+                ? "catalog_sku_authority_sku_absent"
+                : "catalog_sku_authority_product_absent");
+            requirePostgresCatalogSkuEnvelopeRow(row, parsed.kind === "primary_product_slug"
+                ? "catalog_sku_authority_primary_sku_invalid"
+                : "catalog_sku_authority_current_document_invalid");
+            if (parsed.kind === "primary_product_slug"
+                && (row.primary_sku_id !== row.sku_id || row.product_id !== row.sku_product_id)) {
+                throw new CatalogSkuAuthorityError("catalog_sku_authority_primary_sku_invalid");
+            }
+            const identifiers = await readPostgresCatalogSkuIdentifiers(executor, [row.sku_id]);
+            return mapPostgresCatalogSkuEnvelope(row, identifiers.get(row.sku_id) ?? []);
+        },
+        async getSkuEnvelopeById(skuId) {
+            const row = uniqueDetailRow(await readRows(executor, DETAIL_ENVELOPE_BY_ID_SQL, [skuId]), "catalog_sku_authority_sku_absent");
+            requirePostgresCatalogSkuEnvelopeRow(row, "catalog_sku_authority_current_document_invalid");
+            const identifiers = await readPostgresCatalogSkuIdentifiers(executor, [row.sku_id]);
+            return mapPostgresCatalogSkuEnvelope(row, identifiers.get(row.sku_id) ?? []);
+        },
+    };
+}
+async function listEnvelopes(executor, query, sql, prefixValues = [], suffixValues = []) {
+    const rows = await readRows(executor, sql, [...prefixValues, query.cursor, checkedLimit(query.limit) + 1, ...suffixValues]);
+    const pageRows = rows.slice(0, query.limit).map((row) => {
+        requirePostgresCatalogSkuEnvelopeRow(row, "catalog_sku_authority_current_document_invalid");
+        return row;
+    });
+    const identifiers = await readPostgresCatalogSkuIdentifiers(executor, pageRows.map((row) => row.sku_id));
+    return {
+        items: pageRows.map((row) => mapPostgresCatalogSkuEnvelope(row, identifiers.get(row.sku_id) ?? [])),
+        nextCursor: rows.length > query.limit ? pageRows[pageRows.length - 1]?.sku_id ?? null : null,
+    };
+}
+function uniqueDetailRow(rows, absent) {
+    if (rows.length === 0)
+        throw new CatalogSkuAuthorityError(absent);
+    if (rows.length !== 1) {
+        throw new CatalogSkuAuthorityError("catalog_sku_authority_selector_ambiguous");
+    }
+    return rows[0];
+}
+async function readRows(executor, sql, values) {
+    const { rows } = await executor.query(sql, values);
+    return rows;
+}
+function checkedLimit(limit) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+        throw new RangeError("catalog_sku_envelope_invalid_limit");
+    }
+    return limit;
+}

package/dist/catalog/catalogSkuEnvelopeMapper.d.ts

@@ -0,0 +1,38 @@
+import { CatalogSkuAuthorityError, type CatalogSkuIdentifier, type NeutralSkuEnvelopeV1 } from "./foundationSchemas.js";
+import type { PgQueryExecutor } from "../data/index.js";
+export interface PostgresCatalogSkuEnvelopeRow {
+    product_id: string;
+    product_slug: string;
+    primary_sku_id: string | null;
+    current_document_revision_id: string | null;
+    sku_id: string | null;
+    sku_product_id: string | null;
+    sku_code: string | null;
+    net_content_unscaled: number | null;
+    sku_status: "draft" | "active" | "archived" | null;
+    sellable_one_time: boolean | null;
+    sellable_subscription: boolean | null;
+    is_addon: boolean | null;
+    asset_ref: string | null;
+    document_revision_id: string | null;
+    document_product_id: string | null;
+    document_revision_no: number | null;
+    document_schema_id: string | null;
+    document_ref: string | null;
+    document_source_ref: string | null;
+    document_digest: string | null;
+}
+export type CompletePostgresCatalogSkuEnvelopeRow = PostgresCatalogSkuEnvelopeRow & {
+    primary_sku_id: string;
+    sku_id: string;
+    sku_product_id: string;
+    sku_code: string;
+    net_content_unscaled: number;
+    sku_status: "draft" | "active" | "archived";
+    sellable_one_time: boolean;
+    sellable_subscription: boolean;
+    is_addon: boolean;
+};
+export declare function requirePostgresCatalogSkuEnvelopeRow(row: PostgresCatalogSkuEnvelopeRow, refusal: CatalogSkuAuthorityError["code"]): asserts row is CompletePostgresCatalogSkuEnvelopeRow;
+export declare function readPostgresCatalogSkuIdentifiers(executor: PgQueryExecutor, skuIds: string[]): Promise<Map<string, CatalogSkuIdentifier[]>>;
+export declare function mapPostgresCatalogSkuEnvelope(row: CompletePostgresCatalogSkuEnvelopeRow, identifiers: CatalogSkuIdentifier[]): NeutralSkuEnvelopeV1;