@everystack/cli 0.4.41 → 0.4.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.41",
+  "version": "0.4.43",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -109,7 +109,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.7"
+    "@everystack/model": "0.4.8"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",

package/src/cli/authz-compile.ts

@@ -22,6 +22,7 @@
 
 import type { ModelDescriptor, Ability } from '@everystack/model';
 import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract.js';
+import { parenthesizeOnce } from './authz-contract.js';
 
 export interface CompileOptions {
   /** Schema the table lives in. Default: `public`. */
@@ -176,9 +177,17 @@ function resolveVia(model: ModelDescriptor): ViaRef | null {
   };
 }
 
-/** The conventional soft-delete column SQL name, when the model has one. */
+/**
+ * The soft-delete column SQL name, when the model DECLARES one.
+ *
+ * Keyed on `softDelete`, never on the field's presence. A column named `deleted_at` is not a
+ * statement of visibility intent, and inferring the guard from it made the compiler author a
+ * security predicate nobody wrote — one that `db:pull` then handed to every brownfield model
+ * automatically, so the first plan narrowed a policy the adopter had written. `defineModel`
+ * refuses to guess: a model with the field and a public read must say which it means.
+ */
 function softDeleteColumn(model: ModelDescriptor): string | null {
-  return 'deletedAt' in model.fields ? 'deleted_at' : null;
+  return model.softDelete ? 'deleted_at' : null;
 }
 
 /**
@@ -228,7 +237,11 @@ function rawPredicate(value: unknown, where: string): string | null {
       `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — an RLS predicate is authored, never stringly assembled.`,
     );
   }
-  return `(${text.trim()})`;
+  // Parenthesized exactly once. A pulled predicate arrives already fully parenthesized
+  // (that is how pg_get_expr deparses it), and wrapping it again made the compiled policy
+  // differ from the live one by a single layer of parens — enough for the reconciler to
+  // plan a DROP + CREATE that changed nothing.
+  return parenthesizeOnce(text.trim());
 }
 
 /** AND-compose predicates, dropping the vacuous ones. A condition only ever NARROWS. */
@@ -266,11 +279,20 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // A "row-scoped" condition is either a direct owner or a transitive via.
   const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
 
+  /**
+   * A read scoped to a named role — `can('read', { role })`. It compiles to its own
+   * `<table>_select_<role>` policy, so its predicate must NOT also be folded into the
+   * public read's predicate: a rule written for one role would otherwise narrow what
+   * every other role can see.
+   */
+  const isRoleRead = (a: Ability): boolean =>
+    a.action === 'read' && Boolean(a.condition.role) && !isColumnRead(a);
+
   // Author-supplied predicates, per action. `manage` carries no predicate of its own —
   // it is the admin bypass — so only the specific verbs are consulted.
   const predFor = (action: Ability['action']): string | null => {
     for (const a of model.abilities) {
-      if (a.action !== action) continue;
+      if (a.action !== action || isRoleRead(a)) continue;
       const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('${action}')`);
       if (p) return p;
     }
@@ -336,6 +358,26 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     policy(`${t}_select_self`, 'SELECT', ['authenticated'], rowPred, null);
   }
 
+  // Role-scoped reads — `can('read', { role })`, with or without a predicate. These match
+  // none of the branches above: the public read requires NO role, and the owner/column reads
+  // require a row-scoping condition. Before this they compiled to a SELECT grant and no
+  // policy at all — and since `rls.enabled` is unconditional, the role saw ZERO rows while
+  // the model read as though it could see its own. The declared predicate was computed and
+  // discarded. That is the same failure `rawPredicate` throws over, one level up: a predicate
+  // that evaporates is an authorization hole wearing the costume of a working rule.
+  for (const a of abilities.filter(isRoleRead)) {
+    const role = a.condition.role!;
+    const name = `${t}_select_${role}`;
+    const where = `${table}: can('read', { role: '${role}' })`;
+    if (policies.some((p) => p.name === name)) {
+      throw new Error(
+        `${where} collides with the ${name} policy already compiled from this model's public read. `
+        + `Declare one or the other: permissive policies OR together, so the role-scoped rule could only ever widen — never the narrowing it reads as.`,
+      );
+    }
+    policy(name, 'SELECT', [role], rawPredicate(a.condition.sql ?? a.condition.where, where) ?? 'true', null);
+  }
+
   // owner-gated writes. INSERT checks ownership (you can only create rows you own);
   // UPDATE gates + checks; DELETE gates. `rowPred` is the direct-owner or `via:` predicate.
   //

package/src/cli/authz-contract.ts

@@ -82,6 +82,51 @@ export interface PolicyContract {
   check: string | null;
 }
 
