@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/ApiClient.js

@@ -1,20 +1,66 @@
 /**
- * Stateless API client for `Ablo({ apiKey })`.
- *
- * This is the hosted-API product surface: no schema, no object pool, no
- * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
- * nouns directly to HTTP routes on sync-server.
+ * The stateless API client behind `Ablo({ apiKey })`. It carries no schema,
+ * object pool, local database, or WebSocket, and maps the public Model, Claim,
+ * and Commit nouns directly to HTTP routes on the server. This is the transport
+ * used for server-side agents, workers, and serverless code.
  */
-import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
+import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloIdempotencyError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
+import { z } from 'zod';
+import { v5 as uuidv5 } from 'uuid';
 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 { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
-import { toSeconds } from '../utils/duration.js';
+import { toMs, toSeconds } from '../utils/duration.js';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
 import { mintSession } from './sessionMint.js';
+import { parseIdentityResolveResponse } from '../auth/schemas.js';
+/**
+ * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
+ * than `held` means the lease is no longer ours (a holder cannot be `queued`;
+ * `lost` rides a 409 that the wire error mapping already surfaces as
+ * AbloClaimedError before reaching here). The thrown loss is the definitive
+ * signal that stops the auto-heartbeat loop.
+ */
+function heldHeartbeatReply(reply, label) {
+    if (reply.status === 'held' && typeof reply.expiresAt === 'number') {
+        return {
+            expiresAt: reply.expiresAt,
+            ...(reply.queueDepth !== undefined ? { queueDepth: reply.queueDepth } : {}),
+        };
+    }
+    throw new AbloClaimedError(`The lease behind ${label} is no longer held — it expired or was granted onward. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' });
+}
 import { assertWriteOptions } from './writeOptionsSchema.js';
+import { createDurableHttpCommitEnvelope, canonicalHttpCommitBody, durableHttpCommitEnvelopeSchema, httpCommitEnvelopeRecordId, isHttpCommitReplayExpired, } from '../transactions/httpCommitEnvelope.js';
 /** Default per-request deadline for the stateless HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const successfulCommitResponseSchema = z
+    .object({
+    object: z.literal('commit_receipt'),
+    id: z.string().min(1).optional(),
+    clientTxId: z.string().min(1),
+    serverTxId: z.string().min(1),
+    status: z.enum(['queued', 'confirmed']),
+    success: z.literal(true),
+    lastSyncId: z.number().int().nonnegative().optional(),
+    ops: z.number().int().positive(),
+    /** Ids of UPDATE/DELETE targets that matched zero rows (loud 0-row writes). */
+    missingIds: z.array(z.string().min(1)).optional(),
+})
+    .loose();
+function parseSuccessfulCommitResponse(value, idempotencyKey) {
+    const parsed = successfulCommitResponseSchema.safeParse(value);
+    if (!parsed.success || parsed.data.clientTxId !== idempotencyKey) {
+        throw new AbloConnectionError('The commit endpoint returned an invalid success receipt; its outcome remains pending and is safe to retry.', {
+            code: 'commit_no_result',
+            cause: parsed.success
+                ? new Error('Commit receipt clientTxId did not match its idempotency key')
+                : parsed.error,
+        });
+    }
+    return parsed.data;
+}
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -32,11 +78,12 @@ 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,
+    // Observability hook for the stateless HTTP transport. The WebSocket transport
+    // emits claim and conflict events; 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.
+    // agent evaluation stayed empty. This mirrors the two WebSocket events here:
+    // claim acquired and coordination-conflict rejection. A 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
@@ -47,14 +94,17 @@ export function createProtocolClient(options) {
     const recordCoordinationConflict = (error, clientTxId, fallbackRows) => {
         if (!observability)
             return;
-        const code = error?.code;
+        const errorRecord = typeof error === 'object' && error !== null
+            ? error
+            : undefined;
+        const code = errorRecord?.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 rawConflicts = errorRecord?.conflicts;
         const rows = Array.isArray(rawConflicts) && rawConflicts.length > 0
             ? rawConflicts.map((r) => ({
                 model: typeof r.model === 'string' ? r.model : 'unknown',
@@ -73,19 +123,54 @@ export function createProtocolClient(options) {
         url,
         bootstrapBaseUrl: options.bootstrapBaseUrl,
     }).replace(/\/+$/, '');
+    const commitOutbox = options.commitOutbox;
+    const httpOutboxPlaneNamespace = canonicalHttpCommitBody({
+        apiBaseUrl,
+        defaultQuery: Object.entries(options.defaultQuery ?? {}).sort(([a], [b]) => a.localeCompare(b)),
+    });
+    let httpOutboxScopeNamespace = null;
     let readyPromise = null;
+    let httpCommitLane = Promise.resolve();
+    function runInHttpCommitLane(work) {
+        const result = httpCommitLane.then(work);
+        httpCommitLane = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async function resolveHttpOutboxScope() {
+        if (!commitOutbox)
+            return null;
+        if (httpOutboxScopeNamespace)
+            return httpOutboxScopeNamespace;
+        let scope = options.commitOutboxScope;
+        if (!scope) {
+            const rawIdentity = await requestJson('/auth/identity', { method: 'GET' }, true);
+            const identity = parseIdentityResolveResponse(rawIdentity);
+            scope = {
+                organizationId: identity.accountScope,
+                participantId: identity.participantId,
+                namespace: 'http',
+            };
+        }
+        httpOutboxScopeNamespace = canonicalHttpCommitBody({
+            ...scope,
+            plane: httpOutboxPlaneNamespace,
+        });
+        return httpOutboxScopeNamespace;
+    }
     async function ready() {
         if (readyPromise)
             return readyPromise;
         readyPromise = (async () => {
-            if (!configuredDatabaseUrl)
-                return;
-            await registerDataSource({
-                baseUrl: apiBaseUrl,
-                apiKey: await resolveApiKeyValue(configuredApiKey),
-                databaseUrl: configuredDatabaseUrl,
-                ...(options.fetch ? { fetchImpl: options.fetch } : {}),
-            });
+            if (configuredDatabaseUrl) {
+                await registerDataSource({
+                    baseUrl: apiBaseUrl,
+                    apiKey: await resolveApiKeyValue(configuredApiKey),
+                    databaseUrl: configuredDatabaseUrl,
+                    ...(options.fetch ? { fetchImpl: options.fetch } : {}),
+                });
+            }
+            await resolveHttpOutboxScope();
+            await replayHttpCommitOutbox();
         })();
         try {
             await readyPromise;
@@ -127,8 +212,9 @@ export function createProtocolClient(options) {
         return target.toString();
     }
     const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    async function requestJson(path, init) {
-        await ready();
+    async function requestJson(path, init, skipReady = false) {
+        if (!skipReady)
+            await ready();
         const { idempotencyKey, ...requestInit } = init;
         const headers = await authHeaders();
         if (idempotencyKey)
@@ -139,7 +225,7 @@ export function createProtocolClient(options) {
         // is combined with the deadline via a shared controller — the portable
         // equivalent of `AbortSignal.any([caller, AbortSignal.timeout(t)])`,
         // which older runtimes (and the jsdom test env) don't implement. The
-        // same pattern already guards `query/client.ts` and `BootstrapHelper`.
+        // same pattern already guards `query/client.ts` and `BootstrapFetcher`.
         const callerSignal = requestInit.signal ?? undefined;
         const controller = new AbortController();
         const onCallerAbort = () => { controller.abort(callerSignal?.reason); };
@@ -172,6 +258,7 @@ export function createProtocolClient(options) {
             bodyText = await res.text();
         }
         catch (error) {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- assigned asynchronously by the deadline callback
             if (timedOut) {
                 // Retryable by contract: `wait_for_timeout` is a registered transient
                 // transport code, so `isRetryableCode` steers callers to retry.
@@ -192,6 +279,169 @@ export function createProtocolClient(options) {
         }
         return body;
     }
+    function isDefinitiveHttpRejection(error) {
+        if (typeof error !== 'object' || error === null)
+            return false;
+        const candidate = error;
+        const status = typeof candidate.httpStatus === 'number'
+            ? candidate.httpStatus
+            : typeof candidate.status === 'number'
+                ? candidate.status
+                : undefined;
+        return (status !== undefined &&
+            status >= 400 &&
+            status < 500 &&
+            status !== 408 &&
+            status !== 425 &&
+            status !== 429);
+    }
+    async function settleHttpEnvelope(recordId) {
+        if (!commitOutbox)
+            return;
+        try {
+            await commitOutbox.remove(recordId);
+        }
+        catch (cause) {
+            // Do not report the remote outcome until local settlement is durable.
+            // The retained record can still be replayed inside the safe window.
+            throw new AbloConnectionError('The server settled the commit, but its local outbox record could not be cleared.', { code: 'db_not_opened', cause });
+        }
+    }
+    async function replayHttpCommitOutbox() {
+        const replayed = new Map();
+        if (!commitOutbox)
+            return replayed;
+        const scopeNamespace = await resolveHttpOutboxScope();
+        if (!scopeNamespace)
+            return replayed;
+        const rows = await commitOutbox.list();
+        const envelopes = [];
+        for (const row of rows) {
+            if (typeof row !== 'object' ||
+                row === null ||
+                row.type !== 'http_commit_envelope')
+                continue;
+            const parsed = durableHttpCommitEnvelopeSchema.safeParse(row);
+            if (!parsed.success) {
+                throw new AbloValidationError('A saved HTTP write is unreadable; replay stopped before any newer write was sent.', { code: 'write_options_invalid', cause: parsed.error });
+            }
+            if (parsed.data.scopeNamespace !== scopeNamespace)
+                continue;
+            if (isHttpCommitReplayExpired(parsed.data)) {
+                throw new AbloIdempotencyError('A saved HTTP write is older than the server idempotency window and cannot be replayed safely.', { code: 'idempotency_conflict' });
+            }
+            envelopes.push(parsed.data);
+        }
+        envelopes.sort((a, b) => (a.sequence ?? a.sealedAt * 1_000) -
+            (b.sequence ?? b.sealedAt * 1_000) ||
+            a.id.localeCompare(b.id));
+        for (const envelope of envelopes) {
+            try {
+                const raw = await requestJson(envelope.request.path, {
+                    method: envelope.request.method,
+                    idempotencyKey: envelope.idempotencyKey,
+                    body: envelope.request.body,
+                }, true);
+                const response = parseSuccessfulCommitResponse(raw, envelope.idempotencyKey);
+                await settleHttpEnvelope(envelope.id);
+                replayed.set(envelope.idempotencyKey, { envelope, response });
+            }
+            catch (error) {
+                if (isDefinitiveHttpRejection(error)) {
+                    await settleHttpEnvelope(envelope.id);
+                }
+                throw error;
+            }
+        }
+        return replayed;
+    }
+    let lastHttpCommitSequence = 0;
+    function nextHttpCommitSequence() {
+        const wallSequence = Date.now() * 1_000;
+        lastHttpCommitSequence = Math.max(wallSequence, lastHttpCommitSequence + 1);
+        return lastHttpCommitSequence;
+    }
+    async function sealHttpCommit(input) {
+        if (!commitOutbox)
+            return null;
+        const scopeNamespace = await resolveHttpOutboxScope();
+        if (!scopeNamespace) {
+            throw new AbloValidationError('HTTP commit outbox scope was not resolved', {
+                code: 'write_options_invalid',
+            });
+        }
+        const recordId = httpCommitEnvelopeRecordId(input.idempotencyKey, scopeNamespace);
+        const legacyRecordId = httpCommitEnvelopeRecordId(input.idempotencyKey);
+        const existingRows = await commitOutbox.list();
+        const existingRaw = existingRows.find((row) => typeof row === 'object' &&
+            row !== null &&
+            (row.id === recordId ||
+                row.id === legacyRecordId));
+        const serializedBody = canonicalHttpCommitBody(input.body);
+        if (existingRaw !== undefined) {
+            const existing = durableHttpCommitEnvelopeSchema.parse(existingRaw);
+            if (isHttpCommitReplayExpired(existing)) {
+                throw new AbloIdempotencyError('This saved HTTP write is older than the server idempotency window and cannot be retried safely.', { code: 'idempotency_conflict' });
+            }
+            if (existing.scopeNamespace !== scopeNamespace ||
+                existing.request.method !== input.method ||
+                existing.request.path !== input.path ||
+                existing.request.body !== serializedBody) {
+                throw new AbloIdempotencyError('Idempotency key reused with a different HTTP commit request', { code: 'idempotency_conflict' });
+            }
+            return existing;
+        }
+        const envelope = createDurableHttpCommitEnvelope({
+            idempotencyKey: input.idempotencyKey,
+            request: { method: input.method, path: input.path, body: input.body },
+            scopeNamespace,
+            sequence: nextHttpCommitSequence(),
+        });
+        await commitOutbox.seal(envelope, []);
+        return envelope;
+    }
+    async function dispatchHttpCommit(input, beforeSettlement) {
+        return runInHttpCommitLane(async () => {
+            await ready();
+            // `ready()` covers startup. Re-draining here makes every later write wait
+            // behind an ambiguous predecessor from this same process.
+            const replayed = await replayHttpCommitOutbox();
+            const prior = replayed.get(input.idempotencyKey);
+            if (prior) {
+                const serializedBody = canonicalHttpCommitBody(input.body);
+                if (prior.envelope.request.method !== input.method ||
+                    prior.envelope.request.path !== input.path ||
+                    prior.envelope.request.body !== serializedBody) {
+                    throw new AbloIdempotencyError('Idempotency key reused with a different HTTP commit request', { code: 'idempotency_conflict' });
+                }
+                await beforeSettlement?.(prior.response);
+                return prior.response;
+            }
+            const durableEnvelope = await sealHttpCommit(input);
+            const requestBody = durableEnvelope?.request.body ?? canonicalHttpCommitBody(input.body);
+            let response;
+            try {
+                const raw = await requestJson(input.path, {
+                    method: input.method,
+                    idempotencyKey: input.idempotencyKey,
+                    body: requestBody,
+                }, true);
+                response = parseSuccessfulCommitResponse(raw, input.idempotencyKey);
+            }
+            catch (error) {
+                if (durableEnvelope && isDefinitiveHttpRejection(error)) {
+                    await settleHttpEnvelope(durableEnvelope.id);
+                }
+                throw error;
+            }
+            // A model-create readback can participate in settlement: if it fails,
+            // retain the exact write so a same-key retry recovers the generated id.
+            await beforeSettlement?.(response);
+            if (durableEnvelope)
+                await settleHttpEnvelope(durableEnvelope.id);
+            return response;
+        });
+    }
     function createClientTxId(idempotencyKey) {
         if (idempotencyKey && idempotencyKey.length > 0)
             return idempotencyKey;
@@ -204,17 +454,28 @@ export function createProtocolClient(options) {
             ? `int_${crypto.randomUUID()}`
             : `int_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function createModelId() {
+    function createModelId(modelName, idempotencyKey) {
+        if (idempotencyKey) {
+            return uuidv5(`${modelName}:${idempotencyKey}`, 'aa4ba6d4-bf0b-5b38-9c45-116f79a6e548');
+        }
         return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function childClient(authToken) {
+    function childClient(authToken, scope) {
         return createProtocolClient({
             ...options,
             apiKey: null,
             authToken,
             schema: null,
+            ...(scope
+                ? {
+                    commitOutboxScope: {
+                        ...scope,
+                        namespace: options.commitOutboxScope?.namespace ?? 'http',
+                    },
+                }
+                : { commitOutboxScope: undefined }),
         });
     }
     function normalizeCommitOperation(op, defaults) {
@@ -341,17 +602,20 @@ export function createProtocolClient(options) {
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
+            const requestBody = {
+                clientTxId,
+                idempotencyKey: clientTxId,
+                claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
+                operations,
+                reads: commitOptions.reads,
+            };
             let body;
             try {
-                body = await requestJson('/v1/commits', {
+                body = await dispatchHttpCommit({
+                    path: '/v1/commits',
                     method: 'POST',
                     idempotencyKey: clientTxId,
-                    body: JSON.stringify({
-                        clientTxId,
-                        idempotencyKey: clientTxId,
-                        claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
-                        operations,
-                    }),
+                    body: requestBody,
                 });
             }
             catch (error) {
@@ -370,7 +634,7 @@ export function createProtocolClient(options) {
             // the rejection body (already thrown).
             const status = body.status === 'queued' ? 'queued' : 'confirmed';
             return {
-                id: body.id ?? body.clientTxId ?? clientTxId,
+                id: body.id ?? body.clientTxId,
                 status,
                 lastSyncId: body.lastSyncId,
                 ...(body.missingIds && body.missingIds.length > 0
@@ -381,9 +645,9 @@ export function createProtocolClient(options) {
     };
     const capabilities = {
         async create(capabilityOptions) {
-            const ttlSeconds = capabilityOptions.ttlSeconds ??
+            const ttlSeconds = capabilityOptions.ttlSeconds ?? // eslint-disable-line @typescript-eslint/no-deprecated -- compatibility alias
                 capabilityOptions.leaseSeconds ??
-                toSeconds(capabilityOptions.ttl ?? capabilityOptions.lease ?? DEFAULT_AGENT_LEASE);
+                toSeconds(capabilityOptions.ttl ?? capabilityOptions.lease ?? DEFAULT_AGENT_LEASE); // eslint-disable-line @typescript-eslint/no-deprecated -- compatibility alias
             const body = await requestJson('/v1/capabilities', {
                 method: 'POST',
                 body: JSON.stringify({
@@ -408,7 +672,10 @@ export function createProtocolClient(options) {
                 organizationId: body.organizationId,
                 scope: body.scope,
                 userMeta: body.userMeta,
-                client: () => childClient(body.token),
+                client: () => childClient(body.token, {
+                    organizationId: body.organizationId,
+                    participantId: body.scope.participantId,
+                }),
             };
         },
         async retrieve(id) {
@@ -462,7 +729,10 @@ export function createProtocolClient(options) {
                     id: body.rotatedFrom.capabilityId ?? body.rotatedFrom.id ?? id,
                     expiresAt: body.rotatedFrom.expiresAt,
                 },
-                client: () => childClient(body.token),
+                client: () => childClient(body.token, {
+                    organizationId: body.organizationId,
+                    participantId: body.scope.participantId,
+                }),
             };
         },
         mint(options) {
@@ -482,11 +752,11 @@ export function createProtocolClient(options) {
                     queue: claimOptions.queue,
                 }),
             });
-            // The fair-queue grant is PUSHED over a WebSocket (`claim_granted`),
-            // which this stateless HTTP client doesn't hold. Returning a handle here
-            // would be a phantom holder — a lease we can't confirm is ours. So a
-            // queued response is surfaced as a typed claimed signal; callers that need
-            // to *wait* in line use the realtime (WS-backed) `ablo.<model>.claim`.
+            // The fair-queue grant is pushed over a WebSocket (`claim_granted`), which
+            // this stateless HTTP client doesn't hold. Returning a handle here would be
+            // a phantom holder — a lease we can't confirm is ours. So a queued response
+            // is surfaced as a typed claimed signal; callers that need to wait in line
+            // use the realtime (WebSocket-backed) `ablo.<model>.claim`.
             if (body.status === 'queued') {
                 throw new AbloClaimedError(`Target ${claimOptions.target.model}/${claimOptions.target.id} is held; ` +
                     `queued at position ${body.position ?? 0}. The HTTP client can't await ` +
@@ -500,9 +770,24 @@ export function createProtocolClient(options) {
                 released = true;
                 await requestJson(`/v1/claims/${encodeURIComponent(id)}`, { method: 'DELETE' });
             };
+            // The by-id twin of the model-scoped heartbeat — same reply contract.
+            const heartbeat = async (beatOptions) => {
+                const resolved = resolveHeartbeatOptions(beatOptions);
+                const reply = await requestJson(`/v1/claims/${encodeURIComponent(id)}/heartbeat`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        ...(resolved.ttl !== undefined ? { ttl: resolved.ttl } : {}),
+                        ...(resolved.details !== undefined
+                            ? { details: resolved.details }
+                            : {}),
+                    }),
+                });
+                return heldHeartbeatReply(reply, `claim ${id}`);
+            };
             return {
                 object: 'claim',
                 id,
+                heartbeat,
                 reason: claimOptions.reason,
                 target: {
                     type: claimOptions.target.model,
@@ -523,6 +808,23 @@ export function createProtocolClient(options) {
         waitFor(target, options) {
             return waitForNoClaims(target, options);
         },
+        async heartbeatAll(options) {
+            const reply = await requestJson('/v1/claims/heartbeat', {
+                method: 'POST',
+                body: JSON.stringify(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            });
+            return (reply.results ?? []).flatMap((entry) => typeof entry.claimId === 'string' && typeof entry.expiresAt === 'number'
+                ? [
+                    {
+                        claimId: entry.claimId,
+                        expiresAt: entry.expiresAt,
+                        ...(entry.queueDepth !== undefined
+                            ? { queueDepth: entry.queueDepth }
+                            : {}),
+                    },
+                ]
+                : []);
+        },
     };
     async function listModel(modelName, options) {
         const params = new URLSearchParams();
@@ -554,11 +856,11 @@ export function createProtocolClient(options) {
         const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, {
             method: 'GET',
         });
-        // Miss = `data: undefined`, NOT a thrown error. The WebSocket client's
+        // A miss is `data: undefined`, not a thrown error. The WebSocket client's
         // `retrieve` returns `T | undefined` for a missing row; throwing only here
         // made the obvious read ("does this row exist?") a hard edge that an agent
-        // had to wrap in try/catch. Both transports now agree: absent row → absent
-        // data. Callers branch on `.data` (already the documented `.data?.x` usage).
+        // had to wrap in try/catch. Both transports agree: an absent row means absent
+        // data. Callers branch on `.data` (the documented `.data?.x` usage).
         // Normalize a miss to `undefined` (the server may send `null` or omit it).
         const data = (query.data ?? undefined);
         return {
@@ -568,18 +870,18 @@ export function createProtocolClient(options) {
         };
     }
     /**
-     * Single-op mutation over the model-scoped routes — the canonical surface
-     * that mirrors `ablo.<model>.create/update/delete`:
+     * A single-operation mutation over the model-scoped routes — the canonical
+     * surface that mirrors `ablo.<model>.create/update/delete`:
      *
      *   POST   /v1/models/:model        create
      *   PATCH  /v1/models/:model/:id     update
      *   DELETE /v1/models/:model/:id     delete
      *
-     * This replaces the previous indirection through `POST /v1/commits`. The raw
-     * `commits.create(...)` resource is still the path for ATOMIC MULTI-OP
-     * envelopes — this helper is the one-op, one-record path only.
+     * The `commits.create(...)` resource remains the path for atomic
+     * multi-operation envelopes; this helper handles the one-operation,
+     * one-record case.
      */
-    async function mutateModel(action, modelName, id, data, options) {
+    async function mutateModel(action, modelName, id, data, options, beforeSettlement) {
         assertWriteOptions(options && {
             idempotencyKey: options.idempotencyKey,
             readAt: options.readAt,
@@ -595,11 +897,12 @@ export function createProtocolClient(options) {
         const method = action === 'create' ? 'POST' : action === 'update' ? 'PATCH' : 'DELETE';
         // A carried claim handle supplies the stale-guard defaults — one claim
         // vocabulary across the WS proxy, `commits.create`, and these routes.
-        const claimHandle = typeof options?.claim === 'object' &&
-            options?.claim !== null &&
-            options.claim.object === 'claim' &&
-            typeof options.claim.id === 'string'
-            ? options.claim
+        const rawClaim = options?.claim;
+        const claimHandle = typeof rawClaim === 'object' &&
+            rawClaim !== null &&
+            rawClaim.object === 'claim' &&
+            typeof rawClaim.id === 'string'
+            ? rawClaim
             : undefined;
         const readAt = options?.readAt ?? claimHandle?.readAt;
         const requestBody = {
@@ -614,16 +917,16 @@ export function createProtocolClient(options) {
             requestBody.data = data;
         let body;
         try {
-            body = await requestJson(path, {
+            body = await dispatchHttpCommit({
+                path,
                 method,
                 idempotencyKey: clientTxId,
-                body: JSON.stringify(requestBody),
-            });
+                body: requestBody,
+            }, beforeSettlement);
         }
         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.
+            // The per-model write door (`ablo.<model>.update/create/delete`). Capture
+            // coordination collisions here too; this single row is the fallback target.
             recordCoordinationConflict(error, clientTxId, [{ model: modelName, id }]);
             throw error;
         }
@@ -632,7 +935,7 @@ export function createProtocolClient(options) {
         // subset; `'rejected'` only appears on a thrown rejection body.
         const status = body.status === 'queued' ? 'queued' : 'confirmed';
         return {
-            id: body.serverTxId ?? body.id ?? body.clientTxId ?? clientTxId,
+            id: body.serverTxId,
             status,
             lastSyncId: body.lastSyncId,
         };
@@ -669,11 +972,25 @@ export function createProtocolClient(options) {
                 throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
                     `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
             }
-            // `claimId` is the queued-response field name (routes/claims.ts) — a
-            // pre-rename regression duplicated the `body.id` arm and dropped it.
+            // `claimId` is the field name the queued response uses; check it alongside
+            // the other id shapes the response may carry.
             return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
+        // One beat on the held lease. A lapsed lease answers `claim_lost`
+        // (409), which the wire error mapping surfaces as AbloClaimedError —
+        // the definitive signal that stops the auto-heartbeat loop.
+        const heartbeatClaim = async (id, claimId, options) => {
+            const reply = await requestJson(`${claimPath(id)}/heartbeat`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    claimId,
+                    ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
+                    ...(options.details !== undefined ? { details: options.details } : {}),
+                }),
+            });
+            return heldHeartbeatReply(reply, `claim ${claimId} on ${name}/${id}`);
+        };
         async function claimImpl(params) {
             const claimId = await acquireClaim(params);
             observability?.captureClaim({
@@ -691,7 +1008,33 @@ export function createProtocolClient(options) {
             if (data === undefined) {
                 throw new AbloNotFoundError(`Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope).`, [params.id]);
             }
-            const release = () => releaseClaim(params);
+            const heartbeat = async (beatOptions) => {
+                const resolved = resolveHeartbeatOptions(beatOptions);
+                const beat = await heartbeatClaim(params.id, claimId, {
+                    ttl: resolved.ttl ?? params.ttl,
+                    ...(resolved.details !== undefined
+                        ? { details: resolved.details }
+                        : {}),
+                });
+                params.onHeartbeat?.(beat);
+                return beat;
+            };
+            // Opt-in auto-heartbeat — the background-worker cadence. The stateless
+            // HTTP claim defaults to the server's 60s acquire window when no TTL
+            // was requested, so the default cadence lands at 20s beats.
+            const stopHeartbeatLoop = params.heartbeat
+                ? startClaimHeartbeatLoop({
+                    beat: () => heartbeat(),
+                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : 60_000, params.heartbeat),
+                    ...(params.onHeartbeatLost
+                        ? { onLost: params.onHeartbeatLost }
+                        : {}),
+                })
+                : undefined;
+            const release = () => {
+                stopHeartbeatLoop?.();
+                return releaseClaim(params);
+            };
             return {
                 object: 'claim',
                 id: claimId,
@@ -711,6 +1054,7 @@ export function createProtocolClient(options) {
                 revoke: () => {
                     void release().catch(() => { });
                 },
+                heartbeat,
                 [Symbol.asyncDispose]: release,
             };
         }
@@ -729,8 +1073,8 @@ export function createProtocolClient(options) {
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
                     method: 'POST',
-                    // The reorder route's payload is `{ heldBy, claimId }[]` — Claim's id
-                    // IS the claimId.
+                    // The reorder route's payload is `{ heldBy, claimId }[]` — a Claim's id
+                    // is the claimId.
                     body: JSON.stringify({ order: params.order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })) }),
                 });
             },
@@ -742,7 +1086,13 @@ export function createProtocolClient(options) {
             if (isClaimHandle(claimInput)) {
                 return run({ ...input, claimRef: { id: claimInput.id }, claim: undefined });
             }
-            const claimId = await acquireClaim({ id, ...claimInput });
+            // `isClaimHandle` ruled out the handle form above; the generic mismatch
+            // (the union carries `Claim`, the guard narrows `Claim<T>`) keeps the
+            // compiler from subtracting it, so narrow to the inline-options form.
+            const claimId = await acquireClaim({
+                id,
+                ...claimInput,
+            });
             try {
                 return await run({ ...input, claimRef: { id: claimId }, claim: undefined });
             }
@@ -790,23 +1140,31 @@ export function createProtocolClient(options) {
                 return listModel(name, options);
             },
             async create(params) {
-                const id = params.id ?? createModelId();
+                const id = params.id ?? createModelId(name, params.idempotencyKey);
                 return withMutationClaim(id, params, async (options) => {
                     await applyClaimedPolicy({ model: name, id }, options);
                     // Confirm the write, then return the row — the obvious expectation of
                     // "create" (the WebSocket client already returns the row). The read-
                     // back is the authoritative server row, so it carries the framework
-                    // defaults (createdAt/createdBy/…) AND, for an idempotent re-create of
-                    // an existing id, the EXISTING row rather than the caller's input.
+                    // defaults (createdAt, createdBy, …) and, for an idempotent re-create of
+                    // an existing id, the existing row rather than the caller's input.
+                    let created;
                     await mutateModel('create', name, id, params.data, {
                         ...options,
                         wait: options?.wait ?? 'confirmed',
+                    }, async () => {
+                        const read = await retrieveModel(name, { id });
+                        if (read.data === undefined) {
+                            throw new AbloNotFoundError(`create ${name}/${id} did not yield a readable row (the write did not confirm).`, [id]);
+                        }
+                        created = read.data;
                     });
-                    const { data } = await retrieveModel(name, { id });
-                    if (data === undefined) {
-                        throw new AbloNotFoundError(`create ${name}/${id} did not yield a readable row (the write did not confirm).`, [id]);
+                    if (created === undefined) {
+                        throw new AbloConnectionError('Create settlement did not return its row.', {
+                            code: 'commit_no_result',
+                        });
                     }
-                    return data;
+                    return created;
                 });
             },
             update: updateModel,
@@ -820,7 +1178,10 @@ export function createProtocolClient(options) {
     }
     return {
         ready,
-        async waitForFlush() { },
+        waitForFlush: () => runInHttpCommitLane(async () => {
+            await ready();
+            await replayHttpCommitOutbox();
+        }),
         async dispose() { },
         async purge() { },
         capabilities,
@@ -829,9 +1190,9 @@ export function createProtocolClient(options) {
         model,
         sessions: {
             async create(params) {
-                // Stateless mint: the configured key IS the control-plane credential here
-                // (no startup `rk_` exchange runs on this client). Reuse the resolved base
-                // URL + fetch; the shared `mintSession` owns the two server doors.
+                // Stateless mint: the configured key is the control-plane credential here
+                // (no startup `rk_` exchange runs on this client). It reuses the resolved
+                // base URL and fetch; the shared `mintSession` handles the two server routes.
                 const apiKey = await resolveApiKeyValue(configuredApiKey);
                 if (!apiKey) {
                     throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });