@ultimat3/realtime 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -29,18 +29,13 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   and never absent. `bun run side-effects` is the check.
 - **Every `@ultimat3/realtime/<subpath>` written in shipped source must be a key of `exports`**,
   comments included — `fix-specifier.test.ts`.
-- **`@ultimat3/realtime/server` needs its own `paths` entry in `tsconfig.base.json`** (the wildcard
-  maps it to a directory that does not exist; `scripts/**` reports `TS2307` without it).
-- A browser file imports core from `@ultimat3/core/page` (`packages/core/src/page-bundle.test.ts`,
-  `packages/query/src/client-bundle.test.ts`).
+- A browser file imports core from `@ultimat3/core/page` (`packages/core/src/page-bundle.test.ts`).
 
 ## Numbers and ceilings
 
 - **Every numeric option is refused when it is not FINITE** — `@ultimat3/core`'s `finiteOption()`.
-  `bun run finite-bounds` reads zero for this package, but it cannot see an option with no `??`
-  default or where a screen runs, so audit by reading the option interfaces
-  (`SubscriptionBook`'s `maxPerTenant` and `openNatsClient`'s `maxReconnectAttempts` were the two it
-  missed). `SyncGrant.expiresAt` is app DATA, not an option, and is deliberately unscreened.
+  `bun run finite-bounds` reads zero here but cannot see an option with no `??` default, so audit
+  by reading the option interfaces. `SyncGrant.expiresAt` is app DATA, deliberately unscreened.
 - **A ceiling is refused where the object is BUILT**, never in a per-connection callback:
   `socketCeilings()` (`sync-node-bounds.ts`) runs once in `createSyncNode`; `SyncSocket` keeps its own
   screen because it is exported. `AcceptBudget`, `SyncSocket` and `SocketRegistry` throw
@@ -50,14 +45,14 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   at the top of `routeFrame` **before `touch()`**), and `FRAME_LIMITS` in `decode` everything a
   client sizes (narrowable, never widenable). `list()` takes a required `max`. `input` is walked
   ITERATIVELY.
-- **Every `SyncSocket` ceiling is reachable from `createSyncNode`**, forwarded as
-  `...(x === undefined ? {} : { x })`.
 - **A `SubscriptionLimitError` names the knob**: every throw site passes `knob` explicitly;
   `channel.test.ts` asserts the hub's two against the option names.
-- **Retained memory is bounded by BYTES**: `RingChangeBuffer` keeps the patch count as a replay
-  bound and byte budgets as the memory bound. `forget(qid)` runs when the last subscriber goes and
-  from `#dropIfUnheld` after a failed cold subscribe (only if the entry is still in the table, unheld
-  and has no read in flight).
+- **Retained memory is bounded by BYTES** (`RingChangeBuffer`: patch count bounds replay, bytes
+  bound memory). `forget(qid)` runs when the last subscriber goes and from `#dropIfUnheld`.
+- **The ring floor is one rule (`change-buffer.ts`, `Ring`)**: only a read that LANDED floors it
+  (`fillWindow().landed`), a forced one exclusively; a position-less read is marked with the
+  node's origin and answers that cursor alone below its first patch; a stale entry serves cold
+  starts only.
 - **Every question a hot path asks is indexed**: `SubscriptionBook` keeps `#bySocket` and a
   per-tenant count; `SocketRegistry` keeps `#byTopic`, changed only by `joinTopic`/`leaveTopic`.
   `reauthorize` calls `book.retenant(socket)`.
@@ -85,8 +80,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A denial is a decision; everything else is a failure.** `visibleWithPolicy` matches
   `QueryDeniedError` and rethrows the rest; `subscriber-gate.ts` and `reauthorize` ask
   `isPolicyDenial(error)`. A failed snapshot raises out of `subscribe`; a failed delivery desyncs that
-  one subscriber; a failed `reauthorize` keeps the subscription, unless its org moved — then it is
-  refused under its sid (`refuseSubscription`), as is a failed re-seat. Failures count as
+  one subscriber; a failed `reauthorize` keeps the subscription, a DENIED one is refused under its sid
+  (`refuseSubscription`) — as is one whose org moved, and a failed re-seat. Failures count as
   `gateFailures` via `onGateFailed`, never `onRowDenied`.
 - **One serial lane per query id (`WindowLock`) is the only thing that orders a fanout.** `deliver`
   enters every lane before awaiting any; no fanout takes a second lane; a lane that fails desyncs its
@@ -107,7 +102,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   never clears a mark (`live-fanout.test.ts`).
 - **A change the window already holds is refused** (`change.lsn <= entry.lsn`, counted as
   `staleChanges`). **A gap is detected**: the replicator stamps `producer` + `seq`; a skipped
-  sequence marks every window stale and every subscriber desynced; `refillWindowInLane` replaces it.
+  sequence — or a NEW producer after a known one — stales every window; `refillWindowInLane` replaces it.
 - **A bulk write stales only the windows reading its entity** (`invalidate(entity)`, from
   `onBulk`). **A stale window's re-read re-snapshots EVERY subscriber**, before the lsn guard and
   on a non-matching change too (`live-replicator-bulk.test.ts`, `live-fanout.test.ts`).
@@ -124,24 +119,21 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 ## The node, the bus and presence
 
 - `sync` is stateless: no sticky sessions, nothing on a socket survives a restart.
