@everystack/cli 0.4.45 → 0.4.47

package/src/cli/authz-contract.ts

@@ -22,7 +22,7 @@
  */
 
 import { parsePgArray } from './security-catalog.js';
-import { withCanonicalSearchPath } from './search-path.js';
+import { INTROSPECTION_SESSION, type SessionRunner } from './session.js';
 import { matchPolicies, roleSetEqual } from './authz-identity.js';
 
 // ---------------------------------------------------------------------------
@@ -137,6 +137,83 @@ export function holdsPrivilege(t: TableContract, role: string, privilege: string
     || Boolean(cols.public?.[privilege]?.length);
 }
 
+/** The four row-level commands a policy can govern. `FOR ALL` fans out across them. */
+export const POLICY_COMMANDS = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+
+/** Every command a policy governs — `ALL` fans out, so a live `FOR ALL` is compared per command. */
+export function policyCommands(p: PolicyContract): string[] {
+  return p.command === 'ALL' ? [...POLICY_COMMANDS] : [p.command];
+}
+
+/**
+ * Is this policy DEAD — does it authorize nothing at all?
+ *
+ * PostgreSQL checks the GRANT before the policy, so a policy governing a privilege none of
+ * its roles holds is inert: it cannot admit a single row today, and removing it takes away
+ * access that was never there. A PUBLIC policy applies to every grantee, so it is dead only
+ * when NO grantee holds the privilege.
+ *
+ * ONE definition, four callers — the classifier (what class is this statement?), the
+ * reconciler (should I drop it?), the canonical form (is it part of the state?), and db:pull
+ * (what do I tell the adopter?). They were drifting apart, which is this milestone's recurring
+ * bug: two surfaces answering the same question differently. Note the deadness is a property
+ * of the CONTRACT, not the policy — it is recomputed against live grants every time, so a
+ * policy RESURRECTS the moment a grant makes it effective.
+ */
+export function isPolicyDead(t: TableContract, p: PolicyContract): boolean {
+  const roles = p.roles.includes('public') || p.roles.includes('PUBLIC')
+    ? Object.keys(t.grants)
+    : p.roles;
+  if (!roles.length) return true;
+  // `holdsPrivilege`, not the table-level one: a column-scoped grant is real access, so a
+  // policy governing it is doing live work. See the two-predicate note above.
+  return !policyCommands(p).some((cmd) => roles.some((r) => holdsPrivilege(t, r, cmd)));
+}
+
+/** Does this policy name PostgreSQL's PUBLIC pseudo-role — the open set of every role? */
+export function isPublicPolicy(p: PolicyContract): boolean {
+  return p.roles.some((r) => r.toUpperCase() === 'PUBLIC');
+}
+
+/**
+ * A policy's RULE, with the roles and the NAME deliberately absent — what it authorizes, not
+ * whom it names or what it is called. The same normalization the canonical form hashes by, so
+ * "these two policies say the same thing" has one answer.
+ */
+export function policyRuleKey(p: PolicyContract): string {
+  return JSON.stringify([p.command, p.permissive, p.using ?? '', effectivePolicyCheck(p) ?? '']);
+}
+
+/**
+ * Is this policy SUBSUMED — does an identical rule already reach every role it names?
+ *
+ * PERMISSIVE policies OR together, and a policy TO PUBLIC applies to every role there is. So a
+ * role-scoped policy whose rule is character-for-character a PUBLIC policy's rule contributes
+ * nothing: every session it would admit is already admitted. Dropping it changes no access,
+ * which is why it is churn rather than a change — a brownfield database often carries both,
+ * one from the framework and one from a migration written years earlier.
+ *
+ * Two guards, and they are the whole safety of this:
+ *
+ *  - **RESTRICTIVE policies are never subsumed.** They AND rather than OR, so a restrictive
+ *    policy is the thing NARROWING access; removing it would widen. Only permissive policies
+ *    can be redundant, and only a permissive PUBLIC policy can make them so.
+ *  - **The rule must match exactly**, including the effective WITH CHECK. A PUBLIC policy with
+ *    a laxer predicate does not subsume a stricter role-scoped one — under OR the lax rule
+ *    already wins, but the two are not the same state, and hashing them equal would report
+ *    MATCH while the reconciler still had work.
+ */
+export function isPolicySubsumed(t: TableContract, p: PolicyContract): boolean {
+  if (!p.permissive || isPublicPolicy(p)) return false;
+  const key = policyRuleKey(p);
+  // No self-exclusion by NAME: `p` is asked about against BOTH the live and the declared
+  // contract (subsumed before and after), and the compiler routinely picks the same policy
+  // name the brownfield database already uses — so a name guard here would silently exclude
+  // the very PUBLIC policy doing the covering. It is not needed: `p` is non-PUBLIC by the
+  // line above and every candidate is PUBLIC, so `p` can never match itself.
+  return t.policies.some((o) => o.permissive && isPublicPolicy(o) && policyRuleKey(o) === key);
+}
+
 /** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
 export function isWrappedExpression(s: string): boolean {
   if (!s.startsWith('(') || !s.endsWith(')')) return false;
@@ -516,27 +593,23 @@ export function assembleContract(rows: ContractRows): AuthzContract {
 
 /** Run every introspection query through one runner and assemble the contract. */
 export async function introspectContract(
-  run: QueryRunner,
+  session: SessionRunner,
   mapFunctionRow: (row: any) => { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean },
   functionsSql: string,
 ): Promise<AuthzContract> {
-  // Policy USING/WITH CHECK expressions deparse relative to the search_path — pin the
-  // canonical baseline so an ambient non-default path never reads as false authz drift.
-  return withCanonicalSearchPath(run, async () => {
-    const [rls, policies, grants, columnGrants, fnRows] = await Promise.all([
-      run(RLS_SQL),
-      run(POLICIES_SQL),
-      run(GRANTS_SQL),
-      run(COLUMN_GRANTS_SQL),
-      run(functionsSql),
-    ]);
-    return assembleContract({
-      rls: rls as RlsRow[],
-      policies: policies as PolicyRow[],
-      grants: grants as GrantRow[],
-      columnGrants: columnGrants as ColumnGrantRow[],
-      functions: (fnRows as any[]).map(mapFunctionRow),
-    });
+  // ONE session: the five queries describe one moment under one pinned search_path.
+  // Policy USING / WITH CHECK expressions deparse relative to that path, so a read spread
+  // across connections can report authz drift that does not exist.
+  const [rls, policies, grants, columnGrants, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, functionsSql],
+    INTROSPECTION_SESSION,
+  );
+  return assembleContract({
+    rls: rls as RlsRow[],
+    policies: policies as PolicyRow[],
+    grants: grants as GrantRow[],
+    columnGrants: columnGrants as ColumnGrantRow[],
+    functions: (fnRows as any[]).map(mapFunctionRow),
   });
 }
 

package/src/cli/authz-derive.ts

@@ -240,6 +240,58 @@ function sqlFragment(pred: string | null): string | null {
   return `sql\`${t.replace(/`/g, '\\`')}\``;
 }
 
