@ultimat3/realtime 24.0.0 → 25.1.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,12 +21,12 @@ 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`.
 - A browser file imports core from `@ultimat3/core/page` (`packages/core/src/page-bundle.test.ts`).
@@ -34,10 +34,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 ## Numbers and ceilings
 
 - **Every numeric option is refused when it is not FINITE** — `@ultimat3/core`'s `finiteOption()`.
-  `bun run finite-bounds` reads zero here but cannot see an option with no `??` default, so audit
-  by reading the option interfaces. `SyncGrant.expiresAt` is app DATA, 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
@@ -57,7 +56,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   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
@@ -103,9 +102,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **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 — or a NEW producer after a known one — stales every window; `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`).
+- **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
@@ -114,6 +113,7 @@ 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
@@ -122,9 +122,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **`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`**; reconnect and re-subscription are the
-  library's — `NatsTransport` never grows subscription bookkeeping. Above the port: the herd jitter
-  and presence's KV semantics (`nats-jetstream.ts`, `nats-kv.ts`). `nats-fake.ts` has server semantics.
+- **`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.
@@ -138,13 +138,12 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **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.
@@ -154,7 +153,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   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 `createSyncNode({ authenticate })` only**, run before
+- **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`.
@@ -162,18 +161,15 @@ 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.
@@ -182,14 +178,17 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **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).
-- **A channel patch id carries the node** (`nodeId`, default a per-hub `uuid()`).
+  `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**; `stop()`/`release()` await the in-flight one. A start
+  `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.**
@@ -206,7 +205,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   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`**.
+- **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
@@ -221,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.
@@ -239,27 +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. `#epoch` is
-  bumped before the requeue scan and read every pass iteration. `#persist` hands the store
-  SNAPSHOTS by KEY; one tab drains at a time (`navigator.locks`) and resets a stored `inflight`
-  under the lock. A `rescope` abandons the queue, clears the single-flight slot and bumps the
-  outbox's epoch synchronously; `enqueue` decides WHOSE queue before its first await and refuses
-  otherwise (`X_OFFLINE_QUEUE_ABANDONED`), and `useMutation` fences its own await (the POST) on the
-  scope epoch it was called under. A wipe or open the disk refuses is warned
-  `X_LOCAL_STORE_UNAVAILABLE` and never rejects `ready`. At-least-once: an entry leaves the disk
-  when its ack is written.
+- **`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
 
@@ -285,12 +284,10 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 
 ## 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 — the scope kept is read at the wipe, after the disk opens, never at boot start — 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.
 
@@ -309,7 +306,7 @@ Browser bytes per hook, as last measured: `docs/history/realtime.md`. Re-measure
 ## 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
 ```
 
@@ -320,4 +317,5 @@ without one) and bumping `PROTOCOL_VERSION` **when an old frame becomes unreadab
 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.
 
-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).