@rindle/api-server 0.4.4 → 0.6.3

package/dist/index.js

@@ -1,10 +1,24 @@
-import { driveMutationAsync, insertCell, insertPlan, isoTx, toCell } from "@rindle/client";
+import { driveMutationAsync, insertCell, insertPlan, isGeneratorMutator, isoTx, toCell } from "@rindle/client";
 import { DaemonHttpError } from "@rindle/daemon-client";
 import { compile as compileQueryAst } from "@rindle/query-compiler";
+import { assertLabeledProfilesExist, assertUnwindowedFootprint, attachRealtimeLabel, compileRoomProfiles, compileRoomScopeSpecs, compileRoomTableSpecs, mintRoomDoc, queryRealtimeLabel, queryResultToAst, splitRoomDoc, } from "./rooms.js";
+let roomTokenModule;
+async function loadRoomTokenModule() {
+    if (roomTokenModule === undefined) {
+        const m = await import("@rindle/room/token");
+        roomTokenModule = { mintRoomToken: m.mintRoomToken, scopeSpecsHash: m.scopeSpecsHash };
+    }
+    return roomTokenModule;
+}
 // Re-export the shared (generator) mutator seam so an app builds its server mutators from ONE import:
 // co-locate each body with its arg schema (`shared`), bulk-drive the registry ({@link sharedApiMutators}),
 // keeping only server-only authority as explicit overrides (see MUTATORS-ISOMORPHIC).
 export { isoTx, shared } from "@rindle/client";
+// The room-profile declaration layer (RINDLE-REALTIME-QUERY-ENABLEMENT §2, slice G-iv-a). The
+// compiled-profile shapes stay internal to `./rooms.ts` — G-iv-b consumes them in-package.
+// `RoomTableSpec` (G-iv-b) is public: it rides the lease wire (`QueryLeaseResponse.realtime`).
+// `RoomScopeSpec` (H-iv-b) is public: it rides the boot wire (`RoomBootResponse.scopes`).
+export { queryRealtimeLabel, queryResultToAst } from "./rooms.js";
 export const DEFAULT_RINDLE_API_ROUTES = {
     query: "/api/rindle/query",
     read: "/api/rindle/read",
@@ -17,6 +31,58 @@ export const DEFAULT_RINDLE_API_ROUTES = {
     // The DO shell's cold-boot callback (§10.1) — active only when `realtime` is configured.
     roomBoot: "/api/rindle/room-boot",
 };
+// --------------------------------------------------------------------------- scoped (outside-tx) mutators
+//
+// The tx-form {@link ApiMutator} above runs ENTIRELY inside the transaction. A SCOPED mutator
+// (WORK-OUTSIDE-TX) instead controls the boundary itself: it receives a {@link MutationScope}, runs
+// server-only code BEFORE opening the one atomic transaction (`scope.transact`), and MAY run code
+// AFTER it commits. The outside-tx code is server-only by nature (the client's optimistic prediction
+// can't call Stripe), so it lives HERE, never in the isomorphic body — the shared generator stays
+// pure and identical on both tiers; server-computed values flow into it through `ctx`, exactly like
+// `ctx.user` (undefined/predicted on the client, authoritative here).
+/** Thrown by {@link MutationScope.transact} when the transacted body BUSINESS-rejects: the data
+ *  rolled back and `lmid` advanced alone (§2.4). Catch it to COMPENSATE an outside-tx side effect
+ *  (refund the charge), then rethrow or return — the mutation's protocol outcome is already sealed
+ *  as rejected, so a post-reject throw can't change it. A DB/infra failure is NOT this — it
+ *  propagates as the raw driver error (the client retries; `lmid` did not advance). */
+export class MutationRejected extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "MutationRejected";
+        this.reason = reason;
+    }
+}
+/** Mark a mutator as SCOPED so the api-server gives it a {@link MutationScope} (author-controlled tx
+ *  boundary via `scope.transact`) rather than running its whole body inside the transaction. Register
+ *  it alongside the tx-form mutators — it wins by key like any override:
+ *
+ *  ```ts
+ *  mutators: defineApiMutators({
+ *    ...sharedApiMutators(sharedMutators, sharedCtx),        // tx-form (common case)
+ *    createOrder: scoped(async (scope, raw, ctx) => {        // needs outside-tx work
+ *      const args = createOrder.args.parse(raw);
+ *      const chargeId = await stripe.charge(args.amount, { idempotencyKey: ctx.envelope.mid }); // outside tx
+ *      try {
+ *        await scope.transact(createOrder, args, { ...sharedCtx(ctx), chargeId });              // inside tx
+ *      } catch (e) {
+ *        await stripe.refund(chargeId);                       // compensate — the write rejected
+ *        throw e;
+ *      }
+ *      await sendReceipt(ctx.user);                           // after commit
+ *    }),
+ *  }),
+ *  ```
+ */
+export function scoped(fn) {
+    // The brand carries the scoped runtime shape; typing the RETURN as the (branded) tx-form keeps it
+    // assignable into `mutators` WITHOUT unioning that record — the harness routes on the brand and
+    // never calls it as a tx-form mutator, so the cast is sound.
+    return Object.assign(fn, { __rindleScoped: true });
+}
+function isScoped(m) {
+    return m.__rindleScoped === true;
+}
 // The DEFAULT flush credential: `rfc1.<b64url payload>.<b64url hmac-sha256>`, payload
 // `{v:1, doc, epoch, iat}`. Deliberately EPOCH-bound, not time-bound: the credential's lifecycle
 // IS the placement fence (§8.3 — a superseded epoch's flushes 409 at the store no matter what
@@ -182,10 +248,18 @@ export class SplitDaemonClient {
             return Promise.reject(new Error("the write master lacks roomLmids"));
         return lmids(input);
     }
+    // Pure computation hosted by rindled: keep it on the read/follower leg. The write master owns
+    // room durability, not query-cover analysis.
+    coverQuery(input) {
+        const cover = this.reads.coverQuery?.bind(this.reads);
+        if (!cover)
+            return Promise.reject(new Error("the read follower lacks coverQuery"));
+        return cover(input);
+    }
     migrate(input) {
         return this.writes.migrate(input);
     }
-    // reads → the router (it stamps `wsEndpoint` onto the outputs)
+    // reads → the fleet (one FLEET_URL follower; the affinity ticket + Fly edge place the machine)
     materialize(input) {
         return this.reads.materialize(input);
     }
@@ -373,6 +447,23 @@ class AbsorbedReplay extends Error {
         super("mutation absorbed by mid dedup at session begin");
     }
 }
+const MUTATOR_CONFLICT_MAX_ATTEMPTS = 5;
+function isRetryableCommitConflict(error) {
+    if (!(error instanceof DaemonHttpError) || error.status !== 409)
+        return false;
+    try {
+        const body = JSON.parse(error.body);
+        return body.code === "retryable-conflict" && body.retryable === true;
+    }
+    catch {
+        return false;
+    }
+}
+async function mutatorConflictBackoff(attempt) {
+    const ceiling = Math.min(32, 2 ** attempt);
+    const millis = ceiling + Math.floor(Math.random() * 4);
+    await new Promise((resolve) => setTimeout(resolve, millis));
+}
 /**
  * The daemon server tx (DAEMON-INTERACTIVE-TXN-DESIGN.md §5): ONE authoring surface, two
  * execution strategies. It starts ACCUMULATING — a pure-write mutator ships one batch to
@@ -633,43 +724,55 @@ class PgLiveTx {
 export function daemonBackend(daemon) {
     return {
         dialect: sqliteDialect,
-        async runMutation({ envelope, render, run }) {
-            const tx = new DaemonLazyTx(render, daemon, envelope);
-            try {
-                await run(tx);
-            }
-            catch (err) {
-                // A begin-absorbed replay: the authoritative outcome already committed — answer it,
-                // whatever the body did with the unwind (§4.1; the latch, not the throw, decides).
-                if (tx.absorbed)
-                    return { accepted: true, output: tx.absorbed };
-                if (err instanceof BackendError) {
-                    await tx.rollbackSessionQuietly();
-                    throw err.driverError; // infra — never a user rejection
-                }
-                const reason = errMessage(err);
-                // Data first, watermark second: the rollback releases the single writer that the
-                // `/reject-mutation` lmid-only commit needs (§2.4 on the session path).
-                await tx.rollbackSessionQuietly();
-                const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
-                return { accepted: false, reason, output };
-            }
-            if (tx.absorbed)
-                return { accepted: true, output: tx.absorbed };
-            if (tx.session) {
+        async runMutation(input) {
+            for (let attempt = 0; attempt < MUTATOR_CONFLICT_MAX_ATTEMPTS; attempt++) {
                 try {
-                    return { accepted: true, output: await tx.commitSession() };
+                    const { envelope, render, run } = input;
+                    const tx = new DaemonLazyTx(render, daemon, envelope);
+                    try {
+                        await run(tx);
+                    }
+                    catch (err) {
+                        // A begin-absorbed replay: the authoritative outcome already committed — answer it,
+                        // whatever the body did with the unwind (§4.1; the latch, not the throw, decides).
+                        if (tx.absorbed)
+                            return { accepted: true, output: tx.absorbed };
+                        if (err instanceof BackendError) {
+                            await tx.rollbackSessionQuietly();
+                            throw err.driverError; // infra — never a user rejection
+                        }
+                        const reason = errMessage(err);
+                        // Data first, watermark second: rollback releases this session's connection before
+                        // the lmid-only rejection commit.
+                        await tx.rollbackSessionQuietly();
+                        const output = await daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
+                        return { accepted: false, reason, output };
+                    }
+                    if (tx.absorbed)
+                        return { accepted: true, output: tx.absorbed };
+                    if (tx.session) {
+                        try {
+                            return { accepted: true, output: await tx.commitSession() };
+                        }
+                        catch (err) {
+                            if (err instanceof BackendError)
+                                throw err.driverError;
+                            throw err;
+                        }
+                    }
+                    const txn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
+                    if (tx.idempotencyKey !== undefined)
+                        txn.idempotencyKey = tx.idempotencyKey;
+                    return { accepted: true, output: await daemon.executeSqlTxn(txn) };
                 }
-                catch (err) {
-                    if (err instanceof BackendError)
-                        throw err.driverError; // infra (client retries; dedup absorbs)
-                    throw err;
+                catch (error) {
+                    if (!isRetryableCommitConflict(error) || attempt + 1 === MUTATOR_CONFLICT_MAX_ATTEMPTS) {
+                        throw error;
+                    }
+                    await mutatorConflictBackoff(attempt);
                 }
             }
-            const txn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
-            if (tx.idempotencyKey !== undefined)
-                txn.idempotencyKey = tx.idempotencyKey;
-            return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+            throw new Error("unreachable mutator conflict retry loop");
         },
         reject({ envelope, reason }) {
             return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
@@ -851,7 +954,11 @@ export function registerQueries(queries) {
         if (Object.prototype.hasOwnProperty.call(out, query.queryName)) {
             throw new Error(`registerQueries: duplicate query name "${query.queryName}"`);
         }
-        out[query.queryName] = (ctx, args) => query.resolve(args, ctx);
+        const wrapped = (ctx, args) => query.resolve(args, ctx);
+        // The §2.1 realtime label survives this seam (read it back with {@link queryRealtimeLabel}) —
+        // the lease path looks up (room profile, args mapping) by query name. Unlabeled queries get
+        // the exact bare wrapper they always did.
+        out[query.queryName] = query.realtime === undefined ? wrapped : attachRealtimeLabel(wrapped, query.realtime);
     }
     return out;
 }
@@ -886,11 +993,42 @@ export function sharedApiMutators(registry, principal) {
     }
     return out;
 }
-export function queryResultToAst(result) {
-    if (result && typeof result === "object" && "ast" in result && typeof result.ast === "function") {
-        return result.ast();
-    }
-    return result;
+/**
+ * Wrap a SHARED (generator) mutator with a row-level ACCESS GUARD — the multi-tenant authz twin of
+ * {@link sharedApiMutators}. It parses the untrusted wire args, derives the {@link MutatorCtx}
+ * principal (the SAME mapping you pass to `sharedApiMutators`), evaluates `predicate` against the OPEN
+ * mutation txn (so it can READ the rows the write depends on), and throws `forbidden` (403 — the
+ * client's optimistic write snaps back) when access is denied; otherwise it drives the SAME body the
+ * client predicts ({@link runSharedMutation}). Use it for the entries that need server-only authority
+ * the client cannot predict, OVERRIDING the auto-wrapped default (spread `sharedApiMutators(...)`
+ * first, then the guarded overrides win by key):
+ *
+ * ```ts
+ * const principal = (ctx) => ({ user: requireUser(ctx.user) });
+ * mutators: defineApiMutators({
+ *   ...sharedApiMutators(sharedMutators, principal),
+ *   updateSlide: guardMutator(sharedMutators.updateSlide, principal,
+ *     async (tx, a, { user }) =>
+ *       (await tx.query(q.slide.where.id(a.slideId).where(editableBy(user)).one())) != null,
+ *     { message: "not permitted to edit this slide" }),
+ * }),
+ * ```
+ *
+ * The predicate keeps the shared body READ-FREE, so the client's `.folded` hot paths (drag/keystroke)
+ * still fold — the read is server-side only. Return `false` to deny (→ the default or `opts.message`
+ * forbidden); return `true`/nothing to allow. To reject with a different status/message (a business
+ * rejection, a not-found), throw a {@link RindleApiError} from inside the predicate instead. `principal`
+ * runs before the predicate, so it too may throw `forbidden` for an anonymous caller.
+ */
+export function guardMutator(gen, principal, predicate, opts) {
+    return async (tx, raw, ctx) => {
+        const args = gen.args.parse(raw);
+        const pctx = principal(ctx);
+        if ((await predicate(tx, args, pctx)) === false) {
+            throw new RindleApiError("forbidden", opts?.message ?? "not permitted", 403);
+        }
+        return runSharedMutation(gen, args, pctx, tx);
+    };
 }
 /**
  * Dump every registered named query's wire AST — feeder 1 ("exemplar enumeration") of
@@ -968,6 +1106,76 @@ function normalizeCondition(c) {
             };
     }
 }
+/**
+ * The runtime {@link MutationScope} handed to a {@link ScopedMutator}. It owns the single atomic
+ * transaction (delegating to {@link MutationBackend.runMutation} — the exact machinery a tx-form
+ * mutator uses), but lets the AUTHOR decide when it opens, so server-only work can run outside it.
+ *
+ * It records its outcome so the harness — not the author — enforces the `lmid`-always-advances
+ * invariant: `phase` reports whether the tx committed, business-rejected, or never ran, and `infra`
+ * latches a backend (DB) failure. Because the backend's `runMutation` RETURNS `{accepted:false}` for
+ * a business rejection (having already advanced `lmid` alone) and THROWS only for infra, `transact`
+ * can cleanly re-throw {@link MutationRejected} on the former (for author compensation) and propagate
+ * the raw driver error on the latter.
+ */
+class MutationScopeImpl {
+    attempted = false;
+    backend;
+    envelope;
+    render;
+    /** Set once `transact` resolved through the backend (accepted OR business-rejected). */
+    outcome;
+    /** The value the backend threw on INFRA (the DB failed) — always propagated, never an `lmid`
+     *  advance. Its presence is tracked by {@link infraLatched}, NOT by testing this for `undefined`:
+     *  a driver may legitimately reject with a falsy value, and misreading that as "no infra" would
+     *  reclassify a lost-connection failure as a business rejection and wrongly advance `lmid`. */
+    infra;
+    /** True once an INFRA failure latched, regardless of its (possibly falsy) value. */
+    infraLatched = false;
+    /** The in-flight `transact` promise. `settle` awaits it before sealing, so a transact the author
+     *  FORGOT to await (a floating promise — nothing here lints against it) is still resolved to its
+     *  real outcome first; otherwise the seal would read `untouched`, reply with a phantom no-op, and
+     *  let the real write commit out-of-band after the response was already sent. */
+    pending;
+    constructor(backend, envelope, render) {
+        this.backend = backend;
+        this.envelope = envelope;
+        this.render = render;
+    }
+    transact(first, args, ctx) {
+        if (this.attempted)
+            throw new Error("scope.transact may be called at most once per mutation");
+        this.attempted = true;
+        const promise = this.drive(first, args, ctx);
+        // Record the in-flight promise so `settle` can await it even when the author didn't. Errors are
+        // latched onto `this` (outcome / infra), so this tracking copy swallows them — the author's
+        // returned `promise` still rejects for them to await/catch.
+        this.pending = promise.then(() => undefined, () => undefined);
+        return promise;
+    }
+    async drive(first, args, ctx) {
+        // A shared (generator) mutator is driven via the isomorphic seam; a plain callback gets the raw tx.
+        const run = isGeneratorMutator(first)
+            ? async (tx) => {
+                await runSharedMutation(first, args, ctx, tx);
+            }
+            : async (tx) => {
+                await first(tx);
+            };
+        let outcome;
+        try {
+            outcome = await this.backend.runMutation({ envelope: this.envelope, render: this.render, run });
+        }
+        catch (err) {
+            this.infra = err; // the backend throws ONLY for infra; a business rejection returns {accepted:false}
+            this.infraLatched = true;
+            throw err;
+        }
+        this.outcome = outcome;
+        if (!outcome.accepted)
+            throw new MutationRejected(outcome.reason);
+    }
+}
 export function createRindleApiServer(opts) {
     const routes = { ...DEFAULT_RINDLE_API_ROUTES, ...opts.routes };
     const mode = opts.mode ?? "normalized";
@@ -980,6 +1188,22 @@ export function createRindleApiServer(opts) {
     // Names that are ALSO configured pins — a lease for one is forced to a `pinned` policy (the lazy
     // floor, §4.1) so the first viewer to route to a follower warms it for late joiners.
     const pinnedNames = new Set((opts.pinnedQueries ?? []).map((p) => p.name));
+    // Rindle Realtime declaration layer (RINDLE-REALTIME-QUERY-ENABLEMENT §2, slice G-iv-a):
+    // compile the named room profiles and run every "loud at registration" (§2.3) check NOW —
+    // construction is the moment a misconfigured profile or label can still fail the deploy,
+    // not a 3am room boot. The legacy flat `resolveFootprint` stays the anonymous profile and
+    // is deliberately NOT probed or validated (byte-identical legacy behavior).
+    const realtime = opts.realtime;
+    const roomProfiles = compileRoomProfiles({
+        rooms: realtime?.rooms,
+        schema: opts.schema,
+        warn: realtime?.warn,
+    });
+    assertLabeledProfilesExist(opts.queries, roomProfiles);
+    if (realtime !== undefined && roomProfiles.size === 0 && realtime.resolveFootprint === undefined) {
+        throw new Error("realtime: configure at least one room profile (realtime.rooms) or the legacy resolveFootprint — " +
+            "a realtime host with neither can never boot a room.");
+    }
     // Resolve a named query (+ args) to its AST under a given context — the shared path for both
     // a per-viewer lease and a system-level pin (which skips per-user authorization).
     const resolveAst = async (name, args, context) => {
@@ -991,6 +1215,344 @@ export function createRindleApiServer(opts) {
             : await query(context, args);
         return queryResultToAst(result);
     };
+    // ---------------------------------------------------------------- the room-serve decision
+    //
+    // RINDLE-REALTIME-QUERY-ENABLEMENT §2.1 lease-flow steps 2–5, slice G-iv-b. Everything here is
+    // FAIL-OPEN: any missing wiring, refused proof, or thrown error means the lease is served from
+    // the daemon EXACTLY as today (no `realtime` block, top-level fields untouched) plus a one-time
+    // diagnostic — a coverage/config problem must never block a lease.
+    const realtimeWarn = realtime?.warn ?? ((message) => console.warn(message));
+    // One-time per (queryName, profile): the serve decision runs on EVERY lease, so an uncovered
+    // labeled query would otherwise warn once per viewer per mount.
+    const warnedRoomServe = new Set();
+    const warnRoomServeOnce = (queryName, profile, reasons) => {
+        const key = `${queryName}\u0000${profile}`;
+        if (warnedRoomServe.has(key))
+            return;
+        warnedRoomServe.add(key);
+        realtimeWarn(`query "${queryName}" is labeled realtime (room profile "${profile}") but is NOT room-served — ` +
+            `${reasons.join("; ")}. It serves from the daemon (correct, just not room-accelerated). ` +
+            `This warning fires once per (query, profile).`);
+    };
+    // The §2.3 aggregate refusal: the client's aggregate overlay is daemon-gated until post-G, so
+    // an aggregate/reduce-shaped query is refused room-serving REGARDLESS of coverage.
+    const AGGREGATE_REFUSAL = "the query AST contains an aggregate/reduce shape — aggregate overlays are daemon-gated until post-G";
+    // Verdict cache. The verdict is a pure function of exactly two inputs — the resolved footprint
+    // AST and the resolved query AST — so the tightest SOUND key is those two ASTs themselves
+    // (stable-stringified), scoped by (queryName, profile) for legibility. Args/user/ctx need no
+    // separate slot precisely because anything that changes the verdict must change one of the two
+    // ASTs (predicate literals embed the args; ctx-scoped queries embed the principal); keying on
+    // `(name, args)` alone would ALIAS two users' different ASTs under one verdict — unsound.
+    // Bounded FIFO (Map iterates in insertion order) so per-user literals can't grow it forever.
+    const coverVerdicts = new Map();
+    const COVER_VERDICT_CACHE_MAX = 1024;
+    const maybeRoomServe = async (input, queryAst, context, subject) => {
+        // (a) the label + (b) its profile — the fast bail keeps unlabeled leases byte-identical.
+        const label = queryRealtimeLabel(opts.queries?.[input.name]);
+        if (label === undefined)
+            return undefined;
+        const profile = roomProfiles.get(label.room);
+        if (profile === undefined)
+            return undefined; // unreachable: construction asserted it exists
+        try {
+            // (c) the wiring gates — each absence fail-opens with a one-time, named reason.
+            if (realtime?.locateRoom === undefined) {
+                warnRoomServeOnce(input.name, profile.name, ["realtime.locateRoom is not configured"]);
+                return undefined;
+            }
+            const coverQuery = opts.daemon.coverQuery?.bind(opts.daemon);
+            if (coverQuery === undefined) {
+                warnRoomServeOnce(input.name, profile.name, [
+                    "the configured daemon client does not implement coverQuery (/cover-check)",
+                ]);
+                return undefined;
+            }
+            const tokenKey = realtime.roomTokenKey;
+            if (tokenKey === undefined) {
+                warnRoomServeOnce(input.name, profile.name, [
+                    "realtime.roomTokenKey is not configured — the room lease token cannot be signed",
+                ]);
+                return undefined;
+            }
+            // The token's subject: the same resolved subject the daemon lease carries, else the
+            // browser's clientId. The shell refuses a subject-less token, so with neither we fail open.
+            const sub = subject ?? input.clientId;
+            if (sub === undefined) {
+                warnRoomServeOnce(input.name, profile.name, [
+                    "no token subject — configure `subject` (or have the client send clientId)",
+                ]);
+                return undefined;
+            }
+            // §2.1: (roomProfile, roomArgs) via the label's args mapping; key + doc minted SERVER-side
+            // (input.args just passed the query's own validation inside resolveAst).
+            const roomArgs = label.args !== undefined ? label.args(input.args) : input.args;
+            const key = profile.key(roomArgs);
+            const doc = mintRoomDoc(profile.name, key);
+            // The profile footprint for THIS key under the request ctx (works for non-static
+            // profiles), with the §2.3 unwindowed backstop `/room-boot` also applies.
+            const footprintAst = queryResultToAst(await profile.footprint(key, context));
+            assertUnwindowedFootprint(footprintAst, profile.name);
+            const verdictKey = `${input.name}\u0000${profile.name}\u0000${stableStringify(footprintAst)}\u0000${stableStringify(queryAst)}`;
+            let verdict = coverVerdicts.get(verdictKey);
+            if (verdict === undefined) {
+                verdict = astHasAggregate(queryAst)
+                    ? { covered: false, reasons: [AGGREGATE_REFUSAL] }
+                    : await coverQuery({ footprint: footprintAst, query: queryAst });
+                // (A coverQuery THROW never lands here — the outer catch fail-opens without caching, so
+                // a transient daemon failure doesn't pin an uncovered verdict.)
+                if (coverVerdicts.size >= COVER_VERDICT_CACHE_MAX) {
+                    coverVerdicts.delete(coverVerdicts.keys().next().value);
+                }
+                coverVerdicts.set(verdictKey, verdict);
+            }
+            if (!verdict.covered) {
+                warnRoomServeOnce(input.name, profile.name, verdict.reasons ?? ["not provably covered"]);
+                return undefined;
+            }
+            // Covered ⇒ assemble the realtime block. The room endpoint rides ITS OWN field
+            // (`realtime.wsEndpoint`) — a separate connection from the daemon session's fixed ws host.
+            const { wsEndpoint } = await realtime.locateRoom(doc);
+            const now = Date.now();
+            const ttlMs = realtime.roomTokenTtlMs ?? DEFAULT_ROOM_TOKEN_TTL_MS;
+            const { mintRoomToken, scopeSpecsHash } = await loadRoomTokenModule();
+            // The lease-wire specs, hashed ONCE: the same value is stamped on the token (so the
+            // shell can flag scope skew — a profile edited under a live room, whose gate armed
+            // with the OLD specs at boot) and returned as the client's `tables`.
+            const tables = compileRoomTableSpecs(footprintAst, profile.context);
+            const roomToken = await mintRoomToken({
+                doc,
+                ast: queryAst, // the APPROVED resolved AST — the client carries it, it can't mint/alter it
+                sub,
+                kid: tokenKey.kid,
+                key: tokenKey.secret,
+                ttlMs,
+                now,
+                scopesHash: scopeSpecsHash(tables),
+            });
+            return {
+                // `parse_source_key` (rust/src/wasm/db.rs): anything but the reserved "daemon" is a room
+                // source; the client-store convention is `room:` + the wire doc.
+                sourceKey: `room:${doc}`,
+                wsEndpoint,
+                roomToken,
+                exp: now + ttlMs,
+                doc,
+                tables,
+            };
+        }
+        catch (e) {
+            // Fail open — a lease is never blocked on the proof. Not cached (may be transient).
+            warnRoomServeOnce(input.name, profile.name, [`room-serve failed: ${errMessage(e)}`]);
+            return undefined;
+        }
+    };
+    // ---------------------------------------------------------------- the §4 lifecycle mint (I-iii)
+    //
+    // Gated on the OPT-IN `realtime.lifecycle` block: absent, this whole section is dead code and
+    // every lease response is byte-identical to pre-lifecycle. Present, a labeled lease gains the
+    // doorbell system lease and a ROOM-SERVED one the fence bundle (see {@link QueryLeaseLifecycle}).
+    // FAIL-OPEN like the room-serve decision: a mint failure (e.g. a daemon that never ran
+    // `enable_realtime_lifecycle`) warns once per query and the lease ships without the block.
+    const warnedLifecycle = new Set();
+    const warnLifecycleOnce = (queryName, reason) => {
+        if (warnedLifecycle.has(queryName))
+            return;
+        warnedLifecycle.add(queryName);
+        realtimeWarn(`query "${queryName}" is realtime-labeled with lifecycle configured, but its lifecycle ` +
+            `system leases were not minted — ${reason}. The lease serves without the lifecycle block ` +
+            `(correct, just no §4 upgrade/downgrade plane). This warning fires once per query.`);
+    };
+    /** THE SCOPE-KEY DECISION (§4.1): the doorbell scope IS the wire room doc — `"<profile>/<key>"`
+     *  via {@link mintRoomDoc}, the same computation `maybeRoomServe` runs (label args mapping →
+     *  `profile.key`) and the same key `locateRoom`/`/room-boot` address the room by. Occupancy
+     *  (I-iv writes the `_rindle_scope_sessions` rows) must be counted on EXACTLY the key the 1→2
+     *  transition provisions, and this is that key. Computed independently of the room-serve
+     *  decision on purpose: the doorbell rides every LABELED lease — an uncovered/unwired labeled
+     *  query still counts toward occupancy (its collaborators still want the upgrade). */
+    const lifecycleScopeDoc = (input) => {
+        const label = queryRealtimeLabel(opts.queries?.[input.name]);
+        if (label === undefined)
+            return undefined; // unlabeled — no scope to count on
+        const profile = roomProfiles.get(label.room);
+        if (profile === undefined)
+            return undefined; // unreachable: construction asserted it exists
+        const roomArgs = label.args !== undefined ? label.args(input.args) : input.args;
+        return mintRoomDoc(profile.name, profile.key(roomArgs));
+    };
+    const maybeLifecycle = async (input, roomServed, subject, routingKey) => {
+        if (realtime?.lifecycle === undefined)
+            return undefined; // the opt-in gate — mint NOTHING
+        try {
+            const doc = lifecycleScopeDoc(input);
+            if (doc === undefined)
+                return undefined;
+            // Each system lease is an ordinary daemon materialization (the room-boot direct pattern),
+            // carrying the SAME subject/routingKey as the primary lease so a routed deploy co-locates
+            // the system streams on the follower the client's daemon session already lives on. The
+            // daemon dedups by canonical query, so N clients' doorbells over one scope share ONE
+            // materialization (each still minting its own leaseToken); the client-scoped fence ASTs
+            // are per-client by construction.
+            const mint = (ast) => opts.daemon.materialize({
+                ast,
+                mode,
+                subject,
+                leaseTtlMs: opts.leaseTtlMs,
+                metadata: routingKey !== undefined ? { routingKey } : undefined,
+                // Lifecycle leases are follower-local exactly like the primary lease. Forward the SAME
+                // opaque placement ticket so every doorbell/fence materialization is minted on the
+                // browser socket's follower instead of independently anycasting across the fleet.
+                ...(input.affinity !== undefined ? { affinity: input.affinity } : {}),
+            });
+            const lease = (table, out, id) => ({
+                table,
+                leaseToken: out.leaseToken,
+                ...(id.scope !== undefined ? { scope: id.scope } : {}),
+                ...(id.doc !== undefined ? { doc: id.doc } : {}),
+                ...(id.clientId !== undefined ? { clientId: id.clientId } : {}),
+            });
+            const lifecycle = {
+                doorbell: lease(SCOPE_SESSIONS_TABLE, await mint(scopeSessionsAst(doc)), { scope: doc }),
+            };
+            // The fence bundle only where a room domain exists to fence (room-served leases): the
+            // §4.2 watermark, the §7.1 daemon-carried ledger, and the §3.3 outcome rows.
+            if (roomServed) {
+                const clientId = input.clientId;
+                lifecycle.fence = [
+                    lease(ROOM_WATERMARK_TABLE, await mint(roomWatermarkAst(doc)), { doc }),
+                    lease(ROOM_CLIENT_MUTATIONS_TABLE, await mint(docClientAst(ROOM_CLIENT_MUTATIONS_TABLE, doc, clientId)), { doc, clientId }),
+                    lease(ROOM_MUTATION_OUTCOMES_TABLE, await mint(docClientAst(ROOM_MUTATION_OUTCOMES_TABLE, doc, clientId)), { doc, clientId }),
+                ];
+            }
+            return lifecycle;
+        }
+        catch (e) {
+            warnLifecycleOnce(input.name, errMessage(e)); // fail open — a lease is never blocked
+            return undefined;
+        }
+    };
+    // ------------------------------------------------------------ the §4.1 occupancy gate (I-iv)
+    //
+    // Runs on EVERY labeled lease under the opt-in `realtime.lifecycle` config (mint AND renewal —
+    // both land on this same route), BEFORE the room-serve decision: (1) sweep + upsert the
+    // caller's session row through the normal write path (the write is the doorbell — I-i's CDC
+    // capture fans the row delta to every solo watcher's doorbell subscription), then (2) read the
+    // occupancy count and return the D6 gate verdict `maybeRoomServe` is conditioned on. The upsert
+    // deliberately precedes the count so the caller's own row is on disk when the verdict is
+    // computed (its own presence rides the `+ 1`, and — more importantly — a concurrent second
+    // client's read sees it). Ordering within the pair is otherwise value-neutral: the count
+    // EXCLUDES the caller's clientId and adds the `+ 1` analytically.
+    //
+    // THE RENEWAL-vs-FRESH DECISION (grounded here because the task forces it): this server is
+    // stateless and the lease request carries no "I am currently room-attached" field, so the gate
+    // CANNOT distinguish a fresh mint from a live room's renewal. Instead of gating on the raw
+    // count (which would suppress a momentarily-solo room's renewal and force the loud client-side
+    // downgrade anomaly), the gate applies the §9.1 hysteresis DIRECTLY FROM THE LINGERING ROWS the
+    // D4 sweep preserves: room-serve iff `liveOthers + self ≥ minSessions` OR some other session
+    // expired within `graceMs`. A renewal is therefore never suppressed until the scope has been
+    // solo SUSTAINED past the grace window — which is exactly Slice I-v's downgrade condition, read
+    // from the same rows; I-v replaces that post-grace loud suppression with the fenced downgrade
+    // dance, refining (not re-deciding) this verdict. A truly fresh solo scope (no other row, live
+    // or lingering) is suppressed immediately — the D6 point.
+    //
+    // Timestamps are `Date.now()` server-side throughout (mint, sweep, count): occupancy tolerates
+    // clock skew between api-server instances up to ~grace — a skewed `now` moves a session between
+    // "live" and "in-grace", both of which hold the gate open; only skew past the grace+slack band
+    // could mis-sweep, and the slack exists to keep that band clear.
+    //
+    // A request with NO `clientId` (a non-shipped client — the shipped one always sends it, see
+    // `postLease`) upserts NO row and contributes NOTHING to occupancy, including to its own gate:
+    // it room-serves only if the OTHER sessions alone reach `minSessions` (there is no session
+    // identity to count it under, D7). It still gets its doorbell (`maybeLifecycle` is independent).
+    //
+    // FAIL-OPEN, like every lifecycle surface: an occupancy failure (e.g. a daemon that never ran
+    // `enable_realtime_lifecycle`) warns once per query and returns `true` — the gate falls away
+    // and the lease serves exactly as pre-I-iv. Suppressing on infrastructure failure would turn
+    // realtime off fleet-wide from one missing table; never block, never suppress, on an error.
+    const warnedOccupancy = new Set();
+    const lifecycleOccupancy = async (input) => {
+        const lc = realtime?.lifecycle;
+        if (lc === undefined)
+            return { gateOpen: true, roomPlausible: false, doc: undefined }; // lifecycle off — the gate does not exist (inert-until-fed)
+        const doc = lifecycleScopeDoc(input);
+        if (doc === undefined)
+            return { gateOpen: true, roomPlausible: false, doc: undefined }; // unlabeled — no scope to count on, nothing to gate
+        try {
+            const now = Date.now();
+            const minSessions = lc.minSessions ?? DEFAULT_LIFECYCLE_MIN_SESSIONS;
+            const graceMs = lc.graceMs ?? DEFAULT_LIFECYCLE_GRACE_MS;
+            const sessionTtlMs = lc.sessionTtlMs ?? opts.leaseTtlMs ?? DEFAULT_SESSION_TTL_MS;
+            const clientId = input.clientId;
+            // (1) sweep + upsert, ONE write txn (D4: the sweep shares the upsert's transaction — no
+            // separate maintenance pass, and the linger bound holds atomically with the refresh).
+            const statements = [
+                { sql: SESSION_SWEEP_SQL, params: [doc, now - (graceMs + SESSION_SWEEP_SLACK_MS)] },
+            ];
+            if (clientId !== undefined) {
+                statements.push({ sql: SESSION_UPSERT_SQL, params: [doc, clientId, now + sessionTtlMs] });
+            }
+            await opts.daemon.executeSqlTxn({ statements });
+            // (2) the count — read-your-writes via `consistency: "strong"` (see the section note above).
+            const read = await opts.daemon.executeSqlRead({
+                sql: clientId !== undefined ? SESSION_COUNT_OTHERS_SQL : SESSION_COUNT_SQL,
+                params: clientId !== undefined
+                    ? [now, now, now - graceMs, doc, clientId]
+                    : [now, now, now - graceMs, doc],
+                consistency: "strong",
+            });
+            const cells = read.rows[0] ?? [];
+            const liveOthers = Number(cells[0] ?? 0); // SUM over zero rows is NULL — coerce
+            const graceOthers = Number(cells[1] ?? 0);
+            const totalOthers = Number(cells[2] ?? 0); // ALL other rows (any expiry, pre-sweep)
+            const self = clientId !== undefined ? 1 : 0;
+            return {
+                gateOpen: liveOthers + self >= minSessions || graceOthers > 0,
+                // Room plausibly exists ⇒ this scope was shared (a room was provisioned on the 1→2). A
+                // never-shared solo doc has NO other row and must never drain (no wasted room boot).
+                roomPlausible: totalOthers > 0,
+                doc,
+            };
+        }
+        catch (e) {
+            if (!warnedOccupancy.has(input.name)) {
+                warnedOccupancy.add(input.name);
+                realtimeWarn(`query "${input.name}" is realtime-labeled with lifecycle configured, but the §4.1 ` +
+                    `occupancy step failed — ${errMessage(e)}. The occupancy gate fail-opens (the lease ` +
+                    `serves exactly as pre-I-iv; no session row was counted). This warning fires once per query.`);
+            }
+            return { gateOpen: true, roomPlausible: false, doc };
+        }
+    };
+    // ------------------------------------------------------------ the §4.2 downgrade drain (I-v)
+    //
+    // When the occupancy gate closes for a scope a room plausibly hosted, drain that room to a
+    // COMMITTED flush seq and hand it back as the fence. `drainRoom` (deployment-wired to the room
+    // shell / DO `/drain`) is idempotent (concurrent api-server instances may both call it) and
+    // fails OPEN — a downgrade must never block a lease, so an unconfigured or throwing hook simply
+    // omits the fence (warn-once) and the client falls to its loud legacy downgrade path.
+    const warnedDrain = new Set();
+    const warnDrainOnce = (queryName, reason) => {
+        if (warnedDrain.has(queryName))
+            return;
+        warnedDrain.add(queryName);
+        realtimeWarn(`query "${queryName}" downgraded (occupancy gate closed) but no §4.2 fence was attached — ` +
+            `${reason}. The lease ships without the fence; a room-attached client falls back to its ` +
+            `loud legacy downgrade (correct, just not graceful). This warning fires once per query.`);
+    };
+    const maybeDrainRoom = async (queryName, doc) => {
+        const drainRoom = realtime?.lifecycle?.drainRoom;
+        if (drainRoom === undefined) {
+            warnDrainOnce(queryName, "realtime.lifecycle.drainRoom is not configured");
+            return undefined;
+        }
+        try {
+            const { finalFlushSeq } = await drainRoom(doc);
+            return { sourceKey: `room:${doc}`, doc, finalFlushSeq };
+        }
+        catch (e) {
+            warnDrainOnce(queryName, `drainRoom threw — ${errMessage(e)}`);
+            return undefined;
+        }
+    };
     const createQueryLease = async (input) => {
         const context = { user: input.user, request: input.request };
         await assertAuthorized(opts.authorizeQuery, {
@@ -1017,8 +1579,41 @@ export function createRindleApiServer(opts) {
             // The anonymous routing key rides `metadata.routingKey`; the router keys on
             // `subject ?? metadata.routingKey` (§2.2). Omitted when there is none.
             metadata: routingKey !== undefined ? { routingKey } : undefined,
+            // Forward the browser's opaque affinity ticket (if any) so the fleet `fly-replay`s this
+            // materialize to the follower the ws is pinned to (FOLLOWER-AFFINITY-DESIGN.md §4). Opaque —
+            // never verified here. Inert when the reads client is a single daemon (no fleet edge).
+            ...(input.affinity !== undefined ? { affinity: input.affinity } : {}),
         });
-        return queryLeaseResponse(out);
+        const res = queryLeaseResponse(out);
+        // I-iv (§4.1): the occupancy step FIRST — session sweep+upsert, then the D6 gate verdict. A
+        // closed gate suppresses the room-serve ONLY (the lease ships without the realtime block,
+        // indistinguishable from an uncovered query — the fail-open daemon path) while the doorbell
+        // below still rides; lifecycle-off ⇒ `gateOpen: true` unconditionally and this line is inert.
+        const occ = await lifecycleOccupancy(input);
+        // G-iv-b: a covered labeled query ADDITIONALLY gains the realtime block. The daemon lease
+        // above is unconditional (and its fields untouched) — room-serving only ever adds a field,
+        // so an uncovered/unwired/legacy lease stays byte-identical and nothing here can block one.
+        const rt = occ.gateOpen ? await maybeRoomServe(input, ast, context, subject) : undefined;
+        if (rt !== undefined)
+            res.realtime = rt;
+        // I-v (§4.2): the gate CLOSED and a room plausibly hosted this scope — drain it and ride the
+        // fence back so a room-attached client runs the GRACEFUL downgrade instead of the loud legacy
+        // anomaly. A never-shared solo doc (`!roomPlausible`) never drains (no wasted room boot); a
+        // daemon-attached client that receives a stray fence ignores it (its resolver reads only the
+        // daemon fields). `drainRoom` absent/throwing ⇒ no fence (fail-open, warn-once).
+        if (!occ.gateOpen && occ.roomPlausible && occ.doc !== undefined) {
+            const fence = await maybeDrainRoom(input.name, occ.doc);
+            if (fence !== undefined)
+                res.realtimeFence = fence;
+        }
+        // I-iii: under the opt-in `realtime.lifecycle` config a LABELED lease additionally gains the
+        // §4 system-stream block (doorbell always; the fence bundle iff room-served OR downgrade-fenced
+        // — a downgrading client needs the watermark/ledger/outcome streams to run the ghost drop).
+        // Same additive discipline as the realtime block: absent config ⇒ byte-identical response.
+        const lc = await maybeLifecycle(input, rt !== undefined || res.realtimeFence !== undefined, subject, routingKey);
+        if (lc !== undefined)
+            res.lifecycle = lc;
+        return res;
     };
     const readQuery = async (input) => {
         const context = { user: input.user, request: input.request };
@@ -1039,11 +1634,13 @@ export function createRindleApiServer(opts) {
         const subject = await resolveSubject(opts.subject, input);
         const routingKey = await resolveRoutingKey(opts.routingKey, input);
         const visibilityKey = subject ?? routingKey;
-        const out = await opts.daemon.query({ ast, visibilityKey, ttlMs: opts.readIdleTtlMs });
-        const res = { rows: out.rows, cvMin: out.cvMin, queryKey: out.queryKey };
-        if (out.wsEndpoint !== undefined)
-            res.wsEndpoint = out.wsEndpoint;
-        return res;
+        const out = await opts.daemon.query({
+            ast,
+            visibilityKey,
+            ttlMs: opts.readIdleTtlMs,
+            ...(input.affinity !== undefined ? { affinity: input.affinity } : {}),
+        });
+        return { rows: out.rows, cvMin: out.cvMin, queryKey: out.queryKey };
     };
     const pushMutation = async (input) => {
         const context = { user: input.user, request: input.request };
@@ -1061,24 +1658,82 @@ export function createRindleApiServer(opts) {
         catch (err) {
             return reject(backend, input.envelope, errMessage(err));
         }
-        // Run the mutator INSIDE the backend's transaction. A throw from the mutator body is a business
-        // rejection (roll data back, advance `lmid`); a BackendError (DB failure) rejects this promise.
+        const mctx = {
+            user: input.user,
+            envelope: input.envelope,
+            daemon: opts.daemon,
+            request: input.request,
+        };
+        // SCOPED mutator (WORK-OUTSIDE-TX): the author controls the tx boundary via `scope.transact`,
+        // running server-only code before/after it. The `lmid`-always-advances invariant is OURS, not
+        // the author's — we seal the response from the scope's recorded state, so an early return, a
+        // never-called transact, or a swallowed rejection can't wedge the client's pending queue.
+        if (isScoped(mutator)) {
+            const scope = new MutationScopeImpl(backend, input.envelope, renderIndex);
+            // A throw that reaches `settle` AFTER the outcome is already sealed (post-commit effect, or a
+            // compensation handler after a business rejection) can't change the response — but it must not
+            // vanish. Route it to the app's hook, else log so a failed refund is never fully silent.
+            const reportSealed = (err, phase) => {
+                if (opts.onScopeError)
+                    opts.onScopeError(err, { phase, envelope: input.envelope });
+                else
+                    console.error(`[rindle api-server] scoped mutator ${input.envelope.name}: post-${phase} code threw (outcome already sealed):`, err);
+            };
+            // Derive the response from the scope's OUTCOME (not the body's return), so control flow in the
+            // author's function can't skip the lmid advance. `caught` distinguishes "the body threw"
+            // (present, even if the thrown value was `undefined`) from "it returned cleanly".
+            const settle = async (caught) => {
+                // Seal from the REAL outcome even if the author forgot to `await` transact: draining its
+                // in-flight promise here records the outcome/infra before we read it (else a phantom no-op
+                // ships while the real write commits out-of-band). Already-resolved when it WAS awaited.
+                if (scope.pending)
+                    await scope.pending;
+                // Infra always wins: the backend threw, the commit state is unknown — never advance lmid.
+                // Keyed on the latched BOOLEAN, so a driver that rejects with a falsy value is still infra.
+                if (scope.infraLatched)
+                    throw scope.infra;
+                // transact resolved (committed OR business-rejected): seal from its recorded outcome. A
+                // post-commit / post-reject-compensation throw can't change the sealed outcome (its effects
+                // can't roll the tx back, and lmid already advanced §2.4). Rethrowing the MutationRejected is
+                // the sanctioned "compensated, stay rejected" signal — expected, not surfaced. Any OTHER throw
+                // (a FAILED refund, a post-commit effect) must not vanish — surface it.
+                if (scope.outcome) {
+                    if (caught && !(caught.err instanceof MutationRejected)) {
+                        reportSealed(caught.err, scope.outcome.accepted ? "committed" : "rejected");
+                    }
+                    return outcomeToResponse(scope.outcome);
+                }
+                // Never transacted:
+                if (caught) {
+                    // A throw before/around transact. A BackendError is the author signaling INFRA (retry);
+                    // any other throw is a BUSINESS rejection — advance lmid alone so the prediction snaps back.
+                    if (caught.err instanceof BackendError)
+                        throw caught.err.driverError;
+                    return reject(backend, input.envelope, errMessage(caught.err));
+                }
+                // Clean return with no transact — an accepted no-op that STILL advances lmid (the client
+                // predicted a write; its pending entry must resolve).
+                return outcomeToResponse(await backend.runMutation({ envelope: input.envelope, render: renderIndex, run: async () => { } }));
+            };
+            try {
+                await mutator(scope, input.envelope.args, mctx);
+            }
+            catch (err) {
+                return settle({ err });
+            }
+            return settle();
+        }
+        // Run the (tx-form) mutator INSIDE the backend's transaction. A throw from the mutator body is a
+        // business rejection (roll data back, advance `lmid`); a BackendError (DB failure) rejects this promise.
         const outcome = await backend.runMutation({
             envelope: input.envelope,
             render: renderIndex,
             run: async (tx) => {
-                const result = await mutator(tx, input.envelope.args, {
-                    user: input.user,
-                    envelope: input.envelope,
-                    daemon: opts.daemon,
-                    request: input.request,
-                });
+                const result = await mutator(tx, input.envelope.args, mctx);
                 applyResultToTx(result, tx);
             },
         });
-        if (outcome.accepted)
-            return { accepted: true, rejected: false, output: outcome.output };
-        return { accepted: false, rejected: true, reason: outcome.reason, output: outcome.output };
+        return outcomeToResponse(outcome);
     };
     const pushMutations = async (input) => {
         const out = [];
@@ -1137,10 +1792,60 @@ export function createRindleApiServer(opts) {
             throw new Error(`assertPins: ${failures.length} failed — ${failures.join("; ")}`);
         }
     };
+    // The explicit coverage diagnostic (the assertPins pattern: system-level, resolved under
+    // `pinUser`, per-query failures collected — never strand the rest). It runs the REAL check —
+    // the daemon's /cover-check on the actually-resolved ASTs — so its verdicts are exactly the
+    // lease path's, minus the serving wiring (locateRoom/roomTokenKey), which it deliberately
+    // ignores: it answers "is this labeled query coverable", the deployable-config question.
+    const validateRealtime = async (vopts) => {
+        const context = { user: opts.pinUser, request: undefined };
+        const coverQuery = opts.daemon.coverQuery?.bind(opts.daemon);
+        const verdicts = [];
+        for (const [name, q] of Object.entries(opts.queries ?? {})) {
+            const label = queryRealtimeLabel(q);
+            if (label === undefined)
+                continue;
+            const profile = roomProfiles.get(label.room);
+            if (profile === undefined)
+                continue; // unreachable: construction asserted it exists
+            for (const args of vopts?.exemplars?.[name] ?? [null]) {
+                const verdict = { query: name, profile: profile.name, args, covered: false };
+                try {
+                    const ast = await resolveAst(name, args, context);
+                    const roomArgs = label.args !== undefined ? label.args(args) : args;
+                    const footprintAst = queryResultToAst(await profile.footprint(profile.key(roomArgs), context));
+                    assertUnwindowedFootprint(footprintAst, profile.name);
+                    if (astHasAggregate(ast)) {
+                        verdict.reasons = [AGGREGATE_REFUSAL];
+                    }
+                    else if (coverQuery === undefined) {
+                        verdict.reasons = ["the configured daemon client does not implement coverQuery (/cover-check)"];
+                    }
+                    else {
+                        const out = await coverQuery({ footprint: footprintAst, query: ast });
+                        verdict.covered = out.covered;
+                        if (!out.covered)
+                            verdict.reasons = out.reasons ?? ["not provably covered"];
+                    }
+                }
+                catch (e) {
+                    verdict.reasons = [errMessage(e)];
+                }
+                verdicts.push(verdict);
+            }
+        }
+        const uncovered = verdicts.filter((v) => !v.covered);
+        if (vopts?.strict && uncovered.length > 0) {
+            throw new Error(`validateRealtime: ${uncovered.length} labeled query verdict(s) not provably covered — ` +
+                uncovered
+                    .map((v) => `${v.query} (profile "${v.profile}"): ${(v.reasons ?? []).join("; ")}`)
+                    .join(" | "));
+        }
+        return { verdicts, uncovered };
+    };
     // The room write-authority gate (§5.3.1): endpoints are disabled until the app opts in —
     // the `realtime` block (which also activates `/room-boot`) or the deprecated bare
     // `authorizeRoom` (trio only). Hosting an authority is never a default.
-    const realtime = opts.realtime;
     const roomAuthorizer = realtime
         ? (realtime.authorize ?? defaultFlushGate(realtime.shellSecret))
         : opts.authorizeRoom;
@@ -1150,6 +1855,31 @@ export function createRindleApiServer(opts) {
         }
         await assertAuthorized(roomAuthorizer, context);
     };
+    // §2.1 room-key routing: a "<profile>/<key>" doc resolves through its NAMED profile — with the
+    // boot-time unwindowed backstop (§2.3), which covers footprints that weren't statically
+    // resolvable at construction AND key-dependent branches that window only some docs. Anything
+    // else falls through to the legacy single-profile alias BYTE-IDENTICALLY (the anonymous
+    // profile, bare-key form). A named profile wins over a legacy doc that merely contains "/".
+    // Returns the profile's context set beside the AST (H-iv-b: the scope-spec compilation needs
+    // the §2.2 owned/followed split; the legacy anonymous profile has no declaration — empty set).
+    const resolveRoomFootprint = async (rt, doc, context) => {
+        const split = splitRoomDoc(doc);
+        if (split !== undefined) {
+            const profile = roomProfiles.get(split.profile);
+            if (profile !== undefined) {
+                const ast = queryResultToAst(await profile.footprint(split.key, context));
+                assertUnwindowedFootprint(ast, profile.name);
+                return { ast, contextTables: profile.context };
+            }
+        }
+        if (rt.resolveFootprint) {
+            return {
+                ast: queryResultToAst(await rt.resolveFootprint(doc, context)),
+                contextTables: new Set(),
+            };
+        }
+        throw new RindleApiError("not-found", `no room profile matches doc "${doc}" — named profiles are addressed as "<profile>/<key>"`, 404);
+    };
     // The store's verdict rides specific statuses + body shapes (fence / conflict /
     // identity) the room decodes — pass a daemon HTTP error through VERBATIM.
     const daemonVerdict = (e) => {
@@ -1170,6 +1900,7 @@ export function createRindleApiServer(opts) {
         createQueryLease,
         readQuery,
         assertPins,
+        validateRealtime,
         pushMutation,
         pushMutations,
         handleApplyRowChangeTxnJson: async (body, context) => {
@@ -1201,6 +1932,7 @@ export function createRindleApiServer(opts) {
         handleRoomLmidsJson: async (body, context) => {
             await roomGate(context);
             const msg = parseObject(body, "room-lmids request");
+            const doc = parseString(msg.doc, "doc");
             if (!Array.isArray(msg.clients) || msg.clients.some((c) => typeof c !== "string")) {
                 throw new RindleApiError("bad-request", "clients must be an array of strings", 400);
             }
@@ -1209,7 +1941,7 @@ export function createRindleApiServer(opts) {
                 throw new Error("the configured daemon client does not implement roomLmids");
             }
             try {
-                return { status: 200, body: await lmids({ clients: msg.clients }) };
+                return { status: 200, body: await lmids({ doc, clients: msg.clients }) };
             }
             catch (e) {
                 return daemonVerdict(e);
@@ -1224,7 +1956,7 @@ export function createRindleApiServer(opts) {
             const doc = parseString(msg.doc, "doc");
             if (msg.instance !== undefined)
                 parseString(msg.instance, "instance"); // diagnostic identity only
-            const ast = queryResultToAst(await realtime.resolveFootprint(doc, context));
+            const { ast, contextTables } = await resolveRoomFootprint(realtime, doc, context);
             const claim = opts.daemon.claimRoomEpoch?.bind(opts.daemon);
             if (!claim) {
                 throw new Error("the configured daemon client does not implement claimRoomEpoch");
@@ -1252,6 +1984,9 @@ export function createRindleApiServer(opts) {
                 const res = {
                     epoch,
                     upstreamLeaseToken: lease.leaseToken,
+                    // H-iv-b: the §3.3 commit-gate scope specs, for named-profile AND legacy docs alike
+                    // (the footprint AST is resolved either way; legacy has an empty context set).
+                    scopes: compileRoomScopeSpecs(ast, contextTables),
                     flush: {
                         urls: {
                             apply: routes.applyRowChangeTxn,
@@ -1261,7 +1996,9 @@ export function createRindleApiServer(opts) {
                         headers,
                     },
                 };
-                const upstreamWsEndpoint = realtime.upstreamWsEndpoint ?? lease.wsEndpoint;
+                if (lease.affinity !== undefined)
+                    res.upstreamAffinity = lease.affinity;
+                const upstreamWsEndpoint = realtime.upstreamWsEndpoint;
                 if (upstreamWsEndpoint !== undefined)
                     res.upstreamWsEndpoint = upstreamWsEndpoint;
                 return { status: 200, body: res };
@@ -1278,6 +2015,7 @@ export function createRindleApiServer(opts) {
                 args: msg.args ?? null,
                 request: context.request,
                 clientId: typeof msg.clientId === "string" ? msg.clientId : undefined,
+                affinity: typeof msg.affinity === "string" ? msg.affinity : undefined,
             });
         },
         handleReadJson: (body, context) => {
@@ -1288,6 +2026,7 @@ export function createRindleApiServer(opts) {
                 args: msg.args ?? null,
                 request: context.request,
                 clientId: typeof msg.clientId === "string" ? msg.clientId : undefined,
+                affinity: typeof msg.affinity === "string" ? msg.affinity : undefined,
             });
         },
         handleMutateJson: (body, context) => {
@@ -1444,24 +2183,155 @@ async function resolveRoutingKey(routingKey, input) {
     return typeof routingKey === "function" ? routingKey(input) : routingKey;
 }
 function queryLeaseResponse(out) {
-    const res = {
+    return {
         leaseToken: out.leaseToken,
         materializationId: out.materializationId,
         queryKey: out.queryKey,
         reused: out.reused,
     };
-    // Only present in a routed deploy — absent reproduces today's single-daemon response exactly.
-    if (out.wsEndpoint !== undefined)
-        res.wsEndpoint = out.wsEndpoint;
-    return res;
 }
 function errMessage(reason) {
     return String(reason?.message ?? reason);
 }
+// --------------------------------------------------------- lifecycle system leases (Slice I-iii)
+// The four §4 lifecycle system tables, mirrored VERBATIM from the daemon DDL — the source of
+// truth is `rust/rindle-replica/src/mutations.rs` (`realtime_lifecycle_ddl()` + the room-ledger
+// DDL in `enable_client_mutations`); duplicated here like `DEFAULT_ROUTES` is client-side so this
+// package needs no engine import. `Db::enable_realtime_lifecycle` REGISTERS all four, so a
+// hand-built AST over them materializes and resolves `hello` like any base table (the room-boot
+// direct-materialize pattern).
+const SCOPE_SESSIONS_TABLE = "_rindle_scope_sessions";
+const ROOM_WATERMARK_TABLE = "_rindle_room_watermark";
+const ROOM_CLIENT_MUTATIONS_TABLE = "_rindle_room_client_mutations";
+const ROOM_MUTATION_OUTCOMES_TABLE = "_rindle_room_mutation_outcomes";
+// --------------------------------------------------------- occupancy counting (Slice I-iv, §4.1)
+//
+// The occupancy step rides the NORMAL surfaces end to end: the session upsert + lazy sweep are one
+// `executeSqlTxn` (a plain write txn — CDC-captured since I-i, so the row landing IS the doorbell
+// delta fanning to every subscribed solo client; no clientID/mid — a system write must never
+// advance an lmid — and no idempotencyKey — a renewal's re-upsert must re-run, that is the
+// refresh), and the count is one `executeSqlRead` with `consistency: "strong"` — the read surface
+// the api-server already has against the daemon (the `DaemonLazyTx` fallback precedent above).
+// "strong" routes the read to the WRITE MASTER in a split deploy, which just serialized our
+// upsert: read-your-writes without a mutation session (the interactive-txn machinery is optional
+// on the daemon interface and far heavier than this two-round-trip pair needs).
+/** Default {@link RindleRealtimeLifecycleOptions.minSessions} — the §4.1 1→2 trigger. */
+const DEFAULT_LIFECYCLE_MIN_SESSIONS = 2;
+/** Default {@link RindleRealtimeLifecycleOptions.graceMs} — the §9.1 hysteresis window. */
+const DEFAULT_LIFECYCLE_GRACE_MS = 120_000;
+/** Default {@link RindleRealtimeLifecycleOptions.sessionTtlMs} fallback when no `leaseTtlMs` is
+ *  configured either — 5 minutes, the {@link DEFAULT_ROOM_TOKEN_TTL_MS} cadence (see the field doc). */
+const DEFAULT_SESSION_TTL_MS = 5 * 60_000;
+/** Sweep slack past the grace window (D4): rows are deleted only once expired for MORE than
+ *  `graceMs + this` — the linger I-v's downgrade decision reads must comfortably outlive the
+ *  grace comparison itself under clock skew between api-server instances (occupancy tolerates
+ *  skew ≤ grace; the slack keeps the boundary case out of the deletable band). */
+const SESSION_SWEEP_SLACK_MS = 60_000;
+/** D7 upsert: one row per (scope, clientId) — `(scope, client_id)` is the table's PRIMARY KEY
+ *  (`realtime_lifecycle_ddl()`), so a renewal refreshes `expires_at` in place. */
+const SESSION_UPSERT_SQL = `INSERT INTO ${SCOPE_SESSIONS_TABLE} (scope, client_id, expires_at) VALUES (?, ?, ?) ` +
+    `ON CONFLICT(scope, client_id) DO UPDATE SET expires_at = excluded.expires_at`;
+/** The D4 lazy sweep, in the SAME txn as the upsert: age out THIS scope's long-expired rows.
+ *  Param 2 is `now − (graceMs + SESSION_SWEEP_SLACK_MS)` — never tighter (the linger contract). */
+const SESSION_SWEEP_SQL = `DELETE FROM ${SCOPE_SESSIONS_TABLE} WHERE scope = ? AND expires_at < ?`;
+/** The occupancy read, one SELECT: cell 0 = DISTINCT unexpired sessions (`expires_at > now`;
+ *  distinct by construction — `(scope, client_id)` is the PK), cell 1 = sessions expired WITHIN
+ *  the grace window (`now − graceMs < expires_at ≤ now`) — the upward hysteresis input, cell 2 =
+ *  ALL matching rows regardless of expiry (the I-v "room plausibly exists" signal: a scope with
+ *  ANY other-session row — live OR still lingering pre-sweep — was shared, so a room was
+ *  provisioned; a never-shared solo doc has none and must never drain). Params:
+ *  `[now, now, now − graceMs, scope]`. */
+const SESSION_COUNT_SQL = `SELECT SUM(CASE WHEN expires_at > ? THEN 1 ELSE 0 END), ` +
+    `SUM(CASE WHEN expires_at <= ? AND expires_at > ? THEN 1 ELSE 0 END), ` +
+    `COUNT(*) ` +
+    `FROM ${SCOPE_SESSIONS_TABLE} WHERE scope = ?`;
+/** {@link SESSION_COUNT_SQL} excluding the CALLER's own row (D6 counts *other* sessions; the
+ *  caller contributes itself as the `+ 1`). One extra trailing param: the caller's clientId. */
+const SESSION_COUNT_OTHERS_SQL = `${SESSION_COUNT_SQL} AND client_id <> ?`;
+/** `col = <string literal>` — the only predicate shape the lifecycle ASTs need. */
+function colEq(name, value) {
+    return { type: "simple", op: "=", left: { type: "column", name }, right: { type: "literal", value } };
+}
+/** The doorbell AST (§4.1): every unexpired row under the scope is one live session; the row
+ *  delta arriving through a solo client's daemon subscription IS the 1→2 upgrade signal. The
+ *  expiry filter is deliberately NOT in the predicate — `expires_at > now()` would freeze `now`
+ *  at mint time; liveness is the READER's judgment (I-iv), the stream just carries the rows. */
+function scopeSessionsAst(scope) {
+    return { table: SCOPE_SESSIONS_TABLE, where: colEq("scope", scope) };
+}
+/** The §4.2 fence AST: the doc's monotone `flush_seq` row. */
+function roomWatermarkAst(doc) {
+    return { table: ROOM_WATERMARK_TABLE, where: colEq("doc", doc) };
+}
+/** The §7.1 ledger / §3.3 outcome ASTs share one shape: doc-scoped, and ADDITIONALLY
+ *  client-scoped when the lease request carried the browser's stable `clientId` (the same id the
+ *  mutation envelopes stamp, so it is exactly the ledger/outcome `client_id`). Without it the
+ *  predicate stays doc-only and the client filters to its own rows (defense in depth either
+ *  way — the client always filters). */
+function docClientAst(table, doc, clientId) {
+    const docCond = colEq("doc", doc);
+    return {
+        table,
+        where: clientId === undefined ? docCond : { type: "and", conditions: [docCond, colEq("client_id", clientId)] },
+    };
+}
+// --------------------------------------------------------- room-serve helpers (G-iv-b)
+/** Default room lease token TTL: short (minutes) per RINDLE-REALTIME §4.1 — renewal is a fresh
+ *  lease through the api-server, never an extension of this token. */
+const DEFAULT_ROOM_TOKEN_TTL_MS = 5 * 60_000;
+/** Deterministic JSON: object keys sorted recursively, so two structurally identical ASTs from
+ *  independent resolves stringify identically (the verdict-cache key). */
+function stableStringify(v) {
+    return JSON.stringify(v, (_key, value) => {
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            const rec = value;
+            const sorted = {};
+            for (const k of Object.keys(rec).sort())
+                sorted[k] = rec[k];
+            return sorted;
+        }
+        return value;
+    });
+}
+/** Does the AST contain an aggregate/reduce shape ANYWHERE (root, a `related` subquery, or an
+ *  `EXISTS` child)? Room-serving refuses these regardless of coverage: the client's aggregate
+ *  overlay (AGGREGATE-SYNC) is computed against the DAEMON's normalized stream and stays
+ *  daemon-gated until post-G. (`groupBy`/`having` only occur alongside `aggregate`, so testing
+ *  `aggregate` covers them; `having` is still walked for nested EXISTS aggregates.) */
+function astHasAggregate(ast) {
+    if (ast.aggregate !== undefined)
+        return true;
+    for (const rel of ast.related ?? []) {
+        if (astHasAggregate(rel.subquery))
+            return true;
+    }
+    return conditionHasAggregate(ast.where) || conditionHasAggregate(ast.having);
+}
+function conditionHasAggregate(cond) {
+    if (cond === undefined)
+        return false;
+    switch (cond.type) {
+        case "simple":
+            return false;
+        case "and":
+        case "or":
+            return cond.conditions.some(conditionHasAggregate);
+        case "correlatedSubquery":
+            return astHasAggregate(cond.related.subquery);
+    }
+}
 async function reject(backend, envelope, reason) {
     const output = await backend.reject({ envelope, reason });
     return { accepted: false, rejected: true, reason, output };
 }
+/** The single place a {@link MutationOutcome} becomes the wire {@link PushMutationResponse} — shared
+ *  by the tx-form path and every scoped-mutator seal branch so the accepted/rejected shape can never
+ *  drift between them. */
+function outcomeToResponse(outcome) {
+    return outcome.accepted
+        ? { accepted: true, rejected: false, output: outcome.output }
+        : { accepted: false, rejected: true, reason: outcome.reason, output: outcome.output };
+}
 function parseObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new RindleApiError("bad-request", `invalid ${label}`, 400);