@abloatai/ablo 0.29.2 → 0.30.0

package/dist/client/httpTransport.js

@@ -6,17 +6,15 @@
  * transport envelopes, watermarks, replay, and route details.
  */
 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 { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, rejectRemovedDatabaseUrlOption, warnIfCliKeyMismatch, } from './auth.js';
 import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
+import { commitReceiptSchema } from '../wire/commit.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`;
@@ -38,23 +36,9 @@ import { createDurableHttpCommitEnvelope, canonicalHttpCommitBody, durableHttpCo
 import { resolveDurableWrites } from './durableWrites.js';
 /** @internal Default per-request deadline for the private 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(),
-    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();
+const HTTP_CONFIRMATION_POLL_INTERVAL_MS = 250;
 function parseSuccessfulCommitResponse(value, idempotencyKey) {
-    const parsed = successfulCommitResponseSchema.safeParse(value);
+    const parsed = commitReceiptSchema.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',
@@ -71,8 +55,8 @@ function claimFromModelClaim(claim) {
         object: 'claim',
         id: claim.id,
         ...(claim.status ? { status: claim.status } : {}),
-        reason: claim.reason,
-        ...(claim.description ? { description: claim.description } : {}),
+        // The server always stamps a description; default only for total safety.
+        description: claim.description ?? 'editing',
         heldBy: claim.actor,
         participantKind: claim.participantKind,
         expiresAt: claim.expiresAt,
@@ -93,15 +77,10 @@ export function createHttpTransport(options) {
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
-    const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
-    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
-    // passed — no logger on this path, so the helper falls back to console.warn.
-    warnIfDatabaseUrlEnvIgnored(authInput);
-    warnIfDatabaseUrlDeprecated(authInput);
     void warnIfCliKeyMismatch(authInput);
+    rejectRemovedDatabaseUrlOption(options);
     assertBrowserSafety({
         apiKey: configuredApiKey,
-        databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     // Observability hook for the stateless HTTP transport. The WebSocket transport
@@ -154,7 +133,8 @@ export function createHttpTransport(options) {
     // constructor exposes the behavior as `durableWrites`.
     const commitOutbox = durableWrites.store;
     const durableWriteNamespace = durableWrites.namespace ?? 'http';
-    const legacyCommitOutboxScope = options.commitOutboxScope;
+    const legacyCommitOutboxScope = options
+        .commitOutboxScope;
     const httpOutboxPlaneNamespace = canonicalHttpCommitBody({
         apiBaseUrl,
         defaultQuery: Object.entries(options.defaultQuery ?? {}).sort(([a], [b]) => a.localeCompare(b)),
@@ -197,14 +177,6 @@ export function createHttpTransport(options) {
         if (readyPromise)
             return readyPromise;
         readyPromise = (async () => {
-            if (configuredDatabaseUrl) {
-                await registerDataSource({
-                    baseUrl: apiBaseUrl,
-                    apiKey: await resolveApiKeyValue(configuredApiKey),
-                    databaseUrl: configuredDatabaseUrl,
-                    ...(options.fetch ? { fetchImpl: options.fetch } : {}),
-                });
-            }
             await resolveHttpOutboxScope();
             await replayHttpCommitOutbox();
         })();
@@ -270,7 +242,9 @@ export function createHttpTransport(options) {
         // same pattern already guards `query/client.ts` and `BootstrapFetcher`.
         const callerSignal = requestInit.signal ?? undefined;
         const controller = new AbortController();
-        const onCallerAbort = () => { controller.abort(callerSignal?.reason); };
+        const onCallerAbort = () => {
+            controller.abort(callerSignal?.reason);
+        };
         if (callerSignal) {
             if (callerSignal.aborted)
                 onCallerAbort();
@@ -349,6 +323,110 @@ export function createHttpTransport(options) {
             throw new AbloConnectionError('The server settled the commit, but its local outbox record could not be cleared.', { code: 'db_not_opened', cause });
         }
     }
+    /**
+     * Persist the first queued source receipt before exposing acceptance to the
+     * caller. This is a monotonic upgrade of the same sealed request: connected
+     * source keys are permanent, so the envelope may safely remain replayable
+     * after the hosted 24-hour idempotency window while it awaits its WAL echo.
+     */
+    async function persistHttpAcceptance(envelope, response) {
+        if (!commitOutbox || response.status !== 'queued')
+            return envelope;
+        const correlationId = response.correlationId;
+        if (!correlationId) {
+            throw new AbloConnectionError('The source accepted the commit without durable correlation evidence.', { code: 'commit_no_result' });
+        }
+        if (envelope.correlationId !== undefined && envelope.correlationId !== correlationId) {
+            throw new AbloIdempotencyError('The same HTTP commit replay returned a different source correlation.', { code: 'idempotency_conflict' });
+        }
+        if (envelope.acceptedAt !== undefined)
+            return envelope;
+        const accepted = durableHttpCommitEnvelopeSchema.parse({
+            ...envelope,
+            acceptedAt: Date.now(),
+            correlationId,
+        });
+        try {
+            await commitOutbox.seal(accepted, []);
+        }
+        catch (cause) {
+            throw new AbloConnectionError('The source accepted the commit, but that acceptance could not be persisted locally.', { code: 'db_not_opened', cause });
+        }
+        return accepted;
+    }
+    function replicationLagTimeout(request, response) {
+        return new AbloConnectionError(`The source accepted commit ${request.idempotencyKey}, but its replication echo did not arrive within ${requestTimeoutMs}ms.`, {
+            code: 'replication_lag_timeout',
+            httpStatus: 504,
+            details: {
+                clientTxId: request.idempotencyKey,
+                ...(response.correlationId ? { correlationId: response.correlationId } : {}),
+                timeoutMs: requestTimeoutMs,
+                accepted: true,
+            },
+        });
+    }
+    /**
+     * Replays one byte-identical, idempotent HTTP commit until mutation-log
+     * replay reports the source echo as confirmed. `queued` is acceptance only:
+     * this loop never clears the durable envelope and never converts it into a
+     * successful `wait: 'confirmed'` result.
+     */
+    async function pollHttpCommitConfirmation(request, initial) {
+        let current = initial;
+        const correlationId = initial.correlationId;
+        const deadlineAt = requestTimeoutMs > 0 ? Date.now() + requestTimeoutMs : null;
+        while (current.status === 'queued') {
+            const remaining = deadlineAt === null ? null : deadlineAt - Date.now();
+            if (remaining !== null && remaining <= 0) {
+                throw replicationLagTimeout(request, current);
+            }
+            const confirmationController = new AbortController();
+            const confirmationDeadline = remaining !== null
+                ? setTimeout(() => {
+                    confirmationController.abort();
+                }, remaining)
+                : null;
+            try {
+                const raw = await requestJson(request.path, {
+                    method: request.method,
+                    idempotencyKey: request.idempotencyKey,
+                    ...(request.sealedProtocolVersion !== undefined
+                        ? { sealedProtocolVersion: request.sealedProtocolVersion }
+                        : {}),
+                    body: request.body,
+                    signal: confirmationController.signal,
+                }, true);
+                const next = parseSuccessfulCommitResponse(raw, request.idempotencyKey);
+                if (next.correlationId !== correlationId) {
+                    throw new AbloIdempotencyError('The same HTTP commit replay returned different source correlation evidence.', { code: 'idempotency_conflict' });
+                }
+                current = next;
+            }
+            catch (error) {
+                if (confirmationController.signal.aborted ||
+                    (deadlineAt !== null && Date.now() >= deadlineAt)) {
+                    throw replicationLagTimeout(request, current);
+                }
+                throw error;
+            }
+            finally {
+                if (confirmationDeadline)
+                    clearTimeout(confirmationDeadline);
+            }
+            if (current.status === 'confirmed')
+                return current;
+            const delayMs = deadlineAt === null
+                ? HTTP_CONFIRMATION_POLL_INTERVAL_MS
+                : Math.min(HTTP_CONFIRMATION_POLL_INTERVAL_MS, Math.max(0, deadlineAt - Date.now()));
+            if (delayMs > 0) {
+                await new Promise((resolve) => {
+                    setTimeout(resolve, delayMs);
+                });
+            }
+        }
+        return current;
+    }
     async function replayHttpCommitOutbox() {
         const replayed = new Map();
         if (!commitOutbox)
@@ -374,8 +452,7 @@ export function createHttpTransport(options) {
             }
             envelopes.push(parsed.data);
         }
-        envelopes.sort((a, b) => (a.sequence ?? a.sealedAt * 1_000) -
-            (b.sequence ?? b.sealedAt * 1_000) ||
+        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 {
@@ -386,8 +463,21 @@ export function createHttpTransport(options) {
                     body: envelope.request.body,
                 }, true);
                 const response = parseSuccessfulCommitResponse(raw, envelope.idempotencyKey);
-                await settleHttpEnvelope(envelope.id);
-                replayed.set(envelope.idempotencyKey, { envelope, response });
+                if (envelope.correlationId !== undefined &&
+                    response.correlationId !== envelope.correlationId) {
+                    throw new AbloIdempotencyError('The saved HTTP commit replay returned different source correlation evidence.', { code: 'idempotency_conflict' });
+                }
+                const replayEnvelope = await persistHttpAcceptance(envelope, response);
+                // A queued source receipt is only acceptance. Keep the exact request
+                // durable so startup/retry can ask mutation-log replay whether its WAL
+                // echo has materialized; only confirmed is a definitive success.
+                if (response.status === 'confirmed') {
+                    await settleHttpEnvelope(envelope.id);
+                }
+                replayed.set(envelope.idempotencyKey, {
+                    envelope: replayEnvelope,
+                    response,
+                });
             }
             catch (error) {
                 if (isDefinitiveHttpRejection(error)) {
@@ -398,6 +488,37 @@ export function createHttpTransport(options) {
         }
         return replayed;
     }
+    /**
+     * A flush is stronger than startup replay: it promises that every retained
+     * envelope has reached a definitive outcome, not merely that the server
+     * accepted it for forwarding. Poll queued receipts through mutation-log
+     * replay and leave their envelopes intact if the confirmation deadline
+     * expires.
+     */
+    async function confirmReplayedHttpCommits(replayed) {
+        for (const { envelope, response } of replayed.values()) {
+            if (response.status !== 'queued')
+                continue;
+            try {
+                const confirmed = await pollHttpCommitConfirmation({
+                    idempotencyKey: envelope.idempotencyKey,
+                    method: envelope.request.method,
+                    path: envelope.request.path,
+                    body: envelope.request.body,
+                    sealedProtocolVersion: envelope.protocolVersion,
+                }, response);
+                if (confirmed.status === 'confirmed') {
+                    await settleHttpEnvelope(envelope.id);
+                }
+            }
+            catch (error) {
+                if (isDefinitiveHttpRejection(error)) {
+                    await settleHttpEnvelope(envelope.id);
+                }
+                throw error;
+            }
+        }
+    }
     let lastHttpCommitSequence = 0;
     function nextHttpCommitSequence() {
         const wallSequence = Date.now() * 1_000;
@@ -457,22 +578,56 @@ export function createHttpTransport(options) {
                     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;
+                let priorResponse = prior.response;
+                if (priorResponse.status === 'queued' && input.wait === 'confirmed') {
+                    try {
+                        priorResponse = await pollHttpCommitConfirmation({
+                            idempotencyKey: prior.envelope.idempotencyKey,
+                            method: prior.envelope.request.method,
+                            path: prior.envelope.request.path,
+                            body: prior.envelope.request.body,
+                            sealedProtocolVersion: prior.envelope.protocolVersion,
+                        }, priorResponse);
+                    }
+                    catch (error) {
+                        if (isDefinitiveHttpRejection(error)) {
+                            await settleHttpEnvelope(prior.envelope.id);
+                        }
+                        throw error;
+                    }
+                }
+                if (priorResponse.status === 'confirmed') {
+                    await beforeSettlement?.(priorResponse);
+                    await settleHttpEnvelope(prior.envelope.id);
+                }
+                return priorResponse;
             }
             const durableEnvelope = await sealHttpCommit(input);
             const requestBody = durableEnvelope?.request.body ?? canonicalHttpCommitBody(input.body);
+            const exactRequest = {
+                idempotencyKey: input.idempotencyKey,
+                method: input.method,
+                path: input.path,
+                body: requestBody,
+                ...(durableEnvelope ? { sealedProtocolVersion: durableEnvelope.protocolVersion } : {}),
+            };
             let response;
             try {
-                const raw = await requestJson(input.path, {
-                    method: input.method,
-                    idempotencyKey: input.idempotencyKey,
-                    ...(durableEnvelope
-                        ? { sealedProtocolVersion: durableEnvelope.protocolVersion }
+                const raw = await requestJson(exactRequest.path, {
+                    method: exactRequest.method,
+                    idempotencyKey: exactRequest.idempotencyKey,
+                    ...(exactRequest.sealedProtocolVersion !== undefined
+                        ? { sealedProtocolVersion: exactRequest.sealedProtocolVersion }
                         : {}),
-                    body: requestBody,
+                    body: exactRequest.body,
                 }, true);
                 response = parseSuccessfulCommitResponse(raw, input.idempotencyKey);
+                if (durableEnvelope && response.status === 'queued') {
+                    await persistHttpAcceptance(durableEnvelope, response);
+                }
+                if (response.status === 'queued' && input.wait === 'confirmed') {
+                    response = await pollHttpCommitConfirmation(exactRequest, response);
+                }
             }
             catch (error) {
                 if (durableEnvelope && isDefinitiveHttpRejection(error)) {
@@ -482,9 +637,13 @@ export function createHttpTransport(options) {
             }
             // 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);
+            // A queued source receipt cannot be read back from the log yet and stays
+            // durable until a later confirmed replay.
+            if (response.status === 'confirmed') {
+                await beforeSettlement?.(response);
+                if (durableEnvelope)
+                    await settleHttpEnvelope(durableEnvelope.id);
+            }
             return response;
         });
     }
@@ -508,7 +667,7 @@ export function createHttpTransport(options) {
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function normalizeCommitOperation(op, defaults) {
+    function normalizeCommitOperation(op, defaults, fenceToken) {
         return {
             action: op.action,
             model: op.model,
@@ -517,13 +676,18 @@ export function createHttpTransport(options) {
             transactionId: op.transactionId ?? null,
             readAt: op.readAt ?? defaults.readAt ?? null,
             onStale: op.onStale ?? defaults.onStale ?? null,
+            // The batch's claim (if any) supplies one token for every op, mirroring
+            // how it supplies the batch `readAt`.
+            fenceToken: op.fenceToken ?? fenceToken ?? null,
         };
     }
-    function normalizeCommitOperations(commitOptions) {
+    function normalizeCommitOperations(commitOptions, fenceToken) {
         if (commitOptions.operations.length === 0) {
-            throw new AbloValidationError('Commit requires a non-empty `operations` array.', { code: 'commit_operation_required' });
+            throw new AbloValidationError('Commit requires a non-empty `operations` array.', {
+                code: 'commit_operation_required',
+            });
         }
-        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions));
+        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions, fenceToken));
     }
     async function listClaimState(target) {
         const params = new URLSearchParams();
@@ -534,7 +698,9 @@ export function createHttpTransport(options) {
         if (target?.field)
             params.set('field', target.field);
         const suffix = params.toString();
-        const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
+        const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, {
+            method: 'GET',
+        });
         return {
             active: body.claims ?? [],
             queue: body.queue ?? [],
@@ -568,11 +734,12 @@ export function createHttpTransport(options) {
                 ...commitOptions,
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
-            });
+            }, claim?.fenceToken ?? null);
             const requestBody = {
                 operations,
                 reads: commitOptions.reads,
             };
+            const wait = commitOptions.wait ?? 'confirmed';
             let body;
             try {
                 body = await dispatchHttpCommit({
@@ -580,6 +747,7 @@ export function createHttpTransport(options) {
                     method: 'POST',
                     idempotencyKey: clientTxId,
                     body: requestBody,
+                    wait,
                 });
             }
             catch (error) {
@@ -604,9 +772,7 @@ export function createHttpTransport(options) {
                 ...(body.notifications && body.notifications.length > 0
                     ? { notifications: body.notifications }
                     : {}),
-                ...(body.missingIds && body.missingIds.length > 0
-                    ? { missingIds: body.missingIds }
-                    : {}),
+                ...(body.missingIds && body.missingIds.length > 0 ? { missingIds: body.missingIds } : {}),
             };
         },
     };
@@ -693,6 +859,9 @@ export function createHttpTransport(options) {
             claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
             onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
             readAt,
+            // The claim's fencing token (Option B), so the per-model HTTP write door
+            // fences the same as the WS proxy and `commits.create`.
+            fenceToken: options?.fenceToken ?? claimHandle?.fenceToken,
         };
         if (action === 'create')
             requestBody.id = id;
@@ -705,6 +874,7 @@ export function createHttpTransport(options) {
                 method,
                 idempotencyKey: clientTxId,
                 body: requestBody,
+                wait: options?.wait ?? 'confirmed',
             }, beforeSettlement);
         }
         catch (error) {
@@ -733,18 +903,13 @@ export function createHttpTransport(options) {
             value.object === 'claim' &&
             typeof value.id === 'string' &&
             typeof value.release === 'function';
-        const claimMeta = (options) => {
-            if (!options?.description)
-                return options?.meta;
-            return { ...(options.meta ?? {}), description: options.description };
-        };
+        const claimMeta = (options) => options?.meta;
         const acquireClaim = async (params) => {
             const body = await requestJson(claimPath(params.id), {
                 method: 'POST',
                 body: JSON.stringify({
-                    reason: params.reason ?? 'editing',
+                    description: params.description ?? 'editing',
                     ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
-                    ...(params.description !== undefined ? { description: params.description } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
                     // `queue` (default true) → queue behind the holder; false → fail-fast
                     // with AbloClaimedError (work-distribution dedup).
@@ -757,9 +922,13 @@ export function createHttpTransport(options) {
             }
             // `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 id = body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
+            const fenceToken = body.claim?.fenceToken;
+            return fenceToken !== undefined ? { id, fenceToken } : { id };
         };
-        const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
+        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.
@@ -775,14 +944,14 @@ export function createHttpTransport(options) {
             return heldHeartbeatReply(reply, `claim ${claimId} on ${name}/${id}`);
         };
         async function claimImpl(params) {
-            const claimId = await acquireClaim(params);
+            const { id: claimId, fenceToken } = await acquireClaim(params);
             observability?.captureClaim({
                 phase: 'acquired',
                 claimId,
                 model: name,
                 id: params.id,
                 ...(params.field ? { field: params.field } : {}),
-                reason: params.reason ?? 'editing',
+                reason: params.description ?? 'editing',
             });
             const { data, stamp } = await retrieveModel(name, { id: params.id });
             // A held claim hands back a snapshot; the typed `HeldClaim.data` is `T`.
@@ -795,9 +964,7 @@ export function createHttpTransport(options) {
                 const resolved = resolveHeartbeatOptions(beatOptions);
                 const beat = await heartbeatClaim(params.id, claimId, {
                     ttl: resolved.ttl ?? params.ttl,
-                    ...(resolved.details !== undefined
-                        ? { details: resolved.details }
-                        : {}),
+                    ...(resolved.details !== undefined ? { details: resolved.details } : {}),
                 });
                 params.onHeartbeat?.(beat);
                 return beat;
@@ -809,9 +976,7 @@ export function createHttpTransport(options) {
                 ? startClaimHeartbeatLoop({
                     beat: () => heartbeat(),
                     intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : 60_000, params.heartbeat),
-                    ...(params.onHeartbeatLost
-                        ? { onLost: params.onHeartbeatLost }
-                        : {}),
+                    ...(params.onHeartbeatLost ? { onLost: params.onHeartbeatLost } : {}),
                 })
                 : undefined;
             const release = () => {
@@ -822,6 +987,7 @@ export function createHttpTransport(options) {
                 object: 'claim',
                 id: claimId,
                 readAt: stamp,
+                ...(fenceToken !== undefined ? { fenceToken } : {}),
                 target: {
                     type: name,
                     id: params.id,
@@ -830,8 +996,7 @@ export function createHttpTransport(options) {
                     ...(params.range ? { range: params.range } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
                 },
-                reason: params.reason ?? 'editing',
-                ...(params.description ? { description: params.description } : {}),
+                description: params.description ?? 'editing',
                 data,
                 release,
                 revoke: () => {
@@ -861,7 +1026,9 @@ export function createHttpTransport(options) {
                     method: 'POST',
                     // 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 })) }),
+                    body: JSON.stringify({
+                        order: params.order.map((i) => ({ heldBy: i.heldBy, claimId: i.id })),
+                    }),
                 });
             },
         });
@@ -875,12 +1042,17 @@ export function createHttpTransport(options) {
             // `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({
+            const { id: claimId, fenceToken } = await acquireClaim({
                 id,
                 ...claimInput,
             });
             try {
-                return await run({ ...input, claimRef: { id: claimId }, claim: undefined });
+                return await run({
+                    ...input,
+                    claimRef: { id: claimId },
+                    ...(fenceToken !== undefined ? { fenceToken } : {}),
+                    claim: undefined,
+                });
             }
             finally {
                 await releaseClaim({ id }).catch(() => { });
@@ -937,7 +1109,10 @@ export function createHttpTransport(options) {
                     let created;
                     await mutateModel('create', name, id, params.data, {
                         ...options,
-                        wait: options?.wait ?? 'confirmed',
+                        // This method returns the authoritative row, not a receipt. A
+                        // queued source acceptance cannot satisfy that return contract,
+                        // even when the caller supplied `wait: 'queued'`.
+                        wait: 'confirmed',
                     }, async () => {
                         const read = await retrieveModel(name, { id });
                         if (read.data === undefined) {
@@ -966,7 +1141,8 @@ export function createHttpTransport(options) {
         ready,
         waitForFlush: () => runInHttpCommitLane(async () => {
             await ready();
-            await replayHttpCommitOutbox();
+            const replayed = await replayHttpCommitOutbox();
+            await confirmReplayedHttpCommits(replayed);
         }),
         async dispose() { },
         async purge() { },
@@ -985,9 +1161,7 @@ export function createHttpTransport(options) {
                     apiKey,
                     baseUrl: apiBaseUrl,
                     ...(options.fetch ? { fetch: options.fetch } : {}),
-                    ...(options.modelTypenames
-                        ? { modelTypenames: options.modelTypenames }
-                        : {}),
+                    ...(options.modelTypenames ? { modelTypenames: options.modelTypenames } : {}),
                 });
             },
         },

package/dist/client/options.d.ts

@@ -89,21 +89,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * route, and passing both is a validation error.
      */
     authEndpoint?: string | ApiKeySetter | null | undefined;
-    /**
-     * @deprecated The direct connector lets Ablo dial into your Postgres and write to
-     * it directly. Prefer the signed data-source endpoint: keep your `DATABASE_URL`
-     * in your own app, expose `dataSource(...)`, and let your server own the write
-     * while Ablo coordinates the sync stream. Ablo hosts only the ordered
-     * `sync_deltas` log and coordination, never your rows. To keep the log in your own
-     * infrastructure as well, self-host the engine.
-     *
-     * Still honored at runtime for backward compatibility. It is server-only: because
-     * it carries credentials it is never sent from the browser, and constructing a
-     * client with both `databaseUrl` and `dangerouslyAllowBrowser` throws. If you do
-     * use it, supply a role that is neither a superuser nor `BYPASSRLS`; the connector
-     * rejects privileged roles that cannot enforce row-level security.
-     */
-    databaseUrl?: string | null | undefined;
     /**
      * Local persistence mode. Pass `indexeddb` only when you want offline
      * queueing and a reload-surviving browser cache.