rn-update 1.0.0

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

@@ -0,0 +1,123 @@
+/**
+ * [INPUT]: 依赖 librnupdate.so NAPI 默认导出与共享 C++ state/patch/update-flow 方法签名
+ * [OUTPUT]: 对外提供状态操作码、含成功确认匹配结果的 DTO、归档/请求接口和 NativePatchCore 收窄后的原生能力
+ * [POS]: Harmony 编译期/运行时原生防腐层，ArkTS 只通过此文件消费共享内核，不解析 NAPI 细节
+ */
+import NativeUpdateCore from 'librnupdate.so';
+
+export const STATE_OP_SWITCH_VERSION = 1;
+export const STATE_OP_MARK_SUCCESS = 2;
+export const STATE_OP_ROLLBACK = 3;
+export const STATE_OP_CLEAR_FIRST_TIME = 4;
+export const STATE_OP_CLEAR_ROLLBACK_MARK = 5;
+export const STATE_OP_RESOLVE_LAUNCH = 6;
+
+export const ARCHIVE_PATCH_TYPE_FULL = 1;
+export const ARCHIVE_PATCH_TYPE_FROM_PACKAGE = 2;
+export const ARCHIVE_PATCH_TYPE_FROM_PPK = 3;
+
+export interface StateCoreResult {
+  packageVersion?: string;
+  buildTime?: string;
+  currentVersion?: string;
+  lastVersion?: string;
+  firstTime: boolean;
+  firstTimeOk: boolean;
+  rolledBackVersion?: string;
+  changed?: boolean;
+  staleVersionToDelete?: string;
+  loadVersion?: string;
+  didRollback?: boolean;
+  consumedFirstTime?: boolean;
+  markSuccessAccepted?: boolean;
+}
+
+export interface ArchivePatchPlanResult {
+  mergeSourceSubdir?: string;
+  enableMerge: boolean;
+}
+
+export interface CopyGroupResult {
+  from: string;
+  toPaths: string[];
+}
+
+export interface FileSourcePatchRequest {
+  copyFroms: string[];
+  copyTos: string[];
+  deletes: string[];
+  sourceRoot: string;
+  targetRoot: string;
+  originBundlePath: string;
+  bundlePatchPath: string;
+  bundleOutputPath: string;
+  mergeSourceSubdir?: string;
+  enableMerge?: boolean;
+  /** __diff.json 中该 bundle patch 条目的 hbcTransform 元数据(原始 JSON) */
+  bundleHbcTransformMeta?: string;
+}
+
+interface NativePatchCoreBindings {
+  syncStateWithBinaryVersion(
+    packageVersion: string,
+    buildTime: string,
+    state: StateCoreResult,
+  ): StateCoreResult;
+  runStateCore(
+    operation: number,
+    state: StateCoreResult,
+    stringArg?: string,
+    flagA?: boolean,
+    flagB?: boolean,
+  ): StateCoreResult;
+  buildArchivePatchPlan(
+    patchType: number,
+    entryNames: string[],
+    copyFroms: string[],
+    copyTos: string[],
+    deletes: string[],
+    bundlePatchEntryName?: string,
+  ): ArchivePatchPlanResult;
+  buildCopyGroups(copyFroms: string[], copyTos: string[]): CopyGroupResult[];
+  applyPatchFromFileSource(options: FileSourcePatchRequest): Promise<void>;
+  /**
+   * 删除 rootDir 下超过 maxAgeDays 且名字不在 keepNames 里的条目(native
+   * 工作线程)。keepNames 必须包含所有可能仍在使用的版本:持久化的
+   * current/last 以及本进程实际启动的版本。
+   */
+  cleanupOldEntries(
+    rootDir: string,
+    keepNames: string[],
+    maxAgeDays: number,
+  ): Promise<void>;
+  /** sha256(小写 hex)。同步:输入是已在内存的 rawfile bundle,哈希毫秒级 */
+  sha256Hex(data: Uint8Array): string;
+  // 文件流式 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 轨道) */
+  getSupportedDiffVersion(): number;
+
+  // 更新流程决策层(cpp/update_flow_core,NATIVE_CHECKUPDATE_DESIGN §10):
+  // JSON 字符串进出,与决策层自身的边界一致。返回 undefined = 输入未通过
+  // 解析,编排器跳过本轮检测。
+  buildCheckRequestBody(inputJson: string): string | undefined;
+  orderEndpointCandidates(
+    endpointsJson: string,
+    randomSample: number,
+  ): string | undefined;
+  handleCheckResponse(
+    responseText: string,
+    identityJson: string,
+    afterDownload: string,
+  ): string | undefined;
+  // 响应 schema 门槛(update_flow_core::IsValidCheckResponse):200 但只带
+  // `{"error":...}` 的节点算失败,不得阻止继续 fallback。
+  isValidCheckResponse(responseText: string): boolean;
+}
+
+export default NativeUpdateCore as unknown as NativePatchCoreBindings;

