@abloatai/ablo 0.26.0 → 0.28.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';
@@ -14,22 +18,23 @@ import { SyncPosition } from '../sync/syncPosition.js';
 import type { WriteOptions } from '../interfaces/index.js';
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import { type MutationInput, type Transaction, type UserContext } from './commitPayload.js';
+import { type DurableCommitEnvelope, type DurableCommitOperation, type CommitOutboxScope } from './commitEnvelope.js';
+import type { CommitOutboxStore } from './commitOutboxStore.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` (see `./commitPayload.js`):
- * 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: {
-        type: string;
+        type: DurableCommitOperation['type'];
         model: string;
         id: string;
         input?: Record<string, unknown>;
@@ -38,13 +43,19 @@ interface CommitTransaction {
         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;
     attempts: number;
     lastSyncId?: number;
     error?: Error;
+    sealedAt: number;
+    sequence: number;
+    sealPromise?: Promise<void>;
+    durableEnvelope?: DurableCommitEnvelope;
+    /** Journal entries atomically consumed when this request was sealed. */
+    sourceMutationIds?: string[];
 }
 interface ConflictResolution {
     strategy: 'last-write-wins' | 'merge' | 'reject' | 'custom';
@@ -72,21 +83,21 @@ 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;
 }
 export declare class TransactionQueue extends EventEmitter {
+    private static readonly DURABLE_REPLAY_WINDOW_MS;
     private store;
     private lastPermanentErrorSig?;
     private _mutationExecutor;
@@ -103,6 +114,15 @@ export declare class TransactionQueue extends EventEmitter {
     private commitLane;
     private commitStore;
     private commitProcessing;
+    private lastCommitSequence;
+    private durableReplayBlock;
+    /** Browser-backed strict outbox; absent for standalone/in-memory consumers. */
+    private commitOutbox;
+    private commitOutboxScope;
+    private nextCommitSequence;
+    private emitCommitLifecycle;
+    private assertDurableReplayOpen;
+    private assertEnvelopeInsideReplayWindow;
     private computePriorityScore;
     private ensureDerivedFields;
     private entityKey;
@@ -121,17 +141,49 @@ export declare class TransactionQueue extends EventEmitter {
     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 batchIndex;
+    /** Mints the request identity once; retry paths only read the stored value. */
+    private generateCommitIdempotencyKey;
+    /**
+     * Binds an ordered transaction batch to one wire-level idempotency key.
+     * Existing envelopes are validated and restored to their original order;
+     * they are never extended with newly queued work.
+     */
+    private ensureCommitEnvelope;
+    /** Bind the strict local outbox used before any mutation reaches the wire. */
+    setCommitOutbox(outbox: CommitOutboxStore): void;
+    setCommitOutboxScope(scope: CommitOutboxScope): void;
+    private sourceMutationIdsFor;
+    /**
+     * Atomically replaces staged mutation journal rows with one exact request.
+     * The returned operations are the JSON-normalized values that must be sent;
+     * callers never send a separately reconstructed payload after sealing.
+     */
+    private sealDurableCommit;
+    /** Best-effort cleanup after a definitive result; replay is safe if it fails. */
+    private removeDurableCommit;
+    /**
+     * Takes either one complete retry envelope or a fresh batch. A retry waits
+     * until every original member has re-entered the queue, preventing an
+     * ambiguous A+B commit from being replayed later as A and B separately.
+     */
+    private takeNextExecutionBatch;
+    /**
+     * Selects one reconnect batch without changing the request identity of work
+     * that was already attempted. Explicit caller keys remain one-call batches;
+     * an existing envelope is replayed only with all of its original members.
+     */
+    private takeOfflineFlushBatch;
     /**
      * Resolvers for per-transaction `confirmation` promises. Populated in
      * `attachConfirmation` at staging time, consumed by the constructor-time
@@ -142,99 +194,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.
+     * Drives 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.
+     * 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.
      *
-     * On `'connected'`: clear any pending grace timer. Brief blips are
-     * absorbed transparently; the existing reconnect-retry path in
-     * `processCommitLane` / `flushOfflineQueue` handles the resumption.
-     *
-     * 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 transport fails, the transactions retain this exact commit
+     * envelope when they fall back to normal queue 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>;
+    create(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): 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>;
+    update(model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions, sourceMutationId?: string): 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>;
+    delete(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<Transaction>;
     /**
-     * Upload attachment — delegates to attachment-uploader.ts
+     * Uploads a single attachment, delegating to the mutation executor.
      */
     uploadAttachment(_file: File, options: {
         id: string;
@@ -243,7 +300,7 @@ 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: {
         id: string;
@@ -253,66 +310,69 @@ export declare class TransactionQueue extends EventEmitter {
         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>;
+    archive(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): 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.
-     * Policy + timeout maps live in the `./deltaConfirmation.js` leaf.
-     * @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;
     /**
-     * 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;
+    }): Promise<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;
@@ -320,88 +380,92 @@ 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;
+    /** True only when the server definitively rejected before applying. */
+    private isDefinitiveRejection;
     /**
-     * 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 — apply/rollback rules live in `./optimistic.js`;
-     * these delegates bind the host-owned ledger + event emitter.
+     * 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
+     * Restore exact sealed requests after the local database is open. Sealed
+     * envelopes replay through the atomic commit lane and are never re-projected
+     * through model/schema state from the new process.
      */
-    loadPersistedTransactions(database: Database): Promise<void>;
+    restoreDurableCommits(): Promise<Set<string>>;
     /**
-     * Validate + rehydrate one persisted row (the T1.8 IDB replay boundary).
-     * Rows written by other subsystems into the same store (`'queue'`,
-     * `'awaiting_delta'`) are skipped silently; rows that fail the
-     * persisted-transaction schema (older SDK versions, corruption) are
-     * DROPPED with an observability capture instead of replayed as commits.
+     * 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.
      */
     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;
@@ -432,24 +496,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;
@@ -476,12 +539,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;
@@ -490,7 +552,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;
 }