@abloatai/ablo 0.14.0 → 0.15.1

package/dist/source/connector.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const DEFAULT_RECONNECT_SCHEDULE: readonly number[];
+/**
+ * Minimal structural WebSocket surface — the browser/`globalThis.WebSocket` API,
+ * which Node 24+ implements natively. The `ws` package's default export also
+ * satisfies this (it exposes `addEventListener`). Injectable for tests.
+ */
+export interface ConnectorWebSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    addEventListener(type: 'open', listener: () => void): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: (event: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+}
+export type ConnectorWebSocketFactory = (url: string, protocols: readonly string[]) => ConnectorWebSocket;
+/** Lifecycle of the connector's socket, surfaced via `onStatus`. */
+export type ConnectorStatus = 'connecting' | 'ready' | 'disconnected';
+export interface SourceConnectorOptions {
+    /**
+     * Ablo project API key. Defaults gate to `sk_test_*` (local-dev / sandbox);
+     * an `sk_live_*` key is only accepted when the source has opted into
+     * reverse-channel for production server-side.
+     */
+    readonly apiKey: string;
+    /**
+     * The unchanged Data Source handler — `dataSource(options)` /
+     * `abloSource(options)`. The connector feeds it synthesized `Request`s and
+     * relays the `Response`s back; it never inspects or alters them.
+     */
+    readonly handler: (request: Request) => Promise<Response>;
+    /** Ablo Cloud base URL. Default `https://api.abloatai.com`. */
+    readonly baseURL?: string;
+    /** Inject a WebSocket implementation. Default `globalThis.WebSocket`. */
+    readonly webSocket?: ConnectorWebSocketFactory;
+    /** Override reconnect backoff. Default `DEFAULT_RECONNECT_SCHEDULE`. */
+    readonly reconnectSchedule?: readonly number[];
+    /** Random jitter on reconnect delays. Default ±10%. Set 0 to disable. */
+    readonly jitter?: number;
+    /** Advisory client id sent in the `register` frame for server-side logs. */
+    readonly client?: string;
+    /** Pluggable clock (tests). */
+    readonly now?: () => number;
+    /** Observe connection lifecycle transitions. */
+    readonly onStatus?: (status: ConnectorStatus) => void;
+    /** Observe non-fatal errors (decode failures, handler throws, socket errors). */
+    readonly onError?: (error: unknown) => void;
+}
+export interface SourceConnector {
+    /**
+     * Run the connect → serve → reconnect loop until `signal` aborts. Resolves
+     * when aborted. Rejects only on a fatal, non-retryable condition (e.g. no
+     * WebSocket implementation available).
+     */
+    run(signal: AbortSignal): Promise<void>;
+}
+export declare function createSourceConnector(options: SourceConnectorOptions): SourceConnector;

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;
     /**