@abloatai/humans 0.37.0

package/dist/local/BaseSyncedStore.js

@@ -0,0 +1,1516 @@
+/**
+ * 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.
+ *
+ * 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, action, computed, runInAction } from 'mobx';
+import { AbloConnectionError, AbloValidationError, toAbloError } from '@abloatai/transaction/errors';
+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 '@abloatai/transaction/types';
+import { SyncWebSocket, } from './sync/SyncWebSocket.js';
+import { QueryProcessor } from './query/QueryProcessor.js';
+import { Model, rowAsModel } from './Model.js';
+import { globalRuntime } from './context.js';
+import { AbloSessionError, isAccessCredentialExpiryCloseReason } from '@abloatai/transaction/errors';
+import { ModelScope } from './InstanceCache.js';
+import { LazyReferenceCollection } from './LazyReferenceCollection.js';
+import { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
+import { CredentialLifecycle } from './sync/credentialLifecycle.js';
+import { TerminalSessionLifecycle } from './sync/terminalSessionLifecycle.js';
+import { wireSocketEvents } from './sync/socketEventWiring.js';
+import { performReconnect as runReconnect } from './sync/reconnect.js';
+import { initialize as runInitialize } from './sync/initialize.js';
+import { createConnectionManager as runCreateConnectionManager, startConnectionManager as runStartConnectionManager, waitForWebSocketConnected as runWaitForWebSocketConnected, } from './sync/connectionManagerLifecycle.js';
+import * as groupChange from './sync/groupChange.js';
+import * as bootstrapApply from './sync/bootstrapApply.js';
+import * as deltaPipeline from './sync/deltaPipeline.js';
+import { queryByClass as runQueryByClass, countModels } from './store/queryApi.js';
+/**
+ * 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 = {
+    MAX_RETRY_ATTEMPTS: 3,
+    RETRY_DELAY_MS: 500,
+};
+// 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 ──────────────────────────────────────────────────────────────
+/**
+ * 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.
+ *
+ * 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).
+ * Subclasses pass their own event map to get typed `subscribe()` calls on
+ * the underlying SyncWebSocket without casts:
+ *
+ * @example
+ *   interface EditorEvents {
+ *     'document:selection': [SelectionEvent];
+ *     'document:cursor':    [CursorEvent];
+ *   }
+ *   class EditorStore extends BaseSyncedStore<EditorEvents> {
+ *     subscribeToCursor(handler: (e: CursorEvent) => void) {
+ *       return this.syncWebSocket.subscribe('document:cursor', handler);
+ *     }
+ *   }
+ */
+export class BaseSyncedStore {
+    // ── Observable sync status for UI ──
+    syncStatus = {
+        state: 'idle',
+        progress: 0,
+        pendingChanges: 0,
+        isSessionError: false,
+    };
+    // ── Injected dependencies ──
+    /** The owning client's runtime; the module-global bridge when constructed directly. */
+    runtime;
+    /** The installed plugins the delta pipeline dispatches stage handlers to. */
+    stagePlugins;
+    syncClient;
+    database;
+    objectPool;
+    modelRegistry;
+    auth;
+    /**
+     * Schema the store was constructed with. Used by the schema-typed
+     * `create(key, data)` factory and model self-healing.
+     */
+    schema;
+    // ── Real-time sync ──
+    /**
+     * 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. Constructed with the connection; the permanent base scopes are
+     * seeded in `setupWebSocketSync` once identity resolves.
+     */
+    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();
+    /** In-flight scoped hydrations, keyed by group — single-flights concurrent
+     *  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.
+     */
+    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 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. 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);
+    }
+    /**
+     * 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 groups = this.scopeToGroups(scope);
+        const subscribed = Promise.all(groups.map((g) => this.areaOfInterest.enter(g))).then(() => undefined);
+        if (!opts?.hydrate)
+            return subscribed;
+        return subscribed.then(() => this.hydrateGroups(groups));
+    }
+    /**
+     * 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));
+        if (need.length === 0) {
+            // Nothing new to fetch, but await any in-flight hydration for the
+            // requested groups so callers can sequence on completion.
+            await Promise.all(syncGroups
+                .map((g) => this.hydratingGroups.get(g))
+                .filter((p) => p !== undefined));
+            return;
+        }
+        const work = (async () => {
+            try {
+                const data = await this.database.fetchScopedBootstrapData(need);
+                this.syncClient.applyBootstrapDataToPool(data, undefined, { scoped: true });
+                for (const g of need)
+                    this.hydratedGroups.add(g);
+            }
+            catch (err) {
+                this.runtime.logger.debug('[BaseSyncedStore] scoped hydrate failed', {
+                    syncGroups: need,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                // Soft-fail — leave `need` un-hydrated so a re-enter retries.
+            }
+            finally {
+                for (const g of need)
+                    this.hydratingGroups.delete(g);
+            }
+        })();
+        for (const g of need)
+            this.hydratingGroups.set(g, work);
+        await work;
+    }
+    /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
+    leaveScope(scope) {
+        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) {
+        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) {
+        return Promise.all(this.scopeToGroups(scope).map((g) => this.areaOfInterest.unpin(g))).then(() => undefined);
+    }
+    // ── Internal helpers ──
+    queryProcessor;
+    /**
+     * 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 ──
+    // 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 ──
+    /**
+     * Declarative enrichment plan: "for model X, when a delta arrives,
+     * read data[foreignKey] and attach the matching parent from the pool
+     * as data[relationKey]." Merged from schema-derived + config at
+     * construction time. Replaces the `enrichRelations` subclass override
+     * pattern.
+     */
+    enrichmentPlan = [];
+    smartSyncOptions;
+    pendingDeltas = [];
+    batchTimer = null;
+    syncPromise = null;
+    /** 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 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 ──
+    modelTypesHydrated = new Set();
+    modelTypeHydrationInFlight = new Map();
+    constructor(dependencies, config = {}) {
+        this.runtime = dependencies.runtime ?? globalRuntime;
+        this.stagePlugins = dependencies.stagePlugins ?? [];
+        this.syncClient = dependencies.syncClient;
+        this.database = dependencies.database;
+        this.objectPool = dependencies.objectPool;
+        this.modelRegistry = dependencies.modelRegistry;
+        this.auth = dependencies.auth;
+        this.schema = dependencies.schema;
+        this.terminalSessionLifecycle = new TerminalSessionLifecycle({
+            runtime: this.runtime,
+            listeners: this.sessionErrorListeners,
+            purgeAuthenticatedState: () => this.purge(),
+            updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
+        });
+        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 ───────────────────────────────────────
+        //
+        // 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 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)
+            : { enrichmentPlan: [], foreignKeyIndexes: [] };
+        const mergedForeignKeyIndexes = [
+            ...derived.foreignKeyIndexes,
+            ...(config.foreignKeyIndexes ?? []),
+        ];
+        for (const { modelName, fieldName } of mergedForeignKeyIndexes) {
+            this.objectPool.registerForeignKey(modelName, fieldName);
+        }
+        // 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,
+            ...(config.enrichmentPlan ?? []),
+        ];
+        // Set dependencies for LazyReferenceCollection
+        LazyReferenceCollection.setDependencies(this.database, this.objectPool);
+        // Apply config defaults
+        this.config = {
+            enableOffline: config.enableOffline ?? true,
+            enableCache: config.enableCache ?? true,
+            enableTelemetry: config.enableTelemetry ?? false,
+        };
+        // Smart sync options
+        this.smartSyncOptions = {
+            maxDeltasBeforeBootstrap: 1000,
+            maxBootstrapSize: 10 * 1024 * 1024,
+            batchingDelay: 100,
+            maxBatchSize: 50,
+        };
+        // Create internal helpers
+        this.queryProcessor = new QueryProcessor({
+            enableCache: this.config.enableCache,
+        });
+        // Auto-invalidate query cache when SyncClient modifies the pool.
+        // Replaces all manual queryProcessor.invalidateCache() calls.
+        this.syncClient.on('models:changed', (modelNames) => {
+            for (const name of modelNames) {
+                this.queryProcessor.invalidateCache(`.*${name}.*`);
+            }
+        });
+        // 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` 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,
+            isReady: computed,
+            isSyncing: computed,
+            isOffline: computed,
+            isReconnecting: computed,
+            isError: computed,
+            hasUnsyncedChanges: computed,
+        });
+    }
+    // ── Protected extension points ────────────────────────────────────────────
+    /**
+     * Register foreign-key indexes for constant-time lookups.
+     *
+     * 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 InstanceCache.
+     *
+     * Base implementation walks `this.enrichmentPlan` — entries populated
+     * from the schema's `{ enrich: true }` relations and from
+     * `config.enrichmentPlan`. Subclasses can still override for bespoke
+     * logic, calling `super.enrichRelations(modelName, data)` first to
+     * apply the declarative plan before layering on custom work.
+     *
+     * Enrichment is best-effort: if the parent isn't yet in the pool
+     * (e.g., a child delta arrives before its parent in a bootstrap
+     * batch), the entry is silently skipped and the data passes through
+     * untouched. The next delta for the same child will re-enrich.
+     */
+    enrichRelations(modelName, data) {
+        for (const entry of this.enrichmentPlan) {
+            if (entry.modelName !== modelName)
+                continue;
+            const fkValue = data[entry.foreignKey];
+            if (typeof fkValue !== 'string')
+                continue;
+            const parent = this.objectPool.get(fkValue);
+            if (parent) {
+                data[entry.relationKey] = parent;
+            }
+        }
+        return data;
+    }
+    /** Check if a model name represents a custom/dynamic entity type. */
+    isCustomEntity(modelName) {
+        return !this.objectPool.registry.getModelByName(modelName);
+    }
+    /** Create a custom entity instance from delta data. Override for domain-specific custom entities. */
+    createCustomEntity(_modelName, _modelId, _data) {
+        return null;
+    }
+    /** Called before save for domain-specific validation/self-healing. */
+    beforeSave(_model) { }
+    /** Connection lifecycle event callback — set by subclass to wire connection state machine. */
+    onConnectionEvent;
+    /**
+     * Internal connection FSM. Owns network probe + backoff + reconnect
+     * orchestration for the default path. Constructed lazily once we
+     * have a user context + a WebSocket (see `wireWebSocketEvents`);
+     * driven by the `onConnectionEvent` hook AND browser online/offline
+     * events it sets up itself.
+     *
+     * Every consumer gets production-grade offline-to-online recovery
+     * out of the box. Subclasses that want their own lifecycle owner
+     * can disable this by overriding `createConnectionManager()` to
+     * return null.
+     */
+    connectionManager = null;
+    /**
+     * 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.
+     */
+    credentialLifecycle = new CredentialLifecycle({
+        setAuthToken: (token) => { this.auth?.setAuthToken(token); },
+        nudgeReconnect: () => { this.nudgeReconnect(); },
+        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
+     * session-error event is received. Separate from `onConnectionEvent`
+     * (which exists for the ConnectionStore FSM) so multiple consumers —
+     * typically `<AbloProvider>` and a connection-lifecycle owner — can
+     * both react without racing on the single-callback slot.
+     */
+    sessionErrorListeners = new Set();
+    terminalSessionLifecycle;
+    /**
+     * Subscribe to session-error events. The returned function removes
+     * the listener. Safe to call multiple times from different consumers
+     * (each gets its own slot in the listener set).
+     */
+    subscribeSessionError(listener) {
+        this.sessionErrorListeners.add(listener);
+        return () => { this.sessionErrorListeners.delete(listener); };
+    }
+    /**
+     * Subscribe to per-mutation failure payloads. Forwarded from the
+     * underlying `SyncClient.mutationQueue` so consumers (toast layer,
+     * route-level reverted boundaries, telemetry) can react without
+     * reaching across the store. Returns an unsubscribe function.
+     *
+     * Why this lives on the base store rather than SyncClient: the React
+     * `<AbloProvider>` binds against this surface, so adding it here
+     * keeps the engine's internal wiring private while still giving the
+     * SDK a single hook to expose. Mirrors `subscribeSessionError` —
+     * same shape, same lifecycle.
+     */
+    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
+     * lookup contract; resolves immediately if nothing is in flight.
+     */
+    waitForConfirmation(modelName, modelId) {
+        return this.syncClient.waitForConfirmation(modelName, modelId);
+    }
+    /**
+     * Observe the LOCAL mutation stream for undo recording (see
+     * {@link import('./storeContract.js').LocalMutation}). Taps the
+     * 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 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.modelName || !tx.modelId)
+                return;
+            handler({
+                type: tx.type,
+                modelName: tx.modelName,
+                modelId: tx.modelId,
+                data: tx.data ?? null,
+                previousData: tx.previousData ?? null,
+            });
+        });
+    }
+    // ── Bootstrap + Retry ────────────────────────────────────────────────────
+    /**
+     * Execute a bootstrap function with timeout protection and automatic retry.
+     * Prevents the common issue where bootstrap hangs on startup.
+     */
+    async executeBootstrapWithTimeout(bootstrapFn, _context, signal) {
+        let lastError = null;
+        // 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');
+                }
+                // `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`).
+                const navigatorOnline = typeof navigator === 'undefined' ? undefined : navigator.onLine;
+                if (navigatorOnline === false) {
+                    this.runtime.observability.breadcrumb(`Bootstrap attempt ${attempt} skipped - offline`, 'sync.bootstrap', 'warning');
+                    throw new AbloConnectionError('Bootstrap skipped - device is offline', {
+                        code: 'bootstrap_offline',
+                    });
+                }
+                try {
+                    this.runtime.logger.info(`[BaseSyncedStore] Bootstrap attempt ${attempt}/${BOOTSTRAP_CONFIG.MAX_RETRY_ATTEMPTS}`);
+                    const result = (await Promise.race([
+                        bootstrapFn(),
+                        this.createBootstrapTimeout(attempt),
+                    ]));
+                    this.runtime.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;
+                    const navigatorOnline = typeof navigator === 'undefined' ? undefined : navigator.onLine;
+                    if (isNetworkError && navigatorOnline === false) {
+                        this.runtime.observability.captureBootstrapFailure(error, { type: 'network-offline' });
+                        throw error;
+                    }
+                    this.runtime.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) {
+                        this.runtime.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();
+        }
+    }
+    /**
+     * 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 = this.database.helper.budgetMs;
+        return new Promise((_, reject) => {
+            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 {
+            this.objectPool.clear({ preserveObserved: true });
+            this.queryProcessor.clearCache();
+            runInAction(() => { this.dataReady = false; });
+            this.modelTypesHydrated.clear();
+            this.modelTypeHydrationInFlight.clear();
+            // The pool is being wiped + re-bootstrapped, so the scoped-hydrate ledger
+            // is stale — clear it so re-entered groups backfill again.
+            this.hydratedGroups.clear();
+            this.hydratingGroups.clear();
+            this.runtime.logger.info('[BaseSyncedStore] Bootstrap state reset complete');
+        }
+        catch {
+            this.runtime.observability.breadcrumb('Error resetting bootstrap state', 'sync.bootstrap', 'warning');
+        }
+    }
+    // ── Reconnection ─────────────────────────────────────────────────────────
+    /** Perform reconnect: bootstrap + WS reconnect. Returns outcome for state machine. */
+    async performReconnect() {
+        const thisStore = this;
+        return runReconnect({
+            get userContext() { return thisStore.userContext; },
+            database: this.database,
+            syncClient: this.syncClient,
+            objectPool: this.objectPool,
+            syncWebSocket: this.syncWebSocket,
+            runtime: this.runtime,
+            get dataReady() { return thisStore.dataReady; },
+            set dataReady(value) { thisStore.dataReady = value; },
+            checkSyncGroupShrinkage: () => this.checkSyncGroupShrinkage(),
+            resolveSyncGroups: (context) => this.resolveSyncGroups(context),
+            applyBootstrapToPool: (result) => this.applyBootstrapToPool(result),
+            updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
+        });
+    }
+    /**
+     * 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 CredentialLifecycle.setRefresher}.
+     */
+    setCredentialRefresher(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. Single-flight; no refresher wired ⇒ `'refreshed'` (a no-op
+     * re-probe). Full contract on {@link CredentialLifecycle.refresh}.
+     */
+    async performCredentialRefresh() {
+        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
+     * and safe in any state (ignored while `connected`). Call after pushing a
+     * freshly-minted token via `setAuthToken`, or on an OS-wake signal, so a
+     * connection parked in `offline` / `backoff` / `auth_blocked` picks the new
+     * credential up immediately instead of waiting for the 30s watchdog.
+     */
+    nudgeReconnect() {
+        this.connectionManager?.send({ type: 'CREDENTIAL_REFRESHED' });
+    }
+    /**
+     * 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, opts) {
+        this.credentialLifecycle.start(getToken, opts);
+    }
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    stopCredentialLifecycle() {
+        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 {
+            runtime: this.runtime,
+            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(); },
+        };
+    }
+    /**
+     * Handle an actionType 'G' delta — incremental `{ group, userId }` or
+     * legacy `{ addedGroups, removedGroups }` payloads. Full pathway doc on
+     * {@link groupChange.handleSyncGroupChange}.
+     */
+    async handleSyncGroupChange(delta) {
+        return groupChange.handleSyncGroupChange(this.groupChangeContext(), delta);
+    }
+    /**
+     * Handle an incremental GroupAdded delta — metadata only, no re-bootstrap
+     * (covering deltas bring the entities). See {@link groupChange.handleGroupAdded}.
+     */
+    async handleGroupAdded(payload, syncId) {
+        return groupChange.handleGroupAdded(this.groupChangeContext(), payload, syncId);
+    }
+    /**
+     * 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) {
+        return groupChange.handleGroupRemoved(this.groupChangeContext(), delta);
+    }
+    /** Compute new sync groups after applying additions and removals */
+    computeUpdatedSyncGroups(payload) {
+        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() {
+        groupChange.forceFullRebootstrap(this.groupChangeContext());
+    }
+    /**
+     * Single source of truth for the sync-group list this session is
+     * subscribed to. Server-issued (`context.syncGroups`) is authoritative.
+     * When absent, the SDK subscribes to no explicit groups. Both
+     * `checkSyncGroupShrinkage` and `setupWebSocketSync` resolve through
+     * here so the WS subscription and the security-critical shrinkage
+     * check can never disagree.
+     */
+    resolveSyncGroups(context) {
+        return groupChange.resolveSyncGroups(context);
+    }
+    /** Check if sync groups shrank since last session — force full bootstrap if so */
+    async checkSyncGroupShrinkage() {
+        return groupChange.checkSyncGroupShrinkage(this.groupChangeContext());
+    }
+    // ── 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 {
+            runtime: this.runtime,
+            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) {
+        return bootstrapApply.applyBootstrapToPool(this.poolContext(), bootstrapResult, protectedIds);
+    }
+    // ── Initialize + Lifecycle ───────────────────────────────────────────────
+    /**
+     * Initialize the sync engine with user context.
+     * Offline-first: hydrate from IDB → show UI → bootstrap from server in background.
+     */
+    *initialize(context, signal) {
+        const thisStore = this;
+        return yield* runInitialize({
+            get initialized() { return thisStore.initialized; },
+            set initialized(value) { thisStore.initialized = value; },
+            get userContext() {
+                const value = thisStore.userContext;
+                if (!value)
+                    throw new Error('User context is unavailable during initialization');
+                return value;
+            },
+            set userContext(value) { thisStore.userContext = value; },
+            get dataReady() { return thisStore.dataReady; },
+            set dataReady(value) { thisStore.dataReady = value; },
+            runtime: this.runtime,
+            database: this.database,
+            syncClient: this.syncClient,
+            objectPool: this.objectPool,
+            syncWebSocket: this.syncWebSocket,
+            updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
+            setupWebSocketSync: (nextContext, lastSyncId) => { this.setupWebSocketSync(nextContext, lastSyncId); },
+            waitForWebSocketConnected: (timeoutMs) => this.waitForWebSocketConnected(timeoutMs),
+            performBackgroundBootstrap: (requirements, nextContext, nextSignal) => this.performBackgroundBootstrap(requirements, nextContext, nextSignal),
+            executeBootstrapWithTimeout: (fn, nextContext, nextSignal) => this.executeBootstrapWithTimeout(fn, nextContext, nextSignal),
+            resolveSyncGroups: (nextContext) => this.resolveSyncGroups(nextContext),
+        }, context, signal);
+    }
+    /** Background bootstrap — non-blocking, user sees cached data while this runs */
+    async performBackgroundBootstrap(requirements, context, signal) {
+        await this.withDeltaQueuing(async () => {
+            try {
+                const preBootstrapIds = new Set(this.objectPool.getAllIds());
+                const bootstrapResult = await this.database.bootstrapFromServer(requirements, this.resolveSyncGroups(context));
+                const deltaProtectedIds = this.collectDeltaProtectedIds(preBootstrapIds);
+                this.applyBootstrapToPool(bootstrapResult, deltaProtectedIds);
+                this.updateSyncStatus({ state: 'idle', progress: 100 });
+            }
+            catch (error) {
+                this.runtime.logger.debug('[sync-engine] Background bootstrap failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                    cause: error,
+                });
+                this.runtime.observability.captureBootstrapFailure(error, { type: 'background' });
+                if (AbloSessionError.isSessionError(error)) {
+                    this.syncWebSocket.setSessionErrorDetected();
+                    this.syncWebSocket.disconnect();
+                    this.updateSyncStatus({ state: 'error', error: error });
+                }
+                else if (!this.syncWebSocket.isConnected()) {
+                    this.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
+                }
+            }
+        });
+    }
+    /** Run bootstrap with delta queuing to prevent race conditions */
+    async withDeltaQueuing(fn) {
+        this.activeBootstrapCount++;
+        if (this.bootstrapDeltaQueue === null)
+            this.bootstrapDeltaQueue = [];
+        try {
+            return await fn();
+        }
+        finally {
+            this.activeBootstrapCount--;
+            if (this.activeBootstrapCount === 0)
+                this.replayQueuedDeltas();
+        }
+    }
+    /** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
+    collectDeltaProtectedIds(preBootstrapIds) {
+        return bootstrapApply.collectDeltaProtectedIds(this.poolContext(), preBootstrapIds);
+    }
+    /** Replay deltas queued during bootstrap (atomically, via `applyDeltaFrame`). */
+    replayQueuedDeltas() {
+        bootstrapApply.replayQueuedDeltas(this.poolContext());
+    }
+    createConnectionManager(kind) {
+        return runCreateConnectionManager({
+            syncServerUrl: this._syncServerUrl,
+            auth: this.auth,
+            syncWebSocket: this.syncWebSocket,
+        }, kind);
+    }
+    /**
+     * 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) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+        this.pendingDeltas = [];
+        for (const dispose of this.disposers)
+            dispose();
+        this.disposers = [];
+        if (this.connectionManager) {
+            this.connectionManager.dispose();
+            this.connectionManager = null;
+        }
+        try {
+            const last = this.syncWebSocket.getLastSyncId();
+            if (last > 0)
+                await this.database.updateWorkspaceMetadata({ lastSyncId: last });
+        }
+        catch { }
+        this.syncWebSocket.disconnect();
+        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' });
+    }
+    /** Stop access and await deletion of this identity's local state. */
+    async purge() {
+        // Clear the bearer first so no request started during teardown can carry
+        // the terminal credential.
+        this.auth?.setAuthToken(null);
+        await this.disconnect();
+        this.objectPool.clear();
+        this.queryProcessor.clearCache();
+        await this.database.purgePersistence();
+    }
+    // ── WebSocket Setup ───────────────────────────────────────────────────────
+    /**
+     * Create WebSocket connection and wire all event handlers.
+     * Handles: deltas, batches, presence, bootstrap_required, errors, reconnection.
+     */
+    /**
+     * Block until the WebSocket reports a `connected` event, or until
+     * `timeoutMs` elapses (returns false on timeout, true on connect).
+     * Used by `initialize()` for `bootstrapMode: 'none'` consumers to
+     * honor `ready()`'s "WS is connected when this resolves" contract
+     * — `setupWebSocketSync` is fire-and-forget on the upgrade, and
+     * without an explicit wait the next mutation can race the open.
+     *
+     * Resolves immediately if the WS is already connected (e.g., warm
+     * reconnect after redeploy). Resolves false on timeout rather than
+     * throwing so initialize() can complete and let the caller's first
+     * mutation attempt surface a clearer error.
+     */
+    async waitForWebSocketConnected(timeoutMs) {
+        return runWaitForWebSocketConnected({
+            syncWebSocket: this.syncWebSocket,
+            runtime: this.runtime,
+        }, 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) {
+            this.runtime.observability.breadcrumb('Cannot setup WebSocket sync without user context', 'sync.websocket', 'warning');
+            return;
+        }
+        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() {
+        const thisStore = this;
+        wireSocketEvents({
+            syncWebSocket: this.syncWebSocket,
+            syncClient: this.syncClient,
+            database: this.database,
+            objectPool: this.objectPool,
+            areaOfInterest: this.areaOfInterest,
+            runtime: this.runtime,
+            get dataReady() { return thisStore.dataReady; },
+            connectionManager: this.connectionManager,
+            disposers: this.disposers,
+            onConnectionEvent: this.onConnectionEvent,
+            updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
+            processDeltaWithBatching: (delta) => { this.processDeltaWithBatching(delta); },
+            applyDeltaFrame: (deltas) => { this.applyDeltaFrame(deltas); },
+            handleBootstrapRequired: (hint) => { this.handleBootstrapRequired(hint); },
+            handleBootstrapData: (data) => { this.handleBootstrapData(data); },
+            handlePresenceUpdate: (data) => { this.handlePresenceUpdate(data); },
+            performCredentialRefresh: () => this.performCredentialRefresh(),
+            handleTerminalSessionError: (error) => { this.terminalSessionLifecycle.start(error); },
+            nudgeReconnect: () => { this.nudgeReconnect(); },
+        });
+    }
+    /*
+     * Kept as a distinct method so subclasses retain the original override
+     * point; transport wiring itself lives in sync/socketEventWiring.ts.
+     */
+    /**
+     * 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) {
+        const thisStore = this;
+        runStartConnectionManager({
+            get connectionManager() { return thisStore.connectionManager; },
+            set connectionManager(value) { thisStore.connectionManager = value; },
+            get onConnectionEvent() { return thisStore.onConnectionEvent; },
+            set onConnectionEvent(value) { thisStore.onConnectionEvent = value; },
+            syncWebSocket: this.syncWebSocket,
+            get syncStatus() { return thisStore.syncStatus; },
+            createConnectionManager: (nextKind) => this.createConnectionManager(nextKind),
+            performReconnect: () => this.performReconnect(),
+            performCredentialRefresh: () => this.performCredentialRefresh(),
+            handleTerminalSessionError: (error) => { this.terminalSessionLifecycle.start(error); },
+            updateSyncStatus: (updates) => { this.updateSyncStatus(updates); },
+            runtime: this.runtime,
+        }, kind);
+    }
+    // ── 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 = {
+            runtime: this.runtime,
+            stagePlugins: this.stagePlugins,
+            // 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, transactionId, correlationId) => {
+                this.syncClient.onDeltaReceived(syncId, transactionId, correlationId);
+            },
+            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.applyChangesToPool(results); },
+            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);
+            },
+        };
+        return this._deltaPipelineContext;
+    }
+    /**
+     * Lands persisted changes in the in-memory pool, with this store's
+     * relation enrichment bound. The one apply path: the pipeline's bridge
+     * (no plugins installed) and the `humans()` apply handler both call it.
+     */
+    applyChangesToPool(changes) {
+        this.syncClient.applyDeltaBatchToPool(changes, (name, data) => this.enrichRelations(name, data));
+    }
+    /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
+    getStateFields(_modelName) {
+        return ['status', 'state', 'isActive'];
+    }
+    /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
+    deduplicateDeltas(deltas) {
+        return deltaPipeline.deduplicateDeltas(this.deltaPipelineContext, deltas);
+    }
+    /** Process incoming delta with smart batching */
+    processDeltaWithBatching(delta) {
+        if (!this.enqueueDelta(delta))
+            return;
+        this.scheduleDeltaFlush();
+    }
+    /**
+     * Apply a complete, server-delivered delta frame atomically.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * 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) {
+        deltaPipeline.applyDeltaFrame(this.deltaPipelineContext, deltas);
+    }
+    /**
+     * Per-delta bookkeeping + enqueue. Returns `true` when the delta was
+     * pushed onto `pendingDeltas` (a regular batchable I/U/C/D delta that a
+     * subsequent flush must drain), `false` when it was skipped (dedup),
+     * deferred (bootstrap queue), or handled immediately out-of-band (G/S
+     * sync-group mutations). Does NOT schedule a flush — callers decide
+     * whether to debounce (live) or flush atomically (catch-up frame).
+     */
+    enqueueDelta(delta, options = {}) {
+        return deltaPipeline.enqueueDelta(this.deltaPipelineContext, delta, options);
+    }
+    /** Debounce a flush for live single-delta traffic. */
+    scheduleDeltaFlush() {
+        deltaPipeline.scheduleDeltaFlush(this.deltaPipelineContext);
+    }
+    /**
+     * Cancel pending transactions for child entities when a parent is deleted.
+     *
+     * Uses `pool.getByForeignKey` (O(1) via the FK index registered at
+     * 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 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.
+     */
+    cascadeCancelTransactionsForDeletedParent(parentModelName, parentId) {
+        const reg = this.objectPool.registry;
+        const childModels = reg.getChildModels(parentModelName);
+        if (childModels.length === 0)
+            return;
+        let totalCancelled = 0;
+        for (const { childModel, foreignKey } of childModels) {
+            const cancelled = this.syncClient.cancelTransactionsByForeignKey(childModel, foreignKey, parentId);
+            totalCancelled += cancelled;
+            // O(1) FK-index lookup — skips the prior `getByType().filter(toJSON)` scan.
+            const children = this.objectPool.getByForeignKey(childModel, foreignKey, parentId);
+            for (const child of children) {
+                this.cascadeCancelTransactionsForDeletedParent(childModel, child.id);
+            }
+        }
+        if (totalCancelled > 0) {
+            this.runtime.logger.info('[BaseSyncedStore] Cascade cancelled orphaned transactions', {
+                parentModel: parentModelName,
+                parentId: parentId.slice(0, 12),
+                totalCancelled,
+            });
+        }
+    }
+    /** Flush pending deltas with deduplication. Pool writes are delegated to {@link SyncClient}. */
+    async flushPendingDeltas() {
+        return deltaPipeline.flushPendingDeltas(this.deltaPipelineContext);
+    }
+    // ── Core mutations (thin delegation to SyncClient) ────────────────────────
+    //
+    // 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;
+    }
+    /** Validate model against schema before save */
+    validateModel(model) {
+        const modelName = model.getModelName();
+        const properties = this.modelRegistry.getPropertiesForModel(modelName);
+        const modelData = model.toJSON();
+        for (const [propName, metadata] of properties) {
+            if (metadata.type === PropertyType.referenceModel)
+                continue;
+            if (metadata.type === PropertyType.ephemeralProperty)
+                continue;
+            if (!metadata.optional && (modelData[propName] === null || modelData[propName] === undefined)) {
+                throw new AbloValidationError(`Required field ${propName} is missing on ${modelName}`, { code: 'model_required_field_missing' });
+            }
+        }
+    }
+    /**
+     * Save a model (create or update).
+     *
+     * Accepts any entity shape with `{ id: string }` so consumers can pass the
+     * 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
+     * cast below preserves that invariant inside the SDK.
+     */
+    async save(entity, options) {
+        const model = rowAsModel(entity);
+        this.beforeSave(model);
+        if (!options?.skipValidation)
+            this.validateModel(model);
+        if (!model.createdAt)
+            model.createdAt = new Date();
+        // SyncClient.add/update handles: optimistic pool add, transaction queue, IDB write
+        const isCreate = !this.objectPool.get(model.id);
+        if (isCreate) {
+            model.updatedAt = new Date();
+            this.syncClient.add(model);
+        }
+        else {
+            this.syncClient.update(model);
+        }
+    }
+    /** Save with an atomic server mutation (e.g., createSectionWithBlocks) */
+    async saveWithAtomicMutation(model, mutation) {
+        this.objectPool.add(model, ModelScope.live);
+        await mutation(this.syncClient.gql);
+    }
+    /** Delete a model. Accepts schema-inferred entity shapes (see `save`). */
+    async delete(entity) {
+        const model = rowAsModel(entity);
+        this.pendingDeletes.add(model.id);
+        // SyncClient.delete handles: pool remove, transaction queue
+        this.syncClient.delete(model);
+    }
+    /** Archive a model. Accepts schema-inferred entity shapes (see `save`). */
+    async archive(entity) {
+        const model = rowAsModel(entity);
+        model.archivedAt = new Date();
+        this.syncClient.archive(model);
+    }
+    /** Unarchive a model. Accepts schema-inferred entity shapes (see `save`). */
+    async unarchive(entity) {
+        const model = rowAsModel(entity);
+        model.archivedAt = null;
+        this.syncClient.update(model);
+    }
+    // ── Query API ────────────────────────────────────────────────────────────
+    // `ablo.<model>.local.get` / `.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. */
+    retrieve(_modelClass, id) {
+        return this.objectPool.get(id);
+    }
+    /** Find any entity by ID regardless of type */
+    findAnyById(id) {
+        return this.objectPool.get(id);
+    }
+    /**
+     * Lookup a model by ID alone. Matches the `SyncStoreRef.getById` contract
+     * that schema-defined computeds use when they need to resolve a related
+     * entity without holding onto its constructor.
+     */
+    getById(id) {
+        return this.objectPool.get(id);
+    }
+    /**
+     * Create a model instance locally, typed via the schema.
+     *
+     * ```ts
+     * const ledger = store.create('ledgers', { name, reportId });
+     * // ledger: Ledger | null — no cast needed
+     * ```
+     *
+     * The `typename` arg is the schema key (camelCase plural, e.g.
+     * `'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.
+     */
+    create(typename, data) {
+        if (!this.schema) {
+            throw new AbloValidationError('store.create requires a schema to be passed to the BaseSyncedStore constructor.', { code: 'store_create_schema_missing' });
+        }
+        const modelDef = this.schema.models[typename];
+        const wireTypename = modelDef?.typename ?? typename;
+        // Same boundary-cast idiom used by `createReaderActions.findById` — the
+        // runtime instance IS the schema-typed shape (the dynamic class was
+        // built from the same Zod shape), TypeScript just can't unify the SDK's
+        // static `Model` class with the schema's object-literal type.
+        return this.objectPool.create(wireTypename, data);
+    }
+    /**
+     * 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) {
+        return runQueryByClass(this.objectPool, this.pendingDeletes, modelClass, options);
+    }
+    /**
+     * 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 `Model<S, K>`.
+     */
+    allModelsOfType(modelClass, scope) {
+        return this.objectPool.getByType(modelClass, scope ?? ModelScope.live);
+    }
+    /** Error handler for fire-and-forget flushPendingDeltas calls */
+    handleFlushError = (error) => {
+        this.runtime.observability.captureMutationFailure({
+            context: 'flush-pending-deltas',
+            modelName: 'batch',
+            modelId: 'batch',
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+        this.runtime.logger.debug('[BaseSyncedStore] Delta flush error', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    };
+    /** Process a single delta (used for immediate DELETE processing). Override for domain-specific handling. */
+    async processDelta(delta) {
+        const dbResult = await this.database.processDelta({
+            syncId: delta.id,
+            actionType: delta.actionType,
+            modelName: delta.modelName,
+            modelId: delta.modelId,
+            data: typeof delta.data === 'string' ? JSON.parse(delta.data) : delta.data,
+        });
+        // Track pending deletes for query filtering
+        if (dbResult.action === 'remove') {
+            this.pendingDeletes.add(dbResult.modelId);
+        }
+        // Delegate pool writes to SyncClient (auto-invalidates cache via 'models:changed' event)
+        this.syncClient.applyDeltaBatchToPool([dbResult], (name, data) => this.enrichRelations(name, data));
+        // This path runs after the delta was written to IDB — advance both
+        // cursors through the shared position.
+        this.syncClient.position.advancePersisted(delta.id);
+    }
+    /** Handle bootstrap_required event */
+    handleBootstrapRequired(_hint) {
+        // Subclass implements — triggers background bootstrap
+    }
+    /** Handle bootstrap_data event. Override in subclass. */
+    handleBootstrapData(_data) {
+        this.updateSyncStatus({ state: 'syncing' });
+    }
+    /** Handle presence_update event. Override in subclass. */
+    handlePresenceUpdate(_data) { }
+    // ── Pending changes tracking ─────────────────────────────────────────────
+    incrementPendingChanges() {
+        runInAction(() => { this.syncStatus.pendingChanges++; });
+    }
+    decrementPendingChanges() {
+        runInAction(() => {
+            if (this.syncStatus.pendingChanges > 0)
+                this.syncStatus.pendingChanges--;
+        });
+    }
+    // ── Status helpers ───────────────────────────────────────────────────────
+    updateSyncStatus(updates) {
+        runInAction(() => {
+            Object.assign(this.syncStatus, updates);
+        });
+    }
+    // ── Accessors ─────────────────────────────────────────────────────────────
+    get pool() {
+        return this.objectPool;
+    }
+    get lastSyncId() {
+        return this.lastAckedId;
+    }
+    // ── Status convenience getters ──────────────────────────────────────────
+    // 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)
+            || (this.dataReady && this.syncStatus.state === 'syncing');
+    }
+    get isSyncing() {
+        return this.syncStatus.state === 'syncing';
+    }
+    get isOffline() {
+        return this.syncStatus.state === 'offline';
+    }
+    get isReconnecting() {
+        return this.syncStatus.state === 'reconnecting';
+    }
+    get isError() {
+        return this.syncStatus.state === 'error';
+    }
+    get hasUnsyncedChanges() {
+        return this.syncStatus.pendingChanges > 0;
+    }
+    /** The SyncWebSocket handle — for collaboration events. */
+    get ws() {
+        return this.syncWebSocket;
+    }
+    /** The Database instance — for demand loaders and direct IDB operations. */
+    get db() {
+        return this.database;
+    }
+    /** The SyncClient instance — for assignment operations and other direct sync actions. */
+    get sc() {
+        return this.syncClient;
+    }
+    /** The current organization ID — from the last initialize() call. */
+    get orgId() {
+        return this.userContext?.organizationId;
+    }
+    /** Count models matching a predicate. */
+    count(modelClass, predicate) {
+        return countModels(this.objectPool, modelClass, this.pendingDeletes, predicate);
+    }
+    /** Get entities by foreign key (used by Model subclasses via Model.store) */
+    getByForeignKey(modelName, foreignKey, id) {
+        return this.objectPool.getByForeignKey(modelName, foreignKey, id);
+    }
+}