@everystack/cli 0.4.69 → 0.4.70

package/src/cli/git-descent.ts

@@ -31,7 +31,7 @@ import { pathToFileURL } from 'node:url';
 import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect';
 import type { AuthzContract } from './authz-contract';
-import { fingerprintLive } from './schema-fingerprint';
+import { fingerprintLive, fingerprintLiveAtVersion, type CanonHasher } from './schema-fingerprint';
 import { predictLiveFingerprint, governedLiveFingerprint } from './edge-plan';
 import { governedRolesForModels } from './schema-fingerprint';
 
@@ -67,26 +67,6 @@ export interface DescentOptions {
   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 }
-  /**
-   * One or more trees could not be EVALUATED at all — extraction or IO failed, so "no tree
-   * declares this state" is not a conclusion we are entitled to draw. Distinct from `drift`
-   * because the operator's next move is different: retry, not `db:pull`.
-   *
-   * `unevaluated` names the trees and why each failed.
-   */
-  | { status: 'indeterminate'; scannedTrees: number; unevaluated: string[]; reason: string };
-
 export interface ModelTreeCandidate {
   /** The models directory's tree oid — the identity of a declared state. */
   tree: string;
@@ -118,8 +98,17 @@ const defaultLoader: ModelsLoader = async (barrel) => {
  * `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);
+export function enumerateModelTrees(
+  modelsDir: string,
+  cwd: string,
+  opts: { ancestorsOf?: string } = {},
+): ModelTreeCandidate[] {
+  // Default: every historical state across ALL refs (the whole-history search). With
+  // `ancestorsOf`, restrict to the ancestors of one commit — the fallback proof only ever
+  // considers trees the checkout descends from, so a diverged side branch is not even a
+  // candidate (a non-ancestor declaring commit is the ledger's REVERT case, not recompile's).
+  const range = opts.ancestorsOf ? [opts.ancestorsOf] : ['--all'];
+  const out = git(['rev-list', ...range, '--full-history', '--date-order', '--', modelsDir], cwd);
   if (out === null) return [];
   const shas = out.trim().split('\n').filter(Boolean);
   if (shas.length === 0) return [];
@@ -159,9 +148,9 @@ export function enumerateModelTrees(modelsDir: string, cwd: string): ModelTreeCa
  * does. Measured 2026-08-11 on a full-repo run: `spawnSync tar EPIPE`, recorded against a
  * historical tree, twice in four runs.
  *
- * It failed badly, not loudly: `verifyDescent` recorded it as a COMPILE failure and returned
- * `drift`, telling the operator their database had been hand-edited. See the `indeterminate`
- * verdict for that half of the fix; this is the half that stops the failure happening.
+ * It failed badly, not loudly: the descent recompile recorded it as a COMPILE failure and
+ * returned `drift`, telling the operator their database had been hand-edited. See the
+ * `unverifiable` verdict for that half of the fix; this is the half that stops the failure happening.
  *
  * `git archive -o` writes the archive itself and `tar -xf <file>` reads it — two independent
  * processes, no shared pipe, no backpressure to lose, and no multi-hundred-MB buffer through
@@ -180,164 +169,558 @@ export function materializeTree(tree: string, dest: string, cwd: string): void {
 }
 
 /**
- * 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.
+ * TWO KINDS OF FAILURE, and conflating them is what made this path lie once.
+ *
+ *  - `declares`: this tree's committed models DECLARE the live state (or not) — a real,
+ *    deterministic property of the tree.
+ *  - `compile-failed`: the tree no longer builds against today's @everystack/model. Also a
+ *    real property of the tree; skipping it is correct, but it means the search was not able
+ *    to read that state.
+ *  - `unevaluated`: extraction (git archive / tar) failed. This says NOTHING about the tree —
+ *    we never saw it. Reporting it as drift told operators their database was hand-edited; the
+ *    real cause was a lost pipe under load. It must never harden into a drift conclusion.
  */
-export async function verifyDescent(
-  modelsPath: string,
-  live: LiveState,
-  opts: DescentOptions = {},
-): Promise<DescentVerdict> {
-  if (live.snapshot.tables.length === 0) return { status: 'fresh-target' };
+type TreeEval =
+  | { kind: 'declares' }
+  | { kind: 'no' }
+  | { kind: 'compile-failed'; detail: string }
+  | { kind: 'unevaluated'; detail: string };
+
+interface EvalContext {
+  repoRoot: string;
+  materializeRoot: string;
+  barrel: string;
+  loader: ModelsLoader;
+  materialize: (tree: string, dest: string, cwd: string) => void;
+  schema?: string;
+}
 
+/**
+ * Materialize a candidate tree (one retry — extraction can fail transiently under load) and
+ * ask whether its committed models declare the live state. The declares-test is GOVERNED on
+ * both sides, per candidate: the commit's models define the governed set, and the live hash is
+ * filtered through the SAME set — comparing a governed prediction against a raw live hash can
+ * never match on a brownfield target with foreign roles.
+ */
+async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx: EvalContext): Promise<TreeEval> {
+  const dest = path.join(ctx.materializeRoot, candidate.tree);
+  const where = `${short(candidate.tree)} (at ${short(candidate.commits[0])})`;
+
+  try {
+    if (!fs.existsSync(dest)) ctx.materialize(candidate.tree, dest, ctx.repoRoot);
+  } catch {
+    try {
+      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 — ${err.message}` };
+    }
+  }
+
+  const evaluate = async (): Promise<boolean> => {
+    const models = await ctx.loader(path.join(dest, ctx.barrel));
+    const governedRoles = governedRolesForModels(models);
+    const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: ctx.schema, governedRoles });
+    return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
+  };
+  try {
+    let declares: boolean;
+    try {
+      declares = await evaluate();
+    } catch {
+      declares = await evaluate();
+    }
+    return declares ? { kind: 'declares' } : { kind: 'no' };
+  } catch (err: any) {
+    return { kind: 'compile-failed', detail: `${where}: ${err.message}` };
+  }
+}
+
+/** Resolve the repo root, HEAD, and the models directory/barrel split — shared setup. */
+function resolveRepoContext(
+  modelsPath: string,
+  opts: DescentOptions,
+): { repoRoot: string; head: string; modelsDir: string; barrel: string } | null {
   const cwd = opts.cwd ?? process.cwd();
   const rootOut = git(['rev-parse', '--show-toplevel'], cwd);
-  if (rootOut === null) return { status: 'no-git' };
+  if (rootOut === null) return null;
   const repoRoot = rootOut.trim();
   const headOut = git(['rev-parse', opts.headRef ?? 'HEAD'], cwd);
-  if (headOut === null) return { status: 'no-git' };
+  if (headOut === null) return null;
   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.
+  // 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);
+  return { repoRoot, head, modelsDir: path.dirname(rel) || '.', barrel: path.basename(modelsAbs) };
+}
+
+/** `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' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `git merge-base --is-ancestor <ancestor> <head>` — does HEAD descend from the commit? */
+function isAncestor(ancestor: string, head: string, cwd: string): boolean {
+  try {
+    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lineage proof — is a declaring commit UNREACHABLE from every ref?
+//
+// This is the ONE case the `--attest-lineage-lost` attestation covers (Fable-adjudicated
+// 2026-08-26, replacing the retired `--force-descent`): the commit that declared the target's live
+// state is gone from every ref (a since-rebased or deleted branch), so no `git revert` can reach it
+// and no re-plan can express it. Everything else has a flagless git-native escape, so the attestation
+// must be structurally INERT there — this proof is what makes it refusable when the operator is merely
+// stale. "Unreachable" is PROVEN, never assumed: a shallow/partial clone, or a clone behind any
+// remote, cannot tell "gone" from "not fetched", so those refuse the attestation rather than honour it.
+// ---------------------------------------------------------------------------
+
+/** The git operations the lineage proof needs, injected so the proof logic is testable without a repo. */
+export interface GitLineageProbe {
+  /** `git rev-parse --is-shallow-repository` === true. */
+  isShallow(): boolean;
+  /** A partial clone (a promisor remote / `extensions.partialClone`), where absence is not proof. */
+  isPartial(): boolean;
+  /** `git cat-file -e <sha>^{commit}` — is the commit object in this repo at all? */
+  objectExists(sha: string): boolean;
+  /** `git for-each-ref --contains=<sha>` over ALL of refs/ — the full ref names that contain it. */
+  refsContaining(sha: string): string[];
+  /** `git merge-base --is-ancestor <sha> <committish>` — is sha an ancestor of committish? */
+  isAncestorOf(sha: string, committish: string): boolean;
+  /** `git remote` — configured remote names; null when the command itself failed (not an empty
+   *  list). Null must refuse: a git failure that read as "no remotes" would skip the remote-currency
+   *  loop and let a locally-absent commit prove "gone", falling OPEN on the attestation. */
+  remotes(): string[] | null;
+  /** `git ls-remote --heads --tags <remote>` advertised tip shas; null when the remote is unreachable. */
+  lsRemote(remote: string): string[] | null;
+}
+
+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 };
+
+/**
+ * Prove the declaring commit `sha` is reachable from NO ref, local or remote. Refuse-closed: every
+ * path that cannot PROVE "gone" returns `proven: false` with the flagless escape the operator should
+ * take instead. Only two paths prove it: the commit is present but in no local ref and no advertised
+ * remote tip's ancestry (a rebased-away branch), or it is absent from a full, remote-current clone
+ * (which could not be true if any reachable ref still held it).
+ */
+export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProof {
+  if (git.isShallow()) {
+    return { proven: false, kind: 'shallow', reason: `this is a shallow clone, so ${short(sha)} being absent is not proof it is gone — unshallow first (git fetch --unshallow), then re-run.` };
+  }
+  if (git.isPartial()) {
+    return { proven: false, kind: 'partial', reason: `this is a partial clone, so objects can be fetched lazily and absence is not proof — fetch the full history, then re-run.` };
+  }
+
+  const present = git.objectExists(sha);
+  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.` };
+    }
+    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.` };
+    }
+  }
+
+  // Remote currency — the guard against mistaking "not fetched" for "gone". Every advertised tip must
+  // already be present locally; only then is a full clone's object graph complete enough to prove
+  // absence, and only then can we test sha against each remote branch's ancestry.
+  const remotes = git.remotes();
+  if (remotes === null) {
+    // The command that lists remotes failed. We cannot tell a remote-free repo from an unreadable one,
+    // so we cannot prove the remote-currency precondition — refuse rather than skip the loop (skipping
+    // it would let a locally-absent commit prove "gone", falling open on the attestation).
+    return { proven: false, kind: 'remote-list-failed', reason: `could not list this repo's git remotes to confirm ${short(sha)} is not on any of them — retry, or fetch the remotes first.` };
+  }
+  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.` };
+    }
+    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.` };
+      }
+    }
+  }
+
+  // A commit PRESENT in the clone but reachable from no ref, and on no remote's ancestry, is
+  // genuinely lost here — no remote can make it reachable if none advertises it, so an empty remote
+  // set is fine for this subcase.
+  if (present) return { proven: true, subcase: 'revert-unreachable' };
+
+  // An ABSENT commit is a different claim. Absence is only PROOF of "gone" when the clone is
+  // complete (not shallow/partial — checked above) AND current with every remote the commit could
+  // still live on (the loop above confirmed each advertised tip is present locally). With NO remotes
+  // there was nothing to confirm against — an absent sha could simply be one this clone never had.
+  // Refuse rather than attest a commit lost we cannot see anywhere.
+  if (remotes.length === 0) {
+    return {
+      proven: false,
+      kind: 'no-remotes',
+      reason: `${short(sha)} is not in this clone, and this repo has no remotes to confirm it is gone — an absent commit here is not proof it is lost. Add the remote it was on and fetch, or revert in git and re-plan instead of attesting it lost.`,
+    };
+  }
+  return { proven: true, subcase: 'unknown-commit-proven-absent' };
+}
 
