@abloatai/ablo 0.58.0 → 0.59.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Ablo lets AI agents and humans safely edit the same typed data without clobbering each other. When two of them touch the same row, a "claim" makes one wait for the other instead of overwriting it. This file shows a coding assistant the one safe pattern: read a row, claim it, then write.
+Ablo lets AI agents and humans safely edit the same typed data without clobbering each other. When two of them touch the same row, a "claim" makes one wait for the other instead of overwriting it. For an existing application, first preserve its named operation and persistence boundary; use the schema-backed row pattern below only when that route owns the write.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them and re-reads the fresh row before handing it to you — so two writers serialize instead of clobbering.
 
@@ -8,7 +8,7 @@ Claims don't lock. If another writer holds the row, `claim` waits for them and r
 
 Before choosing among identifier claims, row claims, captured reads, atomic
 commits, existing database writes, and Ablo-routed writes, use the
-[Agent Integration Decision Guide](./docs/agent-integration-decision-guide.md).
+[coordinate existing work guide](./docs/coordinate-existing-work.md).
 It routes existing applications to the smallest relevant example and names the
 test layer that proves each guarantee.
 
@@ -44,7 +44,7 @@ Every model verb takes ONE options object. The common loop:
 1. **Get or read** the row — `get({ id })` observes; `read({ id })` declares that a later mutation depends on this exact version. `list({ where })` is observational. In React render, use `local.get(id)`.
 2. **See who's active** (optional) — `ablo.<model>.claim.state({ id })` (synchronous; never blocks).
 3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, description?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
-4. **Write** — pass `reads: [row]` when the decision used a row returned by `read`, or write through the held claim. If the declared read moved, the mutation does not land.
+4. **Write** — pass `reads: [row]` when the decision used a row returned by `read`, or pass `claim` when writing through a held claim. If the declared read moved or the claim was lost, the mutation does not land.
 
 Keep coding assistants on this schema-backed path.
 
