@abloatai/ablo 0.20.2 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.22.0
+
+### Minor Changes
+
+- Add the functional update form: `ablo.<model>.update(id, current => next)`.
+
+  The `setState(prev => next)` of the data layer. Pass a function of the latest
+  row and the SDK owns everything that used to be the caller's problem under
+  contention: it reads the freshest row, runs your updater, writes it as a
+  compare-and-swap against the row's watermark, and re-reads + re-runs on any
+  concurrent write. No claim, no per-participant identity, and no
+  `stale_context` / `claim_*` codes ever surface — correctness rides on the
+  watermark, so concurrent writers reconcile instead of silently clobbering. The
+  write either lands or throws a single `AbloContentionError` once its reconcile
+  budget is spent.
+
+  Identical guarantee on both transports (HTTP and WebSocket share one reconcile
+  loop). Return `null`/`undefined` from the updater to skip the write. Tune with
+  `{ retries, signal }`. Exports: `AbloContentionError`, `ModelUpdater`,
+  `ContentionOptions`, `DEFAULT_CONTENTION_RETRIES`.
+
+  The classic `update({ id, data })` form is unchanged.
+
+## 0.21.0
+
+### Minor Changes
+
+- Coordination observability now fires on BOTH transports. Previously `captureClaim`/`captureConflict` were emitted only by the WebSocket transport, so a `ClaimLog` (or any `observability` provider) handed to a stateless HTTP client — the transport server-side agents use via `Ablo({ transport: 'http' })` — stayed empty, and even on WebSocket a hard commit rejection went unrecorded. Fixed:
+  - **HTTP transport now emits.** `Ablo({ transport: 'http', observability })` records `claim` acquisition (`captureClaim`) and coordination-conflict rejections (`captureConflict`, code `stale_context` / `claim_conflict` / `entity_claimed`) on BOTH HTTP write doors (`commits.create` and per-model `ablo.<model>.update/create/delete`). The conflict names the collided rows — from the server's `conflicts` detail when present, otherwise the ops the write attempted. `observability` is now a documented option on the HTTP client.
+  - **WebSocket rejections now recorded.** A commit rejected by the conflict policy (`mutation_result` `success: false` with a coordination code) now calls `captureConflict`, mirroring the existing notify-on-success path. So `ClaimLog.collisions()` no longer silently misses rejected writes.
+
+  Net effect: a `ClaimLog` behaves identically regardless of transport — `entries`, `collisions()`, and `onChange` reflect the real coordination timeline for headless agent evals and live activity feeds alike.
+
 ## 0.20.2
 
 ### Patch Changes

package/dist/cli.cjs

