react-native-update 10.59.2 → 10.61.0

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

@@ -13,16 +13,17 @@ export function revealText(hex: string): string {
   return text;
 }
 
-// Request path appended to an endpoint base.
-export const QUERY_PATH: string = revealText('7514fcd4ad805d55263e08fc99');
-
 // Protocol values, version-info flags and storage names, stored encoded.
+// <generated:texts> (scripts/contract.ts; bun scripts/generate-contract.ts)
+// The round status / decision reason when nothing is to be installed.
 export const STATUS_NONE: string = revealText('3418c1c1aa8a7c40');
-export const POLICY_NEXT_LAUNCH: string = revealText('2912e0ffab8e6c70323b1dedd3');
-export const STORAGE_DIR_NAME: string = revealText('0502e4d5af9f6d');
 export const PREFERENCES_NAME: string = revealText('2f07f0d0ba8e');
-export const PPK_DELTA_SUFFIX: string = revealText('7407e4dae09b69512137');
-export const APP_DELTA_SUFFIX: string = revealText('7416e4c1e09b69512137');
+export const STORAGE_DIR_NAME: string = revealText('0502e4d5af9f6d');
+// The bundle patch entry inside a patch archive.
 export const BUNDLE_DELTA_ENTRY: string = revealText('3802fad5a28e264d232d11f6d8aade67596914e0ead8b0');
+export const PPK_DELTA_SUFFIX: string = revealText('7407e4dae09b69512137');
+// Archive suffix of a patch against the installed package.
+export const PACKAGE_DELTA_SUFFIX: string = revealText('7416e4c1e09b69512137');
 export const DEVTOOLS_RESTART_EVENT: string = revealText('0832d8fe8faf');
 export const DEVTOOLS_RESTART_REASON: string = revealText('1218e0e3ab876744266d');
+// </generated:texts>

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

@@ -1,8 +1,9 @@
 import preferences from '@ohos.data.preferences';
 import fileIo from '@ohos.file.fs';
 import {
+  HARMONY_BUNDLE_FILE_NAME,
   isInstallComplete,
-  readInstallRecord,
+  recordedBundleSha256,
   verifyInstallForActivation,
 } from './InstallRecord';
 import { DownloadTask } from './DownloadTask';
