@ultimat3/realtime 30.9.0 → 31.0.0

package/CLAUDE.md

@@ -1,6 +1,7 @@
 # @ultimat3/realtime — agent notes
 
 Tier 3 package. Channels, live queries, local-first sync. One protocol for all three.
+A rule marked `†` has its full text in [`docs/history/realtime-rules.md`](../../docs/history/realtime-rules.md).
 
 ## Boundary
 
@@ -20,13 +21,17 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   the hub, the registry or the fanout (`nats` requires `stream/web`, which a browser build cannot
   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.
-- **`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.
+  boot and the SharedWorker entry; `./adapter` the bus driver's port plus the boot's installer.
+- **`error-titles.ts` holds the PAGE codes and titles** (every code a browser raises or receives on
+  the wire), **`error-titles-server.ts` the server-only ones** (replication, topology, producer
+  conflict — never on the wire); `errors.ts` composes `REALTIME_OWNED_ERROR_CODES` /
+  `REALTIME_ERROR_TITLES` from both. `page-errors.ts` the browser refusals, `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`). A new code: `bun run new-error-code …
+  --browser | --server-only`, exactly one (`scripts/lib/error-code-realm.ts`).
+- **`sideEffects` is `["./src/error-titles.ts", "./src/error-titles-server.ts"]`**; the server one is
+  imported bare by `errors.ts` and `server.ts`, never a page module (`error-titles.test.ts`: no
+  server title in an island chunk); 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`).
@@ -57,37 +62,31 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `reauthorize` calls `book.retenant(socket)`.
 - **A cap is a RESERVATION taken before the first await**: `SubscriptionBook.reserve(socket, sid)`
   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.
+  `ChannelHub.subscribe` does the same for its caps. Released in a `finally`, idempotent.
 - **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
-  the same 503 + `retry-after-ms` and spends no second `tryAccept()`.
+  `authenticate` and right before `server.upgrade`: the recheck sheds with the same 503 +
+  `retry-after-ms`, no second `tryAccept()`.
 
 ## Live queries
 
-- Policy is evaluated **once per subscriber**, never once per query (`live-query.test.ts`, and
-  `live-definition.test.ts` for a real `query({ live: true })`). Every policy call in `live-query.ts`
-  takes a `Subscriber`.
-- **A name nothing registered is `X_LIVE_QUERY_UNKNOWN`**, fix `x queries list --json`. The
-  registry is never enumerated over the wire.
+- Policy is evaluated **once per subscriber**, never once per query (`live-query.test.ts`,
+  `live-definition.test.ts`); every policy call in `live-query.ts` takes a `Subscriber`.
+- **An unregistered name is `X_LIVE_QUERY_UNKNOWN`** (`x queries list --json`); the registry is
+  never enumerated over the wire.
 - **One build per `(query, input)`**: `target.live()` returns the descriptor and runs the read
-  (`LiveQuery.execute`), never memoised.
+  (`LiveQuery.execute`), unmemoised.
 - `liveQueryDefinition` caches per query id the compiled source, shape, matcher and shared window —
-  never a decision. The shared half is built with `enforce: false` on purpose; `authorize` runs per socket.
+  never a decision: the shared half is `enforce: false`, `authorize` runs per socket.
 - **The row policy sees the WHOLE row from the shared window.** A patch whose row the window does not
   hold is WITHHELD (not denied, not a failure). A delta resume onto an unread entry fills it first
   (`entry.lsn === ''`).
-- **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, 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
-  own subscribers; lanes chain on a settled shadow of each task.
-- **Two reads of one entry are ordered by a READ GENERATION**, never by an lsn (`QueryEntry.lsn` may
-  be `''`): `entry.generation` / `entry.applied` is an identity check. The lsn guard stays for the
-  other question — a read that resolved behind a change the fanout already folded.
+- **A denial is a decision; everything else is a failure** (`isPolicyDenial`): a denied re-check
+  refuses the subscription, a failed one keeps it and counts `gateFailures`. †
+- **One serial lane per query id (`WindowLock`) is the only thing that orders a fanout**; a lane at
+  `maxLaneDepth` (1,024) sheds: window staled, `changesShed` counted. †
+- **Two reads of one entry are ordered by a READ GENERATION**, never an lsn (`QueryEntry.lsn` may be
+  `''`): `entry.generation` / `entry.applied`. The lsn guard answers the other question — a read
+  that resolved behind a change the fanout already folded.
 - **The definition's read is once per entry**: a cold subscriber joins the in-flight read (a share,
   cleared on settle), and the result lands in the lane and never backwards.
 - **The shared read carries a deadline and frees the SLOT**: `startRead` races it against
@@ -96,51 +95,44 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   a non-positive or non-finite value takes the default (`query-window.test.ts`).
 - The retained change window stores **pre-policy** patches; resume re-filters them per subscriber,
   outside the lane, against the live window.
