@abloatai/ablo 0.7.0 → 0.9.0

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,25 +33,31 @@ 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({ id: 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.
-    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,
-        });
+    // If another agent or user already holds this row, claim waits for them
+    // to finish, re-reads the fresh row, then hands it back on `claim.data`.
+    // The claim is released automatically when it goes out of scope.
+    await using claim = await ablo.weatherReports.claim({
+      id: reportId,
+      action: 'editing',
+      ttl: '2m',
+    });
+    const claimed = claim.data;
 
-        return { ok: true, report: updated };
+    // 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({
+      id: claimed.id,
+      data: {
+        status: status ?? claimed.status,
+        forecast: forecast ?? claimed.forecast,
       },
-      { action: 'editing', ttl: '2m' },
-    );
+    });
+
+    return { ok: true, report: updated };
   },
 });
 
@@ -64,11 +72,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`,
-- releases the claim automatically when the callback returns or throws,
+- 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 handle goes out of scope,
 - 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({ id: 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
 
@@ -206,15 +213,20 @@ The app does not need a flag-day rewrite. Move one model at a time.
 ```ts
 const snap = ablo.snapshot({ weatherReports: reportId });
 
-await ablo.weatherReports.update(
-  reportId,
-  { status: 'ready' },
-  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
-);
+await ablo.weatherReports.update({
+  id: reportId,
+  data: { status: 'ready' },
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
 ```
 
 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,15 +249,18 @@ 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({ id: reportId });
 const snap = ablo.snapshot({ weatherReports: reportId });
 
-await ablo.weatherReports.update(
-  reportId,
-  { status: 'ready' },
-  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
-);
+await ablo.weatherReports.update({
+  id: reportId,
+  data: { status: 'ready' },
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
 ```
 
-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({ id: params.id });
   if (!report) return null;
 
   return <ReportEditor report={report} />;
@@ -42,23 +54,26 @@ export default async function ReportPage({
 import { ablo } from '@/lib/ablo';
 
 export async function markReady(id: string) {
-  const report = await ablo.weatherReports.claim(
+  await using claim = await ablo.weatherReports.claim({
     id,
-    async (claimed) =>
-      ablo.weatherReports.update(
-        claimed.id,
-        { status: 'ready' },
-        { wait: 'confirmed' },
-      ),
-    { wait: false, action: 'marking_ready' },
-  );
+    wait: false,
+    action: 'marking_ready',
+  });
+  const claimed = claim.data;
+
+  const report = await ablo.weatherReports.update({
+    id: claimed.id,
+    data: { status: 'ready' },
+    wait: 'confirmed',
+  });
 
   return { status: 'ready', report };
 }
 ```
 
-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 while the `claim` is held. 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 +83,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({ id: 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' });
+await ablo.slides.update({ id: slideId, data: { 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,17 @@
 # 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 automatically when the claim goes out of scope.
+
+`claim({ id })` takes the record for your worker and returns a disposable handle:
+the fresh post-lease row is on `claim.data`, and holding the handle with
+`await using` releases the claim on scope exit (or call `claim.release()`). 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,23 +33,38 @@ 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({ 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' },
-  );
+  await using claim = await ablo.weatherReports.claim({
+    id: reportId,
+    wait: false,
+    action: 'completing',
+  });
+  const claimed = claim.data;
+
+  const updated = await ablo.weatherReports.update({
+    id: claimed.id,
+    data: { status: 'ready' },
+    wait: 'confirmed',
+  });
 
   return { status: 'ready', report: updated };
 }
 ```
 
-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 while
+the claim is held, 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
 
@@ -9,16 +16,17 @@ boundary.
 the authoritative sync cursor.
 
 ```ts
-const updated = await ablo.weatherReports.update(
-  'report_stockholm',
-  { status: 'ready' },
-  { wait: 'confirmed' },
-);
+const updated = await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { 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 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.
 
@@ -43,11 +51,13 @@ read:
 ```ts
 const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.weatherReports.update(
-  'report_stockholm',
-  { status: 'ready' },
-  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
-);
+await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
 ```
 
 `onStale: 'reject'` prevents lost updates. If the target changed after the
@@ -58,27 +68,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 +109,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: