@ultimat3/realtime 29.4.0 → 30.1.0

package/CLAUDE.md

@@ -98,7 +98,10 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   outside the lane, against the live window.
 - **`desynced` is a mark with a reader**: the next delivery serves a fresh snapshot out of the shared
   window and only then clears it. **`result.refill` is checked BEFORE the mark** — a guessed window
-  never clears a mark (`live-fanout.test.ts`).
+  never clears a mark (`live-fanout.test.ts`). **A quiet query has three more readers**
+  (`sync-drain.test.ts`): Bun's `drain` (`registry.repair`, which waits out a read in flight), a read
+  that lands, and the node's sweep (`registry.repairMarked`, on the idle interval), which also re-reads
+  a stale window that owes one, once a pass. Never out of a window stale or with a read not settled.
 - **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 — or a NEW producer after a known one — stales every window; `refillWindowInLane` replaces it.
@@ -131,6 +134,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   `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.
+- **A socket closed during its presence write takes the write back** (`joinPresence`, asked after the
+  awaits; `sync-frames.test.ts`).
 - 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
@@ -149,7 +154,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   late subscription and RAISES `X_TRANSPORT_UNAVAILABLE`. `#release` takes the reserved bridge, never
   a name.
 - **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
+  (`sync-origin.ts`): `allowedOrigins`, when declared, is the WHOLE list (`sec-fetch-site` unread); 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
@@ -183,6 +188,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   per table per node (`ProducerKinds`, `X_REALTIME_PRODUCER_CONFLICT`); the x dev bridge skips a
   claimed table (`isPublishedTable`). `ChangeEvent.table` is the relation on every producer.
 - **An error never renders a credential**: `parsePgUrl`/`parseNatsUrl` name the variable.
+- **`deviceSocket()`**: `wiki/Realtime.md#device-sockets`.
 
 ## Replication
 
@@ -214,6 +220,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 
 ## The page
 
+- **A timed re-read is `useQuery`'s `poll: pollEvery(ms)`** (`query-poll.ts`), non-live by type, through core's `visibleInterval`. Full rule: `docs/history/realtime.md`.
 - **One record store per PAGE (`record-store.ts`)**, keyed `type:key` with the SERVER's key
   (`live-record-type.ts`); the browser never derives one. SYNCED truth plus an OVERLAY of pending
   optimistic writes, REPLAYED over synced truth whenever it moves. Installed as core's `RecordSink` on
@@ -232,8 +239,8 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   routed; a port silent for `REAP_AFTER_BEATS` is reaped; each tab resubscribes from its OWN cursors.
   No `SharedWorker` → the in-page host runs the same engine over a `MessageChannel`.
 - **The socket is READ-ONLY (protocol 3)**. A write is `useMutation`: the twin into the overlay, then
