@rindle/api-server 0.4.4 → 0.6.3

package/src/index.ts

@@ -1,4 +1,4 @@
-import { driveMutationAsync, insertCell, insertPlan, isoTx, toCell } from "@rindle/client";
+import { driveMutationAsync, insertCell, insertPlan, isGeneratorMutator, isoTx, toCell } from "@rindle/client";
 import type {
   Ast,
   ColType,
@@ -21,6 +21,8 @@ import type { Catalog, ColumnType as QueryColumnType, TableSchema } from "@rindl
 import type {
   ClaimRoomEpochInput,
   ClaimRoomEpochOutput,
+  CoverQueryInput,
+  CoverQueryOutput,
   DematerializeInput,
   DematerializeOutput,
   MaterializationPolicy,
@@ -51,12 +53,52 @@ import type {
   WireValue,
 } from "@rindle/daemon-client";
 
+import {
+  assertLabeledProfilesExist,
+  assertUnwindowedFootprint,
+  attachRealtimeLabel,
+  compileRoomProfiles,
+  compileRoomScopeSpecs,
+  compileRoomTableSpecs,
+  mintRoomDoc,
+  queryRealtimeLabel,
+  queryResultToAst,
+  splitRoomDoc,
+} from "./rooms.ts";
+import type { RoomProfile, RoomScopeSpec, RoomTableSpec } from "./rooms.ts";
+// The room lease token (RINDLE-REALTIME §10.1): minted here, verified by the room SHELL against
+// its `downstream.tokenKeys` ring — the `/token` subpath is pure WebCrypto (no wasm, no shell).
+// Loaded LAZILY at the first mint: `@rindle/room` is an OPTIONAL dependency (see package.json), so
+// it is installed transitively — a consumer bundling api-server (Vite/Rollup/esbuild) can resolve
+// this dynamic import even when it never uses rooms — yet the mint only runs when
+// `realtime.roomTokenKey` is configured. Should the module be genuinely absent (an install that
+// skipped the optional dep), the serve decision fail-opens: daemon-served leases plus a one-time
+// warning naming the missing module. It is NOT a hard `dependency` because the entire code path is
+// optional; optionalDependencies keeps a failed install of it non-fatal.
+import type { mintRoomToken as MintRoomToken, scopeSpecsHash as ScopeSpecsHash } from "@rindle/room/token";
+let roomTokenModule: { mintRoomToken: typeof MintRoomToken; scopeSpecsHash: typeof ScopeSpecsHash } | undefined;
+async function loadRoomTokenModule(): Promise<{ mintRoomToken: typeof MintRoomToken; scopeSpecsHash: typeof ScopeSpecsHash }> {
+  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";
 export type { ArgSchema, IsoTx, MutationGen, MutatorCtx, SharedMutator, SharedMutatorWithArgs } 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.ts";
+export type { RoomProfile, RoomScopeSpec, RoomTableSpec } from "./rooms.ts";
+export type { RealtimeQueryLabel } from "@rindle/client";
+
 export const DEFAULT_RINDLE_API_ROUTES = {
   query: "/api/rindle/query",
   read: "/api/rindle/read",
@@ -149,6 +191,103 @@ export type ApiMutator<User, Args> = (
   args: Args,
   ctx: MutationContext<User>,
 ) => MaybePromise<ApiMutatorResult>;
+
+// --------------------------------------------------------------------------- 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 {
+  readonly reason: string;
+  constructor(reason: string) {
+    super(reason);
+    this.name = "MutationRejected";
+    this.reason = reason;
+  }
+}
+
+/** The per-mutation server handle a {@link ScopedMutator} runs against. Code before {@link transact}
+ *  runs OUTSIDE the transaction; code after a clean `transact` runs AFTER the commit. The
+ *  `lmid`-always-advances invariant is the HARNESS's, not the author's: {@link RindleApiServer.pushMutation}
+ *  seals the response from this handle's recorded outcome, so an early return, a never-called
+ *  `transact`, or a swallowed {@link MutationRejected} still advances `lmid` and never wedges the
+ *  client's pending queue. */
+export interface MutationScope {
+  /** Open the ONE atomic write transaction and drive `body` inside it, committing (stamping `lmid`
+   *  co-transactionally) on a clean return. MAY be called at most once — a second call throws.
+   *
+   *  Two forms:
+   *   - `transact(sharedMutator, args, ctx)` — drive a SHARED (generator) mutator (the same body the
+   *     client predicts); pass the already-parsed `args` and the server `ctx` (fold server-only
+   *     values like a charge id into `ctx` here).
+   *   - `transact(run)` — a raw callback receiving the live {@link ServerMutationTx} (the escape
+   *     hatch: `tx.exec`, logical writes, read-your-writes reads).
+   *
+   *  A THROW from the body that is not a {@link BackendError} is a BUSINESS rejection: the data rolls
+   *  back, `lmid` advances alone, and this method throws {@link MutationRejected} (so surrounding
+   *  code can compensate). A {@link BackendError} is INFRA: it propagates (the client retries). */
+  transact(run: (tx: ServerMutationTx) => void | Promise<void>): Promise<void>;
+  transact<A, C extends MutatorCtx>(mutator: SharedMutator<A, C>, args: A, ctx: C): Promise<void>;
+}
+
+/** A SCOPED server mutator (WORK-OUTSIDE-TX): server-only code, ONE `scope.transact`, optional
+ *  post-commit code. Register it by wrapping in {@link scoped} — the tag the api-server routes on to
+ *  hand it a {@link MutationScope} instead of running its whole body inside the transaction. */
+export type ScopedMutator<User, Args> = (
+  scope: MutationScope,
+  args: Args,
+  ctx: MutationContext<User>,
+) => void | Promise<void>;
+
+/** A {@link ScopedMutator} tagged by {@link scoped} so the harness invokes it with a
+ *  {@link MutationScope}. Typed as a BRANDED tx-form {@link ApiMutator} purely so it registers in the
+ *  `mutators` record without widening it to a union (which would break contextual inference for every
+ *  plain tx-form entry). Its true runtime shape is `(scope, args, ctx)`; the tag — not the type —
+ *  routes it, and it is never actually called as a tx-form mutator. */
+export type ScopedApiMutator<User, Args> = ApiMutator<User, Args> & { readonly __rindleScoped: true };
+
+/** 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<User, Args>(fn: ScopedMutator<User, Args>): ScopedApiMutator<User, Args> {
+  // 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 as const }) as unknown as ScopedApiMutator<User, Args>;
+}
+
+function isScoped<User>(m: ApiMutator<User, any>): m is ScopedApiMutator<User, any> {
+  return (m as { __rindleScoped?: boolean }).__rindleScoped === true;
+}
+
 export type ApiMutators<User> = Record<string, ApiMutator<User, any>>;
 
 export interface QueryLeaseRequest<User> {
@@ -160,6 +299,96 @@ export interface QueryLeaseRequest<User> {
    *  when there is no authenticated subject and no session cookie (READ-ROUTER-DESIGN.md §1.5/§2.2).
    *  A routing HINT only, never authorization. */
   clientId?: string;
+  /** The browser's opaque follower-affinity ticket (FOLLOWER-AFFINITY-DESIGN.md §3), read off the
+   *  query POST and forwarded OPAQUELY on `materialize` so the fleet `fly-replay`s to the follower
+   *  the browser's ws is pinned to (§2, §4) — both legs co-locate. The api-server does NOT verify
+   *  it (the fleet does); it holds no signing key. Absent ⇒ single daemon / affinity off. */
+  affinity?: string;
+}
+
+/**
+ * The room-serve block on a query lease (RINDLE-REALTIME-QUERY-ENABLEMENT §2.1 step 5 / §2.4,
+ * slice G-iv-b): present only when the named query carries a realtime label AND its resolved AST
+ * was PROVABLY covered by its room profile's footprint (the daemon's `/cover-check`). The G-v
+ * client uses it to open the room transport for THIS query beside — never instead of — its daemon
+ * session.
+ *
+ * It is a dedicated block on purpose: the ROOM ws is a SEPARATE connection this query opens beside
+ * its daemon session (never a migration of the daemon session — the daemon ws host is fixed and
+ * placed by the affinity ticket). A room-served lease's top-level fields are byte-identical to the
+ * daemon-served ones.
+ */
+export interface QueryLeaseRealtime {
+  /** The client store's gate/domain key for this room source (`connectSource`) AND the string the
+   *  wasm engine's `parse_source_key` accepts: any string other than the reserved `"daemon"`
+   *  parses as a room source, and the established convention is `"room:" + doc`
+   *  (e.g. `room:document/doc:d1`). */
+  sourceKey: string;
+  /** Where the client opens the ROOM ws for this query (from `realtime.locateRoom`) — its OWN
+   *  connection, distinct from the daemon session's fixed ws host. */
+  wsEndpoint: string;
+  /** The room's self-authorizing signed lease (`@rindle/room/token`): the APPROVED query AST +
+   *  doc + subject, HMAC-signed with `realtime.roomTokenKey` so the room shell's
+   *  `downstream.tokenKeys` ring verifies it. The room materializes on first presentation. */
+  roomToken: string;
+  /** Token expiry (ms epoch) — the client's renewal clock (renewal = a fresh lease). */
+  exp: number;
+  /** The wire room doc (`"<profile>/<key>"`, minted server-side — never client-derived). */
+  doc: string;
+  /** Per-footprint-table specs: the §2.2 owned/followed split + §3.2 routing metadata. Since
+   *  H-iii each spec also carries `footprintWhere` — the same exact membership predicate the boot
+   *  wire ships the room gate (one compiler, `compileRoomScopeSpecs`) — feeding the client's §3
+   *  prove-or-slow-path router. Advisory routing metadata, never a credential (§3.2). */
+  tables: RoomTableSpec[];
+}
+
+/**
+ * One minted SYSTEM-STREAM lease on a query lease's `lifecycle` block (RINDLE-REALTIME-QUERY-
+ * ENABLEMENT §4, Slice I-iii): an ordinary daemon materialization over one of the four
+ * `_rindle_*` lifecycle system tables (registered by the daemon's `enable_realtime_lifecycle` —
+ * `rust/rindle-replica/src/mutations.rs`), attachable by the EXISTING client subscribe path
+ * (present `leaseToken` on a `subscribe` frame, exactly like the primary lease). The identity
+ * fields (`scope`/`doc`/`clientId`) document the minted AST's predicate — the client keys its
+ * retains and its release-time row filters on them.
+ */
+export interface QueryLeaseLifecycleLease {
+  /** Which system table this lease's subscription serves. */
+  table: string;
+  leaseToken: string;
+  /** DOORBELL only: the §4.1 occupancy scope — the wire room doc (`"<profile>/<key>"`). */
+  scope?: string;
+  /** FENCE entries only: the room doc the predicate is scoped to. */
+  doc?: string;
+  /** FENCE ledger/outcome entries: present iff the predicate was ALSO client-scoped (the lease
+   *  request carried `clientId`). Absent ⇒ doc-only predicate — the client filters to its own
+   *  rows regardless (defense in depth). */
+  clientId?: string;
+}
+
+/** The §4 lifecycle block on a query lease (Slice I-iii): present only when BOTH the realtime
+ *  `lifecycle` config is on AND the query is realtime-labeled. `doorbell` rides EVERY labeled
+ *  lease (occupancy is counted whether or not the query is room-served — the 1→2 upgrade trigger
+ *  needs solo watchers subscribed BEFORE any room exists, §4.1); `fence` rides only a ROOM-SERVED
+ *  lease (the §4.2/§7.1/§3.3 downgrade surfaces are meaningful only where a room domain exists).
+ *  The §4.2 fence VALUE (`finalFlushSeq`) is deliberately NOT here — it arrives with the I-v
+ *  downgrade response; I-iii only stands up the streams. */
+export interface QueryLeaseLifecycle {
+  doorbell: QueryLeaseLifecycleLease;
+  fence?: QueryLeaseLifecycleLease[];
+}
+
+/** The §4.2 downgrade fence on a query lease (Slice I-v): rides a labeled reply whose §4.1
+ *  occupancy gate CLOSED (so there is NO `realtime` block) when the server could drain the room.
+ *  A SIBLING of `realtime`, never nested inside it — block-ABSENCE is the downgrade signal, and
+ *  the fence rides alongside that absence. Its `finalFlushSeq` is the room's last COMMITTED flush
+ *  seq; the client's frozen room ghost holds visible until the daemon plane has provably absorbed
+ *  it (`_rindle_room_watermark(doc) ≥ finalFlushSeq`). Absent from every non-downgrade reply. */
+export interface QueryLeaseRealtimeFence {
+  /** The retiring room source's gate/domain key — `"room:" + doc`, matching what the room-served
+   *  lease's {@link QueryLeaseRealtime.sourceKey} carried. */
+  sourceKey: string;
+  doc: string;
+  finalFlushSeq: number;
 }
 
 export interface QueryLeaseResponse {
@@ -167,9 +396,17 @@ export interface QueryLeaseResponse {
   materializationId: string;
   queryKey?: string;
   reused?: boolean;
-  /** The follower this lease lives on (READ-ROUTER-DESIGN.md §2.3) — the browser opens its
-   *  subscription ws here. Absent ⇒ single-daemon (the client uses its static `wsUrl`). */
-  wsEndpoint?: string;
+  /** The room-serve block (G-iv-b) — see {@link QueryLeaseRealtime}. Absent ⇒ the lease is
+   *  byte-identical to the legacy daemon-served shape. */
+  realtime?: QueryLeaseRealtime;
+  /** The §4.2 downgrade fence (Slice I-v) — see {@link QueryLeaseRealtimeFence}. Present only on a
+   *  labeled reply whose occupancy gate closed AND `realtime.lifecycle.drainRoom` could drain the
+   *  room; absent otherwise (including on every room-served reply). */
+  realtimeFence?: QueryLeaseRealtimeFence;
+  /** The §4 lifecycle system-stream block (Slice I-iii) — see {@link QueryLeaseLifecycle}.
+   *  Minted ONLY under the opt-in `realtime.lifecycle` config; absent ⇒ byte-identical to the
+   *  pre-lifecycle response. */
+  lifecycle?: QueryLeaseLifecycle;
 }
 
 /** A one-shot SSR read of a named query (SSR-DESIGN.md §6): same `(name, args)` surface as a lease,
@@ -183,6 +420,9 @@ export interface QueryReadRequest<User> {
    *  {@link QueryLeaseRequest.clientId}). Lets the SSR read co-locate on the follower the booting
    *  client's first subscribe will hit (READ-ROUTER-DESIGN.md §2.4). */
   clientId?: string;
+  /** The browser's opaque follower-affinity ticket — see {@link QueryLeaseRequest.affinity}.
+   *  Forwarded on the one-shot `query` so an SSR read lands on the same pinned follower. */
+  affinity?: string;
 }
 
 /** The assembled (nested-by-name) first-paint snapshot the server-side Store seeds + dehydrates
@@ -191,9 +431,6 @@ export interface QueryReadResponse {
   rows: Array<{ cols: Record<string, unknown>; [rel: string]: unknown }>;
   cvMin?: number;
   queryKey?: string;
-  /** The follower this read warmed (READ-ROUTER-DESIGN.md §2.4) — inject it into the SSR bootstrap
-   *  so the booting client opens its ws to the same warm follower. Absent ⇒ single-daemon. */
-  wsEndpoint?: string;
 }
 
 /** The context a {@link MutationBackend} needs to run one mutation inside its transaction. */
@@ -311,6 +548,16 @@ export interface RoomBootResponse {
   /** Where the room opens its upstream subscription (a routed deploy's follower). Absent ⇒ the
    *  shell's statically configured rindled ws endpoint. */
   upstreamWsEndpoint?: string;
+  /** Fresh opaque follower-placement ticket minted alongside `upstreamLeaseToken`. The DO offers
+   *  it with `rindle.v1` on the separate upstream ws so a static fleet endpoint replays to the
+   *  exact follower holding that local lease. Absent when daemon affinity is off. */
+  upstreamAffinity?: string;
+  /** Per-footprint-table scope specs (H-iv-b), compiled from the resolved footprint AST + the
+   *  profile's context set (the legacy anonymous profile compiles with an empty context set):
+   *  what the shell hands the wasm room's `enableWritesV2` — the §3.3 commit gate. Optional
+   *  only for wire compatibility with pre-H-iv-b servers; a shell that doesn't receive them
+   *  enables the v1 table-granular write plane exactly as before. */
+  scopes?: RoomScopeSpec[];
   flush: RoomBootFlush;
 }
 
@@ -319,11 +566,22 @@ export interface RindleRealtimeOptions<User> {
    *  room's `Authorization: Bearer` on `/room-boot` (the default {@link authorizeBoot}) and keys
    *  the DEFAULT epoch-bound flush credential. */
   shellSecret: string;
+  /** NAMED room profiles (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §2.1): profile name → key
+   *  derivation + canonical unwindowed footprint + read-only context tables. The wire room key
+   *  for a named profile is `"<profile>/<key>"`; `/room-boot` splits it and resolves the
+   *  profile's footprint with the bare key. Compiled + validated LOUDLY at construction (§2.3):
+   *  a windowed footprint, a context table missing from the schema/footprint, or a registered
+   *  query whose realtime label names a missing profile all throw from `createRindleApiServer`. */
+  rooms?: Record<string, RoomProfile<User>>;
   /** doc → the room's approved upstream footprint (§3.1) — an `Ast` or fluent `Query`. MAY
    *  delegate to the named-query registry internally; throw `RindleApiError("not-found", …, 404)`
    *  for a doc that shouldn't exist. The §9 footprint budget belongs here — it runs once per
-   *  placement, at lease mint. */
-  resolveFootprint: (doc: string, ctx: ApiContext<User>) => MaybePromise<ApiQueryResult>;
+   *  placement, at lease mint.
+   *  @deprecated Prefer named {@link rooms} profiles (RINDLE-REALTIME-QUERY-ENABLEMENT §2.1).
+   *  This bare form remains as the single-profile LEGACY alias — the anonymous/default profile:
+   *  a doc with no known `"<profile>/"` prefix resolves here, byte-identically to before named
+   *  profiles existed (and with none of their construction/boot-time validation). */
+  resolveFootprint?: (doc: string, ctx: ApiContext<User>) => MaybePromise<ApiQueryResult>;
   /** Gates the flush trio — `authorizeRoom`, relocated. Default: verify the default flush
    *  credential from the {@link ROOM_FLUSH_CREDENTIAL_HEADER} request header — which requires the
    *  transport to pass its incoming request as `context.request` (Fetch `Request` and node
@@ -339,9 +597,77 @@ export interface RindleRealtimeOptions<User> {
   /** Lease TTL for the room's upstream footprint materialization (defaults to the server-wide
    *  `leaseTtlMs`, else the daemon's default). */
   upstreamLeaseTtlMs?: number;
-  /** Static override for where rooms open their upstream subscription; default is the
-   *  `wsEndpoint` the materialize returns (set in routed deploys), else absent. */
+  /** Static endpoint where rooms open their upstream subscription. In a follower fleet this is the
+   *  fleet ws URL; `/room-boot` pairs it with the materialization's fresh placement ticket so the
+   *  room lands on the exact follower holding its lease. Absent ⇒ no explicit upstream (the Node
+   *  room shell may use its own default; the shipped DO shell requires this endpoint). */
   upstreamWsEndpoint?: string;
+  /** Locate (or place) the room serving `doc` and return the ROOM ws endpoint a room-served
+   *  lease's client should open (G-iv-b; on the DO shell this is the Worker's room URL). The
+   *  endpoint rides the lease's dedicated `realtime.wsEndpoint` — its OWN connection, distinct from
+   *  the daemon session's fixed ws host. Absent ⇒ room-serving is OFF: labeled queries serve from
+   *  the daemon exactly as today (fail-open). */
+  locateRoom?: (doc: string) => MaybePromise<{ wsEndpoint: string }>;
+  /** The room lease token signing key (`@rindle/room/token`): `kid` + secret, matching an entry
+   *  in the room shell's `downstream.tokenKeys` ring. Required for room-serving (without it a
+   *  labeled query fail-opens to the daemon with a one-time warning). A separate secret from
+   *  `shellSecret` on purpose — the shell's ring is the client-token trust domain, the shell
+   *  secret is the boot/flush trust domain. */
+  roomTokenKey?: { kid: string; secret: string };
+  /** Room lease token TTL, ms (default 5 minutes — the §4.1 short-TTL backstop; renewal is a
+   *  fresh lease through this server, never an extension). */
+  roomTokenTtlMs?: number;
+  /** Loud-diagnostics sink for the realtime layer (profile compilation warnings + the one-time
+   *  per-(query, profile) "not room-served" serve-decision warnings). Defaults to
+   *  `console.warn`; injectable for tests. */
+  warn?: (message: string) => void;
+  /** The §4 upgrade/downgrade lifecycle plane (RINDLE-REALTIME-QUERY-ENABLEMENT §4, Slice
+   *  I-iii): PRESENCE of this block is the opt-in — every realtime-labeled lease then
+   *  additionally mints the doorbell system lease (occupancy, §4.1) and every ROOM-SERVED lease
+   *  the fence bundle (watermark + ledger + outcomes, §4.2/§7.1/§3.3) — see
+   *  {@link QueryLeaseLifecycle}. Requires the daemon to have run `enable_realtime_lifecycle`
+   *  (the four `_rindle_*` system tables must be registered or the minted materializations fail
+   *  — which fail-opens with a one-time warning, never blocking the lease). Absent ⇒ the lease
+   *  response is byte-identical to pre-lifecycle. */
+  lifecycle?: RindleRealtimeLifecycleOptions;
+}
+
+/** {@link RindleRealtimeOptions.lifecycle}. PRESENCE of the block is the opt-in switch (I-iii);
+ *  the fields below are the Slice I-iv occupancy knobs (§4.1, decisions D4/D6/D7). All optional —
+ *  `lifecycle: {}` gets the designed defaults. */
+export interface RindleRealtimeLifecycleOptions {
+  /** D6 (§4.1): the occupancy threshold for room-serving. A labeled lease whose scope counts
+   *  FEWER than this many distinct unexpired sessions (the caller's own included) ships WITHOUT
+   *  the realtime block — served from the daemon, indistinguishable from an uncovered query —
+   *  but WITH the doorbell, so the 1→2 transition wakes it (that is the point: solo docs never
+   *  cost room infrastructure). Default **2** (the design's 1→2 trigger). Set `1` to room-serve
+   *  solo viewers (the pre-I-iv behavior under lifecycle config). */
+  minSessions?: number;
+  /** The §9.1 hysteresis window, ms (default **120_000**). Two consumers: (a) the lazy sweep
+   *  (D4) keeps expired session rows lingering at least this long past expiry — Slice I-v's
+   *  downgrade decision ("no other unexpired row AND the newest other row expired > graceMs
+   *  ago") is read FROM those rows, so they must survive to be read; (b) this slice's gate
+   *  applies the same hysteresis upward: a scope with an other-session row expired ≤ graceMs
+   *  ago keeps room-serving through the window (see `lifecycleOccupancy` — no flap on one
+   *  client's brief lapse). §9.1-tunable: raise it for docs where collaborators churn slowly. */
+  graceMs?: number;
+  /** TTL of an occupancy session row, ms — `expires_at = now + sessionTtlMs` on every labeled
+   *  lease mint/renewal (D7: session identity = the request's `clientId`; two tabs are two
+   *  sessions iff their clientIds differ). Default = the server's `leaseTtlMs`, else 5 minutes —
+   *  matching the room-token renewal cadence (`roomTokenTtlMs`, renewed 30s early), so a
+   *  room-attached client's renewals keep its row unexpired; a daemon-attached solo client's row
+   *  MAY lapse (it has no renewal timer) and is refreshed by its next doorbell-triggered
+   *  re-lease — occupancy converges through the doorbell itself. */
+  sessionTtlMs?: number;
+  /** The §4.2 downgrade drain hook (Slice I-v). When the occupancy gate CLOSES for a labeled
+   *  lease whose scope PLAUSIBLY hosted a room (an other-session row still lingers — never a
+   *  never-shared solo doc), the api-server calls this to drain the room's pending write-behind
+   *  and learn its last COMMITTED `flush_seq`, then rides the value back on the lease as the
+   *  {@link QueryLeaseRealtimeFence}. The deployment wires it to the room shell's / DO's `/drain`
+   *  control. Absent ⇒ no fence is attached (the client hits its loud legacy downgrade path);
+   *  a throw fails OPEN to the same (a downgrade never blocks the lease). Concurrent drains across
+   *  api-server instances are fine — `/drain` is idempotent. */
+  drainRoom?: (doc: string) => Promise<{ finalFlushSeq: number }>;
 }
 
 // The DEFAULT flush credential: `rfc1.<b64url payload>.<b64url hmac-sha256>`, payload
@@ -496,12 +822,11 @@ export interface RindleApiServerOptions<User> {
    *  HINT only — never authorization. Ignored by a single (unrouted) daemon, which has nothing to
    *  route. */
   routingKey?: string | ((input: QueryLeaseRequest<User>) => MaybePromise<string | undefined>);
-  /** The EXPLICIT fleet pin fan-out (READ-ROUTER-DESIGN.md §4.2 "push") — when set,
-   *  {@link RindleApiServer.assertPins} fans each resolved pin across ALL live followers through it
-   *  (e.g. `createRouterPinClient` from `@rindle/router`) instead of materializing each pin once on
-   *  the (single) daemon. A per-viewer `materialize` always routes ONE; a pin-assert always fans
-   *  ALL — never inferred from `policy.kind`. Absent ⇒ single-daemon behavior (one materialize per
-   *  pin). */
+  /** The EXPLICIT fleet pin fan-out — when set, {@link RindleApiServer.assertPins} fans each
+   *  resolved pin across ALL live followers through it (a fleet control action over the machine
+   *  list — FOLLOWER-AFFINITY-DESIGN.md §11) instead of materializing each pin once on the (single)
+   *  daemon. A per-viewer `materialize` always routes ONE; a pin-assert always fans ALL — never
+   *  inferred from `policy.kind`. Absent ⇒ single-daemon behavior (one materialize per pin). */
   pinFanout?: PinFanout;
   /** Named queries to keep permanently materialized via {@link RindleApiServer.assertPins}.
    *  Each is materialized with a `pinned` policy (survives zero subscribers) so late joiners
@@ -510,6 +835,12 @@ export interface RindleApiServerOptions<User> {
   /** The user context pins resolve under (pins are shared, so they should not depend on a
    *  per-viewer identity). Defaults to `undefined`. */
   pinUser?: User;
+  /** Surfaced when a SCOPED mutator ({@link scoped}) throws from code that runs AFTER `scope.transact`
+   *  has already sealed the protocol outcome — a post-commit effect, or a compensation handler running
+   *  after a business rejection. The outcome is fixed (this callback CANNOT change the client's
+   *  response or the `lmid` advance), but the throw must not vanish: a failed refund is real money.
+   *  Absent ⇒ the error is logged to `console.error`. */
+  onScopeError?: (err: unknown, info: { phase: "committed" | "rejected"; envelope: MutationEnvelope }) => void;
 }
 
 export interface RindleApiServer<User> {
@@ -520,6 +851,18 @@ export interface RindleApiServer<User> {
    *  startup and whenever the daemon restarts (e.g. from the daemon-client `onBootId` hook), since
    *  the daemon holds no durable materialization state. No-op when `pinnedQueries` is empty. */
   assertPins(): Promise<void>;
+  /** The room-serving coverage DIAGNOSTIC (G-iv-b; the `assertPins`-style explicit check): for
+   *  every realtime-labeled query, resolve it (under `pinUser`, per exemplar args), resolve its
+   *  profile's footprint, and run the REAL daemon coverage check — the same verdict the lease
+   *  path serves by. Returns every verdict; `strict` throws when any labeled query is not
+   *  provably covered (deploy-gate mode). Deliberately ignores `locateRoom`/`roomTokenKey` — it
+   *  answers "would this query be coverable", not "is serving fully wired". */
+  validateRealtime(opts?: {
+    /** Per-query exemplar args (a query is checked once per exemplar; default: one `null`). */
+    exemplars?: Partial<Record<string, readonly unknown[]>>;
+    /** Throw when any labeled query is uncovered (instead of just reporting). */
+    strict?: boolean;
+  }): Promise<ValidateRealtimeReport>;
   pushMutation(input: PushMutationRequest<User>): Promise<PushMutationResponse>;
   /** Apply an in-order batch (the client mutation queue's flush). Envelopes run strictly
    *  sequentially; a rejection still advances the daemon's lmid, so later envelopes in the
@@ -558,6 +901,24 @@ export interface RindleApiServer<User> {
   handleRoomBootJson(body: unknown, context: ApiContext<User>): Promise<RoomHostResponse>;
 }
 
+/** One {@link RindleApiServer.validateRealtime} verdict: a labeled query × exemplar args. */
+export interface ValidateRealtimeVerdict {
+  query: string;
+  profile: string;
+  args: unknown;
+  covered: boolean;
+  /** Why it is not covered (uncovered verdicts only) — the daemon's reason strings, the
+   *  aggregate refusal, or a resolve/footprint error message. */
+  reasons?: string[];
+}
+
+/** The {@link RindleApiServer.validateRealtime} report. */
+export interface ValidateRealtimeReport {
+  verdicts: ValidateRealtimeVerdict[];
+  /** The uncovered subset of `verdicts` (what `strict` throws on). */
+  uncovered: ValidateRealtimeVerdict[];
+}
+
 export type RindleApiErrorCode = "bad-request" | "forbidden" | "not-found" | "rejected";
 
 export class RindleApiError extends Error {
@@ -652,11 +1013,18 @@ export class SplitDaemonClient implements RindleDaemonClient {
     if (!lmids) 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: CoverQueryInput): Promise<CoverQueryOutput> {
+    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: MigrateInput): Promise<MigrateOutput> {
     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: MaterializeInput): Promise<MaterializeOutput> {
     return this.reads.materialize(input);
   }
@@ -885,6 +1253,24 @@ class AbsorbedReplay extends Error {
   }
 }
 
+const MUTATOR_CONFLICT_MAX_ATTEMPTS = 5;
+
+function isRetryableCommitConflict(error: unknown): boolean {
+  if (!(error instanceof DaemonHttpError) || error.status !== 409) return false;
+  try {
+    const body = JSON.parse(error.body) as { code?: unknown; retryable?: unknown };
+    return body.code === "retryable-conflict" && body.retryable === true;
+  } catch {
+    return false;
+  }
+}
+
+async function mutatorConflictBackoff(attempt: number): Promise<void> {
+  const ceiling = Math.min(32, 2 ** attempt);
+  const millis = ceiling + Math.floor(Math.random() * 4);
+  await new Promise<void>((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
@@ -1156,37 +1542,48 @@ class PgLiveTx implements ServerMutationTx {
 export function daemonBackend(daemon: RindleDaemonClient): MutationBackend {
   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() };
-        } catch (err) {
-          if (err instanceof BackendError) throw err.driverError; // infra (client retries; dedup absorbs)
-          throw err;
+          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: SqlTxn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
+          if (tx.idempotencyKey !== undefined) txn.idempotencyKey = tx.idempotencyKey;
+          return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+        } catch (error) {
+          if (!isRetryableCommitConflict(error) || attempt + 1 === MUTATOR_CONFLICT_MAX_ATTEMPTS) {
+            throw error;
+          }
+          await mutatorConflictBackoff(attempt);
         }
       }
-      const txn: SqlTxn = { statements: [...tx.statements], clientID: envelope.clientID, mid: envelope.mid };
-      if (tx.idempotencyKey !== undefined) txn.idempotencyKey = tx.idempotencyKey;
-      return { accepted: true, output: await daemon.executeSqlTxn(txn) };
+      throw new Error("unreachable mutator conflict retry loop");
     },
     reject({ envelope, reason }) {
       return daemon.rejectMutation({ clientID: envelope.clientID, mid: envelope.mid, reason });
@@ -1390,7 +1787,11 @@ export function registerQueries<User>(queries: readonly NamedQuery<any, any, any
     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: ApiQuery<User, any> = (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;
 }
@@ -1431,11 +1832,47 @@ export function sharedApiMutators<User>(
   return out;
 }
 
-export function queryResultToAst(result: ApiQueryResult): Ast {
-  if (result && typeof result === "object" && "ast" in result && typeof result.ast === "function") {
-    return result.ast();
-  }
-  return result as Ast;
+/**
+ * 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<User, Args>(
+  gen: SharedMutatorWithArgs<Args>,
+  principal: (ctx: MutationContext<User>) => MutatorCtx,
+  predicate: (tx: ServerMutationTx, args: Args, ctx: MutatorCtx) => boolean | void | Promise<boolean | void>,
+  opts?: { message?: string },
+): ApiMutator<User, unknown> {
+  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);
+  };
 }
 
 /** One exemplar invocation for {@link dumpQueryShapes} — the `args`/`user` a query is built with.
@@ -1536,6 +1973,88 @@ function normalizeCondition(c: Condition): unknown {
   }
 }
 
+/**
+ * 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 implements MutationScope {
+  private attempted = false;
+  private readonly backend: MutationBackend;
+  private readonly envelope: MutationEnvelope;
+  private readonly render: RenderIndex;
+  /** Set once `transact` resolved through the backend (accepted OR business-rejected). */
+  outcome?: MutationOutcome;
+  /** 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?: unknown;
+  /** 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?: Promise<void>;
+
+  constructor(backend: MutationBackend, envelope: MutationEnvelope, render: RenderIndex) {
+    this.backend = backend;
+    this.envelope = envelope;
+    this.render = render;
+  }
+
+  transact(
+    first: SharedMutator<any, any> | ((tx: ServerMutationTx) => void | Promise<void>),
+    args?: unknown,
+    ctx?: MutatorCtx,
+  ): Promise<void> {
+    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;
+  }
+
+  private async drive(
+    first: SharedMutator<any, any> | ((tx: ServerMutationTx) => void | Promise<void>),
+    args?: unknown,
+    ctx?: MutatorCtx,
+  ): Promise<void> {
+    // A shared (generator) mutator is driven via the isomorphic seam; a plain callback gets the raw tx.
+    const run = isGeneratorMutator(first)
+      ? async (tx: ServerMutationTx) => {
+          await runSharedMutation(first as SharedMutator<unknown, MutatorCtx>, args, ctx as MutatorCtx, tx);
+        }
+      : async (tx: ServerMutationTx) => {
+          await (first as (tx: ServerMutationTx) => void | Promise<void>)(tx);
+        };
+    let outcome: MutationOutcome;
+    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<User = unknown>(opts: RindleApiServerOptions<User>): RindleApiServer<User> {
   const routes = { ...DEFAULT_RINDLE_API_ROUTES, ...opts.routes };
   const mode = opts.mode ?? "normalized";
@@ -1549,6 +2068,25 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
   // 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<User>({
+    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: string, args: unknown, context: ApiContext<User>): Promise<Ast> => {
@@ -1560,6 +2098,375 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     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: string) => 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<string>();
+  const warnRoomServeOnce = (queryName: string, profile: string, reasons: readonly string[]): void => {
+    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<string, CoverQueryOutput>();
+  const COVER_VERDICT_CACHE_MAX = 1024;
+
+  const maybeRoomServe = async (
+    input: QueryLeaseRequest<User>,
+    queryAst: Ast,
+    context: ApiContext<User>,
+    subject: string | undefined,
+  ): Promise<QueryLeaseRealtime | undefined> => {
+    // (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 as string);
+        }
+        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<string>();
+  const warnLifecycleOnce = (queryName: string, reason: string): void => {
+    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: QueryLeaseRequest<User>): string | undefined => {
+    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: QueryLeaseRequest<User>,
+    roomServed: boolean,
+    subject: string | undefined,
+    routingKey: string | undefined,
+  ): Promise<QueryLeaseLifecycle | undefined> => {
+    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: 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: string, out: MaterializeOutput, id: { scope?: string; doc?: string; clientId?: string }): QueryLeaseLifecycleLease => ({
+        table,
+        leaseToken: out.leaseToken,
+        ...(id.scope !== undefined ? { scope: id.scope } : {}),
+        ...(id.doc !== undefined ? { doc: id.doc } : {}),
+        ...(id.clientId !== undefined ? { clientId: id.clientId } : {}),
+      });
+      const lifecycle: QueryLeaseLifecycle = {
+        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<string>();
+  interface LifecycleOccupancy {
+    /** The D6 room-serve gate verdict — `false` ⇒ suppress the room block (solo/uncovered). */
+    gateOpen: boolean;
+    /** The I-v downgrade guard: a room plausibly hosts this scope (some other-session row lives
+     *  or lingers). Only a `!gateOpen && roomPlausible` reply drains — never a never-shared doc. */
+    roomPlausible: boolean;
+    /** The wire doc the scope maps to (`"<profile>/<key>"`); `undefined` when unlabeled / off. */
+    doc: string | undefined;
+  }
+  const lifecycleOccupancy = async (input: QueryLeaseRequest<User>): Promise<LifecycleOccupancy> => {
+    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: SqlStatement[] = [
+        { 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<string>();
+  const warnDrainOnce = (queryName: string, reason: string): void => {
+    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: string, doc: string): Promise<QueryLeaseRealtimeFence | undefined> => {
+    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: QueryLeaseRequest<User>): Promise<QueryLeaseResponse> => {
     const context: ApiContext<User> = { user: input.user, request: input.request };
     await assertAuthorized(opts.authorizeQuery, {
@@ -1586,8 +2493,38 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
       // 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: QueryReadRequest<User>): Promise<QueryReadResponse> => {
@@ -1609,10 +2546,13 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     const subject = await resolveSubject(opts.subject, input);
     const routingKey = await resolveRoutingKey(opts.routingKey, input);
     const visibilityKey = subject ?? routingKey;
-    const out = await opts.daemon.query({ ast, visibilityKey, ttlMs: opts.readIdleTtlMs });
-    const res: QueryReadResponse = { rows: out.rows, cvMin: out.cvMin, queryKey: out.queryKey };
-    if (out.wsEndpoint !== undefined) res.wsEndpoint = out.wsEndpoint;
-    return res;
+    const 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: PushMutationRequest<User>): Promise<PushMutationResponse> => {
@@ -1629,23 +2569,80 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     } 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: MutationContext<User> = {
+      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<User>(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: unknown, phase: "committed" | "rejected"): void => {
+        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?: { err: unknown }): Promise<PushMutationResponse> => {
+        // 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 as unknown as ScopedMutator<User, unknown>)(scope, input.envelope.args as never, 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 as never, {
-          user: input.user,
-          envelope: input.envelope,
-          daemon: opts.daemon,
-          request: input.request,
-        });
+        const result = await mutator(tx, input.envelope.args as never, 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: PushMutationsRequest<User>): Promise<PushMutationResponse[]> => {
@@ -1703,10 +2700,60 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     }
   };
 
+  // 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?: {
+    exemplars?: Partial<Record<string, readonly unknown[]>>;
+    strict?: boolean;
+  }): Promise<ValidateRealtimeReport> => {
+    const context: ApiContext<User> = { user: opts.pinUser as User, request: undefined };
+    const coverQuery = opts.daemon.coverQuery?.bind(opts.daemon);
+    const verdicts: ValidateRealtimeVerdict[] = [];
+    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: ValidateRealtimeVerdict = { 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: Authorizer<ApiContext<User>> | undefined = realtime
     ? (realtime.authorize ?? defaultFlushGate(realtime.shellSecret))
     : opts.authorizeRoom;
@@ -1717,6 +2764,40 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     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: RindleRealtimeOptions<User>,
+    doc: string,
+    context: ApiContext<User>,
+  ): Promise<{ ast: Ast; contextTables: ReadonlySet<string> }> => {
+    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<string>(),
+      };
+    }
+    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: unknown): RoomHostResponse => {
@@ -1737,6 +2818,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     createQueryLease,
     readQuery,
     assertPins,
+    validateRealtime,
     pushMutation,
     pushMutations,
     handleApplyRowChangeTxnJson: async (body, context) => {
@@ -1766,6 +2848,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
     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);
       }
@@ -1774,7 +2857,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         throw new Error("the configured daemon client does not implement roomLmids");
       }
       try {
-        return { status: 200, body: await lmids({ clients: msg.clients as string[] }) };
+        return { status: 200, body: await lmids({ doc, clients: msg.clients as string[] }) };
       } catch (e) {
         return daemonVerdict(e);
       }
@@ -1787,7 +2870,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
       const msg = parseObject(body, "room-boot request");
       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");
@@ -1815,6 +2898,9 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         const res: RoomBootResponse = {
           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,
@@ -1824,7 +2910,8 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
             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 };
       } catch (e) {
@@ -1839,6 +2926,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         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) => {
@@ -1849,6 +2937,7 @@ export function createRindleApiServer<User = unknown>(opts: RindleApiServerOptio
         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) => {
@@ -2020,21 +3109,157 @@ async function resolveRoutingKey<User>(
 }
 
 function queryLeaseResponse(out: MaterializeOutput): QueryLeaseResponse {
-  const res: QueryLeaseResponse = {
+  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: unknown): string {
   return String((reason as Error)?.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: string, value: string): Condition {
+  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: string): Ast {
+  return { table: SCOPE_SESSIONS_TABLE, where: colEq("scope", scope) };
+}
+
+/** The §4.2 fence AST: the doc's monotone `flush_seq` row. */
+function roomWatermarkAst(doc: string): Ast {
+  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: string, doc: string, clientId: string | undefined): Ast {
+  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: unknown): string {
+  return JSON.stringify(v, (_key, value: unknown) => {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const rec = value as Record<string, unknown>;
+      const sorted: Record<string, unknown> = {};
+      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: Ast): boolean {
+  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: Condition | undefined): boolean {
+  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: MutationBackend,
   envelope: MutationEnvelope,
@@ -2044,6 +3269,15 @@ async function reject(
   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: MutationOutcome): PushMutationResponse {
+  return outcome.accepted
+    ? { accepted: true, rejected: false, output: outcome.output }
+    : { accepted: false, rejected: true, reason: outcome.reason, output: outcome.output };
+}
+
 function parseObject(value: unknown, label: string): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new RindleApiError("bad-request", `invalid ${label}`, 400);