react-native-update 10.53.1 → 10.54.0

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

@@ -0,0 +1,83 @@
+import fileIo from '@ohos.file.fs';
+import statvfs from '@ohos.file.statvfs';
+
+// ArkTS mirror of cpp/patch_core/archive_limits.h — keep in sync by hand.
+// 损坏或恶意更新包的伤害上限:最多耗费有限的磁盘/内存/时间,绝不撑爆磁盘。
+export const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+export const MAX_TOTAL_UNCOMPRESSED_BYTES = 2048 * 1024 * 1024;
+export const MAX_ENTRY_BYTES = 512 * 1024 * 1024;
+export const MAX_ENTRIES = 20000;
+export const MAX_COMPRESSION_RATIO = 100;
+export const RATIO_CHECK_MIN_BYTES = 1 * 1024 * 1024;
+export const MAX_MANIFEST_BYTES = 16 * 1024 * 1024;
+export const FREE_DISK_MARGIN_BYTES = 64 * 1024 * 1024;
+
+/**
+ * 目标所在文件系统必须还能再写 bytesToWrite + 安全余量。取不到可用空间
+ * (返回 0/异常)视为未知,放行。
+ */
+export async function ensureFreeSpace(
+  target: string,
+  bytesToWrite: number,
+): Promise<void> {
+  let probe = target;
+  while (probe.length > 1 && !fileIo.accessSync(probe)) {
+    const slash = probe.lastIndexOf('/');
+    if (slash <= 0) {
+      return;
+    }
+    probe = probe.substring(0, slash);
+  }
+  let free = 0;
+  try {
+    free = await statvfs.getFreeSize(probe);
+  } catch (e) {
+    return;
+  }
+  if (free <= 0) {
+    return;
+  }
+  const needed = Math.max(0, bytesToWrite) + FREE_DISK_MARGIN_BYTES;
+  if (free < needed) {
+    throw Error(`insufficient disk space: need ${needed} bytes, have ${free}`);
+  }
+}
+
+export interface DirectoryMeasure {
+  entries: number;
+  bytes: number;
+}
+
+/**
+ * 递归统计目录里的条目数与总字节数;两者任一超过上限立即抛错(不必扫完)。
+ */
+export async function measureExtractedDirectory(
+  directory: string,
+  acc: DirectoryMeasure = { entries: 0, bytes: 0 },
+): Promise<DirectoryMeasure> {
+  const names = (await fileIo.listFile(directory)).filter(
+    name => name !== '.' && name !== '..',
+  );
+  for (const name of names) {
+    const path = `${directory}/${name}`;
+    const stat = await fileIo.stat(path);
+    acc.entries += 1;
+    if (acc.entries > MAX_ENTRIES) {
+      throw Error(`archive has too many entries (> ${MAX_ENTRIES})`);
+    }
+    if (stat.isDirectory()) {
+      await measureExtractedDirectory(path, acc);
+      continue;
+    }
+    if (stat.size > MAX_ENTRY_BYTES) {
+      throw Error(`archive entry too large: ${name} (${stat.size} bytes)`);
+    }
+    acc.bytes += stat.size;
+    if (acc.bytes > MAX_TOTAL_UNCOMPRESSED_BYTES) {
+      throw Error(
+        `archive expands beyond ${MAX_TOTAL_UNCOMPRESSED_BYTES} bytes`,
+      );
+    }
+  }
+  return acc;
+}

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

@@ -12,6 +12,18 @@ import NativePatchCore, {
   CopyGroupResult,
 } from './NativePatchCore';
 import { monotonicNowMs } from './MonotonicClock';
+import {
+  MAX_ARCHIVE_BYTES,
+  MAX_MANIFEST_BYTES,
+  ensureFreeSpace,
+  measureExtractedDirectory,
+} from './ArchiveLimits';
+import {
+  HARMONY_BUNDLE_FILE_NAME,
+  buildInstallRecord,
+  stagingDirectoryFor,
+  writeInstallRecord,
+} from './InstallRecord';
 
 export const VERSION_COMPLETE_FILE_NAME = '.pushy-complete';
 
