react-native-update 10.59.2 → 10.61.0

package/android/src/main/java/cn/reactnative/modules/update/SyncCoordinator.java

@@ -6,10 +6,10 @@ import androidx.annotation.Nullable;
 import java.io.IOException;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
-import java.util.HashSet;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
 import okhttp3.MediaType;
 import okhttp3.OkHttpClient;
 import okhttp3.Request;
@@ -31,20 +31,22 @@ import org.json.JSONObject;
  * version blacklisting.
  */
 final class SyncCoordinator {
-    // Version-info flags read by JS (metadata.ts), stored encoded.
-    private static final String INFO_CRASH_HOLD = Texts.reveal("3905f5c2a6b96d56212a19");
-    private static final String INFO_FORCE_BOOT = Texts.reveal("3c18e6d2aba9674a360d19ead5a695");
+    // Version-info flag read by JS (metadata.ts), stored encoded.
+    private static final String INFO_CRASH_HOLD = Texts.INFO_CRASH_HOLD;
 
+    // Shared with Harmony. The response cache lives in its own
+    // SharedPreferences file (UpdateContext.getNativeCheckCache).
+    // <generated:storage-keys> (scripts/contract.ts; bun scripts/generate-contract.ts)
+    // The persisted native check config (JS syncNativeConfig or the host).
     static final String KEY_CONFIG = "nativeConfig";
-    // Raw response cache for the JS side to reuse (§10.3), scoped to the
-    // exact logical request and native config that produced it.
+    // Raw response cache for the JS side to reuse (§10.3), scoped to the exact
+    // logical request and native config that produced it.
     static final String KEY_RESP_CACHE = "nativeCheckResp";
     // Set when a round starts, cleared when it ends (§11.4). Residue on the
-    // next launch means the previous process died mid-round (a crash rescue
-    // was truncated): that launch resumes immediately instead of waiting 5s.
+    // next launch means the previous process died mid-round: that launch
+    // resumes immediately instead of waiting 5s.
     static final String KEY_ROUND_INCOMPLETE = "nativeCheckIncomplete";
-    private static final int MAX_QUERY_HTTP_ATTEMPTS = 8;
-    private static final long DOWNLOAD_PHASE_TIMEOUT_SECONDS = 600;
+    // </generated:storage-keys>
     // The check response (and a remote queryUrls list) is a small JSON
     // document; anything bigger is a broken or hijacked endpoint.
     private static final long MAX_QUERY_RESPONSE_BYTES = 1024 * 1024;
@@ -67,7 +69,7 @@ final class SyncCoordinator {
     // bumps it, and the late activation must lose to that reset exactly like
     // the round itself would. Written generation-first, read hash-first, so
     // a torn read can only see a stricter (newer) generation.
-    private static volatile String unactivatedHash;
+    static volatile String unactivatedHash;
     private static volatile long unactivatedGeneration;
     private static volatile UpdateContext sContext;
     private static volatile String sLaunchRolledBackVersion;
@@ -77,42 +79,50 @@ final class SyncCoordinator {
     private static volatile String sJsCompletedConfig;
     // Published after the launch rollback snapshot, before host calls are accepted.
     private static volatile boolean nativeReady;
-    private static volatile BundlePreparationResult roundResult =
+    static volatile BundlePreparationResult roundResult =
         BundlePreparationResult.of(BundlePreparationResult.FAILED, "check_failed");
     private static volatile long roundGeneration = -1;
     private static volatile long roundConfigGeneration = -1;
     private static volatile String roundConfigJson;
 
-    /** Blocking only on the host API's worker; never call on the UI thread. */
-    static BundlePreparationResult prepareBundle(UpdateContext context) throws InterruptedException {
-        if (UpdateContext.DEBUG) {
+    // prepareBundle without an explicit timeout waits this long at most: past
+    // the longest round (8 query requests, then two 600s download phases).
+    // Same default as iOS (kPushyHostPrepareDefaultTimeout).
+    static final long DEFAULT_PREPARE_TIMEOUT_MS = 30 * 60 * 1000L;
+
+    /**
+     * Blocking only on the host API's worker; never call on the UI thread.
+     * Waits at most timeoutMs for this process's round: on expiry the result
+     * is failed/timeout, and the round keeps running in the background (its
+     * result still applies to the next launch), as on iOS.
+     */
+    static BundlePreparationResult prepareBundle(UpdateContext context, long timeoutMs)
+        throws InterruptedException {
+        if (BuildConfig.DEBUG) {
             return BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "debug");
         }
         if (!nativeReady || sContext != context || !context.getIsUsingBundleUrl()) {
             return BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "not_initialized");
         }
         String configJson = context.getKv(KEY_CONFIG);
-        if (configJson == null || configJson.isEmpty()) {
-            return BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "not_configured");
+        BundlePreparationResult rejection = configRejection(configJson);
+        if (rejection != null) {
+            return rejection;
         }
-        try {
-            JSONObject config = new JSONObject(configJson);
-            if (config.optBoolean("disabled", false)) {
-                return BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "disabled");
-            }
-            if (config.optString("appKey", "").isEmpty()) {
-                return BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_config");
-            }
-        } catch (JSONException e) {
-            return BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_config");
+        // Run the round on its own thread rather than this caller's, so the
+        // wait below can be bounded.
+        if (claimRound()) {
+            Threads.startDaemon("pushy-native-sync", () -> runClaimedRound(0));
         }
-        startRound(0);
         if (!roundStarted.get()) {
             return BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "config_changed");
         }
-        roundDone.await();
+        if (!roundDone.await(Math.max(0, timeoutMs), TimeUnit.MILLISECONDS)) {
+            return BundlePreparationResult.of(BundlePreparationResult.FAILED, "timeout");
+        }
         if (roundConfigGeneration != UpdateContext.getNativeConfigGeneration()
-            || !configJson.equals(roundConfigJson) || !configJson.equals(context.getKv(KEY_CONFIG))) {
+            || !FlowBridge.configsEquivalent(configJson, roundConfigJson)
+            || !FlowBridge.configsEquivalent(configJson, context.getKv(KEY_CONFIG))) {
             return BundlePreparationResult.of(BundlePreparationResult.CANCELLED, "config_changed");
         }
         if (roundGeneration != UpdateContext.getResetGeneration()) {
@@ -127,21 +137,49 @@ final class SyncCoordinator {
     }
 
     /**
-     * True when JS already obtained a valid response in this process for the
-     * exact config the native round would use: the delayed round is then a
-     * duplicate request. Only the scheduled round consults this — the
-     * crash-rescue path still runs, JS is dead by then.
+     * True when JS already obtained a valid response in this process for a
+     * config equivalent (FlowBridge.configsEquivalent, contract C1) to
+     * the one the native round would use: the delayed round is then a
+     * duplicate request. JS and a host may serialize the same config
+     * differently, so exact string equality would almost never match. Only
+     * the scheduled round consults this — the crash-rescue path still runs,
+     * JS is dead by then.
      */
     private static boolean hasJsRound(UpdateContext context) {
         String jsConfig = sJsCompletedConfig;
-        return jsConfig != null && jsConfig.equals(context.getKv(KEY_CONFIG));
+        return jsConfig != null
+            && FlowBridge.configsEquivalent(jsConfig, context.getKv(KEY_CONFIG));
+    }
+
+    /**
+     * The shared gate (FlowBridge.runnableConfig, update_flow_core) every
+     * entry point (prepareBundle, the automatic round's gate, the round
+     * itself) applies to the persisted config, so they cannot disagree on
+     * what is runnable: null when a round may run, otherwise the result —
+     * absent is skipped/not_configured, a non-object failed/invalid_config, a
+     * truthy disabled skipped/disabled, a blank appKey failed/invalid_config.
+     */
+    @Nullable
+    static BundlePreparationResult configRejection(@Nullable String json) {
+        try {
+            String result = FlowBridge.runnableConfig(json);
+            if (result == null) {
+                return BundlePreparationResult.of(BundlePreparationResult.FAILED, "internal_error");
+            }
+            JSONObject verdict = new JSONObject(result);
+            return verdict.has("status")
+                ? BundlePreparationResult.of(verdict.getString("status"), verdict.getString("reason"))
+                : null;
+        } catch (JSONException e) {
+            return BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_config");
+        }
     }
 
     private SyncCoordinator() {
     }
 
     static void schedule(final UpdateContext context, final String launchRolledBackVersion) {
-        if (UpdateContext.DEBUG) {
+        if (BuildConfig.DEBUG) {
             return;
         }
         if (!scheduled.compareAndSet(false, true)) {
@@ -155,60 +193,35 @@ final class SyncCoordinator {
         if (context.getKv(KEY_CONFIG) != null) {
             CrashHold.install();
         }
-        Thread thread = new Thread(new Runnable() {
-            @Override
-            public void run() {
-                try {
-                    // Keep the check away from the cold-start critical path
-                    // (§7 R5) — unless the previous process died mid-round,
-                    // in which case every launch second counts (§11.4).
-                    if (context.getKv(KEY_ROUND_INCOMPLETE) == null) {
-                        Thread.sleep(5000);
-                    }
-                    if (hasJsRound(context)) {
-                        // Not consuming the round: a later crash rescue may
-                        // still need it.
-                        Log.i(Texts.LOG_TAG,
-                            "native sync skipped: JS already queried in this process");
-                        return;
-                    }
-                    startRound(0);
-                } catch (Throwable e) {
-                    // The rescue path must never take the app down with it.
-                    Log.w(Texts.LOG_TAG, "native sync failed: " + e);
+        Threads.startDaemon("pushy-native-sync", Thread.MIN_PRIORITY + 1, () -> {
+            try {
+                // Keep the check away from the cold-start critical path
+                // (§7 R5) — unless the previous process died mid-round,
+                // in which case every launch second counts (§11.4).
+                if (context.getKv(KEY_ROUND_INCOMPLETE) == null) {
+                    Thread.sleep(5000);
+                }
+                if (hasJsRound(context)) {
+                    // Not consuming the round: a later crash rescue may
+                    // still need it.
+                    Log.i(Texts.LOG_TAG,
+                        "native sync skipped: JS already queried in this process");
+                    return;
                 }
+                startRound(0);
+            } catch (Throwable e) {
+                // The rescue path must never take the app down with it.
+                Log.w(Texts.LOG_TAG, "native sync failed: " + e);
             }
-        }, "pushy-native-sync");
-        thread.setPriority(Thread.MIN_PRIORITY + 1);
-        thread.setDaemon(true);
-        thread.start();
+        });
     }
 
     static boolean isRoundInFlight() {
         return roundStarted.get() && !roundCompleted;
     }
 
-    /**
-     * Runs the process's single round on the calling thread if nobody has
-     * started it yet. deadlineNanos > 0 (crash rescue) caps every HTTP call
-     * and download phase to the remaining budget.
-     */
     private static boolean hasRunnableConfig(UpdateContext context) {
-        if (context == null) {
-            return false;
-        }
-        try {
-            String json = context.getKv(KEY_CONFIG);
-            if (json == null) {
-                return false;
-            }
-            JSONObject config = new JSONObject(json);
-            return !config.optBoolean("disabled", false)
-                && config.opt("appKey") instanceof String
-                && !config.getString("appKey").trim().isEmpty();
-        } catch (JSONException e) {
-            return false;
-        }
+        return context != null && configRejection(context.getKv(KEY_CONFIG)) == null;
     }
 
     static void onConfigured(UpdateContext context) {
@@ -217,17 +230,27 @@ final class SyncCoordinator {
         }
     }
 
+    /**
+     * Runs the process's single round on the calling thread if nobody has
+     * started it yet. deadlineNanos > 0 (crash rescue) caps every HTTP call
+     * and download phase to the remaining budget.
+     */
     private static void startRound(long deadlineNanos) {
-        // An automatic check before first-run provisioning must not consume
-        // the process's only round. Hosts may configure later in this launch.
-        if (!hasRunnableConfig(sContext)) {
-            return;
-        }
-        if (!roundStarted.compareAndSet(false, true)) {
-            return;
+        if (claimRound()) {
+            runClaimedRound(deadlineNanos);
         }
+    }
+
+    // Claims the process's only round. An automatic check before first-run
+    // provisioning must not consume it: hosts may configure later in this
+    // launch.
+    private static boolean claimRound() {
+        return hasRunnableConfig(sContext) && roundStarted.compareAndSet(false, true);
+    }
+
+    private static void runClaimedRound(long deadlineNanos) {
         try {
-            runOnce(sContext, sLaunchRolledBackVersion, deadlineNanos);
+            runOnce(new DeviceRound(sContext, sLaunchRolledBackVersion), deadlineNanos);
         } catch (Throwable e) {
             Log.w(Texts.LOG_TAG, "native sync failed: " + e);
             roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "internal_error");
@@ -299,253 +322,349 @@ final class SyncCoordinator {
         }
     }
 
-    private static void runOnce(
-        UpdateContext context,
-        String launchRolledBackVersion,
-        long deadlineNanos
-    ) throws JSONException {
-        final long resetGeneration = UpdateContext.getResetGeneration();
-        roundGeneration = resetGeneration;
-        roundConfigGeneration = UpdateContext.getNativeConfigGeneration();
-        roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "check_failed");
-        String configJson = context.getKv(KEY_CONFIG);
-        roundConfigJson = configJson;
-        if (configJson == null || configJson.isEmpty()) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "not_configured");
-            return;
+    // The engine's clock: milliseconds on System.nanoTime, offset from this
+    // class's load so every value is positive (0 means "no deadline"). The
+    // nanoTime origin is arbitrary, so a hold deadline in nanos may be
+    // negative: only 0 means none on this side too.
+    private static final long CLOCK_ORIGIN_NANOS = System.nanoTime() - TimeUnit.SECONDS.toNanos(1);
+
+    static double engineMillis(long nanos) {
+        return (nanos - CLOCK_ORIGIN_NANOS) / 1e6;
+    }
+
+    static long engineNanos(double millis) {
+        return CLOCK_ORIGIN_NANOS + (long) (millis * 1e6);
+    }
+
+    /** A monotonic clock in nanoseconds (System.nanoTime on the device). */
+    interface Clock {
+        long nanoTime();
+    }
+
+    /**
+     * Everything a round does besides deciding: the engine step, the clock,
+     * the persisted state and the IO the engine's commands ask for.
+     * DeviceRound is the device's; the JVM tests replay the engine vectors
+     * through a scripted one (SyncRoundReplayTest).
+     */
+    interface RoundHost extends DownloadStarter, Clock {
+        /** FlowBridge.stepRound; null when the engine is unavailable. */
+        @Nullable
+        String stepRound(@Nullable String state, String event);
+
+        /** Whether a crash is being held right now (crashHoldActive). */
+        boolean crashHold();
+
+        long resetGeneration();
+
+        long configGeneration();
+
+        @Nullable
+        String getKv(String key);
+
+        void setKv(String key, String value);
+
+        void removeKv(String key);
+
+        /** This launch as the shared core sees it (native_round.h). */
+        JSONObject launchEnv() throws JSONException;
+
+        /** The response body; null when the request failed. */
+        @Nullable
+        String httpRequest(String url, @Nullable String postBody, long timeoutMs, long callTimeoutMs);
+
+        /** Wall-clock seconds, stamped on each response. */
+        double wallSeconds();
+
+        boolean hasCompletedVersion(String hash);
+
+        /** UpdateContext.commitSyncResult: whether the commit landed. */
+        boolean commitSyncResult(
+            long expectedGeneration, @Nullable String hash, @Nullable String hashInfoJson,
+            boolean activate, String responseCacheJson) throws Exception;
+    }
+
+    /** The round on the device: the JNI engine, UpdateContext, OkHttp. */
+    private static final class DeviceRound implements RoundHost {
+        private final UpdateContext context;
+        private final String launchRolledBackVersion;
+
+        DeviceRound(UpdateContext context, String launchRolledBackVersion) {
+            this.context = context;
+            this.launchRolledBackVersion = launchRolledBackVersion;
         }
-        JSONObject config;
-        try {
-            config = new JSONObject(configJson);
-        } catch (JSONException e) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_config");
-            return;
+
+        @Override
+        public long nanoTime() {
+            return System.nanoTime();
         }
-        if (config.optBoolean("disabled", false)) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "disabled");
-            return;
+
+        @Override
+        public String stepRound(String state, String event) {
+            return FlowBridge.stepRound(state, event);
         }
-        String appKey = config.optString("appKey", "");
-        if (appKey.isEmpty()) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_config");
-            return;
+
+        @Override
+        public boolean crashHold() {
+            return crashHoldActive;
         }
-        // Keep the existing interrupted-round breadcrumb and reset generation.
-        try {
-            context.setKv(KEY_ROUND_INCOMPLETE, "1");
-        } catch (IllegalStateException ignored) {
+
+        @Override
+        public long resetGeneration() {
+            return UpdateContext.getResetGeneration();
         }
-        try {
-            runConfiguredRound(
-                context, launchRolledBackVersion, deadlineNanos,
-                resetGeneration, configJson, config, appKey);
-        } finally {
-            try {
-                context.removeKv(KEY_ROUND_INCOMPLETE);
-            } catch (IllegalStateException ignored) {
-            }
+
+        @Override
+        public long configGeneration() {
+            return UpdateContext.getNativeConfigGeneration();
         }
-    }
 
-    private static void runConfiguredRound(
-        UpdateContext context,
-        String launchRolledBackVersion,
-        long deadlineNanos,
-        long resetGeneration,
-        String configJson,
-        JSONObject config,
-        String appKey
-    ) throws JSONException {
-        String packageVersion = config.optString(
-            "packageVersion", context.getPackageVersion());
-        if (packageVersion.isEmpty()) {
-            packageVersion = context.getPackageVersion();
+        @Override
+        public String getKv(String key) {
+            return context.getKv(key);
         }
 
-        String currentVersion = context.getCurrentVersion();
-        // Snapshot captured on the launch path before getConstants consumes
-        // the one-shot rollback marker. Reading SharedPreferences here, five
-        // seconds later, would lose the guard and could forceBoot the version
-        // that this very launch just rolled back.
-        String rolledBackVersion = launchRolledBackVersion;
-        String uuid = context.getKv("uuid");
-        if (uuid == null) {
-            uuid = "";
-        }
-
-        JSONObject identity = new JSONObject();
-        identity.put("packageVersion", packageVersion);
-        identity.put(
-            "currentVersion",
-            currentVersion == null ? JSONObject.NULL : currentVersion
-        );
-        identity.put("uuid", uuid);
-        if (rolledBackVersion != null) {
-            identity.put("rolledBackVersion", rolledBackVersion);
-        }
-
-        JSONObject cInfo = new JSONObject();
-        cInfo.put("rnu", config.optString("rnu", ""));
-        cInfo.put("rn", config.optString("rn", ""));
-        // React Native's Platform.Version is the Android SDK integer; use the
-        // same value so this request can be fingerprinted against the JS one.
-        cInfo.put("os", "android " + Build.VERSION.SDK_INT);
-        cInfo.put("uuid", uuid);
-
-        JSONObject input = new JSONObject();
-        input.put("packageVersion", packageVersion);
-        input.put(
-            "currentVersion",
-            currentVersion == null ? JSONObject.NULL : currentVersion
-        );
-        input.put("buildTime", context.getBuildTime());
-        input.put("cInfo", cInfo);
-        input.put("supportedDiffVersion", NativeCore.supportedDiffVersion());
-        input.put("bundleHash", context.computeBundleHash());
-
-        String body = FlowBridge.buildRequestBody(input.toString());
-        if (body == null) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_request");
-            return;
+        @Override
+        public void setKv(String key, String value) {
+            context.setKv(key, value);
         }
 
-        String responseText = runQueryRequest(config, appKey, body, deadlineNanos);
-        if (responseText == null) {
-            Log.i(Texts.LOG_TAG,
-                "native sync: no endpoint reachable, giving up until next launch");
-            return;
+        @Override
+        public void removeKv(String key) {
+            context.removeKv(key);
         }
-        // Cache freshness is anchored to when the server response arrived,
-        // not to when a potentially long download/patch/activation finished.
-        final long responseAtSeconds = System.currentTimeMillis() / 1000;
 
-        String decisionJson = FlowBridge.handleResponse(
-            responseText, identity.toString(), config.optString("afterDownload", ""));
-        if (decisionJson == null) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_response");
-            return;
+        @Override
+        public JSONObject launchEnv() throws JSONException {
+            return SyncCoordinator.launchEnv(context, launchRolledBackVersion);
         }
-        JSONObject decision = new JSONObject(decisionJson);
-        if (!"download".equals(decision.optString("action"))) {
-            boolean committed = context.commitSyncResult(
-                resetGeneration, null, null, false,
-                buildResponseCacheJson(configJson, body, responseText, responseAtSeconds));
-            roundResult = committed
-                ? BundlePreparationResult.of(BundlePreparationResult.NO_UPDATE, decision.optString("reason"))
-                : BundlePreparationResult.of(BundlePreparationResult.CANCELLED, "reset");
-            Log.i(Texts.LOG_TAG,
-                "native sync: nothing to do (" + decision.optString("reason") + ")");
-            return;
+
+        @Override
+        public String httpRequest(String url, String postBody, long timeoutMs, long callTimeoutMs) {
+            return SyncCoordinator.httpRequest(url, postBody, timeoutMs, callTimeoutMs);
         }
-        String hash = decision.optString("hash", "");
-        if (!UpdateFileUtils.isSafePathComponent(hash)) {
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "invalid_response");
-            return;
+
+        @Override
+        public double wallSeconds() {
+            return System.currentTimeMillis() / 1000.0;
         }
 
-        boolean downloaded = context.hasCompletedVersion(hash);
-        if (!downloaded) {
-            downloaded = performAttempts(
-                context, decision.optJSONArray("attempts"), hash, currentVersion,
-                deadlineNanos);
-        }
-        if (!downloaded) {
-            // The native attempt has finished, so JS may safely reuse the
-            // response and retry through its own strategy chain.
-            boolean committed = context.commitSyncResult(
-                resetGeneration, null, null, false,
-                buildResponseCacheJson(configJson, body, responseText, responseAtSeconds));
-            roundResult = BundlePreparationResult.of(
-                committed ? BundlePreparationResult.FAILED : BundlePreparationResult.CANCELLED,
-                committed ? "download_failed" : "reset");
-            return;
+        @Override
+        public boolean hasCompletedVersion(String hash) {
+            return context.hasCompletedVersion(hash);
         }
 
-        // Version info (mirroring the JS side's setLocalHashInfo), the
-        // activation and the response cache all land in one atomic commit —
-        // see UpdateContext.commitSyncResult.
-        String hashInfoJson = null;
-        JSONObject info = decision.optJSONObject("info");
-        if (info != null) {
-            JSONObject hashInfo = new JSONObject();
-            for (String key : new String[] {"name", "description", "metaInfo"}) {
-                Object value = info.opt(key);
-                if (value instanceof String) {
-                    hashInfo.put(key, value);
+        @Override
+        public boolean commitSyncResult(
+            long expectedGeneration, String hash, String hashInfoJson,
+            boolean activate, String responseCacheJson) {
+            return context.commitSyncResult(
+                expectedGeneration, hash, hashInfoJson, activate, responseCacheJson);
+        }
+
+        @Override
+        public DownloadTaskParams start(
+            String strategy, String url, String hash, String originHash,
+            UpdateContext.DownloadFileListener listener, long deadlineNanos) {
+            if ("diff".equals(strategy)) {
+                return context.downloadPatchFromPpk(url, hash, originHash, listener, deadlineNanos);
+            }
+            if ("pdiff".equals(strategy)) {
+                return context.downloadPatchFromApk(url, hash, listener, deadlineNanos);
+            }
+            return context.downloadFullUpdate(url, hash, listener, deadlineNanos);
+        }
+    }
+
+    /**
+     * The round itself is the shared engine's (cpp/update_flow_core
+     * round_engine.h, NATIVE_CHECKUPDATE_DESIGN §12): this drives it on the
+     * calling thread and runs what it asks for — the breadcrumb, the launch
+     * facts, the requests, the downloads and the commit.
+     */
+    static void runOnce(RoundHost host, long deadlineNanos) throws JSONException {
+        final long resetGeneration = host.resetGeneration();
+        final long configGeneration = host.configGeneration();
+        roundGeneration = resetGeneration;
+        roundConfigGeneration = configGeneration;
+        roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "check_failed");
+        String configJson = host.getKv(KEY_CONFIG);
+        roundConfigJson = configJson;
+
+        JSONObject event = new JSONObject()
+            .put("type", "start")
+            .put("config", configJson == null ? "" : configJson)
+            .put("resetGeneration", resetGeneration)
+            .put("configGeneration", configGeneration)
+            .put("sample", Math.random())
+            .put("deadline", deadlineNanos != 0 ? engineMillis(deadlineNanos) : 0);
+        String state = null;
+        boolean marked = false;
+        try {
+            while (true) {
+                event.put("now", engineMillis(host.nanoTime()))
+                    .put("crashHold", host.crashHold());
+                String step = host.stepRound(state, event.toString());
+                if (step == null) {
+                    roundResult = BundlePreparationResult.of(
+                        BundlePreparationResult.FAILED, "internal_error");
+                    return;
+                }
+                JSONObject result = new JSONObject(step);
+                state = result.getJSONObject("state").toString();
+                JSONArray commands = result.getJSONArray("commands");
+                event = new JSONObject();
+                for (int i = 0; i < commands.length(); i++) {
+                    JSONObject command = commands.getJSONObject(i);
+                    String type = command.getString("type");
+                    if ("markIncomplete".equals(type)) {
+                        marked = true;
+                        try {
+                            host.setKv(KEY_ROUND_INCOMPLETE, "1");
+                        } catch (IllegalStateException ignored) {
+                        }
+                    } else if ("finish".equals(type)) {
+                        finishRound(command, resetGeneration);
+                        return;
+                    } else {
+                        event = perform(host, command, configGeneration);
+                    }
                 }
             }
-            // A forceBoot activation is the brick-rescue path: mark it in the
-            // persisted info so JS can report force_boot_rescue when this
-            // version survives to markSuccess. Only the server-sent directive
-            // counts — a silent-strategy activation is ordinary delivery.
-            JSONObject infoConfig = info.optJSONObject("config");
-            if (infoConfig != null && infoConfig.optBoolean("forceBoot", false)) {
-                hashInfo.put(INFO_FORCE_BOOT, true);
+        } finally {
+            // A committed round already cleared the breadcrumb in its own
+            // commit (UpdateContext.commitSyncResult); only rounds that ended
+            // without committing need the extra write.
+            if (marked) {
+                try {
+                    if (host.getKv(KEY_ROUND_INCOMPLETE) != null) {
+                        host.removeKv(KEY_ROUND_INCOMPLETE);
+                    }
+                } catch (IllegalStateException ignored) {
+                }
             }
-            if (crashHoldActive) {
-                hashInfo.put(INFO_CRASH_HOLD, true);
+        }
+    }
+
+    /** Runs one engine command and returns the event that answers it. */
+    private static JSONObject perform(RoundHost host, JSONObject command, long configGeneration)
+        throws JSONException {
+        String type = command.getString("type");
+        switch (type) {
+            case "collectEnv":
+                return new JSONObject()
+                    .put("type", "env")
+                    .put("env", host.launchEnv());
+            case "http": {
+                boolean post = command.optBoolean("post");
+                String text = host.httpRequest(
+                    command.getString("url"),
+                    post ? command.getString("body") : null,
+                    (long) command.getDouble("timeoutMs"),
+                    (long) command.getDouble("callTimeoutMs"));
+                JSONObject event = new JSONObject().put("type", "http");
+                if (text != null) {
+                    event.put("text", text).put("at", host.wallSeconds());
+                }
+                return event;
             }
-            hashInfoJson = hashInfo.toString();
-        }
-        // Silent strategies or a server-marked forceBoot version (per-version
-        // remote override — the brick rescue) activate for the next launch;
-        // otherwise activation stays with the JS side. Unless a crash is
-        // being held: JS is dead, deferring to it would leave the fix on
-        // disk forever (§11.3).
-        boolean activate = decision.optBoolean("activate", false) || crashHoldActive;
-        boolean committed;
+            case "checkInstalled":
+                return new JSONObject()
+                    .put("type", "installed")
+                    .put("installed", host.hasCompletedVersion(command.getString("hash")));
+            case "download":
+                return download(command, host, host);
+            case "commit":
+                return commit(host, command, configGeneration);
+            default:
+                // Unknown to this adapter: the engine finishes the round.
+                return new JSONObject().put("type", type);
+        }
+    }
+
+    // This launch as the shared core sees it (native_round.h). Absent values
+    // (null) are left out.
+    private static JSONObject launchEnv(UpdateContext context, String launchRolledBackVersion)
+        throws JSONException {
+        String currentVersion = context.getCurrentVersion();
+        JSONObject env = new JSONObject();
+        env.put("packageVersion", context.getPackageVersion());
+        // The JS constant's form, so JS can reuse the response cache.
+        env.put("currentVersion", currentVersion == null ? JSONObject.NULL : currentVersion);
+        env.put("uuid", context.getKv("uuid"));
+        // Snapshot captured on the launch path before getConstants consumes
+        // the one-shot rollback marker. Reading SharedPreferences here, five
+        // seconds later, would lose the guard and could forceBoot the version
+        // that this very launch just rolled back.
+        env.put("rolledBackVersion", launchRolledBackVersion);
+        env.put("buildTime", context.getBuildTime());
+        // React Native's Platform.Version is the Android SDK integer; use the
+        // same value so this request can be fingerprinted against the JS one.
+        env.put("os", "android " + Build.VERSION.SDK_INT);
+        env.put("bundleHash", context.computeBundleHash());
+        return env;
+    }
+
+    // Version info, the activation and the response cache land in one atomic
+    // commit (UpdateContext.commitSyncResult). A config change bumps the
+    // reset generation too, so the commit refuses either; the config
+    // generation tells the two apart.
+    private static JSONObject commit(RoundHost host, JSONObject command, long configGeneration)
+        throws JSONException {
+        String hash = command.getString("hash");
+        String hashInfo = command.getString("hashInfo");
+        JSONObject event = new JSONObject().put("type", "committed");
         try {
-            committed = context.commitSyncResult(
-                resetGeneration,
-                hash,
-                hashInfoJson,
-                activate,
-                buildResponseCacheJson(configJson, body, responseText, responseAtSeconds));
+            boolean committed = host.commitSyncResult(
+                (long) command.getDouble("resetGeneration"),
+                hash.isEmpty() ? null : hash,
+                hashInfo.isEmpty() ? null : hashInfo,
+                command.getBoolean("activate"),
+                command.getString("cache"));
+            event.put("ok", committed);
+            if (!committed && host.configGeneration() != configGeneration) {
+                event.put("reason", "config_changed");
+            }
         } catch (Exception e) {
             Log.w(Texts.LOG_TAG, "native sync: commit failed: " + e);
-            roundResult = BundlePreparationResult.of(BundlePreparationResult.FAILED, "commit_failed");
+            event.put("error", true);
+        }
+        return event;
+    }
+
+    private static void finishRound(JSONObject finish, long resetGeneration) {
+        String status = finish.optString("status");
+        String reason = finish.optString("reason");
+        if (!BundlePreparationResult.DOWNLOADED.equals(status)) {
+            Log.i(Texts.LOG_TAG, "native sync: " + status + " (" + reason + ")");
+            roundResult = BundlePreparationResult.of(status, reason);
             return;
         }
-        if (!committed) {
-            Log.i(Texts.LOG_TAG, "native sync: reset during round, dropping result");
-        } else if (activate) {
+        String hash = finish.optString("hash");
+        boolean activated = finish.optBoolean("activated");
+        if (activated) {
             unactivatedHash = null;
-            Log.i(Texts.LOG_TAG,
-                "native sync: downloaded " + hash + " and set for next launch");
+            Log.i(Texts.LOG_TAG, "native sync: downloaded " + hash + " and set for next launch");
         } else {
             // Remembered so a crash later in this process can still activate
             // it (activatePendingVersion) — JS never will.
             unactivatedGeneration = resetGeneration;
             unactivatedHash = hash;
-            Log.i(Texts.LOG_TAG,
-                "native sync: downloaded " + hash + ", activation left to JS");
+            Log.i(Texts.LOG_TAG, "native sync: downloaded " + hash + ", activation left to JS");
         }
-        roundResult = committed
-            ? BundlePreparationResult.downloaded(hash, activate)
-            : BundlePreparationResult.of(BundlePreparationResult.CANCELLED, "reset");
-    }
-
-    private static String buildResponseCacheJson(
-        String configJson,
-        String requestBody,
-        String responseText,
-        long responseAtSeconds
-    ) throws JSONException {
-        JSONObject cacheEntry = new JSONObject();
-        cacheEntry.put("ts", responseAtSeconds);
-        cacheEntry.put("body", responseText);
-        cacheEntry.put("request", requestBody);
-        cacheEntry.put("config", configJson);
-        return cacheEntry.toString();
+        roundResult = BundlePreparationResult.downloaded(hash, activated);
     }
 
-    private static final OkHttpClient httpClient = new OkHttpClient.Builder()
+    private static final OkHttpClient httpClient = HttpClients.base().newBuilder()
         .connectTimeout(10, TimeUnit.SECONDS)
         .readTimeout(10, TimeUnit.SECONDS)
         .callTimeout(15, TimeUnit.SECONDS)
         .build();
 
-    private static String httpRequest(String url, String postBody, long deadlineNanos) {
+    // The engine's per-request bounds, already capped by the round deadline.
+    private static String httpRequest(
+        String url, String postBody, long timeoutMs, long callTimeoutMs
+    ) {
         try {
             Request.Builder builder =
                 new Request.Builder().url(url).header("Accept", "application/json");
@@ -553,25 +672,15 @@ final class SyncCoordinator {
                 builder.post(RequestBody.create(
                     postBody, MediaType.parse("application/json; charset=utf-8")));
             }
-            OkHttpClient client = httpClient;
-            if (deadlineNanos > 0) {
-                // Crash-rescue budget: never let a single request outlive the
-                // handler's hold window.
-                long remainingMillis = TimeUnit.NANOSECONDS.toMillis(
-                    deadlineNanos - System.nanoTime());
-                if (remainingMillis <= 0) {
-                    return null;
-                }
-                if (remainingMillis < 15000) {
-                    client = httpClient.newBuilder()
-                        .callTimeout(remainingMillis, TimeUnit.MILLISECONDS)
-                        .build();
-                }
-            }
+            OkHttpClient client = httpClient.newBuilder()
+                .connectTimeout(Math.max(1, timeoutMs), TimeUnit.MILLISECONDS)
+                .readTimeout(Math.max(1, timeoutMs), TimeUnit.MILLISECONDS)
+                .callTimeout(Math.max(1, callTimeoutMs), TimeUnit.MILLISECONDS)
+                .build();
             try (Response response = client.newCall(builder.build()).execute()) {
                 // Same rule as the artifact download: an https endpoint that
                 // redirects to plaintext http is a failed endpoint.
-                DownloadTask.rejectProtocolDowngrade(url, response);
+                HttpClients.rejectProtocolDowngrade(url, response);
                 ResponseBody body = response.body();
                 if (!response.isSuccessful() || body == null) {
                     return null;
@@ -609,205 +718,70 @@ final class SyncCoordinator {
         return source.readString(charset == null ? StandardCharsets.UTF_8 : charset);
     }
 
-    // Shared schema rule (update_flow_core::IsValidResponse): a 200 with
-    // `{"error": ...}` is a failed endpoint, not a verdict, and must not stop
-    // the endpoint fallback.
-    private static boolean isValidResponse(String responseText) {
-        return responseText != null && FlowBridge.isValidResponse(responseText);
+    /** Queues one download attempt; null when it was rejected up front (the listener was told). */
+    interface DownloadStarter {
+        @Nullable
+        DownloadTaskParams start(
+            String strategy, String url, String hash, @Nullable String originHash,
+            UpdateContext.DownloadFileListener listener, long deadlineNanos);
     }
 
     /**
-     * Sequential fallback over the ordered candidates (§5.1): one request at
-     * a time with its own timeout; after the configured round fails,
-     * queryUrls discovery merges remote candidates (excluding the
-     * already-tried) for one more round. No hedged race on purpose — this
-     * path is latency-insensitive.
+     * One download attempt the engine asked for, waited on up to its
+     * deadline: {"type": "download", ok, code?, timedOut?}.
      */
-    private static String runQueryRequest(
-        JSONObject config, String appKey, String body, long deadlineNanos
-    ) {
-        JSONArray endpoints = config.optJSONArray("endpoints");
-        String orderedJson = FlowBridge.orderEndpointCandidates(
-            endpoints == null ? "[]" : endpoints.toString(), Math.random());
-        JSONArray ordered;
-        try {
-            ordered = orderedJson == null ? new JSONArray() : new JSONArray(orderedJson);
-        } catch (JSONException e) {
-            return null;
-        }
-        HashSet<String> tried = new HashSet<>();
-        int httpAttempts = 0;
-        for (int i = 0; i < ordered.length(); i++) {
-            String base = HttpUtils.normalizeEndpointBase(ordered.optString(i, ""));
-            if (base.isEmpty() || !tried.add(base)) {
-                continue;
-            }
-            if (httpAttempts++ >= MAX_QUERY_HTTP_ATTEMPTS) {
-                return null;
-            }
-            String response = httpRequest(
-                base + HttpUtils.QUERY_PATH + appKey, body, deadlineNanos);
-            if (isValidResponse(response)) {
-                return response;
-            }
-        }
-        JSONArray queryUrls = config.optJSONArray("queryUrls");
-        if (queryUrls == null) {
-            return null;
-        }
-        for (int i = 0; i < queryUrls.length(); i++) {
-            String listUrl = queryUrls.optString(i, "");
-            if (listUrl.isEmpty()) {
-                continue;
-            }
-            if (httpAttempts++ >= MAX_QUERY_HTTP_ATTEMPTS) {
-                return null;
-            }
-            String listText = httpRequest(listUrl, null, deadlineNanos);
-            if (listText == null) {
-                continue;
-            }
-            JSONArray remote;
-            try {
-                remote = new JSONArray(listText);
-            } catch (JSONException e) {
-                continue;
-            }
-            for (int j = 0; j < remote.length(); j++) {
-                String base = HttpUtils.normalizeEndpointBase(remote.optString(j, ""));
-                if (base.isEmpty() || tried.contains(base)) {
-                    continue;
-                }
-                if (httpAttempts++ >= MAX_QUERY_HTTP_ATTEMPTS) {
-                    return null;
-                }
-                tried.add(base);
-                String response = httpRequest(
-                    base + HttpUtils.QUERY_PATH + appKey, body, deadlineNanos);
-                if (isValidResponse(response)) {
-                    return response;
-                }
-            }
-            // One successfully fetched remote list is enough.
-            break;
-        }
-        return null;
-    }
-
-    private static long capToHoldBudget(long phaseDeadlineNanos, long holdDeadlineNanos) {
-        if (holdDeadlineNanos <= 0) {
-            return phaseDeadlineNanos;
-        }
-        return Math.min(phaseDeadlineNanos, holdDeadlineNanos);
+    static JSONObject download(JSONObject command, DownloadStarter starter) throws JSONException {
+        return download(command, starter, System::nanoTime);
     }
 
-    private static boolean performAttempts(
-        UpdateContext context, JSONArray attempts, String hash, String originHash,
-        long holdDeadlineNanos
-    ) {
-        if (attempts == null) {
-            return false;
-        }
-        final long incrementalDeadlineNanos = capToHoldBudget(
-            System.nanoTime() + TimeUnit.SECONDS.toNanos(DOWNLOAD_PHASE_TIMEOUT_SECONDS),
-            holdDeadlineNanos);
-        long fullDeadlineNanos = 0;
-        for (int i = 0; i < attempts.length(); i++) {
-            JSONObject attempt = attempts.optJSONObject(i);
-            if (attempt == null) {
-                continue;
-            }
-            String type = attempt.optString("type");
-            if ("diff".equals(type) && (originHash == null || originHash.isEmpty())) {
-                // diff patches from the running version; none is running.
-                continue;
-            }
-            final boolean isFullAttempt = !"diff".equals(type) && !"pdiff".equals(type);
-            if (isFullAttempt && fullDeadlineNanos == 0) {
-                // Incremental failures must not consume the last-resort full
-                // download's budget. Each phase gets one bounded 10min window.
-                fullDeadlineNanos = capToHoldBudget(
-                    System.nanoTime()
-                        + TimeUnit.SECONDS.toNanos(DOWNLOAD_PHASE_TIMEOUT_SECONDS),
-                    holdDeadlineNanos);
-            }
-            final long deadlineNanos = isFullAttempt
-                ? fullDeadlineNanos : incrementalDeadlineNanos;
-            JSONArray urls = attempt.optJSONArray("urls");
-            if (urls == null) {
-                continue;
+    static JSONObject download(JSONObject command, DownloadStarter starter, Clock clock)
+        throws JSONException {
+        final String strategy = command.getString("strategy");
+        final long deadlineNanos = engineNanos(command.getDouble("deadline"));
+        final CountDownLatch latch = new CountDownLatch(1);
+        final AtomicBoolean succeeded = new AtomicBoolean(false);
+        final AtomicReference<Throwable> failure = new AtomicReference<>();
+        UpdateContext.DownloadFileListener listener = new UpdateContext.DownloadFileListener() {
+            @Override
+            public void onDownloadCompleted(DownloadTaskParams params) {
+                succeeded.set(true);
+                latch.countDown();
             }
-            for (int j = 0; j < urls.length(); j++) {
-                String url = urls.optString(j, "");
-                if (url.isEmpty()) {
-                    continue;
-                }
-                // Check before enqueueing: once the phase budget is gone we
-                // must not launch an orphan download that outlives the round.
-                long remainingNanos = deadlineNanos - System.nanoTime();
-                if (remainingNanos <= 0) {
-                    if (isFullAttempt) {
-                        return false;
-                    }
-                    break;
-                }
-                final CountDownLatch latch = new CountDownLatch(1);
-                final AtomicBoolean succeeded = new AtomicBoolean(false);
-                final String attemptType = type;
-                UpdateContext.DownloadFileListener listener =
-                    new UpdateContext.DownloadFileListener() {
-                        @Override
-                        public void onDownloadCompleted(DownloadTaskParams params) {
-                            succeeded.set(true);
-                            latch.countDown();
-                        }
 
-                        @Override
-                        public void onDownloadFailed(Throwable error) {
-                            Log.i(Texts.LOG_TAG, "native sync: " + attemptType
-                                + " attempt failed: " + error);
-                            latch.countDown();
-                        }
-                    };
-                DownloadTaskParams task;
-                if ("diff".equals(type)) {
-                    task = context.downloadPatchFromPpk(
-                        url, hash, originHash, listener, deadlineNanos);
-                } else if ("pdiff".equals(type)) {
-                    task = context.downloadPatchFromApk(
-                        url, hash, listener, deadlineNanos);
-                } else {
-                    task = context.downloadFullUpdate(
-                        url, hash, listener, deadlineNanos);
-                }
-                try {
-                    if (!latch.await(remainingNanos, TimeUnit.NANOSECONDS)) {
-                        Log.w(Texts.LOG_TAG,
-                            "native sync: download phase timed out during " + type);
-                        // The task shares one download thread with the next
-                        // attempt: cancel its transfer (or keep it from
-                        // starting) instead of queueing behind it
-                        // (CODE_AUDIT 2.12).
-                        if (task != null) {
-                            task.cancel();
-                        }
-                        if (isFullAttempt) {
-                            return false;
-                        }
-                        break;
-                    }
-                } catch (InterruptedException e) {
-                    Thread.currentThread().interrupt();
-                    if (task != null) {
-                        task.cancel();
-                    }
-                    return false;
-                }
-                if (succeeded.get()) {
-                    return true;
-                }
+            @Override
+            public void onDownloadFailed(Throwable error) {
+                Log.i(Texts.LOG_TAG, "native sync: " + strategy + " attempt failed: " + error);
+                failure.set(error);
+                latch.countDown();
             }
+        };
+        DownloadTaskParams task = starter.start(
+            strategy, command.getString("url"), command.getString("hash"),
+            command.has("originHash") ? command.getString("originHash") : null,
+            listener, deadlineNanos);
+        JSONObject event = new JSONObject().put("type", "download");
+        boolean settled;
+        try {
+            settled = latch.await(deadlineNanos - clock.nanoTime(), TimeUnit.NANOSECONDS);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            settled = false;
+        }
+        if (!settled) {
+            Log.w(Texts.LOG_TAG, "native sync: download phase timed out during " + strategy);
+            // The task shares one download thread with the next attempt:
+            // cancel its transfer (or keep it from starting) instead of
+            // queueing behind it (CODE_AUDIT 2.12).
+            if (task != null) {
+                task.cancel();
+            }
+            return event.put("timedOut", true);
+        }
+        event.put("ok", succeeded.get());
+        Throwable error = failure.get();
+        if (error != null) {
+            event.put("code", ErrorCodes.forDownloadFailure(error));
         }
-        return false;
+        return event;
     }
 }