@abloatai/ablo 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 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
+
+- Claim API consistency + coordination docs
+  - **React:** document `useWatch` (scoped presence + read-interest, with `claim`/`hydrate`/`paused` options) and `usePeers` (read-only presence) — previously exported but undocumented.
+  - **HTTP claim surface:** `HttpClaimApi` is now a mechanically derived async projection of the reactive `ClaimApi` (`AwaitedClaimMethod`), so the two transports can never drift. No behavior change — the only difference remains the `Promise` wrapper that statelessness forces on `state`/`queue`/`reorder`.
+  - **Naming:** unified the claim read verb to `state` across every layer (the internal `ModelCollaboration.observe` is now `state`, matching the public `ablo.<model>.claim.state({ id })`).
+  - **Docs:** corrected the `Claim` object reference — the field is `reason` (serialized on the wire as `action`), and `createdAt`/`expiresAt` are `number` (epoch-ms), not strings; corrected the claim options to `reason` and `queue`.
+
 ## 0.13.0
 
 ### Minor Changes

package/dist/BaseSyncedStore.js

@@ -781,47 +781,54 @@ export class BaseSyncedStore {
     startCredentialLifecycle(getToken) {
         this.stopCredentialLifecycle();
         this.setCredentialRefresher(getToken);
-        // A transient failure is swallowed: the engine keeps its current token and
-        // the next trigger — or the reactive `credential_stale` path — retries. We
-        // never tear down or sign out on a failed proactive roll.
+        // Re-mint through the SAME single-flight path the FSM's reactive probe uses
+        // (`performCredentialRefresh`) rather than calling `getToken()` directly. Two
+        // wins over the old direct call:
+        //   - SINGLE-FLIGHT: a wake nudge, an in-flight probe, and this proactive
+        //     roll share one in-flight promise — no double-mint thrash.
+        //   - The tri-state is HONOURED. The old code did `if (token) {…}` and
+        //     dropped a `null` on the floor — a zombie session that re-minted on
+        //     every tab focus and logged "signing out" forever without ever signing
+        //     out. `session_error` now drives the FSM to actually expire.
         const refresh = async () => {
-            try {
-                const token = await getToken();
-                if (token) {
-                    // Push into the shared credential source (read lazily by bootstrap
-                    // HTTP, probes, and the WS reconnect URL), then nudge a parked
-                    // connection to re-probe with the fresh key. Same two steps the
-                    // engine's `setAuthToken` wrapper performs.
-                    this.auth?.setAuthToken(token);
-                    this.nudgeReconnect();
-                }
+            const outcome = await this.performCredentialRefresh();
+            if (outcome === 'refreshed') {
+                // Fresh key already pushed into the credential source by
+                // `performCredentialRefresh`; nudge a parked connection to re-probe.
+                this.nudgeReconnect();
             }
-            catch {
-                // transient (offline / mint hiccup) — a later trigger retries.
+            else if (outcome === 'session_error') {
+                // The long-lived login is gone (mint answered 401/403). Surface it —
+                // the proactive path's job is to report this, not hide it. A no-op in
+                // FSM states that don't accept the event (the probe converges on
+                // sign-out there anyway); `session_expired`'s onEnter owns the log.
+                this.connectionManager?.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
             }
+            // 'network_error' → transient (offline / mint hiccup); the next timer tick
+            // or the FSM's own probe retries. Never sign out for it.
         };
         // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled) tick
-        // is recovered by the next, or by the reactive probe.
+        // is recovered by the next, or by the reactive probe. The timer is the sole
+        // proactive PRE-ROLL — it keeps the key warm ahead of expiry even while the
+        // socket sits healthy-`connected` (a state the FSM never probes unprompted).
         const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
         const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
         const teardowns = [() => clearInterval(timer)];
         if (typeof window !== 'undefined') {
-            const onTrigger = () => void refresh();
-            window.addEventListener('online', onTrigger);
-            // OS-wake: the desktop shell bridges Electron `powerMonitor` 'resume' to
-            // this DOM event (visibilitychange does NOT fire on wake-from-sleep, so a
-            // nap longer than the TTL would otherwise leave a dead key untouched).
-            window.addEventListener('ablo:wake', onTrigger);
-            teardowns.push(() => window.removeEventListener('online', onTrigger));
-            teardowns.push(() => window.removeEventListener('ablo:wake', onTrigger));
-        }
-        if (typeof document !== 'undefined') {
-            const onVisible = () => {
-                if (document.visibilityState === 'visible')
-                    void refresh();
-            };
-            document.addEventListener('visibilitychange', onVisible);
-            teardowns.push(() => document.removeEventListener('visibilitychange', onVisible));
+            // OS-wake (desktop only): the Electron shell bridges `powerMonitor`
+            // 'resume' to this DOM event. This is the ONE event-trigger the lifecycle
+            // still owns, because `visibilitychange` does NOT fire on wake-from-sleep
+            // and — unlike `online`/`visibilitychange` — the ConnectionManager's own
+            // browser listeners (`setupBrowserListeners`) don't cover wake.
+            //
+            // The `online` and `visibilitychange` listeners that used to live here
+            // were REMOVED: the FSM already re-probes on NETWORK_ONLINE / TAB_VISIBLE
+            // through this exact credential path, so registering them here too only
+            // fired a second, null-swallowing mint per focus — the "session-key
+            // POSTed on every tab focus" spam in the console.
+            const onWake = () => void refresh();
+            window.addEventListener('ablo:wake', onWake);
+            teardowns.push(() => window.removeEventListener('ablo:wake', onWake));
         }
         this.credentialLifecycleTeardown = () => {
             for (const t of teardowns)

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/batching/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `@abloatai/ablo/batching` — a dependency-free batch-coalescing primitive.
+ *
+ * Accumulate items issued close together (the canonical case: a synchronous
+ * burst, e.g. `Promise.all([ a(), b(), c() ])` in one event-loop tick) and
+ * dispatch them as ONE atomic batch instead of one call each. This is the
+ * scheduling essence of Ablo's `TransactionQueue` (and Linear's sync engine) —
+ * microtask same-tick staging, size/cost/delay flush triggers, and in-flight
+ * backpressure — distilled to a pure state machine with NO dependency on
+ * models, MobX, IndexedDB, or the wire. Consumers inject the actual dispatch.
+ *
+ * Guarantees:
+ *   - a batch is ONE `dispatchBatch(items)` call → **atomic** (all-or-nothing).
+ *   - on dispatch failure, **every** enqueued promise in that batch rejects
+ *     with the same error.
+ *   - items dispatch in enqueue order (optionally reordered by `compare` just
+ *     before a batch is cut); batches run FIFO under a `maxInFlight` cap.
+ *
+ * The slides-sdk wraps this to coalesce `commits.create` calls; the stateful
+ * `TransactionQueue` MAY adopt it later (it would supply `compare` for FK
+ * ordering and keep its merge/confirm/retry logic in its own hooks).
+ */
+export interface BatchSchedulerOptions<T> {
+    /** Master switch. When false, every `enqueue` dispatches solo immediately. Default true. */
+    readonly enabled?: boolean;
+    /** Coalescing window in ms. `0` (default) → flush on the next microtask (zero added latency). */
+    readonly windowMs?: number;
+    /** Max items per batch before a forced flush. Default 256. */
+    readonly maxBatchSize?: number;
+    /** Max accumulated `costOf` per batch before a forced flush. Default `Infinity` (disabled). */
+    readonly maxBatchCost?: number;
+    /** Per-item cost used by `maxBatchCost` (e.g. serialized bytes). Default `() => 0`. */
+    readonly costOf?: (item: T) => number;
+    /** Max dispatches in flight at once (backpressure). Default 1 → strictly ordered. */
+    readonly maxInFlight?: number;
+}
+export interface BatchSchedulerHooks<T, R> {
+    /** The single dispatch for one batch. One call → atomic at this layer. */
+    dispatchBatch(items: T[]): Promise<R>;
+    /**
+     * Optional ordering applied to the staged items immediately before a batch
+     * is cut (e.g. FK-priority). Omit for FIFO. Does not affect which items share
+     * a batch — only their order within the dispatched array.
+     */
+    compare?(a: T, b: T): number;
+}
+export interface BatchScheduler<T, R> {
+    /** Stage one item; resolves with its batch's dispatch result, or rejects with the batch error. */
+    enqueue(item: T): Promise<R>;
+    /** Stage an item that must dispatch in its OWN batch (e.g. it carries an explicit idempotency key). */
+    enqueueSolo(item: T): Promise<R>;
+    /** Force-flush the pending batch and resolve once everything in flight has settled. */
+    flush(): Promise<void>;
+    /** Stop scheduling and clear timers. Pending/in-flight promises still settle. */
+    dispose(): void;
+}
+export declare function createBatchScheduler<T, R>(hooks: BatchSchedulerHooks<T, R>, options?: BatchSchedulerOptions<T>): BatchScheduler<T, R>;

package/dist/batching/index.js

@@ -0,0 +1,150 @@
+/**
+ * `@abloatai/ablo/batching` — a dependency-free batch-coalescing primitive.
+ *
+ * Accumulate items issued close together (the canonical case: a synchronous
+ * burst, e.g. `Promise.all([ a(), b(), c() ])` in one event-loop tick) and
+ * dispatch them as ONE atomic batch instead of one call each. This is the
+ * scheduling essence of Ablo's `TransactionQueue` (and Linear's sync engine) —
+ * microtask same-tick staging, size/cost/delay flush triggers, and in-flight
+ * backpressure — distilled to a pure state machine with NO dependency on
+ * models, MobX, IndexedDB, or the wire. Consumers inject the actual dispatch.
+ *
+ * Guarantees:
+ *   - a batch is ONE `dispatchBatch(items)` call → **atomic** (all-or-nothing).
+ *   - on dispatch failure, **every** enqueued promise in that batch rejects
+ *     with the same error.
+ *   - items dispatch in enqueue order (optionally reordered by `compare` just
+ *     before a batch is cut); batches run FIFO under a `maxInFlight` cap.
+ *
+ * The slides-sdk wraps this to coalesce `commits.create` calls; the stateful
+ * `TransactionQueue` MAY adopt it later (it would supply `compare` for FK
+ * ordering and keep its merge/confirm/retry logic in its own hooks).
+ */
+export function createBatchScheduler(hooks, options) {
+    const enabled = options?.enabled ?? true;
+    const windowMs = options?.windowMs ?? 0;
+    const maxBatchSize = options?.maxBatchSize ?? 256;
+    const maxBatchCost = options?.maxBatchCost ?? Infinity;
+    const costOf = options?.costOf ?? (() => 0);
+    const maxInFlight = options?.maxInFlight ?? 1;
+    let pending = null;
+    let timer = null;
+    let microtaskScheduled = false;
+    const ready = [];
+    let inFlight = 0;
+    let idleWaiters = [];
+    let disposed = false;
+    function scheduleFlush() {
+        if (microtaskScheduled || timer)
+            return;
+        if (windowMs > 0) {
+            timer = setTimeout(() => {
+                timer = null;
+                flushPending();
+            }, windowMs);
+        }
+        else {
+            microtaskScheduled = true;
+            queueMicrotask(() => {
+                microtaskScheduled = false;
+                flushPending();
+            });
+        }
+    }
+    function flushPending() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        microtaskScheduled = false;
+        if (!pending)
+            return;
+        if (hooks.compare)
+            pending.items.sort(hooks.compare);
+        ready.push(pending);
+        pending = null;
+        pump();
+    }
+    function pump() {
+        while (inFlight < maxInFlight && ready.length > 0) {
+            const batch = ready.shift();
+            if (!batch)
+                break;
+            inFlight++;
+            let dispatched;
+            try {
+                dispatched = hooks.dispatchBatch(batch.items);
+            }
+            catch (error) {
+                dispatched = Promise.reject(error);
+            }
+            dispatched
+                .then((result) => {
+                for (const d of batch.deferreds)
+                    d.resolve(result);
+            }, (error) => {
+                for (const d of batch.deferreds)
+                    d.reject(error);
+            })
+                .finally(() => {
+                inFlight--;
+                pump();
+                notifyIdleIfDrained();
+            });
+        }
+    }
+    function notifyIdleIfDrained() {
+        if (inFlight === 0 && ready.length === 0 && idleWaiters.length > 0) {
+            const waiters = idleWaiters;
+            idleWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+    }
+    function enqueueSolo(item) {
+        return new Promise((resolve, reject) => {
+            ready.push({ items: [item], deferreds: [{ resolve, reject }], cost: costOf(item) });
+            pump();
+        });
+    }
+    function enqueue(item) {
+        if (disposed)
+            return Promise.reject(new Error('batch scheduler disposed'));
+        if (!enabled)
+            return enqueueSolo(item);
+        const cost = costOf(item);
+        return new Promise((resolve, reject) => {
+            const deferred = { resolve, reject };
+            // Rollover: if appending would blow a cap, flush the current batch first.
+            if (pending && (pending.items.length + 1 > maxBatchSize || pending.cost + cost > maxBatchCost)) {
+                flushPending();
+            }
+            if (!pending)
+                pending = { items: [], deferreds: [], cost: 0 };
+            pending.items.push(item);
+            pending.deferreds.push(deferred);
+            pending.cost += cost;
+            if (pending.items.length >= maxBatchSize || pending.cost >= maxBatchCost) {
+                flushPending();
+            }
+            else {
+                scheduleFlush();
+            }
+        });
+    }
+    async function flush() {
+        flushPending();
+        while (ready.length > 0 || inFlight > 0) {
+            await new Promise((resolve) => idleWaiters.push(resolve));
+        }
+    }
+    function dispose() {
+        disposed = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        microtaskScheduled = false;
+    }
+    return { enqueue, enqueueSolo, flush, dispose };
+}

package/dist/cli.cjs

@@ -276903,9 +276903,18 @@ var ERROR_CODES = {
   // ── quota / rate limit (429) ──────────────────────────────────────
   quota_exceeded: wire("rate_limit", 429, true, "The organization exceeded its configured usage quota."),
   connection_limit_exceeded: wire("rate_limit", 429, true, "Too many concurrent WebSocket connections for this principal or organization. Close idle connections, or retry once others drain."),
+  // Per-CREDENTIAL request-rate limit — the fast (RPS/burst) axis, distinct from
+  // the slow-axis `quota_exceeded` (org daily/monthly usage). Keyed per API key,
+  // so one noisy key backs off without affecting the rest of the org. The
+  // `Retry-After` header carries the bucket-refill delay.
+  rate_limit_exceeded: wire("rate_limit", 429, true, "This API key is sending requests too quickly; slow down and retry after the indicated delay."),
   // ── server (5xx) ───────────────────────────────────────────────────
   internal_error: wire("server", 500, true, "An unexpected server error occurred."),
   quota_lookup_failed: wire("server", 503, true, "The quota decision could not be loaded."),
+  // The per-key rate-limiter backend (Redis) was unreachable and the API is
+  // configured to FAIL CLOSED on that path, so the request was rejected rather
+  // than admitted unchecked. Retryable: the next attempt re-probes the backend.
+  rate_limiter_unavailable: wire("server", 503, true, "The rate-limiter backend is unavailable and this endpoint is configured to fail closed; retry shortly."),
   turn_open_failed: wire("server", 500, true, "The agent turn failed to open."),
   turn_close_failed: wire("server", 500, true, "The agent turn failed to close cleanly."),
   // ── client-only invariants (never serialized) ──────────────────────
@@ -277058,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';
@@ -28,7 +29,7 @@ import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import type { SyncGroupInput } from '../schema/roles.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { ClaimStream, ClaimWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
-import type { ClaimHandle, Duration, Claim } from '../types/streams.js';
+import type { ClaimHandle, Duration } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
 /**
@@ -371,7 +372,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  *   `claim({ id })` — durable claim handle for coordinated writes
  */
 export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
-import type { ModelOperations, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ServerReadOptions } from './createModelProxy.js';
+import type { ModelOperations, ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, ServerReadOptions } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelRead<T = Record<string, unknown>> {
@@ -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;
 }
@@ -473,30 +492,21 @@ export interface ModelMutationOptions extends ClaimedOptions {
  * The HTTP/stateless claim surface. Normal tools usually put `claim` directly
  * on the write (`update({ id, data, claim })`) and let the SDK release it. Use
  * this namespace for multi-step handles and coordination screens.
+ *
+ * Same surface as the reactive {@link ClaimApi}, but every read is a server
+ * round-trip, so `state`/`queue`/`reorder` are **awaited** here (the WebSocket
+ * client resolves them synchronously from its local pool — which is what lets
+ * `useAblo((ablo) => ablo.x.claim.state({ id }))` work inside a React render; a
+ * stateless client has no pool to read, so the `Promise` is unavoidable).
+ *
+ * Mechanically DERIVED from `ClaimReadApi` via {@link AwaitedClaimMethod} so the
+ * two transports can never drift: the ONLY difference is the uniform `Promise`
+ * wrapper that statelessness forces. `claim({ id })` is identical (already async
+ * on both); `state`/`queue`/`reorder`/`release` are the awaited form.
  */
-export interface HttpClaimApi<T> {
-    /** Take a manual claim handle for multi-step work. Release it when done. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
-    /** Release a manual claim you hold. */
-    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
-    /**
-     * Current holder of the lease on a row, or `null` when free. For UI badges,
-     * preflight checks, and operators.
-     */
-    state(params: ClaimLookupParams<T>): Promise<Claim | null>;
-    /**
-     * FIFO wait line behind the holder. Advanced: useful for operator UIs and
-     * schedulers.
-     */
-    queue(params: ClaimLookupParams<T>): Promise<{
-        readonly object: 'list';
-        readonly data: readonly Claim[];
-    }>;
-    /**
-     * Re-rank the wait line. Advanced and permission-gated.
-     */
-    reorder(params: ClaimReorderParams<T>): Promise<void>;
-}
+export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<ClaimHandle<T>>) & {
+    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
+};
 export interface ModelClient<T = Record<string, unknown>> {
     /**
      * Single-row read over HTTP. **Returns an envelope, not the bare row** — the
@@ -552,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
@@ -1325,7 +1325,7 @@ export function Ablo(options) {
             }),
             queue: (target) => publicClaims.queueFor({ type: target.model, id: target.id }),
             reorder: (target, order) => publicClaims.reorder({ type: target.model, id: target.id }, order),
-            observe: (target) => {
+            state: (target) => {
                 // The live claim stream only tracks *open* (active) claims;
                 // terminal states (committed / expired / canceled) drop out of
                 // the list entirely — exactly the ephemeral coordination model.
@@ -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) {