@rindle/optimistic 0.5.0 → 0.6.3

package/dist/backend.d.ts

@@ -1,5 +1,4 @@
-import type { Ast, Backend, BackendDevObserver, ChangeEvent, ColsMap, Condition, IsoTx, KeyedRow, Mutation, MutationEnvelope, MutationGen, MutatorCtx, OptimisticSource, QueryArg, QueryId, QueryResultRow, RemoteQuery, ResultType, Schema, WireValue } from "@rindle/client";
-import { type WritableDescriptor } from "@rindle/wasm";
+import type { Ast, Backend, BackendDevObserver, ChangeEvent, ColsMap, IsoTx, KeyedRow, Mutation, MutationEnvelope, MutationGen, MutatorCtx, OptimisticSource, QueryArg, QueryId, QueryResultRow, RemoteQuery, ResultType, Schema, WireValue } from "@rindle/client";
 import { type SystemStreamSpec } from "./system-streams.ts";
 export type { SystemStreamSpec, SystemStreamTable } from "./system-streams.ts";
 /** A keyed row: column name → cell. The ergonomic shape — column names are validated against the
@@ -60,16 +59,13 @@ export type { ResultType };
  *  the post-write image (positional wire cells, schema column order); `undefined` for a `remove` —
  *  no row survives it, and `row === undefined` stays the remove marker.
  *
- *  `oldRow` is the PRE-IMAGE, captured for a `remove` (G-iii, §7.3 tombstone) AND — since H-ii —
- *  an `edit` (it feeds H-iii's join-key no-change rule, old vs new join-key cells, and mirrors the
- *  engine, which routes an Edit by its OLD row — the H-i handoff): the full-width row read via
- *  `tx.get` immediately BEFORE the write staged — read-your-writes, so a write to the same pk
- *  earlier in the SAME invocation shows through — falling back to the caller's asserted old row
- *  when the pk is not txn-visible (a raw remove/edit of an absent row; incl. the pk-MOVING raw
- *  edit, whose record is keyed by the NEW pk yet whose pre-image is the caller's OLD row — the row
- *  H-i's `provenanceOf` routes by). A captured remove/edit thus always carries a full-width
- *  pre-image (the engine width-checks `holdBackAbsent`; Slice H evaluates writable predicates on
- *  it) — with ONE exception: a record that collapses to a (re-)insert has none, see the matrix.
+ *  `oldRow` is the PRE-IMAGE, captured for a `remove` AND an `edit` (H-ii): the full-width row
+ *  read via `tx.get` immediately BEFORE the write staged — read-your-writes, so a write to the
+ *  same pk earlier in the SAME invocation shows through — falling back to the caller's asserted
+ *  old row when the pk is not txn-visible (a raw remove/edit of an absent row; incl. the
+ *  pk-MOVING raw edit, whose record is keyed by the NEW pk yet whose pre-image is the caller's
+ *  OLD row). A captured remove/edit thus always carries a full-width pre-image — with ONE
+ *  exception: a record that collapses to a (re-)insert has none, see the matrix.
  *
  *  Coalescing within one invocation is last-write-wins per pk on `row` (the final image matches
  *  the engine head's own semantics for that pk) with `oldRow` pinned to the TXN-ENTRY BASE — the
@@ -114,119 +110,19 @@ export interface ReadRecord {
     table: string;
     pk: WireValue[];
     outcome: ReadOutcome;
-    /** Per-read provenance (H-ii, §3.2 #3): the engine's `provenanceOf` answer AT THE MOMENT OF THE
-     *  READ — which source ("daemon" / a room key) served the row the mutator saw. Live pre-commit
-     *  state: an open txn's staged writes are not consulted (H-i), so a PRESENT read of a pk this
-     *  txn itself created reports `undefined` — recorded honestly, key omitted (the router treats
-     *  self-reads via write-set membership, not provenance). ABSENT reads carry no source (the
-     *  mutator saw no row; there is no full-width row to probe with — a pk this txn staged-removed
-     *  thus also records `undefined`, again a write-set-membership case for the router). Probed only
-     *  on a PROMOTED table ({@link promotedTables}): a never-promoted (Collapsed) table is
-     *  daemon-owned by construction, so a pure single-domain app pays zero wasm calls per read and
-     *  `undefined` is still correct (everything is daemon-owned). One probe call per recorded
-     *  present read, at read time. */
-    source?: string;
 }
 /** The read-log captured over ONE mutator invocation when recording is armed (RINDLE-REALTIME-
  *  QUERY-ENABLEMENT-DESIGN.md §3.2 #2): every point read (`reads` — the public `tx.get`/`tx.row`
  *  and, since H-ii, the keyed writers' internal pre-existence probes) plus every resolved query AST
  *  (`queries`, from `tx.query`). A SIBLING of the folded read TRAP (`FoldReadError` below) — the
  *  trap arms on the folded path and throws before any read completes (recording never runs there);
- *  recording arms on the ordinary (non-folded) prediction run and never throws. Pure capture: which
- *  row/predicate a read is actually PROVEN covered by (§3.1's table) is a later slice's job. */
+ *  recording arms on the ordinary (non-folded) prediction run and never throws. Pure capture for
+ *  devtools/inspection (the §3 routing derivation it once fed was removed by
+ *  302-ROOM-STORE-SEPARATION-DESIGN.md §5 — mutators DECLARE their domain now). */
 export interface ReadLog {
     reads: ReadRecord[];
     queries: Ast[];
 }
