@ultimat3/realtime 20.2.1 → 22.0.0

package/README.md

@@ -8,7 +8,7 @@ Three tiers, one ladder, one protocol. Climbing a rung is a config change, never
 |---|---|---|
 | **1 — channels** | `publish`/`subscribe` on typed topics, presence, cursors, typing indicators | ~0. One filtered `send` per subscribed socket — no DB, no replication slot. **At most once**: a frame backpressure drops is counted, never replayed |
 | **2 — live queries** | the list updates when someone else edits; your own click feels instant | one change feed + a matcher per query id + a bounded change window |
-| **3 — local-first** | writes that survive being offline | a durable local store, a rebase log, client-side migrations, a conflict story per mutator |
+| **3 — local-first** | writes that survive being offline | a durable outbox, client-side migrations, a conflict story per mutator (plan 101 slice 12) |
 
 Tier 2 covers ~90% of "make it realtime". Tier 3 buys exactly one extra property — offline writes — and charges a client database for it. Do not buy it by accident.
 
@@ -25,35 +25,34 @@ export const liveFeed = query({
 
 // mutator (action + optimistic local twin)
 export const likePost = mutator({
-  // Convergent, not incremental: `local` replays on every rebase, so applying it N times has to
+  // 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 }) {
     tx.posts.update(postId, (p) =>
       p.likedByMe ? {} : { likedByMe: true, likeCount: p.likeCount + 1 });
   },
   async server(ctx, { postId }) { return ctx.posts.like(postId); },
-  conflict: 'server-wins', // | 'last-write-wins' | custom(merge)
+  conflict: 'server-wins', // | 'last-write-wins' | { kind: 'custom', merge(local, server) }
 });
 ```
 
-`persist: true` on the query moves that route from tier 2 to tier 3. Same mutator, same authz, same
-frames — `local` starts writing to a durable store and the mutation queue starts surviving reloads.
-**One protocol serves all three tiers**: a channel message, a live-query patch and an offline
-mutation drain are frames in the same discriminated union (`src/sync-protocol.ts`), so the client's
-frame handler is unchanged between rungs.
+A write is always HTTP: `useMutation(likePost)` runs `local` into the page store's optimistic
+overlay, then POSTs the mutator's action with an idempotency key. The socket is **read-only** —
+subscriptions go up, snapshots, patches and presence come down (protocol 3, 21.0.0).
 
-`local` must be pure — no I/O, no `Date.now()`, no `Math.random()` — because rebase replays it.
+`local` must be pure and convergent — no I/O, no `Date.now()`, no `Math.random()`, and applying it
+over its own result changes nothing — because the overlay REPLAYS it over every server update.
 
 ## Two entries, and which one an island may import
 
-`As of 2026-08`, `@ultimat3/realtime` is the **client** half — the hooks, the identity map, the offline queue, the
-wire and the reconnect vocabulary. `@ultimat3/realtime/server` is the bus, the Postgres replication
+`@ultimat3/realtime` is the **client** half — the hooks, the page's record store, the offline outbox,
+the wire and the reconnect vocabulary. `@ultimat3/realtime/server` is the bus, the Postgres replication
 path and the sync node. A name lives in exactly one of them; the `Entry` column below says which.
 
 The split is not cosmetic. `nats` `require()`s `stream/web`, so one barrel carrying `openNatsClient`
-beside `useLive` made the browser island this package promises **unbuildable** —
+beside the client hooks made the browser island this package promises **unbuildable** —
 `Browser build cannot require() Node.js builtin: "stream/web"`. `packages/cli/src/realtime-browser-barrel.test.ts`
-bundles an entry importing only `useLive` for `target: 'browser'` and fails the build if either
+bundles a client-only entry for `target: 'browser'` and fails the build if either
 half reaches the other; `barrel-split.test.ts` fails if one name is exported from both.
 
 Migrating from 7.x: an import of a **server** name changes its specifier and nothing else.
@@ -63,81 +62,123 @@ Migrating from 7.x: an import of a **server** name changes its specifier and not
 + import { ChannelHub, createSyncNode, LiveQueryRegistry } from '@ultimat3/realtime/server';
 ```
 
-Client names — `useLive`, `liveHookFor`, `LiveClient`, `OfflineQueue`, `RebaseLog`, `IdentityMap`,
-`encode`/`decode`, every `X_*` error class — are unchanged.
+Client names — the hooks, `RecordStore`, `OfflineQueue`, `encode`/`decode`, every `X_*` error
+class — stay on `.`.
 
 ## Public API
 
 | Concern | Entry | Export |
 |---|---|---|
-| tier 1 | `./server` | `topic`, `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
+| 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 |
 | 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`, `backoffDelay`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
-| the client store | `.` | `IdentityMap` — one row value per `(entity, id)` — plus `RowWindows`, `rowKey`, `privateScope`, `applyPatches`/`orderAfterPatches` |
-| tier 3 | `.` | `MemoryLocalStore`, `createOpfsLocalStore`, `OfflineQueue`, `RebaseLog`, `reconcile`, `custom` |
-| wire | `.` | `PROTOCOL_VERSION`, `encode`, `decode`, `Frame` |
-| halves | both | `LiveClient` on `.`; `createSyncNode` / `listenSyncNode` (`sync` role) on `./server` |
+| 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 |
+| wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
+| the node | `./server` | `createSyncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue`, `hasLiveClient` |
-| the server render's client | `.` | `serverRenderLiveClient` — what a hook falls back to with no DOM; `LiveClientLike` is the shape both it and `LiveClient` satisfy |
-| the typed projection | `.` | `liveHookFor` — one query bound to one named hook |
+| hooks | `.` | `useQuery`, `useRecord`, `useMutation`, `useMutationQueue`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
+| offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `MemoryLocalStore` |
+| the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 
-## The four hooks
+## `channelRef` — a channel an island can hold
 
-Register the client once, in the app entry. Every hook reads it from there — no hook takes a client
-argument, and one that runs **in a browser** before the registration is `X_LIVE_CLIENT_MISSING`,
-never a default.
-
-**A server render is not a missing registration.** With no DOM there is no socket a client could
-have been registered for, so every hook falls back to `serverRenderLiveClient()`: `useLive` answers
-`state() === 'loading'` with no rows, `useConnection()` reports online, both queue counts are `0`,
-and `mutate` / `drain` refuse with `X_LIVE_SERVER_RENDER`. The page renders its own loading branch
-and a hydrating island takes over. `hasLiveClient()` still answers `false` there, which is what a
-component with a static fallback is asking. `useLive` in a page BODY is not made live by this — a
-page component never runs in a browser; put the live half in an `island()`.
+A channel has two halves, and they live in two files so a browser chunk never bundles an entity or
+a policy. `channelRef(name, { params, catchUp })` is the **client** half: the name, the ordered
+params and the catch-up read — nothing else. The server declares the records and who may join on
+**the same ref** with `channel(ref, { … })`, so the name and the params are written once.
 
 ```ts
-setLiveClient(new LiveClient({ signal: createSignal, connect, buildId, store, queue }));
+// app/posts/channel-ref.ts — imported by islands
+import { channelRef } from '@ultimat3/realtime';
+
+export const ORG_POSTS = channelRef('org-posts', {
+  params: ['orgId'],
+  catchUp: { name: 'orgPosts' },   // the query a client re-runs on `replay-gap` or a new epoch
+});
 
-const feed = useLive(liveFeed, () => ({ orgId: actor.orgId })); // feed(), feed.state(), feed.unsubscribe()
-const connection = useConnection();                             // .offline .online .reconnectAt .updateAvailable
-const like = useMutation(likePost);                             // await like(input); like.pending
-const queue = useMutationQueue();                               // .pending .failed .drain()
+// The one topic spelling both halves use.
+ORG_POSTS.topic({ orgId: 'org_1' });   // 'org-posts.org_1'
 ```
 
-| Rule | Why |
-|---|---|
-| **No `solid-js` import.** Reactivity is the `SignalFactory` the client was built with | one reactive runtime per app, and a tier-3 package that installs and tests with none |
-| Every member is a **getter**, every result set an **accessor** | a value snapshotted at hook time never re-renders |
-| A thunk `input` is read **once**, at subscribe time | nothing here re-runs it; changing input is a new subscription |
-| The caller owns `unsubscribe` | this layer does not know what a mount is |
-| Every subscription handle (`useLive`'s return, `client.subscribe(topic, …)`'s return) is `Disposable` | `using feed = useLive(liveFeed, () => input)` unsubscribes on scope exit — the same call as `unsubscribe()`, never a second teardown path |
-| `pending` / `failed` are read off the queue, through an invalidation signal refreshed on each `mutate` and `drain` | the count is never a second copy of the queue, and `OfflineQueue` holds arrays, not signals |
+The server half, in its own file, names the entity and the policy on the same ref —
+`channel(ORG_POSTS, { records: [posts], policy: feedRead })` — and an island subscribes with
+`useChannel(ORG_POSTS, { orgId })`.
 
-Tier 2 has no queue, so `pending` is `0` there — stated, not guessed.
+`ref.topic(params)` is the one spelling of the topic both halves use (`org-posts.<orgId>`), and
+`bun run channel-literals` refuses a hand-built topic anywhere else. A bad name or a repeated param
+is `X_CHANNEL_DECLARATION_INVALID` at declaration. `catchUp` is read on every access, so a query
+whose name `registerQueries()` stamps at boot is picked up. The reference app's
+[`app/posts/channel-ref.ts`](../../examples/dummy/apps/web/app/posts/channel-ref.ts) is the idiom.
 
-### The typed one: `liveHookFor`
+## The hooks
 
-`useLive(query, input)` takes any object carrying a `name`, so it cannot type either side.
-`liveHookFor` binds one declared `query({ live: true })` to one named hook and carries both types
-through — the query's `input` in, its row type out. It is not a second subscribe path: it *is*
-`useLive`, with the name and the types already bound.
+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.
 
 ```ts
-export const useLiveFeed = liveHookFor(liveFeed); // app/feed/hooks.ts — one line, no codegen
-
-const feed = useLiveFeed({ orgId: actor.orgId }); // feed()[0].title typechecks
-useLiveFeed({ orgIdd: actor.orgId });             // does not compile
+import {
+  type ChannelRef,
+  type MutatorLike,
+  useChannel,
+  useConnection,
+  useMutation,
+  useMutationQueue,
+  usePresence,
+  useQuery,
+  useRecord,
+} from '@ultimat3/realtime';
+
+declare const orgId: string;
+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;
+
+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 like = useMutation(LIKE_POST);                                // await like(input); like.pending
+const connection = useConnection();                                 // .offline .online .reconnectAt .updateAvailable
+const writes = useMutationQueue();                                  // .pending .failed
+const feedChannel = useChannel(orgFeed, { orgId }, { onEvent });   // records → the store; events → onEvent
+const room = usePresence(orgFeed, { orgId });                      // the channel's roster
 ```
 
-The query's name is read **per call**, never at bind time: `registerQueries()` stamps it at boot,
-after a module-level binding has already run. Binding a query with no `live: true` is
-`X_QUERY_NOT_SUBSCRIBABLE`, thrown where the binding is written — a read that never patches has no
-subscription to hold, and the non-live read from a component is `query.client({ baseUrl })`.
-`type-pins.ts` fails the build if the hook ever widens either type.
+**One socket per origin and principal**: the page's socket lives in a `SharedWorker`
+(`@ultimat3/realtime/sync-worker`, bundled by `x build`) shared by every tab; with no worker the
+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.
+
+`<AsyncRegion state={feed()} …/>` takes the answer as-is: `AsyncState` is `@ultimat3/core`'s, the
+same type `@ultimat3/ui` renders.
+
+| Rule | Why |
+|---|---|
+| 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 |
+| 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 |
+| Every member is a **getter**, every result an **accessor** | a value snapshotted at hook time never re-renders |
+| `input` is read **once** | nothing here re-runs it; a changed input is a new `useQuery` |
+| The caller owns `release()` / `using` | this layer does not know what a mount is |
+
+**A server render** (no install, no DOM) answers `pending`, reports online and creates no page
+state; a `useMutation` call refuses with `X_LIVE_SERVER_RENDER`. With a DOM and no install, every
+hook is `X_REALTIME_UNINSTALLED`. `hasPageSocket()` is the guard a component with a static fallback
+asks.
 
 ## Who a socket is
 
@@ -147,16 +188,25 @@ resolves is what every policy downstream decides against — the topic guard, `a
 the per-tenant subscription cap.
 
 ```ts
-createSyncNode({
+import type { Actor } from '@ultimat3/core';
+import type { SyncGrant, SyncNodeOptions } from '@ultimat3/realtime/server';
+
+declare function sessionFrom(
+  request: Request,
+): 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.
+const options: Pick<SyncNodeOptions, 'authenticate'> = {
   // From @ultimat3/auth, or anywhere else: `sync` imports no authenticator, exactly as it owns no
-  // mutation logic. `refresh` is yours too, so the framework retains no credential of its own.
+  // business logic. `refresh` is yours too, so the framework retains no credential of its own.
   authenticate: async (request) => {
     const session = await sessionFrom(request);
     return session === null
       ? null
       : { actor: session.actor, expiresAt: session.expiresAt, refresh: () => renew(session.token) };
   },
-});
+};
 ```
 
 | The answer | What the node does |
@@ -226,37 +276,22 @@ authenticated socket is the cheapest foothold there is.
 `input` reaches `canonicalJson`, which recurses, so an unbounded one is a stack overflow in the
 process rather than a slow query.
 
-## One row per `(entity, id)`
+## One record per `type:key`, per page
 
-Two components subscribing to two live queries that both return post #7 hold **one** row, not two
-copies of it. That is the client's whole store: a `LiveClient` owns one `IdentityMap`, every live
-window is an ordered list of ids over it, and the tier-3 local store's tables are membership over
-the same map. A write through any of them is the same row for all of them.
-
-```ts
-const feed = useLive(liveFeed, () => ({ orgId }));   // holds p1, p2, p7
-const pinned = useLive(livePinned, () => ({ orgId })); // holds p7
-
-await like({ postId: 'p7' });  // one optimistic write...
-feed()[2] === pinned()[0];     // ...and both views are looking at it
-```
-
-Nothing is declared to get this. There is no normalization schema, no cache key, no selector — an
-app writes `useLive` and `useMutation` exactly as before.
+Two islands showing post #7 hold **one** record, not two copies. The page's `RecordStore` is the
+whole client store: every live window, every `useQuery` list and every `useRecord` is a projection
+over it, and an HTTP answer's records, a socket patch and an optimistic write all land in it.
 
 | Rule | Why |
 |---|---|
-| Identity is `(entity, id)`, never `id` alone | two entities may spell one id the same way; `posts/7` and `users/7` are two rows |
-| The entity comes **from the server**, on the `snapshot` frame | the shape is compiled server-side out of `sql`; a browser cannot derive it, and a scope an app declares by hand is a second place for it to be wrong |
-| A subscription the server named no entity for keeps its rows in a scope private to itself | no sharing is a stale view; wrong sharing is two entities merged into one row |
-| A value is **replaced, never mutated** — every write is a new object | a mutated row is a render that never happens |
-| A write **merges** columns; it never drops one | two queries may project different columns of one row, and the narrower one must not blank what the wider one renders |
-| A row is dropped when the last window and the last table let go of it | an infinite scroll must not retain every row it ever saw |
-| A rebase rolls back through the same map | the optimistic write, the server's truth and the replay are one row's history, not a second copy's |
-
-`entity` on a `snapshot` frame is **additive**: an older node omits it and the client falls back to
-the private scope, a newer node sends it and an older client ignores it. Both skews are safe in
-both directions, which is why it carries no `PROTOCOL_VERSION` bump.
+| Identity is `type:key` — the entity's NAME and the key the SERVER computed | two entities may spell one key the same way, and the browser has no entity schema to derive a key from |
+| 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 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 |
+| A principal change clears the store | nothing of the previous principal survives in memory |
 
 ## Reconnect is the hard part
 
@@ -284,7 +319,7 @@ sends a `reconnect` frame carrying that delay — clients redistribute instead o
 because refusing without one just moves the herd next door.
 
 The client dials itself back. A closed socket arms one timer — the node's delay when a `reconnect`
-frame assigned one, otherwise `backoffDelay()` — and that timer calls `connect()`, which re-subscribes
+frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `BackoffPolicy` — and that timer calls `connect()`, which re-subscribes
 every registration **and re-announces every topic**. Topic membership is state on the node's socket
 and `hello` carries none of it, so without that half a channel goes silent from the first reconnect
 onwards while its handler is still installed — and its presence membership is swept, because
@@ -292,14 +327,18 @@ subscribing to a topic *is* joining the room. `reconnectAt` is what a component
 waits; `close()` cancels it, and `connect()` starts over. The timer comes from an injected
 `Scheduler`, so a test fires it by hand instead of sleeping.
 
+A browser's curve is `browserBackoff` — the same core curve, `equal` jitter, capped at
+`BROWSER_RECONNECT_MAX_MS` (4s) where the server-side `defaultBackoff` caps at 30s: a node that
+comes back is reached within seconds, and so is the `update-available` it carries. The socket
+engine (one per origin, in the `SharedWorker`) keeps none of it across pages: a page arriving while
+the node is down dials at once on a fresh curve, and the last page leaving forgets the target, so
+the next build's page never dials with the old build id.
+
 ### Liveness: `heartbeatMs`
 
 A half-open socket — the TCP connection is dead and no `close` ever fires — is invisible to the
-browser. The client is the only thing that can end one.
-
-```ts
-new LiveClient({ signal, connect, buildId, heartbeatMs: 15_000 }); // 0 disables the pass
-```
+browser. The client is the only thing that can end one, and the page socket beats at the default
+below (`heartbeatMs` on the internal `LiveClient`; `0` disables the pass).
 
 | Property | Behaviour |
 |---|---|
@@ -329,7 +368,8 @@ wire twice by a reconnect that raced an ack.
 | Backpressure **declines**, it does not fail | over `MAX_BUFFERED_BYTES` (1 MiB, the node's `backpressureLimit` at the other end of the same socket) the sender throws `X_TRANSPORT_UNAVAILABLE`, the mutation stays pending and the next drain resumes there. `ClientSocket.bufferedAmount` is optional; a socket that does not report it is treated as never backed up |
 | Delivery is therefore at least once | every mutation carries an idempotency key — the `key` argument, or `<mutator>:<uuid>` — and the resend carries the same one |
 | A lost connection **cancels the pass it interrupted** | the lane orders passes against each other, but a socket death is not a pass and cannot reach one parked inside `send`. `requeueInflight()` bumps a connection epoch; a pass whose epoch went stale returns and leaves the rest `pending`. Without it the parked pass resumed and marked everything behind it `inflight` for a dead socket — never re-sent (`inflight` is not sendable) and never acked |
-| The store is handed a **snapshot**, never the live entries | `QueueStore.save` is a durable write and may await before it reads; given the array itself it persists a status that was never true when it was called |
+| 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` |
 
 ### Limits, stated plainly
 
@@ -353,16 +393,9 @@ wire twice by a reconnect that raced an ack.
   froze at the last snapshot and `shouldResnapshot`'s lag check answered "re-snapshot" for every
   client connected longer than `maxLagMs` — the delta resume the retained window exists for, dead
   exactly during the deploy storm it was built for.
-- **An accepted mutation is committed, not merely acknowledged.** The `ack` drops the journal row
-  and the rebase-log entry — there is nothing to roll back *to* any more, and a later reconcile
-  would otherwise replay a write the server already applied over rows that have moved on. The row
-  itself stays exactly as the optimistic twin left it: an accepted write does not flicker.
-- **A refused mutation is rolled back, not retried.** An `ack` carrying an error undoes that
-  mutation's optimistic write *and* every write made after it — newest first — then replays the
-  others without it, which is sound only because `local` is pure. The refused intent is dropped from
-  the rebase log rather than retried: a denial is a decision about that intent, and replaying it
-  would put the write the server refused back on the screen. Idempotent for a key the log does not
-  hold, because a denial can arrive twice and tier 2 records nothing to undo.
+- **The socket carries no writes (protocol 3, 21.0.0).** A write is HTTP; an `ack` is only ever a
+  refusal, naming the subscription it refused (that window renders `failed`) or the socket for a
+  frame the node could not read — including a `mutate` from a client one major behind.
 - **Nothing on the client detects drift, and nothing ever did.** `verifyDigest()` claimed to and had
   no caller (deleted 2026-08-23); the `digest` it read went with it (2026-08-24), along with the
   `count` beside it. What detects drift is the server's `desynced` mark and the re-snapshot it
@@ -388,10 +421,10 @@ wire twice by a reconnect that raced an ack.
   cannot mark a subscriber desynced — which is to say it cannot do any of the three things above.
   `WsLike.subscribe`/`unsubscribe` stay **declared and unused**: the interface is structural and a
   tracked app implements it, so deleting the members breaks that app's typecheck.
-- **Inbound frames are ordered per `mutate`-socket and per subscription, never per socket.** A
+- **Inbound frames are ordered per subscription, never per socket.** A
   global per-socket lane puts every frame behind the slowest one, and the slowest one is a
   subscribe's snapshot read — the round trip every reconnecting client pays in a restart storm.
-  `mutate` is one lane per socket; `subscribe` is one lane per sid, or per topic name; `hello` and
+  `subscribe` is one lane per sid, or per topic name; `hello` and
   the server-authored kinds are unlaned. A lane exists only while work is queued on it, because a
   lane keyed by a client-chosen sid that outlived its work is an unbounded map one socket can grow.
 - **`qid` is `@ultimat3/query`'s `queryHash(name, input)`** — `<name>:<first 16 hex of
@@ -490,11 +523,15 @@ wire twice by a reconnect that raced an ack.
   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.
-- **`selectTransport(env)` decides which transport a boot fans out on** — the same law again, and
-  the only place that reads `NATS_URL`. It returns `{ transport, mode, detail, bucket,
-  presenceTtlMs, connect }`: unset → `InProcessTransport` and `mode: 'embedded'`, set → a
-  `NatsTransport` on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so two apps on one
-  cluster do not share one presence namespace), validated here rather than on first connect.
+- **`selectTransport(env, realtime)` decides which transport a boot fans out on** — and since
+  22.0.0 the CONFIG decides it, not the environment: `realtime` is `app.config.ts`'s
+  `{ transport, urlEnv }`. It returns `{ transport, mode, detail, bucket, presenceTtlMs, connect }`:
+  `'memory'` → `InProcessTransport` and `mode: 'embedded'`; `'nats'` → a `NatsTransport` dialling
+  the variable `urlEnv` names, on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so
+  two apps on one cluster do not share one presence namespace), validated here rather than on
+  first connect. Both mismatches refuse with `X_CONFIG_INVALID`: `'nats'` with that variable unset,
+  and `'memory'` with `NATS_URL` (or the named variable) set — an operator who set one expected
+  fanout across nodes. Until 22.0.0 `NATS_URL` alone decided and both keys were read by nothing.
   `presenceTtlMs` comes back with it because the bucket's whole-stream age limit was derived from
   it — a `PresenceRegistry` given a different number would report members leaving that never left.
   Selection is pure; `connect()` is the dial, so an unreachable bus fails at boot.
