@abloatai/ablo 0.5.0 → 0.6.0

package/docs/examples/existing-python-backend.md

@@ -9,7 +9,7 @@ that need multiplayer now and agent-safe writes later.
 
 This also applies to any API-backed app, not only Python. A product like a YC
 company's existing dashboard can keep its current endpoint/service/database
-shape and migrate one coordinated resource at a time.
+shape and migrate one coordinated model at a time.
 
 ```txt
 Browser UI
@@ -30,10 +30,10 @@ Create a schema for the records that need realtime coordination.
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
-  tasks: model({
+  weatherReports: model({
     id: z.string(),
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
     updatedAt: z.string(),
   }),
 });
@@ -51,7 +51,7 @@ export const ablo = Ablo({
 ```
 
 Mount the React provider near the app root so client components can subscribe to
-model resources without importing server credentials.
+model clients without importing server credentials.
 
 ```tsx
 // web/app/providers.tsx
@@ -68,30 +68,32 @@ export function Providers({ children }: { children: React.ReactNode }) {
 ## 2. Add Live Reads In The UI
 
 Keep the first render backed by the existing Python endpoint. After that,
-subscribe to the same model resource Ablo writes through.
+subscribe to the same model client Ablo writes through.
 
 ```tsx
 'use client';
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskRow({ task: serverTask }: { task: Task }) {
-  const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
-  const intents = useAblo((ablo) =>
-    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
-  ) ?? [];
-  const busy = intents.length > 0;
+export function ReportRow({
+  report: serverReport,
+}: {
+  report: { id: string; location: string; status: string };
+}) {
+  const report = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const claimed = Boolean(active);
 
   return (
-    <button disabled={busy || task.status === 'done'}>
-      {busy ? 'Someone is editing' : task.title}
+    <button disabled={claimed || report.status === 'ready'}>
+      {claimed ? 'Someone is editing' : report.location}
     </button>
   );
 }
 ```
 
 No string model key is needed in the first example. The selector reads from
-`ablo.tasks`, so React uses the same model resource as writes and agents.
+`ablo.weatherReports`, so React uses the same model client as writes and agents.
 
 ## 3. Add One Python Data Source Endpoint
 
@@ -120,7 +122,7 @@ import os
 import time
 from fastapi import APIRouter, HTTPException, Request
 
-from app.services.tasks import get_task, list_tasks, apply_task_operations
+from app.services.reports import get_report, list_reports, apply_report_operations
 
 router = APIRouter()
 
@@ -160,15 +162,15 @@ async def ablo_source(request: Request):
     body = json.loads(raw_body)
 
     if body["type"] == "load":
-        if body["model"] == "tasks":
-            return {"row": await get_task(body["id"])}
+        if body["model"] == "weatherReports":
+            return {"row": await get_report(body["id"])}
 
     if body["type"] == "list":
-        if body["model"] == "tasks":
-            return {"rows": await list_tasks(body.get("query", {}))}
+        if body["model"] == "weatherReports":
+            return {"rows": await list_reports(body.get("query", {}))}
 
     if body["type"] == "commit":
-        rows = await apply_task_operations(
+        rows = await apply_report_operations(
             operations=body["operations"],
             client_tx_id=body.get("clientTxId"),
             scope=body.get("scope", {}),
@@ -178,7 +180,7 @@ async def ablo_source(request: Request):
     raise HTTPException(status_code=400, detail="unsupported request")
 ```
 
-`apply_task_operations` should reuse the same transaction and validation logic
+`apply_report_operations` should reuse the same transaction and validation logic
 the existing Python endpoints already use. Dedupe by `clientTxId` so retries are
 safe.
 
@@ -193,20 +195,20 @@ Button -> Python endpoint -> service -> database
 Target button path:
 
 ```txt
-Button -> ablo.tasks.update(...)
+Button -> ablo.weatherReports.update(...)
 Ablo -> Python Data Source endpoint
 Python service -> database
 Ablo -> realtime fanout and receipt
 ```
 
-The app does not need a flag-day rewrite. Move one resource at a time.
+The app does not need a flag-day rewrite. Move one model at a time.
 
 ```ts
-const snap = ablo.snapshot({ tasks: taskId });
+const snap = ablo.snapshot({ weatherReports: reportId });
 
-await ablo.tasks.update(
-  taskId,
-  { status: 'done' },
+await ablo.weatherReports.update(
+  reportId,
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```
@@ -235,12 +237,12 @@ and timestamp. If the change originated from an Ablo commit, include the same
 Agents use the same model API as the UI:
 
 ```ts
-const [task] = await ablo.tasks.load({ where: { id: taskId } });
-const snap = ablo.snapshot({ tasks: taskId });
+const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+const snap = ablo.snapshot({ weatherReports: reportId });
 
-await ablo.tasks.update(
-  taskId,
-  { status: 'done' },
+await ablo.weatherReports.update(
+  reportId,
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```

package/docs/examples/nextjs.md

@@ -7,11 +7,11 @@ Server Components, and live client subscriptions.
 
 ```txt
 app/
-  tasks/
+  reports/
     [id]/
       page.tsx          # RSC: retrieve + render
       actions.ts        # Server Action: schema update with stale-state check
-      TaskEditor.tsx    # Client: live updates
+      ReportEditor.tsx    # Client: live updates
   lib/
     ablo.ts             # Schema-backed Ablo client for server actions
 ```
@@ -19,40 +19,41 @@ app/
 ## RSC Initial Render
 
 ```tsx
-// app/tasks/[id]/page.tsx
+// app/reports/[id]/page.tsx
 import { ablo } from '@/lib/ablo';
 
-export default async function TaskPage({
+export default async function ReportPage({
   params,
 }: { params: { id: string } }) {
   await ablo.ready();
-  const [task] = await ablo.tasks.load({ where: { id: params.id } });
-  if (!task) return null;
+  const [report] = await ablo.weatherReports.load({ where: { id: params.id } });
+  if (!report) return null;
 
-  return <TaskEditor task={task} />;
+  return <ReportEditor report={report} />;
 }
 ```
 
 ## Server Action Commit
 
 ```ts
-// app/tasks/[id]/actions.ts
+// app/reports/[id]/actions.ts
 'use server';
 
 import { ablo } from '@/lib/ablo';
 
-export async function markDone(id: string) {
-  const busy = ablo.intents.list({ resource: 'tasks', id });
-  if (busy.length > 0) return { status: 'busy', intents: busy };
-
-  const snap = ablo.snapshot({ tasks: id });
-  const task = await ablo.tasks.update(
+export async function markReady(id: string) {
+  const report = await ablo.weatherReports.claim(
     id,
-    { status: 'done' },
-    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+    async (claimed) =>
+      ablo.weatherReports.update(
+        claimed.id,
+        { status: 'ready' },
+        { wait: 'confirmed' },
+      ),
+    { wait: false, action: 'marking_ready' },
   );
 
-  return { status: 'done', task };
+  return { status: 'ready', report };
 }
 ```
 
@@ -66,16 +67,14 @@ rejects. The action can re-fetch and ask the user to retry.
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskEditor({ 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 busy = intents.length > 0;
+export function ReportEditor({ report: serverReport }: Props) {
+  const data = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const claimed = Boolean(active);
 
   return (
-    <button disabled={busy || data.status === 'done'}>
-      {busy ? 'Someone is editing' : 'Mark done'}
+    <button disabled={claimed || data.status === 'ready'}>
+      {claimed ? 'Someone is editing' : 'Mark ready'}
     </button>
   );
 }

package/docs/examples/server-agent.md

@@ -8,10 +8,10 @@ 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']),
-    summary: z.string().optional(),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
   }),
 });
 
