@everystack/cli 0.4.78 → 0.4.80

package/src/cli/edge-plan.ts

@@ -27,13 +27,16 @@
 import { createHash } from 'node:crypto';
 import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect';
-import type { AuthzContract } from './authz-contract';
+import type { AuthzContract, SequenceGrantContract, DefaultAclScope } from './authz-contract';
+import { ownSequenceName } from './schema-diff';
 import { generateMigrationSql, unmodeledTables } from './migration-generate';
 import { compileTableContract } from './authz-compile';
+import { carryUngovernedAuthz, inheritedSequenceGrants, type GrantExemption } from './authz-reconcile';
+import { BASELINE_FILE } from './authz-baseline';
 import { classifyGeneratedStatements, classifyDestructive, partitionStatements, renderStatementHistogram } from './state-apply';
-import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, FINGERPRINT_VERSION, type Fingerprint } from './schema-fingerprint';
+import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, schemaOf, FINGERPRINT_VERSION, type Fingerprint } from './schema-fingerprint';
 import { compileDeclaredState } from './declared-diff';
-import { compileTableRenames, compileTableMoves } from './schema-compile';
+import { compileTableRenames, compileTableMoves, compileRenames } from './schema-compile';
 
 export const PLAN_VERSION = 2;
 
@@ -48,8 +51,20 @@ export const PLAN_VERSION = 2;
  * runs, or a gate's semantics. Both packages import THIS binding (the server from the cli it
  * bundles), so a version skew is a hard, exact-equality refusal in both directions — never a
  * silently dropped gate.
+ *
+ * v2 (milestone plan-endpoint-full): `plan.toFingerprint` became the FULL endpoint (carries the
+ * ungoverned live authz through) and the server verifies the raw landed hash against it. An
+ * un-redeployed v1 ops Lambda would verify a GOVERNED landed hash against the full `to` and report
+ * verify-failed on a SUCCESSFUL brownfield apply — so the meaning of a gate changed and the peers
+ * must not mix. The handshake now forces a stage redeploy before an apply crosses versions.
+ *
+ * v3 (milestone finish-0-4-x): the payload gained `plan.defaultAclHash` and the server runs a new
+ * gate on it (`default privileges`, pre-dispatch). A v2 ops Lambda would ignore the key and skip
+ * the gate — not a false pass of the apply (it degrades to the post-DDL verify failure), but a
+ * silently dropped gate the operator was told is in force. The BUMP RULE says a gate the server
+ * runs is part of the contract, so the peers refuse until the stage is redeployed.
  */
