@abloatai/ablo 0.35.0 → 0.37.0

package/docs/deployment.md

@@ -57,10 +57,10 @@ A **plane** is the isolation unit a credential acts on. `production` is the root
 plane; every sandbox sits beside it. Three things are per-plane, and knowing
 which three is most of what production readiness means:
 
-- **Rows** — a sandbox write is invisible to production and to every other sandbox.
-- **The registered database** — one per plane, so your production database and
+- **Rows:** a sandbox write is invisible to production and to every other sandbox.
+- **The registered database:** one per plane, so your production database and
   your dev database are separate registrations.
-- **The active schema artifact** — the model shapes the engine actually routes on.
+- **The active schema artifact:** the model shapes the engine actually routes on.
 
 A key's plane is fixed at mint and spelled in its prefix: `sk_live_` acts on
 production, `sk_test_` on a sandbox. There is no runtime override — the
@@ -219,14 +219,14 @@ handler, the Standard Webhooks signature, and rolling a secret.
 
 ## What to watch once it is live
 
-- **`ablo logs`** — commit activity as it happens, scoped by the key, so a live
+- **`ablo logs`:** commit activity as it happens, scoped by the key, so a live
   key streams the org and a test key streams only its sandbox. `--json` emits
   NDJSON for piping.
-- **`ablo status`** — the readiness verdict. Cheap enough to run from a health
+- **`ablo status`:** the readiness verdict. Cheap enough to run from a health
   check on your own side.
-- **The [audit log](./audit.md)** — every confirmed write traced back to the key
+- **The [audit log](./audit.md):** every confirmed write traced back to the key
   that made it and the person who authorized that key.
-- **Your own logger** — pass `logger` to the client and SDK lifecycle, sync,
+- **Your own logger:** pass `logger` to the client and SDK lifecycle, sync,
   retry, and rollback events join your existing pipeline.
 
 Writes carry receipts rather than being fire-and-forget: a commit is accepted the
@@ -242,7 +242,7 @@ and what each promises.
 | `password authentication failed` during connect | Often a pooled host refusing a session it cannot serve, in the words of a wrong password. | Register the direct database host. |
 | `server_execute_unknown_model` | The plane's active schema does not carry that model. | `ablo push` with a key for that plane. |
 | Clients rejected at connect | The deployed schema and the client's schema disagree. | Push this tree, or deploy the revision the server is running. |
-| `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project — a push cannot cross projects. |
+| `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project: a push cannot cross projects. |
 | 403 on `ablo push` | The key authenticated but cannot author schema. | A secret `sk_live_`; the `ablo login` live key is observe-only. |
 
 ## The checklist

package/docs/examples/agent-human.md

@@ -25,7 +25,7 @@ a typed error if the row moved underneath you while the agent was busy.
 ## Schema-Backed Worker
 
 The worker uses the same schema client the app uses. It reads the task from the
-server with `retrieve({ id })`, claims the row, and writes through
+server with `get({ id })`, claims the row, and writes through
 `ablo.tasks.update(...)` with a stale-check so a concurrent edit can't be
 overwritten.
 
