@abloatai/ablo 0.35.0 → 0.36.0

package/dist/testing/mocks/MockSyncStore.js

@@ -1,171 +0,0 @@
-/**
- * An in-memory {@link SyncStoreContract} for tests. It lets you seed rows,
- * read and write them synchronously, and inspect every call the code under
- * test made — all without a real sync backend.
- */
-import { ViewRegistry } from '../../core/ViewRegistry.js';
-import { AbloValidationError } from '../../transaction/errors.js';
-/**
- * An in-memory implementation of {@link SyncStoreContract}. Seed rows with
- * {@link MockSyncStore.setModels}, then read and write through the contract
- * methods; every call is recorded on {@link MockSyncStore.calls} so tests can
- * assert on what happened.
- */
-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);
-    }
-    /**
-     * Adds or replaces a single model, keyed by its id.
-     */
-    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);
-        // Store the model under its constructor so a later retrieve or query
-        // returns it.
-        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,
-    };
-    /** A minimal object pool backing the useEntity and useEntities hooks in tests. */
-    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

@@ -1,71 +0,0 @@
-/**
- * A controllable WebSocket stand-in for sync engine tests. It reproduces the
- * event interface of the real connection without opening a socket, so tests
- * can drive connection changes, deltas, and bootstrap hints by hand.
- */
-import type { SyncActionType } from '../../stores/syncAction.js';
-import type { BootstrapReason } from '../../transaction/wire/bootstrapReason.js';
-/** The shape of a single delta — one change the server pushes to the client. */
-export interface MockDelta {
-    id: number;
-    modelName: string;
-    modelId: string;
-    action: SyncActionType;
-    data: Record<string, unknown>;
-}
-/**
- * A hint from the server that the client has fallen too far behind and should
- * rebuild its data from scratch rather than catch up one delta at a time.
- */
-export interface MockBootstrapHint {
-    reason: BootstrapReason;
-    tables?: string[];
-    staleTables?: string[];
-}
-type EventHandler = (...args: unknown[]) => void;
-/**
- * A controllable, event-based stand-in for the sync engine's WebSocket
- * connection. Subscribe with {@link MockWebSocket.on} exactly as production
- * code does, then use the `simulate*` and `receive*` methods to push
- * connection changes, deltas, and bootstrap hints. Every event the mock emits
- * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
- */
-export declare class MockWebSocket {
-    private _connected;
-    private _sessionError;
-    private _listeners;
-    /** Every event the mock has emitted, in order, for assertions. */
-    readonly emittedEvents: {
-        type: string;
-        data: unknown;
-    }[];
-    get connected(): boolean;
-    get sessionError(): boolean;
-    on(event: string, handler: EventHandler): () => void;
-    private emit;
-    /** Fires a successful connection, emitting the `connected` event. */
-    simulateConnect(): void;
-    /** Drops the connection, emitting the `disconnected` event. */
-    simulateDisconnect(): void;
-    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
-    simulateReconnecting(attempt: number, delay: number): void;
-    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
-    simulateSessionError(code?: number): void;
-    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
-    simulateReconnectFailed(): void;
-    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
-    receiveDelta(delta: MockDelta): void;
-    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
-    receiveDeltas(deltas: MockDelta[]): void;
-    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
-    simulateBootstrapHint(hint: MockBootstrapHint): void;
-    /** Emits a `presence_update` event carrying the given payload. */
-    simulatePresenceUpdate(data: Record<string, unknown>): void;
-    /** Returns the payloads of every emitted event of the given type, in order. */
-    getEvents(type: string): unknown[];
-    /** Reports whether an event of the given type has been emitted. */
-    hasEmitted(type: string): boolean;
-    /** Clears connection state, listeners, and the record of emitted events. */
-    reset(): void;
-}
-export {};

package/dist/testing/mocks/MockWebSocket.js

