@abloatai/ablo 0.27.0 → 0.29.0

package/dist/client/{ApiClient.js → httpTransport.js}

@@ -1,17 +1,22 @@
 /**
- * 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.
+ * Private HTTP protocol client behind `Ablo({ schema, transport: 'http' })`.
+ * It carries no object pool, local database, or WebSocket and maps Model,
+ * Claim, and Commit protocol shapes directly to server routes. The typed
+ * facade in `httpClient.ts` is the application boundary; this module owns
+ * transport envelopes, watermarks, replay, and route details.
  */
-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 { toMs, toSeconds } from '../utils/duration.js';
+import { toMs } from '../utils/duration.js';
 import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
 import { mintSession } from './sessionMint.js';
+import { parseIdentityResolveResponse } from '../auth/schemas.js';
+import { staleNotificationSchema } from '../coordination/schema.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`;
@@ -29,10 +34,61 @@ function heldHeartbeatReply(reply, label) {
     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';
-/** Default per-request deadline for the stateless HTTP transport. */
+import { createDurableHttpCommitEnvelope, canonicalHttpCommitBody, durableHttpCommitEnvelopeSchema, httpCommitEnvelopeRecordId, isHttpCommitReplayExpired, } from '../transactions/httpCommitEnvelope.js';
+import { resolveDurableWrites } from './durableWrites.js';
+/** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
-const DEFAULT_AGENT_LEASE = '10m';
-export function createProtocolClient(options) {
+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(),
+    notifications: z.array(staleNotificationSchema).optional(),
+    /** 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;
+}
+/** Decode the HTTP claim DTO into the one public Claim shape. */
+function claimFromModelClaim(claim) {
+    return {
+        object: 'claim',
+        id: claim.id,
+        ...(claim.status ? { status: claim.status } : {}),
+        reason: claim.reason,
+        ...(claim.description ? { description: claim.description } : {}),
+        heldBy: claim.actor,
+        participantKind: claim.participantKind,
+        expiresAt: claim.expiresAt,
+        ...(claim.position !== undefined ? { position: claim.position } : {}),
+        target: {
+            type: claim.target.model,
+            id: claim.target.id,
+            ...(claim.target.path ? { path: claim.target.path } : {}),
+            ...(claim.target.range ? { range: claim.target.range } : {}),
+            ...(claim.target.field ? { field: claim.target.field } : {}),
+            ...(claim.target.meta ? { meta: claim.target.meta } : {}),
+        },
+    };
+}
+/** @internal Constructed only by the typed HTTP facade. */
+export function createHttpTransport(options) {
     const env = readProcessEnv();
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
@@ -64,14 +120,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',
@@ -90,19 +149,64 @@ export function createProtocolClient(options) {
         url,
         bootstrapBaseUrl: options.bootstrapBaseUrl,
     }).replace(/\/+$/, '');
+    const durableWrites = resolveDurableWrites(options);
+    // Internal replay code retains transactional-outbox terminology. The public
+    // constructor exposes the behavior as `durableWrites`.
+    const commitOutbox = durableWrites.store;
+    const durableWriteNamespace = durableWrites.namespace ?? 'http';
+    const legacyCommitOutboxScope = options.commitOutboxScope;
+    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 = legacyCommitOutboxScope
+            ? {
+                ...legacyCommitOutboxScope,
+                namespace: durableWriteNamespace,
+            }
+            : undefined;
+        if (!scope) {
+            const rawIdentity = await requestJson('/auth/identity', { method: 'GET' }, true);
+            const identity = parseIdentityResolveResponse(rawIdentity);
+            scope = {
+                organizationId: identity.accountScope,
+                participantId: identity.participantId,
+                namespace: durableWriteNamespace,
+            };
+        }
+        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;
@@ -112,11 +216,11 @@ export function createProtocolClient(options) {
             throw error;
         }
     }
