@abloatai/ablo 0.7.0 → 0.8.0

package/dist/sync/NetworkProbe.d.ts

@@ -27,6 +27,14 @@ export interface ProbeResult {
     reachable: boolean;
     /** Whether the session cookie is still valid (null if server unreachable) */
     sessionValid: boolean | null;
+    /**
+     * Reachable, but a NON-retryable auth/config failure that is NOT a session
+     * expiry (e.g. `api_key_required`, `jwt_issuer_untrusted`). The session is
+     * fine — the data-plane rejected the credential TYPE — so neither
+     * reconnecting nor re-authenticating will help. The manager stops instead of
+     * looping. Distinct from `sessionValid: false` (genuine expiry → sign in).
+     */
+    authBlocked?: boolean;
     /** Round-trip time in ms (null if failed) */
     latencyMs: number | null;
 }

package/dist/sync/NetworkProbe.js

@@ -22,7 +22,7 @@
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
 import { getContext } from '../context.js';
-import { SyncSessionError } from '../errors.js';
+import { SyncSessionError, isRetryableCode } from '../errors.js';
 const PROBE_TIMEOUT_MS = 4000;
 /**
  * Derive the probe URL from a sync-server base URL. Accepts `ws://`,
@@ -72,7 +72,17 @@ export async function probeNetwork(baseUrl) {
             headers: { 'Cache-Control': 'no-cache' },
         });
         const latencyMs = Math.round(performance.now() - start);
-        if (SyncSessionError.isSessionErrorResponse(response.status)) {
+        // The probe is a HEAD (no body), but the sync-server sets `X-Auth-Failure:
+        // <code>` on every auth rejection — feed that to the code-aware detector so
+        // only a genuine session/JWT EXPIRY marks the session invalid. A non-expiry
+        // auth failure (e.g. api_key_required, jwt_issuer_untrusted) leaves
+        // sessionValid alone — the user IS logged in; signing them out wouldn't fix
+        // a credential-type/config problem and just bounces them to /signin.
+        const authFailure = response.headers.get('x-auth-failure');
+        const failureBody = authFailure
+            ? JSON.stringify({ code: authFailure })
+            : undefined;
+        if (SyncSessionError.isSessionErrorResponse(response.status, failureBody)) {
             // Server reachable but session expired/invalid
             getContext().logger.info('[NetworkProbe] Server reachable, session expired', {
                 status: response.status,
@@ -80,6 +90,18 @@ export async function probeNetwork(baseUrl) {
             });
             return { reachable: true, sessionValid: false, latencyMs };
         }
+        // Reachable, but a NON-retryable auth/config failure that is NOT a session
+        // expiry (api_key_required, jwt_issuer_untrusted, …). Re-auth won't fix it
+        // and retrying won't either — signal authBlocked so the manager STOPS
+        // rather than reconnect-looping or signing the user out.
+        if (authFailure && !isRetryableCode(authFailure)) {
+            getContext().logger.warn('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                status: response.status,
+                code: authFailure,
+                latencyMs,
+            });
+            return { reachable: true, sessionValid: true, authBlocked: true, latencyMs };
+        }
         // 2xx (including 204) means reachable + session valid.
         // 3xx/4xx (non-auth) still prove connectivity even though the probe
         // expected 204; log a warning so misconfigurations surface instead of

package/dist/sync/SyncWebSocket.d.ts

@@ -271,7 +271,7 @@ export interface CoreSyncEventMap {
     /**
      * Per-entity wait-queue snapshot: `{ target, queue: Intent[] }` with each
      * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
-     * queue mutation — powers the reactive `ablo.<model>.queue(id)` read.
+     * queue mutation — powers the reactive `ablo.<model>.claim.queue(id)` read.
      */
     intent_queue: [Record<string, unknown>];
     intent_acquired: [Record<string, unknown>];

package/dist/sync/SyncWebSocket.js

@@ -10,7 +10,7 @@
 import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
-import { AbloClaimedError, CapabilityError, SyncSessionError, } from '../errors.js';
+import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
 // Consumers pass their own event types as TCollaboration generic parameter.
@@ -214,7 +214,7 @@ export class SyncWebSocket extends EventEmitter {
             const errorMessage = error instanceof Error ? error.message : 'Failed to create WebSocket';
             getContext().observability.captureWebSocketError({ context: 'create-websocket', error: errorMessage });
             this.isConnecting = false;
-            this.emit('error', new Error(errorMessage));
+            this.emit('error', new AbloConnectionError(errorMessage, { cause: error }));
             this.scheduleReconnect();
         }
     }
@@ -360,38 +360,19 @@ export class SyncWebSocket extends EventEmitter {
                             else {
                                 errorMessage = 'mutation failed on server';
                             }
-                            // Capability denials route through the typed CapabilityError
-                            // so callers can `instanceof CapabilityError` and read
-                            // `.requiredCapability` to attenuate-and-retry without
-                            // string-matching the error code.
-                            if (errorCode === 'capability_scope_denied' ||
-                                errorCode === 'capability_invalid') {
-                                pending.reject(new CapabilityError(errorCode, errorMessage, requiredCapability));
-                            }
-                            else if (errorCode === 'intent_conflict' ||
-                                errorCode === 'claim_conflict' ||
-                                errorCode === 'entity_claimed') {
-                                // Claim enforcement: another participant holds a live claim on
-                                // a targeted entity. Two server layers reject this — the Hub's
-                                // pre-commit lease check (`intent_conflict`, the code that
-                                // reaches clients in practice) and `executeCommit`'s deeper
-                                // guard (`entity_claimed`). Both mean "claimed", so both route
-                                // through the typed AbloClaimedError, letting callers
-                                // `instanceof AbloClaimedError` (or read `e.type` across worker
-                                // boundaries) and wait/bypass — symmetric with the
-                                // CapabilityError branch above, and with the HTTP commit path
-                                // (`translateHttpError`).
-                                pending.reject(new AbloClaimedError(errorMessage, {
-                                    code: errorCode === 'intent_conflict' ? 'claim_conflict' : errorCode,
-                                    httpStatus: 409,
-                                }));
-                            }
-                            else {
-                                const rejection = new Error(errorMessage);
-                                if (errorCode)
-                                    rejection.code = errorCode;
-                                pending.reject(rejection);
-                            }
+                            // Build the proper typed AbloError from the wire code via the
+                            // shared factory — the same code→class mapping the HTTP commit
+                            // path uses (`translateHttpError`). This keeps rejected commits
+                            // inside the typed hierarchy (capability denials →
+                            // CapabilityError with `.requiredCapability`; foreign-claim
+                            // conflicts → AbloClaimedError; everything else → the subclass
+                            // its registry `httpStatus` implies) instead of a hand-rolled
+                            // `new Error`, so callers can `instanceof`/`e.type` it and
+                            // downstream retry logic can read the contract's retryability.
+                            pending.reject(errorFromWire(errorMessage, {
+                                code: errorCode,
+                                requiredCapability,
+                            }));
                         }
                         break;
                     }
@@ -438,11 +419,10 @@ export class SyncWebSocket extends EventEmitter {
                                 pending.reject(new CapabilityError(code, msg, requiredCapability));
                             }
                             else {
-                                // Attach `code` as a property on the rejection so callers
-                                // can discriminate (`scope_conflict`, `malformed_claim`,
-                                // ...) without parsing the message.
-                                const rejection = Object.assign(new Error(`${code}: ${msg}`), { code });
-                                pending.reject(rejection);
+                                // Route through the shared factory so a failed claim_ack is a
+                                // typed AbloError (registry code → right subclass), symmetric
+                                // with the commit `mutation_result` path — never a bare Error.
+                                pending.reject(errorFromWire(msg, { code }));
                             }
                         }
                         break;
@@ -539,12 +519,12 @@ export class SyncWebSocket extends EventEmitter {
             // Check if we're offline first
             if (!getContext().onlineStatus.isOnline()) {
                 getContext().observability.breadcrumb('WebSocket error: Network is offline', 'sync.websocket', 'warning');
-                this.emit('error', new Error('Network is offline'));
+                this.emit('error', new AbloConnectionError('Network is offline', { code: 'bootstrap_offline' }));
                 return;
             }
             // After session error, suppress Sentry capture — the root cause is already reported.
             // Still emit so SyncedStore can update UI state.
-            const error = new Error(`WebSocket connection failed`);
+            const error = new AbloConnectionError(`WebSocket connection failed`);
             if (!this._sessionErrorDetected) {
                 getContext().observability.captureWebSocketError({
                     context: 'connection-error',
@@ -578,12 +558,16 @@ export class SyncWebSocket extends EventEmitter {
             if (this.pendingMutations.size > 0) {
                 for (const pending of this.pendingMutations.values()) {
                     clearTimeout(pending.timeout);
-                    pending.reject(Object.assign(new Error(`WebSocket closed while commit was in flight (code=${event.code}` +
+                    // AbloConnectionError → `isPermanentError` treats it as transient,
+                    // so TransactionQueue retries the commit on reconnect rather than
+                    // rolling it back. `diagnostics` is preserved as a property (the
+                    // queue's failure log walks the cause chain for it).
+                    pending.reject(Object.assign(new AbloConnectionError(`WebSocket closed while commit was in flight (code=${event.code}` +
                         (event.reason ? ` reason=${event.reason}` : '') +
                         (this.lastForceCloseReason
                             ? ` forceCloseReason=${this.lastForceCloseReason}`
                             : '') +
-                        ')'), { diagnostics: this.getConnectionDiagnostics() }));
+                        ')', { code: 'commit_no_result' }), { diagnostics: this.getConnectionDiagnostics() }));
                 }
                 this.pendingMutations.clear();
             }
@@ -594,7 +578,7 @@ export class SyncWebSocket extends EventEmitter {
             if (this.pendingClaims.size > 0) {
                 for (const pending of this.pendingClaims.values()) {
                     clearTimeout(pending.timeout);
-                    pending.reject(new Error(`WebSocket closed while claim was in flight (code=${event.code})`));
+                    pending.reject(new AbloConnectionError(`WebSocket closed while claim was in flight (code=${event.code})`));
                 }
                 this.pendingClaims.clear();
             }
@@ -762,7 +746,7 @@ export class SyncWebSocket extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingMutations.delete(clientTxId);
-                reject(new Error(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`));
+                reject(new AbloConnectionError(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`, { code: 'commit_no_result' }));
             }, timeoutMs);
             this.pendingMutations.set(clientTxId, { resolve, reject, timeout });
             try {
@@ -778,9 +762,7 @@ export class SyncWebSocket extends EventEmitter {
             catch (error) {
                 clearTimeout(timeout);
                 this.pendingMutations.delete(clientTxId);
-                reject(error instanceof Error
-                    ? error
-                    : new Error(String(error)));
+                reject(toAbloError(error));
             }
         });
     }
@@ -826,7 +808,9 @@ export class SyncWebSocket extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingClaims.delete(claimId);
-                reject(new Error(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`));
+                reject(new AbloConnectionError(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`, {
+                    code: 'wait_for_timeout',
+                }));
             }, timeoutMs);
             this.pendingClaims.set(claimId, { resolve, reject, timeout });
             try {
@@ -843,7 +827,7 @@ export class SyncWebSocket extends EventEmitter {
             catch (error) {
                 clearTimeout(timeout);
                 this.pendingClaims.delete(claimId);
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject(toAbloError(error));
             }
         });
     }
@@ -864,7 +848,10 @@ export class SyncWebSocket extends EventEmitter {
         if (pending) {
             clearTimeout(pending.timeout);
             this.pendingClaims.delete(claimId);
-            pending.reject(new Error(`claim ${claimId} released before ack`));
+            pending.reject(new AbloError(`claim ${claimId} released before ack`, {
+                code: 'intent_wait_aborted',
+                httpStatus: 409,
+            }));
         }
         if (this.ws?.readyState !== WebSocket.OPEN)
             return;
@@ -1172,8 +1159,11 @@ export class SyncWebSocket extends EventEmitter {
         else {
             detail = 'never_connected';
         }
-        const err = new Error(`SyncWebSocket not connected — cannot send ${action} (${detail})`);
-        err.diagnostics = d;
+        // Typed so it lands in the AbloError hierarchy AND `isPermanentError`
+        // sees a transient transport failure (retry on reconnect, don't roll
+        // back). `diagnostics` stays a property — the queue's failure log walks
+        // the cause chain for it.
+        const err = Object.assign(new AbloConnectionError(`SyncWebSocket not connected — cannot send ${action} (${detail})`, { code: 'ws_not_ready' }), { diagnostics: d });
         return err;
     }
     /** Returns the sync groups this connection is subscribed to. */

package/dist/sync/participants.js

@@ -1,4 +1,5 @@
 import { scopeKindOf } from '../schema/model.js';
+import { AbloConnectionError, AbloValidationError } from '../errors.js';
 export function createParticipantManager(config) {
     return {
         async join(input, overrides) {
@@ -10,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) {
@@ -154,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/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('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 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. |
+| `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. |
 
-`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`, `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
 
@@ -80,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. |
@@ -105,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" },
@@ -128,21 +149,24 @@ 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
-const claim = ablo.weatherReports.claimState('report_stockholm');
+const claim = ablo.weatherReports.claim.state('report_stockholm');
 if (claim) {
   claim.heldBy;
   claim.action;
@@ -155,19 +179,52 @@ const updated = await ablo.weatherReports.claim(
 );
 ```
 
-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.