@abloatai/ablo 0.6.0 → 0.8.0

package/docs/data-sources.md

@@ -1,19 +1,19 @@
 # Connect Your Database
 
-Every schema model has a backing store.
+By default, Ablo stores the rows for the models you define, so you don't need a
+database to get started. But if you already have your own application database
+and want it to stay the source of truth, you can attach it as a Data Source —
+then Ablo coordinates each write and calls your app to commit it, instead of
+storing the data itself.
 
-Customer apps must define an Ablo schema. The schema is the contract between
-the SDK, agents, realtime subscriptions, and the Data Source endpoint. Use
-`defineSchema`, `model`, and Zod the same way a Prisma project starts with a
-`schema.prisma`.
+That default makes Ablo the managed state store for your models, the same way
+Stripe stores `Customer` and `PaymentIntent` objects that you create through
+Stripe's API.
 
-By default, Ablo stores the rows for the models you declare. That makes Ablo the
-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
-canonical, attach a Data Source. Then Ablo coordinates the write and calls your
-app to commit it.
+Either way, you define an Ablo schema with `defineSchema`, `model`, and Zod —
+the same way a Prisma project starts with a `schema.prisma`. Your schema
+describes your data once, and everything else (the SDK, agents, and your
+database connection) relies on that one definition.
 
 Your app can keep using its own `DATABASE_URL`. Store that value in your app or
 backend environment, not in Ablo. The integration boundary is the HTTPS
@@ -24,7 +24,7 @@ Use the SDK with an API key:
 
 ```ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -56,15 +56,18 @@ The SDK call is the same in both modes:
 ```ts
 await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
 await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
-const report = ablo.weatherReports.retrieve('report_stockholm');
+const report = ablo.weatherReports.get('report_stockholm');
 ```
 
 Only the backing store changes.
 
 Multiplayer behavior is the same in both modes. Writes made through
 `ablo.<model>.create/update/delete` are coordinated by Ablo, then confirmed rows
-fan out to subscribers. Direct database writes outside Ablo need Data Source
-events so connected humans and agents see the change.
+fan out to subscribers. If something writes to your database without going
+through Ablo (a cron job, an admin tool), Ablo can't know about it
+automatically. To keep everyone's screen up to date, your app reports those
+outside changes back through an events feed — shown below in
+[External Writes](#external-writes).
 
 ## When To Use A Data Source
 
@@ -100,7 +103,7 @@ The shape is the same as a production webhook integration:
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSource } from '@abloatai/ablo';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
 export const POST = dataSource({
@@ -231,10 +234,9 @@ Before using a customer-owned database in production:
 - Dedupe outbox events by event `id`.
 - Monitor last success, last error, retry count, event lag, and cursor.
 
-Do not send the customer's database URL to Ablo for this path. Direct database
-URL custody would be a separate connector product with encrypted secret storage,
-rotation, least-privilege roles, connection limits, table allowlists, and clear
-data-processing terms.
+Don't give Ablo your database URL for this integration — Ablo never connects to
+your database directly. (Direct database access would be a separate product with
+its own security model.)
 
 ## Security
 

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
@@ -26,7 +32,7 @@ Browser UI
 Create a schema for the records that need realtime coordination.
 
 ```ts
-// web/ablo.schema.ts
+// web/ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
@@ -42,7 +48,7 @@ export const schema = defineSchema({
 ```ts
 // web/ablo.ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -58,7 +64,7 @@ model clients without importing server credentials.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider schema={schema}>{children}</AbloProvider>;
@@ -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

@@ -0,0 +1,93 @@
+# Agent Scoped to One Deck
+
+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 relationship, once
+
+```ts
+import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema(
+  {
+    // A deck's rows form the group `deck:<id>` (the kind comes from `scope`).
+    decks: model(
+      { title: z.string() },
+      {},
+      { orgScoped: true, scope: 'deck' },
+    ),
+    // 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 }) },
+      { orgScoped: true },
+    ),
+  },
+  {
+    // Humans get their full org scope automatically from these.
+    identityRoles: [
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+    ],
+  },
+);
+```
+
+## 2. Dispatch — narrow the agent to the deck it's working on
+
+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`.
+
+```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 — 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
+
+- [Identity & Sync Groups](../identity.md) — the full scope / parent / grants model.
+- [Agent + Human](./agent-human.md) — yielding when a human edits the same row.

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.