@@ -80,6 +80,7 @@ const claimed = claim.data;
 await ablo.weatherReports.update({
   id: claimed.id,
   data: { status: 'ready', forecast: await getForecast(claimed.location) },
+  claim,
 });
 ```
 

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## 0.59.1
+
+### Plans recognize completed database migrations
+
+`ablo plan` now treats a connected PostgreSQL column as evidence that required
+field migration work is complete when the mapped column exists, has the expected
+type, and already enforces `NOT NULL`. The plan reports that verified work once
+instead of demanding a synthetic backfill merely because the active Ablo
+artifact predates the database migration.
+
+The same reconciliation now recognizes a risky field-type correction as already
+completed when PostgreSQL has the candidate type, so activation does not demand
+`--force` merely because the active artifact still describes the old type. That
+evidence remains a forward-only contract boundary: reactivating the old artifact
+would disagree with the migrated database. Enum narrowing is not inferred from
+a `TEXT` column because the observed shape does not prove existing values satisfy
+the new constraint.
+
+Removing a model from the served schema also no longer implies that Ablo will
+drop its table when the connected database is application-owned and the table is
+still present. The plan reports a compatibility warning, retains the physical
+table, and allows the reviewed metadata activation without `--force`. Ablo-owned
+tables, missing application tables, and unobserved database states remain
+destructive errors.
+
+Missing, nullable, incompatible, contradictory, and unobserved database states
+remain blocked. Duplicate physical findings shared by the candidate and active
+schemas are collapsed, while genuine three-state disagreements remain visible
+in both directions.
+
+### Batched writes preserve their exact-read evidence
+
+Reactive writes that carry captured rows through `reads` now retain those
+dependencies when several writes are sealed into one durable commit, including
+after an offline replay. A premise that became stale is therefore still rejected
+instead of being lost at the batch boundary.
+
+## 0.59.0
+
+### Schema changes now have one ordered deployment plan
+
+`ablo plan` compares the source schema, the active Ablo schema artifact, and the
+connected PostgreSQL shape without changing any of them. It produces one
+fingerprinted expand, dual-write, backfill, verify, switch, and contract
+sequence, with explicit owners, blockers, and a rollback target:
+
+```sh
+npx ablo plan
+npx ablo plan --json
+```
+
+`ablo check` is now the database-compatibility view of that same plan. `ablo
+push` and `ablo migrate` consume it instead of maintaining separate migration
+judgments, and `ablo rollback` plans or applies a reviewed reactivation of an
+earlier schema artifact. The shared deployment contracts are available through
+`@abloatai/ablo/schema` and `@abloatai/transaction/schema`.
+
+Planning must observe all three states. `ablo plan`, `ablo check`, and `ablo
+migrate` therefore require `ABLO_API_KEY` plus
+`DATABASE_ADMIN_URL`/`DATABASE_URL`; a migration dry run is no longer a
+source-only operation. `ablo push` now refuses a blocked plan and can accept an
+explicit lifecycle manifest with `--manifest <path>`.
+
+Runtime schema-drift warnings now name the affected fields and distinguish
+client-only fields, active-only fields, and changes to type or optionality.
+
+### Declared timestamps no longer recurse during local edits
+
+Schemas can declare `createdAt` and `updatedAt` for typed reads and ordering
+without turning Ablo's automatic timestamp bookkeeping into another model
+edit. Updating an observable field now advances `updatedAt` once, keeps the
+timestamp observable, and excludes system-managed timestamps from the
+user-authored change payload.
+
+### The public client configuration boundary is explicit
+
+The supported `Ablo({ ... })` options are now machine-checked against the
+published reference. The internal `onCommitReceipt` transport callback is no
+longer accepted by the public factory type.
+
+### Connection capacity is selectable from the public pricing model
+
+The pricing API can now select the first tier that accommodates a requested
+connection count. The published Pro allowance increases from 1,000 to 5,000
+concurrent connections.
+
+### CLI telemetry can reach authenticated ingestion
+
+When an Ablo runtime key is available, the CLI uses it only in memory to
+authenticate product-analytics delivery. The key is not written to the local
+telemetry state, and existing telemetry opt-outs continue to apply.
+
+### Version-matched integration guidance is easier to enter
+
+The documentation bundled with `@abloatai/ablo` now starts from installation,
+the operation being coordinated, and whether an existing write boundary must
+be preserved. New focused pages cover basic usage, implementation choices,
+existing-operation coordination, every client option, security,
+instrumentation, comparisons, common questions, and GraphQL.js. `npx ablo
+docs` continues to read this package-local documentation, so the guidance
+matches the installed version.
+
+A new stale-context agent-turn example shows the complete long-running policy:
+abort cancellable work when an exact read moves, rebuild context for a bounded
+retry, retain the authoritative write guard, and reconcile rather than blindly
+replay an irreversible external side effect.
+
 ## 0.58.0
 
 ### Reads now distinguish observation from decision input

package/README.md

@@ -3,12 +3,12 @@
 </p>
 
 <p align="center">
-  <strong>Collaboration infrastructure for AI agents.</strong>
+  <strong>Coordination infrastructure for agents, applications, services, and people working on shared state.</strong>
 </p>
 
 <p align="center">
   <a href="https://docs.abloatai.com">Docs</a> &nbsp;|&nbsp;
-  <a href="https://docs.abloatai.com/quickstart">Quickstart</a> &nbsp;|&nbsp;
+  <a href="https://docs.abloatai.com/installation">Installation</a> &nbsp;|&nbsp;
   <a href="https://docs.abloatai.com/api">API</a> &nbsp;|&nbsp;
   <a href="https://github.com/Abloatai/ablo">GitHub</a>
 </p>
@@ -22,8 +22,8 @@
 
 ---
 
-Ablo is collaboration infrastructure for AI agents: one API for agents, apps,
-and services to claim, change, and confirm the same rows.
+Ablo is coordination infrastructure for agents, applications, services, and
+people working on shared state.
 
 Every write goes through it, so authority, idempotency, conflicts, ordering,
 and confirmation are enforced in one place. Your Postgres remains the source of

package/docs/agents.md

@@ -2,6 +2,25 @@
 
 > The stateless participant: wake on a trigger, read, claim, commit, go idle.
 
+## Stateless HTTP reads
+
+Use `get` to read one task row by id and `list` to find matching rows. Agents
+and other stateless workers use the HTTP client directly, without a
+synchronization step or a `.data` wrapper.
+
+```ts
+const task = await ablo.tasks.get({ id: taskId });
+if (!task) throw new Error('task not found');
+console.log(task.title);
+
+const matching = await ablo.tasks.list({ where: { title } });
+if (!matching[0]) throw new Error('task not found');
+console.log(matching[0].title);
+```
+
+These are observational reads. Use `read({ id })` only when a later Ablo write
+depends on that exact version and will pass it through `reads`.
+
 An agent is a **reactive** participant: it wakes on something happening, reads
 what it needs, writes a result, and goes idle. That's a request/response
 workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
@@ -16,7 +35,7 @@ other*.**
 <Note>
 Agents transact against your **pushed schema**, same as everyone — `ablo.records`
 exists because you defined a `record` model and ran `ablo push`. The key
-authenticates; the [schema](/quickstart) defines what you can call.
+authenticates; the [schema](/installation) defines what you can call.
 </Note>
 
 ## The agent client

package/docs/api.md

@@ -96,6 +96,49 @@ fallback removed — nothing to await, so they return a value.
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
+## Atomic commits
+
+Use one `ablo.commits.create` when several Ablo model writes must all land or
+none may land. Put every operation in `operations` and every exact row returned
+by `read` that influenced the batch in the top-level `reads` array.
+
+```ts
+import { AbloStaleContextError } from '@abloatai/ablo';
+
+const task = await ablo.tasks.read({ id: taskId });
+if (!task) throw new Error('task not found');
+
+try {
+  await ablo.commits.create({
+    operations: [
+      {
+        action: 'update', model: 'tasks',
+        id: task.id,
+        data: { status: 'done' },
+      },
+      {
+        action: 'create', model: 'tasks',
+        id: markerId,
+        data: { title: 'atomic marker', status: 'done' },
+      },
+    ],
+    reads: [task],
+  });
+} catch (error) {
+  if (error instanceof AbloStaleContextError && error.code === 'stale_context') {
+    console.log(error.code);
+  } else {
+    throw error;
+  }
+}
+```
+
+The server checks the premises and applies the operations in one transaction.
+If any premise is stale or any operation fails, no operation lands. Independent
+model calls are not an atomic batch. External effects and application-owned
+Postgres writes cannot join this commit; keep those in their existing
+transaction or outbox.
+
 ### Reading a whole collection
 
 Prefer a filtered `listAll` when the application truly needs one complete
@@ -252,13 +295,18 @@ const handle = await ablo.weatherReports.claim({
   description: 'editing',
   ttl: '2m',
 });
-await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await ablo.weatherReports.update({
+  id: handle.data.id,
+  data: { status: 'ready' },
+  claim: handle,
+});
 await handle.release();
 ```
 
