@rindle/api-server 0.2.0 → 0.4.2

package/dist/index.js

@@ -1,7 +1,19 @@
+import { driveMutationAsync, isoTx } 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",
     mutate: "/api/rindle/mutate",
+    // The room write-authority host (RINDLE-REALTIME-DESIGN.md §5.3.1): the room's
+    // SOLE flush counterpart — the store's own handler is private ingress behind these.
+    applyRowChangeTxn: "/api/rindle/apply-row-change-txn",
+    claimRoomEpoch: "/api/rindle/claim-room-epoch",
+    roomLmids: "/api/rindle/room-lmids",
 };
 export class RindleApiError extends Error {
     code;
@@ -51,9 +63,53 @@ 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);
     }
+    claimRoomEpoch(input) {
+        const claim = this.writes.claimRoomEpoch?.bind(this.writes);
+        if (!claim)
+            return Promise.reject(new Error("the write master lacks claimRoomEpoch"));
+        return claim(input);
+    }
+    roomLmids(input) {
+        const lmids = this.writes.roomLmids?.bind(this.writes);
+        if (!lmids)
+            return Promise.reject(new Error("the write master lacks roomLmids"));
+        return lmids(input);
+    }
     migrate(input) {
         return this.writes.migrate(input);
     }
@@ -68,6 +124,626 @@ 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;
+        out[name] = { columns, pkNames: [...meta.primaryKey], types };
+    }
+    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 column (an insert carries a whole row — there are no defaults). 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.columns : 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).
+    const bind = (c, row) => {
+        params.push(encode(dialect, row[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");
+    }
+}
+/**
+ * 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 {
+        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 });
+        },
+    };
+}
+/** 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")
+VALUES ($1, $2)
+ON CONFLICT ("client_id") DO UPDATE
+  SET "last_mutation_id" = GREATEST("_rindle_client_mutations"."last_mutation_id", EXCLUDED."last_mutation_id")`;
+/**
+ * The BYO-Postgres {@link MutationBackend} (`BYO-POSTGRES-LMID-CONTRACT-DESIGN.md` §6.3): one PG
+ * transaction runs the mutator's statements and ALWAYS upserts `_rindle_client_mutations` —
+ * the upsert sits outside any acceptance guard by construction, so the §2.4 footgun (a rejection
+ * that forgets to advance `lmid` and wedges the client's pending queue) cannot be written.
+ *
+ * Confirmation does NOT come from this call's response: the lmid row rides the same PG commit
+ * through CDC → relay → follower and reaches the client in the same coherent release as the
+ * data (§8.2 relocated upstream). A rejection's `reason` still returns on the HTTP reply, but
+ * nothing rejection-shaped travels the replication path — the optimistic prediction snaps back
+ * when the advanced `lmid` arrives.
+ */
+export function postgresBackend(plugger, opts = {}) {
+    const rewrite = opts.rewriteSql ?? ((sql) => sql);
+    // 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 {
+        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}:
+ *  one client per transaction, `BEGIN`/`COMMIT` bracketing, `ROLLBACK` + rethrow on failure. */
+export function pgPoolPlugger(pool) {
+    return {
+        async transaction(fn) {
+            const client = await pool.connect();
+            try {
+                await client.query("BEGIN");
+                const q = {
+                    exec: async (sql, params) => {
+                        await client.query(sql, params);
+                    },
+                    query: async (sql, params) => (await client.query(sql, params)).rows,
+                };
+                const out = await fn(q);
+                await client.query("COMMIT");
+                return out;
+            }
+            catch (err) {
+                try {
+                    await client.query("ROLLBACK");
+                }
+                catch {
+                    // the connection may already be unusable; the original error is the one that matters
+                }
+                throw err;
+            }
+            finally {
+                client.release();
+            }
+        },
+    };
+}
+/**
+ * Rewrite SQLite-style `?` positional placeholders to Postgres `$1..$n`, for mutators written
+ * once and run against either backend (pass as {@link PostgresBackendOptions.rewriteSql}).
+ * Skips `'…'` string literals (with `''` escapes), `"…"` quoted identifiers, `--` line comments,
+ * and non-nested C-style block comments. Do not mix `?` and `$n` styles in one statement.
+ */
+export function questionToDollarParams(sql) {
+    let out = "";
+    let n = 0;
+    let i = 0;
+    while (i < sql.length) {
+        const c = sql[i];
+        if (c === "?") {
+            out += `$${++n}`;
+            i += 1;
+        }
+        else if (c === "'" || c === '"') {
+            // consume the quoted span; a doubled quote is an escape inside it
+            const quote = c;
+            let j = i + 1;
+            while (j < sql.length) {
+                if (sql[j] === quote) {
+                    if (sql[j + 1] === quote)
+                        j += 2;
+                    else
+                        break;
+                }
+                else {
+                    j += 1;
+                }
+            }
+            out += sql.slice(i, j + 1);
+            i = j + 1;
+        }
+        else if (c === "-" && sql[i + 1] === "-") {
+            const end = sql.indexOf("\n", i);
+            const j = end === -1 ? sql.length : end;
+            out += sql.slice(i, j);
+            i = j;
+        }
+        else if (c === "/" && sql[i + 1] === "*") {
+            const end = sql.indexOf("*/", i + 2);
+            const j = end === -1 ? sql.length : end + 2;
+            out += sql.slice(i, j);
+            i = j;
+        }
+        else {
+            out += c;
+            i += 1;
+        }
+    }
+    return out;
+}
 export function defineApiQueries(queries) {
     return queries;
 }
@@ -102,15 +778,124 @@ 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();
     }
     return result;
 }
