@ultimat3/realtime 21.0.0 → 22.1.0

package/README.md

@@ -69,22 +69,53 @@ class — stay on `.`.
 
 | Concern | Entry | Export |
 |---|---|---|
-| tier 1 | `./server` | `topic`, `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
+| tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
 | tier 2 | `./server` | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
 | replication | `./server` | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `entityRow`, `changeLsn`, `commitPositionOf` |
+| the in-process change source | `./server` | `startLiveReplicator` — a repository's own writes as `ChangeEvent`s, for the embedded database `x dev` runs on (PGlite has no walsender). Moved from `@ultimat3/testing`, which no longer re-exports it |
 | fanout | `./server` | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
 | the bus, behind `NatsTransport` | `./server` | the port — `NatsClient`, `NatsMessage`, `NatsSubscription`, `NatsConnect`, `NatsTarget`, `parseNatsUrl` — plus `openNatsClient` (the `nats` adapter), `NatsKvSet`, `ensureKvBucket`, `kvGet`/`kvLast`/`kvWrite`, `assertBucket`, `encodeToken`/`decodeToken`, and `FakeNatsBroker`/`fakeNatsConnect` for tests |
-| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `backoffDelay`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
+| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
 | the page's record store | `.` | `RecordStore` — one record per `type:key`, synced truth plus the optimistic overlay — `recordKey`, `LocalTx`, `RowWindows`, `applyPatches`/`orderAfterPatches` |
 | the outbox | `.` | `OfflineQueue`, `MemoryQueueStore` — replayed over HTTP from plan 101 slice 12. The conflict vocabulary is `ConflictPolicy` from `@ultimat3/core`; realtime declares none |
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `createSyncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
 | hooks | `.` | `useQuery`, `useRecord`, `useMutation`, `useMutationQueue`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
-| channels | `.` | `channel`, `topic`, `readPresence`, the channel frame types |
+| channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
 | offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `MemoryLocalStore` |
 | the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 
+## `channelRef` — a channel an island can hold
+
+A channel has two halves, and they live in two files so a browser chunk never bundles an entity or
+a policy. `channelRef(name, { params, catchUp })` is the **client** half: the name, the ordered
+params and the catch-up read — nothing else. The server declares the records and who may join on
+**the same ref** with `channel(ref, { … })`, so the name and the params are written once.
+
+```ts
+// app/posts/channel-ref.ts — imported by islands
+import { channelRef } from '@ultimat3/realtime';
+
+export const ORG_POSTS = channelRef('org-posts', {
+  params: ['orgId'],
+  catchUp: { name: 'orgPosts' },   // the query a client re-runs on `replay-gap` or a new epoch
+});
+
+// The one topic spelling both halves use.
+ORG_POSTS.topic({ orgId: 'org_1' });   // 'org-posts.org_1'
+```
+
+The server half, in its own file, names the entity and the policy on the same ref —
+`channel(ORG_POSTS, { records: [posts], policy: feedRead })` — and an island subscribes with
+`useChannel(ORG_POSTS, { orgId })`.
+
+`ref.topic(params)` is the one spelling of the topic both halves use (`org-posts.<orgId>`), and
+`bun run channel-literals` refuses a hand-built topic anywhere else. A bad name or a repeated param
+is `X_CHANNEL_DECLARATION_INVALID` at declaration. `catchUp` is read on every access, so a query
+whose name `registerQueries()` stamps at boot is picked up. The reference app's
+[`app/posts/channel-ref.ts`](../../examples/dummy/apps/web/app/posts/channel-ref.ts) is the idiom.
+
 ## The hooks
 
 One record store and one socket per **page**, on `globalThis`: every island is its own bundle, so a
@@ -285,10 +316,26 @@ never stumbled into.
 On drain, `drainPlan()` gives every client its own jittered slot in a spread window and the node
 sends a `reconnect` frame carrying that delay — clients redistribute instead of stampeding.
 `AcceptBudget` is the receiving node's token bucket, and a refusal always carries a retry delay,
