@abloatai/ablo 0.34.1 → 0.35.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,19 +21,19 @@ 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.
 
 ---
@@ -43,13 +45,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 +87,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 +104,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 +140,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 +155,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 +172,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 +197,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.
 
@@ -204,7 +207,7 @@ 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
+- **The convention** — 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).

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.

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,14 +10,14 @@ 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
 
-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
   commit chokepoint — where claims, ordering, and idempotency are enforced — and
@@ -57,7 +59,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 +82,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.