@abloatai/ablo 0.11.0 → 0.11.1

package/dist/client/createModelProxy.js

@@ -18,6 +18,7 @@ import { autorun } from 'mobx';
 import { AbloClaimedError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { Model, modelAsRow } from '../Model.js';
+import { toMs } from '../utils/duration.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -75,7 +76,17 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // Claims this proxy currently holds, keyed by entity id. Lets the flat
     // `release({ id })` and `update({ id, data })` find the lease + snapshot a `claim({ id })`
     // took — no per-call handle. Released on dispose, explicit release, or TTL.
+    //
+    // `target` / `action` / `expiresAt` are kept alongside the lease so
+    // `claim.state` can synthesize a self-claim: the server excludes a holder's
+    // own presence frames, so the local proxy is the ONLY place that knows "I
+    // hold this." `expiresAt` is the client's best estimate from the requested
+    // TTL (a genuine epoch-ms expiry, not a fabricated watermark), defaulting to
+    // the server's keepalive lease window when no TTL was requested.
     const activeClaims = new Map();
+    // Server keepalive lease window (Hub `LEASE_RENEW_TTL_MS`). The fallback
+    // expiry estimate when a claim is taken without an explicit TTL.
+    const DEFAULT_LEASE_TTL_MS = 90_000;
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
@@ -124,7 +135,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     };
     const takeClaim = async (params) => {
         if (!collaboration) {
-            throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+            throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
         const { id, ...options } = params;
         // Is someone ELSE already on this target? Read the local coordination
@@ -157,6 +168,14 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         if (!model) {
             throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
         }
+        // Write-intent: enter the entity scope BEFORE acquiring the lease so the
+        // holder's claim presence broadcasts to whoever is in this entity group —
+        // including a peer that subscribed just before us. Pinning before the
+        // lease (rather than after) closes the subscribe-vs-broadcast race: the
+        // server fans `broadcastPresenceChange` out at claim time, so we must be
+        // in the group when `createClaim` lands. Awaited because the broadcast
+        // ordering depends on it; still soft (the store swallows reconcile errors).
+        await collaboration.pinScope?.({ [schemaKey]: id });
         // Acquire the lease. Default (`wait` !== false) goes through the server's
         // fair FIFO queue — `queue: true` resolves only once the lease is genuinely
         // ours, blocking behind any current holder, with no TOCTOU gap (the server
@@ -194,7 +213,27 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        activeClaims.set(id, { lease, snapshot });
+        const action = options?.action ?? 'editing';
+        // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
+        // report (`observe` maps `held.target.model` → `type`), so a holder and a
+        // peer see the SAME target.type for one row — the wire model token.
+        const selfTarget = {
+            type: wireModel,
+            id,
+            ...(options?.field ? { field: options.field } : {}),
+            ...(options?.path ? { path: options.path } : {}),
+            ...(options?.range ? { range: options.range } : {}),
+            ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
+        };
+        const expiresAt = Date.now() +
+            (options?.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS);
+        activeClaims.set(id, {
+            lease,
+            snapshot,
+            target: selfTarget,
+            action,
+            expiresAt,
+        });
         const target = {
             model: schemaKey,
             id,
@@ -209,7 +248,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             claimId: lease.claimId,
             readAt: snapshot.stamp,
             target,
-            action: options?.action ?? 'editing',
+            action,
             ...(options?.description ? { description: options.description } : {}),
             data: modelAsRow(model),
             release,
@@ -226,6 +265,28 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // are the same object.
     const claimApi = Object.assign(guard(claim), {
         state(params) {
+            // Read-interest: a passive observer subscribing to a row's claim state
+            // must enter that row's entity scope, or it sits on `org:`/`user:`
+            // groups only and never receives the holder's entity-scoped claim
+            // presence. Soft + fire-and-forget — never blocks or rejects the read.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
+            // Self-awareness: the server excludes a holder's OWN presence frames and
+            // the client skips them, so `observe` returns null for a row WE hold.
+            // Synthesize the active claim for self from the stored lease so the
+            // holder sees its own claim (the JSDoc contract on `claim.state`).
+            const own = activeClaims.get(params.id);
+            if (own) {
+                return {
+                    object: 'claim',
+                    id: own.lease.claimId,
+                    status: 'active',
+                    target: own.target,
+                    action: own.action,
+                    heldBy: collaboration?.selfParticipantId ?? '',
+                    participantKind: collaboration?.selfParticipantKind ?? 'user',
+                    expiresAt: own.expiresAt,
+                };
+            }
             return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
@@ -241,6 +302,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     });
     const operations = {
         retrieve: guard(async (params) => {
+            // Read-interest enrolment: READ a row → enter its entity scope, so a
+            // Node/agent client lands in the same group the holder's claim presence
+            // fans out on and `claim.state`/`claim.queue` report peers. Soft +
+            // fire-and-forget — never make the read reject or slower.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
             const rows = await load({
                 ...params,
                 where: [['id', params.id]],
@@ -248,6 +314,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             });
             return rows[0];
         }),
+        // NB: no auto scope enrolment on bulk `list`/`getAll` — that would
+        // subscribe to an unbounded set of rows' entity groups. Bulk-list scope
+        // enrolment is a deliberate follow-up (a bounded, opt-in policy).
         list: guard(load),
         get(id) {
             return objectPool.get(id);
@@ -295,8 +364,14 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             let autoLease;
             if (claim && !isClaimHandle(claim)) {
                 if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" cannot claim a row without collaboration wiring.`, { code: 'model_claim_not_configured' });
+                    throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
                 }
+                // Write-intent: enter the new row's entity scope BEFORE acquiring the
+                // create-claim so the holder's claim presence broadcasts to whoever is
+                // already in this entity group (closing the subscribe-vs-broadcast
+                // race — see `takeClaim`). Released with the lease in the `finally`
+                // below. Awaited for broadcast ordering; still soft.
+                await collaboration.pinScope?.({ [schemaKey]: id });
                 autoLease = await collaboration.createClaim({
                     target: {
                         model: wireModel,

package/dist/errorCodes.js

@@ -158,7 +158,7 @@ export const ERROR_CODES = {
     malformed_subscription: wire('validation', 400, false, 'The update_subscription payload was malformed; expected { syncGroups: string[] }.'),
     model_claimed: wire('claim', 409, false, 'The model instance is claimed by another participant.'),
     model_claimed_timeout: wire('claim', 409, false, 'Timed out waiting for a model claim to clear.'),
-    model_claim_not_configured: client('claim', 'Claiming was requested on a model that has no claim configuration.'),
+    model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
     // ── stale context / idempotency (409) ──────────────────────────────
     stale_context: wire('conflict', 409, true, 'The write carried a readAt watermark that is now stale; re-read and retry.'),
     idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),

package/dist/schema/schema.d.ts

@@ -116,13 +116,13 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
  * ```
  */
 /** The schema bound via `declare module … interface Register { Schema: … }`
- *  (the `ablo.d.ts` the scaffold writes). `never` when not registered. */
+ *  (the `ablo/register.ts` the scaffold writes). `never` when not registered. */
 type RegisteredSchema = import('../types/global.js').Register extends {
     Schema: infer S extends Schema;
 } ? S : never;
 /**
- * THE model type helper. With the scaffold's `ablo.d.ts` registration in
- * place, one parameter is all it takes:
+ * THE model type helper. With the scaffold's `ablo/register.ts` registration
+ * in place, one parameter is all it takes:
  *
  * ```ts
  * type Task = Model<'tasks'>;

package/dist/transactions/TransactionQueue.d.ts

@@ -427,6 +427,17 @@ export declare class TransactionQueue extends EventEmitter {
     private extractUpdateData;
     private buildUpdateInput;
     private extractPreviousData;
+    /**
+     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
+     * committed. Called right after {@link extractPreviousData} freezes their
+     * `.old` into the transaction, so the NEXT update to the same field sees this
+     * update's result as its baseline rather than the stale pre-session `.old`
+     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
+     * keys present in this update — untouched fields keep their baselines. Safe
+     * because the wire payload lives on `transaction.data` and rollback restores
+     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
+     */
+    private consumeModifiedFields;
     /**
      * Public API
      */

package/dist/transactions/TransactionQueue.js

@@ -773,6 +773,15 @@ export class TransactionQueue extends EventEmitter {
             ? this.mapChangesToInput(actualModelName, precomputedChanges)
             : this.extractUpdateData(model);
         const previousData = this.extractPreviousData(model, updateInput);
+        // Advance the per-field baseline for the keys we just froze into this
+        // transaction. `Model.propertyChanged` is first-old-wins and only cleared on
+        // sync-ack, so without this a SECOND update to the same field before the
+        // first acks would re-capture the original `.old` (the pre-session value)
+        // instead of THIS update's result — corrupting the stream-recorded undo
+        // inverse (the second move's "before" would point all the way back). The
+        // wire payload is already frozen in `transaction.data`, so dropping the
+        // consumed entries is safe. Mirrors `RecordingTransaction.consumeModifiedFields`.
+        this.consumeModifiedFields(model, updateInput);
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('update', actualModelName);
         const transaction = {
@@ -1991,16 +2000,63 @@ export class TransactionQueue extends EventEmitter {
     // expose a typed `getPreviousData()` accessor on Model and call that.
     extractPreviousData(model, updateInput) {
         const prev = { id: model.id };
-        if (model.modifiedProperties instanceof Map && model.modifiedProperties.size > 0) {
-            for (const [key, change] of model.modifiedProperties) {
-                // Only include keys that are part of this update if provided
-                if (updateInput && !(key in updateInput))
+        const modified = model.modifiedProperties instanceof Map ? model.modifiedProperties : null;
+        // When the update's written keys are known, capture a before-image for
+        // EXACTLY those keys so the recorded undo inverse can revert them and only
+        // them (a full-row inverse would clobber concurrent edits to unrelated
+        // fields). Resolution order mirrors `RecordingTransaction.snapshotFields`:
+        //   1. `modifiedProperties.old` — first-old-wins pre-session baseline, set
+        //      whenever the caller mutated the field in place before committing.
+        //   2. `getOriginalSnapshot()` — the last loaded/acked row, the correct
+        //      before-image for a key written WITHOUT a prior in-place mutation
+        //      (e.g. a `precomputedChanges` write).
+        // Without (2) such a key yields an empty `previousData`, and `buildUndoOps`
+        // nulls the inverse entirely — making updates silently un-undoable where a
+        // create's `delete(id)` inverse never is. This closes that asymmetry.
+        if (updateInput) {
+            const original = model.getOriginalSnapshot();
+            for (const key of Object.keys(updateInput)) {
+                if (key === 'id')
                     continue;
+                const mod = modified?.get(key);
+                if (mod) {
+                    prev[key] = mod.old;
+                }
+                else if (original && key in original) {
+                    prev[key] = original[key];
+                }
+            }
+            return prev;
+        }
+        if (modified && modified.size > 0) {
+            for (const [key, change] of modified) {
                 prev[key] = change.old;
             }
         }
         return prev;
     }
+    /**
+     * Re-baseline `modifiedProperties` for the fields a freshly-staged update just
+     * committed. Called right after {@link extractPreviousData} freezes their
+     * `.old` into the transaction, so the NEXT update to the same field sees this
+     * update's result as its baseline rather than the stale pre-session `.old`
+     * preserved by `Model.propertyChanged`'s first-old-wins policy. Only consumes
+     * keys present in this update — untouched fields keep their baselines. Safe
+     * because the wire payload lives on `transaction.data` and rollback restores
+     * from `transaction.previousData`; neither re-reads `modifiedProperties`.
+     */
+    consumeModifiedFields(model, updateInput) {
+        if (!(model.modifiedProperties instanceof Map) || model.modifiedProperties.size === 0) {
+            return;
+        }
+        for (const key of [...model.modifiedProperties.keys()]) {
+            if (key === 'id')
+                continue;
+            if (updateInput && !(key in updateInput))
+                continue;
+            model.modifiedProperties.delete(key);
+        }
+    }
     /**
      * Public API
      */

package/dist/types/global.d.ts

@@ -12,11 +12,16 @@
  * global, not prefixed). It's a language feature, not a library trick: any file
  * in the compilation can augment it and every resolver below picks it up.
  *
- * Consumer example:
+ * Consumer example (`npx ablo init` scaffolds this as `ablo/register.ts`, a
+ * sibling of `ablo/schema.ts`). It's a regular `.ts` module, NOT a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` makes the `declare module`
+ * block MERGE (augment) this interface rather than collide with it — the same
+ * shape TanStack Router uses in `src/router.tsx`. Any `.ts` file in the
+ * `tsconfig` `include` works; it never needs to be imported.
  *
  * ```ts
- * // apps/your-app/src/ablo.d.ts
- * import type { schema } from './your-schema';
+ * // ablo/register.ts
+ * import type { schema } from './schema';
  *
  * declare module '@abloatai/ablo' {
  *   interface Register {

package/dist/types/global.js

@@ -12,11 +12,16 @@
  * global, not prefixed). It's a language feature, not a library trick: any file
  * in the compilation can augment it and every resolver below picks it up.
  *
- * Consumer example:
+ * Consumer example (`npx ablo init` scaffolds this as `ablo/register.ts`, a
+ * sibling of `ablo/schema.ts`). It's a regular `.ts` module, NOT a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` makes the `declare module`
+ * block MERGE (augment) this interface rather than collide with it — the same
+ * shape TanStack Router uses in `src/router.tsx`. Any `.ts` file in the
+ * `tsconfig` `include` works; it never needs to be imported.
  *
  * ```ts
- * // apps/your-app/src/ablo.d.ts
- * import type { schema } from './your-schema';
+ * // ablo/register.ts
+ * import type { schema } from './schema';
  *
  * declare module '@abloatai/ablo' {
  *   interface Register {

package/docs/api.md

@@ -120,18 +120,18 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
 
 | Field | Type | Description |
 |---|---|---|
-| `object` | `'intent'` | String representing the object's type. |
+| `object` | `'claim'` | String representing the object's type. |
 | `id` | string | Unique identifier for the claim. |
 | `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
 | `target` | `{ type, id, field? }` | What is being coordinated. |
 | `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
 | `heldBy` | string | Participant id holding the claim. |
-| `participantKind` | `'human' \| 'agent'` | Whether a human session or an agent holds it. |
+| `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
 | `expiresAt` | string | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
 
 ```json
 {
-  "object": "intent",
+  "object": "claim",
   "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
   "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },

package/docs/client-behavior.md

@@ -29,6 +29,7 @@ Common options:
 |---|---|
 | `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
+| `databaseUrl` | Optional, server-only. Registers your Postgres directly (the connection-string path). Pass it explicitly — it is **not** auto-read from the environment. Omit it for a signed Data Source endpoint or the hosted sandbox. The SDK throws if it sees this in a browser. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
@@ -36,9 +37,11 @@ Common options:
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |
 | `dangerouslyAllowBrowser` | Required before sending an API key from browser code. Prefer a server route instead. |
 
-There is intentionally no `databaseURL` constructor option. Teams that keep
-canonical rows in their own database use a signed [Data Source](./data-sources.md)
-endpoint.
+`databaseUrl` is an optional, server-only constructor option. It is **not**
+auto-read from the environment — pass it explicitly to register your Postgres
+directly (the connection-string path). Omit it when you expose a signed
+[Data Source](./data-sources.md) endpoint, or when trying Ablo against the hosted
+sandbox.
 
 ## Model Methods
 

package/docs/coordination.md

@@ -29,7 +29,7 @@ make:
 
 | layer | kind | what it does | enforces? |
 |---|---|---|---|
-| **Presence** (`claim.state`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." | **No.** Advisory only — it never blocks or rejects a write. |
+| **Presence** (`claim.state`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." Reading or claiming a row auto-enrolls you in its sync group, so `claim.state({ id })` observes co-participants from any client (browser or Node agent) with no manual subscribe step. | **No.** Advisory only — it never blocks or rejects a write. |
 | **Claim** (`claim`/`claim.queue`/`claim.release`) | pessimistic | Reserves a row for one participant. Foreign writers are rejected server-side; contenders join a fair FIFO queue. | **Yes**, between participants — mutual exclusion. |
 | **Stale-context** (`readAt` + `onStale`) | optimistic (LWW) | On commit, rejects a write whose snapshot is older than the row's latest delta. Last-writer-wins detection. | **Yes**, against time — lost-update detection. |
 
@@ -70,7 +70,7 @@ a model row. It's what `claim.state()` returns and what observers render.
 | `target` | `EntityRef` | What is being coordinated (`{ model, id, field? }`). |
 | `action` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
 | `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
-| `participantKind` | `'human' \| 'agent'` | Who's behind it. |
+| `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
 | `position` | `number?` | 0-based place in the FIFO line — present only when `status: 'queued'` (`0` = next behind the holder). |
 | `createdAt` | `string?` | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
 | `expiresAt` | `string` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
@@ -167,6 +167,16 @@ ablo.<model>.claim.state({ id })
 Read who's currently working on a row, for observers and UI. Synchronous and
 reactive (it reads the local coordination snapshot). Never blocks.
 
+**You don't subscribe to anything first.** Reading or claiming a row
+automatically enrolls you in that row's sync group: reading it (including
+`retrieve`/`get`, or `claim.state` itself) gives you **read-interest**, and
+`claim`-ing it gives you a **pinned write-intent**. So `claim.state({ id })`
+observes co-participants on that row from **any** client — a browser, a Server
+Action, or a Node agent — and a holder sees its own claim, with no manual
+subscribe step. There is no `participants.join` to call: the typed
+`ablo.<model>` surface (read / `claim` / `claim.state` / `claim.queue`) is the
+whole coordination API.
+
 **Parameters**
 
 | name | type | required | description |
@@ -306,7 +316,7 @@ inspect the `code`.
 | `AbloClaimedError` | `claim_conflict` | An `update`/`delete` targets a row another participant holds — the server's pre-commit check rejected it. | — |
 | `AbloClaimedError` | `entity_claimed` | Same conflict, from the commit guard backstop. | — |
 | `AbloStaleContextError` | — | A guarded `update` (under a claim, or any write carrying `readAt`) targets a row that received deltas since the snapshot — your reasoning is stale. | `readAt`, `conflicts[]` |
-| `AbloValidationError` | `model_claim_not_configured` | `claim` called on a model without collaboration wiring. | — |
+| `AbloValidationError` | `model_claim_not_configured` | `claim` called on a model proxy built without the collaboration runtime — an internal/advanced construction path. The standard `Ablo({ schema, apiKey })` client enables claiming for **every** model; there is no per-model claim config to add. | — |
 | `AbloValidationError` | `entity_not_found` | The row id doesn't exist locally or on load. | — |
 
 `AbloStaleContextError.conflicts` lists the `(model, id, observedSyncId)` rows

package/docs/data-sources.md

@@ -1,15 +1,20 @@
 # Connect Your Database
 
-**Your database is the system of record — Ablo never hosts your data.** Every
-synced model is backed by your own Postgres; Ablo is the transaction layer on
-top of it. There are two ways to connect, and they are the same product with the
-same writes — the only difference is where your database credential lives:
+**In production, your database is the system of record.** Every synced model is
+backed by your own Postgres; Ablo is the transaction layer on top of it. There
+are two ways to connect, and they are the same product with the same writes — the
+only difference is where your database credential lives:
 
 | | How Ablo reaches your Postgres | Use when |
 |---|---|---|
-| **Connection string** (default) | You pass `databaseUrl` to `Ablo(...)`; Ablo registers the connection and commits each write directly, behind row-level security. | You can hand over a scoped connection string. |
+| **Connection string** (primary) | You pass `databaseUrl` to `Ablo(...)` explicitly (it is never auto-read from the environment); Ablo registers the connection and commits each write directly, behind row-level security. | You can hand over a scoped connection string. |
 | **Signed endpoint** | Your app exposes one route built from an ORM adapter; Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
 
+> Just trying Ablo? You don't need a database at all to start: the hosted
+> **sandbox** can host rows in Ablo's test plane — pass an `apiKey` only and omit
+> `databaseUrl`, like Stripe test mode. Connect your Postgres (either shape
+> below) when you're ready for it to be the system of record.
+
 Either way, you define an Ablo schema with `defineSchema`, `model`, and Zod. The
 Ablo schema describes **only your synced, collaborative models** — the rows Ablo
 coordinates and fans out in realtime. It is *not* your whole-database schema and
@@ -36,7 +41,7 @@ import { schema } from './ablo/schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
+  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
 ```
 
@@ -50,6 +55,20 @@ On first connect the SDK registers the connection — sent once over TLS, stored
 sealed, never returned by any API. From then on Ablo commits every confirmed
 write directly to your database and reads canonical rows from it.
 
+### A localhost Postgres can't be the system of record
+
+This is the connection-string fact people hit first. Ablo's **cloud** registers
+your connection string and connects to your Postgres **over the network**. A
+`localhost` / private-range database (`127.0.0.1`, `192.168.*`, Docker's
+`db:5432`) is unreachable from Ablo's side, so such connection strings are
+**rejected**. Two escape hatches for local development against your own DB:
+
+- **Expose a signed Data Source endpoint.** Your app — which *can* reach your
+  local DB — proxies Ablo's commits to it. See [Signed Endpoint](#signed-endpoint)
+  below. This is the right answer for "my dev DB stays on my machine."
+- **Use the hosted sandbox.** Skip the database entirely: pass an `apiKey` only,
+  omit `databaseUrl`, and let Ablo's test plane host the rows while you build.
+
 Safety requirements, enforced server-side before the first write:
 
 - **Non-superuser role.** The connection must not be a superuser or hold
@@ -58,11 +77,12 @@ Safety requirements, enforced server-side before the first write:
 - **Row-level security on synced tables.** `npx ablo migrate` provisions your
   synced-model tables with `FORCE ROW LEVEL SECURITY` already applied; tables
   you create yourself must do the same.
-- **Public hosts only.** Connection strings resolving to loopback or private
-  address ranges are rejected.
+- **Network-reachable host.** As above, connection strings resolving to loopback
+  or private address ranges are rejected — Ablo connects from its cloud.
 
 `databaseUrl` is server-only: the SDK throws if it sees one in a browser-like
-environment, and `dangerouslyAllowBrowser` does not override that.
+environment, and `dangerouslyAllowBrowser` does not override that. It is also
+never auto-read from the environment — pass it explicitly to `Ablo(...)`.
 
 ## Signed Endpoint
 

package/docs/migration.md

@@ -11,6 +11,7 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.11.0** | `intent` → `claim` rename completed across the React hook, type namespace, and wire frames | `useIntent` → `useClaim`; `Register.Intents` → `Register.Claims`; `Ablo.Intent.*` → `Ablo.Claim.*`. Upgrade client **and** server together (wire frames moved `intent_*` → `claim_*`) |
 | **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
@@ -24,6 +25,45 @@ change when you upgrade.
 
 ---
 
+## 0.11.0 — `intent` → `claim` rename completed
+
+The coordination primitive has been `claim` since 0.9.2, but a few `intent`-named
+surfaces lingered. 0.11.0 finishes the rename. There are three edits, all
+mechanical:
+
+**1. React hook.** `useIntent` is now `useClaim` (same signature):
+
+```diff
+- import { useIntent } from '@abloatai/ablo/react';
+- const claimEditLayer = useIntent('editLayer');
++ import { useClaim } from '@abloatai/ablo/react';
++ const claimEditLayer = useClaim('editLayer');
+```
+
+**2. Type registration.** The `Register` interface key is `Claims`, not `Intents`:
+
+```diff
+  declare module '@abloatai/ablo' {
+    interface Register {
+-     Intents: { editLayer: { slideId: string; layerId: string } };
++     Claims: { editLayer: { slideId: string; layerId: string } };
+    }
+  }
+```
+
+**3. Type namespace.** The `Ablo.Intent.*` helper types moved to `Ablo.Claim.*`.
+If you referenced them directly, rename the namespace; the shapes are unchanged.
+
+> **Coordinated deploy required.** The on-the-wire frames moved from `intent_*`
+> to `claim_*`. A `claim_*`-aware client cannot coordinate with an `intent_*`
+> server (and vice-versa), so ship the client and server together. If you run a
+> self-managed sync server, deploy it first.
+
+Two non-breaking improvements ride along: claim-rejection errors now surface the
+contending holders (`AbloClaimedError.claims` and a policy reason folded into the
+message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
+on presence and claim state.
+
 ## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
 
 ### Environment enum rename (the only breaking change)