@rindle/api-server 0.3.1 → 0.4.3

package/dist/index.js

@@ -1,4 +1,10 @@
+import { driveMutationAsync, insertCell, insertPlan, isoTx, toCell } from "@rindle/client";
 import { DaemonHttpError } from "@rindle/daemon-client";
+import { compile as compileQueryAst } from "@rindle/query-compiler";
+// Re-export the shared (generator) mutator seam so an app builds its server mutators from ONE import:
+// co-locate each body with its arg schema (`shared`), bulk-drive the registry ({@link sharedApiMutators}),
+// keeping only server-only authority as explicit overrides (see MUTATORS-ISOMORPHIC).
+export { isoTx, shared } from "@rindle/client";
 export const DEFAULT_RINDLE_API_ROUTES = {
     query: "/api/rindle/query",
     read: "/api/rindle/read",
@@ -8,7 +14,79 @@ export const DEFAULT_RINDLE_API_ROUTES = {
     applyRowChangeTxn: "/api/rindle/apply-row-change-txn",
     claimRoomEpoch: "/api/rindle/claim-room-epoch",
     roomLmids: "/api/rindle/room-lmids",
+    // The DO shell's cold-boot callback (§10.1) — active only when `realtime` is configured.
+    roomBoot: "/api/rindle/room-boot",
 };
+// The DEFAULT flush credential: `rfc1.<b64url payload>.<b64url hmac-sha256>`, payload
+// `{v:1, doc, epoch, iat}`. Deliberately EPOCH-bound, not time-bound: the credential's lifecycle
+// IS the placement fence (§8.3 — a superseded epoch's flushes 409 at the store no matter what
+// credential they carry), and platform revocation is registry suspension, so an `exp` would only
+// force spurious re-boots of long-lived rooms. HMAC via WebCrypto (`crypto.subtle`) so the exact
+// same code runs in Node and a Cloudflare Worker — no `node:crypto` import (matching
+// `@rindle/room`'s token module).
+export const ROOM_FLUSH_CREDENTIAL_HEADER = "x-rindle-room-credential";
+const FLUSH_CREDENTIAL_PREFIX = "rfc1";
+function b64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// Return type inferred (`Uint8Array<ArrayBuffer>` under TS ≥5.7 libs) — an explicit
+// `Uint8Array` annotation widens to `ArrayBufferLike` and fails `crypto.subtle`'s
+// `BufferSource` under consumers compiling this source with newer lib types.
+function unb64url(s) {
+    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+async function flushHmacKey(secret, usage) {
+    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+}
+/** Sign the default epoch-bound flush credential (`/room-boot` mints one per placement). */
+export async function mintRoomFlushCredential(opts) {
+    const payload = {
+        v: 1,
+        doc: opts.doc,
+        epoch: opts.epoch,
+        iat: opts.now ?? Date.now(),
+    };
+    const body = b64url(new TextEncoder().encode(JSON.stringify(payload)));
+    const signed = `${FLUSH_CREDENTIAL_PREFIX}.${body}`;
+    const key = await flushHmacKey(opts.shellSecret, "sign");
+    const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(signed)));
+    return `${signed}.${b64url(sig)}`;
+}
+/** Verify a flush credential's MAC, then its claims; returns the payload or throws. The MAC is
+ *  checked FIRST — no claim is trusted before it passes. */
+export async function verifyRoomFlushCredential(credential, shellSecret) {
+    const parts = credential.split(".");
+    if (parts.length !== 3 || parts[0] !== FLUSH_CREDENTIAL_PREFIX) {
+        throw new Error("not a room flush credential");
+    }
+    const [, body, sig] = parts;
+    const key = await flushHmacKey(shellSecret, "verify");
+    const ok = await crypto.subtle.verify("HMAC", key, unb64url(sig), new TextEncoder().encode(`${FLUSH_CREDENTIAL_PREFIX}.${body}`));
+    if (!ok)
+        throw new Error("bad signature");
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(unb64url(body)));
+    }
+    catch {
+        throw new Error("malformed payload");
+    }
+    if (payload.v !== 1)
+        throw new Error("unknown version");
+    if (typeof payload.doc !== "string" || payload.doc.length === 0) {
+        throw new Error("missing doc");
+    }
+    if (typeof payload.epoch !== "number")
+        throw new Error("missing epoch");
+    return payload;
+}
 export class RindleApiError extends Error {
     code;
     status;
@@ -57,6 +135,38 @@ export class SplitDaemonClient {
     rejectMutation(input) {
         return this.writes.rejectMutation(input);
     }
+    // Interactive mutation sessions hold the MASTER's write transaction — never a replica's
+    // (DAEMON-INTERACTIVE-TXN-DESIGN.md §4.1; the follower write-fence enforces the same).
+    beginMutationSession(input) {
+        const begin = this.writes.beginMutationSession?.bind(this.writes);
+        if (!begin)
+            return Promise.reject(new Error("the write master lacks mutation sessions"));
+        return begin(input);
+    }
+    execInMutationSession(input) {
+        const exec = this.writes.execInMutationSession?.bind(this.writes);
+        if (!exec)
+            return Promise.reject(new Error("the write master lacks mutation sessions"));
+        return exec(input);
+    }
+    queryInMutationSession(input) {
+        const query = this.writes.queryInMutationSession?.bind(this.writes);
+        if (!query)
+            return Promise.reject(new Error("the write master lacks mutation sessions"));
+        return query(input);
+    }
+    commitMutationSession(input) {
+        const commit = this.writes.commitMutationSession?.bind(this.writes);
+        if (!commit)
+            return Promise.reject(new Error("the write master lacks mutation sessions"));
+        return commit(input);
+    }
+    rollbackMutationSession(input) {
+        const rollback = this.writes.rollbackMutationSession?.bind(this.writes);
+        if (!rollback)
+            return Promise.reject(new Error("the write master lacks mutation sessions"));
+        return rollback(input);
+    }
     applyRowChangeTxn(input) {
         return this.writes.applyRowChangeTxn(input);
     }
@@ -86,18 +196,480 @@ export class SplitDaemonClient {
         return this.reads.dematerialize(input);
     }
 }
+export const sqliteDialect = { name: "sqlite", placeholder: () => "?" };
+export const postgresDialect = { name: "postgres", placeholder: (i) => `$${i}` };
+/** Build the {@link RenderIndex} from a typed schema (`schema.tables[name]` is a `TableMeta`). */
+export function buildRenderIndex(schema) {
+    const out = {};
+    const tables = schema.tables;
+    for (const name of Object.keys(tables)) {
+        const meta = tables[name];
+        const columns = Object.keys(meta.columns);
+        const types = {};
+        for (const c of columns)
+            types[c] = meta.columns[c].type;
+        // Same schema-derived plan the client funnel uses (design 206 §6.1), so their required-sets
+        // and null-fills can't drift.
+        const { required, nullable } = insertPlan(schema.tables[name]);
+        out[name] = { columns, pkNames: [...meta.primaryKey], types, required, nullable };
+    }
+    return out;
+}
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+function tableMeta(render, table) {
+    const meta = render[table];
+    if (!meta) {
+        const known = Object.keys(render);
+        throw new Error(`logical mutator write to unknown table ${JSON.stringify(table)} — did you pass \`schema\` to createRindleApiServer? known tables: ${known.length ? known.join(", ") : "(none — no schema configured)"}`);
+    }
+    return meta;
+}
+/** Validate a keyed row against a table: reject unknown columns; require the pk columns; with
+ *  `full`, require every NON-nullable column (a nullable column may be omitted and is filled with
+ *  `NULL`, design 206 §6.2). Mirrors the client `trackingTx.checkColumns` messages so an author sees
+ *  the same error on both tiers. */
+function checkColumns(table, obj, meta, full) {
+    const unknown = Object.keys(obj).filter((k) => !meta.columns.includes(k));
+    if (unknown.length) {
+        throw new Error(`unknown column${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} on ${table} — columns: ${meta.columns.join(", ")}`);
+    }
+    const required = full ? meta.required : meta.pkNames;
+    const missing = required.filter((c) => !(c in obj));
+    if (missing.length) {
+        throw new Error(`missing ${full ? "column" : "primary-key column"}${missing.length > 1 ? "s" : ""} ${missing.join(", ")} on ${table}`);
+    }
+}
+const encode = (dialect, v, type) => dialect.encodeValue ? dialect.encodeValue(v, type) : v;
+/** Render one {@link MutationOp} to a `{sql, params}` for the dialect, or `null` for a no-op (an
+ *  `update` whose row names only pk columns — nothing to SET, matching the client's no-op edit). */
+export function renderOp(op, meta, dialect) {
+    const t = quoteIdent(op.table);
+    const params = [];
+    // Bind a value and return its placeholder at the correct 1-based index (post-push length).
+    // `insertCell` fills NULL for an omitted nullable column on the insert arm (design 206 §6.2);
+    // on update/delete every bound column is guaranteed present, so it is a pass-through there.
+    // `toCell` stringifies a `json` object (a typed mutator passes the parsed object) — a string
+    // passes through, so an author may still pass pre-stringified json.
+    const bind = (c, row) => {
+        params.push(encode(dialect, toCell(insertCell(row, c), meta.types[c]), meta.types[c]));
+        return dialect.placeholder(params.length);
+    };
+    if (op.kind === "insert" || op.kind === "insertIgnore" || op.kind === "upsert") {
+        checkColumns(op.table, op.row, meta, true);
+        const cols = meta.columns;
+        const values = cols.map((c) => bind(c, op.row));
+        let sql = `INSERT INTO ${t} (${cols.map(quoteIdent).join(", ")}) VALUES (${values.join(", ")})`;
+        if (op.kind === "insertIgnore") {
+            sql += ` ON CONFLICT (${meta.pkNames.map(quoteIdent).join(", ")}) DO NOTHING`;
+        }
+        else if (op.kind === "upsert") {
+            const nonPk = cols.filter((c) => !meta.pkNames.includes(c));
+            sql += ` ON CONFLICT (${meta.pkNames.map(quoteIdent).join(", ")}) `;
+            sql += nonPk.length
+                ? `DO UPDATE SET ${nonPk.map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`).join(", ")}`
+                : `DO NOTHING`;
+        }
+        return { sql, params };
+    }
+    if (op.kind === "update") {
+        checkColumns(op.table, op.row, meta, false);
+        const setCols = meta.columns.filter((c) => !meta.pkNames.includes(c) && c in op.row);
+        if (!setCols.length)
+            return null; // pk-only row → nothing to change (client no-op edit)
+        const setSql = setCols.map((c) => `${quoteIdent(c)} = ${bind(c, op.row)}`);
+        const whereSql = meta.pkNames.map((c) => `${quoteIdent(c)} = ${bind(c, op.row)}`);
+        return { sql: `UPDATE ${t} SET ${setSql.join(", ")} WHERE ${whereSql.join(" AND ")}`, params };
+    }
+    // delete
+    checkColumns(op.table, op.pk, meta, false);
+    const whereSql = meta.pkNames.map((c) => `${quoteIdent(c)} = ${bind(c, op.pk)}`);
+    return { sql: `DELETE FROM ${t} WHERE ${whereSql.join(" AND ")}`, params };
+}
+/** Render a point read (`tx.row`) — `SELECT <cols> FROM "T" WHERE <pk>` — for read-your-writes. */
+export function renderPointRead(table, pk, meta, dialect) {
+    checkColumns(table, pk, meta, false);
+    const params = [];
+    const whereSql = meta.pkNames.map((c) => {
+        params.push(encode(dialect, pk[c], meta.types[c]));
+        return `${quoteIdent(c)} = ${dialect.placeholder(params.length)}`;
+    });
+    const cols = meta.columns.map(quoteIdent).join(", ");
+    return { sql: `SELECT ${cols} FROM ${quoteIdent(table)} WHERE ${whereSql.join(" AND ")}`, params };
+}
+/** Map a driver row (column-name keyed) to a {@link KeyedRow} over the table's known columns. */
+function rowToKeyed(row, meta) {
+    if (!row)
+        return undefined;
+    const out = {};
+    for (const c of meta.columns)
+        out[c] = row[c];
+    return out;
+}
+// --------------------------------------------------------------------------- backends + server tx
+/** Thrown (wrapping the driver error) by a server tx's DB calls, so the seam can tell an INFRA
+ *  failure (retry) from a mutator-body throw (business rejection). */
+export class BackendError extends Error {
+    driverError;
+    constructor(driverError) {
+        super(driverError instanceof Error ? driverError.message : String(driverError));
+        this.name = "BackendError";
+        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
+ *  map is inherently per-query. `columnTypes` are stubs: the sqlite dialect binds natives and
+ *  never consults them (DAEMON-INTERACTIVE-TXN §5.4 — no casts). */
+function catalogFor(render, root) {
+    const tables = {};
+    const ensure = (table) => {
+        const existing = tables[table];
+        if (existing)
+            return existing;
+        const meta = tableMeta(render, table);
+        const columnTypes = {};
+        for (const c of meta.columns)
+            columnTypes[c] = { type: "text", isEnum: false, isArray: false };
+        return (tables[table] = {
+            columns: [...meta.columns],
+            primaryKey: [...meta.pkNames],
+            columnTypes,
+            relationships: {},
+        });
+    };
+    const walkCondition = (cond) => {
+        if (!cond)
+            return;
+        if (cond.type === "and" || cond.type === "or") {
+            for (const c of cond.conditions)
+                walkCondition(c);
+        }
+        else if (cond.type === "correlatedSubquery") {
+            walkAst(cond.related.subquery);
+        }
+    };
+    const walkAst = (ast) => {
+        const t = ensure(ast.table);
+        for (const rel of ast.related ?? []) {
+            const alias = rel.subquery.alias;
+            if (alias != null)
+                t.relationships[alias] = rel.subquery.one === true ? "one" : "many";
+            walkAst(rel.subquery);
+        }
+        walkCondition(ast.where);
+    };
+    walkAst(root);
+    return { tables };
+}
+/** The control-flow unwind for a begin-absorbed replay (DAEMON-INTERACTIVE-TXN §4.1): thrown
+ *  from the first read so the mutator body stops re-running an already-committed envelope; the
+ *  backend answers with the tx's latched authoritative output. Never surfaces to users. */
+class AbsorbedReplay extends Error {
+    constructor() {
+        super("mutation absorbed by mid dedup at session begin");
+    }
+}
 /**
- * Today's behavior as a {@link MutationBackend}: ship the statements + envelope to the daemon,
- * whose `/execute-sql-txn` path stamps `lmid` co-transactionally (and `/reject-mutation` advances
- * it past a rejected mid). This is the default backend — existing users never see a change.
+ * The daemon 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
+ * 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.
+ * From then on reads run THROUGH the open transaction (read-your-writes — PG parity, and no
+ * read-then-write race) and writes buffer locally, flushing before the next read/commit: k
+ * 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}
+ * 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 {
+    /** Pre-upgrade: the accumulated batch/prefix. Post-upgrade: writes buffered for the next flush. */
+    stmts = [];
+    render;
+    daemon;
+    envelope;
+    sessionId;
+    /** The begin-absorbed replay output (§4.1), latched for the backend. */
+    absorbed;
+    idempotencyKey;
+    constructor(render, daemon, envelope) {
+        this.render = render;
+        this.daemon = daemon;
+        this.envelope = envelope;
+    }
+    /** True once the tx upgraded to an interactive session (the backend then commits it). */
+    get session() {
+        return this.sessionId !== undefined;
+    }
+    get statements() {
+        return this.stmts;
+    }
+    exec(sql, params = []) {
+        this.stmts.push({ sql, params });
+    }
+    push(op) {
+        const rendered = renderOp(op, tableMeta(this.render, op.table), sqliteDialect);
+        if (rendered)
+            this.stmts.push(rendered);
+        return Promise.resolve();
+    }
+    insert(table, row) {
+        return this.push({ kind: "insert", table, row });
+    }
+    update(table, row) {
+        return this.push({ kind: "update", table, row });
+    }
+    upsert(table, row) {
+        return this.push({ kind: "upsert", table, row });
+    }
+    insertIgnore(table, row) {
+        return this.push({ kind: "insertIgnore", table, row });
+    }
+    delete(table, pk) {
+        return this.push({ kind: "delete", table, pk });
+    }
+    async row(table, pk) {
+        const read = renderPointRead(table, pk, tableMeta(this.render, table), sqliteDialect);
+        const out = await this.readThroughTxn(read);
+        const cells = out.rows[0];
+        if (!cells)
+            return undefined;
+        const keyed = {}; // the daemon returns positional cells — zip with `cols`
+        out.cols.forEach((c, i) => (keyed[c] = cells[i]));
+        return keyed;
+    }
+    /** A full-shape read inside the open transaction (§5.4): compile to ONE SQLite `SELECT`
+     *  (native bind params, no casts — SQLite is the canonical store), ride the session like
+     *  `row` (including the lazy upgrade / begin ride-along), parse the single JSON cell. */
+    async query(q) {
+        const ast = typeof q.ast === "function" ? q.ast() : q;
+        const compiled = compileQueryAst(ast, catalogFor(this.render, ast), { dialect: "sqlite" });
+        const out = await this.readThroughTxn({ sql: compiled.sql, params: compiled.params });
+        const cell = out.rows[0]?.[0];
+        if (typeof cell !== "string")
+            return ast.one === true ? null : [];
+        return JSON.parse(cell);
+    }
+    /** 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) {
+            try {
+                return await this.daemon.executeSqlRead({ sql: read.sql, params: read.params });
+            }
+            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,
+                    statements: this.stmts.splice(0),
+                    query: read,
+                });
+                if (opened.absorbed) {
+                    const { absorbed: _a, sessionId: _s, read: _r, ...output } = opened;
+                    this.absorbed = output;
+                    throw new AbsorbedReplay();
+                }
+                if (!opened.sessionId || !opened.read) {
+                    throw new Error(`malformed mutate-session begin reply: ${JSON.stringify(opened)}`);
+                }
+                this.sessionId = opened.sessionId;
+                return opened.read;
+            }
+            await this.flush();
+            return await this.daemon.queryInMutationSession({
+                sessionId: this.sessionId,
+                sql: read.sql,
+                params: read.params,
+            });
+        }
+        catch (err) {
+            if (err instanceof AbsorbedReplay || err instanceof BackendError)
+                throw err;
+            throw new BackendError(err);
+        }
+    }
+    /** Ship buffered writes into the open session, order-preserving; a no-op when none pend. */
+    async flush() {
+        if (this.stmts.length === 0)
+            return;
+        await this.daemon.execInMutationSession({
+            sessionId: this.sessionId,
+            statements: 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 });
+        }
+        catch (err) {
+            throw err instanceof BackendError ? err : new BackendError(err);
+        }
+    }
+    /** 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)
+            return;
+        const sessionId = this.sessionId;
+        this.sessionId = undefined;
+        try {
+            await this.daemon.rollbackMutationSession({ sessionId });
+        }
+        catch {
+            // Unreachable daemon / already-expired session: the deadline rollback covers it.
+        }
+    }
+}
+/** The Postgres server tx: a REAL interactive transaction. Logical writes render to `$n` and run
+ *  LIVE against the open txn; raw `exec` runs live too (after `rewrite`); `row` reads the open txn
+ *  (read-your-writes). Ops append to an internally-serialized chain so order holds even when a legacy
+ *  sync mutator does not `await`; the backend drains the chain (`settle`) before the lmid upsert. */
+class PgLiveTx {
+    chain = Promise.resolve();
+    stmts = [];
+    q;
+    render;
+    rewrite;
+    idempotencyKey;
+    constructor(q, render, rewrite) {
+        this.q = q;
+        this.render = render;
+        this.rewrite = rewrite;
+    }
+    get statements() {
+        return this.stmts;
+    }
+    settle() {
+        return this.chain;
+    }
+    execLive(sql, params) {
+        this.chain = this.chain.then(async () => {
+            try {
+                await this.q.exec(sql, params);
+            }
+            catch (err) {
+                throw new BackendError(err);
+            }
+        });
+    }
+    exec(sql, params = []) {
+        const stmt = { sql: this.rewrite(sql), params };
+        this.stmts.push(stmt);
+        this.execLive(stmt.sql, params);
+    }
+    write(op) {
+        let rendered;
+        try {
+            rendered = renderOp(op, tableMeta(this.render, op.table), postgresDialect);
+        }
+        catch (err) {
+            return Promise.reject(err); // a validation error (business rejection), synchronous shape
+        }
+        if (rendered)
+            this.execLive(rendered.sql, rendered.params ?? []);
+        return this.chain;
+    }
+    insert(table, row) {
+        return this.write({ kind: "insert", table, row });
+    }
+    update(table, row) {
+        return this.write({ kind: "update", table, row });
+    }
+    upsert(table, row) {
+        return this.write({ kind: "upsert", table, row });
+    }
+    insertIgnore(table, row) {
+        return this.write({ kind: "insertIgnore", table, row });
+    }
+    delete(table, pk) {
+        return this.write({ kind: "delete", table, pk });
+    }
+    async row(table, pk) {
+        const meta = tableMeta(this.render, table);
+        const read = renderPointRead(table, pk, meta, postgresDialect); // validates before draining
+        await this.settle(); // read-your-writes: drain queued writes first
+        let rows;
+        try {
+            rows = await this.q.query(read.sql, read.params);
+        }
+        catch (err) {
+            throw new BackendError(err);
+        }
+        return rowToKeyed(rows[0], meta);
+    }
+    query() {
+        // The compiler's postgres dialect ships (@rindle/query-compiler); what remains is the §7
+        // 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"));
+    }
+}
+/**
+ * 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) {
     return {
-        apply({ envelope, statements, idempotencyKey }) {
-            const txn = { statements: [...statements], clientID: envelope.clientID, mid: envelope.mid };
-            if (idempotencyKey !== undefined)
-                txn.idempotencyKey = idempotencyKey;
-            return daemon.executeSqlTxn(txn);
+        dialect: sqliteDialect,
+        async runMutation({ envelope, render, run }) {
+            const tx = new DaemonLazyTx(render, daemon, envelope);
+            try {
+                await run(tx);
+            }
+            catch (err) {
+                // A begin-absorbed replay: the authoritative outcome already committed — answer it,
+                // whatever the body did with the unwind (§4.1; the latch, not the throw, decides).
+                if (tx.absorbed)
+                    return { accepted: true, output: tx.absorbed };
+                if (err instanceof BackendError) {
+                    await tx.rollbackSessionQuietly();
+                    throw err.driverError; // infra — never a user rejection
+                }
+                const reason = errMessage(err);
+                // Data first, watermark second: the rollback releases the single writer that the
+                // `/reject-mutation` lmid-only commit needs (§2.4 on the session path).
+                await tx.rollbackSessionQuietly();
+                const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+                return { accepted: false, reason, output };
+            }
+            if (tx.absorbed)
+                return { accepted: true, output: tx.absorbed };
+            if (tx.session) {
+                try {
+                    return { accepted: true, output: await tx.commitSession() };
+                }
+                catch (err) {
+                    if (err instanceof BackendError)
+                        throw err.driverError; // infra (client retries; dedup absorbs)
+                    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) };
         },
         reject({ envelope, reason }) {
             return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
@@ -124,16 +696,46 @@ ON CONFLICT ("client_id") DO UPDATE
  */
 export function postgresBackend(plugger, opts = {}) {
     const rewrite = opts.rewriteSql ?? ((sql) => sql);
-    const applyInTxn = (envelope, statements) => plugger.transaction(async (q) => {
-        for (const s of statements)
-            await q.exec(rewrite(s.sql), (s.params ?? []));
-        // ALWAYS — accepted or rejected — in this same transaction (§2.2, §2.4).
+    // A tagged business rejection escaping `plugger.transaction` — the plugger rolls the data back on
+    // any throw; this marker distinguishes "mutator said no" (reject) from an infra failure (rethrow).
+    class RejectSignal extends Error {
+    }
+    const lmidOnly = (envelope) => plugger.transaction(async (q) => {
         await q.exec(LMID_UPSERT, [envelope.clientID, envelope.mid]);
         return { applied: true, lmidAdvances: [{ clientID: envelope.clientID, lmid: envelope.mid }] };
     });
     return {
-        apply: ({ envelope, statements }) => applyInTxn(envelope, statements),
-        reject: ({ envelope }) => applyInTxn(envelope, []),
+        dialect: postgresDialect,
+        async runMutation({ envelope, render, run }) {
+            try {
+                const output = await plugger.transaction(async (q) => {
+                    const tx = new PgLiveTx(q, render, rewrite);
+                    try {
+                        await run(tx);
+                        await tx.settle(); // drain any un-awaited queued writes before the lmid stamp
+                    }
+                    catch (err) {
+                        if (err instanceof BackendError)
+                            throw err; // infra → rollback + propagate
+                        throw new RejectSignal(errMessage(err)); // business → rollback data, tag for §2.4
+                    }
+                    // ALWAYS on the accepted path, SAME transaction (§2.2): the lmid upsert commits with data.
+                    await q.exec(LMID_UPSERT, [envelope.clientID, envelope.mid]);
+                    return { applied: true, lmidAdvances: [{ clientID: envelope.clientID, lmid: envelope.mid }] };
+                });
+                return { accepted: true, output };
+            }
+            catch (err) {
+                if (err instanceof RejectSignal) {
+                    // Data rolled back; STILL advance lmid alone (§2.4 — the client's queue must drain).
+                    return { accepted: false, reason: err.message, output: await lmidOnly(envelope) };
+                }
+                if (err instanceof BackendError)
+                    throw err.driverError; // infra
+                throw err;
+            }
+        },
+        reject: ({ envelope }) => lmidOnly(envelope).then(() => undefined),
     };
 }
 /** Adapt a node-postgres `Pool` (or anything pool-shaped) to a {@link PostgresPlugger}:
@@ -256,6 +858,34 @@ export function registerQueries(queries) {
 export function defineApiMutators(mutators) {
     return mutators;
 }
+/**
+ * Bulk-register a SHARED (generator) mutator registry as server mutators — the mutator twin of
+ * {@link registerQueries} (which does the same for co-located `defineQuery` values). Each shared
+ * mutator carries its own arg validator (`shared(schema, gen)`), so this wraps every one with the
+ * UNIVERSAL server triad and nothing else: parse the UNTRUSTED wire args (its `.args`), map the server
+ * {@link MutationContext} to the shared {@link MutatorCtx} principal, and drive the SAME body the
+ * client predicts ({@link runSharedMutation}). The point is that a shared mutator whose server run
+ * adds NO authority beyond that triad needs no hand-written wrapper.
+ *
+ * Server-only AUTHORITY the client cannot predict (a title guard, an owner-gated cascade, a
+ * `NOT EXISTS` dedup) stays an explicit {@link ApiMutator} that OVERRIDES the auto-wrapped default —
+ * spread this first, then the overrides win by key:
+ *
+ * ```ts
+ * mutators: defineApiMutators({
+ *   ...sharedApiMutators(sharedMutators, (ctx) => ({ user: requireUser(ctx.user) })),
+ *   createIssue: withTitleGuard(sharedMutators.createIssue), // + server-only policy
+ *   deleteIssue: async (tx, raw, ctx) => { ... },            // raw owner-gated cascade
+ * }),
+ * ```
+ */
+export function sharedApiMutators(registry, principal) {
+    const out = {};
+    for (const [name, mutator] of Object.entries(registry)) {
+        out[name] = (tx, raw, ctx) => runSharedMutation(mutator, mutator.args.parse(raw), principal(ctx), tx);
+    }
+    return out;
+}
 export function queryResultToAst(result) {
     if (result && typeof result === "object" && "ast" in result && typeof result.ast === "function") {
         return result.ast();
@@ -342,6 +972,10 @@ export function createRindleApiServer(opts) {
     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);
+    // 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).
+    const renderIndex = opts.schema ? buildRenderIndex(opts.schema) : {};
     // Names that are ALSO configured pins — a lease for one is forced to a `pinned` policy (the lazy
     // floor, §4.1) so the first viewer to route to a follower warms it for late joiners.
     const pinnedNames = new Set((opts.pinnedQueries ?? []).map((p) => p.name));
@@ -413,33 +1047,37 @@ export function createRindleApiServer(opts) {
     const pushMutation = async (input) => {
         const context = { user: input.user, request: input.request };
         const mutator = opts.mutators?.[input.envelope.name];
+        // PRE-FLIGHT rejections — no txn, no data, `lmid` alone (the queue must still drain).
         if (!mutator)
             return reject(backend, input.envelope, `unknown mutator: ${input.envelope.name}`);
-        let sql;
         try {
             await assertAuthorized(opts.authorizeMutation, {
                 user: input.user,
                 envelope: input.envelope,
                 context,
             });
-            const tx = new CollectingSqlMutationTx();
-            const result = await mutator(tx, input.envelope.args, {
-                user: input.user,
-                envelope: input.envelope,
-                daemon: opts.daemon,
-                request: input.request,
-            });
-            sql = mutationResultToSqlTxn(result, tx);
         }
         catch (err) {
-            return reject(backend, input.envelope, String(err?.message ?? err));
+            return reject(backend, input.envelope, errMessage(err));
         }
-        const output = await backend.apply({
+        // Run the mutator INSIDE the backend's transaction. A throw from the mutator body is a business
+        // rejection (roll data back, advance `lmid`); a BackendError (DB failure) rejects this promise.
+        const outcome = await backend.runMutation({
             envelope: input.envelope,
-            statements: sql.statements,
-            idempotencyKey: sql.idempotencyKey,
+            render: renderIndex,
+            run: async (tx) => {
+                const result = await mutator(tx, input.envelope.args, {
+                    user: input.user,
+                    envelope: input.envelope,
+                    daemon: opts.daemon,
+                    request: input.request,
+                });
+                applyResultToTx(result, tx);
+            },
         });
-        return { accepted: true, rejected: false, output };
+        if (outcome.accepted)
+            return { accepted: true, rejected: false, output: outcome.output };
+        return { accepted: false, rejected: true, reason: outcome.reason, output: outcome.output };
     };
     const pushMutations = async (input) => {
         const out = [];
@@ -498,13 +1136,18 @@ export function createRindleApiServer(opts) {
             throw new Error(`assertPins: ${failures.length} failed — ${failures.join("; ")}`);
         }
     };
-    // The room write-authority gate (§5.3.1): endpoints are disabled until the app
-    // opts in with `authorizeRoom` — hosting an authority is never a default.
+    // 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.
+    const realtime = opts.realtime;
+    const roomAuthorizer = realtime
+        ? (realtime.authorize ?? defaultFlushGate(realtime.shellSecret))
+        : opts.authorizeRoom;
     const roomGate = async (context) => {
-        if (!opts.authorizeRoom) {
+        if (!roomAuthorizer) {
             throw new RindleApiError("forbidden", "room authority not configured", 403);
         }
-        await assertAuthorized(opts.authorizeRoom, context);
+        await assertAuthorized(roomAuthorizer, context);
     };
     // The store's verdict rides specific statuses + body shapes (fence / conflict /
     // identity) the room decodes — pass a daemon HTTP error through VERBATIM.
@@ -571,6 +1214,61 @@ export function createRindleApiServer(opts) {
                 return daemonVerdict(e);
             }
         },
+        handleRoomBootJson: async (body, context) => {
+            if (!realtime) {
+                throw new RindleApiError("forbidden", "realtime not configured", 403);
+            }
+            await assertAuthorized(realtime.authorizeBoot ?? defaultBootGate(realtime.shellSecret), context);
+            const msg = parseObject(body, "room-boot request");
+            const doc = parseString(msg.doc, "doc");
+            if (msg.instance !== undefined)
+                parseString(msg.instance, "instance"); // diagnostic identity only
+            const ast = queryResultToAst(await realtime.resolveFootprint(doc, context));
+            const claim = opts.daemon.claimRoomEpoch?.bind(opts.daemon);
+            if (!claim) {
+                throw new Error("the configured daemon client does not implement claimRoomEpoch");
+            }
+            try {
+                // Claim FIRST (§2.5): the lease below is minted for THIS placement, so a boot
+                // that loses the epoch race learns it here, before any materialization exists.
+                const { epoch } = await claim({ doc });
+                const lease = await opts.daemon.materialize({
+                    ast,
+                    // The room's upstream leg IS the normalized protocol (§3) — never the app's
+                    // viewer `mode`.
+                    mode: "normalized",
+                    leaseTtlMs: realtime.upstreamLeaseTtlMs ?? opts.leaseTtlMs,
+                });
+                const headers = realtime.mintFlushHeaders
+                    ? await realtime.mintFlushHeaders({ doc, epoch })
+                    : {
+                        [ROOM_FLUSH_CREDENTIAL_HEADER]: await mintRoomFlushCredential({
+                            shellSecret: realtime.shellSecret,
+                            doc,
+                            epoch,
+                        }),
+                    };
+                const res = {
+                    epoch,
+                    upstreamLeaseToken: lease.leaseToken,
+                    flush: {
+                        urls: {
+                            apply: routes.applyRowChangeTxn,
+                            claim: routes.claimRoomEpoch,
+                            lmids: routes.roomLmids,
+                        },
+                        headers,
+                    },
+                };
+                const upstreamWsEndpoint = realtime.upstreamWsEndpoint ?? lease.wsEndpoint;
+                if (upstreamWsEndpoint !== undefined)
+                    res.upstreamWsEndpoint = upstreamWsEndpoint;
+                return { status: 200, body: res };
+            }
+            catch (e) {
+                return daemonVerdict(e);
+            }
+        },
         handleQueryJson: (body, context) => {
             const msg = parseObject(body, "query request");
             return createQueryLease({
@@ -605,22 +1303,61 @@ export function createRindleApiServer(opts) {
         },
     };
 }
-class CollectingSqlMutationTx {
-    stmts = [];
-    get statements() {
-        return this.stmts;
-    }
-    exec(sql, params = []) {
-        this.stmts.push({ sql, params });
+/** Run a SHARED generator mutator (the SAME body the client predicts) against a live server
+ *  transaction (MUTATORS-ISOMORPHIC): bind the tier-agnostic {@link isoTx} factory and drive it —
+ *  each yielded logical op renders + runs against `tx` (dialect SQL, per backend), each `tx.row`
+ *  suspends for read-your-writes, and `tx.all` fans out. A server mutator uses this to delegate its
+ *  write body after parsing untrusted args and applying its server-only authority (principal, policy).
+ *  A mutator-body throw remains a business rejection; a DB failure propagates as infra. */
+export function runSharedMutation(mutator, args, ctx, tx) {
+    return driveMutationAsync(mutator(isoTx, args, ctx), {
+        apply: (op) => applyOpToServerTx(tx, op),
+        read: (table, pk) => tx.row(table, pk),
+        query: async (q) => {
+            // The shared-seam contract is ALWAYS an array of rows: the client's `WriteTxn.query` returns
+            // an array even for a root `.one()` (the root unwrap is the Store's `materialize()`, not the
+            // in-mutator read — rust/src/wasm/db.rs). The server's `tx.query` returns a scalar (object|null)
+            // for a `.one()` root, so normalize it to `[]`/`[row]` here — one body sees the same shape on
+            // both tiers. (Postgres backend: `tx.query` rejects until POSTGRES-READ-COMPILER-DESIGN.md
+            // Phase B; the daemon/SQLite backend compiles + rides the open session — DAEMON §5.4.)
+            const ast = q.ast();
+            const res = await tx.query(ast);
+            if (ast.one === true)
+                return res == null ? [] : [res];
+            return (res ?? []);
+        },
+    });
+}
+/** Run one logical {@link MutationOp} (yielded by a shared generator mutator) against the live server
+ *  write surface — the SAME async methods a plain async mutator calls (they render dialect SQL and
+ *  execute/accumulate per backend). */
+function applyOpToServerTx(tx, op) {
+    switch (op.kind) {
+        case "insert":
+            return tx.insert(op.table, op.row);
+        case "upsert":
+            return tx.upsert(op.table, op.row);
+        case "insertIgnore":
+            return tx.insertIgnore(op.table, op.row);
+        case "update":
+            return tx.update(op.table, op.row);
+        case "delete":
+            return tx.delete(op.table, op.pk);
     }
 }
-function mutationResultToSqlTxn(result, tx) {
-    if (Array.isArray(result))
-        return { statements: result };
-    if (result && typeof result === "object" && "statements" in result) {
-        return { statements: result.statements, idempotencyKey: result.idempotencyKey };
+/** 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. */
+function applyResultToTx(result, tx) {
+    if (!result)
+        return;
+    const statements = Array.isArray(result) ? result : result.statements;
+    for (const s of statements)
+        tx.exec(s.sql, s.params);
+    if (!Array.isArray(result) && result.idempotencyKey !== undefined) {
+        tx.idempotencyKey = result.idempotencyKey;
     }
-    return { statements: [...tx.statements] };
 }
 async function assertAuthorized(authorizer, input) {
     if (!authorizer)
@@ -629,6 +1366,65 @@ async function assertAuthorized(authorizer, input) {
     if (result === false)
         throw new RindleApiError("forbidden", "rindle request forbidden", 403);
 }
+/** The default flush-trio gate: verify the default epoch-bound credential from the request
+ *  header. The two refusal messages are deliberately distinct — "missing" is a transport wiring
+ *  bug (no `context.request`), "refused" is an invalid credential. */
+function defaultFlushGate(shellSecret) {
+    return async (context) => {
+        const credential = requestHeader(context.request, ROOM_FLUSH_CREDENTIAL_HEADER);
+        if (!credential) {
+            throw new RindleApiError("forbidden", `missing ${ROOM_FLUSH_CREDENTIAL_HEADER} header — is the transport passing its incoming request as context.request?`, 403);
+        }
+        try {
+            await verifyRoomFlushCredential(credential, shellSecret);
+        }
+        catch (e) {
+            throw new RindleApiError("forbidden", `flush credential refused: ${errMessage(e)}`, 403);
+        }
+    };
+}
+/** The default `/room-boot` gate: `Authorization: Bearer <shell secret>` (README contract),
+ *  compared constant-time. */
+function defaultBootGate(shellSecret) {
+    return (context) => {
+        const auth = requestHeader(context.request, "authorization");
+        const bearer = auth && /^bearer\s/i.test(auth) ? auth.replace(/^bearer\s+/i, "") : undefined;
+        if (!bearer || !timingSafeEqualStr(bearer, shellSecret)) {
+            throw new RindleApiError("forbidden", "room-boot: shell secret refused", 403);
+        }
+    };
+}
+/** Best-effort header extraction from whatever the transport put in `context.request`: a Fetch
+ *  `Request` (`headers.get`), a node `IncomingMessage` (lowercased header map), or a plain
+ *  `{headers: {...}}`. `undefined` when there is no request or no such header. */
+function requestHeader(request, name) {
+    if (!request || typeof request !== "object")
+        return undefined;
+    const headers = request.headers;
+    if (!headers || typeof headers !== "object")
+        return undefined;
+    if (typeof headers.get === "function") {
+        return headers.get(name) ?? undefined;
+    }
+    const map = headers;
+    const v = map[name.toLowerCase()] ?? map[name];
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v) && typeof v[0] === "string")
+        return v[0];
+    return undefined;
+}
+/** Constant-time string equality (a length mismatch fails fast — length is not the secret). */
+function timingSafeEqualStr(a, b) {
+    const ab = new TextEncoder().encode(a);
+    const bb = new TextEncoder().encode(b);
+    if (ab.length !== bb.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < ab.length; i++)
+        diff |= ab[i] ^ bb[i];
+    return diff === 0;
+}
 async function resolvePolicy(policy, input) {
     if (!policy)
         return { kind: "whileSubscribed" };