@abloatai/ablo 0.34.1 → 0.35.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
@@ -128,46 +131,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:
 
-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):
+| 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.
+
+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
 
@@ -293,7 +303,7 @@ equivalent for when you hold a claim without `await using`.
 ### 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
@@ -546,11 +556,11 @@ snapshot.
 
 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
 ```
 
@@ -627,7 +637,7 @@ inspect the `code`.
 
 `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 {

package/docs/data-sources.md

@@ -1,5 +1,7 @@
 # Connect Your Database
 
+> Keep the rows in your own Postgres while Ablo coordinates and confirms every write.
+
 You write through Ablo, and Ablo writes to your Postgres. A call to
 `ablo.<model>.create / update / delete` enters Ablo's commit chokepoint — where
 claims, ordering, and idempotency are enforced — and Ablo applies the change to
@@ -180,7 +182,7 @@ await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 } })
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 }, wait: 'confirmed' });
 
 // Reads are live off the same stream.
-const report = ablo.weatherReports.get('report_stockholm');
+const report = ablo.weatherReports.local.retrieve('report_stockholm');
 ```
 
 A commit is accepted the moment Ablo takes it (`queued`); it becomes `confirmed`

package/docs/debugging.md

@@ -1,6 +1,8 @@
 # Debugging & Logs
 
-By default the SDK is quiet — it logs only warnings and errors. When you're building a human + agent flow and want to *see* the coordination happen (who claimed what, who's waiting in line, who got preempted), turn on Ablo's diagnostic logging. Every line is prefixed `[Ablo]` so it's obvious which output is ours in a console full of other tools.
+> Watch claims, queueing, and grants as they happen while you build.
+
+By default the SDK is quiet — it logs only warnings and errors. When you're building a multi-agent flow and want to *see* the coordination happen (who claimed what, who's waiting in line, who got preempted), turn on Ablo's diagnostic logging. Every line is prefixed `[Ablo]` so it's obvious which output is ours in a console full of other tools.
 
 ## Turn it on
 
@@ -39,7 +41,7 @@ Precedence: an explicit `logLevel` wins, then `debug: true` (⇒ `debug`), then
 
 ## What you'll see — the coordination trace
 
-These lines (all at `info`) let you watch the human + agent handover you built:
+These lines (all at `info`) let you watch the handover you built:
 
 ```
 [Ablo] claim: requesting documents:doc_42 for "editing" (will queue if contended)
@@ -61,7 +63,7 @@ Read it as the lifecycle of one claim:
 
 ## Where the logs run
 
-The coordination trace and the proactive credential refresh run **in the browser** (and any client that holds a live socket) — that's where the human + agent activity is. Server-side code that mints credentials or does one-shot reads won't emit the trace; it has no live session to narrate.
+The coordination trace and the proactive credential refresh run **in the browser** (and any client that holds a live socket) — that's where the live coordination activity is. Server-side code that mints credentials or does one-shot reads won't emit the trace; it has no live session to narrate.
 
 ## Bring your own logger
 

package/docs/deployment.md