-export const APPLY_CONTRACT_VERSION = 1;
+export const APPLY_CONTRACT_VERSION = 3;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
@@ -82,13 +97,29 @@ export interface EdgePlan {
    */
   fpVersion?: number;
   /**
-   * The predicted live fingerprint after apply — exact, unmodeled-aware, and
-   * GOVERNED: hashed through the models' governed-role set (`governedRoles`
-   * below), because it is a declared-vs-live claim. Compare it only against
-   * `governedLiveFingerprint` computed with the same set — never against the
-   * raw `from` flavor.
+   * The predicted live fingerprint after apply — exact and unmodeled-aware. Its FLAVOR is
+   * `toFlavor`: a `full` endpoint (every plan minted since N3) carries the ungoverned live authz
+   * through, so it equals the post-apply RAW live hash and db:apply compares `from`-flavor live
+   * against it directly. A `governed`/absent endpoint predates the full flavor and db:apply
+   * REFUSES it — comparing a full live hash against a governed `to` would false-verify-fail after
+   * the DDL already landed.
    */
   toFingerprint: string;
+  /**
+   * Which flavor `toFingerprint` is (milestone plan-endpoint-full). `full` carries the ungoverned
+   * live grants/policies/sequence ACLs through the prediction and is what db:apply verifies
+   * against. Absent means a pre-N3 plan whose `to` was governed — db:apply refuses it (re-mint).
+   */
+  toFlavor?: 'governed' | 'full';
+  /**
+   * The content address of the default-privilege posture (`pg_default_acl`, tables + sequences,
+   * every schema and grantee) the FULL prediction consumed at mint. `from` never hashed it —
+   * default ACLs are not object state — so an `ALTER DEFAULT PRIVILEGES` between mint and apply
+   * passed the concurrency lock, the DDL landed, and verify-after failed POST-DDL. db:apply
+   * compares this against the live posture BEFORE dispatch and refuses on a difference; absent
+   * means a plan minted before the lock existed, and db:apply refuses that too (re-mint).
+   */
+  defaultAclHash?: string;
   /**
    * The governed-role set `to` was hashed under, sorted — carried on the plan
    * so every apply venue verifies with the exact set the mint used. Absent on
@@ -162,7 +193,7 @@ export function predictLiveFingerprint(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
-  opts: { schema?: string; governedRoles?: ReadonlySet<string> } = {},
+  opts: { schema?: string; governedRoles?: ReadonlySet<string>; carryUngoverned?: boolean } = {},
 ): string {
   return predictLiveState(models, snapshot, contract, opts).hash;
 }
@@ -176,14 +207,20 @@ export function predictLiveState(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
-  opts: { schema?: string; governedRoles?: ReadonlySet<string> } = {},
+  opts: { schema?: string; governedRoles?: ReadonlySet<string>; carryUngoverned?: boolean } = {},
 ): Fingerprint {
-  // The prediction is a DECLARED-vs-live comparison, so it must hash through the
-  // models' governed set — the live side of any comparison against it must use
-  // the same set (see governedLiveFingerprint). Unfiltered, every ride-through
-  // table's foreign grants poison the endpoint and verify-after can never pass
-  // on a brownfield target.
+  // Two FLAVORS (milestone plan-endpoint-full):
+  //  - GOVERNED (default): hash through the models' governed set. A DECLARED-vs-live comparison —
+  //    the descent declares-test and db:check — must ignore the foreign grants the reconciler
+  //    leaves alone, or it reads "drifted" against a state the models can never reach.
+  //  - FULL (`carryUngoverned`): the plan's `to` endpoint. The reconciler converges the governed
+  //    roles and leaves the foreign ones, so the post-apply truth is the declared contract PLUS
+  //    the live ungoverned authz. Carry it through and hash UNFILTERED, so `to` equals the
+  //    post-apply full live hash and an empty plan means the two fingerprints are equal.
+  const carry = opts.carryUngoverned === true;
   const governedRoles = opts.governedRoles ?? governedRolesForModels(models);
+  const foreignGrantee = (role: string): boolean =>
+    !governedRoles.has(role) && !(role.toUpperCase() === 'PUBLIC' && governedRoles.has('PUBLIC'));
   const declared = compileDeclaredState(models, { schema: opts.schema });
   const declaredTables = new Set(declared.snapshot.tables.map((t) => t.table));
   const currentNames = new Set(snapshot.tables.map((t) => t.table));
@@ -214,16 +251,122 @@ export function predictLiveState(
       ...(snapshot.enums ?? []).filter((e) => !declaredEnums.has(e.name)),
     ],
   };
+  // The live counterpart of a declared table: its rename or move source when the edge brings it
+  // in under a new name, else its own name. Grants, policies and owned sequences survive RENAME
+  // TABLE and SET SCHEMA alike (they attach by OID), so the foreign authz carries across both.
+  // A model cannot declare both, so the two maps never collide.
+  const priorNameOf: Record<string, string> = {
+    ...compileTableMoves(models, { schema: opts.schema }),
+    ...compileTableRenames(models, { schema: opts.schema }),
+  };
+  const liveNameFor = (declaredTable: string): string =>
+    !currentNames.has(declaredTable) && currentNames.has(priorNameOf[declaredTable] ?? '')
+      ? priorNameOf[declaredTable]
+      : declaredTable;
+  const liveByTable = new Map(contract.tables.map((t) => [t.table, t]));
+  const declaredColumnsByTable = new Map(
+    declared.snapshot.tables.map((t) => [t.table, new Set(t.columns.map((c) => c.name))]),
+  );
+
+  // The UNGOVERNED default-privilege grants that fire for an object created in `schema` — the
+  // schema-specific rows unioned with the all-schemas ('') rows, foreign grantees only. Postgres
+  // applies these at CREATE, so a plan-created table/sequence lands with them; the reconciler
+  // never touches a foreign role, so they persist. Governed roles are excluded — the reconciler
+  // sets those explicitly and the declared contract already models them.
+  const defaultAclFor = (scope: DefaultAclScope | undefined, schema: string): Record<string, string[]> => {
+    if (!scope) return {};
+    const out: Record<string, string[]> = {};
+    for (const key of ['', schema]) {
+      for (const [grantee, privileges] of Object.entries(scope[key] ?? {})) {
+        if (foreignGrantee(grantee)) out[grantee] = [...new Set([...(out[grantee] ?? []), ...privileges])].sort();
+      }
+    }
+    return out;
+  };
+
+  // FULL flavor: each declared table's authz AFTER apply = declared contract + the live authz of
+  // the ungoverned roles, carried onto the columns the declared target keeps (carryUngovernedAuthz).
+  // A CREATED table (no live counterpart) has nothing to carry — but Postgres applies the schema's
+  // default privileges to it at creation, so fold the ungoverned default ACL in, or the endpoint
+  // omits a grant the apply lands and verify-after false-fails.
+  const declaredAuthz = carry
+    ? declared.contract.tables.map((d) => {
+      const liveTable = liveByTable.get(liveNameFor(d.table));
+      if (liveTable) return carryUngovernedAuthz(d, liveTable, governedRoles, declaredColumnsByTable.get(d.table) ?? new Set());
+      const defaultGrants = defaultAclFor(contract.defaultAcls?.tables, schemaOf(d.table));
+      return Object.keys(defaultGrants).length > 0 ? { ...d, grants: { ...d.grants, ...defaultGrants } } : d;
+    })
+    : declared.contract.tables;
   const mergedAuthz = [
-    ...declared.contract.tables,
+    ...declaredAuthz,
     ...contract.tables.filter((t) => ridesThrough(t.table)),
   ];
+
   // Sequence ACLs (v11): declared tables DERIVE their reconciled (inherited) target, so pass
   // measured ACLs ONLY for rides-through tables — the ones reconciliation never touches, whose
   // live ACLs carry through unchanged. Passing all measured would make a declared table's
   // predicted endpoint read its pre-reconcile ACL and never converge with the plan it mints.
   const ridesThroughSeqGrants = (contract.sequenceGrants ?? []).filter((s) => ridesThrough(s.table));
-  return fingerprintState(mergedSnapshot, mergedAuthz, { governedRoles, sequenceGrants: ridesThroughSeqGrants });
+  let sequenceGrants = ridesThroughSeqGrants;
+  if (carry) {
+    // FULL flavor, the sequence combine: a declared table's sequence lands with its GOVERNED
+    // grants DERIVED (the reconciler converges them onto the A6 inheritance) AND its FOREIGN
+    // grants MEASURED (the reconciler skips ungoverned roles, so their direct grants are
+    // unchanged). Deriving alone drops the foreign grant; passing the live measured grants reads
+    // a stale (pre-reconcile) governed shape. So synthesize one entry per live sequence whose
+    // grants = inherited-governed ∪ that-sequence's-foreign-live-grants, and hash UNFILTERED.
+    const liveSeqByTable = new Map<string, SequenceGrantContract[]>();
+    for (const s of contract.sequenceGrants ?? []) {
+      (liveSeqByTable.get(s.table) ?? liveSeqByTable.set(s.table, []).get(s.table)!).push(s);
+    }
+    const declaredColumnsFor = new Map(declared.snapshot.tables.map((t) => [t.table, t.columns]));
+    const liveColumnsFor = new Map(snapshot.tables.map((t) => [t.table, new Set(t.columns.map((c) => c.name))]));
+    const columnRenames = compileRenames(models, { schema: opts.schema });
+    const declaredSeqGrants: SequenceGrantContract[] = [];
+    for (const d of declaredAuthz) {
+      if (ridesThrough(d.table)) continue;
+      const inherited = inheritedSequenceGrants(d);
+      const liveName = liveNameFor(d.table);
+      for (const s of liveSeqByTable.get(liveName) ?? []) {
+        const foreign: Record<string, string[]> = {};
+        for (const [role, privileges] of Object.entries(s.grants)) {
+          if (foreignGrantee(role)) foreign[role] = privileges;
+        }
+        declaredSeqGrants.push({
+          sequence: s.sequence,
+          table: d.table,
+          grants: { ...inherited, ...foreign },
+          ...(s.identity !== undefined ? { identity: s.identity } : {}),
+        });
+      }
+      // The sequences THIS plan creates — every serial column of a created table, or a serial
+      // column ADDED to a live one. `plannedSerialSequences` grants by the diff's `createTable` /
+      // `addColumn` changes; this side has no diff in hand, so it reads the same facts off the
+      // live snapshot: a column is added when neither its own name nor its `renamedFrom` source
+      // exists live (a rename is a `renameColumn` change and creates nothing). Each lands with the
+      // governed inheritance the same plan grants (finish-0-4-x F1) PLUS the SEQUENCE default ACL
+      // Postgres applied at creation for the foreign roles. Identity columns own no nextval
+      // default and are excluded on both sides, so only serial columns count.
+      const liveColumns = liveColumnsFor.get(liveName);
+      const renamedFromOf = columnRenames[d.table] ?? {};
+      const existsLive = (column: string): boolean =>
+        liveColumns?.has(column) === true || (renamedFromOf[column] !== undefined && liveColumns?.has(renamedFromOf[column]) === true);
+      const seqDefaultGrants = defaultAclFor(contract.defaultAcls?.sequences, schemaOf(d.table));
+      (declaredColumnsFor.get(d.table) ?? [])
+        .filter((c) => ownSequenceName(d.table, c) != null && !existsLive(c.name))
+        .forEach((_, i) => declaredSeqGrants.push({
+          sequence: `${d.table}#created_seq_${i}`,
+          table: d.table,
+          grants: { ...seqDefaultGrants, ...inherited },
+          identity: false,
+        }));
+    }
+    sequenceGrants = [...ridesThroughSeqGrants, ...declaredSeqGrants];
+  }
+  return fingerprintState(mergedSnapshot, mergedAuthz, {
+    governedRoles: carry ? undefined : governedRoles,
+    sequenceGrants,
+  });
 }
 
 /**
@@ -283,19 +426,22 @@ export function mintEdgePlan(
   const breakdown = partitionStatements(classified.executable, { declaredGrantees });
   const destructive = breakdown.drops.length + breakdown.narrowings.length + breakdown.strips.length;
 
-  // The plan's two endpoints are two different FLAVORS, deliberately:
-  //  - `from` is the RAW live hash (everything introspected) — the concurrency
-  //    lock and the backup-stamp chain (backup.fp == plan.from) compare
-  //    live-vs-live and must stay computable with no models in hand.
-  //  - `to` is the GOVERNED hash — a declared-vs-live claim, filtered through
-  //    the models' governed set, which rides ON the plan so every venue
-  //    (direct, ops Lambda) verifies with the set the mint used.
+  // The plan's two endpoints are both FULL live hashes, deliberately:
+  //  - `from` is the RAW live hash (everything introspected) — the concurrency lock and the
+  //    backup-stamp chain (backup.fp == plan.from) compare live-vs-live.
+  //  - `to` is the FULL predicted endpoint: the declared state PLUS the ungoverned live authz the
+  //    reconciler leaves alone (carryUngoverned). So `to` equals the post-apply raw live hash, an
+  //    empty plan means `from == to`, and db:apply verifies the full landed hash against it.
+  // The governed set still rides on the plan — the descent declares-test and db:check use it — but
+  // the endpoint itself is full.
   const governedRoles = governedRolesForModels(models, opts.governedRoles);
   return {
     v: PLAN_VERSION,
     fromFingerprint: fingerprintLive(snapshot, contract).hash,
     fpVersion: FINGERPRINT_VERSION,
-    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema, governedRoles }),
+    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema, governedRoles, carryUngoverned: true }),
+    toFlavor: 'full',
+    defaultAclHash: defaultAclHash(contract),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
     governedRoles: [...governedRoles].sort(),
     statements,
@@ -384,6 +530,24 @@ export function tablesLeftWithoutARead(statements: readonly string[], live?: Aut
   return dark.sort();
 }
 
+/**
+ * The content address of a contract's default-privilege posture — what `plan.defaultAclHash`
+ * carries and what db:apply recomputes over the live contract before dispatch. The WHOLE
+ * posture, not just the foreign slice the prediction folds in: a governed default ACL changes
+ * what a created object lands with too, and re-minting is free. A contract that never read
+ * default ACLs (an older recorder, a hand-built fixture) hashes as "not measured" — equal to
+ * itself, never to a measured one.
+ *
+ * `current_user`-relative, like the read it hashes (DEFAULT_ACL_SQL keys on the role that will
+ * create the objects). Mint and apply as DIFFERENT database roles that own different default
+ * ACLs, and the hashes differ with no change in between — a false refusal whose escape is one
+ * re-mint. The stage lanes share one operator role, so this only bites a mint over a local DSN
+ * applied through `--stage`, or two local DSNs — and a plan should be minted where it is applied.
+ */
+export function defaultAclHash(contract: Pick<AuthzContract, 'defaultAcls'>): string {
+  return createHash('sha256').update(stableStringify(contract.defaultAcls ?? null)).digest('hex');
+}
+
 /** The plan's content address — recorded as `plan_ref` on the schema_log row. */
 export function planHash(plan: EdgePlan): string {
   return createHash('sha256').update(stableStringify(plan)).digest('hex');
@@ -420,15 +584,42 @@ const short = (hash: string): string => hash.slice(0, 12);
  * cutover, cli 0.4.77). The caller computes it at mint from the canonical forms; it is never
  * stored on the plan.
  */
+/**
+ * What accounts for an EMPTY edge between two DIFFERENT fingerprints — the `carriedBy` the
+ * summary prints. The `from` half is the full live fingerprint (the concurrency lock), the `to`
+ * half the declared endpoint through the governed set, and on a brownfield adopter they differ by
+ * exactly the roles the models do not govern: the reconciler leaves those grants alone. So when
+ * any ungoverned grantee is present, it IS the difference — name the roles and the baseline that
+ * admitted them (`db/authz-baseline.json`). Naming "35 tables differ" instead sent a consumer
+ * hunting a schema change that was not there (0.4.78 re-plan). Fall back to the raw divergent
+ * surfaces only when NO ungoverned grantee explains it — a live object the vocabulary cannot
+ * declare, say a policy on a governed role. Interim: the full fix carries the ungoverned authz
+ * through so the edge is truly empty (milestone plan-endpoint-full, N3).
+ */
+export function explainCarriedBy(
+  exemptions: readonly GrantExemption[],
+  divergent: readonly string[],
+): string[] {
+  const grantees = [...new Set(exemptions.map((e) => e.grantee))].sort();
+  if (grantees.length > 0) {
+    return [`grants to baseline-adopted role(s) ${grantees.join(', ')} (${BASELINE_FILE})`];
+  }
+  return [...divergent];
+}
+
 export function buildPlanSummary(plan: EdgePlan, opts: { carriedBy?: string[] } = {}): string[] {
   const lines: string[] = [];
   lines.push(`edge: ${short(plan.fromFingerprint)} → ${short(plan.toFingerprint)}`);
   if (plan.statements.length === 0) {
+    const carried = opts.carriedBy?.length ? `; carried by: ${opts.carriedBy.join('; ')}` : '';
     if (plan.fromFingerprint === plan.toFingerprint) {
-      lines.push('empty — the target already declares this state');
+      // Condition (c), milestone plan-endpoint-full: the full endpoint carries the foreign grants
+      // through, so a brownfield adopter reaches from == to — but the operator must still see WHICH
+      // ungoverned roles ride through untouched, or the baseline they were admitted under is invisible.
+      lines.push('empty — the target already declares this state' + carried);
     } else {
       lines.push('empty — no statement to emit. The fingerprints differ by what the plan leaves alone: `from` is the target\'s full fingerprint (the concurrency lock), `to` the declared endpoint through the governed set'
-        + (opts.carriedBy?.length ? `; carried by: ${opts.carriedBy.join('; ')}` : '') + '.');
+        + carried + '.');
     }
     return lines;
   }

package/src/cli/git-descent.ts

@@ -278,8 +278,9 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
   // 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.
+  // UNVERIFIABLE — which sends a never-adopted database to "retry/upgrade" instead of to the
+  // first-adoption lane (db:pull → commit → db:plan). 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' };
 
@@ -433,7 +434,7 @@ const firstLine = summarizeCompileError;
  * in a monorepo the app (`apps/expo/db/models`) has `apps/expo/node_modules`, and the root
  * `node_modules` may not carry the package at all (closing-gate review round 4, reproduced). No
  * `node_modules` anywhere up to the repo root → the repo root itself (a nested checkout still walks
- * up to its host's). Never the OS temp dir — that resolves nothing (the db:adopt 0.4.74 bug).
+ * up to its host's). Never the OS temp dir — that resolves nothing (the 0.4.74 sandbox-resolution bug).
  */
 export function materializeBase(repoRoot: string, modelsAbs: string): string {
   let dir = path.dirname(modelsAbs);

package/src/cli/index.ts

@@ -11,7 +11,6 @@ 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';
@@ -186,9 +185,6 @@ async function main() {
     case 'db:pull':
       await dbPullCommand(flags);
       break;
-    case 'db:adopt':
-      await dbAdoptCommand(flags);
-      break;
     case 'db:reconcile':
       await dbReconcileCommand(flags);
       break;
@@ -368,9 +364,8 @@ Usage:
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   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
+  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 on-ramp for an existing database: commit what it renders, then db:plan --stage <s>. EMPTY plan = adopted as it is (that commit declares the database; every later db:apply descends from it). NON-EMPTY plan = the hardening edge: review it, db:apply --plan <f> --stage <s> — no commit declares the database yet, so the reviewed plan is the ORIGIN. Render from the stage, never from a local restore of a dump. --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 AS IT IS, BY PROOF. A production DB that never went through Models has no committed ancestor declaring it; db:adopt is the on-ramp that makes one. It 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 edge, and writes NOTHING — that is the HARDENING case (the Models vocabulary cannot declare what is live, e.g. a sequence grant with no INSERT behind it), and it needs no adoption commit: commit the Models you intend, db:plan --stage, db:apply --stage. No commit declares the database yet, so db:apply PROVES that (proven drift) and treats the reviewed plan as the ORIGIN. 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/migration-generate.ts

@@ -16,12 +16,13 @@
  */
 
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
-import type { SchemaSnapshot } from './schema-introspect';
-import type { AuthzContract } from './authz-contract';
+import type { SchemaSnapshot, ColumnSchema } from './schema-introspect';
+import type { AuthzContract, SequenceGrantContract } from './authz-contract';
 import { compileTableSchema, compileRenames, compileTableRenames, compileTableMoves, compileCreateTable, compileEnums, compileSequences } from './schema-compile';
 import { compileTableContract } from './authz-compile';
 import { emitReconcileSql, governedRoleSet } from './authz-reconcile';
-import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff';
+import { diffSchema, emitSchemaSql, ownSequenceName, type SchemaChange } from './schema-diff';
+import { schemaOf } from './schema-fingerprint';
 
 export interface GenerateOptions {
   /** The Postgres schema the Models live in. Default: `public`. */
@@ -233,12 +234,22 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
       .filter(([, from]) => pendingMoveSources.has(from))
       .map(([to, from]) => [from, to] as const),
   ]);
+  // The owned sequences ride a RENAME/SET SCHEMA with their table (the sequence keeps its
+  // own name), so their live ACLs are keyed under the new table name too — else the sequence
+  // reconcile finds nothing for a renamed table and its inheritance lags a plan behind.
   const liveAuthzRenamed = opts.liveAuthz && pendingByFrom.size > 0
     ? {
         ...opts.liveAuthz,
         tables: opts.liveAuthz.tables.map((t) =>
           pendingByFrom.has(t.table) ? { ...t, table: pendingByFrom.get(t.table)! } : t,
         ),
+        ...(opts.liveAuthz.sequenceGrants
+          ? {
+              sequenceGrants: opts.liveAuthz.sequenceGrants.map((s) =>
+                pendingByFrom.has(s.table) ? { ...s, table: pendingByFrom.get(s.table)! } : s,
+              ),
+            }
+          : {}),
       }
     : opts.liveAuthz;
   const desiredContracts = models.map((m) => compileTableContract(m, { schema }));
@@ -246,6 +257,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   const authzPhase = liveAuthzRenamed
     ? emitReconcileSql(desiredAuthz, liveAuthzRenamed, {
         governedRoles: governedRoleSet(desiredAuthz, opts.governedRoles ?? []),
+        createdSequences: plannedSerialSequences(changes),
       })
     : [];
 
@@ -295,6 +307,28 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   return [...extensionPhase, ...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
 }
 
+/**
+ * The serial sequences a diff's data phase CREATES — one per serial column in a `createTable`
+ * or `addColumn` change whose default draws the column's OWN conventional `<table>_<col>_seq`
+ * (the `serial` shorthand is what creates it). A foreign `nextval` draws an existing sequence
+ * and creates none; an identity column has no nextval default; a rename/move creates nothing
+ * (the live sequence rides along under its old name). Returned as live-shaped entries with NO
+ * grants, for `emitReconcileSql`'s `createdSequences` — the reconcile then grants the same
+ * plan's INSERT-holders their inheritance right after the CREATE that makes the sequence.
+ */
+export function plannedSerialSequences(changes: readonly SchemaChange[]): SequenceGrantContract[] {
+  const out: SequenceGrantContract[] = [];
+  const push = (table: string, c: ColumnSchema): void => {
+    const seq = ownSequenceName(table, c);
+    if (seq) out.push({ sequence: `${schemaOf(table)}.${seq}`, table, grants: {}, identity: false });
+  };
+  for (const change of changes) {
+    if (change.kind === 'createTable') for (const c of change.schema.columns) push(change.table, c);
+    else if (change.kind === 'addColumn') push(change.table, change.column);
+  }
+  return out;
+}
+
 /** The marker drizzle migration files put between statements. */
 const BREAKPOINT = '\n--> statement-breakpoint\n';
 

package/src/cli/schema-diff.ts

@@ -208,10 +208,21 @@ export function sequenceCreateSql(seq: SequenceSchema): string {
   return `${s};`;
 }
 
+/**
+ * The bare name of the sequence a column OWNS through the `serial` shorthand — its conventional
+ * `<table>_<col>_seq` — or null: a foreign `nextval` draws an existing sequence and owns none,
+ * and an identity column has no nextval default. This is the one place that spells the
+ * convention; the CREATE/ADD renderer, the created-sequence grant, and the endpoint prediction
+ * all read it here so they cannot disagree about which columns make a sequence.
+ */
+export function ownSequenceName(table: string, col: ColumnSchema): string | null {
+  const seq = nextvalSequence(col.default);
+  return seq != null && seq === `${bareTable(table)}_${col.name}_seq` ? seq : null;
+}
+
 /** True when a column's default draws a sequence that is NOT its own conventional one. */
 function isForeignSequenceDefault(table: string, col: ColumnSchema): boolean {
-  const seq = nextvalSequence(col.default);
-  return seq != null && seq !== `${bareTable(table)}_${col.name}_seq`;
+  return nextvalSequence(col.default) != null && ownSequenceName(table, col) == null;
 }
 
 // ---------------------------------------------------------------------------
@@ -888,8 +899,7 @@ function serialSpelling(col: ColumnSchema, table: string): string | null {
   // ONLY the column's own conventional sequence is a serial declaration — the shorthand
   // creates a sequence, so spelling it for a foreign `nextval` would mint a duplicate
   // and silently detach the column from the sequence it declared.
-  const seq = nextvalSequence(col.default);
-  if (seq == null || seq !== `${bareTable(table)}_${col.name}_seq`) return null;
+  if (ownSequenceName(table, col) == null) return null;
   if (col.type === 'integer') return 'serial';
   if (col.type === 'bigint') return 'bigserial';
   return null;

package/src/cli/schema-fingerprint.ts

@@ -301,8 +301,10 @@ export interface CanonicalizeOptions {
    * 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}.
+   * passes nothing; the plan's predicted endpoint passes the rides-through tables measured — and
+   * in its FULL flavor (`carryUngoverned`) also one synthesized entry per declared table's
+   * sequence: its live sequences combined with the reconciled governed shape, plus the sequences
+   * the plan creates. See {@link canonicalSequenceAuthz}.
    */
   sequenceGrants?: SequenceGrantContract[];
 }
@@ -568,13 +570,14 @@ WHERE p.prosecdef
   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 = p.oid AND d.deptype = 'e')
 UNION ALL
--- A14, the interim before v11. A column's GENERATED … AS IDENTITY is now READ, DECLARED and
--- BUILT, but it is not yet hashed: the fingerprint's coverage is a version contract, and a
--- property entering the hash inside a version makes two operators on different CLI builds
--- disagree about the same database. So it is named here until v11 carries it, batched with the
--- sequence ACLs and the schema posture. The gap is real and narrow: an identity that is silently
--- dropped or flipped ALWAYS to BY DEFAULT leaves every fingerprint gate green. db:generate sees
--- it (the differ compares it), and the round-trip oracle's pg_dump comparison catches it.
+-- A14. A column's GENERATED … AS IDENTITY is READ, DECLARED and BUILT, but it is NOT hashed:
+-- the fingerprint's coverage is a version contract, and a property entering the hash inside a
+-- version makes two operators on different CLI builds disagree about the same database. v11
+-- took the sequence ACLs and deliberately left this and the schema posture out; both stay
+-- named here until a canon bump (a v12 candidate) carries them together. The gap is real and
+-- narrow: an identity that is silently dropped or flipped ALWAYS to BY DEFAULT leaves the MATCH
+-- claim green. It is not silent on the write path — db:generate/db:plan diff it (the differ
+-- compares identity) — and the round-trip oracle's pg_dump comparison catches it.
 SELECT 'identity column',
        n.nspname || '.' || c.relname || '.' || a.attname ||
        ' → ' || CASE a.attidentity WHEN 'a' THEN 'always' ELSE 'by default' END

package/src/cli/adopt.ts

@@ -1,58 +0,0 @@
-/**
- * adopt — the PROVE core of `db:adopt` (P2a). Pure: live introspection + compiled Models in, a
- * verdict out. The command shell (commands/db-adopt.ts) does the IO — introspect, render, load,
- * write files, print the commit.
- *
- * The doctrine (Fable-ruled 2026-09-05): PROVE, not attest. There is no bypass flag. db:adopt
- * renders Models from a live database and may finalize them ONLY when the compiled Models declare
- * that database EXACTLY — the same declares-test descent and db:check use (predicted == governed
- * live). A commit that carries such Models legitimately declares the live state, so a later
- * db:apply descends for real (proveDescent finds the adopt commit) instead of being forced past a
- * drift refusal. When the round-trip is not exact, adoption REFUSES and names what diverged —
- * because a baseline that silently papered over a difference is the bypass under another name.
- */
-
-import type { ModelDescriptor } from '@everystack/model';
-import type { SchemaSnapshot } from './schema-introspect';
-import type { AuthzContract } from './authz-contract';
-import { governedRolesForModels, fingerprintState, fingerprintLive, divergentSurfaces } from './schema-fingerprint';
-import { predictLiveState, governedLiveFingerprint } from './edge-plan';
-
-export interface AdoptionProof {
-  /** True when the compiled Models declare the live state exactly — safe to finalize the baseline. */
-  clean: boolean;
-  /** The RAW live fingerprint — the baseline id that names the adopt commit (`adopt live baseline <fp>`). */
-  fingerprint: string;
-  /** When not clean, the surfaces that still diverge (base schema / authorization / sequence ACLs,
-   *  with the tables named), so the refusal says exactly what the render could not capture. Empty when clean. */
-  divergentSurfaces: string[];
-}
-
-/**
- * Does this compiled Models set declare the live state exactly? The declares-test, governed on
- * both sides through the SAME set the Models imply — a governed prediction against a raw live
- * hash can never converge on a brownfield database with foreign roles. Reuses the very functions
- * descent (`evaluateTree`) and db:fingerprint compare with, so "adoption is clean" and "the plan
- * is empty" are one answer, not two that can disagree.
- */
-export function proveAdoption(
-  models: ModelDescriptor[],
-  snapshot: SchemaSnapshot,
-  contract: AuthzContract,
-  opts: { schema?: string } = {},
-): AdoptionProof {
-  const governedRoles = governedRolesForModels(models);
-  const predicted = predictLiveState(models, snapshot, contract, { schema: opts.schema, governedRoles });
-  const governedLiveHash = governedLiveFingerprint(snapshot, contract, governedRoles);
-  const clean = predicted.hash === governedLiveHash;
-  return {
-    clean,
-    fingerprint: fingerprintLive(snapshot, contract).hash,
-    divergentSurfaces: clean
-      ? []
-      : divergentSurfaces(
-          predicted.canonical,
-          fingerprintState(snapshot, contract.tables, { governedRoles, sequenceGrants: contract.sequenceGrants }).canonical,
-        ),
-  };
-}