@abloatai/ablo 0.26.0 → 0.28.0

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,9 +37,9 @@ 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.
@@ -46,16 +47,20 @@ export class HydrationCoordinator {
     hydratedKeys = new Set();
     authTokenProvider = null;
     /**
-     * The auth-recovery backbone (the store's `recoverFromAuthRejection`),
-     * late-bound like {@link setAuthTokenProvider} because the store doesn't
+     * 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 WS
-     * probe and proactive pre-roll use, then replays once — instead of silently
-     * returning empty rows against an expired key forever.
+     * 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;
     }
     /**
@@ -84,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);
@@ -114,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) {
@@ -190,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) {
@@ -205,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))
@@ -325,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) {
@@ -337,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.
@@ -352,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.
      */
@@ -471,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;

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

@@ -1,51 +1,42 @@
 /**
- * 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: readonly string[]): Promise<{
         syncGroups: string[];
     }>;
 }
-export interface AreaOfInterestOptions {
+export interface SubscriptionManagerOptions {
     /** Connection to drive. `SyncWebSocket` satisfies this structurally. */
     transport: SubscriptionTransport;
     /**
@@ -59,17 +50,16 @@ export interface AreaOfInterestOptions {
      */
     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. */

package/dist/sync/{AreaOfInterestManager.js → SubscriptionManager.js}

@@ -1,38 +1,28 @@
 /**
- * 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.
  */
 function setsEqual(a, b) {
     if (a.size !== b.size)
@@ -42,7 +32,7 @@ function setsEqual(a, b) {
             return false;
     return true;
 }
-export class AreaOfInterestManager {
+export class SubscriptionManager {
     transport;
     baseGroups;
     warmTtlMs;
@@ -165,19 +155,15 @@ export class AreaOfInterestManager {
         return [...this.lastSent];
     }
     /**
-     * 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() {
         this.lastSent = new Set();
@@ -214,14 +200,20 @@ export class AreaOfInterestManager {
                         this.lastSent = new Set(result.syncGroups);
                     }
                     catch {
-                        // Transport unavailable (offline / socket not open) or the
-                        // server rejected the set. Interest is SOFT state — never throw
-                        // out of enter/leave/sweep for an expected transient. Leave
-                        // `lastSent` unchanged so the diff persists; `resync()` on the
-                        // next `connected` re-pushes the then-current desired set,
-                        // which is what recovers "interest changed while offline."
+                        // Transport unavailable (offline, or socket not open) or the
+                        // server rejected the set. Read interest is soft state, so enter,
+                        // leave, and sweep never throw for an expected transient failure.
+                        // Leaving `lastSent` unchanged keeps the pending diff; `resync()`
+                        // on the next successful connect re-pushes the then-current desired
+                        // set, which recovers any interest that changed while offline.
                         break;
                     }
+                    // A concurrent reconcile() arriving during the await above sets
+                    // `this.dirty` back to true (the coalescing path near line 245).
+                    // TypeScript's intra-closure flow analysis can't see that cross-
+                    // invocation mutation and reads this as always-false, but the loop
+                    // is genuinely reentrant.
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
                 } while (this.dirty);
             }
             finally {