@@ -1,118 +0,0 @@
-/**
- * A controllable WebSocket stand-in for sync engine tests. It reproduces the
- * event interface of the real connection without opening a socket, so tests
- * can drive connection changes, deltas, and bootstrap hints by hand.
- */
-/**
- * A controllable, event-based stand-in for the sync engine's WebSocket
- * connection. Subscribe with {@link MockWebSocket.on} exactly as production
- * code does, then use the `simulate*` and `receive*` methods to push
- * connection changes, deltas, and bootstrap hints. Every event the mock emits
- * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
- */
-export class MockWebSocket {
-    _connected = false;
-    _sessionError = false;
-    _listeners = new Map();
-    /** Every event the mock has emitted, in order, for assertions. */
-    emittedEvents = [];
-    get connected() {
-        return this._connected;
-    }
-    get sessionError() {
-        return this._sessionError;
-    }
-    // ─────────────────────────────────────────────
-    // Event subscription (matches the real connection's 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
-    // ─────────────────────────────────────────────
-    /** Fires a successful connection, emitting the `connected` event. */
-    simulateConnect() {
-        this._connected = true;
-        this._sessionError = false;
-        this.emit('connected');
-    }
-    /** Drops the connection, emitting the `disconnected` event. */
-    simulateDisconnect() {
-        this._connected = false;
-        this.emit('disconnected');
-    }
-    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
-    simulateReconnecting(attempt, delay) {
-        this.emit('reconnecting', { attempt, delay });
-    }
-    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
-    simulateSessionError(code = 401) {
-        this._sessionError = true;
-        this._connected = false;
-        this.emit('session_error', { code });
-    }
-    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
-    simulateReconnectFailed() {
-        this._connected = false;
-        this.emit('reconnect_failed');
-    }
-    // ─────────────────────────────────────────────
-    // Test control: delta injection
-    // ─────────────────────────────────────────────
-    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
-    receiveDelta(delta) {
-        this.emit('delta', delta);
-    }
-    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
-    receiveDeltas(deltas) {
-        this.emit('delta_batch', deltas);
-    }
-    // ─────────────────────────────────────────────
-    // Test control: bootstrap hints
-    // ─────────────────────────────────────────────
-    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
-    simulateBootstrapHint(hint) {
-        this.emit('bootstrap_required', hint);
-    }
-    // ─────────────────────────────────────────────
-    // Test control: presence
-    // ─────────────────────────────────────────────
-    /** Emits a `presence_update` event carrying the given payload. */
-    simulatePresenceUpdate(data) {
-        this.emit('presence_update', data);
-    }
-    // ─────────────────────────────────────────────
-    // Assertions
-    // ─────────────────────────────────────────────
-    /** Returns the payloads of every emitted event of the given type, in order. */
-    getEvents(type) {
-        return this.emittedEvents.filter((e) => e.type === type).map((e) => e.data);
-    }
-    /** Reports whether an event of the given type has been emitted. */
-    hasEmitted(type) {
-        return this.emittedEvents.some((e) => e.type === type);
-    }
-    /** Clears connection state, listeners, and the record of emitted events. */
-    reset() {
-        this._connected = false;
-        this._sessionError = false;
-        this._listeners.clear();
-        this.emittedEvents.length = 0;
-    }
-}

package/docs/interaction-model.md

@@ -1,99 +0,0 @@
-# Interaction Model
-
-> The one write path every actor shares: load, claim, update, confirm.
-
-When two agents, a server action, and a person can all write to the same row, you
-need one write path that stops them from clobbering each other. Ablo gives you
-exactly one: load the row, claim it while you work, update it, and wait for
-confirmation. This page walks through that path and the few primitives behind it.
-
-Here's the whole path in one block — claim a row, update it inside the claim, and
-let the claim release when your callback returns:
-
-```ts
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-
-await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
-await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' }, wait: 'confirmed' });
-```
-
-Claims don't lock. If another writer holds the row, `claim` waits for them,
-re-reads the fresh row, then hands it to you — so two writers serialize instead
-of clobbering.
-
-## Primitives
-
-| Primitive | Plane | Purpose |
-|---|---|---|
-| `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async reads), `local.retrieve`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
-| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral — never persisted. |
-| `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
-| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
-
-### Why each primitive is separate
-
-Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
-does a job the others can't. If you're coming from Replicache or Yjs you'd
-expect just `Commit`; here's what the other two buy you over that minimum:
-
-- **`Claim` is not a read lock.** Reads stay open. Claims serialize
-  acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
-  from fresh state.
-- **`Receipt` is not a `200 OK`.** It's the durable artifact a commit
-  produced — accepted commit id, server-assigned timestamps, stale-check
-  outcome — addressable after the fact and replayable into a different
-  client. A status code can't be re-read by a sub-agent that wasn't on
-  the original call.
-
-## Run Loop
-
-A normal schema-backed run is:
-
-```ts
-const report = await ablo.weatherReports.retrieve({ id });
-const active = ablo.weatherReports.claim.state({ id });
-await using claim = await ablo.weatherReports.claim({ id });
-await ablo.weatherReports.update({ id: claim.data.id, data: patch, wait: 'confirmed' });
-```
-
-`retrieve({ id })` is an async server read (await it). `claim.state({ id })` is a
-synchronous local read of who currently holds the row — it never blocks.
-
-## Coordination
-
-> Loop view only. Full claim reference — methods, the claim-state object, the
-> `claim.queue`, errors — is [Coordination](./coordination.md).
-
-Claims broadcast across the org. Call `claim({ id })`, do your writes with the
-normal `update` inside the `await using` scope, and the claim releases
-automatically when the scope exits:
-
-```ts
-await using claim = await ablo.weatherReports.claim({
-  id: 'report_stockholm',
-  description: 'editing',
-});
-await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
-```
-
-`ablo.weatherReports.claim.state({ id: 'report_stockholm' })` reads the live claim (or
-`null`) without blocking. Claims don't lock: if another participant holds the
-row, `claim` waits for them to finish, re-reads, and then hands you the fresh
-row. The same signal is visible to every schema client through `claim.state({ id })`
-and the live claim stream.
-
-## Conflict resolution
-
-Schema updates can carry `readAt` and `onStale`. If the state advanced past
-`readAt`, Ablo applies the `onStale` policy:
-
-- `reject` — fail the commit (first writer wins).
-- `notify` — accept the write, but flag it for product review.
-- `overwrite` — apply the write unconditionally.
-
-The choice is per-commit. No CRDT default; the policy is explicit.
-
-## The contract in one sentence
-
-Declare schema, load state, coordinate a claim, update the model, and wait for confirmation.