+/**
+ * Dump every registered named query's wire AST — feeder 1 ("exemplar enumeration") of
+ * `rindle indices suggest` (docs/INDEXING.md applied mechanically to the query set).
+ *
+ * Because named queries are FUNCTIONS of `(args, ctx)`, one query can build structurally
+ * different ASTs on different args; each exemplar invocation contributes its shape, and shapes
+ * that differ only in literal values (a limit, a filter string) dedupe to one entry. A query
+ * with no configured exemplars is invoked once with no args. The registry is the app's whole
+ * server-side query surface, so the resulting document is the complete static shape set —
+ * modulo arg-value-dependent branches, which need an exemplar (or runtime shape recording) to
+ * surface.
+ */
+export async function dumpQueryShapes(opts) {
+    const tables = Object.values(opts.schema.tables)
+        // Local-only tables live in the browser's memory source, never a TableSource — no indexes.
+        .filter((t) => t.local !== true)
+        .map((t) => ({ name: t.name, primaryKey: [...t.primaryKey] }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const queries = [];
+    for (const [name, query] of Object.entries(opts.queries).sort(([a], [b]) => a.localeCompare(b))) {
+        const seen = new Set();
+        for (const ex of opts.exemplars?.[name] ?? [{}]) {
+            const ast = queryResultToAst(await query({ user: ex.user }, ex.args));
+            const key = JSON.stringify(normalizeShape(ast));
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            queries.push({ name: seen.size > 1 ? `${name}#${seen.size}` : name, ast });
+        }
+    }
+    return { tables, queries };
+}
+/** The literal-stripped structure of an AST — the dedupe key for {@link dumpQueryShapes}. */
+function normalizeShape(ast) {
+    return {
+        table: ast.table,
+        where: ast.where && normalizeCondition(ast.where),
+        related: ast.related?.map((r) => ({
+            correlation: r.correlation,
+            subquery: normalizeShape(r.subquery),
+        })),
+        orderBy: ast.orderBy,
+        limit: ast.limit !== undefined,
+        start: ast.start
+            ? { keys: Object.keys(ast.start.row).sort(), exclusive: ast.start.exclusive }
+            : undefined,
+        aggregate: ast.aggregate,
+        groupBy: ast.groupBy,
+        having: ast.having && normalizeCondition(ast.having),
+        one: ast.one,
+    };
+}
+function normalizeCondition(c) {
+    switch (c.type) {
+        case "simple":
+            return {
+                type: c.type,
+                op: c.op,
+                left: c.left,
+                right: c.right.type === "literal" ? { type: "literal" } : c.right,
+            };
+        case "and":
+        case "or":
+            return { type: c.type, conditions: c.conditions.map(normalizeCondition) };
+        case "correlatedSubquery":
+            return {
+                type: c.type,
+                op: c.op,
+                related: {
+                    correlation: c.related.correlation,
+                    subquery: normalizeShape(c.related.subquery),
+                },
+            };
+    }
+}
 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);
+    // 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));
@@ -182,33 +967,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(opts.daemon, input.envelope, `unknown mutator: ${input.envelope.name}`);
-        let sql;
+            return reject(backend, input.envelope, `unknown mutator: ${input.envelope.name}`);
         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(opts.daemon, input.envelope, String(err?.message ?? err));
+            return reject(backend, input.envelope, errMessage(err));
         }
