react-native-update 10.60.0 → 10.61.0

package/README-CN.md

@@ -43,6 +43,7 @@
 | `disableTelemetry` | `false` | 不向服务端上报生命周期事件（下载/补丁失败、回滚、标记成功） |
 | `disableErrorReporting` | `false` | 关闭 JS 错误上报（见下节） |
 | `disableNativeCheck` | `false` | 关闭原生冷启动检测（救砖通道） |
+| `nativeConfigSource` | `'javascript'` | 原生检测配置的归属；宿主自己调用 `configure()` 时设为 `'native'`，JS 不再覆盖（见[迁移说明](docs/NATIVE_HOST_API_MIGRATION.md)） |
 | `testChannel` | `true` | 是否响应 `__rnPushyVersionHash` 深链/二维码；生产构建建议设为 `false` |
 | `logger` | – | 接收 SDK 全部事件（`type`、`data`）用于自定义日志 |
 
@@ -179,3 +180,8 @@ Hermes 字节码对通用二进制 diff 极不友好，我们在两个环节同
 Apple 平台使用 `RCTPushy`，Harmony 使用已有的 `PushyFileJSBundleProvider`。
 请在正常启动 bundle 解析后调用。改名不改变 JS 桥接契约，但原生接入代码需要迁移并重新构建。
 详见[原生接口迁移说明](docs/NATIVE_HOST_API_MIGRATION.md)。
+
+三端都可以传入等待上限：`PushyRuntime.prepareBundle(context, timeoutMillis, callback)`、
+`RCTPushy.prepareBundle(timeout:completion:)`、`prepareBundle(timeoutMs)`。超时返回
+`failed` / `timeout`，检测轮次继续在后台运行，结果仍对下次启动生效。不传时
+Android 与 iOS 最多等 30 分钟，HarmonyOS 等到轮次结束。

package/README.md

@@ -43,6 +43,7 @@ through `client.setOptions(...)`.
 | `disableTelemetry` | `false` | Stop lifecycle events (download/patch failure, rollback, mark success) reaching the server |
 | `disableErrorReporting` | `false` | Stop JS exception reporting (see below) |
 | `disableNativeCheck` | `false` | Turn off the native cold-start check that rescues bricked devices |
+| `nativeConfigSource` | `'javascript'` | Who owns the persisted native check configuration; `'native'` when the host calls `configure()` itself, so JS never overwrites it ([migration notes](docs/NATIVE_HOST_API_MIGRATION.md)) |
 | `testChannel` | `true` | Honour `__rnPushyVersionHash` deep links / QR codes; set `false` in production builds |
 | `logger` | – | Receives every SDK event (`type`, `data`) for your own logging |
 
@@ -162,3 +163,10 @@ Bridge-free hosts use `PushyRuntime.prepareBundle` (Android),
 (HarmonyOS), after normal launch bundle resolution. See the
 [native host API migration guide](docs/NATIVE_HOST_API_MIGRATION.md) for the
 source-breaking rename, unchanged JS bridge contract, and native rebuild steps.
+
+Each platform also takes a timeout: `PushyRuntime.prepareBundle(context,
+timeoutMillis, callback)`, `RCTPushy.prepareBundle(timeout:completion:)` and
+`prepareBundle(timeoutMs)`. On expiry the result is `failed` / `timeout`; the
+round keeps running in the background and still applies to the next launch.
+Without one, Android and iOS wait at most 30 minutes and HarmonyOS waits for
+the round.

package/android/jni/Android.mk

@@ -17,11 +17,13 @@ Shared_Files := \
 	$(sort $(wildcard $(CPP_DIR)/hpatch/*.c))
 
 # HDiffPatch / lzma submodules: only the decoder sources hpatch.c uses.
+# <generated:vendored-sources> (scripts/contract.ts; bun scripts/generate-contract.ts)
 Hdp_Files := \
 	HDiffPatch/libHDiffPatch/HPatch/patch.c \
 	HDiffPatch/file_for_patch.c \
 	lzma/C/LzmaDec.c \
 	lzma/C/Lzma2Dec.c
+# </generated:vendored-sources>
 
 LOCAL_SRC_FILES := \
 	$(patsubst $(LOCAL_PATH)/%,%,$(Shared_Files)) \

package/android/jni/Application.mk

@@ -12,5 +12,7 @@ APP_CPPFLAGS += -std=c++17 -Oz -fexceptions -fno-rtti -fno-unwind-tables -fno-as
 APP_LDFLAGS += -Wl,--gc-sections -Wl,--exclude-libs,ALL
 APP_LDFLAGS += -Wl,--icf=all
 APP_BUILD_SCRIPT := Android.mk
-APP_ABI := armeabi-v7a arm64-v8a x86 x86_64
+# <generated:abis> (scripts/contract.ts; bun scripts/generate-contract.ts)
+APP_ABI := arm64-v8a armeabi-v7a x86 x86_64
+# </generated:abis>
 APP_STL := c++_static

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

@@ -21,7 +21,7 @@ import java.util.concurrent.ConcurrentHashMap;
 
 final class ApkInstaller {
     private static final String SESSION_ID_EXTRA =
-        Texts.reveal("3919bac3ab8a6b512c3e08f0c0b6de60452311edfbc8f680624b2d1de38da5a58e65557f3ecaeb8ea3b859661f3dc3f98bab48646c042bd0e19ca546681c2939");
+        Texts.INSTALLER_SESSION_EXTRA;
     private static final ConcurrentHashMap<Integer, Promise> pendingPromises =
         new ConcurrentHashMap<Integer, Promise>();
 

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

@@ -5,15 +5,16 @@ package cn.reactnative.modules.update;
  * itself (entry count, sizes, ratios, reserved names, the unknown-length
  * probe plan) is the shared core's (cpp/patch_core/archive_limits.h, over
  * JNI); the constants below are the ones this side still compares against
- * itself, mirrored by hand (scripts/check-constant-parity.js asserts they
- * match the header).
+ * itself, generated from scripts/contract.ts like the header.
  */
 final class ArchiveLimits {
+    // <generated:limits> (scripts/contract.ts; bun scripts/generate-contract.ts)
     static final long MAX_ARCHIVE_BYTES = 512L * 1024 * 1024;
     static final long MAX_TOTAL_UNCOMPRESSED_BYTES = 2048L * 1024 * 1024;
     static final long MAX_ENTRY_BYTES = 512L * 1024 * 1024;
     static final long MAX_MANIFEST_BYTES = 16L * 1024 * 1024;
     static final long FREE_DISK_MARGIN_BYTES = 64L * 1024 * 1024;
+    // </generated:limits>
 
     private ArchiveLimits() {
     }

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

@@ -5,11 +5,13 @@ package cn.reactnative.modules.update;
  * mean that the running React Native instance has been reloaded.
  */
 public final class BundlePreparationResult {
+    // <generated:statuses> (scripts/contract.ts; bun scripts/generate-contract.ts)
     public static final String SKIPPED = "skipped";
     public static final String NO_UPDATE = "noUpdate";
     public static final String DOWNLOADED = "downloaded";
     public static final String FAILED = "failed";
     public static final String CANCELLED = "cancelled";
+    // </generated:statuses>
 
     private final String status;
     private final String reason;

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

@@ -25,12 +25,11 @@ import okio.BufferedSink;
 import okio.BufferedSource;
 import okio.Okio;
 import org.json.JSONObject;
-import org.json.JSONTokener;
 
 class DownloadTask implements Runnable {
     // Bundle delta entry inside a patch archive, stored encoded.
     private static final String BUNDLE_DELTA_ENTRY =
-        Texts.reveal("3319f0d4b6c56a502c3b10fcdca0de7d4b3307e9");
+        Texts.BUNDLE_DELTA_ENTRY;
 
     // Resume sidecars are a few hundred bytes of JSON.
     private static final long MAX_SIDECAR_BYTES = 64 * 1024;
@@ -124,48 +123,25 @@ class DownloadTask implements Runnable {
         }
     }
 
-    private JSONObject readResumeMeta(File sidecar, String url) {
+    // The sidecar's text, "" when there is none or it cannot be one (larger
+    // than a sidecar ever is, unreadable): ResumePlan treats both as "no
+    // trusted partial".
+    private static String readSidecarText(File sidecar) {
         if (!sidecar.isFile()) {
-            return null;
+            return "";
         }
         try {
-            JSONObject meta = (JSONObject) new JSONTokener(
-                UpdateFileUtils.readSmallUtf8(sidecar, MAX_SIDECAR_BYTES)).nextValue();
-            if (url.equals(meta.optString("url"))) {
-                return meta;
-            }
+            return UpdateFileUtils.readSmallUtf8(sidecar, MAX_SIDECAR_BYTES);
         } catch (Throwable e) {
-            // A corrupt sidecar simply means "cannot resume".
+            return "";
         }
-        return null;
     }
 
-    private void writeResumeMeta(
-        File sidecar, String url, Response response, JSONObject previousMeta, long total
-    ) {
+    private static void writeSidecarText(File sidecar, String text) {
         try {
-            JSONObject meta = new JSONObject();
-            meta.put("url", url);
-            String etag = response.header("ETag");
-            String lastModified = response.header("Last-Modified");
-            if (etag == null && previousMeta != null) {
-                etag = previousMeta.optString("etag", null);
-            }
-            if (lastModified == null && previousMeta != null) {
-                lastModified = previousMeta.optString("lastModified", null);
-            }
-            if (etag != null) {
-                meta.put("etag", etag);
-            }
-            if (lastModified != null) {
-                meta.put("lastModified", lastModified);
-            }
-            if (total > 0) {
-                meta.put("total", total);
-            }
             UpdateFileUtils.ensureParentDirectory(sidecar);
             try (java.io.FileOutputStream out = new java.io.FileOutputStream(sidecar)) {
-                out.write(meta.toString().getBytes(StandardCharsets.UTF_8));
+                out.write(text.getBytes(StandardCharsets.UTF_8));
             }
         } catch (Throwable e) {
             // Non-fatal: without a sidecar the next attempt starts from zero.
@@ -173,6 +149,18 @@ class DownloadTask implements Runnable {
         }
     }
 
+    // A ResumePlan result; null from the native core means memory ran out.
+    private static JSONObject resumeDecision(String json) throws IOException {
+        if (json == null) {
+            throw new IOException("resume plan failed");
+        }
+        try {
+            return new JSONObject(json);
+        } catch (org.json.JSONException e) {
+            throw new IOException("resume plan failed", e);
+        }
+    }
+
     private void downloadFile() throws IOException {
         this.hash = params.hash;
         streamedArchiveSha256 = null;
@@ -184,31 +172,35 @@ class DownloadTask implements Runnable {
         // Cross-launch resume (NATIVE_CHECKUPDATE_DESIGN §11.4): a brick gets
         // a few hundred milliseconds per launch plus a bounded crash-rescue
         // window, so every partial byte must survive process death and count.
-        long resumeOffset = 0;
-        JSONObject resumeMeta = readResumeMeta(sidecar, url);
-        if (resumeMeta != null && writePath.isFile() && writePath.length() > 0) {
-            long knownTotal = resumeMeta.optLong("total", 0);
-            long size = writePath.length();
-            if (knownTotal > 0 && size == knownTotal) {
-                // Fully received in a previous attempt (the process died
-                // between download end and unzip): nothing left to transfer.
-                downloadPhaseCompleted = true;
-                postProgress(knownTotal, knownTotal);
-                return;
-            }
-            if (knownTotal <= 0 || size < knownTotal) {
-                resumeOffset = size;
-            }
+        // What to request is the shared core's decision (ResumePlan).
+        String sidecarText = readSidecarText(sidecar);
+        JSONObject plan = resumeDecision(ResumePlan.planRequest(
+            sidecarText, url, writePath.isFile() ? writePath.length() : 0));
+        String action = plan.optString("action");
+        if ("complete".equals(action)) {
+            // Fully received in a previous attempt (the process died
+            // between download end and unzip): nothing left to transfer.
+            long total = plan.optLong("total");
+            downloadPhaseCompleted = true;
+            postProgress(total, total);
+            return;
         }
-        if (resumeOffset == 0) {
+        long resumeOffset = 0;
+        JSONObject headers = null;
+        if ("resume".equals(action)) {
+            resumeOffset = plan.optLong("offset");
+            headers = plan.optJSONObject("headers");
+        } else {
             discardPartial(writePath);
+            sidecarText = "";
         }
 
-        if (!transferArchive(url, writePath, sidecar, resumeMeta, resumeOffset)) {
-            // The server rejected the range for a partial that no longer
-            // matches (416): drop it and retry once from zero.
+        if (!transferArchive(url, writePath, sidecar, sidecarText, resumeOffset, headers)) {
+            // The partial no longer matches what the server serves (a stale
+            // 416, an untrusted range response): drop it and retry once from
+            // zero.
             discardPartial(writePath);
-            if (!transferArchive(url, writePath, sidecar, null, 0)) {
+            if (!transferArchive(url, writePath, sidecar, "", 0, null)) {
                 throw new IOException("Server rejected the download range for " + url);
             }
         }
@@ -225,32 +217,23 @@ class DownloadTask implements Runnable {
 
     /**
      * One HTTP transfer, appending from resumeOffset when the server honours
-     * the range. Returns false only for the retryable stale-partial case
-     * (416 with a size mismatch); throws on every other failure.
+     * the range. Returns false only when the partial must be discarded and the
+     * download retried from zero (ResumePlan's "restart"); throws on every
+     * other failure.
      */
     private boolean transferArchive(
-        String url, File writePath, File sidecar, JSONObject resumeMeta, long resumeOffset
+        String url, File writePath, File sidecar, String sidecarText, long resumeOffset,
+        JSONObject resumeHeaders
     ) throws IOException {
         Request.Builder builder = new Request.Builder().url(url);
-        if (resumeOffset > 0) {
-            // Only resume requests pin the encoding: Range offsets must
-            // address the same bytes that are on disk. Fresh downloads keep
-            // OkHttp's transparent gzip (it decompresses and strips the
-            // headers itself), matching the pre-resume behaviour for servers
-            // that compress regardless.
-            builder.header("Accept-Encoding", "identity");
-            builder.header("Range", "bytes=" + resumeOffset + "-");
-            String validator = null;
-            if (resumeMeta != null) {
-                validator = resumeMeta.optString("etag", null);
-                if (validator == null) {
-                    validator = resumeMeta.optString("lastModified", null);
-                }
-            }
-            if (validator != null) {
-                // With a validator the server falls back to a full 200 when
-                // the file changed instead of appending mismatched bytes.
-                builder.header("If-Range", validator);
+        if (resumeHeaders != null) {
+            // Range, Accept-Encoding: identity and If-Range (ResumePlan).
+            // Fresh downloads send none of them and keep OkHttp's
+            // transparent gzip, which decompresses and strips the headers.
+            java.util.Iterator<String> names = resumeHeaders.keys();
+            while (names.hasNext()) {
+                String name = names.next();
+                builder.header(name, resumeHeaders.optString(name));
             }
         }
 
@@ -261,53 +244,42 @@ class DownloadTask implements Runnable {
         params.attachCall(call);
         try (Response response = call.execute()) {
             HttpClients.rejectProtocolDowngrade(url, response);
-            if (response.code() == 416) {
-                long total = resumeMeta == null ? 0 : resumeMeta.optLong("total", 0);
-                if (total > 0 && writePath.length() == total) {
-                    // The partial is actually the complete file.
-                    postProgress(total, total);
-                    return true;
-                }
+            ResponseBody body = response.body();
+            long contentLength = body == null ? -1 : body.contentLength();
+            // The Content-Encoding header is visible only when the server
+            // encoded the body itself (OkHttp strips it when it transparently
+            // decompresses its own gzip).
+            JSONObject decision = resumeDecision(ResumePlan.classifyResponse(
+                response.code(),
+                resumeOffset,
+                response.header("Content-Range"),
+                response.header("Content-Encoding"),
+                contentLength,
+                sidecarText,
+                url,
+                writePath.isFile() ? writePath.length() : 0));
+            String action = decision.optString("action");
+            if ("complete".equals(action)) {
+                // The partial is actually the complete file.
+                long total = decision.optLong("total");
+                postProgress(total, total);
+                return true;
+            }
+            if ("restart".equals(action)) {
                 return false;
             }
-            if (!response.isSuccessful()) {
+            if (!"write".equals(action)) {
+                // The partial and its sidecar stay: that is the resume state.
                 throw new IOException("Server error: " + response.code() + " " + response.message());
             }
-
-            ResponseBody body = response.body();
             if (body == null) {
                 throw new IOException("Empty response body for " + url);
             }
 
-            String contentEncoding = response.header("Content-Encoding");
-            // Visible only when the server encoded the body itself (OkHttp
-            // strips the header when it transparently decompresses its own
-            // gzip). Byte offsets in an encoded representation do not match
-            // the decoded bytes on disk, so resume is off the table.
-            boolean encodedBody = contentEncoding != null
-                && !contentEncoding.equalsIgnoreCase("identity");
-            boolean append = response.code() == 206 && resumeOffset > 0;
-            if (append && encodedBody) {
-                // The server ignored Accept-Encoding: identity on a range
-                // request; the appended bytes could not be trusted.
-                return false;
-            }
-            long baseOffset = append ? resumeOffset : 0;
-            long contentLength = body.contentLength();
-            long totalAll;
-            if (append) {
-                totalAll = HttpUtils.parseContentRange(
-                    response.header("Content-Range"), resumeOffset);
-                if (totalAll < 0) {
-                    // Malformed or mismatched Content-Range: treat like a
-                    // stale partial (one clean retry from zero) instead of
-                    // failing — a throw would keep the partial and hit the
-                    // same wall on every future attempt.
-                    return false;
-                }
-            } else {
-                totalAll = contentLength > 0 ? contentLength : 0;
-            }
+            boolean append = decision.optBoolean("append");
+            long baseOffset = decision.optLong("base");
+            long totalAll = decision.optLong("total");
+            boolean encodedBody = decision.optBoolean("encoded");
             if (totalAll > ArchiveLimits.MAX_ARCHIVE_BYTES) {
                 throw new IOException("archive too large: " + totalAll + " bytes");
             }
@@ -319,12 +291,15 @@ class DownloadTask implements Runnable {
                 // writes must never leave a sidecar describing stale bytes).
                 discardPartial(writePath);
             }
-            if (encodedBody) {
+            String etag = response.header("ETag");
+            String lastModified = response.header("Last-Modified");
+            if (decision.optBoolean("persistSidecar")) {
+                // Persist before streaming so a mid-stream crash can resume.
+                writeSidecarText(sidecar,
+                    ResumePlan.sidecar(url, etag, lastModified, sidecarText, totalAll));
+            } else {
                 // No resume across an encoded transfer.
                 deleteResumeSidecar(writePath);
-            } else {
-                // Persist before streaming so a mid-stream crash can resume.
-                writeResumeMeta(sidecar, url, response, resumeMeta, totalAll);
             }
 
             long bytesRead;
@@ -401,6 +376,14 @@ class DownloadTask implements Runnable {
                 throw new IOException("Download incomplete: expected " + totalAll
                     + " bytes, got " + writePath.length());
             }
+            if (!encodedBody) {
+                // Refresh with the final size: a length unknown up front
+                // (chunked) left the sidecar without a total, so a process
+                // dying between download end and unzip would otherwise
+                // download the whole archive again.
+                writeSidecarText(sidecar, ResumePlan.sidecar(
+                    url, etag, lastModified, sidecarText, writePath.length()));
+            }
             streamedArchiveSha256 = UpdateFileUtils.toHex(digest.digest());
             // Final progress event, skipped when the loop already posted this
             // exact value (known length reaching 100% posts it in-loop).

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

@@ -8,9 +8,11 @@ import java.io.File;
 class DownloadTaskParams {
     static final int TASK_TYPE_CLEANUP          = 0; //Keep hash & originHash
 
-    static final int TASK_TYPE_PATCH_FULL       = 1;
-    static final int TASK_TYPE_PATCH_FROM_APK   = 2;
-    static final int TASK_TYPE_PATCH_FROM_PPK   = 3;
+    // <generated:archive-patch-types> (scripts/contract.ts; bun scripts/generate-contract.ts)
+    static final int TASK_TYPE_PATCH_FULL = 1;
+    static final int TASK_TYPE_PATCH_FROM_APK = 2;
+    static final int TASK_TYPE_PATCH_FROM_PPK = 3;
+    // </generated:archive-patch-types>
     static final int TASK_TYPE_PLAIN_DOWNLOAD   = 4;
 
     static final int DEFAULT_MAX_AGE_DAYS = 3;

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

@@ -4,11 +4,12 @@ package cn.reactnative.modules.update;
  * Stable, machine-readable error codes used as the promise rejection code so
  * the JS layer and user loggers can aggregate errors across platforms.
  *
- * MUST stay in sync with cpp/patch_core/error_codes.h (the single source of
- * truth) and src/error.ts (UpdateErrorCode). Messages are free-form; only the
- * codes are part of the contract.
+ * The codes of cpp/patch_core/error_codes.h and src/error.ts
+ * (UpdateErrorCode), all generated from scripts/contract.ts. Messages are
+ * free-form; only the codes are part of the contract.
  */
 final class ErrorCodes {
+    // <generated:error-codes> (scripts/contract.ts; bun scripts/generate-contract.ts)
     static final String INVALID_OPTIONS = "INVALID_OPTIONS";
     static final String DOWNLOAD_FAILED = "DOWNLOAD_FAILED";
     // Encoded (see Texts.reveal): the value is "PATCH_FAILED".
@@ -22,6 +23,7 @@ final class ErrorCodes {
     static final String UNSUPPORTED_PLATFORM = "UNSUPPORTED_PLATFORM";
     static final String APK_INSTALL_PERMISSION_REQUIRED = "APK_INSTALL_PERMISSION_REQUIRED";
     static final String APK_INSTALL_FAILED = "APK_INSTALL_FAILED";
+    // </generated:error-codes>
 
     private ErrorCodes() {
     }

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

@@ -23,6 +23,13 @@ final class FlowBridge {
      */
     static native String nextQueryStep(String stateJson, String responseText);
 
+    /**
+     * One step of the round driver (cpp/update_flow_core/round_engine.h):
+     * {"state", "commands"} for the previous state (null to start) and the
+     * event. Null only when the core threw.
+     */
+    static native String stepRound(String stateJson, String eventJson);
+
     /** The decision with planned attempts, hashInfo and the response-cache text. */
     static native String handleResponse(
         String responseText, String configJson, String envJson, String requestBody,

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

@@ -14,38 +14,4 @@ final class HttpUtils {
     static boolean isHttpsUrl(String url) {
         return url != null && url.regionMatches(true, 0, "https://", 0, 8);
     }
-
-    // "bytes <start>-<end>/<total>". Returns the total (0 when "*"), or -1
-    // when the header is missing/malformed, the start does not match the
-    // local partial, or the range and total contradict each other (end
-    // before start, or a numeric total not beyond the end) — either way the
-    // appended bytes could not be trusted. A total of 0 would otherwise pass
-    // as "unknown" and skip the final size check (RFC 9110 §14.4: the
-    // complete length must exceed the last position).
-    static long parseContentRange(String header, long expectedStart) {
-        if (header == null || !header.startsWith("bytes ")) {
-            return -1;
-        }
-        try {
-            String range = header.substring("bytes ".length()).trim();
-            int slash = range.indexOf('/');
-            int dash = range.indexOf('-');
-            if (slash < 0 || dash < 0 || dash > slash) {
-                return -1;
-            }
-            long start = Long.parseLong(range.substring(0, dash).trim());
-            long end = Long.parseLong(range.substring(dash + 1, slash).trim());
-            if (start != expectedStart || end < start) {
-                return -1;
-            }
-            String totalPart = range.substring(slash + 1).trim();
-            if (totalPart.equals("*")) {
-                return 0;
-            }
-            long total = Long.parseLong(totalPart);
-            return total > end ? total : -1;
-        } catch (NumberFormatException e) {
-            return -1;
-        }
-    }
 }

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

@@ -13,8 +13,10 @@ import java.io.IOException;
  * isInstalled / recordedBundleSha256, which only stat and read the record.
  */
 final class InstallRecord {
-    // Mirrors install_record.h kStagingSuffix (scripts/check-constant-parity.js).
+    // install_record.h kStagingSuffix, generated from scripts/contract.ts.
+    // <generated:staging-suffix> (scripts/contract.ts; bun scripts/generate-contract.ts)
     static final String STAGING_SUFFIX = ".staging";
+    // </generated:staging-suffix>
     /** The JS bundle inside a version directory. */
     static final String BUNDLE_FILE_NAME = "index.bundlejs";
 

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

@@ -21,7 +21,7 @@ final class NativeCore {
         }
 
         try {
-            System.loadLibrary(Texts.reveal("2819e4c4bd8371"));
+            System.loadLibrary(Texts.LIBRARY_NAME);
         } catch (UnsatisfiedLinkError error) {
             UnsatisfiedLinkError wrapped = new UnsatisfiedLinkError(
                 "Failed to load the native library. Original error: "

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

@@ -15,9 +15,12 @@ public final class PushyRuntime {
         void onComplete(BundlePreparationResult result);
     }
 
-    // A single waiting worker, not one thread per caller. The actual round is
-    // shared with cold start and crash rescue by SyncCoordinator.
-    private static final Executor WORKER = Threads.single("pushy-host-sync", true);
+    // Waiting threads, reused while idle. Not a single worker: each caller's
+    // wait is bounded by its own timeout, which a queue behind another
+    // caller's longer wait would break (iOS waits on a concurrent queue too).
+    // The actual round is shared with cold start and crash rescue by
+    // SyncCoordinator, on its own thread.
+    private static final Executor WORKER = Threads.cached("pushy-host-sync");
 
     public interface ConfigurationCallback {
         /** Main thread; null means configuration was persisted successfully. */
@@ -70,8 +73,24 @@ public final class PushyRuntime {
      * UpdateContext.getBundleUrl. Do not resolve the bundle again just to call
      * this method: bundle resolution consumes first-load/rollback markers.
      * Missing persisted configuration and debug builds are reported as skipped.
+     *
+     * Waits at most 30 minutes for the round (longer than any round takes).
      */
     public static void prepareBundle(Context context, final Callback callback) {
+        prepareBundle(context, SyncCoordinator.DEFAULT_PREPARE_TIMEOUT_MS, callback);
+    }
+
+    /**
+     * Same as prepareBundle(Context, Callback), but the callback runs after at
+     * most timeoutMillis. On expiry the result is status failed, reason
+     * timeout; the round keeps running in the background and its result still
+     * applies to the next launch.
+     */
+    public static void prepareBundle(
+        Context context,
+        final long timeoutMillis,
+        final Callback callback
+    ) {
         if (context == null || callback == null) {
             throw new IllegalArgumentException("context and callback are required");
         }
@@ -83,7 +102,7 @@ public final class PushyRuntime {
                     outcome = BundlePreparationResult.of(BundlePreparationResult.SKIPPED, "debug");
                 } else {
                     outcome = SyncCoordinator.prepareBundle(
-                        UpdateContext.getInstance(applicationContext));
+                        UpdateContext.getInstance(applicationContext), timeoutMillis);
                 }
             } catch (InterruptedException e) {
                 Thread.currentThread().interrupt();

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

@@ -237,7 +237,7 @@ final class ReactReloadManager {
         jsBundleLoaderField.setAccessible(true);
         jsBundleLoaderField.set(reactHostDelegate, loader);
 
-        Method reloadMethod = reactHost.getClass().getMethod(Texts.reveal("2812f8deaf8f"), String.class);
+        Method reloadMethod = reactHost.getClass().getMethod(Texts.RELOAD_METHOD, String.class);
         reloadMethod.invoke(reactHost, Texts.LOG_TAG);
     }
 

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

@@ -0,0 +1,31 @@
+package cn.reactnative.modules.update;
+
+/**
+ * The resumable-download decisions (cpp/patch_core/resume_plan.h): what to
+ * request for a partial archive and its sidecar, what to do with the
+ * response, and the sidecar text to persist. JSON text out; null only when
+ * the native core failed (memory ran out). DownloadTask keeps the IO.
+ */
+final class ResumePlan {
+    static {
+        NativeCore.ensureLoaded();
+    }
+
+    private ResumePlan() {
+    }
+
+    static native String planRequest(String sidecar, String url, long partialSize);
+
+    static native String classifyResponse(
+        int status,
+        long resumeOffset,
+        String contentRange,
+        String contentEncoding,
+        long contentLength,
+        String sidecar,
+        String url,
+        long partialSize);
+
+    static native String sidecar(
+        String url, String etag, String lastModified, String previousSidecar, long total);
+}