@abloatai/ablo 0.56.0 → 0.58.0

package/docs/concurrency-convention.md

@@ -1,59 +1,59 @@
 # 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.
+Ablo does not put a configurable stale mode between your code and a
+commit. The public choice is visible at the call site:
 
-## Unguarded writes
-
-A plain write has no stale premise:
-
-```ts
-await ablo.records.update({ id, data: { status: 'done' } });
-```
-
-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.
 
-| 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. |
+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.
 
-`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.
+## 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:
+
+```ts
+const visible = await ablo.records.get({ id });
+await ablo.records.update({ id, data: { status: 'done' } });
+```
+
+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 +61,49 @@ 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:
+Claims and stale reads answer different questions:
 
-- 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.
+| 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? |
 
-See [Coordination](./coordination.md#claims) for the API.
+Claims do not hold a Postgres transaction open while an agent thinks. The
+database transaction remains short and owns only validation plus apply.
 
 ## Cross-row and batch premises
 
-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.
+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.
 
-## Notifications
+Low-level runtimes can also declare row or group watermarks directly. They have
+the same fixed result: stale rejects, fresh applies.
 
-A `StaleNotification` identifies the stale premise and provides the current
-state needed to reconcile. The original write has not been applied.
+## Live change delivery is separate
 
-A typical loop is:
-
-1. Inspect the current value in the notification.
-2. Recompute the intended change.
-3. Submit a new guarded write with a fresh premise.
-
-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,49 @@ 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.
 
 ## External context
 
@@ -108,7 +137,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 +186,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.

package/docs/coordination.md

@@ -9,7 +9,7 @@ meaning. Choose the narrowest one that matches the operation.
 |---|---|---|
 | Set an independent value | `update({ id, data })` | Last-write-wins when no claim applies. |
 | Compute a value from the current row | `update(id, current => next)` | Re-reads and retries if the row changes concurrently. |
-| Write only if earlier rows are still current | `reads: [record, policy]` | Rejects when an explicitly named dependency changed. |
+| Write only if earlier rows are still current | `reads: [record, rules]` | Rejects when an explicitly named dependency changed. |
 | Read, call a model, then write | `claim({ id })` | Other participants cannot write the claimed target by default until your claim ends. |
 
 **If a model call sits between the read and the write, take a claim.** A stale
@@ -25,8 +25,8 @@ does not carry a stale premise. It is intentionally last-write-wins.
 Pass the exact rows that produced a decision on the write:
 
 ```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 });
 if (!record || !policy) throw new Error('required input is missing');
 
 const result = await model({ record, policy });
@@ -91,7 +91,7 @@ Use explicit returned rows when application code reads first and writes later,
 but does not need to reserve the row:
 
 ```ts
-const report = await ablo.reports.get({ id: reportId });
+const report = await ablo.reports.read({ id: reportId });
 if (!report) throw new Error('report missing');
 
 await ablo.reports.update({
@@ -101,37 +101,13 @@ await ablo.reports.update({
 });
 ```
 
-The dispositions are:
-
-| `onStale` | Behavior |
-|---|---|
-| `reject` | Reject the write if its premise is stale. |
-| `notify` | Leave the row unchanged and return the current value for reconciliation. |
-| `overwrite` | Apply the write without a stale check. |
+There is no stale-mode option on the write. If a declared row changed, Ablo
+rejects the whole mutation with `AbloStaleContextError`. Re-read and recompute,
+or use the functional update form when the computation is pure and retryable.
+To make an unconditional assignment, omit `reads` deliberately.
 
 See [Concurrency Convention](./concurrency-convention.md) for guarded batches
-and notifications.
-
-### Decide the model's conflict policy
-
-Who yields is a design decision about the model, not something to restate on
-every write. Declare it once, in the schema, and it travels to the server with
-the rest of the model:
-
-```ts
-import { coordination, model, z } from '@abloatai/ablo/schema';
-
-const cards = model(
-  { title: z.string() },
-  {
-    conflict: coordination.humansOverwrite().agentsReject(),
-  },
-);
-```
-
-An omitted participant kind uses the engine default, `reject`. A per-write
-`onStale` states the disposition for that one write. Keep the policy simple, and
-document any rule that lets a participant overwrite a held claim.
+and the `get` / `read` boundary.
 
 ## Claims
 
