@ultimat3/realtime 23.0.0 → 25.0.0

package/README.md

@@ -25,6 +25,9 @@ export const liveFeed = query({
 
 // mutator (action + optimistic local twin)
 export const likePost = mutator({
+  // REQUIRED (`X_MUTATOR_NOT_IDEMPOTENT`): a replay under the same Idempotency-Key answers the
+  // first result instead of running `server` again.
+  idempotent: true,
   // Convergent, not incremental: `local` replays on every server update, so applying it N times has to
   // equal applying it once — `likedByMe` is what makes the second application a no-op.
   local(tx, { postId }) {
@@ -58,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
@@ -70,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
@@ -116,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 {
@@ -135,6 +199,7 @@ import {
   usePresence,
   useQuery,
   useRecord,
+  useRecords,
 } from '@ultimat3/realtime';
 
 declare const orgId: string;
@@ -142,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
@@ -158,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.
@@ -168,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 |
@@ -182,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.
@@ -196,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.
@@ -227,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.
@@ -266,18 +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` |
+| 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` |
 
@@ -314,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 |
@@ -350,15 +427,32 @@ credential drained the bucket and every signed-in reconnect behind it was shed.
 behind an ingress every dial has the ingress's address, and a forwarded header is the caller's own
 claim.
 
-**A socket from a foreign page is refused** — `403 X_SOCKET_ORIGIN_REFUSED`, before `authenticate`
+**A socket from another origin is refused** — `403 X_SOCKET_ORIGIN_REFUSED`, before `authenticate`
 and before the budget. A websocket carries the session cookie and no CORS applies to it, so a page on
 a sibling host (same-site, which `SameSite=Lax` does not stop) could open one as its visitor. The
-rule is `@ultimat3/core`'s `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks, with two
-admissions of the node's own (`sync-origin.ts`): no `Origin` header (RFC 6455 has every browser send
-one, so its absence is not a browser), and the node's own host name at any port or scheme (cookies
-are not port-isolated, and the Compose rung serves the page on `:3000` and the node on `:3001`). A
-page on another host is admitted by `createSyncNode({ allowedOrigins })` — the CLI passes
-`APP_URL`'s origin.
+rule is `@ultimat3/core`'s `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks, and what
+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 |
+| `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`
+and the Helm chart sets from `ingress.host`. Under `x dev` it also adds the web role's own origin
+and its `localhost`, `127.0.0.1` and `[::1]` spellings to a declared list, so `x dev --port 4000`
+beside an `.env` naming `:3000` still connects, and passes `admitReachedOrigin: true`, which keeps
+the origin the node was reached on beside the list (a Codespace, a tunnel: `x dev` binds loopback,
+so a `Host` reaches it only through a forward its own user set up); a container adds nothing, and a wrong `APP_URL`
+there refuses. The refusal's cause names the origin that asked and every origin the node admits;
+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**
+(`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.
 
 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
@@ -384,7 +478,7 @@ below (`heartbeatMs` on the internal `LiveClient`; `0` disables the pass).
 
 | Property | Behaviour |
 |---|---|
-| Default | `DEFAULT_HEARTBEAT_MS`, 15s. The client's own number and the only one: `realtime.heartbeatMs` in `app.config.ts` was deleted 2026-08-19 because nothing read it |
+| Default | `DEFAULT_HEARTBEAT_MS`, 10s — a third of the default presence ttl, until the node names its own on its `hello` reply (`hello.heartbeatMs` = `min(ttl / 3, idle / 4)`, floored at 1 s): the client follows that for the life of the socket, and the SharedWorker engine reaps a tab on the longer of the two. The client's own number: `realtime.heartbeatMs` in `app.config.ts` was deleted 2026-08-19 because nothing read it |
 | One beat | a `hello` — which carries no cursors at all; `HelloFrame` has no resume list, so a beat and an opening frame are byte-identical — plus one subscribe frame per topic held |
 | Why the topics | on the node, repeating the subscribe frame **is** the presence heartbeat; presence has no frame of its own in either direction |
 | Not a deploy check | `update-available` answers a skew between the build the client claims — the `hello`'s `buildId`, or `?build=` on the dial; every hello is read and the latest one is the record — and the node's own. A client says the same build on every beat and the node's never moves while the socket is open, so every `hello` on one socket answers the same forever. A client hears about a deploy on the socket it opens against the **new** node |
@@ -413,6 +507,10 @@ 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` |
 
+`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.
+
 ### Limits, stated plainly
 
 - **The change window is per node, and a `qid` window can only be.** A client that reconnects to a
@@ -421,16 +519,29 @@ wire twice by a reconnect that raced an ack.
   matcher and no window, so it cannot produce one. What the snapshot path costs is one **shared**
   read per (query, node), not one per client. A cross-node delta needs an *entity*-keyed window each
   node fills from the change stream it already subscribes to, which is a `ResumeSource` shape change.
+- **A ring is complete from its floor, and never from the start of time** (24.0.0). A
+  `RingChangeBuffer` ring is born with one: the lsn of its first patch, or the lsn its window was
+  read at (`floorAt(qid, lsn)`, which only ever raises it and drops what a re-read superseded). A
+  cursor below the floor re-snapshots. A ring used to be born with none, so a cursor minted on
+  another node resumed as a delta over changes this node never retained.
 - **Fanout is at-most-once, and a gap is detected rather than assumed away.** The replicator stamps
-  every published change with `producer` + `seq`; a `sync` node that sees a skipped sequence
+  every published change with `producer` + `seq`; a `sync` node that sees a skipped sequence —
+  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
@@ -449,17 +560,17 @@ wire twice by a reconnect that raced an ack.
   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
@@ -485,9 +596,11 @@ wire twice by a reconnect that raced an ack.
   the new node never held, so the resume falls back correctly rather than silently; the `qidOf`
   removal itself costs nothing, because every qid a node computes comes from a decoded frame and
   `JSON.parse` produces none of the values the two spellings disagreed about.
-- **A topic guard that *fails* keeps the topic.** On the re-auth pass, only a denial
-  (`X_TOPIC_FORBIDDEN`, or a policy denial) unsubscribes; anything else increments `hub.guardFailures`
-  and logs `channel.guard_failed`. `catch { unsubscribe }` reported a store that timed out as a
+- **A topic guard that *fails* suspends the topic.** On the re-auth pass, only a denial
+  (`X_TOPIC_FORBIDDEN`, or a policy denial) unsubscribes; anything else increments `hub.guardFailures`,
+  logs `channel.guard_failed` and SUSPENDS the seat — kept, and sent nothing, until a pass
+  succeeds. Two answers are denials before any rule runs: a `null` actor on a channel with a `row`
+  loader, and a loader the tenant guard refused. `catch { unsubscribe }` reported a store that timed out as a
   revoked grant — every topic on every re-authenticated socket, silently, with the client never told
   to resubscribe. The initial `subscribe` is deliberately not split that way: there is no
   subscription to keep, so a guard that raises refuses that subscribe and the client hears about it.
@@ -516,7 +629,8 @@ wire twice by a reconnect that raced an ack.
 - **A full presence frame is capped** at `maxMembers` (256) and carries `total`, so a 5,000-person
   room renders "and 4,744 others" instead of shipping 5,000 members to every joiner. The set itself
   is never capped — the sweep differences it — and one node per topic runs that sweep, elected
-  through the shared store, rather than every node re-reading every room it has ever seen.
+  through the shared store, rather than every node re-reading every room it has ever seen; the
+  leader's lease carries its roster, so a takeover announces a dead leader's members.
 - **Deliveries are serialized per query id, not per node.** A change is fanned out inside that
   query's own FIFO lane, so two changes off the bus cannot interleave: the window one of them
   writes is the window every subscriber's gate reads, and patch frames leave in lsn order. Every
@@ -548,7 +662,7 @@ wire twice by a reconnect that raced an ack.
   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
@@ -556,14 +670,36 @@ wire twice by a reconnect that raced an ack.
   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
-  defaults for `x dev` and every test.
+  `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()`. `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
+  process published, so one rejected `transport.publish` costs a redial and loses nothing.
+  `stats()` carries `restarts` and `failure`; **`replicator.running` is what a readiness check
+  reads**. Until 24.0.0 the death was recorded in `stats().failure`, which nothing read.
+- **A row crosses the bus as the row it was** (`replicator-row.ts`, 24.0.0). The bus carries text;
+  `parseEnvelope` revives each value through the column its entity declared (`entityForTable` +
+  `$parse`) — a `timestamp()` is a `Date` again, `bytes()` (sent as base64) a `Uint8Array` — and
+  decides by that declaration, never by what a value looks like. A table with no entity on the
+  node, and a value its column refuses, cross as they arrived. Until 24.0.0 a `Date` reached the
+  matcher as an ISO string and every window ordered by a timestamp mis-sorted on any deployment
+  with a bus.
+- **`ChangeEvent.omitted` names what an update could not carry** (24.0.0). Postgres logs no bytes
+  for an out-of-line (TOAST) value an `UPDATE` did not touch. Under `REPLICA IDENTITY FULL` the
+  value is copied from the old tuple and `after` is whole; under any other identity `after` lacks
+  the property and `omitted` lists it (entity property names), so a consumer re-reads the row
+  rather than adopting a partial one.
 - **`selectChangeFeed(env, { entities })` decides which feed a boot installs** — same law
   `selectMailDriver` follows: an unset variable means the embedded default. It returns `{ feed,
   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`)
@@ -580,6 +716,14 @@ wire twice by a reconnect that raced an ack.
   `X_REPLICATION_TLS` naming the check. Until 22.1.0 `prefer` verified — every private-CA server
   (CNPG) failed as a refused write — and the raw socket kept feeding ciphertext to the reader
   after the upgrade, so a trusted CA still hung the stream.
+- **A password the network could use is sent only when the mode allows it** (24.0.0): a
+  cleartext or md5 request is answered under `require`, `verify-ca`, `verify-full` (the session is
+  guaranteed encrypted) or `disable` (the operator said it is not), and refused with
+  `X_REPLICATION_FAILED` under `prefer` — the default — and `allow`, where a stripped upgrade falls
+  back to cleartext without a word. SCRAM is answered under every mode. `require` encrypts to
+  whoever answered and verifies no certificate: it protects the password from a passive listener
+  only. An attacker on the path needs `verify-ca` or `verify-full` to be stopped; `require`
+  answers a cleartext or md5 request for libpq parity, not because it is safe against one.
 - **`REPLICATION` is a cluster-wide grant.** A `replication=database` session may also run
   `BASE_BACKUP` and `START_REPLICATION PHYSICAL` with no database check, so on a shared Postgres
   cluster the role could copy every database, `pg_authid` included, drop other slots and exhaust
@@ -588,10 +732,25 @@ wire twice by a reconnect that raced an ack.
   `REPLICATION` to an app role on a shared cluster. Every fix line that hands the grant over says
   so (`REPLICATION_GRANT_WARNING`, `pg-wire.ts`) and links
   [`docs/ops/01-kubernetes.md`](../../docs/ops/01-kubernetes.md#replication-is-a-cluster-wide-grant).
-- **`PgAdvisoryLock` is the production `AdvisoryLock`** — `SELECT
+- **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: `postgresAdvisoryLock()` watches its idle session through
+  `PgConnection.watchIdle` (EOF, a read error or a server `FATAL`; no polling), and
+  `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
+  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
+  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.
-  `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 }`:
@@ -614,7 +773,16 @@ wire twice by a reconnect that raced an ack.
   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. The bucket needs
+  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
   nats-server ≥ 2.11 (batch direct get, per-message TTL); an older one is `X_TRANSPORT_PROTOCOL` on
   the first dial, never a retry loop, because no amount of reconnecting makes a server newer.
 - **The lsn is `<commit position><row position in the transaction>`, 24 hex characters.** Neither
@@ -622,7 +790,14 @@ wire twice by a reconnect that raced an ack.
   *transactions* in commit order, so per-record WAL positions are not monotonic across them. The
   pair sorts in delivery order and is byte-identical on replay, which is what turns at-least-once
   redelivery into a drop instead of a duplicate.
-- **A keyed table does not need `REPLICA IDENTITY FULL`; a table with NO identity is warned**
+- **A channel with params needs `REPLICA IDENTITY FULL` on its `records` tables** (24.0.0). It
+  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
+  `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**
   (`As of 2026-09-23`). Under DEFAULT an update carries no old tuple and a delete only the key, and
   neither decides a live query: the shared window holds the whole row, so a row leaving the result
   set is decided from the window and a delete by `holds(id)` — proved on real WAL by
@@ -685,7 +860,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `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` |
-| `NotImplementedError` (extends `RealtimeError`) | `X_NOT_IMPLEMENTED` | `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` |

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "23.0.0",
+  "version": "25.0.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": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/query": "23.0.0",
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/entity": "25.0.0",
+    "@ultimat3/policy": "25.0.0",
+    "@ultimat3/query": "25.0.0",
     "nats": "2.29.3"
   }
 }