@everystack/cli 0.4.32 → 0.4.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.32",
+  "version": "0.4.34",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -100,6 +100,7 @@
     "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/client-ssm": "3.1053.0",
+    "@aws-sdk/lib-storage": "3.1053.0",
     "@aws-sdk/client-sts": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1048.0",
     "glob": "13.0.6",

package/src/cli/aws.ts

@@ -13,7 +13,7 @@ let lambdaClient: InstanceType<typeof import('@aws-sdk/client-lambda').LambdaCli
 let kvsClient: InstanceType<typeof import('@aws-sdk/client-cloudfront-keyvaluestore').CloudFrontKeyValueStoreClient> | null = null;
 let rdsClient: InstanceType<typeof import('@aws-sdk/client-rds').RDSClient> | null = null;
 
-async function getS3(region: string) {
+export async function getS3(region: string) {
   if (!s3Client) {
     const { S3Client } = await importOptionalAws(
       () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'this command',

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

@@ -4,14 +4,152 @@
  * db:backup/db:export run in the ephemeral Task lane (the ops Lambda holds no pg binaries); the CLI
  * dispatches and polls. db:backups/db:restore/download are thin invokeAction wrappers. The image's
  * version handshake is the compatibility gate — verify a deploy with `everystack task:probe`.
+ *
+ * db:backup has a SECOND venue for break-glass: `--database-url <local> --stage <target>` dumps a
+ * LOCAL database and uploads it into the target stage's backups bucket as a db:backup-shaped object
+ * (same key scheme + .meta.json + dump flags as a server backup). The standard credential-free
+ * `db:restore --from <id> --stage <target>` then lands it via the Task lane (pg_restore runs as the
+ * privileged `migrator` role, which can CREATE SCHEMA + own objects). The local dump is the only
+ * held connection; the upload rides the operator's AWS credentials — the same trust boundary as
+ * db:fork's cross-stage presign. This is the sanctioned local→stage full replace on a role-managed
+ * stage (raw pg_restore can't: the operator/api role can't CREATE SCHEMA, and only the master could).
  */
 
+import { spawn } from 'node:child_process';
+import { createGzip } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+import { randomBytes } from 'node:crypto';
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
-import { invokeAction, presignGet } from '../aws.js';
-import { parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard } from '../backup.js';
+import { invokeAction, presignGet, getS3 } from '../aws.js';
+import {
+  parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard,
+  backupKey, backupId, metaKey, utcStamp,
+} from '../backup.js';
+import { pgEnvFromUrl } from './db.js';
 import { pollTaskUntilStopped } from '../task-poll.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+/** Which database db:backup dumps. LOCAL requires a target --stage (its bucket receives the upload
+ *  AND names the backup id). Note this DIVERGES from db:export, where --database-url and --stage are
+ *  mutually-exclusive venues: here the local venue COMBINES them (dump local → upload to the stage). */
+export type BackupVenue =
+  | { kind: 'local'; url: string; stage: string }
+  | { kind: 'stage'; stage: string | undefined };
+
+export function resolveBackupVenue(flags: Record<string, string>): BackupVenue {
+  const url = flags['database-url'];
+  if (url) {
+    if (!flags.stage) {
+      throw new Error(
+        'db:backup --database-url <local> also needs --stage <target> — the local dump uploads into '
+        + "that stage's backups bucket, and the stage names the backup id `db:restore --from` consumes.",
+      );
+    }
+    return { kind: 'local', url, stage: flags.stage };
+  }
+  return { kind: 'stage', stage: flags.stage };
+}
+
+/**
+ * Full-DB streaming pg_dump args — IDENTICAL to the server's db:backup dump (packages/server
+ * backup.ts pgDumpArgs()), minus `-f`: streamed to stdout so it pipes into gzip → S3. Excludes the
+ * everystack ops schema (task_log/schema_log/etc — the TARGET's own audit history, not app data;
+ * restoring it would rewind that history AND makes pg_restore --clean fail on DROP SCHEMA everystack).
+ */
+export function pgDumpFullArgs(): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments', '--exclude-schema=everystack'];
+}
+
+/** The .meta.json sidecar — byte-shape identical to the server's runBackup meta (backup-run.ts:156),
+ *  so db:backups list and the destructive-apply gate read a local upload exactly like a stage backup.
+ *  `bytes` is undefined-safe (JSON.stringify drops it) exactly as the server leaves it on a failed
+ *  HeadObject — never coerced to 0. */
+export function localBackupMeta(opts: {
+  id: string;
+  stage: string;
+  createdAt: Date;
+  bytes?: number;
+  key: string;
+}): Record<string, unknown> {
+  return {
+    id: opts.id,
+    stage: opts.stage,
+    createdAt: opts.createdAt.toISOString(),
+    bytes: opts.bytes,
+    key: opts.key,
+  };
+}
+
+/**
+ * Stream a local database into a stage's backups bucket as a db:backup-shaped object. Mirrors the
+ * server's runBackup streaming AND its load-bearing correctness rule: a completed S3 multipart upload
+ * does NOT mean pg_dump succeeded (pg_dump can exit non-zero mid-stream while the upload "completes"),
+ * so we await the child exit code SEPARATELY and, on any failure, abort the upload and delete the
+ * partial object. A backup tool that ships a truncated dump is worse than none.
+ */
+export async function runLocalBackupUpload(deps: {
+  region: string;
+  bucket: string;
+  url: string;
+  stage: string;
+}): Promise<{ id: string; key: string; bytes?: number }> {
+  const now = new Date();
+  const stamp = utcStamp(now);
+  const shortId = randomBytes(3).toString('hex');
+  const key = backupKey(deps.stage, stamp, shortId);
+  const id = backupId(deps.stage, stamp, shortId);
+  const mkey = metaKey(key);
+
+  const env = { ...process.env, ...pgEnvFromUrl(deps.url) };
+  const s3 = await getS3(deps.region);
+  const { Upload } = await import('@aws-sdk/lib-storage');
+  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+
+  const child = spawn('pg_dump', pgDumpFullArgs(), { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  const childExit = new Promise<void>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+  });
+
+  const gzip = createGzip();
+  const upload = new Upload({
+    client: s3,
+    params: {
+      Bucket: deps.bucket, Key: key, Body: gzip,
+      ContentType: 'application/gzip', ServerSideEncryption: 'AES256',
+    },
+  });
+
+  try {
+    await Promise.all([
+      pipeline(child.stdout!, gzip), // pg_dump → gzip; errors propagate, streams destroyed
+      upload.done(),                 // gzip → S3 multipart
+      childExit,                     // the guard: non-zero pg_dump rejects the whole thing
+    ]);
+  } catch (err) {
+    try { await upload.abort(); } catch { /* may already have completed */ }
+    await s3.send(new DeleteObjectCommand({ Bucket: deps.bucket, Key: key })).catch(() => {});
+    throw err;
+  }
+
+  let bytes: number | undefined;
+  try {
+    const head = await s3.send(new HeadObjectCommand({ Bucket: deps.bucket, Key: key }));
+    bytes = head.ContentLength;
+  } catch { /* size is best-effort */ }
+
+  await s3.send(new PutObjectCommand({
+    Bucket: deps.bucket, Key: mkey,
+    Body: JSON.stringify(localBackupMeta({ id, stage: deps.stage, createdAt: now, bytes, key })),
+    ContentType: 'application/json', ServerSideEncryption: 'AES256',
+  }));
+
+  return { id, key, bytes };
+}
+
 function fmtBytes(n?: number): string {
   if (n == null) return '-';
   if (n < 1024) return `${n} B`;
@@ -27,6 +165,53 @@ function fmtBytes(n?: number): string {
  * the compatibility gate (a too-old image fails the run loudly — no separate layer pre-flight).
  */
 export async function dbBackupCommand(flags: Record<string, string>): Promise<void> {
+  let venue: BackupVenue;
+  try {
+    venue = resolveBackupVenue(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Local venue: dump a reachable database here and upload it into the target stage's backups bucket
+  // as a db:backup-shaped object, so `db:restore --from <id> --stage <target>` lands it credential-free.
+  if (venue.kind === 'local') {
+    step('Resolving deployed config...');
+    let config: CliConfig;
+    try {
+      config = await resolveConfig(venue.stage);
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    if (!config.backupsBucket) {
+      fail('No backupsBucket in the deployed config. Add `backupsBucket: backups.name` to sst.config outputs and redeploy.');
+      process.exit(1);
+    }
+    info(`Region: ${config.region}, Bucket: ${config.backupsBucket}`);
+    // Version gate for the local venue: unlike the stage venue (whose pg binaries are the Task image),
+    // this dumps with the OPERATOR's pg_dump. pg_restore refuses an archive from a NEWER pg_dump major,
+    // so a mismatch surfaces only at restore time ("unsupported version in file header") — loud and
+    // lossless (it fails before --clean drops anything), but discovered exactly when you need the
+    // backup. Surface the local major up front so the operator can match it to the target's PG major.
+    try {
+      const { execFileSync } = await import('node:child_process');
+      const v = execFileSync('pg_dump', ['--version']).toString().trim();
+      info(`Local ${v} — must be ≤ the target stage's PostgreSQL major, or db:restore will reject the dump.`);
+    } catch { /* a missing pg_dump surfaces loudly in the dump step below */ }
+    step(`Running pg_dump (full, --exclude-schema=everystack) against --database-url → S3 (this may take a while for large databases)...`);
+    try {
+      const res = await runLocalBackupUpload({
+        region: config.region, bucket: config.backupsBucket, url: venue.url, stage: venue.stage,
+      });
+      success(`Backup ${res.id} (${fmtBytes(res.bytes)}). Restore with: everystack db:restore --from ${res.id} --stage ${venue.stage} --confirm`);
+    } catch (err: any) {
+      fail(`Backup failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   step('Resolving deployed config...');
   let config: CliConfig;
   try {

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

@@ -206,7 +206,7 @@ export async function executeReconcile(
       // 'sql'-kind objects are invisible to the catalog: provenance records the source
       // hash on both sides plus HOW TO REMOVE it (the escape hatch's whole contract).
       if (src.kind === 'sql') {
-        bookkeeping.push(renderProvenanceUpsert(identity, src.hash, src.hash, 'sql', src.drop));
+        bookkeeping.push(renderProvenanceUpsert(identity, src.hash, src.hash, 'sql', src.drop, src.bodyHash));
         continue;
       }
       const liveObj = liveById.get(identity);
@@ -214,7 +214,7 @@ export async function executeReconcile(
         throw new Error(`reconcile applied but ${identity} is not introspectable afterwards — provenance not recorded, investigate`);
       }
       const dropSql = src.kind === 'trigger' && src.table ? triggerDropSql(src.name, src.table) : undefined;
-      bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash, src.kind, dropSql));
+      bookkeeping.push(renderProvenanceUpsert(identity, src.hash, liveObj.defHash, src.kind, dropSql, src.bodyHash));
     }
     for (const m of rendered.migrate) bookkeeping.push(renderProvenanceMigrate(m.from, m.to));
     for (const identity of rendered.remove) bookkeeping.push(renderProvenanceDelete(identity));
@@ -292,7 +292,7 @@ export function formatBytes(bytes: number): string {
 }
 
 const VERB_GLYPH: Record<string, string> = {
-  create: '+', replace: '~', drop: '-', refresh: '↻', baseline: '◦', rebaseline: '≈', prune: '·',
+  create: '+', replace: '~', drop: '-', refresh: '↻', baseline: '◦', rebaseline: '≈', prune: '·', backfill: '◌',
 };
 
 export function buildReconcileReport(plan: ReconcilePlan): string[] {
@@ -330,9 +330,12 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
 }
 
 /** Anything that makes `--check` fail: pending work or unresolved findings.
- *  Baseline and rebaseline are explicit adoption the operator asked for, not findings. */
+ *  Baseline and rebaseline are explicit adoption the operator asked for, not findings; a
+ *  backfill is record-only bookkeeping (body_hash arming) — neither is a CI failure. An
+ *  UNAPPLIED authz-only grant change still fails here via `regrants` below (the real signal);
+ *  an empty regrant delta means live already matches declared, so green is correct. */
 export function checkFails(plan: ReconcilePlan): boolean {
-  return plan.actions.some((a) => a.action !== 'baseline' && a.action !== 'rebaseline')
+  return plan.actions.some((a) => a.action !== 'baseline' && a.action !== 'rebaseline' && a.action !== 'backfill')
     || plan.drift.length > 0
     || plan.needsBaseline.length > 0
     || plan.blocked.length > 0

package/src/cli/derived-apply.ts

@@ -41,6 +41,10 @@ export const ENSURE_RECONCILER_SQL: string[] = [
   // databases upgrade in place; their old rows (relations/functions) never need these.
   `ALTER TABLE everystack.derived_provenance ADD COLUMN IF NOT EXISTS kind text`,
   `ALTER TABLE everystack.derived_provenance ADD COLUMN IF NOT EXISTS drop_sql text`,
+  // body_hash = the source hash MINUS plain grants (authz-only-change discriminator). Idempotent;
+  // legacy rows have NULL until the reconciler re-records them, and a NULL body_hash falls back to
+  // the rebuild-on-src-change behavior (no regression) — the fix only ARMS once body_hash is recorded.
+  `ALTER TABLE everystack.derived_provenance ADD COLUMN IF NOT EXISTS body_hash text`,
   `CREATE TABLE IF NOT EXISTS everystack.schema_log (
   id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
   applied_at timestamptz NOT NULL DEFAULT now(),
@@ -221,6 +225,12 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
         record.push(action.identity);
         break;
       }
+      // Arm the authz-only fast path on an up-to-date object: no DDL — the upsert just adds the
+      // body_hash column value the record loop always writes now. Idempotent; converges in one run.
+      case 'backfill': {
+        record.push(action.identity);
+        break;
+      }
       case 'prune': {
         remove.push(action.identity);
         break;
@@ -235,10 +245,10 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
   return { statements, record, remove, migrate: [...plan.migrations] };
 }
 
-export function renderProvenanceUpsert(identity: string, srcHash: string, defHash: string, kind?: string, dropSql?: string): string {
-  return `INSERT INTO everystack.derived_provenance (identity, src_hash, def_hash, kind, drop_sql, applied_at)
-VALUES (${escapeLiteral(identity)}, ${escapeLiteral(srcHash)}, ${escapeLiteral(defHash)}, ${nullable(kind)}, ${nullable(dropSql)}, now())
-ON CONFLICT (identity) DO UPDATE SET src_hash = EXCLUDED.src_hash, def_hash = EXCLUDED.def_hash, kind = EXCLUDED.kind, drop_sql = EXCLUDED.drop_sql, applied_at = now()`;
+export function renderProvenanceUpsert(identity: string, srcHash: string, defHash: string, kind?: string, dropSql?: string, bodyHash?: string): string {
+  return `INSERT INTO everystack.derived_provenance (identity, src_hash, def_hash, kind, drop_sql, body_hash, applied_at)
+VALUES (${escapeLiteral(identity)}, ${escapeLiteral(srcHash)}, ${escapeLiteral(defHash)}, ${nullable(kind)}, ${nullable(dropSql)}, ${nullable(bodyHash)}, now())
+ON CONFLICT (identity) DO UPDATE SET src_hash = EXCLUDED.src_hash, def_hash = EXCLUDED.def_hash, kind = EXCLUDED.kind, drop_sql = EXCLUDED.drop_sql, body_hash = EXCLUDED.body_hash, applied_at = now()`;
 }
 
 /** A table rename carried its triggers along — same object, new identity; the provenance

package/src/cli/derived-compile.ts

@@ -22,14 +22,22 @@ import type {
   FunctionDescriptor, SqlDescriptor, TriggerSpec, Ability, SetofReturn, DependsOnRef,
 } from '@everystack/model';
 import { hashSourceContent, parseQualified, DECLARED_SOURCE_FILE, type Attachment, type SourceObject } from './derived-source.js';
+import { isPlainGrantAttachment } from './derived-grants.js';
 import { findInvokerReachabilityGaps } from './derived-lint.js';
 
 /** The provenance marker for descriptor-compiled objects (SourceObject.file). */
 const DECLARED = DECLARED_SOURCE_FILE;
 
-/** `public.x` renders bare (authored style — hash parity with hand-written sources); other schemas qualify. */
+/**
+ * Always schema-qualify — the CREATE/GRANT/COMMENT target must be `schema.name` so the object lands
+ * in its DECLARED schema regardless of the apply-time search_path order. A bare `public` name landed
+ * in search_path[0] instead (derivedSearchPath puts public LAST), so a new public derived object
+ * created while a non-public derived schema existed mislanded into the wrong schema and the record
+ * loop couldn't find it. (The old bare-public rendering chased hash parity with hand-written db/sql
+ * sources; db/sql is retired — B7 — so that rationale is dead. Qualifying is the correctness rule.)
+ */
 function renderName(schema: string, name: string): string {
-  return schema === 'public' ? name : `${schema}.${name}`;
+  return `${schema}.${name}`;
 }
 
 /** The declared name of a dependable ref, for rendering (`SETOF posts`) and identity. */
@@ -243,6 +251,9 @@ function make(kind: SourceObject['kind'], rawName: string, sql: string, attachme
     identity: extra.identity ?? `${schema}.${name}`,
     sql, attachments,
     hash: hashSourceContent(sql, attachments),
+    // bodyHash excludes PLAIN grants (column-scoped grants stay in — attacl isn't drift-checked, so
+    // a column-grant change must still rebuild). Equal across an authz-only plain-grant change.
+    bodyHash: hashSourceContent(sql, attachments.filter((a) => !isPlainGrantAttachment(a))),
     file: DECLARED, seq,
     ...extra,
   });

package/src/cli/derived-grants.ts

@@ -41,6 +41,21 @@ export interface ParsedGrants {
 const GRANT_RE = /^GRANT\s+([A-Z]+)\s*(\([^)]*\))?\s+ON\s+(.+?)\s+TO\s+(.+)$/i;
 const REVOKE_PUBLIC_RE = /^REVOKE\s+ALL\s+ON\s+(.+?)\s+FROM\s+PUBLIC$/i;
 
+/**
+ * A PLAIN (non-column-scoped) grant/revoke attachment — a table/function-level `GRANT … TO …` with
+ * no column list, or a `REVOKE ALL … FROM PUBLIC`. These are the grants `diffObjectGrants` can fully
+ * express, so `bodyHash` excludes them: an authz-only change to them applies as a bare regrant, never
+ * a rebuild. Column-scoped grants (`GRANT SELECT ("a","b") …`) are NOT plain — attacl is not
+ * introspected, so a change to them must still rebuild; they stay in `bodyHash`. Non-grant
+ * attachments (index/comment) are structural and always return false.
+ */
+export function isPlainGrantAttachment(a: Attachment): boolean {
+  if (a.kind !== 'grant') return false;
+  if (REVOKE_PUBLIC_RE.test(a.sql)) return true;
+  const g = a.sql.match(GRANT_RE);
+  return g !== null && !g[2]; // g[2] is the (columns) group — present => column-scoped => not plain
+}
+
 /** The declared grant contract, read back from an object's own grant attachments. */
 export function parseGrantAttachments(attachments: readonly Attachment[]): ParsedGrants {
   const grants: Record<string, Set<string>> = {};

package/src/cli/derived-introspect.ts

@@ -81,6 +81,9 @@ export interface ProvenanceRow {
   kind?: string;
   /** How to remove what was recorded — the C1 closure: removal never orphans. */
   dropSql?: string;
+  /** The source hash MINUS plain grants at record time. Present only once the reconciler has
+   *  re-recorded the row post-fix; absent on legacy rows → the planner falls back to rebuild. */
+  bodyHash?: string;
 }
 
 export interface DerivedCatalog {
@@ -514,6 +517,7 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
       defHash: String(r.def_hash ?? ''),
       ...(r.extra?.kind != null ? { kind: String(r.extra.kind) } : {}),
       ...(r.extra?.drop_sql != null ? { dropSql: String(r.extra.drop_sql) } : {}),
+      ...(r.extra?.body_hash != null ? { bodyHash: String(r.extra.body_hash) } : {}),
     }))
     .sort((a, b) => a.identity.localeCompare(b.identity));
 

package/src/cli/derived-plan.ts

@@ -29,7 +29,7 @@ import type { DerivedCatalog, LiveObject } from './derived-introspect.js';
 import { triggerDropSql } from './derived-apply.js';
 import { parseGrantAttachments, diffObjectGrants } from './derived-grants.js';
 
-export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune';
+export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune' | 'backfill';
 
 export interface ReconcileAction {
   action: ReconcileVerb;
@@ -192,6 +192,9 @@ export function planReconcile(
   const baseline: string[] = [];
   const rebaseline: string[] = [];
   const prune: string[] = [];
+  /** Up-to-date objects (src+live unchanged) whose provenance predates body_hash — record it once
+   *  so a FUTURE authz-only change is a regrant, not a rebuild. Record-only, no DDL; arms the fix. */
+  const backfill: string[] = [];
 
   // -------------------------------------------------------------------------
   // The decision table.
@@ -289,14 +292,34 @@ export function planReconcile(
       continue;
     }
     if (srcChanged) {
+      // Authz-only change: the BODY (and live) is untouched, only plain grants moved — bodyHash
+      // matches provenance. Route it like a rebaseline: no rebuild, re-record the (new) source +
+      // body hash, and the grant-drift pass below (which covers skipped ∪ rebaseline) applies the
+      // bare GRANT/REVOKE delta. Gate is strict — any leg missing falls through to today's rebuild:
+      //   - bodyHash recorded AND equal        → the change is grants-only, not body (armed row only)
+      //   - live grants introspected (≠ undef) → diffObjectGrants can actually run (absent ≠ empty)
+      //   - no column-scoped grants            → attacl isn't drift-applied, so those MUST rebuild
+      const parsed = parseGrantAttachments(src.attachments);
+      const authzOnly =
+        prov.bodyHash != null &&
+        src.bodyHash === prov.bodyHash &&
+        liveObj.grants !== undefined &&
+        !parsed.hasColumnGrants;
       // The live object is verifiably untouched here (liveChanged was handled above), so
       // under rebaseline a source re-render is bookkeeping: re-record the source hash,
       // rebuild nothing, cascade nothing.
-      if (options.rebaseline) rebaseline.push(src.identity);
+      if (options.rebaseline || authzOnly) rebaseline.push(src.identity);
       else if (isRelation(src.kind)) rebuild.set(src.identity, 'source changed');
       else fnReplace.set(src.identity, 'source changed');
       continue;
     }
+    // Up-to-date (src + live both match provenance). If provenance predates body_hash, record it
+    // once — a record-only backfill that ARMS the authz-only fast path for a future grant change.
+    // Converges: after this run the row has body_hash, so it skips cleanly next time.
+    if (prov.bodyHash == null) {
+      backfill.push(src.identity);
+      continue;
+    }
     skipped.push(src.identity);
   }
 
@@ -336,7 +359,7 @@ export function planReconcile(
   // Rebaselined objects join the lens: their live catalog rows are as real as a skip's,
   // and running the checks NOW means a migration converges (grants ride the same apply)
   // instead of surfacing on the next plan.
-  const lensSet = new Set([...skipped, ...rebaseline]);
+  const lensSet = new Set([...skipped, ...rebaseline, ...backfill]);
   for (const src of source.objects) {
     if (!lensSet.has(src.identity)) continue;
     if (src.kind === 'trigger' || src.kind === 'sql') continue; // no grants, no rewrite edges
@@ -485,6 +508,7 @@ export function planReconcile(
       .map(([id, reason]) => actionFor(id, 'refresh', reason)),
     ...baseline.sort().map((id) => actionFor(id, 'baseline', 'recording provenance for an existing match (trusted once, explicitly)')),
     ...rebaseline.sort().map((id) => actionFor(id, 'rebaseline', 'source re-rendered — live verified untouched (defHash match); provenance re-recorded, no rebuild')),
+    ...backfill.sort().map((id) => actionFor(id, 'backfill', 'recording body_hash on an up-to-date object — arms the authz-only fast path, no rebuild')),
     ...prune.sort().map((id) => ({
       action: 'prune' as const, identity: id, kind: 'view' as DerivedKind,
       reason: 'stale provenance — object gone from both source and database',

package/src/cli/derived-source.ts

@@ -48,6 +48,14 @@ export interface SourceObject {
   attachments: Attachment[];
   /** sha256 of the normalized CREATE + attachments — comment/whitespace edits do not change it. */
   hash: string;
+  /**
+   * sha256 of the normalized CREATE + attachments EXCEPT plain (non-column-scoped) grants — the
+   * "would a rebuild be required" hash. Equal across an authz-only change (plain grants moved, body
+   * unchanged), so the reconciler can route that to a bare GRANT delta instead of a matview rebuild.
+   * Column-scoped grants stay IN (attacl not introspected → they must rebuild). `hash` stays the
+   * full/stable formula for provenance compat; this is the additional discriminator.
+   */
+  bodyHash: string;
   /** Source file this object came from (descriptors: the declared-models marker). */
   file: string;
   /** Position in the concatenated source — a valid dependency order by convention. */

package/src/cli/index.ts

@@ -368,7 +368,7 @@ Usage:
   everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are set as the ROLE default (ALTER ROLE … SET search_path) — the secret stays credentials-only, and the URL is libpq-clean
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
-  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id)
+  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id). Add --database-url <local> --stage <target> to dump a LOCAL database and upload it into the target stage's bucket as a restorable backup — the credential-free break-glass local→stage full replace (then: db:restore --from <id> --stage <target>)
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)