@abloatai/ablo 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- **Notify-instead-of-abort: non-coercive conflict handling + read-set (the "did anything I looked at change?" layer).**
+
+  The principle: on a stale-context conflict the engine now **surfaces the current state and lets the actor — agent or human — resolve it**, instead of forcing an outcome. See `docs/concurrency-convention.md`.
+
+  **`onStale` redesigned — Stripe-aligned values (BREAKING).**
+
+  The mode set is now `'reject' | 'overwrite' | 'notify'`. Each value names its outcome:
+  - **`notify` (new, non-coercive)** — the conflicting write is **held** (not applied) and the commit returns a `StaleNotification` carrying the conflicting field's *current* value, so the actor reconciles and re-commits rather than losing work. The rest of the batch still commits.
+  - **`overwrite`** (was `force`) — blind last-writer-wins, no signal.
+  - **`reject`** (default, unchanged) — throws `AbloStaleContextError`.
+
+  Migration:
+  - `onStale: 'force'` → `onStale: 'overwrite'`.
+  - `onStale: 'flag'` / `onStale: 'merge'` → `onStale: 'notify'` (both removed; `notify` is the single hold-and-surface mode).
+
+  **`StaleNotification` — the new advisory signal.** New public type + `staleNotificationSchema`:
+  `{ object: 'stale_notification', model, id, readAt, observedSyncId, conflictingFields, currentValues, writtenBy, group? }`. Delivered two ways:
+  - on the receipt — `CommitReceipt.notifications` (and `CommitResult.notifications`);
+  - on a new SDK event — **`conflict:notified`** `{ clientTxId, notifications }` (mirrors `reconciliation:needed` / `sync:rollback`).
+
+  **Read-set (`reads[]`) — declare what you looked at, not just what you write (new).** A commit may carry batch-level read dependencies; a moved premise fires that entry's `onStale` over the whole batch (`notify` holds every write + notifies, `reject` aborts, `overwrite` proceeds). Two granularities:
+  - **Row** — `{ model, id, readAt, fields? }`: did this row (optionally these fields) change?
+  - **Group** — `{ group, readAt }`: did anything in this sync group (`deck:abc`, `org:X`) change? — the same unit a participant watches and claims.
+
+  New public type `ReadDependency` + `readDependencySchema`; available on `ablo.commits.create({ operations, reads })` and the lower-level write options. This closes the gap the write-target check alone could not: a premise that changed without the written row changing.
+
+  **Conflict policy.** `ConflictDecision` gains `{ action: 'notify' }`; `defaultPolicy` maps `onStale: 'notify'` → notify-and-hold, everything else → reject. `StaleContextConflict.requestedMode` is added so custom policies can honor the caller's declared intent.
+
+- **Data Source reverse-channel connector (new).** A customer Data Source can now **dial out** to the engine over a single outbound WebSocket (`ablo.source.v1` subprotocol) instead of exposing an inbound HTTP endpoint — the deployment shape private/VPC stores need.
+
+  - **`createSourceConnector({ apiKey, handler, baseURL? })`** (new public API, exported from the root and `/source`) — opens one outbound socket (Node global `WebSocket`, no new dependency), with reconnect/backoff, and serves the customer's existing Data Source `handler`.
+  - Server side: a connector registry + `/v1/source/listen` upgrade route bridge requests down / responses up, teed into `SourceClient` through the storage resolver.
+  - **Trust model unchanged:** the Standard-Webhooks HMAC is signed *above* the transport, so the socket carries the signed envelope byte-for-byte and the customer's `verifyAbloSourceRequest` is untouched. Transport changes, trust model doesn't.
+  - Opt-in per source via `reverse_channel_prod` (migration `20260622150000`); gated in `authorizeUpgrade`.
+
 ## 0.14.0
 
 ### Minor Changes

package/dist/Database.d.ts