@@ -528,16 +565,9 @@ wire twice by a reconnect that raced an ack.
   running half: one per change delivered off a relation that is not FULL, so the decisions it
   actually cost are countable rather than silent. A hard refusal at `x verify` time is the
   follow-up.
-- Tier 3's OPFS SQLite store is browser-only, is **not built**, and throws `X_NOT_IMPLEMENTED` on
-  call. `createOpfsLocalStore` is exported from `.` and stays there when it ships — there is no
-  third entry to wait for, and the refusal used to name one (`@ultimat3/realtime/browser`, a
-  subpath `exports` never declared). `MemoryLocalStore`, beside it on `.`, implements the full
-  journal/rollback/replay semantics today and is what the refusal's `fix:` names. It holds
-  membership and the journal; the row values are the client's one `IdentityMap`, which is what a
-  browser store has to inherit rather than re-implement.
-- The identity map is **per client**, in memory, and it is not a query cache: it answers "what is
-  row X now", never "have I run this query before". Nothing evicts by time or size — a row lives
-  exactly as long as a window or a table holds it.
+- The record store is **per page**, in memory, and it is not a query cache: it answers "what is
+  record X now", never "have I run this query before". Nothing evicts by time or size — a record
+  lives as long as something holds it. Persisting it (IndexedDB) is plan 101 slice 12.
 
 ## Errors
 
@@ -545,7 +575,8 @@ wire twice by a reconnect that raced an ack.
 `X_PROTOCOL_VERSION` · `X_CURSOR_STALE` ·
 `X_REBASE_CONFLICT` · `X_TRANSPORT_UNAVAILABLE` · `X_TRANSPORT_PROTOCOL` ·
 `X_REPLICATION_FAILED` · `X_REPLICATION_PROTOCOL` · `X_REPLICATOR_SLOT_HELD` ·
-`X_LIVE_CLIENT_MISSING` · `X_LIVE_SERVER_RENDER` · `X_LIVE_QUERY_UNKNOWN` ·
+`X_REALTIME_UNINSTALLED` · `X_SYNC_UNCONFIGURED` · `X_RECORD_REJECTED` ·
+`X_LIVE_SERVER_RENDER` · `X_LIVE_QUERY_UNKNOWN` ·
 `X_LIVE_REPLICA_IDENTITY` ·
 `X_SOCKET_UNAUTHENTICATED` · `X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED` ·
 `X_TIMEOUT`
@@ -553,8 +584,9 @@ wire twice by a reconnect that raced an ack.
 `X_NOT_IMPLEMENTED` and `X_TIMEOUT` are **borrowed** from `@ultimat3/core`, which owns and titles
 them — `REALTIME_BORROWED_ERROR_CODES`. Everything else on that list is realtime's own.
 