+/**
+ * The WITH CHECK expression PostgreSQL will actually enforce.
+ *
+ * For `ALL` and `UPDATE`, an omitted `WITH CHECK` is not "no check" — the server reuses the
+ * `USING` expression. So a live `FOR ALL USING (true)` (which is what `CREATE POLICY … USING
+ * (true)` records, with `pg_policies.with_check` NULL) and a compiled `FOR ALL USING (true)
+ * WITH CHECK (true)` are the SAME authorization. Comparing the raw fields calls them
+ * different and plans a DROP + CREATE — the loudest possible way to say "no change", and it
+ * defeats a zero-statement bar even when the SQL is identical.
+ *
+ * `INSERT` has only a check, `SELECT`/`DELETE` have none — for those the field stands alone
+ * and no defaulting applies.
+ */
+export function effectivePolicyCheck(p: PolicyContract): string | null {
+  if (p.command === 'ALL' || p.command === 'UPDATE') return p.check ?? p.using;
+  return p.check;
+}
+
+/** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
+export function isWrappedExpression(s: string): boolean {
+  if (!s.startsWith('(') || !s.endsWith(')')) return false;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * A predicate parenthesized exactly once — the normal form both producers must agree on.
+ *
+ * `pg_get_expr` already deparses a policy predicate fully parenthesized, so `db:pull` renders
+ * one into a model verbatim. Wrapping it again produced a compiled predicate identical to
+ * live but for one layer of parens, which the equality check called a difference and turned
+ * into a same-name DROP + CREATE that changed nothing. Emission already knew this rule; the
+ * comparison did not, so both go through this.
+ */
+export function parenthesizeOnce(expr: string): string {
+  return isWrappedExpression(expr) ? expr : `(${expr})`;
+}
+
 /**
  * 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
@@ -581,7 +626,9 @@ function diffPolicies(table: string, d: TableContract, l: TableContract, out: Dr
     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`);
+    // Compared through the server's own defaulting rule, so this agrees with
+    // emitReconcileSql — otherwise db:check reports drift the plan does not carry.
+    if ((effectivePolicyCheck(dp) ?? '') !== (effectivePolicyCheck(lp) ?? '')) changes.push(`WITH CHECK changed`);
     if (changes.length) {
       out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
     }

package/src/cli/authz-reconcile.ts

@@ -16,6 +16,7 @@
  */
 
 import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import { effectivePolicyCheck, parenthesizeOnce } from './authz-contract.js';
 import { quoteQualified } from './pg-ident.js';
 
 /**
@@ -116,24 +117,8 @@ export function renderGrantExemptions(exemptions: readonly GrantExemption[]): st
   return lines;
 }
 
-/** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
-function isWrapped(s: string): boolean {
-  if (!s.startsWith('(') || !s.endsWith(')')) return false;
-  let depth = 0;
-  for (let i = 0; i < s.length; i++) {
-    if (s[i] === '(') depth++;
-    else if (s[i] === ')') {
-      depth--;
-      if (depth === 0 && i < s.length - 1) return false;
-    }
-  }
-  return depth === 0;
-}
-
 /** A USING/WITH CHECK clause expression, parenthesized exactly once. */
