@rindle/api-server 0.1.0-rc.5

package/src/index.ts

@@ -0,0 +1,656 @@
+import type { Ast, MutationEnvelope, NamedQuery, Query } from "@rindle/client";
+import type {
+  DematerializeInput,
+  DematerializeOutput,
+  MaterializationPolicy,
+  MaterializeInput,
+  MaterializeOutput,
+  MigrateInput,
+  MigrateOutput,
+  MutationRejection,
+  MutationRejectionOutput,
+  QueryOnceInput,
+  QueryOnceOutput,
+  RindleDaemonClient,
+  RowChangeTxn,
+  RowChangeTxnOutput,
+  SqlStatement,
+  SqlTxn,
+  SqlTxnOutput,
+  StreamMode,
+  WireValue,
+} from "@rindle/daemon-client";
+
+export const DEFAULT_RINDLE_API_ROUTES = {
+  query: "/api/rindle/query",
+  read: "/api/rindle/read",
+  mutate: "/api/rindle/mutate",
+} as const;
+
+export type MaybePromise<T> = T | PromiseLike<T>;
+
+export interface ApiContext<User> {
+  user: User;
+  request?: unknown;
+}
+
+export type ApiQueryResult = Ast | Query<any, any, any>;
+export type ApiQuery<User, Args> = (ctx: ApiContext<User>, args: Args) => MaybePromise<ApiQueryResult>;
+export type ApiQueries<User> = Record<string, ApiQuery<User, any>>;
+
+export interface RunQueryInput<User> {
+  user: User;
+  name: string;
+  args: unknown;
+  query: ApiQuery<User, any>;
+  context: ApiContext<User>;
+}
+
+export type RunQuery<User> = (input: RunQueryInput<User>) => MaybePromise<ApiQueryResult>;
+
+export interface AuthorizeQueryInput<User> {
+  user: User;
+  name: string;
+  args: unknown;
+  context: ApiContext<User>;
+}
+
+export interface AuthorizeMutationInput<User> {
+  user: User;
+  envelope: MutationEnvelope;
+  context: ApiContext<User>;
+}
+
+export type Authorizer<T> = (input: T) => MaybePromise<boolean | void>;
+
+export interface MutationContext<User> {
+  user: User;
+  envelope: MutationEnvelope;
+  daemon: RindleDaemonClient;
+  request?: unknown;
+}
+
+export interface SqlMutationTx {
+  exec(sql: string, params?: WireValue[]): void;
+  readonly statements: readonly SqlStatement[];
+}
+
+export type ApiMutatorResult = void | SqlStatement[] | SqlTxn;
+export type ApiMutator<User, Args> = (
+  tx: SqlMutationTx,
+  args: Args,
+  ctx: MutationContext<User>,
+) => MaybePromise<ApiMutatorResult>;
+export type ApiMutators<User> = Record<string, ApiMutator<User, any>>;
+
+export interface QueryLeaseRequest<User> {
+  user: User;
+  name: string;
+  args: unknown;
+  request?: unknown;
+  /** The browser's stable `clientId` (sent on the query POST) — the anonymous routing-key fallback
+   *  when there is no authenticated subject and no session cookie (READ-ROUTER-DESIGN.md §1.5/§2.2).
+   *  A routing HINT only, never authorization. */
+  clientId?: string;
+}
+
+export interface QueryLeaseResponse {
+  leaseToken: string;
+  materializationId: string;
+  queryKey?: string;
+  reused?: boolean;
+  /** The follower this lease lives on (READ-ROUTER-DESIGN.md §2.3) — the browser opens its
+   *  subscription ws here. Absent ⇒ single-daemon (the client uses its static `wsUrl`). */
+  wsEndpoint?: string;
+}
+
+/** A one-shot SSR read of a named query (SSR-DESIGN.md §6): same `(name, args)` surface as a lease,
+ *  but the daemon serializes the current view ONCE and registers no subscriber. */
+export interface QueryReadRequest<User> {
+  user: User;
+  name: string;
+  args: unknown;
+  request?: unknown;
+  /** The browser's stable `clientId` — the anonymous routing-key fallback (see
+   *  {@link QueryLeaseRequest.clientId}). Lets the SSR read co-locate on the follower the booting
+   *  client's first subscribe will hit (READ-ROUTER-DESIGN.md §2.4). */
+  clientId?: string;
+}
+
+/** The assembled (nested-by-name) first-paint snapshot the server-side Store seeds + dehydrates
+ *  (SSR-DESIGN.md §3.3). `rows` hydrate without an engine; `cvMin` is their watermark baseline. */
+export interface QueryReadResponse {
+  rows: Array<{ cols: Record<string, unknown>; [rel: string]: unknown }>;
+  cvMin?: number;
+  queryKey?: string;
+  /** The follower this read warmed (READ-ROUTER-DESIGN.md §2.4) — inject it into the SSR bootstrap
+   *  so the booting client opens its ws to the same warm follower. Absent ⇒ single-daemon. */
+  wsEndpoint?: string;
+}
+
+export interface PushMutationRequest<User> {
+  user: User;
+  envelope: MutationEnvelope;
+  request?: unknown;
+}
+
+export interface PushMutationsRequest<User> {
+  user: User;
+  envelopes: MutationEnvelope[];
+  request?: unknown;
+}
+
+export type PushMutationResponse =
+  | { accepted: true; rejected: false; output: SqlTxnOutput }
+  | { accepted: false; rejected: true; reason: string; output?: unknown };
+
+export interface RindleApiRoutes {
+  query: string;
+  read: string;
+  mutate: string;
+}
+
+/** A named query to keep permanently materialized (warm with zero subscribers). */
+export interface PinnedQuery {
+  name: string;
+  args?: unknown;
+}
+
+/** The explicit fleet pin fan-out seam (READ-ROUTER-DESIGN.md §4.2). The api-server resolves each
+ *  pin's authoritative AST under `pinUser` and hands the ready {@link MaterializeInput}s here; the
+ *  implementation (the read router) fans EACH across all live followers. Distinct, on purpose, from
+ *  a per-viewer `materialize` (which routes ONE) — a pin-assert always sprays ALL. */
+export interface PinFanout {
+  assertPins(pins: readonly MaterializeInput[]): Promise<void>;
+}
+
+export interface RindleApiServerOptions<User> {
+  daemon: RindleDaemonClient;
+  queries?: ApiQueries<User>;
+  runQuery?: RunQuery<User>;
+  mutators?: ApiMutators<User>;
+  authorizeQuery?: Authorizer<AuthorizeQueryInput<User>>;
+  authorizeMutation?: Authorizer<AuthorizeMutationInput<User>>;
+  routes?: Partial<RindleApiRoutes>;
+  mode?: StreamMode;
+  materializationPolicy?:
+    | MaterializationPolicy
+    | ((input: QueryLeaseRequest<User>) => MaybePromise<MaterializationPolicy>);
+  leaseTtlMs?: number;
+  /** Idle TTL (ms) the warm pipeline a one-shot SSR {@link RindleApiServer.readQuery read} leaves
+   *  behind is held at (SSR-DESIGN.md §3.4) — it must comfortably cover page-load + client-boot +
+   *  the follow-up live `subscribe` so the browser lands on a still-warm pipeline (the warm
+   *  handoff). The TTL is NOT part of the dedup key (max-wins), so it only ever extends a shared
+   *  query's window. Absent ⇒ the daemon's default idle TTL. */
+  readIdleTtlMs?: number;
+  subject?: string | ((input: QueryLeaseRequest<User>) => MaybePromise<string | undefined>);
+  /** The ANONYMOUS routing key forwarded to the read router (READ-ROUTER-DESIGN.md §2.2) — used by
+   *  HRW placement when there is no authenticated `subject`. The router keys on `subject ?? this`;
+   *  the resolved value rides `metadata.routingKey` to the daemon. Default: the browser-supplied
+   *  `clientId` (from the query POST body). NOTE: the default cannot co-locate an ANONYMOUS SSR read
+   *  with the booting client — an SSR server can't see the browser's localStorage `clientId`, so the
+   *  two legs compute different keys and §2.4's warm handoff misses (still correct — just an extra
+   *  first-touch materialize). For anonymous SSR co-location, set this to read a server-set session
+   *  cookie from `input.request` (it rides the SSR request AND every browser request). A routing
+   *  HINT only — never authorization. Ignored by a single (unrouted) daemon, which has nothing to
+   *  route. */
+  routingKey?: string | ((input: QueryLeaseRequest<User>) => MaybePromise<string | undefined>);
+  /** The EXPLICIT fleet pin fan-out (READ-ROUTER-DESIGN.md §4.2 "push") — when set,
+   *  {@link RindleApiServer.assertPins} fans each resolved pin across ALL live followers through it
+   *  (e.g. `createRouterPinClient` from `@rindle/router`) instead of materializing each pin once on
+   *  the (single) daemon. A per-viewer `materialize` always routes ONE; a pin-assert always fans
+   *  ALL — never inferred from `policy.kind`. Absent ⇒ single-daemon behavior (one materialize per
+   *  pin). */
+  pinFanout?: PinFanout;
+  /** Named queries to keep permanently materialized via {@link RindleApiServer.assertPins}.
+   *  Each is materialized with a `pinned` policy (survives zero subscribers) so late joiners
+   *  attach to an already-warm result. Pins are viewer-independent — resolved with `pinUser`. */
+  pinnedQueries?: PinnedQuery[];
+  /** The user context pins resolve under (pins are shared, so they should not depend on a
+   *  per-viewer identity). Defaults to `undefined`. */
+  pinUser?: User;
+}
+
+export interface RindleApiServer<User> {
+  readonly routes: RindleApiRoutes;
+  createQueryLease(input: QueryLeaseRequest<User>): Promise<QueryLeaseResponse>;
+  /** (Re-)materialize every `pinnedQueries` entry with a pinned policy. Idempotent — the daemon
+   *  dedupes by canonical query, so a re-assert reuses the existing materialization. Call it at
+   *  startup and whenever the daemon restarts (e.g. from the daemon-client `onBootId` hook), since
+   *  the daemon holds no durable materialization state. No-op when `pinnedQueries` is empty. */
+  assertPins(): Promise<void>;
+  pushMutation(input: PushMutationRequest<User>): Promise<PushMutationResponse>;
+  /** Apply an in-order batch (the client mutation queue's flush). Envelopes run strictly
+   *  sequentially; a rejection still advances the daemon's lmid, so later envelopes in the
+   *  batch stay contiguous and keep applying. A daemon ERROR throws for the whole batch —
+   *  the client retries it and the daemon's mid dedup absorbs the already-applied prefix. */
+  pushMutations(input: PushMutationsRequest<User>): Promise<PushMutationResponse[]>;
+  /** One-shot SSR read (SSR-DESIGN.md §6): resolve `(name, args)` → AST (same authority path as a
+   *  lease, `authorizeQuery` enforced), have the daemon serialize the current view once, and return
+   *  the assembled rows for the loader to seed + dehydrate. Registers NO subscriber — a dropped
+   *  render leaks nothing; the pipeline self-reclaims after the idle TTL ({@link
+   *  RindleApiServerOptions.readIdleTtlMs}) unless the browser's follow-up `subscribe` lands first. */
+  readQuery(input: QueryReadRequest<User>): Promise<QueryReadResponse>;
+  handleQueryJson(body: unknown, context: ApiContext<User>): Promise<QueryLeaseResponse>;
+  /** Parse a default `{name, args}` read body and run {@link readQuery}. */
+  handleReadJson(body: unknown, context: ApiContext<User>): Promise<QueryReadResponse>;
+  /** Accepts `{envelope}` (one) or `{envelopes: [...]}` (an in-order batch → array reply). */
+  handleMutateJson(
+    body: unknown,
+    context: ApiContext<User>,
+  ): Promise<PushMutationResponse | PushMutationResponse[]>;
+}
+
+export type RindleApiErrorCode = "bad-request" | "forbidden" | "not-found" | "rejected";
+
+export class RindleApiError extends Error {
+  readonly code: RindleApiErrorCode;
+  readonly status: number;
+
+  constructor(code: RindleApiErrorCode, message: string, status: number) {
+    super(message);
+    this.name = "RindleApiError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * A read/write-split `RindleDaemonClient` (READ-ROUTER-DESIGN.md §2.1). Writes
+ * (`executeSqlTxn` / `rejectMutation` / `applyRowChangeTxn` / `migrate`) go to the single
+ * write-master, UNCHANGED and never through the router; reads (`materialize` / `query` /
+ * `dematerialize`) go to the read router. Hand one of these to {@link createRindleApiServer} as
+ * `daemon` to point the reads leg at the router while writes stay on the master — no placement
+ * logic enters the api-server.
+ *
+ * ```ts
+ * const daemon = new SplitDaemonClient(
+ *   new HttpRindleDaemonClient({ baseUrl: MASTER_URL, headers: writeAuth }),  // writes → master
+ *   new HttpRindleDaemonClient({ baseUrl: ROUTER_URL, headers: routerAuth }), // reads  → router
+ * );
+ * ```
+ */
+export class SplitDaemonClient implements RindleDaemonClient {
+  private readonly writes: RindleDaemonClient;
+  private readonly reads: RindleDaemonClient;
+
+  constructor(writes: RindleDaemonClient, reads: RindleDaemonClient) {
+    this.writes = writes;
+    this.reads = reads;
+  }
+
+  // writes → the single master, never through the router
+  executeSqlTxn(input: SqlTxn): Promise<SqlTxnOutput> {
+    return this.writes.executeSqlTxn(input);
+  }
+  rejectMutation(input: MutationRejection): Promise<MutationRejectionOutput> {
+    return this.writes.rejectMutation(input);
+  }
+  applyRowChangeTxn(input: RowChangeTxn): Promise<RowChangeTxnOutput> {
+    return this.writes.applyRowChangeTxn(input);
+  }
+  migrate(input: MigrateInput): Promise<MigrateOutput> {
+    return this.writes.migrate(input);
+  }
+
+  // reads → the router (it stamps `wsEndpoint` onto the outputs)
+  materialize(input: MaterializeInput): Promise<MaterializeOutput> {
+    return this.reads.materialize(input);
+  }
+  query(input: QueryOnceInput): Promise<QueryOnceOutput> {
+    return this.reads.query(input);
+  }
+  dematerialize(input: DematerializeInput): Promise<DematerializeOutput> {
+    return this.reads.dematerialize(input);
+  }
+}
+
+export function defineApiQueries<User, Q extends ApiQueries<User>>(queries: Q): Q {
+  return queries;
+}
+
+/**
+ * Register a list of co-located client {@link NamedQuery `defineQuery`} values as the server's query
+ * surface — the bulk, no-boilerplate counterpart to {@link defineApiQueries}. Each query already
+ * carries its wire `name` and a `resolve` that re-runs its validator on the UNTRUSTED wire args and
+ * builds the authoritative `Query`, so the server just imports every co-located query and hands the
+ * list here. The same validated args build a byte-identical AST on both tiers.
+ *
+ * The query's AUTHORITATIVE {@link ApiContext} is forwarded as `resolve`'s ctx — so a context-scoped
+ * `defineQuery` (e.g. "my issues") is built from the server's trusted principal, never the client's.
+ * A context-free query simply ignores the extra argument.
+ *
+ * Use {@link defineApiQueries} instead (or in addition) only when the server must DIVERGE from the
+ * client — define a server-specific `defineQuery` with the same name and register that.
+ *
+ * ```ts
+ * queries: registerQueries<User>([issuesPageQuery, issueDetailQuery, recentCommentsQuery, usersQuery]),
+ * ```
+ */
+export function registerQueries<User>(queries: readonly NamedQuery<any, any, any>[]): ApiQueries<User> {
+  const out: Record<string, ApiQuery<User, any>> = {};
+  for (const query of queries) {
+    if (Object.prototype.hasOwnProperty.call(out, query.queryName)) {
+      throw new Error(`registerQueries: duplicate query name "${query.queryName}"`);
+    }
+    out[query.queryName] = (ctx, args) => query.resolve(args, ctx);
+  }
+  return out;
+}
+
+export function defineApiMutators<User, M extends ApiMutators<User>>(mutators: M): M {
+  return mutators;
+}
+
+export function queryResultToAst(result: ApiQueryResult): Ast {
+  if (result && typeof result === "object" && "ast" in result && typeof result.ast === "function") {
+    return result.ast();
+  }
+  return result as Ast;
+}
+
+export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptions<User>): RindleApiServer<User> {
+  const routes = { ...DEFAULT_RINDLE_API_ROUTES, ...opts.routes };
+  const mode = opts.mode ?? "normalized";
+  // 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));
+
+  // Resolve a named query (+ args) to its AST under a given context — the shared path for both
+  // a per-viewer lease and a system-level pin (which skips per-user authorization).
+  const resolveAst = async (name: string, args: unknown, context: ApiContext<User>): Promise<Ast> => {
+    const query = opts.queries?.[name];
+    if (!query) throw new RindleApiError("not-found", `unknown query: ${name}`, 404);
+    const result = opts.runQuery
+      ? await opts.runQuery({ user: context.user, name, args, query, context })
+      : await query(context, args as never);
+    return queryResultToAst(result);
+  };
+
+  const createQueryLease = async (input: QueryLeaseRequest<User>): Promise<QueryLeaseResponse> => {
+    const context: ApiContext<User> = { user: input.user, request: input.request };
+    await assertAuthorized(opts.authorizeQuery, {
+      user: input.user,
+      name: input.name,
+      args: input.args,
+      context,
+    });
+    const ast = await resolveAst(input.name, input.args, context);
+    // Lazy pin tier (§4.1): a leased query that is ALSO a configured pin is materialized with a
+    // `pinned` policy regardless of the configured default, so it survives its first viewer's
+    // departure. Otherwise use the configured policy.
+    const policy = pinnedNames.has(input.name)
+      ? ({ kind: "pinned", name: input.name } as MaterializationPolicy)
+      : await resolvePolicy(opts.materializationPolicy, input);
+    const subject = await resolveSubject(opts.subject, input);
+    const routingKey = await resolveRoutingKey(opts.routingKey, input);
+    const out = await opts.daemon.materialize({
+      ast,
+      mode,
+      policy,
+      subject,
+      leaseTtlMs: opts.leaseTtlMs,
+      // The anonymous routing key rides `metadata.routingKey`; the router keys on
+      // `subject ?? metadata.routingKey` (§2.2). Omitted when there is none.
+      metadata: routingKey !== undefined ? { routingKey } : undefined,
+    });
+    return queryLeaseResponse(out);
+  };
+
+  const readQuery = async (input: QueryReadRequest<User>): Promise<QueryReadResponse> => {
+    const context: ApiContext<User> = { user: input.user, request: input.request };
+    // Same per-viewer gate a live lease passes — a one-shot read returns the same rows a subscribe
+    // would, so it must clear the same authorization.
+    await assertAuthorized(opts.authorizeQuery, {
+      user: input.user,
+      name: input.name,
+      args: input.args,
+      context,
+    });
+    const ast = await resolveAst(input.name, input.args, context);
+    // Scope the one-shot's dedup `QueryKey` by the SAME key the lease path routes on — the routing
+    // key (`subject ?? cookie ?? clientId`) — so the warm pipeline this read leaves behind is the
+    // very one the browser's follow-up `subscribe` reuses, ON THE SAME FOLLOWER HRW will place it
+    // (the warm handoff, SSR-DESIGN.md §3.4 / READ-ROUTER-DESIGN.md §2.4) rather than a second,
+    // viewer-mismatched materialization.
+    const subject = await resolveSubject(opts.subject, input);
+    const routingKey = await resolveRoutingKey(opts.routingKey, input);
+    const visibilityKey = subject ?? routingKey;
+    const out = await opts.daemon.query({ ast, visibilityKey, ttlMs: opts.readIdleTtlMs });
+    const res: QueryReadResponse = { rows: out.rows, cvMin: out.cvMin, queryKey: out.queryKey };
+    if (out.wsEndpoint !== undefined) res.wsEndpoint = out.wsEndpoint;
+    return res;
+  };
+
+  const pushMutation = async (input: PushMutationRequest<User>): Promise<PushMutationResponse> => {
+    const context: ApiContext<User> = { user: input.user, request: input.request };
+    const mutator = opts.mutators?.[input.envelope.name];
+    if (!mutator) return reject(opts.daemon, input.envelope, `unknown mutator: ${input.envelope.name}`);
+    let sql: Pick<SqlTxn, "statements" | "idempotencyKey">;
+    try {
+      await assertAuthorized(opts.authorizeMutation, {
+        user: input.user,
+        envelope: input.envelope,
+        context,
+      });
+      const tx = new CollectingSqlMutationTx();
+      const result = await mutator(tx, input.envelope.args as never, {
+        user: input.user,
+        envelope: input.envelope,
+        daemon: opts.daemon,
+        request: input.request,
+      });
+      sql = mutationResultToSqlTxn(result, tx);
+    } catch (err) {
+      return reject(opts.daemon, input.envelope, String((err as Error)?.message ?? err));
+    }
+    const output = await opts.daemon.executeSqlTxn({
+      ...sql,
+      clientID: input.envelope.clientID,
+      mid: input.envelope.mid,
+    });
+    return { accepted: true, rejected: false, output };
+  };
+
+  const pushMutations = async (input: PushMutationsRequest<User>): Promise<PushMutationResponse[]> => {
+    const out: PushMutationResponse[] = [];
+    for (const envelope of input.envelopes) {
+      out.push(await pushMutation({ user: input.user, envelope, request: input.request }));
+    }
+    return out;
+  };
+
+  const assertPins = async (): Promise<void> => {
+    const pins = opts.pinnedQueries;
+    if (!pins?.length) return;
+    const context: ApiContext<User> = { user: opts.pinUser as User, request: undefined };
+    // Resolve every pin's authoritative AST under the system pin user (a transient failure on one
+    // shouldn't strand the rest), then drive the warm-up — fleet fan-out via the router if
+    // configured, else one materialize per pin on the single daemon.
+    const resolved = await Promise.allSettled(
+      pins.map(async (pin) => ({
+        pin,
+        req: {
+          ast: await resolveAst(pin.name, pin.args ?? null, context),
+          mode,
+          policy: { kind: "pinned", name: pin.name } as MaterializationPolicy,
+          leaseTtlMs: opts.leaseTtlMs,
+        } satisfies MaterializeInput,
+      })),
+    );
+    const failures: string[] = [];
+    const pairs: Array<{ pin: PinnedQuery; req: MaterializeInput }> = [];
+    resolved.forEach((r, i) => {
+      if (r.status === "fulfilled") pairs.push(r.value);
+      else failures.push(`${pins[i].name}: ${errMessage(r.reason)}`);
+    });
+    const reqs = pairs.map((p) => p.req);
+    if (reqs.length) {
+      if (opts.pinFanout) {
+        // Push tier (§4.2): fan EACH pin across ALL live followers via the router (fire-and-forget,
+        // router-stateless). A whole-fan-out failure is surfaced so the caller retries.
+        try {
+          await opts.pinFanout.assertPins(reqs);
+        } catch (e) {
+          failures.push(errMessage(e));
+        }
+      } else {
+        // Single-daemon: materialize each pin once (the daemon dedups by canonical query).
+        const results = await Promise.allSettled(reqs.map((req) => opts.daemon.materialize(req)));
+        results.forEach((r, i) => {
+          if (r.status === "rejected") failures.push(`${pairs[i].pin.name}: ${errMessage(r.reason)}`);
+        });
+      }
+    }
+    if (failures.length) {
+      throw new Error(`assertPins: ${failures.length} failed — ${failures.join("; ")}`);
+    }
+  };
+
+  return {
+    routes,
+    createQueryLease,
+    readQuery,
+    assertPins,
+    pushMutation,
+    pushMutations,
+    handleQueryJson: (body, context) => {
+      const msg = parseObject(body, "query request");
+      return createQueryLease({
+        user: context.user,
+        name: parseString(msg.name, "name"),
+        args: msg.args ?? null,
+        request: context.request,
+        clientId: typeof msg.clientId === "string" ? msg.clientId : undefined,
+      });
+    },
+    handleReadJson: (body, context) => {
+      const msg = parseObject(body, "read request");
+      return readQuery({
+        user: context.user,
+        name: parseString(msg.name, "name"),
+        args: msg.args ?? null,
+        request: context.request,
+        clientId: typeof msg.clientId === "string" ? msg.clientId : undefined,
+      });
+    },
+    handleMutateJson: (body, context) => {
+      const msg = parseObject(body, "mutation request");
+      if (Array.isArray(msg.envelopes)) {
+        return pushMutations({
+          user: context.user,
+          envelopes: msg.envelopes.map(parseEnvelope),
+          request: context.request,
+        });
+      }
+      const envelope = parseEnvelope(msg.envelope ?? msg);
+      return pushMutation({ user: context.user, envelope, request: context.request });
+    },
+  };
+}
+
+class CollectingSqlMutationTx implements SqlMutationTx {
+  private readonly stmts: SqlStatement[] = [];
+
+  get statements(): readonly SqlStatement[] {
+    return this.stmts;
+  }
+
+  exec(sql: string, params: WireValue[] = []): void {
+    this.stmts.push({ sql, params });
+  }
+}
+
+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 };
+  }
+  return { statements: [...tx.statements] };
+}
+
+async function assertAuthorized<T>(authorizer: Authorizer<T> | undefined, input: T): Promise<void> {
+  if (!authorizer) return;
+  const result = await authorizer(input);
+  if (result === false) throw new RindleApiError("forbidden", "rindle request forbidden", 403);
+}
+
+async function resolvePolicy<User>(
+  policy: RindleApiServerOptions<User>["materializationPolicy"],
+  input: QueryLeaseRequest<User>,
+): Promise<MaterializationPolicy> {
+  if (!policy) return { kind: "whileSubscribed" };
+  return typeof policy === "function" ? await policy(input) : policy;
+}
+
+async function resolveSubject<User>(
+  subject: RindleApiServerOptions<User>["subject"],
+  input: QueryLeaseRequest<User>,
+): Promise<string | undefined> {
+  if (typeof subject === "function") return subject(input);
+  return subject;
+}
+
+/** Resolve the anonymous routing key (READ-ROUTER-DESIGN.md §2.2): an explicit value/resolver if
+ *  configured, otherwise the browser-supplied `clientId`. The router keys on `subject ?? this`. */
+async function resolveRoutingKey<User>(
+  routingKey: RindleApiServerOptions<User>["routingKey"],
+  input: QueryLeaseRequest<User>,
+): Promise<string | undefined> {
+  if (routingKey === undefined) return input.clientId;
+  return typeof routingKey === "function" ? routingKey(input) : routingKey;
+}
+
+function queryLeaseResponse(out: MaterializeOutput): QueryLeaseResponse {
+  const res: QueryLeaseResponse = {
+    leaseToken: out.leaseToken,
+    materializationId: out.materializationId,
+    queryKey: out.queryKey,
+    reused: out.reused,
+  };
+  // Only present in a routed deploy — absent reproduces today's single-daemon response exactly.
+  if (out.wsEndpoint !== undefined) res.wsEndpoint = out.wsEndpoint;
+  return res;
+}
+
+function errMessage(reason: unknown): string {
+  return String((reason as Error)?.message ?? reason);
+}
+
+async function reject(
+  daemon: RindleDaemonClient,
+  envelope: MutationEnvelope,
+  reason: string,
+): Promise<PushMutationResponse> {
+  const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+  return { accepted: false, rejected: true, reason, output };
+}
+
+function parseObject(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new RindleApiError("bad-request", `invalid ${label}`, 400);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseString(value: unknown, label: string): string {
+  if (typeof value !== "string") throw new RindleApiError("bad-request", `invalid ${label}`, 400);
+  return value;
+}
+
+function parseEnvelope(value: unknown): MutationEnvelope {
+  const obj = parseObject(value, "mutation envelope");
+  return {
+    clientID: parseString(obj.clientID, "clientID"),
+    mid: parseNumber(obj.mid, "mid"),
+    name: parseString(obj.name, "name"),
+    args: obj.args ?? null,
+  };
+}
+
+function parseNumber(value: unknown, label: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new RindleApiError("bad-request", `invalid ${label}`, 400);
+  }
+  return value;
+}