-because refusing without one just moves the herd next door.
+because refusing without one just moves the herd next door. **A token is reserved before `authenticate`
+and refunded on every exit that takes no socket** (22.1.0): a 401, an authenticator that throws, a
+shed after it, an upgrade that did not take. Reserved first, so a reconnect herd reaches the token
+service bounded by the burst; refunded, because spent-and-kept, one client dialling with no
+credential drained the bucket and every signed-in reconnect behind it was shed. Not per client IP:
+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`
+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.
 
 The client dials itself back. A closed socket arms one timer — the node's delay when a `reconnect`
-frame assigned one, otherwise `backoffDelay()` — and that timer calls `connect()`, which re-subscribes
+frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `BackoffPolicy` — and that timer calls `connect()`, which re-subscribes
 every registration **and re-announces every topic**. Topic membership is state on the node's socket
 and `hello` carries none of it, so without that half a channel goes silent from the first reconnect
 onwards while its handler is still installed — and its presence membership is swept, because
@@ -337,7 +384,8 @@ wire twice by a reconnect that raced an ack.
 | Backpressure **declines**, it does not fail | over `MAX_BUFFERED_BYTES` (1 MiB, the node's `backpressureLimit` at the other end of the same socket) the sender throws `X_TRANSPORT_UNAVAILABLE`, the mutation stays pending and the next drain resumes there. `ClientSocket.bufferedAmount` is optional; a socket that does not report it is treated as never backed up |
 | Delivery is therefore at least once | every mutation carries an idempotency key — the `key` argument, or `<mutator>:<uuid>` — and the resend carries the same one |
 | A lost connection **cancels the pass it interrupted** | the lane orders passes against each other, but a socket death is not a pass and cannot reach one parked inside `send`. `requeueInflight()` bumps a connection epoch; a pass whose epoch went stale returns and leaves the rest `pending`. Without it the parked pass resumed and marked everything behind it `inflight` for a dead socket — never re-sent (`inflight` is not sendable) and never acked |
-| The store is handed a **snapshot**, never the live entries | `QueueStore.save` is a durable write and may await before it reads; given the array itself it persists a status that was never true when it was called |
+| The store is handed **snapshots, by key**, never the live entries or the whole queue | `QueueStore.write` is a durable write and may await before it reads; given an entry itself it persists a status that was never true when it was called. By key, because two tabs of one user share the store and a whole-queue save let the last tab erase the other's write |
+| One tab drains at a time, and drains what every tab queued | the outbox's replay runs under the Web Lock `ultimate-outbox:<principal>` and re-reads the queue first, so a write another tab queued is sent, in order, and a stored `inflight` from a closed page goes back to `pending` |
 
 ### Limits, stated plainly
 
@@ -474,7 +522,11 @@ wire twice by a reconnect that raced an ack.
   (SCRAM-SHA-256, in-band TLS, CopyBoth), no driver dependency. It preflights `wal_level`, 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
+  slot as it goes so the WAL does not grow without bound. **The publication is ensured, not merely
+  checked** (`pg-publication.ts`): missing, it is created `FOR TABLE` every entity table; present,
+  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.
 - **`selectChangeFeed(env, { entities })` decides which feed a boot installs** — same law
   `selectMailDriver` follows: an unset variable means the embedded default. It returns `{ feed,
@@ -487,15 +539,38 @@ wire twice by a reconnect that raced an ack.
   wrong database's WAL would be silently wrong forever. `REPLICATION_SLOT` (default `x_replicator`)
   and `REPLICATION_PUBLICATION` (default `x_changes`) name the slot and publication, both checked
   against `[a-z_][a-z0-9_]*` before they reach a replication command.
+- **TLS follows libpq's `sslmode`** (`pg-tls.ts`, 22.1.0): `disable`; `allow`, `prefer` (the
+  default) and `require` encrypt and verify **nothing**; `verify-ca` checks the chain;
+  `verify-full` the chain and the host name. `sslrootcert=<path>` is the only trust anchor when
+  set (and turns `require` into `verify-ca`, as libpq does); `sslrootcert=system` means the runtime
+  store and `verify-full`. With neither, the runtime store is used — it honours
+  `NODE_EXTRA_CA_CERTS`; libpq's `~/.postgresql/root.crt` is never read. `allow` is served as
+  `prefer` (TLS offered first), never cleartext first. The runtime never rejects on its own
+  (`rejectUnauthorized: false`); the handshake's report is judged per mode, and a failure is
+  `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.
+- **`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
+  the walsenders. Run the replicator against a cluster dedicated to the app, or give it its own role
+  through `REPLICATION_URL` with `pg_hba.conf`'s `replication` lines restricted to it — never grant
+  `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).
 - **`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.
   `InMemoryAdvisoryLock` remains the single-process default for `x dev` and tests.
