@ultimat3/realtime 24.0.0 → 25.1.0

package/README.md

@@ -61,8 +61,8 @@ half reaches the other; `barrel-split.test.ts` fails if one name is exported fro
 Migrating from 7.x: an import of a **server** name changes its specifier and nothing else.
 
 ```
-- import { ChannelHub, createSyncNode, LiveQueryRegistry } from '@ultimat3/realtime';
-+ import { ChannelHub, createSyncNode, LiveQueryRegistry } from '@ultimat3/realtime/server';
+- import { ChannelHub, syncNode, LiveQueryRegistry } from '@ultimat3/realtime';
++ import { ChannelHub, syncNode, LiveQueryRegistry } from '@ultimat3/realtime/server';
 ```
 
 Client names — the hooks, `RecordStore`, `OfflineQueue`, `encode`/`decode`, every `X_*` error
@@ -73,20 +73,22 @@ class — stay on `.`.
 | Concern | Entry | Export |
 |---|---|---|
 | tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
-| tier 2 | `./server` | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
-| replication | `./server` | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `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). Moved from `@ultimat3/testing`, which no longer re-exports it |
+| 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 |
 | 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 |
+| the outbox | `.` | `OfflineQueue`, `memoryQueueStore()` — 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` | `createSyncNode` / `listenSyncNode` (`sync` role) |
+| the node | `./server` | `syncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `useQuery`, `useRecord`, `useMutation`, `useMutationQueue`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useMutation`, `useMutationQueue`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| 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 |
-| offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `MemoryLocalStore` |
+| first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`: the boot's restore and the open outbox, capped (#506) |
+| offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `memoryLocalStore()` |
 | the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 
 ## `channelRef` — a channel an island can hold
@@ -119,13 +121,72 @@ is `X_CHANNEL_DECLARATION_INVALID` at declaration. `catchUp` is read on every ac
 whose name `registerQueries()` stamps at boot is picked up. The reference app's
 [`app/posts/channel-ref.ts`](../../examples/dummy/apps/web/app/posts/channel-ref.ts) is the idiom.
 
+### What `useChannel()` reports
+
+`useChannel(ref, params)()` is a `ChannelState`. Every channel that carries `records` or `events`
+leaves `joining` on the node's first answer; nothing waits for app traffic.
+
+| State | Entered when | Left when |
+|---|---|---|
+| `joining` | the subscribe is sent (on hold, and again on every reconnect) | the node's answer: a `records` channel's `replay-gap` (a fresh seat) or the `records` frame at a current cursor; an `events` channel's roster — sent on every seat, an empty one from a node with no presence (24.0.0) |
+| `catching-up` | a `replay-gap`, or a frame in a new epoch: the `catchUp` query is re-read, frames held behind it | the read lands → `live` (the held frames applied in order) |
+| `live` | as above | the socket drops → `offline`; a gap → `catching-up` |
+| `offline` | the page socket closed | it reopens → `joining` |
+| `failed` | the node refused the subscribe (`error()` is the coded refusal), or a catch-up read failed (retried on the client's curve, and on the next open) | a successful retry → `live` |
+
+A channel declared with **neither** `records` nor `events` carries nothing, so nothing answers its
+join and it reads `joining` for as long as it is held.
+
+## Channel records with no replicator
+
+A channel's `records` come off the change bus every sync node reads. The WAL replicator fills it
+— and needs a replication slot and the `REPLICATION` grant, cluster-wide on a shared Postgres.
+Without one, `recordPublisher` (`./server`) is how an app puts its own **committed** rows on that
+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 { 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[];
+
+// Once per process, at boot, naming every entity it will publish.
+const publisher = recordPublisher({ transport, entities: [runs] });
+
+// After the transaction commits.
+export async function settled(): Promise<void> {
+  await publisher.publish(runs, finished);
+  await publisher.publish(runs, finished, { op: 'delete' });
+}
+
+export const shutdown = (): void => publisher.close();
+```
+
+| Fact | Rule |
+|---|---|
+| one per process | one publisher is one `producer`; its `seq` counts from 1, one per row, in call order. A node reads a hole in it as a gap, and the members of every records topic re-run their catch-up read. A NEW publisher is not a gap — publishers run side by side, one per process |
+| committed rows only | call it after COMMIT. A row published from inside a transaction is on every page before a rollback; nothing here can see the transaction |
+| what rides | the entity's record properties and nothing else: a sealed column and a property the entity does not declare are dropped. A row without its key is `X_RECORD_KEY_MISSING`, before any row of the call is sent |
+| `op` | `upsert` (default) adopts the rows; `delete` removes them by key. A row whose channel params changed: publish its old image as a `delete`, then the new one |
+| `write` | the keyed request the call runs inside (`writeDigest` of its idempotency key), so the writing page settles its own echo; or the digest you pass; or `null` |
+| a send the bus refused | the call rejects (`X_TRANSPORT_UNAVAILABLE` from NATS); that row's seq stays spent, so the nodes see the hole and repair it |
+| channels, never live queries | a publisher has no commit position, and a live window refuses a change below its own lsn as stale. Its changes reach the declared channels only; a live query needs the replicator |
+| under `x dev` | an entity a publisher claims is no longer carried to channels by the in-process bridge — the app's publish is its one delivery, as in production. Live queries still hear the bridge |
+| one producer kind per table | a sync node keeps the producer KIND (replicator or publisher) that first carried a table and drops the other's changes for it, logged once per table as `X_REALTIME_PRODUCER_CONFLICT` — a replicator and a publisher on one table was every row twice on every channel. The replicator carries every entity table, so the fix is always to stop publishing that one; the node decides again on restart |
+| refusals | `X_INVARIANT`: an entity the publisher did not claim, a `write` that is not a digest, a closed publisher |
+
 ## The hooks
 
 One record store and one socket per **page**, on `globalThis`: every island is its own bundle, so a
-module-level singleton would be one per island. The island bootstrap `x build` prepends installs
-realtime for its bundle — `installRealtime({ signal: createSignal, sync: { url, buildId } })` — and
-an island never constructs a client or a socket. The socket opens on the first live hook; an island
-that only reads records or writes ships none of it.
+module-level singleton would be one per island. Both belong to the **page runtime** — the store,
+the socket stack, the query client and core's transport — installed ONCE per page and never inside
+an island: the page boot carries it, and where no boot is rendered the island loads
+`/islands/page-runtime.<id>.js`, the one chunk `x build` builds from `@ultimat3/realtime/page-runtime`.
+The island bootstrap `x build` prepends awaits that runtime, then installs realtime for its bundle —
+`installRealtime({ signal: createSignal })` — so a hook is a thin reader and an island never
+constructs a client or a socket. The socket opens on the first live hook.
 
 ```ts
 import {
@@ -138,6 +199,7 @@ import {
   usePresence,
   useQuery,
   useRecord,
+  useRecords,
 } from '@ultimat3/realtime';
 
 declare const orgId: string;
@@ -145,10 +207,16 @@ declare const postId: string;
 declare const LIKE_POST: MutatorLike; // name + local twin + conflict — never the mutator VALUE
 declare const orgFeed: ChannelRef<'orgId'>; // a `channel('org-feed', { params: ['orgId'], … })`
 declare function onEvent(event: Readonly<Record<string, unknown>>): void;
+type Run = { readonly id: string; readonly state: string; readonly startedAt: string };
 
 const feed = useQuery({ name: 'liveFeed', live: true }, { orgId }); // AsyncState<readonly Row[]>
 const posts = useQuery({ name: 'listPosts', entity: 'posts' }, {}); // one HTTP read, rows as records
 const post = useRecord('posts', postId);                            // AsyncState<Row | undefined>
+const pair = useRecords('posts', [postId]);                         // those keys, in key order
+const runs = useRecords<Run>('runs', {                              // EVERY `runs` record on the page
+  where: (run) => run.state !== 'done',
+  order: (a, b) => (a.startedAt < b.startedAt ? 1 : -1),
+});
 const like = useMutation(LIKE_POST);                                // await like(input); like.pending
 const connection = useConnection();                                 // .offline .online .reconnectAt .updateAvailable
 const writes = useMutationQueue();                                  // .pending .failed
@@ -161,8 +229,9 @@ const room = usePresence(orgFeed, { orgId });                      // the channe
 same engine runs in-page. Writes that find no network go to the page's outbox — overlay kept — and
 replay over HTTP, under their original idempotency keys, when the socket comes back. The outbox is
 the page boot's (`@ultimat3/realtime/boot`): an island only reads it off the page. On a page the
-CLI renders no boot for (no scope tag, so nothing on it persists) such a write is refused like any
-other — rejected, overlay taken back — never held in memory a reload would silently lose.
+CLI renders no boot for (no scope tag, so nothing on it persists) the island's runtime chunk opens
+no outbox, and such a write is refused like any other — rejected, overlay taken back — never held
+in memory a reload would silently lose.
 
 `<AsyncRegion state={feed()} …/>` takes the answer as-is: `AsyncState` is `@ultimat3/core`'s, the
 same type `@ultimat3/ui` renders.
@@ -171,6 +240,7 @@ same type `@ultimat3/ui` renders.
 |---|---|
 | A query ref is `{ name, live?, entity? }`, never the query VALUE | importing a `query()` drags its read path into the island (698,801 B measured) |
 | Lists hold keys; rows are the store's | a record updated by any answer or frame re-renders every list showing it, with no refetch |
+| A list that must GROW with the store is `useRecords(type, { where?, order? })` | a `useQuery` list holds its own answer's keys and `useRecords(type, keys)` the keys it was given, so a record a channel's `records` frame adopts reaches neither. The whole-type form is the channel-records counterpart of a live window: `ready` from its first read, every record of the type the store holds (optimistic ones included), default order by key, and none evicted while it is held — a row it alone kept goes when the last reader of the type lets go (#680) |
 | Every write is HTTP through core's `clientTransport` | one write path: the action's authz, idempotency and contract; the socket carries none |
 | The answer's records are adopted before the overlay goes | a convergent twin never flickers back to the pre-write value |
 | **No `solid-js` import.** Each bundle installs its own `SignalFactory` | every island carries its own solid-js; a signal from another bundle is invisible to its effects |
@@ -185,7 +255,7 @@ asks.
 
 ## Who a socket is
 
-`createSyncNode({ authenticate })` is the one place a websocket gets an identity. It runs on the
+`syncNode({ authenticate })` is the one place a websocket gets an identity. It runs on the
 upgrade **before** `server.upgrade`, so a refused credential never costs a socket, and the actor it
 resolves is what every policy downstream decides against — the topic guard, `authorize`, `visible`,
 the per-tenant subscription cap.
@@ -199,7 +269,7 @@ declare function sessionFrom(
 ): Promise<{ actor: Actor; expiresAt: number; token: string } | null>;
 declare function renew(token: string): Promise<SyncGrant | null>;
 
-// The one option this section is about; `createSyncNode({ …, authenticate })` takes it.
+// The one option this section is about; `syncNode({ …, authenticate })` takes it.
 const options: Pick<SyncNodeOptions, 'authenticate'> = {
   // From @ultimat3/auth, or anywhere else: `sync` imports no authenticator, exactly as it owns no
   // business logic. `refresh` is yours too, so the framework retains no credential of its own.
@@ -230,7 +300,7 @@ the socket and retries next pass — a token service timing out is not a revocat
 `hub.guard('org.*.feed', ({ actor }) => actor?.orgId === …)` denies everyone and the only guard that
 lets anything through is one that reads no actor at all.
 
-Authz goes through `@ultimat3/query`'s `guard`, which is the only contact with `@ultimat3/policy`.
+Authz goes through `@ultimat3/query`'s `guardQuery`, which is the only contact with `@ultimat3/policy`.
 One authz system, never two: `policy` is evaluated **once per subscriber**, never once per query.
 Two actors on one live query get two different result sets, and a row that leaves an actor's policy
 is delivered to them as a `delete` — never as silence.
@@ -269,19 +339,21 @@ wire.
 
 | Ceiling | Default | Option | Refused with |
 |---|---|---|---|
-| concurrent sockets on this node | 250,000 | `createSyncNode({ maxConnections })` | `503` + `retry-after-ms`, the same shed as the accept budget |
-| inbound bytes per frame | 256 KiB | `createSyncNode({ maxFrameBytes })` | the socket, by `Bun.serve`'s `maxPayloadLength` |
-| inbound frames per socket | 64/s, burst 256 | `createSyncNode({ maxFramesPerSecond, frameBurst })` | `X_FRAME_RATE_LIMIT` |
+| concurrent sockets on this node | 250,000 | `syncNode({ maxConnections })` | `503` + `retry-after-ms`, the same shed as the accept budget |
+| inbound bytes per frame | 256 KiB | `syncNode({ maxFrameBytes })` | the socket, by `Bun.serve`'s `maxPayloadLength` |
+| inbound frames per socket | 64/s, burst 256 | `syncNode({ maxFramesPerSecond, frameBurst })` | `X_FRAME_RATE_LIMIT` |
 | live subscriptions per socket | 128 | `new LiveQueryRegistry({ maxPerSocket })` | `X_SUBSCRIPTION_LIMIT` |
+| live subscriptions per actor (anonymous: per resolved client address), across its sockets | 1,000 (`DEFAULT_MAX_PER_ACTOR`) | `new LiveQueryRegistry({ maxPerActor })`; the boot passes `realtime.maxSubscriptionsPerActor` | `X_SUBSCRIPTION_LIMIT` |
+| 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` |
 | 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` |
-| outbound bytes buffered on one socket | 1 MiB | `createSyncNode({ maxBufferedBytes })` | the frame is dropped and `send` answers `false` |
-| dropped frames before that socket is closed | 32 | `createSyncNode({ maxDroppedFrames })` | close `1013` (`overloaded`), reason `backpressure` |
-| time one socket may route no frame | 120s | `createSyncNode({ idleTimeoutMs })` | close `4001` (`idle`), reason `idle timeout` |
-| time one grant's `refresh()` may hold the re-auth pass | 10s (10 000 ms) | `createSyncNode({ grantRefreshDeadlineMs })` | reported and skipped: the grant stays expired and is asked again next pass |
+| outbound bytes buffered on one socket | 1 MiB | `syncNode({ maxBufferedBytes })` | the frame is dropped and `send` answers `false` |
+| dropped frames before that socket is closed | 32 | `syncNode({ maxDroppedFrames })` | close `1013` (`overloaded`), reason `backpressure` |
+| time one socket may route no frame | 120s | `syncNode({ idleTimeoutMs })` | close `4001` (`idle`), reason `idle timeout` |
+| time one grant's `refresh()` may hold the re-auth pass | 10s (10 000 ms) | `syncNode({ grantRefreshDeadlineMs })` | reported and skipped: the grant stays expired and is asked again next pass |
 | retained patch bytes per node | 64 MiB | `new RingChangeBuffer({ maxBytes, maxBytesPerQuery })` | eviction, then a re-snapshot on resume |
 | array lengths and `input` nesting in a frame | `FRAME_LIMITS` | none — a hard ceiling | `X_PROTOCOL_VERSION` |
 
@@ -318,6 +390,7 @@ over it, and an HTTP answer's records, a socket patch and an optimistic write al
 | The live path names the type server-side (`recordTypeForTable`) | a changefeed speaks tables; the store speaks entities |
 | Two layers: synced truth and the optimistic overlay | a refused write drops its overlay and shows exactly what the server said — never a stale before-image |
 | The overlay is REPLAYED over every server update | two pending writes on one row land in order on top of someone else's change |
+| A server frame that echoes this page's write names it — `records.write`, `patch.writes` (a delta resume names each it replays), `writeDigest(idempotencyKey)` — and settles it in the frame's own batch | merged under its still-pending twin, the echo painted the write twice (truth plus overlay) until the HTTP answer landed. `ChangeEvent.write` is `string \| null`, required, so a producer cannot forget it |
 | A value is **replaced, never mutated**; a write **merges** columns | a mutated row is a render that never happens; a narrower projection must not blank a wider one |
 | A structurally bad row is `X_RECORD_REJECTED`, dropped and reported | never partially merged — a keyless row would overwrite another record |
 | The last holder leaving evicts the record | an infinite scroll must not retain every row it ever saw |
@@ -363,7 +436,7 @@ is admitted is decided in `sync-origin.ts`:
 | Admitted | When |
 |---|---|
 | no `Origin` header | always — RFC 6455 has every browser send one, so its absence is not a browser |
-| `createSyncNode({ allowedOrigins })`, compared exactly (scheme, host, port) | when any is declared. The declaration is the WHOLE list (24.0.0): the origin the node was reached on is no longer admitted beside it, because that origin is read off the `Host` header and a sibling subdomain pointed at the node would be "its own" |
+| `syncNode({ allowedOrigins })`, compared exactly (scheme, host, port) | when any is declared. The declaration is the WHOLE list (24.0.0): the origin the node was reached on is no longer admitted beside it, because that origin is read off the `Host` header and a sibling subdomain pointed at the node would be "its own" |
 | the origin the node was reached on | only when nothing is declared. A node reached over plain `http` also admits the `https` spelling of that host and port: TLS ended at a proxy, the scheme is not knowable there, and a browser sends no `sec-fetch-site` on a websocket handshake |
 
 The CLI passes `APP_URL`'s origin, which the Compose rung (`:3000` / `:3001`) requires on `sync`
@@ -376,7 +449,7 @@ there refuses. The refusal's cause names the origin that asked and every origin
 its fix is the `export APP_URL=…` that admits the asker.
 
 **The node's `/healthz` and `/readyz` tell the detail to a listed peer only**
-(`createSyncNode({ healthDetailPeers })`, default the box itself). A request carrying `Forwarded`,
+(`syncNode({ healthDetailPeers })`, default the box itself). A request carrying `Forwarded`,
 `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Real-IP` or `Via` is told the
 verdict only. A proxy that adds none of them is indistinguishable from a direct peer: a
 header-less proxy must not route the health paths.
@@ -434,7 +507,7 @@ wire twice by a reconnect that raced an ack.
 | The store is handed **snapshots, by key**, never the live entries or the whole queue | `QueueStore.write` is a durable write and may await before it reads; given an entry itself it persists a status that was never true when it was called. By key, because two tabs of one user share the store and a whole-queue save let the last tab erase the other's write |
 | One tab drains at a time, and drains what every tab queued | the outbox's replay runs under the Web Lock `ultimate-outbox:<principal>` and re-reads the queue first, so a write another tab queued is sent, in order, and a stored `inflight` from a closed page goes back to `pending` |
 
-`createOutbox({ warn })` — where a disk that refused the queue is said
+`localOutbox({ warn })` — where a disk that refused the queue is said
 (`X_LOCAL_STORE_UNAVAILABLE`, default `console.warn`); the outbox then queues in memory for that
 principal.
 
@@ -456,13 +529,19 @@ principal.
   or, since 24.0.0, a new `producer` after one it already read: the run before it died, and the
   tail of a dead stream has no later sequence to be missed against —
   invalidates every window it holds and desyncs every subscriber, so the next change to each query
-  re-reads and re-snapshots. Both fields are optional on the bus, so a publisher that does not
-  sequence simply detects nothing. Durable replay (JetStream) is a separate decision — retention,
+  re-reads and re-snapshots — and tells every member of every open topic that carries records
+  `replay-gap` at a new epoch, so each re-runs its channel's catch-up read (`ChannelHub.invalidate`,
+  24.0.0, #681). A bus that reconnected is the same repair, with no later message needed. Both
+  fields are optional on the bus, so a publisher that does not sequence simply detects nothing.
+  A `recordPublisher`'s changes are sequenced too (`source: 'publisher'`): a hole in one is a
+  gap; a new publisher is not, because publishers run side by side. Durable replay (JetStream) is a separate decision — retention,
   storage and replay window — and is deliberately not this mechanism.
 - **A bulk write re-reads only the windows over its entity.** `updateWhere`/`deleteWhere` name a
   filter, not rows, so the in-process replicator calls `registry.invalidate(entity)`: windows whose
   shape reads that entity go stale and their subscribers desynced. The next change re-reads the
-  window and re-snapshots every subscriber, whether or not that change matches the query.
+  window and re-snapshots every subscriber, whether or not that change matches the query. The
+  channels are told too — `ChannelHub.invalidate(entity)` — so every topic carrying that table
+  sends its members `replay-gap` and they re-run the channel's catch-up read.
 - **`desynced` has a reader.** A subscriber recorded as diverged — a dropped patch, a gate that
   failed, a window that lost its tail — is served a fresh snapshot out of the shared window on the
   next delivery, and only then is the mark cleared. A snapshot the socket refuses leaves it
@@ -481,17 +560,17 @@ principal.
   readers that throw on an absent field, unlike the `list()` that made `hello.resume`'s removal free.
 - **Backpressure drops patch frames.** That is safe *only* because a re-snapshot is cheap: the drop
   is recorded on the socket (`desynced`) and the next delivery re-snapshots rather than diverging.
-- **A dropped CHANNEL frame is not safe, and is not repaired.** A topic has no cursor, no mark and
-  no re-snapshot, so tier 1 is **at most once**. Every refusal is counted — the series
+- **A dropped `events` frame is not repaired** (a dropped `records` frame is: `replay-gap` once the
+  socket drains). An event has no cursor, no mark and no re-snapshot, so tier 1's `events` are
+  **at most once**. Every refusal is counted — the series
   `channel_frames_dropped_total` (no labels: a topic is client-chosen, so a per-topic label is
   unbounded series one socket can mint), the log line `channel.frames_dropped` at `warn` carrying
   `{ topic, dropped, total }`, and `node.sockets.droppedChannelFrames` for a test or a benchmark
   that cannot scrape. Node-wide and cumulative, because a socket past `maxDroppedFrames` is closed
   and removed — a per-socket count leaves exactly when loss is worst. Distinct from
   `SyncSocket.droppedFrames`, which counts every kind of frame one connection lost and dies with it.
-  Repair would need a per-topic sequence on the wire: a channel's `lsn` is the publishing hub's own
-  per-node counter, so a client cannot tell a gap from a message that arrived via another node.
-  **Anything that must arrive belongs on a live query.**
+  `records` frames carry a per-node `seq`/`epoch`, which is what lets them be repaired; `events`
+  carry none. **Anything that must arrive belongs on a live query or a `records` channel.**
 - **Bun's native WS pub/sub is not used.** `subscribeTopic` does not call `ws.subscribe` and the
   websocket config declares no `publishToSelf`; every channel message is one filtered `send` per
   socket through `SocketRegistry.deliver`, reading a per-topic index rather than walking the socket
@@ -583,7 +662,7 @@ principal.
   every subscriber learned the id and the instant of every *other* tenant's row as it was deleted,
   on a query whose `visible` rule had never let them see one. A subscriber that holds the row is
   told it is gone; one that does not gets nothing, counted as `rowsDenied`.
-- **`PgLogicalReplicationFeed` decodes `pgoutput` off a real slot** — its own Postgres v3 client
+- **`postgresChangeFeed()` decodes `pgoutput` off a real slot** — its own Postgres v3 client
   (SCRAM-SHA-256, in-band TLS, CopyBoth), no driver dependency. It preflights `wal_level`, the
   publication, every entity's replica identity and the slot — in that order, because the identity
   check is worthless once the slot exists — creates the slot when there is none, and confirms the
@@ -591,12 +670,12 @@ principal.
   checked** (`pg-publication.ts`): missing, it is created `FOR TABLE` every entity table; present,
   it gains the entity tables it lacks (`ALTER PUBLICATION … ADD TABLE`) and loses none. `FOR TABLE`
   because a table's owner may publish it without a superuser; a role that may not is refused with
-  `X_REPLICATION_FAILED` and the statement to run as one that may. `InMemoryChangeFeed` + `InProcessTransport` remain the
+  `X_REPLICATION_FAILED` and the statement to run as one that may. `memoryChangeFeed()` + `InProcessTransport` remain the
   defaults for `x dev` and every test. `START_REPLICATION` asks `messages 'true'`, which needs
   **Postgres ≥ 14**.
 - **A replication stream that ends is restarted** (24.0.0). `ChangeFeed.start` takes
   `onEnd(reason)`, called when the pump dies on its own — the walsender ended the copy, a decode
-  failed, the handler rejected — and never for a `stop()`. `createReplicator` answers it: `running`
+  failed, the handler rejected — and never for a `stop()`. `changeFeedReplicator` answers it: `running`
   goes `false`, the feed is stopped, the advisory lock is released so a standby may take the slot,
   and the same process redials on `retryDelayMs(attempt)` (through `ReplicatorOptions.schedule`)
   until it holds the stream again or `stop()` is called. The restart resumes from the last lsn this
@@ -620,7 +699,7 @@ principal.
   mode, detail, slot, lock }`: `mode` is `'embedded' | 'external'`, `detail` is the env key that
   selected it and never a credential, and `lock` is the `AdvisoryLock` for that feed — built here
   rather than by the caller, because constructing one needs the URL and the URL carries a password.
-  Neither `DATABASE_URL` nor `REPLICATION_URL` set → `InMemoryChangeFeed`,
+  Neither `DATABASE_URL` nor `REPLICATION_URL` set → `memoryChangeFeed()`,
   `mode: 'embedded'`. `REPLICATION_URL` wins when both are set, but naming a different host, port or
   database than `DATABASE_URL` is refused at boot with `X_CONFIG_INVALID` — a feed streaming the
   wrong database's WAL would be silently wrong forever. `REPLICATION_SLOT` (default `x_replicator`)
@@ -656,9 +735,9 @@ principal.
 - **A lock that is lost ends the stream** (24.0.0). The lock is a session, and a session can die
   while the replication stream stays up — Postgres then grants the lock to the next process that
   asks, and a holder that kept streaming would be one of two replicators. `AdvisoryLock.onLost(
-  listener)` (required) reports it: `PgAdvisoryLock` watches its idle session through
+  listener)` (required) reports it: `postgresAdvisoryLock()` watches its idle session through
   `PgConnection.watchIdle` (EOF, a read error or a server `FATAL`; no polling), and
-  `createReplicator` answers exactly as it does a dead stream — `running` false, feed stopped,
+  `changeFeedReplicator` answers exactly as it does a dead stream — `running` false, feed stopped,
   back into the takeover loop to compete for the lock again.
 - **A recovery asks nothing, and a stop waits a bounded time** (24.0.0). A dead stream or a lost
   lock calls `ChangeFeed.abandon()` and then `AdvisoryLock.abandon()` (both required, both
@@ -668,10 +747,10 @@ principal.
   been published, so a change the bus refuses every time backs off to `maxMs` instead of
   redialling at the base; `stats().failure` names its entity and lsn, and `running` stays `false`
   until it goes out.
-- **`PgAdvisoryLock` is the production `AdvisoryLock`** — `SELECT
+- **`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.
-  `InMemoryAdvisoryLock` remains the single-process default for `x dev` and tests.
+  `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 }`:
@@ -694,7 +773,13 @@ principal.
   the library's own KV abstraction expresses neither a per-message TTL nor a batch direct get.
   Reconnect and re-subscription are the library's: a lost connection is re-established underneath
   the caller, which is what makes `sync` stateless, and the jitter that spreads a restart herd is
-  handed to it as its reconnect delay rather than re-implemented above it.
+  handed to it as its reconnect delay rather than re-implemented above it. The one loss the
+  library does not recover is its own end: once its reconnect budget is spent it closes the
+  client for good and says so through the port's `onClosed`. `NatsTransport` then re-dials in the
+  background on the same backoff, one attempt at a time, until a client is up or `close()` runs;
+  callers meanwhile get `X_TRANSPORT_UNAVAILABLE` at once. Every live subscription is bound again
+  on the new client and the recovery is announced through `onReconnect`. Before 2026-10 the dead
+  client was handed out until the process was restarted.
   `transport.onReconnect(listener)` — a required member of `Transport` since 24.0.0 — announces
   each recovery and returns the unsubscribe: fanout is at-most-once, so whatever was published
   during the drop never arrived. `InProcessTransport` has no connection to lose and never calls it. The bucket needs
@@ -709,7 +794,7 @@ principal.
   holds no window: a DELETE is routed to the topic the OLD row's params name, and under the default
   identity that image is the key alone — no topic, no `remove`, and members keep the deleted
   record. Preflight asks the catalog about exactly those tables (`paramsChannelTables()`, or
-  `PgLogicalReplicationOptions.fullIdentityTables`) and logs `replication.channel_identity_partial`
+  `PostgresChangeFeedOptions.fullIdentityTables`) and logs `replication.channel_identity_partial`
   with the fix `x db gen "replica identity full"`: `x db gen` grants FULL to those tables beside
   the live queries' `subscribes:` ones, so an app that declares a params channel owes one migration.
 - **For a live query, a keyed table does not need `REPLICA IDENTITY FULL`; a table with NO identity is warned**

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
-    "./src/errors.ts"
+    "./src/error-titles.ts"
   ],
   "repository": {
     "type": "git",
@@ -19,6 +19,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./boot": "./src/boot.ts",
+    "./page-runtime": "./src/page-runtime.ts",
+    "./page-runtime-wait": "./src/page-runtime-wait.ts",
     "./server": "./src/server.ts",
     "./sync-worker": "./src/sync-worker.ts"
   },
@@ -31,16 +33,17 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/entity": "24.0.0",
-    "@ultimat3/query": "24.0.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/entity": "25.1.0",
+    "@ultimat3/policy": "25.1.0",
+    "@ultimat3/query": "25.1.0",
     "nats": "2.29.3"
   }
 }

package/src/advisory-lock.ts

@@ -22,7 +22,7 @@ export interface AdvisoryLock {
 }
 
 /** Single-process default: correct for `x dev` and tests, useless across containers (by design). */
-export class InMemoryAdvisoryLock implements AdvisoryLock {
+export class MemoryAdvisoryLock implements AdvisoryLock {
   static readonly #held = new Set<string>();
   readonly key: string;
   #mine = false;
@@ -32,21 +32,21 @@ export class InMemoryAdvisoryLock implements AdvisoryLock {
   }
 
   async tryAcquire(): Promise<boolean> {
-    if (InMemoryAdvisoryLock.#held.has(this.key)) return false;
-    InMemoryAdvisoryLock.#held.add(this.key);
+    if (MemoryAdvisoryLock.#held.has(this.key)) return false;
+    MemoryAdvisoryLock.#held.add(this.key);
     this.#mine = true;
     return true;
   }
 
   async release(): Promise<void> {
     if (!this.#mine) return;
-    InMemoryAdvisoryLock.#held.delete(this.key);
+    MemoryAdvisoryLock.#held.delete(this.key);
     this.#mine = false;
   }
 
   abandon(): void {
     if (!this.#mine) return;
-    InMemoryAdvisoryLock.#held.delete(this.key);
+    MemoryAdvisoryLock.#held.delete(this.key);
     this.#mine = false;
   }
 
@@ -55,3 +55,8 @@ export class InMemoryAdvisoryLock implements AdvisoryLock {
     return () => undefined;
   }
 }
+
+/** The one way to build the in-process lock — the twin of `postgresAdvisoryLock()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function memoryAdvisoryLock(key: string): MemoryAdvisoryLock {
+  return new MemoryAdvisoryLock(key);
+}

