@everystack/cli 0.4.79 → 0.4.81

package/src/cli/authz-derive.ts

@@ -92,14 +92,20 @@ function deriveExtraPrivileges(contract: TableContract): Record<string, string[]
 }
 
 /**
- * The deparsed owner predicate the compiler produces, in both its casts:
- *   (col = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text)))
+ * The deparsed owner predicate, in BOTH wire spellings — the `::text` casts are optional:
+ *   normalized (what both producers emit since a616a1f3, 2026-08-24, and what a live stage
+ *     returns through `predicate()`'s cross-version normalizer):
+ *       (col = (((current_setting('request.jwt.claims', true))::jsonb ->> 'sub'))::uuid)
+ *   raw old-major deparse (a dump captured before the normalizer, or an older stage):
+ *       (col = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text)))
  * Recognising it turns a predicate back into `{ owner: 'col' }` — the structured shape —
- * instead of an opaque `sql:` fragment. Anything unrecognised stays verbatim rather than
- * being guessed at.
+ * instead of an opaque `sql:` fragment. Before the casts were made optional the matcher
+ * expected only the raw spelling, so a normalized live predicate — every one, today — fell
+ * through to `sql:` and lost the `owner:` on round-trip. Anything unrecognised still stays
+ * verbatim rather than being guessed at.
  */
 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;
+  /^\(?([a-z_][a-z0-9_]*)\s*=\s*\(*\(current_setting\('request\.jwt\.claims'(?:::text)?,\s*true\)\)::jsonb\s*->>\s*'([a-z_]+)'(?:::text)?\)*(?:::[a-z]+)?\)?$/i;
 
 /**
  * The OTHER owner shape: the database's own accessor, `(<col> = auth.user_id())`.
@@ -132,6 +138,33 @@ export function parseOwnerPredicate(
   return f ? { column: f[1], claim: 'sub', expr: f[2] } : null;
 }
 
+/**
+ * Decompose a WRITE predicate into its owner conjunct and the remaining guard.
+ *
+ * The compiler builds an owner write as `rowScope AND where` (USING) and `rowScope AND (check ??
+ * where)` (WITH CHECK). To round-trip, the deriver reverses that: the owner term may be the whole
+ * predicate (`owner = claim`) or one top-level AND conjunct (`owner = claim AND state = 'draft'`),
+ * and everything else is the guard the compiler will AND back in beside the owner. Returns the
+ * owner parse (null when there is none) and the guard text (null when the owner is the whole
+ * predicate). Nothing is guessed: a predicate with no recognisable owner conjunct returns
+ * `{ owner: null, guard: <the whole predicate> }`, which the caller carries verbatim as `sql:`.
+ */
+function splitOwnerPredicate(
+  pred: string | null,
+): { owner: ReturnType<typeof parseOwnerPredicate>; guard: string | null } {
+  if (!pred) return { owner: null, guard: null };
+  const direct = parseOwnerPredicate(pred);
+  if (direct) return { owner: direct, guard: null };
+  const conjuncts = splitTopLevel(pred, 'AND');
+  if (conjuncts.length < 2) return { owner: null, guard: pred };
+  const idx = conjuncts.findIndex((c) => parseOwnerPredicate(c));
+  if (idx === -1) return { owner: null, guard: pred };
+  const owner = parseOwnerPredicate(conjuncts[idx]);
+  const rest = conjuncts.filter((_, i) => i !== idx);
+  const guard = rest.length === 0 ? null : rest.length === 1 ? rest[0] : `(${rest.join(' AND ')})`;
+  return { owner, guard };
+}
+
 /**
  * Split a predicate on a top-level operator, respecting parens and string literals.
  *
@@ -562,7 +595,7 @@ export function deriveAbilities(
     }
 
     if (diverges && own) {
-      const parts = [`owner: '${own.owner.column}'`];
+      const parts = [`owner: '${modelFieldKey(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);
@@ -597,7 +630,7 @@ export function deriveAbilities(
     const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
     const owner = parseOwnerPredicate(pol?.using ?? null);
     if (owner) {
-      const parts = [`owner: '${owner.column}'`];
+      const parts = [`owner: '${modelFieldKey(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(', ')} })`);
@@ -616,22 +649,58 @@ export function deriveAbilities(
       ?? policiesFor(contract, 'authenticated', command)[0];
     const using = pol?.using ?? null;
     const check = pol?.check ?? null;
-    const owner = parseOwnerPredicate(using) ?? parseOwnerPredicate(check);
+    // Decompose both halves into (owner, guard). INSERT carries the owner in WITH CHECK (its
+    // USING is null); UPDATE/DELETE carry it in USING. The owner is recovered from whichever
+    // half has it.
+    const u = splitOwnerPredicate(using);
+    const c = splitOwnerPredicate(check);
+    const owner = u.owner ?? c.owner;
 
     const parts: string[] = [];
     if (owner) {
-      parts.push(`owner: '${owner.column}'`);
+      parts.push(`owner: '${modelFieldKey(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);
-    if (usingFrag) parts.push(`sql: ${usingFrag}`);
-    // The WRITE half, only when it genuinely differs. Postgres defaults it to USING, and
-    // emitting it unconditionally would be noise that also defeats the round-trip diff.
-    if (check && check !== using) {
-      const checkFrag = sqlFragment(check);
-      if (checkFrag) parts.push(`check: ${checkFrag}`);
+      // The USING guard beyond the owner gate (a state guard, a tenant filter) rides as `sql`.
+      const usingGuard = sqlFragment(u.guard);
+      if (usingGuard) parts.push(`sql: ${usingGuard}`);
+      // The WRITE half rides as `check` ONLY when its guard differs from the USING guard. The
+      // compiler defaults WITH CHECK to (rowScope AND where), so emitting an equal guard would
+      // double the owner term on recompile — the round-trip regression this closes.
+      // WITH CHECK handling. `check == null` means the live policy has NO explicit WITH CHECK
+      // (Postgres defaults it to USING at runtime) — emit no `check:` and let the compiler
+      // default it the same way. Only an EXPLICIT check that differs from the USING guard needs a
+      // `check:`, and only in the shapes below.
+      if (command !== 'DELETE' && check != null && c.owner == null) {
+        // The live WITH CHECK does not even restate the owner gate that USING carries — it is
+        // WIDER on the owner axis (the extreme is `WITH CHECK (true)`: write a row you do not
+        // own). The model has no spelling for that, and every `check:` the compiler emits ANDs
+        // the owner back in, so the derived ability necessarily TIGHTENS live. Disclose it rather
+        // than round-trip the loss silently; the residual db:plan statement is the real diff.
+        notes.push(`policy "${pol?.name}" (${command}) has a WITH CHECK that does not restate the owner gate in its USING —`);
+        notes.push(`  it is wider than any owner ability can express, so the rendered model TIGHTENS it to the owner. Live WITH CHECK:`);
+        notes.push(`    ${check}`);
+      } else if (command !== 'DELETE' && check != null && c.owner != null && c.guard == null && u.guard != null) {
+        // Explicit owner-only WITH CHECK while USING carries a guard — the write half is
+        // deliberately WIDER than the read half (the moderation shape this file's header names:
+        // "your own draft rows" to target, "your own row" to write into). Left implicit, the
+        // compiler would default WITH CHECK to (owner AND where) and TIGHTEN it, so the pull would
+        // misreport live. `check: sql`true`` forces WITH CHECK back to the owner gate alone.
+        parts.push('check: sql`true`');
+      } else if (c.guard != null && (c.guard ?? '') !== (u.guard ?? '')) {
+        // An explicit WITH CHECK carrying a DIFFERENT guard than USING (owner ∧ a distinct write
+        // guard). Rides as `check:`; the compiler ANDs the owner back in.
+        const checkFrag = sqlFragment(c.guard);
+        if (checkFrag) parts.push(`check: ${checkFrag}`);
+      }
+    } else {
+      // No owner recovered — carry the predicates verbatim, USING and (differing) WITH CHECK.
+      const usingFrag = sqlFragment(using);
+      if (usingFrag) parts.push(`sql: ${usingFrag}`);
+      if (check && check !== using) {
+        const checkFrag = sqlFragment(check);
+        if (checkFrag) parts.push(`check: ${checkFrag}`);
+      }
     }
 
     if (!parts.length && !pol) {

package/src/cli/authz-reconcile.ts

@@ -89,6 +89,61 @@ export function ungovernedGrants(live: AuthzContract, governed: ReadonlySet<stri
   return out.sort((a, b) => a.grantee.localeCompare(b.grantee) || a.table.localeCompare(b.table));
 }
 
+/**
+ * A declared table's authz AFTER the edge lands — the FULL prediction's per-table building block.
+ *
+ * The reconciler converges the GOVERNED roles onto the declared contract and leaves every other
+ * (foreign) grantee alone. So the post-apply truth for a declared table is: the declared contract
+ * PLUS the live authz of the ungoverned roles. The governed prediction drops that second half; on
+ * a brownfield stage the foreign grants live on, so a `to` endpoint without them can never equal
+ * the post-apply full live hash (milestone plan-endpoint-full).
+ *
+ * Carried ONLY onto objects the declared target still has (condition (a) of the N2 ruling):
+ *  - table-level grants ride whole — the table is present by construction;
+ *  - a column grant rides only for the columns in `presentColumns`; a grant on a column the edge
+ *    DROPS is gone after apply, so carrying it would predict an endpoint the apply cannot reach —
+ *    a false verify-failed after the DDL already landed;
+ *  - a policy rides only when EVERY role it names is ungoverned. A policy touching a governed role
+ *    is the reconciler's to manage, so it is not carried here (if the reconciler leaves it, the
+ *    verify-after fails LOUD rather than being hidden).
+ *
+ * The declared (governed) grants always win over any live grant to the same role: a governed role
+ * whose live grant the models dropped must be REVOKED by the plan, never carried through.
+ */
+export function carryUngovernedAuthz(
+  declared: TableContract,
+  live: TableContract,
+  governed: ReadonlySet<string>,
+  presentColumns: ReadonlySet<string>,
+): TableContract {
+  const foreign = (role: string): boolean => !isGoverned(governed, role);
+
+  const grants: Record<string, string[]> = { ...declared.grants };
+  for (const [role, privileges] of Object.entries(live.grants)) {
+    if (foreign(role)) grants[role] = [...privileges];
+  }
+
+  const columnGrants: Record<string, Record<string, string[]>> = { ...(declared.columnGrants ?? {}) };
+  for (const [role, byPrivilege] of Object.entries(live.columnGrants ?? {})) {
+    if (!foreign(role)) continue;
+    const kept: Record<string, string[]> = {};
+    for (const [privilege, columns] of Object.entries(byPrivilege)) {
+      const present = columns.filter((c) => presentColumns.has(c));
+      if (present.length > 0) kept[privilege] = present;
+    }
+    if (Object.keys(kept).length > 0) columnGrants[role] = kept;
+  }
+
+  const carriedPolicies = live.policies.filter((p) => p.roles.length > 0 && p.roles.every(foreign));
+
+  return {
+    ...declared,
+    grants,
+    ...(Object.keys(columnGrants).length > 0 ? { columnGrants } : {}),
+    policies: [...declared.policies, ...carriedPolicies],
+  };
+}
+
 /**
  * The exemption report, one line per grantee — the shared rendering every surface prints.
  *
@@ -307,7 +362,18 @@ function reconcileSequenceGrants(
 export function emitReconcileSql(
   declared: AuthzContract,
   live: AuthzContract,
-  opts: { governedRoles?: ReadonlySet<string> } = {},
+  opts: {
+    governedRoles?: ReadonlySet<string>;
+    /**
+     * The serial sequences the SAME plan's data phase CREATES (a new serial table, a serial
+     * column added to an existing one) — reconciled as if live with no grants. Without them a
+     * created sequence got no governed grant until the NEXT plan: db:apply verified green and
+     * every INSERT by the governed holder failed `permission denied for sequence` for one plan
+     * cycle (milestone finish-0-4-x F1). They are emitted even when the live side never read
+     * sequences: the plan creates these, so there is no unread live state to misjudge.
+     */
+    createdSequences?: readonly SequenceGrantContract[];
+  } = {},
 ): string[] {
   // Condition C — two phases PER TABLE in one transaction: every access-REMOVING statement
   // (policy DROP, REVOKE, RLS ENABLE/FORCE) before every access-ADDING one (policy CREATE, GRANT,
@@ -325,7 +391,7 @@ export function emitReconcileSql(
   // Absent = the recorder never read sequences; skip the pass entirely rather than diff
   // against a set nobody measured. Grouped once, not re-scanned per table.
   const sequencesByTable = new Map<string, SequenceGrantContract[]>();
-  for (const seq of live.sequenceGrants ?? []) {
+  for (const seq of [...(live.sequenceGrants ?? []), ...(opts.createdSequences ?? [])]) {
     (sequencesByTable.get(seq.table) ?? sequencesByTable.set(seq.table, []).get(seq.table)!).push(seq);
   }
 

package/src/cli/commands/db-check.ts

@@ -80,6 +80,15 @@ export interface StaticCheckInput {
   artifactPath: string;
   /** null = no generated schema artifact on disk. */
   artifactSource: string | null;
+  /**
+   * Where `artifactPath` came from — the same resolution db:generate records. An ABSENT artifact
+   * is only "nothing to match" at the untouched default (an app that never generated one). A path
+   * the operator named with `--schema-out`, or one the journal recorded, is a claim that an
+   * artifact lives there; its absence is the artifact gate vanishing, and must FAIL. Measured:
+   * `db:check --schema-out db/does-not-exist.ts` printed the note and passed with exit 0.
+   * Absent = default (older callers).
+   */
+  artifactOrigin?: 'flag' | 'recorded' | 'default';
   /** Set when a retired db/sql directory still carries .sql files — the tombstone
    *  message (with the migration path); a hard fail, never a shrug. */
   sqlDirRetired?: string | null;
@@ -250,7 +259,19 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     }
   }
 
-  if (input.artifactSource === null) {
+  if (input.artifactSource === null && input.artifactOrigin === 'flag') {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — the path came from --schema-out, so an artifact is expected there. Fix the path, or run db:generate to write it. A named path with nothing at it is a gate that guards nothing.`,
+    });
+  } else if (input.artifactSource === null && input.artifactOrigin === 'recorded') {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — the migration journal records that path as the artifact (db:generate wrote it there). Restore it, run db:generate, or re-record with --schema-out.`,
+    });
+  } else if (input.artifactSource === null) {
     findings.push({
       level: 'note',
       area: 'artifact',
@@ -393,7 +414,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } catch { /* no baseline — see above */ }
 
   const findings = runStaticChecks({
-    modelsPath, models, modelsError, modelFileScans, extensions, artifactPath, artifactSource, sqlDirRetired,
+    modelsPath, models, modelsError, modelFileScans, extensions, artifactPath, artifactSource, artifactOrigin: artifactRes.source, sqlDirRetired,
     sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
     moduleModels: declaredDb?.models ?? null,
     baselineSource,

package/src/cli/commands/db-plan.ts

@@ -49,7 +49,7 @@ import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport } fr
 import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
-import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan';
+import { mintEdgePlan, planHash, buildPlanSummary, explainCarriedBy } from '../edge-plan';
 import { proveDescent, describeDriftOrigin, proveLineageLost, realLineageProbe, type ProveVerdict, type LineageProof } from '../git-descent';
 import { fingerprintLive, divergentSurfaces } from '../schema-fingerprint';
 import { predictLiveState } from '../edge-plan';
@@ -337,16 +337,22 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       await fs.writeFile(out, body, 'utf8');
     }
 
-    // An EMPTY edge between two different fingerprints reads as a contradiction. `from` is the
-    // target's full fingerprint (the concurrency lock at apply); `to` is the declared endpoint
-    // through the models' governed set. They differ by exactly what the plan leaves alone — name
-    // it, computed at mint from the two canonical forms, never stored on the plan.
-    const carriedBy = plan.statements.length === 0 && plan.fromFingerprint !== plan.toFingerprint
-      ? divergentSurfaces(
-        predictLiveState(models, snapshot, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) }).canonical,
-        fingerprintLive(snapshot, contract).canonical,
-      )
-      : undefined;
+    // An EMPTY edge still has a story to tell, and the two cases tell DIFFERENT ones:
+    //  - `from == to`: the full endpoint carried the foreign grants through, so the plan is empty
+    //    AND equal. Name the ungoverned roles (condition (c)) — the operator must still see what
+    //    rides untouched and under which baseline.
+    //  - `from != to`: the FULL prediction failed to reproduce raw live — a real, unexplained
+    //    divergence. The foreign grants are ABSORBED into `to`, so they are NOT the cause; naming
+    //    them would misdirect. Name the divergent surface of the FULL prediction vs live instead.
+    const emptyEdge = plan.statements.length === 0;
+    const carriedBy = !emptyEdge
+      ? undefined
+      : plan.fromFingerprint === plan.toFingerprint
+        ? explainCarriedBy(exemptions, [])
+        : divergentSurfaces(
+          predictLiveState(models, snapshot, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles), carryUngoverned: true }).canonical,
+          fingerprintLive(snapshot, contract).canonical,
+        );
     for (const line of buildPlanSummary(plan, carriedBy ? { carriedBy } : {})) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);