@abloatai/transaction 0.48.0 → 0.50.0

package/src/transport/httpTransport.ts

@@ -22,7 +22,7 @@ import { z } from 'zod';
 import {
   reconcileFunctionalUpdate,
   type ModelUpdater,
-  type ContentionOptions,
+  type FunctionalUpdateOptions,
 } from '../resources/functionalUpdate.js';
 import {
   assertBrowserSafety,
@@ -36,7 +36,14 @@ import {
   warnIfCliKeyMismatch,
 } from '../auth/apiKey.js';
 import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
-import { commitReceiptSchema, type CommitReceiptWire } from '../wire/commit.js';
+import {
+  commitReceiptSchema,
+  commitRecordSchema,
+  commitRecordListSchema,
+  commitRecordListOptionsSchema,
+  commitRecordWhereSchema,
+  type CommitReceiptWire,
+} from '../wire/commit.js';
 import { logListResponseSchema } from '../wire/feedEvent.js';
 import {
   claimAcquireResponseSchema,
@@ -89,6 +96,7 @@ import {
   rotateCapability,
 } from '../auth/capabilityLifecycle.js';
 import { parseIdentityResolveResponse } from '../auth/schemas.js';
+import type { EffectiveAuthority } from '../auth/capability.js';
 
 /**
  * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
@@ -136,6 +144,7 @@ import {
   subTarget,
   streamTarget,
   batchFence,
+  claimIdFor,
   fenceTokenFor,
 } from '../coordination/locator.js';
 import { declaredMeta, wireMeta } from '../coordination/claimMeta.js';
@@ -150,8 +159,8 @@ import {
   isHttpCommitReplayExpired,
   type DurableHttpCommitEnvelope,
   type DurableHttpCommitMethod,
-} from '../transactions/settlement/httpCommitEnvelope.js';
-import type { CommitOutboxScope } from '../transactions/settlement/commitEnvelope.js';
+} from '../transactions/confirmation/httpCommitEnvelope.js';
+import type { CommitOutboxScope } from '../transactions/confirmation/commitEnvelope.js';
 import { resolveDurableWrites } from '../durableWrites.js';
 
 /** @internal Private options for the schema-agnostic HTTP protocol transport. */
@@ -204,6 +213,8 @@ export interface HttpTransport {
    */
   readonly claims: HttpClaimsResource;
   readonly logs: HttpLogsResource;
+  /** Server-confirmed authority of the active bearer, populated by `ready()`. */
+  readonly identity: EffectiveAuthority | null;
   model<T = Record<string, unknown>, Fields = T>(
     name: string,
   ): HttpTransportModel<T, Fields>;
@@ -348,6 +359,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   let httpOutboxScopeNamespace: string | null = null;
 
   let readyPromise: Promise<void> | null = null;
+  let effectiveAuthority: EffectiveAuthority | null = null;
   let httpCommitLane: Promise<void> = Promise.resolve();
 
   function runInHttpCommitLane<T>(work: () => Promise<T>): Promise<T> {
@@ -385,7 +397,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     return httpOutboxScopeNamespace;
   }
 
-  async function ready(): Promise<void> {
+  async function prepare(): Promise<void> {
     if (readyPromise) return readyPromise;
 
     readyPromise = (async () => {
@@ -401,6 +413,14 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     }
   }
 
+  async function ready(): Promise<void> {
+    await prepare();
+    if (!effectiveAuthority) {
+      const rawIdentity = await requestRaw('/auth/identity', { method: 'GET' }, true);
+      effectiveAuthority = parseIdentityResolveResponse(rawIdentity).authority;
+    }
+  }
+
   async function authHeaders(sealedProtocolVersion?: number): Promise<Record<string, string>> {
     const apiKey = await resolveApiKeyValue(configuredApiKey);
     const token = apiKey ?? configuredAuthToken;
@@ -463,7 +483,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     },
     skipReady = false
   ): Promise<unknown> {
-    if (!skipReady) await ready();
+    if (!skipReady) await prepare();
     const { idempotencyKey, sealedProtocolVersion, ...requestInit } = init;
     const headers = await authHeaders(sealedProtocolVersion);
     if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
@@ -589,7 +609,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     try {
       await commitOutbox.remove(recordId);
     } catch (cause) {
-      // Do not report the remote outcome until local settlement is durable.
+      // Do not report the remote outcome until local confirmation 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.',
@@ -652,6 +672,33 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     readonly sealedProtocolVersion?: number;
   }
 
+  function observeCommitReceipt(
+    request: ExactHttpCommitRequest,
+    receipt: CommitResponse,
+  ): void {
+    // A successful receipt carries the same server-authored authority as the
+    // identity exchange. Reuse it so startup replay does not add a redundant
+    // auth request before callers can inspect `identity`.
+    effectiveAuthority = receipt.authority;
+    if (!options.onCommitReceipt) return;
+    let body: unknown = request.body;
+    try {
+      body = JSON.parse(request.body) as unknown;
+    } catch {
+      // Preserve the exact opaque body for observability if it is not JSON.
+    }
+    try {
+      options.onCommitReceipt({
+        receipt,
+        method: request.method,
+        path: request.path,
+        body,
+      });
+    } catch {
+      // Receipt observation must never change the commit outcome.
+    }
+  }
+
   function replicationLagTimeout(
     request: ExactHttpCommitRequest,
     response: CommitResponse
@@ -713,6 +760,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           true
         );
         const next = parseSuccessfulCommitResponse(raw, request.idempotencyKey);
+        observeCommitReceipt(request, next);
         if (next.correlationId !== correlationId) {
           throw new AbloIdempotencyError(
             'The same HTTP commit replay returned different source correlation evidence.',
@@ -794,6 +842,16 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           true
         );
         const response = parseSuccessfulCommitResponse(raw, envelope.idempotencyKey);
+        observeCommitReceipt(
+          {
+            idempotencyKey: envelope.idempotencyKey,
+            method: envelope.request.method,
+            path: envelope.request.path,
+            body: envelope.request.body,
+            sealedProtocolVersion: envelope.protocolVersion,
+          },
+          response,
+        );
         if (
           envelope.correlationId !== undefined &&
           response.correlationId !== envelope.correlationId
@@ -929,11 +987,11 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       body: unknown;
       wait: CommitWait;
     },
-    beforeSettlement?: (response: CommitResponse) => Promise<void>
+    beforeConfirmation?: (response: CommitResponse) => Promise<void>
   ): Promise<CommitResponse> {
     return runInHttpCommitLane(async () => {
-      await ready();
-      // `ready()` covers startup. Re-draining here makes every later write wait
+      await prepare();
+      // Startup preparation covers replay. 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);
@@ -970,7 +1028,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           }
         }
         if (priorResponse.status === 'confirmed') {
-          await beforeSettlement?.(priorResponse);
+          await beforeConfirmation?.(priorResponse);
           await settleHttpEnvelope(prior.envelope.id);
         }
         return priorResponse;
@@ -1000,6 +1058,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           true
         );
         response = parseSuccessfulCommitResponse(raw, input.idempotencyKey);
+        observeCommitReceipt(exactRequest, response);
         if (durableEnvelope && response.status === 'queued') {
           await persistHttpAcceptance(durableEnvelope, response);
         }
@@ -1013,12 +1072,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         throw error;
       }
 
-      // A model-create readback can participate in settlement: if it fails,
+      // A model-create readback can participate in confirmation: if it fails,
       // retain the exact write so a same-key retry recovers the generated 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);
+        await beforeConfirmation?.(response);
         if (durableEnvelope) await settleHttpEnvelope(durableEnvelope.id);
       }
       return response;
@@ -1044,7 +1103,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   function normalizeCommitOperation(
     op: CommitOperationInput,
     defaults: Pick<CommitCreateOptions, 'readAt' | 'onStale'>,
-    fence: BatchFence | null
+    fence: BatchFence | null,
+    claim: Claim | null,
   ): CommitOperationInput {
     return {
       action: op.action,
@@ -1052,6 +1112,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       id: op.id ?? null,
       data: op.data ?? null,
       transactionId: op.transactionId ?? null,
+      claimId:
+        op.claimId ?? claimIdFor(claim?.target, claim?.id, op.model, op.id ?? null),
       readAt: op.readAt ?? defaults.readAt ?? null,
       onStale: op.onStale ?? defaults.onStale ?? null,
       fenceToken: op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null),
@@ -1068,7 +1130,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       });
     }
     return commitOptions.operations.map((op) =>
-      normalizeCommitOperation(op, commitOptions, fence)
+      normalizeCommitOperation(op, commitOptions, fence, commitOptions.claim ?? null)
     );
   }
 
