@openlup/platform 0.17.0 → 0.19.0

package/sql/20260827220000_catalog_document_revision_foundation.sql

@@ -0,0 +1,226 @@
+-- Catalog Wave 2a adds an inert, portable document-revision and price-policy foundation.
+-- It deliberately carries no rows or runtime bindings: existing catalog and pricing authorities stay active.
+-- Application-owned document payloads and SHA-256 digests are opaque here; this stock PostgreSQL forward
+-- validates only the digest shape and relational invariants, never JSON content or jsonb text representation.
+
+CREATE TABLE public.catalog_product_document_revisions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id uuid NOT NULL REFERENCES public.catalog_products (id) ON DELETE RESTRICT,
+  revision_no integer NOT NULL CHECK (revision_no > 0),
+  schema_id text NOT NULL CHECK (btrim(schema_id) <> ''),
+  document_ref text NOT NULL CHECK (btrim(document_ref) <> ''),
+  document_payload jsonb NOT NULL,
+  source_ref text NOT NULL CHECK (btrim(source_ref) <> ''),
+  provenance jsonb NOT NULL,
+  digest text NOT NULL CHECK (digest ~ '^[0-9a-f]{64}$'),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT catalog_product_document_revisions_product_revision_key UNIQUE (product_id, revision_no),
+  CONSTRAINT catalog_product_document_revisions_product_digest_key UNIQUE (product_id, digest),
+  CONSTRAINT catalog_product_document_revisions_product_id_id_key UNIQUE (product_id, id)
+);
+
+ALTER TABLE public.catalog_skus
+  ADD COLUMN asset_ref text CHECK (asset_ref IS NULL OR btrim(asset_ref) <> '');
+
+-- catalog_skus.id is already a primary key, so every existing (product_id, id)
+-- pair is unique. The production manifest runner is transactional, which makes
+-- CONCURRENTLY unavailable; keep this exception scoped to this reference key.
+-- squawk-ignore require-concurrent-index-creation
+CREATE UNIQUE INDEX catalog_skus_product_id_id_key
+  ON public.catalog_skus (product_id, id);
+
+ALTER TABLE public.catalog_products
+  ADD COLUMN primary_sku_id uuid,
+  ADD COLUMN current_document_revision_id uuid,
+  ADD CONSTRAINT catalog_products_primary_sku_same_product_fkey
+    FOREIGN KEY (id, primary_sku_id)
+    REFERENCES public.catalog_skus (product_id, id)
+    ON DELETE RESTRICT NOT VALID,
+  ADD CONSTRAINT catalog_products_current_document_revision_same_product_fkey
+    FOREIGN KEY (id, current_document_revision_id)
+    REFERENCES public.catalog_product_document_revisions (product_id, id)
+    ON DELETE RESTRICT NOT VALID;
+
+CREATE TABLE public.catalog_sku_identifiers (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  catalog_sku_id uuid NOT NULL REFERENCES public.catalog_skus (id) ON DELETE RESTRICT,
+  issuer text NOT NULL CHECK (btrim(issuer) <> ''),
+  identifier_kind text NOT NULL CHECK (identifier_kind IN ('gtin', 'other')),
+  normalized_value text NOT NULL CHECK (btrim(normalized_value) <> ''),
+  pack_kind text NOT NULL CHECK (pack_kind IN ('unit', 'collective')),
+  quantity integer NOT NULL CHECK (quantity > 0),
+  is_primary boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT catalog_sku_identifiers_issuer_value_key UNIQUE (issuer, normalized_value),
+  CONSTRAINT catalog_sku_identifiers_pack_quantity_check
+    CHECK (
+      (pack_kind = 'unit' AND quantity = 1)
+      OR (pack_kind = 'collective' AND quantity > 1)
+    ),
+  CONSTRAINT catalog_sku_identifiers_primary_gtin_unit_check
+    CHECK (
+      NOT is_primary
+      OR (identifier_kind = 'gtin' AND pack_kind = 'unit' AND quantity = 1)
+    )
+);
+
+CREATE UNIQUE INDEX catalog_sku_identifiers_one_primary_gtin_per_sku_key
+  ON public.catalog_sku_identifiers (catalog_sku_id)
+  WHERE is_primary AND identifier_kind = 'gtin';
+
+CREATE INDEX catalog_sku_identifiers_sku_kind_primary_idx
+  ON public.catalog_sku_identifiers (catalog_sku_id, identifier_kind, is_primary);
+
+-- price_lists.id is already a primary key, so every existing (id, region_code,
+-- currency) tuple is unique. This is the transaction-safe repository pattern for
+-- a reference index on an existing table.
+-- squawk-ignore require-concurrent-index-creation
+CREATE UNIQUE INDEX price_lists_id_region_currency_key
+  ON public.price_lists (id, region_code, currency);
+
+CREATE TABLE public.subscription_price_policy_revisions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  price_list_id uuid NOT NULL,
+  region_code text NOT NULL,
+  currency text NOT NULL CHECK (currency ~ '^[A-Z]{3}$'),
+  channel text NOT NULL,
+  revision_no integer NOT NULL CHECK (revision_no > 0),
+  discount_bps integer NOT NULL CHECK (discount_bps BETWEEN 0 AND 10000),
+  rounding_quantum_minor integer NOT NULL CHECK (rounding_quantum_minor > 0),
+  rounding_rule text NOT NULL CHECK (rounding_rule = 'FLOOR_TO_QUANTUM'),
+  effective_from timestamptz NOT NULL,
+  effective_to timestamptz,
+  digest text NOT NULL CHECK (digest ~ '^[0-9a-f]{64}$'),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT subscription_price_policy_revisions_effective_interval_check
+    CHECK (effective_to IS NULL OR effective_to > effective_from),
+  CONSTRAINT subscription_price_policy_revisions_region_code_check
+    CHECK (region_code ~ '^[A-Z]{2,3}$'),
+  CONSTRAINT subscription_price_policy_revisions_channel_check
+    CHECK (channel ~ '^[A-Za-z0-9._:-]+$'),
+  CONSTRAINT subscription_price_policy_revisions_price_list_context_fkey
+    FOREIGN KEY (price_list_id, region_code, currency)
+    REFERENCES public.price_lists (id, region_code, currency)
+    ON DELETE RESTRICT,
+  CONSTRAINT subscription_price_policy_revisions_context_revision_key
+    UNIQUE (price_list_id, region_code, currency, channel, revision_no),
+  CONSTRAINT subscription_price_policy_revisions_context_digest_key
+    UNIQUE (price_list_id, region_code, currency, channel, digest)
+);
+
+CREATE INDEX catalog_product_document_revisions_product_id_revision_no_idx
+  ON public.catalog_product_document_revisions (product_id, revision_no);
+
+CREATE INDEX subscription_price_policy_revisions_context_effective_from_idx
+  ON public.subscription_price_policy_revisions (
+    price_list_id,
+    region_code,
+    currency,
+    channel,
+    effective_from
+  );
+
+CREATE FUNCTION public.catalog_product_document_revisions_reject_mutation()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+BEGIN
+  RAISE EXCEPTION 'catalog_product_document_revision_immutable'
+    USING ERRCODE = '55000';
+END;
+$$;
+
+CREATE FUNCTION public.subscription_price_policy_revisions_guard_mutation()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'subscription_price_policy_revision_immutable'
+      USING ERRCODE = '55000';
+  END IF;
+
+  IF OLD.effective_to IS NOT NULL
+    OR NEW.effective_to IS NULL
+    OR NEW.effective_to <= OLD.effective_from
+    OR NEW.id IS DISTINCT FROM OLD.id
+    OR NEW.price_list_id IS DISTINCT FROM OLD.price_list_id
+    OR NEW.region_code IS DISTINCT FROM OLD.region_code
+    OR NEW.currency IS DISTINCT FROM OLD.currency
+    OR NEW.channel IS DISTINCT FROM OLD.channel
+    OR NEW.revision_no IS DISTINCT FROM OLD.revision_no
+    OR NEW.discount_bps IS DISTINCT FROM OLD.discount_bps
+    OR NEW.rounding_quantum_minor IS DISTINCT FROM OLD.rounding_quantum_minor
+    OR NEW.rounding_rule IS DISTINCT FROM OLD.rounding_rule
+    OR NEW.effective_from IS DISTINCT FROM OLD.effective_from
+    OR NEW.digest IS DISTINCT FROM OLD.digest
+    OR NEW.created_at IS DISTINCT FROM OLD.created_at
+  THEN
+    RAISE EXCEPTION 'subscription_price_policy_revision_close_only'
+      USING ERRCODE = '55000';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE FUNCTION public.subscription_price_policy_revisions_prevent_overlap()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+  v_context_key text;
+BEGIN
+  IF current_setting('transaction_isolation') <> 'read committed' THEN
+    RAISE EXCEPTION 'subscription_price_policy_revision_overlap_requires_read_committed'
+      USING ERRCODE = '0A000';
+  END IF;
+
+  v_context_key := concat_ws(
+    '|',
+    NEW.price_list_id::text,
+    NEW.region_code,
+    NEW.currency,
+    NEW.channel
+  );
+
+  PERFORM pg_catalog.pg_advisory_xact_lock(
+    pg_catalog.hashtextextended(v_context_key, 0)
+  );
+
+  IF EXISTS (
+    SELECT 1
+      FROM public.subscription_price_policy_revisions AS existing
+     WHERE existing.id <> NEW.id
+       AND existing.price_list_id = NEW.price_list_id
+       AND existing.region_code = NEW.region_code
+       AND existing.currency = NEW.currency
+       AND existing.channel = NEW.channel
+       AND tstzrange(existing.effective_from, existing.effective_to, '[)')
+           && tstzrange(NEW.effective_from, NEW.effective_to, '[)')
+  ) THEN
+    RAISE EXCEPTION 'subscription_price_policy_revision_overlaps'
+      USING ERRCODE = '23P01';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER catalog_product_document_revisions_immutable
+  BEFORE UPDATE OR DELETE ON public.catalog_product_document_revisions
+  FOR EACH ROW
+  EXECUTE FUNCTION public.catalog_product_document_revisions_reject_mutation();
+
+CREATE TRIGGER subscription_price_policy_revisions_00_guard_mutation
+  BEFORE UPDATE OR DELETE ON public.subscription_price_policy_revisions
+  FOR EACH ROW
+  EXECUTE FUNCTION public.subscription_price_policy_revisions_guard_mutation();
+
+CREATE TRIGGER subscription_price_policy_revisions_10_prevent_overlap
+  BEFORE INSERT OR UPDATE ON public.subscription_price_policy_revisions
+  FOR EACH ROW
+  EXECUTE FUNCTION public.subscription_price_policy_revisions_prevent_overlap();

