@abloatai/ablo 0.7.0 → 0.8.0

package/docs/examples/agent-human.md

@@ -4,21 +4,29 @@ A report-writing agent that yields when a human is editing the same report.
 
 ## Scenario
 
-A product queue has reports that humans and agents both update. They must not
-collide:
+The same reports are edited by both humans and agents. 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 report changes mid-run, the commit rejects instead of overwriting newer
-  state.
+- If a human 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.
+
+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 to you, so two
+writers serialize instead of clobbering. And once you hold a claim, any `update`
+you make inside it is stale-checked for free: the SDK records the row version you
+were handed and rejects the write with a typed error if the row moved underneath
+you while the agent was busy.
 
 ## Schema-Backed Worker
 
-Use the same schema client the app uses. The worker loads the report, claims the
-row, and writes through `ablo.weatherReports.update(...)`.
+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.
 
 ```ts
-import Ablo from '@abloatai/ablo';
+import Ablo, { AbloClaimedError, AbloStaleContextError } from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
@@ -33,21 +41,52 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 export async function markReady(reportId: string) {
   await ablo.ready();
 
-  const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+  // retrieve(id) is an async server read — await it.
+  const report = await ablo.weatherReports.retrieve(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: 'ready', report: updated };
+  try {
+    const updated = await ablo.weatherReports.claim(
+      reportId,
+      async (claimed) =>
+        // 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(claimed.id, { status: 'ready' }, {
+        //     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.
+        ablo.weatherReports.update(
+          claimed.id,
+          { status: 'ready' },
+          { wait: 'confirmed' },
+        ),
+      {
+        // wait: false → don't queue behind a current holder. If a human already
+        // holds the row, claim rejects with AbloClaimedError (caught below), so
+        // the agent yields instead of waiting. Omit it, or pass wait: true, to
+        // queue behind them. action → the label observers see while we work.
+        wait: false,
+        action: 'marking_ready',
+      },
+    );
+
+    return { status: 'ready', report: updated };
+  } catch (err) {
+    // A human 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
+    // rejected our commit, so nothing was overwritten — re-run on fresh data.
+    if (err instanceof AbloStaleContextError) return { status: 'stale' };
+    throw err;
+  }
 }
 ```
 
@@ -61,8 +100,8 @@ 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.retrieve(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const data = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state(serverReport.id));
   const agentActive = active?.participantKind === 'agent';
 
   return (
@@ -76,7 +115,12 @@ export function ReportRow({ report: serverReport }: Props) {
 
 ## Why It Works
 
-- 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.
+- 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, work)` makes writers take turns instead of racing — with
+  `wait: false`, the agent simply yields when a human already holds the row.
+- The `update` inside the claim is stale-checked automatically, so a human's
+  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.

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

@@ -1,6 +1,8 @@
 # AI SDK Tool
 
-Use AI SDK for the loop and Ablo for the state boundary inside the tool.
+When an AI agent updates a shared record from inside a tool call, you have a concurrency problem: another agent or a user might be editing the same row, and a naive write silently overwrites their change. This example shows the safe pattern — read the record, claim the row so anyone else waits their turn, write through a version-checked update, and release the claim automatically.
+
+Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -31,16 +33,18 @@ const updateReport = tool({
   execute: async ({ reportId, status, forecast }) => {
     await ablo.ready();
 
-    const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+    // retrieve hits the server for the latest row (async — await it).
+    const report = await ablo.weatherReports.retrieve(reportId);
     if (!report) return { ok: false, reason: 'not_found' };
 
-    // 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.
+    // If another agent or user already holds this row, claim waits for them
+    // to finish, re-reads the fresh row, then runs the callback. The claim
+    // is released when the callback returns or throws.
     return ablo.weatherReports.claim(
       reportId,
       async (claimed) => {
-        // update is stale-guarded under the held claim
+        // Because you hold the claim, this update is rejected if the row
+        // changed underneath you, instead of silently overwriting it.
         const updated = await ablo.weatherReports.update(claimed.id, {
           status: status ?? claimed.status,
           forecast: forecast ?? claimed.forecast,
@@ -64,11 +68,10 @@ export async function POST(req: Request) {
 }
 ```
 
-The important part is not the model provider. The important part is that the
-tool:
+The model provider is interchangeable. What matters is that the tool:
 
-- loads the latest weather report,
-- claims the row (advisory — serializes behind any current holder, then re-reads),
-- writes through the normal stale-guarded `update`,
+- reads the latest weather report with `retrieve` (a server read),
+- claims the row — if someone else holds it, the claim waits for them, then re-reads,
+- writes through `update`, which is rejected if the row changed underneath you,
 - releases the claim automatically when the callback returns or throws,
 - waits for server confirmation.

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

@@ -1,15 +1,21 @@
 # Existing Python Backend
 
-Use this path when a product already has a Python API server and every button
-currently calls an application endpoint.
+Put Ablo in front of the records several people (or AI agents) edit at once and
+you get two things at no cost to your stack: every edit fans out live to
+everyone watching, and humans and agents write through one shared contract. Your
+Python service and database stay the source of truth — Ablo doesn't replace your
+backend, it coordinates the writes into it. You stop calling your endpoint
+directly; you call Ablo, Ablo calls your endpoint, and Ablo pushes the result
+back out to every browser and agent on that record.
 
-The goal is not to replace the backend. Keep the Python service layer and
-database as the source of truth. Add Ablo as the shared write path for records
-that need multiplayer now and agent-safe writes later.
+Use this path when a product already has a Python API server and every button
+currently calls an application endpoint. It applies to any API-backed app, not
+only Python — a YC company's existing dashboard can keep its current
+endpoint/service/database shape and migrate one coordinated model at a time.
 
-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 model at a time.
+Here is the full path a button takes. After your Python service commits the
+change, Ablo pushes it live to every other browser and agent watching that
+record (the "realtime fanout" step at the bottom):
 
 ```txt
 Browser UI
@@ -80,8 +86,8 @@ export function ReportRow({
 }: {
   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 report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state(serverReport.id));
   const claimed = Boolean(active);
 
   return (
@@ -92,8 +98,9 @@ export function ReportRow({
 }
 ```
 
-No string model key is needed in the first example. The selector reads from
-`ablo.weatherReports`, so React uses the same model client as writes and agents.
+No string model key is needed in the first example. Because the selector reads
+straight from `ablo.weatherReports`, your reads, your writes, and any agent all
+go through one client — so a live edit shows up here without extra wiring.
 
 ## 3. Add One Python Data Source Endpoint
 
@@ -214,7 +221,10 @@ await ablo.weatherReports.update(
 ```
 
 Use `readAt` and `onStale: 'reject'` for actions that depend on state the user
-or agent already saw.
+or agent already saw. If two people both click "mark ready" on a report one of
+them already finished, `onStale: 'reject'` makes the second write fail instead
+of silently clobbering — `readAt: snap.stamp` is the version the user actually
+saw, and the write is rejected if the row changed underneath them.
 
 ## 5. Report Direct Database Writes
 
@@ -237,7 +247,7 @@ and timestamp. If the change originated from an Ablo commit, include the same
 Agents use the same model API as the UI:
 
 ```ts
-const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+const report = await ablo.weatherReports.retrieve(reportId);
 const snap = ablo.snapshot({ weatherReports: reportId });
 
 await ablo.weatherReports.update(
@@ -247,5 +257,6 @@ await ablo.weatherReports.update(
 );
 ```
 
-That is the point of the migration: humans and agents share one write contract,
-while the Python backend remains the canonical business logic and database owner.
+Agents reach for the exact same calls the UI does — the same write contract
+stated at the top of this page. The Python backend keeps owning the business
+logic and the database; agents just become another safe writer in front of it.

package/docs/examples/nextjs.md

@@ -1,7 +1,19 @@
 # Next.js Example
 
-A production-shaped Next.js + Ablo Sync app. App Router, Server Actions, React
-Server Components, and live client subscriptions.
+Building collaborative state in a Next.js app means handling three things at
+once: a fast initial render from the server, writes that don't overwrite a
+teammate's change, and a UI that updates the moment data changes. This example
+wires all three with Ablo Sync. The key piece is `claim()` — commit a write
+through it and Ablo rejects the write if someone edited the same record since
+you read it, so you never silently clobber another person's work.
+
+Claims don't lock. If another writer holds the row, `claim` waits for them,
+re-reads the fresh row, then hands it to you — so two writers serialize instead
+of clobbering.
+
+The app uses three layers, mapped to three files: a React Server Component reads
+and renders, a Server Action claims and writes, and a client component shows
+live updates.
 
 ## Structure
 
@@ -10,7 +22,7 @@ app/
   reports/
     [id]/
       page.tsx          # RSC: retrieve + render
-      actions.ts        # Server Action: schema update with stale-state check
+      actions.ts        # Server Action: write that's rejected if someone else edited first
       ReportEditor.tsx    # Client: live updates
   lib/
     ablo.ts             # Schema-backed Ablo client for server actions
@@ -26,7 +38,7 @@ export default async function ReportPage({
   params,
 }: { params: { id: string } }) {
   await ablo.ready();
-  const [report] = await ablo.weatherReports.load({ where: { id: params.id } });
+  const report = await ablo.weatherReports.retrieve(params.id);
   if (!report) return null;
 
   return <ReportEditor report={report} />;
@@ -57,8 +69,9 @@ export async function markReady(id: string) {
 }
 ```
 
-If another participant commits between the read and the write, the commit
-rejects. The action can re-fetch and ask the user to retry.
+The write runs inside the `claim` callback. If another participant commits
+between the read and the write, the commit is rejected because the row changed
+underneath you. The action can re-fetch and ask the user to retry.
 
 ## Live Client
 
@@ -68,8 +81,8 @@ rejects. The action can re-fetch and ask the user to retry.
 import { useAblo } from '@abloatai/ablo/react';
 
 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 data = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state(serverReport.id));
   const claimed = Boolean(active);
 
   return (

package/docs/examples/scoped-agent.md

@@ -1,28 +1,32 @@
 # Agent Scoped to One Deck
 
-An agent that edits **one deck** and receives realtime updates for **only that
-deck** — not the whole org. Shows the sync-group model end to end: a scope root,
-a containment (`parent`) edge, identity roles, and the model-form `scope`.
+You want an agent that edits **one deck** and pushes realtime updates to the
+people on **that deck only** — not a broadcast to the whole org. The catch most
+people hit: which write reaches whom is decided by how the rows *relate*, not by
+which columns the write touched. So a slide edit that never sets `deckId` still
+reaches everyone viewing the deck, because the slide already belongs to it. You
+get this by declaring the relationship once, then narrowing the agent to the deck
+id — you never assemble a `deck:<id>` audience string by hand.
+
+The three steps below show how to declare it, scope the agent, and write.
 
 See [Identity & Sync Groups](../identity.md) for the full reference.
 
-## 1. Schema — declare the scope, once
+## 1. Schema — declare the relationship, once
 
 ```ts
 import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
-    // A scope root: deck rows form the group `deck:<id>`.
+    // A deck's rows form the group `deck:<id>` (the kind comes from `scope`).
     decks: model(
       { title: z.string() },
       {},
       { orgScoped: true, scope: 'deck' },
     ),
-    // A child: no group of its own. It inherits its deck's group via the
-    // `parent` edge, so a slide write reaches everyone viewing the deck —
-    // even a slide edit that doesn't touch `deckId` (routing is keyed on the
-    // row's id, not the changed columns).
+    // A slide has no group of its own. It inherits its deck's group via the
+    // `parent` edge, so a slide write reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string(), body: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
@@ -41,36 +45,47 @@ export const schema = defineSchema(
 
 ## 2. Dispatch — narrow the agent to the deck it's working on
 
-The agent inherits the triggering user's identity (its ceiling) and is narrowed
-to one deck (the floor). You pass the **model and id** — never a `deck:<id>`
-string; the engine builds the group from the model's `scope`.
+An agent can never reach more than the user who triggered it — that's the upper
+limit. From there you narrow it to a single deck with `scope`. You pass the
+**model and id** — `{ decks: deckId }`, never a `deck:<id>` string; the engine
+builds the group from the `decks` model's `scope`.
 
-```ts
-const ablo = Ablo({
-  schema,
-  url: process.env.ABLO_URL,
-  kind: 'agent',
-  agentId: 'agent:slide-writer',
-  userId: triggeringUser.id,     // ceiling: can't exceed this user's reach
-  organizationId: triggeringUser.organizationId,
-  scope: { decks: deckId },      // floor: just this deck → deck:<deckId>
-});
-await ablo.ready();
+```tsx
+import { AbloProvider } from '@abloatai/ablo/react';
+
+// The agent run is mounted on behalf of its triggering user.
+<AbloProvider
+  schema={schema}
+  userId={triggeringUser.id}   // ceiling: can't exceed this user's reach
+  scope={{ decks: deckId }}    // floor: narrowed to just this deck → deck:<deckId>
+>
+  {children}
+</AbloProvider>
 ```
 
+`scope` requests, it never grants: at connect the server intersects the groups
+you ask for with the groups the identity is actually allowed, so the agent can
+never reach a deck its triggering user couldn't.
+
 ## 3. Write — it fans out to everyone on that deck
 
+Inside any component under the provider, grab the scoped client with `useAblo()`
+and write. The connection is already narrowed to `deck:<deckId>` from Step 2.
+
 ```ts
+const ablo = useAblo<(typeof schema)['models']>();
+
 // Other participants subscribed to deck:<deckId> — the human in the editor,
 // a reviewer agent — receive this delta in realtime. Participants on other
 // decks never see it.
 await ablo.slides.update(slideId, { body: 'Q4 revenue up 12% YoY' });
 ```
 
-The slide's delta is stamped `deck:<deckId>` (derived server-side from the
-slide → deck `parent` edge), so it reaches the deck's audience authoritatively —
-regardless of which groups the agent happened to subscribe to. And `scope` only
-ever *narrows*: the agent can't reach a deck its triggering user couldn't.
+The slide's delta is stamped `deck:<deckId>`, derived server-side from the
+slide → deck `parent` edge — not from `deckId` appearing in this particular
+write, and not from whatever the agent happened to subscribe to. The routing is
+decided by the data: a slide belongs to its deck, so its writes go to the deck's
+group, full stop.
 
 ## See also
 

package/docs/examples/server-agent.md

@@ -1,7 +1,16 @@
 # Server Agent
 
-Most server agents should import the app schema and use the same model methods
-as the product UI.
+A server agent is backend code — a cron job, a queue worker, an AI task — that
+reads and writes your app's records outside the browser. The hard part is doing
+it without racing the live UI: if your worker and a user edit the same report at
+once, one write clobbers the other. This is what `claim()` is for. Below, a
+worker finishes a weather report by claiming it, writing the result, and
+releasing it — all in one call.
+
+`claim(id, work)` takes the record for your worker, runs your update inside the
+callback, then releases it when the callback returns. Claims don't lock. If
+another writer holds the row, `claim` waits for them, re-reads the fresh row,
+then hands it to you — so two writers serialize instead of clobbering.
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -23,7 +32,7 @@ const ablo = Ablo({
 export async function completeReport(reportId: string) {
   await ablo.ready();
 
-  const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+  const report = await ablo.weatherReports.retrieve(reportId);
   if (!report) return { status: 'not_found' };
 
   const updated = await ablo.weatherReports.claim(
@@ -41,5 +50,18 @@ export async function completeReport(reportId: string) {
 }
 ```
 
-Use the schema-backed version for server agents so the worker, app, and React UI
-share the same model methods.
+`retrieve(id)` is an async server read — it hits the server and returns the row
+(or `null`, which the early `not_found` guard handles). The update runs inside
+the claim callback, and `{ wait: 'confirmed' }` makes that update resolve only
+once the server has accepted it.
+
+The two options on the claim:
+
+- `wait: false` — skip this record if another claim is already in progress,
+  rather than queueing behind it. (The default queues.)
+- `action: 'completing'` — a human-readable label for what your worker is doing,
+  visible to anyone reading `claim.state(id)`.
+
+Because the worker uses the same schema and `claim()` as the UI, its writes sync
+to every connected client in real time and never collide with edits already in
+progress.

package/docs/guarantees.md

@@ -1,7 +1,14 @@
 # Guarantees
 
-This page is the short contract for what Ablo guarantees at the state
-boundary.
+When an Ablo write succeeds, the server has accepted it — and when two people or
+agents touch the same row, Ablo coordinates them instead of letting one silently
+overwrite the other. This page is the precise list of what you can count on:
+confirmed writes, stale-write protection, claims, and the audit trail behind
+every change.
+
+Claims don't lock. If another writer holds the row, `claim` waits for them,
+re-reads the fresh row, then hands it to you — so two writers serialize instead
+of clobbering.
 
 ## Confirmed Writes
 
@@ -17,8 +24,9 @@ const updated = await ablo.weatherReports.update(
 ```
 
 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 claim conflict, idempotency, rate limit, or transport failure.
+typed error tells you exactly why — the most common reasons being failed
+authorization, a schema validation error, or a stale-state or claim conflict
+(each covered below).
 
 Schema model writes return the updated model row.
 
@@ -58,27 +66,28 @@ Advanced policies exist for controlled product flows:
 - `reject` fails the write when state moved.
 - `force` applies the write without stale protection.
 - `flag` accepts the write and marks it for product review.
-- `merge` is reserved for server-defined merge behavior.
+
+`merge` is not yet available.
 
 ## Claim Coordination
 
-> The guarantee, not the how-to. Methods, the claim-state object, and the `queue`
+> The guarantee, not the how-to. Methods, the claim-state object, and the `claim.queue`
 > live in [Coordination](./coordination.md).
 
 Claims are live coordination signals. They are not database locks.
 
-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.
+`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 stay open while a
+claim is held — `ablo.<model>.claim.state(id)` returns the current claim state
+(or `null`) without ever blocking. A server read can pass `ifClaimed: 'wait'` to
+wait for the claim to clear, or `ifClaimed: 'fail'` to error out, when it should
+not return a row while someone else is mid-edit.
 
 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.
+`ablo.<model>.update(id, ...)` is rejected with `AbloStaleContextError` if the row
+changed underneath you after your claim point.
 
 ## Agent Runs
 
@@ -98,8 +107,8 @@ authorized it, which run did it, and what state was it based on?"
 
 ## Persistence
 
-Ablo defaults to volatile in-memory persistence. That keeps the SDK focused on
-coordination and audit instead of silently becoming a browser storage product.
+Ablo defaults to volatile in-memory persistence, so nothing is written to disk
+unless you ask for it.
 
 Opt into a durable browser cache that survives reloads when you need it: