@everystack/cli 0.4.77 → 0.4.79

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.79] - 2026-09-07
+
+### Removed
+
+- remove db:adopt — its proof was "would db:plan be empty", and db:plan answers that on the review surface
+
+### Added
+
+- db:pull ends with the on-ramp runbook; docs and help say the on-ramp is pull, commit, plan
+
+### Fixed
+
+- closing-gate round 1 — the as-is lane runs the shipped db:pull, the runbook is gated on --abilities live, the fixture proves live derivation, live-models.ts is gone
+
+## [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
@@ -931,6 +955,13 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [0.2.37] - 2026-06-17
 
+### Removed
+
+- remove onMutation callback — events replaces it
+- remove unused @everystack/jobs devDependency
+- remove secret auto-injection, skip SSR check for web-only updates
+- remove media asset pruning from update command
+
 ### Added
 
 - rename @everystack/updates → @everystack/cli, add db:migrate/db:seed, remove AdminSecret
@@ -982,7 +1013,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ### Fixed
 
 - normalize cache:purge --path to strip query params and ensure leading slash
-- remove unused @everystack/jobs devDependency
 - include updateId in register-web payload
 - psql Lambda-only queries, composite key notify, logging defaults
 - add AWS KVS + SigV4a as direct dependencies
@@ -1001,14 +1031,12 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - drop GetFunctionConfiguration from log group resolution
 - detect export completion to prevent static pre-rendering hang
 - rewrite secrets for SST Ion, filter EXPO_PUBLIC_* only
-- remove secret auto-injection, skip SSR check for web-only updates
 - clear Metro transform cache on export
 - worker function discovery and log group resolution for SQS subscribers
 - replace infrastructure headers with single X-Server-Debug timestamp
 - version bumps and publish fixes for cli, server, jobs
 - invalidate stale config cache on schema change
 - fall back to outputs.json for custom-named media buckets
-- remove media asset pruning from update command
 - media-sync test uses same minimatch interop as source
 - discover the Router distribution by domain and SST tags
 - use minimatch's named export — the package ships types now
@@ -1017,7 +1045,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Changed
 
-- remove onMutation callback — events replaces it
 - migrate all package schemas to everyschema canonical tables
 - lazy-load AWS SDK imports for faster CLI startup
 - drop type module from all packages, switch Jest to CJS mode

package/package.json

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

