@ultimat3/realtime 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -79,6 +79,21 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   prevent. A lane that fails now desyncs its own subscribers and the first failure still reaches
   the caller, but it costs one query id. The lane chains on a settled shadow of each task: one
   fanout that threw must not reject every fanout behind it.
+- **Two reads of one entry are ordered by a READ GENERATION, never by an lsn.** `QueryEntry.lsn`
+  is optional — a definition with no lsn provider answers `''` from every snapshot — so the
+  never-backwards rule expressed purely in lsn terms read `'' >= ''` as "newer" and let the older
+  of two concurrent reads land on top of the newer one's window. The interleaving: a cold
+  subscriber issues P1; the change stream skips a sequence and `registry.invalidate()` marks the
+  entry; a second cold subscriber forces P2, which **clears `stale` on the way in**; P2 lands with
+  the post-gap rows; P1 lands last and overwrites them. `stale` is false, so `fanoutChange`'s
+  repair never fires, the next change patches the pre-gap window and re-snapshots every desynced
+  subscriber out of it — permanently stale on a healthy socket, which is the exact outcome `stale`
+  exists to prevent. `entry.generation` is bumped in `startRead` and `entry.applied` records the
+  newest read whose rows are on the window: an *identity* check, the same one `startRead` makes on
+  `entry.reading` one function down and `packages/cache/src/single-flight.ts:70` makes for the same
+  reason. The lsn guard stays beside it for the other question — a read that resolved behind a
+  *change* the fanout already folded — because those are two orderings and neither answers the
+  other.
 - **The definition's read is once per entry, not once per subscriber.** A cold subscriber arriving
   while another's read is in flight joins that read — N cold subscribers on one query id being N
   reads is the shared window not existing. It is a share, not a cache: the in-flight promise is
@@ -141,6 +156,34 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   could reach a different one than the container it is standing in for. The KV bucket and the
   presence TTL come back with the transport for the same reason: they are one decision.
 - `sync` is stateless: no sticky sessions, nothing on a socket survives a restart.
+- **A socket the node evicts ITSELF is released through `teardown`, never through
+  `sockets.remove`.** Bun's `close` callback runs `teardown`; a drain and the idle sweep have no
+  callback behind them — Bun's fires a tick later and `sockets.get` misses by then — so whatever
+  they do instead *is* the whole release. `drain()` inlined three of `teardown`'s five steps
+  (`close`, `sockets.remove`, `grants.delete`) and skipped the two the rest of the fleet can see:
+  `registry.unsubscribeSocket` and `presence.leave` per topic. What that left is a `QueryEntry`
+  whose `subscribers` map never empties — matcher, shared window and `WindowLock` pinned, and
+  `source.forget(qid)` never called — and, worse because it is cross-node, a presence member every
+  other node renders for a full TTL. During a **rolling restart** that is every room showing each
+  user twice for up to 30s, beside the same client's reconnection under a new socket id. One
+  `evict(socket, code, reason)`, and every path that ends a socket without a callback takes it.
+- **The idle sweep exists, is armed by `start()`, and its budget is an APPLICATION one.**
+  `SocketRegistry.sweepIdle` had no caller for as long as it existed, so `touch()`, `idleFor` and
+  the 120s default decided nothing and `idleTimeoutMs` was unreachable from `createSyncNode`. The
+  only live guard was `websocket.idleTimeout: 120` handed to Bun — which Bun's own ping/pong
+  renews, so a client whose frame loop is wedged answers pings and keeps its `GrantBook` entry,
+  its `SubscriptionBook` entries and its `#byTopic` membership forever. It is now
+  `SocketRegistry.idle()`, a **query**: this table is three of the five things a socket holds, so
+  the object that can evict one is the node and not the registry. `start()` arms one `.unref()`ed
+  pass every `idleSweepPeriodMs(idleTimeoutMs)` — a quarter of the budget, floored at a second,
+  derived rather than configured because a second knob is a second number that can disagree with
+  the one it is a fraction of — and `release()` clears it beside the presence sweep. **It measures
+  on `Clock.monotonic()`**, the clock `AcceptBudget` already uses: the sweep compares a DURATION,
+  and a duration read off `now().getTime()` is decided by whatever NTP last wrote — a step forward
+  evicts every socket that is talking, a step backward makes `idleFor` negative and spares every
+  socket that is dead, and the sweep had only just gained its first caller when both became
+  reachable. The field is named `lastSeenMonotonicMs` so nobody hands it to `new Date()`;
+  `openedAt` is the wall-clock one and stays that way, because a human reads it.
 - **`drain()` and `stop()` both release what `start()` acquired, and releasing twice is a no-op.**
   A `drain()` is terminal on its own — it closes the hub and evicts every socket — and nothing
   obliges a `stop()` to follow it, so leaving the change subscription and the presence sweep to
