react-native-update 10.55.1 → 10.56.0

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

@@ -0,0 +1,75 @@
+// ArkTS mirror of cpp/patch_core/error_codes.h — keep in sync by hand
+// (harmony/pushy/src/test/check-constant-parity.js asserts the values match).
+// 与 Android/iOS 共用的稳定错误码:JS 层(src/error.ts)按 code 聚合遥测,
+// 消息文案各平台可不同,只有码是契约。
+//
+// RNOH 的异步桥以纯字符串 reject,Error 上的 `code` 属性到 JS 侧很可能已丢。
+// 因此每个错误的消息都以 `[CODE] ` 前缀开头,JS 鸿蒙分支据此解析回 code。
+// 本文件不依赖任何其他模块,任何文件都可安全引用它而不会形成 import 环。
+
+export const ERROR_INVALID_OPTIONS = 'INVALID_OPTIONS';
+export const ERROR_DOWNLOAD_FAILED = 'DOWNLOAD_FAILED';
+export const ERROR_PATCH_FAILED = 'PATCH_FAILED';
+export const ERROR_FILE_OPERATION_FAILED = 'FILE_OPERATION_FAILED';
+export const ERROR_SWITCH_VERSION_FAILED = 'SWITCH_VERSION_FAILED';
+export const ERROR_MARK_SUCCESS_FAILED = 'MARK_SUCCESS_FAILED';
+export const ERROR_RESTART_FAILED = 'RESTART_FAILED';
+export const ERROR_RESET_FAILED = 'RESET_FAILED';
+export const ERROR_INVALID_HASH_INFO = 'INVALID_HASH_INFO';
+export const ERROR_UNSUPPORTED_PLATFORM = 'UNSUPPORTED_PLATFORM';
+export const ERROR_APK_INSTALL_PERMISSION_REQUIRED =
+  'APK_INSTALL_PERMISSION_REQUIRED';
+export const ERROR_APK_INSTALL_FAILED = 'APK_INSTALL_FAILED';
+
+/**
+ * 带稳定错误码的 Error:`code` 是属性,消息同时带 `[CODE] ` 前缀(桥丢属性时
+ * JS 仍能解析)。始终经 createUpdateError / toUpdateError 构造。
+ */
+export class UpdateError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(`[${code}] ${message}`);
+    this.name = 'UpdateError';
+    this.code = code;
+  }
+}
+
+/** 任意抛出值的可读消息(Error 取 message,其余 String())。 */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String((error as Record<string, unknown>).message);
+  }
+  return String(error);
+}
+
+export function createUpdateError(code: string, message: string): UpdateError {
+  return new UpdateError(code, message);
+}
+
+/**
+ * 给未带码的错误补上 `code`:已是 UpdateError 的原样返回(保留其更精确的码
+ * 与前缀,绝不叠两层前缀),其余按 defaultCode 重包并保留原消息。
+ */
+export function toUpdateError(error: unknown, defaultCode: string): UpdateError {
+  if (error instanceof UpdateError) {
+    return error;
+  }
+  return new UpdateError(defaultCode, getErrorMessage(error));
+}
+
+/** 从 `[CODE] message` 形式的消息里解析错误码;无前缀返回空串。 */
+export function parseErrorCodePrefix(message: string): string {
+  if (typeof message !== 'string' || !message.startsWith('[')) {
+    return '';
+  }
+  const end = message.indexOf('] ');
+  if (end <= 1) {
+    return '';
+  }
+  const code = message.substring(1, end);
+  return /^[A-Z][A-Z0-9_]*$/.test(code) ? code : '';
+}

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

