@abloatai/ablo 0.26.0 → 0.27.0

package/dist/SyncClient.d.ts

@@ -1,17 +1,17 @@
 /**
- * SyncClient - Mutation and offline queue manager
- *
- * Responsibilities:
- * - Handle model mutations (create, update, delete, archive)
- * - Manage offline mutation queue with persistence
- * - Send mutations to server via API client
- * - Handle conflict resolution for local changes
+ * Applies model mutations and manages the offline write queue. The
+ * SyncClient turns local create, update, delete, and archive calls into
+ * optimistic changes, holds them while the client is offline, sends them to
+ * the server when connectivity returns, and resolves conflicts when the
+ * server's version of a row disagrees with the local one. It sits between the
+ * reactive object pool and the {@link TransactionQueue} that delivers writes
+ * over the network.
  */
-import { ObjectPool } from './ObjectPool.js';
+import { InstanceCache } from './InstanceCache.js';
 import { Model } from './Model.js';
 import { EventEmitter } from 'events';
 import { TransactionQueue } from './transactions/TransactionQueue.js';
-import { type OptimisticEchoMetrics } from './transactions/OptimisticEchoTracker.js';
+import { type UnconfirmedWritesMetrics } from './transactions/UnconfirmedWrites.js';
 import type { Database } from './Database.js';
 import type { WriteOptions } from './interfaces/index.js';
 import { SyncPosition } from './sync/syncPosition.js';
@@ -50,33 +50,29 @@ export declare class SyncClient extends EventEmitter {
     private organizationId;
     private pendingMutations;
     /**
-     * Tracks transaction ids the client has optimistically applied but
-     * the server has not yet confirmed. The receive path consults it
-     * to recognize delta echoes of own mutations and suppress the
-     * (otherwise-redundant) pool mutation — the IDB write still runs
-     * because the delta is the authoritative version of the row.
+     * Tracks the ids of transactions the client has applied optimistically but
+     * the server has not yet confirmed. When a delta arrives, the receive path
+     * consults this set to recognize the echo of the client's own mutation and
+     * skip the now-redundant pool update; the IndexedDB write still runs,
+     * because the delta is the authoritative version of the row. Without this
+     * discriminator, an optimistically applied delete followed by a
+     * server-confirmed create echo would resurrect the row for the window
+     * between the two confirmations.
      *
-     * The receive-layer discriminator named in
-     * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. Without
-     * it, an optimistically-applied DELETE followed by a
-     * server-confirming CREATE echo resurrects the row for the window
-     * between the two confirmations (the chart-delete flicker).
-     *
-     * Bounded with FIFO eviction; observability via `getEchoMetrics()`.
+     * The set is bounded with first-in-first-out eviction, and
+     * {@link SyncClient.getEchoMetrics} exposes its counters.
      */
     private readonly echoTracker;
     private connectionState;
-    private offlineSince?;
-    private maxRetries;
     private isDisposed;
     /**
-     * THE client's place in the global delta order — the one canonical
-     * instance (see `sync/syncPosition.ts`). The store advances
-     * `applied`/`persisted` as deltas land; the queue advances `acked` on
-     * commit responses; snapshots/claims read `readFloor`.
+     * The client's position in the global delta order, held as the single
+     * canonical {@link SyncPosition} instance. The store advances `applied` and
+     * `persisted` as deltas land, the queue advances `acked` on commit
+     * responses, and snapshots and claims read `readFloor`.
      */
     readonly position: SyncPosition;
-    constructor(objectPool: ObjectPool, database: Database);
+    constructor(objectPool: InstanceCache, database: Database);
     /**
      * Setup network monitoring handlers
      */
@@ -104,20 +100,20 @@ export declare class SyncClient extends EventEmitter {
      */
     private setupTransactionRollbackHandling;
     /**
-     * Forward reconciliation requests from TransactionQueue to the sync layer.
-     * When delta confirmation times out, TransactionQueue emits 'reconciliation:needed'
-     * instead of rolling back — following the Replicache/PowerSync pattern of never
-     * destroying optimistic state that the server may have committed.
+     * Forward reconciliation requests from the {@link TransactionQueue} to the
+     * sync layer. When delta confirmation times out, the queue emits
+     * `reconciliation:needed` instead of rolling back, so optimistic state the
+     * server may already have committed is never destroyed.
      */
     private setupReconciliationForwarding;
     /**
-     * LINEAR PATTERN: Persist unconfirmed transactions to IndexedDB.
-     * When delta confirmation retries exhaust, the transaction data is cached in IDB
-     * so it survives tab close. On next session, WebSocket reconnect + delta catch-up
-     * will deliver the missing deltas and naturally confirm the transaction.
+     * Persist unconfirmed transactions to IndexedDB. When delta-confirmation
+     * retries are exhausted, the transaction is cached so it survives a tab
+     * close. On the next session, a WebSocket reconnect and delta catch-up
+     * deliver the missing deltas and confirm the transaction.
      */
     private setupAwaitingTransactionPersistence;
-    /** Persist an unconfirmed transaction to IDB (never rejects — failures are captured). */
+    /** Persist an unconfirmed transaction to IndexedDB (never rejects — failures are captured). */
     private persistAwaitingTransaction;
     /** Drop the persisted awaiting-row once confirmed (never rejects). */
     private removeAwaitingTransaction;
@@ -135,7 +131,7 @@ export declare class SyncClient extends EventEmitter {
      * Self-healing helper for individual model records.
      *
      * Two registry-driven repair passes run on every row hydrated from
-     * IDB or merged from a delta:
+     * IndexedDB or merged from a delta:
      *
      * 1. **Auto-fill** — for each `autoFill` rule the consumer's schema
      *    declares on this model, copy the corresponding identity value
@@ -156,12 +152,12 @@ export declare class SyncClient extends EventEmitter {
         healed: boolean;
     } | null;
     /**
-     * Hydrate ObjectPool with data from Database
+     * Hydrate InstanceCache with data from Database
      * Called after bootstrap is complete
      */
     hydrateFromDatabase(): Promise<void>;
     /**
-     * Re-hydrate ObjectPool from IndexedDB when the pool already has data.
+     * Re-hydrate InstanceCache from IndexedDB when the pool already has data.
      *
      * Unlike hydrateFromDatabase() (which uses addBatch and skips existing IDs),
      * this method properly:
@@ -172,13 +168,14 @@ export declare class SyncClient extends EventEmitter {
      */
     rehydrateFromDatabase(): Promise<RehydrationStats>;
     /**
-     * Mutate model optimistically and queue for server sync.
-     * IndexedDB is only updated when server confirms via delta packet.
-     *
-     * CRITICAL: Changes are captured BEFORE poolAction to prevent data loss.
-     * The captured changes are frozen and passed to queueMutation.
+     * Apply a mutation to a model optimistically and queue it for server sync.
+     * IndexedDB is updated only once the server confirms the change with a delta
+     * packet.
      *
-     * @see src/sync-engine/types/TrackableModel.ts for change capture pattern
+     * A model's changes are captured before the pool action runs, because a pool
+     * operation such as an upsert can clear the model's local change set;
+     * capturing first ensures those changes are never lost. The captured set is
+     * frozen and handed to {@link queueMutation}.
      */
     private mutate;
     private pendingChangedTypes;
@@ -210,8 +207,9 @@ export declare class SyncClient extends EventEmitter {
      */
     private clearPendingMutationsForModel;
     /**
-     * Upload file and create attachment (UPLOAD operation)
-     * Uses Linear-style pattern with immediate URL generation
+     * Upload a file and create its attachment record. The upload runs through
+     * the {@link TransactionQueue}, and a model is built from the server's
+     * response and added to the pool.
      */
     uploadFile(file: File, options: {
         id: string;
@@ -239,16 +237,17 @@ export declare class SyncClient extends EventEmitter {
     /** Archive model (ARCHIVE) - works offline */
     archive(model: Model): void;
     /**
-     * Append a mutation and schedule its sync work.
+     * Append a mutation to the pending queue and schedule its sync work.
      *
-     * IDB persistence and the server push are deferred to a microtask so N
-     * pushes inside the same tick collapse into ONE IDB serialization + ONE
-     * process call. Without the deferral, queueing 100 mutations (paste,
-     * PPTX import, AI sandbox layer creation) reserializes the entire
-     * growing queue 100× — O(N²) `model.toJSON()`.
+     * IndexedDB persistence and the server push are deferred to a microtask, so
+     * many pushes within the same tick collapse into a single serialization and
+     * a single process call. Without the deferral, queueing a hundred mutations
+     * at once — a large paste, a document import, bulk layer creation — would
+     * reserialize the whole growing queue a hundred times, an O(N²) cost in
+     * `model.toJSON()`.
      *
-     * @param mutation.capturedChanges - Pre-captured changes (frozen), used
-     *   to avoid re-reading changes after pool ops that might clear them.
+     * @param mutation.capturedChanges - Pre-captured, frozen changes, used to
+     *   avoid re-reading a model after pool operations that might clear them.
      */
     private queueMutation;
     private syncScheduled;
@@ -258,12 +257,13 @@ export declare class SyncClient extends EventEmitter {
      */
     private persistMutationQueue;
     /**
-     * Restore mutation queue from IndexedDB.
+     * Restore the mutation queue from IndexedDB.
      *
-     * The persisted record was written by a PREVIOUS session (possibly an older
-     * SDK build), so each entry is validated at this replay boundary (T1.8):
-     * corrupt entries are dropped + logged at debug, and a failure never
-     * vanishes into an empty catch — offline write survival must be observable.
+     * The persisted record was written by an earlier session, possibly by an
+     * older build of the SDK, so each entry is validated as it is replayed:
+     * corrupt entries are dropped and logged at debug level, and a failure is
+     * never swallowed silently, because the survival of offline writes must be
+     * observable.
      */
     private restoreMutationQueue;
     /**
@@ -281,17 +281,16 @@ export declare class SyncClient extends EventEmitter {
      */
     private stageMutation;
     /**
-     * Resolve conflicts between local and server data
-     * Used when processing deltas from WebSocket
-     *
-     * CRITICAL: Always respects certain server states (deletes, deactivations)
-     * even when there are local changes, to maintain data consistency.
+     * Resolve a conflict between the local model and incoming server data,
+     * called while processing deltas from the WebSocket. Certain server states,
+     * such as deletions and deactivations, always take precedence even when the
+     * local model has unsynced changes, so the two sides stay consistent.
      */
     resolveConflicts(localModel: Model, serverData: Record<string, unknown>): Model;
     /**
-     * Extract critical state fields from server data
-     * These are states that must always be respected, even with local changes.
-     * The conflict brain reads exactly these known fields — nothing else.
+     * Extract the critical state fields from server data. These are the states
+     * that must be honored even when the local model has unsynced changes. The
+     * conflict resolver reads exactly these fields and no others.
      */
     private extractCriticalState;
     /**
@@ -344,26 +343,26 @@ export declare class SyncClient extends EventEmitter {
      */
     dispose(): void;
     /**
-     * LINEAR PATTERN: Notify TransactionQueue of incoming delta for sync ID threshold confirmation.
-     * Transactions are confirmed when any delta with id >= their lastSyncId threshold arrives.
-     * @param syncId - The sync ID of the received delta
+     * Notify the {@link TransactionQueue} of an incoming delta so it can confirm
+     * transactions by sync-id threshold. A transaction is confirmed once any
+     * delta with an id at or beyond its `lastSyncId` threshold arrives.
+     * @param syncId - The sync id of the received delta.
      */
     onDeltaReceived(syncId: number): void;
     /**
-     * LINEAR PATTERN: Cancel transactions for orphaned child entities
-     *
-     * Called by SyncedStore when a DELETE delta arrives for a parent entity.
-     * Cancels pending transactions for children that reference the deleted parent.
+     * Cancel pending transactions for child entities orphaned by a parent's
+     * deletion. The store calls this when a delete delta arrives for a parent,
+     * cancelling any queued writes on children that reference it.
      *
-     * @param childModelName - The child model type (e.g., 'SlideLayer')
-     * @param foreignKey - The FK property name (e.g., 'slideId')
-     * @param parentId - The deleted parent's ID
-     * @returns Number of transactions cancelled
+     * @param childModelName - The child model type (for example, `SlideLayer`).
+     * @param foreignKey - The foreign-key property name (for example, `slideId`).
+     * @param parentId - The id of the deleted parent.
+     * @returns The number of transactions cancelled.
      */
     cancelTransactionsByForeignKey(childModelName: string, foreignKey: string, parentId: string): number;
     /**
-     * Wait for a transaction to be confirmed via delta echo (Linear pattern)
-     * Delegates to TransactionQueue which already handles timeouts
+     * Wait for a transaction to be confirmed by its delta echo. Delegates to the
+     * {@link TransactionQueue}, which handles the confirmation timeout.
      */
     waitForDeltaConfirmation(transactionId: string): Promise<void>;
     /**
@@ -373,12 +372,12 @@ export declare class SyncClient extends EventEmitter {
     /**
      * Get sync statistics. Return type is inferred from the literal so
      * the call site sees the actual shape — `connectionState` narrowed
-     * to its three states, `objectPoolStats` typed by `ObjectPool.getStats`.
+     * to its three states, `objectPoolStats` typed by `InstanceCache.getStats`.
      */
     getSyncStats(): {
         connectionState: 'connected' | 'disconnected' | 'connecting';
         pendingMutations: number;
-        objectPoolStats: ReturnType<ObjectPool['getStats']>;
+        objectPoolStats: ReturnType<InstanceCache['getStats']>;
     };
     /**
      * Get pending transaction count from TransactionQueue
@@ -396,10 +395,10 @@ export declare class SyncClient extends EventEmitter {
      * can render typed UI (toast keyed by `AbloError.type`, route-level
      * "this entity reverted" boundaries, telemetry).
      *
-     * Distinct from `onTransactionEvent('failed', cb)`, which exists only
-     * for the legacy parameterless `pendingChanges` counter and intentionally
-     * drops the payload. The two coexist — keep the counter callback fast
-     * and the typed listener for user-visible surfaces.
+     * Distinct from `onTransactionEvent('failed', cb)`, which serves the
+     * parameterless `pendingChanges` counter and intentionally drops the
+     * payload. The two coexist: the counter callback stays lightweight, while
+     * this typed listener drives user-visible surfaces.
      */
     onMutationFailure(listener: (payload: {
         transaction: import('./transactions/TransactionQueue.js').Transaction;
@@ -407,15 +406,16 @@ export declare class SyncClient extends EventEmitter {
         permanent?: boolean;
     }) => void): () => void;
     /**
-     * Subscribe to LOCAL transaction creation with the full {@link Transaction}
+     * Subscribe to local transaction creation with the full {@link Transaction}
      * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
-     * the feed `BaseSyncedStore.subscribeLocalMutations` taps for undo recording.
+     * the feed the store's local-mutation subscription taps for undo recording.
      *
-     * MUST subscribe to the TransactionQueue's emitter directly — that is the
-     * ONLY emitter that fires `transaction:created`. SyncClient's own emitter
-     * (reached via `subscribe()`) never re-broadcasts it, so routing undo through
-     * `subscribe('transaction:created')` silently records nothing. Mirrors
-     * `onMutationFailure`, which taps the queue for the same reason.
+     * It subscribes to the {@link TransactionQueue}'s emitter directly, since
+     * that is the only emitter that fires `transaction:created`. The SyncClient's
+     * own emitter (reached through {@link subscribe}) never rebroadcasts that
+     * event, so routing undo through `subscribe('transaction:created')` would
+     * record nothing. {@link onMutationFailure} taps the queue for the same
+     * reason.
      */
     onLocalTransaction(listener: (tx: import('./transactions/TransactionQueue.js').Transaction) => void): () => void;
     /**
@@ -464,9 +464,9 @@ export declare class SyncClient extends EventEmitter {
     unassignEntity(entityType: string, entityId: string): Promise<void>;
     reassignEntity(entityType: string, entityId: string, assigneeType: string, assigneeId: string, id?: string): Promise<void>;
     /**
-     * Apply a batch of delta results from Database to the ObjectPool.
+     * Apply a batch of delta results from Database to the InstanceCache.
      * Owns: model creation, upsert, remove, archive, conflict resolution.
-     * Returns: nothing — ObjectPool is updated in place.
+     * Returns: nothing — InstanceCache is updated in place.
      */
     /**
      * Mark a local transaction as optimistically applied. The matching
@@ -482,14 +482,14 @@ export declare class SyncClient extends EventEmitter {
      * — a sustained `evictions > 0` rate or `rollbacks` spike is a
      * health signal worth alerting on.
      */
-    getEchoMetrics(): Readonly<OptimisticEchoMetrics>;
+    getEchoMetrics(): Readonly<UnconfirmedWritesMetrics>;
     /**
-     * Package-internal accessor for the TransactionQueue. Used by
-     * `Ablo.commits.create()` to route raw multi-op envelopes through the
-     * same retry-on-reconnect lane as the Model proxy path, and by tests
-     * to exercise the queue ↔ markTransactionPending wiring on the real
-     * instance the SyncClient subscribes to. NOT re-exported to SDK
-     * consumers — `Ablo` itself is the public surface.
+     * Package-internal accessor for the {@link TransactionQueue}. Used by
+     * `Ablo.commits.create()` to route raw multi-operation envelopes through the
+     * same retry-on-reconnect lane as the model proxy path, and by tests to
+     * exercise the queue's interaction with {@link markTransactionPending} on the
+     * real instance the SyncClient subscribes to. It is not re-exported to SDK
+     * consumers; `Ablo` is the public surface.
      */
     getTransactionQueue(): TransactionQueue;
     applyDeltaBatchToPool(dbResults: {
@@ -507,7 +507,7 @@ export declare class SyncClient extends EventEmitter {
         transactionId?: string;
     }[], enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
     /**
-     * Apply bootstrap data to the ObjectPool with ghost removal.
+     * Apply bootstrap data to the InstanceCache with ghost removal.
      * Owns: model creation, batch upsert, ghost detection + removal.
      */
     applyBootstrapDataToPool(bootstrapData: {
@@ -515,13 +515,13 @@ export declare class SyncClient extends EventEmitter {
         failedModels?: string[];
     }, protectedIds?: ReadonlySet<string>, options?: {
         /**
-         * SCOPED backfill (P4 hydrate-on-enter): the snapshot covers only the
-         * groups just entered, NOT the whole type. Two behaviors change to keep
-         * it from corrupting the pool:
-         *   - upsert is version-guarded ({@link ObjectPool.upsertIfNewer}) so a
-         *     concurrent live delta isn't clobbered back to the snapshot version;
-         *   - ghost removal is SKIPPED — a subset snapshot must never evict rows
-         *     of the same type that belong to other (unhydrated) groups.
+         * Scoped backfill for the hydrate-on-enter path: the snapshot covers only
+         * the groups just entered, not the whole model type. Two behaviors change
+         * so the subset cannot corrupt the pool. First, the upsert is
+         * version-guarded ({@link InstanceCache.upsertIfNewer}) so a concurrent live
+         * delta is not clobbered back to the snapshot version. Second, ghost
+         * removal is skipped, because a subset snapshot must never evict rows of
+         * the same type that belong to other, unhydrated groups.
          */
         scoped?: boolean;
     }): {