@@ -17,7 +17,7 @@ interface PersistedMutation {
     timestamp: string;
     writeOptions?: {
         readAt?: number | null;
-        onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+        onStale?: 'reject' | 'overwrite' | 'notify' | null;
     };
 }
 /** Persisted transaction for offline/retry support.

package/dist/auth/index.d.ts

@@ -34,6 +34,10 @@ export interface MintUserSessionRequest {
     readonly baseUrl: string;
     /** The end user's external IdP id — becomes the session's `participantId`. */
     readonly userId: string;
+    /** Target org for a cross-org (platform) mint — the Stripe-Connect
+     *  `Stripe-Account` analogue. Requires the `sk_` to carry
+     *  `ephemeral:mint-any-org`; omit to mint into the key's own org. */
+    readonly organizationId?: string;
     readonly syncGroups?: readonly string[];
     readonly ttlSeconds: number;
     readonly label?: string;

package/dist/auth/index.js

@@ -107,6 +107,7 @@ export async function mintUserSessionKey(options) {
             },
             body: JSON.stringify({
                 user: { id: options.userId },
+                ...(options.organizationId ? { organizationId: options.organizationId } : {}),
                 ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
                 ttlSeconds: options.ttlSeconds,
                 ...(options.label ? { label: options.label } : {}),

package/dist/cli.cjs

@@ -277067,12 +277067,65 @@ var targetRefSchema = import_zod3.z.object({
   field: import_zod3.z.string().optional(),
   meta: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()).optional()
 });
-var onStaleModeSchema = import_zod3.z.enum(["reject", "force", "flag", "merge"]);
+var onStaleModeSchema = import_zod3.z.enum(["reject", "overwrite", "notify"]);
 var writeGuardSchema = import_zod3.z.object({
   readAt: import_zod3.z.number().nullish(),
   onStale: onStaleModeSchema.nullish(),
   bypass: import_zod3.z.boolean().optional()
 });
+var staleNotificationSchema = import_zod3.z.object({
+  /** Stripe-style object tag — every returned object names its type. */
+  object: import_zod3.z.literal("stale_notification").optional(),
+  /** Model name of the conflicting row. */
+  model: import_zod3.z.string(),
+  /** Row id. */
+  id: import_zod3.z.string(),
+  /** The watermark the committer reasoned against (its `readAt`). */
+  readAt: import_zod3.z.number(),
+  /**
+   * Newest delta id on the row — the committer's new watermark. Re-capture
+   * context at/after this id to reconcile.
+   */
+  observedSyncId: import_zod3.z.number(),
+  /**
+   * Fields whose concurrent change collided with this write (intersection of
+   * the committer's written columns and a newer delta's `changed_fields`).
+   * Empty ⇒ a whole-entity change (CREATE/DELETE/legacy delta).
+   */
+  conflictingFields: import_zod3.z.array(import_zod3.z.string()),
+  /**
+   * Post-conflict live values of `conflictingFields` — the part a plain stale
+   * error never carried. Lets the LLM self-heal without a round-trip read.
+   */
+  currentValues: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()),
+  /** Who wrote the conflicting delta. */
+  writtenBy: import_zod3.z.object({
+    kind: participantKindSchema,
+    id: import_zod3.z.string()
+  }),
+  /**
+   * Set when this notification is for a GROUP read-dependency (e.g. `deck:abc`,
+   * `slide:s1`) rather than a single row — "something in the group you read
+   * changed." For a group notification `conflictingFields`/`currentValues` are
+   * empty (the change could span many rows); re-read the group at
+   * `observedSyncId` to reconcile. Absent ⇒ a row-scoped notification.
+   */
+  group: import_zod3.z.string().optional()
+});
+var readDependencySchema = import_zod3.z.union([
+  import_zod3.z.object({
+    model: import_zod3.z.string(),
+    id: import_zod3.z.string(),
+    readAt: import_zod3.z.number(),
+    fields: import_zod3.z.array(import_zod3.z.string()).optional(),
+    onStale: onStaleModeSchema.optional()
+  }),
+  import_zod3.z.object({
+    group: import_zod3.z.string(),
+    readAt: import_zod3.z.number(),
+    onStale: onStaleModeSchema.optional()
+  })
+]);
 var claimStatusSchema = import_zod3.z.enum([
   "active",
   "committed",

package/dist/client/Ablo.d.ts

@@ -18,6 +18,7 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { SyncEngineConfig, SyncLogger, MutationExecutor, MutationDispatcher, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
@@ -424,7 +425,7 @@ export interface CommitOperationInput {
     readonly data?: 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 CommitCreateOptions {
     readonly claimRef?: string | {
@@ -432,7 +433,7 @@ export interface CommitCreateOptions {
     } | null;
     readonly idempotencyKey?: string | null;
     readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /**
      * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
      * surface). Same vocabulary as the per-model writes: the handle's
@@ -445,11 +446,29 @@ export interface CommitCreateOptions {
     readonly operation?: CommitOperationInput;
     readonly operations?: readonly CommitOperationInput[];
     readonly wait?: CommitWait;
+    /**
+     * Batch-level read dependencies (the STORM "did anything I looked at change?"
+     * layer). Declare the rows (`{model,id,readAt,fields?}`) or sync groups
+     * (`{group,readAt}`, e.g. `deck:abc`) this batch was premised on; the server
+     * validates none moved since `readAt` and fires the entry's `onStale` over the
+     * batch. Distinct from the write-target `readAt` — this guards what you READ,
+     * not what you write.
+     */
+    readonly reads?: readonly ReadDependency[] | null;
 }
 export interface CommitReceipt {
     readonly id: string;
     readonly status: CommitWait;
     readonly lastSyncId?: number;
+    /**
+     * Stale-context notifications (notify-instead-of-abort, non-coercion). Present
+     * only when this commit guarded a write with `onStale: 'notify' and
+     * the premise moved concurrently — the conflicting field's current value,
+     * handed back as data instead of a forced `AbloStaleContextError`. The engine
+     * surfaces state; the intelligent actor (agent or human) decides how to
+     * resolve. Also fires on `conflict:notified`.
+     */
+    readonly notifications?: readonly StaleNotification[];
 }
 export interface CommitResource {
     create(options: CommitCreateOptions): Promise<CommitReceipt>;
@@ -465,7 +484,7 @@ export interface ModelMutationOptions extends ClaimedOptions {
     } | null;
     readonly idempotencyKey?: string | null;
     readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
     readonly wait?: CommitWait;
     readonly claim?: ClaimHandle | ClaimOptions | null;
 }
@@ -543,6 +562,11 @@ export interface CreateUserSessionParams {
     user: {
         id: string;
     };
+    /** Mint the session into THIS organization instead of the key's own org — the
+     *  Stripe Connect `Stripe-Account` pattern, for a platform serving many tenants
+     *  from one backend. Requires the `sk_` to carry the `ephemeral:mint-any-org`
+     *  scope; omit for the normal single-tenant case. */
+    organizationId?: string;
     /** Sync groups this session may subscribe to — typed (`'default'` or
      *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
      *  `@abloatai/ablo/schema`). Omit for the server default:

package/dist/client/Ablo.js

@@ -606,7 +606,7 @@ function createDefaultMutationExecutor(getWs) {
                 : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
         try {
             return await ws.sendCommit(operations, clientTxId, undefined, // use sendCommit's built-in 15s default; no per-call override
-            options?.causedByTaskId);
+            options?.causedByTaskId, options?.reads);
         }
         catch (err) {
             // Wrap transport-level failures as connection errors so the
@@ -1412,12 +1412,19 @@ export function Ablo(options) {
             // SyncClient we already hold from createInternalComponents —
             // no need to leak an accessor through BaseSyncedStore.
             const queue = syncClient.getTransactionQueue();
-            queue.enqueueCommit(clientTxId, operations);
+            queue.enqueueCommit(clientTxId, operations, {
+                ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
+            });
             if (wait === 'queued') {
                 return { id: clientTxId, status: 'queued' };
             }
-            const { lastSyncId } = await queue.waitForCommitReceipt(clientTxId);
-            return { id: clientTxId, status: 'confirmed', lastSyncId };
+            const { lastSyncId, notifications } = await queue.waitForCommitReceipt(clientTxId);
+            return {
+                id: clientTxId,
+                status: 'confirmed',
+                lastSyncId,
+                ...(notifications && notifications.length > 0 ? { notifications } : {}),
+            };
         },
     };
     async function retrieveModel(modelName, id, options) {

package/dist/client/sessionMint.js

@@ -40,6 +40,7 @@ export async function mintSession(params, ctx) {
             apiKey,
             baseUrl,
             userId: params.user.id,
+            ...(params.organizationId ? { organizationId: params.organizationId } : {}),
             ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
             ttlSeconds: params.ttlSeconds ?? 900,
             ...(ctx.fetch ? { fetch: ctx.fetch } : {}),

package/dist/client/writeOptionsSchema.d.ts

@@ -17,9 +17,8 @@
 import { z } from 'zod';
 export declare const onStaleModeSchema: z.ZodEnum<{
     reject: "reject";
-    force: "force";
-    flag: "flag";
-    merge: "merge";
+    overwrite: "overwrite";
+    notify: "notify";
 }>;
 export declare const writeOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -31,9 +30,8 @@ export declare const writeOptionsSchema: 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";
     }>>>;
     claim: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         id: z.ZodString;

package/dist/client/writeOptionsSchema.js

@@ -16,7 +16,7 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
-export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export const writeOptionsSchema = z.object({
     /** Server-side mutation_log cache key; `null` opts out of retry-safety. */
     idempotencyKey: z.string().min(1).max(255).nullish(),

package/dist/coordination/schema.d.ts

@@ -82,15 +82,19 @@ export declare const targetRefSchema: z.ZodObject<{
 export type TargetRef = z.infer<typeof targetRefSchema>;
 /**
  * Mode applied when a write's snapshot watermark (`readAt`) is older than the
- * target row's latest delta. `'reject'` is the default whenever `readAt` is
- * present. `'flag'` and `'merge'` are reserved — the wire accepts them, the
- * server does not yet enforce them.
+ * target row's latest delta. Three dispositions, split by the non-coercion
+ * convention (see docs/concurrency-convention.md):
+ *   • `notify`    — NON-COERCIVE: hold the write, return a `StaleNotification`
+ *                   with the current value; the actor (agent or human) resolves.
+ *   • `reject`    — coercive escape hatch: throw `AbloStaleContextError`
+ *                   (default when `readAt` is present).
+ *   • `overwrite` — coercive escape hatch: apply blindly last-writer-wins, no
+ *                   signal.
  */
 export declare const onStaleModeSchema: z.ZodEnum<{
     reject: "reject";
-    force: "force";
-    flag: "flag";
-    merge: "merge";
+    overwrite: "overwrite";
+    notify: "notify";
 }>;
 export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
 /**
@@ -103,13 +107,88 @@ export declare const writeGuardSchema: 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";
     }>>>;
     bypass: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type WriteGuard = z.infer<typeof writeGuardSchema>;
+/**
+ * The advisory signal returned to a committer whose write hit a stale-context
+ * conflict under `onStale: 'notify'` — the engine's answer to "the typed value
+ * you reasoned against changed while you were away."
+ *
+ * Philosophy: NON-COERCION. The engine's job is to surface the truthful current
+ * state and let the intelligent actor — agent OR human — decide what to do; it
+ * does NOT force an outcome. The two *forcing* dispositions are `reject`
+ * (force-abort, discards the work) and `overwrite` (force-clobber). This
+ * notification is the non-coercive path: instead of throwing, the server hands
+ * back the conflicting field's *current* value as data so the actor can solve
+ * it. The CLAIM is the prospective form of the same principle (coordinate
+ * before acting); this notification is the in-flight form (here's what changed,
+ * you resolve). Both an agent reasoning over the change and a human watching the
+ * row are valid resolvers. (Cf. CoAgent/MTPO, arXiv:2606.15376, which bets the
+ * resolver is specifically an LLM; Ablo's bet is the same non-coercion, actor
+ * left to agent or human.) Rides on the commit ack alongside `lastSyncId`; an
+ * empty/absent array means no premise moved.
+ *
+ * Only `notify` produces this: the conflicting op was HELD (not written), and
+ * the actor reconciles against `currentValues` and re-commits. (`reject` throws,
+ * `overwrite` is silent — neither notifies.)
+ */
+export declare const staleNotificationSchema: z.ZodObject<{
+    object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
+    model: z.ZodString;
+    id: z.ZodString;
+    readAt: z.ZodNumber;
+    observedSyncId: z.ZodNumber;
+    conflictingFields: z.ZodArray<z.ZodString>;
+    currentValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    writtenBy: z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StaleNotification = z.infer<typeof staleNotificationSchema>;
+/**
+ * A read DEPENDENCY declared on a commit — the STORM "did anything I looked at
+ * change?" layer (vs. the write-target check that only validates the rows being
+ * written). The server re-runs stale detection against each declared read at
+ * `readAt`; a moved premise fires the entry's `onStale` disposition (default
+ * `reject`) over the WHOLE batch (`notify` holds every write + notifies;
+ * `reject` aborts; `overwrite` proceeds silently). Two granularities, choice:
+ *
+ *   • ROW   — `{ model, id, readAt, fields? }`: did this specific row (optionally
+ *             these fields) change? The literal STORM/per-object premise.
+ *   • GROUP — `{ group, readAt }`: did ANYTHING in this sync group change? `group`
+ *             is a sync-group key like `deck:abc` or `slide:s1` — the same unit a
+ *             human/agent watches and claims. Coarser, and more Ablo-native.
+ */
+export declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
+    model: z.ZodString;
+    id: z.ZodString;
+    readAt: z.ZodNumber;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    onStale: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    readAt: z.ZodNumber;
+    onStale: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+}, z.core.$strip>]>;
+export type ReadDependency = z.infer<typeof readDependencySchema>;
 /**
  * Lifecycle of an claim — the Stripe `PaymentIntent.status` shape. Absent on
  * the wire ⇒ `'active'` (additive back-compat). The server stamps `'active'`
@@ -407,9 +486,8 @@ export declare const commitOperationSchema: 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";
     }>>>;
     bypass: z.ZodOptional<z.ZodBoolean>;
     type: z.ZodEnum<{

package/dist/coordination/schema.js

@@ -80,11 +80,16 @@ export const targetRefSchema = z.object({
 // ─────────────────────────────────────────────────────────────────────────
 /**
  * Mode applied when a write's snapshot watermark (`readAt`) is older than the
- * target row's latest delta. `'reject'` is the default whenever `readAt` is
- * present. `'flag'` and `'merge'` are reserved — the wire accepts them, the
- * server does not yet enforce them.
+ * target row's latest delta. Three dispositions, split by the non-coercion
+ * convention (see docs/concurrency-convention.md):
+ *   • `notify`    — NON-COERCIVE: hold the write, return a `StaleNotification`
+ *                   with the current value; the actor (agent or human) resolves.
+ *   • `reject`    — coercive escape hatch: throw `AbloStaleContextError`
+ *                   (default when `readAt` is present).
+ *   • `overwrite` — coercive escape hatch: apply blindly last-writer-wins, no
+ *                   signal.
  */
-export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 /**
  * The optimistic guard carried on a commit operation. `readAt` is the
  * snapshot watermark from `context.capture` (null/absent ⇒ unguarded write).
@@ -96,6 +101,96 @@ export const writeGuardSchema = z.object({
     onStale: onStaleModeSchema.nullish(),
     bypass: z.boolean().optional(),
 });
+/**
+ * The advisory signal returned to a committer whose write hit a stale-context
+ * conflict under `onStale: 'notify'` — the engine's answer to "the typed value
+ * you reasoned against changed while you were away."
+ *
+ * Philosophy: NON-COERCION. The engine's job is to surface the truthful current
+ * state and let the intelligent actor — agent OR human — decide what to do; it
+ * does NOT force an outcome. The two *forcing* dispositions are `reject`
+ * (force-abort, discards the work) and `overwrite` (force-clobber). This
+ * notification is the non-coercive path: instead of throwing, the server hands
+ * back the conflicting field's *current* value as data so the actor can solve
+ * it. The CLAIM is the prospective form of the same principle (coordinate
+ * before acting); this notification is the in-flight form (here's what changed,
+ * you resolve). Both an agent reasoning over the change and a human watching the
+ * row are valid resolvers. (Cf. CoAgent/MTPO, arXiv:2606.15376, which bets the
+ * resolver is specifically an LLM; Ablo's bet is the same non-coercion, actor
+ * left to agent or human.) Rides on the commit ack alongside `lastSyncId`; an
+ * empty/absent array means no premise moved.
+ *
+ * Only `notify` produces this: the conflicting op was HELD (not written), and
+ * the actor reconciles against `currentValues` and re-commits. (`reject` throws,
+ * `overwrite` is silent — neither notifies.)
+ */
+export const staleNotificationSchema = z.object({
+    /** Stripe-style object tag — every returned object names its type. */
+    object: z.literal('stale_notification').optional(),
+    /** Model name of the conflicting row. */
+    model: z.string(),
+    /** Row id. */
+    id: z.string(),
+    /** The watermark the committer reasoned against (its `readAt`). */
+    readAt: z.number(),
+    /**
+     * Newest delta id on the row — the committer's new watermark. Re-capture
+     * context at/after this id to reconcile.
+     */
+    observedSyncId: z.number(),
+    /**
+     * Fields whose concurrent change collided with this write (intersection of
+     * the committer's written columns and a newer delta's `changed_fields`).
+     * Empty ⇒ a whole-entity change (CREATE/DELETE/legacy delta).
+     */
+    conflictingFields: z.array(z.string()),
+    /**
+     * Post-conflict live values of `conflictingFields` — the part a plain stale
+     * error never carried. Lets the LLM self-heal without a round-trip read.
+     */
+    currentValues: z.record(z.string(), z.unknown()),
+    /** Who wrote the conflicting delta. */
+    writtenBy: z.object({
+        kind: participantKindSchema,
+        id: z.string(),
+    }),
+    /**
+     * Set when this notification is for a GROUP read-dependency (e.g. `deck:abc`,
+     * `slide:s1`) rather than a single row — "something in the group you read
+     * changed." For a group notification `conflictingFields`/`currentValues` are
+     * empty (the change could span many rows); re-read the group at
+     * `observedSyncId` to reconcile. Absent ⇒ a row-scoped notification.
+     */
+    group: z.string().optional(),
+});
+/**
+ * A read DEPENDENCY declared on a commit — the STORM "did anything I looked at
+ * change?" layer (vs. the write-target check that only validates the rows being
+ * written). The server re-runs stale detection against each declared read at
+ * `readAt`; a moved premise fires the entry's `onStale` disposition (default
+ * `reject`) over the WHOLE batch (`notify` holds every write + notifies;
+ * `reject` aborts; `overwrite` proceeds silently). Two granularities, choice:
+ *
+ *   • ROW   — `{ model, id, readAt, fields? }`: did this specific row (optionally
+ *             these fields) change? The literal STORM/per-object premise.
+ *   • GROUP — `{ group, readAt }`: did ANYTHING in this sync group change? `group`
+ *             is a sync-group key like `deck:abc` or `slide:s1` — the same unit a
+ *             human/agent watches and claims. Coarser, and more Ablo-native.
+ */
+export const readDependencySchema = z.union([
+    z.object({
+        model: z.string(),
+        id: z.string(),
+        readAt: z.number(),
+        fields: z.array(z.string()).optional(),
+        onStale: onStaleModeSchema.optional(),
+    }),
+    z.object({
+        group: z.string(),
+        readAt: z.number(),
+        onStale: onStaleModeSchema.optional(),
+    }),
+]);
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 2 — PESSIMISTIC claim / claim-lease
 // ─────────────────────────────────────────────────────────────────────────

package/dist/index.d.ts

@@ -57,6 +57,7 @@ export type { AbloPersistence } from './client/persistence.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { createSourceConnector, type SourceConnector, type SourceConnectorOptions, type ConnectorStatus, } from './source/connector.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
@@ -67,6 +68,8 @@ export type { Environment, KeyPrefixEnvironment } from './environment.js';
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
 export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
+export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
+export type { StaleNotification, ReadDependency } from './coordination/schema.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';

package/dist/index.js

@@ -69,6 +69,10 @@ export default Ablo;
 // canonical, skip this entirely. Type counterparts live under
 // `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+// Reverse-channel connector: serve the Data Source `commit`/`load`/`list` leg
+// over an OUTBOUND WebSocket (localhost / locked-down VPC, no public inbound
+// URL). The dial-out counterpart to `createPushQueue` for the `events` leg.
+export { createSourceConnector, } from './source/connector.js';
 // Schema DSL is intentionally published from `@abloatai/ablo/schema`.
 // Keeping it out of the root import preserves one clean runtime surface:
 // `import Ablo from '@abloatai/ablo'`.
@@ -90,6 +94,11 @@ export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromK
 // (e.g. an agent tool's input schema). Runtime twin of `MutationOptions`,
 // drift-guarded at compile time.
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
+// Notify-instead-of-abort signal: the value handed back to a committer whose
+// write hit a stale-context conflict under `onStale: 'notify' so its
+// agent can self-heal rather than discard work (see coordination/schema.ts and
+// docs/coordination.md → "Notify, do not abort").
+export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';

package/dist/interfaces/index.d.ts

@@ -5,6 +5,7 @@
  * Consumers implement them to wire in their own logging, observability,
  * GraphQL client, session handling, and analytics.
  */
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -140,6 +141,13 @@ export interface ModelDebugLoggerContract {
 /** Result of a successful `commit()` — server's sync cursor after the batch landed. */
 export interface CommitResult {
     lastSyncId: number;
+    /**
+     * Stale-context notifications (CoAgent/MTPO notify-instead-of-abort). Present
+     * only when a write guarded with `onStale: 'notify' collided with a
+     * concurrent change; the committer self-heals from these rather than
+     * receiving an `AbloStaleContextError`. See `StaleNotification`.
+     */
+    notifications?: StaleNotification[];
 }
 /**
  * Per-call knobs attached to any mutation. Mirrors Stripe's options
@@ -159,7 +167,7 @@ export interface MutationOptions {
     label?: string;
     wait?: 'queued' | 'confirmed';
     readAt?: number | null;
-    onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /** Claim-pin attribution: the id (or `{ id }`) of the claim this write
      *  belongs to. Distinct from the `claim` HANDLE on the model write params —
      *  this is the low-level reference the commit carries to bypass the holder's
@@ -174,6 +182,14 @@ export interface MutationOptions {
      * id). Kept optional for wire-compat; always `null` from the client.
      */
     causedByTaskId?: string | null;
+    /**
+     * Batch-level read dependencies (the STORM "did anything I looked at change?"
+     * layer). Each entry is a row (`{model,id,readAt,fields?}`) or a sync group
+     * (`{group,readAt}`) this write was premised on; the server validates none
+     * moved since `readAt` and fires the entry's `onStale` over the batch.
+     * Distinct from per-op `readAt` (which guards only the row being written).
+     */
+    reads?: ReadDependency[] | null;
 }
 /**
  * The `MutationOptions` subset carried per-write through the offline
@@ -208,7 +224,7 @@ export interface MutationOperation {
      */
     transactionId?: string;
     readAt?: number | null;
-    onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /**
      * Per-op idempotency + audit metadata. `idempotencyKey` doubles as
      * the `mutation_log.client_tx_id` cache key; `label` is persisted to