@abloatai/ablo 0.6.0 → 0.8.0

package/dist/sync/createIntentStream.js

@@ -11,7 +11,8 @@
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
  *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId } }`
+ *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
+ *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
  *     stamped with `declaredAt`, `expiresAt`.
  *   • Inbound: `intent_rejected` event with conflict metadata.
@@ -38,6 +39,7 @@ export function createIntentStream(config, transport = null) {
     // ── Subscribers ──────────────────────────────────────────────────
     const listeners = new Set();
     const rejectionListeners = new Set();
+    const lostListeners = new Set();
     const notifyListeners = () => {
         intentsSnapshot = Object.freeze(Array.from(activeByIntentId.values()));
         for (const l of listeners) {
@@ -131,6 +133,24 @@ export function createIntentStream(config, transport = null) {
                 }
             }
         }));
+        // (2a) Server-side LOSS frames — you held it, then lost it (preempted /
+        //      expired). Distinct from a rejection (a claim the server refused).
+        unsubs.push(t.subscribe('intent_lost', (payload) => {
+            const lost = payload;
+            if (!lost.intentId)
+                return;
+            // Drop the lost own-claim so reconnect doesn't re-announce a lease we
+            // no longer hold.
+            ownIntents.delete(lost.intentId);
+            for (const l of lostListeners) {
+                try {
+                    l(lost);
+                }
+                catch {
+                    /* isolate */
+                }
+            }
+        }));
         // (2b) Per-entity wait-queue snapshots. The server fans the full line
         //      out on every queue mutation; we replace our cached line for that
         //      entity and notify so `queue(target)` reads reactively.
@@ -178,6 +198,20 @@ export function createIntentStream(config, transport = null) {
             },
         });
     }
+    function sendReorder(entityType, entityId, order) {
+        if (!attached?.isConnected())
+            return;
+        attached.send({
+            type: 'intent_reorder',
+            payload: {
+                entityType,
+                entityId,
+                // The wire shape identifies a waiter by heldBy + intentId; map the
+                // ergonomic `Intent[]` (what `queueFor` returns) down to that.
+                order: order.map((i) => ({ heldBy: i.heldBy, intentId: i.id })),
+            },
+        });
+    }
     function sendAbandon(intentId, intent) {
         if (!attached?.isConnected())
             return;
@@ -252,6 +286,10 @@ export function createIntentStream(config, transport = null) {
             const ref = resolveTarget(target);
             return queueByEntity.get(entityKey(ref.type, ref.id)) ?? EMPTY_QUEUE;
         },
+        reorder(target, order) {
+            const ref = resolveTarget(target);
+            sendReorder(ref.type, ref.id, order);
+        },
         onChange: (listener) => {
             listeners.add(listener);
             return () => {
@@ -264,6 +302,12 @@ export function createIntentStream(config, transport = null) {
                 rejectionListeners.delete(listener);
             };
         },
+        onLost: (listener) => {
+            lostListeners.add(listener);
+            return () => {
+                lostListeners.delete(listener);
+            };
+        },
         [Symbol.asyncIterator]() {
             return asyncIteratorFrom((onChange) => {
                 listeners.add(onChange);
@@ -279,6 +323,7 @@ export function createIntentStream(config, transport = null) {
             unsubs.length = 0;
             listeners.clear();
             rejectionListeners.clear();
+            lostListeners.clear();
             activeByIntentId.clear();
             ownIntents.clear();
             queueByEntity.clear();

package/dist/sync/participants.js

@@ -1,3 +1,5 @@
+import { scopeKindOf } from '../schema/model.js';
+import { AbloConnectionError, AbloValidationError } from '../errors.js';
 export function createParticipantManager(config) {
     return {
         async join(input, overrides) {
@@ -9,7 +11,7 @@ export function createParticipantManager(config) {
             await config.ready();
             const transport = config.getTransport();
             if (!transport) {
-                throw new Error('Ablo participant join failed: WebSocket is not connected');
+                throw new AbloConnectionError('Ablo participant join failed: WebSocket is not connected', { code: 'ws_not_ready' });
             }
             const claimId = createParticipantClaimId();
             if (syncGroups.length > 0) {
@@ -74,17 +76,13 @@ export function resolveParticipantSyncGroups(scope, schema) {
 }
 export function syncGroupFromEntityRef(ref, schema) {
     const match = findModelForEntityRef(ref, schema);
-    if (match?.def.syncGroupFormat) {
-        return renderSyncGroupFormat(match.def.syncGroupFormat, { id: ref.id });
-    }
-    return `${ref.type.toLowerCase()}:${ref.id}`;
+    const kind = match ? scopeKindOf(match.def, match.key) : undefined;
+    return `${kind ?? ref.type.toLowerCase()}:${ref.id}`;
 }
 function syncGroupFromSchemaKey(schemaKey, id, schema) {
     const def = schema?.models?.[schemaKey];
-    if (def?.syncGroupFormat) {
-        return renderSyncGroupFormat(def.syncGroupFormat, { id });
-    }
-    return `${schemaKey}:${id}`;
+    const kind = def ? scopeKindOf(def, schemaKey) : undefined;
+    return `${kind ?? schemaKey}:${id}`;
 }
 function findModelForEntityRef(ref, schema) {
     if (!schema?.models)
@@ -98,12 +96,6 @@ function findModelForEntityRef(ref, schema) {
     }
     return null;
 }
-function renderSyncGroupFormat(format, values) {
-    return format.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, key) => {
-        const value = values[key];
-        return value === undefined ? `{${key}}` : value;
-    });
-}
 export function parseParticipantTtlSeconds(value) {
     if (typeof value === 'number' && Number.isFinite(value))
         return value;
@@ -163,7 +155,9 @@ function createJoinedParticipant(args) {
     const requireTarget = (target) => {
         const resolved = target ? targetToEntityRef(target) : currentTarget;
         if (!resolved) {
-            throw new Error('Participant action requires a structured target');
+            throw new AbloValidationError('Participant action requires a structured target', {
+                code: 'invalid_request',
+            });
         }
         return resolved;
     };

package/dist/transactions/TransactionQueue.js

@@ -12,7 +12,7 @@ import { getContext } from '../context.js';
 import { getActiveRegistry } from '../ModelRegistry.js';
 import { MutationOperationType } from '../types/index.js';
 import { handleMutationError } from './mutation-error-handler.js';
-import { AbloError, AbloConnectionError } from '../errors.js';
+import { AbloError, AbloConnectionError, errorCodeSpec } from '../errors.js';
 /**
  * Framework-internal keys added by `Model.toJSON()` that must never
  * reach the wire. The server treats each top-level key as a target
@@ -1482,6 +1482,18 @@ export class TransactionQueue extends EventEmitter {
         if (error instanceof AbloConnectionError) {
             return false;
         }
+        // Registry-driven retryability is authoritative when the error carries a
+        // known wire code: the error contract (errorCodes.ts) decides whether the
+        // same request can succeed on retry, not message string-matching. This is
+        // why rejected commits must arrive as typed AbloErrors (see
+        // `errorFromWire`) — a bare `Error` has no code and falls through to the
+        // heuristics below. Unknown / forward-compat codes (`errorCodeSpec`
+        // returns undefined) also fall through, preserving the safe default.
+        if (error instanceof AbloError && error.code) {
+            const spec = errorCodeSpec(error.code);
+            if (spec)
+                return !spec.retryable;
+        }
         const message = error?.message?.toLowerCase() || '';
         // Network/connection errors are transient - retry these
         const isNetworkError = message.includes('failed to fetch') ||

package/dist/types/streams.d.ts

@@ -9,6 +9,8 @@
  * the shared coordination substrate.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
+import type { TargetRange, OnStaleMode, IntentClaim, PresenceKind } from '../coordination/schema.js';
+export type { TargetRange, OnStaleMode, IntentClaim, PresenceKind };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form
  * metadata that will be persisted / transported as JSON — avoids
@@ -113,13 +115,6 @@ export interface ContextChange {
  * snapshot. Defaults to `'reject'` when `readAt` is provided without
  * `onStale`.
  */
-export type OnStaleMode = 'reject' | 'flag' | 'merge' | 'force';
-export interface TargetRange {
-    readonly startLine: number;
-    readonly endLine: number;
-    readonly startColumn?: number;
-    readonly endColumn?: number;
-}
 /**
  * A pointer to one entity, optionally narrowed to a structured
  * subtarget. `type` and `id` are customer schema vocabulary; `path`,
@@ -304,32 +299,6 @@ export interface Peer {
     /** Pending-mutation intents this participant has declared. */
     readonly activeIntents?: ReadonlyArray<IntentClaim>;
 }
-/**
- * Pending-mutation intent on the wire. Declared via `intent_begin`,
- * cleared on `intent_abandon` / commit / disconnect / TTL expiry.
- * Server stamps `declaredAt` and `expiresAt` (ms epoch). The SDK's
- * `IntentStream.others` exposes a richer `ActiveIntent` view (defined
- * below) that adds `heldBy` so callers know which participant owns it.
- */
-export interface IntentClaim {
-    readonly intentId: string;
-    readonly entityType: string;
-    readonly entityId: string;
-    readonly path?: string;
-    readonly range?: TargetRange;
-    readonly action: string;
-    readonly field?: string;
-    readonly meta?: Record<string, unknown>;
-    readonly declaredAt: number;
-    readonly expiresAt: number;
-}
-/**
- * Transition type carried on every presence frame from the server.
- *   - `'enter'`  — first frame the receiver sees for this peer.
- *   - `'update'` — activity / intent change on an already-known peer.
- *   - `'leave'`  — peer departed (explicit disconnect or TTL expiry).
- */
-export type PresenceKind = 'enter' | 'update' | 'leave';
 /** Outbound `presence_update` payload. */
 export interface PresenceUpdatePayload {
     readonly status: 'online' | 'away' | 'offline' | (string & {});
@@ -411,6 +380,15 @@ export interface IntentStream {
      * `subscribe(...)` for change notifications.
      */
     queueFor(target: PresenceTarget): readonly Intent[];
+    /**
+     * Re-rank the wait queue on a target — move the listed waiters to the front
+     * in the given order; unlisted waiters keep their relative FIFO order behind
+     * them. Pass the `Intent[]` from `queueFor(target)` in the order you want
+     * (each `Intent` carries its `heldBy` + `id`). Privileged: the server gates
+     * it (a participant lacking the `intent.reorder` capability is denied), so
+     * this is fire-and-forget — the new order arrives reactively via `queueFor`.
+     */
+    reorder(target: PresenceTarget, order: readonly Intent[]): void;
     /**
      * Framework-agnostic reactivity. Same contract as
      * `PresenceStream.subscribe` — register a listener fired on every
@@ -435,6 +413,23 @@ export interface IntentStream {
      * Returns an unsubscribe fn.
      */
     onRejected(listener: (rejection: IntentRejection) => void): () => void;
+    /**
+     * Observe LOSING an intent you held — distinct from `onRejected` (a claim the
+     * server refused). Fires on the server's `intent_lost` frame, carrying why:
+     * `'preempted'` (a privileged participant evicted you) or `'expired'` (your
+     * TTL lapsed). Lets a holder react — re-plan vs re-claim — instead of
+     * silently discovering the lease gone via presence.
+     *
+     * ```ts
+     * participant.intents.onLost((lost) => {
+     *   if (lost.reason === 'preempted') replanAgainst(lost.target);
+     *   else reclaim(lost.target);
+     * });
+     * ```
+     *
+     * Returns an unsubscribe fn.
+     */
+    onLost(listener: (lost: IntentLost) => void): () => void;
     /**
      * Async-iterable view of everyone else's open intents. Each
      * iteration yields the current snapshot on every mutation.
@@ -473,6 +468,31 @@ export interface IntentRejection {
     /** When the existing claim expires (ms since epoch). */
     readonly heldByExpiresAt: number;
 }
+/**
+ * You LOST an intent you were HOLDING — distinct from `IntentRejection` (a
+ * claim the server refused you). Delivered via `onLost`.
+ */
+export interface IntentLost {
+    /** The held claim's id that you just lost. */
+    readonly intentId: string;
+    /**
+     * How you lost it. `'preempted'`: a privileged participant (one holding the
+     * `intent.preempt` capability) evicted you and took the lease — its work now
+     * supersedes yours, so re-plan against the new holder rather than blindly
+     * re-claiming. `'expired'`: your TTL lapsed without finishing — re-claim if
+     * you still need it.
+     */
+    readonly reason: 'expired' | 'preempted';
+    /** The target you no longer hold. */
+    readonly target: {
+        readonly entityType: string;
+        readonly entityId: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly field?: string;
+        readonly meta?: Record<string, unknown>;
+    };
+}
 export interface IntentDeclaration {
     readonly target: EntityRef;
     /** Human-readable reason — "rewriting title" / "restyling chart". */

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
@@ -22,3 +22,47 @@ Use API keys from trusted runtimes:
 - webhooks
 
 Never ship a secret API key to a browser bundle.
+
+## Test mode and sandboxes
+
+Test and live keys are the same shape; the prefix names the environment:
+
+- `sk_test_…` — a key bound to a **sandbox**. Its reads and writes are isolated
+  to that sandbox and are invisible to live keys (and to other sandboxes).
+- `sk_live_…` — a key against your live data.
+
+Every org has a default **Test mode** sandbox, plus any number of additional
+sandboxes you create. **Data is isolated per sandbox; the schema is shared
+across the whole org.** A schema you push from a test key defines the same
+models your live keys see — only the rows differ. This mirrors how Stripe
+separates test and live data while keeping the API shape identical.
+
+## Scopes
+
+Keys carry scopes following the principle of least privilege — each key gets
+only what its job needs. A secret key with **no scopes** has full org authority
+(the default for a `sk_live_` backend key); a key with a non-empty scope set is
+restricted to exactly those grants:
+
+- `schema:push` — author the org schema (`ablo schema push`, `ablo dev`). A
+  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>` — 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
+default — enable "schema authoring" when minting if you want that key to push
+schema too. Hand data-only keys to embedded apps and CI agents; reserve
+schema-authoring keys for the developer running `ablo dev`.
+
+### `ablo dev`
+
+```sh
+ABLO_API_KEY=sk_test_… npx ablo dev
+```
+
+Pushes your `ablo/schema.ts` to the test sandbox, prints the one line you need
+in `.env.local`, and re-pushes on every save. It refuses `sk_live_` keys so a
+tight save loop can never churn production data.

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,47 +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('report_stockholm');
 if (!report) throw new Error('Row not found');
 
 await ablo.weatherReports.update('report_stockholm', { 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.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 in the
-local pool yet. Use `retrieve` after `ready()` or `load()` when you want a cheap
-local 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 local read. |
-| `list(options?)` | `T[]` | You want a synchronous local list. |
-| `count(options?)` | `number` | You want a synchronous local count. |
+| `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. |
 
-`list` and `count` read the local pool. They default to live rows and accept:
-
-```ts
-const readyReports = ablo.weatherReports.list({
-  where: { status: 'ready' },
-  filter: (report) => !report.location.startsWith('[archived]'),
-  orderBy: { updatedAt: 'desc' },
-  limit: 20,
-  scope: 'live', // 'live' | 'archived' | 'all'
-});
-```
+`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
 
@@ -88,23 +98,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, work)` takes the claim and runs your work,
+`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. |
@@ -113,7 +126,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" },
@@ -136,49 +149,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, work)` is the write
+side: it takes the claim and returns the row. 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
-// Read side — who is working on this target right now?
-const claim = ablo.weatherReports.claimState('report_stockholm');
+const claim = ablo.weatherReports.claim.state('report_stockholm');
 if (claim) {
-  claim.heldBy; // 'agent:report-writer'
-  claim.action; // 'editing'
+  claim.heldBy;
+  claim.action;
 }
 
-// Write side — claim for the duration of the callback.
 const updated = await ablo.weatherReports.claim(
   'report_stockholm',
   async (report) => ablo.weatherReports.update(report.id, { status: 'ready' }),
   { action: 'editing', ttl: '2m' },
 );
-updated.status; // 'ready'
 ```
 
-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
+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.
+The callback form releases the claim automatically when the callback returns or
+throws; call `ablo.weatherReports.claim.release(id)` if you claimed manually and
 need to release early.
 
 ## Agent
 
 Most agents should import the same schema as the app and call
-`ablo.<model>.load(...)`, `ablo.<model>.claim(...)`, and
+`ablo.<model>.list(...)`, `ablo.<model>.claim(...)`, and
 `ablo.<model>.update(...)`.
 
+## 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
 
 All SDK errors extend `AbloError` and expose a stable `type` string.