@everystack/cli 0.4.90 → 0.4.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.90",
+  "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`)
@@ -476,6 +554,7 @@ export function buildReconcileReport(plan: ReconcilePlan): string[] {
   for (const a of plan.actions) {
     const cost = a.bytes !== undefined ? `; ${formatBytes(a.bytes)}${a.rows ? `, ~${a.rows} rows` : ''}` : '';
     lines.push(`${VERB_GLYPH[a.action] ?? '?'} ${a.action} ${a.identity} (${a.reason}${cost})`);
+    for (const r of a.revokes ?? []) lines.push(`    - ${r} (no longer declared)`);
   }
   // Pending identity migrations. Bookkeeping only — no DDL, no object changed — but they ARE a
   // write, and they were invisible here while also being excluded from `checkFails`. Silence in

package/src/cli/derived-apply.ts

@@ -140,9 +140,11 @@ export type OwnerApplyMode = 'set-role' | 'alter-owner';
  * carry pg_dump's WITH NO DATA ordering.)
  *
  * A declared owner is enacted one of two ways; see {@link OwnerApplyMode} for which and why.
+ * `revokes` (a replace's REVOKEs of dropped grantees) trail the attachments, inside the owner
+ * block for the same reason the attachments are.
  */
-function objectSql(obj: SourceObject, ownerMode: OwnerApplyMode = 'set-role'): string[] {
-  const statements = [obj.sql, ...obj.attachments.map((a) => a.sql)];
+function objectSql(obj: SourceObject, ownerMode: OwnerApplyMode = 'set-role', revokes: readonly string[] = []): string[] {
+  const statements = [obj.sql, ...obj.attachments.map((a) => a.sql), ...revokes];
   if (obj.kind === 'materialized view' && WITH_NO_DATA_RE.test(normalizeSql(obj.sql))) {
     statements.push(`REFRESH MATERIALIZED VIEW ${quoteQualified(obj.identity)}`);
   }
@@ -271,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[];
@@ -280,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.
@@ -294,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));
@@ -308,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
@@ -343,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;
@@ -401,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 });
   }
@@ -408,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:`,
@@ -422,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;`,
     );
   }
@@ -457,7 +468,7 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[],
       case 'replace': {
         const obj = srcById.get(action.identity);
         if (!obj) throw new Error(`replace action for ${action.identity} has no source object`);
-        statements.push(...objectSql(obj, ownerMode).map(ensureOrReplace));
+        statements.push(...objectSql(obj, ownerMode, action.revokes).map(ensureOrReplace));
         record.push(action.identity);
         break;
       }
@@ -496,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-grants.ts

@@ -62,6 +62,12 @@ export function isPlainGrantAttachment(a: Attachment): boolean {
   return g !== null && !g[2]; // g[2] is the (columns) group — present => column-scoped => not plain
 }
 
+/** Whether the attachments run a `REVOKE ALL … FROM PUBLIC` — PUBLIC holds nothing after them
+ *  beyond what a later attachment grants it back. */
+export function revokesPublic(attachments: readonly Attachment[]): boolean {
+  return attachments.some((a) => a.kind === 'grant' && REVOKE_PUBLIC_RE.test(a.sql));
+}
+
 /** 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>> = {};
@@ -86,7 +92,12 @@ export function parseGrantAttachments(attachments: readonly Attachment[]): Parse
     target ??= onTarget.trim();
     const privileges = privilegeList.split(',').map((p) => p.trim().toUpperCase()).filter(Boolean);
     for (const role of roleList.split(',').map((r) => r.trim()).filter(Boolean)) {
-      for (const privilege of privileges) (grants[role] ??= new Set()).add(privilege);
+      // PUBLIC is a keyword, not a role: `TO public` and `TO PUBLIC` are one grantee, and the live
+      // read spells it `PUBLIC` (the table path's granteeKey, same rule). Keyed as written, a
+      // lowercase declaration read as a REVOKE from PUBLIC plus a GRANT to `public` — a replace,
+      // which keeps only the REVOKE, removed every caller's access.
+      const grantee = role.toLowerCase() === 'public' ? 'PUBLIC' : role;
+      for (const privilege of privileges) (grants[grantee] ??= new Set()).add(privilege);
     }
   }
 

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 } 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';
@@ -43,6 +45,10 @@ export interface ReconcileAction {
   /** Drops for the structural kinds — a trigger's `DROP TRIGGER … ON table`, a 'sql'
    *  object's recorded/declared drop. Legacy kinds keep the keyword rendering. */
   dropSql?: string;
