@everystack/cli 0.4.77 → 0.4.79

package/src/cli/git-descent.ts

@@ -85,9 +85,13 @@ export interface ModelTreeCandidate {
 
 const short = (ref: string): string => ref.slice(0, 12);
 
+/** Every git command this module runs is bounded: in a partial clone even `cat-file` and
+ *  `merge-base` can fetch lazily over the network, and a hang must become a null (refuse-closed). */
+const GIT_TIMEOUT_MS = 60_000;
+
 function git(args: string[], cwd: string): string | null {
   try {
-    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).toString();
   } catch {
     return null;
   }
@@ -100,6 +104,44 @@ const defaultLoader: ModelsLoader = async (barrel) => {
   return models;
 };
 
+/**
+ * The SQUASHED SUCCESSOR of a witness commit HEAD does not descend from: an ancestor of HEAD that
+ * carries the witness's models tree UNCHANGED (same tree oid) and is not itself an ancestor of
+ * the witness. Deploy from a PR branch, squash-merge, deploy the next stage — the ledger names the
+ * PR commit, main carries its tree under a new sha, and every line of the declaring commit is
+ * inside HEAD. Refusing that as a revert is false (consumer cutover, cli 0.4.77, 2026-09-07).
+ *
+ * The second clause is the whole safety. In an S→T→S episode the pre-episode ancestor carries S's
+ * tree too — byte-identical — and a checkout branched there must still be refused: the witness
+ * (the re-declaration of S) DESCENDS from that carrier, so the carrier is the state the episode
+ * started from, not a successor. A squash commit is never an ancestor of the branch it squashed.
+ * Tree identity is exact and cheap (`rev-parse <sha>:<dir>`, no materialization); a state-level
+ * recompile is deliberately NOT used here, because it cannot tell those two shapes apart.
+ *
+ * One carrier that IS an ancestor of the witness still counts: the one with NO models change
+ * between it and the witness. That is the app-only PR — the deploy changed no models, the
+ * witness's tree is the base tree, and `rev-list --full-history -- <dir>` lists only the base as a
+ * carrier (closing-gate review, 2026-09-07). The pre-episode carrier never qualifies: the T
+ * episode sits between it and the witness, so `rev-list carrier..witness -- <dir>` is non-empty.
+ */
+function squashedSuccessor(witness: string, head: string, modelsDir: string, repoRoot: string): string | null {
+  const spec = modelsDir === '.' ? `${witness}^{tree}` : `${witness}:${modelsDir}`;
+  const tree = git(['rev-parse', '--verify', '--quiet', spec], repoRoot)?.trim();
+  if (!tree) return null;
+  const carriers = enumerateModelTrees(modelsDir, repoRoot, { ancestorsOf: head }).find((c) => c.tree === tree)?.commits ?? [];
+  const modelsUnchangedBetween = (carrier: string): boolean => {
+    const changes = git(['rev-list', `${carrier}..${witness}`, '--', modelsDir], repoRoot);
+    return changes !== null && changes.trim() === '';
+  };
+  // Refuse-closed on BOTH git questions: an ancestry git could not answer is not "not an
+  // ancestor" (that would accept the carrier), and a rev-list that failed is not "no changes".
+  return carriers.find((c) => {
+    const anc = ancestry(c, witness, repoRoot);
+    if (anc === null) return false;
+    return !anc || modelsUnchangedBetween(c);
+  }) ?? null;
+}
+
 /**
  * Every historical state of the models directory across ALL refs, newest
  * first, grouped by tree oid. `--full-history` keeps every !TREESAME commit
@@ -132,6 +174,7 @@ export function enumerateModelTrees(
       cwd,
       input: specs.join('\n') + '\n',
       stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: GIT_TIMEOUT_MS,
     }).toString();
   } catch {
     return [];
@@ -195,8 +238,9 @@ export function materializeTree(tree: string, dest: string, cwd: string): void {
 type TreeEval =
   | { kind: 'declares' }
   | { kind: 'no' }
-  | { kind: 'compile-failed'; detail: string }
-  | { kind: 'unevaluated'; detail: string };
+  /** `detail` is the one-line record (`<tree> (at <commit>): <error>`); `error` is the bare cause. */
+  | { kind: 'compile-failed'; detail: string; error: string }
+  | { kind: 'unevaluated'; detail: string; error: string };
 
 interface EvalContext {
   repoRoot: string;
@@ -225,7 +269,8 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
       fs.rmSync(dest, { recursive: true, force: true });
       ctx.materialize(candidate.tree, dest, ctx.repoRoot);
     } catch (err: any) {
-      return { kind: 'unevaluated', detail: `${where}: could not extract — ${firstLine(err.message)}` };
+      const error = `could not extract — ${firstLine(err.message)}`;
+      return { kind: 'unevaluated', detail: `${where}: ${error}`, error };
     }
   }
 