-- **`desynced` is a mark with a reader**: the next delivery serves a fresh snapshot out of the shared
-  window and only then clears it. **`result.refill` is checked BEFORE the mark** — a guessed window
-  never clears a mark (`live-fanout.test.ts`). **A quiet query has three more readers**
-  (`sync-drain.test.ts`): Bun's `drain` (`registry.repair`, which waits out a read in flight), a read
-  that lands, and the node's sweep (`registry.repairMarked`, on the idle interval), which also re-reads
-  a stale window that owes one, once a pass. Never out of a window stale or with a read not settled.
+- **`desynced` is a mark with a reader**: the next delivery re-snapshots out of the shared window,
+  then clears it; `result.refill` is checked BEFORE the mark. A quiet query's three other readers
+  (drain, a landed read, `repairMarked`): `docs/history/realtime.md` (2026-11-09).
 - **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 its entity's readers**: windows + channel topics, `invalidate(entity)`
-  on both from `onBulk` (channels: not a `recordPublisher` table). **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`). The read runs `readFor`
-  (`live-definition.ts`): the node's ctx, a service actor carrying ONLY that org — never the
-  subscriber. A cursor naming another window is a cold start; `reauthorize` re-seats a
-  subscription whose actor changed org (`live-tenancy.test.ts`; `docs/history/realtime.md`).
-- **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`.
+  on both from `onBulk` (channels: not a `recordPublisher` table). **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).
+- **`startLiveReplicator` SUBSCRIBES to `entity.row`/`entity.bulk`**, never a slot: `stop()`
+  releases its own; two both hear a write (`live-replicator.test.ts`). Its handlers never throw.
+- **A WINDOW is per TENANT** (`windowId(queryHash, tenant)`, `live-tenant.ts`); the read runs as a
+  service actor carrying ONLY that org, never the subscriber. †
+- **A `sid` is CLIENT data: a subscription is keyed by `(socket, sid)`** (`subscription-book.ts`);
+  reusing one 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, { use })` is the one place config + env become a bus** (bucket
-  and presence TTL come back). `'nats'` refuses (`X_CONFIG_INVALID`) an unset `urlEnv` variable;
-  `'memory'` a set one. `use`: `'sockets'`/`'feed'` await a 15 s dial, then
+- **`selectTransport(env, { use })` is the one place env becomes the DEFAULT bus**: `NATS_URL` set
+  is NATS, unset in-process (bucket and presence TTL come back); any other bus is `runtime.ts`'s
+  `transport`, installed with `installChannelTransport` from `./adapter` — never a setter. `use`: `'sockets'`/`'feed'` await a 15 s dial, then
   `X_TRANSPORT_UNAVAILABLE`; `'publish'` dials in background. Never `waitOnFirstConnect`
   (retries forever). A publish with no live connection is refused.
-- **`nats` is imported only by `nats-lib-client.ts`**; its reconnect re-subscribes. When it GIVES
-  UP (`onClosed`) `NatsTransport` re-dials on backoff and re-binds.
+- **`nats` is imported only by `nats-lib-client.ts`**; its reconnect re-subscribes. GIVEN UP
+  (`onClosed`), `NatsTransport` re-dials on backoff and re-binds.
 - **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 key or member id is base64url-encoded (`encodeToken`).
 - **A socket closed during its presence write takes the write back** (`joinPresence`, asked after the
   awaits; `sync-frames.test.ts`).
-- 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'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.
+- **An upgrade from another origin is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
+  (`sync-origin.ts`); `allowedOrigins` is the WHOLE list. Detail: `docs/history/realtime-agent-notes.md`.
 - **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`).
@@ -153,12 +145,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **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 another origin is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
-  (`sync-origin.ts`): `allowedOrigins`, when declared, is the WHOLE list (`sec-fetch-site` unread); 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.
+- Presence lives in `transport.shared`; the sync node is `PresenceRegistry`'s only caller, and
+  **one node per topic sweeps**. Detail: `docs/history/realtime-agent-notes.md`.
 - **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
