@abloatai/ablo 0.3.1 → 0.5.0

package/dist/schema/index.js

@@ -1,11 +1,11 @@
 /**
- * @ablo/sync-engine/schema — Schema Definition DSL
+ * @abloatai/ablo/schema — Schema Definition DSL
  *
  * Define your data models with Zod. Types are inferred automatically.
  *
  * ```ts
  * import { z } from 'zod';
- * import { defineSchema, model, relation } from '@ablo/sync-engine/schema';
+ * import { defineSchema, model, relation } from '@abloatai/ablo/schema';
  *
  * export const schema = defineSchema({
  *   tasks: model({

package/dist/schema/model.d.ts

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   import { z } from 'zod';
- *   import { model, relation } from '@ablo/sync-engine/schema';
+ *   import { model, relation } from '@abloatai/ablo/schema';
  *
  *   const tasks = model({
  *     title: z.string(),
@@ -293,7 +293,7 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
  *
  * ```ts
  * import { z } from 'zod';
- * import { model, relation } from '@ablo/sync-engine/schema';
+ * import { model, relation } from '@abloatai/ablo/schema';
  *
  * const tasks = model({
  *   title: z.string(),

package/dist/schema/model.js

@@ -6,7 +6,7 @@
  *
  * Usage:
  *   import { z } from 'zod';
- *   import { model, relation } from '@ablo/sync-engine/schema';
+ *   import { model, relation } from '@abloatai/ablo/schema';
  *
  *   const tasks = model({
  *     title: z.string(),
@@ -24,7 +24,7 @@ import { getFieldMeta, inferFieldMetaFromZod } from './field.js';
  *
  * ```ts
  * import { z } from 'zod';
- * import { model, relation } from '@ablo/sync-engine/schema';
+ * import { model, relation } from '@abloatai/ablo/schema';
  *
  * const tasks = model({
  *   title: z.string(),

package/dist/schema/queries.d.ts

@@ -10,7 +10,7 @@
  *   import { z } from 'zod';
  *   import {
  *     defineSchema, defineQueries, model, query, relation,
- *   } from '@ablo/sync-engine/schema';
+ *   } from '@abloatai/ablo/schema';
  *
  *   const schema = defineSchema({
  *     slideLayer: model(

package/dist/schema/queries.js

@@ -10,7 +10,7 @@
  *   import { z } from 'zod';
  *   import {
  *     defineSchema, defineQueries, model, query, relation,
- *   } from '@ablo/sync-engine/schema';
+ *   } from '@abloatai/ablo/schema';
  *
  *   const schema = defineSchema({
  *     slideLayer: model(

package/dist/schema/relation.d.ts

@@ -7,7 +7,7 @@
  * - Query include/join support
  *
  * Usage:
- *   import { relation } from '@ablo/sync-engine/schema';
+ *   import { relation } from '@abloatai/ablo/schema';
  *
  *   const taskRelations = {
  *     project: relation.belongsTo('projects', 'projectId'),

package/dist/schema/relation.js

@@ -7,7 +7,7 @@
  * - Query include/join support
  *
  * Usage:
- *   import { relation } from '@ablo/sync-engine/schema';
+ *   import { relation } from '@abloatai/ablo/schema';
  *
  *   const taskRelations = {
  *     project: relation.belongsTo('projects', 'projectId'),

package/dist/schema/schema.d.ts

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   import { z } from 'zod';
- *   import { defineSchema, model, relation } from '@ablo/sync-engine/schema';
+ *   import { defineSchema, model, relation } from '@abloatai/ablo/schema';
  *
  *   const schema = defineSchema({
  *     tasks: model({

package/dist/schema/schema.js

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   import { z } from 'zod';
- *   import { defineSchema, model, relation } from '@ablo/sync-engine/schema';
+ *   import { defineSchema, model, relation } from '@abloatai/ablo/schema';
  *
  *   const schema = defineSchema({
  *     tasks: model({

package/dist/source/index.d.ts

@@ -141,7 +141,7 @@ export interface SourceCommitParams<TAuth = unknown> {
 }
 /**
  * Operation-level permission tag used by `resolveScopes`. Mirrors the
- * four wire request types: a secret/key carries the set of operations
+ * four wire request types: an API key carries the set of operations
  * it's allowed to invoke. Stripe's restricted-key model at the
  * operation granularity — model-level scoping is a future addition.
  */
@@ -191,8 +191,8 @@ export interface SourceHandlerContext<TAuth = unknown> {
      * can use it in `authorize` (to reject out-of-scope calls) and in
      * `list` / `load` (to filter rows the participant is allowed to see).
      *
-     * Absent for calls made without scope context (legacy callers,
-     * tests, or single-tenant deployments that haven't enabled it).
+     * Absent for calls made without scope context, such as tests or
+     * single-tenant deployments that do not need scoped fan-out yet.
      */
     readonly scope?: SourceRequestContext;
 }
@@ -221,9 +221,9 @@ type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
         readonly id: string;
     } & Record<string, unknown>, InferCreate<Schema<S>, K>, TAuth>;
 }>;
-export type SourceSecret = string | ((context: SourceAuthorizeContext) => Promise<string> | string);
+export type SourceApiKey = string | ((context: SourceAuthorizeContext) => Promise<string> | string);
 export interface SourceSignatureOptions {
-    readonly secret: string;
+    readonly apiKey: string;
     readonly body: string;
     /**
      * Unique message id (`webhook-id` per the Standard Webhooks spec).
@@ -231,12 +231,15 @@ export interface SourceSignatureOptions {
      * receivers may dedupe by it.
      */
     readonly messageId: string;
+    /**
+     * Unix timestamp in seconds. Defaults to the current time.
+     */
     readonly timestamp?: number;
 }
 export interface SourceSignatureVerificationOptions {
     readonly request: Request;
     readonly body: string;
-    readonly secret: string;
+    readonly apiKey: string;
     readonly toleranceMs?: number;
 }
 export interface SourceSignatureVerificationResult {
@@ -263,21 +266,13 @@ export declare class SourceSignatureError extends Error {
 export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
     readonly schema: Schema<S>;
     /**
-     * Shared secret for Ablo Cloud -> customer source calls. When set,
-     * abloSource verifies HMAC_SHA256(secret, `${timestamp}.${body}`)
-     * before `authorize` or any model handler runs.
-     *
-     * @deprecated Use `signingSecret`. Kept so existing source routes
-     * do not break during the Data Source naming cleanup.
-     */
-    readonly secret?: SourceSecret;
-    /**
-     * Signing secret for Ablo -> customer Data Source calls. The value is
-     * created for the Data Source endpoint in Ablo and stored in the
-     * customer's app environment. Used to verify Standard Webhooks
-     * headers before any handler runs.
+     * Customer-visible Ablo credential. In the API-key-only onboarding
+     * path, Ablo signs Data Source calls with the same project API key
+     * that the customer's server-side SDK uses. This keeps the customer
+     * env surface to one Ablo credential while preserving signed request
+     * verification before any handler runs.
      */
-    readonly signingSecret?: SourceSecret;
+    readonly apiKey: SourceApiKey;
     /**
      * Clock-skew window for signed source requests. Default: 5 minutes.
      */
@@ -287,7 +282,7 @@ export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
      * a database handle, account scope, or current actor. Keep database
      * credentials in this function's environment; never send them to Ablo.
      *
-     * Signature verification is handled by `secret` before this function
+     * Signature verification is handled by `apiKey` before this function
      * runs. `authorize` should only attach business context.
      */
     readonly authorize?: (context: SourceAuthorizeContext) => Promise<TAuth> | TAuth;
@@ -299,12 +294,11 @@ export type AbloSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
      * runs.
      *
      * Customers typically extract a key id from the request (e.g.
-     * `webhook-id` prefix, a custom header, or the secret itself) and
-     * look up the scopes for that key in their store. Mirrors Stripe
-     * restricted keys: one secret can read, another can read + write.
+     * `webhook-id` prefix, a custom header, or the API key itself) and
+     * look up the scopes for that key in their store.
      *
-     * When omitted, all operations are allowed (back-compat). Returning
-     * an empty set denies all operations.
+     * When omitted, all operations are allowed. Returning an empty set
+     * denies all operations.
      */
     readonly resolveScopes?: (params: {
         readonly auth: TAuth;
@@ -351,7 +345,7 @@ export type SourceListRequest = {
 export type SourceCommitRequest = {
     readonly type: 'commit';
     /**
-     * Legacy single-model hint. Omit for cross-model commits; top-level
+     * Optional single-model hint. Omit for cross-model commits; top-level
      * `commit` receives the whole operation array unchanged.
      */
     readonly model?: string;
@@ -407,7 +401,7 @@ export type DataSourceAuthorizeContext = SourceAuthorizeContext;
 export type DataSourceHandlerContext<TAuth = unknown> = SourceHandlerContext<TAuth>;
 export type DataSourceModelHandlers<Row, CreateInput, TAuth = unknown> = SourceModelHandlers<Row, CreateInput, TAuth>;
 export type DataSourceCommitHandler<TAuth = unknown> = SourceCommitHandler<TAuth>;
-export type DataSourceSecret = SourceSecret;
+export type DataSourceApiKey = SourceApiKey;
 export type DataSourceSignatureOptions = SourceSignatureOptions;
 export type DataSourceSignatureVerificationOptions = SourceSignatureVerificationOptions;
 export type DataSourceSignatureVerificationResult = SourceSignatureVerificationResult;

package/dist/source/index.js

@@ -79,13 +79,13 @@ function bufferToBase64(buffer) {
     }
     return btoa(binary);
 }
-async function hmacSha256Base64(secret, payload) {
+async function hmacSha256Base64(apiKey, payload) {
     const crypto = globalThis.crypto?.subtle;
     if (!crypto) {
         throw new SourceSignatureError('source_signature_invalid', 'WebCrypto HMAC support is unavailable in this runtime');
     }
     const encoder = new TextEncoder();
-    const key = await crypto.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const key = await crypto.importKey('raw', encoder.encode(apiKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
     return bufferToBase64(await crypto.sign('HMAC', key, encoder.encode(payload)));
 }
 /**
@@ -101,12 +101,9 @@ function timingSafeEqual(expected, actual) {
     return diff === 0;
 }
 export async function signAbloSourceRequest(options) {
-    const signedAt = options.timestamp ?? Date.now();
+    const signedAt = options.timestamp ?? Math.floor(Date.now() / 1000);
     // Standard Webhooks signing input: `${msg_id}.${timestamp}.${payload}`
-    // Timestamps are seconds-since-epoch in the spec; we keep millis on
-    // the wire for backwards compatibility with our existing tolerance
-    // window — the receiver compares them millis-to-millis.
-    const signature = await hmacSha256Base64(options.secret, `${options.messageId}.${signedAt}.${options.body}`);
+    const signature = await hmacSha256Base64(options.apiKey, `${options.messageId}.${signedAt}.${options.body}`);
     return {
         signedAt,
         signature,
@@ -131,14 +128,16 @@ export async function verifyAbloSourceRequest(options) {
         throw new SourceSignatureError('source_timestamp_invalid', 'Invalid webhook-timestamp header');
     }
     const toleranceMs = options.toleranceMs ?? DEFAULT_SIGNATURE_TOLERANCE_MS;
-    if (Math.abs(Date.now() - signedAt) > toleranceMs) {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const toleranceSeconds = Math.ceil(toleranceMs / 1000);
+    if (Math.abs(nowSeconds - signedAt) > toleranceSeconds) {
         throw new SourceSignatureError('source_timestamp_expired', 'webhook-timestamp is outside the allowed clock-skew window');
     }
     const presented = parseSignatureHeader(getHeader(options.request, ABLO_SOURCE_HEADERS.signature));
     if (presented.length === 0) {
         throw new SourceSignatureError('source_signature_missing', 'Missing webhook-signature header');
     }
-    const expected = await hmacSha256Base64(options.secret, `${messageId}.${signedAt}.${options.body}`);
+    const expected = await hmacSha256Base64(options.apiKey, `${messageId}.${signedAt}.${options.body}`);
     // Accept any presented signature that matches — supports key
     // rotation per the Standard Webhooks spec.
     const ok = presented.some((sig) => timingSafeEqual(expected, sig));
@@ -147,10 +146,10 @@ export async function verifyAbloSourceRequest(options) {
     }
     return { messageId, signedAt };
 }
-async function resolveSecret(secret, context) {
-    if (!secret)
+async function resolveApiKey(apiKey, context) {
+    if (!apiKey)
         return null;
-    return typeof secret === 'function' ? secret(context) : secret;
+    return typeof apiKey === 'function' ? apiKey(context) : apiKey;
 }
 /**
  * Map a wire request to its scope tag. Each request type corresponds
@@ -209,19 +208,23 @@ export function abloSource(options) {
         }
         let signature = null;
         try {
-            const secret = await resolveSecret(options.signingSecret ?? options.secret, {
+            const apiKey = await resolveApiKey(options.apiKey, {
                 request,
                 body,
                 rawBody,
             });
-            if (secret) {
-                signature = await verifyAbloSourceRequest({
-                    request,
-                    body: rawBody,
-                    secret,
-                    toleranceMs: options.signatureToleranceMs,
-                });
+            if (!apiKey) {
+                return json({
+                    error: 'source_api_key_missing',
+                    message: 'Data Source apiKey is required',
+                }, 401);
             }
+            signature = await verifyAbloSourceRequest({
+                request,
+                body: rawBody,
+                apiKey,
+                toleranceMs: options.signatureToleranceMs,
+            });
         }
         catch (err) {
             if (err instanceof SourceSignatureError) {

package/dist/source/pushQueue.d.ts

@@ -60,7 +60,7 @@ export interface PushQueueStorage {
 export declare const STANDARD_WEBHOOKS_RETRY_SCHEDULE: readonly number[];
 export interface PushQueueOptions {
     readonly endpoint: string;
-    readonly secret: string;
+    readonly apiKey: string;
     readonly storage: PushQueueStorage;
     /**
      * Override the retry delays. Default: Standard Webhooks schedule.

package/dist/source/pushQueue.js

@@ -84,9 +84,9 @@ export function createPushQueue(options) {
         let signed;
         try {
             signed = await signAbloSourceRequest({
-                secret: options.secret,
+                apiKey: options.apiKey,
                 body: rawBody,
-                timestamp: now(),
+                timestamp: Math.floor(now() / 1000),
                 // Reuse the queue id as the webhook-id across all retry
                 // attempts so the receiver can dedupe replays per spec.
                 messageId: item.id,

package/dist/sync/SyncWebSocket.d.ts

@@ -113,11 +113,12 @@ export interface SyncWebSocketOptions {
      */
     kind?: 'user' | 'agent' | 'system';
     /**
-     * Biscuit capability bearer token. When set, sent as
-     * `?authorization=Bearer+<token>` on the WS upgrade — query-param
-     * form so it works in both Node (no header support) and browsers.
-     * The server's auth path accepts either form. Required for
-     * `kind: 'agent'`; ignored for `kind: 'user'`.
+     * The agent's bearer credential — a restricted (`rk_`) API key. When
+     * set, sent as `?authorization=Bearer+<token>` on the WS upgrade —
+     * query-param form so it works in both Node (no header support) and
+     * browsers. The server's auth path accepts either form. Required for
+     * `kind: 'agent'`; ignored for `kind: 'user'`. (Field name predates
+     * the Biscuit→opaque-key migration.)
      */
     capabilityToken?: string;
 }
@@ -193,6 +194,20 @@ export interface PresenceUpdateEvent {
         meta?: Record<string, unknown>;
         declaredAt: number;
         expiresAt: number;
+        /**
+         * Lifecycle state. Additive — older servers omit it and the reader
+         * treats absence as `'active'`. Terminal states (`committed` /
+         * `expired` / `canceled`) ride one frame as the claim ends so peers
+         * learn *how* it resolved before it drops from the active set.
+         */
+        status?: 'active' | 'committed' | 'expired' | 'canceled';
+        error?: {
+            code: string;
+            message?: string;
+            heldBy?: string;
+            heldByIntentId?: string;
+            heldByExpiresAt?: number;
+        };
     }>;
     localTime?: string;
     type?: string;

package/dist/sync/createIntentStream.js

@@ -78,6 +78,13 @@ export function createIntentStream(config, transport = null) {
                 }
             }
             for (const claim of event.activeIntents ?? []) {
+                // Terminal-status entries (committed / expired / canceled) are
+                // one-shot "this claim ended" signals. The holder sweep above
+                // already removed the prior active entry; skipping the re-add
+                // drops it from `others`, which is what resolves a contender's
+                // `settled()`. Absent status means active (wire back-compat).
+                if (claim.status && claim.status !== 'active')
+                    continue;
                 activeByIntentId.set(claim.intentId, {
                     id: claim.intentId,
                     heldBy: event.userId,

package/dist/testing/fixtures/models.d.ts

@@ -1,5 +1,5 @@
 /**
- * Test Model subclasses for @ablo/sync-engine tests.
+ * Test Model subclasses for @abloatai/ablo tests.
  *
  * Lightweight Model implementations with FK relationships matching
  * the MODEL_CREATE_PRIORITY map in TransactionQueue:

package/dist/testing/fixtures/models.js

@@ -1,5 +1,5 @@
 /**
- * Test Model subclasses for @ablo/sync-engine tests.
+ * Test Model subclasses for @abloatai/ablo tests.
  *
  * Lightweight Model implementations with FK relationships matching
  * the MODEL_CREATE_PRIORITY map in TransactionQueue:

package/dist/testing/helpers/react-wrapper.d.ts

@@ -19,7 +19,7 @@ export interface TestWrapperOptions {
  *
  * @example
  * import { renderHook } from '@testing-library/react';
- * import { createReactTestWrapper, createMockSyncStore } from '@ablo/sync-engine/testing';
+ * import { createReactTestWrapper, createMockSyncStore } from '@abloatai/ablo/testing';
  *
  * const mockStore = createMockSyncStore();
  * mockStore.setModels(Task, [task1, task2]);
@@ -40,7 +40,7 @@ export declare function createReactTestWrapper(options?: TestWrapperOptions): Re
  * consumers without React tests to install it.
  *
  * @example
- * import { renderSyncHook, createMockSyncStore } from '@ablo/sync-engine/testing';
+ * import { renderSyncHook, createMockSyncStore } from '@abloatai/ablo/testing';
  *
  * const mockStore = createMockSyncStore();
  * mockStore.addModel(Task, myTask);

package/dist/testing/helpers/react-wrapper.js

@@ -13,7 +13,7 @@ import { MockSyncStore, createMockSyncStore } from '../mocks/MockSyncStore.js';
  *
  * @example
  * import { renderHook } from '@testing-library/react';
- * import { createReactTestWrapper, createMockSyncStore } from '@ablo/sync-engine/testing';
+ * import { createReactTestWrapper, createMockSyncStore } from '@abloatai/ablo/testing';
  *
  * const mockStore = createMockSyncStore();
  * mockStore.setModels(Task, [task1, task2]);
@@ -37,7 +37,7 @@ export function createReactTestWrapper(options = {}) {
  * consumers without React tests to install it.
  *
  * @example
- * import { renderSyncHook, createMockSyncStore } from '@ablo/sync-engine/testing';
+ * import { renderSyncHook, createMockSyncStore } from '@abloatai/ablo/testing';
  *
  * const mockStore = createMockSyncStore();
  * mockStore.addModel(Task, myTask);

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine/testing — Public test utilities for SDK consumers.
+ * @abloatai/ablo/testing — Public test utilities for SDK consumers.
  *
  * Provides mock implementations, fixture factories, and test harnesses
  * for writing integration tests against the sync engine.

package/dist/testing/index.js

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine/testing — Public test utilities for SDK consumers.
+ * @abloatai/ablo/testing — Public test utilities for SDK consumers.
  *
  * Provides mock implementations, fixture factories, and test harnesses
  * for writing integration tests against the sync engine.

package/dist/types/streams.d.ts

@@ -57,7 +57,8 @@ export interface AgentDelta {
 /**
  * A reference to whoever's authority bounds a joined participant.
  * The spawned participant can never see or do more than this principal.
- * Enforced cryptographically via Biscuit attenuation.
+ * Enforced server-side: the spawned agent gets its own restricted
+ * (`rk_`) key whose scope is a subset of the parent's.
  *
  *   • `SessionRef`     — human is joining an agent (chat assistant flow)
  *   • `AgentRef`       — agent spawning a sub-agent (attenuation chain)
@@ -493,3 +494,42 @@ export interface ActiveIntent extends IntentDeclaration {
     readonly announcedAt: string;
     readonly expiresAt: string;
 }
+/** Every lifecycle state of a coordination intent, in one enum. */
+export type IntentStatus = 'active' | 'committed' | 'expired' | 'canceled';
+/** Options for waiting on a target to become free. */
+export interface IntentWaitOptions {
+    readonly timeout?: number;
+    readonly pollInterval?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * The coordination state of one entity. Self-describing on the wire via
+ * `object: 'intent'`. Existence with `status: 'active'` *is* the lock;
+ * the fields *are* the awareness ("agent X is editing this until Y").
+ *
+ * Deliberately omits a Stripe-style `next_action`: a contender's only
+ * response is "wait until free, then re-read", and the runtime performs
+ * that uniformly at the tool boundary (`IntentHandle.whenFree()` + the
+ * stale-context guard that forces a re-read). Encoding a constant
+ * instruction the engine always takes would be the kind of ceremony this
+ * object exists to remove.
+ */
+export interface Intent {
+    readonly object: 'intent';
+    readonly id: string;
+    readonly status: IntentStatus;
+    /** What is being coordinated. */
+    readonly target: EntityRef;
+    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
+    readonly action: string;
+    /** Participant holding it. */
+    readonly heldBy: string;
+    readonly participantKind: 'human' | 'agent';
+    /**
+     * Ms-epoch the holder opened it. Optional until the lease wire carries
+     * it — derived shapes (e.g. mapped from a presence frame) may omit it.
+     */
+    readonly createdAt?: string;
+    /** Ms-epoch the server auto-expires it if the holder doesn't finish. */
+    readonly expiresAt: string;
+}

package/docs/api.md

@@ -107,31 +107,89 @@ that work to clear, or `ifBusy: 'fail'` to throw `AbloBusyError`.
 
 ## Intent
 
-Intent is the coordination signal. It tells humans and agents who is working on
-a target before the write lands.
+Intent is the coordination object — it tells humans and agents who is working on
+a target before the write lands. Like Stripe's `PaymentIntent`, one
+self-describing object carries the whole 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.
+
+Read or open one through the model accessor — `ablo.<model>.intent(id)` — which
+sits beside `create`/`update`/`retrieve` and returns a handle **synchronously**,
+so you can inspect who holds a target without awaiting.
+
+### The Intent object
+
+| Field | Type | Description |
+|---|---|---|
+| `object` | `'intent'` | String representing the object's type. Always `'intent'`. |
+| `id` | string | Unique identifier for the intent. |
+| `status` | `'active' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. |
+| `target` | `{ type, id, field? }` | What is being coordinated. |
+| `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `heldBy` | string | Participant id holding the intent. |
+| `participantKind` | `'human' \| 'agent'` | Whether a human session or an agent holds it. |
+| `expiresAt` | string | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
+
+```json
+{
+  "object": "intent",
+  "id": "int_3MtwBwLkdIwHu7ix",
+  "status": "active",
+  "target": { "type": "tasks", "id": "task_123", "field": "status" },
+  "action": "editing",
+  "heldBy": "agent:task-writer",
+  "participantKind": "agent",
+  "expiresAt": "1716580000000"
+}
+```
+
+### Lifecycle
+
+```
+            claim()                    update() lands
+  (free) ───────────▶ active ───────────────────────▶ committed
+                        │
+            ┌───────────┴───────────┐
+            ▼                       ▼
+        canceled                 expired
+     (finish w/o write)       (TTL; holder died)
+```
+
+A target is free when `ablo.<model>.intent(id).current` is `null`. Terminal
+states drop out of the live stream — a present intent is, by definition,
+`active`.
+
+### Reading and claiming
 
 ```ts
-const intent = await ablo.intents.create({
-  target: { resource: 'tasks', id: 'task_123', field: 'status' },
-  action: 'update',
-});
+const task = ablo.tasks.intent('task_123');
 
-try {
-  const snap = ablo.snapshot({ tasks: 'task_123' });
-  const task = await ablo.tasks.update(
-    'task_123',
-    { status: 'done' },
-    { intent, readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
-  );
-
-  task.status; // done
-} finally {
-  await intent.release();
+// Read side — who is working on this target right now?
+if (task.current) {
+  task.current.heldBy; // 'agent:task-writer'
+  task.current.action; // 'editing'
+  await task.whenFree(); // wait until they finish, then continue
 }
+
+// Write side — claim, write, auto-release in one flow.
+await task.claim({ action: 'editing', field: 'status', ttl: '2m' });
+const updated = await task.update({ status: 'done' });
+updated.status; // 'done'
 ```
 
-`intents.waitFor(target)` waits until the live intent stream clears. Pass
-`timeout` only when your product needs an upper bound.
+`task.update(...)` carries the same stale-check as a plain update: it rejects
+with `AbloStaleContextError` if the row advanced past your claim point, so you
+re-read before retrying. The intent releases automatically when `update`
+resolves; call `task.finish()` if the work ends without a write.
+
+`task.whenFree({ timeout })` waits until the target is free. Pass `timeout` only
+when your product needs an upper bound.
+
+### Cross-resource coordination
+
+For lower-level coordination that isn't scoped to a single model row, the
+top-level `ablo.intents` resource (`create`, `list`, `waitFor`) remains
+available. Most callers should prefer `ablo.<model>.intent(id)`.
 
 ## Advanced Commit API
 
@@ -176,7 +234,7 @@ import { schema } from './ablo.schema';
 
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
   async commit({ operations, clientTxId, context }) {
     // Write operations to the customer's database transaction.
     return { rows: [] };