@abloatai/ablo 0.11.0 → 0.11.2

package/dist/sync/ConnectionManager.js

@@ -20,18 +20,29 @@
  * Designed to be embedded by `BaseSyncedStore`: one instance per store,
  * started on first successful connect, disposed on teardown.
  *
- *   CONNECTED ──► OFFLINE ──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
- *                    │              │                    │
- *                    ▼              ▼                    ▼
- *             WAITING_FOR_NETWORK  SESSION_EXPIRED    BACKOFF ──► PROBING_NETWORK
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
  *
- * Includes two fixes over the original app-side FSM:
+ * Includes three fixes over the original app-side FSM:
  *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
  *      probing immediately when the network comes back, without
  *      waiting for the backoff timer to elapse.
  *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
  *      `attempt`) when `navigator.onLine === false` at max retries,
  *      instead of hard-reloading an already-offline browser.
+ *   3. A socket drop (`WS_DISCONNECTED`, typically code 1006) goes
+ *      STRAIGHT to `probing_network`, not the passive `offline` state.
+ *      1006 is browser-local and carries no connectivity signal, so on a
+ *      healthy machine no `online`/`offline` event ever fires — parking in
+ *      `offline` stranded recovery until the 30s watchdog, long enough for
+ *      queued commits to roll back. Only a genuine OS-level `NETWORK_LOST`
+ *      parks in `offline` and waits for the `online` event.
  */
 import { makeAutoObservable, runInAction } from 'mobx';
 import { getContext } from '../context.js';
