@abloatai/ablo 0.27.0 → 0.28.0

package/dist/cli.cjs

@@ -276796,7 +276796,7 @@ var ERROR_CODES = {
   jwt_invalid: wire("auth", 401, false, "The bearer JWT failed validation for a reason the server could not classify further. Check the token's issuer, signature, audience, and expiry."),
   jwt_malformed: wire("auth", 401, false, "The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent."),
   jwt_missing_issuer: wire("auth", 401, false, "The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer."),
-  jwt_issuer_untrusted: wire("auth", 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Register it via POST /v1/trusted-issuers, or check the token's issuer claim."),
+  jwt_issuer_untrusted: wire("auth", 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Check the token's issuer claim, or register the issuer with your deployment before retrying."),
   jwt_signature_invalid: wire("auth", 401, false, "The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token)."),
   jwt_audience_mismatch: wire("auth", 401, false, "The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with."),
   jwt_missing_subject: wire("auth", 401, false, "The bearer JWT has no `sub` (subject) claim to identify the user."),
@@ -276845,7 +276845,11 @@ var ERROR_CODES = {
   model_claim_not_configured: client("claim", "Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically \u2014 there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path)."),
   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 row changed after you read it \u2014 the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
+  // Not retryable at the transport: the rejected request carries its frozen
+  // `readAt`, so resending the identical payload can never succeed. Recovery
+  // is a caller-level re-read that produces a NEW request with a fresh
+  // watermark — the same shape as `claim_conflict`.
+  stale_context: wire("conflict", 409, false, "The row changed after you read it \u2014 the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
   // Raised by the functional `update(id, current => next)` form once its
   // internal reconcile budget is exhausted, because the row stayed continuously
   // contended. The SDK has already retried; the caller decides whether to back

package/dist/client/Ablo.d.ts

@@ -18,7 +18,7 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
-import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate, InferRow } from '../schema/schema.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
 import { InstanceCache } from '../InstanceCache.js';
@@ -34,6 +34,18 @@ export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.j
 export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, ModelRead, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, ModelClient, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
 export { computeFKDepthPriority } from './schemaConfig.js';
 import type { ModelOperations } from './createModelProxy.js';
+/**
+ * The reactive-read client a `useAblo` selector receives. The same surface as
+ * {@link Ablo}, except model reads are typed as reactive rows
+ * ({@link InferRow}: data fields + computeds, no relation accessors, no model
+ * methods) — the shape a reactive read actually delivers after
+ * `toReactiveSnapshot()`. Reading `row.layers` off a reactive read is a
+ * compile error here instead of a silent runtime `undefined`; compose
+ * relations through selectors or hooks that resolve the pool's instance.
+ */
+export type AbloReads<S extends SchemaRecord> = Omit<Ablo<S>, keyof S & string> & {
+    readonly [K in keyof S & string]: ModelOperations<InferRow<Schema<S>, K>, InferCreate<Schema<S>, K>>;
+};
 /** The typed sync engine client — one property per model in the schema */
 export type Ablo<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: ModelOperations<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
@@ -351,6 +363,11 @@ import type * as _SchemaTypes from '../schema/schema.js';
  */
 export declare namespace Ablo {
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
+    /**
+     * The read view of the client that `useAblo` selectors receive: model reads
+     * typed as reactive rows (data fields + computeds, no relation accessors).
+     */
+    type Reads<S extends SchemaRecord = SchemaRecord> = AbloReads<S>;
     type Api = AbloApi;
     type ApiClaims = AbloApiClaims;
     type Capability = import('./ApiClient.js').Capability;
@@ -390,6 +407,12 @@ export declare namespace Ablo {
     namespace Schema {
         type InferModel<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferModel<S, K>;
         type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
+        /**
+         * The reactive-row companion to {@link InferModel}: data fields + computed
+         * getters, no relation accessors, no model methods — the shape `useAblo`
+         * reads return.
+         */
+        type InferRow<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferRow<S, K>;
         type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
     }
     type Conflict = _Policy.Conflict;

package/dist/client/Ablo.js

@@ -18,6 +18,7 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
+import { durableCommitOperationSchema, } from '../transactions/commitEnvelope.js';
 import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { initSyncEngine } from '../context.js';
@@ -523,7 +524,7 @@ export function Ablo(options) {
         }
         const type = op.action.toUpperCase();
         const id = op.id ?? op.target?.id ?? '';
-        return {
+        return durableCommitOperationSchema.parse({
             type,
             model: model.toLowerCase(),
             id,
@@ -531,7 +532,7 @@ export function Ablo(options) {
             transactionId: op.transactionId ?? undefined,
             readAt: op.readAt ?? defaults.readAt ?? undefined,
             onStale: op.onStale ?? defaults.onStale ?? undefined,
-        };
+        });
     }
     function normalizeCommitOperations(commitOptions) {
         if (commitOptions.operation && commitOptions.operations) {
@@ -817,7 +818,7 @@ export function Ablo(options) {
             // SyncClient we already hold from createInternalComponents —
             // no need to leak an accessor through BaseSyncedStore.
             const queue = syncClient.getTransactionQueue();
-            queue.enqueueCommit(clientTxId, operations, {
+            await queue.enqueueCommit(clientTxId, operations, {
                 ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
             });
             if (wait === 'queued') {

package/dist/client/ApiClient.js

@@ -4,7 +4,9 @@
  * 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';
@@ -12,6 +14,7 @@ import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersi
 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`;
@@ -29,8 +32,35 @@ 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';
+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();
@@ -64,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',
@@ -90,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;
@@ -144,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)
@@ -189,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.
@@ -209,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;
@@ -221,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) {
@@ -358,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) {
@@ -387,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
@@ -398,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({
@@ -425,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) {
@@ -479,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) {
@@ -628,7 +881,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,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 = {
@@ -663,11 +917,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 +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,
         };
@@ -885,7 +1140,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 +1148,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,7 +1178,10 @@ export function createProtocolClient(options) {
     }
     return {
         ready,
-        async waitForFlush() { },
+        waitForFlush: () => runInHttpCommitLane(async () => {
+            await ready();
+            await replayHttpCommitOutbox();
+        }),
         async dispose() { },
         async purge() { },
         capabilities,

package/dist/client/createInternalComponents.d.ts

@@ -16,6 +16,7 @@ import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import { type AbloPersistence } from './persistence.js';
+import type { CommitOutboxStore } from '../transactions/commitOutboxStore.js';
 export interface InternalComponentsInput<S extends SchemaRecord> {
     readonly schema: Schema<S>;
     /** The WebSocket URL. Used to derive the bootstrap HTTP base URL when the
@@ -28,6 +29,7 @@ export interface InternalComponentsInput<S extends SchemaRecord> {
         readonly persistence?: AbloPersistence;
         readonly offline?: boolean;
         readonly inMemory?: boolean;
+        readonly commitOutbox?: CommitOutboxStore;
     };
     readonly auth?: AuthCredentialSource;
 }

package/dist/client/createInternalComponents.js

@@ -41,7 +41,7 @@ export function createInternalComponents(input) {
         // IndexedDB is unavailable there.
         inMemory: shouldUseInMemoryPersistence(options),
     });
-    const syncClient = new SyncClient(objectPool, database);
+    const syncClient = new SyncClient(objectPool, database, options.commitOutbox, url);
     // Lazy-load lane: hydrates the object pool and IndexedDB on demand for
     // entities not in scope at bootstrap (`load: 'lazy'` models, or an entity
     // reached by deep link before the pool warmed up). Single-flight, with