@abloatai/ablo 0.58.0 → 0.59.0

package/docs/index.md

@@ -1,198 +1,79 @@
-# Ablo Docs
+# Introduction
 
-> Collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
+> Coordination infrastructure for agents, applications, services, and people working on shared state
 
-Two agents reach for the same row. One claims it, does slow work — an LLM call,
-a fetch, a chain of tools — and commits. The second is neither rejected nor
-allowed to clobber: it waits in line, is handed the row as it now stands, and
-proceeds. Contention becomes an ordering problem instead of a retry loop.
+Ablo is a framework-agnostic coordination layer for agents, applications,
+services, and people working on shared state. It provides claims, waiting,
+participant identity, stale-work rejection, confirmed writes, and live updates
+through one typed interface. Whether you are adding agents to an existing
+application or building a new multi-user system, Ablo lets you focus on your
+product instead of rebuilding coordination infrastructure.
 
-```ts
-// Take the row. Anyone else who wants it waits, then reads it fresh.
-await using claim = await ablo.reports.claim({ id: reportId });
+Ablo works with your existing database, API, authorization, and business logic,
+while providing a common coordination model across runtimes and frameworks.
 
-await ablo.reports.update({
-  id: claim.data.id,
-  data: { forecast: await generateForecast(claim.data) },
-});
-```
+## Features
 
-Claims do not lock. A lock is held against a caller who may never come back; a
-claim is a durable lease with a wait-line behind it, so you can always ask who
-holds a row and who is queued for it. The write returns a receipt, and a write
-based on a row that has since changed is turned away rather than applied.
-
-## What people build
+Ablo provides a comprehensive set of coordination capabilities and a shared
+model that can be used across agents, services, applications, and human
+interfaces.
 
 <Columns>
-  <Card title="Run agents in parallel" icon="users" href="/coordination">
-    Many agents over one dataset. Claims put them in a line instead of a race.
+  <Card title="Claims and waiting" icon="handshake" href="/coordination">
+    Let one participant perform contested work while others wait, skip, or fail according to an explicit policy.
+  </Card>
+
+  <Card title="Existing PostgreSQL" icon="database" href="/coordinate-existing-work">
+    Keep the authoritative transaction, locks, constraints, and direct SQL paths your application already owns.
+  </Card>
+
+  <Card title="Participant identity" icon="fingerprint" href="/identity">
+    Give agents, people, and services distinct scoped credentials instead of treating every worker as the same caller.
+  </Card>
+
+  <Card title="Crash recovery" icon="rotate-ccw" href="/guarantees">
+    Expiring leases and heartbeats let later participants proceed when an owner disappears.
   </Card>
 
-  <Card title="Hand work between agents" icon="arrow-left-right" href="/agent-messaging">
-    One agent claims, works, releases. The next picks up with the fresh row and a durable note about why.
+  <Card title="Stale-work rejection" icon="shield-check" href="/concurrency-convention">
+    Carry the rows behind a decision into its write and reject the result when those premises changed.
   </Card>
 
-  <Card title="Scope what an agent may write" icon="key-round" href="/api-keys">
-    A revocable key bound to one project's models. Attribution comes from the credential, not the call site.
+  <Card title="Atomic commits" icon="git-merge" href="/api#atomic-commits">
+    Apply several Ablo writes together, with their captured premises, or apply none of them.
   </Card>
 
-  <Card title="Confirm what landed" icon="receipt" href="/guarantees">
-    Every write returns a receipt. Nothing is fire-and-forget, and stale writes are rejected.
+  <Card title="Confirmed writes" icon="receipt" href="/guarantees">
+    Know when a write reached the authoritative database and why a rejected write did not land.
   </Card>
 
-  <Card title="Audit every agent action" icon="scroll-text" href="/audit">
-    Trace any committed change back to the key that made it, and to the person who authorized that key.
+  <Card title="Humans and agents" icon="users" href="/react">
+    Coordinate stateless HTTP workers with live human interfaces over the same shared state.
   </Card>
 
-  <Card title="Keep a person in the loop" icon="hand" href="/react">
-    Add the `humans()` plugin and people get presence and live queries. A person's claim is just another holder the agent waits behind.
+  <Card title="Audit and visibility" icon="scroll-text" href="/audit">
+    Inspect ownership, contention, and committed changes with the responsible participant attached.
   </Card>
 </Columns>
 
