react-native-update 10.59.2 → 10.61.0

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

@@ -5,107 +5,87 @@ import NativePatchCore from './NativePatchCore';
 import type { UpdateContext } from './UpdateContext';
 import { BundlePreparationRound, bundlePreparationResult } from './BundlePreparationResult';
 import type { BundlePreparationResult } from './BundlePreparationResult';
-import { isSafePathComponent } from './PathUtils';
-import { QUERY_PATH, STATUS_NONE } from './Texts';
 import { monotonicNowMs } from './MonotonicClock';
-import {
-  ERROR_DOWNLOAD_FAILED,
-  createPushyError,
-  getErrorMessage,
-} from './ErrorCodes';
+import { PushyError, getErrorMessage } from './ErrorCodes';
 
 // 原生冷启动检测(NATIVE_CHECKUPDATE_DESIGN §10):每进程一次,getBundleUrl
 // 后延迟数秒运行,完全不依赖 app bundle——坏热更把 JS 砸挂后,下次启动仍能
-// 拉到修复版。决策全部来自 cpp/update_flow_core(经 NativePatchCore 的
-// NAPI 面),本文件只是 IO 胶水。失败静默且有界:每次启动至多一轮,无重试
+// 拉到修复版。轮次本身由共享引擎驱动(cpp/update_flow_core/round_engine.h,
+// 经 NativePatchCore.stepRound,NATIVE_CHECKUPDATE_DESIGN §12),本文件只
+// 执行它要求的 IO。失败静默且有界:每次启动至多一轮,无重试
 // 风暴,不拉黑版本。
 // 鸿蒙的 debug 门控由触发点天然承担:dev 走 MetroJSBundleProvider,
 // PushyFileJSBundleProvider.getBundleUrl 不会被调用。
 const TAG = 'NativeSync';
+// 与 Android 共用的存储键。鸿蒙不做 crash-hold(errorManager 的同步回调驱动
+// 不了 ArkTS 异步网络 IO),续传 + 零延迟标记是收敛砖机的全部机制。
+// <generated:storage-keys> (scripts/contract.ts; bun scripts/generate-contract.ts)
+// The persisted native check config (JS syncNativeConfig or the host).
 export const KEY_CONFIG = 'nativeConfig';
-// 供 JS 侧复用的原始响应缓存(§10.3),同时记录请求与配置指纹以限定命中范围。
+// Raw response cache for the JS side to reuse (§10.3), scoped to the exact
+// logical request and native config that produced it.
 export const KEY_RESP_CACHE = 'nativeCheckResp';
-// 轮次开始落盘、结束清除(§11.4)。下次启动读到残留 = 上个进程死于轮中
-// (砖机的签名),该次启动跳过 5s 延迟立即续传。鸿蒙本版不做 crash-hold
-// (errorManager 的同步回调驱动不了 ArkTS 异步网络 IO),续传 + 零延迟
-// 标记是收敛砖机的全部机制。
+// Set when a round starts, cleared when it ends (§11.4). Residue on the
+// next launch means the previous process died mid-round: that launch
+// resumes immediately instead of waiting 5s.
 export const KEY_ROUND_INCOMPLETE = 'nativeCheckIncomplete';
-const REQUEST_TIMEOUT_MS = 10000;
-const REQUEST_CALL_TIMEOUT_MS = 15000;
-const MAX_QUERY_HTTP_ATTEMPTS = 8;
+// </generated:storage-keys>
 const START_DELAY_MS = 5000;
-const DOWNLOAD_PHASE_TIMEOUT_MS = 10 * 60 * 1000;
-const DOWNLOAD_TYPE_DIFF = 'diff';
-const DOWNLOAD_TYPE_PDIFF = 'pdiff';
 
