@abloatai/ablo 0.29.3 → 0.30.1

package/dist/testing/mocks/MockMutationExecutor.d.ts

@@ -6,6 +6,7 @@
  * so tests can drive the delta-confirmation flow that depends on those ids.
  */
 import type { MutationExecutor, MutationOperation, MutationOptions, CommitResult } from '../../interfaces/index.js';
+import type { StaleNotification } from '../../coordination/schema.js';
 export interface CapturedMutation {
     method: string;
     modelName?: string;
@@ -23,6 +24,14 @@ export interface MockMutationExecutorOptions {
     shouldSucceed?: boolean;
     /** A delay applied before each call resolves, in milliseconds, to simulate a slow network. */
     latencyMs?: number;
+    /** Optional explicit receipt status. Omission preserves legacy confirmed semantics. */
+    status?: CommitResult['status'];
+    /** Optional server-issued source/WAL correlation returned with queued receipts. */
+    correlationId?: string;
+    /** Optional stale-context notifications returned with each commit. */
+    notifications?: StaleNotification[];
+    /** Optional zero-row target ids returned with each commit. */
+    missingIds?: string[];
 }
 export declare class MockMutationExecutor implements MutationExecutor {
     /** Every captured call, in the order it was made. Assertions read from this list. */
@@ -31,6 +40,10 @@ export declare class MockMutationExecutor implements MutationExecutor {
     private _syncId;
     private _shouldSucceed;
     private _latencyMs;
+    private _status;
+    private _correlationId;
+    private _notifications;
+    private _missingIds;
     /** Per-method failure overrides: method name → error */
     private _failureOverrides;
     /** Per-method response overrides */
@@ -40,6 +53,14 @@ export declare class MockMutationExecutor implements MutationExecutor {
     get currentSyncId(): number;
     /** Sets the next sync id the executor will return. */
     setSyncId(id: number): void;
+    /** Sets the settlement status returned by subsequent commit calls. */
+    setStatus(status: CommitResult['status']): void;
+    /** Sets the opaque source/WAL correlation returned by subsequent commits. */
+    setCorrelationId(correlationId: string | undefined): void;
+    /** Sets stale-context notifications returned by subsequent commit calls. */
+    setNotifications(notifications: StaleNotification[] | undefined): void;
+    /** Sets zero-row target ids returned by subsequent commit calls. */
+    setMissingIds(missingIds: string[] | undefined): void;
     /** Makes every mutation reject. Pass an error to control what is thrown. */
     failAll(error?: Error): void;
     /** Restores the default where mutations succeed, clearing any failure overrides. */

package/dist/testing/mocks/MockMutationExecutor.js

@@ -13,6 +13,10 @@ export class MockMutationExecutor {
     _syncId;
     _shouldSucceed;
     _latencyMs;
+    _status;
+    _correlationId;
+    _notifications;
+    _missingIds;
     /** Per-method failure overrides: method name → error */
     _failureOverrides = new Map();
     /** Per-method response overrides */
@@ -21,6 +25,10 @@ export class MockMutationExecutor {
         this._syncId = options.initialSyncId ?? 1;
         this._shouldSucceed = options.shouldSucceed ?? true;
         this._latencyMs = options.latencyMs ?? 0;
+        this._status = options.status;
+        this._correlationId = options.correlationId;
+        this._notifications = options.notifications;
+        this._missingIds = options.missingIds;
     }
     // ─────────────────────────────────────────────
     // Test control API
@@ -33,6 +41,22 @@ export class MockMutationExecutor {
     setSyncId(id) {
         this._syncId = id;
     }
+    /** Sets the settlement status returned by subsequent commit calls. */
+    setStatus(status) {
+        this._status = status;
+    }
+    /** Sets the opaque source/WAL correlation returned by subsequent commits. */
+    setCorrelationId(correlationId) {
+        this._correlationId = correlationId;
+    }
+    /** Sets stale-context notifications returned by subsequent commit calls. */
+    setNotifications(notifications) {
+        this._notifications = notifications;
+    }
+    /** Sets zero-row target ids returned by subsequent commit calls. */
+    setMissingIds(missingIds) {
+        this._missingIds = missingIds;
+    }
     /** Makes every mutation reject. Pass an error to control what is thrown. */
     failAll(error) {
         this._shouldSucceed = false;
@@ -67,6 +91,10 @@ export class MockMutationExecutor {
         this._syncId = options?.initialSyncId ?? 1;
         this._shouldSucceed = options?.shouldSucceed ?? true;
         this._latencyMs = options?.latencyMs ?? 0;
+        this._status = options?.status;
+        this._correlationId = options?.correlationId;
+        this._notifications = options?.notifications;
+        this._missingIds = options?.missingIds;
         this._failureOverrides.clear();
         this._responseOverrides.clear();
     }
@@ -78,7 +106,31 @@ export class MockMutationExecutor {
         await this._maybeDelay();
         this._maybeThrow('commit');
         const syncId = this._syncId++;
-        return { lastSyncId: syncId };
+        if (this._status === 'queued') {
+            if (!this._correlationId) {
+                throw new Error('Mock queued commits require a correlationId');
+            }
+            return {
+                lastSyncId: 0,
+                status: 'queued',
+                correlationId: this._correlationId,
+                ...(this._notifications ? { notifications: this._notifications } : {}),
+                ...(this._missingIds ? { missingIds: this._missingIds } : {}),
+            };
+        }
+        const evidence = {
+            ...(this._notifications ? { notifications: this._notifications } : {}),
+            ...(this._missingIds ? { missingIds: this._missingIds } : {}),
+        };
+        if (this._status === 'confirmed') {
+            return {
+                lastSyncId: syncId,
+                status: 'confirmed',
+                ...(this._correlationId ? { correlationId: this._correlationId } : {}),
+                ...evidence,
+            };
+        }
+        return { lastSyncId: syncId, ...evidence };
     }
     async executeCreate(modelName, id, input, clientMutationId) {
         this._capture('executeCreate', { modelName, modelId: id, input, clientMutationId });

package/dist/transactions/TransactionQueue.d.ts

@@ -45,10 +45,12 @@ interface CommitTransaction {
     causedByTaskId?: string | null;
     /** 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';
+    status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed';
     createdAt: number;
     attempts: number;
     lastSyncId?: number;
+    /** Opaque customer-side batch ledger key returned by a queued receipt. */
+    correlationId?: string;
     error?: Error;
     sealedAt: number;
     sequence: number;
@@ -113,6 +115,20 @@ export declare class TransactionQueue extends EventEmitter {
     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;
@@ -126,6 +142,18 @@ export declare class TransactionQueue extends EventEmitter {
     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;
@@ -137,6 +165,8 @@ export declare class TransactionQueue extends EventEmitter {
     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;
@@ -170,8 +200,25 @@ export declare class TransactionQueue extends EventEmitter {
      * callers never send a separately reconstructed payload after sealing.
      */
     private sealDurableCommit;
-    /** Best-effort cleanup after a definitive result; replay is safe if it fails. */
+    /** 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;
+    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
@@ -333,13 +380,15 @@ export declare class TransactionQueue extends EventEmitter {
      * greatly reduces batch latency.
      */
     private processBatch;
+    private rememberDeltaCorrelation;
+    private queuedCommitEchoSyncId;
+    private queuedCommitMatchesCorrelation;
+    private completeQueuedCommit;
     /**
-     * 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.
+     * Confirms awaiting writes. Hosted/anomaly receipts keep their sync-id
+     * threshold semantics; queued forwards require the exact server correlation.
      */
-    onDeltaReceived(syncId: number): void;
+    onDeltaReceived(syncId: number, _transactionId?: string, correlationId?: string): void;
     private scheduleDeltaConfirmationTimeout;
     /**
      * Resolves once the given transaction is confirmed and rejects if it fails.
@@ -353,8 +402,10 @@ export declare class TransactionQueue extends EventEmitter {
      * `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.
+     * 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?: {
         causedByTaskId?: string | null;
@@ -377,6 +428,7 @@ export declare class TransactionQueue extends EventEmitter {
     waitForCommitReceipt(clientTxId: string): Promise<{
         lastSyncId: number;
         notifications?: StaleNotification[];
+        missingIds?: string[];
     }>;
     private isReorderPayload;
     /**