@abloatai/ablo 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- Structured error contract, schema/migration engine, and a full `ablo` CLI.
+  - **Structured error contract across HTTP + WS planes.** A closed, canonical
+    error-code registry is now the `code` tier of a Stripe-style error model. A
+    single HTTP egress funnel converts every throw to a canonical
+    `{ type, code, message, doc_url, request_id, ...details }` envelope; the WS
+    plane narrows mutation/claim error codes to the same union.
+  - **Versioned contract + drift guard.** `ERROR_CONTRACT_VERSION` (date-based)
+    ships in `errors.json` and on the `Ablo-Version` response header, so consumers
+    detect contract changes without diffing docs. Generated `errors.mdx` /
+    `errors.json` plus a CI drift guard keep the docs, OpenAPI spec, and SDK from
+    silently diverging from the registry.
+  - **Always-on request correlation.** Every response carries a `req_…` request id
+    (honoring an inbound `x-request-id`), stamped into the envelope's `request_id`.
+  - **OpenAPI parity.** The stale `{ error, reason }` schema is replaced by the
+    canonical envelope plus a generated `ErrorCode` enum.
+
+  CLI + schema:
+  - **Schema diff + migration planning engine** (`generateProvisionPlan` /
+    `generateMigrationPlan` in `@abloatai/ablo/schema`) — pure diff, classify,
+    apply, and constant-value backfill for required-field migrations.
+  - **`ablo generate`** — emit TypeScript types from the pushed schema.
+  - **Full `ablo` CLI suite**, Stripe-CLI-shaped: `init`, `login` / `logout` /
+    `status`, `mode [test|live]`, `dev` (push schema to the test sandbox + watch),
+    `logs` (tail your scope's commit activity), and the data-source commands below.
+    Authentication is the OAuth 2.0 device flow; `login` provisions and stores a
+    test and a live key, and `mode` switches the active one.
+  - **Database-URL structure (bring-your-own-database).** The CLI is split by where
+    it writes:
+    - `ablo pull` / `ablo check` / `ablo migrate` operate on **your own
+      `DATABASE_URL`** — `pull` introspects it to emit `defineSchema(...)` from
+      existing tables (read-only, like `prisma db pull`), `check` verifies tables
+      fit the schema with no DDL, and `migrate` applies DDL to `DATABASE_URL`.
+    - `ablo schema push` / `ablo dev` target the **hosted** test/live sandbox; the
+      server diffs, migrates, and activates the uploaded schema. `dev` never
+      touches live data.
+
+  **BREAKING** — removed the legacy React hooks `useQuery` / `useOne` / `useMutate`
+  / `useReader`. Use `useAblo()` + `ablo.<model>.*` instead. The `MutateActions`,
+  `ReaderActions`, and `ReaderFindOptions` types are still re-exported for callers
+  that referenced them.
+
+## 0.6.0
+
+### Minor Changes
+
+- 0f663e7: Coordination surface: fair queue, reactive wait-line, and lease renewal.
+  - **Claims acquire through a server FIFO queue.** On contention a claim waits its turn and re-reads before proceeding; reads are never blocked. Writes blocked by another participant's claim throw a typed `AbloBusyError`.
+  - **`ablo.<model>.queue(id)`** — reactive read of the wait-line behind a row: who's queued, their action, and FIFO position. Synced to peers like `activity(id)`.
+  - **Backpressure on `claim`** — `{ wait: false }` skips instead of waiting if the row is already held (claim-or-skip dedup); `{ maxQueueDepth: n }` bails with `AbloBusyError('queue_too_deep')` rather than joining a line already that deep.
+  - **Lease renewal** — a held claim renews automatically while the holder's connection is alive, so you never size a TTL; it lapses only after the holder goes silent. A queued claim that's abandoned is dequeued (no ghost waiters).
+  - **Reads are never gated by a claim**, including for agents.
+  - Intent vocabulary cleanup: a waiting claim is an `Intent` with `status: 'queued'` (`position` carries its place in line). Removed the unbuilt `whenFree`.
+
+- **BREAKING — API renames** (apply when upgrading from 0.5.1):
+  - Change-listeners renamed to `.onChange(...)`: `ablo.<model>.subscribe(cb)`, `presence.subscribe()`, `intents.subscribe()` → `.onChange(...)`. (`subscribe` is reserved for an upcoming scope-grant verb.)
+  - Row-access API renamed Resource → Model: `Ablo.Resource.*` → `Ablo.Model.*`, `ablo.resource(name)` → `ablo.model(name)`, `ModelTarget.resource` → `ModelTarget.model`, error code `resource_not_found` → `model_not_found`.
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,11 @@
 # Ablo
 
-Ablo Sync is a typed sync engine for shared app state — the kind that humans,
+[![npm](https://img.shields.io/npm/v/@abloatai/ablo.svg)](https://www.npmjs.com/package/@abloatai/ablo)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+[![types](https://img.shields.io/badge/types-included-blue.svg)](#)
+[![runtime](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#keys--runtime)
+
+Ablo is a typed sync engine for shared app state — the kind that humans,
 server code, and AI agents all edit at once.
 
 Reach for it when those edits need to show up everywhere in real time, not
@@ -8,28 +13,49 @@ silently overwrite each other, expose who's working on what, and leave a record
 of who changed what.
 
 ```txt
-schema -> ablo.<model>.create/retrieve/load/update/intent(...)
+schema -> ablo.<model>.create/retrieve/update/claim(...)
 ```
 
-## Install
+## Why Ablo
+
+- **Real-time by default.** Every `create` / `update` / `delete` fans out
+  confirmed deltas to all subscribers — humans and agents — with no separate
+  "multiplayer mode" to switch on.
+- **No silent clobbers.** Writes are guarded against stale reads, and `claim`
+  holds a row across a slow read → LLM → write gap so concurrent edits queue
+  instead of overwriting.
+- **Built for agents.** See who's mid-edit (`claimState` / `queue`), coordinate a
+  fair line, and ship an `llms.txt` so coding agents integrate from the real API.
+- **Typed end to end.** Your Zod schema produces typed model proxies
+  (`ablo.<model>.update(...)`), optimistic local reads, and reactive React hooks.
+- **Bring your own auth and database.** Ablo scopes realtime data to *sync
+  groups* from your existing identity, and can leave your database as the source
+  of truth via a Data Source.
+
+**Built for:** collaborative editors, AI agent workflows, internal tools, and any
+app where multiple actors mutate shared state and everyone must see it live.
+
+## Set up
 
 ```bash
 npm install @abloatai/ablo
 ```
 
-Requires Node 22+ and TypeScript 5+.
-
-## Get a Test Key
+**Keys & runtime.** Ablo needs Node 22+ and TypeScript 5+. Grab an `sk_test_*`
+key for a sandbox
+(`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server runtimes only.
+In the browser, `<AbloProvider>` authenticates with the signed-in user's
+session — never the raw key.
 
-Create an Ablo sandbox and copy an `sk_test_*` API key. Keep API keys in trusted
-server runtimes only.
+Then wire it by hand — the [Quick Start](#quick-start) below is the shape to
+copy. For production (React, an existing backend, Data Source, agents), the
+[Integration Guide](./docs/integration-guide.md) is the deeper map.
 
-```bash
-export ABLO_API_KEY=sk_test_...
-```
+**Prefer to let an agent wire it?** The package ships an `llms.txt` — a precise
+map of the API — so Claude Code or Cursor integrates from the real surface
+instead of guessing:
 
-In the browser, connect through the React provider (`<AbloProvider>`), which
-authenticates with the signed-in user's session — never the raw API key.
+> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema, a `<AbloProvider>`, and my first create / retrieve / update.
 
 ## Quick Start
 
@@ -73,9 +99,104 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
-Pass `schema` to get typed models like `ablo.weatherReports.update(...)`. Omit it
-only for the lower-level client used by custom agents and MCP routes that can't
-import your app's schema.
+Pass `schema` to get typed models like `ablo.weatherReports.update(...)`.
+
+## Reading
+
+`retrieve(id)` returns one row from the local cache — synchronous, no round-trip.
+`list(...)` filters and sorts what's already synced; it's also synchronous, and
+reactive under `useAblo`/`subscribe`. `load(...)` fetches from the server when a
+row may not be local yet.
+
+```ts
+ablo.weatherReports.retrieve('report_stockholm');
+
+const pending = ablo.weatherReports.list({
+  where: { status: 'pending' },
+  orderBy: { location: 'asc' },
+  limit: 20,
+});
+
+const ready = await ablo.weatherReports.load({
+  where: { status: 'ready' },
+  type: 'complete',
+});
+```
+
+An array value in `where` means `IN`. On `load`, `type: 'complete'` waits for
+the server; `'unknown'` returns what's local now and refreshes in the background.
+
+## Writing
+
+`create` / `update` apply optimistically and resolve to the row. Two options
+matter day to day:
+
+| Option | Values | What it does |
+| --- | --- | --- |
+| `wait` | `'queued'` \| `'confirmed'` | `'confirmed'` resolves only after the server acks the write; `'queued'` resolves as soon as it's locally queued (fire-and-forget). |
+| `idempotencyKey` | `string` | Auto-generated per call. Override only when you own the retry boundary (e.g. a job id) so a re-run dedupes server-side. |
+
+```ts
+await ablo.weatherReports.update(id, { status: 'ready' }, { wait: 'confirmed' });
+```
+
+To guard a write against a row that changed under you, pass `readAt` + `onStale`
+— see [Coordinating long agent work](#coordinating-long-agent-work).
+
+## Coordinating long agent work
+
+An agent reads a row, thinks for 30s, writes back — and clobbers whatever changed
+meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
+
+```ts
+await ablo.weatherReports.claim('report_stockholm', async (report) => {
+  const forecast = await weatherAgent.getWeather(report.location);
+  await ablo.weatherReports.update(report.id, { forecast, status: 'ready' });
+});
+```
+
+If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
+so `report` is the current row, never a stale snapshot. Reads stay open by
+default; only acting on the row serializes. The claim releases when the callback
+returns or throws.
+
+See who's mid-edit before you act — decide to wait, or skip:
+
+```ts
+ablo.weatherReports.claimState('report_stockholm');
+ablo.weatherReports.queue('report_stockholm');
+
+await ablo.weatherReports.claim(id, async (report) => {
+  /* do the held work */
+}, { wait: false });
+
+await ablo.weatherReports.claim(id, async (report) => {
+  /* do the held work */
+}, { maxQueueDepth: 2 });
+```
+
+`claimState` returns the holder (or `null`); `queue` returns the line waiting
+behind it. `wait: false` skips rather than waiting when the row is held;
+`maxQueueDepth: 2` bails when two or more are already ahead.
+
+Default reads keep working while a row is claimed. Server reads that need claimed
+semantics can opt in with `ifClaimed: 'return' | 'wait' | 'fail'`.
+
+Even an unclaimed write can't land on stale reasoning — the commit is guarded:
+
+```ts
+try {
+  await ablo.weatherReports.update(id, { status: 'ready' }, { readAt, onStale: 'reject' });
+} catch (e) {
+  if (e instanceof AbloStaleContextError) { /* row moved under you — re-read, retry */ }
+}
+```
+
+> Prefer the callback form for ordinary held work. Manual scoped claims are
+> available for wider lifetimes, but callback claims are the docs default.
+
+See [Coordination](./docs/coordination.md) for the full `claim` / `claimState` /
+`queue` / `release` reference.
 
 ## React
 
@@ -85,7 +206,7 @@ everything inside is live.
 
 ```tsx
 import { AbloProvider, useAblo } from '@abloatai/ablo/react';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 function App() {
   return (
@@ -96,14 +217,11 @@ function App() {
 }
 
 function Report({ id }: { id: string }) {
-  // Reactive read: this re-renders whenever the row changes — whether you,
-  // a teammate, or an agent changed it.
   const report = useAblo((ablo) => ablo.weatherReports.retrieve(id));
   const ablo = useAblo();
 
   if (!report) return null;
 
-  // Write: same method as the server example above. Optimistic; fans out.
   return (
     <button onClick={() => ablo?.weatherReports.update(id, { status: 'ready' })}>
       {report.status}
@@ -112,62 +230,44 @@ function Report({ id }: { id: string }) {
 }
 ```
 
-`<AbloProvider>` owns the connection and authenticates with the signed-in user's
-session — no API key in the browser. That's the whole loop: read with
-`useAblo(selector)`, write with `ablo.<model>`, and every other client (human or
-agent) on that row sees it in real time. See [React](./docs/react.md) for
-`fallback`, `bootstrapMode`, presence, and status hooks.
+The `useAblo(selector)` read re-renders whenever the row changes — whether you,
+a teammate, or an agent changed it. The write is the same optimistic, fan-out
+method as the server example above.
 
-## Set up with Claude Code
+`<AbloProvider>` owns the connection — no API key in the browser. That's the
+whole loop: read with `useAblo(selector)`, write with `ablo.<model>`, and every
+other client (human or agent) on that row sees it in real time. See
+[React](./docs/react.md) for the full `<AbloProvider>` prop surface (`userId`,
+`teamIds`, `syncGroups`, `fallback`, `bootstrapMode`) and status hooks.
 
-The package ships an `llms.txt` — a compact, LLM-readable map of the whole API.
-Point your coding agent at it and let it do the integration:
+## Identity & Sync Groups
 
-> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema and
-> `<AbloProvider>` to this app and wire up my first create / retrieve / update.
+Ablo is **not** an auth provider — you keep your own (Clerk, Auth0, NextAuth,
+whatever). Ablo's job starts after you've authenticated a request: you tell it
+*who* is connecting, and it scopes their realtime data to the right **sync
+groups** (named channels like `org:acme` or `deck:abc123` that are both the unit
+of fan-out and the unit of access).
 
-It scaffolds the schema, sets up the provider, and writes your first
-`ablo.<model>` calls — the same shape as the Quick Start above.
+The model is a proxy: your `ABLO_API_KEY` stays on your trusted server, your
+server resolves the signed-in user (org / team / user) from your own auth, and
+the browser connects as an already-scoped participant — it never holds the key
+and can't widen its own scope. Your schema's `identityRoles` map that identity
+to sync-group strings.
 
-For a production integration with React, an existing backend, Data Source, and
-future agents, read [Integration Guide](./docs/integration-guide.md).
+`userId` / `teamIds` come from your auth, resolved server-side:
 
-## AI Activity on Existing State
-
-When AI or background work will spend real time on an existing row — not just a
-one-shot write — coordinate through `ablo.<model>.intent(id)`, the coordination
-accessor that sits beside `create`/`update`/`retrieve`. It takes the row's `id` (the same
-id you pass to `retrieve(id)` / `update(id, …)`) and returns a handle
-synchronously, so you can see who's already working on a row before you start.
-
-```ts
-// `report_stockholm` is this weather report's id — set at create time, or the
-// `created.id` returned above.
-const report = ablo.weatherReports.intent('report_stockholm');
-
-// Read side: is someone already on it? Wait for them to finish.
-if (report.current) {
-  report.current.heldBy; // 'agent:forecaster'
-  await report.whenFree();
-}
-
-// Write side: claim so other participants yield while we work.
-await report.claim({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
-
-// Your existing weather tool or agent call. While this runs, other clients see
-// that report_stockholm is being checked.
-const row = ablo.weatherReports.retrieve('report_stockholm');
-const weather = await weatherAgent.getWeather(row.location);
-
-await report.update({
-  status: 'ready',
-  forecast: weather.summary,
-});
+```tsx
+<AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
+  <App />
+</AbloProvider>
 ```
 
-Ablo does not fetch the weather. It keeps the activity visible while the work
-runs, rejects `report.update(...)` with `AbloStaleContextError` if the row
-changed under you, and finishes the claim automatically once the write lands.
+If it isn't obvious where org / team / user come from in the Quick Start above,
+that's because they come from *your* app — see
+[Identity & Sync Groups](./docs/identity.md) for the full picture: what a sync
+group is, the two halves of scoping (`identityRoles` + per-model `orgScoped` /
+`syncGroupFormat`), and how identity reaches Ablo without an API key in the
+browser.
 
 ## Multiplayer
 
@@ -176,63 +276,32 @@ workers share the same schema and write through `ablo.<model>`, they all see
 each other's changes in real time — that's the default, not a feature you turn on.
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
-- `useAblo(...)` gives React clients the live row plus active intents.
-- `ablo.<model>.intent(id)` lets humans and agents see and coordinate active work before a write lands.
-
-Always write through Ablo — the SDK (`ablo.<model>.create/update/delete`) or the
-HTTP API (`POST /v1/commits`). If you write straight to your own database
-instead, those changes won't reach connected clients. Use Ablo's endpoints and
-the fan-out is automatic.
-
-Under the hood, capabilities, tasks, leases, intents, commits, and receipts are
-real protocol primitives. They exist so agent work is scoped, coordinated,
-attributable, and cleaned up if a runtime disappears — but you don't touch them
-in a first integration. The default path above is enough.
-
-## HTTP API
-
-The SDK is a typed wrapper over a signed HTTP API, the same way `stripe-node`
-wraps Stripe's REST API. Everything you do through `ablo.<model>` is reachable
-over HTTP, so backends in other languages and server-to-server callers work
-without the SDK.
-
-Writes — create, update, and delete — all go through one endpoint as a batch of
-operations:
-
-```http
-POST /v1/commits
-Authorization: Bearer sk_live_...
-Idempotency-Key: <your-unique-id>
-
-{
-  "operations": [
-    {
-      "type": "UPDATE",
-      "model": "weatherReports",
-      "id": "report_stockholm",
-      "input": { "status": "ready" },
-      "readAt": 1042,
-      "onStale": "reject"
-    }
-  ]
-}
-```
+- `useAblo(...)` gives React clients the live row, kept current automatically.
+- `ablo.<model>.claim(id)` / `claimState(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
-Each operation is one `CREATE` / `UPDATE` / `DELETE` (plus `ARCHIVE` /
-`UNARCHIVE`). Reads fetch a single row with `GET /v1/resources/{model}/{id}`.
-The same API key, scope, idempotency, and stale-write rules apply as in the SDK
-— the SDK just removes the boilerplate.
+Always write through Ablo — either the SDK model methods
+(`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
+write straight to your own database instead, those changes won't reach connected
+clients.
 
-## Load vs Retrieve
+## HTTP Writes
 
-Most reads are `retrieve` — it's the everyday path, especially inside `useAblo(...)`:
+Use the SDK when you are in JavaScript and want typed models or realtime. Use the
+HTTP endpoint when a server-to-server caller needs to write without opening a
+WebSocket:
 
-- `ablo.weatherReports.retrieve(id)` is sync. It returns the already-loaded row from
-  the local pool (or `undefined` if it isn't loaded yet). In React,
-  `useAblo((ablo) => ablo.weatherReports.retrieve(id))` keeps that read live.
-- `ablo.weatherReports.load({ where })` is async. Reach for it when you need to
-  guarantee a row is hydrated before you read it — initial fetch, SSR, scripts, or
-  any non-reactive runtime.
+```bash
+curl https://api.abloatai.com/v1/commits \
+  -H "Authorization: Bearer sk_test_..." \
+  -H "Content-Type: application/json" \
+  -d '{ "operations": [
+        { "action": "update", "model": "weatherReports", "id": "report_stockholm", "data": { "status": "ready" } }
+      ] }'
+```
+
+```json
+{ "object": "commit_receipt", "status": "confirmed", "serverTxId": "tx_…", "lastSyncId": 1042, "ops": 1 }
+```
 
 ## Connect Your Database
 
@@ -245,18 +314,73 @@ Source: Ablo sends signed commit requests to an endpoint you host, and your app
 writes its own database. Your `DATABASE_URL` stays in your app — Ablo only ever
 sees the API key.
 
-See [Connect Your Database](./docs/data-sources.md) for the route and commit shape.
+See [Connect Your Database](./docs/data-sources.md) for the integration shape.
+
+## Configuration
+
+`Ablo({ ... })` takes one required option and a couple of transport overrides:
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
+| `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
+| `baseURL` | `string` | `wss://mesh.ablo.finance` | Point at a self-hosted or staging mesh |
+
+Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
+authenticates with the signed-in user's session; the raw-key path is gated
+behind `dangerouslyAllowBrowser` for server-proxy setups only. Self-hosted
+deployments can pass `authToken` instead of `apiKey`. Advanced hooks (custom
+`fetch`, logging, observability) live in [Client Behavior](./docs/client-behavior.md).
+
+## Errors
+
+Every SDK error extends `AbloError` and carries a `requestId` for support.
+Discriminate with `instanceof` or the `type` string — the string form also
+survives worker / `postMessage` boundaries, where `instanceof` does not:
+
+```ts
+try {
+  await ablo.weatherReports.update(id, { status: 'ready' }, { readAt, onStale: 'reject' });
+} catch (e) {
+  if (e instanceof AbloStaleContextError) { /* row moved under you — re-read, retry */ }
+  if ((e as AbloError).type === 'AbloClaimedError') { /* another participant holds it */ }
+}
+```
+
+| Error | When |
+| --- | --- |
+| `AbloAuthenticationError` | Invalid / missing / expired credentials |
+| `AbloPermissionError` / `CapabilityError` | Action forbidden by scope |
+| `AbloRateLimitError` | Rate limited (carries `retryAfterSeconds`) |
+| `AbloIdempotencyError` | Same `idempotencyKey` reused with a different body |
+| `AbloValidationError` | Invalid request payload |
+| `AbloStaleContextError` | Write carried `readAt`, but the row has newer changes (`conflicts`) |
+| `AbloClaimedError` | Target is claimed by another participant (`claims`) |
+| `AbloConnectionError` / `AbloServerError` | Transport failure / server 5xx |
+| `SyncSessionError` | Session expired (prompts re-auth) |
+
+## Reconnect & retries
+
+The client owns reconnection so your code doesn't have to. A dropped WebSocket
+reconnects automatically with exponential backoff (1s → 30s, ±15% jitter, up to
+~7.5 minutes); session errors (401/403) suppress it so you re-authenticate
+instead of looping. Commits are idempotent by client transaction id, and a
+commit that times out is never silently rolled back — the client reconciles
+against authoritative server state on reconnect. These defaults are the
+contract; there are no retry or timeout knobs to tune.
 
 ## Production Reference
 
-- [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, intent coordination, and agent lifecycle.
+- [Identity & Sync Groups](./docs/identity.md) — bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
+- [Coordination](./docs/coordination.md) — `claim` / `claimState` / `queue` / `release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.
 - [AI SDK Tool](./docs/examples/ai-sdk-tool.md) — use Ablo inside an AI SDK tool call.
-- [Server Agent](./docs/examples/server-agent.md) — schema-backed worker plus advanced schema-less run.
+- [Server Agent](./docs/examples/server-agent.md) — schema-backed worker.
 
 ## License
 

package/dist/BaseSyncedStore.d.ts

@@ -21,7 +21,7 @@ import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model } from './Model.js';
 import { ModelScope } from './ObjectPool.js';
 import type { Schema } from './schema/schema.js';
-import { type ReaderActions } from './react/useReader.js';
+import { type ReaderActions } from './mutators/readerActions.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
 export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
 /** Concrete constructor type for instantiation */
@@ -139,7 +139,7 @@ export interface UserContext {
      *  - `'full'` (default): pull every delta in scope before `ready()`
      *    resolves. The standard browser/user replica behavior.
      *  - `'none'`: open the WebSocket and process live deltas only.
-     *    Reads go through `resource.retrieve()` / filtered subscriptions
+     *    Reads go through `model.retrieve()` / filtered subscriptions
      *    backfilled by `Covering` deltas. Suitable for transactional
      *    participants — agent-worker, video-pipeline, routine runners —
      *    that don't need a local replica of the org's tenant plane.
@@ -662,7 +662,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     queryByClass(modelClass: ModelConstructor<Model>, options?: {
         predicate?: (model: Model) => boolean;
-        scope?: ModelScope;
+        state?: ModelScope;
         orderBy?: keyof Model;
         order?: 'asc' | 'desc';
         limit?: number;

package/dist/BaseSyncedStore.js

@@ -22,7 +22,7 @@ import { getContext } from './context.js';
 import { SyncSessionError } from './errors.js';
 import { ModelScope } from './ObjectPool.js';
 import { LazyReferenceCollection } from './LazyReferenceCollection.js';
-import { createReaderActions } from './react/useReader.js';
+import { createReaderActions } from './mutators/readerActions.js';
 /** Bootstrap timeout configuration */
 export const BOOTSTRAP_CONFIG = {
     OVERALL_TIMEOUT_MS: 15_000,
@@ -790,7 +790,7 @@ export class BaseSyncedStore {
             //
             // `bootstrapMode: 'none'` participants (agent-worker, headless
             // task runners) skip baseline replication — they read via
-            // `resource.retrieve()` round-trips and rely on covering deltas
+            // `model.retrieve()` round-trips and rely on covering deltas
             // from filtered subscriptions to populate the pool lazily. The
             // WS is already open by `setupWebSocketSync` above, so live
             // delta flow works regardless of this branch.
@@ -1688,7 +1688,7 @@ export class BaseSyncedStore {
         const modelName = this.objectPool.registry.getModelNameFromConstructor(modelClass);
         if (!modelName)
             return { data: [], total: 0, hasMore: false };
-        let allModels = this.objectPool.getByType(modelClass, options?.scope ?? ModelScope.live);
+        let allModels = this.objectPool.getByType(modelClass, options?.state ?? ModelScope.live);
         // Filter out pending deletes
         allModels = allModels.filter((m) => !this.pendingDeletes.has(m.id));
         // Apply predicate

package/dist/api/index.d.ts

@@ -2,9 +2,9 @@
  * Internal compatibility entrypoint for the stateless hosted protocol client.
  *
  * Use this build for serverless functions, scripts, and backends that want
- * Resource / Intent / Commit over HTTP without the realtime sync runtime.
+ * model reads/writes and commits over HTTP without the realtime sync runtime.
  */
-export { createProtocolClient, createProtocolClient as Ablo, type AbloApi, type AbloApiClientOptions, type AbloApiIntents, type Agent, type AgentIntentInput, type AgentIntentOptions, type AgentOptions, type AgentResourceClient, type AgentResourceReadOptions, type AgentResourceMutationOptions, type AgentRunContext, type AgentRunDone, type AgentRunFailed, type AgentRunCancelled, type AgentRunOptions, type AgentRunResult, type AgentRunStatus, type Capability, type CapabilityCreateOptions, type CapabilityParticipantKind, type CapabilityRecord, type CapabilityResource, type CapabilityRevocation, type CapabilityScope, type Task, type TaskCloseOptions, type TaskCloseResult, type TaskCreateOptions, type TaskResource, } from '../client/ApiClient.js';
-export type { CommitCreateOptions, CommitOperationInput, CommitReceipt, CommitWait, IntentCreateOptions, IntentHandle, IntentWaitOptions, BusyOptions, BusyPolicy, ResourceClient, ResourceIntent, ResourceMutationOptions, ResourceReadOptions, ResourceRead, ResourceTarget, } from '../client/Ablo.js';
+export { createProtocolClient, createProtocolClient as Ablo, type AbloApi, type AbloApiClientOptions, type AbloApiIntents, type Agent, type AgentIntentInput, type AgentIntentOptions, type AgentOptions, type AgentModelClient, type AgentModelReadOptions, type AgentModelMutationOptions, type AgentRunContext, type AgentRunDone, type AgentRunFailed, type AgentRunCancelled, type AgentRunOptions, type AgentRunResult, type AgentRunStatus, type Capability, type CapabilityCreateOptions, type CapabilityParticipantKind, type CapabilityRecord, type CapabilityResource, type CapabilityRevocation, type CapabilityScope, type Task, type TaskCloseOptions, type TaskCloseResult, type TaskCreateOptions, type TaskResource, } from '../client/ApiClient.js';
+export type { CommitCreateOptions, CommitOperationInput, CommitReceipt, CommitWait, IntentCreateOptions, IntentHandle, IntentWaitOptions, ClaimedOptions, IfClaimedPolicy, ModelClient, ModelClaim, ModelMutationOptions, ModelReadOptions, ModelRead, ModelTarget, } from '../client/Ablo.js';
 import { createProtocolClient } from '../client/ApiClient.js';
 export default createProtocolClient;

package/dist/api/index.js

@@ -2,7 +2,7 @@
  * Internal compatibility entrypoint for the stateless hosted protocol client.
  *
  * Use this build for serverless functions, scripts, and backends that want
- * Resource / Intent / Commit over HTTP without the realtime sync runtime.
+ * model reads/writes and commits over HTTP without the realtime sync runtime.
  */
 export { createProtocolClient, createProtocolClient as Ablo, } from '../client/ApiClient.js';
 import { createProtocolClient } from '../client/ApiClient.js';