@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/{HydrationCoordinator.d.ts → OnDemandLoader.d.ts}

@@ -1,32 +1,34 @@
 /**
- * HydrationCoordinator — the lazy-load lane of the sync engine.
+ * Loads model rows on demand — the lazy-load path of the sync engine. When
+ * something needs an entity that the initial bootstrap did not fetch,
+ * {@link OnDemandLoader.fetch | fetch} finds it and populates the
+ * in-memory {@link InstanceCache} so the rest of the engine can read it normally.
  *
- * Bridges "I need this entity but bootstrap didn't fetch it" → pool
- * hydration. Replaces the per-app loader files (documentLoaders,
- * slideLayerLoaders, layoutLoaders, ensureVaultFiles, ensureDataroomFiles)
- * with one engine-level path.
+ * A fetch resolves against three tiers in order, stopping at the first that can
+ * answer:
+ *   1. The object pool — if rows already in memory match the query, return them.
+ *   2. Local storage — if matching rows exist there, hydrate the pool and return.
+ *   3. The network — post the query to `/sync/query`, then hydrate both the pool
+ *      and local storage.
  *
- * Lookup order on `fetch(modelName, where)`:
- *   1. ObjectPool — if rows already match the where, return them (cheap).
- *   2. IndexedDB — if matching rows exist locally, hydrate pool, return.
- *   3. Network — `postQuery` against `/sync/query`, hydrate pool + IDB.
+ * Concurrent calls with the same query key share one in-flight promise, so a
+ * burst of components mounting and asking for the same data on first paint
+ * triggers a single fetch rather than one each.
  *
- * Single-flight dedup: concurrent calls with the same query key share
- * one in-flight promise. Prevents the loader anti-pattern where N
- * components mount and fire N identical hydrations on first paint.
- *
- * The coordinator does NOT replace bootstrap (full sync of `instant`
- * models) or live deltas (WS push). It only fills the gap for `lazy`
- * models accessed by id/where after the engine is ready.
+ * The coordinator does not replace the bootstrap (which fully syncs instantly
+ * loaded models) or the live delta stream (pushed over the WebSocket). It only
+ * fills the gap for lazily loaded models read by id or filter after the engine
+ * is ready.
  */
-import type { ObjectPool } from '../ObjectPool.js';
+import type { InstanceCache } from '../InstanceCache.js';
 import type { Database } from '../Database.js';
 import type { Model } from '../Model.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
+import type { RecoveryClass } from '../errorCodes.js';
 import type { LoadWhere, WhereClause } from '../query/types.js';
 import type { Schema } from '../schema/schema.js';
