@abloatai/ablo 0.11.1 → 0.11.2

package/dist/sync/ConnectionManager.js

@@ -20,18 +20,29 @@
  * Designed to be embedded by `BaseSyncedStore`: one instance per store,
  * started on first successful connect, disposed on teardown.
  *
- *   CONNECTED ──► OFFLINE ──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
- *                    │              │                    │
- *                    ▼              ▼                    ▼
- *             WAITING_FOR_NETWORK  SESSION_EXPIRED    BACKOFF ──► PROBING_NETWORK
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
  *
- * Includes two fixes over the original app-side FSM:
+ * Includes three fixes over the original app-side FSM:
  *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
  *      probing immediately when the network comes back, without
  *      waiting for the backoff timer to elapse.
  *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
  *      `attempt`) when `navigator.onLine === false` at max retries,
  *      instead of hard-reloading an already-offline browser.
+ *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
+ *      STRAIGHT to `probing_network`, not the passive `offline` state.
+ *      1006 is browser-local and carries no connectivity signal, so on a
+ *      healthy machine no `online`/`offline` event ever fires — parking in
+ *      `offline` stranded recovery until the 30s watchdog, long enough for
+ *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
+ *      parks in `offline` and waits for the `online` event.
  */
 import { makeAutoObservable, runInAction } from 'mobx';
 import { getContext } from '../context.js';
@@ -142,8 +153,19 @@ export class ConnectionManager {
             case 'connected':
                 switch (event.type) {
                     case 'NETWORK_LOST':
-                    case 'WS_DISCONNECTED':
+                        // The OS reported the NIC down — park passively in `offline` and
+                        // wait for the `online` event. Probing a downed adapter is wasted
+                        // work.
                         return 'offline';
+                    case 'WS_DISCONNECTED':
+                        // The socket died (typically code 1006) but the OS network is
+                        // almost certainly fine — 1006 is generated locally when the TCP
+                        // conn vanishes and carries NO connectivity signal, so the browser
+                        // fires no online/offline event. Probe IMMEDIATELY rather than
+                        // landing in the passive `offline` dead-end (which only escaped via
+                        // the 30s watchdog, long after queued commits rolled back). The
+                        // probe fast-fails if we genuinely ARE offline → waiting_for_network.
+                        return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
                         return 'session_expired';
@@ -301,7 +323,7 @@ export class ConnectionManager {
         }
     }
     // ── Side effects per state ───────────────────────────────────────────
-    onEnterState(state, _event) {
+    onEnterState(state, event) {
         switch (state) {
             case 'connected':
                 this.clearBackoffTimer();
@@ -314,6 +336,19 @@ export class ConnectionManager {
                 this.callbacks?.onDisconnectWebSocket();
                 break;
             case 'probing_network':
+                // A socket drop (`WS_DISCONNECTED`) now lands here directly so recovery
+                // starts immediately. Tear the dead socket down FIRST — this is what
+                // sets SyncWebSocket's `isManualClose=true` and suppresses its own
+                // scheduleReconnect, keeping the FSM the single reconnect authority on
+                // the human path. The teardown runs synchronously inside the
+                // `disconnected` emit, before `SyncWebSocket.onclose` checks the flag,
+                // so the timing matches the previous `offline`-entry teardown. We gate
+                // on the drop event specifically: the other paths into `probing_network`
+                // (TAB_VISIBLE re-validation, handshake retry, backoff elapse) must NOT
+                // tear down a socket that may still be live.
+                if (event.type === 'WS_DISCONNECTED') {
+                    this.callbacks?.onDisconnectWebSocket();
+                }
                 this.runProbe();
                 break;
             case 'waiting_for_network':

package/dist/transactions/TransactionQueue.d.ts

@@ -427,17 +427,6 @@ export declare class TransactionQueue extends EventEmitter {
     private extractUpdateData;
     private buildUpdateInput;
     private extractPreviousData;
-    /**
-     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
-     * committed. Called right after {@link extractPreviousData} freezes their
-     * `.old` into the transaction, so the NEXT update to the same field sees this
-     * update's result as its baseline rather than the stale pre-session `.old`
-     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
-     * keys present in this update — untouched fields keep their baselines. Safe
-     * because the wire payload lives on `transaction.data` and rollback restores
-     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
-     */
-    private consumeModifiedFields;
     /**
      * Public API
      */

package/dist/transactions/TransactionQueue.js

@@ -780,8 +780,8 @@ export class TransactionQueue extends EventEmitter {
         // instead of THIS update's result — corrupting the stream-recorded undo
         // inverse (the second move's "before" would point all the way back). The
         // wire payload is already frozen in `transaction.data`, so dropping the
-        // consumed entries is safe. Mirrors `RecordingTransaction.consumeModifiedFields`.
-        this.consumeModifiedFields(model, updateInput);
+        // consumed entries is safe.
+        model.consumeModifiedFields(Object.keys(updateInput));
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('update', actualModelName);
         const transaction = {
@@ -1999,63 +1999,19 @@ export class TransactionQueue extends EventEmitter {
     // model ever needs to surface previous-state outside `modifiedProperties`,
     // expose a typed `getPreviousData()` accessor on Model and call that.
     extractPreviousData(model, updateInput) {
-        const prev = { id: model.id };
-        const modified = model.modifiedProperties instanceof Map ? model.modifiedProperties : null;
         // When the update's written keys are known, capture a before-image for
         // EXACTLY those keys so the recorded undo inverse can revert them and only
         // them (a full-row inverse would clobber concurrent edits to unrelated
-        // fields). Resolution order mirrors `RecordingTransaction.snapshotFields`:
-        //   1. `modifiedProperties.old` — first-old-wins pre-session baseline, set
-        //      whenever the caller mutated the field in place before committing.
-        //   2. `getOriginalSnapshot()` — the last loaded/acked row, the correct
-        //      before-image for a key written WITHOUT a prior in-place mutation
-        //      (e.g. a `precomputedChanges` write).
-        // Without (2) such a key yields an empty `previousData`, and `buildUndoOps`
-        // nulls the inverse entirely — making updates silently un-undoable where a
-        // create's `delete(id)` inverse never is. This closes that asymmetry.
-        if (updateInput) {
-            const original = model.getOriginalSnapshot();
-            for (const key of Object.keys(updateInput)) {
-                if (key === 'id')
-                    continue;
-                const mod = modified?.get(key);
-                if (mod) {
-                    prev[key] = mod.old;
-                }
-                else if (original && key in original) {
-                    prev[key] = original[key];
-                }
-            }
-            return prev;
-        }
-        if (modified && modified.size > 0) {
-            for (const [key, change] of modified) {
-                prev[key] = change.old;
-            }
-        }
-        return prev;
-    }
-    /**
-     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
-     * committed. Called right after {@link extractPreviousData} freezes their
-     * `.old` into the transaction, so the NEXT update to the same field sees this
-     * update's result as its baseline rather than the stale pre-session `.old`
-     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
-     * keys present in this update — untouched fields keep their baselines. Safe
-     * because the wire payload lives on `transaction.data` and rollback restores
-     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
-     */
-    consumeModifiedFields(model, updateInput) {
-        if (!(model.modifiedProperties instanceof Map) || model.modifiedProperties.size === 0) {
-            return;
-        }
-        for (const key of [...model.modifiedProperties.keys()]) {
-            if (key === 'id')
-                continue;
-            if (updateInput && !(key in updateInput))
-                continue;
-            model.modifiedProperties.delete(key);
-        }
+        // fields). `fallbackToLive: false` makes `Model.capturePreviousValues` OMIT
+        // any key it can't resolve from `modifiedProperties.old` / the original
+        // snapshot — `buildUndoOps` then drops an un-revertible inverse rather than
+        // inventing one. With no `updateInput` (full extract) fall back to every
+        // tracked field. `Model.capturePreviousValues` is the single before-image
+        // source shared with `RecordingTransaction.snapshotFields`.
+        const keys = updateInput
+            ? Object.keys(updateInput)
+            : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
+        return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
     }
     /**
      * Public API

package/dist/types/global.d.ts

@@ -60,6 +60,9 @@ export interface DefaultSyncShape {
  * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
  * when an expected key is absent. Exported from the package root so the module
  * augmentation merges into this declaration.
+ *
+ * The `Schema` augmentation key holds the type produced by `defineSchema`, so
+ * the same noun reads consistently here and in {@link ResolveSchema}.
  */
 export interface Register {
 }

package/dist/types/streams.d.ts

@@ -57,28 +57,6 @@ export interface AgentDelta {
     causedByTaskId?: string | null;
     createdAt: string;
 }
-/**
- * A reference to whoever's authority bounds a joined participant.
- * The spawned participant can never see or do more than this principal.
- * Enforced server-side: the spawned agent gets its own restricted
- * (`rk_`) key whose scope is a subset of the parent's.
- *
- *   • `SessionRef`     — human is joining an agent (chat assistant flow)
- *   • `AgentRef`       — agent spawning a sub-agent (attenuation chain)
- *   • omitted          — the API key on the Ablo client is the ceiling
- */
-export type Principal = SessionRef | AgentRef;
-export interface SessionRef {
-    readonly kind: 'session';
-    readonly id: string;
-    readonly userId: string;
-    readonly organizationId: string;
-}
-export interface AgentRef {
-    readonly kind: 'agent';
-    readonly id: string;
-    readonly capabilityToken: string;
-}
 /**
  * Flat snapshot view returned from `participant.snapshot(...)`.
  *

package/dist/utils/mobx-setup.js

@@ -145,6 +145,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         'propertyChanged',
         'markAsPersisted',
         'clearChanges',
+        'consumeModifiedFields',
         'updateFromData',
         'applyChanges',
     ];

package/docs/api-keys.md

@@ -12,6 +12,55 @@ The key identifies the Ablo account. Application code does not pass an organizat
 
 "Trusted" means the runtime can hold a secret: a backend or other server-side environment a browser can't read. Browser and app clients use the same `@abloatai/ablo` import but authenticate differently — they never carry a secret key.
 
+## Which credential to use
+
+There's **one field — `apiKey`** — and what you pass depends on **where the code runs**.
+Pick your row:
+
+| Where your code runs | What to pass | Example |
+|---|---|---|
+| **Server / worker / CLI** (can hold a secret) | your secret `sk_` — it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
+| **Browser — read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
+| **Browser — writing as the signed-in user** | a function that fetches a short-lived per-user token from your own backend | `Ablo({ schema, apiKey: () => fetch('/api/ablo-session').then((r) => r.text()) })` |
+
+That's the whole story: one knob, filled by audience.
+
+**Coming from Stripe? It's the same key model, same prefixes:**
+
+| Stripe | Ablo | Where it goes |
+|---|---|---|
+| publishable `pk_` (client-safe) | `pk_` | browser — read-only |
+| secret `sk_` (server, full) | `sk_` | server — full authority |
+| restricted `rk_` (granular) | `rk_` | scoped agent sessions (`sessions.create({ agent, can })`) |
+| ephemeral key (client, customer-scoped) | `ek_` | per-user browser sessions (`sessions.create({ user })`) |
+
+Mode lives in the prefix too — `sk_test_` / `sk_live_` — exactly like Stripe. The
+`apiKey` resolver fetching an `ek_` is Ablo's ephemeral-key flow: server mints, client holds.
+
+**Why a function for browser writes?** Anything you ship to a browser must be public, and a
+public `pk_` is **read-only** — it can't carry one specific user's write authority. So when
+the browser writes *as the logged-in user*, your backend (which holds the secret `sk_` and
+knows who's signed in) mints a short-lived per-user token with `sessions.create({ user })`,
+and the browser's `apiKey` function fetches it. You don't manage refresh — the SDK calls the
+function once before connecting and then keeps the token fresh (re-mint before expiry, and on
+tab-focus / network-online / device-wake). This is the Stripe ephemeral-key / Supabase
+session model. For a read-only app you don't need any of this — just the `pk_` above.
+
+Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
+code passes nothing. The secret `sk_` (and `databaseUrl`) are **server-only** — never in a
+browser bundle. There is no `getToken`, `authEndpoint`, or `as` option — `apiKey` (a string,
+or a function for the browser-write case) is the single credential knob.
+
+### Minting per-user / agent tokens (server-side, with your `sk_`)
+
+| Mint | Call | Result |
+|---|---|---|
+| Human end-user session | `await server.sessions.create({ user: { id } })` | `ek_` (full user authority) |
+| Scoped delegated agent | `await server.sessions.create({ agent: { id }, can: { Task: ['update'] } })` | `rk_` (scoped to `can`) |
+| Connect Ablo to your own Postgres | `Ablo({ schema, apiKey, databaseUrl })` (server-only) | dedicated tenant |
+
+The principal kind comes from *which* shape you pass — `{ user }` → `user`, `{ agent, can }` → `agent`.
+
 ## Server-Side API Keys
 
 Use API keys from trusted (server-side) runtimes:

package/docs/api.md

@@ -167,8 +167,9 @@ side: it takes the claim and returns a `ClaimHandle`. Claims don't lock — if s
 already holds the row, `claim` waits for them to finish, re-reads the fresh row,
 then hands it to you, so you always proceed from current state. Default reads
 return the row even while someone is mid-edit; if a server read should not
-return a row while it's claimed, pass `ifClaimed: 'wait'` to wait for the claim
-to clear, or `ifClaimed: 'fail'` to error out instead.
+return a row while it's claimed, pass `ifClaimed: 'fail'` to error out instead.
+Reads never block on a claim — to wait for a row to free up, `claim({ id })` it
+(the claim queues fairly behind the holder).
 
 ```ts
 const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });

package/docs/client-behavior.md

@@ -32,6 +32,7 @@ Common options:
 | `databaseUrl` | Optional, server-only. Registers your Postgres directly (the connection-string path). Pass it explicitly — it is **not** auto-read from the environment. Omit it for a signed Data Source endpoint or the hosted sandbox. The SDK throws if it sees this in a browser. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
+| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (`get`/`getAll`, `onChange`, `watch`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |

package/docs/coordination.md

@@ -1,9 +1,10 @@
 # Coordination Reference
 
 Coordinate long-running work on a row so humans and agents don't clobber each
-other. Most writes need none of this — `ablo.<model>.update({ id, data })` is optimistic
-and the server rejects it if the row moved. Reach for `claim` only when you'll
-**hold a row across a slow gap** (read → LLM call → write).
+other. Most writes need none of this — a plain `ablo.<model>.update({ id, data })`
+is **last-write-wins** by default. For lost-update detection, take a claim or pass
+`readAt` / `onStale` yourself. Reach for `claim` only when you'll **hold a row
+across a slow gap** (read → LLM call → write).
 
 Claims don't lock. If another writer holds the row, `claim` waits for them,
 re-reads the fresh row, then hands it to you — so two writers serialize instead
@@ -36,10 +37,12 @@ make:
 **The one decision: do you hold the row across a slow gap (read → LLM call →
 write)?**
 
-- **No** (the common case — a single quick `update`): do nothing. `ablo.<model>.update`
-  is optimistically guarded by stale-context already; it rejects with
-  `AbloStaleContextError` if the row moved under you. This is the default and
-  needs no ceremony.
+- **No** (the common case — a single quick `update`): a plain `ablo.<model>.update`
+  is **last-write-wins** — it carries no `readAt`, so the server skips the stale
+  check and the write simply lands. That's fine for most fields. If you need
+  lost-update detection on a no-claim write, pass `readAt` + `onStale: 'reject'`
+  yourself and it rejects with `AbloStaleContextError` when the row moved under
+  you.
 - **Yes** (you'll reason for seconds while holding the row): `claim` it. The claim
   excludes other participants for the duration, queues contenders fairly, and —
   see below — your own writes under it stay stale-guarded too.
@@ -48,12 +51,13 @@ write)?**
 non-holder writing to a claimed row is rejected (`AbloClaimedError`) regardless of
 `readAt`. If you do hold it, your own writes are still stale-checked — a row that
 moved between your snapshot and your write still rejects with
-`AbloStaleContextError`. With no claim held, the stale check is the only
-protection, and it's automatic, which is why the no-claim path is safe by default.
-Presence (`claim.state`) never decides anything — read it to render, act on the
-errors. The two checks are independent: one rejects writes from people who don't
-hold the claim, the other rejects writes based on a stale snapshot, and the SDK
-adds the stale-check for you when you write under a claim, so you don't pass
+`AbloStaleContextError`. With no claim held and no `readAt`, there is **no**
+stale protection — the plain write is last-write-wins; opt into lost-update
+detection by passing `readAt` + `onStale` yourself. Presence (`claim.state`)
+never decides anything — read it to render, act on the errors. The two checks are
+independent: one rejects writes from people who don't hold the claim, the other
+rejects writes based on a stale snapshot, and the SDK adds the stale-check for you
+when you write under a claim **you took on this client**, so there you don't pass
 anything extra.
 
 ---
@@ -92,6 +96,17 @@ a model row. It's what `claim.state()` returns and what observers render.
 
 ## Methods
 
+One word — "claim" — names four distinct things; keep them separate as you read:
+
+- **the lease (claim handle)** — the *object* returned by `ablo.<model>.claim({ id })`
+  (`ClaimHandle`, an `AsyncDisposable` with `.data` and `.release()`).
+- **acquiring a claim/lease** — the *verb* `ablo.<model>.claim({ id })`, the call
+  that takes the lease.
+- **`claim.state` / `claim.queue`** — the *inspection namespace* hanging off the
+  model, for reading who holds the row and who's lined up.
+- **the write's `claim` param** — `update({ id, data, claim })`, where you pass a
+  lease the proxy didn't take itself.
+
 Each method below follows one fixed shape: **signature · what it does ·
 parameters · returns · example**.
 
@@ -149,15 +164,19 @@ held. Server/model reads can choose a claimed policy:
 ```ts
 await ablo.weatherReports.retrieve({
   id: 'report_stockholm',
-  ifClaimed: 'wait',
-  claimedTimeout: 30_000,
+  ifClaimed: 'fail',
 });
 ```
 
-- `ifClaimed: 'return'` reads now and includes active work metadata.
-- `ifClaimed: 'wait'` waits for the active claim to clear before reading.
+- `ifClaimed: 'return'` (the default) reads now and includes active work metadata.
 - `ifClaimed: 'fail'` throws `AbloClaimedError` if the row is claimed.
 
+Reads never block on a claim — there is no `ifClaimed: 'wait'`. Waiting for a row
+to free up is a **claim-side** concern: take `ablo.<model>.claim({ id })` (it
+queues fairly behind the current holder and re-reads the fresh row once it's
+yours). Use `ifClaimed: 'fail'` when a read should simply refuse to proceed
+against a row someone else is mid-editing.
+
 ### `claim.state`
 
 ```ts
@@ -272,19 +291,54 @@ try {
 }
 ```
 
+### `watch` — presence for a set of rows
+
+Reading or claiming a row auto-enrolls you in its sync group, which is enough for
+`claim.state`/`claim.queue` to observe co-participants. When you want to *hold*
+presence on a known set of rows — a deck's slides, a board's cards — and react to
+who joins or leaves, use `watch`:
+
+```ts
+await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+room.peers; // who else is here, live
+```
+
+`watch(ids, { ttl? })` opens a model-scoped presence/claim subscription and returns
+a participant handle (`.peers`, the scoped claim stream, `.leave()` / `await using`
+disposal). It is the model-scoped successor to the old top-level
+`ablo.participants.join({ scope })`. **WebSocket only** — presence needs a live
+socket, so `watch` is absent on the HTTP client (`Ablo({ transport: 'http' })`) and
+throws on any non-ws construction.
+
 ### Writing under a claim
 
 There is no separate "write" method on a claim — use the normal
-`ablo.<model>.update({ id, data })`. While you hold a claim on `id`, that `update` is
-automatically stale-guarded against the snapshot the claim took (`readAt` =
-snapshot watermark, `onStale: 'reject'`) and attributed to the claim's lease, so
-it rejects with [`AbloStaleContextError`](#errors) if the row changed under you.
+`ablo.<model>.update({ id, data })`. The auto-guarding holds **only when this same
+client took the claim** via `ablo.<model>.claim({ id })` (the proxy remembers the
+lease in-process): that `update` is then stale-guarded against the snapshot the
+claim took (`readAt` = snapshot watermark, `onStale: 'reject'`) and attributed to
+the claim's lease, so it rejects with [`AbloStaleContextError`](#errors) if the
+row changed under you.
 
 ```ts
 await using claim = await ablo.weatherReports.claim({ id });
 await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // guarded by the claim
 ```
 
+A claim handle minted by **another client** (or returned over HTTP) is not known
+to this proxy, so a plain `update` won't pick it up. Pass it explicitly:
+
+```ts
+await ablo.weatherReports.update({ id, data: { status: 'ready' }, claim: handle });
+```
+
+**Self-stale on a second write.** The claim's watermark is fixed at claim time
+and is **not** re-baselined as you write. So a *second* `update` under one held
+claim is stale-checked against the snapshot the claim took — which your *first*
+write already moved past — and rejects with `AbloStaleContextError` against your
+own earlier write. Re-read (and re-claim) between writes if you need to write the
+same row more than once under one claim.
+
 Claims are **enforced server-side**: if you `update`/`delete` a row that *another*
 participant holds, the commit is rejected with [`AbloClaimedError`](#errors) (`code:
 'entity_claimed'`). To proceed, `claim` the row yourself — the claim queues

package/docs/examples/existing-python-backend.md

@@ -57,8 +57,9 @@ export const ablo = Ablo({
 ```
 
 Mount the React provider near the app root. Build the browser client first —
-with an `authEndpoint` so it mints a short-lived session token instead of
-carrying the secret key — then pass it to the provider via `client`.
+with an `apiKey` resolver (an async `() => Promise<string | null>`) that fetches
+the short-lived session token your backend minted, instead of carrying the
+secret key — then pass it to the provider via `client`.
 
 ```tsx
 // web/app/providers.tsx
@@ -68,9 +69,12 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// Browser client: no secret key — `authEndpoint` mints the session token
-// server-side (see the session route below).
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+// Browser client: no secret key — the `apiKey` resolver fetches the session
+// token your server route mints (see the session route below).
+const ablo = Ablo({
+  schema,
+  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+});
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider client={ablo}>{children}</AbloProvider>;

package/docs/examples/scoped-agent.md

@@ -81,7 +81,7 @@ import { schema } from './schema';
 
 const ablo = Ablo({
   schema,
-  getToken: async () => mintDeckAgentSession(deckId, agentId),
+  apiKey: async () => mintDeckAgentSession(deckId, agentId),
 });
 
 // The agent run is mounted on behalf of its triggering user.

package/docs/guarantees.md

@@ -82,9 +82,10 @@ Claims are live coordination signals. They are not database locks.
 already holds the row, the claim waits for them to finish, then re-reads the row
 before handing it back, so you proceed from fresh state. Reads stay open while a
 claim is held — `ablo.<model>.claim.state({ id })` returns the current claim state
-(or `null`) without ever blocking. A server read can pass `ifClaimed: 'wait'` to
-wait for the claim to clear, or `ifClaimed: 'fail'` to error out, when it should
-not return a row while someone else is mid-edit.
+(or `null`) without ever blocking. A server read can pass `ifClaimed: 'fail'` to
+error out, when it should not return a row while someone else is mid-edit. Reads
+never block on a claim — to wait for a row to free up, `claim({ id })` it (the
+claim queues fairly behind the holder).
 
 A claim does not reject or block other writers; it announces work so peers
 serialize behind it rather than racing. While you hold a claim, the matching