@@ -18,7 +19,6 @@ import {
   scheduleNativeSync,
 } from './SyncCoordinator';
 import NativePatchCore, {
-  STATE_OP_CLEAR_FIRST_TIME,
   STATE_OP_CLEAR_ROLLBACK_MARK,
   STATE_OP_MARK_SUCCESS,
   STATE_OP_RESOLVE_LAUNCH,
@@ -27,13 +27,14 @@ import NativePatchCore, {
   StateCoreResult,
 } from './NativePatchCore';
 import { assertSafePathComponent } from './PathUtils';
+import { withRawFd } from './SaveFile';
 import {
-  ERROR_SWITCH_VERSION_FAILED,
   createPushyError,
+  ERROR_SWITCH_VERSION_FAILED,
   getErrorMessage,
   toPushyError,
 } from './ErrorCodes';
-import { APP_DELTA_SUFFIX, PPK_DELTA_SUFFIX, PREFERENCES_NAME, STORAGE_DIR_NAME } from './Texts';
+import { PACKAGE_DELTA_SUFFIX, PPK_DELTA_SUFFIX, PREFERENCES_NAME, STORAGE_DIR_NAME } from './Texts';
 
 export { isSafePathComponent } from './PathUtils';
 
@@ -41,18 +42,48 @@ const TAG = 'PushyContext';
 // 常规清理保留最近 3 天内触碰过的条目(续传 partial、staging 同样按 mtime)。
 const CLEANUP_MAX_AGE_DAYS = 3;
 
-// Preferences.flushSync 是 API 14 才有、getAllSync 老 SDK 声明里没有:HAR 兼容
-// API 12,按结构化视图探测(不用交叉类型——ArkTS 不支持)。
+// Preferences.flushSync 是 API 14 才有:HAR 兼容 API 12,按结构化视图探测
+// (不用交叉类型——ArkTS 不支持)。
 interface OptionalPreferencesApi {
   flushSync?: () => void;
-  getAllSync?: () => Record<string, unknown>;
 }
 
+// C1 配置等价(cpp/update_flow_core ConfigsEquivalent,与 Android/iOS 共用):
+// 缺省键补默认值、端点/发现地址去尾斜杠并保序去重、忽略键序。等价的配置不算
+// "变更"——宿主重复 configure、或 JS 同步一份只差格式的同一配置,都不应取消
+// 在飞轮次或丢弃响应缓存。任一缺省即不等价。
+function nativeConfigsEquivalent(a: string | undefined, b: string | undefined): boolean {
+  return NativePatchCore.configsEquivalent(a, b);
+}
+
+// Per-version info key prefix and the first-load marker key.
+const HASH_INFO_PREFIX = 'hash_';
+const FIRST_LOAD_MARKED_KEY = 'firstLoadMarked';
+
+interface ClearedKeys {
+  keys: string[];
+  prefixes: string[];
+}
+
+// <generated:lifecycle> (scripts/contract.ts; bun scripts/generate-contract.ts)
+// What a reset to the packaged bundle and a binary upgrade delete besides
+// the state fields (scripts/contract.ts storedItems; every other item survives
+// both: the uuid, the native config, the round breadcrumb, the bundle hash
+// cache).
+const RESET_CLEARED: ClearedKeys = {
+  keys: [FIRST_LOAD_MARKED_KEY, KEY_RESP_CACHE],
+  prefixes: [HASH_INFO_PREFIX],
+};
+const UPGRADE_CLEARED: ClearedKeys = {
+  keys: [FIRST_LOAD_MARKED_KEY, KEY_RESP_CACHE],
+  prefixes: [HASH_INFO_PREFIX],
+};
+// </generated:lifecycle>
+
 interface PersistOptions {
   removeStaleHash?: boolean;
   cleanUp?: boolean;
   markFirstLoadMarker?: boolean;
-  clearFirstLoadMarker?: boolean;
 }
 
 export class UpdateContext {
@@ -133,7 +164,7 @@ export class UpdateContext {
         ` cv=${snap.currentVersion} lv=${snap.lastVersion}` +
         ` ft=${snap.firstTime} fto=${snap.firstTimeOk}` +
         ` rb=${snap.rolledBackVersion}` +
-        ` flm=${this.readString('firstLoadMarked')}` +
+        ` flm=${this.readString(FIRST_LOAD_MARKED_KEY)}` +
         ` uuidSet=${!!this.readString('uuid')}`,
     );
   }
@@ -202,6 +233,18 @@ export class UpdateContext {
         `Failed to read build time from raw file: ${getErrorMessage(error)}`,
       );
     }
+    // 绝不返回空串(与 iOS 用 Info.plist mtime 兜底一致):buildTime 为空时
+    // syncStateWithBinaryVersion 整体跳过,保留 versionName 的重装二进制会
+    // 让旧热更活过应用升级。每次(覆盖)安装 updateTime 都会变,用它顶替。
+    const updateTime = this.getBundleModifiedTime();
+    if (updateTime > 0) {
+      logger.warn(
+        TAG,
+        'meta.json has no build stamp; using the app install time as buildTime',
+      );
+      UpdateContext.cachedBuildTime = String(updateTime);
+      return UpdateContext.cachedBuildTime;
+    }
     return '';
   }
 