@@ -276808,6 +276808,12 @@ var ERROR_CODES = {
   model_watch_not_configured: client("claim", "watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport)."),
   // ── stale context / idempotency (409) ──────────────────────────────
   stale_context: wire("conflict", 409, true, "The write carried a readAt watermark that is now stale; re-read and retry."),
+  // Raised by the functional `update(id, current => next)` form once its
+  // internal reconcile budget is exhausted — the row stayed continuously
+  // contended. Client-side: the SDK already retried; the caller decides whether
+  // to back off, raise `retries`, or move the row to the WebSocket transport.
+  contention_exhausted: client("conflict", "A functional update could not land after exhausting its reconcile budget; the row stayed continuously contended."),
+  update_aborted: client("conflict", "The functional update reconcile loop was aborted via its AbortSignal before the write landed."),
   idempotency_conflict: wire("conflict", 409, false, "The same Idempotency-Key was reused with a different request body."),
   idempotency_key_too_long: wire("validation", 400, false, "The supplied Idempotency-Key exceeds the maximum length."),
   // ── validation (400 / 422) ─────────────────────────────────────────

package/dist/client/Ablo.d.ts

@@ -28,6 +28,7 @@ import type { SyncStoreContract } from '../react/context.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import type { SyncGroupInput } from '../schema/roles.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
+import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
 import type { ClaimStream, ClaimWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
 import type { Claim, HeldClaim, Duration } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
@@ -579,6 +580,17 @@ export interface ModelClient<T = Record<string, unknown>> {
         readonly id: string;
         readonly data: Record<string, unknown>;
     }): Promise<CommitReceipt>;
+    /**
+     * Update under contention with a function of the latest state —
+     * `update(id, current => next)`, the `setState(prev => next)` of the data
+     * layer. The SDK reads the freshest row, runs your updater, writes it as a
+     * compare-and-swap against the row's watermark, and re-reads + re-runs on any
+     * concurrent write. No claim, no identity, no conflict codes surface: the
+     * write either lands or throws {@link AbloContentionError} once its reconcile
+     * budget is spent. Return `null`/`undefined` from the updater to skip the
+     * write (resolves to `undefined`).
+     */
+    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<CommitReceipt | undefined>;
     delete(params: ModelMutationOptions & {
         readonly id: string;
     }): Promise<CommitReceipt>;

package/dist/client/Ablo.js

@@ -37,6 +37,7 @@ import { createPresenceStream } from '../sync/createPresenceStream.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
 import { awaitClaimGrant } from '../sync/awaitClaimGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
+import { reconcileFunctionalUpdate } from './functionalUpdate.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
 // Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
@@ -1529,13 +1530,33 @@ export function Ablo(options) {
         };
     }
     function model(name) {
-        return {
-            retrieve(params) {
-                return retrieveModel(name, params.id, params);
-            },
-            async create(params) {
-                const id = params.id ?? createModelId();
-                await applyClaimedPolicy({ model: name, id }, params);
+        function updateModel(arg, updater, contention) {
+            if (typeof arg === 'string') {
+                const id = arg;
+                if (typeof updater !== 'function') {
+                    throw new AbloValidationError(`${name}.update('${id}', updater): the second argument must be an updater ` +
+                        `function (current) => next. To write a fixed value, use update({ id, data }).`, { code: 'write_options_invalid' });
+                }
+                return reconcileFunctionalUpdate(updater, contention, {
+                    model: name,
+                    id,
+                    readFresh: async () => {
+                        const read = await retrieveModel(name, id, {});
+                        return { data: read.data, stamp: read.stamp };
+                    },
+                    writeNext: (patch, readAt) => commits.create({
+                        readAt,
+                        onStale: 'reject',
+                        wait: 'confirmed',
+                        operations: [
+                            { action: 'update', model: name, id, data: patch },
+                        ],
+                    }),
+                });
+            }
+            const params = arg;
+            return (async () => {
+                await applyClaimedPolicy({ model: name, id: params.id }, params);
                 return commits.create({
                     claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
@@ -1544,17 +1565,18 @@ export function Ablo(options) {
                     ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
-                        {
-                            action: 'create',
-                            model: name,
-                            id,
-                            data: params.data,
-                        },
+                        { action: 'update', model: name, id: params.id, data: params.data },
                     ],
                 });
+            })();
+        }
+        return {
+            retrieve(params) {
+                return retrieveModel(name, params.id, params);
             },
-            async update(params) {
-                await applyClaimedPolicy({ model: name, id: params.id }, params);
+            async create(params) {
+                const id = params.id ?? createModelId();
+                await applyClaimedPolicy({ model: name, id }, params);
                 return commits.create({
                     claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
@@ -1564,14 +1586,15 @@ export function Ablo(options) {
                     wait: params.wait,
                     operations: [
                         {
-                            action: 'update',
+                            action: 'create',
                             model: name,
-                            id: params.id,
+                            id,
                             data: params.data,
                         },
                     ],
                 });
             },
+            update: updateModel,
             async delete(params) {
                 await applyClaimedPolicy({ model: name, id: params.id }, params);
                 return commits.create({

package/dist/client/ApiClient.d.ts

@@ -9,9 +9,16 @@ import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions,
 import type { SchemaRecord } from '../schema/schema.js';
 import type { Duration } from '../utils/duration.js';
 import type { Claim } from '../types/streams.js';
+import type { SyncObservabilityProvider } from '../interfaces/index.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
     readonly bootstrapBaseUrl?: string | undefined;
+    /**
+     * Observability provider forwarded from `Ablo({ observability })`. The HTTP
+     * transport emits the same claim/conflict seams as the WS transport so a
+     * `ClaimLog` works identically for headless (server-agent) evals.
+     */
+    readonly observability?: SyncObservabilityProvider;
 };
 export interface AbloApiClaims {
     create(options: ClaimCreateOptions): Promise<Claim>;

package/dist/client/ApiClient.js

@@ -6,6 +6,7 @@
  * nouns directly to HTTP routes on sync-server.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.js';
+import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
@@ -28,6 +29,38 @@ export function createProtocolClient(options) {
         databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
+    // Observability seam for the STATELESS HTTP transport. The WS transport emits
+    // claim/conflict events from SyncWebSocket; the HTTP path (server-side agents,
+    // `transport: 'http'`) emitted nothing, so a `ClaimLog` handed to a headless
+    // agent eval stayed empty. Mirror the two WS seams here: claim acquired +
+    // coordination-conflict rejection. No-op when no provider is configured.
+    const observability = options.observability;
+    // Shared by the two HTTP write doors (`commits.create` + per-model
+    // `mutateModel`): a rejected write whose code is a coordination conflict is
+    // the collision ClaimLog exists to surface. Prefer the server's `conflicts`
+    // detail (carried on the typed error / envelope); fall back to the rows the
+    // caller tried to write so the collision always names a target. Inert without
+    // a provider or for non-conflict errors. Never throws (capture is best-effort).
+    const recordCoordinationConflict = (error, clientTxId, fallbackRows) => {
+        if (!observability)
+            return;
+        const code = error?.code;
+        const isConflict = code === 'stale_context' ||
+            code === 'claim_conflict' ||
+            code === 'entity_claimed' ||
+            (typeof code === 'string' && code.startsWith('policy:'));
+        if (!isConflict)
+            return;
+        const rawConflicts = error?.conflicts;
+        const rows = Array.isArray(rawConflicts) && rawConflicts.length > 0
+            ? rawConflicts.map((r) => ({
+                model: typeof r.model === 'string' ? r.model : 'unknown',
+                id: typeof r.id === 'string' ? r.id : 'unknown',
+                fields: [],
+            }))
+            : fallbackRows.map((r) => ({ model: r.model, id: r.id, fields: [] }));
+        observability.captureConflict({ clientTxId, rows });
+    };
     const fetchImpl = options.fetch ?? globalThis.fetch;
     if (typeof fetchImpl !== 'function') {
         throw new AbloConnectionError('Ablo API client requires a fetch implementation. Pass `fetch` in Ablo({ ... }) for this runtime.', { code: 'fetch_unavailable' });
@@ -256,16 +289,29 @@ export function createProtocolClient(options) {
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
-            const body = await requestJson('/v1/commits', {
-                method: 'POST',
-                idempotencyKey: clientTxId,
-                body: JSON.stringify({
-                    clientTxId,
+            let body;
+            try {
+                body = await requestJson('/v1/commits', {
+                    method: 'POST',
                     idempotencyKey: clientTxId,
-                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
-                    operations,
-                }),
-            });
+                    body: JSON.stringify({
+                        clientTxId,
+                        idempotencyKey: clientTxId,
+                        claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
+                        operations,
+                    }),
+                });
+            }
+            catch (error) {
+                // Coordination collision over HTTP — surface it to observability on the
+                // same footing as the WS transport, then rethrow unchanged. Fall back to
+                // the ops we tried to write so the collision always names a row.
+                recordCoordinationConflict(error, clientTxId, operations.map((o) => ({
+                    model: typeof o.model === 'string' ? o.model : 'unknown',
+                    id: typeof o.id === 'string' ? o.id : 'unknown',
+                })));
+                throw error;
+            }
             // `requestJson` throws via `translateHttpError` on any non-2xx,
             // so reaching here implies success. Narrow `status` to the
             // `CommitWait`-compatible subset; `'rejected'` only appears on
@@ -511,11 +557,21 @@ export function createProtocolClient(options) {
             requestBody.id = id;
         if (data !== undefined)
             requestBody.data = data;
-        const body = await requestJson(path, {
-            method,
-            idempotencyKey: clientTxId,
-            body: JSON.stringify(requestBody),
-        });
+        let body;
+        try {
+            body = await requestJson(path, {
+                method,
+                idempotencyKey: clientTxId,
+                body: JSON.stringify(requestBody),
+            });
+        }
+        catch (error) {
+            // Per-model write door (`ablo.<model>.update/create/delete`) — the path
+            // the demo editor + server agents actually take. Capture coordination
+            // collisions here too; this single row IS the fallback target.
+            recordCoordinationConflict(error, clientTxId, [{ model: modelName, id }]);
+            throw error;
+        }
         // `requestJson` throws via `translateHttpError` on any non-2xx, so reaching
         // here implies success. Narrow `status` to the `CommitWait`-compatible
         // subset; `'rejected'` only appears on a thrown rejection body.
@@ -563,6 +619,14 @@ export function createProtocolClient(options) {
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
         async function claimImpl(params) {
             const claimId = await acquireClaim(params);
+            observability?.captureClaim({
+                phase: 'acquired',
+                claimId,
+                model: name,
+                id: params.id,
+                ...(params.field ? { field: params.field } : {}),
+                reason: params.reason ?? 'editing',
+            });
             const { data, stamp } = await retrieveModel(name, { id: params.id });
             const release = () => releaseClaim(params);
             return {
@@ -623,6 +687,37 @@ export function createProtocolClient(options) {
                 await releaseClaim({ id }).catch(() => { });
             }
         };
+        function updateModel(arg, updater, contention) {
+            // Functional form: update(id, current => next). The SDK owns the
+            // read-fresh → compute → compare-and-swap → reconcile loop; correctness
+            // rides on the row's watermark (readAt + onStale:'reject'), so no claim
+            // or per-participant identity is needed and contention never clobbers.
+            if (typeof arg === 'string') {
+                const id = arg;
+                if (typeof updater !== 'function') {
+                    throw new AbloValidationError(`${name}.update('${id}', updater): the second argument must be an updater ` +
+                        `function (current) => next. To write a fixed value, use update({ id, data }).`, { code: 'write_options_invalid' });
+                }
+                return reconcileFunctionalUpdate(updater, contention, {
+                    model: name,
+                    id,
+                    readFresh: async () => {
+                        const read = await retrieveModel(name, { id });
+                        return { data: read.data, stamp: read.stamp };
+                    },
+                    writeNext: (patch, readAt) => mutateModel('update', name, id, patch, {
+                        readAt,
+                        onStale: 'reject',
+                        wait: 'confirmed',
+                    }),
+                });
+            }
+            const params = arg;
+            return withMutationClaim(params.id, params, async (options) => {
+                await applyClaimedPolicy({ model: name, id: params.id }, options);
+                return mutateModel('update', name, params.id, params.data, options);
+            });
+        }
         return {
             claim,
             retrieve(params) {
@@ -638,12 +733,7 @@ export function createProtocolClient(options) {
                     return mutateModel('create', name, id, params.data, options);
                 });
             },
-            async update(params) {
-                return withMutationClaim(params.id, params, async (options) => {
-                    await applyClaimedPolicy({ model: name, id: params.id }, options);
-                    return mutateModel('update', name, params.id, params.data, options);
-                });
-            },
+            update: updateModel,
             async delete(params) {
                 return withMutationClaim(params.id, params, async (options) => {
                     await applyClaimedPolicy({ model: name, id: params.id }, options);

package/dist/client/auth.js

@@ -96,7 +96,13 @@ function activeProjectSlug(value) {
     return typeof slug === 'string' && slug.length > 0 ? slug : undefined;
 }
 function importNodeBuiltin(specifier) {
-    return import(specifier);
+    // Node-only runtime import (CLI credential snapshot). The call is dead in
+    // browser/edge builds — guarded by `process.versions.node` and `window`
+    // checks in the callers — but bundlers still try to resolve the dynamic
+    // `import()` and Turbopack fails the build on the unanalyzable specifier.
+    // The magic comments tell each bundler to emit the import verbatim and never
+    // resolve it. Keep both so webpack and Turbopack consumers are covered.
+    return import(/* webpackIgnore: true */ /* turbopackIgnore: true */ specifier);
 }
 async function readJsonIfPresent(path) {
     try {

package/dist/client/createModelProxy.d.ts

@@ -14,6 +14,7 @@
  * `claim.reorder`), and `onChange`. The factory returns a plain object; the
  * client assembles the `ablo.<model>` lookup table from these.
  */
+import { type ModelUpdater, type ContentionOptions } from './functionalUpdate.js';
 import type { MutationOptions } from '../interfaces/index.js';
 import type { ModelRegistry } from '../ModelRegistry.js';
 import type { ObjectPool } from '../ObjectPool.js';
@@ -402,6 +403,17 @@ export interface ModelOperations<T, CreateInput> {
     create(params: ModelCreateParams<T, CreateInput>): Promise<T>;
     /** Update an entity by id — optimistic, offline-first (see `create`). */
     update(params: ModelUpdateParams<T>): Promise<T>;
+    /**
+     * Update under contention with a function of the latest state —
+     * `update(id, current => next)`, the `setState(prev => next)` of the data
+     * layer. The SDK reads the freshest row, runs your updater, writes it as a
+     * compare-and-swap, and re-reads + re-runs on any concurrent write. Nothing
+     * about claims, identity, or conflict codes surfaces: the write either lands
+     * or throws {@link AbloContentionError} once its reconcile budget is spent.
+     * Return `null`/`undefined` from the updater to skip the write. Resolves to
+     * the reconciled row (or `undefined` when the updater opted out).
+     */
+    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<T | undefined>;
     /** Delete an entity by id — optimistic, offline-first (see `create`). */
     delete(params: ModelDeleteParams<T>): Promise<void>;
     /**

package/dist/client/createModelProxy.js

@@ -17,6 +17,7 @@
 import { autorun } from 'mobx';
 import { AbloClaimedError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
+import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { Model, modelAsRow } from '../Model.js';
 import { toMs } from '../utils/duration.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
@@ -414,57 +415,116 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 await autoLease?.release?.().catch(() => { });
             }
         }),
-        update: guard(async (params) => {
-            const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
-            if (autoClaim) {
-                const handle = await takeClaim({ ...autoClaim, id: params.id });
-                try {
-                    return await operations.update({ ...params, claim: handle });
+        // `update` is overloaded — classic `update({ id, data })` + functional
+        // `update(id, current => next)`. The IIFE keeps the shared error-guard
+        // wrapping while exposing the two public signatures (a plain `guard(...)`
+        // would collapse them to one).
+        update: (() => {
+            const updateImpl = guard(async (arg, updater, contention) => {
+                // Functional form: update(id, current => next). Same guarantee as the
+                // HTTP client (shared reconcile loop), implemented with this transport's
+                // own read-fresh + confirmed compare-and-swap. A forced server round-trip
+                // gets the latest row + watermark; the write is stale-guarded by it, so
+                // concurrent writers reconcile instead of clobbering — no claim needed.
+                if (typeof arg === 'string') {
+                    const id = arg;
+                    if (typeof updater !== 'function') {
+                        throw new AbloValidationError(`${registeredModelName}.update('${id}', updater): the second argument must ` +
+                            `be an updater function (current) => next. To write a fixed value, use ` +
+                            `update({ id, data }).`, { code: 'write_options_invalid' });
+                    }
+                    if (!collaboration) {
+                        throw new AbloValidationError(`${registeredModelName}.update(id, updater) needs the collaboration runtime ` +
+                            `(a live WebSocket) to read the row's watermark for its compare-and-swap. ` +
+                            `Use the standard Ablo({ schema, apiKey }) client.`, { code: 'model_claim_not_configured' });
+                    }
+                    return reconcileFunctionalUpdate(updater, contention, {
+                        model: registeredModelName,
+                        id,
+                        readFresh: async () => {
+                            // `type: 'complete'` forces the round-trip — the hydration ledger
+                            // would otherwise serve a possibly-stale local row for a hydrated id.
+                            await load({ where: [['id', id]], type: 'complete' });
+                            const fresh = objectPool.get(id);
+                            const snapshot = collaboration.createSnapshot(schemaKey, id);
+                            return {
+                                data: fresh ? modelAsRow(fresh) : undefined,
+                                stamp: snapshot.stamp,
+                            };
+                        },
+                        writeNext: async (patch, readAt) => {
+                            const model = objectPool.get(id);
+                            if (!model) {
+                                throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+                            }
+                            const effective = {
+                                wait: 'confirmed',
+                                readAt,
+                                onStale: 'reject',
+                            };
+                            model.applyChanges(patch);
+                            syncClient.update(model, effective);
+                            await waitForMutation(model, effective);
+                            return modelAsRow(model);
+                        },
+                    });
                 }
-                finally {
-                    await handle.release?.();
+                const params = arg;
+                const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+                if (autoClaim) {
+                    const handle = await takeClaim({ ...autoClaim, id: params.id });
+                    try {
+                        return await operations.update({ ...params, claim: handle });
+                    }
+                    finally {
+                        await handle.release?.();
+                    }
                 }
+                const { id } = params;
+                const model = objectPool.get(id);
+                if (!model)
+                    throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+                // If we hold a claim on this row, guard the write with its snapshot
+                // watermark + lease so it's stale-rejected and attributed to the claim.
+                const claimed = activeClaims.get(id);
+                const opts = mutationOptions(params);
+                const handle = isClaimHandle(params.claim) ? params.claim : undefined;
+                const effective = claimed
+                    ? {
+                        wait: 'confirmed',
+                        readAt: claimed.snapshot.stamp,
+                        onStale: 'reject',
+                        claimRef: { id: claimed.lease.id },
+                        ...opts,
+                    }
+                    : {
+                        // A carried handle engages the same stale guard as a claim this
+                        // proxy took itself — the watermark rides on the handle, so it
+                        // works across clients (HTTP-minted handles included).
+                        ...(handle?.readAt !== undefined
+                            ? {
+                                wait: 'confirmed',
+                                readAt: handle.readAt,
+                                onStale: 'reject',
+                            }
+                            : {}),
+                        ...opts,
+                        ...(handle ? { claim: { id: handle.id } } : {}),
+                    };
+                // Local user update: `applyChanges` keeps change tracking ON so
+                // the edited fields land in `modifiedProperties` and actually get
+                // sent to the server. (`updateFromData` is the hydration path and
+                // would discard the tracking → empty `input: {}` no-op mutation.)
+                model.applyChanges(params.data);
+                syncClient.update(model, effective);
+                await waitForMutation(model, effective);
+                return modelAsRow(model);
+            });
+            function update(arg, updater, contention) {
+                return updateImpl(arg, updater, contention);
             }
-            const { id } = params;
-            const model = objectPool.get(id);
-            if (!model)
-                throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
-            // If we hold a claim on this row, guard the write with its snapshot
-            // watermark + lease so it's stale-rejected and attributed to the claim.
-            const claimed = activeClaims.get(id);
-            const opts = mutationOptions(params);
-            const handle = isClaimHandle(params.claim) ? params.claim : undefined;
-            const effective = claimed
-                ? {
-                    wait: 'confirmed',
-                    readAt: claimed.snapshot.stamp,
-                    onStale: 'reject',
-                    claimRef: { id: claimed.lease.id },
-                    ...opts,
-                }
-                : {
-                    // A carried handle engages the same stale guard as a claim this
-                    // proxy took itself — the watermark rides on the handle, so it
-                    // works across clients (HTTP-minted handles included).
-                    ...(handle?.readAt !== undefined
-                        ? {
-                            wait: 'confirmed',
-                            readAt: handle.readAt,
-                            onStale: 'reject',
-                        }
-                        : {}),
-                    ...opts,
-                    ...(handle ? { claim: { id: handle.id } } : {}),
-                };
-            // Local user update: `applyChanges` keeps change tracking ON so
-            // the edited fields land in `modifiedProperties` and actually get
-            // sent to the server. (`updateFromData` is the hydration path and
-            // would discard the tracking → empty `input: {}` no-op mutation.)
-            model.applyChanges(params.data);
-            syncClient.update(model, effective);
-            await waitForMutation(model, effective);
-            return modelAsRow(model);
-        }),
+            return update;
+        })(),
         delete: guard(async (params) => {
             const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
             if (autoClaim) {

package/dist/client/functionalUpdate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The functional update — `ablo.<model>.update(id, current => next)`.
+ *
+ * This is the "just works under contention" surface. The developer expresses
+ * ONLY their intent — "given the latest row, here is the next state" — and the
+ * SDK owns everything else: read the fresh row + its watermark, run the updater,
+ * write it as a compare-and-swap against that watermark, and on any concurrent
+ * write re-read → recompute → retry. No claim, no identity, no transport
+ * awareness, and no `stale_context` / `claim_*` error codes ever reach the
+ * caller. The write either lands or, at the extreme, throws a single
+ * {@link AbloContentionError} after the reconcile budget is spent.
+ *
+ * Correctness comes from the `readAt` watermark + `onStale: 'reject'`
+ * (optimistic concurrency / compare-and-swap), NOT from participant identity —
+ * which is why it is immune to the shared-credential silent-clobber footgun and
+ * behaves identically on both transports. The HTTP and WebSocket clients inject
+ * the same two thunks ({@link ReconcileTransport}); the loop below is shared, so
+ * the guarantee can never drift between them — only the mechanism differs.
+ *
+ * The mental model is React's `setState(prev => next)`: pass a function of the
+ * current state, the runtime owns reconciliation.
+ */
+import { AbloContentionError } from '../errors.js';
+/**
+ * The functional form of an update: given the freshly-read row, return the
+ * fields to write. Return `null` / `undefined` to make NO write — a no-op the
+ * caller decided on after seeing the latest state (e.g. "already done").
+ */
+export type ModelUpdater<T> = (current: T) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
+/** Tuning for the functional update's internal reconcile loop. */
+export interface ContentionOptions {
+    /**
+     * Max reconcile rounds under contention before throwing
+     * {@link AbloContentionError}. Each round re-reads the latest row and re-runs
+     * your updater. Defaults to {@link DEFAULT_CONTENTION_RETRIES}.
+     */
+    readonly retries?: number;
+    /** Abort the reconcile loop (e.g. the request was cancelled). */
+    readonly signal?: AbortSignal;
+}
+/** Reconcile rounds before a hot row is declared permanently contended. */
+export declare const DEFAULT_CONTENTION_RETRIES = 16;
+/**
+ * Does this thrown error mean "another writer moved the row — re-read and
+ * retry" rather than a genuine failure to surface? These are the optimistic-
+ * concurrency signals the functional update reconciles against:
+ *   - `stale_context` — our `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted us (e.g. a human under `humansOverwrite`)
+ *   - `claim_queued`  — a holder is actively editing the row right now
+ */
+export declare function isReconcilableConflict(err: unknown): boolean;
+/**
+ * Transport-specific read/write the shared loop drives. Each client injects its
+ * own pair — that's the ONLY thing that differs between HTTP and WebSocket.
+ */
+export interface ReconcileTransport<T, R> {
+    readonly model: string;
+    readonly id: string;
+    /** Read the latest row + its watermark from the authoritative store. */
+    readFresh: () => Promise<{
+        readonly data: T | null | undefined;
+        readonly stamp: number;
+    }>;
+    /**
+     * Write the computed patch as a compare-and-swap against `readAt`. MUST throw
+     * a reconcilable conflict (`stale_context` / `claim_*`) when the watermark was
+     * overtaken — that rejection is what drives the next reconcile round.
+     */
+    writeNext: (patch: Partial<T>, readAt: number) => Promise<R>;
+}
+/**
+ * Run the read-fresh → compute → compare-and-swap → reconcile loop. Shared by
+ * both transports so the guarantee is provably identical. Returns the write's
+ * result, or `undefined` when the updater opted out of writing.
+ */
+export declare function reconcileFunctionalUpdate<T, R>(updater: ModelUpdater<T>, options: ContentionOptions | undefined, transport: ReconcileTransport<T, R>): Promise<R | undefined>;
+export { AbloContentionError };

package/dist/client/functionalUpdate.js

@@ -0,0 +1,87 @@
+/**
+ * The functional update — `ablo.<model>.update(id, current => next)`.
+ *
+ * This is the "just works under contention" surface. The developer expresses
+ * ONLY their intent — "given the latest row, here is the next state" — and the
+ * SDK owns everything else: read the fresh row + its watermark, run the updater,
+ * write it as a compare-and-swap against that watermark, and on any concurrent
+ * write re-read → recompute → retry. No claim, no identity, no transport
+ * awareness, and no `stale_context` / `claim_*` error codes ever reach the
+ * caller. The write either lands or, at the extreme, throws a single
+ * {@link AbloContentionError} after the reconcile budget is spent.
+ *
+ * Correctness comes from the `readAt` watermark + `onStale: 'reject'`
+ * (optimistic concurrency / compare-and-swap), NOT from participant identity —
+ * which is why it is immune to the shared-credential silent-clobber footgun and
+ * behaves identically on both transports. The HTTP and WebSocket clients inject
+ * the same two thunks ({@link ReconcileTransport}); the loop below is shared, so
+ * the guarantee can never drift between them — only the mechanism differs.
+ *
+ * The mental model is React's `setState(prev => next)`: pass a function of the
+ * current state, the runtime owns reconciliation.
+ */
+import { AbloError, AbloNotFoundError, AbloStaleContextError, AbloClaimedError, AbloContentionError, } from '../errors.js';
+/** Reconcile rounds before a hot row is declared permanently contended. */
+export const DEFAULT_CONTENTION_RETRIES = 16;
+/**
+ * Does this thrown error mean "another writer moved the row — re-read and
+ * retry" rather than a genuine failure to surface? These are the optimistic-
+ * concurrency signals the functional update reconciles against:
+ *   - `stale_context` — our `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted us (e.g. a human under `humansOverwrite`)
+ *   - `claim_queued`  — a holder is actively editing the row right now
+ */
+export function isReconcilableConflict(err) {
+    if (err instanceof AbloStaleContextError)
+        return true;
+    if (err instanceof AbloClaimedError) {
+        return err.code === 'claim_lost' || err.code === 'claim_queued';
+    }
+    return false;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Jittered backoff so N reconcilers retrying at once don't lock-step straight
+ * back into the same collision. Bounded; grows mildly with the attempt.
+ */
+function backoffMs(attempt) {
+    return 60 + attempt * 40 + Math.floor(Math.random() * 60);
+}
+/**
+ * Run the read-fresh → compute → compare-and-swap → reconcile loop. Shared by
+ * both transports so the guarantee is provably identical. Returns the write's
+ * result, or `undefined` when the updater opted out of writing.
+ */
+export async function reconcileFunctionalUpdate(updater, options, transport) {
+    const retries = options?.retries ?? DEFAULT_CONTENTION_RETRIES;
+    let lastConflict;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        if (options?.signal?.aborted) {
+            throw new AbloError(`Update of ${transport.model}/${transport.id} was aborted before it landed.`, { code: 'update_aborted' });
+        }
+        const { data, stamp } = await transport.readFresh();
+        if (data == null) {
+            throw new AbloNotFoundError(`Cannot update ${transport.model}/${transport.id}: it does not exist (or is ` +
+                `outside this credential's scope).`, [transport.id]);
+        }
+        const patch = await updater(data);
+        if (patch == null)
+            return undefined; // updater opted out after reading fresh
+        try {
+            return await transport.writeNext(patch, stamp);
+        }
+        catch (err) {
+            if (!isReconcilableConflict(err))
+                throw err; // genuine failure — surface it
+            lastConflict = err;
+            if (attempt < retries)
+                await sleep(backoffMs(attempt));
+        }
+    }
+    throw new AbloContentionError(transport.model, transport.id, retries + 1, {
+        cause: lastConflict,
+    });
+}
+// Re-exported so call sites import the loop + its terminal error from one place;
+// the class itself lives with the rest of the hierarchy in `errors.ts`.
+export { AbloContentionError };

package/dist/errorCodes.d.ts

@@ -159,6 +159,8 @@ export declare const ERROR_CODES: {
     readonly model_claim_not_configured: ErrorCodeSpec;
     readonly model_watch_not_configured: ErrorCodeSpec;
     readonly stale_context: ErrorCodeSpec;
+    readonly contention_exhausted: ErrorCodeSpec;
+    readonly update_aborted: ErrorCodeSpec;
     readonly idempotency_conflict: ErrorCodeSpec;
     readonly idempotency_key_too_long: ErrorCodeSpec;
     readonly write_options_invalid: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -163,6 +163,12 @@ export const ERROR_CODES = {
     model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
     stale_context: wire('conflict', 409, true, 'The write carried a readAt watermark that is now stale; re-read and retry.'),
+    // Raised by the functional `update(id, current => next)` form once its
+    // internal reconcile budget is exhausted — the row stayed continuously
+    // contended. Client-side: the SDK already retried; the caller decides whether
+    // to back off, raise `retries`, or move the row to the WebSocket transport.
+    contention_exhausted: client('conflict', 'A functional update could not land after exhausting its reconcile budget; the row stayed continuously contended.'),
+    update_aborted: client('conflict', 'The functional update reconcile loop was aborted via its AbortSignal before the write landed.'),
     idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),
     idempotency_key_too_long: wire('validation', 400, false, 'The supplied Idempotency-Key exceeds the maximum length.'),
     // ── validation (400 / 422) ─────────────────────────────────────────

package/dist/errors.d.ts

@@ -180,6 +180,29 @@ export declare class AbloStaleContextError extends AbloError {
         }>;
     });
 }
+/**
+ * The functional `update(id, current => next)` form exhausted its reconcile
+ * budget — the row stayed continuously contended (a hot row under sustained
+ * concurrent writes), so no attempt could land a compare-and-swap.
+ *
+ * This is the ONLY coordination concept the functional update ever surfaces, and
+ * only at the extreme: the SDK has already read-fresh → recomputed → retried on
+ * every stale/claim conflict on the caller's behalf. Catch it to back off and
+ * retry later, raise the `retries` budget, or move that row to the WebSocket
+ * transport (which parks writers in a fair FIFO queue instead of racing). The
+ * last underlying conflict that drove the final retry is on `.cause`.
+ */
+export declare class AbloContentionError extends AbloError {
+    readonly type: "AbloContentionError";
+    /** The contended model + row that could not be written. */
+    readonly model: string;
+    readonly id: string;
+    /** How many reconcile rounds were attempted before giving up. */
+    readonly attempts: number;
+    constructor(model: string, id: string, attempts: number, options?: {
+        cause?: unknown;
+    });
+}
 export interface ClaimContext {
     readonly id?: string;
     readonly claimId?: string;

package/dist/errors.js

@@ -196,6 +196,37 @@ export class AbloStaleContextError extends AbloError {
             this.conflicts = options.conflicts;
     }
 }
+/**
+ * The functional `update(id, current => next)` form exhausted its reconcile
+ * budget — the row stayed continuously contended (a hot row under sustained
+ * concurrent writes), so no attempt could land a compare-and-swap.
+ *
+ * This is the ONLY coordination concept the functional update ever surfaces, and
+ * only at the extreme: the SDK has already read-fresh → recomputed → retried on
+ * every stale/claim conflict on the caller's behalf. Catch it to back off and
+ * retry later, raise the `retries` budget, or move that row to the WebSocket
+ * transport (which parks writers in a fair FIFO queue instead of racing). The
+ * last underlying conflict that drove the final retry is on `.cause`.
+ */
+export class AbloContentionError extends AbloError {
+    type = 'AbloContentionError';
+    /** The contended model + row that could not be written. */
+    model;
+    id;
+    /** How many reconcile rounds were attempted before giving up. */
+    attempts;
+    constructor(model, id, attempts, options) {
+        super(`Could not update ${model}/${id} after ${attempts} attempts — the row stayed ` +
+            `continuously contended, so nothing was written. Retry later, raise \`retries\`, ` +
+            `or use the WebSocket transport for a fair FIFO queue.`, {
+            code: 'contention_exhausted',
+            ...(options?.cause !== undefined ? { cause: options.cause } : {}),
+        });
+        this.model = model;
+        this.id = id;
+        this.attempts = attempts;
+    }
+}
 function claimReason(claim) {
     if (!claim)
         return undefined;

package/dist/index.d.ts

@@ -49,6 +49,8 @@
  */
 export { Ablo } from './client/Ablo.js';
 export type { MutationExecutor } from './interfaces/index.js';
+export type { ModelUpdater, ContentionOptions } from './client/functionalUpdate.js';
+export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
 export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
@@ -59,7 +61,7 @@ export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 export { createSourceConnector, type SourceConnector, type SourceConnectorOptions, type ConnectorStatus, } from './source/connector.js';
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './policy/index.js';
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, AbloContentionError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
 export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';

package/dist/index.js

@@ -55,6 +55,7 @@
 // `import Ablo from '@abloatai/ablo'` works; named export so
 // `import { Ablo }` also compiles.
 export { Ablo } from './client/Ablo.js';
+export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
@@ -84,7 +85,7 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, AbloContentionError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 // Canonical wire-egress contract (dependency-free): the error envelope shape +
 // the AbloError-subclass→HTTP-status table. Re-exported so server consumers
 // (e.g. apps/sync-server, which keeps its own self-contained copy) can assert

package/dist/sync/SyncWebSocket.js

@@ -404,6 +404,36 @@ export class SyncWebSocket extends EventEmitter {
                             else {
                                 errorMessage = 'mutation failed on server';
                             }
+                            // Coordination collision: a stale-context rejection (the write's
+                            // readAt premise moved underneath) or a foreign-claim conflict is
+                            // exactly the collision ClaimLog exists to surface. The notify
+                            // path (success + notifications) emits captureConflict above; a
+                            // HARD rejection must too — otherwise observability.collisions()
+                            // silently misses every rejected write. The conflicted rows ride
+                            // along on the typed error's `conflicts` detail (see
+                            // AbloStaleContextError.toJSON / errorEnvelope).
+                            if (errorCode === 'stale_context' ||
+                                errorCode === 'claim_conflict' ||
+                                errorCode === 'entity_claimed' ||
+                                errorCode?.startsWith('policy:') === true) {
+                                const rawConflicts = error != null &&
+                                    typeof error === 'object' &&
+                                    Array.isArray(error.conflicts)
+                                    ? error
+                                        .conflicts
+                                    : [];
+                                const conflictEvent = {
+                                    clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
+                                    rows: rawConflicts.map((r) => ({
+                                        model: typeof r.model === 'string' ? r.model : 'unknown',
+                                        id: typeof r.id === 'string' ? r.id : 'unknown',
+                                        fields: [],
+                                    })),
+                                };
+                                const ctx = getContext();
+                                ctx.observability.breadcrumb(formatConflict(conflictEvent), 'sync.coordination', 'warning');
+                                ctx.observability.captureConflict(conflictEvent);
+                            }
                             // Build the proper typed AbloError from the wire code via the
                             // shared factory — the same code→class mapping the HTTP commit
                             // path uses (`translateHttpError`). This keeps rejected commits

package/docs/coordination.md

@@ -7,9 +7,25 @@
 
 Coordinate long-running work on a row so humans and agents don't clobber each
 other. Most writes need none of this — a plain `ablo.<model>.update({ id, data })`
-is **last-write-wins** by default. For lost-update detection, take a claim or pass
-`readAt` / `onStale` yourself. Reach for `claim` only when you'll **hold a row
-across a slow gap** (read → LLM call → write).
+is **last-write-wins** by default.
+
+> **Read-modify-write under contention? Use the functional update — it owns all
+> of this for you.** When the new value is computed from the current one (the
+> shape that races), pass a function instead of data:
+>
+> ```ts
+> await ablo.documents.update(id, (current) => ({ content: revise(current.content) }));
+> ```
+>
+> The SDK reads the freshest row, runs your updater, writes it as a
+> compare-and-swap, and re-reads + re-runs on any concurrent write — no claim, no
+> per-agent identity, no `stale_context` / `claim_*` codes, no retry loop, and no
+> way to silently clobber. See [Functional update](#functional-update).
+> The rest of this page is the **low-level** machinery the functional form is
+> built on — reach for it directly only when you need to **hold a row across a
+> slow gap with side effects** (e.g. presence badges, multi-row handles), or want
+> explicit FIFO ordering. For lost-update detection on a single read-modify-write,
+> prefer the functional form over hand-rolling `claim` / `readAt` / `onStale`.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them,
 re-reads the fresh row, then hands it to you — so two writers serialize instead
@@ -19,13 +35,34 @@ Reads stay open: reading a claimed row is allowed unless the caller explicitly
 asks for claimed gating. A claim carries a TTL so a crashed holder is
 auto-released and the queue advances.
 
+> **Transport: WebSocket queues, HTTP reconciles.** The "blocks until promoted"
+> behaviour above needs a live socket to wake the waiter, so it applies to the
+> **WebSocket client only**. On the **stateless HTTP client**
+> (`Ablo({ transport: 'http' })` — the transport server-side agents use) there is
+> nothing to park a waiter, so a contended `claim` does **not** wait: it acquires
+> immediately, or rejects right away with `AbloClaimedError('claim_queued')`
+> (`queue: true`, the default) / `AbloClaimedError('entity_claimed')`
+> (`queue: false`). And because short claim→write→release cycles rarely overlap,
+> concurrent HTTP agents usually all acquire, then collide at **write** time — the
+> first write wins and the rest get `AbloStaleContextError('stale_context')`.
+> The coordination pattern over HTTP is therefore a **reconcile loop**, not a
+> queue: catch `claim_queued` / `claim_lost` / `stale_context`, re-read fresh,
+> regenerate, retry. See [Errors](#errors) and the loop sketch there.
+
 This reference opens with [the model](#the-model--three-layers-one-decision) — the
 one answer to "how do two agents not clobber each other" — then covers the
 [claim state object](#the-claim-state-object), the SDK [methods](#methods)
 (`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
+> **Before anything else: one identity per agent (for the low-level claim
+> path).** The [functional update](#functional-update) does
+> **not** need this — its safety comes from the row watermark (compare-and-swap),
+> not from participant identity, so it's correct even when many workers share one
+> `sk_`. The rule below applies when you take **explicit `claim`s** for FIFO
+> exclusion or presence.
+>
+> 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
@@ -453,6 +490,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_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?` |
 | `AbloClaimedError` | `claim_conflict` | An `update`/`delete` targets a row another participant holds — the server's pre-commit check rejected it. | — |
@@ -479,3 +517,138 @@ try {
   } else throw err;
 }
 ```
+
+### The reconcile loop, by hand (rarely needed)
+
+This is the loop the [functional update](#functional-update) runs for you. Write
+it yourself only when one attempt isn't a pure re-read-and-recompute — e.g. you
+must hold an explicit `claim` for a presence badge across the gap, or coordinate
+several rows in one handle. For a single read-modify-write, use the functional
+form instead of this.
+
+```ts
+const RETRYABLE = (e: unknown) =>
+  e instanceof AbloStaleContextError ||                       // row moved under our write
+  (e instanceof AbloClaimedError &&
+    (e.code === 'claim_queued' ||                             // someone holds it right now
+     e.code === 'claim_lost'));                               // a human preempted us
+
+for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+  try {
+    await using claim = await ablo.reports.claim({ id });     // acquire or claim_queued
+    const fresh = claim.data;                                 // read at the lease moment
+    const next = await generate(fresh);                       // slow gap
+    await ablo.reports.update({ id, data: next, claim });     // first writer wins
+    break;                                                    // landed
+  } catch (err) {
+    if (!RETRYABLE(err) || attempt === MAX_ATTEMPTS) throw err;
+    await sleep(80 + attempt * 40 + Math.random() * 60);      // jitter: don't lock-step
+  }
+}
+```
+
+The loop, not a queue, is the coordination mechanism over HTTP. On the WebSocket
+client the same code works but rarely loops, because `claim` blocks in the FIFO
+line instead of throwing `claim_queued`.
+
+---
+
+## Functional update
+
+The read-modify-write surface that owns the loop above so you never write it.
+Pass a **function of the current state** instead of fixed `data` — the
+`setState(prev => next)` of the data layer:
+
+```ts
+const row = await ablo.documents.update(documentId, (current) => ({
+  content: revise(current.content),        // "given the latest, here is the next"
+}));
+```
+
+What the SDK does on every call, on **both transports** (one shared loop, so the
+guarantee can't drift): read the freshest row + its watermark → run your updater
+→ write it as a **compare-and-swap** against that watermark (`readAt` +
+`onStale: 'reject'`) → on any concurrent write, re-read and re-run. Correctness
+comes from the watermark, **not** from participant identity — so it's immune to
+the shared-credential clobber footgun and needs no `claim` and no per-agent `rk_`.
+
+Nothing about claims, identity, or conflict codes surfaces. The call either
+returns the reconciled row (a `CommitReceipt` on the HTTP client; the row on the
+WebSocket client) or, at the extreme, throws **one** error:
+
+```ts
+import { AbloContentionError } from '@abloatai/ablo';
+
+try {
+  await ablo.documents.update(id, (cur) => ({ content: revise(cur.content) }), {
+    retries: 16,            // reconcile rounds before giving up (default 16)
+    signal: req.signal,     // optional: abort the loop if the request is cancelled
+  });
+} catch (err) {
+  if (err instanceof AbloContentionError) {
+    // The row stayed continuously contended past the budget — nothing was
+    // written. err.attempts, err.cause (the last conflict). Back off, raise
+    // `retries`, or move the row to the WebSocket transport (fair FIFO queue).
+  }
+}
+```
+
+Return `null` / `undefined` from the updater to **skip the write** after seeing
+fresh state (the call resolves to `undefined`). A missing row throws
+`AbloNotFoundError`; a genuine failure (validation, constraint, permission)
+propagates immediately without retrying.
+
+### How `create` and `delete` relate
+
+They don't get a functional form — and shouldn't. The functional form exists
+because `update` is the only verb whose **next state is a function of the current
+state**, which is the shape that races. The other two aren't read-modify-write:
+
+| Verb | Functional form? | Why | Its "just works" property |
+| --- | --- | --- | --- |
+| `update` | **yes** — `update(id, current => next)` | next value depends on the current one (lost-update hazard) | compare-and-swap + reconcile |
+| `create` | no — `create({ data, id? })` | no prior state to read; the hazard is *id collision*, a terminal `unique_violation`, not a lost update | **idempotency** — stable id / `idempotencyKey` makes a retried create safe |
+| `delete` | no — `delete({ id })` | no resulting state to compute; "make it not exist" is unchanged by concurrent edits, and delete is idempotent | naturally idempotent |
+
+The same reason React has `setState(prev => next)` but no functional mount /
+unmount. A *conditional* delete ("only if unchanged since I read it") is the one
+niche case — express it with an explicit `claim` / `readAt` on `delete({ id })`,
+not a function.
+
+---
+
+## Observability — the `ClaimLog`
+
+Coordination you can't see is coordination you can't debug. Pass an
+`observability` provider to `Ablo({ ... })` and the client reports every claim
+lifecycle event and stale-write collision it sees. The batteries-included
+provider is `ClaimLog`:
+
+```ts
+import Ablo, { ClaimLog } from '@abloatai/ablo';
+
+const log = new ClaimLog();
+const ablo = Ablo({ schema, apiKey, observability: log });
+// …run your agents…
+
+log.entries        // full ordered timeline, one readable line each
+log.collisions()   // just the collisions: rejected/lost claims + stale writes
+log.toString()     // pretty, greppable timeline to print
+log.onChange(fn)   // reactive subscribe → drive a live activity feed / useSyncExternalStore
+```
+
+`collisions()` is the eval primitive — `expect(log.collisions()).toHaveLength(0)`
+asserts "no one stepped on anyone." Each line names the row it touched, e.g.
+`conflict: tx … — 1 row(s) changed underneath: reports/r1`.
+
+`ClaimLog` implements the full `SyncObservabilityProvider`, so it drops straight
+into the `observability` slot; spread `noopObservability` if you only want to
+override a few hooks (e.g. forward to Sentry/OTel). Exports: `ClaimLog`,
+`formatClaim`, `formatConflict`, `noopObservability`, and the types `ClaimEvent`,
+`ConflictEvent`, `ClaimLogEntry`, `SyncObservabilityProvider`.
+
+> **Both transports, from 0.21.0.** Observability fires on the WebSocket **and**
+> the stateless HTTP transport (claim acquired + coordination-conflict
+> rejections, on every write door). Before 0.21.0 only WebSocket emitted, so a
+> `ClaimLog` on an HTTP client — e.g. a headless server-agent eval — stayed
+> silent even though coordination still worked.

package/package.json

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