@everystack/cli 0.4.44 → 0.4.46

package/package.json

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

package/src/cli/alter-type-dependents.ts

@@ -0,0 +1,96 @@
+/**
+ * alter-type-dependents — the mint-time gate for a hard PostgreSQL rule:
+ * `ALTER COLUMN … SET DATA TYPE` fails when a view, materialized view, or
+ * rewrite rule references the column ("cannot alter type of a column used by
+ * a view or rule"), and it fails MID-TRANSACTION, at apply time.
+ *
+ * The plan lane's contract is "what it mints, it can apply" — so the mint
+ * refuses the plan up front, with the dependents NAMED, instead of letting the
+ * operator discover them from a rolled-back apply. (Proven live: the first-ever
+ * Z1a apply of a brownfield adoption plan failed exactly this way.) The route
+ * for a real type migration under dependents is deliberate: rebuild through
+ * `db:swap`, or drop and re-create the derived objects around the change.
+ */
+
+import type { QueryRunner } from './authz-contract.js';
+
+export interface AlterTypeTarget {
+  table: string;
+  column: string;
+}
+
+export interface BlockedAlterType extends AlterTypeTarget {
+  /** Qualified names of the views / matviews / rules that bind the column. */
+  dependents: string[];
+}
+
+/**
+ * The (table, column) pairs a plan's `SET DATA TYPE` statements touch — read
+ * from the emitted artifact itself, the same way the destructive classifier
+ * reads it: the statement is what gets applied, so it is what gets checked.
+ */
+export function alterTypeStatementTargets(statements: readonly string[]): AlterTypeTarget[] {
+  const targets: AlterTypeTarget[] = [];
+  for (const s of statements) {
+    const m = s.match(/ALTER TABLE\s+(\S+)\s+ALTER COLUMN\s+"([^"]+)"\s+SET DATA TYPE\s/);
+    if (m) targets.push({ table: m[1], column: m[2] });
+  }
+  return targets;
+}
+
+const quoteLiteral = (s: string): string => `'${s.replace(/'/g, "''")}'`;
+
+/**
+ * The dependents PostgreSQL itself would refuse over: rewrite-rule entries
+ * (views, matviews, rules) that depend on the specific column. Whole-table
+ * dependencies (refobjsubid 0 — every view's FROM clause) are deliberately
+ * excluded: a view that never touches the column does not block the change.
+ */
+export function dependentsSql(target: AlterTypeTarget): string {
+  const rel = quoteLiteral(target.table);
+  return `
+SELECT DISTINCT
+  CASE cl.relkind WHEN 'v' THEN 'view' WHEN 'm' THEN 'materialized view' ELSE 'rule' END AS kind,
+  n.nspname || '.' || cl.relname AS name
+FROM pg_depend d
+JOIN pg_rewrite r ON r.oid = d.objid
+JOIN pg_class cl ON cl.oid = r.ev_class
+JOIN pg_namespace n ON n.oid = cl.relnamespace
+WHERE d.classid = 'pg_rewrite'::regclass
+  AND d.refclassid = 'pg_class'::regclass
+  AND d.refobjid = ${rel}::regclass
+  AND d.refobjsubid = (
+    SELECT attnum FROM pg_attribute
+    WHERE attrelid = ${rel}::regclass AND attname = ${quoteLiteral(target.column)}
+  )
+  AND cl.oid <> ${rel}::regclass
+ORDER BY name;
+`.trim();
+}
+
+/** Query the live catalog for each target; return only the blocked ones. */
+export async function findAlterTypeDependents(
+  runner: QueryRunner,
+  targets: readonly AlterTypeTarget[],
+): Promise<BlockedAlterType[]> {
+  const blocked: BlockedAlterType[] = [];
+  for (const t of targets) {
+    const rows = await runner(dependentsSql(t));
+    if (rows.length > 0) {
+      blocked.push({ ...t, dependents: rows.map((r: any) => `${r.kind} ${r.name}`) });
+    }
+  }
+  return blocked;
+}
+
+/** The refusal, with every dependent named — actionable, not archaeological. */
+export function renderAlterTypeRefusal(blocked: readonly BlockedAlterType[]): string {
+  const lines = blocked.map(
+    (b) => `  ${b.table}."${b.column}" is bound by: ${b.dependents.join(', ')}`,
+  );
+  return [
+    `This plan changes the type of ${blocked.length} column(s) that a view or rule depends on — PostgreSQL would refuse the ALTER mid-transaction ("cannot alter type of a column used by a view or rule"), so the mint refuses it now:`,
+    ...lines,
+    `Route the type change through db:swap (rebuild + atomic rename), or drop and re-create the dependent derived objects around it (db:reconcile) — deliberately, not as an apply-time surprise.`,
+  ].join('\n');
+}

package/src/cli/apply-execute.ts

@@ -30,9 +30,11 @@
  */
 
 import { introspectContract, type QueryRunner, type AuthzContract } from './authz-contract.js';
+import type { SessionRunner } from './session.js';
 import { introspectSchema, type SchemaSnapshot } from './schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog.js';
 import { fingerprintLive } from './schema-fingerprint.js';
+import { governedLiveFingerprint } from './edge-plan.js';
 import { applyGeneratedStatements } from './state-apply.js';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply.js';
 import { checkPlanPrecondition, planHash, type EdgePlan } from './edge-plan.js';
@@ -134,21 +136,30 @@ export interface LiveBaseFingerprint {
  * destructive-apply safety gate (backup.fp == plan.from). A second copy would silently drift the
  * fingerprint chain — the whole point of the gate.
  */
-export async function liveBaseFingerprint(runner: QueryRunner): Promise<LiveBaseFingerprint> {
-  const snapshot = await introspectSchema(runner);
-  const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+export async function liveBaseFingerprint(session: SessionRunner): Promise<LiveBaseFingerprint> {
+  const snapshot = await introspectSchema(session);
+  const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
   return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract };
 }
 
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
 export async function executeApplyPlan(
   runner: QueryRunner,
+  session: SessionRunner,
   plan: EdgePlan,
   options: ApplyPlanOptions = {},
 ): Promise<ApplyPlanResult> {
-  const { hash: live, snapshot: before, contract: beforeAuthz } = await liveBaseFingerprint(runner);
+  const { hash: live, snapshot: before, contract: beforeAuthz } = await liveBaseFingerprint(session);
 
-  if (live === plan.toFingerprint) {
+  // Two flavors, matched to what each check compares (see EdgePlan): the RAW
+  // hash for live-vs-live (the lock, the backup chain), the GOVERNED hash for
+  // declared-vs-live (already-applied here, verify-after below) — computed with
+  // the exact set the mint stamped on the plan. A plan minted before the field
+  // existed verifies raw, as it was minted.
+  const governed = plan.governedRoles ? new Set(plan.governedRoles) : undefined;
+  const governedLive = governed ? governedLiveFingerprint(before, beforeAuthz, governed) : live;
+
+  if (governedLive === plan.toFingerprint) {
     return { status: 'already-applied', liveFingerprint: live };
   }
   const pre = checkPlanPrecondition(plan, live);
@@ -200,16 +211,19 @@ export async function executeApplyPlan(
     now: options.now,
   });
 
-  const { hash: landed } = await liveBaseFingerprint(runner);
+  const { hash: landed, snapshot: after, contract: afterAuthz } = await liveBaseFingerprint(session);
   if (result.logId !== undefined) {
+    // The log stamps the RAW landed hash — the same flavor as `from`, so the
+    // schema_log chain reads as one consistent series of live states.
     await runner(renderSchemaLogFingerprintUpdate(result.logId, landed));
   }
 
-  if (landed !== plan.toFingerprint) {
+  const governedLanded = governed ? governedLiveFingerprint(after, afterAuthz, governed) : landed;
+  if (governedLanded !== plan.toFingerprint) {
     return {
       status: 'verify-failed',
       liveFingerprint: landed,
-      reason: `applied, but the target landed on ${landed.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
+      reason: `applied, but the target landed on ${governedLanded.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
       ...(result.logId !== undefined ? { logId: result.logId } : {}),
     };
   }

package/src/cli/authz-adoption-class.ts

@@ -0,0 +1,314 @@
+/**
+ * authz-adoption-class — WHY does this statement exist?
+ *
+ * A brownfield adopter's first plan is long, and the length is not the problem. The problem is
+ * that nobody can tell which statements are the tool imposing its own spelling and which are
+ * real differences between the model and the database. This classifier answers that, per
+ * statement, mechanically.
+ *
+ * FOUR CLASSES, and the whole point is that the first one should reach zero:
+ *
+ *  - `convention`  — exists ONLY because we spell a semantically identical rule differently.
+ *                    Every one of these is our bug. Phase A's success criterion is zero.
+ *  - `capability`  — the model cannot express what is live, so the plan would remove it.
+ *                    Real, and a gap in everystack, not in their schema.
+ *  - `narrowing`   — a genuine reduction of access. Must ship, labeled, and be approved by a
+ *                    human before it is applied.
+ *  - `dead`        — the live object is dead code: policed but never granted, so it authorizes
+ *                    nothing today.
+ *
+ * NAME COLLISION, stated once so nobody conflates them. `edge-plan.ts` already has
+ * `PlanClassification.narrowings`, which means a DATA-LOSSY `ALTER COLUMN … TYPE`. This
+ * `narrowing` means an ACCESS reduction. They are two orthogonal axes on the same statement —
+ * one asks "what does it cost?", the other asks "why is it here?" — and both are correct in
+ * their own frame. This module deliberately does NOT extend `PlanClassification`.
+ *
+ * READ-ONLY. Nothing here changes what is emitted. It reasons over the same declared and live
+ * contracts the emitter does, and a test pins its statement list to the emitter's actual
+ * output so the two can never drift apart.
+ */
+
+import { matchPolicies, roleSetEqual } from './authz-identity.js';
+import { governedRoleSet } from './authz-reconcile.js';
+import { effectivePolicyCheck, holdsPrivilege, isPolicyDead, policyCommands } from './authz-contract.js';
+import type { AuthzContract, PolicyContract, TableContract } from './authz-contract.js';
+
+export type AdoptionClass = 'convention' | 'capability' | 'narrowing' | 'dead' | 'unclassified';
+
+export interface ClassifiedStatement {
+  table: string;
+  /** The statement's subject — a policy name, or `grantee` for a privilege change. */
+  subject: string;
+  cls: AdoptionClass;
+  /** One line, in plain words, for the plan's report. */
+  why: string;
+}
+
+export interface AdoptionCounts {
+  convention: number;
+  capability: number;
+  narrowing: number;
+  dead: number;
+  unclassified: number;
+}
+
+/**
+ * The reconciler's own exemption rule, mirrored: a grantee the declared authz does not govern
+ * is left alone. `PUBLIC` compares case-insensitively because it is a pseudo-role with two
+ * catalog spellings; every other name compares exactly.
+ */
+function isGovernedGrantee(governed: ReadonlySet<string>, grantee: string): boolean {
+  return governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+const CRUD = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+
+/**
+ * Does `outer` cover every role in `inner`?
+ *
+ * PUBLIC (`['public']`) covers everything — it is an open set. That fact is used HERE ONLY, to
+ * decide whether a live policy's replacement is narrower (a label). It is deliberately NOT
+ * available to the matcher: letting PUBLIC compare equal to an enumerated set there would be
+ * the false match the whole phase exists to prevent. Labeling cannot widen access; matching
+ * can.
+ */
+function covers(outer: readonly string[], inner: readonly string[]): boolean {
+  if (outer.includes('public')) return true;
+  const o = new Set(outer);
+  return inner.every((r) => o.has(r));
+}
+
+/** Same authorization on every axis EXCEPT which roles it names — the role-split test. */
+function sameRule(a: PolicyContract, b: PolicyContract): boolean {
+  return a.command === b.command
+    && a.permissive === b.permissive
+    && (a.using ?? '') === (b.using ?? '')
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
+}
+
+/**
+ * A policy's predicate, collapsed to one line for the report.
+ *
+ * Live predicates arrive from `pg_get_expr` with real newlines and indentation (an EXISTS
+ * subquery spans several lines), and the adoption report is one line per statement. Collapsing
+ * keeps the rule READABLE in place rather than referring the operator elsewhere to find it.
+ */
+function pred(p: PolicyContract): string {
+  const using = (p.using ?? 'true').replace(/\s+/g, ' ').trim();
+  return using === 'true' ? 'true (unfiltered)' : using;
+}
+
+// `commandsOf` and the dead-policy test live in authz-contract — ONE definition, shared with
+// the reconciler, the canonical form, and db:pull.
+const commandsOf = policyCommands;
+const isDead = isPolicyDead;
+
+/** Classify the policy statements one table would emit. */
+function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedStatement[], governed: ReadonlySet<string>): void {
+  const table = d.table;
+  const m = matchPolicies(d.policies, l.policies);
+  const liveByName = new Map(l.policies.map((p) => [p.name, p]));
+
+  // Adopted shapes — a rule-identical policy under another name, or a live multi-role policy
+  // covering the declared per-role group — emit NOTHING, so there is nothing here to classify.
+  // This is what driving `convention` toward zero looks like: the statements stop existing
+  // rather than getting a nicer label.
+
+  const declaredByName = new Map(m.toCreate.map((p) => [p.name, p]));
+  const consumed = new Set<string>();
+
+  for (const name of m.toDrop) {
+    const live = l.policies.find((p) => p.name === name)!;
+
+    // The reconciler LEAVES a policy scoped entirely to ungoverned roles alone, so no statement
+    // is emitted for it and there is nothing here to classify. Counting one would describe a
+    // plan nobody is going to apply — the same reason classifyGrants skips those grantees.
+    if (live.roles.length > 0 && live.roles.every((r) => !isGovernedGrantee(governed, r))) continue;
+
+    // A DEAD policy is left alone by the reconciler now (it authorizes nothing, so dropping it
+    // changes no access), which means no statement exists to classify — same as the ungoverned
+    // case above, and counting one would describe a plan nobody is going to apply. The adopter
+    // still hears about it: db:pull writes the finding into the model file, where it persists.
+    if (isDead(l, live)) continue;
+
+    // A replacement exists when some declared policy governs the same command. If those
+    // replacements together cover FEWER roles than the live policy did, the plan is reducing
+    // access — a narrowing, which must be approved rather than merely applied.
+    const replacements = m.toCreate.filter(
+      (c) => commandsOf(c).some((cmd) => commandsOf(live).includes(cmd)),
+    );
+    if (!replacements.length) {
+      out.push({ table, subject: name, cls: 'capability', why: `no declared policy governs ${commandsOf(live).join('/')} — the model cannot express this rule` });
+      continue;
+    }
+
+    const replacementRoles = [...new Set(replacements.flatMap((r) => r.roles))];
+
+    // The role split: one live policy covering several roles, against the per-role policies the
+    // compiler emits. Same predicate, and the declared roles union to EXACTLY the live role set,
+    // so the two authorize identically for every session. Pure spelling — ours to fix (A5).
+    // Note this is recognized here for LABELING before the matcher can act on it; the two must
+    // agree once A5 lands, which is what the emitter-parity test pins.
+    if (roleSetEqual(live.roles, replacementRoles) && replacements.every((r) => sameRule(r, live))) {
+      out.push({ table, subject: name, cls: 'convention', why: `live covers ${live.roles.join(' + ')} in one policy; we split it per role with the same predicate` });
+      for (const r of replacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'convention', why: `the per-role half of "${name}"` });
+      }
+      continue;
+    }
+
+    if (covers(live.roles, replacementRoles) && !roleSetEqual(live.roles, replacementRoles)) {
+      out.push({ table, subject: name, cls: 'narrowing', why: `live applies to ${live.roles.join(', ')}; the declared replacement covers only ${replacementRoles.join(', ')}` });
+      for (const r of replacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'narrowing', why: `the narrower replacement for "${name}"` });
+      }
+      continue;
+    }
+
+    // The PREDICATE axis. Everything above this line decides on ROLE SETS alone, and that was
+    // the blind spot: a replacement holding the SAME roles with a different USING is a real
+    // access change that no role comparison can see. It fell to `unclassified` — a bucket with
+    // a count and, until E3, no detail — so the most dangerous shape this tool can emit was
+    // also its quietest. A live `(guard) AND (mine OR published)` read replaced by a
+    // `published`-only one is not silence; it is a replacement that READS as equivalent.
+    //
+    // Narrower vs. wider is not decidable here without a predicate lattice, so this takes the
+    // most severe reading, exactly as the destructive-statement partition does: an access change
+    // we cannot prove is identical is reported as a reduction, and BOTH predicates are carried
+    // so the operator reads the rule rather than the label.
+    const sameRoleReplacements = replacements.filter((r) => r.roles.some((role) => live.roles.includes(role)));
+    if (sameRoleReplacements.length && !sameRoleReplacements.some((r) => sameRule(r, live))) {
+      const shared = [...new Set(sameRoleReplacements.flatMap((r) => r.roles.filter((role) => live.roles.includes(role))))];
+      out.push({
+        table,
+        subject: name,
+        cls: 'narrowing',
+        why:
+          `live applies to ${shared.join(', ')} USING ${pred(live)}; the declared replacement `
+          + `${sameRoleReplacements.map((r) => `"${r.name}"`).join(', ')} keeps the same role(s) but states `
+          + `${sameRoleReplacements.map((r) => pred(r)).join(' / ')} — a different rule, not a different spelling`,
+      });
+      for (const r of sameRoleReplacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'narrowing', why: `the differently-predicated replacement for "${name}"` });
+      }
+      continue;
+    }
+
+    out.push({ table, subject: name, cls: 'unclassified', why: `dropped with a replacement that is neither the same rule nor narrower` });
+  }
+
+  for (const [name] of declaredByName) {
+    if (consumed.has(name)) continue;
+    out.push({ table, subject: name, cls: 'unclassified', why: `created with no live counterpart` });
+  }
+}
+
+/** Classify the privilege statements one table would emit. */
+function classifyGrants(
+  d: TableContract,
+  l: TableContract,
+  governed: ReadonlySet<string>,
+  out: ClassifiedStatement[],
+): void {
+  const table = d.table;
+
+  for (const grantee of Object.keys(l.grants).sort()) {
+    // The reconciler LEAVES ungoverned grantees alone — a migrator or BI reader the model
+    // vocabulary cannot name keeps its access, reported instead of revoked. It emits nothing
+    // for them, so neither may we: counting statements that are never emitted would describe
+    // a plan nobody is going to apply.
+    if (!isGovernedGrantee(governed, grantee)) continue;
+    const declared = new Set(d.grants[grantee] ?? []);
+    const live = l.grants[grantee] ?? [];
+    const revoked = live.filter((p) => !declared.has(p));
+    if (!revoked.length) continue;
+
+    // Every revoke here is now a NARROWING, including the beyond-CRUD trio.
+    //
+    // It used to be `convention` for REFERENCES/TRIGGER/TRUNCATE: `manage` means exactly CRUD,
+    // so live admin holding those three read as drift and the plan revoked them — 28 statements
+    // on the reference schema, none of which anybody asked for. The model has a word for them
+    // now (`privileges`), and `db:pull` transcribes what is live, so a pulled model emits
+    // nothing. A model that does NOT declare them is choosing to remove them, which is a real
+    // access reduction and gets labeled as one. The fix is at the source, not in the label.
+    out.push({ table, subject: grantee, cls: 'narrowing', why: `revokes ${revoked.join(', ')} from ${grantee}` });
+  }
+
+  // Column grants: the model expresses column scoping for READ only, so a live column-scoped
+  // UPDATE has no declaration and the plan revokes it. That is a gap in everystack.
+  const lcg = l.columnGrants ?? {};
+  const dcg = d.columnGrants ?? {};
+  for (const grantee of Object.keys(lcg).sort()) {
+    if (!isGovernedGrantee(governed, grantee)) continue;
+    for (const priv of Object.keys(lcg[grantee]).sort()) {
+      const declaredCols = new Set(dcg[grantee]?.[priv] ?? []);
+      const revoked = (lcg[grantee][priv] ?? []).filter((c) => !declaredCols.has(c));
+      if (!revoked.length) continue;
+      out.push({ table, subject: `${grantee}/${priv}`, cls: 'capability', why: `column-scoped ${priv} on ${revoked.length} column(s) — the model declares columns for read only` });
+    }
+  }
+}
+
+/**
+ * Classify every authorization statement the plan would emit, per table.
+ *
+ * Live tables no model declares are skipped: the plan does not touch them, so they contribute
+ * no statements to classify.
+ */
+export function classifyAdoption(
+  declared: AuthzContract,
+  live: AuthzContract,
+  opts: { governedRoles?: ReadonlySet<string> } = {},
+): {
+  statements: ClassifiedStatement[];
+  counts: AdoptionCounts;
+} {
+  const governed = opts.governedRoles ?? governedRoleSet(declared);
+  const liveByTable = new Map(live.tables.map((t) => [t.table, t]));
+  const statements: ClassifiedStatement[] = [];
+
+  for (const d of declared.tables) {
+    const l = liveByTable.get(d.table);
+    if (!l) continue; // a brand-new table adds; nothing here is an adoption decision
+    classifyPolicies(d, l, statements, governed);
+    classifyGrants(d, l, governed, statements);
+  }
+
+  const counts: AdoptionCounts = { convention: 0, capability: 0, narrowing: 0, dead: 0, unclassified: 0 };
+  for (const s of statements) counts[s.cls]++;
+  return { statements, counts };
+}
+
+/**
+ * The report block for the plan surface. Terse: one line per class, then the offenders.
+ *
+ * `unclassified` is the one class whose count cannot be acted on by itself — its whole meaning
+ * is "read these before applying", and a bare number gives the reader nothing to read. The
+ * adopter who hit this said it best: a count with no way to act on it is the same shape as the
+ * problem the bucket was created to solve. So every unclassified statement is NAMED here, and
+ * the per-statement detail rides on the artifact too (`adoption` on the plan).
+ *
+ * Only `unclassified` is expanded. The others are counts on purpose — 19 narrowings listed
+ * inline is a wall nobody reads, and they are each described by their class.
+ */
+export function renderAdoptionReport(counts: AdoptionCounts, statements: readonly ClassifiedStatement[] = []): string[] {
+  const lines = [
+    `  convention   ${counts.convention}  — our spelling, not their schema (this must reach 0)`,
+    `  capability   ${counts.capability}  — the model cannot express what is live`,
+    `  narrowing    ${counts.narrowing}  — real access reduction, approve before applying`,
+    `  dead         ${counts.dead}  — policed but never granted`,
+  ];
+  if (counts.unclassified) {
+    lines.push(`  unclassified ${counts.unclassified}  — NOT described; read these before applying:`);
+    for (const s of statements.filter((s) => s.cls === 'unclassified')) {
+      lines.push(`    ${s.table} "${s.subject}" — ${s.why}`);
+    }
+  }
+  return lines;
+}

