@everystack/cli 0.3.21 → 0.3.22

package/README.md

@@ -220,7 +220,8 @@ everystack db:reconcile                 # deploy the derived layer (functions/vi
 everystack db:fingerprint               # content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:sync                      # make the database match your checkout — state + compute, one verb (dev DBs)
 everystack db:diff                      # the state edge between two declared states — no DB, CI-pure; reverse = computed rollback
-everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends
+everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends + the fast-forward rule (checkout must descend from the commit declaring the target's state)
+everystack db:check                     # the CI gate per PR: merged declared state composes + artifacts match regeneration (+ ephemeral from-scratch build w/ a scratch PG)
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

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

@@ -22,15 +22,17 @@
  */
 
 import fs from 'node:fs/promises';
-import { introspectContract, type QueryRunner } from '../authz-contract.js';
-import { introspectSchema } from '../schema-introspect.js';
+import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract.js';
+import { introspectSchema, type SchemaSnapshot } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { fingerprintLive } from '../schema-fingerprint.js';
 import { applyGeneratedStatements, currentGitRef } from '../state-apply.js';
 import { renderSchemaLogFingerprintUpdate } from '../derived-apply.js';
 import { checkPlanPrecondition, planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan.js';
+import { verifyDescent, type LiveState } from '../git-descent.js';
+import { resolveModelsPath } from '../models-path.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
-import { step, success, fail, info } from '../output.js';
+import { step, success, fail, info, warn } from '../output.js';
 
 // ---------------------------------------------------------------------------
 // The testable core.
@@ -40,12 +42,24 @@ export interface ApplyPlanOptions {
   actor?: string | null;
   /** Defaults to the plan's own gitRef (the intent that minted it). */
   gitRef?: string | null;
+  /**
+   * The fast-forward rule (brick 7): called with the target's live state
+   * after the concurrency lock passes, BEFORE anything executes. Return
+   * `ok: false` to refuse — the checkout does not descend from the commit
+   * declaring the target's state. Omitted = no descent enforcement (tests,
+   * or an explicit, confirmed, snapshotted force).
+   */
+  verifyDescent?: (live: {
+    snapshot: SchemaSnapshot;
+    contract: AuthzContract;
+    fingerprint: string;
+  }) => Promise<{ ok: true } | { ok: false; reason: string }>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
 
 export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'verify-failed';
+  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
@@ -69,6 +83,13 @@ export async function executeApplyPlan(
     return { status: 'refused', liveFingerprint: live, reason: pre.reason };
   }
 
+  if (options.verifyDescent) {
+    const descent = await options.verifyDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live });
+    if (!descent.ok) {
+      return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };
+    }
+  }
+
   const result = await applyGeneratedStatements(runner, plan.statements, {
     actor: options.actor,
     gitRef: options.gitRef ?? plan.gitRef,
@@ -134,15 +155,53 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     process.exit(1);
   }
 
+  // The fast-forward rule's force ceremony (design decision 9): explicit
+  // (--force-descent), snapshotted (its value NAMES the snapshot you took),
+  // and confirmed (--confirm). All three or no bypass.
+  const forceDescent = flags['force-descent'];
+  if (forceDescent !== undefined) {
+    if (forceDescent === 'true') {
+      fail('--force-descent needs the snapshot you took as its value: --force-descent <snapshot-ref> (take one first: db:snapshot or db:backup).');
+      process.exit(1);
+    }
+    if (flags.confirm !== 'true') {
+      fail('--force-descent bypasses the fast-forward rule — confirm explicitly with --confirm.');
+      process.exit(1);
+    }
+  }
+
   step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
   const { runner, end } = await createUrlRunner(dbSource.url);
 
   try {
     info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
+    if (forceDescent !== undefined) {
+      warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
+    }
     step('Verifying the target is where the plan started...');
     const result = await executeApplyPlan(runner, plan, {
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
+      ...(forceDescent === undefined ? {
+        verifyDescent: async (live: LiveState & { fingerprint: string }) => {
+          step('Descent: searching git for the commit that declares the target\'s state...');
+          const verdict = await verifyDescent(resolveModelsPath(flags.models), live, {});
+          switch (verdict.status) {
+            case 'ok':
+              info(`descent: ${verdict.commit.slice(0, 12)} declares the target's state and is an ancestor of HEAD — fast-forward.`);
+              return { ok: true };
+            case 'fresh-target':
+              info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
+              return { ok: true };
+            case 'no-git':
+              warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
+              return { ok: true };
+            case 'diverged':
+            case 'drift':
+              return { ok: false, reason: verdict.reason };
+          }
+        },
+      } : {}),
     });
 
     switch (result.status) {
@@ -153,6 +212,10 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
         fail(`REFUSED: ${result.reason}`);
         process.exit(1);
         break;
+      case 'descent-refused':
+        fail(`REFUSED (fast-forward rule): ${result.reason}`);
+        process.exit(1);
+        break;
       case 'verify-failed':
         fail(`Verify FAILED: ${result.reason}`);
         process.exit(1);

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

@@ -0,0 +1,306 @@
+/**
+ * `everystack db:check` — the CI regenerate-and-match gate (brick 7's PR
+ * invariant: the merged declared state must compose, and generated
+ * artifacts must match regeneration).
+ *
+ *   db:check [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>]
+ *            [--database-url <url>] [--json]
+ *
+ * Two rings, both from the checkout alone (no target database is ever
+ * touched — the gate runs on every PR):
+ *
+ *   STATIC — the models load and compose (a semantic merge conflict that
+ *   git can't see, like two branches declaring the same table, fails
+ *   here); the generated drizzle schema matches a byte-for-byte
+ *   regeneration (hand-edited artifacts and forgotten `db:generate` runs
+ *   fail loudly); the derived sources in db/sql parse.
+ *
+ *   EPHEMERAL COMPOSE — with a scratch PostgreSQL (`--database-url` /
+ *   DATABASE_URL), build the merged declared state FROM SCRATCH on an
+ *   ephemeral database (created and dropped inside the run): state, authz,
+ *   and the derived layer. Cross-layer breakage both layers hid from the
+ *   static ring — a matview referencing a dropped column — fails here,
+ *   mechanically. The bar is the brick-2 identity: the fresh database must
+ *   land EXACTLY on the models' fingerprint (MATCH), which is
+ *   regenerate-and-match at full strength.
+ *
+ * Exit 1 on any failure; nothing is ever skipped silently.
+ */
+
+import fs from 'node:fs/promises';
+import postgres from 'postgres';
+import type { ModelDescriptor } from '@everystack/model';
+import type { TableContract } from '../authz-contract.js';
+import { compileDeclaredState } from '../declared-diff.js';
+import { compileMigration } from '../migration-compile.js';
+import { compileDrizzleSource } from '../schema-source.js';
+import { parseSqlSources, type SourceFile } from '../derived-source.js';
+import { currentGitRef } from '../state-apply.js';
+import { createUrlRunner } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { executeSync, buildSyncReport, readSqlDirIfPresent } from './db-sync.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_SQL_DIR = 'db/sql';
+const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
+
+// ---------------------------------------------------------------------------
+// The static ring (pure).
+// ---------------------------------------------------------------------------
+
+export interface CheckFinding {
+  level: 'ok' | 'note' | 'fail';
+  area: 'models' | 'compose' | 'artifact' | 'compute';
+  message: string;
+}
+
+export interface StaticCheckInput {
+  modelsPath: string;
+  /** null = the barrel did not load — the gate's first failure. */
+  models: ModelDescriptor[] | null;
+  modelsError?: string;
+  artifactPath: string;
+  /** null = no generated schema artifact on disk. */
+  artifactSource: string | null;
+  /** null = no db/sql directory. */
+  sources: SourceFile[] | null;
+}
+
+export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
+  const findings: CheckFinding[] = [];
+
+  if (input.models === null) {
+    findings.push({
+      level: 'fail',
+      area: 'models',
+      message: `models did not load from ${input.modelsPath}: ${input.modelsError ?? 'unknown error'}`,
+    });
+    return findings;
+  }
+  findings.push({ level: 'ok', area: 'models', message: `${input.models.length} model(s) loaded from ${input.modelsPath}` });
+
+  // The semantic merge conflict git can't see: two branches declaring the
+  // same table both merge cleanly — the merged state must still compose.
+  const seen = new Map<string, number>();
+  for (const m of input.models) seen.set(`${m.schema}.${m.table}`, (seen.get(`${m.schema}.${m.table}`) ?? 0) + 1);
+  const duplicates = [...seen.entries()].filter(([, n]) => n > 1).map(([t]) => t);
+  if (duplicates.length > 0) {
+    findings.push({
+      level: 'fail',
+      area: 'compose',
+      message: `the merged declared state does NOT compose: table(s) declared more than once — ${duplicates.join(', ')}. A merge landed two declarations of the same table; resolve to one.`,
+    });
+    return findings;
+  }
+  try {
+    compileDeclaredState(input.models);
+    const statements = compileMigration(input.models);
+    findings.push({ level: 'ok', area: 'compose', message: `declared state composes — ${statements.length} statement(s) from scratch` });
+  } catch (err: any) {
+    findings.push({ level: 'fail', area: 'compose', message: `the merged declared state does NOT compose: ${err.message}` });
+    return findings;
+  }
+
+  if (input.artifactSource === null) {
+    findings.push({
+      level: 'note',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — nothing to match (db:generate writes it)`,
+    });
+  } else if (input.artifactSource === compileDrizzleSource(input.models)) {
+    findings.push({ level: 'ok', area: 'artifact', message: `${input.artifactPath} matches regeneration byte-for-byte` });
+  } else {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `${input.artifactPath} does NOT match regeneration — the models moved without db:generate, or the artifact was hand-edited (generated artifacts are never edited). Regenerate and commit.`,
+    });
+  }
+
+  if (input.sources === null) {
+    findings.push({ level: 'note', area: 'compute', message: 'no db/sql directory — derived layer not declared, nothing to parse' });
+  } else {
+    try {
+      const parsed = parseSqlSources(input.sources);
+      findings.push({
+        level: 'ok',
+        area: 'compute',
+        message: `${parsed.objects.length} derived object(s) parsed from ${input.sources.length} db/sql file(s)`,
+      });
+      for (const w of parsed.warnings) findings.push({ level: 'note', area: 'compute', message: w });
+    } catch (err: any) {
+      findings.push({ level: 'fail', area: 'compute', message: `db/sql does not parse: ${err.message}` });
+    }
+  }
+
+  return findings;
+}
+
+export function checkFailed(findings: CheckFinding[]): boolean {
+  return findings.some((f) => f.level === 'fail');
+}
+
+// ---------------------------------------------------------------------------
+// The ephemeral compose ring.
+// ---------------------------------------------------------------------------
+
+/** Every role the contract grants to or names in a policy — the compose DB needs them. */
+export function rolesFromContract(tables: TableContract[]): string[] {
+  const roles = new Set<string>();
+  for (const t of tables) {
+    for (const grantee of Object.keys(t.grants)) roles.add(grantee);
+    for (const grantee of Object.keys(t.columnGrants ?? {})) roles.add(grantee);
+    for (const p of t.policies) for (const r of p.roles) roles.add(r);
+  }
+  roles.delete('PUBLIC');
+  roles.delete('public');
+  return [...roles].sort();
+}
+
+export interface EphemeralComposeResult {
+  database: string;
+  createdRoles: string[];
+  converged: boolean;
+  fingerprintMatch: boolean;
+  fingerprint: string;
+  report: string[];
+}
+
+/**
+ * Build the declared state from scratch on an ephemeral database: CREATE
+ * DATABASE, roles the contract references (NOLOGIN, cluster-level, created
+ * only if absent), one `executeSync` for both layers, DROP DATABASE —
+ * always, error or not. The bar is `converged && fingerprintMatch`: a
+ * fresh database has nothing unmodeled and nothing to drop, so anything
+ * short of MATCH is a real compose fault.
+ */
+export async function executeEphemeralCompose(
+  adminUrl: string,
+  models: ModelDescriptor[],
+  sources: SourceFile[] | null,
+  opts: { actor?: string | null; gitRef?: string | null } = {},
+): Promise<EphemeralComposeResult> {
+  const dbName = `escheck_${process.pid}_${Date.now()}`;
+  const admin = postgres(adminUrl, { max: 1 });
+  try {
+    await admin.unsafe(`CREATE DATABASE "${dbName}"`);
+  } finally {
+    await admin.end();
+  }
+
+  const { runner, end } = await createUrlRunner(adminUrl.replace(/\/[^/?]+(\?|$)/, `/${dbName}$1`));
+  try {
+    const roles = rolesFromContract(compileDeclaredState(models).contract.tables);
+    for (const role of roles) {
+      if (!/^[a-z_][a-z0-9_$]*$/i.test(role)) {
+        throw new Error(`contract references a role name that is not a plain identifier: ${JSON.stringify(role)}`);
+      }
+      await runner(
+        `DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE "${role}" NOLOGIN; END IF; END $$`,
+      );
+    }
+
+    const run = await executeSync(runner, models, sources, {
+      actor: opts.actor ?? 'db:check',
+      gitRef: opts.gitRef ?? null,
+    });
+    return {
+      database: dbName,
+      createdRoles: roles,
+      converged: run.converged,
+      fingerprintMatch: run.fingerprintMatch,
+      fingerprint: run.state.toFingerprint,
+      report: buildSyncReport(run),
+    };
+  } finally {
+    await end?.();
+    const reaper = postgres(adminUrl, { max: 1 });
+    try {
+      await reaper.unsafe(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
+    } finally {
+      await reaper.end();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The CLI shell.
+// ---------------------------------------------------------------------------
+
+const MARK: Record<CheckFinding['level'], string> = { ok: '=', note: '·', fail: '!' };
+
+export async function dbCheckCommand(flags: Record<string, string>): Promise<void> {
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[] | null = null;
+  let modelsError: string | undefined;
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+  } catch (err: any) {
+    modelsError = err.message;
+  }
+
+  const artifactPath = flags['schema-out'] || DEFAULT_SCHEMA_OUT;
+  let artifactSource: string | null = null;
+  try {
+    artifactSource = await fs.readFile(artifactPath, 'utf8');
+  } catch {
+    artifactSource = null;
+  }
+  const sources = await readSqlDirIfPresent(flags['sql-dir'] || DEFAULT_SQL_DIR);
+
+  const findings = runStaticChecks({ modelsPath, models, modelsError, artifactPath, artifactSource, sources });
+  for (const f of findings) {
+    (f.level === 'fail' ? warn : info)(`${MARK[f.level]} ${f.area}: ${f.message}`);
+  }
+
+  let ephemeral: EphemeralComposeResult | null = null;
+  let ephemeralError: string | null = null;
+  const url = flags['database-url'] || process.env.DATABASE_URL;
+  const staticFailed = checkFailed(findings);
+  if (staticFailed) {
+    warn('ephemeral compose skipped — fix the static failures first.');
+  } else if (!url) {
+    warn('ephemeral compose SKIPPED — no --database-url / DATABASE_URL. Point db:check at a scratch PostgreSQL for the full gate (it creates and drops an ephemeral database).');
+  } else {
+    step('Composing the declared state from scratch on an ephemeral database...');
+    try {
+      ephemeral = await executeEphemeralCompose(url, models!, sources, {
+        actor: process.env.USER ?? 'db:check',
+        gitRef: currentGitRef(),
+      });
+      for (const line of ephemeral.report) info(`  ${line}`);
+    } catch (err: any) {
+      ephemeralError = err.message;
+      warn(`! compose: the declared state does NOT build from scratch: ${ephemeralError}`);
+    }
+  }
+
+  const ephemeralFailed = ephemeralError !== null
+    || (ephemeral !== null && !(ephemeral.converged && ephemeral.fingerprintMatch));
+  const failed = staticFailed || ephemeralFailed;
+
+  if (flags.json === 'true') {
+    console.log(JSON.stringify({
+      findings,
+      ephemeral: ephemeral === null ? null : {
+        converged: ephemeral.converged,
+        fingerprintMatch: ephemeral.fingerprintMatch,
+        fingerprint: ephemeral.fingerprint,
+        createdRoles: ephemeral.createdRoles,
+      },
+      ephemeralError,
+      ephemeralRan: ephemeral !== null,
+      failed,
+    }, null, 2));
+  } else if (failed) {
+    fail('db:check FAILED — the merged declared state is not shippable as-is (findings above).');
+  } else if (ephemeral !== null) {
+    success(`db:check passed — declared state composes from scratch and lands MATCH at ${ephemeral.fingerprint.slice(0, 12)}.`);
+  } else {
+    success('db:check passed (static ring only — no database provided for the ephemeral compose).');
+  }
+
+  if (failed) process.exit(1);
+}

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

@@ -24,6 +24,7 @@ import { introspectContract, type QueryRunner } from '../authz-contract.js';
 import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
+import { verifyDescent } from '../git-descent.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -101,6 +102,17 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
 
     for (const line of buildPlanSummary(plan)) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
+
+    // The fast-forward rule, warn-only at mint time (db:apply enforces it):
+    // a stale checkout mints a legal-looking plan whose edge REVERTS merged
+    // work — say so on the review surface, where a human still reads it.
+    if (plan.statements.length > 0) {
+      const verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
+      if (verdict.status === 'diverged' || verdict.status === 'drift') {
+        warn(`descent: ${verdict.reason}`);
+        warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+      }
+    }
     if (out !== '-') {
       success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
       warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');

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

@@ -212,7 +212,7 @@ export function syncFailed(run: SyncRun): boolean {
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
+export async function readSqlDirIfPresent(dir: string): Promise<SourceFile[] | null> {
   let entries: string[];
   try {
     entries = await fs.readdir(dir);

package/src/cli/edge-plan.ts

@@ -64,35 +64,24 @@ export interface MintOptions {
 }
 
 /**
- * Mint the edge from a target's introspected state to the models' declared
- * state. Pure: introspection in, plan out. Throws when the edge would hold
- * drops back — a plan must be complete to have a reachable endpoint.
+ * The predicted live fingerprint of a target AFTER the models' edge lands:
+ * declared tables on their compiled shapes exactly (that is what
+ * apply-and-verify proves), unmodeled tables and enums riding through
+ * untouched. A pending table rename's SOURCE does not ride through — the
+ * edge renames it away, and it lands as its declared new name.
+ * fingerprintState sorts internally, so merge order is irrelevant.
+ *
+ * Two callers, one meaning: minting uses it as a plan's `to` endpoint, and
+ * git-descent uses it as the declares-test — a commit DECLARES a target's
+ * live state exactly when this prediction equals the live fingerprint
+ * (the edge from the target to that commit's models is empty).
  */
-export function mintEdgePlan(
+export function predictLiveFingerprint(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
-  opts: MintOptions = {},
-): EdgePlan {
-  const statements = generateMigrationSql(models, snapshot, {
-    schema: opts.schema,
-    allowDrops: opts.allowDrops,
-    liveAuthz: contract,
-  });
-  const classified = classifyGeneratedStatements(statements);
-  if (classified.heldDrops.length > 0) {
-    throw new Error(
-      `the edge holds ${classified.heldDrops.length} destructive change(s) back — a plan must be complete. ` +
-      'Re-mint with --allow-drops to carry the destruction explicitly, or mark the contraction in the models first and drop later.',
-    );
-  }
-
-  // The predicted endpoint: declared tables land exactly on their compiled
-  // shapes (that is what apply-and-verify proves), unmodeled tables and
-  // enums ride through untouched. A pending table rename's SOURCE does not
-  // ride through — the edge renames it away, and it lands as its declared
-  // new name. fingerprintState sorts internally, so merge order is
-  // irrelevant.
+  opts: { schema?: string } = {},
+): string {
   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));
@@ -119,11 +108,37 @@ export function mintEdgePlan(
     ...declared.contract.tables,
     ...contract.tables.filter((t) => ridesThrough(t.table)),
   ];
+  return fingerprintState(mergedSnapshot, mergedAuthz).hash;
+}
+
+/**
+ * Mint the edge from a target's introspected state to the models' declared
+ * state. Pure: introspection in, plan out. Throws when the edge would hold
+ * drops back — a plan must be complete to have a reachable endpoint.
+ */
+export function mintEdgePlan(
+  models: ModelDescriptor[],
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: MintOptions = {},
+): EdgePlan {
+  const statements = generateMigrationSql(models, snapshot, {
+    schema: opts.schema,
+    allowDrops: opts.allowDrops,
+    liveAuthz: contract,
+  });
+  const classified = classifyGeneratedStatements(statements);
+  if (classified.heldDrops.length > 0) {
+    throw new Error(
+      `the edge holds ${classified.heldDrops.length} destructive change(s) back — a plan must be complete. ` +
+      'Re-mint with --allow-drops to carry the destruction explicitly, or mark the contraction in the models first and drop later.',
+    );
+  }
 
   return {
     v: PLAN_VERSION,
     fromFingerprint: fingerprintLive(snapshot, contract).hash,
-    toFingerprint: fingerprintState(mergedSnapshot, mergedAuthz).hash,
+    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema }),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
     statements,
     executable: classified.executable.length,

package/src/cli/git-descent.ts

@@ -0,0 +1,251 @@
+/**
+ * git-descent — a protected database is a git ref (brick 7 of the
+ * migration-authority design).
+ *
+ * The rule git already taught everyone: `db:apply` is a fast-forward push.
+ * The target's live fingerprint maps to the git commit whose committed
+ * models DECLARE that state; the deploying checkout must be a descendant
+ * of such a commit, or the apply refuses — "rebase first". This is what
+ * stops the multi-dev disaster case: A merges and deploys, B (branched
+ * before A merged) mints against the target — the concurrency lock passes,
+ * because B's plan was minted against current reality, but B's edge would
+ * REVERT A's merged work. The descent check catches exactly that: the
+ * commit declaring the target's state is not in B's history.
+ *
+ * The search runs over GIT ALONE, never `schema_log` (the ledger is a
+ * memoir, not a control surface — design decision 7): enumerate every
+ * historical state of the models directory across all refs, compile each
+ * unique tree, and ask whether its predicted live endpoint equals the
+ * target's live fingerprint (brick 4's merged prediction, so unmodeled
+ * brownfield tables ride through the test). A fingerprint no commit
+ * declares is a DRIFT report and an explicit operator decision — never a
+ * guess. Identity is the models-directory TREE, not the commit: a
+ * cherry-picked identical state is the same declared state.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect.js';
+import type { AuthzContract } from './authz-contract.js';
+import { fingerprintLive } from './schema-fingerprint.js';
+import { predictLiveFingerprint } from './edge-plan.js';
+
+/** Compile a models barrel on disk. The default rides the CLI's runtime (tsx). */
+export type ModelsLoader = (barrel: string) => Promise<ModelDescriptor[]>;
+
+export interface LiveState {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+}
+
+export interface DescentOptions {
+  /** Where git commands run. Default: process.cwd(). */
+  cwd?: string;
+  /** The Postgres schema the Models default to. Default: `public`. */
+  schema?: string;
+  loader?: ModelsLoader;
+  /**
+   * Where historical trees materialize. Default: a fresh temp dir under the
+   * repo's node_modules — bare imports (`@everystack/model`) must resolve
+   * from the materialized files, and node walks parent directories.
+   */
+  materializeRoot?: string;
+  /** The ref that must descend from the declaring commit. Default: HEAD. */
+  headRef?: string;
+}
+
+export type DescentVerdict =
+  /** Not a git checkout (or no commits yet) — the rule cannot be verified here. */
+  | { status: 'no-git' }
+  /** The target has no tables — nothing to protect, first apply bootstraps it. */
+  | { status: 'fresh-target' }
+  /** Fast-forward: `commit` declares the target's live state and is an ancestor of HEAD. */
+  | { status: 'ok'; commit: string; tree: string; scannedTrees: number }
+  /** The declaring commits exist but none is an ancestor of HEAD — rebase first. */
+  | { status: 'diverged'; commits: string[]; tree: string; reason: string }
+  /** No committed models state declares the live fingerprint — operator decision. */
+  | { status: 'drift'; scannedTrees: number; compileFailures: string[]; reason: string };
+
+export interface ModelTreeCandidate {
+  /** The models directory's tree oid — the identity of a declared state. */
+  tree: string;
+  /** Every enumerated commit carrying that tree, newest first. */
+  commits: string[];
+}
+
+const short = (ref: string): string => ref.slice(0, 12);
+
+function git(args: string[], cwd: string): string | null {
+  try {
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+  } catch {
+    return null;
+  }
+}
+
+const defaultLoader: ModelsLoader = async (barrel) => {
+  const mod: any = await import(pathToFileURL(path.resolve(barrel)).href);
+  const models = mod.models ?? mod.default;
+  if (!Array.isArray(models)) throw new Error(`${barrel} does not export a \`models\` array`);
+  return models;
+};
+
+/**
+ * Every historical state of the models directory across ALL refs, newest
+ * first, grouped by tree oid. `--full-history` keeps every !TREESAME commit
+ * (no simplification dropping a state introduced on a side branch); one
+ * `cat-file --batch-check` resolves all `<sha>:<dir>` specs in a single
+ * child process, in input order.
+ */
+export function enumerateModelTrees(modelsDir: string, cwd: string): ModelTreeCandidate[] {
+  const out = git(['rev-list', '--all', '--full-history', '--date-order', '--', modelsDir], cwd);
+  if (out === null) return [];
+  const shas = out.trim().split('\n').filter(Boolean);
+  if (shas.length === 0) return [];
+
+  const specs = shas.map((sha) => (modelsDir === '.' ? `${sha}^{tree}` : `${sha}:${modelsDir}`));
+  let batch: string;
+  try {
+    batch = execFileSync('git', ['cat-file', '--batch-check'], {
+      cwd,
+      input: specs.join('\n') + '\n',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).toString();
+  } catch {
+    return [];
+  }
+
+  const byTree = new Map<string, string[]>();
+  const order: string[] = [];
+  batch.trim().split('\n').forEach((line, i) => {
+    const m = line.trim().match(/^([0-9a-f]{40,64}) tree /);
+    if (!m) return; // the directory is absent at that commit, or not a tree
+    if (!byTree.has(m[1])) {
+      byTree.set(m[1], []);
+      order.push(m[1]);
+    }
+    byTree.get(m[1])!.push(shas[i]);
+  });
+  return order.map((tree) => ({ tree, commits: byTree.get(tree)! }));
+}
+
+/** Extract a tree into `dest` — `git archive` piped to tar, no shell. */
+export function materializeTree(tree: string, dest: string, cwd: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  const archive = execFileSync('git', ['archive', '--format=tar', tree], {
+    cwd,
+    maxBuffer: 512 * 1024 * 1024,
+  });
+  execFileSync('tar', ['-xf', '-', '-C', dest], { input: archive });
+}
+
+/**
+ * The fast-forward rule. Given the target's live state (already
+ * introspected — the apply path has it in hand), find the commit whose
+ * committed models declare that state and verify the checkout descends
+ * from it. Any declaring ancestor satisfies the rule; `diverged` is
+ * reported only when NO tree declaring the state has one.
+ */
+export async function verifyDescent(
+  modelsPath: string,
+  live: LiveState,
+  opts: DescentOptions = {},
+): Promise<DescentVerdict> {
+  if (live.snapshot.tables.length === 0) return { status: 'fresh-target' };
+
+  const cwd = opts.cwd ?? process.cwd();
+  const rootOut = git(['rev-parse', '--show-toplevel'], cwd);
+  if (rootOut === null) return { status: 'no-git' };
+  const repoRoot = rootOut.trim();
+  const headOut = git(['rev-parse', opts.headRef ?? 'HEAD'], cwd);
+  if (headOut === null) return { status: 'no-git' };
+  const head = headOut.trim();
+
+  // realpath the cwd side: `--show-toplevel` resolves symlinks (macOS tmpdir
+  // is /var → /private/var), and a mismatched prefix would walk the models
+  // path right out of the repo.
+  const modelsAbs = path.resolve(fs.realpathSync(cwd), modelsPath);
+  const rel = path.relative(repoRoot, modelsAbs);
+  const modelsDir = path.dirname(rel) || '.';
+  const barrel = path.basename(modelsAbs);
+
+  const candidates = enumerateModelTrees(modelsDir, repoRoot);
+  const liveFingerprint = fingerprintLive(live.snapshot, live.contract).hash;
+
+  const nodeModules = path.join(repoRoot, 'node_modules');
+  const materializeRoot = opts.materializeRoot
+    ?? fs.mkdtempSync(path.join(fs.existsSync(nodeModules) ? nodeModules : os.tmpdir(), '.everystack-descent-'));
+  const ownsRoot = !opts.materializeRoot;
+  const loader = opts.loader ?? defaultLoader;
+
+  const compileFailures: string[] = [];
+  const declaringButDiverged: ModelTreeCandidate[] = [];
+  try {
+    for (const candidate of candidates) {
+      const dest = path.join(materializeRoot, candidate.tree);
+      let predicted: string;
+      try {
+        if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
+        const models = await loader(path.join(dest, barrel));
+        predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+      } catch (err: any) {
+        compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
+        continue;
+      }
+      if (predicted !== liveFingerprint) continue;
+
+      for (const commit of candidate.commits) {
+        try {
+          execFileSync('git', ['merge-base', '--is-ancestor', commit, head], {
+            cwd: repoRoot,
+            stdio: 'ignore',
+          });
+          return {
+            status: 'ok',
+            commit,
+            tree: candidate.tree,
+            scannedTrees: candidates.indexOf(candidate) + 1,
+          };
+        } catch {
+          // not an ancestor — keep looking; an identical tree elsewhere may be
+        }
+      }
+      declaringButDiverged.push(candidate);
+    }
+  } finally {
+    if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
+  }
+
+  if (declaringButDiverged.length > 0) {
+    const commits = declaringButDiverged.flatMap((c) => c.commits);
+    return {
+      status: 'diverged',
+      commits,
+      tree: declaringButDiverged[0].tree,
+      reason:
+        `the target's state is declared by ${short(commits[0])}` +
+        (commits.length > 1 ? ` (+${commits.length - 1} more)` : '') +
+        ', which is NOT an ancestor of your checkout — your branch diverged before it. ' +
+        'Rebase onto it and re-mint, so your edge moves the target forward instead of reverting merged work.',
+    };
+  }
+
+  const failureNote = compileFailures.length > 0
+    ? ` (${compileFailures.length} historical tree(s) no longer compile and were skipped)`
+    : '';
+  return {
+    status: 'drift',
+    scannedTrees: candidates.length,
+    compileFailures,
+    reason:
+      `no committed models state declares the target's live fingerprint ${short(liveFingerprint)} — ` +
+      `scanned ${candidates.length} historical tree(s) across all refs${failureNote}. ` +
+      'Either the database was hand-edited (drift) or the declaring history was rewritten. ' +
+      'Align the models with the live database first (db:pull, commit), ' +
+      'or force with ceremony: --force-descent <snapshot-ref> --confirm.',
+  };
+}

package/src/cli/index.ts

@@ -17,6 +17,7 @@ import { dbSyncCommand } from './commands/db-sync.js';
 import { dbDiffCommand } from './commands/db-diff.js';
 import { dbPlanCommand } from './commands/db-plan.js';
 import { dbApplyCommand } from './commands/db-apply.js';
+import { dbCheckCommand } from './commands/db-check.js';
 import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
 import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
 import { consoleCommand } from './commands/console.js';
@@ -196,6 +197,9 @@ async function main() {
     case 'db:apply':
       await dbApplyCommand(flags);
       break;
+    case 'db:check':
+      await dbCheckCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -323,7 +327,8 @@ Usage:
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against db/sql, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), apply as one transaction (schema_log w/ plan_ref), verify it landed exactly on plan.to. Idempotent when already at the target state; direct connection required
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--models <barrel>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"; force needs the snapshot you took + --confirm), apply as one transaction (schema_log w/ plan_ref), verify it landed exactly on plan.to. Idempotent when already at the target state; direct connection required
+  everystack db:check          [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, db/sql parses) and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
   everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
   everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)