@rindle/room 0.5.0

package/src/shell.ts

@@ -0,0 +1,1859 @@
+// The Node test shell (RINDLE-REALTIME-DESIGN.md §11, P0/P1): a plain process running
+// the SAME wasm build the Durable Object shell will run, wired to real sockets.
+//
+//   rindled ──ws (normalized protocol)──▶ WasmRoom (base store) ──serving──▶ subscribers
+//            upstream leg (§3)                                   downstream leg (§4)
+//
+// Both legs speak the one protocol. Upstream, the shell is a client of rindled's public
+// ws plane: `init` → `subscribe {queryId, leaseToken}` → `nhello` → seq-0 `nbatch` →
+// live tail; the lease is minted on rindled's private control plane (`POST /materialize`)
+// — the room fetches its own footprint lease at boot, the same shape as the DO shell's
+// boot callback (§10.1). Downstream, the shell serves the `@rindle/remote` wire verbatim,
+// gated by **self-authorizing signed lease tokens** (§10.1): `subscribe {queryId,
+// leaseToken}` verifies the token (signature, doc, expiry, revocation) and materializes
+// the approved AST it carries on presentation — no `/materialize` control call, no named
+// registry, ASTs never composed by clients. Identical queries share one pipeline
+// (QueryKey dedup in the wasm room); each subscriber gets its own epoch/seq envelope.
+//
+// Lease lifecycle (§4.1): tokens are short-lived; the shell drops any subscription whose
+// lease passes `exp` unrenewed (a `queryError`, then detach — renewal is
+// re-authorization through the API server, which is a fresh subscribe with a fresh
+// token). The private control plane's `POST /revoke {userId}` terminates a user's
+// subscriptions and sockets immediately and refuses pre-revocation tokens (`iat` <
+// revocation) — the synchronous layer; the TTL is the backstop.
+//
+// The write path (§5.1, P2 — no write-behind yet): a connection `init`s its clientID,
+// then pushes `{t:"pushMutation", envelope:{clientID, mid, name, args}}` frames. Per
+// mutation: dedup/gap-check → run the registered mutator against a staged wasm tx →
+// commit to the shared head → fan the data `nbatch`es out IMMEDIATELY (step 2: fanout
+// is never gated on durability) → append the envelope to the journal under a ≤~5ms
+// group commit → on append, ACK: advance the author's `_rindle_client_mutations` row
+// and fan the lmid frame (step 4: the ack a client observes survives a process crash
+// by construction — §8.1). A failed/unknown mutator is a silent reject that still
+// consumes the mid (the ledger advances with no effects; the author's prediction snaps
+// back — `rindle-replica`'s contract). On boot, the journal replays by RE-INVOKING the
+// mutators against the fresh base (§3.3), then acks everything replayed.
+//
+// Release protocol: every downstream `nbatch` is stamped with the room's `head_cv`,
+// and after each drain the shell sends the connection-level `{t:"progress",
+// frame:{cvMin}}` the optimistic client releases on. One §1.3.1-coherence rule: the
+// AUTHOR's cvMin holds below its oldest un-acked mutation's apply-cv until the ack
+// lands (data released before its lmid advance would make the client re-invoke a
+// confirmed mutation on top of its own effect); everyone else releases at head_cv.
+//
+// Backpressure (§9, T8): each downstream socket has a bounded send budget. A stalled
+// client that overflows it is TERMINATED with a gap — the normalized protocol's
+// re-subscribe repair — so one slow client never holds frames in room memory.
+//
+// Failure posture (§3.4): the room is an INCARNATION. Any upstream violation — a frame
+// that fails to decode, a seq gap, a poisoned apply, an upstream `queryError`, the
+// socket dropping — kills the incarnation: the wasm store is freed, every downstream
+// socket is closed (subscriptions die with the incarnation; reconnecting clients
+// re-subscribe against the next one), and the shell re-subscribes upstream. On the same
+// socket that is a `subscribe` re-send (rindled bumps the epoch and re-snapshots); on a
+// fresh socket it is a new subscription. There is no patch-up path, by design.
+
+import { createServer, type Server } from "node:http";
+import { randomUUID } from "node:crypto";
+
+import { WebSocket, WebSocketServer, type RawData } from "ws";
+
+import { initRoomWasm, WasmRoom } from "./wasm.ts";
+import { verifyRoomToken, RoomTokenError, scopeSpecsHash } from "./token.ts";
+import {
+  assertSyncMutatorReturn,
+  isEnvironmentShortfall,
+  mutationTx,
+  type RoomMutator,
+  type TableShape,
+} from "./mutation-tx.ts";
+import {
+  journalEntryOutcome,
+  memoryJournal,
+  type RoomJournal,
+  type RoomJournalEntry,
+} from "./journal.ts";
+import type { RoomAuthority } from "./authority.ts";
+
+/** The upstream half of the shell's config: where rindled lives and what to follow. */
+export interface UpstreamOptions {
+  /** rindled's public subscription plane, e.g. `ws://127.0.0.1:7601`. */
+  wsUrl: string;
+  /** rindled's private control plane, e.g. `http://127.0.0.1:7600` (lease minting). */
+  controlUrl: string;
+  /** Bearer token for the control plane (required unless rindled runs unauthenticated). */
+  authToken?: string;
+  /** The document footprint — a wire `Ast` (§3.1). What this room follows and serves from. */
+  footprintAst: unknown;
+  /** Lease TTL passed to `/materialize` (rindled's default when omitted). */
+  leaseTtlMs?: number;
+  /** The `init` clientID on the upstream socket (diagnostic identity). */
+  clientId?: string;
+}
+
+/** The downstream half: how clients are authorized and served (§4/§10.1). */
+export interface DownstreamOptions {
+  /** This room's document id — lease tokens for any other doc are refused. */
+  docId: string;
+  /** Token key ring: `kid` → shared secret (the API server signs with the same ring). */
+  tokenKeys: Record<string, string>;
+  /** Idle grace before an unsubscribed query's pipeline is reclaimed (default 30s). */
+  idleTtlMs?: number;
+  /** Lease-expiry / idle-sweep cadence (default 1s). */
+  sweepIntervalMs?: number;
+  /** How long a revocation keeps refusing pre-revocation tokens (default 30min — set
+   *  it ≥ the longest token TTL the API server mints). */
+  revocationWindowMs?: number;
+  /** The room's private control plane (`POST /revoke`, `GET /stats`). Omit to run
+   *  without one (no revocation surface). */
+  control?: { authToken: string; port?: number };
+  /** The write plane (§5.1). Omit to run read-only (writes are refused). */
+  writes?: WritesOptions;
+  /** Per-socket downstream send budget in bytes (§9; default 4 MiB). A socket whose
+   *  queued bytes would exceed it is terminated with a gap — re-subscribing is the
+   *  repair. */
+  sendBudgetBytes?: number;
+}
+
+/** One table's §3.3 scope spec (H-iv-b): an element of the api-server's
+ *  `RoomBootResponse.scopes`, passed VERBATIM to the wasm room's `enableWritesV2`.
+ *  Structurally identical to `@rindle/api-server`'s `RoomScopeSpec` (declared locally —
+ *  the shell must not depend on the api-server package; TS structural typing keeps the
+ *  two in lockstep at the host's threading site). */
+export interface RoomScopeSpec {
+  table: string;
+  /** The footprint's row-local predicate for this table (a wire `Condition`) — drives
+   *  the commit gate's absent-read proof. Absent ⇒ absent reads on this table always
+   *  deopt (fail closed). */
+  footprintWhere?: unknown;
+  writable:
+    | { kind: "none" }
+    | { kind: "predicate"; where?: unknown; joinKeyCols: string[] };
+}
+
+/** The §5.1 write plane: the room's own mutator registry over its owned tables. */
+export interface WritesOptions {
+  /** The server registry (§4.2): named mutators run against the shared head. PLAIN
+   *  synchronous `(tx, args, ctx)` functions only — a `shared(...)` GENERATOR registry
+   *  does NOT register verbatim (nothing drives it here; the shell rejects a mutator
+   *  that returns a generator/promise — see `assertSyncMutatorReturn`). */
+  mutators: Record<string, RoomMutator>;
+  /** §3.2's owned set — the only tables mutators may write. Must all be in the
+   *  upstream footprint; followed tables and the ledger are never writable. */
+  ownedTables: string[];
+  /** The §3.3 per-table scope specs from the boot wire (`RoomBootResponse.scopes` —
+   *  H-iv-b). Present ⇒ the write plane enables in v2 GATED mode (`enableWritesV2`):
+   *  staged writes validate against the writable predicates, join-key edits refuse,
+   *  absent reads must prove against `footprintWhere`, context (`kind:"none"`) tables
+   *  become txGet-READABLE, and a violating commit returns a structured DEOPT instead
+   *  of applying. The scopes' writable tables must be a SUBSET of {@link ownedTables}
+   *  (the host's own declaration) — a wider server scope throws at construction, so a
+   *  self-hoster's owned set can never be extended from the wire. Absent ⇒ the v1
+   *  table-granular write plane, byte-identical to before. */
+  scopes?: RoomScopeSpec[];
+  /** The durable sidecar an ack means (§8.1). Defaults to `memoryJournal()` — the
+   *  "survives nothing beyond the process" class; hosts bring their own. */
+  journal?: RoomJournal;
+  /** The journal group-commit window (default 5ms): mutations arriving within it
+   *  share one append, and their acks ride one ledger commit. */
+  groupCommitMs?: number;
+  /** The write authority (§5.3.1) — the API server's `/apply-row-change-txn` host
+   *  (or the P3 gate's mock). Omit to run journal-only (P2 semantics: nothing is
+   *  ever durable upstream). With an authority, the shell claims a placement epoch
+   *  at boot, probes durable lmids before replay, and write-behinds on the flush
+   *  cadence (§5.3). */
+  authority?: RoomAuthority;
+  /** The flush debounce (§5.3; default 250ms, within the design's ≤1s budget). */
+  flushDebounceMs?: number;
+  /** Flush immediately once this many keys are dirty (default 512). */
+  flushDirtyMax?: number;
+}
+
+export interface RoomShellOptions {
+  upstream: UpstreamOptions;
+  downstream: DownstreamOptions;
+  /** Downstream ws port (default 0 = ephemeral; bound on 127.0.0.1). */
+  port?: number;
+  /** Diagnostic sink (default: silent). */
+  log?: (line: string) => void;
+}
+
+export interface RoomShell {
+  /** The bound downstream port. */
+  readonly port: number;
+  /** The bound control-plane port (0 when no control plane was configured). */
+  readonly controlPort: number;
+  /** Resolves when the CURRENT incarnation is live (seq-0 snapshot applied);
+   *  immediately if it already is. */
+  awaitLive(): Promise<void>;
+  /** The last-applied upstream commit version, if live. */
+  cv(): number | undefined;
+  /** The upstream subscription epoch of the current incarnation, if any. */
+  upstreamEpoch(): number | undefined;
+  /** This incarnation's downstream bootId (rotates on every re-subscribe). */
+  bootId(): string;
+  /** Fire the write-behind flush now (instead of the debounce) and await its
+   *  settlement — deterministic flushing for tests and drain-before-close. No-op
+   *  without an authority. */
+  flushNow(): Promise<void>;
+  close(): Promise<void>;
+}
+
+const UPSTREAM_QID = 1;
+/** Delay before re-subscribing after a violation — keeps a persistent violation from
+ *  becoming a hot loop while staying far below human-perceptible recovery time. */
+const RESUBSCRIBE_DELAY_MS = 250;
+const RECONNECT_MAX_MS = 5_000;
+const DEFAULT_IDLE_TTL_MS = 30_000;
+const DEFAULT_SWEEP_INTERVAL_MS = 1_000;
+const DEFAULT_REVOCATION_WINDOW_MS = 30 * 60_000;
+const DEFAULT_GROUP_COMMIT_MS = 5;
+const DEFAULT_SEND_BUDGET_BYTES = 4 * 1024 * 1024;
+const DEFAULT_FLUSH_DEBOUNCE_MS = 250;
+const DEFAULT_FLUSH_DIRTY_MAX = 512;
+/** §4.2 drain-before-downgrade iteration cap: a healthy room quiesces in a handful of flushes; a
+ *  runaway (a straggler push per flush, or a wedged CAS loop) fails LOUD rather than spinning. */
+const DRAIN_MAX_ITERATIONS = 100;
+/** Flush-retry backoff bounds (network-class failures only; same journaled bytes). */
+const FLUSH_RETRY_MIN_MS = 100;
+const FLUSH_RETRY_MAX_MS = 2_000;
+/** The reserved lmid system query — subscribed BY NAME even in lease mode; identity
+ *  comes from the connection's `init`, never from args. */
+const LMID_QUERY_NAME = "_rindle/clientLmid";
+
+/** Mint the room's upstream footprint lease on rindled's control plane (§4: the room
+ *  fetches its own lease — on the DO shell this is the boot callback's job). */
+async function mintLease(up: UpstreamOptions): Promise<string> {
+  const res = await fetch(new URL("/materialize", up.controlUrl), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(up.authToken ? { authorization: `Bearer ${up.authToken}` } : {}),
+    },
+    body: JSON.stringify({
+      ast: up.footprintAst,
+      ...(up.leaseTtlMs !== undefined ? { leaseTtlMs: up.leaseTtlMs } : {}),
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`upstream /materialize failed: ${res.status} ${await res.text()}`);
+  }
+  const out = (await res.json()) as { leaseToken?: string };
+  if (typeof out.leaseToken !== "string") {
+    throw new Error("upstream /materialize returned no leaseToken");
+  }
+  return out.leaseToken;
+}
+
+function send(ws: WebSocket, frame: unknown): void {
+  if (ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(frame));
+  }
+}
+
+/** One downstream subscription's routing + lease state (keyed by its wasm subKey). */
+interface SubMeta {
+  ws: WebSocket;
+  conn: ConnState;
+  clientQid: number;
+  /** The token's subject — the §4.1 revocation key. */
+  user: string;
+  /** The token's expiry — enforced by the sweep (drop at `exp` unrenewed). */
+  exp: number;
+}
+
+interface ConnQuery {
+  subKey: string;
+  epoch: number;
+}
+
+interface ConnState {
+  id: number;
+  ws: WebSocket;
+  queries: Map<number, ConnQuery>;
+  /** Serializes message handling per connection (token verify is async; a client's
+   *  subscribe/unsubscribe order must hold). */
+  busy: Promise<void>;
+  /** The `init` identity — what the lmid subscribe and pushMutation key on. An
+   *  idempotency key, NOT an identity (it is client-supplied). */
+  clientID: string | null;
+  /** The connection's AUTHENTICATED subject (managed-writes §3.1): the `sub` of the
+   *  first verified lease token presented on this connection. Shell-stamped, one
+   *  principal per connection, and the gate `pushMutation` requires. */
+  sub: string | null;
+}
+
+/** One mutation applied to the head but not yet acked: the author's release point
+ *  holds below `applyCv` until the journal append lands (§1.3.1 coherence — see the
+ *  module docs' release-protocol note). */
+interface UnackedMutation {
+  mid: number;
+  applyCv: number;
+}
+
+/** A recorded NON-APPLIED verdict (H-iv-b): what the `mutationOutcome` frame carries,
+ *  and what a re-sent mid whose `beginMutation` dedups is re-answered with. `name`/
+ *  `args` are kept for DEOPT verdicts only — the frame must be self-contained (a
+ *  client that already retired the entry re-invokes from the frame). */
+interface RecordedOutcome {
+  kind: "deopt" | "rejected";
+  reason?: string;
+  name?: string;
+  args?: unknown;
+}
+
+/** Per-client retention cap for {@link RecordedOutcome}s. The map only holds
+ *  NON-APPLIED mids, and a client only re-sends a mid while its ledger lmid trails it
+ *  — a contiguously-advancing window bounded by the client's in-flight backlog, far
+ *  below this cap. Past it the oldest records evict (insertion order): a re-send of an
+ *  evicted mid degrades to today's silence — the mid still dedups and the ledger still
+ *  covers it, only the outcome re-answer is lost. */
+const MAX_RECORDED_OUTCOMES_PER_CLIENT = 512;
+
+class Shell implements RoomShell {
+  private readonly opts: RoomShellOptions;
+  private readonly log: (line: string) => void;
+  private readonly wss: WebSocketServer;
+  private control: Server | null = null;
+
+  private room: WasmRoom | null = null;
+  private live = false;
+  private incarnationBootId = randomUUID();
+  private liveWaiters: Array<() => void> = [];
+
+  private upstream: WebSocket | null = null;
+  private leaseToken = "";
+  private subscribeInFlight = false;
+  private reconnectDelayMs = RESUBSCRIBE_DELAY_MS;
+  private closed = false;
+  private nextConnId = 1;
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** subKey (what the wasm room routes by) → where its frames go + lease state. */
+  private readonly subs = new Map<string, SubMeta>();
+  /** Every open downstream connection — revocation must reach a BOUND conn even when
+   *  it holds no live subscription (it is still write-capable). */
+  private readonly conns = new Set<ConnState>();
+  /** userId → when they were revoked (refuses tokens with `iat` ≤ this; pruned after
+   *  the revocation window). */
+  private readonly revoked = new Map<string, number>();
+  /** Downstream subscribes queued while no incarnation is live. */
+  private pendingSubs: Array<{ ws: WebSocket; conn: ConnState; msg: SubscribeMsg }> = [];
+
+  // ------------------------------ write-plane state ------------------------------
+  /** The {@link scopeSpecsHash} of the boot-wire scopes THIS shell armed its §3.3 gate
+   *  with — `undefined` in v1 (ungated) mode. Compared against each lease token's
+   *  `scopesHash` to flag scope skew (a profile edited under this live room), which
+   *  otherwise manifests only as an undiagnosable deopt loop. */
+  private readonly armedScopesHash: string | undefined;
+  /** Scope-skew hash pairs already logged (`lease→armed`), so the diagnostic fires ONCE
+   *  per distinct skew, not once per subscribe. */
+  private readonly loggedScopeSkew = new Set<string>();
+  /** The journal (write plane only). One per shell — it outlives incarnations; that
+   *  is the point (§3.3: pending is replayed from it on every re-subscribe). */
+  private journal: RoomJournal | null = null;
+  /** Positional table shapes from the upstream hello (keyed layer of MutationTx). */
+  private tableShapes = new Map<string, TableShape>();
+  /** Mutations queued while no incarnation is live (drained after pendingSubs). */
+  private pendingMutes: Array<{ ws: WebSocket; conn: ConnState; envelope: PushEnvelope }> = [];
+  /** clientID → its applied-but-unacked mutations, oldest first (release holdback). */
+  private readonly unacked = new Map<string, UnackedMutation[]>();
+  /** clientID → its recorded NON-APPLIED outcomes (mid → verdict), insertion-ordered
+   *  and capped per client ({@link MAX_RECORDED_OUTCOMES_PER_CLIENT}). Seeded from the
+   *  journal replay each incarnation (`finishBoot` — so it reflects what THIS
+   *  incarnation's replay produced), appended live, and cleared with the incarnation. */
+  private readonly outcomes = new Map<string, Map<number, RecordedOutcome>>();
+  /** The group-commit window: entries awaiting the next journal append. */
+  private ackQueue: RoomJournalEntry[] = [];
+  private ackTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Serializes journal appends (one in flight; acks apply in append order). */
+  private ackChain: Promise<void> = Promise.resolve();
+
+  // ------------------------------ flush state (§5.3) ------------------------------
+  /** The placement epoch (§2.5), claimed once per shell process at start. 0 = no
+   *  authority configured. */
+  private placementEpoch = 0;
+  /** The next flush-stream seq — also the (zero-padded) wire offset. Seeded from the
+   *  journal so offset strings stay monotone across restarts sharing one journal. */
+  private flushSeq = 1;
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  /** One flush settlement in flight at a time (the wasm room guards too). */
+  private flushBusy = false;
+  /** The settlement chain `flushNow()` awaits. */
+  private flushChain: Promise<void> = Promise.resolve();
+  private flushesConfirmed = 0;
+  /** The last flush seq that COMMITTED at the authority (§4.2/§5.4 `flush_ok`): the value the
+   *  `/drain` control reports as `finalFlushSeq`, the fence a downgraded client's ghost waits on
+   *  (`_rindle_room_watermark(doc) ≥ finalFlushSeq`, and the watermark row's `flush_seq` IS this
+   *  offset — consumer.rs). Seeded from the journal at boot (a re-booted room that already flushed
+   *  reports its journaled max, not 0); 0 for a never-flushed room. */
+  private lastCommittedFlushSeq = 0;
+  /** Fenced at the authority (§2.5): this room is superseded — terminal. */
+  private moved = false;
+
+  // --------------------- §301 upstream-absorption advert (301-ECHO-FENCE §1.2) ---------------------
+  /** The daemon boot id the upstream connection serves (each upstream `nhello` stamps it) —
+   *  rides the downstream progress frames as `upstreamBoot`, the §2.4 boot-rule input. */
+  private upstreamBoot: string | undefined;
+  /** The daemon's released `cvMin` this room has provably absorbed through — recorded from the
+   *  upstream `progress` frames (same-socket ordering: every nbatch at-or-below it was already
+   *  applied when the frame is read), NOT from the applied head cv (a sparse footprint would
+   *  starve the advert while the daemon advances). Rides downstream as `upstreamCv`;
+   *  `undefined` until the first upstream progress of the current daemon boot. */
+  private upstreamCvMin: number | undefined;
+
+  constructor(opts: RoomShellOptions) {
+    this.opts = opts;
+    this.log = opts.log ?? (() => {});
+    if (opts.downstream.writes) {
+      if (opts.downstream.writes.ownedTables.length === 0) {
+        throw new Error("writes.ownedTables must name at least one table");
+      }
+      // H-iv-b: the boot-wire scopes may only ever NARROW the host's owned set, never
+      // extend it — a wider server scope would let mutators write tables this
+      // deployment never declared writable (self-hoster semantics preserved). Loud at
+      // construction, exactly like the empty-owned check above.
+      const scopes = opts.downstream.writes.scopes;
+      if (scopes !== undefined) {
+        const owned = new Set(opts.downstream.writes.ownedTables);
+        const rogue = scopes
+          .filter((s) => s.writable.kind !== "none" && !owned.has(s.table))
+          .map((s) => s.table);
+        if (rogue.length > 0) {
+          throw new Error(
+            `writes.scopes marks ${rogue.map((t) => `\`${t}\``).join(", ")} writable, but the ` +
+              `host's writes.ownedTables does not include ${rogue.length === 1 ? "it" : "them"} — ` +
+              `the boot-wire scopes may only ever narrow the host's owned set, never extend it`,
+          );
+        }
+      }
+      // The armed-scope fingerprint: what the gate enforces, hashed once, for the
+      // skew check on the token path. `undefined` scopes = v1 ungated → no check.
+      if (scopes !== undefined) this.armedScopesHash = scopeSpecsHash(scopes);
+      this.journal = opts.downstream.writes.journal ?? memoryJournal();
+    }
+    this.wss = new WebSocketServer({ port: opts.port ?? 0, host: "127.0.0.1" });
+    this.wss.on("connection", (ws) => this.serveDownstream(ws));
+  }
+
+  async start(): Promise<void> {
+    await initRoomWasm();
+    await new Promise<void>((resolve) => {
+      if (this.wss.address() !== null) return resolve();
+      this.wss.on("listening", () => resolve());
+    });
+    if (this.opts.downstream.control) {
+      await this.startControl(this.opts.downstream.control);
+    }
+    const interval = this.opts.downstream.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    this.sweepTimer = setInterval(() => this.sweep(), interval);
+    this.sweepTimer.unref?.();
+    const authority = this.opts.downstream.writes?.authority;
+    if (authority && this.journal) {
+      // Seed the flush stream past everything this journal ever numbered, then claim
+      // the placement epoch (§2.5) — once per process, BEFORE anything else touches
+      // the authority: from this moment every stale body a dead predecessor left
+      // mid-network is fenced, which is what closes the probe race for good.
+      // Unconfirmed batches settle per incarnation in finishBoot — a prior process's
+      // records are fenced there (routine: their mutations recover by envelope
+      // replay under OUR epoch), our own land or dedup.
+      const { maxSeq } = await this.journal.replayFlushes();
+      this.flushSeq = maxSeq + 1;
+      this.lastCommittedFlushSeq = maxSeq; // journal-seeded (self-corrects upward on each flush_ok)
+      this.placementEpoch = await authority.claimEpoch(this.opts.downstream.docId);
+      this.log(`placement epoch ${this.placementEpoch}`);
+    }
+    this.leaseToken = await mintLease(this.opts.upstream);
+    this.connectUpstream();
+  }
+
+  get port(): number {
+    const addr = this.wss.address();
+    return typeof addr === "object" && addr !== null ? addr.port : 0;
+  }
+
+  get controlPort(): number {
+    const addr = this.control?.address();
+    return typeof addr === "object" && addr !== null ? addr.port : 0;
+  }
+
+  awaitLive(): Promise<void> {
+    if (this.live) return Promise.resolve();
+    return new Promise((resolve) => this.liveWaiters.push(resolve));
+  }
+
+  cv(): number | undefined {
+    return this.room?.cv();
+  }
+
+  upstreamEpoch(): number | undefined {
+    return this.room?.epoch();
+  }
+
+  bootId(): string {
+    return this.incarnationBootId;
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.sweepTimer) clearInterval(this.sweepTimer);
+    if (this.ackTimer !== null) {
+      clearTimeout(this.ackTimer);
+      this.ackTimer = null;
+    }
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.upstream?.close();
+    for (const client of this.wss.clients) client.close();
+    await new Promise<void>((resolve) => this.wss.close(() => resolve()));
+    if (this.control) {
+      await new Promise<void>((resolve) => this.control?.close(() => resolve()));
+    }
+    if (this.room) {
+      this.room.free();
+      this.room = null;
+    }
+  }
+
+  // ------------------------------ upstream leg ------------------------------
+
+  private connectUpstream(): void {
+    if (this.closed) return;
+    const ws = new WebSocket(this.opts.upstream.wsUrl);
+    this.upstream = ws;
+    ws.on("open", () => {
+      this.reconnectDelayMs = RESUBSCRIBE_DELAY_MS;
+      send(ws, {
+        t: "init",
+        clientID: this.opts.upstream.clientId ?? `room-shell-${this.incarnationBootId}`,
+      });
+      this.sendSubscribe();
+    });
+    ws.on("message", (data) => this.onUpstreamFrame(data));
+    ws.on("error", (err) => this.log(`upstream socket error: ${String(err)}`));
+    ws.on("close", () => {
+      if (this.closed) return;
+      // A subscribe may have died with the socket — the fresh connection must be free
+      // to send its own.
+      this.subscribeInFlight = false;
+      this.incarnationDead("upstream socket closed");
+      const delay = this.reconnectDelayMs;
+      this.reconnectDelayMs = Math.min(delay * 2, RECONNECT_MAX_MS);
+      this.log(`upstream reconnect in ${delay}ms`);
+      setTimeout(() => this.connectUpstream(), delay).unref?.();
+    });
+  }
+
+  /** (Re-)send the upstream subscribe. On an already-open socket rindled treats a
+   *  re-send for the same queryId as gap recovery: tears down the old attachment, bumps
+   *  the epoch, re-snapshots. */
+  private sendSubscribe(): void {
+    if (this.closed || this.subscribeInFlight) return;
+    if (this.upstream?.readyState !== WebSocket.OPEN) return; // reconnect path re-enters
+    this.subscribeInFlight = true;
+    send(this.upstream, { t: "subscribe", queryId: UPSTREAM_QID, leaseToken: this.leaseToken });
+  }
+
+  private onUpstreamFrame(data: RawData): void {
+    let frame: Record<string, unknown>;
+    try {
+      frame = JSON.parse(String(data)) as Record<string, unknown>;
+    } catch {
+      // Not even JSON: the transport is garbage — violation posture.
+      this.violation("upstream frame is not JSON");
+      return;
+    }
+    if (frame.queryId !== undefined && frame.queryId !== UPSTREAM_QID) return;
+    switch (frame.t) {
+      case "nhello": {
+        this.subscribeInFlight = false;
+        // §301: the daemon boot this connection now serves. A CHANGED boot resets the absorbed
+        // cv watermark — the new boot's cv space starts over, and the advert must never pair an
+        // old cv with a new boot (the client's §2.4 boot rule keys on the pair).
+        const boot = typeof frame.bootId === "string" ? frame.bootId : undefined;
+        if (boot !== this.upstreamBoot) {
+          this.upstreamBoot = boot;
+          this.upstreamCvMin = undefined;
+        }
+        // A hello supersedes any prior incarnation (e.g. rindled restarted and
+        // re-served us): the old store is gone either way.
+        if (this.room) this.incarnationDead("superseded by a new upstream hello");
+        try {
+          this.room = WasmRoom.open(
+            JSON.stringify(frame.hello),
+            this.opts.downstream.idleTtlMs ?? DEFAULT_IDLE_TTL_MS,
+          );
+          this.tableShapes = shapesOf(frame.hello);
+          this.log(`upstream hello: epoch ${this.room.epoch()}`);
+        } catch (e) {
+          this.violation(`upstream hello rejected: ${String(e)}`);
+        }
+        break;
+      }
+      case "nbatch": {
+        if (!this.room) return; // pre-hello or post-death stragglers: drop
+        let status: { applied: string; rows?: number; ops?: number };
+        try {
+          status = JSON.parse(this.room.apply(JSON.stringify(frame.batch))) as typeof status;
+        } catch (e) {
+          this.violation(`upstream apply failed: ${String(e)}`);
+          return;
+        }
+        if (status.applied === "snapshot") {
+          this.log(`upstream snapshot: ${status.rows} rows @ cv ${this.room.cv()}`);
+          void this.finishBoot(this.room);
+        } else if (status.applied === "live") {
+          this.drainDownstream();
+        } else if (status.applied === "staleEpoch") {
+          this.log("dropped stale-epoch upstream frame");
+        }
+        break;
+      }
+      case "progress": {
+        // §301 (301-ECHO-FENCE-DESIGN.md §1.2): the daemon's release point is THE provable
+        // absorption statement — "everything ≤ cvMin this room will ever be sent has been
+        // sent", and same-socket ordering means it is already applied. Record it and
+        // RE-ADVERTISE to every subscribed connection even with no data flowing (an
+        // out-of-footprint echo's fence must clear without waiting for unrelated churn); the
+        // room's own cvMin in that frame is unchanged, so clients release nothing new.
+        const cvMin = (frame.frame as { cvMin?: unknown } | undefined)?.cvMin;
+        if (typeof cvMin === "number" && cvMin > (this.upstreamCvMin ?? -1)) {
+          this.upstreamCvMin = cvMin;
+          const touched = new Set<ConnState>();
+          for (const meta of this.subs.values()) touched.add(meta.conn);
+          for (const conn of touched) this.sendProgress(conn);
+        }
+        break;
+      }
+      case "queryError": {
+        // The lease died (expiry, dematerialize, daemon restart): re-mint, re-subscribe.
+        this.subscribeInFlight = false;
+        this.incarnationDead(`upstream queryError: ${String(frame.message)}`);
+        void mintLease(this.opts.upstream)
+          .then((token) => {
+            this.leaseToken = token;
+            setTimeout(() => this.sendSubscribe(), RESUBSCRIBE_DELAY_MS).unref?.();
+          })
+          .catch((e) => {
+            this.log(`lease re-mint failed: ${String(e)}`);
+            // The socket is still up; retry the whole path after a beat.
+            setTimeout(() => {
+              if (!this.closed) this.onUpstreamFrame(data);
+            }, RECONNECT_MAX_MS).unref?.();
+          });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  /** A §3.4 violation: kill the incarnation and re-subscribe (never patch up). */
+  private violation(reason: string): void {
+    this.incarnationDead(reason);
+    setTimeout(() => this.sendSubscribe(), RESUBSCRIBE_DELAY_MS).unref?.();
+  }
+
+  private incarnationDead(reason: string): void {
+    this.log(`incarnation dead: ${reason}`);
+    if (this.room) {
+      this.room.free();
+      this.room = null;
+    }
+    this.live = false;
+    this.incarnationBootId = randomUUID();
+    // Downstream subscriptions die with the incarnation (§3.4): close the sockets;
+    // reconnecting clients re-subscribe against the next incarnation.
+    for (const meta of this.subs.values()) {
+      meta.ws.close(1012, "room re-subscribing");
+    }
+    this.subs.clear();
+    this.pendingSubs = [];
+    // The write plane's optimism dies with the incarnation too: whatever was not yet
+    // journaled was never acked, and never will be (§8.1's `applied` class). The
+    // journal itself outlives us — the next incarnation replays it.
+    this.pendingMutes = [];
+    this.unacked.clear();
+    // Recorded outcomes die with the incarnation too — the next incarnation reseeds
+    // them from its own journal replay (finishBoot), which is the source of truth for
+    // what THAT incarnation's base produced.
+    this.outcomes.clear();
+    this.ackQueue = [];
+    if (this.ackTimer !== null) {
+      clearTimeout(this.ackTimer);
+      this.ackTimer = null;
+    }
+    // The flush debounce dies with the incarnation; an in-flight settlement keeps
+    // running (its batch is journaled and epoch-bound — the bootId guard keeps its
+    // outcome from touching the next incarnation's state).
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  /** After the seq-0 snapshot: enable the write plane, settle any unconfirmed flush
+   *  batches, probe the authority's durable lmids, and replay the journal onto the
+   *  fresh base (§3.3 — pending re-invoked; a mid the probe covered replays as dedup,
+   *  its effects already in the snapshot; everything replayed acked, since journal
+   *  presence IS the ack), then start serving. The order is load-bearing: the
+   *  resubmission SETTLES before the probe, so a batch a dead incarnation left
+   *  mid-network can never land between the probe and our first flush. No subscriber
+   *  exists yet (they died with the previous incarnation), so replay fans out to
+   *  nobody — the snapshots the queued subscribes get below already include the
+   *  replayed rows. */
+  private async finishBoot(room: WasmRoom): Promise<void> {
+    const writes = this.opts.downstream.writes;
+    if (writes && this.journal) {
+      let entries: RoomJournalEntry[];
+      try {
+        // H-iv-b: boot-wire scopes arm the §3.3 commit gate (v2); without them the v1
+        // table-granular plane enables byte-identically to before. Either enable
+        // throws loudly on a malformed input and leaves writes disabled — the
+        // violation below keeps that from becoming a half-enabled room.
+        if (writes.scopes !== undefined) {
+          room.enableWritesV2(JSON.stringify(writes.scopes));
+        } else {
+          room.enableWrites(JSON.stringify(writes.ownedTables));
+        }
+        entries = await this.journal.replay();
+      } catch (e) {
+        this.violation(`write-plane boot failed: ${String(e)}`);
+        return;
+      }
+      if (this.room !== room) return; // an incarnation death raced the replay
+      if (writes.authority) {
+        try {
+          await this.settleUnconfirmedFlushes(writes.authority);
+        } catch (e) {
+          if (this.moved || this.closed) return;
+          this.violation(`flush resubmission failed: ${String(e)}`);
+          return;
+        }
+        if (this.room !== room) return;
+        const clients = [...new Set(entries.map((e) => e.clientID))];
+        if (clients.length > 0) {
+          let lmids: Record<string, number>;
+          try {
+            lmids = await withNetRetry(
+              () => writes.authority!.lmids(this.opts.downstream.docId, clients),
+              () => this.closed || this.room !== room,
+              this.log,
+            );
+          } catch (e) {
+            if (this.room !== room || this.closed) return;
+            this.violation(`durable-lmid probe failed: ${String(e)}`);
+            return;
+          }
+          if (this.room !== room) return;
+          const seeds = Object.entries(lmids)
+            .filter(([, lmid]) => lmid > 0)
+            .map(([clientID, lmid]) => ({ clientID, lmid }));
+          if (seeds.length > 0) {
+            try {
+              room.seedDurable(JSON.stringify(seeds));
+              room.commitAll(); // drop the (subscriber-less) ledger fanout
+            } catch (e) {
+              this.violation(`durable seed failed: ${String(e)}`);
+              return;
+            }
+            this.log(`durable seed: ${seeds.map((s) => `${s.clientID}→${s.lmid}`).join(", ")}`);
+          }
+        }
+      }
+      try {
+        for (const entry of entries) {
+          const res = this.runMutation(room, entry);
+          // Seed the recorded-outcome map with what THIS incarnation's replay
+          // produced. That includes the H-iv-a replay gotcha: an entry journaled
+          // APPLIED can legitimately DEOPT (or reject) re-invoked against the moved
+          // base — the §3.3 rebase class. The journal record is never rewritten
+          // (history stays what the acking incarnation observed); the map is this
+          // incarnation's answer sheet for re-sent mids.
+          if (res.outcome === "rejected" || res.outcome === "deopt") {
+            this.recordOutcome(entry.clientID, entry.mid, {
+              kind: res.outcome,
+              ...(res.reason !== undefined ? { reason: res.reason } : {}),
+              ...(res.outcome === "deopt" ? { name: entry.name, args: entry.args } : {}),
+            });
+            if (journalEntryOutcome(entry) === "applied") {
+              this.log(
+                `replayed APPLIED mutation ${entry.clientID}:${entry.mid} (\`${entry.name}\`) ` +
+                  `now ${res.outcome}s against the moved base — mid stays burnt, no effects`,
+              );
+            }
+          }
+        }
+        if (entries.length > 0) {
+          room.ack(
+            JSON.stringify(entries.map(({ clientID, mid }) => ({ clientID, mid }))),
+          );
+          room.commitAll(); // drop the (subscriber-less) fanout of the replay
+        }
+      } catch (e) {
+        this.violation(`journal replay failed: ${String(e)}`);
+        return;
+      }
+      if (entries.length > 0) {
+        this.log(`journal replay: ${entries.length} mutation(s) re-invoked and acked`);
+      }
+    }
+    this.becomeLive();
+    this.scheduleFlush(); // replay may have left dirty entries / unflushed lmids
+  }
+
+  /** Resubmit every unconfirmed journaled flush batch, byte-identically, in seq order
+   *  (§3.3/§5.3 step 4). Outcomes: committed or deduped → confirm; fenced under an
+   *  OLD epoch → routine cleanup (a prior process's batch — its mutations recover by
+   *  replay under OUR epoch); fenced under OUR epoch → another room claimed the doc:
+   *  terminal (`room_moved`); conflict → drop (the replay + next flush re-derive the
+   *  net effect against the authority's current rows); identity mismatch → fatal. */
+  private async settleUnconfirmedFlushes(authority: RoomAuthority): Promise<void> {
+    if (!this.journal) return;
+    const { records } = await this.journal.replayFlushes();
+    for (const record of records) {
+      if (this.closed || this.moved) return;
+      let res: Awaited<ReturnType<RoomAuthority["applyRowChangeTxn"]>>;
+      try {
+        res = await withNetRetry(
+          () => authority.applyRowChangeTxn(record.body),
+          () => this.closed || this.moved,
+          this.log,
+        );
+      } catch (e) {
+        if ((e as { fatal?: boolean })?.fatal !== true) throw e;
+        // The §8.3 identity check tripped on a journaled record — a same-id/
+        // different-body bug. LOUD, dropped, never a silent dedup and never a
+        // violation loop: the batch is dead; the envelope replay re-derives its
+        // effects under a fresh flush id.
+        this.log(`flush ${record.seq} DROPPED: batch identity mismatch: ${String(e)}`);
+        await this.journal.confirmFlush(record.seq);
+        continue;
+      }
+      if (res.kind === "ok") {
+        await this.journal.confirmFlush(record.seq);
+        this.log(
+          `flush ${record.seq} settled at boot: ${res.applied ? "applied" : "already applied"}`,
+        );
+      } else if (res.kind === "conflict") {
+        await this.journal.confirmFlush(record.seq);
+        this.log(`flush ${record.seq} dropped at boot: conflict (replay supersedes)`);
+      } else {
+        await this.journal.confirmFlush(record.seq);
+        if (record.epoch === this.placementEpoch) {
+          this.roomMoved(`flush ${record.seq} fenced under our epoch`);
+          return;
+        }
+        this.log(`flush ${record.seq} (old epoch ${record.epoch}) fenced: dropped`);
+      }
+    }
+  }
+
+  private becomeLive(): void {
+    this.live = true;
+    const waiters = this.liveWaiters;
+    this.liveWaiters = [];
+    for (const w of waiters) w();
+    const queued = this.pendingSubs;
+    this.pendingSubs = [];
+    for (const { ws, conn, msg } of queued) {
+      if (ws.readyState === WebSocket.OPEN) {
+        conn.busy = conn.busy.then(() => this.handleSubscribe(ws, conn, msg));
+      }
+    }
+    const mutes = this.pendingMutes;
+    this.pendingMutes = [];
+    for (const { ws, conn, envelope } of mutes) {
+      if (ws.readyState === WebSocket.OPEN) {
+        conn.busy = conn.busy.then(() => this.handlePushMutation(ws, conn, envelope));
+      }
+    }
+  }
+
+  /** After any commit (an upstream apply, a local mutation, an ack): one commitAll
+   *  drains every query's net delta, fanned out per subscriber envelope (empty → no
+   *  frame, no seq — every stream stays gap-free over emitted frames), then each
+   *  touched connection gets its `progress` release point. */
+  private drainDownstream(): void {
+    if (!this.room) return;
+    const frames = JSON.parse(this.room.commitAll()) as Array<{ sub: string; batch: unknown }>;
+    const touched = new Set<ConnState>();
+    for (const { sub, batch } of frames) {
+      const meta = this.subs.get(sub);
+      if (meta) {
+        this.sendBudgeted(meta.conn, { t: "nbatch", queryId: meta.clientQid, batch });
+        touched.add(meta.conn);
+      }
+    }
+    for (const conn of touched) this.sendProgress(conn);
+  }
+
+  /** The connection-level release point (`{t:"progress", frame:{cvMin}}`): `head_cv`,
+   *  except an author with un-acked mutations holds below its oldest one's apply-cv —
+   *  its own data must never release ahead of the lmid advance that confirms it
+   *  (§1.3.1: the client would re-invoke the mutator on top of its own effect). */
+  private sendProgress(conn: ConnState): void {
+    if (!this.room) return;
+    let cvMin = this.room.headCv();
+    if (conn.clientID) {
+      const held = this.unacked.get(conn.clientID);
+      if (held && held.length > 0) {
+        cvMin = Math.min(cvMin, held[0].applyCv - 1);
+      }
+    }
+    // §301: stamp the upstream-absorption advert (once the current daemon boot has released
+    // anything to us) — the client's direction-B pin fence input. Optional fields: an old
+    // client reads `cvMin` only.
+    const frame: { cvMin: number; upstreamCv?: number; upstreamBoot?: string } = { cvMin };
+    if (this.upstreamCvMin !== undefined) {
+      frame.upstreamCv = this.upstreamCvMin;
+      if (this.upstreamBoot !== undefined) frame.upstreamBoot = this.upstreamBoot;
+    }
+    this.sendBudgeted(conn, { t: "progress", frame });
+  }
+
+  /** §9's per-socket send budget (T8): a socket whose queued bytes would exceed it is
+   *  TERMINATED — the close handler reclaims its subscriptions, so room memory stays
+   *  bounded and the client repairs by re-subscribing (a gap, §8.5). Never buffer
+   *  unboundedly on behalf of one slow reader. */
+  private sendBudgeted(conn: ConnState, frame: unknown): void {
+    const ws = conn.ws;
+    if (ws.readyState !== WebSocket.OPEN) return;
+    const text = JSON.stringify(frame);
+    const budget = this.opts.downstream.sendBudgetBytes ?? DEFAULT_SEND_BUDGET_BYTES;
+    if (ws.bufferedAmount + text.length > budget) {
+      this.log(`send budget exceeded (conn ${conn.id}): closed with a gap`);
+      ws.terminate();
+      return;
+    }
+    ws.send(text);
+  }
+
+  // ------------------------------ the write path ------------------------------
+
+  /** Apply one envelope to the room: dedup → run the mutator against a staged tx →
+   *  commit (or reject/deopt, consuming the mid). Shared verbatim by the live path and
+   *  the boot-time journal replay (§3.3 — recovery is re-invocation; a journaled
+   *  NON-APPLIED entry replays its recorded outcome without running anything). Verdict
+   *  classification (H-iv-b): the §3.3 commit gate's structured verdict and an
+   *  environment shortfall (a capability the room lacks — `tx.query`) are DEOPTS (the
+   *  client re-routes the mutation to the daemon stream); an unknown mutator or an
+   *  authz/validation throw is a FINAL rejection. Throws only when the room is torn
+   *  (a mid gap, a poisoned commit) — the caller decides the blast radius. */
+  private runMutation(
+    room: WasmRoom,
+    entry: RoomJournalEntry,
+  ):
+    | { outcome: "applied"; applyCv: number }
+    | { outcome: "rejected"; reason?: string }
+    | { outcome: "deopt"; reason?: string }
+    | { outcome: "dedup" } {
+    // The envelope rides the wasm tx (Slice I-ii): should this mid end non-applied,
+    // its durable outcome row echoes `name`/`args` on a DEOPT — the same
+    // self-contained-re-invoke rule as the frame (H-iv-b), but readable through the
+    // daemon after downgrade when no room socket exists to deliver one.
+    const begin = JSON.parse(
+      room.beginMutation(
+        entry.clientID,
+        entry.mid,
+        entry.name,
+        entry.args === undefined ? undefined : JSON.stringify(entry.args),
+      ),
+    ) as {
+      begin: "tx" | "dedup";
+    };
+    if (begin.begin === "dedup") return { outcome: "dedup" };
+    // A journaled non-applied entry replays its RECORDED verdict without running: the
+    // live run already consumed the mid with no effects, and re-judging (a deopt that
+    // would now PASS against the moved base) would invent effects for a mutation the
+    // client was told to re-route elsewhere — a double apply. Passing the verdict
+    // through the reject IS the replay re-seed (I-ii): a recorded-but-never-flushed
+    // outcome re-enters the core buffer here, so the next flush carries its row —
+    // while a mid the boot probe covered dedups above and never re-seeds (its row
+    // co-committed with the flush that made it durable). The journal keeps no
+    // `reason`, so a replayed row carries kind + envelope only, like the replayed
+    // frame.
+    const journaled = journalEntryOutcome(entry);
+    if (journaled !== "applied") {
+      room.rejectMutation(journaled, undefined);
+      return { outcome: journaled };
+    }
+    const mutator = this.opts.downstream.writes?.mutators[entry.name];
+    if (!mutator) {
+      const reason = `unknown mutator \`${entry.name}\``;
+      room.rejectMutation("rejected", reason);
+      this.log(`mutation ${entry.clientID}:${entry.mid} rejected: ${reason}`);
+      return { outcome: "rejected", reason };
+    }
+    try {
+      // The ambient auth context (managed-writes §3.2): the journaled subject, so a
+      // replayed invocation sees exactly the identity the live one did (`""` for
+      // entries journaled before the identity plane — unauthenticated).
+      const returned = (mutator as (...a: unknown[]) => unknown)(
+        mutationTx(room, this.tableShapes),
+        entry.args as never,
+        { user: entry.sub ?? "" },
+      );
+      assertSyncMutatorReturn(returned, entry.name);
+    } catch (e) {
+      // The shell owns the H-iv-b classification, so it rides the reject into the
+      // core's outcome record (the flush carries the durable row) exactly as it rides
+      // the frame below.
+      const message = String((e as Error)?.message ?? e);
+      if (isEnvironmentShortfall(e)) {
+        room.rejectMutation("deopt", "environment");
+        this.log(
+          `mutation \`${entry.name}\` (${entry.clientID}:${entry.mid}) deopted: ` +
+            `environment shortfall: ${message}`,
+        );
+        return { outcome: "deopt", reason: "environment" };
+      }
+      room.rejectMutation("rejected", message);
+      this.log(`mutation \`${entry.name}\` (${entry.clientID}:${entry.mid}) rejected: ${message}`);
+      return { outcome: "rejected", reason: message };
+    }
+    const out = JSON.parse(room.commitMutation()) as {
+      headCv?: number;
+      deopt?: { reason: string; table: string; pk: unknown[] };
+    };
+    if (out.deopt !== undefined) {
+      // The gate refused at commit and consumed the tx INTERNALLY (mid burnt,
+      // watermark advanced, no head commit) — do NOT call rejectMutation here.
+      this.log(
+        `mutation \`${entry.name}\` (${entry.clientID}:${entry.mid}) deopted: ` +
+          `${out.deopt.reason} on \`${out.deopt.table}\` pk ${JSON.stringify(out.deopt.pk)}`,
+      );
+      return { outcome: "deopt", reason: out.deopt.reason };
+    }
+    return { outcome: "applied", applyCv: out.headCv as number };
+  }
+
+  /** The live `pushMutation` path (§5.1): apply → fan the data out NOW → journal under
+   *  the group commit → ack (the ledger advance) once the append resolves. */
+  private handlePushMutation(ws: WebSocket, conn: ConnState, envelope: PushEnvelope): void {
+    const fail = (message: string) => send(ws, { t: "error", message });
+    if (!this.opts.downstream.writes || !this.journal) {
+      fail("this room is read-only (no write plane configured)");
+      return;
+    }
+    if (!conn.clientID) {
+      fail("init with a clientID before pushMutation");
+      return;
+    }
+    if (envelope.clientID !== conn.clientID) {
+      // The envelope's clientID is bound to the connection identity — a session may
+      // not write another client's mid stream.
+      fail("envelope clientID does not match the connection identity");
+      return;
+    }
+    if (!this.live || !this.room) {
+      this.pendingMutes.push({ ws, conn, envelope });
+      return;
+    }
+    // Checked at execution time (after the live gate), so a mutation queued behind a
+    // still-pending subscribe is judged AFTER that subscribe bound the subject.
+    if (conn.sub === null) {
+      fail("pushMutation requires an authenticated subject — subscribe with a lease token first");
+      return;
+    }
+    const room = this.room;
+    let result: ReturnType<Shell["runMutation"]>;
+    try {
+      result = this.runMutation(room, { ...envelope, sub: conn.sub });
+    } catch (e) {
+      const message = String((e as Error)?.message ?? e);
+      if (room.isPoisoned()) {
+        this.violation(`mutation commit tore the head: ${message}`);
+      } else {
+        // The mid-gap contract: the exact "mutation gap …" text the client's
+        // recovery keys on rides an error frame.
+        fail(message);
+      }
+      return;
+    }
+    if (result.outcome === "dedup") {
+      // Absorbed; the ledger already covers it (or its in-flight ack will). But a
+      // re-sent NON-APPLIED mid is ANSWERED with its recorded outcome (H-iv-b): the
+      // client may have missed the original frame (reconnect), and silence would
+      // leave its deopted mutation parked forever.
+      const recorded = this.outcomes.get(conn.clientID)?.get(envelope.mid);
+      if (recorded !== undefined) this.sendOutcome(conn, envelope.mid, recorded);
+      return;
+    }
+    if (result.outcome === "applied") {
+      const held = this.unacked.get(conn.clientID) ?? [];
+      held.push({ mid: envelope.mid, applyCv: result.applyCv });
+      this.unacked.set(conn.clientID, held);
+      this.drainDownstream(); // §5.1 step 2: never gated on durability
+    } else {
+      // Non-applied (deopt/rejected): record + answer NOW — synchronously, before the
+      // journal enqueue below, so on this ordered socket the `mutationOutcome` frame
+      // always precedes the lmid ack that burns the mid. Applied mutations send
+      // NOTHING (additive frame: old clients drop unknown `t`).
+      const recorded: RecordedOutcome = {
+        kind: result.outcome,
+        ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        ...(result.outcome === "deopt" ? { name: envelope.name, args: envelope.args } : {}),
+      };
+      this.recordOutcome(conn.clientID, envelope.mid, recorded);
+      this.sendOutcome(conn, envelope.mid, recorded);
+    }
+    this.enqueueJournal({
+      clientID: envelope.clientID,
+      mid: envelope.mid,
+      name: envelope.name,
+      args: envelope.args,
+      sub: conn.sub,
+      outcome: result.outcome,
+      // The legacy flag rides alongside BOTH non-applied kinds: a pre-H-iv-b reader
+      // replays either as a consumed-mid-no-effect — exactly right (journal.ts).
+      ...(result.outcome !== "applied" ? { rejected: true } : {}),
+    });
+    // §5.1 step 5: the write-behind rides its own debounce — applied mutations dirty
+    // rows, rejected/deopted ones still advance an lmid the authority must eventually
+    // hold.
+    this.scheduleFlush();
+  }
+
+  /** Record a non-applied verdict for `(clientID, mid)` — the re-send answer sheet.
+   *  Insertion-ordered per client; past {@link MAX_RECORDED_OUTCOMES_PER_CLIENT} the
+   *  oldest evicts (see the constant's retention rationale). */
+  private recordOutcome(clientID: string, mid: number, outcome: RecordedOutcome): void {
+    let byMid = this.outcomes.get(clientID);
+    if (byMid === undefined) {
+      byMid = new Map();
+      this.outcomes.set(clientID, byMid);
+    }
+    byMid.delete(mid); // re-recording refreshes recency
+    byMid.set(mid, outcome);
+    while (byMid.size > MAX_RECORDED_OUTCOMES_PER_CLIENT) {
+      byMid.delete(byMid.keys().next().value as number);
+    }
+  }
+
+  /** The `mutationOutcome` frame (H-iv-b): `{t, mid, kind, reason?, name?, args?}` on
+   *  the mutating client's socket. DEOPT frames echo `name`/`args` so they are
+   *  self-contained — a client that already retired the entry can re-invoke from the
+   *  frame alone. Sent before the mid's journal append is even enqueued, so it always
+   *  precedes the lmid ack on this ordered socket. */
+  private sendOutcome(conn: ConnState, mid: number, o: RecordedOutcome): void {
+    this.sendBudgeted(conn, {
+      t: "mutationOutcome",
+      mid,
+      kind: o.kind,
+      ...(o.reason !== undefined ? { reason: o.reason } : {}),
+      ...(o.kind === "deopt" ? { name: o.name, args: o.args } : {}),
+    });
+  }
+
+  /** Collect entries for the next group commit (§5.1 step 3: one append per window). */
+  private enqueueJournal(entry: RoomJournalEntry): void {
+    this.ackQueue.push(entry);
+    if (this.ackTimer === null) {
+      const window = this.opts.downstream.writes?.groupCommitMs ?? DEFAULT_GROUP_COMMIT_MS;
+      this.ackTimer = setTimeout(() => this.flushJournal(), window);
+      this.ackTimer.unref?.();
+    }
+  }
+
+  private flushJournal(): void {
+    this.ackTimer = null;
+    const batch = this.ackQueue;
+    this.ackQueue = [];
+    if (batch.length === 0 || !this.journal) return;
+    const journal = this.journal;
+    const bootAtFlush = this.incarnationBootId;
+    // One append in flight at a time; acks apply in append order.
+    this.ackChain = this.ackChain.then(async () => {
+      try {
+        await journal.append(batch);
+      } catch (e) {
+        // An ack that might not survive must never be sent (§8.1): the incarnation
+        // dies loudly instead.
+        if (this.incarnationBootId === bootAtFlush && !this.closed) {
+          this.violation(`journal append failed: ${String(e)}`);
+        }
+        return;
+      }
+      if (this.incarnationBootId !== bootAtFlush || !this.room) {
+        return; // the incarnation died mid-append: its optimism died with it
+      }
+      this.applyAck(this.room, batch);
+    });
+  }
+
+  /** §5.1 step 4 — the ack: advance the ledger rows, ship the lmid frames, and raise
+   *  every author's release point past its confirmed data. */
+  private applyAck(room: WasmRoom, batch: RoomJournalEntry[]): void {
+    let headCv: number | null;
+    try {
+      const entries = batch.map(({ clientID, mid }) => ({ clientID, mid }));
+      headCv = (JSON.parse(room.ack(JSON.stringify(entries))) as { headCv: number | null })
+        .headCv;
+    } catch (e) {
+      this.violation(`ack failed: ${String(e)}`);
+      return;
+    }
+    const authors = new Set<string>();
+    for (const { clientID, mid } of batch) {
+      authors.add(clientID);
+      const held = this.unacked.get(clientID);
+      if (held) {
+        const rest = held.filter((u) => u.mid > mid);
+        if (rest.length > 0) this.unacked.set(clientID, rest);
+        else this.unacked.delete(clientID);
+      }
+    }
+    if (headCv !== null) {
+      this.drainDownstream(); // the lmid frames (+ progress to their receivers)
+    }
+    // Raise the release point for every author connection even if no frame reached
+    // it in this drain (e.g. its lmid slice was already current).
+    for (const meta of this.subs.values()) {
+      if (meta.conn.clientID && authors.has(meta.conn.clientID)) {
+        this.sendProgress(meta.conn);
+        authors.delete(meta.conn.clientID);
+      }
+    }
+  }
+
+  // --------------------------- the write-behind flush ---------------------------
+
+  /** Arm the flush debounce (or fire now past the dirty-size threshold). Cheap and
+   *  idempotent — called after every applied/rejected mutation and every settlement. */
+  private scheduleFlush(): void {
+    const writes = this.opts.downstream.writes;
+    if (!writes?.authority || this.flushBusy || this.flushTimer !== null) return;
+    if (this.closed || this.moved || !this.live || !this.room) return;
+    const dirtyMax = writes.flushDirtyMax ?? DEFAULT_FLUSH_DIRTY_MAX;
+    const delay =
+      this.room.dirtyLen() >= dirtyMax ? 0 : writes.flushDebounceMs ?? DEFAULT_FLUSH_DEBOUNCE_MS;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.fireFlush();
+    }, delay);
+    this.flushTimer.unref?.();
+  }
+
+  /** Fire the write-behind flush now and await its settlement (tests, drain paths). */
+  flushNow(): Promise<void> {
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.fireFlush();
+    return this.flushChain;
+  }
+
+  /** §4.2/§7.4 drain-before-downgrade: fire the write-behind repeatedly until pending AND dirty
+   *  are both empty, awaiting each settlement, then report the last COMMITTED flush seq — the
+   *  value a downgraded client's frozen ghost fences against
+   *  (`_rindle_room_watermark(doc) ≥ finalFlushSeq`). A never-flushed room reports 0. Idempotent:
+   *  re-draining an already-quiescent room re-reports the same seq without flushing. It does NOT
+   *  refuse later pushes (§4.2 R2: a straggler push after drain flushes at seq+1; the client
+   *  ghost's second conjunct — no sent room-domain pending — carries correctness). A room that
+   *  fails to quiesce within {@link DRAIN_MAX_ITERATIONS} throws LOUD (never silently). */
+  async drainForDowngrade(): Promise<number> {
+    const writes = this.opts.downstream.writes;
+    let iterations = 0;
+    while (
+      writes?.authority &&
+      this.live &&
+      !this.moved &&
+      !this.closed &&
+      this.room !== null &&
+      (this.room.dirtyLen() > 0 || this.room.pendingLen() > 0)
+    ) {
+      if (++iterations > DRAIN_MAX_ITERATIONS) {
+        throw new Error(
+          `drain: room ${this.opts.downstream.docId} failed to quiesce after ${DRAIN_MAX_ITERATIONS} flushes ` +
+            `(dirty=${this.room.dirtyLen()}, pending=${this.room.pendingLen()})`,
+        );
+      }
+      await this.flushNow();
+    }
+    return this.lastCommittedFlushSeq;
+  }
+
+  /** §5.3: build the batch (synchronously — the build IS the snapshot), journal its
+   *  exact body bytes, then settle it against the authority. One in flight; the
+   *  settlement outcome drives the state machine (§5.4). */
+  private fireFlush(): void {
+    const writes = this.opts.downstream.writes;
+    const authority = writes?.authority;
+    if (!authority || !this.journal || this.flushBusy) return;
+    if (this.closed || this.moved || !this.live || !this.room) return;
+    const room = this.room;
+    let out: string | undefined;
+    try {
+      out = room.beginFlush();
+    } catch (e) {
+      this.violation(`beginFlush failed: ${String(e)}`);
+      return;
+    }
+    if (!out) return; // nothing dirty, nothing unflushed
+    const { changes, batchHash } = JSON.parse(out) as {
+      changes: unknown[];
+      batchHash: string;
+    };
+    const seq = this.flushSeq++;
+    // Composed ONCE; journaled and sent as this exact string forever (§5.3 step 4).
+    const body = JSON.stringify({
+      source: `room:${this.opts.downstream.docId}:${this.placementEpoch}`,
+      offset: padOffset(seq),
+      doc: this.opts.downstream.docId,
+      epoch: this.placementEpoch,
+      batchHash,
+      cas: true,
+      changes,
+    });
+    const journal = this.journal;
+    const bootAtFlush = this.incarnationBootId;
+    this.flushBusy = true;
+    this.flushChain = (async () => {
+      try {
+        await journal.appendFlush({ seq, epoch: this.placementEpoch, body });
+      } catch (e) {
+        // An unjournaled batch must never reach the wire: a retry could rebuild
+        // different bytes under the same id (§8.3). Loud incarnation death.
+        this.flushBusy = false;
+        if (this.incarnationBootId === bootAtFlush && !this.closed) {
+          this.violation(`flush journal append failed: ${String(e)}`);
+        }
+        return;
+      }
+      let res: Awaited<ReturnType<RoomAuthority["applyRowChangeTxn"]>>;
+      try {
+        res = await withNetRetry(
+          () => authority.applyRowChangeTxn(body),
+          () => this.closed || this.moved,
+          this.log,
+        );
+      } catch (e) {
+        this.flushBusy = false;
+        if (this.closed || this.moved) return;
+        // Fatal-class apply error (identity mismatch): our bug, never retried.
+        if (this.incarnationBootId === bootAtFlush) {
+          this.violation(`flush apply failed fatally: ${String(e)}`);
+        }
+        return;
+      }
+      this.flushBusy = false;
+      const sameIncarnation = this.incarnationBootId === bootAtFlush && this.room !== null;
+      if (res.kind === "ok") {
+        this.flushesConfirmed += 1;
+        this.lastCommittedFlushSeq = Math.max(this.lastCommittedFlushSeq, seq); // §4.2 fence input
+        await journal.confirmFlush(seq);
+        if (!sameIncarnation) {
+          // Settled; the new incarnation replayed its own state — let it flush.
+          this.scheduleFlush();
+          return;
+        }
+        try {
+          this.room!.flushOk();
+        } catch (e) {
+          this.violation(`flushOk failed: ${String(e)}`);
+          return;
+        }
+        this.scheduleFlush(); // in-flight re-dirties / new lmids
+      } else if (res.kind === "conflict") {
+        await journal.confirmFlush(seq); // nothing applied; the retry re-derives
+        if (!sameIncarnation) {
+          this.scheduleFlush();
+          return;
+        }
+        try {
+          const out = JSON.parse(this.room!.flushConflict(JSON.stringify(res.conflicts))) as {
+            headCv: number | null;
+          };
+          if (out.headCv !== null) {
+            this.drainDownstream(); // the corrective frames (§5.4: ordinary edits)
+          }
+        } catch (e) {
+          this.violation(`flushConflict failed: ${String(e)}`);
+          return;
+        }
+        this.log(`flush ${seq} CAS-conflicted: converged to the authority, retrying the rest`);
+        this.scheduleFlush();
+      } else {
+        // Fenced under OUR epoch: this room is superseded (§2.5) — terminal.
+        await journal.confirmFlush(seq);
+        this.roomMoved(`flush ${seq} fenced (authority epoch ${res.currentEpoch ?? "?"})`);
+      }
+    })();
+  }
+
+  /** §2.5 stale-room behavior: the authority fenced us — another placement owns the
+   *  doc. Final state discarded, downstream closed with `room_moved`, nothing
+   *  reconnects. Clients re-open through the API server onto the current epoch. */
+  private roomMoved(reason: string): void {
+    if (this.moved) return;
+    this.moved = true;
+    this.log(`room moved: ${reason}`);
+    for (const meta of this.subs.values()) {
+      meta.ws.close(4009, "room_moved");
+    }
+    void this.close();
+  }
+
+  // ----------------------------- downstream leg -----------------------------
+
+  private serveDownstream(ws: WebSocket): void {
+    const conn: ConnState = {
+      id: this.nextConnId++,
+      ws,
+      queries: new Map(),
+      busy: Promise.resolve(),
+      clientID: null,
+      sub: null,
+    };
+    this.conns.add(conn);
+    ws.on("message", (data) => {
+      let msg: Record<string, unknown>;
+      try {
+        msg = JSON.parse(String(data)) as Record<string, unknown>;
+      } catch {
+        return;
+      }
+      // Serialize per connection: subscribe verification is async, and a client's
+      // subscribe → unsubscribe order must hold. A per-message throw is isolated to
+      // THIS connection (the reference server's #12).
+      conn.busy = conn.busy.then(async () => {
+        try {
+          await this.handleDownstreamMsg(ws, conn, msg);
+        } catch (err) {
+          send(ws, {
+            t: "error",
+            queryId: msg.queryId,
+            message: String((err as Error)?.message ?? err),
+          });
+        }
+      });
+    });
+    ws.on("close", () => {
+      const now = Date.now();
+      for (const q of conn.queries.values()) {
+        if (this.subs.get(q.subKey)?.ws === ws) {
+          this.subs.delete(q.subKey);
+          this.room?.unsubscribe(q.subKey, now);
+        }
+      }
+      conn.queries.clear();
+      this.conns.delete(conn);
+    });
+  }
+
+  private async handleDownstreamMsg(
+    ws: WebSocket,
+    conn: ConnState,
+    msg: Record<string, unknown>,
+  ): Promise<void> {
+    switch (msg.t) {
+      case "init": {
+        // The connection identity: what the lmid subscribe and pushMutation key on.
+        // No reply frame — exactly rindled's wire.
+        if (typeof msg.clientID === "string" && msg.clientID.length > 0) {
+          conn.clientID = msg.clientID;
+        }
+        break;
+      }
+      case "subscribe": {
+        if (typeof msg.queryId !== "number") return;
+        if (!this.live || !this.room) {
+          // Not live yet: hold the subscribe until the seq-0 snapshot lands, so a
+          // booting room doesn't refuse its first clients.
+          this.pendingSubs.push({ ws, conn, msg: msg as unknown as SubscribeMsg });
+          return;
+        }
+        await this.handleSubscribe(ws, conn, msg as unknown as SubscribeMsg);
+        break;
+      }
+      case "unsubscribe": {
+        if (typeof msg.queryId !== "number") return;
+        const prev = conn.queries.get(msg.queryId);
+        if (prev) {
+          conn.queries.delete(msg.queryId);
+          this.subs.delete(prev.subKey);
+          this.room?.unsubscribe(prev.subKey, Date.now());
+        }
+        break;
+      }
+      case "pushMutation": {
+        const e = msg.envelope as Partial<PushEnvelope> | undefined;
+        if (
+          e === null ||
+          typeof e !== "object" ||
+          typeof e.clientID !== "string" ||
+          typeof e.mid !== "number" ||
+          !Number.isFinite(e.mid) ||
+          typeof e.name !== "string"
+        ) {
+          send(ws, { t: "error", message: "malformed pushMutation envelope" });
+          break;
+        }
+        this.handlePushMutation(ws, conn, {
+          clientID: e.clientID,
+          mid: e.mid,
+          name: e.name,
+          args: e.args,
+        });
+        break;
+      }
+      case "mutate":
+        // Raw CRUD never crosses this wire: room writes are named mutators (§4.2),
+        // validated against the owned set at the transaction boundary.
+        send(ws, {
+          t: "error",
+          queryId: msg.queryId,
+          message: "this room accepts named mutators only (pushMutation)",
+        });
+        break;
+      default:
+        break;
+    }
+  }
+
+  private async handleSubscribe(
+    ws: WebSocket,
+    conn: ConnState,
+    msg: SubscribeMsg,
+  ): Promise<void> {
+    if (!this.room) return; // raced an incarnation death; the socket is being closed
+    const queryError = (message: string) =>
+      send(ws, { t: "queryError", queryId: msg.queryId, message });
+
+    // The reserved lmid system query arrives BY NAME even in lease mode — the write
+    // plane's confirmation stream. The room composes the AST itself from the
+    // connection's `init` identity (client args are ignored, exactly as on rindled).
+    if (typeof msg.name === "string") {
+      if (msg.name !== LMID_QUERY_NAME) {
+        queryError("subscribe requires a lease token");
+        return;
+      }
+      if (!this.opts.downstream.writes) {
+        queryError("this room is read-only (no write plane configured)");
+        return;
+      }
+      if (!conn.clientID) {
+        queryError("subscribe lmid query before init");
+        return;
+      }
+      const prev = conn.queries.get(msg.queryId);
+      const epoch = prev ? prev.epoch + 1 : 1;
+      const subKey = `${conn.id}:${msg.queryId}`;
+      if (prev) this.subs.delete(prev.subKey);
+      let res: { hello: unknown; snapshot: unknown };
+      try {
+        res = JSON.parse(
+          this.room.lmidSubscribe(subKey, epoch, conn.clientID, Date.now()),
+        ) as typeof res;
+      } catch (e) {
+        queryError(`materialize failed: ${String((e as Error)?.message ?? e)}`);
+        return;
+      }
+      conn.queries.set(msg.queryId, { subKey, epoch });
+      this.subs.set(subKey, {
+        ws,
+        conn,
+        clientQid: msg.queryId,
+        // Not lease-gated: it lives exactly as long as its connection — never
+        // swept by exp, never a revocation key (revoking a user closes the socket).
+        user: "",
+        exp: Number.POSITIVE_INFINITY,
+      });
+      send(ws, {
+        t: "nhello",
+        queryId: msg.queryId,
+        hello: res.hello,
+        bootId: this.incarnationBootId,
+      });
+      send(ws, { t: "nbatch", queryId: msg.queryId, batch: res.snapshot });
+      this.sendProgress(conn);
+      return;
+    }
+    if (typeof msg.leaseToken !== "string") {
+      queryError("subscribe requires a lease token");
+      return;
+    }
+
+    // The §10.1 gate: signature, doc, expiry — then the §4.1 revocation check.
+    const now = Date.now();
+    let payload;
+    try {
+      payload = await verifyRoomToken(msg.leaseToken, {
+        doc: this.opts.downstream.docId,
+        keys: this.opts.downstream.tokenKeys,
+        now,
+      });
+    } catch (e) {
+      queryError(e instanceof RoomTokenError ? e.message : "lease token refused");
+      return;
+    }
+    const revokedAt = this.revoked.get(payload.sub);
+    if (revokedAt !== undefined && payload.iat <= revokedAt) {
+      queryError("lease token refused: revoked");
+      return;
+    }
+
+    // Scope-skew tripwire: a lease proving against scopes this room's gate did NOT arm
+    // with means a profile was edited after this room booted (the gate arms once). The
+    // subscribe is NOT refused — the gate is still sound, it will just deopt routed
+    // writes until the room re-boots. Log once per distinct skew so the otherwise-silent
+    // deopt loop is diagnosable. Both hashes present required (a pre-stamp token or v1
+    // gate skips).
+    if (
+      this.armedScopesHash !== undefined &&
+      payload.scopesHash !== undefined &&
+      payload.scopesHash !== this.armedScopesHash
+    ) {
+      const key = `${payload.scopesHash}${this.armedScopesHash}`;
+      if (!this.loggedScopeSkew.has(key)) {
+        this.loggedScopeSkew.add(key);
+        this.log(
+          `scope skew: this room's gate armed with scopes ${this.armedScopesHash} but a lease ` +
+            `proves against ${payload.scopesHash} — a room profile was edited under this live ` +
+            `room. Routed writes will deopt (safe, but degraded) until the room re-boots.`,
+        );
+      }
+    }
+
+    // Subject binding (managed-writes §3.1): the FIRST verified lease binds the
+    // connection's authenticated subject; a later lease whose `sub` differs is refused
+    // — one principal per connection, so "the connection's user" is well-defined and
+    // privilege-mixing is closed.
+    if (conn.sub === null) {
+      conn.sub = payload.sub;
+    } else if (conn.sub !== payload.sub) {
+      queryError("lease token refused: connection is bound to another subject");
+      return;
+    }
+
+    // A re-subscribe (gap recovery) replaces the prior envelope and bumps the
+    // DOWNSTREAM epoch — the same rule rindled applies per (conn, queryId).
+    const prev = conn.queries.get(msg.queryId);
+    const epoch = prev ? prev.epoch + 1 : 1;
+    const subKey = `${conn.id}:${msg.queryId}`;
+    if (prev) this.subs.delete(prev.subKey);
+
+    let res: { queryKey: string; reused: boolean; hello: unknown; snapshot: unknown };
+    try {
+      res = JSON.parse(
+        this.room.subscribe(subKey, epoch, JSON.stringify(payload.ast), now),
+      ) as typeof res;
+    } catch (e) {
+      queryError(`materialize failed: ${String((e as Error)?.message ?? e)}`);
+      return;
+    }
+    conn.queries.set(msg.queryId, { subKey, epoch });
+    this.subs.set(subKey, {
+      ws,
+      conn,
+      clientQid: msg.queryId,
+      user: payload.sub,
+      exp: payload.exp,
+    });
+    send(ws, {
+      t: "nhello",
+      queryId: msg.queryId,
+      hello: res.hello,
+      bootId: this.incarnationBootId,
+    });
+    send(ws, { t: "nbatch", queryId: msg.queryId, batch: res.snapshot });
+    // The release point for the snapshot: an optimistic client buffers every nbatch
+    // until a progress frame's cvMin covers its cv.
+    this.sendProgress(conn);
+  }
+
+  /** The periodic enforcement tick: drop subscriptions whose lease passed `exp`
+   *  unrenewed (§4.1's TTL backstop), reclaim idle pipelines, prune old revocations. */
+  private sweep(): void {
+    const now = Date.now();
+    for (const [subKey, meta] of [...this.subs]) {
+      if (meta.exp <= now) {
+        send(meta.ws, {
+          t: "queryError",
+          queryId: meta.clientQid,
+          message: "expired lease — renew through the API server",
+        });
+        this.dropSub(subKey, meta, now);
+      }
+    }
+    if (this.room && this.live) {
+      this.room.sweep(now);
+    }
+    const window = this.opts.downstream.revocationWindowMs ?? DEFAULT_REVOCATION_WINDOW_MS;
+    for (const [user, at] of [...this.revoked]) {
+      if (now - at > window) this.revoked.delete(user);
+    }
+  }
+
+  private dropSub(subKey: string, meta: SubMeta, now: number): void {
+    this.subs.delete(subKey);
+    meta.conn.queries.delete(meta.clientQid);
+    this.room?.unsubscribe(subKey, now);
+  }
+
+  /** §4.1 layer 2: synchronous revocation. Terminates every subscription and socket of
+   *  `user` and refuses their pre-revocation tokens from here on. */
+  private revokeUser(user: string): number {
+    const now = Date.now();
+    this.revoked.set(user, now);
+    const sockets = new Set<WebSocket>();
+    let dropped = 0;
+    for (const [subKey, meta] of [...this.subs]) {
+      if (meta.user !== user) continue;
+      send(meta.ws, {
+        t: "queryError",
+        queryId: meta.clientQid,
+        message: "lease revoked",
+      });
+      this.dropSub(subKey, meta, now);
+      sockets.add(meta.ws);
+      dropped++;
+    }
+    // A conn BOUND to the subject is write-capable even with no live subscription
+    // (managed-writes §3.1/§3.4) — its socket goes too.
+    for (const conn of this.conns) {
+      if (conn.sub === user) sockets.add(conn.ws);
+    }
+    for (const ws of sockets) {
+      ws.close(1008, "revoked");
+    }
+    this.log(`revoked ${user}: ${dropped} subscription(s)`);
+    return dropped;
+  }
+
+  // ----------------------------- control plane ------------------------------
+
+  private startControl(control: { authToken: string; port?: number }): Promise<void> {
+    const server = createServer((req, res) => {
+      const reply = (status: number, body: unknown) => {
+        res.writeHead(status, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+      };
+      if (req.headers.authorization !== `Bearer ${control.authToken}`) {
+        return reply(401, { error: "unauthorized" });
+      }
+      if (req.method === "GET" && req.url === "/stats") {
+        return reply(200, {
+          live: this.live,
+          connections: this.wss.clients.size,
+          subscriptions: this.subs.size,
+          materializations: this.room?.materializationCount() ?? 0,
+          pendingMutations: this.room?.pendingLen() ?? 0,
+          dirtyKeys: this.room?.dirtyLen() ?? 0,
+          placementEpoch: this.placementEpoch,
+          flushesConfirmed: this.flushesConfirmed,
+          flushInFlight: this.flushBusy,
+        });
+      }
+      if (req.method === "POST" && req.url === "/revoke") {
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+          try {
+            const { userId } = JSON.parse(body) as { userId?: string };
+            if (typeof userId !== "string" || userId.length === 0) {
+              return reply(400, { error: "userId required" });
+            }
+            reply(200, { revoked: this.revokeUser(userId) });
+          } catch {
+            reply(400, { error: "invalid JSON" });
+          }
+        });
+        return;
+      }
+      if (req.method === "POST" && req.url === "/drain") {
+        // §4.2 drain-before-downgrade: the api-server's `drainRoom` hook lands here. No body.
+        this.drainForDowngrade().then(
+          (finalFlushSeq) => reply(200, { finalFlushSeq, drained: true }),
+          (e) => reply(500, { error: String((e as Error)?.message ?? e) }),
+        );
+        return;
+      }
+      reply(404, { error: "unknown endpoint" });
+    });
+    this.control = server;
+    return new Promise((resolve) => {
+      server.listen(control.port ?? 0, "127.0.0.1", () => resolve());
+    });
+  }
+}
+
+interface SubscribeMsg {
+  queryId: number;
+  name?: unknown;
+  leaseToken?: unknown;
+}
+
+/** The wire mutation envelope (`{t:"pushMutation", envelope}`) — `clientID` capital
+ *  ID, exactly as `@rindle/remote` sends it. */
+interface PushEnvelope {
+  clientID: string;
+  mid: number;
+  name: string;
+  args: unknown;
+}
+
+/** A flush seq as its wire offset: zero-padded so `rindled`'s lexicographic keyset
+ *  compare (`run_already_applied`) orders it like the number it is. */
+function padOffset(seq: number): string {
+  return String(seq).padStart(20, "0");
+}
+
+/** Retry `op` on network-class failures (backoff, same inputs — for the flush that
+ *  means the same journaled bytes) until it settles, `stop()` says quit, or the error
+ *  is fatal (`{fatal: true}` — retrying cannot help). */
+async function withNetRetry<T>(
+  op: () => Promise<T>,
+  stop: () => boolean,
+  log: (line: string) => void,
+): Promise<T> {
+  let delay = FLUSH_RETRY_MIN_MS;
+  for (;;) {
+    try {
+      return await op();
+    } catch (e) {
+      if ((e as { fatal?: boolean })?.fatal === true || stop()) throw e;
+      log(`authority call failed (retrying in ${delay}ms): ${String(e)}`);
+      await new Promise((r) => {
+        const t = setTimeout(r, delay);
+        (t as { unref?: () => void }).unref?.();
+      });
+      if (stop()) throw e;
+      delay = Math.min(delay * 2, FLUSH_RETRY_MAX_MS);
+    }
+  }
+}
+
+/** Positional table shapes from the upstream hello — the keyed MutationTx layer's
+ *  schema. (The hello was already validated by `WasmRoom.open` before this runs.) */
+function shapesOf(hello: unknown): Map<string, TableShape> {
+  const shapes = new Map<string, TableShape>();
+  const tables = (
+    hello as { tables?: Array<{ name: string; columns: string[]; primaryKey: number[] }> }
+  )?.tables;
+  if (Array.isArray(tables)) {
+    for (const t of tables) {
+      shapes.set(t.name, { columns: t.columns, primaryKey: t.primaryKey });
+    }
+  }
+  return shapes;
+}
+
+/** Boot a room shell: init the wasm, mint the upstream lease, connect the upstream leg,
+ *  and serve the downstream ws (+ the private control plane, if configured). Returns
+ *  once the ports are bound and the upstream connection is underway — await
+ *  `shell.awaitLive()` for the seed. */
+export async function createRoomShell(opts: RoomShellOptions): Promise<RoomShell> {
+  const shell = new Shell(opts);
+  try {
+    await shell.start();
+  } catch (e) {
+    await shell.close();
+    throw e;
+  }
+  return shell;
+}