@@ -40,6 +40,7 @@ import {
   attestationNote,
   proveLineageLost,
   realLineageProbe,
+  resolveAttestation,
   type DescentLedgerRow,
   type LiveState,
   type ProveVerdict,
@@ -118,7 +119,12 @@ export function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void
 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.` };
+      // 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':
@@ -166,15 +172,18 @@ export async function proveDescentForApply(input: {
    *  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: input.attestation } : {}),
+    ...(input.attestation ? { attestation: resolveAttestation(input.attestation, cwd) } : {}),
     destructive: input.destructive,
-    proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(input.cwd ?? process.cwd())),
+    proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(cwd)),
   });
   if (!decision.ok) return { descentVerdict: { ok: false, reason: decision.reason } };
   if (decision.attested) {

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

@@ -50,7 +50,9 @@ 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, describeDriftOrigin, type ProveVerdict } from '../git-descent';
+import { proveDescent, describeDriftOrigin, 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 { planBackfills, readBackfillLog } from '../backfill';
 import { readSqlDirIfPresent } from './db-sync';
@@ -77,9 +79,42 @@ import { step, success, fail, info, warn, reserveStdoutForData } from '../output
  * 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[] {
+export function describePlanDescent(
+  verdict: ProveVerdict,
+  opts: { proveLineage?: (sha: string) => LineageProof } = {},
+): string[] {
+  // The plan predicts the apply. For a verdict that names a declaring commit, run the SAME lineage
+  // proof db:apply runs and say what it will do with it: a commit reachable from a ref → rebase
+  // onto that ref; a commit reachable from NO ref → the exact attestation apply will honour. The
+  // two surfaces disagreed once (consumer cutover, cli 0.4.77): plan said "will refuse — rebase"
+  // on a commit no ref held, and apply honoured the attest. Phase A tests OBJECT presence, so a
+  // ref-less commit still reads as a revert until the lineage proof is asked.
+  const applyWillDo = (commit: string): string => {
+    const proof = opts.proveLineage?.(commit);
+    if (!proof) return 'db:apply from this checkout will refuse this plan — rebase first, then re-mint.';
+    if (proof.proven) {
+      return `db:apply from this checkout will refuse this plan without an attestation; commit ${commit} is reachable from no ref ` +
+        `(${proof.subcase}), so it will honour --attest-lineage-lost ${commit} — or fetch the branch that had it, rebase, and re-mint.`;
+    }
+    if (proof.kind === 'reachable' && proof.ref && proof.ref !== 'HEAD') {
+      // `ref` is a full ref name, or a REMOTE name when the commit was found in a remote branch's
+      // ancestry (the probe sees advertised tips, not their branch names) — you cannot rebase onto
+      // a remote, so that case says fetch first. `HEAD` cannot reach here from a revert (the commit
+      // is not an ancestor of HEAD by construction); if it ever did, the generic reason is safer
+      // than "git fetch HEAD".
+      return proof.ref.startsWith('refs/')
+        ? `db:apply from this checkout will refuse this plan — that commit is still on ${proof.ref}; rebase onto it, then re-mint.`
+        : `db:apply from this checkout will refuse this plan — that commit is still on remote '${proof.ref}'; fetch it (git fetch ${proof.ref}), rebase onto the branch that has it, then re-mint.`;
+    }
+    return `db:apply from this checkout will refuse this plan — ${proof.reason}`;
+  };
   switch (verdict.status) {
     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
+        ? [`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.`]
+        : [];
     case 'fresh-target':
     case 'no-git':
       return [];
@@ -94,10 +129,19 @@ export function describePlanDescent(verdict: ProveVerdict): string[] {
         '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.'];
+      return [`descent: ${verdict.reason}`, applyWillDo(verdict.commit)];
+    case 'unknown-commit': {
+      // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit. Unless
+      // the lineage proof says the commit is gone from every remote too: then apply will honour the
+      // attestation, and fetching cannot help.
+      const proof = opts.proveLineage?.(verdict.commit);
+      return [
+        `descent: ${verdict.reason}`,
+        proof?.proven
+          ? applyWillDo(verdict.commit)
+          : '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).
@@ -293,7 +337,17 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       await fs.writeFile(out, body, 'utf8');
     }
 
-    for (const line of buildPlanSummary(plan)) info(line);
+    // An EMPTY edge between two different fingerprints reads as a contradiction. `from` is the
+    // target's full fingerprint (the concurrency lock at apply); `to` is the declared endpoint
+    // through the models' governed set. They differ by exactly what the plan leaves alone — name
+    // it, computed at mint from the two canonical forms, never stored on the plan.
+    const carriedBy = plan.statements.length === 0 && plan.fromFingerprint !== plan.toFingerprint
+      ? divergentSurfaces(
+        predictLiveState(models, snapshot, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) }).canonical,
+        fingerprintLive(snapshot, contract).canonical,
+      )
+      : undefined;
+    for (const line of buildPlanSummary(plan, carriedBy ? { carriedBy } : {})) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
 
     // WHY does each authorization statement exist? — the same report db:generate prints,
@@ -331,7 +385,9 @@ 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.
-      for (const line of describePlanDescent(verdict)) warn(line);
+      // A PROVEN verdict is information, as it is on the apply surface; everything else is a warning.
+      const say = verdict.status === 'proven' ? info : warn;
+      for (const line of describePlanDescent(verdict, { proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(process.cwd())) })) say(line);
     }
 
     // Visibility, never automation (brick 8): the review surface names the

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

@@ -38,6 +38,36 @@ import { fingerprintLive } from '../schema-fingerprint';
 import { ungovernedGrants, vestigialSequenceGrants, renderVestigialSequenceGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect';
+
+/**
+ * The on-ramp runbook, printed last so the operator is never left guessing what a pull is FOR.
+ *
+ * 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
+ * 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.
+ */
+export function pullOnRampRunbook(opts: { stage?: string; out?: string; abilities?: string }): string[] {
+  const target = opts.stage ? `--stage ${opts.stage}` : '--stage <name>';
+  const what = opts.out ? `the files in ${opts.out}` : 'these Models';
+  // Only a LIVE pull transcribes the database's own authz; only then can an empty plan mean
+  // "adopted as it is". A commented or public-read pull carries authored abilities — its plan is
+  // an edge to review (public-read on an existing database GRANTS public read of every table),
+  // never an adoption, and the runbook must not call it one (closing-gate review, 2026-09-07).
+  if (opts.abilities !== 'live') {
+    return [
+      `Next: author each model's abilities (db:check fails until every model declares) — for an EXISTING database, re-pull with --abilities live to derive them from the grants and policies already there. Then commit ${what} and run \`everystack db:plan ${target}\`: the plan is an edge to review, not an adoption of what is live.`,
+    ];
+  }
+  return [
+    `Next: commit ${what}, then \`everystack db:plan ${target}\`.`,
+    'EMPTY plan = adopted as it is: that commit declares the database, and every later db:apply descends from it. Nothing to apply.',
+    `NON-EMPTY plan = the hardening edge: review it, then \`everystack db:apply --plan <file> ${target}\`. No commit declares this database yet, so the reviewed plan is the ORIGIN — db:apply proves that and records it.`,
+  ];
+}
 import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract';
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
@@ -461,5 +491,6 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       note(`Committing this file ADOPTS those roles. Anything not in it — or anything that grows beyond it — refuses at db:plan.`);
     }
   }
