@abloatai/ablo 0.34.1 → 0.36.0

package/dist/BaseSyncedStore.d.ts

@@ -10,7 +10,7 @@
  * queue, {@link Database} owns local persistence, {@link InstanceCache} holds the
  * in-memory models, and {@link ModelRegistry} holds their metadata.
  */
-import type { RecoveryClass } from './errorCodes.js';
+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';
@@ -18,22 +18,25 @@ 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 PresenceUpdateEvent, type EventMap, type DefaultCollaborationEvents } from './sync/SyncWebSocket.js';
-import { QueryProcessor } from './core/QueryProcessor.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 './query/QueryProcessor.js';
 import { Model } from './Model.js';
+import type { RuntimeContext } from './RuntimeContext.js';
+import type { AbloPlugin, AppliedChange } from './transaction/plugin.js';
 import { ModelScope } from './InstanceCache.js';
-import type { Schema } from './schema/schema.js';
-import type { SyncStatus, LocalMutation } from './core/storeContract.js';
-import type { AuthCredentialSource } from './auth/credentialSource.js';
-import type { ModelData } from './types/modelData.js';
+import type { Schema } from './transaction/schema/schema.js';
+import type { SyncStatus, LocalMutation } from './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 './types/modelData.js';
+export type { ModelData } from './transaction/types/modelData.js';
 /** Query result interface */
 export interface QueryResult<T extends Model> {
     data: T[];
@@ -47,6 +50,16 @@ 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
@@ -64,7 +77,7 @@ export interface SyncedStoreConfig {
      */
     foreignKeyIndexes?: readonly ForeignKeyIndexSpec[];
 }
-export type { SyncStatus } from './core/storeContract.js';
+export type { SyncStatus } from './storeContract.js';
 /** User context for initialization */
 export interface UserContext {
     userId: string;
@@ -75,7 +88,7 @@ export interface UserContext {
      *  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';
+    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. */
@@ -107,14 +120,20 @@ export interface SmartSyncOptions {
     maxBatchSize?: number;
 }
 export type { RehydrationStats } from './sync/bootstrapApply.js';
-/** Bootstrap timeout configuration */
+/**
+ * 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 OVERALL_TIMEOUT_MS: 15000;
     readonly MAX_RETRY_ATTEMPTS: 3;
     readonly RETRY_DELAY_MS: 500;
 };
 export { ModelScope };
-export type { SyncDelta, SyncGroupChangePayload, GroupAddedPayload, GroupRemovedPayload, BootstrapHint, BootstrapDataEvent, PresenceUpdateEvent, };
+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
@@ -133,18 +152,22 @@ export { deriveSyncPlanFromSchema } from './sync/syncPlan.js';
  * the underlying SyncWebSocket without casts:
  *
  * @example
- *   interface AbloEvents {
- *     'sheet:selection': [SheetSelectionEvent];
- *     'slide:cursor':    [SlideCursorEvent];
+ *   interface EditorEvents {
+ *     'document:selection': [SelectionEvent];
+ *     'document:cursor':    [CursorEvent];
  *   }
- *   class SyncedStore extends BaseSyncedStore<AbloEvents> {
- *     subscribeToSlideCursor(handler: (e: SlideCursorEvent) => void) {
- *       return this.syncWebSocket?.subscribe('slide:cursor', handler);
+ *   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;
+    /** The owning client's runtime; the module-global bridge when constructed directly. */
+    protected readonly runtime: RuntimeContext;
+    /** The installed plugins the delta pipeline dispatches stage handlers to. */
+    protected readonly stagePlugins: readonly AbloPlugin[];
     protected readonly syncClient: SyncClient;
     protected readonly database: Database;
     protected readonly objectPool: InstanceCache;
@@ -155,15 +178,20 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * `create(key, data)` factory and model self-healing.
      */
     protected readonly schema?: TSchema;
-    protected syncWebSocket: SyncWebSocket<TCollaboration> | null;
+    /**
+     * 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. Lives alongside `syncWebSocket` and is recreated with it; the
-     * stable `enterScope`/`leaveScope`/`pinScope`/`unpinScope` methods forward
-     * to whichever instance is current, so callers (the React participant
-     * hook) never hold a stale reference. Null until `setupWebSocketSync`.
+     * groups. Constructed with the connection; the permanent base scopes are
+     * seeded in `setupWebSocketSync` once identity resolves.
      */
-    protected areaOfInterest: SubscriptionManager | null;
+    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;
@@ -171,15 +199,32 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      *  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. Returns null until WS is initialized during
-     * `initialize()`.
+     * normal typing.
      */
-    getSyncWebSocket(): SyncWebSocket<TCollaboration> | null;
+    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
@@ -230,13 +275,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected pendingDeltas: SyncDelta[];
     protected batchTimer: ReturnType<typeof setTimeout> | null;
     protected syncPromise: Promise<void> | null;
-    /** Resume/ack cursor — delegates to the shared SyncPosition (see
-     *  sync/syncPosition.ts). Advances only after IDB persistence. */
+    /** 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 SyncPosition. */
+    /** 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>>;
@@ -245,6 +292,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         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
@@ -257,6 +313,14 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         url?: string;
         /** Shared bearer credential source for every auth-aware transport. */
         auth?: AuthCredentialSource;
+        /** The owning client's runtime. Defaults to the module-global bridge. */
+        runtime?: RuntimeContext;
+        /**
+         * The installed plugins, whose declared stage handlers the delta
+         * pipeline dispatches. Empty on direct construction — the store's own
+         * apply is then the whole pipeline.
+         */
+        stagePlugins?: readonly AbloPlugin[];
     }, config?: SyncedStoreConfig);
     /**
      * Register foreign-key indexes for constant-time lookups.
@@ -331,7 +395,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     subscribeSessionError(listener: (error: Error) => void): () => void;
     /**
      * Subscribe to per-mutation failure payloads. Forwarded from the
-     * underlying `SyncClient.transactionQueue` so consumers (toast layer,
+     * underlying `SyncClient.mutationQueue` so consumers (toast layer,
      * route-level reverted boundaries, telemetry) can react without
      * reaching across the store. Returns an unsubscribe function.
      *
@@ -342,10 +406,17 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * same shape, same lifecycle.
      */
     subscribeMutationFailure(listener: (payload: {
-        transaction: import('./transactions/TransactionQueue.js').Transaction;
+        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
@@ -354,8 +425,8 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     waitForConfirmation(modelName: string, modelId: string): Promise<void>;
     /**
      * Observe the LOCAL mutation stream for undo recording (see
-     * {@link import('./core/storeContract.js').LocalMutation}). Taps the
-     * TransactionQueue's `transaction:created` event — fired once per local
+     * {@link import('./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).
@@ -366,8 +437,29 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * 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 */
+    /**
+     * 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. */
@@ -495,8 +587,15 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * 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 */
+    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.
@@ -535,12 +634,41 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * 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();
+    /**
+     * Lands persisted changes in the in-memory pool, with this store's
+     * relation enrichment bound. The one apply path: the pipeline's bridge
+     * (no plugins installed) and the `humans()` apply handler both call it.
+     */
+    applyChangesToPool(changes: readonly AppliedChange[]): void;
     /** 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 */
@@ -590,7 +718,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * 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
+     * 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.
      */
@@ -605,7 +733,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * 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
+     * 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
@@ -618,7 +746,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     }>(entity: T, options?: {
         skipValidation?: boolean;
     }): Promise<void>;
-    /** Save with an atomic server mutation (e.g., createSlideWithLayers) */
+    /** 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 {
@@ -648,17 +776,17 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * Create a model instance locally, typed via the schema.
      *
      * ```ts
-     * const sheet = store.create('spreadsheetSheets', { name, spreadsheetId });
-     * // sheet: SpreadsheetSheet | null — no cast needed
+     * const ledger = store.create('ledgers', { name, reportId });
+     * // ledger: Ledger | 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.
+     * `'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('./schema/schema.js').InferModel<TSchema, K> | null;
+    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
@@ -676,7 +804,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /**
      * 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>`.
+     * which does proper inference via `Model<S, K>`.
      */
     allModelsOfType(modelClass: ModelConstructor<Model>, scope?: ModelScope): Model[];
     /** Error handler for fire-and-forget flushPendingDeltas calls */
@@ -688,7 +816,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     /** 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 handlePresenceUpdate(_data: PresenceUpdate): void;
     protected incrementPendingChanges(): void;
     protected decrementPendingChanges(): void;
     protected updateSyncStatus(updates: Partial<SyncStatus>): void;