@ultimat3/realtime 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -7,7 +7,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | May import | Must not |
 |---|---|
 | `@ultimat3/core`, `@ultimat3/query`, `@ultimat3/entity` (`/record` only, server-side) | anything tier 4+ (`render`, `pwa`, `mcp`, `ui`, `cli`) |
-| `@ultimat3/policy` **only via** `@ultimat3/query`'s `guard` | a second authz path of any kind |
+| `@ultimat3/policy` **only via** `@ultimat3/query`'s `guardQuery` for a decision (`policyCapability` / `policyPermissions` are display reads) | a second authz path of any kind |
 | — | `solid-js` (each island bundle installs its own signal factory: `installRealtime`) |
 | `nats` (the one external dependency, pinned exact) — from `nats-lib-client.ts` and no other file | `nats` from anywhere else. Every other file is written against the port in `nats-client.ts` |
 
@@ -21,28 +21,22 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   link). `packages/cli/src/realtime-browser-barrel.test.ts` bundles a `useLive`-only entry;
   `barrel-split.test.ts` refuses a name exported from both. `./boot` and `./sync-worker` are the page
   boot and the SharedWorker entry.
-- **`errors.ts` is the code table plus the client-reachable refusals**; `realtime-error.ts` holds
-  the base class alone (an `extends` must not read it in a TDZ) and `replication-errors.ts` the
-  Postgres ones. Every name is still exported from `./errors`. A browser path loads `page-errors.ts`,
-  never the table (`page-errors-bundle.test.ts`).
-- **`sideEffects` is the ARRAY `["./src/errors.ts"]`**, never `false` (drops `registerErrorCodes()`)
-  and never absent. `bun run side-effects` is the check.
+- **`error-titles.ts` holds the codes, titles and `registerErrorCodes()`**; `errors.ts` the server
+  refusals, `page-errors.ts` the browser ones, `realtime-error.ts` the base class (TDZ),
+  `replication-errors.ts` Postgres. All re-exported from `./errors`. A hook's chunk never loads
+  `errors.ts` (`page-errors-bundle.test.ts`).
+- **`sideEffects` is `["./src/error-titles.ts"]`**, imported bare by the barrel (`refusalError` and
+  `page-errors.ts` title by code); never `false` or absent.
 - **Every `@ultimat3/realtime/<subpath>` written in shipped source must be a key of `exports`**,
   comments included — `fix-specifier.test.ts`.
-- **`@ultimat3/realtime/server` needs its own `paths` entry in `tsconfig.base.json`** (the wildcard
-  maps it to a directory that does not exist; `scripts/**` reports `TS2307` without it).
-- A browser file imports core from `@ultimat3/core/page` (`packages/core/src/page-bundle.test.ts`,
-  `packages/query/src/client-bundle.test.ts`).
+- A browser file imports core from `@ultimat3/core/page` (`packages/core/src/page-bundle.test.ts`).
 
 ## Numbers and ceilings
 
 - **Every numeric option is refused when it is not FINITE** — `@ultimat3/core`'s `finiteOption()`.
-  `bun run finite-bounds` reads zero for this package, but it cannot see an option with no `??`
-  default or where a screen runs, so audit by reading the option interfaces
-  (`SubscriptionBook`'s `maxPerTenant` and `openNatsClient`'s `maxReconnectAttempts` were the two it
-  missed). `SyncGrant.expiresAt` is app DATA, not an option, and is deliberately unscreened.
+  `bun run finite-bounds` cannot see an option with no `??` default: read the option interfaces. `SyncGrant.expiresAt` is app DATA, deliberately unscreened.
 - **A ceiling is refused where the object is BUILT**, never in a per-connection callback:
-  `socketCeilings()` (`sync-node-bounds.ts`) runs once in `createSyncNode`; `SyncSocket` keeps its own
+  `socketCeilings()` (`sync-node-bounds.ts`) runs once in `syncNode`; `SyncSocket` keeps its own
   screen because it is exported. `AcceptBudget`, `SyncSocket` and `SocketRegistry` throw
   `X_INVARIANT` at construction on `NaN`/`±Infinity`.
 - **A ceiling per resource, and the wire's are not options** (table in `README.md`): the accept