-## Using Ablo
-
-<Steps>
-  <Step title="Declare the models agents share">
-    `npx ablo init` scaffolds `ablo/schema.ts`, the typed client, and the type registration.
-    Declare only the models agents coordinate over — your auth, billing, and everything else
-    stay in your own migrations.
-
-    ```bash
-    npx ablo init
-    npx ablo dev
-    ```
-
-    `dev` gives the current Git branch an isolated Ablo branch, wires its temporary key,
-    pushes the schema, and watches for changes. Until the server has your schema, a write to
-    a new model fails with `server_execute_unknown_model`. See
-    [Branch-first development](./branch-development.md).
-  </Step>
-
-  <Step title="Connect the database the rows live in">
-    Ablo writes through a scoped role and confirms by tailing your write-ahead log. It runs no
-    DDL and owns no schema — your migration tool stays in charge of the shape of your database.
-
-    ```bash
-    npx ablo connect
-    ```
-
-    No database yet? Pass an `apiKey` only and Ablo keeps the rows in its own log, so you can
-    build the whole system today and point it at Postgres when you are ready.
-  </Step>
-
-  <Step title="Build with Ablo">
-    You are writing the agent yourself — a worker, a job handler, a tool inside a model loop.
-    Agents hold no socket; the credential is the identity.
-
-    ```ts
-    const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
-    ```
-
-    Read with `list` / `get`, coordinate with `claim`, write with `create` / `update` /
-    `delete`. See [Agents](./agents.md) for the loop and [API Reference](./api.md) for the shape.
-  </Step>
-
-  <Step title="Or point an MCP host at it">
-    The agent is Claude, Cursor, or another MCP host, and you want it operating your data
-    directly. The coordination server exposes the same claim-and-commit loop as tools.
-
-    ```bash
-    claude mcp add ablo -- npx -y @abloatai/mcp
-    ```
-
-    See [Model Context Protocol](./mcp.md) — and read the surface table below before you pick,
-    because Ablo publishes two MCP servers and only one of them is a data plane.
-  </Step>
-</Steps>
-
-## Surfaces
-
-Every surface reaches the same coordinated state. Pick by who is calling.
-
-| Surface | Use it for |
-|---|---|
-| **SDK**: `@abloatai/ablo`, `transport: 'http'` | The agents themselves. Stateless, request/response, nothing held open. The main path. |
-| **Coordination MCP**: `@abloatai/mcp` | An agent living inside an MCP host that needs claim and commit as tools. A data plane. |
-| **`humans()`**: with `@abloatai/ablo/react` | The interfaces a person watches agent work arrive in: presence, live queries, a local copy. |
-| **CLI**: `ablo` | Scaffolding, schema push, connecting a database. Terminals and CI. |
-| **REST**: `/api/v1` | Runtimes with no SDK. |
-| **Integration-helper MCP**: hosted `/api/mcp` | Teaching a coding assistant the SDK while you build. Docs, lint, and scaffolds only. |
-
-The two MCP servers are not interchangeable. The coordination server changes
-your data; the integration-helper server serves documentation and has no
-per-model data tools at all. An agent that edits rows uses the SDK or the
-coordination server — never the helper.
-
-### Where people fit
-
-The bare client is the coordination layer: commit, read, observe, claim. People
-are something you add to it. `humans()` is the plugin that declares the local,
-watchable copy — the offline store, live queries, presence, and the framework
-bindings — and it needs a duplex connection, so a stateless agent cannot install
-it and is told so at construction rather than left with a subscription that never
-delivers.
-
-There is no `agents()` plugin, and the absence is the point: agents are the
-default caller, not a special one.
-
-## Concepts
-
-- [How Ablo Works](./how-it-works.md) — the mental model in one page: you write through Ablo, it lands in your Postgres, the write-ahead log confirms it. **Read this first.**
-- [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue`: who holds a row, and who is waiting.
-- [Concurrency Convention](./concurrency-convention.md) — the precise rule for guarded and unguarded writes.
-- [Guarantees](./guarantees.md) — what a confirmed write, a stale-write rejection, and a claim each promise.
-- [Idempotency](./idempotency.md) — make a retried write safe; what replays, what re-runs, and for how long.
-- [Schema Contract](./schema-contract.md) — one schema becomes typed clients, agent writes, React reads, and the push.
-- [Agents](./agents.md) — the stateless participant: wake, read, claim, commit, idle.
-- [Agent Messaging](./agent-messaging.md) — durable handoffs between agents, linked to the claim they discuss.
-- [Identity & Sync Groups](./identity.md) — who is connecting, and which slice of state they see.
-- [Change Propagation](./groups.md) — how one row's change reaches the actors that depend on it.
-- [Client Behavior](./client-behavior.md) — options, errors, retries, timeouts, and imports.
-
-## Authority
-
-- [Projects](./projects.md) — one organization, many apps; each with its own schema, planes, and keys.
-- [API Keys](./api-keys.md) — the credential that carries an agent's identity and its scopes.
-- [Sessions](./sessions.md) — short-lived scoped credentials your backend mints.
-- [Customer Organizations](./customer-organizations.md) — serve many isolated customer organizations from one schema and backend.
-- [Audit Log](./audit.md) — trace any confirmed write back to the person behind it.
-- [Operating on Your Database](./operating-on-your-database.md) — which actions run freely, which to verify first, and which belong to a human.
-- [Session Settings](./session-settings.md) — point your row-level-security policies at Ablo's writes, by naming the settings they already read.
-
-## Build
-
-- [Agent Integration Decision Guide](./agent-integration-decision-guide.md) — choose identifier or row claims, captured reads, atomic boundaries, persistence ownership, transport, and the smallest proof before opening an example.
-- [TypeScript Library](./libraries/typescript.md) — construct the server client,
-  keep schema ownership beneath one boundary, and select an integration approach.
-- [GraphQL.js over an Existing Backend](./approaches/graphql/graphql-js.md) —
-  keep resolvers thin and call one named Ablo-backed domain operation.
-- [Quickstart](./quickstart.md) — make your first coordinated write.
-- [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
-- [Integrations](./integrations.md) — long-running records, ingestion, and other application-edge runtimes.
-- [CLI & Migrations](./cli.md) — `init` / `connect` / `push` / `migrate` / `generate`.
-- [Connect Your Database](./data-sources.md) — where rows land when your own database is canonical.
-- [Deployment](./deployment.md) — the database, the keys, and the schema push that take an integration to production.
-- [React](./react.md) — provider, hooks, and reactive reads.
-- [Webhooks](./webhooks.md) — react to confirmed change from outside the SDK.
-- [Debugging & Logs](./debugging.md) — watch claims, queueing, and grants while you build.
-
-## Reference
-
-- [API Reference](./api.md) — model-by-model method shape.
-- [Errors](./errors.md) — the code registry, its categories, and what to do about each.
-- [Upgrade Guide](./migration.md) — upgrade a pinned pre-1.0 SDK safely.
-- [Changelog](../CHANGELOG.md) — what shipped recently.
-
-## Examples
-
-- [AI SDK Tool](./examples/ai-sdk-tool.md) — put Ablo inside a model's tool call.
-- [Agent + Human](./examples/agent-human.md) — yield when a person is holding the same report.
-- [Server Agent](./examples/server-agent.md) — a schema-backed worker.
-- [Existing Python Backend](./examples/existing-python-backend.md) — add coordination without replacing your API server.
-- [Next.js](./examples/nextjs.md) — app-router setup with React bindings.
-
-## More
-
-- [README](../README.md) — product overview and first example.
-- [AGENTS.md](../AGENTS.md) — installation guidance for coding assistants.
+...and more.
+
+---
+
+## Get started
+
+- [Installation](./installation.md) — install Ablo, declare the shared models,
+  and create a client.
+- [Basic usage](./basic-usage.md) — read, write, and coordinate one operation.
+- [Comparison](./comparison.md) — see how Ablo relates to PostgreSQL locks,
+  Redis reservations, queues, workflow engines, and rolling your own.
+- [Choose the Ablo operation](./implement.md) — route an existing use case to
+  the smallest correct implementation.
+
+## AI resources
+
+Ablo is designed to be implemented by agents as well as people. Use
+[llms.txt](https://docs.abloatai.com/llms.txt) for the public documentation
+index, or connect an assistant to the [documentation MCP server](./mcp.md). The
+coordination MCP package also ships its agent-facing skill as
+`@abloatai/mcp/skill.md`.

package/docs/installation.md

@@ -0,0 +1,77 @@
+# Installation
+
+> Install Ablo, declare the models participants share, and create a typed client.
+
+Install the Ablo TypeScript SDK in an existing or new project.
+
+## Install the package
+
+```bash
+npm install @abloatai/ablo
+npx ablo init
+```
+
+`ablo init` creates the schema, registration, and client files and signs the
+developer in. Keep these files together under one `ablo/` ownership boundary.
+
+## Declare shared models
+
+Declare only the rows Ablo coordinates. Your other tables stay in the schema
+and migrations the application already owns.
+
+```ts
+// ablo/schema.ts
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema({
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['open', 'done']),
+  }),
+});
+```
+
+Every model automatically has an `id`. Declare application fields such as
+timestamps and actor ids yourself when you need them.
+
+## Start development
+
+```bash
+npx ablo dev
+```
+
+The development command prepares an isolated Ablo branch, supplies its
+temporary `ABLO_API_KEY`, pushes the schema, and watches for changes. Runtime
+code always reads `ABLO_API_KEY`; do not put management credentials in the
+application.
+
+## Use your PostgreSQL database
+
+```bash
+npx ablo connect
+```
+
+Ablo runs no DDL and does not replace your migration tool. It writes the models
+you declared and confirms changes from PostgreSQL's write-ahead log. Existing
+APIs, direct SQL, constraints, and transactions can remain in place.
+
+## Create the client
+
+`ablo init` scaffolds this file. Start with the HTTP client for an agent or
+server operation; it has no persistent connection to manage.
+
+```ts
+// ablo/client.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from './schema';
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
+```
+
+Continue to [Basic usage](./basic-usage.md) to read, write, and coordinate one
+operation. Use the [full Quickstart](./quickstart.md) when you need the detailed
+branch, schema-registration, and database setup explanation.

package/docs/instrumentation.md

@@ -0,0 +1,52 @@
+# Instrumentation
+
+> Connect Ablo coordination outcomes and durable activity to the observability tools you already use.
+
+Ablo exposes two complementary signals: process-local coordination events for
+live telemetry, and credential-scoped logs for durable inspection.
+
+## Capture coordination events
+
+Pass an `observability` sink to the package-root client:
+
+```ts
+const ablo = Ablo({
+  schema,
+  observability: {
+    captureClaim: (event) => telemetry.capture('ablo.claim', event),
+    captureConflict: (event) => telemetry.capture('ablo.conflict', event),
+  },
+});
+```
+
+`captureClaim` reports acquisition, queueing, grant, release, loss, and expiry.
+`captureConflict` reports stale dependencies and writes rejected by another
+participant's claim. The sink should return quickly and must not be the
+correctness path for the operation it observes.
+
+## Inspect durable activity
+
+The stateless client exposes `ablo.logs` for authoritative, credential-scoped
+event pages. Use it for audit views, support tooling, and reconciliation rather
+than treating process logs as durable truth.
+
+Access is bounded by the same credential that created the client. Do not copy
+customer-wide logs into a less restricted telemetry destination.
+
+## What to measure
+
+Useful coordination measures include:
+
+- claim acquisition, wait, and hold duration;
+- queue depth and contention outcome;
+- expired or lost claims;
+- stale-context and foreign-claim rejections;
+- retry count and request latency;
+- durable-write backlog and replay outcome.
+
+Alert on sustained changes in rates, not on every expected contention event.
+Queueing and stale-write rejection are often the system preventing duplicate or
+obsolete work, not failures by themselves.
+
+See [Debugging & Logs](./debugging.md) for local diagnosis and event formatting,
+and [Audit Log](./audit.md) for stored attribution and verification.

package/docs/integrations/sandbox-runtime.md

@@ -2,12 +2,21 @@
 
 > Run an Ablo agent with OS-enforced filesystem and network boundaries while its coordinated work remains durable outside the sandbox.
 
+## Choose the write owner first
+
+- If the sandbox reads and writes shared Ablo rows itself, continue with this page.
+- If the sandbox only returns a prepared result and the host process commits
+  through an existing application operation, **stop here and open**
+  [Coordinate existing work](../coordinate-existing-work.md).
+  That guide owns the implementation. Keep the operation, its database
+  transaction, and the existing Ablo wiring.
+
 Anthropic Sandbox Runtime and Ablo own different boundaries:
 
 | Concern | Owner |
 |---|---|
 | Filesystem, network, Unix sockets, process-tree restrictions | Sandbox Runtime |
-| Typed reads and writes, claims, fencing, idempotency, confirmation | Ablo |
+| Typed reads and writes, claims, safe retries, and confirmation | Ablo |
 | Prompts, tools, model calls, and business behavior | Your application |
 | Authentication, branch creation, schema push, and database connection | A trusted host workflow |
 

package/docs/migration.md

@@ -11,13 +11,14 @@ releases remain compatible within the same minor line.
 2. Read the changelog entries between your installed and target versions.
 3. Use the documentation bundled with the target package while changing code.
 4. Run type-checks and tests before updating a production branch.
-5. Push schema changes deliberately after reviewing the generated diff.
+5. Run the three-state deployment plan, then push the exact reviewed plan.
 
 ```bash
 npm install @abloatai/ablo@0.48
 npx ablo docs
 npx ablo docs api
