@abloatai/ablo 0.5.1 → 0.6.0

package/docs/api.md

@@ -11,30 +11,30 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
   }),
 });
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 await ablo.ready();
-const [task] = await ablo.tasks.load({ where: { id: 'task_123' } });
-if (!task) throw new Error('Task not found');
+const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+if (!report) throw new Error('Row not found');
 
-await ablo.tasks.update('task_123', { status: 'done' }, { wait: 'confirmed' });
+await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
 ```
 
 ## Model Methods
 
-Each schema model becomes a typed resource on the client:
+Each schema model becomes a typed model on the client:
 
-- `ablo.tasks.load({ where })` hydrates rows asynchronously.
-- `ablo.tasks.retrieve(id)` reads one already-loaded row synchronously.
-- `ablo.tasks.create(data)` creates a row.
-- `ablo.tasks.update(id, data, options?)` updates a row.
-- `ablo.tasks.delete(id, options?)` deletes a row.
+- `ablo.weatherReports.load({ where })` hydrates rows asynchronously.
+- `ablo.weatherReports.retrieve(id)` reads one already-loaded row synchronously.
+- `ablo.weatherReports.create(data)` creates a row.
+- `ablo.weatherReports.update(id, data, options?)` updates a row.
+- `ablo.weatherReports.delete(id, options?)` deletes a row.
 
 `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
@@ -53,9 +53,9 @@ local read.
 `list` and `count` read the local pool. They default to live rows and accept:
 
 ```ts
-const activeDoneTasks = ablo.tasks.list({
-  where: { status: 'done' },
-  filter: (task) => !task.title.startsWith('[archived]'),
+const readyReports = ablo.weatherReports.list({
+  where: { status: 'ready' },
+  filter: (report) => !report.location.startsWith('[archived]'),
   orderBy: { updatedAt: 'desc' },
   limit: 20,
   scope: 'live', // 'live' | 'archived' | 'all'
@@ -67,11 +67,11 @@ const activeDoneTasks = ablo.tasks.list({
 Use `snapshot` when a write should reject if the row changed mid-flight:
 
 ```ts
-const snap = ablo.snapshot({ tasks: 'task_123' });
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```
@@ -82,62 +82,43 @@ Protected write options:
 |---|---|
 | `readAt` | The state cursor the write was based on. |
 | `onStale` | Stale-state policy. Prefer `reject` for agent writes. |
-| `intent` | Active work claim associated with the write. |
 | `wait` | `queued` resolves after local queueing; `confirmed` waits for server acceptance. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 | `timeout` | Maximum time to wait for the write call. |
 
-## Advanced Resource API
+## Claims
 
-Use `resource(name)` only when you intentionally need the raw protocol shape:
-generic server runtimes, MCP routes, batch tools, or code that has no schema.
+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.
 
-```ts
-const tasks = ablo.resource<{ status: string }>('tasks');
-
-const { data, stamp, intents } = await tasks.retrieve('task_123', {
-  ifBusy: 'return',
-});
-```
-
-`stamp` is the state watermark. Pass it as `readAt` to reject stale writes.
+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.
 
-`intents` lists active work on the target. Set `ifBusy: 'wait'` to wait for
-that work to clear, or `ifBusy: 'fail'` to throw `AbloBusyError`.
-
-## Intent
-
-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
+### The Claim State Object
 
 | Field | Type | Description |
 |---|---|---|
-| `object` | `'intent'` | String representing the object's type. Always `'intent'`. |
-| `id` | string | Unique identifier for the intent. |
+| `object` | `'claim'` | String representing the object's type. |
+| `id` | string | Unique identifier for the claim. |
 | `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. |
+| `heldBy` | string | Participant id holding the claim. |
 | `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",
+  "object": "claim",
+  "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
-  "target": { "type": "tasks", "id": "task_123", "field": "status" },
+  "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
   "action": "editing",
-  "heldBy": "agent:task-writer",
+  "heldBy": "agent:report-writer",
   "participantKind": "agent",
   "expiresAt": "1716580000000"
 }
@@ -146,128 +127,57 @@ so you can inspect who holds a target without awaiting.
 ### Lifecycle
 
 ```
-            claim()                    update() lands
+            claim(id)                  update(id) lands
   (free) ───────────▶ active ───────────────────────▶ committed
                         │
             ┌───────────┴───────────┐
             ▼                       ▼
         canceled                 expired
-     (finish w/o write)       (TTL; holder died)
+   (release 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`.
+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.
 
 ### Reading and claiming
 
-```ts
-const task = ablo.tasks.intent('task_123');
+`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.
 
+```ts
 // 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
+const claim = ablo.weatherReports.claimState('report_stockholm');
+if (claim) {
+  claim.heldBy; // 'agent:report-writer'
+  claim.action; // 'editing'
 }
 
-// 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'
-```
-
-`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
-
-Most callers use `ablo.<model>.update(...)` or `resource.update(...)`. For atomic
-batches or custom runtimes, use `commits.create`.
-
-```ts
-await ablo.commits.create({
-  wait: 'confirmed',
-  operations: [
-    {
-      action: 'update',
-      resource: 'tasks',
-      id: 'task_123',
-      data: { status: 'done' },
-      readAt: stamp,
-      onStale: 'reject',
-    },
-  ],
-});
+// 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'
 ```
 
-Every state change becomes a commit. Commits check authorization, stale state,
-intent conflicts, and idempotency.
+Writes go through the normal flat `ablo.<model>.update(id, data)`. While you hold
+a claim on `id`, that `update` is automatically stale-guarded: it rejects with
+`AbloStaleContextError` if the row advanced past your claim point, so you re-read
+before retrying. The callback form releases automatically when the callback
+returns or throws, or call `ablo.weatherReports.release(id)` if you claimed manually and
+need to release early.
 
 ## Agent
 
 Most agents should import the same schema as the app and call
-`ablo.<model>.load(...)` plus `ablo.<model>.update(...)`. The schema-less
-`agent.run(...)` wrapper exists for advanced server workers that cannot import
-the app schema; it creates the capability and task internally and returns
-`done`, `failed`, or `cancelled`.
-
-## Data Source
-
-Use `dataSource(...)` only when the customer's app database remains canonical
-and Ablo should call a signed endpoint instead of storing customer rows itself.
-
-```ts
-import { dataSource } from '@abloatai/ablo';
-import { schema } from './ablo.schema';
-
-export const POST = dataSource({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
-  async commit({ operations, clientTxId, context }) {
-    // Write operations to the customer's database transaction.
-    return { rows: [] };
-  },
-});
-```
-
-The SDK still uses `ablo.<model>.update(...)`. The Data Source endpoint is a
-server-to-server storage adapter. See [Connect Your Database](./data-sources.md).
-
-## Capability
-
-Capabilities are the lower-level permission boundary. Most apps should let
-`agent.run(...)` create and revoke them.
-
-```ts
-const capability = await api.capabilities.create({
-  participantKind: 'agent',
-  participantId: 'agent:task-writer',
-  // Strings derive from the schema's `identityRoles` templates
-  // (see integration-guide.md §1) or a model's `syncGroupFormat`.
-  syncGroups: ['org:acme', 'user:agent:task-writer'],
-  operations: ['tasks.retrieve', 'tasks.update'],
-  lease: '10m',
-});
-```
-
-Use `lease` as a crash cleanup window. Normal agent runs still close when the
-handler returns, fails, or is cancelled.
-
-For the design rationale — why capabilities instead of static API keys,
-why the lease + signature + revocation triple, and how this maps to AWS
-STS / Vault / Auth0 Token Vault — see [Capabilities](./capabilities.md#why-capabilities-not-api-keys).
+`ablo.<model>.load(...)`, `ablo.<model>.claim(...)`, and
+`ablo.<model>.update(...)`.
 
 ## Errors
 
@@ -283,6 +193,6 @@ All SDK errors extend `AbloError` and expose a stable `type` string.
 | `AbloValidationError` | Invalid input. |
 | `AbloServerError` | Server-side 5xx. |
 | `AbloStaleContextError` | `readAt` no longer matches current state. |
-| `AbloBusyError` | Active intent conflict or busy wait timeout. |
+| `AbloClaimedError` | Active claim conflict or claim wait timeout. |
 
 See [Client Behavior](./client-behavior.md) for retry and timeout guidance.

package/docs/audit.md

@@ -12,11 +12,11 @@ tamper-evident, queryable, exportable.
   actorId:              string,
   onBehalfOfKind:       'user' | 'agent' | 'system' | null,
   onBehalfOfId:         string | null,
-  capabilityId:         string | null,
-  capabilityLabel:      string | null,
+  credentialId:         string | null,
+  credentialLabel:      string | null,
   delegationChainRoot:  string | null,    // always points at a human
-  causedByTaskId:       string | null,
-  actionType:           string,           // e.g. 'task.update'
+  causedByRunId:        string | null,
+  actionType:           string,           // e.g. 'weatherReport.update'
   modelName:            string | null,    // e.g. 'claude-opus-4-7'
   diffSummary:          unknown,
   // tamper-evident
@@ -37,7 +37,7 @@ a thing in this system; every chain starts with a person.
 ```bash
 curl https://<your-app>/api/orgs/<slug>/audit/verify-chain?\
   principalKind=agent\
-  &principalId=task-writer-v3
+  &principalId=weather-agent-v3
 ```
 
 Returns either:

package/docs/client-behavior.md

@@ -9,9 +9,9 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
   }),
 });
 
