@rindle/optimistic 0.5.0 → 0.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/backend.js CHANGED
@@ -58,8 +58,8 @@ const REAL_CLOCK = {
58
58
  now: () => Date.now(),
59
59
  };
60
60
  /** The (shared, frozen-by-convention) empty map {@link OptimisticBackend.roomTablesFor} answers
61
- * for a room with no promoted tables. */
62
- const EMPTY_ROUTING = new Map();
61
+ * for a room with no registered tables. */
62
+ const EMPTY_ROOM_TABLES = new Map();
63
63
  /** Per-domain retention cap for the processed-outcome set (H-v) — mirrors the shell's
64
64
  * `MAX_RECORDED_OUTCOMES_PER_CLIENT`: the sender caps what it can re-answer at 512 per client,
65
65
  * so remembering more than 512 processed mids per domain buys nothing. */
@@ -149,15 +149,23 @@ export class OptimisticBackend {
149
149
  * an evicted mid would be re-processed — the same bounded-window trade the shell makes, and it
150
150
  * takes 512 interleaving non-applied outcomes on one domain to open it. */
151
151
  outcomesProcessed = new Map();
152
- /** THE routing table (H-iii §3): per connected room `sourceKey` → per promoted table → its
153
- * client-held {@link RoomTableRouting}. Written ONLY by {@link promoteRoomTable} (same breath
154
- * as the engine attach + {@link promotedTables}); read by {@link deriveDomain} and — via
155
- * {@link roomTablesFor} the client's `__realtimeInspect` bookkeeping. */
156
- roomRouting = new Map();
157
- /** Q6 counters ({@link RoutingInspect}): successful derivations per room. */
158
- routingDerived = new Map();
159
- /** Q6 counters ({@link RoutingInspect}): derivation failures per {@link RoutingFailureReason}. */
160
- routingReasons = new Map();
152
+ /** THE room-table registry (302 §2 — one source per table): per connected room `sourceKey`, the
153
+ * wire-table engine-table map for the tables that room OWNS (its writable scope). Written by
154
+ * {@link registerRoomTables} (same breath as the engine registration); read by the gate's
155
+ * release rename/filter, the mutator staging map, the view swap ({@link processSwapIns}), and
156
+ * the client's `__realtimeInspect` bookkeeping. The record outlives a downgrade's disconnect —
157
+ * the ghost's views still read the engine tables — and drops at {@link dropGhost} (or the last
158
+ * clean release via {@link unregisterRoomTables}). */
159
+ roomTables = new Map();
160
+ /** Local view qids currently REGISTERED on a room's namespaced tables (302 §4 swap-in), →
161
+ * their sourceKey. Set by {@link processSwapIns}; cleared by the swap-back ({@link dropGhost})
162
+ * and view teardown. The original AST stays in {@link asts} throughout — the swap re-registers
163
+ * only the ENGINE query. */
164
+ roomSwappedViews = new Map();
165
+ /** Room subs whose FIRST snapshot released in the current release — their views swap onto the
166
+ * room tables at the release tail ({@link processSwapIns}), strictly AFTER the reconcile folded
167
+ * the snapshot into those tables (swapping earlier would hydrate the view EMPTY, a flash). */
168
+ pendingSwapIns = new Set();
161
169
  /** The live fold entries, by fold key `${name}\0${identityJSON}` — at most one per key
162
170
  * (FOLDED-MUTATIONS-DESIGN §8). Insertion order is creation order (the drain/flush tiebreak). */
163
171
  folds = new Map();
@@ -180,45 +188,6 @@ export class OptimisticBackend {
180
188
  * scalars (`__inspect`) read it directly; its `sync` IS {@link sync} (the agg overlay and
181
189
  * synthetic tables are daemon-tracked by design). */
182
190
  daemonGate;
183
- /** Tables promoted to a MERGED multi-source engine (a room source attached). Written by the one
184
- * promotion seam ({@link promoteRoomTable}; the test-named {@link __addRoomSource} and Slice
185
- * G-v's lease-driven promotion from `RoomTableSpec[]` both flow through it). Read by the §7.3
186
- * hold-back trigger in
187
- * {@link applyRelease}: parking on a never-promoted (Collapsed) table is SKIPPED — inert anyway
188
- * today (`rewind_collapsed` never consults `held_back`), and a live hazard if the table later
189
- * promotes (a stale Collapsed-era entry turns overlay-first-visible and pins forever). Slice H's
190
- * prove-or-slow-path routing keeps the real scenario — a room-confirmed mutation writing a
191
- * Collapsed table — impossible; this gate covers the window until then. */
192
- promotedTables = new Set();
193
- /** The §301 pin registry ({@link EchoFencePin}): every parked §7.3 hold-back's delivery-fence
194
- * inputs, keyed `${table}\0${sourceKey}\0${pkKey}`. Written in the same breath as the
195
- * `holdBack`/`holdBackAbsent` park; read by {@link dropEchoFencePins} at the tail of every
196
- * release. Empty on every single-domain client — the drop pass is then a structural no-op. */
197
- pins = new Map();
198
- /** The §301 direction-A fence input: per room domain, the highest lmid the DAEMON-CARRIED
199
- * ledger rows have folded ({@link foldSystemFrames} step 2 — and ONLY that path: the room
200
- * socket's own lmid stream confirms long before the flush reaches the daemon, so it folds
201
- * into the shared {@link watermark} but never here, 301 §1.1). When this covers a pin's mid,
202
- * the same coherent release (or an earlier one) folded the flush data that carried it into
203
- * the daemon baseline — the fence. */
204
- daemonCarriedLmid = new Map();
205
- /** The §301 §2.4 boot rule's inputs: the daemon boot ids this client has OBSERVED, in order
206
- * (id → ordinal), plus the current one. Boot ids are opaque — ordering is the client's own
207
- * observation ({@link OptimisticSource.onBootId} on the daemon gate). Direction-B pins stamp
208
- * the current boot; a room advertising a LATER-observed boot proves absorption (its
209
- * re-snapshot came from a daemon state that durably includes the confirmed write). */
210
- daemonBootOrdinals = new Map();
211
- daemonBootId;
212
- /** The per-read provenance probe `invoke` hands `trackingTx` when recording is armed (H-ii,
213
- * §3.2 #3): the engine's `provenanceOf` — the VISIBLE overlay-first winner for the row's pk,
214
- * read from LIVE pre-commit state (an open txn's staged writes are not consulted; H-i). Gated
215
- * on PER-TABLE {@link promotedTables} membership — the cheapest existing signal, and the
216
- * correct one: provenance is an ENGINE-merge question, not a channel question ({@link gates}
217
- * can hold a connected-but-unpromoted room feed, and the oracle harness promotes with no gate),
218
- * and a never-promoted (Collapsed) table is daemon-owned by construction. So a pure
219
- * single-domain app pays ZERO wasm calls per recorded read; the recorded `source` is then
220
- * `undefined`, which is also correct — everything is daemon-owned (see {@link ReadRecord}). */
221
- readProvenance = (table, row) => this.promotedTables.has(table) ? this.local.provenanceOf(table, row) : undefined;
222
191
  // --- the §4 lifecycle SYSTEM-STREAM plane (Slice I-iii) --------------------------------
223
192
  /** System retains by source qid ({@link retainSystemQuery}): a subscription with NO store view
224
193
  * and NO user-visible table — its frames buffer on its gate exactly like {@link LMID_QID}'s and
@@ -334,13 +303,6 @@ export class OptimisticBackend {
334
303
  source.onNormalized((qid, ev) => this.onFrame(gate, qid, ev));
335
304
  source.onProgress((frame) => this.onGateProgress(gate, frame));
336
305
  source.onRestart?.(() => this.resetGate(gate));
337
- // §301 §2.4: the DAEMON channel's observed boot-id stream seeds the client-local boot
338
- // ordinals the direction-B fence's boot rule compares against (boot ids are opaque; order is
339
- // the client's own observation). Only the daemon gate's boots matter — a room's advertised
340
- // `upstreamBoot` names a DAEMON boot, and room-channel incarnations are handled by
341
- // `resetGate`. Optional: an in-process source never reports one.
342
- if (key === "daemon")
343
- source.onBootId?.((bootId) => this.observeDaemonBoot(bootId));
344
306
  // The deopt handshake's client half (H-v §3.3): the channel's `mutationOutcome` frames arrive
345
307
  // as `(domain = gate.key, frame)`. OUT-OF-BAND — the source dispatches on arrival and this
346
308
  // handler runs immediately, NEVER behind the gate's cv buffer: a deopt must migrate its entry
@@ -372,7 +334,52 @@ export class OptimisticBackend {
372
334
  if (this.gates.has(sourceKey)) {
373
335
  throw new Error(`optimistic backend: source ${sourceKey} is already connected`);
374
336
  }
375
- this.attachGate(sourceKey, source, new NormalizedSync(this.pkCols, this.colCounts));
337
+ const gate = this.attachGate(sourceKey, source, new NormalizedSync(this.pkCols, this.colCounts));
338
+ // A re-upgrade of a doc whose tables are still registered (a ghost that never dropped, or a
339
+ // quick down/up bounce) adopts the surviving record as this incarnation's rename map.
340
+ const tables = this.roomTables.get(sourceKey);
341
+ if (tables !== undefined)
342
+ gate.tableMap = tables;
343
+ // …and CANCELS the pending swap-back: the room is the authority again, its views stay swapped,
344
+ // and a ghost left armed would fire against this LIVE gate when the old fence clears —
345
+ // un-swapping the views and unregistering the namespaced tables the gate's tableMap still
346
+ // renames deltas into (the next release would then throw from serverBatchBegin and poison the
347
+ // rebase state). A future downgrade arms a fresh ghost with its own fence.
348
+ this.ghosts.delete(sourceKey);
349
+ }
350
+ /** Register the tables room `sourceKey` OWNS (its writable scope — 302 §2): each wire table
351
+ * gets its own namespaced ENGINE table (`{@link roomEngineTable}`), an ordinary tracked table
352
+ * whose sole authority is the room channel. From here on the channel's released deltas rename
353
+ * into these tables (wire tables outside the map are DROPPED — context stays daemon-owned,
354
+ * 302 §6), room-domain mutators stage onto them, and a room-homed view swaps onto them once
355
+ * the room sub hydrates ({@link processSwapIns}). Idempotent per (sourceKey, table); a wire
356
+ * table unknown to the schema is skipped (nothing to hold rows for). */
357
+ registerRoomTables(sourceKey, tables) {
358
+ if (sourceKey === "daemon") {
359
+ throw new Error("optimistic backend: the daemon is not a room — no namespaced tables");
360
+ }
361
+ let map = this.roomTables.get(sourceKey);
362
+ if (!map)
363
+ this.roomTables.set(sourceKey, (map = new Map()));
364
+ for (const table of tables) {
365
+ if (map.has(table))
366
+ continue;
367
+ const spec = this.specs[table];
368
+ if (spec === undefined || this.localTables.has(table))
369
+ continue;
370
+ const engineTable = roomEngineTable(table, sourceKey);
371
+ this.local.registerTable(engineTable, { columns: spec.columns, primaryKey: spec.primaryKey });
372
+ map.set(table, engineTable);
373
+ }
374
+ const gate = this.gates.get(sourceKey);
375
+ if (gate !== undefined)
376
+ gate.tableMap = map;
377
+ }
378
+ /** The wire-table → engine-table map for room `sourceKey`'s owned tables (empty when none) —
379
+ * the client's idempotence check and `__realtimeInspect` read THIS record (one source of
380
+ * truth; the client keeps no shadow copy). */
381
+ roomTablesFor(sourceKey) {
382
+ return this.roomTables.get(sourceKey) ?? EMPTY_ROOM_TABLES;
376
383
  }
377
384
  // --- the Backend seam ---------------------------------------------------------
378
385
  /** `channel` (G-iii registration-time routing) names the authority channel the remote sub
@@ -410,7 +417,7 @@ export class OptimisticBackend {
410
417
  // child is left a native reduce (L1) — `rewriteAggregates`/`ensureSyntheticTables` skip it.
411
418
  this.ensureSyntheticTables(qid, ast);
412
419
  // Local first (synchronous empty view), then the server stream hydrates it.
413
- this.local.registerQuery(qid, rewriteAggregates(ast, (t) => this.localTables.has(t)));
420
+ this.local.registerQuery(qid, this.plainEngineAst(ast));
414
421
  if (remote) {
415
422
  // A remote query is `unknown` until its first server snapshot lands (hydration); retainRemote
416
423
  // attaches it to the sub and sets the lifecycle against the sub's hydration state.
@@ -484,6 +491,7 @@ export class OptimisticBackend {
484
491
  this.source.expectClientSchema?.([...this.clientTablesBase, ...this.synthetic.values()]);
485
492
  }
486
493
  unregisterQuery(qid) {
494
+ this.roomSwappedViews.delete(qid); // a swapped view's teardown forgets its room backing
487
495
  const remoteQid = this.releaseRemote(qid);
488
496
  // GC: rows this remote footprint SOLELY referenced fall to refcount 0 → net removes. A qid
489
497
  // lives on ONE channel, so at most one gate's dropQuery is non-empty (dropQuery of an
@@ -493,7 +501,7 @@ export class OptimisticBackend {
493
501
  this.pendingRetargetGc.delete(remoteQid); // the sweep below covers a mid-retarget teardown
494
502
  for (const gate of this.gates.values()) {
495
503
  gate.buffer = gate.buffer.filter((f) => f.qid !== remoteQid);
496
- const gc = gate.sync.dropQuery(remoteQid);
504
+ const gc = mapGateDeltas(gate, gate.sync.dropQuery(remoteQid));
497
505
  if (gc.length)
498
506
  gcs.push([gate.key, gc]);
499
507
  }
@@ -545,7 +553,7 @@ export class OptimisticBackend {
545
553
  // Per-gate sweep, like `unregisterQuery`: at most one gate owned this qid's frames/rows.
546
554
  for (const gate of this.gates.values()) {
547
555
  gate.buffer = gate.buffer.filter((f) => f.qid !== remoteQid);
548
- const gc = gate.sync.dropQuery(remoteQid);
556
+ const gc = mapGateDeltas(gate, gate.sync.dropQuery(remoteQid));
549
557
  if (gc.length)
550
558
  this.runReconcileCycle(gate.key, gc);
551
559
  }
@@ -568,17 +576,15 @@ export class OptimisticBackend {
568
576
  * precedent), flip `sub.channel`, re-arm `sub.hydrated` (the room's own snapshot is the
569
577
  * cutover point), and register on the room source (its resolver presents the handed
570
578
  * roomToken). The old gate's SYNC rows are deliberately NOT dropped: they keep the view's
571
- * rows visible through the window (merge: the daemon-tier holder). Local views keep their
572
- * `hydrated` membership the view stays `complete` on its authoritative daemon rows.
573
- * 2. AT THE ROOM'S FIRST RELEASED SNAPSHOT ({@link flushRetargetGc}): the room source now
574
- * holds the footprint rows (folded via `serverBatchBegin(sourceKey)` value-equal rows
575
- * re-hydrate as a net-zero diff, RT §3.4 per channel), so the deferred
576
- * `dropQuery`+reconcile on the OLD gate flips each pk's winner daemon→room value-equal:
577
- * net-zero again. No emission carries a disappearance at any point.
579
+ * plain tables populated through the window the view still reads them until the swap.
580
+ * 2. AT THE ROOM'S FIRST RELEASED SNAPSHOT: the reconcile folds the snapshot into the room's
581
+ * namespaced tables, the release tail SWAPS every local view onto them (302 §4.1,
582
+ * {@link processSwapIns} the accepted-flash boundary), and {@link flushRetargetGc}'s
583
+ * deferred `dropQuery`+reconcile on the OLD gate then GCs the plain-table rows the sub
584
+ * alone referenced invisible to the swapped views.
578
585
  *
579
586
  * Idempotent per target channel: a sub already on `sourceKey` returns immediately (the
580
- * double-doorbell / re-entrancy guard — one retarget per (query, sourceKey), mirroring
581
- * {@link promoteRoomTable}'s caller-side per-(sourceKey, table) idempotence). Validates before
587
+ * double-doorbell / re-entrancy guard — one retarget per (query, sourceKey)). Validates before
582
588
  * mutating: a throw here leaves the sub fully daemon-attached (the client's fail-open). */
583
589
  retargetRemoteQuery(remote, sourceKey) {
584
590
  const newGate = this.requireGate(sourceKey); // throw loudly BEFORE any sub state moves
@@ -621,41 +627,30 @@ export class OptimisticBackend {
621
627
  const oldGate = this.gates.get(oldGateKey);
622
628
  if (!oldGate)
623
629
  continue;
624
- const gc = oldGate.sync.dropQuery(sourceQid);
630
+ const gc = mapGateDeltas(oldGate, oldGate.sync.dropQuery(sourceQid));
625
631
  if (gc.length)
626
632
  this.runReconcileCycle(oldGateKey, gc);
627
633
  }
628
634
  }
629
635
  // --- the §4.2 downgrade: demote → ghost → fence → drop (Slice I-v) ----------------------
630
- /** The I-v downgrade orchestration primitive (§4.2/§7.4): retire room `sourceKey` behind the
631
- * watermark fence. The caller has ALREADY retargeted every live sub off the channel
632
- * ({@link retargetRemoteQuery} room→daemon — validated loudly below) and holds the fence from
633
- * the api-server's downgrade response (`finalFlushSeq` = the room's last COMMITTED flush seq;
634
- * `doc` keys the §4.2 watermark fold, {@link roomWatermarks}). Steps, in order:
636
+ /** The I-v downgrade orchestration primitive (§4.2/§7.4, re-expressed by 302 §4.2 as the
637
+ * SWAP-BACK GATE): retire room `sourceKey` behind the watermark fence. The caller has ALREADY
638
+ * retargeted every live sub off the channel ({@link retargetRemoteQuery} room→daemon —
639
+ * validated loudly below) and holds the fence from the api-server's downgrade response
640
+ * (`finalFlushSeq` = the room's last COMMITTED flush seq; `doc` keys the §4.2 watermark fold,
641
+ * {@link roomWatermarks}). Steps, in order:
635
642
  *
636
- * 1. **De-candidacy NOW**: the sourceKey's {@link roomRouting} entries are removed, so
637
- * {@link deriveDomain} stops proposing the room (zero candidates ⇒ `"daemon"`). Unsent
638
- * pending (`mid === null`) re-routes for free — a fold's flush re-derives from the live
639
- * candidate set (§7.5 rule 1). The engine's frozen scope still ANSWERS (`writableMatches`
640
- * / `provenanceOf` — freezing gates serving, not the scope definition); routing is
641
- * TS-gated here.
642
- * 2. **Freeze** the WRITABLE promoted tables (`freezeSource`): the room slice becomes the
643
- * §4.2 ghost — wins-if-present in the merge (D4), so its rows (at-or-ahead of the daemon
644
- * until the flush echoes) stay visible while the slice accepts nothing. Context tables
645
- * (`writable: false`) are deliberately NOT frozen: the daemon is authoritative for them
646
- * LIVE (§5.2's context tier) and freezing would invert that, pinning a possibly-BEHIND
647
- * relayed copy over fresher daemon rows; unfrozen they keep exactly the live tiering.
648
- * 3. **Disconnect** the channel ({@link disconnectSource}): handlers detached, gate + buffer
643
+ * 1. **Disconnect** the channel ({@link disconnectSource}): handlers detached, gate + buffer
649
644
  * dropped. `nextMid`/`watermark`/processed-outcomes for the domain are KEPT FOREVER (§7.1:
650
645
  * an assigned mid pins its domain; a later re-upgrade of the same doc continues the
651
646
  * sequence — {@link connectSource} attaches a fresh gate and the lmid snapshot max-folds
652
647
  * into the surviving watermark). Disconnecting BEFORE the daemon sub's first release is
653
648
  * load-bearing: it makes {@link flushRetargetGc}'s deferred old-channel GC a no-op (gate
654
- * gone ⇒ record deleted, nothing dropped) running that GC would rewind the room slice's
655
- * rows at daemon hydration, i.e. BEFORE the fence, surfacing a lagging follower's stale
656
- * images (the exact regression §4.2 exists to prevent). The ghost's rows leave only
657
- * through {@link dropGhost}'s `removeRoomSource`, value-equal under the fence.
658
- * 4. **Ghost + first evaluation**: the record joins {@link ghosts} and is evaluated once
649
+ * gone ⇒ record deleted, nothing dropped). The room's namespaced tables and the views
650
+ * swapped onto them deliberately stay: frozen at the room's last state, they keep the
651
+ * document visible while the falling-back follower may still lack the final flush.
652
+ * Swapping back earlier would show its pre-flush images the regression §4.2 prevents.
653
+ * 2. **Ghost + first evaluation**: the record joins {@link ghosts} and is evaluated once
659
654
  * immediately — `finalFlushSeq === 0` (a never-flushed room) with no room-domain pending
660
655
  * drops on the spot, the single-daemon first-frame case.
661
656
  *
@@ -667,8 +662,6 @@ export class OptimisticBackend {
667
662
  if (sourceKey === "daemon") {
668
663
  throw new Error("optimistic backend: the daemon source cannot be demoted");
669
664
  }
670
- if (this.ghosts.has(sourceKey))
671
- return; // idempotent — one ghost per source
672
665
  // Validate FIRST (nothing mutated yet): a live sub still on the channel would silently
673
666
  // starve once the gate detaches — the caller must retarget every sub off the room first.
674
667
  for (const sub of this.remoteSubs.values()) {
@@ -676,14 +669,22 @@ export class OptimisticBackend {
676
669
  throw new Error(`optimistic backend: cannot demote ${JSON.stringify(sourceKey)} — query "${sub.remote.name}" is still retained on it (retarget it to the daemon first)`);
677
670
  }
678
671
  }
679
- const routing = this.roomRouting.get(sourceKey);
680
- const tables = routing ? [...routing.keys()] : [];
681
- const writable = routing ? tables.filter((t) => routing.get(t).writable) : [];
682
- this.roomRouting.delete(sourceKey); // (1) de-candidacy
683
- for (const table of writable)
684
- this.local.freezeSource(table, sourceKey); // (2) the ghost
685
- this.disconnectSource(sourceKey); // (3) the channel
686
- this.ghosts.set(sourceKey, { doc, finalFlushSeq, tables, stuckReported: false }); // (4)
672
+ // Idempotent per sourceKey (co-tenant queries sharing the room demote into the existing
673
+ // ghost) but NEVER a bare early-return: each demote carries its own fence, so keep the
674
+ // NEWEST flush (monotone max swapping back on an older fence would show pre-flush images),
675
+ // and disconnect defensively in case a gate re-attached since the ghost was armed (a
676
+ // down→up→down bounce; {@link connectSource} cancels the ghost on re-upgrade, so this arm
677
+ // normally finds no gate — but a stale gate left connected would let the next daemon release
678
+ // GC the room slice out from under the still-swapped views, the §4.2 regression).
679
+ const existing = this.ghosts.get(sourceKey);
680
+ if (existing) {
681
+ this.disconnectSource(sourceKey);
682
+ existing.finalFlushSeq = Math.max(existing.finalFlushSeq, finalFlushSeq);
683
+ this.evaluateGhosts();
684
+ return;
685
+ }
686
+ this.disconnectSource(sourceKey); // (1) the channel
687
+ this.ghosts.set(sourceKey, { doc, finalFlushSeq, stuckReported: false }); // (2)
687
688
  this.evaluateGhosts();
688
689
  }
689
690
  /** Detach one connected room channel (Slice I-v step 3): the source's handlers are replaced
@@ -729,6 +730,11 @@ export class OptimisticBackend {
729
730
  if (this.ghosts.size === 0)
730
731
  return; // every non-downgrade release: structural no-op
731
732
  for (const [sourceKey, ghost] of [...this.ghosts]) {
733
+ // A LIVE gate means the doc re-upgraded — dropping now would dismantle the live room
734
+ // (un-swap its views, unregister the tables its tableMap renames into). connectSource
735
+ // cancels the ghost on re-upgrade, so this guard is purely defensive; hold, never drop.
736
+ if (this.gates.has(sourceKey))
737
+ continue;
732
738
  if ((this.roomWatermarks.get(ghost.doc) ?? 0) < ghost.finalFlushSeq)
733
739
  continue; // fence holds
734
740
  const stuck = this.pendingMutations.filter((p) => p.domain === sourceKey && p.mid !== null);
@@ -739,52 +745,50 @@ export class OptimisticBackend {
739
745
  }
740
746
  continue; // hold — never a timeout-retire (§7.5 rule 2)
741
747
  }
742
- this.dropGhost(sourceKey, ghost);
743
- }
744
- }
745
- /** Drop one cleared ghost (§4.2 end state): detach every promoted table's room source (D2
746
- * stay-merged `removeRoomSource` reconciles each held pk to daemon-or-vanish, value-equal
747
- * under the fence, so visually a no-op), release the {@link promotedTables} record for tables
748
- * no OTHER room/ghost still holds, then run ONE daemon reconcile so entries whose writes had
749
- * staged onto the ghost slice re-invoke and re-stage by provenance onto the daemon slice (the
750
- * removal took their staged copies with the tree; provenance now answers daemon). The whole
751
- * drop runs under one commit boundary so the removal's compensating deltas and the re-staged
752
- * predictions notify as ONE step. After this, a FUTURE upgrade of the same doc promotes
753
- * again from scratch the round trip is pinned by the §8.5 lanes. */
754
- dropGhost(sourceKey, ghost) {
748
+ this.dropGhost(sourceKey);
749
+ }
750
+ }
751
+ /** Drop one cleared ghost — the 302 §4.2 SWAP-BACK: under the fence the daemon tables are
752
+ * value-equal-or-ahead of the room's final state, so (1) every view swapped onto the room's
753
+ * namespaced tables re-registers on its ORIGINAL (daemon-table) AST — visually a no-op, the
754
+ * Store folds the re-hello as an in-place reset; (2) the namespaced tables unregister (no
755
+ * reader is left after the swap); (3) ONE daemon reconcile re-invokes the pending set so any
756
+ * entry whose writes had staged onto the now-gone room tables re-stages onto the daemon tables
757
+ * (its domain policy stopped naming the dead room when the client dropped it). The whole drop
758
+ * runs under one commit boundary so the swap and the re-staged predictions notify as ONE step.
759
+ * After this, a FUTURE upgrade of the same doc registers again from scratch. */
760
+ dropGhost(sourceKey) {
755
761
  this.ghosts.delete(sourceKey);
756
- // Re-stage eligibility FIRST: a pending entry staged (only) on the ghost slice must join the
757
- // daemon reconcile below (the cycle filter is `touchedSources.has(sourceKey)`) — union, never
758
- // shrink, the §5.3 rule.
759
- let restage = false;
760
- for (const p of this.pendingMutations) {
761
- if (p.touchedSources.has(sourceKey)) {
762
- p.touchedSources.add("daemon");
763
- restage = true;
764
- }
765
- }
766
762
  this.inOneCommit(() => {
767
- for (const table of ghost.tables)
768
- this.local.removeRoomSource(table, sourceKey);
769
- for (const table of ghost.tables) {
770
- let held = false;
771
- for (const byTable of this.roomRouting.values())
772
- if (byTable.has(table))
773
- held = true;
774
- for (const g of this.ghosts.values())
775
- if (g.tables.includes(table))
776
- held = true;
777
- if (!held)
778
- this.promotedTables.delete(table);
763
+ for (const [qid, key] of [...this.roomSwappedViews]) {
764
+ if (key !== sourceKey)
765
+ continue;
766
+ this.roomSwappedViews.delete(qid);
767
+ const ast = this.asts.get(qid);
768
+ if (ast === undefined)
769
+ continue;
770
+ this.local.unregisterQuery(qid);
771
+ this.local.registerQuery(qid, this.plainEngineAst(ast));
779
772
  }
780
- // One daemon reconcile replays the re-staged entries onto the daemon slice. Run whenever
781
- // any pending exists: the removal above may have taken a staged write with the tree even
782
- // when `touchedSources` never recorded the ghost (defensive; an empty-pending drop skips).
783
- if (restage || this.pendingMutations.length > 0)
773
+ this.unregisterRoomTables(sourceKey);
774
+ // One daemon reconcile re-stages the pending set onto the surviving tables. Run whenever
775
+ // any pending exists: unregistering the room tables took their staged copies with the tree.
776
+ if (this.pendingMutations.length > 0)
784
777
  this.runReconcileCycle("daemon", []);
785
778
  });
786
779
  this.refreshPending(); // the reconcile may have dropped a throwing re-invocation
787
780
  }
781
+ /** Unregister room `sourceKey`'s namespaced engine tables and drop the {@link roomTables}
782
+ * record. Callers must have no view registered on them (the engine refuses otherwise —
783
+ * loud by design). No-op for an unknown sourceKey. */
784
+ unregisterRoomTables(sourceKey) {
785
+ const map = this.roomTables.get(sourceKey);
786
+ if (!map)
787
+ return;
788
+ this.roomTables.delete(sourceKey);
789
+ for (const engineTable of map.values())
790
+ this.local.unregisterTable(engineTable);
791
+ }
788
792
  // --- the §4 lifecycle SYSTEM-STREAM retains (Slice I-iii) ------------------------------
789
793
  /** Retain one minted SYSTEM subscription (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §4, Slice
790
794
  * I-iii): a wire sub with NO store view and NO user-visible table. Registered through the same
@@ -932,201 +936,58 @@ export class OptimisticBackend {
932
936
  this.nextMid.set(domain, mid + 1);
933
937
  return { mid, seq: ++this.dealSeq };
934
938
  }
935
- // --- the §3 prove-or-slow-path ROUTER (H-iii) -----------------------------------
936
- //
937
- // RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §3: a mutation routes to room R iff every row its
938
- // prediction run WROTE is provably inside R's writable scope and every read it RECORDED is
939
- // provably covered by R's footprint — ANY unproven condition routes slow (the §0 asymmetry:
940
- // mis-guessing "slow" costs one round-trip; mis-guessing "room" would commit divergent data).
941
- // Failure is therefore SILENT "daemon" — never a throw, never a warning per call — plus the Q6
942
- // per-reason counters ({@link RoutingInspect}).
943
- //
944
- // The proof evaluates against the ENGINE wherever the engine has an answer: `writableMatches`
945
- // (the registered compiled writable scope — the same predicate the merge's winner tiering uses)
946
- // and `provenanceOf` (the visible overlay-first winner). It runs AFTER the prediction committed,
947
- // so the probes see the prediction's own staged effects — which only ever strengthens the
948
- // conservative direction (a fresh pk reports "daemon"/undefined and neither disqualifies).
949
- //
950
- // ** THE ONE CLIENT-SIDE NON-ENGINE EVALUATOR — deliberately minimal (the TS evaluation
951
- // caveat). ** Evaluating `footprintWhere` on a read's pk cells ({@link evalFootprintOnPk}) is
952
- // the single place Slice H allows a non-engine evaluator, and it is restricted to STRICT cell
953
- // equality only: `simple` `=` / `!=` between a pk column and a same-primitive-type non-null
954
- // literal, composed under and/or (the empty AND is the vacuous-true exact-unconstrained-root
955
- // emission and evaluates true). ANY other op or shape — LIKE, <, >=, IS, IN, null operands,
956
- // cross-type comparisons, column-vs-column — is NOT EVALUABLE and fails to the daemon.
957
- // Justification: a mis-evaluation here cannot commit divergence — the room GATE (H-iv) re-proves
958
- // every write and absent read engine-side at commit and deopts, so a wrong client verdict only
959
- // costs a wasted hop (route room → gate deopt) or a skipped optimization (route daemon); and
960
- // restricting to strict equality on non-null, same-typed pk cells removes the entire
961
- // null/collation/coercion divergence space between this evaluator and the engine's comparators.
962
- // The gate remains the contract; this router is the optimization.
939
+ // --- the DECLARED router (302 §5: declared, not derived) --------------------------------
963
940
  //
964
- // ** H-v (SHIPPED the router's missing recovery half). ** A derived (or pinned) room route
965
- // whose gate DEOPTS (the H-iv-b `mutationOutcome {kind:"deopt"}` frame the mid is burnt in
966
- // the room ledger, no effects committed) is re-enqueued onto the daemon stream by
967
- // {@link handleMutationOutcome}: the entry flips in place (fresh daemon mid, ORIGINAL seq,
968
- // prediction applied throughout), or already retired re-invokes from the frame's echoed
969
- // name/args pinned to the daemon. A reconnect re-sends unconfirmed mids so a frame lost with
970
- // its socket is re-answered ({@link resendPending}). A wrong client verdict therefore costs
971
- // exactly one room round-trip plus one burnt room-mid (§3.3), never a stranded prediction.
972
- /** The route decision for one invocation (invoke, and again at fold flush): the explicit
973
- * `domainPolicy` is the OVERRIDE a string pins that domain verbatim, no proof runs;
974
- * `undefined` (or no policy configured) derives per §3. */
975
- resolveDomain(name, args, writes, reads) {
976
- const pinned = this.domainPolicy(name, args);
977
- if (pinned !== undefined)
978
- return pinned;
979
- return this.deriveDomain(writes, reads);
980
- }
981
- /** §9.3: does this fold's write-set route into a room (vs the daemon)? Used ONLY to pick the
982
- * {@link FoldOptions.roomDebounceMs} cadence at a fold window's start. It probes
983
- * {@link resolveDomain} but RESTORES the Q6 routing diagnostics afterward — the authoritative
984
- * route and its single counter bump belong to the flush ({@link flushFold}), not to this
985
- * interval hint. A fold's reads are provably empty (the read-trap arms on that path), so the
986
- * write-set alone decides. */
987
- routesToRoom(name, args, writes) {
988
- const reasons = [...this.routingReasons];
989
- const derived = [...this.routingDerived];
990
- const domain = this.resolveDomain(name, args, writes, { reads: [], queries: [] });
991
- this.routingReasons.clear();
992
- for (const [k, v] of reasons)
993
- this.routingReasons.set(k, v);
994
- this.routingDerived.clear();
995
- for (const [k, v] of derived)
996
- this.routingDerived.set(k, v);
997
- return domain !== "daemon";
998
- }
999
- /** Count one derivation failure ({@link RoutingInspect}). Returns `false` so the per-candidate
1000
- * proof's call sites read `return this.failDerivation(...)`. */
1001
- failDerivation(reason) {
1002
- this.routingReasons.set(reason, (this.routingReasons.get(reason) ?? 0) + 1);
1003
- return false;
1004
- }
1005
- /** The §3 derivation. Candidates are the connected room gates with at least one promoted table
1006
- * (a promoted table with no gate cannot confirm; a gate with no promoted table holds no data to
1007
- * prove against). Zero candidates `"daemon"` (the single-domain fast path). The proof runs
1008
- * per candidate and EXACTLY ONE must survive — two rooms both proving routes slow (principled
1009
- * disambiguation is a §9.2 multi-room NON-goal, deferred past Slice J; slow is always sound). */
1010
- deriveDomain(writes, reads) {
1011
- const candidates = [];
1012
- for (const key of this.gates.keys()) {
1013
- if (key === "daemon")
1014
- continue;
1015
- if ((this.roomRouting.get(key)?.size ?? 0) > 0)
1016
- candidates.push(key);
1017
- }
1018
- if (candidates.length === 0) {
1019
- this.failDerivation("no-candidates");
1020
- return "daemon";
1021
- }
1022
- // tx.query is not room-executable client-side: predicate containment (rindle-cover) is
1023
- // native-only BY DESIGN, so a declarative read fails the WHOLE derivation unconditionally.
1024
- // This is required, not conservative.
1025
- if (reads.queries.length > 0) {
1026
- this.failDerivation("tx-query");
1027
- return "daemon";
1028
- }
1029
- const proven = candidates.filter((room) => this.provesRoom(room, writes, reads));
1030
- if (proven.length === 1) {
1031
- const room = proven[0];
1032
- this.routingDerived.set(room, (this.routingDerived.get(room) ?? 0) + 1);
1033
- return room;
1034
- }
1035
- if (proven.length > 1)
1036
- this.failDerivation("ambiguous");
1037
- return "daemon"; // zero survivors: each candidate already counted its own failure reason
1038
- }
1039
- /** One candidate room's §3 proof over the captured write-set + read-log. Every write must pass
1040
- * ALL the write rules; every read must pass ONE of the read rules. First failure wins (and is
1041
- * counted); order is deterministic (write-set map order, then read-log order). */
1042
- provesRoom(room, writes, reads) {
1043
- const specs = this.roomRouting.get(room);
1044
- // --- write rules: every WriteRecord passes ALL of #1–#4 -------------------------------
1045
- for (const [table, byPk] of writes) {
1046
- // #1: the table is promoted for R with a writable (predicate-kind) spec. A context table
1047
- // (`writable: none`), an un-promoted table, and a local table (unreachable — the mutator
1048
- // guard refuses local writes at stage time) all fail here.
1049
- const spec = specs?.get(table);
1050
- if (spec === undefined || !spec.writable)
1051
- return this.failDerivation("write-unwritable-table");
1052
- const colIx = this.colIndex[table];
1053
- for (const rec of byPk.values()) {
1054
- const removeShape = rec.row === undefined;
1055
- // #2: the registered writable scope, evaluated BY THE ENGINE on the post-image for
1056
- // add/edit shapes and on the pre-image for removes (the row the room would delete). A
1057
- // remove record always carries its full-width pre-image (the H-ii capture contract);
1058
- // a violated contract fails closed rather than probing nothing.
1059
- const scopeRow = removeShape ? rec.oldRow : rec.row;
1060
- if (scopeRow === undefined || !this.local.writableMatches(table, room, scopeRow)) {
1061
- return this.failDerivation("write-scope-miss");
1062
- }
1063
- // #3: join-key no-change. An edit-shape (row + oldRow — the oldRow is the txn-entry base)
1064
- // must keep every joinKeyCols cell STRICTLY identical old-vs-new; an add-shape may SET
1065
- // them (it creates the correlation); removes are exempt. A join-key column missing from
1066
- // the schema is a spec bug — fail closed.
1067
- if (!removeShape && rec.oldRow !== undefined) {
1068
- for (const col of spec.joinKeyCols) {
1069
- const i = colIx?.get(col);
1070
- if (i === undefined || !identicalCell(rec.oldRow[i], rec.row[i])) {
1071
- return this.failDerivation("write-join-key-change");
1072
- }
1073
- }
1074
- }
1075
- // #4: provenance corroboration — the engine routes an Edit by its OLD row (H-i), so probe
1076
- // the pre-image for edit/remove shapes and the post-image for add-shapes. A winner naming
1077
- // a DIFFERENT room disqualifies; "daemon"/undefined does NOT (a thin slice, or a fresh pk
1078
- // — fresh pks stage to the daemon slice by the E2 decision, kept permanently: the
1079
- // room-side authoritative run is the committing execution either way).
1080
- const probeRow = rec.oldRow ?? rec.row;
1081
- if (probeRow !== undefined) {
1082
- const src = this.local.provenanceOf(table, probeRow);
1083
- if (src !== undefined && src !== "daemon" && src !== room) {
1084
- return this.failDerivation("write-cross-room-provenance");
1085
- }
1086
- }
1087
- }
1088
- }
1089
- // --- read rules: every ReadRecord passes ONE ------------------------------------------
1090
- // (tx.query already failed the whole derivation in deriveDomain — never reaches here.)
1091
- for (const r of reads.reads) {
1092
- // Self-read: the pk is in THIS invocation's write-set for that table — the write rules
1093
- // above already judged it (covers the keyed writers' probe-then-write shape). NOTE the
1094
- // read-log reflects the ORIGINAL invoke only (the pre-existing capture caveat).
1095
- if (writes.get(r.table)?.has(stableJson(r.pk)))
1096
- continue;
1097
- if (r.source !== undefined) {
1098
- if (r.source === room)
1099
- continue; // the room served the row — in-footprint by construction
1100
- if (r.source !== "daemon")
1101
- return this.failDerivation("read-cross-room");
1102
- }
1103
- // Present-with-daemon/undefined source, or ABSENT (source is never recorded for those —
1104
- // including the un-promoted-table meaning of an absent key): the footprint-membership test
1105
- // on the PK ALONE. R's footprintWhere must exist, be key-decidable (every column it reads is
1106
- // a pk column), and evaluate TRUE on the read's pk cells:
1107
- // present-daemon + TRUE ⇒ the row is in the room's COMPLETE footprint ⇒ covered;
1108
- // absent + TRUE ⇒ absent-in-room = absent-in-truth ⇒ covered;
1109
- // FALSE (either outcome) ⇒ fail — present-daemon-FALSE means the room lacks the row;
1110
- // absent-FALSE is arguably provable (decidably-outside ⇒ the room never sees the pk)
1111
- // but the room-side run would then read absent for a DIFFERENT reason than truth's —
1112
- // stay CONSERVATIVE and fail;
1113
- // no footprintWhere / not key-decidable / not evaluable ⇒ fail (see the evaluator caveat
1114
- // on the router block comment).
1115
- const fw = specs?.get(r.table)?.footprintWhere;
1116
- if (fw === undefined)
1117
- return this.failDerivation("read-no-footprint-where");
1118
- const tspec = this.specs[r.table];
1119
- const pkCols = tspec.primaryKey.map((i) => tspec.columns[i]);
1120
- if (!keyDecidable(fw, new Set(pkCols)))
1121
- return this.failDerivation("read-not-key-decidable");
1122
- const pkCells = new Map(pkCols.map((c, j) => [c, r.pk[j]]));
1123
- const verdict = evalFootprintOnPk(fw, pkCells);
1124
- if (verdict === undefined)
1125
- return this.failDerivation("read-not-evaluable");
1126
- if (!verdict)
1127
- return this.failDerivation("read-outside-footprint");
1128
- }
1129
- return true;
941
+ // The user declares which mutators are room mutators; the client neither proves, derives,
942
+ // widens, nor falls back. The declaration reaches this backend as `domainPolicy` the client
943
+ // layer resolves (mutator name, args) against its declared realtime mutators and the currently
944
+ // attached rooms. A misdeclaration fails SOFT (302 §5.1): a daemon-declared mutator touching
945
+ // room-visible data stages onto the daemon tables while the room-homed view reads the room
946
+ // tables no optimistic feedback until the echo relays it a hop later, never a divergence.
947
+ // The room GATE stays the authoritative backstop: a room-routed mutation the room refuses comes
948
+ // back as a `mutationOutcome` deopt/reject frame and the H-v machinery below re-enqueues or
949
+ // surfaces it.
950
+ /** The declared confirming stream for one invocation: the `domainPolicy`'s verdict, `"daemon"`
951
+ * when it abstains. Resolved BEFORE the prediction runs — the domain picks the staging map
952
+ * (a room domain stages its owned tables onto the room's namespaced twins). */
953
+ resolveDomain(name, args) {
954
+ return this.domainPolicy(name, args) ?? "daemon";
955
+ }
956
+ /** The staging table map for a `domain`-routed prediction ({@link trackingTx}'s `stage`):
957
+ * wire table → the room's namespaced engine table for the tables the room owns; identity for
958
+ * everything else (including the whole map for the daemon domain). */
959
+ stagingMap(domain) {
960
+ return domain === "daemon" ? undefined : this.roomTables.get(domain);
961
+ }
962
+ /** The PLAIN (daemon-homed) engine AST for `ast` aggregate relationships rewritten to their
963
+ * synthetic `__agg_*` reads, no room renames. The ONE form every non-swapped engine
964
+ * registration uses ({@link registerQuery}, {@link dropGhost}'s swap-back) and the base the
965
+ * swap-in renames ({@link processSwapIns}). */
966
+ plainEngineAst(ast) {
967
+ return rewriteAggregates(ast, (t) => this.localTables.has(t));
968
+ }
969
+ /** Mutator names the cross-authority warn below already fired for (once per name). */
970
+ warnedCrossAuthority = new Set();
971
+ /** 302 §5.1 dev-time guard: a room-DECLARED mutator wrote tables the room does not own. Those
972
+ * writes staged onto the PLAIN daemon tables (the staging map covers only owned tables), but
973
+ * the entry confirms on the ROOM stream — and only the room's OWNED tables flush back to the
974
+ * daemon, so nothing upstream ever echoes them: once the room confirm retires the entry, the
975
+ * next release's whole-store rewind reverts them for good. The first-party room shell refuses
976
+ * such a mutation (the §3.3 deopt/reject backstop re-routes it to the daemon), so this warns
977
+ * for the shapes where that backstop may be absent (a BYO relay) — loud, once, soft (§5.1:
978
+ * misdeclarations never throw). */
979
+ warnCrossAuthorityWrites(name, domain, touched) {
980
+ if (domain === "daemon" || this.warnedCrossAuthority.has(name))
981
+ return;
982
+ const map = this.roomTables.get(domain);
983
+ const staged = new Set(map?.values() ?? []);
984
+ const outside = [...touched].filter((t) => !staged.has(t));
985
+ if (outside.length === 0)
986
+ return;
987
+ this.warnedCrossAuthority.add(name);
988
+ console.warn(`[rindle] room mutator "${name}" wrote table(s) ${outside.join(", ")} that room ${JSON.stringify(domain)} does not own` +
989
+ ` (owned: ${map !== undefined && map.size > 0 ? [...map.keys()].join(", ") : "none"}) — these writes rely on the room` +
990
+ ` shell's deopt backstop and revert after the room confirm if the shell applies the mutation anyway (302 §5.1).`);
1130
991
  }
1131
992
  /** Run the named client mutator optimistically: the prediction applies to the live
1132
993
  * engine now (affected views update synchronously), `(mid, name, args)` joins the
@@ -1147,43 +1008,33 @@ export class OptimisticBackend {
1147
1008
  // One commit boundary spans the prediction AND the `__agg`-head reconcile below, so their views
1148
1009
  // (data + count) flush together rather than tearing across two engine commits.
1149
1010
  return this.inOneCommit(() => {
1150
- // Apply the prediction FIRST. If the mutator throws (client-side validation, a bad read),
1011
+ // The confirming stream is DECLARED (302 §5), so it resolves BEFORE the prediction: the
1012
+ // domain picks the staging map — a room-domain mutator's writes to the room's owned tables
1013
+ // land on the namespaced engine twins the room-homed views read. An H-v deopt re-invocation
1014
+ // pins via `pin` and the policy never runs.
1015
+ const domain = pin ?? this.resolveDomain(name, args);
1016
+ // Apply the prediction. If the mutator throws (client-side validation, a bad read),
1151
1017
  // the staged write is discarded (the wasm txn is a clean no-op until commit) and the throw
1152
1018
  // propagates with NO mid consumed — a burnt mid is a permanent server-side gap that
1153
1019
  // silently refuses every later mutation from this client (#10).
1154
1020
  const writes = new Map();
1155
1021
  const reads = { reads: [], queries: [] };
1156
1022
  const ops = [];
1157
- // Per-staged-write source keys (staged order), zipped with the `commitTracked` `sources[]`
1158
- // below to learn which physical source each pk routed onto (§5.3 filter + §7.3 hold-back).
1159
- const stagedKeys = [];
1160
- const sources = this.local.writeWith((tx) => {
1161
- this.runMutator(mutator,
1162
- // `readProvenance` rides only with recording (H-ii §3.2 #3): the folded path (trap, no
1163
- // readLog) and the reconcile replay (no readLog) never probe — see trackingTx.
1164
- trackingTx(tx, writes, this.specs, this.localTables, this.opCollector(ops), false, reads, stagedKeys, this.readProvenance), args);
1023
+ this.local.writeWith((tx) => {
1024
+ this.runMutator(mutator, trackingTx(tx, writes, this.specs, this.localTables, this.opCollector(ops), false, reads, this.stagingMap(domain)), args);
1165
1025
  });
1166
1026
  // `touched` is DERIVED, never separately populated (§3.2 #1) — see {@link WriteSet}.
1167
1027
  const touched = new Set(writes.keys());
1028
+ this.warnCrossAuthorityWrites(name, domain, touched);
1168
1029
  // Flush-on-enqueue (§4.2): a fold whose tables overlap this write must take its mid NOW, BEFORE
1169
1030
  // this write does, so wire order == local-apply order for any pair that can observe each other
1170
1031
  // (a read-dependent write reading a folded cell sees the same value optimistically and on the
1171
1032
  // wire — no snap). Drained folds ship with smaller mids; this write's mid is dealt after.
1172
1033
  this.drainOverlapping(touched);
1173
- // The confirming stream (§7.1): its ledger deals the mid and its watermark alone retires the
1174
- // entry. THE §3 ROUTER RUNS HERE (H-iii)after the prediction (write/read capture is
1175
- // complete, and the engine holds the committed prediction the probes read) and BEFORE the
1176
- // mid is dealt: an assigned mid pins its domain forever (§7.1) — a re-invocation never
1177
- // re-routes. An explicit `domainPolicy` string pins verbatim (no proof); an H-v deopt
1178
- // re-invocation pins via `pin` (see {@link invokeWith}) and the router never runs.
1179
- const domain = pin ?? this.resolveDomain(name, args, writes, reads);
1034
+ // The confirming stream's ledger deals the mid and its watermark alone retires the entry
1035
+ // (§7.1). An assigned mid pins its domain forever a re-invocation never re-routes.
1180
1036
  const { mid, seq } = this.dealMid(domain);
1181
- // The write-source axes (§5.3): which physical source each write staged onto. All `"daemon"`
1182
- // in single-domain (Collapsed) — so the filter and hold-back below are inert on the live path.
1183
- const touchedSources = new Set(sources);
1184
- const writeSources = new Map();
1185
- mergeWriteSources(writeSources, stagedKeys, sources);
1186
- this.pendingMutations.push({ mid, seq, name, args, domain, touched, writes, reads, touchedSources, writeSources });
1037
+ this.pendingMutations.push({ mid, seq, name, args, domain, touched, writes, reads });
1187
1038
  // The prediction stuck — fold its child ops into the optimistic agg delta and push it onto
1188
1039
  // the `__agg` head rows (§4). No reset here (this is the §1.3 trivial case, no rewind): the
1189
1040
  // delta accumulates on top of the prior pending set, and `reconcileAggHead` recomputes each
@@ -1207,6 +1058,9 @@ export class OptimisticBackend {
1207
1058
  const foldKey = `${name}\0${stableJson(opts.key)}`;
1208
1059
  // One commit boundary spans the prediction AND the `__agg`-head reconcile (see {@link inOneCommit}),
1209
1060
  // so a folded mutation's list view and count view flush together, never torn across two commits.
1061
+ // The declared domain (302 §5) — resolved up front, like `invoke`'s: it picks the staging
1062
+ // map, the §9.3 cadence, and the provisional confirming stream (the flush re-resolves).
1063
+ const domain = this.resolveDomain(name, args);
1210
1064
  return this.inOneCommit(() => {
1211
1065
  // Apply the prediction with the read trap armed (§5): a folded mutator that reads state to
1212
1066
  // compute its write is non-absorbing and refused. A throw discards the staged write (clean
@@ -1214,11 +1068,9 @@ export class OptimisticBackend {
1214
1068
  // path stays byte-for-byte as it was; recording (§3.2 #2) never arms alongside the trap.
1215
1069
  const writes = new Map();
1216
1070
  const ops = [];
1217
- const stagedKeys = [];
1218
- let sources = [];
1219
1071
  try {
1220
- sources = this.local.writeWith((tx) => {
1221
- this.runMutator(mutator, trackingTx(tx, writes, this.specs, this.localTables, this.opCollector(ops), true, undefined, stagedKeys), args);
1072
+ this.local.writeWith((tx) => {
1073
+ this.runMutator(mutator, trackingTx(tx, writes, this.specs, this.localTables, this.opCollector(ops), true, undefined, this.stagingMap(domain)), args);
1222
1074
  });
1223
1075
  }
1224
1076
  catch (e) {
@@ -1232,38 +1084,31 @@ export class OptimisticBackend {
1232
1084
  this.reconcileAggHead();
1233
1085
  // `touched` is DERIVED, never separately populated (§3.2 #1) — see {@link WriteSet}.
1234
1086
  const touched = new Set(writes.keys());
1235
- // The write-source axes (§5.3), like `touched`/`writes` — REPLACED wholesale on an in-place
1236
- // fold overwrite (the latest invocation supersedes, absorbing), initialized on a new entry.
1237
- const touchedSources = new Set(sources);
1238
- const writeSources = new Map();
1239
- mergeWriteSources(writeSources, stagedKeys, sources);
1087
+ this.warnCrossAuthorityWrites(name, domain, touched);
1240
1088
  const now = this.clock.now();
1241
1089
  let f = this.folds.get(foldKey);
1242
1090
  if (f) {
1243
1091
  // Overwrite the single entry in place — the pending stack does NOT grow (§1 #2). The head
1244
1092
  // already carries this new prediction (absorbing, last-wins on the cell); the entry holds
1245
1093
  // only the LATEST args, which is what a rebase re-derives from and what the flush ships.
1094
+ // `domain` too: THIS invocation staged through the freshly-resolved domain's map above, so
1095
+ // a mid-window rebase must re-stage through the same one (the flush re-resolves anyway;
1096
+ // no mid is pinned yet — `entry.mid` is null until flush).
1246
1097
  f.entry.args = args;
1247
1098
  f.entry.touched = touched;
1248
1099
  f.entry.writes = writes;
1249
- f.entry.touchedSources = touchedSources;
1250
- f.entry.writeSources = writeSources;
1100
+ f.entry.domain = domain;
1251
1101
  f.args = args;
1252
1102
  this.clock.clearTimeout(f.timer);
1253
1103
  }
1254
1104
  else {
1255
- // Provisional domain (§7.1): re-resolved from the final args/write-set at flush, when the
1256
- // mid is dealt. Never read before then — an un-flushed fold (`mid == null`) is
1257
- // unconditionally retained — so the full (counting) derivation deliberately does NOT run
1258
- // here (it would double-bump the Q6 counters for one logical route); the flush derives.
1259
- const domain = this.domainPolicy(name, args) ?? "daemon";
1260
1105
  // §9.3: pick the window's cadence. Routing into a room ⇒ flush at roomDebounceMs so
1261
1106
  // intermediates stream to the shared head; off the room, the caller's collapse debounce
1262
- // governs. The probe restores the Q6 diagnostics (the flush owns the authoritative bump).
1263
- const inRoom = opts.roomDebounceMs !== undefined && this.routesToRoom(name, args, writes);
1107
+ // governs.
1108
+ const inRoom = opts.roomDebounceMs !== undefined && domain !== "daemon";
1264
1109
  const debounceMs = inRoom ? opts.roomDebounceMs : opts.debounceMs ?? DEFAULT_FOLD_DEBOUNCE_MS;
1265
1110
  const maxWaitMs = inRoom ? opts.roomDebounceMs : opts.maxWaitMs;
1266
- const entry = { mid: null, seq: null, name, args, domain, touched, writes, reads: { reads: [], queries: [] }, touchedSources, writeSources };
1111
+ const entry = { mid: null, seq: null, name, args, domain, touched, writes, reads: { reads: [], queries: [] } };
1267
1112
  this.pendingMutations.push(entry);
1268
1113
  let resolveMid;
1269
1114
  const midPromise = new Promise((res) => (resolveMid = res));
@@ -1315,13 +1160,11 @@ export class OptimisticBackend {
1315
1160
  return;
1316
1161
  this.clock.clearTimeout(f.timer);
1317
1162
  this.folds.delete(foldKey);
1318
- // Resolve the confirming stream from the FINAL args (§7.1) and deal the mid from that domain's
1319
- // ledger — SEND order, never reserved, so gapless within the domain. Under H-iii derivation
1320
- // this RE-DERIVES from the entry's LATEST write-set (each in-place fold overwrite replaced it,
1321
- // so it reflects the final absorbed value): same §3 rules minus reads — a fold's read-set is
1322
- // provably empty by construction (the FoldReadError trap, not recording, arms on that path),
1323
- // which is the STRONGEST read proof there is. The mid dealt below then pins this domain.
1324
- const domain = this.resolveDomain(f.entry.name, f.args, f.entry.writes, f.entry.reads);
1163
+ // Re-resolve the DECLARED confirming stream from the FINAL args (§7.1) and deal the mid from
1164
+ // that domain's ledger — SEND order, never reserved, so gapless within the domain. The mid
1165
+ // dealt below then pins this domain. (A domain that changed since the window opened a room
1166
+ // attached or dropped mid-window re-stages on the next reconcile's re-invocation.)
1167
+ const domain = this.resolveDomain(f.entry.name, f.args);
1325
1168
  f.entry.domain = domain;
1326
1169
  const { mid, seq } = this.dealMid(domain);
1327
1170
  f.entry.mid = mid;
@@ -1433,8 +1276,7 @@ export class OptimisticBackend {
1433
1276
  }, frame.reason ?? "mutation rejected");
1434
1277
  return;
1435
1278
  }
1436
- // kind === "deopt": Q6's completion how often a routed mutation came back refused.
1437
- this.routingReasons.set("deopt", (this.routingReasons.get("deopt") ?? 0) + 1);
1279
+ // kind === "deopt": the room gate refused a declared-room mutation re-enqueue onto the daemon.
1438
1280
  const entry = this.pendingMutations.find((p) => p.domain === domain && p.mid === frame.mid);
1439
1281
  if (entry) {
1440
1282
  entry.domain = "daemon";
@@ -1617,37 +1459,14 @@ export class OptimisticBackend {
1617
1459
  return {
1618
1460
  nextMid: Object.fromEntries(this.nextMid),
1619
1461
  watermark: Object.fromEntries(this.watermark),
1620
- gates: Object.fromEntries([...this.gates].map(([k, g]) => [
1621
- k,
1622
- {
1623
- appliedCv: g.appliedCv,
1624
- bufferedFrames: g.buffer.length,
1625
- ...(g.upstreamCv !== undefined ? { upstreamCv: g.upstreamCv } : {}),
1626
- ...(g.upstreamBoot !== undefined ? { upstreamBoot: g.upstreamBoot } : {}),
1627
- },
1628
- ])),
1629
- routing: {
1630
- derived: Object.fromEntries(this.routingDerived),
1631
- reasons: Object.fromEntries(this.routingReasons),
1632
- },
1462
+ gates: Object.fromEntries([...this.gates].map(([k, g]) => [k, { appliedCv: g.appliedCv, bufferedFrames: g.buffer.length }])),
1463
+ roomTables: Object.fromEntries([...this.roomTables].map(([k, m]) => [k, Object.fromEntries(m)])),
1464
+ swappedViews: Object.fromEntries(this.roomSwappedViews),
1633
1465
  lifecycle: {
1634
1466
  roomWatermarks: Object.fromEntries(this.roomWatermarks),
1635
1467
  scopeSessions: Object.fromEntries([...this.scopeSessions].map(([scope, sessions]) => [scope, Object.fromEntries(sessions)])),
1636
- ghosts: Object.fromEntries([...this.ghosts].map(([k, g]) => [k, { doc: g.doc, finalFlushSeq: g.finalFlushSeq, tables: [...g.tables] }])),
1468
+ ghosts: Object.fromEntries([...this.ghosts].map(([k, g]) => [k, { doc: g.doc, finalFlushSeq: g.finalFlushSeq }])),
1637
1469
  },
1638
- pins: Object.fromEntries([...this.pins].map(([k, p]) => [
1639
- k,
1640
- {
1641
- table: p.table,
1642
- sourceKey: p.sourceKey,
1643
- domain: p.domain,
1644
- mid: p.mid,
1645
- ...(p.daemonBoot !== undefined ? { daemonBoot: p.daemonBoot } : {}),
1646
- ...(p.daemonCv !== undefined ? { daemonCv: p.daemonCv } : {}),
1647
- tripwired: p.tripwired === true,
1648
- },
1649
- ])),
1650
- daemonCarriedLmid: Object.fromEntries(this.daemonCarriedLmid),
1651
1470
  pending: this.pendingMutations.map((p) => ({
1652
1471
  mid: p.mid,
1653
1472
  // The client-global deal sequence — the REPLAY order (mids are per-domain, incomparable
@@ -1655,11 +1474,6 @@ export class OptimisticBackend {
1655
1474
  seq: p.seq,
1656
1475
  name: p.name,
1657
1476
  domain: p.domain,
1658
- // The write-source axes (§5.3): which physical source(s) this entry's writes routed onto —
1659
- // the filter basis, and (per pk) the hold-back's cross-slice test. The harness asserts the
1660
- // filter/routing against its independent model with these.
1661
- touchedSources: [...p.touchedSources],
1662
- writeSources: Object.fromEntries(p.writeSources),
1663
1477
  })),
1664
1478
  };
1665
1479
  }
@@ -1761,16 +1575,6 @@ export class OptimisticBackend {
1761
1575
  * delta, lmid → watermark) and {@link applyRelease} (per-source confirm-drop + reconcile) —
1762
1576
  * N independent gates all feed the ONE apply half; {@link __testRelease} drives it directly. */
1763
1577
  onGateProgress(gate, frame) {
1764
- // §301 direction B: record the frame's upstream-absorption advert BEFORE the release applies,
1765
- // so the drop pass at applyRelease's tail evaluates exactly this release's advert — the room
1766
- // emits data-then-progress on one socket, so by the time the advert says "absorbed through
1767
- // cv U" the re-published echo data is in this release's fold (never ahead of it). Verbatim,
1768
- // not max-folded: on a daemon restart the advertised cv space legitimately resets and the
1769
- // §2.4 boot rule (not monotonicity) carries the ordering.
1770
- if (frame.upstreamCv !== undefined) {
1771
- gate.upstreamCv = frame.upstreamCv;
1772
- gate.upstreamBoot = frame.upstreamBoot;
1773
- }
1774
1578
  const { deltas, newlyHydrated, touchedScopes } = this.computeRelease(gate, frame);
1775
1579
  this.applyRelease(gate.key, deltas, undefined, newlyHydrated);
1776
1580
  // I-iv phase 2: a retargeted sub whose first ROOM snapshot released just now gets its old
@@ -1825,7 +1629,10 @@ export class OptimisticBackend {
1825
1629
  this.foldLmidOps(f.ops, gate.key);
1826
1630
  continue;
1827
1631
  }
1828
- muts.push(...(f.kind === "snapshot" ? gate.sync.rehydrate(f.qid, f.ops) : gate.sync.applyBatch(f.qid, f.ops)));
1632
+ // A ROOM gate's deltas rename into the room's namespaced tables — and a wire table outside
1633
+ // the registered map is DROPPED (302 §6: context comes from the daemon, one authority per
1634
+ // table; a room's relayed context copy must never enter the store).
1635
+ muts.push(...mapGateDeltas(gate, f.kind === "snapshot" ? gate.sync.rehydrate(f.qid, f.ops) : gate.sync.applyBatch(f.qid, f.ops)));
1829
1636
  // A query's first released snapshot is its hydration point — even an empty one (0 rows is an
1830
1637
  // authoritative answer): lift every local view this sub feeds out of `unknown` (loading).
1831
1638
  if (f.kind === "snapshot")
@@ -1850,44 +1657,6 @@ export class OptimisticBackend {
1850
1657
  if (watermarkUpdate !== undefined) {
1851
1658
  this.watermark.set(sourceKey, Math.max(this.watermark.get(sourceKey) ?? 0, watermarkUpdate));
1852
1659
  }
1853
- // Echo hold-back (§7.3), BEFORE the confirm-drop: an entry `p` this release CONFIRMS
1854
- // (`p.mid <= watermark[p.domain]`) but which staged a write onto a DIFFERENT source `S` (a
1855
- // cross-slice write — e.g. a room-domain mutation whose write routed to the daemon slice) is
1856
- // about to leave `pendingMutations`, so it will NOT be re-invoked on `S`'s next rewind. Park each
1857
- // such write inertly on `S` so that rewind (which un-applies the not-re-invoked write) does not
1858
- // flash-revert it. Two variants, one per write shape (G-i unified them engine-side):
1859
- // - ADD/EDIT (`rec.row` present): pinned PRESENCE — drops when `S`'s confirmed baseline
1860
- // value-matches (its echo lands — the E-i-tested drop).
1861
- // - REMOVE (`rec.row === undefined`, G-iii): pinned ABSENCE — the §7.3 tombstone, parked with
1862
- // the captured pre-image (`rec.oldRow`) so `S`'s rewind cannot resurrect the deleted row;
1863
- // drops when `S`'s baseline lacks the pk (the delete echoed).
1864
- // Inert in single-domain: every write's source equals its domain.
1865
- for (const p of this.pendingMutations) {
1866
- if (p.mid === null || p.mid > (this.watermark.get(p.domain) ?? 0))
1867
- continue; // not confirmed now
1868
- for (const [table, byPk] of p.writes) {
1869
- // The Collapsed-park gate (G-iii): NEVER park on an un-promoted table. Inert-anyway today
1870
- // (`rewind_collapsed` never consults `held_back`), so skipping is behaviorally identical —
1871
- // but a stale Collapsed-era entry would become overlay-first-visible (a permanent pin) if
1872
- // the table later promotes. Slice H's prove-or-slow-path routing makes the real scenario
1873
- // (a room-confirmed mutation writing a Collapsed table) impossible; this covers until then.
1874
- if (!this.promotedTables.has(table))
1875
- continue;
1876
- for (const [pkKey, rec] of byPk) {
1877
- const s = p.writeSources.get(writeSourceKey(table, pkKey));
1878
- if (s === undefined || s === p.domain)
1879
- continue; // same-slice: the rewind replays it
1880
- if (rec.row !== undefined)
1881
- this.local.holdBack(table, s, rec.row);
1882
- else if (rec.oldRow !== undefined)
1883
- this.local.holdBackAbsent(table, s, rec.oldRow);
1884
- else
1885
- continue;
1886
- // §301 §2.1: register the pin's delivery-fence inputs in the same breath as the park.
1887
- this.registerPin(table, s, pkKey, rec.row ?? rec.oldRow, p);
1888
- }
1889
- }
1890
- }
1891
1660
  // Drop confirmed pending (§1.3 step 5's bookkeeping half), PER DOMAIN: an entry is retired only
1892
1661
  // when ITS domain's watermark reaches its mid — so two concurrent streams never alias one counter
1893
1662
  // (§7.1). A failed mutation drops the same way (the release carries no effects, so the rewind snaps
@@ -1936,11 +1705,11 @@ export class OptimisticBackend {
1936
1705
  this.handler(qid, { type: "batch", events: [], catchUp: true });
1937
1706
  }
1938
1707
  this.refreshPending();
1939
- // The §301 echo-fence drop pass — strictly AFTER the reconcile above folded this release's
1940
- // data, so a fence that cleared in this release drops its pin only once the co-committed
1941
- // echo data is actually in the baseline (dropping earlier would itself reopen the flash
1942
- // window §7.3 closes). Structural no-op with no pins (every single-domain client).
1943
- this.dropEchoFencePins();
1708
+ // The 302 §4.1 swap-in — strictly AFTER the reconcile above folded this release's data, so a
1709
+ // room sub whose first snapshot just released swaps its views onto room tables that already
1710
+ // hold the snapshot (swapping earlier would hydrate them empty). Structural no-op with no
1711
+ // pending swap (every single-domain client).
1712
+ this.processSwapIns();
1944
1713
  // The I-v ghost-drop watcher (§4.2), LAST: this release's watermark rows have folded
1945
1714
  // (computeRelease) and its confirm-drop has retired what it covers — exactly the two inputs
1946
1715
  // the drop condition reads. Structural no-op with no ghost.
@@ -1954,151 +1723,49 @@ export class OptimisticBackend {
1954
1723
  __testRelease(sourceKey, deltas, watermarkUpdate) {
1955
1724
  this.applyRelease(sourceKey, deltas, watermarkUpdate);
1956
1725
  }
1957
- // --- the §301 echo fences (301-ECHO-FENCE-DESIGN.md) -----------------------------------
1958
- /** Register (or overwrite a later cross-slice confirm re-pinning the same slice-pk matches
1959
- * the engine's `held_back.insert`) one {@link EchoFencePin}, in the same breath as the
1960
- * engine park (§2.1). `p` is the confirmed entry whose write staged onto `sourceKey`; its
1961
- * `mid` is non-null by the caller's confirm filter. */
1962
- registerPin(table, sourceKey, pkKey, probeRow, p) {
1963
- const pin = {
1964
- table,
1965
- sourceKey,
1966
- probeRow,
1967
- domain: p.domain,
1968
- mid: p.mid,
1969
- };
1970
- if (sourceKey !== "daemon" && p.domain === "daemon") {
1971
- // Direction B stamps (§1.2): the parking daemon release's coherence position — the confirm
1972
- // folded at-or-before it, so a room advertising absorption ≥ this cv has absorbed the
1973
- // commit that carried the write — plus the client-observed boot it belongs to (§2.4).
1974
- pin.daemonCv = this.daemonGate.appliedCv;
1975
- if (this.daemonBootId !== undefined)
1976
- pin.daemonBoot = this.daemonBootId;
1977
- }
1978
- // The tripwire reference (§2.5): the slice's confirmed-baseline row at park.
1979
- pin.baselineAtPark = this.local.heldBackState(table, sourceKey, probeRow)?.baseline;
1980
- this.pins.set(`${table}\0${sourceKey}\0${pkKey}`, pin);
1981
- }
1982
- /** The §2.3 drop pass, run at the tail of every applied release: prune registry entries whose
1983
- * engine pin is already gone (the rewind's state-match fallback or a whole-source removal beat
1984
- * the fence — benign), drop every pin whose fence cleared (one engine drop each, delivered on
1985
- * the ordinary event stream, bracketed as ONE notification commit), and tripwire the rest. */
1986
- dropEchoFencePins() {
1987
- if (this.pins.size === 0)
1988
- return; // every single-domain client: structural no-op
1989
- let cleared = null;
1990
- for (const [key, pin] of this.pins) {
1991
- const state = this.local.heldBackState(pin.table, pin.sourceKey, pin.probeRow);
1992
- if (state === undefined) {
1993
- this.pins.delete(key); // engine pin gone (state-match / source removal): lazy prune
1994
- continue;
1995
- }
1996
- if (this.pinFenceCleared(pin))
1997
- (cleared ??= []).push([key, pin]);
1998
- else
1999
- this.maybeTripwirePin(key, pin, state.baseline);
2000
- }
2001
- if (!cleared)
2002
- return;
1726
+ // --- the 302 §4 swap-in ------------------------------------------------------------------
1727
+ /** Swap every view of each just-hydrated ROOM sub onto the room's namespaced tables (302 §4.1):
1728
+ * re-register the local engine query with the AST's room-owned table references renamed
1729
+ * ({@link remapAstTables}); the Store folds the re-hello as an in-place reset, so the caller's
1730
+ * view reference survives and subscribers see ONE transition. Runs at the applyRelease tail —
1731
+ * the reconcile has already folded the sub's snapshot into the room tables, so the swapped
1732
+ * view hydrates straight to the room state (swapping earlier would flash it empty). The
1733
+ * ORIGINAL ast stays in {@link asts}; the swap-back ({@link dropGhost}) re-registers it.
1734
+ *
1735
+ * This is the accepted-flash boundary (302 §4.1/§7.1): the room's copy may be behind the
1736
+ * daemon rows the view showed a moment ago — accepted by decision, revisit on a real
1737
+ * two-region deploy. */
1738
+ processSwapIns() {
1739
+ if (this.pendingSwapIns.size === 0)
1740
+ return; // every single-domain release: structural no-op
1741
+ const subs = [...this.pendingSwapIns];
1742
+ this.pendingSwapIns.clear();
2003
1743
  this.inOneCommit(() => {
2004
- for (const [key, pin] of cleared) {
2005
- this.pins.delete(key);
2006
- this.local.dropHeldBack(pin.table, pin.sourceKey, pin.probeRow);
1744
+ for (const sub of subs) {
1745
+ const map = this.roomTables.get(sub.channel);
1746
+ for (const qid of sub.localQids.keys()) {
1747
+ const ast = this.asts.get(qid);
1748
+ if (ast === undefined)
1749
+ continue;
1750
+ if (map === undefined || map.size === 0)
1751
+ continue; // no owned tables — nothing to swap
1752
+ if (this.roomSwappedViews.get(qid) === sub.channel)
1753
+ continue; // already swapped
1754
+ const rewritten = remapAstTables(this.plainEngineAst(ast), map);
1755
+ this.local.unregisterQuery(qid);
1756
+ this.local.registerQuery(qid, rewritten);
1757
+ this.roomSwappedViews.set(qid, sub.channel);
1758
+ // The pending axis follows the engine tables the view now reads (union — the wire
1759
+ // names stay too, conservatively: a daemon-declared write to a room-visible table is
1760
+ // still an honest "pending elsewhere" signal).
1761
+ const tables = this.queryTables.get(qid);
1762
+ if (tables)
1763
+ for (const t of map.values())
1764
+ tables.add(t);
1765
+ }
2007
1766
  }
2008
1767
  });
2009
1768
  }
2010
- /** Has `pin`'s delivery fence provably closed its confirm→echo window? (§2.3/§2.4.) */
2011
- pinFenceCleared(pin) {
2012
- if (pin.sourceKey === "daemon") {
2013
- // Direction A: the daemon-carried ledger for the confirming room domain covers the mid —
2014
- // the I-ii co-commit means this release (or an earlier one) folded the flush data that
2015
- // carried it into the daemon baseline (§1.1).
2016
- return (this.daemonCarriedLmid.get(pin.domain) ?? 0) >= pin.mid;
2017
- }
2018
- // Direction B: only a daemon-confirmed write has the daemon-cv stamp; a room-staged pin
2019
- // confirmed by ANOTHER room (outside today's two-tier topology) has no fence.
2020
- if (pin.daemonCv === undefined)
2021
- return false;
2022
- const gate = this.gates.get(pin.sourceKey);
2023
- if (!gate || gate.upstreamCv === undefined)
2024
- return false; // no advert (old shell): §2.5 fallback
2025
- if (gate.upstreamBoot === pin.daemonBoot)
2026
- return gate.upstreamCv >= pin.daemonCv;
2027
- // Boot mismatch (§2.4): a boot the client has OBSERVED as later proves absorption (the
2028
- // room's post-restart re-snapshot came from daemon state that durably includes the
2029
- // confirmed write); an unknown/older/unstamped boot holds — conservative, its next
2030
- // re-snapshot advances it.
2031
- if (pin.daemonBoot === undefined || gate.upstreamBoot === undefined)
2032
- return false;
2033
- const pinOrd = this.daemonBootOrdinals.get(pin.daemonBoot);
2034
- const advOrd = this.daemonBootOrdinals.get(gate.upstreamBoot);
2035
- return pinOrd !== undefined && advOrd !== undefined && advOrd > pinOrd;
2036
- }
2037
- /** The §2.5 stuck-pin tripwire, in the scopesHash spirit: log ONCE per pin when its slice's
2038
- * baseline row has CHANGED VALUE since park while the pin still holds — the suspicious state
2039
- * that precedes every forever-pin (a fence-less pairing, a fence bug). Never drops anything. */
2040
- maybeTripwirePin(key, pin, baseline) {
2041
- if (pin.tripwired)
2042
- return;
2043
- const same = pin.baselineAtPark === undefined || baseline === undefined
2044
- ? pin.baselineAtPark === baseline
2045
- : pin.baselineAtPark.length === baseline.length &&
2046
- pin.baselineAtPark.every((c, i) => identicalCell(c, baseline[i]));
2047
- if (same)
2048
- return;
2049
- pin.tripwired = true;
2050
- const [table, sourceKey, pkKey] = key.split("\0");
2051
- console.warn(`rindle: a §7.3 hold-back pin on table "${table}" slice "${sourceKey}" pk ${pkKey} (confirming domain ${pin.domain}, mid ${pin.mid}) is parked while its slice's baseline moved past it — if this client never converges on that row, this pin is why (301-ECHO-FENCE-DESIGN.md §2.5).`);
2052
- }
2053
- /** Record one observed daemon boot id (§2.4): first observation of an id assigns the next
2054
- * ordinal (the client's own total order over opaque boot ids); every call refreshes the
2055
- * current-boot stamp for direction-B parks. */
2056
- observeDaemonBoot(bootId) {
2057
- if (!this.daemonBootOrdinals.has(bootId)) {
2058
- this.daemonBootOrdinals.set(bootId, this.daemonBootOrdinals.size);
2059
- }
2060
- this.daemonBootId = bootId;
2061
- }
2062
- /** Promote `table` to a MERGED multi-source engine with room `sourceKey`'s per-row writable
2063
- * scope (RINDLE-REALTIME-QUERY-ENABLEMENT-DESIGN.md §5.2) — THE one promotion seam. The engine
2064
- * attach and the {@link promotedTables} record move in the same breath: the §7.3 hold-back
2065
- * trigger in {@link applyRelease} parks ONLY on promoted tables, so a promotion that bypassed
2066
- * the record would silently disable the echo hold-back for that table (and a record without the
2067
- * engine attach would park onto a slice that doesn't exist). Recorded AFTER the engine accepts —
2068
- * a rejected descriptor/table must not leave a phantom promotion. Slice G-v's client drives this
2069
- * from the lease's `realtime.tables` (`RoomTableSpec` → {@link WritableDescriptor}); idempotence
2070
- * per `(sourceKey, table)` is the CALLER's job (the engine refuses a duplicate room).
2071
- *
2072
- * `spec` (H-iii) is the per-table ROUTING spec riding the same lease table block — recorded
2073
- * into {@link roomRouting} (THE routing table the §3 router reads) in the same breath, with
2074
- * `writable` derived from the descriptor's kind (`none` = a context table the room may not
2075
- * write). Omitted (the E-iii-b harness alias below) ⇒ an empty spec: no join keys to guard, no
2076
- * `footprintWhere` (that room's reads then fail closed to the daemon unless self/room-served). */
2077
- promoteRoomTable(table, sourceKey, writable, spec) {
2078
- this.local.addRoomSource(table, sourceKey, writable);
2079
- this.promotedTables.add(table);
2080
- let byTable = this.roomRouting.get(sourceKey);
2081
- if (!byTable)
2082
- this.roomRouting.set(sourceKey, (byTable = new Map()));
2083
- byTable.set(table, {
2084
- writable: writable.kind !== "none",
2085
- joinKeyCols: [...(spec?.joinKeyCols ?? [])],
2086
- ...(spec?.where !== undefined ? { where: spec.where } : {}),
2087
- ...(spec?.footprintWhere !== undefined ? { footprintWhere: spec.footprintWhere } : {}),
2088
- });
2089
- }
2090
- /** The recorded routing specs for `sourceKey`'s promoted tables (table → its
2091
- * {@link RoomTableRouting}) — read-only: the client's `__realtimeInspect`/idempotence
2092
- * bookkeeping reads THIS record instead of keeping its own shadow copy (one source of truth).
2093
- * Empty map when the room has promoted nothing. */
2094
- roomTablesFor(sourceKey) {
2095
- return this.roomRouting.get(sourceKey) ?? EMPTY_ROUTING;
2096
- }
2097
- /** Test-named alias of {@link promoteRoomTable} (E-iii-b scaffolding — the multi-domain oracle
2098
- * and per-source-gate suites drive it). Pure delegation: ONE body, one `promotedTables` record. */
2099
- __addRoomSource(table, roomKey, writable, spec) {
2100
- this.promoteRoomTable(table, roomKey, writable, spec);
2101
- }
2102
1769
  /** Fold `domain`'s lmid system query's released ops (lmid-as-data): the one row's
2103
1770
  * `last_mutation_id` cell is this client's confirmed high-water mid in that domain — it advances
2104
1771
  * `watermark[domain]` and, on a fresh session ahead of our issued mids, `nextMid[domain]`. The
@@ -2232,16 +1899,7 @@ export class OptimisticBackend {
2232
1899
  continue;
2233
1900
  if (spec.doc !== undefined && doc !== spec.doc)
2234
1901
  continue;
2235
- const covered = Number(lmid);
2236
- this.foldConfirm(roomDomainKey(doc), covered);
2237
- // The §301 direction-A fence input: the DAEMON-CARRIED ledger fold ALONE (the room
2238
- // socket's own lmid stream confirms long before the flush reaches the daemon, so it
2239
- // folds the shared watermark above but never this map — 301 §1.1). Max-fold: ledger
2240
- // rows re-deliver across re-hydrates.
2241
- if (Number.isFinite(covered)) {
2242
- const dom = roomDomainKey(doc);
2243
- this.daemonCarriedLmid.set(dom, Math.max(this.daemonCarriedLmid.get(dom) ?? 0, covered));
2244
- }
1902
+ this.foldConfirm(roomDomainKey(doc), Number(lmid));
2245
1903
  }
2246
1904
  }
2247
1905
  // (3) watermark rows → the monotone §4.2 fence value per doc.
@@ -2327,40 +1985,36 @@ export class OptimisticBackend {
2327
1985
  * deliver the coalesced result (`serverBatchEnd`). This is the engine's only sync-moving
2328
1986
  * boundary — `onProgress` releases and `unregisterQuery`'s GC both go through here so head
2329
1987
  * and sync never diverge (the §1.2 invariant; CRIT#2). */
2330
- runReconcileCycle(sourceKey, serverDeltas) {
2331
- // `sourceKey` names the authority these `deltas` confirm — `"daemon"` on the live daemon path (and
2332
- // the GC path), a `room:doc:X` string on a per-source release (E-iii). It selects which physical
2333
- // source the wasm engine's rewind folds the delta into (`Db::serverBatchBegin`). The E-iii-b/c
2334
- // per-source rewind + intersecting-pending re-invoke filter ride the same seam later.
2335
- this.local.serverBatchBegin(sourceKey, serverDeltas.map(toServerOp));
2336
- // The aggregate overlay (§4) is DAEMON-tracked: its `__agg_*` tables are server-authoritative
2337
- // synthetic tables that only the daemon feed drives. A room cycle must not wipe or rebuild it
2338
- // (that would double-count / lose daemon agg state), so gate every overlay interaction reset,
2339
- // observe, and reconcileAggHead on the daemon cycle. Single-domain: always daemon unchanged.
2340
- const daemonCycle = sourceKey === "daemon";
2341
- if (daemonCycle) {
2342
- // The rewind cleared every optimistic write incl. prior `__agg` edits so head is now the
2343
- // server baseline. Rebuild the optimistic agg delta from scratch off the re-invoked
2344
- // (confirm-filtered) pending set, so a just-confirmed mutation's delta vanishes exactly as its
2345
- // server count is absorbed (§5 watermark no double count).
2346
- this.overlay.reset();
2347
- }
1988
+ runReconcileCycle(_sourceKey, serverDeltas) {
1989
+ // `_sourceKey` names the authority these `deltas` confirm — `"daemon"` on the live daemon
1990
+ // path (and the GC path), a `room:doc:X` string on a room release, whose deltas already carry
1991
+ // the room's ENGINE table names (the gate's rename/filter). Kept for call-site readability
1992
+ // and tracing only: the engine itself is source-agnostic (302: one authority per table) — its
1993
+ // rewind covers EVERY tracked table and every pending mutation re-invokes below regardless of
1994
+ // which channel released, so NOTHING in this cycle may branch on it.
1995
+ this.local.serverBatchBegin(serverDeltas.map(toServerOp));
1996
+ // The rewind covers EVERY tracked table (302: the engine is source-agnostic there is no
1997
+ // per-source rewind)including the `__agg_*` head rows whichever channel released. So the
1998
+ // optimistic agg delta rebuilds on EVERY cycle, room or daemon: reset here, re-observe from
1999
+ // the re-invoked pending set below, re-apply onto the rewound heads at the end. Gating any of
2000
+ // the three on a daemon-only cycle (the pre-302 per-source-rewind contract) would let a room
2001
+ // release wipe the optimistic `__agg` edits and skip the rebuild — every count() view snaps
2002
+ // back to the server base until the next daemon release. The delta stays sound across
2003
+ // domains: `reconcileAggHead` recomputes each head as the absolute `server_base ⊕ delta`,
2004
+ // and the server base (`this.sync`) only moves on daemon releases.
2005
+ this.overlay.reset();
2348
2006
  // Sort ALL pending into SEND order (the client-global `seq` ascending, then unflushed folds
2349
2007
  // last by creation order — the deterministic §4.1 slot; the comparator is explicit, NOT
2350
- // `(seq ?? ∞) - (seq ?? ∞)` which is `∞ - ∞ = NaN` and corrupts V8's sort), THEN FILTER to the
2351
- // writers of THIS source5.3): a per-source rewind un-applied ONLY that source's staged
2352
- // writes, so ONLY those must re-invoke the others' predictions are intact on their un-rewound
2353
- // trees. The key MUST be `seq`, never `mid`: mids are per-domain (§7.1) so mids from different
2354
- // domains are incomparable — a mid-sort would replay a room mid 1 before a daemon mid 5 that
2355
- // was sent FIRST, letting a read-dependent mutator re-predict from a base it never saw
2356
- // (confirmation order is per-domain; replay order is client-global). FILTERING the
2357
- // globally-ordered array preserves the relative send order among the subset (the 200 §4.1
2358
- // invariant); NEVER re-sort the subset. Single-domain: every entry has
2359
- // `touchedSources = {"daemon"}` and seq order == mid order (except H-v deopt re-enqueues,
2360
- // which keep their ORIGINAL seq under a later daemon mid — deliberately, so this very sort
2361
- // replays them at their original overlay position) ⇒ byte-identical to before.
2362
- const order = [...this.pendingMutations]
2363
- .sort((a, b) => {
2008
+ // `(seq ?? ∞) - (seq ?? ∞)` which is `∞ - ∞ = NaN` and corrupts V8's sort). The key MUST be
2009
+ // `seq`, never `mid`: mids are per-domain 7.1) so mids from different domains are
2010
+ // incomparable a mid-sort would replay a room mid 1 before a daemon mid 5 that was sent
2011
+ // FIRST, letting a read-dependent mutator re-predict from a base it never saw (confirmation
2012
+ // order is per-domain; replay order is client-global). EVERY entry re-invokes the engine's
2013
+ // rewind covers every tracked table (302: there is no per-source rewind), so every entry's
2014
+ // staged writes were just un-applied, whichever channel released. Single-domain: seq order ==
2015
+ // mid order (except H-v deopt re-enqueues, which keep their ORIGINAL seq under a later daemon
2016
+ // mid deliberately, so this very sort replays them at their original overlay position).
2017
+ const order = [...this.pendingMutations].sort((a, b) => {
2364
2018
  if (a.seq === null && b.seq === null)
2365
2019
  return 0; // both unflushed → stable creation order
2366
2020
  if (a.seq === null)
@@ -2368,20 +2022,19 @@ export class OptimisticBackend {
2368
2022
  if (b.seq === null)
2369
2023
  return -1;
2370
2024
  return a.seq - b.seq;
2371
- })
2372
- .filter((p) => p.touchedSources.has(sourceKey));
2025
+ });
2373
2026
  const dropped = new Set();
2374
2027
  try {
2375
2028
  for (const p of order) {
2376
2029
  // NO `readLog` here — recording is armed only on the initial `invoke` (§3.2 #2 note on
2377
2030
  // `PendingMutation.reads`); a re-invocation's write-set still needs fresh capture (below).
2031
+ // The staging map follows the entry's CURRENT domain — a deopt-flipped or re-routed entry
2032
+ // re-stages onto its new domain's tables here.
2378
2033
  const writes = new Map();
2379
2034
  const ops = [];
2380
- const stagedKeys = [];
2381
- let sources = [];
2382
2035
  try {
2383
- sources = this.local.writeWith((tx) => {
2384
- this.runMutator(this.registry[p.name], trackingTx(tx, writes, this.specs, this.localTables, this.opCollector(ops), false, undefined, stagedKeys), p.args);
2036
+ this.local.writeWith((tx) => {
2037
+ this.runMutator(this.registry[p.name], trackingTx(tx, writes, this.specs, this.localTables, this.opCollector(ops), false, undefined, this.stagingMap(p.domain)), p.args);
2385
2038
  });
2386
2039
  }
2387
2040
  catch {
@@ -2394,31 +2047,23 @@ export class OptimisticBackend {
2394
2047
  dropped.add(p);
2395
2048
  continue;
2396
2049
  }
2397
- // The re-invocation stuck — fold its child ops into the rebuilt optimistic agg delta (daemon
2398
- // cycle only a room cycle leaves the daemon-tracked overlay untouched).
2399
- if (daemonCycle)
2400
- for (const op of ops)
2401
- this.overlay.observe(op);
2050
+ // The re-invocation stuck — fold its child ops into the rebuilt optimistic agg delta.
2051
+ for (const op of ops)
2052
+ this.overlay.observe(op);
2402
2053
  // The pending footprint is the UNION across invocations: a re-run that no-ops (touched =
2403
2054
  // {}) must NOT shrink it, else a still-pending mutation reports not-pending and its
2404
- // pending-axis clear fires early (§7.2). `writes`/the source axes mirror this: merge, never
2405
- // replace. (A re-invocation may route differently, e.g. onto a source the room feed now
2406
- // holds — union so the filter still catches it on either source's next cycle.)
2055
+ // pending-axis clear fires early (§7.2). `writes` mirrors this: merge, never replace.
2407
2056
  for (const t of writes.keys())
2408
2057
  p.touched.add(t);
2409
2058
  mergeWriteSet(p.writes, writes);
2410
- for (const s of sources)
2411
- p.touchedSources.add(s);
2412
- mergeWriteSources(p.writeSources, stagedKeys, sources);
2413
2059
  }
2414
2060
  // Preserve creation order in the live array (the unflushed-fold sort tiebreak depends on it).
2415
2061
  if (dropped.size)
2416
2062
  this.pendingMutations = this.pendingMutations.filter((p) => !dropped.has(p));
2417
2063
  // Re-apply the optimistic agg delta onto the (rewound) `__agg` head rows — INSIDE the open
2418
2064
  // cycle, so the writes buffer and coalesce into the one per-query delivery `serverBatchEnd`
2419
- // makes (and never escape as a separate batch). Daemon cycle only (see above).
2420
- if (daemonCycle)
2421
- this.reconcileAggHead();
2065
+ // makes (and never escape as a separate batch). Every cycle (see the reset above).
2066
+ this.reconcileAggHead();
2422
2067
  }
2423
2068
  finally {
2424
2069
  this.local.serverBatchEnd(); // ALWAYS close the cycle — ONE delivery per affected query.
@@ -2435,10 +2080,6 @@ export class OptimisticBackend {
2435
2080
  resetGate(gate) {
2436
2081
  gate.buffer = [];
2437
2082
  gate.appliedCv = 0;
2438
- // The §301 upstream-absorption advert dies with the incarnation that made it — the fresh
2439
- // one re-advertises (direction-B pins conservatively hold until it does).
2440
- delete gate.upstreamBoot;
2441
- delete gate.upstreamCv;
2442
2083
  }
2443
2084
  /** The §8.5 escape: ONE gate's buffer outgrew its cap (a pinned `cvMin` under churn on that
2444
2085
  * channel). Drop everything it buffered and re-register every query on that source — the fresh
@@ -2472,8 +2113,10 @@ export class OptimisticBackend {
2472
2113
  this.setResultType(qid, this.hydrated.has(qid) ? "complete" : "unknown");
2473
2114
  }
2474
2115
  /** A remote sub's first snapshot landed: mark it (and every local view it feeds) hydrated, then
2475
- * lift those views out of `unknown` (loading). Idempotent a re-hydrate snapshot re-marks
2476
- * harmlessly; a source qid with no sub (the lmid system query) is a no-op. */
2116
+ * lift those views out of `unknown` (loading). A ROOM sub's hydration additionally queues the
2117
+ * 302 §4.1 swap-in performed at the applyRelease TAIL ({@link processSwapIns}), once the
2118
+ * reconcile has folded this snapshot into the room tables. Idempotent — a re-hydrate snapshot
2119
+ * re-marks harmlessly; a source qid with no sub (the lmid system query) is a no-op. */
2477
2120
  markSubHydrated(sourceQid) {
2478
2121
  const key = this.sourceToRemote.get(sourceQid);
2479
2122
  if (!key)
@@ -2482,6 +2125,8 @@ export class OptimisticBackend {
2482
2125
  if (!sub || sub.hydrated)
2483
2126
  return;
2484
2127
  sub.hydrated = true;
2128
+ if (sub.channel !== "daemon" && !this.systemQids.has(sub.sourceQid))
2129
+ this.pendingSwapIns.add(sub);
2485
2130
  for (const localQid of sub.localQids.keys()) {
2486
2131
  this.hydrated.add(localQid);
2487
2132
  this.recomputeResultType(localQid);
@@ -2512,11 +2157,32 @@ export class OptimisticBackend {
2512
2157
  // A late-joiner to an already-hydrated sub is immediately hydrated; otherwise this view now
2513
2158
  // awaits the sub's first snapshot (so a split-path local view registered `complete` flips to
2514
2159
  // `unknown` here). Then recompute its lifecycle.
2515
- if (sub.hydrated)
2160
+ if (sub.hydrated) {
2516
2161
  this.hydrated.add(localQueryId);
2517
- else
2162
+ // 302 §4.1 LATE JOIN: a ROOM sub's one-shot swap queue ({@link markSubHydrated}) fired at
2163
+ // its first released snapshot — long gone by now — so a view attaching afterwards must
2164
+ // swap onto the room's namespaced tables HERE, or its engine query stays registered on
2165
+ // the plain daemon tables the room channel never feeds (empty/stale, reported complete,
2166
+ // diverging from its already-swapped siblings forever). The room tables already hold the
2167
+ // released state (hydrated ⇒ folded), so swapping immediately is the ordinary
2168
+ // after-the-data order; processSwapIns skips already-swapped siblings, and
2169
+ // pendingSwapIns is empty outside a release, so exactly this sub's un-swapped views move.
2170
+ if (sub.channel !== "daemon" && !this.systemQids.has(sub.sourceQid)) {
2171
+ this.pendingSwapIns.add(sub);
2172
+ this.processSwapIns();
2173
+ }
2174
+ // FORCE the notify past setResultType's dedup: the labeled split registers the local
2175
+ // half `complete`, then flips the STORE view to `unknown` for the lease window WITHOUT
2176
+ // touching our record — so a complete→complete recompute here would swallow the event
2177
+ // and strand the late-joining view `unknown` forever. Redundant notifies are idempotent
2178
+ // Store-side; a swallowed transition is not recoverable.
2179
+ this.resultTypes.set(localQueryId, "complete");
2180
+ this.resultTypeHandler(localQueryId, "complete");
2181
+ }
2182
+ else {
2518
2183
  this.hydrated.delete(localQueryId);
2519
- this.recomputeResultType(localQueryId);
2184
+ this.recomputeResultType(localQueryId);
2185
+ }
2520
2186
  }
2521
2187
  this.localToRemote.set(retainQid, key);
2522
2188
  this.remoteRetainToLocal.set(retainQid, localQueryId);
@@ -2640,109 +2306,54 @@ function mergeWriteSet(dest, src) {
2640
2306
  d.set(pkKey, rec);
2641
2307
  }
2642
2308
  }
2643
- /** The key a per-pk write source is stored under in {@link PendingMutation.writeSources}: `table`
2644
- * + NUL + the pk-key (`stableJson(pk)`). NUL appears in neither a table name nor `stableJson`
2645
- * output, so it is an unambiguous separator the same key the confirm-drop hold-back reconstructs
2646
- * from `(table, pkKey)` while iterating `writes`. */
2647
- function writeSourceKey(table, pkKey) {
2648
- return `${table}\u0000${pkKey}`;
2309
+ // --- the 302 room-table helpers -------------------------------------------------------
2310
+ /** The namespaced ENGINE table backing wire `table` for room `sourceKey` (302 §2: `room_deck`
2311
+ * `deck` one authority per table). `@` appears in no schema table name ENFORCED by
2312
+ * `createSchema`/`extendSchema`'s addTableMeta ban (packages/client/src/schema.ts), so the name
2313
+ * cannot collide with a real table. */
2314
+ export function roomEngineTable(table, sourceKey) {
2315
+ return `${table}@${sourceKey}`;
2649
2316
  }
2650
- /** Zip the staged-order per-write source keys (`stagedKeys`, from `trackingTx`) with the staged-order
2651
- * `sources[]` (`commitTracked`) into `dest`, last-write-per-key winning (§5.3). Never shrinks `dest`
2652
- * a rebase re-invocation MERGES its fresh routing in, mirroring {@link mergeWriteSet}. The two
2653
- * arrays align 1:1: `trackingTx` pushes exactly one key per staged change, and `commitTracked`
2654
- * returns one source per staged change, both in staged order. */
2655
- function mergeWriteSources(dest, stagedKeys, sources) {
2656
- const n = Math.min(stagedKeys.length, sources.length);
2657
- for (let i = 0; i < n; i++)
2658
- dest.set(stagedKeys[i], sources[i]);
2659
- }
2660
- // --- the §3 router's pure helpers (H-iii) --------------------------------------------
2661
- /** STRICT cell identity for the join-key no-change rule (§3 write rule #3): `===`, nothing more —
2662
- * no coercion, no deep equality (a non-primitive join-key cell compares by reference and thus
2663
- * conservatively fails), `NaN !== NaN` conservatively fails. Failing closed here only costs a
2664
- * daemon route. */
2665
- function identicalCell(a, b) {
2666
- return a === b;
2667
- }
2668
- /** Whether `cond` is decidable from the KEY ALONE: every column it references — collected from
2669
- * BOTH operand positions (under-counting could over-claim decidability; over-counting only fails
2670
- * closed — the H-iv-a discipline) — is a pk column. A `correlatedSubquery` is never key-local. */
2671
- // Exported for test/predicate_agreement.test.ts — the TS corner of the cross-evaluator
2672
- // agreement corpus (rust/rindle-room-core/tests/fixtures/predicate-agreement.json). NOT part of
2673
- // the package surface (index.ts curates exports); the corpus is the drift tripwire that keeps
2674
- // this evaluator honest against the engine + room-gate pair it shares no code with.
2675
- export function keyDecidable(cond, pkCols) {
2676
- switch (cond.type) {
2677
- case "simple": {
2678
- if (cond.left.type === "column" && !pkCols.has(cond.left.name))
2679
- return false;
2680
- if (cond.right.type === "column" && !pkCols.has(cond.right.name))
2681
- return false;
2682
- return true;
2683
- }
2684
- case "and":
2685
- case "or":
2686
- return cond.conditions.every((c) => keyDecidable(c, pkCols));
2687
- case "correlatedSubquery":
2688
- return false;
2317
+ /** Rename a room gate's released deltas into the room's namespaced tables, DROPPING deltas for
2318
+ * wire tables outside the map (context / unknown the daemon is their sole authority, 302 §6).
2319
+ * Identity (no copy) for a map-less gate the daemon path is untouched. */
2320
+ function mapGateDeltas(gate, muts) {
2321
+ const map = gate.tableMap;
2322
+ if (map === undefined)
2323
+ return muts;
2324
+ const out = [];
2325
+ for (const m of muts) {
2326
+ const engineTable = map.get(m.table);
2327
+ if (engineTable === undefined)
2328
+ continue;
2329
+ out.push({ ...m, table: engineTable });
2689
2330
  }
2331
+ return out;
2690
2332
  }
2691
- /** Evaluate a key-decidable `footprintWhere` on a read's pk cells H-iii's ONE client-side
2692
- * non-engine evaluator, DELIBERATELY MINIMAL (the TS evaluation caveat on the router block
2693
- * comment): `simple` `=`/`!=` between a pk COLUMN and a same-primitive-type NON-NULL literal,
2694
- * composed under and/or. The empty AND the compiler's vacuous-true emission for an exact
2695
- * unconstrained footprint root evaluates `true` (load-bearing: whole-table footprints keep
2696
- * provable reads); the empty OR is vacuous-false. Returns `undefined` = NOT EVALUABLE for
2697
- * anything else (other ops, null on either side, cross-type comparisons, column-vs-column,
2698
- * literal-vs-literal, non-primitive cells, correlated subqueries) — the caller fails to the
2699
- * daemon. A non-evaluable node anywhere poisons the whole tree (no short-circuit past it):
2700
- * partial evaluation could otherwise claim a verdict the engine's semantics might contradict. */
2701
- // Exported for test/predicate_agreement.test.ts (see keyDecidable's note above).
2702
- export function evalFootprintOnPk(cond, pkCells) {
2703
- switch (cond.type) {
2704
- case "simple": {
2705
- if (cond.op !== "=" && cond.op !== "!=")
2706
- return undefined;
2707
- const col = cond.left.type === "column" ? cond.left : cond.right.type === "column" ? cond.right : undefined;
2708
- const lit = cond.left.type === "literal" ? cond.left : cond.right.type === "literal" ? cond.right : undefined;
2709
- if (col === undefined || lit === undefined)
2710
- return undefined; // column-vs-column / literal-vs-literal
2711
- if (!pkCells.has(col.name))
2712
- return undefined; // not a pk column (keyDecidable pre-screens)
2713
- const cell = pkCells.get(col.name);
2714
- const value = lit.value;
2715
- if (cell === null || value === null)
2716
- return undefined; // no null semantics client-side
2717
- if (typeof cell !== typeof value)
2718
- return undefined; // no cross-type comparison semantics
2719
- if (typeof cell !== "string" && typeof cell !== "number" && typeof cell !== "boolean")
2720
- return undefined;
2721
- return cond.op === "=" ? cell === value : cell !== value;
2722
- }
2723
- case "and": {
2724
- let out = true;
2725
- for (const c of cond.conditions) {
2726
- const v = evalFootprintOnPk(c, pkCells);
2727
- if (v === undefined)
2728
- return undefined;
2729
- out = out && v;
2730
- }
2731
- return out;
2732
- }
2733
- case "or": {
2734
- let out = false;
2735
- for (const c of cond.conditions) {
2736
- const v = evalFootprintOnPk(c, pkCells);
2737
- if (v === undefined)
2738
- return undefined;
2739
- out = out || v;
2740
- }
2741
- return out;
2742
- }
2743
- case "correlatedSubquery":
2744
- return undefined;
2745
- }
2333
+ /** Rename every TABLE reference in a query AST through `map` (302 §2 point 3the room-homed
2334
+ * view's rewrite): the root `table`, every `related` subquery, every `correlatedSubquery`
2335
+ * (EXISTS) condition walking the KNOWN wire-AST shape, never a blind key scan: `start.row` is
2336
+ * keyed by COLUMN name (a schema column literally named `table` must keep its bound value), and
2337
+ * the same goes for any future column-keyed record. Tables absent from the map keep their name —
2338
+ * that is the client-side join across kinds (a room table joined to daemon-owned context,
2339
+ * 201-style). Structural clone; the input AST is never mutated. */
2340
+ export function remapAstTables(ast, map) {
2341
+ const walkCond = (c) => {
2342
+ if (c.type === "and" || c.type === "or")
2343
+ return { ...c, conditions: c.conditions.map(walkCond) };
2344
+ if (c.type === "correlatedSubquery")
2345
+ return { ...c, related: walkSub(c.related) };
2346
+ return c; // "simple" — column refs and literals carry no table reference
2347
+ };
2348
+ const walkSub = (s) => ({ ...s, subquery: walk(s.subquery) });
2349
+ const walk = (a) => ({
2350
+ ...a,
2351
+ table: map.get(a.table) ?? a.table,
2352
+ ...(a.where !== undefined ? { where: walkCond(a.where) } : {}),
2353
+ ...(a.having !== undefined ? { having: walkCond(a.having) } : {}),
2354
+ ...(a.related !== undefined ? { related: a.related.map(walkSub) } : {}),
2355
+ });
2356
+ return walk(ast);
2746
2357
  }
2747
2358
  /** Wrap the raw wasm txn as the client `MutationTx`, capturing a pk-granular write-set as it
2748
2359
  * applies (`writes`, a {@link WriteSet} — table → pk-key → last-write-wins image, §3.2 #1);
@@ -2780,17 +2391,22 @@ function applyOpToTx(tx, op) {
2780
2391
  return tx.delete(op.table, op.pk);
2781
2392
  }
2782
2393
  }
2783
- function trackingTx(tx, writes, specs, localTables, onOp, trapReads = false, readLog, stagedKeys,
2784
- /** Per-read provenance probe (H-ii §3.2 #3): called once per RECORDED present read with the
2785
- * full-width row the read observed; meaningful only alongside `readLog` (never consulted when
2786
- * recording is offthe fold and replay paths pass neither). */
2787
- provenance) {
2394
+ function trackingTx(tx, writes, specs, localTables, onOp, trapReads = false, readLog,
2395
+ /** The 302 staging map for a room-DECLARED mutation: wire table the room's namespaced engine
2396
+ * table for the tables the room owns; identity for everything else. Every raw engine access —
2397
+ * reads and writesgoes through it, so a room mutator reads/writes the room's own state
2398
+ * (its optimistic effects land where the room-homed views look) while its envelope still
2399
+ * ships the wire names. Absent (or a non-owned table) ⇒ the plain table, verbatim. */
2400
+ stage) {
2788
2401
  const spec = (table) => {
2789
2402
  const s = specs[table];
2790
2403
  if (!s)
2791
2404
  throw new Error(`unknown table ${JSON.stringify(table)} — tables: ${Object.keys(specs).join(", ")}`);
2792
2405
  return s;
2793
2406
  };
2407
+ /** The ENGINE table a wire-named access lands on (302 §2). Schema/column validation always
2408
+ * runs on the WIRE name (the namespaced twin shares the spec). */
2409
+ const staged = (table) => stage?.get(table) ?? table;
2794
2410
  // M1 (`201-LOCAL-ONLY-TABLES-DESIGN.md` §6): a replayable mutator is a pure function of
2795
2411
  // (synced base + args) — it neither READS nor WRITES a local-only table. The server runs the
2796
2412
  // same mutator from `args` alone and cannot see local tables, so any dependence diverges the
@@ -2825,18 +2441,16 @@ provenance) {
2825
2441
  // this invocation — an add-then-edit (or edit-then-edit) of the same pk collapses to its final
2826
2442
  // image, matching the engine head's own semantics for that pk. The record is replaced with
2827
2443
  // exactly the arguments given: the CALLERS (`edit`/`remove` below, consulting `prior`) decide
2828
- // the pre-image per the H-ii coalescing matrix on {@link WriteRecord}.
2829
- const recordWrite = (table, pk, row, oldRow) => {
2830
- let byPk = writes.get(table);
2444
+ // the pre-image per the H-ii coalescing matrix on {@link WriteRecord}. Keyed by the STAGED
2445
+ // (engine) table name, so the pending axis and the write-set match what the engine holds.
2446
+ const recordWrite = (engineTable, pk, row, oldRow) => {
2447
+ let byPk = writes.get(engineTable);
2831
2448
  if (!byPk)
2832
- writes.set(table, (byPk = new Map()));
2449
+ writes.set(engineTable, (byPk = new Map()));
2833
2450
  const pkKey = stableJson(pk);
2834
2451
  // Defensive copies: the wasm binding's returned arrays are not contractually immutable/unique,
2835
2452
  // so a captured record must not alias a cell array the engine could later reuse or mutate.
2836
- byPk.set(pkKey, { table, pk: [...pk], row: row ? [...row] : undefined, ...(oldRow ? { oldRow: [...oldRow] } : {}) });
2837
- // Staged-order key trace (§5.3): pushed once per staged change, so it zips 1:1 with the staged
2838
- // order of `commitTracked`'s `sources[]` — letting the caller learn each write's routed source.
2839
- stagedKeys?.push(writeSourceKey(table, pkKey));
2453
+ byPk.set(pkKey, { table: engineTable, pk: [...pk], row: row ? [...row] : undefined, ...(oldRow ? { oldRow: [...oldRow] } : {}) });
2840
2454
  };
2841
2455
  // A full insert row: each cell is `obj[c]`, or `null` for an omitted nullable column (design 206
2842
2456
  // §6.2); a `json` object is stringified for the engine (`toCell`). Non-nullable columns are
@@ -2864,22 +2478,17 @@ provenance) {
2864
2478
  // trapped path (where `readLog` is never armed) records nothing, exactly as before.
2865
2479
  const rawGet = (table, pk) => {
2866
2480
  assertNotLocal(table, "read");
2867
- return tx.get(table, pk);
2481
+ return tx.get(staged(table), pk);
2868
2482
  };
2869
2483
  // Push one {@link ReadRecord} when recording is armed (§3.2 #2/#3): outcome from `row`'s
2870
- // presence, per-read provenance probed with the observed FULL-WIDTH row — present reads only
2871
- // (an absent read has no row to probe with, and records no source; see {@link ReadRecord}).
2872
- // The `source` key is OMITTED (not set to undefined) when there is no answer, so a
2873
- // single-domain record is byte-identical to Slice B's.
2484
+ // presence. Pure capture for inspection.
2874
2485
  const recordRead = (table, pk, row) => {
2875
2486
  if (!readLog)
2876
2487
  return;
2877
- const source = row === undefined ? undefined : provenance?.(table, row);
2878
2488
  readLog.reads.push({
2879
2489
  table,
2880
2490
  pk: [...pk],
2881
2491
  outcome: row === undefined ? "absent" : "present",
2882
- ...(source !== undefined ? { source } : {}),
2883
2492
  });
2884
2493
  };
2885
2494
  // The PUBLIC positional read (§3.2 #2) — and, since H-ii, the keyed writers' pre-existence
@@ -2899,50 +2508,55 @@ provenance) {
2899
2508
  return cells ? toKeyed(table, cells) : undefined;
2900
2509
  };
2901
2510
  // The pk's existing record from THIS invocation, if any — the coalescing-matrix input for
2902
- // `edit`/`remove` below (see {@link WriteRecord}).
2903
- const prior = (table, pk) => writes.get(table)?.get(stableJson(pk));
2511
+ // `edit`/`remove` below (see {@link WriteRecord}). Keyed by the STAGED name like the records.
2512
+ const prior = (table, pk) => writes.get(staged(table))?.get(stableJson(pk));
2904
2513
  const add = (table, row) => {
2905
2514
  assertNotLocal(table, "write");
2906
- recordWrite(table, pkFromCells(table, row), row);
2515
+ const t = staged(table);
2516
+ recordWrite(t, pkFromCells(table, row), row);
2517
+ // ChildOps carry the WIRE name (unlike the write-set): the agg overlay's defs are keyed by
2518
+ // the ORIGINAL AST's child tables (`collectAggDefs`), and the `__agg_*` heads it feeds are
2519
+ // shared by plain and swapped views alike — a staged name would silently miss the dispatch
2520
+ // and the optimistic count would lag every room-declared write until its echo.
2907
2521
  onOp?.({ table, kind: "add", row });
2908
- tx.add(table, row);
2522
+ tx.add(t, row);
2909
2523
  };
2910
2524
  const remove = (table, row) => {
2911
2525
  assertNotLocal(table, "write");
2526
+ const t = staged(table);
2912
2527
  const pk = pkFromCells(table, row);
2913
- // The remove PRE-IMAGE (G-iii, §7.3 tombstone; the H-ii matrix on {@link WriteRecord}):
2914
- // remove-after-edit/-remove keeps the ORIGINAL captured pre-image (the txn-entry base — the
2915
- // net effect is a remove of the row the external world last knew, never the edited transient).
2916
- // Otherwise (first touch, or remove-after-add) the truthful full-width row is the txn-visible
2917
- // one — `tx.get` read BEFORE the remove stages (read-your-writes: an add of this pk earlier in
2918
- // the SAME invocation shows through). Captured NOW so Slice H's writable-predicate evaluation
2919
- // over it needs no migration. Falls back to the caller's asserted `row` when the pk is not
2528
+ // The remove PRE-IMAGE (the H-ii matrix on {@link WriteRecord}): remove-after-edit/-remove
2529
+ // keeps the ORIGINAL captured pre-image (the txn-entry base — the net effect is a remove of
2530
+ // the row the external world last knew, never the edited transient). Otherwise (first touch,
2531
+ // or remove-after-add) the truthful full-width row is the txn-visible one — `tx.get` read
2532
+ // BEFORE the remove stages (read-your-writes: an add of this pk earlier in the SAME
2533
+ // invocation shows through). Falls back to the caller's asserted `row` when the pk is not
2920
2534
  // resident (a raw remove of an absent row) — a captured remove thus always carries a
2921
- // full-width pre-image (the engine width-checks `holdBackAbsent`).
2922
- const oldRow = prior(table, pk)?.oldRow ?? tx.get(table, pk) ?? row;
2923
- recordWrite(table, pk, undefined, oldRow);
2924
- onOp?.({ table, kind: "remove", row });
2925
- tx.remove(table, row);
2535
+ // full-width pre-image.
2536
+ const oldRow = prior(table, pk)?.oldRow ?? tx.get(t, pk) ?? row;
2537
+ recordWrite(t, pk, undefined, oldRow);
2538
+ onOp?.({ table, kind: "remove", row }); // wire name — see `add`
2539
+ tx.remove(t, row);
2926
2540
  };
2927
2541
  const edit = (table, oldRow, newRow) => {
2928
2542
  assertNotLocal(table, "write");
2543
+ const t = staged(table);
2929
2544
  const pk = pkFromCells(table, newRow);
2930
- // The edit PRE-IMAGE (H-ii; the matrix on {@link WriteRecord}) H-iii's join-key no-change
2931
- // input, and the row the engine routes the Edit by (H-i). First touch: the txn-visible row
2932
- // read BEFORE staging, falling back to the caller's asserted `oldRow` when the pk is not
2545
+ // The edit PRE-IMAGE (the H-ii matrix on {@link WriteRecord}). First touch: the txn-visible
2546
+ // row read BEFORE staging, falling back to the caller's asserted `oldRow` when the pk is not
2933
2547
  // resident (covers the pk-MOVING raw edit — the record is keyed by the NEW pk; the pre-image
2934
2548
  // carries the OLD row). Edit-after-edit: keep the FIRST pre-image (the txn-entry base).
2935
2549
  // Edit-after-add / edit-after-remove: the record collapses to a (re-)insert — NO pre-image
2936
2550
  // (the pk did not pre-exist this invocation's base).
2937
2551
  const p = prior(table, pk);
2938
2552
  const pre = p === undefined
2939
- ? (tx.get(table, pk) ?? oldRow)
2553
+ ? (tx.get(t, pk) ?? oldRow)
2940
2554
  : p.row !== undefined && p.oldRow !== undefined
2941
2555
  ? p.oldRow
2942
2556
  : undefined;
2943
- recordWrite(table, pk, newRow, pre);
2944
- onOp?.({ table, kind: "edit", row: newRow, old: oldRow });
2945
- tx.edit(table, oldRow, newRow);
2557
+ recordWrite(t, pk, newRow, pre);
2558
+ onOp?.({ table, kind: "edit", row: newRow, old: oldRow }); // wire name — see `add`
2559
+ tx.edit(t, oldRow, newRow);
2946
2560
  };
2947
2561
  // The folded read trap (§5): a mutator that reads to compute its write is refused. `() => never`
2948
2562
  // is assignable to the wider read signatures (extra args ignored, `never` widens to the result).
@@ -2959,7 +2573,9 @@ provenance) {
2959
2573
  for (const t of collectTables(ast))
2960
2574
  assertNotLocal(t, "read");
2961
2575
  readLog?.queries.push(ast);
2962
- return tx.query(ast);
2576
+ // A room-declared mutator's one-shot query reads the room's own staged state for the tables
2577
+ // the room owns (the same staging rule as the point reads above).
2578
+ return tx.query(stage !== undefined && stage.size > 0 ? remapAstTables(ast, stage) : ast);
2963
2579
  };
2964
2580
  return {
2965
2581
  get: trapReads ? trapped : getImpl,