package/harmony/pakta/src/main/ets/PaktaFileJSBundleProvider.ets

@@ -0,0 +1,54 @@
+/**
+ * [INPUT]: 依赖 RNOH JSBundleProvider、UIAbilityContext、file system 和 UpdateContext 的 bundle 选择
+ * [OUTPUT]: 对外提供 PaktaFileJSBundleProvider.getURL/getBundle/getAppKeys
+ * [POS]: Harmony bundle 生命周期适配器，负责把已选版本文件交给 RNOH，不执行下载或切包
+ */
+import {
+  FileJSBundle,
+  JSBundleProvider,
+  JSBundleProviderError,
+} from '@rnoh/react-native-openharmony';
+import common from '@ohos.app.ability.common';
+import fs from '@ohos.file.fs';
+import { UpdateContext } from './UpdateContext';
+
+export class PaktaFileJSBundleProvider extends JSBundleProvider {
+  private updateContext: UpdateContext;
+
+  constructor(context: common.UIAbilityContext) {
+    super();
+    this.updateContext = UpdateContext.getInstance(context);
+  }
+
+  getURL(): string {
+    return this.updateContext.getBundleUrl();
+  }
+
+  async getBundle(): Promise<FileJSBundle> {
+    const path = this.updateContext.getBundleUrl();
+    if (!path) {
+      throw new JSBundleProviderError({
+        whatHappened: 'No pakta bundle found. using default bundle',
+        howCanItBeFixed: [''],
+      });
+    }
+    try {
+      await fs.access(path, fs.OpenMode.READ_ONLY);
+      return {
+        filePath: path,
+      };
+    } catch (error) {
+      throw new JSBundleProviderError({
+        whatHappened: `Couldn't load JSBundle from ${path}`,
+        extraData: error,
+        howCanItBeFixed: [
+          `Check if a bundle exists at "${path}" on your device.`,
+        ],
+      });
+    }
+  }
+
+  getAppKeys(): string[] {
+    return [];
+  }
+}

package/harmony/pakta/src/main/ets/PaktaPackage.ets

@@ -0,0 +1,15 @@
+/**
+ * [INPUT]: 依赖 RNOH RNOHPackage 与 PaktaPackageFactory 工厂映射
+ * [OUTPUT]: 对外提供新 RNOH PaktaPackage，注册 Pakta TurboModule 工厂
+ * [POS]: Harmony 新架构 Package 注册边界，不承载更新状态或文件事务
+ */
+import {
+  RNOHPackage,
+} from '@rnoh/react-native-openharmony';
+import { createPaktaTurboModuleFactoryMap } from './PaktaPackageFactory';
+
+export class PaktaPackage extends RNOHPackage {
+  override getUITurboModuleFactoryByNameMap() {
+    return createPaktaTurboModuleFactoryMap();
+  }
+}

package/harmony/pakta/src/main/ets/PaktaPackageCompat.ts

