@ultimat3/realtime 29.3.1 → 29.4.0

package/CLAUDE.md

@@ -253,7 +253,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - Anything a component reads is a getter or accessor. `MutatorLike.local` uses method syntax.
   `useQuery`'s input is read once, at call time.
 - **`useRecords(type, selection)` holds the TYPE** (`retainType`): `ready` at once, recomputed per
-  change to that type, no row of it evicted while held; the last type hold evicts what it spared.
+  change to that type, no row of it released away while held; the last type hold evicts what it spared.
+- **Bounded store**: README "One record per `type:key`"; `channel-retention.test.ts`.
 - **Read hooks answer the SAME object until what they show moved** (`keptAnswer`); a `where`
   reader hears only keys it shows or keeps (history, 2026-10-29).
 - Every subscription handle is `Disposable`; `[Symbol.dispose]` IS the release. Type claims go in

package/README.md

@@ -436,6 +436,8 @@ over it, and an HTTP answer's records, a socket patch and an optimistic write al
 | A value is **replaced, never mutated**; a write **merges** columns | a mutated row is a render that never happens; a narrower projection must not blank a wider one |
 | A structurally bad row is `X_RECORD_REJECTED`, dropped and reported | never partially merged — a keyless row would overwrite another record |
 | The last holder leaving evicts the record | an infinite scroll must not retain every row it ever saw |
+| A joined channel keeps the rows its frames and catch-up reads adopted — dropped (the last `useChannel` released) it evicts each it alone kept; a row the server removes leaves its keep at once | a `records` frame's rows carry no reader hold: a run page's channel left its events behind after the reader navigated away |
+| Each type is capped — `new RecordStore({ maxRowsPerType, maxRowsByType })`: `maxRowsPerType` for every type (default `DEFAULT_MAX_ROWS_PER_TYPE` = 10 000), `maxRowsByType: { run_logs: 50_000 }` for the types it names; `Infinity` turns a cap off, anything not a whole number ≥ 1 is `X_INVARIANT`. Past it, at the close of a batch, the least recently written row goes — never one a key reader holds (`useRecord`, `useRecords(type, keys)`, a `useQuery` list, a live window), never one a pending write touched, never one that arrived in that batch | a backstop against a fleet feed joined for hours, which adopts a row per run forever — not a view limit: the default sits far above what a page shows of one type. Neither a channel's keep nor a whole-type reader (`useRecords(type, selection)`, which shows at most the cap) exempts a type, so a type a page shows more of than the default names its own cap |
 | A principal change clears the store | nothing of the previous principal survives in memory |
 
 ## Reconnect is the hard part
@@ -866,8 +868,11 @@ principal.
   table not on FULL, on every boot. `ReplicationStreamStats.partialBefore` still counts changes off
   a non-FULL relation — a volume figure, not a correctness one.
 - The record store is **per page**, in memory, and it is not a query cache: it answers "what is
-  record X now", never "have I run this query before". Nothing evicts by time or size — a record
-  lives as long as something holds it. Persisting it (IndexedDB) is plan 101 slice 12.
+  record X now", never "have I run this query before". Nothing evicts by time; size is bounded —
+  a record lives while a reader, a joined channel or a pending write holds it, and an unheld row
+  (an HTTP answer's before its reader holds it, a channel's) is also bounded by the per-type cap
+  (`maxRowsPerType` / `maxRowsByType`, least recently written first). An eviction is a change like any other: the
+  persister deletes the row from disk with it. Persisting it (IndexedDB) is plan 101 slice 12.
 
 ## Errors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "29.3.1",
+  "version": "29.4.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -40,10 +40,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.1",
-    "@ultimat3/entity": "29.3.1",
-    "@ultimat3/policy": "29.3.1",
-    "@ultimat3/query": "29.3.1",
+    "@ultimat3/core": "29.4.0",
+    "@ultimat3/entity": "29.4.0",
+    "@ultimat3/policy": "29.4.0",
+    "@ultimat3/query": "29.4.0",
     "nats": "2.29.3"
   }
 }

package/src/client-channels.ts

