@ultimat3/realtime 23.0.0 → 25.0.0

package/src/server.ts

@@ -4,6 +4,7 @@
 // island realtime promises unbuildable. Every name here has exactly one home; the shared
 // vocabulary (the wire, the errors, `Row`, the backoff) stays on `@ultimat3/realtime`.
 
+export { type AdvisoryLock, type MemoryAdvisoryLock, memoryAdvisoryLock } from './advisory-lock';
 // ---- the retained change window one node fans out from ------------------------------------------
 export {
   type ChangeBufferOptions,
@@ -18,11 +19,13 @@ export {
   type ChangeFeedStartOptions,
   type ChangeOp,
   formatLsn,
-  InMemoryChangeFeed,
-  type InMemoryChangeFeedOptions,
-  PgLogicalReplicationFeed,
-  type PgLogicalReplicationOptions,
+  type MemoryChangeFeed,
+  type MemoryChangeFeedOptions,
+  memoryChangeFeed,
+  type PostgresChangeFeed,
+  type PostgresChangeFeedOptions,
   parseLsn,
+  postgresChangeFeed,
 } from './changefeed';
 export {
   type ChangeFeedSelection,
@@ -113,24 +116,30 @@ export {
 export { decodeToken, encodeToken, NatsKvSet, type NatsKvSetOptions } from './nats-kv';
 export { openNatsClient } from './nats-open';
 export { NatsTransport, type NatsTransportOptions } from './nats-transport';
-export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
+export {
+  type PostgresAdvisoryLock,
+  type PostgresAdvisoryLockOptions,
+  postgresAdvisoryLock,
+} from './pg-advisory-lock';
 // ---- the postgres replication path ------------------------------------------------------------
 export { entityRow } from './pg-entity-row';
+export { paramsChannelTables } from './pg-identity-tables';
+export { CHANNEL_IDENTITY_EVENT } from './pg-preflight';
 export {
   changeLsn,
   commitPositionOf,
   type ReplicationStreamStats,
 } from './pg-replication';
 export { bunPgStream, type PgTarget, parsePgUrl, type SslMode } from './pg-socket';
+export { answersWeakAuth } from './pg-tls';
 // The value domain a WAL tuple lands in. Public because it is `PgOutputMessage`'s and
 // `entityRow`'s: a caller naming either type has to be able to name what is inside one.
 export { decodeValue, type PhysicalRow, type PhysicalValue } from './pg-values';
 export type { PgStream } from './pg-wire';
-export {
-  type PgColumn,
-  PgOutputDecoder,
-  type PgOutputMessage,
-  type PgRelation,
+export type {
+  PgColumn,
+  PgOutputMessage,
+  PgRelation,
 } from './pgoutput';
 export { authorizeWithPolicy, type GateOptions, visibleWithPolicy } from './policy-gate';
 export {
@@ -143,43 +152,55 @@ export {
   type PresenceRoster,
   presenceFrame,
 } from './presence';
+export { ANONYMOUS_SOCKET_MULTIPLIER, DEFAULT_MAX_SOCKETS_PER_ACTOR } from './principal-sockets';
 export {
-  createEntry,
   DEFAULT_READ_DEADLINE_MS,
   type EntryOptions,
   fillWindow,
   orgIdOf,
   type PendingRead,
   type QueryEntry,
+  queryEntry,
   refillWindowInLane,
 } from './query-window';
+// ---- channel records with no replicator: an app's committed rows, published by the app ----------
+export {
+  type PublishOptions,
+  type RecordPublisher,
+  type RecordPublisherOptions,
+  recordPublisher,
+} from './record-publisher';
 export {
-  type AdvisoryLock,
   CHANGE_SUBJECT_PREFIX,
-  type ChangeEnvelope,
+  changeFeedReplicator,
   changeSubject,
-  createReplicator,
-  InMemoryAdvisoryLock,
   normalize,
-  parseChange,
-  parseEnvelope,
   type Replicator,
   type ReplicatorOptions,
   type ReplicatorStats,
-  SeqGapDetector,
 } from './replicator';
+export {
+  type ChangeEnvelope,
+  type EnvelopeSource,
+  encodeEnvelope,
+  parseChange,
+  parseEnvelope,
+  SeqGapDetector,
+} from './replicator-envelope';
 export {
   actorIdOf,
   CLOSE,
-  DEFAULT_FRAME_BURST,
-  DEFAULT_MAX_BUFFERED_BYTES,
-  DEFAULT_MAX_FRAMES_PER_SECOND,
   SocketRegistry,
   type SocketRegistryOptions,
   SyncSocket,
   type SyncSocketOptions,
   type WsLike,
 } from './socket';
+export {
+  DEFAULT_FRAME_BURST,
+  DEFAULT_MAX_BUFFERED_BYTES,
+  DEFAULT_MAX_FRAMES_PER_SECOND,
+} from './socket-defaults';
 export { DEFAULT_IDLE_TIMEOUT_MS, idleSweepPeriodMs } from './socket-idle';
 export type {
   GateFailed,
@@ -188,6 +209,7 @@ export type {
   Subscriber,
   SubscriberGateOptions,
 } from './subscriber-gate';
+export { DEFAULT_MAX_PER_ACTOR, DEFAULT_MAX_PER_SOCKET } from './subscription-book';
 export {
   GrantBook,
   type GrantSweepDeps,
@@ -197,9 +219,9 @@ export {
   sweepGrants,
 } from './sync-auth';
 export {
-  createFrameRouter,
   type FrameRouter,
   type FrameRouterOptions,
+  frameRouter,
 } from './sync-frames';
 export {
   type ListenOptions,
@@ -207,13 +229,13 @@ export {
   type SyncListener,
 } from './sync-listen';
 export {
-  createSyncNode,
   DEFAULT_MAX_CONNECTIONS,
   DEFAULT_MAX_FRAME_BYTES,
   DEFAULT_REAUTH_INTERVAL_MS,
   type SyncNode,
   type SyncNodeOptions,
   type SyncWs,
+  syncNode,
   type UpgradeTarget,
   type WsData,
 } from './sync-node';

package/src/socket-defaults.ts

@@ -0,0 +1,20 @@
+// The default ceilings one server socket is built with. Split from `socket.ts` at its size
+// ceiling: the socket owns behaviour, this owns the numbers it and `sync-node.ts` agree on.
+
+/**
+ * What one socket may ask this node to do per second, and how much of it may arrive at once.
+ *
+ * The burst clears `DEFAULT_MAX_PER_SOCKET` (128) plus a `hello`, because that is exactly what a
+ * legitimate client sends on connect; the sustained rate is well under the ~155 frames/s measured
+ * to consume a node through the subscribe path's amplifiers.
+ */
+export const DEFAULT_MAX_FRAMES_PER_SECOND = 64;
+export const DEFAULT_FRAME_BURST = 256;
+/**
+ * Queued-but-unwritten bytes on one server socket before `send` declines and marks the subscriber
+ * desynced. `sync-node.ts` hands the same number to Bun as `backpressureLimit` rather than spelling
+ * it again: they are one socket's one buffer, and a check the runtime's own limit fires before is a
+ * check that never runs. The client half (`client-mutations.ts`) is deliberately its own constant —
+ * it is browser code, and importing this file would pull the node's socket registry into the tab.
+ */
+export const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024;

package/src/socket-engine.ts

@@ -173,6 +173,9 @@ export class SocketEngine {
     switch (frame.type) {
       case 'hello':
         this.#hello = frame;
+        // The node names the beat. Every tab hears the same number on its next beat (this frame is
+        // what `#helloReply` answers with), so the socket and the ports keep one rhythm.
+        if (frame.heartbeatMs !== undefined) this.#heartbeat.follow(frame.heartbeatMs);
         return;
       case 'snapshot':
       case 'patch':
@@ -301,12 +304,21 @@ export class SocketEngine {
     if (this.#reaper !== null) return;
     this.#reaper = this.#schedule(() => {
       this.#reaper = null;
-      const cutoff = this.#now() - REAP_AFTER_BEATS * this.#beatMs;
+      const cutoff = this.#now() - REAP_AFTER_BEATS * this.#portBeatMs();
       for (const attached of [...this.#ports.values()]) {
         if (attached.lastSeen < cutoff) this.#reap(attached);
       }
       if (this.#ports.size > 0) this.#armReaper();
-    }, this.#beatMs);
+    }, this.#portBeatMs());
+  }
+
+  /**
+   * The slowest a healthy tab can be beating: its own default until it hears the node's `hello`,
+   * the node's figure after. The LONGER of the two — a tab is never reaped for keeping a beat the
+   * node asked for, nor for not having heard a shorter one yet.
+   */
+  #portBeatMs(): number {
+    return Math.max(this.#beatMs, this.#heartbeat.intervalMs);
   }
 
   #beat(): void {

package/src/socket-idle.ts

@@ -6,7 +6,9 @@
  * inactivity budget and not Bun's transport one: Bun's `idleTimeout` is renewed by its own
  * ping/pong, so a client whose TCP stack still answers pings while its frame loop is wedged holds
  * its grant, its subscriptions and its topic membership forever. A beating client sends a `hello`
- * every `DEFAULT_HEARTBEAT_MS` (15s), so this is eight missed beats.
+ * every `DEFAULT_HEARTBEAT_MS` (10s), so this is twelve missed beats — and it stays a multiple of
+ * the beat whatever either is set to: the node TELLS the client its beat (`hello.heartbeatMs`),
+ * never slower than a quarter of this budget (`clientHeartbeatMs`, `sync-node-bounds.ts`).
  */
 export const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 

package/src/socket-routes.ts

@@ -122,9 +122,14 @@ export class PortRouter {
     }
     if (held.ports.has(attached.id)) return;
     held.ports.add(attached.id);
-    // The node never hears this add, so it cannot answer it with the `replay-gap` a fresh seat
-    // gets; the engine does. With no epoch yet, the node's own answer is still on its way and now
-    // reaches this port too.
+    // Forwarded as a BEAT (no `since`): to the node it is the seat it already holds, repeated, and
+    // what a seated socket is answered with is the room's roster — the only frame an events-only
+    // channel ever gets, so unforwarded this tab read `joining` until the next beat, and with no
+    // presence on the node, until the first app event.
+    this.#deps.send(withoutSince(held.add));
+    // A beat is never answered with the `replay-gap` a fresh seat gets, so the engine says it.
+    // With no epoch yet, the node's own answer to the first add is on its way and reaches this
+    // port too.
     if (held.epoch === null) return;
     const gap: Frame = {
       type: 'replay-gap',

package/src/socket.ts

@@ -14,7 +14,7 @@ import {
   logger,
   recordConnection,
   systemClock,
-  uuid,
+  uuidV7,
 } from '@ultimat3/core';
 import { GapRepairs } from './channel-gaps';
 import type { ChannelRecordsFrame } from './channel-wire';
@@ -55,6 +55,11 @@ export interface SyncSocketOptions {
   readonly clientBuildId: string;
   readonly serverBuildId: string;
   readonly actor?: Actor | null;
+  /**
+   * The caller's address, resolved ONCE at the upgrade (`UpgradeDeps.clientAddressOf`) — the
+   * only subject an anonymous reader has. `null` when the host cannot say.
+   */
+  readonly clientAddress?: string | null;
   readonly id?: string;
   readonly clock?: Clock;
   /** Frames are dropped rather than queued past this. See `desynced`. */
@@ -66,23 +71,11 @@ export interface SyncSocketOptions {
   readonly frameBurst?: number;
 }
 
-/**
- * What one socket may ask this node to do per second, and how much of it may arrive at once.
- *
- * The burst clears `DEFAULT_MAX_PER_SOCKET` (128) plus a `hello`, because that is exactly what a
- * legitimate client sends on connect; the sustained rate is well under the ~155 frames/s measured
- * to consume a node through the subscribe path's amplifiers.
- */
-export const DEFAULT_MAX_FRAMES_PER_SECOND = 64;
-export const DEFAULT_FRAME_BURST = 256;
-/**
- * Queued-but-unwritten bytes on one server socket before `send` declines and marks the subscriber
- * desynced. `sync-node.ts` hands the same number to Bun as `backpressureLimit` rather than spelling
- * it again: they are one socket's one buffer, and a check the runtime's own limit fires before is a
- * check that never runs. The client half (`client-mutations.ts`) is deliberately its own constant —
- * it is browser code, and importing this file would pull the node's socket registry into the tab.
- */
-export const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024;
+import {
+  DEFAULT_FRAME_BURST,
+  DEFAULT_MAX_BUFFERED_BYTES,
+  DEFAULT_MAX_FRAMES_PER_SECOND,
+} from './socket-defaults';
 
 /**
  * Channel frames this process dropped under backpressure. A dropped `records` frame is now marked
@@ -142,6 +135,7 @@ export class SyncSocket {
   readonly frameBudget: AcceptBudget;
 
   actor: Actor | null;
+  readonly clientAddress: string | null;
   /**
    * MONOTONIC milliseconds, not an instant — the idle sweep measures a duration, and a duration
    * read off the wall clock is decided by whatever NTP last wrote. A step forward evicts sockets
@@ -163,10 +157,11 @@ export class SyncSocket {
   constructor(options: SyncSocketOptions) {
     this.#ws = options.ws;
     this.#clock = options.clock ?? systemClock;
-    this.id = options.id ?? uuid();
+    this.id = options.id ?? uuidV7();
     this.#clientBuildId = options.clientBuildId;
     this.serverBuildId = options.serverBuildId;
     this.actor = options.actor ?? null;
+    this.clientAddress = options.clientAddress ?? null;
     this.#maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
     finiteOption('SyncSocket', 'maxBufferedBytes', this.#maxBufferedBytes);
     this.#maxDroppedFrames = options.maxDroppedFrames ?? 32;

package/src/subscriber-gate.ts

@@ -7,6 +7,7 @@ import type { Actor } from '@ultimat3/core';
 import { isPolicyDenial } from './errors';
 import type { JsonValue, Row, RowPatch } from './json';
 import type { LiveQueryDefinition } from './live-contract';
+import { narrowRow, projectionOf } from './matcher-bridge';
 
 /**
  * Who a decision is being made for. Every policy call in the live pipeline takes one, which is the
@@ -219,7 +220,16 @@ export class SubscriberGate {
     // subscriber is not entitled to keep, and one that holds it is told so.
     if (full === undefined) return holds ? withdrawn(patch) : null;
     const row: Row = { ...full, ...patch.row, id: patch.id };
-    if (await this.#visible(target, who, row, 'patch')) return patch;
+    if (await this.#visible(target, who, row, 'patch')) {
+      // An update carries the changed columns only. A subscriber who was never sent this row —
+      // denied at its snapshot, admitted by this change — would fold them onto nothing, and its
+      // cursor would never record the id, so the row's later delete was withheld from it. It gets
+      // the whole row as an insert, which is also what makes `Holding` and `advance` count it.
+      if (patch.op === 'update' && !holds) {
+        return { ...patch, op: 'insert', row: narrowRow(row, projectionOf(target.rows)) };
+      }
+      return patch;
+    }
     this.#denied(target.qid, who, patch.id);
     return holds ? withdrawn(patch) : null;
   }

package/src/subscription-book.ts

@@ -1,13 +1,14 @@
 // Who holds which subscription, and the composite identity that makes that answerable. A `sid`
 // is CLIENT data — unique only to the socket that chose it — so every lookup here takes the
-// owner too, and the per-socket and per-tenant caps are answered from this book because it is
-// the only thing that knows what exists. Every question it answers is indexed, never scanned.
+// owner too, and the per-socket, per-tenant and per-actor caps are answered from this book because
+// it is the only thing that knows what exists. Every question it answers is indexed, never scanned.
 
 import type { Actor } from '@ultimat3/core';
-import { finiteOption } from '@ultimat3/core';
+import { addressNetwork, ConfigInvalidError, finiteOption, isAnonymous } from '@ultimat3/core';
 import { SubscriptionIdTakenError, SubscriptionLimitError } from './errors';
 import type { LiveSubscription } from './live-contract';
 import type { SyncSocket } from './socket';
+import { CappedCount } from './subscription-count';
 
 /**
  * A slot taken synchronously at the top of `subscribe` and given back when it has either become a
@@ -32,11 +33,50 @@ export interface SubscriptionCaps {
   readonly maxPerSocket?: number;
   readonly maxPerTenant?: number;
   readonly tenantOf?: (actor: Actor | null) => string | null;
+  /** Live subscriptions one actor may hold on this node, across all of its sockets. */
+  readonly maxPerActor?: number;
 }
 
 /** Sockets may open this many live queries before `X_SUBSCRIPTION_LIMIT`. */
 export const DEFAULT_MAX_PER_SOCKET = 128;
 
+/**
+ * One actor's share of a node, across every socket it opens. A tenth of `DEFAULT_MAX_ENTRIES`
+ * (10,000), so no single actor reaches the node cap — before it, 79 sockets at 128 each filled the
+ * node and every other user's next subscribe was refused — and eight tabs at the per-socket 128
+ * still fit under it. `@ultimat3/core`'s `realtime.maxSubscriptionsPerActor` defaults to the same
+ * number; `runtime-realtime.test.ts` in `@ultimat3/cli` holds the two together.
+ */
+export const DEFAULT_MAX_PER_ACTOR = 1_000;
+
+/**
+ * Who a socket counts against for the per-actor caps (subscriptions, and sockets at the upgrade):
+ * the actor, or — anonymous — the NETWORK of the client address resolved at the upgrade
+ * (`addressNetwork`: IPv4 exact, IPv6 by /64), so a visitor with no account is bounded too, and one
+ * IPv6 host cannot rotate through its /64 for a fresh budget per address. A socket that names
+ * neither shares ONE principal, `address:unknown`: fail closed, bounded together, not unbounded.
+ */
+export function principalOf(socket: Pick<SyncSocket, 'actor' | 'clientAddress'>): string {
+  return principalFor(socket.actor, socket.clientAddress);
+}
+
+/** The same key from its two parts — the upgrade has them before any socket exists. */
+export function principalFor(actor: Actor | null, clientAddress: string | null): string {
+  if (actor !== null && !isAnonymous(actor)) return `actor:${actor.id}`;
+  return `address:${clientAddress === null ? 'unknown' : addressNetwork(clientAddress)}`;
+}
+
+/** A per-actor ceiling is a COUNT of at least 1, refused as the config key of the same name is. */
+function actorCeiling(value: number | undefined): number {
+  const max = value ?? DEFAULT_MAX_PER_ACTOR;
+  if (Number.isSafeInteger(max) && max >= 1) return max;
+  throw new ConfigInvalidError({
+    cause: `maxPerActor (realtime.maxSubscriptionsPerActor) must be a whole number of at least 1, not ${String(max)} — 0 refuses every subscribe, and a fraction or a NaN is a cap no count ever reaches`,
+    fix: `new LiveQueryRegistry({ maxPerActor: ${String(DEFAULT_MAX_PER_ACTOR)} })   # or realtime: { maxSubscriptionsPerActor: ${String(DEFAULT_MAX_PER_ACTOR)} } in app.config.ts`,
+    meta: { key: 'realtime.maxSubscriptionsPerActor', value: max },
+  });
+}
+
 const SUBJECT = 'the subscription caps';
 
 /**
@@ -60,21 +100,16 @@ export class SubscriptionBook {
   readonly #bySid = new Map<string, LiveSubscription>();
   /** socket id -> its sids. The drop list on close, the retry list on re-auth. */
   readonly #bySocket = new Map<string, Set<string>>();
-  /** tenant -> live subscriptions held by its sockets. The per-tenant cap's whole answer. */
-  readonly #perTenant = new Map<string, number>();
-  /**
-   * The tenant each socket's subscriptions were counted under. Remembered rather than re-derived,
-   * because `socket.actor` is replaced by a re-auth: deriving it again at `delete` time would
-   * decrement a tenant that was never incremented and leave the old one counting forever.
-   */
-  readonly #tenantOfSocket = new Map<string, string>();
   /** sids a socket has claimed but not yet attached. Empty between subscribes, so it never grows. */
   readonly #claimedBySocket = new Map<string, Set<string>>();
-  /** The same claims counted per tenant, because that cap spans sockets and a lane cannot see it. */
-  readonly #claimedPerTenant = new Map<string, number>();
+  /** The keys each in-flight claim was counted under, by `(socket, sid)` — read at attach. */
+  readonly #claimKeys = new Map<string, { tenant: string | null; actor: string | null }>();
+  /** The caps that span sockets: one per tenant (opt-in), one per actor (always). */
+  readonly #tenants: CappedCount;
+  readonly #actors: CappedCount;
   readonly #caps: SubscriptionCaps;
   /**
-   * BOTH caps screened here, once, rather than on the subscribe path — and `maxPerTenant` was not
+   * Every cap screened here, once, rather than on the subscribe path — and `maxPerTenant` was not
    * screened at all: it has no `??` default, which is the one shape `bun run finite-bounds` states
    * in its own header that it cannot see. `count >= NaN` is false, so the only cap that spans the
    * sockets of one tenant was off in silence; measured, a book built with `maxPerTenant: NaN`
@@ -82,7 +117,6 @@ export class SubscriptionBook {
    * caller is saying "no per-tenant cap" rather than handing a number that is not one.
    */
   readonly #maxPerSocket: number;
-  readonly #maxPerTenant: number | undefined;
 
   constructor(caps: SubscriptionCaps = {}) {
     this.#caps = caps;
@@ -91,10 +125,21 @@ export class SubscriptionBook {
       'maxPerSocket',
       caps.maxPerSocket ?? DEFAULT_MAX_PER_SOCKET,
     );
-    this.#maxPerTenant =
-      caps.maxPerTenant === undefined
-        ? undefined
-        : finiteOption(SUBJECT, 'maxPerTenant', caps.maxPerTenant);
+    this.#tenants = new CappedCount({
+      principalOf: (socket) => this.#caps.tenantOf?.(socket.actor) ?? null,
+      max:
+        caps.maxPerTenant === undefined
+          ? undefined
+          : finiteOption(SUBJECT, 'maxPerTenant', caps.maxPerTenant),
+      scope: 'tenant',
+      knob: 'maxPerTenant',
+    });
+    this.#actors = new CappedCount({
+      principalOf,
+      max: actorCeiling(caps.maxPerActor),
+      scope: 'actor',
+      knob: 'realtime.maxSubscriptionsPerActor',
+    });
   }
 
   get(socketId: string, sid: string): LiveSubscription | undefined {
@@ -115,10 +160,8 @@ export class SubscriptionBook {
     const sids = this.#bySocket.get(socketId);
     if (sids) sids.add(subscription.sid);
     else this.#bySocket.set(socketId, new Set([subscription.sid]));
-    const tenant = this.#tenantFor(subscription.socket);
-    if (tenant === null) return;
-    this.#tenantOfSocket.set(socketId, tenant);
-    this.#perTenant.set(tenant, (this.#perTenant.get(tenant) ?? 0) + 1);
+    this.#tenants.added(subscription.socket);
+    this.#actors.added(subscription.socket);
   }
 
   delete(socketId: string, sid: string): void {
@@ -127,10 +170,8 @@ export class SubscriptionBook {
     sids?.delete(sid);
     const empty = sids === undefined || sids.size === 0;
     if (empty) this.#bySocket.delete(socketId);
-    const tenant = this.#tenantOfSocket.get(socketId);
-    if (tenant === undefined) return;
-    this.#bump(tenant, -1);
-    if (empty) this.#tenantOfSocket.delete(socketId);
+    this.#tenants.deleted(socketId, empty);
+    this.#actors.deleted(socketId, empty);
   }
 
   /** A copy, because every caller mutates the book while walking it. */
@@ -152,29 +193,67 @@ export class SubscriptionBook {
 
   /** Live subscriptions counted against one tenant. The metric the cap reads. */
   tenantCount(tenant: string): number {
-    return this.#perTenant.get(tenant) ?? 0;
+    return this.#tenants.count(tenant);
   }
 
   /**
-   * A re-auth moved this socket to another tenant, so its subscriptions move with it. Without
-   * this the count the cap reads drifts from the book for the rest of the process — one tenant
-   * refused for subscriptions it does not hold, another admitted past its cap.
+   * A re-auth moved this socket to another tenant — or another actor — so its subscriptions move
+   * with it. Without this the counts the caps read drift from the book for the rest of the process:
+   * one key refused for subscriptions it does not hold, another admitted past its cap.
    */
   retenant(socket: SyncSocket): void {
     const held = this.#bySocket.get(socket.id)?.size ?? 0;
-    const before = this.#tenantOfSocket.get(socket.id) ?? null;
-    const after = this.#caps.tenantOf?.(socket.actor) ?? null;
-    if (before === after) return;
-    if (before !== null) this.#bump(before, -held);
-    if (after === null) this.#tenantOfSocket.delete(socket.id);
-    else {
-      this.#tenantOfSocket.set(socket.id, after);
-      if (held > 0) this.#perTenant.set(after, (this.#perTenant.get(after) ?? 0) + held);
-    }
+    this.#tenants.reassign(socket, held);
+    this.#actors.reassign(socket, held);
   }
 
   /**
-   * Refuse a subscribe that would exceed a cap. Load shedding, not a crash: both scopes throw
+   * About to attach `(socket, sid)`: if a re-auth moved the socket to another tenant or actor
+   * while the subscribe was in flight, the new key was never asked — ask it now, and refuse when
+   * it is full. Called before the attach writes anything, so a refusal leaves nothing behind.
+   */
+  assertAttachable(socket: SyncSocket, sid: string): void {
+    const claimed = this.#claimKeys.get(subscriptionKey(socket.id, sid));
+    if (claimed === undefined) return;
+    this.#tenants.assertIfMoved(socket, claimed.tenant);
+    this.#actors.assertIfMoved(socket, claimed.actor);
+  }
+
+  /**
+   * How many of this socket's subscriptions a re-auth must refuse so that neither its new tenant
+   * nor its new actor ends above its cap, and the refusal to send each — `null` when all fit.
+   * Asked BEFORE `retenant`, so the refused ones leave the key they were counted under.
+   */
+  overflowOnRekey(
+    socket: SyncSocket,
+  ): { readonly excess: number; readonly error: SubscriptionLimitError } | null {
+    const held = this.#bySocket.get(socket.id)?.size ?? 0;
+    const byActor = this.#actors.overflowOnRekey(socket, held);
+    const byTenant = this.#tenants.overflowOnRekey(socket, held);
+    if (byActor === 0 && byTenant === 0) return null;
+    return byActor >= byTenant
+      ? { excess: byActor, error: this.#actors.refusalFor(socket) }
+      : { excess: byTenant, error: this.#tenants.refusalFor(socket) };
+  }
+
+  /** The socket closed: forget the keys it was counted under, held or not. */
+  forgetSocket(socketId: string): void {
+    this.#tenants.forget(socketId);
+    this.#actors.forget(socketId);
+  }
+
+  /** Sockets either spanning cap still remembers — a leak shows here first. */
+  get trackedSockets(): number {
+    return this.#tenants.remembered + this.#actors.remembered;
+  }
+
+  /** Live subscriptions counted against one principal (`actor:<id>` / `address:<ip>`). */
+  actorCount(principal: string): number {
+    return this.#actors.count(principal);
+  }
+
+  /**
+   * Refuse a subscribe that would exceed a cap. Load shedding, not a crash: every scope throws
    * `X_SUBSCRIPTION_LIMIT` naming which one refused, so the fix line points at one knob.
    *
    * Claims count, because the thing being bounded is work that starts before it is held: a
@@ -192,17 +271,8 @@ export class SubscriptionBook {
         knob: 'maxPerSocket',
       });
     }
-    const perTenant = this.#maxPerTenant;
-    const tenant = this.#tenantFor(socket);
-    if (perTenant === undefined || tenant === null) return;
-    if (this.tenantCount(tenant) + (this.#claimedPerTenant.get(tenant) ?? 0) >= perTenant) {
-      throw new SubscriptionLimitError({
-        scope: 'tenant',
-        id: tenant,
-        limit: perTenant,
-        knob: 'maxPerTenant',
-      });
-    }
+    this.#tenants.assert(socket);
+    this.#actors.assert(socket);
   }
 
   /**
@@ -226,10 +296,10 @@ export class SubscriptionBook {
     const claims = this.#claimedBySocket.get(socketId);
     if (claims) claims.add(sid);
     else this.#claimedBySocket.set(socketId, new Set([sid]));
-    const tenant = this.#tenantFor(socket);
-    if (tenant !== null) {
-      this.#claimedPerTenant.set(tenant, (this.#claimedPerTenant.get(tenant) ?? 0) + 1);
-    }
+    const tenant = this.#tenants.claim(socket);
+    const actor = this.#actors.claim(socket);
+    const claimKey = subscriptionKey(socketId, sid);
+    this.#claimKeys.set(claimKey, { tenant: tenant.principal, actor: actor.principal });
     let released = false;
     return {
       release: (): void => {
@@ -238,22 +308,10 @@ export class SubscriptionBook {
         const held = this.#claimedBySocket.get(socketId);
         held?.delete(sid);
         if (held !== undefined && held.size === 0) this.#claimedBySocket.delete(socketId);
-        if (tenant === null) return;
-        const next = (this.#claimedPerTenant.get(tenant) ?? 0) - 1;
-        if (next > 0) this.#claimedPerTenant.set(tenant, next);
-        else this.#claimedPerTenant.delete(tenant);
+        this.#claimKeys.delete(claimKey);
+        tenant.release();
+        actor.release();
       },
     };
   }
-
-  /** The tenant this socket's subscriptions are counted under: the remembered one, or the actor's. */
-  #tenantFor(socket: SyncSocket): string | null {
-    return this.#tenantOfSocket.get(socket.id) ?? this.#caps.tenantOf?.(socket.actor) ?? null;
-  }
-
-  #bump(tenant: string, by: number): void {
-    const next = (this.#perTenant.get(tenant) ?? 0) + by;
-    if (next > 0) this.#perTenant.set(tenant, next);
-    else this.#perTenant.delete(tenant);
-  }
 }