@abloatai/ablo 0.48.0 → 0.49.0

package/AGENTS.md

@@ -11,7 +11,7 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 - **Read the docs for THIS version:** `npx ablo docs` lists every page, `npx ablo docs <page>` prints one. They ship inside the installed package, so they describe the code in `node_modules` and work with no network. Read them instead of a docs URL — a website describes the newest release, so against a pinned version it will hand you a call your package doesn't have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0).
 - **Scaffold:** `npx ablo init --yes` — flag-driven, never prompts. Override defaults with `--framework <nextjs|vite|remix|vanilla>`, `--auth <apikey|…>`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`. (Plain `ablo init` needs a TTY and will **HANG** in an agent/CI run — always pass `--yes`.)
 - **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
-- **Connect your database — logical replication (the primary path):** `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect register` registers the source with Ablo in one step. Ablo **consumes your Postgres' logical-replication stream** — it never runs DDL on, writes to, owns, or migrates your database, and your application keeps the write path. Registration **is** the enable; there is no tier or flag to pick. (Ablo hosts only the transaction log + coordination, never your rows.)
+- **Connect your database — logical replication (the primary path):** `npx ablo connect apply --url <postgres-url>` provisions scoped roles and replication using the admin credential supplied for that command. Model writes then go through Ablo and land in your Postgres; its change stream confirms them. Ablo does not own your rows or run application-schema migrations. Your ORM remains responsible for tables, columns, and constraints.
 - **Fallback — signed Data Source endpoint** (DB can't grant a `REPLICATION` role): the generated `ablo/data-source.ts` exposes one route; Ablo sends signed requests and your app touches its own DB. **Only in this mode** does `npx ablo migrate` provision the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`) plus your Ablo models — it does **not** touch your other tables. Keep your own migrations (drizzle-kit / prisma migrate) for auth and anything outside the Ablo schema.
 - **No database yet?** Run `npx ablo dev --no-watch --branch <name>` to create an isolated non-root branch and obtain its expiring `sk_` credential. The branch uses a throwaway hosted data plane; Production remains the protected root. There is no shared Sandbox mode.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
@@ -21,7 +21,7 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 
 When you use the signed-endpoint fallback, the generated `ablo/data-source.ts` is the whole endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
 
