@venturekit/data 0.0.32 → 0.0.33

package/src/sql/{vk_data_001_tenancy_foundation.sql → 0000_vk_data_foundation.sql}

@@ -1,278 +1,305 @@
--- @venturekit/data — multi-tenant Postgres foundation.
---
--- Functions created by this migration:
---   vk_uuid_generate_v7()                      — time-ordered primary keys
---   vk_tenant_scope()                          — every tenant this request may READ
---   vk_acting_tenant()                         — the single tenant it may WRITE as
---   vk_install_tenant_guards(schema, table, role)  — forced RLS + policy + grants
---   vk_install_catalog_guards(schema, table, role) — read-only grants for shared catalogs
---
--- # Why this is the framework's job
---
--- `runWithTenantScope()` in this package publishes `app.tenant_id` and
--- `app.tenant_ids` as Postgres GUCs. That is only half a tenancy feature: the
--- GUCs do nothing until a policy reads them, and until now every consumer had
--- to write that policy — and the `ENABLE`/`FORCE`/`GRANT` around it — by hand,
--- once per table. A project with sixty tenant-scoped tables hand-writes ~300
--- lines in which a single omission is invisible: the table still works, queries
--- still return rows, and the only symptom is that one table has no isolation at
--- all. Shipping the reader and the installer next to the writer of the GUCs
--- makes that omission impossible to write by accident.
---
--- Row-level security is also the one guarantee that CANNOT move into
--- application code: Postgres enforces it against the connection, which is
--- exactly what makes it hold when a query forgets its WHERE clause.
---
--- # The role split RLS depends on
---
--- RLS is skipped for superusers, for roles with BYPASSRLS, and for a table's
--- owner unless FORCE ROW LEVEL SECURITY is set. So:
---
---   * migrations run as the OWNER (they must create and alter tables);
---   * the application connects as the tenant role — `DatabaseIntent.tenantRole`
---     in `vk.config.ts` — which owns nothing and has neither attribute, and is
---     granted only DML.
---
--- FORCE is set anyway, so even a mistaken connection as the owner is filtered.
--- Local development against a superuser bypasses all of it, which is why
--- isolation tests must connect as the tenant role explicitly or they pass while
--- proving nothing.
---
--- Names are `vk_`-prefixed and unqualified, matching `vk_tenants` and
--- `vk_notifications`: a package-owned object must not collide with a consumer's
--- own, and creating a schema in someone else's database is not this package's
--- call to make. A project that prefers its own namespace can wrap these —
--- `CREATE OR REPLACE FUNCTION sys.tenant_scope() ... SELECT vk_tenant_scope()`
--- — which keeps one implementation while leaving existing call sites alone.
---
--- Idempotent throughout (`CREATE OR REPLACE`, `IF NOT EXISTS`), so re-applying
--- after a partial failure never breaks a deploy.
-
--- ─── Extensions ─────────────────────────────────────────────────────────
--- `pgcrypto` for gen_random_bytes, which the v7 generator below needs.
-CREATE EXTENSION IF NOT EXISTS pgcrypto;
-
--- ─── Identifiers ────────────────────────────────────────────────────────
-
-/**
- * Time-ordered uuid (RFC 9562 v7).
- *
- * v4 keys scatter inserts across the whole index, so a busy table's hot page
- * set is the entire index rather than its right edge — measurable write
- * amplification once a table is taking millions of rows a day. v7 puts a
- * millisecond timestamp in the leading 48 bits, restoring insert locality while
- * still not exposing a guessable sequence.
- *
- * `clock_timestamp()` rather than `now()`: `now()` is fixed for the whole
- * transaction, so a bulk insert of 5 000 rows would emit 5 000 keys sharing one
- * timestamp prefix and lose the ordering this exists to provide.
- */
-CREATE OR REPLACE FUNCTION vk_uuid_generate_v7()
-RETURNS uuid
-LANGUAGE plpgsql
-VOLATILE
-PARALLEL SAFE
-AS $$
-DECLARE
-  ts_ms  bigint := (extract(epoch FROM clock_timestamp()) * 1000)::bigint;
-  raw    bytea;
-BEGIN
-  -- 48-bit big-endian millisecond timestamp, then 80 random bits.
-  raw := substring(int8send(ts_ms) FROM 3 FOR 6) || gen_random_bytes(10);
-  -- Version 7 in the high nibble of octet 6.
-  raw := set_byte(raw, 6, (get_byte(raw, 6) & 15) | 112);
-  -- RFC 4122 variant (10xx) in the high bits of octet 8.
-  raw := set_byte(raw, 8, (get_byte(raw, 8) & 63) | 128);
-  RETURN encode(raw, 'hex')::uuid;
-END;
-$$;
-
-COMMENT ON FUNCTION vk_uuid_generate_v7() IS
-  'Time-ordered uuid v7 (RFC 9562). Insert-local alternative to gen_random_uuid().';
-
--- ─── Tenancy ────────────────────────────────────────────────────────────
-
-/**
- * Every tenant the current request may READ, or NULL when un-scoped.
- *
- * Reads `app.tenant_ids`, published by this package's `runWithTenantScope()`.
- * A parent tenant's request carries itself plus its descendants, so "a group
- * owner sees their child tenants" is satisfied by this one policy instead of a
- * branch in every query.
- *
- * NULL is the fail-closed sentinel: `x = ANY (NULL)` is NULL, so an un-scoped
- * request sees nothing rather than everything. The `true` argument to
- * `current_setting` makes an unset GUC return NULL instead of raising, which is
- * what lets a migration or an admin connection run outside any request scope.
- *
- * STABLE, so the planner evaluates it once per statement rather than per row.
- */
-CREATE OR REPLACE FUNCTION vk_tenant_scope()
-RETURNS uuid[]
-LANGUAGE sql
-STABLE
-PARALLEL SAFE
-AS $$
-  SELECT CASE
-           WHEN coalesce(current_setting('app.tenant_ids', true), '') = '' THEN NULL::uuid[]
-           ELSE string_to_array(current_setting('app.tenant_ids', true), ',')::uuid[]
-         END;
-$$;
-
-COMMENT ON FUNCTION vk_tenant_scope() IS
-  'Tenants readable by this request (app.tenant_ids). NULL = un-scoped = no rows.';
-
-/**
- * The single tenant this request ACTS as — `app.tenant_id`, the acting tenant
- * of the scope.
- *
- * Writes are checked against this, not against the whole scope: a parent-tenant
- * administrator reading twelve child tenants should not be able to create a row
- * in one of them by accident. Widening a write to another tenant has to be a
- * deliberate re-scope, which is visible in the code that does it.
- */
-CREATE OR REPLACE FUNCTION vk_acting_tenant()
-RETURNS uuid
-LANGUAGE sql
-STABLE
-PARALLEL SAFE
-AS $$
-  SELECT nullif(current_setting('app.tenant_id', true), '')::uuid;
-$$;
-
-COMMENT ON FUNCTION vk_acting_tenant() IS
-  'The tenant this request may WRITE as (app.tenant_id). NULL = un-scoped.';
-
-/**
- * Attach the standard guards to a tenant-scoped table:
- *
- *   1. RLS, ENABLEd and FORCEd;
- *   2. the isolation policy — read across the scope, write only as the acting
- *      tenant;
- *   3. DML grants for `p_role`.
- *
- * This is DDL run at migration time, not runtime behaviour: a macro that
- * expands to the statements every tenant-scoped table needs.
- *
- * `p_role` is a parameter rather than a constant because the application role is
- * the consumer's (`DatabaseIntent.tenantRole`), and a framework that hard-coded
- * one would work for exactly one project. It is validated against `pg_roles`
- * and interpolated with `%I`, so it cannot carry SQL.
- *
- * Idempotent, so re-running a migration during development is safe. The table
- * must have a `tenant_id` column, asserted rather than assumed because a table
- * that silently skipped its policy is exactly the failure this prevents.
- */
-CREATE OR REPLACE FUNCTION vk_install_tenant_guards(
-  p_schema text,
-  p_table  text,
-  p_role   text
-)
-RETURNS void
-LANGUAGE plpgsql
-AS $$
-DECLARE
-  qualified text := format('%I.%I', p_schema, p_table);
-  fn_schema text;
-BEGIN
-  IF NOT EXISTS (
-    SELECT 1 FROM information_schema.columns
-    WHERE table_schema = p_schema AND table_name = p_table AND column_name = 'tenant_id'
-  ) THEN
-    RAISE EXCEPTION 'vk_install_tenant_guards: %.% has no tenant_id column', p_schema, p_table;
-  END IF;
-
-  -- A missing role is a misconfiguration, not something to paper over: the
-  -- grant would fail anyway, and failing here names the cause.
-  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = p_role) THEN
-    RAISE EXCEPTION 'vk_install_tenant_guards: role % does not exist', p_role;
-  END IF;
-
-  /* The policy must name the scope functions SCHEMA-QUALIFIED.
-     A policy expression is re-resolved against the *querying* session's
-     `search_path`, not the one in effect when the policy was created. Left
-     bare, `vk_tenant_scope()` would fail — or, far worse, resolve to a
-     same-named function in a schema earlier on some connection's path, which
-     is a tenant-isolation bypass that no test connecting normally would see.
-     So resolve where this migration actually put them, once, here. */
-  SELECT n.nspname INTO fn_schema
-    FROM pg_proc p
-    JOIN pg_namespace n ON n.oid = p.pronamespace
-   WHERE p.proname = 'vk_tenant_scope'
-   LIMIT 1;
-
-  IF fn_schema IS NULL THEN
-    RAISE EXCEPTION 'vk_install_tenant_guards: vk_tenant_scope() not found — is @venturekit/data''s migration applied?';
-  END IF;
-
-  EXECUTE format('ALTER TABLE %s ENABLE ROW LEVEL SECURITY', qualified);
-  EXECUTE format('ALTER TABLE %s FORCE ROW LEVEL SECURITY', qualified);
-
-  EXECUTE format('DROP POLICY IF EXISTS tenant_isolation ON %s', qualified);
-  EXECUTE format(
-    'CREATE POLICY tenant_isolation ON %s
-       USING (tenant_id = ANY (%I.vk_tenant_scope()))
-       WITH CHECK (tenant_id = %I.vk_acting_tenant())',
-    qualified, fn_schema, fn_schema);
-
-  EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON %s TO %I', qualified, p_role);
-END;
-$$;
-
-COMMENT ON FUNCTION vk_install_tenant_guards(text, text, text) IS
-  'Attach forced RLS, the isolation policy and DML grants. Call once per tenant-scoped table.';
-
-/**
- * Grants for a table that is deliberately NOT tenant-scoped — the shared
- * catalogs every tenant reads and none may edit.
- *
- * Read-only to the application on purpose: these rows are curated centrally,
- * and a tenant-facing service editing a shared catalog is how one tenant's
- * data-entry mistake becomes everyone's.
- */
-CREATE OR REPLACE FUNCTION vk_install_catalog_guards(
-  p_schema text,
-  p_table  text,
-  p_role   text
-)
-RETURNS void
-LANGUAGE plpgsql
-AS $$
-DECLARE
-  qualified text := format('%I.%I', p_schema, p_table);
-BEGIN
-  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = p_role) THEN
-    RAISE EXCEPTION 'vk_install_catalog_guards: role % does not exist', p_role;
-  END IF;
-
-  EXECUTE format('GRANT SELECT ON %s TO %I', qualified, p_role);
-END;
-$$;
-
-COMMENT ON FUNCTION vk_install_catalog_guards(text, text, text) IS
-  'Read-only grants for a shared, non-tenant-scoped catalog table.';
-
--- ─── Auditing the result ────────────────────────────────────────────────
---
--- "Which tenant-scoped tables are missing RLS?" is a query, not a view, so it
--- can live in the test that asserts it rather than in a schema object nobody
--- reads:
---
---   SELECT c.relname
---     FROM pg_class c
---     JOIN pg_namespace n ON n.oid = c.relnamespace
---    WHERE n.nspname = ANY ($1::text[])
---      AND c.relkind = 'r'
---      AND EXISTS (SELECT 1 FROM information_schema.columns
---                   WHERE table_schema = n.nspname AND table_name = c.relname
---                     AND column_name = 'tenant_id')
---      AND NOT (c.relrowsecurity AND EXISTS (
---                 SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid));
---
--- A table counts as protected when RLS is ENABLEd and at least one policy
--- exists. FORCE is deliberately not required by that check: it applies the
--- policy to the table owner too, and trusted processes that legitimately write
--- across tenants (an event projector, an ingest listener, catalog seeds) run as
--- the owner. What matters is that the tenant role — the only one serving user
--- requests, and which owns nothing — is filtered. ENABLE plus a policy
--- guarantees that.
+-- @venturekit/data — multi-tenant Postgres foundation.
+--
+-- Functions created by this migration:
+--   vk_uuid_generate_v7()                      — time-ordered primary keys
+--   vk_tenant_scope()                          — every tenant this request may READ
+--   vk_acting_tenant()                         — the single tenant it may WRITE as
+--   vk_install_tenant_guards(schema, table, role)  — forced RLS + policy + grants
+--   vk_install_catalog_guards(schema, table, role) — read-only grants for shared catalogs
+--
+-- # Why this is the framework's job
+--
+-- `runWithTenantScope()` in this package publishes `app.tenant_id` and
+-- `app.tenant_ids` as Postgres GUCs. That is only half a tenancy feature: the
+-- GUCs do nothing until a policy reads them, and until now every consumer had
+-- to write that policy — and the `ENABLE`/`FORCE`/`GRANT` around it — by hand,
+-- once per table. A project with sixty tenant-scoped tables hand-writes ~300
+-- lines in which a single omission is invisible: the table still works, queries
+-- still return rows, and the only symptom is that one table has no isolation at
+-- all. Shipping the reader and the installer next to the writer of the GUCs
+-- makes that omission impossible to write by accident.
+--
+-- Row-level security is also the one guarantee that CANNOT move into
+-- application code: Postgres enforces it against the connection, which is
+-- exactly what makes it hold when a query forgets its WHERE clause.
+--
+-- # The role split RLS depends on
+--
+-- RLS is skipped for superusers, for roles with BYPASSRLS, and for a table's
+-- owner unless FORCE ROW LEVEL SECURITY is set. So:
+--
+--   * migrations run as the OWNER (they must create and alter tables);
+--   * the application connects as the tenant role — `DatabaseIntent.tenantRole`
+--     in `vk.config.ts` — which owns nothing and has neither attribute, and is
+--     granted only DML.
+--
+-- FORCE is set anyway, so even a mistaken connection as the owner is filtered.
+-- Local development against a superuser bypasses all of it, which is why
+-- isolation tests must connect as the tenant role explicitly or they pass while
+-- proving nothing.
+--
+-- Names are `vk_`-prefixed and unqualified, matching `vk_tenants` and
+-- `vk_notifications`: a package-owned object must not collide with a consumer's
+-- own, and creating a schema in someone else's database is not this package's
+-- call to make. A project that prefers its own namespace can wrap these —
+-- `CREATE OR REPLACE FUNCTION sys.tenant_scope() ... SELECT <schema>.vk_tenant_scope()`
+-- — which keeps one implementation while leaving existing call sites alone.
+--
+-- # Why the `0000_` filename prefix
+--
+-- The migration runner merges the project's own `.sql` files with every
+-- installed package's and applies them in ALPHABETIC order, which puts the
+-- conventional `vk_<pkg>_<NNN>_*` names *after* a project's `0xx_*` files. That
+-- is right for tables a project only reads, and wrong for these: a consumer's
+-- own migration calls `vk_install_tenant_guards(...)` as it creates each table,
+-- so the functions must already exist. Worse, a `LANGUAGE sql` wrapper around
+-- one of them is validated when it is CREATEd, so a project delegating to these
+-- would fail at migrate time rather than at call time.
+--
+-- So this file takes the same one-character departure, for the same reason, as
+-- `@venturekit-pro/tenancy`'s `0000_vk_tenancy_tenants.sql`: primordial-parent
+-- status. Sorting before `0000_vk_tenancy_*` is incidental - neither depends on
+-- the other.
+--
+-- # Effect on projects already in production
+--
+-- Additive, and safe to pick up late. The runner tracks applied files by name
+-- and applies any it has not seen, so an existing database simply gains these
+-- five functions on its next migrate; the `0000_` name does not imply
+-- re-running anything, and nothing here depends on schema that a later
+-- migration created. No existing file is touched, which is the thing that would
+-- break - `vk migrate` hashes every applied file and raises
+-- `MigrationHashMismatchError` if one changes. `pgcrypto` is already created by
+-- `@venturekit-pro/tenancy`.
+--
+-- Idempotent throughout (`CREATE OR REPLACE`, `IF NOT EXISTS`), so re-applying
+-- after a partial failure never breaks a deploy.
+
+-- ─── Extensions ─────────────────────────────────────────────────────────
+-- `pgcrypto` for gen_random_bytes, which the v7 generator below needs.
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ─── Identifiers ────────────────────────────────────────────────────────
+
+/**
+ * Time-ordered uuid (RFC 9562 v7).
+ *
+ * v4 keys scatter inserts across the whole index, so a busy table's hot page
+ * set is the entire index rather than its right edge — measurable write
+ * amplification once a table is taking millions of rows a day. v7 puts a
+ * millisecond timestamp in the leading 48 bits, restoring insert locality while
+ * still not exposing a guessable sequence.
+ *
+ * `clock_timestamp()` rather than `now()`: `now()` is fixed for the whole
+ * transaction, so a bulk insert of 5 000 rows would emit 5 000 keys sharing one
+ * timestamp prefix and lose the ordering this exists to provide.
+ */
+CREATE OR REPLACE FUNCTION vk_uuid_generate_v7()
+RETURNS uuid
+LANGUAGE plpgsql
+VOLATILE
+PARALLEL SAFE
+AS $$
+DECLARE
+  ts_ms  bigint := (extract(epoch FROM clock_timestamp()) * 1000)::bigint;
+  raw    bytea;
+BEGIN
+  -- 48-bit big-endian millisecond timestamp, then 80 random bits.
+  raw := substring(int8send(ts_ms) FROM 3 FOR 6) || gen_random_bytes(10);
+  -- Version 7 in the high nibble of octet 6.
+  raw := set_byte(raw, 6, (get_byte(raw, 6) & 15) | 112);
+  -- RFC 4122 variant (10xx) in the high bits of octet 8.
+  raw := set_byte(raw, 8, (get_byte(raw, 8) & 63) | 128);
+  RETURN encode(raw, 'hex')::uuid;
+END;
+$$;
+
+COMMENT ON FUNCTION vk_uuid_generate_v7() IS
+  'Time-ordered uuid v7 (RFC 9562). Insert-local alternative to gen_random_uuid().';
+
+-- ─── Tenancy ────────────────────────────────────────────────────────────
+
+/**
+ * Every tenant the current request may READ, or NULL when un-scoped.
+ *
+ * Reads `app.tenant_ids`, published by this package's `runWithTenantScope()`.
+ * A parent tenant's request carries itself plus its descendants, so "a group
+ * owner sees their child tenants" is satisfied by this one policy instead of a
+ * branch in every query.
+ *
+ * NULL is the fail-closed sentinel: `x = ANY (NULL)` is NULL, so an un-scoped
+ * request sees nothing rather than everything. The `true` argument to
+ * `current_setting` makes an unset GUC return NULL instead of raising, which is
+ * what lets a migration or an admin connection run outside any request scope.
+ *
+ * STABLE, so the planner evaluates it once per statement rather than per row.
+ */
+CREATE OR REPLACE FUNCTION vk_tenant_scope()
+RETURNS uuid[]
+LANGUAGE sql
+STABLE
+PARALLEL SAFE
+AS $$
+  SELECT CASE
+           WHEN coalesce(current_setting('app.tenant_ids', true), '') = '' THEN NULL::uuid[]
+           ELSE string_to_array(current_setting('app.tenant_ids', true), ',')::uuid[]
+         END;
+$$;
+
+COMMENT ON FUNCTION vk_tenant_scope() IS
+  'Tenants readable by this request (app.tenant_ids). NULL = un-scoped = no rows.';
+
+/**
+ * The single tenant this request ACTS as — `app.tenant_id`, the acting tenant
+ * of the scope.
+ *
+ * Writes are checked against this, not against the whole scope: a parent-tenant
+ * administrator reading twelve child tenants should not be able to create a row
+ * in one of them by accident. Widening a write to another tenant has to be a
+ * deliberate re-scope, which is visible in the code that does it.
+ */
+CREATE OR REPLACE FUNCTION vk_acting_tenant()
+RETURNS uuid
+LANGUAGE sql
+STABLE
+PARALLEL SAFE
+AS $$
+  SELECT nullif(current_setting('app.tenant_id', true), '')::uuid;
+$$;
+
+COMMENT ON FUNCTION vk_acting_tenant() IS
+  'The tenant this request may WRITE as (app.tenant_id). NULL = un-scoped.';
+
+/**
+ * Attach the standard guards to a tenant-scoped table:
+ *
+ *   1. RLS, ENABLEd and FORCEd;
+ *   2. the isolation policy — read across the scope, write only as the acting
+ *      tenant;
+ *   3. DML grants for `p_role`.
+ *
+ * This is DDL run at migration time, not runtime behaviour: a macro that
+ * expands to the statements every tenant-scoped table needs.
+ *
+ * `p_role` is a parameter rather than a constant because the application role is
+ * the consumer's (`DatabaseIntent.tenantRole`), and a framework that hard-coded
+ * one would work for exactly one project. It is validated against `pg_roles`
+ * and interpolated with `%I`, so it cannot carry SQL.
+ *
+ * Idempotent, so re-running a migration during development is safe. The table
+ * must have a `tenant_id` column, asserted rather than assumed because a table
+ * that silently skipped its policy is exactly the failure this prevents.
+ */
+CREATE OR REPLACE FUNCTION vk_install_tenant_guards(
+  p_schema text,
+  p_table  text,
+  p_role   text
+)
+RETURNS void
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  qualified text := format('%I.%I', p_schema, p_table);
+  fn_schema text;
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = p_schema AND table_name = p_table AND column_name = 'tenant_id'
+  ) THEN
+    RAISE EXCEPTION 'vk_install_tenant_guards: %.% has no tenant_id column', p_schema, p_table;
+  END IF;
+
+  -- A missing role is a misconfiguration, not something to paper over: the
+  -- grant would fail anyway, and failing here names the cause.
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = p_role) THEN
+    RAISE EXCEPTION 'vk_install_tenant_guards: role % does not exist', p_role;
+  END IF;
+
+  /* The policy must name the scope functions SCHEMA-QUALIFIED.
+     A policy expression is re-resolved against the *querying* session's
+     `search_path`, not the one in effect when the policy was created. Left
+     bare, `vk_tenant_scope()` would fail — or, far worse, resolve to a
+     same-named function in a schema earlier on some connection's path, which
+     is a tenant-isolation bypass that no test connecting normally would see.
+     So resolve where this migration actually put them, once, here. */
+  SELECT n.nspname INTO fn_schema
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE p.proname = 'vk_tenant_scope'
+   LIMIT 1;
+
+  IF fn_schema IS NULL THEN
+    RAISE EXCEPTION 'vk_install_tenant_guards: vk_tenant_scope() not found — is @venturekit/data''s migration applied?';
+  END IF;
+
+  EXECUTE format('ALTER TABLE %s ENABLE ROW LEVEL SECURITY', qualified);
+  EXECUTE format('ALTER TABLE %s FORCE ROW LEVEL SECURITY', qualified);
+
+  EXECUTE format('DROP POLICY IF EXISTS tenant_isolation ON %s', qualified);
+  EXECUTE format(
+    'CREATE POLICY tenant_isolation ON %s
+       USING (tenant_id = ANY (%I.vk_tenant_scope()))
+       WITH CHECK (tenant_id = %I.vk_acting_tenant())',
+    qualified, fn_schema, fn_schema);
+
+  EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON %s TO %I', qualified, p_role);
+END;
+$$;
+
+COMMENT ON FUNCTION vk_install_tenant_guards(text, text, text) IS
+  'Attach forced RLS, the isolation policy and DML grants. Call once per tenant-scoped table.';
+
+/**
+ * Grants for a table that is deliberately NOT tenant-scoped — the shared
+ * catalogs every tenant reads and none may edit.
+ *
+ * Read-only to the application on purpose: these rows are curated centrally,
+ * and a tenant-facing service editing a shared catalog is how one tenant's
+ * data-entry mistake becomes everyone's.
+ */
+CREATE OR REPLACE FUNCTION vk_install_catalog_guards(
+  p_schema text,
+  p_table  text,
+  p_role   text
+)
+RETURNS void
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  qualified text := format('%I.%I', p_schema, p_table);
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = p_role) THEN
+    RAISE EXCEPTION 'vk_install_catalog_guards: role % does not exist', p_role;
+  END IF;
+
+  EXECUTE format('GRANT SELECT ON %s TO %I', qualified, p_role);
+END;
+$$;
+
+COMMENT ON FUNCTION vk_install_catalog_guards(text, text, text) IS
+  'Read-only grants for a shared, non-tenant-scoped catalog table.';
+
+-- ─── Auditing the result ────────────────────────────────────────────────
+--
+-- "Which tenant-scoped tables are missing RLS?" is a query, not a view, so it
+-- can live in the test that asserts it rather than in a schema object nobody
+-- reads:
+--
+--   SELECT c.relname
+--     FROM pg_class c
+--     JOIN pg_namespace n ON n.oid = c.relnamespace
+--    WHERE n.nspname = ANY ($1::text[])
+--      AND c.relkind = 'r'
+--      AND EXISTS (SELECT 1 FROM information_schema.columns
+--                   WHERE table_schema = n.nspname AND table_name = c.relname
+--                     AND column_name = 'tenant_id')
+--      AND NOT (c.relrowsecurity AND EXISTS (
+--                 SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid));
+--
+-- A table counts as protected when RLS is ENABLEd and at least one policy
+-- exists. FORCE is deliberately not required by that check: it applies the
+-- policy to the table owner too, and trusted processes that legitimately write
+-- across tenants (an event projector, an ingest listener, catalog seeds) run as
+-- the owner. What matters is that the tenant role — the only one serving user
+-- requests, and which owns nothing — is filtered. ENABLE plus a policy
+-- guarantees that.