@everystack/cli 0.4.33 → 0.4.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.33",
+  "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>",

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. */