@everystack/cli 0.4.76 → 0.4.78

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.78] - 2026-09-07
+
+### Fixed
+
+- the adoption report describes the plan it ships with
+- the unreadable-tree refusal names the refs that carry each tree and leads with the fix the ledger supports
+- a squashed successor proves the fast-forward; the attest resolves through git; the plan predicts the apply; an empty edge names what carries the hash difference
+- closing-gate round 1 — app-only squash, squash proof recorded and announced, bounded runbook, scrubbed errors, git timeouts
+- closing-gate round 2 — doc matches the shipped squash rule, the round-1 fixes are pinned, every git call is bounded, the squash guard refuses when git cannot answer
+
+## [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.78",
   "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-adoption-class.ts

@@ -30,7 +30,8 @@
 
 import { matchPolicies, roleSetEqual } from './authz-identity';
 import { governedRoleSet } from './authz-reconcile';
-import { effectivePolicyCheck, holdsPrivilege, isPolicyDead, policyCommands } from './authz-contract';
+import { tablePoliciesEquivalent } from './authz-canonical';
+import { effectivePolicyCheck, holdsPrivilegeEffective, isPolicyDead, policyCommands } from './authz-contract';
 import type { AuthzContract, PolicyContract, TableContract } from './authz-contract';
 
 export type AdoptionClass = 'convention' | 'capability' | 'narrowing' | 'dead' | 'unclassified';
@@ -78,24 +79,66 @@ function covers(outer: readonly string[], inner: readonly string[]): boolean {
   return inner.every((r) => o.has(r));
 }
 