-  `POST actionPath(name)` through core's `clientTransport` with an idempotency key; the answer's
-  records are adopted inside the transport call, before `settle`. An `ack` is only a refusal.
+  the stamped pin (`renderedActionPin`) or `POST actionPath(name)`, via `clientTransport`, keyed;
+  the answer's records are adopted inside the transport call, before `settle`. An `ack` is only a refusal.
   KNOWN offline (`knownOffline()`), it is queued with no POST and painted once on disk (#777).
 - **`LiveClient` holds no signal** — plain reads plus `onStatus` / `onChange`; hooks wrap them.
 - **An answer that did not carry a touched row keeps that row's overlay** until the server's next row
@@ -241,12 +248,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A catch-up read waits for the page's writes in flight over its types**
   (`RecordStore.afterWrites`): it lands once each is answered or echoed, within that bound; a row
   moved meanwhile is kept (#778).
-- **A frame names the write that produced it**: `records.write`, `patch.writes` (a live patch
-  one, a resume each it replays, off `RowPatch.write` in the ring) — `writeDigest(key)`, from a
-  REQUIRED `ChangeEvent.write: string | null`. `RecordStore.push` digests each overlay key first
-  (`record-names.ts`); `client-channels.ts` / `live-rows.ts` settle in the frame's own batch. A
-  non-digest is a protocol error, dropped on the bus. Partly confirmed rows go to
-  `OverlayEntry.confirmed`. `write-echo.test.ts`, `live-write-echo.test.ts`.
+- **A frame names the write that produced it** (`writeDigest(key)`, from a REQUIRED `ChangeEvent.write`; `write-echo.test.ts`). Full rule: `docs/history/realtime.md`.
 - `local(tx, input)` is pure and CONVERGENT: no I/O, no `Date.now()`, no `Math.random()`.
 - **One conflict vocabulary**: `ConflictPolicy` from `@ultimat3/core`, resolved by core's
   `resolveConflict(overlayRow, serverRow)` in `RecordStore.settle`. A server delete is not a conflict.
@@ -259,12 +261,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
   reader hears only keys it shows or keeps (history, 2026-10-29).
 - Every subscription handle is `Disposable`; `[Symbol.dispose]` IS the release. Type claims go in
   `type-pins.ts`.
-- **The outbox**: only `pending` is sendable; `drain()` is one chained pass at a time; `#epoch` is
-  bumped before the requeue scan, read every pass. `#persist` hands SNAPSHOTS by KEY; one tab drains
-  (`navigator.locks`), resetting a stored `inflight`. A `rescope` abandons the queue and bumps the
-  epoch synchronously; `enqueue` decides WHOSE queue before its first await
-  (`X_OFFLINE_QUEUE_ABANDONED`); `useMutation` fences its POST on its scope epoch. A refused disk is
-  warned `X_LOCAL_STORE_UNAVAILABLE`, never rejecting `ready`. An entry leaves disk at its ack.
+- **The outbox**: only `pending` is sendable, one chained `drain()` at a time, one tab drains (`navigator.locks`); a `rescope` abandons the queue (`X_OFFLINE_QUEUE_ABANDONED`). Full rule: `docs/history/realtime.md`.
 
 ## The client connection
 

package/README.md

@@ -2,6 +2,8 @@
 
 Three tiers, one ladder, one protocol. Climbing a rung is a config change, never a rewrite.
 
+`bun add @ultimat3/realtime` · guide: [Realtime](https://github.com/developerz-ai/ultimate/wiki/Realtime)
+
 ## The ladder
 
 | Tier | What it gives you | What it costs you |
@@ -84,10 +86,10 @@ class — stay on `.`.
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `syncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useRecordChanges`, `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| hooks | `.` | `useQuery` (and `pollEvery` for its `poll`), `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useRecordChanges`, `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
 | channel records, no replicator | `./server` | `recordPublisher` — an app's committed rows as channel `records`, sequenced per producer ([below](#channel-records-with-no-replicator)) |
 | channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
-| first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`, for an island that reads the store or the outbox: the boot's restore and the open outbox, capped (#506). An island taking only `useChannel` / `usePresence` / `useConnection` never awaits it and is never hidden |
+| first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`, for an island that reads the store or the outbox: the boot's restore and the open outbox, capped (#506). An island taking only `useChannel` / `usePresence` / `useConnection` never awaits it and is never hidden, nor is one taking `useQuery` / `useRecord` in an app that declares no `persist: true` entity |
 | offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `memoryLocalStore()` |
 | the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 
@@ -254,6 +256,10 @@ const runs = useRecords<Run>('runs', {                              // EVERY `ru
   throttleMs: 1_000,                                                // optional: at most once a second
 });
 const like = useMutation(LIKE_POST);                                // await like(input); like.pending
+// A ref names the primitive, never its URL: an action or query declared `http: { path, method }`
+// is reached where the server's `<meta name="ultimate-pins">` says (core's `renderedActionPin` /
+// `renderedQueryPin`), and a queued write keeps the pin it was sent under. A `:param` the input
+// cannot fill is `X_MUTATION_PATH_UNFILLED`, before anything is painted or sent.
 const connection = useConnection();                                 // .offline .online .reconnectAt .updateAvailable
 const writes = useMutationQueue();                                  // .pending .failed
 const outbox = useOutbox();                                         // .size — queued, not yet sent
@@ -279,6 +285,8 @@ same type `@ultimat3/ui` renders.
 |---|---|
 | A query ref is `{ name, live?, entity? }`, never the query VALUE | importing a `query()` drags its read path into the island (698,801 B measured) |
 | Lists hold keys; rows are the store's | a record updated by any answer or frame re-renders every list showing it, with no refetch |
+| A `useQuery` list is in ANSWER order | the envelope's `order[type]` where the server sent one — an object enumerates integer-like keys ascending, so an `integer()` keyed newest-first feed rendered oldest-first from `records[type]` alone — else `records[type]`'s key order |
+| A live `refetch` re-asks a REFUSED subscription | a refusal with no `retryAfterSeconds` stays `failed` on an open socket until it reconnects; `refetch` calls `LiveHandle.retry()` and settles on the node's next answer, so a pull-to-refresh does something in exactly that state. Any other live state settles at once: the socket is its refresh |
 | A list that must GROW with the store is `useRecords(type, { where?, order? })` | a `useQuery` list holds its own answer's keys and `useRecords(type, keys)` the keys it was given, so a record a channel's `records` frame adopts reaches neither. The whole-type form is the channel-records counterpart of a live window: `ready` from its first read, every record of the type the store holds (optimistic ones included), default order by key, and none evicted while it is held — a row it alone kept goes when the last reader of the type lets go (#680) |
 | An answer is the SAME object until what it shows moved | `useQuery`, `useRecord` and both `useRecords` forms hand back the previous answer — and its `data` array — while the status and every row object match: a refetch or poll that found the same rows, or a re-read after an unrelated change, re-runs nothing derived from it (Solid's `===`). A whole-type reader with `where` is not even TOLD of a record it neither shows nor would show: on a run page the viewer's alerts list stopped hearing the fleet's runs (180 of 200 frames, 0 its own) |
 | A busy feed is throttled by the reader, `useRecords(type, { throttleMs })` | the first change is told at once, a burst as ONE notification at the end of the period, the last always lands; `release()` drops what is owed. A live board on a phone took ten records a second, each a whole-board redraw: `throttleMs: 1000` tells it 21 times in 20 s instead of 200. Absent or `0`: every change, as before. A non-finite or fractional value is `X_INVARIANT`; `schedule` injects the timer in a test |
@@ -288,6 +296,7 @@ same type `@ultimat3/ui` renders.
 | **No `solid-js` import.** Each bundle installs its own `SignalFactory` | every island carries its own solid-js; a signal from another bundle is invisible to its effects |
 | Every member is a **getter**, every result an **accessor** | a value snapshotted at hook time never re-renders |
 | `input` is read **once** | nothing here re-runs it; a changed input is a new `useQuery` |
+| A timed re-read is `useQuery(ref, input, { poll: pollEvery(ms) })` | non-live refs only (a live ref refuses it by type: `LiveQueryOptions`); `refetch` through core's `visibleInterval`, so a hidden tab, a lost session and `release()` all stop it. A value, not a number: `useQuery` never references the timer, so only an island importing `pollEvery` carries it (the reference like control rose 39,210 → 41,477 B across wave 5a, nearly all of it this, 2026-11-05) |
 | The caller owns `release()` / `using` | this layer does not know what a mount is |
 
 **A server render** (no install, no DOM) answers `pending`, reports online and creates no page
@@ -382,7 +391,7 @@ wire.
 | Ceiling | Default | Option | Refused with |
 |---|---|---|---|
 | concurrent sockets on this node | 250,000 | `syncNode({ maxConnections })` | `503` + `retry-after-ms`, the same shed as the accept budget |
-| inbound bytes per frame | 256 KiB | `syncNode({ maxFrameBytes })` | the socket, by `Bun.serve`'s `maxPayloadLength` |
+| inbound bytes per frame | 256 KiB | `syncNode({ maxFrameBytes })` | a `1009` close, by `Bun.serve`'s `maxPayloadLength` and by the node itself — a listener shared with a `deviceSocket()` takes the widest mount's limit |
 | inbound frames per socket | 64/s, burst 256 | `syncNode({ maxFramesPerSecond, frameBurst })` | `X_FRAME_RATE_LIMIT` |
 | live subscriptions per socket | 128 | `new LiveQueryRegistry({ maxPerSocket })` | `X_SUBSCRIPTION_LIMIT` |
 | live subscriptions per actor (anonymous: per resolved client address), across its sockets | 1,000 (`DEFAULT_MAX_PER_ACTOR`) | `new LiveQueryRegistry({ maxPerActor })`; the boot passes `realtime.maxSubscriptionsPerActor` | `X_SUBSCRIPTION_LIMIT` |
@@ -480,7 +489,7 @@ is admitted is decided in `sync-origin.ts`:
 | Admitted | When |
 |---|---|
 | no `Origin` header | always — RFC 6455 has every browser send one, so its absence is not a browser |
-| `syncNode({ allowedOrigins })`, compared exactly (scheme, host, port) | when any is declared. The declaration is the WHOLE list (24.0.0): the origin the node was reached on is no longer admitted beside it, because that origin is read off the `Host` header and a sibling subdomain pointed at the node would be "its own" |
+| `syncNode({ allowedOrigins })`, compared exactly (scheme, host, port) | when any is declared. The declaration is the WHOLE list (24.0.0): the origin the node was reached on is no longer admitted beside it, because that origin is read off the `Host` header and a sibling subdomain pointed at the node would be "its own". `sec-fetch-site` is not read beside it, for the same reason |
 | 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`
@@ -514,6 +523,16 @@ engine (one per origin, in the `SharedWorker`) keeps none of it across pages: a
 the node is down dials at once on a fresh curve, and the last page leaving forgets the target, so
 the next build's page never dials with the old build id.
 
+### A live read joins its caller's trace
+
+`As of 2026-11`. A `subscribe` frame may carry `traceparent` (additive, no protocol bump), from
+`LiveClient({ traceparent: () => … })`, asked per frame. The node keeps the newest subscriber's on
+the window: the snapshot a subscribe causes runs in `live.snapshot <query>`, a child of it; a
+re-read a change forces runs in `live.rerun <query>`, linked to it and parented on the change
+(`@ultimat3/query`'s `traceLiveRead`). A non-string or oversized value is dropped at decode and an
+unparsable one ignored — telemetry never fails a subscribe. The page socket sends none: a browser
+holds no ambient trace.
+
 ### Liveness: `heartbeatMs`
 
 A half-open socket — the TCP connection is dead and no `close` ever fires — is invisible to the
@@ -874,6 +893,26 @@ principal.
   (`maxRowsPerType` / `maxRowsByType`, least recently written first). An eviction is a change like any other: the
   persister deletes the row from disk with it. Persisting it (IndexedDB) is plan 101 slice 12.
 
+## Device sockets
+
+`deviceSocket({ path, resolveToken, onFrame, maxSocketsPerActor?, heartbeatMs?, allowedOrigins? })`
+— a declared socket for a non-browser client, from `./server`. A factory over `route`: the value is
+a websocket mount plus `request(ctx, deviceId, frame, { deadlineMs })`, which reaches one connected
+device from any process over the bus, scoped to `ctx.actor.orgId`. `deviceAgent({ url, token,
+onRequest })` is the Bun client. Every rule (credential, caps, frame limit, beat, drain, codes):
+[wiki/Realtime.md#device-sockets](../../wiki/Realtime.md#device-sockets).
+
+| File | Job |
+|---|---|
+| `device-socket.ts` | the declaration, its screen, the registry, `request()` and `attach()` |
+| `device-upgrade.ts` | the upgrade decision: origin, bearer token under a deadline, expiry, cap |
+| `device-host.ts` | the sockets one node holds: frames, the lane, the sweep, the drain |
+| `device-bus.ts` | where a device is and how a request reaches it and comes back |
+| `device-wire.ts` | both hops' frames and the frame limit |
+| `device-agent.ts` | the device's half, on Bun |
+| `device-errors.ts` | its refusals |
+| `device-declarer.ts` | the file that called `deviceSocket()`, so `x dev` refuses another module taking a path |
+
 ## Errors
 
 `X_TOPIC_FORBIDDEN` · `X_SUBSCRIPTION_LIMIT` · `X_SUBSCRIPTION_ID_TAKEN` ·
@@ -883,7 +922,8 @@ principal.
 `X_REALTIME_UNINSTALLED` · `X_SYNC_UNCONFIGURED` · `X_RECORD_REJECTED` ·
 `X_LIVE_SERVER_RENDER` · `X_LIVE_QUERY_UNKNOWN` ·
 `X_LIVE_REPLICA_IDENTITY` ·
-`X_SOCKET_UNAUTHENTICATED` · `X_SOCKET_AUTH_UNAVAILABLE` · `X_NOT_IMPLEMENTED` ·
+`X_SOCKET_UNAUTHENTICATED` · `X_SOCKET_AUTH_UNAVAILABLE` ·
+`X_DEVICE_OFFLINE` · `X_DEVICE_REQUEST_TIMEOUT` · `X_DEVICE_FRAME_TOO_LARGE` · `X_NOT_IMPLEMENTED` ·
 `X_TIMEOUT`
 
 `X_NOT_IMPLEMENTED` and `X_TIMEOUT` are **borrowed** from `@ultimat3/core`, which owns and titles

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "realtime",
+    "websocket",
+    "local-first",
+    "sync"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Realtime",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -40,10 +50,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/entity": "29.4.0",
-    "@ultimat3/policy": "29.4.0",
-    "@ultimat3/query": "29.4.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/entity": "30.1.0",
+    "@ultimat3/policy": "30.1.0",
+    "@ultimat3/query": "30.1.0",
     "nats": "2.29.3"
   }
 }

package/src/client-contract.ts

@@ -37,6 +37,12 @@ export interface LiveHandle<R extends object = Row> extends Disposable {
   cursor(): LiveCursor | null;
   /** What the node answered when it refused the subscription; `undefined` unless `failed`. */
   error(): unknown;
+  /**
+   * Ask the node again, now, for a `failed` subscription on an open socket — a refusal with no
+   * stated delay stays refused until the socket itself reconnects. `true` = a subscribe went out
+   * and the state is `loading`; `false` = nothing to retry, or no socket (the reopen replays it).
+   */
+  retry(): boolean;
   /** Called after anything the reads above answer has moved. Returns the unsubscribe. */
   onChange(listener: () => void): () => void;
   unsubscribe(): void;
@@ -71,6 +77,12 @@ export interface LiveClientOptions {
   readonly heartbeatMs?: number;
   /** Where a failure nobody awaits is reported. Defaults to `console.error`. */
   readonly onError?: (error: unknown) => void;
+  /**
+   * The W3C `traceparent` a live subscribe carries, asked at each `subscribe` frame, so the read
+   * it causes joins the caller's trace. Absent, or answering `undefined`, sends none: a browser
+   * has no ambient trace, and the node then starts the read's own.
+   */
+  readonly traceparent?: () => string | undefined;
   /**
    * A channel's catch-up read, re-run on `replay-gap` or a new epoch: the named query, answering its
    * records UNADOPTED for the channel book to adopt with the frames held behind the read.

package/src/client.ts

@@ -300,6 +300,7 @@ export class LiveClient {
       state: (): LiveState => registration.state,
       cursor: (): LiveCursor | null => registration.cursor,
       error: (): unknown => registration.error,
+      retry: () => this.#retryNow(registration),
       onChange: (listener) => {
         listeners.add(listener);
         return () => {
@@ -324,6 +325,7 @@ export class LiveClient {
   }
 
   #sendSubscribe(registration: Registration): void {
+    const traceparent = this.#options.traceparent?.();
     this.#send({
       type: 'subscribe',
       v: PROTOCOL_VERSION,
@@ -335,6 +337,7 @@ export class LiveClient {
         input: registration.input,
         cursor: registration.cursor,
       },
+      ...(traceparent === undefined ? {} : { traceparent }),
     });
   }
 
@@ -361,23 +364,30 @@ export class LiveClient {
 
   /**
    * Ask again once the node's stated delay has passed — a rate-limited subscribe, whose bucket
-   * refills. Only while the registration is still held, still refused and the socket still up:
-   * anything else and the reopen's replay, or the unsubscribe, already decided its fate.
+   * refills. `#retryNow` holds it to a registration still held and refused on an open socket.
    */
   #retryLater(registration: Registration, afterMs: number): void {
     this.#retries.get(registration.sid)?.();
     const cancel = (this.#options.scheduler ?? timeoutScheduler)(() => {
       this.#retries.delete(registration.sid);
-      if (this.#registrations.get(registration.sid) !== registration) return;
-      if (!this.#connected || registration.state !== 'failed') return;
-      registration.state = 'loading';
-      registration.error = undefined;
-      registration.notify();
-      this.#sendSubscribe(registration);
+      this.#retryNow(registration);
     }, afterMs);
     this.#retries.set(registration.sid, cancel);
   }
 
+  /** The re-subscribe itself, timed or asked for (`LiveHandle.retry`). Cancels a pending timer. */
+  #retryNow(registration: Registration): boolean {
+    const held = this.#registrations.get(registration.sid) === registration;
+    if (!held || !this.#connected || registration.state !== 'failed') return false;
+    this.#retries.get(registration.sid)?.();
+    this.#retries.delete(registration.sid);
+    registration.state = 'loading';
+    registration.error = undefined;
+    registration.notify();
+    this.#sendSubscribe(registration);
+    return true;
+  }
+
   /** The opening frame, and the heartbeat's. One shape, because it makes one claim: I am here. */
   #hello(): Frame {
     return {

package/src/device-agent.ts

@@ -0,0 +1,174 @@
+// The device's half of a `deviceSocket()`, for an agent written on Bun: dial with the bearer token,
+// beat at the interval the node names, answer `request` frames, and redial on realtime's one
+// jittered backoff — or at the slot a draining node's `reconnect` frame assigns.
+
+import { reportError } from '@ultimat3/core';
+import { bytesOverLimit, type DeviceInbound, decodeNodeFrame } from './device-wire';
+import type { JsonValue } from './json';
+import {
+  type BackoffPolicy,
+  defaultBackoff,
+  policyDelay,
+  type Rng,
+  type Scheduler,
+  timeoutScheduler,
+} from './thundering-herd';
+
+/** As much of a websocket as the agent drives — Bun's `WebSocket` fits. */
+export interface AgentSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: (() => void) | null;
+  onmessage: ((event: { readonly data: unknown }) => void) | null;
+  onclose: (() => void) | null;
+}
+
+export type AgentDial = (url: string, headers: Readonly<Record<string, string>>) => AgentSocket;
+
+/**
+ * Bun's `WebSocket` takes `{ headers }` and sends them on the upgrade — the thing a browser's
+ * cannot do, and why a device token rides `Authorization` rather than the URL. The DOM lib this
+ * repo also loads types the constructor without that overload (`Bun.WebSocketOptions` exists only
+ * when it is absent), so the one call is typed by the shape Bun really accepts.
+ */
+type HeaderedWebSocket = new (
+  url: string,
+  options: { readonly headers: Readonly<Record<string, string>> },
+) => AgentSocket;
+
+const bunDial: AgentDial = (url, headers) =>
+  new (WebSocket as unknown as HeaderedWebSocket)(url, { headers });
+
+export interface DeviceAgentOptions {
+  /** `wss://app.example.com/link` — the declaration's path on the app's origin. */
+  readonly url: string;
+  /** Asked on every dial, so a refreshed token is the next connection's. */
+  readonly token: () => string | Promise<string>;
+  /** The answer to a node's `request(ctx, deviceId, frame)`. */
+  readonly onRequest: (frame: JsonValue) => Promise<JsonValue> | JsonValue;
+  /** What `onFrame` on the node answered, and anything else it pushes. */
+  readonly onFrame?: ((frame: JsonValue) => void) | undefined;
+  readonly backoff?: BackoffPolicy | undefined;
+  readonly rng?: Rng | undefined;
+  readonly schedule?: Scheduler | undefined;
+  readonly dial?: AgentDial | undefined;
+}
+
+export interface DeviceAgent {
+  readonly connected: boolean;
+  /** One frame for the node's `onFrame`. `false` when no socket is open to carry it. */
+  send(frame: JsonValue): boolean;
+  /** Closes for good: no redial. */
+  close(): void;
+}
+
+export function deviceAgent(options: DeviceAgentOptions): DeviceAgent {
+  const schedule = options.schedule ?? timeoutScheduler;
+  const backoff = options.backoff ?? defaultBackoff;
+  const dial = options.dial ?? bunDial;
+  let socket: AgentSocket | null = null;
+  let open = false;
+  let closed = false;
+  let attempt = 0;
+  let cancelBeat: () => void = () => undefined;
+  let cancelRedial: (() => void) | null = null;
+
+  const write = (frame: DeviceInbound): boolean => {
+    const text = JSON.stringify(frame);
+    if (!open || socket === null || bytesOverLimit(text) !== null) return false;
+    socket.send(text);
+    return true;
+  };
+
+  const beat = (everyMs: number): void => {
+    cancelBeat();
+    cancelBeat = schedule(() => {
+      write({ type: 'beat' });
+      beat(everyMs);
+    }, everyMs);
+  };
+
+  const redialIn = (ms: number): void => {
+    if (closed || cancelRedial !== null) return;
+    cancelRedial = schedule(() => {
+      cancelRedial = null;
+      void connect();
+    }, ms);
+  };
+
+  const answer = async (id: string, frame: JsonValue): Promise<void> => {
+    try {
+      write({ type: 'response', id, frame: await options.onRequest(frame) });
+    } catch (error) {
+      // No answer is the answer: the node's deadline tells its caller, with the code that says so.
+      reportError(error, { source: 'realtime', scope: { operation: 'device.agent_request' } });
+    }
+  };
+
+  const receive = (current: AgentSocket, data: unknown): void => {
+    if (current !== socket || typeof data !== 'string') return;
+    const frame = decodeNodeFrame(data);
+    if (frame === undefined) return;
+    if (frame.type === 'hello') beat(frame.heartbeatMs);
+    else if (frame.type === 'request') void answer(frame.id, frame.frame);
+    else if (frame.type === 'frame') options.onFrame?.(frame.frame);
+    else if (frame.type === 'reconnect') {
+      // The node's slot, not the backoff: the spread is what keeps a fleet restart off one node.
+      attempt = 0;
+      cancelRedial?.();
+      cancelRedial = null;
+      redialIn(frame.afterMs);
+      current.close(4002, 'reconnect');
+    }
+  };
+
+  async function connect(): Promise<void> {
+    if (closed) return;
+    let current: AgentSocket;
+    try {
+      const token = await options.token();
+      // `close()` may have landed while the token was fetched: a dial now is a socket, and a beat,
+      // that nothing would ever close.
+      if (closed) return;
+      current = dial(options.url, { authorization: `Bearer ${token}` });
+    } catch (error) {
+      reportError(error, { source: 'realtime', scope: { operation: 'device.agent_dial' } });
+      attempt += 1;
+      redialIn(policyDelay(backoff, attempt, options.rng));
+      return;
+    }
+    socket = current;
+    current.onopen = () => {
+      if (current !== socket) return;
+      open = true;
+      attempt = 0;
+    };
+    current.onmessage = (event) => receive(current, event.data);
+    current.onclose = () => {
+      if (current !== socket) return;
+      socket = null;
+      open = false;
+      cancelBeat();
+      attempt += 1;
+      redialIn(policyDelay(backoff, attempt, options.rng));
+    };
+  }
+
+  void connect();
+  return {
+    get connected() {
+      return open;
+    },
+    send: (frame) => write({ type: 'frame', frame }),
+    close: () => {
+      closed = true;
+      cancelBeat();
+      cancelRedial?.();
+      cancelRedial = null;
+      const current = socket;
+      socket = null;
+      open = false;
+      current?.close(1000, 'closed');
+    },
+  };
+}