@everystack/cli 0.4.76 → 0.4.77

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.77] - 2026-09-07
+
+### Added
+
+- proven drift is the operator's decision — passes at apply with its origin recorded
+- proven drift is announced as the origin on both lanes; refusals name a verb that works
+
+### Fixed
+
+- currency is ref reachability, not object presence; a failed all-refs walk is unverifiable
+- an empty barrel declares nothing; a non-commit tag is not 'behind'; tests bind the production decision
+- one shipped descent step for both lanes, bound end to end by the real CLI; trees materialize inside the project
+- the sandbox sits below the nearest node_modules above the barrel; a dirty-worktree origin reaches every surface
+- the compile-failure detail keeps the cause; the monorepo test skips loudly; the stash filter sits on the refuse-closed side
+
+### Documentation
+
+- proven drift, declared-elsewhere, the adoption lifecycle table, and a db:adopt section
+
 ## [0.4.76] - 2026-09-07
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.76",
+  "version": "0.4.77",
   "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/apply-execute.ts

@@ -131,9 +131,11 @@ export interface ApplyPlanOptions {
   /** Injectable clock for tests. */
   now?: () => number;
   /**
-   * A note for the schema_log outcome when the fast-forward rule was waived by a
-   * `--attest-lineage-lost` attestation. A getter, because the attestation is decided inside
-   * `checkDescent` (which runs before the write) — the getter reads that decision at write time.
+   * A note for the schema_log outcome (`applied — <note>`) carrying what descent decided: a
+   * honoured `--attest-lineage-lost` waiver, or a PROVEN DRIFT origin (`descent: drift-origin
+   * proven (never-declared | hand-edited since … | applied from a DIRTY worktree at …)`) — the record that makes this row the origin
+   * every later apply descends from. A getter, because the decision is made inside `checkDescent`
+   * (which runs before the write) — the getter reads it at write time.
    */
   descentNote?: () => string | undefined;
 }
