@abloatai/ablo 0.57.0 → 0.59.0

package/docs/coordinate-existing-work.md

@@ -0,0 +1,104 @@
+# Coordinate Existing Work
+
+> Start here. Preserve the application, coordinate one operation, and read another page only when the routing table sends you there.
+
+Use this guide to coordinate expensive work while its existing PostgreSQL
+transaction remains authoritative.
+
+Many production systems already reserve slow work in Redis and protect the
+final write with a PostgreSQL transaction. That is a sound architecture. The
+cost appears when every workflow must independently define ownership, expiry,
+heartbeat, waiting, recovery, participant identity, and operational visibility.
+
+Ablo standardizes that coordination lifecycle. It does not replace the
+application's authoritative transaction.
+
+## Existing backend: copy this shape
+
+For an application that already owns its API and Postgres transaction:
+
+1. Choose one named operation, such as `completeTask`.
+2. Keep its API, authorization, validation, transaction, locks, and constraints.
+3. Give each concurrent worker a distinct scoped credential.
+4. Claim the operation's stable business identifier before expensive work.
+5. While the claim is held, call the existing operation to commit.
+
+```ts
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
+
+await using lease = await ablo.taskRuns.claim(taskId, {
+  contention: { mode: 'skip' },
+  ttl: '30s',
+  heartbeat: { every: '10s' },
+});
+if (!lease) return { outcome: 'skipped' };
+
+const prepared = await performExpensiveWork(taskId);
+return existingTaskService.commitPrepared(taskId, prepared);
+```
+
+The string passed to `claim` is an identifier-only lease. It does not require an
+Ablo row and returns no row data. `commitPrepared` must still re-read and validate
+inside the application's Postgres transaction. An Ablo lease does not join a
+transaction in another process.
+
+If the operation only needs to inspect an Ablo row before calling the existing
+write path, keep it this small:
+
+```ts
+const task = await ablo.tasks.get({ id: taskId });
+if (!task) throw new Error('task not found');
+
+await completeTask({ id: task.id, expectedTitle: task.title });
+return task.id;
+```
+
+`get({ id })` observes a row. Use `read({ id })` only when its captured evidence
+will be passed to an Ablo write through `reads`.
+
+## Change the shape only when required
+
+| Your operation requires this | Use | Read |
+|---|---|---|
+| The claimed target is an Ablo model row and the final write goes through that model. | Row-backed claim; pass the returned `claim` to the write. | [Coordination](../coordination.md) |
+| The result depends on an Ablo row that may change while work runs. | `read(...)` the premise and pass it through `reads`. | [Concurrency Convention](../concurrency-convention.md) |
+| Several Ablo writes must all land or none may land. | One `commits.create(...)`. | [API Reference](../api.md) |
+| A person needs live state, presence, or reactive local reads. | WebSocket client for that human interface. Workers stay on HTTP. | [React](../react.md) |
+| The operation sends email, charges money, writes a file, or calls another provider. | That system's idempotency key or an application outbox. | [Idempotency](../idempotency.md) |
+
+Do not add a mechanism unless its condition is true. In particular, do not
+replace an existing database operation merely because Ablo coordinates it.
+
+## Check these boundaries before editing
+
+- What existing operation and public result must remain unchanged?
+- What stable identifier represents the contested work?
+- Which process performs expensive work, and which process commits?
+- Does Postgres or Ablo own each final write?
+- What does the caller receive on contention, failure, and retry?
+
+If an answer is unknown, preserve the existing write path. Do not copy an
+advanced example or expand the schema to hide the missing decision.
+
+## Prove the implementation
+
+For the adopted operation, test that:
+
+1. The coordinated and existing paths return the same public result.
+2. Two distinct participants do not both perform the expensive work.
+3. A contender follows the chosen skip or wait behavior.
+4. Failure or expiry allows a later attempt to proceed.
+5. The existing authorization and database transaction still run.
+
+Local tests prove application behavior. Run
+[`examples/coordination-conformance`](../../../../examples/coordination-conformance/README.md)
+against hosted Ablo to prove participant identity, heartbeat, exclusion, release,
+and expiry. Run staging against the real database and authorization to prove the
+production boundary.
+
+For setup, read the [Integration Guide](../integration-guide.md). The complete
+implementation on this page is the starter route for an existing backend.

