@abloatai/ablo 0.7.0 → 0.9.0

package/docs/coordination.md

@@ -1,20 +1,22 @@
 # 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, …)` is optimistic
+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).
 
-Claims are **fair**: on contention a second claimer joins a **server-side FIFO
-queue** and blocks until promoted to the head of the line — it does not fail and
-does not poll. Reads are open by default; reading a claimed row is allowed unless
-the caller explicitly asks for claimed gating. A claim carries a TTL so a crashed
-holder is auto-released and the queue advances.
+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
+of clobbering. The wait is a **server-side FIFO queue**: a second claimer blocks
+until promoted to the head of the line — it does not fail and does not poll.
+Reads stay open: reading a claimed row is allowed unless the caller explicitly
+asks for claimed gating. A claim carries a TTL so a crashed holder is
+auto-released and the queue advances.
 
 This reference opens with [the model](#the-model--three-layers-one-decision) — the
 one answer to "how do two agents not clobber each other" — then covers the
 [claim state object](#the-claim-state-object), the SDK [methods](#methods)
-(`claim` · `claimState` · `queue` · `release` · [writing under a
+(`claim` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
 claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
 ---
@@ -27,8 +29,8 @@ make:
 
 | layer | kind | what it does | enforces? |
 |---|---|---|---|
-| **Presence** (`claimState`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." | **No.** Advisory only — it never blocks or rejects a write. |
-| **Claim** (`claim`/`queue`/`release`) | pessimistic | Reserves a row for one participant. Foreign writers are rejected server-side; contenders join a fair FIFO queue. | **Yes**, between participants — mutual exclusion. |
+| **Presence** (`claim.state`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." | **No.** Advisory only — it never blocks or rejects a write. |
+| **Claim** (`claim`/`claim.queue`/`claim.release`) | pessimistic | Reserves a row for one participant. Foreign writers are rejected server-side; contenders join a fair FIFO queue. | **Yes**, between participants — mutual exclusion. |
 | **Stale-context** (`readAt` + `onStale`) | optimistic (LWW) | On commit, rejects a write whose snapshot is older than the row's latest delta. Last-writer-wins detection. | **Yes**, against time — lost-update detection. |
 
 **The one decision: do you hold the row across a slow gap (read → LLM call →
@@ -42,42 +44,29 @@ write)?**
   excludes other participants for the duration, queues contenders fairly, and —
   see below — your own writes under it stay stale-guarded too.
 
-**How they compose (what wins):**
-
-1. **Claim supersedes stale-context for *foreign* writers.** A non-holder writing
-   to a claimed row is rejected by the claim guard (`AbloClaimedError`,
-   `claim_conflict`/`entity_claimed`) *before* any watermark check — `readAt` is
-   irrelevant when you don't hold the lease. Pessimistic exclusion is the outer
-   gate.
-2. **Stale-context is the always-on backstop for *unclaimed* writes.** No claim
-   held → the watermark check is the only protection, and it's automatic. This is
-   why the no-claim path is safe by default.
-3. **Inside a claim, both apply.** A claim is not a license to clobber yourself:
-   writes under a held claim carry the claim's snapshot as `readAt` with
-   `onStale: 'reject'` (see [Writing under a claim](#writing-under-a-claim)), so a
-   `bypass` write or a row that moved between snapshot and write still rejects.
-   Claim = "no one else"; stale-context = "and not against a moved snapshot."
-4. **Presence never decides.** It is the visualization of (1)–(3), not a fourth
-   gate. Never branch enforcement logic on `claimState` — read it to render, act
-   on the errors above.
-
-Claims and stale-context are **orthogonal by construction**, not wired into each
-other on the server: the claim guard runs pre-transaction; the watermark check
-runs inside it. The SDK attaches `readAt`/`onStale` for you when writing under a
-claim — that coupling lives in the SDK, deliberately, so the server's two checks
-stay independent and individually testable.
+**How they compose (what wins):** If you don't hold the row, claims win — a
+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
+anything extra.
 
 ---
 
 ## The claim state object
 
 The claim state object is the live record that a participant is coordinating work on
-a model row. It's what `claimState()` returns and what observers render.
+a model row. It's what `claim.state()` returns and what observers render.
 
 | field | type | description |
 |---|---|---|
 | `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. |
+| `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'`. |
 | `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
@@ -109,8 +98,7 @@ parameters · returns · example**.
 ### `claim`
 
 ```ts
-ablo.<model>.claim(id, work, options?): Promise<R>   // callback form
-ablo.<model>.claim(id, options?): Promise<ClaimedRow<T>>
+ablo.<model>.claim({ id, ...options }): Promise<ClaimHandle<T>>  // handle; AsyncDisposable, auto-releases with `await using`
 ```
 
 Claim a row so other writers serialize behind you until you're done; reads stay
@@ -118,8 +106,8 @@ open by default. The claim acquires through the server's fair FIFO queue: if the
 target is free the lease is yours immediately, and if another participant holds
 it your claim **waits in line** and resolves only once it reaches the head —
 then re-reads so the claimed snapshot reflects what the previous holder
-committed. There's no client-side poll and no TOCTOU gap: the server orders
-contenders.
+committed. There's no polling and no race window — the server decides the order,
+so two claimers can't both think they won.
 
 **Parameters**
 
@@ -131,38 +119,36 @@ contenders.
 | `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.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. |
-| `work` | `(row) => …` | no | Callback form: hold the claim for the callback, release when it returns. |
 
 The high-level `claim` queues by default, so on contention you either get the row
 when your turn arrives or one of the [queue errors](#errors) (`claim_lost`,
 `grant_timeout`).
 
-**Returns** — with the callback form, returns whatever `work` returns and
-releases after the callback returns or throws. The manual form returns the
-claimed row (`ClaimedRow<T> = T & AsyncDisposable`): the row data plus a
-release hook for manual scopes.
+**Returns** — a `ClaimHandle<T>` (an `AsyncDisposable`): `handle.data` is the
+fresh row snapshot taken once the lease is yours, and `handle.release()` gives
+the claim back. Bind it with `await using` so the claim auto-releases when the
+scope exits.
 
 **Example**
 
 ```ts
-const forecast = await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  const weather = await weatherAgent.getWeather(report.location);
-  await ablo.weatherReports.update(report.id, { forecast: weather });
-  return weather;
-});
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const report = claim.data;
+const weather = await weatherAgent.getWeather(report.location);
+await ablo.weatherReports.update({ id: report.id, data: { forecast: weather } });
 ```
 
-The manual scoped form is still available for wider TS 5.2+ scopes, but ordinary
-held work should use the callback form above.
+The claim releases when the `await using` scope exits — on return or throw.
 
 ### Claim-gated reads
 
-`claimState(id)` always returns immediately. Model reads such as
-`ablo.<model>.retrieve(id)` are local reads and stay available while a claim is
+`claim.state({ id })` always returns immediately. Model reads such as
+`ablo.<model>.get(id)` are local reads and stay available while a claim is
 held. Server/model reads can choose a claimed policy:
 
 ```ts
-await ablo.model('weatherReports').retrieve('report_stockholm', {
+await ablo.weatherReports.retrieve({
+  id: 'report_stockholm',
   ifClaimed: 'wait',
   claimedTimeout: 30_000,
 });
@@ -172,10 +158,10 @@ await ablo.model('weatherReports').retrieve('report_stockholm', {
 - `ifClaimed: 'wait'` waits for the active claim to clear before reading.
 - `ifClaimed: 'fail'` throws `AbloClaimedError` if the row is claimed.
 
-### `claimState`
+### `claim.state`
 
 ```ts
-ablo.<model>.claimState(id)
+ablo.<model>.claim.state({ id })
 ```
 
 Read who's currently working on a row, for observers and UI. Synchronous and
@@ -193,7 +179,7 @@ is free.
 **Example**
 
 ```ts
-const who = ablo.weatherReports.claimState('report_stockholm');
+const who = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (who) console.log(`${who.heldBy} is ${who.action}`);
 ```
 
@@ -211,17 +197,17 @@ Returns the active claim state when the row is held, or `null` when it's free:
 }
 ```
 
-### `queue`
+### `claim.queue`
 
 ```ts
-ablo.<model>.queue(id)
+ablo.<model>.claim.queue({ id })
 ```
 
 Read the **wait line** behind a row — the FIFO of claims queued behind the
-current holder, in promotion order. Like `claimState`, it's synchronous and
+current holder, in promotion order. Like `claim.state`, it's synchronous and
 reactive (it reads the local coordination snapshot, kept current by the server's
-queue-mutation frames), and reading never blocks. Where `claimState` answers "who
-holds it," `queue` answers "who's lined up next" — render "3rd in line", or
+queue-mutation frames), and reading never blocks. Where `claim.state` answers "who
+holds it," `claim.queue` answers "who's lined up next" — render "3rd in line", or
 decide the wait isn't worth it.
 
 **Parameters**
@@ -237,19 +223,19 @@ the active holder; `[]` when no one is waiting.
 **Example**
 
 ```ts
-const { data: waiting } = ablo.weatherReports.queue('report_stockholm');
+const { data: waiting } = ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 console.log(`${waiting.length} ahead of you`);
 console.log(waiting.map((i) => i.heldBy));
 ```
 
-### `release`
+### `claim.release`
 
 ```ts
-ablo.<model>.release(id): Promise<void>
+ablo.<model>.claim.release({ id }): Promise<void>
 ```
 
-Release a claim you hold. Usually **implicit** — the callback returning releases
-for you, and TTL cleans up a crashed holder.
+Release a claim you hold. Usually **implicit** — the `await using` scope exiting
+releases for you, and TTL cleans up a crashed holder.
 Call this only to give a manually held claim back early (claimed, then decided
 not to write).
 Releasing **promotes the head of the queue**: the next waiter receives the claim.
@@ -265,28 +251,28 @@ Releasing **promotes the head of the queue**: the next waiter receives the claim
 **Example**
 
 ```ts
-const report = await ablo.weatherReports.claim('report_stockholm', { action: 'reviewing' });
+const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', action: 'reviewing' });
+const report = claim.data;
 try {
   const ok = await reviewExternally(report);
   if (!ok) return; // abandon, no write
-  await ablo.weatherReports.update(report.id, { status: 'ready' });
+  await ablo.weatherReports.update({ id: report.id, data: { status: 'ready' } });
 } finally {
-  await ablo.weatherReports.release(report.id);
+  await ablo.weatherReports.claim.release({ id: report.id });
 }
 ```
 
 ### Writing under a claim
 
-There is no separate "write" method on a claim — use the normal flat
-`ablo.<model>.update(id, data)`. While you hold a claim on `id`, that `update` is
+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.
 
 ```ts
-await ablo.weatherReports.claim(id, async (report) => {
-  await ablo.weatherReports.update(report.id, { status: 'ready' }); // guarded by the claim
-});
+await using claim = await ablo.weatherReports.claim({ id });
+await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // guarded by the claim
 ```
 
 Claims are **enforced server-side**: if you `update`/`delete` a row that *another*
@@ -297,7 +283,7 @@ on fresh data. You never conflict with your own claim, and reads are never gated
 
 ```ts
 try {
-  await ablo.weatherReports.update(id, { status: 'ready' });
+  await ablo.weatherReports.update({ id, data: { status: 'ready' } });
 } catch (err) {
   if (err instanceof AbloClaimedError) {
     // someone else holds it — claim the row and retry from fresh state
@@ -329,10 +315,10 @@ that moved during your generation window — use it for selective regeneration
 
 ```ts
 try {
-  await ablo.weatherReports.claim('report_stockholm', async (report) => {
-    const weather = await weatherAgent.getWeather(report.location); // slow gap
-    await ablo.weatherReports.update(report.id, { forecast: weather });
-  });
+  await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+  const report = claim.data;
+  const weather = await weatherAgent.getWeather(report.location); // slow gap
+  await ablo.weatherReports.update({ id: report.id, data: { forecast: weather } });
 } catch (err) {
   if (err instanceof AbloClaimedError && err.code === 'claim_lost') {
     // Our lease lapsed mid-flight (we stalled past the TTL). Re-claim and retry.

package/docs/data-sources.md

@@ -1,19 +1,19 @@
 # Connect Your Database
 
-Every schema model has a backing store.
+By default, Ablo stores the rows for the models you define, so you don't need a
+database to get started. But if you already have your own application database
+and want it to stay the source of truth, you can attach it as a Data Source —
+then Ablo coordinates each write and calls your app to commit it, instead of
+storing the data itself.
 
-Customer apps must define an Ablo schema. The schema is the contract between
-the SDK, agents, realtime subscriptions, and the Data Source endpoint. Use
-`defineSchema`, `model`, and Zod the same way a Prisma project starts with a
-`schema.prisma`.
+That default makes Ablo the managed state store for your models, the same way
+Stripe stores `Customer` and `PaymentIntent` objects that you create through
+Stripe's API.
 
-By default, Ablo stores the rows for the models you declare. That makes Ablo the
-managed state store for those models, the same way Stripe stores `Customer`
-and `PaymentIntent` objects that you create through Stripe's API.
-
-If you already have application tables and want those tables to remain
-canonical, attach a Data Source. Then Ablo coordinates the write and calls your
-app to commit it.
+Either way, you define an Ablo schema with `defineSchema`, `model`, and Zod —
+the same way a Prisma project starts with a `schema.prisma`. Your schema
+describes your data once, and everything else (the SDK, agents, and your
+database connection) relies on that one definition.
 
 Your app can keep using its own `DATABASE_URL`. Store that value in your app or
 backend environment, not in Ablo. The integration boundary is the HTTPS
@@ -54,17 +54,20 @@ ABLO_API_KEY=sk_live_...
 The SDK call is the same in both modes:
 
 ```ts
-await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
-await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
-const report = ablo.weatherReports.retrieve('report_stockholm');
+await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
+const report = ablo.weatherReports.get('report_stockholm');
 ```
 
 Only the backing store changes.
 
 Multiplayer behavior is the same in both modes. Writes made through
 `ablo.<model>.create/update/delete` are coordinated by Ablo, then confirmed rows
-fan out to subscribers. Direct database writes outside Ablo need Data Source
-events so connected humans and agents see the change.
+fan out to subscribers. If something writes to your database without going
+through Ablo (a cron job, an admin tool), Ablo can't know about it
+automatically. To keep everyone's screen up to date, your app reports those
+outside changes back through an events feed — shown below in
+[External Writes](#external-writes).
 
 ## When To Use A Data Source
 
@@ -93,13 +96,13 @@ The shape is the same as a production webhook integration:
 2. Store `ABLO_API_KEY` in your app.
 3. Verify signed HTTP calls before opening a database transaction.
 4. Keep your database credentials in your app.
-5. Write an outbox row when data changes outside Ablo.
+5. Write an outbox row in the same transaction as every app-row change.
 
 ## Route
 
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource } from '@abloatai/ablo';
+import { dataSource, sourceEventForOperation } from '@abloatai/ablo';
 import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
@@ -114,7 +117,23 @@ export const POST = dataSource({
   async commit({ operations, clientTxId, context }) {
     const rows = await context.auth.db.transaction(async (tx) => {
       await tx.idempotency.upsert({ key: clientTxId, operations });
-      return applyOperations(tx, operations);
+      const changes = await applyOperations(tx, operations);
+      await tx.outbox.createMany({
+        data: changes.map(({ eventId, operation, entityId, data }) =>
+          sourceEventForOperation({
+            eventId,
+            operation,
+            entityId,
+            data,
+            ...(clientTxId ? { clientTxId } : {}),
+            ...(context.scope?.organizationId
+              ? { organizationId: context.scope.organizationId }
+              : {}),
+            occurredAt: Date.now(),
+          }),
+        ),
+      });
+      return changes.map(({ row }) => row);
     });
 
     return { rows };
@@ -137,11 +156,13 @@ export const POST = dataSource({
 Your app code still writes through the normal model API:
 
 ```ts
-await ablo.weatherReports.update(
-  'report_stockholm',
-  { status: 'ready' },
-  { wait: 'confirmed', readAt: snap.stamp, onStale: 'reject' },
-);
+await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  wait: 'confirmed',
+  readAt: snap.stamp,
+  onStale: 'reject',
+});
 ```
 
 ## Commit Request
@@ -185,10 +206,12 @@ Return canonical rows:
 Use explicit `deltas` only when your source already computes canonical change
 events.
 
-## External Writes
+## Outbox Events
 
-If your app changes data outside Ablo, return those changes from an `events`
-handler so connected humans and agents stay current:
+Return your outbox feed from an `events` handler so connected humans and agents
+stay current. Include SDK-origin events too. If Ablo already appended the commit
+directly, `clientTxId` lets Ablo filter the echo; if the direct append failed,
+the same outbox row repairs it on the next poll or push.
 
 ```ts
 export const POST = dataSource({
@@ -215,7 +238,6 @@ export const POST = dataSource({
 });
 ```
 
-`clientTxId` lets Ablo drop SDK echoes that already produced a realtime update.
 Events without `clientTxId` are treated as external writes.
 
 ## Production Checklist
@@ -227,14 +249,14 @@ Before using a customer-owned database in production:
 - Verify signatures before opening a database transaction.
 - Store `clientTxId` in an idempotency table before applying writes.
 - Return canonical rows after each commit.
-- Write outbox events in the same transaction as non-Ablo writes.
+- Write outbox events in the same transaction as every app-row write, including
+  Data Source `commit` writes.
 - Dedupe outbox events by event `id`.
 - Monitor last success, last error, retry count, event lag, and cursor.
 
-Do not send the customer's database URL to Ablo for this path. Direct database
-URL custody would be a separate connector product with encrypted secret storage,
-rotation, least-privilege roles, connection limits, table allowlists, and clear
-data-processing terms.
+Don't give Ablo your database URL for this integration — Ablo never connects to
+your database directly. (Direct database access would be a separate product with
+its own security model.)
 
 ## Security
 

package/docs/examples/agent-human.md

@@ -4,21 +4,30 @@ A report-writing agent that yields when a human is editing the same report.
 
 ## Scenario
 
-A product queue has reports that humans and agents both update. They must not
-collide:
+The same reports are edited by both humans and agents. They must not collide:
 
-- If the user is editing, the agent waits or yields.
-- If the agent is updating, the UI can show who is active.
-- If the report changes mid-run, the commit rejects instead of overwriting newer
-  state.
+- If a human already holds the row, the agent yields instead of fighting for it.
+- While the agent is updating, the UI can show who is active.
+- If the report changes mid-run, the commit is rejected instead of overwriting
+  the human's newer edit.
+
+A **claim** does both jobs. Claims don't lock — if another writer holds the row,
+`claim` waits for them, re-reads the fresh row, then hands it back to you on
+`claim.data`, so two writers serialize instead of clobbering. The handle is an
+`AsyncDisposable`: hold it with `await using` and it releases on scope exit. And
+once you hold a claim, any `update` you make while it's held is stale-checked for
+free: the SDK records the row version you were handed and rejects the write with
+a typed error if the row moved underneath you while the agent was busy.
 
 ## Schema-Backed Worker
 
-Use the same schema client the app uses. The worker loads the report, claims the
-row, and writes through `ablo.weatherReports.update(...)`.
+The worker uses the same schema client the app uses. It reads the report from
+the server with `retrieve({ id })`, claims the row, and writes through
+`ablo.weatherReports.update(...)` with a stale-check so a human's concurrent edit
+can't be overwritten.
 
 ```ts
-import Ablo from '@abloatai/ablo';
+import Ablo, { AbloClaimedError, AbloStaleContextError } from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
@@ -33,21 +42,53 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 export async function markReady(reportId: string) {
   await ablo.ready();
 
-  const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+  // retrieve({ id }) is an async server read — await it.
+  const report = await ablo.weatherReports.retrieve({ id: reportId });
   if (!report) return { status: 'not_found' };
 
-  const updated = await ablo.weatherReports.claim(
-    reportId,
-    async (claimed) =>
-      ablo.weatherReports.update(
-        claimed.id,
-        { status: 'ready' },
-        { wait: 'confirmed' },
-      ),
-    { wait: false, action: 'marking_ready' },
-  );
-
-  return { status: 'ready', report: updated };
+  try {
+    // wait: false → don't queue behind a current holder. If a human already
+    // holds the row, claim rejects with AbloClaimedError (caught below), so the
+    // agent yields instead of waiting. Omit it, or pass wait: true, to queue
+    // behind them. action → the label observers see while we work.
+    await using claim = await ablo.weatherReports.claim({
+      id: reportId,
+      wait: false,
+      action: 'marking_ready',
+    });
+    const claimed = claim.data;
+
+    // Inside an active claim, `update` is stale-checked automatically: the SDK
+    // attaches the claim's snapshot version as `readAt` and sets
+    // `onStale: 'reject'`. The write below is therefore equivalent to passing
+    // those options yourself:
+    //
+    //   ablo.weatherReports.update({
+    //     id: claimed.id,
+    //     data: { status: 'ready' },
+    //     wait: 'confirmed',
+    //     readAt: <claim snapshot version>,
+    //     onStale: 'reject',
+    //   });
+    //
+    // If a human saved a newer version mid-run, the row no longer matches
+    // `readAt`, so the server rejects this commit with AbloStaleContextError
+    // (caught below) instead of clobbering their edit.
+    const updated = await ablo.weatherReports.update({
+      id: claimed.id,
+      data: { status: 'ready' },
+      wait: 'confirmed',
+    });
+
+    return { status: 'ready', report: updated };
+  } catch (err) {
+    // A human already holds the row — yield this run and let them finish.
+    if (err instanceof AbloClaimedError) return { status: 'yielded' };
+    // A human saved a newer version while we held the claim. The stale-check
+    // rejected our commit, so nothing was overwritten — re-run on fresh data.
+    if (err instanceof AbloStaleContextError) return { status: 'stale' };
+    throw err;
+  }
 }
 ```
 
@@ -61,8 +102,8 @@ Keep workers on the same schema-backed client as the app.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportRow({ report: serverReport }: Props) {
-  const data = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const data = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const agentActive = active?.participantKind === 'agent';
 
   return (
@@ -76,7 +117,12 @@ export function ReportRow({ report: serverReport }: Props) {
 
 ## Why It Works
 
-- Claims are visible through `claimState(id)` and over the live stream.
-- `claim(id, work)` lets agents wait for active work instead of racing.
-- `readAt` plus `onStale: 'reject'` turns mid-flight changes into typed errors.
-- Audit rows tie each accepted write back to the run that caused it.
+- The claim is visible to everyone: the UI reads it synchronously with
+  `claim.state({ id })`, and it also arrives over the live stream.
+- `claim({ id })` makes writers take turns instead of racing — with
+  `wait: false`, the agent simply yields when a human already holds the row.
+- The `update` made while the claim is held is stale-checked automatically, so a human's
+  edit landing mid-run rejects the agent's write with a typed
+  `AbloStaleContextError` instead of overwriting it.
+- That same write carries the claim, so each accepted change is attributed to
+  the run that made it.