+/** The policy catalog spells the PUBLIC pseudo-role lower-case; grants spell it upper-case. */
+function policyRoleForGrantee(grantee: string): string {
+  return grantee === 'PUBLIC' ? 'public' : grantee;
+}
+
+/** `db:pull` renders fields camel-cased; abilities must name those same model keys. */
+function modelFieldKey(column: string): string {
+  return column.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+/** One column grant is renderable only when exactly one declared-style policy gates it. */
+function columnPolicyFor(contract: TableContract, grantee: string, command: string): PolicyContract | null {
+  const role = policyRoleForGrantee(grantee);
+  const matches = contract.policies.filter((p) =>
+    p.command === command && p.permissive && p.roles.length === 1 && p.roles[0] === role,
+  );
+  return matches.length === 1 ? matches[0] : null;
+}
+
+/** Render one precise column grant plus its exactly-paired policy as one ability. */
+function renderColumnAbility(
+  action: 'read' | 'update',
+  grantee: string,
+  columns: readonly string[],
+  policy: PolicyContract,
+): string | null {
+  const using = policy.using ?? null;
+  const owner = parseOwnerPredicate(using);
+  const parts: string[] = [];
+  const role = policyRoleForGrantee(grantee);
+
+  // Owner-only uses the model's authenticated default. Every other grantee must be named so
+  // the compiler emits the policy TO the live role, rather than a role-less public ability.
+  if (!owner || role !== 'authenticated') parts.push(`role: '${role}'`);
+  if (owner) {
+    parts.push(`owner: '${modelFieldKey(owner.column)}'`);
+    if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+    if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
+  } else {
+    const fragment = sqlFragment(using);
+    if (fragment) parts.push(`sql: ${fragment}`);
+  }
+
+  if (action === 'update' && policy.check && policy.check !== using) {
+    const fragment = sqlFragment(policy.check);
+    if (!fragment) return null;
+    parts.push(`check: ${fragment}`);
+  }
+  parts.push(`columns: [${columns.map((column) => `'${modelFieldKey(column)}'`).join(', ')}]`);
+  return `can('${action}', { ${parts.join(', ')} })`;
+}
+
 /**
  * Derive the ability stanza for ONE table from its live contract.
  *
@@ -274,10 +326,8 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
       if (!live.length || !p.roles.some((r) => r !== 'admin')) continue;
       const viaColumns = live.filter((r) => holdsPrivilege(contract, r, priv));
       if (viaColumns.length) {
-        notes.push(
-          `policy "${p.name}" (${cmd}) is live through the ${viaColumns.join(', ')} COLUMN grant below, not a table grant.`,
-        );
-        notes.push(`  NOT dead. Not rendered either: an ability would grant ${priv} on the whole table.`);
+        // The column-grant pass below carries this pair into a column ability, or names the
+        // exact missing pairing. Do not pre-judge it here as dead or unrenderable.
         continue;
       }
       notes.push(
@@ -299,7 +349,6 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     const anonPol = policiesFor(contract, 'anon', 'SELECT')[0];
     const anonPred = anonPol?.using ?? null;
     const frag = sqlFragment(anonPred);
-    abilities.push(frag ? `can('read', { sql: ${frag} })` : `can('read')`);
 
     // The authenticated SELECT is a SEPARATE policy and routinely says MORE than the anon
     // one — `(public) OR (mine)`, so an author sees their own not-yet-public rows. Reading
@@ -310,25 +359,94 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
       ? policiesFor(contract, 'authenticated', 'SELECT').find((p) => p.name !== anonPol?.name)
       : undefined;
     const authedPred = authedPol?.using ?? null;
-    if (authedPol && (authedPred ?? 'true') !== (anonPred ?? 'true')) {
-      const own = parsePublicOrOwn(authedPred, anonPred);
-      if (own) {
-        const parts = [`owner: '${own.owner.column}'`];
-        if (own.owner.claim !== 'sub') parts.push(`userField: '${own.owner.claim}'`);
-        if (own.owner.expr) parts.push(`ownerExpr: sql\`${own.owner.expr}\``);
-        const guard = sqlFragment(own.ownerSql);
-        if (guard) parts.push(`sql: ${guard}`);
-        abilities.push(`can('read', { ${parts.join(', ')} })`);
-      } else {
-        // P6: it must SAY SO. An unexpressible predicate becomes a comment naming the
-        // policy and its text, never a model that quietly means less.
+    const diverges = !!authedPol && (authedPred ?? 'true') !== (anonPred ?? 'true');
+    const own = diverges ? parsePublicOrOwn(authedPred, anonPred) : null;
+
+    // A role-less `can('read')` fans out to anon AND authenticated — one ability, two policies
+    // and two GRANTS. That is only honest when both roles genuinely hold a table-level SELECT
+    // and the same rule. Two separate ways it was not:
+    //
+    //   - WIDENING: `authedRead` is a TABLE-level check, so a live authenticated SELECT held
+    //     only through COLUMN grants reads as false. The fan-out then granted authenticated
+    //     SELECT on the WHOLE table — the model meaning MORE than the database, which is the
+    //     one thing this project never does. Now the read is scoped to anon alone.
+    //   - NARROWING: when the authenticated rule diverges and cannot be decomposed, the
+    //     fan-out pushed the ANON predicate onto authenticated, silently replacing a live
+    //     owner-admitting read with a public-only one. Now each role carries its own rule.
+    // The fan-out is honest in exactly two cases, and both need authenticated to hold a real
+    // table-level SELECT:
+    //   - the two roles carry the SAME rule, so one ability states it once; or
+    //   - the rule DECOMPOSES, and the `owner:` ability below ADDS the owner branch on top of
+    //     this public one. Scoping this read to anon there would strip authenticated of the
+    //     public half — a narrowing introduced by the fix itself.
+    const fanOutIsHonest = authedRead && (!diverges || !!own);
+
+    // The live read is ONE policy TO PUBLIC — the ordinary Postgres idiom, and an OPEN
+    // audience. Rendering it as the role-scoped pair would mean strictly less than the
+    // database does: every role outside {anon, authenticated} loses the read. `policyRoles`
+    // says the audience without touching the grants, so this transcribes rather than narrows
+    // (B1). Only when PUBLIC is the whole audience — a policy naming public ALONGSIDE a
+    // named role is a different shape and is left to the branches below.
+    const publicAudience = !!anonPol && anonPol.roles.length === 1 && anonPol.roles[0] === 'public';
+
+    if (publicAudience) {
+      abilities.push(frag ? `can('read', { policyRoles: 'public', sql: ${frag} })` : `can('read', { policyRoles: 'public' })`);
+
+      // An OPEN audience must say who it actually opens to, ON THIS TABLE.
+      //
+      // `policyRoles: 'public'` reads like "anyone", and the model vocabulary only names
+      // anon/authenticated/admin — so a reviewer has no way to know that a migrator or an ETL
+      // role also holds SELECT here and therefore reads rows through this very policy. The
+      // pull already names ungoverned grantees once, globally, on stdout; that is the wrong
+      // place and the wrong granularity for a decision recorded per table in a committed file.
+      // Adopting an open audience without seeing its real membership is exactly "inert must
+      // never mean blind".
+      const openTo = Object.keys(contract.grants)
+        .filter((r) => !GOVERNED_VOCABULARY.has(r) && holdsPrivilege(contract, r, 'SELECT'))
+        .sort();
+      if (openTo.length) {
         notes.push(
-          `policy "${authedPol.name}" (SELECT) grants authenticated MORE than the anon read,`,
+          `policyRoles: 'public' is an OPEN audience — it also admits ${openTo.join(', ')}, which hold`,
         );
-        notes.push(`  and its shape is not expressible as abilities. Live USING:`);
-        notes.push(`    ${authedPred}`);
-        notes.push(`  Declare it by hand, or leave the table adopted. NOT rendered above.`);
+        notes.push(`  SELECT on this table. The grants are unchanged; this names who the policy reaches.`);
       }
+    } else if (fanOutIsHonest) {
+      abilities.push(frag ? `can('read', { sql: ${frag} })` : `can('read')`);
+    } else {
+      abilities.push(frag ? `can('read', { role: 'anon', sql: ${frag} })` : `can('read', { role: 'anon' })`);
+    }
+
+    if (diverges && own) {
+      const parts = [`owner: '${own.owner.column}'`];
+      if (own.owner.claim !== 'sub') parts.push(`userField: '${own.owner.claim}'`);
+      if (own.owner.expr) parts.push(`ownerExpr: sql\`${own.owner.expr}\``);
+      const guard = sqlFragment(own.ownerSql);
+      if (guard) parts.push(`sql: ${guard}`);
+      abilities.push(`can('read', { ${parts.join(', ')} })`);
+    } else if (diverges && authedRead) {
+      // TRANSCRIBE, never synthesize. The structured parse failed, so the live predicate is
+      // carried VERBATIM and scoped to exactly the role that holds it — meaning preserved
+      // bit for bit, at the cost of a model that expresses little. The note below is
+      // DISCLOSURE, not refusal: `verbatim-sql:` is a stable marker so an adoption that
+      // reached zero through escape hatches can be counted apart from one that reached zero
+      // through vocabulary. Fidelity achieved is not expressiveness achieved.
+      abilities.push(`can('read', { role: 'authenticated', sql: sql\`${authedPred!.replace(/`/g, '\\`')}\` })`);
+      notes.push(
+        `verbatim-sql: policy "${authedPol!.name}" (SELECT) grants authenticated MORE than the anon read.`,
+      );
+      notes.push(`  Its shape does not decompose, so it is transcribed VERBATIM above, scoped to`);
+      notes.push(`  authenticated. The model does not interpret it. Restructure by hand into`);
+      notes.push(`  owner:/via: when you can — until then this table is adopted, not expressed.`);
+    } else if (diverges) {
+      // Diverges, and authenticated does NOT hold a table-level SELECT — a column-scoped grant,
+      // or none. Rendering the read either way would widen it to the whole table, so we refuse
+      // and say so. The residual statements in db:plan ARE the visibility here.
+      notes.push(
+        `policy "${authedPol!.name}" (SELECT) grants authenticated MORE than the anon read,`,
+      );
+      notes.push(`  but authenticated holds no TABLE-level SELECT — rendering it would widen a`);
+      notes.push(`  column-scoped grant to the whole table. NOT rendered. Live USING:`);
+      notes.push(`    ${authedPred}`);
     }
   } else if (authedRead) {
     const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
@@ -380,30 +498,37 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     abilities.push(`can('${action}'${parts.length ? `, { ${parts.join(', ')} }` : ''})`);
   }
 
-  // --- the column grants, which nothing above renders -----------------------------------
+  // --- column grants ---------------------------------------------------------------------
   //
-  // The model expresses column scoping for READ only (`can('read', { owner, columns })`), and
-  // even that pairs with an owner policy this deriver does not attempt to reconstruct. So
-  // every live column grant is a privilege the rendered model does not carry, and the first
-  // plan REVOKES it — 11 statements on the reference schema, none of which had a word beside
-  // the model the adopter reviews.
-  //
-  // Named exactly: grantee, privilege, and the columns. A count is not auditable, and "some
-  // column grants were not captured" is the shape of silence this note exists to break.
+  // A column grant is live access, not a lesser table grant. Render SELECT and UPDATE when
+  // exactly one permissive policy TO the same role proves the row gate. Anything else stays a
+  // note: guessing the pairing could grant the right columns under the wrong row policy.
+  const renderedColumnRoles = new Set<string>();
   for (const grantee of Object.keys(contract.columnGrants ?? {}).sort()) {
-    if (!GOVERNED_VOCABULARY.has(grantee)) continue; // ungoverned: left alone, never revoked
     const byPriv = contract.columnGrants![grantee];
     for (const priv of Object.keys(byPriv).sort()) {
       const cols = byPriv[priv] ?? [];
       if (!cols.length) continue;
+      const action = priv === 'SELECT' ? 'read' : priv === 'UPDATE' ? 'update' : null;
+      const policy = action ? columnPolicyFor(contract, grantee, priv) : null;
+      const ability = action && policy ? renderColumnAbility(action, grantee, cols, policy) : null;
+      if (ability) {
+        abilities.push(ability);
+        renderedColumnRoles.add(grantee);
+        continue;
+      }
       notes.push(`${grantee} holds a COLUMN-scoped ${priv} on ${cols.length} column(s): ${cols.join(', ')}.`);
-      notes.push(`  NOT rendered — the model has no way to declare it. The next plan REVOKES it.`);
+      notes.push(
+        action
+          ? `  NOT rendered — it needs exactly one permissive ${priv} policy TO ${policyRoleForGrantee(grantee)}.`
+          : `  NOT rendered — the model supports column-scoped SELECT and UPDATE only.`,
+      );
     }
   }
 
   // --- roles the compiler has no vocabulary for ----------------------------------------
   const unmappedRoles = Object.keys(contract.grants).filter(
-    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public',
+    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public' && !renderedColumnRoles.has(r),
   );
 
   if (!abilities.length && !notes.length && !unmappedRoles.length) {

package/src/cli/authz-reconcile.ts

@@ -16,7 +16,7 @@
  */
 
 import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
-import { effectivePolicyCheck, parenthesizeOnce } from './authz-contract.js';
+import { effectivePolicyCheck, parenthesizeOnce, isPolicyDead, isPolicySubsumed } from './authz-contract.js';
 import { matchPolicies } from './authz-identity.js';
 import { quoteQualified } from './pg-ident.js';
 
@@ -169,7 +169,7 @@ export function emitReconcileSql(
     // the EMITTED SQL must quote it, or a reserved table name (`public.user`) is a syntax error.
     const table = quoteQualified(d.table);
     reconcileRls(table, d, l, sql);
-    reconcilePolicies(table, d, l, sql);
+    reconcilePolicies(table, d, l, sql, governed);
     reconcileGrants(table, d, l, sql, governed);
     reconcileColumnGrants(table, d, l, sql, governed);
   }
@@ -230,11 +230,53 @@ function reconcileRls(table: string, d: TableContract, l: TableContract | undefi
  * The matcher requires full field equality, so this can only turn a DROP + CREATE pair into a
  * no-op — never emit DDL the name-keyed version would not have emitted.
  */
-function reconcilePolicies(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
-  const m = matchPolicies(d.policies, l?.policies ?? []);
+function reconcilePolicies(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {
+  const live = l?.policies ?? [];
+  const m = matchPolicies(d.policies, live);
+  const byName = new Map(live.map((p) => [p.name, p]));
+
   // Drops first, so a replaced policy never briefly co-exists with its old form.
-  for (const name of m.toDrop) out.push(policyDropSql(table, name));
-  for (const p of m.toCreate) out.push(policyCreateSql(table, p));
+  for (const name of m.toDrop) {
+    // A live policy scoped ENTIRELY to roles the models do not govern is left alone, exactly
+    // as reconcileGrants leaves that role's privileges alone. Without this the two lanes
+    // disagree about the same role: it keeps its GRANT and loses its POLICY, and on an
+    // RLS-enabled table that combination reads zero rows. A bounded read-only role added for
+    // one indexable query is the shape this bites — the model has no word for it, so "no
+    // declaration" and "no access" collapsed into the same thing. Same failure as the
+    // ungoverned-grantee bug, one lane over.
+    //
+    // Only when EVERY role is ungoverned. A policy naming anon alongside such a role still
+    // governs anon, and leaving it would be the reconciler declining to do its job.
+    const p = byName.get(name);
+    if (p && p.roles.length > 0 && p.roles.every((r) => !isGoverned(governed, r))) continue;
+    // A DEAD policy authorizes nothing — no role it names holds the privilege it polices, so
+    // Postgres refuses at the GRANT before ever consulting it. Dropping it changes no access,
+    // which makes it churn: a statement an adopter must read, approve and apply to reach zero,
+    // whose only effect is to tidy a catalog. Leave it, exactly as the canonical form leaves
+    // it out of the state.
+    //
+    // DEAD BEFORE **AND AFTER**, and the second half is the whole safety of this. Deadness is
+    // a property of the contract, not the policy: if THIS plan grants the privilege the policy
+    // polices, the policy wakes up the moment the plan lands — undeclared, ungoverned, and
+    // granting access the model never asked for. Leaving it would be a widening the plan
+    // performs on itself. So it may only be left alone when the DECLARED state keeps it just
+    // as inert as the live one does.
+    if (p && l && isPolicyDead(l, p) && isPolicyDead(d, p)) continue;
+    // Subsumed, before AND after, for exactly the reason deadness needs both: if this plan
+    // drops the PUBLIC policy that was covering it, the role-scoped one stops being redundant
+    // the moment the plan lands — and leaving it would keep access the model never declared.
+    if (p && l && isPolicySubsumed(l, p) && isPolicySubsumed(d, p)) continue;
+    out.push(policyDropSql(table, name));
+  }
+  // Symmetric with the drop rule above, and required by the same identity: a DECLARED policy
+  // the declared grants do not back is inert — it would authorize nothing the moment it
+  // landed. The canonical form already leaves it out of the declared state, so creating it
+  // would emit a statement for a difference the hash says does not exist. It appears the
+  // moment the model grants the privilege it polices.
+  for (const p of m.toCreate) {
+    if (isPolicyDead(d, p) || isPolicySubsumed(d, p)) continue;
+    out.push(policyCreateSql(table, p));
+  }
 }
 
 function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {

package/src/cli/aws.ts

@@ -7,6 +7,7 @@
 
 import { isOpsHandlerCrash, formatOpsCrashReport, fetchDiagnosisWithRetry } from './ops-diagnostics.js';
 import { tagInvokeTransport } from './ops-advice.js';
+import type { SessionRunner } from './session.js';
 
 let s3Client: InstanceType<typeof import('@aws-sdk/client-s3').S3Client> | null = null;
 let lambdaClient: InstanceType<typeof import('@aws-sdk/client-lambda').LambdaClient> | null = null;
@@ -302,6 +303,37 @@ export function lambdaQueryRunner(
   };
 }
 
+/**
+ * A `SessionRunner` backed by the ops Lambda's `db:session` action — the stage lane's
+ * only consistent read.
+ *
+ * `lambdaQueryRunner` above sends one invoke per statement, so a multi-statement read is
+ * answered by however many containers happen to be warm, each on its own connection.
+ * This sends the statements TOGETHER: one invoke, one container, one connection, one
+ * transaction. The response arrives gzipped (catalog JSON compresses 10-20x, which is
+ * what keeps a real schema inside the 6 MB invoke-response limit).
+ */
+export function lambdaSessionRunner(
+  region: string,
+  functionName: string,
+  invoke: typeof invokeAction = invokeAction,
+): SessionRunner {
+  return async (statements, opts) => {
+    const result: any = await invoke(region, functionName, 'db:session', {
+      statements,
+      ...(opts ?? {}),
+    });
+    if (result?.error) throw new Error(`Session failed: ${result.error}`);
+    if (typeof result?.gzip !== 'string') {
+      throw new Error(
+        'the ops Lambda did not answer db:session. Deploy a server build that ships the db:session action — the stage lane cannot read consistently without it.',
+      );
+    }
+    const { gunzipSync } = await import('node:zlib');
+    return JSON.parse(gunzipSync(Buffer.from(result.gzip, 'base64')).toString('utf8'));
+  };
+}
+
 export async function invokeAction(
   region: string,
   functionName: string,