@everystack/cli 0.4.69 → 0.4.71

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

@@ -50,7 +50,8 @@ 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 { verifyDescent } from '../git-descent';
+import { proveDescent } from '../git-descent';
+import { readDescentLedger } from '../apply-execute';
 import { planBackfills, readBackfillLog } from '../backfill';
 import { readSqlDirIfPresent } from './db-sync';
 import { currentGitRef } from '../state-apply';
@@ -277,25 +278,35 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // The fast-forward rule, warn-only at mint time (db:apply enforces it):
     // a stale checkout mints a legal-looking plan whose edge REVERTS merged
     // work — say so on the review surface, where a human still reads it.
+    //
+    // Ledger-first, SYMMETRIC with db:apply — it must warn about exactly what apply will do.
+    // The old whole-history recompile warned "rebase first, will refuse" for
+    // 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 verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
-      // A switch, not an `if (diverged || drift)`. That form silently ignored every verdict
-      // it did not name, so `indeterminate` would have minted a plan with no warning at all
-      // and then been refused at apply time with no hint of why. Exhaustive here means a new
-      // verdict cannot be forgotten.
+      const ledger = await readDescentLedger(session);
+      const verdict = await proveDescent(modelsPath, { snapshot, contract }, ledger, {});
+      // 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 'ok':
+        case 'proven':
         case 'fresh-target':
         case 'no-git':
           break;
-        case 'diverged':
+        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 'indeterminate':
+        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 failed, so the rule is unproven either way.
+          // 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;

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

@@ -647,6 +647,8 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
           info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply credential-free over the direct lane: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct. (--database-url <url> is the local venue — against a deployed stage it puts a privileged connection string on argv.)');
         } else if (/timed out|timeout|task timed out/i.test(String(result.error))) {
           info('A large derived rebuild (dozens of objects) can exceed the ops-Lambda 900-second clock. Re-run credential-free with an unbounded clock: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct.');
+        } else if (/must be owner of/i.test(String(result.error))) {
+          info('This is a brownfield object owned by the master (the old tool created it), which the least-privilege operator cannot replace. Run `everystack db:provision --stage ' + (flags.stage ?? '<stage>') + '` first: it ADOPTS pre-existing objects to their declared owners (--confirm for SECURITY DEFINER), so the operator can then manage them. No hand-written ALTER … OWNER.');
         }
         process.exit(1);
       }

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

@@ -40,12 +40,11 @@ import { rewriteStatementLine, opensCopyData, closesCopyData } from '../schema-r
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease';
 import { resolveConfig, opsFunction, type CliConfig } from '../config';
-import { invokeAction, presignGet, createRdsSnapshot, describeRdsSnapshots } from '../aws';
-import { keyForArtifactId, metaKey, utcStamp } from '../backup';
-import { rdsSnapshotIdentifier } from '../rds-snapshot';
-import { pollTaskUntilStopped } from '../task-poll';
-import { decideSnapshotMode, confirmPhysicalSnapshot, interpretBackupPoll, type SnapshotModeRequest } from '../swap-snapshot';
-import { runStageBackup, stageBackupDeps } from '../stage-backup';
+import { invokeAction, presignGet } from '../aws';
+import { keyForArtifactId, metaKey } from '../backup';
+import { decideSnapshotMode, type SnapshotModeRequest } from '../swap-snapshot';
+import { confirmRollbackPoint } from '../rollback-point';
+import { stageConfirmDeps } from '../stage-rollback-deps';
 import { pgEnvFromUrl, pgKeepaliveConninfo } from './db';
 import { step, success, fail, warn, info } from '../output';
 