-    async function authHeaders() {
+    async function authHeaders(sealedProtocolVersion) {
         const apiKey = await resolveApiKeyValue(configuredApiKey);
         const token = apiKey ?? configuredAuthToken;
         if (!token) {
-            throw new AbloAuthenticationError('Ablo({ apiKey }) requires an API key. Pass `apiKey` or set ABLO_API_KEY.', { code: 'api_key_required' });
+            throw new AbloAuthenticationError('The HTTP client requires an API key. Pass `apiKey` or set ABLO_API_KEY.', { code: 'api_key_required' });
         }
         const headers = {
             'Content-Type': 'application/json',
@@ -133,6 +237,12 @@ export function createProtocolClient(options) {
                 headers[key] = value;
             }
         }
+        // A durable write owns its wire version. Force the sealed value after
+        // caller defaults so a restarted (or rolled-back) SDK cannot rewrite the
+        // protocol identity of a request that may already have reached the server.
+        if (sealedProtocolVersion !== undefined) {
+            headers[PROTOCOL_VERSION_HEADER] = String(sealedProtocolVersion);
+        }
         return headers;
     }
     function endpoint(path) {
@@ -144,10 +254,11 @@ export function createProtocolClient(options) {
         return target.toString();
     }
     const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    async function requestJson(path, init) {
-        await ready();
-        const { idempotencyKey, ...requestInit } = init;
-        const headers = await authHeaders();
+    async function requestJson(path, init, skipReady = false) {
+        if (!skipReady)
+            await ready();
+        const { idempotencyKey, sealedProtocolVersion, ...requestInit } = init;
+        const headers = await authHeaders(sealedProtocolVersion);
         if (idempotencyKey)
             headers['Idempotency-Key'] = idempotencyKey;
         // Deadline: abort the request after `timeoutMs` so a black-holed server
@@ -189,6 +300,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.
@@ -209,6 +321,173 @@ 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,
+                    sealedProtocolVersion: envelope.protocolVersion,
+                    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 durable-write 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,
+                    ...(durableEnvelope
+                        ? { sealedProtocolVersion: durableEnvelope.protocolVersion }
+                        : {}),
+                    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;
@@ -221,29 +500,19 @@ 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) {
-        return createProtocolClient({
-            ...options,
-            apiKey: null,
-            authToken,
-            schema: null,
-        });
-    }
     function normalizeCommitOperation(op, defaults) {
-        const model = op.model ?? op.target?.model;
-        if (!model) {
-            throw new AbloValidationError('Commit operation requires `model` or `target.model`.', { code: 'commit_operation_model_required' });
-        }
-        const id = op.id ?? op.target?.id ?? null;
         return {
             action: op.action,
-            model,
-            id,
+            model: op.model,
+            id: op.id ?? null,
             data: op.data ?? null,
             transactionId: op.transactionId ?? null,
             readAt: op.readAt ?? defaults.readAt ?? null,
@@ -251,20 +520,10 @@ export function createProtocolClient(options) {
         };
     }
     function normalizeCommitOperations(commitOptions) {
-        if (commitOptions.operation && commitOptions.operations) {
-            throw new AbloValidationError('Pass either `operation` or `operations`, not both.', { code: 'commit_operations_ambiguous' });
+        if (commitOptions.operations.length === 0) {
+            throw new AbloValidationError('Commit requires a non-empty `operations` array.', { code: 'commit_operation_required' });
         }
-        const inputOperations = commitOptions.operation
-            ? [commitOptions.operation]
-            : commitOptions.operations ?? [];
-        if (inputOperations.length === 0) {
-            throw new AbloValidationError('Commit requires at least one operation.', { code: 'commit_operation_required' });
-        }
-        return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
-    }
-    async function listClaims(target) {
-        const state = await listClaimState(target);
-        return state.active;
+        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
     async function listClaimState(target) {
         const params = new URLSearchParams();
@@ -281,54 +540,6 @@ export function createProtocolClient(options) {
             queue: body.queue ?? [],
         };
     }
-    function delay(ms, signal) {
-        if (signal?.aborted) {
-            return Promise.reject(new AbloConnectionError('Claim wait aborted.', {
-                code: 'claim_wait_aborted',
-                cause: signal.reason,
-            }));
-        }
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(done, ms);
-            function cleanup() {
-                clearTimeout(timeout);
-                signal?.removeEventListener('abort', onAbort);
-            }
-            function done() {
-                cleanup();
-                resolve();
-            }
-            function onAbort() {
-                cleanup();
-                reject(new AbloConnectionError('Claim wait aborted.', {
-                    code: 'claim_wait_aborted',
-                    cause: signal?.reason,
-                }));
-            }
-            signal?.addEventListener('abort', onAbort, { once: true });
-        });
-    }
-    async function waitForNoClaims(target, options) {
-        const startedAt = Date.now();
-        const pollInterval = options?.pollInterval;
-        for (;;) {
-            const claims = await listClaims(target);
-            if (claims.length === 0)
-                return;
-            if (pollInterval == null) {
-                throw new AbloValidationError('Cannot wait for claims over the HTTP client without `pollInterval`. ' +
-                    'Use the schema client for event-driven claim waits, pass `ifClaimed: "return"`, ' +
-                    'or provide an explicit poll interval for this runtime.', { code: 'claim_wait_poll_interval_required' });
-            }
-            if (options?.timeout != null && Date.now() - startedAt >= options.timeout) {
-                throw claimedError(target, claims, 'model_claimed_timeout');
-            }
-            const remaining = options?.timeout == null
-                ? pollInterval
-                : Math.max(0, Math.min(pollInterval, options.timeout - (Date.now() - startedAt)));
-            await delay(remaining, options?.signal);
-        }
-    }
     async function applyClaimedPolicy(target, options, defaultPolicy = 'return') {
         const policy = options?.ifClaimed ?? defaultPolicy;
         if (policy === 'return')
@@ -358,17 +569,17 @@ export function createProtocolClient(options) {
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
+            const requestBody = {
+                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) {
@@ -387,192 +598,18 @@ 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.notifications && body.notifications.length > 0
+                    ? { notifications: body.notifications }
+                    : {}),
                 ...(body.missingIds && body.missingIds.length > 0
                     ? { missingIds: body.missingIds }
                     : {}),
             };
         },
     };
-    const capabilities = {
-        async create(capabilityOptions) {
-            const ttlSeconds = capabilityOptions.ttlSeconds ??
-                capabilityOptions.leaseSeconds ??
-                toSeconds(capabilityOptions.ttl ?? capabilityOptions.lease ?? DEFAULT_AGENT_LEASE);
-            const body = await requestJson('/v1/capabilities', {
-                method: 'POST',
-                body: JSON.stringify({
-                    participantKind: capabilityOptions.participantKind ?? 'agent',
-                    participantId: capabilityOptions.participantId,
-                    syncGroups: capabilityOptions.syncGroups,
-                    operations: capabilityOptions.operations,
-                    ttlSeconds,
-                    label: capabilityOptions.label,
-                    wideScope: capabilityOptions.wideScope,
-                    userMeta: capabilityOptions.userMeta,
-                }),
-            });
-            const id = body.capabilityId ?? body.id;
-            if (!id) {
-                throw new AbloValidationError('Capability create response did not include an id.', { code: 'capability_id_missing' });
-            }
-            return {
-                id,
-                token: body.token,
-                expiresAt: body.expiresAt,
-                organizationId: body.organizationId,
-                scope: body.scope,
-                userMeta: body.userMeta,
-                client: () => childClient(body.token),
-            };
-        },
-        async retrieve(id) {
-            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}`, { method: 'GET' });
-            return {
-                id: body.capabilityId ?? body.id ?? id,
-                organizationId: body.organizationId,
-                participantKind: body.participantKind,
-                participantId: body.participantId,
-                label: body.label,
-                status: body.status,
-                issuedAt: body.issuedAt,
-                expiresAt: body.expiresAt,
-                revokedAt: body.revokedAt,
-                lastUsedAt: body.lastUsedAt,
-                operations: body.operations ?? [],
-                syncGroups: body.syncGroups ?? [],
-            };
-        },
-        async revoke(id) {
-            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}`, { method: 'DELETE' });
-            return {
-                id: body.capabilityId ?? body.id ?? id,
-                deleted: body.deleted ?? true,
-                activeSessionsClosed: body.activeSessionsClosed,
-            };
-        },
-        async rotate(id, rotateOptions = {}) {
-            const graceSeconds = rotateOptions.graceSeconds ??
-                (rotateOptions.grace !== undefined ? toSeconds(rotateOptions.grace) : undefined);
-            const leaseSeconds = rotateOptions.leaseSeconds ??
-                (rotateOptions.lease !== undefined ? toSeconds(rotateOptions.lease) : undefined);
-            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}/rotate`, {
-                method: 'POST',
-                body: JSON.stringify({
-                    ...(graceSeconds !== undefined ? { graceSeconds } : {}),
-                    ...(leaseSeconds !== undefined ? { ttlSeconds: leaseSeconds } : {}),
-                }),
-            });
-            const newId = body.capabilityId ?? body.id;
-            if (!newId) {
-                throw new AbloValidationError('Capability rotate response did not include an id.', { code: 'capability_id_missing' });
-            }
-            return {
-                id: newId,
-                token: body.token,
-                expiresAt: body.expiresAt,
-                organizationId: body.organizationId,
-                scope: body.scope,
-                rotatedFrom: {
-                    id: body.rotatedFrom.capabilityId ?? body.rotatedFrom.id ?? id,
-                    expiresAt: body.rotatedFrom.expiresAt,
-                },
-                client: () => childClient(body.token),
-            };
-        },
-        mint(options) {
-            return capabilities.create(options);
-        },
-    };
-    const claims = {
-        async create(claimOptions) {
-            const claimId = createClaimId();
-            const body = await requestJson('/v1/claims', {
-                method: 'POST',
-                body: JSON.stringify({
-                    claimId,
-                    target: claimOptions.target,
-                    reason: claimOptions.reason,
-                    ttl: claimOptions.ttl,
-                    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 (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 ` +
-                    `the grant (no socket) — use the realtime client to wait in line.`, { code: 'claim_queued' });
-            }
-            const id = body.claim?.id ?? claimId;
-            let released = false;
-            const release = async () => {
-                if (released)
-                    return;
-                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,
-                    id: claimOptions.target.id,
-                    ...(claimOptions.target.field ? { field: claimOptions.target.field } : {}),
-                    ...(claimOptions.target.path ? { path: claimOptions.target.path } : {}),
-                    ...(claimOptions.target.range ? { range: claimOptions.target.range } : {}),
-                    ...(claimOptions.target.meta ? { meta: claimOptions.target.meta } : {}),
-                },
-                release,
-                revoke: () => {
-                    void release().catch(() => { });
-                },
-                [Symbol.asyncDispose]: release,
-            };
-        },
-        list: listClaims,
-        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();
         if (options?.limit !== undefined)
