@rindle/api-server 0.6.3 → 0.7.0

package/dist/index.js

@@ -1,5 +1,6 @@
 import { driveMutationAsync, insertCell, insertPlan, isGeneratorMutator, isoTx, toCell } from "@rindle/client";
 import { DaemonHttpError } from "@rindle/daemon-client";
+import { createSqlClient, encodeSqlValue, RindleSqlError } from "@rindle/sql-client";
 import { compile as compileQueryAst } from "@rindle/query-compiler";
 import { assertLabeledProfilesExist, assertUnwindowedFootprint, attachRealtimeLabel, compileRoomProfiles, compileRoomScopeSpecs, compileRoomTableSpecs, mintRoomDoc, queryRealtimeLabel, queryResultToAst, splitRoomDoc, } from "./rooms.js";
 let roomTokenModule;
@@ -248,14 +249,6 @@ export class SplitDaemonClient {
             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) {
-        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) {
         return this.writes.migrate(input);
     }
@@ -390,9 +383,6 @@ export class BackendError extends Error {
         this.driverError = driverError;
     }
 }
-/** 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
@@ -449,6 +439,9 @@ class AbsorbedReplay extends Error {
 }
 const MUTATOR_CONFLICT_MAX_ATTEMPTS = 5;
 function isRetryableCommitConflict(error) {
+    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 {
@@ -464,10 +457,248 @@ async function mutatorConflictBackoff(attempt) {
     const millis = ceiling + Math.floor(Math.random() * 4);
     await new Promise((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) {
+    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, params) {
+    if (params === undefined)
+        return;
+    for (let index = 0; index < params.length; index++) {
+        try {
+            encodeSqlValue(params[index]);
+        }
+        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) {
+    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`);
+    }
+}
+function daemonMutationTransport(daemon) {
+    return {
+        interactive: daemon.beginMutationSession !== undefined,
+        strictValues: false,
+        execute({ envelope, statements, idempotencyKey }) {
+            const txn = { 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 = {
+                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 };
+            }
+            return { handle: opened.sessionId, read: opened.read };
+        },
+        async exec(handle, statements) {
+            await daemon.execInMutationSession({ sessionId: handle, statements });
+        },
+        query(handle, statement) {
+            return daemon.queryInMutationSession({
+                sessionId: handle,
+                sql: statement.sql,
+                params: statement.params,
+            });
+        },
+        commit(handle) {
+            return daemon.commitMutationSession({ sessionId: handle });
+        },
+        async rollback(handle) {
+            await daemon.rollbackMutationSession({ sessionId: handle });
+        },
+        readCommitted(statement) {
+            return daemon.executeSqlRead({ sql: statement.sql, params: statement.params });
+        },
+    };
+}
+function mutationReceiptOutput(receipt, clientID) {
+    const output = {
+        applied: receipt.applied,
+        lmid: receipt.lmid,
+        lmidAdvances: [{ clientID, lmid: receipt.lmid }],
+    };
+    if (receipt.commitCursor !== null)
+        output.cursor = receipt.commitCursor;
+    return output;
+}
+function publicMutationStatement(statement) {
+    return statement.params === undefined ? { sql: statement.sql } : { sql: statement.sql, args: statement.params };
+}
+function mutationRowsOutput(rows) {
+    return { cols: rows.columns, rows: rows.rows };
+}
+/** Convert the transports' compact positional rows into the ergonomic server-only raw-SQL shape. */
+function keyedSqlRows(columns, rows) {
+    // 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();
+    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]])));
+}
+function daemonOutsideSql(daemon) {
+    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(sql, params = []) {
+            const out = await daemon.executeSqlRead({ sql, params: [...params], consistency: "strong" });
+            return keyedSqlRows(out.cols, out.rows);
+        },
+    };
+}
+function sqlSessionOutsideSql(sql) {
+    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(text, params = []) {
+            const out = await sql.execute({ sql: text, args: [...params], wantRows: true }, { consistency: "strong" });
+            return keyedSqlRows(out.result.columns.map((column) => column.name), out.result.rows);
+        },
+    };
+}
+function sqlClientMutationTransport(sql) {
+    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.batch(statements.map(publicMutationStatement));
+        },
+        async query(handle, statement) {
+            return mutationRowsOutput(await handle.query(publicMutationStatement(statement)));
+        },
+        async commit(handle) {
+            const receipt = await handle.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.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,
+            };
+        },
+    };
+}
 /**
- * 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.
@@ -476,40 +707,61 @@ async function mutatorConflictBackoff(attempt) {
  * 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 {
+class RemoteLazyTx {
     /** Pre-upgrade: the accumulated batch/prefix. Post-upgrade: writes buffered for the next flush. */
     stmts = [];
     render;
-    daemon;
+    transport;
     envelope;
-    sessionId;
+    sessionHandle;
+    sql;
     /** The begin-absorbed replay output (§4.1), latched for the backend. */
     absorbed;
     idempotencyKey;
-    constructor(render, daemon, envelope) {
+    constructor(render, transport, envelope) {
         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: (sql, params = []) => this.querySql(sql, params),
+        };
     }
     /** True once the tx upgraded to an interactive session (the backend then commits it). */
     get session() {
-        return this.sessionId !== undefined;
+        return this.sessionHandle !== undefined;
     }
     get statements() {
         return this.stmts;
     }
     exec(sql, params = []) {
+        // 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 });
     }
     push(op) {
         const rendered = renderOp(op, tableMeta(this.render, op.table), sqliteDialect);
-        if (rendered)
+        if (rendered) {
+            if (this.transport.strictValues)
+                assertEncodableParams(rendered.sql, rendered.params);
             this.stmts.push(rendered);
+        }
         return Promise.resolve();
     }
     insert(table, row) {
@@ -549,44 +801,49 @@ class DaemonLazyTx {
             return ast.one === true ? null : [];
         return JSON.parse(cell);
     }
+    async querySql(sql, params) {
+        const out = await this.readThroughTxn({ sql, params: [...params] });
+        return keyedSqlRows(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. */
     async readThroughTxn(read) {
         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;
+                    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)
@@ -598,17 +855,18 @@ class DaemonLazyTx {
     async flush() {
         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
      *  answers the same shape `/execute-sql-txn` does. */
     async commitSession() {
         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);
@@ -617,12 +875,12 @@ class DaemonLazyTx {
     /** 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() {
-        if (this.sessionId === undefined)
+        if (this.sessionHandle === undefined)
             return;
-        const sessionId = this.sessionId;
-        this.sessionId = undefined;
+        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.
@@ -639,11 +897,25 @@ class PgLiveTx {
     q;
     render;
     rewrite;
+    sql;
     idempotencyKey;
     constructor(q, render, rewrite) {
         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: (sql, params = []) => this.querySql(sql, params),
+        };
     }
     get statements() {
         return this.stmts;
@@ -711,24 +983,29 @@ class PgLiveTx {
         // static-catalog + driver-pin wiring (POSTGRES-READ-COMPILER-DESIGN.md Phase B).
         return Promise.reject(new Error("tx.query is not wired on the Postgres backend yet (POSTGRES-READ-COMPILER-DESIGN.md Phase B) — use tx.row for point reads meanwhile"));
     }
+    async querySql(sql, params) {
+        await this.settle();
+        try {
+            return (await this.q.query(this.rewrite(sql), [...params]));
+        }
+        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) {
+/** 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, outsideSql) {
     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);
                     }
@@ -745,7 +1022,7 @@ export function daemonBackend(daemon) {
                         // 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)
@@ -760,10 +1037,14 @@ export function daemonBackend(daemon) {
                             throw err;
                         }
                     }
-                    const txn = { 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) {
@@ -775,10 +1056,21 @@ export function daemonBackend(daemon) {
             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) {
+    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) {
+    return remoteMutationBackend(sqlClientMutationTransport(sql), sqlSessionOutsideSql(sql));
+}
 /** The §2.3 upsert, verbatim from the contract: monotonic via GREATEST, keyed by client. The
  *  identifiers are lowercase so quoting is cosmetic, but quote-everything is the repo's PG rule. */
 const LMID_UPSERT = `INSERT INTO "_rindle_client_mutations" ("client_id", "last_mutation_id")
@@ -807,8 +1099,28 @@ export function postgresBackend(plugger, opts = {}) {
         await q.exec(LMID_UPSERT, [envelope.clientID, envelope.mid]);
         return { applied: true, lmidAdvances: [{ clientID: envelope.clientID, lmid: envelope.mid }] };
     });
+    const outsideSql = {
+        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(sql, params = []) {
+            return plugger.transaction(async (q) => (await q.query(rewrite(sql), [...params])));
+        },
+    };
     return {
         dialect: postgresDialect,
+        outsideSql,
         async runMutation({ envelope, render, run }) {
             try {
                 const output = await plugger.transaction(async (q) => {
@@ -1106,6 +1418,47 @@ function normalizeCondition(c) {
             };
     }
 }
+/** 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) {
+    const unavailable = () => 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) => 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(text, params = []) {
+            if (!sql)
+                throw unavailable();
+            try {
+                return await sql.query(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
@@ -1123,6 +1476,7 @@ class MutationScopeImpl {
     backend;
     envelope;
     render;
+    sql;
     /** Set once `transact` resolved through the backend (accepted OR business-rejected). */
     outcome;
     /** The value the backend threw on INFRA (the DB failed) — always propagated, never an `lmid`
@@ -1141,6 +1495,7 @@ class MutationScopeImpl {
         this.backend = backend;
         this.envelope = envelope;
         this.render = render;
+        this.sql = scopedOutsideSql(backend.outsideSql);
     }
     transact(first, args, ctx) {
         if (this.attempted)
@@ -1179,8 +1534,24 @@ class MutationScopeImpl {
 export function createRindleApiServer(opts) {
     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;
+    let backend;
+    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).
@@ -1234,18 +1605,12 @@ export function createRindleApiServer(opts) {
             `${reasons.join("; ")}. It serves from the daemon (correct, just not room-accelerated). ` +
             `This warning fires once per (query, profile).`);
     };
-    // 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.
-    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();
-    const COVER_VERDICT_CACHE_MAX = 1024;
+    // 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 contains an aggregate/reduce shape — room-served aggregates are not yet supported (the room gate drops `__agg` rows)";
     const maybeRoomServe = async (input, queryAst, context, subject) => {
         // (a) the label + (b) its profile — the fast bail keeps unlabeled leases byte-identical.
         const label = queryRealtimeLabel(opts.queries?.[input.name]);
@@ -1260,13 +1625,6 @@ export function createRindleApiServer(opts) {
                 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, [
@@ -1292,24 +1650,13 @@ export function createRindleApiServer(opts) {
             // profiles), with the §2.3 unwindowed backstop `/room-boot` also applies.
             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);
-                }
-                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();
@@ -1341,7 +1688,8 @@ export function createRindleApiServer(opts) {
             };
         }
         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;
         }
@@ -1587,12 +1935,12 @@ export function createRindleApiServer(opts) {
         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;
@@ -1792,57 +2140,6 @@ export function createRindleApiServer(opts) {
             throw new Error(`assertPins: ${failures.length} failed — ${failures.join("; ")}`);
         }
     };
-    // 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) => {
-        const context = { user: opts.pinUser, request: undefined };
-        const coverQuery = opts.daemon.coverQuery?.bind(opts.daemon);
-        const verdicts = [];
-        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 = { 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.
@@ -1897,10 +2194,10 @@ export function createRindleApiServer(opts) {
     };
     return {
         routes,
+        close: () => ownedSql?.close(),
         createQueryLease,
         readQuery,
         assertPins,
-        validateRealtime,
         pushMutation,
         pushMutations,
         handleApplyRowChangeTxnJson: async (body, context) => {
@@ -2087,8 +2384,9 @@ function applyOpToServerTx(tx, op) {
 }
 /** 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, tx) {
     if (!result)
         return;
@@ -2211,7 +2509,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).
@@ -2279,20 +2577,6 @@ function docClientAst(table, doc, clientId) {
 /** Default room lease token TTL: short (minutes) per RINDLE-REALTIME §4.1 — renewal is a fresh
  *  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) {
-    return JSON.stringify(v, (_key, value) => {
-        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-            const rec = value;
-            const sorted = {};
-            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
  *  overlay (AGGREGATE-SYNC) is computed against the DAEMON's normalized stream and stays