@@ -320,7 +363,7 @@ export class UpdateContext {
   }
 
   private getBundlePath(hash: string): string {
-    return `${this.rootDir}/${hash}/bundle.harmony.js`;
+    return `${this.rootDir}/${hash}/${HARMONY_BUNDLE_FILE_NAME}`;
   }
 
   private getStateSnapshot(): StateCoreResult {
@@ -352,10 +395,7 @@ export class UpdateContext {
       this.preferences.deleteSync(`hash_${state.staleVersionToDelete}`);
     }
     if (options.markFirstLoadMarker) {
-      this.preferences.putSync('firstLoadMarked', 'true');
-    }
-    if (options.clearFirstLoadMarker) {
-      this.preferences.deleteSync('firstLoadMarked');
+      this.preferences.putSync(FIRST_LOAD_MARKED_KEY, 'true');
     }
     if (options.cleanUp) {
       this.cleanUp();
@@ -404,6 +444,60 @@ export class UpdateContext {
   // switchVersion 激活。
   private taskChain: Promise<void> = Promise.resolve();
 
+  // 在途的破坏性清理(常规清理与 reset 清理)及其开始次数。激活与破坏性清理
+  // 互斥(Android 的 versionFilesLock):激活校验前先等在途清理结束,校验后
+  // 若期间又有清理开始则重来。清理的保留名单在任务开始时(主线程)取,而
+  // 校验通过到 applySwitch 之间没有 await,所以此后开始的清理一定看得到
+  // 刚激活的版本。
+  private cleanupInFlight: Promise<void> | null = null;
+  private cleanupStarts: number = 0;
+
+  private enqueueCleanupTask(job: () => Promise<void>): Promise<void> {
+    return this.enqueueSerialTask(() => {
+      this.cleanupStarts += 1;
+      const running = job();
+      const tracked = running.then(
+        () => undefined,
+        () => undefined,
+      );
+      this.cleanupInFlight = tracked;
+      tracked.then(() => {
+        if (this.cleanupInFlight === tracked) {
+          this.cleanupInFlight = null;
+        }
+      });
+      return running;
+    });
+  }
+
+  private static readonly MAX_ACTIVATION_VERIFY_ATTEMPTS = 3;
+
+  /**
+   * verifyActivation,并保证返回时没有破坏性清理在途、校验期间也没有清理
+   * 开始过(见 cleanupInFlight)。调用方须在返回后、下一个 await 之前完成
+   * applySwitch。
+   */
+  private async verifyActivationExclusive(hash: string): Promise<void> {
+    for (
+      let attempt = 0;
+      attempt < UpdateContext.MAX_ACTIVATION_VERIFY_ATTEMPTS;
+      attempt++
+    ) {
+      while (this.cleanupInFlight !== null) {
+        await this.cleanupInFlight;
+      }
+      const starts = this.cleanupStarts;
+      await this.verifyActivation(hash);
+      if (this.cleanupInFlight === null && this.cleanupStarts === starts) {
+        return;
+      }
+    }
+    throw createPushyError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Version ${hash} kept racing cleanup while switching.`,
+    );
+  }
+
   private enqueueSerialTask<T>(job: () => Promise<T>): Promise<T> {
     const run = this.taskChain.then(job);
     this.taskChain = run.then(
@@ -415,13 +509,9 @@ export class UpdateContext {
 
   private async executeTask(params: DownloadTaskParams): Promise<void> {
     await this.enqueueSerialTask(() => {
-      const isPatchTask =
-        params.type === DownloadTaskParams.TASK_TYPE_PATCH_FULL ||
-        params.type === DownloadTaskParams.TASK_TYPE_PATCH_FROM_APP ||
-        params.type === DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK;
       // Re-check only when this queued job actually starts. A JS download may
       // have completed while the cold-start duplicate waited behind it.
-      if (isPatchTask && this.hasDownloadedVersion(params.hash)) {
+      if (this.hasDownloadedVersion(params.hash)) {
         return Promise.resolve();
       }
       const downloadTask = new DownloadTask(this.context);
@@ -429,6 +519,27 @@ export class UpdateContext {
     });
   }
 
+  // Deletes `cleared` from the store (in memory; the caller flushes). A
+  // failed read leaves harmless orphans: none of them affects the state.
+  private removeKeys(cleared: ClearedKeys, event: string): void {
+    for (const key of cleared.keys) {
+      this.preferences.deleteSync(key);
+    }
+    if (cleared.prefixes.length === 0) {
+      return;
+    }
+    try {
+      const all = this.preferences.getAllSync();
+      for (const key of Object.keys(all)) {
+        if (cleared.prefixes.some(prefix => key.startsWith(prefix))) {
+          this.preferences.deleteSync(key);
+        }
+      }
+    } catch (e) {
+      logger.error(TAG, `Failed to clear keys on ${event}: ${getErrorMessage(e)}`);
+    }
+  }
+
   public syncStateWithBinaryVersion(
     packageVersion: string,
     buildTime: string,
@@ -452,27 +563,38 @@ export class UpdateContext {
     );
     UpdateContext.ignoreRollback = false;
     this.cleanUp();
-    // 仅重置状态机字段（currentVersion / lastVersion / firstTime / firstTimeOk /
-    // rolledBackVersion）。不再 clearExisting，避免连带清除 uuid / firstLoadMarked /
-    // hash_* 等与 binary 版本无关的 KV —— 它们在多实例场景下本就脆弱，连带清除会
-    // 让 getConstants() 永远读到空，从而 isFirstTime=false、markSuccess 永不执行。
+    // 旧二进制的版本已不在状态里:删掉它们的元信息、首启标记与响应缓存,与
+    // 各端一致(scripts/contract.ts storedItems)。uuid、原生配置等属于安装本身的
+    // 键保留——不走 clearExisting(那会让 getConstants 读到空的 uuid)。升级后
+    // 没有运行中的热更版本,首启标记不会在本次启动里先写后删。
+    this.removeKeys(UPGRADE_CLEARED, 'binary upgrade');
     this.writeState(nextState, {});
     this.flushInBackground('sync binary version');
   }
 
-  /** 写入并落盘;flushSync 不可用时以 flush() 的结果拒绝。 */
-  /** Shared JS/native configuration writer; all mutations precede the first await. */
   private static nativeConfigGeneration: number = 0;
 
   public getNativeConfigGeneration(): number {
     return UpdateContext.nativeConfigGeneration;
   }
 
+  /** 与持久化的配置是否等价(C1)。 */
+  public isStoredNativeConfig(config: string | undefined): boolean {
+    return nativeConfigsEquivalent(config, this.getKv(KEY_CONFIG));
+  }
+
+  /**
+   * Shared JS/native configuration writer; all mutations precede the first
+   * await. An equivalent configuration (C1) is not a change: the stored string,
+   * response cache and generations stay as they are.
+   */
   public setNativeConfig(config: string): Promise<void> {
     if (!this.getKv('uuid')) {
       this.preferences.putSync('uuid', util.generateRandomUUID());
     }
-    if (this.getKv(KEY_CONFIG) !== config) {
+    const current = this.getKv(KEY_CONFIG);
+    // Byte-identical is trivially no change, even for a value C1 cannot parse.
+    if (!current || (current !== config && !nativeConfigsEquivalent(current, config))) {
       // Also guards A -> B -> A replacements and late download commits.
       UpdateContext.resetGeneration += 1;
       UpdateContext.nativeConfigGeneration += 1;
@@ -484,6 +606,7 @@ export class UpdateContext {
     return this.flushPreferences('persist configuration');
   }
 
+  /** 写入并落盘;flushSync 不可用时以 flush() 的结果拒绝。 */
   public setKv(key: string, value: string): Promise<void> {
     this.preferences.putSync(key, value);
     return this.flushPreferences(`set key ${key}`);
@@ -498,10 +621,6 @@ export class UpdateContext {
     return this.flushPreferences(`remove key ${key}`);
   }
 
-  public isFirstTime(): boolean {
-    return this.getStateSnapshot().firstTime;
-  }
-
   public rolledBackVersion(): string {
     return this.getStateSnapshot().rolledBackVersion || '';
   }
@@ -518,14 +637,6 @@ export class UpdateContext {
     await this.flushPreferences('mark success');
   }
 
-  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, '', {
@@ -560,28 +671,11 @@ export class UpdateContext {
     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);
+      // 删除版本元信息、首启标记与响应缓存(缓存仍在宣告本次 reset 刚删掉的
+      // 版本),与各端一致(scripts/contract.ts storedItems)。不走 clear():
+      // 它是异步的,且会连带清掉 uuid。
+      this.removeKeys(RESET_CLEARED, 'reset');
+      this.writeState(resetState, {});
     } finally {
       flushed = this.endFlushBatch('reset to packaged bundle');
     }
@@ -590,7 +684,7 @@ export class UpdateContext {
 
     // maxAgeDays=0：删除下载目录内容，仅保留当前运行版本的目录（残留目录由
     // 下次常规清理回收）。挂到串行任务链尾，避免与在飞的解压/打补丁并发。
-    this.enqueueSerialTask(() =>
+    this.enqueueCleanupTask(() =>
       NativePatchCore.cleanupOldEntries(
         this.rootDir,
         [UpdateContext.launchVersion].filter(name => name.length > 0),
@@ -627,7 +721,7 @@ export class UpdateContext {
     }
     const shouldSwitch = activate && !!hash;
     if (shouldSwitch) {
-      await this.verifyActivation(hash);
+      await this.verifyActivationExclusive(hash);
       if (UpdateContext.resetGeneration !== expectedGeneration) {
         return false;
       }
@@ -658,20 +752,15 @@ export class UpdateContext {
     hash: string,
     deadlineUptimeMs: number = 0,
   ): Promise<void> {
-    try {
-      const params = this.createTaskParams(
-        DownloadTaskParams.TASK_TYPE_PATCH_FULL,
-        url,
-        hash,
-      );
-      params.targetFile = `${this.rootDir}/${hash}.ppk`;
-      params.unzipDirectory = `${this.rootDir}/${hash}`;
-      params.deadlineUptimeMs = deadlineUptimeMs;
-      await this.executeTask(params);
-    } catch (e) {
-      logger.error(TAG, `Failed to download full package: ${getErrorMessage(e)}`);
-      throw e;
-    }
+    const params = this.createTaskParams(
+      DownloadTaskParams.TASK_TYPE_PATCH_FULL,
+      url,
+      hash,
+    );
+    params.targetFile = `${this.rootDir}/${hash}.ppk`;
+    params.unzipDirectory = `${this.rootDir}/${hash}`;
+    params.deadlineUptimeMs = deadlineUptimeMs;
+    await this.executeTask(params);
   }
 
   public async downloadPatchFromPpk(
@@ -698,23 +787,15 @@ export class UpdateContext {
     hash: string,
     deadlineUptimeMs: number = 0,
   ): Promise<void> {
-    try {
-      const params = this.createTaskParams(
-        DownloadTaskParams.TASK_TYPE_PATCH_FROM_APP,
-        url,
-        hash,
-      );
-      params.targetFile = `${this.rootDir}/${hash}${APP_DELTA_SUFFIX}`;
-      params.unzipDirectory = `${this.rootDir}/${hash}`;
-      params.deadlineUptimeMs = deadlineUptimeMs;
-      return await this.executeTask(params);
-    } catch (e) {
-      logger.error(
-        TAG,
-        `Failed to download package delta: ${getErrorMessage(e)}`,
-      );
-      throw e;
-    }
+    const params = this.createTaskParams(
+      DownloadTaskParams.TASK_TYPE_PATCH_FROM_APP,
+      url,
+      hash,
+    );
+    params.targetFile = `${this.rootDir}/${hash}${PACKAGE_DELTA_SUFFIX}`;
+    params.unzipDirectory = `${this.rootDir}/${hash}`;
+    params.deadlineUptimeMs = deadlineUptimeMs;
+    await this.executeTask(params);
   }
 
   // 运行中热更版本安装记录里的 bundleSha256(崩溃归因用);内置 bundle /
@@ -724,10 +805,9 @@ export class UpdateContext {
       return '';
     }
     try {
-      const record = readInstallRecord(
+      return recordedBundleSha256(
         `${this.rootDir}/${assertSafePathComponent(hash)}`,
       );
-      return record?.bundleSha256 ?? '';
     } catch (e) {
       return '';
     }
@@ -738,51 +818,26 @@ export class UpdateContext {
   public hasDownloadedVersion(hash: string): boolean {
     try {
       const safeHash = assertSafePathComponent(hash);
-      return fileIo.accessSync(this.getBundlePath(safeHash))
-        && isInstallComplete(`${this.rootDir}/${safeHash}`, safeHash);
+      return isInstallComplete(`${this.rootDir}/${safeHash}`, safeHash);
     } catch (e) {
       return false;
     }
   }
 
   /**
-   * 激活前置校验(同步,不写任何东西):bundle 在盘上,且要么是本 SDK 记录为
-   * 完整安装的版本(bundle + 记录),要么是标记机制之前就激活过的历史版本
-   * (current/last 里有它)。其他无记录的目录可能是崩溃留下的半成品。
-   * 返回是否还需复核安装记录里的 bundle 摘要(历史版本无记录可核)。
-   */
-  private assertActivatable(safeHash: string): boolean {
-    if (!fileIo.accessSync(this.getBundlePath(safeHash))) {
-      throw createPushyError(
-        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 createPushyError(
-        ERROR_SWITCH_VERSION_FAILED,
-        `Bundle version ${safeHash} is incomplete.`,
-      );
-    }
-    return !legacyActivated;
-  }
-
-  /**
-   * 完整的激活校验(含 native 工作线程上的 bundle 摘要复核),不写状态。
-   * 记录里的 bundle 摘要必须与盘上字节一致,才能把下次启动指向它。
+   * 完整的激活校验(含 native 工作线程上的 bundle 摘要复核),不写状态:
+   * bundle 在盘上,且记录里的 bundle 摘要与盘上字节一致,才能把下次启动指向
+   * 它。标记机制之前就激活过、目录里没有记录文件的历史版本(current/last
+   * 里有它)免检;有记录文件的目录即便是 current/last 也照常复核。
    */
   public async verifyActivation(hash: string): Promise<void> {
     const safeHash = assertSafePathComponent(hash);
-    if (this.assertActivatable(safeHash)) {
-      await verifyInstallForActivation(
-        `${this.rootDir}/${safeHash}`,
-        safeHash,
-        this.getBundlePath(safeHash),
-      );
-    }
+    await verifyInstallForActivation(
+      `${this.rootDir}/${safeHash}`,
+      safeHash,
+      this.readString('currentVersion') === safeHash ||
+        this.readString('lastVersion') === safeHash,
+    );
   }
 
   /** 内存里切换状态(不落盘);调用方负责 flush。 */
@@ -797,7 +852,16 @@ export class UpdateContext {
   public async switchVersion(hash: string): Promise<void> {
     try {
       const safeHash = assertSafePathComponent(hash);
-      await this.verifyActivation(safeHash);
+      const generation = UpdateContext.resetGeneration;
+      await this.verifyActivationExclusive(safeHash);
+      // 与 commitSyncResult 一致:校验期间发生过 reset(它会删掉刚校验过的
+      // 目录),不能再把下次启动指向它。
+      if (UpdateContext.resetGeneration !== generation) {
+        throw createPushyError(
+          ERROR_SWITCH_VERSION_FAILED,
+          `Reset to the packaged bundle while switching to ${safeHash}.`,
+        );
+      }
       this.applySwitch(safeHash);
       await this.flushPreferences(`switch version ${safeHash}`);
     } catch (e) {
@@ -807,10 +871,10 @@ export class UpdateContext {
   }
 
   public consumeFirstLoadMarker(): boolean {
-    const marked = this.readString('firstLoadMarked') === 'true';
+    const marked = this.readString(FIRST_LOAD_MARKED_KEY) === 'true';
     this.trace(`consumeFirstLoadMarker:marked=${marked}`);
     if (marked) {
-      this.preferences.deleteSync('firstLoadMarked');
+      this.preferences.deleteSync(FIRST_LOAD_MARKED_KEY);
       this.flushInBackground('clear first load marker');
     }
     return marked;
@@ -912,19 +976,21 @@ export class UpdateContext {
    * executor)。
    */
   public cleanUp(): void {
-    const state = this.getStateSnapshot();
-    const keepNames = [
-      state.currentVersion || '',
-      state.lastVersion || '',
-      UpdateContext.launchVersion,
-    ].filter(name => name.length > 0);
-    this.enqueueSerialTask(() =>
-      NativePatchCore.cleanupOldEntries(
+    // 保留名单在任务真正开始时取,不在入队时取(与 Android 一致):清理可能
+    // 排在一个长下载后面,期间激活的版本必须在名单里。
+    this.enqueueCleanupTask(() => {
+      const state = this.getStateSnapshot();
+      const keepNames = [
+        state.currentVersion || '',
+        state.lastVersion || '',
+        UpdateContext.launchVersion,
+      ].filter(name => name.length > 0);
+      return NativePatchCore.cleanupOldEntries(
         this.rootDir,
         keepNames,
         CLEANUP_MAX_AGE_DAYS,
-      ),
-    ).catch((error: Object) => {
+      );
+    }).catch((error: Object) => {
       logger.error(TAG, `cleanupOldEntries failed: ${getErrorMessage(error)}`);
     });
   }
@@ -952,29 +1018,56 @@ export class UpdateContext {
     }
   }
 
+  // 进行中的摘要计算:JS getBundleHash 与原生轮次可能同时要它,共用一次。
+  private bundleHashTask: Promise<string> | null = null;
+
   /**
    * bundleHash = 二进制内嵌 JS bundle 的 sha256 —— 标识二进制本身,与当前运行
    * 的热更版本无关。哈希对象与 pdiff 的源读取完全一致:rawfile 的
    * bundle.harmony.js(DownloadTask.doPatchFromApp 同一读法)。懒计算 + 缓存;
    * 永不失败——空串表示"未知",服务端回退 buildTime 启发式。
    */
-  public async getBundleHash(): Promise<string> {
+  public getBundleHash(): Promise<string> {
     if (UpdateContext.DEBUG) {
       // debug 下 bundle 由 metro 提供,与 dev 删 buildTime 的行为对齐。
-      return '';
+      return Promise.resolve('');
     }
     const cachePrefix = `${this.getPackageVersion()}|${this.getBundleModifiedTime()}|`;
     const cached = this.readString(UpdateContext.KEY_BUNDLE_HASH_CACHE);
     if (cached.startsWith(cachePrefix)) {
-      return cached.slice(cachePrefix.length);
+      return Promise.resolve(cached.slice(cachePrefix.length));
+    }
+    if (!this.bundleHashTask) {
+      const task = this.computeBundleHash(cachePrefix);
+      this.bundleHashTask = task;
+      task.then(
+        () => {
+          this.bundleHashTask = null;
+        },
+        () => {
+          this.bundleHashTask = null;
+        },
+      );
     }
+    return this.bundleHashTask;
+  }
+
+  private async computeBundleHash(cachePrefix: string): Promise<string> {
     let hash = '';
     try {
-      // 异步读:TurboModule 跑在 UI 线程,同步读几 MB 会卡主线程一次。C++
-      // 哈希本身毫秒级,同步无妨。
-      const content =
-        await this.context.resourceManager.getRawFileContent('bundle.harmony.js');
-      hash = NativePatchCore.sha256Hex(content);
+      // 内嵌 bundle 有几 MB:不读进内存,也不在 UI 线程(TurboModule 所在)
+      // 哈希——native 工作线程按 rawfile descriptor 的区间 pread 流式计算。
+      // fd 在 promise 落定后才关闭(withRawFd)。
+      hash = await withRawFd(
+        this.context.resourceManager,
+        HARMONY_BUNDLE_FILE_NAME,
+        descriptor =>
+          NativePatchCore.sha256HexRawFdAsync(
+            descriptor.fd,
+            descriptor.offset,
+            descriptor.length,
+          ),
+      );
     } catch (error) {
       // rawfile 缺 bundle(未打包 release bundle)是合法的"未知",不是错误。
       logger.info(TAG, `Cannot hash embedded bundle: ${getErrorMessage(error)}`);