@ultimat3/realtime 24.0.0 → 25.1.0

package/src/sync-node.ts

@@ -10,21 +10,24 @@ import {
   markReady,
   reportError,
   systemClock,
-  uuid,
+  uuidV7,
 } from '@ultimat3/core';
 import type { Topic } from './channel';
 import { ChannelSids } from './channel-sids';
 import { detach } from './detach';
 import { evictInChunks } from './drain-evictions';
-import { isClientFault, TopicForbiddenError } from './errors';
+import { isClientFault } from './errors';
 import type { TransportSubscription } from './fanout';
-import { refuseSubscription } from './live-refusal';
+import { PrincipalSockets } from './principal-sockets';
 import { CHANGE_SUBJECT_ALL } from './replicator';
-import { parseEnvelope, SeqGapDetector } from './replicator-envelope';
-import { CLOSE, DEFAULT_MAX_BUFFERED_BYTES, SocketRegistry, SyncSocket } from './socket';
+import { SeqGapDetector } from './replicator-envelope';
+import { CLOSE, SocketRegistry, SyncSocket } from './socket';
+import { DEFAULT_MAX_BUFFERED_BYTES } from './socket-defaults';
 import { idleSweepPeriodMs } from './socket-idle';
+import { actorChangeHandler } from './sync-actor-change';
 import { GrantBook, sweepGrants } from './sync-auth';