+  /** A replace's REVOKEs of grantees the source no longer declares. CREATE OR REPLACE keeps the
+   *  live ACL and the attachments only add, so without these a dropped role keeps its privilege.
+   *  They run with the replace, inside its owner block — REVOKE on a function needs its owner. */
+  revokes?: string[];
 }
 
 export interface DriftFinding {
@@ -54,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). */
@@ -144,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,
@@ -474,34 +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 owners = {
-          ...(src.owner !== undefined ? { declared: src.owner } : {}),
-          ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}),
-        };
-        const { statements, suppressed } = diffObjectGrants(target, parsed.grants, liveObj.grants, owners);
-        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
@@ -631,6 +663,32 @@ export function planReconcile(
     return { action, identity: id, kind, reason, ...cost, ...structural };
   };
 
+  /**
+   * The REVOKEs a function replace needs to converge its ACL in the same apply.
+   *
+   * CREATE OR REPLACE keeps the live ACL, and the compiled attachments only ADD: a REVOKE ALL
+   * FROM PUBLIC (unless PUBLIC is declared), then one GRANT per declared role. So a role dropped
+   * from the abilities in the same change as a body edit kept its EXECUTE until a second apply
+   * found it as grant drift. The ACL after the replace is the live one minus PUBLIC (when the
+   * attachments revoke it) plus the declared grants, so only the REVOKEs of the diff are left
+   * to do. They ride the replace itself rather than the regrant pass, because the replace runs
+   * inside its owner's SET ROLE block and a REVOKE on a function needs its owner.
+   *
+   * Read after the dependency cascade: a function it promoted to drop+create is recreated with a
+   * fresh ACL from its attachments alone, and is no longer in fnReplace.
+   */
+  const replaceRevokes = (id: string): string[] => {
+    const src = srcById.get(id);
+    const liveObj = liveById.get(id);
+    if (!src || !liveObj || liveObj.grants === undefined) return [];
+    const afterReplace = { ...liveObj.grants };
+    if (revokesPublic(src.attachments)) delete afterReplace.PUBLIC;
+    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[] = [
     ...orderDrops(dropSet).map((id) => actionFor(id, 'drop', rebuild.get(id) ?? drop.get(id) ?? '')),
     // 'sql'-kind drops (rebuilds + removals) — invisible to the live catalog, so they
@@ -638,7 +696,10 @@ export function planReconcile(
     ...[...sqlDrops.entries()].sort((a, b) => a[0].localeCompare(b[0]))
       .map(([id, d]) => ({ action: 'drop' as const, identity: id, kind: 'sql' as DerivedKind, reason: d.reason, dropSql: d.dropSql })),
     ...[...fnReplace.entries()].sort((a, b) => seqOf(a[0]) - seqOf(b[0]))
-      .map(([id, reason]) => actionFor(id, 'replace', reason)),
+      .map(([id, reason]) => {
+        const revokes = replaceRevokes(id);
+        return { ...actionFor(id, 'replace', reason), ...(revokes.length ? { revokes } : {}) };
+      }),
     ...createSet.sort((a, b) => seqOf(a) - seqOf(b))
       .map((id) => actionFor(id, 'create', rebuild.get(id) ?? create.get(id) ?? '')),
     ...[...refresh.entries()].sort((a, b) => seqOf(a[0]) - seqOf(b[0]))