@abloatai/ablo 0.25.0 → 0.27.0

package/dist/testing/helpers/{sync-engine-harness.js → syncEngineHarness.js}

@@ -1,17 +1,21 @@
 /**
- * Full sync engine test harness.
- *
- * Creates a complete stack (ModelRegistry, ObjectPool, TransactionQueue, etc.)
- * with real implementations backed by mocked I/O for integration tests.
+ * An integration-test harness that assembles a full sync engine stack —
+ * the model registry, object pool, transaction queue, and related parts —
+ * from the real implementations, but with mocked input and output. It lets
+ * tests exercise the engine end to end without a network or a live server.
  */
 import { ModelRegistry, setActiveRegistry } from '../../ModelRegistry.js';
-import { ObjectPool } from '../../ObjectPool.js';
+import { InstanceCache } from '../../InstanceCache.js';
+import { MockMutationExecutor } from '../mocks/MockMutationExecutor.js';
+import { MockNetworkMonitor } from '../mocks/MockNetworkMonitor.js';
 import { MockWebSocket } from '../mocks/MockWebSocket.js';
 import { createTestContext } from '../mocks/MockSyncContext.js';
 import { registerTestModels, createTestConfig, resetFixtureCounter, } from '../fixtures/models.js';
 import { resetDeltaCounter } from '../fixtures/deltas.js';
 /**
- * Create a full test harness with real sync engine components + mocked I/O.
+ * Builds a full test harness: real sync engine components wired to mocked
+ * input and output. Reset the counters and tear everything down through the
+ * returned {@link TestHarness.cleanup}.
  *
  * Usage:
  * ```ts
@@ -28,7 +32,7 @@ export function createTestHarness(options = {}) {
     const registry = new ModelRegistry();
     setActiveRegistry(registry);
     registerTestModels(registry);
-    // Create DI context with test config
+    // Create the dependency-injection context with the test config
     const testConfig = createTestConfig();
     const context = createTestContext({
         config: testConfig,
@@ -37,14 +41,14 @@ export function createTestHarness(options = {}) {
             initialSyncId: options.initialSyncId ?? 1,
         },
     });
-    // Create real ObjectPool with FK indexes
-    const pool = new ObjectPool({
+    // Create the real object pool with foreign-key indexes
+    const pool = new InstanceCache({
         maxSize: options.poolConfig?.maxSize ?? 10000,
         maxAge: options.poolConfig?.maxAge ?? 5 * 60 * 1000,
         gcInterval: options.poolConfig?.gcInterval ?? 0, // Disable auto-GC in tests
         useWeakRefs: options.poolConfig?.useWeakRefs ?? false, // Disable WeakRefs for predictable tests
     }, registry);
-    // Register FK indexes for test models
+    // Register foreign-key indexes for the test models
     pool.registerForeignKey('Task', 'projectId');
     pool.registerForeignKey('Comment', 'taskId');
     pool.registerForeignKey('Slide', 'deckId');
@@ -58,7 +62,6 @@ export function createTestHarness(options = {}) {
         context,
         mutationExecutor: context.mocks.mutationExecutor,
         networkMonitor: context.mocks.networkMonitor,
-        mutationDispatcher: context.mocks.mutationDispatcher,
         cleanup: () => {
             pool.clear();
             webSocket.reset();

package/dist/testing/helpers/wait.d.ts

@@ -1,25 +1,30 @@
 /**
- * Async test helpers for timing-sensitive sync engine tests.
+ * Asynchronous helpers for tests whose assertions depend on timing — for
+ * flushing pending work, polling for a condition, or waiting a fixed delay.
  */
 /**
- * Flush all pending microtasks (Promise.resolve, queueMicrotask).
- * Critical for testing TransactionQueue's microtask batching.
+ * Flushes all pending microtasks, such as resolved promises and
+ * `queueMicrotask` callbacks. Useful for testing work the transaction queue
+ * batches on the microtask queue.
  */
 export declare function flushMicrotasks(): Promise<void>;
 /**
- * Wait for a condition to become true, polling at intervals.
- * Times out after maxWait ms.
+ * Polls `condition` until it returns true, checking every `interval`
+ * milliseconds. Rejects with an {@link AbloConnectionError} if `maxWait`
+ * milliseconds pass first.
  */
 export declare function waitFor(condition: () => boolean, options?: {
     maxWait?: number;
     interval?: number;
 }): Promise<void>;
 /**
- * Wait for N milliseconds. Use sparingly — prefer flushMicrotasks() or waitFor().
+ * Waits for the given number of milliseconds. Use sparingly; prefer
+ * {@link flushMicrotasks} or {@link waitFor}, which don't tie tests to
+ * wall-clock time.
  */
 export declare function delay(ms: number): Promise<void>;
 /**
- * Run a callback after flushing microtasks.
- * Useful for asserting state after TransactionQueue batch processing.
+ * Flushes pending microtasks, then runs `fn` and returns its result. Handy
+ * for asserting state after the transaction queue processes a batch.
  */
 export declare function afterMicrotasks<T>(fn: () => T): Promise<T>;

package/dist/testing/helpers/wait.js

@@ -1,10 +1,12 @@
 /**
- * Async test helpers for timing-sensitive sync engine tests.
+ * Asynchronous helpers for tests whose assertions depend on timing — for
+ * flushing pending work, polling for a condition, or waiting a fixed delay.
  */
 import { AbloConnectionError } from '../../errors.js';
 /**
- * Flush all pending microtasks (Promise.resolve, queueMicrotask).
- * Critical for testing TransactionQueue's microtask batching.
+ * Flushes all pending microtasks, such as resolved promises and
+ * `queueMicrotask` callbacks. Useful for testing work the transaction queue
+ * batches on the microtask queue.
  */
 export function flushMicrotasks() {
     return new Promise((resolve) => {
@@ -13,8 +15,9 @@ export function flushMicrotasks() {
     });
 }
 /**
- * Wait for a condition to become true, polling at intervals.
- * Times out after maxWait ms.
+ * Polls `condition` until it returns true, checking every `interval`
+ * milliseconds. Rejects with an {@link AbloConnectionError} if `maxWait`
+ * milliseconds pass first.
  */
 export async function waitFor(condition, options = {}) {
     const { maxWait = 5000, interval = 10 } = options;
@@ -29,14 +32,16 @@ export async function waitFor(condition, options = {}) {
     }
 }
 /**
- * Wait for N milliseconds. Use sparingly — prefer flushMicrotasks() or waitFor().
+ * Waits for the given number of milliseconds. Use sparingly; prefer
+ * {@link flushMicrotasks} or {@link waitFor}, which don't tie tests to
+ * wall-clock time.
  */
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Run a callback after flushing microtasks.
- * Useful for asserting state after TransactionQueue batch processing.
+ * Flushes pending microtasks, then runs `fn` and returns its result. Handy
+ * for asserting state after the transaction queue processes a batch.
  */
 export async function afterMicrotasks(fn) {
     await flushMicrotasks();

package/dist/testing/index.d.ts

@@ -9,13 +9,13 @@ export type { CapturedMutation, MockMutationExecutorOptions } from './mocks/Mock
 export { MockNetworkMonitor } from './mocks/MockNetworkMonitor.js';
 export { MockWebSocket } from './mocks/MockWebSocket.js';
 export type { MockDelta, MockBootstrapHint } from './mocks/MockWebSocket.js';
-export { createTestContext, MockMutationDispatcher, } from './mocks/MockSyncContext.js';
+export { createTestContext, } from './mocks/MockSyncContext.js';
 export type { TestContextOptions, TestContextResult } from './mocks/MockSyncContext.js';
 export { TestProject, TestTask, TestComment, TestSlideDeck, TestSlide, TestSlideLayer, TEST_MODEL_PRIORITIES, registerTestModels, createTestConfig, resetFixtureCounter, createProjectFixture, createTaskFixture, createCommentFixture, createSlideDeckFixture, createSlideFixture, createSlideLayerFixture, } from './fixtures/models.js';
 export { createDelta, createInsertDelta, createUpdateDelta, createDeleteDelta, createArchiveDelta, createUnarchiveDelta, createCoveringDelta, createGroupAddedDelta, createLegacyGroupChangeDelta, createGroupRemovedDelta, createDeltaBatch, createConfirmationDelta, resetDeltaCounter, } from './fixtures/deltas.js';
 export { createFullBootstrapResponse, createPartialBootstrapResponse, createTestBootstrapResponse, } from './fixtures/bootstrap.js';
 export type { BootstrapModelData, BootstrapResponse } from './fixtures/bootstrap.js';
-export { createTestHarness, } from './helpers/sync-engine-harness.js';
-export type { TestHarness, TestHarnessOptions } from './helpers/sync-engine-harness.js';
+export { createTestHarness, } from './helpers/syncEngineHarness.js';
+export type { TestHarness, TestHarnessOptions } from './helpers/syncEngineHarness.js';
 export { flushMicrotasks, waitFor, delay, afterMicrotasks, } from './helpers/wait.js';
-export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, type TestWrapperOptions, } from './helpers/react-wrapper.js';
+export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, type TestWrapperOptions, } from './helpers/reactWrapper.js';

