@rindle/api-server 0.3.1 → 0.4.3

package/src/index.ts

@@ -1,5 +1,23 @@
-import type { Ast, Condition, MutationEnvelope, NamedQuery, Query, Schema } from "@rindle/client";
+import { driveMutationAsync, insertCell, insertPlan, isoTx, toCell } from "@rindle/client";
+import type {
+  Ast,
+  ColType,
+  Condition,
+  KeyedRow,
+  MutationEnvelope,
+  MutationOp,
+  MutatorCtx,
+  NamedQuery,
+  Query,
+  QueryResultRow,
+  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,
@@ -12,6 +30,11 @@ import type {
   MigrateOutput,
   MutationRejection,
   MutationRejectionOutput,
+  MutationSessionBegin,
+  MutationSessionBeginOutput,
+  MutationSessionExec,
+  MutationSessionQuery,
+  MutationSessionRef,
   QueryOnceInput,
   QueryOnceOutput,
   RindleDaemonClient,
@@ -28,6 +51,12 @@ 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",
@@ -37,6 +66,8 @@ export const DEFAULT_RINDLE_API_ROUTES = {
   applyRowChangeTxn: "/api/rindle/apply-row-change-txn",
   claimRoomEpoch: "/api/rindle/claim-room-epoch",
   roomLmids: "/api/rindle/room-lmids",
+  // The DO shell's cold-boot callback (§10.1) — active only when `realtime` is configured.
+  roomBoot: "/api/rindle/room-boot",
 } as const;
 
 export type MaybePromise<T> = T | PromiseLike<T>;
@@ -82,14 +113,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>;
@@ -140,32 +196,44 @@ export interface QueryReadResponse {
   wsEndpoint?: string;
 }
 
-/** One mutation's collected effects, handed to a {@link MutationBackend} as ONE atomic unit. */
-export interface MutationApplyInput {
+/** The context a {@link MutationBackend} needs to run one mutation inside its transaction. */
+export interface MutationRunInput {
   envelope: MutationEnvelope;
-  /** What the mutator emitted, in order. */
-  statements: readonly SqlStatement[];
-  /** Present when the mutator returned a full `SqlTxn` carrying one. */
-  idempotencyKey?: string;
+  /** 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's statements go, and who stamps `lmid` — the seam that makes the mutator
- * authoring surface backend-agnostic (`BYO-POSTGRES-LMID-CONTRACT-DESIGN.md` §6). Two impls ship:
- * {@link daemonBackend} (today's behavior — the daemon's co-transactional stamp; the default) and
- * {@link postgresBackend} (BYO-Postgres: the same guarantees discharged in one PG transaction,
- * confirmation riding the CDC loop back down).
+ * 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).
  *
- * Both methods advance the client's `last_mutation_id`; that is the load-bearing invariant:
- * - `apply` runs the statements AND advances `lmid` to `envelope.mid` in the SAME atomic unit
- *   (OPTIMISTIC-WRITES-DESIGN.md §8.2) — never in a second transaction.
- * - `reject` applies NO data but STILL advances `lmid` past `envelope.mid` (§2.4 — the sharp
- *   edge: without it the client's pending queue never drains and the optimistic stack wedges).
- * - A backend/infrastructure failure THROWS from either — it is never reported as a user
- *   rejection (the client retries; mid dedup absorbs any applied prefix).
+ * 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 {
-  apply(input: MutationApplyInput): Promise<SqlTxnOutput>;
+  /** 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>;
 }
 
@@ -192,6 +260,7 @@ export interface RindleApiRoutes {
   applyRowChangeTxn: string;
   claimRoomEpoch: string;
   roomLmids: string;
+  roomBoot: string;
 }
 
 /** A room-host reply the transport writes VERBATIM (`status` + JSON `body`): the
@@ -217,21 +286,191 @@ export interface PinFanout {
   assertPins(pins: readonly MaterializeInput[]): Promise<void>;
 }
 
+// --------------------------------------------------------------------------- realtime (room) host
+//
+// Enabling Rindle Realtime for an app (RINDLE-REALTIME-ENABLEMENT-DESIGN.md §3.1) is ONE named
+// opt-in: the `realtime` options block. Its presence activates the flush trio AND `/room-boot`;
+// its absence keeps every room endpoint 403 and adds no route. The deprecated bare `authorizeRoom`
+// still gates the trio alone (it never activates `/room-boot`).
+
+/** The room-boot flush leg (enablement §5): where the placed room's write-behind lands and what
+ *  credential it presents. `urls` are the trio's ROUTE PATHS (root-relative — the shell resolves
+ *  them against the boot call's origin), so an app that overrides `routes` needs no out-of-band
+ *  sync; `headers` ride every flush call verbatim (`httpAuthority`'s `headers`). */
+export interface RoomBootFlush {
+  urls: { apply: string; claim: string; lmids: string };
+  headers: Record<string, string>;
+}
+
+/** The `/room-boot` response (RINDLE-REALTIME-DESIGN.md §10.1 — the DO shell's cold-boot
+ *  callback): the claimed placement epoch, the room's upstream footprint lease, and the flush
+ *  leg. A cold room boots inert and serves nothing until this returns. */
+export interface RoomBootResponse {
+  epoch: number;
+  upstreamLeaseToken: string;
+  /** Where the room opens its upstream subscription (a routed deploy's follower). Absent ⇒ the
+   *  shell's statically configured rindled ws endpoint. */
+  upstreamWsEndpoint?: string;
+  flush: RoomBootFlush;
+}
+
+export interface RindleRealtimeOptions<User> {
+  /** The boot shell secret (§10.1 — a host binding, never client-derived). Authenticates the
+   *  room's `Authorization: Bearer` on `/room-boot` (the default {@link authorizeBoot}) and keys
+   *  the DEFAULT epoch-bound flush credential. */
+  shellSecret: string;
+  /** doc → the room's approved upstream footprint (§3.1) — an `Ast` or fluent `Query`. MAY
+   *  delegate to the named-query registry internally; throw `RindleApiError("not-found", …, 404)`
+   *  for a doc that shouldn't exist. The §9 footprint budget belongs here — it runs once per
+   *  placement, at lease mint. */
+  resolveFootprint: (doc: string, ctx: ApiContext<User>) => MaybePromise<ApiQueryResult>;
+  /** Gates the flush trio — `authorizeRoom`, relocated. Default: verify the default flush
+   *  credential from the {@link ROOM_FLUSH_CREDENTIAL_HEADER} request header — which requires the
+   *  transport to pass its incoming request as `context.request` (Fetch `Request` and node
+   *  `IncomingMessage` shapes are both understood). */
+  authorize?: Authorizer<ApiContext<User>>;
+  /** Gates `/room-boot`. Default: constant-time `Authorization: Bearer` check against
+   *  {@link shellSecret} (same `context.request` requirement as {@link authorize}). */
+  authorizeBoot?: Authorizer<ApiContext<User>>;
+  /** Mint the flush headers a placed room presents on every flush call. Default:
+   *  {@link mintRoomFlushCredential} under {@link ROOM_FLUSH_CREDENTIAL_HEADER}. Override this
+   *  and {@link authorize} TOGETHER — they are the two ends of one credential. */
+  mintFlushHeaders?: (input: { doc: string; epoch: number }) => MaybePromise<Record<string, string>>;
+  /** Lease TTL for the room's upstream footprint materialization (defaults to the server-wide
+   *  `leaseTtlMs`, else the daemon's default). */
+  upstreamLeaseTtlMs?: number;
+  /** Static override for where rooms open their upstream subscription; default is the
+   *  `wsEndpoint` the materialize returns (set in routed deploys), else absent. */
+  upstreamWsEndpoint?: string;
+}
+
+// The DEFAULT flush credential: `rfc1.<b64url payload>.<b64url hmac-sha256>`, payload
+// `{v:1, doc, epoch, iat}`. Deliberately EPOCH-bound, not time-bound: the credential's lifecycle
+// IS the placement fence (§8.3 — a superseded epoch's flushes 409 at the store no matter what
+// credential they carry), and platform revocation is registry suspension, so an `exp` would only
+// force spurious re-boots of long-lived rooms. HMAC via WebCrypto (`crypto.subtle`) so the exact
+// same code runs in Node and a Cloudflare Worker — no `node:crypto` import (matching
+// `@rindle/room`'s token module).
+
+export const ROOM_FLUSH_CREDENTIAL_HEADER = "x-rindle-room-credential";
+
+const FLUSH_CREDENTIAL_PREFIX = "rfc1";
+
+export interface RoomFlushCredentialPayload {
+  v: 1;
+  doc: string;
+  epoch: number;
+  iat: number;
+}
+
+function b64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// Return type inferred (`Uint8Array<ArrayBuffer>` under TS ≥5.7 libs) — an explicit
+// `Uint8Array` annotation widens to `ArrayBufferLike` and fails `crypto.subtle`'s
+// `BufferSource` under consumers compiling this source with newer lib types.
+function unb64url(s: string) {
+  const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function flushHmacKey(secret: string, usage: "sign" | "verify") {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+/** Sign the default epoch-bound flush credential (`/room-boot` mints one per placement). */
+export async function mintRoomFlushCredential(opts: {
+  shellSecret: string;
+  doc: string;
+  epoch: number;
+  /** Mint time; defaults to `Date.now()`. Injectable for tests. */
+  now?: number;
+}): Promise<string> {
+  const payload: RoomFlushCredentialPayload = {
+    v: 1,
+    doc: opts.doc,
+    epoch: opts.epoch,
+    iat: opts.now ?? Date.now(),
+  };
+  const body = b64url(new TextEncoder().encode(JSON.stringify(payload)));
+  const signed = `${FLUSH_CREDENTIAL_PREFIX}.${body}`;
+  const key = await flushHmacKey(opts.shellSecret, "sign");
+  const sig = new Uint8Array(
+    await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(signed)),
+  );
+  return `${signed}.${b64url(sig)}`;
+}
+
+/** Verify a flush credential's MAC, then its claims; returns the payload or throws. The MAC is
+ *  checked FIRST — no claim is trusted before it passes. */
+export async function verifyRoomFlushCredential(
+  credential: string,
+  shellSecret: string,
+): Promise<RoomFlushCredentialPayload> {
+  const parts = credential.split(".");
+  if (parts.length !== 3 || parts[0] !== FLUSH_CREDENTIAL_PREFIX) {
+    throw new Error("not a room flush credential");
+  }
+  const [, body, sig] = parts;
+  const key = await flushHmacKey(shellSecret, "verify");
+  const ok = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    unb64url(sig),
+    new TextEncoder().encode(`${FLUSH_CREDENTIAL_PREFIX}.${body}`),
+  );
+  if (!ok) throw new Error("bad signature");
+  let payload: RoomFlushCredentialPayload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(unb64url(body))) as RoomFlushCredentialPayload;
+  } catch {
+    throw new Error("malformed payload");
+  }
+  if (payload.v !== 1) throw new Error("unknown version");
+  if (typeof payload.doc !== "string" || payload.doc.length === 0) {
+    throw new Error("missing doc");
+  }
+  if (typeof payload.epoch !== "number") throw new Error("missing epoch");
+  return payload;
+}
+
 export 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>>;
+  /** Rindle Realtime (RINDLE-REALTIME-ENABLEMENT-DESIGN.md §3.1): the ONE named opt-in.
+   *  Presence activates the room flush trio AND `/room-boot`; absence keeps every room
+   *  endpoint 403. Takes precedence over the deprecated {@link authorizeRoom}. */
+  realtime?: RindleRealtimeOptions<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. */
+   *  hosting a write authority is an explicit opt-in, never a default.
+   *  @deprecated Use {@link realtime} (its `authorize`) — this bare form gates the
+   *  flush trio but never activates `/room-boot`. When both are set, `realtime` wins. */
   authorizeRoom?: Authorizer<ApiContext<User>>;
   routes?: Partial<RindleApiRoutes>;
   mode?: StreamMode;
@@ -313,6 +552,10 @@ export interface RindleApiServer<User> {
   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>;
+  /** The DO shell's cold-boot callback (§10.1; enablement §3.1): authenticate the shell
+   *  secret, resolve the doc's footprint, claim the placement epoch, mint the upstream
+   *  lease and the flush leg. 403 until {@link RindleApiServerOptions.realtime} is set. */
+  handleRoomBootJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
 }
 
 export type RindleApiErrorCode = "bad-request" | "forbidden" | "not-found" | "rejected";
@@ -369,6 +612,33 @@ 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);
   }
@@ -398,17 +668,525 @@ 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>;
+  /** Columns a full insert must name — the non-nullable ones (design 206 §6.2). */
+  required: string[];
+  /** The nullable (omittable-to-null) columns — an omitted one binds `NULL` (design 206 §6.2). */
+  nullable: ReadonlySet<string>;
+}
+
+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;
+    // Same schema-derived plan the client funnel uses (design 206 §6.1), so their required-sets
+    // and null-fills can't drift.
+    const { required, nullable } = insertPlan(schema.tables[name]);
+    out[name] = { columns, pkNames: [...meta.primaryKey], types, required, nullable };
+  }
+  return out;
+}
+
+const quoteIdent = (name: 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 NON-nullable column (a nullable column may be omitted and is filled with
+ *  `NULL`, design 206 §6.2). Mirrors the client `trackingTx.checkColumns` messages so an author sees
+ *  the same error on both tiers. */
+function checkColumns(table: 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.required : meta.pkNames;
+  const missing = required.filter((c) => !(c in obj));
+  if (missing.length) {
+    throw new Error(`missing ${full ? "column" : "primary-key column"}${missing.length > 1 ? "s" : ""} ${missing.join(", ")} on ${table}`);
+  }
+}
+
+const encode = (dialect: 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).
+  // `insertCell` fills NULL for an omitted nullable column on the insert arm (design 206 §6.2);
+  // on update/delete every bound column is guaranteed present, so it is a pass-through there.
+  // `toCell` stringifies a `json` object (a typed mutator passes the parsed object) — a string
+  // passes through, so an author may still pass pre-stringified json.
+  const bind = (c: string, row: KeyedRow): string => {
+    params.push(encode(dialect, toCell(insertCell(row, c), meta.types[c]), meta.types[c]));
+    return dialect.placeholder(params.length);
+  };
+
+  if (op.kind === "insert" || op.kind === "insertIgnore" || op.kind === "upsert") {
+    checkColumns(op.table, op.row, meta, true);
+    const cols = meta.columns;
+    const values = cols.map((c) => bind(c, op.row));
+    let sql = `INSERT INTO ${t} (${cols.map(quoteIdent).join(", ")}) VALUES (${values.join(", ")})`;
+    if (op.kind === "insertIgnore") {
+      sql += ` ON CONFLICT (${meta.pkNames.map(quoteIdent).join(", ")}) DO NOTHING`;
+    } else if (op.kind === "upsert") {
+      const nonPk = cols.filter((c) => !meta.pkNames.includes(c));
+      sql += ` ON CONFLICT (${meta.pkNames.map(quoteIdent).join(", ")}) `;
+      sql += nonPk.length
+        ? `DO UPDATE SET ${nonPk.map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`).join(", ")}`
+        : `DO NOTHING`;
+    }
+    return { sql, params };
+  }
+
+  if (op.kind === "update") {
+    checkColumns(op.table, op.row, meta, false);
+    const setCols = meta.columns.filter((c) => !meta.pkNames.includes(c) && c in op.row);
+    if (!setCols.length) return null; // pk-only row → nothing to change (client no-op edit)
+    const setSql = setCols.map((c) => `${quoteIdent(c)} = ${bind(c, op.row)}`);
+    const whereSql = meta.pkNames.map((c) => `${quoteIdent(c)} = ${bind(c, op.row)}`);
+    return { sql: `UPDATE ${t} SET ${setSql.join(", ")} WHERE ${whereSql.join(" AND ")}`, params };
+  }
+
+  // delete
+  checkColumns(op.table, op.pk, meta, false);
+  const whereSql = meta.pkNames.map((c) => `${quoteIdent(c)} = ${bind(c, op.pk)}`);
+  return { sql: `DELETE FROM ${t} WHERE ${whereSql.join(" AND ")}`, params };
+}
+
+/** Render a point read (`tx.row`) — `SELECT <cols> FROM "T" WHERE <pk>` — for read-your-writes. */
+export function renderPointRead(table: 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",
+      ),
+    );
+  }
+}
+
 /**
- * Today's behavior as a {@link MutationBackend}: ship the statements + envelope to the daemon,
- * whose `/execute-sql-txn` path stamps `lmid` co-transactionally (and `/reject-mutation` advances
- * it past a rejected mid). This is the default backend — existing users never see a change.
+ * The 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 {
-    apply({ envelope, statements, idempotencyKey }) {
-      const txn: SqlTxn = { statements: [...statements], clientID: envelope.clientID, mid: envelope.mid };
-      if (idempotencyKey !== undefined) txn.idempotencyKey = idempotencyKey;
-      return daemon.executeSqlTxn(txn);
+    dialect: sqliteDialect,
+    async runMutation({ envelope, render, run }) {
+      const tx = new DaemonLazyTx(render, daemon, envelope);
+      try {
+        await run(tx);
+      } catch (err) {
+        // A begin-absorbed replay: the authoritative outcome already committed — answer it,
+        // whatever the body did with the unwind (§4.1; the latch, not the throw, decides).
+        if (tx.absorbed) return { accepted: true, output: tx.absorbed };
+        if (err instanceof BackendError) {
+          await tx.rollbackSessionQuietly();
+          throw err.driverError; // infra — never a user rejection
+        }
+        const reason = errMessage(err);
+        // Data first, watermark second: the rollback releases the single writer that the
+        // `/reject-mutation` lmid-only commit needs (§2.4 on the session path).
+        await tx.rollbackSessionQuietly();
+        const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+        return { accepted: false, reason, output };
+      }
+      if (tx.absorbed) return { accepted: true, output: tx.absorbed };
+      if (tx.session) {
+        try {
+          return { accepted: true, output: await tx.commitSession() };
+        } catch (err) {
+          if (err instanceof BackendError) throw err.driverError; // infra (client retries; dedup absorbs)
+          throw err;
+        }
+      }
+      const txn: 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 });
@@ -458,16 +1236,42 @@ ON CONFLICT ("client_id") DO UPDATE
  */
 export function postgresBackend(plugger: PostgresPlugger, opts: PostgresBackendOptions = {}): MutationBackend {
   const rewrite = opts.rewriteSql ?? ((sql: string) => sql);
-  const applyInTxn = (envelope: MutationEnvelope, statements: readonly SqlStatement[]): Promise<SqlTxnOutput> =>
+  // 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) => {
-      for (const s of statements) await q.exec(rewrite(s.sql), (s.params ?? []) as unknown[]);
-      // ALWAYS — accepted or rejected — in this same transaction (§2.2, §2.4).
       await q.exec(LMID_UPSERT, [envelope.clientID, envelope.mid]);
       return { applied: true, lmidAdvances: [{ clientID: envelope.clientID, lmid: envelope.mid }] };
     });
   return {
-    apply: ({ envelope, statements }) => applyInTxn(envelope, statements),
-    reject: ({ envelope }) => applyInTxn(envelope, []),
+    dialect: postgresDialect,
+    async runMutation({ envelope, render, run }) {
+      try {
+        const output = await plugger.transaction(async (q) => {
+          const tx = new PgLiveTx(q, render, rewrite);
+          try {
+            await run(tx);
+            await tx.settle(); // drain any un-awaited queued writes before the lmid stamp
+          } catch (err) {
+            if (err instanceof BackendError) throw err; // infra → rollback + propagate
+            throw new RejectSignal(errMessage(err)); // business → rollback data, tag for §2.4
+          }
+          // ALWAYS on the accepted path, SAME transaction (§2.2): the lmid upsert commits with data.
+          await q.exec(LMID_UPSERT, [envelope.clientID, envelope.mid]);
+          return { applied: true, lmidAdvances: [{ clientID: envelope.clientID, lmid: envelope.mid }] };
+        });
+        return { accepted: true, output };
+      } catch (err) {
+        if (err instanceof RejectSignal) {
+          // Data rolled back; STILL advance lmid alone (§2.4 — the client's queue must drain).
+          return { accepted: false, reason: err.message, output: await lmidOnly(envelope) };
+        }
+        if (err instanceof BackendError) throw err.driverError; // infra
+        throw err;
+      }
+    },
+    reject: ({ envelope }) => lmidOnly(envelope).then(() => undefined),
   };
 }
 
@@ -595,6 +1399,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();
@@ -704,6 +1540,10 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
   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));
@@ -777,31 +1617,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];
+    // PRE-FLIGHT rejections — no txn, no data, `lmid` alone (the queue must still drain).
     if (!mutator) return reject(backend, input.envelope, `unknown mutator: ${input.envelope.name}`);
-    let sql: Pick<SqlTxn, "statements" | "idempotencyKey">;
     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(backend, input.envelope, String((err as Error)?.message ?? err));
+      return reject(backend, input.envelope, errMessage(err));
     }
-    const output = await backend.apply({
+    // Run the mutator INSIDE the backend's transaction. A throw from the mutator body is a business
+    // rejection (roll data back, advance `lmid`); a BackendError (DB failure) rejects this promise.
+    const outcome = await backend.runMutation({
       envelope: input.envelope,
-      statements: sql.statements,
-      idempotencyKey: sql.idempotencyKey,
+      render: renderIndex,
+      run: async (tx) => {
+        const result = await mutator(tx, input.envelope.args 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[]> => {
@@ -859,13 +1702,18 @@ 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.
+  // The room write-authority gate (§5.3.1): endpoints are disabled until the app opts in —
+  // the `realtime` block (which also activates `/room-boot`) or the deprecated bare
+  // `authorizeRoom` (trio only). Hosting an authority is never a default.
+  const realtime = opts.realtime;
+  const roomAuthorizer: Authorizer<ApiContext<User>> | undefined = realtime
+    ? (realtime.authorize ?? defaultFlushGate(realtime.shellSecret))
+    : opts.authorizeRoom;
   const roomGate = async (context: ApiContext<User>): Promise<void> => {
-    if (!opts.authorizeRoom) {
+    if (!roomAuthorizer) {
       throw new RindleApiError("forbidden", "room authority not configured", 403);
     }
-    await assertAuthorized(opts.authorizeRoom, context);
+    await assertAuthorized(roomAuthorizer, context);
   };
 
   // The store's verdict rides specific statuses + body shapes (fence / conflict /
@@ -930,6 +1778,58 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         return daemonVerdict(e);
       }
     },
+    handleRoomBootJson: async (body, context) => {
+      if (!realtime) {
+        throw new RindleApiError("forbidden", "realtime not configured", 403);
+      }
+      await assertAuthorized(realtime.authorizeBoot ?? defaultBootGate(realtime.shellSecret), context);
+      const msg = parseObject(body, "room-boot request");
+      const doc = parseString(msg.doc, "doc");
+      if (msg.instance !== undefined) parseString(msg.instance, "instance"); // diagnostic identity only
+      const ast = queryResultToAst(await realtime.resolveFootprint(doc, context));
+      const claim = opts.daemon.claimRoomEpoch?.bind(opts.daemon);
+      if (!claim) {
+        throw new Error("the configured daemon client does not implement claimRoomEpoch");
+      }
+      try {
+        // Claim FIRST (§2.5): the lease below is minted for THIS placement, so a boot
+        // that loses the epoch race learns it here, before any materialization exists.
+        const { epoch } = await claim({ doc });
+        const lease = await opts.daemon.materialize({
+          ast,
+          // The room's upstream leg IS the normalized protocol (§3) — never the app's
+          // viewer `mode`.
+          mode: "normalized",
+          leaseTtlMs: realtime.upstreamLeaseTtlMs ?? opts.leaseTtlMs,
+        });
+        const headers = realtime.mintFlushHeaders
+          ? await realtime.mintFlushHeaders({ doc, epoch })
+          : {
+              [ROOM_FLUSH_CREDENTIAL_HEADER]: await mintRoomFlushCredential({
+                shellSecret: realtime.shellSecret,
+                doc,
+                epoch,
+              }),
+            };
+        const res: RoomBootResponse = {
+          epoch,
+          upstreamLeaseToken: lease.leaseToken,
+          flush: {
+            urls: {
+              apply: routes.applyRowChangeTxn,
+              claim: routes.claimRoomEpoch,
+              lmids: routes.roomLmids,
+            },
+            headers,
+          },
+        };
+        const upstreamWsEndpoint = realtime.upstreamWsEndpoint ?? lease.wsEndpoint;
+        if (upstreamWsEndpoint !== undefined) res.upstreamWsEndpoint = upstreamWsEndpoint;
+        return { status: 200, body: res };
+      } catch (e) {
+        return daemonVerdict(e);
+      }
+    },
     handleQueryJson: (body, context) => {
       const msg = parseObject(body, "query request");
       return createQueryLease({
@@ -965,24 +1865,65 @@ 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),
+    query: async (q) => {
+      // The shared-seam contract is ALWAYS an array of rows: the client's `WriteTxn.query` returns
+      // an array even for a root `.one()` (the root unwrap is the Store's `materialize()`, not the
+      // in-mutator read — rust/src/wasm/db.rs). The server's `tx.query` returns a scalar (object|null)
+      // for a `.one()` root, so normalize it to `[]`/`[row]` here — one body sees the same shape on
+      // both tiers. (Postgres backend: `tx.query` rejects until POSTGRES-READ-COMPILER-DESIGN.md
+      // Phase B; the daemon/SQLite backend compiles + rides the open session — DAEMON §5.4.)
+      const ast = q.ast();
+      const res = await tx.query(ast);
+      if (ast.one === true) return res == null ? [] : [res as QueryResultRow];
+      return (res ?? []) as QueryResultRow[];
+    },
+  });
+}
 
-  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> {
@@ -991,6 +1932,66 @@ async function assertAuthorized<T>(authorizer: Authorizer<T> | undefined, input:
   if (result === false) throw new RindleApiError("forbidden", "rindle request forbidden", 403);
 }
 
+/** The default flush-trio gate: verify the default epoch-bound credential from the request
+ *  header. The two refusal messages are deliberately distinct — "missing" is a transport wiring
+ *  bug (no `context.request`), "refused" is an invalid credential. */
+function defaultFlushGate<User>(shellSecret: string): Authorizer<ApiContext<User>> {
+  return async (context) => {
+    const credential = requestHeader(context.request, ROOM_FLUSH_CREDENTIAL_HEADER);
+    if (!credential) {
+      throw new RindleApiError(
+        "forbidden",
+        `missing ${ROOM_FLUSH_CREDENTIAL_HEADER} header — is the transport passing its incoming request as context.request?`,
+        403,
+      );
+    }
+    try {
+      await verifyRoomFlushCredential(credential, shellSecret);
+    } catch (e) {
+      throw new RindleApiError("forbidden", `flush credential refused: ${errMessage(e)}`, 403);
+    }
+  };
+}
+
+/** The default `/room-boot` gate: `Authorization: Bearer <shell secret>` (README contract),
+ *  compared constant-time. */
+function defaultBootGate<User>(shellSecret: string): Authorizer<ApiContext<User>> {
+  return (context) => {
+    const auth = requestHeader(context.request, "authorization");
+    const bearer = auth && /^bearer\s/i.test(auth) ? auth.replace(/^bearer\s+/i, "") : undefined;
+    if (!bearer || !timingSafeEqualStr(bearer, shellSecret)) {
+      throw new RindleApiError("forbidden", "room-boot: shell secret refused", 403);
+    }
+  };
+}
+
+/** Best-effort header extraction from whatever the transport put in `context.request`: a Fetch
+ *  `Request` (`headers.get`), a node `IncomingMessage` (lowercased header map), or a plain
+ *  `{headers: {...}}`. `undefined` when there is no request or no such header. */
+function requestHeader(request: unknown, name: string): string | undefined {
+  if (!request || typeof request !== "object") return undefined;
+  const headers = (request as { headers?: unknown }).headers;
+  if (!headers || typeof headers !== "object") return undefined;
+  if (typeof (headers as { get?: unknown }).get === "function") {
+    return (headers as { get(n: string): string | null }).get(name) ?? undefined;
+  }
+  const map = headers as Record<string, unknown>;
+  const v = map[name.toLowerCase()] ?? map[name];
+  if (typeof v === "string") return v;
+  if (Array.isArray(v) && typeof v[0] === "string") return v[0];
+  return undefined;
+}
+
+/** Constant-time string equality (a length mismatch fails fast — length is not the secret). */
+function timingSafeEqualStr(a: string, b: string): boolean {
+  const ab = new TextEncoder().encode(a);
+  const bb = new TextEncoder().encode(b);
+  if (ab.length !== bb.length) return false;
+  let diff = 0;
+  for (let i = 0; i < ab.length; i++) diff |= ab[i] ^ bb[i];
+  return diff === 0;
+}
+
 async function resolvePolicy<User>(
   policy: RindleApiServerOptions<User>["materializationPolicy"],
   input: QueryLeaseRequest<User>,