-Topics deny by default: a topic with no matching guard is forbidden. An authz hole is not a config
-option someone forgot to set.
+Topics deny by default: a topic no `channel()` declares is forbidden, and a `channel()` with no
+`policy` is refused at declaration (`X_CHANNEL_DECLARATION_INVALID`) — a public channel writes
+`policy: allow('public')`. An authz hole is not a config option someone forgot to set.
 
 An upgrade `authenticate` refuses is `X_SOCKET_UNAUTHENTICATED` (401) and one it *could not decide*
 is `X_SOCKET_AUTH_UNAVAILABLE` (503). Two codes, because the two have opposite instructions: the
@@ -573,3 +605,32 @@ The fix is `x queries list --json`, and the name the client sent is echoed back
 never is.
 
 `As of 2026-07`: tiers 1–2 target v1, tier 3 targets v2.
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `CursorStaleError` (extends `RealtimeError`) | `X_CURSOR_STALE` | `src/page-errors.ts` |
+| `FrameRateLimitError` (extends `RealtimeError`) | `X_FRAME_RATE_LIMIT` | `src/errors.ts` |
+| `LiveQueryUnknownError` (extends `RealtimeError`) | `X_LIVE_QUERY_UNKNOWN` | `src/errors.ts` |
+| `LiveRowUnidentifiedError` (extends `RealtimeError`) | `X_LIVE_ROW_UNIDENTIFIED` | `src/errors.ts` |
+| `NotImplementedError` (extends `RealtimeError`) | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `ProtocolVersionError` (extends `RealtimeError`) | `X_PROTOCOL_VERSION` | `src/page-errors.ts` |
+| `RealtimeError` | any `RealtimeErrorCode` — `REALTIME_ERROR_CODES`; the base of every other class here, thrown directly for a code none of them covers | `src/realtime-error.ts` |
+| `RealtimeUninstalledError` (extends `RealtimeError`) | `X_REALTIME_UNINSTALLED` | `src/page-errors.ts` |
+| `RebaseConflictError` (extends `RealtimeError`) | `X_REBASE_CONFLICT` | `src/page-errors.ts` |
+| `RecordRejectedError` (extends `RealtimeError`) | `X_RECORD_REJECTED` | `src/page-errors.ts` |
+| `ReplicaIdentityError` (extends `RealtimeError`) | `X_LIVE_REPLICA_IDENTITY` | `src/replication-errors.ts` |
+| `ReplicationFailedError` (extends `RealtimeError`) | `X_REPLICATION_FAILED` | `src/replication-errors.ts` |
+| `ReplicationProtocolError` (extends `RealtimeError`) | `X_REPLICATION_PROTOCOL` | `src/replication-errors.ts` |
+| `ReplicatorSlotHeldError` (extends `RealtimeError`) | `X_REPLICATOR_SLOT_HELD` | `src/replication-errors.ts` |
+| `ServerRenderLiveError` (extends `RealtimeError`) | `X_LIVE_SERVER_RENDER` | `src/page-errors.ts` |
+| `SubscriptionLimitError` (extends `RealtimeError`) | `X_SUBSCRIPTION_LIMIT` | `src/errors.ts` |
+| `SyncUnconfiguredError` (extends `RealtimeError`) | `X_SYNC_UNCONFIGURED` | `src/page-errors.ts` |
+| `TopicForbiddenError` (extends `RealtimeError`) | `X_TOPIC_FORBIDDEN` | `src/errors.ts` |
+| `TransportProtocolError` (extends `RealtimeError`) | `X_TRANSPORT_PROTOCOL` | `src/errors.ts` |
+| `TransportUnavailableError` (extends `RealtimeError`) | `X_TRANSPORT_UNAVAILABLE` | `src/errors.ts` |
+| `WindowReadTimeoutError` (extends `RealtimeError`) | `X_TIMEOUT` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,9 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./server": "./src/server.ts"
+    "./boot": "./src/boot.ts",
+    "./server": "./src/server.ts",
+    "./sync-worker": "./src/sync-worker.ts"
   },
   "files": [
     "src",
@@ -36,8 +38,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/query": "20.2.1",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/query": "22.0.0",
     "nats": "2.29.3"
   }
 }

