@everystack/cli 0.4.91 → 0.4.92

package/package.json

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

@@ -32,7 +32,7 @@
 import type { QueryRunner } from '../authz-contract';
 import type { SourceObject } from '../derived-source';
 import { introspectDerived } from '../derived-introspect';
-import { planReconcile, type ReconcilePlan, type ReconcileOptions } from '../derived-plan';
+import { planReconcile, objectGrantDelta, type ReconcilePlan, type ReconcileOptions } from '../derived-plan';
 import {
   renderReconcileSql,
   renderProvenanceUpsert,
@@ -269,8 +269,9 @@ export async function executeReconcile(
     // stable regardless of the create-time wide path above — and that wide path survives the read.
     // The unwrapped path has no transaction to borrow, so it takes a session of its own.
     phase = 'verify';
-    const after = await introspectDerived(atomic ? borrowedSessionRunner(runner) : session);
-    const liveById = new Map(after.objects.map((o) => [o.identity, o]));
+    const reread = () => introspectDerived(atomic ? borrowedSessionRunner(runner) : session);
+    let after = await reread();
+    let liveById = new Map(after.objects.map((o) => [o.identity, o]));
     const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
 
     // THE ORPHAN CHECK — an outcome assertion, not a plan-shape one. Every identity whose
@@ -309,6 +310,82 @@ export async function executeReconcile(
       );
     }
 
+    // THE GRANT CONVERGENCE CHECK — the same outcome assertion, for authz. Every object whose
+    // grants this batch set (creates, replaces, regrants) must now match its declaration, read
+    // from the real post-DDL catalog with the same diff the plan used.
+    //
+    // A statement that ran is not a statement that worked. PostgreSQL answers a REVOKE that
+    // matches nothing with `WARNING: no privileges could be revoked` and a success tag: issued by
+    // a role that is not the grantor (an operator while ownership is still converging, or a grant
+    // someone with grant option made by hand), it removes nothing. Without this check the apply
+    // reported success while the role kept its privilege — the exact failure a declared-authz
+    // tool exists to prevent. Inside the atomic path the throw rolls the whole batch back.
+    //
+    // SETTLE FIRST. A create's ACL is its attachments PLUS whatever the database adds on its own:
+    // `ALTER DEFAULT PRIVILEGES` grants (db:provision --with-reader sets exactly these), and — for a
+    // superuser builder that creates then hands over — a builder grant folded into the pre-transfer
+    // owner's entry and lost by ALTER … OWNER. The plan cannot see either; only the post-DDL catalog
+    // can. So each created/replaced object's remaining delta runs NOW, in the same batch, and only
+    // then is convergence checked. Without this, those shapes fail every apply, forever: the
+    // rollback restores the plan's `create`, which rebuilds the same ACL. (Main converged them one
+    // apply late, via the next plan's regrant.) Regrants are not re-run: they were computed from
+    // this catalog already, and a repeat of a statement that did not land lands no better.
+    const built = plan.actions.filter((a) => a.action === 'create' || a.action === 'replace').map((a) => a.identity);
+    const settle: string[] = [];
+    for (const identity of built) {
+      const src = srcById.get(identity);
+      const liveObj = liveById.get(identity);
+      if (!src || !liveObj) continue;
+      const delta = objectGrantDelta(src, liveObj);
+      if (!delta || delta.columnScoped || delta.statements.length === 0) continue;
+      // As the owner under set-role, for the reason regrants are: GRANT/REVOKE needs ownership.
+      // The preflight already proved every created object's owner assumable.
+      if (src.owner && liveObj.owner === src.owner && (ownerMode ?? 'set-role') === 'set-role') {
+        settle.push(`SET ROLE ${src.owner}`, ...delta.statements, 'RESET ROLE');
+      } else {
+        settle.push(...delta.statements);
+      }
+    }
+    if (settle.length > 0) {
+      // Recorded BEFORE it runs, so a failed attempt's schema_log row carries the statement that failed.
+      rendered = { ...rendered, statements: [...rendered.statements, ...settle] };
+      phase = 'ddl'; // a GRANT/REVOKE that fails is a DDL failure, not a verify one
+      try {
+        if (atomic) await runner(settle.join(';\n'));
+        else for (const statement of settle) await runner(statement);
+      } catch (err) {
+        throw new Error(
+          `${String((err as any)?.message ?? err)}\n\nThis came from the grant settle pass, which runs after the DDL: `
+          + `the grants the built objects still needed once the catalog was read back (${settle.filter((st) => !/ROLE\b/.test(st)).join('; ')}).`,
+        );
+      }
+      phase = 'verify';
+      after = await reread();
+      liveById = new Map(after.objects.map((o) => [o.identity, o]));
+    }
+
+    const grantTouched = new Set([...built, ...plan.regrants.map((r) => r.identity)]);
+    const unconverged: string[] = [];
+    for (const identity of [...grantTouched].sort()) {
+      const src = srcById.get(identity);
+      const liveObj = liveById.get(identity);
+      if (!src || !liveObj) continue;
+      const delta = objectGrantDelta(src, liveObj);
+      if (delta && !delta.columnScoped && delta.statements.length > 0) {
+        unconverged.push(`${identity}: still needs ${delta.statements.join('; ')}`);
+      }
+    }
+    if (unconverged.length > 0) {
+      throw new Error(
+        `grants did not converge — the statements ran, but the catalog afterwards still differs from the `
+        + `declaration:\n  ${unconverged.join('\n  ')}\n\nA REVOKE that matches nothing only WARNs in PostgreSQL. `
+        + `The usual cause of a REVOKE that did not land is a grant whose grantor is not the role that ran it: `
+        + `the object's live owner differs from its declared owner (converge ownership with \`everystack `
+        + `db:provision\`), or a role holding grant option granted it by hand (revoke it as that role). A GRANT `
+        + `that did not land means the role that ran it holds no grant option on the object. No provenance was written.`,
+      );
+    }
+
     const bookkeeping: string[] = [];
     // ORDER MATTERS: migrate, then record, then remove. This ordering is LOAD-BEARING — it is the
     // fix, not the belt. `renderProvenanceMigrate`'s own guard is the belt (see its docstring).
@@ -426,9 +503,10 @@ export function explainReconcileError(err: unknown, phase: 'ddl' | 'verify' | 'b
       `${msg}\n\nThis failed AFTER the DDL, not in it. `
       + (phase === 'verify'
         ? `The failure came from the verify half: the post-apply catalog re-read, or one of the checks `
-          + `over it — a recorded identity with no source object, an object the catalog cannot see `
-          + `afterwards, or a backend pid that moved. No provenance and no 'applied' schema_log row `
-          + `was written; the bookkeeping write is never reached`
+          + `over it — an object whose DROP left it live, grants that did not converge, a recorded `
+          + `identity with no source object, an object the catalog cannot see afterwards, or a backend `
+          + `pid that moved. No provenance and no 'applied' schema_log row was written; the bookkeeping `
+          + `write is never reached`
         : `The failure came from the bookkeeping write that records what was built — the provenance and `
           + `schema_log statements, or the COMMIT that seals them. The post-apply catalog re-read `
           + `succeeded, so every recorded object was introspectable when it ran`)

package/src/cli/derived-apply.ts

@@ -273,7 +273,9 @@ export function renderEnsureObjectSchemas(objects: SourceObject[]): string[] {
 // Declared-owner preflight — the refusal that beats a raw Postgres error.
 // ---------------------------------------------------------------------------
 
-/** One declared owner and every schema the batch will create an object of theirs in. */
+/** One declared owner and every schema the batch will create an object of theirs in. Empty
+ *  `schemas` means the batch only GRANTs/REVOKEs as that owner: it must exist and be assumable,
+ *  but it creates nothing, so it needs CREATE nowhere. */
 export interface OwnerRequirement {
   owner: string;
   schemas: string[];
@@ -282,7 +284,7 @@ export interface OwnerRequirement {
 /**
  * The declared owners this batch will actually enact, and where.
  *
- * Scoped to CREATE and REPLACE, because those are the actions that run under `SET ROLE`. A
+ * Scoped to CREATE, REPLACE and owned REGRANTS, because those are what run under `SET ROLE`. A
  * baseline, a prune or an unchanged object never assumes anyone's identity, so demanding its
  * owner be assumable would refuse work the batch was never going to attempt. On a from-scratch
  * build every object is created, so this set is every declared owner anyway.
@@ -296,6 +298,9 @@ export function ownerRequirements(plan: ReconcilePlan, source: SourceObject[]):
     if (!obj?.owner) continue;
     (byOwner.get(obj.owner) ?? byOwner.set(obj.owner, new Set()).get(obj.owner)!).add(obj.schema);
   }
+  for (const r of plan.regrants) {
+    if (r.owner && !byOwner.has(r.owner)) byOwner.set(r.owner, new Set());
+  }
   return [...byOwner.entries()]
     .map(([owner, schemas]) => ({ owner, schemas: [...schemas].sort() }))
     .sort((a, b) => a.owner.localeCompare(b.owner));
@@ -310,7 +315,9 @@ export function ownerRequirements(plan: ReconcilePlan, source: SourceObject[]):
  * and the privilege only evaluated when it is really there.
  */
 export function ownerPreflightSql(requirements: OwnerRequirement[]): string {
-  const pairs = requirements.flatMap((r) => r.schemas.map((s) => `(${escapeLiteral(r.owner)}, ${escapeLiteral(s)})`));
+  // A grant-only owner still needs its row (does it exist, can we assume it): one with no schema.
+  const pairs = requirements.flatMap((r) => (r.schemas.length ? r.schemas : [null])
+    .map((s) => `(${escapeLiteral(r.owner)}, ${s === null ? 'NULL::text' : escapeLiteral(s)})`));
   return `
 WITH declared(owner_name, schema_name) AS (VALUES ${pairs.join(', ')})
 SELECT
@@ -345,7 +352,8 @@ export interface OwnerPreflightRow {
   builder?: unknown;
   builder_is_superuser?: unknown;
   owner_name: string;
-  schema_name: string;
+  /** Null for a grant-only owner — nothing is created, so there is no schema to check. */
+  schema_name: string | null;
   role_exists?: unknown;
   schema_exists?: unknown;
   owner_is_superuser?: unknown;
@@ -403,6 +411,7 @@ export function ownerPreflightRefusal(rows: OwnerPreflightRow[]): string | null
     // A superuser owner holds CREATE everywhere, including in a schema this build is about to
     // make — there is nothing to refuse.
     if (truthy(row.owner_is_superuser)) continue;
+    if (row.schema_name == null) continue;
     if (!truthy(row.schema_exists)) noCreate.push({ owner, schema: String(row.schema_name), exists: false });
     else if (!truthy(row.owner_can_create)) noCreate.push({ owner, schema: String(row.schema_name), exists: true });
   }
@@ -410,7 +419,7 @@ 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 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:`,
@@ -424,7 +433,7 @@ export function ownerPreflightRefusal(rows: OwnerPreflightRow[]): string | null
   }
   for (const owner of [...unassumable].sort()) {
     lines.push(
-      `  CANNOT SET ROLE  '${builderName}' cannot assume '${owner}'. The CREATE runs as the owner:`,
+      `  CANNOT SET ROLE  '${builderName}' cannot assume '${owner}'. The CREATE and every GRANT/REVOKE on its objects run as the owner:`,
       `      GRANT ${owner} TO ${builderName} WITH INHERIT FALSE, SET TRUE;`,
     );
   }
@@ -498,8 +507,14 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[],
   }
 
   // Grant convergence rides the same batch, after every object exists. Idempotent
-  // REVOKE/GRANT — no provenance to record (ACLs are not in any hash).
-  for (const r of plan.regrants) statements.push(...r.statements);
+  // REVOKE/GRANT — no provenance to record (ACLs are not in any hash). An owned object's grants
+  // run AS its owner, for the reason objectSql keeps attachments inside the block: GRANT/REVOKE
+  // needs ownership, and a non-superuser operator does not have it. A superuser builder
+  // (alter-owner) acts as any owner already.
+  for (const r of plan.regrants) {
+    if (r.owner && ownerMode === 'set-role') statements.push(`SET ROLE ${r.owner}`, ...r.statements, 'RESET ROLE');
+    else statements.push(...r.statements);
+  }
 
   // NOTE — a `remove` entry that is also a migration's TARGET is CORRECT, not a contradiction.
   // A legacy-keyed function the source has removed migrates onto its signature identity and is

package/src/cli/derived-plan.ts

@@ -27,7 +27,9 @@
 import { type ParsedSources, type SourceObject, type DerivedKind } from './derived-source';
 import type { DerivedCatalog, LiveObject } from './derived-introspect';
 import { triggerDropSql } from './derived-apply';
-import { parseGrantAttachments, diffObjectGrants, revokesPublic } from './derived-grants';
+import {
+  parseGrantAttachments, diffObjectGrants, revokesPublic, type GrantOwnerContext, type ObjectGrantDiff,
+} from './derived-grants';
 import { legacyFunctionIdentity, splitFunctionIdentity } from './pg-argtypes';
 
 export type ReconcileVerb = 'create' | 'replace' | 'refresh' | 'drop' | 'baseline' | 'rebaseline' | 'prune' | 'backfill';
@@ -58,6 +60,11 @@ export interface DriftFinding {
 export interface RegrantFinding {
   identity: string;
   statements: string[];
+  /** The role the statements must run as: GRANT/REVOKE on an object needs its owner, and a
+   *  non-superuser operator is not it. Set only when the declared owner IS the live owner — under
+   *  any other role a REVOKE can match nothing and only WARN. That case runs as the operator, and
+   *  the post-apply convergence check (db-reconcile) fails it rather than letting it read as success. */
+  owner?: string;
 }
 
 /** Declared `dependsOn` vs the live catalog's actual edges (B4: declared, then verified). */
@@ -148,6 +155,40 @@ export interface ReconcileOptions {
 
 const isRelation = (kind: DerivedKind): boolean => kind !== 'function';
 
+const ownerContext = (src: SourceObject, liveObj: LiveObject): GrantOwnerContext => ({
+  ...(src.owner !== undefined ? { declared: src.owner } : {}),
+  ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}),
+});
+
+/**
+ * The REVOKE/GRANT delta between an object's declared grants and a live ACL — the ONE diff the
+ * drift pass, a replace's revokes and the post-apply convergence check all use, so the check can
+ * never disagree with the plan about what "converged" means. Null when there is nothing to
+ * compare (no ACL read, or a kind with no grants). Column-scoped grants are not compared
+ * (attacl is not introspected) and say so.
+ *
+ * Ownership context is passed for EVERY kind. An owner's implicit privileges are excluded from
+ * the live read for relations too (`a.grantee <> c.relowner`), so a model that both owns an object
+ * and lists that owner in its grants declares a self-grant the read can never confirm —
+ * diffObjectGrants normalizes the owner grantee away. The earlier belief that a relation's grant
+ * set "does not shift with its owner" holds only while relacl is NULL; the first non-owner grant
+ * materializes the ACL and the owner's own rows drop out, exactly as for a function. (A consumer's
+ * ADOPT'd view, owned by a role its model also grants, looped forever — 2026-09-04.)
+ * KNOWN LIMIT: a privilege an owner has deliberately self-revoked is not restored — that is a
+ * failure to ADD access (availability), never to remove it.
+ */
+export function objectGrantDelta(
+  src: SourceObject,
+  liveObj: LiveObject,
+  liveGrants: Record<string, string[]> | undefined = liveObj.grants,
+): (ObjectGrantDiff & { columnScoped: boolean }) | null {
+  if (liveGrants === undefined || src.kind === 'trigger' || src.kind === 'sql') return null;
+  const parsed = parseGrantAttachments(src.attachments);
+  if (parsed.hasColumnGrants) return { statements: [], suppressed: [], columnScoped: true };
+  const target = parsed.target ?? (src.kind === 'function' ? `FUNCTION ${src.identity}` : src.identity);
+  return { ...diffObjectGrants(target, parsed.grants, liveGrants, ownerContext(src, liveObj)), columnScoped: false };
+}
+
 export function planReconcile(
   source: ParsedSources,
   live: DerivedCatalog,
@@ -465,10 +506,6 @@ export function planReconcile(
 
   const regrants: RegrantFinding[] = [];
   const dependencyDrift: DependencyDriftFinding[] = [];
-  const ownerContext = (src: SourceObject, liveObj: LiveObject): { declared?: string; live?: string } => ({
-    ...(src.owner !== undefined ? { declared: src.owner } : {}),
-    ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}),
-  });
   // 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.
@@ -482,30 +519,21 @@ export function planReconcile(
     // Every object is descriptor-compiled (db/sql retired, B7), and the compiler
     // ALWAYS declares authz — a private relation is declared-empty, not undeclared —
     // so every up-to-date object is grant-checked.
-    if (liveObj?.grants !== undefined) {
-      const parsed = parseGrantAttachments(src.attachments);
-      if (parsed.hasColumnGrants) {
-        extraWarnings.push(
-          `${src.identity}: column-scoped grants are applied at create but not drift-checked (attacl introspection is future work) — hand edits to them are invisible here.`,
-        );
-      } else {
-        const target = parsed.target ?? (src.kind === 'function' ? `FUNCTION ${src.identity}` : src.identity);
-        // Ownership context is passed for EVERY kind. An owner's implicit privileges are excluded
-        // from the live read for relations too (`a.grantee <> c.relowner`), so a model that both
-        // owns an object and lists that owner in its grants declares a self-grant the read can
-        // never confirm — diffObjectGrants normalizes the owner grantee away. The earlier belief
-        // that a relation's grant set "does not shift with its owner" holds only while relacl is
-        // NULL; the first non-owner grant materializes the ACL and the owner's own rows drop out,
-        // exactly as for a function. (A consumer's ADOPT'd view, owned by a role its model also
-        // grants, looped forever — 2026-09-04.)
-        // KNOWN LIMIT: a privilege an owner has deliberately self-revoked is not restored — that
-        // is a failure to ADD access (availability), never to remove it, and unnormalized code did
-        // not converge on it either.
-        const { statements, suppressed } = diffObjectGrants(target, parsed.grants, liveObj.grants, ownerContext(src, liveObj));
-        if (statements.length > 0) regrants.push({ identity: src.identity, statements });
-        // Never silent: a withheld revoke is reported every run until the owner is declared.
-        for (const note of suppressed) extraWarnings.push(note);
+    const delta = liveObj ? objectGrantDelta(src, liveObj) : null;
+    if (delta?.columnScoped) {
+      extraWarnings.push(
+        `${src.identity}: column-scoped grants are applied at create but not drift-checked (attacl introspection is future work) — hand edits to them are invisible here.`,
+      );
+    } else if (delta && liveObj) {
+      if (delta.statements.length > 0) {
+        // Run as the owner only when the declared owner IS the live owner: under any other role a
+        // REVOKE can match nothing and only WARN. The post-apply convergence check catches that
+        // case whichever role runs it.
+        const owner = src.owner !== undefined && liveObj.owner === src.owner ? src.owner : undefined;
+        regrants.push({ identity: src.identity, statements: delta.statements, ...(owner ? { owner } : {}) });
       }
+      // Never silent: a withheld revoke is reported every run until the owner is declared.
+      for (const note of delta.suppressed) extraWarnings.push(note);
     }
 
     // Dependency drift — declared, then verified. Only descriptor-home relations carry a
@@ -653,14 +681,12 @@ export function planReconcile(
     const src = srcById.get(id);
     const liveObj = liveById.get(id);
     if (!src || !liveObj || liveObj.grants === undefined) return [];
-    const parsed = parseGrantAttachments(src.attachments);
-    if (parsed.hasColumnGrants) return [];
-    const target = parsed.target ?? `FUNCTION ${src.identity}`;
     const afterReplace = { ...liveObj.grants };
     if (revokesPublic(src.attachments)) delete afterReplace.PUBLIC;
-    const { statements, suppressed } = diffObjectGrants(target, parsed.grants, afterReplace, ownerContext(src, liveObj));
-    for (const note of suppressed) extraWarnings.push(note);
-    return statements.filter((st) => /^REVOKE\b/i.test(st));
+    const delta = objectGrantDelta(src, liveObj, afterReplace);
+    if (!delta || delta.columnScoped) return [];
+    for (const note of delta.suppressed) extraWarnings.push(note);
+    return delta.statements.filter((st) => /^REVOKE\b/i.test(st));
   };
 
   const actions: ReconcileAction[] = [