@@ -171,6 +214,22 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   threw skipped the close and the pump await, leaking the socket and telling a supervisor the
   teardown was over before it had begun. Every step runs whatever the step before it did, and the
   first failure is rethrown only once the connection is closed and the pump has ended.
+- **`REPLICA IDENTITY FULL` is asked about at preflight, warned about, and counted — never thrown**
+  (added 2026-08-19). `pg-replication.ts`'s `#deliver` hands a `delete` its `message.before`,
+  and under any identity but FULL that tuple is the KEY COLUMNS ALONE — which `toRow` accepts,
+  because it only requires a text `id`. So `bridgeChange` decided "did this row leave the result
+  set" from a one-column row, `visible` read `undefined` for every column the identity did not
+  carry, and nothing anywhere recorded that it had happened: no emit, no check, and
+  `X_LIVE_REPLICA_IDENTITY` existed in neither the source nor the manifest. The check is a fourth
+  `connection.query` in `preflight`, and it **must** stay ahead of
+  `pg_create_logical_replication_slot` — changing the identity after a slot exists does not reach
+  what that slot decodes. It WARNS (`logger.warn(code, { cause, fix, tables })`, the message being
+  the code alone) because a throw would stop every app on the default identity from booting, which
+  is a worse outcome than the partial rows. `ReplicationStreamStats.partialBefore` is the runtime
+  half, read off `PgRelation.replicaIdentity` and never off the tuple: a DEFAULT-identity table
+  whose non-key columns happen to be NULL sends the bytes a FULL one does, so counting absent keys
+  would undercount exactly the rows a policy is most likely to misjudge. A hard refusal in the
+  `x verify` step is the follow-up and lives in `@ultimat3/cli`.
 - A change lsn is `<16 hex commit position><8 hex row position in that transaction>`. Never order by
   either half alone: the commit lsn repeats within a transaction, and per-record WAL positions are
   not monotonic across transactions. Never make it depend on wall time, the entity list or a process
@@ -268,6 +327,33 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   double presence membership, double fanout — until the tab closed. `#socket` is nulled before the
   close so the corpse's `onClose` takes its early return, and `onMessage` carries the same identity
   guard `onClose` already had.
+- **The grant is recorded BEFORE `server.upgrade`, and released on the path that never opens.**
+  Bun runs `websocket.open` SYNCHRONOUSLY inside `server.upgrade` and does not return until it has
+  (bun 1.3.14), and `open` is where `sync-node` reads the `GrantBook` for the socket's actor.
+  Recorded on the line after the upgrade — which it was — every authenticated socket on a real node
+  carried `actor: null`: `ChannelHub.#authorize` denied every topic with `X_TOPIC_FORBIDDEN`,
+  `authorize`/`visible` decided about nobody, `maxPerTenant` never applied and `hello.actorId` was
+  null. It did not self-repair, because `GrantBook.expired()` skips a grant with no `expiresAt` —
+  the shape `authenticate: async () => ({ actor })` produces. `onUngranted` is what makes the
+  correct order safe (only a `close` callback deletes a grant, and an upgrade that never took gets
+  no callback); it is REQUIRED on `UpgradeDeps`, so a second host of `handleUpgrade` cannot forget
+  it. The harness is half the rule: `sync-node-auth.test.ts`'s `upgradeTarget()` returned `true`
+  without ever calling `open`, so the bug was invisible to every test here — it now opens the socket
+  inside `upgrade()`, the way Bun does.
+- **Every `socket.send` on the node reads its answer, and what a `false` costs is decided per
+  frame.** A subscribe reply is REPAIRABLE and was the silent one: `registry.subscribe` has already
+  seated the subscription and cleared its desync mark, so a dropped snapshot left the server
+  believing a client holding no rows was in sync, and every later change reached it as a patch
+  folded onto nothing — on a healthy socket, forever. It is marked desynced, exactly as
+  `live-fanout` marks a lost patch. A `rebase`/`ack` has nothing to mark (the node keeps no
+  per-mutation state) and a client only returns an `inflight` mutation to its queue when the
+  connection dies, so an undeliverable settlement **closes the socket**: the reconnect requeues and
+  replays it under the same idempotency key, and acking a rebase that never left is the
+  rebase-before-ack order defeated one frame later. A presence roster has no repair at all — the
+  membership is already on the shared set and the client's next heartbeat re-rosters — so it is
+  logged (`sync.presence_roster_dropped`). The drain's `reconnect` frame is the socket's slot in the
+  spread and nothing re-sends it, so `drain()` returns `DrainedSocket[]` with `notified` per socket
+  and logs `sync.drain_frames_dropped`.
 - **A socket's actor comes from `createSyncNode({ authenticate })` and from nowhere else.** The node
   imports no authenticator — the app supplies one, exactly as it supplies `onMutate` — and it runs
   on the upgrade *before* `server.upgrade`, so a refused credential never costs a websocket.