@@ -195,14 +183,18 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - Exactly one `replicator` per DB, by a session-level advisory lock. **`start()` and
   `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.
+- **The pump has one way out, `#die`**: failure, timer, connection, then `onEnd`. **A walsender
+  that stops answering is dead** — 3 intervals read-silent, or a confirm unsettled
+  (`pg-replication-liveness.ts`): destroyed, no goodbye. A run is fenced by its connection.
+- **A stream that ENDS, or a LOST lock, is restarted** from `lastLsn` on `retryDelayMs`; a lost
+  connection (`connectionLost`) redials at once, then ≤ 2 s (`replicator-reconnect.ts`); feed then
+  lock ABANDONED; `running` = pumping and no refused change owed (history, 2026-11-09).
+- **A slot is asked its `wal_status`**: `lost` is `X_REPLICATION_SLOT_INVALIDATED`; one created under
+  a resume is `X_REPLICATION_SLOT_RECREATED`, drops `from`, and owes `x.change.-resync` (a node
+  answers it as a reconnect) till published.
+- **A slot still held is waited for before START_REPLICATION** (`pg-slot-release.ts`): a walsender
+  frees it AFTER the goodbye, so preflight reads `active_pid` and polls on the server's clock, ~5 s
+  bound, then lets 55006 refuse (`pg-slot-release.test.ts`, the held-slot live test).
 - **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`**.
@@ -210,7 +202,8 @@ 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`, `TimeZone=UTC`**.
+- **Every session pins `datestyle=ISO`, `intervalstyle=postgres`, `extra_float_digits=3`, `TimeZone=UTC`**,
+  and asks for TCP keepalives (10 s/5 s/3): a lock holder lost without a FIN frees it in ~25 s.
 - 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
@@ -234,10 +227,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **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.
-  No `SharedWorker` → the in-page host runs the same engine over a `MessageChannel`.
+- **One socket per ORIGIN and principal, in a SharedWorker** (`socket-engine.ts`); no `SharedWorker`
+  → the same engine in-page. †
 - **The socket is READ-ONLY (protocol 3)**. A write is `useMutation`: the twin into the overlay, then
   the stamped pin (`renderedActionPin`) or `POST actionPath(name)`, via `clientTransport`, keyed;
   the answer's records are adopted inside the transport call, before `settle`. An `ack` is only a refusal.
@@ -265,10 +256,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 
 ## The client connection
 
-- **The client owns its reconnect**: a closed socket arms ONE timer through the injected `Scheduler`
-  that calls `connect()`. `onClose` nulls `#socket`, schedules only when nothing is armed (a
-  `reconnect` frame's slot wins), and speaks only for its own socket; `close()` cancels. A dial that
-  throws in the timer is reported through `onError` (default `console.error`) and arms the next.
+- **The client owns its reconnect**: ONE timer through the injected `Scheduler`; `close()`
+  cancels. Detail: `docs/history/realtime-agent-notes.md`.
 - **`connect()` closes the socket it replaces**; `onOpen`, `onMessage` and `onClose` all carry the
   identity guard.
 - **A refusal `ack` is revived as a branded `UltimateError`** (`refusalError`, `client-frames.ts`).
@@ -278,8 +267,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `client-heartbeat.test.ts`; `0` disables): a `hello` plus one subscribe per topic. Two silent
   windows after an UNANSWERED beat 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.