@@ -25,7 +25,7 @@ Common options:
 
 | Option | Purpose |
 |---|---|
-| `schema` | Required for typed model resources. Omit only for advanced schema-less runtimes. |
+| `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `volatile` by default. Use `indexeddb` for browser durable cache and offline queueing. |
@@ -40,17 +40,17 @@ endpoint.
 
 ## Model Methods
 
-Each schema model becomes a typed resource:
+Each schema model becomes a typed model:
 
 ```ts
 await ablo.ready();
 
-const [task] = await ablo.tasks.load({ where: { id: 'task_123' } });
-const local = ablo.tasks.retrieve('task_123');
+const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+const local = ablo.weatherReports.retrieve('report_stockholm');
 
-await ablo.tasks.create({ title: 'Draft launch plan', status: 'todo' });
-await ablo.tasks.update('task_123', { status: 'done' }, { wait: 'confirmed' });
-await ablo.tasks.delete('task_123', { wait: 'confirmed' });
+await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
+await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
+await ablo.weatherReports.delete('report_stockholm', { wait: 'confirmed' });
 ```
 
 `load` is async hydration from local store and server. `retrieve`, `list`, and
@@ -63,15 +63,15 @@ rows.
 
 ## Multiplayer Behavior
 
-Multiplayer works when every participant uses the same model resource path. A
+Multiplayer works when every participant uses the same model client path. A
 human Server Action, a browser view, and an agent worker can all use
-`ablo.tasks`:
+`ablo.weatherReports`:
 
 ```ts
-const [task] = await ablo.tasks.load({ where: { id } });
-const snap = ablo.snapshot({ tasks: id });
+const [report] = await ablo.weatherReports.load({ where: { id } });
+const snap = ablo.snapshot({ weatherReports: id });
 
