@abloatai/ablo 0.36.0 → 0.37.1

package/dist/transactions/mutations/MutationQueue.d.ts

@@ -1,661 +0,0 @@
-/**
- * MutationQueue 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 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';
-import { Model } from '../../Model.js';
-import type { RuntimeContext } from '../../RuntimeContext.js';
-import { LogPosition } from '../../transaction/logPosition.js';
-import type { WriteOptions } from '../../interfaces/index.js';
-import type { OnStaleMode, StaleNotification, ReadDependency, TrackDependency } from '../../transaction/coordination/schema.js';
-import { type MutationInput, type QueuedMutation, type UserContext } from './commitPayload.js';
-import { type DurableCommitEnvelope, type DurableCommitOperation, type CommitOutboxScope } from '../../transaction/transactions/settlement/commitEnvelope.js';
-import type { DurableWriteStore } from './durableWriteStore.js';
-export type { QueuedMutation, UserContext } from './commitPayload.js';
-/**
- * A pre-built, multi-operation commit submitted through
- * `ablo.commits.create()`. Unlike the per-model {@link QueuedMutation} (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: DurableCommitOperation['type'];
-        model: string;
-        id: string;
-        input?: Record<string, unknown>;
-        transactionId?: string;
-        readAt?: number | null;
-        onStale?: OnStaleMode | null;
-    }[];
-    /** The premise for the whole batch, forwarded to the executor so the server can detect stale-context writes. */
-    reads?: ReadDependency[] | null;
-    /** Durable premises (`track`) to register for the batch's participant, forwarded to the executor. */
-    track?: TrackDependency[] | null;
-    status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed';
-    createdAt: number;
-    attempts: number;
-    /**
-     * Transient failures that were NOT the transport being down. Waiting out a
-     * dropped connection is unbounded on purpose — that is what lets a commit
-     * survive a reconnect — so connection errors are deliberately not counted
-     * here, and only a server that keeps rejecting can exhaust the lane.
-     */
-    transientAttempts?: number;
-    lastSyncId?: number;
-    /** Opaque customer-side batch ledger key returned by a queued receipt. */
-    correlationId?: string;
-    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';
-    resolver?: (local: MutationInput | undefined, remote: MutationInput) => MutationInput;
-}
-interface MutationQueueConfig {
-    /** Shared client position (see logPosition.ts). One per client. */
-    position?: LogPosition;
-    /** The owning client's runtime. Defaults to the module-global bridge. */
-    runtime?: RuntimeContext;
-    maxBatchSize: number;
-    batchDelay: number;
-    maxRetries: number;
-    conflictResolution: ConflictResolution;
-    enablePersistence: boolean;
-    enableOptimistic: boolean;
-    maxExecutingTransactions: number;
-    deltaConfirmationTimeout: number;
-    /**
-     * Exponential backoff for retryable server responses (HTTP 429/503).
-     * `baseMs` is the first retry delay; each subsequent attempt doubles
-     * up to `capMs`. Final delay = min(capMs, baseMs * 2^(attempt-1)) +
-     * up to 100ms of jitter. Defaults: 200ms / 1500ms.
-     */
-    retryBackoff: {
-        baseMs: number;
-        capMs: number;
-    };
-    /**
-     * 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' })` would wait
-     * forever if the connection died while a commit was in flight.
-     */
-    commitOfflineGraceMs: number;
-    /**
-     * How long, in milliseconds, to wait for the transport to acknowledge a
-     * dispatched commit before treating the silence as a retryable no-receipt
-     * failure. A transport that never answers — a half-open socket, a dropped
-     * response frame — would otherwise hold the commit in flight forever, and
-     * with it the client's staged-batch lock: every later write in the session
-     * queues silently behind the unanswered one. The envelope's idempotency key
-     * is stable across retries, so a commit the server DID apply before the
-     * timeout is deduplicated on the retry rather than double-applied.
-     * Defaults to 30 seconds. Set `0` to disable the bound.
-     */
-    commitDispatchTimeoutMs: number;
-}
-export declare class MutationQueue extends EventEmitter {
-    private static readonly DURABLE_REPLAY_WINDOW_MS;
-    private store;
-    private lastPermanentErrorSig?;
-    private _mutationExecutor;
-    private get mutationExecutor();
-    private readonly runtime;
-    private executionQueue;
-    private isProcessing;
-    private processTimer?;
-    private processScheduled;
-    private createdTransactions;
-    private commitScheduled;
-    private inFlightByModel;
-    private pendingMergeByModel;
-    private deferredDeletesByCreate;
-    private commitLane;
-    private commitStore;
-    /**
-     * Small race buffer for authoritative echoes that arrive before the queued
-     * mutation receipt. The forward and WAL stream are independent channels, so
-     * either can win without changing the settlement result.
-     */
-    private recentDeltaCorrelations;
-    /**
-     * Client-facing confirmation deadlines for source-forwarded writes. These
-     * timers settle only the caller waiting for `confirmed`; the accepted write
-     * remains in `awaiting_delta`, with its durable envelope intact, until the
-     * authoritative WAL echo arrives.
-     */
-    private replicationLagTimeouts;
-    private replicationLagErrors;
-    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;
-    /** Collision-safe receipt target identity across models sharing a row id. */
-    private receiptTargetKey;
-    /**
-     * Relates stale notifications back to write targets without assuming the
-     * server's canonical model name uses the same spelling as the public schema
-     * key (`Task` versus `tasks`). Exact `(model,id)` wins; a globally unique id
-     * is the compatibility fallback. An ambiguous same-id cross-model mismatch
-     * is deliberately left unclassified, so it cannot falsely settle a queued
-     * write. A notification with no write-target id (or an explicit group) is a
-     * declared-read conflict and holds the whole batch.
-     */
-    private classifyReceiptNotifications;
-    private resolveConfirmation;
-    private takeUnsentCreateForModel;
-    private cancelUnsentCreateForDelete;
-    private findCreateBarrierForDelete;
-    private completeLocalDelete;
-    private deferDeleteUntilCreateSettles;
-    private releaseDeferredDeletesForCreate;
-    private config;
-    private executingCount;
-    private optimisticUpdates;
-    private commitNotifications;
-    /** Zero-row targets returned on a successful atomic commit receipt. */
-    private commitMissingIds;
-    private readonly deltaConfirmation;
-    private isConnectedFn;
-    private commitOfflineGraceTimer;
-    /**
-     * 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 `../logPosition.js` for the full contract.
-     */
-    readonly position: LogPosition;
-    /** 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: DurableWriteStore): 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 rejection, confirmed ack, or echo. */
-    private removeDurableCommit;
-    /**
-     * Upgrade a sealed request with permanent connected-source acceptance before
-     * exposing the queued receipt. This is not completion: the envelope remains
-     * until the matching WAL correlation arrives. The upgrade only makes a
-     * crash/restart safe after the hosted 24-hour replay window has elapsed.
-     */
-    private persistDurableCommitAcceptance;
-    /** Parse an untrusted/custom executor receipt without making ambiguity fatal. */
-    private parseMutationCommitResult;
-    /**
-     * Dispatch a sealed envelope to the transport, bounded by
-     * `commitDispatchTimeoutMs`. Every executor call site routes through here:
-     * a transport that never answers must become a retryable no-receipt failure
-     * (the same class as a malformed receipt) instead of an eternally in-flight
-     * commit, because an unanswered commit holds the staged-batch lock and
-     * silently stalls every later write in the session. The abandoned commit's
-     * eventual result, if it ever arrives, is discarded; the retry re-sends the
-     * identical idempotency key, so the server deduplicates an already-applied
-     * write.
-     */
-    private dispatchCommitBounded;
-    private clearReplicationLagState;
-    /**
-     * Bounds the public `wait: 'confirmed'` promise without changing the
-     * accepted write's lifecycle. A lag timeout is not a rejection from the
-     * source database, so it must never emit `transaction:failed`, roll back
-     * optimistic state, or remove the durable replay envelope.
-     */
-    private scheduleReplicationLagTimeout;
-    /**
-     * 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
-     * listeners on `transaction:completed` / `transaction:failed`. Kept off
-     * the QueuedMutation row so the store's iteration order stays plain-data
-     * and serialization-friendly.
-     */
-    private confirmationResolvers;
-    constructor(config?: Partial<MutationQueueConfig>);
-    /**
-     * 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".
-     *
-     * 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 QueuedMutation}: 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>;
-    /**
-     * 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.
-     *
-     * 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;
-    /**
-     * 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;
-    /**
-     * Drives the offline-grace timer for in-flight commit-lane transactions.
-     *
-     * 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'` 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;
-    /**
-     * 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;
-    /**
-     * Stages a transaction for commit. Transactions staged within the same
-     * event-loop tick are committed together.
-     */
-    private stageTransaction;
-    /**
-     * Schedules the staged transactions to commit on a microtask, so all
-     * transactions created synchronously within one tick are batched together.
-     */
-    private scheduleCommit;
-    /**
-     * 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>;
-    /**
-     * Records a create and applies it optimistically, then stages it for the next
-     * batched commit. Returns the {@link QueuedMutation}, whose `confirmation`
-     * promise settles once the server confirms the write.
-     */
-    create(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
-    /**
-     * 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, sourceMutationId?: string): Promise<QueuedMutation>;
-    /**
-     * 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, sourceMutationId?: string): Promise<QueuedMutation>;
-    /**
-     * Uploads a single attachment, delegating to the mutation executor.
-     */
-    uploadAttachment(_file: File, options: {
-        id: string;
-        [key: string]: unknown;
-    }, _context: UserContext): Promise<{
-        url: string;
-    } | null>;
-    /**
-     * Uploads several attachments in one call, delegating to the mutation executor.
-     */
-    batchUploadAttachments(_files: File[], items: {
-        id: string;
-        [key: string]: unknown;
-    }[], _context: UserContext): Promise<{
-        id: string;
-        url: string;
-    }[]>;
-    /**
-     * Records an archive and applies it optimistically, then stages it for the
-     * next batched commit.
-     */
-    archive(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
-    /**
-     * Records an unarchive and applies it optimistically, then stages it for the
-     * next batched commit.
-     */
-    unarchive(model: Model, context: UserContext): Promise<QueuedMutation>;
-    /**
-     * 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;
-    /**
-     * 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;
-    private rememberDeltaCorrelation;
-    private queuedCommitEchoSyncId;
-    private queuedCommitMatchesCorrelation;
-    private completeQueuedCommit;
-    /**
-     * Confirms awaiting writes. Hosted/anomaly receipts keep their sync-id
-     * threshold semantics; queued forwards require the exact server correlation.
-     */
-    onDeltaReceived(syncId: number, _transactionId?: string, correlationId?: string): void;
-    private 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;
-    /**
-     * 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. After an accepted write exceeds its
-     * replication-confirmation deadline, an explicit same-key retry reuses the
-     * exact sealed envelope as an idempotent status probe; the server's
-     * `mutation_log` still prevents a second logical write.
-     */
-    enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
-        reads?: ReadDependency[] | null;
-        track?: TrackDependency[] | null;
-    }): Promise<void>;
-    /**
-     * 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;
-    /**
-     * 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;
-        notifications?: StaleNotification[];
-        missingIds?: string[];
-    }>;
-    private isReorderPayload;
-    /**
-     * 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 (retried):
-     * - Network failures, connection errors, and timeouts.
-     * - Server errors (HTTP 5xx).
-     * - Rate limiting (HTTP 429).
-     *
-     * 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;
-    /**
-     * Handles a failed transaction: retries transient failures with backoff and
-     * rolls back permanent ones, settling the transaction's confirmation promise
-     * either way.
-     */
-    private handleFailure;
-    /**
-     * 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: QueuedMutation, serverData: MutationInput): Promise<void>;
-    /**
-     * 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;
-    /**
-     * 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.
-     */
-    loadPersistedTransactions(database: Database): Promise<void>;
-    /**
-     * 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.
-     */
-    restoreDurableCommits(): Promise<Set<string>>;
-    /**
-     * 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;
-    /**
-     * 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): QueuedMutation[];
-    /**
-     * 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 (for example 'Block').
-     * @param foreignKey - The foreign-key property name (for example 'sectionId').
-     * @param parentId - The deleted parent's id.
-     * @returns The number of transactions cancelled.
-     */
-    cancelTransactionsByForeignKey(childModelName: string, foreignKey: string, parentId: string): number;
-    /**
-     * Returns the number of transactions still pending or executing.
-     */
-    getOutstandingTransactionCount(): number;
-    /** Generates a unique local transaction id. */
-    private generateId;
-    private mergeData;
-    private extractCreateData;
-    private mapChangesToInput;
-    private extractUpdateData;
-    private extractPreviousData;
-    /** Returns a snapshot of queue counts and the current configuration. */
-    getStats(): {
-        pending: number;
-        executing: number;
-        completed: number;
-        failed: number;
-        optimistic: number;
-        totalTransactions: number;
-        batchIndex: number;
-        config: {
-            /** Shared client position (see logPosition.ts). One per client. */
-            position?: LogPosition;
-            /** The owning client's runtime. Defaults to the module-global bridge. */
-            runtime?: RuntimeContext;
-            maxBatchSize: number;
-            batchDelay: number;
-            maxRetries: number;
-            conflictResolution: ConflictResolution;
-            enablePersistence: boolean;
-            enableOptimistic: boolean;
-            maxExecutingTransactions: number;
-            deltaConfirmationTimeout: number;
-            /**
-             * Exponential backoff for retryable server responses (HTTP 429/503).
-             * `baseMs` is the first retry delay; each subsequent attempt doubles
-             * up to `capMs`. Final delay = min(capMs, baseMs * 2^(attempt-1)) +
-             * up to 100ms of jitter. Defaults: 200ms / 1500ms.
-             */
-            retryBackoff: {
-                baseMs: number;
-                capMs: number;
-            };
-            /**
-             * 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' })` would wait
-             * forever if the connection died while a commit was in flight.
-             */
-            commitOfflineGraceMs: number;
-            /**
-             * How long, in milliseconds, to wait for the transport to acknowledge a
-             * dispatched commit before treating the silence as a retryable no-receipt
-             * failure. A transport that never answers — a half-open socket, a dropped
-             * response frame — would otherwise hold the commit in flight forever, and
-             * with it the client's staged-batch lock: every later write in the session
-             * queues silently behind the unanswered one. The envelope's idempotency key
-             * is stable across retries, so a commit the server DID apply before the
-             * timeout is deduplicated on the retry rather than double-applied.
-             * Defaults to 30 seconds. Set `0` to disable the bound.
-             */
-            commitDispatchTimeoutMs: number;
-        };
-    };
-    /**
-     * Returns detailed internal state — pending, executing, and awaiting-delta
-     * transactions — to help diagnose delta-confirmation issues.
-     */
-    getDebugInfo(): {
-        lastSeenSyncId: number;
-        awaitingDeltaCount: number;
-        awaitingDeltaTransactions: {
-            id: string;
-            type: "update" | "create" | "delete" | "archive" | "unarchive";
-            modelName: string;
-            modelId: string;
-            syncIdNeeded: number | undefined;
-            createdAt: number;
-            age: number;
-        }[];
-        pendingTransactions: {
-            id: string;
-            type: "update" | "create" | "delete" | "archive" | "unarchive";
-            modelName: string;
-            modelId: string;
-        }[];
-        executingTransactions: {
-            id: string;
-            type: "update" | "create" | "delete" | "archive" | "unarchive";
-            modelName: string;
-            modelId: string;
-        }[];
-    };
-    /** Merges the given options into the queue's configuration. */
-    setConfig(config: Partial<MutationQueueConfig>): void;
-    /**
-     * 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;
-        modelName: string;
-        action: string;
-        data: any;
-    }): boolean;
-    /**
-     * Releases the queue's resources: rolls back outstanding optimistic updates,
-     * clears all timers and stored transactions, and removes event listeners.
-     */
-    dispose(): void;
-}