package/sql/20260827220001_catalog_document_revision_foundation_validate.sql

@@ -0,0 +1,10 @@
+-- Catalog Wave 2a validates the same-product pointer foreign keys after their
+-- NOT VALID installation in the immediately preceding transactional forward.
+-- Both pointer columns were introduced nullable and without backfill, so this
+-- scan confirms the current catalog before the constraints are marked valid.
+
+ALTER TABLE public.catalog_products
+  VALIDATE CONSTRAINT catalog_products_primary_sku_same_product_fkey;
+
+ALTER TABLE public.catalog_products
+  VALIDATE CONSTRAINT catalog_products_current_document_revision_same_product_fkey;

package/sql/20260908100000_catalog_draft_foundation.sql

@@ -0,0 +1,217 @@
+-- Draft foundation installs empty, isolated authoring tables and bounded command/read routines.
+-- Immutable revisions and receipts retain original replay results; identity reservations survive abandonment.
+-- No current catalog, document, pricing, stock, publication or subscription row is changed.
+-- migration:allow-trigger: reject edits and deletion of immutable draft revision and command history.
+-- migration:allow-rls: new tables default-deny all browser access; callers use bounded routines.
+-- migration:allow-grant: revoke inherited table/routine privileges before granting the intended routine access.
+-- migration:allow-dynamic-ddl: withdraw inherited nonowner ACL using catalog identities and quoted role names.
+-- migration:allow-dml: transactional routines write only the four new draft-owned relations.
+-- Owner-only INVOKER routines require externally verified operator context; no human-login or publication parity is claimed.
+CREATE TABLE public.catalog_draft_heads (
+  draft_id uuid PRIMARY KEY, product_id uuid NOT NULL UNIQUE,
+  revision integer NOT NULL CHECK (revision > 0), status text NOT NULL CHECK (status IN ('open', 'abandoned'))
+);
+CREATE TABLE public.catalog_draft_revisions (
+  draft_id uuid NOT NULL REFERENCES public.catalog_draft_heads(draft_id), revision integer NOT NULL CHECK (revision > 0),
+  product_id uuid NOT NULL, status text NOT NULL CHECK (status IN ('open', 'abandoned')),
+  payload jsonb NOT NULL, command_key text NOT NULL, fingerprint text NOT NULL CHECK (fingerprint ~ '^[0-9a-f]{64}$'),
+  actor_id text NOT NULL CHECK (btrim(actor_id) <> ''), created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  PRIMARY KEY (draft_id, revision)
+);
+CREATE TABLE public.catalog_draft_command_receipts (
+  draft_id uuid NOT NULL, command_key text NOT NULL, fingerprint text NOT NULL CHECK (fingerprint ~ '^[0-9a-f]{64}$'),
+  revision integer NOT NULL, PRIMARY KEY (draft_id, command_key),
+  FOREIGN KEY (draft_id, revision) REFERENCES public.catalog_draft_revisions(draft_id, revision)
+);
+CREATE TABLE public.catalog_draft_sku_reservations (
+  sku_id uuid PRIMARY KEY, draft_id uuid NOT NULL REFERENCES public.catalog_draft_heads(draft_id),
+  product_id uuid NOT NULL, code text UNIQUE CHECK (code IS NULL OR (btrim(code) = code AND length(code) BETWEEN 1 AND 160))
+);
+CREATE FUNCTION public.catalog_draft_reject_mutation() RETURNS trigger
+LANGUAGE plpgsql SET search_path = pg_catalog AS $$
+BEGIN RAISE EXCEPTION 'catalog_draft_history_immutable' USING ERRCODE = '55000'; END;
+$$;
+CREATE TRIGGER catalog_draft_revisions_immutable BEFORE UPDATE OR DELETE ON public.catalog_draft_revisions
+  FOR EACH ROW EXECUTE FUNCTION public.catalog_draft_reject_mutation();
+CREATE TRIGGER catalog_draft_receipts_immutable BEFORE UPDATE OR DELETE ON public.catalog_draft_command_receipts
+  FOR EACH ROW EXECUTE FUNCTION public.catalog_draft_reject_mutation();
+ALTER TABLE public.catalog_draft_heads ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.catalog_draft_revisions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.catalog_draft_command_receipts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.catalog_draft_sku_reservations ENABLE ROW LEVEL SECURITY;
+
+
+CREATE FUNCTION public.catalog_draft_record(p_draft_id uuid, p_revision integer) RETURNS jsonb
+LANGUAGE sql STABLE SET search_path = pg_catalog AS $$
+  SELECT jsonb_build_object('draftId', draft_id, 'productId', product_id, 'revision', revision,
+    'status', status, 'payload', payload, 'commandKey', command_key, 'fingerprint', fingerprint,
+    'actorId', actor_id, 'createdAt', created_at)
+  FROM public.catalog_draft_revisions WHERE draft_id = p_draft_id AND revision = p_revision
+$$;
+CREATE FUNCTION public.catalog_draft_apply(p_canonical_command text, p_fingerprint text, p_actor_id text) RETURNS jsonb
+LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, public AS $$
+DECLARE
+  c jsonb; p jsonb; s jsonb; h public.catalog_draft_heads%ROWTYPE;
+  receipt public.catalog_draft_command_receipts%ROWTYPE; reserved public.catalog_draft_sku_reservations%ROWTYPE;
+  d uuid; product uuid; sku uuid; key text; action text; expected integer; next_revision integer;
+  actor text; state text; code_value text;
+BEGIN
+  actor := p_actor_id; IF actor IS NULL OR actor <> btrim(actor) OR length(actor) NOT BETWEEN 1 AND 240 THEN RAISE EXCEPTION 'catalog_draft_actor_required' USING ERRCODE='42501'; END IF;
+  IF p_canonical_command IS NULL OR octet_length(p_canonical_command) NOT BETWEEN 2 AND 1048576
+    OR p_fingerprint IS NULL OR p_fingerprint !~ '^[0-9a-f]{64}$'
+    OR encode(sha256(convert_to(p_canonical_command, 'UTF8')), 'hex') <> p_fingerprint THEN
+    RETURN jsonb_build_object('outcome','validation_issue','reason','command_fingerprint_invalid');
+  END IF;
+  c := p_canonical_command::jsonb;
+  IF jsonb_typeof(c) IS DISTINCT FROM 'object' OR c->'schemaVersion' IS DISTINCT FROM '1'::jsonb
+    OR c->>'action' IS NULL OR c->>'action' NOT IN ('create','revise','abandon')
+    OR jsonb_typeof(c->'draftId') IS DISTINCT FROM 'string'
+    OR jsonb_typeof(c->'commandKey') IS DISTINCT FROM 'string' OR length(c->>'commandKey') NOT BETWEEN 1 AND 240
+    OR btrim(c->>'commandKey') <> c->>'commandKey'
+    OR jsonb_typeof(c->'expectedRevision') IS DISTINCT FROM 'number'
+    OR c->>'expectedRevision' !~ '^(0|[1-9][0-9]*)$'
+    OR EXISTS (SELECT FROM jsonb_object_keys(c) k WHERE k NOT IN ('schemaVersion','action','draftId','commandKey','expectedRevision','payload')) THEN
+    RETURN jsonb_build_object('outcome','validation_issue','reason','command_invalid');
+  END IF;
+  d := (c->>'draftId')::uuid; key := c->>'commandKey'; action := c->>'action'; expected := (c->>'expectedRevision')::integer;
+  IF expected > 2147483646 THEN RETURN jsonb_build_object('outcome','validation_issue','reason','revision_limit'); END IF;
+  IF d::text <> c->>'draftId' THEN RETURN jsonb_build_object('outcome','validation_issue','reason','command_invalid'); END IF;
+  PERFORM pg_advisory_xact_lock(hashtextextended('catalog-draft:' || d::text, 0));
+  SELECT * INTO receipt FROM public.catalog_draft_command_receipts WHERE draft_id = d AND command_key = key;
+  IF FOUND THEN
+    IF receipt.fingerprint <> p_fingerprint THEN
+      RETURN jsonb_build_object('outcome','conflict','reason','command_key_reused');
+    END IF;
+    IF public.catalog_draft_record(d,receipt.revision)->>'actorId' <> actor THEN RETURN jsonb_build_object('outcome','unauthorized','reason','operator_mismatch'); END IF;
+    RETURN jsonb_build_object('outcome','replayed','record',public.catalog_draft_record(d, receipt.revision));
+  END IF;
+  SELECT * INTO h FROM public.catalog_draft_heads WHERE draft_id = d FOR UPDATE;
+  IF (action = 'create' AND (FOUND OR expected <> 0)) OR (action <> 'create' AND (NOT FOUND OR expected <> h.revision)) THEN
+    RETURN jsonb_build_object('outcome','conflict','reason','revision_conflict','currentRevision',coalesce(h.revision,0));
+  END IF;
+  IF h.status = 'abandoned' THEN RETURN jsonb_build_object('outcome','conflict','reason','draft_abandoned','currentRevision',h.revision); END IF;
+  next_revision := coalesce(h.revision,0) + 1;
+  state := CASE WHEN action = 'abandon' THEN 'abandoned' ELSE 'open' END;
+  IF action = 'abandon' THEN
+    IF c ? 'payload' THEN RETURN jsonb_build_object('outcome','validation_issue','reason','abandon_payload_invalid'); END IF;
+    SELECT payload INTO p FROM public.catalog_draft_revisions WHERE draft_id = d AND revision = h.revision;
+    product := h.product_id;
+  ELSE
+    p := c->'payload';
+    IF jsonb_typeof(p) IS DISTINCT FROM 'object' OR p->'schemaVersion' IS DISTINCT FROM '1'::jsonb
+      OR jsonb_typeof(p->'product') IS DISTINCT FROM 'object' OR jsonb_typeof(p->'skus') IS DISTINCT FROM 'array'
+      OR jsonb_typeof(p->'product'->'id') IS DISTINCT FROM 'string'
+      OR jsonb_typeof(p->'product'->'type') IS DISTINCT FROM 'object'
+      OR jsonb_typeof(p->'product'->'type'->'key') IS DISTINCT FROM 'string'
+      OR p->'product'->'type'->>'key' !~ '^[a-z][a-z0-9.-]*:[a-z][a-z0-9._-]*$'
+      OR jsonb_typeof(p->'product'->'type'->'version') IS DISTINCT FROM 'number'
+      OR p->'product'->'type'->>'version' !~ '^[1-9][0-9]*$'
+      OR jsonb_typeof(p->'product'->'dimensions') IS DISTINCT FROM 'array'
+      OR jsonb_array_length(p->'product'->'dimensions') > 16 OR jsonb_array_length(p->'skus') > 10000 THEN
+      RETURN jsonb_build_object('outcome','validation_issue','reason','payload_invalid');
+    END IF;
+    product := (p->'product'->>'id')::uuid;
+    IF product::text <> p->'product'->>'id' OR (h.product_id IS NOT NULL AND h.product_id <> product)
+      OR (p->'product' ? 'documentRevision' AND p->'product'->'documentRevision'->>'productId' IS DISTINCT FROM product::text)
+      OR (p->'product' ? 'primarySkuId' AND NOT EXISTS (SELECT FROM jsonb_array_elements(p->'skus') x WHERE x->>'id' = p->'product'->>'primarySkuId')) THEN
+      RETURN jsonb_build_object('outcome','validation_issue','reason','product_reference_invalid');
+    END IF;
+    IF EXISTS (SELECT FROM jsonb_array_elements(p->'skus') x GROUP BY x->>'id' HAVING count(*) > 1)
+      OR EXISTS (SELECT FROM jsonb_array_elements(p->'skus') x WHERE x ? 'code' GROUP BY x->>'code' HAVING count(*) > 1) THEN
+      RETURN jsonb_build_object('outcome','validation_issue','reason','sku_identity_duplicate');
+    END IF;
+    FOR s IN SELECT value FROM jsonb_array_elements(p->'skus') LOOP
+      IF jsonb_typeof(s) IS DISTINCT FROM 'object' OR jsonb_typeof(s->'id') IS DISTINCT FROM 'string'
+        OR s->>'productId' IS DISTINCT FROM product::text OR s ? 'sharedContent'
+        OR jsonb_typeof(s->'options') IS DISTINCT FROM 'object'
+        OR (s ? 'code' AND (jsonb_typeof(s->'code') IS DISTINCT FROM 'string' OR length(s->>'code') NOT BETWEEN 1 AND 160 OR btrim(s->>'code') <> s->>'code' OR s->>'code' !~ '^[A-Za-z0-9._:-]+$')) THEN
+        RETURN jsonb_build_object('outcome','validation_issue','reason','sku_reference_invalid');
+      END IF;
+      sku := (s->>'id')::uuid;
+      IF sku::text <> s->>'id' THEN RETURN jsonb_build_object('outcome','validation_issue','reason','sku_reference_invalid'); END IF;
+      SELECT * INTO reserved FROM public.catalog_draft_sku_reservations WHERE sku_id = sku;
+      IF FOUND AND (reserved.draft_id <> d OR reserved.product_id <> product OR (reserved.code IS NOT NULL AND reserved.code IS DISTINCT FROM s->>'code')) THEN
+        RETURN jsonb_build_object('outcome','conflict','reason','sku_identity_reserved');
+      END IF;
+    END LOOP;
+  END IF;
+  -- The exception block rolls back every write if any cross-draft reservation loses a race.
+  BEGIN
+    IF action = 'create' THEN INSERT INTO public.catalog_draft_heads VALUES(d,product,next_revision,state);
+    ELSE UPDATE public.catalog_draft_heads SET revision=next_revision,status=state WHERE draft_id=d; END IF;
+    IF action <> 'abandon' THEN
+      FOR s IN SELECT value FROM jsonb_array_elements(p->'skus') LOOP
+        INSERT INTO public.catalog_draft_sku_reservations(sku_id,draft_id,product_id,code)
+          VALUES((s->>'id')::uuid,d,product,s->>'code') ON CONFLICT(sku_id) DO NOTHING;
+        SELECT * INTO reserved FROM public.catalog_draft_sku_reservations WHERE sku_id=(s->>'id')::uuid FOR UPDATE;
+        IF reserved.draft_id <> d OR reserved.product_id <> product OR (reserved.code IS NOT NULL AND reserved.code IS DISTINCT FROM s->>'code') THEN
+          RAISE unique_violation USING MESSAGE='sku_identity_reserved';
+        END IF;
+        IF reserved.code IS NULL AND s ? 'code' THEN
+          UPDATE public.catalog_draft_sku_reservations SET code=s->>'code' WHERE sku_id=(s->>'id')::uuid;
+        END IF;
+      END LOOP;
+    END IF;
+    INSERT INTO public.catalog_draft_revisions(draft_id,revision,product_id,status,payload,command_key,fingerprint,actor_id)
+      VALUES(d,next_revision,product,state,p,key,p_fingerprint,actor);
+    INSERT INTO public.catalog_draft_command_receipts VALUES(d,key,p_fingerprint,next_revision);
+  EXCEPTION WHEN unique_violation THEN
+    RETURN jsonb_build_object('outcome','conflict','reason','identity_reserved');
+  END;
+  RETURN jsonb_build_object('outcome','committed','record',public.catalog_draft_record(d,next_revision));
+EXCEPTION WHEN invalid_text_representation OR numeric_value_out_of_range THEN
+  RETURN jsonb_build_object('outcome','validation_issue','reason','command_invalid');
+END;
+$$;
+CREATE FUNCTION public.catalog_draft_get(p_draft_id uuid, p_revision integer DEFAULT NULL, p_command_key text DEFAULT NULL) RETURNS jsonb
+LANGUAGE plpgsql SECURITY INVOKER STABLE SET search_path = pg_catalog, public AS $$
+DECLARE r integer;
+BEGIN
+  -- Owner-only: verified operator context is supplied at the dark domain boundary.
+  IF p_revision IS NOT NULL AND p_command_key IS NOT NULL THEN RAISE EXCEPTION 'read_selector_invalid' USING ERRCODE='22023'; END IF;
+  IF p_command_key IS NOT NULL THEN
+    SELECT revision INTO r FROM public.catalog_draft_command_receipts WHERE draft_id=p_draft_id AND command_key=p_command_key;
+  ELSIF p_revision IS NOT NULL THEN r := p_revision;
+  ELSE SELECT revision INTO r FROM public.catalog_draft_heads WHERE draft_id=p_draft_id; END IF;
+  RETURN public.catalog_draft_record(p_draft_id,r);
+END;
+$$;
+CREATE FUNCTION public.catalog_draft_list(p_after_draft_id uuid DEFAULT NULL, p_limit integer DEFAULT 100) RETURNS jsonb
+LANGUAGE plpgsql SECURITY INVOKER STABLE SET search_path = pg_catalog, public AS $$
+DECLARE result jsonb;
+BEGIN
+  -- Owner-only: verified operator context is supplied at the dark domain boundary.
+  IF p_limit IS NULL OR p_limit NOT BETWEEN 1 AND 100 THEN RAISE EXCEPTION 'list_limit_invalid' USING ERRCODE='22023'; END IF;
+  WITH page AS (SELECT draft_id,revision FROM public.catalog_draft_heads
+    WHERE p_after_draft_id IS NULL OR draft_id > p_after_draft_id ORDER BY draft_id LIMIT p_limit+1),
+  visible AS (SELECT * FROM page ORDER BY draft_id LIMIT p_limit)
+  SELECT jsonb_build_object('items',coalesce(jsonb_agg(jsonb_build_object(
+    'draftId',r.draft_id,'productId',r.product_id,'revision',r.revision,'status',r.status,
+    'commandKey',r.command_key,'fingerprint',r.fingerprint,'actorId',r.actor_id,'createdAt',r.created_at) ORDER BY r.draft_id),'[]'::jsonb),
+    'nextCursor',CASE WHEN (SELECT count(*) FROM page)>p_limit THEN (SELECT draft_id::text FROM visible ORDER BY draft_id DESC LIMIT 1) END)
+    INTO result FROM visible v JOIN public.catalog_draft_revisions r ON r.draft_id=v.draft_id AND r.revision=v.revision;
+  RETURN result;
+END;
+$$;
+REVOKE ALL ON TABLE public.catalog_draft_heads, public.catalog_draft_revisions,
+  public.catalog_draft_command_receipts, public.catalog_draft_sku_reservations FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.catalog_draft_reject_mutation() FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.catalog_draft_record(uuid,integer) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.catalog_draft_apply(text,text,text) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.catalog_draft_get(uuid,integer,text) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.catalog_draft_list(uuid,integer) FROM PUBLIC, anon, authenticated;
+
+DO $$ DECLARE observer record; BEGIN
+  FOR observer IN SELECT DISTINCT roles.rolname FROM pg_class c
+    CROSS JOIN LATERAL aclexplode(c.relacl) a JOIN pg_roles roles ON roles.oid=a.grantee
+    WHERE c.oid IN ('public.catalog_draft_heads'::regclass,'public.catalog_draft_revisions'::regclass,
+      'public.catalog_draft_command_receipts'::regclass,'public.catalog_draft_sku_reservations'::regclass)
+      AND a.grantee<>c.relowner LOOP
+    EXECUTE format('REVOKE ALL ON TABLE public.catalog_draft_heads, public.catalog_draft_revisions, public.catalog_draft_command_receipts, public.catalog_draft_sku_reservations FROM %I',observer.rolname);
+  END LOOP;
+  FOR observer IN SELECT p.oid::regprocedure routine,roles.rolname FROM pg_proc p
+    CROSS JOIN LATERAL aclexplode(p.proacl) a JOIN pg_roles roles ON roles.oid=a.grantee
+    WHERE p.pronamespace='public'::regnamespace AND p.proname LIKE 'catalog_draft_%' AND a.grantee<>p.proowner LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM %I',observer.routine,observer.rolname);
+  END LOOP;
+END $$;

package/src/catalog/activeSkuSelection.ts

@@ -0,0 +1,20 @@
+import { catalogSkuEnvelopeSelectorSchema } from "./foundationSchemas.js";
+
+/** Shares exact-code parsing with detail reads; omission alone keeps discovery broad. */
+export function parseCatalogActiveSkuSelection(value: unknown): readonly string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length < 1 || value.length > 100) {
+    throw new RangeError("catalog_active_sku_selection_invalid");
+  }
+  const codes: string[] = [];
+  const seen = new Set<string>();
+  for (const skuCode of value) {
+    const parsed = catalogSkuEnvelopeSelectorSchema.safeParse({ kind: "sku_code", skuCode });
+    if (!parsed.success || parsed.data.kind !== "sku_code" || seen.has(parsed.data.skuCode)) {
+      throw new RangeError("catalog_active_sku_selection_invalid");
+    }
+    codes.push(parsed.data.skuCode);
+    seen.add(parsed.data.skuCode);
+  }
+  return codes;
+}

package/src/catalog/adminBindings.ts

@@ -0,0 +1,59 @@
+import type { ZodType } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+
+/** Structural inputs to the reference admin kit. Authorization and parsing stay with the host. */
+export type AuthorizeAdmin = () => Promise<
+  | { ok: true; userId: string; role: "admin" | "distributor"; isMachineActor: boolean }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string; identityCode?: string }
+>;
+export interface AgentDomainQuerySpec<T> {
+  readonly key: string;
+  readonly requestSchema: ZodType<T, unknown>;
+  readonly gate: "read";
+  readonly allowedActorKinds: readonly ("human" | "machine")[];
+}
+export interface AgentDomainMutationSpec<T> extends Omit<AgentDomainQuerySpec<T>, "gate"> {
+  readonly gate: "mutation" | "activation";
+  readonly lifecycleMarkers: readonly ("LIFECYCLE_ACTIVATE" | "LIFECYCLE_DEACTIVATE" | "HARD_DELETE")[];
+}
+export type BundleMutationKey = "create" | "update" | "setComposition" | "setTargetPrice" | "archive" | "restore" | "cloneDraft" | "activate" | "deactivate";
+export type BundleQueryKey = "list" | "get" | "history" | "previewPrice";
+export interface BundleResponseSchema {
+  safeParse(value: unknown): { success: boolean; data?: unknown };
+}
+type Handler = (req: HttpRequest, res: HttpResponse) => Promise<void>;
+interface CommonOptions<T> {
+  authorizeAdmin: AuthorizeAdmin;
+  flagName?: string;
+  enabled?: boolean;
+  toResponse(value: T): Record<string, unknown>;
+  disabledMessage?: string;
+  invalidRequestMessage: string;
+  failureMessage: string;
+}
+export interface BundleAdminBindings {
+  bundleSpec: {
+    readonly mutations: Readonly<Record<string, AgentDomainMutationSpec<unknown>>>;
+    readonly queries?: Readonly<Record<string, AgentDomainQuerySpec<unknown>>>;
+    readonly mutationFlag: `${string}_MUTATIONS_ENABLED`;
+    readonly activationFlag: `${string}_ACTIVATION_ENABLED`;
+    readonly readFlag?: `${string}_READ_ENABLED`;
+  };
+  COMMERCE_CONTRACT_VERSION: "commerce.v0";
+  /** Passed by identity: instanceof and shared SQLSTATE mapping retain their owner. */
+  BundleRpcError: new (sqlstate: string | undefined, message: string) => Error & { sqlstate: string | undefined; pgMessage: string };
+  createAdminMutationHandler<Request, Result>(options: CommonOptions<Result> & {
+    mutation: AgentDomainMutationSpec<Request>;
+    invoke(actorId: string, request: Request): Promise<Result>;
+  }): Handler;
+  createAdminParameterizedReadHandler<Request, Result>(options: CommonOptions<Result> & {
+    query: AgentDomainQuerySpec<Request>;
+    load(actorId: string, request: Request): Promise<Result>;
+    responseSchema: BundleResponseSchema;
+    invalidResponseMessage: string;
+  }): Handler;
+  bundleHistoryResponseSchema: BundleResponseSchema;
+  getBundleResponseSchema: BundleResponseSchema;
+  listBundlesResponseSchema: BundleResponseSchema;
+  previewBundlePriceResponseSchema: BundleResponseSchema;
+}