@@ -155,7 +131,7 @@ await ablo.reports.update({
 If another participant already holds the target, `claim` waits its turn and
 then resolves with a fresh row in `claim.data`. Ordinary reads remain open. By
 default, a write from a participant that does not hold the active claim is
-rejected; an explicit model conflict policy can choose otherwise.
+rejected.
 
 Bind claims with `await using` whenever possible. The claim then releases when
 the scope exits, including when the external call or write throws. For runtimes
@@ -198,7 +174,7 @@ try {
 }
 ```
 
-To wait with limits, keep the policy together:
+To wait with limits, keep the contention settings together:
 
 ```ts
 const claim = await ablo.records.claim({
@@ -226,6 +202,19 @@ await using claim = await ablo.records.claim({
 Claims on disjoint fields can coexist. A whole-row claim conflicts with every
 field claim on that row.
 
+### Relations do not create hierarchical claims
+
+A `parent: true` relation controls ownership, access inheritance, and sync
+routing. It does not make claims conflict across related rows. For example, a
+claim on one document row and a claim on one of its page rows have different
+model-and-ID targets and can coexist.
+
+Choose the row that represents the actual unit of exclusive work. Page rows
+allow different pages to process concurrently. If a whole-document operation
+must exclude every page operation, enumerate the authoritative page manifest,
+acquire page claims in one stable order, and guard the manifest against change.
+Do not infer that exclusion from the schema relation alone.
+
 The target options are:
 
 | Option | Purpose |
@@ -251,12 +240,102 @@ The main methods are:
 
 | Method | Purpose |
 |---|---|
-| `claim({ id })` | Acquire the target, waiting by default. |
+| `claim({ id, ...options })` | Read and claim an existing model row; the handle includes fresh row data. |
+| `claim(id, options)` | Claim an identifier in a registered model namespace without reading a row. |
 | `claim.state({ id })` | Read the current holder without blocking. |
 | `claim.queue({ id })` | Read the current wait order. |
 | `claim.release({ id })` | Release early when you do not hold a handle. |
 | `join({ scope })` | Observe presence for a broader scope. |
 
+Choose the overload deliberately:
+
+| Form | Evidence requirement | Typical use |
+|---|---|---|
+| `model.claim({ id })` | The row exists and the caller may read it. | Coordinate work on a synchronized row while using `handle.data`. |
+| `model.claim(id, options)` | The model namespace is registered; no row is read. | Select one participant before calling an existing authoritative service. |
+
+The identifier-only form is row-free, not schema-free. It does not authorize a
+worker or test fixture to push an unrelated model into an inherited production
+schema. Register the namespace through the application's normal schema process,
+or select an already registered namespace whose ownership matches the operation.
+
+## Coordinate an existing database operation
+
+Use this pattern when an application already has a service that protects a
+transition with a Postgres row lock or advisory lock, but slow preparation such
+as OCR, a model call, or another tool currently happens while that database
+lock is held.
+
+Keep the ownership boundary explicit:
+
+| Owner | Responsibility |
+|---|---|
+| Ablo claim | Select one participating worker before expensive work begins. |
+| Application service | Authoritative re-read, transition policy, database lock, idempotency, and commit. |
+| Postgres | Canonical row, constraints, and final integrity boundary. |
+
+The operation runs in this order:
+
+```text
+claim identifier
+  -> prepare expensive result once
+    -> application service re-reads and commits under its database lock
+      -> release claim in finally
+```
+
+Model the service seam as two operations rather than moving database policy
+into a resolver, worker, or agent tool:
+
+```ts
+interface ExistingOperationService<Input, Result, Row> {
+  run(
+    input: Input,
+    prepare: () => Promise<Result>,
+  ): Promise<Row>;
+
+  commitPrepared(
+    input: Input,
+    prepared: Result,
+  ): Promise<Row>;
+}
+```
+
+The existing rollout path calls `run` and preserves current behavior. The
+coordinated path wins the claim, prepares once, then calls `commitPrepared`.
+Both methods stay under the same application-service owner and enforce the same
+authorization and transition rules.
+
+When the transition permits it, implement `commitPrepared` as one SQL statement
+that acquires a transaction-level advisory lock, re-reads the row, validates
+its current state, and updates it. The statement's implicit transaction
+releases the advisory lock automatically. This can remove several sequential
+client/database round trips without replacing the existing database lock.
+
+Do not make any of these substitutions:
+
+- Do not assume a remote Ablo request joins a local Postgres transaction.
+- Do not remove database constraints or locks during the coordination rollout.
+- Do not prepare expensive work speculatively before the claim resolves.
+- Do not assume direct SQL writers obey an Ablo claim. A claim coordinates only
+  callers routed through the participating operation.
+- Do not use a claim as durable workflow state. A lease expires; workflow
+  progress must survive independently.
+
+Measure the old and coordinated paths with the same inputs. Record cold and
+warm claim acquire/release latency, database round-trip latency, database-lock
+duration, end-to-end latency, duplicate work under contention, and recovery
+after worker exit. Keep a per-operation switch to the old path until the new
+path preserves behavior and improves the selected race at production
+percentiles.
+
+For a runnable GraphQL.js implementation and PostgreSQL race/crash proof, see
+[GraphQL.js over an existing backend](./approaches/graphql/graphql-js.md).
+For a domain-neutral hosted lease proof, see
+[Verify hosted coordination separately](./examples/coordination-conformance.md).
+For the same operation boundary applied to source-versioned document
+processing, see
+[Process an existing document once](./examples/existing-document-pipeline.md).
+
 ## Choosing correctly
 
 - Prefer a plain update for values that do not depend on an earlier read.