@rindle/api-server 0.2.0 → 0.4.2

package/src/index.ts

@@ -1,5 +1,25 @@
-import type { Ast, MutationEnvelope, NamedQuery, Query } from "@rindle/client";
+import { driveMutationAsync, isoTx } from "@rindle/client";
 import type {
+  Ast,
+  ColType,
+  Condition,
+  KeyedRow,
+  MutationEnvelope,
+  MutationOp,
+  MutatorCtx,
+  NamedQuery,
+  Query,
+  Schema,
+  SharedMutator,
+  SharedMutatorWithArgs,
+  ServerWriteTx,
+} from "@rindle/client";
+import { DaemonHttpError } from "@rindle/daemon-client";
+import { compile as compileQueryAst } from "@rindle/query-compiler";
+import type { Catalog, ColumnType as QueryColumnType, TableSchema } from "@rindle/query-compiler";
+import type {
+  ClaimRoomEpochInput,
+  ClaimRoomEpochOutput,
   DematerializeInput,
   DematerializeOutput,
   MaterializationPolicy,
@@ -9,9 +29,16 @@ import type {
   MigrateOutput,
   MutationRejection,
   MutationRejectionOutput,
+  MutationSessionBegin,
+  MutationSessionBeginOutput,
+  MutationSessionExec,
+  MutationSessionQuery,
+  MutationSessionRef,
   QueryOnceInput,
   QueryOnceOutput,
   RindleDaemonClient,
+  RoomLmidsInput,
+  RoomLmidsOutput,
   RowChangeTxn,
   RowChangeTxnOutput,
   SqlRead,
@@ -23,10 +50,21 @@ import type {
   WireValue,
 } from "@rindle/daemon-client";
 
+// 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 type { ArgSchema, IsoTx, MutationGen, MutatorCtx, SharedMutator, SharedMutatorWithArgs } 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",
 } as const;
 
 export type MaybePromise<T> = T | PromiseLike<T>;
@@ -72,14 +110,39 @@ export interface MutationContext<User> {
   request?: unknown;
 }
 
+/** The legacy raw-SQL escape hatch (still the surface for relational/authority statements a keyed op
+ *  can't express — an owner-gated cascade, a `NOT EXISTS` dedup). `exec` accumulates on the daemon
+ *  backend and executes live on the Postgres backend; `statements` is the collected raw list. */
 export interface SqlMutationTx {
   exec(sql: string, params?: WireValue[]): void;
   readonly statements: readonly SqlStatement[];
 }
 
+/** The write handle a server mutator runs against — the ASYNC twin of the client's `MutationTx`. It
+ *  is both the isomorphic {@link ServerWriteTx} logical surface (insert/update/upsert/insertIgnore/
+ *  delete/row, rendered to dialect SQL) AND the legacy {@link SqlMutationTx} raw escape hatch. Both
+ *  backends run reads through the OPEN transaction (read-your-writes): the Postgres backend executes
+ *  everything live; the daemon backend accumulates writes and lazily upgrades to an interactive
+ *  mutation session at the first read (DAEMON-INTERACTIVE-TXN-DESIGN.md §5). */
+export interface ServerMutationTx extends ServerWriteTx, SqlMutationTx {
+  /** Run a full query (a fluent `Query` or its wire `Ast`) INSIDE the open transaction —
+   *  read-your-writes, like {@link ServerWriteTx.row} but for arbitrary shapes. Returns the
+   *  parsed nested result tree: an array for a plural root, an object or `null` for a `.one()`
+   *  root, with cells in their raw SQLite storage-class representations (the same vocabulary
+   *  `row` speaks). Daemon backend: compiled by `@rindle/query-compiler`'s sqlite dialect (bind
+   *  params, NO casts — §5.4) and executed through the mutation session. Postgres backend: lands
+   *  with the read-compiler catalog integration (POSTGRES-READ-COMPILER-DESIGN.md Phase B). */
+  query(q: Ast | Query<any, any, any>): Promise<unknown>;
+}
+
 export type ApiMutatorResult = void | SqlStatement[] | SqlTxn;
+/** A server mutator: a plain async function against the live {@link ServerMutationTx}. Two ways to
+ *  write one (MUTATORS-ISOMORPHIC): drive it directly (the raw escape hatch — an owner-gated cascade,
+ *  a `NOT EXISTS` dedup — plus a returned `SqlStatement[]`/`SqlTxn`), OR delegate to a SHARED generator
+ *  (the SAME body the client predicts) via {@link runSharedMutation}, keeping only the server-only
+ *  authority (arg parse, principal, policy) in the wrapper. */
 export type ApiMutator<User, Args> = (
-  tx: SqlMutationTx,
+  tx: ServerMutationTx,
   args: Args,
   ctx: MutationContext<User>,
 ) => MaybePromise<ApiMutatorResult>;
@@ -130,6 +193,47 @@ export interface QueryReadResponse {
   wsEndpoint?: string;
 }
 
+/** The context a {@link MutationBackend} needs to run one mutation inside its transaction. */
+export interface MutationRunInput {
+  envelope: MutationEnvelope;
+  /** Schema-derived render metadata (from {@link RindleApiServerOptions.schema}). A logical op on a
+   *  table absent here throws loudly — never a silent dropped write. `{}` when no schema is set. */
+  render: RenderIndex;
+  /** Invoke the (authorized) mutator against the backend-provided tx. A THROW that is NOT a
+   *  {@link BackendError} is a BUSINESS rejection (roll the data back, then advance `lmid` alone,
+   *  §2.4); a {@link BackendError} (a DB-layer failure) is INFRA and rejects the returned promise. */
+  run(tx: ServerMutationTx): Promise<void>;
+}
+
+/** The result of {@link MutationBackend.runMutation}: either the data+lmid committed together, or a
+ *  business rejection whose data was rolled back but whose `lmid` still advanced (§2.4). */
+export type MutationOutcome =
+  | { accepted: true; output: SqlTxnOutput }
+  | { accepted: false; reason: string; output?: unknown };
+
+/**
+ * Where a mutation runs and who stamps `lmid` — the seam that makes the mutator authoring surface
+ * backend-agnostic (`BYO-POSTGRES-LMID-CONTRACT-DESIGN.md` §6; MUTATORS-ISOMORPHIC plan). Two impls
+ * ship: {@link daemonBackend} (the default — writes accumulate, one batch to the daemon which stamps
+ * `lmid` co-transactionally) and {@link postgresBackend} (a REAL interactive PG transaction — writes
+ * and reads execute live, `lmid` committed in the same txn, confirmation riding the CDC loop down).
+ *
+ * The load-bearing invariant is that a mutation ALWAYS advances the client's `last_mutation_id`:
+ * - `runMutation` runs the mutator inside the backend's transaction; on success it advances `lmid`
+ *   to `envelope.mid` in the SAME atomic unit (OPTIMISTIC-WRITES-DESIGN.md §8.2); on a BUSINESS
+ *   rejection it rolls the data back but STILL advances `lmid` (§2.4 — else the client's pending
+ *   queue never drains and the optimistic stack wedges).
+ * - `reject` is the pre-flight path (unknown mutator, failed authorization): NO data, `lmid` alone.
+ * - An infrastructure failure THROWS from `runMutation` — never a user rejection (the client
+ *   retries; mid dedup absorbs any applied prefix).
+ */
+export interface MutationBackend {
+  /** The SQL dialect this backend renders logical ops to (drives placeholder style). */
+  readonly dialect: SqlDialect;
+  runMutation(input: MutationRunInput): Promise<MutationOutcome>;
+  reject(input: { envelope: MutationEnvelope; reason: string }): Promise<unknown>;
+}
+
 export interface PushMutationRequest<User> {
   user: User;
   envelope: MutationEnvelope;
@@ -150,6 +254,18 @@ export interface RindleApiRoutes {
   query: string;
   read: string;
   mutate: string;
+  applyRowChangeTxn: string;
+  claimRoomEpoch: string;
+  roomLmids: string;
+}
+
+/** A room-host reply the transport writes VERBATIM (`status` + JSON `body`): the
+ *  daemon's fence/conflict/identity semantics ride specific statuses and body shapes
+ *  the room's `httpAuthority` decodes, so this endpoint trio can't run through the
+ *  throw-on-error result shapes the viewer endpoints use. */
+export interface RoomHostResponse {
+  status: number;
+  body: unknown;
 }
 
 /** A named query to keep permanently materialized (warm with zero subscribers). */
@@ -168,11 +284,25 @@ export interface PinFanout {
 
 export interface RindleApiServerOptions<User> {
   daemon: RindleDaemonClient;
+  /** Where mutations are applied and `lmid` is stamped ({@link MutationBackend}). Default:
+   *  `daemonBackend(daemon)` — exactly today's behavior. Pass `postgresBackend(...)` when
+   *  Postgres is the source of truth (the daemon leg then serves only the read side). */
+  backend?: MutationBackend;
+  /** The typed schema (`createSchema`/`refineSchema`). Required only when a mutator uses the LOGICAL
+   *  write vocabulary (`tx.insert`/`update`/`upsert`/`insertIgnore`/`delete`/`row`) — it drives the
+   *  dialect SQL renderer (column order, pk, quoting). A logical op with no schema configured throws
+   *  loudly. Pure raw-`tx.exec` mutators do not need it. */
+  schema?: Schema;
   queries?: ApiQueries<User>;
   runQuery?: RunQuery<User>;
   mutators?: ApiMutators<User>;
   authorizeQuery?: Authorizer<AuthorizeQueryInput<User>>;
   authorizeMutation?: Authorizer<AuthorizeMutationInput<User>>;
+  /** The room write-authority gate (§5.3.1): validates the caller is a placed room —
+   *  the epoch-bound flush credential rides `context.request`, and what it means is
+   *  the app's to define. The room endpoints are DISABLED (403) until this is set:
+   *  hosting a write authority is an explicit opt-in, never a default. */
+  authorizeRoom?: Authorizer<ApiContext<User>>;
   routes?: Partial<RindleApiRoutes>;
   mode?: StreamMode;
   materializationPolicy?:
@@ -241,6 +371,18 @@ export interface RindleApiServer<User> {
     body: unknown,
     context: ApiContext<User>,
   ): Promise<PushMutationResponse | PushMutationResponse[]>;
+  /** The room's flush (§5.3.1): gate on `authorizeRoom`, forward the txn to the write
+   *  authority, and pass the store's verdict through VERBATIM — `200 {applied, cv}`,
+   *  `409 {error:"fenced"|"conflict", …}`, or the loud identity `500`. Write
+   *  `status` + `body` as-is; the room's `httpAuthority` decodes them. */
+  handleApplyRowChangeTxnJson(
+    body: unknown,
+    context: ApiContext<User>,
+  ): Promise<RoomHostResponse>;
+  /** Claim the next placement epoch for a doc (§2.5), same gate + envelope. */
+  handleClaimRoomEpochJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
+  /** The room's boot probe (§3.3), same gate + envelope. */
+  handleRoomLmidsJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
 }
 
 export type RindleApiErrorCode = "bad-request" | "forbidden" | "not-found" | "rejected";
@@ -297,9 +439,46 @@ export class SplitDaemonClient implements RindleDaemonClient {
   rejectMutation(input: MutationRejection): Promise<MutationRejectionOutput> {
     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: MutationSessionBegin): Promise<MutationSessionBeginOutput> {
+    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: MutationSessionExec): Promise<unknown> {
+    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: MutationSessionQuery): Promise<SqlReadOutput> {
+    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: MutationSessionRef): Promise<SqlTxnOutput> {
+    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: MutationSessionRef): Promise<unknown> {
+    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: RowChangeTxn): Promise<RowChangeTxnOutput> {
     return this.writes.applyRowChangeTxn(input);
   }
+  claimRoomEpoch(input: ClaimRoomEpochInput): Promise<ClaimRoomEpochOutput> {
+    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: RoomLmidsInput): Promise<RoomLmidsOutput> {
+    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: MigrateInput): Promise<MigrateOutput> {
     return this.writes.migrate(input);
   }
@@ -316,6 +495,688 @@ export class SplitDaemonClient implements RindleDaemonClient {
   }
 }
 
+// --------------------------------------------------------------------------- dialect SQL renderer
+//
+// A logical {@link MutationOp} → dialect `SqlStatement`. The whole per-dialect delta is the
+// PLACEHOLDER STYLE (`?` vs `$n`): identifiers are always double-quoted (SQLite tolerates it, PG
+// requires it — `user` is reserved, camelCase folds), and upserts use portable `ON CONFLICT` (both
+// engines). So `sqliteDialect`/`postgresDialect` differ only in `placeholder`.
+
+/** A SQL dialect for the logical mutation renderer. */
+export interface SqlDialect {
+  readonly name: "sqlite" | "postgres";
+  /** Render the i-th (1-based) bind placeholder. sqlite: `?`; postgres: `$i`. */
+  placeholder(oneBased: number): string;
+  /** Optional value coercion hook (e.g. a future SQLite `0/1` boolean). Default: identity. */
+  encodeValue?(v: WireValue, type: ColType): WireValue;
+}
+
+export const sqliteDialect: SqlDialect = { name: "sqlite", placeholder: () => "?" };
+export const postgresDialect: SqlDialect = { name: "postgres", placeholder: (i) => `$${i}` };
+
+/** Per-table metadata the renderer needs (all reachable from a `TableMeta`). */
+export interface TableRenderMeta {
+  /** Columns in schema (wire) order — the stable INSERT column list + completeness check. */
+  columns: string[];
+  /** Primary-key column NAMES — the WHERE / ON CONFLICT target / SET partition. */
+  pkNames: string[];
+  /** Column name → declared type (only consulted by {@link SqlDialect.encodeValue}). */
+  types: Record<string, ColType>;
+}
+
+export type RenderIndex = Record<string, TableRenderMeta>;
+
+/** Build the {@link RenderIndex} from a typed schema (`schema.tables[name]` is a `TableMeta`). */
+export function buildRenderIndex(schema: Schema): RenderIndex {
+  const out: RenderIndex = {};
+  const tables = (schema as unknown as { tables: Record<string, { columns: Record<string, { type: ColType }>; primaryKey: readonly string[] }> }).tables;
+  for (const name of Object.keys(tables)) {
+    const meta = tables[name];
+    const columns = Object.keys(meta.columns);
+    const types: Record<string, ColType> = {};
+    for (const c of columns) types[c] = meta.columns[c].type;
+    out[name] = { columns, pkNames: [...meta.primaryKey], types };
+  }
+  return out;
+}
+
+const quoteIdent = (name: string): string => `"${name.replace(/"/g, '""')}"`;
+
+function tableMeta(render: RenderIndex, table: string): TableRenderMeta {
+  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: string, obj: KeyedRow, meta: TableRenderMeta, full: boolean): void {
+  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: SqlDialect, v: WireValue, type: ColType): WireValue =>
+  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: MutationOp, meta: TableRenderMeta, dialect: SqlDialect): SqlStatement | null {
+  const t = quoteIdent(op.table);
+  const params: WireValue[] = [];
+  // Bind a value and return its placeholder at the correct 1-based index (post-push length).
+  const bind = (c: string, row: KeyedRow): string => {
+    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: string, pk: KeyedRow, meta: TableRenderMeta, dialect: SqlDialect): SqlStatement {
+  checkColumns(table, pk, meta, false);
+  const params: WireValue[] = [];
+  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: Record<string, unknown> | undefined, meta: TableRenderMeta): KeyedRow | undefined {
+  if (!row) return undefined;
+  const out: KeyedRow = {};
+  for (const c of meta.columns) out[c] = row[c] as WireValue;
+  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 {
+  readonly driverError: unknown;
+  constructor(driverError: unknown) {
+    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: RenderIndex, root: Ast): Catalog {
+  const tables: Record<string, TableSchema> = {};
+  const ensure = (table: string): TableSchema => {
+    const existing = tables[table];
+    if (existing) return existing;
+    const meta = tableMeta(render, table);
+    const columnTypes: Record<string, QueryColumnType> = {};
+    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: Condition | undefined): void => {
+    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: Ast): void => {
+    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 implements ServerMutationTx {
+  /** Pre-upgrade: the accumulated batch/prefix. Post-upgrade: writes buffered for the next flush. */
+  private readonly stmts: SqlStatement[] = [];
+  private readonly render: RenderIndex;
+  private readonly daemon: RindleDaemonClient;
+  private readonly envelope: MutationEnvelope;
+  private sessionId?: string;
+  /** The begin-absorbed replay output (§4.1), latched for the backend. */
+  absorbed?: SqlTxnOutput;
+  idempotencyKey?: string;
+
+  constructor(render: RenderIndex, daemon: RindleDaemonClient, envelope: MutationEnvelope) {
+    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(): boolean {
+    return this.sessionId !== undefined;
+  }
+
+  get statements(): readonly SqlStatement[] {
+    return this.stmts;
+  }
+
+  exec(sql: string, params: WireValue[] = []): void {
+    this.stmts.push({ sql, params });
+  }
+
+  private push(op: MutationOp): Promise<void> {
+    const rendered = renderOp(op, tableMeta(this.render, op.table), sqliteDialect);
+    if (rendered) this.stmts.push(rendered);
+    return Promise.resolve();
+  }
+
+  insert(table: string, row: KeyedRow): Promise<void> {
+    return this.push({ kind: "insert", table, row });
+  }
+  update(table: string, row: KeyedRow): Promise<void> {
+    return this.push({ kind: "update", table, row });
+  }
+  upsert(table: string, row: KeyedRow): Promise<void> {
+    return this.push({ kind: "upsert", table, row });
+  }
+  insertIgnore(table: string, row: KeyedRow): Promise<void> {
+    return this.push({ kind: "insertIgnore", table, row });
+  }
+  delete(table: string, pk: KeyedRow): Promise<void> {
+    return this.push({ kind: "delete", table, pk });
+  }
+
+  async row(table: string, pk: KeyedRow): Promise<KeyedRow | undefined> {
+    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: KeyedRow = {}; // 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: Ast | Query<any, any, any>): Promise<unknown> {
+    const ast = typeof (q as Query<any, any, any>).ast === "function" ? (q as Query<any, any, any>).ast() : (q as Ast);
+    const compiled = compileQueryAst(ast, catalogFor(this.render, ast), { dialect: "sqlite" });
+    const out = await this.readThroughTxn({ sql: compiled.sql, params: compiled.params as WireValue[] });
+    const cell = out.rows[0]?.[0];
+    if (typeof cell !== "string") return ast.one === true ? null : [];
+    return JSON.parse(cell) as unknown;
+  }
+
+  /** Run one read: upgrade to a session at the first (§5.1), ride the open one after, or fall
+   *  back to the legacy committed-state read when the daemon client lacks sessions. */
+  private async readThroughTxn(read: SqlStatement): Promise<SqlReadOutput> {
+    if (this.absorbed) throw new AbsorbedReplay();
+    if (!this.daemon.beginMutationSession) {
+      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 as SqlTxnOutput;
+          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. */
+  private async flush(): Promise<void> {
+    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(): Promise<SqlTxnOutput> {
+    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(): Promise<void> {
+    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 implements ServerMutationTx {
+  private chain: Promise<void> = Promise.resolve();
+  private readonly stmts: SqlStatement[] = [];
+  private readonly q: PgQuery;
+  private readonly render: RenderIndex;
+  private readonly rewrite: (sql: string) => string;
+  idempotencyKey?: string;
+
+  constructor(q: PgQuery, render: RenderIndex, rewrite: (sql: string) => string) {
+    this.q = q;
+    this.render = render;
+    this.rewrite = rewrite;
+  }
+
+  get statements(): readonly SqlStatement[] {
+    return this.stmts;
+  }
+
+  settle(): Promise<void> {
+    return this.chain;
+  }
+
+  private execLive(sql: string, params: WireValue[]): void {
+    this.chain = this.chain.then(async () => {
+      try {
+        await this.q.exec(sql, params as unknown[]);
+      } catch (err) {
+        throw new BackendError(err);
+      }
+    });
+  }
+
+  exec(sql: string, params: WireValue[] = []): void {
+    const stmt = { sql: this.rewrite(sql), params };
+    this.stmts.push(stmt);
+    this.execLive(stmt.sql, params);
+  }
+
+  private write(op: MutationOp): Promise<void> {
+    let rendered: SqlStatement | null;
+    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: string, row: KeyedRow): Promise<void> {
+    return this.write({ kind: "insert", table, row });
+  }
+  update(table: string, row: KeyedRow): Promise<void> {
+    return this.write({ kind: "update", table, row });
+  }
+  upsert(table: string, row: KeyedRow): Promise<void> {
+    return this.write({ kind: "upsert", table, row });
+  }
+  insertIgnore(table: string, row: KeyedRow): Promise<void> {
+    return this.write({ kind: "insertIgnore", table, row });
+  }
+  delete(table: string, pk: KeyedRow): Promise<void> {
+    return this.write({ kind: "delete", table, pk });
+  }
+  async row(table: string, pk: KeyedRow): Promise<KeyedRow | undefined> {
+    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: Array<Record<string, unknown>>;
+    try {
+      rows = await this.q.query(read.sql, read.params as unknown[]);
+    } catch (err) {
+      throw new BackendError(err);
+    }
+    return rowToKeyed(rows[0], meta);
+  }
+
+  query(): Promise<unknown> {
+    // 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: RindleDaemonClient): MutationBackend {
+  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: SqlTxn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
+      if (tx.idempotencyKey !== undefined) txn.idempotencyKey = tx.idempotencyKey;
+      return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+    },
+    reject({ envelope, reason }) {
+      return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+    },
+  };
+}
+
+/** The query surface a {@link PostgresPlugger} transaction exposes. `exec` runs one statement;
+ *  `query` returns rows keyed by column name (read-your-own-writes inside the txn). */
+export interface PgQuery {
+  exec(sql: string, params?: unknown[]): Promise<void>;
+  query(sql: string, params?: unknown[]): Promise<Array<Record<string, unknown>>>;
+}
+
+/** The thin driver adapter that keeps `pg` / `postgres.js` out of this package's dependencies
+ *  (`BYO-POSTGRES-LMID-CONTRACT-DESIGN.md` §6.2): run `fn` inside ONE transaction — commit on
+ *  resolve, roll back on throw. {@link pgPoolPlugger} adapts a node-postgres `Pool`. */
+export interface PostgresPlugger {
+  transaction<T>(fn: (q: PgQuery) => Promise<T>): Promise<T>;
+}
+
+export interface PostgresBackendOptions {
+  /** Rewrite each MUTATOR statement's SQL before it runs (never the lmid upsert). The intended
+   *  use is dialect bridging for a dual-topology app whose mutators are written SQLite-style:
+   *  pass {@link questionToDollarParams} to convert `?` placeholders to `$1..$n`. */
+  rewriteSql?: (sql: string) => string;
+}
+
+/** 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: PostgresPlugger, opts: PostgresBackendOptions = {}): MutationBackend {
+  const rewrite = opts.rewriteSql ?? ((sql: string) => 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: MutationEnvelope): Promise<SqlTxnOutput> =>
+    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),
+  };
+}
+
+/** The slice of a node-postgres `Pool` the plugger needs — structural, so `pg` stays a
+ *  dependency of the APP, never of this package. */
+export interface PgPoolLike {
+  connect(): Promise<{
+    query(sql: string, params?: unknown[]): Promise<{ rows: Array<Record<string, unknown>> }>;
+    release(err?: unknown): void;
+  }>;
+}
+
+/** 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: PgPoolLike): PostgresPlugger {
+  return {
+    async transaction<T>(fn: (q: PgQuery) => Promise<T>): Promise<T> {
+      const client = await pool.connect();
+      try {
+        await client.query("BEGIN");
+        const q: PgQuery = {
+          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: string): string {
+  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<User, Q extends ApiQueries<User>>(queries: Q): Q {
   return queries;
 }
@@ -353,6 +1214,38 @@ export function defineApiMutators<User, M extends ApiMutators<User>>(mutators: M
   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<User>(
+  registry: Record<string, SharedMutatorWithArgs<any>>,
+  principal: (ctx: MutationContext<User>) => MutatorCtx,
+): ApiMutators<User> {
+  const out: ApiMutators<User> = {};
+  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: ApiQueryResult): Ast {
   if (result && typeof result === "object" && "ast" in result && typeof result.ast === "function") {
     return result.ast();
@@ -360,9 +1253,112 @@ export function queryResultToAst(result: ApiQueryResult): Ast {
   return result as Ast;
 }
 
+/** One exemplar invocation for {@link dumpQueryShapes} — the `args`/`user` a query is built with.
+ *  Literal values never matter to the dump (shapes are deduped with literals stripped); what an
+ *  exemplar buys is BRANCH coverage, so supply one per code path a query function can take
+ *  (an optional filter present/absent, each enum axis, …). */
+export interface ShapeExemplar<User = unknown> {
+  args?: unknown;
+  user?: User;
+}
+
+/** The query-shapes document `rindle indices suggest` consumes: the app's synced tables (name +
+ *  primary key) and one wire AST per structurally distinct shape a registered query can build. */
+export interface QueryShapesDoc {
+  tables: Array<{ name: string; primaryKey: string[] }>;
+  queries: Array<{ name: string; ast: Ast }>;
+}
+
+/**
+ * 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<User>(opts: {
+  schema: Schema;
+  queries: ApiQueries<User>;
+  exemplars?: Partial<Record<string, ReadonlyArray<ShapeExemplar<User>>>>;
+}): Promise<QueryShapesDoc> {
+  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: QueryShapesDoc["queries"] = [];
+  for (const [name, query] of Object.entries(opts.queries).sort(([a], [b]) => a.localeCompare(b))) {
+    const seen = new Set<string>();
+    for (const ex of opts.exemplars?.[name] ?? [{}]) {
+      const ast = queryResultToAst(await query({ user: ex.user as 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: Ast): Record<string, unknown> {
+  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: Condition): unknown {
+  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<User = unknown>(opts: RindleApiServerOptions<User>): RindleApiServer<User> {
   const routes = { ...DEFAULT_RINDLE_API_ROUTES, ...opts.routes };
   const mode = opts.mode ?? "normalized";
+  // The mutation seam — defaulting to the daemon's co-transactional lmid stamp (unchanged behavior).
+  const backend = opts.backend ?? daemonBackend(opts.daemon);
+  // 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: 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));
@@ -436,31 +1432,34 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
   const pushMutation = async (input: PushMutationRequest<User>): Promise<PushMutationResponse> => {
     const context: ApiContext<User> = { user: input.user, request: input.request };
     const mutator = opts.mutators?.[input.envelope.name];
-    if (!mutator) return reject(opts.daemon, input.envelope, `unknown mutator: ${input.envelope.name}`);
-    let sql: Pick<SqlTxn, "statements" | "idempotencyKey">;
+    // 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}`);
     try {
       await assertAuthorized(opts.authorizeMutation, {
         user: input.user,
         envelope: input.envelope,
         context,
       });
-      const tx = new CollectingSqlMutationTx();
-      const result = await mutator(tx, input.envelope.args as never, {
-        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 as Error)?.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 as never, {
+          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: PushMutationsRequest<User>): Promise<PushMutationResponse[]> => {
@@ -518,6 +1517,30 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     }
   };
 
+  // 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: ApiContext<User>): Promise<void> => {
+    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: unknown): RoomHostResponse => {
+    if (e instanceof DaemonHttpError) {
+      let body: unknown;
+      try {
+        body = JSON.parse(e.body);
+      } catch {
+        body = { error: e.body };
+      }
+      return { status: e.status, body };
+    }
+    throw e;
+  };
+
   return {
     routes,
     createQueryLease,
@@ -525,6 +1548,46 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     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 as unknown as RowChangeTxn);
+        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 as string[] }) };
+      } catch (e) {
+        return daemonVerdict(e);
+      }
+    },
     handleQueryJson: (body, context) => {
       const msg = parseObject(body, "query request");
       return createQueryLease({
@@ -560,24 +1623,53 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
   };
 }
 
-class CollectingSqlMutationTx implements SqlMutationTx {
-  private readonly stmts: SqlStatement[] = [];
-
-  get statements(): readonly SqlStatement[] {
-    return this.stmts;
-  }
+/** 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<Args, Ctx extends MutatorCtx>(
+  mutator: SharedMutator<Args, Ctx>,
+  args: Args,
+  ctx: Ctx,
+  tx: ServerMutationTx,
+): Promise<void> {
+  return driveMutationAsync(mutator(isoTx, args, ctx), {
+    apply: (op) => applyOpToServerTx(tx, op),
+    read: (table, pk) => tx.row(table, pk),
+  });
+}
 
-  exec(sql: string, params: WireValue[] = []): void {
-    this.stmts.push({ sql, params });
+/** 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: ServerWriteTx, op: MutationOp): Promise<void> {
+  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: ApiMutatorResult, tx: SqlMutationTx): Pick<SqlTxn, "statements" | "idempotencyKey"> {
-  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: ApiMutatorResult, tx: ServerMutationTx): void {
+  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 as { idempotencyKey?: string }).idempotencyKey = result.idempotencyKey;
   }
-  return { statements: [...tx.statements] };
 }
 
 async function assertAuthorized<T>(authorizer: Authorizer<T> | undefined, input: T): Promise<void> {
@@ -629,11 +1721,11 @@ function errMessage(reason: unknown): string {
 }
 
 async function reject(
-  daemon: RindleDaemonClient,
+  backend: MutationBackend,
   envelope: MutationEnvelope,
   reason: string,
 ): Promise<PushMutationResponse> {
-  const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+  const output = await backend.reject({ envelope, reason });
   return { accepted: false, rejected: true, reason, output };
 }