@ultimat3/realtime 24.0.0 → 25.0.0

package/src/page-store.ts

@@ -1,9 +1,14 @@
-// The page's realtime state: ONE record store and ONE sync target per tab, whichever island bundle
-// asks first. On `globalThis` under a `Symbol.for` key, because every island is its own bundle and
-// a module-scope singleton here is one store PER ISLAND — the bug this file exists to end.
+// The page's realtime state as every island READS it: one object per tab on `globalThis` under a
+// `Symbol.for` key, because every island is its own bundle and a module-scope singleton here is
+// one store PER ISLAND. Thin by design — the store, the socket and the transport behind it are the
+// page runtime's (`page-runtime.ts`), shipped once per page and never inside an island (#505).
 
-import { CLIENT_SCOPE_META, onRescope, pageClient } from '@ultimat3/core/page';
-import { RecordStore } from './record-store';
+import type { clientTransport } from '@ultimat3/core/page';
+import { CLIENT_SCOPE_META } from '@ultimat3/core/page';
+import type { queryClientMethodFor } from '@ultimat3/query/client';
+import type { LiveClient } from './client';
+import { RealtimeUninstalledError } from './page-errors';
+import type { RecordStore } from './record-store';
 
 /** Where the page's one socket dials. Resolved on the server and handed to the island bootstrap. */
 export interface SyncTarget {
@@ -15,7 +20,12 @@ export interface SyncTarget {
 
 /** Page-wide and shared by every bundle. Structural on purpose: no `instanceof` across copies. */
 export interface PageRealtime {
-  readonly store: RecordStore;
+  /**
+   * The page's ONE record store — `undefined` until the page runtime is installed (the page boot,
+   * or the runtime chunk an island loads where no boot is rendered). A hook reads it through
+   * `installedPage`, which refuses by code rather than answering a store nobody shares.
+   */
+  store: RecordStore | undefined;
   sync: SyncTarget | undefined;
   /** The socket client, once a live hook opened it. Typed by `page-socket.ts`, its one writer. */
   socket: unknown;
@@ -27,8 +37,30 @@ export interface PageRealtime {
    * the first frame can race it. Resolved at once on a page that carries no boot script.
    */
   readonly booted: Promise<void>;
+  /** What a hook calls instead of bundling it — installed with the store, by the page runtime. */
+  services: PageServices | undefined;
+}
+
+/**
+ * The runtime's half of every hook: the work whose code would otherwise ship in each island. An
+ * island calls these off the page object, so the socket stack, the query client and core's
+ * transport are in the page runtime once, however many islands the page renders.
+ */
+export interface PageServices {
+  /** The page's one socket, opened on the first ask. `hook` names the caller in a refusal. */
+  socket(hook: string): LiveClient;
+  /** A non-live query read over HTTP — `@ultimat3/query`'s client, through core's transport. */
+  read(name: string): ReturnType<typeof queryClientMethodFor>;
+  /** Core's one transport, for a write's POST. */
+  send: typeof clientTransport;
 }
 
+/** The page once its runtime is installed: what every hook works against. */
+export type InstalledPage = PageRealtime & {
+  readonly store: RecordStore;
+  readonly services: PageServices;
+};
+
 /** Every optimistic write on the page, counted per mutator name, and who renders the counts. */
 export interface PageWrites {
   readonly pending: Map<string, number>;
@@ -86,9 +118,32 @@ export function bootedPromise(): Promise<void> {
   return waiting;
 }
 
+/**
+ * Whether a deferred `<script>` of this document may still run. Not past `loading`, yes; past
+ * `complete`, no. In between (`interactive`) the deferred scripts run, then DOMContentLoaded fires —
+ * and `readyState` stays `interactive` until every image has loaded, so the navigation timing's
+ * `domContentLoadedEventStart` is what says they have all run (a boot that 404'd among them). A
+ * document with no such reading is assumed still running them: a caller then waits on DOMContentLoaded.
+ */
+export function deferredScriptsPending(): boolean {
+  if (typeof document === 'undefined') return false;
+  const state: unknown = document.readyState;
+  if (state === 'complete') return false;
+  if (state !== 'interactive') return true;
+  const timing: unknown =
+    typeof performance === 'undefined' || typeof performance.getEntriesByType !== 'function'
+      ? undefined
+      : performance.getEntriesByType('navigation')[0];
+  const started: unknown =
+    typeof timing === 'object' && timing !== null
+      ? Reflect.get(timing, 'domContentLoadedEventStart')
+      : undefined;
+  return !(typeof started === 'number' && started > 0);
+}
+
 function bootComing(): boolean {
   if (typeof document === 'undefined' || typeof addEventListener !== 'function') return false;
-  if (document.readyState === 'complete') return false;
+  if (!deferredScriptsPending()) return false;
   // A partial `document` (a component test's stand-in) has no query surface: no tag, no boot.
   if (typeof document.querySelector !== 'function') return false;
   return document.querySelector(`meta[name="${CLIENT_SCOPE_META}"]`) !== null;
@@ -96,25 +151,25 @@ function bootComing(): boolean {
 
 type Host = { [KEY]?: PageRealtime };
 
-/** Get-or-create. Installs the store as core's `RecordSink`, so HTTP answers adopt into it. */
+/**
+ * Get-or-create the page object — never its runtime: an island that asks before the runtime is
+ * installed (`installRealtime` seating a sync target) gets the object the runtime then fills.
+ */
 export function pageRealtime(): PageRealtime {
   const host = globalThis as Host;
   const existing = host[KEY];
   if (existing !== undefined) return existing;
-  const store = new RecordStore();
   const created: PageRealtime = {
-    store,
+    store: undefined,
     sync: undefined,
     socket: undefined,
     writes: { pending: new Map(), failed: 0, listeners: new Set() },
     get booted(): Promise<void> {
       return bootedPromise();
     },
+    services: undefined,
   };
   Object.defineProperty(host, KEY, { value: created, configurable: true });
-  pageClient().store = store;
-  // A new principal sees nothing of the previous one: every record goes, in memory, at once.
-  onRescope(() => store.clear());
   return created;
 }
 
@@ -123,6 +178,18 @@ export function peekPageRealtime(): PageRealtime | undefined {
   return (globalThis as Host)[KEY];
 }
 
+/**
+ * The page with its runtime installed, or `X_REALTIME_UNINSTALLED` naming `hook`. An island `x
+ * build` wrapped never sees the refusal — its bootstrap awaits the runtime before any hook runs.
+ */
+export function installedPage(hook: string): InstalledPage {
+  const page = pageRealtime();
+  if (page.store === undefined || page.services === undefined) {
+    throw new RealtimeUninstalledError({ hook });
+  }
+  return page as InstalledPage;
+}
+
 /**
  * Whether this page holds a socket — `false` on a server render and before any live hook ran.
  * The guard a component with a static fallback asks (an offline banner, an update prompt). Here,
@@ -132,7 +199,7 @@ export function hasPageSocket(): boolean {
   return peekPageRealtime()?.socket !== undefined;
 }
 
-/** The page's record store. */
-export function pageStore(): RecordStore {
-  return pageRealtime().store;
+/** The page's record store, from its installed runtime. */
+export function pageStore(hook = 'pageStore'): RecordStore {
+  return installedPage(hook).store;
 }

package/src/pg-advisory-lock.ts

@@ -13,7 +13,7 @@ import type { Rng } from './thundering-herd';
 /** A key reaches a simple query unparameterised, so its charset is the injection boundary. */
 const KEY_PATTERN = /^[A-Za-z0-9:_.-]+$/;
 
-export interface PgAdvisoryLockOptions {
+export interface PostgresAdvisoryLockOptions {
   /** Connection string for the database whose replicator this is. */
   readonly url: string;
   /** Lock identity, e.g. `x:replicator:<slot>`. Hashed by Postgres, not by us. */
@@ -30,9 +30,9 @@ export interface PgAdvisoryLockOptions {
  * already holds the key would need a matching second `pg_advisory_unlock`, and `release()` only
  * ever issues one, so taking a second grant here would be a leak, not a no-op.
  */
-export class PgAdvisoryLock implements AdvisoryLock {
+export class PostgresAdvisoryLock implements AdvisoryLock {
   readonly key: string;
-  readonly #options: PgAdvisoryLockOptions;
+  readonly #options: PostgresAdvisoryLockOptions;
   #connection: PgConnection | null = null;
   /**
    * The acquisition in flight, if any. `#connection` cannot answer "am I already taking this" —
@@ -47,7 +47,7 @@ export class PgAdvisoryLock implements AdvisoryLock {
   #acquiring: Promise<boolean> | null = null;
   readonly #lostListeners = new Set<(reason: string) => void>();
 
-  constructor(options: PgAdvisoryLockOptions) {
+  constructor(options: PostgresAdvisoryLockOptions) {
     if (!KEY_PATTERN.test(options.key)) {
       throw new ReplicationFailedError({
         stage: 'preflight',
@@ -176,3 +176,8 @@ export class PgAdvisoryLock implements AdvisoryLock {
     }
   }
 }
+
+/** The one way to build the session lock — the twin of `memoryAdvisoryLock()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function postgresAdvisoryLock(options: PostgresAdvisoryLockOptions): PostgresAdvisoryLock {
+  return new PostgresAdvisoryLock(options);
+}

package/src/pg-connection.ts

@@ -118,7 +118,13 @@ export class PgConnection {
       // trips exactly on servers whose default is not already 3. A server that refuses one
       // answers `ErrorResponse` during startup, so the replicator fails to boot with the server's
       // own words — never a warning that a feed then goes on mis-sorting behind.
-      options: '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3',
+      //
+      // `TimeZone=UTC` is the one pin libpqwalreceiver does not send, and it closes the same hole
+      // from the other side: a `timestamptz` is written in the SESSION's zone, so a server, database
+      // or role default like `America/New_York` writes a pre-1883 instant at its LMT offset,
+      // `-04:56:02`. The decoder reads that too, but UTC text is the one form with no ambient zone
+      // in it — and a client option outranks every server-side default, `ALTER ROLE … SET` included.
+      options: '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3 -c TimeZone=UTC',
     };
     if (options.replication !== undefined) parameters['replication'] = options.replication;
     // A handshake fails on ordinary conditions — no password, an ErrorResponse, an EOF — and on

package/src/pg-replication.ts

@@ -4,7 +4,7 @@
 // the lsn is the only authority the pipeline has.
 
 import { type Clock, finiteOption, logger, renderThrowable, systemClock } from '@ultimat3/core';
-import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
+import type { ChangeEvent, ChangeOp, PostgresChangeFeedOptions } from './changefeed';
 import { ReplicationProtocolError } from './errors';
 import { ByteReader, ByteWriter, epochMsToPgTimestamp, printLsn } from './pg-bytes';
 import { PgConnection } from './pg-connection';
@@ -90,11 +90,11 @@ export interface ReplicationStreamHandlers {
 }
 
 /**
- * One slot, one connection, one process. Started by `PgLogicalReplicationFeed`, which is itself
+ * One slot, one connection, one process. Started by `PostgresChangeFeed`, which is itself
  * held by the single `replicator` role — the advisory lock upstream is what keeps that "one" true.
  */
 export class PgReplicationStream {
-  readonly #options: PgLogicalReplicationOptions;
+  readonly #options: PostgresChangeFeedOptions;
   readonly #clock: Clock;
   readonly #entities: ReadonlySet<string>;
   readonly #slot: string;
@@ -116,7 +116,7 @@ export class PgReplicationStream {
   #failure: string | null = null;
   #onEnd: ((reason: string) => void) | undefined;
 
-  constructor(options: PgLogicalReplicationOptions) {
+  constructor(options: PostgresChangeFeedOptions) {
     this.#options = options;
     this.#clock = options.clock ?? systemClock;
     this.#entities = new Set(options.entities.map((name) => assertIdentifier('entity', name)));
@@ -414,7 +414,7 @@ export class PgReplicationStream {
     }
     const { before, after, omitted } = replicatedImages(relation, oldTuple, newTuple, unchanged);
     const event: ChangeEvent = {
-      entity: relation.name,
+      table: relation.name,
       op,
       before,
       after,
@@ -422,7 +422,7 @@ export class PgReplicationStream {
       txid: transaction.xid.toString(10),
       orgId: tenantOf(after ?? before),
       at: transaction.commitAt,
-      ...(transaction.write === undefined ? {} : { write: transaction.write }),
+      write: transaction.write ?? null,
       ...(omitted.length === 0 ? {} : { omitted }),
     };
     await handlers.onChange(event);

package/src/pg-socket.ts

@@ -52,6 +52,23 @@ export interface PgTarget {
   readonly rootCert?: string | undefined;
 }
 
+/**
+ * One URL part, percent-decoded. `decodeURIComponent` throws a bare `URIError` on a stray `%`
+ * (`50%off`), so a password pasted unencoded failed the replicator with no code and no fix.
+ * Refused under the part's NAME, never its value: that is the database credential.
+ */
+function decodeUrlPart(raw: string, part: 'user' | 'password' | 'database'): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `DATABASE_URL has a malformed percent-escape in its ${part}`,
+      fix: `bun -e 'console.log(encodeURIComponent(process.argv[1]))' '<the raw value>'   # then put the result in the ${part} of DATABASE_URL`,
+    });
+  }
+}
+
 /** `postgres://user:pass@host:5432/db?sslmode=require`. The one place a connection URL is read. */
 export function parsePgUrl(url: string): PgTarget {
   let parsed: URL;
@@ -75,13 +92,13 @@ export function parsePgUrl(url: string): PgTarget {
     });
   }
   const { ssl, rootCert } = parseSsl(parsed.searchParams);
-  const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
+  const database = decodeUrlPart(parsed.pathname.replace(/^\//, ''), 'database');
   return {
     host: parsed.hostname,
     port: parsed.port === '' ? 5432 : Number.parseInt(parsed.port, 10),
     database: database === '' ? 'postgres' : database,
-    user: decodeURIComponent(parsed.username) || 'postgres',
-    password: parsed.password === '' ? undefined : decodeURIComponent(parsed.password),
+    user: decodeUrlPart(parsed.username, 'user') || 'postgres',
+    password: parsed.password === '' ? undefined : decodeUrlPart(parsed.password, 'password'),
     ssl,
     rootCert,
   };

package/src/pg-values.ts

@@ -33,13 +33,20 @@ export type PhysicalRow = { [key: string]: PhysicalValue };
 /**
  * `2026-08-09 12:00:00.123456+00` -> the ISO-8601 form `new Date` is specified to accept.
  *
- * Postgres writes a space between the date and the clock, an offset that may be `+00`, `+0530` or
- * `+05:30`, and as many fractional digits as the column's precision. `Date` holds milliseconds, so
- * the fraction is TRUNCATED to three — which is what the driver does on the repository side, so
- * both readers of one column land on the same instant.
+ * Postgres writes a space between the date and the clock, an offset that may be `+00`, `+0530`,
+ * `+05:30` or — for an instant before its zone adopted standard time, a zone's LMT — `-04:56:02`,
+ * and as many fractional digits as the column's precision. `Date` holds milliseconds, so the
+ * fraction is TRUNCATED to three — which is what the driver does on the repository side, so both
+ * readers of one column land on the same instant.
+ *
+ * Seconds only ever follow a colon-separated minute (`EncodeTimezone` in postgres' `datetime.c`),
+ * so `-0456:02` is not a spelling this matches.
  */
 const TIMESTAMP =
-  /^(\d{4,6})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-]\d{2}(?::?\d{2})?)?$/;
+  /^(\d{4,6})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-]\d{2}(?:\d{2}|:\d{2}(?::\d{2})?)?)?$/;
+
+/** `±HH`, `±HHMM`, `±HH:MM`, `±HH:MM:SS` — the zone group of `TIMESTAMP`, taken apart. */
+const OFFSET = /^([+-])(\d{2}):?(\d{2})?:?(\d{2})?$/;
 
 /**
  * `undefined` for a text this decoder does not describe — `infinity`, a BC date, a non-ISO
@@ -61,18 +68,26 @@ function toInstant(text: string): Date | undefined {
   if (parts === null) return undefined;
   const [, year, month, day, hour, minute, second, fraction, zone] = parts;
   const millis = fraction === undefined ? '000' : `${fraction.slice(1)}000`.slice(0, 3);
-  const parsed = new Date(
-    `${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}${offsetOf(zone)}`,
-  );
+  const offset = offsetMillis(zone);
+  if (offset === undefined) return undefined;
+  // Read the wall clock as UTC, then move it by the offset: `Date` has no spelling for a seconds
+  // offset, so handing it the zone would leave an LMT instant as text while the driver, which
+  // reads the binary form, hands the repository its `Date`.
+  const wall = Date.parse(`${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}Z`);
+  if (Number.isNaN(wall)) return undefined;
+  const parsed = new Date(wall - offset);
   return Number.isNaN(parsed.getTime()) ? undefined : parsed;
 }
 
-/** `+05` and `+0530` are offsets postgres writes and `Date` does not read; `±HH:MM` is both. */
-function offsetOf(zone: string | undefined): string {
-  if (zone === undefined || zone === 'Z') return 'Z';
-  if (zone.length === 3) return `${zone}:00`;
-  if (zone.length === 5) return `${zone.slice(0, 3)}:${zone.slice(3)}`;
-  return zone;
+/** East of UTC is positive. `undefined` for a minute or second past 59 — not an offset at all. */
+function offsetMillis(zone: string | undefined): number | undefined {
+  if (zone === undefined || zone === 'Z') return 0;
+  const parts = OFFSET.exec(zone);
+  if (parts === null) return undefined;
+  const [, sign, hours, minutes = '00', seconds = '00'] = parts;
+  if (Number(minutes) > 59 || Number(seconds) > 59) return undefined;
+  const magnitude = (Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds)) * 1000;
+  return sign === '-' ? -magnitude : magnitude;
 }
 
 const HEX = /^[0-9a-fA-F]*$/;

package/src/policy-gate.ts

@@ -1,6 +1,6 @@
-// The single seam between realtime and authz. It goes through `@ultimat3/query`'s `guard`, which
-// is itself the only point of contact with `@ultimat3/policy` — one authz system, never two, and
-// realtime does not get its own opinion about what a decision means.
+// The single seam between realtime and authz. It goes through `@ultimat3/query`'s `guardQuery`,
+// which is itself the only point of contact with `@ultimat3/policy` — one authz system, never two,
+// and realtime does not get its own opinion about what a decision means.
 //
 // The row gate turns a denial into "not visible" instead of an error: a row that fails an actor's
 // policy is dropped, never sent. That is the rule from the live-query pipeline, implemented once.
@@ -8,7 +8,7 @@
 // database is down" are different facts and one of them has to page someone.
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { guard, QueryDeniedError, type QueryPolicy, type QuerySubject } from '@ultimat3/query';
+import { guardQuery, QueryDeniedError, type QueryPolicy, type QuerySubject } from '@ultimat3/query';
 import type { JsonValue, Row } from './json';
 
 export interface GateOptions {
@@ -25,7 +25,7 @@ export function authorizeWithPolicy(
   return async (args) => {
     // No row exists yet at subscribe time; `null` says so rather than leaving the predicate
     // to infer it from an absent field.
-    guard(policy, subjectOf(options, args.actor, args.input, null), 'live');
+    guardQuery(policy, subjectOf(options, args.actor, args.input, null), 'live');
   };
 }
 
@@ -40,10 +40,10 @@ export function visibleWithPolicy<R extends Row = Row>(
 ): (args: { actor: Actor | null; row: R; input: JsonValue }) => Promise<boolean> {
   return async (args) => {
     try {
-      guard(policy, subjectOf(options, args.actor, args.input, args.row), 'live');
+      guardQuery(policy, subjectOf(options, args.actor, args.input, args.row), 'live');
       return true;
     } catch (error) {
-      // `guard` throws `QueryDeniedError` for a decision and for nothing else, so that class is
+      // `guardQuery` throws `QueryDeniedError` for a decision and for nothing else, so that class is
       // the whole of "not visible". A rule that reached for a row and timed out throws something
       // else, and answering `false` to it would report an outage as a permission change: the rows
       // leave the subscriber's screen, `live.rows_denied` counts the drop, and no error reaches

package/src/presence.ts

@@ -6,7 +6,7 @@
 // On the wire it is not a frame kind: a roster change is an `events` frame on the channel the member
 // joined (`channel-presence.ts` is the payload), so only a channel declared `events: true` has one.
 
-import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, finiteOption, systemClock, uuidV7 } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
 import { presenceEvent } from './channel-presence';
 import type { ChannelEventsFrame } from './channel-wire';
@@ -86,7 +86,7 @@ export class PresenceRegistry {
       1,
       finiteOption('presence', 'maxMembers', options.maxMembers ?? DEFAULT_MAX_PRESENCE_MEMBERS),
     );
-    this.#nodeId = options.nodeId ?? uuid();
+    this.#nodeId = options.nodeId ?? uuidV7();
   }
 
   get ttlMs(): number {

package/src/principal-sockets.ts

@@ -0,0 +1,75 @@
+// One principal's open sockets on this node, counted so the upgrade can refuse the next one. The
+// per-actor SUBSCRIPTION cap bounds what a principal holds; this bounds how many sockets it holds it
+// across — each one a grant, a frame budget, a heartbeat and a slot of `maxConnections`.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+
+/**
+ * Sixteen sockets at the per-socket 128 subscriptions is 2,048 — past the per-actor 1,000, so a
+ * legitimate principal's tabs never hit this before they hit the subscription cap, while one
+ * principal can no longer take a node's `maxConnections` for itself.
+ */
+export const DEFAULT_MAX_SOCKETS_PER_ACTOR = 16;
+
+/**
+ * An ANONYMOUS principal is a network, not a person: an office behind one corporate NAT viewing a
+ * public live page is one `address:` key, and held to an actor's 16 it was 16 sockets for the whole
+ * floor. A network gets this many actors' worth — 128 at the default — while a signed-in actor keeps
+ * `maxSocketsPerActor`. The subscription cap is not multiplied.
+ */
+export const ANONYMOUS_SOCKET_MULTIPLIER = 8;
+
+const isNetwork = (principal: string): boolean => principal.startsWith('address:');
+
+/** A COUNT of at least 1, refused as the config key of the same name is. */
+function socketCeiling(value: number | undefined): number {
+  const max = value ?? DEFAULT_MAX_SOCKETS_PER_ACTOR;
+  if (Number.isSafeInteger(max) && max >= 1) return max;
+  throw new ConfigInvalidError({
+    cause: `maxSocketsPerActor (realtime.maxSocketsPerActor) must be a whole number of at least 1, not ${String(max)} — 0 refuses every upgrade, and a fraction or a NaN is a cap no count ever reaches`,
+    fix: `syncNode({ maxSocketsPerActor: ${String(DEFAULT_MAX_SOCKETS_PER_ACTOR)} })   # or realtime: { maxSocketsPerActor: ${String(DEFAULT_MAX_SOCKETS_PER_ACTOR)} } in app.config.ts`,
+    meta: { key: 'realtime.maxSocketsPerActor', value: max },
+  });
+}
+
+/**
+ * Taken at the upgrade — synchronously, right before `server.upgrade`, so a herd parked in
+ * `authenticate` cannot all pass one count — and given back on EVERY path a socket ends: its
+ * close, and an upgrade that threw or declined after the slot was taken. `release` is idempotent.
+ */
+export class PrincipalSockets {
+  readonly max: number;
+  readonly #bySocket = new Map<string, string>();
+  readonly #count = new Map<string, number>();
+
+  constructor(max: number | undefined) {
+    this.max = socketCeiling(max);
+  }
+
+  /** Admit `socketId` under `principal`, or `false` when that principal is at its cap. */
+  admit(socketId: string, principal: string): boolean {
+    const held = this.#count.get(principal) ?? 0;
+    if (held >= this.limitFor(principal)) return false;
+    this.#bySocket.set(socketId, principal);
+    this.#count.set(principal, held + 1);
+    return true;
+  }
+
+  /** The cap `principal` is held to: `max` for an actor, `max × 8` for an anonymous network. */
+  limitFor(principal: string): number {
+    return isNetwork(principal) ? this.max * ANONYMOUS_SOCKET_MULTIPLIER : this.max;
+  }
+
+  release(socketId: string): void {
+    const principal = this.#bySocket.get(socketId);
+    if (principal === undefined) return;
+    this.#bySocket.delete(socketId);
+    const next = (this.#count.get(principal) ?? 0) - 1;
+    if (next > 0) this.#count.set(principal, next);
+    else this.#count.delete(principal);
+  }
+
+  count(principal: string): number {
+    return this.#count.get(principal) ?? 0;
+  }
+}

package/src/query-window.ts

@@ -80,7 +80,7 @@ export interface PendingRead {
   readonly result: Promise<SnapshotResult>;
 }
 
-export function createEntry(
+export function queryEntry(
   qid: string,
   definition: LiveQueryDefinition,
   input: JsonValue,