-npx ablo check
+npx ablo plan
+npx ablo plan --json
 ```
 
 `npx ablo docs` is version-matched to the installed package. Prefer it during an
@@ -41,17 +42,21 @@ types and server-confirmed identity instead.
 
 ## Schema and database safety
 
-An SDK upgrade and a database migration are separate operations.
+An SDK upgrade and a database migration are separate operations coordinated by
+one deployment plan.
 
-- `ablo push` updates Ablo's typed schema contract. It does not run application
-  DDL or drop your tables.
-- `ablo check` compares the contract with the connected database without
-  changing it.
+- `ablo plan` compares source, the active Ablo artifact, and PostgreSQL without
+  changing any of them. Its fingerprint pins all three observations.
+- `ablo push` consumes that reviewed fingerprint and refuses if any state moved.
+- `ablo check` is the database-compatibility view of the same plan.
 - Your ORM or migration tool remains responsible for tables, columns,
   constraints, and application data migrations.
 
 When both need to change, deploy the database migration in a backwards-compatible
 form first, push the compatible Ablo schema, then remove old application paths.
+For a live rename or required-field change, keep expand, dual-write, resumable
+backfill, verification, switch, and contract as explicit gates. Contract is a
+later, separately approved deployment—not the tail of expand.
 
 ## If an upgrade fails
 

package/docs/options.md

@@ -0,0 +1,172 @@
+# Options
+
+> Every option accepted by the default `Ablo({ ... })` client.
+
+Import `Ablo` from `@abloatai/ablo`. Only `schema` is required. A server can
+usually rely on `ABLO_API_KEY` and keep the constructor small:
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { schema } from './ablo/schema';
+
+export const ablo = Ablo({ schema });
+```
+
+These options configure the stateless HTTP client exported by the package root.
+For a live human interface, use the [React guide](./react.md).
+
+## schema
+
+The schema created with `defineSchema()`. It gives each declared model a typed
+`ablo.<model>` client. This is the only required option.
+
+## apiKey
+
+A server API key, or an async function that resolves a credential at request
+time. When omitted, Ablo reads `ABLO_API_KEY`.
+
+```ts
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+```
+
+Use a resolver for credentials that rotate. Return `null` when the login has
+ended; throw when credential resolution failed temporarily. Do not pass both
+`apiKey` and `authEndpoint`.
+
+## authEndpoint
+
+A same-origin URL that mints a short-lived credential, or an async credential
+resolver. The client sends a `POST` with cookies included and renews the token
+when needed.
+
+```ts
+const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+```
+
+Use this instead of placing a private API key in browser code.
+
+## authToken
+
+A bearer token the caller already holds. This is mainly for self-hosted or
+custom authentication layers. Hosted applications normally use `apiKey` or
+`authEndpoint`.
+
+## baseURL
+
+Overrides the Ablo API URL. Leave it unset for hosted Ablo. Use it for a private
+deployment, local development proxy, or test server.
+
+```ts
+const ablo = Ablo({ schema, baseURL: 'https://ablo.internal.example' });
+```
+
+Because credentials are sent to this URL, Ablo rejects URLs containing embedded
+credentials, query parameters, or fragments. Plain HTTP is accepted only for
+local hosts.
+
+## dangerouslyAllowBrowser
+
+Allows a credential-bearing client to run in a browser. Defaults to `false`.
+
+Private API keys must not ship to browsers. Prefer `authEndpoint`; enable this
+option only when the browser receives a narrowly scoped session credential or
+all traffic passes through a controlled server proxy.
+
+## fetch
+
+A custom `fetch` implementation for tests, proxies, or runtimes without the
+standard global implementation.
+
+## authTimeoutMs
+
+The deadline in milliseconds for a request to `authEndpoint`. Defaults to
+`10000`. This is separate from `timeoutMs`, which covers ordinary Ablo API
+requests.
+
+## allowCrossOriginAuthEndpoint
+
+Allows `authEndpoint` to use a different origin. Defaults to `false`.
+
+Keep the default unless the credential-minting service intentionally lives on a
+different trusted origin.
+
+## bootstrapBaseUrl
+
+Overrides the URL used for credential exchange and bootstrap. Most applications
+should leave this unset and use `baseURL` for a private or test deployment.
+
+## defaultHeaders
+
+Headers included with every Ablo HTTP request. A `null` value removes a default
+header.
+
+```ts
+const ablo = Ablo({
+  schema,
+  defaultHeaders: { 'x-deployment': 'worker-eu' },
+});
+```
+
+Do not use this option to duplicate the credential header; authentication is
+owned by `apiKey`, `authEndpoint`, or `authToken`.
+
+## defaultQuery
+
+Query parameters included with every Ablo HTTP request. This is primarily for
+proxies and controlled test deployments.
+
+## observability
+
+A sink for claim lifecycle and rejected-write events. It implements
+`captureClaim(event)` and `captureConflict(event)`. Use it to connect Ablo's
+coordination outcomes to the application's existing telemetry.
+
+```ts
+const ablo = Ablo({
+  schema,
+  observability: {
+    captureClaim: (event) => telemetry.capture('ablo.claim', event),
+    captureConflict: (event) => telemetry.capture('ablo.conflict', event),
+  },
+});
+```
+
+## durableWrites
+
+Persists an outbound write before dispatch so a worker can recover an
+unacknowledged `create`, `update`, or `delete` after a crash.
+
+```ts
+const ablo = Ablo({
+  schema,
+  durableWrites: { store, namespace: 'invoice-worker' },
+});
+```
+
+The store must implement `seal()`, `list()`, and `remove()`. `namespace` separates
+deployments or workflow lanes sharing the same authenticated actor. Most clients
+do not need durable writes.
+
+## commitOutbox
+
+Deprecated compatibility name for the durable write store. Use
+`durableWrites: { store }`. Passing both forms is an error.
+
+## commitOutboxScope
+
+Deprecated compatibility scope for `commitOutbox`. Authentication now resolves
+actor identity. Use `durableWrites.namespace` when shared storage needs separate
+workflow or deployment lanes.
+
+## transport
+
+The package-root client uses request/response HTTP. `transport: 'http'` is
+accepted but optional.
+
+Live state, presence, and local reads belong to the reactive client described in
+the [React guide](./react.md), rather than another value on this option.
+
+## timeoutMs
+
+The deadline in milliseconds for an Ablo HTTP request. Defaults to `30000`. Pass
+`0` only when the surrounding runtime already enforces a deadline.

package/docs/quickstart.md

@@ -281,6 +281,7 @@ await ablo.weatherReports.update({
     status: 'ready',
     forecast: weather.summary,
   },
+  claim: handle,
 });
 // scope exit releases the claim — no manual release, even if the work threw
 ```
@@ -307,7 +308,11 @@ if (active) {
 }
 
 await using handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' });
-await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await ablo.weatherReports.update({
+  id: handle.data.id,
+  data: { status: 'ready' },
+  claim: handle,
+});
 ```
 
 Use `contention: { mode: 'skip' }` when work should be skipped instead of