@everystack/cli 0.4.72 → 0.4.74

package/src/cli/git-descent.ts

@@ -217,8 +217,17 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
     }
   }
 
+  // A materialized tree that carries NO barrel DECLARES NOTHING — a clean, deterministic 'no',
+  // not a failure to read. Every pre-Models repo has such ancestors: the models directory
+  // scaffolded (or present for another reason) before its barrel existed. Letting the loader
+  // throw on the absent file would classify it `compile-failed`, poisoning the verdict to
+  // UNVERIFIABLE — which sends a never-adopted database to "retry/upgrade" instead of to
+  // db:adopt. So the missing barrel is decided here, before the loader is ever consulted.
+  const barrelPath = path.join(dest, ctx.barrel);
+  if (!fs.existsSync(barrelPath)) return { kind: 'no' };
+
   const evaluate = async (): Promise<boolean> => {
-    const models = await ctx.loader(path.join(dest, ctx.barrel));
+    const models = await ctx.loader(barrelPath);
     const governedRoles = governedRolesForModels(models);
     const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: ctx.schema, governedRoles });
     return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
@@ -623,9 +632,13 @@ export async function proveDescent(
     reason:
       `no ancestor of your checkout declares the target's live fingerprint ` +
       `${short(fingerprintLive(live.snapshot, live.contract).hash)} — read ${candidates.length} ` +
-      'ancestor model state(s), all cleanly, and none matches. The database was hand-edited ' +
-      '(drift), or the deploying branch is not in this checkout. Align the models with the live ' +
-      'database (db:pull, commit), or waive the rule deliberately.',
+      'ancestor model state(s), all cleanly, and none matches. Either this database has never been ' +
+      'adopted into Models (nothing committed can declare it — the first-adoption case), or it ' +
+      'drifted after adoption. THE RUNBOOK: run everystack db:adopt — it renders Models from the ' +
+      'live database and PROVES they declare it exactly (it REFUSES rather than paper over any ' +
+      'difference); commit AND push that baseline, then re-run db:plan / db:apply and it descends ' +
+      'normally. If instead your Models are the source of truth and the database drifted, reconcile ' +
+      'with db:generate, or waive the rule deliberately.',
   };
 }
 

package/src/cli/index.ts