@@ -1270,6 +1332,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           onStale: commitOptions.onStale,
           wait: commitOptions.wait,
           claim: commitOptions.claim,
+          reads: commitOptions.reads,
+          track: commitOptions.track,
         },
         'commits.create'
       );
@@ -1318,7 +1382,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // `requestJson` throws via `translateHttpError` on any non-2xx, so
       // reaching here implies success and `body` is already the success-only
       // receipt union — a rejection is a separate type that never arrives here.
-      // The settlement status therefore passes through verbatim: no branch may
+      // The confirmation status therefore passes through verbatim: no branch may
       // collapse a state the server reported into a different one.
       return {
         id: body.id ?? body.clientTxId,
@@ -1330,6 +1394,34 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         ...(body.missingIds && body.missingIds.length > 0 ? { missingIds: body.missingIds } : {}),
       };
     },
+    get({ id }) {
+      if (!id) {
+        throw new AbloValidationError('commits.get requires a non-empty id.', {
+          code: 'write_options_invalid',
+          param: 'id',
+        });
+      }
+      return requestJson(
+        `/v1/commits/${encodeURIComponent(id)}`,
+        { method: 'GET' },
+        commitRecordSchema.nullable(),
+      );
+    },
+    list(options = {}) {
+      const parsed = commitRecordListOptionsSchema.parse(options);
+      const where = commitRecordWhereSchema.parse(parsed.where ?? {});
+      const params = new URLSearchParams();
+      if (where.actorId) params.set('actorId', where.actorId);
+      if (where.status) params.set('status', where.status);
+      if (parsed.cursor) params.set('cursor', parsed.cursor);
+      if (parsed.limit !== undefined) params.set('limit', String(parsed.limit));
+      const query = params.size > 0 ? `?${params.toString()}` : '';
+      return requestJson(
+        `/v1/commits${query}`,
+        { method: 'GET' },
+        commitRecordListSchema,
+      );
+    },
   };
 
   const logs: HttpLogsResource = {
@@ -1352,7 +1444,10 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     },
   };
 
-  async function listModel<T>(modelName: string, options?: ServerReadOptions<T>): Promise<T[]> {
+  async function listModel<T>(
+    modelName: string,
+    options?: ServerReadOptions<T>,
+  ): Promise<{ readonly data: readonly T[]; readonly evidence?: readonly { id: string; stamp: number }[] }> {
     const params = new URLSearchParams();
     if (options?.limit !== undefined) params.set('limit', String(options.limit));
     if (options?.orderBy) {
@@ -1380,7 +1475,10 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     // transport is schema-agnostic — it moves rows for whatever schema the
     // caller declared, and `T` is that declaration. Row validation belongs to
     // the typed facade above, which holds the model's schema.
-    return res.data as T[];
+    return {
+      data: res.data as T[],
+      ...(res.evidence ? { evidence: res.evidence } : {}),
+    };
   }
 
   async function retrieveModel<T>(
@@ -1426,7 +1524,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     id: string,
     data: Record<string, unknown> | undefined,
     options: ModelMutationOptions | undefined,
-    beforeSettlement?: (response: CommitResponse) => Promise<void>
+    beforeConfirmation?: (response: CommitResponse) => Promise<void>
   ): Promise<CommitReceipt> {
     assertWriteOptions(
       options && {
@@ -1434,6 +1532,10 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         readAt: options.readAt,
         onStale: options.onStale,
         claim: options.claim,
+        claimRef: options.claimRef,
+        fenceToken: options.fenceToken,
+        reads: options.reads,
+        track: options.track,
       },
       `${modelName} ${action}`
     );
@@ -1460,6 +1562,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
       onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
       readAt,
+      reads: options?.reads,
+      track: options?.track,
       // 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,
@@ -1480,7 +1584,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           // lower-level `commits.create` lifecycle surface.
           wait: 'confirmed',
         },
-        beforeSettlement
+        beforeConfirmation
       );
     } catch (error) {
       // The per-model write door (`ablo.<model>.update/create/delete`). Capture
@@ -1490,7 +1594,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     }
 
     // Same contract as `commits.create` above: a non-2xx already threw, so
