@abloatai/ablo 0.57.0 → 0.59.0

package/docs/integrations.md

@@ -13,6 +13,7 @@ into authoritative application state.
 
 | Category | Integration | Status | Use it for |
 |---|---|---|---|
+| Agent execution | [Anthropic Sandbox Runtime](./integrations/sandbox-runtime.md) | Available | Restricting the filesystem, network, sockets, and inherited authority of an agent process |
 | Long-running records | [Temporal](./integrations/temporal.md) | Available | Durable Workflows, Activity retries, timers, cancellation, and durable AI SDK calls |
 | Long-running records | [Inngest](./integrations/inngest.md) | Available | Event-driven durable functions, retriable steps, flow control, and checkpointed AI SDK calls |
 | Data ingestion | Connector runtimes | Planned | Bringing external data into Ablo-backed models without creating a second write authority |
@@ -22,6 +23,14 @@ the boundary has been tested. A dedicated package comes later still: only
 repeated production integrations that reveal substantial reusable behavior
 justify adding another public runtime dependency.
 
+## Agent execution
+
+Use [Anthropic Sandbox Runtime](./integrations/sandbox-runtime.md) to enforce the
+boundary around an agent process. The runtime owns filesystem and network
+access. Ablo remains below it and owns typed shared-state operations, claims,
+idempotency, and confirmation. The runnable example lives in
+`examples/sandboxed-agent`.
+
 ## Long-running records
 
 Use [Temporal](./integrations/temporal.md) when work must survive process

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/operating-on-your-database.md

@@ -39,6 +39,13 @@ Ablo prevents a non-holder from writing through another participant's claim by
 default. It does not infer that every plain update is a read-modify-write
 operation; use the guarded forms when lost-update protection matters.
 
+Direct SQL remains outside that enforcement path. If an existing application
+service writes the same row directly, keep its database constraints and locks
+as the final integrity boundary and route every participating caller through
+one named operation. Ablo can select one worker before expensive work begins;
+the existing service must still re-read, validate, and commit authoritatively.
+See [Coordinate an existing database operation](./coordination.md#coordinate-an-existing-database-operation).
+
 ## Three kinds of action
 
 Sort any action you're about to take into one of these, and the right move

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

@@ -10,10 +10,11 @@ confirms it by tailing your write-ahead log (WAL). Your rows live in your databa
 which stays the system of record. Ablo writes rows but **runs no DDL and owns no
 schema** — your migration tool stays in charge of the shape of your database.
 
-> No database yet? Pass an `apiKey` only and Ablo keeps your rows in its own log,
-> so you can build the whole app today. Point it at a
-> separate or local Postgres for a development branch, or at your production
-> database when you're ready.
+> **Which database?** A branch needs one connected before a schema will push, so
+> start on a throwaway rather than your production Postgres. `ablo dev` gives
+> each Git branch its own isolated plane: point a development branch at a local
+> or separate database, and connect your production one when you're ready for it
+> to be the system of record.
 
 ## 1. Install and initialize
 
@@ -26,14 +27,16 @@ npx ablo init
 by signing you in — one browser click, and a project-scoped `mk_` management
 credential is saved locally. Later, `npx ablo dev` (step 4) prepares an isolated branch and writes
 its temporary `ABLO_API_KEY` into `.env.local`, so the SDK follows your Git
-branch with no manual copy-paste. `npx ablo login` also exists standalone. In
-CI, set project management access explicitly:
+branch with no manual copy-paste. `npx ablo login` also exists standalone.
+Headless CI uses the same credential input as every other Ablo process; during branch
+preparation it contains an `mk_` credential:
 
 ```bash
-export ABLO_MANAGEMENT_KEY=mk_...
+export ABLO_API_KEY=mk_...
 ```
 
-Every runtime call needs a branch-bound API key. `ablo dev` exchanges the
+Do not pass that value to application code. Every runtime call needs a
+branch-bound API key. `ablo dev` exchanges the
 stored management credential for
 an expiring `sk_*` key bound to the current development branch.
 Production runtimes use `sk_*`. In production a key points at the database
@@ -67,9 +70,12 @@ export const schema = defineSchema({
 });
 ```
 
-**Reserved fields** — `id`, `createdAt`, `updatedAt`, `organizationId`, and
-`createdBy` are provided by the SDK automatically. Don't declare them in your
-`model(...)` fields; declare only your own.
+**`id` is the only automatic field.** Every row carries one, so leave it out of
+`model(...)`. Everything else is yours, audit fields included: declare
+`createdAt`, `updatedAt` or `createdBy` and `ablo migrate` gives each a column,
+which your write or a database default then fills. Ablo does not write them for
+you. A model that omits them still reads and writes, it just orders and
+attributes its history less precisely.
 
 The schema is registered once (init scaffolds `ablo/register.ts` for you), and
 every type is one parameter away — no `typeof schema` re-stating, anywhere:
@@ -229,12 +235,12 @@ const updated = await ablo.weatherReports.update({
 console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
-Read a single row back with `get({ id })`. It resolves to the row, or to
+Read a single row back with `read({ id })`. It resolves to the row, or to
 `undefined` when no row has that id — so narrow it once, then the fields are
 fully typed:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: created.id });
+const report = await ablo.weatherReports.read({ id: created.id });
 if (!report) throw new Error(`weatherReports ${created.id} not found`);
 
 console.log(report.status); // 'ready'
@@ -275,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
 ```
@@ -301,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

package/docs/react.md

@@ -25,7 +25,7 @@ as props. Construct the client once, then pass that instance to the provider.
 
 ```ts
 // lib/ablo.ts
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { createAbloReact } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
@@ -140,12 +140,12 @@ const reports = useAblo((ablo) =>
 ## Server Load
 
 ```tsx
-const report = await ablo.weatherReports.get({ id });
+const report = await ablo.weatherReports.read({ id });
 ```
 
 Use `get` in Server Components when the row may not be in the local pool
 yet — it hydrates from the local store and the server, and returns a Promise, so
-`await` it. (Server reads come in two shapes: `get({ id })` for one row and
+`await` it. (Server reads come in two shapes: `read({ id })` for one row and
 `list({ where })` for many; both are async. The synchronous local reads are
 the `local` reads, used in render below.)
 
@@ -156,12 +156,12 @@ For Server Actions and route handlers, call the SDK directly:
 ```ts
 import { ablo } from '@/lib/ablo';
 
-const snap = ablo.snapshot({ weatherReports: id });
+const report = await ablo.weatherReports.read({ id });
+if (!report) throw new Error('report not found');
 await ablo.weatherReports.update({
   id,
   data: patch,
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -173,12 +173,12 @@ const ablo = useAblo();
 
 async function markReady() {
   if (!ablo) return;
-  const snap = ablo.snapshot({ weatherReports: id });
+  const report = await ablo.weatherReports.read({ id });
+  if (!report) return;
   await ablo.weatherReports.update({
     id,
     data: { status: 'ready' },
-    readAt: snap.stamp,
-    onStale: 'reject',
+    reads: [report],
   });
 }
 ```

package/docs/schema-contract.md

@@ -51,26 +51,27 @@ The model key (`weatherReports`) becomes the client namespace
 contract. You should not create a parallel string-keyed write path for the same
 data.
 
-### Reserved fields
+### The one field you don't declare
 
-The SDK provides these on every row automatically — do **not** declare them in
-your `model(...)` fields:
+`id` is supplied on every row, so leave it out of your `model(...)` fields. That
+is the whole list.
 
-- `id`
-- `createdAt`
-- `updatedAt`
-- `organizationId`
-- `createdBy`
+Two things look like framework territory and are not. **Audit fields are yours to
+declare and yours to fill.** Add `createdAt`, `updatedAt` or `createdBy` and
+`ablo migrate` gives each a column, which your own write or a database default
+then populates; Ablo records who changed what in its transaction log and does not
+write these columns for you. Omit them and no column is created at all; the model
+still reads and writes, it just orders and attributes its history less precisely.
 
-Declare only your own fields; the reserved ones are still present on the row and
-readable, you just don't author them.
+**The tenancy column** (`organizationId` by default) comes from the model's
+`policy` rather than its field list, so you neither declare it nor lose it.
 
 ## Reads and writes
 
 Use async reads when the row may not be local:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: reportId });
+const report = await ablo.weatherReports.read({ id: reportId });
 const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
 ```
 
@@ -123,8 +124,8 @@ session route, never a raw API key.
 - Keep direct database writes out of the coordinated path unless they are reported
   back through Data Source events.
 - Use `claim` for slow read -> think -> write spans.
-- Use `readAt` + `onStale: 'reject'` when a write must fail if the row changed
-  after it was read.
+- Use `read` and pass its exact row in `reads` when a write must fail if the row
+  changed after it was read.
 
 For the shortest runnable path, start with [Quickstart](./quickstart.md). For a
 production app, continue with [Integration Guide](./integration-guide.md).

package/docs/security.md

@@ -0,0 +1,64 @@
+# Security
+
+> The authority boundaries to preserve when agents, applications, and people coordinate through Ablo.
+
+Ablo carries authenticated participant identity into coordination and writes.
+It does not replace your application's authorization, PostgreSQL constraints, or
+transactional invariants.
+
+## Keep secret credentials on the server
+
+Trusted agents, workers, route handlers, and services use a server-side `sk_`
+credential, normally supplied through `ABLO_API_KEY`. Never include it in a
+browser bundle or agent-generated output.
+
+Browsers use either a publishable read-only `pk_` credential or a short-lived,
+scoped session minted by your backend through `authEndpoint`. See [API
+Keys](./api-keys.md) and [Sessions](./sessions.md) for the credential classes and
+minting flow.
+
+## Give every participant its own identity
+
+Claims are re-entrant for the same participant. Two workers that share one
+credential can therefore appear to Ablo as the same owner. Use separate scoped
+participant credentials when independently operating agents must contend.
+
+The credential also determines project, branch, organization, and allowed
+operations. Callers cannot broaden that authority by adding ids to a request.
+
+## Treat claims as coordination, not authorization
+
+A claim says who currently owns a piece of work. It does not grant permission to
+read or write that resource. Authorization is evaluated independently, and the
+final write must still satisfy the database schema and application invariants.
+
+Claims are leases rather than permanent locks. They expire when their owner
+stops heartbeating. A guarded Ablo write checks ownership again at commit time so
+an expired participant cannot use an old claim handle.
+
+## Keep PostgreSQL authoritative
+
+Ablo coordinates work before and during a write; PostgreSQL remains the durable
+source of truth. Existing constraints, transactions, row-level security, and
+short database locks can remain in place.
+
+A direct database write bypasses Ablo's claims and request ordering. Logical
+replication makes the result visible to Ablo readers, but cannot retroactively
+coordinate the writer. Preserve database constraints for every invariant that
+must also hold for bypass writers.
+
+## Bound external side effects separately
+
+Ablo idempotency covers an Ablo request. It cannot make an email, payment, model
+call, or third-party API mutation exactly once. Give the external provider its
+own idempotency key, or persist an application-owned effect record and reconcile
+ambiguous outcomes.
+
+## Report vulnerabilities privately
+
+Do not put credentials, customer data, or an unpatched vulnerability in a public
+issue. Report it through [GitHub Security
+Advisories](https://github.com/Abloatai/ablo/security/advisories/new).
+
+For operational checks and key rotation, continue to [API Keys](./api-keys.md),
+[Audit Log](./audit.md), and [Operating on Your Database](./operating-on-your-database.md).

package/docs/sessions.md

@@ -74,7 +74,7 @@ plumbing:
 ```tsx
 'use client';
 
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo.schema';
 

package/examples/README.md

@@ -30,8 +30,8 @@ For read-reason-write work, pass the exact returned rows that informed the
 decision. Their watermarks stay opaque:
 
 ```ts
-const record = await ablo.records.get({ id: recordId });
-const policy = await ablo.policies.get({ id: policyId });
+const record = await ablo.records.read({ id: recordId });
+const policy = await ablo.policies.read({ id: policyId });
 const result = await model({ record, policy });
 await ablo.records.update({
   id: record.id,
@@ -48,6 +48,11 @@ rejected locally.
 heartbeating claim, post-grant model input, durable commit inspection, automatic
 release, and a released-claim fencing check.
 
+`stale-context-agent-turn.ts` owns the standard long-running agent policy:
+subscribe to exact-read changes, abort cancellable work, retain the guarded
+write, rebuild context for bounded retries, and reconcile rather than replay
+after an irreversible side effect.
+
 Import the same schema in every runtime. Use `commits.create` only when several
 typed row operations must land atomically; ordinary writes stay on
 `ablo.<model>.create/update/delete`.
@@ -63,6 +68,7 @@ cd packages/ablo
 ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
 ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/agent-turn.ts
 ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
+ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/stale-context-agent-turn.ts
 ```
 
 ## Data Source (customer-owned database)

package/examples/agent-turn.ts

@@ -21,7 +21,7 @@ if (!recordId) throw new Error('RECORD_ID is required');
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 try {
   await ablo.ready();
-  const record = await ablo.records.get({ id: recordId });
+  const record = await ablo.records.read({ id: recordId });
   if (!record) throw new Error(`Record ${recordId} was not found`);
   const commitId = `record:${recordId}:cheap`;
   await ablo.records.update({

package/examples/expensive-agent-turn.ts

@@ -49,7 +49,7 @@ try {
   if (!durable) throw new Error(`Commit ${commitId} was not retained`);
   console.log({
     identity: ablo.identity,
-    readSet: durable.readSet,
+    reads: durable.reads,
     attempts: durable.attempts,
     claims: durable.claims,
     authority: durable.authority,