@abloatai/ablo 0.29.3 → 0.30.1

package/docs/coordination.md

@@ -197,7 +197,7 @@ a model row. It's what `claim.state()` returns and what observers render.
 | `id` | `string` | The claim id (distinct from the target row id). |
 | `status` | `ClaimStatus` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'`. `active` = the holder; `queued` = waiting in line behind it. The other three are terminal states you only see on a claim you just finished — `committed` (released after a successful write), `expired` (TTL lapsed), `canceled` (released early). |
 | `target` | `EntityRef` | What is being coordinated (`{ model, id, field? }`). |
-| `reason` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. Serialized on the wire as `action`. |
+| `description` | `string` | Peer-visible description of the work — the sentence another participant reads to decide whether to wait or move on (`'rewriting the risk section'`). Defaults to `'editing'`. |
 | `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
 | `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). |
@@ -209,7 +209,7 @@ a model row. It's what `claim.state()` returns and what observers render.
   "id": "claim_8fJ2",
   "status": "active",
   "target": { "model": "weatherReports", "id": "report_stockholm" },
-  "reason": "editing",
+  "description": "editing",
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
   "createdAt": 1748160000000,
@@ -254,7 +254,7 @@ so two claimers can't both think they won.
 | name | type | required | description |
 |---|---|---|---|
 | `id` | `string` | yes | The row id — same id as `retrieve` / `update`. |
-| `options.reason` | `string` | no | Phase shown to observers (default `'editing'`). Serialized on the wire as `action`. |
+| `options.description` | `string` | no | Peer-visible description of the work, shown to observers (default `'editing'`). |
 | `options.field` | `string` | no | Field-level target, for fine-grained claimed-state badges. |
 | `options.queue` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
 | `options.maxQueueDepth` | `number` | no | Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of joining a line already `>= maxQueueDepth` deep. Omit to wait however deep the queue is. |
@@ -278,7 +278,17 @@ const weather = await weatherAgent.getWeather(report.location);
 await ablo.weatherReports.update({ id: report.id, data: { forecast: weather } });
 ```
 
-The claim releases when the `await using` scope exits — on return or throw.
+The claim releases when the `await using` scope exits — **on return and on
+throw.** The "on throw" is the whole reason to bind it with `await using`: if the
+work between the claim and the write fails — the agent call errors, validation
+rejects, you decide not to write — the scope unwinds, the lease is released, and
+the next waiter is promoted, with no `finally` to remember. And nothing reaches
+the server until `update`, so a failure *before* the write leaves the row exactly
+as it was: claiming and committing are separate steps, so a failure between them
+has nothing to roll back. (A failure *after* a successful write leaves that write
+committed — pass an idempotency key on the write if you replay the block.) The
+lower-level [`claim.release`](#claimrelease) shows the manual `try/finally`
+equivalent for when you hold a claim without `await using`.
 
 ### Claim-gated reads
 
@@ -334,7 +344,7 @@ is free.
 
 ```ts
 const who = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
-if (who) console.log(`${who.heldBy} is ${who.reason}`);
+if (who) console.log(`${who.heldBy} is ${who.description}`);
 ```
 
 Returns the active claim state when the row is held, or `null` when it's free:
@@ -344,7 +354,7 @@ Returns the active claim state when the row is held, or `null` when it's free:
   "id": "claim_8fJ2",
   "status": "active",
   "target": { "model": "weatherReports", "id": "report_stockholm" },
-  "reason": "editing",
+  "description": "editing",
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
   "expiresAt": 1748160030000
@@ -405,7 +415,7 @@ Releasing **promotes the head of the queue**: the next waiter receives the claim
 **Example**
 
 ```ts