@@ -144,6 +156,32 @@ export class DownloadTask {
   // 一经 downloadFile 正常返回即置位:之后的失败是 patch 应用失败,归档
   // 已被判定有毒,清理时必须连 sidecar 一起删,绝不能续传进同一个失败。
   private downloadPhaseCompleted = false;
+  // 下载归档的 SHA-256,解压前计算,写进完成记录。
+  private artifactSha256 = '';
+
+  // 两阶段安装(cpp/patch_core/install_record.h):解压/打补丁全部在
+  // <hash>.staging 里进行,写完完成记录后一次 rename 成 <hash>;失败或崩溃
+  // 都不会留下一个"看起来像版本"的半成品目录。
+  private stagingDirectory(params: DownloadTaskParams): string {
+    return stagingDirectoryFor(params.unzipDirectory);
+  }
+
+  private async promoteStaging(params: DownloadTaskParams): Promise<void> {
+    const work = this.stagingDirectory(params);
+    const bundlePath = `${work}/${HARMONY_BUNDLE_FILE_NAME}`;
+    if (!fileIo.accessSync(bundlePath)) {
+      throw Error(`bundle missing after install: ${bundlePath}`);
+    }
+    const bundleSha256 = NativePatchCore.sha256HexFile(bundlePath);
+    await writeInstallRecord(
+      work,
+      buildInstallRecord(params.hash, bundleSha256, this.artifactSha256),
+    );
+    if (fileIo.accessSync(params.unzipDirectory)) {
+      await this.removeDirectory(params.unzipDirectory);
+    }
+    await fileIo.rename(work, params.unzipDirectory);
+  }
 
   constructor(context: common.Context) {
     this.context = context;
@@ -267,6 +305,49 @@ export class DownloadTask {
     await this.ensureDirectory(parentPath);
   }
 
+  /**
+   * The completion marker is written by this SDK only, after the whole
+   * install succeeded. zlib.decompressFile offers no per-entry filter, so an
+   * archive that ships its own marker is detected right after extraction:
+   * the marker is removed (so the failure cleanup below cannot mistake the
+   * directory for a finished install) and the package is rejected.
+   */
+  private async rejectReservedEntries(unzipDirectory: string): Promise<void> {
+    const marker = `${unzipDirectory}/${VERSION_COMPLETE_FILE_NAME}`;
+    if (!fileIo.accessSync(marker)) {
+      return;
+    }
+    try {
+      await fileIo.unlink(marker);
+    } catch (e) {
+      // The directory is removed by the failure cleanup either way.
+    }
+    const error: Error & { code?: string } = Error(
+      `archive contains reserved entry ${VERSION_COMPLETE_FILE_NAME}`,
+    );
+    error.code = 'PATCH_FAILED';
+    throw error;
+  }
+
+  /**
+   * 解压 + 资源上限(cpp/patch_core/archive_limits.h)。zlib.decompressFile
+   * 没有逐条钩子:解压前按归档大小与 2 倍启发式查磁盘,解压后统计条目数与
+   * 总字节数(超限即失败,目录由失败清理删除),再拒绝保留条目。
+   */
+  private async extractArchive(
+    archiveFile: string,
+    unzipDirectory: string,
+  ): Promise<void> {
+    const archiveStat = await fileIo.stat(archiveFile);
+    if (archiveStat.size > MAX_ARCHIVE_BYTES) {
+      throw Error(`archive too large: ${archiveStat.size} bytes`);
+    }
+    await ensureFreeSpace(unzipDirectory, archiveStat.size * 2);
+    await zlib.decompressFile(archiveFile, unzipDirectory);
+    await measureExtractedDirectory(unzipDirectory);
+    await this.rejectReservedEntries(unzipDirectory);
+  }
+
   private async recreateDirectory(path: string): Promise<void> {
     await this.removeDirectory(path);
     await this.ensureDirectory(path);
@@ -353,6 +434,10 @@ export class DownloadTask {
       };
     }
 
+    const manifestStat = await fileIo.stat(manifestPath);
+    if (manifestStat.size > MAX_MANIFEST_BYTES) {
+      throw Error(`patch manifest too large: ${manifestStat.size} bytes`);
+    }
     return parseManifestToArrays(
       this.parseJsonEntry(await this.readFileContent(manifestPath)),
       normalizeResourceCopies,
@@ -553,6 +638,10 @@ export class DownloadTask {
 
     const enqueueWrite = (data: ArrayBuffer) => {
       received += data.byteLength;
+      if (!writeError && baseOffset + received > MAX_ARCHIVE_BYTES) {
+        // 未知长度/分块传输的兜底:超过上限即停写,请求在下面结算时失败。
+        writeError = Error(`archive too large: exceeded ${MAX_ARCHIVE_BYTES}`);
+      }
       writeQueue = writeQueue.then(async () => {
         if (!writer || writeError) {
           return;
@@ -771,6 +860,14 @@ export class DownloadTask {
           fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY,
         );
       }
+      if (totalAll > MAX_ARCHIVE_BYTES) {
+        writeError = Error(`archive too large: ${totalAll} bytes`);
+        throw writeError;
+      }
+      await ensureFreeSpace(
+        params.targetFile,
+        totalAll > 0 ? totalAll - baseOffset : 0,
+      );
       // 先落 sidecar 再放行写入,流中崩溃才有得续。
       const meta: ResumeMeta = { url: params.url };
       const etag = etagHeader || resumeMeta?.etag;
@@ -874,8 +971,10 @@ export class DownloadTask {
 
   private async doFullPatch(params: DownloadTaskParams): Promise<void> {
     await this.downloadFile(params);
-    await this.recreateDirectory(params.unzipDirectory);
-    await zlib.decompressFile(params.targetFile, params.unzipDirectory);
+    const work = this.stagingDirectory(params);
+    await this.recreateDirectory(work);
+    this.artifactSha256 = NativePatchCore.sha256HexFile(params.targetFile);
+    await this.extractArchive(params.targetFile, work);
     await this.deleteArchiveAndSidecar(params.targetFile);
   }
 
@@ -895,12 +994,14 @@ export class DownloadTask {
   private async doPatchFromAppAfterDownload(
     params: DownloadTaskParams,
   ): Promise<void> {
-    await this.recreateDirectory(params.unzipDirectory);
+    const work = this.stagingDirectory(params);
+    await this.recreateDirectory(work);
+    this.artifactSha256 = NativePatchCore.sha256HexFile(params.targetFile);
 
-    await zlib.decompressFile(params.targetFile, params.unzipDirectory);
+    await this.extractArchive(params.targetFile, work);
     const [entryNames, manifestArrays] = await Promise.all([
-      this.listEntryNames(params.unzipDirectory),
-      this.readManifestArrays(params.unzipDirectory, true),
+      this.listEntryNames(work),
+      this.readManifestArrays(work, true),
     ]);
 
     NativePatchCore.buildArchivePatchPlan(
@@ -912,7 +1013,7 @@ export class DownloadTask {
       HARMONY_BUNDLE_PATCH_ENTRY,
     );
 
-    const bundlePatchPath = `${params.unzipDirectory}/${HARMONY_BUNDLE_PATCH_ENTRY}`;
+    const bundlePatchPath = `${work}/${HARMONY_BUNDLE_PATCH_ENTRY}`;
     if (!fileIo.accessSync(bundlePatchPath)) {
       throw Error('bundle patch not found');
     }
@@ -922,9 +1023,9 @@ export class DownloadTask {
     );
     await this.applyBundlePatchFromFileSource(
       originContent.buffer as ArrayBuffer,
-      params.unzipDirectory,
+      work,
       bundlePatchPath,
-      `${params.unzipDirectory}/bundle.harmony.js`,
+      `${work}/${HARMONY_BUNDLE_FILE_NAME}`,
       manifestArrays.hbcTransformMeta,
     );
     // 组按 from 聚合;同一 from 的内容必然一致,所以每组一个 CRC 即可
@@ -941,7 +1042,7 @@ export class DownloadTask {
         manifestArrays.copyFroms,
         manifestArrays.copyTos,
       ),
-      params.unzipDirectory,
+      work,
       crcByFrom,
     );
     await this.deleteArchiveAndSidecar(params.targetFile);
@@ -961,12 +1062,14 @@ export class DownloadTask {
   private async doPatchFromPpkAfterDownload(
     params: DownloadTaskParams,
   ): Promise<void> {
-    await this.recreateDirectory(params.unzipDirectory);
+    const work = this.stagingDirectory(params);
+    await this.recreateDirectory(work);
+    this.artifactSha256 = NativePatchCore.sha256HexFile(params.targetFile);
 
-    await zlib.decompressFile(params.targetFile, params.unzipDirectory);
+    await this.extractArchive(params.targetFile, work);
     const [entryNames, manifestArrays] = await Promise.all([
-      this.listEntryNames(params.unzipDirectory),
-      this.readManifestArrays(params.unzipDirectory, false),
+      this.listEntryNames(work),
+      this.readManifestArrays(work, false),
     ]);
 
     const plan = NativePatchCore.buildArchivePatchPlan(
@@ -982,10 +1085,10 @@ export class DownloadTask {
       copyTos: manifestArrays.copyTos,
       deletes: manifestArrays.deletes,
       sourceRoot: params.originDirectory,
-      targetRoot: params.unzipDirectory,
+      targetRoot: work,
       originBundlePath: `${params.originDirectory}/bundle.harmony.js`,
-      bundlePatchPath: `${params.unzipDirectory}/${HARMONY_BUNDLE_PATCH_ENTRY}`,
-      bundleOutputPath: `${params.unzipDirectory}/bundle.harmony.js`,
+      bundlePatchPath: `${work}/${HARMONY_BUNDLE_PATCH_ENTRY}`,
+      bundleOutputPath: `${work}/${HARMONY_BUNDLE_FILE_NAME}`,
       mergeSourceSubdir: plan.mergeSourceSubdir,
       enableMerge: plan.enableMerge,
       bundleHbcTransformMeta: manifestArrays.hbcTransformMeta,
@@ -1147,10 +1250,7 @@ export class DownloadTask {
           throw Error(`Unknown task type: ${params.type}`);
       }
       if (isPatchTask) {
-        await this.writeFileContent(
-          `${params.unzipDirectory}/${VERSION_COMPLETE_FILE_NAME}`,
-          new Uint8Array(0),
-        );
+        await this.promoteStaging(params);
       }
     } catch (error: any) {
       console.error('Task execution failed:', error.message);
@@ -1159,15 +1259,11 @@ export class DownloadTask {
           if (params.type === DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD) {
             await fileIo.unlink(params.targetFile);
             await this.deleteResumeSidecar(params.targetFile);
-          } else if (
-            !fileIo.accessSync(
-              `${params.unzipDirectory}/${VERSION_COMPLETE_FILE_NAME}`,
-            ) ||
-            !fileIo.accessSync(`${params.unzipDirectory}/bundle.harmony.js`)
-          ) {
-            // Never let a failed duplicate task remove an install already
-            // handed off by an earlier task via marker + bundle.
-            await this.removeDirectory(params.unzipDirectory);
+          } else {
+            // Only the staging directory is ours to drop: the final version
+            // directory is never touched by a failed install, so a failed
+            // duplicate task cannot remove an earlier task's install.
+            await this.removeDirectory(this.stagingDirectory(params));
             if (this.downloadPhaseCompleted) {
               // 收齐后才失败的是解压/patch 失败:归档有毒,续传只会撞上
               // 同一个失败。下载阶段的失败则保留 partial + sidecar——那

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

@@ -0,0 +1,129 @@
+import fileIo from '@ohos.file.fs';
+import { util } from '@kit.ArkTS';
+import NativePatchCore from './NativePatchCore';
+
+// ArkTS mirror of cpp/patch_core/install_record.h — keep in sync by hand.
+// 两阶段安装的完成记录:作为安装最后一步写进 staging 目录,随后 staging
+// 原子 rename 成版本目录;激活前重新校验 bundle 摘要。空文件 = 旧版 SDK
+// 写的历史标记,仍视为完整安装(无摘要可验)。
+export const INSTALL_RECORD_SCHEMA = 1;
+export const INSTALL_RECORD_FILE_NAME = '.pushy-complete';
+export const STAGING_SUFFIX = '.staging';
+export const HARMONY_BUNDLE_FILE_NAME = 'bundle.harmony.js';
+
+export interface InstallRecordData {
+  schema?: number;
+  versionHash?: string;
+  bundleSha256?: string;
+  artifactSha256?: string;
+}
+
+export function stagingDirectoryFor(versionDir: string): string {
+  return `${versionDir}${STAGING_SUFFIX}`;
+}
+
+export function buildInstallRecord(
+  versionHash: string,
+  bundleSha256: string,
+  artifactSha256: string,
+): string {
+  const record: InstallRecordData = {
+    schema: INSTALL_RECORD_SCHEMA,
+    versionHash,
+  };
+  if (bundleSha256) {
+    record.bundleSha256 = bundleSha256;
+  }
+  if (artifactSha256) {
+    record.artifactSha256 = artifactSha256;
+  }
+  return JSON.stringify(record);
+}
+
+/** 写入并 fsync:紧随其后的 rename 必须能在盘上看到它。 */
+export async function writeInstallRecord(
+  versionDir: string,
+  recordJson: string,
+): Promise<void> {
+  const path = `${versionDir}/${INSTALL_RECORD_FILE_NAME}`;
+  if (fileIo.accessSync(path)) {
+    await fileIo.unlink(path);
+  }
+  const file = await fileIo.open(
+    path,
+    fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY,
+  );
+  try {
+    const bytes = new util.TextEncoder().encodeInto(recordJson);
+    await fileIo.write(file.fd, bytes.buffer as ArrayBuffer);
+    await fileIo.fsync(file.fd);
+  } finally {
+    await fileIo.close(file);
+  }
+}
+
+/**
+ * 解析记录:文件缺失/畸形返回 null;空文件(历史标记)返回 {}。
+ */
+export function readInstallRecord(versionDir: string): InstallRecordData | null {
+  const path = `${versionDir}/${INSTALL_RECORD_FILE_NAME}`;
+  if (!fileIo.accessSync(path)) {
+    return null;
+  }
+  try {
+    const stat = fileIo.statSync(path);
+    if (stat.size === 0) {
+      return {};
+    }
+    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;
+  } catch (e) {
+    return null;
+  }
+}
+
+/** 存在性判定(启动/去重路径,不算摘要):记录存在且(非历史空文件时)指向本版本。 */
+export function isInstallComplete(versionDir: string, versionHash: string): boolean {
+  const record = readInstallRecord(versionDir);
+  if (record === null) {
+    return false;
+  }
+  if (Object.keys(record).length === 0) {
+    return true;
+  }
+  return (
+    record.schema === INSTALL_RECORD_SCHEMA && record.versionHash === versionHash
+  );
+}
+
+/** 激活前校验:记录带摘要时重新计算 bundle 摘要;不通过则抛错说明原因。 */
+export function verifyInstallForActivation(
+  versionDir: string,
+  versionHash: string,
+  bundlePath: string,
+): void {
+  const record = readInstallRecord(versionDir);
+  if (record === null) {
+    throw Error(`Bundle version ${versionHash} has no valid completion record.`);
+  }
+  if (Object.keys(record).length === 0) {
+    return;
+  }
+  if (
+    record.schema !== INSTALL_RECORD_SCHEMA ||
+    record.versionHash !== versionHash
+  ) {
+    throw Error(`Bundle version ${versionHash} completion record mismatch.`);
+  }
+  if (!record.bundleSha256) {
+    return;
+  }
+  const actual = NativePatchCore.sha256HexFile(bundlePath);
+  if (actual.toLowerCase() !== record.bundleSha256.toLowerCase()) {
+    throw Error(`Bundle version ${versionHash} bundle digest mismatch.`);
+  }
+}

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

@@ -92,6 +92,22 @@ interface RespCacheEntry {
 }
 
 let scheduled = false;
+// JS 在本进程内已拿到有效检查响应时对应的配置 JSON(markJsCheckCompleted)。
+// 进程级:下次启动无信号,冷启动轮次照常运行。
+let jsCompletedConfig: string | undefined;
+
+export function markJsCheckCompleted(config: string): void {
+  jsCompletedConfig = config;
+}
+
+// JS 已用与原生完全相同的配置拿到有效响应(§10.3):延迟轮次就是一次重复请求。
+// 只有计划内的轮次会问这个问题——JS 没起来、启动即崩、检查失败时都不会有信号。
+function isJsCheckCompleted(context: UpdateContext): boolean {
+  return (
+    jsCompletedConfig !== undefined &&
+    jsCompletedConfig === context.getKv(KEY_CONFIG)
+  );
+}
 
 export function scheduleNativeCheck(
   context: UpdateContext,
@@ -105,6 +121,13 @@ export function scheduleNativeCheck(
   // 除非上个进程死于轮中(残留标记),那时每一秒启动时间都要用来续传。
   const delayMs = context.getKv(KEY_ROUND_INCOMPLETE) ? 0 : START_DELAY_MS;
   setTimeout(() => {
+    if (isJsCheckCompleted(context)) {
+      logger.info(
+        TAG,
+        'native check skipped: JS check completed in this process',
+      );
+      return;
+    }
     runOnce(context, launchRolledBackVersion).catch((e: Object) => {
       // 救援路径自身绝不能把应用拖垮。
       logger.error(TAG, `native check failed: ${e}`);
@@ -315,8 +338,7 @@ function isValidCheckResponse(responseText: string | undefined): boolean {
     return false;
   }
   try {
-    const parsed = JSON.parse(responseText) as Object | null;
-    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
+    return NativePatchCore.isValidCheckResponse(responseText);
   } catch (e) {
     return false;
   }

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

@@ -82,6 +82,8 @@ interface NativePatchCoreBindings {
   ): Promise<void>;
   /** sha256(小写 hex)。同步:输入是已在内存的 rawfile bundle,哈希毫秒级 */
   sha256Hex(data: Uint8Array): string;
+  // 文件流式 SHA-256(小写 hex;不可读时空串),供安装记录使用。
+  sha256HexFile(path: string): string;
   /** CRC32(zip/zlib 多项式)。pdiff 拷贝前与 copiesCrc 比对用 */
   crc32(data: Uint8Array | ArrayBuffer): number;
   /** 原生 patch 内核可消费的 diff 轨道版本(2 = hdiffv2 轨道) */
@@ -100,6 +102,9 @@ interface NativePatchCoreBindings {
     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/pushy/src/main/ets/PushyTurboModule.ts

@@ -10,6 +10,7 @@ import { UpdateContext } from './UpdateContext';
 import { EventHub } from './EventHub';
 import {
   KEY_CONFIG,
+  markJsCheckCompleted,
   KEY_RESP_CACHE,
 } from './NativeCheckOrchestrator';
 
@@ -136,6 +137,7 @@ export class PushyTurboModule extends UITurboModule {
     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');
@@ -148,6 +150,7 @@ export class PushyTurboModule extends UITurboModule {
     const result = {
       downloadRootDir: `${this.mUiCtx.filesDir}/_update`,
       currentVersionInfo,
+      currentBundleSha256,
       packageVersion,
       currentVersion,
       buildTime,
@@ -201,6 +204,15 @@ export class PushyTurboModule extends UITurboModule {
     this.context.setKv(KEY_CONFIG, config);
   }
 
+  // JS 本进程已拿到有效检查响应:延迟的原生轮次据此跳过重复请求(§10.3)。
+  async markJsCheckCompleted(config: string): Promise<void> {
+    logger.debug(TAG, ',call markJsCheckCompleted');
+    if (typeof config !== 'string' || config.length === 0) {
+      throw Error('config must be a non-empty string');
+    }
+    markJsCheckCompleted(config);
+  }
+
   // 原生冷启动检测落盘的原始响应缓存,JS 侧新鲜期内直接复用免二次请求
   // (NATIVE_CHECKUPDATE_DESIGN §10.3)。缺省空串,永不 reject。
   async getNativeCheckCache(): Promise<string> {