-  const candidates = enumerateModelTrees(modelsDir, repoRoot);
+/** The real probe: each method is one git command run in `cwd`. */
+export function realLineageProbe(cwd: string): GitLineageProbe {
+  const run = (args: string[]): string | null => {
+    try {
+      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    } catch {
+      return null;
+    }
+  };
+  return {
+    isShallow: () => (run(['rev-parse', '--is-shallow-repository']) ?? '').trim() === 'true',
+    isPartial: () => {
+      // A promisor remote is the mark of a partial clone; `extensions.partialClone` names it.
+      const ext = run(['config', '--get', 'extensions.partialClone']);
+      return ext !== null && ext.trim().length > 0;
+    },
+    objectExists: (sha) => commitPresent(sha, cwd),
+    refsContaining: (sha) =>
+      (run(['for-each-ref', '--format=%(refname)', `--contains=${sha}`]) ?? '')
+        .split('\n').map((l) => l.trim()).filter(Boolean),
+    isAncestorOf: (sha, committish) => isAncestor(sha, committish, cwd),
+    remotes: () => {
+      const out = run(['remote']);
+      // null (the command threw) is NOT an empty remote set — it must refuse, not skip the loop.
+      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;
+      return out.split('\n').map((l) => l.split('\t')[0]?.trim()).filter((s): s is string => !!s && s.length >= 7);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// proveDescent — the ledger-first fast-forward proof (apply-legibility Phase 1a).
+// ---------------------------------------------------------------------------
+
+/**
+ * One `everystack.schema_log` row, as descent reads it. The apply path writes these on every
+ * successful state apply; the fast-forward proof reads them newest-first.
+ *
+ * Trust note: the ledger is a memoir, and a forger with write access to it already has write
+ * access to the database. The proof does not rest on the ledger's honesty — the fingerprint
+ * join (`fingerprintLiveAtVersion(fp_version) == to_fingerprint`) forces a row to be correctly
+ * content-addressed before its git_ref is ever consulted. A row with a stale or wrong
+ * to_fingerprint simply does not match, and descent falls through as if it were not there.
+ */
+export interface DescentLedgerRow {
+  id: string;
+  /** The raw live fingerprint recorded when this state was applied. */
+  toFingerprint: string | null;
+  /** HEAD at apply time — the commit whose ancestry proves the fast-forward. */
+  gitRef: string | null;
+  /** The FINGERPRINT_VERSION `to_fingerprint` was computed under (null = pre-fp_version row). */
+  fpVersion: number | null;
+  /** The apply ran from a dirty worktree — git_ref does not declare what was applied. */
+  dirty: boolean;
+  /** When the apply landed — for the REVERT message (names the commit + date). */
+  appliedAt: string;
+  /** Only a successful state apply is a witness. */
+  outcome: string;
+}
+
+export type ProveVerdict =
+  /** The database has no tables — first apply bootstraps it. */
+  | { 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 }
+  /** 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. */
+  | { status: 'unknown-commit'; commit: string; reason: string }
+  /** No ledger witness, and the ancestor recompile could not read every tree — inconclusive. */
+  | { status: 'unverifiable'; reason: string; unevaluated: string[]; compileFailures: string[] }
+  /** No ledger witness, every ancestor tree read cleanly, none declares live — real drift. */
+  | { status: 'drift'; reason: string; scannedTrees: number };
+
+export interface ProveDescentOptions extends DescentOptions {
+  /** Retained-canon registry override — the cross-bump recompute path (tests inject a
+   *  synthetic retired canon). Defaults to the module's RETAINED_CANONS. */
+  canons?: Readonly<Record<number, CanonHasher>>;
+}
+
+const shortDate = (at: string): string => at.slice(0, 10);
+
+/**
+ * The fast-forward proof, ledger-first. Refuse-closed: no inconclusive branch passes.
+ *
+ *   Phase A — the newest successful ledger row whose `to_fingerprint` matches the live state
+ *   (recomputed under the ROW'S canon) and whose git_ref is usable (non-null, not a dirty
+ *   mint) is THE witness — newest wins. Ancestor of HEAD → PROVEN; not an ancestor → REVERT;
+ *   absent from the clone → UNKNOWN-COMMIT. A null git_ref, a dirty mint, an unrecomputable
+ *   canon (pre-fp_version or a retired canon we no longer retain), or a non-matching
+ *   fingerprint SKIPS the row — the search continues to older rows.
+ *
+ *   Phase B — no usable ledger witness: recompile RESTRICTED TO HEAD ANCESTORS. A declaring
+ *   ancestor → PROVEN. Otherwise the classification is honest about what it could read: any
+ *   tree we could not extract or compile makes "nothing declares this" a claim we cannot make
+ *   → UNVERIFIABLE (never "drift"). Only a clean, exhaustive no-match is DRIFT.
+ *
+ * The old descent recompiled ALL history under the CURRENT CLI, so a stage whose declaring
+ * commit no longer compiled was reported as drift and stranded. Phase A never recompiles; the
+ * ledger carries the proof across a canon or API bump.
+ */
+export async function proveDescent(
+  modelsPath: string,
+  live: LiveState,
+  ledger: DescentLedgerRow[],
+  opts: ProveDescentOptions = {},
+): Promise<ProveVerdict> {
+  if (live.snapshot.tables.length === 0) return { status: 'fresh-target' };
+
+  const ctx = resolveRepoContext(modelsPath, opts);
+  if (ctx === null) return { status: 'no-git' };
+  const { repoRoot, head, modelsDir, barrel } = ctx;
+
+  // ---- Phase A: the ledger witness (newest usable row wins). ----
+  // "Newest wins" (the S→T→S pre-episode refusal) is a security-relevant property, so do not
+  // TRUST the caller's ordering — enforce it. Production callers read ORDER BY id DESC, but a
+  // future caller passing an unsorted ledger must not silently let a pre-episode row win.
+  const ordered = [...ledger].sort((a, b) => Number(b.id) - Number(a.id));
+  for (const r of ordered) {
+    if (r.outcome !== 'applied') continue; // only a successful state apply is a witness
+    if (!r.toFingerprint) continue;
+    if (!r.gitRef) continue; // a null git_ref cannot declare a commit
+    if (r.dirty) continue; // a dirty mint's git_ref does not declare what was applied
+    const liveFp = fingerprintLiveAtVersion(r.fpVersion, live.snapshot, live.contract, {}, opts.canons);
+    if (liveFp === null) continue; // canon we cannot reproduce — skip, never guess
+    if (liveFp !== r.toFingerprint) continue; // not this witness (a stale/forged hash fails here)
+
+    // r is THE witness — the newest matching row with a usable git_ref. Decide on it; do not
+    // fall back to an older row (the pre-episode branch of an S→T→S history is refused).
+    if (!commitPresent(r.gitRef, repoRoot)) {
+      return {
+        status: 'unknown-commit',
+        commit: r.gitRef,
+        reason:
+          `the commit that last deployed this state (${short(r.gitRef)}) is not in this clone — ` +
+          'it is a shallow checkout, or the branch was not fetched. Fetch the full history ' +
+          '(git fetch --unshallow, or fetch the deploying branch) and re-run; the fast-forward ' +
+          'rule cannot be proven against a commit you do not have.',
+      };
+    }
+    if (isAncestor(r.gitRef, head, repoRoot)) {
+      return { status: 'proven', via: 'ledger', commit: 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.',
+    };
+  }
+
+  // ---- Phase B: no usable ledger witness → ancestor-restricted recompile. ----
+  const candidates = enumerateModelTrees(modelsDir, repoRoot, { ancestorsOf: head });
 
   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 materialize = opts.materialize ?? materializeTree;
+  const evalCtx: EvalContext = {
+    repoRoot,
+    materializeRoot,
+    barrel,
+    loader: opts.loader ?? defaultLoader,
+    materialize: opts.materialize ?? materializeTree,
+    schema: opts.schema,
+  };
 
   const compileFailures: string[] = [];
   const unevaluated: string[] = [];
-  const declaringButDiverged: ModelTreeCandidate[] = [];
   try {
     for (const candidate of candidates) {
-      const dest = path.join(materializeRoot, candidate.tree);
-      const where = `${short(candidate.tree)} (at ${short(candidate.commits[0])})`;
-
-      // TWO KINDS OF FAILURE, and conflating them is what made this path lie.
-      //
-      // EXTRACTION failing says nothing about the tree — we never saw it. It was recorded as a
-      // "compile failure" and the verdict fell through to `drift`, which tells an operator
-      // their database was hand-edited. Observed for real: `spawnSync tar EPIPE` under a loaded
-      // machine. Those trees now go to `unevaluated` and produce `indeterminate`.
-      //
-      // COMPILING failing IS a property of the tree — a models file that no longer builds
-      // against today's @everystack/model is genuinely unusable, deterministically, and
-      // skipping it is correct. Those keep `compileFailures` and still allow `drift`.
-      //
-      // Each gets ONE retry from a clean materialization first, because either can also be
-      // transient under load.
-      try {
-        if (!fs.existsSync(dest)) materialize(candidate.tree, dest, repoRoot);
-      } catch {
-        try {
-          fs.rmSync(dest, { recursive: true, force: true });
-          materialize(candidate.tree, dest, repoRoot);
-        } catch (err: any) {
-          unevaluated.push(`${where}: could not extract — ${err.message}`);
-          continue;
-        }
-      }
-
-      // The declares-test is GOVERNED on both sides, per candidate: the commit's
-      // models define the governed set, and the live hash is filtered through the
-      // SAME set as the prediction — comparing a governed prediction against the
-      // raw live hash can never match on a brownfield target with foreign roles.
-      const evaluate = async (): Promise<boolean> => {
-        const models = await loader(path.join(dest, barrel));
-        const governedRoles = governedRolesForModels(models);
-        const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema, governedRoles });
-        return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
-      };
-      let declares: boolean;
-      try {
-        try {
-          declares = await evaluate();
-        } catch {
-          declares = await evaluate();
-        }
-      } catch (err: any) {
-        compileFailures.push(`${where}: ${err.message}`);
+      const result = await evaluateTree(candidate, live, evalCtx);
+      if (result.kind === 'unevaluated') {
+        unevaluated.push(result.detail);
         continue;
       }
-      if (!declares) 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
-        }
+      if (result.kind === 'compile-failed') {
+        compileFailures.push(result.detail);
+        continue;
       }
-      declaringButDiverged.push(candidate);
+      if (result.kind === 'no') continue;
+      // Enumerated over HEAD's ancestors, so every commit here descends into HEAD — but confirm,
+      // since a tree can be carried by commits on more than one line of history.
+      const ancestor = candidate.commits.find((commit) => isAncestor(commit, head, repoRoot)) ?? candidate.commits[0];
+      return { status: 'proven', via: 'recompile', commit: ancestor };
     }
   } finally {
     if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
   }
 
-  if (declaringButDiverged.length > 0) {
-    const commits = declaringButDiverged.flatMap((c) => c.commits);
+  // No ancestor carries a committed models directory to compare against — a shallow clone that
+  // truncated the deploying history, or the deploying branch is simply not in this checkout.
+  // That is a limit of THIS clone, not a hand-edit: UNVERIFIABLE, never drift.
+  if (candidates.length === 0) {
     return {
-      status: 'diverged',
-      commits,
-      tree: declaringButDiverged[0].tree,
+      status: 'unverifiable',
       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.',
+        'cannot verify the fast-forward rule — no ancestor of your checkout carries a committed ' +
+        'models directory to compare against. This is a shallow clone (fetch the full history: ' +
+        'git fetch --unshallow) or the deploying branch is not in this checkout, not evidence ' +
+        'about the database — it is NOT drift. Fetch the deploying history, or waive the rule deliberately.',
+      unevaluated,
+      compileFailures,
     };
   }
 
-  // Nothing matched — but if a tree was never evaluated, "nothing matched" is a claim we
-  // cannot make. The unevaluated one could be the declaring tree. Reported BEFORE drift
-  // because drift accuses the database, and this condition is about our own run.
-  if (unevaluated.length > 0) {
+  // A tree we could not READ is not evidence about the database. If any ancestor tree could not
+  // be extracted or compiled, "nothing declares this state" is a claim we are not entitled to
+  // make — the answer is UNVERIFIABLE, and its next move is retry/upgrade, never db:pull.
+  if (unevaluated.length > 0 || compileFailures.length > 0) {
+    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`);
     return {
-      status: 'indeterminate',
-      scannedTrees: candidates.length,
-      unevaluated,
+      status: 'unverifiable',
       reason:
-        `${unevaluated.length} of ${candidates.length} historical tree(s) could not be extracted, ` +
-        'so the search was not exhaustive and one of them may be the commit that declares this state. ' +
-        'This is a fault in THIS run, not evidence about the database — retry, and if it persists ' +
-        `check disk space and open-file limits. Details: ${unevaluated.join('; ')}`,
+        `cannot verify the fast-forward rule — of ${candidates.length} ancestor 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 waive the rule deliberately.',
+      unevaluated,
+      compileFailures,
     };
   }
 
-  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(fingerprintLive(live.snapshot, live.contract).hash)} — ` +
-      `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.',
+      `no ancestor of your checkout declares the target's live fingerprint ` +
+      `${short(fingerprintLive(live.snapshot, live.contract).hash)} — read ${candidates.length} ` +
+      'ancestor model state(s), all cleanly, and none matches. The database was hand-edited ' +
+      '(drift), or the deploying branch is not in this checkout. Align the models with the live ' +
+      'database (db:pull, commit), or waive the rule deliberately.',
   };
 }
+
+/**
+ * Collapse a ProveVerdict into the ok/reason shape the apply core enforces. Refuse-closed:
+ * only proven / fresh-target / no-git pass; every other verdict refuses, carrying its own
+ * distinct cause so the operator's next move is unambiguous.
+ */
+export function proveVerdictForApply(verdict: ProveVerdict): { ok: true } | { ok: false; reason: string } {
+  switch (verdict.status) {
+    case 'proven':
+    case 'fresh-target':
+    case 'no-git':
+      return { ok: true };
+    case 'revert':
+    case 'unknown-commit':
+    case 'unverifiable':
+    case 'drift':
+      return { ok: false, reason: verdict.reason };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The descent decision AT APPLY, WITH the lineage-lost attestation.
+//
+// This replaces the retired `--force-descent` (which skipped the descent check wholesale). A descent
+// refusal now has a GIT-NATIVE flagless escape, and the ONE attestation `--attest-lineage-lost <sha>`
+// is honoured only where no re-plan can express the fix: the declaring commit is PROVEN unreachable
+// from every ref. The proof (`proveLineageLost`) is injected so this stays a pure decision.
+// Fable-adjudicated 2026-08-26.
+// ---------------------------------------------------------------------------
+
+export interface DescentApplyContext {
+  /** `--attest-lineage-lost <sha>`, if the operator passed it. */
+  attestation?: string;
+  /** Destructive plans have no additive no-git waiver — the no-git escape differs. */
+  destructive: boolean;
+  /** Proves a declaring commit is unreachable from every ref. `realLineageProbe`-backed in production. */
+  proveLineage: (sha: string) => LineageProof;
+}
+
+export type DescentApplyDecision =
+  /** Proceed. `attested` is set only when the attestation was honoured — record it in schema_log. */
+  | { ok: true; attested?: { commit: string; subcase: 'revert-unreachable' | 'unknown-commit-proven-absent' } }
+  | { ok: false; reason: string };
+
+/** A short recorded note for a honoured attestation — goes in the apply row's schema_log outcome. */
+export function attestationNote(a: { commit: string; subcase: string }): string {
+  return `descent-attested-lineage-lost (${short(a.commit)}, ${a.subcase})`;
+}
+
+export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyContext): DescentApplyDecision {
+  switch (verdict.status) {
+    case 'proven':
+    case 'fresh-target':
+      return { ok: true };
+
+    case 'no-git':
+      // no-git is "not standing in the lineage", NOT "lineage gone" — the attestation never covers it.
+      // Additive rides the (caller-warned) waiver as before; destructive refuses outright.
+      return ctx.destructive
+        ? { ok: false, reason: 'this is not a git checkout and the plan is DESTRUCTIVE, so the fast-forward rule cannot be verified — run db:apply from the git checkout that declares your models.' }
+        : { ok: true };
+
+    case 'unverifiable':
+    case 'drift':
+      // No single declaring commit — nothing to attest ABOUT. The escape is to make HEAD declare the
+      // live state, then re-plan. An attestation here is a category error, refused as one.
+      return {
+        ok: false,
+        reason: ctx.attestation
+          ? `--attest-lineage-lost does not apply here: there is no single declaring commit to attest about. ${verdict.reason} Commit your models so HEAD declares this state (db:generate), then db:plan and db:apply again.`
+          : `${verdict.reason} Commit your models so HEAD declares this state (db:generate), then db:plan and db:apply again.`,
+      };
+
+    case 'revert':
+    case 'unknown-commit': {
+      // These name a declaring commit. Without an attestation the flagless escape (git revert / fetch)
+      // is the verdict's own message; append the last-resort attestation for a branch that is truly gone.
+      if (!ctx.attestation) {
+        return {
+          ok: false,
+          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) {
+        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.`,
+        };
+      }
+      const proof = ctx.proveLineage(verdict.commit);
+      return proof.proven
+        ? { ok: true, attested: { commit: verdict.commit, subcase: proof.subcase } }
+        : { ok: false, reason: proof.reason };
+    }
+  }
+}