-const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', reason: 'reviewing' });
+const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', description: 'reviewing' });
 const report = claim.data;
 try {
   const ok = await reviewExternally(report);
@@ -435,7 +445,7 @@ third of the TTL until release:
 ```ts
 await using claim = await ablo.reports.claim({
   id: 'report_q3',
-  reason: 'generating',
+  description: 'generating',
   ttl: '5m',
   heartbeat: true,               // or an explicit cadence: heartbeat: '2m'
   onHeartbeatLost: () => abortWork(),
@@ -475,6 +485,51 @@ A stateless worker holding **many** rows beats them all in one round trip:
 entry per extended lease. This is the socketless twin of the realtime
 keepalive, which already renews every held lease on each ping.
 
+### durability — what a claim survives
+
+A lease belongs to your **identity** — the participant behind the credential —
+not to the socket it was claimed on; the server keys each lease by participant
+and `claimId`. That one fact decides what a claim lives through.
+
+**A brief blip is transparent.** The realtime client reconnects on its own
+(exponential backoff), and on each reconnect it re-announces every claim it
+still holds, so the server renews those leases and peers never see them flicker.
+A heartbeat that would land while the socket is momentarily down is skipped
+rather than failed — the next tick retries once the connection is back. Nothing
+to write: hold the claim and keep working.
+
+**A crashed holder frees the claim quickly — and it is the keepalive, not the
+TTL, that does it.** A dead holder is caught whichever way fires first: a clean
+socket close releases immediately, and a silent socket that never sent a close
+frame (a crashed tab, a dropped NAT) is reaped on the keepalive cycle (a ~30s
+ping / 10s pong window) and released then. Either way the next waiter is
+promoted within tens of seconds. This reclaim is **per-connection**, and it runs
+whether or not the TTL is anywhere near lapsing. Release fires only when your
+**last** connection goes, so a second connection under the same identity keeps
+the claim held.
+
+**The TTL is the deeper floor — for when the server itself restarts.** The live
+claim roster is held in memory, so a server restart would lose it; the durable
+lease in the coordination store carries the TTL, and a reconnecting client
+re-announces its claims before that TTL lapses. So size `ttl` to cover a
+deploy or restart window, not your work duration — beating covers the work
+duration.
+
+**To hold a claim across a holder crash, give it a durable identity.** A claim
+that must outlive a single failure belongs to a process that stays up — a
+backend worker or agent with its own credential — rather than one ephemeral
+browser tab. On reconnect the SDK re-announces it; if the row was granted onward
+while you were gone, that re-announce comes back as `AbloClaimedError`
+(`claim_lost`) — re-claim (you rejoin the line fairly) and retry from the fresh
+snapshot.
+
+| the holder… | what happens to the claim |
+| --- | --- |
+| blips, then reconnects within the window | renewed automatically on reconnect — no interruption |
+| crashes or drops for good | released within one keepalive cycle; the queue advances |
+| still has a second live connection | survives — release fires only on the last connection |
+| loses the server to a restart | rides the TTL in the coordination store; re-announced on reconnect |
+
 ### `watch` — presence for a set of rows
 
 Reading or claiming a row auto-enrolls you in its sync group, which is enough for
@@ -548,7 +603,7 @@ inspect the `code`.
 
 | error | `code` | thrown when | carries |
 |---|---|---|---|
-| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away (holder TTL lapse on disconnect, or revoke) while you were holding or waiting. | `claims?` |
+| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, or was revoked — while you were holding or waiting. | `claims?` |
 | `AbloClaimedError` | `claim_queued` | **HTTP transport only.** A contended `claim` (default `queue: true`) could not block-wait for the lease (no socket), so it rejected immediately instead of queueing. Retryable — re-attempt the claim. | `claims?` |
 | `AbloClaimedError` | `grant_timeout` | The optional `timeoutMs` elapsed while you were still queued for a grant. | `claims?` |
 | `AbloClaimedError` | `queue_too_deep` | `claim` was passed `maxQueueDepth` and the wait line was already that deep when you tried to join — fail-fast instead of waiting. | `claims?` |

package/docs/data-sources.md

@@ -205,12 +205,9 @@ rows.
 > connecting a new database. They are the seams that caused painful onboarding,
 > and `ablo connect` exists precisely to replace them.
 
-These older shapes connected Ablo to a database two other ways: by handing Ablo a
-**connection string** to operate directly (`databaseUrl` on the client, committing
-writes itself behind row-level security), or by exposing a **signed Data Source
+This older shape connected Ablo to a database by exposing a **signed Data Source
 endpoint** built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`,
 with `ablo_outbox` / `ablo_idempotency` bookkeeping and a reverse-channel
-connector for VPCs). Both required Ablo to either operate your database or proxy
-every write, and both have been superseded by logical replication, where Ablo only
-reads your WAL. If you are maintaining one of these integrations, migrate it to
-`ablo connect` at the next opportunity.
+connector for VPCs). It required Ablo to proxy every write, and has been superseded
+by logical replication, where Ablo only reads your WAL. If you are maintaining one
+of these integrations, migrate it to `ablo connect` at the next opportunity.

package/docs/integration-guide.md

@@ -48,14 +48,12 @@ Every schema model is backed by **your own database**. The SDK call shape is the
 same everywhere.
 
 In this guide — an app that already owns its backend and database — keep
-`DATABASE_URL` inside your app and expose a signed Data Source endpoint: Ablo
-coordinates each write and your app commits it to your Postgres. Do not pass
-`databaseUrl` to `Ablo(...)` here; application and agent code use `ABLO_API_KEY`.
-
-If instead you want Ablo to connect to your Postgres directly, pass `databaseUrl`
-(a live, server-only option) to `Ablo(...)`. That and the sandbox-only `apiKey`
-shape are the other two start states — [Connect Your Database](./data-sources.md)
-is the single source of truth for all three.
+`DATABASE_URL` inside your app and connect it out of band: run `npx ablo connect`
+for logical replication (Ablo tails your WAL), or expose a signed Data Source
+endpoint where Ablo coordinates each write and your app commits it to your
+Postgres. Either way, application and agent code hold only `ABLO_API_KEY` — the
+client never sees a connection string. [Connect Your Database](./data-sources.md)
+is the single source of truth for both paths.
 
 ## Test With Sandboxes
 

package/docs/migration.md

@@ -234,9 +234,6 @@ The flat coordination methods are gone; everything lives under `claim`.
 + await ablo.task.claim.release(id)
 ```
 
-This release also added the `databaseUrl` option for the direct Postgres
-connector — additive, no migration required.
-
 ---
 
 ## 0.7.0 — legacy React hooks removed

package/docs/quickstart.md

@@ -215,11 +215,13 @@ of clobbering. Normal reads still work while the claim is held. If a server read
 should not return a row while someone else is mid-edit, 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).
-Call `handle.release()` when your work is done.
+Bind the handle with `await using` and the claim releases itself when the scope
+exits — on success or on a throw, so a failing agent call never leaves the row
+locked.
 
 ```ts
 // Claim the row so other participants serialize behind us while we work.