@@ -0,0 +1,15 @@
+/**
+ * [INPUT]: 依赖旧 RNOH RNPackage/ts 类型与 PaktaPackageFactory 工厂映射
+ * [OUTPUT]: 对外提供兼容旧 RNOH 的 PaktaPackage
+ * [POS]: Harmony 旧宿主 Package 适配器，与新入口共享同一 TurboModule 构造逻辑
+ */
+import {
+  RNPackage,
+} from '@rnoh/react-native-openharmony/ts';
+import { createPaktaTurboModuleFactoryMap } from './PaktaPackageFactory';
+
+export class PaktaPackage extends RNPackage {
+  override getUITurboModuleFactoryByNameMap() {
+    return createPaktaTurboModuleFactoryMap();
+  }
+}

package/harmony/pakta/src/main/ets/PaktaPackageFactory.ts

@@ -0,0 +1,19 @@
+/**
+ * [INPUT]: 依赖旧 RNOH UITurboModule/Context 类型与 PaktaTurboModule.NAME/构造器
+ * [OUTPUT]: 对外提供 createPaktaTurboModuleFactoryMap，将 Pakta 名称映射到唯一实现
+ * [POS]: Harmony Package 与 TurboModule 的依赖倒置边界，集中模块发现避免新旧 Package 重复注册规则
+ */
+import {
+  UITurboModule,
+  UITurboModuleContext,
+} from '@rnoh/react-native-openharmony/ts';
+import { PaktaTurboModule } from './PaktaTurboModule';
+
+export function createPaktaTurboModuleFactoryMap(): Map<
+  string,
+  (ctx: UITurboModuleContext) => UITurboModule | null
+> {
+  return new Map<string, (ctx: UITurboModuleContext) => UITurboModule | null>([
+    [PaktaTurboModule.NAME, (ctx) => new PaktaTurboModule(ctx)],
+  ]);
+}

package/harmony/pakta/src/main/ets/PaktaTurboModule.ts