-/** One promoted `(sourceKey, table)`'s client-held routing spec — THE per-table routing record the
- *  §3 prove-or-slow-path router reads (H-iii). Recorded by {@link OptimisticBackend.promoteRoomTable}
- *  in the same breath as the engine attach, from the lease's `RealtimeLeaseTableSpec` (the
- *  api-server's `RoomTableSpec`, one compiler with the boot wire).
- *
- *  - `writable`: whether the room may write this table AT ALL — `true` iff the registered engine
- *    {@link WritableDescriptor} is not `none` (a context/"followed" table is `none`; the daemon
- *    stays write-authoritative for it, §2.2). Rule #1 of the write proof.
- *  - `joinKeyCols`: the correlation columns the footprint binds on this table — the "room mutators
- *    never change join keys" input (an edit with a moved join-key cell would re-parent the row
- *    across the footprint's correlation and is refused room-routing). Deliberately client-side —
- *    they never cross the wasm {@link WritableDescriptor} ABI (the room GATE enforces them
- *    engine-side, H-iv).
- *  - `where`: the lease's row-local writable predicate (advisory here — the router evaluates the
- *    ENGINE's compiled copy via `writableMatches`, never this one; kept for introspection parity
- *    with the wire).
- *  - `footprintWhere`: the EXACT footprint-membership predicate (H-iv-b: root-node-only, lossless
- *    extraction; the vacuous-true `{type:"and",conditions:[]}` for an exact unconstrained root;
- *    ABSENT for child/correlated tables). The read proof's pk-membership test input — see
- *    {@link OptimisticBackend.deriveDomain}. */
-export interface RoomTableRouting {
-    writable: boolean;
-    joinKeyCols: string[];
-    where?: Condition;
-    footprintWhere?: Condition;
-}
-/** The per-table spec {@link OptimisticBackend.promoteRoomTable} receives beside the engine
- *  descriptor (H-iii spec plumbing) — the wire-facing half of {@link RoomTableRouting}
- *  (`writable` is derived from the descriptor's kind, never passed separately). */
-export interface RoomTableRoutingSpec {
-    joinKeyCols?: readonly string[];
-    where?: Condition;
-    footprintWhere?: Condition;
-}
-/** The §3 router's Q6 measurement hook ({@link OptimisticBackend.__inspectDomains}`().routing`):
- *  how often derivation succeeded (per derived room) and why it fell back to the daemon (per
- *  failure reason). `reasons` counts PER-CANDIDATE proof failures plus the terminal reasons
- *  (`no-candidates` / `tx-query` / `ambiguous`) — with multiple candidate rooms one derivation can
- *  bump several reason counters (one per failing candidate), and a candidate's failure is counted
- *  even when a sibling candidate ultimately proved. Explicit-policy pins bump NOTHING (the router
- *  never ran). */
-export interface RoutingInspect {
-    /** Successful DERIVED routes, per room key. */
-    derived: Record<string, number>;
-    /** Derivation failures, per {@link RoutingFailureReason}. */
-    reasons: Record<string, number>;
-}
-/** Why a §3 derivation (or one candidate's proof) fell to the daemon — the {@link RoutingInspect}
- *  counter keys. */
-export type RoutingFailureReason = 
-/** No connected room gate with a promoted table — the single-domain fast path. */
-"no-candidates"
-/** The invocation ran `tx.query` — a declarative read is not room-provable client-side
- *  (rindle-cover is native-only BY DESIGN), so the whole derivation fails unconditionally. */
- | "tx-query"
-/** Two or more candidate rooms both proved. Principled disambiguation is a §9.2 (multi-room
- *  clients + budgets) NON-goal, deferred past Slice J; routing slow is always sound (the §3.3
- *  gate is the contract). Reachable essentially only for zero-write mutations — real writes
- *  can't be writable in two rooms (§2.2 exactly-one-writer per doc). */
- | "ambiguous"
-/** A write touched a table not promoted for the candidate, or promoted `writable: none`
- *  (context) — the room may not write it at all. */
- | "write-unwritable-table"
-/** `writableMatches` refused the write's post-image (add/edit) or pre-image (remove). */
- | "write-scope-miss"
-/** An edit moved a join-key cell (old vs new differ on a `joinKeyCols` column). */
- | "write-join-key-change"
-/** The engine's provenance for the write's probe row names a DIFFERENT room. */
- | "write-cross-room-provenance"
-/** A recorded read was served by a DIFFERENT room. */
- | "read-cross-room"
-/** A read needed the pk-membership test but the table has no `footprintWhere` (child /
- *  correlated / inexact extraction / never-promoted table). */
- | "read-no-footprint-where"
-/** `footprintWhere` references a non-pk column — not decidable from the key alone. */
- | "read-not-key-decidable"
-/** `footprintWhere` is key-decidable but outside the deliberately-minimal client evaluator
- *  (an op other than `=`/`!=`, a null/type-mixed comparison, column-vs-column, …). */
- | "read-not-evaluable"
-/** `footprintWhere` evaluated FALSE on the read's pk — the room provably never holds it. */
- | "read-outside-footprint"
-/** NOT a derivation failure (H-v): a routed mutation came back `mutationOutcome
- *  {kind:"deopt"}` — the room GATE refused it at commit and the client re-enqueued it onto the
- *  daemon. Counted per processed deopt frame so Q6's picture is complete: derived-and-deopted
- *  routes are visible beside derived successes (a rising `deopt` count against a rising
- *  `derived` count means the client proof and the gate disagree — a compiler/evaluator skew
- *  worth investigating; each one costs a room round-trip + a burnt room mid, never
- *  correctness). */
- | "deopt";
 /** A virtual-clock seam for the fold debounce/maxWait timers (FOLDED-MUTATIONS-DESIGN §9): the
  *  oracle injects a deterministic scheduler; production defaults to real timers + `Date.now`. */
 export interface FoldClock {
@@ -284,6 +180,19 @@ export interface DowngradeStuckEvent {
     doc: string;
     mids: number[];
 }
+/** The 302 §6.1 context-coverage event ({@link OptimisticBackend.onRoomContextJoin}): a view
+ *  swapping onto room `sourceKey`'s namespaced tables still references `tables` the room does NOT
+ *  own — those refs keep reading the PLAIN daemon tables (the client-side join across kinds), and
+ *  the room's relayed copies of them are dropped by design (§6). Whether a daemon subscription
+ *  covers the joined rows is unknowable here, so the condition is surfaced ONCE per view: without
+ *  coverage the join renders silently empty for the whole room session. Fired at swap-in — a view
+ *  whose every referenced table is room-owned (every in-repo app today) never fires it. */
+export interface RoomContextJoinEvent {
+    sourceKey: string;
+    name: string;
+    args: unknown;
+    tables: string[];
+}
 export interface OptimisticBackendOptions {
     /** Stable per-client identity for the upstream envelopes (§8.1). */
     clientID: string;
@@ -297,14 +206,13 @@ export interface OptimisticBackendOptions {
     /** Virtual-clock seam for the fold debounce timers (FOLDED-MUTATIONS-DESIGN §9). Defaults to
      *  real `setTimeout`/`clearTimeout`/`Date.now`; the fold oracle injects a deterministic clock. */
     clock?: FoldClock;
-    /** The explicit confirming-stream OVERRIDE (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §7.1 /
-     *  §3). Since H-iii the live default is the §3 prove-or-slow-path DERIVATION
-     *  ({@link OptimisticBackend.deriveDomain}): a configured policy returning a string pins that
-     *  domain VERBATIM — no proof runs (the test suites and the dual-source e2e pin by name);
-     *  returning `undefined` (or configuring no policy) derives the domain from the prediction run's
-     *  write/read capture against the connected room gates' routing table. With no room gate
-     *  connected the derivation short-circuits to `"daemon"` — every single-domain app is
-     *  byte-for-byte as before. */
+    /** The DECLARED confirming stream per mutation (302 §5: declared, not derived — there is no
+     *  routing proof). A policy returning a string pins that domain verbatim: the mutation stages
+     *  onto that room's namespaced tables and ships on its channel. Returning `undefined` (or
+     *  configuring no policy) means `"daemon"`. The client layer builds this from the app's declared
+     *  realtime mutators + the currently attached rooms; a misdeclaration fails SOFT (302 §5.1) —
+     *  the write lands on the other authority's tables and the view simply stops feeling instant
+     *  until the echo relays it. */
     domainPolicy?: (name: string, args: unknown) => string | undefined;
     /** A FINAL (authz/validation) mutation rejection's reason surface — the room plane's twin of the
      *  HTTP mutate route's `onRejected` (H-v; the H-iv-b `mutationOutcome {kind:"rejected"}` frame).
@@ -442,15 +350,23 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  an evicted mid would be re-processed — the same bounded-window trade the shell makes, and it
      *  takes 512 interleaving non-applied outcomes on one domain to open it. */
     private readonly outcomesProcessed;
-    /** THE routing table (H-iii §3): per connected room `sourceKey` → per promoted table → its
-     *  client-held {@link RoomTableRouting}. Written ONLY by {@link promoteRoomTable} (same breath
-     *  as the engine attach + {@link promotedTables}); read by {@link deriveDomain} and — via
-     *  {@link roomTablesFor} — the client's `__realtimeInspect` bookkeeping. */
-    private readonly roomRouting;
-    /** Q6 counters ({@link RoutingInspect}): successful derivations per room. */
-    private readonly routingDerived;
-    /** Q6 counters ({@link RoutingInspect}): derivation failures per {@link RoutingFailureReason}. */
-    private readonly routingReasons;
+    /** THE room-table registry (302 §2 — one source per table): per connected room `sourceKey`, the
+     *  wire-table → engine-table map for the tables that room OWNS (its writable scope). Written by
+     *  {@link registerRoomTables} (same breath as the engine registration); read by the gate's
+     *  release rename/filter, the mutator staging map, the view swap ({@link processSwapIns}), and
+     *  the client's `__realtimeInspect` bookkeeping. The record outlives a downgrade's disconnect —
+     *  the ghost's views still read the engine tables — and drops at {@link dropGhost} (or the last
+     *  clean release via {@link unregisterRoomTables}). */
+    private readonly roomTables;
+    /** Local view qids currently REGISTERED on a room's namespaced tables (302 §4 swap-in), →
+     *  their sourceKey. Set by {@link processSwapIns}; cleared by the swap-back ({@link dropGhost})
+     *  and view teardown. The original AST stays in {@link asts} throughout — the swap re-registers
+     *  only the ENGINE query. */
+    private readonly roomSwappedViews;
+    /** Room subs whose FIRST snapshot released in the current release — their views swap onto the
+     *  room tables at the release tail ({@link processSwapIns}), strictly AFTER the reconcile folded
+     *  the snapshot into those tables (swapping earlier would hydrate the view EMPTY, a flash). */
+    private readonly pendingSwapIns;
     /** The live fold entries, by fold key `${name}\0${identityJSON}` — at most one per key
      *  (FOLDED-MUTATIONS-DESIGN §8). Insertion order is creation order (the drain/flush tiebreak). */
     private readonly folds;
@@ -473,45 +389,6 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  scalars (`__inspect`) read it directly; its `sync` IS {@link sync} (the agg overlay and
      *  synthetic tables are daemon-tracked by design). */
     private readonly daemonGate;
-    /** Tables promoted to a MERGED multi-source engine (a room source attached). Written by the one
-     *  promotion seam ({@link promoteRoomTable}; the test-named {@link __addRoomSource} and Slice
-     *  G-v's lease-driven promotion from `RoomTableSpec[]` both flow through it). Read by the §7.3
-     *  hold-back trigger in
-     *  {@link applyRelease}: parking on a never-promoted (Collapsed) table is SKIPPED — inert anyway
-     *  today (`rewind_collapsed` never consults `held_back`), and a live hazard if the table later
-     *  promotes (a stale Collapsed-era entry turns overlay-first-visible and pins forever). Slice H's
-     *  prove-or-slow-path routing keeps the real scenario — a room-confirmed mutation writing a
-     *  Collapsed table — impossible; this gate covers the window until then. */
-    private readonly promotedTables;
-    /** The §301 pin registry ({@link EchoFencePin}): every parked §7.3 hold-back's delivery-fence
-     *  inputs, keyed `${table}\0${sourceKey}\0${pkKey}`. Written in the same breath as the
-     *  `holdBack`/`holdBackAbsent` park; read by {@link dropEchoFencePins} at the tail of every
-     *  release. Empty on every single-domain client — the drop pass is then a structural no-op. */
-    private readonly pins;
-    /** The §301 direction-A fence input: per room domain, the highest lmid the DAEMON-CARRIED
-     *  ledger rows have folded ({@link foldSystemFrames} step 2 — and ONLY that path: the room
-     *  socket's own lmid stream confirms long before the flush reaches the daemon, so it folds
-     *  into the shared {@link watermark} but never here, 301 §1.1). When this covers a pin's mid,
-     *  the same coherent release (or an earlier one) folded the flush data that carried it into
-     *  the daemon baseline — the fence. */
-    private readonly daemonCarriedLmid;
-    /** The §301 §2.4 boot rule's inputs: the daemon boot ids this client has OBSERVED, in order
-     *  (id → ordinal), plus the current one. Boot ids are opaque — ordering is the client's own
-     *  observation ({@link OptimisticSource.onBootId} on the daemon gate). Direction-B pins stamp
-     *  the current boot; a room advertising a LATER-observed boot proves absorption (its
-     *  re-snapshot came from a daemon state that durably includes the confirmed write). */
-    private readonly daemonBootOrdinals;
-    private daemonBootId;
-    /** The per-read provenance probe `invoke` hands `trackingTx` when recording is armed (H-ii,
-     *  §3.2 #3): the engine's `provenanceOf` — the VISIBLE overlay-first winner for the row's pk,
-     *  read from LIVE pre-commit state (an open txn's staged writes are not consulted; H-i). Gated
-     *  on PER-TABLE {@link promotedTables} membership — the cheapest existing signal, and the
-     *  correct one: provenance is an ENGINE-merge question, not a channel question ({@link gates}
-     *  can hold a connected-but-unpromoted room feed, and the oracle harness promotes with no gate),
-     *  and a never-promoted (Collapsed) table is daemon-owned by construction. So a pure
-     *  single-domain app pays ZERO wasm calls per recorded read; the recorded `source` is then
-     *  `undefined`, which is also correct — everything is daemon-owned (see {@link ReadRecord}). */
-    private readonly readProvenance;
     /** System retains by source qid ({@link retainSystemQuery}): a subscription with NO store view
      *  and NO user-visible table — its frames buffer on its gate exactly like {@link LMID_QID}'s and
      *  fold at RELEASE time ({@link foldSystemFrames}), never entering the sync layer or the local
@@ -552,6 +429,12 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  only through outcome resolution; the ghost holds rather than inventing a timeout-retire).
      *  Default no-op. */
     private downgradeStuckHandler;
+    /** The 302 §6.1 context-coverage surface ({@link onRoomContextJoin}) — fired at most once per
+     *  view ({@link contextJoinWarned}), at swap-in, when its AST references tables the room does
+     *  not own. Default no-op. */
+    private roomContextJoinHandler;
+    /** Views the context-coverage event already fired for (once per view; cleared on teardown). */
+    private readonly contextJoinWarned;
     private readonly asts;
     /** Per query: the base tables its result can draw from (from the AST tree). */
     private readonly queryTables;
@@ -590,6 +473,18 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  a domain may exist with no connected gate (`__testRelease` drives confirms gate-less); the
      *  live production path stays daemon-only until G calls this. */
     connectSource(sourceKey: string, source: OptimisticSource): void;
+    /** Register the tables room `sourceKey` OWNS (its writable scope — 302 §2): each wire table
+     *  gets its own namespaced ENGINE table (`{@link roomEngineTable}`), an ordinary tracked table
+     *  whose sole authority is the room channel. From here on the channel's released deltas rename
+     *  into these tables (wire tables outside the map are DROPPED — context stays daemon-owned,
+     *  302 §6), room-domain mutators stage onto them, and a room-homed view swaps onto them once
+     *  the room sub hydrates ({@link processSwapIns}). Idempotent per (sourceKey, table); a wire
+     *  table unknown to the schema is skipped (nothing to hold rows for). */
+    registerRoomTables(sourceKey: string, tables: readonly string[]): void;
+    /** The wire-table → engine-table map for room `sourceKey`'s owned tables (empty when none) —
+     *  the client's idempotence check and `__realtimeInspect` read THIS record (one source of
+     *  truth; the client keeps no shadow copy). */
+    roomTablesFor(sourceKey: string): ReadonlyMap<string, string>;
     /** `channel` (G-iii registration-time routing) names the authority channel the remote sub
      *  registers on — a `connectSource`d gate key; default `"daemon"` (every existing caller is
      *  byte-identical). Slice G-v threads the lease's `realtime.sourceKey` here. Validated FIRST
@@ -632,17 +527,15 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *      precedent), flip `sub.channel`, re-arm `sub.hydrated` (the room's own snapshot is the
      *      cutover point), and register on the room source (its resolver presents the handed
      *      roomToken). The old gate's SYNC rows are deliberately NOT dropped: they keep the view's
-     *      rows visible through the window (merge: the daemon-tier holder). Local views keep their
-     *      `hydrated` membership — the view stays `complete` on its authoritative daemon rows.
-     *   2. AT THE ROOM'S FIRST RELEASED SNAPSHOT ({@link flushRetargetGc}): the room source now
-     *      holds the footprint rows (folded via `serverBatchBegin(sourceKey)` — value-equal rows
-     *      re-hydrate as a net-zero diff, RT §3.4 per channel), so the deferred
-     *      `dropQuery`+reconcile on the OLD gate flips each pk's winner daemon→room value-equal:
-     *      net-zero again. No emission carries a disappearance at any point.
+     *      plain tables populated through the window — the view still reads them until the swap.
+     *   2. AT THE ROOM'S FIRST RELEASED SNAPSHOT: the reconcile folds the snapshot into the room's
+     *      namespaced tables, the release tail SWAPS every local view onto them (302 §4.1,
+     *      {@link processSwapIns} — the accepted-flash boundary), and {@link flushRetargetGc}'s
+     *      deferred `dropQuery`+reconcile on the OLD gate then GCs the plain-table rows the sub
+     *      alone referenced — invisible to the swapped views.
      *
      *  Idempotent per target channel: a sub already on `sourceKey` returns immediately (the
-     *  double-doorbell / re-entrancy guard — one retarget per (query, sourceKey), mirroring
-     *  {@link promoteRoomTable}'s caller-side per-(sourceKey, table) idempotence). Validates before
+     *  double-doorbell / re-entrancy guard — one retarget per (query, sourceKey)). Validates before
      *  mutating: a throw here leaves the sub fully daemon-attached (the client's fail-open). */
     retargetRemoteQuery(remote: RemoteQuery, sourceKey: string): QueryId;
     /** Phase 2 of {@link retargetRemoteQuery}, run at the end of every gate release: once a
@@ -653,35 +546,24 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  mid-window was already swept by `releaseRemoteQuery`/`unregisterQuery` (which delete the
      *  record); a vanished record here is pruned defensively. */
     private flushRetargetGc;
-    /** The I-v downgrade orchestration primitive (§4.2/§7.4): retire room `sourceKey` behind the
-     *  watermark fence. The caller has ALREADY retargeted every live sub off the channel
-     *  ({@link retargetRemoteQuery} room→daemon — validated loudly below) and holds the fence from
-     *  the api-server's downgrade response (`finalFlushSeq` = the room's last COMMITTED flush seq;
-     *  `doc` keys the §4.2 watermark fold, {@link roomWatermarks}). Steps, in order:
+    /** The I-v downgrade orchestration primitive (§4.2/§7.4, re-expressed by 302 §4.2 as the
+     *  SWAP-BACK GATE): retire room `sourceKey` behind the watermark fence. The caller has ALREADY
+     *  retargeted every live sub off the channel ({@link retargetRemoteQuery} room→daemon —
+     *  validated loudly below) and holds the fence from the api-server's downgrade response
+     *  (`finalFlushSeq` = the room's last COMMITTED flush seq; `doc` keys the §4.2 watermark fold,
+     *  {@link roomWatermarks}). Steps, in order:
      *
-     *   1. **De-candidacy NOW**: the sourceKey's {@link roomRouting} entries are removed, so
-     *      {@link deriveDomain} stops proposing the room (zero candidates ⇒ `"daemon"`). Unsent
-     *      pending (`mid === null`) re-routes for free — a fold's flush re-derives from the live
-     *      candidate set (§7.5 rule 1). The engine's frozen scope still ANSWERS (`writableMatches`
-     *      / `provenanceOf` — freezing gates serving, not the scope definition); routing is
-     *      TS-gated here.
-     *   2. **Freeze** the WRITABLE promoted tables (`freezeSource`): the room slice becomes the
-     *      §4.2 ghost — wins-if-present in the merge (D4), so its rows (at-or-ahead of the daemon
-     *      until the flush echoes) stay visible while the slice accepts nothing. Context tables
-     *      (`writable: false`) are deliberately NOT frozen: the daemon is authoritative for them
-     *      LIVE (§5.2's context tier) and freezing would invert that, pinning a possibly-BEHIND
-     *      relayed copy over fresher daemon rows; unfrozen they keep exactly the live tiering.
-     *   3. **Disconnect** the channel ({@link disconnectSource}): handlers detached, gate + buffer
+     *   1. **Disconnect** the channel ({@link disconnectSource}): handlers detached, gate + buffer
      *      dropped. `nextMid`/`watermark`/processed-outcomes for the domain are KEPT FOREVER (§7.1:
      *      an assigned mid pins its domain; a later re-upgrade of the same doc continues the
      *      sequence — {@link connectSource} attaches a fresh gate and the lmid snapshot max-folds
      *      into the surviving watermark). Disconnecting BEFORE the daemon sub's first release is
      *      load-bearing: it makes {@link flushRetargetGc}'s deferred old-channel GC a no-op (gate
-     *      gone ⇒ record deleted, nothing dropped) — running that GC would rewind the room slice's
-     *      rows at daemon hydration, i.e. BEFORE the fence, surfacing a lagging follower's stale
-     *      images (the exact regression §4.2 exists to prevent). The ghost's rows leave only
-     *      through {@link dropGhost}'s `removeRoomSource`, value-equal under the fence.
-     *   4. **Ghost + first evaluation**: the record joins {@link ghosts} and is evaluated once
+     *      gone ⇒ record deleted, nothing dropped). The room's namespaced tables — and the views
+     *      swapped onto them — deliberately stay: frozen at the room's last state, they keep the
+     *      document visible while the falling-back follower may still lack the final flush.
+     *      Swapping back earlier would show its pre-flush images — the regression §4.2 prevents.
+     *   2. **Ghost + first evaluation**: the record joins {@link ghosts} and is evaluated once
      *      immediately — `finalFlushSeq === 0` (a never-flushed room) with no room-domain pending
      *      drops on the spot, the single-daemon first-frame case.
      *
@@ -705,6 +587,10 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  later registration replaces it, the {@link onScopeSessions} convention); client.ts maps it
      *  onto the loud anomaly surface. */
     onDowngradeStuck(handler: (event: DowngradeStuckEvent) => void): void;
+    /** Register the 302 §6.1 context-coverage sink — see {@link RoomContextJoinEvent}. One handler
+     *  (a later registration replaces it, the {@link onScopeSessions} convention); client.ts maps
+     *  it onto the loud anomaly surface. */
+    onRoomContextJoin(handler: (event: RoomContextJoinEvent) => void): void;
     /** The I-v ghost-drop watcher (§4.2), run after every applied release ({@link applyRelease} —
      *  the seam where {@link roomWatermarks} has just folded and the confirm-drop has just run) and
      *  once at demote time. For each ghost: the fence must be satisfied
@@ -714,16 +600,20 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  HOLDS and the stuck event fires exactly once, naming the mids). Both satisfied ⇒
      *  {@link dropGhost}. */
     private evaluateGhosts;
-    /** Drop one cleared ghost (§4.2 end state): detach every promoted table's room source (D2
-     *  stay-merged — `removeRoomSource` reconciles each held pk to daemon-or-vanish, value-equal
-     *  under the fence, so visually a no-op), release the {@link promotedTables} record for tables
-     *  no OTHER room/ghost still holds, then run ONE daemon reconcile so entries whose writes had
-     *  staged onto the ghost slice re-invoke and re-stage by provenance onto the daemon slice (the
-     *  removal took their staged copies with the tree; provenance now answers daemon). The whole
-     *  drop runs under one commit boundary so the removal's compensating deltas and the re-staged
-     *  predictions notify as ONE step. After this, a FUTURE upgrade of the same doc promotes
-     *  again from scratch — the round trip is pinned by the §8.5 lanes. */
+    /** Drop one cleared ghost — the 302 §4.2 SWAP-BACK: under the fence the daemon tables are
+     *  value-equal-or-ahead of the room's final state, so (1) every view swapped onto the room's
+     *  namespaced tables re-registers on its ORIGINAL (daemon-table) AST — visually a no-op, the
+     *  Store folds the re-hello as an in-place reset; (2) the namespaced tables unregister (no
+     *  reader is left after the swap); (3) ONE daemon reconcile re-invokes the pending set so any
+     *  entry whose writes had staged onto the now-gone room tables re-stages onto the daemon tables
+     *  (its domain policy stopped naming the dead room when the client dropped it). The whole drop
+     *  runs under one commit boundary so the swap and the re-staged predictions notify as ONE step.
+     *  After this, a FUTURE upgrade of the same doc registers again from scratch. */
     private dropGhost;
+    /** Unregister room `sourceKey`'s namespaced engine tables and drop the {@link roomTables}
+     *  record. Callers must have no view registered on them (the engine refuses otherwise —
+     *  loud by design). No-op for an unknown sourceKey. */
+    unregisterRoomTables(sourceKey: string): void;
     /** Retain one minted SYSTEM subscription (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §4, Slice
      *  I-iii): a wire sub with NO store view and NO user-visible table. Registered through the same
      *  {@link RemoteSub} bookkeeping as any remote retain — so qid→channel ownership, the overflow
@@ -802,30 +692,30 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  and takes only the fresh mid (the dealSeq bump is harmless: seq consumers order, never
      *  count). */
     private dealMid;
-    /** The route decision for one invocation (invoke, and again at fold flush): the explicit
-     *  `domainPolicy` is the OVERRIDE — a string pins that domain verbatim, no proof runs;
-     *  `undefined` (or no policy configured) derives per §3. */
+    /** The declared confirming stream for one invocation: the `domainPolicy`'s verdict, `"daemon"`
+     *  when it abstains. Resolved BEFORE the prediction runs — the domain picks the staging map
+     *  (a room domain stages its owned tables onto the room's namespaced twins). */
     private resolveDomain;
-    /** §9.3: does this fold's write-set route into a room (vs the daemon)? Used ONLY to pick the
-     *  {@link FoldOptions.roomDebounceMs} cadence at a fold window's start. It probes
-     *  {@link resolveDomain} but RESTORES the Q6 routing diagnostics afterward — the authoritative
-     *  route and its single counter bump belong to the flush ({@link flushFold}), not to this
-     *  interval hint. A fold's reads are provably empty (the read-trap arms on that path), so the
-     *  write-set alone decides. */
-    private routesToRoom;
-    /** Count one derivation failure ({@link RoutingInspect}). Returns `false` so the per-candidate
-     *  proof's call sites read `return this.failDerivation(...)`. */
-    private failDerivation;
-    /** The §3 derivation. Candidates are the connected room gates with at least one promoted table
-     *  (a promoted table with no gate cannot confirm; a gate with no promoted table holds no data to
-     *  prove against). Zero candidates ⇒ `"daemon"` (the single-domain fast path). The proof runs
-     *  per candidate and EXACTLY ONE must survive — two rooms both proving routes slow (principled
-     *  disambiguation is a §9.2 multi-room NON-goal, deferred past Slice J; slow is always sound). */
-    private deriveDomain;
-    /** One candidate room's §3 proof over the captured write-set + read-log. Every write must pass
-     *  ALL the write rules; every read must pass ONE of the read rules. First failure wins (and is
-     *  counted); order is deterministic (write-set map order, then read-log order). */
-    private provesRoom;
+    /** The staging table map for a `domain`-routed prediction ({@link trackingTx}'s `stage`):
+     *  wire table → the room's namespaced engine table for the tables the room owns; identity for
+     *  everything else (including the whole map for the daemon domain). */
+    private stagingMap;
+    /** The PLAIN (daemon-homed) engine AST for `ast` — aggregate relationships rewritten to their
+     *  synthetic `__agg_*` reads, no room renames. The ONE form every non-swapped engine
+     *  registration uses ({@link registerQuery}, {@link dropGhost}'s swap-back) and the base the
+     *  swap-in renames ({@link processSwapIns}). */
+    private plainEngineAst;
+    /** Mutator names the cross-authority warn below already fired for (once per name). */
+    private readonly warnedCrossAuthority;
+    /** 302 §5.1 dev-time guard: a room-DECLARED mutator wrote tables the room does not own. Those
+     *  writes staged onto the PLAIN daemon tables (the staging map covers only owned tables), but
+     *  the entry confirms on the ROOM stream — and only the room's OWNED tables flush back to the
+     *  daemon, so nothing upstream ever echoes them: once the room confirm retires the entry, the
+     *  next release's whole-store rewind reverts them for good. The first-party room shell refuses
+     *  such a mutation (the §3.3 deopt/reject backstop re-routes it to the daemon), so this warns
+     *  for the shapes where that backstop may be absent (a BYO relay) — loud, once, soft (§5.1:
+     *  misdeclarations never throw). */
+    private warnCrossAuthorityWrites;
     /** Run the named client mutator optimistically: the prediction applies to the live
      *  engine now (affected views update synchronously), `(mid, name, args)` joins the
      *  pending stack, and the envelope ships upstream. Returns the assigned `mid`. */
@@ -951,54 +841,32 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
         nextMid: Record<string, number>;
         watermark: Record<string, number>;
         /** Per connected CHANNEL (§5.1): its release watermark + buffered-frame depth — the axis the
-         *  gate-isolation assertions read (one source's laggy cvMin must never move the other's) —
-         *  plus the §301 upstream-absorption advert last recorded from its progress frames (a ROOM
-         *  gate with a new shell; absent otherwise). */
+         *  gate-isolation assertions read (one source's laggy cvMin must never move the other's). */
         gates: Record<string, {
             appliedCv: number;
             bufferedFrames: number;
-            upstreamCv?: number;
-            upstreamBoot?: string;
         }>;
-        /** The §3 router's counters (H-iii) — Q6's measurement hook: how often derivation succeeded
-         *  (per derived room) and why it fell to the daemon (per reason). See {@link RoutingInspect}
-         *  for the counting discipline (per-candidate failures; pins bump nothing). */
-        routing: RoutingInspect;
+        /** Per connected/registered room: its wire-table → engine-table map (302 §2) and which local
+         *  view qids are currently swapped onto it (302 §4). */
+        roomTables: Record<string, Record<string, string>>;
+        swappedViews: Record<number, string>;
         /** The §4 lifecycle plane's folded state (Slice I-iii introspection): the per-doc §4.2 fence
          *  value (`roomWatermarks`, I-v's ghost-drop input), the per-scope §4.1 occupancy map
          *  (`scopeSessions`: scope → client_id → expires_at, I-iv's doorbell input), and the live
-         *  I-v ghosts (demoted room sources still awaiting their fence). */
+         *  I-v ghosts (demoted room sources still awaiting their swap-back fence). */
         lifecycle: {
             roomWatermarks: Record<string, number>;
             scopeSessions: Record<string, Record<string, number>>;
             ghosts: Record<string, {
                 doc: string;
                 finalFlushSeq: number;
-                tables: string[];
             }>;
         };
-        /** The live §301 pin registry (`301-ECHO-FENCE-DESIGN.md` §2.5 — the devtools/Q6 surface):
-         *  every parked hold-back's fence inputs plus its tripwire state, keyed
-         *  `${table}\0${sourceKey}\0${pkKey}`. Pruned lazily, so an entry here may briefly outlive
-         *  its engine pin (never the reverse). */
-        pins: Record<string, {
-            table: string;
-            sourceKey: string;
-            domain: string;
-            mid: number;
-            daemonBoot?: string;
-            daemonCv?: number;
-            tripwired: boolean;
-        }>;
-        /** The §301 direction-A fence map: per room domain, the highest DAEMON-CARRIED ledger lmid. */
-        daemonCarriedLmid: Record<string, number>;
         pending: {
             mid: number | null;
             seq: number | null;
             name: string;
             domain: string;
-            touchedSources: string[];
-            writeSources: Record<string, string>;
         }[];
     };
     /** Recompute the pending axis for every query and fire `onPending` on transitions only. Called
@@ -1036,50 +904,18 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  exercise a room-domain confirm before the real second lmid stream / per-source gate is wired
      *  (E-iii-b/c). The `__`-prefix marks it a test hook, alongside {@link __inspect}. */
     __testRelease(sourceKey: string, deltas: Mutation[], watermarkUpdate?: number): void;
-    /** Register (or overwrite — a later cross-slice confirm re-pinning the same slice-pk matches
-     *  the engine's `held_back.insert`) one {@link EchoFencePin}, in the same breath as the
-     *  engine park (§2.1). `p` is the confirmed entry whose write staged onto `sourceKey`; its
-     *  `mid` is non-null by the caller's confirm filter. */
-    private registerPin;
-    /** The §2.3 drop pass, run at the tail of every applied release: prune registry entries whose
-     *  engine pin is already gone (the rewind's state-match fallback or a whole-source removal beat
-     *  the fence — benign), drop every pin whose fence cleared (one engine drop each, delivered on
-     *  the ordinary event stream, bracketed as ONE notification commit), and tripwire the rest. */
-    private dropEchoFencePins;
-    /** Has `pin`'s delivery fence provably closed its confirm→echo window? (§2.3/§2.4.) */
-    private pinFenceCleared;
-    /** The §2.5 stuck-pin tripwire, in the scopesHash spirit: log ONCE per pin when its slice's
-     *  baseline row has CHANGED VALUE since park while the pin still holds — the suspicious state
-     *  that precedes every forever-pin (a fence-less pairing, a fence bug). Never drops anything. */
-    private maybeTripwirePin;
-    /** Record one observed daemon boot id (§2.4): first observation of an id assigns the next
-     *  ordinal (the client's own total order over opaque boot ids); every call refreshes the
-     *  current-boot stamp for direction-B parks. */
-    private observeDaemonBoot;
-    /** Promote `table` to a MERGED multi-source engine with room `sourceKey`'s per-row writable
-     *  scope (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §5.2) — THE one promotion seam. The engine
-     *  attach and the {@link promotedTables} record move in the same breath: the §7.3 hold-back
-     *  trigger in {@link applyRelease} parks ONLY on promoted tables, so a promotion that bypassed
-     *  the record would silently disable the echo hold-back for that table (and a record without the
-     *  engine attach would park onto a slice that doesn't exist). Recorded AFTER the engine accepts —
-     *  a rejected descriptor/table must not leave a phantom promotion. Slice G-v's client drives this
-     *  from the lease's `realtime.tables` (`RoomTableSpec` → {@link WritableDescriptor}); idempotence
-     *  per `(sourceKey, table)` is the CALLER's job (the engine refuses a duplicate room).
+    /** Swap every view of each just-hydrated ROOM sub onto the room's namespaced tables (302 §4.1):
+     *  re-register the local engine query with the AST's room-owned table references renamed
+     *  ({@link remapAstTables}); the Store folds the re-hello as an in-place reset, so the caller's
+     *  view reference survives and subscribers see ONE transition. Runs at the applyRelease tail —
+     *  the reconcile has already folded the sub's snapshot into the room tables, so the swapped
+     *  view hydrates straight to the room state (swapping earlier would flash it empty). The
+     *  ORIGINAL ast stays in {@link asts}; the swap-back ({@link dropGhost}) re-registers it.
      *
-     *  `spec` (H-iii) is the per-table ROUTING spec riding the same lease table block — recorded
-     *  into {@link roomRouting} (THE routing table the §3 router reads) in the same breath, with
-     *  `writable` derived from the descriptor's kind (`none` = a context table the room may not
-     *  write). Omitted (the E-iii-b harness alias below) ⇒ an empty spec: no join keys to guard, no
-     *  `footprintWhere` (that room's reads then fail closed to the daemon unless self/room-served). */
-    promoteRoomTable(table: string, sourceKey: string, writable: WritableDescriptor, spec?: RoomTableRoutingSpec): void;
-    /** The recorded routing specs for `sourceKey`'s promoted tables (table → its
-     *  {@link RoomTableRouting}) — read-only: the client's `__realtimeInspect`/idempotence
-     *  bookkeeping reads THIS record instead of keeping its own shadow copy (one source of truth).
-     *  Empty map when the room has promoted nothing. */
-    roomTablesFor(sourceKey: string): ReadonlyMap<string, RoomTableRouting>;
-    /** Test-named alias of {@link promoteRoomTable} (E-iii-b scaffolding — the multi-domain oracle
-     *  and per-source-gate suites drive it). Pure delegation: ONE body, one `promotedTables` record. */
-    __addRoomSource(table: string, roomKey: string, writable: WritableDescriptor, spec?: RoomTableRoutingSpec): void;
+     *  This is the accepted-flash boundary (302 §4.1/§7.1): the room's copy may be behind the
+     *  daemon rows the view showed a moment ago — accepted by decision, revisit on a real
+     *  two-region deploy. */
+    private processSwapIns;
     /** Fold `domain`'s lmid system query's released ops (lmid-as-data): the one row's
      *  `last_mutation_id` cell is this client's confirmed high-water mid in that domain — it advances
      *  `watermark[domain]` and, on a fresh session ahead of our issued mids, `nextMid[domain]`. The
@@ -1177,8 +1013,10 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  longer affects it. Used when a remote sub attaches to or hydrates a local view. */
     private recomputeResultType;
     /** A remote sub's first snapshot landed: mark it (and every local view it feeds) hydrated, then
-     *  lift those views out of `unknown` (loading). Idempotent — a re-hydrate snapshot re-marks
-     *  harmlessly; a source qid with no sub (the lmid system query) is a no-op. */
+     *  lift those views out of `unknown` (loading). A ROOM sub's hydration additionally queues the
+     *  302 §4.1 swap-in — performed at the applyRelease TAIL ({@link processSwapIns}), once the
+     *  reconcile has folded this snapshot into the room tables. Idempotent — a re-hydrate snapshot
+     *  re-marks harmlessly; a source qid with no sub (the lmid system query) is a no-op. */
     private markSubHydrated;
     /** `channel` (G-iii registration-time routing): the gate the sub registers on — the qid's
      *  ownership is fixed HERE, at retain time (no lazy claim; `onFrame` only asserts it). Default
@@ -1187,19 +1025,17 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
     private releaseRemote;
     private addServerDependencyTables;
 }
-/** Whether `cond` is decidable from the KEY ALONE: every column it references — collected from
- *  BOTH operand positions (under-counting could over-claim decidability; over-counting only fails
- *  closed — the H-iv-a discipline) — is a pk column. A `correlatedSubquery` is never key-local. */
-export declare function keyDecidable(cond: Condition, pkCols: ReadonlySet<string>): boolean;
-/** Evaluate a key-decidable `footprintWhere` on a read's pk cells — H-iii's ONE client-side
- *  non-engine evaluator, DELIBERATELY MINIMAL (the TS evaluation caveat on the router block
- *  comment): `simple` `=`/`!=` between a pk COLUMN and a same-primitive-type NON-NULL literal,
- *  composed under and/or. The empty AND — the compiler's vacuous-true emission for an exact
- *  unconstrained footprint root — evaluates `true` (load-bearing: whole-table footprints keep
- *  provable reads); the empty OR is vacuous-false. Returns `undefined` = NOT EVALUABLE for
- *  anything else (other ops, null on either side, cross-type comparisons, column-vs-column,
- *  literal-vs-literal, non-primitive cells, correlated subqueries) — the caller fails to the
- *  daemon. A non-evaluable node anywhere poisons the whole tree (no short-circuit past it):
- *  partial evaluation could otherwise claim a verdict the engine's semantics might contradict. */
-export declare function evalFootprintOnPk(cond: Condition, pkCells: ReadonlyMap<string, WireValue>): boolean | undefined;
+/** The namespaced ENGINE table backing wire `table` for room `sourceKey` (302 §2: `room_deck` ≠
+ *  `deck` — one authority per table). `@` appears in no schema table name — ENFORCED by
+ *  `createSchema`/`extendSchema`'s addTableMeta ban (packages/client/src/schema.ts), so the name
+ *  cannot collide with a real table. */
+export declare function roomEngineTable(table: string, sourceKey: string): string;
+/** Rename every TABLE reference in a query AST through `map` (302 §2 point 3 — the room-homed
+ *  view's rewrite): the root `table`, every `related` subquery, every `correlatedSubquery`
+ *  (EXISTS) condition — walking the KNOWN wire-AST shape, never a blind key scan: `start.row` is
+ *  keyed by COLUMN name (a schema column literally named `table` must keep its bound value), and
+ *  the same goes for any future column-keyed record. Tables absent from the map keep their name —
+ *  that is the client-side join across kinds (a room table joined to daemon-owned context,
+ *  201-style). Structural clone; the input AST is never mutated. */
+export declare function remapAstTables(ast: Ast, map: ReadonlyMap<string, string>): Ast;
 //# sourceMappingURL=backend.d.ts.map