@abloatai/ablo 0.57.0 → 0.59.0

package/docs/index.md

@@ -1,193 +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
-
-- [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/integration-guide.md

@@ -77,7 +77,7 @@ When handing this to a coding agent, give it a concrete target:
 ```txt
 Add Ablo to this app for one model your agents edit.
 Run npx ablo dev and use its branch-bound key. Declare schema, add the Ablo client, replace
-one write with ablo.<model>.update(..., { readAt, onStale: 'reject' }), and add a smoke test for two concurrent writers.
+one decision read with ablo.<model>.read(...), pass that row in the write's reads array, and add a smoke test for two concurrent writers.
 ```
 
 ## 1. Declare A Schema
@@ -93,9 +93,9 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 export const schema = defineSchema(
   {
     weatherReports: model({
-      // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy)
-      // are SDK-provided automatically — never declare them. Declare only your
-      // own fields.
+      // `id` is the only field the SDK supplies; never declare it. Audit
+      // fields are ordinary fields: declare `createdAt` / `updatedAt` /
+      // `createdBy` here if you want columns for them.
       projectId: z.string(),
       location: z.string(),
       status: z.enum(['pending', 'ready']),
@@ -158,7 +158,7 @@ falsy flag. See `packages/transaction/src/schema/model.ts` for the full option s
 Trusted runtimes can use `ABLO_API_KEY`.
 
 ```ts
-// src/ablo.ts
+// src/client/ablo.ts
 import Ablo from '@abloatai/ablo';
 import { schema } from './ablo/schema';
 
@@ -176,7 +176,7 @@ client now).
 
 ```tsx
 // src/ablo-client.ts
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // The browser never holds the API key. The client mints a short-lived token
@@ -256,7 +256,7 @@ refreshes before expiry.
 ## 3. Read State
 
 Reads come in two flavors, and you pick based on whether you can wait.
-`get({ id })` and `list({ where })` hit the server (and hydrate the local
+`get({ id })`, `read({ id })`, and `list({ where })` hit the server (and hydrate the local
 store) — they're async, so you `await` them. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` read the already-synced local
 graph synchronously, so they're the ones you call in render — and the ones you
@@ -268,7 +268,7 @@ and waits.
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
@@ -318,17 +318,17 @@ For simple writes:
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
 ```
 
-For writes based on state the user or agent already read, snapshot first and
-reject stale updates:
+For writes based on current state, use a decision read and pass the exact row
+to the mutation:
 
 ```ts
-const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
+if (!report) throw new Error('report not found');
 
 await ablo.weatherReports.update({
-  id: 'report_stockholm',
+  id: report.id,
   data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -481,12 +481,12 @@ const completeReport = tool({
     forecast: z.string(),
   }),
   execute: async ({ reportId, forecast }) => {
-    const snap = ablo.snapshot({ weatherReports: reportId });
+    const report = await ablo.weatherReports.read({ id: reportId });
+    if (!report) throw new Error('report not found');
     return ablo.weatherReports.update({
       id: reportId,
       data: { status: 'ready', forecast },
-      readAt: snap.stamp,
-      onStale: 'reject',
+      reads: [report],
     });
   },
 });
@@ -529,7 +529,7 @@ that guarantee as eventual completion with repair—not atomicity.
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
 | `durableWrites: { store, namespace? }`     | Recover unacknowledged worker writes after a process restart.      |
 | `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
-| `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
+| `read` + `reads`                          | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
 The first integration should not need most of these. Start with schema and
@@ -540,7 +540,8 @@ them.
 
 | Method                                 | Use it for                                                                       |
 | -------------------------------------- | -------------------------------------------------------------------------------- |
-| `get({ id })`                     | Async read of one row from the server (await it).                                |
+| `get({ id })`                      | Observe one row from the server (await it).                                      |
+| `read({ id })`                     | Read one decision input to carry in a mutation's `reads` array.                  |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
 | `listAll({ where, maxPages?, signal? })` | Explicit bounded traversal of every matching page; filter before collecting.   |
 | `local.get(id)`                   | Synchronous local read of one synced row (use in render).                        |

package/docs/integrations/sandbox-runtime.md

@@ -0,0 +1,157 @@
+# Anthropic Sandbox Runtime
+
+> 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, 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 |
+
+An **execution sandbox** is the disposable process boundary. An **Ablo branch**
+is an isolated data and schema plane. Keep the names and lifecycles separate.
+
+## Use two profiles
+
+Do not give a repository-editing agent the same authority as a runtime agent.
+
+The **integration profile** adapts source code. It receives no Ablo credential,
+has no Ablo network access, cannot read real environment files, and writes only
+inside the selected application root. It can still read the installed-version
+documentation without a network connection:
+
+```bash
+npm exec --offline -- ablo docs integration-guide
+npm exec --offline -- ablo docs api
+npm exec --offline -- ablo setup --plan --json
+```
+
+The **runtime profile** executes application work. It receives one short-lived,
+branch-bound runtime credential, permits the Ablo API, and normally has no
+repository write access. Give it only the model operations and sync groups one
+run needs.
+
+Never inject control-plane authority, a database URL, cloud credentials, or an
+ambient host environment into either profile.
+
+## Prepare authority outside the sandbox
+
+Run control-plane and database operations in a trusted host workflow. That
+workflow prepares the branch, pushes the reviewed schema, and delegates a
+per-run `rk_` credential. Management and broad branch credentials are
+infrastructure details and never enter the agent-facing launcher:
+
+```bash
+# Supplied by trusted CI or a credential broker after branch preparation.
+export ABLO_API_KEY=rk_...
+npm run sandbox -- agent job_123
+```
+
+The sandbox launcher should build an explicit child environment rather than
+inherit `process.env`. A runtime credential is not a substitute for process
+isolation, and process isolation is not a substitute for a narrowly scoped
+credential.
+
+## Keep the repository tree downward
+
+Give the Ablo boundary and agent behavior separate entry points:
+
+```text
+src/
+  ablo/
+    index.ts          schema-backed client boundary
+    client.ts
+    schema.ts
+  agent/
+    index.ts          process entry point
+    processJob.ts
+sandbox/
+  index.ts            sanitized launcher and command catalog
+  integration.policy.json
+  runtime.policy.json
+```
+
+The agent enters through `agent/index.ts` and follows dependencies down into
+`ablo/index.ts`. Ablo code never imports the agent or sandbox implementation.
+
+## Coordinate effects that outlive the process
+
+A filesystem sandbox cannot prevent two valid agents from overwriting the same
+shared row. Read, claim, and write through the schema-backed Ablo client:
+
+```ts
+const claim = await ablo.jobs.claim({
+  id: jobId,
+  description: 'processing in a sandbox',
+  ttl: '30s',
+  heartbeat: { every: '10s' },
+});
+
+try {
+  const result = await performWork(claim.data);
+  await ablo.jobs.update({
+    id: claim.data.id,
+    data: { status: 'complete', result },
+    claim,
+    idempotencyKey: `job:${claim.data.id}:complete`,
+  });
+} finally {
+  await claim.release();
+}
+```
+
+If the sandbox disappears, its heartbeat stops and the lease expires. A later
+holder reads fresh state. If the old process resumes, the checked write is
+refused because it no longer owns the claim.
+
+## Start from deny-first policies
+
+Sandbox Runtime denies writes and network access unless they are allowed, but
+filesystem reads require explicit deny regions. A practical policy should:
+
+- deny the user's home region, then re-allow the selected repository;
+- keep real `.env*`, SSH material, cloud configuration, and credentials denied;
+- allow writes only to the selected application root and a dedicated temporary directory;
+- allow only `api.abloatai.com:443` for an Ablo runtime agent;
+- add a model-provider domain only when the model process itself runs inside the sandbox;
+- leave Docker sockets and Apple Events disabled; and
+- use resolved literal paths because filesystem globs are not supported on Linux.
+
+Domain allowlists are coarse: an allowed domain can still be an exfiltration
+channel. Filesystem isolation, environment sanitation, and least-authority
+credentials must be used together.
+
+## Run the complete example
+
+The repository example contains the launcher, both policies, the schema-backed
+agent, and boundary tests:
+
+```bash
+cd examples/sandboxed-agent
+npm install
+npm run docs:sandboxed
+npm test
+npm run typecheck
+```
+
+Sandbox Runtime is a beta research preview. Keep it behind the launcher boundary
+so policy and API changes do not spread through application or Ablo code.
+
+## References
+
+- [Anthropic Sandbox Runtime](https://github.com/anthropic-experimental/sandbox-runtime)
+- [Agents](../agents.md)
+- [Branch-first development](../branch-development.md)
+- [Coordination](../coordination.md)