@abloatai/ablo 0.5.1 → 0.6.0

package/docs/coordination.md

@@ -0,0 +1,294 @@
+# Coordination Reference
+
+Coordinate long-running work on a row so humans and agents don't clobber each
+other. Most writes need none of this — `ablo.<model>.update(id, …)` is optimistic
+and the server rejects it if the row moved. Reach for `claim` only when you'll
+**hold a row across a slow gap** (read → LLM call → write).
+
+Claims are **fair**: on contention a second claimer joins a **server-side FIFO
+queue** and blocks until promoted to the head of the line — it does not fail and
+does not poll. Reads are open by default; reading a claimed row is allowed unless
+the caller explicitly asks for claimed gating. A claim carries a TTL so a crashed
+holder is auto-released and the queue advances.
+
+This reference has three sections: the [claim state object](#the-claim-state-object),
+the SDK [methods](#methods) (`claim` · `claimState` · `queue` · `release` ·
+[writing under a claim](#writing-under-a-claim)), and the [errors](#errors) you
+can catch.
+
+---
+
+## The claim state object
+
+The claim state object is the live record that a participant is coordinating work on
+a model row. It's what `claimState()` returns and what observers render.
+
+| 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. |
+| `target` | `EntityRef` | What is being coordinated (`{ model, id, field? }`). |
+| `action` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
+| `participantKind` | `'human' \| 'agent'` | Who's behind it. |
+| `position` | `number?` | 0-based place in the FIFO line — present only when `status: 'queued'` (`0` = next behind the holder). |
+| `createdAt` | `string?` | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
+| `expiresAt` | `string` | 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. |
+
+```jsonc
+// A live claim state, as returned by claimState():
+{
+  "id": "claim_8fJ2",
+  "status": "active",
+  "target": { "model": "weatherReports", "id": "report_stockholm" },
+  "action": "editing",
+  "heldBy": "agent:forecaster",
+  "participantKind": "agent",
+  "createdAt": "1748160000000",
+  "expiresAt": "1748160030000"
+}
+```
+
+---
+
+## Methods
+
+Each method below follows one fixed shape: **signature · what it does ·
+parameters · returns · example**.
+
+### `claim`
+
+```ts
+ablo.<model>.claim(id, work, options?): Promise<R>   // callback form
+ablo.<model>.claim(id, options?): Promise<ClaimedRow<T>>
+```
+
+Claim a row so other writers serialize behind you until you're done; reads stay
+open by default. The claim acquires through the server's fair FIFO queue: if the
+target is free the lease is yours immediately, and if another participant holds
+it your claim **waits in line** and resolves only once it reaches the head —
+then re-reads so the claimed snapshot reflects what the previous holder
+committed. There's no client-side poll and no TOCTOU gap: the server orders
+contenders.
+
+**Parameters**
+
+| name | type | required | description |
+|---|---|---|---|
+| `id` | `string` | yes | The row id — same id as `retrieve` / `update`. |
+| `options.action` | `string` | no | Phase shown to observers (default `'editing'`). |
+| `options.field` | `string` | no | Field-level target, for fine-grained claimed-state badges. |
+| `options.wait` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
+| `options.maxQueueDepth` | `number` | no | Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of joining a line already `>= maxQueueDepth` deep. Omit to wait however deep the queue is. |
+| `options.ttl` | `Duration` | no | Crash-cleanup floor. Rarely set — the lease renews while your connection is alive, so it only matters once you go silent. |
+| `work` | `(row) => …` | no | Callback form: hold the claim for the callback, release when it returns. |
+
+The high-level `claim` queues by default, so on contention you either get the row
+when your turn arrives or one of the [queue errors](#errors) (`claim_lost`,
+`grant_timeout`).
+
+**Returns** — with the callback form, returns whatever `work` returns and
+releases after the callback returns or throws. The manual form returns the
+claimed row (`ClaimedRow<T> = T & AsyncDisposable`): the row data plus a
+release hook for manual scopes.
+
+**Example**
+
+```ts
+// Callback form — works on any toolchain:
+const forecast = await ablo.weatherReports.claim('report_stockholm', async (report) => {
+  const weather = await weatherAgent.getWeather(report.location);
+  await ablo.weatherReports.update(report.id, { forecast: weather });
+  return weather;
+});
+```
+
+The manual scoped form is still available for wider TS 5.2+ scopes, but ordinary
+held work should use the callback form above.
+
+### Claim-gated reads
+
+`claimState(id)` always returns immediately. Model reads such as
+`ablo.<model>.retrieve(id)` are local reads and stay available while a claim is
+held. Server/model reads can choose a claimed policy:
+
+```ts
+await ablo.model('weatherReports').retrieve('report_stockholm', {
+  ifClaimed: 'wait',       // wait until the active claim clears
+  claimedTimeout: 30_000,  // maximum wait
+});
+```
+
+- `ifClaimed: 'return'` reads now and includes active work metadata.
+- `ifClaimed: 'wait'` waits for the active claim to clear before reading.
+- `ifClaimed: 'fail'` throws `AbloClaimedError` if the row is claimed.
+
+### `claimState`
+
+```ts
+ablo.<model>.claimState(id)
+```
+
+Read who's currently working on a row, for observers and UI. Synchronous and
+reactive (it reads the local coordination snapshot). Never blocks.
+
+**Parameters**
+
+| name | type | required | description |
+|---|---|---|---|
+| `id` | `string` | yes | The row id. |
+
+**Returns** — the active [claim state object](#the-claim-state-object), or `null` when the row
+is free.
+
+**Example**
+
+```ts
+const who = ablo.weatherReports.claimState('report_stockholm');
+if (who) console.log(`${who.heldBy} is ${who.action}`); // 'agent:forecaster is editing'
+```
+
+```jsonc
+// Resolved value when the row is held:
+{
+  "id": "claim_8fJ2",
+  "status": "active",
+  "target": { "model": "weatherReports", "id": "report_stockholm" },
+  "action": "editing",
+  "heldBy": "agent:forecaster",
+  "participantKind": "agent",
+  "expiresAt": "1748160030000"
+}
+// → null when free.
+```
+
+### `queue`
+
+```ts
+ablo.<model>.queue(id)
+```
+
+Read the **wait line** behind a row — the FIFO of claims queued behind the
+current holder, in promotion order. Like `claimState`, it's synchronous and
+reactive (it reads the local coordination snapshot, kept current by the server's
+queue-mutation frames), and reading never blocks. Where `claimState` answers "who
+holds it," `queue` answers "who's lined up next" — render "3rd in line", or
+decide the wait isn't worth it.
+
+**Parameters**
+
+| name | type | required | description |
+|---|---|---|---|
+| `id` | `string` | yes | The row id. |
+
+**Returns** — a list envelope. `data` contains the queued
+[claim state objects](#the-claim-state-object) in promotion order (head first), excluding
+the active holder; `[]` when no one is waiting.
+
+**Example**
+
+```ts
+const { data: waiting } = ablo.weatherReports.queue('report_stockholm');
+console.log(`${waiting.length} ahead of you`);
+console.log(waiting.map((i) => i.heldBy)); // ['agent:b', 'agent:c']
+```
+
+### `release`
+
+```ts
+ablo.<model>.release(id): Promise<void>
+```
+
+Release a claim you hold. Usually **implicit** — the callback returning releases
+for you, and TTL cleans up a crashed holder.
+Call this only to give a manually held claim back early (claimed, then decided
+not to write).
+Releasing **promotes the head of the queue**: the next waiter receives the claim.
+
+**Parameters**
+
+| name | type | required | description |
+|---|---|---|---|
+| `id` | `string` | yes | The row id you hold a claim on. No-op if you don't hold it. |
+
+**Returns** — resolves once the claim is released.
+
+**Example**
+
+```ts
+const report = await ablo.weatherReports.claim('report_stockholm', { action: 'reviewing' });
+try {
+  const ok = await reviewExternally(report);
+  if (!ok) return; // abandon, no write
+  await ablo.weatherReports.update(report.id, { status: 'ready' });
+} finally {
+  await ablo.weatherReports.release(report.id);
+}
+```
+
+### Writing under a claim
+
+There is no separate "write" method on a claim — use the normal flat
+`ablo.<model>.update(id, data)`. While you hold a claim on `id`, that `update` is
+automatically stale-guarded against the snapshot the claim took (`readAt` =
+snapshot watermark, `onStale: 'reject'`) and attributed to the claim's lease, so
+it rejects with [`AbloStaleContextError`](#errors) if the row changed under you.
+
+```ts
+await ablo.weatherReports.claim(id, async (report) => {
+  await ablo.weatherReports.update(report.id, { status: 'ready' }); // guarded by the claim
+});
+```
+
+Claims are **enforced server-side**: if you `update`/`delete` a row that *another*
+participant holds, the commit is rejected with [`AbloClaimedError`](#errors) (`code:
+'entity_claimed'`). To proceed, `claim` the row yourself — the claim queues
+behind the current holder and re-reads once it's yours, so your `update` lands
+on fresh data. You never conflict with your own claim, and reads are never gated.
+
+```ts
+try {
+  await ablo.weatherReports.update(id, { status: 'ready' });
+} catch (err) {
+  if (err instanceof AbloClaimedError) {
+    // someone else holds it — claim the row and retry from fresh state
+  }
+}
+```
+
+---
+
+## Errors
+
+All extend `AbloError` (`packages/sync-engine/src/errors.ts`). Catch by `type` or
+inspect the `code`.
+
+| error | `code` | thrown when | carries |
+|---|---|---|---|
+| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away (holder TTL lapse on disconnect, or revoke) while you were holding or waiting. | `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 without collaboration wiring. | — |
+| `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.
+
+```ts
+try {
+  await ablo.weatherReports.claim('report_stockholm', async (report) => {
+    const weather = await weatherAgent.getWeather(report.location); // slow gap
+    await ablo.weatherReports.update(report.id, { forecast: weather });
+  });
+} catch (err) {
+  if (err instanceof AbloClaimedError && err.code === 'claim_lost') {
+    // Our lease lapsed mid-flight (we stalled past the TTL). Re-claim and retry.
+  } else if (err instanceof AbloStaleContextError) {
+    // The row moved under us — re-read and regenerate from the fresh snapshot.
+  } else throw err;
+}
+```

package/docs/data-sources.md

@@ -8,7 +8,7 @@ the SDK, agents, realtime subscriptions, and the Data Source endpoint. Use
 `schema.prisma`.
 
 By default, Ablo stores the rows for the models you declare. That makes Ablo the
-managed state store for those resources, the same way Stripe stores `Customer`
+managed state store for those models, the same way Stripe stores `Customer`
 and `PaymentIntent` objects that you create through Stripe's API.
 
 If you already have application tables and want those tables to remain
@@ -54,9 +54,9 @@ ABLO_API_KEY=sk_live_...
 The SDK call is the same in both modes:
 
 ```ts
-await ablo.tasks.create({ title: 'Draft launch plan', status: 'todo' });
-await ablo.tasks.update('task_123', { status: 'done' });
-const task = ablo.tasks.retrieve('task_123');
+await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
+await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
+const report = ablo.weatherReports.retrieve('report_stockholm');
 ```
 
 Only the backing store changes.
@@ -120,13 +120,13 @@ export const POST = dataSource({
     return { rows };
   },
 
-  tasks: {
+  reports: {
     async load({ id, context }) {
-      return context.auth.db.task.findUnique({ where: { id } });
+      return context.auth.db.report.findUnique({ where: { id } });
     },
 
     async list({ query, context }) {
-      return context.auth.db.task.findMany({
+      return context.auth.db.report.findMany({
         take: query.limit ?? 100,
       });
     },
@@ -137,9 +137,9 @@ export const POST = dataSource({
 Your app code still writes through the normal model API:
 
 ```ts
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { wait: 'confirmed', readAt: snap.stamp, onStale: 'reject' },
 );
 ```
@@ -155,9 +155,9 @@ When Ablo calls your Data Source, it sends a signed JSON request:
   operations: [
     {
       type: 'UPDATE',
-      model: 'tasks',
-      id: 'task_123',
-      input: { status: 'done' },
+      model: 'weatherReports',
+      id: 'report_stockholm',
+      input: { status: 'ready' },
       readAt: 1042,
       onStale: 'reject',
     },
@@ -177,7 +177,7 @@ Return canonical rows:
 ```ts
 {
   rows: [
-    { id: 'task_123', title: 'Fix docs', status: 'done' },
+    { id: 'report_stockholm', location: 'Stockholm', status: 'ready' },
   ],
 }
 ```

package/docs/examples/agent-human.md

@@ -1,57 +1,57 @@
 # Agent + Human
 
-A task-writing agent that yields when a human is editing the same task.
+A report-writing agent that yields when a human is editing the same report.
 
 ## Scenario
 
-A product queue has tasks that humans and agents both update. They must not
+A product queue has reports that humans and agents both update. They must not
 collide:
 
 - If the user is editing, the agent waits or yields.
 - If the agent is updating, the UI can show who is active.
-- If the task changes mid-run, the commit rejects instead of overwriting newer
+- If the report changes mid-run, the commit rejects instead of overwriting newer
   state.
 
 ## Schema-Backed Worker
 
-Use the same schema client the app uses. The worker loads the task, checks active
-intents, and writes through `ablo.tasks.update(...)`.
+Use the same schema client the app uses. The worker loads the report, claims the
+row, and writes through `ablo.weatherReports.update(...)`.
 
 ```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
   }),
 });
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-export async function markDone(taskId: string) {
+export async function markReady(reportId: string) {
   await ablo.ready();
 
-  const [task] = await ablo.tasks.load({ where: { id: taskId } });
-  if (!task) return { status: 'not_found' };
-
-  const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
-  if (busy.length > 0) return { status: 'busy', intents: busy };
-
-  const snap = ablo.snapshot({ tasks: taskId });
-  const updated = await ablo.tasks.update(
-    taskId,
-    { status: 'done' },
-    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+  if (!report) return { status: 'not_found' };
+
+  const updated = await ablo.weatherReports.claim(
+    reportId,
+    async (claimed) =>
+      ablo.weatherReports.update(
+        claimed.id,
+        { status: 'ready' },
+        { wait: 'confirmed' },
+      ),
+    { wait: false, action: 'marking_ready' },
   );
 
-  return { status: 'done', task: updated };
+  return { status: 'ready', report: updated };
 }
 ```
 
-Advanced schema-less workers can use `Ablo({ apiKey }).agent(...)`, but that is
-not the first integration path.
+Keep workers on the same schema-backed client as the app.
 
 ## UI
 
@@ -60,16 +60,14 @@ not the first integration path.
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskRow({ task: serverTask }: Props) {
-  const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
-  const intents = useAblo((ablo) =>
-    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
-  ) ?? [];
-  const agentActive = intents.some((i) => i.participantKind === 'agent');
+export function ReportRow({ report: serverReport }: Props) {
+  const data = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const agentActive = active?.participantKind === 'agent';
 
   return (
     <div>
-      <span>{data.title}</span>
+      <span>{data.location}</span>
       {agentActive ? <span>Agent is updating...</span> : null}
     </div>
   );
@@ -78,7 +76,7 @@ export function TaskRow({ task: serverTask }: Props) {
 
 ## Why It Works
 
-- Intents are visible on read and over the live stream.
-- `ifBusy: 'wait'` lets agents wait for active work instead of racing.
+- Claims are visible through `claimState(id)` and over the live stream.
+- `claim(id, work)` lets agents wait for active work instead of racing.
 - `readAt` plus `onStale: 'reject'` turns mid-flight changes into typed errors.
 - Audit rows tie each accepted write back to the run that caused it.

package/docs/examples/ai-sdk-tool.md

@@ -9,10 +9,10 @@ import { streamText, tool } from 'ai';
 import { z } from 'zod';
 
 const schema = defineSchema({
-  tasks: model({
-    title: schemaZ.string(),
-    status: schemaZ.enum(['todo', 'doing', 'done']),
-    summary: schemaZ.string().optional(),
+  weatherReports: model({
+    location: schemaZ.string(),
+    status: schemaZ.enum(['pending', 'ready']),
+    forecast: schemaZ.string().optional(),
   }),
 });
 
@@ -21,35 +21,35 @@ const ablo = Ablo({
   apiKey: process.env.ABLO_API_KEY,
 });
 
-const updateTask = tool({
-  description: 'Update a task in the product database.',
+const updateReport = tool({
+  description: 'Update a weather report in the product database.',
   inputSchema: z.object({
-    taskId: z.string(),
-    status: z.enum(['todo', 'doing', 'done']).optional(),
-    summary: z.string().optional(),
+    reportId: z.string(),
+    status: z.enum(['pending', 'ready']).optional(),
+    forecast: z.string().optional(),
   }),
-  execute: async ({ taskId, status, summary }) => {
+  execute: async ({ reportId, status, forecast }) => {
     await ablo.ready();
 
-    const [task] = await ablo.tasks.load({ where: { id: taskId } });
-    if (!task) return { ok: false, reason: 'not_found' };
+    const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+    if (!report) return { ok: false, reason: 'not_found' };
 
-    const claim = ablo.tasks.intent(taskId);
-    if (claim.current) await claim.whenFree({ timeout: 30_000 });
+    // claim is advisory: if another participant holds the row, it waits for
+    // them to finish and re-reads before entering the callback. Released when
+    // the callback returns or throws.
+    return ablo.weatherReports.claim(
+      reportId,
+      async (claimed) => {
+        // update is stale-guarded under the held claim
+        const updated = await ablo.weatherReports.update(claimed.id, {
+          status: status ?? claimed.status,
+          forecast: forecast ?? claimed.forecast,
+        });
 
-    await claim.claim({ action: 'editing', field: 'status', ttl: '2m' });
-    try {
-      // update commits with the held claim and auto-releases on success
-      const updated = await claim.update({
-        status: status ?? task.status,
-        summary: summary ?? task.summary,
-      });
-
-      return { ok: true, task: updated };
-    } catch (err) {
-      await claim.finish();
-      throw err;
-    }
+        return { ok: true, report: updated };
+      },
+      { action: 'editing', ttl: '2m' },
+    );
   },
 });
 
@@ -59,7 +59,7 @@ export async function POST(req: Request) {
   return streamText({
     model,
     messages,
-    tools: { updateTask },
+    tools: { updateReport },
   }).toUIMessageStreamResponse();
 }
 ```
@@ -67,9 +67,8 @@ export async function POST(req: Request) {
 The important part is not the model provider. The important part is that the
 tool:
 
-- loads the latest task,
-- waits if another participant already holds the row,
-- acquires a claim before writing,
-- writes and auto-releases through the same handle,
+- loads the latest weather report,
+- claims the row (advisory — serializes behind any current holder, then re-reads),
+- writes through the normal stale-guarded `update`,
+- releases the claim automatically when the callback returns or throws,
 - waits for server confirmation.
-