-Writes go through the normal `ablo.<model>.update({ id, data })`. While you hold
-a claim on `id`, that `update` rejects with `AbloStaleContextError` if the row
-changed underneath you since you took the claim, so you re-read before retrying.
+Writes go through the normal model mutation and pass the held handle as `claim`.
+That explicit handle carries commit-time fencing. If the row changed underneath
+you since you took the claim, the update rejects with `AbloStaleContextError`,
+so you re-read before retrying.
 Call `handle.release()` (or `ablo.weatherReports.claim.release({ id })`) to release
 the claim when your work is done.
 
@@ -307,7 +355,9 @@ rendered as agent tools.
 
 ## Errors
 
-All SDK errors extend `AbloError` and expose a stable `type` string.
+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 | Meaning |
 |---|---|

package/docs/basic-usage.md

@@ -0,0 +1,84 @@
+# Basic Usage
+
+> Read one task row by id, list matching rows, create and update state, and coordinate work when needed.
+
+Assume the configured client from [Installation](./installation.md) is exported
+from `./ablo/client`.
+
+## Read rows
+
+```ts
+import { ablo } from './ablo/client';
+
+const task = await ablo.tasks.get({ id: taskId });
+if (!task) throw new Error('task not found');
+
+const open = await ablo.tasks.list({ where: { status: 'open' } });
+```
+
+`get` observes one current row. Use `read` instead only when a later Ablo write
+must be rejected if that exact premise changes.
+
+## Write rows
+
+```ts
+const created = await ablo.tasks.create({
+  data: { title: 'Review return', status: 'open' },
+});
+
+await ablo.tasks.update({
+  id: created.id,
+  data: { status: 'done' },
+});
+```
+
+Writes return after Ablo confirms the authoritative result. Your PostgreSQL
+constraints and schema remain in force.
+
+## Coordinate slow work
+
+When the target is an Ablo model row, claim it before the expensive step and
+pass the claim to the final write.
+
+```ts
+await using claim = await ablo.tasks.claim({ id: taskId });
+
+const result = await performExpensiveWork(claim.data);
+
+await ablo.tasks.update({
+  id: claim.data.id,
+  data: { title: result.title, status: 'done' },
+  claim,
+});
+```
+
+A contender follows the chosen wait, skip, or fail policy. Disposal releases
+the claim, and expiry lets another participant recover when the owner
+disappears.
+
+## Preserve an existing write
+
+The claimed target does not have to be an Ablo row. Claim a stable business id
+and keep the final transaction in the application that already owns it.
+
+```ts
+await using lease = await ablo.taskRuns.claim(taskId, {
+  contention: { mode: 'skip' },
+});
+if (!lease) return;
+
+const prepared = await performExpensiveWork(taskId);
+return existingTaskService.commitPrepared(taskId, prepared);
+```
+
+That transaction must still re-read, validate, and commit authoritatively. An
+Ablo claim does not join a transaction in another process.
+
+## Add stronger guarantees when required
+
+- [Concurrency Convention](./concurrency-convention.md): reject a write when an
+  earlier premise changed.
+- [Atomic commits](./api.md#atomic-commits): apply several Ablo writes together.
+- [Idempotency](./idempotency.md): make retrying the same Ablo mutation safe.
+- [Agents](./agents.md): configure a stateless HTTP worker.
+- [React](./react.md): add live state and presence for a human interface.

package/docs/client-behavior.md

@@ -28,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 model `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but ordinary calls are HTTP round trips with no socket. Stateful-only model methods (`local`, model `onChange`, and `join`) are compile errors. A listener added through `context().onChange` holds one HTTP response open only until its context changes or its last listener stops. |
-| `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
@@ -169,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

@@ -2,6 +2,12 @@
 
 > A write either declares what it read or deliberately does not.
 
+Use a captured read when a write must be rejected because an earlier premise
+changed.
+
+Read the authoritative premise, carry
+that exact evidence into the write, and handle the documented failure code.
+
 Ablo does not put a configurable stale mode between your code and a
 commit. The public choice is visible at the call site:
 
@@ -38,6 +44,22 @@ 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
@@ -71,6 +93,11 @@ 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.
 
+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.
+
 Claims and stale reads answer different questions:
 
 | Mechanism | Lifetime | Question |

package/docs/context.md

@@ -127,6 +127,26 @@ 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
 
 Provider results pass through without an adapter or provider dependency. The

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.