@abloatai/ablo 0.25.0 → 0.26.0

package/dist/client/wsMutationExecutor.js

@@ -0,0 +1,77 @@
+/**
+ * The default `MutationExecutor` — sends `{ type: 'commit', ... }` frames over
+ * the engine's own WebSocket, resolved lazily at commit time (the WS doesn't
+ * exist when the executor is constructed).
+ *
+ * Extracted from `Ablo.ts`; the factory wires it up with a `getWs` closure
+ * over the store holder unless the caller supplies its own executor.
+ */
+import { AbloError, AbloConnectionError } from '../errors.js';
+// ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
+/**
+ * Default mutation executor: sends `{ type: 'commit', payload: ... }` over
+ * the sync engine's own WebSocket.
+ *
+ * Transport ownership follows the Zero / Liveblocks pattern — the engine
+ * owns its socket end-to-end and the executor is internal. Apps pass URLs
+ * and auth; they do NOT inject transport callbacks. That's why this
+ * factory takes a `getWs` closure instead of a full SyncWebSocket: the WS
+ * doesn't exist when the executor is constructed (it's created later in
+ * `Ablo` during `BaseSyncedStore` init), so we resolve it
+ * lazily at commit time. Same trick Zero uses internally — see
+ * `packages/zero-client/src/client/zero.ts` where `Pusher`/`Puller` are
+ * constructed before the socket then wired up at connect time.
+ *
+     * `options.idempotencyKey` becomes the wire-level `clientTxId` when set,
+     * matching Stripe-style retry semantics. Otherwise the SDK generates one.
+     */
+export function createDefaultMutationExecutor(getWs) {
+    async function commit(operations, options) {
+        const ws = getWs();
+        if (!ws?.sendCommit) {
+            throw new AbloConnectionError('SyncWebSocket not ready for commit. The engine must finish bootstrap ' +
+                'before mutations can be sent.', { code: 'ws_not_ready' });
+        }
+        const clientTxId = options?.idempotencyKey ??
+            (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+                ? crypto.randomUUID()
+                : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
+        try {
+            return await ws.sendCommit(operations, clientTxId, undefined, // use sendCommit's built-in 15s default; no per-call override
+            options?.causedByTaskId, options?.reads);
+        }
+        catch (err) {
+            // Wrap transport-level failures as connection errors so the
+            // TransactionQueue's retry classifier treats them as transient
+            // (matches the old HTTP path's network-error handling).
+            if (err instanceof AbloError)
+                throw err;
+            if (err instanceof Error) {
+                if (/not connected|timed out|connection|ECONN/i.test(err.message)) {
+                    const wrapped = new AbloConnectionError(err.message, { cause: err });
+                    // Preserve any `diagnostics` snapshot the underlying SyncWebSocket
+                    // attached to the rejection. Without this, the wrapped error
+                    // bottoms out at "AbloConnectionError: not connected" with no
+                    // attribution to which close code / heartbeat trip / session
+                    // error caused it. See SyncWebSocket.notConnectedError().
+                    if (err &&
+                        typeof err === 'object' &&
+                        'diagnostics' in err &&
+                        err.diagnostics) {
+                        wrapped.diagnostics = err.diagnostics;
+                    }
+                    throw wrapped;
+                }
+            }
+            throw err;
+        }
+    }
+    return {
+        commit,
+        executeCreate: (model, id, input, _txId, options) => commit([{ type: 'CREATE', model: model.toLowerCase(), id, input }], options).then(() => { }),
+        executeUpdate: (model, id, data, _txId, options) => commit([{ type: 'UPDATE', model: model.toLowerCase(), id, input: data }], options),
+        executeDelete: (model, id, _txId, options) => commit([{ type: 'DELETE', model: model.toLowerCase(), id }], options).then(() => { }),
+        executeArchive: (model, id, _txId, options) => commit([{ type: 'ARCHIVE', model: model.toLowerCase(), id }], options).then(() => { }),
+        executeUnarchive: (model, id, _txId, options) => commit([{ type: 'UNARCHIVE', model: model.toLowerCase(), id }], options).then(() => { }),
+    };
+}

package/dist/context.js

@@ -52,7 +52,4 @@ const _fallback = {
         executeArchive: () => Promise.resolve(),
         executeUnarchive: () => Promise.resolve(),
     },
-    mutationDispatcher: {
-        dispatch: () => Promise.resolve(),
-    },
 };

package/dist/coordination/index.d.ts

@@ -2,5 +2,12 @@
  * `@abloatai/ablo/coordination` — the canonical wire schema for the three
  * coordination layers (presence, pessimistic claims, optimistic stale-context).
  * See `./schema.ts` for the model and the per-layer schemas.
+ *
+ * Explicit named list (not `export *`): every addition to schema.ts must be a
+ * deliberate export decision here, so new symbols don't silently become public
+ * API of the published package.
  */
-export * from './schema.js';
+export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
+export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../policy/types.js';
+export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';

package/dist/coordination/index.js

@@ -2,5 +2,28 @@
  * `@abloatai/ablo/coordination` — the canonical wire schema for the three
  * coordination layers (presence, pessimistic claims, optimistic stale-context).
  * See `./schema.ts` for the model and the per-layer schemas.
+ *
+ * Explicit named list (not `export *`): every addition to schema.ts must be a
+ * deliberate export decision here, so new symbols don't silently become public
+ * API of the published package.
  */
-export * from './schema.js';
+// Runtime schemas + helpers.
+export { 
+// Shared primitives
+targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, 
+// Layer 3 — optimistic stale-context
+onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, 
+// Layer 2 — pessimistic claim / claim-lease
+claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, 
+// Read interest — area-of-interest navigation
+updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, 
+// Commit operation — carries the optimistic write-guard
+commitOperationTypeSchema, commitOperationSchema, 
+// Layer 1 — presence
+presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
+// Conflict-policy runtime — the engine detects, the policy decides. Lives in
+// `../policy/types.js` (a dependency-free leaf: its only imports are types),
+// exported here so a server-side consumer reaches the coordination vocabulary
+// AND its default resolution through one leaf subpath instead of the root
+// barrel (which would evaluate the whole browser client stack in Node).
+export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';

package/dist/coordination/trace.d.ts

@@ -83,7 +83,6 @@ export declare class ClaimLog implements SyncObservabilityProvider {
     captureReconciliation(): void;
     captureDeltaRetryExhausted(): void;
     captureWebSocketError(): void;
-    captureOfflineFlushFailure(): void;
     captureSelfHealing(): void;
     captureCommitZeroSyncId(): void;
     startSpan<T>(_name: string, _op: string, fn: () => T): T;

package/dist/coordination/trace.js

@@ -135,7 +135,6 @@ export class ClaimLog {
     captureReconciliation() { }
     captureDeltaRetryExhausted() { }
     captureWebSocketError() { }
-    captureOfflineFlushFailure() { }
     captureSelfHealing() { }
     captureCommitZeroSyncId() { }
     startSpan(_name, _op, fn) {

package/dist/core/DatabaseManager.d.ts

@@ -25,7 +25,6 @@ export interface WorkspaceMetadata {
     updatedAt: Date;
     schemaHash?: string;
     syncGroups?: string[];
-    versions?: Record<string, number>;
 }
 /**
  * DatabaseManager - Manages Ablo's two-tier database architecture

package/dist/core/DatabaseManager.js

@@ -107,7 +107,7 @@ export class DatabaseManager {
             schemaHash,
             schemaVersion,
             userVersion,
-            createdAt: existingInfo?.createdAt || new Date(),
+            createdAt: existingInfo?.createdAt ?? new Date(),
             updatedAt: new Date(),
         };
     }
@@ -143,8 +143,8 @@ export class DatabaseManager {
             tx.oncomplete = () => {
                 resolve();
             };
-            tx.onerror = () => reject(tx.error);
-            request.onerror = () => reject(request.error);
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -157,8 +157,8 @@ export class DatabaseManager {
             const tx = this.metaDb.transaction(['databases'], 'readonly');
             const store = tx.objectStore('databases');
             const request = store.get(name);
-            request.onsuccess = () => resolve(request.result || null);
-            request.onerror = () => reject(request.error);
+            request.onsuccess = () => { resolve(request.result ?? null); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -172,8 +172,8 @@ export class DatabaseManager {
             const store = tx.objectStore('databases');
             const index = store.index('userId');
             const request = index.getAll(userId);
-            request.onsuccess = () => resolve(request.result || []);
-            request.onerror = () => reject(request.error);
+            request.onsuccess = () => { resolve(request.result || []); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -231,18 +231,20 @@ export class DatabaseManager {
                     return;
                 }
                 const meta = {
-                    lastSyncId: data.lastSyncId || 0,
-                    firstSyncId: data.firstSyncId || 0,
-                    backendDatabaseVersion: data.backendDatabaseVersion || 1,
-                    subscribedSyncGroups: data.subscribedSyncGroups || [],
+                    lastSyncId: data.lastSyncId ?? 0,
+                    firstSyncId: data.firstSyncId ?? 0,
+                    backendDatabaseVersion: data.backendDatabaseVersion ?? 1,
+                    subscribedSyncGroups: data.subscribedSyncGroups ?? [],
                     updatedAt: data.updatedAt ? new Date(data.updatedAt) : new Date(),
                     schemaHash: data.schemaHash,
                     syncGroups: data.syncGroups,
-                    versions: data.versions || undefined,
+                    // NOTE: old persisted records may still carry a `versions` key
+                    // (the removed per-entity version vector) — tolerated by simply
+                    // not picking it here.
                 };
                 resolve(meta);
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -253,9 +255,9 @@ export class DatabaseManager {
             const tx = db.transaction(['__meta'], 'readwrite');
             const store = tx.objectStore('__meta');
             const request = store.put(metadata, 'metadata');
-            tx.oncomplete = () => resolve();
-            tx.onerror = () => reject(tx.error);
-            request.onerror = () => reject(request.error);
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -270,7 +272,7 @@ export class DatabaseManager {
                 const data = request.result;
                 resolve(data?.persisted === true);
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -287,9 +289,9 @@ export class DatabaseManager {
                 updatedAt: new Date().toISOString(),
             };
             const request = store.put(persistenceData, modelName);
-            tx.oncomplete = () => resolve();
-            tx.onerror = () => reject(tx.error);
-            request.onerror = () => reject(request.error);
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -312,7 +314,7 @@ export class DatabaseManager {
                 }
                 resolve(states);
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**
@@ -362,10 +364,10 @@ export class DatabaseManager {
                 const schemaVersions = {};
                 for (const db of databases) {
                     // Count by user
-                    databasesByUser[db.userId] = (databasesByUser[db.userId] || 0) + 1;
+                    databasesByUser[db.userId] = (databasesByUser[db.userId] ?? 0) + 1;
                     // Count schema versions
                     const versionKey = `v${db.schemaVersion}`;
-                    schemaVersions[versionKey] = (schemaVersions[versionKey] || 0) + 1;
+                    schemaVersions[versionKey] = (schemaVersions[versionKey] ?? 0) + 1;
                 }
                 resolve({
                     metaDatabaseSize: databases.length,
@@ -374,7 +376,7 @@ export class DatabaseManager {
                     schemaVersions,
                 });
             };
-            request.onerror = () => reject(request.error);
+            request.onerror = () => { reject(request.error); };
         });
     }
     /**

package/dist/core/QueryProcessor.js

@@ -48,9 +48,8 @@ class BasicQueryCache {
             return;
         }
         // Fast path: Check if pattern is a simple model type match like ".*ModelType.*"
-        const simpleMatch = pattern.match(/^\.\*(\w+)\.\*$/);
-        if (simpleMatch) {
-            const modelType = simpleMatch[1];
+        const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
+        if (modelType !== undefined) {
             const keysToDelete = this.modelTypeIndex.get(modelType);
             if (keysToDelete) {
                 for (const key of keysToDelete) {
@@ -88,8 +87,9 @@ class BasicQueryCache {
      * Cache key format: "operation:ModelType:options"
      */
     extractModelType(key) {
-        const parts = key.split(':');
-        return parts.length >= 2 ? parts[1] : null;
+        // `?? null` is equivalent to the old length check: a missing second
+        // segment reads as undefined, and split never yields undefined otherwise.
+        return key.split(':')[1] ?? null;
     }
 }
 export class QueryProcessor {
@@ -229,9 +229,8 @@ export class QueryProcessor {
         this.cache.invalidate(pattern);
         // Also invalidate predicate result cache for this model type
         if (pattern) {
-            const simpleMatch = pattern.match(/^\.\*(\w+)\.\*$/);
-            if (simpleMatch) {
-                const modelType = simpleMatch[1];
+            const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
+            if (modelType !== undefined) {
                 for (const key of this.predicateResultCache.keys()) {
                     if (key.includes(modelType)) {
                         this.predicateResultCache.delete(key);

package/dist/core/QueryView.d.ts

@@ -9,10 +9,22 @@
  * directly and receive granular updates (splice/push, never replacement).
  */
 import { type IObservableArray } from 'mobx';
+import { type Model } from '../Model.js';
 import { ModelScope } from '../types/index.js';
-import type { ObjectPool } from '../ObjectPool.js';
 import type { ViewRegistry } from './ViewRegistry.js';
 import type { IncrementalView } from './query-utils.js';
+/**
+ * The slice of `ObjectPool` a QueryView reads — a minimal structural
+ * interface (LogFoldContext-style) instead of the concrete class, so this
+ * module never imports `../ObjectPool.js` back (ObjectPool imports QueryView
+ * at runtime for `createView()`; the reverse edge was the last core-layer
+ * import cycle). `ObjectPool` satisfies it structurally.
+ */
+export interface QueryViewPool {
+    hasForeignKeyIndex(typename: string, fieldName: string): boolean;
+    getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
+    getByTypeName(modelName: string, scope?: ModelScope): Model[];
+}
 export interface QueryViewOptions<T> {
     where?: Partial<T>;
     filter?: (entity: T) => boolean;
@@ -47,7 +59,7 @@ export declare class QueryView<T extends Record<string, unknown>> implements Inc
     private readonly fkField;
     private readonly fkValue;
     private disposed;
-    constructor(typename: string, pool: ObjectPool, registry: ViewRegistry, options?: QueryViewOptions<T>);
+    constructor(typename: string, pool: QueryViewPool, registry: ViewRegistry, options?: QueryViewOptions<T>);
     private initialScan;
     handleAdded(model: Record<string, unknown>): void;
     handleUpdated(model: Record<string, unknown>): void;

package/dist/core/QueryView.js

@@ -54,10 +54,9 @@ export class QueryView {
         // Check for FK-index optimization: single-field where with an indexed FK
         this.fkField = null;
         this.fkValue = null;
-        if (this.whereEntries &&
-            this.whereEntries.length === 1 &&
-            typeof this.whereEntries[0][1] === 'string') {
-            const [field, value] = this.whereEntries[0];
+        const soleWhereEntry = this.whereEntries && this.whereEntries.length === 1 ? this.whereEntries[0] : undefined;
+        if (soleWhereEntry && typeof soleWhereEntry[1] === 'string') {
+            const [field, value] = soleWhereEntry;
             if (pool.hasForeignKeyIndex(typename, field)) {
                 this.fkField = field;
                 this.fkValue = value;
@@ -120,7 +119,7 @@ export class QueryView {
         if (this.disposed)
             return;
         const entity = model;
-        const id = entity['id'];
+        const id = entity.id;
         const idx = id !== undefined ? this.findIndexById(id) : -1;
         const matchesNow = this.matchesFilter(entity);
         runInAction(() => {

package/dist/core/StoreManager.d.ts

@@ -120,12 +120,12 @@ export declare class StoreManager {
             notReady: number;
         };
         totalRecords: number;
-        storeDetails: Array<{
+        storeDetails: {
             modelName: string;
             storeName: string;
             strategy: LoadStrategy;
             ready: boolean;
             count: number;
-        }>;
+        }[];
     }>;
 }

package/dist/core/StoreManager.js

@@ -5,6 +5,7 @@
  * Creates appropriate store types based on model load strategies.
  * Follows Linear's architecture with 80+ ObjectStore instances.
  */
+import { ModelRegistry } from '../ModelRegistry.js';
 import { ObjectStore } from '../stores/ObjectStore.js';
 import { SyncActionStore } from '../stores/SyncActionStore.js';
 import { LoadStrategy } from '../types/index.js';
@@ -198,7 +199,10 @@ export class StoreManager {
         // Sample a few stores — don't check all 30+ if the first one has data
         const samplesToCheck = Math.min(storeEntries.length, 3);
         for (let i = 0; i < samplesToCheck; i++) {
-            const [, store] = storeEntries[i];
+            const entry = storeEntries[i];
+            if (!entry)
+                break;
+            const [, store] = entry;
             try {
                 const count = await store.count();
                 if (count > 0)

package/dist/core/index.d.ts

@@ -20,7 +20,7 @@ export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyRef
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
 export { postQuery, type PostQueryOptions } from '../query/client.js';
 export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
-export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
+export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
 export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
 export { BootstrapHelper } from '../sync/BootstrapHelper.js';
 export { createClaimStream, type AttachableClaimStream, type ClaimStreamConfig, } from '../sync/createClaimStream.js';

package/dist/core/openIDBWithTimeout.js

@@ -95,23 +95,27 @@ export function openIDBWithTimeout(name, version, options = {}) {
                     // A consumer reaction must never break the close.
                 }
             };
-            settle(() => resolve(db));
+            settle(() => { resolve(db); });
         };
-        request.onerror = () => settle(() => reject(request.error));
+        request.onerror = () => { settle(() => { reject(request.error); }); };
         // The critical handler: another tab is blocking us. Native API leaves
         // the request pending indefinitely; we fail fast with a clear error so
         // the UI can tell the user to close other tabs.
         request.onblocked = () => {
-            settle(() => reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
-                `older version. Close other Ablo tabs and reload.`)));
+            settle(() => {
+                reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
+                    `older version. Close other Ablo tabs and reload.`));
+            });
         };
         // Catch-all timeout: even without `onblocked`, some browsers in some
         // storage states hang without firing any event. Bounded wait →
         // deterministic error.
         const timer = setTimeout(() => {
-            settle(() => reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
-                `Storage may be in a bad state — clearing site data and reloading ` +
-                `usually fixes this.`)));
+            settle(() => {
+                reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
+                    `Storage may be in a bad state — clearing site data and reloading ` +
+                    `usually fixes this.`));
+            });
         }, timeoutMs);
     });
 }
@@ -142,9 +146,9 @@ export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
             resolve(value);
         };
         const request = indexedDB.deleteDatabase(name);
-        request.onsuccess = () => settle(true);
-        request.onerror = () => settle(false);
-        request.onblocked = () => settle(false);
-        const timer = setTimeout(() => settle(false), timeoutMs);
+        request.onsuccess = () => { settle(true); };
+        request.onerror = () => { settle(false); };
+        request.onblocked = () => { settle(false); };
+        const timer = setTimeout(() => { settle(false); }, timeoutMs);
     });
 }

package/dist/core/query-utils.js

@@ -52,7 +52,7 @@ export function matchesWhere(entity, where) {
  */
 export function findIndexById(arr, id) {
     for (let i = 0; i < arr.length; i++) {
-        if (arr[i]['id'] === id)
+        if (arr[i]?.id === id)
             return i;
     }
     return -1;

package/dist/core/storeContract.d.ts

@@ -0,0 +1,143 @@
+/**
+ * storeContract — the framework-neutral store contract.
+ *
+ * `SyncStoreContract` is the minimal store interface the SDK's hooks and
+ * mutators program against; `BaseSyncedStore` is the concrete engine class
+ * that implements it. The contract used to live in `react/context.ts`, which
+ * meant the CORE store layer imported its own contract from the React
+ * adapter (a module that runtime-imports 'react') — an L2-core →
+ * react-integration inversion and a module cycle. It now lives here, in a
+ * dependency-free core leaf: `react/context.ts` re-exports these types so
+ * React consumers are unchanged, and the core layer never touches 'react'.
+ *
+ * Everything in this module is type-only — no runtime imports, no runtime
+ * exports beyond erased interfaces.
+ */
+import type { Model } from '../Model.js';
+import type { ModelScope } from '../types/index.js';
+import type { QueryView, QueryViewOptions } from './QueryView.js';
+import type { ViewRegistry } from './ViewRegistry.js';
+import type { ParticipantScope } from '../sync/participants.js';
+/** Sync status for UI binding */
+export interface SyncStatus {
+    state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
+    progress: number;
+    error?: Error;
+    /** When true, the error is a session/auth error requiring re-authentication. */
+    isSessionError: boolean;
+    lastSyncAt?: Date;
+    pendingChanges: number;
+    offlineSince?: Date;
+}
+/**
+ * A single LOCAL mutation as observed off the commit stream — the substrate
+ * the undo system records from. One is emitted per local create/update/
+ * delete/archive (remote/collaborator deltas never appear here: they apply
+ * through a separate pool path that doesn't queue mutations). `previousData`
+ * holds the pre-edit field values (captured from the model's
+ * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
+ * derivable from the event alone — no separate snapshot pass.
+ *
+ * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
+ * doc and Liveblocks' `room.history` records room ops: undo listens to the
+ * one place all local writes converge, rather than wrapping the write call.
+ */
+export interface LocalMutation {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
+    modelName: string;
+    modelId: string;
+    /** New field values (create/update). */
+    data?: Record<string, unknown> | null;
+    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
+    previousData?: Record<string, unknown> | null;
+}
+/**
+ * Minimal store interface that the SDK hooks need.
+ * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
+ */
+export interface SyncStoreContract {
+    /**
+     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
+     * recording. Optional so minimal test doubles can omit it — when absent,
+     * undo scopes simply record nothing. The concrete store
+     * (`BaseSyncedStore`) wires this to the TransactionQueue's
+     * `transaction:created` event. Returns an unsubscribe function.
+     */
+    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
+    retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
+    queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
+        predicate?: (model: Model) => boolean;
+        scope?: ModelScope;
+        orderBy?: keyof Model;
+        order?: 'asc' | 'desc';
+        limit?: number;
+        offset?: number;
+    }): {
+        data: Model[];
+    };
+    /**
+     * Save (create or update) one entity. Calling `save` in a tight loop
+     * produces a single wire commit with one `batchIndex`: the SyncClient
+     * debounces IDB persistence and the server push to one microtask, and
+     * TransactionQueue coalesces every transaction staged in the tick into
+     * one batch. There is intentionally no `saveMany` — Zero, Replicache,
+     * and the rest of the local-first lineage all expose one-row writes
+     * and rely on the implicit tick boundary.
+     *
+     * `skipValidation` exists for trusted bulk paths (AI sandbox layer
+     * generation, PPTX import, hydration) where the producer has already
+     * type-checked and per-row Zod is a measurable cost.
+     */
+    save(model: Model, options?: {
+        skipValidation?: boolean;
+    }): Promise<void>;
+    delete(model: Model): Promise<void>;
+    archive(model: Model): Promise<void>;
+    unarchive(model: Model): Promise<void>;
+    /** The ObjectPool — for entity/collection lookups by ID or typename. */
+    pool: {
+        get(id: string): Model | undefined;
+        getByTypeName(typename: string, scope?: ModelScope): Model[];
+        getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
+        createFromData(data: Record<string, unknown>): Model | null;
+        hasForeignKeyIndex(typename: string, fieldName: string): boolean;
+        createView<T extends Record<string, unknown>>(typename: string, options?: QueryViewOptions<T>): QueryView<T>;
+        viewRegistry: ViewRegistry;
+    };
+    /**
+     * Reactive sync-status getters. Powered by MobX `computed` inside
+     * `BaseSyncedStore`, so they're safe to read in `observer` components
+     * and inside `reaction(() => store.isReady, ...)`. Consumers that
+     * don't want to touch MobX should prefer the `useSyncStatus()` hook.
+     */
+    readonly isReady: boolean;
+    readonly isSyncing: boolean;
+    readonly isOffline: boolean;
+    readonly isReconnecting: boolean;
+    readonly isError: boolean;
+    readonly hasUnsyncedChanges: boolean;
+    /**
+     * Area-of-interest (dynamic read subscription). `enterScope`/`leaveScope`
+     * move the connection's read interest as the user navigates (open/close a
+     * deck, sheet, doc); `pinScope`/`unpinScope` express prominence (an active
+     * claim keeps a group subscribed). Each resolves the scope through the same
+     * resolver the claim path uses, so read interest and write claims agree on
+     * the sync-group string. Optional so minimal test doubles can omit them;
+     * no-ops before the socket exists. The concrete store (`BaseSyncedStore`)
+     * forwards to its `AreaOfInterestManager`.
+     */
+    enterScope?(scope: ParticipantScope, opts?: {
+        hydrate?: boolean;
+    }): Promise<void>;
+    leaveScope?(scope: ParticipantScope): Promise<void>;
+    pinScope?(scope: ParticipantScope): Promise<void>;
+    unpinScope?(scope: ParticipantScope): Promise<void>;
+    /**
+     * Raw MobX-observable `SyncStatus` record. `useSyncStatus()` reads
+     * `state`, `progress`, `pendingChanges`, `isSessionError`, `error`
+     * from this to build its tagged union. Exposed on the contract so
+     * consumer-facing hooks and test doubles can manipulate it directly.
+     */
+    readonly syncStatus: SyncStatus;
+}