-**Working on a real database?** Ablo never runs DDL, migrates, or drops on your database, and every model write is claim-checked and reversible in the log — so reads and `ablo.<model>.update(...)` are yours to run freely, while raw DDL (`ALTER TABLE …`) and a `--yes` cutover belong to a human. When you're unsure whether a write fits, `npx ablo check` reports the live column-by-column fit read-only, before anything runs. Full sorting rule: [Operating on Your Database](./docs/operating-on-your-database.md).
+**Working on a real database?** Plain model writes are last-write-wins when no active claim applies. Use a functional update, a held claim, or `readAt` when a result depends on an earlier value. Reads are safe to inspect; raw application DDL (`ALTER TABLE …`) and a `--yes` connection cutover belong to a human. When you're unsure whether a write fits, `npx ablo check` reports the live column-by-column fit read-only, before anything runs. Full sorting rule: [Operating on Your Database](./docs/operating-on-your-database.md).
 
 ## Rule
 

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 0.49.0
+
+### An agent can tell Ablo what it read before it writes
+
+An agent reads a row, spends a model call deciding what to do, and then writes.
+Another agent can change that row while the model is still thinking, and the
+write lands anyway, on top of a decision that is no longer true. Pass the rows
+the decision was based on:
+
+```ts
+const task = await ablo.tasks.get({ id: taskId });
+await ablo.tasks.update({
+  id: task.id,
+  data: { status: 'done', result: `Completed: ${task.title}` },
+  reads: [task],
+});
+```
+
+If either row moved while the agent was thinking, the write is refused instead
+of overwriting. The rows carry that evidence themselves, so there is nothing to
+set up around your agent and no wrapper to run it inside. One row or several,
+the same row you are writing or a different one, all use `reads`. Rows an agent
+read without passing stay out of it, so `reads` says what the decision rested on
+rather than everything the agent happened to look at.
+
+`idempotencyKey` stays a separate option. It gives a write one stable identity if
+the agent retries, which is a different question from what the write assumed.
+
+### A claim holds while an agent thinks
+
+Agents that take minutes per turn can now hold work safely. A claim waits its
+turn or skips, expires on its own, and keeps itself alive with a heartbeat while
+the agent works.
+
+If an agent loses its claim during a model call, its final write is refused. Two
+agents cannot both believe they own the same task and both write, and a slow
+agent cannot land its answer on top of whoever picked the work up after it. Ablo
+decides who holds the claim, so an agent cannot assert one it does not have.
+
+### An agent can read back what it committed
+
+Ask what happened to a write, using the same key the agent wrote with:
+
+```ts
+const record = await ablo.commits.get({ id: commitId });
+```
+
+The answer says who committed, what they intended, whether it is confirmed, and
+which claim protected it. `commits.list` walks the history a page at a time, so
+one agent can review what another already did before repeating it.
+
+What an agent sent is not kept. Prompts, reasoning, and your customers' row
+values are removed before the record is stored, so reading history back never
+replays an agent's inputs. Records are kept for 90 days, and permanently for a
+database you connected.
+
+### An agent can check what its key allows before it acts
+
+An agent holding a key can now ask what that key permits and get the answer from
+Ablo, whether it keeps a connection open or calls over HTTP for a single turn.
+An agent that mints a narrower key for a sub-task can confirm what it handed
+over.
+
+### A refused action says which permission was missing
+
+When Ablo refuses, the error names the permission the agent needed. An agent can
+report exactly what it lacked, or request it, instead of retrying a call that
+will never succeed.
+
+### Models named in camelCase resolve when writing to your own database
+
+A model whose key mixes capital letters did not match its declared name when the
+write went to your database directly, so those writes could not find their
+target. They resolve now.
+
+### `ablo connect apply` says when a database is already connected
+
+Connecting a database that another project already owns reported a missing table
+mapping, which described a symptom rather than the reason the command could not
+continue. It now says the database is already connected. Nothing is written
+while it checks, and a project with no models still gets its preflight.
+
+**Action required.** Install this version rather than a tarball or a Git
+dependency. This release pairs the SDK with the engine running behind
+`api.abloatai.com`, which is already serving it, so there is nothing to
+coordinate on your side.
+
 ## 0.48.0
 
 ### A branch is unbound until you connect a database to it
@@ -46,6 +133,26 @@ temporary alias can go:
 DROP PUBLICATION IF EXISTS "ablo_publication";
 ```
 
+### `ablo dev --local` connects a branch to the database on your machine
+
+The rule above raises a fair question: if a branch is unbound until a database
+is connected, what connects one during development? `--local` does.
+
+```bash
+npx ablo dev --local
+```
+
+It registers a connector-only endpoint for that exact branch and opens a
+long-lived secure connector. Your database stays where it is: Ablo receives an
+endpoint descriptor and a signing key, never a connection string, and reaches
+your source back through the connector rather than dialling it. `DATABASE_URL`
+is read from `.env.local` into the handler running on your machine and goes no
+further.
+
+The branch is then connected like any other, so schema pushes, reads and writes
+behave the way they will in production. Because the connector is long-lived,
+`--local` cannot be combined with `--no-watch`.
+
 ### Renamed
 
 `FootprintPlane` is now `DataSourceIdentity`, with the same three fields. The
@@ -433,7 +540,7 @@ through the same transaction API as every other caller.
 
 The integrations keep each product in its proper role: Temporal and Inngest
 own durable execution, scheduling, retries, and workflow history; Ablo owns
-shared-data authority, claims, conflicts, idempotency, settlement, and ordered
+shared-data authority, claims, conflicts, idempotency, confirmation, and ordered
 observation. Workflow code does not open WebSockets or hold live client state.
 
 ### Database adapter foundation, starting with PostgreSQL
@@ -537,7 +644,7 @@ Install `@abloatai/ablo` as the single public SDK:
 - `@abloatai/ablo/react` provides the React bindings.
 
 Every entrypoint uses the same schema, capabilities, commits, claims,
-idempotency, settlement, and ordered changes. Authoritative reads use
+idempotency, confirmation, and ordered changes. Authoritative reads use
 `model.get({ id })`; local reactive snapshots use `model.local.get(id)`.
 
 ### Coordination now matches the unit applications can safely write

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>The transaction layer for AI agents.</strong>
+  <strong>Collaboration infrastructure for AI agents.</strong>
 </p>
 
 <p align="center">
@@ -22,17 +22,12 @@
 
 ---
 
-> **Reading the implementation?** Start with the
-> **[source code map](./CODEMAP.md)**. It shows which files own `create`,
-> `update`, `delete`, `claim`, schemas, transports, and the reactive client.
+Ablo is collaboration infrastructure for AI agents: one API for agents, apps,
+and services to claim, change, and confirm the same rows.
 
-Safely coordinate AI agents, humans, workflows, and services writing to the
-same database.
-
-Ablo is an authoritative transaction layer for shared application state. Every
-write goes through one typed API where authority, idempotency, conflicts,
-ordering, and confirmation can be enforced. Your Postgres remains the source
-of truth.
+Every write goes through it, so authority, idempotency, conflicts, ordering,
+and confirmation are enforced in one place. Your Postgres remains the source of
+truth.
 
 ## Why Ablo
 
@@ -58,7 +53,7 @@ npx ablo dev
 temporary credential to gitignored `.env.local`, pushes the schema, and watches
 for changes.
 
-Read and write through the transaction layer:
+Read and write through one typed API:
 
 ```ts
 const order = await ablo.orders.get({ id: orderId });

