@abloatai/ablo 0.7.0 → 0.9.0

package/dist/wire/errorEnvelope.js

@@ -0,0 +1,86 @@
+/**
+ * ERROR egress — turn ANY thrown value into Stripe's error-object envelope plus
+ * an HTTP status, so every error response across the Ablo surface carries the
+ * identical `{ type, code, param, message, doc_url, request_id }` shape
+ * regardless of which route or service produced it.
+ *
+ * This is the wire-PRODUCE counterpart to `errors.ts`'s wire-PARSE
+ * (`translateHttpError`/`errorFromWire`). It lives in `wire/` — not in the main
+ * SDK entry — so a server-side consumer (a Next.js route) can import it without
+ * dragging in the client runtime (mobx/react/IndexedDB).
+ *
+ * The classifier is the UNIVERSAL baseline: a typed {@link AbloError} passes
+ * through (subclass + code + httpStatus preserved), everything else degrades to
+ * a 500 `internal_error`. Service-specific normalization that needs a DB driver
+ * (apps/sync-server classifies raw Postgres SQLSTATE + MutatorError) is layered
+ * on top in that service — it is intentionally NOT pulled into the shared,
+ * dependency-free contract.
+ */
+import { AbloError, docUrlForCode } from '../errors.js';
+import { errorCodeSpec } from '../errorCodes.js';
+/** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
+ *  match status semantics (a validation error is a 400, a permission error a
+ *  403), so a throw site only picks the right class + code and the status
+ *  follows — an explicit `httpStatus` is passed only when it diverges (e.g. a
+ *  404 on the base class, a 503 on AbloServerError). Mirrors the same table in
+ *  apps/sync-server's self-contained `errors.ts`. */
+export function statusForType(type) {
+    switch (type) {
+        case 'AbloAuthenticationError':
+            return 401;
+        case 'AbloPermissionError':
+            return 403;
+        case 'AbloValidationError':
+            return 400;
+        case 'AbloRateLimitError':
+            return 429;
+        case 'AbloIdempotencyError':
+        case 'AbloStaleContextError':
+        case 'AbloClaimedError':
+            return 409;
+        case 'AbloConnectionError':
+            return 503;
+        case 'AbloServerError':
+            return 500;
+        default:
+            return 500;
+    }
+}
+/**
+ * Convert ANY thrown value into the canonical {@link ErrorEnvelope} plus an
+ * HTTP status. A typed {@link AbloError} is serialized via its own `toJSON`
+ * (so `code`/`param`/`doc_url`/structured `details` survive) and gets its
+ * status from an explicit `httpStatus` or, failing that, {@link statusForType}.
+ * Anything else degrades to a 500 `internal_error` envelope — never a bare
+ * framework "Internal Server Error" text body, and never a raw error string
+ * leaked onto the wire as an unregistered code.
+ *
+ * `requestId` is stamped into the body when the error didn't already carry one,
+ * so the response and the `x-request-id` header agree for support correlation.
+ */
+export function errorEnvelope(err, requestId) {
+    if (err instanceof AbloError) {
+        // Status precedence: an explicit httpStatus wins; else the code's canonical
+        // status from the registry (so `new AbloError('…', { code: 'entity_not_found' })`
+        // is a 404 without the throw site repeating it); else the subclass default.
+        const status = err.httpStatus ??
+            (err.code ? errorCodeSpec(err.code)?.httpStatus : undefined) ??
+            statusForType(err.type);
+        const body = err.toJSON();
+        return {
+            body: requestId && body.request_id === undefined ? { ...body, request_id: requestId } : body,
+            status,
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        body: {
+            type: 'AbloServerError',
+            code: 'internal_error',
+            message,
+            doc_url: docUrlForCode('internal_error'),
+            ...(requestId ? { request_id: requestId } : {}),
+        },
+        status: 500,
+    };
+}

package/dist/wire/frames.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `@abloatai/ablo/wire` — canonical COMMIT-PATH frame contract.
+ *
+ * These are the WebSocket (and HTTP-fallback) message shapes for the
+ * write path: the client's `commit` / `mutation` frames and the server's
+ * `mutation_result` ack. They live here — not in the server app and not
+ * inlined in the SDK's `SyncWebSocket` — so the client, the server, and
+ * any future `@abloatai/ablo/server` host all import ONE definition
+ * and cannot drift.
+ *
+ * Scope note: the delta/sync frames (`sync_response`, `delta`) are NOT
+ * here yet — they reference `SyncDelta`, which currently has two
+ * definitions (server `db/deltas` vs package `core`) pending unification.
+ * They stay server-local until that lands. Everything in this file
+ * depends only on package-canonical types (`OnStaleMode`, `ErrorCode`,
+ * `RequiredCapability`), so it is safe to share today.
+ *
+ * Changing any shape here is a wire-contract change — it requires
+ * coordinated client + server updates.
+ */
+import type { OnStaleMode } from '../coordination/index.js';
+import type { ErrorCode, RequiredCapability } from '../errors.js';
+/**
+ * A single operation within a {@link CommitMessage} batch. The atomic unit
+ * the server's commit executor applies (and, once the mutator seam lands,
+ * the raw-op fallback path when no named mutator is registered).
+ */
+export interface CommitOperation {
+    type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
+    model: string;
+    id?: string | null;
+    input?: Record<string, unknown> | null;
+    /**
+     * Per-op client transaction id. Stamped onto `sync_deltas.transaction_id`
+     * so the originating client can recognize the broadcast as an echo of its
+     * own optimistic mutation. Distinct from the batch-level `clientTxId`
+     * (which keys `mutation_log` for retry idempotency).
+     */
+    transactionId?: string | null;
+    /**
+     * Watermark from `context.capture`. The server checks whether the target
+     * has received deltas since this id; if so the operation's `onStale` mode
+     * applies.
+     */
+    readAt?: number | null;
+    /**
+     * Mode on stale detection. `'reject'` (default) throws
+     * AbloStaleContextError; `'force'` applies unconditionally. `'flag'` /
+     * `'merge'` are reserved, not yet implemented.
+     */
+    onStale?: OnStaleMode | null;
+}
+/**
+ * Client → Server single named-mutation frame. The named-mutator write
+ * primitive (intent + args), as opposed to the raw-op {@link CommitMessage}
+ * batch. Server-side mutator dispatch resolves `mutatorName` against the
+ * host-provided registry.
+ */
+export interface MutationMessage {
+    type: 'mutation';
+    payload: {
+        mutatorName: string;
+        input: unknown;
+        clientTxId: string;
+    };
+}
+/**
+ * Client → Server "commit this batch of operations" frame. Formerly named
+ * `batch_ack` / `BatchAckMessage` — renamed pre-stable to the customer-facing
+ * verb (`commit`) consistently across the wire and the SDK method
+ * (`MutationExecutor.commit`).
+ */
+export interface CommitMessage {
+    type: 'commit';
+    payload: {
+        operations: CommitOperation[];
+        clientTxId: string;
+        /**
+         * Optional turn handle. When the SDK opens a turn via
+         * `SyncAgent.beginTurn(...)`, subsequent commits within the handle's
+         * scope auto-attach the `turnId` here. The Hub validates the turn
+         * belongs to the same agent and is open, then threads it onto every
+         * delta's `caused_by_task_id` column. Absent for human-direct commits
+         * and for SDKs that predate the turn protocol — those produce deltas
+         * with `caused_by_task_id = NULL`, which the audit pane treats as "no
+         * prompt-side context recorded."
+         */
+        causedByTaskId?: string | null;
+    };
+}
+/**
+ * Wire ack for a `commit` frame. Payload mirrors the canonical
+ * `CommitReceipt` shape so WebSocket, HTTP `/v1/commits`, and persisted
+ * `AgentJob.result.receipt` all carry identical fields.
+ *
+ * `object`, `status`, and `ops` are typed optional because pre-unification
+ * WS clients didn't ship them; servers always populate them on the way out.
+ * New clients can rely on them.
+ */
+export interface MutationResultMessage {
+    type: 'mutation_result';
+    payload: {
+        object?: 'commit_receipt';
+        clientTxId: string;
+        serverTxId: string;
+        success: boolean;
+        status?: 'confirmed' | 'rejected';
+        lastSyncId?: number;
+        ops?: number;
+        error?: {
+            code: ErrorCode;
+            message: string;
+            field?: string;
+            /** Structured rejection body (x402-style) emitted when the cap
+             *  verifier denies the commit. */
+            requiredCapability?: RequiredCapability;
+        };
+    };
+}

package/dist/wire/frames.js

@@ -0,0 +1 @@
+export {};

package/dist/wire/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@abloatai/ablo/wire` — the canonical HTTP/frame WIRE CONTRACT, with no
+ * client-runtime (mobx / react / IndexedDB) dependency, so a server-side
+ * consumer — a Next.js route handler, an edge function — can import the
+ * envelope producers without pulling in the whole sync client.
+ *
+ * Two halves, both Stripe-shaped and used across every Ablo surface:
+ *   - ERROR egress — {@link errorEnvelope} / {@link ErrorEnvelope} /
+ *     {@link statusForType} turn any thrown value into
+ *     `{ type, code, param, message, doc_url, request_id }`.
+ *   - LIST egress — {@link listEnvelope} / {@link ListEnvelope} stamp the
+ *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
+ *
+ * The {@link AbloError} hierarchy + {@link docUrlForCode} + the wire-PARSE
+ * helpers are re-exported so a route can THROW the right typed error and
+ * SERIALIZE it through a single import.
+ */
+export { errorEnvelope, statusForType } from './errorEnvelope.js';
+export type { ErrorEnvelope } from './errorEnvelope.js';
+export { listEnvelope } from './listEnvelope.js';
+export type { ListEnvelope } from './listEnvelope.js';
+export type { CommitOperation, MutationMessage, CommitMessage, MutationResultMessage, } from './frames.js';
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, } from '../errors.js';
+export type { ErrorCode, WireErrorCode } from '../errors.js';

package/dist/wire/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@abloatai/ablo/wire` — the canonical HTTP/frame WIRE CONTRACT, with no
+ * client-runtime (mobx / react / IndexedDB) dependency, so a server-side
+ * consumer — a Next.js route handler, an edge function — can import the
+ * envelope producers without pulling in the whole sync client.
+ *
+ * Two halves, both Stripe-shaped and used across every Ablo surface:
+ *   - ERROR egress — {@link errorEnvelope} / {@link ErrorEnvelope} /
+ *     {@link statusForType} turn any thrown value into
+ *     `{ type, code, param, message, doc_url, request_id }`.
+ *   - LIST egress — {@link listEnvelope} / {@link ListEnvelope} stamp the
+ *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
+ *
+ * The {@link AbloError} hierarchy + {@link docUrlForCode} + the wire-PARSE
+ * helpers are re-exported so a route can THROW the right typed error and
+ * SERIALIZE it through a single import.
+ */
+export { errorEnvelope, statusForType } from './errorEnvelope.js';
+export { listEnvelope } from './listEnvelope.js';
+// The error surface a wire consumer needs to throw, classify, and serialize.
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, } from '../errors.js';

package/dist/wire/listEnvelope.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The canonical Ablo LIST envelope — the one shape every endpoint that returns
+ * a collection uses, so a consumer can detect + paginate any list uniformly
+ * instead of learning a per-endpoint payload key (`{ keys }`, `{ origins }`,
+ * `{ events }`, `{ buckets }`…).
+ *
+ * `{ object: 'list', data: [...], has_more, next_cursor }` is the shape the
+ * hosted `GET /v1/models/:model` endpoint already emits (apps/sync-server
+ * `routes/query.ts`) and that `@ablo/mcp` already consumes — promoted here so
+ * sync-web's dashboard lists, the SDK, and any future surface produce the
+ * identical envelope from one definition.
+ *
+ * The field NAMES are Stripe's (`object`/`has_more`/`next_cursor`), not
+ * PlanetScale's (`type`/`cursor_start`/`has_next`): the rest of the Ablo API is
+ * Stripe-modeled, so this keeps one vocabulary across the surface. The
+ * PlanetScale discipline we deliberately borrow is *"every list is the same
+ * envelope"* — not the concrete key names.
+ */
+export interface ListEnvelope<T> {
+    /** Discriminator — always `'list'`. Lets a generic client recognise a
+     *  paginated collection without per-endpoint special-casing. */
+    readonly object: 'list';
+    /** The page of results. Always present (an empty array when there are none),
+     *  never omitted, so `body.data` is a stable access path. */
+    readonly data: readonly T[];
+    /** Whether more results exist past this page. Drive "load more" off this,
+     *  not off `data.length === limit` (ambiguous on an exact-multiple page). */
+    readonly has_more: boolean;
+    /** Opaque cursor to pass back as `?starting_after=` for the next page, or
+     *  `null` when {@link has_more} is `false`. */
+    readonly next_cursor: string | null;
+}
+/**
+ * Stamp the uniform {@link ListEnvelope} onto an already-resolved page of rows.
+ *
+ * Pagination stays the caller's responsibility (fetch `limit + 1`, decide
+ * `hasMore`, derive the cursor from the last row's order key) — this only
+ * applies the envelope so no endpoint hand-rolls the shape. The defaults model
+ * the common "small, unpaginated collection" case (`has_more: false`,
+ * `next_cursor: null`); a paginated endpoint passes both explicitly.
+ */
+export declare function listEnvelope<T>(data: readonly T[], opts?: {
+    hasMore?: boolean;
+    nextCursor?: string | null;
+}): ListEnvelope<T>;

