@abloatai/ablo 0.34.1 → 0.35.0

package/dist/BaseSyncedStore.js

@@ -11,17 +11,18 @@
  * in-memory models, and {@link ModelRegistry} holds their metadata.
  */
 import { makeObservable, observable, action, computed, runInAction } from 'mobx';
-import { AbloConnectionError, AbloValidationError, toAbloError } from './errors.js';
+import { AbloConnectionError, AbloValidationError, toAbloError } from './transaction/errors.js';
 import { ConnectionManager } from './sync/ConnectionManager.js';
+import { contextLogger, contextSocketObservability } from './sync/contextPorts.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 { PropertyType } from './transaction/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, isAccessCredentialExpiryCloseReason } from './errors.js';
+import { AbloSessionError, isAccessCredentialExpiryCloseReason } from './transaction/errors.js';
 import { ModelScope } from './InstanceCache.js';
 import { LazyReferenceCollection } from './LazyReferenceCollection.js';
 import { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
@@ -29,9 +30,15 @@ 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 */
+/**
+ * Bootstrap retry configuration.
+ *
+ * There is deliberately no overall timeout here. How long one attempt may run
+ * is not a policy this layer gets to invent — it is a property of the fetcher's
+ * watchdogs, read from `BootstrapFetcher.budgetMs`. A second number kept here
+ * would only be able to disagree with them, which is exactly what it used to do.
+ */
 export const BOOTSTRAP_CONFIG = {
-    OVERALL_TIMEOUT_MS: 15_000,
     MAX_RETRY_ATTEMPTS: 3,
     RETRY_DELAY_MS: 500,
 };
@@ -58,13 +65,13 @@ export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
  * the underlying SyncWebSocket without casts:
  *
  * @example
- *   interface AbloEvents {
- *     'sheet:selection': [SheetSelectionEvent];
- *     'slide:cursor':    [SlideCursorEvent];
+ *   interface EditorEvents {
+ *     'document:selection': [SelectionEvent];
+ *     'document:cursor':    [CursorEvent];
  *   }
- *   class SyncedStore extends BaseSyncedStore<AbloEvents> {
- *     subscribeToSlideCursor(handler: (e: SlideCursorEvent) => void) {
- *       return this.syncWebSocket?.subscribe('slide:cursor', handler);
+ *   class EditorStore extends BaseSyncedStore<EditorEvents> {
+ *     subscribeToCursor(handler: (e: CursorEvent) => void) {
+ *       return this.syncWebSocket.subscribe('document:cursor', handler);
  *     }
  *   }
  */
@@ -88,15 +95,20 @@ export class BaseSyncedStore {
      */
     schema;
     // ── Real-time sync ──
-    syncWebSocket = null;
+    /**
+     * The connection, owned by whoever built this store (ADR 0016 follow-up
+     * 3b): the host constructs it and hands it in, the store seeds its late
+     * values during `initialize()` and owns the lifecycle from there. One
+     * instance for the store's whole lifetime — reconnects replace the socket
+     * inside it, never the object.
+     */
+    syncWebSocket;
     /**
      * Dynamic read interest (area-of-interest) over the connection's sync
-     * groups. Lives alongside `syncWebSocket` and is recreated with it; the
-     * stable `enterScope`/`leaveScope`/`pinScope`/`unpinScope` methods forward
-     * to whichever instance is current, so callers (the React participant
-     * hook) never hold a stale reference. Null until `setupWebSocketSync`.
+     * groups. Constructed with the connection; the permanent base scopes are
+     * seeded in `setupWebSocketSync` once identity resolves.
      */
-    areaOfInterest = null;
+    areaOfInterest;
     /** Sync groups whose current state has been backfilled into the pool
      *  (hydrate-on-enter). Cleared when the pool is reset on (re)bootstrap. */
     hydratedGroups = new Set();
@@ -104,27 +116,50 @@ export class BaseSyncedStore {
      *  enters of the same scope so they share one fetch. */
     hydratingGroups = new Map();
     _syncServerUrl;
+    /** Application-declared collaboration event types; empty unless configured. */
+    _collaborationEvents = [];
     /**
      * Public accessor for the underlying SyncWebSocket. Used by the
      * factory in `createSyncEngine` to wire the default mutation
      * executor — the executor needs the WS handle to send commit
      * frames, and the factory can't reach `protected` state through
-     * normal typing. Returns null until WS is initialized during
-     * `initialize()`.
+     * normal typing.
      */
     getSyncWebSocket() {
         return this.syncWebSocket;
     }
+    /**
+     * Subscribe to pushed frames — deltas, presence updates, claim grants and
+     * losses, connection changes, and this store's collaboration events.
+     * Durable by construction: the connection object exists for the store's
+     * whole lifetime (reconnects replace only the socket inside it), so a
+     * subscription made before the first connect starts delivering when the
+     * socket opens and keeps delivering across every reconnect. Returns the
+     * unsubscribe function.
+     */
+    subscribe(event, handler) {
+        return this.syncWebSocket.subscribe(event, handler);
+    }
+    /**
+     * Send a collaboration event (an app-specific real-time message from this
+     * store's `TCollaboration` map). A no-op while the connection is down —
+     * presence-grade traffic is not queued.
+     */
+    sendCollaborationEvent(messageType, payload) {
+        this.syncWebSocket.sendCollaborationEvent(messageType, payload);
+    }
     // ── Area-of-interest (dynamic read subscription) ─────────────────
     //
     // `enterScope`/`leaveScope` move the connection's read interest as the
-    // user navigates (open or close a deck, sheet, or doc); `pinScope`/`unpinScope`
+    // user navigates (open or close a record); `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
     // claim path uses (`resolveParticipantSyncGroups`), so read interest and
-    // 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}).
+    // write claims always agree on the string for a given entity. Before the
+    // connection opens they record interest without a wire send, and they
+    // never reject when the transport is offline (see
+    // {@link SubscriptionManager.reconcile}); the on-connect `resync` pushes
+    // whatever interest accumulated.
     scopeToGroups(scope) {
         return resolveParticipantSyncGroups(scope, this.schema);
     }
@@ -137,11 +172,8 @@ export class BaseSyncedStore {
      * and the live delta stream keeps flowing regardless.
      */
     enterScope(scope, opts) {
-        const mgr = this.areaOfInterest;
-        if (!mgr)
-            return Promise.resolve();
         const groups = this.scopeToGroups(scope);
-        const subscribed = Promise.all(groups.map((g) => mgr.enter(g))).then(() => undefined);
+        const subscribed = Promise.all(groups.map((g) => this.areaOfInterest.enter(g))).then(() => undefined);
         if (!opts?.hydrate)
             return subscribed;
         return subscribed.then(() => this.hydrateGroups(groups));
@@ -188,24 +220,15 @@ export class BaseSyncedStore {
     }
     /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
     leaveScope(scope) {
-        const mgr = this.areaOfInterest;
-        if (!mgr)
-            return Promise.resolve();
-        return Promise.all(this.scopeToGroups(scope).map((g) => mgr.leave(g))).then(() => undefined);
+        return Promise.all(this.scopeToGroups(scope).map((g) => this.areaOfInterest.leave(g))).then(() => undefined);
     }
     /** Pin a scope (active claim / prominence) → never warms while pinned. */
     pinScope(scope) {
-        const mgr = this.areaOfInterest;
-        if (!mgr)
-            return Promise.resolve();
-        return Promise.all(this.scopeToGroups(scope).map((g) => mgr.pin(g))).then(() => undefined);
+        return Promise.all(this.scopeToGroups(scope).map((g) => this.areaOfInterest.pin(g))).then(() => undefined);
     }
     /** Release a pin → the group transitions to warm rather than dropping. */
     unpinScope(scope) {
-        const mgr = this.areaOfInterest;
-        if (!mgr)
-            return Promise.resolve();
-        return Promise.all(this.scopeToGroups(scope).map((g) => mgr.unpin(g))).then(() => undefined);
+        return Promise.all(this.scopeToGroups(scope).map((g) => this.areaOfInterest.unpin(g))).then(() => undefined);
     }
     // ── Internal helpers ──
     queryProcessor;
@@ -237,18 +260,20 @@ export class BaseSyncedStore {
     pendingDeltas = [];
     batchTimer = null;
     syncPromise = null;
-    /** Resume/ack cursor — delegates to the shared SyncPosition (see
-     *  sync/syncPosition.ts). Advances only after IDB persistence. */
+    /** Resume/ack cursor — delegates to the shared LogPosition (see
+     *  logPosition.ts). Advances only after IDB persistence. */
     get lastAckedId() {
         return this.syncClient.position.persisted;
     }
-    /** Pool-applied cursor — delegates to the shared SyncPosition. */
+    /** Pool-applied cursor — delegates to the shared LogPosition. */
     get highestProcessedSyncId() {
         return this.syncClient.position.applied;
     }
     // ── Delta queuing during bootstrap ──
     bootstrapDeltaQueue = null;
     activeBootstrapCount = 0;
+    /** The live deadline for the bootstrap attempt in flight, if any. */
+    bootstrapDeadlineTimer = null;
     // ── Delete tracking ──
     pendingDeletes = new Set();
     // ── Model type hydration ──
@@ -262,6 +287,30 @@ export class BaseSyncedStore {
         this.auth = dependencies.auth;
         this.schema = dependencies.schema;
         this._syncServerUrl = dependencies.url;
+        this._collaborationEvents = config.collaborationEvents ?? [];
+        // The connection exists from construction (ADR 0016 follow-up 3b): the
+        // host hands one in, or the store builds its own. `deferConnect` holds
+        // it closed until `initialize()` has seeded identity and read scope, so
+        // nothing can open an unscoped connection in between.
+        this.syncWebSocket =
+            dependencies.syncWebSocket ??
+                new SyncWebSocket({
+                    baseUrl: this._syncServerUrl,
+                    collaborationEvents: [...this._collaborationEvents],
+                    getAuthToken: this.auth?.getAuthToken,
+                    deferConnect: true,
+                    capabilities: {
+                        partialBootstrap: true,
+                        compressedDeltas: true,
+                        streamingBootstrap: true,
+                        batchedDeltas: true,
+                    },
+                });
+        this.areaOfInterest = new SubscriptionManager({ transport: this.syncWebSocket });
+        this.wireSocketEvents();
+        // QueuedMutation events for pendingChanges tracking — connection-
+        // independent, wired once for the store's lifetime.
+        this.disposers.push(this.syncClient.onTransactionEvent('created', () => { this.incrementPendingChanges(); }), this.syncClient.onTransactionEvent('completed', () => { this.decrementPendingChanges(); }), this.syncClient.onTransactionEvent('failed', () => { this.decrementPendingChanges(); }));
         // Set this store as the global Model store
         Model.setStore(this);
         // ── Schema-derived sync plan ───────────────────────────────────────
@@ -414,7 +463,7 @@ export class BaseSyncedStore {
         reportSessionExpired: () => {
             this.connectionManager?.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
         },
-    });
+    }, contextLogger);
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -435,7 +484,7 @@ export class BaseSyncedStore {
     }
     /**
      * Subscribe to per-mutation failure payloads. Forwarded from the
-     * underlying `SyncClient.transactionQueue` so consumers (toast layer,
+     * underlying `SyncClient.mutationQueue` so consumers (toast layer,
      * route-level reverted boundaries, telemetry) can react without
      * reaching across the store. Returns an unsubscribe function.
      *
@@ -448,6 +497,15 @@ export class BaseSyncedStore {
     subscribeMutationFailure(listener) {
         return this.syncClient.onMutationFailure(listener);
     }
+    /**
+     * Subscribe to commit round-trip latency. Forwarded from the underlying
+     * `SyncClient` for the same reason as `subscribeMutationFailure` — the
+     * React provider binds against this surface, so the engine's wiring stays
+     * private while the SDK keeps one hook to expose.
+     */
+    subscribeCommitLatency(listener) {
+        return this.syncClient.onCommitLatency(listener);
+    }
     /**
      * Wait for the in-flight transaction for (modelName, modelId) to be
      * confirmed by the server. See `SyncClient.waitForConfirmation` for the
@@ -459,19 +517,19 @@ export class BaseSyncedStore {
     /**
      * Observe the LOCAL mutation stream for undo recording (see
      * {@link import('./core/storeContract.js').LocalMutation}). Taps the
-     * TransactionQueue's `transaction:created` event — fired once per local
+     * MutationQueue's `transaction:created` event — fired once per local
      * create/update/delete/archive with `previousData` already captured.
      * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
      * emit here, so undo is naturally local-only (you can't undo a teammate).
      */
     subscribeLocalMutations(handler) {
-        // Tap the TransactionQueue directly via `onLocalTransaction`. The previous
+        // Tap the MutationQueue directly via `onLocalTransaction`. The previous
         // `syncClient.subscribe('transaction:created', …)` route registered the
         // handler on SyncClient's OWN emitter, which never fires that event (only
         // the queue's emitter does) — so undo recorded nothing. See
         // `SyncClient.onLocalTransaction` for the full rationale.
         return this.syncClient.onLocalTransaction((tx) => {
-            if (!tx?.type || !tx.modelName || !tx.modelId)
+            if (!tx.modelName || !tx.modelId)
                 return;
             handler({
                 type: tx.type,
@@ -489,69 +547,113 @@ export class BaseSyncedStore {
      */
     async executeBootstrapWithTimeout(bootstrapFn, _context, signal) {
         let lastError = null;
-        for (let attempt = 1; attempt <= BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS; attempt++) {
-            if (signal?.aborted) {
-                throw new DOMException('Initialization aborted', 'AbortError');
-            }
-            // `navigator.onLine === false` is the MDN-reliable "definitely
-            // offline" signal. Don't use `!navigator.onLine`: Node 22+ exposes
-            // `globalThis.navigator` with `onLine === undefined`, so the
-            // negation false-positives every server-side bootstrap (e.g. the
-            // server-side agent.run dispatch path through `connectAgent`).
-            if (typeof navigator !== 'undefined' && navigator.onLine === false) {
-                getContext().observability.breadcrumb(`Bootstrap attempt ${attempt} skipped - offline`, 'sync.bootstrap', 'warning');
-                throw new AbloConnectionError('Bootstrap skipped - device is offline', {
-                    code: 'bootstrap_offline',
-                });
-            }
-            try {
-                getContext().logger.info(`[BaseSyncedStore] Bootstrap attempt ${attempt}/${BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS}`);
-                const result = (await Promise.race([
-                    bootstrapFn(),
-                    this.createBootstrapTimeout(attempt),
-                ]));
-                getContext().logger.info('[BaseSyncedStore] Bootstrap completed successfully', { attempt });
-                return result;
-            }
-            catch (error) {
-                lastError = error;
-                const isTimeout = error instanceof Error && error.message.includes('timed out');
-                const isAbort = error instanceof DOMException && error.name === 'AbortError';
-                const isNetworkError = error instanceof TypeError && error.message.includes('fetch');
-                if (isAbort)
-                    throw error;
-                if (SyncSessionError.isSessionError(error))
-                    throw error;
-                if (isNetworkError && typeof navigator !== 'undefined' && navigator.onLine === false) {
-                    getContext().observability.captureBootstrapFailure(error, { type: 'network-offline' });
-                    throw error;
+        // An aborted initialize has to stop the transfer, not just stop waiting for
+        // it. Without this the caller returns while a cold start keeps downloading,
+        // and those chunks are still in flight when the next initialize begins.
+        const onCallerAbort = () => { this.database.helper.abort(); };
+        signal?.addEventListener('abort', onCallerAbort, { once: true });
+        try {
+            for (let attempt = 1; attempt <= BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS; attempt++) {
+                if (signal?.aborted) {
+                    throw new DOMException('Initialization aborted', 'AbortError');
                 }
-                getContext().observability.breadcrumb(`Bootstrap attempt ${attempt} failed`, 'sync.bootstrap', 'warning', { isTimeout, isNetworkError, willRetry: attempt < BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS });
-                if (isTimeout && attempt < BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS) {
-                    getContext().logger.info('[BaseSyncedStore] Resetting state before bootstrap retry');
-                    this.resetBootstrapState();
-                    await new Promise((resolve) => setTimeout(resolve, BOOTSTRAP_CONFIG.RETRY_DELAY_MS));
+                // `navigator.onLine === false` is the MDN-reliable "definitely
+                // offline" signal. Don't use `!navigator.onLine`: Node 22+ exposes
+                // `globalThis.navigator` with `onLine === undefined`, so the
+                // negation false-positives every server-side bootstrap (e.g. the
+                // server-side agent.run dispatch path through `connectAgent`).
+                if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+                    getContext().observability.breadcrumb(`Bootstrap attempt ${attempt} skipped - offline`, 'sync.bootstrap', 'warning');
+                    throw new AbloConnectionError('Bootstrap skipped - device is offline', {
+                        code: 'bootstrap_offline',
+                    });
                 }
-                else if (!isTimeout && attempt < BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS) {
-                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                try {
+                    getContext().logger.info(`[BaseSyncedStore] Bootstrap attempt ${attempt}/${BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS}`);
+                    const result = (await Promise.race([
+                        bootstrapFn(),
+                        this.createBootstrapTimeout(attempt),
+                    ]));
+                    getContext().logger.info('[BaseSyncedStore] Bootstrap completed successfully', { attempt });
+                    return result;
+                }
+                catch (error) {
+                    lastError = error;
+                    const isTimeout = error instanceof Error && error.message.includes('timed out');
+                    const isAbort = error instanceof DOMException && error.name === 'AbortError';
+                    const isNetworkError = error instanceof TypeError && error.message.includes('fetch');
+                    if (isAbort)
+                        throw error;
+                    if (AbloSessionError.isSessionError(error))
+                        throw error;
+                    if (isNetworkError && typeof navigator !== 'undefined' && navigator.onLine === false) {
+                        getContext().observability.captureBootstrapFailure(error, { type: 'network-offline' });
+                        throw error;
+                    }
+                    getContext().observability.breadcrumb(`Bootstrap attempt ${attempt} failed`, 'sync.bootstrap', 'warning', { isTimeout, isNetworkError, willRetry: attempt < BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS });
+                    if (isTimeout && attempt < BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS) {
+                        getContext().logger.info('[BaseSyncedStore] Resetting state before bootstrap retry');
+                        this.resetBootstrapState();
+                        await new Promise((resolve) => setTimeout(resolve, BOOTSTRAP_CONFIG.RETRY_DELAY_MS));
+                    }
+                    else if (!isTimeout && attempt < BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS) {
+                        await new Promise((resolve) => setTimeout(resolve, 1000));
+                    }
+                }
+                finally {
+                    // Disarm this attempt's deadline the moment it settles — a live timer
+                    // would abort whatever the next attempt puts in flight.
+                    this.clearBootstrapDeadline();
                 }
             }
+            throw lastError
+                ? toAbloError(lastError)
+                : new AbloConnectionError('Bootstrap failed after all retry attempts', {
+                    code: 'bootstrap_fetch_timeout',
+                });
+        }
+        finally {
+            signal?.removeEventListener('abort', onCallerAbort);
+            this.clearBootstrapDeadline();
         }
-        throw lastError
-            ? toAbloError(lastError)
-            : new AbloConnectionError('Bootstrap failed after all retry attempts', {
-                code: 'bootstrap_fetch_timeout',
-            });
     }
-    /** Create a timeout promise for bootstrap attempts */
+    /**
+     * The outer deadline for one bootstrap attempt.
+     *
+     * The length is DERIVED from the fetcher's own watchdog budget, not chosen. A
+     * chosen number is what broke this: the previous fixed 15s was shorter than a
+     * single model chunk's allowance — 20s waiting for response headers plus 15s
+     * of stall grace — so on any workspace with one slow model the deadline fired
+     * before the watchdogs it was meant to backstop, and every attempt timed out
+     * by construction. The watchdogs below are progress-based and already
+     * guarantee termination; this deadline exists only for a hang somewhere other
+     * than the network, so it must sit above them, and it can only do that
+     * reliably by asking them how long they take.
+     *
+     * Reaching it aborts the work in flight. `Promise.race` merely stops waiting:
+     * without the abort the losing bootstrap keeps running, keeps its sockets, and
+     * races the retry that replaced it — which is how one page load turned into
+     * dozens of overlapping requests.
+     */
     createBootstrapTimeout(attempt) {
-        const timeoutMs = BOOTSTRAP_CONFIG.OVERALL_TIMEOUT_MS + (attempt - 1) * 3_000;
+        const timeoutMs = this.database.helper.budgetMs;
         return new Promise((_, reject) => {
-            setTimeout(() => {
+            this.clearBootstrapDeadline();
+            this.bootstrapDeadlineTimer = setTimeout(() => {
+                this.database.helper.abort();
                 reject(new AbloConnectionError(`Bootstrap timed out after ${timeoutMs}ms (attempt ${attempt})`, { code: 'bootstrap_fetch_timeout' }));
             }, timeoutMs);
         });
     }
+    /** Disarm the deadline once its attempt has settled. Load-bearing now that
+     *  firing it aborts real work: a leftover timer would cancel a later,
+     *  unrelated bootstrap. */
+    clearBootstrapDeadline() {
+        if (this.bootstrapDeadlineTimer !== null) {
+            clearTimeout(this.bootstrapDeadlineTimer);
+            this.bootstrapDeadlineTimer = null;
+        }
+    }
     /** Reset bootstrap-related state for a clean retry */
     resetBootstrapState() {
         try {
@@ -588,7 +690,7 @@ export class BaseSyncedStore {
                 await this.syncClient.hydrateFromDatabase();
                 this.dataReady = true;
             }
-            if (this.syncWebSocket && !this.syncWebSocket.isConnected()) {
+            if (!this.syncWebSocket.isConnected()) {
                 this.syncWebSocket.resetReconnectAttempts();
                 this.syncWebSocket.connect();
             }
@@ -597,9 +699,9 @@ export class BaseSyncedStore {
         }
         catch (error) {
             getContext().observability.captureBootstrapFailure(error, { type: 'connection-store-reconnect' });
-            if (SyncSessionError.isSessionError(error)) {
-                this.syncWebSocket?.setSessionErrorDetected();
-                this.syncWebSocket?.disconnect();
+            if (AbloSessionError.isSessionError(error)) {
+                this.syncWebSocket.setSessionErrorDetected();
+                this.syncWebSocket.disconnect();
                 this.updateSyncStatus({ state: 'error', error: error });
                 // SECURITY: Clear locally cached data when session is invalid
                 this.database.clear({ includeWriteJournal: true }).catch(() => { });
@@ -609,10 +711,14 @@ export class BaseSyncedStore {
             if (!this.dataReady && this.objectPool.size === 0) {
                 try {
                     await this.syncClient.hydrateFromDatabase();
-                    if (this.objectPool.size > 0) {
+                    // Re-read through a local: the guard above narrowed `size` to 0, and
+                    // the compiler carries that narrowing across the await even though
+                    // hydrating is precisely what fills the pool.
+                    const hydratedSize = this.objectPool.size;
+                    if (hydratedSize > 0) {
                         this.dataReady = true;
                         getContext().logger.info('[BaseSyncedStore] Hydrated from local fallback', {
-                            objectPoolSize: this.objectPool.size,
+                            objectPoolSize: hydratedSize,
                         });
                     }
                 }
@@ -688,10 +794,10 @@ export class BaseSyncedStore {
         return {
             database: this.database,
             objectPool: this.objectPool,
-            getSubscribedSyncGroups: () => this.syncWebSocket?.getSyncGroups() ?? [],
+            getSubscribedSyncGroups: () => this.syncWebSocket.getSyncGroups(),
             getCurrentSyncGroups: () => this.userContext ? this.resolveSyncGroups(this.userContext) : null,
             getBootstrapMode: () => this.userContext?.bootstrapMode,
-            disconnectWebSocket: () => { this.syncWebSocket?.disconnect(); },
+            disconnectWebSocket: () => { this.syncWebSocket.disconnect(); },
             emitConnectionEvent: (event) => { this.onConnectionEvent?.(event); },
             handleGroupAdded: (payload, syncId) => this.handleGroupAdded(payload, syncId),
             computeUpdatedSyncGroups: (payload) => this.computeUpdatedSyncGroups(payload),
@@ -877,11 +983,11 @@ export class BaseSyncedStore {
                 this.updateSyncStatus({ state: 'idle', progress: 0 });
                 return { success: false, error: error };
             }
-            const isSession = SyncSessionError.isSessionError(error);
+            const isSession = AbloSessionError.isSessionError(error);
             getContext().observability.captureBootstrapFailure(error, { type: 'initialize' });
             if (isSession) {
-                this.syncWebSocket?.setSessionErrorDetected();
-                this.syncWebSocket?.disconnect();
+                this.syncWebSocket.setSessionErrorDetected();
+                this.syncWebSocket.disconnect();
                 this.updateSyncStatus({ state: 'error', error: error });
                 return { success: false, error: error };
             }
@@ -895,7 +1001,7 @@ export class BaseSyncedStore {
             if (this.objectPool.size > 0) {
                 this.dataReady = true;
                 this.initialized = true;
-                this.updateSyncStatus(this.syncWebSocket?.isConnected()
+                this.updateSyncStatus(this.syncWebSocket.isConnected()
                     ? { state: 'idle', progress: 100 }
                     : { state: 'offline', offlineSince: new Date() });
                 return { success: true };
@@ -920,12 +1026,12 @@ export class BaseSyncedStore {
                     cause: error,
                 });
                 getContext().observability.captureBootstrapFailure(error, { type: 'background' });
-                if (SyncSessionError.isSessionError(error)) {
-                    this.syncWebSocket?.setSessionErrorDetected();
-                    this.syncWebSocket?.disconnect();
+                if (AbloSessionError.isSessionError(error)) {
+                    this.syncWebSocket.setSessionErrorDetected();
+                    this.syncWebSocket.disconnect();
                     this.updateSyncStatus({ state: 'error', error: error });
                 }
-                else if (!this.syncWebSocket?.isConnected()) {
+                else if (!this.syncWebSocket.isConnected()) {
                     this.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
                 }
             }
@@ -984,10 +1090,19 @@ export class BaseSyncedStore {
             return null;
         return new ConnectionManager({
             baseUrl: this._syncServerUrl,
-            getAuthToken: () => this.auth?.getAuthToken() ?? this.syncWebSocket?.getAuthToken() ?? null,
+            getAuthToken: () => this.auth?.getAuthToken() ?? this.syncWebSocket.getAuthToken() ?? null,
+            logger: contextLogger,
+            observability: contextSocketObservability,
         });
     }
-    /** Disconnect and clean up all resources */
+    /**
+     * Disconnect and clean up all resources. Terminal: this means "the client
+     * is finished", not "close and reopen later" — the connection object stays
+     * assigned but closed, the event wiring is torn down, and nothing
+     * re-initializes a disconnected store. (Mid-session closes during recovery
+     * go through the connection FSM's `onDisconnectWebSocket`, which closes
+     * the transport without touching the store.)
+     */
     async disconnect() {
         this.stopCredentialLifecycle();
         if (this.batchTimer) {
@@ -1003,15 +1118,12 @@ export class BaseSyncedStore {
             this.connectionManager = null;
         }
         try {
-            const last = this.syncWebSocket?.getLastSyncId?.() || 0;
+            const last = this.syncWebSocket.getLastSyncId();
             if (last > 0)
                 await this.database.updateWorkspaceMetadata({ lastSyncId: last });
         }
         catch { }
-        if (this.syncWebSocket) {
-            this.syncWebSocket.disconnect();
-            this.syncWebSocket = null;
-        }
+        this.syncWebSocket.disconnect();
         this.syncClient.disconnect();
         this.queryProcessor.clearCache();
         // Stop the pool's GC interval — the one timer the pool arms itself.
@@ -1081,8 +1193,6 @@ export class BaseSyncedStore {
      */
     async waitForWebSocketConnected(timeoutMs) {
         const ws = this.syncWebSocket;
-        if (!ws)
-            return false;
         if (ws.isConnected())
             return true;
         return new Promise((resolve) => {
@@ -1105,35 +1215,48 @@ export class BaseSyncedStore {
             }, timeoutMs);
         });
     }
+    /**
+     * Seed the connection's late values and open it. The socket itself exists
+     * from construction; what identity resolution supplies — the participant
+     * kind, the credential, the read scope, and the resume cursor — is seeded
+     * here, and only then is the held first connect released. A retried
+     * `initialize()` after a failed `ready()` re-runs this against the same
+     * connection object: the reconnect counter is reset for a clean slate,
+     * while the session-error latch deliberately survives (only the
+     * credential-expiry recovery clears it).
+     */
     setupWebSocketSync(context, lastSyncId) {
         if (!context.userId || !context.organizationId) {
             getContext().observability.breadcrumb('Cannot setup WebSocket sync without user context', 'sync.websocket', 'warning');
             return;
         }
-        this.syncWebSocket = new SyncWebSocket({
-            baseUrl: this._syncServerUrl,
-            userId: context.userId,
-            organizationId: context.organizationId,
-            syncGroups: [...this.resolveSyncGroups(context)],
-            lastSyncId,
-            kind: context.kind,
-            capabilityToken: context.capabilityToken,
-            getAuthToken: this.auth?.getAuthToken,
-            capabilities: {
-                partialBootstrap: true,
-                compressedDeltas: true,
-                streamingBootstrap: true,
-                batchedDeltas: true,
-            },
-        });
-        // Area-of-interest manager — owns dynamic read-subscription over this
-        // 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 SubscriptionManager({
-            transport: this.syncWebSocket,
-            baseGroups: this.resolveSyncGroups(context),
-        });
+        if (context.kind)
+            this.syncWebSocket.setKind(context.kind);
+        if (context.capabilityToken) {
+            this.syncWebSocket.setCapabilityToken(context.capabilityToken);
+        }
+        const syncGroups = this.resolveSyncGroups(context);
+        this.syncWebSocket.setSyncGroups(syncGroups);
+        this.syncWebSocket.setLastSyncId(lastSyncId || 0);
+        // The permanent base scopes for read interest — same set the connection
+        // subscribes to at upgrade, so the two can never disagree.
+        this.areaOfInterest.setBaseGroups(syncGroups);
+        // ── Connection FSM ────────────────────────────────────────────
+        // Instantiate + start the SDK's ConnectionManager so every consumer
+        // gets correct online/offline recovery. Guarded: a retried
+        // `initialize()` reuses the manager it already started.
+        if (!this.connectionManager)
+            this.startConnectionManager(context.kind);
+        this.syncWebSocket.resetReconnectAttempts();
+        this.syncWebSocket.allowConnect();
+        this.syncWebSocket.connect();
+    }
+    /**
+     * Wire the store's handlers onto the connection. Runs once, at
+     * construction — the connection object is stable for the store's
+     * lifetime, so the wiring is too.
+     */
+    wireSocketEvents() {
         // Connection events → forward to connection lifecycle callback
         const onConnected = this.syncWebSocket.subscribe('connected', () => {
             this.syncClient.markConnected();
@@ -1149,7 +1272,7 @@ export class BaseSyncedStore {
             // changed while offline; after a full reconnect the new socket's URL
             // carries only base groups. `resync` re-pushes the current desired set
             // so the server-side index matches what the user is actually viewing.
-            void this.areaOfInterest?.resync();
+            void this.areaOfInterest.resync();
         });
         const onDisconnected = this.syncWebSocket.subscribe('disconnected', () => {
             this.syncClient.disconnect();
@@ -1209,7 +1332,7 @@ export class BaseSyncedStore {
             this.objectPool.clear();
         };
         const onSessionError = this.syncWebSocket.subscribe('session_error', (error) => {
-            // WS analog of HTTP's `apikey_expired` (see SyncSessionError.
+            // WS analog of HTTP's `apikey_expired` (see AbloSessionError.
             // 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
@@ -1218,12 +1341,12 @@ export class BaseSyncedStore {
             // 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)) {
+            if (AbloSessionError.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();
+                this.syncWebSocket.clearSessionError();
                 void this.performCredentialRefresh().then((outcome) => {
                     if (outcome === 'refreshed') {
                         if (this.connectionManager) {
@@ -1236,8 +1359,8 @@ export class BaseSyncedStore {
                             // (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();
+                            this.syncWebSocket.resetReconnectAttempts();
+                            this.syncWebSocket.connect();
                         }
                         return;
                     }
@@ -1245,7 +1368,7 @@ export class BaseSyncedStore {
                         // 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();
+                        this.syncWebSocket.setSessionErrorDetected();
                         handleTerminalSessionError(error);
                     }
                     // 'network_error' → transient mint failure. The WS_DISCONNECTED
@@ -1271,15 +1394,16 @@ export class BaseSyncedStore {
             getContext().logger.debug('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
             this.updateSyncStatus({ state: 'reconnecting' });
         });
-        this.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { this.areaOfInterest?.dispose(); this.areaOfInterest = null; });
-        // ── Connection FSM ────────────────────────────────────────────
-        // Instantiate + start the SDK's ConnectionManager so every
-        // consumer gets correct online/offline recovery. Previously this
-        // was an external concern (each app rebuilt its own FSM); now
-        // it's default behavior. The `onConnectionEvent` hook stays as
-        // the bridge — WS events fire the hook, the hook forwards into
-        // the FSM.
-        this.connectionManager = this.createConnectionManager(context.kind);
+        this.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { this.areaOfInterest.dispose(); });
+    }
+    /**
+     * Build and start the connection FSM. The `onConnectionEvent` hook is the
+     * bridge — WS events fire the hook, the hook forwards into the FSM. Called
+     * from `setupWebSocketSync` because the FSM's shape depends on the resolved
+     * participant kind (agents get none — see {@link createConnectionManager}).
+     */
+    startConnectionManager(kind) {
+        this.connectionManager = this.createConnectionManager(kind);
         if (this.connectionManager) {
             const manager = this.connectionManager;
             // Preserve any externally-set onConnectionEvent — chain rather
@@ -1310,7 +1434,7 @@ export class BaseSyncedStore {
                 onReconnect: () => this.performReconnect(),
                 onRefreshCredential: () => this.performCredentialRefresh(),
                 onSessionExpired: () => {
-                    const err = new SyncSessionError('Session expired');
+                    const err = new AbloSessionError('Session expired');
                     for (const listener of this.sessionErrorListeners) {
                         try {
                             listener(err);
@@ -1319,7 +1443,7 @@ export class BaseSyncedStore {
                     }
                 },
                 onDisconnectWebSocket: () => {
-                    this.syncWebSocket?.disconnect();
+                    this.syncWebSocket.disconnect();
                 },
                 // Mirror FSM transitions into the visible `syncStatus.state` so
                 // the UI can show "Reconnecting…" while the FSM cycles through
@@ -1371,12 +1495,6 @@ export class BaseSyncedStore {
                 },
             });
         }
-        // Transaction events for pendingChanges tracking
-        const unsubCreated = this.syncClient.onTransactionEvent('created', () => { this.incrementPendingChanges(); });
-        const unsubCompleted = this.syncClient.onTransactionEvent('completed', () => { this.decrementPendingChanges(); });
-        const unsubFailed = this.syncClient.onTransactionEvent('failed', () => { this.decrementPendingChanges(); });
-        this.disposers.push(unsubCreated, unsubCompleted, unsubFailed);
-        this.syncWebSocket.connect();
     }
     // ── Delta processing pipeline ─────────────────────────────────────────────
     //
@@ -1415,7 +1533,7 @@ export class BaseSyncedStore {
             applyDeltaBatchToPool: (results) => {
                 this.syncClient.applyDeltaBatchToPool(results, (name, data) => this.enrichRelations(name, data));
             },
-            acknowledge: (syncId) => { this.syncWebSocket?.acknowledge?.(syncId); },
+            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),
@@ -1525,7 +1643,7 @@ export class BaseSyncedStore {
      * schema build time) to find children. The previous implementation did
      * `getByType(ctor).filter(e => e.toJSON()[foreignKey] === parentId)` —
      * a full pool scan per child model + a `toJSON()` allocation per
-     * candidate. For a deck delete with 10K layers in the pool, that was
+     * candidate. For a report delete with 10K blocks in the pool, that was
      * 10K toJSON allocations per cascade level. The FK-indexed lookup
      * skips both the scan AND the allocation.
      */
@@ -1584,7 +1702,7 @@ export class BaseSyncedStore {
      * Save a model (create or update).
      *
      * Accepts any entity shape with `{ id: string }` so consumers can pass the
-     * Zod-inferred model types from `InferModel<Schema, K>` without knowing
+     * Zod-inferred model types from `Model<Schema, K>` without knowing
      * about the internal `Model` base class. At runtime, every entity reaching
      * this method came through the object pool (via `store.create`, a query
      * accessor, or an optimistic insert) and IS a `Model` instance — the one
@@ -1607,7 +1725,7 @@ export class BaseSyncedStore {
             this.syncClient.update(model);
         }
     }
-    /** Save with an atomic server mutation (e.g., createSlideWithLayers) */
+    /** Save with an atomic server mutation (e.g., createSectionWithBlocks) */
     async saveWithAtomicMutation(model, mutation) {
         this.objectPool.add(model, ModelScope.live);
         await mutation(this.syncClient.gql);
@@ -1632,7 +1750,7 @@ export class BaseSyncedStore {
         this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
-    // `ablo.<model>.get` / `ablo.<model>.getAll` is the read surface for
+    // `ablo.<model>.local.retrieve` / `.local.list` 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. */
@@ -1655,13 +1773,13 @@ export class BaseSyncedStore {
      * Create a model instance locally, typed via the schema.
      *
      * ```ts
-     * const sheet = store.create('spreadsheetSheets', { name, spreadsheetId });
-     * // sheet: SpreadsheetSheet | null — no cast needed
+     * const ledger = store.create('ledgers', { name, reportId });
+     * // ledger: Ledger | null — no cast needed
      * ```
      *
      * The `typename` arg is the schema key (camelCase plural, e.g.
-     * `'spreadsheetSheets'`); the returned instance has the
-     * `InferModel<Schema, K>` shape including computeds + relation accessors.
+     * `'ledgers'`); the returned instance has the
+     * `Model<Schema, K>` shape including computeds + relation accessors.
      * Wraps `pool.create(...)` — the underlying runtime is unchanged, just
      * type-narrowed.
      */
@@ -1718,14 +1836,14 @@ export class BaseSyncedStore {
     /**
      * Get all models of a type. Returns Model[] honestly — callers that need
      * narrow types should use `useAblo((ablo) => ablo.<model>.list(...))`
-     * which does proper inference via `InferModel<S, K>`.
+     * which does proper inference via `Model<S, K>`.
      */
     allModelsOfType(modelClass, scope) {
         return this.objectPool.getByType(modelClass, scope ?? ModelScope.live);
     }
     /** Error handler for fire-and-forget flushPendingDeltas calls */
     handleFlushError = (error) => {
-        getContext().observability.captureTransactionFailure({
+        getContext().observability.captureMutationFailure({
             context: 'flush-pending-deltas',
             modelName: 'batch',
             modelId: 'batch',
@@ -1744,8 +1862,6 @@ export class BaseSyncedStore {
             modelId: delta.modelId,
             data: typeof delta.data === 'string' ? JSON.parse(delta.data) : delta.data,
         });
-        if (!dbResult)
-            return;
         // Track pending deletes for query filtering
         if (dbResult.action === 'remove') {
             this.pendingDeletes.add(dbResult.modelId);