-- **`selectTransport(env)` decides which transport a boot fans out on** — the same law again, and
-  the only place that reads `NATS_URL`. It returns `{ transport, mode, detail, bucket,
-  presenceTtlMs, connect }`: unset → `InProcessTransport` and `mode: 'embedded'`, set → a
-  `NatsTransport` on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so two apps on one
-  cluster do not share one presence namespace), validated here rather than on first connect.
+- **`selectTransport(env, realtime)` decides which transport a boot fans out on** — and since
+  22.0.0 the CONFIG decides it, not the environment: `realtime` is `app.config.ts`'s
+  `{ transport, urlEnv }`. It returns `{ transport, mode, detail, bucket, presenceTtlMs, connect }`:
+  `'memory'` → `InProcessTransport` and `mode: 'embedded'`; `'nats'` → a `NatsTransport` dialling
+  the variable `urlEnv` names, on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so
+  two apps on one cluster do not share one presence namespace), validated here rather than on
+  first connect. Both mismatches refuse with `X_CONFIG_INVALID`: `'nats'` with that variable unset,
+  and `'memory'` with `NATS_URL` (or the named variable) set — an operator who set one expected
+  fanout across nodes. Until 22.0.0 `NATS_URL` alone decided and both keys were read by nothing.
   `presenceTtlMs` comes back with it because the bucket's whole-stream age limit was derived from
   it — a `PresenceRegistry` given a different number would report members leaving that never left.
   Selection is pure; `connect()` is the dial, so an unreachable bus fails at boot.
