@onekeyfe/hd-core 1.1.34-alpha.3 → 1.1.34-alpha.4

package/src/api/FirmwareUpdateV4.ts

@@ -1,2279 +0,0 @@
-import { ERRORS, HardwareError, HardwareErrorCode, wait } from '@onekeyfe/hd-shared';
-import {
-  DeviceRebootType,
-  PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
-  PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
-} from '@onekeyfe/hd-transport';
-
-import { FirmwareUpdateTipMessage, UI_REQUEST } from '../events/ui-request';
-import { validateParams } from './helpers/paramsValidator';
-import {
-  LoggerNames,
-  getDeviceBLEFirmwareVersion,
-  getDeviceBootloaderVersion,
-  getDeviceFirmwareVersion,
-  getFirmwareType,
-  getLogger,
-} from '../utils';
-import { getSysResourceBinary } from './firmware/getBinary';
-import { DataManager } from '../data-manager';
-import { FirmwareUpdateBaseMethod } from './firmware/FirmwareUpdateBaseMethod';
-import { DevicePool } from '../device/DevicePool';
-import {
-  PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
-  ProtocolV2FirmwareTargetType,
-} from '../protocols/protocol-v2';
-import { requestProtocolV2DeviceInfo } from '../protocols/protocol-v2/features';
-import {
-  getProtocolV2UnknownErrorText,
-  isProtocolV2DeviceDisconnectedError,
-} from './protocol-v2/helpers';
-import { openFirmwareByteSource, writeFirmwareByteSource } from './firmware/FirmwareArtifactSource';
-import { FirmwareCheckpointWriter } from './firmware/FirmwareCheckpoint';
-import { resolveFirmwareUpdateHostBinding } from './firmware/FirmwareHostBinding';
-import { compileFirmwareUpdateEpochKinds } from './firmware/FirmwareUpdatePlan';
-import { assertFirmwareUpdatePreparedPlanBinding } from './firmware/FirmwareUpdatePreparedPlan';
-
-import type {
-  FirmwareArtifactReference,
-  FirmwareUpdateV4Params,
-  FirmwareUpdateV4Target,
-} from '../types/api/firmwareUpdate';
-import type { FirmwareUpdatePlanEpochKind } from '../types/api/firmwareUpdatePlan';
-import type { EFirmwareType } from '@onekeyfe/hd-shared';
-import type { TypedResponseMessage } from '../device/DeviceCommands';
-import type {
-  Features,
-  IFirmwareReleaseInfo,
-  IProtocolV2FirmwareComponent,
-  IVersionArray,
-} from '../types';
-import type { FirmwareByteSource } from './firmware/FirmwareArtifactSource';
-
-const Log = getLogger(LoggerNames.Method);
-
-const SESSION_ERROR = 'session not found';
-const PROTOCOL_V2_BOOTLOADER_RECONNECT_TIMEOUT = 60 * 1000;
-const PROTOCOL_V2_FINAL_RECONNECT_TIMEOUT = 2 * 60 * 1000;
-const PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT = 5 * 1000;
-const PROTOCOL_V2_START_UPDATE_TIMEOUT = 3 * 60 * 1000;
-const PROTOCOL_V2_INSTALL_TIMEOUT = 5 * 60 * 1000;
-const PROTOCOL_V2_TARGET_STATUS_PENDING = 0;
-const PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS = 1;
-const PROTOCOL_V2_TARGET_STATUS_FINISHED = 2;
-const PROTOCOL_V2_TARGET_STATUS_FAILED_MIN = 3;
-const PROTOCOL_V2_CONNECT_PROTOCOL = 'V2';
-const PROTOCOL_V2_FIRMWARE_STAGING_VOLUME = 'vol0:/';
-const PROTOCOL_V2_MIN_FILE_CHUNK_SIZE = 64;
-const PROTOCOL_V2_CONNECT_RETRY_COUNT = 10;
-const PROTOCOL_V2_CONNECT_POLL_INTERVAL = 500;
-const PROTOCOL_V2_CONNECT_SINGLE_TIMEOUT = 75 * 1000;
-const PROTOCOL_V2_DEVICE_INFO_READY_TIMEOUT = 60 * 1000;
-const PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT = 3;
-const PROTOCOL_V2_OKPP_HEADER_SIZE = 0x52a0;
-const PROTOCOL_V2_OKPP_PAYLOAD_HASH_OFFSET = 0x200;
-const PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET = 0x240;
-const PROTOCOL_V2_OKPP_HASH_SIZE = 64;
-
-const getProtocolV2DeviceTransferProgress = (
-  bytesBeforeChunk: number,
-  bytesAfterChunk: number,
-  totalBytes: number
-) => {
-  if (!Number.isFinite(totalBytes) || totalBytes <= 0) {
-    return 100;
-  }
-  if (bytesBeforeChunk <= 0 && bytesAfterChunk < totalBytes) {
-    return 0;
-  }
-  if (bytesAfterChunk >= totalBytes) {
-    return 100;
-  }
-  return Math.min(Math.max(Math.ceil((bytesAfterChunk / totalBytes) * 100), 1), 99);
-};
-
-type ProtocolV2FirmwareUpdateStatusTarget = {
-  target_id: number | string;
-  status?: number | string;
-  payload_version?: number;
-  path?: string;
-};
-
-type ProtocolV2FirmwareUpdateStartResponse = TypedResponseMessage<'Success'>;
-
-type ProtocolV2TargetBinary = { fileName: string; binary: ArrayBuffer; targetId: number };
-type ProtocolV2InstallItem = ProtocolV2TargetBinary & {
-  kind: ProtocolV2RemoteComponentTarget['kind'];
-};
-/** RESC bundle okpkg written independently to devicePath through FileWrite. */
-type ProtocolV2ResourceBundleBinary = {
-  name: string;
-  binary: ArrayBuffer;
-  devicePath: string;
-  /** Download URL for remote-config mode; omitted in manual mode. */
-  url?: string;
-  version?: IVersionArray;
-  payloadHash?: string;
-  headerHash?: string;
-};
-
-type ProtocolV2RemoteComponentBinary = ProtocolV2RemoteComponentTarget & {
-  binary: ArrayBuffer;
-};
-
-type ProtocolV2RemoteComponentTarget = {
-  fileName: string;
-  targetId: number;
-  kind: 'bootloader' | 'firmware';
-};
-
-type ProtocolV2InstallSource = {
-  fileName: string;
-  source: FirmwareByteSource;
-  targetId: number;
-  kind: ProtocolV2RemoteComponentTarget['kind'];
-};
-
-type ProtocolV2ResourceBundleSource = {
-  name: string;
-  source: FirmwareByteSource;
-  devicePath: string;
-  version?: IVersionArray;
-  payloadHash?: string;
-  headerHash?: string;
-};
-
-type ProtocolV2ExecutionEpoch = {
-  epoch: number;
-  kind: FirmwareUpdatePlanEpochKind;
-  installSources: ProtocolV2InstallSource[];
-  resourceSources: ProtocolV2ResourceBundleSource[];
-};
-
-type ProtocolV2OkppHeader = {
-  type: string;
-  version: IVersionArray;
-  payloadHash: string;
-  headerHash: string;
-};
-
-const PROTOCOL_V2_REMOTE_COMPONENT_TARGETS: Readonly<
-  Record<string, ProtocolV2RemoteComponentTarget>
-> = {
-  BOOTLOADER: {
-    fileName: 'bootloader.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER,
-    kind: 'bootloader',
-  },
-  APPLICATION_P1: {
-    fileName: 'application_p1.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1,
-    kind: 'firmware',
-  },
-  APPLICATION_P2: {
-    fileName: 'application_p2.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2,
-    kind: 'firmware',
-  },
-  COPROCESSOR: {
-    fileName: 'coprocessor.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR,
-    kind: 'firmware',
-  },
-  SE01: {
-    fileName: 'se01.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01,
-    kind: 'firmware',
-  },
-  SE02: {
-    fileName: 'se02.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02,
-    kind: 'firmware',
-  },
-  SE03: {
-    fileName: 'se03.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03,
-    kind: 'firmware',
-  },
-  SE04: {
-    fileName: 'se04.bin',
-    targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04,
-    kind: 'firmware',
-  },
-};
-
-const PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID = new Map<number, FirmwareUpdateV4Target>([
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER, 'boot'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1, 'app_v1'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2, 'app_v2'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR, 'coprocessor'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01, 'se01'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02, 'se02'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03, 'se03'],
-  [ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04, 'se04'],
-]);
-
-const PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE =
-  'FW_MGMT_TARGET_ROMLOADER is not accepted by the current Pro2 bootloader update request. Flash romloader with the loader-specific flow instead of firmwareUpdateV4.';
-
-// hd-transport historically decodes scalar enums as enum-name strings.
-// Map them back to firmware protocol values before internal comparisons.
-const PROTOCOL_V2_TARGET_ID_BY_DECODED_NAME = new Map<string, number>(
-  Object.entries(ProtocolV2FirmwareTargetType).map(([key, value]) => [key, value])
-);
-const PROTOCOL_V2_TARGET_STATUS_BY_DECODED_NAME = new Map<string, number>([
-  ['FW_MGMT_UPDATER_TASK_STATUS_PENDING', PROTOCOL_V2_TARGET_STATUS_PENDING],
-  ['FW_MGMT_UPDATER_TASK_STATUS_IN_PROGRESS', PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FINISHED', PROTOCOL_V2_TARGET_STATUS_FINISHED],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_FILE_NOT_FOUND', 3],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_FILE_READ', 4],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_FILE_WRITE', 5],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_VERIFY', 6],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_INSTALL', 7],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_ABORT', 8],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_BUSY', 9],
-  ['FW_MGMT_UPDATER_TASK_STATUS_FAILED_ENTRY_OUT_OF_BOUNDS', 10],
-]);
-
-const isProtocolV2ReconnectProbeError = (error: unknown) => {
-  const message = getProtocolV2UnknownErrorText(error).toLowerCase();
-  return (
-    (message.includes('device protocol mismatch') && message.includes('expected v2')) ||
-    message.includes('did not respond to expected protocol')
-  );
-};
-
-const isProtocolV2FirmwareStatusEndpointUnavailable = (error: unknown) => {
-  const message = getProtocolV2UnknownErrorText(error).toLowerCase();
-  return (
-    message.includes('handler not registered') ||
-    message.includes('message handler not found') ||
-    message.includes('unsupported message')
-  );
-};
-
-const isProtocolV2TargetStatusFinished = (status: ProtocolV2FirmwareUpdateStatusTarget['status']) =>
-  normalizeProtocolV2TargetStatus(status) === PROTOCOL_V2_TARGET_STATUS_FINISHED;
-
-const isProtocolV2TargetStatusInProgress = (
-  status: ProtocolV2FirmwareUpdateStatusTarget['status']
-) =>
-  normalizeProtocolV2TargetStatus(status) === PROTOCOL_V2_TARGET_STATUS_PENDING ||
-  normalizeProtocolV2TargetStatus(status) === PROTOCOL_V2_TARGET_STATUS_IN_PROGRESS;
-
-const isProtocolV2TargetStatusFailed = (status: ProtocolV2FirmwareUpdateStatusTarget['status']) => {
-  const normalizedStatus = normalizeProtocolV2TargetStatus(status);
-  return (
-    typeof normalizedStatus === 'number' && normalizedStatus >= PROTOCOL_V2_TARGET_STATUS_FAILED_MIN
-  );
-};
-
-const normalizeProtocolV2TargetId = (targetId: number | string) => {
-  if (typeof targetId === 'number') {
-    return targetId;
-  }
-  return PROTOCOL_V2_TARGET_ID_BY_DECODED_NAME.get(targetId);
-};
-
-const normalizeProtocolV2TargetStatus = (
-  status: ProtocolV2FirmwareUpdateStatusTarget['status']
-) => {
-  if (typeof status === 'number') {
-    return status;
-  }
-  if (typeof status === 'string') {
-    return PROTOCOL_V2_TARGET_STATUS_BY_DECODED_NAME.get(status);
-  }
-  return undefined;
-};
-
-const normalizeProtocolV2Hex = (value?: string) => value?.replace(/^0x/i, '').toLowerCase();
-
-const versionArrayToNumber = (version?: IVersionArray) => {
-  if (!version) return undefined;
-  return version[0] * 0x10000 + version[1] * 0x100 + version[2];
-};
-
-const compareProtocolV2Versions = (current?: IVersionArray, target?: IVersionArray) => {
-  const currentNumber = versionArrayToNumber(current);
-  const targetNumber = versionArrayToNumber(target);
-  if (currentNumber === undefined || targetNumber === undefined) return undefined;
-  return currentNumber - targetNumber;
-};
-
-const bytesToHex = (bytes: Uint8Array) =>
-  Array.from(bytes)
-    .map(byte => byte.toString(16).padStart(2, '0'))
-    .join('');
-
-const hexToProtocolV2Bytes = (hex: string) => {
-  const normalized = hex.replace(/^0x/i, '');
-  if (!normalized || normalized.length % 2 !== 0 || /[^0-9a-f]/i.test(normalized)) {
-    return new Uint8Array(0);
-  }
-  const bytes = new Uint8Array(normalized.length / 2);
-  for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = Number.parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
-  }
-  return bytes;
-};
-
-const toProtocolV2Bytes = (value: unknown): Uint8Array => {
-  if (value instanceof Uint8Array) return value;
-  if (value instanceof ArrayBuffer) return new Uint8Array(value);
-  if (ArrayBuffer.isView(value)) {
-    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
-  }
-  if (typeof value === 'string') return hexToProtocolV2Bytes(value);
-  return new Uint8Array(0);
-};
-
-const toProtocolV2FiniteNumber = (value: unknown) => {
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
-  if (typeof value === 'string') {
-    const numeric = Number(value);
-    return Number.isFinite(numeric) ? numeric : undefined;
-  }
-  if (value && typeof value === 'object') {
-    const longLike = value as { toNumber?: () => number };
-    if (typeof longLike.toNumber === 'function') {
-      const numeric = longLike.toNumber();
-      return Number.isFinite(numeric) ? numeric : undefined;
-    }
-  }
-  return undefined;
-};
-
-const readProtocolV2Ascii = (bytes: Uint8Array, offset: number, length: number) =>
-  Array.from(bytes.slice(offset, offset + length))
-    .map(byte => String.fromCharCode(byte))
-    .join('');
-
-const parseProtocolV2OkppHeader = (bytes: Uint8Array): ProtocolV2OkppHeader | null => {
-  if (bytes.byteLength < PROTOCOL_V2_OKPP_HEADER_SIZE) return null;
-  if (readProtocolV2Ascii(bytes, 0, 4) !== 'OKPP') return null;
-
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  const headerLen = view.getUint32(0x0c, true);
-  if (headerLen !== PROTOCOL_V2_OKPP_HEADER_SIZE) return null;
-
-  const packedVersion = view.getUint32(0x10, true);
-  return {
-    type: readProtocolV2Ascii(bytes, 0x08, 4),
-    version: [
-      Math.floor(packedVersion / 0x10000) % 0x100,
-      Math.floor(packedVersion / 0x100) % 0x100,
-      packedVersion % 0x100,
-    ],
-    payloadHash: bytesToHex(
-      bytes.slice(
-        PROTOCOL_V2_OKPP_PAYLOAD_HASH_OFFSET,
-        PROTOCOL_V2_OKPP_PAYLOAD_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
-      )
-    ),
-    headerHash: bytesToHex(
-      bytes.slice(
-        PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET,
-        PROTOCOL_V2_OKPP_HEADER_HASH_OFFSET + PROTOCOL_V2_OKPP_HASH_SIZE
-      )
-    ),
-  };
-};
-
-export const assertProtocolV2ReconnectIdentity = (
-  expectedDeviceId?: string,
-  actualDeviceId?: string,
-  options: { allowMissingActual?: boolean } = {}
-) => {
-  if (!expectedDeviceId) return;
-  if (!actualDeviceId) {
-    if (options.allowMissingActual) return;
-    throw ERRORS.TypedError(
-      HardwareErrorCode.DeviceNotFound,
-      'Protocol V2 reconnect identity unavailable'
-    );
-  }
-  if (actualDeviceId !== expectedDeviceId) {
-    throw ERRORS.TypedError(
-      HardwareErrorCode.DeviceNotFound,
-      `Protocol V2 reconnect identity mismatch: expected ${expectedDeviceId}, received ${actualDeviceId}`
-    );
-  }
-};
-
-/**
- * FirmwareUpdateV4 is the complete Protocol V2 firmware update flow.
- *
- * It intentionally does not fall back to FirmwareUpdateV3/V1 behavior:
- * - upload uses FilesystemFileWrite
- * - install uses DeviceFirmwareUpdateRequest
- * - completion waits for target status to finish, reboots to normal, then polls DeviceInfo
- */
-export default class FirmwareUpdateV4 extends FirmwareUpdateBaseMethod<FirmwareUpdateV4Params> {
-  private protocolV2ExpectedDeviceId?: string;
-
-  private protocolV2PreparedSources: FirmwareByteSource[] = [];
-
-  private checkpointWriter?: FirmwareCheckpointWriter;
-
-  private protocolV2ExecutionInLoader = false;
-
-  private protocolV2CompletedTargetVersions = new Map<number, number>();
-
-  private protocolV2LatestFinalFeatures?: Features;
-
-  init() {
-    this.allowDeviceMode = [UI_REQUEST.BOOTLOADER, UI_REQUEST.NOT_INITIALIZE];
-    this.requireDeviceMode = [];
-    this.unlockPolicy = 'retry-on-locked';
-    this.useDevicePassphraseState = false;
-    this.skipForceUpdateCheck = true;
-
-    const { payload } = this;
-
-    if (typeof payload.retryCount !== 'number') {
-      payload.retryCount = PROTOCOL_V2_CONNECT_RETRY_COUNT;
-    }
-    if (typeof payload.pollIntervalTime !== 'number') {
-      payload.pollIntervalTime = PROTOCOL_V2_CONNECT_POLL_INTERVAL;
-    }
-    if (typeof payload.timeout !== 'number') {
-      payload.timeout = PROTOCOL_V2_CONNECT_SINGLE_TIMEOUT;
-    }
-    if (typeof payload.protocolV2DeviceInfoTimeoutMs !== 'number') {
-      payload.protocolV2DeviceInfoTimeoutMs = PROTOCOL_V2_DEVICE_INFO_READY_TIMEOUT;
-    }
-
-    validateParams(payload, [
-      { name: 'chunkSize', type: 'number' },
-      { name: 'forcedUpdateRes', type: 'boolean' },
-      { name: 'bootloaderBinary', type: 'buffer' },
-      { name: 'romloaderBinary', type: 'buffer' },
-      { name: 'applicationP1Binary', type: 'buffer' },
-      { name: 'applicationP2Binary', type: 'buffer' },
-      { name: 'coprocessorBinary', type: 'buffer' },
-      { name: 'se01Binary', type: 'buffer' },
-      { name: 'se02Binary', type: 'buffer' },
-      { name: 'se03Binary', type: 'buffer' },
-      { name: 'se04Binary', type: 'buffer' },
-      { name: 'firmwareType', type: 'string' },
-      { name: 'targetsToUpdate', type: 'array', allowEmpty: true },
-      { name: 'platform', type: 'string' },
-      { name: 'expectedDeviceId', type: 'string' },
-      { name: 'resourceBundleFiles', type: 'array', allowEmpty: true },
-    ]);
-    if (
-      payload.expectedDeviceId !== undefined &&
-      (payload.expectedDeviceId.length === 0 || payload.expectedDeviceId.length > 160)
-    ) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.CallMethodInvalidParameter,
-        'Protocol V2 expected device identity is invalid'
-      );
-    }
-    const hostBinding =
-      payload.preparedPlan || payload.componentArtifacts || payload.resourceBundleArtifacts
-        ? resolveFirmwareUpdateHostBinding(payload.hostBindingGeneration)
-        : undefined;
-    if (hostBinding) {
-      if (!payload.expectedDeviceId) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.CallMethodInvalidParameter,
-          'Protocol V2 prepared update requires the expected device identity'
-        );
-      }
-      assertFirmwareUpdatePreparedPlanBinding({
-        preparedPlan: payload.preparedPlan,
-        executor: 'v4',
-        platform: payload.platform,
-        deviceIdentity: payload.expectedDeviceId,
-        scopeTargets: [
-          'boot',
-          'app_v1',
-          'app_v2',
-          'coprocessor',
-          'resource',
-          'se01',
-          'se02',
-          'se03',
-          'se04',
-        ],
-        bindings: [
-          ...Object.entries(payload.componentArtifacts ?? {}).flatMap(([target, artifact]) =>
-            artifact
-              ? [
-                  {
-                    target: target as Exclude<FirmwareUpdateV4Target, 'resource'>,
-                    artifact,
-                  },
-                ]
-              : []
-          ),
-          ...(payload.resourceBundleArtifacts ?? []).map(
-            (entry: { name: string; artifact: FirmwareArtifactReference }) => ({
-              target: 'resource' as const,
-              logicalName: entry.name,
-              artifact: entry.artifact,
-            })
-          ),
-        ],
-      });
-    }
-
-    this.params = {
-      preparedPlan: payload.preparedPlan,
-      hostBindingGeneration: payload.hostBindingGeneration,
-      chunkSize: payload.chunkSize,
-      forcedUpdateRes: payload.forcedUpdateRes,
-      bootloaderBinary: payload.bootloaderBinary,
-      romloaderBinary: payload.romloaderBinary,
-      applicationP1Binary: payload.applicationP1Binary,
-      applicationP2Binary: payload.applicationP2Binary,
-      coprocessorBinary: payload.coprocessorBinary,
-      se01Binary: payload.se01Binary,
-      se02Binary: payload.se02Binary,
-      se03Binary: payload.se03Binary,
-      se04Binary: payload.se04Binary,
-      resourceBundleFiles: payload.resourceBundleFiles,
-      firmwareType: payload.firmwareType,
-      targetsToUpdate: payload.targetsToUpdate,
-      expectedTargetVersions: payload.expectedTargetVersions,
-      platform: payload.platform,
-      expectedDeviceId: payload.expectedDeviceId,
-      artifactReader: hostBinding?.artifactReader ?? payload.artifactReader,
-      componentArtifacts: payload.componentArtifacts,
-      resourceBundleArtifacts: payload.resourceBundleArtifacts,
-      checkpointSink: hostBinding?.checkpointSink ?? payload.checkpointSink,
-      checkpointSequenceStart: payload.checkpointSequenceStart,
-      resumeCheckpoint: payload.resumeCheckpoint,
-    };
-  }
-
-  private getProtocolV2FirmwareChunkSize() {
-    const payloadChunkSize = Number(this.params?.chunkSize);
-    const env = DataManager.getSettings('env');
-    const maxChunkSize =
-      this.params?.platform === 'native' || (env && DataManager.isBleConnect(env))
-        ? PROTOCOL_V2_BLE_FILE_CHUNK_SIZE
-        : PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
-    if (!Number.isFinite(payloadChunkSize) || payloadChunkSize <= 0) {
-      return maxChunkSize;
-    }
-    return Math.min(
-      Math.max(Math.floor(payloadChunkSize), PROTOCOL_V2_MIN_FILE_CHUNK_SIZE),
-      maxChunkSize
-    );
-  }
-
-  async run() {
-    if (!this.device.isProtocolV2()) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'firmwareUpdateV4 requires a Protocol V2 device'
-      );
-    }
-
-    Log.debug('FirmwareUpdateV4 strategy: Protocol V2');
-    return this.runProtocolV2();
-  }
-
-  private async runProtocolV2() {
-    this.checkpointWriter = new FirmwareCheckpointWriter(this.params, {
-      required: !!this.params.artifactReader,
-    });
-    const deviceFeatures = await this.getProtocolV2DeviceFeatures();
-    this.protocolV2ExpectedDeviceId =
-      this.params.expectedDeviceId ?? deviceFeatures.deviceId ?? undefined;
-    assertProtocolV2ReconnectIdentity(
-      this.protocolV2ExpectedDeviceId,
-      deviceFeatures.deviceId ?? undefined,
-      { allowMissingActual: !!deviceFeatures.bootloaderMode }
-    );
-    const deviceFirmwareType = getFirmwareType(deviceFeatures);
-    const firmwareType = this.params.firmwareType ?? deviceFirmwareType;
-    this.validateExpectedTargetVersions();
-
-    const recovery = await this.reconcileInterruptedProtocolV2Install();
-    if (recovery.completed) return recovery.completed;
-
-    if (
-      (this.params.componentArtifacts && Object.keys(this.params.componentArtifacts).length > 0) ||
-      this.params.resourceBundleArtifacts?.length
-    ) {
-      return this.runProtocolV2PreparedArtifacts(deviceFeatures, firmwareType, recovery.startEpoch);
-    }
-
-    let fwBinaryMap: ProtocolV2TargetBinary[] = [];
-    let bootloaderBinary: ArrayBuffer | null = null;
-    let installItems: ProtocolV2InstallItem[] | undefined;
-    let resourceBundles: ProtocolV2ResourceBundleBinary[] | undefined;
-    try {
-      this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
-      fwBinaryMap = this.collectExplicitTargetBinaries();
-      bootloaderBinary = this.prepareBootloaderBinary();
-      if (!this.hasExplicitProtocolV2Payload(fwBinaryMap)) {
-        if (
-          this.params.artifactReader ||
-          DataManager.getSettings('firmwareManifestMode') === 'external-only'
-        ) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.RuntimeError,
-            'Protocol V2 firmware artifacts must be prepared by the external firmware host',
-            {
-              firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
-            }
-          );
-        }
-        const remoteBinaries = await this.prepareRemoteProtocolV2Binaries(
-          firmwareType,
-          deviceFeatures
-        );
-        bootloaderBinary = remoteBinaries.bootloaderBinary;
-        fwBinaryMap = remoteBinaries.fwBinaryMap;
-        installItems = remoteBinaries.installItems;
-      }
-      const resourceDescriptors = this.prepareProtocolV2ResourceBundles(
-        firmwareType,
-        deviceFeatures
-      );
-      resourceBundles = resourceDescriptors?.length
-        ? await this.materializeProtocolV2ResourceBundles(resourceDescriptors)
-        : undefined;
-      this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
-    } catch (err) {
-      throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateDownloadFailed, err.message ?? err);
-    }
-
-    if (!bootloaderBinary && fwBinaryMap.length === 0 && !resourceBundles?.length) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.FirmwareUpdateDownloadFailed,
-        'No firmware to update'
-      );
-    }
-
-    const update = {
-      fwBinaryMap,
-      bootloaderBinary,
-      ...(installItems ? { installItems } : undefined),
-      ...(resourceBundles?.length ? { resourceBundles } : undefined),
-    };
-    if (recovery.startEpoch === 0) {
-      return this.executeProtocolV2Update(update);
-    }
-    return this.executeProtocolV2Update(update, recovery.startEpoch);
-  }
-
-  private async openProtocolV2PreparedSource(artifact: FirmwareArtifactReference) {
-    const source = await openFirmwareByteSource({
-      artifact,
-      reader: this.params.artifactReader,
-    });
-    if (!source) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `Firmware artifact ${artifact.artifactRef} is not prepared`,
-        {
-          firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
-        }
-      );
-    }
-    this.protocolV2PreparedSources.push(source);
-    return source;
-  }
-
-  private async openProtocolV2MemorySource(binary: ArrayBuffer) {
-    const source = await openFirmwareByteSource({ binary });
-    if (!source) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'Protocol V2 firmware binary is empty'
-      );
-    }
-    this.protocolV2PreparedSources.push(source);
-    return source;
-  }
-
-  private async closeProtocolV2PreparedSources() {
-    const sources = this.protocolV2PreparedSources.splice(0);
-    await Promise.all(sources.map(source => source.close().catch(() => undefined)));
-  }
-
-  private async prepareProtocolV2InstallSources(
-    firmwareType: EFirmwareType,
-    features: Features
-  ): Promise<ProtocolV2InstallSource[]> {
-    const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
-    if (!release) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'Protocol V2 firmware release is unavailable'
-      );
-    }
-    const componentArtifacts = this.params.componentArtifacts ?? {};
-    const requestedTargets = new Set(
-      this.params.targetsToUpdate ?? (Object.keys(componentArtifacts) as FirmwareUpdateV4Target[])
-    );
-    const installSources: ProtocolV2InstallSource[] = [];
-    const preparedTargets = new Set<FirmwareUpdateV4Target>();
-
-    for (const [key, component] of this.getRemoteComponentEntries(release)) {
-      const target = this.getRemoteComponentTarget(key, component);
-      const updateTarget = PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(target.targetId);
-      if (updateTarget && updateTarget !== 'resource' && requestedTargets.has(updateTarget)) {
-        const artifact = componentArtifacts[updateTarget];
-        if (!artifact) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.RuntimeError,
-            `Protocol V2 ${updateTarget} artifact is not prepared`,
-            {
-              firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
-              artifactName: updateTarget,
-            }
-          );
-        }
-        installSources.push({
-          ...target,
-          source: await this.openProtocolV2PreparedSource(artifact),
-        });
-        preparedTargets.add(updateTarget);
-      }
-    }
-
-    const unknownTarget = Array.from(requestedTargets).find(
-      target => target !== 'resource' && !preparedTargets.has(target)
-    );
-    if (unknownTarget) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `Protocol V2 release does not contain requested target ${unknownTarget}`
-      );
-    }
-    return installSources;
-  }
-
-  private async prepareProtocolV2ResourceSources(
-    firmwareType: EFirmwareType,
-    features: Features
-  ): Promise<ProtocolV2ResourceBundleSource[]> {
-    const preparedArtifacts = this.params.resourceBundleArtifacts ?? [];
-    const resourceRequested =
-      this.params.targetsToUpdate?.includes('resource') || preparedArtifacts.length > 0;
-    if (!resourceRequested) {
-      return [];
-    }
-    const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
-    const descriptors = release?.resourceBundles ?? [];
-    const artifactByName = new Map(
-      preparedArtifacts.map(item => [item.name, item.artifact] as const)
-    );
-    const sources: ProtocolV2ResourceBundleSource[] = [];
-    for (const descriptor of descriptors) {
-      const artifact = artifactByName.get(descriptor.name);
-      if (!artifact) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          `Protocol V2 resource bundle ${descriptor.name} is not prepared`,
-          {
-            firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
-            artifactName: descriptor.name,
-          }
-        );
-      }
-      sources.push({
-        name: descriptor.name,
-        source: await this.openProtocolV2PreparedSource(artifact),
-        devicePath: descriptor.devicePath,
-        version: descriptor.version,
-        payloadHash: descriptor.payloadHash,
-        headerHash: descriptor.headerHash,
-      });
-      artifactByName.delete(descriptor.name);
-    }
-    if (artifactByName.size > 0) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `Protocol V2 release does not contain resource bundle ${artifactByName.keys().next().value}`
-      );
-    }
-    return sources;
-  }
-
-  private async runProtocolV2PreparedArtifacts(
-    features: Features,
-    firmwareType: EFirmwareType,
-    startEpoch: number
-  ) {
-    try {
-      this.postTipMessage(FirmwareUpdateTipMessage.StartDownloadFirmware);
-      const installSources = await this.prepareProtocolV2InstallSources(firmwareType, features);
-      const resourceSources = await this.prepareProtocolV2ResourceSources(firmwareType, features);
-      if (installSources.length === 0 && resourceSources.length === 0) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.FirmwareUpdateDownloadFailed,
-          'No firmware to update'
-        );
-      }
-      this.postTipMessage(FirmwareUpdateTipMessage.FinishDownloadFirmware);
-
-      return await this.executeProtocolV2SourceUpdate({
-        installSources,
-        resourceSources,
-        startEpoch,
-      });
-    } finally {
-      await this.closeProtocolV2PreparedSources();
-    }
-  }
-
-  private validateExpectedTargetVersions() {
-    const expected = this.params.expectedTargetVersions;
-    if (expected === undefined) return;
-    if (typeof expected !== 'object' || expected === null || Array.isArray(expected)) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'Protocol V2 expected target versions are invalid'
-      );
-    }
-    for (const [target, version] of Object.entries(expected)) {
-      if (
-        !Array.from(PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.values()).includes(
-          target as FirmwareUpdateV4Target
-        ) ||
-        typeof version !== 'string' ||
-        !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/u.test(version) ||
-        version.length > 64
-      ) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          'Protocol V2 expected target version is invalid'
-        );
-      }
-    }
-  }
-
-  private getExpectedProtocolV2TargetVersion(targetId: number) {
-    const target = PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(targetId);
-    const version = target ? this.params?.expectedTargetVersions?.[target] : undefined;
-    if (!version) return undefined;
-    const parts = version.split(/[+-]/u, 1)[0].split('.').map(Number);
-    if (
-      parts.length !== 3 ||
-      parts.some(part => !Number.isSafeInteger(part) || part < 0 || part > 0xff)
-    ) {
-      return undefined;
-    }
-    return parts[0] * 0x10000 + parts[1] * 0x100 + parts[2];
-  }
-
-  private assertExpectedProtocolV2Versions(targets?: readonly FirmwareUpdateV4Target[]) {
-    const expected = this.params?.expectedTargetVersions;
-    if (!expected) return;
-    const features = this.protocolV2LatestFinalFeatures;
-    const requestedTargets = this.getProtocolV2RequestedTargets();
-    const applicationTargets = requestedTargets.filter(
-      target => target === 'app_v1' || target === 'app_v2'
-    );
-    const visibleVersions: Partial<Record<FirmwareUpdateV4Target, string>> = {
-      boot: features ? getDeviceBootloaderVersion(features).join('.') : undefined,
-      coprocessor: features ? getDeviceBLEFirmwareVersion(features).join('.') : undefined,
-      se01: features?.se01Version ?? undefined,
-      se02: features?.se02Version ?? undefined,
-      se03: features?.se03Version ?? undefined,
-      se04: features?.se04Version ?? undefined,
-    };
-    if (features && applicationTargets.length === 1) {
-      visibleVersions[applicationTargets[0]] = getDeviceFirmwareVersion(features).join('.');
-    }
-    const expectedEntries = (
-      Object.entries(expected) as Array<[FirmwareUpdateV4Target, string]>
-    ).filter(([target]) => !targets || targets.includes(target));
-    for (const [target, expectedVersion] of expectedEntries) {
-      const targetId = Array.from(PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.entries()).find(
-        ([, mappedTarget]) => mappedTarget === target
-      )?.[0];
-      const statusVersion =
-        targetId === undefined ? undefined : this.protocolV2CompletedTargetVersions.get(targetId);
-      const observedVersion =
-        statusVersion === undefined
-          ? visibleVersions[target]
-          : `${Math.floor(statusVersion / 0x10000) % 0x100}.${
-              Math.floor(statusVersion / 0x100) % 0x100
-            }.${statusVersion % 0x100}`;
-      if (!observedVersion) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          `Protocol V2 target ${target} has no observable final version`,
-          {
-            firmwareUpdateCode: 'FirmwareReconciliationUnavailable',
-          }
-        );
-      }
-      if (observedVersion !== expectedVersion) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.FirmwareVerificationFailed,
-          `Protocol V2 target ${target} reached ${observedVersion}, expected ${expectedVersion}`,
-          {
-            firmwareUpdateCode: 'FirmwareTransactionConflict',
-          }
-        );
-      }
-    }
-  }
-
-  private getProtocolV2RequestedTargets(): FirmwareUpdateV4Target[] {
-    if (this.params.targetsToUpdate?.length) {
-      return [...new Set(this.params.targetsToUpdate)];
-    }
-    const targets = new Set<FirmwareUpdateV4Target>();
-    Object.keys(this.params.componentArtifacts ?? {}).forEach(target =>
-      targets.add(target as FirmwareUpdateV4Target)
-    );
-    if (this.params.resourceBundleArtifacts?.length || this.params.resourceBundleFiles?.length) {
-      targets.add('resource');
-    }
-    if (this.params.bootloaderBinary) targets.add('boot');
-    if (this.params.applicationP1Binary) targets.add('app_v1');
-    if (this.params.applicationP2Binary) targets.add('app_v2');
-    if (this.params.coprocessorBinary) targets.add('coprocessor');
-    if (this.params.se01Binary) targets.add('se01');
-    if (this.params.se02Binary) targets.add('se02');
-    if (this.params.se03Binary) targets.add('se03');
-    if (this.params.se04Binary) targets.add('se04');
-    return Array.from(targets);
-  }
-
-  private getProtocolV2EpochKinds() {
-    return compileFirmwareUpdateEpochKinds({
-      executor: 'v4',
-      targets: this.getProtocolV2RequestedTargets(),
-    });
-  }
-
-  private getProtocolV2TargetsForEpoch(kind: FirmwareUpdatePlanEpochKind) {
-    const requestedTargets = new Set(this.getProtocolV2RequestedTargets());
-    return Array.from(PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.entries())
-      .filter(([, target]) => {
-        if (!requestedTargets.has(target)) return false;
-        if (kind === 'bootloader-install' || kind === 'bootloader-verify') {
-          return target === 'boot';
-        }
-        return kind === 'component-install' && target !== 'resource' && target !== 'boot';
-      })
-      .map(([targetId]) => ({
-        target_id: targetId,
-        path: this.getProtocolV2InstallItemStagingPath({
-          fileName:
-            Object.values(PROTOCOL_V2_REMOTE_COMPONENT_TARGETS).find(
-              target => target.targetId === targetId
-            )?.fileName ?? `target-${targetId}.bin`,
-        }),
-      }));
-  }
-
-  private async reconcileInterruptedProtocolV2Install() {
-    const checkpoint = this.params.resumeCheckpoint;
-    if (!checkpoint) {
-      return { startEpoch: 0 };
-    }
-    const epochKinds = this.getProtocolV2EpochKinds();
-    const epoch = checkpoint.epoch ?? 0;
-    if (epoch < 0 || epoch >= epochKinds.length) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'Protocol V2 recovery epoch is invalid',
-        {
-          firmwareUpdateCode: 'FirmwareTransactionConflict',
-        }
-      );
-    }
-    if (checkpoint.stage === 'FINAL_VERIFIED') {
-      return {
-        startEpoch: epoch,
-        completed: await this.completeProtocolV2FinalVerification(epoch),
-      };
-    }
-
-    let startEpoch = epoch;
-    const kind = epochKinds[epoch];
-    if (checkpoint.stage === 'INSTALL_REQUESTED' || checkpoint.stage === 'INSTALL_ACCEPTED') {
-      const targets = this.getProtocolV2TargetsForEpoch(kind);
-      if (targets.length === 0) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          'Protocol V2 recovery has no install targets',
-          {
-            firmwareUpdateCode: 'FirmwareTransactionConflict',
-          }
-        );
-      }
-      await this.waitForProtocolV2FirmwareUpdateComplete(targets, {
-        recovery: true,
-      });
-      await this.exitProtocolV2BootloaderToNormal(epoch);
-      await this.checkpointWriter?.commit({
-        stage: 'EPOCH_COMPLETED',
-        target: kind,
-        epoch,
-      });
-      startEpoch = epoch + 1;
-    } else if (
-      checkpoint.stage === 'BEFORE_DEVICE_MODE_CHANGE' &&
-      checkpoint.target === 'normal' &&
-      (kind === 'bootloader-install' || kind === 'component-install')
-    ) {
-      await this.exitProtocolV2BootloaderToNormal(epoch);
-      await this.checkpointWriter?.commit({
-        stage: 'EPOCH_COMPLETED',
-        target: kind,
-        epoch,
-      });
-      startEpoch = epoch + 1;
-    } else if (checkpoint.stage === 'EPOCH_COMPLETED') {
-      startEpoch = epoch + 1;
-    }
-
-    if (epochKinds[startEpoch] === 'final-verify') {
-      return {
-        startEpoch,
-        completed: await this.completeProtocolV2FinalVerification(startEpoch),
-      };
-    }
-    return { startEpoch };
-  }
-
-  private async getProtocolV2DeviceFeatures(): Promise<Features> {
-    if (this.device.features) {
-      return this.device.features;
-    }
-    if (typeof this.device.getFeatures === 'function') {
-      const features = await this.device.getFeatures();
-      if (features) return features;
-    }
-    throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, 'Device features not available');
-  }
-
-  private prepareBootloaderBinary(): ArrayBuffer | null {
-    return this.params.bootloaderBinary ?? null;
-  }
-
-  private hasExplicitProtocolV2Payload(fwBinaryMap: ProtocolV2TargetBinary[]) {
-    return (
-      !!this.params.resourceBundleFiles?.length ||
-      !!this.params.bootloaderBinary ||
-      fwBinaryMap.length > 0
-    );
-  }
-
-  private buildProtocolV2InstallItems({
-    bootloaderBinary,
-    fwBinaryMap,
-  }: {
-    bootloaderBinary: ArrayBuffer | null;
-    fwBinaryMap: ProtocolV2TargetBinary[];
-  }): ProtocolV2InstallItem[] {
-    const installItems: ProtocolV2InstallItem[] = [];
-
-    if (bootloaderBinary) {
-      installItems.push({
-        fileName: 'bootloader.bin',
-        binary: bootloaderBinary,
-        targetId: ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_BOOTLOADER,
-        kind: 'bootloader',
-      });
-    }
-
-    installItems.push(...fwBinaryMap.map(item => ({ ...item, kind: 'firmware' as const })));
-    return installItems;
-  }
-
-  private getRemoteComponentEntries(release: IFirmwareReleaseInfo) {
-    const { components } = release;
-    if (!components) return [];
-
-    const orderedKeys = [
-      ...(release.installOrder ?? []),
-      ...Object.keys(components).filter(key => !release.installOrder?.includes(key)),
-    ];
-
-    return orderedKeys
-      .map(key => {
-        const component = components[key];
-        return component ? ([key, component] as const) : undefined;
-      })
-      .filter((entry): entry is readonly [string, IProtocolV2FirmwareComponent] => !!entry);
-  }
-
-  private getRemoteComponentTarget(key: string, component: IProtocolV2FirmwareComponent) {
-    const targetName = component.target?.toUpperCase();
-    if (targetName === 'ROMLOADER') {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE
-      );
-    }
-    const target = PROTOCOL_V2_REMOTE_COMPONENT_TARGETS[targetName];
-    if (!target) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `Unsupported Protocol V2 firmware component target: ${key}/${component.target}`
-      );
-    }
-    return target;
-  }
-
-  private getProtocolV2ResourceFilePath(path: string) {
-    if (path.startsWith('vol')) return path;
-    if (path.startsWith('/')) return `vol0:${path}`;
-    return `vol0:/${path}`;
-  }
-
-  private async readProtocolV2DeviceFileHeader(path: string) {
-    const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
-    const filePath = this.getProtocolV2ResourceFilePath(path);
-    const pathInfoRes = await typedCall('FilesystemPathInfoQuery', 'FilesystemPathInfo', {
-      path: filePath,
-    });
-    const fileSize = toProtocolV2FiniteNumber(pathInfoRes.message?.size);
-    if (
-      !pathInfoRes.message?.exist ||
-      pathInfoRes.message?.directory ||
-      fileSize === undefined ||
-      fileSize < PROTOCOL_V2_OKPP_HEADER_SIZE
-    ) {
-      return null;
-    }
-
-    const chunkSize = this.getProtocolV2FirmwareChunkSize();
-    const chunks: Uint8Array[] = [];
-    let offset = 0;
-    while (offset < PROTOCOL_V2_OKPP_HEADER_SIZE) {
-      const readLen = Math.min(chunkSize, PROTOCOL_V2_OKPP_HEADER_SIZE - offset);
-      const res = await typedCall('FilesystemFileRead', 'FilesystemFile', {
-        file: {
-          path: filePath,
-          offset,
-          total_size: 0,
-        },
-        chunk_len: readLen,
-        ui_percentage: undefined,
-      });
-      const data = toProtocolV2Bytes(res.message?.data);
-      if (data.byteLength === 0) return null;
-      chunks.push(data);
-      offset += data.byteLength;
-    }
-
-    const headerBytes = new Uint8Array(offset);
-    let cursor = 0;
-    chunks.forEach(chunk => {
-      headerBytes.set(chunk, cursor);
-      cursor += chunk.byteLength;
-    });
-    return parseProtocolV2OkppHeader(headerBytes);
-  }
-
-  private async downloadRemoteProtocolV2Component(
-    key: string,
-    component: IProtocolV2FirmwareComponent
-  ): Promise<ProtocolV2RemoteComponentBinary> {
-    const target = this.getRemoteComponentTarget(key, component);
-    if (!component.url) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `Missing Protocol V2 firmware component url: ${key}/${component.target}`
-      );
-    }
-
-    const { binary } = await getSysResourceBinary(component.url);
-    return {
-      ...target,
-      binary,
-    };
-  }
-
-  private async prepareRemoteProtocolV2Binaries(firmwareType: EFirmwareType, features: Features) {
-    const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
-
-    let bootloaderBinary: ArrayBuffer | null = null;
-    const fwBinaryMap: ProtocolV2TargetBinary[] = [];
-    const installItems: ProtocolV2InstallItem[] = [];
-
-    if (!release) {
-      return {
-        bootloaderBinary,
-        fwBinaryMap,
-        installItems,
-      };
-    }
-
-    const entries = this.getRemoteComponentEntries(release);
-    const targetsToUpdate = new Set(this.params.targetsToUpdate ?? []);
-
-    for (const [key, component] of entries) {
-      const target = this.getRemoteComponentTarget(key, component);
-      const updateTarget = PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(target.targetId);
-      const shouldInstall = updateTarget ? targetsToUpdate.has(updateTarget) : false;
-      if (shouldInstall) {
-        const remoteBinary = await this.downloadRemoteProtocolV2Component(key, component);
-        if (remoteBinary.kind === 'bootloader') {
-          bootloaderBinary = remoteBinary.binary;
-          installItems.push({
-            fileName: remoteBinary.fileName,
-            binary: remoteBinary.binary,
-            targetId: remoteBinary.targetId,
-            kind: remoteBinary.kind,
-          });
-        } else {
-          const binaryEntry = {
-            fileName: remoteBinary.fileName,
-            binary: remoteBinary.binary,
-            targetId: remoteBinary.targetId,
-          };
-          fwBinaryMap.push(binaryEntry);
-          installItems.push({ ...binaryEntry, kind: remoteBinary.kind });
-        }
-      }
-    }
-
-    return {
-      bootloaderBinary,
-      fwBinaryMap,
-      installItems,
-    };
-  }
-
-  // ============================================================
-  // Incremental RESC bundle sync through FileRead and FilesystemFileWrite
-  // ============================================================
-
-  /**
-   * Prepare the RESC bundle list.
-   *
-   * Two modes, matching FirmwareUpdateV3 binary-versus-version behavior:
-   * - resourceBundleFiles supplied: use binaries directly without version checks.
-   * - Otherwise load release.resourceBundles from remote config.json; synchronization
-   *   downloads on demand and skips bundles whose device header already matches.
-   */
-  private prepareProtocolV2ResourceBundles(
-    firmwareType: EFirmwareType,
-    features: Features
-  ): ProtocolV2ResourceBundleBinary[] | undefined {
-    // Manual binaries are installed directly without comparison.
-    if (this.params.resourceBundleFiles?.length) {
-      return this.params.resourceBundleFiles.map(file => ({
-        name: file.devicePath.split('/').pop() ?? file.devicePath,
-        binary: file.binary,
-        devicePath: file.devicePath,
-      }));
-    }
-
-    if (!this.params.targetsToUpdate?.includes('resource')) {
-      return undefined;
-    }
-
-    // Remote-config bundles are downloaded and compared later.
-    const release = DataManager.getFirmwareLatestRelease(features, firmwareType);
-    if (!release?.resourceBundles?.length) return undefined;
-
-    return release.resourceBundles.map(bundle => ({
-      name: bundle.name,
-      binary: new ArrayBuffer(0),
-      devicePath: bundle.devicePath,
-      url: bundle.url,
-      version: bundle.version,
-      payloadHash: bundle.payloadHash,
-      headerHash: bundle.headerHash,
-    })) as ProtocolV2ResourceBundleBinary[];
-  }
-
-  private async materializeProtocolV2ResourceBundles(
-    bundles: ProtocolV2ResourceBundleBinary[]
-  ): Promise<ProtocolV2ResourceBundleBinary[]> {
-    for (const bundle of bundles) {
-      if (bundle.binary.byteLength === 0 && bundle.url) {
-        if (
-          this.params.artifactReader ||
-          DataManager.getSettings('firmwareManifestMode') === 'external-only'
-        ) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.RuntimeError,
-            `Firmware resource bundle ${bundle.name} is not prepared`,
-            {
-              firmwareUpdateCode: 'FirmwareArtifactsNotPrepared',
-              artifactName: bundle.name,
-            }
-          );
-        }
-        Log.log(`[FirmwareUpdateV4] preloading RESC bundle ${bundle.name}`);
-        bundle.binary = (await getSysResourceBinary(bundle.url)).binary;
-      }
-      if (bundle.binary.byteLength === 0) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.FirmwareUpdateDownloadFailed,
-          `Firmware resource bundle ${bundle.name} is empty`
-        );
-      }
-    }
-    return bundles;
-  }
-
-  /**
-   * Compare the existing okpkg OKPP header in remote-config mode.
-   */
-  private async isProtocolV2ResourceBundleUpToDate(
-    bundle: Pick<
-      ProtocolV2ResourceBundleBinary,
-      'name' | 'devicePath' | 'version' | 'payloadHash' | 'headerHash'
-    >
-  ): Promise<boolean> {
-    if (this.params?.forcedUpdateRes) return false;
-    if (!bundle.version && !bundle.payloadHash) return false;
-
-    try {
-      const header = await this.readProtocolV2DeviceFileHeader(bundle.devicePath);
-      if (!header) return false;
-
-      if (bundle.version) {
-        const cmp = compareProtocolV2Versions(header.version, bundle.version);
-        if (cmp === undefined || cmp !== 0) return false;
-      }
-      if (bundle.payloadHash) {
-        const expected = normalizeProtocolV2Hex(bundle.payloadHash);
-        if (expected && header.payloadHash !== expected) return false;
-      }
-      if (bundle.headerHash) {
-        const expected = normalizeProtocolV2Hex(bundle.headerHash);
-        if (expected && header.headerHash !== expected) return false;
-      }
-      return true;
-    } catch (error) {
-      Log.log(`[FirmwareUpdateV4] RESC bundle ${bundle.name} header check failed: `, error);
-      return false;
-    }
-  }
-
-  private isProtocolV2BootloaderMode() {
-    if (typeof this.device.isBootloader === 'function') {
-      return this.device.isBootloader();
-    }
-    return !!this.device.features?.bootloaderMode;
-  }
-
-  async enterProtocolV2BootloaderMode(epoch?: number) {
-    // romloader is the first update environment and forwards targets to bootloader.
-    // It rejects DeviceRebootType.Bootloader, so reuse the current connection.
-    if (this.isProtocolV2BootloaderMode() || this.device.features?.mode === 'romloader') {
-      Log.debug('Protocol V2 device is already in loader mode, skip reboot to bootloader');
-      this.protocolV2ExecutionInLoader = true;
-      return false;
-    }
-
-    try {
-      this.postTipMessage(FirmwareUpdateTipMessage.AutoRebootToBootloader);
-      await this.checkpointWriter?.commit({
-        stage: 'BEFORE_DEVICE_MODE_CHANGE',
-        target: 'bootloader',
-        ...(epoch !== undefined ? { epoch } : {}),
-      });
-      await this.protocolV2Reboot(DeviceRebootType.Bootloader);
-      this.postTipMessage(FirmwareUpdateTipMessage.GoToBootloaderSuccess);
-      await wait(1000);
-      await this.waitForProtocolV2BootloaderMode();
-      this.protocolV2ExecutionInLoader = true;
-      return true;
-    } catch (error) {
-      if (error instanceof HardwareError) {
-        throw error;
-      }
-      Log.log('Protocol V2 auto go to bootloader mode failed: ', error);
-      throw ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure);
-    }
-  }
-
-  private async waitForProtocolV2BootloaderMode(
-    timeout = PROTOCOL_V2_BOOTLOADER_RECONNECT_TIMEOUT,
-    retryInterval = 1000
-  ) {
-    const startTime = Date.now();
-    let lastError: unknown;
-
-    while (Date.now() - startTime < timeout) {
-      try {
-        await this.reconnectProtocolV2Device();
-        const deviceInfo = await requestProtocolV2DeviceInfo({
-          commands: this.device.getCommands(),
-          timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
-        });
-        // This is a reconnect probe after a Bootloader reboot. Bootloader does not
-        // support DeviceStatusGet, so the generic runtime-mode probe is invalid here.
-        const features = this.device.updateProtocolV2Features(deviceInfo, null, 'bootloader');
-        assertProtocolV2ReconnectIdentity(
-          this.protocolV2ExpectedDeviceId,
-          features.deviceId ?? undefined,
-          { allowMissingActual: !!features.bootloaderMode }
-        );
-        if (features?.bootloaderMode) {
-          return features;
-        }
-        lastError = new Error('Protocol V2 device is reachable but is not in bootloader mode');
-      } catch (error) {
-        lastError = error;
-        Log.log('Protocol V2 bootloader mode not ready, polling reconnect: ', error);
-      }
-      await wait(retryInterval);
-    }
-
-    throw ERRORS.TypedError(
-      HardwareErrorCode.FirmwareUpdateAutoEnterBootFailure,
-      `Protocol V2 bootloader not ready within ${timeout / 1000}s: ${this.normalizeErrorMessage(
-        lastError
-      )}`
-    );
-  }
-
-  /**
-   * Collect explicit target binaries grouped by DeviceFirmwareTargetType.
-   * Filenames are display-only staging paths because target_id is explicit.
-   */
-  private collectExplicitTargetBinaries() {
-    const entries: ProtocolV2TargetBinary[] = [];
-    const push = (binary: ArrayBuffer | undefined, fileName: string, targetId: number) => {
-      if (binary) entries.push({ fileName, binary, targetId });
-    };
-
-    if (this.params.romloaderBinary) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        PROTOCOL_V2_ROMLOADER_UNSUPPORTED_MESSAGE
-      );
-    }
-    push(
-      this.params.applicationP1Binary,
-      'application_p1.bin',
-      ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P1
-    );
-    push(
-      this.params.applicationP2Binary,
-      'application_p2.bin',
-      ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_APPLICATION_P2
-    );
-    push(
-      this.params.coprocessorBinary,
-      'coprocessor.bin',
-      ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_COPROCESSOR
-    );
-    push(this.params.se01Binary, 'se01.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE01);
-    push(this.params.se02Binary, 'se02.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE02);
-    push(this.params.se03Binary, 'se03.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE03);
-    push(this.params.se04Binary, 'se04.bin', ProtocolV2FirmwareTargetType.FW_MGMT_TARGET_SE04);
-    return entries;
-  }
-
-  private buildProtocolV2ExecutionEpochs({
-    installSources,
-    resourceSources,
-  }: {
-    installSources: ProtocolV2InstallSource[];
-    resourceSources: ProtocolV2ResourceBundleSource[];
-  }): ProtocolV2ExecutionEpoch[] {
-    const targetById = new Map(
-      Array.from(PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.entries()).map(([id, target]) => [
-        id,
-        target,
-      ])
-    );
-    const targets = [
-      ...installSources.flatMap(source => {
-        const target = targetById.get(source.targetId);
-        return target ? [target] : [];
-      }),
-      ...(resourceSources.length > 0 ? (['resource'] as const) : []),
-    ];
-    return compileFirmwareUpdateEpochKinds({ executor: 'v4', targets }).map((kind, epoch) => {
-      let epochInstallSources: ProtocolV2InstallSource[] = [];
-      if (kind === 'bootloader-install') {
-        epochInstallSources = installSources.filter(source => source.kind === 'bootloader');
-      } else if (kind === 'component-install') {
-        epochInstallSources = installSources.filter(source => source.kind !== 'bootloader');
-      }
-      return {
-        epoch,
-        kind,
-        installSources: epochInstallSources,
-        resourceSources: kind === 'resource-sync' ? resourceSources : [],
-      };
-    });
-  }
-
-  private async executeProtocolV2Epochs({
-    installSources,
-    resourceSources,
-    startEpoch,
-  }: {
-    installSources: ProtocolV2InstallSource[];
-    resourceSources: ProtocolV2ResourceBundleSource[];
-    startEpoch: number;
-  }) {
-    const epochs = this.buildProtocolV2ExecutionEpochs({
-      installSources,
-      resourceSources,
-    });
-    if (startEpoch < 0 || startEpoch >= epochs.length) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        'Protocol V2 execution epoch is invalid',
-        {
-          firmwareUpdateCode: 'FirmwareTransactionConflict',
-        }
-      );
-    }
-    for (const epoch of epochs.slice(startEpoch)) {
-      if (epoch.kind === 'final-verify') {
-        return this.completeProtocolV2FinalVerification(epoch.epoch);
-      }
-      await this.checkpointWriter?.commit({
-        stage: 'EPOCH_STARTED',
-        target: epoch.kind,
-        epoch: epoch.epoch,
-      });
-      if (epoch.kind === 'resource-sync') {
-        await this.enterProtocolV2BootloaderMode(epoch.epoch);
-        await this.executeProtocolV2TransferEpoch(epoch);
-      } else if (epoch.kind === 'bootloader-install' || epoch.kind === 'component-install') {
-        await this.enterProtocolV2BootloaderMode(epoch.epoch);
-        await this.executeProtocolV2TransferEpoch(epoch);
-        await this.exitProtocolV2BootloaderToNormal(epoch.epoch);
-      } else if (epoch.kind === 'bootloader-verify') {
-        await this.waitForProtocolV2FinalFeatures();
-        this.assertExpectedProtocolV2Versions(['boot']);
-      }
-      await this.checkpointWriter?.commit({
-        stage: 'EPOCH_COMPLETED',
-        target: epoch.kind,
-        epoch: epoch.epoch,
-      });
-    }
-    throw ERRORS.TypedError(
-      HardwareErrorCode.RuntimeError,
-      'Protocol V2 execution has no final verification epoch'
-    );
-  }
-
-  private async executeProtocolV2SourceUpdate({
-    installSources,
-    resourceSources,
-    startEpoch = 0,
-  }: {
-    installSources: ProtocolV2InstallSource[];
-    resourceSources: ProtocolV2ResourceBundleSource[];
-    startEpoch?: number;
-  }) {
-    return this.executeProtocolV2Epochs({
-      installSources,
-      resourceSources,
-      startEpoch,
-    });
-  }
-
-  private async executeProtocolV2Update(
-    {
-      fwBinaryMap,
-      bootloaderBinary,
-      installItems,
-      resourceBundles,
-    }: {
-      fwBinaryMap?: ProtocolV2TargetBinary[];
-      bootloaderBinary?: ArrayBuffer | null;
-      installItems?: ProtocolV2InstallItem[];
-      resourceBundles?: ProtocolV2ResourceBundleBinary[];
-    },
-    startEpoch = 0
-  ) {
-    const memoryInstallItems =
-      installItems ??
-      this.buildProtocolV2InstallItems({
-        fwBinaryMap: fwBinaryMap ?? [],
-        bootloaderBinary: bootloaderBinary ?? null,
-      });
-    try {
-      const installSources = await Promise.all(
-        memoryInstallItems.map(async item => ({
-          fileName: item.fileName,
-          source: await this.openProtocolV2MemorySource(item.binary),
-          targetId: item.targetId,
-          kind: item.kind,
-        }))
-      );
-      const resourceSources = await Promise.all(
-        (resourceBundles ?? []).map(async bundle => ({
-          name: bundle.name,
-          source: await this.openProtocolV2MemorySource(bundle.binary),
-          devicePath: bundle.devicePath,
-          version: bundle.version,
-          payloadHash: bundle.payloadHash,
-          headerHash: bundle.headerHash,
-        }))
-      );
-      return await this.executeProtocolV2Epochs({
-        installSources,
-        resourceSources,
-        startEpoch,
-      });
-    } finally {
-      await this.closeProtocolV2PreparedSources();
-    }
-  }
-
-  private async executeProtocolV2TransferEpoch({
-    epoch,
-    installSources,
-    resourceSources,
-  }: ProtocolV2ExecutionEpoch) {
-    let totalSize = installSources.reduce((total, item) => total + item.source.size, 0);
-    const resourcesToSync: ProtocolV2ResourceBundleSource[] = [];
-    for (const resource of resourceSources) {
-      if (await this.isProtocolV2ResourceBundleUpToDate(resource)) {
-        Log.log(`[FirmwareUpdateV4] skip RESC bundle ${resource.name}; already up to date`);
-      } else {
-        resourcesToSync.push(resource);
-        totalSize += resource.source.size;
-      }
-    }
-
-    this.postTipMessage(FirmwareUpdateTipMessage.StartTransferData);
-    let processedSize = 0;
-    for (const resource of resourcesToSync) {
-      const checkpointTarget = `resource:${resource.name}`;
-      await this.checkpointWriter?.commit({
-        stage: 'FILE_TRANSFER_STARTED',
-        target: checkpointTarget,
-        epoch,
-      });
-      processedSize = await this.protocolV2SourceUpdateProcess({
-        source: resource.source,
-        filePath: resource.devicePath,
-        processedSize,
-        totalSize,
-      });
-      await this.verifyProtocolV2StagedFile(resource.devicePath, resource.source.size);
-      await this.checkpointWriter?.commit({
-        stage: 'FILE_TRANSFER_COMPLETED',
-        target: checkpointTarget,
-        epoch,
-      });
-    }
-
-    const stagedInstallTargets: Array<{ targetId: number; path: string }> = [];
-    for (const item of installSources) {
-      const filePath = this.getProtocolV2InstallItemStagingPath(item);
-      const checkpointTarget =
-        PROTOCOL_V2_UPDATE_TARGET_BY_TARGET_ID.get(item.targetId) ?? `target:${item.targetId}`;
-      await this.checkpointWriter?.commit({
-        stage: 'FILE_TRANSFER_STARTED',
-        target: checkpointTarget,
-        epoch,
-      });
-      processedSize = await this.protocolV2SourceUpdateProcess({
-        source: item.source,
-        filePath,
-        processedSize,
-        totalSize,
-      });
-      await this.verifyProtocolV2StagedFile(filePath, item.source.size);
-      await this.checkpointWriter?.commit({
-        stage: 'FILE_TRANSFER_COMPLETED',
-        target: checkpointTarget,
-        epoch,
-      });
-      stagedInstallTargets.push({
-        targetId: item.targetId,
-        path: filePath,
-      });
-    }
-
-    if (totalSize > 0) {
-      this.postProgressMessage(100, 'transferData');
-    }
-    if (stagedInstallTargets.length === 0) {
-      return;
-    }
-
-    this.postTipMessage(FirmwareUpdateTipMessage.ConfirmOnDevice);
-    const targets = stagedInstallTargets.map(item => ({
-      target_id: item.targetId,
-      path: item.path,
-    }));
-    await this.protocolV2StartFirmwareUpdate({ targets, epoch });
-    await this.waitForProtocolV2FirmwareUpdateComplete(targets);
-  }
-
-  private async protocolV2SourceUpdateProcess({
-    source,
-    filePath,
-    processedSize,
-    totalSize,
-  }: {
-    source: FirmwareByteSource;
-    filePath: string;
-    processedSize: number;
-    totalSize: number;
-  }) {
-    let lastError: unknown;
-    for (let attempt = 1; attempt <= PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT; attempt += 1) {
-      try {
-        await writeFirmwareByteSource({
-          source,
-          chunkSize: this.getProtocolV2FirmwareChunkSize(),
-          write: async ({ data, sourceOffset, length, first }) => {
-            const chunkEnd = sourceOffset + length;
-            const progress = getProtocolV2DeviceTransferProgress(
-              processedSize + sourceOffset,
-              processedSize + chunkEnd,
-              totalSize
-            );
-            const response = await this.fileWriteChunk(
-              filePath,
-              source.size,
-              sourceOffset,
-              data,
-              first,
-              progress
-            );
-            const rawProcessedByte = response.message.processed_byte;
-            const nextOffset = rawProcessedByte === undefined ? chunkEnd : Number(rawProcessedByte);
-            if (!Number.isFinite(nextOffset) || nextOffset !== chunkEnd) {
-              throw ERRORS.TypedError(
-                HardwareErrorCode.EmmcFileWriteFirmwareError,
-                `invalid processed_byte ${rawProcessedByte} for offset ${sourceOffset}`
-              );
-            }
-            this.postProgressMessage(progress, 'transferData');
-            return length;
-          },
-        });
-        return processedSize + source.size;
-      } catch (error) {
-        lastError = error;
-        if (attempt < PROTOCOL_V2_FILE_TRANSFER_RETRY_COUNT) {
-          await this.recoverProtocolV2FileTransfer();
-        }
-      }
-    }
-    throw ERRORS.TypedError(
-      HardwareErrorCode.EmmcFileWriteFirmwareError,
-      `transfer data error: ${getProtocolV2UnknownErrorText(lastError)}`
-    );
-  }
-
-  private getProtocolV2InstallItemStagingPath(item: Pick<ProtocolV2InstallItem, 'fileName'>) {
-    return `${PROTOCOL_V2_FIRMWARE_STAGING_VOLUME}${item.fileName}`;
-  }
-
-  private async verifyProtocolV2StagedFile(path: string, expectedSize: number) {
-    const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
-    const response = await typedCall('FilesystemPathInfoQuery', 'FilesystemPathInfo', { path });
-    const actualSize = toProtocolV2FiniteNumber(response.message?.size);
-    if (!response.message?.exist || response.message?.directory || actualSize !== expectedSize) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.EmmcFileWriteFirmwareError,
-        `staged file verification failed: path=${path} exist=${!!response.message
-          ?.exist} expected=${expectedSize} actual=${actualSize ?? 'unknown'}`
-      );
-    }
-  }
-
-  private assertProtocolV2TargetStatus(
-    statusTargets: ProtocolV2FirmwareUpdateStatusTarget[],
-    expectedTargetIds: Set<number>,
-    expectedPaths = new Map<number, string>()
-  ) {
-    Log.log(
-      `[FirmwareUpdateV4] DeviceFirmwareUpdateStatus records=${JSON.stringify(statusTargets)}`
-    );
-    const failedTarget = statusTargets.find(
-      target =>
-        expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1) &&
-        isProtocolV2TargetStatusFailed(target.status)
-    );
-    if (failedTarget) {
-      const failedTargetDetails = JSON.stringify({
-        targetId: failedTarget.target_id,
-        status: failedTarget.status,
-        payloadVersion: failedTarget.payload_version,
-        path: failedTarget.path,
-      });
-      Log.error(`[FirmwareUpdateV4] firmware install failed target=${failedTargetDetails}`);
-      throw ERRORS.TypedError(
-        HardwareErrorCode.FirmwareError,
-        `Protocol V2 firmware target failed: target=${failedTarget.target_id} status=${
-          failedTarget.status ?? 'unknown'
-        } payloadVersion=${failedTarget.payload_version ?? 'unknown'} path=${
-          failedTarget.path ?? 'unknown'
-        }`
-      );
-    }
-
-    const matchingTargets = statusTargets.filter(target =>
-      expectedTargetIds.has(normalizeProtocolV2TargetId(target.target_id) ?? -1)
-    );
-    const seenTargetIds = new Set<number>();
-    for (const target of matchingTargets) {
-      const targetId = normalizeProtocolV2TargetId(target.target_id);
-      if (
-        targetId === undefined ||
-        seenTargetIds.has(targetId) ||
-        (target.path && expectedPaths.get(targetId) && target.path !== expectedPaths.get(targetId))
-      ) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          `Protocol V2 install status conflicts with target ${target.target_id}`,
-          {
-            firmwareUpdateCode: 'FirmwareTransactionConflict',
-          }
-        );
-      }
-      seenTargetIds.add(targetId);
-    }
-    const completedTargets = matchingTargets.filter(target =>
-      isProtocolV2TargetStatusFinished(target.status)
-    );
-    if (completedTargets.length === expectedTargetIds.size && expectedTargetIds.size > 0) {
-      for (const target of completedTargets) {
-        const targetId = normalizeProtocolV2TargetId(target.target_id);
-        const payloadVersion = toProtocolV2FiniteNumber(target.payload_version);
-        if (targetId === undefined) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.RuntimeError,
-            'Protocol V2 completed target identity is invalid',
-            {
-              firmwareUpdateCode: 'FirmwareTransactionConflict',
-            }
-          );
-        }
-        const expectedVersion = this.getExpectedProtocolV2TargetVersion(targetId);
-        if (expectedVersion !== undefined && payloadVersion !== undefined) {
-          if (payloadVersion !== expectedVersion) {
-            throw ERRORS.TypedError(
-              HardwareErrorCode.FirmwareVerificationFailed,
-              `Protocol V2 target ${targetId} reached payload version ${payloadVersion}, expected ${expectedVersion}`,
-              {
-                firmwareUpdateCode: 'FirmwareTransactionConflict',
-              }
-            );
-          }
-        }
-        if (payloadVersion !== undefined) {
-          this.protocolV2CompletedTargetVersions.set(targetId, payloadVersion);
-        }
-      }
-      this.postProgressMessage(100, 'installingFirmware');
-      return true;
-    }
-
-    if (expectedTargetIds.size > 0 && matchingTargets.length > 0) {
-      const hasInProgressTarget = matchingTargets.some(target =>
-        isProtocolV2TargetStatusInProgress(target.status)
-      );
-      const completedProgress = Math.floor(
-        (completedTargets.length / expectedTargetIds.size) * 100
-      );
-      // The protocol exposes no per-target percentage, so report coarse progress by
-      // completed targets and use 1% once work starts to keep the UI responsive.
-      const progress = Math.min(99, Math.max(completedProgress, hasInProgressTarget ? 1 : 0));
-      this.postProgressMessage(progress, 'installingFirmware');
-    }
-
-    return false;
-  }
-
-  private async waitForProtocolV2FirmwareUpdateComplete(
-    targets: Array<{ target_id: number; path: string }>,
-    { recovery = false }: { recovery?: boolean } = {}
-  ) {
-    const expectedTargetIds = new Set(targets.map(target => target.target_id));
-    const expectedPaths = new Map(targets.map(target => [target.target_id, target.path]));
-    const startTime = Date.now();
-    const timeout = recovery ? 15 * 1000 : PROTOCOL_V2_INSTALL_TIMEOUT;
-    let lastError: unknown;
-
-    while (Date.now() - startTime < timeout) {
-      try {
-        await this.reconnectProtocolV2Device();
-        try {
-          const statusResponse = await this.device.getCommands().typedCall(
-            'DeviceFirmwareUpdateStatusGet',
-            'DeviceFirmwareUpdateStatus',
-            {
-              fields: {
-                status: true,
-                payload_version: true,
-                path: true,
-              },
-            },
-            { timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT }
-          );
-          if (
-            this.assertProtocolV2TargetStatus(
-              (statusResponse.message.records ?? []) as ProtocolV2FirmwareUpdateStatusTarget[],
-              expectedTargetIds,
-              expectedPaths
-            )
-          ) {
-            return;
-          }
-          lastError = new Error('Protocol V2 firmware targets are still installing');
-        } catch (error) {
-          if (
-            error instanceof HardwareError &&
-            error.errorCode === HardwareErrorCode.FirmwareError
-          ) {
-            throw error;
-          }
-          // App firmware does not register DeviceFirmwareUpdateStatusGet. If the
-          // device already rebooted into App, this endpoint error signals that the
-          // install phase ended; the later phase performs the final readiness check.
-          if (isProtocolV2FirmwareStatusEndpointUnavailable(error)) {
-            try {
-              const deviceInfo = await requestProtocolV2DeviceInfo({
-                commands: this.device.getCommands(),
-                timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
-              });
-              const observed = await this.device.probeProtocolV2RuntimeState(
-                deviceInfo,
-                PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT
-              );
-              assertProtocolV2ReconnectIdentity(
-                this.protocolV2ExpectedDeviceId,
-                observed.deviceId ?? undefined
-              );
-              if (observed.mode === 'normal' && !observed.bootloaderMode) {
-                return;
-              }
-              lastError = new Error(
-                'Protocol V2 status endpoint is unavailable outside normal mode'
-              );
-            } catch (probeError) {
-              lastError = probeError;
-            }
-            throw ERRORS.TypedError(
-              HardwareErrorCode.RuntimeError,
-              `Protocol V2 firmware install status is unavailable: ${this.normalizeErrorMessage(
-                lastError
-              )}`,
-              {
-                firmwareUpdateCode: 'FirmwareReconciliationUnavailable',
-              }
-            );
-          }
-          lastError = error;
-          Log.log(
-            '[FirmwareUpdateV4] DeviceFirmwareUpdateStatusGet unavailable during install: ',
-            error
-          );
-        }
-      } catch (error) {
-        lastError = error;
-        if (error instanceof HardwareError && error.errorCode === HardwareErrorCode.FirmwareError) {
-          throw error;
-        }
-        if (
-          error instanceof HardwareError &&
-          error.params?.firmwareUpdateCode === 'FirmwareReconciliationUnavailable'
-        ) {
-          throw error;
-        }
-        Log.log('Protocol V2 firmware install device readiness probe failed: ', error);
-      }
-      await wait(1000);
-    }
-
-    throw ERRORS.TypedError(
-      HardwareErrorCode.RuntimeError,
-      `Protocol V2 firmware update status timeout: ${this.normalizeErrorMessage(lastError)}`,
-      recovery
-        ? {
-            firmwareUpdateCode: 'FirmwareReconciliationUnavailable',
-          }
-        : undefined
-    );
-  }
-
-  private async exitProtocolV2BootloaderToNormal(epoch?: number) {
-    await this.reconnectProtocolV2Device();
-    // The connection may still be in bootloader. Request a Normal reboot directly;
-    // repeating it after an automatic App reboot is idempotent.
-    await this.checkpointWriter?.commit({
-      stage: 'BEFORE_DEVICE_MODE_CHANGE',
-      target: 'normal',
-      ...(epoch !== undefined ? { epoch } : {}),
-    });
-    await this.protocolV2Reboot(DeviceRebootType.Normal);
-    this.protocolV2ExecutionInLoader = false;
-  }
-
-  private async waitForProtocolV2FinalFeatures() {
-    const features = await this.waitForProtocolV2ReconnectAndFeatures(
-      PROTOCOL_V2_FINAL_RECONNECT_TIMEOUT
-    );
-
-    const bootloaderVersion = getDeviceBootloaderVersion(features).join('.');
-    const bleVersion = getDeviceBLEFirmwareVersion(features).join('.');
-    const firmwareVersion = getDeviceFirmwareVersion(features).join('.');
-    this.protocolV2LatestFinalFeatures = features;
-    if (firmwareVersion === '0.0.0') {
-      Log.warn(
-        'Protocol V2 firmware update finished but app firmware version is still 0.0.0. This is allowed for Pro2 debug BLE-only update flows.'
-      );
-    }
-
-    return {
-      bootloaderVersion,
-      bleVersion,
-      firmwareVersion,
-    };
-  }
-
-  private async completeProtocolV2FinalVerification(epoch: number) {
-    if (this.protocolV2ExecutionInLoader || this.isProtocolV2BootloaderMode()) {
-      await this.exitProtocolV2BootloaderToNormal(epoch);
-    }
-    const versions = await this.waitForProtocolV2FinalFeatures();
-    this.assertExpectedProtocolV2Versions();
-    await this.checkpointWriter?.commit({
-      stage: 'FINAL_VERIFIED',
-      target: 'final-verify',
-      epoch,
-    });
-    this.postTipMessage(FirmwareUpdateTipMessage.FirmwareUpdateCompleted);
-    DevicePool.resetState();
-    return versions;
-  }
-
-  private async waitForProtocolV2ReconnectAndFeatures(timeout: number) {
-    const startTime = Date.now();
-    let lastError: unknown;
-
-    while (Date.now() - startTime < timeout) {
-      try {
-        await this.reconnectProtocolV2Device();
-        const deviceInfo = await requestProtocolV2DeviceInfo({
-          commands: this.device.getCommands(),
-          timeoutMs: PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT,
-          // Completion needs target versions only; keep scope aligned with the request.
-          request: PROTOCOL_V2_VERSIONS_DEVICE_INFO_REQUEST,
-        });
-        const features = await this.device.probeProtocolV2RuntimeState(
-          deviceInfo,
-          PROTOCOL_V2_SHORT_RESPONSE_TIMEOUT
-        );
-        assertProtocolV2ReconnectIdentity(
-          this.protocolV2ExpectedDeviceId,
-          features.deviceId ?? undefined
-        );
-        if (features.mode !== 'normal' || features.bootloaderMode) {
-          throw ERRORS.TypedError(
-            HardwareErrorCode.DeviceNotFound,
-            'Protocol V2 device is still in bootloader mode'
-          );
-        }
-        return features;
-      } catch (error) {
-        // A confirmed deviceId change is a firmware contract violation and cannot be
-        // fixed by polling. A temporarily missing identity may still become ready.
-        if (this.isProtocolV2ReconnectIdentityMismatch(error)) {
-          throw error;
-        }
-        lastError = error;
-        Log.log('Protocol V2 normal mode not ready, polling Ping: ', error);
-        await wait(1000);
-      }
-    }
-
-    throw ERRORS.TypedError(
-      HardwareErrorCode.DeviceNotFound,
-      `Protocol V2 final features not ready within ${timeout / 1000}s: ${this.normalizeErrorMessage(
-        lastError
-      )}`
-    );
-  }
-
-  private async reconnectProtocolV2Device() {
-    if (this.isBleReconnect()) {
-      await this.acquireProtocolV2BleDevice();
-      return;
-    }
-
-    const deviceDiff = await this.device.deviceConnector?.enumerate();
-    const devicesDescriptor = deviceDiff?.descriptors ?? [];
-
-    if (
-      DataManager.isBrowserWebUsb(DataManager.getSettings('env')) &&
-      devicesDescriptor.length === 1
-    ) {
-      this.device.updateDescriptor(
-        {
-          ...devicesDescriptor[0],
-          protocolType: PROTOCOL_V2_CONNECT_PROTOCOL,
-        },
-        true
-      );
-      await this.ensureProtocolV2DeviceAcquired();
-      this.device.commands.disposed = false;
-      this.device.getCommands().mainId = this.device.mainId ?? '';
-      assertProtocolV2ReconnectIdentity(
-        this.protocolV2ExpectedDeviceId,
-        this.device.getCurrentDeviceId(),
-        // Cached identity may be absent immediately after acquire. Reject only an
-        // existing mismatch; the final refresh performs strict identity validation.
-        { allowMissingActual: true }
-      );
-      return;
-    }
-
-    // App and bootloader serials may differ temporarily. During V4 reconnect, accept
-    // only a uniquely enumerated device instead of repeatedly using the old App path.
-    const { deviceList } = await DevicePool.getDevices(devicesDescriptor, undefined, {
-      connectProtocol: PROTOCOL_V2_CONNECT_PROTOCOL,
-    });
-    if (deviceList.length !== 1) {
-      throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound);
-    }
-
-    Log.debug(
-      'Protocol V2 firmware reconnect using single enumerated device:',
-      deviceList[0].getConnectId()
-    );
-    this.device.updateFromCache(deviceList[0]);
-    await this.ensureProtocolV2DeviceAcquired();
-    this.device.commands.disposed = false;
-    this.device.getCommands().mainId = this.device.mainId ?? '';
-    assertProtocolV2ReconnectIdentity(
-      this.protocolV2ExpectedDeviceId,
-      this.device.getCurrentDeviceId(),
-      // Cached identity may be absent immediately after acquire. Reject only an
-      // existing mismatch; the final refresh performs strict identity validation.
-      { allowMissingActual: true }
-    );
-  }
-
-  /**
-   * After acquiring a USB session, polling reuses its command channel. Reacquire only
-   * after reboot or enumeration changes cause hasDeviceAcquire() to become false.
-   */
-  private async ensureProtocolV2DeviceAcquired() {
-    const commands = this.device.getCommands();
-    if (this.device.hasDeviceAcquire() && !commands.disposed) {
-      return;
-    }
-    await this.device.acquire(PROTOCOL_V2_CONNECT_PROTOCOL, {
-      throwOnRunPromiseError: true,
-    });
-  }
-
-  private isProtocolV2ReconnectIdentityMismatch(error: unknown) {
-    return this.normalizeErrorMessage(error).includes('Protocol V2 reconnect identity mismatch');
-  }
-
-  private async fileWriteChunk(
-    filePath: string,
-    totalFileSize: number,
-    offset: number,
-    chunk: ArrayBuffer | Buffer,
-    overwrite: boolean,
-    progress: number | null
-  ): Promise<TypedResponseMessage<'FilesystemFile'>> {
-    const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
-    const writeRes = await typedCall('FilesystemFileWrite', 'FilesystemFile', {
-      file: {
-        path: filePath,
-        offset,
-        total_size: totalFileSize,
-        data: chunk,
-      },
-      overwrite,
-      append: false,
-      ui_percentage: progress ?? undefined,
-    });
-    if (writeRes.type !== 'FilesystemFile') {
-      if ((writeRes as any).type === 'CallMethodError') {
-        if (((writeRes as any).message.error ?? '').indexOf(SESSION_ERROR) > -1) {
-          throw ERRORS.TypedError(HardwareErrorCode.RuntimeError, SESSION_ERROR);
-        }
-      }
-      throw ERRORS.TypedError(HardwareErrorCode.EmmcFileWriteFirmwareError, 'transfer data error');
-    }
-    return writeRes;
-  }
-
-  private async recoverProtocolV2FileTransfer() {
-    const env = DataManager.getSettings('env');
-    if (DataManager.isBleConnect(env)) {
-      await wait(3000);
-      await this.acquireProtocolV2BleDevice();
-      await this.device.initialize();
-    }
-    await wait(2000);
-  }
-
-  private async acquireProtocolV2BleDevice() {
-    await this.device.deviceConnector?.acquire(
-      this.device.originalDescriptor.id,
-      null,
-      true,
-      PROTOCOL_V2_CONNECT_PROTOCOL
-    );
-  }
-
-  private async protocolV2StartFirmwareUpdate({
-    targets,
-    epoch = 0,
-  }: {
-    targets: Array<{ target_id: number; path: string }>;
-    epoch?: number;
-  }) {
-    const commands = this.device.getCommands();
-    await this.checkpointWriter?.commit({
-      stage: 'INSTALL_REQUESTED',
-      epoch,
-    });
-    const response: ProtocolV2FirmwareUpdateStartResponse = await commands.typedCall(
-      'DeviceFirmwareUpdateRequest',
-      'Success',
-      { targets },
-      { timeoutMs: PROTOCOL_V2_START_UPDATE_TIMEOUT }
-    );
-    await this.checkpointWriter?.commit({
-      stage: 'INSTALL_ACCEPTED',
-      epoch,
-    });
-    // Success acknowledges that the device accepted installation. End confirmation
-    // and begin status polling only after receiving this ACK.
-    this.postTipMessage(FirmwareUpdateTipMessage.FirmwareUpdating);
-    this.postProgressMessage(0, 'installingFirmware');
-    return response;
-  }
-
-  private async protocolV2Reboot(rebootType: DeviceRebootType) {
-    const typedCall = this.device.getCommands().typedCall.bind(this.device.getCommands());
-    try {
-      const res = await typedCall('DeviceReboot', 'Success', {
-        reboot_type: rebootType,
-      });
-      this.device.markProtocolV2Reboot(rebootType);
-      return res.message;
-    } catch (error) {
-      if (isProtocolV2DeviceDisconnectedError(error) || isProtocolV2ReconnectProbeError(error)) {
-        this.device.markProtocolV2Reboot(rebootType);
-        return { message: 'Device rebooted successfully' };
-      }
-      throw error;
-    }
-  }
-
-  private normalizeErrorMessage(error: unknown): string {
-    if (!error) {
-      return '';
-    }
-    return getProtocolV2UnknownErrorText(error);
-  }
-}