@@ -50,19 +44,19 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   at the top of `routeFrame` **before `touch()`**), and `FRAME_LIMITS` in `decode` everything a
   client sizes (narrowable, never widenable). `list()` takes a required `max`. `input` is walked
   ITERATIVELY.
-- **Every `SyncSocket` ceiling is reachable from `createSyncNode`**, forwarded as
-  `...(x === undefined ? {} : { x })`.
 - **A `SubscriptionLimitError` names the knob**: every throw site passes `knob` explicitly;
   `channel.test.ts` asserts the hub's two against the option names.
-- **Retained memory is bounded by BYTES**: `RingChangeBuffer` keeps the patch count as a replay
-  bound and byte budgets as the memory bound. `forget(qid)` runs when the last subscriber goes and
-  from `#dropIfUnheld` after a failed cold subscribe (only if the entry is still in the table, unheld
-  and has no read in flight).
+- **Retained memory is bounded by BYTES** (`RingChangeBuffer`: patch count bounds replay, bytes
+  bound memory). `forget(qid)` runs when the last subscriber goes and from `#dropIfUnheld`.
+- **The ring floor is one rule (`change-buffer.ts`, `Ring`)**: only a read that LANDED floors it
+  (`fillWindow().landed`), a forced one exclusively; a position-less read is marked with the
+  node's origin and answers that cursor alone below its first patch; a stale entry serves cold
+  starts only.
 - **Every question a hot path asks is indexed**: `SubscriptionBook` keeps `#bySocket` and a
   per-tenant count; `SocketRegistry` keeps `#byTopic`, changed only by `joinTopic`/`leaveTopic`.
   `reauthorize` calls `book.retenant(socket)`.
 - **A cap is a RESERVATION taken before the first await**: `SubscriptionBook.reserve(socket, sid)`
-  decides the sid claim, `maxPerSocket` and `maxPerTenant` in one synchronous step;
+  decides the sid claim, `maxPerSocket`, `maxPerTenant` and `maxPerActor` in one synchronous step;
   `ChannelHub.subscribe` does the same for its caps. Released in a `finally`, idempotently.
 - **Readiness AND the connection cap are functions on `UpgradeDeps`**, re-asked after
   `authenticate` (app code with an await) and right before `server.upgrade`. The recheck sheds with
@@ -85,8 +79,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A denial is a decision; everything else is a failure.** `visibleWithPolicy` matches
   `QueryDeniedError` and rethrows the rest; `subscriber-gate.ts` and `reauthorize` ask
   `isPolicyDenial(error)`. A failed snapshot raises out of `subscribe`; a failed delivery desyncs that
-  one subscriber; a failed `reauthorize` keeps the subscription, unless its org moved — then it is
-  refused under its sid (`refuseSubscription`), as is a failed re-seat. Failures count as
+  one subscriber; a failed `reauthorize` keeps the subscription, a DENIED one is refused under its sid
+  (`refuseSubscription`) — as is one whose org moved, and a failed re-seat. Failures count as
   `gateFailures` via `onGateFailed`, never `onRowDenied`.
 - **One serial lane per query id (`WindowLock`) is the only thing that orders a fanout.** `deliver`
   enters every lane before awaiting any; no fanout takes a second lane; a lane that fails desyncs its
@@ -107,10 +101,10 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   never clears a mark (`live-fanout.test.ts`).
 - **A change the window already holds is refused** (`change.lsn <= entry.lsn`, counted as
   `staleChanges`). **A gap is detected**: the replicator stamps `producer` + `seq`; a skipped
