@everystack/cli 0.4.44 → 0.4.45

package/src/cli/authz-ownership.ts

@@ -0,0 +1,193 @@
+/**
+ * Table OWNERSHIP — reported, never compared.
+ *
+ * A table's owner bypasses its own RLS policies unless the table is FORCEd. So the
+ * pair (owner, FORCE) decides whether the policies this repo argues about are actually
+ * in force for the principal that writes. Neither half is visible in the contract:
+ * `GRANTS_SQL` deliberately EXCLUDES the owner's self-grant because the owner is
+ * environment-specific (the dev user locally, the master/operator role when deployed),
+ * and committing it would make the contract non-portable and drift on every stage.
+ *
+ * That exclusion is right, and it is exactly why this module exists. The owner is a
+ * fact about the DEPLOYED database that no committed artifact can carry, so the only
+ * honest treatment is to NAME it on every surface that can see a live database, and
+ * let the human read it. Locally it is the dev user and nothing fires; on the stage it
+ * is somebody else, and that difference is the whole point.
+ *
+ * **The owner is NOT part of the contract.** It does not enter `TableContract`, it does
+ * not enter `canonicalAuthz`, and it therefore does not touch the fingerprint. Putting
+ * an environment-specific field into the content address would make the same declared
+ * state hash differently per stage — and adding any field to the canonical form is a
+ * FORMAT BUMP, which this does not need: it needs to be reported, not equated.
+ *
+ * Search_path: this query deparses nothing (`pg_get_expr` is not involved) — it reads
+ * catalog names directly — so it needs no canonical-path pinning to be stable.
+ */
+
+import type { WrittenBy, ModelDescriptor } from '@everystack/model';
+import { IGNORED_SCHEMAS, type QueryRunner, type AuthzContract } from './authz-contract.js';
+
+/**
+ * Every base table with its owner. The exclusions are RLS_SQL's, verbatim — base
+ * relations only, no `pg_catalog` / `information_schema` / `pg_%`, no extension-owned
+ * objects — so the two queries agree about which tables exist and the report can be
+ * joined onto the contract without either side inventing a table the other cannot see.
+ */
+export const TABLE_OWNERS_SQL = `
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  r.rolname AS owner
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_roles r ON r.oid = c.relowner
+WHERE c.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend d
+    WHERE d.objid = c.oid AND d.deptype = 'e'
+  )
+ORDER BY n.nspname, c.relname;
+`.trim();
+
+export interface TableOwnerRow {
+  schema: string;
+  table: string;
+  owner: unknown;
+}
+
+/** One live table's owner, keyed by the same schema-qualified identity the contract uses. */
+export interface TableOwner {
+  /** Schema-qualified table, e.g. `public.posts`. */
+  table: string;
+  /** The role that owns it. */
+  owner: string;
+}
+
+/**
+ * Fold owner rows into the reportable set. Tooling schemas are dropped here rather than
+ * in SQL, matching `assembleContract` — one definition of "not the app's", applied the
+ * same way on both sides.
+ */
+export function assembleOwners(rows: TableOwnerRow[]): TableOwner[] {
+  return rows
+    .filter((row) => !IGNORED_SCHEMAS.has(row.schema))
+    .map((row) => ({ table: `${row.schema}.${row.table}`, owner: String(row.owner ?? '') }))
+    .sort((a, b) => a.table.localeCompare(b.table));
+}
+
+/** Read the live table owners. Read-only, one query, no canonical-path pinning needed. */
+export async function introspectTableOwners(run: QueryRunner): Promise<TableOwner[]> {
+  return assembleOwners((await run(TABLE_OWNERS_SQL)) as TableOwnerRow[]);
+}
+
+/** One governed table's ownership posture, with the model's own intent beside it. */
+export interface OwnershipRow {
+  /** Schema-qualified table. */
+  table: string;
+  /** The live owner, or null when the ownership query did not return this table. */
+  owner: string | null;
+  /** Live `relforcerowsecurity` — whether the owner is subject to its own policies. */
+  forced: boolean;
+  /** The model's declared write principal, or null when there is no model (db:pull). */
+  writtenBy: WrittenBy | null;
+  /** The owner writes past every policy on this table, and the model did not ask for that. */
+  flagged: boolean;
+}
+
+/**
+ * Build the ownership report for the tables the models govern.
+ *
+ * The flag rule follows the FORCE axiom the compiler already encodes: FORCE iff the
+ * write principal is subject to its own policies.
+ *
+ *   - `writtenBy: 'app'` + FORCE off  -> FLAGGED. The app writes through the owner
+ *     connection past policies the model believes are enforcing. A silent bypass.
+ *   - `writtenBy: 'worker' | 'functions'` + FORCE off -> reported, NOT flagged. These
+ *     write on the owner connection on purpose; a FORCEd table would block them (on RDS
+ *     the owner is not a superuser). Correct, and still named.
+ *   - FORCE on -> reported, not flagged, whatever the principal.
+ *
+ * Without models (`db:pull`, where the models do not exist yet) `writtenBy` is null and
+ * NOTHING is flagged: the intent that would make a bypass wrong has not been declared.
+ * The owner is still named — that half is a live fact the pull genuinely saw.
+ */
+export function buildOwnershipReport(
+  owners: readonly TableOwner[],
+  live: AuthzContract,
+  opts: { models?: readonly ModelDescriptor[]; tables?: readonly string[] } = {},
+): OwnershipRow[] {
+  const ownerByTable = new Map(owners.map((o) => [o.table, o.owner]));
+  const liveByTable = new Map(live.tables.map((t) => [t.table, t]));
+
+  // Governed = the tables the models declare when there are models; else the caller's
+  // explicit subject list (the pull's schema-scoped tables); else every live table.
+  const subjects: { table: string; writtenBy: WrittenBy | null }[] = opts.models
+    ? opts.models.map((m) => ({ table: `${m.schema}.${m.table}`, writtenBy: m.writtenBy }))
+    : (opts.tables ?? live.tables.map((t) => t.table)).map((table) => ({ table, writtenBy: null }));
+
+  const rows: OwnershipRow[] = [];
+  for (const s of subjects) {
+    const l = liveByTable.get(s.table);
+    // A model with no live table is a CREATE — it has no owner yet, and nothing to report.
+    if (!l) continue;
+    const forced = l.rls.forced;
+    rows.push({
+      table: s.table,
+      owner: ownerByTable.get(s.table) ?? null,
+      forced,
+      writtenBy: s.writtenBy,
+      flagged: s.writtenBy === 'app' && !forced,
+    });
+  }
+  return rows.sort((a, b) => a.table.localeCompare(b.table));
+}
+
+/**
+ * Render the report. Grouped by owner, because one operator role usually owns the whole
+ * schema and thirty-three identical lines would bury the findings — the same reason
+ * `db:pull` says "grants exist for X" once instead of repeating it in every model.
+ *
+ * When ONE owner owns everything, that is a single line naming it. When there is more
+ * than one, every owner is named WITH its tables: a split ownership is itself the
+ * anomaly, and a count alone would not say which table changed hands.
+ */
+export function renderOwnershipReport(rows: readonly OwnershipRow[]): string[] {
+  if (rows.length === 0) return [];
+
+  const byOwner = new Map<string, OwnershipRow[]>();
+  for (const r of rows) {
+    const key = r.owner ?? '(not returned by the ownership query)';
+    let group = byOwner.get(key);
+    if (!group) byOwner.set(key, (group = []));
+    group.push(r);
+  }
+  const owners = [...byOwner.keys()].sort();
+
+  const lines = [
+    `Ownership of ${rows.length} governed table(s) — the owner bypasses RLS unless the table is FORCEd:`,
+  ];
+  for (const owner of owners) {
+    const group = byOwner.get(owner)!;
+    const forced = group.filter((r) => r.forced).length;
+    const notForced = group.length - forced;
+    const tail = notForced > 0 ? `, ${notForced} NOT forced` : '';
+    lines.push(`  ${owner} — ${group.length} table(s): ${forced} FORCE on${tail}`);
+    if (owners.length > 1) {
+      for (const r of group) lines.push(`      ${r.table}${r.forced ? '' : ' (not forced)'}`);
+    }
+  }
+
+  const flagged = rows.filter((r) => r.flagged);
+  for (const r of flagged) {
+    lines.push(
+      `  ! ${r.table} — written by the app but NOT FORCEd: owner ${r.owner ?? '(unknown)'} writes past every policy on this table.`,
+    );
+  }
+  const unknown = rows.filter((r) => r.owner === null);
+  for (const r of unknown) {
+    lines.push(`  ? ${r.table} — the ownership query did not return this table; its owner is unknown.`);
+  }
+  return lines;
+}

package/src/cli/authz-reconcile.ts

@@ -17,6 +17,7 @@
 
 import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
 import { effectivePolicyCheck, parenthesizeOnce } from './authz-contract.js';
+import { matchPolicies } from './authz-identity.js';
 import { quoteQualified } from './pg-ident.js';
 
 /**
@@ -135,20 +136,9 @@ 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. 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 ?? '')
-    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
-}
+// Policy equality lives in authz-identity.ts and nowhere else. The copy that used to sit here
+// compared roles as `roles.join(',')`, which made `['a,b']` equal `['a','b']` — a false match
+// on a legal role name. Two implementations of one predicate is how these surfaces drift.
 
 function tableMap(c: AuthzContract): Map<string, TableContract> {
   return new Map(c.tables.map((t) => [t.table, t]));
@@ -229,20 +219,22 @@ function reconcileRls(table: string, d: TableContract, l: TableContract | undefi
   if (!d.rls.forced && l?.rls.forced) out.push(`ALTER TABLE ${table} NO FORCE ROW LEVEL SECURITY;`);
 }
 
+/**
+ * Reconcile policies through the SHARED matcher — the same equivalence the differ and the
+ * fingerprint use, so the three can never contradict each other about one database.
+ *
+ * A live policy carrying the declared authorization under a different name, or covering in one
+ * policy the roles the compiler splits apart, is ADOPTED: it stays exactly as it is and
+ * nothing is emitted. Renaming it would be DDL that buys spelling.
+ *
+ * The matcher requires full field equality, so this can only turn a DROP + CREATE pair into a
+ * no-op — never emit DDL the name-keyed version would not have emitted.
+ */
 function reconcilePolicies(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
-  const dMap = new Map(d.policies.map((p) => [p.name, p]));
-  const lMap = new Map((l?.policies ?? []).map((p) => [p.name, p]));
-
-  // Drops first: policies removed, or changed (dropped then recreated below).
-  for (const [name, lp] of lMap) {
-    const dp = dMap.get(name);
-    if (!dp || !policiesEqual(dp, lp)) out.push(policyDropSql(table, name));
-  }
-  // Creates: policies added, or changed (recreated to the declared form).
-  for (const [name, dp] of dMap) {
-    const lp = lMap.get(name);
-    if (!lp || !policiesEqual(dp, lp)) out.push(policyCreateSql(table, dp));
-  }
+  const m = matchPolicies(d.policies, l?.policies ?? []);
+  // Drops first, so a replaced policy never briefly co-exists with its old form.
+  for (const name of m.toDrop) out.push(policyDropSql(table, name));
+  for (const p of m.toCreate) out.push(policyCreateSql(table, p));
 }
 
 function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {

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

@@ -30,6 +30,8 @@ import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrati
 import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
 import { compileTableContract } from '../authz-compile.js';
 import { governedRoleSet, ungovernedGrants, renderGrantExemptions } from '../authz-reconcile.js';
+import { classifyAdoption, renderAdoptionReport } from '../authz-adoption-class.js';
+import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -151,6 +153,48 @@ function reportGrantExemptions(liveAuthz: AuthzContract | undefined, models: Mod
   info(`Bring them under the reconciler with defineModule({ governedRoles: [...] }), or leave them exempt — either way they are listed here every run.`);
 }
 
+/**
+ * WHY does each authorization statement exist? — printed on every brownfield generate.
+ *
+ * A first plan against an existing database is long, and the length is not the problem: the
+ * problem is that nobody can tell which statements are everystack imposing its own spelling
+ * and which are real differences. `convention` is the count that indicts US, and driving it to
+ * zero is the whole point — so it is named first and never hidden behind a flag.
+ */
+function reportAdoptionClasses(liveAuthz: AuthzContract | undefined, models: ModelDescriptor[]): void {
+  if (!liveAuthz) return; // greenfield — every statement is additive, nothing to adjudicate
+  const declared: AuthzContract = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
+  const { counts } = classifyAdoption(declared, liveAuthz);
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+  if (total === 0) return;
+  info(`${total} authorization statement(s), by why they exist:`);
+  for (const line of renderAdoptionReport(counts)) info(line);
+}
+
+/**
+ * WHO owns each governed table, and is that owner subject to its own RLS? — printed
+ * on every generate that has a live database.
+ *
+ * The owner never appears in the contract or the fingerprint: it is the dev user locally
+ * and the operator role on a stage, so committing it would drift on every environment.
+ * That is precisely why it must be SAID. A deployed owner that differs from the one the
+ * author has in mind is invisible in every artifact, and an unforced table lets that owner
+ * write past every policy in this repo. The report names the owner even when nothing is
+ * wrong, because silence here is what makes the mismatch impossible to notice.
+ */
+function reportOwnership(
+  liveAuthz: AuthzContract | undefined,
+  owners: readonly TableOwner[],
+  models: ModelDescriptor[],
+): void {
+  if (!liveAuthz) return; // greenfield — nothing owns anything yet
+  const rows = buildOwnershipReport(owners, liveAuthz, { models });
+  for (const line of renderOwnershipReport(rows)) {
+    if (line.trimStart().startsWith('!')) warn(line.trim());
+    else info(line);
+  }
+}
+
 async function readJournal(migrationsDir: string): Promise<Journal | null> {
   try {
     return JSON.parse(await fs.readFile(path.join(migrationsDir, 'meta', '_journal.json'), 'utf8'));
@@ -203,6 +247,7 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   let declaredDb: DeclaredDerived | null = null;
   let current;
   let liveAuthz;
+  let liveOwners: TableOwner[] = [];
   let runner!: QueryRunner;
   let end: (() => Promise<void>) | undefined;
   try {
@@ -236,6 +281,9 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     current = await introspectSchema(runner);
     step('Introspecting authorization (rls + grants + policies)...');
     liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+    // Ownership rides the same connection: it is not part of the contract (it never
+    // enters the fingerprint), but it decides whether the contract is actually in force.
+    liveOwners = await introspectTableOwners(runner);
     if (!apply) await end?.();
   } catch (err: any) {
     fail(err.message);
@@ -257,6 +305,8 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
   // ungoverned grantee's privileges alone rather than revoking them; that is only
   // defensible because the artifact says exactly whose access it chose not to govern.
   reportGrantExemptions(liveAuthz, models, declaredDb?.governedRoles ?? []);
+  reportAdoptionClasses(liveAuthz, models);
+  reportOwnership(liveAuthz, liveOwners, models);
   console.log('');
   if (statements.length === 0) {
     success(`db:generate — the live database already matches the models. ${dryRun ? 'Nothing to preview.' : 'No migration written.'}`);

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

@@ -22,6 +22,8 @@ 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 { classifyAdoption, renderAdoptionReport } from '../authz-adoption-class.js';
+import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport } from '../authz-ownership.js';
 import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
@@ -39,7 +41,7 @@ import { governedRoleSet, ungovernedGrants } from '../authz-reconcile.js';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline.js';
 import { compileTableContract } from '../authz-compile.js';
 import { reportPipelineLastRun } from './pipeline-run.js';
-import { step, success, fail, info, warn } from '../output.js';
+import { step, success, fail, info, warn, reserveStdoutForData } from '../output.js';
 
 const DEFAULT_OUT = 'db.plan.json';
 
@@ -61,6 +63,12 @@ function isGitIgnored(file: string): boolean {
 }
 
 export async function dbPlanCommand(flags: Record<string, string>): Promise<void> {
+  const out = flags.out || DEFAULT_OUT;
+  // `--out -` makes stdout the artifact. Declared before anything prints, so the summary,
+  // the adoption report and the ownership report land on stderr and the plan JSON is the
+  // only thing on stdout — otherwise `db:plan --out - | jq` reads a report as its input.
+  if (out === '-') reserveStdoutForData();
+
   let dbSource: DbSource;
   try {
     dbSource = resolveDbSource(flags);
@@ -95,6 +103,9 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     step('Asking the target its fingerprint (introspecting state + authz)...');
     const snapshot = await introspectSchema(runner);
     const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+    // Not part of the plan and not part of either fingerprint — the owner is
+    // environment-specific. It is read here so the REVIEW surface can name it.
+    const owners = await introspectTableOwners(runner);
     // The modules' widened governed-role set. A barrel that exports only `models` has none,
     // which is the greenfield default: govern exactly what the models name.
     let declaredGovernedRoles: string[] = [];
@@ -134,7 +145,6 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
 
-    const out = flags.out || DEFAULT_OUT;
     const body = JSON.stringify(plan, null, 2) + '\n';
     if (out === '-') {
       console.log(body);
@@ -145,6 +155,28 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     for (const line of buildPlanSummary(plan)) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
 
+    // WHY does each authorization statement exist? — the same report db:generate prints,
+    // on the artifact a human actually reviews before applying.
+    //
+    // Re-DERIVED from live every mint, never stored: a recorded claim about what the models
+    // fail to capture goes stale the moment someone closes the gap, and a stale note is worse
+    // than none. `capability` is the count that says "this plan removes something the model
+    // cannot express" — the operator reading this is the last one who can catch it.
+    const adoption = classifyAdoption(declaredAuthz, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) });
+    const adoptionTotal = Object.values(adoption.counts).reduce((a, b) => a + b, 0);
+    if (adoptionTotal > 0) {
+      info(`${adoptionTotal} authorization statement(s), by why they exist:`);
+      for (const line of renderAdoptionReport(adoption.counts)) info(line);
+    }
+
+    // WHO owns the tables this plan authorizes, and does that owner obey the policies it
+    // is about to write? Re-derived live every mint, never stored — the owner is a fact
+    // about THIS target, and the target is the one thing a committed artifact cannot carry.
+    for (const line of renderOwnershipReport(buildOwnershipReport(owners, contract, { models }))) {
+      if (line.trimStart().startsWith('!')) warn(line.trim());
+      else info(line);
+    }
+
     // The fast-forward rule, warn-only at mint time (db:apply enforces it):
     // a stale checkout mints a legal-looking plan whose edge REVERTS merged
     // work — say so on the review surface, where a human still reads it.

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

@@ -34,7 +34,8 @@ import { fingerprintLive } from '../schema-fingerprint.js';
 import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile.js';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
-import { introspectContract, type TableContract } from '../authz-contract.js';
+import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract.js';
+import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
 import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
@@ -150,6 +151,9 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   /** Adoption observation — the foreign grantees present, and what the claim is true OF. */
   let pulledExemptions: GrantExemption[] = [];
   let pulledFingerprint = '';
+  /** Live ownership — reported, never rendered into a model (it is environment-specific). */
+  let liveContract: AuthzContract | undefined;
+  let liveOwners: TableOwner[] = [];
   let derivedCatalog: DerivedCatalog | undefined;
   let matviewColumns: Map<string, ColumnSchema[]> | undefined;
   let candidatesByIdentity: Map<string, string[]> | undefined;
@@ -176,6 +180,11 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     if (abilities === 'live') {
       note('Introspecting live authorization (grants + policies)...');
       const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+      liveContract = contract;
+      // The owner is NOT rendered into the models — it is the dev user here and the
+      // operator role on a stage, so a model that declared it would drift everywhere.
+      // It is read to be SAID, on the one surface that is looking at the database.
+      liveOwners = await introspectTableOwners(runner);
       liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
       detail(`${liveAuthz.size} table(s) carry authorization.`);
       // Roles outside the model vocabulary (anon/authenticated/admin) are usually ONE
@@ -243,6 +252,16 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // WHO owns the tables being pulled. Nothing is FLAGGED here: flagging needs a declared
+  // write principal to contradict, and the models this pull is about to write do not exist
+  // yet. Naming the owner is the half the pull genuinely saw — and the half that vanishes
+  // from every artifact afterwards, because the contract excludes the owner on purpose.
+  if (liveContract) {
+    for (const line of renderOwnershipReport(
+      buildOwnershipReport(liveOwners, liveContract, { tables: pulled.map((t) => t.table) }),
+    )) note(line);
+  }
+
   // The derived layer (B5): rendered from the live catalog with dependsOn from the real
   // edge graph. Everything inexpressible is a stderr warning AND an inline FIXME.
   const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));

package/src/cli/edge-plan.ts

@@ -31,7 +31,7 @@ import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.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 { fingerprintLive, fingerprintState, fingerprintModels, stableStringify, compareStoredFingerprint, formatChangedMessage, FINGERPRINT_VERSION } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
 import { compileTableRenames, compileTableMoves } from './schema-compile.js';
 
@@ -61,6 +61,12 @@ export interface EdgePlan {
   v: number;
   /** The target's exact live fingerprint at mint time — the lock. */
   fromFingerprint: string;
+  /**
+   * The FINGERPRINT_VERSION the endpoints were computed under. Stored beside the hashes so a
+   * plan minted under an older canonical form REFUSES as a format change rather than reporting
+   * drift that no edit could explain. Absent on plans minted before v4.
+   */
+  fpVersion?: number;
   /** The predicted live fingerprint after apply — exact, unmodeled-aware. */
   toFingerprint: string;
   /** The models-only fingerprint — context for the strong claim. Equals `to` when nothing is unmodeled. */
@@ -190,6 +196,7 @@ export function mintEdgePlan(
   return {
     v: PLAN_VERSION,
     fromFingerprint: fingerprintLive(snapshot, contract).hash,
+    fpVersion: FINGERPRINT_VERSION,
     toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema }),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
     statements,
@@ -250,7 +257,12 @@ export type PlanPrecondition = { ok: true } | { ok: false; reason: string };
 
 /** The lock: apply only when the target is exactly where the plan started. */
 export function checkPlanPrecondition(plan: EdgePlan, liveFingerprint: string): PlanPrecondition {
-  if (liveFingerprint === plan.fromFingerprint) return { ok: true };
+  const cmp = compareStoredFingerprint({ hash: plan.fromFingerprint, v: plan.fpVersion }, liveFingerprint);
+  if (cmp.kind === 'match') return { ok: true };
+  // A plan minted under an older canonical form cannot be compared at all. Saying "the state
+  // moved (a concurrent apply or a hand edit)" would send the operator hunting a change that
+  // never happened — plans are ephemeral by design, so the honest answer is re-mint.
+  if (cmp.kind === 'format-changed') return { ok: false, reason: formatChangedMessage(cmp) };
   return {
     ok: false,
     reason:

package/src/cli/index.ts

@@ -45,27 +45,11 @@ import { auditCommand } from './commands/audit.js';
 import { uiAuditCommand } from './commands/ui-audit.js';
 import { runbookCommand } from './commands/runbook.js';
 import { fail } from './output.js';
+import { parseFlags } from './parse-flags.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-function parseFlags(args: string[]): Record<string, string> {
-  const flags: Record<string, string> = {};
-  for (let i = 0; i < args.length; i++) {
-    // Handle both --flag and -flag
-    if (args[i].startsWith('--')) {
-      const key = args[i].slice(2);
-      const value = args[i + 1] && !args[i + 1].startsWith('-') ? args[++i] : 'true';
-      flags[key] = value;
-    } else if (args[i].startsWith('-') && args[i].length > 1) {
-      const key = args[i].slice(1);
-      const value = args[i + 1] && !args[i + 1].startsWith('-') ? args[++i] : 'true';
-      flags[key] = value;
-    }
-  }
-  return flags;
-}
-
 /**
  * Auto-detect HOST_URL from SST outputs.
  * SST writes .sst/outputs.json after every deploy with { routerUrl, apiUrl, ... }.

package/src/cli/model-render.ts

@@ -213,8 +213,25 @@ function bareName(table: string): string {
   return table.replace(/^[^.]+\./, '');
 }
 
-/** Migration infrastructure a pull must never render as a model, whatever schema it landed in. */
-const INFRASTRUCTURE_TABLES = new Set(['__drizzle_migrations']);
+/**
+ * Migration infrastructure a pull must never render as a model, whatever schema it landed in.
+ *
+ * A brownfield pull adopts a database another migration tool still owns, and that tool's
+ * bookkeeping is not the app's data. Rendering it as a model makes everystack GOVERN it: the
+ * compiled contract declares an admin policy, and the adopter's first plan carries a
+ * `CREATE POLICY` on a table nobody asked us to manage. The journal belongs to whoever writes
+ * it — drizzle-kit's `__drizzle_migrations`, Rails' `schema_migrations` +
+ * `ar_internal_metadata`.
+ *
+ * Deliberately a SHORT list of names that are unambiguously a migration tool's own state. It
+ * is not a heuristic and must not become one: a real app table wrongly matched here silently
+ * loses its declared authorization.
+ */
+const INFRASTRUCTURE_TABLES = new Set([
+  '__drizzle_migrations', // drizzle-kit
+  'schema_migrations', // Rails / ActiveRecord
+  'ar_internal_metadata', // Rails / ActiveRecord
+]);
 
 /**
  * The tables a pull renders: the requested schema, minus migration infrastructure.

package/src/cli/output.ts

@@ -11,11 +11,11 @@ export function step(msg: string): void {
 }
 
 export function success(msg: string): void {
-  console.log(`  \u2713 ${msg}`);
+  say(`  \u2713 ${msg}`);
 }
 
 export function warn(msg: string): void {
-  console.log(`  ! ${msg}`);
+  say(`  ! ${msg}`);
 }
 
 export function fail(msg: string): void {
@@ -23,5 +23,27 @@ export function fail(msg: string): void {
 }
 
 export function info(msg: string): void {
-  console.log(`  ${msg}`);
+  say(`  ${msg}`);
+}
+
+/**
+ * When a command makes stdout the DATA channel (`db:plan --out -`), every human-readable
+ * line has to move to stderr \u2014 otherwise the report is interleaved with the artifact and
+ * the stdout form cannot be piped to anything. `step` and `fail` already write to stderr
+ * on that principle; this extends it to the rest, on demand.
+ *
+ * Off by default, so no command's output moves unless it asks. One-way and process-wide:
+ * a CLI process runs exactly one command, and the choice is made once, before it prints.
+ */
+let stdoutReserved = false;
+
+/** Declare stdout the data channel: human-readable output moves to stderr from here on. */
+export function reserveStdoutForData(): void {
+  stdoutReserved = true;
+}
+
+/** Human-readable output \u2014 stdout normally, stderr once stdout is reserved for data. */
+function say(line: string): void {
+  if (stdoutReserved) console.error(line);
+  else console.log(line);
 }

package/src/cli/parse-flags.ts

@@ -0,0 +1,39 @@
+/**
+ * The CLI's flag parser.
+ *
+ * `--key value` / `-k value`, with a value-less flag defaulting to the string `'true'`.
+ * Extracted from the entry point so it can be tested without executing the CLI.
+ *
+ * The subtlety is what counts as "the next argument is a VALUE, not the next flag".
+ * Two legitimate values look like flags, or like nothing, to a naive check:
+ *
+ *   - A bare `-` is the conventional stdout sentinel. `db:plan --out -` documents itself
+ *     as "print to stdout"; read as a value-less flag it became `out=true` and the
+ *     command wrote a file literally named `true`.
+ *   - The EMPTY string is a value. `db:approvers --set ''` is the documented way to
+ *     declare an empty approver set and DISABLE destructive applies on a stage; read as
+ *     value-less it became `set=true`, and the command refused with "--set needs a
+ *     value" — so the documented way to turn the gate off could not be typed.
+ *
+ * Both are the same mistake: treating an unusual-looking value as an absent one. A flag
+ * is an argument that starts with `-` AND is longer than one character; everything else,
+ * including `''`, is a value.
+ */
+
+/** Is this argument a flag (as opposed to a value)? A bare `-` is a value. */
+function isFlag(arg: string): boolean {
+  return arg.startsWith('-') && arg.length > 1;
+}
+
+/** Parse `--key value` / `-k value` pairs; a flag with no value becomes `'true'`. */
+export function parseFlags(args: string[]): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!isFlag(arg)) continue;
+    const key = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
+    const next = args[i + 1];
+    flags[key] = next !== undefined && !isFlag(next) ? args[++i] : 'true';
+  }
+  return flags;
+}