@@ -142,8 +153,19 @@ export class ConnectionManager {
             case 'connected':
                 switch (event.type) {
                     case 'NETWORK_LOST':
-                    case 'WS_DISCONNECTED':
+                        // The OS reported the NIC down — park passively in `offline` and
+                        // wait for the `online` event. Probing a downed adapter is wasted
+                        // work.
                         return 'offline';
+                    case 'WS_DISCONNECTED':
+                        // The socket died (typically code 1006) but the OS network is
+                        // almost certainly fine — 1006 is generated locally when the TCP
+                        // conn vanishes and carries NO connectivity signal, so the browser
+                        // fires no online/offline event. Probe IMMEDIATELY rather than
+                        // landing in the passive `offline` dead-end (which only escaped via
+                        // the 30s watchdog, long after queued commits rolled back). The
+                        // probe fast-fails if we genuinely ARE offline → waiting_for_network.
+                        return 'probing_network';
                     case 'WS_SESSION_ERROR':
                     case 'BOOTSTRAP_FAILED_SESSION':
                         return 'session_expired';
@@ -301,7 +323,7 @@ export class ConnectionManager {
         }
     }
     // ── Side effects per state ───────────────────────────────────────────
-    onEnterState(state, _event) {
+    onEnterState(state, event) {
         switch (state) {
             case 'connected':
                 this.clearBackoffTimer();
@@ -314,6 +336,19 @@ export class ConnectionManager {
                 this.callbacks?.onDisconnectWebSocket();
                 break;
             case 'probing_network':
+                // A socket drop (`WS_DISCONNECTED`) now lands here directly so recovery
+                // starts immediately. Tear the dead socket down FIRST — this is what
+                // sets SyncWebSocket's `isManualClose=true` and suppresses its own
+                // scheduleReconnect, keeping the FSM the single reconnect authority on
+                // the human path. The teardown runs synchronously inside the
+                // `disconnected` emit, before `SyncWebSocket.onclose` checks the flag,
+                // so the timing matches the previous `offline`-entry teardown. We gate
+                // on the drop event specifically: the other paths into `probing_network`
+                // (TAB_VISIBLE re-validation, handshake retry, backoff elapse) must NOT
+                // tear down a socket that may still be live.
+                if (event.type === 'WS_DISCONNECTED') {
+                    this.callbacks?.onDisconnectWebSocket();
+                }
                 this.runProbe();
                 break;
             case 'waiting_for_network':

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.
+        model.consumeModifiedFields(Object.keys(updateInput));
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('update', actualModelName);
         const transaction = {
@@ -1990,16 +1999,19 @@ export class TransactionQueue extends EventEmitter {
     // model ever needs to surface previous-state outside `modifiedProperties`,
     // 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))
-                    continue;
-                prev[key] = change.old;
-            }
-        }
-        return prev;
+        // 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). `fallbackToLive: false` makes `Model.capturePreviousValues` OMIT
+        // any key it can't resolve from `modifiedProperties.old` / the original
+        // snapshot — `buildUndoOps` then drops an un-revertible inverse rather than
+        // inventing one. With no `updateInput` (full extract) fall back to every
+        // tracked field. `Model.capturePreviousValues` is the single before-image
+        // source shared with `RecordingTransaction.snapshotFields`.
+        const keys = updateInput
+            ? Object.keys(updateInput)
+            : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
+        return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
     }
     /**
      * 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 {
@@ -55,6 +60,9 @@ export interface DefaultSyncShape {
  * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
  * when an expected key is absent. Exported from the package root so the module
  * augmentation merges into this declaration.
+ *
+ * The `Schema` augmentation key holds the type produced by `defineSchema`, so
+ * the same noun reads consistently here and in {@link ResolveSchema}.
  */
 export 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/dist/types/streams.d.ts

@@ -57,28 +57,6 @@ export interface AgentDelta {
     causedByTaskId?: string | null;
     createdAt: string;
 }
-/**
- * A reference to whoever's authority bounds a joined participant.
- * The spawned participant can never see or do more than this principal.
- * 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)
- *   • omitted          — the API key on the Ablo client is the ceiling
- */
-export type Principal = SessionRef | AgentRef;
-export interface SessionRef {
-    readonly kind: 'session';
-    readonly id: string;
-    readonly userId: string;
-    readonly organizationId: string;
-}
-export interface AgentRef {
-    readonly kind: 'agent';
-    readonly id: string;
-    readonly capabilityToken: string;
-}
 /**
  * Flat snapshot view returned from `participant.snapshot(...)`.
  *

package/dist/utils/mobx-setup.js

@@ -145,6 +145,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         'propertyChanged',
         'markAsPersisted',
         'clearChanges',
+        'consumeModifiedFields',
         'updateFromData',
         'applyChanges',
     ];

package/docs/api-keys.md

@@ -12,6 +12,55 @@ The key identifies the Ablo account. Application code does not pass an organizat
 
 "Trusted" means the runtime can hold a secret: a backend or other server-side environment a browser can't read. Browser and app clients use the same `@abloatai/ablo` import but authenticate differently — they never carry a secret key.
 
+## Which credential to use
+
+There's **one field — `apiKey`** — and what you pass depends on **where the code runs**.
+Pick your row:
+
+| Where your code runs | What to pass | Example |
+|---|---|---|
+| **Server / worker / CLI** (can hold a secret) | your secret `sk_` — it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
+| **Browser — read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
+| **Browser — writing as the signed-in user** | a function that fetches a short-lived per-user token from your own backend | `Ablo({ schema, apiKey: () => fetch('/api/ablo-session').then((r) => r.text()) })` |
+
+That's the whole story: one knob, filled by audience.
+
+**Coming from Stripe? It's the same key model, same prefixes:**
+
+| Stripe | Ablo | Where it goes |
+|---|---|---|
+| publishable `pk_` (client-safe) | `pk_` | browser — read-only |
+| secret `sk_` (server, full) | `sk_` | server — full authority |
+| restricted `rk_` (granular) | `rk_` | scoped agent sessions (`sessions.create({ agent, can })`) |
+| ephemeral key (client, customer-scoped) | `ek_` | per-user browser sessions (`sessions.create({ user })`) |
+
+Mode lives in the prefix too — `sk_test_` / `sk_live_` — exactly like Stripe. The
+`apiKey` resolver fetching an `ek_` is Ablo's ephemeral-key flow: server mints, client holds.
+
+**Why a function for browser writes?** Anything you ship to a browser must be public, and a
+public `pk_` is **read-only** — it can't carry one specific user's write authority. So when
+the browser writes *as the logged-in user*, your backend (which holds the secret `sk_` and
+knows who's signed in) mints a short-lived per-user token with `sessions.create({ user })`,
+and the browser's `apiKey` function fetches it. You don't manage refresh — the SDK calls the
+function once before connecting and then keeps the token fresh (re-mint before expiry, and on
+tab-focus / network-online / device-wake). This is the Stripe ephemeral-key / Supabase
+session model. For a read-only app you don't need any of this — just the `pk_` above.
+
+Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
+code passes nothing. The secret `sk_` (and `databaseUrl`) are **server-only** — never in a
+browser bundle. There is no `getToken`, `authEndpoint`, or `as` option — `apiKey` (a string,
+or a function for the browser-write case) is the single credential knob.
+
+### Minting per-user / agent tokens (server-side, with your `sk_`)
+
+| Mint | Call | Result |
+|---|---|---|
+| Human end-user session | `await server.sessions.create({ user: { id } })` | `ek_` (full user authority) |
+| Scoped delegated agent | `await server.sessions.create({ agent: { id }, can: { Task: ['update'] } })` | `rk_` (scoped to `can`) |
+| Connect Ablo to your own Postgres | `Ablo({ schema, apiKey, databaseUrl })` (server-only) | dedicated tenant |
+
+The principal kind comes from *which* shape you pass — `{ user }` → `user`, `{ agent, can }` → `agent`.
+
 ## Server-Side API Keys
 
 Use API keys from trusted (server-side) runtimes:

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" },
@@ -167,8 +167,9 @@ side: it takes the claim and returns a `ClaimHandle`. Claims don't lock — if s
 already holds the row, `claim` waits for them to finish, re-reads the fresh row,
 then hands it to you, so you always proceed from current state. Default reads
 return the row even while someone is mid-edit; if a server read should not
-return a row while it's claimed, pass `ifClaimed: 'wait'` to wait for the claim
-to clear, or `ifClaimed: 'fail'` to error out instead.
+return a row while it's claimed, pass `ifClaimed: 'fail'` to error out instead.
+Reads never block on a claim — to wait for a row to free up, `claim({ id })` it
+(the claim queues fairly behind the holder).
 
 ```ts
 const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });

package/docs/client-behavior.md

@@ -29,16 +29,20 @@ 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. |
+| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (`get`/`getAll`, `onChange`, `watch`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `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

@@ -1,9 +1,10 @@
 # Coordination Reference
 
 Coordinate long-running work on a row so humans and agents don't clobber each
-other. Most writes need none of this — `ablo.<model>.update({ id, data })` is optimistic
-and the server rejects it if the row moved. Reach for `claim` only when you'll
-**hold a row across a slow gap** (read → LLM call → write).
+other. Most writes need none of this — a plain `ablo.<model>.update({ id, data })`
+is **last-write-wins** by default. For lost-update detection, take a claim or pass
+`readAt` / `onStale` yourself. Reach for `claim` only when you'll **hold a row
+across a slow gap** (read → LLM call → write).
 
 Claims don't lock. If another writer holds the row, `claim` waits for them,
 re-reads the fresh row, then hands it to you — so two writers serialize instead
@@ -29,17 +30,19 @@ 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. |
 
 **The one decision: do you hold the row across a slow gap (read → LLM call →
 write)?**
 
-- **No** (the common case — a single quick `update`): do nothing. `ablo.<model>.update`
-  is optimistically guarded by stale-context already; it rejects with
-  `AbloStaleContextError` if the row moved under you. This is the default and
-  needs no ceremony.
+- **No** (the common case — a single quick `update`): a plain `ablo.<model>.update`
+  is **last-write-wins** — it carries no `readAt`, so the server skips the stale
+  check and the write simply lands. That's fine for most fields. If you need
+  lost-update detection on a no-claim write, pass `readAt` + `onStale: 'reject'`
+  yourself and it rejects with `AbloStaleContextError` when the row moved under
+  you.
 - **Yes** (you'll reason for seconds while holding the row): `claim` it. The claim
   excludes other participants for the duration, queues contenders fairly, and —
   see below — your own writes under it stay stale-guarded too.
@@ -48,12 +51,13 @@ write)?**
 non-holder writing to a claimed row is rejected (`AbloClaimedError`) regardless of
 `readAt`. If you do hold it, your own writes are still stale-checked — a row that
 moved between your snapshot and your write still rejects with
-`AbloStaleContextError`. With no claim held, the stale check is the only
-protection, and it's automatic, which is why the no-claim path is safe by default.
-Presence (`claim.state`) never decides anything — read it to render, act on the
-errors. The two checks are independent: one rejects writes from people who don't
-hold the claim, the other rejects writes based on a stale snapshot, and the SDK
-adds the stale-check for you when you write under a claim, so you don't pass
+`AbloStaleContextError`. With no claim held and no `readAt`, there is **no**
+stale protection — the plain write is last-write-wins; opt into lost-update
+detection by passing `readAt` + `onStale` yourself. Presence (`claim.state`)
+never decides anything — read it to render, act on the errors. The two checks are
+independent: one rejects writes from people who don't hold the claim, the other
+rejects writes based on a stale snapshot, and the SDK adds the stale-check for you
+when you write under a claim **you took on this client**, so there you don't pass
 anything extra.
 
 ---
@@ -70,7 +74,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. |
@@ -92,6 +96,17 @@ a model row. It's what `claim.state()` returns and what observers render.
 
 ## Methods
 
+One word — "claim" — names four distinct things; keep them separate as you read:
+
+- **the lease (claim handle)** — the *object* returned by `ablo.<model>.claim({ id })`
+  (`ClaimHandle`, an `AsyncDisposable` with `.data` and `.release()`).
+- **acquiring a claim/lease** — the *verb* `ablo.<model>.claim({ id })`, the call
+  that takes the lease.
+- **`claim.state` / `claim.queue`** — the *inspection namespace* hanging off the
+  model, for reading who holds the row and who's lined up.
+- **the write's `claim` param** — `update({ id, data, claim })`, where you pass a
+  lease the proxy didn't take itself.
+
 Each method below follows one fixed shape: **signature · what it does ·
 parameters · returns · example**.
 
@@ -149,15 +164,19 @@ held. Server/model reads can choose a claimed policy:
 ```ts
 await ablo.weatherReports.retrieve({
   id: 'report_stockholm',
-  ifClaimed: 'wait',
-  claimedTimeout: 30_000,
+  ifClaimed: 'fail',
 });
 ```
 
-- `ifClaimed: 'return'` reads now and includes active work metadata.
-- `ifClaimed: 'wait'` waits for the active claim to clear before reading.
+- `ifClaimed: 'return'` (the default) reads now and includes active work metadata.
 - `ifClaimed: 'fail'` throws `AbloClaimedError` if the row is claimed.
 
+Reads never block on a claim — there is no `ifClaimed: 'wait'`. Waiting for a row
+to free up is a **claim-side** concern: take `ablo.<model>.claim({ id })` (it
+queues fairly behind the current holder and re-reads the fresh row once it's
+yours). Use `ifClaimed: 'fail'` when a read should simply refuse to proceed
+against a row someone else is mid-editing.
+
 ### `claim.state`
 
 ```ts
@@ -167,6 +186,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 |
@@ -262,19 +291,54 @@ try {
 }
 ```
 
+### `watch` — presence for a set of rows
+
+Reading or claiming a row auto-enrolls you in its sync group, which is enough for
+`claim.state`/`claim.queue` to observe co-participants. When you want to *hold*
+presence on a known set of rows — a deck's slides, a board's cards — and react to
+who joins or leaves, use `watch`:
+
+```ts
+await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+room.peers; // who else is here, live
+```
+
+`watch(ids, { ttl? })` opens a model-scoped presence/claim subscription and returns
+a participant handle (`.peers`, the scoped claim stream, `.leave()` / `await using`
+disposal). It is the model-scoped successor to the old top-level
+`ablo.participants.join({ scope })`. **WebSocket only** — presence needs a live
+socket, so `watch` is absent on the HTTP client (`Ablo({ transport: 'http' })`) and
+throws on any non-ws construction.
+
 ### Writing under a claim
 
 There is no separate "write" method on a claim — use the normal
-`ablo.<model>.update({ id, data })`. While you hold a claim on `id`, that `update` is
-automatically stale-guarded against the snapshot the claim took (`readAt` =
-snapshot watermark, `onStale: 'reject'`) and attributed to the claim's lease, so
-it rejects with [`AbloStaleContextError`](#errors) if the row changed under you.
+`ablo.<model>.update({ id, data })`. The auto-guarding holds **only when this same
+client took the claim** via `ablo.<model>.claim({ id })` (the proxy remembers the
+lease in-process): that `update` is then stale-guarded against the snapshot the
+claim took (`readAt` = snapshot watermark, `onStale: 'reject'`) and attributed to
+the claim's lease, so it rejects with [`AbloStaleContextError`](#errors) if the
+row changed under you.
 
 ```ts
 await using claim = await ablo.weatherReports.claim({ id });
 await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // guarded by the claim
 ```
 
+A claim handle minted by **another client** (or returned over HTTP) is not known
+to this proxy, so a plain `update` won't pick it up. Pass it explicitly:
+
+```ts
+await ablo.weatherReports.update({ id, data: { status: 'ready' }, claim: handle });
+```
+
+**Self-stale on a second write.** The claim's watermark is fixed at claim time
+and is **not** re-baselined as you write. So a *second* `update` under one held
+claim is stale-checked against the snapshot the claim took — which your *first*
+write already moved past — and rejects with `AbloStaleContextError` against your
+own earlier write. Re-read (and re-claim) between writes if you need to write the
+same row more than once under one claim.
+
 Claims are **enforced server-side**: if you `update`/`delete` a row that *another*
 participant holds, the commit is rejected with [`AbloClaimedError`](#errors) (`code:
 'entity_claimed'`). To proceed, `claim` the row yourself — the claim queues
@@ -306,7 +370,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/examples/existing-python-backend.md

@@ -57,8 +57,9 @@ export const ablo = Ablo({
 ```
 
 Mount the React provider near the app root. Build the browser client first —
-with an `authEndpoint` so it mints a short-lived session token instead of
-carrying the secret key — then pass it to the provider via `client`.
+with an `apiKey` resolver (an async `() => Promise<string | null>`) that fetches
+the short-lived session token your backend minted, instead of carrying the
+secret key — then pass it to the provider via `client`.
 
 ```tsx
 // web/app/providers.tsx
@@ -68,9 +69,12 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// Browser client: no secret key — `authEndpoint` mints the session token
-// server-side (see the session route below).
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+// Browser client: no secret key — the `apiKey` resolver fetches the session
+// token your server route mints (see the session route below).
+const ablo = Ablo({
+  schema,
+  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+});
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider client={ablo}>{children}</AbloProvider>;