@abloatai/ablo 0.7.0 → 0.9.0

package/docs/identity.md

@@ -30,65 +30,16 @@ A **sync group** is a named channel of shared state — a string like
 There is no built-in `org` / `team` / `user` concept in the engine. Those are
 *your* domain words. Ablo only knows sync-group strings. The mapping from "this
 is user U in org O" to "they may subscribe to `org:acme` and `user:U`" is
-something **you declare in your schema** — covered next.
-
-### Two kinds of group — the whole mental model
-
-Every sync group is named after one of two things, and that's the cleanest way
-to hold the model in your head:
-
-- **Membership groups** — named after *who you are*: `org:{id}`, `team:{id}`,
-  `user:{id}`. Produced from **identity** (`identityRoles`, Half 1). They're
-  standing and durable — they don't change as you work.
-- **Entity groups** — named after *a thing*: `dataroom:{id}`, `deck:{id}`,
-  `slide:{id}`. Produced from a **row's id** (a model's entity scope, Half 2).
-  They're granular — one per record — and any participant can be pointed at a
-  specific set of them.
-
-Humans and agents fill that same space differently — and, crucially, the two
-are **declared in different places**, because membership is static (a property of
-identity) while entity scope is dynamic (a property of the task):
-
-| | Subscribed by | Declared where | Gets |
-| --- | --- | --- | --- |
-| **Human** | *who they are* — membership | **the schema** (`identityRoles`) — a rule, written once | every `org` / `team` / `user` group their identity implies — their whole standing world |
-| **Agent** | *what it's been given* — entities | **code, at the spawn site** — chosen per run | a handful of entity groups: the dataroom it's in, the slides it has read — never beyond what its user's membership could reach |
-
-> **One line:** humans subscribe by who they are; agents subscribe by what
-> they've been given.
-
-The asymmetry is the point. A user's org/team/user don't change per request, so
-their scope is a **rule the schema derives automatically** — you never write
-per-user scope code. An agent's reach depends on *what it's working on*, which is
-only knowable at dispatch — so you pass its `syncGroups` **at the call site, in
-code**. The schema's only job for entities is to declare *that* a model is
-entity-scopable and *what its group is named* (`scope: 'deck'` → `deck:{id}`);
-it never declares *which* entities a given agent gets. (A human can opt into the
-same runtime narrowing — a page scoped to one deck — but by default a human's
-scope is fully schema-derived.)
-
-So an agent doesn't need a `user:{id}` standing grant. It's a participant pointed
-at a few entity groups, bounded above by its triggering user's membership. That
-boundary is the whole safety story, and it's covered in
-[Agents are participants too](#agents-are-participants-too).
-
-```txt
-your auth → identity { kind, userId|agentId, organizationId, teamIds }
-          → identityRoles (schema) → allowed sync groups
-          → participant receives deltas for rows in those groups
-```
-
-The identity is a **participant** — and a participant is either a human
-(`kind: 'user'`) or an agent (`kind: 'agent'`). Same shape, same path; see
-[Agents are participants too](#agents-are-participants-too) below. Everything in
-the next two sections applies to both.
+something **you declare in your schema**. Here is that whole declaration in one
+runnable place, so the concepts below have code to attach to.
 
 ## Declare it, end to end
 
 The entire declaration surface is: `identityRoles` (who may see what), and on
 each model `scope` / `parent` / `grants` (which group a row fans out on), plus an
-optional `syncGroups` prop (narrowing). Here they are in one runnable place — the
-sections after this explain each.
+optional `syncGroups` prop (narrowing). Read the three blocks first — a human
+gets their `org` / `team` scope, an agent gets one `deck` — then the sections
+after explain each.
 
 ```ts
 // 1. src/ablo/schema.ts — map identity → groups, and anchor each model to a group
@@ -144,6 +95,60 @@ export const schema = defineSchema(
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
 
+## Two kinds of group — the whole mental model
+
+You just saw a human get `org` / `team` groups and an agent get one `deck`
+group. That split is the model. Every sync group is named after one of two
+things:
+
+- **Membership groups** — named after *who you are*: `org:{id}`, `team:{id}`,
+  `user:{id}`. Produced from **identity** (`identityRoles`, Half 1). They're
+  standing and durable — they don't change as you work.
+- **Entity groups** — named after *a thing*: `dataroom:{id}`, `deck:{id}`,
+  `slide:{id}`. Produced from a **row's id** (a model's entity scope, Half 2).
+  They're granular — one per record — and any participant can be pointed at a
+  specific set of them.
+
+Humans and agents fill that same space differently, and you declare the two in
+different places. A human's groups come from who they are, so you declare them
+once in the schema. An agent's groups come from what it's working on right now,
+so you pass them in code when you start the run.
+
+| | Subscribed by | Declared where | Gets |
+| --- | --- | --- | --- |
+| **Human** | *who they are* — membership | **the schema** (`identityRoles`) — a rule, written once | every `org` / `team` / `user` group their identity implies — their whole standing world |
+| **Agent** | *what it's been given* — entities | **code, at the spawn site** — chosen per run | a handful of entity groups: the dataroom it's in, the slides it has read — never beyond what its user's membership could reach |
+
+> **One line:** humans subscribe by who they are; agents subscribe by what
+> they've been given.
+
+That's why you never write per-user scope code, but you always pass an agent's
+scope at the call site. A user's org/team/user don't change per request, so
+their scope is a **rule the schema derives automatically**. An agent's reach
+depends on *what it's working on*, which is only knowable at dispatch — so you
+pass its `syncGroups` **at the call site, in code**. The schema's only job for
+entities is to declare *that* a model is
+entity-scopable and *what its group is named* (`scope: 'deck'` → `deck:{id}`);
+it never declares *which* entities a given agent gets. (A human can opt into the
+same runtime narrowing — a page scoped to one deck — but by default a human's
+scope is fully schema-derived.)
+
+So an agent doesn't need a `user:{id}` standing grant. It's a participant pointed
+at a few entity groups, bounded above by its triggering user's membership. That
+boundary is the whole safety story, and it's covered in
+[Agents are participants too](#agents-are-participants-too).
+
+```txt
+your auth → identity { kind, userId|agentId, organizationId, teamIds }
+          → identityRoles (schema) → allowed sync groups
+          → participant receives deltas for rows in those groups
+```
+
+The identity is a **participant** — and a participant is either a human
+(`kind: 'user'`) or an agent (`kind: 'agent'`). Same shape, same path; see
+[Agents are participants too](#agents-are-participants-too) below. Everything in
+the next two sections applies to both.
+
 ## The two halves of scoping
 
 Scoping is two declarations that meet in the middle. One describes the
@@ -355,9 +360,10 @@ agent authority = (triggering user's allowed set)    ← ceiling, inherited (on-
                 ∩ (the model instances it touches)    ← floor, least privilege per run
 ```
 
-Mechanically, this is the per-model anchor from
-[Half 2](#half-2--per-model-scope-row--group) doing the work. Declare an entity
-anchor on the models an agent operates on:
+Concretely: each model an agent edits declares a `scope`
+([Half 2](#half-2--per-model-scope-row--group)), so each row forms its own
+group. The agent subscribes only to the groups for the rows it touches. Declare
+an entity anchor on the models an agent operates on:
 
 ```ts
 // each scope-root model an agent edits forms a per-entity group
@@ -393,8 +399,8 @@ user it ran on behalf of, so audit answers "who did this, and on whose behalf."
 It never appears in an `identityRole`, because it changes *who's accountable*,
 not *what's reachable*.
 
-This is deliberately the shape the 2025–2026 agent-identity consensus converged
-on, expressed in Ablo's primitives rather than a bolted-on agent ACL:
+Three rules make agent access safe, and they fall out of the model above rather
+than needing a separate agent permission system:
 
 - **Inherit the user, and no more** — the OAuth
   [on-behalf-of](https://workos.com/blog/oauth-on-behalf-of-ai-agents) model: the

package/docs/index.md

@@ -1,37 +1,47 @@
 # Ablo Docs
 
-Ablo is a state control API for **humans and AI agents editing the same
-typed state in real time, with attribution, conflict handling, and
-fast cutoff**.
+You have a database, and you want an AI agent to edit the same rows your
+users are editing — without the two clobbering each other's work. Ablo gives
+the agent a narrow, audited write path: you declare your models, then everyone
+(React components, server actions, and agents) calls the same
+`ablo.deck.update(...)`. Ablo streams confirmed changes to everyone live and
+rejects any write based on stale data.
 
-It gives agents a narrow way to write production state: declare models, load current state, coordinate active work, and write with stale-state checks.
+The flow is four steps: declare your models, read the current rows, claim the
+row you're about to change, then write — and the write is rejected if someone
+changed the row first.
 
-Multiplayer is not a separate product mode. If humans, server actions, and agents
-use the same `Ablo({ schema, apiKey })` client and write through
-`ablo.<model>`, Ablo fans out confirmed deltas, exposes active claims, and
-rejects stale writes for every participant.
+```ts
+// The same call, whether a person, a server action, or an agent makes it.
+await ablo.deck.update({ id: deckId, data: { title: "Q3 Strategy" } });
+```
 
-## What you get, in three commitments
+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.
 
-These commitments drive every design choice in the rest of the docs; if
-they don't match what you're building, the trade-offs land elsewhere
-(Replicache, ElectricSQL, PowerSync for human-only real-time; Zero for
-query-shaped sync).
+## What you get
+
+Three things stay true no matter how you use Ablo:
 
 - **One model API for every actor.** `ablo.<model>.update(...)` is the
   call from React components, server actions, background workers, and
   AI agents alike. No separate "agent SDK," no parallel mutation path.
   Attribution comes from the credential, not the call site.
-- **Server owns the scope convention.** Tenancy / per-entity scope
+- **You declare tenancy scopes once.** Tenancy / per-entity scope
   prefixes (`org:`, `deck:`, or your own `region:` / `customer:`) are
-  declared once on the schema's `identityRoles`. Consumer code never
-  composes group strings. Same boundary Liveblocks (`prepareSession`),
-  PowerSync (named streams), and Zero (synced queries) settled on.
+  declared once on the schema's `identityRoles`, so application code
+  never builds an `org:123` string by hand — which keeps tenant
+  boundaries from leaking.
+- **Stale writes are rejected.** If the row changed after you read it,
+  your write is turned away instead of silently overwriting the change
+  you didn't see.
 
 ## Start here
 
 - [Quickstart](./quickstart.md) — Make your first schema-backed write.
-- [CLI & Migrations](./cli.md) — `init` / `migrate` / `schema push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
+- [Schema Contract](./schema-contract.md) — One schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
+- [CLI & Migrations](./cli.md) — `init` / `migrate` / `push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
 - [Identity & Sync Groups](./identity.md) — Bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Integration Guide](./integration-guide.md) — Choose Ablo-managed state, Data Source, React, multiplayer, and agent patterns.
 - [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and claims guarantee.
@@ -60,10 +70,11 @@ query-shaped sync).
 
 ## Concepts
 
+- [Schema Contract](./schema-contract.md) — What the schema drives across SDK, React, agents, Data Source, and migrations.
 - [Model Methods](./api.md#model-methods) — Load and write typed state.
 - [Integration Guide](./integration-guide.md) — The normal app path and optional pieces.
 - [Guarantees](./guarantees.md) — Confirmed writes, optimistic state, stale-write protection, and agent lifecycle.
-- [Coordination](./coordination.md) — `claim`, `claimState`, and `queue` for active work.
+- [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue` for active work.
 - [Connect Your Database](./data-sources.md) — Where data lands when your app database is canonical.
 - [Receipt](./api.md#receipt) — Confirm what landed.
 - [Usage](./api.md#usage) — Metering and audit dimensions.

package/docs/integration-guide.md

@@ -1,39 +1,26 @@
 # Integration Guide
 
-Use this guide when you are adding Ablo to a real product, not a demo.
+If humans and AI agents both edit the same records in your app, they overwrite
+each other and there's no good place to coordinate. Ablo gives them one shared,
+typed write path — the same `ablo.<model>.update(...)` call for a React
+component, a server action, a background worker, or an agent — and reconciles the
+edits. This guide adds it to a product that already has a backend and database,
+one model at a time.
 
-## Why Ablo, before the API
-
-Ablo is a sync engine designed from the ground up for **humans and AI
-agents editing the same state at the same time**. That premise drives
-every design choice in this guide; if you only need server-to-server
-data syncing without agents in the loop, the trade-offs land elsewhere
-(Replicache, ElectricSQL, PowerSync are good answers for human-only
-real-time apps; Zero is a good answer for query-shaped sync).
-
-The shape of the SDK reflects three commitments:
+Three things hold no matter which actor is writing:
 
 - **One model API for every actor.** `ablo.<model>.update(...)` is what
   React components, server actions, background workers, and AI agents
   all call. No separate "agent SDK," no parallel mutation path. The
   attribution comes from the credential, not the call site.
-- **Server owns the scope convention; client picks a subset by id.** The
-  `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
-  prefixes live in the schema's `identityRoles` once, never typed by
-  consumer code. Same boundary Liveblocks (`prepareSession`), PowerSync
-  (named streams), and Zero (synced queries) settled on after the same
-  realization: clients that compose scope strings drift; servers that
-  derive scope from authed identity don't.
-- **Capabilities, not API keys, are how agents authenticate.** Static
-  API keys protect server-to-server humans. Agents get per-run,
-  per-scope, leased credentials with per-request signature verification
-  and instant revocation. The 2025-2026 AI-agent auth consensus
-  (OAuth 2.1 / MCP, AWS STS, Vault leases, Auth0 Token Vault) converged
-  on this shape. Capabilities are Ablo's instance.
-
-If you have already built a sync layer or an agent runtime, you know
-what each of those costs. This guide assumes you want them solved once,
-together, behind one client.
+- **You never type `org:123` in client code.** The server derives what each
+  caller can see from their authenticated identity, using the `identityRoles`
+  you declare once in the schema. The client just names which model and id it
+  wants. The `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
+  prefixes live in the schema, never in consumer code.
+- **Agents don't use your account API key.** Each agent run gets a short-lived
+  credential scoped to just what that run can touch, verified per request and
+  revocable instantly. (See the Agents section below for the actual calls.)
 
 ## The integration in one diagram
 
@@ -49,7 +36,7 @@ Declare the models Ablo coordinates, then read and write through
 that same model path.
 
 ```txt
-schema -> ablo.<model>.load(...) -> ablo.<model>.update(...)
+schema -> ablo.<model>.list(...) -> ablo.<model>.update(...)
 ```
 
 Commits and receipts exist under the hood. Most apps do not create protocol
@@ -226,21 +213,28 @@ refreshes before expiry.
 
 ## 3. Read State
 
-Use `load` when the row may not already be local.
+Reads come in two flavors, and you pick based on whether you can wait.
+`retrieve(id)` and `list({ where })` hit the server (and hydrate the local
+store) — they're async, so you `await` them. `get(id)`, `getAll({ where })`,
+and `getCount({ where })` read the already-synced local graph synchronously, so
+they're the ones you call in render.
+
+Use `retrieve` when the row may not be local yet — it fetches from the server
+and waits.
 
 ```ts
 await ablo.ready();
 
-const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
-Use `retrieve`, `list`, and `count` for synchronous reads after data has
-loaded.
+Use `get`, `getAll`, and `getCount` for synchronous local-graph reads after
+data has synced.
 
 ```ts
-const report = ablo.weatherReports.retrieve('report_stockholm');
-const activeReports = ablo.weatherReports.list({
+const report = ablo.weatherReports.get('report_stockholm');
+const activeReports = ablo.weatherReports.getAll({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
@@ -260,8 +254,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 }));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
 }
@@ -278,7 +272,7 @@ const ablo = useAblo();
 For simple writes:
 
 ```ts
-await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
 ```
 
 For writes based on state the user or agent already read, snapshot first and
@@ -287,15 +281,13 @@ reject stale updates:
 ```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',
+});
 ```
 
 `wait: 'confirmed'` resolves after the server accepts the write. Rejections roll
@@ -342,11 +334,11 @@ The migration can be gradual:
 
 1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.weatherReports.retrieve(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.get(id)) ?? serverReport` for live rows.
 4. Add one Data Source endpoint that calls the existing service layer.
 5. Move one mutation button from `fetch('/api/reports/...')` to `ablo.weatherReports.update(...)`.
 6. Add an outbox/events path for writes that still happen outside Ablo.
-7. Let agents use the same `ablo.weatherReports.load(...)` and `ablo.weatherReports.update(...)`.
+7. Let agents use the same `ablo.weatherReports.list(...)` and `ablo.weatherReports.update(...)`.
 
 For the full Python shape, see
 [Existing Python Backend](./examples/existing-python-backend.md).
@@ -407,21 +399,26 @@ The API key verifies Ablo's request. It is not a database credential.
 Agents should use the same model methods as the app when they can import the
 schema.
 
+An agent often reads a row, calls an LLM, then writes back — a slow gap during
+which a human might touch the same row. Wrap that work in a claim. 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
-const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+const report = await ablo.weatherReports.retrieve({ id: reportId });
 if (!report) return;
 
-await ablo.weatherReports.claim(
-  reportId,
-  async (claimed) => {
-    await ablo.weatherReports.update(
-      claimed.id,
-      { status: 'ready', forecast: await getForecast(claimed) },
-      { wait: 'confirmed' }
-    );
-  },
-  { wait: false, action: 'forecasting' }
-);
+await using claim = await ablo.weatherReports.claim({
+  id: reportId,
+  wait: false,
+  action: 'forecasting',
+});
+const claimed = claim.data;
+await ablo.weatherReports.update({
+  id: claimed.id,
+  data: { status: 'ready', forecast: await getForecast(claimed) },
+  wait: 'confirmed',
+});
 ```
 
 Use AI SDK for the model loop. Put Ablo inside the tool that persists the final
@@ -436,11 +433,13 @@ const completeReport = tool({
   }),
   execute: async ({ reportId, forecast }) => {
     const snap = ablo.snapshot({ weatherReports: reportId });
-    return ablo.weatherReports.update(
-      reportId,
-      { status: 'ready', forecast },
-      { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' }
-    );
+    return ablo.weatherReports.update({
+      id: reportId,
+      data: { status: 'ready', forecast },
+      readAt: snap.stamp,
+      onStale: 'reject',
+      wait: 'confirmed',
+    });
   },
 });
 ```
@@ -455,7 +454,7 @@ Keep agent writes on the same schema client surface as the app.
 | `/testing`                                | Test harnesses and deterministic mocks.                           |
 | `Data Source`                             | Keep your app database canonical.                                 |
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
-| `claim` / `claimState` / `queue`          | Show active work and coordinate before a write.                   |
+| `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
 | `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
@@ -465,16 +464,17 @@ them.
 
 ## Method Cheatsheet
 
-| Method                       | Use it for                                                       |
-| ---------------------------- | ---------------------------------------------------------------- |
-| `load({ where })`            | Async hydration from backing store/server.                       |
-| `retrieve(id)`               | Synchronous read of one already-loaded row.                      |
-| `list(options?)`             | Synchronous collection read of loaded rows.                      |
-| `count(options?)`            | Synchronous count of loaded rows.                                |
-| `create(data, options?)`     | Create through the model client.                                  |
-| `update(id, data, options?)` | Update through the model client.                                  |
-| `delete(id, options?)`       | Delete through the model client.                                  |
-| `claimState(id)`             | See active work on a model row.                                  |
-| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs. |
+| Method                       | Use it for                                                                  |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| `retrieve(id)`               | Async read of one row from the server (await it).                           |
+| `list({ where })`           | Async read of many rows from the server (await it).                         |
+| `get(id)`                    | Synchronous local read of one synced row (use in render).                   |
+| `getAll({ where })`         | Synchronous local read of many synced rows.                                 |
+| `getCount({ where })`       | Synchronous local count of synced rows.                                     |
+| `create(data, options?)`     | Create through the model client.                                            |
+| `update(id, data, options?)` | Update through the model client.                                            |
+| `delete(id, options?)`       | Delete through the model client.                                            |
+| `claim.state({ id })`            | See who is currently working on a row (synchronous).                       |
+| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs.            |
 
 Keep first integrations on the model methods above.

package/docs/interaction-model.md

@@ -1,28 +1,39 @@
 # Interaction Model
 
-Ablo's public model is the path every human UI, server action, and agent uses on
-every write:
+When a person, a server action, and an AI agent can all write to the same row,
+you need one write path that stops them from clobbering each other. Ablo gives
+you exactly one: load the row, claim it while you work, update it, and wait for
+confirmation. This page walks through that path and the few primitives behind it.
 
+Here's the whole path in one block — claim a row, update it inside the claim, and
+let the claim release when your callback returns:
+
+```ts
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' }, wait: 'confirmed' });
 ```
-Schema -> Model load -> Claim -> Model update -> Confirmation
-```
+
+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.
 
 ## Primitives
 
 | Primitive | Plane | Purpose |
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `load`, `retrieve`, `create`, `update`, and `delete`. |
-| `Claim` | Coordination | Who is working on a target. Claimed via `ablo.<model>.claim(id, ...)` and read via `ablo.<model>.claimState(id)`. Ephemeral — never persisted. |
+| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async server reads), `get`/`getAll`/`getCount` (synchronous local reads), `create`, `update`, and `delete`. |
+| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral — never persisted. |
 | `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
 | `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
 
 ### Why each primitive is separate
 
-The plane separation isn't ceremony — collapsing any two of these would
-lose a property that's hard to recover later. A reader coming from
-Replicache or Yjs would expect just `Commit`; here's what the others buy
-you over that minimum:
+Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
+does a job the others can't. If you're coming from Replicache or Yjs you'd
+expect just `Commit`; here's what the other two buy you over that minimum:
 
 - **`Claim` is not a read lock.** Reads stay open. Claims serialize
   acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
@@ -33,45 +44,42 @@ you over that minimum:
   client. A status code can't be re-read by a sub-agent that wasn't on
   the original call.
 
-The shape is borrowed from systems that learned the cost of collapse:
-coordination from operational-transform CRDTs and Linear's optimistic
-multiplayer model, and receipts from durable write protocols.
-
 ## Run Loop
 
 A normal schema-backed run is:
 
-```
-const [report] = await ablo.weatherReports.load({ where: { id } });
-const active = ablo.weatherReports.claimState(id);
-await ablo.weatherReports.claim(id, async (report) => {
-  await ablo.weatherReports.update(report.id, patch, { wait: 'confirmed' });
-});
+```ts
+const report = await ablo.weatherReports.retrieve({ id });
+const active = ablo.weatherReports.claim.state({ id });
+await using claim = await ablo.weatherReports.claim({ id });
+await ablo.weatherReports.update({ id: claim.data.id, data: patch, wait: 'confirmed' });
 ```
 
+`retrieve({ id })` is an async server read (await it). `claim.state({ id })` is a
+synchronous local read of who currently holds the row — it never blocks.
+
 ## Coordination
 
 > Loop view only. Full claim reference — methods, the claim-state object, the
-> `queue`, errors — is [Coordination](./coordination.md).
+> `claim.queue`, errors — is [Coordination](./coordination.md).
 
-Claims broadcast across the org. Claim a row through the flat model verb, write
-through the normal `update`, and the claim releases when the callback returns:
+Claims broadcast across the org. Call `claim({ id })`, do your writes with the
+normal `update` inside the `await using` scope, and the claim releases
+automatically when the scope exits:
 
 ```ts
-await ablo.weatherReports.claim(
-  'report_stockholm',
-  async (report) => {
-    await ablo.weatherReports.update(report.id, { status: 'ready' }); // stale-guarded under the claim
-  },
-  { action: 'editing' },
-);
+await using claim = await ablo.weatherReports.claim({
+  id: 'report_stockholm',
+  action: 'editing',
+});
+await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
 ```
 
-`ablo.weatherReports.claimState('report_stockholm')` reads the live claim (or `null`) without
-blocking. The claim is **advisory**: if another participant holds the row,
-`claim` waits for them to finish and re-reads before handing back the row. The
-same signal is visible to every schema client through `claimState(id)` and the live
-claim stream.
+`ablo.weatherReports.claim.state({ id: 'report_stockholm' })` reads the live claim (or
+`null`) without blocking. Claims don't lock: if another participant holds the
+row, `claim` waits for them to finish, re-reads, and then hands you the fresh
+row. The same signal is visible to every schema client through `claim.state({ id })`
+and the live claim stream.
 
 ## Conflict resolution