@@ -49,8 +49,8 @@ const ablo = Ablo({
 export async function markDone(taskId: string) {
   await ablo.ready();
 
-  // retrieve({ id }) is an async server read — await it.
-  const task = await ablo.tasks.retrieve({ id: taskId });
+  // get({ id }) is an async server read — await it.
+  const task = await ablo.tasks.get({ id: taskId });
   if (!task) return { status: 'not_found' };
 
   try {
@@ -109,7 +109,7 @@ Keep workers on the same schema-backed client as the app.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskRow({ task: serverTask }: Props) {
-  const data = useAblo((ablo) => ablo.tasks.local.retrieve(serverTask.id)) ?? serverTask;
+  const data = useAblo((ablo) => ablo.tasks.local.get(serverTask.id)) ?? serverTask;
   const holder = useAblo((ablo) => ablo.tasks.claim.state({ id: serverTask.id }));
   const agentActive = holder?.participantKind === 'agent';
 

package/docs/examples/ai-sdk-tool.md

@@ -54,7 +54,7 @@ const updateTask = tool({
     await ablo.ready();
 
     // retrieve hits the server for the latest row (async — await it).
-    const task = await ablo.tasks.retrieve({ id: taskId });
+    const task = await ablo.tasks.get({ id: taskId });
     if (!task) return { ok: false, reason: 'not_found' };
 
     // If another agent already holds this row, claim waits for them to finish,

package/docs/examples/existing-python-backend.md

@@ -87,13 +87,24 @@ browser only ever sees the short-lived token:
 ```ts
 // web/app/api/ablo-session/route.ts
 import { ablo } from '@/ablo';
+import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
 
 export const runtime = 'nodejs';
 
 export async function POST() {
   const userId = await currentUserId(); // your auth
-  const { token } = await ablo.sessions.create({ user: { id: userId } });
-  return Response.json({ token });
+  const { token, expiresAt } = await ablo.sessions.create({
+    user: { id: userId },
+    can: { tasks: ['read', 'update'] },
+  });
+  return Response.json(
+    credentialEndpointSuccessSchema.parse({
+      token,
+      expiresAt,
+      credentialKind: 'ephemeral',
+    }),
+    { headers: { 'Cache-Control': 'no-store' } },
+  );
 }
 ```
 
@@ -112,7 +123,7 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: string };
 }) {
-  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.get(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 
@@ -275,7 +286,7 @@ and timestamp. If the change originated from an Ablo commit, include the same
 Agents use the same model API as the UI:
 
 ```ts
-const report = await ablo.weatherReports.retrieve({ id: reportId });
+const report = await ablo.weatherReports.get({ id: reportId });
 const snap = ablo.snapshot({ weatherReports: reportId });
 
 await ablo.weatherReports.update({

package/docs/examples/nextjs.md

@@ -64,13 +64,34 @@ The browser can't hold `sk_`, so a backend route mints a scoped, short-lived
 // app/api/ablo-session/route.ts
 import { ablo } from '@/lib/ablo';
 import { getCurrentUser } from '@/auth';
+import {
+  credentialEndpointErrorSchema,
+  credentialEndpointSuccessSchema,
+} from '@abloatai/ablo/auth';
 
 export async function POST() {
   const user = await getCurrentUser();
-  if (!user) return new Response('Unauthorized', { status: 401 });
-
-  const session = await ablo.sessions.create({ user: { id: user.id } });
-  return Response.json({ token: session.token });
+  if (!user) {
+    return Response.json(
+      credentialEndpointErrorSchema.parse({
+        error: { code: 'session_expired' },
+      }),
+      { status: 401, headers: { 'Cache-Control': 'no-store' } },
+    );
+  }
+
+  const { token, expiresAt } = await ablo.sessions.create({
+    user: { id: user.id },
+    can: { tasks: ['read', 'create', 'update'] },
+  });
+  return Response.json(
+    credentialEndpointSuccessSchema.parse({
+      token,
+      expiresAt,
+      credentialKind: 'ephemeral',
+    }),
+    { headers: { 'Cache-Control': 'no-store' } },
+  );
 }
 ```
 
@@ -124,7 +145,7 @@ export default async function TaskPage({
 }: { params: Promise<{ id: string }> }) {
   const { id } = await params;
   await ablo.ready();
-  const task = await ablo.tasks.retrieve({ id });
+  const task = await ablo.tasks.get({ id });
   if (!task) return null;
 
   return <TaskEditor task={task} />;
@@ -167,7 +188,7 @@ you — re-fetch and retry.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskEditor({ task: serverTask }: Props) {
-  const data = useAblo((ablo) => ablo.tasks.local.retrieve(serverTask.id)) ?? serverTask;
+  const data = useAblo((ablo) => ablo.tasks.local.get(serverTask.id)) ?? serverTask;
   const holder = useAblo((ablo) => ablo.tasks.claim.state({ id: serverTask.id }));
   const busy = Boolean(holder);
 

package/docs/examples/scoped-agent.md

@@ -15,7 +15,7 @@ The three steps below show how to declare it, scope the agent, and write.
 
 See [Identity & Sync Groups](../identity.md) for the full reference.
 
-## 1. Schema — declare the relationship, once
+## 1. Schema: declare the relationship, once
 
 ```ts
 import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
@@ -44,7 +44,7 @@ export const schema = defineSchema(
 );
 ```
 
-## 2. Dispatch — narrow the agent to the workspace it's working on
+## 2. Dispatch: narrow the agent to the workspace it's working on
 
 An agent can never reach more than the user who triggered it — that's the upper
 limit. From there you narrow it to a single workspace by minting the agent's session
@@ -95,7 +95,7 @@ const ablo = Ablo({
 groups the session asks for with the groups the identity is actually allowed, so
 the agent can never reach a workspace its triggering user couldn't.
 
-## 3. Write — it fans out to everyone on that workspace
+## 3. Write: it fans out to everyone on that workspace
 
 Inside any component under the provider, grab the scoped client with `useAblo()`
 and write. The connection is already narrowed to `workspace:<workspaceId>` from Step 2.

package/docs/examples/server-agent.md

@@ -38,7 +38,7 @@ const ablo = Ablo({
 export async function completeTask(taskId: string) {
   await ablo.ready();
 
-  const task = await ablo.tasks.retrieve({ id: taskId });
+  const task = await ablo.tasks.get({ id: taskId });
   if (!task) return { status: 'not_found' };
 
   await using claim = await ablo.tasks.claim({
@@ -58,7 +58,7 @@ export async function completeTask(taskId: string) {
 }
 ```
 
-`retrieve({ id })` is an async server read — it hits the server and returns the
+`get({ id })` is an async server read — it hits the server and returns the
 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.

package/docs/groups.md

@@ -38,6 +38,56 @@ 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
@@ -206,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 premise, 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 blocks 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

@@ -65,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
 
@@ -99,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:
 
-- the actor that wrote,
-- the human or system the actor worked on behalf of,
-- the model, operation, and state cursor.
+```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.
+
+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

@@ -10,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.local.retrieve('task_42');
+const task = ablo.tasks.local.get('task_42');
 ```
 
-## The mental model — read this once
+## The mental model: read this once
 
 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.
@@ -37,17 +37,41 @@ one API, and Ablo 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.get`/`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.
@@ -82,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.local.retrieve('task_42');
+const task = ablo.tasks.local.get('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.local.retrieve('task_42'); // read after claiming, not from memory
+const latest = ablo.tasks.local.get('task_42'); // read after claiming, not from memory
 await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
 ```
 

package/docs/idempotency.md

@@ -35,10 +35,10 @@ The key is not a lookup that happens before the write — it is the **execution
 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
+- **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.
+- **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.
@@ -52,7 +52,7 @@ same key string without colliding, and one agent can never replay another's resu
 |---|---|
 | 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, 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
@@ -60,7 +60,7 @@ 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
+## 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.
@@ -106,7 +106,7 @@ may already have committed. Restore the original route and retry the same key.
 | 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. |
+| `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. |