@abloatai/ablo 0.25.0 → 0.27.0

package/dist/BaseSyncedStore.d.ts

@@ -1,36 +1,39 @@
 /**
- * BaseSyncedStore — Generic sync store base class for the SDK.
+ * The base class that application-specific sync stores extend. It supplies the
+ * shared orchestration for reads, writes, delta processing, and bootstrap, and
+ * exports the core types those stores build on.
  *
- * Exports the core types, interfaces, and a base class that app-specific
- * stores extend. The base class provides query/mutation/delta/bootstrap
- * orchestration. Subclasses add domain-specific lazy-loading, collaboration
- * events, and model enrichment.
- *
- * Design: The app's SyncedStore extends this and adds its own methods.
- * This file only contains types and the abstract contract — the actual
- * implementation stays in the app's SyncedStore.ts until we incrementally
- * pull generic methods into this base class.
+ * A subclass adds its own domain behavior — lazy-loaded relations,
+ * collaboration events, and model enrichment — by overriding the protected
+ * extension points defined here. The heavy lifting is delegated to injected
+ * collaborators: {@link SyncClient} owns pool writes and the transaction
+ * queue, {@link Database} owns local persistence, {@link InstanceCache} holds the
+ * in-memory models, and {@link ModelRegistry} holds their metadata.
  */
+import type { RecoveryClass } from './errorCodes.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
-import { AreaOfInterestManager } from './sync/AreaOfInterestManager.js';
+import { SubscriptionManager } from './sync/SubscriptionManager.js';
 import { type ParticipantScope } from './sync/participants.js';
 import type { SyncClient } from './SyncClient.js';
 import type { Database, BootstrapResult } from './Database.js';
-import type { ObjectPool } from './ObjectPool.js';
+import type { InstanceCache } from './InstanceCache.js';
 import { ModelRegistry } from './ModelRegistry.js';
-import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type VersionVector, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdateEvent, type EventMap, type DefaultCollaborationEvents } from './sync/SyncWebSocket.js';
+import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdateEvent, type EventMap, type DefaultCollaborationEvents } from './sync/SyncWebSocket.js';
 import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model } from './Model.js';
-import { ModelScope } from './ObjectPool.js';
+import { ModelScope } from './InstanceCache.js';
 import type { Schema } from './schema/schema.js';
-import type { LocalMutation } from './react/context.js';
+import type { SyncStatus, LocalMutation } from './core/storeContract.js';
 import type { AuthCredentialSource } from './auth/credentialSource.js';
+import type { ModelData } from './types/modelData.js';
+import type { EnrichmentPlanEntry, ForeignKeyIndexSpec } from './sync/syncPlan.js';
+import { type CredentialRefresher } from './sync/credentialLifecycle.js';
+import type { RehydrationStats } from './sync/bootstrapApply.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
 export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
 /** Concrete constructor type for instantiation */
 export type ConcreteModelConstructor<T extends Model> = new (data?: any) => T;