@@ -0,0 +1,433 @@
+/**
+ * [INPUT]: 依赖 RNOH UITurboModule、UIAbility/bundleManager、Logger/EventHub、NativePatchCore、UpdateContext、JS 冻结的启动版本身份与冷启动键
+ * [OUTPUT]: 对外提供 Pakta TurboModule 的常量（含不可变 channel）、版本状态、下载/切换/重载、版本绑定成功确认、配置缓存、bundleHash 与事件协议
+ * [POS]: Harmony JS-Native 应用服务门面，统一参数校验和错误映射，所有持久化/补丁行为委托 UpdateContext
+ */
+import {
+  UITurboModule,
+  UITurboModuleContext,
+} from '@rnoh/react-native-openharmony/ts';
+import common from '@ohos.app.ability.common';
+import { bundleManager } from '@kit.AbilityKit';
+import logger from './Logger';
+import NativePatchCore from './NativePatchCore';
+import { UpdateContext } from './UpdateContext';
+import { EventHub } from './EventHub';
+import {
+  KEY_CONFIG,
+  markJsCheckCompleted,
+  KEY_RESP_CACHE,
+} from './NativeCheckOrchestrator';
+import {
+  ERROR_FILE_OPERATION_FAILED,
+  ERROR_INVALID_HASH_INFO,
+  ERROR_INVALID_OPTIONS,
+  ERROR_MARK_SUCCESS_FAILED,
+  ERROR_RESET_FAILED,
+  ERROR_RESTART_FAILED,
+  ERROR_SWITCH_VERSION_FAILED,
+  ERROR_UNSUPPORTED_PLATFORM,
+  createUpdateError,
+  getErrorMessage,
+  toUpdateError,
+} from './ErrorCodes';
+
+export { getErrorMessage } from './ErrorCodes';
+
+const TAG = 'PaktaTurboModule';
+
+interface RestartWant {
+  bundleName: string;
+  abilityName?: string;
+}
+
+// applicationContext.restartApp 是 API 12 才有的可选能力,按结构探测。
+interface RestartableApplicationContext {
+  restartApp?: (want: RestartWant) => void;
+}
+
+interface ReloadEventEmitter {
+  emit(event: string, payload: Object): void;
+}
+
+// RNOH 的 devToolsController 不在公开的 UITurboModuleContext 类型里。
+interface DevToolsControllerHolder {
+  devToolsController?: { eventEmitter: ReloadEventEmitter };
+}
+
+export function validateHashInfo(info: string): void {
+  let valid = false;
+  try {
+    const parsed = JSON.parse(info) as Object | null;
+    valid = !!parsed && typeof parsed === 'object' && !Array.isArray(parsed);
+  } catch (e) {
+    valid = false;
+  }
+  if (!valid) {
+    throw createUpdateError(ERROR_INVALID_HASH_INFO, 'invalid json string');
+  }
+}
+
+export class PaktaTurboModule extends UITurboModule {
+  public static readonly NAME = 'Pakta';
+
+  mUiCtx: common.UIAbilityContext;
+  context: UpdateContext;
+
+  constructor(protected ctx: UITurboModuleContext) {
+    super(ctx);
+    if (ctx.isDebugModeEnabled) {
+      // 宿主处于 RN 调试模式:打开 debug 级日志,方便接入排查。
+      logger.setDebug(true);
+    }
+    logger.debug(TAG, ',PaktaTurboModule constructor');
+    this.mUiCtx = ctx.uiAbilityContext;
+    this.context = UpdateContext.getInstance(
+      this.mUiCtx,
+      ctx.isDebugModeEnabled,
+    );
+    EventHub.getInstance().setRNInstance(ctx.rnInstance);
+  }
+
+  // RNOH 销毁 TurboModule 时的钩子:释放对已销毁 RNInstance 的引用(只在
+  // EventHub 仍指向它时,见 EventHub.clearRNInstance)。
+  __onDestroy__(): void {
+    EventHub.getInstance().clearRNInstance(this.ctx.rnInstance);
+  }
+
+  private getBundleFlags(): bundleManager.BundleFlag {
+    return bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_REQUESTED_PERMISSION;
+  }
+
+  private requireHash(hash: string, methodName: string): string {
+    if (!hash) {
+      throw createUpdateError(
+        ERROR_INVALID_OPTIONS,
+        `${methodName}: empty hash`,
+      );
+    }
+    return hash;
+  }
+
+  private softReload(): void {
+    const holder = this.ctx as unknown as DevToolsControllerHolder;
+    const devToolsController = holder.devToolsController;
+    if (devToolsController) {
+      devToolsController.eventEmitter.emit('RELOAD', { reason: 'HotReload2' });
+    }
+  }
+
+  private async restartAbility(): Promise<void> {
+    const bundleInfo = await bundleManager.getBundleInfoForSelf(
+      this.getBundleFlags(),
+    );
+    const want: RestartWant = {
+      bundleName: bundleInfo.name,
+      abilityName: this.mUiCtx.abilityInfo?.name,
+    };
+    try {
+      const applicationContext =
+        this.mUiCtx.getApplicationContext() as unknown as RestartableApplicationContext;
+      if (applicationContext && typeof applicationContext.restartApp === 'function') {
+        logger.debug(TAG, 'restartAbility via applicationContext.restartApp');
+        applicationContext.restartApp(want);
+        return;
+      }
+    } catch (e) {
+      logger.error(TAG, `restartAbility via restartApp failed: ${getErrorMessage(e)}`);
+    }
+
+    logger.debug(TAG, 'restartAbility via startAbility fallback');
+    try {
+      await this.mUiCtx.startAbility(want);
+      await this.mUiCtx.terminateSelf();
+    } catch (e) {
+      logger.error(TAG, `restartAbility via startAbility/terminateSelf fallback failed: ${getErrorMessage(e)}`);
+      // Last resort: terminateSelf first
+      await this.mUiCtx.terminateSelf();
+      await this.mUiCtx.startAbility(want);
+    }
+  }
+
+  private async reloadBridge(): Promise<void> {
+    if (this.ctx.isDebugModeEnabled) {
+      logger.debug(TAG, 'reloadBridge via devToolsController RELOAD (debug mode)');
+      this.softReload();
+    } else {
+      logger.debug(TAG, 'reloadBridge via restartAbility (release mode)');
+      // If the process truly restarts, this timer dies with it. It only fires
+      // when the app is still alive after 1.5s — i.e. restartApp resolved but
+      // was silently suppressed (HarmonyOS rate-limits restarts within a few
+      // seconds of cold start / of a previous call) — which is exactly when the
+      // soft reload must take over. So the timer is NOT cleared on the success
+      // path, only in the catch branch where the soft reload runs immediately.
+      const fallbackTimer = setTimeout(() => {
+        logger.warn(TAG, 'restartAbility did not restart the app within 1.5s, triggering soft reload fallback');
+        this.softReload();
+      }, 1500);
+
+      try {
+        await this.restartAbility();
+      } catch (error) {
+        clearTimeout(fallbackTimer);
+        logger.error(TAG, `restartAbility failed: ${getErrorMessage(error)}, triggering soft reload fallback`);
+        this.softReload();
+      }
+    }
+  }
+
+  getConstants(): Object {
+    logger.debug(TAG, ',call getConstants');
+    this.context.logStateSnapshot('getConstants:enter');
+    const packageVersion = this.context.getPackageVersion();
+    const buildTime = this.context.getBuildTime();
+    this.context.syncStateWithBinaryVersion(packageVersion, buildTime);
+    const channel = this.context.getChannel();
+
+    const currentVersion = this.context.getCurrentVersion();
+    const currentVersionInfo = currentVersion
+      ? this.context.getKv(`hash_${currentVersion}`)
+      : '';
+    const currentBundleSha256 = this.context.currentBundleSha256(currentVersion);
+    const isFirstTime = this.context.consumeFirstLoadMarker();
+    const rolledBackVersion = this.context.rolledBackVersion();
+    const uuid = this.context.getKv('uuid');
+    const isUsingBundleUrl = this.context.getIsUsingBundleUrl();
+
+    if (rolledBackVersion) {
+      this.context.clearRollbackMark();
+    }
+
+    const result = {
+      downloadRootDir: `${this.mUiCtx.filesDir}/_update`,
+      currentVersionInfo,
+      currentBundleSha256,
+      packageVersion,
+      currentVersion,
+      buildTime,
+      channel,
+      isUsingBundleUrl,
+      isFirstTime,
+      rolledBackVersion,
+      uuid,
+      supportedDiffVersion: NativePatchCore.getSupportedDiffVersion(),
+    };
+    const logResult = {
+      downloadRootDir: result.downloadRootDir,
+      currentVersionInfo: result.currentVersionInfo,
+      packageVersion: result.packageVersion,
+      currentVersion: result.currentVersion,
+      buildTime: result.buildTime,
+      channel: result.channel,
+      isUsingBundleUrl: result.isUsingBundleUrl,
+      isFirstTime: result.isFirstTime,
+      rolledBackVersion: result.rolledBackVersion,
+      uuidSet: !!result.uuid,
+    };
+    logger.info(TAG, `,getConstants result: ${JSON.stringify(logResult)}`);
+    return result;
+  }
+
+  // 以下方法在 JS spec(src/NativePakta.ts)里都返回 Promise,C++ 方法表
+  // (PaktaTurboModule.cpp)相应用 PAKTA_ASYNC_METHOD 注册:同步注册会把
+  // ArkTS 的 Promise 变成空对象、把 reject 丢成 ArkTS 侧的 unhandled rejection。
+  // 每个拒绝都带稳定错误码(ErrorCodes.ts):`code` 属性 + `[CODE] ` 消息前缀。
+
+  async setLocalHashInfo(hash: string, info: string): Promise<void> {
+    logger.debug(TAG, ',call setLocalHashInfo');
+    this.requireHash(hash, 'setLocalHashInfo');
+    validateHashInfo(info);
+    try {
+      await this.context.setKv(`hash_${hash}`, info);
+    } catch (error) {
+      throw toUpdateError(error, ERROR_FILE_OPERATION_FAILED);
+    }
+  }
+
+  // 没有记录时返回 ''(iOS 同样 resolve nil):JS 侧把空值当 {}。只有存在
+  // 但不是 JSON 对象的记录才是 INVALID_HASH_INFO。
+  async getLocalHashInfo(hash: string): Promise<string> {
+    this.requireHash(hash, 'getLocalHashInfo');
+    const value = this.context.getKv(`hash_${hash}`);
+    if (!value) {
+      return '';
+    }
+    validateHashInfo(value);
+    return value;
+  }
+
+  async setUuid(uuid: string): Promise<void> {
+    logger.debug(TAG, ',call setUuid');
+    try {
+      await this.context.setKv('uuid', uuid);
+    } catch (error) {
+      throw toUpdateError(error, ERROR_FILE_OPERATION_FAILED);
+    }
+  }
+
+  // Provisioning for the native cold-start update check
+  // (NATIVE_CHECKUPDATE_DESIGN §10.1): the raw JSON persists as-is, parsed on
+  // read by the orchestrator; absent config = check disabled. Validated at
+  // write time — a corrupt config would otherwise silently disable the
+  // native check forever with no signal.
+  async syncNativeConfig(config: string): Promise<void> {
+    logger.debug(TAG, ',call syncNativeConfig');
+    try {
+      JSON.parse(config);
+    } catch (e) {
+      throw createUpdateError(
+        ERROR_INVALID_OPTIONS,
+        `syncNativeConfig: config is not valid JSON: ${getErrorMessage(e)}`,
+      );
+    }
+    try {
+      await this.context.setKv(KEY_CONFIG, config);
+    } catch (error) {
+      throw toUpdateError(error, ERROR_FILE_OPERATION_FAILED);
+    }
+  }
+
+  // JS 本进程已拿到有效检查响应:延迟的原生轮次据此跳过重复请求(§10.3)。
+  async markJsCheckCompleted(config: string): Promise<void> {
+    logger.debug(TAG, ',call markJsCheckCompleted');
+    if (typeof config !== 'string' || config.length === 0) {
+      throw createUpdateError(
+        ERROR_INVALID_OPTIONS,
+        'config must be a non-empty string',
+      );
+    }
+    markJsCheckCompleted(config);
+  }
+
+  // 原生冷启动检测落盘的原始响应缓存,JS 侧新鲜期内直接复用免二次请求
+  // (NATIVE_CHECKUPDATE_DESIGN §10.3)。缺省空串,永不 reject。
+  async getNativeCheckCache(): Promise<string> {
+    logger.debug(TAG, ',call getNativeCheckCache');
+    return this.context.getKv(KEY_RESP_CACHE) ?? '';
+  }
+
+  async reloadUpdate(options: { hash: string }): Promise<void> {
+    logger.debug(TAG, ',call reloadUpdate');
+    const hash = this.requireHash(options.hash, 'reloadUpdate');
+
+    // 切换必须真正落盘(switchVersion 内 await flush)后才重启:重启会立刻
+    // 杀进程,未落盘的切换就是"重启回旧 bundle"。
+    try {
+      await this.context.switchVersion(hash);
+    } catch (error) {
+      logger.error(TAG, `reloadUpdate switch failed: ${getErrorMessage(error)}`);
+      throw toUpdateError(error, ERROR_SWITCH_VERSION_FAILED);
+    }
+    try {
+      await this.reloadBridge();
+    } catch (error) {
+      logger.error(TAG, `reloadUpdate restart failed: ${getErrorMessage(error)}`);
+      throw toUpdateError(error, ERROR_RESTART_FAILED);
+    }
+  }
+
+  async restartApp(): Promise<void> {
+    logger.debug(TAG, ',call restartApp');
+    try {
+      await this.reloadBridge();
+    } catch (error) {
+      logger.error(TAG, `restartApp failed: ${getErrorMessage(error)}`);
+      throw toUpdateError(error, ERROR_RESTART_FAILED);
+    }
+  }
+
+  async setNeedUpdate(options: { hash: string }): Promise<void> {
+    logger.debug(TAG, ',call setNeedUpdate');
+    const hash = this.requireHash(options.hash, 'setNeedUpdate');
+
+    try {
+      await this.context.switchVersion(hash);
+    } catch (error) {
+      logger.error(TAG, `setNeedUpdate failed: ${getErrorMessage(error)}`);
+      throw toUpdateError(error, ERROR_SWITCH_VERSION_FAILED);
+    }
+  }
+
+  async markSuccess(expectedHash: string): Promise<boolean> {
+    logger.debug(TAG, ',call markSuccess');
+    try {
+      return await this.context.markSuccess(expectedHash);
+    } catch (error) {
+      logger.error(TAG, `markSuccess failed: ${getErrorMessage(error)}`);
+      throw toUpdateError(error, ERROR_MARK_SUCCESS_FAILED);
+    }
+  }
+
+  async getBundleHash(): Promise<string> {
+    logger.debug(TAG, ',call getBundleHash');
+    try {
+      return await this.context.getBundleHash();
+    } catch (error) {
+      // 空串 = "未知",服务端回退 buildTime 启发式;该方法永不 reject。
+      logger.error(TAG, `getBundleHash failed: ${getErrorMessage(error)}`);
+      return '';
+    }
+  }
+
+  async resetToPackagedBundle(): Promise<void> {
+    logger.debug(TAG, ',call resetToPackagedBundle');
+    try {
+      await this.context.resetToPackagedBundle();
+    } catch (error) {
+      logger.error(TAG, `resetToPackagedBundle failed: ${getErrorMessage(error)}`);
+      throw toUpdateError(error, ERROR_RESET_FAILED);
+    }
+  }
+
+  async downloadPatchFromPpk(options: {
+    updateUrl: string;
+    hash: string;
+    originHash: string;
+  }): Promise<void> {
+    logger.debug(TAG, ',call downloadPatchFromPpk');
+    return this.context.downloadPatchFromPpk(
+      options.updateUrl,
+      options.hash,
+      options.originHash,
+    );
+  }
+
+  async downloadPatchFromPackage(options: {
+    updateUrl: string;
+    hash: string;
+  }): Promise<void> {
+    logger.debug(TAG, ',call downloadPatchFromPackage');
+    return this.context.downloadPatchFromPackage(
+      options.updateUrl,
+      options.hash,
+    );
+  }
+
+  async downloadFullUpdate(options: {
+    updateUrl: string;
+    hash: string;
+  }): Promise<void> {
+    logger.debug(TAG, ',call downloadFullUpdate');
+    return this.context.downloadFullUpdate(options.updateUrl, options.hash);
+  }
+
+  async downloadAndInstallApk(_options: {
+    url: string;
+    target: string;
+    hash: string;
+  }): Promise<void> {
+    logger.debug(TAG, ',call downloadAndInstallApk');
+    throw createUpdateError(
+      ERROR_UNSUPPORTED_PLATFORM,
+      'downloadAndInstallApk is only supported on Android',
+    );
+  }
+
+  addListener(_eventName: string): void {
+    logger.debug(TAG, ',call addListener');
+  }
+
+  removeListeners(_count: number): void {
+    logger.debug(TAG, ',call removeListeners');
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * [INPUT]: 依赖服务端返回的版本/hash/文件名字符串与 ErrorCodes 错误构造，不引入平台 IO
+ * [OUTPUT]: 对外提供 isSafePathComponent 与 assertSafePathComponent，阻断路径穿越和空组件
+ * [POS]: Harmony 纯校验基础层，被 UpdateContext 与 NativeCheckOrchestrator 共享且不形成循环依赖
+ */
+import { ERROR_INVALID_OPTIONS, createUpdateError } from './ErrorCodes';
+
+// Server-controlled identifiers are used as children of the update root. Keep
+// 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' &&
+    name.length > 0 &&
+    name !== '.' &&
+    name !== '..' &&
+    !name.includes('/') &&
+    !name.includes('\\') &&
+    !name.includes('\0')
+  );
+}
+
+export function assertSafePathComponent(name: string): string {
+  if (!isSafePathComponent(name)) {
+    throw createUpdateError(
+      ERROR_INVALID_OPTIONS,
+      `Invalid path component: ${name}`,
+    );
+  }
+  return name;
+}