@abloatai/ablo 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.25.0
+
+### Minor Changes
+
+- ca30064: Logical replication is now the documented default storage path, with self-service data-source registration from the CLI.
+  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
+  - **`ablo init` leads with logical replication** — the default storage mode is now `replication` (was `endpoint`); the generated env + next-steps point at `ablo connect` / `ablo connect --register`. The signed-endpoint and direct modes remain as the explicit fallback / legacy options.
+  - **`ablo status`** — a data-plane diagnostic that probes whether your registered source is reachable and replicating (failure-only reporting, so it never falsely reports healthy).
+  - **`ablo push`** — minor guard/UX refinements (deploy-target clarity).
+  - **Docs (README, `docs/data-sources.md`, `llms.txt`)** rewritten to the one-path model: Ablo consumes your database's logical-replication stream and your application owns the write path. The security wording is precise — a logical-replication connection requires the `REPLICATION` privilege (it is **not** a read-only SQL account), so reviews are not misled by a "read-only" claim.
+
+  No breaking changes to the SDK runtime API. The server-side WAL read cutover these CLI changes support ships by deploying the engine, not this package.
+
+## 0.24.0
+
+### Minor Changes
+
+- Multi-agent coordination for AI SDK tools + safer `ablo push`.
+  - **`coordinatedTool` (`@abloatai/ablo/ai-sdk`)** — one call turns an Ablo model
+    write into a Vercel AI SDK `tool()` with concurrency coordination handled, so an
+    AI agent can contribute to shared state without clobbering concurrent writers.
+    Three strategies: `merge` (default — delegates to the functional update's
+    compare-and-swap + backoff, self-healing accumulate), `claim` (mutual exclusion,
+    returns a `claimed` signal the model retries on), and `queue` (SQS-style
+    poll-acquire over HTTP). The `ai-sdk` entry now also documents the canonical
+    multi-agent coordination model (surface-the-signal + back-off laws, strategy
+    table).
+  - **`ablo push` guards** — `--dry-run`/`--plan` prints the deploy target, a
+    model-level diff vs the deployed schema, and git state, then exits without
+    applying. Production deploys now require a typed confirmation (and refuse an
+    uncommitted schema unless `--allow-dirty`); sandbox confirms interactively.
+    `--yes`/`-y` skips confirmation for CI.
+
 ## 0.23.0
 
 ### Minor Changes

package/README.md

@@ -55,11 +55,13 @@ claims are visible while the work is still in progress.
 [Version History & Migration Guide](./docs/migration.md)
 
 It works with the auth and database you already have. **In production, your
-database is the system of record.** Ablo is the transaction layer on top of it:
-realtime data is scoped to *sync groups* from your own identity, and every
-committed row lives in your Postgres. (Trying Ablo with no database yet? The
-hosted **sandbox** can host rows in Ablo's test plane — apiKey only, like
-Stripe test mode — so you can explore before pointing it at your Postgres.)
+database is the system of record.** Ablo is the sync + coordination layer on top
+of it: it consumes your Postgres' logical-replication stream, scopes realtime
+data to *sync groups* from your own identity, and your application keeps owning
+the write path — every row lives in your Postgres. (Trying Ablo with no database
+yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe test
+mode — so you can explore before pointing it at your Postgres. Test-mode only; in
+production every row lives in your database.)
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
@@ -92,11 +94,11 @@ what's configured at any time.
 
 **Keys & runtime.** Ablo needs Node 24+ and TypeScript 5+. Keys come in two of
 *your* environments — `sk_test_` and `sk_live_`, like Stripe — and `ablo login`
-mints both. Keep the key and the database URL in trusted server runtimes only.
-In the browser, `<AbloProvider>` authenticates with the signed-in user's
-session — never the raw key, never the database URL. Prefer the connection
-string never leaving your infrastructure? Expose a signed
-[Data Source endpoint](./docs/data-sources.md) instead and omit `databaseUrl`.
+mints both. Keep the key in trusted server runtimes only. In the browser,
+`<AbloProvider>` authenticates with the signed-in user's session — never the raw
+key. Your database is connected once, out of band, via `npx ablo connect`
+(logical replication); if it can't grant a replication role, expose a signed
+[Data Source endpoint](./docs/data-sources.md) instead.
 
 For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