-/** Generic record type for model data */
-export type ModelData = Record<string, unknown>;
+export type { ModelData } from './types/modelData.js';
 /** Query result interface */
 export interface QueryResult<T extends Model> {
     data: T[];
@@ -38,55 +41,12 @@ export interface QueryResult<T extends Model> {
     hasMore: boolean;
     fromCache?: boolean;
 }
-/** A foreign-key index to register on the ObjectPool at construction time. */
-export interface ForeignKeyIndexSpec {
-    /**
-     * The child model name (where the FK field lives) — this is the type
-     * that will be passed to `pool.registerForeignKey(modelName, fieldName)`
-     * and later to `pool.getByForeignKey(modelName, fieldName, value)`.
-     *
-     * Use the wire `__typename` casing (e.g., `'SlideLayer'`, not
-     * `'slideLayer'`) — that's the value `createFromData` stamps onto
-     * models and the pool indexes by.
-     */
-    readonly modelName: string;
-    /** The FK field name on the child model, e.g. `'slideId'`. */
-    readonly fieldName: string;
-}
-/**
- * A declarative enrichment rule for the delta-apply path.
- *
- * When a delta for `modelName` arrives, after the model is constructed
- * the base store reads `data[foreignKey]` from the payload, looks up
- * the matching parent in the ObjectPool, and attaches it as
- * `data[relationKey]`. Best-effort: if the parent isn't yet in the
- * pool (e.g., arrived later in the same bootstrap batch), enrichment
- * silently no-ops.
- *
- * Replaces the previous pattern of overriding `enrichRelations` on a
- * subclass to hardcode per-model enrichment logic.
- */
-export interface EnrichmentPlanEntry {
-    /** The child model whose incoming deltas should be enriched. */
-    readonly modelName: string;
-    /** The FK field on the child that points at the parent's id. */
-    readonly foreignKey: string;
-    /** The property name under which to attach the parent model. */
-    readonly relationKey: string;
-}
+export type { ForeignKeyIndexSpec, EnrichmentPlanEntry } from './sync/syncPlan.js';
 /** Configuration for SyncedStore behavior */
 export interface SyncedStoreConfig {
     enableOffline?: boolean;
     enableCache?: boolean;
     enableTelemetry?: boolean;
-    /**
-     * Initial version vector keys, each seeded to 0. Merged with the
-     * schema-derived set (if a schema is provided to the constructor) —
-     * explicit keys here layer on top of derived ones. Replaces the
-     * subclass pattern of hardcoding `this.versionVector = { tasks: 0, ... }`
-     * in the constructor.
-     */
-    versionVectorKeys?: readonly string[];
     /**
      * Declarative enrichment plan consumed by `enrichRelations`. Replaces
      * the subclass override of `enrichRelations` for per-model parent
@@ -95,7 +55,7 @@ export interface SyncedStoreConfig {
      */
     enrichmentPlan?: readonly EnrichmentPlanEntry[];
     /**
-     * Foreign-key indexes to register on the ObjectPool at construction
+     * Foreign-key indexes to register on the InstanceCache at construction
      * time. Replaces the subclass override of `registerForeignKeys` for
      * per-model FK registration. Merged with schema-derived entries
      * (relations marked `{ index: true }` on `belongsTo`). Both sets
@@ -104,17 +64,7 @@ export interface SyncedStoreConfig {
      */
     foreignKeyIndexes?: readonly ForeignKeyIndexSpec[];
 }
-/** Sync status for UI binding */
-export interface SyncStatus {
-    state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
-    progress: number;
-    error?: Error;
-    /** When true, the error is a session/auth error requiring re-authentication. */
-    isSessionError: boolean;
-    lastSyncAt?: Date;
-    pendingChanges: number;
-    offlineSince?: Date;
-}
+export type { SyncStatus } from './core/storeContract.js';
 /** User context for initialization */
 export interface UserContext {
     userId: string;
@@ -128,8 +78,7 @@ export interface UserContext {
     kind?: 'user' | 'agent' | 'system';
     /** Restricted (`rk_`) API key for `kind: 'agent'` — the agent's
      *  bearer credential. Sent in the `ablo.bearer.<token>` WebSocket
-     *  subprotocol, never in the URL. (Field name predates the
-     *  Biscuit→opaque-key migration.) */
+     *  subprotocol, never in the URL. */
     capabilityToken?: string;
     /** Server-authoritative sync groups, supplied by auth/capability
      *  exchange. The SDK does not invent org/user/default groups; app
@@ -157,15 +106,7 @@ export interface SmartSyncOptions {
     batchingDelay?: number;
     maxBatchSize?: number;
 }
-/** Rehydration statistics from bootstrap */
-export interface RehydrationStats {
-    added: number;
-    updated: number;
-    removed: number;
-    skipped: number;
-    healed: number;
-    elapsedMs: number;
-}
+export type { RehydrationStats } from './sync/bootstrapApply.js';
 /** Bootstrap timeout configuration */
 export declare const BOOTSTRAP_CONFIG: {
     readonly OVERALL_TIMEOUT_MS: 15000;
@@ -173,18 +114,18 @@ export declare const BOOTSTRAP_CONFIG: {
     readonly RETRY_DELAY_MS: 500;
 };
 export { ModelScope };
-export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, VersionVector, BootstrapHint, BootstrapDataEvent, PresenceUpdateEvent, };
+export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdateEvent, };
+export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 /**
- * BaseSyncedStore — abstract base for app-specific sync stores.
+ * The abstract base class that application-specific sync stores extend. It
+ * carries the injected collaborators, the observable sync status, and the
+ * orchestration for initialization, delta processing, bootstrap, and the
+ * read and write API. A subclass supplies its own domain behavior by
+ * overriding the protected extension points defined here and by typing its
+ * collaboration events through the generic parameter.
  *
- * Provides the dependency structure, observable status, and protected
- * accessors that subclasses use. The actual sync orchestration (initialize,
- * delta processing, bootstrap, query, save, delete, etc.) lives in the
- * app's concrete subclass for now — methods will be pulled up into this
- * base class incrementally as they are genericized.
- *
- * Subclasses MUST call `super(dependencies, config)` and then set up
- * their own MobX observables.
+ * A subclass must call `super(dependencies, config)` and then set up its own
+ * MobX observables.
  *
  * Generic over `TCollaboration` — an app-defined event map for real-time
  * collaboration events (cursors, selections, presence beyond the core set).
@@ -202,35 +143,11 @@ export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemoved
  *     }
  *   }
  */
-/**
- * Walk a schema and derive the three sync-plan arrays consumed by
- * `BaseSyncedStore`'s constructor: version-vector keys, FK indexes to
- * register on the pool, and the enrichment plan.
- *
- * Version vector keys are derived from each model's `typename` (lowercased
- * to match the server's event-type convention — `'Task'` → `'task'`,
- * `'SlideLayer'` → `'slidelayer'`). A fallback to the schema key applies
- * when `typename` is unset, though `defineSchema()` now always resolves
- * it during assembly so the fallback is defensive-only.
- *
- * FK indexes and enrichment entries are pulled from each `belongsTo`
- * relation where `options.index` / `options.enrich` is set. Relations
- * without those options are skipped — this is an opt-in mechanism so
- * adding a `belongsTo` never silently changes delta or lookup semantics.
- *
- * Pure function: takes a Schema, returns three arrays. No side effects,
- * no class state. Called once at construction time from `BaseSyncedStore`.
- */
-export declare function deriveSyncPlanFromSchema(schema: Schema): {
-    versionVectorKeys: string[];
-    enrichmentPlan: EnrichmentPlanEntry[];
-    foreignKeyIndexes: ForeignKeyIndexSpec[];
-};
 export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents, TSchema extends Schema = Schema> {
     syncStatus: SyncStatus;
     protected readonly syncClient: SyncClient;
     protected readonly database: Database;
-    protected readonly objectPool: ObjectPool;
+    protected readonly objectPool: InstanceCache;
     protected readonly modelRegistry: ModelRegistry;
     protected readonly auth?: AuthCredentialSource;
     /**
@@ -246,7 +163,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * to whichever instance is current, so callers (the React participant
      * hook) never hold a stale reference. Null until `setupWebSocketSync`.
      */
-    protected areaOfInterest: AreaOfInterestManager | null;
+    protected areaOfInterest: SubscriptionManager | null;
     /** Sync groups whose current state has been backfilled into the pool
      *  (hydrate-on-enter). Cleared when the pool is reset on (re)bootstrap. */
     private readonly hydratedGroups;
@@ -265,22 +182,22 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     getSyncWebSocket(): SyncWebSocket<TCollaboration> | null;
     private scopeToGroups;
     /**
-     * Bring a scope into view → subscribe to its groups. With
-     * `{ hydrate: true }`, ALSO backfill the groups' current state into the pool
-     * after the subscription is active (the game "spawn snapshot + delta stream"
-     * pattern): subscribe-first so no live delta is missed in the gap, then
-     * snapshot. Hydration is soft — a failed backfill never rejects `enterScope`
-     * and the live tail still flows.
+     * Bring a scope into view and subscribe to its sync groups. With
+     * `{ hydrate: true }`, also backfill the groups' current state into the pool
+     * once the subscription is active. The order matters: subscribing first
+     * guarantees no live delta is missed in the gap before the snapshot lands.
+     * Hydration is best-effort — a failed backfill never rejects `enterScope`,
+     * and the live delta stream keeps flowing regardless.
      */
     enterScope(scope: ParticipantScope, opts?: {
         hydrate?: boolean;
     }): Promise<void>;
     /**
-     * Backfill the current state of `syncGroups` into the pool via a PURE scoped
-     * snapshot fetch + the version-guarded, ghost-free scoped apply. Idempotent
-     * (skips groups already hydrated) and single-flight (concurrent enters of the
-     * same group share one fetch). Soft-fails: on error the groups are NOT marked
-     * hydrated, so a later re-enter retries.
+     * Backfill the current state of `syncGroups` into the pool with a side-effect-free
+     * scoped snapshot fetch followed by the version-guarded scoped apply. The call
+     * is idempotent (it skips groups already hydrated) and single-flight (concurrent
+     * enters of the same group share one fetch). On error the groups are left
+     * unmarked, so a later re-enter retries.
      */
     protected hydrateGroups(syncGroups: readonly string[]): Promise<void>;
     /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
@@ -291,18 +208,16 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     unpinScope(scope: ParticipantScope): Promise<void>;
     protected readonly queryProcessor: QueryProcessor;
     /**
-     * Runtime behavior flags only — the three schema/config arrays
-     * (`versionVectorKeys`, `enrichmentPlan`, `foreignKeyIndexes`) are
-     * consumed at construction time and stored on the instance as
-     * `versionVector`, `enrichmentPlan`, and pool-registered indexes.
-     * They don't need to persist on `this.config`.
+     * Runtime behavior flags only — the schema/config arrays
+     * (`enrichmentPlan`, `foreignKeyIndexes`) are consumed at construction
+     * time and stored on the instance as `enrichmentPlan` and
+     * pool-registered indexes. They don't need to persist on `this.config`.
      */
     protected readonly config: Required<Pick<SyncedStoreConfig, 'enableOffline' | 'enableCache' | 'enableTelemetry'>>;
-    protected disposers: Array<() => void>;
+    protected disposers: (() => void)[];
     protected initialized: boolean;
     protected dataReady: boolean;
     protected userContext: UserContext | null;
-    protected versionVector: VersionVector;
     /**
      * Declarative enrichment plan: "for model X, when a delta arrives,
      * read data[foreignKey] and attach the matching parent from the pool
@@ -328,15 +243,14 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     constructor(dependencies: {
         syncClient: SyncClient;
         database: Database;
-        objectPool: ObjectPool;
+        objectPool: InstanceCache;
         modelRegistry: ModelRegistry;
         /**
-         * Optional schema. When provided, `deriveSyncPlanFromSchema` walks
-         * the schema's models + relations to auto-populate version vector
-         * keys, FK indexes, and the enrichment plan from declarative
-         * annotations. Class-based subclass users (like Ablo's legacy
-         * SyncedStore) typically pass explicit `config.versionVectorKeys`
-         * / `config.foreignKeyIndexes` / `config.enrichmentPlan` instead.
+         * Optional schema. When provided, {@link deriveSyncPlanFromSchema} walks
+         * the schema's models and relations to auto-populate foreign-key indexes
+         * and the enrichment plan from their declarative annotations. Subclasses
+         * that register model classes directly can instead pass explicit
+         * `config.foreignKeyIndexes` / `config.enrichmentPlan`.
          */
         schema?: TSchema;
         /** Sync server URL for WebSocket connection. Converted to wss:// automatically. */
@@ -345,17 +259,17 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         auth?: AuthCredentialSource;
     }, config?: SyncedStoreConfig);
     /**
-     * Register foreign key indexes for O(1) lookups.
+     * Register foreign-key indexes for constant-time lookups.
      *
-     * Legacy override hook — in Phase 2 the preferred way to declare FK
-     * indexes is via `config.foreignKeyIndexes` at construction time, or
-     * by marking the `belongsTo` relation with `{ index: true }` in the
-     * schema. This hook still fires AFTER the schema-derived + config
-     * registrations, so subclasses can layer additional FKs on top.
+     * This is an override hook. The preferred way to declare a foreign-key
+     * index is `config.foreignKeyIndexes` at construction time, or marking the
+     * `belongsTo` relation with `{ index: true }` in the schema. The hook fires
+     * after the schema-derived and config registrations, so a subclass can
+     * layer additional indexes on top.
      */
     protected registerForeignKeys(): void;
     /**
-     * Enrich delta data with related models from the ObjectPool.
+     * Enrich delta data with related models from the InstanceCache.
      *
      * Base implementation walks `this.enrichmentPlan` — entries populated
      * from the schema's `{ enrich: true }` relations and from
@@ -391,23 +305,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     protected connectionManager: import('./sync/ConnectionManager.js').ConnectionManager | null;
     /**
-     * Re-mint hook for the short-lived access credential (the Stripe-style
-     * `ek_`/`rk_`). Wired by the React provider from its `getToken`/`authEndpoint`
-     * — the engine owns WHEN to refresh (a stale-credential probe / an external
-     * nudge), the integrator owns HOW to mint. Mirrors the `getToken` contract:
-     * resolves a token string on success, `null` when the long-lived login is
-     * gone (terminal), and THROWS on a transient/offline failure. Used by
-     * {@link performCredentialRefresh}. Absent ⇒ no silent re-mint (e.g. a static
-     * `apiKey` deployment whose credential source refreshes out-of-band).
-     */
-    private credentialRefresher;
-    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
-     *  all mint at once (the classic "token thrash → random logout" bug). */
-    private inFlightCredentialRefresh;
-    /** Teardown for the proactive credential lifecycle (refresh timer + wake/
-     *  online/focus listeners) installed by {@link startCredentialLifecycle};
-     *  cleared on {@link disconnect}. Null when no resolver is wired. */
-    private credentialLifecycleTeardown;
+     * Access-credential re-mint + proactive pre-roll — extracted to
+     * sync/credentialLifecycle.ts. Owns the refresher hook, the single-flight
+     * guard, and the browser-only refresh timer / wake listener; talks back
+     * through three lazily-resolved callbacks (the ConnectionManager doesn't
+     * exist until `setupWebSocketSync`). The `setCredentialRefresher` /
+     * `performCredentialRefresh` / `startCredentialLifecycle` methods below
+     * are thin delegates so the store's public surface is unchanged.
+     */
+    private readonly credentialLifecycle;
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -448,7 +354,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     waitForConfirmation(modelName: string, modelId: string): Promise<void>;
     /**
      * Observe the LOCAL mutation stream for undo recording (see
-     * {@link import('./react/context.js').LocalMutation}). Taps the
+     * {@link import('./core/storeContract.js').LocalMutation}). Taps the
      * TransactionQueue's `transaction:created` event — fired once per local
      * create/update/delete/archive with `previousData` already captured.
      * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
@@ -469,28 +375,25 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /**
      * Register the access-credential re-mint hook. Called by the React provider
      * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
-     * See {@link credentialRefresher}.
+     * See {@link CredentialLifecycle.setRefresher}.
      */
-    setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
+    setCredentialRefresher(refresher: CredentialRefresher | null): void;
     /**
      * Re-mint the short-lived access credential and push it into the credential
      * source, reporting a tri-state outcome the {@link ConnectionManager} maps to
-     * its FSM. The contract mirrors `getToken` (and PowerSync's `fetchCredentials`
-     * / Liveblocks' `authEndpoint`, but made explicit instead of overloading
-     * return/throw):
-     *   - token string  → `'refreshed'`     (fresh key in place; re-probe & reconnect)
-     *   - `null`        → `'session_error'` (login itself is gone → terminal, sign out)
-     *   - throw         → `'network_error'` (couldn't reach the mint endpoint → transient)
-     *
-     * SINGLE-FLIGHT: concurrent callers (a wake nudge, an in-flight request, the
-     * probe) share one in-flight promise so we never double-mint — the canonical
-     * fix for the "every 401 mints a token → thrash → spurious logout" anti-pattern.
-     *
-     * No refresher wired ⇒ `'refreshed'` (a no-op re-probe): a static-`apiKey`
-     * deployment has no session to re-mint from; its credential source refreshes
-     * out-of-band, so we just re-probe with whatever it currently holds.
+     * its FSM. Single-flight; no refresher wired ⇒ `'refreshed'` (a no-op
+     * re-probe). Full contract on {@link CredentialLifecycle.refresh}.
      */
     performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
+    /**
+     * The authentication-recovery path for HTTP transports, such as the lazy
+     * query lane. It runs a single-flight credential re-mint driven by the
+     * rejection's recovery class, routing outcomes through the same state
+     * machine the WebSocket probe uses. `'retry'` means a fresh credential is
+     * now in the credential source and the request should be replayed once.
+     * Full contract on {@link CredentialLifecycle.recoverFromAuthRejection}.
+     */
+    recoverFromAuthRejection(recovery: RecoveryClass): Promise<'retry' | 'stop'>;
     /**
      * Nudge the connection FSM to re-probe with the current credential. Idempotent
      * and safe in any state (ignored while `connected`). Call after pushing a
@@ -500,72 +403,40 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     nudgeReconnect(): void;
     /**
-     * Install the access-credential lifecycle the CLIENT owns (this used to live
-     * in the React provider — wrong layer). Two parts:
-     *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
-     *      probe finds the key stale (`credential_stale`) or on a nudge.
-     *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
-     *      block is browser-gated (`typeof window`): server/SSR has no socket to
-     *      keep warm and the resolver is browser-oriented, so arming it in Node
-     *      would fire a relative-URL fetch and throw. (Agents pass a static
-     *      `apiKey` with no resolver, so this method is never called for them.)
-     *
-     * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
-     * never call a refresh method. Idempotent (a second call replaces the first);
-     * torn down on {@link disconnect}.
+     * Install the client-owned access-credential lifecycle: register `getToken`
+     * as the reactive re-mint hook and arm the browser-only proactive refresh
+     * (a refresh timer plus an OS-wake re-mint). Idempotent — a second call
+     * replaces the first — and torn down on {@link disconnect}. Full rationale
+     * on {@link CredentialLifecycle.start}.
      */
-    startCredentialLifecycle(getToken: () => Promise<string | null>): void;
+    startCredentialLifecycle(getToken: CredentialRefresher, opts?: {
+        proactiveInNode?: boolean;
+    }): void;
     /** Tear down the proactive credential lifecycle (idempotent). */
     private stopCredentialLifecycle;
+    /** Narrow context the group-change leaf talks back through. */
+    private groupChangeContext;
     /**
-     * Handle an actionType 'G' delta.
-     *
-     * The server emits 'G' via two distinct pathways, distinguished by payload
-     * shape:
-     *
-     *   Incremental (EmitGroupAdded):   { group, userId }
-     *     - The recipient was added to a single sync group.
-     *     - Subsequent 'C' (Covering) deltas deliver each newly-visible entity.
-     *     - No re-bootstrap — entities arrive via the normal insert path.
-     *
-     *   Legacy (EmitGroupChange):       { addedGroups, removedGroups }
-     *     - Single delta carrying the full group membership diff.
-     *     - Forces a full re-bootstrap (disconnect + reconnect + fetch all).
-     *     - Deprecated on the server; kept here for wire-level backward compat.
+     * Handle an actionType 'G' delta — incremental `{ group, userId }` or
+     * legacy `{ addedGroups, removedGroups }` payloads. Full pathway doc on
+     * {@link groupChange.handleSyncGroupChange}.
      */
     protected handleSyncGroupChange(delta: SyncDelta): Promise<void>;
     /**
-     * Handle an incremental GroupAdded delta.
-     *
-     * Adds the new group to the subscription metadata without triggering a
-     * re-bootstrap. The server will follow up with 'C' (Covering) deltas for
-     * each newly-visible entity, which flow through the normal insert path.
+     * Handle an incremental GroupAdded delta — metadata only, no re-bootstrap
+     * (covering deltas bring the entities). See {@link groupChange.handleGroupAdded}.
      */
     protected handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
     /**
-     * Handle an actionType 'S' (GroupRemoved) delta.
-     *
-     * Signals that the recipient has lost access to a sync group. Because
-     * the client does not track per-entity group membership, we can't
-     * selectively purge entities belonging to that group. The safe fallback
-     * is the legacy behavior: clear local state and force a re-bootstrap
-     * with the updated group list.
-     *
-     * Future optimization: track group membership in the ObjectPool so 'S'
-     * can do a targeted purge instead of a full re-bootstrap.
+     * Handle an actionType 'S' (GroupRemoved) delta: for safety, clear the
+     * revoked local state and trigger a full re-bootstrap. See
+     * {@link groupChange.handleGroupRemoved}.
      */
     protected handleGroupRemoved(delta: SyncDelta): Promise<void>;
     /** Compute new sync groups after applying additions and removals */
     protected computeUpdatedSyncGroups(payload: SyncGroupChangePayload): string[];
-    /** Force a full re-bootstrap via connection lifecycle event.
-     *
-     * No-op for `bootstrapMode: 'none'` participants — they never pull
-     * baseline state, so a "force re-bootstrap" trigger (sync-group
-     * shrink, scope revocation) instead just flushes the local pool and
-     * relies on covering deltas to repopulate the data they actually
-     * subscribe to.
-     */
+    /** Force a full re-bootstrap via connection lifecycle event (no-op for
+     *  `bootstrapMode: 'none'` participants — see {@link groupChange.forceFullRebootstrap}). */
     protected forceFullRebootstrap(): void;
     /**
      * Single source of truth for the sync-group list this session is
@@ -578,8 +449,9 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected resolveSyncGroups(context: UserContext): readonly string[];
     /** Check if sync groups shrank since last session — force full bootstrap if so */
     protected checkSyncGroupShrinkage(): Promise<void>;
-    /** Apply bootstrap data to the ObjectPool with ghost removal */
-    /** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+    /** Narrow context the bootstrap-apply leaf talks back through. */
+    private poolContext;
+    /** Apply bootstrap data to the {@link InstanceCache}, removing entities that are no longer present (ghost removal). Pool writes are delegated to {@link SyncClient}. */
     protected applyBootstrapToPool(bootstrapResult: BootstrapResult, protectedIds?: ReadonlySet<string>): RehydrationStats;
     /**
      * Initialize the sync engine with user context.
@@ -595,7 +467,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected withDeltaQueuing<T>(fn: () => Promise<T>): Promise<T>;
     /** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
     protected collectDeltaProtectedIds(preBootstrapIds: ReadonlySet<string>): Set<string>;
-    /** Replay deltas queued during bootstrap */
+    /** Replay deltas queued during bootstrap (atomically, via `applyDeltaFrame`). */
     protected replayQueuedDeltas(): void;
     /**
      * Factory for the internal `ConnectionManager`. Override to return
@@ -664,11 +536,13 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     protected waitForWebSocketConnected(timeoutMs: number): Promise<boolean>;
     protected setupWebSocketSync(context: UserContext, lastSyncId: number): void;
-    /** State signature for delta deduplication */
-    private extractStateSignature;
+    /** Memoized pipeline context — `enqueueDelta` runs once per delta, so the
+     *  accessor object is built once and reused (the get/set accessors always
+     *  read the live host fields). */
+    private _deltaPipelineContext;
+    private get deltaPipelineContext();
     /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
     protected getStateFields(_modelName: string): string[];
-    private isSameState;
     /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
     protected deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
     /** Process incoming delta with smart batching */
@@ -676,23 +550,24 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /**
      * Apply a complete, server-delivered delta frame atomically.
      *
-     * A `delta_batch` WS event (reconnect/catch-up replay) already carries
-     * the FULL set of missed deltas. Routing it through the per-delta
-     * `processDeltaWithBatching` path re-chunks it via the live-traffic
-     * debounce timer + `maxBatchSize` force-flush, so a 300-delta catch-up
-     * fans out into ~6 separate `flushPendingDeltas` cycles — each its own
-     * IDB write, pool mutation, `models:changed` emit, and React re-render.
-     * The decks gallery visibly re-sorts and "pops in" once per chunk.
+     * A `delta_batch` WebSocket event (a reconnect or catch-up replay) already
+     * carries the full set of missed deltas. Routing it through the per-delta
+     * `processDeltaWithBatching` path would re-chunk it via the live-traffic
+     * debounce timer and `maxBatchSize` force-flush, so a 300-delta catch-up
+     * would fan out into several separate `flushPendingDeltas` cycles — each its
+     * own local write, pool mutation, `models:changed` emit, and re-render, so
+     * the UI visibly repaints once per chunk.
      *
-     * Here we run the per-delta bookkeeping (dedup, ack, version vector,
-     * watermark, G/S routing, D cascade) for every delta WITHOUT scheduling
-     * a flush, then flush ONCE — collapsing the whole frame into a single
-     * IDB write + pool mutation + `models:changed` + re-render. Same code
-     * for the post-bootstrap replay of deltas queued during bootstrap.
+     * Instead, this runs the per-delta bookkeeping (deduplication, ack, version
+     * vector, watermark, group-change routing, delete cascade) for every delta
+     * without scheduling a flush, then flushes once — collapsing the whole frame
+     * into a single local write, pool mutation, `models:changed` emit, and
+     * re-render. The post-bootstrap replay of deltas queued during bootstrap
+     * uses the same path.
      *
-     * (Named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
-     * with `Database.processDeltaBatch` — the lower-level IDB write this
-     * eventually drives through `flushPendingDeltas`.)
+     * It is named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
+     * with {@link Database.processDeltaBatch} — the lower-level local write this
+     * eventually drives through `flushPendingDeltas`.
      */
     protected applyDeltaFrame(deltas: SyncDelta[]): void;
     /**
@@ -720,8 +595,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * skips both the scan AND the allocation.
      */
     protected cascadeCancelTransactionsForDeletedParent(parentModelName: string, parentId: string): void;
-    /** Flush pending deltas with deduplication and batched ObjectPool mutations */
-    /** Flush pending deltas with deduplication. Delegates pool writes to SyncClient. */
+    /** Flush pending deltas with deduplication. Pool writes are delegated to {@link SyncClient}. */
     protected flushPendingDeltas(): Promise<void>;
     /** Check if a model type is local-only (no sync). Override for domain-specific models. */
     protected isLocalOnlyModel(_modelName: string): boolean;
@@ -786,10 +660,10 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     create<K extends keyof TSchema['models'] & string>(typename: K, data: Record<string, unknown>): import('./schema/schema.js').InferModel<TSchema, K> | null;
     /**
-     * Legacy class-based query entry point — kept for callers that still pass
-     * a Model constructor + options object. New code should use the typed
-     * `store.query.<modelKey>` namespace instead, which returns properly
-     * inferred schema types without needing a class value or cast.
+     * Query entry point for callers that hold a {@link Model} constructor and an
+     * options object. It filters, orders, and paginates the matching models from
+     * the pool. Prefer the schema-typed read surface (`ablo.<model>.list`) where
+     * you can, since it infers concrete row types without a class value or cast.
      */
     queryByClass(modelClass: ModelConstructor<Model>, options?: {
         predicate?: (model: Model) => boolean;
@@ -818,7 +692,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected incrementPendingChanges(): void;
     protected decrementPendingChanges(): void;
     protected updateSyncStatus(updates: Partial<SyncStatus>): void;
-    get pool(): ObjectPool;
+    get pool(): InstanceCache;
     get lastSyncId(): number;
     get isReady(): boolean;
     get isSyncing(): boolean;