@abloatai/ablo 0.24.0 → 0.26.0

package/dist/sync/wsFrameHandlers.js

@@ -0,0 +1,378 @@
+/**
+ * Inbound frame dispatch for the sync WebSocket.
+ *
+ * Replaces the monolithic frame `switch` that used to live inside
+ * `SyncWebSocket.setupEventHandlers` with a frame-type → handler table of
+ * functions over a minimal {@link WsSession} interface — only the members
+ * the handlers actually touch, never the transport class itself (no
+ * import cycle). The host's `onmessage` stays responsible for JSON
+ * parsing, heartbeat proof-of-life, and the outer try/catch; everything
+ * after that funnels through {@link dispatchWsFrame}.
+ */
+import { getContext } from '../context.js';
+import { CapabilityError, errorFromWire, } from '../errors.js';
+import { subscriptionAckPayloadSchema } from '../coordination/schema.js';
+import { formatConflict } from '../coordination/trace.js';
+import { parseNotifications, recordClaim } from './commitFrames.js';
+/** Narrow arbitrary wire data to a plain string-keyed record. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Envelope guard for the raw `JSON.parse` result of an inbound WS message.
+ * A frame is any plain object whose `type`, when present, is a string —
+ * payload-level validation stays with each handler (deltas go through the
+ * canonical `clientSyncDeltaSchema` at the `normalizeWireDelta` seam).
+ */
+export function isWsInboundFrame(value) {
+    if (!isRecord(value))
+        return false;
+    const type = value.type;
+    return type === undefined || typeof type === 'string';
+}
+/**
+ * Ack for a prior `commit` we sent. Canonical shape is
+ * `MutationResultMessage` in `@abloatai/ablo/wire`. This stays a
+ * DEFENSIVE parse (not a typed cast) because the payload is
+ * untrusted wire data that may be malformed or from an older server.
+ */
+const handleMutationResult = (session, message) => {
+    const p = (message.payload ?? message);
+    const { clientTxId, success, lastSyncId, error } = p ?? {};
+    // Defensive: validate notifications against the canonical schema —
+    // untrusted wire data from a possibly-older/newer server.
+    const notifications = parseNotifications(p?.notifications);
+    const pending = typeof clientTxId === 'string'
+        ? session.pendingMutations.get(clientTxId)
+        : undefined;
+    if (!pending)
+        return;
+    clearTimeout(pending.timeout);
+    // `pending` exists ⇒ clientTxId was a string key (the guard above).
+    session.pendingMutations.delete(clientTxId);
+    if (success) {
+        // Coerce defensively — bigint columns serialize as strings
+        // from older servers (see normalizeWireDelta).
+        const ackedSyncId = Number(lastSyncId);
+        // Notify-instead-of-abort: a guarded write's premise moved. Emit
+        // the advisory signal so an agent loop can self-heal, AND resolve
+        // the receipt with it (the commit still succeeded).
+        if (notifications && notifications.length > 0) {
+            const txId = typeof clientTxId === 'string' ? clientTxId : '';
+            const event = {
+                clientTxId: txId,
+                rows: notifications.map((n) => ({
+                    model: n.model,
+                    id: n.id,
+                    fields: n.conflictingFields,
+                    writtenBy: n.writtenBy?.kind,
+                })),
+            };
+            const message = formatConflict(event);
+            const ctx = getContext();
+            ctx.logger.warn(message);
+            ctx.observability.breadcrumb(message, 'sync.coordination', 'warning');
+            ctx.observability.captureConflict(event);
+            session.emit('conflict:notified', {
+                clientTxId: txId,
+                notifications,
+            });
+        }
+        pending.resolve({
+            lastSyncId: Number.isFinite(ackedSyncId) ? ackedSyncId : 0,
+            ...(notifications && notifications.length > 0
+                ? { notifications }
+                : {}),
+        });
+    }
+    else {
+        // Capture the FULL server error so the user can see what
+        // actually rejected the mutation. Without this, every
+        // rejection becomes the generic "mutation failed on
+        // server" — useless when debugging chart batches that
+        // tank 40+ ops at once. We stringify object errors so
+        // structured server payloads (e.g., Zod issues, schema
+        // violations) survive the trip through `new Error(...)`.
+        let errorMessage;
+        let errorCode;
+        let requiredCapability;
+        if (typeof error === 'string') {
+            errorMessage = error;
+        }
+        else if (error != null && typeof error === 'object') {
+            const obj = error;
+            if (typeof obj.code === 'string')
+                errorCode = obj.code;
+            if (typeof obj.message === 'string') {
+                errorMessage = obj.message;
+            }
+            else {
+                try {
+                    errorMessage = JSON.stringify(error);
+                }
+                catch {
+                    errorMessage = String(error);
+                }
+            }
+            if (obj.requiredCapability != null &&
+                typeof obj.requiredCapability === 'object' &&
+                typeof obj.requiredCapability.scope === 'string') {
+                requiredCapability = obj.requiredCapability;
+            }
+        }
+        else {
+            errorMessage = 'mutation failed on server';
+        }
+        // Coordination collision: a stale-context rejection (the write's
+        // readAt premise moved underneath) or a foreign-claim conflict is
+        // exactly the collision ClaimLog exists to surface. The notify
+        // path (success + notifications) emits captureConflict above; a
+        // HARD rejection must too — otherwise observability.collisions()
+        // silently misses every rejected write. The conflicted rows ride
+        // along on the typed error's `conflicts` detail (see
+        // AbloStaleContextError.toJSON / errorEnvelope).
+        if (errorCode === 'stale_context' ||
+            errorCode === 'claim_conflict' ||
+            errorCode === 'entity_claimed' ||
+            errorCode?.startsWith('policy:') === true) {
+            const rawConflicts = error != null &&
+                typeof error === 'object' &&
+                Array.isArray(error.conflicts)
+                ? error
+                    .conflicts
+                : [];
+            const conflictEvent = {
+                clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
+                rows: rawConflicts.map((r) => ({
+                    model: typeof r.model === 'string' ? r.model : 'unknown',
+                    id: typeof r.id === 'string' ? r.id : 'unknown',
+                    fields: [],
+                })),
+            };
+            const ctx = getContext();
+            ctx.observability.breadcrumb(formatConflict(conflictEvent), 'sync.coordination', 'warning');
+            ctx.observability.captureConflict(conflictEvent);
+        }
+        // Build the proper typed AbloError from the wire code via the
+        // shared factory — the same code→class mapping the HTTP commit
+        // path uses (`translateHttpError`). This keeps rejected commits
+        // inside the typed hierarchy (capability denials →
+        // CapabilityError with `.requiredCapability`; foreign-claim
+        // conflicts → AbloClaimedError; everything else → the subclass
+        // its registry `httpStatus` implies) instead of a hand-rolled
+        // `new Error`, so callers can `instanceof`/`e.type` it and
+        // downstream retry logic can read the contract's retryability.
+        pending.reject(errorFromWire(errorMessage, {
+            code: errorCode,
+            requiredCapability,
+        }));
+    }
+};
+/**
+ * Ack for a prior `claim` we sent. Wire format mirrors
+ * apps/sync-server/src/hub/types.ts ClaimAckMessage:
+ *   { type: 'claim_ack',
+ *     payload: { claimId, success, syncGroups?,
+ *                ttlSeconds?, error? } }
+ */
+const handleClaimAck = (session, message) => {
+    const p = (message.payload ?? {});
+    const { claimId, success, syncGroups, ttlSeconds, error } = p;
+    const pending = typeof claimId === 'string'
+        ? session.pendingClaims.get(claimId)
+        : undefined;
+    if (!pending)
+        return;
+    clearTimeout(pending.timeout);
+    // `pending` exists ⇒ claimId was a string key (the guard above).
+    session.pendingClaims.delete(claimId);
+    if (success) {
+        pending.resolve({
+            syncGroups: Array.isArray(syncGroups) ? syncGroups : [],
+            ttlSeconds: typeof ttlSeconds === 'number' ? ttlSeconds : undefined,
+        });
+    }
+    else {
+        const err = error;
+        const code = err?.code && typeof err.code === 'string'
+            ? err.code
+            : 'claim_rejected';
+        const msg = err?.message && typeof err.message === 'string'
+            ? err.message
+            : 'claim rejected by server';
+        // Capability denials get the typed CapabilityError so
+        // callers can read `.requiredCapability` and attenuate-
+        // and-retry the claim with a narrower token.
+        if (code === 'capability_scope_denied' ||
+            code === 'capability_invalid') {
+            const rc = error
+                ?.requiredCapability;
+            const requiredCapability = rc != null &&
+                typeof rc === 'object' &&
+                typeof rc.scope === 'string'
+                ? rc
+                : undefined;
+            pending.reject(new CapabilityError(code, msg, requiredCapability));
+        }
+        else {
+            // Route through the shared factory so a failed claim_ack is a
+            // typed AbloError (registry code → right subclass), symmetric
+            // with the commit `mutation_result` path — never a bare Error.
+            pending.reject(errorFromWire(msg, { code }));
+        }
+    }
+};
+/**
+ * Ack for a prior `update_subscription`. The wire carries no
+ * correlation id, so FIFO-match against the oldest pending
+ * request — the server applies and acks subscription updates
+ * in receive order. Validated through the canonical zod schema
+ * (mirrors how the Hub validates inbound frames).
+ */
+const handleSubscriptionAck = (session, message) => {
+    const pending = session.shiftPendingSubscription();
+    if (!pending)
+        return;
+    clearTimeout(pending.timeout);
+    const parsed = subscriptionAckPayloadSchema.safeParse(message.payload);
+    if (!parsed.success) {
+        // Unreadable ack — resolve the pending request as a failure
+        // rather than hang it until timeout.
+        pending.reject(errorFromWire('malformed subscription_ack from server', {
+            code: 'malformed_subscription',
+        }));
+        return;
+    }
+    const ack = parsed.data;
+    if (ack.success) {
+        // Keep the reconnect URL aligned with current interest: a
+        // reconnect re-subscribes from `this.options.syncGroups`.
+        session.options.syncGroups = ack.syncGroups;
+        pending.resolve({ syncGroups: ack.syncGroups });
+    }
+    else {
+        pending.reject(errorFromWire(ack.error?.message ?? 'update_subscription rejected by server', { code: ack.error?.code ?? 'malformed_subscription' }));
+    }
+};
+/**
+ * `delta` frames carry either a single delta or a `{ deltas: [...] }` batch.
+ * Only DISCRIMINATES the two shapes here — each delta is validated exactly
+ * once downstream (the host's `normalizeWireDelta` seam), so batch elements
+ * are handed over raw rather than pre-parsed.
+ */
+const handleDeltaFrame = (session, message) => {
+    const p = message.payload;
+    if (!isRecord(p))
+        return;
+    if (p.actionType || p.modelName) {
+        session.handleDelta(p);
+    }
+    else if (Array.isArray(p.deltas)) {
+        for (const d of p.deltas) {
+            session.handleDelta(d);
+        }
+        // `p.newVersions` from pre-cutover servers is ignored — the version
+        // vector was removed in W4a (sync_id is the causality token).
+    }
+};
+/**
+ * Frame-type → handler table. Every named server frame the SDK
+ * understands dispatches through here; anything else falls to the
+ * collaboration-event / unknown-type path in {@link dispatchWsFrame}.
+ */
+export const wsFrameHandlers = {
+    sync_response: (session, message) => { session.handleSyncResponse(message.payload); },
+    bootstrap_response: (session, message) => { session.handleBootstrapResponse(message.payload); },
+    presence_update: (session, message) => { session.handlePresenceUpdate(message); },
+    mutation_result: handleMutationResult,
+    claim_ack: handleClaimAck,
+    subscription_ack: handleSubscriptionAck,
+    claim_expired: (session, message) => {
+        // Server-initiated expiry notification. Emit as a typed
+        // event so consumers can react (re-claim with a fresh
+        // capability, or accept the drop). The claim is already
+        // inactive server-side by the time this arrives.
+        const p = (message.payload ?? {});
+        if (typeof p.claimId === 'string') {
+            recordClaim('expired', p);
+            session.emit('claim_expired', { claimId: p.claimId });
+        }
+    },
+    claim_rejected: (session, message) => {
+        // Server denied an `claim_begin` because the target is
+        // already claimed by another participant. Forward the
+        // payload as-is — the ClaimStream consumer interprets
+        // the conflict shape (peerId, target, etc.).
+        recordClaim('rejected', (message.payload ?? {}));
+        session.emit('claim_rejected', message.payload ?? {});
+    },
+    claim_acquired: (session, message) => {
+        // Opt-in fair queue: the target was free, so the lease is ours
+        // immediately (no waiting). Payload carries { claimId, target }.
+        recordClaim('acquired', (message.payload ?? {}));
+        session.emit('claim_acquired', message.payload ?? {});
+    },
+    claim_queue: (session, message) => {
+        // Per-entity wait-queue snapshot for reactive `queue(id)`. Not a
+        // single claim's state change, so it isn't logged — the per-claim
+        // `queued`/`granted` events already tell that story.
+        session.emit('claim_queue', message.payload ?? {});
+    },
+    claim_queued: (session, message) => {
+        // Opt-in fair queue: our claim is waiting in line. Payload
+        // carries { claimId, target, position }.
+        recordClaim('queued', (message.payload ?? {}));
+        session.emit('claim_queued', message.payload ?? {});
+    },
+    claim_granted: (session, message) => {
+        // Our queued claim reached the head — the lease is now ours.
+        recordClaim('granted', (message.payload ?? {}));
+        session.emit('claim_granted', message.payload ?? {});
+    },
+    claim_lost: (session, message) => {
+        // A held/granted claim was taken from us (TTL lapse, revoke).
+        recordClaim('lost', (message.payload ?? {}));
+        session.emit('claim_lost', message.payload ?? {});
+    },
+    delta: handleDeltaFrame,
+};
+/**
+ * Route one parsed inbound frame to its handler. Mirrors the original
+ * inline switch exactly: keepalives are ignored, a missing `type` is
+ * the legacy bare-delta form, unknown types fall through to the
+ * collaboration-event map (underscore wire format → colon event key).
+ */
+export function dispatchWsFrame(session, message) {
+    if (message.type === 'pong' || message.type === 'ping') {
+        // Ignore keepalive messages
+        getContext().logger.debug('Received keepalive', { type: message.type });
+        return;
+    }
+    if (message.type === undefined) {
+        // Legacy support: bare delta (validated at the host's
+        // normalizeWireDelta seam like every other delta).
+        if (message.actionType || message.modelName) {
+            session.handleDelta(message);
+        }
+        return;
+    }
+    // Own-property lookup so wire types like 'toString' can never hit
+    // Object.prototype members — those fall through to the unknown-type
+    // path exactly as the switch's `default` did.
+    const handler = Object.prototype.hasOwnProperty.call(wsFrameHandlers, message.type)
+        ? wsFrameHandlers[message.type]
+        : undefined;
+    if (handler) {
+        handler(session, message);
+        return;
+    }
+    // Collaboration events use underscore wire format (e.g., 'sheet_selection')
+    // Convert to colon format for the event map (e.g., 'sheet:selection')
+    const eventKey = message.type?.replace(/_/g, ':');
+    if (eventKey && session.collaborationEventTypes.has(eventKey)) {
+        session.emit(eventKey, message.payload);
+    }
+    else {
+        getContext().logger.debug('Received unknown message type', { message });
+    }
+}