-        const output = await opts.daemon.executeSqlTxn({
-            ...sql,
-            clientID: input.envelope.clientID,
-            mid: input.envelope.mid,
+        // 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,
+            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 = [];
@@ -267,6 +1056,29 @@ 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.
+    const roomGate = async (context) => {
+        if (!opts.authorizeRoom) {
+            throw new RindleApiError("forbidden", "room authority not configured", 403);
+        }
+        await assertAuthorized(opts.authorizeRoom, context);
+    };
+    // The store's verdict rides specific statuses + body shapes (fence / conflict /
+    // identity) the room decodes — pass a daemon HTTP error through VERBATIM.
+    const daemonVerdict = (e) => {
+        if (e instanceof DaemonHttpError) {
+            let body;
+            try {
+                body = JSON.parse(e.body);
+            }
+            catch {
+                body = { error: e.body };
+            }
+            return { status: e.status, body };
+        }
+        throw e;
+    };
     return {
         routes,
         createQueryLease,
@@ -274,6 +1086,49 @@ export function createRindleApiServer(opts) {
         assertPins,
         pushMutation,
         pushMutations,
+        handleApplyRowChangeTxnJson: async (body, context) => {
+            await roomGate(context);
+            const msg = parseObject(body, "row-change txn");
+            try {
+                const out = await opts.daemon.applyRowChangeTxn(msg);
+                return { status: 200, body: out };
+            }
+            catch (e) {
+                return daemonVerdict(e);
+            }
+        },
+        handleClaimRoomEpochJson: async (body, context) => {
+            await roomGate(context);
+            const msg = parseObject(body, "claim-room-epoch request");
+            const doc = parseString(msg.doc, "doc");
+            const claim = opts.daemon.claimRoomEpoch?.bind(opts.daemon);
+            if (!claim) {
+                throw new Error("the configured daemon client does not implement claimRoomEpoch");
+            }
+            try {
+                return { status: 200, body: await claim({ doc }) };
+            }
+            catch (e) {
+                return daemonVerdict(e);
+            }
+        },
+        handleRoomLmidsJson: async (body, context) => {
+            await roomGate(context);
+            const msg = parseObject(body, "room-lmids request");
+            if (!Array.isArray(msg.clients) || msg.clients.some((c) => typeof c !== "string")) {
+                throw new RindleApiError("bad-request", "clients must be an array of strings", 400);
+            }
+            const lmids = opts.daemon.roomLmids?.bind(opts.daemon);
+            if (!lmids) {
+                throw new Error("the configured daemon client does not implement roomLmids");
+            }
+            try {
+                return { status: 200, body: await lmids({ clients: msg.clients }) };
+            }
+            catch (e) {
+                return daemonVerdict(e);
+            }
+        },
         handleQueryJson: (body, context) => {
             const msg = parseObject(body, "query request");
             return createQueryLease({
@@ -308,22 +1163,48 @@ 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),
+    });
+}
+/** 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)
@@ -364,8 +1245,8 @@ function queryLeaseResponse(out) {
 function errMessage(reason) {
     return String(reason?.message ?? reason);
 }
-async function reject(daemon, envelope, reason) {
-    const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+async function reject(backend, envelope, reason) {
+    const output = await backend.reject({ envelope, reason });
     return { accepted: false, rejected: true, reason, output };
 }
 function parseObject(value, label) {