@abloatai/transaction 0.60.0 → 0.61.0

package/src/transport/http/transport.ts

@@ -53,7 +53,6 @@ import {
   DEFAULT_CLAIM_TTL_MS,
   type ClaimHeartbeatReply,
   type ClaimListResponse,
-  type ClaimQueuedResponse,
   type ClaimRequest,
   type ClaimState,
   type ClaimTargetBody,
@@ -69,7 +68,7 @@ import {
   resolveHeartbeatPlan,
   startClaimHeartbeatLoop,
 } from '../../claims/heartbeat.js';
-import type { HttpClientConfig } from './options.js';
+import type { HttpTransport, HttpTransportOptions } from './contract.js';
 import type {
   ClaimedOptions,
   CommitCreateOptions,
@@ -90,7 +89,7 @@ import type {
 } from '../../client/resources/httpResources.js';
 import type { CredentialProviderResult } from '../../auth/credentialResult.js';
 import { credentialToken } from '../../auth/credentialResult.js';
-import { createSessionAccess, type SessionAccess } from '../../sessions/index.js';
+import { createSessionAccess } from '../../sessions/index.js';
 import { parseIdentityResolveResponse } from '../../auth/schemas.js';
 import type { EffectiveAuthority } from '../../auth/capability.js';
 
@@ -108,7 +107,6 @@ import type {
   ClaimReorderParams,
   ModelCreateManyParams,
   ServerReadOptions,
-  ResolvedClaimContentionOptions,
   ClaimQueueView,
 } from '../../client/resources/modelOperations.js';
 import {
@@ -119,12 +117,6 @@ import {
 } from '../../client/resources/modelOperations.js';
 import type { Duration } from '../../utils/duration.js';
 import { claimDescription, partName } from '../../coordination/schema.js';
-import type {
-  ClaimAcquired,
-  ClaimBeginPayload,
-  ClaimGranted,
-  ClaimQueued,
-} from '../../coordination/schema.js';
 import type { BatchFence } from '../../claims/locator.js';
 import {
   subTarget,
@@ -141,7 +133,6 @@ import type {
   HeldClaim,
   HeldLease,
 } from '../../types/streams.js';
-import type { CoordinationObservability } from '../../observability.js';
 import {
   assertWriteOptions,
   assertWriteTarget,
@@ -169,86 +160,14 @@ import {
   type ExactHttpCommitRequest,
 } from '../../commit/httpRequest.js';
 import { resolveDurableWrites } from '../../commit/durableWrites.js';
-import { createHttpReadOnChange, type HttpReadOnChange } from './subscription.js';
+import { createHttpReadOnChange } from './subscription.js';
+import { awaitClaimGrantOverHttp } from './claimWait.js';
 import type { CommitFrameOperation } from '../websocket/commitFrames.js';
 
-/** @internal Private options for the schema-agnostic HTTP protocol transport. */
-export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
-  readonly bootstrapBaseUrl?: string | undefined;
-  /**
-   * The observability provider forwarded from `Ablo({ observability })`. The HTTP
-   * transport emits the same claim and conflict events as the WebSocket transport,
-   * so a `ClaimLog` works identically for headless server-agent evaluations.
-   */
-  readonly observability?: CoordinationObservability;
-  /**
-   * Per-request deadline in milliseconds for the stateless HTTP transport.
-   * Every request this client issues is aborted after this long and surfaces
-   * as a retryable connection error — without it a black-holed server hangs
-   * a headless agent forever (browsers never time fetch out on their own).
-   * Pass `0` to disable the deadline.
-   *
-   * @default 30_000
-   */
-  readonly timeoutMs?: number;
-  /** @internal Routes writes through the selected duplex transport. */
-  readonly dispatchCommit?: ((input: {
-    readonly clientTxId: string;
-    readonly operations: readonly CommitFrameOperation[];
-    readonly reads?: readonly import('../../coordination/schema.js').ReadDependency[] | null;
-  }) => Promise<CommitReceiptWire>) | undefined;
-  /** @internal Routes held-claim acquisition through the shared socket. */
-  readonly dispatchClaim?: ((input: ClaimBeginPayload & {
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-    readonly onQueued?: (event: ClaimQueued) => Error | undefined;
-  }) => Promise<ClaimAcquired | ClaimGranted>) | undefined;
-  /** @internal Releases a socket-acquired claim on that same session. */
-  readonly releaseDispatchedClaim?: ((input: {
-    readonly claimId: string;
-    readonly entityType: string;
-    readonly entityId: string;
-  }) => void) | undefined;
-};
-
 /** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const HTTP_CONFIRMATION_POLL_INTERVAL_MS = 250;
-
-/** @internal Private protocol surface wrapped by `AbloHttpClient`. */
-export interface HttpTransport {
-  ready(): Promise<void>;
-  waitForFlush(): Promise<void>;
-  /** Drains scheduled commits and active requests. */
-  dispose(): Promise<void>;
-  purge(): Promise<void>;
-  /** @internal Live check used only by `context().onChange`. */
-  readonly onChange: HttpReadOnChange;
-  readonly commits: CommitResource;
-  /**
-   * Claim-ticket operations keyed by `claimId` — the id a queued acquire
-   * hands back on `AbloClaimedError('claim_queued')`. See
-   * {@link HttpClaimsResource}.
-   */
-  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>;
-  /**
-   * Resolve the active bearer credential this client authenticates with — the
-   * same token its own requests carry in `Authorization`. Returns `null` when
-   * no credential is configured. Async because the API key may be supplied as
-   * an async setter. Use it to authenticate a side-band request to the same
-   * server with the credential this client already holds — no re-mint.
-   */
-  getAuthToken(): Promise<string | null>;
-  /** @internal One normalized source shared by HTTP bootstrap and live transport. */
-  readonly access: SessionAccess;
-}
-
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
 type CommitResponse = CommitReceiptWire;
 
 /** @internal Constructed only by the typed HTTP facade. */
@@ -1169,118 +1088,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     },
   };
 
-  // How the stateless client waits its turn. The queued slot is real server
-  // state, so one heartbeat per tick does both jobs: it refreshes this
-  // waiter's slot and reports the line's answer — `queued` (still waiting) or
-  // `held` (granted). The first check comes quickly because most holds are a
-  // short claim→write→release; after that the cadence relaxes, with jitter so
-  // a fleet of waiters doesn't beat in step.
-  const GRANT_POLL_FIRST_MS = 250;
-  const GRANT_POLL_INTERVAL_MS = 1_000;
-  // An abort cuts the sleep short so the wait ends within a tick of the
-  // signal, not at the next scheduled beat.
-  const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
-    new Promise((resolve) => {
-      const done = (): void => {
-        clearTimeout(timer);
-        signal?.removeEventListener('abort', done);
-        resolve();
-      };
-      const timer = setTimeout(done, ms);
-      signal?.addEventListener('abort', done, { once: true });
-    });
-
-  async function awaitGrantOverHttp(
-    targetLabel: string,
-    queued: ClaimQueuedResponse,
-    options: ResolvedClaimContentionOptions,
-  ): Promise<{ id: string; fenceToken?: number }> {
-    // The queued reply is a claim resource in its waiting state, so the
-    // handle is its `id` — same rule as the 201 and the poll.
-    const claimId = queued.id;
-    const { signal } = options;
-    // Leave the line before rejecting: an abandoned slot would otherwise sit
-    // in the queue until its TTL lapses, stalling every waiter behind it.
-    const rejectAndLeave = async (error: AbloClaimedError): Promise<never> => {
-      await claims.release({ claimId }).catch(() => {});
-      throw error;
-    };
-
-    emitClaimStatus(options.onStatus, {
-      type: 'queued',
-      claimId,
-      position: queued.position,
-      ahead: queued.position + 1,
-    });
-
-    if (options.maxDepth !== undefined && queued.position >= options.maxDepth) {
-      return rejectAndLeave(
-        new AbloClaimedError(
-          `Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxDepth}).`,
-          { code: 'queue_too_deep' }
-        )
-      );
-    }
-
-    const deadline =
-      options.timeoutMs !== undefined ? Date.now() + options.timeoutMs : undefined;
-    let delay = GRANT_POLL_FIRST_MS;
-    for (;;) {
-      if (signal?.aborted) {
-        return rejectAndLeave(
-          new AbloClaimedError(
-            `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
-            { code: 'claim_wait_aborted' }
-          )
-        );
-      }
-      if (deadline !== undefined && Date.now() >= deadline) {
-        return rejectAndLeave(
-          new AbloClaimedError(
-            `Timed out after ${options.timeoutMs}ms waiting for the queue grant on ${targetLabel}.`,
-            { code: 'grant_timeout' }
-          )
-        );
-      }
-      await sleep(
-        deadline !== undefined ? Math.min(delay, Math.max(0, deadline - Date.now())) : delay,
-        signal
-      );
-      if (signal?.aborted) {
-        return rejectAndLeave(
-          new AbloClaimedError(
-            `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
-            { code: 'claim_wait_aborted' }
-          )
-        );
-      }
-      delay = GRANT_POLL_INTERVAL_MS * (0.85 + Math.random() * 0.3);
-      // A lease that ended answers the beat with 409 `claim_lost`, which the
-      // wire error mapping raises as AbloClaimedError before this reads
-      // anything — the wait fails with the loss, as the socket wait does.
-      const beat = await claims.heartbeat({ claimId });
-      if (beat.status !== 'held') continue;
-      // Granted. The heartbeat ack does not carry the fence token — the claim
-      // state does, server-stamped at grant.
-      const state = await claims.retrieve({ claimId });
-      if (state.status !== 'active') {
-        return rejectAndLeave(
-          new AbloClaimedError(`Claim lost while queued for ${targetLabel}.`, {
-            code: 'claim_lost',
-          })
-        );
-      }
-      emitClaimStatus(options.onStatus, {
-        type: 'granted',
-        claimId,
-        waited: true,
-      });
-      return state.fenceToken !== undefined
-        ? { id: claimId, fenceToken: state.fenceToken }
-        : { id: claimId };
-    }
-  }
-
   async function applyClaimedPolicy(
     target: Partial<ModelTarget>,
     options?: ClaimedOptions,
@@ -1734,7 +1541,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // the manual ticket surface.)
       if (body.status === 'queued') {
         try {
-          return await awaitGrantOverHttp(
+          return await awaitClaimGrantOverHttp(
+            claims,
             `${name}/${params.id}`,
             body,
             contention,
@@ -1767,8 +1575,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     ): Promise<void> => {
       const entityId = isClaimHandle(params) ? params.target.id : params.id;
       if (claimId && options.releaseDispatchedClaim) {
-        options.releaseDispatchedClaim({ claimId, entityType: name, entityId });
-        return Promise.resolve();
+        return options.releaseDispatchedClaim({ claimId, entityType: name, entityId });
       }
       return requestRaw(claimPath(entityId), {
         method: 'DELETE',
@@ -1896,7 +1703,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         description: claimDescription(params),
         release,
         revoke: () => {
-          void release().catch(() => {});
+          void release().catch(ignoreBestEffortClaimReleaseFailure);
         },
         heartbeat,
         [Symbol.asyncDispose]: release,
@@ -1911,7 +1718,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // this credential until the TTL lapses, behind no handle anyone can
       // release, and every other participant is refused for the duration.
       if (data === undefined) {
-        await release().catch(() => undefined);
+        await release().catch(ignoreBestEffortClaimReleaseFailure);
         throw new AbloNotFoundError(
           `Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope). ` +
             `To hold a key before its row exists, claim it by id alone: claim('${params.id}') returns a lease without a snapshot.`,
@@ -2018,7 +1825,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           claim: undefined,
         });
       } finally {
-        await releaseClaim({ id }, claimId).catch(() => {});
+        await releaseClaim({ id }, claimId).catch(ignoreBestEffortClaimReleaseFailure);
       }
     };
 

package/src/transport/websocket/frameHandlers.ts

@@ -425,6 +425,13 @@ const validatedFrameHandlers: Record<
       session.emit('claim_acquired', payload);
     },
   ),
+  claim_abandon_ack: validating(
+    WS_INBOUND_FRAMES.claim_abandon_ack.payload,
+    'claim_abandon_ack',
+    (session, payload) => {
+      session.emit('claim_abandon_ack', payload);
+    },
+  ),
   claim_queued: validating(
     WS_INBOUND_FRAMES.claim_queued.payload,
     'claim_queued',

package/src/transport/websocket/session.ts

@@ -2,9 +2,9 @@ import {
   AbloClaimedError,
   AbloConnectionError,
   AbloSessionError,
-  errorFromWire,
   isAccessCredentialExpiryCloseReason,
 } from '../../errors.js';
+import { claimAdmissionError } from '../../claims/admission.js';
 import { classifyCredentialKind } from '../../auth/credentialKind.js';
 import {
   credentialToken,
@@ -38,6 +38,10 @@ interface StoredPosition {
 }
 
 const MAX_BUFFERED_OBSERVATION_DELTAS = 1_024;
+const ignoreObservedAcknowledgeFailure = (): undefined => undefined;
+// Preserve the originating claim wait error when best-effort queue cleanup
+// fails for the same disconnected transport.
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
 
 function parsePosition(value: string | null): StoredPosition {
   if (!value) return { lastSyncId: 0, cursor: null };
@@ -206,7 +210,15 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
       return;
     }
     this.pendingSessionError = error;
-    void this.credentialLifecycle.recoverFromAuthRejection('access_credential_expiry');
+    void this.credentialLifecycle
+      .recoverFromAuthRejection('access_credential_expiry')
+      .catch((recoveryError: unknown) => {
+        this.failTerminal(
+          recoveryError instanceof Error
+            ? recoveryError
+            : new AbloConnectionError('The WebSocket credential recovery failed.'),
+        );
+      });
   }
 
   private failTerminal(error: Error): void {
@@ -284,14 +296,27 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
 
   async claim(input: WebSocketClaimInput) {
     await this.ready();
-    const timeoutMs = input.timeoutMs ?? 15_000;
     return new Promise<import('../../coordination/schema.js').ClaimAcquired | import('../../coordination/schema.js').ClaimGranted>((resolve, reject) => {
       const cleanups: (() => void)[] = [];
+      let finished = false;
       const finish = (outcome: () => void): void => {
-        clearTimeout(timeout);
+        if (finished) return;
+        finished = true;
+        if (timeout) clearTimeout(timeout);
         for (const cleanup of cleanups) cleanup();
         outcome();
       };
+      const abandonAndReject = (error: Error): void => {
+        if (finished) return;
+        finished = true;
+        if (timeout) clearTimeout(timeout);
+        for (const cleanup of cleanups) cleanup();
+        void this.release({
+          claimId: input.claimId,
+          entityType: input.entityType,
+          entityId: input.entityId,
+        }).catch(ignoreBestEffortClaimReleaseFailure).then(() => reject(error));
+      };
       const matches = (event: { claimId: string }): boolean => event.claimId === input.claimId;
       cleanups.push(this.socket.subscribe('claim_acquired', (event) => {
         if (matches(event)) finish(() => resolve(event));
@@ -303,27 +328,12 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
         if (!matches(event)) return;
         const refusal = input.onQueued?.(event);
         if (refusal) {
-          this.release({
-            claimId: input.claimId,
-            entityType: input.entityType,
-            entityId: input.entityId,
-          });
-          finish(() => reject(refusal));
+          abandonAndReject(refusal);
         }
       }));
       cleanups.push(this.socket.subscribe('claim_rejected', (event) => {
         if (!matches(event)) return;
-        finish(() => reject(errorFromWire(
-          event.message ?? `Claim ${event.claimId} was rejected.`,
-          {
-            code: event.reason === 'conflict' ? 'claim_conflict' : 'claim_rejected',
-            details: {
-              ...(event.target ? { target: event.target } : {}),
-              ...(event.heldBy ? { heldBy: event.heldBy } : {}),
-              ...(event.heldByClaimId ? { heldByClaimId: event.heldByClaimId } : {}),
-            },
-          },
-        )));
+        finish(() => reject(claimAdmissionError(event)));
       }));
       cleanups.push(this.socket.subscribe('disconnected', () => {
         finish(() => reject(new AbloConnectionError(
@@ -331,29 +341,21 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
         )));
       }));
       const abort = (): void => {
-        this.release({
-          claimId: input.claimId,
-          entityType: input.entityType,
-          entityId: input.entityId,
-        });
-        finish(() => reject(new AbloClaimedError(
+        abandonAndReject(new AbloClaimedError(
           `The wait for claim ${input.claimId} was aborted.`,
           { code: 'claim_wait_aborted' },
-        )));
+        ));
       };
       input.signal?.addEventListener('abort', abort, { once: true });
       cleanups.push(() => input.signal?.removeEventListener('abort', abort));
-      const timeout = setTimeout(() => {
-        this.release({
-          claimId: input.claimId,
-          entityType: input.entityType,
-          entityId: input.entityId,
-        });
-        finish(() => reject(new AbloClaimedError(
-          `claim timed out after ${timeoutMs}ms (claimId=${input.claimId})`,
-          { code: 'grant_timeout' },
-        )));
-      }, timeoutMs);
+      const timeout = input.timeoutMs !== undefined
+        ? setTimeout(() => {
+            abandonAndReject(new AbloClaimedError(
+              `claim timed out after ${input.timeoutMs}ms (claimId=${input.claimId})`,
+              { code: 'grant_timeout' },
+            ));
+          }, input.timeoutMs)
+        : undefined;
       if (input.signal?.aborted) {
         abort();
         return;
@@ -368,8 +370,40 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     });
   }
 
-  release(input: { claimId: string; entityType?: string; entityId?: string }): void {
-    this.socket.send({ type: 'claim_abandon', payload: input });
+  async release(input: {
+    claimId: string;
+    entityType?: string;
+    entityId?: string;
+  }): Promise<void> {
+    await this.ready();
+    const requestId = crypto.randomUUID();
+    await new Promise<void>((resolve, reject) => {
+      const finish = (outcome: () => void): void => {
+        clearTimeout(timeout);
+        offAck();
+        offDisconnect();
+        outcome();
+      };
+      const offAck = this.socket.subscribe('claim_abandon_ack', (event) => {
+        if (event.requestId !== requestId || event.claimId !== input.claimId) return;
+        finish(resolve);
+      });
+      const offDisconnect = this.socket.subscribe('disconnected', () => {
+        finish(() => reject(new AbloConnectionError(
+          `WebSocket closed before claim ${input.claimId} release was confirmed.`,
+        )));
+      });
+      const timeout = setTimeout(() => {
+        finish(() => reject(new AbloConnectionError(
+          `Timed out waiting for claim ${input.claimId} release confirmation.`,
+          { code: 'claim_lease_unavailable' },
+        )));
+      }, 15_000);
+      this.socket.send({
+        type: 'claim_abandon',
+        payload: { ...input, requestId },
+      });
+    });
   }
 
   subscribe<K extends keyof SyncWebSocketEventMap<TEvents>>(
@@ -456,13 +490,13 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
   }
 
   async acknowledge(lastSyncId: number): Promise<void> {
-    const attempt = this.acknowledgeLane.catch(() => undefined).then(async () => {
+    const attempt = this.acknowledgeLane.catch(ignoreObservedAcknowledgeFailure).then(async () => {
       const position = this.socket.positionAfter(lastSyncId);
       await this.options.cursorStore?.save(this.cursorKey, JSON.stringify(position));
       this.socket.markDurable(position);
       this.socket.acknowledge(position.lastSyncId);
     });
-    this.acknowledgeLane = attempt.catch(() => undefined);
+    this.acknowledgeLane = attempt.catch(ignoreObservedAcknowledgeFailure);
     await attempt;
   }
 

package/src/transport/websocket/sessionContract.ts

@@ -87,7 +87,7 @@ export interface AbloWebSocketSession<
     readonly claimId: string;
     readonly entityType?: string;
     readonly entityId?: string;
-  }): void;
+  }): Promise<void>;
   subscribe<K extends keyof SyncWebSocketEventMap<TEvents>>(
     event: K,
     listener: (...args: SyncWebSocketEventMap<TEvents>[K]) => void,

package/src/transport/websocket/transport.ts

@@ -31,6 +31,7 @@ import type { BootstrapReason } from '../../wire/bootstrapReason.js';
 import type { ClientSyncDelta } from '../../observation/contract.js';
 import type {
   ClaimAcquired,
+  ClaimAbandonAckPayload,
   PresenceUpdate,
   ClaimGranted,
   ClaimHeartbeatAckPayload,
@@ -228,6 +229,7 @@ export interface CoreSyncEventMap {
    */
   claim_queue: [ClaimQueue];
   claim_acquired: [ClaimAcquired];
+  claim_abandon_ack: [ClaimAbandonAckPayload];
   claim_queued: [ClaimQueued];
   claim_granted: [ClaimGranted];
   claim_lost: [ClaimLost];

package/src/wire/inboundFrames.ts

@@ -28,6 +28,7 @@ import { commitReceiptSchema } from '../commit/contract.js';
 import { clientSyncDeltaSchema } from '../observation/contract.js';
 import {
   claimAcquiredSchema,
+  claimAbandonAckPayloadSchema,
   claimGrantedSchema,
   claimHeartbeatAckPayloadSchema,
   claimLostSchema,
@@ -123,6 +124,10 @@ export const WS_INBOUND_FRAMES = {
   presence_update: { validation: 'schema', payload: presenceUpdateSchema },
   claim_rejected: { validation: 'schema', payload: claimRejectionSchema },
   claim_acquired: { validation: 'schema', payload: claimAcquiredSchema },
+  claim_abandon_ack: {
+    validation: 'schema',
+    payload: claimAbandonAckPayloadSchema,
+  },
   claim_queued: { validation: 'schema', payload: claimQueuedSchema },
   claim_granted: { validation: 'schema', payload: claimGrantedSchema },
   claim_lost: { validation: 'schema', payload: claimLostSchema },