@abloatai/ablo 0.57.0 → 0.59.0

package/docs/faq.md

@@ -0,0 +1,75 @@
+# FAQ
+
+> Short answers to the implementation choices developers encounter most often.
+
+## Does Ablo replace PostgreSQL?
+
+No. PostgreSQL remains the durable source of truth. Keep its schema, constraints,
+transactions, row-level security, and short write locks. Ablo coordinates work
+around that state and can route guarded writes into it.
+
+## Does Ablo replace Redis locks?
+
+It can replace an application-owned reservation layer, but it does not require a
+rewrite. Ablo standardizes resource identity, participant identity, leases,
+waiting, recovery, stale-work rejection, and visibility. Teams can begin by
+coordinating an existing operation while its final transaction remains in the
+application.
+
+## Is Ablo only for agents?
+
+No. Agents, workers, application services, and people can coordinate over the
+same resources. The package-root client is suited to stateless server work; the
+[React client](./react.md) adds live state and presence for human interfaces.
+
+## Which client should I import?
+
+Use the default export from `@abloatai/ablo` for agents, workers, route handlers,
+and server operations. It uses ordinary request/response HTTP. Use
+`@abloatai/ablo/react` when a live interface needs local synchronized state,
+subscriptions, or presence.
+
+## What is the difference between get and read?
+
+`get({ id })` observes the current row. `read({ id })` captures the exact row
+version as evidence for a later guarded write. Pass that returned row in the
+mutation's `reads` array when the decision must be rejected if its premise
+changed.
+
+## When should I claim a resource?
+
+Claim before slow or expensive work when another participant should not perform
+conflicting work on the same business resource. Do not add a claim to every
+write: a short, independent update can use its normal database and mutation
+semantics.
+
+## Is a claim a database lock?
+
+No. A claim is a participant-scoped lease held across work that may outlive one
+database transaction. It expires after heartbeat loss. PostgreSQL locks still
+protect the short authoritative transaction.
+
+## What if code writes directly to PostgreSQL?
+
+Ablo observes the resulting change through the configured data source, but the
+writer bypasses Ablo claims and request ordering. Keep database constraints for
+rules that must apply to every writer.
+
+## Are retries exactly once?
+
+Ablo idempotency deduplicates the same Ablo request within its retention window.
+It does not make external side effects exactly once. Use the external provider's
+idempotency mechanism or an application-owned effect record.
+
+## Does Ablo run long workflows?
+
+No. Temporal, Inngest, queues, and application workers still own scheduling,
+retries, and durable workflow progress. Ablo coordinates the shared state those
+executions read and change.
+
+## Do I need to understand fencing first?
+
+No. Start from the public behavior: a claim expires, another participant can
+take over, and an obsolete owner cannot use an old claim to commit through Ablo.
+The implementation mechanism is documented for operators and advanced
+integrations, not required for basic SDK use.

package/docs/groups.md

@@ -17,30 +17,28 @@ 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.
 
-The recipe is one field on the commit: declare the group you read as a premise,
-and say what should happen if it moved.
+The recipe is one field on the commit: declare the group you read as a premise.
 
 ```ts
 // The agent read everything under workspace:abc to compose this write.
 await ablo.blocks.update({
   id: 'block-C',
   data: { text: revised },
-  reads: [{ group: 'workspace:abc', readAt: watermark, onStale: 'notify' }],
+  reads: [{ group: 'workspace:abc', readAt: watermark }],
 });
 ```
 
 At commit, inside the write transaction, the engine asks a single question: *did
 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
-`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.
+write applies. If something moved, Ablo rejects the batch with a `409`, so the
+agent can re-read `workspace:abc`, regenerate, and submit a fresh guarded
+write. 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
+Three channels carry "something changed", and they answer three different
 questions. Pick by the question you have.
 
 ```ts
