@everystack/cli 0.4.41 → 0.4.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.41",
+  "version": "0.4.44",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -109,7 +109,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.7"
+    "@everystack/model": "0.4.9"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",

package/src/cli/authz-compile.ts

@@ -22,6 +22,7 @@
 
 import type { ModelDescriptor, Ability } from '@everystack/model';
 import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract.js';
+import { parenthesizeOnce } from './authz-contract.js';
 
 export interface CompileOptions {
   /** Schema the table lives in. Default: `public`. */
@@ -65,7 +66,11 @@ function claimExpr(claim: string): string {
  *   uuid: (author_id = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))::uuid)
  *   text: (user_id   =  ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))
  */
-function ownerPredicate(sqlColumn: string, type: string, claim: string): string {
+function ownerPredicate(sqlColumn: string, type: string, claim: string, expr: string | null = null): string {
+  // A declared `ownerExpr` is the accessor the database already has (`auth.user_id()`),
+  // emitted verbatim and uncast: the function returns the owner column's type, and a cast
+  // the deparser would not print is a DROP + CREATE on every owner policy in the schema.
+  if (expr) return `(${sqlColumn} = ${expr})`;
   const ce = claimExpr(claim);
   if (type === 'text') return `(${sqlColumn} = ${ce})`;
   return `(${sqlColumn} = (${ce})::${castForType(type)})`;
@@ -88,7 +93,7 @@ function softDeleteGuard(sqlColumn: string): string {
  *     WHERE (uploads.user_id = ((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text))))
  */
 function viaPredicate(v: ViaRef): string {
-  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim);
+  const parentOwner = ownerPredicate(`${v.parentTable}.${v.parentOwner.sqlColumn}`, v.parentOwner.type, v.parentOwner.claim, v.parentOwner.expr);
   return `(${v.fkColumn} IN ( SELECT ${v.parentTable}.${v.parentPk}\n   FROM ${v.parentTable}\n  WHERE ${parentOwner}))`;
 }
 
@@ -102,6 +107,8 @@ interface OwnerRef {
   type: string;
   /** JWT claim holding the owner id. */
   claim: string;
+  /** A declared accessor for the caller's id (`auth.user_id()`), or null for the inline claim. */
+  expr: string | null;
 }
 
 /**
@@ -134,6 +141,7 @@ function resolveOwner(model: ModelDescriptor): OwnerRef | null {
     sqlColumn: toSnakeCase(fieldKey),
     type: model.fields[fieldKey]?.spec.type ?? 'uuid',
     claim: ownerAbility.condition.userField ?? 'sub',
+    expr: rawExpr(ownerAbility.condition.ownerExpr, `${model.table}: can({ ownerExpr })`),
   };
 }
 
@@ -176,9 +184,17 @@ function resolveVia(model: ModelDescriptor): ViaRef | null {
   };
 }
 
-/** The conventional soft-delete column SQL name, when the model has one. */
+/**
+ * The soft-delete column SQL name, when the model DECLARES one.
+ *
+ * Keyed on `softDelete`, never on the field's presence. A column named `deleted_at` is not a
+ * statement of visibility intent, and inferring the guard from it made the compiler author a
+ * security predicate nobody wrote — one that `db:pull` then handed to every brownfield model
+ * automatically, so the first plan narrowed a policy the adopter had written. `defineModel`
+ * refuses to guess: a model with the field and a public read must say which it means.
+ */
 function softDeleteColumn(model: ModelDescriptor): string | null {
-  return 'deletedAt' in model.fields ? 'deleted_at' : null;
+  return model.softDelete ? 'deleted_at' : null;
 }
 
 /**
@@ -228,7 +244,28 @@ function rawPredicate(value: unknown, where: string): string | null {
       `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — an RLS predicate is authored, never stringly assembled.`,
     );
   }
-  return `(${text.trim()})`;
+  // Parenthesized exactly once. A pulled predicate arrives already fully parenthesized
+  // (that is how pg_get_expr deparses it), and wrapping it again made the compiled policy
+  // differ from the live one by a single layer of parens — enough for the reconciler to
+  // plan a DROP + CREATE that changed nothing.
+  return parenthesizeOnce(text.trim());
+}
+
+/**
+ * Unwrap a sql fragment to its text, UNparenthesized — for an expression that is not a
+ * predicate. `ownerExpr` is the right-hand side of `<col> = …`; parenthesizing it would
+ * emit `(user_id = (auth.user_id()))`, which is not what the deparser prints, and the
+ * whole point of declaring it is to match the live text exactly.
+ */
+function rawExpr(value: unknown, where: string): string | null {
+  if (value == null) return null;
+  const text = (value as { sql?: unknown }).sql;
+  if (typeof text !== 'string' || !text.trim()) {
+    throw new Error(
+      `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — the expression that decides who owns a row is authored, never stringly assembled.`,
+    );
+  }
+  return text.trim();
 }
 
 /** AND-compose predicates, dropping the vacuous ones. A condition only ever NARROWS. */
@@ -257,7 +294,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // parent subquery. Both drive the same owner-gated policies (select/insert/
   // update/delete_own); only the predicate text differs.
   const rowPred = owner
-    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim)
+    ? ownerPredicate(owner.sqlColumn, owner.type, owner.claim, owner.expr)
     : via
       ? viaPredicate(via)
       : null;