@@ -321,6 +407,13 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `Bridge` comment describes, one state earlier. So `close()` sets `#closed` **before** the walk and
   `#open` closes its own subscription when it lands after one, dropping the entry with it so a
   second post-close subscribe opens and closes its own rather than double-unsubscribing this handle.
+  It then **raises** `X_TRANSPORT_UNAVAILABLE` rather than returning: returning let `subscribe` fall
+  through to `joinTopic`, so the socket became a member of a topic nothing on this node is bridged
+  to — silent for the life of the connection, no error on either side, and no reason for the client
+  to redial. Reachable between `hub.close()` inside `node.drain()` and the last in-flight subscribe.
+  `#release` takes the bridge the caller reserved for the same reason: after `close()` cleared the
+  table, that topic name may hold a bridge a LATER subscribe opened, and releasing by name alone
+  decrements somebody else's refcount.
 - Deny by default on topics. No guard = `X_TOPIC_FORBIDDEN`.
 - **A guard that FAILS is not a guard that denied — the hub's copy of the rule the row gate already
   follows.** On `onActorChange` (the re-auth pass) only a denial unsubscribes; anything else keeps
@@ -368,20 +461,33 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   channel's lsn is the publishing hub's own per-node counter, so a client cannot tell a gap from a
   message that came via another node. Declared in `socket.ts`, not core's `runtime-metrics.ts`:
   that file is the series every process emits, this one exists only where channels do.
