@everystack/cli 0.4.40 → 0.4.43

package/src/cli/edge-plan.ts

@@ -29,21 +29,32 @@ import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
-import { classifyGeneratedStatements, classifyDestructive, renderStatementHistogram } from './state-apply.js';
+import { compileTableContract } from './authz-compile.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';
 
 export const PLAN_VERSION = 2;
 
-/** Classification counts (brick 9, decision 11): destructive = drops + narrowings. */
+/** 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;
   /** Lossy/risky `ALTER COLUMN … TYPE` — data loss wearing an ALTER. */
   narrowings: number;
+  /** 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 {
@@ -72,6 +83,12 @@ export interface MintOptions {
   allowDrops?: boolean;
   gitRef?: string | null;
   actor?: string | null;
+  /**
+   * Roles the modules declare as governed beyond the ones the models name. A live grantee
+   * outside the governed set is left untouched rather than revoked — without this the
+   * MINTED PLAN carries those revokes, which is where they would actually be applied.
+   */
+  governedRoles?: string[];
 }
 
 /**
@@ -145,6 +162,7 @@ export function mintEdgePlan(
     schema: opts.schema,
     allowDrops: opts.allowDrops,
     liveAuthz: contract,
+    governedRoles: opts.governedRoles,
   });
   const classified = classifyGeneratedStatements(statements);
   if (classified.heldDrops.length > 0) {
@@ -158,8 +176,16 @@ export function mintEdgePlan(
   // (the authz phase is data-safe by construction); dropping a table,
   // column, or type is not — and neither is a narrowing type change, which
   // is data loss wearing an ALTER.
-  const breakdown = classifyDestructive(classified.executable);
-  const destructive = breakdown.drops.length + breakdown.narrowings.length;
+  // The grantees the models actually declare — the discriminator for a STRIP (a revoke
+  // against a role no model grants to has nothing to restore it from, so it carries the
+  // same ceremony as a dropped column).
+  const declaredGrantees = new Set<string>();
+  for (const t of models.map((m) => compileTableContract(m, { schema: opts.schema }))) {
+    for (const g of Object.keys(t.grants)) declaredGrantees.add(g);
+    for (const g of Object.keys(t.columnGrants ?? {})) declaredGrantees.add(g);
+  }
+  const breakdown = partitionStatements(classified.executable, { declaredGrantees });
+  const destructive = breakdown.drops.length + breakdown.narrowings.length + breakdown.strips.length;
 
   return {
     v: PLAN_VERSION,
@@ -170,9 +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),
@@ -181,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');
@@ -223,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/migration-generate.ts

@@ -20,7 +20,7 @@ import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { compileTableSchema, compileRenames, compileTableRenames, compileTableMoves, compileCreateTable, compileEnums, compileSequences } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
-import { emitReconcileSql } from './authz-reconcile.js';
+import { emitReconcileSql, governedRoleSet } from './authz-reconcile.js';
 import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
 
 export interface GenerateOptions {
@@ -44,6 +44,13 @@ export interface GenerateOptions {
    * removed table/enum becomes a drop (still held by the `allowDrops` gate).
    */
   scope?: 'declared' | 'full';
+  /**
+   * Roles the modules declare as governed BEYOND the ones the models name
+   * (`moduleGovernedRoles`). A live grantee outside the governed set is left untouched
+   * rather than revoked — see authz-reconcile's `governedRoleSet`. Widen-only: this can
+   * never stop a model-named role being governed.
+   */
+  governedRoles?: string[];
   /**
    * The live authorization contract (`introspectContract`). When provided, the migration
    * carries the authz layer too — the Models' `abilities` compiled to RLS/policies/grants,
@@ -208,8 +215,11 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
       }
     : opts.liveAuthz;
   const desiredContracts = models.map((m) => compileTableContract(m, { schema }));
+  const desiredAuthz: AuthzContract = { tables: desiredContracts, functions: [] };
   const authzPhase = liveAuthzRenamed
-    ? emitReconcileSql({ tables: desiredContracts, functions: [] }, liveAuthzRenamed)
+    ? emitReconcileSql(desiredAuthz, liveAuthzRenamed, {
+        governedRoles: governedRoleSet(desiredAuthz, opts.governedRoles ?? []),
+      })
     : [];
 
   // 0a-bis (the diff analog of compileMigration's). A role cannot reach a table in a

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

@@ -71,22 +71,147 @@ export function classifyGeneratedStatements(statements: string[]): ClassifiedSta
  *
  * Recoverable metadata is never destructive: policies, grants, constraints,
  * defaults, nullability all re-declare from the models without touching a row.
+ *
+ *   strips     — the ONE exception to that rule. A REVOKE against a grantee NO model
+ *                declares is not recoverable from the models: there is no declaration to
+ *                re-derive it from, and the role simply loses its access. This is the
+ *                deliberate case left over once ungoverned grantees stopped being revoked
+ *                by accident (authz-reconcile's governedRoleSet) — someone put a role in
+ *                `governedRoles` and then granted it nothing, which reads as "strip it".
+ *                Deliberate removal deserves the same ceremony as a dropped column.
+ *                Framework roles (anon/authenticated/admin/PUBLIC) are excluded: revoking
+ *                from those is ordinary authz churn and re-declaring an ability restores it.
  */
 export interface DestructiveBreakdown {
   drops: string[];
   narrowings: string[];
+  /** REVOKEs that leave an undeclared grantee with nothing to restore it from. */
+  strips: string[];
 }
 
-export function classifyDestructive(executable: string[]): DestructiveBreakdown {
+/**
+ * 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
+  // reading one as null would silently UNDER-classify a strip — the failure direction that
+  // matters, since it skips the ceremony rather than adding one.
+  const m = /^REVOKE\s+[\s\S]+?\sFROM\s+("[^"]*"|[A-Za-z_][A-Za-z0-9_$]*)\s*;?\s*$/i.exec(statement.trim());
+  return m ? m[1].replace(/^"|"$/g, '') : null;
+}
+
+export function classifyDestructive(
+  executable: string[],
+  opts: { declaredGrantees?: ReadonlySet<string> } = {},
+): DestructiveBreakdown {
   const drops: string[] = [];
   const narrowings: string[] = [];
+  const strips: string[] = [];
   for (const statement of executable) {
     if (/\bDROP\s+(TABLE|COLUMN|TYPE)\b/.test(statement)) drops.push(statement);
     else if (/\bSET DATA TYPE\b/.test(statement) && /\bUSING\b/.test(statement)) narrowings.push(statement);
+    else if (opts.declaredGrantees) {
+      // Only classified when the caller supplied the declared side — without it there is
+      // no way to tell a strip from ordinary churn, and guessing would newly force
+      // --confirm on plans that never needed it.
+      const grantee = revokeTarget(statement);
+      if (grantee && !opts.declaredGrantees.has(grantee) && !FRAMEWORK_ROLES.has(grantee.toUpperCase())) {
+        strips.push(statement);
+      }
+    }
   }
-  return { drops, narrowings };
+  return { drops, narrowings, strips };
 }
 
+/** Roles the framework itself owns — revoking from these re-declares from an ability. */
+const FRAMEWORK_ROLES = new Set(['PUBLIC', 'ANON', 'AUTHENTICATED', 'ADMIN']);
+
 /**
  * The kind histogram — what a plan IS, before anyone reads its SQL. A real edge can
  * run to four digits of statements (a consumer's adoption edge was 1,671), and the