@everystack/cli 0.4.76 → 0.4.78

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 } 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';
@@ -70,6 +72,90 @@ import { compileTableContract } from '../authz-compile';
 import { reportPipelineLastRun } from './pipeline-run';
 import { step, success, fail, info, warn, reserveStdoutForData } from '../output';
 
+/**
+ * What db:plan says about descent at mint — SYMMETRIC with what db:apply will do, because a mint
+ * that warns "will refuse" for a plan apply then runs (or the reverse) is the lie this used to
+ * tell. Exported so a test pins every verdict's text. The `never` arm makes the switch REALLY
+ * exhaustive: a new verdict fails to compile here instead of minting a plan with no warning and
+ * refusing at apply with no hint of why.
+ */
+export function describePlanDescent(
+  verdict: ProveVerdict,
+  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 [];
+    case 'drift':
+      return [
+        `descent: NO COMMIT ON ANY REF DECLARES THIS DATABASE (${describeDriftOrigin(verdict.origin, { human: true })}) — proven over a full, current clone.`,
+        'db:apply will treat this reviewed plan as the ORIGIN: it applies, warns, and records the origin in schema_log; every later apply descends from it.',
+      ];
+    case 'declared-elsewhere':
+      return [
+        `descent: ${verdict.reason}`,
+        'db:apply from this checkout will refuse this plan — fetch and merge or rebase onto that commit, then re-mint.',
+      ];
+    case 'revert':
+      return [`descent: ${verdict.reason}`, 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).
+      return [`descent: ${verdict.reason}`, 'db:apply from this checkout will refuse this plan until that search completes — fetch or prune as it says, then re-mint.'];
+    default: {
+      // Compile-time exhaustiveness; at runtime (a verdict shape from outside this compile unit)
+      // an empty warning list is the safe value — the caller iterates it.
+      const exhaustive: never = verdict;
+      void exhaustive;
+      return [];
+    }
+  }
+}
+
 const DEFAULT_OUT = 'db.plan.json';
 
 /**
@@ -251,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,
@@ -289,28 +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.
-      switch (verdict.status) {
-        case 'proven':
-        case 'fresh-target':
-        case 'no-git':
-          break;
-        case 'revert':
-        case 'drift':
-          warn(`descent: ${verdict.reason}`);
-          warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
-          break;
-        case 'unknown-commit':
-          // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit.
-          warn(`descent: ${verdict.reason}`);
-          warn('db:apply from this checkout will refuse this plan until you fetch that commit — fetch, then re-mint.');
-          break;
-        case 'unverifiable':
-          // NOT "rebase first" — nothing is wrong with the checkout or the database. The
-          // search could not read an ancestor state, so the rule is unproven either way.
-          warn(`descent: ${verdict.reason}`);
-          warn('db:apply from this checkout will refuse this plan until that search completes — re-mint and try again.');
-          break;
-      }
+      // 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

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

package/src/cli/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)`);