@ultimat3/realtime 20.2.1 → 22.0.0

package/src/sync-protocol.ts

@@ -1,14 +1,15 @@
-// The wire. One protocol for all three tiers: a channel subscribe, a live-query subscribe, and an
-// offline mutation drain are frames in the same union — so moving a route from tier 2 to tier 3
-// needs no new protocol, and THAT is the half this file enforces.
-// It is not a `persist: true` config flag: this header said so until 2026-09 and `query()` has
-// never accepted the key (`local-store.ts` records the same). Tier 3 is reached by passing a
-// `LocalStore` to the live client, which is a client-side wiring decision this file cannot see —
-// claiming to enforce it here is the declared-and-never-wired shape the repo keeps re-shipping.
-
-import { renderThrowable, stringField } from '@ultimat3/core';
-import { CURSOR_ID_LIMIT, type LiveCursor } from './cursor';
-import { ProtocolVersionError } from './errors';
+// The wire, READ-ONLY for the client: channel and live-query subscriptions go up, snapshots,
+// patches, presence and refusals come down. A client write is HTTP (`useMutation`), never a frame —
+// so there is one write path, with the action's authz, idempotency store and contract behind it.
+
+import { renderThrowable, stringField } from '@ultimat3/core/page';
+import type {
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ChannelSubscribeTarget,
+  ReplayGapFrame,
+} from './channel-wire';
+import type { LiveCursor } from './cursor';
 import {
   isJsonObject,
   isRow,
@@ -17,41 +18,19 @@ import {
   type Row,
   type RowPatch,
 } from './json';
-
-/**
- * **2 since 2026-08-24**, when `cursor.digest` and `cursor.count` were deleted. The version guards
- * incompatibility, never novelty — an additive optional field (`snapshot.entity`) and a removed
- * field read through `list()` (`hello.resume`) both stayed at 1, because `decode` is a whitelist
- * and `list()` answers `[]` for an absent field. `cursor()` is the other kind of reader: it reads
- * through `str`/`num`, which THROW on an absent field, so a cursor without those two is a frame a
- * node or a client one deploy behind cannot read — in BOTH directions, since a cursor rides the
- * client's `subscribe` and the node's `snapshot`. That is exactly what this number refuses, with
- * one instruction instead of a per-frame "field \"digest\" must be a string".
- */
-export const PROTOCOL_VERSION = 2;
-
-/**
- * What one frame may contain. Hard ceilings a caller cannot widen — the shape
- * `packages/mcp/src/query-limits.ts` uses — because every one of them is read off a socket the
- * node has already paid for: an unbounded `cursor.ids` was consumed raw into a `Set`, and an
- * `input` of arbitrary depth reached `canonicalJson`, which recurses.
- *
- * Every number clears what this node itself produces, or the decoder refuses its own frames on
- * the next reconnect: `cursorIds` is `CURSOR_ID_LIMIT`, `patches` clears
- * `defaultReconnectBudget.maxPatches`.
- */
-export const FRAME_LIMITS = Object.freeze({
-  cursorIds: CURSOR_ID_LIMIT,
-  patches: 4_096,
-  rows: 10_000,
-  members: 4_096,
-  /** Nesting one `input` may reach. 32 is far past any query's real argument shape. */
-  inputDepth: 32,
-  /** Values one `input` may hold in total, so a flat-but-enormous object is refused too. */
-  inputNodes: 10_000,
-});
-
-export type ConflictStrategyName = 'server-wins' | 'last-write-wins' | 'custom';
+import { ProtocolVersionError } from './page-errors';
+import { channelTarget, events, records, replayGap } from './wire-channel';
+import { bounded, fail, list, nullableStr, num, object, pick, str } from './wire-read';
+import { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
+
+export type {
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ChannelSubscribeTarget,
+  ReplayGapFrame,
+} from './channel-wire';
+/** The version and the ceilings live below this file so the readers can share them without a cycle. */
+export { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
 
 export interface WireError {
   readonly code: string;
@@ -69,7 +48,8 @@ export interface PresenceMember {
 }
 
 export type SubscribeTarget =
-  | { readonly kind: 'topic'; readonly topic: string }
+  /** A declared `channel()`: its NAME and params, never a topic string the client spelled. */
+  | ChannelSubscribeTarget
   | {
       /**
        * Client -> server, `qid` carries the *query name*; the server derives the real qid from
@@ -124,6 +104,12 @@ export interface SnapshotFrame {
    * skews are safe in both directions, which is why it carries no `PROTOCOL_VERSION` bump.
    */
   readonly entity?: string;
+  /**
+   * Each row's RECORD key, parallel to `rows`, sent only when some key is not its row's `id` (a
+   * composite primary key). The server renders it with the entity's projection; the browser never
+   * derives a key.
+   */
+  readonly keys?: readonly string[];
 }
 
 export interface PatchFrame {
@@ -134,51 +120,18 @@ export interface PatchFrame {
   readonly lsn: string;
 }
 
-export interface MutateFrame {
-  readonly type: 'mutate';
-  readonly v: number;
-  /** Idempotency key. The server collapses repeats; the client never renumbers. */
-  readonly key: string;
-  readonly seq: number;
-  readonly name: string;
-  readonly input: JsonValue;
-}
-
 export interface AckFrame {
   readonly type: 'ack';
   readonly v: number;
-  /** Mutation key or subscription id being acknowledged. */
+  /**
+   * What a refusal refers to: the sid of a subscription the node refused, or the socket id for a
+   * frame it could not read at all. The socket carries no writes, so an ack is never a receipt.
+   */
   readonly ref: string;
   readonly lsn: string | null;
   readonly error: WireError | null;
 }
 
-export interface RebaseFrame {
-  readonly type: 'rebase';
-  readonly v: number;
-  readonly key: string;
-  readonly entity: string;
-  readonly strategy: ConflictStrategyName;
-  /** Server truth for the row the mutation touched; `null` when the server deleted it. */
-  readonly row: Row | null;
-}
-
-export interface PresenceFrame {
-  readonly type: 'presence';
-  readonly v: number;
-  readonly topic: string;
-  readonly op: 'join' | 'leave' | 'update' | 'sync';
-  readonly members: readonly PresenceMember[];
-  /**
-   * Members in the whole set behind a `sync` frame, which is capped: a 5,000-avatar row is not a UI
-   * anyone renders, and the count is what lets a client say "and 4,744 others" without holding
-   * them. Optional and **additive**, exactly like `snapshot.entity`: an old node omits it and a new
-   * one reads its absence as "this frame is the whole set", so neither skew is unreadable and
-   * `PROTOCOL_VERSION` does not move. Never set on a `join`/`leave`/`update` — those are deltas.
-   */
-  readonly total?: number;
-}
-
 export interface ReconnectFrame {
   readonly type: 'reconnect';
   readonly v: number;
@@ -198,12 +151,12 @@ export type Frame =
   | SubscribeFrame
   | SnapshotFrame
   | PatchFrame
-  | MutateFrame
   | AckFrame
-  | RebaseFrame
-  | PresenceFrame
   | ReconnectFrame
-  | UpdateAvailableFrame;
+  | UpdateAvailableFrame
+  | ChannelRecordsFrame
+  | ChannelEventsFrame
+  | ReplayGapFrame;
 
 export type FrameKind = Frame['type'];
 
@@ -212,12 +165,12 @@ export const FRAME_KINDS: readonly FrameKind[] = [
   'subscribe',
   'snapshot',
   'patch',
-  'mutate',
   'ack',
-  'rebase',
-  'presence',
   'reconnect',
   'update-available',
+  'records',
+  'events',
+  'replay-gap',
 ];
 
 export function encode(frame: Frame): string {
@@ -265,7 +218,14 @@ export function decode(raw: string | Uint8Array): Frame {
         cursor: cursor(parsed['cursor']),
       } as const;
       const entity = nullableStr(parsed, 'entity');
-      return entity === null ? base : { ...base, entity };
+      const scoped = entity === null ? base : { ...base, entity };
+      if (parsed['keys'] === undefined) return scoped;
+      const keys = list(parsed, 'keys', FRAME_LIMITS.rows).map((key) => {
+        if (typeof key !== 'string') throw fail('snapshot.keys must hold strings');
+        return key;
+      });
+      if (keys.length !== base.rows.length) throw fail('snapshot.keys must pair with rows');
+      return { ...scoped, keys };
     }
     case 'patch':
       return {
@@ -275,15 +235,6 @@ export function decode(raw: string | Uint8Array): Frame {
         patches: list(parsed, 'patches', FRAME_LIMITS.patches).map(patch),
         lsn: str(parsed, 'lsn'),
       };
-    case 'mutate':
-      return {
-        type: 'mutate',
-        v: PROTOCOL_VERSION,
-        key: str(parsed, 'key'),
-        seq: num(parsed, 'seq'),
-        name: str(parsed, 'name'),
-        input: bounded(parsed['input'] ?? null, 'input'),
-      };
     case 'ack':
       return {
         type: 'ack',
@@ -292,25 +243,6 @@ export function decode(raw: string | Uint8Array): Frame {
         lsn: nullableStr(parsed, 'lsn'),
         error: wireError(parsed['error']),
       };
-    case 'rebase':
-      return {
-        type: 'rebase',
-        v: PROTOCOL_VERSION,
-        key: str(parsed, 'key'),
-        entity: str(parsed, 'entity'),
-        strategy: pick(parsed, 'strategy', ['server-wins', 'last-write-wins', 'custom'] as const),
-        row: parsed['row'] === null ? null : row(parsed['row']),
-      };
-    case 'presence': {
-      const base = {
-        type: 'presence',
-        v: PROTOCOL_VERSION,
-        topic: str(parsed, 'topic'),
-        op: pick(parsed, 'op', ['join', 'leave', 'update', 'sync'] as const),
-        members: list(parsed, 'members', FRAME_LIMITS.members).map(member),
-      } as const;
-      return parsed['total'] === undefined ? base : { ...base, total: num(parsed, 'total') };
-    }
     case 'reconnect':
       return {
         type: 'reconnect',
@@ -320,6 +252,12 @@ export function decode(raw: string | Uint8Array): Frame {
       };
     case 'update-available':
       return { type: 'update-available', v: PROTOCOL_VERSION, buildId: str(parsed, 'buildId') };
+    case 'records':
+      return records(parsed);
+    case 'events':
+      return events(parsed);
+    case 'replay-gap':
+      return replayGap(parsed);
     default:
       throw fail(`unknown frame type ${JSON.stringify(kind)}`);
   }
@@ -340,80 +278,6 @@ export function toWireError(error: unknown): WireError {
   return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
 }
 
-function fail(detail: string): ProtocolVersionError {
-  return new ProtocolVersionError({ got: detail, expected: PROTOCOL_VERSION, detail });
-}
-
-function str(obj: JsonObject, key: string): string {
-  const value = obj[key];
-  if (typeof value !== 'string') throw fail(`field "${key}" must be a string`);
-  return value;
-}
-
-function nullableStr(obj: JsonObject, key: string): string | null {
-  const value = obj[key];
-  if (value === null || value === undefined) return null;
-  if (typeof value !== 'string') throw fail(`field "${key}" must be a string or null`);
-  return value;
-}
-
-function num(obj: JsonObject, key: string): number {
-  const value = obj[key];
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw fail(`field "${key}" must be a finite number`);
-  }
-  return value;
-}
-
-function pick<T extends string>(obj: JsonObject, key: string, allowed: readonly T[]): T {
-  const value = str(obj, key);
-  const found = allowed.find((candidate) => candidate === value);
-  if (found === undefined) throw fail(`field "${key}" must be one of ${allowed.join('|')}`);
-  return found;
-}
-
-/**
- * An array field, with the ceiling the caller had to choose. `max` is required rather than
- * defaulted: a new list field on a new frame is a new thing an authenticated socket can make
- * arbitrarily large, and a default would let one ship without anyone deciding its size.
- */
-function list(obj: JsonObject, key: string, max: number, label = key): JsonValue[] {
-  const value = obj[key];
-  if (value === undefined || value === null) return [];
-  if (!Array.isArray(value)) throw fail(`field "${label}" must be an array`);
-  if (value.length > max) {
-    throw fail(`field "${label}" carries ${value.length} entries, over the limit of ${max}`);
-  }
-  return value;
-}
-
-/**
- * A client-supplied value, walked ITERATIVELY to its limits. Iteratively because the thing being
- * refused is a stack overflow: `queryHash` -> `canonicalJson` recurses over exactly this value, so a
- * depth check that recursed would be the same crash one frame earlier.
- */
-function bounded(value: JsonValue, label: string): JsonValue {
-  const stack: { node: JsonValue; depth: number }[] = [{ node: value, depth: 1 }];
-  let seen = 0;
-  while (stack.length > 0) {
-    // `pop` cannot answer undefined here — the loop guard is the length — and the check is what
-    // makes that readable to the compiler without a cast.
-    const next = stack.pop();
-    if (next === undefined) break;
-    seen += 1;
-    if (seen > FRAME_LIMITS.inputNodes) {
-      throw fail(`field "${label}" holds more than ${FRAME_LIMITS.inputNodes} values`);
-    }
-    if (next.depth > FRAME_LIMITS.inputDepth) {
-      throw fail(`field "${label}" is nested deeper than ${FRAME_LIMITS.inputDepth}`);
-    }
-    if (next.node === null || typeof next.node !== 'object') continue;
-    const children = Array.isArray(next.node) ? next.node : Object.values(next.node);
-    for (const child of children) stack.push({ node: child, depth: next.depth + 1 });
-  }
-  return value;
-}
-
 function row(value: unknown): Row {
   if (!isRow(value)) throw fail('row must be an object with a string "id"');
   return value;
@@ -440,23 +304,15 @@ function patch(value: unknown): RowPatch {
     row: value['row'] === null || value['row'] === undefined ? null : object(value['row']),
     lsn: str(value, 'lsn'),
   };
-  return value['index'] === undefined ? base : { ...base, index: num(value, 'index') };
-}
-
-function member(value: unknown): PresenceMember {
-  if (!isJsonObject(value)) throw fail('presence member must be an object');
-  return {
-    id: str(value, 'id'),
-    actorId: nullableStr(value, 'actorId'),
-    meta: object(value['meta'] ?? {}),
-    updatedAt: num(value, 'updatedAt'),
-  };
+  const indexed = value['index'] === undefined ? base : { ...base, index: num(value, 'index') };
+  const key = nullableStr(value, 'key');
+  return key === null ? indexed : { ...indexed, key };
 }
 
 function target(value: unknown): SubscribeTarget {
   if (!isJsonObject(value)) throw fail('subscribe.target must be an object');
-  const kind = pick(value, 'kind', ['topic', 'query'] as const);
-  if (kind === 'topic') return { kind, topic: str(value, 'topic') };
+  const kind = pick(value, 'kind', ['query', 'channel'] as const);
+  if (kind === 'channel') return channelTarget(value);
   return {
     kind,
     qid: str(value, 'qid'),
@@ -466,11 +322,6 @@ function target(value: unknown): SubscribeTarget {
   };
 }
 
-function object(value: unknown): JsonObject {
-  if (!isJsonObject(value)) throw fail('expected a JSON object');
-  return value;
-}
-
 function wireError(value: unknown): WireError | null {
   if (value === null || value === undefined) return null;
   if (!isJsonObject(value)) throw fail('ack.error must be an object or null');

package/src/sync-worker.ts

@@ -0,0 +1,12 @@
+// The SharedWorker entry (plan 101, slice 11): every tab of this origin and principal connects a
+// port, and the one engine behind them holds the one socket. `x build` bundles this file as a
+// classic script at `/_x/sync-worker/<hash>.js`. No other code lives here.
+
+import { browserSocket, dialUrl } from './browser-socket';
+import { messagePort, SocketEngine } from './socket-engine';
+
+const engine = new SocketEngine({ dial: (target) => browserSocket(dialUrl(target)) });
+
+(globalThis as { onconnect?: (event: MessageEvent) => void }).onconnect = (event) => {
+  for (const port of event.ports) engine.attach(messagePort(port));
+};

package/src/thundering-herd.ts

@@ -3,17 +3,17 @@
 //
 // Three mechanisms, in the order they fire:
 //   1. drainPlan()    — the draining node assigns each client a distinct delay slot before closing
-//   2. backoffDelay() — the client's own jittered retry, for failures nobody scheduled
+//   2. policyDelay()  — the client's own jittered retry, for failures nobody scheduled
 //   3. AcceptBudget   — the receiving node's token bucket, so recovery sheds instead of collapsing
 
 import {
+  backoffDelay,
   type Clock,
-  backoffDelay as coreBackoffDelay,
   finiteOption,
   type JitterMode,
   type Random,
   systemClock,
-} from '@ultimat3/core';
+} from '@ultimat3/core/page';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
 /** Injected so tests are deterministic and `local` mutators stay replayable. */
@@ -40,21 +40,40 @@ export const defaultBackoff: BackoffPolicy = {
   jitter: 'full',
 };
 
+/** The longest a browser waits between two dials, whatever the attempt. */
+export const BROWSER_RECONNECT_MAX_MS = 4_000;
+
+/**
+ * A browser's redial: the same curve, capped at seconds rather than `defaultBackoff`'s thirty.
+ * Measured after a deploy — six dials in ~3s, then a full-jitter roll under a 30s cap left the
+ * node that came back (and the `update-available` it had for the tab) unreached for 27s. `equal`
+ * jitter, because at the cap it keeps a floor: a SIGKILLed node's herd redials inside a 2-4s
+ * window rather than at once, and the `AcceptBudget` sheds the excess before any query runs. A
+ * PLANNED restart never reaches this: the drain's `reconnect` frame assigns each socket its slot.
+ */
+export const browserBackoff: BackoffPolicy = {
+  baseMs: 500,
+  maxMs: BROWSER_RECONNECT_MAX_MS,
+  factor: 2,
+  jitter: 'equal',
+};
+
 /**
- * Attempt is 0-BASED. Result is always in `[0, maxMs]`.
+ * A {@link BackoffPolicy} mapped onto `@ultimat3/core`'s `backoffDelay` — the one curve. Attempt is
+ * 1-BASED, core's count: the wait after the first failure is `attempt: 1` and is `baseMs`.
  *
- * The arithmetic is core's, and `attempt + 1` is the WHOLE of the seam: a client counts its first
- * reconnect as attempt 0 and core counts the first wait as attempt 1, so dropping the shift would
- * double every reconnect delay in the framework — silently, and only under the load this file
- * exists to survive. `thundering-herd-core-parity.test.ts` pins the numbers.
+ * Internal to this package and never re-exported from the barrel. Until 22.0.0 `.` exported a
+ * 0-based `backoffDelay` of its own that shifted by one before delegating, which made two counting
+ * conventions under one name — and a caller that passed a 1-based count to it (the channel
+ * catch-up retry did) waited twice as long as it meant to, with no error anywhere.
  */
-export function backoffDelay(
+export function policyDelay(
+  policy: BackoffPolicy,
   attempt: number,
-  policy: BackoffPolicy = defaultBackoff,
   rng: Rng = Math.random,
 ): number {
-  return coreBackoffDelay({
-    attempt: attempt + 1,
+  return backoffDelay({
+    attempt,
     base: policy.baseMs,
     max: policy.maxMs,
     factor: policy.factor,

package/src/transport-env.ts

@@ -1,20 +1,30 @@
-// Single responsibility: environment → fanout transport. The one place a boot decides whether this
-// process fans changes out inside its own heap or over NATS, so `x dev`, a `sync` container and any
-// custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
+// Single responsibility: `realtime.transport` + environment → fanout transport. The one place a boot
+// decides whether this process fans changes out inside its own heap or over NATS, so `x dev`, a
+// `sync` container and any custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
 // the bucket's whole-stream age limit and `PresenceRegistry`'s TTL are the same number seen from
 // two sides, and a caller that had to pass each one separately could quietly set them apart.
 
-import type { Clock } from '@ultimat3/core';
-import { finiteOption } from '@ultimat3/core';
+import type { Clock, RealtimeConfig } from '@ultimat3/core';
+import { ConfigInvalidError, finiteOption } from '@ultimat3/core';
 import type { Transport } from './fanout';
 import { InProcessTransport } from './fanout';
 import type { NatsConnect } from './nats-client';
 import { assertBucket } from './nats-jetstream';
 import { NatsTransport } from './nats-transport';
 
-/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+/**
+ * The keys read here, and nothing else. Named once so docs and tests cannot drift from the code.
+ * `NATS_URL` is the conventional bus variable: read under `transport: 'nats'` when `urlEnv` names
+ * it, and under `'memory'` only to refuse it — see `selectTransport`.
+ */
 export const TRANSPORT_ENV_KEYS = ['NATS_URL', 'NATS_KV_BUCKET'] as const;
 
+/** The two fields of `app.config.ts`'s `realtime` section that decide the bus. */
+export type RealtimeTopology = Pick<RealtimeConfig, 'transport' | 'urlEnv'>;
+
+/** Named in every refusal, so the reader edits the file the decision lives in. */
+const CONFIG_FILE = 'app.config.ts';
+
 /**
  * One bucket per deployment, not per cluster: two apps sharing a nats-server would otherwise share
  * one presence namespace, and a room name that collided would list the other app's members.
@@ -59,13 +69,22 @@ const nonEmpty = (value: string | undefined): string | undefined =>
   value === undefined || value.trim().length === 0 ? undefined : value.trim();
 
 /**
- * No url means the in-process transport — the same "an unset variable means the embedded default"
- * law the db, mail, storage and replication bindings follow. The bucket name is validated here
- * rather than on first connect: a typo'd bucket is a boot that reports a healthy bus and then
- * fails every presence write, which is the failure this whole selector exists to move earlier.
+ * The config decides the transport and the environment supplies its url — never the other way
+ * round. Until 22.0.0 `NATS_URL` alone decided and `realtime.transport` / `realtime.urlEnv` were
+ * read by nothing, so `transport: 'nats'` with the variable unset booted the in-process bus and
+ * reached no other node, with no error on either side. Both mismatches are refused here:
+ *
+ * - `'nats'` with the variable `urlEnv` names unset or blank.
+ * - `'memory'` with a bus url set (`NATS_URL`, or the variable `urlEnv` names). An operator who set
+ *   one expected fanout across nodes; keeping every change in this heap instead is the same silent
+ *   failure seen from the other side, so the two are refused rather than reconciled.
+ *
+ * The bucket name is validated here rather than on first connect: a typo'd bucket is a boot that
+ * reports a healthy bus and then fails every presence write.
  */
 export function selectTransport(
   env: TransportEnvironment,
+  topology: RealtimeTopology,
   options: SelectTransportOptions = {},
 ): TransportSelection {
   const presenceTtlMs = finiteOption(
@@ -73,22 +92,32 @@ export function selectTransport(
     'presenceTtlMs',
     options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS,
   );
-  const url = nonEmpty(env['NATS_URL']);
 
-  if (url === undefined) {
+  if (topology.transport === 'memory') {
+    refuseStrayBusUrl(env, topology);
     const transport = new InProcessTransport(
       options.clock === undefined ? {} : { clock: options.clock },
     );
     return {
       transport,
       mode: 'embedded',
-      detail: 'in-process fanout — set NATS_URL to reach the other nodes',
+      detail: `in-process fanout — set realtime.transport 'nats' in ${CONFIG_FILE} and NATS_URL to reach the other nodes`,
       bucket: null,
       presenceTtlMs,
       connect: () => Promise.resolve(),
     };
   }
 
+  const urlEnv = topology.urlEnv ?? 'NATS_URL';
+  const url = nonEmpty(env[urlEnv]);
+  if (url === undefined) {
+    throw new ConfigInvalidError({
+      cause: `realtime.transport is 'nats' and realtime.urlEnv names ${urlEnv}, which is unset in this process's environment, so no node would be reachable`,
+      fix: `set ${urlEnv} to the nats-server url for every realtime role (web, sync, replicator), or set realtime: { transport: 'memory' } in ${CONFIG_FILE} for a single node`,
+      meta: { key: 'realtime.urlEnv', variable: urlEnv },
+    });
+  }
+
   const bucket = nonEmpty(env['NATS_KV_BUCKET']) ?? DEFAULT_PRESENCE_BUCKET;
   assertBucket(bucket);
   const transport = new NatsTransport({
@@ -101,9 +130,21 @@ export function selectTransport(
   return {
     transport,
     mode: 'external',
-    detail: 'NATS_URL',
+    detail: urlEnv,
     bucket,
     presenceTtlMs,
     connect: () => transport.connect(),
   };
 }
+
+/** `'memory'` with a bus url in the environment: the conflict `selectTransport` refuses. */
+function refuseStrayBusUrl(env: TransportEnvironment, topology: RealtimeTopology): void {
+  const names = topology.urlEnv === undefined ? ['NATS_URL'] : ['NATS_URL', topology.urlEnv];
+  const set = names.find((name) => nonEmpty(env[name]) !== undefined);
+  if (set === undefined) return;
+  throw new ConfigInvalidError({
+    cause: `${set} is set but realtime.transport is 'memory', so this process would fan out in its own heap and reach no other node`,
+    fix: `set realtime: { transport: 'nats', urlEnv: '${set}' } in ${CONFIG_FILE} to use the bus, or unset ${set} for a single node`,
+    meta: { key: 'realtime.transport', variable: set },
+  });
+}