@abloatai/ablo 0.9.1 → 0.9.3

package/docs/quickstart.md

@@ -1,74 +1,121 @@
 # Quickstart
 
-Start building with Ablo in two steps: install, then declare one model and write
-through its generated client.
+Build with Ablo on **your own database**. You declare a small Ablo schema for the
+models humans and agents edit together, hand the client your Postgres
+`DATABASE_URL`, and coordinate every write through `ablo.<model>`. Your database
+is the system of record — Ablo never hosts your data. It is the transaction
+layer on top: it registers your connection, commits every write there behind
+row-level security, and fans the confirmed rows out to every connected client.
 
-If you already have a backend and database, still start here. The SDK call shape
-is the same; [Integration Guide](./integration-guide.md) explains when to use
-Ablo-managed state versus a Data Source that calls your existing API service.
-
-## 1. Install and set a sandbox key
+## 1. Install and get a key
 
 ```bash
 npm install @abloatai/ablo
+npx ablo login
+```
+
+`ablo login` opens the browser — sign in (or sign up) and a `sk_test_` key is
+saved locally for the CLI. Later, `npx ablo dev` (step 4) writes
+`ABLO_API_KEY` into your `.env.local` so the SDK finds it too — no manual
+copy-paste. In CI, or to manage it by hand, set it yourself instead:
+
+```bash
 export ABLO_API_KEY=sk_test_...
 ```
 
-`ABLO_API_KEY` is for trusted server runtimes. Browser apps should use the React
-provider with a scoped session route, not a bundled API key.
+Every SDK and CLI call needs a key. Test and live keys work like Stripe's —
+except both point at databases *you* own: `sk_test_*` for your dev database,
+`sk_live_*` for production. There is no keyless mode; the public `/sandbox` page
+is a hosted demo, not your app.
 
-## 2. Declare schema and write state
+## 2. Declare your Ablo schema
 
-Your schema is the contract. It generates `ablo.<model>` methods for app code,
-server actions, agents, React reads, and Data Source requests.
+The schema is the contract — it generates `ablo.<model>` methods for app code,
+server actions, agents, and React reads. Declare **only the synced models** Ablo
+coordinates; your auth, billing, and other tables stay in your own Drizzle schema,
+owned by your own migrations.
 
 ```ts
-import Ablo from '@abloatai/ablo';
+// ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
-const schema = defineSchema({
+export const schema = defineSchema({
   weatherReports: model({
     location: z.string(),
     status: z.enum(['pending', 'ready']),
     forecast: z.string().optional(),
   }),
 });
+```
+
+## 3. Point Ablo at your database
+
+The client takes your schema, your key, and your `DATABASE_URL`. On first
+connect Ablo registers the connection (sent once over TLS, stored sealed, never
+echoed back) and from then on commits every write directly to your Postgres.
+
+```bash
+# .env — server runtime only, never the browser
+DATABASE_URL=postgres://ablo_app:...@host:5432/db
+ABLO_API_KEY=sk_test_...
+```
+
+```ts
+// ablo/client.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from './schema';
 
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
+  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
 });
+```
+
+Use a dedicated **non-superuser role** for the connection — Ablo enforces
+tenant isolation with row-level security, so the server rejects superuser or
+`BYPASSRLS` roles outright.
+
+Don't want a connection string to leave your infrastructure? Keep
+`DATABASE_URL` in your app only and expose one signed **Data Source endpoint**
+built from an ORM adapter instead — same product, same writes, see
+[Connect Your Database](./data-sources.md). In that setup, omit `databaseUrl`
+from `Ablo(...)`.
+
+## 4. Provision your tables, then push the schema
+
+```bash
+npx ablo migrate   # creates your synced-model tables (with row-level security)
+                   # in YOUR database — your other tables are left untouched
+npx ablo dev       # pushes the schema (test mode), writes ABLO_API_KEY to
+                   # .env.local, and re-pushes on every save — the dev loop
+```
+
+`ablo dev` (or one-shot `npx ablo push`) uploads the schema *definition* —
+model names, fields, types. That metadata is the only thing Ablo keeps; the
+rows stay in your database. Skipping the push makes every write to a new or
+changed model fail with `server_execute_unknown_model` — that error literally
+means "run `npx ablo push`."
+
+## 5. Write through the model
+
+The rows land in your Postgres; every connected client sees them live.
+
+```ts
+import { ablo } from './ablo/client';
+
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  data: {
-    location: 'Stockholm',
-    status: 'pending',
-  },
+  data: { location: 'Stockholm', status: 'pending' },
 });
 
 const updated = await ablo.weatherReports.update({
   id: created.id,
-  data: {
-    status: 'ready',
-    forecast: 'Light rain, 13C',
-  },
+  data: { status: 'ready', forecast: 'Light rain, 13C' },
 });
 
-console.log({ id: updated.id, status: updated.status });
-```
-
-Expected output:
-
-```txt
-{ id: '...', status: 'ready' }
-```
-
-## Run the example
-
-```bash
-cd packages/sync-engine
-ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
+console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
 ## Add coordination for slow work
@@ -146,5 +193,5 @@ Keep using the schema client for app and agent writes.
 - [Schema Contract](./schema-contract.md) explains what the schema drives across SDK, React, agents, Data Source, and schema push.
 - [Guarantees](./guarantees.md) explains what confirmed writes and stale checks mean.
 - [Client Behavior](./client-behavior.md) covers errors, retries, and public imports.
-- [Connect Your Database](./data-sources.md) covers the optional route for teams keeping rows in their own database.
+- [Connect Your Database](./data-sources.md) covers both connection shapes — `databaseUrl` and the signed Data Source endpoint.
 - [AI SDK Tool](./examples/ai-sdk-tool.md) shows the same write path inside a tool call.

package/docs/react.md

@@ -14,6 +14,27 @@ The React bindings ship with the main package — no extra install.
 import { useAblo } from '@abloatai/ablo/react';
 ```
 
