@abloatai/ablo 0.3.0

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

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+import type { SyncEngineContext } from '../../SyncEngineContext.js';
+import type { SyncLogger, SyncObservabilityProvider, SessionErrorDetector, MutationDispatcher, SyncEngineConfig } from '../../interfaces/index.js';
+import { MockMutationExecutor } from './MockMutationExecutor.js';
+import { MockNetworkMonitor } from './MockNetworkMonitor.js';
+export interface TestContextOptions {
+    /** Override the logger (default: noopLogger) */
+    logger?: SyncLogger;
+    /** Override observability (default: noopObservability) */
+    observability?: SyncObservabilityProvider;
+    /** Override session error detector */
+    sessionErrorDetector?: SessionErrorDetector;
+    /** Override mutation executor options */
+    mutationExecutorOptions?: ConstructorParameters<typeof MockMutationExecutor>[0];
+    /** Override the sync engine config */
+    config?: Partial<SyncEngineConfig>;
+    /** Start offline (default: false) */
+    startOffline?: boolean;
+}
+export interface TestContextResult {
+    /** The full SyncEngineContext passed to initSyncEngine */
+    context: SyncEngineContext;
+    /** 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.
+ *
+ * Usage:
+ * ```ts
+ * const { context, mocks, cleanup } = createTestContext();
+ * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor
+ * cleanup();
+ * ```
+ */
+export declare function createTestContext(options?: TestContextOptions): TestContextResult;

package/dist/testing/mocks/MockSyncContext.js

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+import { noopLogger, noopObservability, noopAnalytics, defaultSessionErrorDetector, emptyConfig, } from '../../SyncEngineContext.js';
+import { initSyncEngine, resetSyncEngine } from '../../context.js';
+import { ModelRegistry, setActiveRegistry, hasActiveRegistry, } 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.
+ *
+ * Usage:
+ * ```ts
+ * const { context, mocks, cleanup } = createTestContext();
+ * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor
+ * cleanup();
+ * ```
+ */
+export function createTestContext(options = {}) {
+    const mutationExecutor = new MockMutationExecutor(options.mutationExecutorOptions);
+    const mutationDispatcher = new MockMutationDispatcher();
+    const networkMonitor = new MockNetworkMonitor(!options.startOffline);
+    const config = {
+        ...emptyConfig,
+        ...options.config,
+        // Merge maps/sets properly if overrides provided
+        modelCreatePriority: options.config?.modelCreatePriority ?? emptyConfig.modelCreatePriority,
+    };
+    const context = {
+        logger: options.logger ?? noopLogger,
+        observability: options.observability ?? noopObservability,
+        analytics: noopAnalytics,
+        sessionErrorDetector: options.sessionErrorDetector ?? defaultSessionErrorDetector,
+        onlineStatus: networkMonitor,
+        mutationExecutor,
+        mutationDispatcher,
+        config,
+    };
+    initSyncEngine(context);
+    // Bootstrap a default ModelRegistry with test models if none is active.
+    // Tests that manage their own registry call setActiveRegistry before this.
+    const bootstrappedRegistry = !hasActiveRegistry();
+    if (bootstrappedRegistry) {
+        const defaultRegistry = new ModelRegistry();
+        setActiveRegistry(defaultRegistry);
+        registerTestModels(defaultRegistry);
+    }
+    return {
+        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.
+            mutationExecutor.reset();
+            mutationDispatcher.reset();
+            networkMonitor.reset();
+        },
+    };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * MockSyncStore — a SyncStoreContract implementation for testing.
+ *
+ * Provides an in-memory store that tests can configure, inspect, and mutate.
+ * All reactive operations are synchronous and observable via Jest spies.
+ */
+import type { Model } from '../../Model.js';
+import type { ModelScope } from '../../ObjectPool.js';
+import type { SyncStoreContract } from '../../react/context.js';
+interface QueryOptions<T extends Model> {
+    predicate?: (model: T) => boolean;
+    scope?: ModelScope;
+    orderBy?: keyof T;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+interface QueryResult<T extends Model> {
+    data: T[];
+}
+type ModelCtor<T extends Model> = abstract new (...args: never[]) => T;
+/**
+ * MockSyncStore is an in-memory implementation of SyncStoreContract.
+ * Tests can seed data with `setModels()`, inspect calls via `calls`,
+ * and assert behavior without needing a real sync backend.
+ */
+export declare class MockSyncStore implements SyncStoreContract {
+    private byClass;
+    calls: {
+        retrieve: Array<{
+            modelClass: ModelCtor<Model>;
+            id: string;
+        }>;
+        query: Array<{
+            modelClass: ModelCtor<Model>;
+            options?: QueryOptions<Model>;
+        }>;
+        save: Model[];
+        delete: Model[];
+        archive: Model[];
+        unarchive: Model[];
+    };
+    /**
+     * Seed the store with models of a specific class.
+     *
+     * @example
+     * mockStore.setModels(Task, [task1, task2]);
+     */
+    setModels<T extends Model>(modelClass: ModelCtor<T>, models: T[]): void;
+    /**
+     * Add a single model (upsert).
+     */
+    addModel<T extends Model>(modelClass: ModelCtor<T>, model: T): void;
+    /**
+     * Remove a model by ID.
+     */
+    removeModel<T extends Model>(modelClass: ModelCtor<T>, id: string): void;
+    /**
+     * Clear all seeded data and call history.
+     */
+    reset(): void;
+    retrieve<T extends Model>(modelClass: ModelCtor<T>, id: string): T | undefined;
+    queryByClass<T extends Model>(modelClass: ModelCtor<T>, options?: QueryOptions<T>): QueryResult<T>;
+    save(model: Model): Promise<void>;
+    delete(model: Model): Promise<void>;
+    archive(model: Model): Promise<void>;
+    unarchive(model: Model): Promise<void>;
+    isReady: boolean;
+    isSyncing: boolean;
+    isOffline: boolean;
+    isReconnecting: boolean;
+    isError: boolean;
+    hasUnsyncedChanges: boolean;
+    syncStatus: {
+        state: "idle";
+        progress: number;
+        pendingChanges: number;
+        isSessionError: boolean;
+    };
+    /** Mock pool for useEntity/useEntities hooks. */
+    pool: SyncStoreContract['pool'];
+}
+/**
+ * Create a new MockSyncStore.
+ * Shorthand for `new MockSyncStore()`.
+ */
+export declare function createMockSyncStore(): MockSyncStore;
+export {};

package/dist/testing/mocks/MockSyncStore.js

@@ -0,0 +1,171 @@
+/**
+ * MockSyncStore — a SyncStoreContract implementation for testing.
+ *
+ * Provides an in-memory store that tests can configure, inspect, and mutate.
+ * All reactive operations are synchronous and observable via Jest spies.
+ */
+import { ViewRegistry } from '../../core/ViewRegistry.js';
+import { AbloValidationError } from '../../errors.js';
+/**
+ * MockSyncStore is an in-memory implementation of SyncStoreContract.
+ * Tests can seed data with `setModels()`, inspect calls via `calls`,
+ * and assert behavior without needing a real sync backend.
+ */
+export class MockSyncStore {
+    // Seeded data, keyed by model class
+    byClass = new Map();
+    // Call tracking for assertions
+    calls = {
+        retrieve: [],
+        query: [],
+        save: [],
+        delete: [],
+        archive: [],
+        unarchive: [],
+    };
+    /**
+     * Seed the store with models of a specific class.
+     *
+     * @example
+     * mockStore.setModels(Task, [task1, task2]);
+     */
+    setModels(modelClass, models) {
+        const map = new Map();
+        for (const m of models) {
+            map.set(m.id, m);
+        }
+        this.byClass.set(modelClass, map);
+    }
+    /**
+     * Add a single model (upsert).
+     */
+    addModel(modelClass, model) {
+        let map = this.byClass.get(modelClass);
+        if (!map) {
+            map = new Map();
+            this.byClass.set(modelClass, map);
+        }
+        map.set(model.id, model);
+    }
+    /**
+     * Remove a model by ID.
+     */
+    removeModel(modelClass, id) {
+        this.byClass.get(modelClass)?.delete(id);
+    }
+    /**
+     * Clear all seeded data and call history.
+     */
+    reset() {
+        this.byClass.clear();
+        this.calls = {
+            retrieve: [],
+            query: [],
+            save: [],
+            delete: [],
+            archive: [],
+            unarchive: [],
+        };
+    }
+    // ── SyncStoreContract implementation ──────────────────────────────────
+    retrieve(modelClass, id) {
+        this.calls.retrieve.push({ modelClass: modelClass, id });
+        return this.byClass.get(modelClass)?.get(id);
+    }
+    queryByClass(modelClass, options) {
+        this.calls.query.push({
+            modelClass: modelClass,
+            options: options,
+        });
+        const map = this.byClass.get(modelClass);
+        if (!map) {
+            return { data: [] };
+        }
+        let data = Array.from(map.values());
+        // Apply predicate
+        if (options?.predicate) {
+            data = data.filter(options.predicate);
+        }
+        // Apply ordering
+        if (options?.orderBy) {
+            const key = options.orderBy;
+            const order = options.order ?? 'asc';
+            data.sort((a, b) => {
+                const av = a[key];
+                const bv = b[key];
+                if (av === bv)
+                    return 0;
+                const cmp = av < bv ? -1 : 1;
+                return order === 'asc' ? cmp : -cmp;
+            });
+        }
+        // Apply pagination
+        if (options?.offset) {
+            data = data.slice(options.offset);
+        }
+        if (options?.limit !== undefined) {
+            data = data.slice(0, options.limit);
+        }
+        return { data };
+    }
+    async save(model) {
+        this.calls.save.push(model);
+        // Auto-seed on save so findById returns it afterwards
+        // Consumer passes a concrete class-less object; we store by constructor
+        const ctor = model.constructor;
+        this.addModel(ctor, model);
+    }
+    async delete(model) {
+        this.calls.delete.push(model);
+        const ctor = model.constructor;
+        this.removeModel(ctor, model.id);
+    }
+    async archive(model) {
+        this.calls.archive.push(model);
+    }
+    async unarchive(model) {
+        this.calls.unarchive.push(model);
+    }
+    // Sync-status getters default to "ready, idle". Tests that exercise
+    // offline/reconnect flows can set these before rendering.
+    isReady = true;
+    isSyncing = false;
+    isOffline = false;
+    isReconnecting = false;
+    isError = false;
+    hasUnsyncedChanges = false;
+    syncStatus = {
+        state: 'idle',
+        progress: 100,
+        pendingChanges: 0,
+        isSessionError: false,
+    };
+    /** Mock pool for useEntity/useEntities hooks. */
+    pool = {
+        get: (id) => {
+            for (const models of this.byClass.values()) {
+                const model = models.get(id);
+                if (model)
+                    return model;
+            }
+            return undefined;
+        },
+        getByTypeName: (_typename) => [],
+        getByForeignKey: () => [],
+        createFromData: () => null,
+        hasForeignKeyIndex: () => false,
+        createView: () => {
+            throw new AbloValidationError('MockSyncStore does not support createView', {
+                code: 'mock_unsupported_operation',
+            });
+        },
+        viewRegistry: new ViewRegistry(),
+    };
+}
+/**
+ * Create a new MockSyncStore.
+ * Shorthand for `new MockSyncStore()`.
+ */
+export function createMockSyncStore() {
+    return new MockSyncStore();
+}

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

@@ -0,0 +1,66 @@
+/**
+ * MockWebSocket — Controllable WebSocket for sync engine tests.
+ *
+ * Simulates the SyncWebSocket event interface without a real connection.
+ * Provides methods to inject deltas, simulate disconnection/reconnection,
+ * and trigger bootstrap hints.
+ */
+import type { SyncActionType } from '../../types/index.js';
+/** Delta shape matching the SyncAction interface */
+export interface MockDelta {
+    id: number;
+    modelName: string;
+    modelId: string;
+    action: SyncActionType;
+    data: Record<string, unknown>;
+}
+/** Bootstrap hint from server */
+export interface MockBootstrapHint {
+    reason: 'too_far_behind' | 'too_many_deltas' | 'missing_entities';
+    tables?: string[];
+    staleTables?: string[];
+}
+type EventHandler = (...args: unknown[]) => void;
+/**
+ * MockWebSocket provides a controllable event-based interface
+ * for testing sync engine components that consume WebSocket events.
+ */
+export declare class MockWebSocket {
+    private _connected;
+    private _sessionError;
+    private _listeners;
+    /** Track all emitted events for assertions */
+    readonly emittedEvents: Array<{
+        type: string;
+        data: unknown;
+    }>;
+    get connected(): boolean;
+    get sessionError(): boolean;
+    on(event: string, handler: EventHandler): () => void;
+    private emit;
+    /** Simulate successful connection */
+    simulateConnect(): void;
+    /** Simulate disconnection */
+    simulateDisconnect(): void;
+    /** Simulate reconnection attempt */
+    simulateReconnecting(attempt: number, delay: number): void;
+    /** Simulate session error (401/403) */
+    simulateSessionError(code?: number): void;
+    /** Simulate reconnection failure (max attempts reached) */
+    simulateReconnectFailed(): void;
+    /** Inject a single delta (as if received from server) */
+    receiveDelta(delta: MockDelta): void;
+    /** Inject a batch of deltas */
+    receiveDeltas(deltas: MockDelta[]): void;
+    /** Inject a bootstrap_required hint from server */
+    simulateBootstrapHint(hint: MockBootstrapHint): void;
+    /** Inject a presence update */
+    simulatePresenceUpdate(data: Record<string, unknown>): void;
+    /** Get all events of a specific type */
+    getEvents(type: string): unknown[];
+    /** Check if a specific event was emitted */
+    hasEmitted(type: string): boolean;
+    /** Reset all state */
+    reset(): void;
+}
+export {};

package/dist/testing/mocks/MockWebSocket.js

@@ -0,0 +1,117 @@
+/**
+ * MockWebSocket — Controllable WebSocket for sync engine tests.
+ *
+ * Simulates the SyncWebSocket event interface without a real connection.
+ * Provides methods to inject deltas, simulate disconnection/reconnection,
+ * and trigger bootstrap hints.
+ */
+/**
+ * MockWebSocket provides a controllable event-based interface
+ * for testing sync engine components that consume WebSocket events.
+ */
+export class MockWebSocket {
+    _connected = false;
+    _sessionError = false;
+    _listeners = new Map();
+    /** Track all emitted events for assertions */
+    emittedEvents = [];
+    get connected() {
+        return this._connected;
+    }
+    get sessionError() {
+        return this._sessionError;
+    }
+    // ─────────────────────────────────────────────
+    // Event subscription (matches SyncWebSocket API)
+    // ─────────────────────────────────────────────
+    on(event, handler) {
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set());
+        }
+        this._listeners.get(event).add(handler);
+        return () => {
+            this._listeners.get(event)?.delete(handler);
+        };
+    }
+    emit(event, ...args) {
+        this.emittedEvents.push({ type: event, data: args[0] });
+        const handlers = this._listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(...args);
+            }
+        }
+    }
+    // ─────────────────────────────────────────────
+    // Test control: connection lifecycle
+    // ─────────────────────────────────────────────
+    /** Simulate successful connection */
+    simulateConnect() {
+        this._connected = true;
+        this._sessionError = false;
+        this.emit('connected');
+    }
+    /** Simulate disconnection */
+    simulateDisconnect() {
+        this._connected = false;
+        this.emit('disconnected');
+    }
+    /** Simulate reconnection attempt */
+    simulateReconnecting(attempt, delay) {
+        this.emit('reconnecting', { attempt, delay });
+    }
+    /** Simulate session error (401/403) */
+    simulateSessionError(code = 401) {
+        this._sessionError = true;
+        this._connected = false;
+        this.emit('session_error', { code });
+    }
+    /** Simulate reconnection failure (max attempts reached) */
+    simulateReconnectFailed() {
+        this._connected = false;
+        this.emit('reconnect_failed');
+    }
+    // ─────────────────────────────────────────────
+    // Test control: delta injection
+    // ─────────────────────────────────────────────
+    /** Inject a single delta (as if received from server) */
+    receiveDelta(delta) {
+        this.emit('delta', delta);
+    }
+    /** Inject a batch of deltas */
+    receiveDeltas(deltas) {
+        this.emit('delta_batch', deltas);
+    }
+    // ─────────────────────────────────────────────
+    // Test control: bootstrap hints
+    // ─────────────────────────────────────────────
+    /** Inject a bootstrap_required hint from server */
+    simulateBootstrapHint(hint) {
+        this.emit('bootstrap_required', hint);
+    }
+    // ─────────────────────────────────────────────
+    // Test control: presence
+    // ─────────────────────────────────────────────
+    /** Inject a presence update */
+    simulatePresenceUpdate(data) {
+        this.emit('presence_update', data);
+    }
+    // ─────────────────────────────────────────────
+    // Assertions
+    // ─────────────────────────────────────────────
+    /** Get all events of a specific type */
+    getEvents(type) {
+        return this.emittedEvents.filter((e) => e.type === type).map((e) => e.data);
+    }
+    /** Check if a specific event was emitted */
+    hasEmitted(type) {
+        return this.emittedEvents.some((e) => e.type === type);
+    }
+    /** Reset all state */
+    reset() {
+        this._connected = false;
+        this._sessionError = false;
+        this._listeners.clear();
+        this.emittedEvents.length = 0;
+    }
+}