@@ -517,18 +592,17 @@ 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`, 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.
+- **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
+  `pg-identity-window.live.test.ts` (out of the filter, into it, delete, a row never held).
+  `preflight`'s fourth question, **before** `pg_create_logical_replication_slot`, names only the
+  entity tables with no identity (`NOTHING`, or `DEFAULT` with no primary key), whose `UPDATE` and
+  `DELETE` Postgres refuses once published: a **coded warning**, `X_LIVE_REPLICA_IDENTITY`, fix
+  `ALTER TABLE <t> REPLICA IDENTITY FULL;` per table — not a throw. Until 22.1.0 it named every
+  table not on FULL, on every boot. `ReplicationStreamStats.partialBefore` still counts changes off
+  a non-FULL relation — a volume figure, not a correctness one.
 - The record store is **per page**, in memory, and it is not a query cache: it answers "what is
   record X now", never "have I run this query before". Nothing evicts by time or size — a record
   lives as long as something holds it. Persisting it (IndexedDB) is plan 101 slice 12.
@@ -548,8 +622,9 @@ wire twice by a reconnect that raced an ack.
 `X_NOT_IMPLEMENTED` and `X_TIMEOUT` are **borrowed** from `@ultimat3/core`, which owns and titles
 them — `REALTIME_BORROWED_ERROR_CODES`. Everything else on that list is realtime's own.
 
-Topics deny by default: a topic with no matching guard is forbidden. An authz hole is not a config
-option someone forgot to set.
+Topics deny by default: a topic no `channel()` declares is forbidden, and a `channel()` with no
+`policy` is refused at declaration (`X_CHANNEL_DECLARATION_INVALID`) — a public channel writes
+`policy: allow('public')`. An authz hole is not a config option someone forgot to set.
 
 An upgrade `authenticate` refuses is `X_SOCKET_UNAUTHENTICATED` (401) and one it *could not decide*
 is `X_SOCKET_AUTH_UNAVAILABLE` (503). Two codes, because the two have opposite instructions: the
@@ -568,3 +643,32 @@ The fix is `x queries list --json`, and the name the client sent is echoed back
 never is.
 
 `As of 2026-07`: tiers 1–2 target v1, tier 3 targets v2.
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `CursorStaleError` (extends `RealtimeError`) | `X_CURSOR_STALE` | `src/page-errors.ts` |
+| `FrameRateLimitError` (extends `RealtimeError`) | `X_FRAME_RATE_LIMIT` | `src/errors.ts` |
+| `LiveQueryUnknownError` (extends `RealtimeError`) | `X_LIVE_QUERY_UNKNOWN` | `src/errors.ts` |
+| `LiveRowUnidentifiedError` (extends `RealtimeError`) | `X_LIVE_ROW_UNIDENTIFIED` | `src/errors.ts` |
+| `NotImplementedError` (extends `RealtimeError`) | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `ProtocolVersionError` (extends `RealtimeError`) | `X_PROTOCOL_VERSION` | `src/page-errors.ts` |
+| `RealtimeError` | any `RealtimeErrorCode` — `REALTIME_ERROR_CODES`; the base of every other class here, thrown directly for a code none of them covers | `src/realtime-error.ts` |
+| `RealtimeUninstalledError` (extends `RealtimeError`) | `X_REALTIME_UNINSTALLED` | `src/page-errors.ts` |
+| `RebaseConflictError` (extends `RealtimeError`) | `X_REBASE_CONFLICT` | `src/page-errors.ts` |
+| `RecordRejectedError` (extends `RealtimeError`) | `X_RECORD_REJECTED` | `src/page-errors.ts` |
+| `ReplicaIdentityError` (extends `RealtimeError`) | `X_LIVE_REPLICA_IDENTITY` | `src/replication-errors.ts` |
+| `ReplicationFailedError` (extends `RealtimeError`) | `X_REPLICATION_FAILED` | `src/replication-errors.ts` |
+| `ReplicationProtocolError` (extends `RealtimeError`) | `X_REPLICATION_PROTOCOL` | `src/replication-errors.ts` |
+| `ReplicatorSlotHeldError` (extends `RealtimeError`) | `X_REPLICATOR_SLOT_HELD` | `src/replication-errors.ts` |
+| `ServerRenderLiveError` (extends `RealtimeError`) | `X_LIVE_SERVER_RENDER` | `src/page-errors.ts` |
+| `SubscriptionLimitError` (extends `RealtimeError`) | `X_SUBSCRIPTION_LIMIT` | `src/errors.ts` |
+| `SyncUnconfiguredError` (extends `RealtimeError`) | `X_SYNC_UNCONFIGURED` | `src/page-errors.ts` |
+| `TopicForbiddenError` (extends `RealtimeError`) | `X_TOPIC_FORBIDDEN` | `src/errors.ts` |
+| `TransportProtocolError` (extends `RealtimeError`) | `X_TRANSPORT_PROTOCOL` | `src/errors.ts` |
+| `TransportUnavailableError` (extends `RealtimeError`) | `X_TRANSPORT_UNAVAILABLE` | `src/errors.ts` |
+| `WindowReadTimeoutError` (extends `RealtimeError`) | `X_TIMEOUT` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "21.0.0",
+  "version": "22.1.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": "21.0.0",
-    "@ultimat3/entity": "21.0.0",
-    "@ultimat3/query": "21.0.0",
+    "@ultimat3/core": "22.1.0",
+    "@ultimat3/entity": "22.1.0",
+    "@ultimat3/query": "22.1.0",
     "nats": "2.29.3"
   }
 }

package/src/changefeed.ts

@@ -11,7 +11,13 @@ import type { PgTarget } from './pg-socket';
 import type { PgStream } from './pg-wire';
 import type { Rng } from './thundering-herd';
 
-export type ChangeOp = 'insert' | 'update' | 'delete';
+/**
+ * `truncate` carries no row — `before` and `after` are both `null` — and means every row of the
+ * relation is gone. A window cannot be patched from it, only re-read; a channel's members are told
+ * to re-read (`replay-gap`). It was decoded and dropped, so with the recommended `FOR ALL TABLES`
+ * publication every window and every client kept the truncated rows forever.
+ */
+export type ChangeOp = 'insert' | 'update' | 'delete' | 'truncate';
 
 export interface ChangeEvent<R extends Row = Row> {
   /** Entity name, not table name — the matcher's dependency sets are declared in entity terms. */

package/src/channel-authz.ts

@@ -2,7 +2,7 @@
 // the channel's own loader answered. Through `@ultimat3/query`'s `guard`, the package's one authz
 // seam — the same call `policy-gate.ts` makes for a live query.
 
-import type { Actor, Ctx } from '@ultimat3/core';
+import { type Actor, type Ctx, createContext, runWithContext } from '@ultimat3/core';
 import { guard, QueryDeniedError } from '@ultimat3/query';
 import type { Channel } from './channel-decl';
 import { TopicForbiddenError } from './errors';
@@ -18,10 +18,17 @@ export async function authorizeChannel(
   topic: string,
   params: Readonly<Record<string, string>>,
 ): Promise<void> {
-  if (channel.policy === undefined) return;
-  const row = channel.row === undefined ? null : await channel.row({ params, ctx });
+  // The loader and the rule run AS the subscriber, never as the node. Under the node's context — no
+  // actor, no tenant — a repository read inside the loader was scoped by nothing but what the
+  // loader happened to name, and `@ultimat3/entity`'s tenancy seam had no actor to hold it to.
+  // Services are rebuilt for this actor by `createContext`, the rule `withChildContext` follows.
+  const scoped = actor === null ? ctx : subscriberContext(ctx, actor);
+  const row =
+    channel.row === undefined
+      ? null
+      : await runWithContext(scoped, async () => await channel.row?.({ params, ctx: scoped }));
   try {
-    guard(channel.policy, { actor, input: params, row, ctx, query: channel.name }, 'live');
+    guard(channel.policy, { actor, input: params, row, ctx: scoped, query: channel.name }, 'live');
   } catch (error) {
     if (!(error instanceof QueryDeniedError)) throw error;
     throw new TopicForbiddenError({
@@ -31,3 +38,15 @@ export async function authorizeChannel(
     });
   }
 }
+
+/** The node's context, re-made for one subscriber: same deploy, role and clock, their actor. */
+function subscriberContext(node: Ctx, actor: Actor): Ctx {
+  return createContext({
+    actor,
+    role: node.role,
+    buildId: node.buildId,
+    clock: node.clock,
+    locale: node.locale,
+    tz: node.tz,
+  });
+}

package/src/channel-decl.ts

@@ -43,10 +43,12 @@ function projectionFor(name: string, entity: ChannelEntity): RecordProjection {
 export interface ChannelServerInit {
   /**
    * Evaluated on subscribe: the params are the input, and `row` is what the loader below answered
-   * (`null` without one). Omitted = any socket may join. Records are NOT gated per row — the topic's
+   * (`null` without one). REQUIRED, as on an `action` and a `query`: it was optional, and an omitted
+   * one let any socket — anonymous included — join with any param and receive every committed row.
+   * A public channel says so with `allow('public')`. Records are NOT gated per row — the topic's
    * params are the scope, so a channel that must hide rows is declared narrower.
    */
-  readonly policy?: QueryPolicy;
+  readonly policy: QueryPolicy;
   /**
    * The subject the policy decides about, loaded by the SURFACE before the rule runs — the same
    * split an action's `row:` makes, because a rule is synchronous and membership is a read.
@@ -69,7 +71,7 @@ export interface Channel<K extends string = string> {
   readonly kind: 'channel';
   readonly name: string;
   readonly params: readonly K[];
-  readonly policy: QueryPolicy | undefined;
+  readonly policy: QueryPolicy;
   readonly row: ChannelRowLoader | undefined;
   readonly catchUp: string;
   readonly records: readonly RecordProjection[];
@@ -87,7 +89,7 @@ export interface Channel<K extends string = string> {
  * Registers the declaration (`channel-registry.ts`) — a second one of the same name is refused.
  *
  * The params-matching rule, decided here once: a row belongs to the topic whose params equal the
- * row's own properties of those names. So `channel('org-feed', { params: ['orgId'], records:
+ * row's own properties of those names. So `channel('org-feed', { params: ['orgId'], policy, records:
  * [posts] })` carries every `posts` row on `org-feed.<row.orgId>`, and every listed entity must have
  * a column named after every param — refused at declaration, where the author is.
  */
@@ -103,6 +105,15 @@ export function channel<K extends string>(
   const ref =
     typeof nameOrRef === 'string' ? channelRef(nameOrRef, init as ChannelInit<K>) : nameOrRef;
   const name = ref.name;
+  // The type requires it; this is the refusal a JS caller, or a cast, reaches.
+  const policy = (init as Partial<ChannelServerInit>).policy;
+  if (policy === undefined) {
+    refuseChannel(
+      name,
+      'declares no policy, so any socket, anonymous included, could join and receive every row',
+      "add policy: can('<resource>:read') to the channel() call, or policy: allow('public') for a channel anyone may join",
+    );
+  }
   const records = (init.records ?? []).map((entity) => {
     const projection = projectionFor(name, entity);
     for (const param of ref.params) {
@@ -121,7 +132,7 @@ export function channel<K extends string>(
     kind: 'channel' as const,
     name,
     params: ref.params,
-    policy: init.policy,
+    policy,
     row: init.row,
     get catchUp(): string {
       return ref.catchUp;

package/src/channel-describe.ts

@@ -13,8 +13,11 @@ export interface ChannelDescription {
   /** Record types (entity names) the channel carries, sorted. */
   readonly records: readonly string[];
   readonly events: boolean;
-  /** The policy's display label, `null` for a channel any socket may join. */
-  readonly policy: string | null;
+  /**
+   * The policy's display label. Never absent since 22.0.0 — `channel()` requires a policy, and a
+   * channel any socket may join reads `allow('public')`'s label, said out loud.
+   */
+  readonly policy: string;
   /** Every permission the policy asserts, flattened — what a report matches a grant against. */
   readonly permissions: readonly string[];
 }
@@ -26,8 +29,7 @@ export function describeChannels(): readonly ChannelDescription[] {
     catchUp: declared.catchUp,
     records: declared.records.map((projection) => projection.type).sort(),
     events: declared.events,
-    policy: declared.policy === undefined ? null : policyCapability(declared.policy),
-    permissions:
-      declared.policy === undefined ? [] : [...policyPermissions(declared.policy)].sort(),
+    policy: policyCapability(declared.policy),
+    permissions: [...policyPermissions(declared.policy)].sort(),
   }));
 }

package/src/channel-logs.ts

@@ -5,7 +5,7 @@
 import { logger, renderThrowable, uuid } from '@ultimat3/core';
 import type { ChangeEvent } from './changefeed';
 import type { Channel } from './channel-decl';
-import { updatesFor } from './channel-records';
+import { carriesTable, updatesFor } from './channel-records';
 import { renderRecords } from './channel-render';
 import { ChannelRing } from './channel-ring';
 import type { ChannelSince, ReplayGapFrame } from './channel-wire';
@@ -59,6 +59,7 @@ export class ChannelLogs {
    * the change is somebody else's too, and one malformed image must not stop the rest.
    */
   deliverChange(channels: Iterable<Channel>, change: ChangeEvent): number {
+    if (change.op === 'truncate') return this.#truncated(change.entity);
     let frames = 0;
     let updates: ReturnType<typeof updatesFor>;
     try {
@@ -80,6 +81,23 @@ export class ChannelLogs {
     return frames;
   }
 
+  /**
+   * Every row of `table` is gone, and no frame can say which ones a member holds. Each open topic
+   * of a channel carrying it starts a NEW epoch — nothing in the old ring may be replayed onto a
+   * table that no longer has those rows — and every member is told `replay-gap` at it, which the
+   * client answers by re-running the channel's catch-up read.
+   */
+  #truncated(table: string): number {
+    let announced = 0;
+    for (const [topic, open] of [...this.#byTopic]) {
+      if (!carriesTable(open.target.channel, table)) continue;
+      this.#byTopic.delete(topic);
+      const ring = this.open(topic, open.target);
+      announced += this.#sockets.announceGap(topic, ring.epoch);
+    }
+    return announced;
+  }
+
   /**
    * A (re)subscribe `since` a position: every frame after it from the ring, or — when the ring
    * cannot prove it holds them all, or the epoch moved — one `replay-gap`.

package/src/channel-records.ts

@@ -29,6 +29,9 @@ export interface TopicUpdate {
  */
 export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): TopicUpdate[] {
   const updates: TopicUpdate[] = [];
+  // A truncate names no row, so it routes to no topic here: `ChannelLogs` announces a gap on every
+  // open topic of every channel carrying the relation instead (`truncatedTopics`).
+  if (change.op === 'truncate') return updates;
   for (const channel of channels) {
     const projection = channel.records.find((candidate) => candidate.table === change.entity);
     if (projection === undefined) continue;
@@ -77,3 +80,8 @@ function removal(
     row,
   };
 }
+
+/** The channels whose records a truncate of `table` wiped: every one listing that relation. */
+export function carriesTable(channel: Channel, table: string): boolean {
+  return channel.records.some((projection) => projection.table === table);
+}

package/src/client-channels.ts

@@ -38,6 +38,11 @@ export interface ChannelBookDeps {
   /** Re-run the channel's catch-up read; its records land in the store through the transport. */
   catchUp(query: string, params: Readonly<Record<string, string>>): Promise<unknown>;
   report(error: unknown): void;
+  /**
+   * When a failed catch-up tries again on its own, on the client's reconnect curve. Absent, a
+   * failed read waits for the next open of the socket or the next gap.
+   */
+  readonly retry?: ((attempt: number, run: () => void) => () => void) | undefined;
 }
 
 interface Entry {
@@ -57,6 +62,17 @@ interface Entry {
   readonly above: Set<number>;
   /** Frames that arrived while the catch-up read was in flight, applied after it lands. */
   buffered: ChannelRecordsFrame[] | null;
+  /**
+   * A gap announced while a read was in flight: one more read follows it, in this epoch (or the
+   * current one when the gap named none). A flag, never a count — the `coalesceReloads` shape.
+   */
+  again: { readonly epoch: string | undefined } | null;
+  /** The read is not in flight: it failed, and waits for a retry with `buffered` still held. */
+  waiting: boolean;
+  /** Consecutive failed reads — the retry curve's attempt number. */
+  failures: number;
+  /** Disarms the scheduled retry. */
+  disarm: (() => void) | null;
 }
 
 export interface ChannelMembership extends Disposable {
@@ -97,6 +113,10 @@ export class ChannelBook {
         contiguous: null,
         above: new Set(),
         buffered: null,
+        again: null,
+        waiting: false,
+        failures: 0,
+        disarm: null,
       };
       this.#byTopic.set(topic, entry);
       if (this.#deps.connected()) this.#deps.send(this.#frame(entry, 'add', true));
@@ -110,6 +130,8 @@ export class ChannelBook {
       held.holders.delete(handlers);
       if (held.holders.size > 0) return;
       this.#byTopic.delete(topic);
+      held.disarm?.();
+      held.disarm = null;
       this.#deps.send(this.#frame(held, 'drop', false));
     };
     return {
@@ -130,6 +152,12 @@ export class ChannelBook {
   /** Every membership again, on a new socket — resuming from each cursor. */
   resubscribe(): void {
     for (const entry of this.#byTopic.values()) {
+      // A catch-up that failed retries on the new socket: the read is what it was waiting for.
+      if (entry.waiting) {
+        this.#deps.send(this.#frame(entry, 'add', true));
+        this.#read(entry);
+        continue;
+      }
       this.#set(entry, 'joining');
       this.#deps.send(this.#frame(entry, 'add', true));
     }
@@ -225,32 +253,74 @@ export class ChannelBook {
   /**
    * Re-read the channel through its catch-up query, holding every frame that arrives meanwhile;
    * then apply those, in order, over the read. The cursor restarts in the new epoch.
+   *
+   * A gap that lands DURING the read is not dropped: it earns one more read after this one (it
+   * was ignored, and the hole it announced was never repaired).
    */
   #catchUp(entry: Entry, pending: ChannelRecordsFrame[], epoch?: string): void {
     if (entry.buffered !== null) {
       entry.buffered.push(...pending);
+      if (pending.length === 0) entry.again = { epoch: epoch ?? entry.again?.epoch };
+      // No read in flight — the last one failed — so this gap is the retry, now.
+      if (entry.waiting) this.#read(entry);
       return;
     }
     entry.buffered = [...pending];
-    entry.epoch = epoch ?? pending[0]?.epoch ?? entry.epoch;
+    this.#restart(entry, epoch ?? pending[0]?.epoch ?? entry.epoch);
+    this.#read(entry);
+  }
+
+  /** The cursor, reset into `epoch`: every seq before the read is the read's to answer. */
+  #restart(entry: Entry, epoch: string | null): void {
+    entry.epoch = epoch;
     entry.contiguous = null;
     entry.above.clear();
+  }
+
+  #read(entry: Entry): void {
+    entry.waiting = false;
+    entry.error = undefined;
+    entry.disarm?.();
+    entry.disarm = null;
     this.#set(entry, 'catching-up');
     this.#deps.catchUp(entry.catchUp, entry.params).then(
       () => this.#drain(entry),
       (error: unknown) => {
         this.#deps.report(error);
-        this.#drain(entry);
+        // NOT live: the frames held behind the read would land over a store it never refreshed.
+        // Failed, the error exposed, and the frames still held for the retry — which the next
+        // open of the socket runs (`resubscribe`), or the next gap.
+        entry.waiting = true;
+        entry.error = error;
+        entry.failures += 1;
+        if (this.#byTopic.get(entry.topic) !== entry) return;
+        this.#set(entry, 'failed');
+        entry.disarm =
+          this.#deps.retry?.(entry.failures, () => {
+            entry.disarm = null;
+            if (entry.waiting && this.#byTopic.get(entry.topic) === entry) this.#read(entry);
+          }) ?? null;
       },
     );
   }
 
   #drain(entry: Entry): void {
     const held = entry.buffered ?? [];
+    // A newer epoch arrived while the read was in flight (the node restarted mid-read): the read
+    // answered for the OLD one, so it is re-read in the new one, keeping only that epoch's frames.
+    // `#drain` used to discard them, and the rows they carried with them.
+    const newer = held.find((frame) => frame.epoch !== entry.epoch);
+    if (entry.again !== null || newer !== undefined) {
+      const epoch = newer?.epoch ?? entry.again?.epoch ?? entry.epoch;
+      entry.again = null;
+      entry.buffered = held.filter((frame) => frame.epoch === epoch);
+      this.#restart(entry, epoch);
+      this.#read(entry);
+      return;
+    }
     entry.buffered = null;
-    // Frames of an epoch other than the one caught up to predate it; the read already holds them.
-    const current = held.filter((frame) => frame.epoch === entry.epoch);
-    current.sort((a, b) => a.seq - b.seq);
+    entry.failures = 0;
+    const current = [...held].sort((a, b) => a.seq - b.seq);
     for (const frame of current) {
       if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
       this.#apply(entry, frame);

package/src/client.ts

@@ -19,7 +19,7 @@ import type { JsonObject, JsonValue } from './json';
 import { type LiveState, type Registration, RowWindows, unnamedType } from './live-rows';
 import { RecordStore } from './record-store';
 import { decode, encode, type Frame, PROTOCOL_VERSION } from './sync-protocol';
-import { backoffDelay, browserBackoff, timeoutScheduler } from './thundering-herd';
+import { browserBackoff, policyDelay, timeoutScheduler } from './thundering-herd';
 
 export type {
   ClientSocket,
@@ -78,6 +78,17 @@ export class LiveClient {
       connected: () => this.#connected,
       catchUp: options.catchUp,
       report: (error) => this.#onError(error),
+      // A failed catch-up retries on the reconnect curve this client already dials on.
+      retry: (attempt, run) =>
+        (this.#options.scheduler ?? timeoutScheduler)(
+          run,
+          // `attempt` is the book's failure count, 1 on the first failure: core's count as is.
+          policyDelay(
+            this.#options.backoff ?? browserBackoff,
+            attempt,
+            this.#options.rng ?? Math.random,
+          ),
+        ),
     });
     this.#heartbeat = new Heartbeat({
       intervalMs: finiteOption(
@@ -369,7 +380,8 @@ export class LiveClient {
     this.#cancelReconnect();
     const rng = this.#options.rng ?? Math.random;
     const delay =
-      serverDelayMs ?? backoffDelay(this.#attempt, this.#options.backoff ?? browserBackoff, rng);
+      // `#attempt` counts reconnects already scheduled, from 0; the wait being armed is the next one.
+      serverDelayMs ?? policyDelay(this.#options.backoff ?? browserBackoff, this.#attempt + 1, rng);
     this.#attempt += 1;
     this.#setStatus({ reconnectAt: this.#clock.now().getTime() + delay });
     const schedule = this.#options.scheduler ?? timeoutScheduler;