@@ -0,0 +1,267 @@
+# Deployment
+
+> What production takes: a database Ablo can reach, a key minted for the plane you mean, and a schema push in the deploy.
+
+One command answers the question this page exists for — would a write succeed
+right now, and if not, why:
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo status
+```
+
+```text
+  ablo status
+
+  key     sk_live_51H8… (ABLO_API_KEY env — overrides stored)
+  mode    production
+  org     org_3nKq…
+  project checkout (prj_7Yb2…)
+  acts on production
+  ○ sandbox     sk_test_9fJd… · expires in 71d
+  ● production  — no key
+  push    production with sk_live_51H8… (env)
+  api     https://api.abloatai.com  reachable
+  data    ✓ database connected to this plane (direct)
+  schema  4 models pushed (rev 12) hash 3f9a2c81 @ 2026-07-18
+          • orders         typename=orders
+          • lineItems      typename=lineItems
+          • fulfilments    typename=fulfilments
+          • reviews        typename=reviews
+
+  ✓ ready — a write should succeed
+```
+
+`status` asks the routing authority rather than sampling a read, because reads
+resolve while writes are held — a plane with no database connected serves every
+read and refuses every write. The verdict at the bottom is the whole page in one
+line, and `--json` puts the same conclusion in a `blockers` array you can gate a
+deploy on.
+
+## The three ingredients
+
+There is no Ablo service for you to deploy. Ablo is hosted, your rows live in
+your own Postgres, and your app runs where it already runs — so a deployment is
+three pieces pointed at the same plane.
+
+| Ingredient | Who runs it | What "deploying" means for it |
+|---|---|---|
+| **Your Postgres** | You (or your provider) | Registering it against your production plane, once, with a production key. |
+| **Ablo** | Hosted at `api.abloatai.com` | Nothing to run. You choose a project, a plane, and the keys that reach them. |
+| **Your app and agents** | You | Holding the right credential for the runtime, and pushing the schema in the deploy. |
+
+Everything below is those three in order.
+
+### Planes: what a deployment targets
+
+A **plane** is the isolation unit a credential acts on. `production` is the root
+plane; every sandbox sits beside it. Three things are per-plane, and knowing
+which three is most of what production readiness means:
+
+- **Rows** — a sandbox write is invisible to production and to every other sandbox.
+- **The registered database** — one per plane, so your production database and
+  your dev database are separate registrations.
+- **The active schema artifact** — the model shapes the engine actually routes on.
+
+A key's plane is fixed at mint and spelled in its prefix: `sk_live_` acts on
+production, `sk_test_` on a sandbox. There is no runtime override — the
+credential *is* the environment selector, which is why application code never
+passes one.
+
+One asymmetry is worth carrying into your deploy plan. A sandbox with no schema
+artifact of its own reads **production's**, so a schema pushed to production
+reaches your sandboxes automatically. The reverse does not hold: a push from a
+sandbox key creates a sandbox artifact that shadows production **for that
+sandbox's readers only**, and production keeps running the schema it was last
+pushed. Production gets its models when you push to production.
+
+## 1. The database production writes to
+
+Your production database joins Ablo the same way your dev database did — logical
+replication so Ablo can read and confirm, a scoped writer role so Ablo can land
+rows — run once, with a production key so the registration attaches to the
+production plane:
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo connect apply --url postgres://admin:…@host:5432/db
+ABLO_API_KEY=sk_live_… npx ablo connect check
+```
+
+[Connect Your Database](./data-sources.md) is the full walkthrough — the SQL, the
+two roles, and the complete list of what Ablo touches. Five things about it are
+specifically production concerns:
+
+**Your agents do not each hold a connection.** Every agent, worker, and function
+talks to Ablo, and Ablo holds the database connections — at most 4 connections
+per plane, the same 4 whether one caller is writing behind them or ten thousand
+are. They identify themselves as `ablo-direct-writer`, so `pg_stat_activity`
+accounts for everything Ablo has open at any moment. Size the database for that
+number rather than for your agent count.
+
+**Register the direct host, not the pooler.** A pooler terminates the session
+that replication needs, and it refuses the connection in the same words a wrong
+password would — so a pooled host reads as a credentials problem for as long as
+you let it. `ablo status` names a pooled host when it sees one, with the direct
+host to use instead.
+
+**Reachability is measured from Ablo's network, not yours.** `connect check`
+runs from the infrastructure replication runs on, so an IPv6-only,
+IP-allowlisted, or VPC-private database still verifies — and a database your
+laptop can reach but Ablo cannot fails here rather than at the first write.
+
+**`wal_level = logical` needs a restart.** It is server-wide and not reloadable.
+On RDS and Aurora it is a parameter-group change plus a reboot. Schedule it;
+it is the one setup step with downtime in it.
+
+**A replication slot retains WAL.** While Ablo is connected the slot holds what
+it has not yet acknowledged, so a long disconnection accumulates disk. Ablo
+monitors slot lag and retention and surfaces it, and drops an abandoned slot
+rather than letting it grow without bound.
+
+A database that cannot grant a `REPLICATION` role connects through the signed
+[Data Source endpoint](./data-sources.md) instead. Same model surface, same
+commit chokepoint — it is the marked fallback, so reach for it when replication
+is genuinely unavailable.
+
+## 2. The credential each runtime holds
+
+There is one field, `apiKey`, and what goes in it follows from where the code
+runs. In production that resolves to four rows:
+
+| Runtime | Credential | Notes |
+|---|---|---|
+| Server, worker, agent, cron | `sk_live_` in `ABLO_API_KEY` | Defaults from the environment, so most code passes nothing. |
+| Serverless function | `sk_live_` in `ABLO_API_KEY`, with `transport: 'http'` | Stateless request/response; nothing held open across invocations. |
+| Browser, read-only | `pk_live_` | Publishable and safe to ship, like a Stripe `pk_`. Reads only. |
+| Browser, writing as the signed-in user | `authEndpoint` | A route on your backend mints a short-lived `ek_` per user. |
+
+[API Keys](./api-keys.md) covers the model; [Sessions](./sessions.md) covers
+minting. Two things bite specifically at deploy time.
+
+**The live key `ablo login` gives you cannot push schema.** It is a restricted,
+observe-only `rk_live_` by design, so a stolen CLI config cannot write to
+production. A production deploy needs a **secret** `sk_live_` from the dashboard,
+supplied as `ABLO_API_KEY`. You do not have to discover this from a failed
+deploy: `ablo login`, `ablo mode production`, and `ablo status` each name what
+the key in hand does, and `ablo status --json` reports it as `effectiveKey.kind`
+for a pipeline to check before it pushes.
+
+**An explicit key always wins.** The CLI resolves `ABLO_API_KEY`, then
+`.env.local`, then `.env`, then the stored login — and `ablo status` prints which
+one it found under `key`, with its source. When a deploy lands somewhere
+surprising, that line is usually the answer.
+
+## 3. Pushing the schema is a deploy step
+
+The server keeps its own copy of your schema and routes on that copy. Until it
+has yours, a write to a new model fails with `server_execute_unknown_model` — so
+`ablo push` belongs in your deploy pipeline, ordered **before** the code that
+depends on the new models goes live.
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo push --yes
+```
+
+Production requires confirmation: interactively you type the destination
+project's name, which is what makes a wrong-project deploy impossible to do by
+reflex. In CI there is no TTY, so `--yes` is the confirmation and a push without
+it stops rather than proceeding unattended.
+
+**Additive changes pass; destructive ones ask.** Adding a model or an optional
+field applies cleanly. Dropping a model or a field, narrowing an enum, or a lossy
+cast is classified as data loss and needs `--force`; adding a required field to a
+populated table needs a `--backfill`. A push that fails is recorded `failed` and
+never activated, so a broken migration cannot leave clients gated against tables
+that do not match.
+
+This is the same expand-and-contract shape any online migration has, and it
+sequences the same way: push the additive change, deploy the code that writes
+both shapes, backfill, then push the removal in a later deploy once nothing reads
+the old field.
+
+**Drift is a connect-time rejection, not a runtime surprise.** A client built
+against a schema the server is no longer running is turned away when it connects.
+`ablo status` prints the local hash beside the deployed one, and the running
+client reports the same `serverSchemaHash` value, so the two can be matched at a
+glance.
+
+## Gate the deploy on the verdict
+
+`ablo status --json` reports the same conclusion the human output ends with, in a
+form a pipeline can act on. An empty `blockers` array is the machine-readable
+form of "ready":
+
+```bash
+blockers=$(ABLO_API_KEY=$ABLO_API_KEY npx ablo status --json | jq '.blockers | length')
+[ "$blockers" -eq 0 ] || { npx ablo status; exit 1; }
+```
+
+Each blocker carries a `problem` and the single `fix` that resolves it, in the
+order you should act on them: an unreachable API makes every other finding
+unverifiable, and a plane with nothing connected makes a schema question
+academic. The JSON also carries `confirmedTarget` — the org, project, and
+environment the server says this key resolves to — which is the authoritative
+answer to where a push would land.
+
+## Webhooks point at the deployed URL
+
+`npx ablo dev` forwards commits to your machine while you build, the way
+`stripe listen` does. A deployed endpoint is registered once, and Ablo returns
+the signing secret a single time:
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo webhooks create https://yourapp.com/api/ablo/[...all]
+ABLO_API_KEY=sk_live_… npx ablo webhooks list   # endpoints + delivery health
+```
+
+`webhooks list` reports each endpoint's status, cursor, and last error — the
+place to look when a mirror falls behind. [Webhooks](./webhooks.md) covers the
+handler, the Standard Webhooks signature, and rolling a secret.
+
+## What to watch once it is live
+
+- **`ablo logs`** — commit activity as it happens, scoped by the key, so a live
+  key streams the org and a test key streams only its sandbox. `--json` emits
+  NDJSON for piping.
+- **`ablo status`** — the readiness verdict. Cheap enough to run from a health
+  check on your own side.
+- **The [audit log](./audit.md)** — every confirmed write traced back to the key
+  that made it and the person who authorized that key.
+- **Your own logger** — pass `logger` to the client and SDK lifecycle, sync,
+  retry, and rollback events join your existing pipeline.
+
+Writes carry receipts rather than being fire-and-forget: a commit is accepted the
+moment Ablo takes it (`queued`) and becomes `confirmed` once the row appears on
+your database's WAL. [Guarantees](./guarantees.md) covers which state to wait for
+and what each promises.
+
+## When something is wrong
+
+| What you see | What it means | The fix |
+|---|---|---|
+| `no database is connected to this plane` | Writes are held rather than routed. Reads still resolve, which is why a read probe stays quiet. | `ablo connect apply` with a key for that plane. |
+| `password authentication failed` during connect | Often a pooled host refusing a session it cannot serve, in the words of a wrong password. | Register the direct database host. |
+| `server_execute_unknown_model` | The plane's active schema does not carry that model. | `ablo push` with a key for that plane. |
+| Clients rejected at connect | The deployed schema and the client's schema disagree. | Push this tree, or deploy the revision the server is running. |
+| `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project — a push cannot cross projects. |
+| 403 on `ablo push` | The key authenticated but cannot author schema. | A secret `sk_live_`; the `ablo login` live key is observe-only. |
+
+## The checklist
+
+1. Production database registered against the production plane, direct host, and
+   `ablo connect check` all green.
+2. A secret `sk_live_` in the deploy environment as `ABLO_API_KEY` — never in a
+   browser bundle.
+3. `ablo push --yes` in the pipeline, ahead of the code that needs the new models.
+4. `ablo status --json` gating the deploy on an empty `blockers` array.
+5. Browser clients on a `pk_live_` or an `authEndpoint`, not a secret key.
+6. Webhook endpoints registered at their deployed URLs, with the signing secret
+   in your environment.
+
+## Next steps
+
+- [Connect Your Database](./data-sources.md) — the setup this page registers, in full.
+- [Projects](./projects.md) — one org, many apps, each with its own planes and keys.
+- [API Keys](./api-keys.md) — which credential each runtime holds, and what it may do.
+- [CLI](./cli.md) — every command, its flags, and the environment variables.
+- [Operating on Your Database](./operating-on-your-database.md) — which actions run freely and which belong to a human.
+- [Debugging & Logs](./debugging.md) — watching claims, queueing, and grants while you build.

package/docs/examples/agent-human.md

@@ -1,15 +1,18 @@
 # Agent + Human
 
-A report-writing agent that yields when a human is editing the same report.
+> An agent that yields the row when a person is already holding it.
+
+A task-writing agent that yields when a person is editing the same task.
 
 ## Scenario
 
-The same reports are edited by both humans and agents. They must not collide:
+The same tasks are edited by agents and by the people watching them. They must
+not collide:
 
-- If a human already holds the row, the agent yields instead of fighting for it.
+- If a person 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.
+- If the task changes mid-run, the commit is rejected instead of overwriting the
+  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
@@ -21,70 +24,74 @@ a typed error if the row moved underneath you while the agent was busy.
 
 ## Schema-Backed Worker
 
-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.
+The worker uses the same schema client the app uses. It reads the task from the
+server with `retrieve({ id })`, claims the row, and writes through
+`ablo.tasks.update(...)` with a stale-check so a concurrent edit can't be
+overwritten.
 
 ```ts
 import Ablo, { AbloClaimedError, AbloStaleContextError } from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  weatherReports: model({
-    location: z.string(),
-    status: z.enum(['pending', 'ready']),
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
   }),
 });
 
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
 