package/dist/transactions/OptimisticEchoTracker.d.ts

@@ -0,0 +1,82 @@
+/**
+ * OptimisticEchoTracker — receive-layer reconciliation primitive.
+ *
+ * Tracks the set of transaction ids the client has applied locally
+ * but the server has not yet confirmed. When a sync delta arrives
+ * carrying a `transactionId` the tracker recognizes, the pool
+ * mutation is suppressed (the optimistic write already reflects it).
+ * Drained when the matching delta echo lands or when the originating
+ * transaction is rolled back.
+ *
+ * Architectural framing: see
+ * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. This is the
+ * "discriminator at the apply layer" the doc names — without it the
+ * authoritative-layer apply path blindly re-applies confirmations on
+ * top of whatever optimistic state has since diverged, producing the
+ * chart-delete flicker.
+ *
+ * Bounded by `maxSize` to defend against runaway growth from a
+ * pathological "transactions never confirmed and never rolled back"
+ * loop. When the bound is hit, the OLDEST id is evicted (FIFO via
+ * insertion-ordered Map). Eviction means a future echo of that
+ * transaction will be applied as a foreign mutation — no correctness
+ * risk for the originating tab (the pool already reflects the local
+ * write); the worst case is a single redundant pool re-set.
+ */
+export interface OptimisticEchoTrackerOptions {
+    /**
+     * Hard upper bound on tracked ids. FIFO eviction beyond this. The
+     * default of 10_000 covers a 200-tab user mid-bulk-edit (each tab
+     * tracking dozens of unconfirmed transactions) with two orders of
+     * magnitude of headroom.
+     */
+    maxSize?: number;
+}
+export interface OptimisticEchoMetrics {
+    /** Total ids currently tracked. */
+    size: number;
+    /** Cumulative ids ever added since construction. */
+    totalAdded: number;
+    /** Cumulative successful echo matches (delta arrived → drained). */
+    hits: number;
+    /** Cumulative explicit rollback drains (transaction never made it). */
+    rollbacks: number;
+    /** Cumulative ids evicted due to maxSize pressure. */
+    evictions: number;
+}
+export declare class OptimisticEchoTracker {
+    private readonly ids;
+    private readonly maxSize;
+    private _totalAdded;
+    private _hits;
+    private _rollbacks;
+    private _evictions;
+    constructor(options?: OptimisticEchoTrackerOptions);
+    /**
+     * Mark a transaction as locally-applied. The next sync delta with a
+     * matching `transactionId` will be recognized as the server's
+     * confirmation of this same write. Idempotent — repeated calls with
+     * the same id are no-ops.
+     */
+    markPending(transactionId: string): void;
+    /**
+     * If the id is currently tracked, drain it and return true (signal
+     * to the caller: this is an echo, skip the pool mutation).
+     * Otherwise return false (foreign mutation, apply normally).
+     *
+     * Combined check+drain into one method to make the receive-path
+     * idiom hard to misuse: a separate `has` then `drain` would race
+     * if multiple deltas with the same id arrived in the same batch.
+     */
+    consumeEcho(transactionId: string | null | undefined): boolean;
+    /**
+     * Drain on rollback. The transaction was cancelled before a server
+     * confirmation arrived — no echo will ever come, so the pending
+     * entry would otherwise leak. Counts as a separate metric category
+     * so a spike of `rollbacks` (vs `hits`) signals network or
+     * server-side health issues.
+     */
+    drainOnRollback(transactionId: string): void;
+    getMetrics(): Readonly<OptimisticEchoMetrics>;
+    clear(): void;
+}