@abloatai/ablo 0.5.1 → 0.7.0

package/docs/guarantees.md

@@ -1,6 +1,6 @@
 # Guarantees
 
-This page is the short contract for what Ablo Sync guarantees at the state
+This page is the short contract for what Ablo guarantees at the state
 boundary.
 
 ## Confirmed Writes
@@ -9,19 +9,18 @@ boundary.
 the authoritative sync cursor.
 
 ```ts
-const updated = await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+const updated = await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { wait: 'confirmed' },
 );
 ```
 
 If the call resolves, the write was accepted by the server. If it rejects, the
 error explains whether the write was rejected for auth, validation, stale state,
-active intent conflict, idempotency, rate limit, or transport failure.
+active claim conflict, idempotency, rate limit, or transport failure.
 
-Schema model writes return the updated model row. Advanced resource writes and
-`commits.create(...)` return a receipt with the commit status and sync cursor.
+Schema model writes return the updated model row.
 
 ## Optimistic Local State
 
@@ -42,11 +41,11 @@ Use `snapshot(...)` and `readAt` when a write depends on state the agent already
 read:
 
 ```ts
-const snap = ablo.snapshot({ tasks: 'task_123' });
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```
@@ -61,45 +60,30 @@ Advanced policies exist for controlled product flows:
 - `flag` accepts the write and marks it for product review.
 - `merge` is reserved for server-defined merge behavior.
 
-## Intent Coordination
+## Claim Coordination
 
-Intents are live coordination signals. They are not database locks.
+> The guarantee, not the how-to. Methods, the claim-state object, and the `queue`
+> live in [Coordination](./coordination.md).
 
-When another human or agent is active on the same target, the caller chooses the
-behavior:
+Claims are live coordination signals. They are not database locks.
 
-- `ifBusy: 'return'` returns active intents immediately.
-- `ifBusy: 'wait'` waits until the matching intent clears.
-- `ifBusy: 'fail'` throws `AbloBusyError` with the active intents attached.
+Claims are **advisory** and **cooperative**. `ablo.<model>.claim(id, ...)`
+serializes on contention: if another human or agent already holds the row, the
+claim waits for them to finish, then re-reads the row before handing it back, so
+you proceed from fresh state. Reads are open by default —
+`ablo.<model>.claimState(id)` returns the current claim state (or `null`) without
+ever blocking. Server/model reads can opt into `ifClaimed: 'wait'` or
+`ifClaimed: 'fail'` when they should not read through active work.
 
-Schema clients wait from the realtime intent stream. Schema-less HTTP callers
-must pass an explicit `busyPollInterval` if they choose `ifBusy: 'wait'`; Ablo
-does not hide a hard-coded polling loop. `busyTimeout` is only a maximum wait.
+A claim does not reject or block other writers; it announces work so peers
+serialize behind it rather than racing. While you hold a claim, the matching
+`ablo.<model>.update(id, ...)` is stale-guarded and rejects with
+`AbloStaleContextError` if the row advanced past your claim point.
 
 ## Agent Runs
 
-`agent.run(...)` is the advanced schema-less run envelope for workers that cannot
-import the app schema. It returns one of three statuses:
-
-- `done` — the handler returned successfully.
-- `failed` — the handler threw or the commit failed.
-- `cancelled` — the run signal aborted.
-
-Normal schema-backed agents should import the same schema as the app and write
-through `ablo.<model>.update(...)`. The lower-level run envelope exists for
-platform runtimes that need capability and task management without app code.
-
-## Capabilities and Tasks
-
-Capabilities scope what an agent is allowed to do. Tasks group a run for audit
-and cost attribution.
-
-Most users do not create either one manually. The SDK and hosted API manage the
-common case. Manual capability and task APIs are for platform builders, custom
-agent runtimes, and internal infrastructure.
-
-Use `lease` as a crash cleanup window. A successful agent run still closes when
-the handler returns, fails, or is cancelled.
+Agents should import the same schema as the app and write through
+`ablo.<model>.claim(...)` plus `ablo.<model>.update(...)`.
 
 ## Audit Trail
 
@@ -107,19 +91,17 @@ Accepted writes can be attributed to:
 
 - the actor that wrote,
 - the human or system the actor worked on behalf of,
-- the capability that scoped the write,
-- the task or run that caused it,
-- the resource, operation, and state cursor.
+- the model, operation, and state cursor.
 
 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?"
 
 ## Persistence
 
-Ablo defaults to volatile local persistence. That keeps the SDK focused on
+Ablo defaults to volatile in-memory persistence. That keeps the SDK focused on
 coordination and audit instead of silently becoming a browser storage product.
 
-Opt into durable browser cache and offline queueing when you need it:
+Opt into a durable browser cache that survives reloads when you need it:
 
 ```ts
 const ablo = Ablo({
@@ -137,12 +119,8 @@ Ablo does not need a customer database URL. When your own database is canonical,
 Ablo calls a signed Data Source endpoint and records the coordination result for
 receipts, realtime fanout, and audit. See [Connect Your Database](./data-sources.md).
 
-## Batches
-
-Most apps should use `ablo.<model>.create/update/delete`. Use
-`commits.create(...)` only when you need a low-level batch or a schema-less
-runtime.
+## Writes
 
-Each operation in the commit carries its own target, data, stale policy, and
-idempotency context. The server validates authorization, stale state, active
-intent conflicts, and idempotency before accepting the commit.
+Use `ablo.<model>.create/update/delete` for state changes. The server validates
+authorization, stale state, active claim conflicts, and idempotency before
+accepting the write.