@abloatai/ablo 0.8.0 → 0.9.1

package/dist/webhooks/events.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A Stripe-style webhook event delivered to the customer's endpoint. Verified
+ * (via the Standard Webhooks library) before the customer reads it.
+ */
+export interface AbloWebhookEvent {
+    /** Stable event id = `String(syncId)`. Dedupe by this (idempotency). */
+    readonly id: string;
+    /** `<model>.<verb>`, e.g. `"slide.updated"` — switch on this. */
+    readonly type: string;
+    /** Wire model name, e.g. `"Slide"`. */
+    readonly model: string;
+    /** The changed row's id. */
+    readonly objectId: string;
+    /** Monotonic transaction-log position. ORDER by this (and dedupe). */
+    readonly syncId: number;
+    /** The post-change row (the object), or `null` on a delete. Like Stripe's
+     *  `event.data.object`. */
+    readonly data: Record<string, unknown> | null;
+    /** ISO timestamp the change was committed. */
+    readonly createdAt: string;
+}
+/** The minimal delta shape the mapping reads (a `ServerSyncDelta` satisfies it). */
+export interface WebhookSourceDelta {
+    readonly id: number;
+    readonly actionType: string;
+    readonly modelName: string;
+    readonly modelId: string;
+    /** `jsonb` — parsed object, raw JSON string, or null. */
+    readonly data: Record<string, unknown> | string | null;
+    readonly createdAt: string;
+}
+/**
+ * Map a committed delta to a customer-facing webhook event. Returns `null` for
+ * internal sync deltas (permission/group changes) that aren't customer events —
+ * the caller skips those (no webhook emitted). Pure: the `syncId` and timestamp
+ * come from the delta, so the mapping is deterministic.
+ */
+export declare function deltaToWebhookEvent(delta: WebhookSourceDelta): AbloWebhookEvent | null;

package/dist/webhooks/events.js

@@ -0,0 +1,40 @@
+/**
+ * The customer-facing verb per delta action. Only the CRUD-ish actions become
+ * webhook events; `C`overing / `G`roupAdded / `S`groupRemoved are internal sync
+ * mechanics (permission/visibility), NOT customer events → no webhook.
+ */
+const ACTION_VERB = {
+    I: 'created',
+    U: 'updated',
+    D: 'deleted',
+    A: 'archived',
+    V: 'unarchived',
+};
+function parseRow(data) {
+    if (data == null)
+        return null;
+    if (typeof data === 'string') {
+        return data === '' ? null : JSON.parse(data);
+    }
+    return data;
+}
+/**
+ * Map a committed delta to a customer-facing webhook event. Returns `null` for
+ * internal sync deltas (permission/group changes) that aren't customer events —
+ * the caller skips those (no webhook emitted). Pure: the `syncId` and timestamp
+ * come from the delta, so the mapping is deterministic.
+ */
+export function deltaToWebhookEvent(delta) {
+    const verb = ACTION_VERB[delta.actionType];
+    if (!verb)
+        return null; // C / G / S — internal sync mechanics, not a customer event
+    return {
+        id: String(delta.id),
+        type: `${delta.modelName.toLowerCase()}.${verb}`,
+        model: delta.modelName,
+        objectId: delta.modelId,
+        syncId: delta.id,
+        data: parseRow(delta.data),
+        createdAt: delta.createdAt,
+    };
+}

package/dist/webhooks/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@abloatai/ablo/webhooks` — the webhook event catalog + delta mapping.
+ *
+ * Customers import {@link AbloWebhookEvent} to type their handler; the server
+ * uses {@link deltaToWebhookEvent} to turn transaction-log deltas into events
+ * for Svix to deliver. Signature verification is NOT here — the customer uses
+ * the open Standard Webhooks library (`svix` / `standardwebhooks`), so Ablo
+ * ships no crypto.
+ */
+export { deltaToWebhookEvent, type AbloWebhookEvent, type WebhookSourceDelta, } from './events.js';

package/dist/webhooks/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@abloatai/ablo/webhooks` — the webhook event catalog + delta mapping.
+ *
+ * Customers import {@link AbloWebhookEvent} to type their handler; the server
+ * uses {@link deltaToWebhookEvent} to turn transaction-log deltas into events
+ * for Svix to deliver. Signature verification is NOT here — the customer uses
+ * the open Standard Webhooks library (`svix` / `standardwebhooks`), so Ablo
+ * ships no crypto.
+ */
+export { deltaToWebhookEvent, } from './events.js';

package/dist/wire/errorEnvelope.d.ts

@@ -0,0 +1,34 @@
+/** The canonical wire envelope — Stripe's error-object shape. Every HTTP error
+ *  response and every structured frame error carries this exact set of keys,
+ *  regardless of which route or transport produced it. */
+export interface ErrorEnvelope {
+    readonly type: string;
+    readonly code?: string;
+    readonly param?: string;
+    readonly message: string;
+    readonly doc_url?: string;
+    readonly request_id?: string;
+}
+/** {@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 declare function statusForType(type: string): number;
+/**
+ * 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 declare function errorEnvelope(err: unknown, requestId?: string): {
+    body: ErrorEnvelope;
+    status: number;
+};

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.md

@@ -31,10 +31,10 @@ const schema = defineSchema({
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 await ablo.ready();
-const report = await ablo.weatherReports.retrieve('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
@@ -44,29 +44,29 @@ agents, read the [Integration Guide](./integration-guide.md).
 
 Each schema model becomes a typed model on the client:
 
-- `ablo.weatherReports.retrieve(id)` reads one row asynchronously (server read).
+- `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.
+- `ablo.weatherReports.create({ data })` creates a row.
+- `ablo.weatherReports.update({ id, data, ...options })` updates a row.
+- `ablo.weatherReports.delete({ id, ...options })` deletes a row.
 
 `retrieve`/`list` and `get`/`getAll`/`getCount` are not aliases. Use
-`retrieve(id)` or `list({ where })` when the row may not be local yet — they
+`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 |
 |---|---|---|
-| `retrieve(id)` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
+| `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. |
+| `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**
@@ -79,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:
@@ -105,11 +107,11 @@ 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.
 
 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`.
+`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
 
@@ -140,7 +142,7 @@ coordination surface is `claim.state(id)` / `claim.queue(id)` /
 ### Lifecycle
 
 ```
-            claim(id)                  update(id) lands
+            claim({ id })              update({ id }) lands
   (free) ───────────▶ active ───────────────────────▶ committed
                         │
             ┌───────────┴───────────┐
@@ -149,16 +151,16 @@ coordination surface is `claim.state(id)` / `claim.queue(id)` /
    (release w/o write)        (TTL; holder died)
 ```
 
-A target is free when `ablo.<model>.claim.state(id)` is `null`. Terminal
+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)`).
+`claim.queue({ id })`).
 
 ### Reading and claiming
 
-`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
+`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
@@ -166,31 +168,32 @@ 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.claim.state('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 `ablo.<model>.update(id, data)`. While you hold
+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.
+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>.list(...)`, `ablo.<model>.claim(...)`, and
-`ablo.<model>.update(...)`.
+`ablo.<model>.list(...)`, `ablo.<model>.claim({ id })`, and
+`ablo.<model>.update({ id, data })`.
 
 ## HTTP API
 
@@ -203,12 +206,12 @@ 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>.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` |
+| `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