@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transactions/{TransactionQueue.d.ts → mutations/MutationQueue.d.ts}

@@ -1,5 +1,5 @@
 /**
- * TransactionQueue manages the lifecycle of local writes on their way to the
+ * 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.
@@ -12,18 +12,19 @@
  * - 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 { SyncPosition } from '../sync/syncPosition.js';
-import type { WriteOptions } from '../interfaces/index.js';
-import type { StaleNotification, ReadDependency, TrackDependency } 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 { 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 { Transaction, UserContext } from './commitPayload.js';
+export type { QueuedMutation, UserContext } from './commitPayload.js';
 /**
  * A pre-built, multi-operation commit submitted through
- * `ablo.commits.create()`. Unlike the per-model {@link Transaction} (see
+ * `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
@@ -40,16 +41,22 @@ interface CommitTransaction {
         input?: Record<string, unknown>;
         transactionId?: string;
         readAt?: number | null;
-        onStale?: 'reject' | 'overwrite' | 'notify' | null;
+        onStale?: OnStaleMode | null;
     }[];
-    causedByTaskId?: string | null;
-    /** Read dependencies for the whole batch, forwarded to the executor so the server can detect stale-context writes. */
+    /** The premise for the whole batch, forwarded to the executor so the server can detect stale-context writes. */
     reads?: ReadDependency[] | null;
-    /** Durable read-dependencies (`track`) to register for the batch's participant, forwarded to the executor. */
+    /** 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;
@@ -65,9 +72,11 @@ interface ConflictResolution {
     strategy: 'last-write-wins' | 'merge' | 'reject' | 'custom';
     resolver?: (local: MutationInput | undefined, remote: MutationInput) => MutationInput;
 }
-interface TransactionQueueConfig {
-    /** Shared client position (see sync/syncPosition.ts). One per client. */
-    position?: SyncPosition;
+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;
@@ -99,13 +108,26 @@ interface TransactionQueueConfig {
      * 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 TransactionQueue extends EventEmitter {
+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?;
@@ -177,9 +199,9 @@ export declare class TransactionQueue extends EventEmitter {
      * 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.
+     * `readFloor`. See `../logPosition.js` for the full contract.
      */
-    readonly position: SyncPosition;
+    readonly position: LogPosition;
     /** Applied-cursor alias, kept so the many internal read sites stay legible. */
     private get lastSeenSyncId();
     private noteAck;
@@ -213,6 +235,18 @@ export declare class TransactionQueue extends EventEmitter {
     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
@@ -237,11 +271,11 @@ export declare class TransactionQueue extends EventEmitter {
      * 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 Transaction row so the store's iteration order stays plain-data
+     * the QueuedMutation row so the store's iteration order stays plain-data
      * and serialization-friendly.
      */
     private confirmationResolvers;
-    constructor(config?: Partial<TransactionQueueConfig>);
+    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
@@ -252,7 +286,7 @@ export declare class TransactionQueue extends EventEmitter {
      * 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
+     * {@link QueuedMutation}: use this method at call sites that hold a model
      * returned by `ablo.<model>.create()` but never see the underlying
      * transaction.
      */
@@ -297,7 +331,7 @@ export declare class TransactionQueue extends EventEmitter {
      * through this instance's connection even when several client instances exist
      * in the same process.
      */
-    setMutationExecutor(executor: import('../interfaces/index.js').MutationExecutor): void;
+    setMutationExecutor(executor: import('../../interfaces/index.js').MutationExecutor): void;
     /**
      * Stages a transaction for commit. Transactions staged within the same
      * event-loop tick are committed together.
@@ -321,24 +355,24 @@ export declare class TransactionQueue extends EventEmitter {
     flushOfflineQueue(): Promise<void>;
     /**
      * Records a create and applies it optimistically, then stages it for the next
-     * batched commit. Returns the {@link Transaction}, whose `confirmation`
+     * 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<Transaction>;
+    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<Transaction>;
+    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<Transaction>;
+    delete(model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
     /**
      * Uploads a single attachment, delegating to the mutation executor.
      */
@@ -362,12 +396,12 @@ export declare class TransactionQueue extends EventEmitter {
      * 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<Transaction>;
+    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<Transaction>;
+    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.
@@ -410,7 +444,6 @@ export declare class TransactionQueue extends EventEmitter {
      * `mutation_log` still prevents a second logical write.
      */
     enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
-        causedByTaskId?: string | null;
         reads?: ReadDependency[] | null;
         track?: TrackDependency[] | null;
     }): Promise<void>;
@@ -464,7 +497,7 @@ export declare class TransactionQueue extends EventEmitter {
      * 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>;
+    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.
@@ -497,14 +530,14 @@ export declare class TransactionQueue extends EventEmitter {
      * optionally limited to one operation type, rolling back their optimistic
      * state. Returns the cancelled transactions.
      */
-    cancelTransactionsForModel(modelId: string, transactionType?: string): Transaction[];
+    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 'SlideLayer').
-     * @param foreignKey - The foreign-key property name (for example 'slideId').
+     * @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.
      */
@@ -530,8 +563,10 @@ export declare class TransactionQueue extends EventEmitter {
         totalTransactions: number;
         batchIndex: number;
         config: {
-            /** Shared client position (see sync/syncPosition.ts). One per client. */
-            position?: SyncPosition;
+            /** 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;
@@ -563,6 +598,18 @@ export declare class TransactionQueue extends EventEmitter {
              * 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;
         };
     };
     /**
@@ -595,7 +642,7 @@ export declare class TransactionQueue extends EventEmitter {
         }[];
     };
     /** Merges the given options into the queue's configuration. */
-    setConfig(config: Partial<TransactionQueueConfig>): void;
+    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.