@abloatai/ablo 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- 9154c1b: Rename intent handle methods to a clearer claim vocabulary; add `AbloProvider` `bootstrapMode`.
+
+  BREAKING — on the model intent handle (`ablo.<model>.intent(id)`):
+  `acquire`→`claim`, `acquireOrAwait`→`claimOrWait`, `settled`→`whenFree`,
+  `release`→`finish`, `revoke`→`cancel`. The lower-level `IntentHandle` /
+  `IntentLeaseHandle` (`ablo.intents.*`) are unchanged.
+
+  Also: `AbloProvider` gains a `bootstrapMode` prop (`'full' | 'none'`) to skip the
+  baseline pull on read-light pages; `StaleContextConflict` gains an optional
+  `conflictingFields`; README + JSDoc clarity pass and a new HTTP API section.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -1,13 +1,14 @@
 # Ablo
 
-Ablo Sync is a schema-first state control layer for AI agents and collaborative apps.
+Ablo Sync is a typed sync engine for shared app state — the kind that humans,
+server code, and AI agents all edit at once.
 
-Use it when human UI, server actions, and AI agents need to edit the same typed
-state with realtime fanout, stale-write protection, active-work coordination,
-and audit.
+Reach for it when those edits need to show up everywhere in real time, not
+silently overwrite each other, expose who's working on what, and leave a record
+of who changed what.
 
 ```txt
-schema -> ablo.<model>.create/load/edit/update(...)
+schema -> ablo.<model>.create/load/update(...)
 ```
 
 ## Install
