@onekeyfe/hd-transport 1.2.0-alpha.3 → 1.2.0-alpha.31

package/src/protocols/index.ts

@@ -6,10 +6,14 @@ import { decodeMessage as decodeV1Message } from './v1/receive';
 import { createMessageFromName, createMessageFromType } from '../serialization/protobuf/messages';
 import { encode as encodeProtobuf } from '../serialization/protobuf/encode';
 import { decode as decodeProtobuf } from '../serialization/protobuf/decode';
-import { decodeFrame as decodeV2Frame, encodeProtobufFrame } from './v2';
+import {
+  decodeFrame as decodeV2Frame,
+  encodeProtobufFrame,
+  inspectFrameHeader,
+  isAckFrame,
+} from './v2';
 
 import type { Root } from 'protobufjs/light';
-import type { ProtocolV2DebugLogger } from './v2';
 
 export const PROTOCOL_V2_SYS_MESSAGE_THRESHOLD = 60000;
 
@@ -23,9 +27,6 @@ type ProtocolV2FrameOptions = {
   router?: number;
   /** Sequence number (1-255). Managed per-session by ProtocolV2Session. */
   seq?: number;
-  logger?: ProtocolV2DebugLogger;
-  logPrefix?: string;
-  context?: string;
 };
 
 const resolveProtocolV2EncodeSchema = (name: string, schemas: ProtocolV2Schemas) => {
@@ -74,6 +75,24 @@ export const ProtocolV1 = {
 };
 
 export const ProtocolV2 = {
+  isAckFrame,
+  inspectFrameHeader,
+
+  inspectFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
+    const { messageTypeId, pbPayload, seq, router, packetSrc, dataType } = decodeV2Frame(frame);
+    const { messageName } = createProtocolV2MessageFromType(messageTypeId, schemas);
+    return {
+      messageName,
+      messageTypeId,
+      pbPayload,
+      seq,
+      router,
+      packetSrc,
+      dataType,
+      type: messageName,
+    };
+  },
+
   encodeFrame(
     schemas: ProtocolV2Schemas,
     name: string,
@@ -87,51 +106,31 @@ export const ProtocolV2 = {
     const rawPbBuffer = pbBuffer.toBuffer() as unknown as ArrayBuffer;
     const pbBytes = new Uint8Array(rawPbBuffer);
 
-    options.logger?.debug?.(`[${options.logPrefix ?? 'ProtocolV2'}] encode protobuf`, {
-      context: options.context ?? `encode:${name}`,
-      messageName: name,
-      messageTypeId,
-      pbPayloadLength: pbBytes.length,
-      packetSrc: options.packetSrc ?? 0,
-      router: options.router ?? 0,
-    });
-
     return encodeProtobufFrame(
       messageTypeId,
       pbBytes,
       options.packetSrc,
       options.router,
-      {
-        logger: options.logger,
-        logPrefix: options.logPrefix,
-        context: options.context ?? `encode:${name}`,
-        messageName: name,
-      },
       options.seq
     );
   },
 
-  decodeFrame(
-    schemas: ProtocolV2Schemas,
-    frame: Uint8Array,
-    options: Pick<ProtocolV2FrameOptions, 'logger' | 'logPrefix' | 'context'> = {}
-  ) {
-    const { messageTypeId, pbPayload, seq } = decodeV2Frame(frame, {
-      logger: options.logger,
-      logPrefix: options.logPrefix,
-      context: options.context ?? 'decode',
-    });
-    const { Message, messageName } = createProtocolV2MessageFromType(messageTypeId, schemas);
+  decodeFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
+    const { messageTypeId, pbPayload, seq, messageName } = this.inspectFrame(schemas, frame);
+    const { Message } = createProtocolV2MessageFromType(messageTypeId, schemas);
     const rxByteBuffer = ByteBuffer.wrap(Buffer.from(pbPayload) as unknown as ArrayBuffer);
-    const message = decodeProtobuf(Message, rxByteBuffer);
-
-    options.logger?.debug?.(`[${options.logPrefix ?? 'ProtocolV2'}] decode protobuf`, {
-      context: options.context ?? `decode:${messageName}`,
-      messageName,
-      messageTypeId,
-      pbPayloadLength: pbPayload.length,
-      seq,
-    });
+    let message: ReturnType<typeof decodeProtobuf>;
+    try {
+      message = decodeProtobuf(Message, rxByteBuffer);
+    } catch (cause) {
+      const error = new Error(
+        `Protocol V2 protobuf decode failed for "${messageName}" ` +
+          `(${messageTypeId}, ${pbPayload.length}-byte payload); ` +
+          'the payload is malformed or incompatible with the active SDK schema.'
+      );
+      (error as Error & { cause?: unknown }).cause = cause;
+      throw error;
+    }
 
     return {
       message,

package/src/protocols/v2/ble-frame-writer.ts

@@ -0,0 +1,77 @@
+export type ProtocolV2BleFrameWriterOptions = {
+  frame: Uint8Array;
+  packetCapacity: number;
+  writePacket: (packet: Uint8Array, packetIndex: number) => Promise<void>;
+  assertActive?: () => void;
+  signal?: AbortSignal;
+  abortMessage?: string;
+  initialDelayMs?: number;
+  burstSize?: number;
+  burstPauseMs?: number;
+  flushDelayMs?: number;
+  wait?: (timeoutMs: number) => Promise<void>;
+};
+
+const defaultWait = (timeoutMs: number) =>
+  new Promise<void>(resolve => {
+    setTimeout(resolve, timeoutMs);
+  });
+
+export async function writeProtocolV2BleFrame({
+  frame,
+  packetCapacity,
+  writePacket,
+  assertActive,
+  signal,
+  abortMessage = 'Protocol V2 BLE write aborted',
+  initialDelayMs = 0,
+  burstSize,
+  burstPauseMs = 0,
+  flushDelayMs = 0,
+  wait = defaultWait,
+}: ProtocolV2BleFrameWriterOptions): Promise<void> {
+  if (!Number.isInteger(packetCapacity) || packetCapacity <= 0) {
+    throw new Error('Protocol V2 BLE packet capacity must be a positive integer');
+  }
+  if (burstSize !== undefined && (!Number.isInteger(burstSize) || burstSize <= 0)) {
+    throw new Error('Protocol V2 BLE burst size must be a positive integer');
+  }
+
+  const assertWritable = () => {
+    assertActive?.();
+    if (signal?.aborted) {
+      throw new Error(abortMessage);
+    }
+  };
+
+  if (frame.length > 0 && initialDelayMs > 0) {
+    assertWritable();
+    await wait(initialDelayMs);
+    assertWritable();
+  }
+
+  let packetsWritten = 0;
+  for (let offset = 0; offset < frame.length; offset += packetCapacity) {
+    assertWritable();
+    const packet = frame.slice(offset, offset + packetCapacity);
+    await writePacket(packet, packetsWritten);
+    packetsWritten += 1;
+    assertWritable();
+
+    const hasMorePackets = offset + packetCapacity < frame.length;
+    if (
+      hasMorePackets &&
+      burstSize !== undefined &&
+      packetsWritten % burstSize === 0 &&
+      burstPauseMs > 0
+    ) {
+      await wait(burstPauseMs);
+      assertWritable();
+    }
+  }
+
+  if (burstSize !== undefined && packetsWritten > burstSize && flushDelayMs > 0) {
+    await wait(flushDelayMs);
+    assertWritable();
+  }
+}

package/src/protocols/v2/constants.ts

@@ -4,3 +4,4 @@ export const PROTO_HEAD_CRC_SIZE = 8;
 export const CRC8_INIT = 0x30;
 export const PACKET_SIZE = 4096;
 export const PROTO_DATA_TYPE_PACKET = 0;
+export const PROTO_DATA_TYPE_ACK = 1;

package/src/protocols/v2/crc8.ts

@@ -22,7 +22,7 @@ export const CRC8_TABLE = new Uint8Array([
 ]);
 
 /**
- * 计算 data 前 len 个字节的 CRC-8，使用与固件侧一致的初始值。
+ * Compute CRC-8 over the first len bytes using the firmware-compatible initial value.
  */
 export function crc8(data: Uint8Array, len: number): number {
   let crc = CRC8_INIT;

package/src/protocols/v2/decode.ts

@@ -1,8 +1,10 @@
-import { PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF } from './constants';
+import {
+  PROTO_DATA_TYPE_ACK,
+  PROTO_DATA_TYPE_PACKET,
+  PROTO_HEAD_CRC_SIZE,
+  PROTO_HEAD_SOF,
+} from './constants';
 import { crc8 } from './crc8';
-import { logProtocolV2Debug } from './debug';
-
-import type { ProtocolV2FrameDebugOptions } from './debug';
 
 export interface ProtoV2Frame {
   /** Little-endian message type ID */
@@ -11,22 +13,23 @@ export interface ProtoV2Frame {
   pbPayload: Uint8Array;
   /** Sequence number from the frame header */
   seq: number;
+  /** Routing channel from the frame header */
+  router: number;
+  /** Packet source from the frame header */
+  packetSrc: number;
+  /** Packet or ACK discriminator from the frame header */
+  dataType: number;
 }
 
-/**
- * Parse and validate a Protocol V2 response frame.
- *
- * Validates:
- *   - SOF byte (0x5A)
- *   - Header CRC (bytes 0-2)
- *   - Frame CRC (full frame except last byte)
- *
- * Returns the decoded messageTypeId, raw protobuf payload, and sequence number.
- */
-export function decodeFrame(
-  data: Uint8Array,
-  debugOptions?: ProtocolV2FrameDebugOptions
-): ProtoV2Frame {
+export type ProtoV2FrameHeader = {
+  frameLen: number;
+  router: number;
+  packetSrc: number;
+  dataType: number;
+  seq: number;
+};
+
+export function inspectFrameHeader(data: Uint8Array): ProtoV2FrameHeader {
   if (data.length < PROTO_HEAD_CRC_SIZE) {
     throw new Error(`Protocol V2 frame too short: ${data.length} bytes`);
   }
@@ -39,11 +42,12 @@ export function decodeFrame(
 
   const frameLen = data[1] + data[2] * 256;
 
-  if (data.length < frameLen) {
-    throw new Error(`Frame truncated: expected ${frameLen} bytes, got ${data.length}`);
+  if (data.length !== frameLen) {
+    throw new Error(
+      `Protocol V2 frame length mismatch: expected ${frameLen} bytes, got ${data.length}`
+    );
   }
 
-  // Verify pre-header CRC (bytes 0-2)
   const expectedHeaderCrc = crc8(data, 3);
   if (data[3] !== expectedHeaderCrc) {
     throw new Error(
@@ -53,7 +57,6 @@ export function decodeFrame(
     );
   }
 
-  // Verify frame CRC (all bytes except last)
   const expectedFrameCrc = crc8(data, frameLen - 1);
   if (data[frameLen - 1] !== expectedFrameCrc) {
     throw new Error(
@@ -63,7 +66,52 @@ export function decodeFrame(
     );
   }
 
+  // eslint-disable-next-line no-bitwise
+  const dataType = data[5] & 0x03;
+  // eslint-disable-next-line no-bitwise
+  const packetSrc = (data[5] >> 2) & 0x0f;
   const seq = data[6];
+  if (seq === 0) {
+    throw new Error('Invalid Protocol V2 sequence: 0 is reserved');
+  }
+
+  return {
+    frameLen,
+    router: data[4],
+    packetSrc,
+    dataType,
+    seq,
+  };
+}
+
+export function isAckFrame(data: Uint8Array): boolean {
+  // eslint-disable-next-line no-bitwise
+  if (data.length < 6 || (data[5] & 0x03) !== PROTO_DATA_TYPE_ACK) {
+    return false;
+  }
+
+  const header = inspectFrameHeader(data);
+  if (header.frameLen !== PROTO_HEAD_CRC_SIZE) {
+    throw new Error(`Invalid Protocol V2 ACK frame length: ${header.frameLen}`);
+  }
+  return true;
+}
+
+/**
+ * Parse and validate a Protocol V2 response frame.
+ *
+ * Validates:
+ *   - SOF byte (0x5A)
+ *   - Header CRC (bytes 0-2)
+ *   - Frame CRC (full frame except last byte)
+ *
+ * Returns the decoded messageTypeId, raw protobuf payload, and sequence number.
+ */
+export function decodeFrame(data: Uint8Array): ProtoV2Frame {
+  const { frameLen, router, packetSrc, dataType, seq } = inspectFrameHeader(data);
+  if (dataType !== PROTO_DATA_TYPE_PACKET) {
+    throw new Error(`Invalid Protocol V2 data type: expected packet, got ${dataType}`);
+  }
   // Payload spans bytes 7 to frameLen-2 (inclusive), excluding final CRC byte
   const payloadData = data.slice(7, frameLen - 1);
 
@@ -74,19 +122,5 @@ export function decodeFrame(
   const messageTypeId = payloadData[0] + payloadData[1] * 256;
   const pbPayload = payloadData.slice(2);
 
-  logProtocolV2Debug(debugOptions, 'decode raw frame', {
-    frameLen,
-    dataLength: data.length,
-    router: data[4],
-    attr: data[5],
-    seq,
-    headerCrc: data[3],
-    expectedHeaderCrc,
-    frameCrc: data[frameLen - 1],
-    expectedFrameCrc,
-    messageTypeId,
-    pbPayloadLength: pbPayload.length,
-  });
-
-  return { messageTypeId, pbPayload, seq };
+  return { messageTypeId, pbPayload, seq, router, packetSrc, dataType };
 }

package/src/protocols/v2/encode.ts

@@ -1,10 +1,7 @@
 import { PROTO_DATA_TYPE_PACKET, PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF } from './constants';
 import { crc8 } from './crc8';
-import { logProtocolV2Debug } from './debug';
 import { PROTOCOL_V2_FRAME_MAX_BYTES } from '../../constants';
 
-import type { ProtocolV2FrameDebugOptions } from './debug';
-
 // Default sequence number when callers do not manage one themselves.
 // Stateful per-session sequencing lives in ProtocolV2Session (session.ts),
 // which advances the counter via nextProtoSeq() and passes it in explicitly.
@@ -35,7 +32,6 @@ export function encodeFrame(
   payload: Uint8Array | null,
   packetSrc?: number,
   router?: number,
-  debugOptions?: ProtocolV2FrameDebugOptions,
   seq?: number
 ): Uint8Array {
   const resolvedPacketSrc = packetSrc ?? 0;
@@ -47,7 +43,7 @@ export function encodeFrame(
   const payloadLen = payload ? payload.length : 0;
   const frameLen = payloadLen + PROTO_HEAD_CRC_SIZE;
   if (frameLen > PROTOCOL_V2_FRAME_MAX_BYTES) {
-    throw new Error(`Protocol V2 frame too large: ${frameLen}`);
+    throw new Error(`Protocol V2 frame too large: ${frameLen} > ${PROTOCOL_V2_FRAME_MAX_BYTES}`);
   }
   const frame = new Uint8Array(frameLen);
 
@@ -69,17 +65,6 @@ export function encodeFrame(
   // CRC8 over entire frame except last byte
   frame[frameLen - 1] = crc8(frame, frameLen - 1);
 
-  logProtocolV2Debug(debugOptions, 'encode raw frame', {
-    frameLen,
-    payloadLen,
-    packetSrc: resolvedPacketSrc,
-    router: frame[4],
-    attr: frame[5],
-    seq: frame[6],
-    headerCrc: frame[3],
-    frameCrc: frame[frameLen - 1],
-  });
-
   return frame;
 }
 
@@ -95,22 +80,11 @@ export function encodeProtobufFrame(
   pbPayload: Uint8Array,
   packetSrc?: number,
   router?: number,
-  debugOptions?: ProtocolV2FrameDebugOptions,
   seq?: number
 ): Uint8Array {
   const payload = new Uint8Array(2 + pbPayload.length);
   payload[0] = messageTypeId % 256;
   payload[1] = Math.floor(messageTypeId / 256) % 256;
   payload.set(pbPayload, 2);
-  return encodeFrame(
-    payload,
-    packetSrc,
-    router,
-    {
-      ...debugOptions,
-      messageTypeId,
-      pbPayloadLength: pbPayload.length,
-    },
-    seq
-  );
+  return encodeFrame(payload, packetSrc, router, seq);
 }

package/src/protocols/v2/errors.ts

@@ -0,0 +1,25 @@
+export type ProtocolV2LinkErrorCode =
+  | 'response-timeout'
+  | 'io'
+  | 'generation'
+  | 'router'
+  | 'packet-source'
+  | 'ack-sequence'
+  | 'response-sequence'
+  | 'frame';
+
+export class ProtocolV2LinkError extends Error {
+  readonly code: ProtocolV2LinkErrorCode;
+
+  readonly cause?: unknown;
+
+  constructor(code: ProtocolV2LinkErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'ProtocolV2LinkError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+export const isProtocolV2LinkError = (error: unknown): error is ProtocolV2LinkError =>
+  error instanceof ProtocolV2LinkError;

package/src/protocols/v2/frame-assembler.ts

@@ -1,6 +1,7 @@
 import { PROTOCOL_V2_FRAME_MAX_BYTES } from '../../constants';
 import { PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF, PROTO_PRE_HEAD_SIZE } from './constants';
 import { crc8 } from './crc8';
+import { ProtocolV2LinkError } from './errors';
 
 export function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array {
   const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
@@ -58,7 +59,7 @@ export class ProtocolV2FrameAssembler {
 
     if (this.buffer[0] !== PROTO_HEAD_SOF) {
       this.reset();
-      throw new Error('Invalid Protocol V2 SOF');
+      throw new ProtocolV2LinkError('frame', 'Invalid Protocol V2 SOF');
     }
 
     const expectedLen = this.buffer[1] + this.buffer[2] * 256;
@@ -67,11 +68,11 @@ export class ProtocolV2FrameAssembler {
       // complete frame: without resetting, this poison prefix would stay in
       // the buffer forever and deadlock the caller's drain loop.
       this.reset();
-      throw new Error(`Protocol V2 frame length too small: ${expectedLen}`);
+      throw new ProtocolV2LinkError('frame', `Protocol V2 frame length too small: ${expectedLen}`);
     }
     if (expectedLen > this.maxFrameBytes) {
       this.reset();
-      throw new Error(`Protocol V2 frame too large: ${expectedLen}`);
+      throw new ProtocolV2LinkError('frame', `Protocol V2 frame too large: ${expectedLen}`);
     }
 
     if (this.buffer.length < PROTO_PRE_HEAD_SIZE) return undefined;
@@ -82,7 +83,8 @@ export class ProtocolV2FrameAssembler {
     const expectedHeaderCrc = crc8(this.buffer, 3);
     if (this.buffer[3] !== expectedHeaderCrc) {
       this.reset();
-      throw new Error(
+      throw new ProtocolV2LinkError(
+        'frame',
         `Protocol V2 header CRC mismatch: expected 0x${expectedHeaderCrc
           .toString(16)
           .padStart(2, '0')}`

package/src/protocols/v2/index.ts

@@ -1,6 +1,7 @@
 export * from './constants';
 export * from './crc8';
-export * from './debug';
 export * from './encode';
 export * from './decode';
+export * from './errors';
 export * from './frame-assembler';
+export * from './ble-frame-writer';

package/src/protocols/v2/link-manager.ts

@@ -0,0 +1,186 @@
+import { ProtocolV2SequenceCursor } from './sequence-cursor';
+import { ProtocolV2LinkError } from './errors';
+import { ProtocolV2Session, getErrorMessage } from './session';
+
+import type { MessageFromOneKey, TransportCallOptions } from '../../types';
+import type { ProtocolV2CallContext, ProtocolV2Schemas, ProtocolV2SessionOptions } from './session';
+
+export type ProtocolV2LinkErrorClassification = 'link-fatal' | 'recoverable';
+
+export interface ProtocolV2LinkAdapter {
+  router: number;
+  maxFrameBytes?: number;
+  generation: number;
+  prepareCall(context: ProtocolV2CallContext): Promise<void> | void;
+  writeFrame(frame: Uint8Array, context: ProtocolV2CallContext): Promise<void>;
+  readFrame(context: ProtocolV2CallContext): Promise<Uint8Array>;
+  reset(reason: string): Promise<void> | void;
+  logger?: ProtocolV2SessionOptions['logger'];
+  logPrefix?: string;
+  createTimeoutError?: ProtocolV2SessionOptions['createTimeoutError'];
+}
+
+export type ProtocolV2LinkManagerOptions<Key> = {
+  getSchemas: () => ProtocolV2Schemas;
+  classifyError: (error: unknown) => ProtocolV2LinkErrorClassification;
+  onLinkInvalidated?: (key: Key, reason: string) => Promise<void> | void;
+};
+
+type ProtocolV2Link = {
+  adapter: ProtocolV2LinkAdapter;
+  session: ProtocolV2Session;
+  state: {
+    invalidatedReason?: string;
+  };
+};
+
+export class ProtocolV2LinkManager<Key> {
+  private readonly links = new Map<Key, ProtocolV2Link>();
+
+  private readonly sequences = new Map<Key, ProtocolV2SequenceCursor>();
+
+  private readonly callQueues = new Map<Key, Promise<unknown>>();
+
+  private readonly generations = new Map<Key, number>();
+
+  private readonly invalidationReasons = new Map<Key, { generation: number; reason: string }>();
+
+  private readonly options: ProtocolV2LinkManagerOptions<Key>;
+
+  constructor(options: ProtocolV2LinkManagerOptions<Key>) {
+    this.options = options;
+  }
+
+  call(
+    key: Key,
+    createAdapter: () => ProtocolV2LinkAdapter,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ): Promise<MessageFromOneKey> {
+    const generation = this.generations.get(key) ?? 0;
+    const run = () => {
+      this.assertCallGeneration(key, generation);
+      return this.executeCall(key, createAdapter, name, data, options);
+    };
+    const previous = this.callQueues.get(key) ?? Promise.resolve();
+    const result = previous.then(run, run);
+    const queue = result.catch(() => undefined);
+    this.callQueues.set(key, queue);
+    result
+      .then(
+        () => this.clearSettledCallQueue(key, queue),
+        () => this.clearSettledCallQueue(key, queue)
+      )
+      .catch(() => undefined);
+    return result;
+  }
+
+  async invalidateLink(key: Key, reason: string): Promise<void> {
+    const generation = (this.generations.get(key) ?? 0) + 1;
+    this.generations.set(key, generation);
+    this.invalidationReasons.set(key, { generation, reason });
+
+    const link = this.links.get(key);
+    if (!link) return;
+
+    this.links.delete(key);
+    link.state.invalidatedReason = reason;
+    await link.adapter.reset(reason);
+    await this.options.onLinkInvalidated?.(key, reason);
+  }
+
+  async invalidateAllLinks(reason: string): Promise<void> {
+    const keys = new Set([...this.links.keys(), ...this.callQueues.keys()]);
+    await Promise.all(Array.from(keys, key => this.invalidateLink(key, reason)));
+  }
+
+  async dispose(reason: string): Promise<void> {
+    await this.invalidateAllLinks(reason);
+    this.sequences.clear();
+    this.callQueues.clear();
+  }
+
+  private getOrCreateLink(key: Key, createAdapter: () => ProtocolV2LinkAdapter): ProtocolV2Link {
+    const existing = this.links.get(key);
+    if (existing) return existing;
+
+    const adapter = createAdapter();
+    const state: ProtocolV2Link['state'] = {};
+    const assertLinkActive = () => {
+      if (state.invalidatedReason) {
+        throw new Error(state.invalidatedReason);
+      }
+    };
+    let sequenceCursor = this.sequences.get(key);
+    if (!sequenceCursor) {
+      sequenceCursor = new ProtocolV2SequenceCursor();
+      this.sequences.set(key, sequenceCursor);
+    }
+    const session = new ProtocolV2Session({
+      schemas: this.options.getSchemas(),
+      router: adapter.router,
+      maxFrameBytes: adapter.maxFrameBytes,
+      generation: adapter.generation,
+      sequenceCursor,
+      prepareCall: async context => {
+        assertLinkActive();
+        await adapter.prepareCall(context);
+        assertLinkActive();
+      },
+      writeFrame: async (frame, context) => {
+        assertLinkActive();
+        await adapter.writeFrame(frame, context);
+        assertLinkActive();
+      },
+      readFrame: async context => {
+        assertLinkActive();
+        const frame = await adapter.readFrame(context);
+        assertLinkActive();
+        return frame;
+      },
+      logger: adapter.logger,
+      logPrefix: adapter.logPrefix,
+      createTimeoutError: adapter.createTimeoutError,
+    });
+    const link = { adapter, session, state };
+    this.links.set(key, link);
+    return link;
+  }
+
+  private async executeCall(
+    key: Key,
+    createAdapter: () => ProtocolV2LinkAdapter,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ): Promise<MessageFromOneKey> {
+    try {
+      return await this.getOrCreateLink(key, createAdapter).session.call(name, data, options);
+    } catch (error) {
+      if (this.options.classifyError(error) === 'link-fatal') {
+        const errorMessage = getErrorMessage(error) || 'unknown error';
+        await this.invalidateLink(key, `Protocol V2 link-fatal error: ${errorMessage}`);
+      }
+      throw error;
+    }
+  }
+
+  private clearSettledCallQueue(key: Key, queue: Promise<unknown>) {
+    if (this.callQueues.get(key) === queue) {
+      this.callQueues.delete(key);
+    }
+  }
+
+  private assertCallGeneration(key: Key, generation: number) {
+    const currentGeneration = this.generations.get(key) ?? 0;
+    if (currentGeneration === generation) return;
+
+    const invalidation = this.invalidationReasons.get(key);
+    const reason =
+      invalidation?.generation === currentGeneration
+        ? invalidation.reason
+        : 'Protocol V2 link generation changed';
+    throw new ProtocolV2LinkError('generation', reason);
+  }
+}