package/docs/coordination.md

@@ -2,6 +2,20 @@
 
 > Choose plain writes, functional updates, stale guards, or claims without losing concurrent work.
 
+This page owns row coordination: acquire ownership, proceed from the granted
+state, and release on every exit path.
+
+## Choose the owner first
+
+| Where the result lands | Start here |
+|---|---|
+| Existing application path: API, GraphQL operation, Postgres transaction, filesystem write, or Git branch merge | [Coordinate existing work](./coordinate-existing-work.md) |
+| Ablo model row, written through the Ablo client | Continue on this page |
+
+If Ablo only decides who may start, use the first row and stop here. The claim
+examples below own Ablo-row writes; they are not the starter for wrapping an
+existing operation.
+
 Ablo gives you several concurrency tools because not every write has the same
 meaning. Choose the narrowest one that matches the operation.
 
@@ -9,7 +23,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 +39,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 +105,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 +115,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
 
@@ -149,19 +139,66 @@ const forecast = await generateForecast(claim.data.location);
 await ablo.reports.update({
   id: claim.data.id,
   data: { forecast, status: 'ready' },
+  claim,
 });
 ```
 
 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.
+then resolves with a fresh row in `claim.data`. Ordinary reads remain open. Pass
+the handle as `claim` on the write so Ablo can verify that you still own the row
+and that it has not changed since the claim was granted.
 
 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
 without explicit resource management, use `try/finally` and
 `await claim.release()`.
 
+### Handle an expired claim
+
+When heartbeat is unset, the lease ends at its TTL. A delayed write that passes
+the expired handle rejects with `AbloClaimedError` and code `claim_lost`. Do not
+apply the prepared result elsewhere; clean up best-effort, then restart from a
+new claim and its fresh `claim.data`.
+
+```ts
+import { AbloClaimedError } from '@abloatai/ablo';
+
+const claim = await ablo.tasks.claim({ id: taskId, ttl: '2s' });
+try {
+  await new Promise((resolve) => setTimeout(resolve, 2300));
+  await ablo.tasks.update({
+    id: claim.data.id,
+    data: { status: 'done' },
+    claim,
+  });
+} catch (error) {
+  if (error instanceof AbloClaimedError && error.code === 'claim_lost') {
+    console.log(error.code);
+  } else {
+    throw error;
+  }
+} finally {
+  try { await claim.release(); } catch { /* already expired */ }
+}
+```
+
+### Keep a claim alive
+
+Set `ttl` to how quickly another worker should recover if this one stops. If the
+work can take longer, set `heartbeat: true` so Ablo renews the claim:
+
+```ts
+const claim = await ablo.records.claim({
+  id: recordId,
+  ttl: '30s',
+  heartbeat: true,
+});
+```
+
+Leave `heartbeat` out when the claim should expire after the TTL; do not pass
+`false`. If a write returns `claim_lost`, discard that result, claim the row
+again, and restart from the new `claim.data`.
+
 ### One identity per participant
 
 Explicit claims coordinate authenticated participants. Two clients using the
@@ -198,7 +235,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 +263,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 +301,17 @@ 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.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. |
 
+This page owns row-backed claims: `model.claim({ id })` reads and claims an Ablo
+model row, and the handle carries fresh data. Identifier-only claims before an
+existing authoritative service have a different persistence boundary; use the
+[coordinate-existing-work guide](./coordinate-existing-work.md) for that form.
+
 ## Choosing correctly
 
 - Prefer a plain update for values that do not depend on an earlier read.

package/docs/data-sources.md

@@ -110,12 +110,12 @@ migrations — your migration tool stays in charge of the shape of your database
 Ablo only writes rows into tables you already have, through a role scoped to
 exactly that.
 
-> **Just trying Ablo?** You don't need a database to start. Pass an `apiKey` only,
-> and Ablo keeps your rows in its own log so you can build the whole app today.
-> `ablo dev` gives each Git branch its own isolated plane.
-> Keep it hosted with no database, or point that branch at a separate/local
-> Postgres. Connect your production root (below) when you're ready for its
-> database to be the system of record.
+> **Just trying Ablo?** Start on a throwaway Postgres rather than your production
+> one. `ablo dev` gives each Git branch its own isolated plane, so point that
+> branch at a separate or local database, build against it, and connect your
+> production root (below) when you're ready for its database to be the system of
+> record. A branch with nothing connected refuses a schema push, which is the
+> first thing you'll hit if you skip this.
 
 Connecting sets up two capabilities on your Postgres: **logical replication**, so
 Ablo can read and confirm, and a **scoped DML role**, so Ablo can write. `ablo
@@ -475,6 +475,12 @@ directly by other application code is visible only if that code writes the same
 outbox record in its transaction. Native WAL observation sees both Ablo and
 external writes.
 
+Endpoint events use a versioned envelope. Version 2 freezes `syncGroups` in the
+writing transaction; version 1 is retained only to decode events written by an
+older adapter during a rolling upgrade. Poll requests keep `cursor` (where to
+read) separate from `acknowledgedThrough` (what Ablo has durably accepted), and
+the built-in adapters prune acknowledged rows in bounded batches.
+
 ## Next steps
 
 - [Quickstart](./quickstart.md) — connect and write through `ablo.<model>`.

package/docs/debugging.md

@@ -86,7 +86,7 @@ Read it as the lifecycle of one claim:
 - **`queued … position N of M`:** the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
 - **`granted … your turn`:** you reached the head of the line; the lease is now yours and the row may have changed while you waited.
 - **`rejected … held by <who>`:** your claim was refused because someone else holds it (and the model's policy didn't let you in).
-- **`lost`:** you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
+- **`lost`:** you held the lease and it ended (the queue fairness ceiling advanced, or it expired).
 - **`released`:** you (or `await using`'s scope exit) gave the lease back.
 
 ## Where the logs run

package/docs/deployment.md

@@ -229,6 +229,24 @@ ABLO_API_KEY=sk_… npx ablo webhooks list   # endpoints + delivery health
 place to look when a mirror falls behind. [Webhooks](./webhooks.md) covers the
 handler, the Standard Webhooks signature, and rolling a secret.
 
+## Multi-stage schema changes
+
+`ablo plan` is the read-only front door for source, active artifact, and
+PostgreSQL together. For a live rename, type transition, or required-field
+change, commit a deployment manifest and pass the same file to plan and push.
+Its gates are `expand`, `dual_write`, `backfill`, `verify`, `switch`, and
+`contract`; each names an owner, resource, dependencies, status, and action.
+
+```bash
+npx ablo plan --manifest ablo/deployment.json
+npx ablo push --manifest ablo/deployment.json --yes
+```
+
+A live manifest cannot combine expand and contract for the same resource.
+Contract belongs in a later manifest with its own recorded `approval`. A
+backfill being finished is not contract evidence; verification and client-drain
+gates must also be satisfied.
+
 ## What to watch once it is live
 
 - **`ablo logs`:** commit activity as it happens, scoped by the key. A
@@ -263,7 +281,7 @@ and what each promises.
    `ablo connect check` all green.
 2. A secret `sk_` in the deploy environment as `ABLO_API_KEY` — never in a
    browser bundle.
-3. `ablo push --yes` in the pipeline, ahead of the code that needs the new models.
+3. `ablo plan` reviewed, followed by fingerprint-gated `ablo push --yes`.
 4. `ablo status --json` gating the deploy on an empty `blockers` array.
 5. Browser clients on a root-bound `pk_` or an `authEndpoint`, not a secret key.
 6. Webhook endpoints registered at their deployed URLs, with the signing secret

package/docs/examples/agent-human.md

@@ -25,7 +25,7 @@ a typed error if the row moved underneath you while the agent was busy.
 ## Schema-Backed Worker
 
 The worker uses the same schema client the app uses. It reads the record from the
-server with `get({ id })`, claims the row, and writes through
+server with `read({ id })`, claims the row, and writes through
 `ablo.records.update(...)` with a stale-check so a concurrent edit can't be
 overwritten.
 
@@ -49,8 +49,8 @@ const ablo = Ablo({
 export async function markDone(recordId: string) {
   await ablo.ready();
 
-  // get({ id }) is an async server read — await it.
-  const record = await ablo.records.get({ id: recordId });
+  // read({ id }) is an async server read — await it.
+  const record = await ablo.records.read({ id: recordId });
   if (!record) return { status: 'not_found' };
 
   try {
@@ -67,21 +67,9 @@ export async function markDone(recordId: string) {
     await using claim = acquired;
     if (claim.data.status === 'done') return { status: 'noop' };
 
-    // Inside an active claim, `update` is stale-checked automatically: the SDK
-    // attaches the claim's snapshot version as `readAt` and sets
-    // `onStale: 'reject'`. The write below is therefore equivalent to passing
-    // those options yourself:
-    //
-    //   ablo.records.update({
-    //     id: claim.data.id,
-    //     data: { status: 'done' },
-    //     readAt: <claim snapshot version>,
-    //     onStale: 'reject',
-    //   });
-    //
-    // If a newer version landed mid-run, the row no longer matches `readAt`, so
-    // the server rejects this commit with AbloStaleContextError (caught below)
-    // instead of clobbering that edit.
+    // The claim handle carries its acquisition snapshot. If a newer version
+    // somehow lands mid-run, the server rejects this commit with
+    // AbloStaleContextError instead of clobbering that edit.
     const updated = await ablo.records.update({
       id: claim.data.id,
       data: { status: 'done' },

package/docs/examples/coordination-conformance.md

@@ -0,0 +1,69 @@
+# Verify hosted coordination separately
+
+> Prove claim behavior once, without coupling the proof to a document, workflow, or GraphQL schema.
+
+Use two test layers when adopting Ablo behind an existing application:
+
+| Proof | Responsibility |
+|---|---|
+| Domain contract | State transitions, stale evidence, provenance, idempotency, and old/new path parity. |
+| Hosted coordination conformance | Participant identity, exclusion, heartbeat, release, and lease-expiry recovery. |
+
+The runnable hosted proof is
+[`examples/coordination-conformance`](../../../../examples/coordination-conformance/README.md).
+It creates a temporary test branch that inherits an existing non-production
+schema. It does not push a schema or change domain rows.
+
+## File structure
+
+```text
+src/conformance/index.ts
+  -> src/conformance/claimExclusion.ts
+  -> src/conformance/contract.ts
+src/runtime/index.ts
+  -> src/runtime/client.ts
+  -> src/runtime/config.ts
+live/index.ts
+  -> live/claimAndExit.ts
+```
+
+The conformance operation depends on a narrow structural claim interface. The
+runtime child supplies the real Ablo model resource. Domain examples depend on
+the same narrow behavior without inheriting this runner's branch or credential
+setup.
+
+## Run
+
+First run the deterministic structure and configuration checks:
+
+```bash
+cd examples/coordination-conformance
+npm test
+npm run typecheck
+```
+
+Then name an existing model on the CLI login's dedicated non-production
+project:
+
+```bash
+ABLO_CONFORMANCE_MODEL=existingModel npm run test:live
+```
+
+The model name supplies only a typed claim namespace. Every claim target is a
+new random identifier; the proof creates no model row. The disposable branch
+is deleted even when an assertion fails.
+
+The runtime deliberately calls `model.claim(id, options)`. This identifier
+overload is row-free. `model.claim({ id, ...options })` is the row-backed form:
+it reads the model row and is not interchangeable in a coordination-only
+rollout.
+
+## What this lets domain examples omit
+
+A document-processing example does not need its own branch provisioning,
+session delegation, heartbeat, or process-death fixture. It must still test its
+own behavior when a claim is won, skipped, released after failure, and combined
+with changing evidence.
+
+This separation prevents a vertical testcase from force-replacing an inherited
+schema merely to re-prove generic lease behavior.