@abloatai/ablo 0.14.0 → 0.15.0

package/dist/source/connector.js

@@ -0,0 +1,264 @@
+/**
+ * Customer-side Data Source reverse-channel connector.
+ *
+ * The dial-out half of the reverse channel (see `connector-protocol.ts`). The
+ * customer runs this next to their database; it opens an OUTBOUND WebSocket to
+ * Ablo Cloud and serves the `commit`/`load`/`list` leg over that socket instead
+ * of receiving inbound webhooks. This is the symmetric primitive to
+ * `createPushQueue` (which already gives the `events` leg an outbound transport)
+ * and mirrors the Stripe CLI's `stripe listen`.
+ *
+ * The connector does NOT reimplement any handler logic. It wraps the SAME
+ * `(request: Request) => Promise<Response>` the customer's deployed route uses:
+ *
+ *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
+ *   import { sourceOptions } from './ablo.source'; // shared with route.ts
+ *
+ *   const connector = createSourceConnector({
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     handler: dataSource(sourceOptions),
+ *   });
+ *   await connector.run(controller.signal);
+ *
+ * Each drained `request` frame is replayed into a synthesized `Request` carrying
+ * the original Standard Webhooks signature headers, so the handler verifies it
+ * through the unchanged `verifyAbloSourceRequest` — identical to the webhook
+ * path. The transport changes; the trust model does not.
+ */
+import { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, } from './connector-protocol.js';
+/** Default Ablo Cloud base. The connector appends `SOURCE_CONNECTOR_WS_PATH`. */
+const DEFAULT_BASE_URL = 'https://api.abloatai.com';
+/**
+ * Reconnect backoff, in ms, indexed by consecutive failed connect attempts.
+ * Unlike the (multi-day) Standard Webhooks delivery schedule, a long-lived
+ * control socket should re-establish quickly and cap at a steady interval, so
+ * this is a short capped curve. The last entry repeats for further attempts. A
+ * clean `ready` resets the counter to 0.
+ */
+export const DEFAULT_RECONNECT_SCHEDULE = [
+    0, // immediate first reconnect
+    1_000, // 1s
+    2_000, // 2s
+    5_000, // 5s
+    10_000, // 10s
+    30_000, // 30s (steady state)
+];
+export function createSourceConnector(options) {
+    const baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const url = toWebSocketUrl(baseURL) + SOURCE_CONNECTOR_WS_PATH;
+    const schedule = options.reconnectSchedule ?? DEFAULT_RECONNECT_SCHEDULE;
+    const jitter = options.jitter ?? 0.1;
+    const factory = options.webSocket ?? defaultWebSocketFactory;
+    return {
+        async run(signal) {
+            let attempt = 0;
+            while (!signal.aborted) {
+                const delay = backoffFor(schedule, attempt, jitter);
+                if (delay > 0)
+                    await sleep(delay, signal);
+                if (signal.aborted)
+                    return;
+                options.onStatus?.('connecting');
+                const becameReady = await connectOnce({
+                    url,
+                    apiKey: options.apiKey,
+                    handler: options.handler,
+                    factory,
+                    client: options.client,
+                    onStatus: options.onStatus,
+                    onError: options.onError,
+                    signal,
+                });
+                // A connection that reached `ready` resets the backoff so the next
+                // drop reconnects immediately; one that never readied keeps escalating.
+                attempt = becameReady ? 0 : attempt + 1;
+            }
+        },
+    };
+}
+/**
+ * One connection lifecycle: open → register → serve drained requests until the
+ * socket closes or `signal` aborts. Resolves to whether the connection reached
+ * the `ready` state (used to reset reconnect backoff). Never rejects — transport
+ * failures are normal and drive a reconnect.
+ */
+function connectOnce(params) {
+    return new Promise((resolve) => {
+        let ws;
+        try {
+            ws = params.factory(params.url, sourceConnectorSubprotocols(params.apiKey));
+        }
+        catch (err) {
+            params.onError?.(err);
+            resolve(false);
+            return;
+        }
+        let ready = false;
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            params.signal.removeEventListener('abort', onAbort);
+            params.onStatus?.('disconnected');
+            resolve(ready);
+        };
+        const onAbort = () => {
+            try {
+                ws.close(1000, 'connector_aborted');
+            }
+            catch {
+                // Already closing/closed.
+            }
+            finish();
+        };
+        params.signal.addEventListener('abort', onAbort, { once: true });
+        ws.addEventListener('open', () => {
+            send(ws, {
+                type: 'register',
+                protocolVersion: SOURCE_CONNECTOR_PROTOCOL_VERSION,
+                ...(params.client ? { client: params.client } : {}),
+            });
+        });
+        ws.addEventListener('message', (event) => {
+            let frame;
+            try {
+                frame = decodeFrame(event.data);
+            }
+            catch (err) {
+                params.onError?.(err instanceof ConnectorProtocolError
+                    ? err
+                    : new ConnectorProtocolError(String(err)));
+                return;
+            }
+            handleFrame(frame);
+        });
+        ws.addEventListener('error', (event) => {
+            params.onError?.(event);
+            // `close` always follows `error`; finish() runs there.
+        });
+        ws.addEventListener('close', () => {
+            finish();
+        });
+        function handleFrame(frame) {
+            switch (frame.type) {
+                case 'ready':
+                    handleReady(frame);
+                    return;
+                case 'request':
+                    // Do not await — serve each request concurrently so a slow handler
+                    // never blocks draining the next frame off the socket.
+                    void serveRequest(frame);
+                    return;
+                case 'error':
+                    params.onError?.(new ConnectorProtocolError(`${frame.code}: ${frame.message}`));
+                    return;
+                // `register`/`response` are connector→server only; ignore if echoed.
+                case 'register':
+                case 'response':
+                    return;
+            }
+        }
+        function handleReady(frame) {
+            if (frame.protocolVersion !== SOURCE_CONNECTOR_PROTOCOL_VERSION) {
+                params.onError?.(new ConnectorProtocolError(`Server protocol version ${frame.protocolVersion} != ${SOURCE_CONNECTOR_PROTOCOL_VERSION}`));
+                try {
+                    ws.close(1002, 'protocol_version_mismatch');
+                }
+                catch {
+                    // closing
+                }
+                return;
+            }
+            ready = true;
+            params.onStatus?.('ready');
+        }
+        async function serveRequest(frame) {
+            const response = await runHandler(frame);
+            // Best-effort: if the socket dropped while the handler ran, the server
+            // times the request out and the SDK retries — same as a webhook timeout.
+            send(ws, response);
+        }
+        async function runHandler(frame) {
+            try {
+                const request = new Request(frame.url, {
+                    method: frame.method,
+                    headers: frame.headers,
+                    body: frame.body,
+                });
+                const result = await params.handler(request);
+                const body = await result.text();
+                return {
+                    type: 'response',
+                    id: frame.id,
+                    status: result.status,
+                    body,
+                };
+            }
+            catch (err) {
+                params.onError?.(err);
+                // Surface as a 500 so the server-side SourceClient treats it as a
+                // retryable failure, exactly like a webhook endpoint throwing.
+                return {
+                    type: 'response',
+                    id: frame.id,
+                    status: 500,
+                    body: JSON.stringify({
+                        error: 'source_connector_handler_error',
+                        message: err instanceof Error ? err.message : String(err),
+                    }),
+                };
+            }
+        }
+        function send(socket, frame) {
+            try {
+                socket.send(encodeFrame(frame));
+            }
+            catch (err) {
+                params.onError?.(err);
+            }
+        }
+    });
+}
+function defaultWebSocketFactory(url, protocols) {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor) {
+        throw new Error('No global WebSocket available. Pass `webSocket` (e.g. the `ws` package) to createSourceConnector.');
+    }
+    return new Ctor(url, protocols);
+}
+/** `http(s)://` → `ws(s)://`. Leaves an explicit `ws(s)` scheme untouched. */
+function toWebSocketUrl(baseURL) {
+    if (baseURL.startsWith('https://'))
+        return `wss://${baseURL.slice('https://'.length)}`;
+    if (baseURL.startsWith('http://'))
+        return `ws://${baseURL.slice('http://'.length)}`;
+    return baseURL;
+}
+function backoffFor(schedule, attempt, jitter) {
+    if (attempt <= 0)
+        return 0;
+    const base = schedule[Math.min(attempt, schedule.length - 1)] ?? 0;
+    if (jitter <= 0 || base === 0)
+        return base;
+    const swing = base * jitter;
+    return Math.max(0, base + (Math.random() * 2 - 1) * swing);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/source/contract.d.ts

@@ -44,9 +44,8 @@ export declare const operationSchema: z.ZodObject<{
     readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         reject: "reject";
-        force: "force";
-        flag: "flag";
-        merge: "merge";
+        overwrite: "overwrite";
+        notify: "notify";
     }>>>;
 }, z.core.$strip>;
 export type Operation = z.infer<typeof operationSchema>;
@@ -71,9 +70,8 @@ export declare const changeSetSchema: z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             reject: "reject";
-            force: "force";
-            flag: "flag";
-            merge: "merge";
+            overwrite: "overwrite";
+            notify: "notify";
         }>>>;
     }, z.core.$strip>>;
     clientTxId: z.ZodString;

package/dist/source/contract.js

@@ -36,7 +36,7 @@ export const operationSchema = z.object({
     input: jsonObject.nullish(),
     transactionId: z.string().nullish(),
     readAt: z.number().nullish(),
-    onStale: z.enum(['reject', 'force', 'flag', 'merge']).nullish(),
+    onStale: z.enum(['reject', 'overwrite', 'notify']).nullish(),
 });
 /**
  * The atomic unit an adapter commits: one or more operations under a single

package/dist/source/index.d.ts

@@ -71,7 +71,7 @@ export interface SourceOperation {
     readonly input?: Record<string, unknown> | null;
     readonly transactionId?: string | null;
     readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
 }
 export interface SourceDelta {
     readonly model: string;
@@ -464,6 +464,8 @@ export type DataSourceResponse<Row = Record<string, unknown>> = SourceResponse<R
 export declare function abloSource<const S extends SchemaRecord, TAuth = unknown>(options: AbloSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
 export declare function dataSource<const S extends SchemaRecord, TAuth = unknown>(options: DataSourceOptions<S, TAuth>): (request: Request) => Promise<Response>;
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, type PushQueue, type PushQueueItem, type PushQueueOptions, type PushQueueStorage, } from './pushQueue.js';
+export { createSourceConnector, DEFAULT_RECONNECT_SCHEDULE, type SourceConnector, type SourceConnectorOptions, type ConnectorWebSocket, type ConnectorWebSocketFactory, type ConnectorStatus, } from './connector.js';
+export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, type ConnectorFrame, type RegisterFrame, type ReadyFrame, type RequestFrame, type ResponseFrame, type ErrorFrame, } from './connector-protocol.js';
 export { type DataSourceAdapter, type AdapterReadRequest, type AdapterCommitResult, type Row as AdapterRow, } from './adapter.js';
 export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, type Operation, type ChangeSet, type OutboxEvent, type EventsPage, type Migration, type AdapterCapabilities, } from './contract.js';
 export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';

package/dist/source/index.js

@@ -418,6 +418,12 @@ export function dataSource(options) {
     return abloSource(options);
 }
 export { createPushQueue, InMemoryPushQueueStorage, STANDARD_WEBHOOKS_RETRY_SCHEDULE, } from './pushQueue.js';
+// ── Reverse-channel connector (outbound transport for the commit/load/list leg) ──
+// The dial-out counterpart to `createPushQueue`. Lets a customer serve Data
+// Source `commit`/`load`/`list` from localhost or a locked-down VPC with no
+// public inbound URL — see `connector-protocol.ts`.
+export { createSourceConnector, DEFAULT_RECONNECT_SCHEDULE, } from './connector.js';
+export { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, WS_SOURCE_SUBPROTOCOL, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, connectorFrameSchema, } from './connector-protocol.js';
 export { operationSchema, operationTypeSchema, changeSetSchema, outboxEventSchema, eventsPageSchema, migrationSchema, adapterCapabilitiesSchema, } from './contract.js';
 export { prismaDataSource } from './adapters/prisma.js';
 export { adapterTableMigrations } from './migrations.js';

package/dist/sync/SyncWebSocket.d.ts

@@ -10,7 +10,16 @@
 import { EventEmitter } from 'events';
 import type { MutationOperation } from '../interfaces/index.js';
 import type { ClientSyncDelta } from '../schema/sync-delta-wire.js';
-import type { ClaimError, ClaimRejection } from '../coordination/schema.js';
+import type { ClaimError, ClaimRejection, StaleNotification, ReadDependency } from '../coordination/schema.js';
+/**
+ * Resolution value of a commit ack. `notifications` is present only when a
+ * guarded write (`onStale: 'notify') hit a concurrent change — the
+ * advisory self-heal signal, surfaced both here and via `conflict:notified`.
+ */
+export interface CommitAck {
+    lastSyncId: number;
+    notifications?: StaleNotification[];
+}
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 /**
  * The wire delta the client receives. Derived from the canonical
@@ -266,6 +275,20 @@ export interface CoreSyncEventMap {
     claim_queued: [Record<string, unknown>];
     claim_granted: [Record<string, unknown>];
     claim_lost: [Record<string, unknown>];
+    /**
+     * Notify-instead-of-abort (non-coercion). A committed write guarded with
+     * `onStale: 'notify' collided with a concurrent change; rather than
+     * forcing an outcome, the engine returned the conflicting field's current
+     * value so the actor can solve it. The resolver is the intelligent actor —
+     * an agent reasoning over the change, or a human watching the row. The commit
+     * SUCCEEDED; held ops ('notify') weren't written and the actor re-issues once
+     * it has reconciled. (The claim is the prospective form of the same
+     * non-coercion; this is the in-flight form.)
+     */
+    'conflict:notified': [{
+        clientTxId: string;
+        notifications: StaleNotification[];
+    }];
 }
 /**
  * Collaboration event — app-specific real-time events (selection, cursors, etc.)
@@ -461,9 +484,13 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * NOT auto-retry here — the caller's TransactionQueue owns retry +
      * offline replay semantics and the SDK shouldn't duplicate that logic.
      */
-    sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null): Promise<{
-        lastSyncId: number;
-    }>;
+    /**
+     * Defensively validate the optional `notifications` array off a commit ack.
+     * Untrusted wire data — a malformed entry is dropped rather than throwing,
+     * so a bad notification never sinks an otherwise-successful commit.
+     */
+    private parseNotifications;
+    sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
     /**
      * Send a commit frame without waiting for `mutation_result`.
      *
@@ -472,7 +499,7 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * eventual `mutation_result` frame is intentionally ignored by this
      * instance because no pending resolver is registered.
      */
-    sendCommitQueued(operations: ReadonlyArray<MutationOperation>, clientTxId: string, causedByTaskId?: string | null): void;
+    sendCommitQueued(operations: ReadonlyArray<MutationOperation>, clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): void;
     /**
      * Activate a participant claim on this connection. Multiplexed
      * subscription pattern (Phoenix Channels / Pusher) — the same

package/dist/sync/SyncWebSocket.js

@@ -11,7 +11,7 @@ import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
 import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
-import { subscriptionAckPayloadSchema } from '../coordination/schema.js';
+import { subscriptionAckPayloadSchema, staleNotificationSchema, } from '../coordination/schema.js';
 import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
@@ -320,6 +320,9 @@ export class SyncWebSocket extends EventEmitter {
                         // untrusted wire data that may be malformed or from an older server.
                         const p = message.payload ?? message;
                         const { clientTxId, success, lastSyncId, error } = p ?? {};
+                        // Defensive: validate notifications against the canonical schema —
+                        // untrusted wire data from a possibly-older/newer server.
+                        const notifications = this.parseNotifications(p?.notifications);
                         const pending = typeof clientTxId === 'string'
                             ? this.pendingMutations.get(clientTxId)
                             : undefined;
@@ -331,8 +334,20 @@ export class SyncWebSocket extends EventEmitter {
                             // Coerce defensively — bigint columns serialize as strings
                             // from older servers (see normalizeWireDelta).
                             const ackedSyncId = Number(lastSyncId);
+                            // Notify-instead-of-abort: a guarded write's premise moved. Emit
+                            // the advisory signal so an agent loop can self-heal, AND resolve
+                            // the receipt with it (the commit still succeeded).
+                            if (notifications && notifications.length > 0) {
+                                this.emit('conflict:notified', {
+                                    clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
+                                    notifications,
+                                });
+                            }
                             pending.resolve({
                                 lastSyncId: Number.isFinite(ackedSyncId) ? ackedSyncId : 0,
+                                ...(notifications && notifications.length > 0
+                                    ? { notifications }
+                                    : {}),
                             });
                         }
                         else {
@@ -802,7 +817,7 @@ export class SyncWebSocket extends EventEmitter {
      * `as` narrows the validated op `type` to the wire union — the only
      * loosening, localized to this boundary.
      */
-    buildCommitFrame(operations, clientTxId, causedByTaskId) {
+    buildCommitFrame(operations, clientTxId, causedByTaskId, reads) {
         const payload = {
             operations: operations.map((op) => ({
                 type: op.type,
@@ -817,6 +832,9 @@ export class SyncWebSocket extends EventEmitter {
         };
         if (causedByTaskId)
             payload.causedByTaskId = causedByTaskId;
+        // Batch-level read-set (STORM layer): rows/groups the batch was premised on.
+        if (reads && reads.length > 0)
+            payload.reads = [...reads];
         return { type: 'commit', payload };
     }
     /**
@@ -838,7 +856,23 @@ export class SyncWebSocket extends EventEmitter {
      * NOT auto-retry here — the caller's TransactionQueue owns retry +
      * offline replay semantics and the SDK shouldn't duplicate that logic.
      */
-    sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId) {
+    /**
+     * Defensively validate the optional `notifications` array off a commit ack.
+     * Untrusted wire data — a malformed entry is dropped rather than throwing,
+     * so a bad notification never sinks an otherwise-successful commit.
+     */
+    parseNotifications(raw) {
+        if (!Array.isArray(raw) || raw.length === 0)
+            return undefined;
+        const out = [];
+        for (const entry of raw) {
+            const parsed = staleNotificationSchema.safeParse(entry);
+            if (parsed.success)
+                out.push(parsed.data);
+        }
+        return out.length > 0 ? out : undefined;
+    }
+    sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             return Promise.reject(this.notConnectedError('commit'));
         }
@@ -853,7 +887,7 @@ export class SyncWebSocket extends EventEmitter {
                 // an open turn — keeps the wire shape stable for sessions
                 // that don't use turns. Servers that don't know the field
                 // ignore it; newer servers stamp it onto every delta.
-                const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId);
+                const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
                 this.ws.send(JSON.stringify(frame));
             }
             catch (error) {
@@ -871,11 +905,11 @@ export class SyncWebSocket extends EventEmitter {
      * eventual `mutation_result` frame is intentionally ignored by this
      * instance because no pending resolver is registered.
      */
-    sendCommitQueued(operations, clientTxId, causedByTaskId) {
+    sendCommitQueued(operations, clientTxId, causedByTaskId, reads) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             throw this.notConnectedError('commit');
         }
-        const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId);
+        const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId, reads);
         this.ws.send(JSON.stringify(frame));
     }
     /**

package/dist/transactions/TransactionQueue.d.ts

@@ -12,6 +12,7 @@ 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 } from '../coordination/schema.js';
 export interface UserContext {
     userId: string;
     organizationId: string;
@@ -71,9 +72,11 @@ interface CommitTransaction {
         input?: Record<string, unknown>;
         transactionId?: string;
         readAt?: number | null;
-        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+        onStale?: 'reject' | 'overwrite' | 'notify' | null;
     }>;
     causedByTaskId?: string | null;
+    /** Batch-level read dependencies (STORM read-set), forwarded to the executor. */
+    reads?: ReadDependency[] | null;
     status: 'pending' | 'executing' | 'completed' | 'failed';
     createdAt: number;
     attempts: number;
@@ -151,6 +154,7 @@ export declare class TransactionQueue extends EventEmitter {
     private config;
     private executingCount;
     private optimisticUpdates;
+    private commitNotifications;
     private deltaConfirmationTimeouts;
     private deltaConfirmationRetries;
     private isConnectedFn;
@@ -337,6 +341,7 @@ export declare class TransactionQueue extends EventEmitter {
      */
     enqueueCommit(clientTxId: string, operations: CommitTransaction['operations'], options?: {
         causedByTaskId?: string | null;
+        reads?: ReadDependency[] | null;
     }): void;
     /**
      * Drain pending commit-lane envelopes serially. Transient failures
@@ -353,6 +358,7 @@ export declare class TransactionQueue extends EventEmitter {
      */
     waitForCommitReceipt(clientTxId: string): Promise<{
         lastSyncId: number;
+        notifications?: StaleNotification[];
     }>;
     private isReorderPayload;
     /**

package/dist/transactions/TransactionQueue.js

@@ -409,6 +409,10 @@ export class TransactionQueue extends EventEmitter {
     executingCount = 0;
     // Optimistic update tracking
     optimisticUpdates = new Map();
+    // Stale-context notifications (CoAgent/MTPO notify-instead-of-abort) keyed by
+    // transaction id, populated from the commit ack and drained by
+    // `waitForCommitReceipt` so the receipt carries the self-heal signal.
+    commitNotifications = new Map();
     // LINEAR PATTERN: Track delta confirmation timeouts for awaiting_delta transactions
     // Following Replicache/PowerSync pattern: retry with backoff instead of rolling back
     deltaConfirmationTimeouts = new Map();
@@ -1127,6 +1131,20 @@ export class TransactionQueue extends EventEmitter {
                         const result = await this.mutationExecutor.commit(operations);
                         const lastSyncId = result?.lastSyncId ?? 0;
                         this.noteAck(lastSyncId);
+                        // Notify-instead-of-abort: the server returned stale-context
+                        // notifications for `onStale: 'notify'` ops whose premise moved.
+                        // Every notified op was HELD (not written) — its optimistic state
+                        // must be rolled back here; no delta will ever confirm it. We also
+                        // stamp the signal so `waitForCommitReceipt` carries it onto the
+                        // receipt.
+                        const notifications = result?.notifications;
+                        const heldIds = new Set((notifications ?? []).map((n) => n.id));
+                        for (const { tx } of batchOps) {
+                            const txNotifs = notifications?.filter((n) => n.id === tx.modelId);
+                            if (txNotifs && txNotifs.length > 0) {
+                                this.commitNotifications.set(tx.id, txNotifs);
+                            }
+                        }
                         // Detect server bug: lastSyncId 0 means mutation succeeded but no sync delta was emitted
                         if (lastSyncId === 0) {
                             getContext().observability.captureCommitZeroSyncId({
@@ -1137,6 +1155,19 @@ export class TransactionQueue extends EventEmitter {
                         // LINEAR PATTERN: Mark as awaiting_delta with syncId threshold
                         // Transactions will be confirmed when any delta with id >= lastSyncId arrives
                         for (const { tx } of batchOps) {
+                            // Held op ('notify'): the server withheld the write, so no delta
+                            // will confirm it. Roll back the optimistic update (server
+                            // wins) and complete the transaction now — the agent self-heals
+                            // from the notification rather than waiting out the delta
+                            // timeout. The receipt still resolves (commit succeeded).
+                            if (heldIds.has(tx.modelId)) {
+                                await this.rollbackOptimistic(tx, 'conflict_server_wins');
+                                this.store.updateStatus(tx.id, 'completed');
+                                this.emit('transaction:completed', tx);
+                                this.emit(`transaction:completed:${tx.id}`, tx);
+                                this.optimisticUpdates.delete(tx.id);
+                                continue;
+                            }
                             tx.syncIdNeededForCompletion = lastSyncId;
                             // Safety net: when lastSyncId is 0, DELETE transactions should be confirmed
                             // immediately. DELETEs are idempotent — if no delta was emitted, the entity
@@ -1528,6 +1559,7 @@ export class TransactionQueue extends EventEmitter {
             kind: 'commit',
             operations: [...operations],
             causedByTaskId: options.causedByTaskId ?? null,
+            ...(options.reads ? { reads: options.reads } : {}),
             status: 'pending',
             createdAt: Date.now(),
             attempts: 0,
@@ -1565,6 +1597,7 @@ export class TransactionQueue extends EventEmitter {
                     const result = await this.mutationExecutor.commit(tx.operations, {
                         idempotencyKey: tx.id,
                         causedByTaskId: tx.causedByTaskId ?? undefined,
+                        ...(tx.reads ? { reads: tx.reads } : {}),
                     });
                     tx.lastSyncId = result?.lastSyncId ?? 0;
                     this.noteAck(tx.lastSyncId);
@@ -1610,10 +1643,18 @@ export class TransactionQueue extends EventEmitter {
      * of `ablo.commits.create()`.
      */
     waitForCommitReceipt(clientTxId) {
+        // Drain any stale-context notifications stamped for this tx on the ack.
+        const drainNotifications = () => {
+            const n = this.commitNotifications.get(clientTxId);
+            if (!n)
+                return undefined;
+            this.commitNotifications.delete(clientTxId);
+            return n.length > 0 ? n : undefined;
+        };
         return new Promise((resolve, reject) => {
             const existing = this.commitStore.get(clientTxId);
             if (existing?.status === 'completed') {
-                resolve({ lastSyncId: existing.lastSyncId ?? 0 });
+                resolve({ lastSyncId: existing.lastSyncId ?? 0, notifications: drainNotifications() });
                 return;
             }
             if (existing?.status === 'failed' && existing.error) {
@@ -1622,7 +1663,7 @@ export class TransactionQueue extends EventEmitter {
             }
             const onCompleted = (tx) => {
                 cleanup();
-                resolve({ lastSyncId: tx.lastSyncId ?? 0 });
+                resolve({ lastSyncId: tx.lastSyncId ?? 0, notifications: drainNotifications() });
             };
             const onFailed = ({ error }) => {
                 cleanup();