-const handle = await ablo.weatherReports.claim({
+await using handle = await ablo.weatherReports.claim({
   id: 'weather_stockholm',
   reason: 'checking_weather',
   ttl: '2m',
@@ -236,15 +238,13 @@ await ablo.weatherReports.update({
     forecast: weather.summary,
   },
 });
-
-await handle.release();
+// scope exit releases the claim — no manual release, even if the work threw
 ```
 
 Ablo does not fetch the weather. If another participant already holds the row,
 `claim` waits for them to finish, re-reads, and then hands you the fresh row.
 While you hold the claim, `update({ id, data })` rejects with `AbloStaleContextError`
-if someone else changed the row first — so you never overwrite work you didn't
-see. Call `handle.release()` once your work is done.
+if someone else changed the row first — so you never overwrite work you didn't see.
 
 ## Multiplayer and claimed work
 
@@ -262,9 +262,8 @@ if (active) {
   console.log(`${active.heldBy} is ${active.reason}`);
 }
 
-const handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' });
+await using handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' });
 await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
-await handle.release();
 ```
 
 Use `{ queue: false }` on `claim` when work should be skipped instead of queued

package/docs/schema-contract.md

@@ -104,14 +104,13 @@ the fresh row. Reads stay open; only acting on the row serializes.
 
 Every schema model is backed by your own database. There are three start states,
 all covered in [Connect Your Database](./data-sources.md) (the single source of
-truth): the sandbox (`apiKey` only, no database), a direct connection string
-(`databaseUrl` passed to `Ablo(...)`, a live, server-only option), or a signed
-Data Source endpoint where your app keeps the database credential and commits
-each write itself.
-
-If your database stays canonical behind a Data Source endpoint, do not pass
-`databaseUrl` to `Ablo(...)` — trusted runtimes use `ABLO_API_KEY`. Browser code
-goes through `<AbloProvider>` or a scoped session route, never a raw API key.
+truth): the sandbox (`apiKey` only, no database), logical replication set up with
+`npx ablo connect` (Ablo tails your WAL), or a signed Data Source endpoint where
+your app keeps the database credential and commits each write itself.
+
+Your database connects out of band, so the client holds only `ABLO_API_KEY` —
+never a connection string. Browser code goes through `<AbloProvider>` or a scoped
+session route, never a raw API key.
 
 ## Rules of thumb
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.29.3",
+  "version": "0.30.1",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -136,9 +136,9 @@
     "prepack": "node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs && npm run lint:mintlify",
-    "build:docs": "node scripts/build-mintlify-docs.mjs",
-    "lint:mintlify": "node scripts/build-mintlify-docs.mjs --check",
+    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs && npm run lint:docs-site",
+    "build:docs": "node scripts/build-blume-docs.mjs",
+    "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
     "lint:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",

package/dist/client/registerDataSource.d.ts

@@ -1,19 +0,0 @@
-export interface RegisterDataSourceInput {
-    /** The HTTP API base, for example `https://api.abloatai.com/api`. */
-    readonly baseUrl: string;
-    /** The secret key (`sk_…`) used to authenticate the call and derive the organization. */
-    readonly apiKey: string | null;
-    /** The Postgres connection string to register. */
-    readonly databaseUrl: string;
-    /** An optional Postgres schema; the server defaults to `public`. */
-    readonly schema?: string;
-    /** A custom fetch implementation for tests, proxies, or unusual runtimes. */
-    readonly fetchImpl?: typeof fetch;
-}
-/**
- * Posts the connection string to the data-source registration route. Resolves once
- * the organization's data plane points at this database; otherwise throws an
- * {@link AbloError} with code `datasource_registration_failed`, so `ready()`
- * surfaces the failure instead of quietly bootstrapping against the wrong store.
- */
-export declare function registerDataSource(input: RegisterDataSourceInput): Promise<void>;

package/dist/client/registerDataSource.js

@@ -1,66 +0,0 @@
-/**
- * Registers a direct database connection as an organization's data source.
- *
- * When a client is constructed with `databaseUrl`, the SDK calls this before
- * bootstrap so the server points the organization's data plane at that connection.
- *
- * It posts to `POST /v1/datasources`, falling back to the older
- * `POST /v1/datasource` route on a 404 so registration still works against an
- * earlier server.
- *
- * The organization is derived on the server from the API key; the caller never
- * sends an organization id. The connection string is sent once over TLS and is
- * never echoed back — the server stores it as a secret and returns only a safe
- * projection of the data source (host, database, schema).
- */
-import { AbloError } from '../errors.js';
-/**
- * Posts the connection string to the data-source registration route. Resolves once
- * the organization's data plane points at this database; otherwise throws an
- * {@link AbloError} with code `datasource_registration_failed`, so `ready()`
- * surfaces the failure instead of quietly bootstrapping against the wrong store.
- */
-export async function registerDataSource(input) {
-    if (!input.apiKey) {
-        throw new AbloError('databaseUrl requires an apiKey to register the database connection (the org is derived from the key).', { code: 'datasource_registration_failed' });
-    }
-    const doFetch = input.fetchImpl ?? fetch;
-    const base = input.baseUrl.replace(/\/+$/, '');
-    const body = JSON.stringify({
-        connectionString: input.databaseUrl,
-        ...(input.schema ? { schema: input.schema } : {}),
-    });
-    const post = async (endpoint) => {
-        try {
-            return await doFetch(endpoint, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${input.apiKey}`,
-                },
-                body,
-            });
-        }
-        catch (cause) {
-            throw new AbloError('Could not reach the Ablo API to register the database connection.', {
-                code: 'datasource_registration_failed',
-                cause,
-            });
-        }
-    };
-    let response = await post(`${base}/v1/datasources`);
-    if (response.status === 404) {
-        // The newer route is absent on an older server; use the earlier one.
-        response = await post(`${base}/v1/datasource`);
-    }
-    if (!response.ok) {
-        let detail = '';
-        try {
-            detail = (await response.text()).slice(0, 500);
-        }
-        catch {
-            // ignore body read failures — the status alone is enough to fail loud
-        }
-        throw new AbloError(`Database connection registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
-    }
-}