@rindle/room 0.5.0

package/dist/shell.js

@@ -0,0 +1,1589 @@
+// 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 } from "node:http";
+import { randomUUID } from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+import { initRoomWasm, WasmRoom } from "./wasm.js";
+import { verifyRoomToken, RoomTokenError, scopeSpecsHash } from "./token.js";
+import { assertSyncMutatorReturn, isEnvironmentShortfall, mutationTx, } from "./mutation-tx.js";
+import { journalEntryOutcome, memoryJournal, } from "./journal.js";
+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) {
+    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());
+    if (typeof out.leaseToken !== "string") {
+        throw new Error("upstream /materialize returned no leaseToken");
+    }
+    return out.leaseToken;
+}
+function send(ws, frame) {
+    if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(frame));
+    }
+}
+/** 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 {
+    opts;
+    log;
+    wss;
+    control = null;
+    room = null;
+    live = false;
+    incarnationBootId = randomUUID();
+    liveWaiters = [];
+    upstream = null;
+    leaseToken = "";
+    subscribeInFlight = false;
+    reconnectDelayMs = RESUBSCRIBE_DELAY_MS;
+    closed = false;
+    nextConnId = 1;
+    sweepTimer = null;
+    /** subKey (what the wasm room routes by) → where its frames go + lease state. */
+    subs = new Map();
+    /** Every open downstream connection — revocation must reach a BOUND conn even when
+     *  it holds no live subscription (it is still write-capable). */
+    conns = new Set();
+    /** userId → when they were revoked (refuses tokens with `iat` ≤ this; pruned after
+     *  the revocation window). */
+    revoked = new Map();
+    /** Downstream subscribes queued while no incarnation is live. */
+    pendingSubs = [];
+    // ------------------------------ 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. */
+    armedScopesHash;
+    /** Scope-skew hash pairs already logged (`lease→armed`), so the diagnostic fires ONCE
+     *  per distinct skew, not once per subscribe. */
+    loggedScopeSkew = new Set();
+    /** 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). */
+    journal = null;
+    /** Positional table shapes from the upstream hello (keyed layer of MutationTx). */
+    tableShapes = new Map();
+    /** Mutations queued while no incarnation is live (drained after pendingSubs). */
+    pendingMutes = [];
+    /** clientID → its applied-but-unacked mutations, oldest first (release holdback). */
+    unacked = new Map();
+    /** 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. */
+    outcomes = new Map();
+    /** The group-commit window: entries awaiting the next journal append. */
+    ackQueue = [];
+    ackTimer = null;
+    /** Serializes journal appends (one in flight; acks apply in append order). */
+    ackChain = Promise.resolve();
+    // ------------------------------ flush state (§5.3) ------------------------------
+    /** The placement epoch (§2.5), claimed once per shell process at start. 0 = no
+     *  authority configured. */
+    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. */
+    flushSeq = 1;
+    flushTimer = null;
+    /** One flush settlement in flight at a time (the wasm room guards too). */
+    flushBusy = false;
+    /** The settlement chain `flushNow()` awaits. */
+    flushChain = Promise.resolve();
+    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. */
+    lastCommittedFlushSeq = 0;
+    /** Fenced at the authority (§2.5): this room is superseded — terminal. */
+    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. */
+    upstreamBoot;
+    /** 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. */
+    upstreamCvMin;
+    constructor(opts) {
+        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() {
+        await initRoomWasm();
+        await new Promise((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() {
+        const addr = this.wss.address();
+        return typeof addr === "object" && addr !== null ? addr.port : 0;
+    }
+    get controlPort() {
+        const addr = this.control?.address();
+        return typeof addr === "object" && addr !== null ? addr.port : 0;
+    }
+    awaitLive() {
+        if (this.live)
+            return Promise.resolve();
+        return new Promise((resolve) => this.liveWaiters.push(resolve));
+    }
+    cv() {
+        return this.room?.cv();
+    }
+    upstreamEpoch() {
+        return this.room?.epoch();
+    }
+    bootId() {
+        return this.incarnationBootId;
+    }
+    async close() {
+        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((resolve) => this.wss.close(() => resolve()));
+        if (this.control) {
+            await new Promise((resolve) => this.control?.close(() => resolve()));
+        }
+        if (this.room) {
+            this.room.free();
+            this.room = null;
+        }
+    }
+    // ------------------------------ upstream leg ------------------------------
+    connectUpstream() {
+        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. */
+    sendSubscribe() {
+        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 });
+    }
+    onUpstreamFrame(data) {
+        let frame;
+        try {
+            frame = JSON.parse(String(data));
+        }
+        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;
+                try {
+                    status = JSON.parse(this.room.apply(JSON.stringify(frame.batch)));
+                }
+                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?.cvMin;
+                if (typeof cvMin === "number" && cvMin > (this.upstreamCvMin ?? -1)) {
+                    this.upstreamCvMin = cvMin;
+                    const touched = new Set();
+                    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). */
+    violation(reason) {
+        this.incarnationDead(reason);
+        setTimeout(() => this.sendSubscribe(), RESUBSCRIBE_DELAY_MS).unref?.();
+    }
+    incarnationDead(reason) {
+        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. */
+    async finishBoot(room) {
+        const writes = this.opts.downstream.writes;
+        if (writes && this.journal) {
+            let entries;
+            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;
+                    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. */
+    async settleUnconfirmedFlushes(authority) {
+        if (!this.journal)
+            return;
+        const { records } = await this.journal.replayFlushes();
+        for (const record of records) {
+            if (this.closed || this.moved)
+                return;
+            let res;
+            try {
+                res = await withNetRetry(() => authority.applyRowChangeTxn(record.body), () => this.closed || this.moved, this.log);
+            }
+            catch (e) {
+                if (e?.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`);
+            }
+        }
+    }
+    becomeLive() {
+        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. */
+    drainDownstream() {
+        if (!this.room)
+            return;
+        const frames = JSON.parse(this.room.commitAll());
+        const touched = new Set();
+        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). */
+    sendProgress(conn) {
+        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 };
+        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. */
+    sendBudgeted(conn, frame) {
+        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. */
+    runMutation(room, entry) {
+        // 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)));
+        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(mutationTx(room, this.tableShapes), entry.args, { 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?.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());
+        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 };
+    }
+    /** 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. */
+    handlePushMutation(ws, conn, envelope) {
+        const fail = (message) => 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;
+        try {
+            result = this.runMutation(room, { ...envelope, sub: conn.sub });
+        }
+        catch (e) {
+            const message = String(e?.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 = {
+                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). */
+    recordOutcome(clientID, mid, outcome) {
+        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);
+        }
+    }
+    /** 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. */
+    sendOutcome(conn, mid, o) {
+        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). */
+    enqueueJournal(entry) {
+        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?.();
+        }
+    }
+    flushJournal() {
+        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. */
+    applyAck(room, batch) {
+        let headCv;
+        try {
+            const entries = batch.map(({ clientID, mid }) => ({ clientID, mid }));
+            headCv = JSON.parse(room.ack(JSON.stringify(entries)))
+                .headCv;
+        }
+        catch (e) {
+            this.violation(`ack failed: ${String(e)}`);
+            return;
+        }
+        const authors = new Set();
+        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. */
+    scheduleFlush() {
+        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() {
+        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() {
+        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). */
+    fireFlush() {
+        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;
+        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);
+        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;
+            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)));
+                    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. */
+    roomMoved(reason) {
+        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 -----------------------------
+    serveDownstream(ws) {
+        const conn = {
+            id: this.nextConnId++,
+            ws,
+            queries: new Map(),
+            busy: Promise.resolve(),
+            clientID: null,
+            sub: null,
+        };
+        this.conns.add(conn);
+        ws.on("message", (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(data));
+            }
+            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?.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);
+        });
+    }
+    async handleDownstreamMsg(ws, conn, msg) {
+        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 });
+                    return;
+                }
+                await this.handleSubscribe(ws, conn, msg);
+                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;
+                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;
+        }
+    }
+    async handleSubscribe(ws, conn, msg) {
+        if (!this.room)
+            return; // raced an incarnation death; the socket is being closed
+        const queryError = (message) => 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;
+            try {
+                res = JSON.parse(this.room.lmidSubscribe(subKey, epoch, conn.clientID, Date.now()));
+            }
+            catch (e) {
+                queryError(`materialize failed: ${String(e?.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;
+        try {
+            res = JSON.parse(this.room.subscribe(subKey, epoch, JSON.stringify(payload.ast), now));
+        }
+        catch (e) {
+            queryError(`materialize failed: ${String(e?.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. */
+    sweep() {
+        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);
+        }
+    }
+    dropSub(subKey, meta, now) {
+        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. */
+    revokeUser(user) {
+        const now = Date.now();
+        this.revoked.set(user, now);
+        const sockets = new Set();
+        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 ------------------------------
+    startControl(control) {
+        const server = createServer((req, res) => {
+            const reply = (status, body) => {
+                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);
+                        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?.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());
+        });
+    }
+}
+/** 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) {
+    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(op, stop, log) {
+    let delay = FLUSH_RETRY_MIN_MS;
+    for (;;) {
+        try {
+            return await op();
+        }
+        catch (e) {
+            if (e?.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.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) {
+    const shapes = new Map();
+    const tables = hello?.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) {
+    const shell = new Shell(opts);
+    try {
+        await shell.start();
+    }
+    catch (e) {
+        await shell.close();
+        throw e;
+    }
+    return shell;
+}
+//# sourceMappingURL=shell.js.map