@@ -27,12 +28,13 @@ server runtimes only.
 export ABLO_API_KEY=sk_test_...
 ```
 
-Browser apps should use a scoped capability/session route through the React
-provider. Do not ship `ABLO_API_KEY` in a browser bundle.
+In the browser, connect through the React provider (`<AbloProvider>`), which
+authenticates with the signed-in user's session — never the raw API key. Do not
+ship `ABLO_API_KEY` in a browser bundle.
 
 ## Quick Start
 
-````ts
+```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
@@ -64,16 +66,17 @@ const updated = await ablo.weatherReports.update(created.id, {
 console.log({ id: updated.id, status: updated.status });
 
 await ablo.dispose();
-```c
+```
 
 Expected output:
 
 ```txt
 { id: '...', status: 'ready' }
-````
+```
 
-Pass `schema` for typed model resources. Omit it only for advanced server-side
-resource clients such as custom agents and MCP routes.
+Pass `schema` to get typed models like `ablo.weatherReports.update(...)`. Omit it
+only for the lower-level client used by custom agents and MCP routes that can't
+import your app's schema.
 
 Run the package example from this directory:
 
@@ -87,26 +90,29 @@ future agents, read [Integration Guide](./docs/integration-guide.md).
 
 ## AI Activity on Existing State
 
-When AI or background work will touch an existing row for more than a quick
-write, coordinate through `ablo.<model>.intent(id)` — the coordination accessor
-that sits beside `create`/`update`/`retrieve`. It returns a handle
+When AI or background work will spend real time on an existing row — not just a
+one-shot write — coordinate through `ablo.<model>.intent(id)`, the coordination
+accessor that sits beside `create`/`update`/`retrieve`. It takes the row's `id` (the same
+id you pass to `retrieve(id)` / `update(id, …)`) and returns a handle
 synchronously, so you can see who's already working on a row before you start.
 
 ```ts
-const report = ablo.weatherReports.intent('weather_stockholm');
+// `report_stockholm` is this weather report's id — set at create time, or the
+// `created.id` returned above.
+const report = ablo.weatherReports.intent('report_stockholm');
 
 // Read side: is someone already on it? Wait for them to finish.
 if (report.current) {
   report.current.heldBy; // 'agent:forecaster'
-  await report.settled();
+  await report.whenFree();
 }
 
-// Write side: acquire so other participants yield while we work.
-await report.acquire({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
+// Write side: claim so other participants yield while we work.
+await report.claim({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
 
 // Your existing weather tool or agent call. While this runs, other clients see
-// that weather_stockholm is being checked.
-const row = ablo.weatherReports.retrieve('weather_stockholm');
+// that report_stockholm is being checked.
+const row = ablo.weatherReports.retrieve('report_stockholm');
 const weather = await weatherAgent.getWeather(row.location);
 
 await report.update({
@@ -117,72 +123,80 @@ await report.update({
 
 Ablo does not fetch the weather. It keeps the activity visible while the work
 runs, rejects `report.update(...)` with `AbloStaleContextError` if the row
-changed under you, and releases the intent automatically once the write lands.
+changed under you, and finishes the claim automatically once the write lands.
 
 ## Multiplayer
 
 There is no separate multiplayer mode. When human UI, server actions, and agent
-workers use the same schema client and write through `ablo.<model>`, they are on
-the same shared resource stream.
+workers share the same schema and write through `ablo.<model>`, they all see
+each other's changes in real time — that's the default, not a feature you turn on.
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row plus active intents.
 - `ablo.<model>.intent(id)` lets humans and agents see and coordinate active work before a write lands.
-- `ablo.intents` remains available for custom lower-level coordination across resources.
 
-If a team writes directly to its own database outside Ablo, that write bypasses
-the multiplayer stream until the app reports it through Data Source events.
+Always write through Ablo — the SDK (`ablo.<model>.create/update/delete`) or the
+HTTP API (`POST /v1/commits`). If you write straight to your own database
+instead, those changes won't reach connected clients. Use Ablo's endpoints and
+the fan-out is automatic.
 
 Under the hood, capabilities, tasks, leases, intents, commits, and receipts are
 real protocol primitives. They exist so agent work is scoped, coordinated,
-attributable, and cleaned up if a runtime disappears. They should not be
-ceremony in the first integration.
-
-## Load vs Retrieve
-
-For schema clients, `load` and `retrieve` are intentionally different:
-
-- `ablo.weatherReports.load({ where })` is async. It hydrates matching rows from the
-  local store and server, then returns them.
-- `ablo.weatherReports.retrieve(id)` is sync. It reads one already-loaded row from the
-  local pool and returns `undefined` if it is not loaded yet.
-- `ablo.resource('weatherReports').retrieve(id)` is the lower-level resource API. It
-  returns `{ data, stamp, intents }` for custom runtimes that need raw read
-  stamps and receipts.
-
-## Activity and Busy State
-
-Model edit activity is the live coordination signal. If another participant is
-reading, editing, or updating an entity, Ablo can return that state, wait for it
-to clear, or fail fast with `AbloBusyError`.
-
-```ts
-const busy = ablo.intents.list({
-  resource: 'weatherReports',
-  id: 'weather_stockholm',
-});
-
-if (busy.length > 0) {
-  console.log(`${busy[0].actor} is ${busy[0].action}`);
+attributable, and cleaned up if a runtime disappears — but you don't touch them
+in a first integration. The default path above is enough.
+
+## HTTP API
+
+The SDK is a typed wrapper over a signed HTTP API, the same way `stripe-node`
+wraps Stripe's REST API. Everything you do through `ablo.<model>` is reachable
+over HTTP, so backends in other languages and server-to-server callers work
+without the SDK.
+
+Writes — create, update, and delete — all go through one endpoint as a batch of
+operations:
+
+```http
+POST /v1/commits
+Authorization: Bearer sk_live_...
+Idempotency-Key: <your-unique-id>
+
+{
+  "operations": [
+    {
+      "type": "UPDATE",
+      "model": "weatherReports",
+      "id": "report_stockholm",
+      "input": { "status": "ready" },
+      "readAt": 1042,
+      "onStale": "reject"
+    }
+  ]
 }
-
-await ablo.intents.waitFor({ resource: 'weatherReports', id: 'weather_stockholm' });
 ```
 
-Policy names are literal:
+Each operation is one `CREATE` / `UPDATE` / `DELETE` (plus `ARCHIVE` /
+`UNARCHIVE`). Reads fetch a single row with `GET /v1/resources/{model}/{id}`.
+The same API key, scope, idempotency, and stale-write rules apply as in the SDK
+— the SDK just removes the boilerplate.
 
-- `ifBusy: 'return'` returns immediately with `intents`.
-- `ifBusy: 'wait'` waits on the live intent stream. Plain HTTP callers must
-  provide their own explicit polling policy instead of getting hidden SDK polling.
-- `ifBusy: 'fail'` throws `AbloBusyError` with the active intents attached.
+## Load vs Retrieve
+
+Most reads are `retrieve` — it's the everyday path, especially inside `useAblo(...)`:
+
+- `ablo.weatherReports.retrieve(id)` is sync. It returns the already-loaded row from
+  the local pool (or `undefined` if it isn't loaded yet). In React,
+  `useAblo((ablo) => ablo.weatherReports.retrieve(id))` keeps that read live.
+- `ablo.weatherReports.load({ where })` is async. Reach for it when you need to
+  guarantee a row is hydrated before you read it — initial fetch, SSR, scripts, or
+  any non-reactive runtime.
 
 ## Persistence
 
-Ablo defaults to volatile local persistence. That keeps the SDK focused on shared
-state coordination instead of silently adding an IndexedDB storage product to
-every browser app.
+Ablo keeps local state in memory by default. That keeps the SDK focused on
+coordinating shared state, rather than silently turning every browser app into
+an offline database it didn't ask for.
 
-Opt into browser durable local cache and offline queueing when you need it:
+Opt into a durable browser cache and offline write queue when you want it:
 
 ```ts
 const ablo = Ablo({
@@ -200,11 +214,16 @@ Every schema model has a backing store. By default, Ablo stores rows for the
 models you declare, so `ablo.weatherReports.create(...)` and `ablo.weatherReports.update(...)`
 write to Ablo-managed state.
 
-If your existing database remains the source of truth, connect it with a signed
-Data Source endpoint. Your app keeps the database credentials; Ablo sends signed
-commit requests to your route.
+If your existing database stays the source of truth, connect it as a Data
+Source: Ablo sends signed commit requests to an endpoint you host, and your app
+writes its own database. Ablo never sees your database credentials — only the
+API key:
 
 ```bash
+# stays in your app — Ablo never receives this
+DATABASE_URL=postgres://...
+
+# the only Ablo credential your app needs
 ABLO_API_KEY=sk_live_...
 ```
 

package/dist/BaseSyncedStore.d.ts

@@ -123,8 +123,9 @@ export interface UserContext {
      *  store routes this to SyncWebSocket so the WS URL carries
      *  `kind=agent` and the server applies capability-token auth. */
     kind?: 'user' | 'agent' | 'system';
-    /** Biscuit capability token for `kind: 'agent'`. Sent as
-     *  `?authorization=Bearer <token>` on the WS upgrade. */
+    /** Restricted (`rk_`) API key for `kind: 'agent'` — the agent's
+     *  bearer credential. Sent as `?authorization=Bearer <token>` on the
+     *  WS upgrade. (Field name predates the Biscuit→opaque-key migration.) */
     capabilityToken?: string;
     /** Server-authoritative sync groups, supplied by auth/capability
      *  exchange. The SDK does not invent org/user/default groups; app

package/dist/client/Ablo.d.ts

@@ -55,14 +55,46 @@ export interface Turn {
 export type { ApiKeySetter } from './auth.js';
 import type { ApiKeySetter } from './auth.js';
 import { type AbloPersistence } from './persistence.js';
+/**
+ * Options for `Ablo({...})`.
+ *
+ * The only required field is `schema`. The default path is one line:
+ *
+ * ```ts
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+ * ```
+ *
+ * `apiKey` itself defaults to `process.env.ABLO_API_KEY`, so in most
+ * server setups `Ablo({ schema })` is enough. Every other field is
+ * optional tuning (timeouts, retries, custom fetch, persistence) —
+ * if you're not sure whether you need one, you don't. Reach for them
+ * the way you'd reach for the equivalent option on the Stripe / OpenAI
+ * / Anthropic clients: rarely, and deliberately.
+ *
+ * @see https://docs.ablo.finance — full option reference
+ */
 export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
+    /**
+     * TypeScript schema defined with `defineSchema()`. Required — it's what
+     * makes `ablo.tasks.update(...)` typed. This is the one field you must
+     * pass; start here.
+     */
+    schema: Schema<S>;
     /**
      * API key used for authentication.
      *
      * Accepts a static string (`sk_live_...`) or an async function that
-     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`.
+     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`, so you
+     * usually don't pass this explicitly server-side.
      */
     apiKey?: string | ApiKeySetter | null | undefined;
+    /**
+     * Local persistence mode. Pass `indexeddb` only when you want offline
+     * queueing and a reload-surviving browser cache.
+     *
+     * @default 'volatile'
+     */
+    persistence?: AbloPersistence;
     /**
      * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
      * deployments may pass a bearer token minted by their own auth layer.
@@ -72,9 +104,19 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Override the Ablo API base URL. Defaults to hosted production.
      */
     baseURL?: string | null | undefined;
-    /** Per-request timeout in milliseconds. */
+    /**
+     * Maximum time (ms) to wait for a single request before timing out.
+     * Timed-out requests are retried, so worst-case wait can exceed this.
+     *
+     * @default 600_000
+     */
     timeout?: number | undefined;
-    /** Number of retries for transient failures. */
+    /**
+     * Maximum retries on transient failure (network error / 5xx / 429).
+     * Honors `Retry-After`.
+     *
+     * @default 2
+     */
     maxRetries?: number | undefined;
     /** Custom fetch implementation for tests, proxies, or non-standard runtimes. */
     fetch?: typeof fetch | undefined;
@@ -88,16 +130,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * key or a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
-    /**
-     * TypeScript schema defined with `defineSchema()`. This enables typed
-     * resources such as `ablo.tasks.update(...)`.
-     */
-    schema: Schema<S>;
-    /**
-     * Local persistence mode. Defaults to `volatile`. Pass `indexeddb` only
-     * when you want offline queueing and a reload-surviving browser cache.
-     */
-    persistence?: AbloPersistence;
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**

package/dist/client/createModelProxy.d.ts

@@ -104,7 +104,7 @@ export interface ModelCollaboration<T> {
     }, options?: IntentWaitOptions): Promise<void>;
     /**
      * The local participant's id. Used to distinguish "I already hold this"
-     * from "someone else holds it" in `acquireOrAwait`.
+     * from "someone else holds it" in `claimOrWait`.
      */
     readonly selfParticipantId: string;
 }
@@ -120,13 +120,25 @@ export interface ModelIntentAcquireOptions {
     wait?: MutationOptions['wait'];
 }
 /**
- * Per-entity coordination handle — the same accessor shape as
- * `create`/`update`/`retrieve`, but on the coordination plane. Returned
- * synchronously by `ablo.<model>.intent(id)` so a contender can read
- * `.current` without awaiting; `acquire()` is the async lock.
+ * Per-entity coordination handle, returned synchronously by
+ * `ablo.<model>.intent(id)`. It lets humans and agents claim a row before
+ * they work on it, so two of them don't edit the same thing at once.
  *
- * Read side (any participant): `current`, `status`, `settled()`.
- * Write side (the holder): `acquire()`, `update()`, `release()`.
+ * The lifecycle reads like a sentence:
+ *
+ * ```ts
+ * const report = ablo.weatherReports.intent('weather_stockholm');
+ *
+ * if (report.current) await report.whenFree(); // someone's on it — wait
+ * await report.claim({ action: 'checking_weather' }); // it's mine now
+ * await report.update({ status: 'ready' });    // write, then auto-finish
+ * ```
+ *
+ * `current` is the live `Intent` (or `null` if free). `claim()` announces
+ * you're working so others yield. `whenFree()` waits for whoever holds it.
+ * `claimOrWait()` does both — claim, or wait your turn then claim — which
+ * is what you bind to an agent's write tool so it never reasons about
+ * coordination itself. `finish()`/`cancel()` give the claim back.
  */
 export interface ModelIntentHandle<T> extends AsyncDisposable {
     /** The target entity id this handle coordinates. */
@@ -140,39 +152,35 @@ export interface ModelIntentHandle<T> extends AsyncDisposable {
     /** Convenience: `current?.status ?? 'idle'`. */
     readonly status: IntentStatus | 'idle';
     /**
-     * Acquire the lease so other participants yield. Resolves once the
-     * claim is announced. Throws if another participant already holds it
-     * (cooperative mutex enforced at the server boundary).
+     * Claim this row so other participants yield while you work. Resolves
+     * once the claim is announced. Throws if someone else already holds it
+     * — call `whenFree()` first, or use `claimOrWait()` to do both.
      */
-    acquire(options?: ModelIntentAcquireOptions): Promise<void>;
+    claim(options?: ModelIntentAcquireOptions): Promise<void>;
     /**
-     * Acquire the target, or — if another participant holds it — wait for
-     * them to finish, re-read the (now-changed) row, then acquire. This is
-     * the runtime's serialize-on-contention primitive: the caller never
-     * branches on who holds the target, it just gets the target safely.
-     *
-     * A claim held by *this* participant is treated as already-mine and
-     * acquired without waiting. Bind this to an agent's write-tool boundary
-     * so agents never reason about coordination themselves.
+     * Claim the row, or — if someone else holds it — wait for them to
+     * finish, re-read the (now-changed) row, then claim. The caller never
+     * branches on who holds it; it just gets the row safely. A claim you
+     * already hold is treated as yours and taken without waiting. Bind this
+     * to an agent's write-tool boundary.
      */
-    acquireOrAwait(options?: ModelIntentAcquireOptions): Promise<void>;
+    claimOrWait(options?: ModelIntentAcquireOptions): Promise<void>;
     /**
-     * Optimistic update guarded by the lease this handle holds. Rejects
+     * Optimistic update guarded by the claim this handle holds. Rejects
      * with `AbloStaleContextError` if the row changed under you, then
-     * auto-releases. Call `acquire()` first.
+     * auto-finishes. Call `claim()` first.
      */
     update(data: Partial<T>, options?: MutationOptions): Promise<T>;
-    /** Release a lease you hold (commit / abandon). */
-    release(): Promise<void>;
+    /** Finish: give back a claim you hold once the work is committed. */
+    finish(): Promise<void>;
     /**
-     * Wait until the target is free, then resolve. The contender's
-     * "let me wait until it completes." On resolution your cached copy may
-     * be stale — re-read before writing (the stale-context guard enforces
-     * this if you go through `acquire().update()`).
+     * Wait until the row is free, then resolve. On resolution your cached
+     * copy may be stale — re-read before writing (the stale-context guard
+     * enforces this if you go through `claim()` + `update()`).
      */
-    settled(options?: IntentWaitOptions): Promise<void>;
-    /** Drop a held lease without committing. */
-    revoke(): void;
+    whenFree(options?: IntentWaitOptions): Promise<void>;
+    /** Cancel: drop a claim you hold without committing any work. */
+    cancel(): void;
 }
 export interface ModelOperations<T, CreateInput> {
     /**
@@ -206,14 +214,14 @@ export interface ModelOperations<T, CreateInput> {
      * Coordination accessor for one entity — the same `ablo.<model>(id)`
      * shape as `create`/`update`/`retrieve`, but on the coordination plane
      * (ephemeral, TTL'd, never persisted). Returns a handle synchronously:
-     * read `.current` to see who's editing, `acquire()` to lock, `update()`
-     * to write under the lock, `settled()` to wait for a holder to finish.
+     * read `.current` to see who's editing, `claim()` to take it, `update()`
+     * to write under the claim, `whenFree()` to wait for a holder to finish.
      *
      * ```ts
      * const lock = ablo.slide.intent(slideId);
-     * if (lock.current) await lock.settled();   // someone's editing — wait
-     * await lock.acquire({ action: 'editing' });
-     * await lock.update({ title: 'New' });      // auto-releases
+     * if (lock.current) await lock.whenFree();   // someone's editing — wait
+     * await lock.claim({ action: 'editing' });
+     * await lock.update({ title: 'New' });       // auto-finishes
      * ```
      */
     intent(id: string): ModelIntentHandle<T>;

package/dist/client/createModelProxy.js

@@ -117,30 +117,34 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             let snapshot = null;
             let released = false;
             let acquireWait;
-            const revoke = () => {
+            // Public `cancel()` — drop the claim without committing. Calls the
+            // lower-level lease handle's `revoke()` (a different API; leave it).
+            const cancel = () => {
                 if (released)
                     return;
                 released = true;
                 if (snapshot)
-                    snapshot.signal.removeEventListener('abort', revoke);
+                    snapshot.signal.removeEventListener('abort', cancel);
                 acquired?.revoke();
             };
-            const release = async () => {
+            // Public `finish()` — give the claim back after committing. Calls the
+            // lower-level lease handle's `release()` (a different API; leave it).
+            const finish = async () => {
                 if (released)
                     return;
                 released = true;
                 if (snapshot)
-                    snapshot.signal.removeEventListener('abort', revoke);
+                    snapshot.signal.removeEventListener('abort', cancel);
                 await acquired?.release();
             };
-            const settled = async (options) => {
+            const whenFree = async (options) => {
                 if (!collaboration)
                     return;
                 await collaboration.waitFor(target, options);
             };
-            const acquire = async (options) => {
+            const claim = async (options) => {
                 if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot acquire an intent without collaboration wiring.`, { code: 'model_intent_not_configured' });
+                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim an intent without collaboration wiring.`, { code: 'model_intent_not_configured' });
                 }
                 if (acquired)
                     return;
@@ -155,7 +159,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
                 }
                 const snap = collaboration.createSnapshot(schemaKey, id);
-                snap.signal.addEventListener('abort', revoke, { once: true });
+                snap.signal.addEventListener('abort', cancel, { once: true });
                 snapshot = snap;
                 released = false;
                 acquired = await collaboration.createIntent({
@@ -168,18 +172,18 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     ttl: options?.ttl,
                 });
             };
-            const acquireOrAwait = async (options) => {
+            const claimOrWait = async (options) => {
                 if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot acquire an intent without collaboration wiring.`, { code: 'model_intent_not_configured' });
+                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim an intent without collaboration wiring.`, { code: 'model_intent_not_configured' });
                 }
                 const held = collaboration.observe(target);
-                // A foreign holder: wait for release, then re-read before claiming.
-                // Our own claim (or a free target) skips straight to acquire.
+                // A foreign holder: wait for them to finish, then re-read before
+                // claiming. Our own claim (or a free target) goes straight to claim.
                 if (held && held.heldBy !== collaboration.selfParticipantId) {
-                    await settled();
+                    await whenFree();
                     await load({ where: { id } });
                 }
-                await acquire(options);
+                await claim(options);
             };
             const handle = {
                 id,
@@ -189,11 +193,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 get status() {
                     return collaboration?.observe(target)?.status ?? 'idle';
                 },
-                acquire,
-                acquireOrAwait,
+                claim,
+                claimOrWait,
                 async update(data, updateOptions) {
                     if (!acquired || !snapshot) {
-                        throw new AbloValidationError(`Call acquire() before update() on ablo.${schemaKey}.intent(${id}).`, { code: 'intent_not_acquired' });
+                        throw new AbloValidationError(`Call claim() before update() on ablo.${schemaKey}.intent(${id}).`, { code: 'intent_not_acquired' });
                     }
                     if (snapshot.signal.aborted) {
                         throw new AbloStaleContextError(`Intent context is stale for ${schemaKey}/${id}. Re-read the row and retry.`, {
@@ -212,13 +216,13 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         });
                     }
                     finally {
-                        await release();
+                        await finish();
                     }
                 },
-                release,
-                settled,
-                revoke,
-                [Symbol.asyncDispose]: release,
+                finish,
+                whenFree,
+                cancel,
+                [Symbol.asyncDispose]: finish,
             };
             return handle;
         },

package/dist/client/index.d.ts

@@ -20,7 +20,7 @@
  * ```
  *
  * For headless agents (workers, bots), pass `kind: 'agent'` plus a
- * Biscuit `capabilityToken`:
+ * restricted (`rk_`) API key as `capabilityToken`:
  *
  * ```ts
  * const bot = Ablo({

package/dist/client/index.js

@@ -20,7 +20,7 @@
  * ```
  *
  * For headless agents (workers, bots), pass `kind: 'agent'` plus a
- * Biscuit `capabilityToken`:
+ * restricted (`rk_`) API key as `capabilityToken`:
  *
  * ```ts
  * const bot = Ablo({

package/dist/errors.d.ts

@@ -186,16 +186,18 @@ export interface CommitReceipt {
     };
 }
 /**
- * Biscuit capability token failed verification — either it's
- * malformed / unknown / revoked (`capability_invalid`), or its
- * caveats deny the attempted action (`capability_scope_denied`).
+ * A scoped credential was denied — either the key is unknown / revoked /
+ * expired (`capability_invalid`), or the connection's resolved scope
+ * doesn't cover the attempted action (`capability_scope_denied`). With
+ * opaque restricted (`rk_`) API keys this is a server-side check against
+ * the key's `syncGroups` / `operations`, not a signed-caveat verification.
  *
  * Extends `AbloPermissionError` so existing `instanceof CapabilityError`
  * checks keep working AND broader `instanceof AbloPermissionError`
- * matches for consumers who don't care about the Biscuit specifics.
+ * matches for consumers who don't care about the scope specifics.
  *
- * `requiredCapability` (when present) describes what an attenuated
- * capability must satisfy for the request to succeed on retry.
+ * `requiredCapability` (when present) describes the scope a key must
+ * carry for the request to succeed on retry.
  */
 export declare class CapabilityError extends AbloPermissionError {
     readonly requiredCapability?: RequiredCapability;

package/dist/errors.js

@@ -125,16 +125,18 @@ export class AbloBusyError extends AbloError {
     }
 }
 /**
- * Biscuit capability token failed verification — either it's
- * malformed / unknown / revoked (`capability_invalid`), or its
- * caveats deny the attempted action (`capability_scope_denied`).
+ * A scoped credential was denied — either the key is unknown / revoked /
+ * expired (`capability_invalid`), or the connection's resolved scope
+ * doesn't cover the attempted action (`capability_scope_denied`). With
+ * opaque restricted (`rk_`) API keys this is a server-side check against
+ * the key's `syncGroups` / `operations`, not a signed-caveat verification.
  *
  * Extends `AbloPermissionError` so existing `instanceof CapabilityError`
  * checks keep working AND broader `instanceof AbloPermissionError`
- * matches for consumers who don't care about the Biscuit specifics.
+ * matches for consumers who don't care about the scope specifics.
  *
- * `requiredCapability` (when present) describes what an attenuated
- * capability must satisfy for the request to succeed on retry.
+ * `requiredCapability` (when present) describes the scope a key must
+ * carry for the request to succeed on retry.
  */
 export class CapabilityError extends AbloPermissionError {
     requiredCapability;

package/dist/index.d.ts

@@ -26,6 +26,20 @@
  * Consumer code should converge on `ablo.<model>.load(...)`, which routes
  * through the engine's `HydrationCoordinator` and dedupes single-flight
  * hydrations.
+ *
+ * ── What to import (read this first) ────────────────────────────────
+ * Default path — this is all most apps and agents ever need:
+ *   • `Ablo` (default export) + `AbloOptions` + the `Model*Options` bags
+ *   • the `Ablo*Error` classes, to discriminate failures in catch blocks
+ * That's it. If you're reaching past those, you're in advanced territory.
+ *
+ * Advanced — opt-in, most apps never import these (each is tagged
+ * "Advanced —" at its export below, with the one situation it's for):
+ *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
+ *   • `session` / `agent`          — only for delegated agent principals
+ *   • `defaultPolicy`              — only to customize conflict resolution
+ *   • `defineMutators` / `createTransaction` — only for custom mutators
+ * If you don't recognize one, you don't need it — the default path covers you.
  */
 export { Ablo } from './client/Ablo.js';
 export type { AbloOptions, ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelIntentHandle, ModelIntentAcquireOptions, ModelOperations, } from './client/Ablo.js';

package/dist/index.js

@@ -26,6 +26,20 @@
  * Consumer code should converge on `ablo.<model>.load(...)`, which routes
  * through the engine's `HydrationCoordinator` and dedupes single-flight
  * hydrations.
+ *
+ * ── What to import (read this first) ────────────────────────────────
+ * Default path — this is all most apps and agents ever need:
+ *   • `Ablo` (default export) + `AbloOptions` + the `Model*Options` bags
+ *   • the `Ablo*Error` classes, to discriminate failures in catch blocks
+ * That's it. If you're reaching past those, you're in advanced territory.
+ *
+ * Advanced — opt-in, most apps never import these (each is tagged
+ * "Advanced —" at its export below, with the one situation it's for):
+ *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
+ *   • `session` / `agent`          — only for delegated agent principals
+ *   • `defaultPolicy`              — only to customize conflict resolution
+ *   • `defineMutators` / `createTransaction` — only for custom mutators
+ * If you don't recognize one, you don't need it — the default path covers you.
  */
 // ── Consumer API ──────────────────────────────────────────────────────────
 // These are the only symbols external consumers should need from this path.
@@ -39,24 +53,27 @@ export { Ablo } from './client/Ablo.js';
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
 // `Ablo.Peer`, `Ablo.Claim`, `Ablo.Turn`. No flat re-exports.
-// Principal constructors — explicit factories for delegation paths
-// (`Ablo({ kind: 'agent', as: session({...}) })`). Function exports
-// because they're constructors, not types.
+// Advanced — most apps never import this. Principal constructors for
+// delegated agent paths (`Ablo({ kind: 'agent', as: session({...}) })`).
+// The default `Ablo({ schema, apiKey })` resolves identity from the key;
+// reach for these only when minting a delegated agent principal.
 export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
-// Customer-owned storage adapter. Used only when Ablo Cloud coordinates
-// state while canonical rows remain in the customer's database. Runtime
-// helpers ship flat; type counterparts live under `Ablo.Source.*`
-// (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`, etc.).
+// Advanced — most apps never import this. Customer-owned storage adapter
+// for Data Source mode: only when Ablo Cloud coordinates state while
+// canonical rows stay in YOUR database. The default is Ablo-managed
+// storage — if you haven't deliberately chosen to keep your own DB
+// canonical, skip this entirely. Type counterparts live under
+// `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
 export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 // Schema DSL is intentionally published from `@abloatai/ablo/schema`.
 // Keeping it out of the root import preserves one clean runtime surface:
 // `import Ablo from '@abloatai/ablo'`.
-// Conflict policy — `defaultPolicy` (the rejecting default) is a value
-// callers reference if they want to compose. The type counterparts
-// (`Conflict`, `ConflictPolicy`, etc.) live under `Ablo.Conflict`,
-// `Ablo.Conflict.Policy` on the namespace.
+// Advanced — most apps never import this. Conflict policy: `defaultPolicy`
+// (reject-on-stale) is already applied server-side, so you only import it
+// to COMPOSE a custom policy. Leave it alone and stale writes are rejected
+// safely by default. Type counterparts live under `Ablo.Conflict.*`.
 export { defaultPolicy } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
@@ -66,8 +83,10 @@ export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionErr
 // Intents/UserMeta once in a `.d.ts` via `declare global { interface AbloSync
 // { ... } }`. Resolver types live under the `Ablo` namespace —
 // `Ablo.ResolveSchema`, `Ablo.ResolvePresence`, etc. — pure type-level.
-// Custom mutators — runtime entry point only.
-// Type counterparts moved to the `Ablo` namespace:
+// Advanced — most apps never import this. Custom (Zero-style) mutators:
+// `ablo.<model>.create/update/delete` already covers normal writes. Reach
+// for `defineMutators` only when you need a named, multi-step mutation with
+// custom undo. Type counterparts live under the `Ablo` namespace:
 //   Ablo.Mutator.Fn, Ablo.Transaction
 //   Ablo.Mutator.UndoEntry, Ablo.Mutator.InverseOp
 //   Ablo.Query, Ablo.QueryBatch, Ablo.QueryBatchResult