@@ -52,10 +50,9 @@ await using room = await ablo.records.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.records.track({ id: 's-1' });
+const record = await ablo.records.read({ id: 's-1' });
+if (!record) throw new Error('Record not found');
+await ablo.blocks.update({ id, data, reads: [record] });
 ```
 
 | Question | Channel | Arrives |
@@ -63,29 +60,12 @@ await ablo.records.track({ id: 's-1' });
 | 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 |
-| Stop me writing if it has | `track` with `onStale: 'reject'` | Refuses that commit, at the chokepoint |
-
-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.
+WebSocket client. `reads` rides the commit, so it reaches a socketless actor over
+HTTP too. The row returned by `read` privately carries its model, id, and
+watermark; passing that row in `reads` is enough to protect a later write. Ablo
+does not retain the row contents as read evidence.
 
 ---
 
@@ -158,13 +138,12 @@ Two consequences worth designing around:
 ## Declaring the batch premise
 
 `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.
+each governs the *whole* commit: if one goes stale, every write in the batch
+rejects. You choose the granularity per entry.
 
 ```ts
 reads: [
-  { group: 'workspace:abc', readAt: N, onStale: 'notify' },      // did anything in the workspace move?
+  { group: 'workspace:abc', readAt: N },                         // did anything in the workspace move?
   { model: 'Document', id: 's-1', readAt: N, fields: ['title'] }, // did this row (this field) move?
 ]
 ```
@@ -175,108 +154,9 @@ literal: this object, optionally these fields. A row premise with `fields`
 conflicts only on real field overlap, so two actors editing disjoint fields of
 the same row don't collide.
 
-`onStale` has three settings, defaulting to `reject`:
-
-- **`notify`** holds every write in the batch and returns a `StaleNotification`.
-  For a group premise it carries the group name and the new watermark
-  (`observedSyncId`); re-read the group at that point and regenerate. This is the
-  setting a chain wants — the actor gets the truth and resolves it.
-- **`reject`** aborts the batch with a `stale_context` error (`409`). The right
-  default when there is nothing to reconcile and the write should simply not
-  land.
-- **`overwrite`** skips the check and lets the write land — last-write-wins, the
-  explicit escape hatch.
-
----
-
-## Staying subscribed across commits: `track`
-
-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
-premise it would have declared is stale, and there was no commit in between on
-which to hear that the ground had shifted.
-
-`track` is the durable half of the same idea. Register what you are watching and
-it persists on the server; the next time you commit anything, a change that
-landed on the tracked target since you registered rides back on your receipt —
-the same `StaleNotification` an `onStale: 'notify'` premise would have handed
-you, arriving on the write you were going to make anyway.
-
-```ts
-// Register interest and walk away — no write required.
-await ablo.records.track({ id: 's-1' });
-
-// …minutes of other work later, on your next commit…
-const res = await ablo.blocks.update({ id: 'block-C', data: { text: revised } });
-res.notifications; // populated if s-1 moved under you in the meantime
-```
-
-The target is a row (`{ id }` on the model verb) or a sync group (as a write
-option, below). A track is an idempotent registration: calling it again refreshes
-the same subscription rather than stacking duplicates, and once a change fires the
-track re-baselines, so the same change notifies once. Your own writes to a target
-you track never notify you — the signal is about what *others* did.
-
-You can also register a track as part of a write you are already making, the
-persisted companion to `reads`:
-
-```ts
-await ablo.records.update({
-  id: 's-1',
-  data: { title: revised },
-  reads: [{ group: 'workspace:abc', readAt: N, onStale: 'notify' }], // guards THIS commit
-  track: [{ group: 'workspace:abc' }],                               // and keeps watching after it
-});
-```
-
-So `reads` is the premise for the commit in hand; `track` is a standing
-subscription that outlives it. Both speak the same notification vocabulary.
-Delivery is on your next commit's receipt; a track does not yet push out of band
-between commits.
-
-### Reporting, or gating: `onStale`
-
-A track says what a moved belief should do to your **next write**. Same enum the
-`reads` premise carries, minus the one mode that cannot apply:
-
-```ts
-await ablo.records.track({ id: 's-1' });                        // notify (default)
-await ablo.records.track({ id: 's-1', onStale: 'reject' });     // gate
-```
-
-- **`notify`** — the change rides your next receipt and the commit proceeds. You
-  decide what it means.
-- **`reject`** — your next commit is **refused** while that belief is stale, even
-  if it writes an unrelated row. The gate is on what you *know*, not on what you
-  are touching.
-
-`reject` is for an actor that must not act on a stale picture — an agent that
-read a row, reasoned for minutes, and is about to write based on what it
-believed. Ablo enforces it at the commit chokepoint, so it is a guarantee rather
-than a convention: the write cannot land.
-
-The gate takes a key. It does **not** reopen on its own, because an agent that
-retried blindly would land exactly the write `reject` was asked to prevent. You
-re-read, then re-register the track to say so:
-
-```ts
-try {
-  await ablo.records.update({ id, data });
-} catch (err) {
-  if (err.code === 'stale_context') {
-    const fresh = await ablo.records.get({ id: 's-1' });   // read
-    await ablo.records.track({ id: 's-1', onStale: 'reject' }); // acknowledge
-    await ablo.records.update({ id, data: reconsider(fresh) });     // now it lands
-  }
-}
-```
-
-A track-only call is never gated, so acknowledging is always reachable.
-
-`overwrite` is not offered: it means "apply my write anyway", and a track guards
-no write of its own to apply.
+Any stale premise aborts the batch with `stale_context` (`409`). Re-read and
+regenerate if the work is still relevant. Omit `reads` only when the write is
+intentionally unconditional.
 
 ---
 

