@abloatai/ablo 0.25.0 → 0.27.0

package/dist/BaseSyncedStore.js

@@ -1,29 +1,34 @@
 /**
- * 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 { makeObservable, observable, computed, runInAction } from 'mobx';
+import { makeObservable, observable, action, computed, runInAction } from 'mobx';
 import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
-import { AreaOfInterestManager } from './sync/AreaOfInterestManager.js';
+import { SubscriptionManager } from './sync/SubscriptionManager.js';
 import { resolveParticipantSyncGroups, } from './sync/participants.js';
+import { ModelRegistry } from './ModelRegistry.js';
 import { PropertyType } from './types/index.js';
 import { SyncWebSocket, } from './sync/SyncWebSocket.js';
 import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model, rowAsModel } from './Model.js';
 import { getContext } from './context.js';
-import { SyncSessionError } from './errors.js';
-import { ModelScope } from './ObjectPool.js';
+import { SyncSessionError, isAccessCredentialExpiryCloseReason } from './errors.js';
+import { ModelScope } from './InstanceCache.js';
 import { LazyReferenceCollection } from './LazyReferenceCollection.js';
+import { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
+import { CredentialLifecycle } from './sync/credentialLifecycle.js';
+import * as groupChange from './sync/groupChange.js';
+import * as bootstrapApply from './sync/bootstrapApply.js';
+import * as deltaPipeline from './sync/deltaPipeline.js';
 /** Bootstrap timeout configuration */
 export const BOOTSTRAP_CONFIG = {
     OVERALL_TIMEOUT_MS: 15_000,
@@ -32,18 +37,20 @@ export const BOOTSTRAP_CONFIG = {
 };
 // Re-export for clean API
 export { ModelScope };
+// deriveSyncPlanFromSchema derives a sync plan from a schema and is
+// re-exported here.
+export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
 // ── Base class ──────────────────────────────────────────────────────────────
 /**
- * BaseSyncedStore — abstract base for app-specific sync stores.
- *
- * 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.
+ * 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.
  *
- * 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).
@@ -61,57 +68,6 @@ export { ModelScope };
  *     }
  *   }
  */
-/**
- * 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 function deriveSyncPlanFromSchema(schema) {
-    const versionVectorKeys = [];
-    const enrichmentPlan = [];
-    const foreignKeyIndexes = [];
-    for (const [modelName, def] of Object.entries(schema.models)) {
-        const typename = def.typename ?? modelName;
-        versionVectorKeys.push(typename.toLowerCase());
-        for (const [relationKey, rel] of Object.entries(def.relations)) {
-            if (rel.type === 'belongsTo') {
-                if (rel.options?.index) {
-                    foreignKeyIndexes.push({ modelName: typename, fieldName: rel.foreignKey });
-                }
-                if (rel.options?.enrich) {
-                    enrichmentPlan.push({
-                        modelName: typename,
-                        foreignKey: rel.foreignKey,
-                        relationKey,
-                    });
-                }
-            }
-            else if (rel.type === 'hasMany' || rel.type === 'hasOne') {
-                // hasMany/hasOne: the FK lives on the TARGET model, not the current model.
-                // Register the FK index on the target so getByForeignKey works.
-                // Target typename is resolved at registration time from the schema.
-                const targetDef = schema.models[rel.target];
-                const targetTypename = targetDef?.typename ?? rel.target;
-                foreignKeyIndexes.push({ modelName: targetTypename, fieldName: rel.foreignKey });
-            }
-        }
-    }
-    return { versionVectorKeys, enrichmentPlan, foreignKeyIndexes };
-}
 export class BaseSyncedStore {
     // ── Observable sync status for UI ──
     syncStatus = {
@@ -162,23 +118,23 @@ export class BaseSyncedStore {
     // ── Area-of-interest (dynamic read subscription) ─────────────────
     //
     // `enterScope`/`leaveScope` move the connection's read interest as the
-    // user navigates (open/close a deck, sheet, doc); `pinScope`/`unpinScope`
+    // user navigates (open or close a deck, sheet, or doc); `pinScope`/`unpinScope`
     // express prominence (an active claim keeps a group subscribed). All four
-    // resolve the scope to sync-group strings through the SAME resolver the
+    // resolve the scope to sync-group strings through the same resolver the
     // claim path uses (`resolveParticipantSyncGroups`), so read interest and
-    // write claims always agree on the string for a given entity. No-ops
-    // before the socket exists. Soft state — they never reject for an offline
-    // transport (see `AreaOfInterestManager.reconcile`).
+    // write claims always agree on the string for a given entity. They are
+    // no-ops before the socket exists, and they never reject when the transport
+    // is offline (see {@link SubscriptionManager.reconcile}).
     scopeToGroups(scope) {
         return resolveParticipantSyncGroups(scope, this.schema);
     }
     /**
-     * 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, opts) {
         const mgr = this.areaOfInterest;
@@ -191,11 +147,11 @@ export class BaseSyncedStore {
         return subscribed.then(() => this.hydrateGroups(groups));
     }
     /**
-     * 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.
      */
     async hydrateGroups(syncGroups) {
         const need = syncGroups.filter((g) => !this.hydratedGroups.has(g) && !this.hydratingGroups.has(g));
@@ -254,29 +210,21 @@ export class BaseSyncedStore {
     // ── Internal helpers ──
     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`.
      */
     config;
     disposers = [];
     initialized = false;
     dataReady = false;
     // ── User context ──
-    // Identity context the consumer wired in at construction. The shape
-    // (`{userId, organizationId, teamIds}`) is currently a fixed contract
-    // because the Go-era bootstrap protocol embedded those keys in scope
-    // tokens; the SDK should eventually expose this as an opaque
-    // `principal` blob so consumers with different identity models
-    // aren't forced into user/org. See the architectural note in the
-    // README — "currentUserId" is a domain concept, not an SDK
-    // primitive, and the host (apps/web/SyncEngineProvider) is the
-    // right place to surface it.
+    // The identity the consumer supplied to `initialize()`: user id,
+    // organization id, and optional team ids. Reads are scoped to this
+    // identity, and the sync-group subscription is derived from it.
     userContext = null;
     // ── Smart sync ──
-    versionVector;
     /**
      * Declarative enrichment plan: "for model X, when a delta arrives,
      * read data[foreignKey] and attach the matching parent from the pool
@@ -316,21 +264,19 @@ export class BaseSyncedStore {
         this._syncServerUrl = dependencies.url;
         // Set this store as the global Model store
         Model.setStore(this);
-        // ── Schema-derived sync plan (Phase 2) ─────────────────────────────
+        // ── Schema-derived sync plan ───────────────────────────────────────
         //
-        // When a schema is provided, derive version vector keys, FK indexes,
-        // and the enrichment plan from declarative annotations on the schema's
-        // `belongsTo` relations. Explicit config fields layer on top, so
-        // subclasses (like Ablo's SyncedStore) can pass hardcoded arrays
-        // without needing a full schema.generated.ts.
+        // When a schema is provided, derive foreign-key indexes and the
+        // enrichment plan from the declarative annotations on its `belongsTo`
+        // relations. Explicit config fields layer on top, so a subclass can
+        // pass hardcoded arrays without supplying a full schema.
         //
-        // Order matters: schema-derived first, config second, so that in a
-        // future where Ablo passes both (schema AND explicit config), the
-        // explicit config entries are registered last and can't be
-        // accidentally shadowed by schema derivation.
+        // Order matters: schema-derived entries are registered first and
+        // config entries second, so that when a caller supplies both, the
+        // explicit config entries win and are never shadowed by derivation.
         const derived = dependencies.schema
             ? deriveSyncPlanFromSchema(dependencies.schema)
-            : { versionVectorKeys: [], enrichmentPlan: [], foreignKeyIndexes: [] };
+            : { enrichmentPlan: [], foreignKeyIndexes: [] };
         const mergedForeignKeyIndexes = [
             ...derived.foreignKeyIndexes,
             ...(config.foreignKeyIndexes ?? []),
@@ -338,9 +284,8 @@ export class BaseSyncedStore {
         for (const { modelName, fieldName } of mergedForeignKeyIndexes) {
             this.objectPool.registerForeignKey(modelName, fieldName);
         }
-        // Legacy override hook — still called AFTER schema-driven registration
-        // so subclasses can add more FKs on top of the declarative set.
-        // Kept for backwards compat; subclasses migrate to config at leisure.
+        // Override hook — called after schema-driven registration so a subclass
+        // can add more foreign keys on top of the declarative set.
         this.registerForeignKeys();
         this.enrichmentPlan = [
             ...derived.enrichmentPlan,
@@ -361,14 +306,6 @@ export class BaseSyncedStore {
             batchingDelay: 100,
             maxBatchSize: 50,
         };
-        // Version vector: union of schema-derived keys + explicit config keys,
-        // each seeded to 0. Empty when neither source supplies keys (unchanged
-        // behavior from pre-Phase-2 defaults).
-        const mergedVvKeys = [
-            ...derived.versionVectorKeys,
-            ...(config.versionVectorKeys ?? []),
-        ];
-        this.versionVector = Object.fromEntries(mergedVvKeys.map((k) => [k, 0]));
         // Create internal helpers
         this.queryProcessor = new QueryProcessor({
             enableCache: this.config.enableCache,
@@ -380,15 +317,13 @@ export class BaseSyncedStore {
                 this.queryProcessor.invalidateCache(`.*${name}.*`);
             }
         });
-        // Make sync status fields observable so consumer code can do
+        // Make the sync-status fields observable so consumer code can do
         //   reaction(() => store.isReady, ...)
         //   observer(() => store.isOffline)
         // and actually receive notifications. Without these annotations,
-        // `syncStatus` / `dataReady` are plain properties and the derived
-        // getters (isReady, isSyncing, isOffline, ...) never emit change
-        // signals — a trap that has burned multiple downstream apps
-        // (one stuck forever on the loading skeleton because `reaction`
-        // to `store.isReady` never fired). Explicit > accidental.
+        // `syncStatus` and `dataReady` are plain properties, and the derived
+        // getters (isReady, isSyncing, isOffline, and the rest) never emit
+        // change signals — so a `reaction` on `store.isReady` would never fire.
         makeObservable(this, {
             syncStatus: observable,
             dataReady: observable,
@@ -402,17 +337,17 @@ export class BaseSyncedStore {
     }
     // ── Protected extension points ────────────────────────────────────────────
     /**
-     * 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.
      */
     registerForeignKeys() { }
     /**
-     * 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
@@ -465,23 +400,21 @@ export class BaseSyncedStore {
      */
     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).
+     * 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.
      */
-    credentialRefresher = null;
-    /** 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). */
-    inFlightCredentialRefresh = null;
-    /** 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. */
-    credentialLifecycleTeardown = null;
+    credentialLifecycle = new CredentialLifecycle({
+        setAuthToken: (token) => { this.auth?.setAuthToken(token); },
+        nudgeReconnect: () => { this.nudgeReconnect(); },
+        reportSessionExpired: () => {
+            this.connectionManager?.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
+        },
+    });
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -525,7 +458,7 @@ export class BaseSyncedStore {
     }
     /**
      * 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
@@ -538,7 +471,7 @@ export class BaseSyncedStore {
         // the queue's emitter does) — so undo recorded nothing. See
         // `SyncClient.onLocalTransaction` for the full rationale.
         return this.syncClient.onLocalTransaction((tx) => {
-            if (!tx || !tx.type || !tx.modelName || !tx.modelId)
+            if (!tx?.type || !tx.modelName || !tx.modelId)
                 return;
             handler({
                 type: tx.type,
@@ -695,75 +628,30 @@ export class BaseSyncedStore {
     /**
      * 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) {
-        this.credentialRefresher = refresher;
+        this.credentialLifecycle.setRefresher(refresher);
     }
     /**
      * 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}.
      */
     async performCredentialRefresh() {
-        const refresher = this.credentialRefresher;
-        if (!refresher)
-            return 'refreshed';
-        if (this.inFlightCredentialRefresh)
-            return this.inFlightCredentialRefresh;
-        const run = (async () => {
-            try {
-                const token = await refresher();
-                if (!token) {
-                    // null = the long-lived login is gone (mint endpoint answered 401/403).
-                    // Terminal — the FSM routes this to sign-out.
-                    return 'session_error';
-                }
-                this.auth?.setAuthToken(token);
-                return 'refreshed';
-            }
-            catch (error) {
-                // A throw = transient (offline / mint endpoint unreachable / 5xx). The
-                // login may be perfectly valid; never sign out for this — back off and
-                // retry. Mirrors the `getToken` throw-vs-null contract end-to-end.
-                const message = error?.message ?? String(error);
-                // A relative-URL resolver invoked server-side (Node fetch has no origin
-                // to resolve against) emits the opaque "Failed to parse URL" / "Only
-                // absolute URLs are supported". Translate it into something actionable
-                // instead of a mystery transient blip — the proactive refresh is now
-                // browser-only, so hitting this means the resolver fired from SSR/RSC or
-                // a server route.
-                if (typeof window === 'undefined' && /parse URL|absolute URLs?/i.test(message)) {
-                    getContext().logger.warn('credential resolver ran on the server with a relative URL — Node fetch needs an absolute URL. ' +
-                        'Refresh the Ablo client in the browser, or build an absolute URL server-side ' +
-                        "(e.g. new URL('/api/ablo-session', process.env.NEXT_PUBLIC_APP_URL)).", { error: message });
-                }
-                else {
-                    getContext().logger.debug('access-credential re-mint failed (transient)', { error: message });
-                }
-                return 'network_error';
-            }
-        })();
-        this.inFlightCredentialRefresh = run;
-        try {
-            return await run;
-        }
-        finally {
-            this.inFlightCredentialRefresh = null;
-        }
+        return this.credentialLifecycle.refresh();
+    }
+    /**
+     * 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}.
+     */
+    async recoverFromAuthRejection(recovery) {
+        return this.credentialLifecycle.recoverFromAuthRejection(recovery);
     }
     /**
      * Nudge the connection FSM to re-probe with the current credential. Idempotent
@@ -776,227 +664,71 @@ export class BaseSyncedStore {
         this.connectionManager?.send({ type: 'CREDENTIAL_REFRESHED' });
     }
     /**
-     * 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) {
-        this.stopCredentialLifecycle();
-        this.setCredentialRefresher(getToken);
-        // Re-mint through the SAME single-flight path the FSM's reactive probe uses
-        // (`performCredentialRefresh`) rather than calling `getToken()` directly. Two
-        // wins over the old direct call:
-        //   - SINGLE-FLIGHT: a wake nudge, an in-flight probe, and this proactive
-        //     roll share one in-flight promise — no double-mint thrash.
-        //   - The tri-state is HONOURED. The old code did `if (token) {…}` and
-        //     dropped a `null` on the floor — a zombie session that re-minted on
-        //     every tab focus and logged "signing out" forever without ever signing
-        //     out. `session_error` now drives the FSM to actually expire.
-        const refresh = async () => {
-            const outcome = await this.performCredentialRefresh();
-            if (outcome === 'refreshed') {
-                // Fresh key already pushed into the credential source by
-                // `performCredentialRefresh`; nudge a parked connection to re-probe.
-                this.nudgeReconnect();
-            }
-            else if (outcome === 'session_error') {
-                // The long-lived login is gone (mint answered 401/403). Surface it —
-                // the proactive path's job is to report this, not hide it. A no-op in
-                // FSM states that don't accept the event (the probe converges on
-                // sign-out there anyway); `session_expired`'s onEnter owns the log.
-                this.connectionManager?.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
-            }
-            // 'network_error' → transient (offline / mint hiccup); the next timer tick
-            // or the FSM's own probe retries. Never sign out for it.
-        };
-        const teardowns = [];
-        // The ENTIRE proactive pre-roll is BROWSER-ONLY. On the server (Next.js
-        // SSR/RSC evaluating the `providers` module) there is no live socket to keep
-        // warm AND the scaffolded credential resolver is browser-oriented (a
-        // relative-URL `fetch('/api/ablo-session')`). Arming the timer server-side
-        // fires that resolver in Node, where fetch has no origin to resolve a
-        // relative URL against → "Failed to parse URL" on every tick. Browser-only
-        // refresh is the unanimous vendor model (Supabase `autoRefreshToken: isBrowser()`,
-        // Clerk/Ably/Stripe refresh client-side). The reactive re-mint hook
-        // (`setCredentialRefresher` above) stays UNCONDITIONAL: it only fires on a
-        // real connection probe, which can't happen during a bare SSR module eval.
-        if (typeof window !== 'undefined') {
-            // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled)
-            // tick is recovered by the next, or by the reactive probe. The timer is
-            // the sole proactive PRE-ROLL — it keeps the key warm ahead of expiry even
-            // while the socket sits healthy-`connected` (a state the FSM never probes).
-            const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
-            const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
-            teardowns.push(() => clearInterval(timer));
-            // OS-wake (desktop only): the Electron shell bridges `powerMonitor`
-            // 'resume' to this DOM event. This is the ONE event-trigger the lifecycle
-            // still owns, because `visibilitychange` does NOT fire on wake-from-sleep
-            // and — unlike `online`/`visibilitychange` — the ConnectionManager's own
-            // browser listeners (`setupBrowserListeners`) don't cover wake.
-            //
-            // The `online` and `visibilitychange` listeners that used to live here
-            // were REMOVED: the FSM already re-probes on NETWORK_ONLINE / TAB_VISIBLE
-            // through this exact credential path, so registering them here too only
-            // fired a second, null-swallowing mint per focus — the "session-key
-            // POSTed on every tab focus" spam in the console.
-            const onWake = () => void refresh();
-            window.addEventListener('ablo:wake', onWake);
-            teardowns.push(() => window.removeEventListener('ablo:wake', onWake));
-        }
-        this.credentialLifecycleTeardown = () => {
-            for (const t of teardowns)
-                t();
-        };
+    startCredentialLifecycle(getToken, opts) {
+        this.credentialLifecycle.start(getToken, opts);
     }
     /** Tear down the proactive credential lifecycle (idempotent). */
     stopCredentialLifecycle() {
-        this.credentialLifecycleTeardown?.();
-        this.credentialLifecycleTeardown = null;
+        this.credentialLifecycle.stop();
+    }
+    // ── Sync group management ────────────────────────────────────────────────
+    //
+    // The implementation lives in the sync/groupChange module. The methods
+    // below are thin protected delegates that keep their signatures, so
+    // subclass override points still work; the module routes cross-handler
+    // calls back through `groupChangeContext()` to preserve dynamic dispatch.
+    /** Narrow context the group-change leaf talks back through. */
+    groupChangeContext() {
+        return {
+            database: this.database,
+            objectPool: this.objectPool,
+            getSubscribedSyncGroups: () => this.syncWebSocket?.getSyncGroups() ?? [],
+            getCurrentSyncGroups: () => this.userContext ? this.resolveSyncGroups(this.userContext) : null,
+            getBootstrapMode: () => this.userContext?.bootstrapMode,
+            disconnectWebSocket: () => { this.syncWebSocket?.disconnect(); },
+            emitConnectionEvent: (event) => { this.onConnectionEvent?.(event); },
+            handleGroupAdded: (payload, syncId) => this.handleGroupAdded(payload, syncId),
+            computeUpdatedSyncGroups: (payload) => this.computeUpdatedSyncGroups(payload),
+            forceFullRebootstrap: () => { this.forceFullRebootstrap(); },
+        };
     }
-    // ── Sync Group Management ────────────────────────────────────────────────
     /**
-     * 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}.
      */
     async handleSyncGroupChange(delta) {
-        const raw = typeof delta.data === 'string' ? JSON.parse(delta.data) : delta.data;
-        const rawObj = (raw ?? {});
-        // Detect incremental payload shape: { group, userId }
-        if (typeof rawObj.group === 'string' && typeof rawObj.userId === 'string') {
-            const incremental = {
-                group: rawObj.group,
-                userId: rawObj.userId,
-            };
-            await this.handleGroupAdded(incremental, delta.id);
-            return;
-        }
-        // Legacy payload: { addedGroups, removedGroups }
-        const payload = {
-            removedGroups: rawObj.removedGroups ?? [],
-            addedGroups: rawObj.addedGroups ?? [],
-        };
-        getContext().logger.info('[BaseSyncedStore] Sync group change received (legacy)', {
-            removedGroups: payload.removedGroups,
-            addedGroups: payload.addedGroups,
-            syncId: delta.id,
-        });
-        // SECURITY: If groups were removed, clear cached data immediately.
-        // This prevents revoked data from persisting if the device goes offline
-        // before the full re-bootstrap completes.
-        if (payload.removedGroups.length > 0) {
-            await this.database.clear();
-            this.objectPool.clear();
-            getContext().logger.info('[BaseSyncedStore] Cleared cached data due to revoked sync groups', {
-                removedGroups: payload.removedGroups,
-            });
-        }
-        const updatedGroups = this.computeUpdatedSyncGroups(payload);
-        await this.database.updateWorkspaceMetadata({ subscribedSyncGroups: updatedGroups });
-        this.forceFullRebootstrap();
+        return groupChange.handleSyncGroupChange(this.groupChangeContext(), delta);
     }
     /**
-     * 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}.
      */
     async handleGroupAdded(payload, syncId) {
-        getContext().logger.info('[BaseSyncedStore] Group added (incremental)', {
-            group: payload.group,
-            syncId,
-        });
-        const current = new Set(this.syncWebSocket?.getSyncGroups() ?? []);
-        current.add(payload.group);
-        await this.database.updateWorkspaceMetadata({ subscribedSyncGroups: Array.from(current) });
-        // Note: no forceFullRebootstrap() — covering deltas will bring the entities.
+        return groupChange.handleGroupAdded(this.groupChangeContext(), payload, syncId);
     }
     /**
-     * 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}.
      */
     async handleGroupRemoved(delta) {
-        const raw = typeof delta.data === 'string' ? JSON.parse(delta.data) : delta.data;
-        const rawObj = (raw ?? {});
-        const groupKey = typeof rawObj.group === 'string' ? rawObj.group : undefined;
-        if (!groupKey) {
-            getContext().logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
-                syncId: delta.id,
-            });
-            return;
-        }
-        getContext().logger.info('[BaseSyncedStore] Group removed', {
-            group: groupKey,
-            syncId: delta.id,
-        });
-        // SECURITY: Clear cached data before re-bootstrap. This prevents
-        // revoked-group data from persisting if the device goes offline
-        // between receiving 'S' and completing the re-bootstrap.
-        await this.database.clear();
-        this.objectPool.clear();
-        // Update subscription metadata so the re-bootstrap fetches the
-        // correct set of groups.
-        const current = new Set(this.syncWebSocket?.getSyncGroups() ?? []);
-        current.delete(groupKey);
-        await this.database.updateWorkspaceMetadata({ subscribedSyncGroups: Array.from(current) });
-        this.forceFullRebootstrap();
+        return groupChange.handleGroupRemoved(this.groupChangeContext(), delta);
     }
     /** Compute new sync groups after applying additions and removals */
     computeUpdatedSyncGroups(payload) {
-        const current = new Set(this.syncWebSocket?.getSyncGroups() ?? []);
-        for (const g of payload.removedGroups)
-            current.delete(g);
-        for (const g of payload.addedGroups)
-            current.add(g);
-        return Array.from(current);
-    }
-    /** 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.
-     */
+        return groupChange.computeUpdatedSyncGroups(this.groupChangeContext(), payload);
+    }
+    /** Force a full re-bootstrap via connection lifecycle event (no-op for
+     *  `bootstrapMode: 'none'` participants — see {@link groupChange.forceFullRebootstrap}). */
     forceFullRebootstrap() {
-        if (this.userContext?.bootstrapMode === 'none') {
-            getContext().logger.info('[BaseSyncedStore] forceFullRebootstrap skipped (bootstrapMode=none)');
-            return;
-        }
-        this.database.markRequiresFullBootstrap();
-        this.syncWebSocket?.disconnect();
-        this.onConnectionEvent?.('WS_DISCONNECTED');
+        groupChange.forceFullRebootstrap(this.groupChangeContext());
     }
     /**
      * Single source of truth for the sync-group list this session is
@@ -1007,71 +739,36 @@ export class BaseSyncedStore {
      * check can never disagree.
      */
     resolveSyncGroups(context) {
-        if (context.syncGroups && context.syncGroups.length > 0) {
-            return context.syncGroups;
-        }
-        return [];
+        return groupChange.resolveSyncGroups(context);
     }
     /** Check if sync groups shrank since last session — force full bootstrap if so */
     async checkSyncGroupShrinkage() {
-        if (!this.userContext)
-            return;
-        try {
-            const metadata = await this.database.getWorkspaceMetadata();
-            const stored = metadata?.subscribedSyncGroups ?? [];
-            if (stored.length === 0)
-                return;
-            const currentGroups = new Set(this.resolveSyncGroups(this.userContext));
-            const removedGroups = stored.filter((g) => !currentGroups.has(g));
-            if (removedGroups.length > 0) {
-                getContext().logger.info('[BaseSyncedStore] Sync groups shrank — forcing full bootstrap', {
-                    removedGroups,
-                    storedCount: stored.length,
-                    currentCount: currentGroups.size,
-                });
-                // SECURITY: Clear cached data before re-bootstrap to prevent
-                // revoked-group data from persisting if device goes offline
-                await this.database.clear();
-                this.objectPool.clear();
-                this.database.markRequiresFullBootstrap();
-            }
-            await this.database.updateWorkspaceMetadata({
-                subscribedSyncGroups: Array.from(currentGroups),
-            });
-        }
-        catch (error) {
-            getContext().logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
+        return groupChange.checkSyncGroupShrinkage(this.groupChangeContext());
     }
-    /** Apply bootstrap data to the ObjectPool with ghost removal */
-    /** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+    // ── Bootstrap apply ──────────────────────────────────────────────────────
+    //
+    // The implementation lives in the sync/bootstrapApply module. The protected
+    // delegates below keep their signatures and subclass overridability; the
+    // module talks back through `poolContext()`, with enrichment pre-bound to
+    // `this.enrichRelations` so that override point still applies.
+    /** Narrow context the bootstrap-apply leaf talks back through. */
+    poolContext() {
+        const store = this;
+        return {
+            applyDeltaBatchToPool: (results) => {
+                this.syncClient.applyDeltaBatchToPool(results, (name, data) => this.enrichRelations(name, data));
+            },
+            applyBootstrapDataToPool: (bootstrapData, protectedIds) => this.syncClient.applyBootstrapDataToPool(bootstrapData, protectedIds),
+            getPoolSize: () => this.objectPool.size,
+            getAllPoolIds: () => this.objectPool.getAllIds(),
+            get bootstrapDeltaQueue() { return store.bootstrapDeltaQueue; },
+            set bootstrapDeltaQueue(queue) { store.bootstrapDeltaQueue = queue; },
+            applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
+        };
+    }
+    /** Apply bootstrap data to the {@link InstanceCache}, removing entities that are no longer present (ghost removal). Pool writes are delegated to {@link SyncClient}. */
     applyBootstrapToPool(bootstrapResult, protectedIds) {
-        const { bootstrapData } = bootstrapResult;
-        // Partial bootstrap: Database.processDeltaBatch already wrote the deltas
-        // to IDB. Route the same results through the delta-apply path so the
-        // in-memory pool evicts deleted entities (and updates modified ones).
-        // Without this, reconnect DELETEs persist to IDB but the canvas keeps
-        // showing ghost layers until a full reload.
-        if (bootstrapData.type === 'partial') {
-            const deltaResults = bootstrapResult.deltaResults;
-            if (deltaResults && deltaResults.length > 0) {
-                this.syncClient.applyDeltaBatchToPool(deltaResults, (name, data) => this.enrichRelations(name, data));
-            }
-            return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
-        }
-        if (!bootstrapData.models) {
-            return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
-        }
-        const start = typeof performance !== 'undefined' ? performance.now() : Date.now();
-        // SyncClient owns: model creation, healing, pool upsert, ghost removal
-        const stats = this.syncClient.applyBootstrapDataToPool(bootstrapData, protectedIds);
-        const elapsedMs = Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - start);
-        getContext().logger.info('[BaseSyncedStore] Bootstrap applied', {
-            ...stats, elapsedMs, poolSize: this.objectPool.size,
-        });
-        return { ...stats, elapsedMs };
+        return bootstrapApply.applyBootstrapToPool(this.poolContext(), bootstrapResult, protectedIds);
     }
     // ── Initialize + Lifecycle ───────────────────────────────────────────────
     /**
@@ -1082,14 +779,11 @@ export class BaseSyncedStore {
         if (this.initialized)
             return { success: true };
         this.userContext = context;
-        // Propagate identity to SyncClient. Without this, every mutation
-        // silently drops in `processPendingMutations` / `stageMutation` with
-        // `userId=null, organizationId=null`. Previously the SDK assumed
-        // callers would call `syncClient.initialize()` themselves as a
-        // separate step — that never happened from createSyncEngine, and
-        // the drop was invisible because both guard sites just early-return
-        // rather than throw. The right fix is to do it here where the store
-        // receives the context, so identity is one source of truth.
+        // Propagate identity to the SyncClient. Without this, every mutation
+        // silently drops in the mutation-staging path with a null userId and
+        // organizationId, because those guards early-return rather than throw.
+        // Setting it here, where the store receives the context, keeps identity
+        // in a single place.
         yield this.syncClient.initialize(context.userId, context.organizationId);
         try {
             this.updateSyncStatus({ state: 'syncing', progress: 0 });
@@ -1108,12 +802,6 @@ export class BaseSyncedStore {
             // Get sync baseline for WebSocket
             const lastSyncId = (yield this.database.getLastSyncId());
             this.syncClient.position.advancePersisted(lastSyncId || 0);
-            try {
-                const versions = (yield this.database.getVersionVector());
-                if (versions && typeof versions === 'object')
-                    Object.assign(this.versionVector, versions);
-            }
-            catch { }
             // If local data available, show UI immediately
             if (hasLocalData) {
                 this.dataReady = true;
@@ -1154,8 +842,15 @@ export class BaseSyncedStore {
             }
             else if (requirements.type !== 'local') {
                 if (hasLocalData) {
-                    // Background bootstrap — don't block UI
-                    this.performBackgroundBootstrap(requirements, context, signal);
+                    // Background bootstrap — don't block UI. The method captures its own
+                    // operational failures; this backstop covers escapes from the
+                    // delta-queue replay in withDeltaQueuing's finally (and the error
+                    // handler itself), which would otherwise vanish unhandled.
+                    void this.performBackgroundBootstrap(requirements, context, signal).catch((error) => {
+                        getContext().observability.captureBootstrapFailure(error, {
+                            type: 'background-orchestration',
+                        });
+                    });
                 }
                 else {
                     // First load — must wait for server data
@@ -1253,27 +948,11 @@ export class BaseSyncedStore {
     }
     /** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
     collectDeltaProtectedIds(preBootstrapIds) {
-        const protectedIds = new Set();
-        for (const id of this.objectPool.getAllIds()) {
-            if (!preBootstrapIds.has(id))
-                protectedIds.add(id);
-        }
-        for (const delta of this.bootstrapDeltaQueue ?? []) {
-            if (delta.actionType !== 'D' && delta.modelId)
-                protectedIds.add(delta.modelId);
-        }
-        return protectedIds;
+        return bootstrapApply.collectDeltaProtectedIds(this.poolContext(), preBootstrapIds);
     }
-    /** Replay deltas queued during bootstrap */
+    /** Replay deltas queued during bootstrap (atomically, via `applyDeltaFrame`). */
     replayQueuedDeltas() {
-        const queue = this.bootstrapDeltaQueue;
-        this.bootstrapDeltaQueue = null;
-        if (!queue || queue.length === 0)
-            return;
-        // Deltas that landed during bootstrap are a complete frame — apply
-        // them atomically (one flush, one re-render) rather than dribbling
-        // each back through the live debounce path.
-        this.applyDeltaFrame(queue);
+        bootstrapApply.replayQueuedDeltas(this.poolContext());
     }
     /**
      * Factory for the internal `ConnectionManager`. Override to return
@@ -1336,6 +1015,10 @@ export class BaseSyncedStore {
         }
         this.syncClient.disconnect();
         this.queryProcessor.clearCache();
+        // Stop the pool's GC interval — the one timer the pool arms itself.
+        // Without this a discarded store retains its whole pool via the interval
+        // closure (and a Node process without `unref` support can't exit).
+        this.objectPool.stopGC();
         this.updateSyncStatus({ state: 'offline' });
     }
     /**
@@ -1434,7 +1117,6 @@ export class BaseSyncedStore {
             organizationId: context.organizationId,
             syncGroups: [...this.resolveSyncGroups(context)],
             lastSyncId,
-            versions: this.versionVector,
             kind: context.kind,
             capabilityToken: context.capabilityToken,
             getAuthToken: this.auth?.getAuthToken,
@@ -1449,7 +1131,7 @@ export class BaseSyncedStore {
         // connection. baseGroups (the org/user scopes) are always subscribed;
         // enterScope/leaveScope move per-entity interest. Recreated with the
         // socket; torn down via the disposer pushed below.
-        this.areaOfInterest = new AreaOfInterestManager({
+        this.areaOfInterest = new SubscriptionManager({
             transport: this.syncWebSocket,
             baseGroups: this.resolveSyncGroups(context),
         });
@@ -1506,7 +1188,9 @@ export class BaseSyncedStore {
                 this.updateSyncStatus({ state: 'error', error });
             }
         });
-        const onSessionError = this.syncWebSocket.subscribe('session_error', (error) => {
+        // Terminal session loss (revocation / the login itself is gone): notify,
+        // route the FSM to its terminal state, and clear local data.
+        const handleTerminalSessionError = (error) => {
             getContext().observability.captureWebSocketError({ context: 'session-error', error: error.message });
             this.onConnectionEvent?.('WS_SESSION_ERROR');
             for (const listener of this.sessionErrorListeners) {
@@ -1524,6 +1208,54 @@ export class BaseSyncedStore {
                 getContext().logger.debug('[BaseSyncedStore] Failed to clear database on session error', clearErr);
             });
             this.objectPool.clear();
+        };
+        const onSessionError = this.syncWebSocket.subscribe('session_error', (error) => {
+            // WS analog of HTTP's `apikey_expired` (see SyncSessionError.
+            // isSessionErrorResponse): the hub's keepalive reaper closes sockets
+            // whose SHORT-LIVED access credential (`ek_`/`rk_`) passed its expiry
+            // with `4001 credential_expired`. That is re-mintable from the
+            // still-valid login — recover silently (un-latch, single-flight
+            // re-mint, reconnect) instead of signing out and clearing local data.
+            // Only a mint that answers `null` (the login itself is gone) falls
+            // through to the terminal path. Without this branch, every credential
+            // TTL elapse wedged the socket behind the write-once session latch.
+            if (SyncSessionError.isSessionError(error) && isAccessCredentialExpiryCloseReason(error.message)) {
+                getContext().observability.breadcrumb('WebSocket closed for expired access credential — re-minting', 'sync.websocket', 'warning');
+                // Un-latch BEFORE the async mint so the FSM's own recovery
+                // (probe → refreshing_credential → reconnect) is never blocked on
+                // our .then() ordering.
+                this.syncWebSocket?.clearSessionError();
+                void this.performCredentialRefresh().then((outcome) => {
+                    if (outcome === 'refreshed') {
+                        if (this.connectionManager) {
+                            // Kick a parked FSM; a concurrent probe joins the same
+                            // single-flight mint, so this never double-mints.
+                            this.nudgeReconnect();
+                        }
+                        else {
+                            // Agent/system clients have no connection FSM
+                            // (createConnectionManager returns null for kind 'agent') —
+                            // reconnect the socket directly; connect() reads the
+                            // freshly-minted credential from the credential source.
+                            this.syncWebSocket?.resetReconnectAttempts();
+                            this.syncWebSocket?.connect();
+                        }
+                        return;
+                    }
+                    if (outcome === 'session_error') {
+                        // The mint endpoint rejected: the long-lived login is gone.
+                        // Re-latch so writes reject with the permanent session type
+                        // (see SyncWebSocket.notConnectedError) instead of parking.
+                        this.syncWebSocket?.setSessionErrorDetected();
+                        handleTerminalSessionError(error);
+                    }
+                    // 'network_error' → transient mint failure. The WS_DISCONNECTED
+                    // that follows this event already put the FSM on its probe/backoff
+                    // loop, which retries through the same single-flight refresh.
+                });
+                return;
+            }
+            handleTerminalSessionError(error);
         });
         // Handshake failed: WS close before open. The HTTP status is hidden
         // behind close code 1006, so we can't tell whether the server rejected
@@ -1647,69 +1379,66 @@ export class BaseSyncedStore {
         this.disposers.push(unsubCreated, unsubCompleted, unsubFailed);
         this.syncWebSocket.connect();
     }
-    // ── Delta Processing Pipeline ─────────────────────────────────────────────
-    /** State signature for delta deduplication */
-    extractStateSignature(delta) {
-        if (!delta.data || typeof delta.data !== 'object')
-            return null;
-        const data = typeof delta.data === 'string'
-            ? JSON.parse(delta.data)
-            : delta.data;
-        // Generic state fields — subclasses can override getStateFields() for model-specific fields
-        const fieldsToCheck = this.getStateFields(delta.modelName);
-        const signature = {
-            actionType: delta.actionType,
-            modelName: delta.modelName,
+    // ── Delta processing pipeline ─────────────────────────────────────────────
+    //
+    // The implementation lives in the sync/deltaPipeline module (deduplication,
+    // enqueue bookkeeping, debounce, flush). The methods below are thin protected
+    // delegates with unchanged signatures, and the module routes every call to a
+    // protected override point back through `deltaPipelineContext`, so subclass
+    // dynamic dispatch is preserved. `applyDeltaFrame`, the authoritative-apply
+    // correctness point, deliberately stays here.
+    /** 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). */
+    _deltaPipelineContext = null;
+    get deltaPipelineContext() {
+        if (this._deltaPipelineContext)
+            return this._deltaPipelineContext;
+        const store = this;
+        this._deltaPipelineContext = {
+            // Shared pipeline state, backed by the host fields.
+            get pendingDeltas() { return store.pendingDeltas; },
+            set pendingDeltas(deltas) { store.pendingDeltas = deltas; },
+            get batchTimer() { return store.batchTimer; },
+            set batchTimer(timer) { store.batchTimer = timer; },
+            get bootstrapDeltaQueue() { return store.bootstrapDeltaQueue; },
+            get smartSyncOptions() { return store.smartSyncOptions; },
+            get highestProcessedSyncId() { return store.highestProcessedSyncId; },
+            get lastAckedId() { return store.lastAckedId; },
+            // SyncClient position/transaction bookkeeping.
+            onDeltaReceived: (syncId) => { this.syncClient.onDeltaReceived(syncId); },
+            advanceApplied: (syncId) => { this.syncClient.position.advanceApplied(syncId); },
+            advancePersisted: (syncId) => { this.syncClient.position.advancePersisted(syncId); },
+            // Persistence + pool writes.
+            processDeltaBatch: (deltas) => this.database.processDeltaBatch(deltas),
+            applyDeltaBatchToPool: (results) => {
+                this.syncClient.applyDeltaBatchToPool(results, (name, data) => this.enrichRelations(name, data));
+            },
+            acknowledge: (syncId) => { this.syncWebSocket?.acknowledge?.(syncId); },
+            get objectPool() { return store.objectPool; },
+            // Dynamic-dispatch hooks — protected override points on this class.
+            getStateFields: (modelName) => this.getStateFields(modelName),
+            isCustomEntity: (modelName) => this.isCustomEntity(modelName),
+            createCustomEntity: (modelName, modelId, data) => this.createCustomEntity(modelName, modelId, data),
+            deduplicateDeltas: (deltas) => this.deduplicateDeltas(deltas),
+            flushPendingDeltas: () => this.flushPendingDeltas(),
+            handleFlushError: (error) => { this.handleFlushError(error); },
+            handleSyncGroupChange: (delta) => this.handleSyncGroupChange(delta),
+            handleGroupRemoved: (delta) => this.handleGroupRemoved(delta),
+            forceFullRebootstrap: () => { this.forceFullRebootstrap(); },
+            cascadeCancelTransactionsForDeletedParent: (parentModelName, parentId) => {
+                this.cascadeCancelTransactionsForDeletedParent(parentModelName, parentId);
+            },
         };
-        for (const field of fieldsToCheck) {
-            if (field in data)
-                signature[field] = data[field];
-        }
-        return signature;
+        return this._deltaPipelineContext;
     }
     /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
     getStateFields(_modelName) {
         return ['status', 'state', 'isActive'];
     }
-    isSameState(a, b) {
-        if (!a || !b)
-            return false;
-        const keys = Object.keys(a);
-        if (keys.length !== Object.keys(b).length)
-            return false;
-        return keys.every((k) => a[k] === b[k]);
-    }
     /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
     deduplicateDeltas(deltas) {
-        const byEntity = new Map();
-        for (const d of deltas) {
-            const key = `${d.modelName}:${d.modelId}`;
-            if (!byEntity.has(key))
-                byEntity.set(key, []);
-            byEntity.get(key).push(d);
-        }
-        const result = [];
-        for (const entityDeltas of byEntity.values()) {
-            const sorted = entityDeltas.sort((a, b) => a.id - b.id);
-            // DELETE wins — it's the final state
-            const del = sorted.find((d) => d.actionType === 'D');
-            if (del) {
-                result.push(del);
-                continue;
-            }
-            // Keep deltas that represent different states
-            const unique = [];
-            let prev = null;
-            for (const d of sorted) {
-                const sig = this.extractStateSignature(d);
-                if (!this.isSameState(prev, sig)) {
-                    unique.push(d);
-                    prev = sig;
-                }
-            }
-            result.push(...(unique.length > 0 ? unique : [sorted[sorted.length - 1]]));
-        }
-        return result.sort((a, b) => a.id - b.id);
+        return deltaPipeline.deduplicateDeltas(this.deltaPipelineContext, deltas);
     }
     /** Process incoming delta with smart batching */
     processDeltaWithBatching(delta) {
@@ -1720,35 +1449,36 @@ export class BaseSyncedStore {
     /**
      * 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`.
      */
     applyDeltaFrame(deltas) {
         let enqueuedAny = false;
         for (const delta of deltas) {
-            // A delta_batch frame is the server's AUTHORITATIVE, ordered answer to
+            // A delta_batch frame is the server's authoritative, ordered answer to
             // "everything in my stream after cursor C" (reconnect/catch-up replay or
-            // post-bootstrap drain). Apply every delta it carries — do NOT subject it
+            // post-bootstrap drain). Apply every delta it carries; do not subject it
             // to the live-traffic watermark dedup (`id <= applied`).
             //
             // That watermark is only valid under in-order delivery, and reconnect
-            // breaks the assumption: an in-flight LIVE broadcast for a gap delta can
-            // land out of order BEFORE the catch-up fills the ids below it (e.g. the
+            // breaks the assumption: an in-flight live broadcast for a gap delta can
+            // land out of order before the catch-up fills the ids below it (e.g. the
             // server acks a write, then the test/client reconnects, then that write's
             // pending broadcast arrives on the fresh socket — id 4 live before the
             // catch-up's [2,3,4]). Applying id 4 advances `applied` to 4, and the
@@ -1781,68 +1511,11 @@ export class BaseSyncedStore {
      * whether to debounce (live) or flush atomically (catch-up frame).
      */
     enqueueDelta(delta, options = {}) {
-        // Dedup guard — skip already-processed deltas. The `applied` watermark is a
-        // valid skip threshold ONLY for in-order live traffic; an authoritative
-        // catch-up frame bypasses it (see `applyDeltaFrame`) so an out-of-order
-        // live delta that advanced the watermark can't cause the frame's lower ids
-        // to be silently dropped.
-        if (!options.authoritative && delta.id > 0 && delta.id <= this.highestProcessedSyncId) {
-            return false;
-        }
-        // Confirm awaiting transactions via sync ID threshold (before batching)
-        this.syncClient.onDeltaReceived(delta.id);
-        // Update version vector
-        const entityType = delta.modelName.toLowerCase();
-        if (this.versionVector[entityType] !== undefined) {
-            this.versionVector[entityType] = Math.max(this.versionVector[entityType], delta.id);
-        }
-        // Queue during active bootstrap
-        if (this.bootstrapDeltaQueue !== null) {
-            this.bootstrapDeltaQueue.push(delta);
-            return false;
-        }
-        // Advance watermark
-        this.syncClient.position.advanceApplied(delta.id);
-        // Sync group added — handle immediately. Supports both legacy
-        // (addedGroups/removedGroups) and incremental (group/userId) payloads.
-        if (delta.actionType === 'G') {
-            void this.handleSyncGroupChange(delta);
-            return false;
-        }
-        // Sync group removed — handle immediately. Clears affected local state
-        // and forces re-bootstrap with the updated group list.
-        if (delta.actionType === 'S') {
-            void this.handleGroupRemoved(delta);
-            return false;
-        }
-        // DELETE — fire the cascade cancel immediately (O(1) via FK index;
-        // must run BEFORE any subsequent update on the same model lands so
-        // pending update transactions for soon-deleted children don't race
-        // their parent's delete) but route the IDB+pool write through the
-        // same batched path as UPDATEs. The previous immediate-flush path
-        // produced N IDB writes + N pool mutations + N `models:changed`
-        // events when a peer deleted a chart with N layers; the batched
-        // path produces one of each per microtask flush. Dedup in
-        // `flushPendingDeltas` handles the U-then-D-on-same-model case
-        // correctly via arrival-order replay through `processDeltaBatch`.
-        if (delta.actionType === 'D') {
-            this.cascadeCancelTransactionsForDeletedParent(delta.modelName, delta.modelId);
-        }
-        this.pendingDeltas.push(delta);
-        return true;
+        return deltaPipeline.enqueueDelta(this.deltaPipelineContext, delta, options);
     }
     /** Debounce a flush for live single-delta traffic. */
     scheduleDeltaFlush() {
-        if (this.batchTimer)
-            clearTimeout(this.batchTimer);
-        if (this.pendingDeltas.length >= this.smartSyncOptions.maxBatchSize) {
-            void this.flushPendingDeltas().catch(this.handleFlushError);
-        }
-        else {
-            this.batchTimer = setTimeout(() => {
-                void this.flushPendingDeltas().catch(this.handleFlushError);
-            }, this.smartSyncOptions.batchingDelay);
-        }
+        deltaPipeline.scheduleDeltaFlush(this.deltaPipelineContext);
     }
     /**
      * Cancel pending transactions for child entities when a parent is deleted.
@@ -1878,88 +1551,15 @@ export class BaseSyncedStore {
             });
         }
     }
-    /** 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}. */
     async flushPendingDeltas() {
-        if (this.pendingDeltas.length === 0)
-            return;
-        const deduplicatedDeltas = this.deduplicateDeltas(this.pendingDeltas);
-        // Custom entities → apply directly to ObjectPool (skip IDB)
-        const customDeltas = deduplicatedDeltas.filter((d) => this.isCustomEntity(d.modelName));
-        if (customDeltas.length > 0) {
-            runInAction(() => {
-                for (const delta of customDeltas) {
-                    const data = typeof delta.data === 'string'
-                        ? JSON.parse(delta.data)
-                        : delta.data;
-                    // 'C' (Covering) is treated identically to 'I' here — the client
-                    // gained permission to see the entity, so we insert it into the
-                    // pool as if newly created.
-                    if (delta.actionType === 'I' || delta.actionType === 'U' || delta.actionType === 'C') {
-                        const existing = this.objectPool.get(delta.modelId);
-                        if (existing) {
-                            existing.updateFromData(data);
-                        }
-                        else {
-                            const model = this.createCustomEntity(delta.modelName, delta.modelId, data);
-                            if (model) {
-                                model.markAsPersisted();
-                                this.objectPool.add(model, ModelScope.live);
-                            }
-                        }
-                    }
-                    else if (delta.actionType === 'D') {
-                        this.objectPool.remove(delta.modelId);
-                    }
-                }
-            });
-        }
-        // Regular deltas → IDB then ObjectPool via SyncClient.
-        // 'G' and 'S' deltas are routed upstream (handleSyncGroupChange,
-        // handleGroupRemoved) and never reach flushPendingDeltas, but the
-        // Database.processDelta signature accepts them defensively.
-        const regularDeltas = deduplicatedDeltas.filter((d) => !this.isCustomEntity(d.modelName));
-        const batch = await this.database.processDeltaBatch(regularDeltas.map((d) => ({
-            syncId: d.id,
-            actionType: d.actionType,
-            modelName: d.modelName,
-            modelId: d.modelId,
-            data: typeof d.data === 'string' ? JSON.parse(d.data) : d.data,
-            // Thread `transactionId` through so the receive layer can
-            // recognize echoes of locally-applied transactions and skip
-            // the pool mutation. See `OPTIMISTIC_RECONCILIATION.md`.
-            transactionId: d.transactionId,
-        })));
-        const dbResults = batch.results;
-        // Delegate ObjectPool writes to SyncClient (owns pool operations)
-        this.syncClient.applyDeltaBatchToPool(dbResults, (name, data) => this.enrichRelations(name, data));
-        // Acknowledge + advance sync cursor — gated on IDB persistence.
-        //
-        // We MUST ack `persistedSyncId` (the high-water mark of deltas whose
-        // store transaction actually committed), NOT the input batch's last
-        // delta id. Acking by input range advances the server's view past
-        // deltas that never wrote to IDB; the next catch-up request would
-        // then send the advanced cursor and the server replies "you're up
-        // to date" — losing the un-persisted delta forever. This is the
-        // Replicache "same-transaction" invariant: the cursor and the
-        // persisted view must be consistent.
-        const persistedSyncId = batch.persistedSyncId;
-        if (persistedSyncId > this.lastAckedId) {
-            this.syncWebSocket?.acknowledge?.(persistedSyncId);
-            this.syncClient.position.advancePersisted(persistedSyncId);
-        }
-        // Cache invalidation is automatic via SyncClient 'models:changed' event
-        this.pendingDeltas = [];
-        if (this.batchTimer) {
-            clearTimeout(this.batchTimer);
-            this.batchTimer = null;
-        }
+        return deltaPipeline.flushPendingDeltas(this.deltaPipelineContext);
     }
-    // ── Core Mutations (thin delegation to SyncClient) ────────────────────────
+    // ── Core mutations (thin delegation to SyncClient) ────────────────────────
     //
-    // BaseSyncedStore is an orchestrator, not an implementor.
-    // SyncClient owns: ObjectPool operations, TransactionQueue, IDB writes.
-    // BaseSyncedStore owns: validation, hooks, pending delete tracking.
+    // This class orchestrates; it does not implement the writes. {@link SyncClient}
+    // owns the object-pool operations, the transaction queue, and local writes.
+    // This class owns validation, lifecycle hooks, and pending-delete tracking.
     /** Check if a model type is local-only (no sync). Override for domain-specific models. */
     isLocalOnlyModel(_modelName) {
         return false;
@@ -2031,9 +1631,9 @@ export class BaseSyncedStore {
         this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
-    // `store.query.<model>.*` was DELETED — `ablo.<model>.get/getAll` is the
-    // one read surface. Custom mutators still read transactionally through
-    // `tx.<model>` (mutators/Transaction.ts), which owns `createReaderActions`.
+    // `ablo.<model>.get` / `ablo.<model>.getAll` is the read surface for
+    // application code. Custom mutators read transactionally through
+    // `tx.<model>`, backed by `createReaderActions`.
     /** Retrieve a single entity by id. Synchronous pool read. */
     retrieve(_modelClass, id) {
         return this.objectPool.get(id);
@@ -2077,10 +1677,10 @@ export class BaseSyncedStore {
         return this.objectPool.create(wireTypename, data);
     }
     /**
-     * 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, options) {
         const modelName = this.objectPool.registry.getModelNameFromConstructor(modelClass);
@@ -2189,8 +1789,7 @@ export class BaseSyncedStore {
         return this.lastAckedId;
     }
     // ── Status convenience getters ──────────────────────────────────────────
-    // Thin wrappers over syncStatus for consumer ergonomics. Previously on
-    // SyncedStore; moved here so createSyncEngine consumers get them too.
+    // Thin wrappers over `syncStatus` for consumer ergonomics.
     get isReady() {
         // Ready if: fully synced (idle + 100%) OR local data loaded (dataReady + syncing in background)
         return (this.syncStatus.state === 'idle' && this.syncStatus.progress >= 100)