@abloatai/ablo 0.35.0 → 0.36.0

package/docs/coordination.md

@@ -38,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
@@ -83,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
@@ -91,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)?**
@@ -205,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
 {
@@ -223,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 ·
@@ -259,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`,
@@ -300,6 +367,65 @@ 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
@@ -347,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**
 
@@ -371,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
@@ -436,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 }>
@@ -457,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
@@ -473,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
@@ -507,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
@@ -547,12 +718,12 @@ 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*
@@ -625,15 +796,15 @@ 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
@@ -741,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
@@ -752,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.

package/docs/data-sources.md

@@ -75,7 +75,7 @@ Run it against your database as a superuser or the DB owner. It creates:
 
   Scope it to a subset with `npx ablo connect --tables a,b,c`.
 
-- **A replication role** — it streams the WAL and `SELECT`s, nothing more. This is
+- **A replication role:** it streams the WAL and `SELECT`s, nothing more. This is
   the role Ablo reads and confirms through. You choose the password; it never
   passes through Ablo's CLI or servers:
 
@@ -87,7 +87,7 @@ Run it against your database as a superuser or the DB owner. It creates:
   On Amazon RDS the `REPLICATION` attribute is granted, not set directly:
   `GRANT rds_replication TO "ablo_replicator";`.
 
-- **A scoped writer role** — the role Ablo writes your rows through. It gets row
+- **A scoped writer role:** the role Ablo writes your rows through. It gets row
   DML (`SELECT, INSERT, UPDATE, DELETE`) and the sync ledger, and nothing else: no
   `REPLICATION`, no schema `CREATE`, `NOSUPERUSER NOBYPASSRLS`, row security on. It
   can change rows in your tables; it cannot change your database:
@@ -189,7 +189,7 @@ A commit is accepted the moment Ablo takes it (`queued`); it becomes `confirmed`
 once the row appears on your WAL. See [Guarantees](./guarantees.md) for what each
 state means and when to wait.
 
-## What Ablo touches in your database — the honest footprint
+## What Ablo touches in your database: the honest footprint
 
 This is the complete list. Nothing else.
 
@@ -197,7 +197,7 @@ This is the complete list. Nothing else.
 |---|---|---|
 | `ablo_publication` | A publication naming the tables Ablo reads and confirms against. | You create it (step 2). |
 | `ablo_replicator` role | A `REPLICATION` + `SELECT` role Ablo reads and confirms through. | You create it (step 2). |
-| `ablo_writer` role | A scoped DML role Ablo writes your rows through — row DML + ledger, nothing more. | You create it (step 2). |
+| `ablo_writer` role | A scoped DML role Ablo writes your rows through: row DML + ledger, nothing more. | You create it (step 2). |
 | Replication slot | A logical slot Ablo subscribes through to track its WAL position. | Ablo's runtime creates it on first connect. |
 | `wal_level = logical` | A server setting that **requires a restart**. | You set it (step 1). |
 

package/docs/debugging.md

@@ -13,6 +13,17 @@ import { schema } from './ablo/schema';
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, debug: true });
 ```
 
+## CLI environment and target
+
+The CLI checks an explicit credential in this order: exported `ABLO_API_KEY`,
+`.env.local`, `.env`, then the key saved by `ablo login`. An exported value wins
+over project files. If a stale shell export (for example `OPENAI_API_KEY`) is
+shadowing a value in `.env.local`, restart the shell or unset the stale variable.
+
+When a command appears to use the wrong plane or project, run `ablo status`.
+It reports the credential source and, when reachable, the server-confirmed
+project and environment; that confirmed target is authoritative.
+
 `debug: true` is the simple switch. For finer control use `logLevel`, or set it without touching code via the `ABLO_LOG_LEVEL` environment variable.
 
 ```ts
@@ -31,15 +42,15 @@ ABLO_LOG_LEVEL=debug npm run dev               # same, from the environment
 |---|---|
 | `silent` | nothing |
 | `error` | failures only |
-| `warn` | **default** — warnings + errors |
+| `warn` | **default**: warnings + errors |
 | `info` | the above + the **coordination trace** (claims, grants, queueing) + connection state |
-| `debug` | the above + internal lifecycle (per-model registration, store hydration) — the full firehose |
+| `debug` | the above + internal lifecycle (per-model registration, store hydration): the full firehose |
 
 Precedence: an explicit `logLevel` wins, then `debug: true` (⇒ `debug`), then `ABLO_LOG_LEVEL`, then the `warn` default. `debug: false` (or omitting it) just means "don't raise the level."
 
 > For watching coordination, **`logLevel: 'info'` is the sweet spot** — you get the claim trace without the per-model registration chatter that `debug` adds.
 
-## What you'll see — the coordination trace
+## What you'll see: the coordination trace
 
 These lines (all at `info`) let you watch the handover you built:
 
@@ -54,12 +65,12 @@ These lines (all at `info`) let you watch the handover you built:
 
 Read it as the lifecycle of one claim:
 
-- **`requesting`** — your code (or an agent) called `ablo.<model>.claim(...)`. `(will queue if contended)` appears when you passed `{ queue: true }`.
-- **`queued … position N of M`** — the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
-- **`granted … your turn`** — you reached the head of the line; the lease is now yours and the row may have changed while you waited.
-- **`rejected … held by <who>`** — your claim was refused because someone else holds it (and the model's policy didn't let you in).
-- **`lost`** — you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
-- **`released`** — you (or `await using`'s scope exit) gave the lease back.
+- **`requesting`:** your code (or an agent) called `ablo.<model>.claim(...)`. `(will queue if contended)` appears when you passed `{ queue: true }`.
+- **`queued … position N of M`:** the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
+- **`granted … your turn`:** you reached the head of the line; the lease is now yours and the row may have changed while you waited.
+- **`rejected … held by <who>`:** your claim was refused because someone else holds it (and the model's policy didn't let you in).
+- **`lost`:** you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
+- **`released`:** you (or `await using`'s scope exit) gave the lease back.
 
 ## Where the logs run
 
@@ -82,7 +93,7 @@ Ablo({
 });
 ```
 
-## Read the coordination in code — the activity log
+## Read the coordination in code: the activity log
 
 The console trace above is for *you*, at a terminal. To put the same activity **inside your app** — an activity feed, a "who's editing" badge, a Sentry breadcrumb trail — read it programmatically. Same events, three layers; pick by audience:
 
@@ -114,7 +125,7 @@ interface ConflictEvent {
 
 `phase` is past-tense — the state the claim just entered — and maps one-to-one to what arrives on the wire.
 
-### Collect them — `ClaimLog`
+### Collect them: `ClaimLog`
 
 `ClaimLog` records both into an ordered list. Hand it to `observability`, then read it back:
 
@@ -136,7 +147,7 @@ It's also the simplest way to **assert** coordination in a test — no log scrap
 expect(log.collisions()).toHaveLength(0);   // no one stepped on anyone
 ```
 
-### Show it on a page — reactive
+### Show it on a page: reactive
 
 `ClaimLog.onChange` fires on every event and returns an unsubscribe — the exact shape `useSyncExternalStore` wants, so a live feed is a few lines:
 
@@ -185,6 +196,17 @@ const ablo = Ablo({
 });
 ```
 
+`ClaimLog` implements the full `SyncObservabilityProvider`, so it drops straight
+into the `observability` slot. The surface exports `ClaimLog`, `formatClaim`,
+`formatConflict`, and `noopObservability`, plus the types `ClaimEvent`,
+`ConflictEvent`, `ClaimLogEntry`, and `SyncObservabilityProvider`.
+
+> **Both transports, from 0.21.0.** Observability fires on the WebSocket and on
+> the stateless HTTP transport (claim acquired, plus coordination-conflict
+> rejections on every write door). Before 0.21.0 only WebSocket emitted, so a
+> `ClaimLog` on an HTTP client, such as a headless server-agent eval, stayed
+> silent even though coordination still worked.
+
 ## Errors
 
 Ablo's thrown errors are typed and self-describing — `String(err)` (or logging it) yields one clean line, never a stack dump: