@everystack/cli 0.3.31 → 0.4.0

package/src/cli/derived-introspect.ts

@@ -41,6 +41,28 @@ export interface LiveObject {
   bytes?: number;
   /** Matview only: reltuples estimate. */
   rows?: number;
+  /** Trigger only: the (bare or schema-qualified) relation it rides — `DROP TRIGGER … ON` needs it. */
+  table?: string;
+  /** Live ACLs (grantee → sorted privileges), owner excluded, function defaults expanded.
+   *  Absent on triggers (they take no grants) and when the introspection predates B4. */
+  grants?: Record<string, string[]>;
+  /** View only: the security_invoker reloption — db:pull renders the required property. */
+  securityInvoker?: boolean;
+  /** Function only (B5 pull rendering): the structured signature and body. */
+  fn?: {
+    /** pg_get_function_arguments — `'query text, max integer DEFAULT 20'`. */
+    args: string;
+    /** pg_get_function_result — `'integer'`, `'SETOF posts'`, `'trigger'`. */
+    returns: string;
+    language: string;
+    secdef: boolean;
+    /** provolatile: 'i' | 's' | 'v'. */
+    volatility: string;
+    /** The pinned search_path value, when set ('pg_catalog, public'). */
+    searchPath?: string;
+    /** prosrc — the raw body. */
+    src: string;
+  };
 }
 
 /** dependent identity → referenced identity (both derived objects). */