package/dist/policy/types.d.ts

@@ -29,6 +29,16 @@ export interface StaleContextConflict extends ConflictBase {
     readonly readAt: number;
     /** Most recent delta id on the target. */
     readonly observedSyncId: number;
+    /**
+     * The fields whose concurrent change triggered this conflict — the
+     * intersection of the committer's written fields and the columns a
+     * newer delta touched. Empty array means the conflicting delta was a
+     * whole-entity change (CREATE/DELETE, or a pre-`changed_fields`
+     * legacy delta), which conflicts with any write. Lets a policy decide
+     * at field granularity, e.g. allow when the only collision is on a
+     * cosmetic field. See `docs/internal/per-field-conflict-detection.md`.
+     */
+    readonly conflictingFields?: readonly string[];
 }
 export interface IntentHeldConflict extends ConflictBase {
     readonly kind: 'intent_held';

package/dist/principal.d.ts

@@ -18,8 +18,8 @@
  * participant layer handles attenuation.
  *
  * These are pure — no I/O, no hidden state. If the shape ever grows a
- * required field (say, a Biscuit scope hint), the helper is the one
- * place to flag migrations.
+ * required field (say, a scope hint for the restricted key), the helper
+ * is the one place to flag migrations.
  */
 import type { AgentRef, SessionRef } from './types/streams.js';
 /**

package/dist/principal.js

@@ -18,8 +18,8 @@
  * participant layer handles attenuation.
  *
  * These are pure — no I/O, no hidden state. If the shape ever grows a
- * required field (say, a Biscuit scope hint), the helper is the one
- * place to flag migrations.
+ * required field (say, a scope hint for the restricted key), the helper
+ * is the one place to flag migrations.
  */
 /**
  * Build a `SessionRef` from the identifiers your auth system already

package/dist/query/client.d.ts

@@ -22,13 +22,14 @@ export interface PostQueryOptions {
     /** Timeout in ms for the fetch request. Default: 30000. */
     fetchTimeout?: number;
     /**
-     * Capability token (Biscuit) to attach as `Authorization: Bearer <token>`.
-     * Required for Node consumers (agent-worker, server-side tests) that
-     * have no session cookie to ride. Browser consumers can omit this and
-     * fall back to `credentials: 'include'`. When both are present the
-     * server prefers the Bearer header (see `agentTokenProvider` in
+     * Bearer credential — a restricted (`rk_`) API key — attached as
+     * `Authorization: Bearer <token>`. Required for Node consumers
+     * (agent-worker, server-side tests) that have no session cookie to
+     * ride. Browser consumers can omit this and fall back to
+     * `credentials: 'include'`. When both are present the server prefers
+     * the Bearer header (see `apiKeyProvider` in
      * `apps/sync-server/src/auth`), so passing the token in browser code
-     * is harmless.
+     * is harmless. (Field name predates the Biscuit→opaque-key migration.)
      */
     capabilityToken?: string;
 }

package/dist/react/AbloProvider.d.ts

@@ -29,8 +29,29 @@ import { type SyncStoreContract } from './context.js';
  *     only when `userId` / account scope / `url` change. React
  *     Strict Mode double-mount does not leak a second WebSocket.
  */
+/**
+ * Props for `<AbloProvider>`.
+ *
+ * The default path is one prop:
+ *
+ * ```tsx
+ * <AbloProvider schema={schema}>
+ *   <App />
+ * </AbloProvider>
+ * ```
+ *
+ * That's it for most apps — the provider resolves identity, account
+ * scope, and realtime permissions from auth. `userId`/`apiKey`/`url`
+ * are situational; the `bootstrapMode`, `persistence`, and `fallback`
+ * props are opt-in tuning; and the block tagged "Optional DI (advanced)"
+ * below is escape-hatch wiring for tests and platform builders — if you
+ * don't recognize a prop there, you don't need it.
+ */
 export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
-    /** Schema from `defineSchema()`. Determines the typed hook surface. */
+    /**
+     * Schema from `defineSchema()`. Determines the typed hook surface.
+     * This is the only prop most apps pass — start here.
+     */
     schema: Schema<R>;
     /**
      * WebSocket URL of the sync server (`wss://...` or `ws://...`).
@@ -103,6 +124,28 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
      * for the full semantics.
      */
     persistence?: AbloPersistence;
+    /**
+     * How aggressively this provider pulls baseline state at startup.
+     *
+     *  - `'full'` (default): pull every delta in the configured sync
+     *    groups before the engine reports ready — a local replica of the
+     *    org's tenant plane. Right for collaborative editors and any page
+     *    that reads a lot of shared state.
+     *  - `'none'`: open the connection and process live deltas only — no
+     *    baseline fetch. Reads round-trip via `ablo.<model>.retrieve(...)`
+     *    and subscriptions populate the pool lazily. Right for read-light
+     *    pages (a mostly-static dashboard, a settings screen) that don't
+     *    want to download the whole org to render.
+     *
+     * Note: `'none'` still opens the realtime connection — it skips the
+     * baseline pull, not the socket. A fully connection-free mode for
+     * pages that do zero multiplayer is a separate follow-up (the socket
+     * open lives inside `engine.ready()`, so deferring it needs
+     * engine-level lazy-connect support, not just a provider prop).
+     *
+     * Mirrors `AbloOptions.bootstrapMode`. Changing it rotates the engine.
+     */
+    bootstrapMode?: 'full' | 'none';
     /**
      * Rendered in place of `children` during the *first* bootstrap pass —
      * while the engine is actively transitioning from `initial` →

package/dist/react/AbloProvider.js

@@ -32,7 +32,7 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, bootstrapBaseUrl, maxPoolSize, persistence, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
     // Account scope is no longer accepted from props. The engine learns
     // it from auth (capability token) at bootstrap and we read it back
     // out of `_store.orgId` once `engine.ready()` resolves.
@@ -62,6 +62,7 @@ export function AbloProvider(props) {
     const engineKey = JSON.stringify({
         userId: userId ?? null,
         url,
+        bootstrapMode: bootstrapMode ?? null,
     });
     const [engineState, setEngineState] = useState({ key: engineKey, engine: null });
     // Keep a ref to the current engine key so the rotation effect can
@@ -89,6 +90,7 @@ export function AbloProvider(props) {
             bootstrapBaseUrl,
             maxPoolSize,
             persistence,
+            ...(bootstrapMode ? { bootstrapMode } : {}),
             autoStart: false,
         };
         const engine = Ablo(engineOptions);

package/dist/sync/SyncWebSocket.d.ts

@@ -113,11 +113,12 @@ export interface SyncWebSocketOptions {
      */
     kind?: 'user' | 'agent' | 'system';
     /**
-     * Biscuit capability bearer token. When set, sent as
-     * `?authorization=Bearer+<token>` on the WS upgrade — query-param
-     * form so it works in both Node (no header support) and browsers.
-     * The server's auth path accepts either form. Required for
-     * `kind: 'agent'`; ignored for `kind: 'user'`.
+     * The agent's bearer credential — a restricted (`rk_`) API key. When
+     * set, sent as `?authorization=Bearer+<token>` on the WS upgrade —
+     * query-param form so it works in both Node (no header support) and
+     * browsers. The server's auth path accepts either form. Required for
+     * `kind: 'agent'`; ignored for `kind: 'user'`. (Field name predates
+     * the Biscuit→opaque-key migration.)
      */
     capabilityToken?: string;
 }

package/dist/types/streams.d.ts

@@ -57,7 +57,8 @@ export interface AgentDelta {
 /**
  * A reference to whoever's authority bounds a joined participant.
  * The spawned participant can never see or do more than this principal.
- * Enforced cryptographically via Biscuit attenuation.
+ * Enforced server-side: the spawned agent gets its own restricted
+ * (`rk_`) key whose scope is a subset of the parent's.
  *
  *   • `SessionRef`     — human is joining an agent (chat assistant flow)
  *   • `AgentRef`       — agent spawning a sub-agent (attenuation chain)
@@ -507,8 +508,8 @@ export interface IntentWaitOptions {
  * the fields *are* the awareness ("agent X is editing this until Y").
  *
  * Deliberately omits a Stripe-style `next_action`: a contender's only
- * response is "wait for release, then re-read", and the runtime performs
- * that uniformly at the tool boundary (`IntentHandle.settled()` + the
+ * response is "wait until free, then re-read", and the runtime performs
+ * that uniformly at the tool boundary (`IntentHandle.whenFree()` + the
  * stale-context guard that forces a re-read). Encoding a constant
  * instruction the engine always takes would be the kind of ceremony this
  * object exists to remove.

package/docs/api.md

@@ -146,20 +146,20 @@ so you can inspect who holds a target without awaiting.
 ### Lifecycle
 
 ```
-            acquire()                  update() lands
+            claim()                    update() lands
   (free) ───────────▶ active ───────────────────────▶ committed
                         │
             ┌───────────┴───────────┐
             ▼                       ▼
         canceled                 expired
-     (release w/o write)      (TTL; holder died)
+     (finish w/o write)       (TTL; holder died)
 ```
 
 A target is free when `ablo.<model>.intent(id).current` is `null`. Terminal
 states drop out of the live stream — a present intent is, by definition,
 `active`.
 
-### Reading and acquiring
+### Reading and claiming
 
 ```ts
 const task = ablo.tasks.intent('task_123');
@@ -168,21 +168,21 @@ const task = ablo.tasks.intent('task_123');
 if (task.current) {
   task.current.heldBy; // 'agent:task-writer'
   task.current.action; // 'editing'
-  await task.settled(); // wait until they finish, then continue
+  await task.whenFree(); // wait until they finish, then continue
 }
 
 // Write side — claim, write, auto-release in one flow.
-await task.acquire({ action: 'editing', field: 'status', ttl: '2m' });
+await task.claim({ action: 'editing', field: 'status', ttl: '2m' });
 const updated = await task.update({ status: 'done' });
 updated.status; // 'done'
 ```
 
 `task.update(...)` carries the same stale-check as a plain update: it rejects
-with `AbloStaleContextError` if the row advanced past your acquire point, so you
+with `AbloStaleContextError` if the row advanced past your claim point, so you
 re-read before retrying. The intent releases automatically when `update`
-resolves; call `task.release()` if the work ends without a write.
+resolves; call `task.finish()` if the work ends without a write.
 
-`task.settled({ timeout })` waits until the target is free. Pass `timeout` only
+`task.whenFree({ timeout })` waits until the target is free. Pass `timeout` only
 when your product needs an upper bound.
 
 ### Cross-resource coordination

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

@@ -35,9 +35,9 @@ const updateTask = tool({
     if (!task) return { ok: false, reason: 'not_found' };
 
     const claim = ablo.tasks.intent(taskId);
-    if (claim.current) await claim.settled({ timeout: 30_000 });
+    if (claim.current) await claim.whenFree({ timeout: 30_000 });
 
-    await claim.acquire({ action: 'editing', field: 'status', ttl: '2m' });
+    await claim.claim({ action: 'editing', field: 'status', ttl: '2m' });
     try {
       // update commits with the held claim and auto-releases on success
       const updated = await claim.update({
@@ -47,7 +47,7 @@ const updateTask = tool({
 
       return { ok: true, task: updated };
     } catch (err) {
-      await claim.release();
+      await claim.finish();
       throw err;
     }
   },

package/docs/interaction-model.md

@@ -115,12 +115,12 @@ model accessor:
 
 ```ts
 const task = ablo.tasks.intent('task_123');
-if (task.current) await task.settled();      // someone's working — wait
-await task.acquire({ action: 'editing' });   // claim so others yield
+if (task.current) await task.whenFree();     // someone's working — wait
+await task.claim({ action: 'editing' });     // claim so others yield
 await task.update({ status: 'done' });        // commits + releases
 ```
 
-`task.current` is the live `Intent` (or `null`); `task.settled()` resolves when
+`task.current` is the live `Intent` (or `null`); `task.whenFree()` resolves when
 the holder finishes. The same signal is visible to every schema client through
 `ablo.intents.list(...)` and the live intent stream, so callers decide whether
 to yield, wait, or fail fast. See [API → Intent](./api.md#intent) for the object

package/docs/quickstart.md

@@ -82,17 +82,17 @@ ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
 
 When AI or background work will touch an existing row for more than a quick
 write, coordinate through `ablo.<model>.intent(id)`. It returns a handle
-synchronously — read `.current` to see who's working on the row, `acquire()` to
+synchronously — read `.current` to see who's working on the row, `claim()` to
 claim it, `update()` to write under the claim (which auto-releases).
 
 ```ts
 const report = ablo.weatherReports.intent('weather_stockholm');
 
 // If another participant holds it, wait for them to finish.
-if (report.current) await report.settled();
+if (report.current) await report.whenFree();
 
 // Claim it so other participants yield while we work.
-await report.acquire({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
+await report.claim({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
 
 // Your existing weather tool or agent call. While this runs, other clients see
 // that weather_stockholm is being checked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",