@abloatai/ablo 0.25.0 → 0.27.0

package/dist/transactions/TransactionQueue.d.ts

@@ -1,11 +1,15 @@
 /**
- * TransactionQueue - Production-ready transaction management
+ * TransactionQueue manages the lifecycle of local writes on their way to the
+ * server: it applies each change optimistically, batches the writes made in one
+ * event-loop tick into a single commit, retries transient failures, and rolls
+ * back on permanent rejection.
  *
- * Key features:
- * - Optimistic updates with rollback
- * - Conflict resolution strategies
- * - LINEAR-style microtask batching (transactions in same event loop share batchId)
- * - Proper dependency injection (no singleton)
+ * Key behaviours:
+ * - Optimistic updates with rollback on failure.
+ * - Configurable conflict resolution.
+ * - Microtask batching: transactions created in the same event-loop tick share
+ *   a batch id and commit together in one round trip.
+ * - A dependency-injected executor, so several queues can coexist.
  */
 import { EventEmitter } from 'events';
 import type { Database } from '../Database.js';
@@ -13,59 +17,21 @@ import { Model } from '../Model.js';
 import { SyncPosition } from '../sync/syncPosition.js';
 import type { WriteOptions } from '../interfaces/index.js';
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
-export interface UserContext {
-    userId: string;
-    organizationId: string;
-    role?: string;
-    teamIds?: string[];
-}
-/** Wire-format mutation payload (post-projection). */
-type MutationInput = Record<string, unknown>;
-export interface Transaction {
-    id: string;
-    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-    modelName: string;
-    modelId: string;
-    modelKey: string;
-    data?: MutationInput;
-    previousData?: MutationInput | null;
-    context: UserContext;
-    status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed' | 'rolled_back';
-    createdAt: number;
-    attempts: number;
-    priority: 'normal' | 'high';
-    priorityScore: number;
-    writeOptions?: WriteOptions;
-    batchId?: string;
-    /** Completed locally without a server operation; no sync echo will arrive. */
-    localOnly?: boolean;
-    /** LINEAR PATTERN: syncId threshold - transaction confirms when delta.id >= this value */
-    syncIdNeededForCompletion?: number;
-    /**
-     * Resolves when the server has confirmed this transaction (delta arrived
-     * or HTTP ack). Rejects with the originating error if the transaction is
-     * permanently rolled back. Name matches the queue's existing `'confirmed'`
-     * status vocabulary (`commits.create({wait:'confirmed'})`,
-     * `waitForConfirmation`) — gives call sites a single `await` point for
-     * "did my write land?", so failures surface at the source instead of
-     * leaking via silent pool rollback. The rejection error is the same
-     * `AbloError` recorded on the queue's `transaction:failed` event.
-     */
-    confirmation?: Promise<void>;
-}
+import { type MutationInput, type Transaction, type UserContext } from './commitPayload.js';
+export type { Transaction, UserContext } from './commitPayload.js';
 /**
- * A raw multi-op commit transaction queued via `ablo.commits.create()`.
- *
- * Distinct from the per-model `Transaction` above: operations are
- * pre-built by the caller and the envelope is atomic — no coalescing,
- * no FK reordering, no optimistic local apply. The lane shares the
- * same `mutationExecutor.commit()` underneath as the model-proxy
- * batch path, so reconnect-retry behavior is identical.
+ * A pre-built, multi-operation commit submitted through
+ * `ablo.commits.create()`. Unlike the per-model {@link Transaction} (see
+ * `./commitPayload.js`), the caller supplies the operations and the whole
+ * envelope commits atomically: the queue does not coalesce it, reorder its
+ * operations for foreign keys, or apply it optimistically. It runs through the
+ * same `mutationExecutor.commit()` as the model batch path, so its
+ * retry-on-reconnect behaviour is identical.
  */
 interface CommitTransaction {
     id: string;
     kind: 'commit';
-    operations: Array<{
+    operations: {
         type: string;
         model: string;
         id: string;
@@ -73,9 +39,9 @@ interface CommitTransaction {
         transactionId?: string;
         readAt?: number | null;
         onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    }>;
+    }[];
     causedByTaskId?: string | null;
-    /** Batch-level read dependencies (STORM read-set), forwarded to the executor. */
+    /** Read dependencies for the whole batch, forwarded to the executor so the server can detect stale-context writes. */
     reads?: ReadDependency[] | null;
     status: 'pending' | 'executing' | 'completed' | 'failed';
     createdAt: number;
@@ -109,17 +75,16 @@ interface TransactionQueueConfig {
         capMs: number;
     };
     /**
-     * Grace window in ms before in-flight commit-lane transactions are
-     * failed with `AbloConnectionError` after the WebSocket transitions
-     * to `'disconnected'`. Brief disconnects (deploy rotations, mobile
-     * jitter) are absorbed transparently; only persistent disconnects
-     * surface as failures. Aligned with the 30s convention from the
-     * WebSocket reconnection guidance (websocket.org). Set lower for
-     * human-interactive consumers (e.g. 10s for chat) or higher for
-     * batch workers (e.g. 60s for agent-worker).
+     * How long, in milliseconds, to wait after the connection drops before
+     * failing any in-flight commit-lane transaction with an
+     * {@link AbloConnectionError}. Brief disconnects, such as a server restart
+     * or mobile network jitter, are absorbed transparently; only a disconnect
+     * that outlasts this window surfaces as a failure. Set it lower for
+     * interactive use (for example 10 seconds for chat) and higher for
+     * background batch work. Defaults to 30 seconds.
      *
-     * Without this deadline, `commits.create({wait:'confirmed'})` waits
-     * forever when the WS dies mid-flight — see the 2026-05-15 wedge.
+     * Without this deadline, `commits.create({ wait: 'confirmed' })` would wait
+     * forever if the connection died while a commit was in flight.
      */
     commitOfflineGraceMs: number;
 }
@@ -143,7 +108,6 @@ export declare class TransactionQueue extends EventEmitter {
     private computePriorityScore;
     private ensureDerivedFields;
     private entityKey;
-    private isTransactionForModel;
     private resolveConfirmation;
     private takeUnsentCreateForModel;
     private cancelUnsentCreateForDelete;
@@ -151,29 +115,24 @@ export declare class TransactionQueue extends EventEmitter {
     private completeLocalDelete;
     private deferDeleteUntilCreateSettles;
     private releaseDeferredDeletesForCreate;
-    private mergeUpdateData;
     private config;
     private executingCount;
     private optimisticUpdates;
     private commitNotifications;
-    private deltaConfirmationTimeouts;
-    private deltaConfirmationRetries;
+    private readonly deltaConfirmation;
     private isConnectedFn;
     private commitOfflineGraceTimer;
     /**
-     * THE client's place in the global delta order — the SHARED instance
-     * (injected by SyncClient; standalone construction gets its own). The
-     * queue advances `acked` on commit responses; the store advances
-     * `applied`/`persisted`; snapshots/claims read `readFloor`. Contract +
-     * rationale live in `sync/syncPosition.ts`.
+     * This client's place in the global order of sync deltas. The instance is
+     * shared: the client injects one, and a standalone queue creates its own. The
+     * queue advances the `acked` cursor as commit responses arrive, the store
+     * advances `applied` and `persisted`, and snapshots and claims read
+     * `readFloor`. See `../sync/syncPosition.js` for the full contract.
      */
     readonly position: SyncPosition;
     /** Applied-cursor alias, kept so the many internal read sites stay legible. */
     private get lastSeenSyncId();
     private noteAck;
-    private static readonly DELTA_MAX_RETRIES;
-    private static readonly DELTA_INITIAL_TIMEOUT_MS;
-    private static readonly DELTA_MAX_TIMEOUT_MS;
     private batchIndex;
     /**
      * Resolvers for per-transaction `confirmation` promises. Populated in
@@ -185,99 +144,104 @@ export declare class TransactionQueue extends EventEmitter {
     private confirmationResolvers;
     constructor(config?: Partial<TransactionQueueConfig>);
     /**
-     * Look up the in-flight `confirmation` promise for a (model, id) pair.
-     * Returns the promise from the most-recent live transaction matching
-     * the given model+id, or `Promise.resolve()` if none is open (which
-     * means either "already confirmed" or "never staged" — both safe
-     * outcomes for the routing-helper grace-window use case).
-     *
-     * Looks across `pending`, `executing`, and `awaiting_delta` — these
-     * are the three non-terminal statuses where rollback is still
-     * possible. Skips `completed` (already settled) and `failed` /
-     * `rolled_back` (already rejected; the call site missed the
-     * `confirmation` window and should rely on `onMutationFailure` toast
-     * instead).
+     * Returns the in-flight confirmation promise for a given model and id. When
+     * several transactions match, it returns the most recent one's promise; when
+     * none is open it resolves immediately, which covers both "already confirmed"
+     * and "never staged".
      *
-     * Distinct from `tx.confirmation` on a known transaction — used by
-     * call sites that hold a Model reference (returned by
-     * `ablo.<model>.create()`) but never see the underlying transaction.
+     * It considers the three non-terminal statuses in which the write can still
+     * be rolled back — `pending`, `executing`, and `awaiting_delta` — and ignores
+     * `completed` (already settled) and `failed`/`rolled_back` (already
+     * rejected). This complements the `confirmation` promise carried on a known
+     * {@link Transaction}: use this method at call sites that hold a model
+     * returned by `ablo.<model>.create()` but never see the underlying
+     * transaction.
      */
     confirmationFor(modelName: string, modelId: string): Promise<void>;
     /**
-     * Attach a hot `confirmation` promise to a freshly created transaction.
-     * Must be called BEFORE the transaction is staged so the call site can
-     * `await tx.confirmation` synchronously after the create/update/delete
-     * call returns. Idempotent: returns early if the tx already has one.
+     * Attaches a `confirmation` promise to a newly created transaction. Call this
+     * before the transaction is staged so a caller can `await tx.confirmation`
+     * immediately after a create, update, or delete returns. It is idempotent and
+     * returns early if one is already attached.
      *
-     * The unhandled-rejection trap is mandatory — most call sites won't
-     * `await confirmation`, and Node/browser would otherwise crash on the
-     * rejection. Consumers who *do* want failure visibility just attach a
-     * `.then`/`.catch` and the trap becomes a no-op.
+     * It also attaches a no-op rejection handler. Most callers never await the
+     * confirmation, and without this the runtime would report an unhandled
+     * rejection when a write fails. Callers that do want to observe failure simply
+     * attach their own `.then`/`.catch`.
      */
     private attachConfirmation;
     /**
-     * Set connection state checker - prevents rollbacks during disconnection.
-     * When disconnected, timeouts re-schedule instead of rolling back.
+     * Registers a predicate the queue uses to check whether it is connected.
+     * While disconnected, confirmation timeouts re-schedule themselves instead of
+     * escalating, so a transaction is never rolled back merely because the client
+     * was briefly offline.
      */
     setConnectionChecker(fn: () => boolean): void;
     /**
-     * Drive the offline-grace timer for in-flight commit-lane transactions.
-     *
-     * On `'disconnected'`: start a one-shot timer of
-     * `config.commitOfflineGraceMs`. If the timer fires (disconnect
-     * persisted past grace), iterate every commit-lane transaction with
-     * `status ∈ {'pending', 'executing'}` and emit
-     * `transaction:failed:${id}` with an `AbloConnectionError`. That
-     * lets `waitForCommitReceipt` reject in seconds instead of hanging
-     * forever — which is what wedged the 2026-05-15 subagent run.
+     * Drives the offline-grace timer for in-flight commit-lane transactions.
      *
-     * On `'connected'`: clear any pending grace timer. Brief blips are
-     * absorbed transparently; the existing reconnect-retry path in
-     * `processCommitLane` / `flushOfflineQueue` handles the resumption.
+     * On `'disconnected'` it starts a one-shot timer of
+     * `config.commitOfflineGraceMs`. If that timer fires — meaning the disconnect
+     * outlasted the grace window — every commit-lane transaction still `pending`
+     * or `executing` is failed with an {@link AbloConnectionError}, so
+     * {@link waitForCommitReceipt} rejects within seconds instead of hanging.
      *
-     * Called from SyncClient's `setConnectionState` after the
-     * `'connection:disconnected'` / `'connection:established'` events.
+     * On `'connected'` it clears any pending grace timer. Brief disconnects are
+     * absorbed transparently; {@link processCommitLane} and
+     * {@link flushOfflineQueue} resume the work on reconnect.
      */
     setConnectionState(state: 'connected' | 'disconnected'): void;
     private failInFlightCommitsOnOffline;
     /**
-     * Bind the executor for this queue instance. Called by the owning Ablo
-     * right after `BaseSyncedStore` is constructed so the executor's
-     * `storeHolder.store` closure resolves to *this* Ablo's WS — not whichever
-     * Ablo most recently called `initSyncEngine()`.
+     * Binds the mutation executor for this queue instance. The owning client
+     * calls this right after construction, so commits made here always dispatch
+     * through this instance's connection even when several client instances exist
+     * in the same process.
      */
     setMutationExecutor(executor: import('../interfaces/index.js').MutationExecutor): void;
     /**
-     * Stage a transaction for commit (Linear pattern)
-     * Transactions staged in the same event loop tick will be committed together
+     * Stages a transaction for commit. Transactions staged within the same
+     * event-loop tick are committed together.
      */
     private stageTransaction;
     /**
-     * Schedule commit of staged transactions via microtask
-     * This ensures all synchronous transaction creates are batched together
+     * Schedules the staged transactions to commit on a microtask, so all
+     * transactions created synchronously within one tick are batched together.
      */
     private scheduleCommit;
     /**
-     * Commit all staged transactions to the execution queue (Linear pattern)
-     * All transactions get the same batchIndex for efficient batching
+     * Moves all staged transactions onto the execution queue, assigning them a
+     * single shared batch index so they commit together.
      */
     private commitCreatedTransactions;
+    /**
+     * Flushes every pending transaction in one commit, the fast path taken on
+     * reconnect. If the batch fails, each transaction falls back to normal,
+     * one-by-one processing.
+     */
     flushOfflineQueue(): Promise<void>;
     /**
-     * Create operation with optimistic update
+     * Records a create and applies it optimistically, then stages it for the next
+     * batched commit. Returns the {@link Transaction}, whose `confirmation`
+     * promise settles once the server confirms the write.
      */
     create(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
-     * Update operation with conflict detection
-     * @param precomputedChanges - Optional pre-captured changes (avoids re-reading from model)
+     * Records an update and applies it optimistically, then stages it for the next
+     * batched commit. Rapid updates to the same entity coalesce into a single wire
+     * operation.
+     * @param precomputedChanges - Optional pre-captured changes, used instead of re-reading them from the model.
      */
     update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
-     * Delete operation with cascade handling
+     * Records a delete and applies it optimistically. If the row's own create has
+     * not yet been sent, both are cancelled locally rather than sending a create
+     * followed by a delete; if the create is already in flight, the delete waits
+     * until it settles so the server never sees a delete before the create.
      */
     delete(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
-     * Upload attachment — delegates to attachment-uploader.ts
+     * Uploads a single attachment, delegating to the mutation executor.
      */
     uploadAttachment(_file: File, options: {
         id: string;
@@ -286,76 +250,79 @@ export declare class TransactionQueue extends EventEmitter {
         url: string;
     } | null>;
     /**
-     * Batch upload attachments — delegates to MutationExecutor
+     * Uploads several attachments in one call, delegating to the mutation executor.
      */
-    batchUploadAttachments(_files: File[], items: Array<{
+    batchUploadAttachments(_files: File[], items: {
         id: string;
         [key: string]: unknown;
-    }>, _context: UserContext): Promise<Array<{
+    }[], _context: UserContext): Promise<{
         id: string;
         url: string;
-    }>>;
+    }[]>;
     /**
-     * Archive operation
+     * Records an archive and applies it optimistically, then stages it for the
+     * next batched commit.
      */
     archive(model: Model, context: UserContext, writeOptions?: WriteOptions): Promise<Transaction>;
     /**
-     * Unarchive operation
+     * Records an unarchive and applies it optimistically, then stages it for the
+     * next batched commit.
      */
     unarchive(model: Model, context: UserContext): Promise<Transaction>;
     /**
-     * Enqueue transaction for execution
+     * Places a transaction on the execution queue, coalescing it into an existing
+     * same-entity update where possible so redundant writes collapse.
      */
     private enqueue;
     private scheduleProcessing;
     /**
-     * Process batch of transactions using LINEAR-style unified batch execution.
-     *
-     * Key optimization: Instead of making separate calls per operation type/model,
-     * we collect ALL batchable operations and send them in a SINGLE commit call.
-     * The sync-server handles mixed types atomically inside one transaction.
-     *
-     * This reduces N round-trips to 1, dramatically improving batch latency.
+     * Processes one batch of transactions in a single commit. Rather than calling
+     * the server once per operation type or model, it collects every batchable
+     * operation and sends them together; the server applies the mixed operations
+     * atomically within one transaction. This turns many round trips into one and
+     * greatly reduces batch latency.
      */
     private processBatch;
     /**
-     * LINEAR PATTERN: Confirm all awaiting transactions when delta with syncId >= threshold arrives.
-     * This replaces clientMutationId echoing - transactions are confirmed by sync ID threshold.
-     * @param syncId - The sync ID of the received delta
+     * Confirms every awaiting transaction whose sync-id threshold this delta meets
+     * or exceeds. The confirmation policy and timeout tracking live in
+     * {@link DeltaConfirmationTracker} (`./deltaConfirmation.js`).
+     * @param syncId - The sync id of the received delta.
      */
     onDeltaReceived(syncId: number): void;
     private scheduleDeltaConfirmationTimeout;
-    private cancelDeltaConfirmationTimeout;
     /**
-     * Wait for a transaction to be confirmed via delta echo (Linear pattern)
-     * Reuses existing timeout mechanism from scheduleDeltaConfirmationTimeout
+     * Resolves once the given transaction is confirmed and rejects if it fails.
+     * The confirming delta's timeout is handled by
+     * {@link scheduleDeltaConfirmationTimeout}.
      */
     waitForConfirmation(transactionId: string): Promise<void>;
     hasClientMutationId(id: string): boolean;
     /**
-     * Enqueue a raw multi-op atomic commit envelope (the `ablo.commits.create`
-     * path). Operations are pre-built by the caller; the queue's job is
-     * retry-on-reconnect + idempotent dedup, NOT optimistic apply or FK
-     * ordering. Same idempotency key (clientTxId) is dropped on the floor
-     * if already in flight — server-side `mutation_log` handles cross-session
-     * dedup; this guard handles same-session double-enqueue.
+     * Enqueues a pre-built, multi-operation atomic commit — the
+     * `ablo.commits.create()` path. The caller supplies the operations; the queue
+     * only retries on reconnect and de-duplicates, and does not apply the change
+     * optimistically or reorder for foreign keys. A duplicate `clientTxId`
+     * already in flight is ignored: the server's `mutation_log` de-duplicates
+     * across sessions, and this guard covers a double-enqueue within one session.
      */
     enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
         causedByTaskId?: string | null;
         reads?: ReadDependency[] | null;
     }): void;
     /**
-     * Drain pending commit-lane envelopes serially. Transient failures
-     * (network, ws_not_ready) leave the head-of-queue tx in `pending` and
-     * break — reconnect handler re-kicks via `flushOfflineQueue`.
-     * Permanent failures emit `transaction:failed:<id>` and drop the tx.
+     * Drains the pending commit-lane envelopes one at a time. A transient
+     * failure, such as a network error, leaves the envelope at the head of the
+     * lane in `pending` and stops; reconnect re-kicks it through
+     * {@link flushOfflineQueue}. A permanent failure emits
+     * `transaction:failed:<id>` and drops the envelope.
      */
     private processCommitLane;
     /**
-     * Promise-based confirmation for a commit-lane transaction. Resolves
-     * with the server-side `lastSyncId` once `mutation_result` lands;
-     * rejects on permanent failure. Backs the `wait: 'confirmed'` semantics
-     * of `ablo.commits.create()`.
+     * Resolves once a commit-lane transaction is confirmed, returning the server's
+     * `lastSyncId` and any stale-context notifications; rejects on permanent
+     * failure. This backs the `wait: 'confirmed'` semantics of
+     * `ablo.commits.create()`.
      */
     waitForCommitReceipt(clientTxId: string): Promise<{
         lastSyncId: number;
@@ -363,80 +330,84 @@ export declare class TransactionQueue extends EventEmitter {
     }>;
     private isReorderPayload;
     /**
-     * Determine if an error is transient (retryable) vs permanent (non-retryable).
-     *
-     * IMPORTANT: Uses a BLOCKLIST approach for safety - only retry on known transient errors.
-     * Any unknown error type defaults to permanent (don't retry) to prevent infinite loops.
+     * Classifies an error as transient (worth retrying) or permanent. The
+     * approach is deliberately conservative: only known-transient errors are
+     * retried, and anything unrecognized is treated as permanent so a failing
+     * write cannot loop forever.
      *
-     * Transient errors (will retry):
-     * - Network failures, connection errors, timeouts
-     * - Server errors (5xx status codes)
-     * - Rate limiting (429)
+     * Transient (retried):
+     * - Network failures, connection errors, and timeouts.
+     * - Server errors (HTTP 5xx).
+     * - Rate limiting (HTTP 429).
      *
-     * Permanent errors (won't retry - includes but not limited to):
-     * - Validation errors, constraint violations
-     * - Not found, unauthorized, forbidden
-     * - Any other business logic error from the server
+     * Permanent (not retried), among others:
+     * - Validation errors and constraint violations.
+     * - Not found, unauthorized, and forbidden.
+     * - Any other business-logic error from the server.
      */
     private isPermanentError;
     /**
-     * Handle transaction failure
+     * Handles a failed transaction: retries transient failures with backoff and
+     * rolls back permanent ones, settling the transaction's confirmation promise
+     * either way.
      */
     private handleFailure;
     /**
-     * Conflict resolution
+     * Resolves a conflict against server data using the configured strategy:
+     * last-write-wins rolls the local change back, merge and reject re-enqueue it,
+     * and custom applies the caller's resolver.
      */
     handleConflict(transaction: Transaction, serverData: MutationInput): Promise<void>;
     /**
-     * Optimistic updates
+     * Optimistic updates. The apply and rollback rules live in `./optimisticApply.js`;
+     * these methods bind them to the queue's own tracking map and event emitter.
      */
     private applyOptimisticCreate;
     private applyOptimisticUpdate;
     private applyOptimisticDelete;
     private rollbackOptimistic;
     /**
-     * Execute individual transaction via the unified commit path
+     * Loads transactions persisted from a previous session and re-enqueues them,
+     * so writes made while offline survive a restart. Does nothing when
+     * persistence is disabled.
      */
-    private executeTransaction;
+    loadPersistedTransactions(database: Database): Promise<void>;
     /**
-     * Persistence
+     * Validates and rehydrates one persisted row. Rows written to the same store
+     * by other subsystems are skipped, and rows that fail the persisted
+     * transaction schema — from an older version or corruption — are dropped and
+     * reported rather than replayed as commits.
      */
-    loadPersistedTransactions(database: Database): Promise<void>;
     private deserializeTransaction;
     /**
-     * Cancel transactions for a specific model
+     * Cancels every pending or executing transaction for a given model id,
+     * optionally limited to one operation type, rolling back their optimistic
+     * state. Returns the cancelled transactions.
      */
     cancelTransactionsForModel(modelId: string, transactionType?: string): Transaction[];
     /**
-     * LINEAR PATTERN: Cancel transactions for child entities by foreign key
-     *
-     * Used by SyncedStore for cascade cancellation when a parent is deleted.
-     * This keeps FK relationship knowledge in ModelRegistry/SyncedStore,
-     * while TransactionQueue just handles the cancellation mechanics.
+     * Cancels pending transactions for child rows that reference a deleted parent,
+     * used to cascade a parent deletion. The caller supplies the foreign-key
+     * relationship; this method performs the cancellation.
      *
-     * @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 deleted parent's id.
+     * @returns The number of transactions cancelled.
      */
     cancelTransactionsByForeignKey(childModelName: string, foreignKey: string, parentId: string): number;
     /**
-     * Get count of outstanding transactions
+     * Returns the number of transactions still pending or executing.
      */
     getOutstandingTransactionCount(): number;
-    /**
-     * Utilities
-     */
+    /** Generates a unique local transaction id. */
     private generateId;
     private mergeData;
     private extractCreateData;
     private mapChangesToInput;
     private extractUpdateData;
-    private buildUpdateInput;
     private extractPreviousData;
-    /**
-     * Public API
-     */
+    /** Returns a snapshot of queue counts and the current configuration. */
     getStats(): {
         pending: number;
         executing: number;
@@ -467,24 +438,23 @@ export declare class TransactionQueue extends EventEmitter {
                 capMs: number;
             };
             /**
-             * Grace window in ms before in-flight commit-lane transactions are
-             * failed with `AbloConnectionError` after the WebSocket transitions
-             * to `'disconnected'`. Brief disconnects (deploy rotations, mobile
-             * jitter) are absorbed transparently; only persistent disconnects
-             * surface as failures. Aligned with the 30s convention from the
-             * WebSocket reconnection guidance (websocket.org). Set lower for
-             * human-interactive consumers (e.g. 10s for chat) or higher for
-             * batch workers (e.g. 60s for agent-worker).
+             * How long, in milliseconds, to wait after the connection drops before
+             * failing any in-flight commit-lane transaction with an
+             * {@link AbloConnectionError}. Brief disconnects, such as a server restart
+             * or mobile network jitter, are absorbed transparently; only a disconnect
+             * that outlasts this window surfaces as a failure. Set it lower for
+             * interactive use (for example 10 seconds for chat) and higher for
+             * background batch work. Defaults to 30 seconds.
              *
-             * Without this deadline, `commits.create({wait:'confirmed'})` waits
-             * forever when the WS dies mid-flight — see the 2026-05-15 wedge.
+             * Without this deadline, `commits.create({ wait: 'confirmed' })` would wait
+             * forever if the connection died while a commit was in flight.
              */
             commitOfflineGraceMs: number;
         };
     };
     /**
-     * Get detailed debug info for the sync debug page
-     * Exposes internal state that helps diagnose delta confirmation issues
+     * Returns detailed internal state — pending, executing, and awaiting-delta
+     * transactions — to help diagnose delta-confirmation issues.
      */
     getDebugInfo(): {
         lastSeenSyncId: number;
@@ -511,12 +481,11 @@ export declare class TransactionQueue extends EventEmitter {
             modelId: string;
         }[];
     };
-    /**
-     * Set configuration
-     */
+    /** Merges the given options into the queue's configuration. */
     setConfig(config: Partial<TransactionQueueConfig>): void;
     /**
-     * Handle incoming sync delta - simplified for permanent IDs
+     * Re-emits an incoming sync delta on the `sync:delta` event for the store to
+     * apply. Because rows use stable ids, no id reconciliation is needed here.
      */
     handleSyncDelta(delta: {
         id: string;
@@ -525,8 +494,8 @@ export declare class TransactionQueue extends EventEmitter {
         data: any;
     }): boolean;
     /**
-     * Cleanup and dispose resources
+     * Releases the queue's resources: rolls back outstanding optimistic updates,
+     * clears all timers and stored transactions, and removes event listeners.
      */
     dispose(): void;
 }
-export {};