-- **`selectTransport(env, realtime)` is the one place `realtime.transport` + env become a bus**; the
-  KV bucket and presence TTL come back with it. The config decides, the env supplies (22.0.0):
-  `'nats'` dials the variable `urlEnv` names and refuses (`X_CONFIG_INVALID`) when unset; `'memory'`
-  refuses a set `NATS_URL` (or the named variable).
+- **`selectTransport(env, realtime)` is the one place `realtime.transport` + env become a bus** (KV
+  bucket and presence TTL come back with it). The config decides, the env supplies: `'nats'` refuses
+  (`X_CONFIG_INVALID`) when the `urlEnv` variable is unset; `'memory'` refuses a set one.
 - **`nats` is imported only by `nats-lib-client.ts`**; reconnect and re-subscription are the
-  library's job — `NatsTransport` must never grow subscription bookkeeping. What stays above the
-  port: the herd jitter (`reconnectDelayHandler`) and the KV semantics presence needs
-  (`nats-jetstream.ts`, `nats-kv.ts`). `nats-fake.ts` is a bus with server semantics.
-- **Nothing leaves `NatsTransport` uncoded** — `#translating` wraps the port's synchronous
-  `publish`/`subscribe` refusals as `X_TRANSPORT_UNAVAILABLE`; an `UltimateError` passes through.
-  `transport-parity.test.ts` asserts both transports, and that the wrap still delivers. `#ensure`
-  reuses a mid-reconnect client on purpose.
+  library's — `NatsTransport` never grows subscription bookkeeping. Above the port: the herd jitter
+  and presence's KV semantics (`nats-jetstream.ts`, `nats-kv.ts`). `nats-fake.ts` has server semantics.
+- **Nothing leaves `NatsTransport` uncoded** — `#translating` wraps `publish`/`subscribe` refusals
+  as `X_TRANSPORT_UNAVAILABLE`. `#ensure` reuses a mid-reconnect client on purpose;
+  `Transport.onReconnect(listener)` (required) announces each recovery.
 - **A bucket name is checked before interpolation** (`assertBucket`, `X_TRANSPORT_PROTOCOL`); a
   presence key or member id is base64url-encoded (`encodeToken`), never validated.
 - Presence lives in `transport.shared`. The sync node is `PresenceRegistry`'s only caller:
   subscribing to a topic IS joining, repeating the frame is the heartbeat, dropping or closing is the
   leave. Expiry is silent, so the node sweeps on an interval, and **one node per topic sweeps** (lowest
-  id in the lease key's keyed set). `roster()` caps a frame at `maxMembers` (256) with `total`;
+  id in the lease's keyed set; the lease carries the roster followers record). `roster()` caps a frame at `maxMembers` (256) with `total`;
   `list()` is never capped. `total` is set on `sync` frames only.
 - **A socket the node evicts ITSELF goes through `evict(socket, code, reason)`** (the full
   `teardown`), never `sockets.remove`. **`drain()` waits for the presence leaves it started** —
@@ -156,9 +148,12 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A hub that closed opens nothing**: `close()` sets `#closed` before the walk; `#open` closes a
   late subscription and RAISES `X_TRANSPORT_UNAVAILABLE`. `#release` takes the reserved bridge, never
   a name.
-- **An upgrade from a foreign page is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
-  (`sync-origin.ts`, core's `proveSameOrigin`); `AcceptBudget` is reserved before `authenticate`,
-  `refund()`ed on every exit that takes no socket.
+- **An upgrade from another origin is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
+  (`sync-origin.ts`): `allowedOrigins`, when declared, is the WHOLE list; undeclared, the
+  `Host`-derived origin (and its `https` spelling when reached over plain http). The refusal names
+  the asker and the list. `x dev` keeps the reached-on origin (`admitReachedOrigin`) and adds
+  its web role's beside a declared list; a container adds nothing. `AcceptBudget` is reserved before
+  `authenticate`, `refund()`ed on every exit that takes no socket.
 - **A socket's actor comes from `createSyncNode({ authenticate })` only**, run before
   `server.upgrade`. `null` = 401 `X_SOCKET_UNAUTHENTICATED`; a throw = 503
   `X_SOCKET_AUTH_UNAVAILABLE`. Absent = anonymous, and `start()` warns. The actor lives only in the
@@ -182,42 +177,42 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A channel is a DECLARATION**: `channel(name, { params, policy, catchUp, records?, events? })`.
   Deny by default, and `policy` is REQUIRED (`X_CHANNEL_DECLARATION_INVALID`; a public channel says
   `policy: allow('public')`). Presence rides `events: true` channels.
-- **A guard that FAILS keeps the topic on re-auth** (`guardFailures`, `channel.guard_failed`); the
-  initial subscribe still refuses.
+- **A guard that FAILS on re-auth SUSPENDS the seat** (`guardFailures`): kept, silent until a pass.
+  A `null` actor on a `row` channel and a tenancy refusal are DENIALS.
+- **A seat is decided for the actor ON the socket when the guard resolves** (`#settle`); a denied
+  re-ask on a suspended seat is refused and latched. The latch is capped at `maxTopicsPerSocket`.
+- **A missed change reopens every records topic** (`ChannelHub.invalidate()`, beside both
+  `registry.invalidate()` sites).
 - **A channel patch id carries the node** (`nodeId`, default a per-hub `uuid()`).
-- **An error never renders a credential**: `parsePgUrl` names `DATABASE_URL`, never the URL.
+- **An error never renders a credential**: `parsePgUrl`/`parseNatsUrl` name the variable.
 
 ## Replication
 
 - Exactly one `replicator` per DB, by a session-level advisory lock. **`start()` and
-  `PgAdvisoryLock.tryAcquire` are MEMOISED** (guard and promise published synchronously, cleared on
-  settle); `stop()`/`release()` await the in-flight one. A start that FAILS hands the lock back, and
-  `running` is set only once the feed pumps.
-- **The pump has one way out, `#die`**, which records the failure, stops the confirm timer, closes and
-  nulls the connection. `start()` awaits the previous pump before it dials. **`stop()` releases
-  everything before it reports anything.**
-- **The replicator ensures its publication** (`pg-publication.ts`, from preflight): `CREATE … FOR
-  TABLE` every entity table, or `ALTER … ADD TABLE` the missing; never a DROP, never `FOR ALL
-  TABLES`. Only a server ErrorResponse becomes the refusal. No not-live declaration exists.
-- **A fix handing over `REPLICATION` carries `REPLICATION_GRANT_WARNING`** (cluster-wide grant).
-- **TLS is libpq's `sslmode`** (`pg-tls.ts`): only `verify-*` verify; the runtime never rejects
-  (`rejectUnauthorized: false`), `judgeHandshake` decides; the raw socket is DEAF after
-  `upgradeTLS` (Bun feeds it ciphertext).
-- **Only a table with NO replica identity is warned** (`NOTHING`, or keyless `DEFAULT`), before the
-  slot. A keyed DEFAULT table is correct: the window decides (`pg-identity-window.live.test.ts`).
-- **Every session pins `datestyle=ISO`, `intervalstyle=postgres`, `extra_float_digits=3`** in the
-  startup packet (`pg-connection.ts`), as Postgres' own walreceiver does.
+  `PgAdvisoryLock.tryAcquire` are MEMOISED**; `stop()`/`release()` await the in-flight one. A start
+  that FAILS hands the lock back; `running` is set once the feed pumps.
+- **The pump has one way out, `#die`**: failure recorded, timer stopped, connection closed, then
+  `onEnd(reason)`. `start()` awaits the previous pump. **`stop()` releases everything first.**
+- **A stream that ENDS is restarted**: feed then lock ABANDONED (synchronous, never asked);
+  `stop()` bounds both goodbyes by `STOP_DEADLINE_MS`; redial on `retryDelayMs` (injected
+  `schedule`) from `lastLsn` until `stop()`. The delay resets only when a change is PUBLISHED. A
+  rejected `publish` is one such end, and so is a LOST lock (`AdvisoryLock.onLost`), mid-dial
+  included. `running` = pumping AND no refused change owed; `onChange` is fenced per run and
+  REFUSES, never drops.
+- **A row crosses the bus through its entity's columns** (`replicator-row.ts`): `parseEnvelope`
+  revives by `entityForTable` + `$parse`, bytes as base64 — by declared kind, never by shape.
+- **Cleartext/md5 auth is answered only under `sslmode` `require`, `verify-*` or `disable`**.
+- **The replicator ensures its publication** (`pg-publication.ts`): `CREATE … FOR TABLE` every
+  entity table, or `ALTER … ADD TABLE` the missing; never a DROP, never `FOR ALL TABLES`.
+- **TLS is libpq's `sslmode`** (`pg-tls.ts`): only `verify-*` verify; the runtime never rejects,
+  `judgeHandshake` decides; the raw socket is DEAF after `upgradeTLS`.
+- **Every session pins `datestyle=ISO`, `intervalstyle=postgres`, `extra_float_digits=3`**.
 - A change lsn is `<16 hex commit position><8 hex row position>`; never order by one half, a wall
   time or a counter.
 - Slot, publication and entity names match `[a-z_][a-z0-9_]*` before interpolation — a security
-  boundary (`pg-identifier.ts`, the one `assertIdentifier`). A SQLSTATE is data: `pg-wire.ts`'s
-  `FIXES` is read with `Object.hasOwn`.
-- **A live row equals a repository row**: `pg-entity-row.ts` decodes through `@ultimat3/entity`'s
-  own `decodeRow` / `entityForTable`, so money (three physical columns), scale and every other kind
-  fold exactly as `postgresRepo` folds them.
-- A write's name rides the WAL: `pg-replication.ts` reads it off the transaction's opening
-  `pg_logical_emit_message` (prefix `WRITE_ORIGIN_WAL_PREFIX`; `START_REPLICATION` asks
-  `messages 'true'`).
+  boundary (`pg-identifier.ts`). A SQLSTATE is data: `FIXES` is read with `Object.hasOwn`.
+- **A live row equals a repository row**: `pg-entity-row.ts` decodes by `@ultimat3/entity`'s
+  `decodeRow` / `entityForTable`.
 
 ## The page
 
@@ -256,11 +251,15 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `useQuery`'s input is read once, at call time.
 - Every subscription handle (`LiveHandle`, the hook accessors, `Unsubscribe`) is `Disposable`, and
   `[Symbol.dispose]` is the same function as the release. Type claims go in `type-pins.ts`.
-- **The outbox**: only `pending` is sendable; `drain()` is one chained pass at a time; backpressure
-  over `MAX_BUFFERED_BYTES` declines rather than fails. `#epoch` is bumped before the requeue scan and
-  read every pass iteration. `#persist` hands the store SNAPSHOTS by KEY (`QueueChange`); one tab
-  drains at a time (`navigator.locks`, `page-outbox.ts`'s `exclusive`) and resets a stored `inflight`
-  to `pending` under the lock.
+- **The outbox**: only `pending` is sendable; `drain()` is one chained pass at a time. `#epoch` is
+  bumped before the requeue scan and read every pass iteration. `#persist` hands the store
+  SNAPSHOTS by KEY; one tab drains at a time (`navigator.locks`) and resets a stored `inflight`
+  under the lock. A `rescope` abandons the queue, clears the single-flight slot and bumps the
+  outbox's epoch synchronously; `enqueue` decides WHOSE queue before its first await and refuses
+  otherwise (`X_OFFLINE_QUEUE_ABANDONED`), and `useMutation` fences its own await (the POST) on the
+  scope epoch it was called under. A wipe or open the disk refuses is warned
+  `X_LOCAL_STORE_UNAVAILABLE` and never rejects `ready`. At-least-once: an entry leaves the disk
+  when its ack is written.
 
 ## The client connection
 
@@ -273,20 +272,16 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A refusal `ack` is revived as a branded `UltimateError`** (`refusalError`, `client-frames.ts`).
 - **A reconnect replays registrations AND topics** — one `hello`, one `subscribe` per registration
   (with its cursor) and per topic.
-- **The client beats** (`heartbeatMs`, default `DEFAULT_HEARTBEAT_MS` 15 s, `0` disables): a `hello`
-  plus one subscribe per topic (the presence heartbeat). Two silent windows close with `4000`. The
-  node's `socket.skewed` compares the build the `hello` claims against its own. The server beat is
-  derived: `PresenceRegistry.heartbeatMs = max(1000, floor(ttlMs / 3))`.
+- **The client beats** (`DEFAULT_HEARTBEAT_MS` 10 s = default ttl / 3, pinned by
+  `client-heartbeat.test.ts`; `0` disables): a `hello` plus one subscribe per topic. Two silent
+  windows close with `4000`. **The node names the beat: `hello.heartbeatMs`** — `Heartbeat.follow`
+  per socket; the engine reaps ports on the longer of its own and the node's.
 - **There is ONE `backoffDelay`, `@ultimat3/core`'s, counted from 1** — `policyDelay()` maps a
-  `BackoffPolicy` onto it; `bun run flight-copies` refuses a second curve. Long form:
-  `docs/history/realtime.md`, "Moved 2026-10-01".
+  `BackoffPolicy` onto it; `bun run flight-copies` refuses a second curve.
 
 ## Rules for code here
 
 - Never a bare `Error`. Never `any`. Never `Date.now()` — take a `Clock` (`monotonic()` for durations).
-- **A test fixture standing in for a FOREIGN error extends `Error` on purpose** (`PoolTimeout`,
-  `Denied`, `ThirdPartySdkError`): it simulates a value this package did not construct. The rule
-  governs what this package **throws**, never what a test hands it.
 
 ## The page boot
 
@@ -294,7 +289,8 @@ Browser bytes per hook, as last measured: `docs/history/realtime.md`. Re-measure
 
 - **The disk boot is ONE page script (`boot.ts`, `./boot`)**, served at `/_x/page-boot/<hash>.js`
   on a document with the scope tag and a realtime island; it wipes every other principal's stored
-  scope, then restores. `booted` reads its promise off `globalThis[Symbol.for('ultimate.page-boot')]`.
+  scope — the scope kept is read at the wipe, after the disk opens, never at boot start — then
+  restores. `booted` reads its promise off `globalThis[Symbol.for('ultimate.page-boot')]`.
 - **An island never carries the outbox**: `boot.ts` builds it; `useMutation` and the page socket read
   it through `outbox-slot.ts` after `page.booted`. No boot ⇒ a refused write is rejected, not queued.
 
@@ -303,13 +299,12 @@ Browser bytes per hook, as last measured: `docs/history/realtime.md`. Re-measure
 `index.ts` / `server.ts` are the two barrels. Server side: `sync-node.ts` (+ `sync-auth`,
 `sync-frames`, `sync-upgrade`, `sync-listen`, `drain-evictions`), `channel.ts`, `presence.ts`,
 `socket.ts`, `live-query.ts` (+ `live-definition`, `live-refusal`, `live-tenant`, `live-resume`, `query-window`, `live-fanout`, `window-lock`,
-`subscriber-gate`, `policy-gate` — the only authz seam — and `matcher-bridge`), `replicator.ts` /
+`subscriber-gate`, `policy-gate` — the only authz seam — and `matcher-bridge`), `replicator.ts` (+ `replicator-envelope`) /
 `live-replicator.ts`, the Postgres client (`pg-*.ts`, `pgoutput.ts`), the bus (`nats-*.ts`,
 `transport-env.ts`, `fanout.ts`). Client side: `client*.ts`, `socket-engine.ts` / `socket-host.ts` /
 `sync-worker.ts`, `record-*.ts`, `page-*.ts`, `boot.ts`, `offline-queue.ts`, `use-*.ts`,
 `reactivity.ts`. Shared: `sync-protocol.ts` (the wire), `cursor.ts`, `change-buffer.ts`,
-`thundering-herd.ts`, `live-contract.ts`, `json.ts` (no hash), `type-pins.ts`. Each file's header
-states its one job.
+`thundering-herd.ts`, `live-contract.ts`, `json.ts` (no hash), `type-pins.ts`.
 
 ## Commands
 
@@ -318,12 +313,11 @@ bun test packages/realtime/src            # from the REPO ROOT, never from packa
 bun run typecheck
 ```
 
-`bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers and Bun reads it from the cwd.
+`bunfig.toml`'s preload installs `@ultimat3/testing`'s matchers; Bun reads it from the cwd.
 
 Changing a frame shape means a fixture in `sync-protocol.test.ts` (the round-trip test fails
 without one) and bumping `PROTOCOL_VERSION` **when an old frame becomes unreadable in either
 direction**. `decode` is a whitelist: an additive optional field, or removing a field read through
-`list()`, is free; removing a field read through `str()`/`num()` (which throw) is a bump. Read the
-field's line in `decode` before claiming a removal is free.
+`list()`, is free; removing a field read through `str()`/`num()` (which throw) is a bump.
 
 Why each rule above is shaped the way it is: [`docs/history/realtime.md`](../../docs/history/realtime.md).

package/README.md

@@ -25,6 +25,9 @@ export const liveFeed = query({
 
 // mutator (action + optimistic local twin)
 export const likePost = mutator({
+  // REQUIRED (`X_MUTATOR_NOT_IDEMPOTENT`): a replay under the same Idempotency-Key answers the
+  // first result instead of running `server` again.
+  idempotent: true,
   // Convergent, not incremental: `local` replays on every server update, so applying it N times has to
   // equal applying it once — `likedByMe` is what makes the second application a no-op.
   local(tx, { postId }) {
@@ -278,6 +281,7 @@ wire.
 | outbound bytes buffered on one socket | 1 MiB | `createSyncNode({ maxBufferedBytes })` | the frame is dropped and `send` answers `false` |
 | dropped frames before that socket is closed | 32 | `createSyncNode({ maxDroppedFrames })` | close `1013` (`overloaded`), reason `backpressure` |
 | time one socket may route no frame | 120s | `createSyncNode({ idleTimeoutMs })` | close `4001` (`idle`), reason `idle timeout` |
+| time one grant's `refresh()` may hold the re-auth pass | 10s (10 000 ms) | `createSyncNode({ grantRefreshDeadlineMs })` | reported and skipped: the grant stays expired and is asked again next pass |
 | 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` |
 
@@ -350,15 +354,32 @@ credential drained the bucket and every signed-in reconnect behind it was shed.
 behind an ingress every dial has the ingress's address, and a forwarded header is the caller's own
 claim.
 
-**A socket from a foreign page is refused** — `403 X_SOCKET_ORIGIN_REFUSED`, before `authenticate`
+**A socket from another origin is refused** — `403 X_SOCKET_ORIGIN_REFUSED`, before `authenticate`
 and before the budget. A websocket carries the session cookie and no CORS applies to it, so a page on
 a sibling host (same-site, which `SameSite=Lax` does not stop) could open one as its visitor. The
-rule is `@ultimat3/core`'s `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks, with two
-admissions of the node's own (`sync-origin.ts`): no `Origin` header (RFC 6455 has every browser send
-one, so its absence is not a browser), and the node's own host name at any port or scheme (cookies
-are not port-isolated, and the Compose rung serves the page on `:3000` and the node on `:3001`). A
-page on another host is admitted by `createSyncNode({ allowedOrigins })` — the CLI passes
-`APP_URL`'s origin.
+rule is `@ultimat3/core`'s `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks, and what
+is admitted is decided in `sync-origin.ts`:
+
+| Admitted | When |
+|---|---|
+| no `Origin` header | always — RFC 6455 has every browser send one, so its absence is not a browser |
+| `createSyncNode({ allowedOrigins })`, compared exactly (scheme, host, port) | when any is declared. The declaration is the WHOLE list (24.0.0): the origin the node was reached on is no longer admitted beside it, because that origin is read off the `Host` header and a sibling subdomain pointed at the node would be "its own" |
+| the origin the node was reached on | only when nothing is declared. A node reached over plain `http` also admits the `https` spelling of that host and port: TLS ended at a proxy, the scheme is not knowable there, and a browser sends no `sec-fetch-site` on a websocket handshake |
+
+The CLI passes `APP_URL`'s origin, which the Compose rung (`:3000` / `:3001`) requires on `sync`
+and the Helm chart sets from `ingress.host`. Under `x dev` it also adds the web role's own origin
+and its `localhost`, `127.0.0.1` and `[::1]` spellings to a declared list, so `x dev --port 4000`
+beside an `.env` naming `:3000` still connects, and passes `admitReachedOrigin: true`, which keeps
+the origin the node was reached on beside the list (a Codespace, a tunnel: `x dev` binds loopback,
+so a `Host` reaches it only through a forward its own user set up); a container adds nothing, and a wrong `APP_URL`
+there refuses. The refusal's cause names the origin that asked and every origin the node admits;
+its fix is the `export APP_URL=…` that admits the asker.
+
+**The node's `/healthz` and `/readyz` tell the detail to a listed peer only**
+(`createSyncNode({ healthDetailPeers })`, default the box itself). A request carrying `Forwarded`,
+`X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Real-IP` or `Via` is told the
+verdict only. A proxy that adds none of them is indistinguishable from a direct peer: a
+header-less proxy must not route the health paths.
 
 The client dials itself back. A closed socket arms one timer — the node's delay when a `reconnect`
 frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `BackoffPolicy` — and that timer calls `connect()`, which re-subscribes
@@ -384,7 +405,7 @@ below (`heartbeatMs` on the internal `LiveClient`; `0` disables the pass).
 
 | Property | Behaviour |
 |---|---|
-| Default | `DEFAULT_HEARTBEAT_MS`, 15s. The client's own number and the only one: `realtime.heartbeatMs` in `app.config.ts` was deleted 2026-08-19 because nothing read it |
+| Default | `DEFAULT_HEARTBEAT_MS`, 10s — a third of the default presence ttl, until the node names its own on its `hello` reply (`hello.heartbeatMs` = `min(ttl / 3, idle / 4)`, floored at 1 s): the client follows that for the life of the socket, and the SharedWorker engine reaps a tab on the longer of the two. The client's own number: `realtime.heartbeatMs` in `app.config.ts` was deleted 2026-08-19 because nothing read it |
 | One beat | a `hello` — which carries no cursors at all; `HelloFrame` has no resume list, so a beat and an opening frame are byte-identical — plus one subscribe frame per topic held |
 | Why the topics | on the node, repeating the subscribe frame **is** the presence heartbeat; presence has no frame of its own in either direction |
 | Not a deploy check | `update-available` answers a skew between the build the client claims — the `hello`'s `buildId`, or `?build=` on the dial; every hello is read and the latest one is the record — and the node's own. A client says the same build on every beat and the node's never moves while the socket is open, so every `hello` on one socket answers the same forever. A client hears about a deploy on the socket it opens against the **new** node |
@@ -413,6 +434,10 @@ wire twice by a reconnect that raced an ack.
 | The store is handed **snapshots, by key**, never the live entries or the whole queue | `QueueStore.write` is a durable write and may await before it reads; given an entry itself it persists a status that was never true when it was called. By key, because two tabs of one user share the store and a whole-queue save let the last tab erase the other's write |
 | One tab drains at a time, and drains what every tab queued | the outbox's replay runs under the Web Lock `ultimate-outbox:<principal>` and re-reads the queue first, so a write another tab queued is sent, in order, and a stored `inflight` from a closed page goes back to `pending` |
 
+`createOutbox({ warn })` — where a disk that refused the queue is said
+(`X_LOCAL_STORE_UNAVAILABLE`, default `console.warn`); the outbox then queues in memory for that
+principal.
+
 ### Limits, stated plainly
 
 - **The change window is per node, and a `qid` window can only be.** A client that reconnects to a
@@ -421,8 +446,15 @@ wire twice by a reconnect that raced an ack.
   matcher and no window, so it cannot produce one. What the snapshot path costs is one **shared**
   read per (query, node), not one per client. A cross-node delta needs an *entity*-keyed window each
   node fills from the change stream it already subscribes to, which is a `ResumeSource` shape change.
+- **A ring is complete from its floor, and never from the start of time** (24.0.0). A
+  `RingChangeBuffer` ring is born with one: the lsn of its first patch, or the lsn its window was
+  read at (`floorAt(qid, lsn)`, which only ever raises it and drops what a re-read superseded). A
+  cursor below the floor re-snapshots. A ring used to be born with none, so a cursor minted on
+  another node resumed as a delta over changes this node never retained.
 - **Fanout is at-most-once, and a gap is detected rather than assumed away.** The replicator stamps
-  every published change with `producer` + `seq`; a `sync` node that sees a skipped sequence
+  every published change with `producer` + `seq`; a `sync` node that sees a skipped sequence —
+  or, since 24.0.0, a new `producer` after one it already read: the run before it died, and the
+  tail of a dead stream has no later sequence to be missed against —
   invalidates every window it holds and desyncs every subscriber, so the next change to each query
   re-reads and re-snapshots. Both fields are optional on the bus, so a publisher that does not
   sequence simply detects nothing. Durable replay (JetStream) is a separate decision — retention,
@@ -485,9 +517,11 @@ wire twice by a reconnect that raced an ack.
   the new node never held, so the resume falls back correctly rather than silently; the `qidOf`
   removal itself costs nothing, because every qid a node computes comes from a decoded frame and
   `JSON.parse` produces none of the values the two spellings disagreed about.
-- **A topic guard that *fails* keeps the topic.** On the re-auth pass, only a denial
-  (`X_TOPIC_FORBIDDEN`, or a policy denial) unsubscribes; anything else increments `hub.guardFailures`
-  and logs `channel.guard_failed`. `catch { unsubscribe }` reported a store that timed out as a
+- **A topic guard that *fails* suspends the topic.** On the re-auth pass, only a denial
+  (`X_TOPIC_FORBIDDEN`, or a policy denial) unsubscribes; anything else increments `hub.guardFailures`,
+  logs `channel.guard_failed` and SUSPENDS the seat — kept, and sent nothing, until a pass
+  succeeds. Two answers are denials before any rule runs: a `null` actor on a channel with a `row`
+  loader, and a loader the tenant guard refused. `catch { unsubscribe }` reported a store that timed out as a
   revoked grant — every topic on every re-authenticated socket, silently, with the client never told
   to resubscribe. The initial `subscribe` is deliberately not split that way: there is no
   subscription to keep, so a guard that raises refuses that subscribe and the client hears about it.
@@ -516,7 +550,8 @@ wire twice by a reconnect that raced an ack.
 - **A full presence frame is capped** at `maxMembers` (256) and carries `total`, so a 5,000-person
   room renders "and 4,744 others" instead of shipping 5,000 members to every joiner. The set itself
   is never capped — the sweep differences it — and one node per topic runs that sweep, elected
-  through the shared store, rather than every node re-reading every room it has ever seen.
+  through the shared store, rather than every node re-reading every room it has ever seen; the
+  leader's lease carries its roster, so a takeover announces a dead leader's members.
 - **Deliveries are serialized per query id, not per node.** A change is fanned out inside that
   query's own FIFO lane, so two changes off the bus cannot interleave: the window one of them
   writes is the window every subscriber's gate reads, and patch frames leave in lsn order. Every
@@ -557,7 +592,29 @@ wire twice by a reconnect that raced an ack.
   it gains the entity tables it lacks (`ALTER PUBLICATION … ADD TABLE`) and loses none. `FOR TABLE`
   because a table's owner may publish it without a superuser; a role that may not is refused with
   `X_REPLICATION_FAILED` and the statement to run as one that may. `InMemoryChangeFeed` + `InProcessTransport` remain the
-  defaults for `x dev` and every test.
+  defaults for `x dev` and every test. `START_REPLICATION` asks `messages 'true'`, which needs
+  **Postgres ≥ 14**.
+- **A replication stream that ends is restarted** (24.0.0). `ChangeFeed.start` takes
+  `onEnd(reason)`, called when the pump dies on its own — the walsender ended the copy, a decode
+  failed, the handler rejected — and never for a `stop()`. `createReplicator` answers it: `running`
+  goes `false`, the feed is stopped, the advisory lock is released so a standby may take the slot,
+  and the same process redials on `retryDelayMs(attempt)` (through `ReplicatorOptions.schedule`)
+  until it holds the stream again or `stop()` is called. The restart resumes from the last lsn this
+  process published, so one rejected `transport.publish` costs a redial and loses nothing.
+  `stats()` carries `restarts` and `failure`; **`replicator.running` is what a readiness check
+  reads**. Until 24.0.0 the death was recorded in `stats().failure`, which nothing read.
+- **A row crosses the bus as the row it was** (`replicator-row.ts`, 24.0.0). The bus carries text;
+  `parseEnvelope` revives each value through the column its entity declared (`entityForTable` +
+  `$parse`) — a `timestamp()` is a `Date` again, `bytes()` (sent as base64) a `Uint8Array` — and
+  decides by that declaration, never by what a value looks like. A table with no entity on the
+  node, and a value its column refuses, cross as they arrived. Until 24.0.0 a `Date` reached the
+  matcher as an ISO string and every window ordered by a timestamp mis-sorted on any deployment
+  with a bus.
+- **`ChangeEvent.omitted` names what an update could not carry** (24.0.0). Postgres logs no bytes
+  for an out-of-line (TOAST) value an `UPDATE` did not touch. Under `REPLICA IDENTITY FULL` the
+  value is copied from the old tuple and `after` is whole; under any other identity `after` lacks
+  the property and `omitted` lists it (entity property names), so a consumer re-reads the row
+  rather than adopting a partial one.
 - **`selectChangeFeed(env, { entities })` decides which feed a boot installs** — same law
   `selectMailDriver` follows: an unset variable means the embedded default. It returns `{ feed,
   mode, detail, slot, lock }`: `mode` is `'embedded' | 'external'`, `detail` is the env key that
@@ -580,6 +637,14 @@ wire twice by a reconnect that raced an ack.
   `X_REPLICATION_TLS` naming the check. Until 22.1.0 `prefer` verified — every private-CA server
   (CNPG) failed as a refused write — and the raw socket kept feeding ciphertext to the reader
   after the upgrade, so a trusted CA still hung the stream.
+- **A password the network could use is sent only when the mode allows it** (24.0.0): a
+  cleartext or md5 request is answered under `require`, `verify-ca`, `verify-full` (the session is
+  guaranteed encrypted) or `disable` (the operator said it is not), and refused with
+  `X_REPLICATION_FAILED` under `prefer` — the default — and `allow`, where a stripped upgrade falls
+  back to cleartext without a word. SCRAM is answered under every mode. `require` encrypts to
+  whoever answered and verifies no certificate: it protects the password from a passive listener
+  only. An attacker on the path needs `verify-ca` or `verify-full` to be stopped; `require`
+  answers a cleartext or md5 request for libpq parity, not because it is safe against one.
 - **`REPLICATION` is a cluster-wide grant.** A `replication=database` session may also run
   `BASE_BACKUP` and `START_REPLICATION PHYSICAL` with no database check, so on a shared Postgres
   cluster the role could copy every database, `pg_authid` included, drop other slots and exhaust
@@ -588,6 +653,21 @@ wire twice by a reconnect that raced an ack.
   `REPLICATION` to an app role on a shared cluster. Every fix line that hands the grant over says
   so (`REPLICATION_GRANT_WARNING`, `pg-wire.ts`) and links
   [`docs/ops/01-kubernetes.md`](../../docs/ops/01-kubernetes.md#replication-is-a-cluster-wide-grant).
+- **A lock that is lost ends the stream** (24.0.0). The lock is a session, and a session can die
+  while the replication stream stays up — Postgres then grants the lock to the next process that
+  asks, and a holder that kept streaming would be one of two replicators. `AdvisoryLock.onLost(
+  listener)` (required) reports it: `PgAdvisoryLock` watches its idle session through
+  `PgConnection.watchIdle` (EOF, a read error or a server `FATAL`; no polling), and
+  `createReplicator` answers exactly as it does a dead stream — `running` false, feed stopped,
+  back into the takeover loop to compete for the lock again.
+- **A recovery asks nothing, and a stop waits a bounded time** (24.0.0). A dead stream or a lost
+  lock calls `ChangeFeed.abandon()` and then `AdvisoryLock.abandon()` (both required, both
+  synchronous): the sockets are closed outright with no goodbye written, the feed first so it is
+  silent before the lock is given up. `stop()` asks politely and gives each goodbye
+  `STOP_DEADLINE_MS` (5 s) before abandoning it. The restart delay resets only once a change has
+  been published, so a change the bus refuses every time backs off to `maxMs` instead of
+  redialling at the base; `stats().failure` names its entity and lsn, and `running` stays `false`
+  until it goes out.
 - **`PgAdvisoryLock` is the production `AdvisoryLock`** — `SELECT
   pg_try_advisory_lock(hashtext('x:replicator:<slot>'))` on its own session. Session-scoped, so a
   crashed replicator releases it automatically: no lease renewal, no fencing token, no split brain.
@@ -614,7 +694,10 @@ wire twice by a reconnect that raced an ack.
   the library's own KV abstraction expresses neither a per-message TTL nor a batch direct get.
   Reconnect and re-subscription are the library's: a lost connection is re-established underneath
   the caller, which is what makes `sync` stateless, and the jitter that spreads a restart herd is
-  handed to it as its reconnect delay rather than re-implemented above it. The bucket needs
+  handed to it as its reconnect delay rather than re-implemented above it.
+  `transport.onReconnect(listener)` — a required member of `Transport` since 24.0.0 — announces
+  each recovery and returns the unsubscribe: fanout is at-most-once, so whatever was published
+  during the drop never arrived. `InProcessTransport` has no connection to lose and never calls it. The bucket needs
   nats-server ≥ 2.11 (batch direct get, per-message TTL); an older one is `X_TRANSPORT_PROTOCOL` on
   the first dial, never a retry loop, because no amount of reconnecting makes a server newer.
 - **The lsn is `<commit position><row position in the transaction>`, 24 hex characters.** Neither
@@ -622,7 +705,14 @@ wire twice by a reconnect that raced an ack.
   *transactions* in commit order, so per-record WAL positions are not monotonic across them. The
   pair sorts in delivery order and is byte-identical on replay, which is what turns at-least-once
   redelivery into a drop instead of a duplicate.
-- **A keyed table does not need `REPLICA IDENTITY FULL`; a table with NO identity is warned**
+- **A channel with params needs `REPLICA IDENTITY FULL` on its `records` tables** (24.0.0). It
+  holds no window: a DELETE is routed to the topic the OLD row's params name, and under the default
+  identity that image is the key alone — no topic, no `remove`, and members keep the deleted
+  record. Preflight asks the catalog about exactly those tables (`paramsChannelTables()`, or
+  `PgLogicalReplicationOptions.fullIdentityTables`) and logs `replication.channel_identity_partial`
+  with the fix `x db gen "replica identity full"`: `x db gen` grants FULL to those tables beside
+  the live queries' `subscribes:` ones, so an app that declares a params channel owes one migration.
+- **For a live query, a keyed table does not need `REPLICA IDENTITY FULL`; a table with NO identity is warned**
   (`As of 2026-09-23`). Under DEFAULT an update carries no old tuple and a delete only the key, and
   neither decides a live query: the shared window holds the whole row, so a row leaving the result
   set is decided from the window and a delete by `holds(id)` — proved on real WAL by
@@ -685,7 +775,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `FrameRateLimitError` (extends `RealtimeError`) | `X_FRAME_RATE_LIMIT` | `src/errors.ts` |
 | `LiveQueryUnknownError` (extends `RealtimeError`) | `X_LIVE_QUERY_UNKNOWN` | `src/errors.ts` |
 | `LiveRowUnidentifiedError` (extends `RealtimeError`) | `X_LIVE_ROW_UNIDENTIFIED` | `src/errors.ts` |
-| `NotImplementedError` (extends `RealtimeError`) | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `OfflineQueueAbandonedError` (extends `RealtimeError`) | `X_OFFLINE_QUEUE_ABANDONED` | `src/page-errors.ts` |
 | `ProtocolVersionError` (extends `RealtimeError`) | `X_PROTOCOL_VERSION` | `src/page-errors.ts` |
 | `RealtimeError` | any `RealtimeErrorCode` — `REALTIME_ERROR_CODES`; the base of every other class here, thrown directly for a code none of them covers | `src/realtime-error.ts` |
 | `RealtimeUninstalledError` (extends `RealtimeError`) | `X_REALTIME_UNINSTALLED` | `src/page-errors.ts` |

package/package.json

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

package/src/advisory-lock.ts

@@ -0,0 +1,57 @@
+// Single responsibility: the mutual-exclusion contract behind "exactly one replicator per database",
+// and its single-process implementation. The Postgres one is `pg-advisory-lock.ts`.
+
+/** Session-scoped mutual exclusion. Postgres-backed in production, in-memory for `x dev`. */
+export interface AdvisoryLock {
+  readonly key: string;
+  /** `false` means another process holds it — never block, never steal. */
+  tryAcquire(): Promise<boolean>;
+  release(): Promise<void>;
+  /**
+   * Let go WITHOUT asking: drop the session, synchronously, and wait for nothing. Closing the
+   * session releases the lock, so this is the release for a session that may be dead — an unlock
+   * statement on one is a wait nothing ends. Never calls `onLost`. A no-op when nothing is held.
+   */
+  abandon(): void;
+  /**
+   * Told when a lock this object HELD is gone without `release()` — its session died. Never for a
+   * release, never for a `tryAcquire` that answered `false`. Returns the unsubscribe. The holder
+   * must stop doing what the lock allowed: the database will give it to the next process that asks.
+   */
+  onLost(listener: (reason: string) => void): () => void;
+}
+
+/** Single-process default: correct for `x dev` and tests, useless across containers (by design). */
+export class InMemoryAdvisoryLock implements AdvisoryLock {
+  static readonly #held = new Set<string>();
+  readonly key: string;
+  #mine = false;
+
+  constructor(key: string) {
+    this.key = key;
+  }
+
+  async tryAcquire(): Promise<boolean> {
+    if (InMemoryAdvisoryLock.#held.has(this.key)) return false;
+    InMemoryAdvisoryLock.#held.add(this.key);
+    this.#mine = true;
+    return true;
+  }
+
+  async release(): Promise<void> {
+    if (!this.#mine) return;
+    InMemoryAdvisoryLock.#held.delete(this.key);
+    this.#mine = false;
+  }
+
+  abandon(): void {
+    if (!this.#mine) return;
+    InMemoryAdvisoryLock.#held.delete(this.key);
+    this.#mine = false;
+  }
+
+  /** A set in this process's own heap has no session to lose: the listener is never called. */
+  onLost(): () => void {
+    return () => undefined;
+  }
+}