@abloatai/ablo 0.57.0 → 0.59.0

package/docs/client-behavior.md

@@ -1,8 +1,11 @@
 # Client Behavior
 
-> Per-write options, claim behavior, and which errors are safe to retry.
+> Guarded writes, claim behavior, and which errors are safe to retry.
 
-When several writers touch the same data at once — an agent worker, a Server Action, a person in the browser — the SDK decides whose write lands and how the others find out. This page is the reference for that: per-write options like `wait` and `onStale`, claiming a record so your slow work runs uninterrupted, and which errors are safe to retry.
+When several writers touch the same data at once — an agent worker, a Server
+Action, a person in the browser — the SDK protects explicit read dependencies
+and claims records across slow work. This page describes those guarantees and
+which errors are safe to retry.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
 
@@ -25,20 +28,10 @@ const ablo = Ablo({
 });
 ```
 
-Common options:
-
-| Option | Purpose |
-|---|---|
-| `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. An HTTPS origin, optionally with a path prefix; plain HTTP is accepted for localhost. Your key travels here, so a URL carrying its own credentials, a query, or a fragment is refused at construction. |
-| `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
-| `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
-| `transport` | `'websocket'` (default) is the live, stateful client: a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |
-| `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
-| `defaultHeaders` | Extra headers attached to every HTTP request. |
-| `defaultQuery` | Extra query parameters attached to every HTTP request. |
-| `dangerouslyAllowBrowser` | Required before sending an API key from browser code. Prefer a server route instead. |
+The package-root export is the stateless HTTP client for agents, workers, route
+handlers, and other server operations. See [Options](./options.md) for its exact
+constructor reference. Live state and local reads are added through the
+[React client](./react.md).
 
 Your database connects out of band — through logical replication (`npx ablo
 connect`), or the signed [Data Source](./data-sources.md) endpoint as the
@@ -53,7 +46,7 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 const local = ablo.weatherReports.local.get('report_stockholm');
 
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
@@ -65,7 +58,7 @@ On the reactive client, each model write changes local state optimistically
 before the call returns. Its promise always waits for authoritative
 confirmation, so `await update(...)` is the confirmation barrier.
 
-Call `get`/`list` first — they fetch from the server and you `await` them.
+Call `get`/`list` to observe, or `read` when a later mutation depends on the row.
 After that, `local.get`/`local.list`/`local.count` read the already-synced data instantly with
 no `await`, and stay reactive in render. Use the async pair to load, the sync trio
 to read.
@@ -83,14 +76,13 @@ through the same model client path. A human Server Action, a browser view, and a
 agent worker can all use `ablo.weatherReports`:
 
 ```ts
-const report = await ablo.weatherReports.get({ id });
-const snap = ablo.snapshot({ weatherReports: id });
+const report = await ablo.weatherReports.read({ id });
+if (!report) throw new Error('Row not found');
 
 await ablo.weatherReports.update({
   id,
   data: patch,
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -106,24 +98,28 @@ actor routing through Ablo is coordinated. The one write it can't coordinate is
 one made directly against your database, around Ablo — the WAL echo still catches
 it for reads, but it bypasses claims and ordering.
 
-## Per-Write Options
+## Guarded Writes
 
 ```ts
+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],
   idempotencyKey: 'report_stockholm:mark-ready:v1',
 });
 ```
 
 | Option | Purpose |
 |---|---|
-| `readAt` | State cursor the write was based on. |
-| `onStale` | Policy when the target changed after `readAt`. Prefer `reject`. |
+| `reads` | Exact rows returned by `read` that this mutation depends on. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 
+A stale premise always rejects with `AbloStaleContextError`. Omit `reads` only
+when the assignment is intentionally unconditional.
+
 ## Claimed Behavior
 
 If your update involves a slow step — an API call, an LLM round-trip — and someone
@@ -163,7 +159,9 @@ stream, so they never poll.
 
 ## Errors
 
-All SDK errors extend `AbloError` and carry a stable `type`.
+All SDK errors extend `AbloError`. `type` is the class-name discriminator, such
+as `AbloStaleContextError`; `code` is the wire condition, such as
+`stale_context`. Use `instanceof` in-process and `type` after serialization.
 
 | Error | Typical cause |
 |---|---|

package/docs/comparison.md

@@ -0,0 +1,63 @@
+# Comparison
+
+> How Ablo relates to the coordination tools an experienced team may already use.
+
+Teams do not need Ablo to build a lock. Redis reservations and PostgreSQL locks
+are proven, inexpensive primitives. Ablo is useful when the same team would
+otherwise have to define ownership, expiry, recovery, waiting, participant
+identity, stale-result handling, and visibility for each new workflow.
+
+## Versus PostgreSQL locks
+
+- **Keep the lock.** PostgreSQL should continue to protect the short,
+  authoritative database transaction.
+- **Coordinate before the transaction.** An Ablo claim can cover the model call,
+  document search, browser session, or tool run that happens before commit.
+- **Keep the connection short-lived.** The application does not have to hold one
+  database session while an agent waits on external work.
+- **Revalidate at commit.** The existing service still applies authorization,
+  constraints, version checks, and business rules.
+
+## Versus Redis reservations
+
+- **The primitive is familiar.** Ablo uses expiring leases for live ownership
+  and waiting; it does not claim that temporary reservations are novel.
+- **The lifecycle is defined.** Acquisition, skip, wait, heartbeat, release,
+  expiry, cancellation, and recovery share one client contract.
+- **Ownership has identity.** A claim belongs to a scoped participant rather
+  than only an arbitrary worker string.
+- **Correctness stays durable.** PostgreSQL and commit-time version checks remain
+  the backstop when an expired worker resumes late.
+- **Contention is visible.** Owners, waiters, duration, and rejection reasons use
+  the same operational model across workflows.
+
+## Versus queues and workflow engines
+
+- Queues decide who receives a job; claims decide who may act on a contested
+  business resource.
+- Redelivery still needs idempotency, and delivery does not prove the rows behind
+  a decision are unchanged.
+- Workflow engines remain the right owner for durable steps, timers, and retry
+  history. Ablo coordinates those workflows with other agents, services, and
+  people touching the same state.
+
+## Versus rolling your own
+
+- Start without designing Redis key conventions, ownership tokens, renewal,
+  safe release, wait queues, and crash recovery for every call site.
+- Reuse one participant and authorization model across workers and human
+  interfaces.
+- Test against one documented failure contract instead of rebuilding delayed
+  worker, expiry, retry, and partial-failure tests per workflow.
+- Add captured reads, guarded writes, and atomic Ablo commits only when the
+  operation needs them.
+
+## When Ablo is not necessary
+
+PostgreSQL or a small internal reservation can be enough when one team controls
+every writer, work is short, contention is rare, and stale or duplicate work is
+cheap. Ablo becomes more valuable as slow agent work, independent participants,
+shared resources, recovery, authority, and operational explanation matter.
+
+The adoption boundary is intentionally small: keep the architecture that
+already works and [coordinate one existing operation](./coordinate-existing-work.md).

package/docs/concurrency-convention.md

@@ -1,59 +1,81 @@
 # Concurrency Convention
 
-> What Ablo checks when a guarded write depends on earlier state.
+> A write either declares what it read or deliberately does not.
 
-Ablo never infers whether a write depends on earlier state. You decide, in two
-places. The model's `conflict` setting in the schema says what each kind of
-participant does when it hits a conflict, and it is the policy for that model.
-A per-write `onStale` states the disposition for one write. Ablo enforces what
-you declared and nothing else.
+Use a captured read when a write must be rejected because an earlier premise
+changed.
 
-## Unguarded writes
-
-A plain write has no stale premise:
+Read the authoritative premise, carry
+that exact evidence into the write, and handle the documented failure code.
 
-```ts
-await ablo.records.update({ id, data: { status: 'done' } });
-```
+Ablo does not put a configurable stale mode between your code and a
+commit. The public choice is visible at the call site:
 
-If no active claim conflicts with it, the write is last-write-wins. That is a
-choice rather than a fallback: use it for independent assignments where the
-latest value should win. When a model's writes are never independent, say so
-once in its `conflict` setting instead of at every call site.
+- `get` and `list` observe state. They do not create a write premise.
+- `read` returns a row that can be passed to a mutation in `reads`.
+- a mutation with `reads` rejects with `AbloStaleContextError` if any declared
+  premise changed;
+- a mutation without `reads` is an unconditional, last-write-wins assignment
+  when no active claim applies.
 
 ## Guarded writes
 
-Pass the exact returned rows when a write is based on values previously read:
+Use `read` for every row that materially influenced a decision, then pass the
+exact returned objects to the mutation:
 
 ```ts
-const record = await ablo.records.get({ id });
-const policy = await ablo.policies.get({ id: policyId });
-if (!record || !policy) throw new Error('required input is missing');
+const record = await ablo.records.read({ id });
+const rules = await ablo.rules.read({ id: rulesId });
+if (!record || !rules) throw new Error('required input is missing');
 
 await ablo.records.update({
   id: record.id,
-  data: { status: 'done' },
-  reads: [record, policy],
+  data: decide(record, rules),
+  reads: [record, rules],
 });
 ```
 
-Ablo privately resolves each exact object to its model, id, and read watermark,
-then compares those premises with current state when the write is accepted.
-Clones, fabrications, and rows returned by another client are rejected locally.
+Ablo records only the evidence needed for the check: model, id, and the
+watermark at which the row was read. It does not retain the row's contents.
+The exact object identity matters, so clones, fabricated rows, and rows from a
+different client are rejected locally.
+
+The server validates every declared premise inside the write transaction. If
+one is stale, the entire mutation rejects before any write applies. Re-read,
+recompute, and submit a new mutation when that is the behavior you want.
+
+```ts
+import { AbloStaleContextError } from '@abloatai/ablo';
+
+try {
+  await submitGuardedWrite();
+} catch (error) {
+  if (error instanceof AbloStaleContextError && error.code === 'stale_context') {
+    return rebuildFromFreshReads();
+  }
+  throw error;
+}
+```
+
+`error.type` is the class-name discriminator (`AbloStaleContextError`);
+`error.code` is the wire condition (`stale_context`).
+
+## Unguarded writes
+
+Use `get` or `list` when you only need to observe, and omit `reads` when the
+new value should win regardless of what was previously observed:
 
-| Disposition | If the premise is stale |
-|---|---|
-| `reject` | Reject the write with `AbloStaleContextError`. |
-| `notify` | Keep the current row, return a `StaleNotification`, and let the caller reconcile. |
-| `overwrite` | Apply the new value without enforcing the stale premise. |
+```ts
+const visible = await ablo.records.get({ id });
+await ablo.records.update({ id, data: { status: 'done' } });
+```
 
-`notify` is useful when an agent or human can merge the new information.
-`reject` is useful when the caller should restart from fresh state. Use
-`overwrite` only when the newer assignment should unconditionally win.
+This is deliberately unconditional, not an implicit fallback. It is suitable
+for independent assignments and inappropriate for read-modify-write decisions.
 
 ## Functional updates
 
-For a pure read-modify-write calculation, use the functional update form:
+For a pure calculation based on one current row, use the functional form:
 
 ```ts
 await ablo.counters.update(counterId, (current) => ({
@@ -61,59 +83,54 @@ await ablo.counters.update(counterId, (current) => ({
 }));
 ```
 
-It performs the read, guarded write, and bounded reconciliation loop for you.
-See [Coordination](./coordination.md#functional-updates).
+The SDK reads, attempts a guarded write, and retries from fresh state within a
+bounded budget. Because the updater may run more than once, do not perform
+side effects inside it.
 
 ## Claims
 
-A claim protects a target across a longer interval. By default, other
-participants cannot write the claimed target, while contenders that claim it
-wait their turn. Reads remain open. A model's explicit conflict policy can
-choose a different disposition for a participant kind.
+A claim protects a target across a slower read → decide → write interval.
+Foreign writers are rejected while the claim is active; contenders that ask
+to queue wait in order. Ordinary reads stay open.
 
-Claims and stale guards protect different things:
+When the final effect remains in an existing application path—such as its API,
+database transaction, filesystem, or Git merge—start with
+[Coordinate existing work](./coordinate-existing-work.md). Use the
+row-backed claim below when the target and final write belong to an Ablo model.
 
-- A claim excludes other participants while it is held.
-- A stale guard proves that the state a write depended on has not changed.
-- A write made under a claim is still rejected if its own claimed snapshot has
-  become stale.
+Claims and stale reads answer different questions:
 
-See [Coordination](./coordination.md#claims) for the API.
+| Mechanism | Lifetime | Question |
+|---|---|---|
+| `reads` | One mutation | Is every input to this decision still current? |
+| claim | Slow work interval | Who may write this target while work is underway? |
+| database transaction | One apply | Can this physical change commit atomically? |
+| idempotency key | Retries | Has this same mutation already been applied? |
 
-## Cross-row and batch premises
+Claims do not hold a Postgres transaction open while an agent thinks. The
+database transaction remains short and owns only validation plus apply.
 
-Model writes and lower-level commits can declare rows they read even when the
-write targets somewhere else. This protects decisions such as “update the record
-only if the deal I inspected has not changed.” A stale batch premise applies to
-the whole batch so atomicity is preserved.
-
-Use the high-level model methods unless you are building a custom runtime. When
-you do use batch premises, declare only the rows or groups that materially
-influenced the decision; overly broad premises create unnecessary contention.
-
-## Notifications
+## Cross-row and batch premises
 
-A `StaleNotification` identifies the stale premise and provides the current
-state needed to reconcile. The original write has not been applied.
+A write may depend on rows other than its target. Put every influential row in
+`reads`; if any one changed, Ablo rejects the whole mutation so atomicity is
+preserved. Declare only material dependencies, because broader premises create
+more contention.
 
-A typical loop is:
+Low-level runtimes can also declare row or group watermarks directly. They have
+the same fixed result: stale rejects, fresh applies.
 
-1. Inspect the current value in the notification.
-2. Recompute the intended change.
-3. Submit a new guarded write with a fresh premise.
+## Live change delivery is separate
 
-Give this loop a retry budget. Continuous contention should surface to the
-caller rather than retry forever.
+Model `onChange` is not a stale-write disposition. It streams committed changes
+to a stateful WebSocket client. `context().onChange` has the narrower job of
+calling once when one of that context's exact reads changes; HTTP delivers it
+through a response held open for that listener. Neither replaces passing those
+same `reads` to create, update, or delete.
 
 ## Boundaries
 
-Concurrency control does not replace:
-
-- database constraints and transactions for application invariants;
-- authorization for deciding who may read or write;
-- idempotency for safely replaying the same request;
-- claims for exclusivity across slow, side-effecting work.
-
-The rule is simple: the model's `conflict` setting is the policy, and each write
-declares what it read. Plain writes are last-write-wins because declaring
-nothing is itself a decision, so make it deliberately.
+Concurrency control does not replace authorization, database constraints,
+transactions, or idempotency. The rule at the SDK boundary is intentionally
+small: `read` declares a dependency, `reads` enforces it, and omission means an
+unconditional write.

package/docs/context.md

@@ -1,12 +1,12 @@
 # Context
 
 > Assemble the current information for an action and carry its authoritative
-> Ablo reads into the write that follows.
+> Ablo reads into the model write or atomic commit that follows.
 
 `context()` is a standalone SDK function. It does not run a model, keep a
 conversation, search documents, or create memory. The application chooses the
 values; Ablo awaits them and identifies the exact returned rows that can guard
-a later write.
+a later model write or atomic commit.
 
 ## Context, model, write
 
@@ -21,7 +21,7 @@ import { generateText } from 'ai';
 const ctx = await context({
   ablo,
   data: {
-    record: ablo.records.get({ id: recordId }),
+    record: ablo.records.read({ id: recordId }),
     records: ablo.records.list({ where: { recordId } }),
     memory: loadMemories(recordId),
   },
@@ -42,6 +42,25 @@ await ablo.records.update({
 });
 ```
 
+The same captured rows guard an atomic batch. There is no second read format
+and no manual conversion step:
+
+```ts
+await ablo.commits.create({
+  operations: [
+    { action: 'update', model: 'records', id: recordId, data: update },
+    { action: 'create', model: 'auditEvents', id: eventId, data: event },
+  ],
+  reads: ctx.reads,
+  idempotencyKey: runId,
+});
+```
+
+Both the stateless HTTP client and the reactive WebSocket client resolve these
+captured rows into canonical `{ model, id, readAt }` dependencies before the
+commit reaches the transport. A claim returned by a typed model resource can
+also be passed directly as the batch `claim`.
+
 If an authoritative row moves during the model call, the update rejects with
 `AbloStaleContextError`. Rebuild the context before trying again. The model is
 not called or retried by `context()`.
@@ -54,7 +73,7 @@ protection according to the work:
 | Situation | Use | Why |
 |---|---|---|
 | Bring several current values into one model call | `context()` | Awaits the selected values and collects their evidence. |
-| Reject if any selected Ablo row moves | `reads: ctx.reads` | Checks those premises when the write reaches the server. |
+| Reject if any selected Ablo row moves | `reads: ctx.reads` | Checks those premises when a model write or atomic commit reaches the server. |
 | Avoid paying for a model call while another participant owns the row | `claim()` | Waits first, then supplies fresh state. |
 | Compute a patch from one current row without external work | Functional `update()` | Re-reads and retries the pure calculation. |
 
@@ -64,39 +83,69 @@ See [Coordination](./coordination.md) for the full choice.
 
 ## Result
 
-The result has four members:
+The result has three members:
 
 | Member | Meaning |
 |---|---|
 | `data` | The selected values, with nested promises resolved. |
-| `reads` | Exact Ablo rows accepted by a write's `reads` option. |
-| `cursor` | The greatest watermark among those authoritative reads, or `null`. |
-| `sources` | One provenance summary for each top-level value. |
+| `reads` | Exact Ablo rows accepted by a model write or atomic commit's `reads` option. |
+| `onChange` | Calls a listener once if any exact row in `reads` changes. Returns a function that stops listening. |
 
-If a row in `ctx.reads` moves before the write, the server rejects the write as
-stale. A plain value can inform the action, but it does not gain that guarantee.
-This distinction is visible in `sources`:
+If a row in `ctx.reads` moves before a model write or atomic commit, the server
+rejects the operation as stale. Plain values remain in `ctx.data`, but only
+exact Ablo reads appear in `ctx.reads` and gain that guarantee.
 
-```ts
-ctx.sources;
-// [
-//   { key: 'record', kind: 'ablo', guarantee: 'guardable', cursor: 42 },
-//   { key: 'memory', kind: 'value', guarantee: 'informational', cursor: null },
-// ]
-```
+## Stop work when context changes
 
-A top-level value may contain both kinds. It is then marked `mixed` and only
-its exact Ablo rows appear in `ctx.reads`:
+`onChange` lets long-running work stop early without changing the write rule:
 
 ```ts
-// data: { briefing: { record, memory } }
-// sources: [
-//   { key: 'briefing', kind: 'mixed', guarantee: 'partial', cursor: 42 },
-// ]
+const controller = new AbortController();
+const stop = ctx.onChange((error) => controller.abort(error));
+
+try {
+  const result = await generateText({
+    model,
+    abortSignal: controller.signal,
+    messages: [contextMessage(ctx)],
+  });
+
+  await ablo.records.update({
+    id: ctx.data.record.id,
+    data: parseTaskUpdate(result.text),
+    reads: ctx.reads,
+  });
+} finally {
+  stop();
+}
 ```
 
-`partial` does not weaken the included Ablo rows. It says the surrounding value
-also contains information Ablo cannot guard.
+The first listener starts delivery and all listeners on that context share it.
+The last returned `stop` closes it. A context with no reads opens nothing. The
+first matching change calls every listener with `AbloStaleContextError`, then
+delivery closes. The final create, update, or delete must still receive
+`reads: ctx.reads`; that check remains authoritative if delivery races the
+write or is disconnected.
+
+## Retry stale agent work
+
+Use this policy for a long-running turn:
+
+1. Create one operation key before the retry loop.
+2. Build a new context on every attempt.
+3. Use `onChange` to abort the model and cancellable tools.
+4. Still pass `reads: ctx.reads` to the final write.
+5. Retry a stale attempt at most a small fixed number of times.
+
+Automatic retry is safe only before the first external action that cannot be
+canceled. After sending an email, charging a card, or receiving an uncertain
+tool response, look up that action by the same operation key. Do not run it
+again unless that tool explicitly guarantees the retry is safe.
+
+[`examples/stale-context-agent-turn.ts`](../examples/stale-context-agent-turn.ts)
+is the complete copyable loop. Put that function in the application operation
+that owns the write; GraphQL resolvers and route handlers should call it once,
+not add another retry loop.
 
 ## External context
 
@@ -108,7 +157,7 @@ Reducto, or another system behind their own interfaces.
 const ctx = await context({
   ablo,
   data: {
-    record: ablo.records.get({ id: recordId }),
+    record: ablo.records.read({ id: recordId }),
     memory: loadMemories({ query, userId }),
     related: findRelatedChunks({ projectId, query }),
     evidence: extractEvidence({ recordId }),
@@ -157,14 +206,10 @@ The first version deliberately has no:
 
 - search or memory API;
 - provider registry or provider-specific adapter;
-- `since` cursor or incremental `changes` result;
 - context session, persistence, or sharing lifecycle;
 - token counting, trimming, summarisation, or model call;
 - guarantee that a person or model understood the included information.
 
-Store `ctx.cursor` in application-owned state if it is useful. Incremental
-context is not yet derived from it.
-
 `context` remains available as a schema model name. The helper lives at
 `@abloatai/ablo/context`; it does not add `ablo.context()` or reserve a member
 of the schema-backed client.