@abloatai/ablo 0.35.0 → 0.37.0

package/dist/BaseSyncedStore.d.ts

@@ -1,823 +0,0 @@
-/**
- * The base class that application-specific sync stores extend. It supplies the
- * shared orchestration for reads, writes, delta processing, and bootstrap, and
- * exports the core types those stores build on.
- *
- * A subclass adds its own domain behavior — lazy-loaded relations,
- * collaboration events, and model enrichment — by overriding the protected
- * extension points defined here. The heavy lifting is delegated to injected
- * collaborators: {@link SyncClient} owns pool writes and the transaction
- * queue, {@link Database} owns local persistence, {@link InstanceCache} holds the
- * in-memory models, and {@link ModelRegistry} holds their metadata.
- */
-import type { RecoveryClass } from './transaction/errorCodes.js';
-import { ConnectionManager } from './sync/ConnectionManager.js';
-import { SubscriptionManager } from './sync/SubscriptionManager.js';
-import { type ParticipantScope } from './sync/participants.js';
-import type { SyncClient } from './SyncClient.js';
-import type { Database, BootstrapResult } from './Database.js';
-import type { InstanceCache } from './InstanceCache.js';
-import { ModelRegistry } from './ModelRegistry.js';
-import { SyncWebSocket, type SyncDelta, type SyncGroupChangePayload, type GroupAddedPayload, type GroupRemovedPayload, type BootstrapHint, type BootstrapDataEvent, type PresenceUpdate, type EventMap, type DefaultCollaborationEvents, type SyncWebSocketEventMap } from './sync/SyncWebSocket.js';
-import { QueryProcessor } from './core/QueryProcessor.js';
-import { Model } from './Model.js';
-import { ModelScope } from './InstanceCache.js';
-import type { Schema } from './transaction/schema/schema.js';
-import type { SyncStatus, LocalMutation } from './core/storeContract.js';
-import type { AuthCredentialSource } from './transaction/auth/credentialSource.js';
-import type { ModelData } from './transaction/types/modelData.js';
-import type { EnrichmentPlanEntry, ForeignKeyIndexSpec } from './sync/syncPlan.js';
-import { type CredentialRefresher } from './sync/credentialLifecycle.js';
-import type { RehydrationStats } from './sync/bootstrapApply.js';
-import type { ParticipantKind } from './transaction/types/participant.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;
-export type { ModelData } from './transaction/types/modelData.js';
-/** Query result interface */
-export interface QueryResult<T extends Model> {
-    data: T[];
-    total: number;
-    hasMore: boolean;
-    fromCache?: boolean;
-}
-export type { ForeignKeyIndexSpec, EnrichmentPlanEntry } from './sync/syncPlan.js';
-/** Configuration for SyncedStore behavior */
-export interface SyncedStoreConfig {
-    enableOffline?: boolean;
-    enableCache?: boolean;
-    enableTelemetry?: boolean;
-    /**
-     * Wire message types to surface as collaboration events, e.g.
-     * `['document:selection', 'document:cursor']`.
-     *
-     * The vocabulary belongs to the application, not the SDK — these name the
-     * application's own concepts, and a schema with no documents should never see
-     * them. Defaults to none, so an application opts in by naming the events it
-     * actually broadcasts.
-     */
-    collaborationEvents?: 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 InstanceCache 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[];
-}
-export type { SyncStatus } from './core/storeContract.js';
-/** 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?: ParticipantKind;
-    /** Restricted (`rk_`) API key for `kind: 'agent'` — the agent's
-     *  bearer credential. Sent in the `ablo.bearer.<token>` WebSocket
-     *  subprotocol, never in the URL. */
-    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 `model.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;
-}
-export type { RehydrationStats } from './sync/bootstrapApply.js';
-/**
- * Bootstrap retry configuration.
- *
- * There is deliberately no overall timeout here. How long one attempt may run
- * is not a policy this layer gets to invent — it is a property of the fetcher's
- * watchdogs, read from `BootstrapFetcher.budgetMs`. A second number kept here
- * would only be able to disagree with them, which is exactly what it used to do.
- */
-export declare const BOOTSTRAP_CONFIG: {
-    readonly MAX_RETRY_ATTEMPTS: 3;
-    readonly RETRY_DELAY_MS: 500;
-};
-export { ModelScope };
-export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdate, };
-export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
-/**
- * The abstract base class that application-specific sync stores extend. It
- * carries the injected collaborators, the observable sync status, and the
- * orchestration for initialization, delta processing, bootstrap, and the
- * read and write API. A subclass supplies its own domain behavior by
- * overriding the protected extension points defined here and by typing its
- * collaboration events through the generic parameter.
- *
- * A subclass must call `super(dependencies, config)` and then set up its 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 EditorEvents {
- *     'document:selection': [SelectionEvent];
- *     'document:cursor':    [CursorEvent];
- *   }
- *   class EditorStore extends BaseSyncedStore<EditorEvents> {
- *     subscribeToCursor(handler: (e: CursorEvent) => void) {
- *       return this.syncWebSocket.subscribe('document:cursor', handler);
- *     }
- *   }
- */
-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: InstanceCache;
-    protected readonly modelRegistry: ModelRegistry;
-    protected readonly auth?: AuthCredentialSource;
-    /**
-     * Schema the store was constructed with. Used by the schema-typed
-     * `create(key, data)` factory and model self-healing.
-     */
-    protected readonly schema?: TSchema;
-    /**
-     * The connection, owned by whoever built this store (ADR 0016 follow-up
-     * 3b): the host constructs it and hands it in, the store seeds its late
-     * values during `initialize()` and owns the lifecycle from there. One
-     * instance for the store's whole lifetime — reconnects replace the socket
-     * inside it, never the object.
-     */
-    protected readonly syncWebSocket: SyncWebSocket<TCollaboration>;
-    /**
-     * Dynamic read interest (area-of-interest) over the connection's sync
-     * groups. Constructed with the connection; the permanent base scopes are
-     * seeded in `setupWebSocketSync` once identity resolves.
-     */
-    protected readonly areaOfInterest: SubscriptionManager;
-    /** Sync groups whose current state has been backfilled into the pool
-     *  (hydrate-on-enter). Cleared when the pool is reset on (re)bootstrap. */
-    private readonly hydratedGroups;
-    /** In-flight scoped hydrations, keyed by group — single-flights concurrent
-     *  enters of the same scope so they share one fetch. */
-    private readonly hydratingGroups;
-    private _syncServerUrl?;
-    /** Application-declared collaboration event types; empty unless configured. */
-    private _collaborationEvents;
-    /**
-     * 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.
-     */
-    getSyncWebSocket(): SyncWebSocket<TCollaboration>;
-    /**
-     * Subscribe to pushed frames — deltas, presence updates, claim grants and
-     * losses, connection changes, and this store's collaboration events.
-     * Durable by construction: the connection object exists for the store's
-     * whole lifetime (reconnects replace only the socket inside it), so a
-     * subscription made before the first connect starts delivering when the
-     * socket opens and keeps delivering across every reconnect. Returns the
-     * unsubscribe function.
-     */
-    subscribe<K extends keyof SyncWebSocketEventMap<TCollaboration>>(event: K, handler: (...args: SyncWebSocketEventMap<TCollaboration>[K]) => void): () => void;
-    /**
-     * Send a collaboration event (an app-specific real-time message from this
-     * store's `TCollaboration` map). A no-op while the connection is down —
-     * presence-grade traffic is not queued.
-     */
-    sendCollaborationEvent<K extends string & keyof TCollaboration>(messageType: K, payload: TCollaboration[K] extends [infer P] ? Omit<P & Record<string, unknown>, 'timestamp'> : never): void;
-    private scopeToGroups;
-    /**
-     * Bring a scope into view and subscribe to its sync groups. With
-     * `{ hydrate: true }`, also backfill the groups' current state into the pool
-     * once the subscription is active. The order matters: subscribing first
-     * guarantees no live delta is missed in the gap before the snapshot lands.
-     * Hydration is best-effort — a failed backfill never rejects `enterScope`,
-     * and the live delta stream keeps flowing regardless.
-     */
-    enterScope(scope: ParticipantScope, opts?: {
-        hydrate?: boolean;
-    }): Promise<void>;
-    /**
-     * Backfill the current state of `syncGroups` into the pool with a side-effect-free
-     * scoped snapshot fetch followed by the version-guarded scoped apply. The call
-     * is idempotent (it skips groups already hydrated) and single-flight (concurrent
-     * enters of the same group share one fetch). On error the groups are left
-     * unmarked, so a later re-enter retries.
-     */
-    protected hydrateGroups(syncGroups: readonly string[]): Promise<void>;
-    /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
-    leaveScope(scope: ParticipantScope): Promise<void>;
-    /** Pin a scope (active claim / prominence) → never warms while pinned. */
-    pinScope(scope: ParticipantScope): Promise<void>;
-    /** Release a pin → the group transitions to warm rather than dropping. */
-    unpinScope(scope: ParticipantScope): Promise<void>;
-    protected readonly queryProcessor: QueryProcessor;
-    /**
-     * Runtime behavior flags only — the schema/config arrays
-     * (`enrichmentPlan`, `foreignKeyIndexes`) are consumed at construction
-     * time and stored on the instance as `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: (() => void)[];
-    protected initialized: boolean;
-    protected dataReady: boolean;
-    protected userContext: UserContext | null;
-    /**
-     * 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;
-    /** Resume/ack cursor — delegates to the shared LogPosition (see
-     *  logPosition.ts). Advances only after IDB persistence. */
-    protected get lastAckedId(): number;
-    /** Pool-applied cursor — delegates to the shared LogPosition. */
-    protected get highestProcessedSyncId(): number;
-    protected bootstrapDeltaQueue: SyncDelta[] | null;
-    protected activeBootstrapCount: number;
-    /** The live deadline for the bootstrap attempt in flight, if any. */
-    private bootstrapDeadlineTimer;
-    protected pendingDeletes: Set<string>;
-    protected modelTypesHydrated: Set<string>;
-    protected modelTypeHydrationInFlight: Map<string, Promise<void>>;
-    constructor(dependencies: {
-        syncClient: SyncClient;
-        database: Database;
-        objectPool: InstanceCache;
-        modelRegistry: ModelRegistry;
-        /**
-         * The connection, built by the host. When omitted, the store constructs
-         * its own from `url` and the collaboration-event config — the
-         * self-contained path subclasses and tests use. Either way the store
-         * owns the lifecycle from here: it seeds the late values (identity,
-         * read scope, resume cursor) during `initialize()` and releases the
-         * first connect.
-         */
-        syncWebSocket?: SyncWebSocket<TCollaboration>;
-        /**
-         * Optional schema. When provided, {@link deriveSyncPlanFromSchema} walks
-         * the schema's models and relations to auto-populate foreign-key indexes
-         * and the enrichment plan from their declarative annotations. Subclasses
-         * that register model classes directly can instead pass explicit
-         * `config.foreignKeyIndexes` / `config.enrichmentPlan`.
-         */
-        schema?: TSchema;
-        /** Sync server URL for WebSocket connection. Converted to wss:// automatically. */
-        url?: string;
-        /** Shared bearer credential source for every auth-aware transport. */
-        auth?: AuthCredentialSource;
-    }, config?: SyncedStoreConfig);
-    /**
-     * Register foreign-key indexes for constant-time lookups.
-     *
-     * This is an override hook. The preferred way to declare a foreign-key
-     * index is `config.foreignKeyIndexes` at construction time, or marking the
-     * `belongsTo` relation with `{ index: true }` in the schema. The hook fires
-     * after the schema-derived and config registrations, so a subclass can
-     * layer additional indexes on top.
-     */
-    protected registerForeignKeys(): void;
-    /**
-     * Enrich delta data with related models from the InstanceCache.
-     *
-     * 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;
-    /**
-     * Access-credential re-mint + proactive pre-roll — extracted to
-     * sync/credentialLifecycle.ts. Owns the refresher hook, the single-flight
-     * guard, and the browser-only refresh timer / wake listener; talks back
-     * through three lazily-resolved callbacks (the ConnectionManager doesn't
-     * exist until `setupWebSocketSync`). The `setCredentialRefresher` /
-     * `performCredentialRefresh` / `startCredentialLifecycle` methods below
-     * are thin delegates so the store's public surface is unchanged.
-     */
-    private readonly credentialLifecycle;
-    /**
-     * 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.mutationQueue` 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/mutations/MutationQueue.js').QueuedMutation;
-        error: Error;
-        permanent?: boolean;
-    }) => void): () => void;
-    /**
-     * Subscribe to commit round-trip latency. Forwarded from the underlying
-     * `SyncClient` for the same reason as `subscribeMutationFailure` — the
-     * React provider binds against this surface, so the engine's wiring stays
-     * private while the SDK keeps one hook to expose.
-     */
-    subscribeCommitLatency(listener: (sample: import('./transactions/mutations/commitLatency.js').CommitLatencySample) => 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>;
-    /**
-     * Observe the LOCAL mutation stream for undo recording (see
-     * {@link import('./core/storeContract.js').LocalMutation}). Taps the
-     * MutationQueue's `transaction:created` event — fired once per local
-     * create/update/delete/archive with `previousData` already captured.
-     * Remote/collaborator deltas apply via `applyDeltaBatchToPool` and never
-     * emit here, so undo is naturally local-only (you can't undo a teammate).
-     */
-    subscribeLocalMutations(handler: (mutation: LocalMutation) => void): () => 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>;
-    /**
-     * The outer deadline for one bootstrap attempt.
-     *
-     * The length is DERIVED from the fetcher's own watchdog budget, not chosen. A
-     * chosen number is what broke this: the previous fixed 15s was shorter than a
-     * single model chunk's allowance — 20s waiting for response headers plus 15s
-     * of stall grace — so on any workspace with one slow model the deadline fired
-     * before the watchdogs it was meant to backstop, and every attempt timed out
-     * by construction. The watchdogs below are progress-based and already
-     * guarantee termination; this deadline exists only for a hang somewhere other
-     * than the network, so it must sit above them, and it can only do that
-     * reliably by asking them how long they take.
-     *
-     * Reaching it aborts the work in flight. `Promise.race` merely stops waiting:
-     * without the abort the losing bootstrap keeps running, keeps its sockets, and
-     * races the retry that replaced it — which is how one page load turned into
-     * dozens of overlapping requests.
-     */
-    protected createBootstrapTimeout(attempt: number): Promise<never>;
-    /** Disarm the deadline once its attempt has settled. Load-bearing now that
-     *  firing it aborts real work: a leftover timer would cancel a later,
-     *  unrelated bootstrap. */
-    private clearBootstrapDeadline;
-    /** 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'>;
-    /**
-     * Register the access-credential re-mint hook. Called by the React provider
-     * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
-     * See {@link CredentialLifecycle.setRefresher}.
-     */
-    setCredentialRefresher(refresher: CredentialRefresher | null): void;
-    /**
-     * Re-mint the short-lived access credential and push it into the credential
-     * source, reporting a tri-state outcome the {@link ConnectionManager} maps to
-     * its FSM. Single-flight; no refresher wired ⇒ `'refreshed'` (a no-op
-     * re-probe). Full contract on {@link CredentialLifecycle.refresh}.
-     */
-    performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
-    /**
-     * The authentication-recovery path for HTTP transports, such as the lazy
-     * query lane. It runs a single-flight credential re-mint driven by the
-     * rejection's recovery class, routing outcomes through the same state
-     * machine the WebSocket probe uses. `'retry'` means a fresh credential is
-     * now in the credential source and the request should be replayed once.
-     * Full contract on {@link CredentialLifecycle.recoverFromAuthRejection}.
-     */
-    recoverFromAuthRejection(recovery: RecoveryClass): Promise<'retry' | 'stop'>;
-    /**
-     * Nudge the connection FSM to re-probe with the current credential. Idempotent
-     * and safe in any state (ignored while `connected`). Call after pushing a
-     * freshly-minted token via `setAuthToken`, or on an OS-wake signal, so a
-     * connection parked in `offline` / `backoff` / `auth_blocked` picks the new
-     * credential up immediately instead of waiting for the 30s watchdog.
-     */
-    nudgeReconnect(): void;
-    /**
-     * Install the client-owned access-credential lifecycle: register `getToken`
-     * as the reactive re-mint hook and arm the browser-only proactive refresh
-     * (a refresh timer plus an OS-wake re-mint). Idempotent — a second call
-     * replaces the first — and torn down on {@link disconnect}. Full rationale
-     * on {@link CredentialLifecycle.start}.
-     */
-    startCredentialLifecycle(getToken: CredentialRefresher, opts?: {
-        proactiveInNode?: boolean;
-    }): void;
-    /** Tear down the proactive credential lifecycle (idempotent). */
-    private stopCredentialLifecycle;
-    /** Narrow context the group-change leaf talks back through. */
-    private groupChangeContext;
-    /**
-     * Handle an actionType 'G' delta — incremental `{ group, userId }` or
-     * legacy `{ addedGroups, removedGroups }` payloads. Full pathway doc on
-     * {@link groupChange.handleSyncGroupChange}.
-     */
-    protected handleSyncGroupChange(delta: SyncDelta): Promise<void>;
-    /**
-     * Handle an incremental GroupAdded delta — metadata only, no re-bootstrap
-     * (covering deltas bring the entities). See {@link groupChange.handleGroupAdded}.
-     */
-    protected handleGroupAdded(payload: GroupAddedPayload, syncId: number): Promise<void>;
-    /**
-     * Handle an actionType 'S' (GroupRemoved) delta: for safety, clear the
-     * revoked local state and trigger a full re-bootstrap. See
-     * {@link groupChange.handleGroupRemoved}.
-     */
-    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 — see {@link groupChange.forceFullRebootstrap}). */
-    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>;
-    /** Narrow context the bootstrap-apply leaf talks back through. */
-    private poolContext;
-    /** Apply bootstrap data to the {@link InstanceCache}, removing entities that are no longer present (ghost removal). Pool writes are delegated to {@link 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 (atomically, via `applyDeltaFrame`). */
-    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?: ParticipantKind): ConnectionManager | null;
-    /**
-     * Disconnect and clean up all resources. Terminal: this means "the client
-     * is finished", not "close and reopen later" — the connection object stays
-     * assigned but closed, the event wiring is torn down, and nothing
-     * re-initializes a disconnected store. (Mid-session closes during recovery
-     * go through the connection FSM's `onDisconnectWebSocket`, which closes
-     * the transport without touching the store.)
-     */
-    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>;
-    /**
-     * Seed the connection's late values and open it. The socket itself exists
-     * from construction; what identity resolution supplies — the participant
-     * kind, the credential, the read scope, and the resume cursor — is seeded
-     * here, and only then is the held first connect released. A retried
-     * `initialize()` after a failed `ready()` re-runs this against the same
-     * connection object: the reconnect counter is reset for a clean slate,
-     * while the session-error latch deliberately survives (only the
-     * credential-expiry recovery clears it).
-     */
-    protected setupWebSocketSync(context: UserContext, lastSyncId: number): void;
-    /**
-     * Wire the store's handlers onto the connection. Runs once, at
-     * construction — the connection object is stable for the store's
-     * lifetime, so the wiring is too.
-     */
-    protected wireSocketEvents(): void;
-    /**
-     * Build and start the connection FSM. The `onConnectionEvent` hook is the
-     * bridge — WS events fire the hook, the hook forwards into the FSM. Called
-     * from `setupWebSocketSync` because the FSM's shape depends on the resolved
-     * participant kind (agents get none — see {@link createConnectionManager}).
-     */
-    private startConnectionManager;
-    /** Memoized pipeline context — `enqueueDelta` runs once per delta, so the
-     *  accessor object is built once and reused (the get/set accessors always
-     *  read the live host fields). */
-    private _deltaPipelineContext;
-    private get deltaPipelineContext();
-    /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
-    protected getStateFields(_modelName: string): string[];
-    /** 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;
-    /**
-     * Apply a complete, server-delivered delta frame atomically.
-     *
-     * A `delta_batch` WebSocket event (a reconnect or catch-up replay) already
-     * carries the full set of missed deltas. Routing it through the per-delta
-     * `processDeltaWithBatching` path would re-chunk it via the live-traffic
-     * debounce timer and `maxBatchSize` force-flush, so a 300-delta catch-up
-     * would fan out into several separate `flushPendingDeltas` cycles — each its
-     * own local write, pool mutation, `models:changed` emit, and re-render, so
-     * the UI visibly repaints once per chunk.
-     *
-     * Instead, this runs the per-delta bookkeeping (deduplication, ack, version
-     * vector, watermark, group-change routing, delete cascade) for every delta
-     * without scheduling a flush, then flushes once — collapsing the whole frame
-     * into a single local write, pool mutation, `models:changed` emit, and
-     * re-render. The post-bootstrap replay of deltas queued during bootstrap
-     * uses the same path.
-     *
-     * It is named `applyDeltaFrame`, not `processDeltaBatch`, to avoid confusion
-     * with {@link Database.processDeltaBatch} — the lower-level local write this
-     * eventually drives through `flushPendingDeltas`.
-     */
-    protected applyDeltaFrame(deltas: SyncDelta[]): void;
-    /**
-     * Per-delta bookkeeping + enqueue. Returns `true` when the delta was
-     * pushed onto `pendingDeltas` (a regular batchable I/U/C/D delta that a
-     * subsequent flush must drain), `false` when it was skipped (dedup),
-     * deferred (bootstrap queue), or handled immediately out-of-band (G/S
-     * sync-group mutations). Does NOT schedule a flush — callers decide
-     * whether to debounce (live) or flush atomically (catch-up frame).
-     */
-    protected enqueueDelta(delta: SyncDelta, options?: {
-        authoritative?: boolean;
-    }): boolean;
-    /** Debounce a flush for live single-delta traffic. */
-    protected scheduleDeltaFlush(): 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 report delete with 10K blocks 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. Pool writes are delegated to {@link 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 `Model<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., createSectionWithBlocks) */
-    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>;
-    /** 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 ledger = store.create('ledgers', { name, reportId });
-     * // ledger: Ledger | null — no cast needed
-     * ```
-     *
-     * The `typename` arg is the schema key (camelCase plural, e.g.
-     * `'ledgers'`); the returned instance has the
-     * `Model<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('./transaction/schema/schema.js').Model<TSchema, K> | null;
-    /**
-     * Query entry point for callers that hold a {@link Model} constructor and an
-     * options object. It filters, orders, and paginates the matching models from
-     * the pool. Prefer the schema-typed read surface (`ablo.<model>.list`) where
-     * you can, since it infers concrete row types without a class value or cast.
-     */
-    queryByClass(modelClass: ModelConstructor<Model>, options?: {
-        predicate?: (model: Model) => boolean;
-        state?: 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 `Model<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: PresenceUpdate): void;
-    protected incrementPendingChanges(): void;
-    protected decrementPendingChanges(): void;
-    protected updateSyncStatus(updates: Partial<SyncStatus>): void;
-    get pool(): InstanceCache;
-    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[];
-}