@@ -266,16 +303,52 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // A "row-scoped" condition is either a direct owner or a transitive via.
   const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
 
+  /**
+   * A read scoped to a named role — `can('read', { role })`. It compiles to its own
+   * `<table>_select_<role>` policy, so its predicate must NOT also be folded into the
+   * public read's predicate: a rule written for one role would otherwise narrow what
+   * every other role can see.
+   */
+  const isRoleRead = (a: Ability): boolean =>
+    a.action === 'read' && Boolean(a.condition.role) && !isColumnRead(a);
+
   // Author-supplied predicates, per action. `manage` carries no predicate of its own —
   // it is the admin bypass — so only the specific verbs are consulted.
   const predFor = (action: Ability['action']): string | null => {
     for (const a of model.abilities) {
-      if (a.action !== action) continue;
+      if (a.action !== action || isRoleRead(a)) continue;
       const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('${action}')`);
       if (p) return p;
     }
     return null;
   };
+  /**
+   * The predicate on the PUBLIC read — a read ability with neither a role nor a row scope.
+   *
+   * Read separately from {@link ownerReadPred} because the two are different BRANCHES of
+   * the same authenticated policy. Taking both from one ordered lookup made the anon
+   * policy depend on the order the abilities happened to be declared in: put the owner
+   * read first and `anon` inherited the owner branch's guard as its whole public rule.
+   */
+  const publicReadPred = (): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== 'read' || a.condition.role || rowScoped(a)) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('read')`);
+      if (p) return p;
+    }
+    return null;
+  };
+
+  /** The predicate the OWNER read narrows ITSELF by — `can('read', { owner, sql })`. */
+  const ownerReadPred = (): string | null => {
+    for (const a of model.abilities) {
+      if (a.action !== 'read' || !rowScoped(a) || isColumnRead(a)) continue;
+      const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('read', { owner })`);
+      if (p) return p;
+    }
+    return null;
+  };
+
   /** The WRITE half, when the author declared one distinct from the read half. */
   const checkFor = (action: Ability['action']): string | null => {
     for (const a of model.abilities) {
@@ -312,18 +385,37 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   if (hasPublicRead) {
     // public read on a soft-delete table — split per role; authenticated owners
     // also see their own (soft-deleted) rows, hence the OR'd owner check.
-    const readPred = predFor('read');
+    const readPred = publicReadPred();
     const anonUsing = andPredicates(sdGuard, readPred) ?? 'true';
     policy(`${t}_select_anon`, 'SELECT', ['anon'], anonUsing, null);
 
-    // The owner predicate may only ever WIDEN a public read (the soft-delete OR:
-    // owners also see their own deleted rows). It must never REPLACE it — an owner
-    // condition on a WRITE ability used to narrow the authenticated SELECT to
-    // own-rows-only, so anon saw the whole table and a signed-in user lost it.
-    // Without a soft-delete guard, `true OR owner` is just `true`.
-    const authedUsing = sdGuard && rowPred
-      ? andPredicates(`(${sdGuard} OR ${rowPred})`, readPred)!
-      : anonUsing;
+    let authedUsing: string;
+    if (hasOwnerRead && rowPred && anonUsing !== 'true') {
+      // PUBLIC **OR** MINE. Two read abilities on one model — a public read and an
+      // owner read — are two branches of one authenticated policy, not a contest the
+      // public one wins. They used to be exactly that contest: `hasPublicRead` took
+      // the branch and the owner read was computed and discarded, so a signed-in
+      // author could not see their own non-public rows. On a real brownfield schema
+      // that hid ~13k legacy `pending` rows from the people who wrote them.
+      //
+      // The owner branch escapes the public predicate (that is the whole point) and
+      // carries its OWN guard — `can('read', { owner: 'userId', sql: … })` — so the
+      // author says what "mine" means without loosening what "public" means.
+      const ownBranch = andPredicates(rowPred, ownerReadPred())!;
+      authedUsing = `(${anonUsing} OR ${ownBranch})`;
+    } else {
+      // The owner predicate may only ever WIDEN a public read (the soft-delete OR:
+      // owners also see their own deleted rows). It must never REPLACE it — an owner
+      // condition on a WRITE ability used to narrow the authenticated SELECT to
+      // own-rows-only, so anon saw the whole table and a signed-in user lost it.
+      // Without a soft-delete guard, `true OR owner` is just `true` — and an
+      // unfiltered public read already contains every row an owner could add, which
+      // is why `anonUsing === 'true'` skips the disjunction rather than emitting a
+      // branch that can never change the answer.
+      authedUsing = sdGuard && rowPred
+        ? andPredicates(`(${sdGuard} OR ${rowPred})`, readPred)!
+        : anonUsing;
+    }
     policy(`${t}_select_authenticated`, 'SELECT', ['authenticated'], authedUsing, null);
   } else if (hasOwnerRead && rowPred) {
     // owner-scoped read — no anon visibility; you see only the rows you own
@@ -336,6 +428,26 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     policy(`${t}_select_self`, 'SELECT', ['authenticated'], rowPred, null);
   }
 
+  // Role-scoped reads — `can('read', { role })`, with or without a predicate. These match
+  // none of the branches above: the public read requires NO role, and the owner/column reads
+  // require a row-scoping condition. Before this they compiled to a SELECT grant and no
+  // policy at all — and since `rls.enabled` is unconditional, the role saw ZERO rows while
+  // the model read as though it could see its own. The declared predicate was computed and
+  // discarded. That is the same failure `rawPredicate` throws over, one level up: a predicate
+  // that evaporates is an authorization hole wearing the costume of a working rule.
+  for (const a of abilities.filter(isRoleRead)) {
+    const role = a.condition.role!;
+    const name = `${t}_select_${role}`;
+    const where = `${table}: can('read', { role: '${role}' })`;
+    if (policies.some((p) => p.name === name)) {
+      throw new Error(
+        `${where} collides with the ${name} policy already compiled from this model's public read. `
+        + `Declare one or the other: permissive policies OR together, so the role-scoped rule could only ever widen — never the narrowing it reads as.`,
+      );
+    }
+    policy(name, 'SELECT', [role], rawPredicate(a.condition.sql ?? a.condition.where, where) ?? 'true', null);
+  }
+
   // owner-gated writes. INSERT checks ownership (you can only create rows you own);
   // UPDATE gates + checks; DELETE gates. `rowPred` is the direct-owner or `via:` predicate.
   //

