@rindle/api-server 0.3.1 → 0.4.2

package/src/index.ts

@@ -1,5 +1,22 @@
-import type { Ast, Condition, MutationEnvelope, NamedQuery, Query, Schema } 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,
@@ -12,6 +29,11 @@ import type {
   MigrateOutput,
   MutationRejection,
   MutationRejectionOutput,
+  MutationSessionBegin,
+  MutationSessionBeginOutput,
+  MutationSessionExec,
+  MutationSessionQuery,
+  MutationSessionRef,
   QueryOnceInput,
   QueryOnceOutput,
   RindleDaemonClient,
@@ -28,6 +50,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",
@@ -82,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>;
@@ -140,32 +193,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>;
 }
 
@@ -223,6 +288,11 @@ export interface RindleApiServerOptions<User> {
    *  `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>;
@@ -369,6 +439,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 +495,513 @@ 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",
+      ),
+    );
+  }
+}
+
 /**
- * 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 +1051,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 +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();
@@ -704,6 +1355,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 +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];
+    // 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[]> => {
@@ -965,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> {