@@ -205,10 +207,16 @@ export interface LiveBaseAndLedger extends LiveBaseFingerprint {
  * The newest successful state applies — the descent witnesses. Read alongside the live state
  * (allowFailure, because a database that never applied through this CLI has no schema_log
  * yet). Newest-first, capped: the proof consults the newest usable row and stops.
+ *
+ * `applied%`, not `= 'applied'`: an apply that carried a descent note (an honoured lineage
+ * attestation, or a proven drift origin) is recorded as `applied — <note>`, and it is STILL a
+ * successful apply — the row that proves the next fast-forward. Matching the bare word only
+ * silently dropped every annotated apply from the ledger, which for a drift origin defeats the
+ * entire point of recording it.
  */
 export const SCHEMA_LOG_WITNESS_SQL = `SELECT id, to_fingerprint, git_ref, fp_version, dirty, applied_at, outcome
 FROM everystack.schema_log
-WHERE kind = 'state apply' AND outcome = 'applied' AND to_fingerprint IS NOT NULL
+WHERE kind = 'state apply' AND outcome LIKE 'applied%' AND to_fingerprint IS NOT NULL
 ORDER BY id DESC
 LIMIT 200`;
 

package/src/cli/apply-refusals.ts

@@ -34,7 +34,7 @@ export function snapshotMovedRefusal(ref: string, captured: string, planFrom: st
 // The USER-FACING refusal message (apply-legibility Phase 3, p3-action-refusals).
 //
 // Every refusal db:apply reaches from executeApplyPlan prints an ACTION, never a check name. The
-// reason string is already action-phrased at its source (checkPlanPrecondition, proveVerdictForApply,
+// reason string is already action-phrased at its source (checkPlanPrecondition, decideDescentApply,
 // checkDestructiveAuthority, the snapshot gate, the baseline gate). This layer only marks the OUTCOME
 // and forwards that reason — it does NOT re-label the check the way the old
 // `REFUSED (fast-forward rule):` / `(snapshot gate)` / `(destructive authority)` wording did.

package/src/cli/authz-reconcile.ts

@@ -127,7 +127,7 @@ export interface VestigialSequenceGrant {
 }
 
 /**
- * Sequence grants with no corresponding INSERT — an ADVISORY, never a revoke.
+ * Sequence grants with no corresponding INSERT — the db:pull ADVISORY.
  *
  * The shape a brownfield database arrives in: a blanket `GRANT USAGE ON ALL SEQUENCES IN
  * SCHEMA public` sitting beside a blanket `GRANT SELECT ON ALL TABLES`, years old, granted
@@ -135,11 +135,13 @@ export interface VestigialSequenceGrant {
  * holding USAGE on all 27 sequences with INSERT on zero tables — and it was the single
  * divergence between their database and the inheritance rule.
  *
- * Reported rather than revoked, and the distinction is the whole point: the inheritance rule
- * only ever ADDS what an INSERT needs, so a vestigial grant is untouched by reconciliation and
- * would otherwise sit there unnoticed forever. Naming it lets the owner decide. Revoking it
- * would be the tool making a security decision from an inference — the same move we refused for
- * the invented search_path.
+ * What the reconciler does with it depends on the grantee, and the advisory must say so
+ * exactly (it once said "nothing revokes it — revoke by hand", which sent an operator to a
+ * credential for an edge the tool itself mints): a GOVERNED grantee (anon / authenticated /
+ * admin / PUBLIC, or a declared governedRole) has its vestigial grant REVOKED by the next
+ * plan, as an authz removal — the Models cannot declare a sequence grant with no INSERT
+ * behind it, so the plan converges the database on the inheritance rule. An UNGOVERNED
+ * grantee is left alone (reconcileSequenceGrants skips it) and stays on this list every pull.
  */
 export function vestigialSequenceGrants(live: AuthzContract): VestigialSequenceGrant[] {
   if (!live.sequenceGrants) return []; // not measured
@@ -163,12 +165,24 @@ export function vestigialSequenceGrants(live: AuthzContract): VestigialSequenceG
     .sort((a, b) => a.grantee.localeCompare(b.grantee));
 }
 
-/** One line per grantee — the shared rendering, same idiom as renderGrantExemptions. */
-export function renderVestigialSequenceGrants(findings: readonly VestigialSequenceGrant[]): string[] {
-  return findings.map(({ grantee, sequences }) =>
-    `${grantee} holds privileges on ${sequences.length} sequence(s) but can INSERT into none of their tables — `
-    + `probably a vestigial blanket GRANT ... ON ALL SEQUENCES. Nothing revokes it (the inheritance rule only adds); `
-    + `review and revoke by hand if it is dead: ${sequences.slice(0, 6).join(', ')}${sequences.length > 6 ? `, +${sequences.length - 6} more` : ''}.`);
+/**
+ * One line per grantee — the shared rendering, same idiom as renderGrantExemptions. The line
+ * names the verb that acts on it: a governed grantee's vestigial grant is an authz removal in
+ * the next db:plan; an ungoverned one is left alone.
+ */
+export function renderVestigialSequenceGrants(
+  findings: readonly VestigialSequenceGrant[],
+  /** REQUIRED: the same governed set the next db:plan will use (the vocabulary plus any
+   *  --govern-roles / declared governedRoles). A default here reproduced the bug this fixes. */
+  governed: ReadonlySet<string>,
+): string[] {
+  return findings.map(({ grantee, sequences }) => {
+    const list = `${sequences.slice(0, 6).join(', ')}${sequences.length > 6 ? `, +${sequences.length - 6} more` : ''}`;
+    const head = `${grantee} holds privileges on ${sequences.length} sequence(s) but can INSERT into none of their tables — probably a vestigial blanket GRANT ... ON ALL SEQUENCES.`;
+    return isGoverned(governed, grantee)
+      ? `${head} ${grantee} is governed, so the next db:plan REVOKES it (an authz removal — the Models cannot declare a sequence grant with no INSERT behind it): ${list}.`
+      : `${head} ${grantee} is not governed, so nothing revokes it; declare it in governedRoles to bring it under the plan, or leave it: ${list}.`;
+  });
 }
 
 /** A USING/WITH CHECK clause expression, parenthesized exactly once. */

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

@@ -5,8 +5,7 @@
  *            [--govern-roles r1,r2]
  *
  * The problem it solves: a production database that never went through Models has no committed
- * ancestor declaring it, so db:apply refuses it as unverifiable drift — and no waiver fits (there
- * is nothing to attest a lineage FROM). db:adopt is the deliberate, auditable on-ramp. It renders
+ * ancestor declaring it. db:adopt is the deliberate, auditable on-ramp for taking it AS IT IS: it renders
  * Models from the live database (the same renderers db:pull uses), compiles them back, and PROVES
  * the compiled Models declare the live state EXACTLY — predicted == governed live, the same
  * declares-test descent and db:check use. Only then does it write the model files and print the
@@ -15,8 +14,11 @@
  *
  * The doctrine (Fable-ruled 2026-09-05): PROVE, not attest. There is NO bypass flag. When the
  * round-trip is not exact, adoption REFUSES, names the surfaces that diverged, and prints the
- * db:generate edge — because a baseline that papered over a difference is the bypass under another
- * name. It writes NOTHING on refusal; --out is left untouched.
+ * edge — because a baseline that papered over a difference is the bypass under another name. It
+ * writes NOTHING on refusal; --out is left untouched. That refusal is the HARDENING case (the
+ * vocabulary cannot declare something live), and it needs no adoption commit: commit the intended
+ * Models, db:plan, db:apply — descent proves no commit declares the database and treats the
+ * reviewed plan as the origin (git-descent.ts, proven drift, 2026-09-07).
  *
  * The pure proof core is adopt.ts (proveAdoption); the shared render is live-models.ts
  * (renderLiveModelFiles). This shell is the IO: connect, render into a sandbox to compile, prove,
@@ -123,7 +125,10 @@ export async function applyAdoptVerdict(result: AdoptResult, outDir: string): Pr
       for (const stmt of result.refusalDiff) console.log(stmt.endsWith(';') ? stmt : `${stmt};`);
     }
     console.log('');
-    info('The renderer could not yet capture the surfaces above. Refine by hand until db:generate is empty, then commit the Models — a later db:apply will descend normally.');
+    info('The Models vocabulary cannot declare the surfaces above as they are live (a sequence grant with no INSERT behind it, for example), so no render can round-trip this database. That is the HARDENING case, and it needs no adoption commit: commit the Models you intend, then');
+    info('  everystack db:plan --stage <name>                       # mints the edge above as a reviewable plan');
+    info('  everystack db:apply --plan <file.plan.json> --stage <name>   # credential-free; no commit declares this database yet, so the reviewed plan is the ORIGIN and is recorded as such');
+    info('Every later db:apply descends from that recorded origin.');
     return { exitCode: 1, wrote: false };
   }
 

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

@@ -36,11 +36,14 @@ import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, type EdgePlan } from '.
 import {
   proveDescent,
   decideDescentApply,
+  describeDriftOrigin,
   attestationNote,
   proveLineageLost,
   realLineageProbe,
   type DescentLedgerRow,
   type LiveState,
+  type ProveVerdict,
+  type ProveDescentOptions,
 } from '../git-descent';
 import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity, type AuthorityVerdict } from '../apply-authority';
 import { decideSnapshotMode, type SnapshotModeRequest } from '../swap-snapshot';
@@ -108,6 +111,82 @@ export function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void
   }
 }
 
