@abloatai/ablo 0.58.0 → 0.59.0

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.
 
@@ -125,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.
+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
@@ -241,100 +302,15 @@ The main methods are:
 | Method | Purpose |
 |---|---|
 | `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).
+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
 

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/{existing-document-pipeline.md → evidence-backed-document-pipeline.md}

@@ -1,9 +1,9 @@
-# Process an existing document once
+# Build an evidence-backed document pipeline
 
 > This is an advanced evidence-backed state reference, not the default Ablo
 > integration tutorial. If you are coordinating an operation that already owns
 > its Postgres write, start with the
-> [Agent Integration Decision Guide](../agent-integration-decision-guide.md).
+> [coordinate existing work guide](../coordinate-existing-work.md).
 
 > Coordinate expensive processing over an application-owned document without taking ownership of uploads or storage.
 

package/docs/faq.md

@@ -0,0 +1,75 @@
+# FAQ
+
+> Short answers to the implementation choices developers encounter most often.
+
+## Does Ablo replace PostgreSQL?
+
+No. PostgreSQL remains the durable source of truth. Keep its schema, constraints,
+transactions, row-level security, and short write locks. Ablo coordinates work
+around that state and can route guarded writes into it.
+
+## Does Ablo replace Redis locks?
+
+It can replace an application-owned reservation layer, but it does not require a
+rewrite. Ablo standardizes resource identity, participant identity, leases,
+waiting, recovery, stale-work rejection, and visibility. Teams can begin by
+coordinating an existing operation while its final transaction remains in the
+application.
+
+## Is Ablo only for agents?
+
+No. Agents, workers, application services, and people can coordinate over the
+same resources. The package-root client is suited to stateless server work; the
+[React client](./react.md) adds live state and presence for human interfaces.
+
+## Which client should I import?
+
+Use the default export from `@abloatai/ablo` for agents, workers, route handlers,
+and server operations. It uses ordinary request/response HTTP. Use
+`@abloatai/ablo/react` when a live interface needs local synchronized state,
+subscriptions, or presence.
+
+## What is the difference between get and read?
+
+`get({ id })` observes the current row. `read({ id })` captures the exact row
+version as evidence for a later guarded write. Pass that returned row in the
+mutation's `reads` array when the decision must be rejected if its premise
+changed.
+
+## When should I claim a resource?
+
+Claim before slow or expensive work when another participant should not perform
+conflicting work on the same business resource. Do not add a claim to every
+write: a short, independent update can use its normal database and mutation
+semantics.
+
+## Is a claim a database lock?
+
+No. A claim is a participant-scoped lease held across work that may outlive one
+database transaction. It expires after heartbeat loss. PostgreSQL locks still
+protect the short authoritative transaction.
+
+## What if code writes directly to PostgreSQL?
+
+Ablo observes the resulting change through the configured data source, but the
+writer bypasses Ablo claims and request ordering. Keep database constraints for
+rules that must apply to every writer.
+
+## Are retries exactly once?
+
+Ablo idempotency deduplicates the same Ablo request within its retention window.
+It does not make external side effects exactly once. Use the external provider's
+idempotency mechanism or an application-owned effect record.
+
+## Does Ablo run long workflows?
+
+No. Temporal, Inngest, queues, and application workers still own scheduling,
+retries, and durable workflow progress. Ablo coordinates the shared state those
+executions read and change.
+
+## Do I need to understand fencing first?
+
+No. Start from the public behavior: a claim expires, another participant can
+take over, and an obsolete owner cannot use an old claim to commit through Ablo.
+The implementation mechanism is documented for operators and advanced
+integrations, not required for basic SDK use.

package/docs/guarantees.md

@@ -97,8 +97,9 @@ claim queues fairly behind the holder).
 By default, a held claim rejects writes from other participants to the claimed
 target. Contenders that call `claim` wait their turn; ordinary reads remain
 open. While you hold a claim, the matching
-`ablo.<model>.update({ id, ... })` is rejected with `AbloStaleContextError` if
-the row changed underneath you after your claim point.
+`ablo.<model>.update({ id, ..., claim })` proves ownership at write time and is
+rejected with `AbloStaleContextError` if the row changed underneath you after
+your claim point. Do not omit `claim` from a row-backed claimed write.
 
 ## Agent Runs
 

package/docs/idempotency.md

@@ -2,6 +2,9 @@
 
 > Make a retried write safe: the same key never applies the same change twice.
 
+This page owns idempotency for updates and retries, including changed intent
+and the `idempotency_conflict` failure code.
+
 An agent retries. A socket drops mid-commit, a worker restarts, a queue redelivers — and the write
 you already sent arrives again. An idempotency key is how Ablo tells a retry from a new intention.
 

package/docs/implement.md

@@ -0,0 +1,61 @@
+# Choose the Ablo operation
+
+> Find one implementation route from the work you are doing, copy its smallest recipe, and open guarantee details only when you need recovery behavior.
+
+Do not read the documentation front to back. Start with the operation your
+application already has, then use one row below.
+
+| What you are implementing | Start here | Add only when |
+|---|---|---|
+| Get one row by id or list rows with the installed client | [Basic usage](./basic-usage.md) | Use `read`, not `get`, only when a later Ablo write depends on that exact row. |
+| Configure a stateless worker's identity, permissions, or lifecycle | [Agents](./agents.md) | Keep the worker on HTTP; live human interfaces use React. |
+| Wrap an existing API, service, Postgres transaction, filesystem write, or Git merge | [Coordinate existing work](./coordinate-existing-work.md) | Keep the final write in its existing owner. |
+| Expose an existing named operation through GraphQL.js | [GraphQL.js](./approaches/graphql/graphql-js.md) | Keep the resolver dependent on that operation, not directly on Ablo. |
+| Hold an Ablo model row while slow work runs, then write it through Ablo | [Coordination](./coordination.md) | Pass the returned claim handle to the write. |
+| Reject a write when an earlier decision input changed | [Concurrency convention](./concurrency-convention.md) | Pass the exact object returned by `read` through `reads`. |
+| Apply several Ablo writes all-or-none | [Atomic commits](./api.md#atomic-commits) | Put every operation and every captured premise in one `commits.create`. |
+| Make a retried Ablo write safe | [Idempotency](./idempotency.md) | Derive one key from the business event and reuse it only for the identical request. |
+| Send email, charge money, call a provider, or write a file | Keep that effect in the application | Use the provider's key or an application outbox; an Ablo key covers only the Ablo mutation. |
+| Add a live human interface | [React](./react.md) | Humans use the WebSocket/live plane; stateless workers stay on HTTP. |
+
+## The four choices agents most often confuse
+
+```ts
+// Observe one current row. No later stale check.
+const task = await ablo.tasks.get({ id });
+
+// Declare a premise for one later Ablo write.
+const premise = await ablo.tasks.read({ id });
+if (!premise) throw new Error('task not found');
+await ablo.tasks.update({ id, data, reads: [premise] });
+
+// Hold an Ablo row across slow work. The final write goes through Ablo.
+await using claim = await ablo.tasks.claim({ id });
+await ablo.tasks.update({ id, data, claim });
+
+// Coordinate row-free work whose final write stays in the application.
+await using lease = await ablo.taskRuns.claim(id, {
+  contention: { mode: 'skip' },
+});
+if (lease) await existingTaskService.complete(id);
+```
+
+Use only one of those shapes unless the operation genuinely has both a claimed
+target and separate captured premises. Claims answer who may work; `reads`
+answer whether evidence is still current; `commits.create` answers whether
+several Ablo writes land together; the existing database transaction still
+owns atomicity for application-owned writes.
+
+## Before writing code
+
+Answer these five questions:
+
+1. Which existing operation am I preserving?
+2. Does the final write belong to Ablo or to the application?
+3. Is the coordination identity a model row or only a stable business id?
+4. Which exact rows influenced the decision?
+5. Which writes must land together?
+
+If an answer is unknown, preserve the existing operation and database boundary.
+Do not introduce claims, captured reads, or atomic commits merely because they
+exist.

package/docs/implementation-index.md

@@ -0,0 +1,20 @@
+# Ablo implementation index
+
+> Route an implementation task to the smallest relevant Ablo guide before reading details.
+
+Start with [Introduction](./index.md), then [Choose the Ablo operation](./implement.md). Its one routing table
+separates ordinary reads, existing application writes, claims, captured reads,
+atomic commits, retries, GraphQL, and external effects. Do not scan every page.
+
+| Your task | Read first |
+|---|---|
+| Choose among nearby SDK and ownership patterns | [Choose the Ablo operation](./implement.md) |
+| Add Ablo to existing work without replacing its API, transaction, filesystem write, or Git merge | [Coordinate existing work](./coordinate-existing-work.md) |
+| Install Ablo and create a typed client | [Installation](./installation.md) |
+| Read, write, and coordinate shared state | [Basic usage](./basic-usage.md) |
+| Choose between a plain read, guarded read, claim, or atomic commit | [Concurrency convention](./concurrency-convention.md) |
+| Look up an exact method, option, or error type | [API reference](./api.md) |
+| Connect Ablo to an existing Postgres database | [Integration guide](./integration-guide.md) |
+
+Follow links from that page only when its routing rule applies. Examples prove a
+specific integration; they are not required reading for a first implementation.