-await ablo.tasks.update(id, patch, {
+await ablo.weatherReports.update(id, patch, {
   readAt: snap.stamp,
   onStale: 'reject',
   wait: 'confirmed',
@@ -79,9 +79,9 @@ await ablo.tasks.update(id, patch, {
 ```
 
 The confirmed write fans out over realtime subscriptions. React clients that use
-`useAblo((ablo) => ablo.tasks.retrieve(id))` receive the new row, and selectors
-such as `useAblo((ablo) => ablo.intents.list({ resource: 'tasks', id }))`
-receive active intents. There is
+`useAblo((ablo) => ablo.weatherReports.retrieve(id))` receive the new row, and selectors
+such as `useAblo((ablo) => ablo.weatherReports.claimState(id))`
+receive active claim state. There is
 no extra multiplayer setup beyond routing shared state through Ablo.
 
 If an app writes directly to its database, Ablo cannot coordinate that write
@@ -90,15 +90,14 @@ until the app reports it through Data Source events.
 ## Per-Write Options
 
 ```ts
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   {
     wait: 'confirmed',
     readAt: snap.stamp,
     onStale: 'reject',
-    intent,
-    idempotencyKey: 'task_123:mark-done:v1',
+    idempotencyKey: 'report_stockholm:mark-ready:v1',
     timeout: 20_000,
   },
 );
@@ -109,31 +108,31 @@ await ablo.tasks.update(
 | `wait` | `queued` resolves after local queueing; `confirmed` waits for server acceptance. |
 | `readAt` | State cursor the write was based on. |
 | `onStale` | Policy when the target changed after `readAt`. Prefer `reject`. |
-| `intent` | Active work claim associated with this write. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 | `timeout` | Maximum time for the write call. |
 
-## Busy Behavior
+## Claimed Behavior
 
 ```ts
-const busy = ablo.intents.list({ resource: 'tasks', id: 'task_123' });
+const active = ablo.weatherReports.claimState('report_stockholm');
 
-if (busy.length > 0) {
-  await ablo.intents.waitFor(
-    { resource: 'tasks', id: 'task_123' },
-    { timeout: 30_000 },
-  );
+if (active) {
+  return { status: 'claimed', active };
 }
+
+await ablo.weatherReports.claim('report_stockholm', async (report) => {
+  await ablo.weatherReports.update(report.id, { status: 'ready' });
+});
 ```
 
-Reads never silently block. For raw resource calls, use `ifBusy`:
+Reads never silently block. For schema model calls, use `claimState(id)` to observe
+current work and `claim(id, work)` to serialize a write across a slow step:
 
-- `return` returns active intents.
-- `wait` waits for matching intents to clear.
-- `fail` throws `AbloBusyError`.
+- default `claim` waits in the fair queue and re-reads before invoking `work`;
+- `{ wait: false }` rejects with `AbloClaimedError` instead of queuing;
+- `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
-Schema clients use the realtime stream for waits. Schema-less HTTP clients must
-provide `busyPollInterval` when using `ifBusy: 'wait'`.
+Schema clients use the realtime stream for waits.
 
 ## Errors
 
@@ -149,16 +148,16 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 | `AbloValidationError` | Invalid input or unsupported request shape. |
 | `AbloServerError` | Server-side 5xx. Retry with backoff if the operation is idempotent. |
 | `AbloStaleContextError` | Write was based on stale `readAt` state. Re-read and retry. |
-| `AbloBusyError` | Active intent conflicted with `ifBusy: 'fail'` or a busy wait timed out. |
+| `AbloClaimedError` | An active claim conflicted with `{ wait: false }`, the queue was too deep, or a claim wait timed out. |
 
 ```ts
-import { AbloBusyError } from '@abloatai/ablo';
+import { AbloClaimedError } from '@abloatai/ablo';
 
 try {
-  await ablo.tasks.update('task_123', { status: 'done' }, { wait: 'confirmed' });
+  await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
 } catch (error) {
-  if (error instanceof AbloBusyError) {
-    return { status: 'busy', intents: error.intents };
+  if (error instanceof AbloClaimedError) {
+    return { status: 'claimed' };
   }
   throw error;
 }