@@ -20,67 +20,26 @@ const ablo = Ablo({
   apiKey: process.env.ABLO_API_KEY,
 });
 
-export async function completeTask(taskId: string) {
+export async function completeReport(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: 'completing' },
   );
 
-  return { status: 'done', task: updated };
+  return { status: 'ready', report: updated };
 }
 ```
 
-## Advanced Schema-Less Run
-
-Use `agent.run(...)` when the worker intentionally cannot import the app schema.
-It creates the run envelope and returns `done`, `failed`, or `cancelled`.
-
-```ts
-const api = Ablo({ apiKey: process.env.ABLO_API_KEY });
-
-const result = await api.agent('task-writer', {
-  can: ['tasks.retrieve', 'tasks.update'],
-  syncGroups: ['workspace:acme'],
-}).run(
-  {
-    prompt: 'Mark task_123 done.',
-    surface: 'agent_worker',
-  },
-  async ({ resource }) => {
-    const tasks = resource<{ title: string; status: string }>('tasks');
-
-    const { data, stamp, intents } = await tasks.retrieve('task_123', {
-      ifBusy: 'return',
-    });
-
-    if (intents.length > 0) {
-      return { skipped: true, reason: 'busy' };
-    }
-
-    return tasks.update(
-      'task_123',
-      { status: 'done' },
-      { readAt: stamp, onStale: 'reject', wait: 'confirmed' },
-    );
-  },
-);
-
-if (result.status === 'failed') throw result.error;
-if (result.status === 'cancelled') return;
-```
-
-Use the schema-backed version first. The schema-less version is for generic
-agent infrastructure, MCP routes, and platform code.
-
+Use the schema-backed version for server agents so the worker, app, and React UI
+share the same model methods.

package/docs/guarantees.md

@@ -1,6 +1,6 @@
 # Guarantees
 
-This page is the short contract for what Ablo Sync guarantees at the state
+This page is the short contract for what Ablo guarantees at the state
 boundary.
 
 ## Confirmed Writes
@@ -9,19 +9,18 @@ boundary.
 the authoritative sync cursor.
 
 ```ts