-import { ackRefOf, createFrameRouter } from './sync-frames';
+import { changeHandler, ProducerKinds, reconnectHandler } from './sync-bus-handlers';
+import { ackRefOf, frameRouter } from './sync-frames';
 import {
   clientHeartbeatMs,
   drainGraceMs,
@@ -49,7 +52,7 @@ export type { SyncNode, SyncNodeOptions, SyncWs } from './sync-node-contract';
 /** Declared with the upgrade that builds it — this file only ever reads one. */
 export type { UpgradeTarget, WsData } from './sync-upgrade';
 
-export function createSyncNode(options: SyncNodeOptions): SyncNode {
+export function syncNode(options: SyncNodeOptions): SyncNode {
   const sockets =
     options.sockets ??
     new SocketRegistry({
@@ -66,12 +69,22 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
   const path = options.path ?? '/_x/sync';
   const presence = options.presence;
   const grants = new GrantBook();
+  const principals = new PrincipalSockets(options.maxSocketsPerActor);
   const gaps = new SeqGapDetector();
+  // Kept across restarts of the bus subscription: a table's producer kind is a fact of the fleet.
+  const producers = new ProducerKinds();
   const channelSids = new ChannelSids();
   let reconnects: (() => void) | null = null;
   /** The re-auth pass in flight, shared by every tick that lands while it runs. */
   let reauthPass: Promise<void> | null = null;
   let ready = false;
+  /**
+   * The start in flight or done, and whether a stop/drain has run since. `start()` awaits the bus,
+   * and a stop inside that await found nothing to release: the subscription landed after it and
+   * the node came up `ready` and delivering after it was stopped. The `replicator.ts` pattern.
+   */
+  let started: Promise<void> | null = null;
+  let generation = 0;
   /** Resolved by `teardown` when the last socket leaves, for a drain that is waiting its grace. */
   let lastSocketLeft: (() => void) | null = null;
   let changes: TransportSubscription | null = null;
@@ -119,6 +132,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     for (const name of topics) options.hub.unsubscribe(socket, name);
     sockets.remove(socket.id);
     grants.delete(socket.id);
+    principals.release(socket.id);
     if (sockets.count === 0) lastSocketLeft?.();
     // A closed socket is a leave, said now rather than left to TTL: everyone else would otherwise
     // keep rendering a member who is provably gone for the rest of its window. The write is on the
@@ -182,39 +196,20 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     return reauthPass;
   };
 
+  const onActor = actorChangeHandler({
+    sockets,
+    hub: options.hub,
+    registry: options.registry,
+    channelSids,
+    presence,
+  });
+
   const reauthPassOnce = async (): Promise<void> => {
     await sweepGrants({
       grants,
       clock,
       refreshDeadlineMs: options.grantRefreshDeadlineMs,
-      onActor: async (socketId, actor) => {
-        const socket = sockets.get(socketId);
-        if (!socket) return;
-        const rooms = new Set(options.hub.topicsOf(socket).filter(hasRoster));
-        // The hub sets `socket.actor` and drops the topics this actor may no longer read; the
-        // registry re-decides every live subscription (refusing each one it drops under its sid)
-        // and desyncs the survivors, so the next delivery re-snapshots them under the new
-        // authority rather than the old window.
-        for (const name of await options.hub.onActorChange(socket, actor)) {
-          // A dropped seat is SAID: unsaid, the client kept rendering the channel as live.
-          const sid = channelSids.sidOf(socket, name);
-          channelSids.delete(socket, name);
-          if (sid !== undefined) {
-            refuseSubscription(
-              socket,
-              sid,
-              new TopicForbiddenError({
-                topic: name,
-                actorId: socket.actorId,
-                reason: 'the session changed and the channel policy no longer admits it',
-              }),
-            );
-          }
-          if (presence && rooms.has(name))
-            detach(presence.leave(name, socket.id), 'presence.leave', name);
-        }
-        await options.registry.reauthorize(socket);
-      },
+      onActor,
       onRevoked: (socketId) => {
         const socket = sockets.get(socketId);
         if (!socket) return;
@@ -236,7 +231,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     });
   };
 
-  const routeFrame = createFrameRouter({
+  const routeFrame = frameRouter({
     hub: options.hub,
     registry: options.registry,
     buildId: options.buildId,
@@ -245,84 +240,83 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     heartbeatMs: clientHeartbeatMs(presence?.heartbeatMs, sockets.idleTimeoutMs),
   });
 
+  /** Everything `start()` does, fenced on the generation it began under — see `started`. */
+  const begin = async (): Promise<void> => {
+    const run = generation;
+    const bus = { registry: options.registry, hub: options.hub, gaps, producers };
+    const subscription = await options.transport.subscribe(CHANGE_SUBJECT_ALL, changeHandler(bus));
+    // A stop or drain ran inside that await: what it released did not include this yet.
+    if (run !== generation) {
+      subscription.unsubscribe();
+      return;
+    }
+    changes = subscription;
+    reconnects = options.transport.onReconnect(reconnectHandler(bus));
+    // One pass per heartbeat window: a member is swept only once it has actually missed its
+    // window, and the interval never holds the process open — shutdown is the drain's job.
+    if (presence) {
+      sweeping = setInterval(
+        () => detach(presence.sweepAll(), 'presence.sweep'),
+        presence.heartbeatMs,
+      );
+      sweeping.unref();
+    }
+    // The half-open connection Bun's own `idleTimeout` renews through its ping/pong: a client
+    // whose frame loop is wedged answers pings and keeps its grant, its subscriptions and its
+    // topic membership. `sweepIdle` was written for this and never called, so `touch()` and the
+    // 120s budget under it decided nothing.
+    idling = setInterval(() => {
+      for (const socket of sockets.idle()) evict(socket, CLOSE.idle, 'idle timeout');
+    }, idleSweepPeriodMs(sockets.idleTimeoutMs));
+    idling.unref();
+    if (options.authenticate) {
+      reauthing = setInterval(
+        () => detach(reauthenticate(), 'sync.reauthenticate'),
+        bounds.reauthenticateIntervalMs,
+      );
+      reauthing.unref();
+    } else {
+      // Enforced where it can be: nothing here can invent a credential, so the one honest signal
+      // is that every policy on this node is about to be asked about `null`.
+      logger.warn('sync node has no authenticator: every socket is anonymous', {
+        buildId: options.buildId,
+        fix: 'pass authenticate to syncNode({ authenticate })',
+      });
+    }
+    ready = true;
+    markReady();
+    logger.info('sync node ready', { buildId: options.buildId, path });
+  };
+
+  /** Ends the current generation and waits out a start in flight, so nothing it took outlives us. */
+  const halt = async (): Promise<void> => {
+    generation += 1;
+    ready = false;
+    const inFlight = started;
+    started = null;
+    if (inFlight !== null) await inFlight.catch(() => undefined);
+  };
+
   return {
     sockets,
     path,
+    principalSockets: (principal) => principals.count(principal),
 
     get ready(): boolean {
       return ready;
     },
 
-    async start(): Promise<void> {
-      changes = await options.transport.subscribe(CHANGE_SUBJECT_ALL, (payload) => {
-        const envelope = parseEnvelope(payload);
-        if (!envelope) return;
-        // Fanout is at-most-once over core NATS, so a reconnect is changes this node never saw.
-        // Nothing downstream could notice: no window's lsn moved, so no cursor moved, so nothing
-        // ever asked for a re-snapshot. A gap invalidates every window here instead, and the
-        // subscribers are re-served on the next change to each query.
-        if (gaps.observe(envelope)) {
-          const marked = options.registry.invalidate();
-          // Channels too: their seq is minted from what this node sees, so the hole is invisible
-          // to a ring that would otherwise replay across it as complete history.
-          const channelGaps = options.hub.invalidate();
-          logger.warn('live.change_gap', {
-            entity: envelope.change.entity,
-            desynced: marked,
-            channelGaps,
-          });
-        }
-        // Not awaited: the bus handler must return before the next change, and ordering is the
-        // registry's — one serial lane per query id. What this call site owes is the failure. An
-        // unhandled rejection here is a fanout that reached nobody, reported as a dead process.
-        detach(options.registry.deliver(envelope.change), 'live.deliver', envelope.change.entity);
-        // The same stream feeds the declared channels: a write names no channel (axiom 2), and the
-        // hub turns this change into `records` frames on every channel it touches.
-        options.hub.deliverChange(envelope.change);
-      });
-      // A bus that reconnected is changes this node never saw, and the gap detector only notices
-      // on the NEXT message: with no later write, every window and cursor here stayed behind and
-      // every new subscriber joined the stale window. Said by the transport, repaired now.
-      reconnects = options.transport.onReconnect(() => {
-        gaps.forget();
-        const marked = options.registry.invalidate();
-        const channelGaps = options.hub.invalidate();
-        logger.warn('live.bus_reconnected', { desynced: marked, channelGaps });
+    start(): Promise<void> {
+      // Memoised: two overlapping starts were two subscriptions, every change fanned out twice.
+      if (started !== null) return started;
+      // Cleared only if it is still THIS attempt's memo: an older start failing after a stop and
+      // a newer start must not wipe the newer one, or a third start subscribes a second time.
+      const attempt: Promise<void> = begin().catch((error: unknown) => {
+        if (started === attempt) started = null;
+        throw error;
       });
-      // One pass per heartbeat window: a member is swept only once it has actually missed its
-      // window, and the interval never holds the process open — shutdown is the drain's job.
-      if (presence) {
-        sweeping = setInterval(
-          () => detach(presence.sweepAll(), 'presence.sweep'),
-          presence.heartbeatMs,
-        );
-        sweeping.unref();
-      }
-      // The half-open connection Bun's own `idleTimeout` renews through its ping/pong: a client
-      // whose frame loop is wedged answers pings and keeps its grant, its subscriptions and its
-      // topic membership. `sweepIdle` was written for this and never called, so `touch()` and the
-      // 120s budget under it decided nothing.
-      idling = setInterval(() => {
-        for (const socket of sockets.idle()) evict(socket, CLOSE.idle, 'idle timeout');
-      }, idleSweepPeriodMs(sockets.idleTimeoutMs));
-      idling.unref();
-      if (options.authenticate) {
-        reauthing = setInterval(
-          () => detach(reauthenticate(), 'sync.reauthenticate'),
-          bounds.reauthenticateIntervalMs,
-        );
-        reauthing.unref();
-      } else {
-        // Enforced where it can be: nothing here can invent a credential, so the one honest signal
-        // is that every policy on this node is about to be asked about `null`.
-        logger.warn('sync node has no authenticator: every socket is anonymous', {
-          buildId: options.buildId,
-          fix: 'pass authenticate to createSyncNode({ authenticate })',
-        });
-      }
-      ready = true;
-      markReady();
-      logger.info('sync node ready', { buildId: options.buildId, path });
+      started = attempt;
+      return attempt;
     },
 
     stopAccepting(): void {
@@ -330,8 +324,13 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     },
 
     async stop(): Promise<void> {
-      ready = false;
+      // `halt()` ends the generation synchronously, before its first await; what the current
+      // start installed is released right then. An older start still in flight is fenced by its
+      // generation and drops what it subscribes late itself, and a start() issued after this line
+      // owns a fresh bus that the wait below must not touch.
+      const waiting = halt();
       release();
+      await waiting;
     },
 
     async fetch(request: Request, server: UpgradeTarget): Promise<Response | undefined> {
@@ -346,15 +345,20 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           // is parked inside `authenticate`, which is the whole reason they are functions.
           ready: () => ready,
           socketCount: () => sockets.count,
-          newSocketId: () => uuid(),
+          newSocketId: () => uuidV7(),
           authenticate: options.authenticate,
           allowedOrigins: options.allowedOrigins,
           admitReachedOrigin: options.admitReachedOrigin,
+          clientAddressOf: options.clientAddressOf,
           healthDetailPeers: options.healthDetailPeers ?? DEFAULT_HEALTH_DETAIL_PEERS,
           onGranted: (socketId, grant) => grants.set(socketId, grant),
           // The other half of recording the grant before the upgrade: an upgrade that never took
           // gets no `close` callback, so this is the only thing that can free its entry.
-          onUngranted: (socketId) => grants.delete(socketId),
+          onUngranted: (socketId) => {
+            grants.delete(socketId);
+            principals.release(socketId);
+          },
+          principals,
         },
         request,
         server,
@@ -384,6 +388,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           clientBuildId: ws.data.clientBuildId,
           serverBuildId: options.buildId,
           actor: grants.get(ws.data.socketId)?.actor ?? null,
+          clientAddress: ws.data.clientAddress ?? null,
           clock,
           ...ceilings,
         });
@@ -434,6 +439,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           // The socket is already gone, but a grant recorded for an upgrade whose `open` never ran
           // is not — and nothing else would ever reach it.
           grants.delete(ws.data.socketId);
+          principals.release(ws.data.socketId);
           return;
         }
         teardown(socket);
@@ -441,7 +447,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     },
 
     async drain(drainOptions = {}): Promise<readonly DrainedSocket[]> {
-      ready = false;
+      await halt();
       const ids = [...sockets.all()].map((socket) => socket.id);
       const spread = drainPlan(ids, {
         spreadMs: bounds.drainSpreadMs,

package/src/sync-origin.ts

@@ -33,7 +33,7 @@ export function upgradeOrigin(
     origin,
     secFetchSite: request.headers.get('sec-fetch-site'),
     listed: (asked) => admitted.includes(asked),
-    listName: 'APP_URL or createSyncNode({ allowedOrigins })',
+    listName: 'APP_URL or syncNode({ allowedOrigins })',
   });
 }
 

package/src/sync-protocol.ts

@@ -2,7 +2,12 @@
 // 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 {
+  isWriteDigest,
+  renderThrowable,
+  stringField,
+  WRITE_DIGEST_LENGTH,
+} from '@ultimat3/core/page';
 import type {
   ChannelEventsFrame,
   ChannelRecordsFrame,
@@ -11,7 +16,7 @@ import type {
 } from './channel-wire';
 import type { LiveCursor } from './cursor';
 import {
-  isJsonObject,
+  isParsedJsonObject,
   isRow,
   type JsonObject,
   type JsonValue,
@@ -37,6 +42,8 @@ export interface WireError {
   readonly cause: string;
   readonly fix: string;
   readonly docs?: string;
+  /** When a retry can succeed — a rate-limited subscribe's refill. Whole seconds, positive. */
+  readonly retryAfterSeconds?: number;
 }
 
 export interface PresenceMember {
@@ -116,6 +123,12 @@ export interface SnapshotFrame {
    * derives a key.
    */
   readonly keys?: readonly string[];
+  /**
+   * The writes this server truth already holds, named as `PatchFrame.writes` names them — only
+   * writes behind a row in `rows`, so never one this subscriber may not see. Optional and additive:
+   * no `PROTOCOL_VERSION` bump, for the reason `entity` needs none.
+   */
+  readonly writes?: readonly string[];
 }
 
 export interface PatchFrame {
@@ -124,6 +137,15 @@ export interface PatchFrame {
   readonly sid: string;
   readonly patches: readonly RowPatch[];
   readonly lsn: string;
+  /**
+   * The writes that made these patches: `writeDigest` of each keyed request's idempotency key
+   * (`@ultimat3/core`), never the key, as `ChannelRecordsFrame.write` names one. A live patch names
+   * at most one; a delta resume names every write behind a patch it replays. Absent when no keyed
+   * request made any of them. The page that holds one pending settles it in the frame's own batch.
+   * Additive and optional: a decoder one deploy behind drops it, and a frame without it is read as
+   * it always was — so no `PROTOCOL_VERSION` bump.
+   */
+  readonly writes?: readonly string[];
 }
 
 export interface AckFrame {
@@ -192,7 +214,7 @@ export function decode(raw: string | Uint8Array): Frame {
   } catch {
     throw fail('frame is not JSON');
   }
-  if (!isJsonObject(parsed)) throw fail('frame is not an object');
+  if (!isParsedJsonObject(parsed)) throw fail('frame is not an object');
   const version = parsed['v'];
   if (version !== PROTOCOL_VERSION) {
     throw new ProtocolVersionError({ got: version, expected: PROTOCOL_VERSION });
@@ -228,7 +250,9 @@ export function decode(raw: string | Uint8Array): Frame {
         cursor: cursor(parsed['cursor']),
       } as const;
       const entity = nullableStr(parsed, 'entity');
-      const scoped = entity === null ? base : { ...base, entity };
+      const writes = writesOf(parsed, 'snapshot.writes');
+      const named = writes.length === 0 ? base : { ...base, writes };
+      const scoped = entity === null ? named : { ...named, 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');
@@ -237,14 +261,17 @@ export function decode(raw: string | Uint8Array): Frame {
       if (keys.length !== base.rows.length) throw fail('snapshot.keys must pair with rows');
       return { ...scoped, keys };
     }
-    case 'patch':
-      return {
+    case 'patch': {
+      const base = {
         type: 'patch',
         v: PROTOCOL_VERSION,
         sid: str(parsed, 'sid'),
         patches: list(parsed, 'patches', FRAME_LIMITS.patches).map(patch),
         lsn: str(parsed, 'lsn'),
-      };
+      } as const;
+      const writes = writesOf(parsed, 'patch.writes');
+      return writes.length === 0 ? base : { ...base, writes };
+    }
     case 'ack':
       return {
         type: 'ack',
@@ -285,7 +312,37 @@ export function toWireError(error: unknown): WireError {
   const cause = stringField(error, 'cause') ?? renderThrowable(error);
   const fix = stringField(error, 'fix') ?? 'x doctor realtime';
   const docs = stringField(error, 'docs');
-  return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
+  const base = docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
+  const retryAfterSeconds = retryHintOf(error);
+  return retryAfterSeconds === undefined ? base : { ...base, retryAfterSeconds };
+}
+
+/**
+ * `meta.retryAfterSeconds`, the field `@ultimat3/http`'s `X_RATE_LIMITED` carries — read as totally
+ * as `stringField` reads the rest, because the throwable is app code's and its getters may throw.
+ */
+function retryHintOf(error: unknown): number | undefined {
+  try {
+    const meta: unknown = (error as { readonly meta?: unknown } | null)?.meta;
+    const held: unknown = isParsedJsonObject(meta) ? meta['retryAfterSeconds'] : undefined;
+    return typeof held === 'number' && Number.isFinite(held) && held > 0 ? held : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `writes` on a `patch` or `snapshot`: digests only, capped at the patch ceiling (one write per
+ * patch at most; `snapshotFrame` caps what it sends to the same number). Absent, `null` and `[]`
+ * all name nothing, and read as the frame an older node sends.
+ */
+function writesOf(parsed: JsonObject, label: string): readonly string[] {
+  return list(parsed, 'writes', FRAME_LIMITS.patches, label).map((write) => {
+    if (!isWriteDigest(write)) {
+      throw fail(`${label} must hold ${WRITE_DIGEST_LENGTH}-character lowercase hex digests`);
+    }
+    return write;
+  });
 }
 
 function row(value: unknown): Row {
@@ -294,7 +351,7 @@ function row(value: unknown): Row {
 }
 
 function cursor(value: unknown): LiveCursor {
-  if (!isJsonObject(value)) throw fail('cursor must be an object');
+  if (!isParsedJsonObject(value)) throw fail('cursor must be an object');
   return {
     qid: str(value, 'qid'),
     lsn: str(value, 'lsn'),
@@ -307,7 +364,7 @@ function cursor(value: unknown): LiveCursor {
 }
 
 function patch(value: unknown): RowPatch {
-  if (!isJsonObject(value)) throw fail('patch must be an object');
+  if (!isParsedJsonObject(value)) throw fail('patch must be an object');
   const base = {
     op: pick(value, 'op', ['insert', 'update', 'delete'] as const),
     id: str(value, 'id'),
@@ -320,7 +377,7 @@ function patch(value: unknown): RowPatch {
 }
 
 function target(value: unknown): SubscribeTarget {
-  if (!isJsonObject(value)) throw fail('subscribe.target must be an object');
+  if (!isParsedJsonObject(value)) throw fail('subscribe.target must be an object');
   const kind = pick(value, 'kind', ['query', 'channel'] as const);
   if (kind === 'channel') return channelTarget(value);
   return {
@@ -334,7 +391,10 @@ function target(value: unknown): SubscribeTarget {
 
 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');
+  if (!isParsedJsonObject(value)) throw fail('ack.error must be an object or null');
   const base = { code: str(value, 'code'), cause: str(value, 'cause'), fix: str(value, 'fix') };
-  return value['docs'] === undefined ? base : { ...base, docs: str(value, 'docs') };
+  const documented = value['docs'] === undefined ? base : { ...base, docs: str(value, 'docs') };
+  return value['retryAfterSeconds'] === undefined
+    ? documented
+    : { ...documented, retryAfterSeconds: num(value, 'retryAfterSeconds') };
 }

package/src/sync-upgrade.ts

@@ -12,9 +12,12 @@ import {
 } from '@ultimat3/core';
 import {
   SocketAuthUnavailableError,
+  SocketLimitError,
   SocketOriginRefusedError,
   SocketUnauthenticatedError,
 } from './errors';
+import type { PrincipalSockets } from './principal-sockets';
+import { principalFor } from './subscription-book';
 import type { SyncAuthenticator, SyncGrant } from './sync-auth';
 import { upgradeOrigin } from './sync-origin';
 import { toWireError } from './sync-protocol';
@@ -33,6 +36,11 @@ export interface WsData {
    * forever for having sent no query.
    */
   readonly clientBuildId: string;
+  /**
+   * The caller's address, resolved here once (`clientAddressOf`); `null` when nothing can say.
+   * Optional only for a socket a host builds without this upgrade (a test harness).
+   */
+  readonly clientAddress?: string | null;
 }
 
 /** Structural view of `Bun.serve`'s server object; keeps this module free of a Bun import. */
@@ -66,6 +74,14 @@ export interface UpgradeDeps {
    * (`sync-origin.ts`).
    */
   readonly allowedOrigins?: readonly string[] | undefined;
+  /**
+   * Who the caller is, for keying an anonymous reader's rate limit: the deployment's own rule —
+   * `@ultimat3/http`'s `clientAddress()` under its `TRUSTED_PROXY_HOPS`, injected by the boot so
+   * this package reads no proxy header itself. Absent, the socket's address is the caller.
+   */
+  readonly clientAddressOf?:
+    | ((request: Request, socketAddress: string | null) => string | null)
+    | undefined;
   /** The `Host`-derived origin admitted beside a declared list too — `x dev` only. */
   readonly admitReachedOrigin?: boolean | undefined;
   /**
@@ -89,6 +105,11 @@ export interface UpgradeDeps {
    * same "reserve, then release" shape `channel.ts` uses for a topic slot.
    */
   onUngranted(socketId: string): void;
+  /**
+   * One principal's sockets on this node, keyed as the live-query principal is. Admitted right
+   * before `server.upgrade`; `onUngranted` and the socket's close give the slot back.
+   */
+  readonly principals?: PrincipalSockets | undefined;
 }
 
 /**
@@ -173,7 +194,18 @@ export async function handleUpgrade(
     socketId: deps.newSocketId(),
     // The node's own id is "not skewed until the hello says so", never "current forever".
     clientBuildId: url.searchParams.get('build') ?? deps.buildId,
+    clientAddress: callerAddress(deps, request, server),
   };
+  // Beside the count recheck and for its reason: no await between this and `server.upgrade`, so a
+  // herd of one principal parked in `authenticate` cannot all pass one count.
+  const principal = principalFor(grant?.actor ?? null, data.clientAddress ?? null);
+  if (deps.principals !== undefined && !deps.principals.admit(data.socketId, principal)) {
+    refund();
+    return wireErrorResponse(
+      429,
+      new SocketLimitError({ principal, limit: deps.principals.limitFor(principal) }),
+    );
+  }
   // Before the upgrade, never after: `server.upgrade` runs `websocket.open` synchronously and does
   // not return until it has, so a grant recorded on the next line is one the socket was already
   // built without.
@@ -238,6 +270,13 @@ function health(
   });
 }
 
+function callerAddress(deps: UpgradeDeps, request: Request, server: UpgradeTarget): string | null {
+  const socketAddress = server.requestIP(request)?.address ?? null;
+  return deps.clientAddressOf === undefined
+    ? socketAddress
+    : deps.clientAddressOf(request, socketAddress);
+}
+
 /** Load shedding with a delay attached: refusing without one just moves the herd next door. */
 function shed(deps: UpgradeDeps): Response {
   return new Response('retry', {

package/src/type-pins.ts

@@ -6,7 +6,7 @@
 import type { AsyncState, Row } from '@ultimat3/core';
 import type { LiveHandle, Unsubscribe } from './client-contract';
 import type { QueryAccessor, QueryRef } from './use-query';
-import type { RecordAccessor } from './use-record';
+import type { RecordAccessor, useRecords } from './use-record';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -31,6 +31,14 @@ export type _RecordAnswersAsyncState = Assert<
   Equals<ReturnType<RecordAccessor<FeedRow>>, AsyncState<FeedRow | undefined>>
 >;
 
+/**
+ * `useRecords` takes its selection EXPLICITLY — a key list, or `{}` / `{ where, order }` for the
+ * whole type. A default turned a call that forgot its keys into "every record of the type".
+ */
+export type _UseRecordsSelectionRequired = Assert<
+  Equals<Parameters<typeof useRecords>['length'], 2>
+>;
+
 /**
  * A query ref carries no server field: a `Query` VALUE in an island drags its whole read path into
  * the bundle, so the ref is a name and two declared facts. A `sql` key is refused.