+/**
+ * Say what descent found, on BOTH lanes identically. Exported so a test can pin the one line
+ * that matters most: proven drift is announced as the ORIGIN, loudly, before anything writes.
+ */
+export function describeDescentVerdict(verdict: ProveVerdict, opts: { destructive?: boolean } = {}): { level: 'info' | 'warn'; text: string } | null {
+  switch (verdict.status) {
+    case 'proven':
+      return { level: 'info', text: `descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.` };
+    case 'fresh-target':
+      return { level: 'info', text: 'descent: fresh target (no tables) — nothing to protect, bootstrapping.' };
+    case 'no-git':
+      // On a destructive plan the decision refuses with its own message; do not double-report.
+      return opts.destructive ? null : { level: 'warn', text: 'descent: not a git checkout — the fast-forward rule cannot be verified here.' };
+    case 'drift':
+      return {
+        level: 'warn',
+        text: `NO COMMIT ON ANY REF DECLARES THIS DATABASE (${describeDriftOrigin(verdict.origin, { human: true })}) — this reviewed plan is the ORIGIN. The fast-forward rule has nothing merged to protect (proven over a full, current clone); the origin is recorded in schema_log, and every later apply descends from it.`,
+      };
+    case 'declared-elsewhere':
+    case 'revert':
+    case 'unknown-commit':
+    case 'unverifiable':
+      return null; // the decision refuses with the verdict's own reason
+  }
+}
+
+function reportDescentVerdict(verdict: ProveVerdict, opts: { destructive?: boolean } = {}): void {
+  const line = describeDescentVerdict(verdict, opts);
+  if (!line) return;
+  (line.level === 'warn' ? warn : info)(line.text);
+}
+
+/**
+ * THE descent step, shared by both lanes: prove the fast-forward rule over the live state and the
+ * ledger, report the verdict, decide it (attestation honoured only where proven), and hand back
+ * the wire/record shape — `descentVerdict` for the gate and `descentAttested` for the schema_log
+ * outcome (`applied — <note>`): a honoured lineage-lost waiver, or a PROVEN DRIFT origin.
+ *
+ * One function so the origin record cannot be dropped on one lane and kept on the other, and so
+ * a test can drive the SHIPPED wiring without AWS (the stage lane passes in the state it double-
+ * read and the ledger it fetched; the direct lane passes what executeApplyPlan read in-session).
+ * The closing-gate review found the note assignment unbound at both call sites — this is the bind.
+ */
+export async function proveDescentForApply(input: {
+  modelsPath: string;
+  live: LiveState;
+  ledger: DescentLedgerRow[];
+  destructive: boolean;
+  attestation?: string;
+  /** Where git runs. Default process.cwd(). */
+  cwd?: string;
+  /** Test seam: the barrel loader and materialize root (jest cannot dynamic-import a .ts barrel).
+   *  Production passes nothing and rides the real loader. */
+  descent?: Pick<ProveDescentOptions, 'loader' | 'materializeRoot'>;
+}): Promise<{ descentVerdict: { ok: true } | { ok: false; reason: string }; descentAttested?: string }> {
+  const verdict = await proveDescent(input.modelsPath, input.live, input.ledger, {
+    ...(input.cwd ? { cwd: input.cwd } : {}),
+    ...(input.descent ?? {}),
+  });
+  reportDescentVerdict(verdict, { destructive: input.destructive });
+  const decision = decideDescentApply(verdict, {
+    ...(input.attestation ? { attestation: input.attestation } : {}),
+    destructive: input.destructive,
+    proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(input.cwd ?? process.cwd())),
+  });
+  if (!decision.ok) return { descentVerdict: { ok: false, reason: decision.reason } };
+  if (decision.attested) {
+    const descentAttested = attestationNote(decision.attested);
+    warn(`DESCENT ATTESTED — ${descentAttested}. The declaring commit is proven gone from every ref; the fast-forward rule is waived for this apply and the waiver is recorded.`);
+    return { descentVerdict: { ok: true }, descentAttested };
+  }
+  // A proven-drift origin rides the same recorded field as a waiver — it is the same kind of
+  // record: what descent decided, and why this row is the one later applies descend from.
+  return { descentVerdict: { ok: true }, ...(decision.note ? { descentAttested: decision.note } : {}) };
+}
+
 /**
  * db:apply --stage: the credential-free staged write. The operator never holds
  * a database URL — the WRITE runs in the ops Lambda's db:apply action against
@@ -180,32 +259,17 @@ async function applyPlanViaStage(
     // git-native (git revert / db:generate / fetch); the one attestation
     // (--attest-lineage-lost) is honoured only when the CLI proves the declaring
     // commit is gone from every ref.
-    let descentVerdict: { ok: true } | { ok: false; reason: string };
-    let descentAttested: string | undefined;
-    {
-      const { snapshot, contract } = readPair.state;
-      step("Descent: reading the stage's schema_log ledger...");
-      const ledger = await readDescentLedger(lambdaSessionRunner(region, fn));
-      step("Descent: proving the fast-forward rule against the ledger...");
-      const verdict = await proveDescent(resolveModelsPath(flags.models), { snapshot, contract }, ledger, {});
-      if (verdict.status === 'proven') {
-        info(`descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.`);
-      } else if (verdict.status === 'fresh-target') {
-        info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
-      } else if (verdict.status === 'no-git') {
-        warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
-      }
-      const decision = decideDescentApply(verdict, {
-        ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
-        destructive: plan.destructive > 0,
-        proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(process.cwd())),
-      });
-      if (decision.ok && decision.attested) {
-        descentAttested = attestationNote(decision.attested);
-        warn(`DESCENT ATTESTED — ${descentAttested}. The declaring commit is proven gone from every ref; the fast-forward rule is waived for this apply and the waiver is recorded.`);
-      }
-      descentVerdict = decision.ok ? { ok: true } : { ok: false, reason: decision.reason };
-    }
+    const { snapshot, contract } = readPair.state;
+    step("Descent: reading the stage's schema_log ledger...");
+    const ledger = await readDescentLedger(lambdaSessionRunner(region, fn));
+    step("Descent: proving the fast-forward rule against the ledger...");
+    const { descentVerdict, descentAttested } = await proveDescentForApply({
+      modelsPath: resolveModelsPath(flags.models),
+      live: { snapshot, contract },
+      ledger,
+      destructive: plan.destructive > 0,
+      ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
+    });
 
     // Destructive ceremony — the approver check is against the caller's REAL
     // IAM identity (STS), which the Lambda cannot see, so the CLI resolves it
@@ -571,24 +635,15 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       descentNote: () => descentAttested,
       checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[] }) => {
         step('Descent: proving the fast-forward rule against the schema_log ledger...');
-        const verdict = await proveDescent(resolveModelsPath(flags.models), live, live.ledger, {});
-        if (verdict.status === 'proven') {
-          info(`descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.`);
-        } else if (verdict.status === 'fresh-target') {
-          info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
-        } else if (verdict.status === 'no-git' && plan.destructive === 0) {
-          warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
-        }
-        const decision = decideDescentApply(verdict, {
-          ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
+        const result = await proveDescentForApply({
+          modelsPath: resolveModelsPath(flags.models),
+          live,
+          ledger: live.ledger,
           destructive: plan.destructive > 0,
-          proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(process.cwd())),
+          ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
         });
-        if (decision.ok && decision.attested) {
-          descentAttested = attestationNote(decision.attested);
-          warn(`DESCENT ATTESTED — ${descentAttested}. The declaring commit is proven gone from every ref; the fast-forward rule is waived for this apply and the waiver is recorded.`);
-        }
-        return decision.ok ? { ok: true } : { ok: false, reason: decision.reason };
+        descentAttested = result.descentAttested;
+        return result.descentVerdict;
       },
       }),
     );

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

@@ -50,7 +50,7 @@ import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan';
-import { proveDescent } from '../git-descent';
+import { proveDescent, describeDriftOrigin, type ProveVerdict } from '../git-descent';
 import { readDescentLedger } from '../apply-execute';
 import { planBackfills, readBackfillLog } from '../backfill';
 import { readSqlDirIfPresent } from './db-sync';
@@ -70,6 +70,48 @@ import { compileTableContract } from '../authz-compile';
 import { reportPipelineLastRun } from './pipeline-run';
 import { step, success, fail, info, warn, reserveStdoutForData } from '../output';
 
+/**
+ * What db:plan says about descent at mint — SYMMETRIC with what db:apply will do, because a mint
+ * that warns "will refuse" for a plan apply then runs (or the reverse) is the lie this used to
+ * tell. Exported so a test pins every verdict's text. The `never` arm makes the switch REALLY
+ * exhaustive: a new verdict fails to compile here instead of minting a plan with no warning and
+ * refusing at apply with no hint of why.
+ */
+export function describePlanDescent(verdict: ProveVerdict): string[] {
+  switch (verdict.status) {
+    case 'proven':
+    case 'fresh-target':
+    case 'no-git':
+      return [];
+    case 'drift':
+      return [
+        `descent: NO COMMIT ON ANY REF DECLARES THIS DATABASE (${describeDriftOrigin(verdict.origin, { human: true })}) — proven over a full, current clone.`,
+        'db:apply will treat this reviewed plan as the ORIGIN: it applies, warns, and records the origin in schema_log; every later apply descends from it.',
+      ];
+    case 'declared-elsewhere':
+      return [
+        `descent: ${verdict.reason}`,
+        'db:apply from this checkout will refuse this plan — fetch and merge or rebase onto that commit, then re-mint.',
+      ];
+    case 'revert':
+      return [`descent: ${verdict.reason}`, 'db:apply from this checkout will refuse this plan — rebase first, then re-mint.'];
+    case 'unknown-commit':
+      // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit.
+      return [`descent: ${verdict.reason}`, 'db:apply from this checkout will refuse this plan until you fetch that commit — fetch, then re-mint.'];
+    case 'unverifiable':
+      // NOT "rebase first" — nothing is wrong with the checkout or the database. The search could
+      // not finish (an unreadable tree, or a clone that is not full and current).
+      return [`descent: ${verdict.reason}`, 'db:apply from this checkout will refuse this plan until that search completes — fetch or prune as it says, then re-mint.'];
+    default: {
+      // Compile-time exhaustiveness; at runtime (a verdict shape from outside this compile unit)
+      // an empty warning list is the safe value — the caller iterates it.
+      const exhaustive: never = verdict;
+      void exhaustive;
+      return [];
+    }
+  }
+}
+
 const DEFAULT_OUT = 'db.plan.json';
 
 /**
@@ -289,28 +331,7 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       // A switch, not an `if (revert || drift)`. That form silently ignored every verdict it
       // did not name, so a new one would mint a plan with no warning and then be refused at
       // apply time with no hint of why. Exhaustive here means a new verdict cannot be forgotten.
-      switch (verdict.status) {
-        case 'proven':
-        case 'fresh-target':
-        case 'no-git':
-          break;
-        case 'revert':
-        case 'drift':
-          warn(`descent: ${verdict.reason}`);
-          warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
-          break;
-        case 'unknown-commit':
-          // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit.
-          warn(`descent: ${verdict.reason}`);
-          warn('db:apply from this checkout will refuse this plan until you fetch that commit — fetch, then re-mint.');
-          break;
-        case 'unverifiable':
-          // NOT "rebase first" — nothing is wrong with the checkout or the database. The
-          // search could not read an ancestor state, so the rule is unproven either way.
-          warn(`descent: ${verdict.reason}`);
-          warn('db:apply from this checkout will refuse this plan until that search completes — re-mint and try again.');
-          break;
-      }
+      for (const line of describePlanDescent(verdict)) warn(line);
     }
 
     // Visibility, never automation (brick 8): the review surface names the

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

@@ -236,10 +236,12 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       // as exemptions too would double-book them — declared and exempted at once.
       pulledExemptions = ungovernedGrants(contract, new Set([...ALWAYS_GOVERNED, ...governRoles]));
       // A6's advisory. A blanket `GRANT USAGE ON ALL SEQUENCES` beside a blanket SELECT is a
-      // common brownfield shape, and the inheritance rule never touches it — the rule only ADDS
-      // what an INSERT needs — so it would sit unnoticed forever. Named, never revoked: revoking
-      // it would be the tool deciding a security property from an inference.
-      for (const line of renderVestigialSequenceGrants(vestigialSequenceGrants(contract))) caution(line);
+      // common brownfield shape. The advisory says exactly what the next db:plan will do with it,
+      // so it must see the SAME governed set the plan will use: the vocabulary plus --govern-roles.
+      // (With the default set, a --govern-roles grantee was told "not governed, nothing revokes
+      // it" while the plan minted the REVOKE — closing-gate review, 2026-09-07.)
+      const governedAtPull = new Set<string>([...ALWAYS_GOVERNED, ...governRoles]);
+      for (const line of renderVestigialSequenceGrants(vestigialSequenceGrants(contract), governedAtPull)) caution(line);
       pulledFingerprint = fingerprintLive(current, contract).hash;
     }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the

package/src/cli/git-descent.ts

@@ -17,15 +17,24 @@
  * 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.
+ * brownfield tables ride through the test). Identity is the models-directory
+ * TREE, not the commit: a cherry-picked identical state is the same declared
+ * state.
+ *
+ * A fingerprint NO commit on ANY ref declares is DRIFT, and proven drift is the
+ * operator's decision the design promised: it PASSES at apply. The rule exists to
+ * stop an apply from reverting MERGED work, and when no ref anywhere declares the
+ * live state there is no merged work to revert — by construction. The proof is
+ * refuse-closed: a ref you do not descend from that DOES declare live refuses by
+ * name (`declared-elsewhere`, a teammate got there first); a tree that could not be
+ * read, or a clone that is shallow, partial, or behind a remote, is UNVERIFIABLE,
+ * never drift. `--force-descent` used to be the operator's drift decision; its
+ * retirement (2026-08-26) left drift with no escape at all, and a consumer walked
+ * into that dead end on 2026-09-07. The proof replaced the flag (Fable-ruled).
  */
 
 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';
