@ultimat3/realtime 1.2.0 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@ Three tiers, one ladder, one protocol. Climbing a rung is a config change, never
 
 | Tier | What it gives you | What it costs you |
 |---|---|---|
-| **1 — channels** | `publish`/`subscribe` on typed topics, presence, cursors, typing indicators | ~0. Pub/sub over Bun's native WS. No DB, no replication slot |
+| **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 |
 
@@ -52,12 +52,15 @@ frame handler is unchanged between rungs.
 | tier 2 | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
 | replication | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `entityRow`, `changeLsn`, `commitPositionOf` |
 | fanout | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
-| the bus client | `NatsConnection`, `NatsProtocolParser`, `NatsKvSet`, `ensureKvBucket`, `parseNatsUrl`, `bunNatsStream`, `FakeNatsServer` |
-| reconnect | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `RingChangeBuffer`, `backoffDelay`, `drainPlan`, `AcceptBudget` |
+| the bus, behind `NatsTransport` | 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 | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `RingChangeBuffer`, `backoffDelay`, `Scheduler`, `timeoutScheduler`, `drainPlan`, `AcceptBudget` |
+| 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 | `LiveClient` (client), `createSyncNode` / `listenSyncNode` (`sync` role) |
+| a socket's identity | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
 | hooks | `setLiveClient`, `useLive`, `useConnection`, `useMutation`, `useMutationQueue` |
+| the typed projection | `liveHookFor` — one query bound to one named hook |
 
 ## The four hooks
 
@@ -79,15 +82,145 @@ const queue = useMutationQueue();                               // .pending .fai
 | 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 |
 
 Tier 2 has no queue, so `pending` is `0` there — stated, not guessed.
 
+### The typed one: `liveHookFor`
+
+`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.
+
+```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
+```
+
+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.
+
+## Who a socket is
+
+`createSyncNode({ 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.
+
+```ts
+createSyncNode({
+  // 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.
+  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 |
+|---|---|
+| a `SyncGrant` | upgrades, and the socket carries `grant.actor` |
+| `null` | **401** `X_SOCKET_UNAUTHENTICATED` — a decision, and the client's own condition |
+| a throw | **503** `X_SOCKET_AUTH_UNAVAILABLE` — a failure, reported, and the client is told to retry |
+| the option is absent | upgrades **anonymous**, and `start()` warns: every policy on that node is being asked about `null` |
+
+`expiresAt` is the half a long-lived socket needs: the node re-decides an expired grant on an
+interval (`reauthenticateIntervalMs`, 30s), calling `refresh` and then `hub.onActorChange` +
+`registry.reauthorize` — so a revoked role drops the topics and subscriptions it no longer covers,
+and survivors are re-snapshotted under the new authority. No `refresh`, and an expired grant closes
+the socket with `1008`; the client re-dials with a fresh credential. A `refresh` that *raises* keeps
+the socket and retries next pass — a token service timing out is not a revocation.
+
+**Without `authenticate` this node is single-tenant.** Every actor is `null`, so
+`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`.
 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.
 
+## What one socket may cost
+
+Every ceiling on this node, and the option that moves it. Each one is a default, not a policy: an
+app narrows or widens it where the object is constructed, and none of them can be raised from the
+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` |
+| live subscriptions per socket | 128 | `new LiveQueryRegistry({ maxPerSocket })` | `X_SUBSCRIPTION_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` |
+| 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` |
+| 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` |
+
+**Every one of those is taken as a reservation, not checked.** A subscribe holds nothing until three
+awaits later, so `SubscriptionBook.reserve(socket, sid)` and `ChannelHub`'s bridge reservation decide
+the sid claim and all four subscription caps **synchronously, before the first `await`**, against a
+count that already includes the subscribes still in flight. One WebSocket write carrying N subscribe
+frames used to pass every cap N times — the ordinary case, no attacker required. The slot is given
+back in a `finally`, and releasing twice is a no-op.
+
+The accept budget bounds the accept **rate**; `maxConnections` bounds the **count**, and they are
+two different attacks — 500 accepts/s held open with one keepalive each is 1.8M sockets an hour.
+The frame budget is per socket and checked at the top of the frame router, before anything a frame
+can reach: a subscribe frame is a database read, a presence write and a fleet-wide publish, and one
+authenticated socket is the cheapest foothold there is.
+
+`FRAME_LIMITS` is the wire's own hard ceiling — array lengths (`cursor.ids`, `patches`, `rows`,
+`members`) plus the depth and node count of a client-supplied `input`. It is not an option:
+`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)`
+
+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.
+
+| 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.
+
 ## Reconnect is the hard part
 
 A deploy drops N sockets at once and every one asks "what changed since X?". If that answer needs
@@ -111,16 +244,156 @@ sends a `reconnect` frame carrying that delay — clients redistribute instead o
 `AcceptBudget` is the receiving node's token bucket, and a refusal always carries a retry delay,
 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
+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
+subscribing to a topic *is* joining the room. `reconnectAt` is what a component renders while it
+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.
+
+### 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
+```
+
+| Property | Behaviour |
+|---|---|
+| Default | `DEFAULT_HEARTBEAT_MS`, 15s. The same number as the server's `realtime.heartbeatMs`, restated rather than read: that is server config and this is browser code |
+| 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 id recorded at the upgrade and the node's own, and neither can change on an open socket — 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 |
+| Silence | nothing received for **two** intervals ⇒ close `4000` (a private-use code, so it is distinguishable in a log) and arm the reconnect. Judged from the last frame of any kind, since the point is that bytes still cross |
+| Not an interval | one armed tick, re-armed by itself, on the same injected `Scheduler` the reconnect uses — a client is either beating on a live socket or backing off toward a new one, never both |
+
+`realtime.heartbeatMs` in `app.config.ts` is **read by nothing** `As of 2026-08`; this option is the
+only knob that changes behaviour.
+
+### A `send` that returned is not an acknowledgement
+
+`WebSocket.send` on a CLOSING socket discards the frame and returns normally, so a drained mutation
+is `inflight` — never `acked` — until the server settles it with an `ack`/`fail` frame, or a lost
+connection returns it to `pending`. Only `pending` entries are sendable, so nothing is put on the
+wire twice by a reconnect that raced an ack.
+
+| Rule | Consequence |
+|---|---|
+| `drain()` is **one pass at a time**, chained rather than joined | two overlapping passes read the same entry as sendable and put one key on the wire twice; a later pass could also overtake the one in front of it, which is the ordering guarantee gone. A caller that enqueued mid-pass gets a pass *behind* it, not that pass's promise |
+| A pass stops at the first refusal | continuing past a failure is how a sync engine reorders a user's intent |
+| 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 |
+
 ### Limits, stated plainly
 
-- **The change window is per node.** A client that reconnects to a *different* `sync` node has no
-  window there and takes a snapshot. Making the window shared (replicator-side, request/reply) is
-  gated on the milestone-6 reconnect benchmark — 50k sockets, forced restart, measure
-  time-to-consistent — because that number decides the topology.
+- **The change window is per node, and a `qid` window can only be.** A client that reconnects to a
+  *different* `sync` node has no ring there and takes the snapshot path. It is not a placement bug:
+  a patch is query-scoped, and the replicator is entity-scoped — it holds no compiled shape, no
+  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.
+- **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
+  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,
+  storage and replay window — and is deliberately not this mechanism.
+- **`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
+  diverged, which is the state it is actually in.
+- **The client's cursor advances on every patch, not only on a snapshot.** Left behind, `cursor.at`
+  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.
 - **A delta resume leaves the digest unverified** (`DIGEST_UNVERIFIED`). Only a snapshot re-establishes
   it. `verifyDigest()` is how a client detects drift and asks for a fresh one.
 - **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 flush re-snapshots rather than diverging.
+  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
+  `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.**
+- **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
+  table. A native publish cannot be refused per socket, cannot report the frame it dropped and
+  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
+  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
+  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 `<name>:<first 16 hex of SHA-256(canonicalJson(input))>`** — 64 bits `As of 2026-08`,
+  where it was a 32-bit FNV-1a. It is a *sharing* key: a hit is answered with the existing entry and
+  the seated window, both holding the first subscriber's input and rows, and input is client-chosen,
+  so a collision is one client served out of another's window. A rolling deploy across that change
+  costs one bounded snapshot per subscription — a cursor minted under the old format names a ring
+  entry the new node never held, so the resume falls back correctly rather than silently.
+- **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
+  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.
+- **A `sync` node shuts down in two phases.** The `accept` phase calls `stopAccepting()`: `/readyz`
+  answers 503 and a late upgrade is shed with `retry-after-ms`, while **every socket the node holds
+  keeps its patch stream**. The `close` phase is `drain()` then `stop()`. Registered with no phase it
+  all landed in `close`, and until that ran the node went on upgrading new websockets onto a process
+  that was going away. Both hooks are unregistered by the listener's `stop()`.
+- **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.
+- **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
+  lane is entered before any is awaited, so one slow policy pass never sets the node's pace, and
+  across query ids there is no ordering and none is wanted — a qid pins both the query and its
+  input. A lane that fails costs one query id: its own subscribers are desynced and re-snapshotted
+  on the next flush, every other query id still sees the change, and the failure still reaches the
+  caller.
+- **A cold subscribe reads once per query id.** Subscribers arriving during a read join it and each
+  runs its own policy pass over the result. A read that resolves behind a change already fanned out
+  is discarded rather than written back: the window only ever moves forwards.
+- **A denial drops a row; a gate that could not decide does not.** A policy answer (`X_FORBIDDEN`,
+  `X_UNAUTHENTICATED`) is a decision and costs the row, counted as `rowsDenied`. Anything else a
+  gate throws — a rule whose lookup timed out, a predicate with a typo — is counted as
+  `gateFailures` and reported through `onGateFailed`, never as a denial: it raises out of
+  `subscribe`, desyncs exactly the one subscriber it happened to during a delivery, and leaves a
+  subscription standing at `reauthorize`. Reading a timeout as "you may no longer see this" is an
+  outage published as a permission change.
+- **A patch is authorized against the whole row or it is not authorized.** An update patch carries
+  the changed columns only, so a rule reading a column the change did not touch would read
+  `undefined` and answer as if the row had said so. A patch whose row the shared window does not
+  hold is withheld — the window *is* the result set — and a subscriber holding that row gets the
+  one `delete` that says so. It counts as neither a denial nor a gate failure: nothing decided.
 - **`PgLogicalReplicationFeed` 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 and the slot, creates the slot when there is none, and confirms the slot as it goes so
@@ -149,14 +422,19 @@ because refusing without one just moves the herd next door.
   `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.
-- **`NatsTransport` speaks NATS itself** — its own protocol codec and session over `Bun.connect`,
-  no client dependency. Fanout is core NATS; `shared` is a JetStream KV bucket the transport
-  creates on first connect, one key per presence member, expired by the **server's** per-message
-  TTL so a node that dies needs nobody to notice. Subscriptions are held as *intent*, so a lost
-  connection re-dials and re-subscribes underneath the caller — which is what makes `sync`
-  stateless. That 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.
+- **`NatsTransport` runs on the official `nats` client** — `nats@2.29.3`, pinned exact, admitted at
+  this transport seam and nowhere else
+  ([`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md)). The package reaches it
+  through one port, `NatsClient`, and exactly one file imports the library to implement it, so a
+  test injects a client rather than a socket. Fanout is core NATS. `shared` is a JetStream KV bucket the transport creates on
+  first connect, one key per presence member, expired by the **server's** per-message TTL so a node
+  that dies needs nobody to notice — that bucket and its direct reads stay the framework's, because
+  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
+  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
   half works alone: every row of one transaction shares a commit lsn, and logical decoding emits
   *transactions* in commit order, so per-record WAL positions are not monotonic across them. The
@@ -165,16 +443,39 @@ because refusing without one just moves the herd next door.
 - **A live query needs `REPLICA IDENTITY FULL`.** Deciding whether a row *left* a result set needs
   the old values; with the default identity a delete replicates only the key columns.
 - Tier 3's OPFS SQLite store is browser-only and throws until the browser entry ships; `MemoryLocalStore`
-  implements the full journal/rollback/replay semantics today.
+  implements the full journal/rollback/replay semantics today. 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.
 
 ## Errors
 
-`X_TOPIC_FORBIDDEN` · `X_SUBSCRIPTION_LIMIT` · `X_PROTOCOL_VERSION` · `X_CURSOR_STALE` ·
+`X_TOPIC_FORBIDDEN` · `X_SUBSCRIPTION_LIMIT` · `X_SUBSCRIPTION_ID_TAKEN` ·
+`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_NOT_IMPLEMENTED`
+`X_LIVE_CLIENT_MISSING` · `X_LIVE_QUERY_UNKNOWN` · `X_SOCKET_UNAUTHENTICATED` ·
+`X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED`
 
 Topics deny by default: a topic with no matching guard is forbidden. 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
+first is the client's credential and pages nobody, the second is this node's dependency and pages
+someone. Both are rendered as the error contract in the response body — there is no frame to carry
+one, because the client never got a socket.
+
+A `sid` belongs to the socket that chose it. A subscription is keyed by `(socket, sid)`, a drop
+frame is scoped to the socket that sent it, and reusing a sid the same socket already holds is
+`X_SUBSCRIPTION_ID_TAKEN` — one client can neither take over nor end another's live stream.
+
+A `subscribe` frame naming a query this node never registered is `X_LIVE_QUERY_UNKNOWN`, not
+`X_PROTOCOL_VERSION`: the frame parsed and the version matched, so "rebuild and redeploy the
+client" is the one instruction that cannot help — a rebuilt client spells the name the same way.
+The fix is `x queries list --json`, and the name the client sent is echoed back while the registry
+never is.
+
 `As of 2026-07`: tiers 1–2 target v1, tier 3 targets v2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,8 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,7 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/query": "1.2.0"
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/query": "2.0.0",
+    "nats": "2.29.3"
   }
 }

package/src/apply-patches.ts

@@ -0,0 +1,60 @@
+// One job: fold a patch list onto a result set. Pure and outside `LiveClient` because it is the only
+// piece of the client with no socket, no signal and no state — which is what makes it the piece an
+// 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.
+
+import type { JsonObject, Row, RowPatch } from './json';
+
+/**
+ * Membership and order after a patch list, ids only. `index` places a row the set does not hold
+ * yet; a row it already holds keeps its position, because a patch reorders nothing it did not say
+ * to reorder.
+ */
+export function orderAfterPatches(
+  ids: readonly string[],
+  patches: readonly RowPatch[],
+): readonly string[] {
+  let next = ids;
+  for (const patch of patches) {
+    if (patch.op === 'delete') {
+      next = next.filter((id) => id !== patch.id);
+      continue;
+    }
+    if (patch.row === null) continue;
+    if (next.includes(patch.id)) continue;
+    if (patch.index !== undefined) {
+      const copy = [...next];
+      copy.splice(patch.index, 0, patch.id);
+      next = copy;
+      continue;
+    }
+    next = [...next, patch.id];
+  }
+  return next;
+}
+
+/** Minimal in-place patch application: the shape a Solid store update maps onto directly. */
+export function applyPatches(rows: readonly Row[], patches: readonly RowPatch[]): readonly Row[] {
+  const values = new Map<string, Row>(rows.map((row) => [row.id, row]));
+  for (const patch of patches) {
+    if (patch.op === 'delete' || patch.row === null) continue;
+    values.set(patch.id, mergeRow(values.get(patch.id), patch.id, patch.row));
+  }
+  const out: Row[] = [];
+  for (const id of orderAfterPatches(
+    rows.map((row) => row.id),
+    patches,
+  )) {
+    const row = values.get(id);
+    if (row !== undefined) out.push(row);
+  }
+  return out;
+}
+
+/** The one merge rule: changed columns over the current value, and `id` is never overwritten. */
+function mergeRow(current: Row | undefined, id: string, columns: JsonObject): Row {
+  const next: JsonObject = { ...(current ?? {}), ...columns };
+  return { ...next, id };
+}

package/src/change-buffer.ts

@@ -1,50 +1,109 @@
-// The bounded per-query change window that makes reconnect a delta instead of a refetch.
-// Lives on the `replicator` (one per DB), so a reconnecting client costs zero DB work while its
-// gap is inside the window. Outside it, `resumeFrom` takes one snapshot — never WAL traversal.
+// The bounded per-query change window that makes reconnect a delta instead of a refetch. Inside
+// the window a reconnecting client costs zero DB work; outside it, `resumeFrom` takes one bounded
+// snapshot — never WAL traversal.
+//
+// **It is per `sync` node, and a `qid` window can only be.** The header used to say it lives on the
+// replicator; it does not, and it could not — a patch is query-scoped, so producing one needs that
+// query's compiled shape, its matcher and its current window, none of which the replicator has (it
+// is entity-scoped by construction). The consequence is real and is not fixed here: a client that
+// reconnects onto a node that never served its `qid` finds no ring, `shouldResnapshot` answers
+// `out-of-window`, and it takes the snapshot path. What that costs is one *shared* read per
+// (query, node) — `fillWindow` joins every subscriber arriving during a read into it — and not one
+// read per client. Making the delta path work across nodes means an **entity**-keyed window every
+// node fills from the change stream it already subscribes to, which is a `ResumeSource` shape
+// change, not a placement change.
 
 import type { ResumeSource } from './cursor';
 import type { RowPatch } from './json';
 
 export interface ChangeBufferOptions {
-  /** Retained patches per query hash. */
+  /** Retained patches per query hash — a REPLAY bound: what a delta resume may cost to fold. */
   readonly capacity?: number;
   /** Retained query hashes; the least-recently-written is dropped first. */
   readonly maxQueries?: number;
+  /** Retained bytes per query hash. The memory bound, and the one that actually holds. */
+  readonly maxBytesPerQuery?: number;
+  /** Retained bytes across every query on this node. */
+  readonly maxBytes?: number;
 }
 
+/**
+ * The node's retained-patch memory ceiling. `packages/cache/src/lru.ts:1-2` states the rule this
+ * exists to obey: bounded by BYTES, never by entry count — 4,096 queries x 1,024 patches is 4.19M
+ * retained `RowPatch` objects, each holding a whole row, and nothing in that product is memory.
+ */
+export const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_MAX_BUFFER_BYTES_PER_QUERY = 1024 * 1024;
+
 interface Ring {
   patches: RowPatch[];
+  bytes: number;
   /** Highest lsn already dropped. A cursor at or after this is still resumable. */
   evictedThrough: string | null;
 }
 
+const encoder = new TextEncoder();
+
+/** What one retained patch costs. Its serialised size: the row is the whole of it. */
+function patchBytes(patch: RowPatch): number {
+  return encoder.encode(JSON.stringify(patch)).length;
+}
+
 export class RingChangeBuffer implements ResumeSource {
   readonly #rings = new Map<string, Ring>();
   readonly #capacity: number;
   readonly #maxQueries: number;
+  readonly #maxBytesPerQuery: number;
+  readonly #maxBytes: number;
+  #bytes = 0;
 
   constructor(options: ChangeBufferOptions = {}) {
     this.#capacity = options.capacity ?? 1024;
     this.#maxQueries = options.maxQueries ?? 4096;
+    this.#maxBytesPerQuery = options.maxBytesPerQuery ?? DEFAULT_MAX_BUFFER_BYTES_PER_QUERY;
+    this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+  }
+
+  /** Retained bytes across every query on this node. The number the ceiling is about. */
+  get bytes(): number {
+    return this.#bytes;
   }
 
   append(qid: string, patch: RowPatch): void {
     const existing = this.#rings.get(qid);
-    const ring: Ring = existing ?? { patches: [], evictedThrough: null };
+    const ring: Ring = existing ?? { patches: [], bytes: 0, evictedThrough: null };
     ring.patches.push(patch);
-    while (ring.patches.length > this.#capacity) {
-      const dropped = ring.patches.shift();
-      if (dropped) ring.evictedThrough = dropped.lsn;
+    const cost = patchBytes(patch);
+    ring.bytes += cost;
+    this.#bytes += cost;
+    // Two ceilings, because they bound two different things: the count bounds what a resume has
+    // to fold, the bytes bound what this process holds. Whichever bites first, bites.
+    while (ring.patches.length > this.#capacity || ring.bytes > this.#maxBytesPerQuery) {
+      if (!this.#shift(ring)) break;
     }
     // Re-insert to move this qid to the tail of the LRU order.
     if (existing) this.#rings.delete(qid);
     this.#rings.set(qid, ring);
-    if (this.#rings.size > this.#maxQueries) {
+    while (this.#rings.size > this.#maxQueries || this.#bytes > this.#maxBytes) {
       const oldest = this.#rings.keys().next();
-      if (!oldest.done) this.#rings.delete(oldest.value);
+      // The only ring left is the one just written: evicting it would make a node under memory
+      // pressure retain nothing at all, and every reconnect a snapshot.
+      if (oldest.done || this.#rings.size === 1) break;
+      this.forget(oldest.value);
     }
   }
 
+  /** Drop the oldest patch of a ring, keeping both byte counters honest. Answers what it did. */
+  #shift(ring: Ring): boolean {
+    const dropped = ring.patches.shift();
+    if (!dropped) return false;
+    const cost = patchBytes(dropped);
+    ring.bytes -= cost;
+    this.#bytes -= cost;
+    ring.evictedThrough = dropped.lsn;
+    return true;
+  }
+
   since(qid: string, lsn: string): RowPatch[] | null {
     const ring = this.#rings.get(qid);
     if (!ring) return null;
@@ -58,8 +117,15 @@ export class RingChangeBuffer implements ResumeSource {
     return last ? last.lsn : null;
   }
 
-  /** Called when the last subscriber of a query goes away, so an idle query stops costing memory. */
+  /**
+   * Called when the last subscriber of a query goes away, so an idle query stops costing memory.
+   * It had no caller until `LiveQueryRegistry.unsubscribe` gained one: the entry was dropped and
+   * the ring behind it kept every patch it held until the LRU happened to reach it.
+   */
   forget(qid: string): void {
+    const ring = this.#rings.get(qid);
+    if (!ring) return;
+    this.#bytes -= ring.bytes;
     this.#rings.delete(qid);
   }