react-native-update 10.59.2 → 10.61.0

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

@@ -8,27 +8,26 @@ import android.util.Log;
 import androidx.annotation.Nullable;
 import com.facebook.react.ReactInstanceManager;
 import java.io.File;
-import org.json.JSONObject;
 import java.io.IOException;
 import java.io.InputStream;
-import java.security.MessageDigest;
-import java.security.NoSuchAlgorithmException;
 import java.util.concurrent.Executor;
-import java.util.concurrent.Executors;
-import java.util.concurrent.ThreadFactory;
 
 public class UpdateContext {
+    // The one place that loads librnpushy.so (see NativeCore).
     static {
         NativeCore.ensureLoaded();
     }
 
     static final String TAG = Texts.LOG_TAG;
-    static final boolean DEBUG = BuildConfig.DEBUG;
 
     private final Context context;
     private final File rootDir;
     private final Executor executor;
     private final SharedPreferences sp;
+    // The native check's raw response cache (SyncCoordinator.KEY_RESP_CACHE)
+    // lives in its own file: it is a whole server response, and keeping it in
+    // sp made every small state commit rewrite it.
+    private final SharedPreferences checkCacheSp;
     // Our own PackageInfo, looked up once: every getPackageInfo call is a
     // Binder IPC, and the constructor, the bundle-hash cache and the native
     // check all need the version name / install time.
@@ -48,14 +47,25 @@ public class UpdateContext {
     // running app has not loaded yet. Volatile: written during launch, read
     // from the state serial and download executors.
     private volatile String launchVersion;
+    // bundleSha256 of launchVersion's install record, read once at launch
+    // resolution so getConstants does not hit the file system on the JS
+    // thread. {hash, sha256}; null until a version was resolved.
+    private volatile String[] launchBundleSha256;
+    // bundleHash of the embedded bundle, computed once per process on its own
+    // thread (see startBundleHashComputation); null until known.
+    private final Object bundleHashLock = new Object();
+    private String bundleHash;
+    private java.util.ArrayList<BundleHashListener> pendingBundleHashListeners =
+        new java.util.ArrayList<>();
+    // <generated:state-operations> (scripts/contract.ts; bun scripts/generate-contract.ts)
     private static final int STATE_OP_SWITCH_VERSION = 1;
     private static final int STATE_OP_MARK_SUCCESS = 2;
     private static final int STATE_OP_ROLLBACK = 3;
-    // 4 (clear first time) exists in the state core but has no Android caller.
+    // 4 (ClearFirstTime) has no caller on this side.
     private static final int STATE_OP_CLEAR_ROLLBACK_MARK = 5;
     private static final int STATE_OP_RESOLVE_LAUNCH = 6;
-    private static final String KEY_FIRST_LOAD_MARKED = "firstLoadMarked";
-    static final String VERSION_COMPLETE_FILE = InstallRecord.FILE_NAME;
+    // </generated:state-operations>
+    static final String KEY_FIRST_LOAD_MARKED = "firstLoadMarked";
     // Bumped by resetToPackagedBundle. The cold-start check runs for minutes
     // and may already hold a decision when the app resets to the packaged
     // bundle; the orchestrator samples this counter and abandons activation
@@ -100,20 +110,17 @@ public class UpdateContext {
 
     private UpdateContext(Context context) {
         this.context = context.getApplicationContext();
-        this.executor = Executors.newSingleThreadExecutor(new ThreadFactory() {
-            @Override
-            public Thread newThread(Runnable r) {
-                return new Thread(r, "pushy-download");
-            }
-        });
+        this.executor = Threads.single("pushy-download", false);
 
-        this.rootDir = new File(this.context.getFilesDir(), Texts.reveal("0502e4d5af9f6d"));
+        this.rootDir = new File(this.context.getFilesDir(), Texts.STORAGE_DIR_NAME);
 
         if (!rootDir.exists() && !rootDir.mkdirs() && !rootDir.exists()) {
             throw new IllegalStateException("Failed to create storage root dir: " + rootDir);
         }
 
-        this.sp = this.context.getSharedPreferences(Texts.reveal("2f07f0d0ba8e"), Context.MODE_PRIVATE);
+        this.sp = this.context.getSharedPreferences(Texts.PREFERENCES_NAME, Context.MODE_PRIVATE);
+        this.checkCacheSp = this.context.getSharedPreferences(
+            Texts.PREFERENCES_NAME + "_check", Context.MODE_PRIVATE);
         this.packageInfo = lookupPackageInfo(this.context);
         this.reactInstanceManager = pendingReactInstanceManager;
 
@@ -127,11 +134,28 @@ public class UpdateContext {
 
         if (nextState.changed) {
             // Execute cleanUp before clearing SharedPreferences to avoid race condition
-            this.cleanUp();
+            cleanUp(DownloadTaskParams.DEFAULT_MAX_AGE_DAYS);
             SharedPreferences.Editor editor = this.sp.edit();
-            editor.clear();
+            removeKeys(editor, VersionScopedKeys.clearedOnUpgrade(sp.getAll().keySet()));
             applyState(editor, nextState);
             persistEditor(editor, "sync state with binary version");
+            clearNativeCheckCache();
+        } else {
+            migrateNativeCheckCache();
+        }
+        startBundleHashComputation();
+    }
+
+    // One-time move of the response cache out of the main state file.
+    private void migrateNativeCheckCache() {
+        String legacy = sp.getString(SyncCoordinator.KEY_RESP_CACHE, null);
+        if (legacy == null) {
+            return;
+        }
+        if (checkCacheSp.edit().putString(SyncCoordinator.KEY_RESP_CACHE, legacy).commit()) {
+            SharedPreferences.Editor editor = sp.edit();
+            editor.remove(SyncCoordinator.KEY_RESP_CACHE);
+            persistEditor(editor, "migrate check cache");
         }
     }
 
@@ -177,32 +201,87 @@ public class UpdateContext {
      * identity of the binary itself, not of whatever hot update is currently
      * running. Hashes exactly the bytes pdiff patches from: the hardcoded
      * "index.android.bundle" asset read via AssetManager, same as
-     * DownloadTask.copyBundledAssetToFile. Runs on the download executor;
-     * never fails — an empty string means "unknown" and the server falls back
-     * to the buildTime heuristic.
+     * DownloadTask.copyBundledAssetToFile. Never fails — an empty string
+     * means "unknown" and the server falls back to the buildTime heuristic.
      *
-     * Deliberately java.security.MessageDigest instead of the C++
-     * pushy::digest: librnpushy.so is a prebuilt artifact and this must not
-     * force a rebuild. The NIST vectors in the patch_core tests anchor both
-     * implementations to the same standard.
+     * Computed once per process on a dedicated thread started by the
+     * constructor (not on the download executor, where it used to queue
+     * behind cleanup and downloads and make the first JS checkUpdate send an
+     * empty hash). The listener runs on that thread, or on the caller's when
+     * the value is already known.
+     *
+     * java.security.MessageDigest rather than the C++ pushy::digest: the
+     * bytes come from an AssetManager stream on the Java side, and the
+     * platform digest is native-backed already. The NIST vectors in the
+     * patch_core tests anchor both implementations to the same standard.
      */
     public void getBundleHash(final BundleHashListener listener) {
-        if (DEBUG) {
+        String known;
+        synchronized (bundleHashLock) {
+            known = bundleHash;
+            if (known == null) {
+                pendingBundleHashListeners.add(listener);
+                return;
+            }
+        }
+        listener.onBundleHash(known);
+    }
+
+    // Package-private: also the native cold-start check's request input
+    // (SyncCoordinator). Blocks until the shared computation finished — call
+    // off the main thread.
+    String computeBundleHash() {
+        synchronized (bundleHashLock) {
+            while (bundleHash == null) {
+                try {
+                    bundleHashLock.wait();
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    return "";
+                }
+            }
+            return bundleHash;
+        }
+    }
+
+    private void startBundleHashComputation() {
+        if (BuildConfig.DEBUG) {
             // Metro serves the bundle in debug; mirror the dev buildTime behaviour.
-            listener.onBundleHash("");
+            publishBundleHash("");
             return;
         }
-        executor.execute(new Runnable() {
-            @Override
-            public void run() {
-                listener.onBundleHash(computeBundleHash());
+        Threads.startDaemon("pushy-bundle-hash", () -> {
+            String hash = "";
+            try {
+                hash = loadOrHashBundledAsset();
+            } catch (Throwable e) {
+                Log.w(TAG, "bundle hash failed: " + e);
+            } finally {
+                publishBundleHash(hash);
             }
         });
     }
 
-    // Package-private: also the native cold-start check's request input
-    // (SyncCoordinator). Blocking — call off the main thread.
-    String computeBundleHash() {
+    private void publishBundleHash(String hash) {
+        java.util.ArrayList<BundleHashListener> listeners;
+        synchronized (bundleHashLock) {
+            bundleHash = hash;
+            listeners = pendingBundleHashListeners;
+            pendingBundleHashListeners = null;
+            bundleHashLock.notifyAll();
+        }
+        if (listeners != null) {
+            for (BundleHashListener listener : listeners) {
+                try {
+                    listener.onBundleHash(hash);
+                } catch (Throwable e) {
+                    Log.w(TAG, "bundle hash listener failed: " + e);
+                }
+            }
+        }
+    }
+
+    private String loadOrHashBundledAsset() {
         String cachePrefix = getPackageVersion() + "|" + getPackageLastUpdateTime() + "|";
         String cached = sp.getString(KEY_BUNDLE_HASH_CACHE, null);
         if (cached != null && cached.startsWith(cachePrefix)) {
@@ -223,20 +302,8 @@ public class UpdateContext {
 
     private String sha256OfBundledAsset(String assetName) {
         try (InputStream in = context.getAssets().open(assetName)) {
-            MessageDigest md = MessageDigest.getInstance("SHA-256");
-            byte[] buffer = new byte[64 * 1024];
-            int read;
-            while ((read = in.read(buffer)) != -1) {
-                md.update(buffer, 0, read);
-            }
-            byte[] digest = md.digest();
-            StringBuilder hex = new StringBuilder(digest.length * 2);
-            for (byte b : digest) {
-                hex.append(Character.forDigit((b >> 4) & 0xf, 16));
-                hex.append(Character.forDigit(b & 0xf, 16));
-            }
-            return hex.toString();
-        } catch (IOException | NoSuchAlgorithmException e) {
+            return UpdateFileUtils.sha256Hex(in);
+        } catch (IOException e) {
             // Expected when there is no embedded bundle (custom name, no
             // release bundle); "unknown" is a valid answer, not an error.
             Log.i(TAG, "Cannot hash bundled asset " + assetName + ": " + e);
@@ -261,16 +328,30 @@ public class UpdateContext {
         void onDownloadFailed(Throwable error);
     }
 
-    public void downloadFullUpdate(String url, String hash, DownloadFileListener listener) {
-        downloadFullUpdate(url, hash, listener, 0);
+    /**
+     * Params shared by every download task. deadlineNanos is an absolute
+     * System.nanoTime deadline for orchestrated (native cold-start) tasks; 0
+     * keeps the per-call timeout of a JS-initiated download.
+     */
+    private static DownloadTaskParams downloadParams(
+        int type, String url, String hash, DownloadFileListener listener, long deadlineNanos
+    ) {
+        DownloadTaskParams params = new DownloadTaskParams();
+        params.type = type;
+        params.url = url;
+        params.hash = hash;
+        params.listener = listener;
+        params.deadlineNanos = deadlineNanos;
+        return params;
     }
 
-    /**
-     * The deadline-taking overloads (native cold-start check) return the
-     * queued task's params so the orchestrator can cancel the task when its
-     * phase budget expires (CODE_AUDIT 2.12); null when the request was
-     * rejected up front (the listener has already been told).
+    /*
+     * The patch downloads return the queued task's params so the native
+     * orchestrator can cancel the task when its phase budget expires
+     * (CODE_AUDIT 2.12); null when the request was rejected up front (the
+     * listener has already been told).
      */
+
     @Nullable
     DownloadTaskParams downloadFullUpdate(
         String url, String hash, DownloadFileListener listener, long deadlineNanos
@@ -278,37 +359,25 @@ public class UpdateContext {
         if (rejectUnsafeComponent(hash, listener)) {
             return null;
         }
-        DownloadTaskParams params = new DownloadTaskParams();
-        params.type = DownloadTaskParams.TASK_TYPE_PATCH_FULL;
-        params.url = url;
-        params.hash = hash;
-        params.listener = listener;
-        params.deadlineNanos = deadlineNanos;
+        DownloadTaskParams params = downloadParams(
+            DownloadTaskParams.TASK_TYPE_PATCH_FULL, url, hash, listener, deadlineNanos);
         params.targetFile = new File(rootDir, hash + ".ppk");
         params.unzipDirectory = new File(rootDir, hash);
         enqueue(params);
         return params;
     }
 
+    /** A plain file download into the root dir; hash only keys progress events. */
     public void downloadFile(String url, String hash, String fileName, DownloadFileListener listener) {
         if (rejectUnsafeComponent(fileName, listener)) {
             return;
         }
-        DownloadTaskParams params = new DownloadTaskParams();
-        params.type = DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD;
-        params.url = url;
-        params.hash = hash;
-        params.listener = listener;
-
+        DownloadTaskParams params = downloadParams(
+            DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD, url, hash, listener, 0);
         params.targetFile = new File(rootDir, fileName);
-//        params.unzipDirectory = new File(rootDir, hash);
         enqueue(params);
     }
 
-    public void downloadPatchFromApk(String url, String hash, DownloadFileListener listener) {
-        downloadPatchFromApk(url, hash, listener, 0);
-    }
-
     @Nullable
     DownloadTaskParams downloadPatchFromApk(
         String url, String hash, DownloadFileListener listener, long deadlineNanos
@@ -316,22 +385,14 @@ public class UpdateContext {
         if (rejectUnsafeComponent(hash, listener)) {
             return null;
         }
-        DownloadTaskParams params = new DownloadTaskParams();
-        params.type = DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK;
-        params.url = url;
-        params.hash = hash;
-        params.listener = listener;
-        params.deadlineNanos = deadlineNanos;
-        params.targetFile = new File(rootDir, hash + Texts.reveal("7416e4dae09b69512137"));
+        DownloadTaskParams params = downloadParams(
+            DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK, url, hash, listener, deadlineNanos);
+        params.targetFile = new File(rootDir, hash + Texts.PACKAGE_DELTA_SUFFIX);
         params.unzipDirectory = new File(rootDir, hash);
         enqueue(params);
         return params;
     }
 
-    public void downloadPatchFromPpk(String url, String hash, String originHash, DownloadFileListener listener) {
-        downloadPatchFromPpk(url, hash, originHash, listener, 0);
-    }
-
     @Nullable
     DownloadTaskParams downloadPatchFromPpk(
         String url,
@@ -343,14 +404,10 @@ public class UpdateContext {
         if (rejectUnsafeComponent(hash, listener) || rejectUnsafeComponent(originHash, listener)) {
             return null;
         }
-        DownloadTaskParams params = new DownloadTaskParams();
-        params.type = DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK;
-        params.url = url;
-        params.hash = hash;
+        DownloadTaskParams params = downloadParams(
+            DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK, url, hash, listener, deadlineNanos);
         params.originHash = originHash;
-        params.listener = listener;
-        params.deadlineNanos = deadlineNanos;
-        params.targetFile = new File(rootDir, originHash + "-" + hash + Texts.reveal("7407e4dae09b69512137"));
+        params.targetFile = new File(rootDir, originHash + "-" + hash + Texts.PPK_DELTA_SUFFIX);
         params.unzipDirectory = new File(rootDir, hash);
         params.originDirectory = new File(rootDir, originHash);
         enqueue(params);
@@ -381,6 +438,15 @@ public class UpdateContext {
         }
     }
 
+    // Not editor.clear(): that also wiped the uuid (re-bucketing every gray
+    // release on each app upgrade) and the native config (no crash hold and
+    // no cold-start round until JS ran again). See VersionScopedKeys.
+    private void removeKeys(SharedPreferences.Editor editor, java.util.List<String> keys) {
+        for (String key : keys) {
+            editor.remove(key);
+        }
+    }
+
     private void applyState(SharedPreferences.Editor editor, StateCoreResult state) {
         putNullableString(editor, "packageVersion", state.packageVersion);
         putNullableString(editor, "buildTime", state.buildTime);
@@ -429,28 +495,16 @@ public class UpdateContext {
         if (!UpdateFileUtils.isSafePathComponent(hash)) {
             throw new IllegalArgumentException("Invalid hash: " + hash);
         }
-        File versionDir = new File(rootDir, hash);
-        File bundleFile = new File(versionDir, "index.bundlejs");
-        if (!bundleFile.isFile()) {
-            throw new IllegalStateException("Bundle version " + hash + " not found.");
-        }
         StateCoreResult currentState = getStateSnapshot();
-        boolean isLegacyActivatedVersion = hash.equals(currentState.currentVersion)
+        // Versions activated before completion records existed are
+        // grandfathered through current/last state, but only while their
+        // directory has no record; any other directory must carry a record
+        // whose bundle digest matches the bytes on disk before the next
+        // launch is pointed at them.
+        boolean grandfathered = hash.equals(currentState.currentVersion)
             || hash.equals(currentState.lastVersion);
-        if (isLegacyActivatedVersion) {
-            // Versions activated before completion markers were introduced are
-            // explicitly grandfathered through current/last state.
-            return;
-        }
-        if (!InstallRecord.isComplete(versionDir, hash)) {
-            // An arbitrary markerless directory may be a crash-left partial
-            // install.
-            throw new IllegalStateException("Bundle version " + hash + " is incomplete.");
-        }
-        // The record's bundle digest must match the bytes on disk before
-        // the next launch is pointed at them.
         try {
-            InstallRecord.verifyForActivation(versionDir, hash, bundleFile);
+            InstallRecord.verifyInstalled(new File(rootDir, hash), hash, grandfathered);
         } catch (IOException e) {
             throw new IllegalStateException(e.getMessage(), e);
         }
@@ -462,13 +516,12 @@ public class UpdateContext {
      * holds commitLock and has run verifySwitchTarget.
      */
     private StateCoreResult computeSwitchState(String hash) {
-        return runStateCore(
-            STATE_OP_SWITCH_VERSION,
-            getStateSnapshot(),
-            hash,
-            false,
-            false
-        );
+        return runStateOp(STATE_OP_SWITCH_VERSION, hash);
+    }
+
+    /** One state-core operation on the current snapshot; caller holds commitLock. */
+    private StateCoreResult runStateOp(int operation, @Nullable String hash) {
+        return runStateCore(operation, getStateSnapshot(), hash, false, false);
     }
 
     public void switchVersion(String hash) {
@@ -518,9 +571,9 @@ public class UpdateContext {
 
     /**
      * Reads and clears the first-load marker and the rollback mark in one
-     * commit. getConstants runs this synchronously on the JS thread (a
-     * TurboModule constant read), so the two writes are folded into a single
-     * editor; persistence is best-effort on this launch path.
+     * editor. getConstants runs this synchronously on the JS thread (a
+     * TurboModule constant read), so the write is applied asynchronously;
+     * persistence is best-effort on this launch path.
      */
     LaunchMarkers consumeLaunchMarkers() {
         LaunchMarkers markers;
@@ -534,21 +587,18 @@ public class UpdateContext {
                     editor.remove(KEY_FIRST_LOAD_MARKED);
                 }
                 if (rolledBackVersion != null) {
-                    StateCoreResult nextState = runStateCore(
-                        STATE_OP_CLEAR_ROLLBACK_MARK,
-                        getStateSnapshot(),
-                        null,
-                        false,
-                        false
-                    );
-                    applyState(editor, nextState);
+                    applyState(editor, runStateOp(STATE_OP_CLEAR_ROLLBACK_MARK, null));
                 }
-                persistEditor(editor, "consume launch markers");
+                // Asynchronous on purpose: the in-memory state changes
+                // immediately, the disk write happens on the
+                // SharedPreferences writer. Losing it to a crash only
+                // re-reports the one-shot markers on the next launch.
+                editor.apply();
             }
         }
         if (markers.rolledBackVersion != null) {
             // The rolled-back version's directory is now eligible for cleanup.
-            this.cleanUp();
+            cleanUp(DownloadTaskParams.DEFAULT_MAX_AGE_DAYS);
         }
         return markers;
     }
@@ -562,14 +612,7 @@ public class UpdateContext {
             return;
         }
         synchronized (commitLock) {
-            StateCoreResult currentState = getStateSnapshot();
-            StateCoreResult nextState = runStateCore(
-                STATE_OP_MARK_SUCCESS,
-                currentState,
-                null,
-                false,
-                false
-            );
+            StateCoreResult nextState = runStateOp(STATE_OP_MARK_SUCCESS, null);
             SharedPreferences.Editor editor = sp.edit();
             applyState(editor, nextState);
             if (nextState.staleVersionToDelete != null) {
@@ -578,7 +621,7 @@ public class UpdateContext {
             persistEditorOrThrow(editor, "mark success");
         }
 
-        this.cleanUp();
+        cleanUp(DownloadTaskParams.DEFAULT_MAX_AGE_DAYS);
     }
 
     /**
@@ -586,8 +629,10 @@ public class UpdateContext {
      * (so the next launch resolves to the built-in bundle) and delete the
      * downloaded versions, keeping only the directory of the version this
      * process is running from (a silent reset must not break its on-demand
-     * asset loads). Only the client uuid survives — it identifies the install
-     * for gray release bucketing and must not change on reset.
+     * asset loads). The install's own keys survive (VersionScopedKeys): the
+     * client uuid identifies the install for gray release bucketing and must
+     * not change on reset, and the native config stays with the host, as on
+     * iOS and Harmony.
      */
     public void resetToPackagedBundle() {
         synchronized (commitLock) {
@@ -605,26 +650,18 @@ public class UpdateContext {
         resetState.buildTime = getBuildTime();
         resetState.firstTime = false;
         resetState.firstTimeOk = true;
-        String uuid = sp.getString("uuid", null);
+        // The cached check response still advertises the version this reset
+        // removes; drop it first so a failure aborts before the state wipe.
+        if (!clearNativeCheckCache()) {
+            throw new IllegalStateException("Failed to persist state for reset check cache");
+        }
         SharedPreferences.Editor editor = sp.edit();
-        editor.clear();
+        removeKeys(editor, VersionScopedKeys.clearedOnReset(sp.getAll().keySet()));
         applyState(editor, resetState);
-        if (uuid != null) {
-            editor.putString("uuid", uuid);
-        }
         persistEditorOrThrow(editor, "reset to packaged bundle");
         ignoreRollback = false;
-        // editor.clear() above already dropped the cached check response; it
-        // still advertised the version this reset removed.
         Log.i(TAG, "Reset to packaged bundle");
-
-        DownloadTaskParams params = new DownloadTaskParams();
-        params.type = DownloadTaskParams.TASK_TYPE_CLEANUP;
-        params.maxAgeDays = 0;
-        // Keep names are resolved by the queued task at execution time, so a
-        // later activation is protected too.
-        params.unzipDirectory = rootDir;
-        enqueue(params);
+        cleanUp(0);
     }
 
     public static void setCustomInstanceManager(ReactInstanceManager instanceManager) {
@@ -713,7 +750,7 @@ public class UpdateContext {
                 // the main thread.
                 java.util.HashSet<String> visitedVersions = new java.util.HashSet<>();
                 while (currentVersion != null && visitedVersions.add(currentVersion)) {
-                    File bundleFile = new File(rootDir, currentVersion+"/index.bundlejs");
+                    File bundleFile = InstallRecord.bundleFile(new File(rootDir, currentVersion));
                     if (!bundleFile.exists()) {
                         Log.e(TAG, "Bundle version " + currentVersion + " not found.");
                         currentVersion = this.rollBack();
@@ -721,6 +758,8 @@ public class UpdateContext {
                         continue;
                     }
                     launchVersion = currentVersion;
+                    launchBundleSha256 = new String[] {
+                        currentVersion, readBundleSha256(currentVersion)};
                     syncRolledBackVersion = rolledBackVersion();
                     return bundleFile.toString();
                 }
@@ -736,7 +775,6 @@ public class UpdateContext {
         }
     }
 
-    /** Sampled/compared by the native check orchestrator; see resetGeneration. */
     /** Shared by JS and native hosts. Config replacement invalidates old native decisions. */
     private static final java.util.concurrent.atomic.AtomicLong nativeConfigGeneration =
         new java.util.concurrent.atomic.AtomicLong(0);
@@ -747,15 +785,22 @@ public class UpdateContext {
 
     void setNativeConfig(String config) {
         synchronized (commitLock) {
-            boolean changed = !config.equals(sp.getString(SyncCoordinator.KEY_CONFIG, null));
+            // Canonical comparison (C1, FlowBridge.configsEquivalent):
+            // re-sending the same config with another key order or trailing
+            // slashes must not cancel an in-flight round or drop its cache.
+            boolean changed = !FlowBridge.configsEquivalent(
+                config, sp.getString(SyncCoordinator.KEY_CONFIG, null));
             SharedPreferences.Editor editor = sp.edit();
             if (changed) {
                 // Also invalidate on a failed persistence attempt: an older
                 // round must not commit over uncertain configuration state.
                 resetGeneration.incrementAndGet();
                 nativeConfigGeneration.incrementAndGet();
-                editor.remove(SyncCoordinator.KEY_RESP_CACHE);
                 SyncCoordinator.recordJsRound(null);
+                if (!clearNativeCheckCache()) {
+                    throw new IllegalStateException(
+                        "Failed to persist state for configuration check cache");
+                }
             }
             // A native-only first launch needs a stable gray-release identity
             // before JS initializes. Never replace an existing installation ID.
@@ -771,7 +816,11 @@ public class UpdateContext {
         SyncCoordinator.onConfigured(this);
     }
 
-    // Native-decision generation: bumped by reset AND configuration replacement.
+    /**
+     * Native-decision generation, sampled/compared by the native check
+     * orchestrator: bumped by reset AND configuration replacement (see
+     * resetGeneration).
+     */
     static long getResetGeneration() {
         return resetGeneration.get();
     }
@@ -820,13 +869,20 @@ public class UpdateContext {
             if (switching) {
                 applyState(editor, computeSwitchState(hash));
             }
-            if (responseCacheJson != null) {
-                editor.putString(SyncCoordinator.KEY_RESP_CACHE, responseCacheJson);
-            }
+            // The round is over once its result lands: clear the
+            // interrupted-round breadcrumb in the same commit.
+            editor.remove(SyncCoordinator.KEY_ROUND_INCOMPLETE);
             persistEditorOrThrow(editor, "commit sync result");
             if (switching) {
                 ignoreRollback = false;
             }
+            // Advisory cache, separate file: written after the state it
+            // describes, still under commitLock so a reset cannot interleave.
+            if (responseCacheJson != null
+                && !checkCacheSp.edit()
+                    .putString(SyncCoordinator.KEY_RESP_CACHE, responseCacheJson).commit()) {
+                Log.w(TAG, "Failed to persist native sync response cache");
+            }
             return true;
         }
     }
@@ -837,33 +893,49 @@ public class UpdateContext {
      * unreadable record. Exposed to JS for crash-report attribution.
      */
     String currentBundleSha256(String hash) {
+        String[] cached = launchBundleSha256;
+        if (cached != null && cached[0].equals(hash)) {
+            return cached[1];
+        }
+        return readBundleSha256(hash);
+    }
+
+    private String readBundleSha256(String hash) {
         if (hash == null || hash.isEmpty() || !UpdateFileUtils.isSafePathComponent(hash)) {
             return "";
         }
-        JSONObject record = InstallRecord.read(new File(rootDir, hash));
-        return record == null ? "" : record.optString("bundleSha256", "");
+        return InstallRecord.recordedBundleSha256(new File(rootDir, hash));
+    }
+
+    /** Raw native check response for JS (§10.3); null when absent. */
+    @Nullable
+    String getNativeCheckCache() {
+        return checkCacheSp.getString(SyncCoordinator.KEY_RESP_CACHE, null);
+    }
+
+    private boolean clearNativeCheckCache() {
+        if (!checkCacheSp.contains(SyncCoordinator.KEY_RESP_CACHE)) {
+            return true;
+        }
+        if (!checkCacheSp.edit().remove(SyncCoordinator.KEY_RESP_CACHE).commit()) {
+            Log.e(TAG, "Failed to clear native sync response cache");
+            return false;
+        }
+        return true;
     }
 
     boolean hasCompletedVersion(String hash) {
         if (!UpdateFileUtils.isSafePathComponent(hash)) {
             return false;
         }
-        File versionDir = new File(rootDir, hash);
-        return new File(versionDir, "index.bundlejs").isFile()
-            && InstallRecord.isComplete(versionDir, hash);
+        return InstallRecord.isInstalled(new File(rootDir, hash), hash);
     }
 
     private String rollBack() {
         synchronized (commitLock) {
-            StateCoreResult currentState = getStateSnapshot();
-            StateCoreResult nextState = runStateCore(
-                STATE_OP_ROLLBACK,
-                currentState,
-                null,
-                false,
-                false
-            );
-            Log.e(TAG, "Rolling back version " + currentState.currentVersion
+            String rollingBack = getCurrentVersion();
+            StateCoreResult nextState = runStateOp(STATE_OP_ROLLBACK, null);
+            Log.e(TAG, "Rolling back version " + rollingBack
                 + " to " + nextState.currentVersion);
             SharedPreferences.Editor editor = sp.edit();
             applyState(editor, nextState);
@@ -884,10 +956,15 @@ public class UpdateContext {
     }
 
     interface CleanupAction {
-        void run(@Nullable String keepCurrent, @Nullable String keepPrevious);
+        void run(String[] keepNames);
     }
 
-    /** Resolve keep names immediately before deletion, never when enqueued. */
+    /**
+     * Resolve keep names immediately before the cleanup acts, never when
+     * enqueued. The action runs under versionFilesLock, so it must stay cheap
+     * (DownloadTask only renames doomed entries into a trash directory and
+     * deletes them after this returns).
+     */
     void runCleanupWithLatestState(CleanupAction action) {
         synchronized (versionFilesLock) {
             final String[] keepNames;
@@ -898,19 +975,19 @@ public class UpdateContext {
                     launchVersion
                 );
             }
-            if (keepNames == null) {
-                // JNI has only two keep slots; three distinct live versions are
-                // safer to defer until the next process than to delete one.
-                Log.i(TAG, "Skipping cleanup: three live versions need protection");
-                return;
-            }
-            action.run(keepNames[0], keepNames[1]);
+            action.run(keepNames);
         }
     }
 
-    private void cleanUp() {
+    /**
+     * Queues removal of every version entry older than maxAgeDays (0: all)
+     * except the keep names, which the queued task resolves at execution
+     * time so a later activation is protected too.
+     */
+    private void cleanUp(int maxAgeDays) {
         DownloadTaskParams params = new DownloadTaskParams();
         params.type = DownloadTaskParams.TASK_TYPE_CLEANUP;
+        params.maxAgeDays = maxAgeDays;
         params.unzipDirectory = rootDir;
         enqueue(params);
     }