@everystack/cli 0.4.41 → 0.4.44

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/commands/db-pull.ts

@@ -83,6 +83,24 @@ export function keyCandidates(row: Record<string, unknown>, cols: string[]): str
   return cols.filter((_, i) => Number(row[`c${i}`]) === n && Number(row[`d${i}`]) === n);
 }
 
+/**
+ * The specifier the generated `index.ts` uses to import the `--derived-out` file.
+ *
+ * Both paths are resolved against CWD first, so this works whichever way either was written
+ * (`db/models` + `db/models/derived.ts`, or absolute, or `./db/models/`). Extension stripped
+ * (the barrel's own imports are extensionless), separators normalized for Windows, and a
+ * same-directory result gets the explicit `./` a bare `derived` would lack.
+ *
+ * `--out` may also name a single `.ts` file, in which case the barrel IS that file and the
+ * specifier is relative to its directory.
+ */
+export function derivedImportSpecifier(out: string, derivedOut: string): string {
+  const barrelDir = out.endsWith('.ts') ? path.dirname(path.resolve(out)) : path.resolve(out);
+  const target = path.resolve(derivedOut).replace(/\.ts$/, '');
+  const rel = path.relative(barrelDir, target).split(path.sep).join('/');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
 /** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
 function lambdaRunner(region: string, fn: string): QueryRunner {
   return async (sql: string) => {
@@ -269,15 +287,26 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       process.exit(0);
     }
   }
-  // With --derived-out, the embedded copy would duplicate every descriptor — the
-  // models output carries models only.
+  // With --derived-out, the embedded copy would duplicate every descriptor — the models
+  // output carries models only, and the barrel IMPORTS the layer from its own file. It used
+  // to carry neither, so the same command that wrote 120 descriptors emitted a
+  // `defineModule({ models })` that excluded every one of them, and db:plan then compared
+  // against a fraction of the database while printing a confident statement count.
   const embeddedDerived = derivedOut ? undefined : derived;
+  const externalDerived = derivedOut && flags.out
+    ? {
+      specifier: derivedImportSpecifier(flags.out, derivedOut),
+      sequences: derived.sequenceNames.length > 0,
+      materializedTables: derived.materializedTableNames.length > 0,
+      derived: derived.names.length > 0,
+    }
+    : undefined;
 
   let source: string;
   if (flags.out && !flags.out.endsWith('.ts')) {
     // A directory: one file per model + index.ts — the default shape for a real app.
     const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
+    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived, externalDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));

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

@@ -81,6 +81,10 @@ export interface RenderOptions {
   /** The rendered derived layer (B5) — rides the barrel: block after the models,
    *  sequences/derived arrays on the module wrapper, symbols on the import header. */
   derived?: DerivedRenderResult;
+  /** The `--derived-out` case: the layer lives in its own file, so the barrel imports and
+   *  wires it instead of embedding it. Mutually exclusive with `derived` in practice —
+   *  passing neither is what silently produced `defineModule({ models })`. */
+  externalDerived?: ExternalDerived;
 }
 
 /**
@@ -88,40 +92,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 +486,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. */
@@ -470,22 +509,42 @@ function importHeader(body: string, extra: string[] = []): string {
   return imports.join('\n');
 }
 