-interface NativeConfig {
-  appKey?: string;
-  packageVersion?: string;
-  endpoints?: string[];
-  queryUrls?: string[];
-  afterDownload?: string;
-  rnu?: string;
-  rn?: string;
-  disabled?: boolean;
-}
-
-interface FlowIdentity {
+// 本次启动的事实,交给共享内核(cpp/update_flow_core/native_round.h)。
+interface RoundEnv {
   packageVersion: string;
-  currentVersion?: string;
-  uuid: string;
-  rolledBackVersion?: string;
-}
-
-interface FlowCInfo {
-  rnu: string;
-  rn: string;
-  os: string;
+  currentVersion: string;
   uuid: string;
-}
-
-interface FlowInput {
-  packageVersion: string;
-  currentVersion?: string;
+  rolledBackVersion: string;
   buildTime: string;
-  cInfo: FlowCInfo;
-  supportedDiffVersion: number;
+  os: string;
   bundleHash: string;
 }
 
-interface DecisionAttempt {
+// 引擎的事件与命令(字段含义见 round_engine.h)。
+interface RoundEvent {
   type?: string;
-  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;
+  now?: number;
+  config?: string;
+  resetGeneration?: number;
+  configGeneration?: number;
+  sample?: number;
+  deadline?: number;
+  env?: RoundEnv;
+  text?: string;
+  at?: number;
+  installed?: boolean;
+  ok?: boolean;
+  code?: string;
+  timedOut?: boolean;
+  reason?: string;
+  error?: boolean;
 }
 
-interface Decision {
-  action?: string;
-  reason?: string;
+interface RoundCommand {
+  type: string;
+  url?: string;
+  post?: boolean;
+  body?: string;
+  timeoutMs?: number;
+  callTimeoutMs?: number;
   hash?: string;
-  attempts?: DecisionAttempt[];
+  strategy?: string;
+  originHash?: string;
+  deadline?: number;
+  hashInfo?: string;
   activate?: boolean;
-  info?: DecisionInfo;
+  cache?: string;
+  resetGeneration?: number;
+  status?: string;
+  reason?: string;
+  activated?: boolean;
 }
 
-interface RespCacheEntry {
-  ts: number;
-  body: string;
-  request: string;
-  config: string;
+interface RoundStep {
+  state: Object;
+  commands: RoundCommand[];
 }
 
 let scheduled = false;
@@ -137,57 +117,75 @@ function startNativeRound(
   });
 }
 
+interface ConfigRead {
+  json: string;
+  /** Set when the persisted configuration cannot start a round. */
+  rejection?: BundlePreparationResult;
+}
+
+// The single configuration gate shared by the preflight, the host API and
+// the round itself, so the three can never disagree about what is runnable.
+// The verdict is the shared core's (cpp/update_flow_core ParseRunnableConfig,
+// also used by Android and iOS).
+interface RunnableVerdict {
+  status?: string;
+  reason?: string;
+}
+
+function readNativeConfig(context: UpdateContext): ConfigRead {
+  const json = context.getKv(KEY_CONFIG);
+  const verdict = JSON.parse(NativePatchCore.runnableConfig(json)) as RunnableVerdict;
+  if (verdict.status !== undefined) {
+    return {
+      json,
+      rejection: bundlePreparationResult(verdict.status, verdict.reason ?? ''),
+    };
+  }
+  return { json };
+}
+
 // A preflight skip must not consume the process's only round: configuration
 // may arrive after the delayed startup timer on a first-ever launch.
 function configurationError(context: UpdateContext): BundlePreparationResult | undefined {
-  const json = context.getKv(KEY_CONFIG);
-  if (!json) {
-    return bundlePreparationResult('skipped', 'not_configured');
-  }
-  try {
-    const config = JSON.parse(json) as NativeConfig;
-    if (!config || typeof config !== 'object' || Array.isArray(config)) {
-      return bundlePreparationResult('failed', 'invalid_config');
-    }
-    if (config.disabled) {
-      return bundlePreparationResult('skipped', 'disabled');
-    }
-    if (typeof config.appKey !== 'string' || config.appKey.trim().length === 0) {
-      return bundlePreparationResult('failed', 'invalid_config');
-    }
-  } catch (e) {
-    return bundlePreparationResult('failed', 'invalid_config');
-  }
-  return undefined;
+  return readNativeConfig(context).rejection;
 }
 
+// timeoutMs bounds how long the host waits, as iOS/Android's
+// prepareBundle(timeout): on expiry the result is failed/timeout and the round
+// keeps running (its result still applies to the next launch). Without one the
+// host waits for the round; nothing blocks meanwhile (single-threaded ArkTS).
 export async function prepareBundleNative(
   context: UpdateContext,
+  timeoutMs?: number,
 ): Promise<BundlePreparationResult> {
   if (scheduledContext !== context) {
     return bundlePreparationResult('skipped', 'not_initialized');
   }
-  const configJson = context.getKv(KEY_CONFIG);
-  if (!configJson) {
-    return bundlePreparationResult('skipped', 'not_configured');
+  const read = readNativeConfig(context);
+  if (read.rejection !== undefined) {
+    return read.rejection;
   }
-  try {
-    const config = JSON.parse(configJson) as NativeConfig;
-    if (!config || typeof config !== 'object' || Array.isArray(config)) {
-      return bundlePreparationResult('failed', 'invalid_config');
-    }
-    if (config.disabled) {
-      return bundlePreparationResult('skipped', 'disabled');
-    }
-    if (typeof config.appKey !== 'string' || !config.appKey) {
-      return bundlePreparationResult('failed', 'invalid_config');
+  const configJson = read.json;
+  const round = startNativeRound(context, scheduledRollback);
+  let result: BundlePreparationResult;
+  if (timeoutMs === undefined) {
+    result = await round;
+  } else {
+    let timer: number | undefined;
+    const expired = new Promise<undefined>((resolve) => {
+      timer = setTimeout(() => resolve(undefined), Math.max(0, timeoutMs));
+    });
+    const settled = await Promise.race([round, expired]);
+    clearTimeout(timer);
+    if (settled === undefined) {
+      return bundlePreparationResult('failed', 'timeout');
     }
-  } catch (e) {
-    return bundlePreparationResult('failed', 'invalid_config');
+    result = settled;
   }
-  const result = await startNativeRound(context, scheduledRollback);
+  // 与引擎的 HostCancellation 同一规则:三方 C1 等价且配置代数未变。
   if (roundConfigGeneration !== context.getNativeConfigGeneration()
-      || configJson !== roundConfigJson || configJson !== context.getKv(KEY_CONFIG)) {
+      || !NativePatchCore.configsEquivalent(configJson, roundConfigJson)
+      || !context.isStoredNativeConfig(configJson)) {
     return bundlePreparationResult('cancelled', 'config_changed');
   }
   if (roundGeneration !== context.getResetGeneration()) {
@@ -205,13 +203,11 @@ export function recordJsRound(config: string): void {
   jsCompletedConfig = config;
 }
 
-// JS 已用与原生完全相同的配置拿到有效响应(§10.3):延迟轮次就是一次重复请求。
+// JS 已用与原生等价的配置(C1:规范形式相同,而非逐字相同——宿主持有的配置
+// 与 JS 序列化格式不同)拿到有效响应(§10.3):延迟轮次就是一次重复请求。
 // 只有计划内的轮次会问这个问题——JS 没起来、启动即崩、检查失败时都不会有信号。
 function hasJsRound(context: UpdateContext): boolean {
-  return (
-    jsCompletedConfig !== undefined &&
-    jsCompletedConfig === context.getKv(KEY_CONFIG)
-  );
+  return !!jsCompletedConfig && context.isStoredNativeConfig(jsCompletedConfig);
 }
 
 export function scheduleNativeSync(
@@ -246,286 +242,220 @@ async function runOnce(
   context: UpdateContext,
   launchRolledBackVersion: string,
 ): Promise<void> {
-  // 在任何 IO 之前采样:resetToPackagedBundle 会递增它,本轮运行期间发生的
-  // reset 必须赢过本轮的决策。
+  // 在任何 IO 之前采样:resetToPackagedBundle 与配置替换都会递增 reset 代数,
+  // 本轮运行期间发生的 reset 必须赢过本轮的决策。
   const resetGeneration = context.getResetGeneration();
+  const configGeneration = context.getNativeConfigGeneration();
   roundGeneration = resetGeneration;
-  roundConfigGeneration = context.getNativeConfigGeneration();
+  roundConfigGeneration = configGeneration;
   roundResult = bundlePreparationResult('failed', 'check_failed');
   const configJson = context.getKv(KEY_CONFIG);
   roundConfigJson = configJson;
-  if (!configJson) {
-    // No persisted configuration: report the rollout gate to native callers.
-    roundResult = bundlePreparationResult('skipped', 'not_configured');
-    return;
-  }
-  let config: NativeConfig;
+
+  let event: RoundEvent = {
+    type: 'start',
+    config: configJson ?? '',
+    resetGeneration,
+    configGeneration,
+    sample: Math.random(),
+    deadline: 0,
+  };
+  let state: string | undefined = undefined;
+  let marked = false;
   try {
-    config = JSON.parse(configJson) as NativeConfig;
-    if (!config || typeof config !== 'object' || Array.isArray(config)) {
-      roundResult = bundlePreparationResult('failed', 'invalid_config');
-      return;
+    for (;;) {
+      event.now = monotonicNowMs();
+      const step = JSON.parse(
+        NativePatchCore.stepRound(state, JSON.stringify(event)),
+      ) as RoundStep;
+      state = JSON.stringify(step.state);
+      event = {};
+      for (const command of step.commands) {
+        if (command.type === 'markIncomplete') {
+          // 从这里起本轮开始做真实工作:留下面包屑,死于轮中时下次启动零延迟续传。
+          marked = true;
+          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)}`);
+          }
+        } else if (command.type === 'finish') {
+          finishRound(command);
+          return;
+        } else {
+          event = await perform(context, launchRolledBackVersion, command, configGeneration);
+        }
+      }
     }
-  } catch (e) {
-    roundResult = bundlePreparationResult('failed', 'invalid_config');
-    return;
-  }
-  if (config.disabled) {
-    roundResult = bundlePreparationResult('skipped', 'disabled');
-    return;
-  }
-  const appKey = config.appKey ?? '';
-  if (!appKey) {
-    roundResult = bundlePreparationResult('failed', 'invalid_config');
-    return;
-  }
-  // 从这里起本轮开始做真实工作:留下面包屑,死于轮中时下次启动零延迟续传。
-  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,
-      launchRolledBackVersion,
-      resetGeneration,
-      configJson,
-      config,
-      appKey,
-    );
   } finally {
-    try {
-      await context.removeKv(KEY_ROUND_INCOMPLETE);
-    } catch (e) {
-      // 残留标记只意味着下次启动少等 5 秒。
-      logger.warn(TAG, `cannot clear round marker: ${getErrorMessage(e)}`);
+    if (marked) {
+      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(
+// 执行引擎的一条命令,返回回应它的事件。
+async function perform(
   context: UpdateContext,
   launchRolledBackVersion: string,
-  resetGeneration: number,
-  configJson: string,
-  config: NativeConfig,
-  appKey: string,
-): Promise<void> {
-  const currentVersion = context.getCurrentVersion();
-  // getConstants consumes the persisted rollback marker during startup; use
-  // the launch-path snapshot captured before that happens.
-  const rolledBackVersion = launchRolledBackVersion;
-  const uuid = context.getKv('uuid') ?? '';
-  const packageVersion = config.packageVersion || context.getPackageVersion();
-
-  const identity: FlowIdentity = {
-    packageVersion,
-    currentVersion,
-    uuid,
-  };
-  if (rolledBackVersion) {
-    identity.rolledBackVersion = rolledBackVersion;
+  command: RoundCommand,
+  configGeneration: number,
+): Promise<RoundEvent> {
+  switch (command.type) {
+    case 'collectEnv':
+      return { type: 'env', env: await launchEnv(context, launchRolledBackVersion) };
+    case 'http': {
+      const text = await httpRequest(
+        command.url ?? '',
+        command.post ? command.body ?? '' : undefined,
+        command.timeoutMs ?? 0,
+        command.callTimeoutMs ?? 0,
+      );
+      return text === undefined
+        ? { type: 'http' }
+        : { type: 'http', text, at: Date.now() / 1000 };
+    }
+    case 'checkInstalled':
+      return { type: 'installed', installed: context.hasDownloadedVersion(command.hash ?? '') };
+    case 'download':
+      return download(context, command);
+    case 'commit':
+      return commit(context, command, configGeneration);
+    default:
+      // 本适配器不认识的命令:引擎会以 internal_error 结束本轮。
+      return { type: command.type };
   }
+}
 
-  const cInfo: FlowCInfo = {
-    rnu: config.rnu ?? '',
-    rn: config.rn ?? '',
+async function launchEnv(
+  context: UpdateContext,
+  launchRolledBackVersion: string,
+): Promise<RoundEnv> {
+  return {
+    packageVersion: context.getPackageVersion(),
+    // 与 JS 常量同形(无版本时为 ''),JS 才能复用这次请求的响应缓存。
+    currentVersion: context.getCurrentVersion(),
+    uuid: context.getKv('uuid') ?? '',
+    // getConstants consumes the persisted rollback marker during startup; use
+    // the launch-path snapshot captured before that happens.
+    rolledBackVersion: launchRolledBackVersion,
+    buildTime: context.getBuildTime(),
     // RNOH's Platform.Version is osFullName; use the same value so JS can
     // reuse the response cache produced by this native request.
     os: `harmony ${deviceInfo.osFullName}`,
-    uuid,
-  };
-
-  const input: FlowInput = {
-    packageVersion: identity.packageVersion,
-    currentVersion,
-    buildTime: context.getBuildTime(),
-    cInfo,
-    supportedDiffVersion: NativePatchCore.getSupportedDiffVersion(),
     bundleHash: await context.getBundleHash(),
   };
-  const body = NativePatchCore.buildRequestBody(JSON.stringify(input));
-  if (!body) {
-    roundResult = bundlePreparationResult('failed', 'invalid_request');
-    return;
-  }
-
-  const httpsOnly = isHttpsOnly(config);
-  const responseText = await runQueryRequest(config, appKey, body, httpsOnly);
-  if (!responseText) {
-    logger.warn(TAG, 'no endpoint reachable, giving up until next launch');
-    return;
-  }
-  // Anchor cache freshness to response arrival, before download/patch work.
-  const responseAtSeconds = Math.floor(Date.now() / 1000);
-
-  const decisionJson = NativePatchCore.handleResponse(
-    responseText,
-    JSON.stringify(identity),
-    config.afterDownload ?? '',
-  );
-  if (!decisionJson) {
-    roundResult = bundlePreparationResult('failed', 'invalid_response');
-    return;
-  }
-  const decision = JSON.parse(decisionJson) as Decision;
-  if (decision.action !== 'download') {
-    const committed = await context.commitSyncResult(
-      resetGeneration,
-      '',
-      '',
-      false,
-      buildResponseCacheJson(configJson, body, responseText, responseAtSeconds),
-    );
-    roundResult = committed
-      ? bundlePreparationResult(STATUS_NONE, decision.reason ?? '')
-      : bundlePreparationResult('cancelled', 'reset');
-    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');
-    roundResult = bundlePreparationResult('failed', 'invalid_response');
-    return;
-  }
-
-  let downloaded = context.hasDownloadedVersion(hash);
-  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) {
-    logger.warn(TAG, `all download attempts for ${hash} failed`);
-    const committed = await context.commitSyncResult(
-      resetGeneration,
-      '',
-      '',
-      false,
-      buildResponseCacheJson(configJson, body, responseText, responseAtSeconds),
-    );
-    roundResult = committed
-      ? bundlePreparationResult('failed', 'download_failed')
-      : bundlePreparationResult('cancelled', 'reset');
-    return;
-  }
+}
 
-  // 与 JS 侧下载成功后的 setLocalHashInfo 对齐,持久化版本元信息。
-  const info = decision.info;
-  let hashInfoJson = '';
-  if (info) {
-    const hashInfo: DecisionInfo = {};
-    if (typeof info.name === 'string') {
-      hashInfo.name = info.name;
-    }
-    if (typeof info.description === 'string') {
-      hashInfo.description = info.description;
+// 一次下载尝试,以引擎给的 deadline 为界:超时即 timedOut,失败带错误码
+// (PATCH_FAILED 由引擎决定换策略而不换镜像)。
+async function download(
+  context: UpdateContext,
+  command: RoundCommand,
+): Promise<RoundEvent> {
+  const strategy = command.strategy ?? '';
+  const url = command.url ?? '';
+  const hash = command.hash ?? '';
+  const deadline = command.deadline ?? 0;
+  let timedOut = false;
+  let timer = 0;
+  const expired = new Promise<void>((resolve) => {
+    timer = setTimeout(() => {
+      timedOut = true;
+      resolve();
+    }, Math.max(0, deadline - monotonicNowMs()));
+  });
+  // This bounds queueing, HTTP, decompression and native hpatch work from the
+  // round's perspective. The serialized task may still finish later, but it
+  // can no longer hold the round.
+  const start = (): Promise<void> => {
+    if (strategy === 'diff') {
+      return context.downloadPatchFromPpk(url, hash, command.originHash ?? '', deadline);
     }
-    if (typeof info.metaInfo === 'string') {
-      hashInfo.metaInfo = info.metaInfo;
+    if (strategy === 'pdiff') {
+      return context.downloadPatchFromPackage(url, hash, deadline);
     }
-    // forceBoot 激活就是救砖路径:记进持久化元信息,这个版本活到 markSuccess
-    // 时 JS 上报 forceBootRescue。只认服务端下发的指令——静默策略的激活是
-    // 普通投递(Android/iOS 同一规则)。
-    if (info.config && info.config.forceBoot) {
-      hashInfo.forceBootRescue = true;
+    return context.downloadFullUpdate(url, hash, deadline);
+  };
+  try {
+    await Promise.race([start(), expired]);
+    if (timedOut) {
+      logger.warn(TAG, `${strategy} attempt timed out`);
+      return { type: 'download', timedOut: true };
     }
-    hashInfoJson = JSON.stringify(hashInfo);
+    return { type: 'download', ok: true };
+  } catch (e) {
+    logger.warn(TAG, `${strategy} attempt failed: ${getErrorMessage(e)}`);
+    // 无错误码的失败(网络异常等)可换镜像重试。
+    return e instanceof PushyError
+      ? { type: 'download', ok: false, code: e.code }
+      : { type: 'download', ok: false };
+  } finally {
+    clearTimeout(timer);
   }
+}
 
-  // 版本元信息、激活与响应缓存一次性原子提交(见 commitSyncResult);
-  // 缓存只在原生文件/状态工作结束后公开,避免 JS 观察到响应后并发下载。
-  // 静默策略、或服务端按版本标记的 forceBoot(远程覆盖,救砖指令)才激活。
-  const activate = decision.activate === true;
-  let committed = false;
+// 版本元信息、激活与响应缓存一次性原子提交(见 commitSyncResult)。配置替换
+// 也会递增 reset 代数,提交因此被拒;配置代数用来区分是哪一种。
+async function commit(
+  context: UpdateContext,
+  command: RoundCommand,
+  configGeneration: number,
+): Promise<RoundEvent> {
   try {
-    committed = await context.commitSyncResult(
-      resetGeneration,
-      hash,
-      hashInfoJson,
-      activate,
-      buildResponseCacheJson(configJson, body, responseText, responseAtSeconds),
+    const committed = await context.commitSyncResult(
+      command.resetGeneration ?? -1,
+      command.hash ?? '',
+      command.hashInfo ?? '',
+      command.activate === true,
+      command.cache ?? '',
     );
+    if (!committed && context.getNativeConfigGeneration() !== configGeneration) {
+      return { type: 'committed', ok: false, reason: 'config_changed' };
+    }
+    return { type: 'committed', ok: committed };
   } catch (e) {
     logger.error(TAG, `commit failed: ${getErrorMessage(e)}`);
-    roundResult = bundlePreparationResult('failed', 'commit_failed');
-    return;
-  }
-  if (!committed) {
-    logger.warn(TAG, 'reset during round, dropping result');
-  } else if (activate) {
-    logger.info(TAG, `downloaded ${hash} and set for next launch`);
-  } else {
-    logger.info(TAG, `downloaded ${hash}, activation left to JS`);
+    return { type: 'committed', ok: false, error: true };
   }
-  roundResult = committed
-    ? bundlePreparationResult('downloaded', '', hash, activate)
-    : bundlePreparationResult('cancelled', 'reset');
 }
 
-function buildResponseCacheJson(
-  configJson: string,
-  requestBody: string,
-  responseText: string,
-  responseAtSeconds: number,
-): string {
-  const cacheEntry: RespCacheEntry = {
-    ts: responseAtSeconds,
-    body: responseText,
-    request: requestBody,
-    config: configJson,
-  };
-  return JSON.stringify(cacheEntry);
-}
-
-function isValidResponse(responseText: string | undefined): boolean {
-  if (responseText === undefined) {
-    return false;
-  }
-  try {
-    return NativePatchCore.isValidResponse(responseText);
-  } catch (e) {
-    return false;
+function finishRound(finish: RoundCommand): void {
+  const status = finish.status ?? 'failed';
+  const reason = finish.reason ?? '';
+  if (status === 'downloaded') {
+    const hash = finish.hash ?? '';
+    const activated = finish.activated === true;
+    logger.info(
+      TAG,
+      activated
+        ? `downloaded ${hash} and set for next launch`
+        : `downloaded ${hash}, activation left to JS`,
+    );
+    roundResult = bundlePreparationResult(status, reason, hash, activated);
+    return;
   }
+  logger.info(TAG, `${status} (${reason})`);
+  roundResult = bundlePreparationResult(status, reason);
 }
 
+// The engine's per-request bounds: timeoutMs for connect/read, callTimeoutMs
+// for the whole call.
 async function httpRequest(
   url: string,
-  postBody?: string,
+  postBody: string | undefined,
+  timeoutMs: number,
+  callTimeoutMs: number,
 ): Promise<string | undefined> {
   const client = http.createHttp();
   let callTimer: number | null = null;
@@ -540,14 +470,14 @@ async function httpRequest(
         : http.RequestMethod.GET,
       header,
       extraData: postBody,
-      connectTimeout: REQUEST_TIMEOUT_MS,
-      readTimeout: REQUEST_TIMEOUT_MS,
+      connectTimeout: Math.max(1, Math.floor(timeoutMs)),
+      readTimeout: Math.max(1, Math.floor(timeoutMs)),
       expectDataType: http.HttpDataType.STRING,
     });
     const timeoutPromise = new Promise<http.HttpResponse>((_, reject) => {
       callTimer = setTimeout(() => {
-        reject(Error(`HTTP request exceeded ${REQUEST_CALL_TIMEOUT_MS}ms`));
-      }, REQUEST_CALL_TIMEOUT_MS);
+        reject(Error(`HTTP request exceeded ${callTimeoutMs}ms`));
+      }, Math.max(0, callTimeoutMs));
     });
     const response = await Promise.race([requestPromise, timeoutPromise]);
     if (
@@ -567,185 +497,3 @@ async function httpRequest(
     client.destroy();
   }
 }
-
-// 顺序回退(§5.1):按纯层给出的候选序逐个请求,单请求超时;整轮失败后经
-// queryUrls 发现远程候选(排除已试过的)再来一轮。刻意不做 hedged race——
-// 该路径对延迟不敏感。
-async function runQueryRequest(
-  config: NativeConfig,
-  appKey: string,
-  body: string,
-  httpsOnly: boolean,
-): Promise<string | undefined> {
-  const orderedJson = NativePatchCore.orderEndpointCandidates(
-    JSON.stringify(config.endpoints ?? []),
-    Math.random(),
-  );
-  if (!orderedJson) {
-    return undefined;
-  }
-  const ordered = JSON.parse(orderedJson) as string[];
-  const tried = new Set<string>();
-  let httpAttempts = 0;
-  for (const rawBase of ordered) {
-    const base = normalizeEndpointBase(rawBase);
-    if (!base || tried.has(base)) {
-      continue;
-    }
-    if (httpAttempts++ >= MAX_QUERY_HTTP_ATTEMPTS) {
-      return undefined;
-    }
-    tried.add(base);
-    const response = await httpRequest(`${base}${QUERY_PATH}${appKey}`, body);
-    if (isValidResponse(response)) {
-      return response;
-    }
-  }
-  for (const listUrl of config.queryUrls ?? []) {
-    if (!listUrl) {
-      continue;
-    }
-    if (httpAttempts++ >= MAX_QUERY_HTTP_ATTEMPTS) {
-      return undefined;
-    }
-    const listText = await httpRequest(listUrl);
-    if (listText === undefined) {
-      continue;
-    }
-    let remote: string[];
-    try {
-      const parsed = JSON.parse(listText) as Object;
-      if (!Array.isArray(parsed)) {
-        continue;
-      }
-      remote = parsed as string[];
-    } catch (e) {
-      continue;
-    }
-    for (const rawBase of remote) {
-      if (typeof rawBase !== 'string') {
-        continue;
-      }
-      const base = normalizeEndpointBase(rawBase);
-      if (!base || tried.has(base)) {
-        continue;
-      }
-      if (httpsOnly && !isHttpsUrl(base)) {
-        // 远程注入的端点不得把 https 配置降级成明文。
-        logger.warn(TAG, `ignoring non-https remote endpoint ${base}`);
-        continue;
-      }
-      if (httpAttempts++ >= MAX_QUERY_HTTP_ATTEMPTS) {
-        return undefined;
-      }
-      tried.add(base);
-      const response = await httpRequest(`${base}${QUERY_PATH}${appKey}`, body);
-      if (isValidResponse(response)) {
-        return response;
-      }
-    }
-    // 拉到一份可解析的远程列表就够了。
-    break;
-  }
-  return undefined;
-}
-
-function normalizeEndpointBase(base: string): string {
-  return base.replace(/\/+$/, '');
-}
-
-async function runWithinDeadline(
-  start: () => Promise<void>,
-  deadlineUptimeMs: number,
-): Promise<void> {
-  const remainingMs = deadlineUptimeMs - monotonicNowMs();
-  if (remainingMs <= 0) {
-    throw createPushyError(
-      ERROR_DOWNLOAD_FAILED,
-      'Download phase deadline expired before start',
-    );
-  }
-  let deadlineTimer = 0;
-  const deadlinePromise = new Promise<void>((_, reject) => {
-    deadlineTimer = setTimeout(() => {
-      reject(
-        createPushyError(
-          ERROR_DOWNLOAD_FAILED,
-          'Download phase deadline exceeded',
-        ),
-      );
-    }, remainingMs);
-  });
-  try {
-    // This bounds queueing, HTTP, decompression and native hpatch work from
-    // the orchestrator's perspective. The serialized task may still finish
-    // later, but it can no longer prevent the response cache from settling.
-    await Promise.race([start(), deadlinePromise]);
-  } finally {
-    clearTimeout(deadlineTimer);
-  }
-}
-
-async function performAttempts(
-  context: UpdateContext,
-  attempts: DecisionAttempt[],
-  hash: string,
-  originHash: string,
-  httpsOnly: boolean,
-): Promise<boolean> {
-  const incrementalDeadline = monotonicNowMs() + DOWNLOAD_PHASE_TIMEOUT_MS;
-  let fullDeadline = 0;
-  for (const attempt of attempts) {
-    const type = attempt.type ?? '';
-    if (type === DOWNLOAD_TYPE_DIFF && !originHash) {
-      // diff 以当前运行版本为源;没有运行中的热更版本就跳过。
-      continue;
-    }
-    const isFullAttempt =
-      type !== DOWNLOAD_TYPE_DIFF && type !== DOWNLOAD_TYPE_PDIFF;
-    if (isFullAttempt && fullDeadline === 0) {
-      // Preserve a full 10min rescue budget even when diff/pdiff exhausted
-      // their own phase window.
-      fullDeadline = monotonicNowMs() + DOWNLOAD_PHASE_TIMEOUT_MS;
-    }
-    const deadline = isFullAttempt ? fullDeadline : incrementalDeadline;
-    for (const url of attempt.urls ?? []) {
-      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;
-        }
-        break;
-      }
-      try {
-        if (type === DOWNLOAD_TYPE_DIFF) {
-          await runWithinDeadline(
-            () => context.downloadPatchFromPpk(url, hash, originHash, deadline),
-            deadline,
-          );
-        } else if (type === DOWNLOAD_TYPE_PDIFF) {
-          await runWithinDeadline(
-            () => context.downloadPatchFromPackage(url, hash, deadline),
-            deadline,
-          );
-        } else {
-          await runWithinDeadline(
-            () => context.downloadFullUpdate(url, hash, deadline),
-            deadline,
-          );
-        }
-        return true;
-      } catch (e) {
-        logger.warn(TAG, `${type} attempt failed: ${getErrorMessage(e)}`);
-      }
-    }
-  }
-  return false;
-}