-export async function markReady(reportId: string) {
+export async function markDone(taskId: string) {
   await ablo.ready();
 
   // retrieve({ id }) is an async server read — await it.
-  const report = await ablo.weatherReports.retrieve({ id: reportId });
-  if (!report) return { status: 'not_found' };
+  const task = await ablo.tasks.retrieve({ id: taskId });
+  if (!task) return { status: 'not_found' };
 
   try {
-    // queue: false → don't queue behind a current holder. If a human already
+    // queue: false → don't queue behind a current holder. If someone already
     // holds the row, claim rejects with AbloClaimedError (caught below), so the
     // agent yields instead of waiting. Omit it, or pass queue: true, to queue
     // behind them. description → the label observers see while we work.
-    await using claim = await ablo.weatherReports.claim({
-      id: reportId,
+    await using claim = await ablo.tasks.claim({
+      id: taskId,
       queue: false,
-      description: 'marking_ready',
+      description: 'marking_done',
     });
-    const claimed = claim.data;
+    if (claim.data.status === 'done') return { status: 'noop' };
 
     // 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' },
+    //   ablo.tasks.update({
+    //     id: claim.data.id,
+    //     data: { status: 'done' },
     //     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' },
+    // If a newer version landed mid-run, the row no longer matches `readAt`, so
+    // the server rejects this commit with AbloStaleContextError (caught below)
+    // instead of clobbering that edit.
+    const updated = await ablo.tasks.update({
+      id: claim.data.id,
+      data: { status: 'done' },
       wait: 'confirmed',
     });
 
-    return { status: 'ready', report: updated };
+    return { status: 'done', task: updated };
   } catch (err) {
-    // A human already holds the row — yield this run and let them finish.
+    // Someone 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
+    // A newer version was saved 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;
@@ -101,14 +108,14 @@ 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.get(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
-  const agentActive = active?.participantKind === 'agent';
+export function TaskRow({ task: serverTask }: Props) {
+  const data = useAblo((ablo) => ablo.tasks.local.retrieve(serverTask.id)) ?? serverTask;
+  const holder = useAblo((ablo) => ablo.tasks.claim.state({ id: serverTask.id }));
+  const agentActive = holder?.participantKind === 'agent';
 
   return (
     <div>
-      <span>{data.location}</span>
+      <span>{data.title}</span>
       {agentActive ? <span>Agent is updating...</span> : null}
     </div>
   );
@@ -120,9 +127,9 @@ export function ReportRow({ report: serverReport }: Props) {
 - 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
-  `queue: 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
+  `queue: false`, the agent simply yields when someone already holds the row.
+- The `update` made while the claim is held is stale-checked automatically, so an
   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.
+- That same write carries the claim, so each accepted change is attributed to the
+  run that made it.