@everystack/cli 0.4.92 → 0.4.95

package/CHANGELOG.md

@@ -4,6 +4,82 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.95] - 2026-09-26
+
+### BREAKING CHANGES
+
+- descent reads schema_log and git ancestry, never historical models trees — no OOM, no minutes; when live has moved, the last recorded apply's commit must be in your history, and the schema_log note reads 'descent: drift-origin ...'
+- a destructive db:apply that records no git commit is refused
+
+### Fixed
+
+- read a schema_log written before fp_version and dirty existed
+
+## [0.4.94] - 2026-09-24
+
+### BREAKING CHANGES
+
+- db:exec refuses to write the everystack schema
+
+### Fixed
+
+- --baseline grant-checks what it adopts
+- plain output names every grantee of a multi-grantee grant
+- db:exec's DML-only guard sees rules, triggers, defaults, event triggers, extensions
+- db:exec guard round 2 — deferred triggers, inherited ledgers, track_counts, search_path
+- db:exec guard round 3 — shadowed catalogs, held cursors, re-deferred triggers
+
+## [0.4.93] - 2026-09-24
+
+### BREAKING CHANGES
+
+- a declared owner needs USAGE on its schema; db:apply refuses without it, db:provision (server 0.4.33) grants it
+
+### Fixed
+
+- name USAGE with CREATE for a missing schema; review follow-ups
+
+## [0.4.92] - 2026-09-24
+
+### Fixed
+
+- grant drift on an owned object runs as its owner
+- an apply fails unless the grants it set really converged
+- settle a built object's grants before checking convergence
+- settle statements are recorded and named; pin settle-as-owner
+
+### Documentation
+
+- a declared owner needs USAGE on its schema to grant there
+
+## [0.4.91] - 2026-09-24
+
+### Fixed
+
+- one apply revokes a grantee dropped from a replaced function
+- a lowercase public grant is PUBLIC in the function grant diff
+
+## [0.4.90] - 2026-09-23
+
+### Added
+
+- db:plan warns when the derived layer is out of sync
+
+### Fixed
+
+- db:apply reports skipped brownfield derived objects by default
+
+## [0.4.89] - 2026-09-22
+
+### Fixed
+
+- outputsDescribeStage matches SST's truncated app-name prefix
+- discoverFunction/discoverCfFunction/discoverBuckets match SST's truncated app-name prefix
+- warn once when cloudfront:ListTagsForResource is denied during distribution discovery
+- db:provision --rotate probes siteUrl on a no-CDN_URL stage
+- update refuses a missing HOST_URL with or without --stage
+- db:reconcile/db:refresh --only respects parens in function identities
+
 ## [0.4.88] - 2026-09-21
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.92",
+  "version": "0.4.95",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -182,7 +182,7 @@
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "zod": "3.25.67",
-    "@everystack/server": "0.4.32"
+    "@everystack/server": "0.4.33"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -42,7 +42,7 @@ import {
   type QueryRunner,
   type AuthzContract,
 } from './authz-contract';
-import { INTROSPECTION_SESSION, rowsOrEmpty, type SessionRunner } from './session';
+import { INTROSPECTION_SESSION, isSessionError, rowsOrEmpty, type SessionResult, type SessionRunner } from './session';
 import {
   introspectSchema,
   assembleSchema,
@@ -69,7 +69,7 @@ import {
 import { validationPendingReason, pendingValidationsAreSafe } from './apply-refusals';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 import { checkPlanPrecondition, planHash, defaultAclHash, type EdgePlan } from './edge-plan';
-import type { DescentLedgerRow } from './git-descent';
+import type { DescentLedgerRow, LedgerRead } from './git-descent';
 
 /**
  * CALLER CONTRACT (fail-closed protection lives here, not inside executeApplyPlan):
@@ -108,6 +108,8 @@ export interface ApplyPlanOptions {
      *  degrades toward REVERT/refusal, never a false pass — and the server re-verifies the lock
      *  in its own one-session read. */
     ledger: DescentLedgerRow[];
+    /** What the same read proved about the ledger — absent, present (with counts), or unreadable. */
+    ledgerRead: LedgerRead;
   }) => Promise<{ ok: true } | { ok: false; reason: string }>;
   /**
    * Destructive authority (brick 9, decisions 11+12): called only when the
@@ -141,8 +143,8 @@ export interface ApplyPlanOptions {
   now?: () => number;
   /**
    * 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
+   * honoured `--attest-lineage-lost` waiver, or a DRIFT origin (`descent: drift-origin
+   * 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.
    */
@@ -257,6 +259,7 @@ export async function liveBaseFingerprint(session: SessionRunner): Promise<LiveB
 /** The live base fingerprint AND the descent ledger, read in ONE session. */
 export interface LiveBaseAndLedger extends LiveBaseFingerprint {
   ledger: DescentLedgerRow[];
+  ledgerRead: LedgerRead;
 }
 
 /**
@@ -270,12 +273,85 @@ export interface LiveBaseAndLedger extends LiveBaseFingerprint {
  * 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 LIKE 'applied%' AND to_fingerprint IS NOT NULL
+//
+// `fp_version` and `dirty` are read through `to_jsonb` because a ledger written before they existed
+// lacks the columns until the next apply adds them (ENSURE_RECONCILER_SQL). Such rows read NULL /
+// false, which descent already skips as witnesses; naming the columns made the whole read fail.
+const LEDGER_COLUMNS = `id, to_fingerprint, git_ref,
+  (to_jsonb(s) ->> 'fp_version')::int AS fp_version,
+  COALESCE((to_jsonb(s) ->> 'dirty')::boolean, false) AS dirty,
+  applied_at, outcome`;
+
+export const SCHEMA_LOG_WITNESS_SQL = `SELECT ${LEDGER_COLUMNS}
+FROM everystack.schema_log s
+WHERE kind = 'state apply' AND outcome LIKE 'applied%'
 ORDER BY id DESC
 LIMIT 200`;
 
+/**
+ * The newest successful apply that recorded a commit — the row descent's ancestry check anchors on.
+ * Read on its own, uncapped, because 200 newer no-git applies would push it out of the witness set
+ * and turn a REVERT into a drift. Ordered by id, never applied_at: ids survive a dump restore, and
+ * clocks on different containers do not agree.
+ */
+export const SCHEMA_LOG_ANCHOR_SQL = `SELECT ${LEDGER_COLUMNS}
+FROM everystack.schema_log s
+WHERE kind = 'state apply' AND outcome LIKE 'applied%' AND git_ref IS NOT NULL
+ORDER BY id DESC
+LIMIT 1`;
+
+/** A query that cannot fail on a missing ledger — so "absent" is never a read error in disguise. */
+export const SCHEMA_LOG_PRESENT_SQL = `SELECT to_regclass('everystack.schema_log') IS NOT NULL AS present`;
+
+/** Every successful state apply and every recorded refusal — ALL rows, not the capped witness set. */
+export const SCHEMA_LOG_COUNTS_SQL = `SELECT
+  count(*) FILTER (WHERE kind = 'state apply' AND outcome LIKE 'applied%')::int AS applied,
+  count(*) FILTER (WHERE kind = 'state refusal')::int AS refusals
+FROM everystack.schema_log`;
+
+const LEDGER_STATEMENTS = [
+  { sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true },
+  { sql: SCHEMA_LOG_PRESENT_SQL, allowFailure: true },
+  { sql: SCHEMA_LOG_COUNTS_SQL, allowFailure: true },
+  { sql: SCHEMA_LOG_ANCHOR_SQL, allowFailure: true },
+];
+
+/**
+ * The witness rows and what the read proved about the ledger. A failed read is UNREADABLE, never
+ * empty: only a clean read may say no apply landed, or that none recorded a commit.
+ */
+export function ledgerFromSlots(
+  witness: SessionResult | undefined,
+  present: SessionResult | undefined,
+  counts: SessionResult | undefined,
+  anchor: SessionResult | undefined,
+): { ledger: DescentLedgerRow[]; ledgerRead: LedgerRead } {
+  // Rows that were read are always kept: a witness does not become less true because a sibling
+  // read failed. Only the claims "no apply landed" and "none anchors" need every read to succeed.
+  const ledger = mapLedgerRows(rowsOrEmpty(witness));
+  for (const row of mapLedgerRows(rowsOrEmpty(anchor))) {
+    if (!ledger.some((r) => r.id === row.id)) ledger.push(row);
+  }
+  const unreadable = (slot: SessionResult | undefined, what: string) => ({
+    ledger,
+    ledgerRead: { kind: 'unreadable' as const, reason: isSessionError(slot) ? slot.message : `no ${what} answer` },
+  });
+  if (!Array.isArray(present) || present.length !== 1) return unreadable(present, 'presence');
+  if (present[0].present !== true) return { ledger, ledgerRead: { kind: 'absent' } };
+  if (!Array.isArray(witness)) return unreadable(witness, 'witness');
+  if (!Array.isArray(counts) || counts.length !== 1) return unreadable(counts, 'count');
+  if (!Array.isArray(anchor)) return unreadable(anchor, 'anchor');
+  return {
+    ledger,
+    ledgerRead: {
+      kind: 'present',
+      applied: Number(counts[0].applied),
+      refusals: Number(counts[0].refusals),
+      anchored: anchor.length > 0,
+    },
+  };
+}
+
 function mapLedgerRows(rows: any[]): DescentLedgerRow[] {
   return rows.map((r) => ({
     id: String(r.id),
@@ -288,13 +364,10 @@ function mapLedgerRows(rows: any[]): DescentLedgerRow[] {
   }));
 }
 
-/**
- * Just the descent ledger, over one session — the stage lane already has the live state from
- * its double read, and needs only the witness rows to prove the fast-forward CLI-side.
- */
-export async function readDescentLedger(session: SessionRunner): Promise<DescentLedgerRow[]> {
-  const [rows] = await session([{ sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true }], INTROSPECTION_SESSION);
-  return mapLedgerRows(rowsOrEmpty(rows));
+/** The witness rows AND what the read proved about the ledger, in one session — what descent is handed. */
+export async function readDescentLedgerRead(session: SessionRunner): Promise<{ ledger: DescentLedgerRow[]; ledgerRead: LedgerRead }> {
+  const [witness, present, counts, anchor] = await session(LEDGER_STATEMENTS, INTROSPECTION_SESSION);
+  return ledgerFromSlots(witness, present, counts, anchor);
 }
 
 /**
@@ -314,7 +387,7 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
       // The default-privilege posture the plan's `defaultAclHash` is checked against — read in
       // the SAME session as the lock's state, so the two gates describe one instant.
       DEFAULT_ACL_SQL,
-      { sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true },
+      ...LEDGER_STATEMENTS,
     ],
     INTROSPECTION_SESSION,
   );
@@ -331,8 +404,8 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
     functions: (results[13] as any[]).map(contractFunctionRow),
     defaultAcls: results[14] as any[],
   });
-  const ledger = mapLedgerRows(rowsOrEmpty(results[15]));
-  return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract, ledger };
+  const { ledger, ledgerRead } = ledgerFromSlots(results[15], results[16], results[17], results[18]);
+  return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract, ledger, ledgerRead };
 }
 
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
@@ -342,7 +415,7 @@ export async function executeApplyPlan(
   plan: EdgePlan,
   options: ApplyPlanOptions = {},
 ): Promise<ApplyPlanResult> {
-  const { hash: live, snapshot: before, contract: beforeAuthz, ledger } = await liveBaseAndLedger(session);
+  const { hash: live, snapshot: before, contract: beforeAuthz, ledger, ledgerRead } = await liveBaseAndLedger(session);
 
   // The endpoint is FULL (it carries the ungoverned live authz through), so it is compared against
   // the RAW live hash directly — the same flavor as `from`. A plan without that flavor predates
@@ -381,8 +454,16 @@ export async function executeApplyPlan(
     return { status: 'refused', liveFingerprint: live, reason };
   }
 
+  // A destructive apply must record the commit it came from. Descent anchors on the newest apply
+  // WITH a commit, so a destructive row without one would be invisible to the next ancestry check.
+  if (plan.destructive > 0 && (options.gitRef ?? plan.gitRef) == null) {
+    const reason = 'a destructive apply must record the commit it came from, and this one has none — run db:plan and db:apply from the git checkout that declares your models.';
+    await recordRefusal(runner, plan, live, 'fast-forward rule', reason, options);
+    return { status: 'descent-refused', liveFingerprint: live, reason };
+  }
+
   if (options.checkDescent) {
-    const descent = await options.checkDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live, ledger });
+    const descent = await options.checkDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live, ledger, ledgerRead });
     if (!descent.ok) {
       await recordRefusal(runner, plan, live, 'fast-forward rule', descent.reason, options);
       return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };

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

@@ -37,15 +37,16 @@ import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, declaredGranteesOf, typ
 import {
   proveDescent,
   decideDescentApply,
-  describeDriftOrigin,
+  driftNotice,
+  newerOffHeadNotice,
   attestationNote,
   proveLineageLost,
   realLineageProbe,
   resolveAttestation,
   type DescentLedgerRow,
+  type LedgerRead,
   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';
@@ -68,7 +69,7 @@ import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '
 import { borrowedSessionRunner, type SessionRunner } from '../session';
 import { resolveConfig, opsFunction } from '../config';
 import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws';
-import { executeApplyPlan, readDescentLedger, type ApplyPlanResult } from '../apply-execute';
+import { executeApplyPlan, readDescentLedgerRead, type ApplyPlanResult } from '../apply-execute';
 import { estimateOpsRuntimeFit } from '../ops-fit';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease';
@@ -412,24 +413,23 @@ function exitOnCatchUpFailure(report: CatchUpReport): asserts report is { ok: tr
  */
 export function describeDescentVerdict(verdict: ProveVerdict, opts: { destructive?: boolean } = {}): { level: 'info' | 'warn'; text: string } | null {
   switch (verdict.status) {
-    case 'proven':
+    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.` };
+      const text = verdict.via === 'squash' && verdict.witness
+        ? `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.`
+        : `descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.`;
+      const newer = newerOffHeadNotice(verdict);
+      return newer ? { level: 'warn', text: `${text} ${newer}` } : { level: 'info', text };
+    }
     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':
+      return { level: 'warn', text: `${driftNotice(verdict.origin)} This reviewed plan is the ORIGIN; it is recorded in schema_log, and every later apply descends from it.` };
     case 'revert':
     case 'unknown-commit':
     case 'unverifiable':
@@ -458,18 +458,17 @@ export async function proveDescentForApply(input: {
   modelsPath: string;
   live: LiveState;
   ledger: DescentLedgerRow[];
+  /** What the ledger read proved. */
+  ledgerRead: LedgerRead;
   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 ?? {}),
+    ledgerRead: input.ledgerRead,
   });
   reportDescentVerdict(verdict, { destructive: input.destructive });
   // The attestation is resolved THROUGH git (a prefix, tag or HEAD~n → the full sha) before it is
@@ -569,12 +568,13 @@ async function applyPlanViaStage(
     // commit is gone from every ref.
     const { snapshot, contract } = readPair.state;
     step("Descent: reading the stage's schema_log ledger...");
-    const ledger = await readDescentLedger(lambdaSessionRunner(region, fn));
+    const { ledger, ledgerRead } = await readDescentLedgerRead(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,
+      ledgerRead,
       destructive: plan.destructive > 0,
       ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
     });
@@ -1119,12 +1119,13 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
           },
           dirty: worktreeDirty(resolveModelsPath(flags.models)),
           descentNote: () => descentAttested,
-          checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[] }) => {
+          checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[]; ledgerRead: LedgerRead }) => {
             step('Descent: proving the fast-forward rule against the schema_log ledger...');
             const result = await proveDescentForApply({
               modelsPath: resolveModelsPath(flags.models),
               live,
               ledger: live.ledger,
+              ledgerRead: live.ledgerRead,
               destructive: plan.destructive > 0,
               ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
             });

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

@@ -50,10 +50,10 @@ import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { mintEdgePlan, planHash, buildPlanSummary, explainCarriedBy, declaredGranteesOf } from '../edge-plan';
-import { proveDescent, describeDriftOrigin, proveLineageLost, realLineageProbe, type ProveVerdict, type LineageProof } from '../git-descent';
+import { proveDescent, driftNotice, newerOffHeadNotice, proveLineageLost, realLineageProbe, type ProveVerdict, type LineageProof } from '../git-descent';
 import { fingerprintLive, divergentSurfaces } from '../schema-fingerprint';
 import { predictLiveState } from '../edge-plan';
-import { readDescentLedger } from '../apply-execute';
+import { readDescentLedgerRead } from '../apply-execute';
 import { planBackfills, readBackfillLog } from '../backfill';
 import { readSqlDirIfPresent } from './db-sync';
 import { currentGitRef, classifyGeneratedStatements, classifyDestructive } from '../state-apply';
@@ -115,25 +115,20 @@ export function describePlanDescent(
     return `db:apply from this checkout will refuse this plan — ${proof.reason}`;
   };
   switch (verdict.status) {
-    case 'proven':
+    case 'proven': {
       // A squash proof is the one PROVEN shape whose deploying commit is not in the operator's
       // history — say so where a human reads the plan, as the apply record will.
-      return verdict.via === 'squash' && verdict.witness
+      const lines = verdict.via === 'squash' && verdict.witness
         ? [`descent: fast-forward proven via a squashed successor — ${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. db:apply will record that.`]
         : [];
+      const newer = newerOffHeadNotice(verdict);
+      return newer ? [...lines, newer] : lines;
+    }
     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.',
-      ];
+      return [driftNotice(verdict.origin), '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 'revert':
       return [`descent: ${verdict.reason}`, applyWillDo(verdict.commit)];
     case 'unknown-commit': {
@@ -149,9 +144,8 @@ export function describePlanDescent(
       ];
     }
     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.'];
+      // NOT "rebase first" — nothing is wrong with the checkout or the database. The ledger could not be read.
+      return [`descent: ${verdict.reason}`, 'db:apply will refuse this plan until the ledger can be read — retry, 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.
@@ -433,8 +427,8 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // the very strand apply now PROVES via the ledger and applies, telling the operator the
     // opposite of what happens. proveDescent over the same ledger apply reads keeps them agreed.
     if (plan.statements.length > 0) {
-      const ledger = await readDescentLedger(session);
-      const verdict = await proveDescent(modelsPath, { snapshot, contract }, ledger, {});
+      const { ledger, ledgerRead } = await readDescentLedgerRead(session);
+      const verdict = await proveDescent(modelsPath, { snapshot, contract }, ledger, { ledgerRead });
       // 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.

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

@@ -54,8 +54,8 @@ import { introspectDerived, type DerivedCatalog } from '../derived-introspect';
  *
  * db:pull is the only way an existing database comes in. What happens next is decided by
  * db:plan, not by a verb: an EMPTY plan means the committed Models declare the database as it
- * is (adopted — descent proves the pull commit by recompile, and every later apply descends from
- * it); a NON-EMPTY plan is the hardening edge, reviewed and applied as the origin. db:adopt used
+ * is (adopted — nothing to apply; the first real change applies as the never-declared origin, and
+ * every later apply descends from it); a NON-EMPTY plan is the hardening edge, reviewed and applied as the origin. db:adopt used
  * to bolt a proof onto this render; the proof was "would the plan be empty", so the verb is gone
  * (cli 0.4.79) and this is what replaced it. Exported so a test pins the lines and the
  * refusal-runbook lint reads them.