@@ -107,7 +116,10 @@ export function enumerateModelTrees(
   // `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'];
+  // `--all` walks refs/stash too. A stash is a WIP snapshot, never a deployed state: one that will
+  // not compile would poison the drift proof to unverifiable, and one that happens to match live
+  // would be named as a teammate's deployment. Excluded here and in refsContaining, consistently.
+  const range = opts.ancestorsOf ? [opts.ancestorsOf] : ['--exclude=refs/stash', '--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);
@@ -213,7 +225,7 @@ 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 — ${err.message}` };
+      return { kind: 'unevaluated', detail: `${where}: could not extract — ${firstLine(err.message)}` };
     }
   }
 
@@ -228,6 +240,12 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
 
   const evaluate = async (): Promise<boolean> => {
     const models = await ctx.loader(barrelPath);
+    // A barrel that compiles to ZERO models declares NOTHING. The prediction rides every
+    // undeclared live table through unchanged, so an empty models array "predicts" any live
+    // state exactly — it would declare every database there is. Absent barrel and empty barrel
+    // are the same clean 'no'. (Closing-gate review round 2, 2026-09-07: on a side branch this
+    // minted a false declared-elsewhere; as a HEAD ancestor it silently proved a fast-forward.)
+    if (models.length === 0) return false;
     const governedRoles = governedRolesForModels(models);
     const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: ctx.schema, governedRoles });
     return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
@@ -241,15 +259,61 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
     }
     return declares ? { kind: 'declares' } : { kind: 'no' };
   } catch (err: any) {
-    return { kind: 'compile-failed', detail: `${where}: ${err.message}` };
+    return { kind: 'compile-failed', detail: `${where}: ${firstLine(err.message)}` };
+  }
+}
+
+/**
+ * A compile/extraction error, summarized for a refusal that is RECORDED in a shared stage's
+ * schema_log: the cause, never the operator's filesystem.
+ *
+ *  - MODULE_NOT_FOUND: line 1 is the cause ("Cannot find module '@everystack/model'"); the
+ *    `Require stack:` that follows is absolute local paths — dropped.
+ *  - An esbuild TransformError (the "older tree that no longer builds" case): line 1 is only the
+ *    header "Transform failed with 1 error:" and the cause is on line 2 — kept, with the sandbox
+ *    path prefix stripped so what remains is `db/models/index.ts:2:0: ERROR: …`.
+ *  - An empty message says so instead of rendering nothing.
+ *
+ * (Closing-gate review round 5: a bare first-line take blanked the cause on exactly the class the
+ * `unverifiable` message exists to explain.)
+ */
+export function summarizeCompileError(message: unknown): string {
+  const lines = String(message ?? '').split('\n').map((l) => l.trimEnd());
+  const stop = lines.findIndex((l) => /^\s*Require stack:/.test(l));
+  const useful = (stop === -1 ? lines : lines.slice(0, stop)).filter((l) => l.trim().length > 0);
+  if (useful.length === 0) return '(error with no message)';
+  const take = /^Transform failed with \d+ errors?:?$/.test(useful[0].trim()) && useful.length > 1 ? useful.slice(0, 2) : useful.slice(0, 1);
+  return take
+    .map((l) => l.replace(/\/[^\s:'"]*\.everystack-descent-[^/\s]+\/[0-9a-f]+\//g, '').trim())
+    .join(' — ');
+}
+const firstLine = summarizeCompileError;
+
+/**
+ * Where historical trees materialize so that the materialized barrel can `import '@everystack/model'`:
+ * node walks UP from the importing file, so the sandbox must sit below a `node_modules` that holds
+ * the package. That is the nearest `node_modules` ABOVE THE MODELS BARREL, not the repo root's —
+ * 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).
+ */
+export function materializeBase(repoRoot: string, modelsAbs: string): string {
+  let dir = path.dirname(modelsAbs);
+  while (dir.startsWith(repoRoot)) {
+    const nm = path.join(dir, 'node_modules');
+    if (fs.existsSync(nm)) return nm;
+    if (dir === repoRoot) break;
+    dir = path.dirname(dir);
   }
+  return repoRoot;
 }
 
 /** 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 {
+): { repoRoot: string; head: string; modelsDir: string; barrel: string; modelsAbs: string } | null {
   const cwd = opts.cwd ?? process.cwd();
   const rootOut = git(['rev-parse', '--show-toplevel'], cwd);
   if (rootOut === null) return null;
@@ -261,7 +325,7 @@ function resolveRepoContext(
   // /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);
-  return { repoRoot, head, modelsDir: path.dirname(rel) || '.', barrel: path.basename(modelsAbs) };
+  return { repoRoot, head, modelsDir: path.dirname(rel) || '.', barrel: path.basename(modelsAbs), modelsAbs };
 }
 
 /** `git cat-file -e <ref>^{commit}` — is the commit present in THIS clone (not a shallow gap)? */
@@ -314,6 +378,13 @@ 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;
+  /**
+   * 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
+   * models and cannot be `--contains`-tested (git errors on a non-commit), so currency skips it.
+   * Optional: a probe without it treats every tip as a commit (refuse-closed).
+   */
+  peelsToCommit?(sha: string): boolean | null;
 }
 
 export type LineageProof =
@@ -422,6 +493,10 @@ export function realLineageProbe(cwd: string): GitLineageProbe {
       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);
     },
+    peelsToCommit: (sha) => {
+      if (!commitPresent(sha, cwd) && run(['cat-file', '-e', sha]) === null) return null; // absent
+      return run(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]) !== null;
+    },
   };
 }
 
@@ -451,10 +526,25 @@ export interface DescentLedgerRow {
   dirty: boolean;
   /** When the apply landed — for the REVERT message (names the commit + date). */
   appliedAt: string;
-  /** Only a successful state apply is a witness. */
+  /** Only a successful state apply is a witness: `applied`, or `applied — <descent note>`. */
   outcome: string;
 }
 
+/** A successful state apply, with or without a recorded descent note (`applied — …`). */
+export const isAppliedOutcome = (outcome: string): boolean => outcome === 'applied' || outcome.startsWith('applied — ');
+
+/**
+ * Where a proven drift came from — informs the warning and the schema_log note, never the
+ * verdict (the ledger is a memoir, decision 7). `never-declared`: no successful state apply is
+ * recorded here — first adoption of a database everystack never wrote. `hand-edited`: everystack
+ * did apply here once (the newest such row is named), and the database has moved since, outside
+ * the tool.
+ */
+export type DriftOrigin =
+  | { kind: 'never-declared' }
+  /** `dirty`: that last apply ran from a dirty worktree, so its commit never declared what it applied. */
+  | { kind: 'hand-edited'; commit: string | null; appliedAt: string; dirty?: boolean };
+
 export type ProveVerdict =
   /** The database has no tables — first apply bootstraps it. */
   | { status: 'fresh-target' }
@@ -466,19 +556,94 @@ export type ProveVerdict =
   | { 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. */
+  /** A ref HEAD does not descend from declares the live state — a teammate's merged work. */
+  | { status: 'declared-elsewhere'; commit: string; reason: string }
+  /** The search could not read every tree, or the clone is not full and current — 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 };
+  /** Every tree on every ref read cleanly in a full, current clone, and none declares live —
+   *  PROVEN drift. Passes at apply: nothing merged exists to revert. */
+  | { status: 'drift'; reason: string; scannedTrees: number; origin: DriftOrigin };
 
 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>>;
+  /** The git probe the drift proof uses to establish the clone is full and current.
+   *  Default: {@link realLineageProbe} over the repo root. Injected so tests can prove each
+   *  currency refusal without a remote. */
+  probe?: GitLineageProbe;
 }
 
 const shortDate = (at: string): string => at.slice(0, 10);
 
+/**
+ * The origin, in words — ONE rendering for the plan warning, the apply warning, and the recorded
+ * note, so the dirty-worktree sub-case can never be surfaced in one place and dropped in another
+ * (closing-gate review round 4: the flag was computed and reached no human and no record).
+ *
+ *   never-declared                      — no everystack apply is recorded here
+ *   hand-edited since <sha>, <date>     — everystack applied from that commit; the database moved since
+ *   applied from a DIRTY worktree at <sha>, <date> — that commit never declared what was applied,
+ *                                          so nothing committed can declare this state
+ */
+export function describeDriftOrigin(origin: DriftOrigin, opts: { human?: boolean } = {}): string {
+  if (origin.kind === 'never-declared') return opts.human ? 'never declared: no everystack apply is recorded here' : 'never-declared';
+  const at = origin.commit ? `${short(origin.commit)}, ${shortDate(origin.appliedAt)}` : `an apply on ${shortDate(origin.appliedAt)}`;
+  return origin.dirty ? `applied from a DIRTY worktree at ${at}` : `hand-edited since ${at}`;
+}
+
+/** The recorded note for a proven drift — goes in the apply row's schema_log outcome. */
+export function driftOriginNote(origin: DriftOrigin): string {
+  return `descent: drift-origin proven (${describeDriftOrigin(origin)})`;
+}
+
+/**
+ * Is this clone full and current with every remote? The drift proof's precondition: "no ref
+ * anywhere declares live" is only a claim we may make when we hold every ref there is. Same
+ * probe as the lineage proof, but the question differs — currency, not the fate of one commit —
+ * so an empty remote set is simply current (a purely local repo has nothing to be behind).
+ * Refuse-closed: a failed `git remote` or an unreachable remote is NOT current.
+ *
+ * The test is REF reachability, never object presence. The scan this guards is `git rev-list
+ * --all`, which walks refs; an advertised tip that is present as an object but contained by no
+ * ref (a `git fetch origin <branch>` that wrote only FETCH_HEAD, or a locally deleted branch
+ * the remote still has) is invisible to the scan and MUST count as behind. Testing
+ * `objectExists` here let exactly that tip satisfy currency while the scan missed the models
+ * it declared — found by the closing-gate review 2026-09-07, before it shipped.
+ */
+export function proveCloneCurrent(git: GitLineageProbe): { current: true } | { current: false; reason: string } {
+  if (git.isShallow()) {
+    return { current: false, reason: 'this is a shallow clone, so a ref that declares the live state may simply not be here — unshallow first (git fetch --unshallow), then re-run.' };
+  }
+  if (git.isPartial()) {
+    return { current: false, reason: 'this is a partial clone, so objects can be missing locally — fetch the full history, then re-run.' };
+  }
+  const remotes = git.remotes();
+  if (remotes === null) {
+    return { current: false, reason: "could not list this repo's git remotes to confirm the clone is current — retry, or fetch the remotes first." };
+  }
+  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.` };
+    }
+    for (const tip of tips) {
+      // refs/stash is excluded from the scan (enumerateModelTrees), so a tip contained ONLY by a
+      // stash counts as behind here — the two sides of the currency proof see the same refs, and
+      // this direction is refuse-closed. The probe itself stays raw: for the lineage proof a stash
+      // that reaches a commit is a REACHABLE commit, and filtering it there would fall open.
+      if (git.refsContaining(tip).filter((ref) => ref !== 'refs/stash').length === 0) {
+        // A tip we HOLD that is not a commit and peels to none (a tag on a blob or tree — the
+        // `junio-gpg-pub` shape) carries no models and can never be contained by a ref; it is
+        // not evidence of being behind. An ABSENT tip, or a present commit no ref contains, is.
+        if (git.peelsToCommit && git.peelsToCommit(tip) === false) continue;
+        return { current: false, reason: `this clone is behind ${remote} (it advertises ${short(tip)}, which no ref here contains) — fetch it first (git fetch ${remote} --tags); a ref there may declare the live state.` };
+      }
+    }
+  }
+  return { current: true };
+}
+
 /**
  * The fast-forward proof, ledger-first. Refuse-closed: no inconclusive branch passes.
  *
@@ -508,7 +673,7 @@ export async function proveDescent(
 
   const ctx = resolveRepoContext(modelsPath, opts);
   if (ctx === null) return { status: 'no-git' };
-  const { repoRoot, head, modelsDir, barrel } = ctx;
+  const { repoRoot, head, modelsDir, barrel, modelsAbs } = 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
@@ -516,7 +681,7 @@ export async function proveDescent(
   // 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 (!isAppliedOutcome(r.outcome)) 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
@@ -554,9 +719,26 @@ export async function proveDescent(
   // ---- Phase B: no usable ledger witness → ancestor-restricted recompile. ----
   const candidates = enumerateModelTrees(modelsDir, repoRoot, { ancestorsOf: head });
 
-  const nodeModules = path.join(repoRoot, 'node_modules');
+  // 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: 'unverifiable',
+      reason:
+        '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 and re-run.',
+      unevaluated: [],
+      compileFailures: [],
+    };
+  }
+
+  // Historical trees materialize INSIDE the project, below the nearest node_modules above the
+  // models barrel — see materializeBase. Never the OS temp dir.
   const materializeRoot = opts.materializeRoot
-    ?? fs.mkdtempSync(path.join(fs.existsSync(nodeModules) ? nodeModules : os.tmpdir(), '.everystack-descent-'));
+    ?? fs.mkdtempSync(path.join(materializeBase(repoRoot, modelsAbs), '.everystack-descent-'));
   const ownsRoot = !opts.materializeRoot;
   const evalCtx: EvalContext = {
     repoRoot,
@@ -569,6 +751,28 @@ export async function proveDescent(
 
   const compileFailures: string[] = [];
   const unevaluated: string[] = [];
+  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];
+    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}` : ''}`,
+      unevaluated,
+      compileFailures,
+    };
+  };
+
+  let others: ModelTreeCandidate[] = [];
   try {
     for (const candidate of candidates) {
       const result = await evaluateTree(candidate, live, evalCtx);
@@ -586,79 +790,113 @@ export async function proveDescent(
       const ancestor = candidate.commits.find((commit) => isAncestor(commit, head, repoRoot)) ?? candidate.commits[0];
       return { status: 'proven', via: 'recompile', commit: ancestor };
     }
+
+    // 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) return unverifiable('ancestor', candidates.length);
+
+    // ---- Phase C: the drift proof — no ancestor declares live, so scan EVERY ref. ----
+    // The fast-forward rule protects MERGED work. Before calling the live state undeclared, look
+    // at every tree on every ref this clone holds: one that declares live belongs to a line of
+    // history HEAD does not descend from — a teammate deployed it — and applying our edge would
+    // revert it. That refuses BY NAME. Only when no tree anywhere declares live is there nothing
+    // to protect.
+    const seen = new Set(candidates.map((c) => c.tree));
+    const all = enumerateModelTrees(modelsDir, repoRoot);
+    // The all-refs walk must be a SUPERSET of the ancestor walk — every ancestor tree is reachable
+    // from `--all`. When it is not, `git rev-list --all` failed (a broken or dangling ref makes it
+    // exit 128 while the ancestor walk still succeeds) and returned nothing, which is NOT "no
+    // other refs". Reading an empty result as "nothing else declares live" fell open to drift;
+    // found by the closing-gate review 2026-09-07.
+    const allTrees = new Set(all.map((c) => c.tree));
+    if ([...seen].some((tree) => !allTrees.has(tree))) {
+      return {
+        status: 'unverifiable',
+        reason:
+          'cannot verify the fast-forward rule — the walk over EVERY ref (git rev-list --all) did not ' +
+          'return the trees the ancestor walk did, so it failed part-way: a broken or dangling ref ' +
+          '(run `git fsck`, prune the bad ref) or a git error. That is a limit of THIS clone, not ' +
+          'evidence about the database — it is NOT drift. Repair the ref and re-run.',
+        unevaluated,
+        compileFailures,
+      };
+    }
+    // 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));
+    if (!currency.current) {
+      return {
+        status: 'unverifiable',
+        reason:
+          `cannot verify the fast-forward rule — no ancestor of your checkout declares the live state, and ` +
+          `${currency.reason} That is a limit of THIS clone, not evidence about the database — it is NOT drift.`,
+        unevaluated,
+        compileFailures,
+      };
+    }
+    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);
+        continue;
+      }
+      if (result.kind === 'no') continue;
+      const commit = candidate.commits[0];
+      return {
+        status: 'declared-elsewhere',
+        commit,
+        reason:
+          `a ref your checkout does NOT descend from declares the target's live state — commit ` +
+          `${short(commit)} carries the models that match it. Someone deployed from that line of ` +
+          'history; applying your edge would revert their work. Fetch and merge or rebase onto it, ' +
+          'then re-plan.',
+      };
+    }
   } finally {
     if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
   }
 
-  // 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: 'unverifiable',
-      reason:
-        '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,
-    };
-  }
-
-  // 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: 'unverifiable',
-      reason:
-        `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,
-    };
-  }
-
-  return {
-    status: 'drift',
-    scannedTrees: candidates.length,
-    reason:
-      `no ancestor of your checkout declares the target's live fingerprint ` +
-      `${short(fingerprintLive(live.snapshot, live.contract).hash)} — read ${candidates.length} ` +
-      'ancestor model state(s), all cleanly, and none matches. Either this database has never been ' +
-      'adopted into Models (nothing committed can declare it — the first-adoption case), or it ' +
-      'drifted after adoption. THE RUNBOOK: run everystack db:adopt — it renders Models from the ' +
-      'live database and PROVES they declare it exactly (it REFUSES rather than paper over any ' +
-      'difference); commit AND push that baseline, then re-run db:plan / db:apply and it descends ' +
-      'normally. If instead your Models are the source of truth and the database drifted, reconcile ' +
-      'with db:generate, or waive the rule deliberately.',
-  };
-}
-
-/**
- * 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 };
-  }
+  const scannedTrees = candidates.length + others.length;
+  // A side branch we could not read is not evidence either — refuse-closed, naming the count so
+  // the operator can prune the branch that carries it.
+  if (unevaluated.length > 0 || compileFailures.length > 0) return unverifiable('reachable', scannedTrees);
+
+  // PROVEN DRIFT (the clone was proven full and current before the all-refs scan). The origin is
+  // read from the ledger for the MESSAGE only (memoir, not control): any successful state apply
+  // recorded here means everystack once wrote this database and it has moved since; none means
+  // 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' };
+  const fp = short(fingerprintLive(live.snapshot, live.contract).hash);
+  // The scan is scoped to THIS checkout's models path: a ref that declares live from a different
+  // directory (a models move on another line of history) is outside it. Say so — the claim must
+  // be exactly as wide as the search.
+  const scanned = `read ${scannedTrees} model state(s) at ${modelsDir}/ across every ref of a full, current clone, all cleanly, and none matches`;
+  const runbook =
+    'The reviewed plan you mint is the ORIGIN: `everystack db:plan --stage <name>` mints it, ' +
+    '`everystack db:apply --plan <file> --stage <name>` applies it, warns, and records the origin ' +
+    'in schema_log; every later apply descends from that row.';
+  const reason = origin.kind === 'never-declared'
+    ? `no commit on any ref declares the target's live fingerprint ${fp} — ${scanned}. Nothing has ever ` +
+      'declared this database (no everystack state apply is recorded here), so there is no merged work ' +
+      `the fast-forward rule could protect. ${runbook}`
+    : `no commit on any ref declares the target's live fingerprint ${fp} — ${scanned}. everystack last ` +
+      `applied here ${origin.commit ? `at commit ${short(origin.commit)} ` : ''}on ${shortDate(origin.appliedAt)}` +
+      (origin.dirty
+        ? ' from a DIRTY worktree — that commit never declared what was applied, so nothing committed can declare this state. '
+        : ', and the database has been changed outside the tool since (hand-edited). No ref declares what it is now, so ') +
+      `there is no merged work the fast-forward rule could protect; your committed Models are the source of truth. ${runbook}`;
+  return { status: 'drift', scannedTrees, origin, reason };
 }
 
 // ---------------------------------------------------------------------------
@@ -681,8 +919,9 @@ export interface DescentApplyContext {
 }
 
 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' } }
+  /** Proceed. `attested` is set only when the attestation was honoured — record it in schema_log.
+   *  `note` is set for a proven drift — its origin, recorded in schema_log the same way. */
+  | { ok: true; attested?: { commit: string; subcase: 'revert-unreachable' | 'unknown-commit-proven-absent' }; note?: string }
   | { ok: false; reason: string };
 
 /** A short recorded note for a honoured attestation — goes in the apply row's schema_log outcome. */