@@ -54,6 +76,10 @@ export interface ProvenanceRow {
   identity: string;
   srcHash: string;
   defHash: string;
+  /** The object kind at record time — how a `'sql'` object (invisible to the catalog) is known. */
+  kind?: string;
+  /** How to remove what was recorded — the C1 closure: removal never orphans. */
+  dropSql?: string;
 }
 
 export interface DerivedCatalog {
@@ -66,7 +92,8 @@ export interface DerivedCatalog {
 // Introspection SQL.
 // ---------------------------------------------------------------------------
 
-/** Views and matviews with canonical definitions, size, and comment. */
+/** Views and matviews with canonical definitions, size, comment, and (views) the
+ *  security_invoker reloption — db:pull renders it as the REQUIRED securityInvoker. */
 export const DERIVED_RELATIONS_SQL = `
 SELECT
   n.nspname AS schema,
@@ -76,7 +103,11 @@ SELECT
   obj_description(c.oid, 'pg_class') AS comment,
   c.relispopulated AS populated,
   pg_total_relation_size(c.oid) AS bytes,
-  c.reltuples::bigint AS rows
+  c.reltuples::bigint AS rows,
+  EXISTS (
+    SELECT 1 FROM unnest(COALESCE(c.reloptions, '{}'::text[])) o
+    WHERE o IN ('security_invoker=true', 'security_invoker=on')
+  ) AS security_invoker
 FROM pg_class c
 JOIN pg_namespace n ON n.oid = c.relnamespace
 WHERE c.relkind IN ('v', 'm')
@@ -88,15 +119,28 @@ WHERE c.relkind IN ('v', 'm')
 ORDER BY n.nspname, c.relname;
 `.trim();
 
-/** Plain functions and procedures with canonical definitions and comment. */
+/** Plain functions and procedures: the canonical definition (reconcile's def hash) plus
+ *  the STRUCTURED fields db:pull renders into defineFunction — args/returns from the
+ *  deparse helpers, language, SECDEF, volatility, the pinned search_path, and the raw
+ *  body (prosrc). Anything the v1 signature vocabulary can't say falls back to defineSql
+ *  with the whole pg_get_functiondef. */
 export const DERIVED_FUNCTIONS_SQL = `
 SELECT
   n.nspname AS schema,
   p.proname AS name,
   pg_get_functiondef(p.oid) AS definition,
-  obj_description(p.oid, 'pg_proc') AS comment
+  obj_description(p.oid, 'pg_proc') AS comment,
+  pg_get_function_arguments(p.oid) AS args,
+  pg_get_function_result(p.oid) AS returns,
+  l.lanname AS language,
+  p.prosecdef AS secdef,
+  p.provolatile AS volatility,
+  (SELECT split_part(cfg, '=', 2) FROM unnest(COALESCE(p.proconfig, '{}'::text[])) cfg
+    WHERE cfg LIKE 'search_path=%' LIMIT 1) AS search_path,
+  p.prosrc AS src
 FROM pg_proc p
 JOIN pg_namespace n ON n.oid = p.pronamespace
+JOIN pg_language l ON l.oid = p.prolang
 WHERE p.prokind IN ('f', 'p')
   AND n.nspname NOT IN ('pg_catalog', 'information_schema')
   AND n.nspname NOT LIKE 'pg_%'
@@ -122,10 +166,15 @@ ORDER BY n.nspname, t.relname, idx.indexrelid;
 `.trim();
 
 /**
- * Dependency edges between derived objects, through each view/matview's
- * rewrite rule: view → view/matview it selects from, and view → function it
- * calls. (Function → function edges do not exist in pg_depend — function
- * bodies are opaque to it; source order is the fallback there.)
+ * Dependency edges from each view/matview's rewrite rule: view → view/matview/TABLE it
+ * selects from, and view → function it calls. (Function → function edges do not exist in
+ * pg_depend — function bodies are opaque to it; source order is the fallback there.)
+ *
+ * Table edges (relkind 'r') feed B4's declared-vs-actual dependency drift — the
+ * verification half of "dependsOn: declared, then verified". The cascade logic keys its
+ * lookups by MANAGED derived identities, so table-referenced edges never join it.
+ * System-schema referenced sides are excluded on both branches: a view reading
+ * pg_catalog is not an edge anyone declares.
  */
 export const DERIVED_DEPENDS_SQL = `
 SELECT DISTINCT
@@ -143,7 +192,12 @@ WHERE d.classid = 'pg_rewrite'::regclass
   AND d.refclassid = 'pg_class'::regclass
   AND dc.oid <> rc.oid
   AND dc.relkind IN ('v', 'm')
-  AND rc.relkind IN ('v', 'm')
+  AND rc.relkind IN ('v', 'm', 'r')
+  AND rn.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND rn.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = rc.oid AND dep.deptype = 'e'
+  )
 UNION
 SELECT DISTINCT
   dn.nspname, dc.relname, rn.nspname, rp.proname
@@ -155,12 +209,90 @@ JOIN pg_proc rp ON rp.oid = d.refobjid
 JOIN pg_namespace rn ON rn.oid = rp.pronamespace
 WHERE d.classid = 'pg_rewrite'::regclass
   AND d.refclassid = 'pg_proc'::regclass
-  AND dc.relkind IN ('v', 'm');
+  AND dc.relkind IN ('v', 'm')
+  AND rn.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND rn.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = rp.oid AND dep.deptype = 'e'
+  );
+`.trim();
+
+/**
+ * Live ACLs for the derived kinds — the grant half of B4's drift (a hand-run
+ * GRANT/REVOKE touches no content hash and was invisible without this read).
+ *
+ * Relations (`relacl`): a NULL acl means owner-only — aclexplode(NULL) yields nothing,
+ * which reads correctly as "no grants". Functions (`proacl`) are the opposite trap:
+ * NULL means the BUILT-IN DEFAULT, which includes EXECUTE to PUBLIC — so the function
+ * branch expands `acldefault('f', proowner)` and a never-revoked function honestly
+ * shows its PUBLIC EXECUTE. Owner rows are excluded (owner privileges are not grants);
+ * `LEFT JOIN pg_roles` + COALESCE('PUBLIC') keeps a dropped-role ACL from failing the
+ * read (the table path's offline-safety). `kind` disambiguates a relation and a
+ * function sharing a name.
+ */
+export const DERIVED_GRANTS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS name,
+  'r' AS kind,
+  COALESCE(r.rolname, 'PUBLIC') AS grantee,
+  array_agg(DISTINCT a.privilege_type ORDER BY a.privilege_type) AS privileges
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+CROSS JOIN LATERAL aclexplode(c.relacl) a
+LEFT JOIN pg_roles r ON r.oid = a.grantee
+WHERE c.relkind IN ('v', 'm')
+  AND a.grantee <> c.relowner
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = c.oid AND dep.deptype = 'e'
+  )
+GROUP BY n.nspname, c.relname, r.rolname
+UNION ALL
+SELECT
+  n.nspname,
+  p.proname,
+  'f',
+  COALESCE(r.rolname, 'PUBLIC'),
+  array_agg(DISTINCT a.privilege_type ORDER BY a.privilege_type)
+FROM pg_proc p
+JOIN pg_namespace n ON n.oid = p.pronamespace
+CROSS JOIN LATERAL aclexplode(COALESCE(p.proacl, acldefault('f', p.proowner))) a
+LEFT JOIN pg_roles r ON r.oid = a.grantee
+WHERE p.prokind IN ('f', 'p')
+  AND a.grantee <> p.proowner
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = p.oid AND dep.deptype = 'e'
+  )
+GROUP BY n.nspname, p.proname, r.rolname
+ORDER BY 1, 2, 4;
 `.trim();
 
-/** The reconciler's provenance claims. The table may not exist yet — callers tolerate that. */
+/** The reconciler's provenance claims. The table may not exist yet — callers tolerate
+ *  that. `to_jsonb(p)` carries the newer columns (kind, drop_sql) version-tolerantly:
+ *  a legacy database without them still SELECTs clean, the keys are simply absent. */
 export const PROVENANCE_SQL = `