+- **There is ONE `backoffDelay`, `@ultimat3/core`'s, counted from 1** — `policyDelay()` passes a
+  `ReconnectBackoff` (core's `RetryPolicy` minus `attempts`/`timeBudgetMs`) to it; `bun run flight-copies` refuses a second curve.
 - Never a bare `Error`. Never `any`. Never `Date.now()` — take a `Clock` (`monotonic()` for durations).
 
 ## The page boot
@@ -290,6 +279,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `Symbol.for('ultimate.page-boot')`. No boot: islands load its chunk.
 - **An island never carries the outbox**: `boot.ts` builds it; `useMutation`, `useOutbox`, the page socket
   read it through `outbox-slot.ts` after `page.booted`. No boot ⇒ a refused write is rejected, not queued.
+- **The outbox's ceiling is `realtime.maxQueued`**, read by `boot.ts` off `<meta name="ultimate-outbox-max">`.
 
 ## Map
 
@@ -303,7 +293,7 @@ side: `client*.ts`, `socket-*.ts`, `sync-worker.ts`, `record-*.ts`, `page-*.ts`,
 ## Commands
 
 ```
-bun test packages/realtime/src   # from the REPO ROOT
+bun test ./packages/realtime/   # from the REPO ROOT; the ./ keeps examples/dummy out
 bun run typecheck
 ```
 

package/README.md

@@ -74,15 +74,16 @@ class — stay on `.`.
 
 | Concern | Entry | Export |
 |---|---|---|
-| tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry`; `publishChannelEvent` — a channel event from a job or an action — with the boot's `setChannelTransport` and the test seam `resetChannelTransport` |
+| tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry`; `publishChannelEvent` — a channel event from a job or an action, on the bus the boot installed |
+| a bus driver | `./adapter` | `Transport` and its parts (`TransportHandler`, `TransportSet`, `TransportSetEntry`, `TransportSubscription`), the errors a driver throws (`TransportUnavailableError`, also on `.`; `TransportProtocolError`, only on this entry), and `installChannelTransport` — the boot's installer and `@ultimat3/testing`'s seam, on no other entry. The offline stores (`LocalStore` / `openLocalStore` / `pageLocalStore` / `memoryLocalStore()`, `QueueStore` / `memoryQueueStore()`, `RecordStoreOptions`, `SignalFactory`) are on `.`: no `runtime.ts` field takes one. An app hands its bus to `transport` in `apps/<app>/runtime.ts`, never to the installer |
 | tier 2 | `./server` | `LiveQueryRegistry`, `memoryChangeFeed()`, `postgresChangeFeed()`, `selectChangeFeed`, `changeFeedReplicator`, `postgresAdvisoryLock()`, `matcherFor` |
 | replication | `./server` | `parsePgUrl`, `bunPgStream`, `entityRow`, `changeLsn`, `commitPositionOf` |
-| the in-process change source | `./server` | `startLiveReplicator` — a repository's own writes as `ChangeEvent`s, for the embedded database `x dev` runs on (PGlite has no walsender). `ChangeEvent.table` is the entity's TABLE on it as on the WAL decoder and `recordPublisher`, so an `entity(name, { table })` reaches channels and live windows (25.0.0). Moved from `@ultimat3/testing`, which no longer re-exports it |
+| the in-process change source | `./server` | `startLiveReplicator` — a repository's own writes (core's `entity.row` / `entity.bulk` bus events, subscribed) as `ChangeEvent`s, for the embedded database `x dev` runs on (PGlite has no walsender). `ChangeEvent.table` is the entity's TABLE on it as on the WAL decoder and `recordPublisher`, so an `entity(name, { table })` reaches channels and live windows (25.0.0). Moved from `@ultimat3/testing`, which no longer re-exports it |
 | fanout | `./server` | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
 | the bus, behind `NatsTransport` | `./server` | the port — `NatsClient`, `NatsMessage`, `NatsSubscription`, `NatsConnect`, `NatsTarget`, `parseNatsUrl` — plus `openNatsClient` (the `nats` adapter), `NatsKvSet`, `ensureKvBucket`, `kvGet`/`kvLast`/`kvWrite`, `assertBucket`, `encodeToken`/`decodeToken`, and `FakeNatsBroker`/`fakeNatsConnect` for tests |
-| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
-| the page's record store | `.` | `RecordStore` — one record per `type:key`, synced truth plus the optimistic overlay — `recordKey`, `LocalTx`, `RowWindows`, `applyPatches`/`orderAfterPatches` |
-| the outbox | `.` | `OfflineQueue`, `memoryQueueStore()` — replayed over HTTP from plan 101 slice 12. The conflict vocabulary is `ConflictPolicy` from `@ultimat3/core`; realtime declares none |
+| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `Scheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
+| the page's record store | `.` | `RecordStore` — one record per `type:key`, synced truth plus the optimistic overlay — `recordKey`, `LocalTx`, `applyPatches`/`orderAfterPatches` |
+| the outbox | `.` | `OfflineQueue` (its store is `./adapter`'s `QueueStore`) — replayed over HTTP from plan 101 slice 12. The conflict vocabulary is `ConflictPolicy` from `@ultimat3/core`; realtime declares none |
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `syncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
@@ -90,7 +91,7 @@ class — stay on `.`.
 | channel records, no replicator | `./server` | `recordPublisher` — an app's committed rows as channel `records`, sequenced per producer ([below](#channel-records-with-no-replicator)) |
 | channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
 | first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`, for an island that reads the store or the outbox: the boot's restore and the open outbox, capped (#506). An island taking only `useChannel` / `usePresence` / `useConnection` never awaits it and is never hidden, nor is one taking `useQuery` / `useRecord` in an app that declares no `persist: true` entity |
-| offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `memoryLocalStore()` |
+| offline | `.` | `pageOutbox`, `localOutbox`, `listenForDrain`; the durable store is `./adapter`'s |
 | the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 
 ## `channelRef` — a channel an island can hold
@@ -120,7 +121,9 @@ The server half, in its own file, names the entity and the policy on the same re
 `ref.topic(params)` is the one spelling of the topic both halves use (`org-posts.<orgId>`), and
 `bun run channel-literals` refuses a hand-built topic anywhere else. A bad name or a repeated param
 is `X_CHANNEL_DECLARATION_INVALID` at declaration. `catchUp` is read on every access, so a query
-whose name `registerQueries()` stamps at boot is picked up. The reference app's
+whose name `defineApi({ queries })` stamps at boot is picked up. A `catchUp` given as the query itself
+must carry the channel's own `policy` object — it is served with the channel params as input — or
+`channel()` refuses it (`X_CHANNEL_CATCHUP_POLICY_MISMATCH`); a name-only ref is not checked. The reference app's
 [`app/posts/channel-ref.ts`](../../examples/dummy/apps/web/app/posts/channel-ref.ts) is the idiom.
 
 ### What `useChannel()` reports
@@ -143,7 +146,8 @@ join and it reads `joining` for as long as it is held.
 
 The `ChannelHub` lives in the `sync` role. Everything else publishes an event with
 `publishChannelEvent` (`./server`), on the bus the boot installed for the process — every role's
-`startServices` calls `setChannelTransport` with the transport `selectTransport` chose.
+`startServices` installs the process's transport (`installChannelTransport`, `./adapter`): `runtime.ts`'s `transport`, else
+the one `selectTransport` chose.
 
 ```ts
 import { allow } from '@ultimat3/policy';