+## Building the client
+
+You build the Ablo client once — that's where the schema, the session endpoint,
+and connection config live — then hand it to the provider. The provider takes
+the already-built `client`; it no longer takes `schema`, `url`, `apiKey`, etc.
+as props. This mirrors Stripe's `<Elements stripe={stripePromise}>`: construct
+the thing, then pass it.
+
+```ts
+// lib/ablo.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+
+// The browser never holds your API key. It mints a short-lived session token
+// from your own server route (see Identity below).
+export const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
+});
+```
+
 ## AbloProvider
 
 Mount it once near the root of your tree. It owns the connection, the local
@@ -23,48 +44,38 @@ pool, and the engine lifecycle; everything below it reads with `useAblo`.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+import { ablo } from '@/lib/ablo';
 
 export function Providers({
   children,
   user, // resolved server-side from YOUR auth
 }: {
   children: React.ReactNode;
-  user: { id: string; teamIds: string[] };
+  user: { id: string };
 }) {
   return (
-    <AbloProvider
-      schema={schema}
-      userId={user.id}
-      teamIds={user.teamIds}
-      fallback={<AppSkeleton />}
-    >
+    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
       {children}
     </AbloProvider>
   );
 }
 ```
 
-`schema` is the only required prop. The rest are situational:
-
-| Prop                | Default                | Purpose                                                                                                   |
-| ------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
-| `schema`            | —                      | **Required.** From `defineSchema()`. Determines the typed hook surface.                                   |
-| `userId`            | resolved from auth     | App participant id for app-owned fields and your `identityRoles.extract`. Not the security boundary.      |
-| `teamIds`           | resolved from auth     | Team ids expanded into team sync groups via `identityRoles`.                                               |
-| `syncGroups`        | full allowed set       | **Narrows** the subscription to a subset of what auth allows (e.g. `['deck:abc123']`). Never widens it.   |
-| `url`               | hosted endpoint        | WebSocket URL of the sync server (`wss://…`). Hosted apps omit it.                                         |
-| `apiKey`            | session/cookie         | Bootstrap auth. Browser apps **omit this** — the key stays server-side. See Identity below.               |
-| `fallback`          | neutral spinner        | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `bootstrapMode`     | `'full'`               | `'full'` loads existing rows before the app renders, so reads are populated on first paint; `'none'` skips that initial load and only streams changes as they happen.|
-| `persistence`       | `'volatile'`           | `'indexeddb'` opts into a durable browser cache that survives reloads.                                     |
-| `onSessionExpired`  | —                      | Fired after the engine has already purged on a rejected session — use for redirect-to-sign-in.            |
-| `onError`           | —                      | Engine / WebSocket / `postBootstrap` errors. Wire to Sentry / Datadog.                                    |
-
-Where `userId` / `teamIds` / `syncGroups` come from, and why the API key never
-reaches the browser, is the whole of
-[Identity & Sync Groups](./identity.md) — read that if it isn't obvious how org
-/ team / user map to what a participant can see.
+`client` is the only required prop. The rest are situational:
+
+| Prop        | Default          | Purpose                                                                                                   |
+| ----------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `client`    | —                | **Required.** The `Ablo({ schema, authEndpoint })` instance. It carries the schema and connection config. |
+| `userId`    | resolved from auth | App participant id for app-owned fields and your `identityRoles`. Not the security boundary.            |
+| `fallback`  | neutral spinner  | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
+| `onError`   | —                | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
+
+Everything that used to be a provider prop — `schema`, `url`, `apiKey`,
+`teamIds`, `syncGroups`/`scope`, `persistence`, `bootstrapMode` — now lives on
+the `Ablo({ ... })` client you build before mounting the provider. Where the
+identity comes from, and why the API key never reaches the browser, is the whole
+of [Identity & Sync Groups](./identity.md) — read that if it isn't obvious how
+org / team / user map to what a participant can see.
 
 ## useAblo — model client
 