package/src/apply-patches.ts

@@ -3,7 +3,7 @@
 // app can reuse to apply the same patches to its own store.
 //
 // Order and values are folded separately: a live window keeps its ORDER here and its VALUES in the
-// identity map, so `applyPatches` is the array form of the same fold rather than a second one.
+// record store, so `applyPatches` is the array form of the same fold rather than a second one.
 
 import type { JsonObject, Row, RowPatch } from './json';
 

package/src/boot.ts

@@ -0,0 +1,72 @@
+// `@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.
+
+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 { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
+import type { RecordStore } from './record-store';
+
+/**
+ * The types the document marks persisted, read back off disk, then the page's outbox opened. None
+ * marked is no record disk.
+ */
+async function restoreFromDisk(store: RecordStore, principal: Principal): Promise<void> {
+  const types = persistedTypes();
+  const keep = scopeKey(principal);
+  let persister: RecordPersister | undefined;
+  try {
+    // A sign-out by full navigation (a form post and a redirect) never calls `rescope()`, so the
+    // previous principal's rows and queued writes would outlive it on disk. The boot is the one
+    // moment every page load passes: everything not THIS principal's goes, before anything is
+    // restored. An unscoped page (rendered for nobody) wipes nothing — it knows no principal.
+    // Trade-off: two principals in two tabs of one browser — the newer boot wipes the other's
+    // disk; that tab keeps its records in memory and re-persists them on its next write.
+    if (keep !== undefined) await (await pageLocalStore()).wipeOthers(keep);
+    if (types.size > 0) {
+      persister = recordPersister({ store, local: await pageLocalStore(), types });
+      await persister.restore();
+    }
+  } catch (error) {
+    // A disk the browser refused (quota, a private window) costs the offline copy, never the page.
+    console.error(error);
+  }
+  // The outbox opens with the page, not with the first write or live hook: a reload that holds
+  // neither must still replay what the previous load queued (on open, `online`, the SW's drain).
+  // After the restore, so a replay settles overlays over the records it restored.
+  // A queued write flushes the persisted rows first, so both are on disk before a reload can come.
+  const kept = persister;
+  pageOutbox({ beforeEnqueue: kept === undefined ? undefined : () => kept.flush() });
+}
+
+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").
+ */
+export function bootPage(
+  scope: { readonly principal: Principal } = pageClient().scope,
+): Promise<void> {
+  const host = globalThis as BootHost;
+  const started = host[BOOT_KEY];
+  const waiting = host[BOOT_RELEASE_KEY];
+  // 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 booted = restoreFromDisk(pageRealtime().store, scope.principal);
+  if (started !== undefined && waiting !== undefined) {
+    void booted.then(waiting);
+    return started;
+  }
+  Object.defineProperty(host, BOOT_KEY, { value: booted, configurable: true });
+  return booted;
+}
+
+// As a page script it runs itself; imported by a test (no DOM) it waits to be called.
+if (typeof document !== 'undefined') void bootPage();