@@ -703,17 +942,42 @@ export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyConte
         ? { 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.
+      // PROVEN drift is the operator's decision: no ref anywhere declares live, so there is no merged
+      // work to revert. It passes, and its origin is recorded. An attestation here is a category
+      // error — there is no single declaring commit to attest about — refused as one.
+      if (ctx.attestation) {
+        return {
+          ok: false,
+          reason: `--attest-lineage-lost does not apply here: there is no single declaring commit to attest about. ${verdict.reason} Proven drift needs no attestation — drop the flag and re-run.`,
+        };
+      }
+      return { ok: true, note: driftOriginNote(verdict.origin) };
+
+    case 'unverifiable':
+      // The search could not finish (an unreadable tree, or a clone that is not full and current).
+      // The verdict carries its own fetch/retry runbook; nothing to attest ABOUT.
       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.`,
+          ? `--attest-lineage-lost does not apply here: there is no single declaring commit to attest about. ${verdict.reason}`
+          : verdict.reason,
       };
 
+    case 'declared-elsewhere': {
+      // A commit on a ref we hold declares live and HEAD does not descend from it. Reachable by
+      // 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.` };
+      }
+      const proof = ctx.proveLineage(verdict.commit);
+      return proof.proven
+        ? { ok: true, attested: { commit: verdict.commit, subcase: proof.subcase } }
+        : { ok: false, reason: proof.reason };
+    }
+
     case 'revert':
     case 'unknown-commit': {
       // These name a declaring commit. Without an attestation the flagless escape (git revert / fetch)

package/src/cli/index.ts

@@ -370,14 +370,14 @@ Usage:
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --govern-roles <r1,r2> (with --abilities live) transcribes the named FOREIGN roles' grants into privileges — the models then OWN them, so a fresh build recreates them; required for migration deletion when the migrations created grants to an ops/connection role. Explicit only (a re-pull must not silently govern), complete-or-refuse (a listed role holding a column-scoped grant fails the pull before anything is written). --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
-  everystack db:adopt          [--stage <name> | --database-url <url>] [--schema public] [--out db/models] [--govern-roles r1,r2]  First-time adoption of a pre-Models database, BY PROOF. A production DB that never went through Models has no committed ancestor declaring it, so db:apply refuses it as unverifiable drift and no waiver fits. db:adopt renders field() Models from the live DB (the same renderers db:pull uses, --abilities live), compiles them back, and finalizes the baseline ONLY when the compiled Models declare the live state EXACTLY (predicted == governed live — the same declares-test descent and db:check use). On success it writes --out (default db/models) and prints the \`chore(db): adopt live baseline <fp>\` commit — that commit legitimately declares the live state, so a later db:apply descends for real. PROVE not attest: there is NO bypass flag. When the round-trip is not exact, adoption REFUSES, names the surfaces that diverged, prints the db:generate edge, and writes NOTHING. Commit AND push the baseline before db:apply — an unpushed baseline is an unknown commit to teammates and the ops Lambda.
+  everystack db: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.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--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 the declared descriptors, 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> [--direct] | --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; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line)
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>]  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 — a descent refusal is escaped git-natively: git revert the declaring commit → db:generate → db:plan → db:apply, so the rollback is a recorded forward move; --attest-lineage-lost <sha> waives the rule ONLY for a declaring commit proven gone from every ref), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>]  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 — it protects MERGED work: a commit on any ref that declares the live state and is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a declaring commit proven gone from every ref. When NO commit on ANY ref declares the live state — a database everystack never wrote, or one hand-edited since its last apply — the rule has nothing to protect: over a full, current clone that is PROVEN DRIFT, the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A shallow, partial, or behind-remote clone, or a models tree that will not compile, is UNVERIFIABLE and refuses with a fetch/prune runbook), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
   everystack db:build          --database-url <url> [--models <barrel>]  Build a database FROM the models and KEEP it — the fresh-database bootstrap a deleted migration folder is replaced BY. Runs the same compose db:check proves buildability with (extensions -> schemas -> contract roles -> declared functions -> state -> derived layer), against a real target, then reports MATCH. Venue is EXPLICIT: --database-url only, never the ambient environment, because this writes a whole schema. REFUSES a database that already holds objects — evolving an existing one is db:sync (dev) or db:plan -> db:apply (a stage). Contract roles are created NOLOGIN if absent, and roles are cluster-level
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), 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:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only

package/src/cli/state-apply.ts

@@ -314,9 +314,12 @@ export interface StateApplyOptions {
   /** Injectable clock for tests. */
   now?: () => number;
   /**
-   * When the fast-forward rule was waived by a `--attest-lineage-lost` attestation, a short note read
-   * at WRITE time (a getter, because the attestation is decided in the descent step that runs before
-   * this) and folded into the `applied` schema_log outcome — the durable audit of a deliberate waiver.
+   * What descent decided, folded into the schema_log outcome as `applied — <note>`: a honoured
+   * `--attest-lineage-lost` waiver, or a PROVEN DRIFT origin (`descent: drift-origin proven
+   * (never-declared | hand-edited since … | applied from a DIRTY worktree at …)`) — the record that makes this row the origin every
+   * later apply descends from. Read at WRITE time (a getter, because the decision is made in the
+   * descent step that runs before this). The witness query matches `applied%`, so an annotated
+   * row is still a witness.
    */
   descentNote?: () => string | undefined;
 }