package/dist/wire/listEnvelope.js

@@ -0,0 +1,17 @@
+/**
+ * Stamp the uniform {@link ListEnvelope} onto an already-resolved page of rows.
+ *
+ * Pagination stays the caller's responsibility (fetch `limit + 1`, decide
+ * `hasMore`, derive the cursor from the last row's order key) — this only
+ * applies the envelope so no endpoint hand-rolls the shape. The defaults model
+ * the common "small, unpaginated collection" case (`has_more: false`,
+ * `next_cursor: null`); a paginated endpoint passes both explicitly.
+ */
+export function listEnvelope(data, opts = {}) {
+    return {
+        object: 'list',
+        data,
+        has_more: opts.hasMore ?? false,
+        next_cursor: opts.nextCursor ?? null,
+    };
+}

package/docs/api-keys.md

@@ -1,6 +1,6 @@
 # API Keys
 
-Trusted runtimes authenticate with an API key.
+Authenticate a server-side client — a route handler, worker, or CLI — by passing an API key when you create the client.
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -10,11 +10,11 @@ const ablo = Ablo({ apiKey: process.env.ABLO_API_KEY });
 
 The key identifies the Ablo account. Application code does not pass an organization id; Ablo derives scope from the credential.
 
-Use the root `@abloatai/ablo` import with a schema for app clients.
+"Trusted" means the runtime can hold a secret: a backend or other server-side environment a browser can't read. Browser and app clients use the same `@abloatai/ablo` import but authenticate differently — they never carry a secret key.
 
 ## Server-Side API Keys
 
