@onekeyfe/react-native-background-thread 3.0.63 → 3.0.65

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>
@@ -79,6 +80,11 @@ static constexpr size_t kRuntimeQueueWarnInterval = 128;
 struct RuntimeWorkQueue {
     std::deque<std::function<void(jsi::Runtime &)>> items;
     bool drainScheduled = false;
+    // workId of the drain currently posted to gPendingWork (valid only while
+    // drainScheduled == true). Tracked so a teardown path (nativeInvalidate
+    // SharedRpc) can erase the orphaned gPendingWork entry if its posted drain
+    // is dropped during reload. -1 means "none outstanding".
+    int64_t scheduledDrainWorkId = -1;
 };
 
 static RuntimeWorkQueue gMainRuntimeWorkQueue;
@@ -88,6 +94,20 @@ static RuntimeWorkQueue &getRuntimeWorkQueue(bool isMain) {
     return isMain ? gMainRuntimeWorkQueue : gBgRuntimeWorkQueue;
 }
 
+// Caller MUST hold gWorkMutex. Intentionally leak (abandon) each queued functor
+// — its ~jsi::Function must not run off the JS thread / on a dead runtime — then
+// clear the queue and disarm the drain latch so a recovered runtime re-arms a
+// fresh drain on the next enqueue instead of stranding work behind a stale
+// drainScheduled==true.
+static void leakAndClearRuntimeQueue(RuntimeWorkQueue &queue) {
+    for (auto &work : queue.items) {
+        new std::function<void(jsi::Runtime &)>(std::move(work));
+    }
+    queue.items.clear();
+    queue.drainScheduled = false;
+    queue.scheduledDrainWorkId = -1;
+}
+
 static bool callScheduleOnJSThread(const JavaObjectRef &ref, bool isMain, int64_t workId) {
     JNIEnv *env = getJNIEnv();
     if (!env || !ref) {
@@ -133,6 +153,8 @@ static bool callScheduleOnJSThread(const JavaObjectRef &ref, bool isMain, int64_
     return scheduled == JNI_TRUE;
 }
 
+static void drainPendingBgEvals(const std::string &reason);
+
 static void scheduleRuntimeDrain(const JavaObjectRef &ref, bool isMain);
 
 static void drainRuntimeWorkQueue(jsi::Runtime &rt, JavaObjectRef ref, bool isMain) {
@@ -170,6 +192,9 @@ static void drainRuntimeWorkQueue(jsi::Runtime &rt, JavaObjectRef ref, bool isMa
         remaining = queue.items.size();
         if (remaining == 0) {
             queue.drainScheduled = false;
+            // This drain's gPendingWork entry was already erased by
+            // nativeExecuteWork before it ran; its workId is now stale.
+            queue.scheduledDrainWorkId = -1;
         } else {
             shouldReschedule = true;
         }
@@ -190,8 +215,24 @@ static void scheduleRuntimeDrain(const JavaObjectRef &ref, bool isMain) {
     size_t queued = 0;
     {
         std::lock_guard<std::mutex> lock(gWorkMutex);
+        auto &queue = getRuntimeWorkQueue(isMain);
+        // Stale-id guard: drainRuntimeWorkQueue observes remaining>0, drops the
+        // lock, then calls us — but a concurrent nativeInvalidateSharedRpc can
+        // clear the queue + latch in between. If the queue is now empty there is
+        // nothing to drain: do NOT post a gPendingWork entry / scheduleOnJSThread
+        // for an already-drained/invalidated queue. Just disarm the latch and
+        // return. The normal enqueue→schedule path always has items.size()>=1, so
+        // this never short-circuits it.
+        if (queue.items.empty()) {
+            queue.drainScheduled = false;
+            queue.scheduledDrainWorkId = -1;
+            return;
+        }
         workId = gNextWorkId++;
-        queued = getRuntimeWorkQueue(isMain).items.size();
+        queued = queue.items.size();
+        // Track the outstanding drain's workId so a teardown path can erase its
+        // orphaned gPendingWork entry if the post is dropped during reload.
+        queue.scheduledDrainWorkId = workId;
         gPendingWork[workId] = [ref, isMain](jsi::Runtime &rt) {
             drainRuntimeWorkQueue(rt, ref, isMain);
         };
@@ -199,11 +240,23 @@ static void scheduleRuntimeDrain(const JavaObjectRef &ref, bool isMain) {
 
     bool scheduled = callScheduleOnJSThread(ref, isMain, workId);
     if (!scheduled) {
-        std::lock_guard<std::mutex> lock(gWorkMutex);
-        gPendingWork.erase(workId);
-        getRuntimeWorkQueue(isMain).drainScheduled = false;
-        LOGE("executor: failed to schedule runtime drain isMain=%d, workId=%ld, queued=%zu",
-             isMain, (long)workId, queued);
+        {
+            std::lock_guard<std::mutex> lock(gWorkMutex);
+            gPendingWork.erase(workId);
+            leakAndClearRuntimeQueue(getRuntimeWorkQueue(isMain));
+            LOGE("executor: failed to schedule runtime drain isMain=%d, workId=%ld, queued=%zu",
+                 isMain, (long)workId, queued);
+        }
+        // The bg JS thread is unreachable, so the queued bg-eval lambdas will
+        // never run. Settle any in-flight bg eval (retryable NO_RUNTIME) so its
+        // JNI global ref is released and the JS promise resolves now instead of
+        // hanging on the Kotlin 30s watchdog. Gated on !isMain — a main-thread
+        // schedule hiccup must never falsely reject healthy bg evals. Called
+        // outside gWorkMutex: drainPendingBgEvals takes gBgEvalMutex and does a
+        // Java upcall, so it must not run under a native lock.
+        if (!isMain) {
+            drainPendingBgEvals("Background JS thread unreachable when scheduling segment eval");
+        }
     }
 }
 
@@ -607,6 +660,351 @@ 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. If the
+        // entry is ALREADY gone, a drop/destroy drain (drainPendingBgEvals)
+        // already settled this eval as retryable NO_RUNTIME and JS will retry —
+        // so we must NOT evaluate the segment again. This is reachable because a
+        // ptr==0 reload keeps this lambda in the coalesced queue (it only
+        // disarms the drain latch, preserving queue.items) and the recovered
+        // runtime's install-recover replays it; without this guard the segment
+        // would be evaluated twice on the recovered runtime.
+        {
+            std::lock_guard<std::mutex> lock(gBgEvalMutex);
+            if (gPendingBgEvals.erase(bgEvalId) == 0) {
+                return;
+            }
+        }
+        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 runtime unreachable
+// (context==null / ptr==0) and returned WITHOUT calling nativeExecuteWork for
+// this `workId`. Several things must be released for the given runtime:
+//   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 coalesced RuntimeWorkQueue's drain latch for this runtime — under
+//      the coalesced model a successful post (scheduled==true) that never
+//      reaches the JS thread leaves the queue stranded with drainScheduled==
+//      true, so a recovered runtime would never re-arm a drain. This is a
+//      TRANSIENT condition: ptr==0 happens during reload, and the SAME runtime
+//      recovers with a fresh ptr. We therefore must NOT leak+clear queue.items
+//      — the main runtime has no JS-side retry net, so abandoning its queued
+//      SharedRPC deliveries (notifyOtherRuntime) loses them forever. Instead we
+//      only reset the drain latch (drainScheduled / scheduledDrainWorkId) so the
+//      next enqueue re-arms a fresh drain, leaving queue.items intact for the
+//      recovered runtime to drain. Applies to BOTH runtimes (isMain selects).
+//   3. (bg only) 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 */, jboolean isMain, jlong workId) {
+    {
+        std::lock_guard<std::mutex> lock(gWorkMutex);
+        gPendingWork.erase(static_cast<int64_t>(workId));
+        // TRANSIENT ptr==0 (reload in flight): do NOT abandon queue.items — the
+        // recovered runtime still needs them (main has no JS retry net). Only
+        // disarm the drain latch so the next enqueue re-arms a fresh drain.
+        auto &queue = getRuntimeWorkQueue(static_cast<bool>(isMain));
+        queue.drainScheduled = false;
+        queue.scheduledDrainWorkId = -1;
+    }
+    if (!isMain) {
+        drainPendingBgEvals("Background runtime unreachable when scheduling segment eval");
+    }
+}
+
 // ── nativeInstallSharedBridge ───────────────────────────────────────────
 // Install SharedStore and SharedRPC into a runtime.
 extern "C" JNIEXPORT void JNICALL
@@ -630,6 +1028,11 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
     bool capturedIsMain = static_cast<bool>(isMain);
 
     RPCRuntimeExecutor executor = [ref, capturedIsMain](std::function<void(jsi::Runtime &)> work) {
+        // Coalesce per-runtime work into a single batched drain (see
+        // enqueueRuntimeWork) instead of one Kotlin scheduleOnJSThread hop per
+        // item. The bg-eval failure-drain that previously lived inline here now
+        // runs in scheduleRuntimeDrain's schedule-failure path — under the
+        // coalesced model that is the single place a schedule can fail.
         enqueueRuntimeWork(ref, capturedIsMain, std::move(work));
     };
 
@@ -638,6 +1041,12 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
     // back to the bg JS queue. We must do this BEFORE moving `executor` into
     // SharedRPC::install (which will std::move it out).
     if (!capturedIsMain) {
+        // gBgTimerExecutor is read/cleared under gTimerMutex (timer worker
+        // snapshot ~L857, nativeDestroy ~L1133); this write must take the same
+        // lock or it races those readers (UB on std::function). nativeInstall
+        // SharedBridge holds no other lock here, so a narrow guard scoped to
+        // just the assignment is correct and cannot double-lock.
+        std::lock_guard<std::mutex> lock(gTimerMutex);
         gBgTimerExecutor = executor;
     }
     SharedRPC::install(*rt, std::move(executor), runtimeId);
@@ -650,6 +1059,37 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
         installTimersOnRuntime(*rt);
         invokeOptionalGlobalFunction(*rt, "__setupBackgroundRPCHandler");
     }
+
+    // Recover items stranded by a ptr==0 drop during reload. nativeDropScheduled
+    // Work deliberately KEEPS queue.items (main has no JS retry net) and only
+    // disarms the drain latch, relying on a LATER enqueue to re-arm a drain. But
+    // if no further enqueue arrives after this runtime recovers, those carried-
+    // over items (e.g. main-runtime notifyOtherRuntime deliveries) would sit
+    // until nativeDestroy and be lost. Make recovery structural.
+    //
+    // Force a fresh drain on the freshly installed runtime whenever the queue is
+    // non-empty, REGARDLESS of the drainScheduled latch: a drain posted before
+    // reload may have been queued on the now-dead pre-reload JS thread and
+    // silently discarded (its runnable never runs, so its nativeDropScheduledWork
+    // never fires and the latch is stuck drainScheduled==true). Gating recovery on
+    // !drainScheduled would then skip it and strand the items forever. Re-arming
+    // here on this runtime's executor (`ref`) guarantees they drain; if a stale
+    // drain is in fact still live, it self-cancels via the empty-queue guard in
+    // scheduleRuntimeDrain (at worst one benign extra drain hop). Mirror
+    // enqueueRuntimeWork's lock discipline: set the latch under gWorkMutex, call
+    // scheduleRuntimeDrain OUTSIDE the lock. Applies to BOTH runtimes.
+    bool shouldRecoverDrain = false;
+    {
+        std::lock_guard<std::mutex> lock(gWorkMutex);
+        auto &queue = getRuntimeWorkQueue(capturedIsMain);
+        if (!queue.items.empty()) {
+            queue.drainScheduled = true;
+            shouldRecoverDrain = true;
+        }
+    }
+    if (shouldRecoverDrain) {
+        scheduleRuntimeDrain(ref, capturedIsMain);
+    }
 }
 
 // ── nativeSetupErrorHandler ─────────────────────────────────────────────
@@ -734,6 +1174,26 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInvalidateSharedRpc(
     env->ReleaseStringUTFChars(runtimeId, idChars);
 
     bool found = SharedRPC::invalidate(id);
+
+    // The runtime named by `id` is being torn down (restart → host.reload).
+    // Its coalesced work queue must be fully quiesced: if a drain was posted
+    // (drainScheduled==true) but is dropped during reload, the latch would
+    // survive the reinstall and every future enqueue would see a stale
+    // drainScheduled==true → shouldSchedule stays false and new work enqueues
+    // but never schedules a drain again (work stranded forever). Leak+clear the
+    // queue (it's being destroyed anyway — the queued ~jsi::Function must not
+    // run on the dying runtime), reset the drain latch, and erase the orphaned
+    // gPendingWork entry for the outstanding drain. runtimeId "main" → isMain.
+    {
+        std::lock_guard<std::mutex> lock(gWorkMutex);
+        bool isMain = (id == "main");
+        auto &queue = getRuntimeWorkQueue(isMain);
+        if (queue.scheduledDrainWorkId >= 0) {
+            gPendingWork.erase(queue.scheduledDrainWorkId);
+        }
+        leakAndClearRuntimeQueue(queue);
+    }
+
     LOGI("nativeInvalidateSharedRpc: id=%s found=%d", id.c_str(), found ? 1 : 0);
     return found ? JNI_TRUE : JNI_FALSE;
 }
@@ -776,6 +1236,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) {
@@ -788,8 +1253,15 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeDestroy(
             }
             queue->items.clear();
             queue->drainScheduled = false;
+            queue->scheduledDrainWorkId = -1;
         }
     }
 
+    // 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,41 @@ 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
+    )
+
+    /**
+     * Clean up after a SUCCESSFUL scheduleOnJSThread post that nonetheless can
+     * never run: called from [scheduleOnJSThread]'s ptr == 0 branch (we are
+     * already on the stale/torn-down JS thread, so C++ saw scheduled == true and
+     * will not clean up on its own). For the given runtime ([isMain]) the native
+     * side erases gPendingWork[workId] (frees the captured segment source
+     * buffer) and resets drainScheduled so a recovered runtime re-arms a fresh
+     * drain on the next enqueue. This is a TRANSIENT reload condition, so the
+     * native side deliberately leaves the coalesced RuntimeWorkQueue's items
+     * INTACT — the same runtime recovers and the main runtime has no JS-side
+     * retry net, so abandoning its queued SharedRPC deliveries would lose them.
+     * For the bg runtime only, it also settles every in-flight bg
+     * segment eval as a retryable NO_RUNTIME failure so each JNI global ref is
+     * released and the JS promise resolves immediately instead of leaking until
+     * teardown or the bg watchdog. Exactly-once on the native side.
+     */
+    private external fun nativeDropScheduledWork(isMain: Boolean, workId: Long)
+
     /**
      * Synchronously mark the SharedRPC listener for `runtimeId` as dead
      * before the underlying JS runtime is torn down. See
@@ -412,6 +468,13 @@ 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 JS thread.
+            // Return false so the C++ coalesced scheduler
+            // (callScheduleOnJSThread → scheduleRuntimeDrain's !scheduled branch)
+            // does the FULL cleanup itself: erase gPendingWork[workId], leak+clear
+            // the coalesced RuntimeWorkQueue, reset drainScheduled, and (bg only)
+            // settle any in-flight bg eval as retryable NO_RUNTIME. No
+            // nativeDropScheduledWork call is needed here.
             return false
         }
         return try {
@@ -428,6 +491,17 @@ class BackgroundThreadManager private constructor() {
                     }
                 } else {
                     BTLogger.error("scheduleOnJSThread: ptr is 0! isMain=$isMain")
+                    // We are already on the (stale/torn-down) JS thread after a
+                    // SUCCESSFUL post (C++ saw scheduled==true), so the work won't
+                    // run and C++ won't clean up on its own. Drop it for THIS
+                    // runtime (main or bg): erase gPendingWork[workId] (frees the
+                    // source buffer) and reset drainScheduled so a recovered
+                    // runtime re-arms a fresh drain. The coalesced RuntimeWork
+                    // Queue items are left intact (transient reload; the same
+                    // runtime recovers and main has no JS retry net).
+                    // drainPendingBgEvals inside the native fn is
+                    // gated to !isMain, so settling bg evals only happens for bg.
+                    nativeDropScheduledWork(isMain, workId)
                 }
             }
             if (!posted) {
@@ -443,51 +517,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.63",
+  "version": "3.0.65",
   "description": "react-native-background-thread",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",