package/src/boot.ts

@@ -1,13 +1,14 @@
-// `@ultimat3/realtime/boot` — the page's boot, ONE classic script per document (plan 101), built
-// and served by the CLI the way the sync worker is. It restores the principal's persisted records
-// and opens the outbox, so a reload replays what the previous load queued even on a page whose
-// islands only read. Here and not in `page-store.ts`, so no island bundle carries it.
+// `@ultimat3/realtime/boot` — the page's boot, ONE classic script per document (plan 101), served
+// by the CLI like the sync worker. It installs the page runtime (store, socket, host, channel book;
+// islands await and read it, never carry it — #505), restores the principal's persisted records
+// 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 { pageLocalStore, scopeKey } from './local-store-idb';
 import { pageOutbox } from './page-outbox';
-import { BOOT_KEY, BOOT_RELEASE_KEY, type BootHost, pageRealtime } from './page-store';
+import { installPageRuntime } from './page-runtime';
+import { BOOT_KEY, BOOT_RELEASE_KEY, type BootHost } from './page-store';
 import { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
 import type { RecordStore } from './record-store';
 
@@ -50,9 +51,12 @@ async function restoreFromDisk(store: RecordStore, principal: () => Principal):
 type Principal = ClientScope['principal'];
 
 /**
- * Once per page, whoever calls first; the promise is what `pageRealtime().booted` answers. The
- * scope is the page's own — a parameter only so a test can boot an unscoped page (an OBJECT, so an
- * explicit `undefined` principal is not mistaken for "use the default").
+ * Once per page, whoever calls first; the promise is what `pageRealtime().booted` answers — the
+ * one moment an island may treat the page's records as restored (#506 holds first paint on it).
+ * The runtime is installed synchronously, before the first await, so an island waiting on this
+ * script (`awaitPageRuntime`) is released by the script's `load` with the store already there.
+ * The scope is the page's own — a parameter only so a test can boot an unscoped page (an OBJECT,
+ * so an explicit `undefined` principal is not mistaken for "use the default").
  */
 export function bootPage(scope?: { readonly principal: Principal }): Promise<void> {
   const host = globalThis as BootHost;
@@ -61,10 +65,11 @@ export function bootPage(scope?: { readonly principal: Principal }): Promise<voi
   // Already booting — unless what sits there is an island's placeholder, which this boot claims.
   if (started !== undefined && waiting === undefined) return started;
   Reflect.deleteProperty(host, BOOT_RELEASE_KEY);
+  const page = installPageRuntime();
   // Asked each time, never captured: the page's principal is whatever `rescope()` last said.
   const principal = (): Principal =>
     scope === undefined ? pageClient().scope.principal : scope.principal;
-  const booted = restoreFromDisk(pageRealtime().store, principal);
+  const booted = restoreFromDisk(page.store, principal);
   if (started !== undefined && waiting !== undefined) {
     void booted.then(waiting);
     return started;

package/src/changefeed-env.ts

@@ -1,15 +1,15 @@
 // Single responsibility: environment → change feed. The one place that decides which `ChangeFeed`
 // a boot installs, so `x dev`, a replicator container and any custom host resolve it identically.
-// `PgLogicalReplicationFeed` is useless until something constructs it from a connection string;
+// `PostgresChangeFeed` is useless until something constructs it from a connection string;
 // this is that something, keyed on env rather than a config field so one image deploys everywhere.
 
 import type { Clock } from '@ultimat3/core';
 import { ConfigInvalidError } from '@ultimat3/core';
 import type { AdvisoryLock } from './advisory-lock';
-import { InMemoryAdvisoryLock } from './advisory-lock';
+import { memoryAdvisoryLock } from './advisory-lock';
 import type { ChangeFeed } from './changefeed';
-import { InMemoryChangeFeed, PgLogicalReplicationFeed } from './changefeed';
-import { PgAdvisoryLock } from './pg-advisory-lock';
+import { memoryChangeFeed, postgresChangeFeed } from './changefeed';
+import { postgresAdvisoryLock } from './pg-advisory-lock';
 import type { PgTarget } from './pg-socket';
 import { parsePgUrl } from './pg-socket';
 import type { PgStream } from './pg-wire';
@@ -105,12 +105,12 @@ export function selectChangeFeed(
 
   if (url === undefined) {
     return {
-      feed: new InMemoryChangeFeed(options.retain === undefined ? {} : { retain: options.retain }),
+      feed: memoryChangeFeed(options.retain === undefined ? {} : { retain: options.retain }),
       mode: 'embedded',
       detail: 'in-process change feed — set DATABASE_URL to decode a real WAL',
       slot: null,
       // Single-process mutual exclusion, which is all one process needs and all it can enforce.
-      lock: new InMemoryAdvisoryLock(replicatorLockKey(DEFAULT_REPLICATION_SLOT)),
+      lock: memoryAdvisoryLock(replicatorLockKey(DEFAULT_REPLICATION_SLOT)),
     };
   }
 
@@ -122,7 +122,7 @@ export function selectChangeFeed(
   return {
     // Slot and publication are validated inside the feed, against the same identifier rule the
     // replication command needs — a second copy of that regex here is a second thing to keep true.
-    feed: new PgLogicalReplicationFeed({
+    feed: postgresChangeFeed({
       url,
       slot,
       publication: nonEmpty(env['REPLICATION_PUBLICATION']) ?? DEFAULT_REPLICATION_PUBLICATION,
@@ -136,7 +136,7 @@ export function selectChangeFeed(
     slot,
     // Taken on the same database the feed reads, so the lock and the slot cannot end up in
     // different places — which is the only way "exactly one replicator" could quietly become two.
-    lock: new PgAdvisoryLock({
+    lock: postgresAdvisoryLock({
       url,
       key: replicatorLockKey(slot),
       stream: options.stream,