@@ -175,8 +177,9 @@ const schema = defineSchema({
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
+// Your Postgres is connected once via `npx ablo connect` (logical replication) —
+// not passed here. Ablo tails its WAL; your rows never leave your database.
 
 await ablo.ready();
 
@@ -403,10 +406,12 @@ each other's changes in real time — that's the default, not a feature you turn
 - `useAblo(...)` gives React clients the live row, kept current automatically.
 - `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
-Always write through Ablo — either the SDK model methods
-(`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
-write straight to your own database instead, those changes won't reach connected
-clients.
+Your application owns the write path: writes that land in your database — through
+your own backend, your existing API, any path — are tailed off the WAL and fanned
+out to connected clients automatically (the Electric model). The SDK model
+methods (`ablo.<model>.create/update/delete`) and the HTTP write endpoint are the
+*JavaScript/agent* ergonomic surface — they participate in claims and confirmation
+— but they are not a requirement for your normal writes to show up.
 
 ## HTTP Writes
 
@@ -429,35 +434,39 @@ curl https://api.abloatai.com/v1/commits \
 
 ## Your Database
 
-In production, every schema model is backed by **your own database** — Ablo is
-the transaction layer on top of it. Two ways to connect it:
+In production, every schema model is backed by **your own database** — Ablo
+**consumes** it, never owns it. The model is Electric's (and PowerSync's, and
+Zero's): Ablo consumes your Postgres' logical-replication stream and fans the
+changes out; **your application continues to own the write path.** Two ways Ablo
+connects:
 
-| | How Ablo reaches your Postgres | Use when |
+| | How Ablo connects to your Postgres | Use when |
 | --- | --- | --- |
-| **Connection string** (primary) | `databaseUrl` at init — passed explicitly, never auto-read from the environment. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
-| **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
+| **Logical replication** (primary) | `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect --register` tells Ablo to replicate it. Ablo tails the WAL — it never runs DDL on, writes to, owns, or migrates your database. | Your database can grant a `REPLICATION` role (most can). |
+| **Signed endpoint** (fallback) | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed requests and your app touches its own database. Needs no database configuration. | Your database **can't** grant a replication role (a locked-down managed DB). |
 
-(No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
-omit `databaseUrl` and pass an `apiKey` only, like Stripe test mode — so you can
-try Ablo before connecting your Postgres.)
+(No database yet? A **sandbox** `sk_test` key lets you try Ablo's full API and
+coordination with throwaway **test data** — like Stripe test mode — before you
+connect your own Postgres. Test-mode only: in production your rows always live in
+your database and Ablo holds just the transaction log, never your data.)
 
-Same product, same truth either way: in production your database is the system of
-record. See
-[Connect Your Database](./docs/data-sources.md) for both shapes.
+Your database is the system of record. The old `databaseUrl` dial-in (Ablo
+holding a read/write connection) is **deprecated and being removed** — connect
+via logical replication instead. See
+[Connect Your Database](./docs/data-sources.md).
 
 ## Configuration
 
-`Ablo({ ... })` takes your schema, your key, and — in production — your database,
-either as an explicit `databaseUrl` here or as a signed
-[Data Source endpoint](./docs/data-sources.md) in your app. (`databaseUrl` is
-never auto-read from the environment; omit it to try Ablo against the hosted
-sandbox.) Every other option has correct defaults:
+`Ablo({ ... })` takes your schema and your key. Your database is connected
+**out of band** — once, via `npx ablo connect` (logical replication) or a signed
+[Data Source endpoint](./docs/data-sources.md) — not through the constructor.
+Every other option has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `—` | Your Postgres, registered as the data plane. **Must be passed explicitly — it is not auto-read from the environment.** If you have a `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose), `Ablo()` ignores it unless you pass `databaseUrl` explicitly. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead, or when trying Ablo against the hosted sandbox. |
+| `databaseUrl` | `string \| null` | `—` | **Deprecated — being removed.** The old dial-in (Ablo holding a read/write connection to your DB). Connect via `npx ablo connect` (logical replication) instead; Ablo tails your WAL rather than dialing in. See [Connect Your Database](./docs/data-sources.md). |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -512,7 +521,7 @@ contract; there are no retry or timeout knobs to tune.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
 - [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
-- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by connection string (`databaseUrl`) or signed endpoint; your database is the system of record either way.
+- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by logical replication (`npx ablo connect`) or, as a fallback, a signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.
 - [AI SDK Tool](./docs/examples/ai-sdk-tool.md) — use Ablo inside an AI SDK tool call.
 - [Server Agent](./docs/examples/server-agent.md) — schema-backed worker.

package/dist/ai-sdk/coordinated-tool.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `coordinatedTool` — the one-liner that turns an Ablo model write into a Vercel
+ * AI SDK tool with multi-agent coordination already handled, so an AI agent can
+ * contribute to shared state without ever silently clobbering a concurrent
+ * writer.
+ *
+ * The base `./ai-sdk` pattern (see index.ts) is "write your own `tool()` and
+ * call `ablo.<model>.update({ id, data, claim })` inside `execute`". That's the
+ * right amount of control when a tool does something bespoke. But the *common*
+ * case — "the agent produced some content; save it into the shared row" — should
+ * not require every integration to re-derive optimistic concurrency by hand. This
+ * collapses it to a declaration:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * import { z } from 'zod';
+ *
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   // strategy: 'merge'  ← the default
+ * });
+ *
+ * await streamText({ model, messages, tools: { saveSection } });
+ * ```
+ *
+ * `apply` is the whole API: a pure function of `(freshest row, tool input) →
+ * patch`, exactly like React's `setState(prev => next)`. Everything underneath —
+ * reading the latest row, the compare-and-swap, the jittered backoff between
+ * reconcile rounds, releasing claims — is the runtime's job, not yours.
+ *
+ * ## Strategies (pick by how writers should relate; all verified to converge
+ * under N-way agent contention)
+ *
+ * - `'merge'` *(default)* — delegates straight to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The SDK re-reads
+ *   and re-applies `apply` on top of every concurrent write and backs off between
+ *   rounds, so N agents *accumulate* into one row and the model never sees a
+ *   conflict. **Requires the model's agent conflict policy to be `reject`** (the
+ *   default, or `agentsReject()`); a model declaring `agentsNotify()` HOLDS the
+ *   losing write instead of rejecting it, which defeats the reconcile — use
+ *   `claim`/`queue` there, or switch the policy.
+ *
+ * - `'claim'` — mutual exclusion. Takes a fail-fast claim; if another participant
+ *   holds the row it returns `{ status: 'claimed' }` so the *model* decides to
+ *   retry (a legible signal beats a hidden wait when the agent might do something
+ *   better with its turn). Works regardless of conflict policy.
+ *
+ * - `'queue'` — fair-ish serialization over stateless HTTP, the SQS shape: a
+ *   client poll-acquire loop (true FIFO needs a socket) until the claim is granted
+ *   or `poll.timeoutMs` elapses. The model calls once and the tool waits its turn.
+ */
+import type { z } from 'zod';
+import type { ModelOperations } from '../client/createModelProxy.js';
+export type CoordinationStrategy = 'merge' | 'claim' | 'queue';
+/** The structured result the tool hands back to the model (or the caller). */
+export interface CoordinatedWriteResult<T> {
+    /**
+     * `'written'` — saved. `'claimed'` — another participant holds the row; NOT
+     * saved, the model should try again. `'timeout'` — the queue strategy could not
+     * acquire the row within `poll.timeoutMs`.
+     */
+    status: 'written' | 'claimed' | 'timeout';
+    /** The reconciled row, on `'written'`. */
+    row?: T;
+    message?: string;
+    /** On `'written'` via the `queue` strategy, how long the tool waited in line. */
+    waitedMs?: number;
+}
+export interface CoordinatedToolOptions<TInput, T> {
+    /** Tool description shown to the model. */
+    description: string;
+    /** What the model may send — a normal AI SDK / zod input schema. */
+    inputSchema: z.ZodType<TInput>;
+    /** Which row this write targets, derived from the tool input. */
+    id: (input: TInput) => string;
+    /**
+     * Produce the write patch from the freshest current row + the tool input — a
+     * pure `(prev, input) => next`. Under `merge` it re-runs on every concurrent
+     * write, so it must be idempotent w.r.t. its own contribution (e.g. skip if its
+     * marker is already present) to be safe across reconcile rounds.
+     */
+    apply: (current: T, input: TInput) => Partial<T>;
+    /** How concurrent writers relate. Defaults to `'merge'`. */
+    strategy?: CoordinationStrategy;
+    /** Human-legible coordination metadata attached to the claim (`claim`/`queue`). */
+    claim?: {
+        reason?: string;
+        description?: string;
+    };
+    /** Reconcile budget for `merge` (rounds before `AbloContentionError`). */
+    retries?: number;
+    /** Poll cadence / ceiling for `queue` (defaults 250ms / 30s). */
+    poll?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+}
+export declare function coordinatedTool<TInput, T = Record<string, unknown>, CreateInput = Partial<T>>(model: ModelOperations<T, CreateInput>, options: CoordinatedToolOptions<TInput, T>): import("ai").Tool<TInput, CoordinatedWriteResult<T>>;