-- **`qidOf` is `stableDigest` (SHA-256, 16 hex) and never `fnv1a`.** The qid is a *sharing* key —
-  a hit hands back the existing entry and the seated window, carrying the first subscriber's input
-  and rows — and input is client-chosen, so 32 bits is a collision found offline in seconds and one
-  client served out of another's window. `fnv1a` stays the cursor's result-set digest, where a
-  collision costs a missed re-sort.
-- **`canonicalJson` is injective over the values it accepts, and `JSON.stringify` is not.**
-  `JSON.stringify` answers `"null"` for `NaN` and `±Infinity` and `"0"` for `-0`, so four distinct
-  inputs hashed to one qid — and a qid *hit* hands the joiner the first subscriber's compiled
-  source, matcher and seated window. Bare `NaN` / `Infinity` / `-Infinity` / `-0` tokens are emitted
-  instead; they are not valid JSON, which is correct, because this output is hashed and never
-  parsed. Exposure is narrower than it looks and the tests say so rather than overclaiming: `NaN`
-  and `±Infinity` have no JSON spelling and so cannot arrive on a `subscribe` frame — they reach
-  `qidOf` only from a caller building `input` in JS. **`-0` is wire-reachable**: `JSON.parse('{"a":-0}')`
-  answers `-0`.
+- **A qid is `@ultimat3/query`'s `queryHash(name, input)`, and this package derives none of its
+  own — `As of 2026-08`.** `qidOf` was the same two lines over a local copy of the canonical form
+  (`stableDigest(canonicalJson(input))`), and `canonicalJson`/`stableDigest` were this package's
+  third copy of what `@ultimat3/action` and `@ultimat3/query` also each held. They had already
+  diverged: `{ a: undefined, b: 1 }` gave `feed:eb8ed3ccb5023093` from `queryHash` and
+  `feed:c0bf82ad036cb0a5` from `qidOf`, because query's walk drops an `undefined`-valued key and
+  this one rendered `"a":null`. The two are COMPARED in one flow — `@ultimat3/query`'s `planResume`
+  decides refetch-vs-resume by comparing a cursor's `queryHash` against the query's, while
+  `liveQueryDefinition` keys the shared window by the qid — so keeping both correct was never the
+  option; the first time either moved, every resume decision and every window lookup were keyed
+  differently. `realtime -> query` is the one declared sideways edge and this package already
+  imports it. **`fnv1a` stays here**, and only it: its job is the cursor's result-set digest, where
+  a collision costs a missed re-sort and never one client served out of another's window.
+  `live-contract.test.ts` is the pin — it reads `registry.subscriberCount(queryHash(name, input))`
+  through a real subscribe, so a local derivation fails it. Cost of the move: none observable on the
+  server. Every qid a node computes comes from a DECODED frame, and `JSON.parse` produces no
+  `undefined`, no `Date`, no `Map` and no `Set` — the four values the two forms disagree about — so
+  no live subscription re-keyed and nothing re-snapshotted.
+- **The canonical form is injective over the values it accepts, and `JSON.stringify` is not** —
+  the reason that survives the move, now `@ultimat3/core`'s to enforce. `JSON.stringify` answers
+  `"null"` for `NaN` and `±Infinity` and `"0"` for `-0`, so four distinct inputs hashed to one qid
+  — and a qid *hit* hands the joiner the first subscriber's compiled source, matcher and seated
+  window. Bare `NaN` / `Infinity` / `-Infinity` / `-0` tokens are emitted instead; they are not
+  valid JSON, which is correct, because that output is hashed and never parsed. Exposure is
+  narrower than it looks and the tests say so rather than overclaiming: `NaN` and `±Infinity` have
+  no JSON spelling and so cannot arrive on a `subscribe` frame — they reach the hash only from a
+  caller building `input` in JS. **`-0` is wire-reachable**: `JSON.parse('{"a":-0}')` answers `-0`.
 - **Refusing new sockets and draining the ones you have are two shutdown phases.** `stopAccepting()`
   is the `accept` phase: `ready = false`, `/readyz` 503, a late upgrade shed with `retry-after-ms`,
   and every socket untouched — a draining node still owes its clients their patches, and `stop()` is
@@ -422,7 +528,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   every client on open and read by nobody — the node replied `resume: []` and decided resume per
   subscription from the `subscribe` frame — so every reconnect shipped each cursor twice, up to 512
   ids each, in the restart storm this package is measured on. Wiring it was the wrong half of the
-  choice: a cursor's `qid` is `` `${name}:${stableDigest(input)}` ``, so a node reading a resume list
+  choice: a cursor's `qid` is `` `${name}:${fingerprint(input)}` ``, so a node reading a resume list
   recovers the query **name** — it is the plaintext prefix — but never the `input`, which is the half
   every decision needs. Without it `definition.authorize({ actor, input })` cannot run and no entry
   can be built; the qid names a window but not a decision, and the retained window holds pre-policy
@@ -442,9 +548,11 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   socket it opens against the *new* node. Two silent windows and the client closes with `4000` and
   arms the reconnect. It is one
   self-re-arming tick on the injected `Scheduler`, not an interval: a client is either beating on a
-  live socket or backing off toward a new one, never both. The 15s is restated from
-  `realtime.heartbeatMs` rather than read — that is server config and this is browser code — and
-  `realtime.heartbeatMs` is read by nothing today.
+  live socket or backing off toward a new one, never both. The 15s is the client's OWN number:
+  `realtime.heartbeatMs` was a `RealtimeConfig` key read by nothing and it is **deleted**
+  (2026-08-19). The server half of the beat stays derived — `PresenceRegistry.heartbeatMs` is
+  `max(1000, floor(ttlMs / 3))`, the same rule `idleSweepPeriodMs` follows, because a second knob
+  is a second number that can disagree with the one it is a fraction of.
 - **Every question a hot path asks is indexed, never scanned.** `SubscriptionBook` keeps
   `#bySocket` and a per-tenant count beside `#bySid`, and `SocketRegistry` keeps `#byTopic` beside
   the socket table. Both replaced a walk of the whole node that ran once per socket or once per
@@ -537,6 +645,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | `live-query.ts` / `live-definition.ts` / `changefeed.ts` / `changefeed-env.ts` / `replicator.ts` / `pg-advisory-lock.ts` / `fanout.ts` / `transport-env.ts` / `matcher-bridge.ts` | tier 2 |
 | `pg-bytes.ts` / `pg-wire.ts` / `pg-auth.ts` / `pg-connection.ts` / `pg-socket.ts` | the Postgres v3 client: bytes, frames, SASL, session, socket |
 | `pgoutput.ts` / `pg-entity-row.ts` / `pg-replication.ts` | WAL decode → `ChangeEvent`, and the lsn that orders it |
+| `pg-preflight.ts` | the four questions asked before `START_REPLICATION` — `wal_level`, the publication, every entity's replica identity, the slot — plus `assertIdentifier`, the charset all four interpolate through |
 | `nats-client.ts` | the bus port: publish/subscribe/request/requestMany/close/version/connected, and `parseNatsUrl` — the library takes `host:port` plus credentials and never reads a URL's userinfo |
 | `nats-lib-client.ts` | the `nats` adapter — **the only file in the repo that imports `nats`** |
 | `nats-jetstream.ts` / `nats-kv.ts` / `nats-transport.ts` | the JetStream KV bucket, presence over it, and the production `Transport` — all three written against the port |
@@ -568,8 +677,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | `client-contract.ts` | the client's injected shapes — `ClientSocket`, `LiveClientOptions`, `LiveHandle` — declared apart from the class that consumes them |
 | `policy-gate.ts` | the only authz seam |
 | `subscriber-gate.ts` | the per-subscriber pass of a definition's row policy, and its two counters — `rowsDenied` and `gateFailures`. Evaluates no policy of its own |
-| `live-contract.ts` | what a live query IS: `qidOf`, `LiveQueryDefinition`, `SnapshotResult`, `LiveSubscription`. Four modules need the shape and none of them needs the registry that runs it |
-| `json.ts` | the wire's value types, `canonicalJson`, and the two hashes — `stableDigest` (sharing keys) and `fnv1a` (drift). Tested in `json.test.ts`, beside the declarations: a `qidOf` test proves the qid, not the primitive under it |
+| `live-contract.ts` | what a live query IS: `LiveQueryDefinition`, `SnapshotResult`, `LiveSubscription`. Four modules need the shape and none of them needs the registry that runs it. The **id** is not here and not anywhere in this package — it is `@ultimat3/query`'s `queryHash` |
+| `json.ts` | the wire's value types and `fnv1a` (drift), the one hash still owned here. The canonical form and the sharing-key hash are `@ultimat3/core`'s (`canonicalJson`, `fingerprint`) — `json.test.ts` pins that `fnv1a` is never mistakable for one |
 | `live-definition.ts` | the only bridge from a declared `query({ live: true })` to a registrable definition — and `policy-gate.ts`'s only caller |
 | `matcher-bridge.ts` | the only `@ultimat3/query` matcher seam |
 

package/README.md

@@ -168,6 +168,7 @@ wire.
 | 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` |
 | 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` |
 
@@ -264,15 +265,17 @@ new LiveClient({ signal, connect, buildId, heartbeatMs: 15_000 }); // 0 disables
 
 | 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 |
+| 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 |
 | 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.
+`realtime.heartbeatMs` in `app.config.ts` is **gone** `As of 2026-08-19` — it was read by nothing,
+and an app that still sets it fails `x verify`'s typecheck step with TS2353 (`'heartbeatMs' does not
+exist in type 'Input<RealtimeConfig>'`). Delete the line; this option is the only knob that changes
+behaviour, and the node's presence beat is derived from its TTL rather than configured.
 
 ### A `send` that returned is not an acknowledgement
 
@@ -350,18 +353,36 @@ wire twice by a reconnect that raced an ack.
   `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.
+- **`qid` is `@ultimat3/query`'s `queryHash(name, input)`** — `<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. This package derives none of its own — `qidOf` was a second spelling of
+  `queryHash` while `@ultimat3/query`'s `planResume` compares a cursor's `queryHash` against the
+  query's, so the two had to be one function or every resume decision and every window lookup would
+  be keyed differently the first time either moved. A rolling deploy across the *hash* 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; 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
   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.
+- **An idle socket is swept, and the sweep is an APPLICATION budget, not Bun's.** Bun's own
+  `idleTimeout` is renewed by its ping/pong, so a client whose frame loop is wedged answers pings
+  and keeps its grant, its live subscriptions and its topic membership indefinitely. `start()`
+  arms one `.unref()`ed pass every `idleTimeoutMs / 4` (floored at a second, derived rather than
+  configured) and evicts anything past the budget the same way a close does — through the node's
+  `teardown`, never `SocketRegistry.remove`. `SocketRegistry.idle()` is a *query* for that reason:
+  the socket table is three of the five things a socket holds, and the other two are its live
+  subscriptions and its presence membership on the shared set. `sweepIdle` — which closed and
+  removed here, and had no caller at all — is gone. The budget is measured on `Clock.monotonic()`,
+  so `SyncSocket.lastSeenMonotonicMs` is a duration's start and not an instant: an NTP step forward
+  would otherwise evict every socket that is talking, and a step backward would spare every socket
+  that is dead. `openedAt` stays on the wall clock — it is a value a human reads.
 - **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
@@ -381,7 +402,10 @@ wire twice by a reconnect that raced an ack.
   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.
+  is discarded rather than written back: the window only ever moves forwards. Two reads are ordered
+  by a monotonic **read generation** and never by lsn — a definition with no lsn provider answers
+  `''` for every read, and `'' >= ''` let the older of two concurrent reads land on top of the
+  newer one's gap repair, with `stale` already cleared and therefore nothing left to re-read.
 - **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
@@ -394,10 +418,16 @@ wire twice by a reconnect that raced an ack.
   `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.
+- **A `delete` is withheld too, and `holds` is the whole decision** (`As of 2026-08`). It carries no
+  row, so there is nothing to put in front of the rule — and it was forwarded unconditionally, so
+  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
   (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
-  the WAL does not grow without bound. `InMemoryChangeFeed` + `InProcessTransport` remain 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
+  slot as it goes so the WAL does not grow without bound. `InMemoryChangeFeed` + `InProcessTransport` remain the
   defaults for `x dev` and every test.
 - **`selectChangeFeed(env, { entities })` decides which feed a boot installs** — same law
   `selectMailDriver` follows: an unset variable means the embedded default. It returns `{ feed,
@@ -440,8 +470,18 @@ 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 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.
+- **A live query needs `REPLICA IDENTITY FULL`, and the replicator now says so** (`As of
+  2026-08-19`). Deciding whether a row *left* a result set needs the old values; with the default
+  identity a delete replicates only the key columns, and `toRow` accepts that tuple because it only
+  requires a text `id`. `preflight` asks `pg_class.relreplident` for every entity in the list — the
+  fourth question it asks, and **before** `pg_create_logical_replication_slot`, since changing the
+  identity after a slot exists does not reach the rows that slot will decode. It is a **coded
+  warning**, `X_LIVE_REPLICA_IDENTITY`, whose `fix:` is the `ALTER TABLE <t> REPLICA IDENTITY FULL;`
+  per named table — not a throw, because every app on the default identity would otherwise stop
+  booting, which is worse than the partial rows. `ReplicationStreamStats.partialBefore` is the
+  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 and throws until the browser entry ships; `MemoryLocalStore`
   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
@@ -456,8 +496,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_QUERY_UNKNOWN` · `X_SOCKET_UNAUTHENTICATED` ·
-`X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED`
+`X_LIVE_CLIENT_MISSING` · `X_LIVE_QUERY_UNKNOWN` · `X_LIVE_REPLICA_IDENTITY` ·
+`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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -32,8 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/query": "2.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/query": "4.0.0",
     "nats": "2.29.3"
   }
 }

package/src/changefeed.ts

@@ -126,14 +126,26 @@ export class InMemoryChangeFeed implements ChangeFeed {
   async #deliver(event: ChangeEvent): Promise<void> {
     const handler = this.#handler;
     if (!handler) return;
-    this.#tail = this.#tail.then(async () => {
+    const result = this.#tail.then(async () => {
       await handler(event);
       this.#lastLsn = event.lsn;
     });
-    await this.#tail;
+    // The lane chains on a SETTLED shadow, never on `result` — `window-lock.ts` solves the same
+    // problem the same way. Chained on the live tail, one rejected link poisoned every link behind
+    // it: later changes rejected with the FIRST error, the handler was never called again and
+    // `lastLsn()` froze. Reachable on any single-node deployment, because `createReplicator`'s
+    // `onChange` awaits `transport.publish(...)` and a closed `InProcessTransport` refuses — one
+    // transient publish failure ended change delivery for the life of the process. The rejection
+    // still reaches the caller that pushed THAT event, and only it; `stop()` awaits the shadow, so
+    // a teardown reports the teardown rather than re-raising a failure already handed over.
+    this.#tail = result.then(ignore, ignore);
+    await result;
   }
 }
 