@@ -1,13 +1,16 @@
-type EventCallback = (data: any) => void;
+// The subset of RNOH's RNInstance the SDK needs: device events for download
+// progress. Typed structurally so the hypium tests can pass a mock.
+export interface DeviceEventEmitter {
+  emitDeviceEvent(eventName: string, payload: Object): void;
+}
 
 export class EventHub {
   private static instance: EventHub;
-  private listeners: Map<string, Set<EventCallback>>;
-  private rnInstance: any;
+  // 指向最近一次构造 TurboModule 的 RNInstance:RNOH 重建 RN 实例时会构造
+  // 新的 TurboModule 并在此替换,已销毁实例上的 emit 由 RNOH 自行忽略。
+  private rnInstance: DeviceEventEmitter | undefined = undefined;
 
-  private constructor() {
-    this.listeners = new Map();
-  }
+  private constructor() {}
 
   public static getInstance(): EventHub {
     if (!EventHub.instance) {
@@ -16,24 +19,23 @@ export class EventHub {
     return EventHub.instance;
   }
 
-  public on(event: string, callback: EventCallback): void {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, new Set());
-    }
-    this.listeners.get(event)?.add(callback);
-  }
-
-  public off(event: string, callback: EventCallback): void {
-    this.listeners.get(event)?.delete(callback);
-  }
-
-  public emit(event: string, data: any): void {
+  public emit(event: string, data: Object): void {
     if (this.rnInstance) {
       this.rnInstance.emitDeviceEvent(event, data);
     }
   }
 
-  setRNInstance(instance: any) {
+  setRNInstance(instance: DeviceEventEmitter | undefined): void {
     this.rnInstance = instance;
   }
-}
+
+  /**
+   * TurboModule 销毁时调用:只在仍指向该实例时清除——RNOH 重建 RN 实例时
+   * 新 TurboModule 可能先于旧实例的销毁回调构造,不能把新引用一并清掉。
+   */
+  clearRNInstance(instance: DeviceEventEmitter | undefined): void {
+    if (instance !== undefined && this.rnInstance === instance) {
+      this.rnInstance = undefined;
+    }
+  }
+}

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

@@ -1,14 +1,19 @@
 import fileIo from '@ohos.file.fs';
 import { util } from '@kit.ArkTS';
 import NativePatchCore from './NativePatchCore';
+import { ERROR_SWITCH_VERSION_FAILED, createUpdateError } from './ErrorCodes';
 
-// ArkTS mirror of cpp/patch_core/install_record.h — keep in sync by hand.
+// ArkTS mirror of cpp/patch_core/install_record.h — keep in sync by hand
+// (harmony/pushy/src/test/check-constant-parity.js asserts the values match).
 // 两阶段安装的完成记录:作为安装最后一步写进 staging 目录,随后 staging
 // 原子 rename 成版本目录;激活前重新校验 bundle 摘要。空文件 = 旧版 SDK
 // 写的历史标记,仍视为完整安装(无摘要可验)。
 export const INSTALL_RECORD_SCHEMA = 1;
 export const INSTALL_RECORD_FILE_NAME = '.pushy-complete';
 export const STAGING_SUFFIX = '.staging';
+// 归档不得携带任何 `.pushy-` 前缀的条目(任意深度):这些名字保留给 SDK 自己
+// 写的记录,与 Android 的规则一致。
+export const RESERVED_ENTRY_PREFIX = '.pushy-';
 export const HARMONY_BUNDLE_FILE_NAME = 'bundle.harmony.js';
 
 export interface InstallRecordData {
@@ -22,6 +27,10 @@ export function stagingDirectoryFor(versionDir: string): string {
   return `${versionDir}${STAGING_SUFFIX}`;
 }
 
+export function isReservedEntryName(name: string): boolean {
+  return name.startsWith(RESERVED_ENTRY_PREFIX);
+}
+
 export function buildInstallRecord(
   versionHash: string,
   bundleSha256: string,
@@ -63,7 +72,25 @@ export async function writeInstallRecord(
 }
 
 /**
- * 解析记录:文件缺失/畸形返回 null;空文件(历史标记)返回 {}。
+ * 解析记录文本:空串(历史标记)返回 {};畸形/非对象返回 null。纯函数,
+ * 供 readInstallRecord 与单测共用。
+ */
+export function parseInstallRecord(text: string): InstallRecordData | null {
+  if (text.length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(text) as InstallRecordData | null;
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 读取记录:文件缺失/畸形返回 null;空文件(历史标记)返回 {}。
  */
 export function readInstallRecord(versionDir: string): InstallRecordData | null {
   const path = `${versionDir}/${INSTALL_RECORD_FILE_NAME}`;
@@ -78,17 +105,17 @@ export function readInstallRecord(versionDir: string): InstallRecordData | null
     if (stat.size > 64 * 1024) {
       return null;
     }
-    const text = fileIo.readTextSync(path);
-    const parsed = JSON.parse(text) as InstallRecordData | null;
-    return parsed !== null && typeof parsed === 'object' ? parsed : null;
+    return parseInstallRecord(fileIo.readTextSync(path));
   } catch (e) {
     return null;
   }
 }
 
-/** 存在性判定(启动/去重路径,不算摘要):记录存在且(非历史空文件时)指向本版本。 */
-export function isInstallComplete(versionDir: string, versionHash: string): boolean {
-  const record = readInstallRecord(versionDir);
+/** 记录是否宣告本版本完整安装(历史空记录视为是)。纯函数。 */
+export function isRecordForVersion(
+  record: InstallRecordData | null,
+  versionHash: string,
+): boolean {
   if (record === null) {
     return false;
   }
@@ -100,30 +127,61 @@ export function isInstallComplete(versionDir: string, versionHash: string): bool
   );
 }
 
-/** 激活前校验:记录带摘要时重新计算 bundle 摘要;不通过则抛错说明原因。 */
-export function verifyInstallForActivation(
-  versionDir: string,
+/** 存在性判定(启动/去重路径,不算摘要):记录存在且(非历史空文件时)指向本版本。 */
+export function isInstallComplete(versionDir: string, versionHash: string): boolean {
+  return isRecordForVersion(readInstallRecord(versionDir), versionHash);
+}
+
+/**
+ * 激活前的记录校验(不含摘要):返回需要复核的 bundle 摘要,历史空记录或
+ * 无摘要记录返回空串;记录缺失/不符抛 SWITCH_VERSION_FAILED。纯函数。
+ */
+export function expectedBundleSha256ForActivation(
+  record: InstallRecordData | null,
   versionHash: string,
-  bundlePath: string,
-): void {
-  const record = readInstallRecord(versionDir);
+): string {
   if (record === null) {
-    throw Error(`Bundle version ${versionHash} has no valid completion record.`);
+    throw createUpdateError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Bundle version ${versionHash} has no valid completion record.`,
+    );
   }
   if (Object.keys(record).length === 0) {
-    return;
+    return '';
   }
   if (
     record.schema !== INSTALL_RECORD_SCHEMA ||
     record.versionHash !== versionHash
   ) {
-    throw Error(`Bundle version ${versionHash} completion record mismatch.`);
+    throw createUpdateError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Bundle version ${versionHash} completion record mismatch.`,
+    );
   }
-  if (!record.bundleSha256) {
+  return record.bundleSha256 ?? '';
+}
+
+/**
+ * 激活前校验:记录带摘要时在 native 工作线程重新计算 bundle 摘要(整包
+ * 几十 MB,不能在 UI 线程同步算);不通过则抛错说明原因。
+ */
+export async function verifyInstallForActivation(
+  versionDir: string,
+  versionHash: string,
+  bundlePath: string,
+): Promise<void> {
+  const expected = expectedBundleSha256ForActivation(
+    readInstallRecord(versionDir),
+    versionHash,
+  );
+  if (!expected) {
     return;
   }
-  const actual = NativePatchCore.sha256HexFile(bundlePath);
-  if (actual.toLowerCase() !== record.bundleSha256.toLowerCase()) {
-    throw Error(`Bundle version ${versionHash} bundle digest mismatch.`);
+  const actual = await NativePatchCore.sha256HexFileAsync(bundlePath);
+  if (actual.toLowerCase() !== expected.toLowerCase()) {
+    throw createUpdateError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Bundle version ${versionHash} bundle digest mismatch.`,
+    );
   }
 }

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

@@ -16,36 +16,62 @@ class Logger {
     this.isDebug = isDebug;
   }
 
-  private normalizeArgs(args: string[]): [string, string] {
-    if (args.length === 0) {
-      return ['', ''];
-    }
-    if (args.length === 1) {
-      return [args[0], ''];
-    }
-    return [args[0], args.slice(1).join(' ')];
+  // debug 级别默认关闭;宿主处于 RN 调试模式(RNOH isDebugModeEnabled)时由
+  // TurboModule 在启动时打开,方便接入调试。info/warn/error 永远输出。
+  // (HAR 自身没有可靠的构建期 DEBUG 信号:hvigor 只为宿主模块生成
+  // BuildProfile,在 HAR 里 import 'BuildProfile' 无法解析。)
+  setDebug(enabled: boolean): void {
+    this.isDebug = enabled;
+  }
+
+  private tagOf(args: string[]): string {
+    return args.length > 0 ? args[0] : '';
+  }
+
+  private messageOf(args: string[]): string {
+    return args.length > 1 ? args.slice(1).join(' ') : '';
   }
 
   debug(...args: string[]): void {
     if (this.isDebug) {
-      const [tag, message] = this.normalizeArgs(args);
-      hilog.debug(this.domain, this.prefix, this.format, tag, message);
+      hilog.debug(
+        this.domain,
+        this.prefix,
+        this.format,
+        this.tagOf(args),
+        this.messageOf(args),
+      );
     }
   }
 
   info(...args: string[]): void {
-    const [tag, message] = this.normalizeArgs(args);
-    hilog.info(this.domain, this.prefix, this.format, tag, message);
+    hilog.info(
+      this.domain,
+      this.prefix,
+      this.format,
+      this.tagOf(args),
+      this.messageOf(args),
+    );
   }
 
   warn(...args: string[]): void {
-    const [tag, message] = this.normalizeArgs(args);
-    hilog.warn(this.domain, this.prefix, this.format, tag, message);
+    hilog.warn(
+      this.domain,
+      this.prefix,
+      this.format,
+      this.tagOf(args),
+      this.messageOf(args),
+    );
   }
 
   error(...args: string[]): void {
-    const [tag, message] = this.normalizeArgs(args);
-    hilog.error(this.domain, this.prefix, this.format, tag, message);
+    hilog.error(
+      this.domain,
+      this.prefix,
+      this.format,
+      this.tagOf(args),
+      this.messageOf(args),
+    );
   }
 }
 

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

@@ -5,6 +5,11 @@ import NativePatchCore from './NativePatchCore';
 import type { UpdateContext } from './UpdateContext';
 import { isSafePathComponent } from './PathUtils';
 import { monotonicNowMs } from './MonotonicClock';
+import {
+  ERROR_DOWNLOAD_FAILED,
+  createUpdateError,
+  getErrorMessage,
+} from './ErrorCodes';
 
 // 原生冷启动检测(NATIVE_CHECKUPDATE_DESIGN §10):每进程一次,getBundleUrl
 // 后延迟数秒运行,完全不依赖 app bundle——坏热更把 JS 砸挂后,下次启动仍能
@@ -69,10 +74,19 @@ interface DecisionAttempt {
   urls?: string[];
 }
 
+interface DecisionInfoConfig {
+  forceBoot?: boolean;
+}
+
 interface DecisionInfo {
   name?: string;
   description?: string;
   metaInfo?: string;
+  // 服务端按版本下发的配置(forceBoot = 救砖指令)。
+  config?: DecisionInfoConfig;
+  // 写进 hash 信息:这个版本是被救援通道送进来的,JS 在 markSuccess 时据此
+  // 上报 forceBootRescue 回执(与 Android/iOS 一致)。
+  forceBootRescue?: boolean;
 }
 
 interface Decision {
@@ -130,7 +144,7 @@ export function scheduleNativeCheck(
     }
     runOnce(context, launchRolledBackVersion).catch((e: Object) => {
       // 救援路径自身绝不能把应用拖垮。
-      logger.error(TAG, `native check failed: ${e}`);
+      logger.error(TAG, `native check failed: ${getErrorMessage(e)}`);
     });
   }, delayMs);
 }
@@ -161,7 +175,16 @@ async function runOnce(
     return;
   }
   // 从这里起本轮开始做真实工作:留下面包屑,死于轮中时下次启动零延迟续传。
-  context.setKv(KEY_ROUND_INCOMPLETE, '1');
+  logger.info(
+    TAG,
+    `round started (resume=${!!context.getKv(KEY_ROUND_INCOMPLETE)})`,
+  );
+  // 面包屑只是"下次零延迟"的优化:落盘失败不能阻止救援轮次本身。
+  try {
+    await context.setKv(KEY_ROUND_INCOMPLETE, '1');
+  } catch (e) {
+    logger.warn(TAG, `cannot persist round marker: ${getErrorMessage(e)}`);
+  }
   try {
     await runConfiguredRound(
       context,
@@ -172,10 +195,35 @@ async function runOnce(
       appKey,
     );
   } finally {
-    context.removeKv(KEY_ROUND_INCOMPLETE);
+    try {
+      await context.removeKv(KEY_ROUND_INCOMPLETE);
+    } catch (e) {
+      // 残留标记只意味着下次启动少等 5 秒。
+      logger.warn(TAG, `cannot clear round marker: ${getErrorMessage(e)}`);
+    }
   }
 }
 
+// 配置端点全为 https 时,网络下发的端点列表/制品 URL 一律拒绝明文 http:
+// @ohos.net.http 内部跟随重定向且不暴露最终 URL,这是鸿蒙侧唯一能做的
+// https→http 降级防线(SR-1);其余依赖宿主 network_config.json 的
+// cleartextTrafficPermitted:false(见 harmony/pushy/src/README.md)。
+function isHttpsOnly(config: NativeConfig): boolean {
+  const endpoints = config.endpoints ?? [];
+  return (
+    endpoints.length > 0 &&
+    endpoints.every(endpoint => isHttpsUrl(endpoint))
+  );
+}
+
+function isHttpsUrl(url: string): boolean {
+  return typeof url === 'string' && url.toLowerCase().startsWith('https://');
+}
+
+function isCleartextUrl(url: string): boolean {
+  return typeof url === 'string' && url.toLowerCase().startsWith('http://');
+}
+
 async function runConfiguredRound(
   context: UpdateContext,
   launchRolledBackVersion: string,
@@ -222,9 +270,10 @@ async function runConfiguredRound(
     return;
   }
 
-  const responseText = await runCheckRequest(config, appKey, body);
+  const httpsOnly = isHttpsOnly(config);
+  const responseText = await runCheckRequest(config, appKey, body, httpsOnly);
   if (!responseText) {
-    logger.debug(TAG, 'no endpoint reachable, giving up until next launch');
+    logger.warn(TAG, 'no endpoint reachable, giving up until next launch');
     return;
   }
   // Anchor cache freshness to response arrival, before download/patch work.
@@ -240,32 +289,38 @@ async function runConfiguredRound(
   }
   const decision = JSON.parse(decisionJson) as Decision;
   if (decision.action !== 'download') {
-    context.commitNativeCheckResult(
+    await context.commitNativeCheckResult(
       resetGeneration,
       '',
       '',
       false,
       buildResponseCacheJson(configJson, body, responseText, responseAtSeconds),
     );
-    logger.debug(TAG, `nothing to do (${decision.reason ?? ''})`);
+    logger.info(TAG, `nothing to do (${decision.reason ?? ''})`);
     return;
   }
   const hash = decision.hash ?? '';
   if (!isSafePathComponent(hash)) {
+    logger.warn(TAG, 'decision carries an unsafe hash, ignoring');
     return;
   }
 
   let downloaded = context.hasDownloadedVersion(hash);
-  if (!downloaded) {
+  if (downloaded) {
+    logger.info(TAG, `${hash} already installed, skipping download`);
+  } else {
+    logger.info(TAG, `downloading ${hash}`);
     downloaded = await performAttempts(
       context,
       decision.attempts ?? [],
       hash,
       currentVersion,
+      httpsOnly,
     );
   }
   if (!downloaded) {
-    context.commitNativeCheckResult(
+    logger.warn(TAG, `all download attempts for ${hash} failed`);
+    await context.commitNativeCheckResult(
       resetGeneration,
       '',
       '',
@@ -289,6 +344,12 @@ async function runConfiguredRound(
     if (typeof info.metaInfo === 'string') {
       hashInfo.metaInfo = info.metaInfo;
     }
+    // forceBoot 激活就是救砖路径:记进持久化元信息,这个版本活到 markSuccess
+    // 时 JS 上报 forceBootRescue。只认服务端下发的指令——静默策略的激活是
+    // 普通投递(Android/iOS 同一规则)。
+    if (info.config && info.config.forceBoot) {
+      hashInfo.forceBootRescue = true;
+    }
     hashInfoJson = JSON.stringify(hashInfo);
   }
 
@@ -298,7 +359,7 @@ async function runConfiguredRound(
   const activate = decision.activate === true;
   let committed = false;
   try {
-    committed = context.commitNativeCheckResult(
+    committed = await context.commitNativeCheckResult(
       resetGeneration,
       hash,
       hashInfoJson,
@@ -306,15 +367,15 @@ async function runConfiguredRound(
       buildResponseCacheJson(configJson, body, responseText, responseAtSeconds),
     );
   } catch (e) {
-    logger.error(TAG, `commit failed: ${e}`);
+    logger.error(TAG, `commit failed: ${getErrorMessage(e)}`);
     return;
   }
   if (!committed) {
-    logger.debug(TAG, 'reset during round, dropping result');
+    logger.warn(TAG, 'reset during round, dropping result');
   } else if (activate) {
-    logger.debug(TAG, `downloaded ${hash} and set for next launch`);
+    logger.info(TAG, `downloaded ${hash} and set for next launch`);
   } else {
-    logger.debug(TAG, `downloaded ${hash}, activation left to JS`);
+    logger.info(TAG, `downloaded ${hash}, activation left to JS`);
   }
 }
 
@@ -396,6 +457,7 @@ async function runCheckRequest(
   config: NativeConfig,
   appKey: string,
   body: string,
+  httpsOnly: boolean,
 ): Promise<string | undefined> {
   const orderedJson = NativePatchCore.orderEndpointCandidates(
     JSON.stringify(config.endpoints ?? []),
@@ -450,6 +512,11 @@ async function runCheckRequest(
       if (!base || tried.has(base)) {
         continue;
       }
+      if (httpsOnly && !isHttpsUrl(base)) {
+        // 远程注入的端点不得把 https 配置降级成明文。
+        logger.warn(TAG, `ignoring non-https remote endpoint ${base}`);
+        continue;
+      }
       if (httpAttempts++ >= MAX_CHECK_HTTP_ATTEMPTS) {
         return undefined;
       }
@@ -475,12 +542,20 @@ async function runWithinDeadline(
 ): Promise<void> {
   const remainingMs = deadlineUptimeMs - monotonicNowMs();
   if (remainingMs <= 0) {
-    throw Error('Download phase deadline expired before start');
+    throw createUpdateError(
+      ERROR_DOWNLOAD_FAILED,
+      'Download phase deadline expired before start',
+    );
   }
   let deadlineTimer = 0;
   const deadlinePromise = new Promise<void>((_, reject) => {
     deadlineTimer = setTimeout(() => {
-      reject(Error('Download phase deadline exceeded'));
+      reject(
+        createUpdateError(
+          ERROR_DOWNLOAD_FAILED,
+          'Download phase deadline exceeded',
+        ),
+      );
     }, remainingMs);
   });
   try {
@@ -498,6 +573,7 @@ async function performAttempts(
   attempts: DecisionAttempt[],
   hash: string,
   originHash: string,
+  httpsOnly: boolean,
 ): Promise<boolean> {
   const incrementalDeadline = monotonicNowMs() + DOWNLOAD_PHASE_TIMEOUT_MS;
   let fullDeadline = 0;
@@ -519,6 +595,11 @@ async function performAttempts(
       if (!url) {
         continue;
       }
+      if (httpsOnly && isCleartextUrl(url)) {
+        // 决策里的明文制品 URL 不得把 https 配置降级(SR-1)。
+        logger.warn(TAG, `ignoring cleartext ${type} url ${url}`);
+        continue;
+      }
       if (monotonicNowMs() >= deadline) {
         if (isFullAttempt) {
           return false;
@@ -544,7 +625,7 @@ async function performAttempts(
         }
         return true;
       } catch (e) {
-        logger.debug(TAG, `${type} attempt failed: ${e}`);
+        logger.warn(TAG, `${type} attempt failed: ${getErrorMessage(e)}`);
       }
     }
   }

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

@@ -74,16 +74,23 @@ interface NativePatchCoreBindings {
   ): ArchivePatchPlanResult;
   buildCopyGroups(copyFroms: string[], copyTos: string[]): CopyGroupResult[];
   applyPatchFromFileSource(options: FileSourcePatchRequest): Promise<void>;
+  /**
+   * 删除 rootDir 下超过 maxAgeDays 且名字不在 keepNames 里的条目(native
+   * 工作线程)。keepNames 必须包含所有可能仍在使用的版本:持久化的
+   * current/last 以及本进程实际启动的版本。
+   */
   cleanupOldEntries(
     rootDir: string,
-    keepCurrent: string,
-    keepPrevious: string,
+    keepNames: string[],
     maxAgeDays: number,
   ): Promise<void>;
   /** sha256(小写 hex)。同步:输入是已在内存的 rawfile bundle,哈希毫秒级 */
   sha256Hex(data: Uint8Array): string;
-  // 文件流式 SHA-256(小写 hex;不可读时空串),供安装记录使用。
+  // 文件流式 SHA-256(小写 hex;不可读时空串)。同步,仅限小文件——整包/
+  // 整 bundle 用下面的异步版本,避免冻结 UI 线程。
   sha256HexFile(path: string): string;
+  // 同上,在 libuv 工作线程计算;文件不可读时 reject。
+  sha256HexFileAsync(path: string): Promise<string>;
   /** CRC32(zip/zlib 多项式)。pdiff 拷贝前与 copiesCrc 比对用 */
   crc32(data: Uint8Array | ArrayBuffer): number;
   /** 原生 patch 内核可消费的 diff 轨道版本(2 = hdiffv2 轨道) */

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

@@ -1,6 +1,9 @@
+import { ERROR_INVALID_OPTIONS, createUpdateError } from './ErrorCodes';
+
 // Server-controlled identifiers are used as children of the update root. Keep
-// validation in a dependency-free module so startup orchestration and storage
-// code can share it without creating an import cycle.
+// validation in a dependency-light module (ErrorCodes.ts has no imports) so
+// startup orchestration and storage code can share it without creating an
+// import cycle.
 export function isSafePathComponent(name: string): boolean {
   return (
     typeof name === 'string' &&
@@ -15,7 +18,10 @@ export function isSafePathComponent(name: string): boolean {
 
 export function assertSafePathComponent(name: string): string {
   if (!isSafePathComponent(name)) {
-    throw Error(`Invalid path component: ${name}`);
+    throw createUpdateError(
+      ERROR_INVALID_OPTIONS,
+      `Invalid path component: ${name}`,
+    );
   }
   return name;
 }