-const updated = await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+const updated = await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { wait: 'confirmed' },
 );
 ```
 
 If the call resolves, the write was accepted by the server. If it rejects, the
 error explains whether the write was rejected for auth, validation, stale state,
-active intent conflict, idempotency, rate limit, or transport failure.
+active claim conflict, idempotency, rate limit, or transport failure.
 
-Schema model writes return the updated model row. Advanced resource writes and
-`commits.create(...)` return a receipt with the commit status and sync cursor.
+Schema model writes return the updated model row.
 
 ## Optimistic Local State
 
@@ -42,11 +41,11 @@ Use `snapshot(...)` and `readAt` when a write depends on state the agent already
 read:
 
 ```ts
-const snap = ablo.snapshot({ tasks: 'task_123' });
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```
@@ -61,45 +60,27 @@ Advanced policies exist for controlled product flows:
 - `flag` accepts the write and marks it for product review.
 - `merge` is reserved for server-defined merge behavior.
 
-## Intent Coordination
+## Claim Coordination
 
-Intents are live coordination signals. They are not database locks.
+Claims are live coordination signals. They are not database locks.
 
-When another human or agent is active on the same target, the caller chooses the
-behavior:
+Claims are **advisory** and **cooperative**. `ablo.<model>.claim(id, ...)`
+serializes on contention: if another human or agent already holds the row, the
+claim waits for them to finish, then re-reads the row before handing it back, so
+you proceed from fresh state. Reads are open by default —
+`ablo.<model>.claimState(id)` returns the current claim state (or `null`) without
+ever blocking. Server/model reads can opt into `ifClaimed: 'wait'` or
+`ifClaimed: 'fail'` when they should not read through active work.
 
-- `ifBusy: 'return'` returns active intents immediately.
-- `ifBusy: 'wait'` waits until the matching intent clears.
-- `ifBusy: 'fail'` throws `AbloBusyError` with the active intents attached.
-
-Schema clients wait from the realtime intent stream. Schema-less HTTP callers
-must pass an explicit `busyPollInterval` if they choose `ifBusy: 'wait'`; Ablo
-does not hide a hard-coded polling loop. `busyTimeout` is only a maximum wait.
+A claim does not reject or block other writers; it announces work so peers
+serialize behind it rather than racing. While you hold a claim, the matching
+`ablo.<model>.update(id, ...)` is stale-guarded and rejects with
+`AbloStaleContextError` if the row advanced past your claim point.
 
 ## Agent Runs
 
-`agent.run(...)` is the advanced schema-less run envelope for workers that cannot
-import the app schema. It returns one of three statuses:
-
-- `done` — the handler returned successfully.
-- `failed` — the handler threw or the commit failed.
-- `cancelled` — the run signal aborted.
-
-Normal schema-backed agents should import the same schema as the app and write
-through `ablo.<model>.update(...)`. The lower-level run envelope exists for
-platform runtimes that need capability and task management without app code.
-
-## Capabilities and Tasks
-
-Capabilities scope what an agent is allowed to do. Tasks group a run for audit
-and cost attribution.
-
-Most users do not create either one manually. The SDK and hosted API manage the
-common case. Manual capability and task APIs are for platform builders, custom
-agent runtimes, and internal infrastructure.
-
-Use `lease` as a crash cleanup window. A successful agent run still closes when
-the handler returns, fails, or is cancelled.
+Agents should import the same schema as the app and write through
+`ablo.<model>.claim(...)` plus `ablo.<model>.update(...)`.
 
 ## Audit Trail
 
@@ -107,9 +88,7 @@ Accepted writes can be attributed to:
 
 - the actor that wrote,
 - the human or system the actor worked on behalf of,
-- the capability that scoped the write,
-- the task or run that caused it,
-- the resource, operation, and state cursor.
+- the model, operation, and state cursor.
 
 For agent work, this is what lets an audit surface answer: "what changed, who
 authorized it, which run did it, and what state was it based on?"
@@ -137,12 +116,8 @@ Ablo does not need a customer database URL. When your own database is canonical,
 Ablo calls a signed Data Source endpoint and records the coordination result for
 receipts, realtime fanout, and audit. See [Connect Your Database](./data-sources.md).
 
-## Batches
-
-Most apps should use `ablo.<model>.create/update/delete`. Use
-`commits.create(...)` only when you need a low-level batch or a schema-less
-runtime.
+## Writes
 
-Each operation in the commit carries its own target, data, stale policy, and
-idempotency context. The server validates authorization, stale state, active
-intent conflicts, and idempotency before accepting the commit.
+Use `ablo.<model>.create/update/delete` for state changes. The server validates
+authorization, stale state, active claim conflicts, and idempotency before
+accepting the write.