-Use API keys from trusted runtimes:
+Use API keys from trusted (server-side) runtimes:
 
 - backend route handlers
 - workers and agents
@@ -48,8 +48,8 @@ restricted to exactly those grants:
   high-risk, org-wide grant: because schema is shared, a push affects the live
   table shape. A full-authority key has it implicitly; a *restricted* key (such
   as a sandbox key) needs it granted explicitly.
-- `sandbox:<id>` — marks the key as belonging to a sandbox (its data isolation
-  comes from the sandbox binding, not this scope string).
+- `sandbox:<id>` — identifies which sandbox the key belongs to. (The key's data
+  isolation comes from that sandbox binding, not from this scope string.)
 
 A key minted from the default **Test mode** sandbox carries `schema:push`, so
 `ablo dev` works out of the box. Keys from other sandboxes are **data-only** by

package/docs/api.md

@@ -1,10 +1,21 @@
 # API
 
-Start with the schema client:
-
-For end-to-end app setup across React, existing backends, Data Source, and
-agents, read [Integration Guide](./integration-guide.md).
+This is the per-method reference for reading and writing rows that stay in
+sync across sessions. You declare your models once, then call the same
+`ablo.<model>` methods from React, a server action, or an agent — and every
+confirmed write streams to everyone watching. When two writers touch the same
+row, you can optionally `claim` it so they serialize instead of clobbering
+each other.
+
+Two things to know before the method list. **Reads come in two flavors:**
+`retrieve(id)` / `list({ where })` are async and hit the server (use them when
+the row may not be local yet); `get(id)` / `getAll({ where })` / `getCount({ where })`
+are synchronous reads off the local graph (use them in render, after data has
+synced). **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.
 
