@everystack/cli 0.4.44 → 0.4.46

package/src/cli/git-descent.ts

@@ -32,7 +32,8 @@ import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { fingerprintLive } from './schema-fingerprint.js';
-import { predictLiveFingerprint } from './edge-plan.js';
+import { predictLiveFingerprint, governedLiveFingerprint } from './edge-plan.js';
+import { governedRolesForModels } from './schema-fingerprint.js';
 
 /** Compile a models barrel on disk. The default rides the CLI's runtime (tsx). */
 export type ModelsLoader = (barrel: string) => Promise<ModelDescriptor[]>;
@@ -174,7 +175,6 @@ export async function verifyDescent(
   const barrel = path.basename(modelsAbs);
 
   const candidates = enumerateModelTrees(modelsDir, repoRoot);
-  const liveFingerprint = fingerprintLive(live.snapshot, live.contract).hash;
 
   const nodeModules = path.join(repoRoot, 'node_modules');
   const materializeRoot = opts.materializeRoot
@@ -187,29 +187,36 @@ export async function verifyDescent(
   try {
     for (const candidate of candidates) {
       const dest = path.join(materializeRoot, candidate.tree);
-      let predicted: string;
+      let declares: boolean;
       // A swallowed error here skips the candidate — and if it was the DECLARING tree, the
       // verdict silently falls through to 'drift'. Real compile failures are deterministic;
       // a transient materialize/import failure (fd pressure, module-loader contention under
       // a parallel test run or a busy CI box) is not — so a failed candidate gets exactly
       // one retry, from a clean materialization, before it is recorded as a compile failure.
-      const attempt = async (): Promise<string> => {
+      //
+      // The declares-test is GOVERNED on both sides, per candidate: the commit's
+      // models define the governed set, and the live hash is filtered through the
+      // SAME set as the prediction — comparing a governed prediction against the
+      // raw live hash can never match on a brownfield target with foreign roles.
+      const attempt = async (): Promise<boolean> => {
         if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
         const models = await loader(path.join(dest, barrel));
-        return predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+        const governedRoles = governedRolesForModels(models);
+        const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema, governedRoles });
+        return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
       };
       try {
         try {
-          predicted = await attempt();
+          declares = await attempt();
         } catch {
           fs.rmSync(dest, { recursive: true, force: true });
-          predicted = await attempt();
+          declares = await attempt();
         }
       } catch (err: any) {
         compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
         continue;
       }
-      if (predicted !== liveFingerprint) continue;
+      if (!declares) continue;
 
       for (const commit of candidate.commits) {
         try {
@@ -255,7 +262,7 @@ export async function verifyDescent(
     scannedTrees: candidates.length,
     compileFailures,
     reason:
-      `no committed models state declares the target's live fingerprint ${short(liveFingerprint)} — ` +
+      `no committed models state declares the target's live fingerprint ${short(fingerprintLive(live.snapshot, live.contract).hash)} — ` +
       `scanned ${candidates.length} historical tree(s) across all refs${failureNote}. ` +
       'Either the database was hand-edited (drift) or the declaring history was rewritten. ' +
       'Align the models with the live database first (db:pull, commit), ' +

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, ... }.
@@ -383,7 +367,7 @@ Usage:
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + a snapshot (automatic via db:backup with --stage, else --snapshot-ref) + the stage's approver set when declared (STS identity-verified). Every refusal is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there; direct connection required
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + an attested --snapshot-ref + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only
   everystack db:backfill       [--database-url <url>] [--dir db/backfills] [--apply] [--mark-applied <file.sql>] [--json]  One-shot data jobs in their own lane: plan shows applied (by CONTENT identity — renames/comment edits are no-ops) / pending (in order, unbounded-pass advisories) / blocked (a name that already ran in a different form — one-shot jobs are immutable). --apply runs each pending job as its own transaction, recorded in everystack.backfill_log (a failure rolls back alone, is recorded, stops the run); --mark-applied records without running. Never runs as a schema side effect; direct connection required

package/src/cli/model-render.ts

@@ -97,13 +97,24 @@ export const ABILITY_PRESETS: Record<string, string[]> = {
 };
 
 /**
- * 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.
+ * A rendered ability that is a PUBLIC read — anon-visible, the shape the soft-delete guard
+ * applies to. Tested per-ability (never against the whole joined stanza) so one ability's
+ * `role:` can never mask another's public read.
+ *
+ * The TEXT form of `isPublicReadAbility` from `@everystack/model`, which is the structured
+ * one `defineModel`'s soft-delete refusal uses. Two representations because this renderer only
+ * ever holds rendered source (derive emits text, not descriptors), one meaning — pinned by a
+ * differential test over the ability matrix, the same way `tableReaches` is pinned against the
+ * grant compiler. They used to disagree: this counted `role: 'anon'`, the refusal did not, and
+ * a table whose authenticated read diverges renders exactly that shape. The refusal now fires
+ * on the anonymous audience however it is spelled, so both surfaces answer alike.
  */
-function isPublicReadAbility(expr: string): boolean {
-  return /^can\('read'/.test(expr.trim()) && !/\b(role|owner|via)\s*:/.test(expr);
+export function isPublicReadAbility(expr: string): boolean {
+  const e = expr.trim();
+  if (!/^can\('read'/.test(e)) return false;
+  if (/\b(owner|via)\s*:/.test(e)) return false;
+  const role = /\brole\s*:\s*'([^']+)'/.exec(e);
+  return !role || role[1] === 'anon';
 }
 
 /**
@@ -156,56 +167,47 @@ function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<stri
  * 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.
  */
+/**
+ * `writtenBy`, rendered ONLY when the live table is not FORCEd.
+ *
+ * `writtenBy` is not documentation — it is the sole input to RLS FORCE (`forced: writtenBy ===
+ * 'app'`, the compiler's one use of it), and it defaults to `'app'`. So a pulled model that
+ * omits it silently declares FORCE on every table, and the next plan carries an
+ * `ALTER TABLE … FORCE ROW LEVEL SECURITY` against a table someone deliberately left unforced
+ * — a real change to who bypasses row security, arriving in a plan as though it were adoption.
+ * The reference schema happens to be FORCEd throughout, which is exactly why this went unseen.
+ *
+ * `'worker'` is not a guess about the writer; it is the value whose COMPILED CONSEQUENCE
+ * matches the live bit. The comment says so, because a reader who takes it as a claim about
+ * the application would be misled — and this is a line they must consciously keep or change.
+ */
+function writtenByStanza(table: TableSchema, liveAuthz?: Map<string, TableContract>): string {
+  const live = liveAuthz?.get(table.table);
+  if (!live || live.rls.forced) return '';
+  return `  writtenBy: 'worker', // live reality: RLS is not FORCEd here, and only writtenBy controls that. `
+    + `'app' (the default) would FORCE it — a change to who bypasses row security, not an adoption.\n`;
+}
+
 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). */
-const FIELD_FACTORY: Record<string, string> = {
-  uuid: 'uuid',
-  text: 'text',
-  integer: 'integer',
-  bigint: 'bigint',
-  real: 'real',
-  'double precision': 'doublePrecision',
-  boolean: 'boolean',
-  json: 'json',
-  jsonb: 'jsonb',
-  date: 'date',
-  'timestamp with time zone': 'timestamptz',
-  'timestamp without time zone': 'timestamp',
-  timestamp: 'timestamp',
-};
+// The inverse type map lives with the vocabulary it inverts (`@everystack/model`),
+// where `field.pgType` refuses the spellings a first-class field owns — one
+// definition, two callers, so render and refusal can never disagree.
+import { fieldFactoryCall } from '@everystack/model';
+export { fieldFactoryCall };
 
 /**
- * The full `field.*()` call for a `format_type` string, or null when no field maps it.
- * Handles the parameterized types `format_type` spells out — `numeric(p,s)` and
- * `character varying(n)` — so a pulled column round-trips back to the same DDL. A
- * scale-0 numeric renders as the cleaner `field.numeric(p)` (identical to `(p, 0)`).
+ * The verbatim fallback for a type no first-class field owns: carry the exact
+ * `format_type` spelling with `field.pgType(...)`. An array carries its scalar
+ * plus `.array()` — the factory refuses a bracketed spelling by design.
  */
-export function fieldFactoryCall(type: string): string | null {
-  // An array is its base type + `.array()` — exactly how the compiler emits it
-  // (`format_type` spells arrays `text[]`). An array of an unmapped base stays null.
-  if (type.endsWith('[]')) {
-    const base = fieldFactoryCall(type.slice(0, -2));
-    return base ? `${base}.array()` : null;
-  }
-
-  const direct = FIELD_FACTORY[type];
-  if (direct) return `field.${direct}()`;
-
-  const num = type.match(/^numeric(?:\((\d+),(\d+)\))?$/);
-  if (num) {
-    if (num[1] == null) return 'field.numeric()';
-    return num[2] === '0' ? `field.numeric(${num[1]})` : `field.numeric(${num[1]}, ${num[2]})`;
-  }
-
-  const vc = type.match(/^character varying(?:\((\d+)\))?$/);
-  if (vc) return vc[1] != null ? `field.varchar(${vc[1]})` : 'field.varchar()';
-
-  return null;
+function verbatimFieldCall(type: string): string {
+  if (type.endsWith('[]')) return `${verbatimFieldCall(type.slice(0, -2))}.array()`;
+  return `field.pgType(${tsLiteral(type)})`;
 }
 
 /** `public.image_variants` / `image_variants` → `image_variants` (the bare table name). */
@@ -213,8 +215,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.
@@ -374,8 +393,11 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
     ?? (enumValues
       ? `field.enum(${tsLiteral(col.type)}, [${enumValues.map(tsLiteral).join(', ')}])`
       : fieldFactoryCall(col.type));
-  let expr = call ?? 'field.text()';
-  let comment = call ? '' : ` // FIXME: column type '${col.type}' has no field mapping`;
+  // No first-class field owns the type → carry it VERBATIM. The column's exact
+  // type is the identity, so the round trip is clean: no coercion, no FIXME, no
+  // plan statement. The note stays — a verbatim type is a fact worth seeing.
+  let expr = call ?? verbatimFieldCall(col.type);
+  let comment = call ? '' : ` // verbatim: no first-class field for '${col.type}' — carried as-is`;
 
   const isPk = table.primaryKey.includes(col.name);
   if (isPk) expr += '.primaryKey()';
@@ -486,9 +508,10 @@ 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 writtenBy = writtenByStanza(table, liveAuthz);
   const softDelete = softDeleteStanza(table, stanza.publicRead);
 
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${softDelete}  fields: {\n${fields}\n  },${constraints}\n});`;
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza.text}\n${writtenBy}${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/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;
+}

package/src/cli/schema-compile.ts

@@ -124,9 +124,14 @@ function scalarPgType(spec: FieldSpec): string {
     if (!spec.enumName) throw new Error('field bridge: an enum field needs a type name — field.enum(name, values)');
     return spec.enumName;
   }
+  if (spec.type === 'pgType') {
+    // A verbatim type: the declared string IS the canonical `format_type` spelling
+    // (the factory refused anything else), so it round-trips byte-for-byte.
+    if (!spec.pgTypeName) throw new Error('field bridge: a pgType field needs its type name — field.pgType(name)');
+    return spec.pgTypeName;
+  }
   const t = PG_TYPE[spec.type];
   if (!t) {
-    // geometry needs PostGIS — a deliberate follow-up, not a silent wrong column.
     throw new Error(`field bridge: no DDL mapping for field type '${spec.type}' yet`);
   }
   return t;

package/src/cli/schema-diff.ts

@@ -520,7 +520,7 @@ function createIndexChange(table: string, ix: IndexSchema): SchemaChange {
  * the consumer's 31 phantom drop/creates). Plain btree indexes key exactly as before
  * plus a constant tail — both sides compute the same key, so nothing churns.
  */
-function indexKey(ix: IndexSchema): string {
+export function indexKey(ix: IndexSchema): string {
   const entries = ix.columns.map((c) => normalizeCheck(c)).join(',');
   return `${ix.unique ? 'u' : ''}|${entries}|${normalizeCheck(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
 }

package/src/cli/schema-fingerprint.ts

@@ -46,12 +46,14 @@
  */
 
 import { createHash } from 'node:crypto';
+import { canonicalAuthz } from './authz-canonical.js';
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect.js';
 import type { AuthzContract, TableContract } from './authz-contract.js';
 import { compileTableSchema, compileEnums, compileSequences } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
-import { normalizeDefault, normalizeCheck } from './schema-diff.js';
+import { governedRoleSet } from './authz-reconcile.js';
+import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff.js';
 
 // v2: expression fields (defaults, checks, partial-index WHERE) normalize through
 // the diff's pg-deparse normalizers before hashing, so the model form and the live
@@ -62,7 +64,53 @@ import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 // STANDALONE SEQUENCES enter the canonical form (declared via defineSequence,
 // introspected from pg_sequence minus serial-owned) — a coverage expansion; the
 // `sequences` key appears only when any exist, so sequence-free states hash unchanged.
-export const FINGERPRINT_VERSION = 3;
+// v4: the AUTHZ canonical form became the reconciler's equivalence relation instead of a
+// name-keyed transcript of the catalog. Policy NAMES leave the hash (a brownfield database
+// names its policies whatever its previous migration tool named them, so hashing the name made
+// a policy carrying the declared authorization read as a different state); policies expand
+// across their roles as a MULTISET (so one policy TO a,b hashes equal to two identical ones TO
+// a and TO b, and duplicates never collapse); PUBLIC stays a single sentinel and is never
+// enumerated; and grants are filtered to the GOVERNED grantees, because the reconciler leaves
+// an ungoverned migrator/ETL role alone and a hash that counts it can never converge.
+// Together these restore the identity the format exists for: fingerprints match exactly when
+// db:generate is a no-op.
+// v5 — a redundant DEFAULT PRECISION is no longer part of a column's identity.
+// `timestamp(6) without time zone` and `timestamp without time zone` are the same type (6 is
+// the family's default), so they now canonicalize to one spelling in
+// `canonicalColumnType`. Two columns that always stored identical values used to hash
+// differently, which meant a schema carrying the explicit spelling could never reach MATCH.
+// Only precision 6 and only the timestamp family: `timestamp(3)` is a real difference.
+// Consequence, and the reason this is a VERSION and not a silent fix: a plan or baseline
+// minted under v4 against such a schema refuses as a FORMAT CHANGE and must be re-minted.
+// No DDL, no data movement — the fingerprint is a content address.
+// v6 — an INDEX'S IDENTITY is the differ's content key, verbatim. The v5 form hashed
+// {columns, unique, where} only, so a GIN and a btree index on the same column hashed
+// EQUAL while `db:generate` emitted a DROP + CREATE — MATCH could lie exactly where it
+// matters for tsvector/geometry (GIN/GiST). The v5 form also hashed indexes as a
+// multiset while the diff dedupes by content, so a physically duplicate index (two
+// identical indexes under different names — a common migration-era artifact) made
+// MATCH unreachable even though the diff was, correctly, a no-op. Both fixed the same
+// way: the canonical index entry is now `indexKey` from schema-diff — access method and
+// INCLUDE in, key entries normalized, names out, duplicates collapsed — ONE definition
+// for "are these the same index", shared by the differ and the hash. Same consequence
+// as every bump: plans/baselines minted under v5 refuse as FORMAT CHANGE and re-mint.
+// v7 — a DEAD policy is not part of the state. A policy governing a privilege none of its
+// roles holds authorizes nothing: Postgres refuses at the GRANT before ever consulting it.
+// The reconciler now leaves such a policy alone (dropping it changes no access, so it was
+// pure churn an adopter had to read and approve), and the canonical form stops counting it —
+// the same choice from the same function, `isPolicyDead`, which also backs the adoption
+// classifier's `dead` class and db:pull's notes. Without both halves the state could not
+// converge on any brownfield database carrying policies whose grants were revoked long ago.
+// Deadness is recomputed against live grants every time and never stored, so a policy
+// RE-ENTERS the state the moment a grant makes it effective.
+// v8 — a SUBSUMED policy is not part of the state either. Permissive policies OR together and
+// a PUBLIC policy applies to every role, so a role-scoped policy whose rule is identical to a
+// PUBLIC one admits no session the other does not: it changes no access, so it is churn, not
+// state. Same treatment and same lockstep as v7's dead policies — `isPolicySubsumed` excludes
+// it from the canonical form AND the reconciler leaves it alone, before and after. Restrictive
+// policies are never subsumed (they AND, so removing one would WIDEN), and the rule must match
+// exactly including the effective WITH CHECK.
+export const FINGERPRINT_VERSION = 8;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -107,48 +155,28 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
       })),
       (f) => stableStringify(f),
     ),
-    indexes: byKey(
-      // Partial-index WHERE is a predicate too — normalize it the same way as a check.
-      table.indexes.map((i) => ({ columns: i.columns, unique: i.unique, ...(i.where ? { where: normalizeCheck(i.where) } : {}) })),
-      (i) => stableStringify(i),
-    ),
+    // v6: an index's canonical form IS the differ's content key — one definition,
+    // both surfaces. That brings the access method (`using`) and INCLUDE set into
+    // the identity (a GIN and a btree on the same column are different states),
+    // normalizes key entries the way the diff compares them, and DEDUPES: two
+    // physically duplicate indexes are one state, exactly as the diff (which can
+    // neither create nor drop the second copy) already treats them.
+    indexes: [...new Set(table.indexes.map(indexKey))].sort(),
   };
 }
 
