@abloatai/ablo 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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/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) ──────────────────────

package/dist/client/Ablo.d.ts

@@ -28,7 +28,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 +371,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>> {
@@ -473,30 +473,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

package/dist/client/Ablo.js

@@ -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.

package/dist/client/auth.js

@@ -54,6 +54,14 @@ export function resolveDatabaseUrl(input) {
  * explicit option instead of flipping their mode for them. Warns once per process
  * so it never spams, and falls back to `console.warn` when no logger is supplied
  * (the `transport: 'api'` client has none).
+ *
+ * Suppressed entirely on the hosted/token path: if an `apiKey` resolves (option
+ * or `ABLO_API_KEY` env), the caller has chosen the hosted capability-token /
+ * Data Source transport, which is mutually exclusive with direct `databaseUrl`
+ * mode. A `DATABASE_URL` sitting in that environment is unrelated infra (Prisma,
+ * Drizzle, the sync-server) — never an omitted option — so nudging would be a
+ * false positive. This is the first-party hosted app's exact shape, where the
+ * stray nudge otherwise reaches end-user desktop logs.
  */
 let warnedDatabaseUrlEnvIgnored = false;
 export function warnIfDatabaseUrlEnvIgnored(input, warn) {
@@ -61,6 +69,9 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
         return;
     if (input.options.databaseUrl != null)
         return;
+    // Hosted/token path → DATABASE_URL is unrelated infra, not an omitted option.
+    if (resolveApiKey(input) != null)
+        return;
     const envUrl = input.env.DATABASE_URL;
     if (typeof envUrl !== 'string' || envUrl.length === 0)
         return;

package/dist/client/createModelProxy.d.ts

@@ -109,8 +109,13 @@ export interface ModelCollaboration<T> {
      * `null` when the target is free. The wiring site computes it because
      * only it knows the local participant id (needed to distinguish "I
      * hold it" from "someone else holds it").
+     *
+     * Named `state` to match the public `ablo.<model>.claim.state({ id })` read —
+     * one verb for "who holds this" across every claim surface; the only
+     * difference is this internal contract takes an explicit `{ model, id }`
+     * target because it isn't bound to a single model.
      */
-    observe(target: {
+    state(target: {
         model: string;
         id: string;
     }): Claim | null;
@@ -202,10 +207,11 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
      * work-distribution dedup ("if someone else has this job, skip it") where
      * waiting would mean double-processing.
      *
-     * Named `queue` to match every other claim surface (low-level
-     * `claims.claim`, HTTP `claim.create`, and the wire). The high-level typed
-     * claim defaults it ON because it serializes writers; the low-level lease
-     * and HTTP default it OFF — they return/resolve immediately and can't
+     * Named `queue` to match every other claim surface — `ablo.<model>.claim`
+     * on both the WS and HTTP clients (take-a-claim is the callable `claim({ id
+     * })` on both; the HTTP reads are just awaited) and the wire. The high-level
+     * typed claim defaults it ON because it serializes writers; the low-level
+     * lease and HTTP default it OFF — they return/resolve immediately and can't
      * transparently wait for a grant.
      */
     queue?: boolean;
@@ -276,9 +282,18 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  * handle. `state`, `queue`, and `reorder` are coordination reads/scheduler
  * controls for UI and operators.
  */
-export interface ClaimApi<T> {
-    /** Take a claim and get an explicit held-work handle back. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+/**
+ * Coordination reads + scheduler controls on a claim namespace, in their
+ * REACTIVE (synchronous) form — `state`/`queue`/`reorder` resolve against the
+ * local pool with no round-trip, which is what lets `useAblo((ablo) =>
+ * ablo.x.claim.state({ id }))` read coordination state inside a React render.
+ *
+ * This is the single source of truth for the claim read surface: the stateless
+ * HTTP client exposes the *awaited* projection of EXACTLY these methods
+ * (`HttpClaimApi` in `Ablo.ts`, derived via {@link AwaitedClaimMethod}), so the
+ * two transports can never drift — edit a signature here and HTTP follows.
+ */
+export interface ClaimReadApi<T = Record<string, unknown>> {
     /**
      * Current holder for a row, or `null` when free. Use this for UI badges and
      * preflight checks, not for the normal write path.
@@ -299,6 +314,16 @@ export interface ClaimApi<T> {
     /** Release a manual claim handle early. Single-write claims auto-release. */
     release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
 }
+/**
+ * The awaited form of a claim method: a synchronous return becomes a `Promise`,
+ * an already-async one (`release`) is left untouched. Used to derive the
+ * stateless HTTP claim surface from the reactive {@link ClaimReadApi}.
+ */
+export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
+export interface ClaimApi<T> extends ClaimReadApi<T> {
+    /** Take a claim and get an explicit held-work handle back. */
+    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+}
 export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
 }

package/dist/client/createModelProxy.js

@@ -141,7 +141,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // Is someone ELSE already on this target? Read the local coordination
         // snapshot up front — it decides whether we'll need to re-read after the
         // claim (a free / already-mine target can't have changed under us).
-        const held = collaboration.observe({ model: wireModel, id });
+        const held = collaboration.state({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
         const failFast = options?.queue === false;
         // Fail-fast (`queue: false`): if another participant already holds it,
@@ -215,7 +215,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         const reason = options?.reason ?? 'editing';
         // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
-        // report (`observe` maps `held.target.model` → `type`), so a holder and a
+        // report (`state` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
         const selfTarget = {
             type: wireModel,
@@ -271,7 +271,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             // presence. Soft + fire-and-forget — never blocks or rejects the read.
             void collaboration?.enterScope?.({ [schemaKey]: params.id });
             // Self-awareness: the server excludes a holder's OWN presence frames and
-            // the client skips them, so `observe` returns null for a row WE hold.
+            // the client skips them, so `state` returns null for a row WE hold.
             // Synthesize the active claim for self from the stored lease so the
             // holder sees its own claim (the JSDoc contract on `claim.state`).
             const own = activeClaims.get(params.id);
@@ -287,7 +287,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     expiresAt: own.expiresAt,
                 };
             }
-            return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
+            return collaboration?.state({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
             return {

package/dist/errorCodes.d.ts

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-06-13";
+export declare const ERROR_CONTRACT_VERSION = "2026-06-20";
 /** Coarse grouping for metrics dashboards and docs sectioning. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'claim' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
@@ -239,8 +239,10 @@ export declare const ERROR_CODES: {
     readonly ws_not_ready: ErrorCodeSpec;
     readonly quota_exceeded: ErrorCodeSpec;
     readonly connection_limit_exceeded: ErrorCodeSpec;
+    readonly rate_limit_exceeded: ErrorCodeSpec;
     readonly internal_error: ErrorCodeSpec;
     readonly quota_lookup_failed: ErrorCodeSpec;
+    readonly rate_limiter_unavailable: ErrorCodeSpec;
     readonly turn_open_failed: ErrorCodeSpec;
     readonly turn_close_failed: ErrorCodeSpec;
     readonly invalid_options: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export const ERROR_CONTRACT_VERSION = '2026-06-13';
+export const ERROR_CONTRACT_VERSION = '2026-06-20';
 /**
  * The closed taxonomy of *how a failure recovers* — one rung above the raw
  * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
@@ -258,9 +258,18 @@ export const 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) ──────────────────────

package/docs/api.md

@@ -124,10 +124,11 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
 | `id` | string | Unique identifier for the claim. |
 | `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
 | `target` | `{ type, id, field? }` | What is being coordinated. |
-| `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `reason` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. Serialized on the wire as `action`. |
 | `heldBy` | string | Participant id holding the claim. |
 | `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
-| `expiresAt` | string | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
+| `createdAt` | number? | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
+| `expiresAt` | number | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
 
 ```json
 {
@@ -135,10 +136,10 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
   "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
   "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
-  "action": "editing",
+  "reason": "editing",
   "heldBy": "agent:report-writer",
   "participantKind": "agent",
-  "expiresAt": "1716580000000"
+  "expiresAt": 1716580000000
 }
 ```
 
@@ -175,7 +176,7 @@ Reads never block on a claim — to wait for a row to free up, `claim({ id })` i
 const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (claim) {
   claim.heldBy;
-  claim.action;
+  claim.reason;
 }
 
 const handle = await ablo.weatherReports.claim({

package/docs/coordination.md

@@ -72,23 +72,23 @@ a model row. It's what `claim.state()` returns and what observers render.
 | `id` | `string` | The claim id (distinct from the target row id). |
 | `status` | `ClaimStatus` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'`. `active` = the holder; `queued` = waiting in line behind it. The other three are terminal states you only see on a claim you just finished — `committed` (released after a successful write), `expired` (TTL lapsed), `canceled` (released early). |
 | `target` | `EntityRef` | What is being coordinated (`{ model, id, field? }`). |
-| `action` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `reason` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. Serialized on the wire as `action`. |
 | `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
 | `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
 | `position` | `number?` | 0-based place in the FIFO line — present only when `status: 'queued'` (`0` = next behind the holder). |
-| `createdAt` | `string?` | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
-| `expiresAt` | `string` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
+| `createdAt` | `number?` | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
+| `expiresAt` | `number` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
 
 ```jsonc
 {
   "id": "claim_8fJ2",
   "status": "active",
   "target": { "model": "weatherReports", "id": "report_stockholm" },
-  "action": "editing",
+  "reason": "editing",
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
-  "createdAt": "1748160000000",
-  "expiresAt": "1748160030000"
+  "createdAt": 1748160000000,
+  "expiresAt": 1748160030000
 }
 ```
 
@@ -129,9 +129,9 @@ so two claimers can't both think they won.
 | name | type | required | description |
 |---|---|---|---|
 | `id` | `string` | yes | The row id — same id as `retrieve` / `update`. |
-| `options.action` | `string` | no | Phase shown to observers (default `'editing'`). |
+| `options.reason` | `string` | no | Phase shown to observers (default `'editing'`). Serialized on the wire as `action`. |
 | `options.field` | `string` | no | Field-level target, for fine-grained claimed-state badges. |
-| `options.wait` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
+| `options.queue` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
 | `options.maxQueueDepth` | `number` | no | Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of joining a line already `>= maxQueueDepth` deep. Omit to wait however deep the queue is. |
 | `options.ttl` | `Duration` | no | Crash-cleanup floor. Rarely set — the lease renews while your connection is alive, so it only matters once you go silent. |
 
@@ -209,7 +209,7 @@ is free.
 
 ```ts
 const who = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
-if (who) console.log(`${who.heldBy} is ${who.action}`);
+if (who) console.log(`${who.heldBy} is ${who.reason}`);
 ```
 
 Returns the active claim state when the row is held, or `null` when it's free:
@@ -219,10 +219,10 @@ Returns the active claim state when the row is held, or `null` when it's free:
   "id": "claim_8fJ2",
   "status": "active",
   "target": { "model": "weatherReports", "id": "report_stockholm" },
-  "action": "editing",
+  "reason": "editing",
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
-  "expiresAt": "1748160030000"
+  "expiresAt": 1748160030000
 }
 ```
 

package/docs/react.md

@@ -224,6 +224,75 @@ function wired into the provider (bound to your transport). If no `beginClaim`
 is wired, the returned invoker throws `AbloValidationError` with code
 `claim_not_wired`.
 
+## useWatch — scoped presence + read interest
+
+`useWatch` is the React form of `ablo.<model>.watch`. It joins multiplayer for a
+scope on the engine's existing socket (one TCP connection, N logical
+sub-syncgroup participants) and returns the reactive participant facade. Use it
+when a mount should both *see* who else is on an entity and, optionally, declare
+write interest in it.
+
+```tsx
+'use client';
+
+import { useWatch } from '@abloatai/ablo/react';
+
+export function DeckPresence({ deckId }: { deckId: string }) {
+  const { peers, claims, status } = useWatch({
+    scope: { slideDecks: deckId },
+    claim: true,   // I intend to write — pin the scope + let peers observe the claim
+    hydrate: true, // backfill the deck's current rows if not already loaded
+  });
+
+  if (status !== 'joined') return <span>connecting…</span>;
+  return <span>{peers.length} other{peers.length === 1 ? '' : 's'} here</span>;
+}
+```
+
+Options (`UseWatchOptions`):
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `scope` | — | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
+| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant — leave `false` for read-only. |
+| `hydrate` | `false` | Backfill the scope's current rows into the pool once on enter, then keep them fresh via the live tail. Set `true` for deep-linked / never-opened entities. Single-flight; soft-fails. |
+| `ttlSeconds` | — | Lease TTL for the scope claim. |
+| `paused` | `false` | Tear down and don't re-join while true. |
+
+Returns (`UseWatchReturn`): `{ participant, peers, claims, status, error }`.
+`peers` is everyone else on the scope's sync groups; `claims` is their active
+write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
+`paused` flips true.
+
+## usePeers — read-only presence
+
+`usePeers` is a *pure reader* of the presence stream already flowing on the
+connection. Unlike `useWatch`, it does **not** enter/leave a scope (no
+`update_subscription`, no warm-TTL churn) — so reading it never changes what the
+connection is subscribed to.
+
+```tsx
+'use client';
+
+import { usePeers } from '@abloatai/ablo/react';
+
+export function CursorBroadcaster({ deckId }: { deckId: string }) {
+  const peers = usePeers({ slideDecks: deckId });
+  const alone = !peers.some((p) => p.participantKind === 'user');
+  // suppress live-cursor broadcasts while alone
+}
+```
+
+Pass `scope` to narrow to a sync group's peers, or omit it for everyone on the
+engine's groups. Returns `ReadonlyArray<Peer>`, where each `Peer` carries
+`participantKind` (`'user' | 'agent' | 'system'`), `participantId`, optional
+`label`, `syncGroups`, `activity`, `lastActive`, and optional `activeClaims`.
+
+Reach for `usePeers` (not a second `useWatch`) when some **other** mount already
+owns the scope's read interest — scope `leave` is not reference-counted, so a
+second `useWatch` on the same scope would warm-drop the owner's subscription on
+unmount.
+
 ## Next.js
 
 The Next.js [App Router landing](/nextjs) walks through Server Components

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,6 +43,11 @@
       "import": "./dist/core/index.js",
       "default": "./dist/core/index.js"
     },
+    "./batching": {
+      "types": "./dist/batching/index.d.ts",
+      "import": "./dist/batching/index.js",
+      "default": "./dist/batching/index.js"
+    },
     "./agent": {
       "types": "./dist/agent/index.d.ts",
       "import": "./dist/agent/index.js",