-  sequence marks every window stale and every subscriber desynced; `refillWindowInLane` replaces it.
-- **A bulk write stales only the windows reading its entity** (`invalidate(entity)`, from
-  `onBulk`). **A stale window's re-read re-snapshots EVERY subscriber**, before the lsn guard and
-  on a non-matching change too (`live-replicator-bulk.test.ts`, `live-fanout.test.ts`).
+  sequence — or a NEW producer after a known one — stales every window; `refillWindowInLane` replaces it.
+- **A bulk write stales only its entity's readers**: windows + channel topics, `invalidate(entity)`
+  on both from `onBulk`. **A stale window's re-read re-snapshots EVERY subscriber**, before the lsn
+  guard, even on a non-match (`live-replicator-bulk`, `live-fanout` tests).
 - **A WINDOW is per TENANT**: its id is `windowId(queryHash(name, input), tenant)` (`live-tenant.ts`;
   tenant = the subscriber's `actor.orgId`). This package owns no hash. The read runs `readFor`
   (`live-definition.ts`): the node's ctx, a service actor carrying ONLY that org — never the
@@ -119,47 +113,47 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A `sid` is CLIENT data: a subscription is keyed by `(socket, sid)`**
   (`subscription-book.ts` is the only spelling). Reusing a sid the same socket holds is
   `X_SUBSCRIPTION_ID_TAKEN`.
+- **`rateLimit:` is spent once per NEW subscription** (`live-spend.ts`).
 - Truth is the server. A client is never the merge authority.
 
 ## The node, the bus and presence
 
 - `sync` is stateless: no sticky sessions, nothing on a socket survives a restart.
-- **`selectTransport(env, realtime)` is the one place `realtime.transport` + env become a bus**; the
-  KV bucket and presence TTL come back with it. The config decides, the env supplies (22.0.0):
-  `'nats'` dials the variable `urlEnv` names and refuses (`X_CONFIG_INVALID`) when unset; `'memory'`
-  refuses a set `NATS_URL` (or the named variable).
-- **`nats` is imported only by `nats-lib-client.ts`**; reconnect and re-subscription are the
-  library's job — `NatsTransport` must never grow subscription bookkeeping. What stays above the
-  port: the herd jitter (`reconnectDelayHandler`) and the KV semantics presence needs
-  (`nats-jetstream.ts`, `nats-kv.ts`). `nats-fake.ts` is a bus with server semantics.
-- **Nothing leaves `NatsTransport` uncoded** — `#translating` wraps the port's synchronous
-  `publish`/`subscribe` refusals as `X_TRANSPORT_UNAVAILABLE`; an `UltimateError` passes through.
-  `transport-parity.test.ts` asserts both transports, and that the wrap still delivers. `#ensure`
-  reuses a mid-reconnect client on purpose.
+- **`selectTransport(env, realtime)` is the one place `realtime.transport` + env become a bus** (KV
+  bucket and presence TTL come back with it). The config decides, the env supplies: `'nats'` refuses
+  (`X_CONFIG_INVALID`) when the `urlEnv` variable is unset; `'memory'` refuses a set one.
+- **`nats` is imported only by `nats-lib-client.ts`**; its reconnect re-subscribes. Only when it
+  GIVES UP (`onClosed`) does `NatsTransport` re-dial on backoff and re-bind kept subscriptions
+  (`nats-subscriptions.ts`); callers meanwhile are refused. KV semantics: `nats-jetstream`/`nats-kv`.
+- **Nothing leaves `NatsTransport` uncoded** — `#translating` wraps `publish`/`subscribe` refusals
+  as `X_TRANSPORT_UNAVAILABLE`. `#ensure` reuses a mid-reconnect client on purpose;
+  `Transport.onReconnect(listener)` (required) announces each recovery.
 - **A bucket name is checked before interpolation** (`assertBucket`, `X_TRANSPORT_PROTOCOL`); a
   presence key or member id is base64url-encoded (`encodeToken`), never validated.
 - Presence lives in `transport.shared`. The sync node is `PresenceRegistry`'s only caller:
   subscribing to a topic IS joining, repeating the frame is the heartbeat, dropping or closing is the
   leave. Expiry is silent, so the node sweeps on an interval, and **one node per topic sweeps** (lowest
-  id in the lease key's keyed set). `roster()` caps a frame at `maxMembers` (256) with `total`;
+  id in the lease's keyed set; the lease carries the roster followers record). `roster()` caps a frame at `maxMembers` (256) with `total`;
   `list()` is never capped. `total` is set on `sync` frames only.
 - **A socket the node evicts ITSELF goes through `evict(socket, code, reason)`** (the full
   `teardown`), never `sockets.remove`. **`drain()` waits for the presence leaves it started** —
   `evictInChunks` (`drain-evictions.ts`, `DRAIN_EVICT_CHUNK`, `allSettled`).
-- **The idle sweep is armed by `start()`** (a quarter of `idleTimeoutMs`, floored at 1 s, `.unref()`)
-  and measures on `Clock.monotonic()` (`lastSeenMonotonicMs`). `SocketRegistry.idle()` is a query;
-  the node evicts.
+- **The idle sweep is armed by `start()`** (`idleTimeoutMs / 4`, floored at 1 s, `.unref()`), on
+  `Clock.monotonic()`. `SocketRegistry.idle()` is a query; the node evicts.
 - **`drain()` and `stop()` both call one idempotent `release()`**; `drain()` releases after the
   sockets are gone and before `hub.close()`.
-- **Refusing new sockets and draining are two phases**: `stopAccepting()` is `accept`, `drain()` +
-  `stop()` are `close`. `listenSyncNode` unregisters both on `stop()`.
+- **Refusing and draining are two phases**: `stopAccepting()` is `accept`, `drain()` + `stop()`
+  `close`; `listenSyncNode` unregisters both on `stop()`.
 - **A hub that closed opens nothing**: `close()` sets `#closed` before the walk; `#open` closes a
   late subscription and RAISES `X_TRANSPORT_UNAVAILABLE`. `#release` takes the reserved bridge, never
   a name.
-- **An upgrade from a foreign page is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
-  (`sync-origin.ts`, core's `proveSameOrigin`); `AcceptBudget` is reserved before `authenticate`,
-  `refund()`ed on every exit that takes no socket.
-- **A socket's actor comes from `createSyncNode({ authenticate })` only**, run before
+- **An upgrade from another origin is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
+  (`sync-origin.ts`): `allowedOrigins`, when declared, is the WHOLE list; undeclared, the
+  `Host`-derived origin (and its `https` spelling when reached over plain http). The refusal names
+  the asker and the list. `x dev` keeps the reached-on origin (`admitReachedOrigin`) and adds
+  its web role's beside a declared list; a container adds nothing. `AcceptBudget` is reserved before
+  `authenticate`, `refund()`ed on every exit that takes no socket.
+- **A socket's actor comes from `syncNode({ authenticate })` only**, run before
   `server.upgrade`. `null` = 401 `X_SOCKET_UNAUTHENTICATED`; a throw = 503
   `X_SOCKET_AUTH_UNAVAILABLE`. Absent = anonymous, and `start()` warns. The actor lives only in the
   `GrantBook`.
@@ -167,57 +161,57 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   released on every path that never opens — `onUngranted` is REQUIRED on `UpgradeDeps`, and a
   `server.upgrade` that THROWS releases too. `sync-node-auth.test.ts`'s harness opens inside
   `upgrade()`, as Bun does.
-- **A grant expires; a socket does not**: expired grants are re-decided on an interval through
-  `hub.onActorChange` and `registry.reauthorize`. No `refresh` = close with `1008`; a `refresh` that
-  raises keeps the socket and retries.
-- **Every `socket.send` reads its answer**: a dropped subscribe reply marks the subscription desynced;
-  a dropped presence roster is logged (`sync.presence_roster_dropped`); `drain()` returns
-  `DrainedSocket[]` with `notified` and logs `sync.drain_frames_dropped`.
+- **A grant expires; a socket does not**: expired grants are re-decided on an interval
+  (`hub.onActorChange`, `registry.reauthorize`). No `refresh` = close `1008`; one that raises retries.
+- **Every `socket.send` reads its answer**: a dropped subscribe reply marks it desynced; a dropped
+  roster logs `sync.presence_roster_dropped`; `drain()` returns `DrainedSocket[]` (`notified`).
 - **Inbound frames run in a lane, never the socket**: `subscribe` is `sub:<sid>` or `topic:<name>`,
   everything else unlaned (`frame-lanes.ts`); a lane exists only while work is queued.
 - **A dropped `records` frame is counted AND repaired**: per-node `seq`/`epoch` per channel; a refused
-  frame marks the socket gapped, and the websocket `drain` handler sends `replay-gap`
-  (`channel_replay_gaps_total` beside `channel_frames_dropped_total`). The client re-runs the
-  channel's `catchUp`, holding frames meanwhile.
+  frame marks the socket gapped, and the `drain` handler sends `replay-gap`
+  (`channel_replay_gaps_total`). The client re-runs `catchUp`, holding frames meanwhile.
 - **A channel is a DECLARATION**: `channel(name, { params, policy, catchUp, records?, events? })`.
   Deny by default, and `policy` is REQUIRED (`X_CHANNEL_DECLARATION_INVALID`; a public channel says
   `policy: allow('public')`). Presence rides `events: true` channels.
-- **A guard that FAILS keeps the topic on re-auth** (`guardFailures`, `channel.guard_failed`); the
-  initial subscribe still refuses.
-- **A channel patch id carries the node** (`nodeId`, default a per-hub `uuid()`).
-- **An error never renders a credential**: `parsePgUrl` names `DATABASE_URL`, never the URL.
+- **A guard that FAILS on re-auth SUSPENDS the seat** (`guardFailures`): kept, silent until a pass.
+  A `null` actor on a `row` channel and a tenancy refusal are DENIALS.
+- **A seat is decided for the actor ON the socket when the guard resolves** (`#settle`); a denied
+  re-ask on a suspended seat is refused and latched. The latch is capped at `maxTopicsPerSocket`.
+- **A missed change reopens every records topic** (`ChannelHub.invalidate()`, beside both
+  `registry.invalidate()` sites; `sync-bus-handlers.test.ts`).
+- **A `recordPublisher` change (`source: 'publisher'`) feeds channels ONLY** — no commit position:
+  never `registry.deliver`, its gap stales no window; a new publisher is no gap. One producer KIND
+  per table per node (`ProducerKinds`, `X_REALTIME_PRODUCER_CONFLICT`); the x dev bridge skips a
+  claimed table (`isPublishedTable`). `ChangeEvent.table` is the relation on every producer.
+- **An error never renders a credential**: `parsePgUrl`/`parseNatsUrl` name the variable.
 
 ## Replication
 
 - Exactly one `replicator` per DB, by a session-level advisory lock. **`start()` and
-  `PgAdvisoryLock.tryAcquire` are MEMOISED** (guard and promise published synchronously, cleared on
-  settle); `stop()`/`release()` await the in-flight one. A start that FAILS hands the lock back, and
-  `running` is set only once the feed pumps.
-- **The pump has one way out, `#die`**, which records the failure, stops the confirm timer, closes and
-  nulls the connection. `start()` awaits the previous pump before it dials. **`stop()` releases
-  everything before it reports anything.**
-- **The replicator ensures its publication** (`pg-publication.ts`, from preflight): `CREATE … FOR
-  TABLE` every entity table, or `ALTER … ADD TABLE` the missing; never a DROP, never `FOR ALL
-  TABLES`. Only a server ErrorResponse becomes the refusal. No not-live declaration exists.
-- **A fix handing over `REPLICATION` carries `REPLICATION_GRANT_WARNING`** (cluster-wide grant).
-- **TLS is libpq's `sslmode`** (`pg-tls.ts`): only `verify-*` verify; the runtime never rejects
-  (`rejectUnauthorized: false`), `judgeHandshake` decides; the raw socket is DEAF after
-  `upgradeTLS` (Bun feeds it ciphertext).
-- **Only a table with NO replica identity is warned** (`NOTHING`, or keyless `DEFAULT`), before the
-  slot. A keyed DEFAULT table is correct: the window decides (`pg-identity-window.live.test.ts`).
-- **Every session pins `datestyle=ISO`, `intervalstyle=postgres`, `extra_float_digits=3`** in the
-  startup packet (`pg-connection.ts`), as Postgres' own walreceiver does.
+  `PostgresAdvisoryLock.tryAcquire` are MEMOISED**; `stop()`/`release()` await the in-flight one. A start
+  that FAILS hands the lock back; `running` is set once the feed pumps.
+- **The pump has one way out, `#die`**: failure recorded, timer stopped, connection closed, then
+  `onEnd(reason)`. `start()` awaits the previous pump. **`stop()` releases everything first.**
+- **A stream that ENDS is restarted**: feed then lock ABANDONED (synchronous, never asked);
+  `stop()` bounds both goodbyes by `STOP_DEADLINE_MS`; redial on `retryDelayMs` (injected
+  `schedule`) from `lastLsn` until `stop()`. The delay resets only when a change is PUBLISHED. A
+  rejected `publish` is one such end, and so is a LOST lock (`AdvisoryLock.onLost`), mid-dial
+  included. `running` = pumping AND no refused change owed; `onChange` is fenced per run and
+  REFUSES, never drops.
+- **A row crosses the bus through its entity's columns** (`replicator-row.ts`): `parseEnvelope`
+  revives by `entityForTable` + `$parse`, bytes as base64 — by declared kind, never by shape.
+- **Cleartext/md5 auth is answered only under `sslmode` `require`, `verify-*` or `disable`**.
+- **The replicator ensures its publication** (`pg-publication.ts`): `CREATE … FOR TABLE` every
+  entity table, or `ALTER … ADD TABLE` the missing; never a DROP, never `FOR ALL TABLES`.
+- **TLS is libpq's `sslmode`** (`pg-tls.ts`): only `verify-*` verify; the runtime never rejects,
+  `judgeHandshake` decides; the raw socket is DEAF after `upgradeTLS`.
+- **Every session pins `datestyle=ISO`, `intervalstyle=postgres`, `extra_float_digits=3`, `TimeZone=UTC`**.
 - A change lsn is `<16 hex commit position><8 hex row position>`; never order by one half, a wall
   time or a counter.
 - Slot, publication and entity names match `[a-z_][a-z0-9_]*` before interpolation — a security
-  boundary (`pg-identifier.ts`, the one `assertIdentifier`). A SQLSTATE is data: `pg-wire.ts`'s
-  `FIXES` is read with `Object.hasOwn`.
-- **A live row equals a repository row**: `pg-entity-row.ts` decodes through `@ultimat3/entity`'s
-  own `decodeRow` / `entityForTable`, so money (three physical columns), scale and every other kind
-  fold exactly as `postgresRepo` folds them.
-- A write's name rides the WAL: `pg-replication.ts` reads it off the transaction's opening
-  `pg_logical_emit_message` (prefix `WRITE_ORIGIN_WAL_PREFIX`; `START_REPLICATION` asks
-  `messages 'true'`).
+  boundary (`pg-identifier.ts`). A SQLSTATE is data: `FIXES` is read with `Object.hasOwn`.
+- **A live row equals a repository row**: `pg-entity-row.ts` decodes by `@ultimat3/entity`'s
+  `decodeRow` / `entityForTable`.
 
 ## The page
 
@@ -226,14 +220,14 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   optimistic writes, REPLAYED over synced truth whenever it moves. Installed as core's `RecordSink` on
   `pageClient().store`.
 - **Page state lives on `globalThis[Symbol.for('ultimate.realtime')]` (`page-store.ts`)**, never module
-  scope — every island is its own bundle (`page-client.test.ts` builds the package twice). Never
+  scope — every island is its own bundle (`page-client.test.ts` builds two islands). Never
   `instanceof` across copies.
 - **The signal factory is per BUNDLE**: `installRealtime({ signal, sync })` (`reactivity.ts`). No
   install and a DOM is `X_REALTIME_UNINSTALLED`; no DOM is a server render — hooks answer
   `pending`/online and create no page state. `useRecord` and `useQuery` return `AsyncState` accessors.
-- **One socket per page, built by the first live hook (`page-socket.ts`)**; `browser-socket.ts`
-  holds the framework's only `new WebSocket`. `hasPageSocket()` lives in `page-store.ts`. A principal
-  change (`rescope`) clears the store and redials.
+- **The page runtime (`page-runtime.ts`) is installed once per page, never in an island**;
+  hooks call `installedPage(hook).services`. One socket per page (`page-socket.ts`);
+  `browser-socket.ts` holds the only `new WebSocket`. `rescope` clears the store, redials.
 - **One socket per ORIGIN and principal, in a SharedWorker**: `socket-engine.ts` holds it and talks
   to tabs over `MessagePort`s (`socket-host.ts`'s virtual socket); wants are ref-counted and frames
   routed; a port silent for `REAP_AFTER_BEATS` is reaped; each tab resubscribes from its OWN cursors.
@@ -244,23 +238,27 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **`LiveClient` holds no signal** — plain reads plus `onStatus` / `onChange`; hooks wrap them.
 - **An answer that did not carry a touched row keeps that row's overlay** until the server's next row
   for it, bounded by `DEFAULT_AWAIT_SERVER_MS` (10 s).
-- **A `records` frame names the write that produced it** (`ChannelRecordsFrame.write =
-  writeDigest(idempotencyKey)`, never the key). `RecordStore.push` digests every overlay key before
-  the request leaves (`record-names.ts`); `client-channels.ts` settles inside the frame's own batch.
-  A non-digest `write` is a protocol error (`wire-channel.ts`) and dropped on the bus. Rows an answer
-  or echo partly confirmed go to `OverlayEntry.confirmed` and stop painting. `write-echo.test.ts`.
+- **A frame names the write that produced it**: `records.write`, `patch.writes` (a live patch
+  one, a resume each it replays, off `RowPatch.write` in the ring) — `writeDigest(key)`, from a
+  REQUIRED `ChangeEvent.write: string | null`. `RecordStore.push` digests each overlay key first
+  (`record-names.ts`); `client-channels.ts` / `live-rows.ts` settle in the frame's own batch. A
+  non-digest is a protocol error, dropped on the bus. Partly confirmed rows go to
+  `OverlayEntry.confirmed`. `write-echo.test.ts`, `live-write-echo.test.ts`.
 - `local(tx, input)` is pure and CONVERGENT: no I/O, no `Date.now()`, no `Math.random()`.
 - **One conflict vocabulary**: `ConflictPolicy` from `@ultimat3/core`, resolved by core's
   `resolveConflict(overlayRow, serverRow)` in `RecordStore.settle`. A server delete is not a conflict.
 - Anything a component reads is a getter or accessor. `MutatorLike.local` uses method syntax.
   `useQuery`'s input is read once, at call time.
-- Every subscription handle (`LiveHandle`, the hook accessors, `Unsubscribe`) is `Disposable`, and
-  `[Symbol.dispose]` is the same function as the release. Type claims go in `type-pins.ts`.
-- **The outbox**: only `pending` is sendable; `drain()` is one chained pass at a time; backpressure
-  over `MAX_BUFFERED_BYTES` declines rather than fails. `#epoch` is bumped before the requeue scan and
-  read every pass iteration. `#persist` hands the store SNAPSHOTS by KEY (`QueueChange`); one tab
-  drains at a time (`navigator.locks`, `page-outbox.ts`'s `exclusive`) and resets a stored `inflight`
-  to `pending` under the lock.
+- **`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.
+- Every subscription handle is `Disposable`; `[Symbol.dispose]` IS the release. Type claims go in
+  `type-pins.ts`.
+- **The outbox**: only `pending` is sendable; `drain()` is one chained pass at a time; `#epoch` is
+  bumped before the requeue scan, read every pass. `#persist` hands SNAPSHOTS by KEY; one tab drains
+  (`navigator.locks`), resetting a stored `inflight`. A `rescope` abandons the queue and bumps the
+  epoch synchronously; `enqueue` decides WHOSE queue before its first await
+  (`X_OFFLINE_QUEUE_ABANDONED`); `useMutation` fences its POST on its scope epoch. A refused disk is
+  warned `X_LOCAL_STORE_UNAVAILABLE`, never rejecting `ready`. An entry leaves disk at its ack.
 
 ## The client connection
 
@@ -273,28 +271,23 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A refusal `ack` is revived as a branded `UltimateError`** (`refusalError`, `client-frames.ts`).
 - **A reconnect replays registrations AND topics** — one `hello`, one `subscribe` per registration
   (with its cursor) and per topic.
-- **The client beats** (`heartbeatMs`, default `DEFAULT_HEARTBEAT_MS` 15 s, `0` disables): a `hello`
-  plus one subscribe per topic (the presence heartbeat). Two silent windows close with `4000`. The
-  node's `socket.skewed` compares the build the `hello` claims against its own. The server beat is
-  derived: `PresenceRegistry.heartbeatMs = max(1000, floor(ttlMs / 3))`.
+- **The client beats** (`DEFAULT_HEARTBEAT_MS` 10 s = default ttl / 3, pinned by
+  `client-heartbeat.test.ts`; `0` disables): a `hello` plus one subscribe per topic. Two silent
+  windows close with `4000`. **The node names the beat: `hello.heartbeatMs`** — `Heartbeat.follow`
+  per socket; the engine reaps ports on the longer of its own and the node's.
 - **There is ONE `backoffDelay`, `@ultimat3/core`'s, counted from 1** — `policyDelay()` maps a
-  `BackoffPolicy` onto it; `bun run flight-copies` refuses a second curve. Long form:
-  `docs/history/realtime.md`, "Moved 2026-10-01".
+  `BackoffPolicy` onto it; `bun run flight-copies` refuses a second curve.
 
 ## Rules for code here
 
 - Never a bare `Error`. Never `any`. Never `Date.now()` — take a `Clock` (`monotonic()` for durations).
-- **A test fixture standing in for a FOREIGN error extends `Error` on purpose** (`PoolTimeout`,
-  `Denied`, `ThirdPartySdkError`): it simulates a value this package did not construct. The rule
-  governs what this package **throws**, never what a test hands it.
 
 ## The page boot
 
-Browser bytes per hook, as last measured: `docs/history/realtime.md`. Re-measure before quoting.
-
 - **The disk boot is ONE page script (`boot.ts`, `./boot`)**, served at `/_x/page-boot/<hash>.js`
-  on a document with the scope tag and a realtime island; it wipes every other principal's stored
-  scope, then restores. `booted` reads its promise off `globalThis[Symbol.for('ultimate.page-boot')]`.
+  on a document with the scope tag and a realtime island; it installs the runtime, wipes every other
+  principal's stored scope (read at the wipe), then restores. `booted` reads its promise off
+  `globalThis[Symbol.for('ultimate.page-boot')]`. No boot: islands load its chunk.
 - **An island never carries the outbox**: `boot.ts` builds it; `useMutation` and the page socket read
   it through `outbox-slot.ts` after `page.booted`. No boot ⇒ a refused write is rejected, not queued.
 
@@ -303,27 +296,26 @@ Browser bytes per hook, as last measured: `docs/history/realtime.md`. Re-measure
 `index.ts` / `server.ts` are the two barrels. Server side: `sync-node.ts` (+ `sync-auth`,
 `sync-frames`, `sync-upgrade`, `sync-listen`, `drain-evictions`), `channel.ts`, `presence.ts`,
 `socket.ts`, `live-query.ts` (+ `live-definition`, `live-refusal`, `live-tenant`, `live-resume`, `query-window`, `live-fanout`, `window-lock`,
-`subscriber-gate`, `policy-gate` — the only authz seam — and `matcher-bridge`), `replicator.ts` /
+`subscriber-gate`, `policy-gate` — the only authz seam — and `matcher-bridge`), `replicator.ts` (+ `replicator-envelope`) /
 `live-replicator.ts`, the Postgres client (`pg-*.ts`, `pgoutput.ts`), the bus (`nats-*.ts`,
 `transport-env.ts`, `fanout.ts`). Client side: `client*.ts`, `socket-engine.ts` / `socket-host.ts` /
 `sync-worker.ts`, `record-*.ts`, `page-*.ts`, `boot.ts`, `offline-queue.ts`, `use-*.ts`,
 `reactivity.ts`. Shared: `sync-protocol.ts` (the wire), `cursor.ts`, `change-buffer.ts`,
-`thundering-herd.ts`, `live-contract.ts`, `json.ts` (no hash), `type-pins.ts`. Each file's header
-states its one job.
+`thundering-herd.ts`, `live-contract.ts`, `json.ts` (no hash), `type-pins.ts`.
 
 ## Commands
 
 ```
-bun test packages/realtime/src            # from the REPO ROOT, never from packages/realtime
+bun test packages/realtime/src   # from the REPO ROOT
 bun run typecheck
 ```
 
-`bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers and Bun reads it from the cwd.
+`bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers; Bun reads it from the cwd.
 
 Changing a frame shape means a fixture in `sync-protocol.test.ts` (the round-trip test fails
 without one) and bumping `PROTOCOL_VERSION` **when an old frame becomes unreadable in either
 direction**. `decode` is a whitelist: an additive optional field, or removing a field read through
-`list()`, is free; removing a field read through `str()`/`num()` (which throw) is a bump. Read the
-field's line in `decode` before claiming a removal is free.
+`list()`, is free; removing a field read through `str()`/`num()` (which throw) is a bump.
 
-Why each rule above is shaped the way it is: [`docs/history/realtime.md`](../../docs/history/realtime.md).
+Why each rule is shaped so, and browser bytes per hook (re-measure before quoting):
+[`docs/history/realtime.md`](../../docs/history/realtime.md).