-    // `body` is the success-only receipt union and its settlement status passes
+    // `body` is the success-only receipt union and its confirmation status passes
     // through verbatim rather than through a catch-all branch.
     return {
       id: body.serverTxId,
@@ -1773,7 +1877,14 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       if (!claimInput) return run(input);
 
       if (isClaimHandle(claimInput)) {
-        return run({ ...input, claimRef: { id: claimInput.id }, claim: undefined });
+        return run({
+          ...input,
+          claimRef: { id: claimInput.id },
+          ...(claimInput.fenceToken !== undefined
+            ? { fenceToken: claimInput.fenceToken }
+            : {}),
+          claim: undefined,
+        });
       }
 
       // `isClaimHandle` ruled out the handle form above; the generic mismatch
@@ -1806,14 +1917,14 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     function updateModel(
       id: string,
       updater: ModelUpdater<T>,
-      options?: ContentionOptions
+      options?: FunctionalUpdateOptions
     ): Promise<CommitReceipt | undefined>;
     function updateModel(
       arg:
         | (ModelMutationOptions & { readonly id: string; readonly data: Record<string, unknown> })
         | string,
       updater?: ModelUpdater<T>,
-      contention?: ContentionOptions
+      contention?: FunctionalUpdateOptions
     ): Promise<CommitReceipt | undefined> {
       // Functional form: update(id, current => next). The SDK owns the
       // read-fresh → compute → compare-and-swap → reconcile loop; correctness
@@ -1857,7 +1968,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       retrieve(params: ModelReadOptions & { readonly id: string }): Promise<HttpTransportRead<T>> {
         return retrieveModel<T>(name, params);
       },
-      list(options?: ServerReadOptions<T>): Promise<T[]> {
+      list(options?: ServerReadOptions<T>): ReturnType<typeof listModel<T>> {
         return listModel<T>(name, options);
       },
       async create(
@@ -1893,7 +2004,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
             }
           );
           if (created === undefined) {
-            throw new AbloConnectionError('Create settlement did not return its row.', {
+            throw new AbloConnectionError('Create confirmation did not return its row.', {
               code: 'commit_no_result',
             });
           }
@@ -1935,9 +2046,10 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
 
   return {
     ready,
+    get identity() { return effectiveAuthority; },
     waitForFlush: () =>
       runInHttpCommitLane(async () => {
-        await ready();
+        await prepare();
         const replayed = await replayHttpCommitOutbox();
         await confirmReplayedHttpCommits(replayed);
       }),

package/src/transport/wsFrameHandlers.ts

@@ -14,7 +14,11 @@ import {
   errorFromWire,
   type RequiredCapability,
 } from '../errors.js';
-import { commitAckSchema, commitReceiptSchema } from '../wire/commit.js';
+import {
+  commitAckSchema,
+  commitReceiptSchema,
+  type CommitReceiptWire,
+} from '../wire/commit.js';
 import { subscriptionAckPayloadSchema } from '../coordination/schema.js';
 import {
   WS_INBOUND_FRAMES,
@@ -35,9 +39,10 @@ import type { SocketObservability } from '../observability.js';
  * server, or rejected on timeout / disconnect.
  */
 export interface PendingCommit {
-  resolve: (value: CommitAck) => void;
+  resolve: (value: CommitAck | CommitReceiptWire) => void;
   reject: (err: Error) => void;
   timeout: ReturnType<typeof setTimeout>;
+  readonly returnReceipt?: boolean;
 }
 
 /**
@@ -202,11 +207,14 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
       });
     }
     pending.resolve(
-      commitAckSchema.parse({
+      pending.returnReceipt
+        ? receipt
+        : commitAckSchema.parse({
         status: receipt.status,
         ...(receipt.correlationId
           ? { correlationId: receipt.correlationId }
           : {}),
+        statusAt: receipt.statusAt,
         lastSyncId: receipt.lastSyncId,
         ...(receipt.notifications && receipt.notifications.length > 0
           ? { notifications: receipt.notifications }
@@ -214,7 +222,7 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
         ...(receipt.missingIds && receipt.missingIds.length > 0
           ? { missingIds: receipt.missingIds }
           : {}),
-      }),
+          }),
     );
   } else {
     // Capture the full server error so the caller can see what actually
@@ -233,6 +241,7 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
         code?: unknown;
         message?: unknown;
         request_id?: unknown;
+        event_id?: unknown;
         requiredCapability?: unknown;
         details?: unknown;
       };
@@ -261,6 +270,9 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
         !Array.isArray(obj.details)
           ? (obj.details as Readonly<Record<string, unknown>>)
           : undefined;
+      if (typeof obj.event_id === 'string') {
+        details = { ...(details ?? {}), event_id: obj.event_id };
+      }
     } else {
       errorMessage = 'mutation failed on server';
     }
@@ -341,7 +353,12 @@ const handleClaimAck: WsFrameHandler = (session, message) => {
     });
   } else {
     const err = error as
-      | { code?: unknown; message?: unknown }
+      | {
+          code?: unknown;
+          message?: unknown;
+          request_id?: unknown;
+          event_id?: unknown;
+        }
       | undefined;
     const code =
       err?.code && typeof err.code === 'string'
@@ -351,6 +368,11 @@ const handleClaimAck: WsFrameHandler = (session, message) => {
       err?.message && typeof err.message === 'string'
         ? err.message
         : 'claim rejected by server';
+    const requestId =
+      typeof err?.request_id === 'string' ? err.request_id : undefined;
+    const eventId =
+      typeof err?.event_id === 'string' ? err.event_id : undefined;
+    const details = eventId === undefined ? undefined : { event_id: eventId };
     // Capability denials get the typed CapabilityError so
     // callers can read `.requiredCapability` and attenuate-
     // and-retry the claim with a narrower token.
@@ -366,12 +388,23 @@ const handleClaimAck: WsFrameHandler = (session, message) => {
         typeof (rc as { scope?: unknown }).scope === 'string'
           ? (rc as RequiredCapability)
           : undefined;
-      pending.reject(new CapabilityError(code, msg, requiredCapability));
+      pending.reject(
+        new CapabilityError(code, msg, requiredCapability, {
+          ...(requestId !== undefined ? { requestId } : {}),
+          ...(details !== undefined ? { details } : {}),
+        }),
+      );
     } else {
       // Route through the shared factory so a failed claim_ack is a
       // typed AbloError (registry code → right subclass), symmetric
       // with the commit `mutation_result` path — never a bare Error.
-      pending.reject(errorFromWire(msg, { code }));
+      pending.reject(
+        errorFromWire(msg, {
+          code,
+          requestId,
+          details,
+        }),
+      );
     }
   }
 };
@@ -405,10 +438,15 @@ const handleSubscriptionAck: WsFrameHandler = (session, message) => {
     session.options.syncGroups = ack.syncGroups;
     pending.resolve({ syncGroups: ack.syncGroups });
   } else {
+    const eventId = ack.error?.event_id;
     pending.reject(
       errorFromWire(
         ack.error?.message ?? 'update_subscription rejected by server',
-        { code: ack.error?.code ?? 'malformed_subscription' },
+        {
+          code: ack.error?.code ?? 'malformed_subscription',
+          requestId: ack.error?.request_id,
+          ...(eventId !== undefined ? { details: { event_id: eventId } } : {}),
+        },
       ),
     );
   }

package/src/transport/wsTransport.ts

@@ -56,6 +56,7 @@ import {
   type AuthTokenGetter,
 } from '../auth/credentialSource.js';
 import { buildCommitFrame, type CommitAck, type CommitFrameOperation } from './commitFrames.js';
+import type { CommitReceiptWire } from '../wire/commit.js';
 import {
   dispatchWsFrame,
   readWsInboundFrame,
@@ -1040,7 +1041,47 @@ export class WsTransport<
           ),
         );
       }, timeoutMs);
-      this.pendingMutations.set(clientTxId, { resolve, reject, timeout });
+      this.pendingMutations.set(clientTxId, {
+        resolve: (value) => resolve(value as CommitAck),
+        reject,
+        timeout,
+      });
+      try {
+        const frame = buildCommitFrame(operations, clientTxId, reads, track);
+        this.ws!.send(JSON.stringify(frame));
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingMutations.delete(clientTxId);
+        reject(toAbloError(error));
+      }
+    });
+  }
+
+  /** @internal Exact wire receipt used to correlate a logical commit record. */
+  sendCommitReceipt(
+    operations: readonly CommitFrameOperation[],
+    clientTxId: string,
+    timeoutMs = 15_000,
+    reads?: readonly ReadDependency[] | null,
+    track?: readonly TrackDependency[] | null,
+  ): Promise<CommitReceiptWire> {
+    if (this.ws?.readyState !== WebSocket.OPEN) {
+      return Promise.reject(this.notConnectedError('commit'));
+    }
+    return new Promise<CommitReceiptWire>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingMutations.delete(clientTxId);
+        reject(new AbloConnectionError(
+          `commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`,
+          { code: 'commit_no_result' },
+        ));
+      }, timeoutMs);
+      this.pendingMutations.set(clientTxId, {
+        resolve: (value) => resolve(value as CommitReceiptWire),
+        reject,
+        timeout,
+        returnReceipt: true,
+      });
       try {
         const frame = buildCommitFrame(operations, clientTxId, reads, track);
         this.ws!.send(JSON.stringify(frame));

package/src/utils/json.ts

@@ -38,7 +38,7 @@ import type { JsonValue } from '../types/streams.js';
  * Traversal intentionally creates fresh objects and arrays instead of relying
  * on a framework-specific unwrapping API. That makes Proxy-wrapped plain data
  * (including MobX observables) safe for IndexedDB's structured-clone algorithm
- * while keeping the settlement core independent of any reactive framework.
+ * while keeping the confirmation core independent of any reactive framework.
  *
  * The accepted contract is deliberately narrower than `JSON.stringify`:
  * values that JSON would silently corrupt (`NaN` to `null`, `Map` to `{}`) or