-/** Same authorization on every axis EXCEPT which roles it names — the role-split test. */
-function sameRule(a: PolicyContract, b: PolicyContract): boolean {
-  return a.command === b.command
-    && a.permissive === b.permissive
-    && (a.using ?? '') === (b.using ?? '')
-    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
+/**
+ * The predicate slots ONE command enforces — the same fan the canonical form uses. SELECT and
+ * DELETE have no WITH CHECK; INSERT has no USING and its check falls back to USING when the
+ * source is a `FOR ALL` with no explicit check (the server's own defaulting rule); UPDATE and
+ * ALL carry both. Comparing policies through this is what lets a declared INSERT be measured
+ * against the INSERT arm of a live ALL instead of against a USING the INSERT never had.
+ */
+function armOf(p: PolicyContract, command: string): { using: string; check: string } {
+  const using = command === 'INSERT' ? '' : (p.using ?? '');
+  // ONE definition of the server's WITH CHECK defaulting rule — effectivePolicyCheck, shared with
+  // the matcher, the reconciler and the retained v10 canon.
+  const check = command === 'SELECT' || command === 'DELETE' ? '' : (effectivePolicyCheck(p) ?? '');
+  return { using, check };
 }
 
 /**
- * A policy's predicate, collapsed to one line for the report.
+ * Same authorization on every command the replacement governs, roles aside — the role-split and
+ * per-command tests. Arm for arm, so a live `FOR ALL USING (x)` is the same rule as a declared
+ * `INSERT WITH CHECK (x)` on INSERT. Whether the replacement covers EVERY live command is a
+ * separate question (`aliveCommands`), answered by the caller.
+ */
+function sameRule(r: PolicyContract, live: PolicyContract): boolean {
+  if (r.permissive !== live.permissive) return false;
+  const liveCommands = commandsOf(live);
+  return commandsOf(r).every((cmd) => {
+    if (!liveCommands.includes(cmd)) return false;
+    const a = armOf(r, cmd);
+    const b = armOf(live, cmd);
+    return a.using === b.using && a.check === b.check;
+  });
+}
+
+/** The commands a live policy actually governs — the arms some role it names holds the grant for. */
+function aliveCommands(t: TableContract, p: PolicyContract): string[] {
+  const roles = p.roles.includes('public') || p.roles.includes('PUBLIC')
+    ? Object.keys(t.effectivePrivileges ?? t.grants)
+    : p.roles;
+  return commandsOf(p).filter((cmd) => roles.some((r) => holdsPrivilegeEffective(t, r, cmd)));
+}
+
+/**
+ * A policy's predicate, collapsed to one line for the report, in the slot its command enforces:
+ * an INSERT is shown by its WITH CHECK (it has no USING — rendering one printed
+ * "true (unfiltered)" for every INSERT policy, which is what the consumer read as an unfiltered
+ * rule); UPDATE and ALL show both halves when they differ; SELECT and DELETE show USING.
  *
  * Live predicates arrive from `pg_get_expr` with real newlines and indentation (an EXISTS
  * subquery spans several lines), and the adoption report is one line per statement. Collapsing
  * keeps the rule READABLE in place rather than referring the operator elsewhere to find it.
  */
 function pred(p: PolicyContract): string {
-  const using = (p.using ?? 'true').replace(/\s+/g, ' ').trim();
-  return using === 'true' ? 'true (unfiltered)' : using;
+  const one = (s: string | null | undefined): string => {
+    const t = (s ?? 'true').replace(/\s+/g, ' ').trim();
+    return t === 'true' ? 'true (unfiltered)' : t;
+  };
+  if (p.command === 'INSERT') return `WITH CHECK ${one(p.check)}`;
+  if (p.command === 'SELECT' || p.command === 'DELETE') return `USING ${one(p.using)}`;
+  const using = one(p.using);
+  const check = one(p.check ?? p.using);
+  return check === using ? `USING ${using}` : `USING ${using} WITH CHECK ${check}`;
 }
 
 // `commandsOf` and the dead-policy test live in authz-contract — ONE definition, shared with
@@ -106,6 +149,16 @@ const isDead = isPolicyDead;
 /** Classify the policy statements one table would emit. */
 function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedStatement[], governed: ReadonlySet<string>): void {
   const table = d.table;
+
+  // The reconciler's own gate, mirrored (authz-reconcile reconcilePolicies, Condition B): two
+  // tables that are the SAME authorization under the canonical fan emit nothing, so there is
+  // nothing to classify. A live `FOR ALL` whose alive arms the declared per-command split covers
+  // is the shape that escaped — the per-policy matcher below cannot see it (a live ALL is never
+  // the same policy as a declared INSERT), so this classifier counted four narrowings for a plan
+  // that carried none. Gating on the same predicate the emitter gates on is the only way the
+  // two can never disagree.
+  if (tablePoliciesEquivalent(d, l, governed)) return;
+
   const m = matchPolicies(d.policies, l.policies);
   const liveByName = new Map(l.policies.map((p) => [p.name, p]));
 
@@ -144,12 +197,18 @@ function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedSta
 
     const replacementRoles = [...new Set(replacements.flatMap((r) => r.roles))];
 
+    // The COMMAND axis: which of the live policy's alive arms no replacement governs at all. A
+    // live ALL replaced by an INSERT-only declaration loses SELECT/UPDATE/DELETE — a narrowing
+    // no role or predicate comparison can see. Dead arms are not access, so they are not lost.
+    const liveAlive = aliveCommands(l, live);
+    const uncovered = liveAlive.filter((cmd) => !replacements.some((r) => commandsOf(r).includes(cmd)));
+
     // The role split: one live policy covering several roles, against the per-role policies the
     // compiler emits. Same predicate, and the declared roles union to EXACTLY the live role set,
     // so the two authorize identically for every session. Pure spelling — ours to fix (A5).
     // Note this is recognized here for LABELING before the matcher can act on it; the two must
     // agree once A5 lands, which is what the emitter-parity test pins.
-    if (roleSetEqual(live.roles, replacementRoles) && replacements.every((r) => sameRule(r, live))) {
+    if (roleSetEqual(live.roles, replacementRoles) && !uncovered.length && replacements.every((r) => sameRule(r, live))) {
       out.push({ table, subject: name, cls: 'convention', why: `live covers ${live.roles.join(' + ')} in one policy; we split it per role with the same predicate` });
       for (const r of replacements) {
         if (consumed.has(r.name)) continue;
@@ -181,21 +240,48 @@ function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedSta
     // we cannot prove is identical is reported as a reduction, and BOTH predicates are carried
     // so the operator reads the rule rather than the label.
     const sameRoleReplacements = replacements.filter((r) => r.roles.some((role) => live.roles.includes(role)));
-    if (sameRoleReplacements.length && !sameRoleReplacements.some((r) => sameRule(r, live))) {
-      const shared = [...new Set(sameRoleReplacements.flatMap((r) => r.roles.filter((role) => live.roles.includes(role))))];
+    const shared = [...new Set(sameRoleReplacements.flatMap((r) => r.roles.filter((role) => live.roles.includes(role))))];
+
+    // Same roles, same rule on every command the replacements govern, but some live command is
+    // left with no policy at all — the command-axis narrowing.
+    if (sameRoleReplacements.length && uncovered.length && sameRoleReplacements.every((r) => sameRule(r, live))) {
+      const covered = liveAlive.filter((cmd) => !uncovered.includes(cmd));
+      out.push({
+        table,
+        subject: name,
+        cls: 'narrowing',
+        why:
+          `live governs ${liveAlive.join('/')} for ${shared.join(', ')} ${pred(live)}; the declared replacement `
+          + `${sameRoleReplacements.map((r) => `"${r.name}"`).join(', ')} keeps the same rule but governs only `
+          + `${covered.join('/')} — ${uncovered.join('/')} loses its policy`,
+      });
+      for (const r of sameRoleReplacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'narrowing', why: `the narrower replacement for "${name}"` });
+      }
+      continue;
+    }
+
+    if (sameRoleReplacements.length && !sameRoleReplacements.every((r) => sameRule(r, live))) {
+      const differing = sameRoleReplacements.filter((r) => !sameRule(r, live));
       out.push({
         table,
         subject: name,
         cls: 'narrowing',
         why:
-          `live applies to ${shared.join(', ')} USING ${pred(live)}; the declared replacement `
-          + `${sameRoleReplacements.map((r) => `"${r.name}"`).join(', ')} keeps the same role(s) but states `
-          + `${sameRoleReplacements.map((r) => pred(r)).join(' / ')} — a different rule, not a different spelling`,
+          `live applies to ${shared.join(', ')} ${pred(live)}; the declared replacement `
+          + `${differing.map((r) => `"${r.name}"`).join(', ')} keeps the same role(s) but states `
+          + `${differing.map((r) => pred(r)).join(' / ')} — a different rule, not a different spelling`,
       });
       for (const r of sameRoleReplacements) {
         if (consumed.has(r.name)) continue;
         consumed.add(r.name);
-        out.push({ table, subject: r.name, cls: 'narrowing', why: `the differently-predicated replacement for "${name}"` });
+        // A replacement that DOES match its live arm exists only because the differing one forced
+        // the live policy to be replaced — our spelling, emitted for a real difference next to it.
+        out.push(sameRule(r, live)
+          ? { table, subject: r.name, cls: 'convention', why: `the per-command half of "${name}", same rule; emitted because "${differing[0].name}" differs` }
+          : { table, subject: r.name, cls: 'narrowing', why: `the differently-predicated replacement for "${name}"` });
       }
       continue;
     }
@@ -298,17 +384,21 @@ export function classifyAdoption(
  * inline is a wall nobody reads, and they are each described by their class.
  */
 export function renderAdoptionReport(counts: AdoptionCounts, statements: readonly ClassifiedStatement[] = []): string[] {
+  const row = (label: string, n: number, why: string): string => `  ${label.padEnd(18)} ${n}  — ${why}`;
   const lines = [
-    `  convention   ${counts.convention}  — our spelling, not their schema (this must reach 0)`,
-    `  capability   ${counts.capability}  — the model cannot express what is live`,
-    `  narrowing    ${counts.narrowing}  — real access reduction, approve before applying`,
-    `  dead         ${counts.dead}  — policed but never granted`,
+    row('convention', counts.convention, 'our spelling, not their schema (this must reach 0)'),
+    row('capability', counts.capability, 'the model cannot express what is live'),
+    row('narrowing (access)', counts.narrowing, 'real access reduction, approve before applying'),
+    row('dead', counts.dead, 'policed but never granted'),
   ];
   if (counts.unclassified) {
-    lines.push(`  unclassified ${counts.unclassified}  — NOT described; read these before applying:`);
+    lines.push(row('unclassified', counts.unclassified, 'NOT described; read these before applying:'));
     for (const s of statements.filter((s) => s.cls === 'unclassified')) {
       lines.push(`    ${s.table} "${s.subject}" — ${s.why}`);
     }
   }
+  // The name collision from the module header, said where the operator can see it: the plan
+  // file's `narrowings` is the DESTRUCTIVE axis (lossy type changes) and is counted elsewhere.
+  lines.push('  (access counts above are policies and grants; the plan file\'s `narrowings` counts lossy type changes — the destructive axis, reported separately)');
   return lines;
 }

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,15 @@ import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, type EdgePlan } from '.
 import {
   proveDescent,
   decideDescentApply,
+  describeDriftOrigin,
   attestationNote,
   proveLineageLost,
   realLineageProbe,
+  resolveAttestation,
   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 +112,90 @@ 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':
+      // A squash proof names BOTH commits: the carrier that is an ancestor of HEAD, and the
+      // deploying commit that is not — announcing the carrier alone as "an ancestor" hid that
+      // the proof rests on tree identity (closing-gate review, 2026-09-07).
+      return verdict.via === 'squash' && verdict.witness
+        ? { level: 'info', text: `descent: proven via squash — ${verdict.commit.slice(0, 12)} (an ancestor of HEAD) carries the models tree of the deploying commit ${verdict.witness.slice(0, 12)}, which HEAD does not descend from; recorded in schema_log.` }
+        : { 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 cwd = input.cwd ?? process.cwd();
+  const verdict = await proveDescent(input.modelsPath, input.live, input.ledger, {
+    ...(input.cwd ? { cwd: input.cwd } : {}),
+    ...(input.descent ?? {}),
+  });
+  reportDescentVerdict(verdict, { destructive: input.destructive });
+  // The attestation is resolved THROUGH git (a prefix, tag or HEAD~n → the full sha) before it is
+  // compared; a value git cannot resolve passes through and the prefix compare decides.
+  const decision = decideDescentApply(verdict, {
+    ...(input.attestation ? { attestation: resolveAttestation(input.attestation, cwd) } : {}),
+    destructive: input.destructive,
+    proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(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 +268,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 +644,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;
       },
       }),
     );