@abloatai/ablo 0.3.0

package/dist/BaseSyncedStore.d.ts

@@ -0,0 +1,709 @@
+/**
+ * BaseSyncedStore — Generic sync store base class for the SDK.
+ *
+ * Exports the core types, interfaces, and a base class that app-specific
+ * stores extend. The base class provides query/mutation/delta/bootstrap
+ * orchestration. Subclasses add domain-specific lazy-loading, collaboration
+ * events, and model enrichment.
+ *
+ * Design: The app's SyncedStore extends this and adds its own methods.
+ * This file only contains types and the abstract contract — the actual
+ * implementation stays in the app's SyncedStore.ts until we incrementally
+ * pull generic methods into this base class.
+ */
+import { ConnectionManager } from './sync/ConnectionManager.js';
+import type { SyncClient } from './SyncClient.js';
+import type { Database, BootstrapResult } from './Database.js';
+import type { ObjectPool } from './ObjectPool.js';
+import { ModelRegistry } from './ModelRegistry.js';
+import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type VersionVector, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdateEvent, type EventMap, type DefaultCollaborationEvents } from './sync/SyncWebSocket.js';
+import { QueryProcessor } from './core/QueryProcessor.js';
+import { Model } from './Model.js';
+import { ModelScope } from './ObjectPool.js';
+import type { Schema } from './schema/schema.js';
+import { type ReaderActions } from './react/useReader.js';
+/** Constructor type for Model subclasses (accepts abstract classes) */
+export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
+/** Concrete constructor type for instantiation */
+export type ConcreteModelConstructor<T extends Model> = new (data?: any) => T;
+/** Generic record type for model data */
+export type ModelData = Record<string, unknown>;
+/** Query result interface */
+export interface QueryResult<T extends Model> {
+    data: T[];
+    total: number;
+    hasMore: boolean;
+    fromCache?: boolean;
+}
+/** A foreign-key index to register on the ObjectPool at construction time. */
+export interface ForeignKeyIndexSpec {
+    /**
+     * The child model name (where the FK field lives) — this is the type
+     * that will be passed to `pool.registerForeignKey(modelName, fieldName)`
+     * and later to `pool.getByForeignKey(modelName, fieldName, value)`.
+     *
+     * Use the wire `__typename` casing (e.g., `'SlideLayer'`, not
+     * `'slideLayer'`) — that's the value `createFromData` stamps onto
+     * models and the pool indexes by.
+     */
+    readonly modelName: string;
+    /** The FK field name on the child model, e.g. `'slideId'`. */
+    readonly fieldName: string;
+}
+/**
+ * A declarative enrichment rule for the delta-apply path.
+ *
+ * When a delta for `modelName` arrives, after the model is constructed
+ * the base store reads `data[foreignKey]` from the payload, looks up
+ * the matching parent in the ObjectPool, and attaches it as
+ * `data[relationKey]`. Best-effort: if the parent isn't yet in the
+ * pool (e.g., arrived later in the same bootstrap batch), enrichment
+ * silently no-ops.
+ *
+ * Replaces the previous pattern of overriding `enrichRelations` on a
+ * subclass to hardcode per-model enrichment logic.
+ */
+export interface EnrichmentPlanEntry {
+    /** The child model whose incoming deltas should be enriched. */
+    readonly modelName: string;
+    /** The FK field on the child that points at the parent's id. */
+    readonly foreignKey: string;
+    /** The property name under which to attach the parent model. */
+    readonly relationKey: string;
+}
+/** Configuration for SyncedStore behavior */
+export interface SyncedStoreConfig {
+    enableOffline?: boolean;
+    enableCache?: boolean;
+    enableTelemetry?: boolean;
+    /**
+     * Initial version vector keys, each seeded to 0. Merged with the
+     * schema-derived set (if a schema is provided to the constructor) —
+     * explicit keys here layer on top of derived ones. Replaces the
+     * subclass pattern of hardcoding `this.versionVector = { tasks: 0, ... }`
+     * in the constructor.
+     */
+    versionVectorKeys?: readonly string[];
+    /**
+     * Declarative enrichment plan consumed by `enrichRelations`. Replaces
+     * the subclass override of `enrichRelations` for per-model parent
+     * attachment. Merged with schema-derived entries (relations marked
+     * `{ enrich: true }` on `belongsTo`).
+     */
+    enrichmentPlan?: readonly EnrichmentPlanEntry[];
+    /**
+     * Foreign-key indexes to register on the ObjectPool at construction
+     * time. Replaces the subclass override of `registerForeignKeys` for
+     * per-model FK registration. Merged with schema-derived entries
+     * (relations marked `{ index: true }` on `belongsTo`). Both sets
+     * are registered before the legacy `registerForeignKeys()` hook
+     * fires, so subclasses can still add more on top.
+     */
+    foreignKeyIndexes?: readonly ForeignKeyIndexSpec[];
+}
+/** 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;
+}
+/** User context for initialization */
+export interface UserContext {
+    userId: string;
+    organizationId: string;
+    role?: string;
+    teamIds?: string[];
+    /** Participant kind on the wire. Default 'user' for browser
+     *  sessions; 'agent' for headless bots / worker processes. The
+     *  store routes this to SyncWebSocket so the WS URL carries
+     *  `kind=agent` and the server applies capability-token auth. */
+    kind?: 'user' | 'agent' | 'system';
+    /** Biscuit capability token for `kind: 'agent'`. Sent as
+     *  `?authorization=Bearer <token>` on the WS upgrade. */
+    capabilityToken?: string;
+    /** Server-authoritative sync groups, supplied by auth/capability
+     *  exchange. The SDK does not invent org/user/default groups; app
+     *  structure comes from schema-declared scopes and server-issued
+     *  authorization. */
+    syncGroups?: readonly string[];
+    /**
+     * How aggressively this participant should pull baseline state at
+     * startup.
+     *
+     *  - `'full'` (default): pull every delta in scope before `ready()`
+     *    resolves. The standard browser/user replica behavior.
+     *  - `'none'`: open the WebSocket and process live deltas only.
+     *    Reads go through `resource.retrieve()` / filtered subscriptions
+     *    backfilled by `Covering` deltas. Suitable for transactional
+     *    participants — agent-worker, video-pipeline, routine runners —
+     *    that don't need a local replica of the org's tenant plane.
+     */
+    bootstrapMode?: 'full' | 'none';
+}
+/** Smart sync options */
+export interface SmartSyncOptions {
+    maxDeltasBeforeBootstrap?: number;
+    maxBootstrapSize?: number;
+    batchingDelay?: number;
+    maxBatchSize?: number;
+}
+/** Rehydration statistics from bootstrap */
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+/** Bootstrap timeout configuration */
+export declare const BOOTSTRAP_CONFIG: {
+    readonly OVERALL_TIMEOUT_MS: 15000;
+    readonly MAX_RETRY_ATTEMPTS: 3;
+    readonly RETRY_DELAY_MS: 500;
+};
+export { ModelScope };
+export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, VersionVector, BootstrapHint, BootstrapDataEvent, PresenceUpdateEvent, };
+/**
+ * BaseSyncedStore — abstract base for app-specific sync stores.
+ *
+ * Provides the dependency structure, observable status, and protected
+ * accessors that subclasses use. The actual sync orchestration (initialize,
+ * delta processing, bootstrap, query, save, delete, etc.) lives in the
+ * app's concrete subclass for now — methods will be pulled up into this
+ * base class incrementally as they are genericized.
+ *
+ * Subclasses MUST call `super(dependencies, config)` and then set up
+ * their own MobX observables.
+ *
+ * Generic over `TCollaboration` — an app-defined event map for real-time
+ * collaboration events (cursors, selections, presence beyond the core set).
+ * Subclasses pass their own event map to get typed `subscribe()` calls on
+ * the underlying SyncWebSocket without casts:
+ *
+ * @example
+ *   interface AbloEvents {
+ *     'sheet:selection': [SheetSelectionEvent];
+ *     'slide:cursor':    [SlideCursorEvent];
+ *   }
+ *   class SyncedStore extends BaseSyncedStore<AbloEvents> {
+ *     subscribeToSlideCursor(handler: (e: SlideCursorEvent) => void) {
+ *       return this.syncWebSocket?.subscribe('slide:cursor', handler);
+ *     }
+ *   }
+ */
+/**
+ * Walk a schema and derive the three sync-plan arrays consumed by
+ * `BaseSyncedStore`'s constructor: version-vector keys, FK indexes to
+ * register on the pool, and the enrichment plan.
+ *
+ * Version vector keys are derived from each model's `typename` (lowercased
+ * to match the server's event-type convention — `'Task'` → `'task'`,
+ * `'SlideLayer'` → `'slidelayer'`). A fallback to the schema key applies
+ * when `typename` is unset, though `defineSchema()` now always resolves
+ * it during assembly so the fallback is defensive-only.
+ *
+ * FK indexes and enrichment entries are pulled from each `belongsTo`
+ * relation where `options.index` / `options.enrich` is set. Relations
+ * without those options are skipped — this is an opt-in mechanism so
+ * adding a `belongsTo` never silently changes delta or lookup semantics.
+ *
+ * Pure function: takes a Schema, returns three arrays. No side effects,
+ * no class state. Called once at construction time from `BaseSyncedStore`.
+ */
+export declare function deriveSyncPlanFromSchema(schema: Schema): {
+    versionVectorKeys: string[];
+    enrichmentPlan: EnrichmentPlanEntry[];
+    foreignKeyIndexes: ForeignKeyIndexSpec[];
+};
+/**
+ * Schema-derived accessor namespace exposed on `store.query`. Each key is
+ * a model name from the schema and resolves to a `ReaderActions<S, K>`
+ * with `findById` / `findMany` / `findFirst` / `count`. Return types are
+ * inferred from the schema (`InferModel<S, K>`) so callers don't need to
+ * cast or pass class constructors.
+ *
+ * Prisma / Drizzle / Zero all use this shape: `store.query.<modelKey>.*`.
+ */
+export type QueryNamespace<S extends Schema> = {
+    readonly [K in keyof S['models'] & string]: ReaderActions<S, K>;
+};
+export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents, TSchema extends Schema = Schema> {
+    syncStatus: SyncStatus;
+    protected readonly syncClient: SyncClient;
+    protected readonly database: Database;
+    protected readonly objectPool: ObjectPool;
+    protected readonly modelRegistry: ModelRegistry;
+    /**
+     * Schema the store was constructed with. Persisted so the `query`
+     * accessor namespace can build typed per-model reader actions lazily
+     * without callers having to pass the schema at every lookup site.
+     */
+    protected readonly schema?: TSchema;
+    /** Lazily-built `query.<modelKey>.*` accessor namespace. */
+    private _queryProxy?;
+    protected syncWebSocket: SyncWebSocket<TCollaboration> | null;
+    private _syncServerUrl?;
+    /**
+     * Public accessor for the underlying SyncWebSocket. Used by the
+     * factory in `createSyncEngine` to wire the default mutation
+     * executor — the executor needs the WS handle to send commit
+     * frames, and the factory can't reach `protected` state through
+     * normal typing. Returns null until WS is initialized during
+     * `initialize()`.
+     */
+    getSyncWebSocket(): SyncWebSocket<TCollaboration> | null;
+    protected readonly queryProcessor: QueryProcessor;
+    /**
+     * Runtime behavior flags only — the three schema/config arrays
+     * (`versionVectorKeys`, `enrichmentPlan`, `foreignKeyIndexes`) are
+     * consumed at construction time and stored on the instance as
+     * `versionVector`, `enrichmentPlan`, and pool-registered indexes.
+     * They don't need to persist on `this.config`.
+     */
+    protected readonly config: Required<Pick<SyncedStoreConfig, 'enableOffline' | 'enableCache' | 'enableTelemetry'>>;
+    protected disposers: Array<() => void>;
+    protected initialized: boolean;
+    protected dataReady: boolean;
+    protected userContext: UserContext | null;
+    protected versionVector: VersionVector;
+    /**
+     * Declarative enrichment plan: "for model X, when a delta arrives,
+     * read data[foreignKey] and attach the matching parent from the pool
+     * as data[relationKey]." Merged from schema-derived + config at
+     * construction time. Replaces the `enrichRelations` subclass override
+     * pattern.
+     */
+    protected enrichmentPlan: readonly EnrichmentPlanEntry[];
+    protected smartSyncOptions: Required<SmartSyncOptions>;
+    protected pendingDeltas: SyncDelta[];
+    protected batchTimer: ReturnType<typeof setTimeout> | null;
+    protected syncPromise: Promise<void> | null;
+    protected lastAckedId: number;
+    protected highestProcessedSyncId: number;
+    protected bootstrapDeltaQueue: SyncDelta[] | null;
+    protected activeBootstrapCount: number;
+    protected pendingDeletes: Set<string>;
+    protected modelTypesHydrated: Set<string>;
+    protected modelTypeHydrationInFlight: Map<string, Promise<void>>;
+    constructor(dependencies: {
+        syncClient: SyncClient;
+        database: Database;
+        objectPool: ObjectPool;
+        modelRegistry: ModelRegistry;
+        /**
+         * Optional schema. When provided, `deriveSyncPlanFromSchema` walks
+         * the schema's models + relations to auto-populate version vector
+         * keys, FK indexes, and the enrichment plan from declarative
+         * annotations. Class-based subclass users (like Ablo's legacy
+         * SyncedStore) typically pass explicit `config.versionVectorKeys`
+         * / `config.foreignKeyIndexes` / `config.enrichmentPlan` instead.
+         */
+        schema?: TSchema;
+        /** Sync server URL for WebSocket connection. Converted to wss:// automatically. */
+        url?: string;
+    }, config?: SyncedStoreConfig);
+    /**
+     * Register foreign key indexes for O(1) lookups.
+     *
+     * Legacy override hook — in Phase 2 the preferred way to declare FK
+     * indexes is via `config.foreignKeyIndexes` at construction time, or
+     * by marking the `belongsTo` relation with `{ index: true }` in the
+     * schema. This hook still fires AFTER the schema-derived + config
+     * registrations, so subclasses can layer additional FKs on top.
+     */
+    protected registerForeignKeys(): void;
+    /**
+     * Enrich delta data with related models from the ObjectPool.
+     *
+     * Base implementation walks `this.enrichmentPlan` — entries populated
+     * from the schema's `{ enrich: true }` relations and from
+     * `config.enrichmentPlan`. Subclasses can still override for bespoke
+     * logic, calling `super.enrichRelations(modelName, data)` first to
+     * apply the declarative plan before layering on custom work.
+     *
+     * Enrichment is best-effort: if the parent isn't yet in the pool
+     * (e.g., a child delta arrives before its parent in a bootstrap
+     * batch), the entry is silently skipped and the data passes through
+     * untouched. The next delta for the same child will re-enrich.
+     */
+    protected enrichRelations(modelName: string, data: ModelData): ModelData;
+    /** Check if a model name represents a custom/dynamic entity type. */
+    protected isCustomEntity(modelName: string): boolean;
+    /** Create a custom entity instance from delta data. Override for domain-specific custom entities. */
+    protected createCustomEntity(_modelName: string, _modelId: string, _data: Record<string, unknown>): Model | null;
+    /** Called before save for domain-specific validation/self-healing. */
+    protected beforeSave(_model: Model): void;
+    /** Connection lifecycle event callback — set by subclass to wire connection state machine. */
+    protected onConnectionEvent?: (event: string) => void;
+    /**
+     * Internal connection FSM. Owns network probe + backoff + reconnect
+     * orchestration for the default path. Constructed lazily once we
+     * have a user context + a WebSocket (see `wireWebSocketEvents`);
+     * driven by the `onConnectionEvent` hook AND browser online/offline
+     * events it sets up itself.
+     *
+     * Every consumer gets production-grade offline-to-online recovery
+     * out of the box. Subclasses that want their own lifecycle owner
+     * can disable this by overriding `createConnectionManager()` to
+     * return null.
+     */
+    protected connectionManager: import('./sync/ConnectionManager.js').ConnectionManager | null;
+    /**
+     * Listeners registered via `subscribeSessionError()`. Fired when the
+     * WebSocket closes with a session-invalid code (1008/4001/4003) or a
+     * session-error event is received. Separate from `onConnectionEvent`
+     * (which exists for the ConnectionStore FSM) so multiple consumers —
+     * typically `<AbloProvider>` and a connection-lifecycle owner — can
+     * both react without racing on the single-callback slot.
+     */
+    protected sessionErrorListeners: Set<(error: Error) => void>;
+    /**
+     * Subscribe to session-error events. The returned function removes
+     * the listener. Safe to call multiple times from different consumers
+     * (each gets its own slot in the listener set).
+     */
+    subscribeSessionError(listener: (error: Error) => void): () => void;
+    /**
+     * Subscribe to per-mutation failure payloads. Forwarded from the
+     * underlying `SyncClient.transactionQueue` so consumers (toast layer,
+     * route-level reverted boundaries, telemetry) can react without
+     * reaching across the store. Returns an unsubscribe function.
+     *
+     * Why this lives on the base store rather than SyncClient: the React
+     * `<AbloProvider>` binds against this surface, so adding it here
+     * keeps the engine's internal wiring private while still giving the
+     * SDK a single hook to expose. Mirrors `subscribeSessionError` —
+     * same shape, same lifecycle.
+     */
+    subscribeMutationFailure(listener: (payload: {
+        transaction: import('./transactions/TransactionQueue.js').Transaction;
+        error: Error;
+        permanent?: boolean;
+    }) => void): () => void;
+    /**
+     * Wait for the in-flight transaction for (modelName, modelId) to be
+     * confirmed by the server. See `SyncClient.waitForConfirmation` for the
+     * lookup contract; resolves immediately if nothing is in flight.
+     */
+    waitForConfirmation(modelName: string, modelId: string): Promise<void>;
+    /**
+     * Execute a bootstrap function with timeout protection and automatic retry.
+     * Prevents the common issue where bootstrap hangs on startup.
+     */
+    protected executeBootstrapWithTimeout<T>(bootstrapFn: () => Promise<T>, _context: UserContext, signal?: AbortSignal): Promise<T>;
+    /** Create a timeout promise for bootstrap attempts */
+    protected createBootstrapTimeout(attempt: number): Promise<never>;
+    /** Reset bootstrap-related state for a clean retry */
+    protected resetBootstrapState(): void;
+    /** Perform reconnect: bootstrap + WS reconnect. Returns outcome for state machine. */
+    performReconnect(): Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Handle an actionType 'G' delta.
+     *
+     * The server emits 'G' via two distinct pathways, distinguished by payload
+     * shape:
+     *
+     *   Incremental (EmitGroupAdded):   { group, userId }
+     *     - The recipient was added to a single sync group.
+     *     - Subsequent 'C' (Covering) deltas deliver each newly-visible entity.
+     *     - No re-bootstrap — entities arrive via the normal insert path.
+     *
+     *   Legacy (EmitGroupChange):       { addedGroups, removedGroups }
+     *     - Single delta carrying the full group membership diff.
+     *     - Forces a full re-bootstrap (disconnect + reconnect + fetch all).
+     *     - Deprecated on the server; kept here for wire-level backward compat.
+     */
+    protected handleSyncGroupChange(delta: SyncDelta): Promise<void>;
+    /**
+     * Handle an incremental GroupAdded delta.
+     *
+     * Adds the new group to the subscription metadata without triggering a
+     * re-bootstrap. The server will follow up with 'C' (Covering) deltas for
+     * each newly-visible entity, which flow through the normal insert path.
+     */
+    protected handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
+    /**
+     * Handle an actionType 'S' (GroupRemoved) delta.
+     *
+     * Signals that the recipient has lost access to a sync group. Because
+     * the client does not track per-entity group membership, we can't
+     * selectively purge entities belonging to that group. The safe fallback
+     * is the legacy behavior: clear local state and force a re-bootstrap
+     * with the updated group list.
+     *
+     * Future optimization: track group membership in the ObjectPool so 'S'
+     * can do a targeted purge instead of a full re-bootstrap.
+     */
+    protected handleGroupRemoved(delta: SyncDelta): Promise<void>;
+    /** Compute new sync groups after applying additions and removals */
+    protected computeUpdatedSyncGroups(payload: SyncGroupChangePayload): string[];
+    /** Force a full re-bootstrap via connection lifecycle event.
+     *
+     * No-op for `bootstrapMode: 'none'` participants — they never pull
+     * baseline state, so a "force re-bootstrap" trigger (sync-group
+     * shrink, scope revocation) instead just flushes the local pool and
+     * relies on covering deltas to repopulate the data they actually
+     * subscribe to.
+     */
+    protected forceFullRebootstrap(): void;
+    /**
+     * Single source of truth for the sync-group list this session is
+     * subscribed to. Server-issued (`context.syncGroups`) is authoritative.
+     * When absent, the SDK subscribes to no explicit groups. Both
+     * `checkSyncGroupShrinkage` and `setupWebSocketSync` resolve through
+     * here so the WS subscription and the security-critical shrinkage
+     * check can never disagree.
+     */
+    protected resolveSyncGroups(context: UserContext): readonly string[];
+    /** Check if sync groups shrank since last session — force full bootstrap if so */
+    protected checkSyncGroupShrinkage(): Promise<void>;
+    /** Apply bootstrap data to the ObjectPool with ghost removal */
+    /** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+    protected applyBootstrapToPool(bootstrapResult: BootstrapResult, protectedIds?: ReadonlySet<string>): RehydrationStats;
+    /**
+     * Initialize the sync engine with user context.
+     * Offline-first: hydrate from IDB → show UI → bootstrap from server in background.
+     */
+    initialize(context: UserContext, signal?: AbortSignal): Generator<Promise<unknown>, {
+        success: boolean;
+        error?: Error;
+    }, unknown>;
+    /** Background bootstrap — non-blocking, user sees cached data while this runs */
+    protected performBackgroundBootstrap(requirements: Awaited<ReturnType<typeof this.database.requiredBootstrap>>, context: UserContext, signal?: AbortSignal): Promise<void>;
+    /** Run bootstrap with delta queuing to prevent race conditions */
+    protected withDeltaQueuing<T>(fn: () => Promise<T>): Promise<T>;
+    /** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
+    protected collectDeltaProtectedIds(preBootstrapIds: ReadonlySet<string>): Set<string>;
+    /** Replay deltas queued during bootstrap */
+    protected replayQueuedDeltas(): void;
+    /**
+     * Factory for the internal `ConnectionManager`. Override to return
+     * `null` in subclasses that own their own connection lifecycle
+     * (tests, headless runners, custom FSM wrappers). Default builds a
+     * manager scoped to `_syncServerUrl` with production backoff.
+     *
+     * **Agent participants get `null`.** The FSM is wired around browser
+     * events (`visibilitychange`, `online`/`offline`, watchdog) which are
+     * meaningful for human-facing tabs and meaningless for headless agent
+     * processes. On agent hosts the FSM has no event source to drive
+     * recovery — and worse, its `offline` entry action calls
+     * `syncWebSocket.disconnect()` which sets `isManualClose=true` and
+     * cancels the reconnect that `SyncWebSocket.onclose` had just
+     * scheduled. The two recovery systems fight and the browser-only one
+     * wins by destroying the Node-compatible one's work. Returning `null`
+     * for agents leaves `SyncWebSocket`'s exponential-backoff
+     * `scheduleReconnect()` as the sole recovery path — which is correct
+     * for server-side agents whether they run on Node, Bun, Deno, or
+     * inside a Docker container with no `window`.
+     *
+     * Why gate on `kind` and not `typeof window`: env detection by global
+     * existence is fragile (SSR polyfills, jsdom, sandboxed hosts). The
+     * participant kind is the actual semantic axis — "is this a human-
+     * driven session" vs "is this a server agent". The latter never has
+     * a tab to lose focus or a network adapter to wake up.
+     */
+    protected createConnectionManager(kind?: 'user' | 'agent' | 'system'): ConnectionManager | null;
+    /** Disconnect and clean up all resources */
+    disconnect(): Promise<void>;
+    /**
+     * Destroy every IndexedDB database owned by the sync engine.
+     *
+     * First disconnects (releases WebSocket + timers + in-memory caches),
+     * then walks `indexedDB.databases()` and deletes any database whose
+     * name starts with `ablo_` or `ablo-`. This covers:
+     *   - `ablo_<hash>` workspace data DBs
+     *   - `ablo_databases` meta registry
+     *   - `ablo-sync` offline mutation queue
+     *
+     * Use case: session expiry (previous-user data must not persist on
+     * disk before the next sign-in races into a corrupted state) or
+     * explicit user-initiated logout.
+     *
+     * Best-effort: swallows individual delete errors. Some browsers do
+     * not support `indexedDB.databases()` — the method returns without
+     * deleting in that case, same behavior as the pre-SDK app code.
+     */
+    purge(): Promise<void>;
+    /**
+     * Create WebSocket connection and wire all event handlers.
+     * Handles: deltas, batches, presence, bootstrap_required, errors, reconnection.
+     */
+    /**
+     * Block until the WebSocket reports a `connected` event, or until
+     * `timeoutMs` elapses (returns false on timeout, true on connect).
+     * Used by `initialize()` for `bootstrapMode: 'none'` consumers to
+     * honor `ready()`'s "WS is connected when this resolves" contract
+     * — `setupWebSocketSync` is fire-and-forget on the upgrade, and
+     * without an explicit wait the next mutation can race the open.
+     *
+     * Resolves immediately if the WS is already connected (e.g., warm
+     * reconnect after redeploy). Resolves false on timeout rather than
+     * throwing so initialize() can complete and let the caller's first
+     * mutation attempt surface a clearer error.
+     */
+    protected waitForWebSocketConnected(timeoutMs: number): Promise<boolean>;
+    protected setupWebSocketSync(context: UserContext, lastSyncId: number): void;
+    /** State signature for delta deduplication */
+    private extractStateSignature;
+    /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
+    protected getStateFields(_modelName: string): string[];
+    private isSameState;
+    /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
+    protected deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
+    /** Process incoming delta with smart batching */
+    protected processDeltaWithBatching(delta: SyncDelta): void;
+    /**
+     * Cancel pending transactions for child entities when a parent is deleted.
+     *
+     * Uses `pool.getByForeignKey` (O(1) via the FK index registered at
+     * schema build time) to find children. The previous implementation did
+     * `getByType(ctor).filter(e => e.toJSON()[foreignKey] === parentId)` —
+     * a full pool scan per child model + a `toJSON()` allocation per
+     * candidate. For a deck delete with 10K layers in the pool, that was
+     * 10K toJSON allocations per cascade level. The FK-indexed lookup
+     * skips both the scan AND the allocation.
+     */
+    protected cascadeCancelTransactionsForDeletedParent(parentModelName: string, parentId: string): void;
+    /** Flush pending deltas with deduplication and batched ObjectPool mutations */
+    /** Flush pending deltas with deduplication. Delegates pool writes to SyncClient. */
+    protected flushPendingDeltas(): Promise<void>;
+    /** Check if a model type is local-only (no sync). Override for domain-specific models. */
+    protected isLocalOnlyModel(_modelName: string): boolean;
+    /** Validate model against schema before save */
+    protected validateModel(model: Model): void;
+    /**
+     * Save a model (create or update).
+     *
+     * Accepts any entity shape with `{ id: string }` so consumers can pass the
+     * Zod-inferred model types from `InferModel<Schema, K>` without knowing
+     * about the internal `Model` base class. At runtime, every entity reaching
+     * this method came through the object pool (via `store.create`, a query
+     * accessor, or an optimistic insert) and IS a `Model` instance — the one
+     * cast below preserves that invariant inside the SDK.
+     */
+    save<T extends {
+        id: string;
+        createdAt?: Date;
+        updatedAt?: Date;
+    }>(entity: T, options?: {
+        skipValidation?: boolean;
+    }): Promise<void>;
+    /** Save with an atomic server mutation (e.g., createSlideWithLayers) */
+    saveWithAtomicMutation(model: Model, mutation: (gql: unknown) => Promise<unknown>): Promise<void>;
+    /** Delete a model. Accepts schema-inferred entity shapes (see `save`). */
+    delete<T extends {
+        id: string;
+    }>(entity: T): Promise<void>;
+    /** Archive a model. Accepts schema-inferred entity shapes (see `save`). */
+    archive<T extends {
+        id: string;
+        archivedAt?: Date | null;
+    }>(entity: T): Promise<void>;
+    /** Unarchive a model. Accepts schema-inferred entity shapes (see `save`). */
+    unarchive<T extends {
+        id: string;
+        archivedAt?: Date | null;
+    }>(entity: T): Promise<void>;
+    /**
+     * Schema-keyed accessor namespace — the primary type-safe lookup surface.
+     *
+     * ```ts
+     * const chat = store.query.chats.retrieve(chatId);  // Chat | undefined
+     * const slides = store.query.slides.findMany({ where: { deckId } });  // Slide[]
+     * ```
+     *
+     * Each `query.<modelKey>` is a `ReaderActions<Schema, K>` built lazily on
+     * first access via `createReaderActions`. The returned types are inferred
+     * from the schema (`InferModel<S, K>`), including `InferRelations` — so
+     * `chat.messages`, `slide.layers`, etc. are typed without a cast.
+     *
+     * Throws if the store was constructed without a schema (class-based
+     * subclasses that wire models via `modelRegistry.registerModel` directly
+     * don't have access to schema-derived inference).
+     */
+    get query(): QueryNamespace<TSchema>;
+    /** Retrieve a single entity by id. Synchronous pool read. */
+    retrieve(_modelClass: ModelConstructor<Model>, id: string): Model | undefined;
+    /** Find any entity by ID regardless of type */
+    findAnyById(id: string): Model | undefined;
+    /**
+     * Lookup a model by ID alone. Matches the `SyncStoreRef.getById` contract
+     * that schema-defined computeds use when they need to resolve a related
+     * entity without holding onto its constructor.
+     */
+    getById(id: string): Model | undefined;
+    /**
+     * Create a model instance locally, typed via the schema.
+     *
+     * ```ts
+     * const sheet = store.create('spreadsheetSheets', { name, spreadsheetId });
+     * // sheet: SpreadsheetSheet | null — no cast needed
+     * ```
+     *
+     * The `typename` arg is the schema key (camelCase plural, e.g.
+     * `'spreadsheetSheets'`); the returned instance has the
+     * `InferModel<Schema, K>` shape including computeds + relation accessors.
+     * Wraps `pool.create(...)` — the underlying runtime is unchanged, just
+     * type-narrowed.
+     */
+    create<K extends keyof TSchema['models'] & string>(typename: K, data: Record<string, unknown>): import('./schema/schema.js').InferModel<TSchema, K> | null;
+    /**
+     * Legacy class-based query entry point — kept for callers that still pass
+     * a Model constructor + options object. New code should use the typed
+     * `store.query.<modelKey>` namespace instead, which returns properly
+     * inferred schema types without needing a class value or cast.
+     */
+    queryByClass(modelClass: ModelConstructor<Model>, options?: {
+        predicate?: (model: Model) => boolean;
+        scope?: ModelScope;
+        orderBy?: keyof Model;
+        order?: 'asc' | 'desc';
+        limit?: number;
+        offset?: number;
+    }): QueryResult<Model>;
+    /**
+     * Get all models of a type. Returns Model[] honestly — callers that need
+     * narrow types should use `useAblo((ablo) => ablo.<model>.list(...))`
+     * which does proper inference via `InferModel<S, K>`.
+     */
+    allModelsOfType(modelClass: ModelConstructor<Model>, scope?: ModelScope): Model[];
+    /** Error handler for fire-and-forget flushPendingDeltas calls */
+    protected handleFlushError: (error: unknown) => void;
+    /** Process a single delta (used for immediate DELETE processing). Override for domain-specific handling. */
+    protected processDelta(delta: SyncDelta): Promise<void>;
+    /** Handle bootstrap_required event */
+    protected handleBootstrapRequired(_hint: BootstrapHint): void;
+    /** Handle bootstrap_data event. Override in subclass. */
+    protected handleBootstrapData(_data: BootstrapDataEvent): void;
+    /** Handle presence_update event. Override in subclass. */
+    protected handlePresenceUpdate(_data: PresenceUpdateEvent): void;
+    protected incrementPendingChanges(): void;
+    protected decrementPendingChanges(): void;
+    protected updateSyncStatus(updates: Partial<SyncStatus>): void;
+    get pool(): ObjectPool;
+    get lastSyncId(): number;
+    get isReady(): boolean;
+    get isSyncing(): boolean;
+    get isOffline(): boolean;
+    get isReconnecting(): boolean;
+    get isError(): boolean;
+    get hasUnsyncedChanges(): boolean;
+    /** The SyncWebSocket handle — for collaboration events. */
+    get ws(): SyncWebSocket<TCollaboration> | null;
+    /** The Database instance — for demand loaders and direct IDB operations. */
+    get db(): Database;
+    /** The SyncClient instance — for assignment operations and other direct sync actions. */
+    get sc(): SyncClient;
+    /** The current organization ID — from the last initialize() call. */
+    get orgId(): string | undefined;
+    /** Count models matching a predicate. */
+    count(modelClass: ModelConstructor<Model>, predicate?: (m: Model) => boolean): number;
+    /** Get entities by foreign key (used by Model subclasses via Model.store) */
+    getByForeignKey(modelName: string, foreignKey: string, id: string): Model[];
+}