package/docs/schema-contract.md

@@ -88,10 +88,8 @@ the fresh row. Reads stay open; only acting on the row serializes.
 
 ## Storage boundary
 
-Every schema model needs a backing store:
-
-- Use Ablo-managed state when the row can live in Ablo.
-- Use a Data Source when your app database remains canonical.
+Every schema model is backed by your own database through a Data Source — Ablo
+coordinates each write and your app commits it to your Postgres.
 
 Do not pass a database URL to `Ablo(...)`. Trusted runtimes use `ABLO_API_KEY`.
 Browser code goes through `<AbloProvider>` or a scoped session route, never a raw

package/llms-full.txt

@@ -0,0 +1,360 @@
+# Ablo Full Context
+
+Ablo is the state coordination layer for apps where humans and agents edit the same data.
+
+Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist to the database, coordinate with concurrent human or agent work, and leave an audit trail.
+
+The product surface should read like Stripe, Turbopuffer, or Reducto: one product-name import, models by dot access, optional subpaths only for schema, React, and tests.
+
+```ts
+import Ablo from '@abloatai/ablo';
+```
+
+## Public Surface
+
+Public imports:
+
+- `@abloatai/ablo` — `Ablo`, errors, typed model clients, claims, `dataSource`, and advanced schema-less protocol models.
+- `@abloatai/ablo/schema` — `defineSchema`, `model`, `z`, relations, schema types.
+- `@abloatai/ablo/react` — React provider and hooks.
+- `@abloatai/ablo/testing` — test harnesses and mocks.
+
+Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or `internal/*` as public imports. The Data Source surface — `/source`, `/source/next`, `/source/drizzle`, `/source/kysely`, `/source/conformance` — IS public (it's how a customer-owned database is wired).
+
+The canonical integration doc is `integration-guide`. It explains the end-to-end
+path for schema, React selectors, your Data Source-backed database, multiplayer,
+and agent workers. Use it before inventing a new setup
+flow.
+
+## Production Guarantees
+
+`wait: 'confirmed'` resolves after the server accepts the write. Schema model
+writes are optimistic; a server rejection rolls back local state and raises a
+typed `AbloError`.
+
+Use `snapshot(...)` and `readAt` when an agent write depends on state it already
+read. `onStale: 'reject'` prevents lost updates by rejecting if the target
+changed after the snapshot.
+
+Claims are live coordination signals, not database locks. Schema clients wait
+from the realtime claim stream. Schema-less HTTP clients must pass an explicit
+`claimedPollInterval` for `ifClaimed: 'wait'`; no hidden hard-coded polling.
+
+Agent run bookkeeping is internal. Most users should not create run ledger
+records or scoped access credentials manually.
+
+## Primary App Path
+
+Declare models in a schema, then use typed model clients:
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  weatherReports: model({
+    id: z.string(),
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+    updatedAt: z.string(),
+  }),
+  projects: model({
+    id: z.string(),
+    name: z.string(),
+  }),
+});
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+if (!report) throw new Error('Row not found');
+
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const updated = await ablo.weatherReports.update({
+  id: claim.data.id,
+  data: { status: 'ready', forecast: await getForecast(claim.data) },
+  wait: 'confirmed',
+});
+```
+
+The normal app API (every verb takes ONE options object):
+
+- `ablo.<model>.retrieve({ id })` — async read of one row from the server
+- `ablo.<model>.list({ where })` — async read of many from the server
+- `ablo.<model>.get(id)` / `getAll({ where })` / `getCount({ where })` — synchronous local-graph reads (reactive in React render)
+- `ablo.<model>.create({ data, id? })`
+- `ablo.<model>.update({ id, data })`
+- `ablo.<model>.delete({ id })`
+- `await using claim = await ablo.<model>.claim({ id })` — disposable claim handle; read the fresh row off `claim.data`; auto-releases on scope exit
+- `ablo.<model>.claim.state({ id })` / `claim.queue({ id })` / `claim.release({ id })` / `claim.reorder({ id, order })`
+
+The synchronous reads (`getAll`/`getCount`) accept `where`, `filter`, `orderBy`,
+`limit`, `offset`, and `state`; state defaults to `'live'`, with `'archived'`
+and `'all'` for lifecycle-aware reads.
+
+Use `ablo.model<T>(name)` only when the caller intentionally does not have a schema, such as custom server agents, MCP routes, migration scripts, or generic admin tools.
+
+React reads should use selector `useAblo`:
+
+```tsx
+const report = useAblo((ablo) => ablo.weatherReports.get(id)) ?? serverReport;
+const visibleReports = useAblo((ablo) =>
+  ablo.weatherReports.getAll({ where: { projectId } }),
+);
+```
+
+Use zero-argument `useAblo()` only for callbacks, effects, and writes that need
+the provider-owned client:
+
+```tsx
+const ablo = useAblo();
+await ablo?.weatherReports.update({ id, data: patch, wait: 'confirmed' });
+```
+
+Treat `useQuery`, `useOne`, `useReader`, and `useMutate` as compatibility hooks
+for older string-keyed integrations. Do not teach them as the first React API.
+
+## Multiplayer
+
+Multiplayer is an effect of the normal model API, not a separate setup path.
+When human UI, server actions, and agents use the same
+`Ablo({ schema, apiKey })` client and write through `ablo.<model>`, Ablo
+coordinates the shared model stream:
+
+- confirmed model writes fan out as realtime deltas,
+- React hooks read the latest row and active claims,
+- claims announce active work before a commit,
+- `snapshot(...)` plus `readAt` protects against stale writes.
+
+Direct database writes outside Ablo are not coordinated until the app reports
+them through Data Source events. In Data Source mode, writes made through Ablo
+still coordinate normally because Ablo sends the signed commit request, receives
+canonical rows, and fans out the resulting deltas.
+
+For existing Python backends, keep the Python service layer and database as the
+source of truth. Add one signed Data Source endpoint, keep initial page loads on
+existing APIs if needed, use `useAblo((ablo) => ablo.<model>.get(id)) ?? serverRow`
+for live rows, then migrate buttons one at a time from direct Python endpoint
+writes to `ablo.<model>.update(...)`.
+
+This applies to any API-backed app: Python, Rails, Go, or Node. The backend keeps
+its service layer and DB credentials. Ablo gets a Data Source endpoint and uses
+`ABLO_API_KEY`, not a database URL.
+
+## Client Behavior
+
+Important options: `schema`, `apiKey`, `baseURL`, `persistence`, `fetch`,
+`defaultHeaders`, `defaultQuery`, `logger`, and `dangerouslyAllowBrowser`.
+
+There is intentionally no `databaseURL` option on `Ablo(...)`. Application and
+agent code use `ABLO_API_KEY`. Customer-owned app databases stay private behind
+a signed Data Source endpoint.
+
+Important per-write options: `wait`, `readAt`, `onStale`,
+`idempotencyKey`, and `timeout`.
+
+Errors: `AbloAuthenticationError`, `AbloPermissionError`, `AbloRateLimitError`,
+`AbloIdempotencyError`, `AbloConnectionError`, `AbloValidationError`,
+`AbloServerError`, `AbloStaleContextError`, and `AbloClaimedError`.
+
+Retry transport failures and 5xx with backoff only when the operation is
+idempotent. Do not blindly retry validation, permission, idempotency, claimed, or
+stale-context errors without changing the request.
+
+## Sandboxes
+
+There are two sandbox surfaces:
+
+- Public `/sandbox` is a deterministic visual playground. It demonstrates shared
+  state, active claims, stale-write rejection, receipts, and deltas without
+  making real Ablo calls. It is agent-first: it should expose a prompt that can
+  be pasted into Claude Code or Codex to wire one real model through Ablo.
+- Authenticated org sandboxes are real test environments. The default sandbox is
+  the Stripe-style test mode for an org. It has an isolated sync group prefix,
+  can mint `sk_test_*` keys, and can be reset without touching live state.
+
+Additional org sandboxes can start blank or copy live configuration. Keep
+customer production traffic on `sk_live_*`; use `sk_test_*` for app setup, Data
+Source endpoint wiring, and agent integration testing.
+
+The coding-agent handoff should ask for a narrow integration: one schema model,
+one Ablo client module, one React selector read, one typed model write with
+`readAt`/`onStale: 'reject'`/`wait: 'confirmed'`, and one smoke test where two
+writers prove claim/stale behavior.
+
+## Data Sources
+
+Use these public environment names:
+
+- `ABLO_API_KEY` — SDK authentication for app and agent code. Where it comes
+  from: the human runs `npx ablo login` once (browser; an agent must not run
+  it), and `npx ablo dev` then writes `ABLO_API_KEY=sk_test_…` into
+  `.env.local` automatically. Check the environment and `.env.local` before
+  asking the human for a key.
+
+Do not ask customers to paste their app database URL into Ablo. If their app
+database is canonical, they expose a Data Source endpoint and keep database
+credentials inside their app.
+
+Every schema model is backed by the customer's own database. The SDK methods
+`ablo.<model>.create/update/delete` produce a signed commit request to the
+customer's Data Source route, and that route writes the app database.
+
+When the customer's database is canonical, expose one signed source route:
+
+```ts
+import { dataSourceNext } from '@abloatai/ablo/source/next';
+import { prismaDataSource } from '@abloatai/ablo/source';
+import { schema } from './ablo.schema';
+import { prisma } from './lib/prisma';
+
+// The adapter owns commit / idempotency / outbox — no hand-written commit.
+export const { POST } = dataSourceNext({
+  schema,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, schema) / kyselyDataSource(db, schema)
+});
+```
+
+Commit request shape:
+
+```ts
+{
+  type: 'commit',
+  clientTxId: 'tx_...',
+  operations: [
+    { type: 'UPDATE', model: 'weatherReports', id: 'report_stockholm', input, readAt, onStale: 'reject' },
+  ],
+  scope: { participantId, participantKind, organizationId, requiredSyncGroups, mode: 'live' },
+}
+```
+
+Return `{ rows }` for normal apps or `{ deltas }` for sources that already
+compute canonical change events. External writes come back through the source
+`events` handler or `POST /api/source/events`.
+
+## Advanced Schema Options
+
+Teach schema as model fields and relations first:
+
+```ts
+const schema = defineSchema({
+  weatherReports: model({
+    id: z.string(),
+    location: z.string(),
+  }),
+});
+```
+
+Advanced helpers such as `mutable`, `readOnly`, `field`, `indexed`, query definitions, `load` strategies, parent metadata, and sync-group formats are still part of the schema package for offline/cache/indexing-heavy apps. Do not put them in the first example unless the user asks for local persistence, offline sync, custom loading, or low-level indexing behavior.
+
+## Server Agent Path
+
+Server agents should import the same schema as the app and use the same model
+methods. Claim the row around slow work, then write through `ablo.<model>`.
+
+```ts
+import Ablo from '@abloatai/ablo';
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const forecast = await getForecast(claim.data);
+await ablo.weatherReports.update({
+  id: claim.data.id,
+  data: { status: 'ready', forecast },
+  wait: 'confirmed',
+});
+```
+
+Do not require users to manually create protocol bookkeeping objects in the
+common agent path.
+
+## Model
+
+Every model read returns state plus coordination metadata:
+
+```ts
+type ModelRead<T> = {
+  data: T;
+  stamp: number;
+  claims: ModelClaim[];
+};
+```
+
+`stamp` is the state watermark. Pass it to writes as `readAt`.
+
+`claims` lists active work on the target. Reads are allowed while another participant is working. The caller decides whether to return, fail, or wait.
+
+## Claimed Behavior
+
+Claimed behavior is explicit:
+
+- `ifClaimed: 'return'` returns the current claims with the read.
+- `ifClaimed: 'fail'` throws `AbloClaimedError`.
+- `ifClaimed: 'wait'` waits for matching claims to clear.
+
+Schema clients use the realtime claim stream for waits.
+
+Schema-less HTTP clients cannot know when a claim clears unless the caller opts into polling. When using `ifClaimed: 'wait'` over HTTP, provide `claimedPollInterval` and usually `claimedTimeout`.
+
+```ts
+await api.model('reports').retrieve({
+  id: 'report_stockholm',
+  ifClaimed: 'wait',
+  claimedPollInterval: 1_000,
+  claimedTimeout: 30_000,
+});
+```
+
+No hidden hard-coded claimed polling. `claimedTimeout` is a maximum wait, not the coordination mechanism.
+
+## Write
+
+Use model methods as the normal write path:
+
+```ts
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const updated = await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
+```
+
+Write checks:
+
+- authorization
+- stale state via `readAt`
+- active claim conflicts
+- idempotency when an idempotency key is provided
+
+Use `commits.create(...)` only for low-level batch writes.
+
+## Receipt
+
+Schema model writes return the updated row. Passing `wait: 'confirmed'` waits for
+the server confirmation before resolving. Lower-level model writes return a
+receipt object for custom runtimes that need protocol-level proof.
+
+## Interaction Model
+
+The common agent run is:
+
+1. Read the row through `ablo.<model>.retrieve({ id })` (or `list({ where })`).
+2. Claim it: `await using claim = await ablo.<model>.claim({ id })` — waits if held, hands you `claim.data`.
+3. Do the slow work from `claim.data`.
+4. Write with `ablo.<model>.update({ id, data })`.
+5. The claim auto-releases when it goes out of scope (`await using`).
+
+The underlying primitives are Model, Claim, Commit, and Receipt. Most schema
+users should not call `commits.create(...)` directly.
+
+## Public HTTP Routes
+
+- `GET    /v1/models/{model}/{id}` — read state plus active claims
+- `POST   /v1/commits` — apply mutations
+Use `Authorization: Bearer <api key>` for platform calls.