@onekeyfe/react-native-background-thread 3.0.60 → 3.0.61

package/android/src/main/cpp/cpp-adapter.cpp

@@ -4,6 +4,7 @@
 #include <atomic>
 #include <chrono>
 #include <condition_variable>
+#include <cstdio>
 #include <deque>
 #include <functional>
 #include <memory>
@@ -447,6 +448,323 @@ static void installTimersOnRuntime(jsi::Runtime &rt) {
     LOGI("Timer + rAF + rIC polyfills installed on bg runtime");
 }
 
+// ── Background segment eval (fix A: eval-then-resolve on the BG runtime) ──
+//
+// WHY THIS EXISTS — the "Requiring unknown module" race on the BACKGROUND
+// runtime:
+// The Kotlin BackgroundThreadManager.registerSegmentInBackground previously
+// called `ReactContext.registerSegment(...)`, which (bridgeless) routes through
+// ReactHostImpl.registerSegment → ReactInstance.registerSegment → C++
+// ReactInstance::registerSegment, and that only `scheduleWork`s the
+// evaluateJavaScript onto the RuntimeScheduler before returning. The Kotlin
+// completion callback then fired immediately, so the JS promise resolved BEFORE
+// the segment's `__d(...)` module definitions ran. Metro's
+// `import().then(() => __r(moduleId))` could then run `__r` before the module
+// table was populated → a fatal, uncatchable "Requiring unknown module". Locale
+// segments load through THIS bg path, so a language switch could still crash.
+//
+// THE FIX (mirrors the MAIN-runtime SplitBundleLoaderJSI fix and the iOS
+// callFunctionOnBufferedRuntimeExecutor: fix):
+// We evaluate the segment OURSELVES on the BACKGROUND JS thread and signal
+// completion in the SAME block, strictly AFTER eval. The accessor we use is the
+// background runtime's own RuntimeExecutor (`gBgTimerExecutor`), captured in
+// nativeInstallSharedBridge for the bg runtime (isMain=false). It dispatches via
+// scheduleOnJSThread(isMain=false, ...) → nativeExecuteWork, which runs the work
+// on the bg JS queue thread and then drainMicrotasks() — so this targets the
+// BACKGROUND runtime, NOT the main one. This is the correct bg analogue of the
+// main path's CallInvoker (the bg runtime is created by ReactHostImpl and the bg
+// ReactContext does not surface a usable jsCallInvokerHolder the way the main
+// one does, but its RuntimeExecutor already exists and routes to the bg JS
+// thread).
+//
+// Off-thread read (fix F): the segment file is read on the CALLING (native
+// module) thread before dispatch; only evaluateJavaScript + completion run on
+// the bg JS thread.
+
+// Java callback contract — implemented in Kotlin as
+// BackgroundThreadManager.SegmentEvalCallback.onComplete(error). Empty/null
+// error string → success. A message prefixed with "NO_RUNTIME:" → bg runtime
+// not ready (retryable); "IO_ERROR:" → file read failure (fatal); otherwise →
+// eval throw (fatal). Resolved exactly once on the Kotlin side via its watchdog
+// guard.
+static void invokeBgSegmentCallback(jobject globalCallback, const std::string &error) {
+    JNIEnv *env = getJNIEnv();
+    if (!env || !globalCallback) {
+        return;
+    }
+    jclass cls = env->GetObjectClass(globalCallback);
+    jmethodID mid =
+        env->GetMethodID(cls, "onComplete", "(Ljava/lang/String;)V");
+    if (mid) {
+        jstring jerr = error.empty() ? nullptr : env->NewStringUTF(error.c_str());
+        env->CallVoidMethod(globalCallback, mid, jerr);
+        if (env->ExceptionCheck()) {
+            LOGE("invokeBgSegmentCallback: JNI exception after onComplete");
+            env->ExceptionDescribe();
+            env->ExceptionClear();
+        }
+        if (jerr) {
+            env->DeleteLocalRef(jerr);
+        }
+    } else {
+        LOGE("invokeBgSegmentCallback: onComplete method not found!");
+        if (env->ExceptionCheck()) {
+            env->ExceptionDescribe();
+            env->ExceptionClear();
+        }
+    }
+    env->DeleteLocalRef(cls);
+}
+
+// ── Pending bg-eval callback registry (fix: bounded global-ref lifetime) ──
+//
+// The bg-eval work lambda captures a JNI global ref to the SegmentEvalCallback
+// and is enqueued onto gPendingWork for the bg JS thread. If that work is
+// enqueued but NEVER runs, the captured global ref would leak and the JS promise
+// would settle only via the Kotlin 30s watchdog. The drop paths that release it:
+//   - Java schedule fails (JNI exception / missing scheduleOnJSThread): the C++
+//     executor erases gPendingWork[workId] and drains this eval.
+//   - bg context==null / ptr==0 in scheduleOnJSThread: Kotlin calls
+//     nativeDropScheduledWork(workId) — which erases the work AND drains —
+//     BEFORE it would call nativeExecuteWork. (nativeExecuteWork's own
+//     rt==nullptr guard merely returns and is NOT a drain path; it is never
+//     reached for a dead ptr because Kotlin intercepts that case first.)
+//   - nativeDestroy: intentionally leaks the work lambdas (their ~jsi::Function
+//     can't run on a torn-down runtime) but drains this registry to settle them.
+// To make this strictly bounded, every in-flight bg eval registers here. Whoever
+// settles it first (the work lambda after eval, OR a drain on a drop path) claims
+// it via `settled`, invokes the Java callback exactly once, and deletes the
+// global ref. This guarantees no leak and no double-invoke.
+struct PendingBgEval {
+    jobject globalCallback;                  // owned: deleted by whoever settles
+    std::shared_ptr<std::atomic<bool>> settled;  // exactly-once claim
+};
+static std::mutex gBgEvalMutex;
+static std::unordered_map<int64_t, PendingBgEval> gPendingBgEvals;
+static int64_t gNextBgEvalId = 0;
+
+// Settle a pending bg eval exactly once: invoke the Java callback with `error`
+// (empty => success) and release the global ref. The shared `settled` flag is
+// the single source of truth for the one-shot — the registry entry may already
+// be gone (claimed/erased by the other party), so this is self-contained.
+static void settleBgEval(jobject globalCallback,
+                         const std::shared_ptr<std::atomic<bool>> &settled,
+                         const std::string &error) {
+    if (!settled) {
+        return;
+    }
+    bool expected = false;
+    if (!settled->compare_exchange_strong(expected, true)) {
+        // Already settled by the other party (lambda vs drain). Do nothing —
+        // the winner already invoked + deleted the global ref.
+        return;
+    }
+    invokeBgSegmentCallback(globalCallback, error);
+    JNIEnv *env = getJNIEnv();
+    if (env && globalCallback) {
+        env->DeleteGlobalRef(globalCallback);
+    }
+}
+
+// Settle ALL currently-registered bg evals with a retryable NO_RUNTIME-class
+// failure and clear the registry. Used when the bg runtime is going away (or is
+// unreachable) and any enqueued-but-unrun eval would otherwise leak its global
+// ref and hang the JS promise until the Kotlin watchdog. Each settle is
+// exactly-once (the work lambda may race us, but the shared flag arbitrates),
+// so this never double-invokes.
+static void drainPendingBgEvals(const std::string &reason) {
+    // Move the entries OUT under the lock and clear the registry, then settle
+    // OUTSIDE the lock. settleBgEval performs a Java upcall (onComplete via
+    // CallVoidMethod), so holding gBgEvalMutex across it would hold a native
+    // lock across arbitrary JS — a re-entrancy / deadlock hazard if a callback
+    // ever synchronously re-enters a gBgEvalMutex-taking path. PendingBgEval is
+    // copyable (jobject handle + shared_ptr); copies share the same global ref
+    // and `settled` flag, and the shared flag still arbitrates exactly-once
+    // against a racing work lambda, so the global ref is released exactly once.
+    std::vector<PendingBgEval> drained;
+    {
+        std::lock_guard<std::mutex> lock(gBgEvalMutex);
+        if (gPendingBgEvals.empty()) {
+            return;
+        }
+        LOGE("[SplitBundle] draining %zu pending bg eval(s): %s",
+             gPendingBgEvals.size(), reason.c_str());
+        drained.reserve(gPendingBgEvals.size());
+        for (auto &entry : gPendingBgEvals) {
+            drained.push_back(entry.second);
+        }
+        gPendingBgEvals.clear();
+    }
+    for (auto &entry : drained) {
+        settleBgEval(entry.globalCallback, entry.settled, "NO_RUNTIME:" + reason);
+    }
+}
+
+// Reads the whole file at `path` into `out`. Returns false on failure.
+static bool readBgFileToString(const std::string &path, std::string &out) {
+    FILE *f = std::fopen(path.c_str(), "rb");
+    if (f == nullptr) {
+        return false;
+    }
+    if (std::fseek(f, 0, SEEK_END) != 0) {
+        std::fclose(f);
+        return false;
+    }
+    long size = std::ftell(f);
+    if (size < 0) {
+        std::fclose(f);
+        return false;
+    }
+    if (std::fseek(f, 0, SEEK_SET) != 0) {
+        std::fclose(f);
+        return false;
+    }
+    out.resize(static_cast<size_t>(size));
+    size_t readBytes =
+        (size == 0) ? 0 : std::fread(&out[0], 1, static_cast<size_t>(size), f);
+    std::fclose(f);
+    return readBytes == static_cast<size_t>(size);
+}
+
+// nativeEvaluateSegmentInBackground: schedule eval of the segment at `path`
+// onto the BACKGROUND JS thread via the bg RuntimeExecutor and invoke `callback`
+// from INSIDE that same block, strictly AFTER eval. Returns immediately; the
+// callback fires later on the bg JS thread (or synchronously here on a fail-fast
+// path such as bg runtime not ready / file read failure).
+extern "C" JNIEXPORT void JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeEvaluateSegmentInBackground(
+    JNIEnv *env, jobject /* thiz */, jstring segmentPath, jstring sourceURL,
+    jobject callback) {
+
+    // Global-ref the callback: it is invoked later on a different thread.
+    jobject globalCallback = env->NewGlobalRef(callback);
+    // Shared one-shot claim flag for this eval — used by BOTH the work lambda
+    // (after eval) and any drop-path drain, so exactly one of them invokes the
+    // callback + deletes the global ref.
+    auto settled = std::make_shared<std::atomic<bool>>(false);
+
+    const char *pathChars = segmentPath ? env->GetStringUTFChars(segmentPath, nullptr) : nullptr;
+    std::string path = pathChars ? std::string(pathChars) : std::string();
+    if (pathChars) env->ReleaseStringUTFChars(segmentPath, pathChars);
+
+    const char *urlChars = sourceURL ? env->GetStringUTFChars(sourceURL, nullptr) : nullptr;
+    std::string url = urlChars ? std::string(urlChars) : std::string("segment");
+    if (urlChars) env->ReleaseStringUTFChars(sourceURL, urlChars);
+
+    // Fail-fast on THIS thread: settle exactly once, no registry entry created.
+    auto finishOnThisThread = [&](const std::string &err) {
+        settleBgEval(globalCallback, settled, err);
+    };
+
+    if (path.empty()) {
+        finishOnThisThread("IO_ERROR:Empty segment path");
+        return;
+    }
+
+    // Snapshot the bg RuntimeExecutor under the timer mutex (the same lock that
+    // guards its assignment/teardown). If it's null the bg runtime hasn't
+    // installed its SharedBridge yet → retryable NO_RUNTIME.
+    RPCRuntimeExecutor executor;
+    {
+        std::lock_guard<std::mutex> lock(gTimerMutex);
+        executor = gBgTimerExecutor;
+    }
+    if (!executor) {
+        finishOnThisThread("NO_RUNTIME:Background runtime executor not available");
+        return;
+    }
+
+    // F: read the segment file HERE, on the calling (native module) thread,
+    // BEFORE dispatch — so only evaluateJavaScript + completion run on the bg JS
+    // thread and the read does not block it or race the watchdog.
+    std::string source;
+    if (!readBgFileToString(path, source)) {
+        finishOnThisThread("IO_ERROR:Failed to read bg segment file: " + path);
+        return;
+    }
+    if (source.empty()) {
+        finishOnThisThread("IO_ERROR:Empty bg segment file: " + path);
+        return;
+    }
+
+    // Register this in-flight eval BEFORE dispatch so that if the enqueued work
+    // never runs (schedule fails, context==null, ptr==0, or nativeDestroy drops
+    // pending work) the drain can settle it as a retryable NO_RUNTIME failure
+    // and release the global ref — instead of leaking it and leaning on the
+    // Kotlin 30s watchdog. The work lambda removes its own entry when it runs.
+    int64_t bgEvalId;
+    {
+        std::lock_guard<std::mutex> lock(gBgEvalMutex);
+        bgEvalId = gNextBgEvalId++;
+        gPendingBgEvals[bgEvalId] = PendingBgEval{globalCallback, settled};
+    }
+
+    // Move the already-read buffer + the global callback ref into the work
+    // lambda. The lambda runs on the bg JS thread (via nativeExecuteWork), which
+    // also drainMicrotasks() after — preserving eval+resolve as one atomic turn.
+    executor([globalCallback, settled, bgEvalId, source = std::move(source),
+              url = std::move(url)](jsi::Runtime &rt) {
+        // We are running now → claim ownership and remove our registry entry so
+        // a concurrent nativeDestroy drain can't also touch this eval.
+        {
+            std::lock_guard<std::mutex> lock(gBgEvalMutex);
+            gPendingBgEvals.erase(bgEvalId);
+        }
+        std::string error;
+        try {
+            LOGI("[SplitBundle] bg evaluating segment %s (%zu bytes)", url.c_str(),
+                 source.size());
+            auto buffer =
+                std::make_shared<jsi::StringBuffer>(std::move(source));
+            // Runs the segment's top-level __d(...) synchronously on the bg JS
+            // thread before returning.
+            rt.evaluateJavaScript(std::move(buffer), url);
+            LOGI("[SplitBundle] bg segment %s evaluated", url.c_str());
+        } catch (const jsi::JSError &e) {
+            error = std::string("Bg segment eval JSError for ") + url + ": " +
+                    e.getMessage();
+            LOGE("[SplitBundle] %s", error.c_str());
+        } catch (const std::exception &e) {
+            error = std::string("Bg segment eval failed for ") + url + ": " +
+                    e.what();
+            LOGE("[SplitBundle] %s", error.c_str());
+        } catch (...) {
+            error = std::string("Bg segment eval failed for ") + url +
+                    " (unknown C++ exception)";
+            LOGE("[SplitBundle] %s", error.c_str());
+        }
+        // Resolve/reject from INSIDE this same bg-JS-thread block, strictly
+        // AFTER eval above — the ordering guarantee that fixes the race. The
+        // shared `settled` flag makes this a no-op if a drain already claimed
+        // it (it would not have, since we erased our entry above, but the flag
+        // keeps the invariant airtight against any reorder).
+        settleBgEval(globalCallback, settled, error);
+    });
+}
+
+// nativeDropScheduledWork: clean up after a scheduleOnJSThread drop path where
+// CallVoidMethod itself SUCCEEDED but Kotlin then found the bg runtime
+// unreachable (context==null / ptr==0) and returned WITHOUT calling
+// nativeExecuteWork for this `workId`. Two things must be released:
+//   1. gPendingWork[workId] — the stored work lambda (holding the segment
+//      SOURCE BUFFER). nativeExecuteWork is the only other eraser and it will
+//      never run for this id, so without this it leaks until nativeDestroy.
+//   2. The in-flight bg eval(s) — settle as retryable NO_RUNTIME so the JNI
+//      global ref is released and the JS promise resolves now instead of
+//      hanging on the 30s watchdog. drain-all is sound: an unreachable bg JS
+//      thread dooms every enqueued bg eval equally.
+// Exactly-once via the shared `settled` flag, so a recovered runtime that later
+// DOES run stale work (it can't — we erased it) would be a harmless no-op.
+extern "C" JNIEXPORT void JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeDropScheduledWork(
+    JNIEnv * /* env */, jobject /* thiz */, jlong workId) {
+    {
+        std::lock_guard<std::mutex> lock(gWorkMutex);
+        gPendingWork.erase(static_cast<int64_t>(workId));
+    }
+    drainPendingBgEvals("Background runtime unreachable when scheduling segment eval");
+}
+
 // ── nativeInstallSharedBridge ───────────────────────────────────────────
 // Install SharedStore and SharedRPC into a runtime.
 extern "C" JNIEXPORT void JNICALL
