@abloatai/ablo 0.34.1 → 0.36.0

package/docs/examples/server-agent.md

@@ -1,11 +1,15 @@
 # Server Agent
 
+> A stateless schema-backed worker: wake, claim, commit, go idle.
+
 A server agent is backend code — a cron job, a queue worker, an AI task — that
 reads and writes your app's records outside the browser. The hard part is doing
-it without racing the live UI: if your worker and a user edit the same report at
-once, one write clobbers the other. This is what `claim()` is for. Below, a
-worker finishes a weather report by claiming it, writing the result, and
-releasing it automatically when the claim goes out of scope.
+it without racing whatever else is working: if two workers pick up the same task
+at once, one write clobbers the other. This is what `claim()` is for.
+
+Agents hold no socket, so pass `transport: 'http'` and import the same schema the
+rest of the app uses. Below, a worker finishes a task by claiming it, writing the
+result, and releasing it automatically when the claim goes out of scope.
 
 `claim({ id })` takes the record for your worker and returns a disposable handle:
 the fresh post-lease row is on `claim.data`, and holding the handle with
@@ -18,53 +22,69 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  weatherReports: model({
-    location: z.string(),
-    status: z.enum(['pending', 'ready']),
-    forecast: z.string().optional(),
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
+    summary: z.string().optional(),
   }),
 });
 
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
 });
 
-export async function completeReport(reportId: string) {
+export async function completeTask(taskId: string) {
   await ablo.ready();
 
-  const report = await ablo.weatherReports.retrieve({ id: reportId });
-  if (!report) return { status: 'not_found' };
+  const task = await ablo.tasks.retrieve({ id: taskId });
+  if (!task) return { status: 'not_found' };
 
-  await using claim = await ablo.weatherReports.claim({
-    id: reportId,
+  await using claim = await ablo.tasks.claim({
+    id: taskId,
     queue: false,
     description: 'completing',
   });
-  const claimed = claim.data;
 
-  const updated = await ablo.weatherReports.update({
-    id: claimed.id,
-    data: { status: 'ready' },
+  const updated = await ablo.tasks.update({
+    id: claim.data.id,
+    data: { status: 'done' },
     wait: 'confirmed',
   });
 
-  return { status: 'ready', report: updated };
+  return { status: 'done', task: updated };
+  // claim auto-releases as the function returns
 }
 ```
 
 `retrieve({ id })` is an async server read — it hits the server and returns the
-row (or `null`, which the early `not_found` guard handles). The update runs while
-the claim is held, and `wait: 'confirmed'` makes that update resolve only once
-the server has accepted it.
+row (or `undefined`, which the early `not_found` guard handles). The update runs
+while the claim is held, and `wait: 'confirmed'` makes it resolve only once your
+database has confirmed the row landed.
 
 The two options on the claim:
 
 - `queue: false` — skip this record if another claim is already in progress,
-  rather than queueing behind it. (The default queues.)
-- `description: 'completing'` — a human-readable label for what your worker is doing,
+  rather than queueing behind it. Fail-fast dedup: *if someone else has this job,
+  skip it.* (The default queues.)
+- `description: 'completing'` — a readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 
-Because the worker uses the same schema and `claim()` as the UI, its writes sync
-to every connected client in real time and never collide with edits already in
-progress.
+## Atomic batches
+
+When several rows must change together, submit one atomic commit through the same
+schema-backed client:
+
+```ts
+await ablo.commits.create({
+  operations: [
+    { action: 'update', model: 'tasks', id: 'task_123', data: { status: 'done' } },
+  ],
+  wait: 'confirmed',
+});
+```
+
+Because the worker uses the same schema and `claim()` as everything else, its
+writes reach every connected client in real time and never collide with work
+already in progress.

package/docs/groups.md

@@ -1,5 +1,7 @@
 # Change Propagation
 
+> How one row's change reaches the rows and actors that depend on it.
+
 > How a change to one row reaches the rows and actors that depend on it, and how
 > to keep a chain of dependent work fresh. This is the propagation half of sync
 > groups; [`identity.md`](./identity.md) is the access half (who may read a
@@ -10,8 +12,8 @@
 
 ## Start from the problem
 
-An agent reads deck `A` to write slide `B`. A moment later it reads `B` to write
-layer `C`. Between those steps someone else edits `A`. The agent is now building
+An agent reads workspace `A` to write document `B`. A moment later it reads `B` to write
+block `C`. Between those steps someone else edits `A`. The agent is now building
 `C` on a premise that has moved — and nothing about writing `C` looks wrong in
 isolation. That is stale context, and it is the thing sync groups let you catch.
 
@@ -19,23 +21,73 @@ The recipe is one field on the commit: declare the group you read as a premise,
 and say what should happen if it moved.
 
 ```ts
-// The agent read everything under deck:abc to compose this write.
-await ablo.layers.update({
-  id: 'layer-C',
+// The agent read everything under workspace:abc to compose this write.
+await ablo.blocks.update({
+  id: 'block-C',
   data: { text: revised },
-  reads: [{ group: 'deck:abc', readAt: watermark, onStale: 'notify' }],
+  reads: [{ group: 'workspace:abc', readAt: watermark, onStale: 'notify' }],
 });
 ```
 
 At commit, inside the write transaction, the engine asks a single question: *did
-any delta routed to `deck:abc` land after `watermark`?* If nothing moved, the
+any delta routed to `workspace:abc` land after `watermark`?* If nothing moved, the
 write applies. If something moved, `onStale` decides — `notify` holds the write
 and hands the agent a `StaleNotification` naming the group, so it re-reads
-`deck:abc` and regenerates; `reject` aborts the batch with a `409`. The agent
+`workspace:abc` and regenerates; `reject` aborts the batch with a `409`. The agent
 never persists work built on a premise it can no longer see.
 
 ---
 
+## How you hear about it
+
+Four channels carry "something changed", and they answer four different
+questions. Pick by the question you have.
+
+```ts
+// A screen that stays current.
+ablo.documents.onChange((docs) => render(docs));
+
+// Who else is in here, and what are they holding.
+await using room = await ablo.documents.join(documentIds, { ttl: '5m' });
+room.peers;
+
+// Stop this write if the thing I read moved while I composed it.
+await ablo.blocks.update({ id, data, reads: [{ group: 'workspace:abc', readAt, onStale: 'notify' }] });
+
+// Tell me later if this moves, even though I am not writing now.
+await ablo.documents.track({ id: 's-1' });
+```
+
+| Question | Channel | Arrives |
+| --- | --- | --- |
+| What do the rows say right now? | `onChange` | As deltas land, on the socket |
+| Who else is working here? | `join`, then `room.peers` and `room.claims` | As participants come and go, on the socket |
+| Did the premise for **this** write move? | `reads` on the write | On that write's receipt, before it applies |
+| Has anything I read moved since? | `track` | On your next commit's receipt |
+
+Two distinctions do most of the work here.
+
+**`join` is about people; `track` is about data.** Both open a subscription and
+both are scoped by sync group, which is why they look alike. `join` reports
+participants: who is present, what they are doing, which rows they hold. `track`
+reports the rows themselves: something you said you cared about moved, here is
+the watermark to re-read it at. A tool that wants to avoid duplicating a peer's
+work needs `join`. A tool whose output goes stale when its inputs change needs
+`track`.
+
+**`reads` guards one write; `track` outlives it.** They speak the same
+vocabulary and produce the same `StaleNotification`. A `reads` entry is checked
+once, at the commit that carried it, and discarded. A `track` is persisted and
+re-checked against every delta after it, so a long-running actor hears about a
+change that landed while it was thinking, on the next commit it makes.
+
+`onChange` and `join` need a live socket, so they are available on the default
+WebSocket client. `reads` and `track` ride the commit, so they reach a socketless
+actor over HTTP too, which is what makes them the notification path for agents
+and workers.
+
+---
+
 ## Three ways a change reaches other rows
 
 "A affects B and C" means three different things. The engine does the first two
@@ -43,13 +95,13 @@ for you and leaves the third to you — on purpose.
 
 **Routing — who hears about a change.** Every row belongs to one or more sync
 groups, and a write fans out to all of them. A row also inherits its ancestors'
-groups: editing a layer stamps the delta with `layer:…`, `slide:…`, *and*
-`deck:…`, so everyone watching the deck sees the layer move. This is delivery,
+groups: editing a block stamps the delta with `block:…`, `document:…`, *and*
+`workspace:…`, so everyone watching the workspace sees the block move. This is delivery,
 resolved by walking the ownership tree at commit time. It routes the change; it
 never recomputes a value.
 
-**Structural cascade — what disappears with a change.** Deleting a deck removes
-its slides and layers. The database does that through `ON DELETE CASCADE`, but a
+**Structural cascade — what disappears with a change.** Deleting a workspace removes
+its documents and blocks. The database does that through `ON DELETE CASCADE`, but a
 database-level cascade emits no delta, so open clients would quietly hold rows
 that no longer exist. The engine closes that gap: before the delete it snapshots
 the subtree and emits a tombstone for each descendant, routed to the right
@@ -85,8 +137,8 @@ reaches `C`.
 
 The direction matters. The signal flows forward, A to B to C, and each hop is a
 real write an actor chose to make. The engine supplies the edges (group
-membership) and a stale signal on each edge (the read-dependency check); the
-actors are the runtime that walks them. It is closer to a spreadsheet an analyst
+membership) and a stale signal on each edge (the premise check); the actors are
+the runtime that walks them. It is closer to a spreadsheet an analyst
 recalculates cell by cell than to a reactive engine that recomputes the whole
 column for you.
 
@@ -102,16 +154,17 @@ Two consequences worth designing around:
 
 ---
 
-## Declaring a read premise
+## Declaring the batch premise
 
-A read-dependency is a premise for the *whole* batch: its disposition governs
-every write in the commit, not just one operation. You choose the granularity per
+`reads[]` declares what the commit was based on. Each entry is a premise, and
+each governs the *whole* commit: if one goes stale, its disposition applies to
+every write in the batch, not just one operation. You choose the granularity per
 entry.
 
 ```ts
 reads: [
-  { group: 'deck:abc', readAt: N, onStale: 'notify' },      // did anything in the deck move?
-  { model: 'Slide', id: 's-1', readAt: N, fields: ['title'] }, // did this row (this field) move?
+  { group: 'workspace:abc', readAt: N, onStale: 'notify' },      // did anything in the workspace move?
+  { model: 'Document', id: 's-1', readAt: N, fields: ['title'] }, // did this row (this field) move?
 ]
 ```
 
@@ -137,7 +190,7 @@ the same row don't collide.
 
 ## Staying subscribed across commits: `track`
 
-A read premise guards a single commit: you state what you read, the engine
+A batch premise guards a single commit: you state what you read, the engine
 checks it, the premise is gone. That fits an actor that reads and writes in one
 breath. It does not fit a long-running one — an agent that reads a row now,
 works for a few minutes, and writes much later. By the time it commits, the
@@ -152,10 +205,10 @@ you, arriving on the write you were going to make anyway.
 
 ```ts
 // Register interest and walk away — no write required.
-await ablo.slides.track({ id: 's-1' });
+await ablo.documents.track({ id: 's-1' });
 
 // …minutes of other work later, on your next commit…
-const res = await ablo.layers.update({ id: 'layer-C', data: { text: revised } });
+const res = await ablo.blocks.update({ id: 'block-C', data: { text: revised } });
 res.notifications; // populated if s-1 moved under you in the meantime
 ```
 
@@ -169,11 +222,11 @@ You can also register a track as part of a write you are already making, the
 persisted companion to `reads`:
 
 ```ts
-await ablo.slides.update({
+await ablo.documents.update({
   id: 's-1',
   data: { title: revised },
-  reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }], // guards THIS commit
-  track: [{ group: 'deck:abc' }],                               // and keeps watching after it
+  reads: [{ group: 'workspace:abc', readAt: N, onStale: 'notify' }], // guards THIS commit
+  track: [{ group: 'workspace:abc' }],                               // and keeps watching after it
 });
 ```
 
@@ -194,8 +247,8 @@ broad wakes actors for changes they don't care about, and one that is too narrow
 misses the dependency you meant to track.
 
 The rule of thumb: **make a group the smallest set of rows that must stay
-mutually consistent.** A deck and its slides belong together because editing one
-changes what the others mean; two unrelated decks do not. Reach for finer,
+mutually consistent.** A workspace and its documents belong together because editing one
+changes what the others mean; two unrelated workspaces do not. Reach for finer,
 overlapping groups when you genuinely have a dependency chain to track, and keep
 them coarse everywhere else.
 
@@ -203,8 +256,12 @@ them coarse everywhere else.
 
 ## Where this is defined
 
-- **Access** — who may read or write a group — is [`identity.md`](./identity.md).
-- **The convention** — non-coercion, the read-set, and the notification — is
+- **Access**, meaning who may read or write a group, is
+  [`identity.md`](./identity.md).
+- **The convention** behind non-coercion, the premise, and the notification is
   [`concurrency-convention.md`](./concurrency-convention.md) (§4 and §5).
-- **The mechanics** — the three coordination layers underneath — are
+- **The mechanics**, the three coordination blocks underneath, are
   [`coordination.md`](./coordination.md).
+- **`join` and presence**, the participant half of the table above, are
+  [`coordination.md`](./coordination.md) for the claim stream and
+  [`react.md`](./react.md) for `useJoin`.

package/docs/guarantees.md

@@ -1,7 +1,9 @@
 # Guarantees
 
-When an Ablo write succeeds, the server has accepted it — and when two people or
-agents touch the same row, Ablo coordinates them instead of letting one silently
+> Exactly what a confirmed write, a rejected stale write, and a held claim each promise.
+
+When an Ablo write succeeds, the server has accepted it — and when two agents
+touch the same row, Ablo coordinates them instead of letting one silently
 overwrite the other. This page is the precise list of what you can count on:
 confirmed writes, stale-write protection, claims, and the audit trail behind
 every change.
@@ -63,11 +65,13 @@ await ablo.weatherReports.update({
 `onStale: 'reject'` prevents lost updates. If the target changed after the
 snapshot, the server rejects the write instead of applying stale reasoning.
 
-Advanced policies exist for controlled product flows:
+Two other dispositions exist. `overwrite` applies the write with no stale check
+at all. `notify` **holds** the write, so the row is left as it stands, and hands
+back a `StaleNotification` carrying the current value for the actor to reconcile
+and re-issue; the rest of the batch still commits.
 
-- `reject` fails the write when state moved.
-- `overwrite` applies the write without stale protection.
-- `notify` accepts the write and marks it for product review.
+See [Concurrency Convention](./concurrency-convention.md) for the full taxonomy,
+what each disposition is checked against, and where the convention stops.
 
 ## Claim Coordination
 
@@ -97,14 +101,39 @@ Agents should import the same schema as the app and write through
 
 ## Audit Trail
 
-Accepted writes can be attributed to:
+Attribution is not a separate log you opt into. It rides on the change itself.
+Every broadcast delta names the actor, the authority it acted under, the
+credential that authorized it, and the approval stage it was in:
+
+```ts
+{
+  modelName:         'weatherReports',
+  modelId:           'report_stockholm',
+  actionType:        'U',
+  actor:             { kind: 'agent', id: 'weather-agent-v3' },
+  onBehalfOf:        { kind: 'user',  id: 'user_8f2a' },
+  capabilityId:      '…',       // the key the write was authorized by
+  confirmationState: 'auto',    // previewed | approved | required_human_approval
+  createdAt:         '2026-05-14T14:22:01.034Z',
+}
+```
+
+`actor` and `onBehalfOf` are derived from the credential, not from the call site,
+so an agent cannot name a different actor in its own write. `capabilityId` is
+non-null for every agent and system commit, so a write can always be traced to
+the key that made it, and from that key to the person it was issued to.
+
+The stored history goes one step further than recording. Audit rows are chained
+with a keyed hash, so the log is tamper-*evident*: `verify-chain` walks the chain
+and, if it breaks, names the sequence number and the hashes that disagree. No
+chain roots at an agent. The delegation root is always the person who set the
+work in motion.
 
-- the actor that wrote,
-- the human or system the actor worked on behalf of,
-- the model, operation, and state cursor.
+For agent work this is what answers, after the fact: what changed, who authorized
+it, which run did it, and whether a human was in the loop.
 
-For agent work, this is what lets an audit surface answer: "what changed, who
-authorized it, which run did it, and what state was it based on?"
+See [Audit Log](./audit.md) for the stored row shape, the filters, verification,
+and export.
 
 ## Persistence
 

package/docs/how-it-works.md

@@ -1,5 +1,7 @@
 # How Ablo Works
 
+> You write through Ablo, Ablo writes to your Postgres, and the write-ahead log confirms it.
+
 You write through Ablo, and Ablo writes to your Postgres. That one sentence is the
 whole model — everything below explains what it means and how to use it.
 
@@ -8,16 +10,16 @@ whole model — everything below explains what it means and how to use it.
 await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
 
 // Reads come back live, kept current from your database.
-const task = ablo.tasks.get('task_42');
+const task = ablo.tasks.local.retrieve('task_42');
 ```
 
-## The mental model — read this once
+## The mental model: read this once
 
-Ablo is a **coordination layer in front of your Postgres**. Humans, agents, and
-background jobs all change the same application data through one API, and Ablo
-makes sure their writes don't clobber each other.
+Ablo is a **coordination layer in front of your Postgres**. Agents, background
+jobs, and the people alongside them all change the same application data through
+one API, and Ablo makes sure their writes don't clobber each other.
 
-- **Writes go through Ablo.** `ablo.<model>.create / update / delete` enter Ablo's
+- **Writes go through Ablo:** `ablo.<model>.create / update / delete` enter Ablo's
   commit chokepoint — where claims, ordering, and idempotency are enforced — and
   Ablo applies the change to your Postgres through a scoped writer role. The commit
   is accepted (`queued`) the moment Ablo takes it.
@@ -35,17 +37,41 @@ makes sure their writes don't clobber each other.
 That's the shape: **you write through Ablo → it lands in your Postgres → the WAL
 echo confirms it → everyone connected sees it live.**
 
+## The primitives
+
+| Primitive | Plane | Purpose |
+|---|---|---|
+| `Schema` | State | Declares typed models the app and agents can read and write. |
+| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async reads), `local.retrieve`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
+| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral, never persisted. |
+| `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
+| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
+
+### Why each primitive is separate
+
+Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
+does a job the others cannot. If you are coming from Replicache or Yjs you would
+expect just `Commit`. Here is what the other two buy you over that minimum:
+
+- **`Claim` is not a read lock.** Reads stay open. Claims serialize
+  acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
+  from fresh state.
+- **`Receipt` is not a `200 OK`.** It is the durable artifact a commit produced:
+  accepted commit id, server-assigned timestamps, stale-check outcome. It is
+  addressable after the fact and replayable into a different client. A status
+  code cannot be re-read by a sub-agent that was not on the original call.
+
 ## Where your data lives
 
 You point Ablo at a Postgres database, and that's where its rows live. Only *which*
 database differs by environment — the code is identical.
 
-- **Production** — your Postgres. `ablo connect` sets up a scoped writer role and
+- **Production:** your Postgres. `ablo connect` sets up a scoped writer role and
   logical replication; your rows live in your database, and Ablo writes to them
   through that role.
-- **Sandbox and local dev** — a separate or local Postgres you can throw away. Same
+- **Sandbox and local dev:** a separate or local Postgres you can throw away. Same
   models, same code, a different database behind them.
-- **Before you connect one** — Ablo keeps state in its own log, so you can build the
+- **Before you connect one.** Ablo keeps state in its own log, so you can build the
   whole app today and point it at a real database when you're ready.
 
 Registering the database is the whole switch. There is no tier or flag to choose.
@@ -57,7 +83,7 @@ Registering the database is the whole switch. There is no tier or flag to choose
 npm install @abloatai/ablo
 npx ablo init
 
-# 2. Push your schema (the models humans and agents edit together).
+# 2. Push your schema (the models your agents edit together).
 npx ablo push
 
 # 3. Connect your database — one command, admin credential used once and discarded.
@@ -80,13 +106,13 @@ export const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
 
 // 6. Read — live, no fetch loop.
-const task = ablo.tasks.get('task_42');
+const task = ablo.tasks.local.retrieve('task_42');
 
 // 7. Coordinate when more than one actor can touch a row. Hold a claim and Ablo
 //    serializes writes on that key against everyone else; read after claiming,
 //    then write. The lease releases automatically at the end of the scope.
 await using _hold = await ablo.tasks.claim('task_42');
-const latest = ablo.tasks.get('task_42'); // read after claiming, not from memory
+const latest = ablo.tasks.local.retrieve('task_42'); // read after claiming, not from memory
 await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
 ```
 

package/docs/idempotency.md

@@ -0,0 +1,126 @@
+# Idempotency
+
+> Make a retried write safe: the same key never applies the same change twice.
+
+An agent retries. A socket drops mid-commit, a worker restarts, a queue redelivers — and the write
+you already sent arrives again. An idempotency key is how Ablo tells a retry from a new intention.
+
+Every model write carries one. The SDK generates a key when you omit it, which makes an in-process
+retry safe automatically. It cannot make a retry across a process restart safe, because a new
+process generates a new key — so for anything that must survive a crash, supply your own.
+
+```ts
+await ablo.tasks.update({
+  id: taskId,
+  data: { status: 'done' },
+  idempotencyKey: `task:${taskId}:mark-done:v1`,
+  wait: 'confirmed',
+});
+```
+
+## The one rule
+
+**Derive the key from the business event, not from the attempt.** A key built from
+`crypto.randomUUID()` at the call site is regenerated on every retry, so it protects nothing — each
+attempt looks like a new intention and the write lands twice. A key built from the thing that
+happened (`task:42:mark-done:v1`) is identical on every retry by construction, which is the whole
+point.
+
+The same rule stated as its failure: never derive a key from a timestamp, an attempt counter, or a
+random value. If two retries of one operation can produce different keys, you have no idempotency.
+
+## How it works
+
+The key is not a lookup that happens before the write — it is the **execution lock on the write
+itself**. Ablo inserts a pending row keyed by the caller and the key inside the same transaction as
+the mutation, and a unique index makes that insert the lock:
+
+- **Insert wins:** this transaction owns the execution and runs the write.
+- **Insert conflicts:** someone else owns it. The second caller waits for the owner to finish and
+  then replays its recorded result.
+- **Insert conflicts, different request:** the key was reused to mean something else. Rejected.
+
+Because the lock and the write share a transaction, there is no window in which a write has happened
+but its key has not been recorded.
+
+Keys are scoped to **the organization and the participant**, not globally. Two agents can use the
+same key string without colliding, and one agent can never replay another's result.
+
+## The four outcomes
+
+| You send | Ablo does |
+|---|---|
+| A new key | Runs the write. |
+| The same key, the same request, already finished | Replays the recorded result. The write does not run again. |
+| The same key, the same request, still running | Waits for the in-flight attempt, then replays its result. If the original is still running after a short wait, rejects with `idempotency_conflict` (409): retry the same key. |
+| The same key, a **different** request | Rejects with `idempotency_conflict` (409). A key is bound to the request it first arrived with. |
+
+Both conflict cases return the same code, so tell them apart by what your own
+client did. If you retried an identical request, the original is still in flight
+— wait and retry the same key. If you changed the request, that is a client bug:
+use a new key.
+
+## Failures are not replayed: they re-run
+
+This is where Ablo deliberately differs from Stripe and from most payment APIs, and it is the
+behaviour most likely to surprise you.
+
+**Only successful writes are recorded.** A write that failed leaves no idempotency record, so
+retrying it with the same key **executes fresh** rather than replaying the error.
+
+That is the right default here because most failures are ones you can fix and legitimately want to
+re-attempt — a validation error, a stale premise, a claim held by someone else. Replaying the
+original error for 24 hours would strand the caller behind a decision that is no longer true.
+
+The consequence to hold onto: a retry after a failure is a real execution. If a write failed in a
+way that leaves you unsure whether it landed — a timeout, a dropped socket — do not assume the retry
+is a no-op. Retry with the **same key**: if the original did land, the recorded success replays; if
+it did not, the write runs now. That is exactly the case idempotency exists for.
+
+## The window
+
+A recorded result is retained for **24 hours**, then expires. Within that window a repeated key
+replays. After it, the key is forgotten and reusing it starts a genuinely new write.
+
+Treat 24 hours as *how long a retry is guaranteed safe*, not as permanent deduplication. A nightly
+job that reuses yesterday's key will execute again.
+
+Writes routed to a registered data source are the exception: their intent is retained **permanently**
+rather than expiring, because letting that record lapse would make a reused key indistinguishable
+from old work against your database. A key whose retained intent has expired is rejected with
+`idempotency_key_expired` (409) rather than being silently re-executed.
+
+## Route pinning
+
+A key is bound to the route its first attempt took. If an earlier attempt was applied through a
+direct data source and a retry arrives when the endpoint fallback is active, Ablo rejects it with
+`source_transport_pinned` (409) instead of switching.
+
+That refusal is deliberate: switching routes on a retry risks applying a write that the first route
+may already have committed. Restore the original route and retry the same key.
+
+## When to retry
+
+| Situation | Do |
+|---|---|
+| Timeout or dropped connection, no response | Retry with the **same** key, with backoff. You get the recorded success, or the write runs now. |
+| `source_unreachable` (503) | Retry with the **same** key once connectivity recovers. The write stays pinned to its route. |
+| `replication_lag_timeout` (504) | The write may have materialized. Retry with the **same** key, or wait for source ingestion to catch up. |
+| `AbloStaleContextError` | Re-read the row, regenerate, then write under a **new** key: the new write is a new intention. |
+| `AbloClaimedError` | Someone else holds the row. Wait or yield; the key is unused, so reuse it when you retry. |
+| `idempotency_conflict` (409) after an identical retry | The original is still in flight. Wait, then retry the **same** key. |
+| `idempotency_conflict` (409) after changing the request | A client bug: a key is bound to the first request sent under it. Use a **new** key. |
+| `idempotency_key_too_long` (400) | The key exceeds 255 characters. A UUID or a short business string works. |
+
+## Keys
+
+- Up to **255 characters**. Longer is rejected, not truncated.
+- Unique per logical operation, identical across every retry of that operation.
+- Generate a new one only when a genuinely new operation begins.
+- Never put secrets in a key — it is stored and appears in support diagnostics.
+
+## Related
+
+- [Client Behavior](./client-behavior.md) — every write option, and which errors retry.
+- [Guarantees](./guarantees.md) — what `queued` and `confirmed` promise.
+- [Errors](./errors.md) — the full code registry, including every code named above.