-function canonicalAuthzTable(contract: TableContract): Record<string, unknown> {
-  return {
-    table: contract.table,
-    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
-    grants: Object.fromEntries(
-      Object.entries(contract.grants)
-        .map(([role, privs]) => [role, [...privs].sort()] as const)
-        .sort(([a], [b]) => (a < b ? -1 : 1)),
-    ),
-    ...(contract.columnGrants && Object.keys(contract.columnGrants).length > 0
-      ? {
-          columnGrants: Object.fromEntries(
-            Object.entries(contract.columnGrants)
-              .map(([role, byPriv]) => [
-                role,
-                Object.fromEntries(
-                  Object.entries(byPriv)
-                    .map(([priv, cols]) => [priv, [...cols].sort()] as const)
-                    .sort(([a], [b]) => (a < b ? -1 : 1)),
-                ),
-              ] as const)
-              .sort(([a], [b]) => (a < b ? -1 : 1)),
-          ),
-        }
-      : {}),
-    policies: byKey(
-      contract.policies.map((p) => ({
-        name: p.name, command: p.command, roles: [...p.roles].sort(),
-        permissive: p.permissive, using: p.using, check: p.check,
-      })),
-      (p) => p.name,
-    ),
-    // The handler-side columns exposure block is NOT a database fact — excluded.
-  };
+/**
+ * The authorization slice of the canonical form.
+ *
+ * Delegates to `authz-canonical`, which the reconciler and the differ read too. Keeping a
+ * private copy here is what let the fingerprint drift out of step with the reconciler and
+ * report permanent drift on a database that had nothing to reconcile.
+ */
+function canonicalAuthzTable(
+  contract: TableContract,
+  governed?: ReadonlySet<string>,
+): Record<string, unknown> {
+  return canonicalAuthz(contract, governed);
 }
 
 export interface CanonicalState {
@@ -171,6 +199,17 @@ export interface CanonicalizeOptions {
   /** Restrict the state to these schemas — the content address of ONE schema (e.g. a
    *  schema-scoped artifact) instead of the whole database. Omitted = every schema. */
   schemas?: string[];
+  /**
+   * The grantees the models govern. PASS THIS WHENEVER HASHING A LIVE CONTRACT.
+   *
+   * The reconciler leaves an ungoverned grantee alone by design, so a live grant to a
+   * migrator or ETL role is never reconciled. A hash that counts it describes a state the
+   * models can never reach: the operator gets "nothing to do" from the plan and "you have
+   * drifted" from the gate, with no action in between that resolves it. Omitted means "hash
+   * every grantee", which is correct only for a contract compiled FROM the models, where
+   * every grantee is governed by construction.
+   */
+  governedRoles?: ReadonlySet<string>;
 }
 
 export function canonicalizeState(
@@ -208,7 +247,10 @@ export function canonicalizeState(
         .map((e) => ({ name: e.name, values: e.values })),
       (e) => e.name,
     ),
-    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map(canonicalAuthzTable), (t) => String(t.table)),
+    authz: byKey(
+      authzTables.filter((t) => keepTable(t.table)).map((t) => canonicalAuthzTable(t, opts.governedRoles)),
+      (t) => String(t.table),
+    ),
     ...(sequences.length ? { sequences } : {}),
   };
 }