-/** The barrel's module wrapper: models always; sequences/derived when the pull found any (B5). */
-function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multiline = false): string {
+/**
+ * The barrel's module wrapper: models always; sequences/derived when the pull found any (B5).
+ *
+ * `external` is the `--derived-out` case — the descriptors live in their own file, so the
+ * barrel IMPORTS the arrays rather than re-declaring them. Before this the barrel simply
+ * omitted them, which meant the same pull that wrote 120 descriptors emitted a
+ * `defineModule({ models })` that excluded every one, and `db:plan` then compared against a
+ * fraction of the database while reporting a confident statement count. A plan scoped to
+ * something narrower than the reader assumes is the same false-completeness failure as a
+ * classification that defaults to safe.
+ */
+function moduleFooter(
+  modelNames: string[],
+  derived?: DerivedRenderResult,
+  multiline = false,
+  external?: ExternalDerived,
+): string {
   // A materialized table (--matviews-as-tables) is a MODEL — its block rides the derived
   // render (topo-ordered with the objects around it) but its name belongs in `models`.
-  const allModels = [...modelNames, ...(derived?.materializedTableNames ?? [])];
-  const models = multiline
-    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n];`
-    : `export const models = [${allModels.join(', ')}];`;
-  const parts = [models];
+  const hasMaterialized = external ? external.materializedTables : Boolean(derived?.materializedTableNames.length);
+  const inlineNames = external ? [] : (derived?.materializedTableNames ?? []);
+  const allModels = [...modelNames, ...inlineNames];
+  const rendered = multiline
+    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n${external && hasMaterialized ? '  ...materializedTables,\n' : ''}];`
+    : `export const models = [${[...allModels, ...(external && hasMaterialized ? ['...materializedTables'] : [])].join(', ')}];`;
+  const parts = [rendered];
   const keys = ['models'];
-  if (derived?.sequenceNames.length) {
-    parts.push(`export const sequences = [${derived.sequenceNames.join(', ')}];`);
+
+  const hasSequences = external ? external.sequences : Boolean(derived?.sequenceNames.length);
+  const hasDerived = external ? external.derived : Boolean(derived?.names.length);
+  if (hasSequences) {
+    if (!external) parts.push(`export const sequences = [${derived!.sequenceNames.join(', ')}];`);
     keys.push('sequences');
   }
-  if (derived?.names.length) {
-    parts.push(`export const derived = [${derived.names.join(', ')}];`);
+  if (hasDerived) {
+    if (!external) parts.push(`export const derived = [${derived!.names.join(', ')}];`);
     keys.push('derived');
   }
   parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
@@ -493,6 +552,24 @@ function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multi
   return parts.join('\n\n');
 }
 
+/** What an external (`--derived-out`) derived file exports, so the barrel can wire it. */
+export interface ExternalDerived {
+  /** Import specifier as written in the barrel, e.g. `'./derived'`. */
+  specifier: string;
+  sequences: boolean;
+  materializedTables: boolean;
+  derived: boolean;
+}
+
+/** The named exports to pull out of an external derived file, in a stable order. */
+function externalDerivedNames(e: ExternalDerived): string[] {
+  const names: string[] = [];
+  if (e.derived) names.push('derived');
+  if (e.materializedTables) names.push('materializedTables');
+  if (e.sequences) names.push('sequences');
+  return names;
+}
+
 /**
  * Render a whole snapshot as a single Models module: the import, one block per table (scoped
  * to `opts.schema`), and the `models` array the rest of the framework consumes. The tables
@@ -575,14 +652,21 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   // their own model.
   const names = tables.map((t) => modelVarName(t.table));
   const modelSymbols = ['defineModule', ...(opts.derived?.imports ?? [])];
+  const ext = opts.externalDerived;
+  const extNames = ext ? externalDerivedNames(ext) : [];
   const index = [
     [
       `import { ${modelSymbols.join(', ')} } from '@everystack/model';`,
+      // The --derived-out layer, imported rather than re-declared — the barrel must WIRE it
+      // or db:plan silently compares against models only.
+      ...(extNames.length ? [`import { ${extNames.join(', ')} } from '${ext!.specifier}';`] : []),
       ...names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`),
     ].join('\n'),
     `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
+    // Re-exported so the barrel remains the one place that describes the database.
+    ...(extNames.length ? [`export { ${extNames.join(', ')} };`] : []),
     ...(opts.derived?.block ? [opts.derived.block] : []),
-    moduleFooter(names, opts.derived, true),
+    moduleFooter(names, opts.derived, true, ext),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });
 

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(',')}}'`;
 }