@shipvo/runtime 0.1.3 → 0.1.4

package/README.md

@@ -11,6 +11,14 @@ The native half of Shipvo's over-the-air updates, as an Expo module.
 { "expo": { "plugins": [["@shipvo/runtime", { "baseUrl": "https://<your control plane>", "publicKey": "<base64 Ed25519 public key>", "appId": "myshop" }]] } }
 ```
 
+Optional plugin props declare what the shell can run, so the control plane can skip releases it cannot use:
+
+```json
+{ "hermesBytecodeVersions": [96], "nativeModules": { "react-native-mmkv": "3.1.0" } }
+```
+
+They are written as Android meta-data `dev.shipvo.HERMES_BYTECODE_VERSIONS` (`96`) and `dev.shipvo.NATIVE_MODULES` (`react-native-mmkv@3.1.0`), and as Info.plist keys `ShipvoHermesBytecodeVersions` and `ShipvoNativeModules`. Leave them out and nothing is written. A non-integer version or an empty package name fails the build. The runtime does not read them yet.
+
 ```ts
 import { Runtime } from "@shipvo/runtime";
 const s = Runtime.getState();            // running / pending / previous release, band, baseUrl, appId
@@ -19,3 +27,21 @@ Runtime.markHealthy();                   // call once the first screen rendered
 ```
 
 `shipvo init` wires all of this for you.
+
+## Events to forward
+
+`Runtime.consumeEvents()` returns strings such as `verify_failed:<release>`. Forward `crash_loop_revert`, `rolled_back` and `verify_failed` to telemetry (`POST /t`), once per event. The sample app does this in `apps/tide-and-tackle/src/runtimeEvents.ts`. `verify_failed` is reported under the failed release id. A rejected or corrupt release then shows on the server, not only as repeated downloads.
+
+The runtime does not emit `download_failed` yet. The sample app and the control plane accept it, so it can be forwarded once the runtime raises it.
+
+`Runtime.consumeEvents()` can also return `pointer_rejected:<reason>` on Android when the control plane says this shell cannot run the newest release. It is queued once per reason. `/t` accepts `hermes_bytecode_mismatch`, `native_module_missing` and `native_module_version`. The sample app forwards the two native-module reasons under those names. `hermes_bytecode_mismatch` is its own event and carries a release id.
+
+Events are read at launch. A `verify_failed` raised during `checkForUpdate` is reported on the next cold start.
+
+## Crash after `markHealthy`
+
+`markHealthy` means the first screen rendered. It promotes a staged release, but it does not clear the unhealthy-boot count. The count is cleared when the app has stayed in the foreground for 30 seconds, or when it goes to background. If the process dies before that, the next launch counts as an unhealthy boot for that release. After 3 unhealthy boots inside 60 seconds the runtime blocks the release, goes back to the previous one and records `crash_loop_revert`.
+
+A good release that you open and kill in the foreground within 30 seconds, 4 times in 60 seconds, is reverted too. This is rare.
+
+Reverting does not undo changes the bad release made to app storage (files, databases, keychain, preferences). Write migrations so an older release can read newer data.

package/android/build.gradle

@@ -16,6 +16,7 @@ android {
 }
 
 dependencies {
+  testImplementation 'junit:junit:4.13.2'
   implementation 'com.facebook.react:react-android'
   // Ed25519 verification on Android 7+ (no platform Ed25519 before API 33). Pure Java, ~60 KB.
   implementation 'net.i2p.crypto:eddsa:0.3.0'

package/android/src/main/java/dev/shipvo/runtime/BootRules.kt

@@ -0,0 +1,53 @@
+package dev.shipvo.runtime
+
+/** The unhealthy-boot counters. `Store` implements it; tests use an in-memory copy. */
+internal interface BootCounts {
+  var unhealthyBoots: Int
+  var firstUnhealthyAt: Long
+}
+
+/** The crash-loop counting rules, free of Android types so a plain JVM test can run them. */
+internal object BootRules {
+  /** Counts one boot of the current release. Returns true when the release must be reverted. */
+  fun countBoot(c: BootCounts, now: Long, maxBoots: Int, windowMs: Long): Boolean {
+    if (now - c.firstUnhealthyAt > windowMs) { c.firstUnhealthyAt = now; c.unhealthyBoots = 0 }
+    c.unhealthyBoots = c.unhealthyBoots + 1
+    return c.unhealthyBoots > maxBoots
+  }
+
+  /** The promoting boot was a trial boot and was not counted. Count it now, until the app proves stable. */
+  fun countPromotedBoot(c: BootCounts, now: Long) { c.unhealthyBoots = 1; c.firstUnhealthyAt = now }
+
+  /** Whether a downloaded release may still be staged. Two overlapping checks can both pass the early "newer than known"
+   *  test. The second one must not stage the same release again: that would reset `trialBoots` and give a crashing release
+   *  more than MAX_BOOTS runs. Call this inside the handler lock, right before staging. */
+  fun mayStage(release: Int, current: Int, pending: Int, blocked: Int): Boolean = release > maxOf(current, pending, blocked)
+
+  fun clear(c: BootCounts) { c.unhealthyBoots = 0; c.firstUnhealthyAt = 0 }
+
+  /** The load that last reported healthy (0 = none). */
+  @Volatile var healthyLoad = 0
+
+  fun noteHealthy(load: Int) { healthyLoad = load }
+
+  /** The load that handled an uncaught JS error (0 = none). React destroys the host after such an error, which pauses the
+   *  activity. That pause must not count as a clean trip to the background. */
+  @Volatile var crashedLoad = 0
+
+  fun noteCrash(load: Int) { crashedLoad = load }
+
+  /** What `markHealthy` does to the counts: the promoting boot (if any) is counted, and `load` is recorded as healthy.
+   *  The module and the tests both call this, so they cannot drift apart. */
+  fun onHealthy(c: BootCounts, load: Int, now: Long, promoted: Boolean) {
+    if (promoted) countPromotedBoot(c, now)
+    noteHealthy(load)
+  }
+
+  /** Clears the counts only if `load` is the one that reported healthy and has not hit an uncaught JS error. A reloaded
+   *  load that has not called markHealthy yet keeps its count, so a crash before markHealthy still adds up.
+   *  Returns whether it cleared. */
+  fun markStableIfHealthy(c: BootCounts, load: Int): Boolean {
+    if (healthyLoad == 0 || healthyLoad != load || crashedLoad == load) return false
+    clear(c); return true
+  }
+}

package/android/src/main/java/dev/shipvo/runtime/HermesGuard.kt

@@ -0,0 +1,42 @@
+package dev.shipvo.runtime
+
+/** Refuses a release built for a different Hermes bytecode version than the shell runs. Runs in addition to the
+ *  signature and hash checks, never instead of them. Free of Android types so a plain JVM test can run it. */
+internal object HermesGuard {
+  const val REASON = "hermes_bytecode_mismatch"
+  private val MAGIC = byteArrayOf(0xc6.toByte(), 0x1f, 0xbc.toByte(), 0x03, 0xc1.toByte(), 0x03, 0x19, 0x1f)
+
+  /** The bytecode version in a bundle header (8-byte magic, then a 32-bit little-endian version), or null for plain JS. */
+  fun versionOf(head: ByteArray): Int? {
+    if (head.size < 12 || (0 until 8).any { head[it] != MAGIC[it] }) return null
+    val v = (0 until 4).fold(0L) { acc, i -> acc or ((head[8 + i].toLong() and 0xff) shl (8 * i)) }
+    return if (v in 1..Int.MAX_VALUE) v.toInt() else null
+  }
+
+  /** The first 12 bytes of a bundle stream, read until full or EOF. Null when the stream is missing or unreadable
+   *  ("unknown", so the release is applied as before). A short stream gives a short array, which `versionOf` maps to null. */
+  fun readHeader(open: () -> java.io.InputStream?): ByteArray? = try {
+    open()?.use { ins ->
+      val h = ByteArray(12); var n = 0
+      while (n < h.size) { val r = ins.read(h, n, h.size - n); if (r < 0) break; n += r }
+      h.copyOf(n)
+    }
+  } catch (_: java.io.IOException) { null }
+
+  /** The version field of a pointer body. Only a positive whole number counts; anything else is unknown. */
+  fun releaseVersionOf(raw: Any?): Int? = when (raw) {
+    is Int -> raw.takeIf { it > 0 }
+    is Long -> raw.takeIf { it in 1..Int.MAX_VALUE }?.toInt()
+    else -> null
+  }
+
+  /** The whole decision `check()` makes: the event to log when the release must be refused, or null to go on. */
+  fun decide(release: Int, rawReleaseVersion: Any?, openShellBundle: () -> java.io.InputStream?): String? =
+    mismatchEvent(release, releaseVersionOf(rawReleaseVersion), readHeader(openShellBundle)?.let { versionOf(it) })
+
+  /** The event to log when the release must be refused, or null when it may be staged.
+   *  A missing field on either side means "unknown", so the release is applied as before. */
+  fun mismatchEvent(release: Int, releaseVersion: Int?, shellVersion: Int?): String? =
+    if (releaseVersion == null || shellVersion == null || releaseVersion == shellVersion) null
+    else "$REASON:$release:release=$releaseVersion:shell=$shellVersion"
+}

package/android/src/main/java/dev/shipvo/runtime/PointerQuery.kt

@@ -0,0 +1,35 @@
+package dev.shipvo.runtime
+
+import java.net.URLEncoder
+
+/** Builds the pointer URL and reads the control plane's typed "not for this shell" answers. */
+internal object PointerQuery {
+  val MISMATCH_REASONS = setOf("hermes_bytecode_mismatch", "native_module_missing", "native_module_version")
+
+  private fun enc(v: String) = URLEncoder.encode(v, "UTF-8")
+
+  /** `hbc` is "96,98"; `nm` is "name@1.2.3,@scope/pkg@2.0.0". A blank value is treated as not declared. */
+  fun url(base: String, app: String, shellMajor: Int, band: String, hbc: String?, nm: String?): String {
+    val q = ArrayList<String>()
+    hbc?.split(',')?.map { it.trim() }?.filter { it.isNotEmpty() }?.takeIf { it.isNotEmpty() }
+      ?.let { q += "hbc=" + it.joinToString(",") { v -> enc(v) } }
+    nm?.split(',')?.map { it.trim() }?.filter { it.isNotEmpty() }?.takeIf { it.isNotEmpty() }
+      ?.let { q += "nm=" + it.joinToString(",") { v -> enc(v) } }
+    val path = "$base/p/$app/$shellMajor/$band.json"
+    return if (q.isEmpty()) path else path + "?" + q.joinToString("&")
+  }
+
+  /** The typed reason in a 404 body, or null for any other answer. */
+  fun mismatchReason(body: String?): String? {
+    val m = Regex("\"error\"\\s*:\\s*\"([a-z_]+)\"").find(body ?: return null) ?: return null
+    return m.groupValues[1].takeIf { it in MISMATCH_REASONS }
+  }
+
+  /**
+   * The event to queue for a rejected pointer, or null when the same reason is already queued.
+   * A shell that stays mismatched would otherwise add one event per check and push out
+   * `crash_loop_revert`, `rolled_back` and `verify_failed` (the queue keeps 50).
+   */
+  fun rejectionEvent(queued: List<String>, reason: String): String? =
+    "pointer_rejected:$reason".takeIf { it !in queued }
+}

package/android/src/main/java/dev/shipvo/runtime/ResumableDownload.kt

@@ -0,0 +1,39 @@
+package dev.shipvo.runtime
+
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+
+/** Resumable full-bundle download. It only moves bytes; the caller still checks the signed sha256 and size. */
+object ResumableDownload {
+  /** Partial download, named by the release sha256 so a different release never reuses it. */
+  fun partialFile(dir: File, sha: String) = File(dir, "dl-$sha.part")
+
+  /**
+   * Download into [part], resuming with `Range: bytes=<n>-` when a partial file exists. A 200 answer means the server
+   * ignored the range, so the file restarts. If the connection drops the partial file stays for the next attempt.
+   * Returns how many bytes were already on disk.
+   */
+  fun fetch(url: String, part: File, wantSize: Long): Long {
+    var offset = part.length()
+    if (offset > wantSize) { part.delete(); offset = 0 }
+    if (offset == wantSize) return offset
+    for (attempt in 0..1) {
+      val dl = (URL(url).openConnection() as HttpURLConnection).apply {
+        connectTimeout = 10_000; readTimeout = 30_000; useCaches = false
+        if (offset > 0) setRequestProperty("Range", "bytes=$offset-")
+      }
+      try {
+        val code = dl.responseCode
+        if (code == 416 && offset > 0 && attempt == 0) { part.delete(); offset = 0; continue }
+        require(code == 200 || (code == 206 && offset > 0)) { "bundle HTTP $code" }
+        val append = code == 206
+        if (!append) { part.delete(); offset = 0 }
+        dl.inputStream.use { ins -> FileOutputStream(part, append).use { ins.copyTo(it, 64 * 1024) } }
+        return offset
+      } finally { dl.disconnect() }
+    }
+    error("bundle download failed")
+  }
+}

package/android/src/main/java/dev/shipvo/runtime/ShipvoHostHandler.kt

@@ -40,10 +40,7 @@ class ShipvoHostHandler(private val ctx: Context) : ReactNativeHostHandler {
 
       val current = s.currentPath
       if (current != null && File(current).exists()) {
-        val now = s.now()
-        if (now - s.firstUnhealthyAt > WINDOW_MS) { s.firstUnhealthyAt = now; s.unhealthyBoots = 0 }
-        s.unhealthyBoots = s.unhealthyBoots + 1
-        if (s.unhealthyBoots > MAX_BOOTS) {
+        if (BootRules.countBoot(s, s.now(), MAX_BOOTS, WINDOW_MS)) {
           s.addEvent("crash_loop_revert:${s.currentRelease}")
           s.block(s.currentRelease)
           revertToPrevious(s)
@@ -65,13 +62,15 @@ class ShipvoHostHandler(private val ctx: Context) : ReactNativeHostHandler {
   companion object {
     const val MAX_BOOTS = 3
     const val WINDOW_MS = 60_000L
+    /** A release is stable once its process stayed in the foreground this long after markHealthy. iOS uses the same value. */
+    const val STABILITY_MS = 30_000L
     val LOCK = Any()
 
     internal fun revertToPrevious(s: Store) {
       s.currentPath?.let { if (it != s.previousPath) File(it).delete() }
       s.currentPath = s.previousPath; s.currentRelease = s.previousRelease; s.currentSha = null
       s.previousPath = null; s.previousRelease = 0
-      s.unhealthyBoots = 0; s.firstUnhealthyAt = 0
+      BootRules.clear(s)
     }
   }
 }

package/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt

@@ -52,12 +52,20 @@ class ShipvoRuntimeModule : Module() {
           s.addEvent("applied:${s.currentRelease}")
           promoted = true
         }
-        s.unhealthyBoots = 0; s.firstUnhealthyAt = 0
+        // The promoting boot was a trial boot and was not counted, so onHealthy counts it until the stability window ends.
+        // The counter is not cleared here: markStableIfHealthy does that after the window.
+        BootRules.onHealthy(s, Store.loadsInProcess, s.now(), promoted)
       }
+      scheduleStable()
       val kind = if (Store.loadsInProcess <= 1) "cold" else "reload"
       mapOf("release" to Store.runningRelease, "coldStartMs" to coldStart, "sinceLoadMs" to sinceLoad, "promoted" to promoted, "kind" to kind)
     }
 
+    // Called by the JS error handler before React destroys the host, so the pause that follows is not read as "stable".
+    Function("noteCrash") { synchronized(ShipvoHostHandler.LOCK) { BootRules.noteCrash(Store.loadsInProcess) } }
+
+    OnActivityEntersBackground { stableNow() }
+
     Function("consumeEvents") { Store(ctx).consumeEvents() }
 
     Function("rollback") {
@@ -75,7 +83,35 @@ class ShipvoRuntimeModule : Module() {
     Function("reload") { reloadHost() }
   }
 
+  /** Clears the unhealthy-boot count once the app stayed up for the stability window.
+   *  The task is dropped after it runs and on reload, and `markStableIfHealthy` checks the load number. */
+  private fun scheduleStable() {
+    val app = ctx
+    synchronized(ShipvoHostHandler.LOCK) {
+      stableTask?.let { handler.removeCallbacks(it) }
+      val load = Store.loadsInProcess
+      val task = Runnable {
+        synchronized(ShipvoHostHandler.LOCK) { BootRules.markStableIfHealthy(Store(app), load); stableTask = null }
+      }
+      stableTask = task
+      handler.postDelayed(task, ShipvoHostHandler.STABILITY_MS)
+    }
+  }
+
+  /** Going to background cleanly counts as stable, but only if this load reported healthy (see BootRules). */
+  private fun stableNow() {
+    synchronized(ShipvoHostHandler.LOCK) {
+      if (BootRules.markStableIfHealthy(Store(ctx), Store.loadsInProcess)) {
+        stableTask?.let { handler.removeCallbacks(it) }; stableTask = null
+      }
+    }
+  }
+
+  private val handler = Handler(Looper.getMainLooper())
+  private var stableTask: Runnable? = null
+
   private fun reloadHost() {
+    synchronized(ShipvoHostHandler.LOCK) { stableTask?.let { handler.removeCallbacks(it) }; stableTask = null }
     Handler(Looper.getMainLooper()).post {
       (ctx as? ReactApplication)?.reactHost?.reload("shipvo-update")
     }
@@ -93,9 +129,17 @@ class ShipvoRuntimeModule : Module() {
     val s = Store(ctx)
     require(s.baseUrl.isNotEmpty() && s.publicKey.isNotEmpty() && s.appId.isNotEmpty()) { "runtime not configured" }
     val known = maxOf(s.currentRelease, s.pendingRelease, s.blockedRelease)
-    val conn = http("${s.baseUrl}/p/${s.appId}/${s.shellMajor}/${s.band}.json", if (known > 0) "\"$known\"" else null)
+    val conn = http(PointerQuery.url(s.baseUrl, s.appId, s.shellMajor, s.band, s.hermesBytecodeVersions, s.nativeModules), if (known > 0) "\"$known\"" else null)
     val code = conn.responseCode
-    if (code == 304 || code == 404) { conn.disconnect(); return mapOf("status" to "none") }
+    if (code == 404) {
+      // The shell cannot run the newest release. Keep the current one and say why.
+      val reason = PointerQuery.mismatchReason(try { conn.errorStream?.bufferedReader()?.use { it.readText() } } catch (_: Exception) { null })
+      conn.disconnect()
+      if (reason == null) return mapOf("status" to "none")
+      PointerQuery.rejectionEvent(s.pendingEvents(), reason)?.let { s.addEvent(it) }
+      return mapOf("status" to "none", "reason" to reason)
+    }
+    if (code == 304) { conn.disconnect(); return mapOf("status" to "none") }
     require(code == 200) { "pointer HTTP $code" }
     val envelope = JSONObject(conn.inputStream.bufferedReader().use { it.readText() })
     conn.disconnect()
@@ -110,10 +154,18 @@ class ShipvoRuntimeModule : Module() {
     val shellVersion = ctx.packageManager.getPackageInfo(ctx.packageName, 0).versionName ?: "0.0.0"
     require(!Verify.semverLess(shellVersion, body.getString("min_shell_version"))) { "shell too old for release $release" }
     val verifyPointerMs = SystemClock.elapsedRealtime() - t0
+    // Beside the signature checks, not inside them: refuse a bundle built for another Hermes bytecode version.
+    HermesGuard.decide(release, body.opt("hermes_bytecode_version")) { try { ctx.assets.open("index.android.bundle") } catch (_: java.io.IOException) { null } }?.let { ev ->
+      s.addEvent(ev); s.block(release)
+      return mapOf("status" to "none", "reason" to HermesGuard.REASON)
+    }
 
     val core = body.getJSONObject("core")
     val wantSha = core.getString("sha256"); val wantSize = core.getLong("size")
     val tmp = File(s.dir, "dl-$release.tmp")
+    val part = ResumableDownload.partialFile(s.dir, wantSha)
+    // The release changed: partial files for other hashes can never complete.
+    s.dir.listFiles()?.forEach { if (it.extension == "part" && it.name != part.name) it.delete() }
     val d0 = SystemClock.elapsedRealtime()
     var via = "full"; var bytesDownloaded = 0L; var patchError: String? = null
 
@@ -142,22 +194,22 @@ class ShipvoRuntimeModule : Module() {
 
     // 2. Fall back to the full bundle.
     if (via == "full") {
-      val dl = http(resolve(s, core.getString("url")), null)
-      require(dl.responseCode == 200) { "bundle HTTP ${dl.responseCode}" }
-      dl.inputStream.use { ins -> tmp.outputStream().use { ins.copyTo(it, 64 * 1024) } }
-      dl.disconnect()
-      bytesDownloaded = tmp.length()
+      val resumedFrom = ResumableDownload.fetch(resolve(s, core.getString("url")), part, wantSize)
+      tmp.delete()
+      require(part.renameTo(tmp)) { "could not move downloaded bundle" }
+      bytesDownloaded = tmp.length() - resumedFrom
     }
     val downloadMs = SystemClock.elapsedRealtime() - d0
 
     val v0 = SystemClock.elapsedRealtime()
     val ok = tmp.length() == wantSize && Verify.sha256Hex(tmp) == wantSha
-    if (!ok) { tmp.delete(); s.addEvent("verify_failed:$release"); throw IllegalStateException("bundle hash/size mismatch") }
+    if (!ok) { tmp.delete(); part.delete(); s.addEvent("verify_failed:$release"); throw IllegalStateException("bundle hash/size mismatch") }
     val verifyMs = SystemClock.elapsedRealtime() - v0 + verifyPointerMs
 
     val dest = File(s.dir, "r$release.hbc")
     require(tmp.renameTo(dest)) { "could not stage bundle" }
     synchronized(ShipvoHostHandler.LOCK) {
+      if (!BootRules.mayStage(release, s.currentRelease, s.pendingRelease, s.blockedRelease)) return mapOf("status" to "none")
       s.pendingPath?.let { if (it != dest.path) File(it).delete() }
       s.pendingPath = dest.path; s.pendingRelease = release; s.trialBoots = 0; s.pendingSha = wantSha
       if (s.binaryVersion == null) s.binaryVersion = s.installedBinaryVersion

package/android/src/main/java/dev/shipvo/runtime/Store.kt

@@ -8,7 +8,7 @@ import java.io.File
 import kotlin.random.Random
 
 /** Persistent runtime state. All bundle decisions go through here so the host handler and module agree. */
-internal class Store(private val ctx: Context) {
+internal class Store(private val ctx: Context) : BootCounts {
   private val p: SharedPreferences = ctx.getSharedPreferences("shipvo.runtime", Context.MODE_PRIVATE)
   val dir: File get() = File(ctx.filesDir, "shipvo").apply { mkdirs() }
 
@@ -63,13 +63,15 @@ internal class Store(private val ctx: Context) {
   }
 
   var trialBoots: Int get() = p.getInt("trial_boots", 0); set(v) { p.edit().putInt("trial_boots", v).commit() }
-  var unhealthyBoots: Int get() = p.getInt("unhealthy_boots", 0); set(v) { p.edit().putInt("unhealthy_boots", v).commit() }
-  var firstUnhealthyAt: Long get() = p.getLong("first_unhealthy_at", 0); set(v) { p.edit().putLong("first_unhealthy_at", v).commit() }
+  override var unhealthyBoots: Int get() = p.getInt("unhealthy_boots", 0); set(v) { p.edit().putInt("unhealthy_boots", v).commit() }
+  override var firstUnhealthyAt: Long get() = p.getLong("first_unhealthy_at", 0); set(v) { p.edit().putLong("first_unhealthy_at", v).commit() }
 
   fun addEvent(e: String) {
     val list = p.getString("events", "")!!.split('\n').filter { it.isNotBlank() }.takeLast(49) + e
     p.edit().putString("events", list.joinToString("\n")).commit()
   }
+  /** Events queued and not yet consumed, oldest first. */
+  fun pendingEvents(): List<String> = p.getString("events", "")!!.split('\n').filter { it.isNotBlank() }
   fun consumeEvents(): List<String> {
     val list = p.getString("events", "")!!.split('\n').filter { it.isNotBlank() }
     p.edit().remove("events").commit(); return list
@@ -79,9 +81,18 @@ internal class Store(private val ctx: Context) {
     val ai = ctx.packageManager.getApplicationInfo(ctx.packageName, PackageManager.GET_META_DATA)
     ai.metaData?.getString(key)
   } catch (_: Exception) { null }
+  /** Like [meta], but also accepts numbers: a manifest can store a single version such as 96 as an integer. */
+  private fun metaAny(key: String): String? = try {
+    val ai = ctx.packageManager.getApplicationInfo(ctx.packageName, PackageManager.GET_META_DATA)
+    ai.metaData?.get(key)?.toString()
+  } catch (_: Exception) { null }
   val baseUrl: String get() = (meta("dev.shipvo.BASE_URL") ?: "").trimEnd('/')
   val publicKey: String get() = meta("dev.shipvo.PUBLIC_KEY") ?: ""
   val appId: String get() = meta("dev.shipvo.APP_ID") ?: ""
+  /** Hermes bytecode versions this shell runs, e.g. "96,98". Null when the shell does not declare them. */
+  val hermesBytecodeVersions: String? get() = metaAny("dev.shipvo.HERMES_BYTECODE_VERSIONS")?.takeIf { it.isNotBlank() }
+  /** Native modules in this shell, e.g. "react-native-mmkv@3.1.0,@scope/pkg@1.0.0". Null when not declared. */
+  val nativeModules: String? get() = metaAny("dev.shipvo.NATIVE_MODULES")?.takeIf { it.isNotBlank() }
   val shellMajor: Int get() = (meta("dev.shipvo.SHELL_MAJOR") ?: "1").toIntOrNull() ?: 1
 
   companion object {

package/android/src/test/java/dev/shipvo/runtime/HermesGuardTest.kt

@@ -0,0 +1,73 @@
+package dev.shipvo.runtime
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import java.io.ByteArrayInputStream
+import java.io.IOException
+import java.io.InputStream
+
+class HermesGuardTest {
+  private fun hbc(v: Int) = byteArrayOf(0xc6.toByte(), 0x1f, 0xbc.toByte(), 0x03, 0xc1.toByte(), 0x03, 0x19, 0x1f,
+    v.toByte(), (v shr 8).toByte(), (v shr 16).toByte(), (v shr 24).toByte())
+
+  @Test fun readsVersionFromHeader() {
+    assertEquals(96, HermesGuard.versionOf(hbc(96)))
+    assertEquals(300, HermesGuard.versionOf(hbc(300)))
+    assertNull(HermesGuard.versionOf("var a = 1; // js".toByteArray()))
+    assertNull(HermesGuard.versionOf(ByteArray(4)))
+  }
+
+  @Test fun mismatchIsRefusedWithTypedReason() {
+    assertEquals("hermes_bytecode_mismatch:7:release=98:shell=96", HermesGuard.mismatchEvent(7, 98, 96))
+  }
+
+  @Test fun matchIsAccepted() { assertNull(HermesGuard.mismatchEvent(7, 96, 96)) }
+
+  @Test fun missingFieldIsAccepted() {
+    assertNull(HermesGuard.mismatchEvent(7, null, 96))
+    assertNull(HermesGuard.mismatchEvent(7, 96, null))
+  }
+
+  /** Hands out at most `chunk` bytes per read, like a slow stream. */
+  private fun trickle(b: ByteArray, chunk: Int) = object : InputStream() {
+    var i = 0
+    override fun read(): Int = if (i < b.size) b[i++].toInt() and 0xff else -1
+    override fun read(buf: ByteArray, off: Int, len: Int): Int {
+      if (i >= b.size) return -1
+      val n = minOf(len, chunk, b.size - i); System.arraycopy(b, i, buf, off, n); i += n; return n
+    }
+  }
+
+  @Test fun headerIsReadAcrossShortReads() {
+    assertEquals(96, HermesGuard.readHeader { trickle(hbc(96) + ByteArray(50), 1) }?.let { HermesGuard.versionOf(it) })
+  }
+
+  @Test fun shortStreamAndMissingAssetAreUnknown() {
+    assertNull(HermesGuard.readHeader { trickle(hbc(96).copyOf(5), 3) }?.let { HermesGuard.versionOf(it) })
+    assertNull(HermesGuard.readHeader { ByteArrayInputStream(hbc(96).copyOf(9)) }?.let { HermesGuard.versionOf(it) })
+    assertNull(HermesGuard.readHeader { null })
+    assertNull(HermesGuard.readHeader { throw IOException("gone") })
+    assertNull(HermesGuard.decide(7, 98) { null })
+    assertNull(HermesGuard.decide(7, 98) { ByteArrayInputStream(hbc(96).copyOf(9)) })
+  }
+
+  @Test fun versionFieldMustBeAWholePositiveNumber() {
+    assertEquals(96, HermesGuard.releaseVersionOf(96))
+    assertEquals(96, HermesGuard.releaseVersionOf(96L))
+    assertNull(HermesGuard.releaseVersionOf(96.5))
+    assertNull(HermesGuard.releaseVersionOf("96"))
+    assertNull(HermesGuard.releaseVersionOf(0))
+    assertNull(HermesGuard.releaseVersionOf(-3))
+    assertNull(HermesGuard.releaseVersionOf(null))
+  }
+
+  @Test fun decideCoversMismatchMatchAndMissingField() {
+    val shell = { ByteArrayInputStream(hbc(96) + ByteArray(20)) }
+    assertEquals("hermes_bytecode_mismatch:7:release=98:shell=96", HermesGuard.decide(7, 98, shell))
+    assertNull(HermesGuard.decide(7, 96, shell))
+    assertNull(HermesGuard.decide(7, null, shell))
+    assertNull(HermesGuard.decide(7, 96.5, shell))
+    assertNull(HermesGuard.decide(7, 98) { ByteArrayInputStream("var a;".toByteArray()) })
+  }
+}

package/android/src/test/java/dev/shipvo/runtime/PointerQueryTest.kt

@@ -0,0 +1,42 @@
+package dev.shipvo.runtime
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class PointerQueryTest {
+  private fun url(hbc: String?, nm: String?) = PointerQuery.url("https://x.dev", "app", 1, "b2", hbc, nm)
+
+  @Test fun noQueryWhenNothingDeclared() {
+    assertEquals("https://x.dev/p/app/1/b2.json", url(null, null))
+    assertEquals("https://x.dev/p/app/1/b2.json", url("", " "))
+  }
+
+  @Test fun queryWhenDeclared() {
+    assertEquals("https://x.dev/p/app/1/b2.json?hbc=96,98", url("96,98", null))
+    assertEquals("https://x.dev/p/app/1/b2.json?hbc=96&nm=a%401.0.0", url("96", "a@1.0.0"))
+  }
+
+  @Test fun scopedNamesAreEncoded() {
+    assertEquals("https://x.dev/p/app/1/b2.json?nm=%40s%2Fp%401.2.3,b%402.0.0", url(null, "@s/p@1.2.3,b@2.0.0"))
+  }
+
+  @Test fun readsTypedReason() {
+    assertEquals("native_module_missing", PointerQuery.mismatchReason("{\"error\":\"native_module_missing\"}"))
+    assertEquals("hermes_bytecode_mismatch", PointerQuery.mismatchReason("{ \"error\": \"hermes_bytecode_mismatch\" }"))
+    assertNull(PointerQuery.mismatchReason("{\"error\":\"not_found\"}"))
+    assertNull(PointerQuery.mismatchReason(null))
+  }
+
+  @Test fun scopedNameWithoutVersionIsEncodedAsIs() {
+    // The control plane splits on the last "@", so "@s/p" has no version there.
+    assertEquals("https://x.dev/p/app/1/b2.json?nm=%40s%2Fp", url(null, "@s/p"))
+  }
+
+  @Test fun queuesRejectionOncePerReason() {
+    assertEquals("pointer_rejected:native_module_missing", PointerQuery.rejectionEvent(emptyList(), "native_module_missing"))
+    val queued = listOf("crash_loop_revert", "pointer_rejected:native_module_missing")
+    assertNull(PointerQuery.rejectionEvent(queued, "native_module_missing"))
+    assertEquals("pointer_rejected:hermes_bytecode_mismatch", PointerQuery.rejectionEvent(queued, "hermes_bytecode_mismatch"))
+  }
+}

package/android/src/test/java/dev/shipvo/runtime/ResumableDownloadTest.kt

@@ -0,0 +1,90 @@
+package dev.shipvo.runtime
+
+import java.io.File
+import java.net.InetAddress
+import java.net.ServerSocket
+import kotlin.concurrent.thread
+import org.junit.After
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Before
+import org.junit.Test
+
+class ResumableDownloadTest {
+  private val data = ByteArray(300_000) { (it * 31 % 251).toByte() }
+  private val ranges = mutableListOf<String?>()
+  private var honourRange = true
+  // A minimal HTTP/1.1 server on a plain socket: com.sun.net.httpserver is not on the Android unit-test classpath.
+  private lateinit var server: ServerSocket
+  private lateinit var dir: File
+  private val url get() = "http://127.0.0.1:${server.localPort}/b"
+
+  @Before fun start() {
+    dir = File.createTempFile("shipvo", "dl").apply { delete(); mkdirs() }
+    server = ServerSocket(0, 50, InetAddress.getByName("127.0.0.1"))
+    thread(isDaemon = true) {
+      while (!server.isClosed) {
+        val s = try { server.accept() } catch (e: Exception) { break }
+        s.use { sock ->
+          val reader = sock.getInputStream().bufferedReader(Charsets.ISO_8859_1)
+          reader.readLine() ?: return@use
+          var range: String? = null
+          while (true) {
+            val line = reader.readLine() ?: break
+            if (line.isEmpty()) break
+            val i = line.indexOf(':')
+            if (i > 0 && line.substring(0, i).trim().equals("Range", ignoreCase = true)) range = line.substring(i + 1).trim()
+          }
+          synchronized(ranges) { ranges.add(range) }
+          val start = if (honourRange && range != null) range.removePrefix("bytes=").removeSuffix("-").toInt() else 0
+          val body = data.copyOfRange(start, data.size)
+          val head = buildString {
+            append(if (start > 0) "HTTP/1.1 206 Partial Content\r\n" else "HTTP/1.1 200 OK\r\n")
+            if (start > 0) append("Content-Range: bytes $start-${data.size - 1}/${data.size}\r\n")
+            append("Content-Length: ${body.size}\r\nContent-Type: application/octet-stream\r\nConnection: close\r\n\r\n")
+          }
+          val out = sock.getOutputStream()
+          out.write(head.toByteArray(Charsets.ISO_8859_1)); out.write(body); out.flush()
+        }
+      }
+    }
+  }
+  @After fun stop() { server.close(); dir.deleteRecursively() }
+
+  @Test fun secondRequestStartsAtThePartialSize() {
+    val part = ResumableDownload.partialFile(dir, "abc")
+    part.writeBytes(data.copyOfRange(0, 100_000))
+    val from = ResumableDownload.fetch(url, part, data.size.toLong())
+    assertEquals(100_000L, from)
+    assertEquals(listOf<String?>("bytes=100000-"), ranges)
+    assertArrayEquals(data, part.readBytes())
+  }
+
+  @Test fun a200AnswerToARangeRequestRestartsCleanly() {
+    honourRange = false
+    val part = ResumableDownload.partialFile(dir, "abc")
+    part.writeBytes(data.copyOfRange(0, 100_000))
+    ResumableDownload.fetch(url, part, data.size.toLong())
+    assertEquals(listOf<String?>("bytes=100000-"), ranges)
+    assertArrayEquals(data, part.readBytes())
+  }
+
+  @Test fun freshDownloadSendsNoRange() {
+    val part = ResumableDownload.partialFile(dir, "abc")
+    assertEquals(0L, ResumableDownload.fetch(url, part, data.size.toLong()))
+    assertEquals(listOf<String?>(null), ranges)
+    assertArrayEquals(data, part.readBytes())
+  }
+
+  @Test fun anOversizedPartialIsDiscarded() {
+    val part = ResumableDownload.partialFile(dir, "abc")
+    part.writeBytes(ByteArray(data.size + 5))
+    assertEquals(0L, ResumableDownload.fetch(url, part, data.size.toLong()))
+    assertArrayEquals(data, part.readBytes())
+  }
+
+  @Test fun partialFilesAreNamedByReleaseHash() {
+    assertFalse(ResumableDownload.partialFile(dir, "a") == ResumableDownload.partialFile(dir, "b"))
+  }
+}

package/android/src/test/java/dev/shipvo/runtime/StabilityTest.kt

@@ -0,0 +1,76 @@
+package dev.shipvo.runtime
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+
+class StabilityTest {
+  private class Counts : BootCounts { override var unhealthyBoots = 0; override var firstUnhealthyAt = 0L }
+  private val max = ShipvoHostHandler.MAX_BOOTS
+  private val win = ShipvoHostHandler.WINDOW_MS
+
+  @Before fun reset() { BootRules.healthyLoad = 0; BootRules.crashedLoad = 0 }
+
+  /** One launch of a promoted release: count it, then report healthy. Returns true if the launch reverts. */
+  private fun launch(c: Counts, now: Long, load: Int): Boolean {
+    if (BootRules.countBoot(c, now, max, win)) return true
+    BootRules.onHealthy(c, load, now, promoted = false); return false
+  }
+
+  @Test fun releaseThatDiesAfterMarkHealthyIsReverted() {
+    val c = Counts()
+    BootRules.onHealthy(c, 1, 0, promoted = true)  // boot 1: promoted, counted as 1
+    assertFalse(launch(c, 5_000, 2))           // boot 2
+    assertFalse(launch(c, 10_000, 3))          // boot 3
+    assertTrue("fourth launch reverts", launch(c, 15_000, 4))
+  }
+
+  @Test fun releaseThatReachesStabilityIsKept() {
+    val c = Counts()
+    BootRules.onHealthy(c, 1, 0, promoted = true)
+    for (i in 2..20) {
+      assertFalse(launch(c, i * 5_000L, i))
+      assertTrue(BootRules.markStableIfHealthy(c, i))
+    }
+  }
+
+  @Test fun backgroundBeforeMarkHealthyDoesNotClearTheCount() {
+    val c = Counts()
+    BootRules.onHealthy(c, 1, 0, promoted = true)  // load 1 reported healthy, then the app reloaded
+    BootRules.countBoot(c, 1_000, max, win)    // load 2 starts
+    assertFalse(BootRules.markStableIfHealthy(c, 2))
+    assertEquals(2, c.unhealthyBoots)
+  }
+
+  @Test fun crashAfterMarkHealthyIsNotStableWhenHostIsDestroyed() {
+    val c = Counts()
+    BootRules.onHealthy(c, 1, 0, promoted = true)
+    BootRules.noteCrash(1)                      // JS error, then the host pause calls markStableIfHealthy
+    assertFalse(BootRules.markStableIfHealthy(c, 1))
+    assertEquals(1, c.unhealthyBoots)
+  }
+
+  @Test fun crashInOneLoadDoesNotBlockTheNextLoad() {
+    val c = Counts()
+    BootRules.onHealthy(c, 1, 0, promoted = true)
+    BootRules.noteCrash(1)
+    BootRules.onHealthy(c, 2, 1_000, promoted = false)
+    assertTrue(BootRules.markStableIfHealthy(c, 2))
+  }
+
+  @Test fun countsExpireOutsideTheWindow() {
+    val c = Counts()
+    BootRules.onHealthy(c, 1, 0, promoted = true)
+    assertFalse(BootRules.countBoot(c, win + 1, max, win))
+    assertEquals(1, c.unhealthyBoots)
+  }
+
+  @Test fun aReleaseAlreadyPendingCurrentOrBlockedIsNotStagedAgain() {
+    assertTrue(BootRules.mayStage(5, 3, 4, 2))
+    assertFalse(BootRules.mayStage(5, 3, 5, 0))  // pending: staging again would reset trialBoots
+    assertFalse(BootRules.mayStage(5, 5, 0, 0))
+    assertFalse(BootRules.mayStage(5, 3, 0, 5))
+  }
+}

package/app.plugin.js

@@ -3,15 +3,51 @@
 // change which key it is verified against.
 const { withAndroidManifest, withInfoPlist, AndroidConfig } = require("expo/config-plugins");
 
+// Returns the comma list for the Hermes bytecode versions, or undefined when the prop is omitted.
+function formatBytecodeVersions(value) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new Error("@shipvo/runtime: hermesBytecodeVersions must be an array of integers");
+  for (const v of value) {
+    if (!Number.isInteger(v) || v < 0) {
+      throw new Error(`@shipvo/runtime: hermesBytecodeVersions must be non-negative integers, got ${JSON.stringify(v)}`);
+    }
+  }
+  return value.join(",");
+}
+
+// Returns "name@version,..." for the native modules, or undefined when the prop is omitted.
+function formatNativeModules(value) {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("@shipvo/runtime: nativeModules must be an object of package name to version");
+  }
+  return Object.entries(value)
+    .map(([name, version]) => {
+      if (!name.trim()) throw new Error("@shipvo/runtime: nativeModules has an empty package name");
+      if (typeof version !== "string" || !version.trim()) {
+        throw new Error(`@shipvo/runtime: nativeModules version for "${name}" must be a non-empty string`);
+      }
+      if (/[,\s]/.test(version) || /[,\s]/.test(name)) {
+        throw new Error(`@shipvo/runtime: nativeModules entry "${name}": "${version}" has a comma or space where it cannot`);
+      }
+      return `${name}@${version}`;
+    })
+    .join(",");
+}
+
 module.exports = function withShipvo(config, props) {
   const { baseUrl, publicKey, appId, shellMajor = 1 } = props || {};
   if (!baseUrl || !publicKey || !appId) throw new Error("@shipvo/runtime: baseUrl, publicKey and appId are required");
+  const hbc = formatBytecodeVersions(props.hermesBytecodeVersions);
+  const nm = formatNativeModules(props.nativeModules);
   config.extra = { ...(config.extra ?? {}), shipvo: { baseUrl, appId, shellMajor } };
   config = withInfoPlist(config, (cfg) => {
     cfg.modResults.ShipvoBaseURL = baseUrl;
     cfg.modResults.ShipvoPublicKey = publicKey;
     cfg.modResults.ShipvoAppId = appId;
     cfg.modResults.ShipvoShellMajor = String(shellMajor);
+    if (hbc !== undefined) cfg.modResults.ShipvoHermesBytecodeVersions = hbc;
+    if (nm !== undefined) cfg.modResults.ShipvoNativeModules = nm;
     return cfg;
   });
   return withAndroidManifest(config, (cfg) => {
@@ -21,6 +57,8 @@ module.exports = function withShipvo(config, props) {
     set("dev.shipvo.PUBLIC_KEY", publicKey);
     set("dev.shipvo.APP_ID", appId);
     set("dev.shipvo.SHELL_MAJOR", shellMajor);
+    if (hbc !== undefined) set("dev.shipvo.HERMES_BYTECODE_VERSIONS", hbc);
+    if (nm !== undefined) set("dev.shipvo.NATIVE_MODULES", nm);
     return cfg;
   });
 };

package/ios/BundleSelector.swift

@@ -4,6 +4,8 @@ import Foundation
 enum ShipvoBundleSelector {
   static let maxBoots = 3
   static let windowSeconds: TimeInterval = 60
+  /// A release is stable once its process has stayed in the foreground this long after `markHealthy`. Android uses the same value.
+  static let stabilitySeconds: TimeInterval = 30
 
   /// Idempotent per load: React Native asks for the URL more than once, and only the first ask counts as a boot.
   static func select(_ s: Store) -> URL? {
@@ -25,12 +27,30 @@ enum ShipvoBundleSelector {
       s.currentRelease = s.pendingRelease; s.currentPath = s.pendingPath; s.currentSha = s.pendingSha
       s.pendingRelease = 0; s.pendingPath = nil; s.trialBoots = 0
       s.addEvent("applied:\(s.currentRelease)")
+      // The promoting boot was a trial boot and was not counted. Count it now, until the stability window ends.
+      s.unhealthyBoots = 1; s.firstUnhealthyAt = Store.now()
       promoted = true
     }
-    s.unhealthyBoots = 0; s.firstUnhealthyAt = 0
+    // The boot counter is not cleared here: `markStableIfHealthy` does that after the stability window.
     return promoted
   }
 
+  /// The load that last reported healthy. `markStableIfHealthy` only acts for that load.
+  private static var healthyLoad = 0
+
+  /// Called from `markHealthy`: the current load reached its first screen.
+  static func noteHealthy() { Store.lock.lock(); healthyLoad = Store.loadsInProcess; Store.lock.unlock() }
+
+  /// Clears the count only if the current load reported healthy. After a reload, the new load has not, so a crash
+  /// before its `markHealthy` still counts. Returns whether the count was cleared.
+  @discardableResult
+  static func markStableIfHealthy(_ s: Store) -> Bool {
+    Store.lock.lock(); defer { Store.lock.unlock() }
+    guard healthyLoad != 0, healthyLoad == Store.loadsInProcess else { return false }
+    s.unhealthyBoots = 0; s.firstUnhealthyAt = 0
+    return true
+  }
+
   /// Called before a reload so the next ask is a fresh load.
   static func invalidate() { Store.lock.lock(); Store.selection = (nil, false); Store.lock.unlock() }
 

package/ios/HermesGuard.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+/// Refuses a release built for a different Hermes bytecode version than the shell runs. Runs in addition to the
+/// signature and hash checks, never instead of them.
+enum HermesGuard {
+  static let reason = "hermes_bytecode_mismatch"
+  // Same magic and layout as the CLI code that writes `hermes_bytecode_version` on publish.
+  private static let magic: [UInt8] = [0xc6, 0x1f, 0xbc, 0x03, 0xc1, 0x03, 0x19, 0x1f]
+
+  /// The bytecode version in a bundle header (8-byte magic, then a 32-bit little-endian version), or nil for plain JS.
+  static func version(of head: Data) -> Int? {
+    let b = [UInt8](head.prefix(12))
+    guard b.count >= 12, Array(b[0..<8]) == magic else { return nil }
+    let v = (0..<4).reduce(0) { $0 | Int(b[8 + $1]) << (8 * $1) }
+    return v > 0 ? v : nil
+  }
+
+  /// The release's version field, or nil ("unknown") unless it is a whole number from 1 to Int32.max.
+  /// Same rule as `releaseVersionOf` on Android: rejects Bool, fractions, strings, zero and negatives.
+  static func releaseVersionOf(_ value: Any?) -> Int? {
+    guard let n = value as? NSNumber, CFGetTypeID(n) != CFBooleanGetTypeID() else { return nil }
+    let d = n.doubleValue
+    guard d == d.rounded(), d > 0, d <= Double(Int32.max) else { return nil }
+    return Int(d)
+  }
+
+  /// The event to log when the release must be refused, or nil when it may be staged.
+  /// A missing field on either side means "unknown", so the release is applied as before.
+  static func mismatchEvent(release: Int, releaseVersion: Int?, shellVersion: Int?) -> String? {
+    guard let r = releaseVersion, let s = shellVersion, r != s else { return nil }
+    return "\(reason):\(release):release=\(r):shell=\(s)"
+  }
+
+  /// The version of the bundle embedded in the app, read from its header.
+  /// The embedded bundle header is the source of truth here, not `ShipvoHermesBytecodeVersions` in Info.plist
+  /// (that list is only sent to the control plane to filter releases).
+  /// Read by file path with `FileHandle`, not through `Bundle(path:)` on a plain folder.
+  static func shellVersion(_ bundle: Bundle) -> Int? {
+    guard let url = bundle.url(forResource: "main", withExtension: "jsbundle"), let h = try? FileHandle(forReadingFrom: url) else { return nil }
+    defer { try? h.close() }
+    return version(of: (try? h.read(upToCount: 12)) ?? Data())
+  }
+}

package/ios/ShipvoRuntimeModule.swift

@@ -35,10 +35,14 @@ public final class ShipvoRuntimeModule: Module {
       let coldStart = max(0, (Date().timeIntervalSince1970 - Self.processStart()) * 1000)
       let sinceLoad = Store.bundleSelectedAt > 0 ? (now - Store.bundleSelectedAt) * 1000 : -1
       let promoted = ShipvoBundleSelector.promoteIfRunning(s)
+      ShipvoBundleSelector.noteHealthy()
+      Self.scheduleStable()
       return ["release": Store.runningRelease, "coldStartMs": Int(coldStart), "sinceLoadMs": Int(sinceLoad), "promoted": promoted,
               "kind": Store.loadsInProcess <= 1 ? "cold" : "reload"]
     }
 
+    OnAppEntersBackground { Self.stableNow() }
+
     Function("consumeEvents") { () -> [String] in Store().consumeEvents() }
 
     Function("rollback") { () in
@@ -56,7 +60,30 @@ public final class ShipvoRuntimeModule: Module {
     Function("reload") { () in Self.reloadHost() }
   }
 
+  private static var stableTimer: DispatchWorkItem?
+
+  /// Clears the unhealthy-boot count once the app has stayed up for the stability window.
+  /// The timer is dropped after it fires and on reload, and `markStableIfHealthy` checks the load number.
+  static func scheduleStable() {
+    Store.lock.lock(); defer { Store.lock.unlock() }
+    stableTimer?.cancel()
+    let item = DispatchWorkItem {
+      ShipvoBundleSelector.markStableIfHealthy(Store())
+      Store.lock.lock(); stableTimer = nil; Store.lock.unlock()
+    }
+    stableTimer = item
+    DispatchQueue.main.asyncAfter(deadline: .now() + ShipvoBundleSelector.stabilitySeconds, execute: item)
+  }
+
+  /// Going to background cleanly counts as stable, but only if this load reported healthy.
+  static func stableNow() {
+    if ShipvoBundleSelector.markStableIfHealthy(Store()) {
+      Store.lock.lock(); stableTimer?.cancel(); stableTimer = nil; Store.lock.unlock()
+    }
+  }
+
   static func reloadHost() {
+    Store.lock.lock(); stableTimer?.cancel(); stableTimer = nil; Store.lock.unlock()
     ShipvoBundleSelector.invalidate()
     DispatchQueue.main.async { RCTTriggerReloadCommandListeners("shipvo-update") }
   }

package/ios/Store.swift

@@ -6,6 +6,7 @@ final class Store {
   /// Replaces what the app's Info.plist and file system would say. Tests use it; the app never does.
   struct Overrides {
     var suite: String, dir: URL, baseUrl: String, publicKey: String, appId: String, shellMajor: Int, shellVersion: String, binaryVersion: String
+    var hermesBytecodeVersions: [Int] = [], nativeModules: [String: String] = [:]
   }
 
   private let d: UserDefaults
@@ -44,6 +45,19 @@ final class Store {
   var blockedRelease: Int { get { d.integer(forKey: "blocked_release") } set { d.set(newValue, forKey: "blocked_release") } }
   /// Shell binary the stored OTA bundles were downloaded under.
   var binaryVersion: String? { get { d.string(forKey: "binary_version") } set { d.set(newValue, forKey: "binary_version") } }
+  var appBundle: Bundle { bundle }
+  /// The `main.jsbundle` inside the app: the first release, and the patch base before any download.
+  func embeddedBundle() -> Data? {
+    guard let url = bundle.url(forResource: "main", withExtension: "jsbundle") else { return nil }
+    return try? Data(contentsOf: url)
+  }
+  /// Its sha256, cached per installed binary so the file is hashed once.
+  func embeddedSha() -> String? {
+    let key = "embedded_sha:" + installedBinaryVersion
+    if let v = d.string(forKey: key) { return v }
+    guard let data = embeddedBundle() else { return nil }
+    let sha = Verify.sha256Hex(data); d.set(sha, forKey: key); return sha
+  }
   func block(_ release: Int) { if release > blockedRelease { blockedRelease = release } }
 
   var trialBoots: Int { get { d.integer(forKey: "trial_boots") } set { d.set(newValue, forKey: "trial_boots") } }
@@ -85,6 +99,18 @@ final class Store {
   var baseUrl: String { var s = o?.baseUrl ?? plist("ShipvoBaseURL") ?? ""; while s.hasSuffix("/") { s.removeLast() }; return s }
   var publicKey: String { o?.publicKey ?? plist("ShipvoPublicKey") ?? "" }
   var appId: String { o?.appId ?? plist("ShipvoAppId") ?? "" }
+  /// Hermes bytecode versions this shell runs (Info.plist `ShipvoHermesBytecodeVersions`: an array of numbers or a "96,98" string).
+  var hermesBytecodeVersions: [Int] {
+    if let o { return o.hermesBytecodeVersions }
+    let v = bundle.object(forInfoDictionaryKey: "ShipvoHermesBytecodeVersions")
+    let list: [Any] = (v as? [Any]) ?? ((v as? String)?.split(separator: ",").map { String($0).trimmingCharacters(in: .whitespaces) } ?? [])
+    return list.compactMap { ($0 as? NSNumber)?.intValue ?? Int("\($0)") }.filter { $0 > 0 }
+  }
+  /// Native modules in this shell (Info.plist `ShipvoNativeModules`: a name-to-version dictionary).
+  var nativeModules: [String: String] {
+    if let o { return o.nativeModules }
+    return (bundle.object(forInfoDictionaryKey: "ShipvoNativeModules") as? [String: Any])?.compactMapValues { $0 as? String } ?? [:]
+  }
   var shellMajor: Int { if let o { return o.shellMajor }; return Int(plist("ShipvoShellMajor") ?? "1") ?? 1 }
 
   // MARK: per-process state

package/ios/Updater.swift

@@ -3,7 +3,7 @@ import Foundation
 struct UpdateError: Error { let message: String; init(_ m: String) { message = m } }
 
 /// Fetch, verify and stage the newest signed release for this device's band. Mirrors Android `check()`.
-/// Uses a bsdiff patch when the pointer lists one from the bundle this device runs; any patch problem falls back to the full bundle.
+/// Uses a bsdiff patch when the pointer lists one from the bundle this device runs (or the app's embedded bundle); any patch problem falls back to the full bundle.
 enum Updater {
   private static func require(_ cond: Bool, _ msg: @autoclosure () -> String) throws { if !cond { throw UpdateError(msg()) } }
 
@@ -16,12 +16,32 @@ enum Updater {
 
   private static func resolve(_ s: Store, _ url: String) -> String { url.hasPrefix("http") ? url : "\(s.baseUrl)/\(url.drop(while: { $0 == "/" }))" }
 
+  /// Pointer URL. `?hbc=` and `?nm=` are added only when the shell declares them. Scoped names are percent-encoded.
+  static func pointerURL(_ s: Store) -> String {
+    var url = "\(s.baseUrl)/p/\(s.appId)/\(s.shellMajor)/ios/\(s.band).json"
+    func enc(_ x: String) -> String { x.addingPercentEncoding(withAllowedCharacters: CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~")) ?? x }
+    var q: [String] = []
+    let hbc = s.hermesBytecodeVersions
+    if !hbc.isEmpty { q.append("hbc=" + hbc.map(String.init).joined(separator: ",")) }
+    let nm = s.nativeModules
+    if !nm.isEmpty { q.append("nm=" + nm.keys.sorted().map { enc($0) + "%40" + enc(nm[$0]!) }.joined(separator: ",")) }
+    if !q.isEmpty { url += "?" + q.joined(separator: "&") }
+    return url
+  }
+
   static func check(_ s: Store) async throws -> [String: Any] {
     try require(!s.baseUrl.isEmpty && !s.publicKey.isEmpty && !s.appId.isEmpty, "runtime not configured")
     let known = max(s.currentRelease, s.pendingRelease, s.blockedRelease)
-    let (data, resp) = try await URLSession.shared.data(for: request("\(s.baseUrl)/p/\(s.appId)/\(s.shellMajor)/ios/\(s.band).json", etag: known > 0 ? "\"\(known)\"" : nil))
+    let (data, resp) = try await URLSession.shared.data(for: request(pointerURL(s), etag: known > 0 ? "\"\(known)\"" : nil))
     let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
-    if code == 304 || code == 404 { return ["status": "none"] }
+    if code == 404 {
+      // The control plane says this shell cannot run the release. Keep the current one; stage nothing.
+      let text = String(data: data, encoding: .utf8) ?? ""
+      let reason = ((try? JSONSerialization.jsonObject(with: data)) as? [String: Any])?["error"] as? String ?? text.trimmingCharacters(in: .whitespacesAndNewlines)
+      if ["hermes_bytecode_mismatch", "native_module_missing", "native_module_version"].contains(reason) { return ["status": "none", "reason": reason] }
+      return ["status": "none"]
+    }
+    if code == 304 { return ["status": "none"] }
     try require(code == 200, "pointer HTTP \(code)")
     guard let envelope = try JSONSerialization.jsonObject(with: data) as? [String: Any],
           let bodyStr = envelope["body"] as? String, let sig = envelope["signature"] as? String else { throw UpdateError("pointer is not an envelope") }
@@ -35,11 +55,18 @@ enum Updater {
     if release <= known { return ["status": "none"] }
     try require(!Verify.semverLess(s.shellVersion, body["min_shell_version"] as? String ?? "0.0.0"), "shell too old for release \(release)")
     let verifyPointerMs = (Store.now() - t0) * 1000
+    // Beside the signature checks, not inside them: refuse a bundle built for another Hermes bytecode version.
+    if let ev = HermesGuard.mismatchEvent(release: release, releaseVersion: HermesGuard.releaseVersionOf(body["hermes_bytecode_version"]), shellVersion: HermesGuard.shellVersion(s.appBundle)) {
+      s.addEvent(ev); s.block(release)
+      return ["status": "none", "reason": HermesGuard.reason]
+    }
 
     guard let core = body["core"] as? [String: Any], let wantSha = core["sha256"] as? String,
           let wantSize = (core["size"] as? NSNumber)?.intValue, let url = core["url"] as? String else { throw UpdateError("pointer core incomplete") }
     let tmp = s.dir.appendingPathComponent("dl-\(release).tmp")
     try? FileManager.default.removeItem(at: tmp)
+    let part = partialURL(s, sha: wantSha)
+    dropOtherPartials(s, keep: part)
 
     var via = "full", downloadedBytes = 0
     let d0 = Store.now()
@@ -48,21 +75,20 @@ enum Updater {
       ready = true; via = "patch"; downloadedBytes = patch
     }
     var downloadMs = (Store.now() - d0) * 1000
+    var resumedFrom = 0
     if !ready {
       let f0 = Store.now()
-      let (fileURL, dresp) = try await URLSession.shared.download(for: request(resolve(s, url), etag: nil))
-      let dcode = (dresp as? HTTPURLResponse)?.statusCode ?? 0
-      try require(dcode == 200, "bundle HTTP \(dcode)")
+      resumedFrom = try await downloadFull(s, url: resolve(s, url), part: part, wantSize: wantSize)
       try? FileManager.default.removeItem(at: tmp)
-      try FileManager.default.moveItem(at: fileURL, to: tmp)
+      try FileManager.default.moveItem(at: part, to: tmp)
       downloadMs += (Store.now() - f0) * 1000
     }
 
     let v0 = Store.now()
     let size = (try? FileManager.default.attributesOfItem(atPath: tmp.path)[.size] as? Int) ?? -1
-    if via == "full" { downloadedBytes = size }
+    if via == "full" { downloadedBytes = max(0, size - resumedFrom) }
     let ok = try (size == wantSize && Verify.sha256Hex(file: tmp) == wantSha)
-    if !ok { try? FileManager.default.removeItem(at: tmp); s.addEvent("verify_failed:\(release)"); throw UpdateError("bundle hash/size mismatch") }
+    if !ok { try? FileManager.default.removeItem(at: tmp); try? FileManager.default.removeItem(at: part); s.addEvent("verify_failed:\(release)"); throw UpdateError("bundle hash/size mismatch") }
     let verifyMs = (Store.now() - v0) * 1000 + verifyPointerMs
 
     let dest = s.dir.appendingPathComponent("r\(release).hbc")
@@ -73,19 +99,63 @@ enum Updater {
             "downloadMs": Int(downloadMs), "verifyMs": Int(verifyMs), "issuedAt": body["issued_at"] as? String ?? ""]
   }
 
+  /// Partial full-bundle download, named by the release sha256 so a different release never reuses it.
+  static func partialURL(_ s: Store, sha: String) -> URL { s.dir.appendingPathComponent("dl-\(sha).part") }
+
+  /// The release changed: partial files for other hashes can never complete.
+  private static func dropOtherPartials(_ s: Store, keep: URL) {
+    let files = (try? FileManager.default.contentsOfDirectory(at: s.dir, includingPropertiesForKeys: nil)) ?? []
+    for f in files where f.pathExtension == "part" && f.lastPathComponent != keep.lastPathComponent { try? FileManager.default.removeItem(at: f) }
+  }
+
+  /// Download the full bundle into `part`, resuming with `Range: bytes=<n>-` when a partial file exists.
+  /// A 200 answer means the server ignored the range: start over. Returns how many bytes were already on disk.
+  /// If the connection drops, the partial file stays for the next attempt. The caller still checks the signed hash.
+  private static func downloadFull(_ s: Store, url: String, part: URL, wantSize: Int) async throws -> Int {
+    let fm = FileManager.default
+    func have() -> Int { (try? fm.attributesOfItem(atPath: part.path)[.size] as? Int) ?? 0 }
+    var offset = have()
+    if offset > wantSize { try? fm.removeItem(at: part); offset = 0 }
+    if offset == wantSize { return offset }
+    for attempt in 0..<2 {
+      var req = try request(url, etag: nil)
+      if offset > 0 { req.setValue("bytes=\(offset)-", forHTTPHeaderField: "Range") }
+      let (stream, resp) = try await URLSession.shared.bytes(for: req)
+      let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
+      if code == 416 && offset > 0 && attempt == 0 { try? fm.removeItem(at: part); offset = 0; continue }
+      try require(code == 200 || (code == 206 && offset > 0), "bundle HTTP \(code)")
+      if code == 200 { try? fm.removeItem(at: part); offset = 0 }
+      if !fm.fileExists(atPath: part.path) { try require(fm.createFile(atPath: part.path, contents: nil), "cannot create partial file") }
+      let h = try FileHandle(forWritingTo: part)
+      defer { try? h.close() }
+      try h.seekToEnd()
+      var buf = Data(); buf.reserveCapacity(64 * 1024)
+      for try await b in stream {
+        buf.append(b)
+        if buf.count >= 64 * 1024 { try h.write(contentsOf: buf); buf.removeAll(keepingCapacity: true) }
+      }
+      if !buf.isEmpty { try h.write(contentsOf: buf) }
+      return offset
+    }
+    throw UpdateError("bundle download failed")
+  }
+
   /// Try the patch from the bundle this device runs. Writes the rebuilt bundle to `tmp` and returns the patch size,
   /// or throws (nothing left behind) so the caller can fetch the full bundle. The caller still checks the signed hash.
   private static func patched(_ s: Store, core: [String: Any], wantSha: String, wantSize: Int, to tmp: URL) async throws -> Int {
-    guard let base = s.currentPath, s.currentSha != nil, FileManager.default.fileExists(atPath: base),
+    // Base: the bundle this device runs, or the embedded main.jsbundle before the first update.
+    let baseFile = s.currentPath.flatMap { FileManager.default.fileExists(atPath: $0) ? $0 : nil }
+    let baseSha: String? = baseFile != nil ? s.currentSha : s.embeddedSha()
+    guard let baseSha,
           let list = core["patches"] as? [[String: Any]],
-          let entry = list.first(where: { $0["from_sha256"] as? String == s.currentSha }),
+          let entry = list.first(where: { $0["from_sha256"] as? String == baseSha }),
           let purl = entry["url"] as? String, let psha = entry["sha256"] as? String, let psize = (entry["size"] as? NSNumber)?.intValue,
           psize > 0, psize < wantSize else { throw UpdateError("no usable patch") }
     do {
       let (data, resp) = try await URLSession.shared.data(for: request(resolve(s, purl), etag: nil))
       try require((resp as? HTTPURLResponse)?.statusCode == 200 && data.count == psize && Verify.sha256Hex(data) == psha, "patch download invalid")
-      let old = try Data(contentsOf: URL(fileURLWithPath: base))
-      try require(Verify.sha256Hex(old) == s.currentSha, "current bundle changed on disk")
+      guard let old = try baseFile.map({ try Data(contentsOf: URL(fileURLWithPath: $0)) }) ?? s.embeddedBundle() else { throw UpdateError("no base bundle") }
+      try require(Verify.sha256Hex(old) == baseSha, "base bundle changed on disk")
       let new = try Patch.apply(old: old, patch: data)
       try require(new.count == wantSize && Verify.sha256Hex(new) == wantSha, "patched bundle does not match")
       try new.write(to: tmp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/runtime",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "Apache-2.0",
   "description": "The Shipvo native runtime: a tiny Expo module that verifies (Ed25519 + SHA-256), downloads (bsdiff patches), stages and applies signed over-the-air releases, with crash-loop rollback. Plus the config plugin that pins the trust root in the native shell.",
   "main": "src/index.ts",
@@ -56,5 +56,11 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "devDependencies": {
+    "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/index.ts

@@ -11,6 +11,8 @@ export type CheckResult = {
   /** Shell 1.0.2+ (Android): "patch" when a bsdiff patch was applied, "full" otherwise. iOS always downloads "full". */
   via?: "patch" | "full"; bundleBytes?: number; patchError?: string | null;
   issuedAt?: string; error?: string;
+  /** Android only for now: why a "none" result happened when the control plane rejected the shell's bytecode or native modules. */
+  reason?: "hermes_bytecode_mismatch" | "native_module_missing" | "native_module_version";
 };
 export type HealthyResult = {
   release: number; coldStartMs: number; sinceLoadMs: number; promoted: boolean;
@@ -39,4 +41,31 @@ const fallback: Native = {
   markHealthy: () => ({ release: 0, coldStartMs: Date.now() - t0, sinceLoadMs: 0, promoted: false, kind: "cold" }),
   consumeEvents: () => [], rollback: () => {}, reload: () => {},
 };
-export const Runtime: Native = requireOptionalNativeModule<Native>("ShipvoRuntime") ?? fallback;
+const native = requireOptionalNativeModule<Native & { noteCrash?(): void }>("ShipvoRuntime");
+
+// After markHealthy, tell the native side about an uncaught JS error before React destroys the host. Destroying the host
+// pauses the activity, and that pause must not count as "stable". Needs a shell with `noteCrash`; older shells skip it.
+let crashHookInstalled = false;
+function installCrashHook() {
+  if (crashHookInstalled || typeof native?.noteCrash !== "function") return;
+  const eu = (globalThis as any).ErrorUtils;
+  if (!eu?.setGlobalHandler || !eu.getGlobalHandler) return;
+  crashHookInstalled = true;
+  const prev = eu.getGlobalHandler();
+  eu.setGlobalHandler((e: unknown, isFatal?: boolean) => {
+    if (isFatal) { try { native.noteCrash!(); } catch {} }
+    prev?.(e, isFatal);
+  });
+}
+
+// Every `Native` method must be listed here, or it is silently dropped from `Runtime`.
+export const Runtime: Native = native
+  ? {
+      getState: () => native.getState(),
+      checkForUpdate: (apply) => native.checkForUpdate(apply),
+      markHealthy: () => { const r = native.markHealthy(); installCrashHook(); return r; },
+      consumeEvents: () => native.consumeEvents(),
+      rollback: () => native.rollback(),
+      reload: () => native.reload(),
+    }
+  : fallback;