@abloatai/transaction 0.59.2 → 0.61.0

package/src/transport/websocket/session.ts

@@ -2,8 +2,15 @@ import {
   AbloClaimedError,
   AbloConnectionError,
   AbloSessionError,
-  errorFromWire,
+  isAccessCredentialExpiryCloseReason,
 } from '../../errors.js';
+import { claimAdmissionError } from '../../claims/admission.js';
+import { classifyCredentialKind } from '../../auth/credentialKind.js';
+import {
+  credentialToken,
+  type CredentialProviderResult,
+} from '../../auth/credentialResult.js';
+import { CredentialLifecycle } from '../../sessions/lifecycle.js';
 import {
   clientSyncDeltaSchema,
   type ClientSyncDelta,
@@ -21,7 +28,6 @@ import type {
   WebSocketObserveOptions,
   WebSocketObservedDelta,
   WebSocketPresence,
-  WebSocketJoinInput,
   WebSocketSessionOptions,
   OpenCollaborationEvents,
 } from './sessionContract.js';
@@ -32,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 };
@@ -125,17 +135,29 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
   private closed = false;
   private currentToken: string;
   private acknowledgeLane: Promise<void> = Promise.resolve();
+  private terminalError: Error | null = null;
+  private readonly terminalListeners = new Set<(error: Error) => void>();
+  private readonly credentialLifecycle: CredentialLifecycle | null;
+  private pendingSessionError: Error | null = null;
 
   readonly presence: WebSocketPresence;
   readonly collaboration: WebSocketCollaboration<TEvents>;
 
