@everystack/server 0.4.29 → 0.4.31

package/src/plugin.ts

@@ -13,6 +13,10 @@ import type {
   APIGatewayProxyStructuredResultV2,
 } from 'aws-lambda';
 import type { ApplyPlanOptions } from '@everystack/cli/apply';
+// The Model-derived wire payloads, declared once in @everystack/model/wire and re-exported by
+// @everystack/cli/wire (the CLI is the only @everystack/* package this bundle can resolve the
+// declaration through — see packages/cli/src/wire.ts). Type-only, so nothing new is bundled.
+import type { ReconcileWirePayload } from '@everystack/cli/wire';
 
 /**
  * The stage lane's apply options, with `checkDescent` made REQUIRED. The fast-forward rule is the
@@ -30,6 +34,7 @@ import {
   responseToResult,
   log,
 } from './index';
+import { splitSqlStatements, stripSqlComments } from './sql-lex';
 
 // --- Plugin Types ---
 
@@ -208,12 +213,19 @@ export function createPluginLambdaHandler(
         // post-write alarm). Stamped on BOTH branches, so a stage whose DB init is failing still
         // tells the CLI its contract — an absent field means the deployed server predates the
         // handshake. Old servers simply omit it; the CLI reads absent as "redeploy the stage".
+        //
+        // `modelContract` is the same handshake for the MODEL-DERIVED payloads (db:provision,
+        // db:converge-ownership, db:reconcile). Two INDEPENDENT numbers, deliberately: applyContract
+        // versions db:apply's persisted plan artifact, modelContract versions an ephemeral payload
+        // computed and consumed in one round trip. A CLI checks whichever one its verb rides.
         const { APPLY_CONTRACT_VERSION } = await import('@everystack/cli/apply');
+        const { MODEL_WIRE_CONTRACT } = await import('@everystack/cli/wire');
+        const contracts = { applyContract: APPLY_CONTRACT_VERSION, modelContract: MODEL_WIRE_CONTRACT };
         try {
           const { actions } = await ensureInitialized();
-          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort(), applyContract: APPLY_CONTRACT_VERSION };
+          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort(), ...contracts };
         } catch (error) {
-          return { ok: false, error: String(error), applyContract: APPLY_CONTRACT_VERSION };
+          return { ok: false, error: String(error), ...contracts };
         }
       }
       const { ctx, actions } = await ensureInitialized();
@@ -487,6 +499,56 @@ export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext)
 
 // --- Database Actions Plugin ---
 
+/**
+ * Run `fn` inside a transaction that ALWAYS rolls back, and return what `fn` returned.
+ *
+ * Three actions need exactly this: `db:query` (read-only by construction), `db:authz:probe`
+ * (writes on purpose, keeps none) and the console sandbox.
+ *
+ * The abort is a private object thrown by THIS function and recognised by IDENTITY. Nothing
+ * else can reference `signal`, so `err !== signal` is exact: the only error this swallows is
+ * its own, and every other error propagates untouched — a failed statement is still a failure.
+ *
+ * Why not `tx.rollback()`. drizzle's `rollback()` is nothing but `throw new
+ * TransactionRollbackError()` — there is no database call behind it, and postgres.js rolls the
+ * transaction back because the callback THREW, whatever it threw (proven live in
+ * `__tests__/tx-rollback-live.test.ts`). So the method buys nothing, and it costs: the console
+ * sandbox binds the expression's `db` to this very `tx`, so an expression can call
+ * `db.rollback()` — indistinguishable from ours under any check on the ERROR CLASS, which
+ * turned a failed expression into a silent `{ result: undefined }` — or replace it,
+ * `db.rollback = () => {}`, after which the callback returns normally and the driver COMMITS.
+ * Throwing our own value keeps the mechanism out of the work's reach entirely.
+ *
+ * The class stays drizzle's `TransactionRollbackError` so the abort reads correctly in
+ * drizzle's own taxonomy and in logs; identity, not the class, is what decides.
+ *
+ * `value!` is honest: `signal` is thrown only after the assignment above it.
+ *
+ * The direct-connection twin of `db:authz:probe` — `createUrlProbeRunner`'s `probe()` in
+ * `packages/cli/src/cli/db-source.ts` — keeps its own identity-Symbol version of this on
+ * purpose: it runs on raw postgres.js `sql.begin()`, with no drizzle and no
+ * `TransactionRollbackError` in reach.
+ */
+async function runRolledBack<T>(
+  db: any,
+  fn: (tx: any) => Promise<T>,
+  config?: Record<string, unknown>,
+): Promise<T> {
+  const { TransactionRollbackError } = await import('drizzle-orm');
+  // Per call, and never handed to `fn` — the work cannot reference it, so it cannot forge it.
+  const signal = new TransactionRollbackError();
+  let value!: T;
+  try {
+    await db.transaction(async (tx: any) => {
+      value = await fn(tx);
+      throw signal; // any throw aborts the transaction; this one is ours
+    }, config);
+  } catch (err: unknown) {
+    if (err !== signal) throw err;
+  }
+  return value;
+}
+
 export interface DbPluginOptions {
   /** Absolute path to drizzle migrations folder. Optional — a db:sync app has no migrations;
    *  migrate/db:reset then answer with a clear error while provision/console/psql still work. */
@@ -520,6 +582,23 @@ export interface DbPluginOptions {
   /** Optional read-replica URL for db:query. When unset, db:query runs on the operator
    *  connection. (No env fallback — pass it explicitly if you have a replica.) */
   readDatabaseUrl?: string;
+  /**
+   * The SELECT-only connection `db:query` runs on — the `reader` login `everystack db:provision
+   * --with-reader` creates (QUERY_DATABASE_URL). Takes precedence over `readDatabaseUrl`.
+   *
+   * WHY it exists, and what it is NOT: db:query already runs its statement inside an explicit
+   * `READ ONLY` transaction that is always rolled back, so a plain statement cannot write. What
+   * that transaction does not fence is a function that opens its OWN connection (`dblink_exec`,
+   * `pg_background`): on a database where such an extension exists, a "read-only" query issued on
+   * the OPERATOR connection can still reach the operator's write privilege. Pointing db:query at a
+   * role that HAS no write privilege closes that side channel by construction.
+   *
+   * UNSET IS A SUPPORTED, DOCUMENTED FALLBACK, NOT AN ERROR: db:query then runs on the operator
+   * connection, protected by the read-only transaction alone. That is the pre-existing behaviour and
+   * it is fine for a database without those extensions — but the caveat is real, so it is stated in
+   * `db:psql --help` and docs/cli.md rather than buried here.
+   */
+  queryDatabaseUrl?: string;
   /** pgSettings callback for console auth context — applied via SET LOCAL when user is present */
   pgSettings?: (user: Record<string, unknown> | null) => Record<string, string>;
   /**
@@ -582,6 +661,30 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // connection can be least-privilege and RLS-gated.
     const opsDb = ctx.adminDb ?? ctx.db;
 
+    /**
+     * The Model-derived wire-contract gate — run FIRST in every action that consumes a payload the
+     * CLI computed from the Models barrel (db:provision, db:converge-ownership, db:reconcile).
+     * Returns the action's `{ error }` when the caller's contract does not match this server's,
+     * and null when it does. See model-wire.ts for why missing is a refusal and not a default.
+     *
+     * PRE-DISPATCH by construction: it resolves no connection and runs no SQL, so calling it
+     * before any other work in the action is what keeps a skewed payload away from the database.
+     * A `@everystack/cli/wire` that will not load is ALSO a refusal — a server that cannot state
+     * its own contract must not accept a payload on the caller's say-so.
+     */
+    const modelWireGate = async (verb: string, payload: unknown): Promise<{ error: string } | null> => {
+      const { modelWireRefusal, modelWireUnavailableRefusal } = await import('./model-wire');
+      let enforced: number;
+      try {
+        ({ MODEL_WIRE_CONTRACT: enforced } = await import('@everystack/cli/wire'));
+      } catch (err) {
+        return { error: modelWireUnavailableRefusal(verb, err) };
+      }
+      const declared = (payload as { modelContract?: unknown } | null | undefined)?.modelContract;
+      const refusal = modelWireRefusal(verb, declared, enforced);
+      return refusal ? { error: refusal } : null;
+    };
+
     // Resolve the logical-backup dependencies (bucket + operator URL) once —
     // shared by db:backup/db:backups/db:restore and by db:apply's auto-snapshot
     // before a destructive staged apply. Returns `{ error }` when unconfigured.
@@ -692,34 +795,142 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     };
 
     // --- db:query ---
+    //
+    // READ-ONLY IS ENFORCED BY POSTGRESQL, NOT BY THIS FILE.
+    //
+    // The guard used to be a keyword blocklist over the statement text. A red team against a
+    // real PostgreSQL 16 proved that is not a security boundary, and cannot be made into one:
+    //
+    //   - The blocklist is structurally incomplete. `WITH x AS (DELETE FROM users RETURNING 1)
+    //     SELECT count(*) FROM x`, `SELECT ... INTO new_table`, `EXPLAIN ANALYZE <write>`,
+    //     `COPY ... FROM`, `CALL <procedure>`, `MERGE`, and `DO $$ ... DELETE ... $$` all begin
+    //     with a word outside the list and write for real. Postgres' grammar is open; a
+    //     blocklist over it is a guess.
+    //   - Checking one string and executing another is a bypass by construction. The old code
+    //     tested `stripSqlComments(statement)` and ran the ORIGINAL, and comment removal used
+    //     to delete the comment with no replacement — so `INSERT/**/INTO users VALUES (1)`
+    //     checked as `INSERTINTO ...` (no match) and executed as a plain INSERT.
+    //   - `\s` after a keyword is not a word boundary. `TRUNCATE"users"` and
+    //     `UPDATE"users"SET name=1` are valid SQL with NO whitespace after the keyword.
+    //
+    // So the statement now runs inside an explicit READ ONLY transaction that ALWAYS rolls
+    // back. Postgres refuses every write above AFTER parsing, from inside the engine, where no
+    // text-level trick reaches. Two properties of that transaction are load-bearing:
+    //
+    //   1. It must be an explicit transaction block with the access mode ON THE BLOCK — not a
+    //      session-level `SET SESSION CHARACTERISTICS` and not only a role-level
+    //      `default_transaction_read_only`. Verified: under session characteristics alone, a
+    //      `CALL` to a procedure that does `SET default_transaction_read_only = off; COMMIT;
+    //      DELETE ...` escapes and deletes rows for real. Inside a real `BEGIN READ ONLY`
+    //      block the same CALL errors.
+    //   2. Exactly ONE statement, still. Verified: inside a read-only block,
+    //      `SET TRANSACTION READ WRITE` succeeds as the FIRST statement (no snapshot taken
+    //      yet) and a following write commits. The one-statement rule is what forecloses that.
+    //
+    // The forced rollback (`runRolledBack`, shared with `db:authz:probe` below and the console
+    // sandbox) is belt and braces: nothing a read-only transaction could still have changed
+    // survives the call.
+    //
+    // ACCEPTED NARROWING: a few quasi-read constructs Postgres itself refuses inside ANY
+    // explicit transaction, or specifically inside a READ ONLY one, now fail here where they
+    // used to run under the old autocommit execution: `VACUUM`/bare `ANALYZE`/`REINDEX`/
+    // `CHECKPOINT` (forbidden in a transaction block, full stop) and `SELECT ... FOR UPDATE`/
+    // `FOR SHARE`/`nextval()` (forbidden specifically under read-only). None of these are
+    // writes this guard exists to stop; they're a real capability loss for an operator who
+    // used `db:query` for one of them. Use a direct connection (`db:psql` without `-c`, or
+    // `db:exec`) for those.
     actions['db:query'] = async (payload, _ctx) => {
       const { sql: querySql } = payload as { sql: string };
       if (!querySql) {
         return { error: 'SQL query is required' };
       }
+      // Exactly one statement, always — see property 2 above, and: a `^`-anchored check
+      // against the raw payload is defeated by a leading `-- comment` and by a second
+      // `;`-joined statement, which Postgres' simple query protocol runs regardless of what
+      // this code inspected. Comment-aware, dollar-quote-aware splitting closes both.
+      const statements = splitSqlStatements(querySql);
+      if (statements.length !== 1) {
+        return {
+          // Distinct from the `!querySql` case above: a payload WAS supplied, it just carried
+          // no executable statement (e.g. all comments) — telling the two apart matters to a
+          // caller branching on the message ("you forgot sql" vs "your sql was empty content").
+          error: statements.length === 0
+            ? 'SQL query contained no executable statement (comments/whitespace only)'
+            : `db:query runs exactly one statement (found ${statements.length}) — a second statement can otherwise re-arm the read-only transaction and write. Use db:exec for a multi-statement script.`,
+        };
+      }
+      const [statement] = statements;
+      // ADVISORY PRE-CHECK ONLY — NOT the security boundary.
+      // Its whole job is a fast, friendly error for the obvious cases before a connection is
+      // even opened. The read-only transaction below is what actually enforces read-only, and
+      // it catches everything this list misses. Do not add patterns here believing you are
+      // closing a hole; a hole here is not a hole in the guard. `\b`, not `\s`, so
+      // `TRUNCATE"users"` is still recognised.
       const writePatterns = [
-        /^INSERT\s/i, /^UPDATE\s/i, /^DELETE\s/i, /^DROP\s/i,
-        /^CREATE\s/i, /^ALTER\s/i, /^TRUNCATE\s/i, /^GRANT\s/i, /^REVOKE\s/i,
+        /^INSERT\b/i, /^UPDATE\b/i, /^DELETE\b/i, /^DROP\b/i,
+        /^CREATE\b/i, /^ALTER\b/i, /^TRUNCATE\b/i, /^GRANT\b/i, /^REVOKE\b/i,
       ];
-      if (writePatterns.some(p => p.test(querySql.trim()))) {
+      if (writePatterns.some(p => p.test(stripSqlComments(statement).trim()))) {
         return {
           error: 'Write operations are not allowed via db:query. Use db:migrate, seed, or console for write operations.',
         };
       }
+      let queryDb: any = opsDb;
+      let adhocClient: { end: () => Promise<void> } | undefined;
+      const { sql } = await import('drizzle-orm');
       try {
-        const { sql } = await import('drizzle-orm');
-        let queryDb = opsDb;
-        const readUrl = options.readDatabaseUrl;
+        // The SELECT-only reader first (a role with no write privilege to reach), then a read
+        // replica, then the operator connection — the documented fallback, fenced only by the
+        // read-only transaction below.
+        const readUrl = options.queryDatabaseUrl || options.readDatabaseUrl;
         if (readUrl) {
           const { drizzle } = await import('drizzle-orm/postgres-js');
           const postgres = (await import('postgres')).default;
-          queryDb = drizzle(postgres(readUrl, { max: 1, idle_timeout: 20, connect_timeout: 10 }));
+          const client = postgres(readUrl, { max: 1, idle_timeout: 20, connect_timeout: 10 });
+          adhocClient = client;
+          queryDb = drizzle(client);
         }
-        const result: any = await queryDb.execute(sql.raw(querySql));
-        const rows = Array.isArray(result) ? result : result.rows || [];
+        // Never commit, not even a read — runRolledBack forces the rollback.
+        const rows = await runRolledBack<any[]>(
+          queryDb,
+          async (tx: any) => {
+            const result: any = await tx.execute(sql.raw(statement));
+            return Array.isArray(result) ? result : result?.rows ?? [];
+          },
+          { accessMode: 'read only' },
+        );
         return { rows };
       } catch (err: any) {
         return { error: err.message || String(err) };
+      } finally {
+        // A SESSION-level advisory lock survives ROLLBACK — `SELECT pg_advisory_lock(1)` is a
+        // read as far as the read-only transaction is concerned, and the lock outlives the
+        // transaction that took it. The ops connection is one long-lived connection per
+        // container (db.ts: `max: 1`), so a lock left behind here would be held until the
+        // container dies. Release everything this statement could have taken. Best-effort by
+        // design: a failure here must not mask the query's own result.
+        //
+        // THIS RELEASE ASSUMES ONE PHYSICAL CONNECTION. `pg_advisory_unlock_all()` only frees
+        // locks held by the backend it runs on, and session state (`SET search_path`, a temp
+        // table) is likewise per-backend. If `opsDb` were a pool, the release could land on a
+        // different connection than the one that took the lock — leaking it — and leftover
+        // session state could surface in an unrelated later call. `createAdminDb` pins the
+        // operator connection to `max: 1` for exactly these two reasons; the read-replica
+        // client built above is `max: 1` and closed per invocation for the same reason.
+        try {
+          await queryDb.execute(sql.raw('SELECT pg_advisory_unlock_all()'));
+        } catch {
+          // connection already gone / mock connection — nothing to release
+        }
+        // The read-replica client is built per invocation and used once; closing it is both
+        // the leak fix and a second guarantee that no session state outlives the call.
+        if (adhocClient) {
+          try {
+            await adhocClient.end();
+          } catch {
+            // already closed
+          }
+        }
       }
     };
 
@@ -736,19 +947,16 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         return { error: 'db:authz:probe requires { setup, read } SQL strings' };
       }
       const { sql } = await import('drizzle-orm');
-      const PROBE_ROLLBACK = Symbol('authz_probe_rollback');
-      let rows: any[] = [];
+      let rows: any[];
       try {
-        await opsDb.transaction(async (tx: any) => {
+        // Every probe write is discarded — runRolledBack forces the rollback.
+        rows = await runRolledBack<any[]>(opsDb, async (tx: any) => {
           await tx.execute(sql.raw(setup));
           const result: any = await tx.execute(sql.raw(read));
-          rows = Array.isArray(result) ? result : result?.rows ?? [];
-          throw PROBE_ROLLBACK; // discard every probe write
+          return Array.isArray(result) ? result : result?.rows ?? [];
         });
       } catch (err: unknown) {
-        if (err !== PROBE_ROLLBACK) {
-          return { error: (err as any)?.message || String(err) };
-        }
+        return { error: (err as any)?.message || String(err) };
       }
       return { rows };
     };
@@ -824,6 +1032,12 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // real connectivity BEFORE the authenticator password is set — the ordering that
     // keeps a BYO-database app from sawing off its own ops plane (see provision.ts).
     actions['db:provision'] = async (payload, _ctx) => {
+      // FIRST, before any connection work: this payload's searchPath — and the declaredOwners /
+      // declaredObjects its type accepts — are computed by the CLI from the Models barrel, so a
+      // shape skew between that CLI and the one bundled here must refuse, not ride through.
+      const skew = await modelWireGate('db:provision', payload);
+      if (skew) return skew;
+
       const { sql } = await import('drizzle-orm');
       const { runProvision } = await import('./provision');
 
@@ -880,9 +1094,15 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // is safely in the secret store: credentials (db:provision) → secret write (CLI) → this. A hard
     // kill here strands nothing — the worst case is an un-converged owner db:reconcile refuses on.
     actions['db:converge-ownership'] = async (payload, _ctx) => {
+      // FIRST, before the master client is opened: declaredOwners/declaredObjects come straight
+      // from the CLI's read of the Models barrel, and this action REASSIGNS OWNERSHIP from them —
+      // a misread field here changes which role a SECURITY DEFINER object runs as.
+      const skew = await modelWireGate('db:converge-ownership', payload);
+      if (skew) return skew;
+
       const { sql } = await import('drizzle-orm');
       const { convergeOwnership } = await import('./provision');
-      const { getMasterDatabaseUrl } = await import('./db');
+      const { getAdoptMasterUrl } = await import('./db');
 
       const queryRows = async (statement: string): Promise<any[]> => {
         const res: any = await opsDb.execute(sql.raw(statement));
@@ -891,10 +1111,12 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         return [];
       };
 
-      // The MASTER connection (linked RDS master), when linked — ENACT routes to it the grants the
-      // operator cannot make, and ADOPT requires it outright. Absent on a BYO-database app: master
-      // stays null and ADOPT refuses with the fix SQL. Opened for this invoke, closed in the finally.
-      const masterUrl = getMasterDatabaseUrl();
+      // The MASTER connection ADOPT reassigns through: the linked SST Postgres master, else the
+      // ADMIN_DATABASE_URL operator secret (a brownfield/external-RDS app has no component but wires
+      // a master-capable admin — see getAdoptMasterUrl). ENACT also routes hard grants here. Null
+      // only when NEITHER exists; then ADOPT refuses. Whether the resolved connection can actually
+      // reassign is decided by ADOPT's live probe, not by which source won. Closed in the finally.
+      const masterUrl = getAdoptMasterUrl();
       let masterClient: any = null;
       let master: { execute: (s: string) => Promise<unknown>; query: (s: string) => Promise<any[]> } | null = null;
       if (masterUrl) {
@@ -1032,8 +1254,11 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
            *  later descent ignores this row's git_ref. */
           dirty?: boolean;
           descentVerdict?: { ok: boolean; reason?: string };
-          /** When the CLI honoured a --attest-lineage-lost waiver, the note to record in the
-           *  schema_log outcome — the durable audit of the deliberate descent waiver. */
+          /** What the CLI's descent step decided, to record in the schema_log outcome
+           *  (`applied — <note>`): a honoured --attest-lineage-lost waiver, or a PROVEN DRIFT
+           *  origin (`descent: drift-origin proven (never-declared | hand-edited since … | applied
+           *  from a DIRTY worktree at …)`) — the
+           *  record that makes this row the origin every later apply descends from. */
           descentAttested?: string;
           authorityVerdict?: { ok: boolean; reason?: string };
           stage?: string;
@@ -1094,7 +1319,8 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           gitRef: gitRef ?? null,
           dirty: dirty === true,
           checkDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }),
-          // A honoured --attest-lineage-lost waiver is recorded in the schema_log outcome.
+          // The CLI's descent record (a honoured waiver, or a proven-drift origin) lands in the
+          // schema_log outcome; the witness query matches `applied%`, so the row stays a witness.
           ...(descentAttested ? { descentNote: () => descentAttested } : {}),
           ...(destructive && authorityVerdict
             ? { verifyAuthority: async () => (authorityVerdict.ok ? { ok: true as const } : { ok: false as const, reason: authorityVerdict.reason ?? 'authority refused' }) }
@@ -1142,18 +1368,16 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // barrel), and this introspects → plans → applies, emitting its own SET search_path. The DDL
     // batch and its provenance/schema_log land in one transaction, same as the direct path.
     actions['db:reconcile'] = async (payload, _ctx) => {
-      const p = (payload ?? {}) as {
-        declared?: any[];
-        renamedTables?: any;
-        apply?: boolean;
-        baseline?: boolean;
-        rebaseline?: boolean;
-        rebuild?: boolean;
-        overwriteDrift?: boolean;
-        only?: string[];
-        actor?: string | null;
-        gitRef?: string | null;
-      };
+      // FIRST, before the catalog introspection: `declared` is the derived layer compiled by the
+      // CLI from the Models barrel, and this action CREATES AND REPLACES database objects from it.
+      // It used to be `any[]` on the wire — no shape, no version, nothing to disagree about.
+      const skew = await modelWireGate('db:reconcile', payload);
+      if (skew) return skew;
+
+      // ReconcileWirePayload is the SHARED declaration (@everystack/model/wire, re-exported by
+      // @everystack/cli/wire) — the same type the CLI builds this payload against, so the two
+      // sides no longer agree by convention alone.
+      const p = (payload ?? {}) as ReconcileWirePayload;
       try {
         const { executeReconcile } = await import('@everystack/cli/reconcile');
         const { sql } = await import('drizzle-orm');
@@ -1161,6 +1385,10 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           const result: any = await opsDb.execute(sql.raw(query));
           return Array.isArray(result) ? result : result?.rows ?? [];
         };
+        // No `as any` on this call any more: `p.declared` is DerivedDescriptor[], which IS the
+        // CLI's SourceObject[] (one declaration, in @everystack/model/wire), so the reconcile
+        // core's options type accepts it directly. The cast used to hide exactly the kind of
+        // mismatch this whole contract exists to catch.
         const run = await executeReconcile(runner, sessionOverOpsDb(sql), {
           declared: p.declared,
           renamedTables: p.renamedTables,
@@ -1172,7 +1400,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           only: p.only,
           actor: p.actor ?? null,
           gitRef: p.gitRef ?? null,
-        } as any);
+        });
         return { plan: run.plan, applied: run.applied, statements: run.statements, refusal: run.refusal ?? null };
       } catch (err: any) {
         return { error: err?.message || String(err) };
@@ -1301,6 +1529,13 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // DATA-changed matview refresh had no credential-free path. This runs the refresh HERE on
     // the operator connection: the CLI ships the declared matview identities in dependency order,
     // this REFRESHes each. A least-privileged operator never holds a URL for the routine refresh.
+    // NOT guarded by MODEL_WIRE_CONTRACT, deliberately. The payload is a flat list of
+    // `schema.name` identity strings plus one boolean — there is no descriptor here, so there is
+    // no field that could be renamed or reinterpreted between two CLI versions, and a name this
+    // database does not have fails loudly as a REFRESH against a missing relation. Contrast
+    // db:reconcile's `declared[]`, whose seventeen fields decide whether an object is rebuilt and
+    // under whose ownership. IF this payload ever grows a descriptor shape, it joins the guarded
+    // set — add the modelWireGate call here and bump MODEL_WIRE_CONTRACT.
     actions['db:refresh'] = async (payload, _ctx) => {
       const p = (payload ?? {}) as { matviews?: string[]; verifyNonempty?: boolean };
       try {
@@ -1392,9 +1627,6 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
             ...options.consoleAuth,
           });
 
-          // Sentinel for sandbox rollback
-          const SANDBOX_ROLLBACK = Symbol('sandbox_rollback');
-
           async function evalExpression(db: any) {
             const models = createModels(db, ctx.schema);
             const evalContext: Record<string, unknown> = {
@@ -1438,15 +1670,10 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
             }
 
             if (sandbox) {
-              try {
-                await opsDb.transaction(async (tx: any) => {
-                  await applySettings(tx);
-                  result = await evalExpression(tx);
-                  throw SANDBOX_ROLLBACK;
-                });
-              } catch (err: unknown) {
-                if (err !== SANDBOX_ROLLBACK) throw err;
-              }
+              result = await runRolledBack(opsDb, async (tx: any) => {
+                await applySettings(tx);
+                return evalExpression(tx);
+              });
             } else {
               result = await opsDb.transaction(async (tx: any) => {
                 await applySettings(tx);
@@ -1454,14 +1681,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
               });
             }
           } else if (sandbox) {
-            try {
-              await opsDb.transaction(async (tx: any) => {
-                result = await evalExpression(tx);
-                throw SANDBOX_ROLLBACK;
-              });
-            } catch (err: unknown) {
-              if (err !== SANDBOX_ROLLBACK) throw err;
-            }
+            result = await runRolledBack(opsDb, (tx: any) => evalExpression(tx));
           } else {
             result = await evalExpression(opsDb);
           }