@@ -233,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' };
 
@@ -259,8 +305,100 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
     }
     return declares ? { kind: 'declares' } : { kind: 'no' };
   } catch (err: any) {
-    return { kind: 'compile-failed', detail: `${where}: ${firstLine(err.message)}` };
+    const error = firstLine(err.message);
+    return { kind: 'compile-failed', detail: `${where}: ${error}`, error };
+  }
+}
+
+/** One tree the walk could not read, with where it sits in history — the refusal names it. */
+interface UnreadableTree {
+  candidate: ModelTreeCandidate;
+  /** Carried by a commit HEAD descends from — no ref prune removes it. */
+  ancestor: boolean;
+  error: string;
+}
+
+/** The git verb that removes one ref, or null for a ref shape we do not prescribe deleting. */
+export function pruneCommand(ref: string): string | null {
+  const head = ref.match(/^refs\/heads\/(.+)$/);
+  if (head) return `git branch -D ${head[1]}`;
+  const remote = ref.match(/^refs\/remotes\/([^/]+)\/(.+)$/);
+  if (remote) return `git push ${remote[1]} --delete ${remote[2]}`;
+  const tag = ref.match(/^refs\/tags\/(.+)$/);
+  if (tag) return `git tag -d ${tag[1]}`;
+  return null;
+}
+
+/**
+ * The unreadable-tree refusal, built from what the walk KNOWS: each tree, the refs that carry it,
+ * whether HEAD descends from it, and what the target's ledger says about who deployed what.
+ *
+ * Consumer cutover, cli 0.4.77 (2026-09-07): four August trees carried only by one backup branch
+ * on origin refused a production apply, and the message led with "upgrade/pin the CLI that last
+ * deployed this state" — on a database no CLI had ever deployed (schema_log was empty). The
+ * operator reconstructed the carrying ref with `git rev-list --all -- db/models` and a per-tree
+ * grep. Every fact in that reconstruction was already in this function's hands.
+ *
+ * The verdict does not change here; only the account of it. A tree we cannot read may still
+ * describe live, so the walk stays refuse-closed; the ledger is a memoir and never decides
+ * (decision 7). What the ledger DOES decide is which fix comes first: with no recorded apply,
+ * no CLI deployed these trees and "pin the CLI" is false, so bundle + prune leads; with one, pin
+ * the CLI only when the recorded commit is itself among the unreadable trees.
+ */
+function unreadableRunbook(
+  unreadable: readonly UnreadableTree[],
+  lastApplied: DescentLedgerRow | undefined,
+  probe: GitLineageProbe,
+): string {
+  // Bounded on both axes, because this reason is RECORDED in schema_log and each ref lookup is a
+  // full ref walk: at most MAX_TREES trees are named, and a tree's refs are the union over its
+  // first MAX_COMMITS carrying commits (a tree is often carried by several commits on several
+  // branches — naming one commit's refs under-named the prune; closing-gate review, 2026-09-07).
+  const MAX_TREES = 10;
+  const MAX_COMMITS = 5;
+  const listed = unreadable.slice(0, MAX_TREES);
+  const refsOf = new Map<string, string[]>();
+  for (const u of listed) {
+    const refs = new Set<string>();
+    for (const commit of u.candidate.commits.slice(0, MAX_COMMITS)) {
+      for (const ref of probe.refsContaining(commit)) if (ref !== 'refs/stash') refs.add(ref);
+    }
+    refsOf.set(u.candidate.tree, [...refs].sort());
+  }
+  const lines = listed.map((u) => {
+    const refs = refsOf.get(u.candidate.tree)!;
+    const carried = refs.length === 0
+      ? 'carried by no ref'
+      : `carried by ${refs.slice(0, 3).join(', ')}${refs.length > 3 ? ` and ${refs.length - 3} more` : ''}`;
+    const where = u.ancestor ? "on your checkout's own history" : 'not an ancestor of your checkout';
+    return `  ${short(u.candidate.tree)} at ${short(u.candidate.commits[0])} — ${carried} (${where}) — ${scrubPaths(u.error)}`;
+  });
+  if (unreadable.length > listed.length) {
+    lines.push(`  … and ${unreadable.length - listed.length} more unreadable tree(s) not listed — their refs are not in the prune list below; re-run after pruning to see them`);
+  }
+
+  const prunable = listed.filter((u) => !u.ancestor);
+  const ancestors = unreadable.filter((u) => u.ancestor);
+  const pruneRefs = [...new Set(prunable.flatMap((u) => refsOf.get(u.candidate.tree)!))];
+  const pruneCmds = pruneRefs.map(pruneCommand).filter((c): c is string => c !== null);
+  const prune = pruneRefs.length === 0
+    ? ''
+    : `Keep them if you want (git bundle create unreadable-trees.bundle ${pruneRefs.join(' ')}), then prune: ${pruneCmds.join('; ')}; then re-run.`;
+  const rewrite = ancestors.length === 0
+    ? ''
+    : `${ancestors.length === unreadable.length ? 'These trees are' : `${ancestors.length} of them ${ancestors.length === 1 ? 'is' : 'are'}`} on your checkout's own history, which no ref prune removes; the walk needs every ancestor tree readable. Rewriting that history is the git-native remedy — keep it first (git bundle create everything.bundle --all).`;
+
+  let lead: string;
+  if (!lastApplied) {
+    lead = 'No everystack apply is recorded on this target, so no CLI deployed these trees.';
+  } else {
+    const at = lastApplied.gitRef ? `at ${short(lastApplied.gitRef)} ` : '';
+    const among = lastApplied.gitRef !== null && unreadable.some((u) => u.candidate.commits.includes(lastApplied.gitRef!));
+    lead = `everystack last applied here ${at}on ${shortDate(lastApplied.appliedAt)}.`
+      + (among ? ' That commit is among the unreadable trees — pin the CLI that applied it (the version in that commit\'s lockfile) and re-run.' : '');
+    if (among) return `${lines.join('\n')}\n${lead}`;
   }
+  return `${lines.join('\n')}\n${[lead, prune, rewrite].filter(Boolean).join(' ')}`;
 }
 
 /**
@@ -296,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);
@@ -331,17 +469,32 @@ function resolveRepoContext(
 /** `git cat-file -e <ref>^{commit}` — is the commit present in THIS clone (not a shallow gap)? */
 function commitPresent(ref: string, cwd: string): boolean {
   try {
-    execFileSync('git', ['cat-file', '-e', `${ref}^{commit}`], { cwd, stdio: 'ignore' });
+    execFileSync('git', ['cat-file', '-e', `${ref}^{commit}`], { cwd, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
     return true;
   } catch {
     return false;
   }
 }
 
-/** `git merge-base --is-ancestor <ancestor> <head>` — does HEAD descend from the commit? */
+/**
+ * `git merge-base --is-ancestor`, three-valued: true / false / null when git could not answer
+ * (a timeout, a missing object, a broken repo). Every caller whose SAFE answer is "not an
+ * ancestor" may use {@link isAncestor}; a caller whose safe answer is the OTHER way — the squash
+ * guard accepts a carrier that is NOT an ancestor of the witness — must read null as "refuse".
+ */
+function ancestry(ancestor: string, head: string, cwd: string): boolean | null {
+  try {
+    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+    return true;
+  } catch (err: any) {
+    return err?.status === 1 ? false : null; // exit 1 = "not an ancestor"; anything else = could not tell
+  }
+}
+
+/** `git merge-base --is-ancestor <ancestor> <head>` — does HEAD descend from the commit? False when git cannot tell. */
 function isAncestor(ancestor: string, head: string, cwd: string): boolean {
   try {
-    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore' });
+    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
     return true;
   } catch {
     return false;
@@ -378,6 +531,11 @@ export interface GitLineageProbe {
   remotes(): string[] | null;
   /** `git ls-remote --heads --tags <remote>` advertised tip shas; null when the remote is unreachable. */
   lsRemote(remote: string): string[] | null;
+  /**
+   * Why the last `lsRemote(remote)` returned null — git's own first stderr line, paths scrubbed —
+   * or null when nothing was captured. Optional: a probe without it still names the remote.
+   */
+  lsRemoteError?(remote: string): string | null;
   /**
    * Does this object peel to a commit (`<sha>^{commit}`)? `null` when the object is absent from
    * the clone. An advertised tip that is present but is a tag on a blob or tree can carry no
@@ -387,9 +545,41 @@ export interface GitLineageProbe {
   peelsToCommit?(sha: string): boolean | null;
 }
 
+/**
+ * The runbook for a remote `git ls-remote` could not read. Three things it must do, each learned
+ * from a consumer's production cutover (cli 0.4.77, 2026-09-07) where the remote was named `db`
+ * and "could not read db" was read as the database being unreachable: name the remote AS a git
+ * remote, carry git's own error so the cause is on the surface, and name the verb that clears a
+ * dead one — `git remote remove` — next to the one that fixes a live one.
+ */
+function unreadableRemote(remote: string, git: GitLineageProbe): string {
+  const err = git.lsRemoteError?.(remote);
+  return `git remote '${remote}' could not be read: \`git ls-remote --heads --tags ${remote}\` failed${err ? ` — ${err}` : ''}. `
+    + `Fix the remote or remove it (git remote remove ${remote}), then re-run.`;
+}
+
+/**
+ * git's stderr, reduced to what a refusal may carry: the first non-empty line, absolute paths
+ * and file:// URLs replaced by `<path>` (the reason is recorded, and a home directory is not
+ * part of the diagnosis), capped so a chatty transport cannot flood the surface.
+ */
+export function firstErrorLine(stderr: string): string | null {
+  const line = stderr.split('\n').map((l) => l.trim()).find(Boolean);
+  if (!line) return null;
+  return scrubPaths(line).slice(0, 200);
+}
+
+/** Absolute paths and file:// URLs replaced by `<path>` — a recorded reason never carries a home directory. */
+export function scrubPaths(s: string): string {
+  return s
+    .replace(/file:\/\/\S+/g, 'file://<path>')
+    .replace(/(^|[\s'"(])\/[^\s'"()]+/g, '$1<path>');
+}
+
 export type LineageProof =
   | { proven: true; subcase: 'revert-unreachable' | 'unknown-commit-proven-absent' }
-  | { proven: false; kind: 'shallow' | 'partial' | 'reachable' | 'behind-remote' | 'remote-unreachable' | 'remote-list-failed' | 'no-remotes'; reason: string };
+  /** `ref` is set for `reachable`: the ref (or `HEAD`, or a remote name) that still holds the commit. */
+  | { proven: false; kind: 'shallow' | 'partial' | 'reachable' | 'behind-remote' | 'remote-unreachable' | 'remote-list-failed' | 'no-remotes'; reason: string; ref?: string };
 
 /**
  * Prove the declaring commit `sha` is reachable from NO ref, local or remote. Refuse-closed: every
@@ -410,10 +600,10 @@ export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProo
   if (present) {
     const containing = git.refsContaining(sha);
     if (containing.length > 0) {
-      return { proven: false, kind: 'reachable', reason: `commit ${short(sha)} is still reachable (${containing[0]}) — revert it in git and re-plan instead of attesting it lost.` };
+      return { proven: false, kind: 'reachable', ref: containing[0], reason: `commit ${short(sha)} is still reachable (${containing[0]}) — revert it in git and re-plan instead of attesting it lost.` };
     }
     if (git.isAncestorOf(sha, 'HEAD')) {
-      return { proven: false, kind: 'reachable', reason: `commit ${short(sha)} is still reachable (an ancestor of HEAD) — revert it in git and re-plan instead of attesting it lost.` };
+      return { proven: false, kind: 'reachable', ref: 'HEAD', reason: `commit ${short(sha)} is still reachable (an ancestor of HEAD) — revert it in git and re-plan instead of attesting it lost.` };
     }
   }
 
@@ -430,14 +620,14 @@ export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProo
   for (const remote of remotes) {
     const tips = git.lsRemote(remote);
     if (tips === null) {
-      return { proven: false, kind: 'remote-unreachable', reason: `could not read ${remote} to confirm ${short(sha)} is not on it — check connectivity and retry, or fetch the remote first.` };
+      return { proven: false, kind: 'remote-unreachable', reason: `cannot confirm ${short(sha)} is not on ${remote}: ${unreadableRemote(remote, git)}` };
     }
     for (const tip of tips) {
       if (!git.objectExists(tip)) {
         return { proven: false, kind: 'behind-remote', reason: `this clone is behind ${remote} (it advertises ${short(tip)}, which you do not have) — fetch it first; the declaring commit may still be on the remote.` };
       }
       if (present && git.isAncestorOf(sha, tip)) {
-        return { proven: false, kind: 'reachable', reason: `commit ${short(sha)} is still reachable (on ${remote}) — revert it in git and re-plan instead of attesting it lost.` };
+        return { proven: false, kind: 'reachable', ref: remote, reason: `commit ${short(sha)} is still reachable (on ${remote}) — revert it in git and re-plan instead of attesting it lost.` };
       }
     }
   }
@@ -464,9 +654,12 @@ export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProo
 
 /** The real probe: each method is one git command run in `cwd`. */
 export function realLineageProbe(cwd: string): GitLineageProbe {
+  const lsRemoteErrors = new Map<string, string>();
+  // A hung remote must become a refusal, not a hang: every probe command is bounded. A timeout
+  // throws, so it reads as null — unreachable — and the proof refuses closed as it would offline.
   const run = (args: string[]): string | null => {
     try {
-      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).toString();
     } catch {
       return null;
     }
@@ -489,10 +682,20 @@ export function realLineageProbe(cwd: string): GitLineageProbe {
       return out === null ? null : out.split('\n').map((l) => l.trim()).filter(Boolean);
     },
     lsRemote: (remote) => {
-      const out = run(['ls-remote', '--heads', '--tags', remote]);
-      if (out === null) return null;
+      // stderr is KEPT here, unlike `run`: the refusal this feeds must say why git could not read
+      // the remote, or "could not read db" is the database to whoever reads it.
+      let out: string;
+      try {
+        out = execFileSync('git', ['ls-remote', '--heads', '--tags', remote], { cwd, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS }).toString();
+      } catch (e) {
+        const stderr = (e as { stderr?: Buffer | string }).stderr?.toString() ?? '';
+        lsRemoteErrors.set(remote, firstErrorLine(stderr) ?? firstErrorLine((e as Error).message ?? '') ?? 'no error output');
+        return null;
+      }
+      lsRemoteErrors.delete(remote);
       return out.split('\n').map((l) => l.split('\t')[0]?.trim()).filter((s): s is string => !!s && s.length >= 7);
     },
+    lsRemoteError: (remote) => lsRemoteErrors.get(remote) ?? null,
     peelsToCommit: (sha) => {
       if (!commitPresent(sha, cwd) && run(['cat-file', '-e', sha]) === null) return null; // absent
       return run(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]) !== null;
@@ -550,8 +753,11 @@ export type ProveVerdict =
   | { status: 'fresh-target' }
   /** Not a git checkout — the rule cannot be verified here. */
   | { status: 'no-git' }
-  /** Fast-forward proven — via a ledger witness or an ancestor recompile. */
-  | { status: 'proven'; via: 'ledger' | 'recompile'; commit: string }
+  /** Fast-forward proven — via a ledger witness, its squashed successor, or an ancestor recompile.
+   *  For `squash`, `commit` is the CARRIER (an ancestor of HEAD holding the deploying commit's
+   *  models tree) and `witness` is the deploying commit the ledger names, which HEAD does not
+   *  descend from — both are surfaced and the weaker proof is recorded in schema_log. */
+  | { status: 'proven'; via: 'ledger' | 'squash' | 'recompile'; commit: string; witness?: string }
   /** The newest ledger witness is NOT an ancestor of HEAD — applying would revert merged work. */
   | { status: 'revert'; commit: string; appliedAt: string; reason: string }
   /** The witness names a commit this clone does not have (shallow) — fetch, do not guess. */
@@ -625,7 +831,7 @@ export function proveCloneCurrent(git: GitLineageProbe): { current: true } | { c
   for (const remote of remotes) {
     const tips = git.lsRemote(remote);
     if (tips === null) {
-      return { current: false, reason: `could not read ${remote} to confirm the clone is current — check connectivity and retry, or fetch the remote first.` };
+      return { current: false, reason: `cannot confirm the clone is current: ${unreadableRemote(remote, git)}` };
     }
     for (const tip of tips) {
       // refs/stash is excluded from the scan (enumerateModelTrees), so a tip contained ONLY by a
@@ -705,14 +911,17 @@ export async function proveDescent(
     if (isAncestor(r.gitRef, head, repoRoot)) {
       return { status: 'proven', via: 'ledger', commit: r.gitRef };
     }
+    const squash = squashedSuccessor(r.gitRef, head, modelsDir, repoRoot);
+    if (squash) return { status: 'proven', via: 'squash', commit: squash, witness: r.gitRef };
     return {
       status: 'revert',
       commit: r.gitRef,
       appliedAt: r.appliedAt,
       reason:
         `your checkout is behind the branch that last deployed this state — commit ${short(r.gitRef)} ` +
-        `(applied ${shortDate(r.appliedAt)}) is NOT an ancestor of HEAD. Applying now would revert ` +
-        'that merged work. Pull the deploying branch, rebase onto it, and re-plan.',
+        `(applied ${shortDate(r.appliedAt)}) is NOT an ancestor of HEAD, and no ancestor of HEAD carries ` +
+        'its models tree as a squashed successor. Applying now would revert that merged work. ' +
+        'Pull the deploying branch, rebase onto it, and re-plan.',
     };
   }
 
@@ -751,37 +960,39 @@ export async function proveDescent(
 
   const compileFailures: string[] = [];
   const unevaluated: string[] = [];
+  const unreadable: UnreadableTree[] = [];
+  const probe = opts.probe ?? realLineageProbe(repoRoot);
+  const lastApplied = ordered.find((r) => isAppliedOutcome(r.outcome));
   const unverifiable = (scope: string, scanned: number): ProveVerdict => {
     const notes: string[] = [];
     if (compileFailures.length > 0) notes.push(`${compileFailures.length} would not compile under this CLI`);
     if (unevaluated.length > 0) notes.push(`${unevaluated.length} could not be extracted`);
-    // Show the FIRST actual error: "Cannot find module '@everystack/model'" is a resolution
-    // problem with a different fix than "an older tree that no longer builds", and a message that
-    // hides it sends the operator to upgrade a CLI that is not the cause.
-    const first = compileFailures[0] ?? unevaluated[0];
+    // Every unreadable tree is NAMED — with the refs that carry it, its place in history, and its
+    // own error ("Cannot find module '@everystack/model'" is a resolution problem with a different
+    // fix than "an older tree that no longer builds") — and the runbook leads with the fix the
+    // ledger supports. See unreadableRunbook for the incident that shaped this.
     return {
       status: 'unverifiable',
       reason:
         `cannot verify the fast-forward rule — of ${scanned} ${scope} model state(s), ` +
         `${notes.join(' and ')}, and none of the readable ones declares the live state. This is a ` +
         'limit of THIS run (an older tree that no longer builds, or a failed extraction), not ' +
-        'evidence about the database — it is NOT drift. Upgrade/pin the CLI that last deployed ' +
-        `this state, or prune the branch that carries the unreadable tree, and re-run.${first ? ` First failure: ${first}` : ''}`,
+        `evidence about the database — it is NOT drift. Unreadable:\n${unreadableRunbook(unreadable, lastApplied, probe)}`,
       unevaluated,
       compileFailures,
     };
   };
+  const record = (candidate: ModelTreeCandidate, result: Extract<TreeEval, { error: string }>, ancestor: boolean): void => {
+    (result.kind === 'unevaluated' ? unevaluated : compileFailures).push(result.detail);
+    unreadable.push({ candidate, ancestor, error: result.error });
+  };
 
   let others: ModelTreeCandidate[] = [];
   try {
     for (const candidate of candidates) {
       const result = await evaluateTree(candidate, live, evalCtx);
-      if (result.kind === 'unevaluated') {
-        unevaluated.push(result.detail);
-        continue;
-      }
-      if (result.kind === 'compile-failed') {
-        compileFailures.push(result.detail);
+      if (result.kind === 'unevaluated' || result.kind === 'compile-failed') {
+        record(candidate, result, true);
         continue;
       }
       if (result.kind === 'no') continue;
@@ -824,7 +1035,7 @@ export async function proveDescent(
     }
     // Currency BEFORE the all-refs compile: a clone that is shallow, partial, or behind a remote
     // is told to fetch now, not after paying for every historical tree on every ref.
-    const currency = proveCloneCurrent(opts.probe ?? realLineageProbe(repoRoot));
+    const currency = proveCloneCurrent(probe);
     if (!currency.current) {
       return {
         status: 'unverifiable',
@@ -838,12 +1049,8 @@ export async function proveDescent(
     others = all.filter((c) => !seen.has(c.tree));
     for (const candidate of others) {
       const result = await evaluateTree(candidate, live, evalCtx);
-      if (result.kind === 'unevaluated') {
-        unevaluated.push(result.detail);
-        continue;
-      }
-      if (result.kind === 'compile-failed') {
-        compileFailures.push(result.detail);
+      if (result.kind === 'unevaluated' || result.kind === 'compile-failed') {
+        record(candidate, result, false);
         continue;
       }
       if (result.kind === 'no') continue;
@@ -873,7 +1080,6 @@ export async function proveDescent(
   // this is the first adoption of a database everystack never wrote. A dirty-worktree apply is
   // still an apply — its git_ref declares nothing (Phase A skips it as a witness), so the state
   // it produced was never committed anywhere; the origin says so.
-  const lastApplied = ordered.find((r) => isAppliedOutcome(r.outcome));
   const origin: DriftOrigin = lastApplied
     ? { kind: 'hand-edited', commit: lastApplied.gitRef, appliedAt: lastApplied.appliedAt, ...(lastApplied.dirty ? { dirty: true } : {}) }
     : { kind: 'never-declared' };
@@ -929,9 +1135,44 @@ export function attestationNote(a: { commit: string; subcase: string }): string
   return `descent-attested-lineage-lost (${short(a.commit)}, ${a.subcase})`;
 }
 
+/** The recorded note for a squash proof — goes in the apply row's schema_log outcome. */
+export function squashNote(carrier: string, witness: string): string {
+  return `descent: squash-successor (${short(carrier)} carries the models tree of ${short(witness)}, which HEAD does not descend from)`;
+}
+
+/**
+ * Does the operator's attestation name this commit? Exact, or a hex prefix of at least 7
+ * characters — compared against the ONE commit the refusal named, so there is nothing for a
+ * prefix to be ambiguous with. The refusal prints the 12-character form, and an operator who
+ * pastes it back is naming that commit. A strict string compare refused
+ * "42a3b97af246 does not match (42a3b97af246)" — two identical strings — because the ledger holds
+ * 40 characters and the refusal printed 12 (consumer cutover, cli 0.4.77, 2026-09-07).
+ */
+export function attestsCommit(attestation: string, commit: string): boolean {
+  const a = attestation.trim().toLowerCase();
+  if (a === commit.toLowerCase()) return true;
+  return a.length >= 7 && /^[0-9a-f]+$/.test(a) && commit.toLowerCase().startsWith(a);
+}
+
+/**
+ * Resolve an attestation through git before it is compared: a prefix, a tag, a branch, or a
+ * `HEAD~n` becomes the full sha. A value git cannot resolve (the commit is absent from this clone —
+ * the `unknown-commit-proven-absent` subcase, or a typo) passes through unchanged so the prefix
+ * compare above still gets its chance and a mismatch names what was given.
+ */
+export function resolveAttestation(attestation: string, cwd: string): string {
+  const full = git(['rev-parse', '--verify', '--quiet', `${attestation.trim()}^{commit}`], cwd)?.trim();
+  return full && /^[0-9a-f]{40,64}$/.test(full) ? full : attestation;
+}
+
 export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyContext): DescentApplyDecision {
   switch (verdict.status) {
     case 'proven':
+      // A squash proof rests on models-tree identity, not ancestry of the deploying commit — the
+      // record says so, exactly as an honoured attestation and a proven drift leave their trace.
+      return verdict.via === 'squash' && verdict.witness
+        ? { ok: true, note: squashNote(verdict.commit, verdict.witness) }
+        : { ok: true };
     case 'fresh-target':
       return { ok: true };
 
@@ -969,8 +1210,8 @@ export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyConte
       // construction, so the lineage-lost attestation can never be honoured here — the proof refuses
       // it as reachable. The escape is git-native: merge or rebase.
       if (!ctx.attestation) return { ok: false, reason: verdict.reason };
-      if (ctx.attestation !== verdict.commit) {
-        return { ok: false, reason: `--attest-lineage-lost ${short(ctx.attestation)} does not match the commit that declares this state (${short(verdict.commit)}) — drop the flag; that commit is reachable, so merge or rebase instead.` };
+      if (!attestsCommit(ctx.attestation, verdict.commit)) {
+        return { ok: false, reason: `--attest-lineage-lost ${ctx.attestation} does not match the commit that declares this state (${verdict.commit}) — drop the flag; that commit is reachable, so merge or rebase instead.` };
       }
       const proof = ctx.proveLineage(verdict.commit);
       return proof.proven
@@ -988,10 +1229,11 @@ export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyConte
           reason: `${verdict.reason} If that commit is gone for good (its branch was rebased away or deleted), attest it: --attest-lineage-lost ${short(verdict.commit)}${ctx.destructive ? ' --confirm' : ''}.`,
         };
       }
-      if (ctx.attestation !== verdict.commit) {
+      if (!attestsCommit(ctx.attestation, verdict.commit)) {
+        // Both in FULL: a short form on both sides once printed two identical strings as a mismatch.
         return {
           ok: false,
-          reason: `--attest-lineage-lost ${short(ctx.attestation)} does not match the commit that declared this state (${short(verdict.commit)}) — attest the exact commit the refusal names, or drop the flag.`,
+          reason: `--attest-lineage-lost ${ctx.attestation} does not match the commit that declared this state (${verdict.commit}) — attest the exact commit the refusal names, or drop the flag.`,
         };
       }
       const proof = ctx.proveLineage(verdict.commit);

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.