@@ -248,6 +290,27 @@ export function fingerprintModels(
   return fingerprintState(snapshot, authzTables, opts.schemas ? { schemas: opts.schemas } : {});
 }
 
+/**
+ * The governed-role set a model checkout implies — THE set every declared-vs-live
+ * comparison must filter the live side through. One derivation, all callers:
+ * db:fingerprint's MATCH, the mint's `to` endpoint, the apply's verify-after and
+ * already-applied checks, and git-descent's declares-test. (v4 introduced the
+ * filter in the canonical layer; a live grant nothing will ever reconcile is not
+ * part of the state the models describe. Leaving a caller unfiltered re-creates
+ * the exact defect v4 fixed: zero statements, MATCH unreachable.)
+ * `extra` is the modules' widened `governedRoles` declaration.
+ */
+export function governedRolesForModels(
+  models: ModelDescriptor[],
+  extra?: readonly string[],
+): ReadonlySet<string> {
+  const declared: AuthzContract = {
+    tables: models.map((m) => compileTableContract(m, {})),
+    functions: [],
+  };
+  return governedRoleSet(declared, extra ?? []);
+}
+
 /** Convenience: the live side, from the two existing introspections. */
 export function fingerprintLive(
   snapshot: SchemaSnapshot,
@@ -305,3 +368,52 @@ export interface UnfingerprintedObject {
 export function mapUnfingerprintedRows(rows: Array<{ kind: unknown; identity: unknown }>): UnfingerprintedObject[] {
   return rows.map((r) => ({ kind: String(r.kind), identity: String(r.identity) }));
 }
+
+
+// ---------------------------------------------------------------------------
+// Comparing a STORED fingerprint against live reality.
+// ---------------------------------------------------------------------------
+
+/**
+ * A fingerprint as recorded in an artifact — a plan, a baseline, an export stamp.
+ *
+ * `v` is the format it was computed under. It must be stored ALONGSIDE the hash, not merely
+ * mixed into it: a hash alone cannot say why it differs, and the difference between "you have
+ * drifted" and "the format changed" is the difference between an operator hunting a phantom
+ * change and an operator running one re-baseline.
+ */
+export interface StoredFingerprint {
+  hash: string;
+  /** The FINGERPRINT_VERSION in force when the hash was computed. Absent = pre-v4 artifact. */
+  v?: number;
+}
+
+export type FingerprintComparison =
+  | { kind: 'match' }
+  | { kind: 'drift' }
+  | { kind: 'format-changed'; stored: number | 'unstamped'; current: number };
+
+/**
+ * Compare a stored fingerprint to one computed now.
+ *
+ * A raw hash compare across formats reports DRIFT, which is a lie — the state may be
+ * untouched while the way we describe it changed. Every hash comparison that spans an artifact
+ * boundary must come through here so a format change reads as a format change.
+ */
+export function compareStoredFingerprint(
+  stored: StoredFingerprint,
+  currentHash: string,
+  currentVersion: number = FINGERPRINT_VERSION,
+): FingerprintComparison {
+  if (stored.v !== currentVersion) {
+    return { kind: 'format-changed', stored: stored.v ?? 'unstamped', current: currentVersion };
+  }
+  return stored.hash === currentHash ? { kind: 'match' } : { kind: 'drift' };
+}
+
+/** The operator-facing sentence for a format change. Names the fix, never the phantom drift. */
+export function formatChangedMessage(c: Extract<FingerprintComparison, { kind: 'format-changed' }>): string {
+  return `fingerprint format changed (recorded v${c.stored}, current v${c.current}) — this is NOT drift. `
+    + 'The artifact predates the current canonical form, so its hash cannot be compared. '
+    + 'Re-mint the plan (db:plan) or re-baseline the stage (db:reconcile --rebaseline); no DDL is involved.';
+}