@abloatai/humans 0.37.0

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

@@ -0,0 +1,511 @@
+/**
+ * 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 { LocalModel } from '../../localModelContract.js';
+import type { MutationPersistencePort } from '../../mutationPersistence.js';
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import { type LogPositionPort } from '../../logPosition.js';
+import type { WriteOptions } from '../../interfaces/index.js';
+import type { StaleNotification, ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import { type MutationInput, type QueuedMutation, type UserContext } from './commitPayload.js';
+import { type CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableWriteStore } from './durableWriteStore.js';
+import { type LocalMutationPort } from './localMutation.js';
+import { type CommitTransaction } from './commitLane.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 ConflictResolution {
+    strategy: 'last-write-wins' | 'merge' | 'reject' | 'custom';
+    resolver?: (local: MutationInput | undefined, remote: MutationInput) => MutationInput;
+}
+export interface MutationQueueConfig {
+    /** Shared client position (see logPosition.ts). One per client. */
+    position?: LogPositionPort;
+    /** 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;
+    /** Local adapter for applying and rolling back local writes. */
+    localMutationPort?: LocalMutationPort;
+    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;
+    /** Durable transaction journal owned by this queue, before commit sealing. */
+    private persistence;
+    private deferredMutations;
+    private pendingPersistenceStages;
+    private persistenceStageScheduled;
+    private pendingDrainPromise;
+    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 get commitTransportContext();
+    private get commitLaneContext();
+    private get commitReceiptContext();
+    private get commitApiContext();
+    private get modelMutationContext();
+    private get queueCoalescingContext();
+    private get batchProcessingContext();
+    private get failureHandlingContext();
+    private get conflictPolicyContext();
+    private get processingSchedulerContext();
+    private get pendingDrainContext();
+    private get durableCommitRestoreContext();
+    private get persistenceContext();
+    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 readonly localMutationPort;
+    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: LogPositionPort;
+    /** 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): Promise<void>;
+    deferMutation(type: 'create' | 'update' | 'delete' | 'archive', model: LocalModel, capturedChanges?: Record<string, unknown>, writeOptions?: WriteOptions): void;
+    enqueueModelMutation(type: 'create' | 'update' | 'delete' | 'archive', model: LocalModel, context: UserContext, capturedChanges?: Record<string, unknown>, writeOptions?: WriteOptions): Promise<QueuedMutation>;
+    /** Attach the durable journal supplied by the local/materializer layer. */
+    setPersistence(persistence: MutationPersistencePort): void;
+    private persistQueuedTransaction;
+    private persistAndStage;
+    private removePersistedTransaction;
+    private settlePersistedFailure;
+    private sourceMutationIdsFor;
+    /** Atomically seals a commit before it is allowed onto the dispatch lane. */
+    private sealDurableCommit;
+    private removeDurableCommit;
+    private persistDurableCommitAcceptance;
+    private parseMutationCommitResult;
+    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;
+    private takeNextExecutionBatch;
+    private takePendingDrainBatch;
+    /**
+     * 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 drainPending} resumes the work when the owner decides to drain.
+     */
+    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.
+     */
+    drainPending(): Promise<void>;
+    private drainPendingInternal;
+    create(model: LocalModel, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
+    update(model: LocalModel, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
+    delete(model: LocalModel, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
+    uploadAttachment(_file: File, options: {
+        id: string;
+        [key: string]: unknown;
+    }, _context: UserContext): Promise<{
+        url: string;
+    } | null>;
+    batchUploadAttachments(_files: File[], items: {
+        id: string;
+        [key: string]: unknown;
+    }[], _context: UserContext): Promise<{
+        id: string;
+        url: string;
+    }[]>;
+    archive(model: LocalModel, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
+    unarchive(model: LocalModel, context: UserContext): Promise<QueuedMutation>;
+    private enqueue;
+    private scheduleProcessing;
+    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 atomic commit through the commit API coordinator. */
+    enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
+        reads?: ReadDependency[] | null;
+        track?: TrackDependency[] | null;
+    }): Promise<void>;
+    private processCommitLane;
+    waitForCommitReceipt(clientTxId: string): Promise<{
+        lastSyncId: number;
+        notifications?: StaleNotification[];
+        missingIds?: string[];
+    }>;
+    private isReorderPayload;
+    private isPermanentError;
+    private isDefinitiveRejection;
+    private handleFailure;
+    handleConflict(transaction: QueuedMutation, serverData: MutationInput): Promise<void>;
+    private applyOptimisticCreate;
+    private applyOptimisticUpdate;
+    private applyOptimisticDelete;
+    private rollbackOptimistic;
+    private deserializeLegacyPendingMutation;
+    loadPersistedTransactions(persistence: MutationPersistencePort, sealedMutationIds?: ReadonlySet<string>): Promise<void>;
+    restoreDurableCommits(): Promise<Set<string>>;
+    private deserializeTransaction;
+    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;
+    getOutstandingTransactions(): readonly QueuedMutation[];
+    /** 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?: LogPositionPort;
+            /** 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;
+            /** Local adapter for applying and rolling back local writes. */
+            localMutationPort?: LocalMutationPort;
+            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;
+}