@@ -11,6 +11,7 @@ import { dbMigrateCommand, dbSeedCommand, dbResetCommand, dbPsqlCommand, dbDocto
 import { dbAuthzPullCommand, dbAuthzDiffCommand, dbAuthzTestCommand, dbAuthzOwnerCommand, dbAuthzReportCommand } from './commands/db-authz';
 import { dbGenerateCommand } from './commands/db-generate';
 import { dbPullCommand } from './commands/db-pull';
+import { dbAdoptCommand } from './commands/db-adopt';
 import { dbReconcileCommand } from './commands/db-reconcile';
 import { dbRefreshCommand } from './commands/db-refresh';
 import { dbFingerprintCommand } from './commands/db-fingerprint';
@@ -185,6 +186,9 @@ async function main() {
     case 'db:pull':
       await dbPullCommand(flags);
       break;
+    case 'db:adopt':
+      await dbAdoptCommand(flags);
+      break;
     case 'db:reconcile':
       await dbReconcileCommand(flags);
       break;
@@ -366,6 +370,7 @@ Usage:
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --govern-roles <r1,r2> (with --abilities live) transcribes the named FOREIGN roles' grants into privileges — the models then OWN them, so a fresh build recreates them; required for migration deletion when the migrations created grants to an ops/connection role. Explicit only (a re-pull must not silently govern), complete-or-refuse (a listed role holding a column-scoped grant fails the pull before anything is written). --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
+  everystack db:adopt          [--stage <name> | --database-url <url>] [--schema public] [--out db/models] [--govern-roles r1,r2]  First-time adoption of a pre-Models database, BY PROOF. A production DB that never went through Models has no committed ancestor declaring it, so db:apply refuses it as unverifiable drift and no waiver fits. db:adopt renders field() Models from the live DB (the same renderers db:pull uses, --abilities live), compiles them back, and finalizes the baseline ONLY when the compiled Models declare the live state EXACTLY (predicted == governed live — the same declares-test descent and db:check use). On success it writes --out (default db/models) and prints the \`chore(db): adopt live baseline <fp>\` commit — that commit legitimately declares the live state, so a later db:apply descends for real. PROVE not attest: there is NO bypass flag. When the round-trip is not exact, adoption REFUSES, names the surfaces that diverged, prints the db:generate edge, and writes NOTHING. Commit AND push the baseline before db:apply — an unpushed baseline is an unknown commit to teammates and the ops Lambda.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
   everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url refreshes over a local connection (dev); --stage <name> --direct resolves the stage's operator connection from its ops Lambda (credential never on argv) and refreshes CLI-side on an UNBOUNDED clock, for a matview set that exceeds the ops-Lambda 900s limit; --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.

package/src/cli/live-models.ts

@@ -0,0 +1,65 @@
+/**
+ * renderLiveModelFiles — the render db:pull and db:adopt SHARE.
+ *
+ * Both commands turn a live database into `field()` Models with the same posture: derive each
+ * model's authz from the grants and policies already there (`abilities: 'live'`), render the
+ * derived layer from the live catalog, and write the directory shape (one file per model + an
+ * index barrel). Factoring it here is not only DRY — it is the round-trip's correctness. db:adopt
+ * PROVES the rendered Models declare the live state; if adopt rendered even slightly differently
+ * from pull, the proof could refuse on a cosmetic difference pull produces fine. One renderer,
+ * one result.
+ *
+ * Pure: introspection results in, rendered files out. The command shells do the IO.
+ */
+
+import type { SchemaSnapshot } from './schema-introspect';
+import type { AuthzContract } from './authz-contract';
+import type { DerivedCatalog } from './derived-introspect';
+import { renderModelFiles, pullableTables, modelVarName, type RenderedModelFile } from './model-render';
+import { renderDerivedSource } from './derived-render';
+import { fingerprintLive } from './schema-fingerprint';
+import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from './authz-reconcile';
+import { deriveAbilities } from './authz-derive';
+
+export interface LiveModelRender {
+  /** The directory shape: one file per model + `index.ts` (the barrel that exports `models`). */
+  files: RenderedModelFile[];
+  /** The RAW live fingerprint — the baseline id db:adopt names the commit by. */
+  fingerprint: string;
+  /** Foreign grantees present at pull, exempt from revocation (the adoption baseline observation). */
+  exemptions: GrantExemption[];
+}
+
+/**
+ * Render `field()` Models from a live database in the live-abilities, directory shape. The
+ * `--govern-roles` complete-or-refuse gate runs here (pure re-derivation on the pulled tables),
+ * before any file is written, so a listed role holding a column-scoped grant throws instead of
+ * leaving a half-written tree.
+ */
+export function renderLiveModelFiles(
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  derivedCatalog: DerivedCatalog,
+  opts: { schema?: string | string[]; governRoles?: string[] } = {},
+): LiveModelRender {
+  const schema = opts.schema ?? 'public';
+  const governRoles = opts.governRoles ?? [];
+  const pulled = pullableTables(snapshot, schema);
+  const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
+  const derived = renderDerivedSource(derivedCatalog, { knownTables, sequences: snapshot.sequences });
+  const liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
+
+  // The --govern-roles gate, BEFORE any file is written: a governed role holding a column-scoped
+  // grant fails the render (deriveAbilities throws) rather than producing a half-owned barrel.
+  if (governRoles.length) {
+    const pulledNames = new Set(pulled.map((t) => t.table));
+    const govern = new Set(governRoles);
+    for (const [name, c] of liveAuthz) if (pulledNames.has(name)) deriveAbilities(c, { governRoles: govern });
+  }
+
+  const files = renderModelFiles(snapshot, { schema, abilities: 'live', liveAuthz, governRoles, derived });
+  // A governed role's grants are DECLARED (transcribed as privileges), so they are not also
+  // recorded as exemptions — that would double-book them, declared and exempted at once.
+  const exemptions = ungovernedGrants(contract, new Set([...ALWAYS_GOVERNED, ...governRoles]));
+  return { files, fingerprint: fingerprintLive(snapshot, contract).hash, exemptions };
+}

package/src/cli/schema-fingerprint-v10.ts

@@ -0,0 +1,152 @@
+/**
+ * FROZEN v10 canonicalizer — the exact live-side hash the CLI produced under
+ * FINGERPRINT_VERSION 10, before the command fan (Bug 2), effective-privilege deadness
+ * (Condition A), and serial-sequence ACLs (Bug 3) landed at v11.
+ *
+ * DO NOT EDIT this to track new behaviour. It exists for ONE purpose: `db:apply`'s
+ * fast-forward proof recomputes a `schema_log` row recorded at `fp_version = 10` against a
+ * CURRENT live read, and comparing an old-format hash against a current-format one reports a
+ * phantom mismatch. So the descent registry recomputes the LIVE side under the ROW's canon —
+ * this function — per the standing rule in `RETAINED_CANONS`.
+ *
+ * It is a SELF-CONTAINED copy of the v10 authz canonical form: the command dimension is NOT
+ * fanned, deadness reads the DIRECT grants (never the v11 effective-privilege matrix), and there
+ * is no `sequenceAuthz` slice. It reuses only the stable leaf normalizers (deparse + structure),
+ * whose drift is the documented deparse caveat and is equal across every version.
+ */
+
+import { createHash } from 'node:crypto';
+import type { PolicyContract, TableContract } from './authz-contract';
+import { effectivePolicyCheck, holdsPrivilege, policyCommands, isPolicySubsumed } from './authz-contract';
+import type { SchemaSnapshot, TableSchema } from './schema-introspect';
+import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff';
+import { stableStringify, schemaOf, type CanonicalizeOptions } from './schema-fingerprint';
+
+const PUBLIC_ROLE = 'public';
+
+const byKey = <T>(items: T[], key: (item: T) => string): T[] =>
+  [...items].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+
+// --- v10 authz canonical form (frozen: the command dimension is NOT fanned) ---
+
+/** v10 deadness: a policy governing a privilege none of its roles holds by DIRECT grant. */
+function isPolicyDeadV10(t: TableContract, p: PolicyContract): boolean {
+  const roles = p.roles.includes('public') || p.roles.includes('PUBLIC') ? Object.keys(t.grants) : p.roles;
+  if (!roles.length) return true;
+  return !policyCommands(p).some((cmd) => roles.some((r) => holdsPrivilege(t, r, cmd)));
+}
+
+function stableRuleV10(p: PolicyContract): string {
+  return JSON.stringify([p.command, p.permissive, p.using ?? '', effectivePolicyCheck(p) ?? '']);
+}
+
+function expandPolicyV10(p: PolicyContract): string[] {
+  const rule = stableRuleV10(p);
+  if (p.roles.includes(PUBLIC_ROLE)) return [`${PUBLIC_ROLE}|${rule}`];
+  return [...p.roles].sort().map((r) => `${r}|${rule}`);
+}
+
+function multiset(entries: string[]): Array<[string, number]> {
+  const counts = new Map<string, number>();
+  for (const e of entries) counts.set(e, (counts.get(e) ?? 0) + 1);
+  return [...counts.entries()].sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+function canonicalPoliciesV10(policies: readonly PolicyContract[], governed?: ReadonlySet<string>): Array<[string, number]> {
+  const entries = policies.flatMap(expandPolicyV10);
+  const kept = governed
+    ? entries.filter((e) => {
+        const role = e.slice(0, e.indexOf('|'));
+        return governed.has(role) || role === PUBLIC_ROLE || (role.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+      })
+    : entries;
+  return multiset(kept);
+}
+
+function governedOnly<T>(map: Record<string, T> | undefined, governed: ReadonlySet<string> | undefined): Record<string, T> {
+  if (!map) return {};
+  if (!governed) return map;
+  return Object.fromEntries(
+    Object.entries(map).filter(([grantee]) => governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'))),
+  );
+}
+
+function canonicalAuthzV10(contract: TableContract, governed?: ReadonlySet<string>): Record<string, unknown> {
+  const grants = governedOnly(contract.grants, governed);
+  const columnGrants = governedOnly(contract.columnGrants, governed);
+  return {
+    table: contract.table,
+    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
+    grants: Object.fromEntries(
+      Object.entries(grants).map(([role, privs]) => [role, [...(privs as string[])].sort()] as const).sort(([a], [b]) => (a < b ? -1 : 1)),
+    ),
+    ...(Object.keys(columnGrants).length > 0
+      ? {
+          columnGrants: Object.fromEntries(
+            Object.entries(columnGrants)
+              .map(([role, byPriv]) => [
+                role,
+                Object.fromEntries(
+                  Object.entries(byPriv as Record<string, string[]>).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: canonicalPoliciesV10(
+      contract.policies.filter((p) => !isPolicyDeadV10(contract, p) && !isPolicySubsumed(contract, p)),
+      governed,
+    ),
+  };
+}
+
+// --- v10 base-schema canonical form (identical to v11; frozen here for self-containment) ---
+
+function canonicalTableV10(table: TableSchema): Record<string, unknown> {
+  return {
+    table: table.table,
+    columns: byKey(
+      table.columns.map((c) => ({ name: c.name, type: c.type, notNull: c.notNull, default: normalizeDefault(c.default) })),
+      (c) => c.name,
+    ),
+    primaryKey: table.primaryKey,
+    uniques: byKey(table.uniques.map((u) => ({ columns: u.columns })), (u) => u.columns.join(',')),
+    checks: byKey(table.checks.map((c) => ({ expr: normalizeCheck(c.expr) })), (c) => c.expr),
+    foreignKeys: byKey(
+      table.foreignKeys.map((f) => ({
+        columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,
+        ...(f.onDelete ? { onDelete: f.onDelete } : {}),
+        ...(f.onUpdate ? { onUpdate: f.onUpdate } : {}),
+      })),
+      (f) => stableStringify(f),
+    ),
+    indexes: [...new Set(table.indexes.map(indexKey))].sort(),
+  };
+}
+
+/** The frozen v10 live hash for (snapshot, authzTables, opts). Sequence ACLs are NOT hashed. */
+export function fingerprintV10(snapshot: SchemaSnapshot, authzTables: TableContract[], opts: CanonicalizeOptions = {}): string {
+  const inScope = opts.schemas ? new Set(opts.schemas) : null;
+  const keepTable = (name: string) => inScope === null || inScope.has(schemaOf(name));
+  const tables = snapshot.tables.filter((t) => keepTable(t.table));
+  const usedEnum = new Set<string>();
+  for (const t of tables) for (const c of t.columns) usedEnum.add(schemaOf(c.type) === 'public' ? c.type : c.type.slice(c.type.indexOf('.') + 1));
+  const sequences = byKey(
+    (snapshot.sequences ?? [])
+      .filter((s) => inScope === null || inScope.has(schemaOf(s.name)))
+      .map((s) => ({ name: s.name, as: s.as, ...(s.start != null ? { start: s.start } : {}), ...(s.increment != null ? { increment: s.increment } : {}) })),
+    (s) => String(s.name),
+  );
+  const canonical = {
+    v: 10,
+    tables: byKey(tables.map(canonicalTableV10), (t) => String(t.table)),
+    enums: byKey(
+      (snapshot.enums ?? []).filter((e) => inScope === null || usedEnum.has(e.name)).map((e) => ({ name: e.name, values: e.values })),
+      (e) => e.name,
+    ),
+    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map((t) => canonicalAuthzV10(t, opts.governedRoles)), (t) => String(t.table)),
+    ...(sequences.length ? { sequences } : {}),
+  };
+  return createHash('sha256').update(stableStringify(canonical)).digest('hex');
+}

package/src/cli/schema-fingerprint.ts

@@ -43,21 +43,23 @@
  * Coverage is partial and SAYS SO: `UNFINGERPRINTED_SQL` enumerates what the
  * base fingerprint does not see (triggers — drift-checked separately by the
  * reconciler's provenance — domains, composite types, foreign/partitioned
- * tables, extensions, SEQUENCE ACLs, and the OWNER of a SECURITY DEFINER
- * function that declares none) so partial coverage reads as a report, never as
- * "covered everything". Standalone sequences left this list in v3: covered.
- * Sequence ACLs and the schema posture are scheduled to leave it at v11.
+ * tables, extensions, and the OWNER of a SECURITY DEFINER function that declares
+ * none) so partial coverage reads as a report, never as "covered everything".
+ * Standalone sequences left this list in v3: covered. SEQUENCE ACLs left it at
+ * v11: covered (derived per table from the A6 inheritance rule, measured live).
+ * The schema posture and identity columns remain deferred.
  */
 
 import { createHash } from 'node:crypto';
 import { canonicalAuthz } from './authz-canonical';
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect';
-import type { AuthzContract, TableContract } from './authz-contract';
+import type { AuthzContract, TableContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileEnums, compileSequences } from './schema-compile';
 import { compileTableContract } from './authz-compile';
-import { governedRoleSet } from './authz-reconcile';
-import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff';
+import { governedRoleSet, inheritedSequenceGrants } from './authz-reconcile';
+import { normalizeDefault, normalizeCheck, indexKey, nextvalSequence } from './schema-diff';
+import { fingerprintV10 } from './schema-fingerprint-v10';
 
 // 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
@@ -114,7 +116,21 @@ import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff';
 // 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 = 10;
+// v11 — Bug 2 + Bug 3, one bump. (a) The AUTHZ canonical form FANS THE COMMAND DIMENSION: a
+// policy is one entry per (role, command) with per-command predicate slots (INSERT using='';
+// SELECT/DELETE check=''; INSERT/UPDATE check = check ?? using), so a live FOR ALL and the
+// granular per-command policies a pull produces hash equal when they authorize the same thing —
+// and a FOR ALL that still holds a command a granular set denies stays distinct. Deadness and
+// subsumption move to the ARM: a dead (role,command) arm and a PUBLIC-covered one leave the state.
+// (b) DEADNESS folds ROLE MEMBERSHIP on the live side — a role holding a command through a parent
+// role or PUBLIC is alive, measured by has_table_privilege (the declared side stays on its direct
+// grants). (c) SERIAL-SEQUENCE ACLs enter the hash: per table, the multiset of its serial
+// sequences' grant shapes, derived from the A6 inheritance rule on the declared side and measured
+// on the live side, so a sequence REVOKE moves the fingerprint. Same consequence as every bump: a
+// plan or baseline minted under v10 refuses as a FORMAT CHANGE and must be re-minted (db:plan) or
+// re-baselined (db:reconcile --rebaseline) — no DDL, the fingerprint is a content address. The v10
+// canon is frozen in RETAINED_CANONS so a schema_log row recorded under it still descends.
+export const FINGERPRINT_VERSION = 11;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -191,6 +207,73 @@ export interface CanonicalState {
   /** Standalone sequences — present ONLY when any exist, so a sequence-free state's
    *  canonical form (and hash) is byte-identical to the pre-coverage form. */
   sequences?: Array<Record<string, unknown>>;
+  /** Serial-sequence ACLs, per table, as `[table, sorted multiset of grant-shape strings]`
+   *  (v11). Present ONLY when a table owns a serial sequence with a governed shape. */
+  sequenceAuthz?: Array<[string, string[]]>;
+}
+
+/** Is a grantee governed? PUBLIC compares case-insensitively; every other name exactly. */
+function isGovernedGrantee(governed: ReadonlySet<string> | undefined, grantee: string): boolean {
+  if (!governed) return true;
+  return governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+/** One sequence's grant shape as a stable string: governed grantees → sorted privileges. */
+function seqShape(grants: Record<string, string[]>, governed?: ReadonlySet<string>): string {
+  const kept = Object.entries(grants)
+    .filter(([grantee, privs]) => privs.length > 0 && isGovernedGrantee(governed, grantee))
+    .map(([grantee, privs]) => [grantee, [...privs].sort()] as const);
+  return stableStringify(Object.fromEntries(kept));
+}
+
+/**
+ * The canonical sequence-ACL slice (v11): per table, the sorted MULTISET of its serial
+ * sequences' grant shapes.
+ *
+ * Keyed by TABLE, not by pg's generated sequence name — that name truncates at 63 chars and
+ * collision-suffixes, and the DECLARED side (which never introspected) could not reproduce it.
+ * A multiset, not a union: a REVOKE on ONE of a table's several sequences still moves the hash.
+ *
+ * MEASURED vs DERIVED, PER TABLE — the axis the plan's predicted endpoint needs. A table present
+ * in the measured set uses its live ACLs (so a REVOKE is seen); a table absent DERIVES from its
+ * serial-column count × the A6-inherited grants (the state reconciliation targets). The declared
+ * side passes nothing and derives every table; a plain live read passes every measured table;
+ * the plan's predicted endpoint passes ONLY the rides-through tables, which reconciliation never
+ * touches, and lets the declared tables derive their reconciled target. Identity sequences are
+ * excluded on both sides — they inherit nothing, and the reconciler exempts them.
+ */
+function canonicalSequenceAuthz(
+  tables: TableSchema[],
+  authzTables: TableContract[],
+  measured: SequenceGrantContract[] | undefined,
+  governed: ReadonlySet<string> | undefined,
+  keepTable: (name: string) => boolean,
+): Array<[string, string[]]> {
+  const snapshotByTable = new Map(tables.map((t) => [t.table, t]));
+  const measuredByTable = new Map<string, SequenceGrantContract[]>();
+  for (const s of measured ?? []) {
+    (measuredByTable.get(s.table) ?? measuredByTable.set(s.table, []).get(s.table)!).push(s);
+  }
+  const out: Array<[string, string[]]> = [];
+  for (const az of authzTables) {
+    if (!keepTable(az.table)) continue;
+    let shapes: string[];
+    if (measuredByTable.has(az.table)) {
+      // LIVE: measure each non-identity sequence's actual ACL — this is what sees a REVOKE.
+      shapes = measuredByTable.get(az.table)!.filter((s) => !s.identity).map((s) => seqShape(s.grants, governed));
+    } else {
+      // DERIVED: one inherited shape per serial column (nextval default); identity columns,
+      // which carry no such default, are excluded exactly as the reconciler exempts them.
+      const snap = snapshotByTable.get(az.table);
+      const serialCount = (snap?.columns ?? []).filter((c) => nextvalSequence(normalizeDefault(c.default)) != null).length;
+      if (serialCount === 0) continue;
+      const inherited = seqShape(inheritedSequenceGrants(az), governed);
+      shapes = Array.from({ length: serialCount }, () => inherited);
+    }
+    if (shapes.length === 0) continue;
+    out.push([az.table, shapes.sort()]);
+  }
+  return out.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 /** The schema of a (possibly) qualified name — `stats.entities` → `stats`, a bare name → `public`. */
@@ -214,6 +297,14 @@ export interface CanonicalizeOptions {
    * every grantee is governed by construction.
    */
   governedRoles?: ReadonlySet<string>;
+  /**
+   * The MEASURED serial-sequence ACLs (v11). A table present here is hashed from its live ACLs
+   * (so a REVOKE moves the fingerprint); a table absent DERIVES its ACLs from the A6 inheritance
+   * rule (the reconciled target). The live path passes every measured table; the declared path
+   * passes nothing; the plan's predicted endpoint passes only rides-through tables. See
+   * {@link canonicalSequenceAuthz}.
+   */
+  sequenceGrants?: SequenceGrantContract[];
 }
 
 export function canonicalizeState(
@@ -256,6 +347,10 @@ export function canonicalizeState(
       (t) => String(t.table),
     ),
     ...(sequences.length ? { sequences } : {}),
+    ...((() => {
+      const sequenceAuthz = canonicalSequenceAuthz(tables, authzTables, opts.sequenceGrants, opts.governedRoles, keepTable);
+      return sequenceAuthz.length ? { sequenceAuthz } : {};
+    })()),
   };
 }
 
@@ -266,6 +361,37 @@ export interface Fingerprint {
   canonical: CanonicalState;
 }
 
+/**
+ * Which SURFACES of two canonical states diverge — so a MISMATCH names WHERE to look instead of
+ * only "run db:generate". Compares each top-level slice (base schema, authorization, sequence
+ * ACLs, enums, standalone sequences) as its stable string, and for the per-table slices lists the
+ * specific tables whose entry differs. Empty when the two states are identical.
+ */
+export function divergentSurfaces(a: CanonicalState, b: CanonicalState): string[] {
+  const out: string[] = [];
+  const named = (label: string, av: unknown, bv: unknown): void => {
+    if (stableStringify(av) !== stableStringify(bv)) out.push(label);
+  };
+  // Per-table slices: name the tables that differ, keyed by their `table` field.
+  const tablesDiff = (rows: Array<Record<string, unknown>> = []): Map<string, string> =>
+    new Map(rows.map((r) => [String(r.table), stableStringify(r)]));
+  const tableSurface = (label: string, ar: Array<Record<string, unknown>>, br: Array<Record<string, unknown>>): void => {
+    const am = tablesDiff(ar); const bm = tablesDiff(br);
+    const differ = [...new Set([...am.keys(), ...bm.keys()])].filter((t) => am.get(t) !== bm.get(t)).sort();
+    if (differ.length) out.push(`${label} (${differ.join(', ')})`);
+  };
+  tableSurface('base schema', a.tables, b.tables);
+  tableSurface('authorization', a.authz, b.authz);
+  named('enums', a.enums, b.enums);
+  named('standalone sequences', a.sequences, b.sequences);
+  // sequenceAuthz entries are [table, shapes] — name the tables.
+  const seqTables = (rows: Array<[string, string[]]> = []) => new Map(rows.map(([t, s]) => [t, stableStringify(s)]));
+  const as = seqTables(a.sequenceAuthz); const bs = seqTables(b.sequenceAuthz);
+  const seqDiffer = [...new Set([...as.keys(), ...bs.keys()])].filter((t) => as.get(t) !== bs.get(t)).sort();
+  if (seqDiffer.length) out.push(`sequence ACLs (${seqDiffer.join(', ')})`);
+  return out;
+}
+
 export function fingerprintState(
   snapshot: SchemaSnapshot,
   authzTables: TableContract[],
@@ -315,13 +441,15 @@ export function governedRolesForModels(
   return governedRoleSet(declared, extra ?? []);
 }
 
-/** Convenience: the live side, from the two existing introspections. */
+/** Convenience: the live side, from the two existing introspections. Passes the measured
+ *  sequence ACLs so a live serial-sequence REVOKE moves the hash (v11); when the contract never
+ *  measured them (older recorder), they stay absent and the sequence ACLs derive, as before. */
 export function fingerprintLive(
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
   opts: CanonicalizeOptions = {},
 ): Fingerprint {
-  return fingerprintState(snapshot, contract.tables, opts);
+  return fingerprintState(snapshot, contract.tables, { ...opts, sequenceGrants: contract.sequenceGrants });
 }
 
 // ---------------------------------------------------------------------------
@@ -359,10 +487,11 @@ export type CanonHasher = (
  * absent from this map is unrecomputable: `fingerprintLiveAtVersion` returns null and descent
  * SKIPS that row (fails closed), never guesses a hash.
  *
- * Today the map holds exactly the current version — there is nothing retired yet. It is the
- * mechanism and the rule that ship now; the first retired entry lands with the first bump.
+ * v11 is the FIRST bump, so v10 is the first retired entry: `fingerprintV10`, a self-contained
+ * frozen copy of the v10 canonical form (no command fan, direct-grant deadness, no sequence ACLs).
  */
 export const RETAINED_CANONS: Readonly<Record<number, CanonHasher>> = {
+  10: (snapshot, tables, opts) => fingerprintV10(snapshot, tables, opts),
   [FINGERPRINT_VERSION]: (snapshot, tables, opts) => fingerprintState(snapshot, tables, opts).hash,
 };
 
@@ -381,7 +510,10 @@ export function fingerprintLiveAtVersion(
 ): string | null {
   if (version == null) return null;
   const canon = canons[version];
-  return canon ? canon(snapshot, contract.tables, opts) : null;
+  // Thread the measured serial-sequence ACLs the way `fingerprintLive` does, so a v11 canon
+  // recomputes the SAME hash the apply recorded. A retired canon that predates sequence ACLs
+  // (v10) simply ignores the field — its self-contained copy never reads `sequenceGrants`.
+  return canon ? canon(snapshot, contract.tables, { ...opts, sequenceGrants: contract.sequenceGrants }) : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -390,12 +522,11 @@ export function fingerprintLiveAtVersion(
 
 /**
  * Objects outside both the base fingerprint (this module) and the derived
- * manifest (derived-introspect): standalone sequences, triggers, domains, composite
- * types, foreign tables, partitioned tables, installed extensions — sequence
- * ACLs, whose SHAPE is fingerprinted (a serial sequence rides its column default)
- * while the PRIVILEGES on it are not — and identity columns, which the models can
- * now say and the builder now builds, but which the hash does not yet cover.
- * Both of those last two enter the hash at v11.
+ * manifest (derived-introspect): triggers, domains, composite types, foreign
+ * tables, partitioned tables, installed extensions — and identity columns, which
+ * the models can now say and the builder now builds, but which the hash does not
+ * yet cover (deferred past v11 by scope). Serial-sequence ACLs left this list at
+ * v11: they are fingerprinted now (see canonicalSequenceAuthz).
  */
 export const UNFINGERPRINTED_SQL = `
 SELECT 'trigger' AS kind, n.nspname || '.' || c.relname || '.' || t.tgname AS identity
@@ -421,18 +552,6 @@ JOIN pg_namespace n ON n.oid = c.relnamespace
 WHERE c.relkind IN ('f', 'p')
   AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
 UNION ALL
--- A6/B4, the interim before v11. A serial/identity sequence's SHAPE is fingerprinted (it rides
--- the column default), but its ACL is not — and that ACL is load-bearing: a role that may INSERT
--- into the table and holds nothing on the sequence fails every INSERT with "permission denied for
--- sequence". Only sequences that actually CARRY an ACL are named; an ungranted one has nothing
--- unfingerprinted to say. Enters the hash at v11, batched with the schema posture.
-SELECT 'sequence ACL', n.nspname || '.' || c.relname
-FROM pg_class c
-JOIN pg_namespace n ON n.oid = c.relnamespace
-WHERE c.relkind = 'S' AND c.relacl IS NOT NULL
-  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')
-UNION ALL
 -- B5. A SECURITY DEFINER function executes with its OWNER's rights, so ownership is a privilege
 -- boundary. It is hashed ONLY WHEN DECLARED (derived-source's hashSourceContent prefixes the
 -- owner, so an object without one hashes byte-identically to before the feature existed), and