@abloatai/ablo 0.10.1 → 0.11.1

package/dist/types/streams.d.ts

@@ -3,14 +3,14 @@
  *
  * Ablo treats humans and agents as participants on live application
  * entities. Participants announce what they are reading or editing,
- * claim intent before writing, and capture context watermarks before
+ * claim before writing, and capture context watermarks before
  * long-running AI work. The customer keeps their own schema, agent
  * stack, tools, prompts, and product policy; the sync engine provides
  * the shared coordination substrate.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
-import type { TargetRange, OnStaleMode, IntentClaim, PresenceKind } from '../coordination/schema.js';
-export type { TargetRange, OnStaleMode, IntentClaim, PresenceKind };
+import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind } from '../coordination/schema.js';
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form
  * metadata that will be persisted / transported as JSON — avoids
@@ -290,15 +290,15 @@ export interface Activity {
  * writes this shape only.
  */
 export interface Peer {
-    readonly participantKind: 'human' | 'agent';
+    readonly participantKind: ParticipantKind;
     readonly participantId: string;
     readonly label?: string;
     readonly syncGroups: readonly string[];
     readonly activity: Activity;
     /** Server timestamp of the most recent frame from this participant. */
     readonly lastActive: string;
-    /** Pending-mutation intents this participant has declared. */
-    readonly activeIntents?: ReadonlyArray<IntentClaim>;
+    /** Pending-mutation claims this participant has declared. */
+    readonly activeClaims?: ReadonlyArray<Claim>;
 }
 /** Outbound `presence_update` payload. */
 export interface PresenceUpdatePayload {
@@ -307,24 +307,24 @@ export interface PresenceUpdatePayload {
     readonly isAgent?: boolean;
 }
 /**
- * Intent broadcasts — "I'm about to do X on Y." Broadcasts flow on
+ * Claim broadcasts — "I'm about to do X on Y." Broadcasts flow on
  * the same WS as presence, so every participant sees them in real
- * time. Cooperative mutex: the intent doesn't enforce exclusion; it
+ * time. Cooperative mutex: the claim doesn't enforce exclusion; it
  * announces. Other agents observe and yield. This is cheaper and
  * more flexible than a central lock table and composes with presence.
  */
 /**
- * Options common to every verb-style intent announcement
- * (`intents.analyzing`, `.drafting`, etc.).
+ * Options common to every verb-style claim announcement
+ * (`claims.analyzing`, `.drafting`, etc.).
  *
  * The one required field is the *target* — everything else is a
- * sensible default. Prefer the verb methods in `IntentStream` below
+ * sensible default. Prefer the verb methods in `ClaimStream` below
  * (`analyzing(entity, { ttl: '3m' })`) over the raw `announce(...)`
  * escape hatch.
  */
-export interface IntentOptions {
+export interface ClaimLeaseOptions {
     /**
-     * How long before the server auto-expires this intent if the
+     * How long before the server auto-expires this claim if the
      * participant doesn't finish the work. Accepts either a number (in
      * seconds — back-compat with `ttlSeconds`) or a duration string:
      * `'500ms'`, `'30s'`, `'3m'`, `'24h'`.
@@ -333,7 +333,7 @@ export interface IntentOptions {
 }
 /** Re-export of the duration helper shape. See `./duration.ts`. */
 export type Duration = import('../utils/duration.js').Duration;
-export interface ClaimOptions extends IntentOptions {
+export interface ClaimOptions extends ClaimLeaseOptions {
     /**
      * Free-form reason describing why you're claiming. Surfaces in conflict
      * messages and the activity overlay. Defaults to `'editing'`. Common
@@ -349,21 +349,21 @@ export interface ClaimOptions extends IntentOptions {
     readonly description?: string;
     /**
      * Join the server's fair FIFO queue on contention instead of being
-     * rejected. The grant arrives asynchronously (`intent_acquired` if the
-     * target was free, `intent_granted` once promoted to the head of the line).
+     * rejected. The grant arrives asynchronously (`claim_acquired` if the
+     * target was free, `claim_granted` once promoted to the head of the line).
      * The low-level `claim` returns its handle immediately regardless; callers
      * that need to *wait* for the grant use the awaiting wrappers
-     * (`ablo.<model>.claim`), which pair this flag with `awaitIntentGrant`.
+     * (`ablo.<model>.claim`), which pair this flag with `awaitClaimGrant`.
      */
     readonly queue?: boolean;
 }
-export interface IntentStream {
+export interface ClaimStream {
     /**
-     * Claim an exclusive intent on a target. Returns a handle — call
+     * Claim an exclusive claim on a target. Returns a handle — call
      * `.revoke()` to cancel, let it expire via TTL, or use `await using`
      * (TC39 explicit resource management) to auto-revoke on scope exit.
      *
-     * Server rejects via `intent_rejected` when another participant
+     * Server rejects via `claim_rejected` when another participant
      * already holds a claim on the same target. Default `reason` is
      * `'editing'`; pass `{reason: 'writing'}` (or any string) to override.
      *
@@ -372,30 +372,30 @@ export interface IntentStream {
      * scoped `claim(reason, opts)` overload were collapsed into this
      * single primitive.
      */
-    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
+    claim(target: PresenceTarget, opts?: ClaimOptions): ClaimHandle;
     /**
-     * Reactive view of every other participant's active intents.
+     * Reactive view of every other participant's active claims.
      * Reads return the current snapshot; pair with `subscribe(...)`
      * below to get notified on change.
      */
-    readonly others: ReadonlyArray<ActiveIntent>;
+    readonly others: ReadonlyArray<ActiveClaim>;
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
-     * `status: 'queued'` intents behind the current holder, each with its
+     * `status: 'queued'` claims behind the current holder, each with its
      * `action`, `heldBy`, and `position`. Synced from the server's per-entity
-     * `intent_queue` frame; empty when no one's waiting. Pair with
+     * `claim_queue` frame; empty when no one's waiting. Pair with
      * `subscribe(...)` for change notifications.
      */
-    queueFor(target: PresenceTarget): readonly Intent[];
+    queueFor(target: PresenceTarget): readonly Claim[];
     /**
      * Re-rank the wait queue on a target — move the listed waiters to the front
      * in the given order; unlisted waiters keep their relative FIFO order behind
-     * them. Pass the `Intent[]` from `queueFor(target)` in the order you want
-     * (each `Intent` carries its `heldBy` + `id`). Privileged: the server gates
-     * it (a participant lacking the `intent.reorder` capability is denied), so
+     * them. Pass the `Claim[]` from `queueFor(target)` in the order you want
+     * (each `Claim` carries its `heldBy` + `id`). Privileged: the server gates
+     * it (a participant lacking the `claim.reorder` capability is denied), so
      * this is fire-and-forget — the new order arrives reactively via `queueFor`.
      */
-    reorder(target: PresenceTarget, order: readonly Intent[]): void;
+    reorder(target: PresenceTarget, order: readonly Claim[]): void;
     /**
      * Framework-agnostic reactivity. Same contract as
      * `PresenceStream.subscribe` — register a listener fired on every
@@ -405,30 +405,30 @@ export interface IntentStream {
      */
     onChange(listener: () => void): () => void;
     /**
-     * Observe server-side intent rejections. Fires when the server
-     * rejects an `intents.writing(...)` / `announce(...)` call because
+     * Observe server-side claim rejections. Fires when the server
+     * rejects an `claims.writing(...)` / `announce(...)` call because
      * another participant already holds an open claim on the same
      * target (cooperative mutex → enforced at the server boundary).
      *
      * Use this to surface conflicts to the user:
      * ```ts
-     * participant.intents.onRejected((r) => {
+     * participant.claims.onRejected((r) => {
      *   toast.error(`${r.heldBy} is editing — try again in a moment`);
      * });
      * ```
      *
      * Returns an unsubscribe fn.
      */
-    onRejected(listener: (rejection: IntentRejection) => void): () => void;
+    onRejected(listener: (rejection: ClaimRejection) => void): () => void;
     /**
-     * Observe LOSING an intent you held — distinct from `onRejected` (a claim the
-     * server refused). Fires on the server's `intent_lost` frame, carrying why:
+     * Observe LOSING an claim you held — distinct from `onRejected` (a claim the
+     * server refused). Fires on the server's `claim_lost` frame, carrying why:
      * `'preempted'` (a privileged participant evicted you) or `'expired'` (your
      * TTL lapsed). Lets a holder react — re-plan vs re-claim — instead of
      * silently discovering the lease gone via presence.
      *
      * ```ts
-     * participant.intents.onLost((lost) => {
+     * participant.claims.onLost((lost) => {
      *   if (lost.reason === 'preempted') replanAgainst(lost.target);
      *   else reclaim(lost.target);
      * });
@@ -436,55 +436,29 @@ export interface IntentStream {
      *
      * Returns an unsubscribe fn.
      */
-    onLost(listener: (lost: IntentLost) => void): () => void;
+    onLost(listener: (lost: ClaimLost) => void): () => void;
     /**
-     * Async-iterable view of everyone else's open intents. Each
+     * Async-iterable view of everyone else's open claims. Each
      * iteration yields the current snapshot on every mutation.
      *
      * ```ts
-     * for await (const openIntents of participant.intents) {
-     *   if (openIntents.some((i) => i.target.id === clauseId)) wait();
+     * for await (const openClaims of participant.claims) {
+     *   if (openClaims.some((i) => i.target.id === clauseId)) wait();
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveIntent>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveClaim>>;
 }
 /**
- * Shape of an `intent_rejected` event delivered to
- * `IntentStream.onRejected`. Server rejects an incoming claim when
- * another participant already holds an open intent on the same target.
- */
-export interface IntentRejection {
-    /** The rejected claim's id (the one the caller just tried to mint). */
-    readonly intentId: string;
-    /** Why the server rejected it — currently always `'conflict'`. */
-    readonly reason: 'conflict';
-    /** The target that's already held. */
-    readonly target: {
-        readonly entityType: string;
-        readonly entityId: string;
-        readonly path?: string;
-        readonly range?: TargetRange;
-        readonly field?: string;
-        readonly meta?: Record<string, unknown>;
-    };
-    /** Participant id holding the existing claim. */
-    readonly heldBy: string;
-    /** The existing claim's id (for audit / retry correlation). */
-    readonly heldByIntentId: string;
-    /** When the existing claim expires (ms since epoch). */
-    readonly heldByExpiresAt: number;
-}
-/**
- * You LOST an intent you were HOLDING — distinct from `IntentRejection` (a
+ * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a
  * claim the server refused you). Delivered via `onLost`.
  */
-export interface IntentLost {
+export interface ClaimLost {
     /** The held claim's id that you just lost. */
-    readonly intentId: string;
+    readonly claimId: string;
     /**
      * How you lost it. `'preempted'`: a privileged participant (one holding the
-     * `intent.preempt` capability) evicted you and took the lease — its work now
+     * `claim.preempt` capability) evicted you and took the lease — its work now
      * supersedes yours, so re-plan against the new holder rather than blindly
      * re-claiming. `'expired'`: your TTL lapsed without finishing — re-claim if
      * you still need it.
@@ -500,7 +474,7 @@ export interface IntentLost {
         readonly meta?: Record<string, unknown>;
     };
 }
-export interface IntentDeclaration {
+export interface ClaimDeclaration {
     readonly target: EntityRef;
     /** Human-readable reason — "rewriting title" / "restyling chart". */
     readonly reason: string;
@@ -517,58 +491,100 @@ export interface IntentDeclaration {
  *
  * ```ts
  * {
- *   await using work = participant.intents.analyzing(clause, { ttl: '3m' });
- *   // ... do the work; intent auto-revokes when the block exits
+ *   await using work = participant.claims.analyzing(clause, { ttl: '3m' });
+ *   // ... do the work; claim auto-revokes when the block exits
  * }
  * ```
  */
-export interface Claim extends AsyncDisposable {
-    readonly id: string;
+/**
+ * THE one claim handle. Returned by every claim door — the typed
+ * `ablo.<model>.claim({ id })` (rich: `data`/`readAt`/`target` populated) and
+ * the low-level `participant.claims.claim()` lease (minimal: `claimId` +
+ * `revoke`/`release`). Row-level fields are optional precisely because the
+ * low-level lease has no row snapshot; the model door fills them in.
+ *
+ * Implements `Symbol.asyncDispose` so callers can `await using claim = ...`
+ * and have it auto-release on scope exit.
+ */
+export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
+    readonly object: 'claim';
+    readonly claimId: string;
+    /**
+     * True when the grant came AFTER waiting in the server's FIFO line
+     * (`claim_granted`) — the authoritative "the row may have changed under us"
+     * signal. Absent for an immediate grant or a non-queued lease.
+     */
+    readonly waited?: boolean;
+    /**
+     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
+     * carrying the handle use it as the `readAt` stale guard. Present for
+     * model-scoped claims; absent for low-level leases.
+     */
+    readonly readAt?: number;
+    readonly target: {
+        readonly model: string;
+        readonly id: string;
+        readonly field?: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly meta?: Record<string, unknown>;
+    };
+    readonly action: string;
+    readonly description?: string;
+    /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
+    readonly data?: T;
+    release(): Promise<void>;
     revoke(): void;
 }
-export interface ActiveIntent extends IntentDeclaration {
+export interface ActiveClaim extends ClaimDeclaration {
     readonly id: string;
     readonly heldBy: string;
     /**
-     * Whether the holding participant is a human (session) or an agent.
-     * First-class field so UIs can style "agent editing X" differently
-     * from "user editing X" without string-parsing `heldBy`.
+     * Whether the holding participant is a user (session), an agent, or a
+     * system actor. First-class field so UIs can style "agent editing X"
+     * differently from "user editing X" without string-parsing `heldBy`.
+     * Canonical `'user' | 'agent' | 'system'` — the presence/claim stream
+     * derives the value from the boolean `isAgent` wire flag (so it produces
+     * only `'user'`/`'agent'`), but the type stays the full union it shares
+     * with the HTTP claim surface and lease store.
      */
-    readonly participantKind: 'human' | 'agent';
+    readonly participantKind: ParticipantKind;
     readonly description?: string;
-    readonly announcedAt: string;
-    readonly expiresAt: string;
+    /** Epoch-ms the claim was announced. */
+    readonly announcedAt: number;
+    /** Epoch-ms the server auto-expires it. */
+    readonly expiresAt: number;
 }
 /**
- * Every lifecycle state of a coordination intent, in one enum.
+ * Every lifecycle state of a coordination claim, in one enum.
  * `active` = the current holder (the lock). `queued` = waiting in the FIFO
  * line behind the holder (carries `position`). The terminal states drop the
- * intent from the synced set.
+ * claim from the synced set.
  */
-export type IntentStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
+export type ClaimStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
 /** Options for waiting on a target to become free. */
-export interface IntentWaitOptions {
+export interface ClaimWaitOptions {
     readonly timeout?: number;
     readonly pollInterval?: number;
     readonly signal?: AbortSignal;
 }
 /**
  * The coordination state of one entity. Self-describing on the wire via
- * `object: 'intent'`. Existence with `status: 'active'` *is* the lock;
+ * `object: 'claim'`. Existence with `status: 'active'` *is* the lock;
  * 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 until free, then re-read", and the runtime performs
  * that uniformly — `claim` serializes behind the holder via the server
- * FIFO queue (or low-level `intents.waitFor` to wait without claiming), and the
+ * FIFO queue (or low-level `claims.waitFor` to wait without claiming), and the
  * stale-context guard forces the re-read. Encoding a constant instruction
  * the engine always takes would be the kind of ceremony this object exists
  * to remove.
  */
-export interface Intent {
-    readonly object: 'intent';
+export interface Claim {
+    readonly object: 'claim';
     readonly id: string;
-    readonly status: IntentStatus;
+    readonly status: ClaimStatus;
     /** What is being coordinated. */
     readonly target: EntityRef;
     /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
@@ -577,14 +593,14 @@ export interface Intent {
     readonly description?: string;
     /** Participant holding it. */
     readonly heldBy: string;
-    readonly participantKind: 'human' | 'agent';
+    readonly participantKind: ParticipantKind;
     /**
-     * Ms-epoch the holder opened it. Optional until the lease wire carries
+     * Epoch-ms the holder opened it. Optional until the lease wire carries
      * it — derived shapes (e.g. mapped from a presence frame) may omit it.
      */
-    readonly createdAt?: string;
-    /** Ms-epoch the server auto-expires it if the holder doesn't finish. */
-    readonly expiresAt: string;
+    readonly createdAt?: number;
+    /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
+    readonly expiresAt: number;
     /**
      * 0-based place in the FIFO line — present only when `status: 'queued'`
      * (`0` = next in line behind the holder). Absent for the active holder.

package/dist/types/streams.js

@@ -3,7 +3,7 @@
  *
  * Ablo treats humans and agents as participants on live application
  * entities. Participants announce what they are reading or editing,
- * claim intent before writing, and capture context watermarks before
+ * claim before writing, and capture context watermarks before
  * long-running AI work. The customer keeps their own schema, agent
  * stack, tools, prompts, and product policy; the sync engine provides
  * the shared coordination substrate.

package/dist/utils/asyncIterator.d.ts

@@ -5,7 +5,7 @@
  * The inputs are two functions:
  *
  *   - `subscribe(onChange): unsubscribe` — the existing reactivity
- *     primitive on `PresenceStream` / `IntentStream`. We register a
+ *     primitive on `PresenceStream` / `ClaimStream`. We register a
  *     listener that enqueues a value every time the source mutates;
  *     we tear it down in `return()`.
  *   - `getSnapshot()` — read the latest value to hand to the

package/dist/utils/asyncIterator.js

@@ -5,7 +5,7 @@
  * The inputs are two functions:
  *
  *   - `subscribe(onChange): unsubscribe` — the existing reactivity
- *     primitive on `PresenceStream` / `IntentStream`. We register a
+ *     primitive on `PresenceStream` / `ClaimStream`. We register a
  *     listener that enqueues a value every time the source mutates;
  *     we tear it down in `return()`.
  *   - `getSnapshot()` — read the latest value to hand to the

package/dist/wire/frames.d.ts

@@ -52,7 +52,7 @@ export interface CommitOperation {
 }
 /**
  * Client → Server single named-mutation frame. The named-mutator write
- * primitive (intent + args), as opposed to the raw-op {@link CommitMessage}
+ * primitive (claim + args), as opposed to the raw-op {@link CommitMessage}
  * batch. Server-side mutator dispatch resolves `mutatorName` against the
  * host-provided registry.
  */
@@ -78,7 +78,7 @@ export interface CommitMessage {
         /**
          * Dormant agent-task lineage field. The SDK no longer populates it —
          * turns/tasks were removed and write attribution now rides on the
-         * claim (`intent`) id plus the server-stamped actor/capability. Kept
+         * claim (`claim`) id plus the server-stamped actor/capability. Kept
          * optional for wire-compat; when present the Hub still validates and
          * threads it onto `caused_by_task_id`, but client writes leave it
          * `null` (the audit pane treats null as "no prompt-side context").

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