-  constructor(options: WebSocketSessionOptions, position: StoredPosition, token: string) {
+  constructor(
+    options: WebSocketSessionOptions,
+    position: StoredPosition,
+    credential: CredentialProviderResult,
+  ) {
     this.options = options;
+    const token = credentialToken(credential);
+    if (!token) {
+      throw new AbloSessionError('The WebSocket transport requires an authenticated credential.');
+    }
     this.currentToken = token;
     this.cursorKey = options.cursorKey ?? 'websocket';
     this.socket = new AgentWebSocket<TEvents>({
       baseUrl: options.baseUrl,
-      kind: 'agent',
+      kind: classifyCredentialKind(token) === 'ephemeral' ? 'user' : 'agent',
       getAuthToken: () => this.currentToken,
       syncGroups: [...(options.syncGroups ?? [])],
       collaborationEvents: [...(options.collaborationEvents ?? [])],
@@ -148,23 +170,73 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     this.collaboration = {
       send: (event, payload) => this.socket.sendCollaborationEvent(event, payload),
     } as WebSocketCollaboration<TEvents>;
-    this.socket.subscribe('session_error', () => {
-      void this.refreshExpiredCredential();
+    this.socket.subscribe('session_error', (error) => {
+      this.handleSessionError(error);
     });
+    this.credentialLifecycle = options.access.renewable
+      ? new CredentialLifecycle({
+        setAuthToken: (freshToken) => {
+          this.currentToken = freshToken;
+        },
+        nudgeReconnect: () => {
+          if (this.closed || this.terminalError) return;
+          this.socket.clearSessionError();
+          this.socket.resetReconnectAttempts();
+          this.socket.connect();
+        },
+        reportSessionExpired: () => {
+          this.failTerminal(this.pendingSessionError ?? new AbloSessionError(
+            'The application session ended while renewing its Ablo session.',
+          ));
+        },
+      })
+      : null;
+    if (this.credentialLifecycle) {
+      this.credentialLifecycle.start(() => this.loadCredential(), { proactiveInNode: true });
+      this.credentialLifecycle.accept(credential);
+    }
   }
 
-  private async refreshExpiredCredential(): Promise<void> {
-    if (this.closed) return;
-    try {
-      const next = await this.options.getAuthToken();
-      if (!next || next === this.currentToken) return;
-      this.currentToken = next;
-      this.socket.clearSessionError();
-      this.socket.connect();
-    } catch {
-      // The terminal session_error remains the public signal. A later explicit
-      // ready() call can retry after the caller repairs its credential source.
+  private async loadCredential(): Promise<CredentialProviderResult> {
+    return this.options.access.credential();
+  }
+
+  private handleSessionError(error: Error): void {
+    if (
+      !this.credentialLifecycle
+      || !isAccessCredentialExpiryCloseReason(error.message)
+    ) {
+      this.failTerminal(error);
+      return;
     }
+    this.pendingSessionError = error;
+    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 {
+    if (this.terminalError || this.closed) return;
+    this.terminalError = error;
+    this.socket.setSessionErrorDetected();
+    this.socket.disconnect();
+    for (const listener of this.terminalListeners) listener(error);
+  }
+
+  private onTerminal(listener: (error: Error) => void): () => void {
+    if (this.terminalError) {
+      const error = this.terminalError;
+      queueMicrotask(() => listener(error));
+      return () => undefined;
+    }
+    this.terminalListeners.add(listener);
+    return () => this.terminalListeners.delete(listener);
   }
 
   get connected(): boolean {
@@ -175,6 +247,7 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     if (this.closed) {
       return Promise.reject(new AbloConnectionError('The WebSocket session is closed.'));
     }
+    if (this.terminalError) return Promise.reject(this.terminalError);
     if (this.socket.isConnected()) return Promise.resolve();
     if (this.readyPromise) return this.readyPromise;
     this.readyPromise = new Promise<void>((resolve, reject) => {
@@ -190,7 +263,7 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
         cleanup();
         resolve();
       });
-      const failed = this.socket.subscribe('session_error', (error) => {
+      const failed = this.onTerminal((error) => {
         rejectConnection(error);
       });
       const mismatch = this.socket.subscribe('protocol_mismatch', () => {
@@ -223,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));
@@ -242,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(
@@ -270,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;
@@ -307,23 +370,42 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
     });
   }
 
-  release(input: { claimId: string; entityType?: string; entityId?: string }): void {
-    this.socket.send({ type: 'claim_abandon', payload: input });
-  }
-
-  async join(input: WebSocketJoinInput) {
+  async release(input: {
+    claimId: string;
+    entityType?: string;
+    entityId?: string;
+  }): Promise<void> {
     await this.ready();
-    return this.socket.sendClaim(input.claimId, input.syncGroups, {
-      capabilityToken: input.capabilityToken,
-      ttlSeconds: input.ttlSeconds,
-      timeoutMs: input.timeoutMs,
+    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 },
+      });
     });
   }
 
-  leave(claimId: string): void {
-    this.socket.sendRelease(claimId);
-  }
-
   subscribe<K extends keyof SyncWebSocketEventMap<TEvents>>(
     event: K,
     listener: (...args: SyncWebSocketEventMap<TEvents>[K]) => void,
@@ -357,7 +439,7 @@ class WebSocketSession<TEvents extends EventMap<TEvents>>
       wake?.();
       wake = undefined;
     });
-    const offError = this.socket.subscribe('session_error', (error) => {
+    const offError = this.onTerminal((error) => {
       failure = error;
       wake?.();
       wake = undefined;
@@ -408,19 +490,21 @@ 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;
   }
 
   async close(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
+    this.credentialLifecycle?.stop();
+    this.terminalListeners.clear();
     this.rejectReady?.(new AbloConnectionError('The WebSocket session was disposed.'));
     await this.acknowledgeLane;
     this.socket.disconnect();
@@ -439,11 +523,16 @@ export async function createWebSocketSession<
 ): Promise<AbloWebSocketSession<TEvents>> {
   const cursorKey = options.cursorKey ?? 'websocket';
   const stored = await options.cursorStore?.load(cursorKey) ?? null;
-  const token = await options.getAuthToken();
+  const credential = await options.access.credential();
+  const token = credentialToken(credential);
   if (!token) {
     throw new AbloSessionError('The WebSocket transport requires an authenticated credential.');
   }
-  const session = new WebSocketSession<TEvents>(options, parsePosition(stored), token);
+  const session = new WebSocketSession<TEvents>(
+    options,
+    parsePosition(stored),
+    credential,
+  );
   let rejectOpening: ((error: Error) => void) | undefined;
   const aborted = new Promise<never>((_resolve, reject) => {
     rejectOpening = reject;

package/src/transport/websocket/sessionContract.ts

@@ -8,6 +8,7 @@ import type {
 } from '../../coordination/schema.js';
 import type { ClientSyncDelta } from '../../observation/contract.js';
 import type { ObserveCursorStore } from '../../client/contract.js';
+import type { SessionAccess } from '../../sessions/source.js';
 import type { CommitFrameOperation } from '../websocket/commitFrames.js';
 import type {
   CoreSyncEventMap,
@@ -18,7 +19,8 @@ import type {
 
 export interface WebSocketSessionOptions {
   readonly baseUrl?: string;
-  readonly getAuthToken: () => string | undefined | Promise<string | undefined>;
+  /** Normalized once at the client boundary; transports do not infer policy. */
+  readonly access: SessionAccess;
   readonly syncGroups?: readonly string[];
   readonly collaborationEvents?: readonly string[];
   readonly cursorKey?: string;
@@ -44,15 +46,6 @@ export interface WebSocketObserveOptions {
   readonly signal?: AbortSignal;
 }
 
-/** A multiplexed participant-scope registration on the shared socket. */
-export interface WebSocketJoinInput {
-  readonly claimId: string;
-  readonly syncGroups: readonly string[];
-  readonly capabilityToken?: string;
-  readonly ttlSeconds?: number;
-  readonly timeoutMs?: number;
-}
-
 /** A durable row/field claim carried over the same live protocol. */
 export type WebSocketClaimInput = ClaimBeginPayload & {
   readonly timeoutMs?: number;
@@ -94,9 +87,7 @@ export interface AbloWebSocketSession<
     readonly claimId: string;
     readonly entityType?: string;
     readonly entityId?: string;
-  }): void;
-  join(input: WebSocketJoinInput): Promise<{ syncGroups: string[]; ttlSeconds?: number }>;
-  leave(claimId: string): void;
+  }): Promise<void>;
   subscribe<K extends keyof SyncWebSocketEventMap<TEvents>>(
     event: K,
     listener: (...args: SyncWebSocketEventMap<TEvents>[K]) => void,

package/src/transport/websocket/transport.ts

@@ -22,28 +22,23 @@ import { EventEmitter } from 'events';
 import type { ParticipantKind } from '../../types/participant.js';
 import {
   AbloConnectionError,
-  AbloError,
   AbloSessionError,
   AbloValidationError,
   toAbloError,
 } from '../../errors.js';
-import {
-  participantClaimPayloadSchema,
-  updateSubscriptionPayloadSchema,
-} from '../../coordination/schema.js';
+import { updateSubscriptionPayloadSchema } from '../../coordination/schema.js';
 import type { BootstrapReason } from '../../wire/bootstrapReason.js';
 import type { ClientSyncDelta } from '../../observation/contract.js';
 import type {
   ClaimAcquired,
+  ClaimAbandonAckPayload,
   PresenceUpdate,
-  ClaimExpired,
   ClaimGranted,
   ClaimHeartbeatAckPayload,
   ClaimLost,
   ClaimQueue,
   ClaimQueued,
   ClaimRejection,
-  ParticipantClaimPayload,
   ReadDependency,
   WireClaim,
 } from '../../coordination/schema.js';
@@ -60,7 +55,6 @@ import {
   readWsInboundFrame,
   type WsSession,
   type PendingCommit,
-  type PendingClaim,
   type PendingSubscription,
 } from './frameHandlers.js';
 import { HeartbeatController } from './heartbeat.js';
@@ -213,14 +207,6 @@ export interface CoreSyncEventMap {
    */
   handshake_failed: [CloseEvent];
   reconnect_failed: [{ attempts: number }];
-  /**
-   * Server-initiated notification that a previously-active claim's
-   * TTL has expired. Consumers (e.g., the participant SDK) re-mint
-   * a fresh capability and re-claim, OR accept the drop. The claim
-   * is already inactive on the server side by the time this fires —
-   * no client-side action needed unless re-claiming.
-   */
-  claim_expired: [ClaimExpired];
   /**
    * Server rejected an `claim_begin` because another participant
    * already holds an open claim on the same target (cooperative
@@ -243,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];
@@ -370,6 +357,10 @@ export class WsTransport<
    *  server rejected the upgrade" since browsers hide the HTTP status (e.g.
    *  401) behind the opaque 1006 close code. */
   private _everOpened = false;
+  /** True after any socket in this logical transport has opened. Unlike
+   * `_everOpened`, this survives socket replacement so a failed reconnect
+   * handshake is retried instead of being mistaken for a failed first login. */
+  private _hasConnected = false;
   /**
    * Diagnostic snapshot of the last connection lifecycle. Persisted across
    * the lifetime of the transport so that any subsequent "not connected"
@@ -405,14 +396,6 @@ export class WsTransport<
    */
   private pendingMutations = new Map<string, PendingCommit>();
 
-  /**
-   * In-flight `claim` requests keyed by claimId. Resolved when the matching
-   * `claim_ack` arrives, or rejected on timeout or disconnect — the same
-   * request/response pattern as `pendingMutations`, multiplexed over the one
-   * connection.
-   */
-  private pendingClaims = new Map<string, PendingClaim>();
-
   /**
    * In-flight `update_subscription` frames awaiting `subscription_ack`.
    * A FIFO queue rather than a keyed Map because the wire ack carries no
@@ -483,7 +466,6 @@ export class WsTransport<
       logger: this.logger,
       observability: this.observability,
       pendingMutations: this.pendingMutations,
-      pendingClaims: this.pendingClaims,
       shiftPendingSubscription: () => this.pendingSubscriptions.shift(),
       options: this.options,
       collaborationEventTypes: this.collaborationEventTypes,
@@ -731,6 +713,7 @@ export class WsTransport<
       this.isConnecting = false;
       this.reconnectAttempts = 0;
       this._everOpened = true;
+      this._hasConnected = true;
       this.lastOpenAt = Date.now();
       this.emit('connected');
 
@@ -861,22 +844,6 @@ export class WsTransport<
         this.pendingMutations.clear();
       }
 
-      // Cancel in-flight claims — same rationale. Server-side
-      // claims are bound to the connection; a reconnect will need
-      // to re-claim. Higher-level retry belongs to whoever holds
-      // the participant handle (typically the SDK's claim manager).
-      if (this.pendingClaims.size > 0) {
-        for (const pending of this.pendingClaims.values()) {
-          clearTimeout(pending.timeout);
-          pending.reject(
-            new AbloConnectionError(
-              `WebSocket closed while claim was in flight (code=${event.code})`,
-            ),
-          );
-        }
-        this.pendingClaims.clear();
-      }
-
       // Cancel in-flight subscription updates — the reconnect handshake
       // re-sends `options.syncGroups` (the last acked interest) in the
       // upgrade URL, so a pending change that never acked is simply
@@ -946,7 +913,7 @@ export class WsTransport<
       // from a transient network issue and transition the UI accordingly.
       // Reconnecting blindly is what produced the infinite
       // "offline → reconnecting → offline" loop on stale cookies.
-      if (!everOpened && !this.isManualClose) {
+      if (!everOpened && !this._hasConnected && !this.isManualClose) {
         this.observability.captureWebSocketError({
           context: 'handshake-failed-close',
           code: event.code,
@@ -1172,100 +1139,6 @@ export class WsTransport<
     this.ws.send(JSON.stringify(frame));
   }
 
-  /**
-   * Activates a participant claim on this connection. One connection can hold
-   * several concurrent claims at once, each scoped to a different set of sync
-   * groups, so the SDK reuses the existing connection instead of opening a
-   * separate socket per scope.
-   *
-   * Returns a promise that resolves with the server-canonicalized `syncGroups`
-   * and effective `ttlSeconds` once `claim_ack` arrives, or rejects with a typed
-   * error on a failed ack, a timeout, or a disconnect.
-   */
-  sendClaim(
-    claimId: string,
-    syncGroups: readonly string[],
-    options?: Pick<ParticipantClaimPayload, 'capabilityToken' | 'ttlSeconds'> & {
-      timeoutMs?: number;
-    },
-  ): Promise<{ syncGroups: string[]; ttlSeconds?: number }> {
-    if (this.ws?.readyState !== WebSocket.OPEN) {
-      return Promise.reject(this.notConnectedError('claim'));
-    }
-    // Checked against the schema the server ingests it with, for the same
-    // reason `updateSubscription` below is: the two frames name their scopes
-    // identically, so a group that would be refused there is refused here, at
-    // the call that asked for it, rather than coming back as a failed ack a
-    // round trip later with nothing to point at.
-    const payload = participantClaimPayloadSchema.safeParse({
-      claimId,
-      syncGroups: [...syncGroups],
-      capabilityToken: options?.capabilityToken,
-      ttlSeconds: options?.ttlSeconds,
-    });
-    if (!payload.success) {
-      return Promise.reject(
-        new AbloValidationError(
-          `join was given a sync group the protocol does not accept: ${payload.error.issues[0]?.message ?? 'unreadable'}. A group is 'default' or 'kind:id'.`,
-          { code: 'malformed_claim' },
-        ),
-      );
-    }
-    const timeoutMs = options?.timeoutMs ?? 15_000;
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.pendingClaims.delete(claimId);
-        reject(
-          new AbloConnectionError(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`, {
-            code: 'wait_for_timeout',
-          }),
-        );
-      }, timeoutMs);
-      this.pendingClaims.set(claimId, { resolve, reject, timeout });
-      try {
-        this.ws!.send(JSON.stringify({ type: 'claim', payload: payload.data }));
-      } catch (error) {
-        clearTimeout(timeout);
-        this.pendingClaims.delete(claimId);
-        reject(toAbloError(error));
-      }
-    });
-  }
-
-  /**
-   * Drop a previously-active claim. Idempotent — `release` is
-   * fire-and-forget per the wire contract; the server accepts
-   * unknown claimIds silently so disconnect-time release storms
-   * never error. No ack is expected.
-   *
-   * If a claim's send promise is still pending (no claim_ack yet),
-   * we reject it locally — the user explicitly chose to release.
-   */
-  sendRelease(claimId: string): void {
-    // Cancel any in-flight claim that hadn't acked yet — the user
-    // changed their mind. Without this the timer would eventually
-    // reject; doing it now matches the user's claim immediately.
-    const pending = this.pendingClaims.get(claimId);
-    if (pending) {
-      clearTimeout(pending.timeout);
-      this.pendingClaims.delete(claimId);
-      pending.reject(
-        new AbloError(`claim ${claimId} released before ack`, {
-          code: 'claim_wait_aborted',
-          httpStatus: 409,
-        }),
-      );
-    }
-    if (this.ws?.readyState !== WebSocket.OPEN) return;
-    try {
-      this.ws.send(
-        JSON.stringify({ type: 'release', payload: { claimId } }),
-      );
-    } catch {
-      // Idempotent contract — silent failure is acceptable here.
-    }
-  }
-
   /**
    * Moves this connection's read interest — replaces the connection-level sync
    * groups mid-session as the user opens and closes entities. This is the
@@ -1443,8 +1316,13 @@ export class WsTransport<
     }
 
     if (this.ws) {
-      this.ws.close(1000, 'Manual disconnect');
+      // Detach before close: Node/undici may synchronously fire `onerror` from
+      // close(). The handler's stale-socket guard then suppresses that expected
+      // manual-close error instead of emitting EventEmitter's fatal unhandled
+      // `error` event. `onclose` deliberately accepts a null owner below.
+      const socket = this.ws;
       this.ws = null;
+      socket.close(1000, 'Manual disconnect');
     }
   }