package/src/cli/authz-contract.ts

@@ -82,6 +82,51 @@ export interface PolicyContract {
   check: string | null;
 }
 
+/**
+ * The WITH CHECK expression PostgreSQL will actually enforce.
+ *
+ * For `ALL` and `UPDATE`, an omitted `WITH CHECK` is not "no check" — the server reuses the
+ * `USING` expression. So a live `FOR ALL USING (true)` (which is what `CREATE POLICY … USING
+ * (true)` records, with `pg_policies.with_check` NULL) and a compiled `FOR ALL USING (true)
+ * WITH CHECK (true)` are the SAME authorization. Comparing the raw fields calls them
+ * different and plans a DROP + CREATE — the loudest possible way to say "no change", and it
+ * defeats a zero-statement bar even when the SQL is identical.
+ *
+ * `INSERT` has only a check, `SELECT`/`DELETE` have none — for those the field stands alone
+ * and no defaulting applies.
+ */
+export function effectivePolicyCheck(p: PolicyContract): string | null {
+  if (p.command === 'ALL' || p.command === 'UPDATE') return p.check ?? p.using;
+  return p.check;
+}
+
+/** 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;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * A predicate parenthesized exactly once — the normal form both producers must agree on.
+ *
+ * `pg_get_expr` already deparses a policy predicate fully parenthesized, so `db:pull` renders
+ * one into a model verbatim. Wrapping it again produced a compiled predicate identical to
+ * live but for one layer of parens, which the equality check called a difference and turned
+ * into a same-name DROP + CREATE that changed nothing. Emission already knew this rule; the
+ * comparison did not, so both go through this.
+ */
+export function parenthesizeOnce(expr: string): string {
+  return isWrappedExpression(expr) ? expr : `(${expr})`;
+}
+
 /**
  * One function, enumerated. The cross-table authorization that RLS does not hold lives
  * in SECURITY DEFINER functions as imperative gates; the contract records that they
@@ -581,7 +626,9 @@ function diffPolicies(table: string, d: TableContract, l: TableContract, out: Dr
     if (dp.permissive !== lp.permissive) changes.push(`permissive ${dp.permissive}→${lp.permissive}`);
     if (dp.roles.join(',') !== lp.roles.join(',')) changes.push(`roles [${dp.roles}]→[${lp.roles}]`);
     if ((dp.using ?? '') !== (lp.using ?? '')) changes.push(`USING changed`);
-    if ((dp.check ?? '') !== (lp.check ?? '')) changes.push(`WITH CHECK changed`);
+    // Compared through the server's own defaulting rule, so this agrees with
+    // emitReconcileSql — otherwise db:check reports drift the plan does not carry.
+    if ((effectivePolicyCheck(dp) ?? '') !== (effectivePolicyCheck(lp) ?? '')) changes.push(`WITH CHECK changed`);
     if (changes.length) {
       out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
     }

package/src/cli/authz-derive.ts

@@ -65,11 +65,120 @@ const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
 const OWNER_RE =
   /^\(?([a-z_][a-z0-9_]*)\s*=\s*\(*\(current_setting\('request\.jwt\.claims'::text,\s*true\)\)::jsonb\s*->>\s*'([a-z_]+)'::text\)*(?:::[a-z]+)?\)?$/i;
 
-/** Does this predicate say "the row is mine"? Returns the column and the claim if so. */
-export function parseOwnerPredicate(pred: string | null): { column: string; claim: string } | null {
+/**
+ * The OTHER owner shape: the database's own accessor, `(<col> = auth.user_id())`.
+ *
+ * A brownfield schema almost always has one — a STABLE SECURITY DEFINER function wrapping
+ * the same claim read — and every owner policy in it is written against that function, not
+ * against the claim inline. Rendering those as the inline claim would be a semantically
+ * similar but TEXTUALLY different predicate, and predicates are diffed as text: it would
+ * plan a DROP + CREATE on every owner policy in the schema.
+ *
+ * Deliberately narrow: the right side must be a zero-argument function call. That is what
+ * an "who am I" accessor looks like, and it is what a column-to-column comparison
+ * (`(user_id = reviewer_id)`) is not — so the matcher cannot mistake a join predicate for
+ * a statement of ownership.
+ */
+const OWNER_FN_RE = /^\(?([a-z_][a-z0-9_]*)\s*=\s*((?:[a-z_][a-z0-9_]*\.)?[a-z_][a-z0-9_]*\(\))\)?$/i;
+
+/**
+ * Does this predicate say "the row is mine"? Returns the column, the claim, and the
+ * accessor expression when the schema uses one (null = the claim read inline).
+ */
+export function parseOwnerPredicate(
+  pred: string | null,
+): { column: string; claim: string; expr: string | null } | null {
   if (!pred) return null;
-  const m = OWNER_RE.exec(pred.trim());
-  return m ? { column: m[1], claim: m[2] } : null;
+  const t = pred.trim();
+  const m = OWNER_RE.exec(t);
+  if (m) return { column: m[1], claim: m[2], expr: null };
+  const f = OWNER_FN_RE.exec(t);
+  return f ? { column: f[1], claim: 'sub', expr: f[2] } : null;
+}
+
+/**
+ * Split a predicate on a top-level operator, respecting parens and string literals.
+ *
+ * Needed because the shapes worth recognising are compositional — `(public) OR (mine AND
+ * guard)` — and a naive `.split(' OR ')` cuts inside a nested disjunction, which is how a
+ * template matcher silently mis-reads `((state <> 'deleted') AND ((user_id = …) OR (…)))`
+ * as a top-level OR it is not.
+ */
+function splitTopLevel(pred: string, op: 'OR' | 'AND'): string[] {
+  const needle = ` ${op} `;
+  const parts: string[] = [];
+  let depth = 0;
+  let quoted = false;
+  let start = 0;
+  // Strip one enclosing paren pair so the operator we want is genuinely at depth 0.
+  const s = unwrapOnce(pred.trim());
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") { quoted = !quoted; continue; }
+    if (quoted) continue;
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (depth === 0 && s.startsWith(needle, i)) {
+      parts.push(s.slice(start, i));
+      i += needle.length - 1;
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** Drop one enclosing paren pair, but only when it spans the WHOLE expression. */
+function unwrapOnce(s: string): string {
+  if (!s.startsWith('(') || !s.endsWith(')')) return s;
+  let depth = 0;
+  let quoted = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") { quoted = !quoted; continue; }
+    if (quoted) continue;
+    if (c === '(') depth++;
+    else if (c === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return s; // the pair closed early — not enclosing
+    }
+  }
+  return depth === 0 ? s.slice(1, -1).trim() : s;
+}
+
+/**
+ * Decompose an authenticated read of the form `(public) OR (mine [AND guard])`, given the
+ * public predicate the anon policy already states.
+ *
+ * Keyed on the ANON PREDICATE APPEARING VERBATIM as one of two top-level disjuncts, and an
+ * owner predicate appearing in the other — not on a shape template. The alternative,
+ * matching a `X OR (Y AND Z)` template, both over- and under-fires: it claims predicates it
+ * has not proven are a public branch, and it misses the schema whose OR is nested inside an
+ * AND. Anything that does not decompose EXACTLY returns null, and the caller says so.
+ */
+export function parsePublicOrOwn(
+  authedPred: string | null,
+  anonPred: string | null,
+): { owner: { column: string; claim: string; expr: string | null }; ownerSql: string | null } | null {
+  if (!authedPred || !anonPred) return null;
+  const branches = splitTopLevel(authedPred, 'OR');
+  if (branches.length !== 2) return null;
+
+  const anonNorm = unwrapOnce(anonPred.trim());
+  const publicIdx = branches.findIndex((b) => unwrapOnce(b) === anonNorm);
+  if (publicIdx === -1) return null;
+
+  const ownBranch = branches[1 - publicIdx];
+  const conjuncts = splitTopLevel(ownBranch, 'AND');
+  const ownerIdx = conjuncts.findIndex((c) => parseOwnerPredicate(c));
+  if (ownerIdx === -1) return null;
+
+  const owner = parseOwnerPredicate(conjuncts[ownerIdx])!;
+  const rest = conjuncts.filter((_, i) => i !== ownerIdx);
+  // More than one leftover conjunct would have to be re-ANDed, and the text the compiler
+  // then emits is not guaranteed to be the text that was read. Refuse rather than guess.
+  if (rest.length > 1) return null;
+  return { owner, ownerSql: rest[0] ?? null };
 }
 
 /** Is a privilege EFFECTIVE for a role — i.e. actually granted, not merely policed? */
@@ -135,15 +244,48 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
   if (anonRead) {
     // Public read. If the live policy narrows it (a soft-delete guard, a published flag),
     // carry that predicate — a public read with a filter is still a public read.
-    const pol = policiesFor(contract, 'anon', 'SELECT')[0];
-    const frag = sqlFragment(pol?.using ?? null);
+    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
+    // only the anon policy dropped that branch and rendered a model that meant strictly
+    // less than the database did, with nothing said. On a real schema it hid ~13,184
+    // legacy rows from the people who wrote them.
+    const authedPol = authedRead
+      ? 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.
+        notes.push(
+          `policy "${authedPol.name}" (SELECT) grants authenticated MORE than the anon read,`,
+        );
+        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.`);
+      }
+    }
   } else if (authedRead) {
     const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
     const owner = parseOwnerPredicate(pol?.using ?? null);
     if (owner) {
-      const claim = owner.claim === 'sub' ? '' : `, userField: '${owner.claim}'`;
-      abilities.push(`can('read', { owner: '${owner.column}'${claim} })`);
+      const parts = [`owner: '${owner.column}'`];
+      if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+      if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
+      abilities.push(`can('read', { ${parts.join(', ')} })`);
     } else {
       const frag = sqlFragment(pol?.using ?? null);
       abilities.push(frag ? `can('read', { role: 'authenticated', sql: ${frag} })` : `can('read', { role: 'authenticated' })`);
@@ -165,6 +307,7 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     if (owner) {
       parts.push(`owner: '${owner.column}'`);
       if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+      if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
     }
     // A predicate beyond the owner gate (a state guard, a tenant filter) rides as `sql`.
     const usingFrag = owner && parseOwnerPredicate(using) ? null : sqlFragment(using);
@@ -200,7 +343,11 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
 /** Render one table's derived stanza as the lines that sit inside a model literal. */
 export function renderDerivedAbilities(d: DerivedAbilities): string {
   const out: string[] = [];
-  for (const n of d.notes) out.push(`  // ${n}`);
+  // Split on newlines: a note may carry a live predicate verbatim, and `pg_get_expr`
+  // deparses a subquery across several lines. One `//` for the first line left the rest
+  // as bare SQL in the middle of a TypeScript object — a generated file that would not
+  // parse. Commenting per line here means no note, present or future, can do that.
+  for (const n of d.notes) for (const line of String(n).split('\n')) out.push(`  // ${line}`);
   if (d.abilities.length) {
     out.push(`  abilities: [${d.abilities.join(', ')}],`);
   } else {

package/src/cli/authz-reconcile.ts

@@ -16,6 +16,7 @@
  */
 
 import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import { effectivePolicyCheck, parenthesizeOnce } from './authz-contract.js';
 import { quoteQualified } from './pg-ident.js';
 
 /**
@@ -116,24 +117,8 @@ export function renderGrantExemptions(exemptions: readonly GrantExemption[]): st
   return lines;
 }
 
-/** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
-function isWrapped(s: string): boolean {
-  if (!s.startsWith('(') || !s.endsWith(')')) return false;
-  let depth = 0;
-  for (let i = 0; i < s.length; i++) {
-    if (s[i] === '(') depth++;
-    else if (s[i] === ')') {
-      depth--;
-      if (depth === 0 && i < s.length - 1) return false;
-    }
-  }
-  return depth === 0;
-}
-
 /** A USING/WITH CHECK clause expression, parenthesized exactly once. */
-function clause(expr: string): string {
-  return isWrapped(expr) ? expr : `(${expr})`;
-}
+const clause = parenthesizeOnce;
 
 /** A CREATE POLICY statement from a policy descriptor. */
 function policyCreateSql(table: string, p: PolicyContract): string {
@@ -150,13 +135,19 @@ function policyDropSql(table: string, name: string): string {
   return `DROP POLICY IF EXISTS ${name} ON ${table};`;
 }
 
-/** Two policies are the same authorization when every diffed field matches. */
+/**
+ * Two policies are the same authorization when every diffed field matches. The check is
+ * compared through {@link effectivePolicyCheck}, i.e. the server's own defaulting rule —
+ * a live `FOR ALL USING (true)` and a compiled `FOR ALL USING (true) WITH CHECK (true)`
+ * authorize identically, and reconciling them would emit a DROP + CREATE that changes
+ * nothing.
+ */
 function policiesEqual(a: PolicyContract, b: PolicyContract): boolean {
   return a.command === b.command
     && a.permissive === b.permissive
     && a.roles.join(',') === b.roles.join(',')
     && (a.using ?? '') === (b.using ?? '')
-    && (a.check ?? '') === (b.check ?? '');
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
 }
 
 function tableMap(c: AuthzContract): Map<string, TableContract> {