@@ -471,8 +789,24 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
 
     RPCRuntimeExecutor executor = [ref, capturedIsMain](std::function<void(jsi::Runtime &)> work) {
         JNIEnv *env = getJNIEnv();
+
+        // Settle any enqueued-but-now-unrunnable bg eval when this work will NOT
+        // reach nativeExecuteWork. Bg eval lambdas are only ever dispatched via
+        // the bg executor, so this is gated on !capturedIsMain — a main-thread
+        // schedule hiccup must never falsely reject healthy bg evals. This
+        // mirrors the existing context==null / ptr==0 (nativeDropScheduledWork)
+        // and nativeDestroy drop paths: drain-all is sound because a failed bg
+        // schedule means the bg JS thread is unreachable, so every enqueued bg
+        // eval is equally doomed. NO_RUNTIME is retryable, so JS re-attempts.
+        auto drainBgEvalsIfBg = [capturedIsMain](const char *reason) {
+            if (!capturedIsMain) {
+                drainPendingBgEvals(reason);
+            }
+        };
+
         if (!env || !ref) {
             LOGE("executor: env=%p, ref=%p — aborting", env, ref.get());
+            drainBgEvalsIfBg("Background executor env/ref unavailable when scheduling segment eval");
             return;
         }
 
@@ -485,6 +819,7 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
 
         jclass cls = env->GetObjectClass(ref.get());
         jmethodID mid = env->GetMethodID(cls, "scheduleOnJSThread", "(ZJ)V");
+        bool scheduled = false;
         if (mid) {
             LOGI("executor: calling scheduleOnJSThread(isMain=%d, workId=%ld)", capturedIsMain, (long)workId);
             env->CallVoidMethod(ref.get(), mid, static_cast<jboolean>(capturedIsMain), static_cast<jlong>(workId));
@@ -492,6 +827,8 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
                 LOGE("executor: JNI exception after scheduleOnJSThread");
                 env->ExceptionDescribe();
                 env->ExceptionClear();
+            } else {
+                scheduled = true;
             }
         } else {
             LOGE("executor: scheduleOnJSThread method not found!");
@@ -501,6 +838,21 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
             }
         }
         env->DeleteLocalRef(cls);
