react-native-update 10.55.1 → 10.56.1

package/harmony/pushy/src/main/ets/UpdateContext.ts

@@ -25,23 +25,47 @@ import NativePatchCore, {
   StateCoreResult,
 } from './NativePatchCore';
 import { assertSafePathComponent } from './PathUtils';
+import {
+  ERROR_SWITCH_VERSION_FAILED,
+  createUpdateError,
+  getErrorMessage,
+  toUpdateError,
+} from './ErrorCodes';
 
 export { isSafePathComponent } from './PathUtils';
 
-type FlushablePreferences = preferences.Preferences & {
+const TAG = 'UpdateContext';
+// 常规清理保留最近 3 天内触碰过的条目(续传 partial、staging 同样按 mtime)。
+const CLEANUP_MAX_AGE_DAYS = 3;
+
+// Preferences.flushSync 是 API 14 才有、getAllSync 老 SDK 声明里没有:HAR 兼容
+// API 12,按结构化视图探测(不用交叉类型——ArkTS 不支持)。
+interface OptionalPreferencesApi {
   flushSync?: () => void;
-};
+  getAllSync?: () => Record<string, unknown>;
+}
+
+interface PersistOptions {
+  removeStaleHash?: boolean;
+  cleanUp?: boolean;
+  markFirstLoadMarker?: boolean;
+  clearFirstLoadMarker?: boolean;
+}
 
 export class UpdateContext {
   private context: common.UIAbilityContext;
   private rootDir: string;
   private preferences!: preferences.Preferences;
+  // 宿主传入的调试标志(RNOH isDebugModeEnabled)。debug 下 markSuccess 空转、
+  // 不算内嵌 bundle 摘要,与 Android 的 debug 库对齐。HAR 自身没有构建期
+  // DEBUG 信号(hvigor 不为 HAR 生成 BuildProfile),所以只看宿主。
   private static DEBUG: boolean = false;
   private static isUsingBundleUrl: boolean = false;
   private static ignoreRollback: boolean = false;
   // 本进程实际加载的热更版本（getBundleUrl 解析成功时记录）。
   // resetToPackagedBundle 不能删它的目录：热更包内的图片等资源是运行时按需
   // 读盘的，静默（不重启）reset 若删掉会导致后续所有未加载过的资源失败。
+  // 常规清理同样必须保留它:一次进程内两次切换后 current/last 都不再是它。
   private static launchVersion: string = '';
   // 由 resetToPackagedBundle 递增。原生冷启动检测可能跑数分钟并已握有决策,
   // 期间发生的 reset 必须赢:编排器采样该值,发现变化即放弃激活与响应缓存,
@@ -55,7 +79,18 @@ export class UpdateContext {
   private static instanceCounter: number = 0;
   private readonly instanceId: string;
 
-  public static getInstance(context: common.UIAbilityContext): UpdateContext {
+  /**
+   * @param isDebugHost 宿主的调试标志(RNOH isDebugModeEnabled)。bundle
+   *   provider 先于 TurboModule 构造,不传该参数;TurboModule 随后显式传入时
+   *   会重新解析。
+   */
+  public static getInstance(
+    context: common.UIAbilityContext,
+    isDebugHost?: boolean,
+  ): UpdateContext {
+    if (isDebugHost !== undefined) {
+      UpdateContext.DEBUG = isDebugHost;
+    }
     if (!UpdateContext.instance) {
       UpdateContext.instance = new UpdateContext(context);
     }
@@ -72,7 +107,7 @@ export class UpdateContext {
         fileIo.mkdirSync(this.rootDir);
       }
     } catch (e) {
-      console.error('Failed to create root directory:', e);
+      logger.error(TAG, `Failed to create root directory: ${getErrorMessage(e)}`);
     }
     this.initPreferences();
     this.trace('ctor');
@@ -89,7 +124,7 @@ export class UpdateContext {
   private trace(point: string): void {
     const snap = this.getStateSnapshot();
     logger.debug(
-      'UpdateContext',
+      TAG,
       `trace id=${this.instanceId} ${point}` +
         ` pkg=${snap.packageVersion} bt=${snap.buildTime}` +
         ` cv=${snap.currentVersion} lv=${snap.lastVersion}` +
@@ -115,11 +150,15 @@ export class UpdateContext {
       // which disables rollback protection. Rethrow so the failure surfaces at
       // construction time instead of later as an unrelated TypeError on the
       // undefined `preferences` handle.
-      console.error('Failed to init preferences:', e);
+      logger.error(TAG, `Failed to init preferences: ${getErrorMessage(e)}`);
       throw e;
     }
   }
 
+  private optionalPreferencesApi(): OptionalPreferencesApi {
+    return this.preferences as unknown as OptionalPreferencesApi;
+  }
+
   private getBundleFlags(): bundleManager.BundleFlag {
     return bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_REQUESTED_PERMISSION;
   }
@@ -135,7 +174,7 @@ export class UpdateContext {
       UpdateContext.cachedPackageVersion = bundleInfo?.versionName || 'Unknown';
       return UpdateContext.cachedPackageVersion;
     } catch (error) {
-      console.error('Failed to get bundle info:', error);
+      logger.error(TAG, `Failed to get bundle info: ${getErrorMessage(error)}`);
       return '';
     }
   }
@@ -155,7 +194,10 @@ export class UpdateContext {
         return UpdateContext.cachedBuildTime;
       }
     } catch (error) {
-      console.error('Failed to read build time from raw file:', error);
+      logger.error(
+        TAG,
+        `Failed to read build time from raw file: ${getErrorMessage(error)}`,
+      );
     }
     return '';
   }
@@ -213,33 +255,56 @@ export class UpdateContext {
     this.flushBatchDepth += 1;
   }
 
-  private endFlushBatch(reason: string): void {
+  /** 关闭最外层批次时执行唯一一次落盘;返回该次落盘的 promise。 */
+  private endFlushBatch(reason: string): Promise<void> {
     this.flushBatchDepth = Math.max(0, this.flushBatchDepth - 1);
     if (this.flushBatchDepth === 0) {
-      this.flushPreferences(reason);
+      return this.flushPreferences(reason);
     }
+    return Promise.resolve();
   }
 
-  private flushPreferences(reason: string): void {
+  /**
+   * 落盘。flushSync(API 14)可用时同步完成;否则返回 preferences.flush() 的
+   * promise。有 promise 可拒绝的操作(切换、markSuccess、setKv…)必须 await
+   * 它——切换只有真正写进磁盘后才能向 JS 报成功,reloadUpdate 紧接着就会
+   * 杀进程(SR-5,Android 是 persistEditorOrThrow)。无法 await 的同步路径
+   * (启动解析、getConstants)用 flushInBackground,失败只记日志。
+   * 批次开着时不落盘,由 endFlushBatch 统一执行。
+   */
+  private flushPreferences(reason: string): Promise<void> {
     if (this.flushBatchDepth > 0) {
-      return;
+      return Promise.resolve();
     }
-    const flushablePreferences = this.preferences as FlushablePreferences;
-    if (typeof flushablePreferences.flushSync === 'function') {
+    const api = this.optionalPreferencesApi();
+    if (typeof api.flushSync === 'function') {
       try {
-        flushablePreferences.flushSync();
-        return;
+        api.flushSync();
+        return Promise.resolve();
       } catch (error) {
-        console.error(`Failed to flushSync preferences for ${reason}:`, error);
-        // fall through to async flush rather than failing the whole operation
+        logger.error(
+          TAG,
+          `flushSync failed for ${reason}, falling back to flush(): ` +
+            getErrorMessage(error),
+        );
+        // fall through to the async flush rather than failing outright
       }
     }
-    // flushSync unavailable or failed: writes are already applied in memory via
-    // putSync/deleteSync; persist asynchronously as a best-effort so the state
-    // operation still succeeds instead of throwing (which is worse than a
-    // slightly delayed persist).
-    this.preferences.flush().catch((error: Object) => {
-      console.error(`Failed to flush preferences for ${reason}:`, error);
+    return this.preferences.flush().then(
+      () => undefined,
+      (error: Object) => {
+        logger.error(
+          TAG,
+          `Failed to flush preferences for ${reason}: ${getErrorMessage(error)}`,
+        );
+        throw error;
+      },
+    );
+  }
+
+  private flushInBackground(reason: string): void {
+    this.flushPreferences(reason).catch(() => {
+      // 已在 flushPreferences 里记录。
     });
   }
 
@@ -277,19 +342,8 @@ export class UpdateContext {
     this.putNullableString('rolledBackVersion', state.rolledBackVersion);
   }
 
-  private persistState(
-    state: StateCoreResult,
-    options: {
-      clearExisting?: boolean;
-      removeStaleHash?: boolean;
-      cleanUp?: boolean;
-      markFirstLoadMarker?: boolean;
-      clearFirstLoadMarker?: boolean;
-    } = {},
-  ): void {
-    if (options.clearExisting) {
-      this.preferences.clear();
-    }
+  /** 内存写入(不落盘):状态字段 + 可选的陈旧 hash / 首载标记 / 清理。 */
+  private writeState(state: StateCoreResult, options: PersistOptions): void {
     this.applyState(state);
     if (options.removeStaleHash && state.staleVersionToDelete) {
       this.preferences.deleteSync(`hash_${state.staleVersionToDelete}`);
@@ -300,27 +354,31 @@ export class UpdateContext {
     if (options.clearFirstLoadMarker) {
       this.preferences.deleteSync('firstLoadMarked');
     }
-    this.flushPreferences('persist state');
     if (options.cleanUp) {
       this.cleanUp();
     }
   }
 
+  private persistState(
+    state: StateCoreResult,
+    options: PersistOptions = {},
+  ): Promise<void> {
+    this.writeState(state, options);
+    return this.flushPreferences('persist state');
+  }
+
+  /** 跑一步状态机并写入内存;落盘由调用方决定(await 或后台)。 */
   private runStateOperation(
     operation: number,
     stringArg: string = '',
-    options: {
-      removeStaleHash?: boolean;
-      cleanUp?: boolean;
-      clearFirstLoadMarker?: boolean;
-    } = {},
+    options: PersistOptions = {},
   ): StateCoreResult {
     const nextState = NativePatchCore.runStateCore(
       operation,
       this.getStateSnapshot(),
       stringArg,
     );
-    this.persistState(nextState, options);
+    this.writeState(nextState, options);
     return nextState;
   }
 
@@ -336,10 +394,11 @@ export class UpdateContext {
     return params;
   }
 
-  // 串行化下载/补丁任务与破坏性清理（reset 的全量删除）：Android 靠单线程
-  // download executor 天然串行，Harmony 的 NAPI 任务跑在 libuv worker 池上，
-  // 若不排队，reset 的 RemovePathRecursively 可能与正在写入的解压/打补丁并发，
-  // 产出"bundle 在、资源半删"的目录且可能被后续 switchVersion 激活。
+  // 串行化下载/补丁任务与破坏性清理（reset 的全量删除、按 mtime 的常规清理）：
+  // Android 靠单线程 download executor 天然串行，Harmony 的 NAPI 任务跑在
+  // libuv worker 池上，若不排队，reset 的 RemovePathRecursively 可能与正在
+  // 写入的解压/打补丁并发，产出"bundle 在、资源半删"的目录且可能被后续
+  // switchVersion 激活。
   private taskChain: Promise<void> = Promise.resolve();
 
   private enqueueSerialTask<T>(job: () => Promise<T>): Promise<T> {
@@ -385,7 +444,7 @@ export class UpdateContext {
     }
 
     logger.info(
-      'UpdateContext',
+      TAG,
       `binary version changed, resetting update state id=${this.instanceId}`,
     );
     UpdateContext.ignoreRollback = false;
@@ -394,21 +453,23 @@ export class UpdateContext {
     // rolledBackVersion）。不再 clearExisting，避免连带清除 uuid / firstLoadMarked /
     // hash_* 等与 binary 版本无关的 KV —— 它们在多实例场景下本就脆弱，连带清除会
     // 让 getConstants() 永远读到空，从而 isFirstTime=false、markSuccess 永不执行。
-    this.persistState(nextState);
+    this.writeState(nextState, {});
+    this.flushInBackground('sync binary version');
   }
 
-  public setKv(key: string, value: string): void {
+  /** 写入并落盘;flushSync 不可用时以 flush() 的结果拒绝。 */
+  public setKv(key: string, value: string): Promise<void> {
     this.preferences.putSync(key, value);
-    this.flushPreferences(`set key ${key}`);
+    return this.flushPreferences(`set key ${key}`);
   }
 
   public getKv(key: string): string {
     return this.readString(key);
   }
 
-  public removeKv(key: string): void {
+  public removeKv(key: string): Promise<void> {
     this.preferences.deleteSync(key);
-    this.flushPreferences(`remove key ${key}`);
+    return this.flushPreferences(`remove key ${key}`);
   }
 
   public isFirstTime(): boolean {
@@ -419,7 +480,7 @@ export class UpdateContext {
     return this.getStateSnapshot().rolledBackVersion || '';
   }
 
-  public markSuccess(): void {
+  public async markSuccess(): Promise<void> {
     if (UpdateContext.DEBUG) {
       return;
     }
@@ -428,27 +489,32 @@ export class UpdateContext {
       removeStaleHash: true,
       cleanUp: true,
     });
+    await this.flushPreferences('mark success');
   }
 
-  public clearFirstTime(): void {
+  public async clearFirstTime(): Promise<void> {
     this.runStateOperation(STATE_OP_CLEAR_FIRST_TIME, '', {
       cleanUp: true,
       clearFirstLoadMarker: true,
     });
+    await this.flushPreferences('clear first time');
   }
 
+  /** getConstants(同步)里调用:落盘失败只记日志。 */
   public clearRollbackMark(): void {
     this.runStateOperation(STATE_OP_CLEAR_ROLLBACK_MARK, '', {
       cleanUp: true,
     });
+    this.flushInBackground('clear rollback mark');
   }
 
   /**
    * 恢复到二进制内置包：清空整个更新状态机（下次启动即回内置 bundle）并删除
    * 已下载版本——仅保留当前运行版本的目录（静默 reset 不能破坏运行中 bundle
    * 的按需资源加载）。uuid 保留 —— 它标识安装实例、用于灰度分桶，reset 不应改变。
+   * 状态与响应缓存一次落盘;落盘失败拒绝(JS 按 RESET_FAILED 处理)。
    */
-  public resetToPackagedBundle(): void {
+  public async resetToPackagedBundle(): Promise<void> {
     this.trace('resetToPackagedBundle:before');
     // 实时读取二进制身份（与 Android/iOS 对齐），而非 preferences 快照：
     // meta.json 读取失败时快照可能为空，reset 持久化空值会让下次启动误判
@@ -462,47 +528,50 @@ export class UpdateContext {
       firstTimeOk: true,
       rolledBackVersion: '',
     };
-    // 删除已下载版本的 hash_* 元信息（不走 clear()：它是异步的，且会连带清掉
-    // uuid —— 见 syncStateWithBinaryVersion 的注释）。getAllSync 在旧 SDK 上
-    // 可能不存在，此时残留的 hash_* 只是无害孤儿数据，不影响 reset 语义。
-    const prefsWithGetAll = this.preferences as preferences.Preferences & {
-      getAllSync?: () => Record<string, unknown>;
-    };
-    if (typeof prefsWithGetAll.getAllSync === 'function') {
-      try {
-        const all = prefsWithGetAll.getAllSync();
-        for (const key of Object.keys(all)) {
-          if (key.startsWith('hash_')) {
-            this.preferences.deleteSync(key);
-          }
-        }
-      } catch (e: any) {
-        console.error('Failed to clear hash info on reset:', e);
-      }
-    }
     // 先让在飞的原生检测轮次失效,再清理状态:随后在同一(单线程)执行序里
     // 提交的轮次会看到新代数并整轮丢弃。
     UpdateContext.resetGeneration += 1;
-    this.persistState(resetState, { clearFirstLoadMarker: true });
-    // 缓存里的响应仍在宣告本次 reset 刚删掉的版本,一并丢弃,避免 JS 侧复用。
+    this.beginFlushBatch();
+    let flushed: Promise<void> = Promise.resolve();
     try {
+      // 删除已下载版本的 hash_* 元信息（不走 clear()：它是异步的，且会连带清掉
+      // uuid —— 见 syncStateWithBinaryVersion 的注释）。getAllSync 在旧 SDK 上
+      // 可能不存在，此时残留的 hash_* 只是无害孤儿数据，不影响 reset 语义。
+      const api = this.optionalPreferencesApi();
+      if (typeof api.getAllSync === 'function') {
+        try {
+          const all = api.getAllSync();
+          for (const key of Object.keys(all)) {
+            if (key.startsWith('hash_')) {
+              this.preferences.deleteSync(key);
+            }
+          }
+        } catch (e) {
+          logger.error(
+            TAG,
+            `Failed to clear hash info on reset: ${getErrorMessage(e)}`,
+          );
+        }
+      }
+      this.writeState(resetState, { clearFirstLoadMarker: true });
+      // 缓存里的响应仍在宣告本次 reset 刚删掉的版本,一并丢弃,避免 JS 侧复用。
       this.preferences.deleteSync(KEY_RESP_CACHE);
-    } catch (e: any) {
-      console.error('Failed to clear native check cache on reset:', e);
+    } finally {
+      flushed = this.endFlushBatch('reset to packaged bundle');
     }
     UpdateContext.ignoreRollback = false;
+    await flushed;
 
     // maxAgeDays=0：删除下载目录内容，仅保留当前运行版本的目录（残留目录由
     // 下次常规清理回收）。挂到串行任务链尾，避免与在飞的解压/打补丁并发。
     this.enqueueSerialTask(() =>
       NativePatchCore.cleanupOldEntries(
         this.rootDir,
-        UpdateContext.launchVersion,
-        '',
+        [UpdateContext.launchVersion].filter(name => name.length > 0),
         0,
       ),
     ).catch((error: Object) => {
-      console.error('reset cleanup failed:', error);
+      logger.error(TAG, `reset cleanup failed: ${getErrorMessage(error)}`);
     });
     this.trace('resetToPackagedBundle:after');
   }
@@ -513,37 +582,48 @@ export class UpdateContext {
   }
 
   /**
-   * 一次性提交原生检测轮次的全部持久化结果(版本元信息、激活、响应缓存):
-   * 先复核 reset 代数,再落所有写入。ArkTS 单线程 + 本方法内无 await,因此
-   * 校验与写入之间不存在可插入 reset 的窗口(iOS/Android 用锁达到同一效果)。
-   * 返回是否提交成功。
+   * 一次性提交原生检测轮次的全部持久化结果(版本元信息、激活、响应缓存)。
+   * 切换校验(含工作线程上的 bundle 摘要复核)放在第一个 putSync 之前:校验
+   * 失败时什么都不写,不会出现"元信息已落盘、切换没发生"的半提交。校验后
+   * 复核 reset 代数,之后到写入完成之间没有 await(ArkTS 单线程),因此不存在
+   * 可插入 reset 的窗口(iOS/Android 用锁达到同一效果)。三项写入以一次
+   * flush 落盘,失败拒绝。返回是否提交成功。
    */
-  public commitNativeCheckResult(
+  public async commitNativeCheckResult(
     expectedGeneration: number,
     hash: string,
     hashInfoJson: string,
     activate: boolean,
     responseCacheJson: string,
-  ): boolean {
+  ): Promise<boolean> {
     if (UpdateContext.resetGeneration !== expectedGeneration) {
       return false;
     }
+    const shouldSwitch = activate && !!hash;
+    if (shouldSwitch) {
+      await this.verifyActivation(hash);
+      if (UpdateContext.resetGeneration !== expectedGeneration) {
+        return false;
+      }
+    }
     // One flush for the whole round (see beginFlushBatch): version info,
     // activation and response cache land together or not at all.
     this.beginFlushBatch();
+    let flushed: Promise<void> = Promise.resolve();
     try {
       if (hash && hashInfoJson) {
-        this.setKv(`hash_${hash}`, hashInfoJson);
+        this.preferences.putSync(`hash_${hash}`, hashInfoJson);
       }
-      if (activate && hash) {
-        this.switchVersion(hash);
+      if (shouldSwitch) {
+        this.applySwitch(hash);
       }
       if (responseCacheJson) {
-        this.setKv(KEY_RESP_CACHE, responseCacheJson);
+        this.preferences.putSync(KEY_RESP_CACHE, responseCacheJson);
       }
     } finally {
-      this.endFlushBatch('commit native check result');
+      flushed = this.endFlushBatch('commit native check result');
     }
+    await flushed;
     return true;
   }
 
@@ -563,25 +643,11 @@ export class UpdateContext {
       params.deadlineUptimeMs = deadlineUptimeMs;
       await this.executeTask(params);
     } catch (e) {
-      console.error('Failed to download full update:', e);
+      logger.error(TAG, `Failed to download full update: ${getErrorMessage(e)}`);
       throw e;
     }
   }
 
-  public async downloadFile(
-    url: string,
-    hash: string,
-    fileName: string,
-  ): Promise<void> {
-    const params = this.createTaskParams(
-      DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD,
-      url,
-      hash,
-    );
-    params.targetFile = this.rootDir + '/' + assertSafePathComponent(fileName);
-    await this.executeTask(params);
-  }
-
   public async downloadPatchFromPpk(
     url: string,
     hash: string,
@@ -617,13 +683,14 @@ export class UpdateContext {
       params.deadlineUptimeMs = deadlineUptimeMs;
       return await this.executeTask(params);
     } catch (e) {
-      console.error('Failed to download package patch:', e);
+      logger.error(
+        TAG,
+        `Failed to download package patch: ${getErrorMessage(e)}`,
+      );
       throw e;
     }
   }
 
-  // 原生冷启动检测(NativeCheckOrchestrator)用来跳过已就绪版本的重复下载
-  // ——alert 类策略下版本已下载但未激活,若不判在这里会每次冷启动重下一遍。
   // 运行中热更版本安装记录里的 bundleSha256(崩溃归因用);内置 bundle /
   // 历史安装 / 记录不可读时为空串。
   public currentBundleSha256(hash: string): string {
@@ -640,6 +707,8 @@ export class UpdateContext {
     }
   }
 
+  // 原生冷启动检测(NativeCheckOrchestrator)用来跳过已就绪版本的重复下载
+  // ——alert 类策略下版本已下载但未激活,若不判在这里会每次冷启动重下一遍。
   public hasDownloadedVersion(hash: string): boolean {
     try {
       const safeHash = assertSafePathComponent(hash);
@@ -650,40 +719,64 @@ export class UpdateContext {
     }
   }
 
-  public switchVersion(hash: string): void {
+  /**
+   * 激活前置校验(同步,不写任何东西):bundle 在盘上,且要么是本 SDK 记录为
+   * 完整安装的版本(bundle + 记录),要么是标记机制之前就激活过的历史版本
+   * (current/last 里有它)。其他无记录的目录可能是崩溃留下的半成品。
+   * 返回是否还需复核安装记录里的 bundle 摘要(历史版本无记录可核)。
+   */
+  private assertActivatable(safeHash: string): boolean {
+    if (!fileIo.accessSync(this.getBundlePath(safeHash))) {
+      throw createUpdateError(
+        ERROR_SWITCH_VERSION_FAILED,
+        `Bundle version ${safeHash} not found.`,
+      );
+    }
+    const legacyActivated =
+      this.readString('currentVersion') === safeHash ||
+      this.readString('lastVersion') === safeHash;
+    if (!this.hasDownloadedVersion(safeHash) && !legacyActivated) {
+      throw createUpdateError(
+        ERROR_SWITCH_VERSION_FAILED,
+        `Bundle version ${safeHash} is incomplete.`,
+      );
+    }
+    return !legacyActivated;
+  }
+
+  /**
+   * 完整的激活校验(含 native 工作线程上的 bundle 摘要复核),不写状态。
+   * 记录里的 bundle 摘要必须与盘上字节一致,才能把下次启动指向它。
+   */
+  public async verifyActivation(hash: string): Promise<void> {
+    const safeHash = assertSafePathComponent(hash);
+    if (this.assertActivatable(safeHash)) {
+      await verifyInstallForActivation(
+        `${this.rootDir}/${safeHash}`,
+        safeHash,
+        this.getBundlePath(safeHash),
+      );
+    }
+  }
+
+  /** 内存里切换状态(不落盘);调用方负责 flush。 */
+  private applySwitch(hash: string): void {
+    this.trace(`switchVersion:before ${hash}`);
+    this.runStateOperation(STATE_OP_SWITCH_VERSION, hash);
+    UpdateContext.ignoreRollback = false;
+    this.trace(`switchVersion:after ${hash}`);
+  }
+
+  /** 校验 + 切换 + 落盘;任一步失败拒绝(SWITCH_VERSION_FAILED)。 */
+  public async switchVersion(hash: string): Promise<void> {
     try {
       const safeHash = assertSafePathComponent(hash);
-      const bundlePath = this.getBundlePath(safeHash);
-      if (!fileIo.accessSync(bundlePath)) {
-        throw Error(`Bundle version ${hash} not found.`);
-      }
-      // Same rule as Android/iOS: only a version this SDK recorded as
-      // completely installed (bundle + marker) may be activated. Versions
-      // activated before markers existed are grandfathered through
-      // current/last state; any other markerless directory may be a
-      // crash-left partial install.
-      const legacyActivated =
-        this.readString('currentVersion') === safeHash ||
-        this.readString('lastVersion') === safeHash;
-      if (!this.hasDownloadedVersion(safeHash) && !legacyActivated) {
-        throw Error(`Bundle version ${hash} is incomplete.`);
-      }
-      if (!legacyActivated) {
-        // 记录里的 bundle 摘要必须与盘上字节一致,才能把下次启动指向它。
-        verifyInstallForActivation(
-          `${this.rootDir}/${safeHash}`,
-          safeHash,
-          bundlePath,
-        );
-      }
-
-      this.trace(`switchVersion:before ${hash}`);
-      this.runStateOperation(STATE_OP_SWITCH_VERSION, hash);
-      UpdateContext.ignoreRollback = false;
-      this.trace(`switchVersion:after ${hash}`);
+      await this.verifyActivation(safeHash);
+      this.applySwitch(safeHash);
+      await this.flushPreferences(`switch version ${safeHash}`);
     } catch (e) {
-      console.error('Failed to switch version:', e);
-      throw e;
+      logger.error(TAG, `Failed to switch version: ${getErrorMessage(e)}`);
+      throw toUpdateError(e, ERROR_SWITCH_VERSION_FAILED);
     }
   }
 
@@ -692,7 +785,7 @@ export class UpdateContext {
     this.trace(`consumeFirstLoadMarker:marked=${marked}`);
     if (marked) {
       this.preferences.deleteSync('firstLoadMarked');
-      this.flushPreferences('clear first load marker');
+      this.flushInBackground('clear first load marker');
     }
     return marked;
   }
@@ -714,15 +807,17 @@ export class UpdateContext {
       if (launchState.didRollback) {
         // The crash-protection rollback: the new version never called
         // markSuccess. Keep this visible in release logs.
-        console.error(
+        logger.error(
+          TAG,
           `Version ${stateBeforeLaunch.currentVersion} was not marked as successful,` +
             ` rolled back to ${launchState.currentVersion}`,
         );
       }
       if (launchState.didRollback || launchState.consumedFirstTime) {
+        // 同步启动路径:落盘失败只记日志(状态已在内存里生效)。
         this.persistState(launchState, {
           markFirstLoadMarker: launchState.consumedFirstTime,
-        });
+        }).catch(() => {});
       }
       if (launchState.consumedFirstTime) {
         UpdateContext.ignoreRollback = true;
@@ -743,7 +838,7 @@ export class UpdateContext {
         const bundleFile = this.getBundlePath(version);
         try {
           if (!fileIo.accessSync(bundleFile)) {
-            console.error(`Bundle version ${version} not found.`);
+            logger.error(TAG, `Bundle version ${version} not found.`);
             version = this.rollBack();
             nativeCheckRolledBackVersion = this.rolledBackVersion();
             continue;
@@ -752,7 +847,7 @@ export class UpdateContext {
           nativeCheckRolledBackVersion = this.rolledBackVersion();
           return bundleFile;
         } catch (e) {
-          console.error('Failed to access bundle file:', e);
+          logger.error(TAG, `Failed to access bundle file: ${getErrorMessage(e)}`);
           version = this.rollBack();
           nativeCheckRolledBackVersion = this.rolledBackVersion();
         }
@@ -775,25 +870,36 @@ export class UpdateContext {
   private rollBack(): string {
     const stateBefore = this.getStateSnapshot();
     const nextState = this.runStateOperation(STATE_OP_ROLLBACK);
-    console.error(
+    this.flushInBackground('rollback');
+    logger.error(
+      TAG,
       `Rolling back version ${stateBefore.currentVersion} to ${nextState.currentVersion}`,
     );
     return nextState.currentVersion || '';
   }
 
+  /**
+   * 常规清理(best-effort 后台维护,无人等待其完成):删除 3 天未触碰且不在
+   * 保留名单里的条目。保留 current/last 与本进程启动的版本。挂到串行任务链
+   * 上——下载可能正在追加超过 3 天的续传 partial 或填充 staging,按 mtime
+   * 的清理若并发跑会把它们当陈旧条目删掉(Android 与下载共用同一单线程
+   * executor)。
+   */
   public cleanUp(): void {
     const state = this.getStateSnapshot();
-    // cleanupOldEntries now runs on a native worker thread (returns a Promise).
-    // Cleanup is best-effort background maintenance and no caller depends on its
-    // completion, so fire-and-forget it off the UI thread and just log failures
-    // instead of blocking the state operation (or cold start) on disk I/O.
-    NativePatchCore.cleanupOldEntries(
-      this.rootDir,
+    const keepNames = [
       state.currentVersion || '',
       state.lastVersion || '',
-      3,
+      UpdateContext.launchVersion,
+    ].filter(name => name.length > 0);
+    this.enqueueSerialTask(() =>
+      NativePatchCore.cleanupOldEntries(
+        this.rootDir,
+        keepNames,
+        CLEANUP_MAX_AGE_DAYS,
+      ),
     ).catch((error: Object) => {
-      console.error('cleanupOldEntries failed:', error);
+      logger.error(TAG, `cleanupOldEntries failed: ${getErrorMessage(error)}`);
     });
   }
 
@@ -812,7 +918,10 @@ export class UpdateContext {
       );
       return bundleInfo?.updateTime ?? 0;
     } catch (error) {
-      console.error('Failed to get bundle update time:', error);
+      logger.error(
+        TAG,
+        `Failed to get bundle update time: ${getErrorMessage(error)}`,
+      );
       return 0;
     }
   }
@@ -842,7 +951,7 @@ export class UpdateContext {
       hash = NativePatchCore.sha256Hex(content);
     } catch (error) {
       // rawfile 缺 bundle(未打包 release bundle)是合法的"未知",不是错误。
-      console.info('Cannot hash embedded bundle:', error);
+      logger.info(TAG, `Cannot hash embedded bundle: ${getErrorMessage(error)}`);
       return '';
     }
     if (hash) {
@@ -850,7 +959,8 @@ export class UpdateContext {
         UpdateContext.KEY_BUNDLE_HASH_CACHE,
         cachePrefix + hash,
       );
-      this.flushPreferences('cache bundle hash');
+      // 缓存落盘失败不影响返回值(下次重算即可)。
+      this.flushInBackground('cache bundle hash');
     }
     return hash;
   }