package/dist/testing/fixtures/bootstrap.d.ts

@@ -4,20 +4,18 @@
  * Creates well-formed bootstrap responses matching the server API.
  */
 import type { BootstrapType } from '../../types/index.js';
-export interface BootstrapModelData {
-    [modelName: string]: Array<Record<string, unknown>>;
-}
+export type BootstrapModelData = Record<string, Record<string, unknown>[]>;
 export interface BootstrapResponse {
     type: BootstrapType;
     lastSyncId: number;
     models?: BootstrapModelData;
-    deltas?: Array<{
+    deltas?: {
         id: number;
         modelName: string;
         modelId: string;
         action: string;
         data: Record<string, unknown>;
-    }>;
+    }[];
     deltaCount?: number;
     failedModels?: string[];
     timestamp: number;
@@ -34,12 +32,12 @@ export declare function createPartialBootstrapResponse(deltas: BootstrapResponse
  * Create a full bootstrap response with test model data pre-populated.
  */
 export declare function createTestBootstrapResponse(options?: {
-    tasks?: Array<Record<string, unknown>>;
-    projects?: Array<Record<string, unknown>>;
-    slideDecks?: Array<Record<string, unknown>>;
-    slides?: Array<Record<string, unknown>>;
-    slideLayers?: Array<Record<string, unknown>>;
-    comments?: Array<Record<string, unknown>>;
+    tasks?: Record<string, unknown>[];
+    projects?: Record<string, unknown>[];
+    slideDecks?: Record<string, unknown>[];
+    slides?: Record<string, unknown>[];
+    slideLayers?: Record<string, unknown>[];
+    comments?: Record<string, unknown>[];
     lastSyncId?: number;
     failedModels?: string[];
 }): BootstrapResponse;

package/dist/testing/fixtures/deltas.d.ts

@@ -78,7 +78,7 @@ export declare function createGroupRemovedDelta(userId: string, group: string, s
 /**
  * Create a batch of deltas with sequential sync IDs.
  */
-export declare function createDeltaBatch(deltas: Array<Omit<CreateDeltaOptions, 'id'>>, startingSyncId?: number): SyncAction[];
+export declare function createDeltaBatch(deltas: Omit<CreateDeltaOptions, 'id'>[], startingSyncId?: number): SyncAction[];
 /**
  * Create a confirmation delta — used to confirm that a mutation
  * was persisted by the server (TransactionQueue watches for this).

package/dist/testing/fixtures/models.js

@@ -7,6 +7,7 @@
  *   TestSlideDeck (10) → TestSlide (15, FK→SlideDeck) → TestSlideLayer (20, FK→Slide)
  */
 import { Model } from '../../Model.js';
+import { ModelRegistry } from '../../ModelRegistry.js';
 import { PropertyType, LoadStrategy } from '../../types/index.js';
 // ─────────────────────────────────────────────
 // Test Model Classes

package/dist/testing/helpers/sync-engine-harness.d.ts

@@ -9,7 +9,6 @@ import { ObjectPool } from '../../ObjectPool.js';
 import { MockMutationExecutor } from '../mocks/MockMutationExecutor.js';
 import { MockNetworkMonitor } from '../mocks/MockNetworkMonitor.js';
 import { MockWebSocket } from '../mocks/MockWebSocket.js';
-import { MockMutationDispatcher } from '../mocks/MockSyncContext.js';
 import type { TestContextResult } from '../mocks/MockSyncContext.js';
 export interface TestHarness {
     /** Pre-registered ModelRegistry with test models */
@@ -24,8 +23,6 @@ export interface TestHarness {
     mutationExecutor: MockMutationExecutor;
     /** Shorthand: mock network monitor */
     networkMonitor: MockNetworkMonitor;
-    /** Shorthand: mock mutation dispatcher */
-    mutationDispatcher: MockMutationDispatcher;
     /** Cleanup everything */
     cleanup: () => void;
 }

package/dist/testing/helpers/sync-engine-harness.js

@@ -6,6 +6,8 @@
  */
 import { ModelRegistry, setActiveRegistry } from '../../ModelRegistry.js';
 import { ObjectPool } from '../../ObjectPool.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';
@@ -58,7 +60,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/index.d.ts

@@ -9,7 +9,7 @@ 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';

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
 // ─────────────────────────────────────────────

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

@@ -6,7 +6,7 @@
  * returns handles to all mocks for test 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 {
@@ -29,27 +29,11 @@ export interface TestContextResult {
     /** Mock handles for test assertions */
     mocks: {
         mutationExecutor: MockMutationExecutor;
-        mutationDispatcher: MockMutationDispatcher;
         networkMonitor: MockNetworkMonitor;
     };
     /** Cleanup: calls resetSyncEngine() */
     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.

package/dist/testing/mocks/MockSyncContext.js

@@ -7,37 +7,10 @@
  */
 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.
@@ -51,7 +24,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 +38,6 @@ export function createTestContext(options = {}) {
         sessionErrorDetector: options.sessionErrorDetector ?? defaultSessionErrorDetector,
         onlineStatus: networkMonitor,
         mutationExecutor,
-        mutationDispatcher,
         config,
     };
     initSyncEngine(context);
@@ -82,7 +53,6 @@ export function createTestContext(options = {}) {
         context,
         mocks: {
             mutationExecutor,
-            mutationDispatcher,
             networkMonitor,
         },
         cleanup: () => {
@@ -93,7 +63,6 @@ export function createTestContext(options = {}) {
             // registry in place keeps those calls valid; the next createTestContext
             // with hasActiveRegistry()===true simply reuses it.
             mutationExecutor.reset();
-            mutationDispatcher.reset();
             networkMonitor.reset();
         },
     };

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

@@ -27,14 +27,14 @@ type ModelCtor<T extends Model> = abstract new (...args: never[]) => T;
 export declare class MockSyncStore implements SyncStoreContract {
     private byClass;
     calls: {
-        retrieve: Array<{
+        retrieve: {
             modelClass: ModelCtor<Model>;
             id: string;
-        }>;
-        query: Array<{
+        }[];
+        query: {
             modelClass: ModelCtor<Model>;
             options?: QueryOptions<Model>;
-        }>;
+        }[];
         save: Model[];
         delete: Model[];
         archive: Model[];

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

@@ -30,10 +30,10 @@ export declare class MockWebSocket {
     private _sessionError;
     private _listeners;
     /** Track all emitted events for assertions */
-    readonly emittedEvents: Array<{
+    readonly emittedEvents: {
         type: string;
         data: unknown;
-    }>;
+    }[];
     get connected(): boolean;
     get sessionError(): boolean;
     on(event: string, handler: EventHandler): () => void;