package/dist/testing/index.js

@@ -10,7 +10,7 @@
 export { MockMutationExecutor } from './mocks/MockMutationExecutor.js';
 export { MockNetworkMonitor } from './mocks/MockNetworkMonitor.js';
 export { MockWebSocket } from './mocks/MockWebSocket.js';
-export { createTestContext, MockMutationDispatcher, } from './mocks/MockSyncContext.js';
+export { createTestContext, } from './mocks/MockSyncContext.js';
 // ─────────────────────────────────────────────
 // Fixtures: Models
 // ─────────────────────────────────────────────
@@ -26,7 +26,7 @@ export { createFullBootstrapResponse, createPartialBootstrapResponse, createTest
 // ─────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────
-export { createTestHarness, } from './helpers/sync-engine-harness.js';
+export { createTestHarness, } from './helpers/syncEngineHarness.js';
 export { flushMicrotasks, waitFor, delay, afterMicrotasks, } from './helpers/wait.js';
 // React testing helpers
-export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, } from './helpers/react-wrapper.js';
+export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, } from './helpers/reactWrapper.js';

package/dist/testing/mocks/MockMutationExecutor.d.ts

@@ -1,8 +1,9 @@
 /**
- * MockMutationExecutor — Test double for the MutationExecutor interface.
- *
- * Captures all mutation calls, allows controlled responses (success/failure/latency),
- * and returns configurable lastSyncId for delta confirmation testing.
+ * A test double for {@link MutationExecutor} that records every call instead
+ * of writing to a database. Use it to assert what a component tried to commit
+ * and to script the response — success, failure, or added latency — without a
+ * live backend. Each successful commit hands back an incrementing `lastSyncId`,
+ * so tests can drive the delta-confirmation flow that depends on those ids.
  */
 import type { MutationExecutor, MutationOperation, MutationOptions, CommitResult } from '../../interfaces/index.js';
 export interface CapturedMutation {
@@ -16,15 +17,15 @@ export interface CapturedMutation {
     timestamp: number;
 }
 export interface MockMutationExecutorOptions {
-    /** Starting lastSyncId — increments by 1 per commit call */
+    /** The first `lastSyncId` to return. It increments by one after each commit. */
     initialSyncId?: number;
-    /** Whether mutations should succeed by default */
+    /** Whether mutations succeed by default. Set this false to make every call reject. */
     shouldSucceed?: boolean;
-    /** Simulated network latency in ms */
+    /** A delay applied before each call resolves, in milliseconds, to simulate a slow network. */
     latencyMs?: number;
 }
 export declare class MockMutationExecutor implements MutationExecutor {
-    /** All captured mutation calls in order */
+    /** Every captured call, in the order it was made. Assertions read from this list. */
     readonly calls: CapturedMutation[];
     /** Current sync ID — incremented on each successful commit */
     private _syncId;
@@ -35,23 +36,23 @@ export declare class MockMutationExecutor implements MutationExecutor {
     /** Per-method response overrides */
     private _responseOverrides;
     constructor(options?: MockMutationExecutorOptions);
-    /** Get current sync ID without incrementing */
+    /** Returns the current sync id without advancing it. */
     get currentSyncId(): number;
-    /** Set the next sync ID to return */
+    /** Sets the next sync id the executor will return. */
     setSyncId(id: number): void;
-    /** Make all mutations fail with given error */
+    /** Makes every mutation reject. Pass an error to control what is thrown. */
     failAll(error?: Error): void;
-    /** Make all mutations succeed again */
+    /** Restores the default where mutations succeed, clearing any failure overrides. */
     succeedAll(): void;
-    /** Make a specific method fail */
+    /** Makes a single named method reject. Pass an error to control what is thrown. */
     failMethod(method: string, error?: Error): void;
-    /** Clear failure override for a method */
+    /** Removes the failure override for one method. */
     clearFailure(method: string): void;
-    /** Get calls filtered by method */
+    /** Returns the captured calls for one method, in order. */
     getCallsByMethod(method: string): CapturedMutation[];
-    /** Get the last call made */
+    /** The most recent captured call, or undefined if none have been made. */
     get lastCall(): CapturedMutation | undefined;
-    /** Reset all state */
+    /** Clears captured calls and restores the initial options. */
     reset(options?: MockMutationExecutorOptions): void;
     commit(operations: MutationOperation[], options?: MutationOptions): Promise<CommitResult>;
     executeCreate(modelName: string, id: string, input: Record<string, unknown>, clientMutationId?: string): Promise<void>;

package/dist/testing/mocks/MockMutationExecutor.js

@@ -1,12 +1,13 @@
 /**
- * MockMutationExecutor — Test double for the MutationExecutor interface.
- *
- * Captures all mutation calls, allows controlled responses (success/failure/latency),
- * and returns configurable lastSyncId for delta confirmation testing.
+ * A test double for {@link MutationExecutor} that records every call instead
+ * of writing to a database. Use it to assert what a component tried to commit
+ * and to script the response — success, failure, or added latency — without a
+ * live backend. Each successful commit hands back an incrementing `lastSyncId`,
+ * so tests can drive the delta-confirmation flow that depends on those ids.
  */
 import { AbloError } from '../../errors.js';
 export class MockMutationExecutor {
-    /** All captured mutation calls in order */
+    /** Every captured call, in the order it was made. Assertions read from this list. */
     calls = [];
     /** Current sync ID — incremented on each successful commit */
     _syncId;
@@ -24,43 +25,43 @@ export class MockMutationExecutor {
     // ─────────────────────────────────────────────
     // Test control API
     // ─────────────────────────────────────────────
-    /** Get current sync ID without incrementing */
+    /** Returns the current sync id without advancing it. */
     get currentSyncId() {
         return this._syncId;
     }
-    /** Set the next sync ID to return */
+    /** Sets the next sync id the executor will return. */
     setSyncId(id) {
         this._syncId = id;
     }
-    /** Make all mutations fail with given error */
+    /** Makes every mutation reject. Pass an error to control what is thrown. */
     failAll(error) {
         this._shouldSucceed = false;
         if (error) {
             this._failureOverrides.set('*', error);
         }
     }
-    /** Make all mutations succeed again */
+    /** Restores the default where mutations succeed, clearing any failure overrides. */
     succeedAll() {
         this._shouldSucceed = true;
         this._failureOverrides.clear();
     }
-    /** Make a specific method fail */
+    /** Makes a single named method reject. Pass an error to control what is thrown. */
     failMethod(method, error) {
         this._failureOverrides.set(method, error ?? new Error(`Mock ${method} failed`));
     }
-    /** Clear failure override for a method */
+    /** Removes the failure override for one method. */
     clearFailure(method) {
         this._failureOverrides.delete(method);
     }
-    /** Get calls filtered by method */
+    /** Returns the captured calls for one method, in order. */
     getCallsByMethod(method) {
         return this.calls.filter((c) => c.method === method);
     }
-    /** Get the last call made */
+    /** The most recent captured call, or undefined if none have been made. */
     get lastCall() {
         return this.calls[this.calls.length - 1];
     }
-    /** Reset all state */
+    /** Clears captured calls and restores the initial options. */
     reset(options) {
         this.calls.length = 0;
         this._syncId = options?.initialSyncId ?? 1;

package/dist/testing/mocks/MockNetworkMonitor.d.ts

@@ -1,20 +1,20 @@
 /**
- * MockNetworkMonitor — Test double for OnlineStatusProvider.
- *
- * Allows tests to programmatically toggle online/offline state
- * and trigger visibility change events.
+ * A test double for {@link OnlineStatusProvider} that lets tests flip the
+ * connection between online and offline on demand. Alongside its own state, it
+ * updates the global `navigator.onLine` flag so code that reads the browser
+ * value directly sees the same status.
  */
 import type { OnlineStatusProvider } from '../../interfaces/index.js';
 export declare class MockNetworkMonitor implements OnlineStatusProvider {
     private _online;
     constructor(initialOnline?: boolean);
     isOnline(): boolean;
-    /** Simulate going online */
+    /** Marks the connection online and sets `navigator.onLine` to true. */
     goOnline(): void;
-    /** Simulate going offline */
+    /** Marks the connection offline and sets `navigator.onLine` to false. */
     goOffline(): void;
-    /** Toggle online state and return new value */
+    /** Flips between online and offline, returning the new online state. */
     toggle(): boolean;
-    /** Reset to initial state (online) */
+    /** Returns the monitor to its online starting state. */
     reset(): void;
 }

package/dist/testing/mocks/MockNetworkMonitor.js

@@ -1,8 +1,8 @@
 /**
- * MockNetworkMonitor — Test double for OnlineStatusProvider.
- *
- * Allows tests to programmatically toggle online/offline state
- * and trigger visibility change events.
+ * A test double for {@link OnlineStatusProvider} that lets tests flip the
+ * connection between online and offline on demand. Alongside its own state, it
+ * updates the global `navigator.onLine` flag so code that reads the browser
+ * value directly sees the same status.
  */
 export class MockNetworkMonitor {
     _online;
@@ -12,7 +12,7 @@ export class MockNetworkMonitor {
     isOnline() {
         return this._online;
     }
-    /** Simulate going online */
+    /** Marks the connection online and sets `navigator.onLine` to true. */
     goOnline() {
         this._online = true;
         // Also update navigator.onLine for code that reads it directly
@@ -21,7 +21,7 @@ export class MockNetworkMonitor {
             value: true,
         });
     }
-    /** Simulate going offline */
+    /** Marks the connection offline and sets `navigator.onLine` to false. */
     goOffline() {
         this._online = false;
         Object.defineProperty(navigator, 'onLine', {
@@ -29,7 +29,7 @@ export class MockNetworkMonitor {
             value: false,
         });
     }
-    /** Toggle online state and return new value */
+    /** Flips between online and offline, returning the new online state. */
     toggle() {
         if (this._online) {
             this.goOffline();
@@ -39,7 +39,7 @@ export class MockNetworkMonitor {
         }
         return this._online;
     }
-    /** Reset to initial state (online) */
+    /** Returns the monitor to its online starting state. */
     reset() {
         this.goOnline();
     }

package/dist/testing/mocks/MockSyncContext.d.ts

@@ -1,60 +1,47 @@
 /**
- * MockSyncContext — Creates a fully-wired SyncEngineContext for tests.
- *
- * `createTestContext()` is the primary test utility: it builds a complete
- * DI container with mock implementations, calls initSyncEngine(), and
- * returns handles to all mocks for test assertions.
+ * Assembles a ready-to-use {@link SyncEngineContext} for tests. The context
+ * bundles every dependency the engine needs — logger, network monitor,
+ * mutation executor, and configuration — so a test can start the engine
+ * without a real backend. {@link createTestContext} is the entry point: it
+ * wires the mocks, installs the context globally through {@link initSyncEngine},
+ * and returns handles to each mock for assertions.
  */
 import type { SyncEngineContext } from '../../SyncEngineContext.js';
-import type { SyncLogger, SyncObservabilityProvider, SessionErrorDetector, MutationDispatcher, SyncEngineConfig } from '../../interfaces/index.js';
+import type { SyncLogger, SyncObservabilityProvider, SessionErrorDetector, SyncEngineConfig } from '../../interfaces/index.js';
 import { MockMutationExecutor } from './MockMutationExecutor.js';
 import { MockNetworkMonitor } from './MockNetworkMonitor.js';
 export interface TestContextOptions {
-    /** Override the logger (default: noopLogger) */
+    /** Replaces the default no-op logger. */
     logger?: SyncLogger;
-    /** Override observability (default: noopObservability) */
+    /** Replaces the default no-op observability provider. */
     observability?: SyncObservabilityProvider;
-    /** Override session error detector */
+    /** Replaces the detector that decides whether an error means the session has expired. */
     sessionErrorDetector?: SessionErrorDetector;
-    /** Override mutation executor options */
+    /** Options forwarded to the {@link MockMutationExecutor} that the context creates. */
     mutationExecutorOptions?: ConstructorParameters<typeof MockMutationExecutor>[0];
-    /** Override the sync engine config */
+    /** A partial {@link SyncEngineConfig} merged over the defaults. */
     config?: Partial<SyncEngineConfig>;
-    /** Start offline (default: false) */
+    /** Starts the network monitor offline. Defaults to online. */
     startOffline?: boolean;
 }
 export interface TestContextResult {
-    /** The full SyncEngineContext passed to initSyncEngine */
+    /** The assembled context that {@link createTestContext} installed globally. */
     context: SyncEngineContext;
-    /** Mock handles for test assertions */
+    /** Handles to the underlying mocks, so tests can drive them and assert on them. */
     mocks: {
         mutationExecutor: MockMutationExecutor;
-        mutationDispatcher: MockMutationDispatcher;
         networkMonitor: MockNetworkMonitor;
     };
-    /** Cleanup: calls resetSyncEngine() */
+    /** Tears the test down by resetting the engine and the mocks. Call it when the test finishes. */
     cleanup: () => void;
 }
 /**
- * Simple mock mutation dispatcher that records dispatch calls.
- */
-export declare class MockMutationDispatcher implements MutationDispatcher {
-    readonly dispatched: Array<{
-        operationName: string;
-        variables: Record<string, unknown>;
-    }>;
-    private _shouldSucceed;
-    private _error?;
-    dispatch(operationName: string, variables: Record<string, unknown>): Promise<void>;
-    failAll(error?: Error): void;
-    succeedAll(): void;
-    reset(): void;
-}
-/**
- * Create a test SyncEngineContext with all mocks pre-wired.
- * Calls initSyncEngine() so the global context is set.
+ * Builds a {@link SyncEngineContext} with every mock pre-wired and installs it
+ * globally through {@link initSyncEngine}, so code under test reaches the engine
+ * the same way it would in production. Returns the context, the mock handles,
+ * and a cleanup function to call when the test finishes.
  *
- * Usage:
+ * @example
  * ```ts
  * const { context, mocks, cleanup } = createTestContext();
  * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor

package/dist/testing/mocks/MockSyncContext.js

@@ -1,48 +1,24 @@
 /**
- * MockSyncContext — Creates a fully-wired SyncEngineContext for tests.
- *
- * `createTestContext()` is the primary test utility: it builds a complete
- * DI container with mock implementations, calls initSyncEngine(), and
- * returns handles to all mocks for test assertions.
+ * Assembles a ready-to-use {@link SyncEngineContext} for tests. The context
+ * bundles every dependency the engine needs — logger, network monitor,
+ * mutation executor, and configuration — so a test can start the engine
+ * without a real backend. {@link createTestContext} is the entry point: it
+ * wires the mocks, installs the context globally through {@link initSyncEngine},
+ * and returns handles to each mock for assertions.
  */
 import { noopLogger, noopObservability, noopAnalytics, defaultSessionErrorDetector, emptyConfig, } from '../../SyncEngineContext.js';
 import { initSyncEngine, resetSyncEngine } from '../../context.js';
-import { ModelRegistry, setActiveRegistry, hasActiveRegistry, } from '../../ModelRegistry.js';
+import { ModelRegistry, setActiveRegistry, hasActiveRegistry, clearActiveRegistry, } from '../../ModelRegistry.js';
 import { registerTestModels } from '../fixtures/models.js';
 import { MockMutationExecutor } from './MockMutationExecutor.js';
 import { MockNetworkMonitor } from './MockNetworkMonitor.js';
 /**
- * Simple mock mutation dispatcher that records dispatch calls.
- */
-export class MockMutationDispatcher {
-    dispatched = [];
-    _shouldSucceed = true;
-    _error;
-    async dispatch(operationName, variables) {
-        this.dispatched.push({ operationName, variables });
-        if (!this._shouldSucceed) {
-            throw this._error ?? new Error(`Mock dispatch failed: ${operationName}`);
-        }
-    }
-    failAll(error) {
-        this._shouldSucceed = false;
-        this._error = error;
-    }
-    succeedAll() {
-        this._shouldSucceed = true;
-        this._error = undefined;
-    }
-    reset() {
-        this.dispatched.length = 0;
-        this._shouldSucceed = true;
-        this._error = undefined;
-    }
-}
-/**
- * Create a test SyncEngineContext with all mocks pre-wired.
- * Calls initSyncEngine() so the global context is set.
+ * Builds a {@link SyncEngineContext} with every mock pre-wired and installs it
+ * globally through {@link initSyncEngine}, so code under test reaches the engine
+ * the same way it would in production. Returns the context, the mock handles,
+ * and a cleanup function to call when the test finishes.
  *
- * Usage:
+ * @example
  * ```ts
  * const { context, mocks, cleanup } = createTestContext();
  * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor
@@ -51,7 +27,6 @@ export class MockMutationDispatcher {
  */
 export function createTestContext(options = {}) {
     const mutationExecutor = new MockMutationExecutor(options.mutationExecutorOptions);
-    const mutationDispatcher = new MockMutationDispatcher();
     const networkMonitor = new MockNetworkMonitor(!options.startOffline);
     const config = {
         ...emptyConfig,
@@ -66,7 +41,6 @@ export function createTestContext(options = {}) {
         sessionErrorDetector: options.sessionErrorDetector ?? defaultSessionErrorDetector,
         onlineStatus: networkMonitor,
         mutationExecutor,
-        mutationDispatcher,
         config,
     };
     initSyncEngine(context);
@@ -82,18 +56,15 @@ export function createTestContext(options = {}) {
         context,
         mocks: {
             mutationExecutor,
-            mutationDispatcher,
             networkMonitor,
         },
         cleanup: () => {
             resetSyncEngine();
-            // Intentionally do NOT clear the active ModelRegistry — async callbacks
-            // from in-flight transactions (e.g. fc.asyncProperty iterations) may
-            // call Model.toJSON() after afterEach runs. Leaving the default
-            // registry in place keeps those calls valid; the next createTestContext
-            // with hasActiveRegistry()===true simply reuses it.
+            // Leave the active ModelRegistry in place on purpose. Async callbacks
+            // from in-flight transactions can call Model.toJSON() after a test's
+            // teardown has run; keeping the default registry available keeps those
+            // late calls valid, and the next createTestContext simply reuses it.
             mutationExecutor.reset();
-            mutationDispatcher.reset();
             networkMonitor.reset();
         },
     };