-SELECT identity, src_hash, def_hash FROM everystack.derived_provenance;
+SELECT identity, src_hash, def_hash, to_jsonb(p) AS extra FROM everystack.derived_provenance p;
+`.trim();
+
+/** User triggers (never internal/constraint machinery) with their canonical definition —
+ *  the live side of the trigger reconcile. Compound identity: schema.table.name. */
+export const DERIVED_TRIGGERS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  t.tgname AS name,
+  pg_get_triggerdef(t.oid) AS definition
+FROM pg_trigger t
+JOIN pg_class c ON c.oid = t.tgrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE NOT t.tgisinternal
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY n.nspname, c.relname, t.tgname;
 `.trim();
 
 // ---------------------------------------------------------------------------
@@ -176,6 +308,8 @@ export interface RelationRow {
   populated: unknown;
   bytes: unknown;
   rows: unknown;
+  /** security_invoker reloption (views). Optional — pre-B5 fixtures omit it. */
+  security_invoker?: unknown;
 }
 
 export interface FunctionRow {
@@ -183,6 +317,14 @@ export interface FunctionRow {
   name: string;
   definition: unknown;
   comment: unknown;
+  /** Structured signature fields (B5 pull rendering). Optional — pre-B5 fixtures omit them. */
+  args?: unknown;
+  returns?: unknown;
+  language?: unknown;
+  secdef?: unknown;
+  volatility?: unknown;
+  search_path?: unknown;
+  src?: unknown;
 }
 
 export interface IndexDefRow {
@@ -202,6 +344,24 @@ export interface ProvenanceRawRow {
   identity: string;
   src_hash: unknown;
   def_hash: unknown;
+  /** `to_jsonb(p)` — the version-tolerant payload; carries kind/drop_sql when the columns exist. */
+  extra?: Record<string, unknown> | null;
+}
+
+export interface TriggerRow {
+  schema: string;
+  table: string;
+  name: string;
+  definition: unknown;
+}
+
+export interface GrantAclRow {
+  schema: string;
+  name: string;
+  /** 'r' = relation (view/matview), 'f' = function — disambiguates shared names. */
+  kind: unknown;
+  grantee: string;
+  privileges: unknown;
 }
 
 /** sha256 over an object's normalized definition + sorted indexes + comment. */
@@ -217,6 +377,19 @@ export interface DerivedRows {
   indexes: IndexDefRow[];
   depends: DependsRow[];
   provenance: ProvenanceRawRow[];
+  /** pg_trigger rows (user triggers only). Optional — older callers predate triggers. */
+  triggers?: TriggerRow[];
+  /** Live ACL rows (DERIVED_GRANTS_SQL). Optional — older callers predate B4's drift. */
+  grants?: GrantAclRow[];
+}
+
+/** Coerce a Postgres text[] (a JS array, or the `{a,b}` text form some drivers return) to string[]. */
+function pgTextArray(v: unknown): string[] {
+  if (Array.isArray(v)) return v.map(String);
+  if (typeof v === 'string') {
+    return v.replace(/^\{|\}$/g, '').split(',').map((s) => s.replace(/^"|"$/g, '').trim()).filter(Boolean);
+  }
+  return [];
 }
 
 /**
@@ -225,6 +398,21 @@ export interface DerivedRows {
  * database is byte-stable.
  */
 export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
+  // Live ACLs keyed by kind-class + identity ('r' relations, 'f' functions) so a view and
+  // a function sharing a name never swap grants.
+  const grantsByKey = new Map<string, Record<string, string[]>>();
+  for (const row of rows.grants ?? []) {
+    if (IGNORED_SCHEMAS.has(row.schema)) continue;
+    const key = `${String(row.kind)}:${row.schema}.${row.name}`;
+    const acc = grantsByKey.get(key) ?? {};
+    acc[row.grantee] = [...new Set([...(acc[row.grantee] ?? []), ...pgTextArray(row.privileges)])].sort();
+    grantsByKey.set(key, acc);
+  }
+  const grantsFor = (kindClass: 'r' | 'f', identity: string): { grants?: Record<string, string[]> } => {
+    if (rows.grants === undefined) return {}; // pre-B4 caller — absent, not empty
+    return { grants: grantsByKey.get(`${kindClass}:${identity}`) ?? {} };
+  };
+
   const indexesByIdentity = new Map<string, string[]>();
   for (const row of rows.indexes) {
     if (IGNORED_SCHEMAS.has(row.schema)) continue;
@@ -248,12 +436,16 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
       definition, indexes,
       ...(comment !== undefined ? { comment } : {}),
       defHash: computeDefHash(definition, indexes, comment),
+      ...grantsFor('r', identity),
     };
     if (kind === 'materialized view') {
       obj.populated = row.populated == null ? undefined : String(row.populated) !== 'false';
       obj.bytes = row.bytes == null ? undefined : Number(row.bytes);
       obj.rows = row.rows == null ? undefined : Math.max(0, Number(row.rows));
     }
+    if (kind === 'view' && row.security_invoker !== undefined) {
+      obj.securityInvoker = String(row.security_invoker) === 'true' || row.security_invoker === true || row.security_invoker === 't';
+    }
     objects.push(obj);
   }
 
@@ -267,19 +459,61 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
       definition, indexes: [],
       ...(comment !== undefined ? { comment } : {}),
       defHash: computeDefHash(definition, [], comment),
+      ...grantsFor('f', identity),
+      ...(row.src !== undefined ? {
+        fn: {
+          args: String(row.args ?? ''),
+          returns: String(row.returns ?? ''),
+          language: String(row.language ?? 'sql'),
+          secdef: row.secdef === true || row.secdef === 't' || row.secdef === 'true',
+          volatility: String(row.volatility ?? 'v'),
+          ...(row.search_path != null && String(row.search_path) !== '' ? { searchPath: String(row.search_path) } : {}),
+          src: String(row.src),
+        },
+      } : {}),
     });
   }
 