package/src/cli/authz-baseline.ts

@@ -36,6 +36,7 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { FINGERPRINT_VERSION } from './schema-fingerprint.js';
 import type { GrantExemption } from './authz-reconcile.js';
 
 /** The repo-relative artifact. Generated — regenerating it must reproduce it byte for byte. */
@@ -58,6 +59,15 @@ export interface BaselineStage {
   observedAt: string;
   /** The live base fingerprint at observation time — what the claim was true OF. */
   fingerprint: string;
+  /**
+   * The FINGERPRINT_VERSION that hash was computed under.
+   *
+   * Stored beside the hash rather than only mixed into it, because a bare hash cannot say WHY
+   * it differs. Without this a baseline recorded under an older canonical form reads as drift,
+   * and an operator goes looking for a change nobody made instead of running one re-baseline.
+   * Absent on baselines written before v4.
+   */
+  fpVersion?: number;
   grantees: Record<string, BaselineGrantee>;
 }
 
@@ -71,7 +81,7 @@ export const EMPTY_BASELINE: AuthzBaseline = { version: 1, stages: {} };
 /** Fold the observed exemptions into one entry per grantee. */
 export function buildStageBaseline(
   exemptions: readonly GrantExemption[],
-  meta: { observedAt: string; fingerprint: string },
+  meta: { observedAt: string; fingerprint: string; fpVersion?: number },
 ): BaselineStage {
   const grantees: Record<string, BaselineGrantee> = {};
   for (const e of exemptions) {
@@ -83,7 +93,12 @@ export function buildStageBaseline(
     const all = [...e.privileges, ...Object.keys(e.columnPrivileges ?? {})];
     g.write ||= all.some((p) => WRITE_PRIVILEGES.has(p.toUpperCase()));
   }
-  return { observedAt: meta.observedAt, fingerprint: meta.fingerprint, grantees };
+  return {
+    observedAt: meta.observedAt,
+    fingerprint: meta.fingerprint,
+    fpVersion: meta.fpVersion ?? FINGERPRINT_VERSION,
+    grantees,
+  };
 }
 
 /** Write one stage's entry into the file, leaving every other stage untouched. */
@@ -105,7 +120,14 @@ export function renderBaseline(baseline: AuthzBaseline): string {
       const { privileges, tables, write } = s.grantees[g];
       grantees[g] = { privileges: [...privileges].sort(), tables: [...tables].sort(), write };
     }
-    stages[stage] = { observedAt: s.observedAt, fingerprint: s.fingerprint, grantees };
+    // `fpVersion` rides through the render, or the stamp is lost on the first rewrite and the
+    // baseline silently becomes unstamped — which reads as a format change forever after.
+    stages[stage] = {
+      observedAt: s.observedAt,
+      fingerprint: s.fingerprint,
+      ...(s.fpVersion != null ? { fpVersion: s.fpVersion } : {}),
+      grantees,
+    };
   }
   return JSON.stringify({ version: 1, stages }, null, 2) + '\n';
 }