@@ -448,58 +447,32 @@ async function takePreSwapSnapshot(
   plan: Exclude<ReturnType<typeof decideSnapshotMode>, { mode: 'refuse' }>,
   ctx: { stage?: string; region?: string; opsFn?: string },
 ): Promise<void> {
-  if (plan.mode === 'attested') {
-    info(`pre-swap rollback point: ${plan.ref} (attested via --snapshot-ref — no new snapshot taken).`);
-    return;
-  }
-
-  if (plan.mode === 'none') {
-    warn('NO pre-swap snapshot (--snapshot none). If this swap lands bad data there is no rollback point — the retiring schema is dropped once verify passes.');
-    return;
-  }
-
-  if (plan.mode === 'physical') {
-    step(`Snapshotting the instance before the swap (RDS physical snapshot of ${plan.instanceId})...`);
-    const snapshotId = rdsSnapshotIdentifier(`${ctx.stage ?? 'swap'}-swap`, utcStamp(new Date()));
-    const region = ctx.region!;
-    const { id } = await confirmPhysicalSnapshot({
-      create: (sid) => createRdsSnapshot(region, plan.instanceId, sid),
-      describe: () => describeRdsSnapshots(region, plan.instanceId),
+  // The confirm ceremony is now shared with db:apply (rollback-point.ts) — one definition of
+  // "no destructive statement before a durable rollback point", two verbs. Swap keeps only its
+  // OWN wording: the restore-from advice, and the "swap was NOT applied, live is untouched"
+  // framing on a refusal.
+  const result = await confirmRollbackPoint(plan, {
+    ...stageConfirmDeps({
+      region: ctx.region!,
+      instanceId: plan.mode === 'physical' ? plan.instanceId : undefined,
+      opsFn: ctx.opsFn!,
+      stage: ctx.stage,
+      verb: 'swap',
       log: (m) => info(m),
-      sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-      now: () => Date.now(),
-    }, { instanceId: plan.instanceId, snapshotId });
-    info(`rollback point CONFIRMED: RDS snapshot ${id} is available — restore the instance from it if this swap goes wrong.`);
-    return;
-  }
-
-  // Logical: dispatch the Task and WAIT. The dispatch returning is not the backup existing — that
-  // conflation is what let a pg_dump run concurrently with the restore it was supposed to precede.
-  step('Snapshotting the stage before the swap (db:backup — waiting for the dump to finish)...');
-  // The shared sandwich. A rollback point taken across a concurrent migration holds a schema that
-  // matches neither endpoint — restoring from it would not return the stage to where it was, which
-  // is the one thing a pre-swap snapshot has to guarantee. An unproven artifact fails the swap.
-  const backup = await runStageBackup({
-    ...stageBackupDeps({ region: ctx.region! }, ctx.opsFn!, ctx.stage, {
-      onStep: step,
-      onDispatch: (d: { id: string; runId: string }) => info(`backup ${d.id} dispatched (run ${d.runId}) — waiting for the task to stop before the restore starts.`),
+      step,
     }),
-    // Swap keeps its OWN reading of a finished poll: it is the only caller that can tell the
-    // operator to re-run with `--snapshot-ref <id>` once the dump lands, and each outcome needs
-    // different advice. The shared helper takes injected deps for exactly this.
-    awaitTask: async (ids) => {
-      const poll = await pollTaskUntilStopped(ctx.region!, ctx.opsFn!, { runId: ids.runId, taskArn: ids.taskArn });
-      const verdict = interpretBackupPoll(poll, { runId: ids.runId, id: ids.id });
-      if (!verdict.ok) return verdict;
-      // Carry the stamp through, or this caller silently opts out of the image-skew check.
-      return { ok: true, stampedFingerprint: (poll as any).status?.result?.fingerprint as string | undefined };
-    },
+    log: (m) => info(m),
+    warn: (m) => warn(m),
   });
-  if (!backup.ok) {
-    throw new Error(`the pre-swap backup is not a usable rollback point, so the swap was NOT applied and live is untouched: ${backup.reason}`);
+
+  if (!result.ok) {
+    throw new Error(`the pre-swap rollback point could not be confirmed, so the swap was NOT applied and live is untouched: ${result.reason}`);
   }
-  if (backup.warning) warn(backup.warning);
-  info(`rollback point CONFIRMED: backup ${backup.id} complete — restore with db:restore --from ${backup.id} --confirm.`);
+  // Swap-specific restore advice on top of the shared confirmation.
+  const p = result.point;
+  if (p.mode === 'physical') info(`restore the instance from RDS snapshot ${p.ref} if this swap goes wrong.`);
+  else if (p.mode === 'logical') info(`restore with db:restore --from ${p.ref} --confirm if this swap goes wrong.`);
+  else if (p.mode === 'none') warn('the retiring schema is dropped once verify passes — there is no rollback point.');
 }
 
 export async function dbSwapCommand(flags: Record<string, string>): Promise<void> {

package/src/cli/commands/db.ts

@@ -304,14 +304,35 @@ export function provisionPreservedIsRecoverable(args: {
  *  same seam as pipeline-loader). */
 export interface ServerProvision {
   runProvision(
-    payload: { authPassword?: string; adminPassword?: string; searchPath?: string[]; rotationPairs?: boolean },
+    payload: {
+      authPassword?: string; adminPassword?: string; searchPath?: string[]; rotationPairs?: boolean;
+      declaredOwners?: Array<{ owner: string; schema: string }>;
+      declaredObjects?: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }>;
+      confirm?: boolean;
+    },
     deps: {
       execute: (sql: string) => Promise<unknown>;
       connection?: { host: string; port?: number | string; database: string } | null;
       connectProbe?: (url: string) => Promise<void>;
       roleHasLogin?: (role: string) => Promise<boolean>;
+      query?: (sql: string) => Promise<any[]>;
+      master?: { execute: (sql: string) => Promise<unknown>; query: (sql: string) => Promise<any[]> } | null;
     },
   ): Promise<any>;
+  /** ENACT + ADOPT, run SEPARATELY and AFTER the secret is written (the lockout-safe ordering). */
+  convergeOwnership(
+    payload: {
+      declaredOwners?: Array<{ owner: string; schema: string }>;
+      declaredObjects?: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }>;
+      confirm?: boolean;
+      adminRole?: string;
+    },
+    deps: {
+      execute: (sql: string) => Promise<unknown>;
+      query?: (sql: string) => Promise<any[]>;
+      master?: { execute: (sql: string) => Promise<unknown>; query: (sql: string) => Promise<any[]> } | null;
+    },
+  ): Promise<{ ownerEnactment?: { enacted: number; refusals: string[] }; ownerAdoption?: { reassigned: number; manifest: Array<{ identity: string; kind: string; secdef: boolean; from: string; to: string }>; findings: Array<{ severity: string; identity: string; detail: string }>; refusals: string[] } }>;
 }
 
 /**
@@ -450,6 +471,39 @@ export function declaredSearchPath(schemas: string[]): string[] {
   return nonPublic.length ? [...nonPublic, 'public'] : [];
 }
 
+/** Kinds ADOPT can reassign — triggers have no owner, 'sql' escape-hatch objects are opaque. */
+const ADOPTABLE_KINDS = new Set(['function', 'view', 'materialized view']);
+
+/**
+ * Read the declared ownership out of the compiled derived source: the unique (owner, schema) pairs
+ * to ENACT, and the function/view/matview objects to ADOPT. `secdef` is read from the object's own
+ * CREATE (the descriptor compiler emits SECURITY DEFINER into it), so the confirm gate sees which
+ * reassignments change runs-as. Objects without a declared owner are left alone (reconcile creates
+ * them owned by the operator, no convergence needed).
+ */
+export function extractDeclaredOwnership(objects: Array<{ kind: string; schema: string; name: string; identity: string; sql: string; owner?: string }>): {
+  declaredOwners: Array<{ owner: string; schema: string }>;
+  declaredObjects: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }>;
+} {
+  const seen = new Set<string>();
+  const declaredOwners: Array<{ owner: string; schema: string }> = [];
+  const declaredObjects: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }> = [];
+  for (const o of objects) {
+    if (!o.owner) continue;
+    const key = `${o.owner}\t${o.schema}`;
+    if (!seen.has(key)) { seen.add(key); declaredOwners.push({ owner: o.owner, schema: o.schema }); }
+    if (ADOPTABLE_KINDS.has(o.kind)) {
+      declaredObjects.push({
+        identity: o.identity, schema: o.schema, name: o.name,
+        kind: o.kind as 'function' | 'view' | 'materialized view',
+        secdef: /SECURITY\s+DEFINER/i.test(o.sql),
+        currentOwner: '', declaredOwner: o.owner,
+      });
+    }
+  }
+  return { declaredOwners, declaredObjects };
+}
+
 /**
  * Every schema the API connection must reach — the union of the TABLE schemas (the models
  * barrel) and the DERIVED-object schemas (views/matviews declared via
@@ -838,6 +892,10 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   // authenticator flip doesn't go dark on bare-ref matview reads. Best-effort: a modelless or
   // all-public app sets no path (unchanged behavior).
   let declaredSchemas: string[] = [];
+  // Declared ownership (brownfield convergence) — the (owner, schema) pairs to ENACT and the
+  // function/view/matview objects to ADOPT, read from the same barrel as the schema set.
+  let declaredOwners: Array<{ owner: string; schema: string }> = [];
+  let declaredObjects: Array<{ identity: string; schema: string; name: string; kind: 'function' | 'view' | 'materialized view'; secdef: boolean; currentOwner: string; declaredOwner: string }> = [];
   try {
     const { resolveModelsPath } = await import('../models-path');
     const { loadModels } = await import('./db-generate');
@@ -846,7 +904,10 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     try {
       const { loadDeclaredDerived } = await import('../declared-derived');
       const declared = await loadDeclaredDerived(flags.models);
-      if (declared) derivedObjects = declared.objects;
+      if (declared) {
+        derivedObjects = declared.objects;
+        ({ declaredOwners, declaredObjects } = extractDeclaredOwnership(declared.objects));
+      }
     } catch {
       // No derived layer resolvable — the table schemas still resolve correctly.
     }
@@ -856,6 +917,8 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   }
   const searchPath = declaredSearchPath(declaredSchemas);
   if (searchPath.length) info(`  Declared search_path (set as the role default via ALTER ROLE): ${searchPath.join(', ')}`);
+  const confirm = !!flags.confirm;
+  const ownershipPayload = { declaredOwners, declaredObjects, confirm };
 
   // Generate BOTH login passwords and keep them in memory only — they are written straight
   // into the secret store and are NEVER printed, logged, or returned to a human.
@@ -870,6 +933,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     const { createUrlRunner } = await import('../db-source');
     const { runner, end } = await createUrlRunner(url);
     try {
+      // Credentials ONLY — ownership convergence runs separately, AFTER the secret is written.
       return await runProvision({ authPassword, adminPassword, searchPath, rotationPairs: !!flags['rotation-pairs'] }, {
         execute: async (statement) => runner(statement),
         connection: parseUrlConnection(url),
@@ -950,6 +1014,61 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     success(`Operator login ready: ${result.adminRole} (LOGIN, INHERIT owner) — ${adminMsg}`);
   }
 
+  // Ownership convergence runs AFTER the secret write (below) — never before. Declared here so the
+  // final exit status can see it.
+  let ownershipIncomplete = false;
+
+  // ENACT + ADOPT, factored out because it must run on BOTH exit paths: the normal one (after the
+  // secret write) AND the additive-only NO-OP path (credentials unchanged, so no secret is written —
+  // but the owners in the model may have changed and still need converging). Running it only on the
+  // normal path made the whole feature a no-op on a re-provision, the common brownfield case: the
+  // stage is already provisioned, the operator adds `owner:` declarations (or re-runs the
+  // review-then-`--confirm` flow), and nothing converged. Credentials are already saved on both
+  // paths by the time this runs, so it can strand nothing.
+  const runConvergence = async (): Promise<void> => {
+    if (!declaredOwners.length && !declaredObjects.length) return;
+    const ownerPayload = { ...ownershipPayload, adminRole: result.adminRole };
+    let owned: any = {};
+    try {
+      if (directUrl) {
+        // The direct venue is ONE privileged connection = operator read AND master; ADOPT's live
+        // master_can_act probe gates it (an under-privileged direct connection refuses precisely).
+        const { convergeOwnership } = await loadServerProvision();
+        const { createUrlRunner } = await import('../db-source');
+        const { runner, end } = await createUrlRunner(directUrl);
+        try {
+          owned = await convergeOwnership(ownerPayload, {
+            execute: async (s) => runner(s),
+            query: async (s) => (await runner(s)) as any[],
+            master: { execute: async (s) => runner(s), query: async (s) => (await runner(s)) as any[] },
+          });
+        } finally {
+          await end?.();
+        }
+      } else {
+        owned = await invokeAction(config.region, opsFunction(config), 'db:converge-ownership', ownerPayload);
+      }
+    } catch (err: any) {
+      warn(`Ownership convergence failed (credentials are already saved — nothing stranded): ${err.message}`);
+      ownershipIncomplete = true;
+    }
+    const enact = owned.ownerEnactment;
+    if (enact) {
+      if (enact.enacted) success(`Owner enactment: ${enact.enacted} grant(s) applied.`);
+      for (const r of enact.refusals) { warn(`Owner enactment: ${r}`); ownershipIncomplete = true; }
+    }
+    const adopt = owned.ownerAdoption;
+    if (adopt) {
+      if (adopt.manifest?.length) {
+        info('Ownership adoption — objects reassigned:');
+        for (const m of adopt.manifest) info(`  ${m.identity} [${m.kind}${m.secdef ? ', SECURITY DEFINER' : ''}]  ${m.from} → ${m.to}`);
+      }
+      for (const f of adopt.findings ?? []) warn(`  audit (${f.severity}): ${f.identity} — ${f.detail}`);
+      if (adopt.reassigned) success(`Ownership adoption: ${adopt.reassigned} object(s) reassigned (one transaction).`);
+      for (const r of adopt.refusals ?? []) { warn(`Ownership adoption: ${r}`); ownershipIncomplete = true; }
+    }
+  };
+
   // Additive-only: if the login roles already existed as live logins, provision changed no
   // credential — so there is nothing to write and no host to resolve. Never touch the secret
   // store on a no-op re-provision (the footgun that reset a live password then locked the stage out).
@@ -966,6 +1085,13 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     });
     if (recoverable.ok) {
       success(`Roles already provisioned — passwords and secrets left unchanged. Verify the live credential with \`everystack db:doctor --stage ${flags.stage}\`; run \`everystack db:provision --rotate\` to change credentials.`);
+      // Credentials are a no-op, but declared ownership may still need converging — this is the
+      // re-provision path (add owners, or the review-then---confirm retry). Run it, then exit.
+      await runConvergence();
+      if (ownershipIncomplete) {
+        warn('Ownership was not fully converged — see the refusals above. db:reconcile will refuse until they are resolved.');
+        process.exit(1);
+      }
       return;
     }
     fail(recoverable.reason);
@@ -1028,6 +1154,12 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   success(`Secrets written for stage "${flags.stage}". No credential was displayed.`);
   for (const note of plan.notes) info(`  ${note}`);
   for (const warning of plan.warnings) info(`  ⚠ ${warning}`);
+
+  // OWNERSHIP CONVERGENCE — strictly AFTER the secret write. The credential is now safely in the
+  // store, so a stall or a hard kill in ENACT/ADOPT can strand nothing: the worst case is an
+  // un-converged owner, exactly the state db:reconcile refuses on (and we exit non-zero for it).
+  await runConvergence();
+
   console.log('');
   info('Finish the wiring in sst.config.ts (one-time):');
   info('  API — PRECONDITION: your handler must escalate per request (pgSettings + SET ROLE /');
@@ -1044,6 +1176,14 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     info(`        operator tasks then run as ${result.adminRole}, not the Postgres master.`);
   }
   info(`Verify:  everystack db:doctor --stage ${flags.stage}`);
+
+  // Credentials are done; ownership was left un-converged. Exit non-zero so CI and the operator act
+  // on the refusals above (run the named SQL as master, or re-run with --confirm). db:reconcile
+  // would refuse on exactly this state, so this is a real, actionable failure — not a warning to skip.
+  if (ownershipIncomplete) {
+    warn('Ownership was not fully converged — see the refusals above. db:reconcile will refuse until they are resolved.');
+    process.exit(1);
+  }
 }
 
 /** Render a doctor report — identical output whichever venue produced it. */

package/src/cli/derived-apply.ts

@@ -59,6 +59,15 @@ export const ENSURE_RECONCILER_SQL: string[] = [
   duration_ms integer,
   outcome text NOT NULL
 )`,
+  // The descent witness columns (apply-legibility Phase 1). Idempotent — legacy databases
+  // upgrade in place; their old rows read fp_version = NULL (descent skips them) and
+  // dirty = false (harmless, since a NULL fp_version already skips them).
+  //  - fp_version: the FINGERPRINT_VERSION a row's to_fingerprint was computed under, so the
+  //    fast-forward proof can recompute the live side under the ROW'S canon across a bump.
+  //  - dirty: the apply ran from a worktree whose models differed from HEAD, so its git_ref
+  //    does not declare what was applied — descent must ignore the row (like git_ref = NULL).
+  `ALTER TABLE everystack.schema_log ADD COLUMN IF NOT EXISTS fp_version integer`,
+  `ALTER TABLE everystack.schema_log ADD COLUMN IF NOT EXISTS dirty boolean NOT NULL DEFAULT false`,
 ];
 
 export interface RenderedReconcile {
@@ -399,7 +408,10 @@ export function ownerPreflightRefusal(rows: OwnerPreflightRow[]): string | null
   if (!missing.size && !unassumable.size && !noCreate.length) return null;
 
   const lines: string[] = [
-    `declared function owner(s) cannot be enacted by '${builderName}' — refused before any DDL, so nothing is half-applied:`,
+    `declared function owner(s) cannot be enacted by '${builderName}' — refused before any DDL, so nothing is half-applied.`,
+    `The one-command fix is \`everystack db:provision\`: it ENACTS these grants (and ADOPTS any`,
+    `pre-existing objects owned by the master) from the declared model, so you never hand-write them.`,
+    `The exact statements, if you must run them by hand:`,
   ];
   for (const owner of [...missing].sort()) {
     lines.push(
@@ -555,12 +567,18 @@ export interface SchemaLogEntry {
   durationMs?: number;
   fromFingerprint?: string | null;
   toFingerprint?: string | null;
+  /** The FINGERPRINT_VERSION the fingerprints were computed under — the descent witness's canon. */
+  fpVersion?: number | null;
+  /** The apply ran from a dirty worktree (models differed from HEAD) — descent ignores such a row. */
+  dirty?: boolean;
 }
 
 export function renderSchemaLogInsert(entry: SchemaLogEntry): string {
   const duration = entry.durationMs === undefined ? 'NULL' : String(Math.round(entry.durationMs));
-  return `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, from_fingerprint, to_fingerprint, sql, duration_ms, outcome)
-VALUES (${escapeLiteral(entry.kind)}, ${nullable(entry.actor)}, ${nullable(entry.gitRef)}, ${nullable(entry.planRef)}, ${nullable(entry.fromFingerprint)}, ${nullable(entry.toFingerprint)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)})
+  const fpVersion = entry.fpVersion == null ? 'NULL' : String(Math.floor(entry.fpVersion));
+  const dirty = entry.dirty ? 'true' : 'false';
+  return `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, from_fingerprint, to_fingerprint, sql, duration_ms, outcome, fp_version, dirty)
+VALUES (${escapeLiteral(entry.kind)}, ${nullable(entry.actor)}, ${nullable(entry.gitRef)}, ${nullable(entry.planRef)}, ${nullable(entry.fromFingerprint)}, ${nullable(entry.toFingerprint)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)}, ${fpVersion}, ${dirty})
 RETURNING id`;
 }
 

package/src/cli/edge-plan.ts

@@ -37,6 +37,20 @@ import { compileTableRenames, compileTableMoves } from './schema-compile';
 
 export const PLAN_VERSION = 2;
 
+/**
+ * The db:apply WIRE CONTRACT between the CLI and the ops Lambda — distinct from PLAN_VERSION,
+ * which versions the plan ARTIFACT. This versions the invoke PAYLOAD (its keys) and the ops
+ * Lambda's enforcement of them: the descent/authority/snapshot verdicts the CLI computes and the
+ * gates the server runs from them. PLAN_VERSION can hold while this moves — a payload key added or
+ * a hook's meaning changed leaves the plan file identical but breaks a mismatched peer silently.
+ *
+ * BUMP RULE: increment on ANY change to the db:apply payload keys, the set of gates the server
+ * runs, or a gate's semantics. Both packages import THIS binding (the server from the cli it
+ * bundles), so a version skew is a hard, exact-equality refusal in both directions — never a
+ * silently dropped gate.
+ */
+export const APPLY_CONTRACT_VERSION = 1;
+
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
   /** Statements that positively ADD. Counted from a matcher, never `total - destructive` —