package/docs/guarantees.md

@@ -44,11 +44,11 @@ The server remains the source of truth.
 
 ## Stale-Write Protection
 
-Use `snapshot(...)` and `readAt` when a write depends on state the agent already
-read:
+Use `read(...)` and carry the returned row in `reads` when a write depends on
+state the agent already read:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('report missing');
 
 await ablo.weatherReports.update({
@@ -67,7 +67,7 @@ not acquire this guarantee.
 
 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
+back an `AbloStaleContextError` so the actor can re-read and reconcile
 and re-issue; the rest of the batch still commits.
 
 See [Concurrency Convention](./concurrency-convention.md) for the full taxonomy,
@@ -96,10 +96,10 @@ claim queues fairly behind the holder).
 
 By default, a held claim rejects writes from other participants to the claimed
 target. Contenders that call `claim` wait their turn; ordinary reads remain
-open. An explicit model conflict policy can choose another disposition for a
-participant kind. While you hold a claim, the matching
-`ablo.<model>.update({ id, ... })` is rejected with `AbloStaleContextError` if
-the row changed underneath you after your claim point.
+open. While you hold a claim, the matching
+`ablo.<model>.update({ id, ..., claim })` proves ownership at write time and is
+rejected with `AbloStaleContextError` if the row changed underneath you after
+your claim point. Do not omit `claim` from a row-backed claimed write.
 
 ## Agent Runs
 

package/docs/idempotency.md

@@ -2,6 +2,9 @@
 
 > Make a retried write safe: the same key never applies the same change twice.
 
+This page owns idempotency for updates and retries, including changed intent
+and the `idempotency_conflict` failure code.
+
 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.
 

package/docs/identity.md

@@ -410,7 +410,7 @@ it to the provider:
 
 ```ts
 // lib/ablo.ts
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // Build the client from the identity your server already resolved.
@@ -505,6 +505,7 @@ subset of what its user could see:
 // (the floor). Build each group from the model's scope with `syncGroup(kind, id)`.
 const session = await server.sessions.create({
   agent: { id: agentId },
+  onBehalfOf: { user: { id: triggeringUser.id } },
   can: { Document: ['read', 'update'], Workspace: ['read', 'update'] },
   syncGroups: [syncGroup('document', recordId), syncGroup('workspace', workspaceId)],
 });

package/docs/implement.md

@@ -0,0 +1,61 @@
+# Choose the Ablo operation
+
+> Find one implementation route from the work you are doing, copy its smallest recipe, and open guarantee details only when you need recovery behavior.
+
+Do not read the documentation front to back. Start with the operation your
+application already has, then use one row below.
+
+| What you are implementing | Start here | Add only when |
+|---|---|---|
+| Get one row by id or list rows with the installed client | [Basic usage](./basic-usage.md) | Use `read`, not `get`, only when a later Ablo write depends on that exact row. |
+| Configure a stateless worker's identity, permissions, or lifecycle | [Agents](./agents.md) | Keep the worker on HTTP; live human interfaces use React. |
+| Wrap an existing API, service, Postgres transaction, filesystem write, or Git merge | [Coordinate existing work](./coordinate-existing-work.md) | Keep the final write in its existing owner. |
+| Expose an existing named operation through GraphQL.js | [GraphQL.js](./approaches/graphql/graphql-js.md) | Keep the resolver dependent on that operation, not directly on Ablo. |
+| Hold an Ablo model row while slow work runs, then write it through Ablo | [Coordination](./coordination.md) | Pass the returned claim handle to the write. |
+| Reject a write when an earlier decision input changed | [Concurrency convention](./concurrency-convention.md) | Pass the exact object returned by `read` through `reads`. |
+| Apply several Ablo writes all-or-none | [Atomic commits](./api.md#atomic-commits) | Put every operation and every captured premise in one `commits.create`. |
+| Make a retried Ablo write safe | [Idempotency](./idempotency.md) | Derive one key from the business event and reuse it only for the identical request. |
+| Send email, charge money, call a provider, or write a file | Keep that effect in the application | Use the provider's key or an application outbox; an Ablo key covers only the Ablo mutation. |
+| Add a live human interface | [React](./react.md) | Humans use the WebSocket/live plane; stateless workers stay on HTTP. |
+
+## The four choices agents most often confuse
+
+```ts
+// Observe one current row. No later stale check.
+const task = await ablo.tasks.get({ id });
+
+// Declare a premise for one later Ablo write.
+const premise = await ablo.tasks.read({ id });
+if (!premise) throw new Error('task not found');
+await ablo.tasks.update({ id, data, reads: [premise] });
+
+// Hold an Ablo row across slow work. The final write goes through Ablo.
+await using claim = await ablo.tasks.claim({ id });
+await ablo.tasks.update({ id, data, claim });
+
+// Coordinate row-free work whose final write stays in the application.
+await using lease = await ablo.taskRuns.claim(id, {
+  contention: { mode: 'skip' },
+});
+if (lease) await existingTaskService.complete(id);
+```
+
+Use only one of those shapes unless the operation genuinely has both a claimed
+target and separate captured premises. Claims answer who may work; `reads`
+answer whether evidence is still current; `commits.create` answers whether
+several Ablo writes land together; the existing database transaction still
+owns atomicity for application-owned writes.
+
+## Before writing code
+
+Answer these five questions:
+
+1. Which existing operation am I preserving?
+2. Does the final write belong to Ablo or to the application?
+3. Is the coordination identity a model row or only a stable business id?
+4. Which exact rows influenced the decision?
+5. Which writes must land together?
+
+If an answer is unknown, preserve the existing operation and database boundary.
+Do not introduce claims, captured reads, or atomic commits merely because they
+exist.

package/docs/implementation-index.md

@@ -0,0 +1,20 @@
+# Ablo implementation index
+
+> Route an implementation task to the smallest relevant Ablo guide before reading details.
+
+Start with [Introduction](./index.md), then [Choose the Ablo operation](./implement.md). Its one routing table
+separates ordinary reads, existing application writes, claims, captured reads,
+atomic commits, retries, GraphQL, and external effects. Do not scan every page.
+
+| Your task | Read first |
+|---|---|
+| Choose among nearby SDK and ownership patterns | [Choose the Ablo operation](./implement.md) |
+| Add Ablo to existing work without replacing its API, transaction, filesystem write, or Git merge | [Coordinate existing work](./coordinate-existing-work.md) |
+| Install Ablo and create a typed client | [Installation](./installation.md) |
+| Read, write, and coordinate shared state | [Basic usage](./basic-usage.md) |
+| Choose between a plain read, guarded read, claim, or atomic commit | [Concurrency convention](./concurrency-convention.md) |
+| Look up an exact method, option, or error type | [API reference](./api.md) |
+| Connect Ablo to an existing Postgres database | [Integration guide](./integration-guide.md) |
+
+Follow links from that page only when its routing rule applies. Examples prove a
+specific integration; they are not required reading for a first implementation.