@@ -165,10 +169,10 @@ export const announce = (orgId: string, id: string): Promise<void> =>
 
 | Fact | Rule |
 |---|---|
-| who delivers | every `sync` node bridged to that topic, to its members' `onEvent`. Under `x dev` the node is in this process and shares the bus; across processes the bus is NATS (`realtime.transport: 'nats'`) |
+| who delivers | every `sync` node bridged to that topic, to its members' `onEvent`. Under `x dev` the node is in this process and shares the bus; across processes the bus is NATS (`NATS_URL` set) or the app's own (`transport` in `apps/<app>/runtime.ts`) |
 | after COMMIT | nothing here can see a transaction: an event sent from inside one is on every page before a rollback |
 | at-most-once | never stored, never replayed — a member that was offline does not get it. Send "re-read", never state. A bus that refuses the send rejects (`X_TRANSPORT_UNAVAILABLE`); catch it where an event is not worth failing the write for |
-| nothing booted | a unit test or a bare script publishes onto a heap bus nobody hears, and does not throw. A test that wants delivery calls `setChannelTransport(bus)` with the bus its `ChannelHub` holds, and `resetChannelTransport()` after |
+| nothing booted | a unit test or a bare script publishes onto a heap bus nobody hears, and does not throw. A test that wants delivery swaps the bus through `@ultimat3/testing`'s override seam, which installs the bus its `ChannelHub` holds and releases it after |
 | `realtime.enabled: false` | still safe to call: the bus exists, no node subscribes |
 | refusals | `X_CHANNEL_DECLARATION_INVALID` on a channel declared without `events: true`; `X_TOPIC_FORBIDDEN` for a param that is no topic segment |
 | no replicator | a node that serves no `live: true` query and no `records` channel reads no change, boots `live=none` on a real database, and is never `X_REALTIME_TOPOLOGY` |