-export interface HydrationCoordinatorOptions {
-    readonly objectPool: ObjectPool;
+export interface OnDemandLoaderOptions {
+    readonly objectPool: InstanceCache;
     readonly database: Database;
     readonly registry: ModelRegistry;
     readonly schema: Schema;
@@ -42,11 +44,11 @@ export interface HydrationCoordinatorOptions {
 }
 export interface FetchOptions<T> {
     /**
-     * Filter clauses for the lookup. Accepts either the equality-object
-     * form (`{ id: 'abc' }` → `WHERE id = 'abc'`, array values → `IN`)
-     * or the explicit tuple form (`[['name', 'ILIKE', '%Goldman%']]`)
-     * matching the wire `WhereClause[]` 1:1. Multiple entries AND
-     * together. See `LoadWhere` in `../query/types.ts` for the full shape.
+     * Filter clauses for the lookup. Accepts either the equality-object form
+     * (`{ id: 'abc' }` becomes `WHERE id = 'abc'`, and an array value becomes an
+     * `IN`) or the explicit tuple form (`[['name', 'ILIKE', '%Acme%']]`), which
+     * mirrors the wire `WhereClause[]` exactly. Multiple entries combine with AND.
+     * See {@link LoadWhere} for the full shape.
      */
     readonly where?: LoadWhere<T>;
     readonly orderBy?: {
@@ -71,7 +73,7 @@ export interface FetchOptions<T> {
      */
     readonly expand?: readonly string[];
 }
-export declare class HydrationCoordinator {
+export declare class OnDemandLoader {
     private readonly opts;
     private readonly inFlight;
     /**
@@ -85,22 +87,33 @@ export declare class HydrationCoordinator {
     /**
      * Query keys that have been satisfied from the server at least once this
      * session. Once a key is here, repeat reads serve purely from the pool with
-     * NO network: the WebSocket delta stream keeps those pool rows fresh, so
-     * re-running the HTTP query would be redundant polling. This is the ledger
-     * that stops an already-open deck from re-querying on every navigation.
+     * no network round-trip: the WebSocket delta stream keeps those pool rows
+     * fresh, so re-running the HTTP query would be redundant polling. This ledger
+     * is what stops an already-open view from re-querying on every navigation.
      *
      * Cleared on reconnect (see {@link invalidate}) so that, after a connection
      * drop where deltas may have been missed, the next read re-confirms once.
      */
     private readonly hydratedKeys;
     private authTokenProvider;
-    constructor(opts: HydrationCoordinatorOptions);
+    /**
+     * The credential-recovery hook (the store's `recoverFromAuthRejection`),
+     * late-bound like {@link setAuthTokenProvider} because the store does not
+     * exist yet when the coordinator is constructed. Handed to `postQuery` so a
+     * 401 on the lazy lane re-mints through the same single-flight path the
+     * WebSocket probe uses, then replays the query once — instead of silently
+     * returning empty rows against an expired key.
+     */
+    private credentialRecovery;
+    constructor(opts: OnDemandLoaderOptions);
     /**
      * Late-bind the auth token getter. Browser cookie consumers can omit this;
      * bearer consumers need it so lazy HTTP queries use the same credential as
      * bootstrap and the WebSocket.
      */
     setAuthTokenProvider(provider: () => string | null): void;
+    /** Late-bind the auth-recovery backbone. See {@link credentialRecovery}. */
+    setCredentialRecovery(recover: (recovery: RecoveryClass) => Promise<'retry' | 'stop'>): void;
     /** @deprecated Use `setAuthTokenProvider`. */
     setCapabilityTokenProvider(provider: () => string | null): void;
     /**
@@ -132,13 +145,13 @@ export declare class HydrationCoordinator {
      */
     private fetchFromNetwork;
     /**
-     * Fire-and-forget the ONE server confirm for a query that was just served
-     * from local cache but isn't hydrated yet. On success the key is marked
-     * hydrated, so every later read serves pure-local with no network until a
+     * Fires the single background confirm for a query that was just served from
+     * local cache but is not hydrated yet. On success the key is marked hydrated,
+     * so every later read serves purely from local with no network until a
      * reconnect invalidates the ledger. Deduped per query key so a render burst
-     * doesn't stampede. Errors are swallowed — the caller already has a usable
-     * local snapshot, and a failed confirm leaves the key un-hydrated so the
-     * next read simply tries again.
+     * does not stampede. Errors are swallowed — the caller already has a usable
+     * local snapshot, and a failed confirm leaves the key un-hydrated so the next
+     * read simply tries again.
      */
     private scheduleHydratingFetch;
     /**
@@ -173,7 +186,7 @@ export declare class HydrationCoordinator {
      * `postgres.camel` driver leaves behind when the server's SQL
      * bakes `__typename` into a JSONB literal — the driver's
      * snake↔camel transform misreads `__typename` as `_typename` with
-     * a leading underscore and produces `_Typename`. ObjectPool only
+     * a leading underscore and produces `_Typename`. InstanceCache only
      * recognises `__typename`, so without this step nested rows fall
      * through to the 'Unknown' branch and never instantiate.
      */

package/dist/sync/{HydrationCoordinator.js → OnDemandLoader.js}

@@ -1,28 +1,29 @@
 /**
- * HydrationCoordinator — the lazy-load lane of the sync engine.
+ * Loads model rows on demand — the lazy-load path of the sync engine. When
+ * something needs an entity that the initial bootstrap did not fetch,
+ * {@link OnDemandLoader.fetch | fetch} finds it and populates the
+ * in-memory {@link InstanceCache} so the rest of the engine can read it normally.
  *
- * Bridges "I need this entity but bootstrap didn't fetch it" → pool
- * hydration. Replaces the per-app loader files (documentLoaders,
- * slideLayerLoaders, layoutLoaders, ensureVaultFiles, ensureDataroomFiles)
- * with one engine-level path.
+ * A fetch resolves against three tiers in order, stopping at the first that can
+ * answer:
+ *   1. The object pool — if rows already in memory match the query, return them.
+ *   2. Local storage — if matching rows exist there, hydrate the pool and return.
+ *   3. The network — post the query to `/sync/query`, then hydrate both the pool
+ *      and local storage.
  *
- * Lookup order on `fetch(modelName, where)`:
- *   1. ObjectPool — if rows already match the where, return them (cheap).
- *   2. IndexedDB — if matching rows exist locally, hydrate pool, return.
- *   3. Network — `postQuery` against `/sync/query`, hydrate pool + IDB.
+ * Concurrent calls with the same query key share one in-flight promise, so a
+ * burst of components mounting and asking for the same data on first paint
+ * triggers a single fetch rather than one each.
  *
- * Single-flight dedup: concurrent calls with the same query key share
- * one in-flight promise. Prevents the loader anti-pattern where N
- * components mount and fire N identical hydrations on first paint.
- *
- * The coordinator does NOT replace bootstrap (full sync of `instant`
- * models) or live deltas (WS push). It only fills the gap for `lazy`
- * models accessed by id/where after the engine is ready.
+ * The coordinator does not replace the bootstrap (which fully syncs instantly
+ * loaded models) or the live delta stream (pushed over the WebSocket). It only
+ * fills the gap for lazily loaded models read by id or filter after the engine
+ * is ready.
  */
-import { ModelScope } from '../ObjectPool.js';
+import { ModelScope } from '../InstanceCache.js';
 import { AbloValidationError } from '../errors.js';
 import { postQuery } from '../query/client.js';
-export class HydrationCoordinator {
+export class OnDemandLoader {
     opts;
     inFlight = new Map();
     /**
@@ -36,17 +37,30 @@ export class HydrationCoordinator {
     /**
      * Query keys that have been satisfied from the server at least once this
      * session. Once a key is here, repeat reads serve purely from the pool with
-     * NO network: the WebSocket delta stream keeps those pool rows fresh, so
-     * re-running the HTTP query would be redundant polling. This is the ledger
-     * that stops an already-open deck from re-querying on every navigation.
+     * no network round-trip: the WebSocket delta stream keeps those pool rows
+     * fresh, so re-running the HTTP query would be redundant polling. This ledger
+     * is what stops an already-open view from re-querying on every navigation.
      *
      * Cleared on reconnect (see {@link invalidate}) so that, after a connection
      * drop where deltas may have been missed, the next read re-confirms once.
      */
     hydratedKeys = new Set();
     authTokenProvider = null;
+    /**
+     * The credential-recovery hook (the store's `recoverFromAuthRejection`),
+     * late-bound like {@link setAuthTokenProvider} because the store does not
+     * exist yet when the coordinator is constructed. Handed to `postQuery` so a
+     * 401 on the lazy lane re-mints through the same single-flight path the
+     * WebSocket probe uses, then replays the query once — instead of silently
+     * returning empty rows against an expired key.
+     */
+    credentialRecovery = null;
     constructor(opts) {
         this.opts = opts;
+        // Reading the deprecated `getCapabilityToken` is deliberate: it's the
+        // back-compat shim that keeps older callers who still pass it working
+        // until they migrate to `getAuthToken`.
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         this.authTokenProvider = opts.getAuthToken ?? opts.getCapabilityToken ?? null;
     }
     /**
@@ -57,6 +71,10 @@ export class HydrationCoordinator {
     setAuthTokenProvider(provider) {
         this.authTokenProvider = provider;
     }
+    /** Late-bind the auth-recovery backbone. See {@link credentialRecovery}. */
+    setCredentialRecovery(recover) {
+        this.credentialRecovery = recover;
+    }
     /** @deprecated Use `setAuthTokenProvider`. */
     setCapabilityTokenProvider(provider) {
         this.setAuthTokenProvider(provider);
@@ -71,7 +89,7 @@ export class HydrationCoordinator {
         const ModelClass = this.opts.registry.getModelByName(typename)
             ?? this.opts.registry.getModelByName(modelName);
         if (!ModelClass) {
-            throw new AbloValidationError(`HydrationCoordinator.fetch: unknown model "${modelName}" — ` +
+            throw new AbloValidationError(`OnDemandLoader.fetch: unknown model "${modelName}" — ` +
                 `not registered in the schema.`, { code: 'model_not_registered' });
         }
         const clauses = normalizeWhere(options?.where);
@@ -82,9 +100,15 @@ export class HydrationCoordinator {
             return inFlight;
         const work = this.runFetch(modelName, typename, ModelClass, clauses, options, queryKey);
         this.inFlight.set(queryKey, work);
-        work.finally(() => {
+        // The rejection (if any) reaches callers via the returned `work`; this
+        // side-chain only clears the single-flight slot. Without the trailing
+        // catch, `.finally()` mirrors the rejection into a second, unhandled
+        // promise even when every caller handles theirs.
+        void work
+            .finally(() => {
             this.inFlight.delete(queryKey);
-        });
+        })
+            .catch(() => undefined);
         return work;
     }
     async runFetch(modelName, typename, ModelClass, clauses, options, queryKey) {
@@ -95,24 +119,24 @@ export class HydrationCoordinator {
         const hasExpand = !!(expand && expand.length > 0);
         // Fast path — this exact query was already satisfied from the server this
         // session. The WebSocket delta stream has kept the pool fresh since, so a
-        // repeat read needs ZERO network: serve straight from local. This is what
-        // stops an already-open deck from re-querying on every navigation when no
+        // repeat read needs no network: serve straight from local. This is what
+        // stops an already-open view from re-querying on every navigation when no
         // new deltas have arrived.
         if (!explicitComplete && this.hydratedKeys.has(queryKey)) {
             return applyLimit(await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand), options?.limit);
         }
         // Not yet hydrated (or an explicit complete read). For a non-complete read
-        // WITHOUT expand, if there's anything local to show (warm pool, or IDB
-        // after a reload), hand it back immediately and confirm with the server
-        // ONCE in the background — then mark the key hydrated so subsequent reads
-        // are pure-local. First paint never blocks on the network.
+        // without expand, if there is anything local to show (a warm pool, or local
+        // storage after a reload), hand it back immediately and confirm with the
+        // server once in the background — then mark the key hydrated so subsequent
+        // reads are purely local. First paint never blocks on the network.
         //
-        // Expand queries are deliberately excluded here: a present primary says
-        // nothing about whether its relations are loaded. Returning the parent now
-        // would surface it with empty children and let `layersReady` flip before
-        // the layers exist (the "pop-in" the deck gate guards against). So an
-        // un-hydrated expand query falls through to the blocking fetch that brings
-        // parent + children together; the SECOND open is served by the fast path.
+        // Expand queries are deliberately excluded here: the presence of a primary
+        // row says nothing about whether its relations are loaded. Returning the
+        // parent now would surface it with empty children, letting a readiness flag
+        // flip before the children exist. So an un-hydrated expand query falls
+        // through to the blocking fetch that brings parent and children together;
+        // the second open is served by the fast path.
         if (!explicitComplete && !hasExpand) {
             const local = await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand);
             if (local.length > 0) {
@@ -171,10 +195,10 @@ export class HydrationCoordinator {
     async fetchFromNetwork(modelName, typename, clauses, options) {
         const networkRows = await this.queryNetwork(modelName, clauses, options);
         const networkModels = networkRows
-            // Strict: a row the SERVER returned whose typename this client never
-            // registered is a genuine schema collision (the org's pushed schema
-            // differs from local) — throw it here, naming the cause, rather than
-            // silently dropping the row and failing downstream as `entity_not_found`.
+            // Strict: a row the server returned whose type name this client never
+            // registered is a genuine schema collision (the pushed schema differs
+            // from the local one). Throw here, naming the cause, rather than silently
+            // dropping the row and failing downstream as `entity_not_found`.
             .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
             .filter((m) => m !== null);
         if (networkModels.length > 0) {
@@ -186,13 +210,13 @@ export class HydrationCoordinator {
         return networkModels;
     }
     /**
-     * Fire-and-forget the ONE server confirm for a query that was just served
-     * from local cache but isn't hydrated yet. On success the key is marked
-     * hydrated, so every later read serves pure-local with no network until a
+     * Fires the single background confirm for a query that was just served from
+     * local cache but is not hydrated yet. On success the key is marked hydrated,
+     * so every later read serves purely from local with no network until a
      * reconnect invalidates the ledger. Deduped per query key so a render burst
-     * doesn't stampede. Errors are swallowed — the caller already has a usable
-     * local snapshot, and a failed confirm leaves the key un-hydrated so the
-     * next read simply tries again.
+     * does not stampede. Errors are swallowed — the caller already has a usable
+     * local snapshot, and a failed confirm leaves the key un-hydrated so the next
+     * read simply tries again.
      */
     scheduleHydratingFetch(queryKey, modelName, typename, clauses, options) {
         if (this.revalidating.has(queryKey))
@@ -282,7 +306,7 @@ export class HydrationCoordinator {
             if (!Array.isArray(all))
                 return [];
             const idSet = new Set(parentIds);
-            return all.filter((r) => idSet.has(r[foreignKey]));
+            return all.filter((r) => idSet.has((r)[foreignKey]));
         }
         catch {
             return [];
@@ -306,7 +330,7 @@ export class HydrationCoordinator {
             // after a missed delta (WS dropped, tab slept, redeploy) silently
             // discards the fresh state and the consumer keeps seeing the
             // birth-time snapshot forever. `updateFromData` is the same
-            // primitive `ObjectPool.upsert()` uses for delta application,
+            // primitive `InstanceCache.upsert()` uses for delta application,
             // so the behaviour matches "delta-applied" semantics exactly.
             const existing = this.opts.objectPool.get(obj.id);
             if (existing) {
@@ -318,9 +342,9 @@ export class HydrationCoordinator {
         }
         // Stamp the known relation typename onto the row when the source
         // (IndexedDB rows, sometimes network rows) didn't carry one. Without
-        // this, ObjectPool.createFromData falls through to the 'Unknown'
+        // this, InstanceCache.createFromData falls through to the 'Unknown'
         // model-name branch and emits the
-        // "ObjectPool.createFromData: No model identifier found" warning,
+        // "InstanceCache.createFromData: No model identifier found" warning,
         // failing to hydrate the entity from cache (network path then has to
         // re-populate it). The typename comes from the schema relation
         // (`'SlideLayer'`, `'SlideLayoutLayer'`, etc.) so no guessing involved.
@@ -333,7 +357,7 @@ export class HydrationCoordinator {
      * `postgres.camel` driver leaves behind when the server's SQL
      * bakes `__typename` into a JSONB literal — the driver's
      * snake↔camel transform misreads `__typename` as `_typename` with
-     * a leading underscore and produces `_Typename`. ObjectPool only
+     * a leading underscore and produces `_Typename`. InstanceCache only
      * recognises `__typename`, so without this step nested rows fall
      * through to the 'Unknown' branch and never instantiate.
      */
@@ -368,6 +392,7 @@ export class HydrationCoordinator {
         const result = await postQuery({
             baseUrl: this.opts.baseUrl,
             getAuthToken: this.authTokenProvider ?? undefined,
+            recoverCredential: this.credentialRecovery ?? undefined,
         }, { queries: [query] });
         const rows = Array.isArray(result.results[0]) ? result.results[0] : [];
         // Normalize: wire rows lack `__typename` when the server elides it.
@@ -451,7 +476,7 @@ export class HydrationCoordinator {
     resolveTypename(modelName) {
         // Schema is the source of truth for wire typenames. The model proxy
         // is keyed by camelCase plural (`slideLayers`) but the wire query +
-        // ObjectPool typeIndex use the typename (`SlideLayer`).
+        // InstanceCache typeIndex use the typename (`SlideLayer`).
         const def = this.opts.schema
             .models?.[modelName];
         return def?.typename ?? modelName;
@@ -523,8 +548,8 @@ async function scanIdb(database, modelName, clauses) {
     // through to full-scan + filter.
     if (clausesAreAllEquality(clauses)) {
         const indexedKeys = Object.keys(eqClauses).filter((k) => k !== 'id' && typeof eqClauses[k] === 'string');
-        if (indexedKeys.length === 1) {
-            const idxKey = indexedKeys[0];
+        const idxKey = indexedKeys.length === 1 ? indexedKeys[0] : undefined;
+        if (idxKey !== undefined) {
             try {
                 const rows = await store.getAllFromIndex(idxKey, eqClauses[idxKey]);
                 if (Array.isArray(rows)) {

package/dist/sync/{AreaOfInterestManager.d.ts → SubscriptionManager.d.ts}

@@ -1,75 +1,65 @@
 /**
- * AreaOfInterestManager — client-side hysteresis + prominence policy over
- * the `update_subscription` read primitive.
+ * Decides which sync groups a connection subscribes to as the user navigates,
+ * and pushes each change through the {@link SubscriptionTransport}'s
+ * `update_subscription` call. It smooths two kinds of churn so that opening and
+ * closing entities does not turn into a storm of subscription changes.
  *
- * Game netcode never thrashes its area-of-interest on a boundary: a cell
- * you walk out of stays subscribed for a margin before it's dropped
- * (hysteresis), and "important" entities stay relevant from farther away
- * (prominence). This manager applies both to Ablo sync groups:
+ * The first is hysteresis. Calling {@link SubscriptionManager.leave | leave}
+ * on a group does not unsubscribe it right away; the group stays subscribed for
+ * a grace period — its warm window — and drops only once that window lapses.
+ * Re-entering within the window costs nothing, since the group was never
+ * dropped, so rapid back-and-forth navigation becomes a cache hit rather than a
+ * repeated bootstrap.
  *
- *   - `enter(group)` / `leave(group)` move read interest as the user opens
- *     and closes entities (decks, sheets, docs). A `leave` does NOT
- *     immediately unsubscribe — the group goes WARM with a TTL and stays
- *     in the effective set. Re-entering within the window is a no-op
- *     (already subscribed → no bootstrap), and only when the warm TTL
- *     lapses does the group actually drop. This is the boundary hysteresis
- *     that turns deck-tab flipping from a re-bootstrap storm into a
- *     cache hit.
+ * The second is prominence. A group that holds an active write claim is pinned
+ * (see {@link SubscriptionManager.pin | pin}) and stays subscribed regardless
+ * of navigation, so a row someone is actively editing never loses its live
+ * updates. The `baseGroups` are permanent scopes that are always subscribed.
  *
- *   - `pin(group)` / `unpin(group)` express prominence: a group that holds
- *     an active claim (write-claim) is pinned and never goes warm or
- *     expires while pinned. The claim machinery is the prominence oracle —
- *     the row two agents are fighting over stays subscribed regardless of
- *     navigation.
- *
- *   - `baseGroups` are permanent infrastructure scopes (e.g. `org:<id>`,
- *     `user:<id>`) that are always in the effective set.
- *
- * The effective set is recomputed and diffed against what was last sent;
- * the transport's `update_subscription` is only called when it actually
- * changes, so hysteresis genuinely suppresses network churn rather than
- * just deferring it.
- *
- * Transport-agnostic: it depends only on {@link SubscriptionTransport},
- * which `SyncWebSocket` satisfies structurally. `now` and the sweep timer
- * are injectable so the policy is deterministic under test.
+ * The manager recomputes the full desired set on every change, diffs it against
+ * the set the transport last confirmed, and calls `update_subscription` only
+ * when the set actually changes — so the smoothing suppresses network traffic
+ * rather than merely deferring it. It depends only on
+ * {@link SubscriptionTransport}, which {@link SyncWebSocket} satisfies. The
+ * clock and the sweep timer are injectable so the policy is deterministic under
+ * test.
  */
 /** The single capability this manager needs from the connection. */
 export interface SubscriptionTransport {
     /**
-     * Replace the connection's read interest with the COMPLETE group set.
-     * Resolves with the server's effective set (which the manager treats as
-     * authoritative for its next diff).
+     * Replaces the connection's read interest with the complete group set. This
+     * is a full replace, not an incremental add or remove. Resolves with the
+     * effective set the server applied, which the manager treats as authoritative
+     * for its next diff.
      */
-    updateSubscription(syncGroups: ReadonlyArray<string>): Promise<{
+    updateSubscription(syncGroups: readonly string[]): Promise<{
         syncGroups: string[];
     }>;
 }
-export interface AreaOfInterestOptions {
+export interface SubscriptionManagerOptions {
     /** Connection to drive. `SyncWebSocket` satisfies this structurally. */
     transport: SubscriptionTransport;
     /**
      * Groups always present in the effective set (e.g. `org:<id>`,
      * `user:<id>`). Never warm, never expired.
      */
-    baseGroups?: ReadonlyArray<string>;
+    baseGroups?: readonly string[];
     /**
      * How long a `leave`-ed group stays subscribed before it actually drops.
      * This is the hysteresis margin. Default 30s.
      */
     warmTtlMs?: number;
     /**
-     * Maximum number of warm (left-but-still-subscribed) groups. Under heavy
-     * navigation — opening and closing many entities quickly — warm groups
-     * would otherwise pile up until each TTL lapses, inflating the connection's
-     * subscription set. When the cap is exceeded, the LEAST-recently-warmed
-     * group is evicted immediately (dropped) instead of waiting for its TTL.
-     * This is the bounded relevant-set discipline from game netcode. Default 16.
+     * The maximum number of warm (left but still subscribed) groups. Under heavy
+     * navigation, warm groups would otherwise pile up until each one's window
+     * lapses, inflating the connection's subscription set. When the cap is
+     * exceeded, the least-recently-warmed group is dropped immediately instead of
+     * waiting for its window. Default 16.
      */
     maxWarm?: number;
     /**
      * Auto-run the warm-expiry sweep on this cadence. Set `0` to disable and
-     * drive {@link AreaOfInterestManager.sweep} yourself (tests do this).
+     * drive {@link SubscriptionManager.sweep} yourself (tests do this).
      * Default = `warmTtlMs` (checks about once per margin).
      */
     sweepIntervalMs?: number;
@@ -81,7 +71,7 @@ export interface AreaOfInterestOptions {
      */
     scheduler?: (fn: () => void, intervalMs: number) => () => void;
 }
-export declare class AreaOfInterestManager {
+export declare class SubscriptionManager {
     private readonly transport;
     private readonly baseGroups;
     private readonly warmTtlMs;
@@ -99,7 +89,7 @@ export declare class AreaOfInterestManager {
     private inFlight;
     private dirty;
     private readonly cancelSweep;
-    constructor(options: AreaOfInterestOptions);
+    constructor(options: SubscriptionManagerOptions);
     /**
      * Move a group into the warm set with a fresh TTL, maintaining LRU order
      * and the `maxWarm` cap. JS `Map` preserves insertion order, so deleting
@@ -134,19 +124,15 @@ export declare class AreaOfInterestManager {
     /** The set the manager believes is subscribed (post-confirmation). */
     effectiveGroups(): string[];
     /**
-     * Re-assert the full desired set against the transport, forgetting what
-     * was previously confirmed. Call after a reconnect: a fresh
-     * `SyncWebSocket` instance starts from the connect-time URL groups, so
-     * the manager's `lastSent` diff baseline is stale. Clearing it forces
-     * one `update_subscription` that re-establishes the live interest on the
-     * new socket.
-     *
-     * Resetting `lastSent` makes the next reconcile unconditionally re-push
-     * the current desired set (one `update_subscription` frame) so the fresh
-     * socket's server-side index matches local interest, even if warm/pinned
-     * groups drifted across the disconnect window. The connect-time URL
-     * already carries the last-acked set, so this is a correction frame, not
-     * the primary mechanism.
+     * Re-asserts the full desired set against the transport, forgetting what was
+     * previously confirmed. Call this after a reconnect: a fresh
+     * {@link SyncWebSocket} starts from the sync groups named in the connect-time
+     * URL, so the manager's diff baseline no longer reflects the new socket.
+     * Clearing that baseline makes the next reconcile push one
+     * `update_subscription` frame that re-establishes the current interest —
+     * including any warm or pinned groups that drifted while the connection was
+     * down. The connect-time URL already carries the last-acknowledged set, so
+     * this is a correction, not the primary mechanism.
      */
     resync(): Promise<void>;
     /** Stop the sweep timer. The connection is unaffected. */