-  const edges: DependencyEdge[] = rows.depends
-    .filter((r) => !IGNORED_SCHEMAS.has(r.dependent_schema) && !IGNORED_SCHEMAS.has(r.referenced_schema))
-    .map((r) => ({
-      dependent: `${r.dependent_schema}.${r.dependent_name}`,
-      referenced: `${r.referenced_schema}.${r.referenced_name}`,
-    }))
-    .sort((a, b) => (a.dependent + a.referenced).localeCompare(b.dependent + b.referenced));
+  // Triggers: compound identity (schema.table.name); the table rides along for the
+  // structural drop. An edge to the OWNING relation is synthesized when that relation
+  // is itself derived (a view/matview) — so a view rebuild cascades its INSTEAD OF
+  // triggers instead of CASCADE silently eating them. Tables are state — no edge.
+  const relationIdentities = new Set(objects.map((o) => o.identity));
+  const triggerEdges: DependencyEdge[] = [];
+  for (const row of rows.triggers ?? []) {
+    if (IGNORED_SCHEMAS.has(row.schema)) continue;
+    const ownerIdentity = `${row.schema}.${row.table}`;
+    const identity = `${ownerIdentity}.${row.name}`;
+    const definition = String(row.definition ?? '');
+    objects.push({
+      kind: 'trigger', schema: row.schema, name: row.name, identity,
+      definition, indexes: [],
+      defHash: computeDefHash(definition, []),
+      table: row.schema === 'public' ? row.table : ownerIdentity,
+    });
+    if (relationIdentities.has(ownerIdentity)) {
+      triggerEdges.push({ dependent: identity, referenced: ownerIdentity });
+    }
+  }
+
+  const edges: DependencyEdge[] = [
+    ...rows.depends
+      .filter((r) => !IGNORED_SCHEMAS.has(r.dependent_schema) && !IGNORED_SCHEMAS.has(r.referenced_schema))
+      .map((r) => ({
+        dependent: `${r.dependent_schema}.${r.dependent_name}`,
+        referenced: `${r.referenced_schema}.${r.referenced_name}`,
+      })),
+    ...triggerEdges,
+  ].sort((a, b) => (a.dependent + a.referenced).localeCompare(b.dependent + b.referenced));
 
   const provenance: ProvenanceRow[] = rows.provenance
