@abloatai/transaction 0.37.0

package/CONVENTIONS.md

@@ -0,0 +1,83 @@
+# Transaction-core conventions
+
+`@abloatai/transaction` is the settlement core. It defines, authorizes, orders, and
+settles changes; it does not materialize a local copy of rows or reconcile an
+optimistic client. Apply ADR 0013's five-second test before adding or moving a
+module:
+
+> If there were no UI and no offline mode, would this code still need to exist?
+
+Yes belongs here. IndexedDB, local stores, optimistic queues, bootstrap state,
+WebSocket lifecycle and reactive snapshots belong in `@abloatai/humans`.
+
+## One definition for boundary data
+
+Any shape that crosses a network boundary or is written to durable storage has
+one authoritative Zod schema. Export its TypeScript shape from that schema with
+`z.infer`, `z.input`, or `z.output`; do not maintain an unchecked parallel
+interface or literal union.
+
+Compose variants from the authoritative schema with Zod's `pick`, `omit`,
+`extend`, and unions. A deliberate in-process projection must derive its fields
+from the inferred type with `Pick`, `Omit`, or indexed access and document why it
+differs. The narrow exception is an import-free type leaf needed to break a
+runtime cycle: its one runtime schema must carry a bidirectional exact-type
+assertion and its preamble must name the type leaf as the owner. Do not use an
+equality assertion to justify two otherwise independent definitions.
+
+Handwritten interfaces remain appropriate for behavior contracts (methods) and
+in-process options that are neither parsed from the wire nor persisted. Those
+belong outside `src/wire/` and `src/transactions/settlement/`, so the two
+enforced directories keep a zero baseline rather than an exception list. When a
+port and the records crossing it are discovered together, split them: the shape
+stays in `settlement/`, the methods move out.
+
+Good definition sites include:
+
+- `src/wire/delta.ts` for the shared, client, and server delta projections.
+- `src/transactions/settlement/commitEnvelope.ts` for durable commit identity.
+- `src/transactions/settlement/pendingWrite.ts` for the persisted union a
+  durable-write adapter stores.
+- `src/durableWrites.ts` for the port that stores them — methods, so it lives
+  outside the enforced directories.
+- `src/transactionLayer.ts` for a behavior contract rather than serialized data.
+
+## File preambles state ownership
+
+Every boundary module starts with a short preamble that says:
+
+1. what responsibility the module owns;
+2. which schema or module is authoritative; and
+3. which client/server counterpart consumes it, including any intentional
+   compatibility or projection difference.
+
+Comments explain ownership and invariants. They do not repeat the field names
+that the schema already makes visible.
+
+## Enforcement
+
+CI rejects exported interfaces in `src/wire/` and
+`src/transactions/settlement/`. Those directories have a zero baseline: add a
+schema and infer the type instead of adding an exception. The import boundary is
+enforced separately by dependency-cruiser.
+
+A shape can also be duplicated without ever declaring a type, by writing a
+projection's output out member by member. CI rejects that for the claim locator,
+whose four projections live in `src/coordination/locator.ts`: a literal that
+assembles a target out of another target instead of spreading `wireTarget`,
+`modelTarget`, `streamTarget`, or `subTarget` fails
+`npm run check:locator-copies`. Its per-file baseline holds the two partial
+locators the projections cannot express, and ratchets down only.
+
+Run the focused checks from the repository root:
+
+```sh
+grep -RInE --include='*.ts' \
+  '^[[:space:]]*export[[:space:]]+interface[[:space:]]' \
+  packages/transaction/src/wire \
+  packages/transaction/src/transactions/settlement
+npm run check:locator-copies
+npm run graph:deps
+```
+
+The grep should print nothing; CI turns any match into a failure.

package/README.md

@@ -0,0 +1,48 @@
+<p align="center">
+  <a href="https://abloatai.com">
+    <img src="https://raw.githubusercontent.com/Abloatai/ablo/main/assets/banner.png" alt="Ablo" width="480" />
+  </a>
+</p>
+
+# @abloatai/transaction
+
+The canonical transaction contracts and headless HTTP runtime behind Ablo.
+
+Authoritative reads, atomic commits, idempotency, settlement, claims, and
+durable observation share one typed protocol here. The package has no React,
+MobX, IndexedDB, or WebSocket runtime.
+
+Application code should install the branded Ablo SDK:
+
+```sh
+npm install @abloatai/ablo
+```
+
+```ts
+import { Ablo } from '@abloatai/ablo';
+
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+
+const order = await ablo.orders.get({ id: orderId });
+
+await ablo.orders.update({
+  id: orderId,
+  data: { status: 'approved' },
+});
+```
+
+Use `@abloatai/transaction` directly only when building Ablo adapters,
+integrations, or infrastructure that must consume the canonical contracts.
+The branded SDK delegates to this package without exposing that ownership map
+in normal application imports.
+
+## Links
+
+- [Documentation](https://docs.abloatai.com)
+- [Quickstart](https://docs.abloatai.com/quickstart)
+- [API reference](https://docs.abloatai.com/api)
+- [Source](https://github.com/Abloatai/ablo/tree/main/packages/transaction)
+- [Apache-2.0 license](https://github.com/Abloatai/ablo/blob/main/LICENSE)

package/dist/ablo.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `Ablo` — the entry point to the coordination layer.
+ *
+ * The factory constructs the stateless client: typed model resources, commits,
+ * claims, and session minting over request/response HTTP. It holds no socket,
+ * no store, and no local copy of anything — the bearer credential is the
+ * identity and the server resolves it on every request. This is the client a
+ * server-side actor installs: an agent, a worker, a cron job, a route handler.
+ *
+ * ```ts
+ * import { Ablo } from '@abloatai/ablo';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * await ablo.tasks.update({ id: taskId, data: { status: 'done' } });
+ * ```
+ *
+ * The reactive materialiser — local store, live queries, presence rendering —
+ * is provided by `@abloatai/humans`, which layers
+ * above this one and shares the same `ablo.<model>` surface (ADR 0016).
+ */
+import { type AbloHttpClient, type AbloHttpClientOptions } from './transport/httpClient.js';
+import type { SchemaRecord } from './schema/schema.js';
+import type * as _Streams from './types/streams.js';
+import type * as _SchemaTypes from './schema/schema.js';
+import type * as _Global from './types/global.js';
+import type * as _Policy from './policy/types.js';
+import type * as _Http from './resources/httpResources.js';
+/**
+ * Create a coordination-layer client in one call.
+ *
+ * The core carries one transport today — request/response HTTP — so
+ * `transport: 'http'` is accepted for symmetry with the reactive package's
+ * factory and may be omitted. The duplex transport joins this slot when the
+ * socket carve lands (ADR 0016, follow-up 3a).
+ */
+export declare function Ablo<const S extends SchemaRecord>(options: AbloHttpClientOptions<S> & {
+    transport?: 'http';
+}): AbloHttpClient<S>;
+export declare namespace Ablo {
+    type ClaimTarget = _Streams.ClaimTarget;
+    type PresenceTarget = _Streams.PresenceTarget;
+    type Duration = _Streams.Duration;
+    type Peer = _Streams.Peer;
+    type Activity = _Streams.Activity;
+    type Claim = _Streams.Claim;
+    type ClaimHeartbeat = _Streams.ClaimHeartbeat;
+    type ClaimHeartbeatOptions = _Streams.ClaimHeartbeatOptions;
+    namespace Claim {
+        type Held<T = Record<string, unknown>, M = _Global.ResolveClaimMeta> = _Streams.HeldClaim<T, M>;
+        type WaitOptions = _Streams.ClaimWaitOptions;
+        type LeaseOptions = _Streams.ClaimLeaseOptions;
+    }
+    type Schema<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord> = _SchemaTypes.Schema<S>;
+    /**
+     * The schema this program has registered via `interface Register { Schema }`
+     * (falls back to a loose shape when unregistered). Use it where shared code
+     * needs "this app's schema" without importing a specific one.
+     */
+    type ResolveSchema = _Global.ResolveSchema;
+    /**
+     * The claim metadata shape this program has registered via
+     * `interface Register { ClaimMeta }` (falls back to a loose record when
+     * unregistered). Every claim surface reads `target.meta` as this.
+     */
+    type ResolveClaimMeta = _Global.ResolveClaimMeta;
+    namespace Schema {
+        type Model<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.Model<S, K>;
+        type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
+        type InferRow<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferRow<S, K>;
+        type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
+    }
+    type Conflict = _Policy.Conflict;
+    namespace Conflict {
+        type Kind = _Policy.ConflictKind;
+        type Operation = _Policy.ConflictOperation;
+        type Decision = _Policy.ConflictDecision;
+        type Policy = _Policy.ConflictPolicy;
+        type Axis = _Policy.ConflictAxis;
+    }
+    namespace Commit {
+        type Wait = _Http.CommitWait;
+        type OperationAction = _Http.ModelOperationAction;
+        type OperationInput = _Http.CommitOperationInput;
+        type CreateOptions = _Http.CommitCreateOptions;
+        type Receipt = _Http.CommitReceipt;
+        type Client = _Http.CommitResource;
+    }
+}
+//# sourceMappingURL=ablo.d.ts.map

package/dist/ablo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ablo.d.ts","sourceRoot":"","sources":["../src/ablo.ts"],"names":[],"mappings":"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"}

package/dist/ablo.js

@@ -0,0 +1,34 @@
+/**
+ * `Ablo` — the entry point to the coordination layer.
+ *
+ * The factory constructs the stateless client: typed model resources, commits,
+ * claims, and session minting over request/response HTTP. It holds no socket,
+ * no store, and no local copy of anything — the bearer credential is the
+ * identity and the server resolves it on every request. This is the client a
+ * server-side actor installs: an agent, a worker, a cron job, a route handler.
+ *
+ * ```ts
+ * import { Ablo } from '@abloatai/ablo';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * await ablo.tasks.update({ id: taskId, data: { status: 'done' } });
+ * ```
+ *
+ * The reactive materialiser — local store, live queries, presence rendering —
+ * is provided by `@abloatai/humans`, which layers
+ * above this one and shares the same `ablo.<model>` surface (ADR 0016).
+ */
+import { createAbloHttpClient, } from './transport/httpClient.js';
+/**
+ * Create a coordination-layer client in one call.
+ *
+ * The core carries one transport today — request/response HTTP — so
+ * `transport: 'http'` is accepted for symmetry with the reactive package's
+ * factory and may be omitted. The duplex transport joins this slot when the
+ * socket carve lands (ADR 0016, follow-up 3a).
+ */
+export function Ablo(options) {
+    return createAbloHttpClient(options);
+}
+//# sourceMappingURL=ablo.js.map

package/dist/ablo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ablo.js","sourceRoot":"","sources":["../src/ablo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,oBAAoB,GAGrB,MAAM,2BAA2B,CAAC;AAQnC;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAClB,OAA0D;IAE1D,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC"}

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

@@ -0,0 +1,123 @@
+/**
+ * Turns a write to one of your models into a Vercel AI SDK tool that handles
+ * multi-agent coordination for you, so an agent can contribute to shared state
+ * without silently overwriting another writer's concurrent change.
+ *
+ * The lower-level approach is to write your own `tool()` and call
+ * `ablo.<model>.update({ id, data, claim })` inside its `execute` — the right
+ * amount of control for a bespoke tool. This helper covers the common case
+ * instead: the agent produced some content and you want to save it into a shared
+ * row, without re-deriving optimistic concurrency each time. You declare the
+ * write:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/transaction/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 } });
+ * ```
+ *
+ * The {@link CoordinatedToolOptions.apply} function is the whole API: a pure
+ * function from the freshest row and the tool input to a patch, in the same
+ * spirit as a functional state update. Everything beneath it — reading the latest
+ * row, the compare-and-swap, backing off between retries, and releasing claims —
+ * is the runtime's job.
+ *
+ * ## Strategies
+ *
+ * Choose a strategy by how you want concurrent writers to relate. Each is
+ * designed to converge under many agents writing at once.
+ *
+ * - `'merge'` (the default) delegates to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The runtime
+ *   re-reads and re-applies `apply` on top of every concurrent write, backing off
+ *   between rounds, so many agents accumulate into one row and the model never
+ *   sees a conflict. This requires the model's agent conflict policy to be
+ *   `reject` (the default, or `agentsReject()`). A model that declares
+ *   `agentsNotify()` holds the losing write instead of rejecting it, which
+ *   defeats the reconcile loop — there, use `'claim'` or `'queue'`, or change the
+ *   policy.
+ *
+ * - `'claim'` gives mutual exclusion. It takes a fail-fast claim; if another
+ *   participant holds the row, it returns `{ status: 'claimed' }` and leaves the
+ *   decision to retry up to the model. A visible signal serves the agent better
+ *   than a hidden wait when it might spend its turn on something else. Works under
+ *   any conflict policy.
+ *
+ * - `'queue'` serializes writers over stateless HTTP. The tool polls to acquire
+ *   the claim until it is granted or `poll.timeoutMs` elapses, so the model calls
+ *   once and the tool waits its turn. Ordering is approximate rather than strict
+ *   first-in-first-out, which would require a persistent connection.
+ */
+import type { z } from 'zod';
+import type { ClaimParams, ModelRetrieveParams, ModelUpdateParams } from '../resources/modelOperations.js';
+import type { ModelUpdater, ContentionOptions } from '../resources/functionalUpdate.js';
+import type { HeldClaim } from '../types/streams.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'` means the change was saved. `'claimed'` means another participant
+     * holds the row, so nothing was saved and the model should try again.
+     * `'timeout'` means 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;
+    /** The schema of what the model may send, as a standard AI SDK / Zod input schema. */
+    inputSchema: z.ZodType<TInput>;
+    /** Which row this write targets, derived from the tool input. */
+    id: (input: TInput) => string;
+    /**
+     * Produces the write patch from the freshest current row and the tool input, as
+     * a pure function of the two. Under `'merge'` it re-runs on top of every
+     * concurrent write, so it must be idempotent with respect to its own
+     * contribution — for example, skip its change when its marker is already
+     * present — to stay correct across retries.
+     */
+    apply: (current: T, input: TInput) => Partial<T>;
+    /** How concurrent writers relate. Defaults to `'merge'`. */
+    strategy?: CoordinationStrategy;
+    /** Human-readable coordination metadata attached to the claim, used by the `'claim'` and `'queue'` strategies. */
+    claim?: {
+        description?: string;
+    };
+    /** How many reconcile rounds `'merge'` may take before it gives up with `AbloContentionError`. */
+    retries?: number;
+    /** Poll interval and overall timeout for `'queue'`. Defaults to 250ms and 30s. */
+    poll?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+}
+/**
+ * The small model port this helper needs. Both typed transports implement this
+ * exact contract; local-cache methods, wire receipts, and transport lifecycle
+ * deliberately stay out of an AI tool's dependency surface.
+ */
+export interface CoordinatedModel<T> {
+    get(params: ModelRetrieveParams): Promise<T | undefined>;
+    /** @deprecated Use `get({ id })`. */
+    retrieve?(params: ModelRetrieveParams): Promise<T | undefined>;
+    update(params: ModelUpdateParams<T>): Promise<T>;
+    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<T | undefined>;
+    claim(params: ClaimParams<T>): Promise<HeldClaim<T>>;
+}
+export declare function coordinatedTool<TInput, T = Record<string, unknown>>(model: CoordinatedModel<T>, options: CoordinatedToolOptions<TInput, T>): import("ai").Tool<TInput, CoordinatedWriteResult<T>>;
+//# sourceMappingURL=coordinatedTool.d.ts.map

package/dist/ai-sdk/coordinatedTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinatedTool.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/coordinatedTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAGH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC;;;;;OAKG;IACH,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,0CAA0C;IAC1C,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB,CAAC,MAAM,EAAE,CAAC;IAC/C,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,iEAAiE;IACjE,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,kHAAkH;IAClH,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,kGAAkG;IAClG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAID;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,GAAG,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzD,qCAAqC;IACrC,QAAQ,CAAC,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/D,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC1B,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CACtD;AAED,wBAAgB,eAAe,CAC7B,MAAM,EACN,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,MAAM,EAAE,CAAC,CAAC,wDA4EvE"}

package/dist/ai-sdk/coordinatedTool.js

@@ -0,0 +1,135 @@
+/**
+ * Turns a write to one of your models into a Vercel AI SDK tool that handles
+ * multi-agent coordination for you, so an agent can contribute to shared state
+ * without silently overwriting another writer's concurrent change.
+ *
+ * The lower-level approach is to write your own `tool()` and call
+ * `ablo.<model>.update({ id, data, claim })` inside its `execute` — the right
+ * amount of control for a bespoke tool. This helper covers the common case
+ * instead: the agent produced some content and you want to save it into a shared
+ * row, without re-deriving optimistic concurrency each time. You declare the
+ * write:
+ *
+ * ```ts
+ * import { coordinatedTool } from '@abloatai/transaction/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 } });
+ * ```
+ *
+ * The {@link CoordinatedToolOptions.apply} function is the whole API: a pure
+ * function from the freshest row and the tool input to a patch, in the same
+ * spirit as a functional state update. Everything beneath it — reading the latest
+ * row, the compare-and-swap, backing off between retries, and releasing claims —
+ * is the runtime's job.
+ *
+ * ## Strategies
+ *
+ * Choose a strategy by how you want concurrent writers to relate. Each is
+ * designed to converge under many agents writing at once.
+ *
+ * - `'merge'` (the default) delegates to the functional update
+ *   `ablo.<model>.update(id, current => apply(current, input))`. The runtime
+ *   re-reads and re-applies `apply` on top of every concurrent write, backing off
+ *   between rounds, so many agents accumulate into one row and the model never
+ *   sees a conflict. This requires the model's agent conflict policy to be
+ *   `reject` (the default, or `agentsReject()`). A model that declares
+ *   `agentsNotify()` holds the losing write instead of rejecting it, which
+ *   defeats the reconcile loop — there, use `'claim'` or `'queue'`, or change the
+ *   policy.
+ *
+ * - `'claim'` gives mutual exclusion. It takes a fail-fast claim; if another
+ *   participant holds the row, it returns `{ status: 'claimed' }` and leaves the
+ *   decision to retry up to the model. A visible signal serves the agent better
+ *   than a hidden wait when it might spend its turn on something else. Works under
+ *   any conflict policy.
+ *
+ * - `'queue'` serializes writers over stateless HTTP. The tool polls to acquire
+ *   the claim until it is granted or `poll.timeoutMs` elapses, so the model calls
+ *   once and the tool waits its turn. Ordering is approximate rather than strict
+ *   first-in-first-out, which would require a persistent connection.
+ */
+import { tool } from 'ai';
+import { AbloClaimedError, AbloNotFoundError } from '@abloatai/transaction/errors';
+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') {
+                // Read the freshest row, apply the patch, and commit it with a
+                // compare-and-swap; on any concurrent write, re-read and re-apply with
+                // backoff. The model never sees a conflict.
+                const row = await model.update(id, (current) => options.apply(current, input), {
+                    retries: options.retries,
+                });
+                return { status: 'written', row: row ?? undefined };
+            }
+            // The 'claim' and 'queue' strategies both acquire a claim, write under it,
+            // and release it. They differ only in what they do when the row is already
+            // held: 'claim' returns a signal to the model, while 'queue' waits and
+            // retries by polling to acquire.
+            const acquireWriteRelease = async () => {
+                const claim = await model.claim({
+                    id,
+                    queue: false,
+                    description: options.claim?.description,
+                });
+                try {
+                    const current = await model.get({ 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': poll to acquire the claim 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;
+                }
+            }
+        },
+    });
+}
+//# sourceMappingURL=coordinatedTool.js.map

package/dist/ai-sdk/coordinatedTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinatedTool.js","sourceRoot":"","sources":["../../src/ai-sdk/coordinatedTool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export { coordinatedTool, type CoordinationStrategy, type CoordinatedModel, type CoordinatedToolOptions, type CoordinatedWriteResult, } from './coordinatedTool.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/ai-sdk/index.js

@@ -0,0 +1,2 @@
+export { coordinatedTool, } from './coordinatedTool.js';
+//# sourceMappingURL=index.js.map

package/dist/ai-sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,GAKhB,MAAM,sBAAsB,CAAC"}