@@ -17,6 +17,14 @@ import type {
 } from './sync-protocol';
 import { PROTOCOL_VERSION } from './wire-version';
 
+/**
+ * Frames held behind a catch-up read, and applied seqs above a hole, at most: the node's own ring
+ * (`DEFAULT_CHANNEL_RING`, held equal by a test — not imported, that module is the server's). Past
+ * it the node could not replay them either, so the read answers instead: held, a read failing
+ * for an hour held every frame of the hour, and one lost frame grew `above` for the session.
+ */
+export const CHANNEL_HELD_FRAMES = 256;
+
 /** What a browser needs of a `channel()` declaration: its name, its topic rule, its catch-up read. */
 export interface ChannelRef<K extends string = string> {
   readonly name: string;
@@ -144,6 +152,8 @@ export class ChannelBook {
       this.#byTopic.delete(topic);
       held.disarm?.();
       held.disarm = null;
+      // The rows this channel alone kept go with it; a row a reader still holds stays.
+      this.#deps.store.disown(sidOf(held));
       this.#deps.send(this.#frame(held, 'drop', false));
     };
     return {
@@ -210,7 +220,7 @@ export class ChannelBook {
     const entry = this.#byTopic.get(frame.channel);
     if (entry === undefined) return;
     if (entry.buffered !== null) {
-      entry.buffered.push(frame);
+      this.#hold(entry, entry.buffered, [frame]);
       // The echo of a write the answered read waits on: it lands with the read, settling it there.
       if (frame.write !== undefined) entry.landing?.recheck();
       return;
@@ -267,7 +277,8 @@ export class ChannelBook {
     }
     const store = this.#deps.store;
     store.batch(() => {
-      for (const [type, rows] of Object.entries(frame.adopt ?? {})) store.adopt(type, rows);
+      const owner = sidOf(entry);
+      for (const [type, rows] of Object.entries(frame.adopt ?? {})) store.adopt(type, rows, owner);
       for (const [type, keys] of Object.entries(frame.remove ?? {})) store.remove(type, keys);
       // This page's own write, echoed: settled in the same batch as its rows, so its twin is
       // never replayed over the truth that already holds it.
@@ -281,6 +292,12 @@ export class ChannelBook {
     let next = contiguous;
     while (entry.above.delete(next + 1)) next += 1;
     entry.contiguous = next;
+    // A hole the ring has moved past (a frame lost with no `replay-gap`): no replay can fill it, so
+    // the read does — and `above` stops growing for the rest of the session.
+    if (entry.above.size > CHANNEL_HELD_FRAMES) {
+      this.#catchUp(entry, []);
+      return;
+    }
     if (entry.state !== 'live') this.#set(entry, 'live');
   }
 
@@ -293,7 +310,7 @@ export class ChannelBook {
    */
   #catchUp(entry: Entry, pending: ChannelRecordsFrame[], epoch?: string): void {
     if (entry.buffered !== null) {
-      entry.buffered.push(...pending);
+      this.#hold(entry, entry.buffered, pending);
       if (pending.length === 0) entry.again = { epoch: epoch ?? entry.again?.epoch };
       // No read in flight — the last one failed — so this gap is the retry, now.
       if (entry.waiting) this.#read(entry);
@@ -304,6 +321,18 @@ export class ChannelBook {
     this.#read(entry);
   }
 
+  /**
+   * Frames held behind the read, bounded by the ring: past it they are dropped and one more read
+   * follows, in the newest frame's epoch — the read answers what they carried.
+   */
+  #hold(entry: Entry, held: ChannelRecordsFrame[], frames: readonly ChannelRecordsFrame[]): void {
+    held.push(...frames);
+    if (held.length > CHANNEL_HELD_FRAMES) {
+      entry.again = { epoch: held.at(-1)?.epoch };
+      entry.buffered = [];
+    }
+  }
+
   /** The cursor, reset into `epoch`: every seq before the read is the read's to answer. */
   #restart(entry: Entry, epoch: string | null): void {
     entry.epoch = epoch;
@@ -380,7 +409,7 @@ export class ChannelBook {
       entry.again = null;
       // Its rows land now, alone: they are newer than the store's, and a re-read that fails would
       // otherwise leave the older ones for the whole retry curve. The frames wait for the re-read.
-      this.#adopt(answered);
+      this.#adopt(entry, answered);
       entry.buffered = held.filter((frame) => frame.epoch === epoch);
       this.#restart(entry, epoch);
       this.#read(entry);
@@ -393,7 +422,7 @@ export class ChannelBook {
     // `#adopt` and `#apply` open batches of their own inside this one: `RecordStore.batch` nests,
     // so the read's rows and every held frame are still ONE notification.
     store.batch(() => {
-      this.#adopt(answered);
+      this.#adopt(entry, answered);
       for (const frame of current) {
         if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
         this.#apply(entry, frame);
@@ -403,11 +432,13 @@ export class ChannelBook {
   }
 
   /** A catch-up read's rows, unless the principal it was read for has left (`CatchUpRecords`). */
-  #adopt(answered: CatchUpRecords | undefined): void {
+  #adopt(entry: Entry, answered: CatchUpRecords | undefined): void {
     if (answered === undefined || answered.current?.() === false) return;
     const store = this.#deps.store;
+    const owner = sidOf(entry);
     store.batch(() => {
-      for (const [type, rows] of Object.entries(answered.records ?? {})) store.adopt(type, rows);
+      for (const [type, rows] of Object.entries(answered.records ?? {}))
+        store.adopt(type, rows, owner);
       for (const [type, keys] of Object.entries(answered.removed ?? {})) store.remove(type, keys);
     });
   }

package/src/index.ts

@@ -139,6 +139,7 @@ export { hasPageSocket, type SyncTarget } from './page-store';
 export { installRealtime, type RealtimeInstall } from './reactivity';
 export { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
 export {
+  DEFAULT_MAX_ROWS_PER_TYPE,
   type RecordKey,
   type RecordListener,
   RecordStore,

package/src/live-definition.ts

@@ -103,10 +103,14 @@ const LIVE_READER_ID = 'live-window';
  *
  * `tenant === null` runs under the node's own actor, which has no org: a tenant-scoped read is
  * then `X_TENANCY_ACTOR_ORG_REQUIRED`, the verdict the same anonymous read gets over HTTP.
+ *
+ * EVERY read runs in a fresh child context, the tenant-less one included. The node's `ctx` lives
+ * as long as the process, and per-request state is keyed off the context object (`@ultimat3/cache`'s
+ * request memo is a `WeakMap` on it): run straight in it, every tenant-less read memoised into one
+ * store that never died — stale answers served to every later read, and a heap that only grew.
  */
 function readFor<T>(ctx: Ctx, tenant: string | null, read: () => Promise<T>): Promise<T> {
-  if (tenant === null) return runWithContext(ctx, read);
-  const actor = serviceActor({ id: LIVE_READER_ID, orgId: tenant });
+  const actor = tenant === null ? undefined : serviceActor({ id: LIVE_READER_ID, orgId: tenant });
   return runWithContext(ctx, () => withChildContext({ actor }, read));
 }
 

package/src/record-store.ts

@@ -4,7 +4,7 @@
 // core's `RecordSink`, so `clientTransport` adopts into it without importing this package.
 
 import type { ConflictPolicy, RecordRows, RecordSink, Row } from '@ultimat3/core/page';
-import { resolveConflict } from '@ultimat3/core/page';
+import { finiteCount, resolveConflict } from '@ultimat3/core/page';
 import { RebaseConflictError, RecordRejectedError } from './page-errors';
 import { ServerWait } from './record-await';
 import { isRow, type RecordKey, recordKey } from './record-key';
@@ -28,8 +28,26 @@ export interface RecordStoreOptions {
   readonly schedule?: Scheduler;
   /** How long an overlay waits for the server's row before the synced layer stands. */
   readonly awaitMs?: number;
+  /**
+   * The per-type cap: rows of one type the store keeps at most. Past it the least recently written
+   * row no key reader holds is evicted (`SyncedLayer.trim`) — a backstop for a channel joined for
+   * hours, not a view limit. Default `DEFAULT_MAX_ROWS_PER_TYPE`; `Infinity` turns it off.
+   */
+  readonly maxRowsPerType?: number;
+  /** The cap for the types named here, over `maxRowsPerType` — a log type that runs long, say. */
+  readonly maxRowsByType?: Readonly<Record<string, number>>;
 }
 
+/**
+ * The per-type cap's default. A backstop against hours of a fleet feed: well above what a page
+ * shows of one type (a run's 2 000 log lines): a whole-type reader loses no row it shows while its
+ * type stays under its cap (past it the least recently written unheld rows go — name a bigger
+ * cap for that type in `maxRowsByType`).
+ */
+export const DEFAULT_MAX_ROWS_PER_TYPE = 10_000;
+
+const MAX = Number.MAX_SAFE_INTEGER;
+
 export class RecordStore implements RecordSink {
   readonly #synced = new SyncedLayer();
   /** The overlay's answer per key: a row, or `null` for a record the overlay deleted. */
@@ -48,9 +66,21 @@ export class RecordStore implements RecordSink {
   readonly #names = new WriteNames();
   /** Server truth held behind this page's writes in flight (`afterWrites`). */
   readonly #landings: Landings;
+  /** The per-type cap: every type's, then each type `maxRowsByType` names. */
+  readonly #cap: number;
+  readonly #caps = new Map<string, number>();
 
   constructor(options: RecordStoreOptions = {}) {
     this.#report = options.report ?? ((error) => console.error(error));
+    // `Infinity` is "no cap": the largest count there is. `NaN` stays `NaN`, and is refused.
+    const maxRowsPerType = options.maxRowsPerType ?? DEFAULT_MAX_ROWS_PER_TYPE;
+    this.#cap = finiteCount('RecordStore', 'maxRowsPerType', Math.min(maxRowsPerType, MAX), 1);
+    for (const [type, cap] of Object.entries(options.maxRowsByType ?? {})) {
+      this.#caps.set(
+        type,
+        finiteCount('RecordStore', `maxRowsByType.${type}`, Math.min(cap, MAX), 1),
+      );
+    }
     this.#wait = new ServerWait(options.schedule, options.awaitMs);
     this.#landings = new Landings(
       (fire) => this.#wait.bound(fire),
@@ -90,8 +120,9 @@ export class RecordStore implements RecordSink {
   /**
    * `RecordSink.adopt`: server truth, keyed by the server (it holds the entity's primary key; the
    * browser does not). Merged column by column. A structurally bad row is dropped, never merged.
+   * `owner` is the joined channel whose frame carried them: it keeps them until `disown`.
    */
-  adopt(type: string, rows: RecordRows): void {
+  adopt(type: string, rows: RecordRows, owner?: string): void {
     this.batch(() => {
       for (const [key, row] of Object.entries(rows)) {
         if (!isRow(row) || key === '') {
@@ -104,10 +135,18 @@ export class RecordStore implements RecordSink {
           continue;
         }
         this.merge(type, key, row);
+        if (owner) this.#synced.own(recordKey(type, key), owner);
       }
     });
   }
 
+  /** The channel `owner` was dropped: the rows only it kept are evicted (`SyncedLayer.disown`). */
+  disown(owner: string): void {
+    this.batch(() => {
+      for (const rk of this.#synced.disown(owner)) this.#touchSynced(rk);
+    });
+  }
+
   /** `RecordSink.remove`: the server says these records are gone, for every holder at once. */
   remove(type: string, keys: readonly string[]): void {
     this.batch(() => {
@@ -159,7 +198,7 @@ export class RecordStore implements RecordSink {
     this.#synced.retain(recordKey(type, key));
   }
 
-  /** The last holder leaving evicts the synced record: an infinite scroll must not keep every row. */
+  /** The last holder leaving evicts the synced record — unless a joined channel still keeps it. */
   release(type: string, key: string): void {
     const rk = recordKey(type, key);
     if (this.#synced.release(rk)) this.#touchSynced(rk);
@@ -321,6 +360,7 @@ export class RecordStore implements RecordSink {
     try {
       return fn();
     } finally {
+      this.#trim();
       // Synced truth moved under pending writes: replay them once, at the end, over the new truth.
       if (this.#syncedMoved) {
         this.#syncedMoved = false;
@@ -405,6 +445,15 @@ export class RecordStore implements RecordSink {
     return this.#overlays.delete(key);
   }
 
+  /** The per-type cap, at the close of each batch — never over a row a pending write touched. */
+  #trim(): void {
+    const evicted = this.#synced.trim(
+      (type) => this.#caps.get(type) ?? this.#cap,
+      (rk) => this.#view.has(rk) || [...this.#touched.values()].some((keys) => keys.has(rk)),
+    );
+    for (const rk of evicted) this.#touchSynced(rk);
+  }
+
   #touchSynced(rk: RecordKey): void {
     this.#syncedMoved = true;
     this.#moved.add(rk);

package/src/record-synced.ts

@@ -1,6 +1,7 @@
 // The store's SYNCED layer: server truth per `type:key`, merged column by column, with the holds
-// that evict a record nobody renders and the provisional mark on rows restored from disk. Pure
-// state — it answers what moved, and the store decides who hears about it.
+// that evict a record nobody renders, the channels that keep what they adopted, the per-type cap,
+// and the provisional mark on rows restored from disk. Pure state — it answers what moved, and the
+// store decides who hears about it.
 
 import type { Row } from '@ultimat3/core/page';
 import { sameJson } from './json';
@@ -25,6 +26,14 @@ export class SyncedLayer {
    * a colon (`?query:<name>`, an unnamed live query's rows), so `type:key` splits two ways.
    */
   readonly #typeOfKey = new Map<RecordKey, string>();
+  /**
+   * Per key, the owners (a joined channel's sid) whose frames adopted it: each keeps the row like a
+   * key holder until it leaves, or the server removes the row. Only rows that are here: a removed
+   * row leaves it, so a feed joined for hours holds no key it no longer has.
+   */
+  readonly #owners = new Map<RecordKey, Set<string>>();
+  /** Per type, the writes since the last `trim` — its newest rows, which no reader could hold yet. */
+  readonly #written = new Map<string, Set<RecordKey>>();
 
   get(rk: RecordKey): Row | undefined {
     return this.#rows.get(rk);
@@ -101,6 +110,7 @@ export class SyncedLayer {
   /** Answers whether a row was there to remove. */
   remove(rk: RecordKey): boolean {
     this.#provisional.delete(rk);
+    this.#owners.delete(rk);
     // Gone is no longer spared: a row the server sends again later is a new arrival, not this one.
     const type = this.#typeOfKey.get(rk) ?? typeOf(rk);
     this.#typeOfKey.delete(rk);
@@ -127,14 +137,59 @@ export class SyncedLayer {
       return false;
     }
     this.#holds.delete(rk);
-    const type = this.#typeOfKey.get(rk) ?? typeOf(rk);
-    if (this.#typeHolds.has(type)) {
-      const spared = this.#spared.get(type) ?? new Set<RecordKey>();
-      spared.add(rk);
-      this.#spared.set(type, spared);
-      return false;
+    // A channel that adopted it still keeps it: it goes when that channel leaves.
+    return !this.#owners.has(rk) && this.#evict(rk);
+  }
+
+  /** `owner` (a joined channel) adopted this row, just merged: it stays until the owner leaves. */
+  own(rk: RecordKey, owner: string): void {
+    setIn(this.#owners, rk).add(owner);
+  }
+
+  /**
+   * The owner left (its channel was dropped): every row it alone kept goes — exactly as a last key
+   * holder's release would, so a reader of the whole type still spares it. Answers the rows that went.
+   */
+  disown(owner: string): readonly RecordKey[] {
+    const evicted: RecordKey[] = [];
+    // A walk of the kept rows, not an index per owner: a drop is rare, and an index is bytes in
+    // every page's boot. Deleting the entry being visited is safe while iterating a Map.
+    for (const [rk, owners] of this.#owners) {
+      if (!owners.delete(owner) || owners.size > 0) continue;
+      this.#owners.delete(rk);
+      if (!this.#holds.has(rk) && this.#evict(rk)) evicted.push(rk);
     }
-    return this.remove(rk);
+    return evicted;
+  }
+
+  /**
+   * The per-type cap: each type that grew since the last trim is cut back to its cap, least
+   * recently written first. Never a row a key reader holds, never one `pinned` (a pending write's),
+   * never one written since the last trim (an HTTP answer's rows, before its reader holds them).
+   * A channel's ownership and a whole-type hold do NOT protect a row here: a fleet feed
+   * joined for hours, read by `useRecords(type)`, is exactly what the cap exists to bound.
+   */
+  trim(capOf: (type: string) => number, pinned: (rk: RecordKey) => boolean): readonly RecordKey[] {
+    const evicted: RecordKey[] = [];
+    for (const [type, written] of this.#written) {
+      const keys = this.#byType.get(type) ?? new Set<RecordKey>();
+      let over = keys.size - capOf(type);
+      // Oldest first: `#put` moves a row to the end of its type on every write, so the DISTINCT
+      // rows written since the last trim that are still there are the last ones — never reached
+      // (a row written twice counts once; one removed since is no longer at the end). Deleting the
+      // entry being visited is safe while iterating a Set.
+      let fresh = 0;
+      for (const rk of written) if (keys.has(rk)) fresh += 1;
+      let older = keys.size - fresh;
+      for (const rk of keys) {
+        if (over <= 0 || older-- <= 0) break;
+        if (this.#holds.has(rk) || pinned(rk) || !this.remove(rk)) continue;
+        evicted.push(rk);
+        over -= 1;
+      }
+    }
+    this.#written.clear();
+    return evicted;
   }
 
   retainType(type: string): void {
@@ -157,12 +212,14 @@ export class SyncedLayer {
     this.#spared.delete(type);
     const evicted: RecordKey[] = [];
     for (const rk of spared ?? []) {
-      if (!this.#holds.has(rk) && this.remove(rk)) evicted.push(rk);
+      if (!this.#holds.has(rk) && !this.#owners.has(rk) && this.remove(rk)) evicted.push(rk);
     }
     return evicted;
   }
 
   clear(): void {
+    this.#owners.clear();
+    this.#written.clear();
     this.#rows.clear();
     this.#byType.clear();
     this.#typeOfKey.clear();
@@ -170,16 +227,37 @@ export class SyncedLayer {
     this.#spared.clear();
   }
 
-  #put(rk: RecordKey, row: Row, type: string): void {
-    if (!this.#typeOfKey.has(rk)) {
-      this.#typeOfKey.set(rk, type);
-      const keys = this.#byType.get(type);
-      if (keys === undefined) this.#byType.set(type, new Set([rk]));
-      else keys.add(rk);
+  /** A row nobody holds goes — unless a reader holds its whole type, which spares it till it leaves. */
+  #evict(rk: RecordKey): boolean {
+    const type = this.#typeOfKey.get(rk) ?? typeOf(rk);
+    if (this.#typeHolds.has(type)) {
+      setIn(this.#spared, type).add(rk);
+      return false;
     }
+    return this.remove(rk);
+  }
+
+  #put(rk: RecordKey, row: Row, named: string): void {
+    const type = this.#typeOfKey.get(rk) ?? named;
+    this.#typeOfKey.set(rk, type);
+    // Re-inserted on every write: a type's index is also its recency order, oldest first.
+    const keys = setIn(this.#byType, type);
+    keys.delete(rk);
+    keys.add(rk);
+    setIn(this.#written, type).add(rk);
     this.#rows.set(rk, row);
   }
 }
 
 /** A key's type when no writer named it (a hold on a row not yet there): before its first `:`. */
 const typeOf = (rk: RecordKey): string => rk.slice(0, rk.indexOf(':'));
+
+/** The set `map` holds under `key`, made on first use. */
+function setIn<K, V>(map: Map<K, Set<V>>, key: K): Set<V> {
+  let set = map.get(key);
+  if (set === undefined) {
+    set = new Set();
+    map.set(key, set);
+  }
+  return set;
+}