package/docs/agent-messaging.md

@@ -12,7 +12,7 @@ HTTP, or be replayed from the sync cursor.
 | Need | Use | Why |
 | --- | --- | --- |
 | "I am holding this row because..." | `claim({ description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
-| "Remember this handoff/status/request" | A `messages` model | Durable row. Ordered in `sync_deltas`, replayed after reconnect, readable by HTTP agents. |
+| "Remember this handoff/status/request" | A `messages` model | Durable row, replayed after reconnect and readable by HTTP agents. |
 
 Claim context is ephemeral. If a participant was offline, reconnected later, or
 only uses `transport: "http"`, it can miss claim/presence frames. Message rows
@@ -141,6 +141,6 @@ their cursor and see the rows they missed while offline.
 ## Retention
 
 Deleting or archiving old `messages` rows is your app's policy. The sync log is
-still durable audit/history: `sync_deltas` has no message-specific TTL. That is
+still durable audit/history: messages have no message-specific TTL. That is
 useful for coordination and compliance, but a chat-scale product should plan
 retention before writing high-volume conversation traffic.

package/docs/api.md

@@ -2,8 +2,8 @@
 
 > The per-method reference for every model call an agent or an interface can make.
 
-> **Upgrading?** Every breaking change and its migration is on the
-> [Version History & Migration Guide](./migration.md).
+> **Upgrading?** Follow the version-matched workflow in the
+> [Upgrade Guide](./migration.md), then read the intervening changelog entries.
 
 This is the per-method reference for reading and writing rows that stay in
 sync across sessions. You declare your models once, then call the same

package/docs/concurrency-convention.md

@@ -1,305 +1,119 @@
 # Concurrency Convention
 
-> The governing rule for how Ablo resolves concurrent writes to shared state.
+> What Ablo checks when a guarded write depends on earlier state.
 
-This page is the contract: the `onStale` dispositions, what a conflict is
-checked against, and where the convention stops. The three-layer mechanics of
-claiming live in [Coordination](./coordination.md).
+Ablo never infers whether a write depends on earlier state. You decide, in two
+places. The model's `conflict` setting in the schema says what each kind of
+participant does when it hits a conflict, and it is the policy for that model.
+A per-write `onStale` states the disposition for one write. Ablo enforces what
+you declared and nothing else.
 
----
+## Unguarded writes
 
-## 1. The principle: non-coercion
-
-**The engine surfaces the truthful current state and lets the intelligent actor —
-agent or human — decide what to do. It does not force a resolution.**
-
-That is the whole convention. Everything below is a consequence of it.
-
-Classical concurrency control is *coercive*: it imposes the remedy. Two-phase
-locking forces a block; optimistic concurrency forces an abort. Ablo's wager is
-that the actor in the loop (an agent reasoning over the change, or a human
-watching the row) is better placed to resolve a conflict than a fixed rule baked
-into the storage layer. So the engine's job narrows to one thing: **report what
-is true, on time, and get out of the way.**
-
-There are two forms of non-coercion, and they are the same principle at two
-moments in time:
-
-| form | when | mechanism |
-|---|---|---|
-| **Claim** | *prospective*: before you act | reserve the row; others queue. Coordinate so the conflict never forms. |
-| **Notification** | *in-flight*: after a concurrent change | surface the changed value; the actor resolves and re-issues. |
-
-Use a claim when you will hold the row across a slow read→reason→write gap. Use a
-notification when you didn't, and the premise moved under you.
-
----
-
-## 2. The dispositions (`onStale`)
-
-Every guarded write (and every premise declared in §4) says what should happen
-when it goes stale. Three modes, split by whether they **force** an outcome:
-
-| mode | coercive? | what the engine does | who resolves | use when |
-|---|---|---|---|---|
-| `notify` | **No**: surface + delegate | Holds the write (does **not** apply it); returns a `StaleNotification` with the current value. | The actor (agent or human) reconciles and re-issues. | The aligned mode: tell the actor what changed, let it solve. |
-| `reject` | **Yes**: force-abort | Throws `AbloStaleContextError`; the batch is discarded. | The caller retries from scratch. | Hard invariants; legacy/strict callers. The current default. |
-| `overwrite` | **Yes**: force-clobber | Overwrites blindly last-writer-wins; **no** signal. | Nobody. | You genuinely own the field and concurrent values are noise. |
-
-> `notify` is the convention. `reject` and `overwrite` are escape hatches for the
-> two ends — "never let this be wrong" and "never bother me." They are not the
-> spirit; they are the boundary of it.
-
----
-
-## 3. What is checked: two premises
-
-A conflict is a **premise intersection** — what your operation was based on
-overlaps a concurrent delta. Ablo checks two premises, and they are independent.
-They differ only in what declared them:
-
-| premise | declared by | question | scope |
-|---|---|---|---|
-| **Write-target** | per-op `readAt` | "did a row I'm **writing** change since I read it?" | the rows in `operations[]` |
-| **Batch** | batch-level `reads[]` | "did anything I **looked at** change since I read it?" | rows/groups in `reads[]`, even if not written |
-
-The write-target check alone is the narrow case the canary anomaly defeats: an
-agent reads `deal.stage`, writes `task.status`, and a peer moves `deal.stage` —
-`task` never changed, so a write-target-only check waves it through. The batch
-premise closes that gap.
-
----
-
-## 4. The batch premise (`reads[]`)
-
-A commit may declare, at the batch level, what its writes were based on.
-Two granularities, developer's choice per entry:
+A plain write has no stale premise:
 
 ```ts
-reads: [
-  { model: 'Document', id: 's-1', readAt: N, fields?: ['title'] }, // ROW premise
-  { group: 'workspace:abc', readAt: N, onStale: 'notify' },          // GROUP premise
-]
+await ablo.tasks.update({ id, data: { status: 'done' } });
 ```
 
-- **Row:** did this specific row (optionally these fields) change? The literal
-  per-object premise.
-- **Group:** did *anything* in this sync group change? `group` is a sync-group
-  key (`workspace:abc`, `document:s1`, `org:X`) — the same unit a participant **watches
-  and claims**. This is the more Ablo-native granularity.
+If no active claim conflicts with it, the write is last-write-wins. That is a
+choice rather than a fallback: use it for independent assignments where the
+latest value should win. When a model's writes are never independent, say so
+once in its `conflict` setting instead of at every call site.
 
-**Boundary — a stale premise fires over the whole batch.** Each entry covers
-*all* the writes in the commit, so its disposition governs the batch:
-`reject` aborts it, `notify` holds **every** write and notifies, `overwrite`
-lets them land. Per-entry `onStale` defaults to `reject`.
+## Guarded writes
 
----
+Pass the exact returned rows when a write is based on values previously read:
 
-## 5. The notification (`StaleNotification`)
-
-The non-coercive modes hand back data instead of throwing. The signal is
-delivered **twice**, by design — once as a value, once as an event:
-
-- On the **commit receipt**: `receipt.notifications` (and `CommitResult.notifications`).
-- On the **event channel**: `conflict:notified` (mirrors `reconciliation:needed` /
-  `sync:rollback`).
-
-Shape (canonical in `coordination/schema.ts`): one advisory in two scopes, told
-apart by `scope`, the same way `reads[]` entries come at two granularities.
+```ts
+const task = await ablo.tasks.get({ id });
+const policy = await ablo.policies.get({ id: policyId });
+if (!task || !policy) throw new Error('required input is missing');
+
+await ablo.tasks.update({
+  id: task.id,
+  data: { status: 'done' },
+  reads: [task, policy],
+});
+```
 
-Both scopes carry:
+Ablo privately resolves each exact object to its model, id, and read watermark,
+then compares those premises with current state when the write is accepted.
+Clones, fabrications, and rows returned by another client are rejected locally.
 
-| field | meaning |
+| Disposition | If the premise is stale |
 |---|---|
-| `object` | stable type tag: `'stale_notification'` |
-| `scope` | `'row'` or `'group'` — which premise granularity fired |
-| `target` | **the row that moved**, and which parts: `{ model, id, fields }`. The same locator a claim names its subject with |
-| `readAt` | the watermark the committer reasoned against |
-| `observedSyncId` | the newest delta on the premise: re-read at/after this |
-| `writtenBy` | `{ kind, id }` of the concurrent author, reported faithfully |
-
-`scope: 'row'` adds:
+| `reject` | Reject the write with `AbloStaleContextError`. |
+| `notify` | Keep the current row, return a `StaleNotification`, and let the caller reconcile. |
+| `overwrite` | Apply the new value without enforcing the stale premise. |
 
-| field | meaning |
-|---|---|
-| `currentValues` | the live values of `target.fields`: the premise to reconcile against |
+`notify` is useful when an agent or human can merge the new information.
+`reject` is useful when the caller should restart from fresh state. Use
+`overwrite` only when the newer assignment should unconditionally win.
 
-`scope: 'group'` adds:
+## Functional updates
 
-| field | meaning |
-|---|---|
-| `group` | the group premise that fired (`report:abc`) |
-| `propagation?` | how `target` reached `group`: `{ via, through }` |
-| `changed?` | how much of the group moved: `{ count, sample, truncated }` |
+For a pure read-modify-write calculation, use the functional update form:
 
-`target` names the row that changed in **both** scopes. A group notification
-reports the moved row there and the premise it broke in `group`, so the two are
-never the same field.
+```ts
+await ablo.counters.update(counterId, (current) => ({
+  value: current.value + 1,
+}));
+```
 
-Only `notify` produces a notification (the write was held). `reject` throws and
-`overwrite` is silent — neither notifies.
+It performs the read, guarded write, and bounded reconciliation loop for you.
+See [Coordination](./coordination.md#functional-updates).
 
-### 5.1 The receive → reconcile loop
+## Claims
 
-You receive the signal two ways (same payload), then re-commit against the fresh
-watermark. The engine never re-issues for you — the actor decides.
+A claim protects a target across a longer interval. By default, other
+participants cannot write the claimed target, while contenders that claim it
+wait their turn. Reads remain open. A model's explicit conflict policy can
+choose a different disposition for a participant kind.
 
-```ts
-// Trigger: a guarded write under the non-coercive mode.
-const receipt = await ablo.task.update({
-  id, data: { status: 'blocked' },
-  readAt: myWatermark,
-  onStale: 'notify',
-});
+Claims and stale guards protect different things:
 