@@ -628,7 +665,7 @@ export function createProtocolClient(options) {
      * 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,
@@ -644,15 +681,15 @@ 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 = {
-            idempotencyKey: clientTxId,
             claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
             onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
             readAt,
@@ -663,11 +700,12 @@ 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) {
             // The per-model write door (`ablo.<model>.update/create/delete`). Capture
@@ -680,7 +718,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,
         };
@@ -809,11 +847,14 @@ export function createProtocolClient(options) {
             state: async (params) => {
                 const res = await claimsForEntity(params);
                 const first = res.claims?.[0];
-                return first ?? null;
+                return first ? claimFromModelClaim(first) : null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
-                return { object: 'list', data: res.queue ?? [] };
+                return {
+                    object: 'list',
+                    data: (res.queue ?? []).map(claimFromModelClaim),
+                };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
@@ -885,7 +926,7 @@ 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
@@ -893,15 +934,23 @@ export function createProtocolClient(options) {
                     // 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.
+                    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,
@@ -915,11 +964,12 @@ export function createProtocolClient(options) {
     }
     return {
         ready,
-        async waitForFlush() { },
+        waitForFlush: () => runInHttpCommitLane(async () => {
+            await ready();
+            await replayHttpCommitOutbox();
+        }),
         async dispose() { },
         async purge() { },
-        capabilities,
-        claims,
         commits,
         model,
         sessions: {
@@ -935,6 +985,9 @@ export function createProtocolClient(options) {
                     apiKey,
                     baseUrl: apiBaseUrl,
                     ...(options.fetch ? { fetch: options.fetch } : {}),
+                    ...(options.modelTypenames
+                        ? { modelTypenames: options.modelTypenames }
+                        : {}),
                 });
             },
         },