-    .map((r) => ({ identity: r.identity, srcHash: String(r.src_hash ?? ''), defHash: String(r.def_hash ?? '') }))
+    .map((r) => ({
+      identity: r.identity,
+      srcHash: String(r.src_hash ?? ''),
+      defHash: String(r.def_hash ?? ''),
+      ...(r.extra?.kind != null ? { kind: String(r.extra.kind) } : {}),
+      ...(r.extra?.drop_sql != null ? { dropSql: String(r.extra.drop_sql) } : {}),
+    }))
     .sort((a, b) => a.identity.localeCompare(b.identity));
 
   return {
@@ -295,8 +529,9 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
  * the reconciler has never touched) folds to an empty claims list.
  */
 export async function introspectDerived(run: QueryRunner): Promise<DerivedCatalog> {
-  const [relations, functions, indexes, depends] = await Promise.all([
+  const [relations, functions, indexes, depends, triggers, grants] = await Promise.all([
     run(DERIVED_RELATIONS_SQL), run(DERIVED_FUNCTIONS_SQL), run(MATVIEW_INDEXES_SQL), run(DERIVED_DEPENDS_SQL),
+    run(DERIVED_TRIGGERS_SQL), run(DERIVED_GRANTS_SQL),
   ]);
   let provenance: ProvenanceRawRow[] = [];
   try {
@@ -309,6 +544,8 @@ export async function introspectDerived(run: QueryRunner): Promise<DerivedCatalo
     functions: functions as FunctionRow[],
     indexes: indexes as IndexDefRow[],
     depends: depends as DependsRow[],
+    triggers: triggers as TriggerRow[],
+    grants: grants as GrantAclRow[],
     provenance,
   });
 }

package/src/cli/derived-lint.ts

@@ -0,0 +1,261 @@
+/**
+ * derived-lint — the B2 gates over the declared derived layer
+ * (docs/plans/read-model-everywhere.md, "Rejection rules and gates").
+ *
+ * The table gate (authz-lint's findReadAuthzGaps) has a derived mirror: a declared
+ * relation nobody can read exists superuser-only from the moment it is created. Two more
+ * gates close the function surface (SECURITY DEFINER with undeclared callers) and the
+ * matview trap (a snapshot taken with the refresher's eyes over row-scoped sources), and
+ * one closes the invoker-view gap: `securityInvoker: true` means the CALLER's rights are
+ * checked against every relation the body touches — a view can be granted and still
+ * unreadable, one property over.
+ *
+ * Reachability walks DECLARED deps only — the declared graph paying for itself
+ * (`dependsOn`: declared, then verified; reconcile checks the declaration against the
+ * live catalog). An empty `dependsOn` is an empty closure, not a pass on a technicality:
+ * the drift report names the missing declaration.
+ *
+ * Audience semantics mirror the table grant compiler (authz-compile), and the mirroring
+ * is PINNED by a differential test against compileTableContract (derived-lint.test.ts) —
+ * asserted-in-parallel implementations drift exactly where the examples don't look. The
+ * shapes: bare read → anon + authenticated; owner/via-scoped read → authenticated only;
+ * column-scoped self read (`owner` + `columns`) → its role (or authenticated); `{ role }`
+ * narrows to that role; manage → its role (or authenticated); model-private does NOT
+ * zero the audience (private models still compile grants — the auth.users pattern). Row
+ * scoping (RLS) filters rows, not reach — a grant that returns only your rows is still a
+ * grant.
+ */
+
+import type {
+  ModelDescriptor, DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor,
+  FunctionDescriptor, DependsOnRef, Ability,
+} from '@everystack/model';
+import { parseQualified } from './derived-source.js';
+
+export interface DerivedAuthzGap {
+  /** `schema.name` of the descriptor that fails the gate. */
+  identity: string;
+  message: string;
+}
+
+function identityOf(d: DerivedDescriptor): string {
+  const { schema, name } = parseQualified(d.name);
+  return `${schema}.${name}`;
+}
+
+function isModelRef(ref: DependsOnRef): ref is ModelDescriptor {
+  return 'table' in ref;
+}
+
+/** The column-scoped self read — same predicate as the table grant compiler. */
+function isColumnRead(a: Ability): boolean {
+  return a.action === 'read' && Boolean(a.condition.owner) && Boolean(a.condition.columns?.length);
+}
+
+/**
+ * Does the table's grant compile give `role` SELECT (full or column-scoped)?
+ *
+ * Exported for the differential pin against compileTableContract — this math must agree
+ * with the ACTUAL grant compiler for every ability shape, or the gate refuses views the
+ * database would serve (or worse, passes ones it won't). Note `private` on a MODEL is
+ * deliberately not consulted: private means "not exposed via the generic API", and its
+ * authz still compiles into real grants (the auth.users pattern — private + admin
+ * manage + column-scoped self read). The red team caught the gate treating model-private
+ * as zero-reach, which bricked every invoker view over a private table.
+ */
+export function tableReaches(m: ModelDescriptor, role: string): boolean {
+  for (const a of m.abilities) {
+    if (isColumnRead(a)) {
+      if ((a.condition.role ?? 'authenticated') === role) return true;
+      continue;
+    }
+    if (a.action !== 'read' && a.action !== 'manage') continue;
+    if (a.condition.role) {
+      if (a.condition.role === role) return true;
+      continue;
+    }
+    if (role === 'authenticated') return true;
+    if (role === 'anon' && a.action === 'read' && !a.condition.owner && !a.condition.via) return true;
+  }
+  return false;
+}
+
+/** The roles a relation's grants reach — bare read is anon + authenticated (the table precedent). */
+function relationRoles(d: ViewDescriptor | MaterializedViewDescriptor): Set<string> {
+  const roles = new Set<string>();
+  for (const a of d.abilities) {
+    if (a.condition.role) roles.add(a.condition.role);
+    else {
+      roles.add('anon');
+      roles.add('authenticated');
+    }
+  }
+  return roles;
+}
+
+function functionRoles(fn: FunctionDescriptor): Set<string> {
+  // define-time already rejected bare can('execute') — every ability carries a role.
+  return new Set(fn.abilities.map((a) => a.condition.role!));
+}
+
+// ---------------------------------------------------------------------------
+// Gate: derived read-gap (db:check fail)
+// ---------------------------------------------------------------------------
+
+/**
+ * Every declared relation makes its read decision or fails: an exposed view/matview with
+ * no read ability and no `private: true` is superuser-only from birth — the derived
+ * mirror of the table landmine findReadAuthzGaps catches.
+ */
+export function findDerivedReadGaps(derived: readonly DerivedDescriptor[]): DerivedAuthzGap[] {
+  const gaps: DerivedAuthzGap[] = [];
+  for (const d of derived) {
+    if (d.kind !== 'view' && d.kind !== 'materialized view') continue;
+    if (d.private || d.abilities.length > 0) continue;
+    const identity = identityOf(d);
+    gaps.push({
+      identity,
+      message:
+        `${identity} is a declared ${d.kind} with no read ability and no private: true — no app role can ` +
+        `read it, so it exists superuser-only. Declare can('read') for public data, can('read', { columns }) ` +
+        `to scope fields, or private: true if it is not part of the data API.`,
+    });
+  }
+  return gaps;
+}
+
+// ---------------------------------------------------------------------------
+// Gate: SECURITY DEFINER with no declared caller (db:check fail)
+// ---------------------------------------------------------------------------
+
+/**
+ * A definer function runs with its owner's rights; compiling one with no `can('execute')`
+ * is privileged code with an undeclared audience — callable by nobody today (PUBLIC is
+ * revoked unconditionally) and by whoever gets a grant tomorrow, with no declaration to
+ * review. Invoker functions may stay dark: unprivileged, owner-callable, honest.
+ */
+export function findSecdefExecuteGaps(derived: readonly DerivedDescriptor[]): DerivedAuthzGap[] {
+  const gaps: DerivedAuthzGap[] = [];
+  for (const d of derived) {
+    if (d.kind !== 'function' || d.security !== 'definer' || d.abilities.length > 0) continue;
+    const identity = identityOf(d);
+    gaps.push({
+      identity,
+      message:
+        `${identity} is SECURITY DEFINER with no declared caller — privileged code whose audience nobody ` +
+        `reviewed. Declare who calls it with can('execute', { role: '…' }), or make it security: 'invoker'.`,
+    });
+  }
+  return gaps;
+}
+
+// ---------------------------------------------------------------------------
+// Gate: matview snapshot over row-scoped sources (db:check warn)
+// ---------------------------------------------------------------------------
+
+/** Walk the declared closure through views (a matview's own snapshot is its own decision). */
+function closureModels(refs: readonly DependsOnRef[], seen = new Set<DependsOnRef>()): ModelDescriptor[] {
+  const models: ModelDescriptor[] = [];
+  for (const ref of refs) {
+    if (seen.has(ref)) continue;
+    seen.add(ref);
+    if (isModelRef(ref)) models.push(ref);
+    else if (ref.kind === 'view') models.push(...closureModels(ref.dependsOn, seen));
+  }
+  return models;
+}
+
+function rowScoped(m: ModelDescriptor): boolean {
+  return m.abilities.some((a) => a.condition.owner || a.condition.via);
+}
+
+/**
+ * A matview's rows are whatever its refresher could see, served flat to every granted
+ * role: over a row-scoped source, a superuser refresher snapshots EVERYTHING (broad), and
+ * a FORCE-RLS-subject owner silently snapshots a SUBSET (filtered) — both wrong in a
+ * different direction, neither visible in the schema. Warn, don't fail: an aggregating
+ * body (counts, sums) is the legitimate case, and only the author knows.
+ */
+export function findMatviewSnapshotWarnings(derived: readonly DerivedDescriptor[]): DerivedAuthzGap[] {
+  const warnings: DerivedAuthzGap[] = [];
+  for (const d of derived) {
+    if (d.kind !== 'materialized view' || d.private || d.abilities.length === 0) continue;
+    const scoped = closureModels(d.dependsOn).filter(rowScoped);
+    if (scoped.length === 0) continue;
+    const identity = identityOf(d);
+    const sources = scoped.map((m) => `${m.schema}.${m.table}`).join(', ');
+    warnings.push({
+      identity,
+      message:
+        `${identity} snapshots row-scoped source(s) ${sources} with the refresher's eyes — a superuser ` +
+        `refresh serves EVERY row flat to every granted role; a FORCE-RLS-subject owner silently snapshots ` +
+        `a subset. Confirm the body aggregates/filters away the per-row data, or declare private: true.`,
+    });
+  }
+  return warnings;
+}
+
+// ---------------------------------------------------------------------------
+// Gate: invoker-view grant reachability (compile fail)
+// ---------------------------------------------------------------------------
+
+/** The first ref in the closure `role` cannot reach, or null. */
+function findUnreachable(role: string, refs: readonly DependsOnRef[], seen: Set<DependsOnRef>): string | null {
+  for (const ref of refs) {
+    if (seen.has(ref)) continue;
+    seen.add(ref);
+    if (isModelRef(ref)) {
+      if (!tableReaches(ref, role)) return `${ref.schema}.${ref.table}`;
+      continue;
+    }
+    switch (ref.kind) {
+      case 'view': {
+        if (ref.private || !relationRoles(ref).has(role)) return identityOf(ref);
+        // An invoker dep re-checks the caller one level down; a definer dep reads as its owner.
+        if (ref.securityInvoker) {
+          const deeper = findUnreachable(role, ref.dependsOn, seen);
+          if (deeper) return deeper;
+        }
+        break;
+      }
+      case 'materialized view':
+        // A matview is its own snapshot: SELECT on the matview is the whole requirement.
+        if (ref.private || !relationRoles(ref).has(role)) return identityOf(ref);
+        break;
+      case 'function':
+        // The body calls it with the caller's rights — EXECUTE is part of reach.
+        if (!functionRoles(ref).has(role)) return identityOf(ref);
+        break;
+      case 'sql':
+        break; // opaque — never a false positive
+    }
+  }
+  return null;
+}
+
+/**
+ * `securityInvoker: true` + a grant to role R is a PROMISE that R can read the body's
+ * relations — PostgreSQL checks R, not the owner, against every one of them. This gate
+ * makes the promise static: every granted role must have reach through the declared
+ * `dependsOn` closure, or the view is granted-but-unreadable and the compile refuses.
+ */
+export function findInvokerReachabilityGaps(derived: readonly DerivedDescriptor[]): DerivedAuthzGap[] {
+  const gaps: DerivedAuthzGap[] = [];
+  for (const d of derived) {
+    if (d.kind !== 'view' || !d.securityInvoker || d.private || d.abilities.length === 0) continue;
+    const identity = identityOf(d);
+    for (const role of [...relationRoles(d)].sort()) {
+      const unreachable = findUnreachable(role, d.dependsOn, new Set());
+      if (unreachable) {
+        gaps.push({
+          identity,
+          message:
+            `view '${identity}' grants ${role} but its dependency '${unreachable}' gives ${role} no reach — ` +
+            `granted-but-unreadable (an invoker view reads with the caller's rights). Grant '${unreachable}' ` +
+            `to ${role}, seal the view with securityInvoker: false, or narrow the view's roles.`,
+        });
+      }
+    }
+  }
+  return gaps;
+}