-// Receive — pull: the held write surfaces on the receipt.
-for (const n of receipt.notifications ?? []) resolve(n);
-
-// Receive — push: the same StaleNotification[] fires ambiently on the socket.
-ws.subscribe('conflict:notified', ({ notifications }) => notifications.forEach(resolve));
-
-function resolve(n: StaleNotification) {
-  // n.target     — the row that moved, and which fields (both scopes)
-  // n.writtenBy  — who moved it (e.g. { kind: 'agent', id: 'agent-b' })
-  if (n.scope === 'group') {
-    // "something in report:abc moved" — but `target` says WHICH row, so this is
-    // a one-row re-read, not a re-read of the group.
-    // n.propagation?.via — 'self' | 'parent' | 'transitive'
-    return refreshRow(n.target.model, n.target.id, n.observedSyncId);
-  }
-  // n.currentValues — what's actually there now (e.g. { status: 'done' })
-  if (!stillValid(n.currentValues)) return;       // premise gone → drop the write
-
-  return ablo.task.update({
-    id: n.target.id,
-    data: { status: 'blocked' },
-    readAt: n.observedSyncId,   // adopt the new high-water mark — this is what terminates the loop
-    onStale: 'notify',
-  });
-}
-```
+- A claim excludes other participants while it is held.
+- A stale guard proves that the state a write depended on has not changed.
+- A write made under a claim is still rejected if its own claimed snapshot has
+  become stale.
 
-The loop **terminates** because each retry advances `readAt` to `observedSyncId`;
-a peer that keeps writing only ever notifies you against a *newer* baseline, never
-the same one twice.
+See [Coordination](./coordination.md#claims) for the API.
 
-### 5.2 Reading a group notification
+## Cross-row and batch premises
 
-A group premise says "anything in this group", so the notification has to answer
-"what, exactly?" or the only correct response is to re-read the whole group —
-which on a busy group is how a reconcile loop turns into a large, repeated read.
+Model writes and lower-level commits can declare rows they read even when the
+write targets somewhere else. This protects decisions such as “update the task
+only if the deal I inspected has not changed.” A stale batch premise applies to
+the whole batch so atomicity is preserved.
 
-Four fields answer it:
+Use the high-level model methods unless you are building a custom runtime. When
+you do use batch premises, declare only the rows or groups that materially
+influenced the decision; overly broad premises create unnecessary contention.
 
-- **`target`** — the row that moved and the fields that changed on it. Usually a
-  one-row re-read.
-- **`group`** — the premise that fired.
-- **`propagation`** — how the row reached the group. `via: 'self'` means the row
-  *is* the group's scope root; `'parent'` means one containment edge below it;
-  `'transitive'` means further up, with `through` listing the intermediate
-  models (`['slides', 'decks']`).
-- **`changed`** — how much moved, in **distinct rows** rather than deltas.
-  `count` is the total, `sample` names the most recently changed (capped), and
-  `truncated` says whether the sample tells the whole story.
+## Notifications
 
-`changed` is what lets an actor decline. One row moved, re-read one row; twelve
-thousand moved, stop reasoning and resync the group — or abandon:
+A `StaleNotification` identifies the stale premise and provides the current
+state needed to reconcile. The original write has not been applied.
 
-```ts
-if (n.changed && n.changed.count > 50) return null; // too much moved — abandon the write
-for (const row of n.changed?.sample ?? []) await refresh(row.model, row.id);
-```
+A typical loop is:
 
-`propagation` is absent when the commit path has no record-group spec for the
-model, which is the one case where the server knows a group moved without
-knowing the route. Treat its absence as "re-read the group", the old behavior.
+1. Inspect the current value in the notification.
+2. Recompute the intended change.
+3. Submit a new guarded write with a fresh premise.
 
-### 5.3 Gating on what you know
+Give this loop a retry budget. Continuous contention should surface to the
+caller rather than retry forever.
 
-The notification tells you a belief moved. Whether that should *stop you writing*
-is a separate decision, and it belongs on the belief, not on the write.
+## Boundaries
 
-A `track` is a standing premise — what you are watching, with a watermark for
-when you last looked. Its disposition says what a move does to your next commit:
+Concurrency control does not replace:
 
-```ts
-await ablo.documents.track({ id: 's-1' });                     // notify — report it
-await ablo.documents.track({ id: 's-1', onStale: 'reject' });  // reject — gate my next write
-```
+- database constraints and transactions for application invariants;
+- authorization for deciding who may read or write;
+- idempotency for safely replaying the same request;
+- claims for exclusivity across slow, side-effecting work.
 
-`reject` refuses your next commit while that belief is stale, **even if the
-commit writes an unrelated row**. The gate is on what you *know*, not on what you
-are touching — which is the case a read→reason→write agent actually has.
-
-It is enforced at the commit chokepoint, so it is a guarantee rather than a
-convention. And the gate takes a key: it does not reopen on its own, because an
-agent retrying blindly would land exactly the write `reject` was asked to
-prevent. Re-read, then re-register the track to say you have. See
-[Groups](./groups.md#reporting-or-gating-onstale).
-
-A row that goes stale twice is telling you something: the read→reason→write gap
-wants the *prospective* guard, not the in-flight one. Escalate to a claim
-(§1) rather than raising `retries`.
-
----
-
-## 6. Boundaries & invariants
-
-What the convention **guarantees**, and where it **stops**:
-
-1. **Engine surfaces, actor decides.** Under `notify` the engine never
-   repairs, merges, or re-plans. It reports `currentValues` and the actor (agent
-   or human) owns the resolution. The engine does not distinguish them — it is
-   actor-neutral by design.
-
-2. **Truthfulness:** `currentValues` / `observedSyncId` reflect committed state at
-   detection time, inside the same transaction as the write. A notification is
-   never speculative.
-
-3. **No livelock, which is not the same as termination.** The monotonic
-   `sync_id` landing order is the serialization order. The stale committer
-   always yields/recomputes — an asymmetry that rules out the symmetric
-   notify-rewrite livelock, because each round adopts a newer `observedSyncId`
-   and no baseline is ever reasoned against twice.
-
-   It does **not** rule out starvation. A peer writing faster than your
-   read→decide→write gap keeps winning, and the engine never re-issues on your
-   behalf, so the rounds are yours and they are unbounded. Progress in the
-   watermark is not progress in the work — and for an agent, each round is a
-   model call. `update(id, fn)` bounds it for you and hands the conflict to
-   your updater (§5.3); a hand-rolled loop must bound itself.
-
-4. **Scope: reversible DB state only.** The convention governs writes to the
-   shared database, which are inherently reversible (prior value in
-   `sync_deltas`). **Irreversible external side-effects** (emails, payments,
-   third-party calls) are *out of scope* — the engine cannot hold or undo them,
-   so they must not be gated by `notify`.
-
-5. **Defaults.** A plain write (no `readAt`) is last-writer-wins with **no**
-   check. A guarded write with `readAt` but no `onStale` defaults to `reject`.
-
-6. **Policy seam.** Custom `ConflictPolicy` functions see **write-target**
-   conflicts (`stale_context` / `claim_held`). **Batch-premise** conflicts are
-   resolved directly via each entry's `onStale`, not through the policy seam.
-
-7. **Claims win when held.** A non-holder writing to a claimed row is rejected
-   (`AbloClaimedError`) regardless of `readAt` — the prospective form takes
-   precedence over the in-flight form. Only `user`/`system` principals may
-   `bypass` a foreign claim; agents may not.
-
----
-
-## 7. What this convention does not cover
-
-Three limits worth knowing before you rely on it.
-
-- **Irreversible external side-effects.** Emails, payments, and third-party
-  calls are not gated by this convention (§6.4). The engine cannot hold or undo
-  them, so never place one behind `notify`.
-- **A caller that declares nothing gets no check.** The batch premise catches
-  only what you declared. Write-target checking needs a `readAt` to compare
-  against, so a plain write with neither is last-writer-wins (§6.5). What you
-  declare is what is protected.
-- **`writtenBy.kind` reports what authenticated, not what you meant.** An `sk_`
-  key resolves to `system`, not `agent`. How identities map to participant kinds
-  is a separate concern from this convention.
+The rule is simple: the model's `conflict` setting is the policy, and each write
+declares what it read. Plain writes are last-write-wins because declaring
+nothing is itself a decision, so make it deliberately.