@@ -181,12 +185,12 @@ Without one, `recordPublisher` (`./server`) is how an app puts its own **committ
 bus; every node turns them into `records` frames exactly as it does a replicated change (#682).
 
 ```ts
-import type { ChannelEntity, Row } from '@ultimat3/realtime';
+import type { ChannelEntity, LiveRow } from '@ultimat3/realtime';
 import { recordPublisher, type Transport } from '@ultimat3/realtime/server';
 
 declare const transport: Transport; // the process's bus — the one `selectTransport` chose
 declare const runs: ChannelEntity; // an `entity()` a `channel(…, { records: [runs] })` lists
-declare const finished: readonly Row[];
+declare const finished: readonly LiveRow[];
 
 // Once per process, at boot, naming every entity it will publish.
 const publisher = recordPublisher({ transport, entities: [runs] });
@@ -403,6 +407,7 @@ wire.
 | sockets per actor; an anonymous network (IPv4 exact, IPv6 /64) gets 8 × (`ANONYMOUS_SOCKET_MULTIPLIER`) — one NAT is many people | 16 (`DEFAULT_MAX_SOCKETS_PER_ACTOR`); 128 per anonymous network | `syncNode({ maxSocketsPerActor })`; the boot passes `realtime.maxSocketsPerActor` | `429 X_SOCKET_LIMIT` |
 | live subscriptions per tenant | unset | `new LiveQueryRegistry({ maxPerTenant, tenantOf })` — **both**, or it arms nothing | `X_SUBSCRIPTION_LIMIT` |
 | distinct `(query, input)` pairs per node | 10,000 | `new LiveQueryRegistry({ maxEntries })` | `X_SUBSCRIPTION_LIMIT` |
+| changes queued in one live window's lane | 1,024 (`DEFAULT_MAX_LANE_DEPTH`) | `new LiveQueryRegistry({ maxLaneDepth })` | nothing refused: the change is shed for that window, which is staled and re-read by the next queued change; counted as `registry.changesShed` |
 | how long one entry's SHARED snapshot read may hold its slot | 30s | `new LiveQueryRegistry({ readDeadlineMs })` | `X_TIMEOUT`, to that read's caller AND every subscriber joined to it |
 | channel topics per socket | 64 | `new ChannelHub({ maxTopicsPerSocket })` | `X_SUBSCRIPTION_LIMIT` |
 | distinct channel topics per node | 10,000 | `new ChannelHub({ maxTopicsPerNode })` | `X_SUBSCRIPTION_LIMIT` |
@@ -513,7 +518,7 @@ verdict only. A proxy that adds none of them is indistinguishable from a direct
 header-less proxy must not route the health paths.
 
 The client dials itself back. A closed socket arms one timer — the node's delay when a `reconnect`
-frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `BackoffPolicy` — and that timer calls `connect()`, which re-subscribes
+frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `backoff` (core's `RetryPolicy` fields `base`/`max`/`factor`/`curve`/`jitter`) — and that timer calls `connect()`, which re-subscribes
 every registration **and re-announces every topic**. Topic membership is state on the node's socket
 and `hello` carries none of it, so without that half a channel goes silent from the first reconnect
 onwards while its handler is still installed — and its presence membership is swept, because
@@ -579,6 +584,14 @@ wire twice by a reconnect that raced an ack.
 (`X_LOCAL_STORE_UNAVAILABLE`, default `console.warn`); the outbox then queues in memory for that
 principal.
 
+`maxQueued` — the outbox's ceiling, on `pageOutbox({ maxQueued })` (the page's outbox: the first
+call in a tab builds it) or `localOutbox({ maxQueued })`, and carried to every queue the outbox
+opens, the memory fallback included. A whole number ≥ 1 (`X_INVARIANT` where the outbox is built);
+absent, no ceiling. An app sets it as `realtime: { maxQueued }` in `app.config.ts`; the page boot reads it off the document (`<meta name="ultimate-outbox-max">`, core's `CLIENT_OUTBOX_MAX_META`). It counts writes still to send (a refused one kept for the UI is not); past it
+a NEW write is refused, `X_OFFLINE_QUEUE_FULL`, to the mutation that
+made it — a key already queued collapses as always, and nothing queued is ever dropped to make room.
+`OfflineQueue.open(store, { maxQueued })` is the same rule one level down.
+
 ### Limits, stated plainly
 
 - **The change window is per node, and a `qid` window can only be.** A client that reconnects to a
@@ -812,26 +825,24 @@ principal.
   synchronous): the sockets are closed outright with no goodbye written, the feed first so it is
   silent before the lock is given up. `stop()` asks politely and gives each goodbye
   `STOP_DEADLINE_MS` (5 s) before abandoning it. The restart delay resets only once a change has
-  been published, so a change the bus refuses every time backs off to `maxMs` instead of
+  been published, so a change the bus refuses every time backs off to `max` instead of
   redialling at the base; `stats().failure` names its entity and lsn, and `running` stays `false`
   until it goes out.
 - **`postgresAdvisoryLock()` is the production `AdvisoryLock`** — `SELECT
   pg_try_advisory_lock(hashtext('x:replicator:<slot>'))` on its own session. Session-scoped, so a
   crashed replicator releases it automatically: no lease renewal, no fencing token, no split brain.
   `memoryAdvisoryLock()` remains the single-process default for `x dev` and tests.
-- **`selectTransport(env, realtime)` decides which transport a boot fans out on** — and since
-  22.0.0 the CONFIG decides it, not the environment: `realtime` is `app.config.ts`'s
-  `{ transport, urlEnv }`. It returns `{ transport, mode, detail, bucket, presenceTtlMs, connect }`:
-  `'memory'` → `InProcessTransport` and `mode: 'embedded'`; `'nats'` → a `NatsTransport` dialling
-  the variable `urlEnv` names, on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so
-  two apps on one cluster do not share one presence namespace), validated here rather than on
-  first connect. Both mismatches refuse with `X_CONFIG_INVALID`: `'nats'` with that variable unset,
-  and `'memory'` with `NATS_URL` (or the named variable) set — an operator who set one expected
-  fanout across nodes. Until 22.0.0 `NATS_URL` alone decided and both keys were read by nothing.
+- **`selectTransport(env)` decides the default transport a boot fans out on** — since 31.0.0 the
+  ENVIRONMENT decides it: `NATS_URL` set (not blank) → a `NatsTransport` on the KV bucket
+  `NATS_KV_BUCKET` names (default `x_presence`, so two apps on one cluster do not share one
+  presence namespace), validated here rather than on first connect; unset → `InProcessTransport`,
+  `mode: 'embedded'`. Any other bus is `transport` in `apps/<app>/runtime.ts`, which the boot takes
+  instead. `app.config.ts`'s `realtime.transport`/`urlEnv` (22.0.0–30.x) are gone. It returns
+  `{ transport, mode, detail, bucket, presenceTtlMs, connect }`.
   `presenceTtlMs` comes back with it because the bucket's whole-stream age limit was derived from
   it — a `PresenceRegistry` given a different number would report members leaving that never left.
   Selection is pure; `connect()` is the dial. **What the process does with the bus decides whether
-  that dial is waited for** — `selectTransport(env, realtime, { use })`, `BusUse`:
+  that dial is waited for** — `selectTransport(env, { use })`, `BusUse`:
   `'sockets'` (a `sync` node; the default) awaits it and the presence bucket, retried on backoff for
   `connectWithinMs` (default `BUS_CONNECT_WAIT_MS`, 15 s) and then `X_TRANSPORT_UNAVAILABLE`;
   `'feed'` (the replicator) awaits it and asks JetStream for nothing; `'publish'` (`web`, `worker`,
@@ -963,24 +974,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
-| `CursorStaleError` (extends `RealtimeError`) | `X_CURSOR_STALE` | `src/page-errors.ts` |
-| `FrameRateLimitError` (extends `RealtimeError`) | `X_FRAME_RATE_LIMIT` | `src/errors.ts` |
-| `LiveQueryUnknownError` (extends `RealtimeError`) | `X_LIVE_QUERY_UNKNOWN` | `src/errors.ts` |
-| `LiveRowUnidentifiedError` (extends `RealtimeError`) | `X_LIVE_ROW_UNIDENTIFIED` | `src/errors.ts` |
 | `OfflineQueueAbandonedError` (extends `RealtimeError`) | `X_OFFLINE_QUEUE_ABANDONED` | `src/page-errors.ts` |
-| `ProtocolVersionError` (extends `RealtimeError`) | `X_PROTOCOL_VERSION` | `src/page-errors.ts` |
-| `RealtimeError` | any `RealtimeErrorCode` — `REALTIME_ERROR_CODES`; the base of every other class here, thrown directly for a code none of them covers | `src/realtime-error.ts` |
-| `RealtimeUninstalledError` (extends `RealtimeError`) | `X_REALTIME_UNINSTALLED` | `src/page-errors.ts` |
-| `RebaseConflictError` (extends `RealtimeError`) | `X_REBASE_CONFLICT` | `src/page-errors.ts` |
-| `RecordRejectedError` (extends `RealtimeError`) | `X_RECORD_REJECTED` | `src/page-errors.ts` |
-| `ReplicaIdentityError` (extends `RealtimeError`) | `X_LIVE_REPLICA_IDENTITY` | `src/replication-errors.ts` |
-| `ReplicationFailedError` (extends `RealtimeError`) | `X_REPLICATION_FAILED` | `src/replication-errors.ts` |
-| `ReplicationProtocolError` (extends `RealtimeError`) | `X_REPLICATION_PROTOCOL` | `src/replication-errors.ts` |
+| `RealtimeError` | any `RealtimeErrorCode`; the base of every other class here, thrown directly for a code none of them covers | `src/realtime-error.ts` |
 | `ReplicatorSlotHeldError` (extends `RealtimeError`) | `X_REPLICATOR_SLOT_HELD` | `src/replication-errors.ts` |
-| `ServerRenderLiveError` (extends `RealtimeError`) | `X_LIVE_SERVER_RENDER` | `src/page-errors.ts` |
 | `SubscriptionLimitError` (extends `RealtimeError`) | `X_SUBSCRIPTION_LIMIT` | `src/errors.ts` |
-| `SyncUnconfiguredError` (extends `RealtimeError`) | `X_SYNC_UNCONFIGURED` | `src/page-errors.ts` |
 | `TopicForbiddenError` (extends `RealtimeError`) | `X_TOPIC_FORBIDDEN` | `src/errors.ts` |
-| `TransportProtocolError` (extends `RealtimeError`) | `X_TRANSPORT_PROTOCOL` | `src/errors.ts` |
 | `TransportUnavailableError` (extends `RealtimeError`) | `X_TRANSPORT_UNAVAILABLE` | `src/errors.ts` |
-| `WindowReadTimeoutError` (extends `RealtimeError`) | `X_TIMEOUT` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "30.9.0",
+  "version": "31.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "keywords": [
     "ultimate",
@@ -15,7 +15,8 @@
   "license": "MIT",
   "type": "module",
   "sideEffects": [
-    "./src/error-titles.ts"
+    "./src/error-titles.ts",
+    "./src/error-titles-server.ts"
   ],
   "repository": {
     "type": "git",
@@ -28,6 +29,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
     "./boot": "./src/boot.ts",
     "./page-runtime": "./src/page-runtime.ts",
     "./page-runtime-wait": "./src/page-runtime-wait.ts",
@@ -50,10 +52,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/entity": "30.9.0",
-    "@ultimat3/policy": "30.9.0",
-    "@ultimat3/query": "30.9.0",
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/entity": "31.0.0",
+    "@ultimat3/policy": "31.0.0",
+    "@ultimat3/query": "31.0.0",
     "nats": "2.29.3"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,14 @@
+// Single responsibility: the `@ultimat3/realtime/adapter` entry — what a bus driver implements and
+// throws, and the installer the boot (and `@ultimat3/testing`'s override seam) puts it in with. An
+// app never imports this: it hands its `Transport` to `apps/<app>/runtime.ts`'s `transport`.
+// Never re-exported from `.` or `./server` (`barrel-split.test.ts`).
+
+export { installChannelTransport } from './channel-publish';
+export { TransportProtocolError, TransportUnavailableError } from './errors';
+export type {
+  Transport,
+  TransportHandler,
+  TransportSet,
+  TransportSetEntry,
+  TransportSubscription,
+} from './fanout';

package/src/apply-patches.ts

@@ -5,7 +5,7 @@
 // Order and values are folded separately: a live window keeps its ORDER here and its VALUES in the
 // record store, so `applyPatches` is the array form of the same fold rather than a second one.
 
-import type { JsonObject, Row, RowPatch } from './json';
+import type { JsonObject, LiveRow, RowPatch } from './json';
 
 /**
  * Membership and order after a patch list, ids only. `index` places a row the set does not hold
@@ -36,13 +36,16 @@ export function orderAfterPatches(
 }
 
 /** Minimal in-place patch application: the shape a Solid store update maps onto directly. */
-export function applyPatches(rows: readonly Row[], patches: readonly RowPatch[]): readonly Row[] {
-  const values = new Map<string, Row>(rows.map((row) => [row.id, row]));
+export function applyPatches(
+  rows: readonly LiveRow[],
+  patches: readonly RowPatch[],
+): readonly LiveRow[] {
+  const values = new Map<string, LiveRow>(rows.map((row) => [row.id, row]));
   for (const patch of patches) {
     if (patch.op === 'delete' || patch.row === null) continue;
     values.set(patch.id, mergeRow(values.get(patch.id), patch.id, patch.row));
   }
-  const out: Row[] = [];
+  const out: LiveRow[] = [];
   for (const id of orderAfterPatches(
     rows.map((row) => row.id),
     patches,
@@ -54,7 +57,7 @@ export function applyPatches(rows: readonly Row[], patches: readonly RowPatch[])
 }
 
 /** The one merge rule: changed columns over the current value, and `id` is never overwritten. */
-function mergeRow(current: Row | undefined, id: string, columns: JsonObject): Row {
+function mergeRow(current: LiveRow | undefined, id: string, columns: JsonObject): LiveRow {
   const next: JsonObject = { ...(current ?? {}), ...columns };
   return { ...next, id };
 }

package/src/boot.ts

@@ -4,7 +4,7 @@
 // and opens the outbox, so a reload replays what the last load queued even if islands only read.
 
 import type { ClientScope } from '@ultimat3/core/page';
-import { pageClient } from '@ultimat3/core/page';
+import { CLIENT_OUTBOX_MAX_META, pageClient } from '@ultimat3/core/page';
 import { pageLocalStore, scopeKey } from './local-store-idb';
 import { pageOutbox } from './page-outbox';
 import { installPageRuntime } from './page-runtime';
@@ -18,6 +18,7 @@ import type { RecordStore } from './record-store';
  */
 async function restoreFromDisk(store: RecordStore, principal: () => Principal): Promise<void> {
   const types = persistedTypes();
+  const maxQueued = outboxCeiling();
   let persister: RecordPersister | undefined;
   try {
     // A sign-out by full navigation (a form post and a redirect) never calls `rescope()`, so the
@@ -45,7 +46,19 @@ async function restoreFromDisk(store: RecordStore, principal: () => Principal):
   // After the restore, so a replay settles overlays over the records it restored.
   // A queued write flushes the persisted rows first, so both are on disk before a reload can come.
   const kept = persister;
-  pageOutbox({ beforeEnqueue: kept === undefined ? undefined : () => kept.flush() });
+  pageOutbox({ beforeEnqueue: kept === undefined ? undefined : () => kept.flush(), maxQueued });
+}
+
+/**
+ * `realtime.maxQueued` as the server rendered it (`<meta name="ultimate-outbox-max">`), already
+ * screened by `defineConfig`; `localOutbox` screens it again where it builds, so a malformed meta
+ * is `X_INVARIANT`, never a ceiling no count reaches. Absent: no ceiling.
+ */
+function outboxCeiling(): number | undefined {
+  const doc: { querySelector?: (selector: string) => { content?: unknown } | null } | undefined =
+    Reflect.get(globalThis, 'document');
+  const content = doc?.querySelector?.(`meta[name="${CLIENT_OUTBOX_MAX_META}"]`)?.content;
+  return typeof content === 'string' ? Number(content) : undefined;
 }
 
 type Principal = ClientScope['principal'];