+Start with the schema client:
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -20,39 +31,46 @@ const schema = defineSchema({
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 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('Row not found');
 
-await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
 ```
 
+For end-to-end app setup across React, existing backends, Data Source, and
+agents, read the [Integration Guide](./integration-guide.md).
+
 ## Model Methods
 
 Each schema model becomes a typed model on the client:
 
-- `ablo.weatherReports.load({ where })` hydrates rows asynchronously.
-- `ablo.weatherReports.retrieve(id)` reads one already-loaded row synchronously.
-- `ablo.weatherReports.create(data)` creates a row.
-- `ablo.weatherReports.update(id, data, options?)` updates a row.
-- `ablo.weatherReports.delete(id, options?)` deletes a row.
+- `ablo.weatherReports.retrieve({ id })` reads one row asynchronously (server read).
+- `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
+- `ablo.weatherReports.get(id)` reads one row synchronously from the local graph.
+- `ablo.weatherReports.create({ data })` creates a row.
+- `ablo.weatherReports.update({ id, data, ...options })` updates a row.
+- `ablo.weatherReports.delete({ id, ...options })` deletes a row.
 
-`load` and `retrieve` are not aliases. Use `load` when the row may not be loaded
-yet. Use `retrieve` after `ready()` or `load()` when you want a cheap
-synchronous read.
+`retrieve`/`list` and `get`/`getAll`/`getCount` are not aliases. Use
+`retrieve({ id })` or `list({ where })` when the row may not be local yet — they
+hydrate pool → IndexedDB → network. Use `get(id)` / `getAll({ where })` /
+`getCount({ where })` for a cheap synchronous snapshot of what is already in
+the local graph.
 
 | Method | Returns | Use when |
 |---|---|---|
-| `load({ where })` | `Promise<T[]>` | You need to hydrate rows from local store and server. |
-| `retrieve(id)` | `T \| undefined` | You already loaded the row and want a synchronous read. |
-| `list(options?)` | `T[]` | You want a synchronous list of loaded rows. |
-| `count(options?)` | `number` | You want a synchronous count of loaded rows. |
-| `create(data, options?)` | `Promise<T>` | You want to create through the schema model. |
-| `update(id, data, options?)` | `Promise<T>` | You want to update through the schema model. |
-| `delete(id, options?)` | `Promise<void>` | You want to delete through the schema model. |
-
-`load`, `create`, `update`, and `delete` are the main path — they go through the
-server. `retrieve` / `list` / `count` are **synchronous reads** off the rows a
-session has already loaded, so a cheap re-read needs no round-trip.
+| `retrieve({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
+| `list({ where })` | `Promise<T[]>` | You need to hydrate a collection from local store and server. |
+| `get(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
+| `getAll(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
+| `getCount(options?)` | `number` | You want a synchronous count of local rows. |
+| `create({ data, ...options })` | `Promise<T>` | You want to create through the schema model. |
+| `update({ id, data, ...options })` | `Promise<T>` | You want to update through the schema model. |
+| `delete({ id, ...options })` | `Promise<void>` | You want to delete through the schema model. |
+
+`retrieve`, `list`, `create`, `update`, and `delete` are the main path — they go
+through the server. `get` / `getAll` / `getCount` are **synchronous reads**
+off the rows a session has already synced, so a cheap re-read needs no round-trip.
 
 ## Protected Writes
 
@@ -61,11 +79,13 @@ Use `snapshot` when a write should reject if the row changed mid-flight:
 ```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',
+});
 ```
 
 Protected write options:
@@ -80,23 +100,26 @@ Protected write options:
 
 ## Claims
 
-A claim tells humans and agents who is working on a target before the write
-lands. One self-describing object carries the lifecycle in a single `status`
-field. It lives on the coordination plane: ephemeral, TTL'd, broadcast to peers
-in real time, and never persisted as a row.
+Before anyone writes a row, they can claim it so other people and agents see
+who is editing it in real time. 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. A claim is temporary: it expires
+on its own if the holder stops, and is never saved as a row.
 
-Coordinate one through flat verbs on the model, beside `create`/`update`/`retrieve`:
-`ablo.<model>.claim(id, ...)` to claim a row, `ablo.<model>.claimState(id)` to read
-who holds it (synchronous; never blocks), and `ablo.<model>.release(id)` to release
-early. Claims are **advisory** — they serialize on contention rather than locking.
+You coordinate a row with calls on its model, beside `create`/`update`/`retrieve`:
+`ablo.<model>.claim({ id })` takes the claim and returns a handle,
+`ablo.<model>.claim.state({ id })` reads who currently holds it (synchronous, never
+blocks), and `ablo.<model>.claim.release({ id })` releases it early. The full
+coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
+`claim.release({ id })` / `claim.reorder({ id, order })` hanging off `claim`.
 
 ### The Claim State Object
 
 | Field | Type | Description |
 |---|---|---|
-| `object` | `'claim'` | String representing the object's type. |
+| `object` | `'intent'` | String representing the object's type. |
 | `id` | string | Unique identifier for the claim. |
-| `status` | `'active' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. |
+| `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
 | `target` | `{ type, id, field? }` | What is being coordinated. |
 | `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
 | `heldBy` | string | Participant id holding the claim. |
@@ -105,7 +128,7 @@ early. Claims are **advisory** — they serialize on contention rather than lock
 
 ```json
 {
-  "object": "claim",
+  "object": "intent",
   "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
   "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
@@ -119,7 +142,7 @@ early. Claims are **advisory** — they serialize on contention rather than lock
 ### Lifecycle
 
 ```
-            claim(id)                  update(id) lands
+            claim({ id })              update({ id }) lands
   (free) ───────────▶ active ───────────────────────▶ committed
                         │
             ┌───────────┴───────────┐
@@ -128,45 +151,82 @@ early. Claims are **advisory** — they serialize on contention rather than lock
    (release w/o write)        (TTL; holder died)
 ```
 
-A target is free when `ablo.<model>.claimState(id)` is `null`. Terminal
-states drop out of the live stream, so a present claim is active.
+A target is free when `ablo.<model>.claim.state({ id })` is `null`. Terminal
+states drop out of the live stream, so a present claim is either `active` (the
+holder) or `queued` (waiting in the FIFO line behind the holder; see
+`claim.queue({ id })`).
 
 ### Reading and claiming
 
-`claimState(id)` is the read side for observers: synchronous, never blocks, and
-returns the live claim state object (or `null`). `claim(id, ...)` is the write side:
-it claims the row and returns the row. Because the claim is **advisory**, if
-someone else already holds the row, `claim` waits for them to finish, then
-re-reads the row before handing it back — so you always proceed from fresh state.
-Default reads stay open; server/model reads can opt into `ifClaimed: 'wait'` or
-`ifClaimed: 'fail'` when they should not read through active work.
+`claim.state({ id })` is the read side for observers: synchronous, never blocks, and
+returns the live claim state object (or `null`). `claim({ id })` is the write
+side: it takes the claim and returns a `ClaimHandle`. Claims don't lock — if someone else
+already holds the row, `claim` waits for them to finish, re-reads the fresh row,
+then hands it to you, so you always proceed from current state. Default reads
+return the row even while someone is mid-edit; if a server read should not
+return a row while it's claimed, pass `ifClaimed: 'wait'` to wait for the claim
+to clear, or `ifClaimed: 'fail'` to error out instead.
 
 ```ts
-const claim = ablo.weatherReports.claimState('report_stockholm');
+const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (claim) {
   claim.heldBy;
   claim.action;
 }
 
-const updated = await ablo.weatherReports.claim(
-  'report_stockholm',
-  async (report) => ablo.weatherReports.update(report.id, { status: 'ready' }),
-  { action: 'editing', ttl: '2m' },
-);
+const handle = await ablo.weatherReports.claim({
+  id: 'report_stockholm',
+  action: 'editing',
+  ttl: '2m',
+});
+await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await handle.release();
 ```
 
-Writes go through the normal flat `ablo.<model>.update(id, data)`. While you hold
-a claim on `id`, that `update` is automatically stale-guarded: it rejects with
-`AbloStaleContextError` if the row advanced past your claim point, so you re-read
-before retrying. The callback form releases automatically when the callback
-returns or throws, or call `ablo.weatherReports.release(id)` if you claimed manually and
-need to release early.
+Writes go through the normal `ablo.<model>.update({ id, data })`. While you hold
+a claim on `id`, that `update` rejects with `AbloStaleContextError` if the row
+changed underneath you since you took the claim, so you re-read before retrying.
+Call `handle.release()` (or `ablo.weatherReports.claim.release({ id })`) to release
+the claim when your work is done.
 
 ## Agent
 
 Most agents should import the same schema as the app and call
-`ablo.<model>.load(...)`, `ablo.<model>.claim(...)`, and
-`ablo.<model>.update(...)`.
+`ablo.<model>.list(...)`, `ablo.<model>.claim({ id })`, and
+`ablo.<model>.update({ id, data })`.
+
+## HTTP API
+
+The SDK is a convenience wrapper over a model-scoped HTTP surface — the same
+noun (`model`) and verbs as `ablo.<model>.…`. Non-JS callers (or curl) use it
+directly. The table below shows the shape with `{model}` as a placeholder; the
+[OpenAPI spec](./openapi.json) expands it into one **typed** path per model
+(`/v1/models/task`, `/v1/models/deck`, …, generated from your schema) so each
+endpoint documents that model's real field contract instead of a generic blob.
+
+| SDK call | HTTP |
+|---|---|
+| `ablo.<model>.create({ data })` | `POST /v1/models/{model}` |
+| `ablo.<model>.list({ where })` | `GET /v1/models/{model}` |
+| `ablo.<model>.retrieve({ id })` | `GET /v1/models/{model}/{id}` |
+| `ablo.<model>.update({ id, data })` | `PATCH /v1/models/{model}/{id}` |
+| `ablo.<model>.delete({ id })` | `DELETE /v1/models/{model}/{id}` |
+| `ablo.<model>.claim({ id })` | `POST /v1/models/{model}/{id}/claim` |
+| (release a claim) | `DELETE /v1/models/{model}/{id}/claim` |
+
+Auth is a bearer API key: `Authorization: Bearer sk_…`. Mutations take an
+`Idempotency-Key` header — derive it from the business event, not a random
+value, so a retry never double-writes. Writes return a `CommitReceipt`; a
+rejected write carries an error `code` (e.g. `stale_context`, `intent_conflict`)
+to act on. `GET /v1/models/{model}` is cursor-paginated (`limit`, `order`,
+`order_by`, `starting_after`) and returns `{ data, has_more, next_cursor }`.
+
+`POST /v1/commits` remains the path for **atomic multi-op** writes (several
+operations across rows/models that must commit together) — the per-model routes
+above are the one-record path. Both run the identical guarded-write engine.
+
+The [coordination MCP server](./mcp.md) (`@ablo/mcp`) is this same surface
+rendered as agent tools.
 
 ## Errors