@abloatai/ablo 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,12 +1,65 @@
 # 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
+
+- Per-entity coordination intents on the model accessor.
+
+  Coordinate writes to an entity through the same accessor you read it with —
+  `ablo.<model>.intent(id)`, returning a `ModelIntentHandle`. Intent state is one
+  self-describing object (`{ object: 'intent', id, status, target, action, heldBy,
+participantKind, createdAt?, expiresAt? }`) with a single lifecycle:
+  `status: 'active' | 'committed' | 'expired' | 'canceled'`. An `active` intent is
+  the lock.
+
+  ### Added
+  - `ablo.<model>.intent(id)` → `ModelIntentHandle<T>`, beside `create` / `update`
+    / `retrieve` / `load` on every model.
+    - Read side (any participant, synchronous + reactive): `current` (the holder's
+      intent, or `null`), `status` (`'idle'` when free), `settled()`.
+    - Write side (the holder): `acquire()`, `acquireOrAwait()`, lease-guarded
+      `update()`, `release()`, `revoke()`.
+    - `AsyncDisposable`: `await using lock = ablo.<model>.intent(id)` auto-releases
+      on scope exit.
+  - `acquireOrAwait()` — serialize-on-contention: take the lease, or wait out the
+    current holder, re-read the changed row, then take it. The caller never branches
+    on who holds the target — it just gets the target safely. Bind it to an agent's
+    write-tool boundary so agents never reason about coordination.
+  - New exports: `ModelIntentHandle`, `ModelIntentAcquireOptions`.
+
+  ### Changed
+  - `acquire()` is fire-and-forget over the socket — it does not throw on conflict.
+    Resolve contention with `acquireOrAwait()` (wait) or read `current` for a
+    reactive "who's editing" badge, rather than catching a rejection.
+
+  ### Deprecated
+  - Participant-level `intents.claim()` / `onRejected()` and the `intent_rejected`
+    wire frame still work but are superseded by the per-model handle. Their removal
+    is a future breaking change.
+
 ## Unreleased
 
 Schema-driven identity sync-group composition, plus a terser capability surface.
 
 The convention for deriving a participant's allowed sync-groups from its identity is now declared on the consumer's schema as an open registration. Consumers with a `{ regionId, customerId }` identity shape declare their own roles instead of receiving any built-in prefixes from the SDK.
 
-Capability fields shed their redundant `allowed` prefix to match the surrounding vocabulary — capability inputs always describe what the bearer *can* touch, so the prefix was doing no disambiguation work for the consumer.
+Capability fields shed their redundant `allowed` prefix to match the surrounding vocabulary — capability inputs always describe what the bearer _can_ touch, so the prefix was doing no disambiguation work for the consumer.
 
 ### Added
 

package/NOTICE

@@ -1,4 +1,4 @@
-@ablo/sync-engine
+@abloatai/ablo
 Copyright 2025-2026 Fablo Innovation AB
 
 This product includes software developed by Fablo Innovation AB
@@ -7,6 +7,6 @@ This product includes software developed by Fablo Innovation AB
 "Ablo" is a trademark of Fablo Innovation AB. This license does not grant
 permission to use the Ablo name, logo, or trademarks. Third parties
 may describe their use of or compatibility with Ablo factually (e.g.,
-"built with @ablo/sync-engine") but may not use the Ablo name in a way
+"built with @abloatai/ablo") but may not use the Ablo name in a way
 that suggests endorsement, affiliation, or origin without written
 permission.

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,8 +28,9 @@ 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
 
@@ -72,8 +74,9 @@ Expected output:
 { 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,100 +90,113 @@ future agents, read [Integration Guide](./docs/integration-guide.md).
 
 ## AI Activity on Existing State
 
-Use `edit` when AI or background work will touch an existing row for more than a
-quick write. Other participants can see the activity while your code runs. The
-activity is cleared when `update` finishes; call `release` if the work ends
-without a write.
+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 edit = await ablo.weatherReports.edit('weather_stockholm', {
-  activity: 'checking_weather',
-  field: 'forecast',
-  ttl: '2m',
-});
+// `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.whenFree();
+}
+
+// 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 weather = await weatherAgent.getWeather(edit.current.location, {
-  signal: edit.signal,
-});
+// that report_stockholm is being checked.
+const row = ablo.weatherReports.retrieve('report_stockholm');
+const weather = await weatherAgent.getWeather(row.location);
 
-await edit.update({
+await report.update({
   status: 'ready',
   forecast: weather.summary,
 });
 ```
 
-Ablo does not fetch the weather. It keeps the activity visible, gives the agent
-call an abort signal if the row changes, and clears the activity when
-`edit.update(...)` finishes.
+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 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>.edit(...)` lets humans and agents see active work before a write lands.
-- `ablo.intents` remains available for custom lower-level coordination.
+- `ablo.<model>.intent(id)` lets humans and agents see and coordinate active work before a write lands.
 
-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({
@@ -198,12 +214,17 @@ 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
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+# stays in your app — Ablo never receives this
+DATABASE_URL=postgres://...
+
+# the only Ablo credential your app needs
+ABLO_API_KEY=sk_live_...
 ```
 
 See [Connect Your Database](./docs/data-sources.md) for the route and commit shape.

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/agent/Agent.d.ts

@@ -9,7 +9,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',

package/dist/agent/Agent.js

@@ -9,7 +9,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',

package/dist/agent/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine-internal/agent — Agent SDK helpers
+ * @abloatai/ablo/agent — Agent SDK helpers
  *
  * Two entry points depending on agent lifetime:
  *
@@ -12,7 +12,7 @@
  * server-issued capability token instead of session cookies.
  *
  * ```ts
- * import Ablo from '@ablo/sync-engine';
+ * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({
  *   schema,
@@ -44,7 +44,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',
@@ -78,7 +78,7 @@
  * ```ts
  * import { tool } from 'ai';
  * import { z } from 'zod';
- * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
  *
  * export const updateSlideTool = () => tool({
  *   description: 'Update a slide title',

package/dist/agent/index.js

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine-internal/agent — Agent SDK helpers
+ * @abloatai/ablo/agent — Agent SDK helpers
  *
  * Two entry points depending on agent lifetime:
  *
@@ -12,7 +12,7 @@
  * server-issued capability token instead of session cookies.
  *
  * ```ts
- * import Ablo from '@ablo/sync-engine';
+ * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({
  *   schema,
@@ -44,7 +44,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',
@@ -78,7 +78,7 @@
  * ```ts
  * import { tool } from 'ai';
  * import { z } from 'zod';
- * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
  *
  * export const updateSlideTool = () => tool({
  *   description: 'Update a slide title',
@@ -117,12 +117,12 @@
 // `Agent` is the class AND the namespace for its types. Reach for
 // options, context, and session options via dot access:
 //
-//   import { Agent } from '@ablo/sync-engine-internal/agent';
+//   import { Agent } from '@abloatai/ablo/agent';
 //   const opts: Agent.Options = { ... };
 //   const ctx:  Agent.Context = { perception };
 //   const s:    Agent.SessionOptions = { ... };
 //
 // Everything else (Activity, Claim, Turn, Peer, ActiveIntent, ...)
 // lives on the `Ablo.*` namespace via
-// `import type { Ablo } from '@ablo/sync-engine'`.
+// `import type { Ablo } from '@abloatai/ablo'`.
 export { Agent } from './Agent.js';

package/dist/agent/types.d.ts

@@ -35,7 +35,7 @@ export interface PresenceAnnouncer {
  *
  * ```ts
  * import { generateText, tool } from 'ai';
- * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
  *
  * const updateSlideTool = () => tool({
  *   inputSchema: z.object({ id: z.string(), title: z.string() }),

package/dist/ai-sdk/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@ablo/sync-engine-internal/ai-sdk` — multiplayer-with-AI as language model
+ * `@abloatai/ablo/ai-sdk` — multiplayer-with-AI as language model
  * middleware.
  *
  * Two cross-cutting middlewares for any AI SDK consumer using
@@ -24,7 +24,7 @@
  * import {
  *   intentBroadcastMiddleware,
  *   coordinationContextMiddleware,
- * } from '@ablo/sync-engine-internal/ai-sdk';
+ * } from '@abloatai/ablo/ai-sdk';
  *
  * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
  *
@@ -48,7 +48,7 @@
  * Or use the convenience composition for the common case:
  *
  * ```ts
- * import { wrapWithMultiplayer } from '@ablo/sync-engine-internal/ai-sdk';
+ * import { wrapWithMultiplayer } from '@abloatai/ablo/ai-sdk';
  *
  * const wrappedModel = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),

package/dist/ai-sdk/index.js

@@ -1,5 +1,5 @@
 /**
- * `@ablo/sync-engine-internal/ai-sdk` — multiplayer-with-AI as language model
+ * `@abloatai/ablo/ai-sdk` — multiplayer-with-AI as language model
  * middleware.
  *
  * Two cross-cutting middlewares for any AI SDK consumer using
@@ -24,7 +24,7 @@
  * import {
  *   intentBroadcastMiddleware,
  *   coordinationContextMiddleware,
- * } from '@ablo/sync-engine-internal/ai-sdk';
+ * } from '@abloatai/ablo/ai-sdk';
  *
  * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
  *
@@ -48,7 +48,7 @@
  * Or use the convenience composition for the common case:
  *
  * ```ts
- * import { wrapWithMultiplayer } from '@ablo/sync-engine-internal/ai-sdk';
+ * import { wrapWithMultiplayer } from '@abloatai/ablo/ai-sdk';
  *
  * const wrappedModel = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),

package/dist/ai-sdk/intent-broadcast.d.ts

@@ -11,7 +11,7 @@
  *
  * Open-source-clean: depends only on `@ai-sdk/provider` types and
  * the package's own `SyncAgent`. No app-specific assumptions —
- * Ablo's web app uses this, but so can any consumer of `@ablo/sync-engine`.
+ * Ablo's web app uses this, but so can any consumer of `@abloatai/ablo`.
  *
  * Cost: one WS frame at stream start (`intent_begin`), one at end
  * (`intent_abandon`). No DB I/O, no extra LLM tokens.

package/dist/ai-sdk/intent-broadcast.js

@@ -11,7 +11,7 @@
  *
  * Open-source-clean: depends only on `@ai-sdk/provider` types and
  * the package's own `SyncAgent`. No app-specific assumptions —
- * Ablo's web app uses this, but so can any consumer of `@ablo/sync-engine`.
+ * Ablo's web app uses this, but so can any consumer of `@abloatai/ablo`.
  *
  * Cost: one WS frame at stream start (`intent_begin`), one at end
  * (`intent_abandon`). No DB I/O, no extra LLM tokens.

package/dist/auth/index.d.ts

@@ -63,7 +63,7 @@ export declare function resolveIdentity(options: ResolveIdentityRequest): Promis
 /**
  * Capability-token refresh scheduler.
  *
- * Long-lived `@ablo/sync-engine` clients hold a server-issued capability
+ * Long-lived `@abloatai/ablo` clients hold a server-issued capability
  * token whose TTL (1h default) is shorter than typical browser sessions.
  * Without proactive refresh, the WebSocket would either be force-closed
  * by the server at expiry (code 1008) or fail its next reconnect with