@everystack/cli 0.2.37 → 0.2.40

package/src/cli/authz-contract.ts

@@ -0,0 +1,589 @@
+/**
+ * The Authorization Contract — introspection + format.
+ *
+ * The brownfield slice of the Model architecture (docs/plans/v3-authz-contract.md):
+ * authorization today lives scattered across migrations and the live database, with
+ * no artifact you can read, diff, or test against. This module is the read layer that
+ * extracts the *effective* authorization into a single reviewable shape.
+ *
+ * Two new introspection queries live here — the policy bodies (`pg_policies`) and the
+ * full per-grantee privilege matrix (`aclexplode` over `relacl`) — the layer neither
+ * `security-catalog` (functions + relations) nor `db:doctor` (RLS flags + role split)
+ * reads today. Same contract as security-catalog: the SQL runs through the ops Lambda
+ * (`db:query`); the mappers here are pure and unit-tested without a database.
+ *
+ * Frozen decisions (see the doc's "Open decisions"):
+ *   - SECDEF gates are enumerate-only; behaviour is proven by the RPC test layer.
+ *   - Per-table file layout (`authz/<table>.contract.json`).
+ *   - Predicate text is stored strict — the Postgres deparser output (pg_policies
+ *     already applies pg_get_expr), which is deterministic for a given parsed
+ *     expression regardless of the source whitespace/casing.
+ *   - The contract is a strict sublayer of the Model: defineModel compiles to it.
+ */
+
+import { parsePgArray } from './security-catalog.js';
+
+// ---------------------------------------------------------------------------
+// The contract format — the frozen, reviewable, version-controlled shape.
+// ---------------------------------------------------------------------------
+
+/** Per-table authorization: the RLS posture, grants, policies, and column exposure. */
+export interface TableContract {
+  /** Schema-qualified: `public.posts`. */
+  table: string;
+  rls: {
+    /** `relrowsecurity` — RLS is enabled on the table. */
+    enabled: boolean;
+    /** `relforcerowsecurity` — enforced even for the table owner (load-bearing under the credential split). */
+    forced: boolean;
+  };
+  /** Grantee (role name, or `PUBLIC`) -> the table-level privileges granted to it. */
+  grants: Record<string, string[]>;
+  /**
+   * Column-scoped grants (`GRANT SELECT (col) ON t TO role`): grantee -> privilege ->
+   * sorted column list. Postgres allows column privileges only for SELECT / INSERT /
+   * UPDATE / REFERENCES. This is how least-privilege exposes a subset of a table (e.g.
+   * `auth.users` to `authenticated` as id/email/role only, never the password hash), so
+   * it is first-class in the contract — a table-level grant view alone would miss it.
+   */
+  columnGrants?: Record<string, Record<string, string[]>>;
+  policies: PolicyContract[];
+  /**
+   * Column exposure (hiddenColumns / `.private()`, protectedFields / `.readonly()`).
+   * NOT a database fact — it lives in the handler/Model config — so the DB pull omits
+   * it entirely. Present only when a handler-config/Model producer fills it. Optional
+   * so the DB pull never claims an empty allowlist a diff would fail to flag.
+   */
+  columns?: {
+    /** Never in API responses. */
+    hidden: string[];
+    /** Never accepted on write. */
+    protected: string[];
+  };
+}
+
+/** One RLS policy, normalized to the deparsed predicate text. */
+export interface PolicyContract {
+  name: string;
+  /** `ALL` | `SELECT` | `INSERT` | `UPDATE` | `DELETE`. */
+  command: PolicyCommand;
+  /** Roles the policy applies to; `['public']` for a PUBLIC policy. */
+  roles: string[];
+  /**
+   * PERMISSIVE (OR-combined, the default) vs RESTRICTIVE (AND-combined). A restrictive
+   * policy is a different authorization than a permissive one with identical predicates,
+   * so it is part of the contract — omitting it would make the two look the same.
+   */
+  permissive: boolean;
+  /** `USING` predicate (deparsed), or null when the command has none (e.g. INSERT). */
+  using: string | null;
+  /** `WITH CHECK` predicate (deparsed), or null when absent. */
+  check: string | null;
+}
+
+/**
+ * One function, enumerated. The cross-table authorization that RLS does not hold lives
+ * in SECURITY DEFINER functions as imperative gates; the contract records that they
+ * exist and are correctly shaped (secdef, pinned search_path), and the RPC test layer
+ * proves the gate behaviourally. The imperative body is deliberately not modeled.
+ */
+export interface FunctionContract {
+  /** Schema-qualified: `public.transfer_post_ownership`. */
+  name: string;
+  securityDefiner: boolean;
+  /** A SECDEF function without a pinned `search_path` is a hijack vector. */
+  hasSearchPath: boolean;
+  /**
+   * True when the owner runs above RLS (superuser / BYPASSRLS / rds_superuser member).
+   * The owner *name* is deliberately not committed — it is environment-specific (local
+   * dev user vs deployed master vs a normalized operator), so it would false-fire the
+   * diff. This boolean is the portable, reviewable security fact.
+   * A SECURITY DEFINER function owned by such a role runs above RLS as that role on
+   * every call — the maximum blast radius SECDEF is meant to reduce. `db:migrate`
+   * commonly leaves functions superuser-owned; normalize ownership to a non-superuser
+   * operator. Pinned search_path is necessary but not sufficient.
+   */
+  ownerBypassesRls?: boolean;
+}
+
+/** The whole contract: every table and every function, as introspected. */
+export interface AuthzContract {
+  tables: TableContract[];
+  functions: FunctionContract[];
+}
+
+export type PolicyCommand = 'ALL' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+
+/** Runs one read-only SQL string and returns the rows. The backend (ops Lambda or a
+ *  direct connection) is the command's choice; the core stays backend-agnostic. */
+export type QueryRunner = (sql: string) => Promise<any[]>;
+
+// ---------------------------------------------------------------------------
+// Introspection — the two new queries.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every RLS policy with its deparsed predicates. `pg_policies` already applies
+ * `pg_get_expr` to `qual`/`with_check`, so the text is canonical for a given parsed
+ * expression. `roles` arrives as a `name[]` ({anon,authenticated}); `cmd` is the text
+ * form (`SELECT`, `ALL`, …); `permissive` is `PERMISSIVE`/`RESTRICTIVE`.
+ */
+export const POLICIES_SQL = `
+SELECT
+  schemaname  AS schema,
+  tablename   AS "table",
+  policyname  AS name,
+  cmd         AS command,
+  permissive,
+  roles,
+  qual        AS using_expr,
+  with_check  AS check_expr
+FROM pg_policies
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+  AND schemaname NOT LIKE 'pg_%'
+ORDER BY schemaname, tablename, policyname;
+`.trim();
+
+/**
+ * The full per-grantee privilege matrix — what the schema *declares*, not what a role
+ * effectively inherits (inheritance resolution belongs in the red-team test, which
+ * SET ROLEs and tries). `aclexplode(relacl)` expands the ACL into one row per
+ * (grantee, privilege); a NULL `relacl` means only the owner has privileges (default),
+ * so the table simply produces no grant rows — correctly "no broad grants." Grantee
+ * OID 0 is PUBLIC. Extension-owned tables are excluded via pg_depend, matching the
+ * relations query so vendor objects never need a waiver.
+ *
+ * The table OWNER's self-grant is excluded: it is environment-specific (the local dev
+ * user locally, the master/operator role when deployed) and tautological (the owner
+ * implicitly holds every privilege), so committing it would make the contract
+ * non-portable and drift on every environment. A least-priv app role like
+ * `authenticator` is *not* the owner and is kept — a direct grant to it is a real
+ * (and usually wrong) authorization fact the contract should surface.
+ */
+export const GRANTS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  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 ('r', 'v', 'm')
+  AND c.relacl IS NOT NULL
+  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 d
+    WHERE d.objid = c.oid AND d.deptype = 'e'
+  )
+GROUP BY n.nspname, c.relname, r.rolname
+ORDER BY n.nspname, c.relname, grantee;
+`.trim();
+
+/**
+ * Column-scoped grants from `pg_attribute.attacl` — the privilege layer `relacl` (and
+ * thus GRANTS_SQL) cannot see. `GRANT SELECT (id, email) ON t TO role` lives here, not
+ * in the table ACL. Owner self-grants and extension tables are excluded to match
+ * GRANTS_SQL, so the two compose into one grant picture without double-counting.
+ */
+export const COLUMN_GRANTS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  a.attname AS "column",
+  COALESCE(r.rolname, 'PUBLIC') AS grantee,
+  acl.privilege_type AS privilege
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+CROSS JOIN LATERAL aclexplode(a.attacl) acl
+LEFT JOIN pg_roles r ON r.oid = acl.grantee
+WHERE a.attacl IS NOT NULL
+  AND acl.grantee <> c.relowner
+  AND c.relkind IN ('r', 'v', 'm')
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend d
+    WHERE d.objid = c.oid AND d.deptype = 'e'
+  )
+ORDER BY n.nspname, c.relname, grantee, privilege, a.attname;
+`.trim();
+
+/**
+ * Every base table with its RLS posture — the table enumerator for the contract.
+ * `relrowsecurity` / `relforcerowsecurity` give enabled/forced. A table absent from
+ * this set has no RLS row to report; a table present with `enabled: false` is the
+ * dangerous case the contract makes visible (an ungated table). Extension-owned tables
+ * are excluded via pg_depend, matching the other queries.
+ */
+export const RLS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  c.relrowsecurity      AS enabled,
+  c.relforcerowsecurity AS forced
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend d
+    WHERE d.objid = c.oid AND d.deptype = 'e'
+  )
+ORDER BY n.nspname, c.relname;
+`.trim();
+
+// ---------------------------------------------------------------------------
+// Pure mappers — one catalog row -> one descriptor.
+// ---------------------------------------------------------------------------
+
+/** Coerce a Postgres boolean (true | 't' | 'true' | 1) into a JS boolean. */
+function truthy(v: unknown): boolean {
+  return v === true || v === 't' || v === 'true' || v === 1 || v === '1';
+}
+
+/** A non-empty predicate, trimmed; null/empty/whitespace -> null (a missing clause). */
+function predicate(v: unknown): string | null {
+  if (v == null) return null;
+  const s = String(v).trim();
+  return s.length > 0 ? s : null;
+}
+
+export interface PolicyRow {
+  schema: string;
+  table: string;
+  name: string;
+  command: unknown;
+  permissive: unknown;
+  roles: unknown;
+  using_expr: unknown;
+  check_expr: unknown;
+}
+
+/** Map a `pg_policies` row to a policy descriptor keyed by its schema-qualified table. */
+export function policyRowToDescriptor(row: PolicyRow): { table: string; policy: PolicyContract } {
+  const command = String(row.command ?? '').toUpperCase();
+  return {
+    table: `${row.schema}.${row.table}`,
+    policy: {
+      name: row.name,
+      command: (command || 'ALL') as PolicyCommand,
+      // pg_policies.permissive is the text 'PERMISSIVE' | 'RESTRICTIVE'.
+      permissive: String(row.permissive ?? 'PERMISSIVE').toUpperCase() !== 'RESTRICTIVE',
+      roles: parsePgArray(row.roles) ?? [],
+      using: predicate(row.using_expr),
+      check: predicate(row.check_expr),
+    },
+  };
+}
+
+export interface GrantRow {
+  schema: string;
+  table: string;
+  grantee: unknown;
+  privileges: unknown;
+}
+
+/** Map an `aclexplode` row to a grant descriptor keyed by its schema-qualified table. */
+export function grantRowToDescriptor(row: GrantRow): {
+  table: string;
+  grantee: string;
+  privileges: string[];
+} {
+  return {
+    table: `${row.schema}.${row.table}`,
+    grantee: String(row.grantee ?? 'PUBLIC'),
+    privileges: parsePgArray(row.privileges) ?? [],
+  };
+}
+
+export interface ColumnGrantRow {
+  schema: string;
+  table: string;
+  column: string;
+  grantee: unknown;
+  privilege: unknown;
+}
+
+/** Map a column-grant row to its schema-qualified table + grantee/privilege/column. */
+export function columnGrantRowToDescriptor(row: ColumnGrantRow): {
+  table: string;
+  grantee: string;
+  privilege: string;
+  column: string;
+} {
+  return {
+    table: `${row.schema}.${row.table}`,
+    grantee: String(row.grantee ?? 'PUBLIC'),
+    privilege: String(row.privilege ?? '').toUpperCase(),
+    column: String(row.column),
+  };
+}
+
+export interface RlsRow {
+  schema: string;
+  table: string;
+  enabled: unknown;
+  forced: unknown;
+}
+
+/** Map a `pg_class` RLS-flags row to its schema-qualified table + posture. */
+export function rlsRowToDescriptor(row: RlsRow): {
+  table: string;
+  rls: { enabled: boolean; forced: boolean };
+} {
+  return {
+    table: `${row.schema}.${row.table}`,
+    rls: { enabled: truthy(row.enabled), forced: truthy(row.forced) },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Assembly — fold the row sets into one normalized, deterministic contract.
+// ---------------------------------------------------------------------------
+
+/**
+ * Schemas owned by migration tooling, not the app — excluded from the contract.
+ * `drizzle` holds drizzle-kit's `__drizzle_migrations` journal: it has no policies, no
+ * meaningful grants, and exists only when migrations ran through drizzle's migrator
+ * (so it appears on a deployed stage but not on a raw-applied local DB — pure noise
+ * that would read as local↔remote drift). Same intent as the pg_depend extension filter.
+ */
+export const IGNORED_SCHEMAS = new Set(['drizzle']);
+
+export interface ContractRows {
+  rls: RlsRow[];
+  policies: PolicyRow[];
+  grants: GrantRow[];
+  columnGrants?: ColumnGrantRow[];
+  /** Already-mapped function descriptors (from security-catalog's FUNCTIONS_SQL). */
+  functions: { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean }[];
+}
+
+/**
+ * Fold introspected rows into the contract. Deterministic: tables sorted by name,
+ * policies by name, grant grantees and privilege lists sorted — so the serialized
+ * files are byte-stable and a re-pull of an unchanged database is a no-op diff.
+ *
+ * Column exposure (hidden/protected) is *not* a database fact — it lives in the
+ * handler/Model config — so the DB pull omits `columns` entirely rather than claim an
+ * empty allowlist a diff would never flag. Only SECURITY DEFINER functions are
+ * recorded: an INVOKER function runs as the caller under RLS and is not an
+ * authorization decision point; a SECDEF function runs above RLS and is.
+ */
+export function assembleContract(rows: ContractRows): AuthzContract {
+  const tables = new Map<string, TableContract>();
+  for (const row of rows.rls) {
+    if (IGNORED_SCHEMAS.has(row.schema)) continue;
+    const { table, rls } = rlsRowToDescriptor(row);
+    tables.set(table, { table, rls, grants: {}, policies: [] });
+  }
+
+  // A grant or policy on a table the RLS enumerator didn't list (e.g. a view, excluded
+  // above) is dropped rather than synthesizing a table with unknown RLS posture.
+  for (const row of rows.grants) {
+    const { table, grantee, privileges } = grantRowToDescriptor(row);
+    const t = tables.get(table);
+    if (t) t.grants[grantee] = [...privileges].sort();
+  }
+  for (const row of rows.policies) {
+    const { table, policy } = policyRowToDescriptor(row);
+    const t = tables.get(table);
+    if (t) t.policies.push({ ...policy, roles: [...policy.roles].sort() });
+  }
+  for (const row of rows.columnGrants ?? []) {
+    const { table, grantee, privilege, column } = columnGrantRowToDescriptor(row);
+    const t = tables.get(table);
+    if (!t) continue;
+    const byGrantee = (t.columnGrants ??= {});
+    const byPriv = (byGrantee[grantee] ??= {});
+    (byPriv[privilege] ??= []).push(column);
+  }
+
+  for (const t of tables.values()) {
+    t.policies.sort((a, b) => a.name.localeCompare(b.name));
+    for (const byPriv of Object.values(t.columnGrants ?? {})) {
+      for (const cols of Object.values(byPriv)) cols.sort();
+    }
+  }
+
+  const functions: FunctionContract[] = rows.functions
+    .filter((f) => f.securityDefiner && !IGNORED_SCHEMAS.has(f.schema))
+    .map((f) => ({
+      name: `${f.schema}.${f.name}`,
+      securityDefiner: true,
+      hasSearchPath: f.hasSearchPath,
+      ...(f.ownerBypassesRls !== undefined ? { ownerBypassesRls: f.ownerBypassesRls } : {}),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    tables: [...tables.values()].sort((a, b) => a.table.localeCompare(b.table)),
+    functions,
+  };
+}
+
+/** Run every introspection query through one runner and assemble the contract. */
+export async function introspectContract(
+  run: QueryRunner,
+  mapFunctionRow: (row: any) => { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean },
+  functionsSql: string,
+): Promise<AuthzContract> {
+  const [rls, policies, grants, columnGrants, fnRows] = await Promise.all([
+    run(RLS_SQL),
+    run(POLICIES_SQL),
+    run(GRANTS_SQL),
+    run(COLUMN_GRANTS_SQL),
+    run(functionsSql),
+  ]);
+  return assembleContract({
+    rls: rls as RlsRow[],
+    policies: policies as PolicyRow[],
+    grants: grants as GrantRow[],
+    columnGrants: columnGrants as ColumnGrantRow[],
+    functions: (fnRows as any[]).map(mapFunctionRow),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Diff — declared (committed contract) vs live (introspected). Strict text compare.
+// ---------------------------------------------------------------------------
+
+export type DriftSeverity = 'drift';
+
+export interface DriftFinding {
+  /** Schema-qualified table, or `fn:<name>` for a function finding. */
+  subject: string;
+  /** What changed: rls | grant | policy | table | function. */
+  kind: 'rls' | 'grant' | 'policy' | 'table' | 'function';
+  detail: string;
+}
+
+function tableMap(c: AuthzContract): Map<string, TableContract> {
+  return new Map(c.tables.map((t) => [t.table, t]));
+}
+
+/**
+ * Compare the declared contract (committed source of truth) against the live database.
+ * Strict: predicate text is compared verbatim — the Postgres deparser is deterministic,
+ * so a re-pull of an unchanged policy is identical and any difference is a real change.
+ * Returns every discrepancy; an empty list means the live DB matches the declaration.
+ */
+export function diffContracts(declared: AuthzContract, live: AuthzContract): DriftFinding[] {
+  const findings: DriftFinding[] = [];
+  const dTables = tableMap(declared);
+  const lTables = tableMap(live);
+
+  for (const [name, d] of dTables) {
+    const l = lTables.get(name);
+    if (!l) {
+      findings.push({ subject: name, kind: 'table', detail: 'declared table is missing from the live database' });
+      continue;
+    }
+    if (d.rls.enabled !== l.rls.enabled) {
+      findings.push({ subject: name, kind: 'rls', detail: `RLS enabled: declared ${d.rls.enabled}, live ${l.rls.enabled}` });
+    }
+    if (d.rls.forced !== l.rls.forced) {
+      findings.push({ subject: name, kind: 'rls', detail: `RLS forced: declared ${d.rls.forced}, live ${l.rls.forced}` });
+    }
+    diffGrants(name, d, l, findings);
+    diffColumnGrants(name, d, l, findings);
+    diffPolicies(name, d, l, findings);
+  }
+  for (const name of lTables.keys()) {
+    if (!dTables.has(name)) {
+      findings.push({ subject: name, kind: 'table', detail: 'live table is not in the declared contract (undeclared table)' });
+    }
+  }
+
+  const dFns = new Map(declared.functions.map((f) => [f.name, f]));
+  const lFns = new Map(live.functions.map((f) => [f.name, f]));
+  for (const [name, d] of dFns) {
+    const l = lFns.get(name);
+    if (!l) {
+      findings.push({ subject: `fn:${name}`, kind: 'function', detail: 'declared SECDEF function is missing from the live database' });
+      continue;
+    }
+    if (d.hasSearchPath !== l.hasSearchPath) {
+      findings.push({ subject: `fn:${name}`, kind: 'function', detail: `pinned search_path: declared ${d.hasSearchPath}, live ${l.hasSearchPath}` });
+    }
+    if (d.ownerBypassesRls !== undefined && l.ownerBypassesRls !== undefined && d.ownerBypassesRls !== l.ownerBypassesRls) {
+      findings.push({ subject: `fn:${name}`, kind: 'function', detail: `owner bypasses RLS: declared ${d.ownerBypassesRls}, live ${l.ownerBypassesRls}` });
+    }
+  }
+  for (const name of lFns.keys()) {
+    if (!dFns.has(name)) {
+      findings.push({ subject: `fn:${name}`, kind: 'function', detail: 'live SECDEF function is not in the declared contract' });
+    }
+  }
+
+  return findings;
+}
+
+function diffGrants(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
+  const grantees = new Set([...Object.keys(d.grants), ...Object.keys(l.grants)]);
+  for (const g of grantees) {
+    const dp = (d.grants[g] ?? []).join(',');
+    const lp = (l.grants[g] ?? []).join(',');
+    if (dp !== lp) {
+      out.push({ subject: table, kind: 'grant', detail: `grant to ${g}: declared [${dp}], live [${lp}]` });
+    }
+  }
+}
+
+/** Flatten columnGrants to `grantee/PRIV -> sorted column csv` for a stable comparison. */
+function flattenColumnGrants(t: TableContract): Map<string, string> {
+  const flat = new Map<string, string>();
+  for (const [grantee, byPriv] of Object.entries(t.columnGrants ?? {})) {
+    for (const [priv, cols] of Object.entries(byPriv)) {
+      flat.set(`${grantee}/${priv}`, [...cols].sort().join(','));
+    }
+  }
+  return flat;
+}
+
+function diffColumnGrants(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
+  const dc = flattenColumnGrants(d);
+  const lc = flattenColumnGrants(l);
+  for (const key of new Set([...dc.keys(), ...lc.keys()])) {
+    const dCols = dc.get(key) ?? '';
+    const lCols = lc.get(key) ?? '';
+    if (dCols !== lCols) {
+      out.push({ subject: table, kind: 'grant', detail: `column grant ${key}: declared (${dCols}), live (${lCols})` });
+    }
+  }
+}
+
+function diffPolicies(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
+  const dPol = new Map(d.policies.map((p) => [p.name, p]));
+  const lPol = new Map(l.policies.map((p) => [p.name, p]));
+  for (const [name, dp] of dPol) {
+    const lp = lPol.get(name);
+    if (!lp) {
+      out.push({ subject: table, kind: 'policy', detail: `policy "${name}" declared but missing from the live database` });
+      continue;
+    }
+    const changes: string[] = [];
+    if (dp.command !== lp.command) changes.push(`command ${dp.command}→${lp.command}`);
+    if (dp.permissive !== lp.permissive) changes.push(`permissive ${dp.permissive}→${lp.permissive}`);
+    if (dp.roles.join(',') !== lp.roles.join(',')) changes.push(`roles [${dp.roles}]→[${lp.roles}]`);
+    if ((dp.using ?? '') !== (lp.using ?? '')) changes.push(`USING changed`);
+    if ((dp.check ?? '') !== (lp.check ?? '')) changes.push(`WITH CHECK changed`);
+    if (changes.length) {
+      out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
+    }
+  }
+  for (const name of lPol.keys()) {
+    if (!dPol.has(name)) {
+      out.push({ subject: table, kind: 'policy', detail: `policy "${name}" exists live but is not declared (undeclared policy)` });
+    }
+  }
+}
+
+/** Re-export so a future assembler treats RLS flags the same coercion way as the rest. */
+export { truthy as coerceBool };