-function clause(expr: string): string {
-  return isWrapped(expr) ? expr : `(${expr})`;
-}
+const clause = parenthesizeOnce;
 
 /** A CREATE POLICY statement from a policy descriptor. */
 function policyCreateSql(table: string, p: PolicyContract): string {
@@ -150,13 +135,19 @@ function policyDropSql(table: string, name: string): string {
   return `DROP POLICY IF EXISTS ${name} ON ${table};`;
 }
 
-/** Two policies are the same authorization when every diffed field matches. */
+/**
+ * Two policies are the same authorization when every diffed field matches. The check is
+ * compared through {@link effectivePolicyCheck}, i.e. the server's own defaulting rule —
+ * a live `FOR ALL USING (true)` and a compiled `FOR ALL USING (true) WITH CHECK (true)`
+ * authorize identically, and reconciling them would emit a DROP + CREATE that changes
+ * nothing.
+ */
 function policiesEqual(a: PolicyContract, b: PolicyContract): boolean {
   return a.command === b.command
     && a.permissive === b.permissive
     && a.roles.join(',') === b.roles.join(',')
     && (a.using ?? '') === (b.using ?? '')
-    && (a.check ?? '') === (b.check ?? '');
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
 }
 
 function tableMap(c: AuthzContract): Map<string, TableContract> {

package/src/cli/authz-redteam.ts

@@ -40,7 +40,7 @@ export interface ProbeResult {
 }
 
 export interface RedTeamFinding {
-  severity: 'hole' | 'broken' | 'unprobed' | 'inconclusive' | 'inherited';
+  severity: 'hole' | 'broken' | 'unprobed' | 'inconclusive' | 'inherited' | 'elevated';
   role: string;
   table: string;
   command: ProbeCommand;
@@ -244,6 +244,9 @@ export interface InheritedGrant {
   table: string;   // schema-qualified
   command: ProbeCommand;
   via: string;     // the ancestor role(s) supplying it
+  /** True when an ancestor is SUPERUSER or BYPASSRLS — the role bypasses RLS entirely,
+   *  which makes every probe result for it vacuous. Drives the severity split. */
+  elevated: boolean;
 }
 
 /**
@@ -273,7 +276,8 @@ WITH RECURSIVE anc AS (
 SELECT r.rolname AS role,
        (c.relnamespace::regnamespace::text || '.' || c.relname) AS "table",
        p.priv AS command,
-       string_agg(DISTINCT ar.rolname, ', ' ORDER BY ar.rolname) AS via
+       string_agg(DISTINCT ar.rolname, ', ' ORDER BY ar.rolname) AS via,
+       bool_or(ar.rolsuper OR ar.rolbypassrls) AS elevated
 FROM pg_class c
 CROSS JOIN (VALUES ('SELECT'),('INSERT'),('UPDATE'),('DELETE')) AS p(priv)
 JOIN pg_roles r ON r.rolname = ANY(${pgArrayLiteral(roles)})
@@ -296,6 +300,10 @@ export function toInheritedGrant(row: any): InheritedGrant {
     table: String(row.table),
     command: String(row.command).toUpperCase() as ProbeCommand,
     via: String(row.via),
+    // An ancestor that is SUPERUSER or BYPASSRLS makes every probe result for this role
+    // vacuous — default-deny cannot be falsified and RLS assertions are void. That is a
+    // different finding from inheriting an ordinary role's grants, and it is graded so.
+    elevated: row.elevated === true || row.elevated === 't' || row.elevated === 'true',
   };
 }
 
@@ -329,8 +337,8 @@ export function evaluateRedTeam(
   const findings: RedTeamFinding[] = [];
   // Privileges explained by role membership rather than a direct grant. Keyed so the
   // per-result lookup is exact; reported once per role, not once per table × command.
-  const inheritedBy = new Map(inherited.map((g) => [`${g.role}${g.table}${g.command}`, g]));
-  const inheritedRoles = new Map<string, { via: string; count: number }>();
+  const inheritedBy = new Map(inherited.map((g) => [`${g.role}\u0000${g.table}\u0000${g.command}`, g]));
+  const inheritedRoles = new Map<string, { via: string; count: number; elevated: boolean }>();
 
   for (const r of results) {
     const table = tablesByName.get(r.table);
@@ -347,12 +355,12 @@ export function evaluateRedTeam(
       findings.push({ severity: 'inconclusive', role: r.role, table: r.table, command: r.command,
         detail: `${r.command} on ${r.table} failed before the privilege check — this probe proves nothing about ${r.role}` });
     } else if (allowed && !granted) {
-      const via = inheritedBy.get(`${r.role}${r.table}${r.command}`);
+      const via = inheritedBy.get(`${r.role}\u0000${r.table}\u0000${r.command}`);
       if (via) {
         // Real, but it is one fact about a role, not N facts about N tables.
         const seen = inheritedRoles.get(r.role);
-        if (seen) seen.count += 1;
-        else inheritedRoles.set(r.role, { via: via.via, count: 1 });
+        if (seen) { seen.count += 1; seen.elevated ||= via.elevated; }
+        else inheritedRoles.set(r.role, { via: via.via, count: 1, elevated: via.elevated });
       } else {
         findings.push({ severity: 'hole', role: r.role, table: r.table, command: r.command,
           detail: `${r.role} can ${r.command} ${r.table} but the contract grants no such privilege (enforcement exceeds declaration)` });
@@ -366,9 +374,23 @@ export function evaluateRedTeam(
   // One line per inheriting role. The membership IS the finding — a role that reaches
   // tables through `GRANT parent TO child` is worth stating out loud once, and worth not
   // stating N times.
-  for (const [role, { via, count }] of inheritedRoles) {
-    findings.push({ severity: 'inherited', role, table: '', command: 'SELECT',
-      detail: `${role} holds ${count} undeclared privilege(s) INHERITED via membership in ${via} — not a direct grant, so the contract cannot see them. Intentional for a migrator/owner role; a finding if it is an application role` });
+  for (const [role, { via, count, elevated }] of inheritedRoles) {
+    // The severity axis is WHAT the ancestor is, not that inheritance happened.
+    //
+    // An ordinary ancestor's grants are finite, enumerable, and still RLS-subject: the
+    // database enforces declared ∪ inherited, which is a completeness note.
+    //
+    // A SUPERUSER/BYPASSRLS ancestor is categorically different. The role bypasses every
+    // policy, its effective access is unbounded, and every probe result for it is vacuous —
+    // this tool cannot vouch for the role at all. Reporting that at the same level as
+    // "could not SET ROLE into this role" is what let an adopter read the run as clean.
+    if (elevated) {
+      findings.push({ severity: 'elevated', role, table: '', command: 'SELECT',
+        detail: `${role} inherits ${via}, which is SUPERUSER or BYPASSRLS — it bypasses every RLS policy and holds privileges no ACL lists (${count} seen here). Every probe result for ${role} is vacuous: this run cannot vouch for it` });
+    } else {
+      findings.push({ severity: 'inherited', role, table: '', command: 'SELECT',
+        detail: `${role} holds ${count} undeclared privilege(s) INHERITED via membership in ${via} — not a direct grant, so the contract cannot see them. Intentional for a migrator/owner role; a finding if it is an application role` });
+    }
   }
   return findings;
 }

package/src/cli/commands/db-authz.ts

@@ -252,12 +252,20 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   const unprobed = findings.filter((f) => f.severity === 'unprobed');
   const inconclusive = findings.filter((f) => f.severity === 'inconclusive');
   const inheritedFindings = findings.filter((f) => f.severity === 'inherited');
+  // An ancestor that is SUPERUSER/BYPASSRLS makes every probe for that role vacuous. It is
+  // NOT an enforcement hole — the database enforces exactly what the grants say — so it does
+  // not fail the gate, which would go red on the many legitimate elevated migration roles
+  // and teach adopters to stop running it. But it is warn-grade, and it must qualify the
+  // success line: people read the checkmark and stop, which is exactly how the first adopter
+  // came away thinking a real finding had been dismissed.
+  const elevatedFindings = findings.filter((f) => f.severity === 'elevated');
   const gaps = gapRows.map(toGrantGap);
 
   console.log('');
   for (const f of holes) fail(`[HOLE]   ${f.detail}`);
   for (const f of broken) warn(`[BROKEN] ${f.detail}`);
   for (const g of gaps) fail(`[GRANT-GAP] ${g.secdef} calls ${g.helper} but its owner cannot EXECUTE it (42501 in prod once ownership is normalized)`);
+  for (const f of elevatedFindings) warn(`[ELEVATED] ${f.detail}`);
   for (const f of inheritedFindings) info(`[inherited] ${f.detail}`);
   if (inconclusive.length) {
     // Never a pass and never a failure — a probe that proved nothing, said out loud so it
@@ -273,7 +281,15 @@ export async function dbAuthzTestCommand(flags: Record<string, string>): Promise
   console.log('');
 
   if (holes.length === 0 && broken.length === 0 && gaps.length === 0) {
-    success(`db:authz:test — ${venueLabel} enforces the contract (${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete)`);
+    // "default-deny holds" is a FALSE UNIVERSAL when a role bypasses RLS. Any claim this run
+    // could not verify for a role is excluded from the claim in the sentence that makes it,
+    // so a reader who sees only the green line still learns one role is outside it.
+    const exempt = elevatedFindings.map((f) => f.role).sort();
+    const scope = exempt.length
+      ? `${contract.tables.length} tables probed; default-deny holds EXCEPT for ${exempt.join(', ')} — `
+        + `${exempt.length === 1 ? 'that role bypasses RLS by inheritance and this run cannot vouch for it' : 'those roles bypass RLS by inheritance and this run cannot vouch for them'}`
+      : `${contract.tables.length} tables probed, default-deny holds, SECDEF grants complete`;
+    success(`db:authz:test — ${venueLabel} enforces the contract (${scope})`);
     process.exit(0);
   }
   fail(`db:authz:test — ${holes.length} enforcement hole(s), ${broken.length} broken grant(s), ${gaps.length} SECDEF grant gap(s). ${venueLabel} does not enforce the contract.`);

package/src/cli/commands/db-plan.ts

@@ -19,6 +19,7 @@
  */
 
 import fs from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
@@ -42,6 +43,23 @@ import { step, success, fail, info, warn } from '../output.js';
 
 const DEFAULT_OUT = 'db.plan.json';
 
+/**
+ * True when git would ignore `file` — false when it would happily commit it, and ALSO false
+ * outside a repo or when git is unavailable, because the warning is only ever advice and a
+ * missing git must not turn a plan mint into a failure.
+ *
+ * `check-ignore` exits 0 for ignored, 1 for not-ignored, 128 for "not a repo".
+ */
+function isGitIgnored(file: string): boolean {
+  try {
+    const r = spawnSync('git', ['check-ignore', '-q', file], { stdio: 'ignore' });
+    if (r.error || r.status === 128) return true; // no repo / no git — nothing to warn about
+    return r.status === 0;
+  } catch {
+    return true;
+  }
+}
+
 export async function dbPlanCommand(flags: Record<string, string>): Promise<void> {
   let dbSource: DbSource;
   try {
@@ -161,6 +179,12 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     if (out !== '-') {
       success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
       warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');
+      // "Do NOT commit" is advice; git is what enforces it. The default lands in the app
+      // root, so an adopter following the happy path gets an untracked, unignored artifact
+      // sitting next to their source with only a log line between it and a `git add .`.
+      if (!isGitIgnored(out)) {
+        warn(`${out} is NOT gitignored — add it, or the next \`git add .\` commits the plan: echo '${out}' >> .gitignore`);
+      }
     }
   } finally {
     await end?.();

package/src/cli/edge-plan.ts

@@ -30,7 +30,7 @@ import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
 import { compileTableContract } from './authz-compile.js';
-import { classifyGeneratedStatements, classifyDestructive, renderStatementHistogram } from './state-apply.js';
+import { classifyGeneratedStatements, classifyDestructive, partitionStatements, renderStatementHistogram } from './state-apply.js';
 import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
 import { compileTableRenames, compileTableMoves } from './schema-compile.js';
@@ -39,7 +39,8 @@ export const PLAN_VERSION = 2;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
-  /** Executable statements that lose no data. */
+  /** Statements that positively ADD. Counted from a matcher, never `total - destructive` —
+   *  computing it by subtraction made "safe" the default for anything unrecognized. */
   additive: number;
   /** `DROP TABLE/COLUMN/TYPE` — the data is gone. */
   drops: number;
@@ -48,6 +49,12 @@ export interface PlanClassification {
   /** REVOKEs against a grantee no model declares — nothing re-derives that access.
    *  Optional: a plan minted before this classification existed has no field for it. */
   strips?: number;
+  /** `DROP POLICY` / `REVOKE` / `DISABLE RLS` — authorization removed, no row lost. Not
+   *  destructive (it re-declares from the models) and emphatically not additive. */
+  authzRemovals?: number;
+  /** Statements the classifier does not recognize. Never additive — a plan carrying these
+   *  has not been fully described and a human should read them before it is applied. */
+  unclassified?: number;
 }
 
 export interface EdgePlan {
@@ -177,7 +184,7 @@ export function mintEdgePlan(
     for (const g of Object.keys(t.grants)) declaredGrantees.add(g);
     for (const g of Object.keys(t.columnGrants ?? {})) declaredGrantees.add(g);
   }
-  const breakdown = classifyDestructive(classified.executable, { declaredGrantees });
+  const breakdown = partitionStatements(classified.executable, { declaredGrantees });
   const destructive = breakdown.drops.length + breakdown.narrowings.length + breakdown.strips.length;
 
   return {
@@ -189,10 +196,14 @@ export function mintEdgePlan(
     executable: classified.executable.length,
     destructive,
     classification: {
-      additive: classified.executable.length - destructive,
+      // Counted, never inferred by subtraction — see partitionStatements. A statement nobody
+      // recognized is `unclassified`, and it must never be able to present as additive.
+      additive: breakdown.additive.length,
       drops: breakdown.drops.length,
       narrowings: breakdown.narrowings.length,
       ...(breakdown.strips.length > 0 ? { strips: breakdown.strips.length } : {}),
+      ...(breakdown.authzRemovals.length > 0 ? { authzRemovals: breakdown.authzRemovals.length } : {}),
+      ...(breakdown.unclassified.length > 0 ? { unclassified: breakdown.unclassified.length } : {}),
     },
     notices: classified.notices.length,
     unmodeled: unmodeledTables(models, snapshot),
@@ -201,6 +212,35 @@ export function mintEdgePlan(
   };
 }
 
+/**
+ * Tables this plan leaves with no SELECT-admitting policy — the "goes dark" set.
+ *
+ * A `DROP POLICY` is cheap to reverse and loses no row, which is why it is not gated. But when
+ * a plan drops every policy that admitted a read and creates none in its place, RLS is still
+ * enabled and the grant is still there, so the table returns ZERO rows to that role. On a real
+ * adoption plan that was 11 tables, including the users table, and it printed no notice at all.
+ *
+ * Deliberately conservative: it only names a table when the plan drops a read-admitting policy
+ * and adds none back for that table. It cannot know what other policies exist live, so it
+ * under-reports rather than crying wolf.
+ */
+export function tablesLeftWithoutARead(statements: readonly string[]): string[] {
+  const dropped = new Map<string, number>();
+  const created = new Set<string>();
+  for (const statement of statements) {
+    const head = (statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '').trim();
+    let m = /^DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?\S+\s+ON\s+(\S+?);?$/i.exec(head);
+    if (m) {
+      dropped.set(m[1], (dropped.get(m[1]) ?? 0) + 1);
+      continue;
+    }
+    m = /^CREATE\s+POLICY\s+\S+\s+ON\s+(\S+)/i.exec(head);
+    // Only a SELECT-admitting policy restores a read; an INSERT-only policy does not.
+    if (m && /\bFOR\s+(SELECT|ALL)\b/i.test(head)) created.add(m[1]);
+  }
+  return [...dropped.keys()].filter((t) => !created.has(t)).sort();
+}
+
 /** The plan's content address — recorded as `plan_ref` on the schema_log row. */
 export function planHash(plan: EdgePlan): string {
   return createHash('sha256').update(stableStringify(plan)).digest('hex');
@@ -243,6 +283,24 @@ export function buildPlanSummary(plan: EdgePlan): string[] {
       lines.push(`!   ${ddl.trim()}`);
     }
   }
+  // Authorization removed loses no row, so it is not gated — but it decides who can SEE the
+  // rows, and a plan that drops a table's only read policy leaves that table returning nothing.
+  // 11 tables went dark in a real adoption plan that printed "0 notice(s)".
+  const { authzRemovals, unclassified } = partitionStatements(classifyGeneratedStatements(plan.statements).executable);
+  const dark = tablesLeftWithoutARead(plan.statements);
+  if (authzRemovals.length > 0) {
+    lines.push(`! ${authzRemovals.length} statement(s) REMOVE authorization (policies, grants, RLS). No data is lost; who can read it changes.`);
+    if (dark.length > 0) {
+      lines.push(`!   ${dark.length} table(s) end this plan with NO read policy and RLS still on — they will return zero rows: ${dark.join(', ')}`);
+    }
+  }
+  if (unclassified.length > 0) {
+    lines.push(`! ${unclassified.length} statement(s) could NOT be classified — read them before applying. They are not counted as additive:`);
+    for (const statement of unclassified) {
+      const ddl = statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? statement;
+      lines.push(`!   ${ddl.trim()}`);
+    }
+  }
   if (plan.unmodeled.length > 0) {
     lines.push(`· ${plan.unmodeled.length} unmodeled table(s) ride through untouched: ${plan.unmodeled.join(', ')}`);
   }

package/src/cli/model-render.ts

@@ -88,40 +88,74 @@ export interface RenderOptions {
  * dominant brownfield shape (public reference data, admin-managed). Anything else is a
  * per-model edit — the decision belongs in the file, not in a flag grammar.
  */
-export const ABILITY_PRESETS: Record<string, string> = {
-  'public-read': `abilities: [can('read'), can('manage', { role: 'admin' })],`,
+export const ABILITY_PRESETS: Record<string, string[]> = {
+  'public-read': [`can('read')`, `can('manage', { role: 'admin' })`],
 };
 
 /**
- * The scaffold stanza for one model: the commented decision surface (guide text says the
- * same thing the db:check gate failure says — one voice, two doorways), or a preset
- * stamped uncommented. An unknown preset throws — grants are authored, never guessed.
+ * A rendered ability that is a PUBLIC read — anon-visible, the only shape the soft-delete
+ * guard ever applied to. Matches `defineModel`'s own rule: action `read`, with no `role`,
+ * `owner`, or `via` narrowing it. Tested per-ability (never against the whole joined stanza)
+ * so one ability's `role:` can never mask another's public read.
  */
-function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>): string {
+function isPublicReadAbility(expr: string): boolean {
+  return /^can\('read'/.test(expr.trim()) && !/\b(role|owner|via)\s*:/.test(expr);
+}
+
+/**
+ * The scaffold stanza for one model, plus whether it declares a public read — the renderer
+ * needs the second fact to decide the `softDelete` line, and it must come from the STRUCTURED
+ * abilities, not a regex over the joined text (a live predicate can span lines and carry its
+ * own braces). An unknown preset throws — grants are authored, never guessed.
+ */
+function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>): { text: string; publicRead: boolean } {
   if (mode === 'live') {
     const contract = table && liveAuthz?.get(table.table);
     if (!contract) {
-      return [
-        '  // no live authorization found for this table — nothing was granted, so nothing is',
-        '  // rendered. Author the read model deliberately, or leave it internal:',
-        '  // private: true,',
-      ].join('\n');
+      return {
+        text: [
+          '  // no live authorization found for this table — nothing was granted, so nothing is',
+          '  // rendered. Author the read model deliberately, or leave it internal:',
+          '  // private: true,',
+        ].join('\n'),
+        publicRead: false,
+      };
     }
-    return renderDerivedAbilities(deriveAbilities(contract));
+    const derived = deriveAbilities(contract);
+    return { text: renderDerivedAbilities(derived), publicRead: derived.abilities.some(isPublicReadAbility) };
   }
   if (mode === 'commented') {
-    return [
-      '  // Declare the read model — db:check fails this model until its authz is authored:',
-      `  // abilities: [can('read')],                          // public data`,
-      `  // abilities: [can('read', { owner: '<column>' })],   // rows owned by a user`,
-      '  // private: true,                                     // not part of the data API',
-    ].join('\n');
+    return {
+      text: [
+        '  // Declare the read model — db:check fails this model until its authz is authored:',
+        `  // abilities: [can('read')],                          // public data`,
+        `  // abilities: [can('read', { owner: '<column>' })],   // rows owned by a user`,
+        '  // private: true,                                     // not part of the data API',
+      ].join('\n'),
+      // Nothing is stamped uncommented, so the model declares no read at all yet.
+      publicRead: false,
+    };
   }
   const preset = ABILITY_PRESETS[mode];
   if (!preset) {
     throw new Error(`Unknown --abilities preset '${mode}' — known: ${Object.keys(ABILITY_PRESETS).join(', ')} (or omit the flag for the commented scaffold).`);
   }
-  return `  ${preset}`;
+  return { text: `  abilities: [${preset.join(', ')}],`, publicRead: preset.some(isPublicReadAbility) };
+}
+
+/**
+ * The `softDelete` line, when the model would otherwise fail to define.
+ *
+ * `defineModel` refuses to guess for a table that has `deleted_at` AND a public read: the
+ * guard decides what anonymous users can see, and neither default is safe. A pull renders
+ * `false` — LIVE reality is the truth being transcribed, and no live policy carries a guard
+ * nobody wrote. The comment says how to get the other one, so the decision is visible in the
+ * file rather than buried in a compiler convention.
+ */
+function softDeleteStanza(table: TableSchema, publicRead: boolean): string {
+  const hasColumn = table.columns.some((c) => c.name === 'deleted_at');
+  if (!hasColumn || !publicRead) return '';
+  return `  softDelete: false, // live reality: no policy filters deleted_at. true excludes soft-deleted rows from public reads.\n`;
 }
 
 /** `format_type` → the `field.*()` factory that produces it (the non-parameterized types). */
@@ -448,8 +482,9 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // reviewer must resolve about a model (and where the field-report consumer's codemod
   // put it, proving the position is mechanical-edit-friendly).
   const stanza = abilitiesStanza(abilities, table, liveAuthz);
+  const softDelete = softDeleteStanza(table, stanza.publicRead);
 
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza}\n  fields: {\n${fields}\n  },${constraints}\n});`;
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */

package/src/cli/schema-compile.ts

@@ -223,12 +223,35 @@ function defaultExpr(spec: FieldSpec): string | null {
 }
 
 /**
- * A Postgres array literal for a default — `[]` → `'{}'`, `['a','b']` → `'{"a","b"}'`.
+ * True when PostgreSQL's own `array_out` would quote this element: it is empty, it is the
+ * literal `NULL` (which unquoted means the SQL null), or it contains a delimiter, a brace, a
+ * quote, a backslash, or whitespace.
+ */
+function needsArrayQuote(v: string): boolean {
+  return v === '' || /^NULL$/i.test(v) || /[{},"\\\s]/.test(v);
+}
+
+/**
+ * A Postgres array literal for a default — `[]` → `'{}'`, `['User']` → `'{User}'`,
+ * `['a b']` → `'{"a b"}'`.
+ *
+ * QUOTING MATTERS: this must match `array_out` exactly, because the value round-trips
+ * through the live catalog. Quoting every element unconditionally produced `'{"User"}'`
+ * where PostgreSQL deparses `'{User}'`, so the declared and live defaults never compared
+ * equal and `db:generate` re-emitted the same `SET DEFAULT` on every run, forever.
+ *
+ * Backslashes escape before quotes, or `\` would become `\\"` — the escaping bug the
+ * previous version also carried (it escaped `"` and left `\` alone).
+ *
  * The introspected form carries a `::type[]` cast (`'{}'::text[]`) that `normalizeDefault`
  * strips, so the bare literal round-trips.
  */
 function arrayLiteral(arr: unknown[]): string {
-  const elems = arr.map((v) => (typeof v === 'string' ? `"${v.replace(/"/g, '\\"')}"` : String(v)));
+  const elems = arr.map((v) => {
+    if (typeof v !== 'string') return String(v);
+    if (!needsArrayQuote(v)) return v;
+    return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  });
   return `'{${elems.join(',')}}'`;
 }
 

package/src/cli/schema-diff.ts

@@ -220,6 +220,20 @@ function argsWiden(from: number[], to: number[]): boolean {
   return to.every((v, i) => from[i] == null || v >= from[i]);
 }
 
+/**
+ * Types whose entire meaning survives a trip through `text` — scalars and strings whose
+ * printed form IS their value. Everything else (postgis geometry, tsvector, hstore, ltree,
+ * arrays, composites, ranges, and any extension type) carries structure the cast discards,
+ * so it is deliberately NOT listed: the default for an unknown base is "not free".
+ */
+const TEXT_ROUND_TRIPS = new Set([
+  'text', 'character varying', 'character', 'citext', 'name', 'uuid', 'boolean',
+  'smallint', 'integer', 'bigint', 'numeric', 'decimal', 'real', 'double precision',
+  'date', 'time', 'time without time zone', 'time with time zone',
+  'timestamp', 'timestamp without time zone', 'timestamp with time zone',
+  'json', 'jsonb', 'inet', 'cidr', 'macaddr', 'bytea', 'interval',
+]);
+
 /**
  * Classify a column type change. Conservative by construction — anything not provably safe
  * or merely lossy falls through to `risky`, so a dangerous conversion is never mistaken for
@@ -230,7 +244,18 @@ export function classifyTypeChange(from: string, to: string): TypeChangeRisk {
   const f = parseType(from);
   const t = parseType(to);
 
-  if (t.base === 'text') return 'safe'; // text is the universal sink: every type assignment-casts to it losslessly
+  // `→ text` is only free from a type text can round-trip. It IS the universal sink for the
+  // printable VALUE — but a structured type loses its meaning, not its characters: postgis
+  // `geometry` → text takes every spatial index and `ST_*` call with it, `tsvector` → text
+  // kills the full-text index, `hstore` → text destroys the key/value structure. None of that
+  // is recoverable by casting back.
+  //
+  // This mattered far past taxonomy. A `safe` verdict emits a BARE `SET DATA TYPE` with no
+  // WARNING, and the plan classifier only counts a narrowing when it sees the `USING` cast a
+  // non-safe verdict adds — so 48 postgis/tsvector/hstore/`timestamp(6)` rewrites in a real
+  // adoption plan were reported as additive with `destructive: 0`, which is also the number
+  // that gates `--confirm` + snapshot. Calling these lossy is what arms the gate.
+  if (t.base === 'text') return TEXT_ROUND_TRIPS.has(f.base) ? 'safe' : 'lossy';
 
   const fr = NUMERIC_RANK[f.base];
   const tr = NUMERIC_RANK[t.base];

package/src/cli/state-apply.ts

@@ -89,6 +89,94 @@ export interface DestructiveBreakdown {
   strips: string[];
 }
 
+/**
+ * Statements that positively ADD — the only ones a plan may call additive.
+ *
+ * `additive` used to be computed as `executable.length - destructive`, which made it the
+ * DEFAULT rather than a finding: any statement the classifier did not recognize was reported
+ * as safe. A real adoption plan carrying 38 DROP POLICY, 43 REVOKE and 48 column rewrites
+ * described itself as `additive: 158, destructive: 0`, and since `destructive > 0` is what
+ * gates `--confirm` + snapshot + the approver set, the false zero did not merely mislabel the
+ * plan — it disarmed the gate.
+ *
+ * So the default is inverted. A statement is additive only when it matches one of these; a
+ * statement nobody recognized is `unclassified`, and `unclassified` is never additive. This is
+ * the same rule the reconciler already applies to grants: absence of knowledge means LEAVE IT
+ * ALONE and say so, never "assume it is fine".
+ */
+const ADDITIVE_MATCHERS: RegExp[] = [
+  /^CREATE\s+(TABLE|POLICY|INDEX|UNIQUE\s+INDEX|SEQUENCE|EXTENSION|TYPE|SCHEMA)\b/,
+  /^GRANT\b/,
+  /^COMMENT\s+ON\b/,
+  /^ALTER\s+TABLE\s+[\s\S]+?\sADD\s+(COLUMN|CONSTRAINT|PRIMARY\s+KEY)\b/,
+  // Enabling/forcing RLS only ever RESTRICTS; it cannot widen access or lose a row.
+  /^ALTER\s+TABLE\s+[\s\S]+?\s(ENABLE|FORCE)\s+ROW\s+LEVEL\s+SECURITY\b/,
+  // Relaxing nullability and setting a default add capability; they remove nothing.
+  /^ALTER\s+TABLE\s+[\s\S]+?\sALTER\s+COLUMN\s+[\s\S]+?\sDROP\s+NOT\s+NULL\b/,
+  /^ALTER\s+TABLE\s+[\s\S]+?\sALTER\s+COLUMN\s+[\s\S]+?\sSET\s+DEFAULT\b/,
+];
+
+/**
+ * Statements that REMOVE an authorization without losing a row.
+ *
+ * Deliberately NOT folded into `destructive`, which means data loss and whose taxonomy is
+ * defended above — a dropped policy or grant re-declares from the models without touching a
+ * row. But it is emphatically not ADDITIVE either, and that was the lie: a `DROP POLICY` that
+ * removes a table's only read policy leaves the table returning zero rows, which is the single
+ * highest-consequence thing an adoption plan can carry and it was reported as an addition.
+ */
+const AUTHZ_REMOVAL_MATCHERS: RegExp[] = [
+  /^DROP\s+POLICY\b/,
+  /^REVOKE\b/,
+  /^ALTER\s+TABLE\s+[\s\S]+?\s(DISABLE|NO\s+FORCE)\s+ROW\s+LEVEL\s+SECURITY\b/,
+];
+
+/** The full partition of an executable stream. Every statement lands in exactly one bucket. */
+export interface StatementPartition {
+  additive: string[];
+  drops: string[];
+  narrowings: string[];
+  strips: string[];
+  /** Authorization removed, no data lost — visible, never additive. */
+  authzRemovals: string[];
+  /** Not positively recognized. NEVER additive; needs a human before this plan is applied. */
+  unclassified: string[];
+}
+
+/** The first non-comment line, upper-cased — WARNING prologues must not hide the verb. */
+function statementHead(statement: string): string {
+  return (statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '')
+    .trim()
+    .toUpperCase();
+}
+
+/**
+ * Partition an executable stream into exactly one bucket per statement.
+ *
+ * Order matters: the data-loss buckets are consulted FIRST so a statement that both drops and
+ * revokes is counted at its most severe reading, and `unclassified` is the fallthrough rather
+ * than `additive`.
+ */
+export function partitionStatements(
+  executable: string[],
+  opts: { declaredGrantees?: ReadonlySet<string> } = {},
+): StatementPartition {
+  const { drops, narrowings, strips } = classifyDestructive(executable, opts);
+  const destructive = new Set([...drops, ...narrowings, ...strips]);
+  const additive: string[] = [];
+  const authzRemovals: string[] = [];
+  const unclassified: string[] = [];
+
+  for (const statement of executable) {
+    if (destructive.has(statement)) continue;
+    const head = statementHead(statement);
+    if (AUTHZ_REMOVAL_MATCHERS.some((re) => re.test(head))) authzRemovals.push(statement);
+    else if (ADDITIVE_MATCHERS.some((re) => re.test(head))) additive.push(statement);
+    else unclassified.push(statement);
+  }
+  return { additive, drops, narrowings, strips, authzRemovals, unclassified };
+}
+
 /** `REVOKE … ON <table> FROM <grantee>;` → the grantee, or null when it is not a revoke. */
 export function revokeTarget(statement: string): string | null {
   // A quoted identifier can hold anything (`"Odd-Role"`, a reserved word, mixed case), and