package/dist/ai-sdk/coordinated-tool.js

@@ -0,0 +1,129 @@
+/**
+ * `coordinatedTool` — the one-liner that turns an Ablo model write into a Vercel
+ * AI SDK tool with multi-agent coordination already handled, so an AI agent can
+ * contribute to shared state without ever silently clobbering a concurrent
+ * writer.
+ *
+ * The base `./ai-sdk` pattern (see index.ts) is "write your own `tool()` and
+ * call `ablo.<model>.update({ id, data, claim })` inside `execute`". That's the
+ * right amount of control when a tool does something bespoke. But the *common*
+ * case — "the agent produced some content; save it into the shared row" — should
+ * not require every integration to re-derive optimistic concurrency by hand. This
+ * collapses it to a declaration:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * import { z } from 'zod';
+ *
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   // strategy: 'merge'  ← the default
+ * });
+ *
+ * await streamText({ model, messages, tools: { saveSection } });
+ * ```
+ *
+ * `apply` is the whole API: a pure function of `(freshest row, tool input) →
+ * patch`, exactly like React's `setState(prev => next)`. Everything underneath —
+ * reading the latest row, the compare-and-swap, the jittered backoff between
+ * reconcile rounds, releasing claims — is the runtime's job, not yours.
+ *
+ * ## Strategies (pick by how writers should relate; all verified to converge
+ * under N-way agent contention)
+ *
+ * - `'merge'` *(default)* — delegates straight to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The SDK re-reads
+ *   and re-applies `apply` on top of every concurrent write and backs off between
+ *   rounds, so N agents *accumulate* into one row and the model never sees a
+ *   conflict. **Requires the model's agent conflict policy to be `reject`** (the
+ *   default, or `agentsReject()`); a model declaring `agentsNotify()` HOLDS the
+ *   losing write instead of rejecting it, which defeats the reconcile — use
+ *   `claim`/`queue` there, or switch the policy.
+ *
+ * - `'claim'` — mutual exclusion. Takes a fail-fast claim; if another participant
+ *   holds the row it returns `{ status: 'claimed' }` so the *model* decides to
+ *   retry (a legible signal beats a hidden wait when the agent might do something
+ *   better with its turn). Works regardless of conflict policy.
+ *
+ * - `'queue'` — fair-ish serialization over stateless HTTP, the SQS shape: a
+ *   client poll-acquire loop (true FIFO needs a socket) until the claim is granted
+ *   or `poll.timeoutMs` elapses. The model calls once and the tool waits its turn.
+ */
+import { tool } from 'ai';
+import { AbloClaimedError, AbloNotFoundError } from '../errors.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function coordinatedTool(model, options) {
+    const strategy = options.strategy ?? 'merge';
+    return tool({
+        description: options.description,
+        inputSchema: options.inputSchema,
+        execute: async (input) => {
+            const id = options.id(input);
+            if (strategy === 'merge') {
+                // The setState of the data layer: read fresh → apply → CAS → re-read +
+                // re-apply with backoff on any concurrent write. Self-healing; the model
+                // never sees a conflict. (Backoff lives in the shared reconcile loop.)
+                const row = await model.update(id, (current) => options.apply(current, input), {
+                    retries: options.retries,
+                });
+                return { status: 'written', row: row ?? undefined };
+            }
+            // claim / queue both take a claim, write under it, and release. The only
+            // difference is what they do when the row is already held: claim returns the
+            // signal to the model; queue waits and retries (SQS-style poll-acquire).
+            const acquireWriteRelease = async () => {
+                const claim = await model.claim({
+                    id,
+                    queue: false,
+                    reason: options.claim?.reason,
+                    description: options.claim?.description,
+                });
+                try {
+                    const current = await model.retrieve({ id });
+                    if (current === undefined) {
+                        throw new AbloNotFoundError(`Cannot write ${id}: it does not exist (or is outside this credential's scope).`, [id]);
+                    }
+                    const row = await model.update({ id, data: options.apply(current, input), claim, wait: 'confirmed' });
+                    return { status: 'written', row };
+                }
+                finally {
+                    await claim.release();
+                }
+            };
+            if (strategy === 'claim') {
+                try {
+                    return await acquireWriteRelease();
+                }
+                catch (e) {
+                    if (e instanceof AbloClaimedError) {
+                        return { status: 'claimed', message: 'Another participant holds this row right now — it was NOT saved. Wait briefly and try again.' };
+                    }
+                    throw e;
+                }
+            }
+            // strategy === 'queue': SQS-style poll-acquire over stateless HTTP.
+            const interval = options.poll?.intervalMs ?? 250;
+            const timeout = options.poll?.timeoutMs ?? 30_000;
+            const start = Date.now();
+            for (;;) {
+                try {
+                    const result = await acquireWriteRelease();
+                    return { ...result, waitedMs: Date.now() - start };
+                }
+                catch (e) {
+                    if (e instanceof AbloClaimedError) {
+                        if (Date.now() - start >= timeout) {
+                            return { status: 'timeout', message: `Could not acquire the row within ${timeout}ms.` };
+                        }
+                        await sleep(interval);
+                        continue;
+                    }
+                    throw e;
+                }
+            }
+        },
+    });
+}

package/dist/ai-sdk/index.d.ts

@@ -71,6 +71,48 @@
  * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
+ *
+ * ## Multi-agent coordination — the canonical way
+ *
+ * When several agents (or agents + humans) write the SAME row concurrently, the
+ * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
+ * how smart the model is. The same model silently loses 3 of 4 concurrent
+ * contributions through a blind whole-row write, and lands all 4 through a
+ * coordinated one — because the coordinated write returns a *signal* the model
+ * (or the runtime) acts on. Two empirical laws fall out:
+ *
+ *   1. **Surface the signal.** A write that swallows the conflict and reports
+ *      success is the footgun. Every robust path returns a legible result
+ *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
+ *      clobbering. Reaching for a bigger model does not fix a silent write.
+ *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
+ *      re-collide. The shared reconcile loop already jitters its backoff; any
+ *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ *
+ * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
+ * "save the agent's contribution into the shared row":
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   strategy: 'merge', // 'merge' (default, self-healing) | 'claim' | 'queue'
+ * });
+ * ```
+ *
+ * | strategy | writers relate by | on contention | model conflict policy |
+ * |----------|-------------------|---------------|------------------------|
+ * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
+ * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
+ * | `queue`  | FIFO-ish (SQS)    | poll-acquire until granted / timeout | any |
+ *
+ * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
+ * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
+ * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
  */
 export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordination-context.js';
 export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';
+export { coordinatedTool, type CoordinationStrategy, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinated-tool.js';

package/dist/ai-sdk/index.js

@@ -71,6 +71,48 @@
  * `wrapWithMultiplayer` is optional. Use it when the whole model call is scoped
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
+ *
+ * ## Multi-agent coordination — the canonical way
+ *
+ * When several agents (or agents + humans) write the SAME row concurrently, the
+ * outcome is decided by **(write path) × (the model's conflict policy)**, NOT by
+ * how smart the model is. The same model silently loses 3 of 4 concurrent
+ * contributions through a blind whole-row write, and lands all 4 through a
+ * coordinated one — because the coordinated write returns a *signal* the model
+ * (or the runtime) acts on. Two empirical laws fall out:
+ *
+ *   1. **Surface the signal.** A write that swallows the conflict and reports
+ *      success is the footgun. Every robust path returns a legible result
+ *      (`reject` → re-read & retry; `claimed` → the model tries again) instead of
+ *      clobbering. Reaching for a bigger model does not fix a silent write.
+ *   2. **Back off.** Under N-way contention, writers that retry in lock-step just
+ *      re-collide. The shared reconcile loop already jitters its backoff; any
+ *      hand-rolled retry must too, or it exhausts its budget and drops a writer.
+ *
+ * `coordinatedTool` (below) encodes both. Prefer it over a hand-written tool for
+ * "save the agent's contribution into the shared row":
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/ablo/ai-sdk';
+ * const saveSection = coordinatedTool(ablo.documents, {
+ *   description: 'Save your section into the shared document.',
+ *   inputSchema: z.object({ text: z.string() }),
+ *   id: () => DOC_ID,
+ *   apply: (current, { text }) => ({ content: appendBlock(current.content, text) }),
+ *   strategy: 'merge', // 'merge' (default, self-healing) | 'claim' | 'queue'
+ * });
+ * ```
+ *
+ * | strategy | writers relate by | on contention | model conflict policy |
+ * |----------|-------------------|---------------|------------------------|
+ * | `merge`  | accumulate (CAS)  | re-read + re-apply (silent, backed off) | must be `reject` (default) |
+ * | `claim`  | mutual exclusion  | returns `{status:'claimed'}` → model retries | any |
+ * | `queue`  | FIFO-ish (SQS)    | poll-acquire until granted / timeout | any |
+ *
+ * Note: a model declaring `agentsNotify()` HOLDS a losing write instead of
+ * rejecting it, which defeats `merge`'s reconcile (the loser is dropped, not
+ * retried). Use `agentsReject()` for accumulate semantics, or `claim`/`queue`.
  */
 export { coordinationContextMiddleware, } from './coordination-context.js';
 export { wrapWithMultiplayer } from './wrap.js';
+export { coordinatedTool, } from './coordinated-tool.js';