@abloatai/ablo 0.34.1 → 0.36.0

package/docs/coordination.md

@@ -1,12 +1,15 @@
 # Coordination Reference
 
+> Claim mechanics and the API behind them: who holds a row, who is waiting, and how the line moves.
+
 > **Governing convention:** [`concurrency-convention.md`](./concurrency-convention.md)
 > — the non-coercion principle (surface state, let the actor decide), the full
-> `onStale` taxonomy, the read-set (`reads[]`), and the boundaries. Read that for
-> the *why* and the contract; this reference is the *how* (claim mechanics + API).
+> `onStale` taxonomy, the batch premise (`reads[]`), and the boundaries. Read
+> that for the *why* and the contract; this reference is the *how* (claim
+> mechanics + API).
 
-Coordinate long-running work on a row so humans and agents don't clobber each
-other. Most writes need none of this — a plain `ablo.<model>.update({ id, data })`
+Coordinate long-running work on a row so agents — and the people watching them —
+don't clobber each other. Most writes need none of this — a plain `ablo.<model>.update({ id, data })`
 is **last-write-wins** by default.
 
 > **Read-modify-write under contention? Use the functional update — it owns all
@@ -35,21 +38,36 @@ 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.
 
-> **Transport: WebSocket queues, HTTP reconciles.** The "blocks until promoted"
-> behaviour above needs a live socket to wake the waiter, so it applies to the
-> **WebSocket client only**. On the **stateless HTTP client**
-> (`Ablo({ transport: 'http' })` — the transport server-side agents use) there is
-> nothing to park a waiter, so a contended `claim` does **not** wait: it acquires
-> immediately, or rejects right away with `AbloClaimedError('claim_queued')`
-> (`queue: true`, the default) / `AbloClaimedError('entity_claimed')`
-> (`queue: false`). And because short claim→write→release cycles rarely overlap,
-> concurrent HTTP agents usually all acquire, then collide at **write** time — the
-> first write wins and the rest get `AbloStaleContextError('stale_context')`.
-> The coordination pattern over HTTP is therefore a **reconcile loop**, not a
-> queue: catch `claim_queued` / `claim_lost` / `stale_context`, re-read fresh,
-> regenerate, retry. See [Errors](#errors) and the loop sketch there.
-
-This reference opens with [the model](#the-model--three-layers-one-decision) — the
+A claim is also as narrow as you make it. Name a part of the row — a `field`, a
+`path` into a document, a `range` of text — and exclusion follows the target:
+**two claims on non-overlapping parts of the same row are both granted**, and
+only overlapping targets queue behind each other. See
+[claiming part of a row](#claiming-part-of-a-row).
+
+> **Transport: both wait — only the mechanism differs.** `claim({ id })` means
+> "serialize me behind whoever holds this row" on every transport. The
+> realtime client parks the promise on its socket and resolves it on the grant
+> frame. The **stateless HTTP client** (`Ablo({ transport: 'http' })` — the
+> transport server-side agents use) holds the same place in the same
+> server-side FIFO line; under the hood it heartbeats its queued ticket until
+> the line moves, then re-reads the row and resolves to the same held claim.
+> The same snippet works on both.
+>
+> Shape the wait the same way on either transport: cap it with
+> `waitTimeoutMs` (rejects `grant_timeout` and leaves the line), cancel it
+> from outside with `signal` (an `AbortSignal`; rejects
+> `claim_wait_aborted`), bound the line you'll join with `maxQueueDepth`
+> (`queue_too_deep`), or skip waiting entirely with `queue: false` — the
+> try-claim, which resolves `null` when the target is held (a declined try
+> is not an error) and takes no place in line. For
+> callers that manage the wait themselves, the ticket surface remains:
+> `ablo.claims.retrieve({ claimId })` polls a ticket to its grant,
+> `ablo.claims.heartbeat({ claimId })` keeps the slot, and
+> `ablo.claims.release({ claimId })` leaves the line. And contention can be
+> treated as a signal rather than a wait at all — catch the error, re-read
+> fresh, regenerate, retry; see [Errors](#errors) for the loop sketch.
+
+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` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
@@ -80,7 +98,7 @@ claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
 ---
 
-## The model — three layers, one decision
+## The model: three layers, one decision
 
 Ablo has exactly **three** coordination layers. They are **not** three competing
 answers to the same question — they stack, and only one of them is a decision you
@@ -88,9 +106,9 @@ make:
 
 | layer | kind | what it does | enforces? |
 |---|---|---|---|
-| **Presence** (`claim.state`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." Reading or claiming a row auto-enrolls you in its sync group, so `claim.state({ id })` observes co-participants from any client (browser or Node agent) with no manual subscribe step. | **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. |
+| **Presence** (`claim.state`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." Reading or claiming a row auto-enrolls you in its sync group, so `claim.state({ id })` observes co-participants from any client (browser or Node agent) with no manual subscribe step. | **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 →
 write)?**
@@ -128,46 +146,53 @@ disposition once, in the schema, so every commit to that model is governed
 without per-call wiring. This is the third coordination axis — orthogonal to
 `policy` (who may read a row) and `groups` (which delta channels it fans into).
 
-Add a `conflict` map to `model(...)`, keyed by the **committer's** participant
-kind (`user` / `agent` / `system`), with the same `onStale` vocabulary as values:
-
-| value | meaning |
-|---|---|
-| `'overwrite'` | the write wins; that committer is never blocked. |
-| `'reject'` | the write is refused; that committer yields to a held claim / stale snapshot. |
-| `'notify'` | hold the write and hand back the current value so the committer re-reads and re-applies (stale writes only). |
+Set a model's `conflict` stance with `coordination`, naming one rule per kind of
+committer:
 
 ```ts
-import { model, field } from '@abloatai/ablo/schema';
-
-export const card = model('card', {
-  title: field.string(),
-}, {
-  // "a human's edit always wins (never blocked); an agent yields"
-  conflict: { user: 'overwrite', agent: 'reject' },
-});
+import { coordination, model, z } from '@abloatai/ablo/schema';
+
+export const cards = model(
+  {
+    title: z.string(),
+  },
+  {
+    // "a human's edit always wins (never blocked); an agent yields"
+    conflict: coordination.humansOverwrite().agentsReject(),
+  }
+);
 ```
 
-### Composable helpers
+Each rule pairs a committer with a disposition, drawn from the same `onStale`
+vocabulary the write guards use:
+
+| disposition | meaning |
+|---|---|
+| `overwrite` | the write wins; that committer is never blocked. |
+| `reject` | the write is refused; that committer yields to a held claim / stale snapshot. |
+| `notify` | hold the write and hand back the current value so the committer re-reads and re-applies (stale writes only). |
+
+That gives nine rules — `humansOverwrite` / `humansReject` / `humansNotify`,
+`agentsOverwrite` / `agentsReject` / `agentsNotify`, `systemOverwrite` /
+`systemReject` / `systemNotify` — and a chain may name as many as it needs. A
+kind left unnamed falls through to the engine default, and a kind named twice
+takes the later rule.
 
-For the same map with an authoring surface that reads like the rest of the DSL,
-use the disposition helpers and the `coordination(...)` combinator (a `cn`/`cx`
-for conflict policy — later rules win on key collisions):
+When the rules are assembled at runtime rather than written out, each one is
+also a standalone function, and `coordination()` merges them:
 
 ```ts
-import { model, field, coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
+import { coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
 
-export const card = model('card', {
-  title: field.string(),
-}, {
-  conflict: coordination(humansOverwrite(), agentsReject()),
-  // → { user: 'overwrite', agent: 'reject' }
-});
+const stance = coordination(humansOverwrite(), agentsReject());
 ```
 
-Helpers, one per disposition: `humansOverwrite` / `humansReject` / `humansNotify`,
-`agentsOverwrite` / `agentsReject` / `agentsNotify`,
-`systemOverwrite` / `systemReject` / `systemNotify`.
+Both forms produce the same thing: a map keyed by the committer's participant
+kind, which is what travels to the server.
+
+```ts
+{ user: 'overwrite', agent: 'reject' }
+```
 
 ### How it relates to per-write coordination
 
@@ -195,14 +220,15 @@ 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. 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? }`). |
-| `description` | `string` | Peer-visible description of the work — the sentence another participant reads to decide whether to wait or move on (`'rewriting the risk section'`). Defaults to `'editing'`. |
+| `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: the row (`{ model, id }`) plus any sub-row narrowing the holder claimed: `path?`, `range?`, `field?`, `fields?`, and opaque `meta?`. A target with no narrowing covers the whole row. |
+| `description` | `string` | Peer-visible description of the work: the sentence another participant reads to decide whether to wait or move on (`'rewriting the risk section'`). Defaults to `'editing'`. |
 | `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` | `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. |
+| `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` | `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. |
+| `meta` | `Record<string, unknown>?` | The claim's open metadata bag, as it stands on the wire. A [heartbeat](#heartbeat-holding-a-claim-for-long-running-work) writes its `details` here under `progress`: last beat wins, so an observer can read what a long hold is doing without the holder releasing it. Distinct from `target.meta`, which is the shape your program declared: a declared shape has no member for a key the coordinator wrote. |
 
 ```jsonc
 {
@@ -213,23 +239,49 @@ a model row. It's what `claim.state()` returns and what observers render.
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
   "createdAt": 1748160000000,
-  "expiresAt": 1748160030000
+  "expiresAt": 1748160030000,
+  "meta": { "progress": { "phase": "writing", "done": 2, "of": 5 } }
 }
 ```
 
+### Lifecycle
+
+```
+            claim({ id })              update({ id }) lands
+  (free) ───────────▶ active ───────────────────────▶ committed
+                        │
+            ┌───────────┴───────────┐
+            ▼                       ▼
+        canceled                 expired
+   (release w/o write)        (TTL; holder died)
+```
+
+A target is free when `ablo.<model>.claim.state({ id })` returns `null`. Terminal
+states drop out of the live stream, so a claim you can see is either `active`
+(the holder) or `queued` (waiting in the FIFO line behind it; see
+[`claim.queue`](#claimqueue)).
+
+Reading a holder's progress is the same synchronous read as everything else
+here — no second subscription, and nothing to poll:
+
+```ts
+const held = ablo.documents.claim.state({ id: docId });
+const phase = held?.meta?.progress?.phase ?? 'reading';
+```
+
 ---
 
 ## 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 })`
+- **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
+- **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
+- **`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
+- **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 ·
@@ -249,16 +301,41 @@ then re-reads so the claimed snapshot reflects what the previous holder
 committed. There's no polling and no race window — the server decides the order,
 so two claimers can't both think they won.
 
-**Parameters**
+**Parameters** — every option is flat on the call, and each sits on one of
+four axes. `claim({ id })` alone is a complete call; each axis is opt-in.
+
+*What you claim* — the target, narrowed below the row:
+
+| name | type | required | description |
+|---|---|---|---|
+| `id` | `string` | yes | The row id: same id as `retrieve` / `update`. |
+| `options.field` | `ClaimField` | no | **Deprecated: say it as a set: `fields: ['title']`. Removed in 0.37.0.** One member for a set of one, beside another for a set of any size, is two ways to say one thing, and the singular is the one that misled: a caller needing two parts packed them into it. The wire still reads `field`, so this changes what you write, not what is understood. |
+| `options.fields` | `ClaimField[]` | no | Claim named parts of the row instead of all of it: one or several. Prefer the selector form, `fields: (f) => [f.status]`, where the model hands you its own fields, so a field it does not have stops compiling and a rename is a compile error at every use. A bare name (`'status'`) autocompletes but is not checked; an app-defined part, a cell, a section, is named with `part('B2')`. Two sets conflict where they intersect, so holders of disjoint parts do not wait for each other, see [claiming part of a row](#claiming-part-of-a-row). A name containing a comma is refused: two names in one string compare as a single unrelated name, and both writers would be granted the same part. |
+| `options.path` | `string` | no | A hierarchical position in a document-shaped row: `'/content/3'` claims one block. Paths conflict on containment: `/content` covers `/content/3`, while `/content/3` and `/content/7` are disjoint and both granted. |
+| `options.range` | `TargetRange` | no | A span of the row's text: `{ startLine, endLine, startColumn?, endColumn? }`. Ranges conflict only where their line intervals overlap. An editor addressing by integer position maps it onto `startLine`/`endLine`: the test is plain interval intersection. |
+
+*What others see* — the presence half:
 
 | name | type | required | description |
 |---|---|---|---|
-| `id` | `string` | yes | The row id — same id as `retrieve` / `update`. |
 | `options.description` | `string` | no | Peer-visible description of the work, shown to observers (default `'editing'`). |
-| `options.field` | `string` | no | Field-level target, for fine-grained claimed-state badges. |
-| `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.meta` | `object` | no | App-defined structured metadata, carried verbatim to every participant observing the claim. Declare its shape once on `Register`'s `ClaimMeta` slot. |
+
+*How you wait* — admission to the line:
+
+| name | type | required | description |
+|---|---|---|---|
+| `options.queue` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is the try-claim: if another participant holds the row it resolves `null`: an expected outcome, not an error, so claim-or-skip dedup reads `if (!claim) return` (waiting would double-process). Who holds it stays readable via `claim.state`. A *write* to a held row still rejects `entity_claimed`. |
 | `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. |
+| `options.waitTimeoutMs` | `number` | no | Cap on how long a queued claim waits for its grant before rejecting with `AbloClaimedError('grant_timeout')`. Omit to wait as long as the line takes. Same meaning on both transports; over HTTP a timed-out wait also leaves the line. |
+| `options.signal` | `AbortSignal` | no | Abort a pending wait from outside: a cancelled agent task or an unmounted component takes its queued claim with it. Rejects with `AbloClaimedError('claim_wait_aborted')`; over HTTP the abort also leaves the line. Ignored once the grant has arrived, release a held lease instead. |
+
+*How long you hold* — the lease:
+
+| name | type | required | description |
+|---|---|---|---|
+| `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. |
+| `options.heartbeat` | `true \| Duration \| { every?, onBeat?, onLost? }` | no | Keep the lease alive for work that outlives the TTL: `true` beats every third of the TTL, a duration sets the cadence, and the structured form carries the cadence and both callbacks in one place: `onBeat` fires after every successful beat (chiefly `queueDepth`, the pressure signal), `onLost` once if a beat learns the lease is gone. The loop stops on release. |
 
 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`,
@@ -290,10 +367,69 @@ committed — pass an idempotency key on the write if you replay the block.) The
 lower-level [`claim.release`](#claimrelease) shows the manual `try/finally`
 equivalent for when you hold a claim without `await using`.
 
+### Claiming part of a row
+
+Name a field and a typo cannot survive — the model is already bound by the call,
+so it hands you its own fields:
+
+```ts
+await using mine = await ablo.tasks.claim({ id, fields: (f) => [f.status] });
+```
+
+`f.status` is checked against the model: a field it does not have stops
+compiling, and renaming one is a compile error at every use. Nothing to import,
+nothing to add to your schema file.
+
+`fields: ['status']` still works and still autocompletes; it just accepts
+`'titel'` too, which is granted, excludes nobody, and leaves the write of
+`title` unguarded.
+
+A claim covers the whole row only when you name nothing narrower. Name a
+target — a `path` into a document, a `range` of text, a `field` or set of
+`fields` — and exclusion follows it: **two claims on non-overlapping parts of
+the same row are both granted**, and only overlapping targets queue behind
+each other.
+
+```ts
+// Agent A holds one block of the document…
+await using intro = await ablo.documents.claim({
+  id: docId,
+  path: '/content/3',
+  description: 'rewriting the risk section',
+});
+
+// …while agent B, in another process, holds a different block of the SAME
+// row. Granted immediately — /content/3 and /content/7 do not overlap.
+await using summary = await ablo.documents.claim({
+  id: docId,
+  path: '/content/7',
+  description: 'tightening the summary',
+});
+```
+
+Overlap is judged per axis:
+
+- **`path`:** hierarchical containment, on a separator boundary. `/content`
+  covers `/content/3`, so the parent's holder queues behind (or is queued
+  behind by) the child's; `/content/3` and `/content/7` are disjoint, and
+  `/content` never collides with `/contentious`.
+- **`field` / `fields`:** set intersection. Holders on `title` and `status`
+  proceed concurrently; naming no field covers all of them.
+- **`range`:** interval intersection on `[startLine, endLine]`. An editor
+  that addresses text by integer position rather than by line maps that
+  position axis straight onto `startLine`/`endLine`: the server's test is
+  plain interval intersection and never assumes the units are lines of a
+  file.
+
+A claim with no target is the widest parent: it covers every part of the row
+and conflicts with any narrower claim on it. Region locking on a single
+document row is therefore one claim per region — the row stays one row, and
+the claims carve it up.
+
 ### Claim-gated reads
 
 `claim.state({ id })` always returns immediately. Model reads such as
-`ablo.<model>.get(id)` are local reads and stay available while a claim is
+`ablo.<model>.local.retrieve(id)` are local reads and stay available while a claim is
 held. Server/model reads can choose a claimed policy:
 
 ```ts
@@ -337,8 +473,15 @@ whole coordination API.
 |---|---|---|---|
 | `id` | `string` | yes | The row id. |
 
-**Returns** — the active [claim state object](#the-claim-state-object), or `null` when the row
-is free.
+**Returns** — an active [claim state object](#the-claim-state-object) on the row, or
+`null` when the row is free.
+
+**One holder, and a row can have several.** This reads a row, not a target, and
+answers with a single claim. That is the whole story for a whole-row claim, and
+only part of it once you [claim parts of a row](#claiming-part-of-a-row): three
+agents holding `/content/3`, `/content/7`, and `title` are all active at once,
+and this read surfaces one of them. To render every holder — a rail per claimed
+block, a chip per participant — use [`claim.list`](#claimlist).
 
 **Example**
 
@@ -361,6 +504,45 @@ Returns the active claim state when the row is held, or `null` when it's free:
 }
 ```
 
+### `claim.list`
+
+```ts
+ablo.<model>.claim.list({ id })
+```
+
+Every holder of a row. Same synchronous, reactive read as `claim.state` — off
+the same local snapshot, safe to call inline in a render — and the same list
+envelope as [`claim.queue`](#claimqueue).
+
+Reach for it whenever a row can be claimed in parts. One agent rewriting
+`/content/3` while another tightens `/content/7` are two active claims on one
+row, and only this read returns both.
+
+**Parameters**
+
+| name | type | required | description |
+|---|---|---|---|
+| `id` | `string` | yes | The row id. |
+
+**Returns** — `{ object: 'list', data: Claim[] }`. Your own claim comes first
+when this client holds one, then the other participants'. Empty `data` when the
+row is free.
+
+**Example** — a rail for every claimed block:
+
+```tsx
+const { data: holders } = ablo.documents.claim.list({ id: docId });
+
+return blocks.map((block) => {
+  const held = holders.find((c) => c.target.path === `/content/${block.index}`);
+  return <Block key={block.id} rail={held?.heldBy} note={held?.description} />;
+});
+```
+
+`claim.state({ id })` remains the right read when a row is claimed whole, or
+when all you need is "is anyone working here" — it answers with one claim and
+`null` when the row is free.
+
 ### `claim.queue`
 
 ```ts
@@ -426,7 +608,7 @@ try {
 }
 ```
 
-### `heartbeat` — holding a claim for long-running work
+### `heartbeat`: holding a claim for long-running work
 
 ```ts
 held.heartbeat(ttl?: Duration): Promise<{ expiresAt: number }>
@@ -447,8 +629,7 @@ await using claim = await ablo.reports.claim({
   id: 'report_q3',
   description: 'generating',
   ttl: '5m',
-  heartbeat: true,               // or an explicit cadence: heartbeat: '2m'
-  onHeartbeatLost: () => abortWork(),
+  heartbeat: { onLost: () => abortWork() }, // `true` and '2m' are the shorthands
 });
 await runLongGeneration(claim.data); // lease held for the duration
 // scope exit releases; the loop stops with it
@@ -463,11 +644,11 @@ failures (a connection blip) don't stop the loop — the next tick retries.
 
 Each beat's answer carries two more things:
 
-- **`queueDepth`** — how many participants wait in line behind the lease.
+- **`queueDepth`:** how many participants wait in line behind the lease.
   This is the cooperative-yield pressure signal: a worker that can checkpoint
   may release early when others wait. Read it from the resolved beat, or pass
-  `onHeartbeat` when claiming to observe every auto-beat.
-- **progress `details`** — `held.heartbeat({ details: { pages: 42, of: 100 } })`
+  `heartbeat: { onBeat }` when claiming to observe every auto-beat.
+- **progress `details`:** `held.heartbeat({ details: { pages: 42, of: 100 } })`
   stores the payload as the claim's peer-visible `meta.progress` (last beat
   wins, via `claim.state`). This is presence, not a checkpoint: it dies with
   the lease. Durable progress belongs in the data itself — write a row, and
@@ -497,7 +678,7 @@ A stateless worker holding **many** rows beats them all in one round trip:
 entry per extended lease. This is the socketless twin of the realtime
 keepalive, which already renews every held lease on each ping.
 
-### durability — what a claim survives
+### durability: what a claim survives
 
 A lease belongs to your **identity** — the participant behind the credential —
 not to the socket it was claimed on; the server keys each lease by participant
@@ -537,20 +718,20 @@ snapshot.
 
 | the holder… | what happens to the claim |
 | --- | --- |
-| blips, then reconnects within the window | renewed automatically on reconnect — no interruption |
+| blips, then reconnects within the window | renewed automatically on reconnect: no interruption |
 | crashes or drops for good | released within one keepalive cycle; the queue advances |
-| still has a second live connection | survives — release fires only on the last connection |
+| still has a second live connection | survives: release fires only on the last connection |
 | loses the server to a restart | rides the TTL in the coordination store; re-announced on reconnect |
 
-### `join` — presence for a set of rows
+### `join`: 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
+presence on a known set of rows — a workspace's documents, a board's cards — and react to
 who joins or leaves, use `join`:
 
 ```ts
-await using room = await ablo.slides.join(slideIds, { ttl: '5m' });
+await using room = await ablo.documents.join(slideIds, { ttl: '5m' });
 room.peers; // who else is here, live
 ```
 
@@ -615,19 +796,19 @@ inspect the `code`.
 
 | error | `code` | thrown when | carries |
 |---|---|---|---|
-| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, was revoked, or was preempted (a privileged reorder, or a configured cumulative-hold ceiling reached while contenders waited) — while you were holding or waiting. | `claims?` |
-| `AbloClaimedError` | `claim_queued` | **HTTP transport only.** A contended `claim` (default `queue: true`) could not block-wait for the lease (no socket), so it rejected immediately instead of queueing. Retryable — re-attempt the claim. | `claims?` |
+| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away: the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, was revoked, or was preempted (a privileged reorder, or a configured cumulative-hold ceiling reached while contenders waited), while you were holding or waiting. | `claims?` |
+| `AbloClaimedError` | `claim_queued` | **HTTP transport only.** A contended `claim` (default `queue: true`) could not block-wait for the lease (no socket), so it rejected immediately instead of queueing. Retryable: re-attempt the claim. | `claims?` |
 | `AbloClaimedError` | `grant_timeout` | The optional `timeoutMs` elapsed while you were still queued for a grant. | `claims?` |
-| `AbloClaimedError` | `queue_too_deep` | `claim` was passed `maxQueueDepth` and the wait line was already that deep when you tried to join — fail-fast instead of waiting. | `claims?` |
-| `AbloClaimedError` | `claim_conflict` | An `update`/`delete` targets a row another participant holds — the server's pre-commit check rejected it. | — |
-| `AbloClaimedError` | `entity_claimed` | Same conflict, from the commit guard backstop. | — |
-| `AbloStaleContextError` | — | A guarded `update` (under a claim, or any write carrying `readAt`) targets a row that received deltas since the snapshot — your reasoning is stale. | `readAt`, `conflicts[]` |
-| `AbloValidationError` | `model_claim_not_configured` | `claim` called on a model proxy built without the collaboration runtime — an internal/advanced construction path. The standard `Ablo({ schema, apiKey })` client enables claiming for **every** model; there is no per-model claim config to add. | — |
-| `AbloValidationError` | `entity_not_found` | The row id doesn't exist locally or on load. | — |
+| `AbloClaimedError` | `queue_too_deep` | `claim` was passed `maxQueueDepth` and the wait line was already that deep when you tried to join: fail-fast instead of waiting. | `claims?` |
+| `AbloClaimedError` | `claim_conflict` | An `update`/`delete` targets a row another participant holds: the server's pre-commit check rejected it. |: |
+| `AbloClaimedError` | `entity_claimed` | Same conflict, from the commit guard backstop. |: |
+| `AbloStaleContextError` |: | A guarded `update` (under a claim, or any write carrying `readAt`) targets a row that received deltas since the snapshot: your reasoning is stale. | `readAt`, `conflicts[]` |
+| `AbloValidationError` | `model_claim_not_configured` | `claim` called on a model proxy built without the collaboration runtime: an internal/advanced construction path. The standard `Ablo({ schema, apiKey })` client enables claiming for **every** model; there is no per-model claim config to add. |: |
+| `AbloValidationError` | `entity_not_found` | The row id doesn't exist locally or on load. |: |
 
 `AbloStaleContextError.conflicts` lists the `(model, id, observedSyncId)` rows
 that moved during your generation window — use it for selective regeneration
-(re-think only the slides that changed, not the whole deck) and for metrics.
+(re-think only the documents that changed, not the whole workspace) and for metrics.
 
 ```ts
 try {
@@ -731,9 +912,9 @@ state**, which is the shape that races. The other two aren't read-modify-write:
 
 | Verb | Functional form? | Why | Its "just works" property |
 | --- | --- | --- | --- |
-| `update` | **yes** — `update(id, current => next)` | next value depends on the current one (lost-update hazard) | compare-and-swap + reconcile |
-| `create` | no — `create({ data, id? })` | no prior state to read; the hazard is *id collision*, a terminal `unique_violation`, not a lost update | **idempotency** — stable id / `idempotencyKey` makes a retried create safe |
-| `delete` | no — `delete({ id })` | no resulting state to compute; "make it not exist" is unchanged by concurrent edits, and delete is idempotent | naturally idempotent |
+| `update` | **yes**: `update(id, current => next)` | next value depends on the current one (lost-update hazard) | compare-and-swap + reconcile |
+| `create` | no: `create({ data, id? })` | no prior state to read; the hazard is *id collision*, a terminal `unique_violation`, not a lost update | **idempotency**: stable id / `idempotencyKey` makes a retried create safe |
+| `delete` | no: `delete({ id })` | no resulting state to compute; "make it not exist" is unchanged by concurrent edits, and delete is idempotent | naturally idempotent |
 
 The same reason React has `setState(prev => next)` but no functional mount /
 unmount. A *conditional* delete ("only if unchanged since I read it") is the one
@@ -742,38 +923,19 @@ not a function.
 
 ---
 
-## Observability — the `ClaimLog`
+## Observability
 
 Coordination you can't see is coordination you can't debug. Pass an
 `observability` provider to `Ablo({ ... })` and the client reports every claim
 lifecycle event and stale-write collision it sees. The batteries-included
-provider is `ClaimLog`:
+provider is `ClaimLog`, and `collisions()` is the eval primitive:
 
 ```ts
-import Ablo, { ClaimLog } from '@abloatai/ablo';
-
 const log = new ClaimLog();
 const ablo = Ablo({ schema, apiKey, observability: log });
-// …run your agents…
 
-log.entries        // full ordered timeline, one readable line each
-log.collisions()   // just the collisions: rejected/lost claims + stale writes
-log.toString()     // pretty, greppable timeline to print
-log.onChange(fn)   // reactive subscribe → drive a live activity feed / useSyncExternalStore
+expect(log.collisions()).toHaveLength(0);   // no one stepped on anyone
 ```
 
-`collisions()` is the eval primitive — `expect(log.collisions()).toHaveLength(0)`
-asserts "no one stepped on anyone." Each line names the row it touched, e.g.
-`conflict: tx … — 1 row(s) changed underneath: reports/r1`.
-
-`ClaimLog` implements the full `SyncObservabilityProvider`, so it drops straight
-into the `observability` slot; spread `noopObservability` if you only want to
-override a few hooks (e.g. forward to Sentry/OTel). Exports: `ClaimLog`,
-`formatClaim`, `formatConflict`, `noopObservability`, and the types `ClaimEvent`,
-`ConflictEvent`, `ClaimLogEntry`, `SyncObservabilityProvider`.
-
-> **Both transports, from 0.21.0.** Observability fires on the WebSocket **and**
-> the stateless HTTP transport (claim acquired + coordination-conflict
-> rejections, on every write door). Before 0.21.0 only WebSocket emitted, so a
-> `ClaimLog` on an HTTP client — e.g. a headless server-agent eval — stayed
-> silent even though coordination still worked.
+See [Debugging & Logs](./debugging.md) for the setup, the event shapes, a
+reactive activity feed, and routing events to your own backend.