+/** Settles the shadow lane whichever way the delivery went. Nothing observes the value. */
+const ignore = (): void => undefined;
+
 export interface PgLogicalReplicationOptions {
   /** Connection string for a role with REPLICATION: `postgres://user:pass@host:5432/db`. */
   readonly url: string;

package/src/channel.ts

@@ -6,7 +6,12 @@
 
 import { type Actor, logger, renderThrowable } from '@ultimat3/core';
 import { formatLsn } from './changefeed';
-import { isPolicyDenial, SubscriptionLimitError, TopicForbiddenError } from './errors';
+import {
+  isPolicyDenial,
+  SubscriptionLimitError,
+  TopicForbiddenError,
+  TransportUnavailableError,
+} from './errors';
 import { subjectMatches, type Transport, type TransportSubscription } from './fanout';
 import type { JsonObject } from './json';
 import type { SocketRegistry, SyncSocket } from './socket';
@@ -152,8 +157,11 @@ export class ChannelHub {
       await this.#authorize(socket.actor, name);
       await this.#open(name, bridge);
     } catch (error) {
-      // The slot this subscribe took, given back on the one path that will never fill it.
-      this.#release(name);
+      // The slot this subscribe took, given back on the one path that will never fill it — and
+      // given back to the bridge this subscribe actually reserved. `close()` clears the table, so
+      // a later subscribe may have put a DIFFERENT bridge under this name in the meantime, and
+      // decrementing that one's refs releases a topic somebody else is holding.
+      this.#release(name, bridge);
       throw error;
     } finally {
       const held = this.#claimed.get(socket) ?? 1;
@@ -164,7 +172,7 @@ export class ChannelHub {
     // membership this socket's close will give back, so the reference taken above has to go now or
     // it is a bridge nothing will ever release.
     if (socket.topics.has(name)) {
-      this.#release(name);
+      this.#release(name, bridge);
       return;
     }
     // Through the registry, never `socket.subscribeTopic` directly: membership and the index the
@@ -297,12 +305,31 @@ export class ChannelHub {
     if (this.#closed) {
       unsubscribeWhenOpen(bridge);
       if (this.#bridges.get(name) === bridge) this.#bridges.delete(name);
+      // RAISED, not returned. Returning let `subscribe` fall through to `joinTopic`, so the socket
+      // became a member of a topic nothing on this node is bridged to: silent for the life of the
+      // connection, with no error on either side and nothing telling the client to redial. The
+      // same refusal the transport itself answers when it is gone, because from the client's side
+      // that is what happened — this node's bus for that topic is closed.
+      throw new TransportUnavailableError({
+        transport: 'channel',
+        reason: `the hub closed while "${name}" was opening`,
+        // The reader is a browser websocket client, which cannot run a CLI — so pure command
+        // advice would be worse than prose here. The shape that satisfies axiom 4 anyway is
+        // `http/src/error-map.ts`'s: a command that SHIPS (`x errors explain`, unlike the planned
+        // `x logs tail`) for whoever is holding a terminal, then the instruction as a comment.
+        fix: 'x errors explain X_TRANSPORT_UNAVAILABLE --json   # then reconnect and resubscribe: this node is draining',
+      });
     }
   }
 
-  #release(name: Topic): void {
+  /**
+   * `expected` is the bridge the caller reserved. Without it a release looks the topic up by name,
+   * and after a `close()` cleared the table that name may hold a bridge a LATER subscribe opened.
+   */
+  #release(name: Topic, expected?: Bridge): void {
     const bridge = this.#bridges.get(name);
     if (!bridge) return;
+    if (expected !== undefined && bridge !== expected) return;
     bridge.refs -= 1;
     if (bridge.refs > 0) return;
     unsubscribeWhenOpen(bridge);

package/src/client-contract.ts

@@ -72,8 +72,9 @@ export interface LiveClientOptions<T extends TableMap = TableMap> {
   readonly scheduler?: Scheduler;
   /**
    * How often a live socket re-announces itself, in ms. `0` disables it. Defaults to
-   * `DEFAULT_HEARTBEAT_MS` — the same 15s as the server's `realtime.heartbeatMs`, which browser
-   * code cannot read, so it is an option here rather than a value shipped down the wire.
+   * `DEFAULT_HEARTBEAT_MS`, 15s. The one knob for the beat: `realtime.heartbeatMs` in
+   * `app.config.ts` was deleted 2026-08-19 because nothing read it, so this is not a restatement
+   * of a server value — browser code could never have reached one.
    */
   readonly heartbeatMs?: number;
   /** Where a dial failure inside the reconnect timer is reported. Defaults to `reportToConsole`. */

package/src/client-heartbeat.ts

@@ -5,9 +5,10 @@
 import type { Scheduler } from './thundering-herd';
 
 /**
- * The same 15s as `realtime.heartbeatMs` in `@ultimat3/core`'s config, restated rather than read:
- * that value is server configuration and this is browser code, so the client cannot reach it. The
- * two are kept equal on purpose — a node's presence TTL is sized against this interval.
+ * The client's own number, and `As of 2026-08-19` the only one. It used to be described as a
+ * restatement of `realtime.heartbeatMs` in `@ultimat3/core`'s config — that key was read by
+ * nothing and is deleted, so there is no second value to keep this equal to. The server side of
+ * the beat is DERIVED, never configured: `PresenceRegistry.heartbeatMs` is `ttlMs / 3`.
  */
 export const DEFAULT_HEARTBEAT_MS = 15_000;
 

package/src/cursor.ts

@@ -3,9 +3,9 @@
 // and the budget exists to make the expensive answer (a snapshot) the *chosen* one, not the
 // accidental one. See README "Reconnect is the hard part".
 
-import { type Clock, systemClock } from '@ultimat3/core';
+import { type Clock, canonicalJson, systemClock } from '@ultimat3/core';
 import { CursorStaleError } from './errors';
-import { canonicalJson, fnv1a, type Row, type RowPatch } from './json';
+import { fnv1a, type Row, type RowPatch } from './json';
 
 /** Ids are bounded so a cursor stays small enough to ship on every `subscribe` frame. */
 export const CURSOR_ID_LIMIT = 512;

package/src/errors.ts

@@ -20,6 +20,7 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_LIVE_CLIENT_MISSING',
   'X_LIVE_ROW_UNIDENTIFIED',
   'X_LIVE_QUERY_UNKNOWN',
+  'X_LIVE_REPLICA_IDENTITY',
   'X_QUERY_NOT_SUBSCRIBABLE',
   'X_SOCKET_UNAUTHENTICATED',
   'X_SOCKET_AUTH_UNAVAILABLE',
@@ -113,6 +114,7 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_LIVE_CLIENT_MISSING: 'a realtime hook ran with no LiveClient registered',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
   X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
+  X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
   X_QUERY_NOT_SUBSCRIBABLE: 'a hook was bound to a query that is not declared live',
   X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
   X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
@@ -327,6 +329,34 @@ export class ReplicatorSlotHeldError extends RealtimeError {
   }
 }
 
+/**
+ * A table in the entity list replicates with a replica identity other than FULL, so its `delete`
+ * (and any key-changing `update`) carries the KEY COLUMNS ONLY. `toRow` accepts that tuple —
+ * it only requires a text `id` — so the live matcher decides "did this row leave the result set"
+ * from a one-column row, and a row policy written against `!row.private` reads `undefined`.
+ *
+ * **Raised at preflight and LOGGED, never thrown.** Every app running today on the default
+ * identity would stop booting, and the replicator refusing to start is a worse outcome than the
+ * partial rows it is warning about. The runtime half is `ReplicationStreamStats.partialBefore`,
+ * which counts the changes this actually affects. Refusing it at `x verify` time is the follow-up.
+ *
+ * The tables are named because the fix is per table, and they are the entity list's own names —
+ * every one has already passed `assertIdentifier`, so the `fix:` is SQL that can be pasted.
+ */
+export class ReplicaIdentityError extends RealtimeError {
+  constructor(args: { tables: readonly string[] }) {
+    super({
+      code: 'X_LIVE_REPLICA_IDENTITY',
+      cause:
+        `${args.tables.join(', ')} replicate with a replica identity other than FULL, so a ` +
+        'delete carries the key columns only and a live query decides visibility from a partial row',
+      fix:
+        `${args.tables.map((table) => `ALTER TABLE ${table} REPLICA IDENTITY FULL;`).join(' ')}` +
+        ' -- rows already written to the WAL keep the identity they were written with',
+    });
+  }
+}
+
 /**
  * A hook was called before the app entry registered its client. Never a transient fault: the
  * registration is a single call in the entry, so the fix is the call itself rather than a retry.