@abloatai/ablo 0.47.0 → 0.49.0

package/docs/migration.md

@@ -1,461 +1,64 @@
-# Version History & Migration Guide
+# Upgrade Guide
 
-> Every breaking change and the edit it requires, newest first.
+> A safe workflow for upgrading the pre-1.0 SDK.
 
-The breaking-changes-first companion to the [Changelog](../CHANGELOG.md). The
-changelog tells the story of each release; this page tells you exactly what to
-change when you upgrade.
+Ablo is pre-1.0, so a minor release may contain a breaking API change. Patch
+releases remain compatible within the same minor line.
 
-> Ablo is pre-1.0, so minor versions (`0.x.0`) may carry breaking changes. Patch
-> versions (`0.x.y`) never do. Pin a minor and read this page before bumping it.
+## Upgrade safely
 
-## Breaking changes at a glance
+1. Pin the version you run instead of depending on a floating range.
+2. Read the changelog entries between your installed and target versions.
+3. Use the documentation bundled with the target package while changing code.
+4. Run type-checks and tests before updating a production branch.
+5. Push schema changes deliberately after reviewing the generated diff.
 
-| Version | What changed | What to do |
-|---|---|---|
-| **Next** | New keys no longer encode `live`/`test`; branch binding is authoritative | Accept the new `sk_…`/`rk_…`/`pk_…`/`ek_…` spellings. Do not route or authorize from a key prefix. Old `_live_`/`_test_` keys continue to authenticate; rotate them to mint the current form |
-| **0.36.0** | `ttlSeconds` deprecated on the join surfaces in favour of `ttl` | `useJoin({ scope, ttlSeconds: '5m' })` → `useJoin({ scope, ttl: '5m' })`; same for `ParticipantJoinOptions`. Both spellings work until 0.37.0 |
-| **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.get(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
-| **0.35.0** | `causedByTaskId` write option + seven `turn_*` error codes removed | Delete the `causedByTaskId` argument from writes; a branch on `turn_validation_failed` was unreachable and can go with it |
-| **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
-| **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useJoin`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useJoin({ scope })` |
-| **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useJoin` |
-| **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Historical: update code that branches on the environment (`'test'`→`'sandbox'`, `'live'`→`'production'`). That release retained `sk_test_`/`sk_live_`; current releases mint mode-free, branch-bound keys |
-| **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
-| **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
-| **0.9.0** | One options object per verb | `update(id, data, opts)` → `update({ id, data, ...opts })` |
-| **0.9.0** | `claim` returns a disposable handle | `await using claim = await ablo.x.claim({ id })` |
-| **0.8.0** | Flat coordination methods removed | `ablo.x.claimState(id)` → `ablo.x.claim.state({ id })` |
-| **0.7.0** | Legacy React hooks removed | `useQuery`/`useOne`/`useMutate`/`useReader` → `useAblo()` + `ablo.<model>.*` |
-| **0.6.0** | `subscribe` → `onChange`; `Resource` → `Model` rename | Rename listeners and `ablo.resource()` → `ablo.model()` |
-| **0.5.0** | Intent-handle method renames | `acquire`→`claim`, `acquireOrAwait`→`claimOrWait`, … |
-| **0.3.0** | `<SyncProvider>` / `createAbloContext()` / `withSync` removed | Use the umbrella `<AbloProvider>` |
-
----
-
-## Next: key spelling follows capability, branch binding follows authority
-
-New runtime credentials have one prefix per capability class:
-
-```diff
-- sk_live_… / sk_test_…
-+ sk_…
-```
-
-The same applies to `rk_`, `pk_`, and `ek_`. This does **not** merge branch
-data or weaken production safety. Every key row is still immutably bound to one
-project and one branch, and the server-confirmed `branchRoot` flag distinguishes
-the protected production root from a development child.
-
-Remove code that chooses an endpoint, environment, or confirmation policy by
-matching `_live_` or `_test_`. Use the resolved identity (`ablo whoami` in the
-CLI) instead. Existing suffixed credentials remain valid compatibility inputs,
-so rollout does not require an immediate rotation.
-
----
-
-## 0.36.0: one lease is spelled `ttl`
-
-```diff
-- useJoin({ scope: { documents: [id] }, ttlSeconds: '5m' })
-+ useJoin({ scope: { documents: [id] }, ttl: '5m' })
-```
-
-`ablo.<model>.join(ids, { ttl })` has always said `ttl`, and so does every other
-lease in the SDK: `claim`'s `ttl`, `ClaimLeaseOptions.ttl`. The lower-level join
-surfaces said `ttlSeconds` while accepting exactly the same values, including
-duration strings, so a `ttl: '5m'` handed down from the model verb arrived as
-`ttlSeconds: '5m'`, a field asserting a unit its value did not carry.
-
-Both spellings work until 0.37.0, and `ttl` wins if you pass both. The wire is
-unchanged: it has always carried seconds and still does.
-
----
-
-## 0.35.0: the synchronous reads move under `local`
-
-```diff
-- const task  = ablo.tasks.get(id);
-- const open  = ablo.tasks.getAll({ where: { status: 'open' } });
-- const count = ablo.tasks.getCount({ where: { status: 'open' } });
-+ const task  = ablo.tasks.local.get(id);
-+ const open  = ablo.tasks.local.list({ where: { status: 'open' } });
-+ const count = ablo.tasks.local.count({ where: { status: 'open' } });
-```
-
-Options, return types, and reactivity inside `useAblo` selectors are unchanged.
-Every verb now matches its asynchronous sibling, and `local` narrows the read to
-what has already synced — which is what lets it return a value rather than a
-promise.
-
-`getAll` and `getCount` are distinctive enough to rename by search. `get` is not:
-in most codebases it is outnumbered many times over by `Map.get` and
-`headers.get`, and no search separates them. Upgrade the package first and let
-the compiler name the sites — each one is a type error at exactly the call that
-has to move.
-
-## 0.35.0: `causedByTaskId` and the `turn_*` error codes removed
-
-0.9.2 retired the `turn` primitive but left one field standing: `causedByTaskId`
-on the write options bag. It was never usable. The server validated it against a
-task record that nothing in the system has ever created, so supplying it had the
-whole batch rejected with `turn_validation_failed`, while leaving it null passed
-straight through. The safe way to use the option was to not use it.
-
-**Removed:** `MutationOptions.causedByTaskId`, the seven `turn_*` error codes
-(`turn_validation_failed`, `turn_open_failed`, `turn_close_failed`,
-`turn_not_found`, `turn_foreign_agent`, `parent_turn_not_found`,
-`parent_turn_foreign_agent`), and the stored row's provenance slice
-(`deltaProvenanceSchema` and the `DeltaProvenance` type). `syncDeltaRowSchema` is
-now the core and attribution slices composed.
-
-```diff
-- await ablo.documents.update({ id, data, causedByTaskId: turnId });
-+ await ablo.documents.update({ id, data });
-```
-
-Attribution is unaffected. A delta still records the actor, the `onBehalfOf`
-principal behind a delegated write, the capability that authorized it, and the
-claim it was made under — which is what answers "who did this, and by what
-right." On the wire the field was optional and nullable, so a client that still
-sends it is accepted and ignored.
-
-The `caused_by_task_id` column stays, for the reason 0.9.2 gave when it kept it:
-the audit hash-chain signs its value into every row. Dropping it is a versioned
-migration of its own.
-
----
-
-## 0.34.0: presence verb renamed `watch` → `join`
-
-The model-level presence verb read like a data subscription but delivered
-presence — who else is on a row and what they hold — so it now says what it
-does. `ablo.<model>.join(ids, { ttl })` opens the participant handle
-(`.peers`, `.claims`, `await using` disposal); the returned `status` was
-already `'joined'`, and the layer beneath always called itself `join`, so the
-verb now matches. `onChange` remains the way to hear row *values* change, and
-`track` remains the durable premise for actors.
-
-```ts
-// before
-await using room = await ablo.documents.watch(documentIds, { ttl: '5m' });
-// after
-await using room = await ablo.documents.join(documentIds, { ttl: '5m' });
-```
-
-The React hook follows: `useWatch({ scope })` → `useJoin({ scope })`. There is
-no compatibility alias — rename the call sites and the `WatchOptions` /
-`UseWatchOptions` / `UseWatchReturn` type imports.
-
----
-
-## 0.28.0: dead React multiplayer placeholders removed
-
-Four React exports looked usable but had no live implementation:
-
-- `usePresence` returned no provider-backed presence value. Use `usePeers` for
-  read-only presence or `useJoin` to join a scoped participant.
-- `useClaim` depended on a callback the provider never supplied and always
-  threw. Use `ablo.<model>.claim({ id, ... })` for row claims or
-  `useJoin({ scope, claim: true })` for a scoped participant claim.
-- `SyncGroupProvider` and `useSyncGroup` had no repository consumers. Pass the
-  scope directly to `useJoin({ scope })`.
-
-There is no compatibility alias: the replacement APIs were already the only
-working paths.
-
-## 0.11.0: `intent` → `claim` rename completed
-
-> **Historical note:** this section documents the 0.11.0 transition.
-> `useClaim` was subsequently removed in 0.28.0 because its provider callback
-> was never wired. Do not migrate new code to it; use the replacements above.
-
-The coordination primitive has been `claim` since 0.9.2, but a few `intent`-named
-surfaces lingered. 0.11.0 finishes the rename. There are three edits, all
-mechanical:
-
-**1. React hook.** `useIntent` is now `useClaim` (same signature):
-
-```diff
-- import { useIntent } from '@abloatai/ablo/react';
-- const claimEditLayer = useIntent('editLayer');
-+ import { useClaim } from '@abloatai/ablo/react';
-+ const claimEditLayer = useClaim('editLayer');
+```bash
+npm install @abloatai/ablo@0.48
+npx ablo docs
+npx ablo docs api
+npx ablo check
 ```
 
-**2. Type registration.** The `Register` interface key is `Claims`, not `Intents`:
+`npx ablo docs` is version-matched to the installed package. Prefer it during an
+upgrade: the hosted website documents the newest release, which may expose a
+method your pinned package does not yet contain.
 
-```diff
-  declare module '@abloatai/ablo' {
-    interface Register {
--     Intents: { editLayer: { slideId: string; layerId: string } };
-+     Claims: { editLayer: { slideId: string; layerId: string } };
-    }
-  }
-```
-
-**3. Type namespace.** The `Ablo.Intent.*` helper types moved to `Ablo.Claim.*`.
-If you referenced them directly, rename the namespace; the shapes are unchanged.
-
-> **Coordinated deploy required.** The on-the-wire frames moved from `intent_*`
-> to `claim_*`. A `claim_*`-aware client cannot coordinate with an `intent_*`
-> server (and vice-versa), so ship the client and server together. If you run a
-> self-managed sync server, deploy it first.
-
-Two non-breaking improvements ride along: claim-rejection errors now surface the
-contending holders (`AbloClaimedError.claims` and a policy reason folded into the
-message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
-on presence and claim state.
-
-## 0.10.0: environment enum `sandbox` / `production`; stateless HTTP transport
-
-> Historical migration note: current development uses immutable branches, not a
-> shared sandbox selector. The enum and compatibility fields below remain
-> relevant to integrations written against 0.10, but new applications let the
-> branch-bound credential select the plane.
-
-### Environment enum rename (the only breaking change)
+## What to review
 
-In 0.10 the canonical environment values became **`production`** and
-**`sandbox`** (from `live` and `test`). At that release this was only a
-vocabulary change at the type/API layer: on-the-wire keys still used
-`sk_test_…` / `sk_live_…`. Current releases accept those legacy spellings but
-mint mode-free `sk_…` keys whose persisted branch binding is authoritative.
+Pay particular attention when a release changes:
 
-You only need to act if your code branches on the environment value — most
-commonly a Data Source handler keyed on `mode`. The mapping is exactly
-`test → sandbox`, `live → production`:
+- model method signatures or return values;
+- claim acquisition, contention, or release behavior;
+- credential scope or session minting;
+- schema serialization and push validation;
+- database connection or Data Source setup;
+- error codes your application handles explicitly.
 
-```diff
-  const handler = createSourceHandler({
-    read: async ({ mode }) => {
--     const db = mode === 'test' ? testDb : liveDb;
-+     const db = mode === 'sandbox' ? sandboxDb : productionDb;
-      // …
-    },
-  });
-```
-
-`commit` now also forwards `projectId`, `accountScope`, and `environment` to
-source resolvers, so per-project and per-environment traffic can be routed to
-distinct stores.
-
-> **CLI note:** current login stores one mode-free `mk_` project management
-> credential. Legacy runtime key slots remain readable during the cutover, but
-> re-run `ablo login` before using branch/project commands so the CLI can store
-> the new credential.
-
-### New (non-breaking): `transport: 'http'`
-
-`Ablo({ transport: 'http' })` returns a stateless `AbloHttpClient` for
-server-side actors (agents, workers, serverless): the same `ablo.<model>` surface
-and `claim` coordination, but each call is one HTTP round-trip with identity on
-the Bearer credential — no websocket, no local synced pool. The return type
-narrows, so stateful-only APIs (the `local` reads, `onChange`) become compile
-errors instead of latent runtime gaps. Existing code keeps the default
-`'websocket'` transport, unchanged.
-
-```ts
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
-await ablo.tasks.update({ id, data: { status: 'done' } });
-```
+The release changelog names required edits next to the feature that changed.
+Avoid branching on credential prefixes or undocumented internals; use exported
+types and server-confirmed identity instead.
 
-> **Minting still needs the stateful client.** `sessions.create(...)` is not on
-> the `transport: 'http'` surface. Keep a default-transport `server` client for
-> minting short-lived credentials (see the 0.9.2 example below), and use the
-> http client for the per-request reads and writes.
-
----
-
-## 0.9.2: `turn` / agent-`tasks` removed; `intents` deprecated
-
-The SDK's coordination surface is now exactly two things: `ablo.<model>` writes
-and `claim`. The parallel `turn` / agent-`tasks` mechanism was redundant —
-`claim` already serializes writers **and** carries the causal link (its `intent`
-id rides on every guarded write), and the server stamps `actor` / `onBehalfOf` /
-`capabilityId` onto every delta from the auth context.
-
-**Removed:** `engine.beginTurn()`, the `Turn` handle and `Ablo.Turn` type,
-`AbloApi.beginTurn`, `CommitCreateOptions.causedByTaskId`, the `agent().run()`
-helper, and the agent/task type family (`Agent`, `AgentOptions`,
-`AgentRunResult`, `Task`, `TaskResource`, …).
-
-> **Note:** `ablo.tasks` is — and always was — the schema `tasks` **model**
-> proxy. Only the agent-work *resource* of the same name was removed. If you have
-> a `tasks` model in your schema, it is unaffected.
-
-```diff
-- const turn = await engine.beginTurn();
-- await Ablo({ apiKey }).agent(agentId, opts).run(prompt, handler);
-+ // Mint a scoped credential from a stateful (default-transport) server client —
-+ // sessions.create lives on the stateful client, not on transport: 'http'.
-+ const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
-+ const { token } = await server.sessions.create({ agent: { id: agentId } });
-+ const agent = Ablo({ schema, apiKey: token });
-+ await using claim = await agent.tasks.claim({ id });
-+ await agent.tasks.update({ id, data: { status: 'done' } });
-```
-
-Per-run token/cost now lives in Langfuse, not an `agent_tasks` table. The only
-capability the client loses is the audit pane's "show everything this exact
-prompt produced" filter (it keyed off `caused_by_task_id`); new writes leave that
-column `null`. The server-side `agent_tasks` table, the `caused_by_task_id` delta
-column, and the `agent_actions_log` hash-chain are intentionally **kept but
-dormant** — they are load-bearing for the tamper-evident audit chain. The dead
-`/v1/tasks` and `/api/agent/turn` route handlers were removed.
-
-### `intents` → `claim`
-
-```diff
-- const lock = ablo.intents.editing(target);
-+ await using claim = await ablo.documents.claim({ id });
-```
-
-`ablo.intents` still exists but is marked `@internal`. Use `ablo.<model>.claim`
-everywhere you coordinate concurrent work.
-
----
-
-## 0.9.0: one options object per verb; disposable `claim`
-
-Every model verb takes a single options object, so the id, the data, and every
-modifier are named siblings. Reactive local reads stay on the synchronous
-`get(id)`.
-
-```diff
-- await ablo.tasks.update(id, { status: 'done' }, { wait: 'confirmed' })
-+ await ablo.tasks.update({ id, data: { status: 'done' } })
-
-- await ablo.tasks.retrieve(id)
-+ await ablo.tasks.get({ id })
-
-- useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
-+ useAblo((ablo) => ablo.tasks.local.get(id)) ?? serverTask
-```
-
-`claim` now returns a disposable handle instead of taking a callback. The handle
-exposes the fresh row on `.data` and releases on scope exit.
-
-```diff
-- await ablo.tasks.claim(id, async (task) => {
--   await ablo.tasks.update(task.id, { status: 'in_review' })
-- })
-+ await using claim = await ablo.tasks.claim({ id })
-+ const task = claim.data
-+ await ablo.tasks.update({ id: task.id, data: { status: 'in_review' } })
-```
-
-`claim.state`, `claim.queue`, `claim.release`, and `claim.reorder` also take the
-options object.
-
----
-
-## 0.8.0: callable `claim` namespace
-
-The flat coordination methods are gone; everything lives under `claim`.
-
-```diff
-- await ablo.task.claimState(id)
-- await ablo.task.release(id)
-+ await ablo.task.claim.state(id)
-+ await ablo.task.claim.release(id)
-```
-
----
-
-## 0.7.0: legacy React hooks removed
-
-The query/mutation hooks were replaced by the single `useAblo()` accessor over
-typed model methods.
-
-```diff
-- const { data } = useQuery('task', { where: { done: false } })
-+ const ablo = useAblo()
-+ const tasks = ablo.task.list({ where: { done: false } })
-```
-
-Removed: `useQuery`, `useOne`, `useMutate`, `useReader`. The `MutateActions`,
-`ReaderActions`, and `ReaderFindOptions` types are still exported for callers
-that reference them. This release also replaced the `{ error, reason }` error
-shape with the canonical `{ type, code, message, doc_url, request_id }` envelope.
-
-> **Note:** This — not 0.9.x — is the release where `useAblo()` became the one
-> React read path. If you are coming from a 0.6.x or earlier app, this is your
-> biggest hook migration.
-
----
-
-## 0.6.0: `onChange` and the Resource → Model rename
-
-```diff
-- ablo.tasks.subscribe(cb)
-+ ablo.tasks.onChange(cb)
-
-- ablo.resource('tasks')
-+ ablo.model('tasks')
-```
-
-Also renamed: `Ablo.Resource.*` → `Ablo.Model.*`, `ModelTarget.resource` →
-`ModelTarget.model`, and error code `resource_not_found` → `model_not_found`.
-(`subscribe` is reserved for an upcoming scope-grant verb.)
-
----
-
-## 0.5.0: intent-handle method renames
-
-On the model intent handle (`ablo.<model>.intent(id)`):
-
-```diff
-- handle.acquire()         + handle.claim()
-- handle.acquireOrAwait()  + handle.claimOrWait()
-- handle.settled()         + handle.whenFree()
-- handle.release()         + handle.finish()
-- handle.revoke()          + handle.cancel()
-```
-
-The lower-level `IntentHandle` / `IntentLeaseHandle` (`ablo.intents.*`) were
-unchanged at this release. (They were later folded under `claim` in 0.9.2.)
-
----
-
-## 0.3.0: umbrella `<AbloProvider>`
-
-One provider component now owns the full React lifecycle. `<SyncProvider>`,
-`createAbloContext()`, and `withSync` were removed.
-
-```diff
-- const { AbloProvider, useAblo } = createAbloContext<typeof schema>();
-- <SyncProvider store={sync._store} organizationId={orgId}>
--   <AbloProvider ablo={ablo}>{children}</AbloProvider>
-- </SyncProvider>
-+ const ablo = Ablo({ schema, apiKey });
-+ <AbloProvider client={ablo}>
-+   {children}
-+ </AbloProvider>
-```
-
-`useSyncStatus()` changed from six booleans to a tagged union:
-
-```diff
-- const { isReady } = useSyncStatus()
-+ const isReady = useSyncStatus().name === 'connected'
-```
+## Schema and database safety
 
-Import `observer` from `mobx-react-lite` directly if you used `withSync`.
+An SDK upgrade and a database migration are separate operations.
 
----
+- `ablo push` updates Ablo's typed schema contract. It does not run application
+  DDL or drop your tables.
+- `ablo check` compares the contract with the connected database without
+  changing it.
+- Your ORM or migration tool remains responsible for tables, columns,
+  constraints, and application data migrations.
 
-## The `intent` → `claim` evolution
+When both need to change, deploy the database migration in a backwards-compatible
+form first, push the compatible Ablo schema, then remove old application paths.
 
-Coordination has converged on one verb over several releases. If you are reading
-old code or old docs, this is the through-line:
+## If an upgrade fails
 
-| Release | State of coordination |
-|---|---|
-| 0.4.0 | `ablo.<model>.intent(id)` introduced: per-entity intent handle |
-| 0.5.0 | Intent-handle methods renamed to claim vocabulary (`acquire`→`claim`, …) |
-| 0.8.0 | Callable `claim` namespace (`claim(id)`, `claim.state`, `claim.queue`, …) |
-| 0.9.0 | `claim` returns an `await using` disposable handle |
-| 0.9.2 | `intents` deprecated and made `@internal`: **`claim` is the one coordination API** |
+Use the typed error code and request ID rather than matching message text. The
+[Errors](./errors.md) reference gives the recovery step for each public error.
+If a failure only occurs on the new minor version, keep the previous pinned
+version in production while reproducing it against an isolated branch.
 
-For the full chronological history, see the [Changelog](../CHANGELOG.md).
+See the release changelog for version-specific changes and
+[Deployment](./deployment.md) for the production rollout sequence.

package/docs/operating-on-your-database.md

@@ -1,14 +1,12 @@
 # Operating on Your Database
 
-> Which actions run freely, which to verify first, and which belong to a human.
+> Which actions are read-only, which writes need a guard, and which changes belong to a human.
 
 Ablo sits over your database as a coordination layer, not an owner. It reads
-your Postgres replication stream and routes each write through a claim-checked
-commit that lands in your own tables. It never runs DDL, never migrates, never
-drops. That single boundary is why almost everything you do through Ablo is
-either read-only or reversible — and why the few actions that aren't are easy to
-name. This page is how to tell them apart, so you can work on a real database
-without guessing which move is the dangerous one.
+your Postgres replication stream and routes model writes into your own tables.
+The hosted service does not run application DDL, migrations, or drops. That
+boundary keeps model operations attributable while your migration tool remains
+responsible for the database shape.
 
 The habit that makes it easy is to look before you act. One command shows you
 the real shape of your database measured against your schema, and changes
@@ -32,26 +30,27 @@ radius of anything you do through the model API:
   action, run with your admin credential — never Ablo's.
 - It **never owns your rows.** Canonical data stays in your tables; Ablo hosts
   only the transaction log and the coordination state.
-- Every model write is **claim-checked and recorded.** A write based on a row
-  that moved under you is rejected rather than applied, and the prior value is
-  retained in the log, so a confirmed change is attributable and
-  reconstructable.
+- Every model write is **checked against active claims and recorded.** A plain
+  write is last-write-wins when no claim applies. A functional update, held
+  claim, or explicit `readAt` guard protects a write that depends on an earlier
+  value.
 
-So a normal `ablo.<model>.update(...)` cannot silently corrupt your database:
-the worst case is a clean rejection and a re-read, not a lost row.
+Ablo prevents a non-holder from writing through another participant's claim by
+default. It does not infer that every plain update is a read-modify-write
+operation; use the guarded forms when lost-update protection matters.
 
 ## Three kinds of action
 
 Sort any action you're about to take into one of these, and the right move
 follows.
 
-**Run freely — read-only or reversible.**
+**Normal application operations.**
 Reads (`get`, `list`), `ablo check`, and `ablo pull` observe and
 never change anything. Previews — `--show-sql`, `--dry-run` — print the exact
 SQL a command would run without executing it. Model writes through
-`ablo.<model>.create` / `update` are claim-checked, optimistic, rolled back if
-the server rejects them, and recorded in the log with the prior value. All of
-these are safe to run on your own initiative.
+`ablo.<model>.create` / `update` are authorized, checked against active claims,
+optimistic locally, rolled back locally if the server rejects them, and
+recorded. Review their data effects as you would any application write.
 
 **Verify first — needs one look at the live database.**
 Routing an existing table's writes through a model requires the model to match
@@ -61,28 +60,23 @@ line in the report rather than a surprise at commit time. Decide the model shape
 from what `check` tells you, then proceed. Nothing here is risky — it just reads
 better after you've seen the ground truth.
 
-**Hand to a human — irreversible, outside the log's protection.**
+**Hand to a human — database administration.**
 Raw DDL on the live database — `ALTER TABLE … OWNER TO`, adding or dropping a
-column, changing a constraint — changes the database itself and is not covered
-by the reversible log, so it belongs to a person with their hand on it. So does
+column, changing a constraint — changes the database itself, so it belongs to a
+person with their hand on it. So does
 a `connect` cutover run with its confirmation skipped (`--yes`): the prompt
 exists because the step provisions real roles and reconciles publication on a
 live database, and on a shared or production database that confirmation is the
-human's to give. Removing a model from your schema belongs here too — for the
-reason below.
+human's to give. Removing a model from your pushed schema also deserves review
+because clients will lose that typed API surface.
 
 ## The one action that isn't what it looks like
 
-Deleting a model from `ablo/schema.ts` reads like a code cleanup, but it is a
-schema change. Your schema is a desired-state declaration: `ablo push` diffs it
-against the server's copy, and a model that has vanished from the schema can be
-read as a table that should no longer exist. "Nothing imports it" answers a
-code question. The question that governs safety is *does removing this drop a
-real table on the next push* — and that one is answered against the database,
-not the codebase. Before removing a model that maps a live table, confirm the
-table is gone or empty and that your push path is additive; otherwise keep the
-model until the data is dealt with. A `load: 'lazy'` mapping is often present
-precisely to hold a table in place, so treat its comment as load-bearing.
+Deleting a model from `ablo/schema.ts` removes it from the API contract the next
+time you push the schema. Existing clients can no longer access that model
+through Ablo. It does **not** drop the underlying table or its rows; database DDL
+remains your migration tool's responsibility. Review client usage first, then
+remove the model and push the schema as a normal application change.
 
 ## The verification loop
 
@@ -98,10 +92,9 @@ read-only checks:
 - Read the row and its claim state before you write — `get` / `list`, and
   `ablo.<model>.claim.state({ id })` for who is already working on it.
 
-The pattern underneath all of it is steady: reads and model writes flow freely
-because the boundary and the log make them safe, DDL and cutovers pause for a
-human because they change the database itself, and the space between the two is
-one `ablo check` away from certain.
+The pattern underneath all of it is steady: observe first, use guarded writes
+when a change depends on prior state, and review DDL and cutovers separately
+because they change the database itself.
 
 ## See also
 

package/examples/README.md

@@ -26,6 +26,28 @@ Then:
 - write with `ablo.weatherReports.update`
 - dispose the client when the worker finishes
 
+For read-reason-write work, pass the exact returned rows that informed the
+decision. Their watermarks stay opaque:
+
+```ts
+const task = await ablo.tasks.get({ id: taskId });
+const policy = await ablo.policies.get({ id: policyId });
+const result = await model({ task, policy });
+await ablo.tasks.update({
+  id: task.id,
+  data: result,
+  reads: [task, policy],
+});
+```
+
+This means: apply the update only if the rows used to produce it have not
+changed. Incidental reads do nothing, and cloned or fabricated rows are
+rejected locally.
+
+`agent-turn.ts` is the cheap read/write path. `expensive-agent-turn.ts` adds a
+heartbeating claim, post-grant model input, durable commit inspection, automatic
+release, and a released-claim fencing check.
+
 Import the same schema in every runtime. Use `commits.create` only when several
 typed row operations must land atomically; ordinary writes stay on
 `ablo.<model>.create/update/delete`.
@@ -39,6 +61,8 @@ root and a bare `quickstart.ts` won't be found.
 ```bash
 cd packages/ablo
 ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
+ABLO_API_KEY=sk_... TASK_ID=task_... npx tsx examples/agent-turn.ts
+ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
 ```
 
 ## Data Source (customer-owned database)