+  for (const line of pullOnRampRunbook({ stage: flags.stage, out: flags.out, abilities })) note(line);
   process.exit(0);
 }

package/src/cli/edge-plan.ts

@@ -409,12 +409,27 @@ export function checkPlanPrecondition(plan: EdgePlan, liveFingerprint: string):
 
 const short = (hash: string): string => hash.slice(0, 12);
 
-/** Human summary of a plan — the review surface. */
-export function buildPlanSummary(plan: EdgePlan): string[] {
+/**
+ * Human summary of a plan — the review surface.
+ *
+ * `carriedBy` names what accounts for an EMPTY edge between two DIFFERENT fingerprints: `from`
+ * is the target's full fingerprint (the concurrency lock), `to` the declared endpoint through the
+ * governed set, and they differ by exactly the live objects the plan leaves alone — an ungoverned
+ * role's grants, a policy the vocabulary cannot declare. Without the name the line "the target
+ * already declares this state" under two different hashes reads as a contradiction (consumer
+ * cutover, cli 0.4.77). The caller computes it at mint from the canonical forms; it is never
+ * stored on the plan.
+ */
+export function buildPlanSummary(plan: EdgePlan, opts: { carriedBy?: string[] } = {}): string[] {
   const lines: string[] = [];
   lines.push(`edge: ${short(plan.fromFingerprint)} → ${short(plan.toFingerprint)}`);
   if (plan.statements.length === 0) {
-    lines.push('empty — the target already declares this state');
+    if (plan.fromFingerprint === plan.toFingerprint) {
+      lines.push('empty — the target already declares this state');
+    } else {
+      lines.push('empty — no statement to emit. The fingerprints differ by what the plan leaves alone: `from` is the target\'s full fingerprint (the concurrency lock), `to` the declared endpoint through the governed set'
+        + (opts.carriedBy?.length ? `; carried by: ${opts.carriedBy.join('; ')}` : '') + '.');
+    }
     return lines;
   }
   lines.push(`${plan.executable} executable statement(s), ${plan.notices} notice(s)`);