@abloatai/ablo 0.18.0 → 0.20.0

package/dist/types/streams.d.ts

@@ -100,7 +100,7 @@ export interface ContextChange {
  * `range`, `field`, and `meta` are generic coordination hints for
  * products like code editors, document editors, and design tools.
  */
-export interface EntityRef {
+export interface ClaimTarget {
     readonly type: string;
     readonly id: string;
     readonly path?: string;
@@ -110,11 +110,11 @@ export interface EntityRef {
 }
 /**
  * A pointer to one entity the participant is acting on. Either a
- * typed `EntityRef` (`{ type, id, ... }`), or a tuple
+ * typed `ClaimTarget` (`{ type, id, ... }`), or a tuple
  * `['Clause', 'cl_3']` for ergonomic inline use. The verb methods
  * below accept both.
  */
-export type PresenceTarget = EntityRef | readonly [type: string, id: string];
+export type PresenceTarget = ClaimTarget | readonly [type: string, id: string];
 /**
  * Reactive livestream of what every multiplayer participant is doing.
  * Every participant gets one; it's always on, always current.
@@ -336,27 +336,12 @@ export interface ClaimOptions extends ClaimLeaseOptions {
     readonly queue?: boolean;
 }
 export interface ClaimStream {
-    /**
-     * 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 `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.
-     *
-     * The frame ships on the open WS immediately. One method, one shape —
-     * the verb shortcuts (`editing`, `writing`, `announce`) and the
-     * scoped `claim(reason, opts)` overload were collapsed into this
-     * single primitive.
-     */
-    claim(target: PresenceTarget, opts?: ClaimOptions): ClaimHandle;
     /**
      * 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<ActiveClaim>;
+    readonly others: ReadonlyArray<Claim>;
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
@@ -425,7 +410,7 @@ export interface ClaimStream {
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveClaim>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<Claim>>;
 }
 /**
  * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a
@@ -452,95 +437,6 @@ export interface ClaimLost {
         readonly meta?: Record<string, unknown>;
     };
 }
-export interface ClaimDeclaration {
-    readonly target: EntityRef;
-    /** Human-readable reason — "rewriting title" / "restyling chart". */
-    readonly reason: string;
-    /**
-     * Seconds remaining until the server auto-expires this claim. An OUTPUT
-     * field carrying a concrete countdown, so it's a plain `number` — distinct
-     * from the input `ttl: Duration` (`'3m'`) you pass when announcing. Computed
-     * from `expiresAt - now`.
-     */
-    readonly ttlSeconds?: number;
-}
-/**
- * Handle returned from `announce(...)` / `analyzing(...)` / etc.
- *
- * Implements `Symbol.asyncDispose` so callers can write:
- *
- * ```ts
- * {
- *   await using work = participant.claims.analyzing(clause, { ttl: '3m' });
- *   // ... do the work; claim auto-revokes when the block exits
- * }
- * ```
- */
-/**
- * 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>;
-    };
-    /**
-     * The human-readable phase this claim represents — `'editing'`, `'writing'`,
-     * `'forecasting'`. The SAME word on every claim surface (inputs and outputs);
-     * distinct from the CRUD operation (`CommitOperationInput.action`). Defaults
-     * to `'editing'`. Serialized on the wire as `action`.
-     */
-    readonly reason: 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 ActiveClaim extends ClaimDeclaration {
-    readonly id: string;
-    readonly heldBy: string;
-    /**
-     * 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: ParticipantKind;
-    readonly description?: 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 claim, in one enum.
  * `active` = the current holder (the lock). `queued` = waiting in the FIFO
@@ -554,44 +450,70 @@ export interface ClaimWaitOptions {
     readonly pollInterval?: number;
     readonly signal?: AbortSignal;
 }
-/**
- * The coordination state of one entity. Self-describing on the wire via
- * `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 `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 Claim {
+export interface Claim<T = Record<string, unknown>> {
     readonly object: 'claim';
+    /** This claim's id. */
     readonly id: string;
-    readonly status: ClaimStatus;
+    /**
+     * Lifecycle state. `active` = the holder (the lock); `queued` = waiting in
+     * the FIFO line (carries `position`). Optional on shapes derived from a
+     * presence frame that don't carry it — a present entry is `active` by
+     * construction.
+     */
+    readonly status?: ClaimStatus;
     /** What is being coordinated. */
-    readonly target: EntityRef;
-    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
-     *  field on every claim surface; distinct from the CRUD operation. Serialized
-     *  on the wire as `action`. */
+    readonly target: ClaimTarget;
+    /**
+     * Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
+     * field on every claim surface; distinct from the CRUD operation. Defaults to
+     * `'editing'`.
+     */
     readonly reason: string;
     /** Peer-visible explanation of the work being performed. */
     readonly description?: string;
-    /** Participant holding it. */
-    readonly heldBy: string;
-    readonly participantKind: ParticipantKind;
+    /** Participant holding it. Absent on a handle you hold for yourself. */
+    readonly heldBy?: string;
     /**
-     * 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.
+     * Whether the holder is a user (session), agent, or system actor — so UIs
+     * style "agent editing X" vs "user editing X" without string-parsing
+     * `heldBy`. Present on observed claims; absent on your own fresh handle.
      */
+    readonly participantKind?: ParticipantKind;
+    /** Epoch-ms the holder opened it. */
     readonly createdAt?: number;
     /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
-    readonly expiresAt: number;
+    readonly expiresAt?: number;
+    /**
+     * Seconds remaining until auto-expiry — an OUTPUT countdown (plain `number`),
+     * distinct from the input `ttl: Duration` (`'3m'`) you pass when claiming.
+     */
+    readonly ttlSeconds?: 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.
+     * (`0` = next behind the holder). Absent for the active holder.
      */
     readonly position?: number;
+    /**
+     * 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 (uncontended) grant.
+     */
+    readonly waited?: boolean;
+    /**
+     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
+     * carrying the claim use it as the `readAt` stale guard. Present on a claim
+     * you hold.
+     */
+    readonly readAt?: number;
+    /** Row snapshot under the lease — present on a claim you hold. */
+    readonly data?: T;
+    /**
+     * Release the lease. Present only on a claim you HOLD (returned by
+     * `ablo.<model>.claim`); absent on observed peer claims.
+     */
+    release?(): Promise<void>;
+    /** Synchronously abandon the lease. Present only on a claim you hold. */
+    revoke?(): void;
+    /** Auto-release on `await using` scope exit. Present only on a held claim. */
+    [Symbol.asyncDispose]?(): PromiseLike<void>;
 }

package/dist/utils/json.d.ts

@@ -0,0 +1,39 @@
+/**
+ * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
+ *
+ * Why this exists as a first-class, exported util:
+ *
+ * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
+ * does not preserve object key order** (it reorders keys by length, then
+ * bytewise, and drops insignificant whitespace — see
+ * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
+ * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
+ * value, a different serialization.
+ *
+ * That bites any app that reconciles an Ablo row against an *external* state
+ * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
+ * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
+ * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
+ * in different orders, so it never matches — and the app re-applies the remote
+ * value on every render, clobbering in-flight edits and fighting the cursor.
+ *
+ * The fix is to compare order-insensitively. `deepEqual` does structural
+ * equality directly; `stableStringify` produces a canonical string (recursively
+ * sorted keys) for when you need a stable cache key / dependency value. The SDK
+ * already uses `deepEqual` internally for store-level echo detection; this
+ * module makes the same guarantee available to app authors so they don't each
+ * reinvent it.
+ *
+ * (If you need byte-exact key order preserved end-to-end, store the field in a
+ * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
+ * there, matching Postgres's `json` type behavior.)
+ */
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Canonical JSON serialization: recursively sorts object keys so two values that
+ * differ only in key order (e.g. a jsonb round-trip) produce the same string.
+ * Use this when you need a comparable/cacheable string rather than a boolean —
+ * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/utils/json.js

@@ -0,0 +1,88 @@
+/**
+ * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
+ *
+ * Why this exists as a first-class, exported util:
+ *
+ * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
+ * does not preserve object key order** (it reorders keys by length, then
+ * bytewise, and drops insignificant whitespace — see
+ * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
+ * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
+ * value, a different serialization.
+ *
+ * That bites any app that reconciles an Ablo row against an *external* state
+ * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
+ * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
+ * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
+ * in different orders, so it never matches — and the app re-applies the remote
+ * value on every render, clobbering in-flight edits and fighting the cursor.
+ *
+ * The fix is to compare order-insensitively. `deepEqual` does structural
+ * equality directly; `stableStringify` produces a canonical string (recursively
+ * sorted keys) for when you need a stable cache key / dependency value. The SDK
+ * already uses `deepEqual` internally for store-level echo detection; this
+ * module makes the same guarantee available to app authors so they don't each
+ * reinvent it.
+ *
+ * (If you need byte-exact key order preserved end-to-end, store the field in a
+ * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
+ * there, matching Postgres's `json` type behavior.)
+ */
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++) {
+            if (!deepEqual(av[i], bv[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Canonical JSON serialization: recursively sorts object keys so two values that
+ * differ only in key order (e.g. a jsonb round-trip) produce the same string.
+ * Use this when you need a comparable/cacheable string rather than a boolean —
+ * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
+ */
+export function stableStringify(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === 'object') {
+        const source = value;
+        return Object.keys(source)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = sortKeysDeep(source[key]);
+            return acc;
+        }, {});
+    }
+    return value;
+}

package/docs/coordination.md

@@ -25,6 +25,22 @@ one answer to "how do two agents not clobber each other" — then covers the
 (`claim` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
 claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
+> **Before anything else: one identity per agent.** Coordination excludes
+> *participants*, and a participant **is the key**, not the client object. The
+> server derives identity from the credential's scope — so **N clients sharing
+> one `sk_`/`ek_` are one participant**: they all see the same `heldBy`, never
+> queue behind each other, and a "second" claimer silently re-takes the lease it
+> already holds (no mutual exclusion). To get real per-agent exclusion, mint a
+> **distinct scoped `rk_` per agent** and bind a client to it:
+>
+> ```ts
+> const { token } = await ablo.sessions.create({ agent: { id: `agent-${i}` } }); // rk_
+> const agent = Ablo({ schema, apiKey: token }); // this agent's own participant
+> ```
+>
+> Now `agent-0` holds while `agent-1`/`agent-2` queue in FIFO order and drain in
+> turn. See [sessions](./sessions.md#agent-sessions-rk_) for the minting flow.
+
 ---
 
 ## The model — three layers, one decision

package/docs/debugging.md

@@ -0,0 +1,194 @@
+# Debugging & Logs
+
+By default the SDK is quiet — it logs only warnings and errors. When you're building a human + agent flow and want to *see* the coordination happen (who claimed what, who's waiting in line, who got preempted), turn on Ablo's diagnostic logging. Every line is prefixed `[Ablo]` so it's obvious which output is ours in a console full of other tools.
+
+## Turn it on
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { schema } from './ablo/schema';
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, debug: true });
+```
+
+`debug: true` is the simple switch. For finer control use `logLevel`, or set it without touching code via the `ABLO_LOG_LEVEL` environment variable.
+
+```ts
+Ablo({ schema, apiKey })                       // quiet — warnings + errors only (default)
+Ablo({ schema, apiKey, debug: true })          // everything (coordination + lifecycle)
+Ablo({ schema, apiKey, logLevel: 'info' })     // coordination + connection, no per-model noise
+```
+
+```bash
+ABLO_LOG_LEVEL=debug npm run dev               # same, from the environment
+```
+
+### Levels
+
+| Level | What it shows |
+|---|---|
+| `silent` | nothing |
+| `error` | failures only |
+| `warn` | **default** — warnings + errors |
+| `info` | the above + the **coordination trace** (claims, grants, queueing) + connection state |
+| `debug` | the above + internal lifecycle (per-model registration, store hydration) — the full firehose |
+
+Precedence: an explicit `logLevel` wins, then `debug: true` (⇒ `debug`), then `ABLO_LOG_LEVEL`, then the `warn` default. `debug: false` (or omitting it) just means "don't raise the level."
+
+> For watching coordination, **`logLevel: 'info'` is the sweet spot** — you get the claim trace without the per-model registration chatter that `debug` adds.
+
+## What you'll see — the coordination trace
+
+These lines (all at `info`) let you watch the human + agent handover you built:
+
+```
+[Ablo] claim: requesting documents:doc_42 for "editing" (will queue if contended)
+[Ablo] claim: queued for documents:doc_42 — position 2 of 3, waiting
+[Ablo] claim: granted 7f3c… — your turn (waited in queue)
+[Ablo] claim: rejected documents:doc_42 — held by agent_writer
+[Ablo] claim: lost documents:doc_42 (preempted or expired)
+[Ablo] claim: released documents:doc_42
+```
+
+Read it as the lifecycle of one claim:
+
+- **`requesting`** — your code (or an agent) called `ablo.<model>.claim(...)`. `(will queue if contended)` appears when you passed `{ queue: true }`.
+- **`queued … position N of M`** — the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
+- **`granted … your turn`** — you reached the head of the line; the lease is now yours and the row may have changed while you waited.
+- **`rejected … held by <who>`** — your claim was refused because someone else holds it (and the model's policy didn't let you in).
+- **`lost`** — you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
+- **`released`** — you (or `await using`'s scope exit) gave the lease back.
+
+## Where the logs run
+
+The coordination trace and the proactive credential refresh run **in the browser** (and any client that holds a live socket) — that's where the human + agent activity is. Server-side code that mints credentials or does one-shot reads won't emit the trace; it has no live session to narrate.
+
+## Bring your own logger
+
+Pass a `logger` to route Ablo's output into your own logging stack (Pino, Sentry breadcrumbs, etc.). A custom logger bypasses `debug`/`logLevel` entirely — you decide what to do with each level.
+
+```ts
+Ablo({
+  schema,
+  apiKey,
+  logger: {
+    debug: (...a) => {},
+    info: (...a) => myLogger.info({ ablo: a }),
+    warn: (...a) => myLogger.warn({ ablo: a }),
+    error: (...a) => myLogger.error({ ablo: a }),
+  },
+});
+```
+
+## Read the coordination in code — the activity log
+
+The console trace above is for *you*, at a terminal. To put the same activity **inside your app** — an activity feed, a "who's editing" badge, a Sentry breadcrumb trail — read it programmatically. Same events, three layers; pick by audience:
+
+| Layer | You get | Best for |
+|---|---|---|
+| `logger` (above) | `[Ablo]` text lines | watching a terminal |
+| `observability` | typed `ClaimEvent` / `ConflictEvent` objects | dashboards, alerting (Sentry / Datadog / OTel) |
+| `ClaimLog` | an ordered, **reactive** list of both | rendering an activity feed on a page |
+
+### The events
+
+Every claim state change is a `ClaimEvent`; every notify-instead-of-abort stale write (a write that succeeded but whose premise had moved) is a `ConflictEvent`:
+
+```ts
+interface ClaimEvent {
+  phase: 'acquired' | 'queued' | 'granted' | 'lost' | 'rejected' | 'expired';
+  model?: string; id?: string; field?: string;          // the claimed row
+  actor?: string; participantKind?: 'user' | 'agent' | 'system';
+  position?: number;   // FIFO position, when queued
+  reason?: string;     // why, on rejected
+  claimId?: string;
+}
+
+interface ConflictEvent {
+  clientTxId: string;
+  rows: { model: string; id: string; fields: string[]; writtenBy?: 'user' | 'agent' | 'system' }[];
+}
+```
+
+`phase` is past-tense — the state the claim just entered — and maps one-to-one to what arrives on the wire.
+
+### Collect them — `ClaimLog`
+
+`ClaimLog` records both into an ordered list. Hand it to `observability`, then read it back:
+
+```ts
+import Ablo, { ClaimLog } from '@abloatai/ablo';
+
+const log = new ClaimLog();
+const ablo = Ablo({ schema, apiKey, observability: log });
+
+// …run the agents…
+console.log(`${log}`);   // a printable, ⚠-marked timeline
+log.entries;             // ClaimLogEntry[] — every event, in order, with a `.line`
+log.collisions();        // just the rejected/lost claims + stale writes
+```
+
+It's also the simplest way to **assert** coordination in a test — no log scraping:
+
+```ts
+expect(log.collisions()).toHaveLength(0);   // no one stepped on anyone
+```
+
+### Show it on a page — reactive
+
+`ClaimLog.onChange` fires on every event and returns an unsubscribe — the exact shape `useSyncExternalStore` wants, so a live feed is a few lines:
+
+```tsx
+import { useSyncExternalStore } from 'react';
+import { ClaimLog } from '@abloatai/ablo';
+
+function ActivityFeed({ log }: { log: ClaimLog }) {
+  const entries = useSyncExternalStore(log.onChange, () => log.entries);
+  return (
+    <ul>
+      {entries.map((e) => (
+        <li key={e.seq} className={e.collision ? 'text-amber-600' : undefined}>{e.line}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+> `ClaimLog` lives in browser memory: it starts empty on load and shows events that arrive while mounted. For a feed that survives reload, persist `entries` yourself — but for a live coordination panel, the in-memory log is exactly right.
+
+For **"who holds *this* row right now"** (a badge, not a feed), don't use `ClaimLog` — read the reactive claim state directly. It re-renders on change with no extra wiring:
+
+```tsx
+const holder = useAblo((ablo) => ablo.documents.claim.state({ id }));   // Claim | null
+```
+
+See [React](./react.md) and [Coordination](./coordination.md) for the claim-read APIs.
+
+### Route to your own backend
+
+`ClaimLog` is one implementation of the `observability` slot. To push events into Sentry, Datadog, or OpenTelemetry instead, spread `noopObservability` and override just the two coordination hooks:
+
+```ts
+import Ablo, { noopObservability } from '@abloatai/ablo';
+
+const ablo = Ablo({
+  schema, apiKey,
+  observability: {
+    ...noopObservability,
+    captureClaim: (e) => {
+      if (e.phase === 'rejected') Sentry.captureMessage(`claim blocked: ${e.model}/${e.id} by ${e.actor}`);
+    },
+    captureConflict: (e) => Sentry.captureMessage(`stale write tx ${e.clientTxId} on ${e.rows.length} row(s)`),
+  },
+});
+```
+
+## Errors
+
+Ablo's thrown errors are typed and self-describing — `String(err)` (or logging it) yields one clean line, never a stack dump:
+
+```
+AbloValidationError [model_required_field_missing]: A required field was absent. (see https://docs.abloatai.com/errors#model_required_field_missing) [request_id: req_8Fk2aQ]
+```
+
+Branch on `err.code` (stable) — never on the message (rewordable). See [Client Behavior](./client-behavior.md) for the full error model and which codes are safe to retry.

package/docs/index.md

@@ -48,6 +48,7 @@ Three things stay true no matter how you use Ablo:
 - [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.
 - [API Reference](./api.md) — Model-by-model method shape.
 - [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
+- [Debugging & Logs](./debugging.md) — Turn on the `[Ablo]` coordination trace (`debug` / `logLevel`) to watch claims, queueing, and grants while you build — or read the same activity in code via `ClaimLog` to render an activity feed.
 - [Connect Your Database](./data-sources.md) — Keep canonical rows in your app database without giving Ablo database credentials.
 - [React](./react.md) — Provider, hooks, and reactive reads for React apps.
 - [API Keys](./api-keys.md) — Bearer tokens for the public API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",