+
+        // Schedule failed (JNI exception or missing method): nativeExecuteWork
+        // will never run this workId, so erase it now to free the stored work
+        // (and its captured segment source buffer) instead of leaking it until
+        // nativeDestroy. Then settle the corresponding bg eval(s) so the JNI
+        // global ref is released and the JS promise resolves immediately rather
+        // than hanging on the Kotlin 30s watchdog. Erasing also makes a late
+        // Kotlin enqueue (if scheduleOnJSThread threw AFTER posting) a no-op.
+        if (!scheduled) {
+            {
+                std::lock_guard<std::mutex> lock(gWorkMutex);
+                gPendingWork.erase(workId);
+            }
+            drainBgEvalsIfBg("Background JS thread unreachable when scheduling segment eval");
+        }
     };
 
     std::string runtimeId = isMain ? "main" : "background";
@@ -646,6 +998,11 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeDestroy(
     // Drain pending cross-runtime work. Each std::function may capture a
     // shared_ptr<jsi::Function> tied to the destroyed runtime; leak them
     // for the same reason as above.
+    //
+    // NOTE: the bg-eval work lambdas captured here also hold a JNI global ref
+    // to a SegmentEvalCallback. Leaking the std::function leaks that ref AND
+    // leaves the JS promise pending — so we settle those explicitly below via
+    // gPendingBgEvals (the entry survives independently of the leaked lambda).
     {
         std::lock_guard<std::mutex> lock(gWorkMutex);
         for (auto &entry : gPendingWork) {
@@ -654,5 +1011,11 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeDestroy(
         gPendingWork.clear();
     }
 
+    // Drain pending bg-eval callbacks: the bg runtime is gone, so any eval that
+    // was enqueued but never ran must be settled NOW (retryable NO_RUNTIME) so
+    // the JS promise resolves immediately and the global ref is released —
+    // rather than leaking and relying on the Kotlin 30s watchdog.
+    drainPendingBgEvals("Background runtime destroyed before segment eval ran");
+
     LOGI("Native resources cleaned up");
 }

package/android/src/main/java/com/backgroundthread/BackgroundThreadManager.kt

@@ -24,6 +24,7 @@ import com.facebook.react.shell.MainReactPackage
 import java.io.File
 import java.lang.ref.WeakReference
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
 
 /**
  * Singleton manager for the background React Native runtime.
@@ -63,6 +64,12 @@ class BackgroundThreadManager private constructor() {
     companion object {
         private const val MODULE_NAME = "background"
 
+        // Bounded watchdog: if the bg JS thread never drains to our scheduled
+        // eval (e.g. the bg entry bundle never finished evaluating), reject as a
+        // RETRYABLE timeout rather than leaving the JS promise pending forever.
+        // Matches the main-runtime SplitBundleLoader watchdog.
+        private const val BG_SEGMENT_EVAL_TIMEOUT_MS = 30_000L
+
         init {
             System.loadLibrary("background_thread")
         }
@@ -78,6 +85,20 @@ class BackgroundThreadManager private constructor() {
         }
     }
 
+    /**
+     * Completion contract invoked by the native (JNI) side AFTER the bg segment
+     * has been evaluated into the BACKGROUND runtime. Called from the bg JS
+     * thread (or synchronously on the caller thread for fail-fast paths).
+     *
+     * @param error null on success; a non-empty message on failure. A message
+     *   prefixed with "NO_RUNTIME:" means the bg runtime is not ready yet
+     *   (retryable); "IO_ERROR:" means the segment file read failed (fatal);
+     *   any other message is a segment JS/Hermes eval throw (fatal).
+     */
+    fun interface SegmentEvalCallback {
+        fun onComplete(error: String?)
+    }
+
     // ── JNI declarations ────────────────────────────────────────────────────
 
     private external fun nativeInstallSharedBridge(runtimePtr: Long, isMain: Boolean)
@@ -85,6 +106,34 @@ class BackgroundThreadManager private constructor() {
     private external fun nativeDestroy()
     private external fun nativeExecuteWork(runtimePtr: Long, workId: Long)
 
+    /**
+     * Evaluate the segment at [segmentPath] into the BACKGROUND runtime on its
+     * JS thread and invoke [callback] from inside that same JS-thread block,
+     * strictly AFTER the segment's `__d(...)` module definitions have run. This
+     * is the ordering guarantee that fixes the bg "Requiring unknown module"
+     * race (the bg analogue of the main-runtime SplitBundleLoaderJSI fix).
+     *
+     * Returns immediately; [callback] fires later on the bg JS thread (or
+     * synchronously on the calling thread for fail-fast paths such as the bg
+     * runtime not being ready or the segment file failing to read).
+     */
+    private external fun nativeEvaluateSegmentInBackground(
+        segmentPath: String,
+        sourceURL: String,
+        callback: SegmentEvalCallback
+    )
+
+    /**
+     * Settle every in-flight bg segment eval as a retryable NO_RUNTIME failure
+     * without tearing the runtime down. Called from [scheduleOnJSThread] when
+     * the bg runtime is momentarily unreachable (context == null / ptr == 0) so
+     * any eval enqueued onto the native pending-work map — which will never be
+     * drained on the JS thread in that state — releases its JNI global ref and
+     * settles the JS promise immediately, instead of leaking until the next
+     * teardown or relying on the bg watchdog. Exactly-once on the native side.
+     */
+    private external fun nativeDropScheduledWork(workId: Long)
+
     /**
      * Synchronously mark the SharedRPC listener for `runtimeId` as dead
      * before the underlying JS runtime is torn down. See
@@ -412,8 +461,17 @@ class BackgroundThreadManager private constructor() {
         BTLogger.info("scheduleOnJSThread: isMain=$isMain, workId=$workId, context=${context != null}")
         if (context == null) {
             BTLogger.error("scheduleOnJSThread: context is null! isMain=$isMain, mainCtx=${mainReactContext != null}, bgHost=${bgReactHost != null}, bgCtx=${bgReactHost?.currentReactContext != null}")
+            // The just-enqueued native work will never reach the bg JS thread.
+            // Drop it now: erase gPendingWork[workId] (frees the captured segment
+            // source buffer) and, if it was a bg segment eval, settle it
+            // (retryable NO_RUNTIME) so its JNI global ref is released and the JS
+            // promise resolves instead of leaking until teardown / the bg watchdog.
+            if (!isMain) {
+                nativeDropScheduledWork(workId)
+            }
+            return
         }
-        context?.runOnJSQueueThread {
+        context.runOnJSQueueThread {
             // Re-read ptr inside the block — if a reload happened between
             // scheduling and execution, the old ptr may be stale.
             val ptr = if (isMain) mainRuntimePtr else bgRuntimePtr
@@ -426,6 +484,13 @@ class BackgroundThreadManager private constructor() {
                 }
             } else {
                 BTLogger.error("scheduleOnJSThread: ptr is 0! isMain=$isMain")
+                // Same as the null-context case: the work won't run on this
+                // (stale/torn-down) bg runtime. Drop gPendingWork[workId] (frees
+                // the source buffer) and settle any pending bg eval so it doesn't
+                // leak its global ref / hang the JS promise.
+                if (!isMain) {
+                    nativeDropScheduledWork(workId)
+                }
             }
         }
     }
@@ -433,51 +498,98 @@ class BackgroundThreadManager private constructor() {
     // ── Segment Registration (Phase 2.5 spike) ─────────────────────────────
 
     /**
-     * Register a HBC segment in the background runtime.
-     * Uses CatalystInstance.registerSegment() on the background ReactContext.
+     * Evaluate a HBC segment into the background runtime with completion
+     * callback (fix A: eval-then-resolve).
      *
-     * @param segmentId The segment ID to register
-     * @param path Absolute file path to the .seg.hbc file
-     * @throws IllegalStateException if background runtime is not started
-     * @throws IllegalArgumentException if segment file does not exist
-     */
-    /**
-     * Register a HBC segment in the background runtime with completion callback.
-     * Dispatches to the background JS queue thread and invokes the callback
-     * only after registerSegment has actually executed.
+     * Previously this called `ReactContext.registerSegment(...)`, whose
+     * completion fires BEFORE the segment bytecode is evaluated into the runtime
+     * (registerSegment only ENQUEUES the eval). That races Metro's
+     * `import().then(() => __r(moduleId))` and produces a fatal, uncatchable
+     * "Requiring unknown module" — locale segments load through this bg path, so
+     * a language switch could still crash. We now evaluate the segment OURSELVES
+     * on the bg JS thread via [nativeEvaluateSegmentInBackground] and resolve
+     * ONLY after eval completes, so eval + resolve are one atomic JS-thread turn.
      *
-     * @param segmentId The segment ID to register
+     * @param segmentId The segment ID (used only for the synthetic source URL)
      * @param path Absolute file path to the .seg.hbc file
-     * @param onComplete Called with null on success, or an Exception on failure
+     * @param onComplete Called with (code=null) on success, or
+     *   (code=<contract reject code>, message) on failure. The code is one of
+     *   the SHARED split-bundle contract codes so the JS loader's retryable set
+     *   { SPLIT_BUNDLE_NO_RUNTIME, SPLIT_BUNDLE_TIMEOUT } classifies correctly.
      */
-    fun registerSegmentInBackground(segmentId: Int, path: String, onComplete: (Exception?) -> Unit) {
+    fun registerSegmentInBackground(
+        segmentId: Int,
+        path: String,
+        onComplete: (code: String?, message: String?) -> Unit
+    ) {
         if (!isStarted) {
-            onComplete(IllegalStateException("Background runtime not started"))
+            // Bg runtime not started yet → retryable (the loader will re-attempt
+            // once the bg host is up).
+            onComplete("SPLIT_BUNDLE_NO_RUNTIME", "Background runtime not started")
             return
         }
 
         val file = File(path)
         if (!file.exists()) {
-            onComplete(IllegalArgumentException("Segment file not found: $path"))
+            onComplete("SPLIT_BUNDLE_NOT_FOUND", "Segment file not found: $path")
             return
         }
 
         val context = bgReactHost?.currentReactContext
         if (context == null) {
-            onComplete(IllegalStateException("Background ReactContext not available"))
+            onComplete("SPLIT_BUNDLE_NO_RUNTIME", "Background ReactContext not available")
             return
         }
 
-        // Use ReactContext.registerSegment which works in both bridge
-        // and bridgeless modes.
+        // One-shot guard: native success/error AND the watchdog can each try to
+        // settle; only the first wins.
+        val settled = AtomicBoolean(false)
+        val sourceURL = "seg-$segmentId.js"
+        val segStart = System.nanoTime()
+
+        // Bounded watchdog: if the bg JS thread never drains to our eval, reject
+        // with the RETRYABLE SPLIT_BUNDLE_TIMEOUT instead of hanging forever.
+        val watchdog = Handler(Looper.getMainLooper())
+        val timeoutRunnable = Runnable {
+            if (settled.compareAndSet(false, true)) {
+                BTLogger.error("[SplitBundle] bg segment id=$segmentId eval timed out after ${BG_SEGMENT_EVAL_TIMEOUT_MS}ms (bg entry bundle likely never finished evaluating); rejecting as retryable timeout")
+                onComplete("SPLIT_BUNDLE_TIMEOUT", "Bg segment eval timed out: id=$segmentId")
+            }
+        }
+        watchdog.postDelayed(timeoutRunnable, BG_SEGMENT_EVAL_TIMEOUT_MS)
+
         try {
-            context.registerSegment(segmentId, path) {
-                BTLogger.info("Segment registered in background runtime: id=$segmentId, path=$path")
-                onComplete(null)
+            nativeEvaluateSegmentInBackground(path, sourceURL) { error ->
+                if (settled.compareAndSet(false, true)) {
+                    watchdog.removeCallbacks(timeoutRunnable)
+                    if (error == null) {
+                        val segMs = (System.nanoTime() - segStart) / 1_000_000.0
+                        BTLogger.info("[SplitBundle] bg segment id=$segmentId evaluated in ${String.format("%.1f", segMs)}ms (eval-complete)")
+                        onComplete(null, null)
+                    } else {
+                        // Native prefixes its failures so we can map to the
+                        // shared contract codes: NO_RUNTIME (retryable),
+                        // IO_ERROR (fatal), else eval throw (fatal).
+                        when {
+                            error.startsWith("NO_RUNTIME:") ->
+                                onComplete("SPLIT_BUNDLE_NO_RUNTIME", error.removePrefix("NO_RUNTIME:"))
+                            error.startsWith("IO_ERROR:") ->
+                                onComplete("SPLIT_BUNDLE_IO_ERROR", error.removePrefix("IO_ERROR:"))
+                            else ->
+                                onComplete("SPLIT_BUNDLE_EVAL_ERROR", error)
+                        }
+                    }
+                }
+            }
+        } catch (e: Throwable) {
+            // nativeEvaluateSegmentInBackground itself failed to dispatch (e.g.
+            // UnsatisfiedLinkError). Fail closed; do NOT fall back to the
+            // race-prone registerSegment path.
+            if (settled.compareAndSet(false, true)) {
+                watchdog.removeCallbacks(timeoutRunnable)
+                BTLogger.error("[SplitBundle] FATAL: nativeEvaluateSegmentInBackground threw for id=$segmentId: ${e.message}")
+                onComplete("SPLIT_BUNDLE_NATIVE_UNAVAILABLE", "Bg native segment eval unavailable: ${e.message}")
             }
-        } catch (e: Exception) {
-            BTLogger.error("Failed to register segment in background runtime: ${e.message}")
-            onComplete(e)
         }
     }
 

package/android/src/main/java/com/backgroundthread/BackgroundThreadModule.kt

@@ -30,9 +30,17 @@ class BackgroundThreadModule(reactContext: ReactApplicationContext) :
 
     override fun loadSegmentInBackground(segmentId: Double, path: String, promise: Promise) {
         BackgroundThreadManager.getInstance()
-            .registerSegmentInBackground(segmentId.toInt(), path) { error ->
-                if (error != null) {
-                    promise.reject("BG_SEGMENT_LOAD_ERROR", error.message, error)
+            .registerSegmentInBackground(segmentId.toInt(), path) { code, message ->
+                if (code != null) {
+                    // Reject with the SHARED split-bundle contract code (e.g.
+                    // SPLIT_BUNDLE_NO_RUNTIME / SPLIT_BUNDLE_TIMEOUT are
+                    // retryable; SPLIT_BUNDLE_IO_ERROR / SPLIT_BUNDLE_EVAL_ERROR
+                    // / SPLIT_BUNDLE_NATIVE_UNAVAILABLE / SPLIT_BUNDLE_NOT_FOUND
+                    // are not) so the JS loader classifies retryability the same
+                    // way it does for the main path. registerSegmentInBackground
+                    // always supplies one of these contract codes here, so there
+                    // is no legacy/opaque default string to fall back to.
+                    promise.reject(code, message)
                 } else {
                     promise.resolve(null)
                 }

package/ios/BackgroundThread.mm

@@ -38,7 +38,54 @@
                                     path:path
                               completion:^(NSError * _Nullable error) {
         if (error) {
-            reject(@"BG_SEGMENT_LOAD_ERROR", error.localizedDescription, error);
+            // Fix 1/E: map the manager's DISTINCT NSError.code to its own JS
+            // reject code (matching SplitBundleLoader's main-runtime mapping and
+            // the shared error-code contract) so JS can classify
+            // retryable-vs-fatal. EVERY EBgMgrSegmentEvalError case is mapped
+            // EXPLICITLY here — there is no silent `default → NO_RUNTIME` that
+            // could MISCLASSIFY a fatal failure (e.g. a missing segment file)
+            // as a transient runtime-not-ready that gets retried/masked. The old
+            // code both collapsed bg failures into one opaque
+            // `BG_SEGMENT_LOAD_ERROR` and (before that) let raw codes 1/2 fall
+            // through `default` to retryable NO_RUNTIME.
+            NSString *rejectCode;
+            switch ((EBgMgrSegmentEvalError)error.code) {
+                case EBgMgrSegmentEvalErrorNotStarted:
+                case EBgMgrSegmentEvalErrorNilInstance:
+                    // Bg runtime not started / RCTInstance nil — TRANSIENT: the
+                    // bg host simply wasn't ready yet; a later attempt may win.
+                    rejectCode = @"SPLIT_BUNDLE_NO_RUNTIME";        // retryable
+                    break;
+                case EBgMgrSegmentEvalErrorFileNotFound:
+                    // Segment file missing — FATAL packaging/OTA corruption.
+                    rejectCode = @"SPLIT_BUNDLE_NOT_FOUND";         // fatal
+                    break;
+                case EBgMgrSegmentEvalErrorIvarMissing:
+                    // `_rctInstance` ivar reflection failed — STRUCTURAL/PERMANENT
+                    // (an RN bump renamed the private field). Retrying is futile.
+                    rejectCode = @"SPLIT_BUNDLE_NATIVE_UNAVAILABLE"; // fatal
+                    break;
+                case EBgMgrSegmentEvalErrorIORead:
+                    rejectCode = @"SPLIT_BUNDLE_IO_ERROR";          // fatal
+                    break;
+                case EBgMgrSegmentEvalErrorEvalThrow:
+                    rejectCode = @"SPLIT_BUNDLE_EVAL_ERROR";        // fatal (segment bug)
+                    break;
+                case EBgMgrSegmentEvalErrorTimeout:
+                    rejectCode = @"SPLIT_BUNDLE_TIMEOUT";           // retryable
+                    break;
+                default:
+                    // Defensive LAST RESORT only: every real EBgMgrSegmentEvalError
+                    // case is handled above, so reaching here means the manager
+                    // emitted an unmapped code (a bug). Choose retryable
+                    // NO_RUNTIME so a stale/unknown native build degrades safely
+                    // rather than permanently poisoning a segment — but log it
+                    // loudly so the unmapped code is caught and named.
+                    [BTLogger warn:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: UNMAPPED EBgMgrSegmentEvalError code=%ld — defaulting to retryable NO_RUNTIME. This is a native bug: add an explicit case.", (long)error.code]];
+                    rejectCode = @"SPLIT_BUNDLE_NO_RUNTIME";        // retryable (defensive)
+                    break;
+            }
+            reject(rejectCode, error.localizedDescription, error);
         } else {
             resolve(nil);
         }

package/ios/BackgroundThreadManager.h

@@ -6,6 +6,49 @@ NS_ASSUME_NONNULL_BEGIN
 @class RCTReactNativeFactory;
 @class RCTHost;
 
+/// NSError `code` values produced by `registerSegmentInBackground:` /
+/// `evaluateSegmentInBackground:` under the `BackgroundThread` error domain.
+///
+/// These are DISTINCT (kept numerically aligned with SplitBundleLoader's
+/// `ESegmentEvalError`) so the TurboModule boundary
+/// (`BackgroundThread.loadSegmentInBackground`) can map each to its OWN JS
+/// reject code and JS can classify retryable-vs-fatal — rather than collapsing
+/// every bg failure into one opaque code (fix E). EVERY failure the manager
+/// produces MUST have a NAMED case here so the boundary's switch maps it
+/// explicitly: a raw integer literal would fall through to the boundary's
+/// defensive `default` (→ retryable NO_RUNTIME) and silently MISCLASSIFY a
+/// fatal failure (e.g. a missing segment file) as a transient one that gets
+/// retried/masked instead of surfaced. The mapping the boundary applies is:
+///   - NotStarted  (bg runtime not started yet) → `SPLIT_BUNDLE_NO_RUNTIME`     (retryable)
+///   - FileNotFound (segment file missing)      → `SPLIT_BUNDLE_NOT_FOUND`      (fatal)
+///   - NilInstance (bg RCTInstance is nil)      → `SPLIT_BUNDLE_NO_RUNTIME`     (retryable)
+///   - IORead      (file read/mmap failed)      → `SPLIT_BUNDLE_IO_ERROR`       (fatal)
+///   - EvalThrow   (segment JS/Hermes bug)      → `SPLIT_BUNDLE_EVAL_ERROR`     (fatal)
+///   - Timeout     (buffered executor never ran)→ `SPLIT_BUNDLE_TIMEOUT`        (retryable)
+///   - IvarMissing (`_rctInstance` reflection
+///                  failed — STRUCTURAL/permanent)→ `SPLIT_BUNDLE_NATIVE_UNAVAILABLE` (fatal)
+///
+/// WHY NilInstance and IvarMissing are split (and not both NO_RUNTIME): a nil
+/// RCTInstance is TRANSIENT — the bg host just isn't up yet, a later attempt
+/// can succeed. A missing `_rctInstance` ivar is STRUCTURAL/PERMANENT — an RN
+/// version bump renamed/removed the private field our reflection depends on, so
+/// bg segment loading is disabled until the native code is updated. Retrying
+/// the latter is futile, so it maps to fatal NATIVE_UNAVAILABLE.
+///
+/// Declared here (not file-local in the .mm) so the boundary references these
+/// by NAME — a future renumbering stays exact instead of drifting against a
+/// hardcoded magic-number switch. Values 3-6 are kept STABLE; 1/2/7 fill in the
+/// previously-raw `registerSegmentInBackground:` codes and the structural split.
+typedef NS_ENUM(NSInteger, EBgMgrSegmentEvalError) {
+    EBgMgrSegmentEvalErrorNotStarted = 1,   // bg runtime not started yet (retryable)
+    EBgMgrSegmentEvalErrorFileNotFound = 2, // segment file missing (fatal)
+    EBgMgrSegmentEvalErrorNilInstance = 3,  // bg RCTInstance is nil (retryable)
+    EBgMgrSegmentEvalErrorIORead = 4,       // file read/mmap failed (fatal)
+    EBgMgrSegmentEvalErrorEvalThrow = 5,    // segment JS/Hermes bug (fatal)
+    EBgMgrSegmentEvalErrorTimeout = 6,      // buffered executor never ran (retryable)
+    EBgMgrSegmentEvalErrorIvarMissing = 7,  // `_rctInstance` ivar reflection failed (fatal, structural)
+};
+
 @interface BackgroundThreadManager : NSObject
 
 /// Shared instance for singleton pattern

package/ios/BackgroundThreadManager.mm

@@ -20,6 +20,82 @@
 #import <React/RCTReloadCommand.h>
 #import <ReactCommon/RCTHost.h>
 #import <objc/runtime.h>
+#import <os/lock.h>
+#include <jsi/jsi.h>
+#include <cstdint>
+
+namespace {
+
+// Zero-copy jsi::Buffer that retains its NSData for the async (buffered)
+// executor block's lifetime — same rationale as SplitBundleLoader's
+// NSDataJSIBuffer (M4/M5): no second full copy of the segment bytes, and the
+// mmap'd/heap bytes stay alive because the buffer owns the NSData.
+class BgMgrNSDataJSIBuffer : public facebook::jsi::Buffer {
+ public:
+  explicit BgMgrNSDataJSIBuffer(NSData *data) : data_(data) {}
+  size_t size() const override { return data_.length; }
+  const uint8_t *data() const override {
+    return static_cast<const uint8_t *>(data_.bytes);
+  }
+
+ private:
+  NSData *data_;  // strong retain (ARC).
+};
+
+}  // namespace
+
+// Exactly-once settle guard for the bg watchdog — same design as
+// SplitBundleLoader's SBLSettleGuard. An ARC object captured by both the
+// executor block and the watchdog dispatch_after; ARC keeps its lock alive
+// until both release, so neither block needs (or may do) a manual free —
+// avoiding the use-after-free that would occur if either freed the lock while
+// the other still runs.
+@interface BgMgrSettleGuard : NSObject
+- (BOOL)tryClaim;
+@end
+
+@implementation BgMgrSettleGuard {
+  os_unfair_lock _lock;
+  BOOL _settled;
+}
+- (instancetype)init {
+  if (self = [super init]) {
+    _lock = OS_UNFAIR_LOCK_INIT;
+    _settled = NO;
+  }
+  return self;
+}
+- (BOOL)tryClaim {
+  os_unfair_lock_lock(&_lock);
+  BOOL won = !_settled;
+  if (won) {
+    _settled = YES;
+  }
+  os_unfair_lock_unlock(&_lock);
+  return won;
+}
+@end
+
+// Watchdog window for the bg buffered runtime executor (H2 = bg-runtime port of
+// SplitBundleLoader's C1). The bg runtime's buffered executor stays buffered
+// until the bg entry bundle finishes evaluating in
+// BackgroundReactNativeDelegate.hostDidStart:; if that never completes (host
+// teardown, OTA-resolve abort), the block never runs — without this watchdog
+// the JS promise would hang inflightSegments forever.
+//
+// Fix G: 30s (matching Android and the main-runtime watchdog). The buffered
+// executor stays buffered until the bg ENTRY bundle finishes evaluating; on a
+// slow/throttled cold start that entry eval can itself exceed 10s, which would
+// falsely trip the watchdog on a load that was about to succeed. 30s keeps the
+// genuine-wedge safety net while leaving generous headroom for slow cold starts.
+static const NSTimeInterval kBgSegmentEvalWatchdogSeconds = 30.0;
+
+// EBgMgrSegmentEvalError NSError `code` values are declared in
+// BackgroundThreadManager.h so the TurboModule boundary
+// (BackgroundThread.loadSegmentInBackground) can map each distinct code to its
+// own JS reject code by NAME. They stay numerically aligned with
+// SplitBundleLoader's ESegmentEvalError; see installProdBundleLoader.ts for the
+// retryable-vs-fatal classification (H3 / fix E).
 
 @interface BackgroundThreadManager ()
 @property (nonatomic, strong) BackgroundReactNativeDelegate *reactNativeFactoryDelegate;
@@ -201,33 +277,166 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
                          completion:(void (^)(NSError * _Nullable error))completion
 {
     if (!self.isStarted || !self.reactNativeFactoryDelegate) {
+        // Transient: the bg runtime just isn't up yet. NotStarted → NO_RUNTIME
+        // (retryable). Previously a raw `code:1` which fell through the
+        // boundary's `default` — same destination, but now NAMED so the mapping
+        // is explicit and can never drift (fix 1 / E).
         NSError *error = [NSError errorWithDomain:@"BackgroundThread"
-                                             code:1
+                                             code:EBgMgrSegmentEvalErrorNotStarted
                                          userInfo:@{NSLocalizedDescriptionKey: @"Background runtime not started"}];
         if (completion) completion(error);
         return;
     }
 
-    // Verify the file exists
+    // Verify the file exists. FATAL: a missing segment file is real packaging /
+    // OTA corruption — retrying just re-misses. Previously a raw `code:2` that
+    // the boundary's `default` MISCLASSIFIED as retryable NO_RUNTIME, masking
+    // the corruption; now FileNotFound → NOT_FOUND (fatal) (fix 1 / E — the
+    // NO-SHIP blocker).
     if (![[NSFileManager defaultManager] fileExistsAtPath:path]) {
         NSError *error = [NSError errorWithDomain:@"BackgroundThread"
-                                             code:2
+                                             code:EBgMgrSegmentEvalErrorFileNotFound
                                          userInfo:@{NSLocalizedDescriptionKey:
                                                         [NSString stringWithFormat:@"Segment file not found: %@", path]}];
         if (completion) completion(error);
         return;
     }
 
-    BOOL success = [self.reactNativeFactoryDelegate registerSegmentWithId:segmentId path:path];
-    if (success) {
-        if (completion) completion(nil);
-    } else {
+    [self evaluateSegmentInBackground:segmentId path:path completion:completion];
+}
+
+// Evaluate-then-resolve segment load for the BACKGROUND runtime (H2).
+//
+// WHY THIS REPLACES registerSegmentWithId: + immediate completion(nil):
+// The old path called `[delegate registerSegmentWithId:path:]` (which routes to
+// RCTInstance/ReactInstance::registerSegment — that only ENQUEUES
+// `runtime.evaluateJavaScript(segment)` on the runtime scheduler and returns)
+// then resolved the JS promise immediately. That is the exact
+// "Requiring unknown module" race the MAIN runtime already fixed in
+// SplitBundleLoader: Metro's `import().then(() => __r(moduleId))` microtask can
+// run `__r` BEFORE the scheduled eval populated the module table → a FATAL,
+// uncatchable crash. Locale segments load through THIS path in the bg runtime
+// (ServiceSetting.refreshLocaleMessages → import('./json/*.json') runs in
+// kit-bg), so a language switch could still crash.
+//
+// Fix: evaluate the segment OURSELVES inside one
+// `callFunctionOnBufferedRuntimeExecutor:` block on the bg RCTInstance and
+// signal completion in that SAME block, strictly AFTER eval — making eval +
+// resolve one atomic unit so any subsequent `__r(moduleId)` finds the module.
+// The bg RCTInstance is the delegate's private `_rctInstance` ivar; we read it
+// reflectively (the same pattern installSharedBridgeInMainRuntime: uses on the
+// main host) to keep this fix self-contained in this file rather than widening
+// the delegate's surface. Includes the same exactly-once + watchdog guard as
+// the main-runtime fix (C1) because the bg buffered executor is likewise
+// buffered until the bg entry bundle finishes evaluating in hostDidStart:.
+- (void)evaluateSegmentInBackground:(NSNumber *)segmentId
+                               path:(NSString *)path
+                         completion:(void (^)(NSError * _Nullable error))completion
+{
+    // Reach the bg RCTInstance via the delegate's `_rctInstance` ivar. `id`
+    // (not a typed RCTInstance*) mirrors installSharedBridgeInMainRuntime:'s
+    // untyped handling and avoids needing the RCTInstance header here.
+    BackgroundReactNativeDelegate *delegate = self.reactNativeFactoryDelegate;
+    Ivar ivar = class_getInstanceVariable([delegate class], "_rctInstance");
+    if (!ivar) {
+        // Loud failure (L7 parity): a future RN/delegate refactor that renames
+        // this ivar silently disables ALL bg segment loading — surface it.
+        // STRUCTURAL/PERMANENT (not transient): retrying can never recreate a
+        // renamed ivar, so this maps to fatal NATIVE_UNAVAILABLE — distinct from
+        // the nil-instance case below, which IS transient. Misclassifying this
+        // as NO_RUNTIME would make JS retry a permanently-broken reflection.
+        [BTLogger error:[NSString stringWithFormat:@"[SplitBundle] FATAL: _rctInstance ivar not found on %@ — bg segment loading is DISABLED.", [delegate class]]];
         NSError *error = [NSError errorWithDomain:@"BackgroundThread"
-                                             code:3
-                                         userInfo:@{NSLocalizedDescriptionKey:
-                                                        @"Failed to register segment in background runtime"}];
+                                             code:EBgMgrSegmentEvalErrorIvarMissing
+                                         userInfo:@{NSLocalizedDescriptionKey: @"_rctInstance ivar not found on bg delegate"}];
+        if (completion) completion(error);
+        return;
+    }
+    id instance = object_getIvar(delegate, ivar);
+    if (!instance) {
+        [BTLogger error:@"[SplitBundle] bg loadSegment: background RCTInstance not available"];
+        NSError *error = [NSError errorWithDomain:@"BackgroundThread"
+                                             code:EBgMgrSegmentEvalErrorNilInstance
+                                         userInfo:@{NSLocalizedDescriptionKey: @"Background RCTInstance not available"}];
         if (completion) completion(error);
+        return;
     }
+
+    // M4/M5: mmap + zero-copy buffer (retains the NSData for the async block).
+    NSError *readError = nil;
+    NSData *data = [NSData dataWithContentsOfFile:path
+                                         options:NSDataReadingMappedIfSafe
+                                           error:&readError];
+    if (!data || data.length == 0) {
+        NSError *error = [NSError errorWithDomain:@"BackgroundThread"
+                                             code:EBgMgrSegmentEvalErrorIORead
+                                         userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Failed to read bg segment at %@%@", path, readError ? [NSString stringWithFormat:@": %@", readError.localizedDescription] : @""]}];
+        if (completion) completion(error);
+        return;
+    }
+
+    // M6: synthetic `seg-<id>.js` source URL for in-segment crash symbolication.
+    int segIdInt = segmentId.intValue;
+    NSString *sourceURL = [NSString stringWithFormat:@"seg-%d.js", segIdInt];
+
+    // C1: exactly-once guard shared (and retained) by the executor block and the
+    // watchdog. ARC-owned so the lock outlives both with no manual free.
+    BgMgrSettleGuard *settleGuard = [[BgMgrSettleGuard alloc] init];
+
+    CFAbsoluteTime dispatchStart = CFAbsoluteTimeGetCurrent();
+    [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: evaluating %@ (id=%d, %lu bytes)", sourceURL, segIdInt, (unsigned long)data.length]];
+
+    // No __weak dance needed here (unlike the SharedRPC executor): this block
+    // does not re-dispatch onto the instance — it runs synchronously inside the
+    // instance's own runtime executor with a live `runtime &`, so by the time it
+    // executes the instance is necessarily still alive.
+    [instance callFunctionOnBufferedRuntimeExecutor:^(facebook::jsi::Runtime &runtime) {
+        @autoreleasepool {
+            BOOL won = [settleGuard tryClaim];
+            NSError *evalError = nil;
+            CFAbsoluteTime evalStart = CFAbsoluteTimeGetCurrent();
+            try {
+                auto buffer = std::make_shared<BgMgrNSDataJSIBuffer>(data);
+                runtime.evaluateJavaScript(buffer, [sourceURL UTF8String]);
+                double evalMs = (CFAbsoluteTimeGetCurrent() - evalStart) * 1000.0;
+                [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: %@ evaluated in %.1fms", sourceURL, evalMs]];
+            } catch (const std::exception &e) {
+                evalError = [NSError errorWithDomain:@"BackgroundThread"
+                                                code:EBgMgrSegmentEvalErrorEvalThrow
+                                            userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Bg segment evaluation failed for %@: %s", sourceURL, e.what()]}];
+                [BTLogger error:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: %@ evaluation threw: %s", sourceURL, e.what()]];
+            } catch (...) {
+                evalError = [NSError errorWithDomain:@"BackgroundThread"
+                                                code:EBgMgrSegmentEvalErrorEvalThrow
+                                            userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Bg segment evaluation failed for %@ (unknown C++ exception)", sourceURL]}];
+                [BTLogger error:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: %@ evaluation threw an unknown exception", sourceURL]];
+            }
+            if (won) {
+                // Resolve AFTER eval — the ordering guarantee that fixes the race.
+                if (completion) completion(evalError);
+            } else {
+                [BTLogger warn:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: %@ evaluated AFTER watchdog already settled (bg entry was wedged >%.0fs)", sourceURL, kBgSegmentEvalWatchdogSeconds]];
+            }
+        }
+    }];
+
+    // C1 watchdog — fires only on a genuine wedge (bg entry bundle never
+    // finished evaluating). Rejects with a retryable timeout so the JS loader
+    // re-attempts. settleGuard is retained by this block, so the lock stays
+    // valid even if the executor block later runs.
+    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(kBgSegmentEvalWatchdogSeconds * NSEC_PER_SEC)),
+                   dispatch_get_global_queue(QOS_CLASS_UTILITY, 0), ^{
+        if ([settleGuard tryClaim]) {
+            [BTLogger error:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: %@ WATCHDOG fired after %.0fs — bg runtime executor never ran (bg entry bundle likely never finished evaluating). Rejecting as retryable timeout.", sourceURL, kBgSegmentEvalWatchdogSeconds]];
+            NSError *timeoutError = [NSError errorWithDomain:@"BackgroundThread"
+                                                        code:EBgMgrSegmentEvalErrorTimeout
+                                                    userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Bg segment %@ eval timed out after %.0fs (buffered runtime executor never ran)", sourceURL, kBgSegmentEvalWatchdogSeconds]}];
+            if (completion) completion(timeoutError);
+        }
+    });
+
+    double dispatchMs = (CFAbsoluteTimeGetCurrent() - dispatchStart) * 1000.0;
+    [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg loadSegment: %@ dispatched in %.1fms (resolve fires after eval; watchdog %.0fs)", sourceURL, dispatchMs, kBgSegmentEvalWatchdogSeconds]];
 }
 
 #pragma mark - Restart

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-background-thread",
-  "version": "3.0.60",
+  "version": "3.0.61",
   "description": "react-native-background-thread",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",