@rindle/api-server 0.6.3 → 0.7.0

package/src/index.ts

@@ -16,13 +16,21 @@ import type {
   ServerWriteTx,
 } from "@rindle/client";
 import { DaemonHttpError } from "@rindle/daemon-client";
+import { createSqlClient, encodeSqlValue, RindleSqlError } from "@rindle/sql-client";
+import type {
+  ClientOptions as SqlClientOptions,
+  MutationReceipt as SqlMutationReceipt,
+  MutationRows as SqlMutationRows,
+  SqlClient,
+  SqlMutationTransaction,
+  SqlSession,
+  Statement as PublicSqlStatement,
+} from "@rindle/sql-client";
 import { compile as compileQueryAst } from "@rindle/query-compiler";
 import type { Catalog, ColumnType as QueryColumnType, TableSchema } from "@rindle/query-compiler";
 import type {
   ClaimRoomEpochInput,
   ClaimRoomEpochOutput,
-  CoverQueryInput,
-  CoverQueryOutput,
   DematerializeInput,
   DematerializeOutput,
   MaterializationPolicy,
@@ -155,10 +163,24 @@ export interface MutationContext<User> {
   request?: unknown;
 }
 
-/** The legacy raw-SQL escape hatch (still the surface for relational/authority statements a keyed op
- *  can't express — an owner-gated cascade, a `NOT EXISTS` dedup). `exec` accumulates on the daemon
- *  backend and executes live on the Postgres backend; `statements` is the collected raw list. */
+/** A deliberately narrow raw-SQL facade exposed by the API server. On {@link ServerMutationTx}
+ *  it is bound to the open mutation transaction; on {@link MutationScope} each call runs in its
+ *  own transaction outside the mutation boundary. Column aliases should be unique: positional
+ *  driver rows are keyed by column name, so a duplicate alias is represented by its last value. */
+export interface ServerSql {
+  /** Queue/execute one statement. A transaction-bound call commits with the surrounding mutation. */
+  execute(sql: string, params?: readonly WireValue[]): Promise<void>;
+  /** Queue/execute an ordered statement batch. An empty batch is a no-op. */
+  batch(statements: readonly SqlStatement[]): Promise<void>;
+  /** Run a read and return rows keyed by their column names. */
+  query<Row = Record<string, unknown>>(sql: string, params?: readonly WireValue[]): Promise<Row[]>;
+}
+
+/** The raw-SQL escape hatch for relational/authority statements a keyed op can't express — an
+ *  owner-gated cascade, a `NOT EXISTS` dedup. Prefer `tx.sql`; `exec` remains the synchronous
+ *  compatibility shorthand for a queued `tx.sql.execute`, and `statements` is the raw write list. */
 export interface SqlMutationTx {
+  readonly sql: ServerSql;
   exec(sql: string, params?: WireValue[]): void;
   readonly statements: readonly SqlStatement[];
 }
@@ -166,17 +188,17 @@ export interface SqlMutationTx {
 /** The write handle a server mutator runs against — the ASYNC twin of the client's `MutationTx`. It
  *  is both the isomorphic {@link ServerWriteTx} logical surface (insert/update/upsert/insertIgnore/
  *  delete/row, rendered to dialect SQL) AND the legacy {@link SqlMutationTx} raw escape hatch. Both
- *  backends run reads through the OPEN transaction (read-your-writes): the Postgres backend executes
- *  everything live; the daemon backend accumulates writes and lazily upgrades to an interactive
- *  mutation session at the first read (DAEMON-INTERACTIVE-TXN-DESIGN.md §5). */
+ *  implementations run reads through the OPEN transaction (read-your-writes): Postgres executes
+ *  everything live; the SQL-client and daemon adapters accumulate writes and lazily upgrade to an
+ *  interactive mutation session at the first read (DAEMON-INTERACTIVE-TXN-DESIGN.md §5). */
 export interface ServerMutationTx extends ServerWriteTx, SqlMutationTx {
   /** Run a full query (a fluent `Query` or its wire `Ast`) INSIDE the open transaction —
    *  read-your-writes, like {@link ServerWriteTx.row} but for arbitrary shapes. Returns the
    *  parsed nested result tree: an array for a plural root, an object or `null` for a `.one()`
    *  root, with cells in their raw SQLite storage-class representations (the same vocabulary
-   *  `row` speaks). Daemon backend: compiled by `@rindle/query-compiler`'s sqlite dialect (bind
-   *  params, NO casts — §5.4) and executed through the mutation session. Postgres backend: lands
-   *  with the read-compiler catalog integration (POSTGRES-READ-COMPILER-DESIGN.md Phase B). */
+   *  `row` speaks). Remote SQLite backends: compiled by `@rindle/query-compiler`'s sqlite dialect
+   *  (bind params, NO casts — §5.4) and executed through the mutation session. Postgres: lands with
+   *  the read-compiler catalog integration (POSTGRES-READ-COMPILER-DESIGN.md Phase B). */
   query(q: Ast | Query<any, any, any>): Promise<unknown>;
 }
 
@@ -223,6 +245,10 @@ export class MutationRejected extends Error {
  *  `transact`, or a swallowed {@link MutationRejected} still advances `lmid` and never wedges the
  *  client's pending queue. */
 export interface MutationScope {
+  /** Raw SQL OUTSIDE the mutation transaction. Every call commits independently and therefore may
+   *  be observed even if {@link transact} later rejects or fails. Calls may also repeat when an
+   *  envelope is retried, so outside writes need their own idempotency key/unique constraint. */
+  readonly sql: ServerSql;
   /** Open the ONE atomic write transaction and drive `body` inside it, committing (stamping `lmid`
    *  co-transactionally) on a clean return. MAY be called at most once — a second call throws.
    *
@@ -308,10 +334,9 @@ export interface QueryLeaseRequest<User> {
 
 /**
  * The room-serve block on a query lease (RINDLE-REALTIME-QUERY-ENABLEMENT §2.1 step 5 / §2.4,
- * slice G-iv-b): present only when the named query carries a realtime label AND its resolved AST
- * was PROVABLY covered by its room profile's footprint (the daemon's `/cover-check`). The G-v
- * client uses it to open the room transport for THIS query beside — never instead of — its daemon
- * session.
+ * slice G-iv-b): present when the named query carries a realtime label naming a configured room
+ * profile (302 §5 — declared, not derived; no coverage proof). The G-v client uses it to open the
+ * room transport for THIS query beside — never instead of — its daemon session.
  *
  * It is a dedicated block on purpose: the ROOM ws is a SEPARATE connection this query opens beside
  * its daemon session (never a migration of the daemon session — the daemon ws host is fixed and
@@ -453,10 +478,10 @@ export type MutationOutcome =
 
 /**
  * Where a mutation runs and who stamps `lmid` — the seam that makes the mutator authoring surface
- * backend-agnostic (`BYO-POSTGRES-LMID-CONTRACT-DESIGN.md` §6; MUTATORS-ISOMORPHIC plan). Two impls
- * ship: {@link daemonBackend} (the default — writes accumulate, one batch to the daemon which stamps
- * `lmid` co-transactionally) and {@link postgresBackend} (a REAL interactive PG transaction — writes
- * and reads execute live, `lmid` committed in the same txn, confirmation riding the CDC loop down).
+ * backend-agnostic (`BYO-POSTGRES-LMID-CONTRACT-DESIGN.md` §6; MUTATORS-ISOMORPHIC plan). Three
+ * implementations ship: {@link sqlBackend} is the preferred managed-SQL path; {@link daemonBackend}
+ * keeps the private control-plane compatibility path; and {@link postgresBackend} runs a real
+ * interactive PG transaction with confirmation riding the CDC loop down.
  *
  * The load-bearing invariant is that a mutation ALWAYS advances the client's `last_mutation_id`:
  * - `runMutation` runs the mutator inside the backend's transaction; on success it advances `lmid`
@@ -470,6 +495,9 @@ export type MutationOutcome =
 export interface MutationBackend {
   /** The SQL dialect this backend renders logical ops to (drives placeholder style). */
   readonly dialect: SqlDialect;
+  /** Optional raw-SQL surface outside the mutation transaction. Built-in backends provide it;
+   *  custom backends may omit it, in which case `scope.sql` fails as an infrastructure error. */
+  readonly outsideSql?: ServerSql;
   runMutation(input: MutationRunInput): Promise<MutationOutcome>;
   reject(input: { envelope: MutationEnvelope; reason: string }): Promise<unknown>;
 }
@@ -771,11 +799,30 @@ export async function verifyRoomFlushCredential(
   return payload;
 }
 
+/** Database connection used by the API server's managed SQL path.
+ *
+ *  `intMode` defaults to `"number"` because logical Rindle rows use the JSON-safe {@link WireValue}
+ *  vocabulary — `"bigint"` does not survive `JSON.stringify`, and `"string"` silently retypes every
+ *  integer, breaking arithmetic in mutator bodies. The cost is a HARD BOUND: a mutator read of an
+ *  integer outside ±(2^53 − 1) rejects that mutation rather than silently rounding it. Tables with
+ *  keys beyond that range (snowflake ids, and so on) must override `intMode` and have their mutators
+ *  handle the resulting type. Commit receipts are unaffected — they never decode row values. */
+export type RindleDatabaseOptions = Pick<SqlClientOptions, "url" | "authToken" | "fetch" | "intMode">;
+
 export interface RindleApiServerOptions<User> {
   daemon: RindleDaemonClient;
+  /** Preferred managed setup. The API server constructs and owns its SQL client; authoritative
+   *  mutators, `tx.sql`, and `scope.sql` use it, while `daemon` remains only the lease/query/
+   *  materialization/room control plane. Mutually exclusive with {@link sql} unless `backend`
+   *  explicitly replaces both. */
+  database?: RindleDatabaseOptions;
+  /** Advanced injection/test seam for an already-created SQL session. Most applications should
+   *  configure {@link database} and never import `createSqlClient`. When present (and `backend` is
+   *  absent), authoritative mutators run through {@link sqlBackend}. */
+  sql?: SqlSession;
   /** Where mutations are applied and `lmid` is stamped ({@link MutationBackend}). Default:
-   *  `daemonBackend(daemon)` — exactly today's behavior. Pass `postgresBackend(...)` when
-   *  Postgres is the source of truth (the daemon leg then serves only the read side). */
+   *  managed `sqlBackend` when `database` or `sql` is configured, otherwise the compatibility
+   *  `daemonBackend(daemon)`. Pass `postgresBackend(...)` when Postgres is the source of truth. */
   backend?: MutationBackend;
   /** The typed schema (`createSchema`/`refineSchema`). Required only when a mutator uses the LOGICAL
    *  write vocabulary (`tx.insert`/`update`/`upsert`/`insertIgnore`/`delete`/`row`) — it drives the
@@ -845,24 +892,15 @@ export interface RindleApiServerOptions<User> {
 
 export interface RindleApiServer<User> {
   readonly routes: RindleApiRoutes;
+  /** Close the SQL client created from {@link RindleApiServerOptions.database}. Injected SQL
+   *  sessions and custom backends remain caller-owned. Idempotent. */
+  close(): void;
   createQueryLease(input: QueryLeaseRequest<User>): Promise<QueryLeaseResponse>;
   /** (Re-)materialize every `pinnedQueries` entry with a pinned policy. Idempotent — the daemon
    *  dedupes by canonical query, so a re-assert reuses the existing materialization. Call it at
    *  startup and whenever the daemon restarts (e.g. from the daemon-client `onBootId` hook), since
    *  the daemon holds no durable materialization state. No-op when `pinnedQueries` is empty. */
   assertPins(): Promise<void>;
-  /** The room-serving coverage DIAGNOSTIC (G-iv-b; the `assertPins`-style explicit check): for
-   *  every realtime-labeled query, resolve it (under `pinUser`, per exemplar args), resolve its
-   *  profile's footprint, and run the REAL daemon coverage check — the same verdict the lease
-   *  path serves by. Returns every verdict; `strict` throws when any labeled query is not
-   *  provably covered (deploy-gate mode). Deliberately ignores `locateRoom`/`roomTokenKey` — it
-   *  answers "would this query be coverable", not "is serving fully wired". */
-  validateRealtime(opts?: {
-    /** Per-query exemplar args (a query is checked once per exemplar; default: one `null`). */
-    exemplars?: Partial<Record<string, readonly unknown[]>>;
-    /** Throw when any labeled query is uncovered (instead of just reporting). */
-    strict?: boolean;
-  }): Promise<ValidateRealtimeReport>;
   pushMutation(input: PushMutationRequest<User>): Promise<PushMutationResponse>;
   /** Apply an in-order batch (the client mutation queue's flush). Envelopes run strictly
    *  sequentially; a rejection still advances the daemon's lmid, so later envelopes in the
@@ -901,24 +939,6 @@ export interface RindleApiServer<User> {
   handleRoomBootJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
 }
 
-/** One {@link RindleApiServer.validateRealtime} verdict: a labeled query × exemplar args. */
-export interface ValidateRealtimeVerdict {
-  query: string;
-  profile: string;
-  args: unknown;
-  covered: boolean;
-  /** Why it is not covered (uncovered verdicts only) — the daemon's reason strings, the
-   *  aggregate refusal, or a resolve/footprint error message. */
-  reasons?: string[];
-}
-
-/** The {@link RindleApiServer.validateRealtime} report. */
-export interface ValidateRealtimeReport {
-  verdicts: ValidateRealtimeVerdict[];
-  /** The uncovered subset of `verdicts` (what `strict` throws on). */
-  uncovered: ValidateRealtimeVerdict[];
-}
-
 export type RindleApiErrorCode = "bad-request" | "forbidden" | "not-found" | "rejected";
 
 export class RindleApiError extends Error {
@@ -1013,13 +1033,6 @@ export class SplitDaemonClient implements RindleDaemonClient {
     if (!lmids) return Promise.reject(new Error("the write master lacks roomLmids"));
     return lmids(input);
   }
-  // Pure computation hosted by rindled: keep it on the read/follower leg. The write master owns
-  // room durability, not query-cover analysis.
-  coverQuery(input: CoverQueryInput): Promise<CoverQueryOutput> {
-    const cover = this.reads.coverQuery?.bind(this.reads);
-    if (!cover) return Promise.reject(new Error("the read follower lacks coverQuery"));
-    return cover(input);
-  }
   migrate(input: MigrateInput): Promise<MigrateOutput> {
     return this.writes.migrate(input);
   }
@@ -1200,9 +1213,6 @@ export class BackendError extends Error {
   }
 }
 
-/** The rindle/daemon server tx: logical writes render to SQLite and ACCUMULATE into one batch;
- *  raw `exec` accumulates too; `row` reads COMMITTED state through the daemon (no read-your-writes,
- *  the one interactive-txn limitation of the daemon backend). */
 /** Build the compiler {@link Catalog} for ONE ast from the render index: columns/pk from the
  *  schema; relationship cardinality from the AST ITSELF — a Rindle relationship is declared at
  *  the query site (`sub(alias, rel)` / `.one()`), never on the schema, so the alias→cardinality
@@ -1256,6 +1266,9 @@ class AbsorbedReplay extends Error {
 const MUTATOR_CONFLICT_MAX_ATTEMPTS = 5;
 
 function isRetryableCommitConflict(error: unknown): boolean {
+  if (error instanceof RindleSqlError) {
+    return error.status === 409 && (error.code === "retryable-conflict" || error.code === "TRANSACTION_CONFLICT");
+  }
   if (!(error instanceof DaemonHttpError) || error.status !== 409) return false;
   try {
     const body = JSON.parse(error.body) as { code?: unknown; retryable?: unknown };
@@ -1271,10 +1284,296 @@ async function mutatorConflictBackoff(attempt: number): Promise<void> {
   await new Promise<void>((resolve) => setTimeout(resolve, millis));
 }
 
+/** True when this error is the SQL codec refusing a bind value outright (`undefined`, `Date`, `NaN`,
+ *  a binary view, an out-of-i64 bigint) rather than a transport or database failure. */
+function isUnencodableBind(error: unknown): boolean {
+  return error instanceof RindleSqlError && error.code === "VALUE_UNSUPPORTED";
+}
+
+/** Refuse an unencodable bind at the point the MUTATOR supplies it, so it surfaces as a BUSINESS
+ *  rejection (lmid advances, the browser retires its prediction) instead of an infrastructure
+ *  failure. Left as infra it is retried forever against a deterministic mutator, which wedges the
+ *  client's mutation queue behind a poison message.
+ *
+ *  Only the SQL transport needs this: the legacy daemon encoder is JSON, which silently coerces the
+ *  same values (`undefined`/`NaN` -> null, `Date` -> an ISO string). Asserting there would invent a
+ *  failure that the wire does not actually have. */
+function assertEncodableParams(sql: string, params: readonly WireValue[] | undefined): void {
+  if (params === undefined) return;
+  for (let index = 0; index < params.length; index++) {
+    try {
+      encodeSqlValue(params[index] as Parameters<typeof encodeSqlValue>[0]);
+    } catch (error) {
+      if (!isUnencodableBind(error)) throw error;
+      throw new Error(`bind ${index} of \`${sql}\` cannot be stored: ${errMessage(error)}`);
+    }
+  }
+}
+
+/** Leading keywords the SQL mutation surface structurally REFUSES inside a mutator's write batch: a
+ *  read (`SELECT`/`EXPLAIN`), transaction control, a connection `PRAGMA`, or DDL. None can begin a
+ *  valid mutation write, so refusing them has no false positives — a `WITH`-prefixed statement is
+ *  deliberately absent because it may resolve to either a read or a write, and the server stays the
+ *  authority for that case. */
+const MUTATION_REFUSED_LEADING_KEYWORDS = new Set([
+  "SELECT", "EXPLAIN", "VALUES",
+  "BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "RELEASE", "END",
+  "PRAGMA", "VACUUM", "ATTACH", "DETACH",
+  "CREATE", "ALTER", "DROP", "REINDEX", "ANALYZE",
+]);
+
+/** Refuse a statement whose CLASS the mutation surface rejects, at the point the MUTATOR supplies it,
+ *  so it surfaces as a business rejection instead of a poison. When the batch reaches the transport
+ *  the body has already returned, so a server 400 there is (mis)read as infrastructure and retried
+ *  forever — the same wedge {@link assertEncodableParams} prevents for bind values. Conservative by
+ *  design: it fires only for a leading keyword that can never start a valid write, and leaves every
+ *  ambiguous case (including CTE-prefixed writes) to the server's authoritative classifier. */
+function assertMutationWriteStatement(sql: string): void {
+  const match = /^[\s;]*([a-zA-Z]+)/.exec(sql);
+  if (match === null) return;
+  const keyword = match[1]!.toUpperCase();
+  if (MUTATION_REFUSED_LEADING_KEYWORDS.has(keyword)) {
+    throw new Error(
+      `a mutator write statement cannot begin with ${keyword} (\`${sql}\`); ` +
+        `mutations write rows only — use tx.sql.query(...) for reads and migrations for DDL`,
+    );
+  }
+}
+
+interface MutationTransportBegin {
+  handle?: unknown;
+  absorbed?: SqlTxnOutput;
+  read?: SqlReadOutput;
+}
+
+/** The mutation-only transport consumed by the API-server transaction harness. Both the legacy
+ *  daemon client and `@rindle/sql-client` adapt to this one shape, so lmid/rejection/lazy-session
+ *  policy is implemented once. */
+interface MutationTransport {
+  readonly interactive: boolean;
+  /** Whether this transport's wire REFUSES values the daemon's JSON encoder coerces. Drives
+   *  {@link assertEncodableParams} — see its docs for why the daemon adapter opts out. */
+  readonly strictValues: boolean;
+  execute(input: {
+    envelope: MutationEnvelope;
+    statements: SqlStatement[];
+    idempotencyKey?: string;
+  }): Promise<SqlTxnOutput>;
+  reject(input: { envelope: MutationEnvelope; reason: string }): Promise<unknown>;
+  begin(input: {
+    envelope: MutationEnvelope;
+    statements: SqlStatement[];
+    query: SqlStatement;
+    idempotencyKey?: string;
+  }): Promise<MutationTransportBegin>;
+  exec(handle: unknown, statements: SqlStatement[]): Promise<void>;
+  query(handle: unknown, statement: SqlStatement): Promise<SqlReadOutput>;
+  commit(handle: unknown): Promise<SqlTxnOutput>;
+  rollback(handle: unknown): Promise<void>;
+  readCommitted(statement: SqlStatement): Promise<SqlReadOutput>;
+}
+
+function daemonMutationTransport(daemon: RindleDaemonClient): MutationTransport {
+  return {
+    interactive: daemon.beginMutationSession !== undefined,
+    strictValues: false,
+    execute({ envelope, statements, idempotencyKey }) {
+      const txn: SqlTxn = { statements, clientID: envelope.clientID, mid: envelope.mid };
+      if (idempotencyKey !== undefined) txn.idempotencyKey = idempotencyKey;
+      return daemon.executeSqlTxn(txn);
+    },
+    reject({ envelope, reason }) {
+      return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+    },
+    async begin({ envelope, statements, query, idempotencyKey }) {
+      if (!daemon.beginMutationSession) throw new Error("the daemon client does not support mutation sessions");
+      const input: MutationSessionBegin = {
+        clientID: envelope.clientID,
+        mid: envelope.mid,
+        statements,
+        query,
+      };
+      if (idempotencyKey !== undefined) input.idempotencyKey = idempotencyKey;
+      const opened = await daemon.beginMutationSession(input);
+      if (opened.absorbed) {
+        const { absorbed: _absorbed, sessionId: _sessionId, read: _read, ...output } = opened;
+        return { absorbed: output as SqlTxnOutput };
+      }
+      return { handle: opened.sessionId, read: opened.read };
+    },
+    async exec(handle, statements) {
+      await daemon.execInMutationSession!({ sessionId: handle as string, statements });
+    },
+    query(handle, statement) {
+      return daemon.queryInMutationSession!({
+        sessionId: handle as string,
+        sql: statement.sql,
+        params: statement.params,
+      });
+    },
+    commit(handle) {
+      return daemon.commitMutationSession!({ sessionId: handle as string });
+    },
+    async rollback(handle) {
+      await daemon.rollbackMutationSession!({ sessionId: handle as string });
+    },
+    readCommitted(statement) {
+      return daemon.executeSqlRead({ sql: statement.sql, params: statement.params });
+    },
+  };
+}
+
+function mutationReceiptOutput(receipt: SqlMutationReceipt, clientID: string): SqlTxnOutput {
+  const output: SqlTxnOutput = {
+    applied: receipt.applied,
+    lmid: receipt.lmid,
+    lmidAdvances: [{ clientID, lmid: receipt.lmid }],
+  };
+  if (receipt.commitCursor !== null) output.cursor = receipt.commitCursor;
+  return output;
+}
+
+function publicMutationStatement(statement: SqlStatement): PublicSqlStatement {
+  return statement.params === undefined ? { sql: statement.sql } : { sql: statement.sql, args: statement.params };
+}
+
+function mutationRowsOutput(rows: SqlMutationRows): SqlReadOutput {
+  return { cols: rows.columns, rows: rows.rows as WireValue[][] };
+}
+
+/** Convert the transports' compact positional rows into the ergonomic server-only raw-SQL shape. */
+function keyedSqlRows<Row = Record<string, unknown>>(
+  columns: readonly string[],
+  rows: readonly (readonly unknown[])[],
+): Row[] {
+  // Row objects are keyed by column NAME, so a read that projects the same name twice
+  // (`SELECT parent.status, child.status ...`) would silently keep only the last value — and a
+  // mutator branching on `row.status` would then authorize against the wrong cell. Refuse it loudly
+  // so the collision surfaces as a rejection reason instead of silent, wrong data.
+  const seen = new Set<string>();
+  for (const column of columns) {
+    if (seen.has(column)) {
+      throw new Error(
+        `raw SQL read projects the column name ${JSON.stringify(column)} more than once; ` +
+          `alias them to distinct names (e.g. SELECT a.id AS a_id, b.id AS b_id)`,
+      );
+    }
+    seen.add(column);
+  }
+  return rows.map((cells) => Object.fromEntries(columns.map((column, index) => [column, cells[index]])) as Row);
+}
+
+function daemonOutsideSql(daemon: RindleDaemonClient): ServerSql {
+  return {
+    async execute(sql, params = []) {
+      await daemon.executeSqlTxn({ statements: [{ sql, params: [...params] }] });
+    },
+    async batch(statements) {
+      if (statements.length === 0) return;
+      await daemon.executeSqlTxn({
+        statements: statements.map((statement) => ({
+          sql: statement.sql,
+          ...(statement.params !== undefined ? { params: [...statement.params] } : {}),
+        })),
+      });
+    },
+    async query<Row = Record<string, unknown>>(sql: string, params: readonly WireValue[] = []): Promise<Row[]> {
+      const out = await daemon.executeSqlRead({ sql, params: [...params], consistency: "strong" });
+      return keyedSqlRows<Row>(out.cols, out.rows);
+    },
+  };
+}
+
+function sqlSessionOutsideSql(sql: SqlSession): ServerSql {
+  return {
+    async execute(text, params = []) {
+      await sql.execute({ sql: text, args: [...params] });
+    },
+    async batch(statements) {
+      if (statements.length === 0) return;
+      await sql.batch(statements.map(publicMutationStatement));
+    },
+    async query<Row = Record<string, unknown>>(text: string, params: readonly WireValue[] = []): Promise<Row[]> {
+      const out = await sql.execute({ sql: text, args: [...params], wantRows: true }, { consistency: "strong" });
+      return keyedSqlRows<Row>(
+        out.result.columns.map((column) => column.name),
+        out.result.rows,
+      );
+    },
+  };
+}
+
+function sqlClientMutationTransport(sql: SqlSession): MutationTransport {
+  return {
+    interactive: true,
+    strictValues: true,
+    // NOTE: `execute`/`begin` deliberately ignore the interface's optional `idempotencyKey`. On the
+    // SQL mutation wire the (clientID, mid) pair IS the durable retry identity — a redelivery is
+    // absorbed by mid, so there is no idempotency key to carry. The field stays on the shared
+    // MutationTransport only because the legacy daemon foreign-write path still threads it.
+    async execute({ envelope, statements }) {
+      const receipt = await sql.executeMutation({
+        clientId: envelope.clientID,
+        mid: envelope.mid,
+        statements: statements.map(publicMutationStatement),
+      });
+      return mutationReceiptOutput(receipt, envelope.clientID);
+    },
+    async reject({ envelope, reason }) {
+      return mutationReceiptOutput(
+        await sql.rejectMutation({ clientId: envelope.clientID, mid: envelope.mid, reason }),
+        envelope.clientID,
+      );
+    },
+    async begin({ envelope, statements, query }) {
+      const opened = await sql.beginMutation({
+        clientId: envelope.clientID,
+        mid: envelope.mid,
+        statements: statements.map(publicMutationStatement),
+        query: publicMutationStatement(query),
+      });
+      if (opened.absorbed) {
+        return { absorbed: mutationReceiptOutput(opened.receipt, envelope.clientID) };
+      }
+      return {
+        handle: opened.transaction,
+        ...(opened.read !== undefined ? { read: mutationRowsOutput(opened.read) } : {}),
+      };
+    },
+    async exec(handle, statements) {
+      await (handle as SqlMutationTransaction).batch(statements.map(publicMutationStatement));
+    },
+    async query(handle, statement) {
+      return mutationRowsOutput(await (handle as SqlMutationTransaction).query(publicMutationStatement(statement)));
+    },
+    async commit(handle) {
+      const receipt = await (handle as SqlMutationTransaction).commit();
+      const advance = receipt.lmid;
+      // The handle is opened for exactly one client; RemoteLazyTx patches the client id from its
+      // envelope after this call so the legacy MutationBackend receipt remains byte-compatible.
+      return {
+        applied: receipt.applied,
+        cursor: receipt.commitCursor ?? undefined,
+        lmid: advance,
+      };
+    },
+    async rollback(handle) {
+      await (handle as SqlMutationTransaction).rollback();
+    },
+    async readCommitted(statement) {
+      const result = await sql.execute(publicMutationStatement(statement), { consistency: "strong" });
+      return {
+        cols: result.result.columns.map((column) => column.name),
+        rows: result.result.rows as WireValue[][],
+      };
+    },
+  };
+}
+
 /**
- * The daemon server tx (DAEMON-INTERACTIVE-TXN-DESIGN.md §5): ONE authoring surface, two
+ * The remote SQLite server tx (DAEMON-INTERACTIVE-TXN-DESIGN.md §5): ONE authoring surface, two
  * execution strategies. It starts ACCUMULATING — a pure-write mutator ships one batch to
- * `/execute-sql-txn`, byte-identical to prior behavior — and LAZILY UPGRADES to an interactive
+ * the selected mutation transport — and LAZILY UPGRADES to an interactive
  * mutation session at the mutator's first read: `begin` carries the envelope identity, the
  * accumulated statement prefix (sound to replay — nothing before the first read observed DB
  * state, §5.2), and the read itself, so a one-read mutator pays exactly one extra round trip.
@@ -1283,31 +1582,44 @@ async function mutatorConflictBackoff(attempt: number): Promise<void> {
  * reads cost k+2 round trips regardless of write count.
  *
  * Begin-time mid dedup can ABSORB the envelope (a redelivery whose commit response was lost):
- * the replay output is latched on {@link DaemonLazyTx.absorbed} and {@link AbsorbedReplay}
+ * the replay output is latched on {@link RemoteLazyTx.absorbed} and {@link AbsorbedReplay}
  * unwinds the body — the latch (not the throw) is authoritative, so a mutator that swallows
  * the unwind still cannot re-apply (no session opened; buffered writes are never shipped).
  * A daemon client without session support keeps the LEGACY committed-state point read.
  */
-class DaemonLazyTx implements ServerMutationTx {
+class RemoteLazyTx implements ServerMutationTx {
   /** Pre-upgrade: the accumulated batch/prefix. Post-upgrade: writes buffered for the next flush. */
   private readonly stmts: SqlStatement[] = [];
   private readonly render: RenderIndex;
-  private readonly daemon: RindleDaemonClient;
+  private readonly transport: MutationTransport;
   private readonly envelope: MutationEnvelope;
-  private sessionId?: string;
+  private sessionHandle?: unknown;
+  readonly sql: ServerSql;
   /** The begin-absorbed replay output (§4.1), latched for the backend. */
   absorbed?: SqlTxnOutput;
   idempotencyKey?: string;
 
-  constructor(render: RenderIndex, daemon: RindleDaemonClient, envelope: MutationEnvelope) {
+  constructor(render: RenderIndex, transport: MutationTransport, envelope: MutationEnvelope) {
     this.render = render;
-    this.daemon = daemon;
+    this.transport = transport;
     this.envelope = envelope;
+    this.sql = {
+      execute: async (sql, params = []) => {
+        this.exec(sql, [...params]);
+      },
+      batch: async (statements) => {
+        for (const statement of statements) {
+          this.exec(statement.sql, statement.params === undefined ? [] : [...statement.params]);
+        }
+      },
+      query: <Row = Record<string, unknown>>(sql: string, params: readonly WireValue[] = []) =>
+        this.querySql<Row>(sql, params),
+    };
   }
 
   /** True once the tx upgraded to an interactive session (the backend then commits it). */
   get session(): boolean {
-    return this.sessionId !== undefined;
+    return this.sessionHandle !== undefined;
   }
 
   get statements(): readonly SqlStatement[] {
@@ -1315,12 +1627,21 @@ class DaemonLazyTx implements ServerMutationTx {
   }
 
   exec(sql: string, params: WireValue[] = []): void {
+    // Refuse here, INSIDE the mutator body, so the harness reads it as a business rejection. By the
+    // time the statement reaches the transport the body has returned and the throw is infra.
+    if (this.transport.strictValues) {
+      assertMutationWriteStatement(sql);
+      assertEncodableParams(sql, params);
+    }
     this.stmts.push({ sql, params });
   }
 
   private push(op: MutationOp): Promise<void> {
     const rendered = renderOp(op, tableMeta(this.render, op.table), sqliteDialect);
-    if (rendered) this.stmts.push(rendered);
+    if (rendered) {
+      if (this.transport.strictValues) assertEncodableParams(rendered.sql, rendered.params);
+      this.stmts.push(rendered);
+    }
     return Promise.resolve();
   }
 
@@ -1362,42 +1683,47 @@ class DaemonLazyTx implements ServerMutationTx {
     return JSON.parse(cell) as unknown;
   }
 
+  private async querySql<Row>(sql: string, params: readonly WireValue[]): Promise<Row[]> {
+    const out = await this.readThroughTxn({ sql, params: [...params] });
+    return keyedSqlRows<Row>(out.cols, out.rows);
+  }
+
   /** Run one read: upgrade to a session at the first (§5.1), ride the open one after, or fall
    *  back to the legacy committed-state read when the daemon client lacks sessions. */
   private async readThroughTxn(read: SqlStatement): Promise<SqlReadOutput> {
     if (this.absorbed) throw new AbsorbedReplay();
-    if (!this.daemon.beginMutationSession) {
+    // Refuse an unencodable read bind at the mutator boundary, exactly as `exec` does for writes.
+    // A read's parameters are encoded inside the transport, where the throw becomes a BackendError
+    // (infra) that retries the deterministic mutator forever and wedges the client's queue; asserting
+    // here makes it a business rejection instead.
+    if (this.transport.strictValues) assertEncodableParams(read.sql, read.params);
+    if (!this.transport.interactive) {
       try {
-        return await this.daemon.executeSqlRead({ sql: read.sql, params: read.params });
+        return await this.transport.readCommitted(read);
       } catch (err) {
         throw new BackendError(err);
       }
     }
     try {
-      if (this.sessionId === undefined) {
-        const opened = await this.daemon.beginMutationSession({
-          clientID: this.envelope.clientID,
-          mid: this.envelope.mid,
+      if (this.sessionHandle === undefined) {
+        const opened = await this.transport.begin({
+          envelope: this.envelope,
           statements: this.stmts.splice(0),
           query: read,
+          ...(this.idempotencyKey !== undefined ? { idempotencyKey: this.idempotencyKey } : {}),
         });
         if (opened.absorbed) {
-          const { absorbed: _a, sessionId: _s, read: _r, ...output } = opened;
-          this.absorbed = output as SqlTxnOutput;
+          this.absorbed = opened.absorbed;
           throw new AbsorbedReplay();
         }
-        if (!opened.sessionId || !opened.read) {
+        if (opened.handle === undefined || !opened.read) {
           throw new Error(`malformed mutate-session begin reply: ${JSON.stringify(opened)}`);
         }
-        this.sessionId = opened.sessionId;
+        this.sessionHandle = opened.handle;
         return opened.read;
       }
       await this.flush();
-      return await this.daemon.queryInMutationSession!({
-        sessionId: this.sessionId,
-        sql: read.sql,
-        params: read.params,
-      });
+      return await this.transport.query(this.sessionHandle, read);
     } catch (err) {
       if (err instanceof AbsorbedReplay || err instanceof BackendError) throw err;
       throw new BackendError(err);
@@ -1407,10 +1733,7 @@ class DaemonLazyTx implements ServerMutationTx {
   /** Ship buffered writes into the open session, order-preserving; a no-op when none pend. */
   private async flush(): Promise<void> {
     if (this.stmts.length === 0) return;
-    await this.daemon.execInMutationSession!({
-      sessionId: this.sessionId!,
-      statements: this.stmts.splice(0),
-    });
+    await this.transport.exec(this.sessionHandle!, this.stmts.splice(0));
   }
 
   /** Flush + commit the open session — the daemon stamps lmid co-transactionally (§4.4) and
@@ -1418,7 +1741,11 @@ class DaemonLazyTx implements ServerMutationTx {
   async commitSession(): Promise<SqlTxnOutput> {
     try {
       await this.flush();
-      return await this.daemon.commitMutationSession!({ sessionId: this.sessionId! });
+      const output = await this.transport.commit(this.sessionHandle!);
+      if (output.lmid !== undefined && output.lmidAdvances === undefined) {
+        output.lmidAdvances = [{ clientID: this.envelope.clientID, lmid: output.lmid }];
+      }
+      return output;
     } catch (err) {
       throw err instanceof BackendError ? err : new BackendError(err);
     }
@@ -1427,11 +1754,11 @@ class DaemonLazyTx implements ServerMutationTx {
   /** Best-effort rollback (the daemon's deadline is the backstop). MUST be awaited before a
    *  follow-up `/reject-mutation`: that lmid-only commit needs the writer this session holds. */
   async rollbackSessionQuietly(): Promise<void> {
-    if (this.sessionId === undefined) return;
-    const sessionId = this.sessionId;
-    this.sessionId = undefined;
+    if (this.sessionHandle === undefined) return;
+    const sessionHandle = this.sessionHandle;
+    this.sessionHandle = undefined;
     try {
-      await this.daemon.rollbackMutationSession!({ sessionId });
+      await this.transport.rollback(sessionHandle);
     } catch {
       // Unreachable daemon / already-expired session: the deadline rollback covers it.
     }
@@ -1448,12 +1775,27 @@ class PgLiveTx implements ServerMutationTx {
   private readonly q: PgQuery;
   private readonly render: RenderIndex;
   private readonly rewrite: (sql: string) => string;
+  readonly sql: ServerSql;
   idempotencyKey?: string;
 
   constructor(q: PgQuery, render: RenderIndex, rewrite: (sql: string) => string) {
     this.q = q;
     this.render = render;
     this.rewrite = rewrite;
+    this.sql = {
+      execute: async (sql, params = []) => {
+        this.exec(sql, [...params]);
+        await this.settle();
+      },
+      batch: async (statements) => {
+        for (const statement of statements) {
+          this.exec(statement.sql, statement.params === undefined ? [] : [...statement.params]);
+        }
+        await this.settle();
+      },
+      query: <Row = Record<string, unknown>>(sql: string, params: readonly WireValue[] = []) =>
+        this.querySql<Row>(sql, params),
+    };
   }
 
   get statements(): readonly SqlStatement[] {
@@ -1528,25 +1870,30 @@ class PgLiveTx implements ServerMutationTx {
       ),
     );
   }
+
+  private async querySql<Row>(sql: string, params: readonly WireValue[]): Promise<Row[]> {
+    await this.settle();
+    try {
+      return (await this.q.query(this.rewrite(sql), [...params])) as Row[];
+    } catch (err) {
+      throw new BackendError(err);
+    }
+  }
 }
 
-/**
- * The default {@link MutationBackend}. A pure-write mutator keeps the historical shape: writes
- * ACCUMULATE and ship as ONE batch to `/execute-sql-txn`, which stamps `lmid` co-transactionally
- * (and `/reject-mutation` advances it past a rejected mid) — byte-identical behavior. A
- * READ-bearing mutator lazily upgrades to an interactive mutation session
- * (DAEMON-INTERACTIVE-TXN-DESIGN.md): reads are read-your-writes through the open transaction
- * (PG parity), the commit stamps `lmid` in the same atomic unit, and a begin-absorbed replay
- * short-circuits without re-running the body.
- */
-export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
+/** Shared remote-SQL mutation backend. A pure-write mutator remains one request; a read-bearing
+ * mutator lazily upgrades at its first read; accepted effects commit with lmid; business rejection
+ * rolls effects back before an lmid-only commit. Both daemonBackend and sqlBackend use this exact
+ * policy implementation. */
+function remoteMutationBackend(transport: MutationTransport, outsideSql: ServerSql): MutationBackend {
   return {
     dialect: sqliteDialect,
+    outsideSql,
     async runMutation(input) {
       for (let attempt = 0; attempt < MUTATOR_CONFLICT_MAX_ATTEMPTS; attempt++) {
         try {
           const { envelope, render, run } = input;
-          const tx = new DaemonLazyTx(render, daemon, envelope);
+          const tx = new RemoteLazyTx(render, transport, envelope);
           try {
             await run(tx);
           } catch (err) {
@@ -1561,7 +1908,7 @@ export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
             // Data first, watermark second: rollback releases this session's connection before
             // the lmid-only rejection commit.
             await tx.rollbackSessionQuietly();
-            const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+            const output = await transport.reject({ envelope, reason });
             return { accepted: false, reason, output };
           }
           if (tx.absorbed) return { accepted: true, output: tx.absorbed };
@@ -1573,9 +1920,14 @@ export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
               throw err;
             }
           }
-          const txn: SqlTxn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
-          if (tx.idempotencyKey !== undefined) txn.idempotencyKey = tx.idempotencyKey;
-          return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+          return {
+            accepted: true,
+            output: await transport.execute({
+              envelope,
+              statements: [...tx.statements],
+              ...(tx.idempotencyKey !== undefined ? { idempotencyKey: tx.idempotencyKey } : {}),
+            }),
+          };
         } catch (error) {
           if (!isRetryableCommitConflict(error) || attempt + 1 === MUTATOR_CONFLICT_MAX_ATTEMPTS) {
             throw error;
@@ -1586,11 +1938,24 @@ export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
       throw new Error("unreachable mutator conflict retry loop");
     },
     reject({ envelope, reason }) {
-      return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+      return transport.reject({ envelope, reason });
     },
   };
 }
 
+/** Legacy/private-plane adapter. Kept for existing deployments; its mutation policy is shared with
+ * {@link sqlBackend}, so the two transports cannot drift. */
+export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
+  return remoteMutationBackend(daemonMutationTransport(daemon), daemonOutsideSql(daemon));
+}
+
+/** Run API-server mutators through `@rindle/sql-client`'s explicit mutation facade. Query leases,
+ * SSR reads and room control continue to use `daemon`; only authoritative mutation execution moves
+ * to the versioned SQL transport. */
+export function sqlBackend(sql: SqlSession): MutationBackend {
+  return remoteMutationBackend(sqlClientMutationTransport(sql), sqlSessionOutsideSql(sql));
+}
+
 /** The query surface a {@link PostgresPlugger} transaction exposes. `exec` runs one statement;
  *  `query` returns rows keyed by column name (read-your-own-writes inside the txn). */
 export interface PgQuery {
@@ -1641,8 +2006,27 @@ export function postgresBackend(plugger: PostgresPlugger, opts: PostgresBackendO
       await q.exec(LMID_UPSERT, [envelope.clientID, envelope.mid]);
       return { applied: true, lmidAdvances: [{ clientID: envelope.clientID, lmid: envelope.mid }] };
     });
+  const outsideSql: ServerSql = {
+    async execute(sql, params = []) {
+      await plugger.transaction(async (q) => {
+        await q.exec(rewrite(sql), [...params]);
+      });
+    },
+    async batch(statements) {
+      if (statements.length === 0) return;
+      await plugger.transaction(async (q) => {
+        for (const statement of statements) {
+          await q.exec(rewrite(statement.sql), statement.params === undefined ? [] : [...statement.params]);
+        }
+      });
+    },
+    query<Row = Record<string, unknown>>(sql: string, params: readonly WireValue[] = []): Promise<Row[]> {
+      return plugger.transaction(async (q) => (await q.query(rewrite(sql), [...params])) as Row[]);
+    },
+  };
   return {
     dialect: postgresDialect,
+    outsideSql,
     async runMutation({ envelope, render, run }) {
       try {
         const output = await plugger.transaction(async (q) => {
@@ -1973,6 +2357,44 @@ function normalizeCondition(c: Condition): unknown {
   }
 }
 
+/** Keep outside-SQL driver failures on the infrastructure path even when they happen before the
+ * scoped mutator has opened its mutation transaction. */
+function scopedOutsideSql(sql: ServerSql | undefined): ServerSql {
+  const unavailable = (): BackendError =>
+    new BackendError(new Error("scope.sql is unavailable on this custom MutationBackend"));
+  // An unencodable bind is a deterministic authoring error, not a database failure. Wrapping it in
+  // BackendError would latch `scope.infra` and retry the envelope forever; leaving it a plain throw
+  // lets the scoped harness treat it as a business rejection and advance lmid.
+  const infra = (error: unknown): unknown =>
+    isUnencodableBind(error) ? new Error(errMessage(error)) : error instanceof BackendError ? error : new BackendError(error);
+  return {
+    async execute(text, params = []) {
+      if (!sql) throw unavailable();
+      try {
+        await sql.execute(text, params);
+      } catch (error) {
+        throw infra(error);
+      }
+    },
+    async batch(statements) {
+      if (!sql) throw unavailable();
+      try {
+        await sql.batch(statements);
+      } catch (error) {
+        throw infra(error);
+      }
+    },
+    async query<Row = Record<string, unknown>>(text: string, params: readonly WireValue[] = []): Promise<Row[]> {
+      if (!sql) throw unavailable();
+      try {
+        return await sql.query<Row>(text, params);
+      } catch (error) {
+        throw infra(error);
+      }
+    },
+  };
+}
+
 /**
  * The runtime {@link MutationScope} handed to a {@link ScopedMutator}. It owns the single atomic
  * transaction (delegating to {@link MutationBackend.runMutation} — the exact machinery a tx-form
@@ -1990,6 +2412,7 @@ class MutationScopeImpl implements MutationScope {
   private readonly backend: MutationBackend;
   private readonly envelope: MutationEnvelope;
   private readonly render: RenderIndex;
+  readonly sql: ServerSql;
   /** Set once `transact` resolved through the backend (accepted OR business-rejected). */
   outcome?: MutationOutcome;
   /** The value the backend threw on INFRA (the DB failed) — always propagated, never an `lmid`
@@ -2009,6 +2432,7 @@ class MutationScopeImpl implements MutationScope {
     this.backend = backend;
     this.envelope = envelope;
     this.render = render;
+    this.sql = scopedOutsideSql(backend.outsideSql);
   }
 
   transact(
@@ -2058,8 +2482,24 @@ class MutationScopeImpl implements MutationScope {
 export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptions<User>): RindleApiServer<User> {
   const routes = { ...DEFAULT_RINDLE_API_ROUTES, ...opts.routes };
   const mode = opts.mode ?? "normalized";
-  // The mutation seam — defaulting to the daemon's co-transactional lmid stamp (unchanged behavior).
-  const backend = opts.backend ?? daemonBackend(opts.daemon);
+  // Explicit backend wins; otherwise prefer the versioned Rindle-SQL mutation transport and retain
+  // daemonBackend as the compatibility path for deployments that have not exposed it yet.
+  let ownedSql: SqlClient | undefined;
+  let backend: MutationBackend;
+  if (opts.backend !== undefined) {
+    backend = opts.backend;
+  } else {
+    if (opts.database !== undefined && opts.sql !== undefined) {
+      throw new TypeError("configure either database or sql, not both");
+    }
+    const sql =
+      opts.sql ??
+      (opts.database !== undefined
+        ? // Default FIRST so `database.intMode` can override it; see RindleDatabaseOptions.
+          (ownedSql = createSqlClient({ intMode: "number", ...opts.database }))
+        : undefined);
+    backend = sql === undefined ? daemonBackend(opts.daemon) : sqlBackend(sql);
+  }
   // Schema-derived render metadata for logical mutator writes; `{}` when no schema is configured (a
   // logical op then throws loudly — the tx never silently drops a write). Each backend renders in its
   // own dialect (`backend.dialect`: daemon→sqlite, postgres→postgres).
@@ -2120,20 +2560,13 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     );
   };
 
-  // The §2.3 aggregate refusal: the client's aggregate overlay is daemon-gated until post-G, so
-  // an aggregate/reduce-shaped query is refused room-serving REGARDLESS of coverage.
+  // Room-served aggregates are refused: a room-retargeted query carrying a count()/reduce reads an
+  // `__agg` head only the daemon feed maintains, and the client's room gate DROPS the `__agg` rows
+  // the room publishes — a known-unsupported shape (302 post-impl review). Room serving otherwise
+  // trusts the declaration (302 §5: declared, not derived); this one shape stays a policy refusal
+  // until room-served aggregates are designed.
   const AGGREGATE_REFUSAL =
-    "the query AST contains an aggregate/reduce shape — aggregate overlays are daemon-gated until post-G";
-
-  // Verdict cache. The verdict is a pure function of exactly two inputs — the resolved footprint
-  // AST and the resolved query AST — so the tightest SOUND key is those two ASTs themselves
-  // (stable-stringified), scoped by (queryName, profile) for legibility. Args/user/ctx need no
-  // separate slot precisely because anything that changes the verdict must change one of the two
-  // ASTs (predicate literals embed the args; ctx-scoped queries embed the principal); keying on
-  // `(name, args)` alone would ALIAS two users' different ASTs under one verdict — unsound.
-  // Bounded FIFO (Map iterates in insertion order) so per-user literals can't grow it forever.
-  const coverVerdicts = new Map<string, CoverQueryOutput>();
-  const COVER_VERDICT_CACHE_MAX = 1024;
+    "the query contains an aggregate/reduce shape — room-served aggregates are not yet supported (the room gate drops `__agg` rows)";
 
   const maybeRoomServe = async (
     input: QueryLeaseRequest<User>,
@@ -2152,13 +2585,6 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         warnRoomServeOnce(input.name, profile.name, ["realtime.locateRoom is not configured"]);
         return undefined;
       }
-      const coverQuery = opts.daemon.coverQuery?.bind(opts.daemon);
-      if (coverQuery === undefined) {
-        warnRoomServeOnce(input.name, profile.name, [
-          "the configured daemon client does not implement coverQuery (/cover-check)",
-        ]);
-        return undefined;
-      }
       const tokenKey = realtime.roomTokenKey;
       if (tokenKey === undefined) {
         warnRoomServeOnce(input.name, profile.name, [
@@ -2187,25 +2613,14 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
       const footprintAst = queryResultToAst(await profile.footprint(key, context));
       assertUnwindowedFootprint(footprintAst, profile.name);
 
-      const verdictKey = `${input.name}\u0000${profile.name}\u0000${stableStringify(footprintAst)}\u0000${stableStringify(queryAst)}`;
-      let verdict = coverVerdicts.get(verdictKey);
-      if (verdict === undefined) {
-        verdict = astHasAggregate(queryAst)
-          ? { covered: false, reasons: [AGGREGATE_REFUSAL] }
-          : await coverQuery({ footprint: footprintAst, query: queryAst });
-        // (A coverQuery THROW never lands here — the outer catch fail-opens without caching, so
-        // a transient daemon failure doesn't pin an uncovered verdict.)
-        if (coverVerdicts.size >= COVER_VERDICT_CACHE_MAX) {
-          coverVerdicts.delete(coverVerdicts.keys().next().value as string);
-        }
-        coverVerdicts.set(verdictKey, verdict);
-      }
-      if (!verdict.covered) {
-        warnRoomServeOnce(input.name, profile.name, verdict.reasons ?? ["not provably covered"]);
+      // Trust the declaration (302 §5): a labeled + wired query is room-served, no coverage proof.
+      // The one shape still refused is the aggregate (a policy gate, not a coverage verdict).
+      if (astHasAggregate(queryAst)) {
+        warnRoomServeOnce(input.name, profile.name, [AGGREGATE_REFUSAL]);
         return undefined;
       }
 
-      // Covered ⇒ assemble the realtime block. The room endpoint rides ITS OWN field
+      // Assemble the realtime block. The room endpoint rides ITS OWN field
       // (`realtime.wsEndpoint`) — a separate connection from the daemon session's fixed ws host.
       const { wsEndpoint } = await realtime.locateRoom(doc);
       const now = Date.now();
@@ -2236,7 +2651,8 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         tables,
       };
     } catch (e) {
-      // Fail open — a lease is never blocked on the proof. Not cached (may be transient).
+      // Fail open — a lease is never blocked on room-serve wiring (footprint resolution,
+      // locateRoom, token minting). A failure here just serves the query from the daemon.
       warnRoomServeOnce(input.name, profile.name, [`room-serve failed: ${errMessage(e)}`]);
       return undefined;
     }
@@ -2501,12 +2917,12 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     const res = queryLeaseResponse(out);
     // I-iv (§4.1): the occupancy step FIRST — session sweep+upsert, then the D6 gate verdict. A
     // closed gate suppresses the room-serve ONLY (the lease ships without the realtime block,
-    // indistinguishable from an uncovered query — the fail-open daemon path) while the doorbell
+    // indistinguishable from a non-room-served query — the daemon path) while the doorbell
     // below still rides; lifecycle-off ⇒ `gateOpen: true` unconditionally and this line is inert.
     const occ = await lifecycleOccupancy(input);
-    // G-iv-b: a covered labeled query ADDITIONALLY gains the realtime block. The daemon lease
+    // G-iv-b: a labeled + wired query ADDITIONALLY gains the realtime block. The daemon lease
     // above is unconditional (and its fields untouched) — room-serving only ever adds a field,
-    // so an uncovered/unwired/legacy lease stays byte-identical and nothing here can block one.
+    // so a non-room-served/legacy lease stays byte-identical and nothing here can block one.
     const rt = occ.gateOpen ? await maybeRoomServe(input, ast, context, subject) : undefined;
     if (rt !== undefined) res.realtime = rt;
     // I-v (§4.2): the gate CLOSED and a room plausibly hosted this scope — drain it and ride the
@@ -2700,57 +3116,6 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     }
   };
 
-  // The explicit coverage diagnostic (the assertPins pattern: system-level, resolved under
-  // `pinUser`, per-query failures collected — never strand the rest). It runs the REAL check —
-  // the daemon's /cover-check on the actually-resolved ASTs — so its verdicts are exactly the
-  // lease path's, minus the serving wiring (locateRoom/roomTokenKey), which it deliberately
-  // ignores: it answers "is this labeled query coverable", the deployable-config question.
-  const validateRealtime = async (vopts?: {
-    exemplars?: Partial<Record<string, readonly unknown[]>>;
-    strict?: boolean;
-  }): Promise<ValidateRealtimeReport> => {
-    const context: ApiContext<User> = { user: opts.pinUser as User, request: undefined };
-    const coverQuery = opts.daemon.coverQuery?.bind(opts.daemon);
-    const verdicts: ValidateRealtimeVerdict[] = [];
-    for (const [name, q] of Object.entries(opts.queries ?? {})) {
-      const label = queryRealtimeLabel(q);
-      if (label === undefined) continue;
-      const profile = roomProfiles.get(label.room);
-      if (profile === undefined) continue; // unreachable: construction asserted it exists
-      for (const args of vopts?.exemplars?.[name] ?? [null]) {
-        const verdict: ValidateRealtimeVerdict = { query: name, profile: profile.name, args, covered: false };
-        try {
-          const ast = await resolveAst(name, args, context);
-          const roomArgs = label.args !== undefined ? label.args(args) : args;
-          const footprintAst = queryResultToAst(await profile.footprint(profile.key(roomArgs), context));
-          assertUnwindowedFootprint(footprintAst, profile.name);
-          if (astHasAggregate(ast)) {
-            verdict.reasons = [AGGREGATE_REFUSAL];
-          } else if (coverQuery === undefined) {
-            verdict.reasons = ["the configured daemon client does not implement coverQuery (/cover-check)"];
-          } else {
-            const out = await coverQuery({ footprint: footprintAst, query: ast });
-            verdict.covered = out.covered;
-            if (!out.covered) verdict.reasons = out.reasons ?? ["not provably covered"];
-          }
-        } catch (e) {
-          verdict.reasons = [errMessage(e)];
-        }
-        verdicts.push(verdict);
-      }
-    }
-    const uncovered = verdicts.filter((v) => !v.covered);
-    if (vopts?.strict && uncovered.length > 0) {
-      throw new Error(
-        `validateRealtime: ${uncovered.length} labeled query verdict(s) not provably covered — ` +
-          uncovered
-            .map((v) => `${v.query} (profile "${v.profile}"): ${(v.reasons ?? []).join("; ")}`)
-            .join(" | "),
-      );
-    }
-    return { verdicts, uncovered };
-  };
-
   // The room write-authority gate (§5.3.1): endpoints are disabled until the app opts in —
   // the `realtime` block (which also activates `/room-boot`) or the deprecated bare
   // `authorizeRoom` (trio only). Hosting an authority is never a default.
@@ -2815,10 +3180,10 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
 
   return {
     routes,
+    close: () => ownedSql?.close(),
     createQueryLease,
     readQuery,
     assertPins,
-    validateRealtime,
     pushMutation,
     pushMutations,
     handleApplyRowChangeTxnJson: async (body, context) => {
@@ -3005,8 +3370,9 @@ function applyOpToServerTx(tx: ServerWriteTx, op: MutationOp): Promise<void> {
 
 /** Feed a mutator's RETURNED result (the alternative to calling `tx.exec`/logical ops directly) into
  *  the backend tx: a returned `SqlStatement[]` / `SqlTxn` is exec'd onto `tx`, and a carried
- *  `idempotencyKey` is stashed (the daemon backend honors it; PG ignores it). A `void` return is a
- *  no-op — the mutator already drove the tx. Preserves the pre-existing return-style contract. */
+ *  `idempotencyKey` is stashed for the legacy daemon adapter; the SQL mutation facade uses `mid`
+ *  as its durable retry identity and PG ignores it. A `void` return is a no-op — the mutator already
+ *  drove the tx. Preserves the return-style contract. */
 function applyResultToTx(result: ApiMutatorResult, tx: ServerMutationTx): void {
   if (!result) return;
   const statements = Array.isArray(result) ? result : result.statements;
@@ -3141,7 +3507,7 @@ const ROOM_MUTATION_OUTCOMES_TABLE = "_rindle_room_mutation_outcomes";
 // delta fanning to every subscribed solo client; no clientID/mid — a system write must never
 // advance an lmid — and no idempotencyKey — a renewal's re-upsert must re-run, that is the
 // refresh), and the count is one `executeSqlRead` with `consistency: "strong"` — the read surface
-// the api-server already has against the daemon (the `DaemonLazyTx` fallback precedent above).
+// the api-server already has against the daemon (the `RemoteLazyTx` fallback precedent above).
 // "strong" routes the read to the WRITE MASTER in a split deploy, which just serialized our
 // upsert: read-your-writes without a mutation session (the interactive-txn machinery is optional
 // on the daemon interface and far heavier than this two-round-trip pair needs).
@@ -3220,19 +3586,6 @@ function docClientAst(table: string, doc: string, clientId: string | undefined):
  *  lease through the api-server, never an extension of this token. */
 const DEFAULT_ROOM_TOKEN_TTL_MS = 5 * 60_000;
 
-/** Deterministic JSON: object keys sorted recursively, so two structurally identical ASTs from
- *  independent resolves stringify identically (the verdict-cache key). */
-function stableStringify(v: unknown): string {
-  return JSON.stringify(v, (_key, value: unknown) => {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      const rec = value as Record<string, unknown>;
-      const sorted: Record<string, unknown> = {};
-      for (const k of Object.keys(rec).sort()) sorted[k] = rec[k];
-      return sorted;
-    }
-    return value;
-  });
-}
 
 /** Does the AST contain an aggregate/reduce shape ANYWHERE (root, a `related` subquery, or an
  *  `EXISTS` child)? Room-serving refuses these regardless of coverage: the client's aggregate