@shipvo/runtime 0.1.3 → 0.1.5

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,45 @@
+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"))
+    assertEquals("https://x.dev/p/app/1/b2.json?hbc=96&hbe=250829098.0.10&nm=a%401.0.0", PointerQuery.url("https://x.dev", "app", 1, "b2", "96", "a@1.0.0", "250829098.0.10"))
+    assertEquals("https://x.dev/p/app/1/b2.json?hbe=1.2.3", PointerQuery.url("https://x.dev", "app", 1, "b2", null, null, " 1.2.3 "))
+    assertEquals("https://x.dev/p/app/1/b2.json", PointerQuery.url("https://x.dev", "app", 1, "b2", null, null, " "))
+  }
+
+  @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/RotationTest.kt

@@ -0,0 +1,141 @@
+package dev.shipvo.runtime
+
+import net.i2p.crypto.eddsa.EdDSAEngine
+import net.i2p.crypto.eddsa.EdDSAPrivateKey
+import net.i2p.crypto.eddsa.EdDSAPublicKey
+import net.i2p.crypto.eddsa.spec.EdDSANamedCurveTable
+import net.i2p.crypto.eddsa.spec.EdDSAPrivateKeySpec
+import net.i2p.crypto.eddsa.spec.EdDSAPublicKeySpec
+import org.json.JSONArray
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.security.MessageDigest
+import java.text.SimpleDateFormat
+import java.util.Base64
+import java.util.Locale
+import java.util.TimeZone
+
+/** Runs the shared vectors (packages/runtime/test-vectors/rotation.json) against Rotation with an in-memory store. */
+class RotationTest {
+  private class Mem : RotationState {
+    override var storedReleaseKey: String? = null
+    override var storedSequence = 0L
+    override var storedPinnedKey: String? = null
+    override var storedPending: String? = null
+    var commits = 0
+    override fun commit(releaseKey: String?, sequence: Long, pinnedKey: String?, pending: String?) {
+      storedReleaseKey = releaseKey; storedSequence = sequence; storedPinnedKey = pinnedKey; storedPending = pending; commits++
+    }
+  }
+
+  private val spec = EdDSANamedCurveTable.getByName(EdDSANamedCurveTable.ED_25519)
+  private fun dec(s: String) = Base64.getDecoder().decode(s)
+  private fun verify(m: ByteArray, sig: String, key: String): Boolean = try {
+    val e = EdDSAEngine(MessageDigest.getInstance(spec.hashAlgorithm))
+    e.initVerify(EdDSAPublicKey(EdDSAPublicKeySpec(dec(key), spec)))
+    e.update(m); e.verify(dec(sig))
+  } catch (_: Exception) { false }
+  private fun sign(m: ByteArray, seed: String): String {
+    val e = EdDSAEngine(MessageDigest.getInstance(spec.hashAlgorithm))
+    e.initSign(EdDSAPrivateKey(EdDSAPrivateKeySpec(dec(seed), spec)))
+    e.update(m); return Base64.getEncoder().encodeToString(e.sign())
+  }
+  private fun time(s: String) = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply { timeZone = TimeZone.getTimeZone("UTC") }.parse(s)!!.time
+
+  private val vectors = JSONObject(javaClass.classLoader!!.getResourceAsStream("rotation.json")!!.bufferedReader().readText())
+  private val keys = vectors.getJSONObject("keys")
+  private fun pub(name: String) = keys.getJSONObject(name).getString("publicKey")
+
+
+  private fun make(state: Mem, clock: Array<Long>, count: IntArray) = Rotation(
+    state, vectors.getString("appId"), pub("K1"), vectors.getJSONObject("root").getString("publicKey"),
+    vectors.getLong("minSequence"), { clock[0] }, { m, s, k -> count[0]++; verify(m, s, k) }, { dec(it) })
+
+  @Test fun sharedVectors() {
+    val cases = vectors.getJSONArray("cases")
+    assertEquals(14, cases.length())
+    for (c in 0 until cases.length()) {
+      val case = cases.getJSONObject(c)
+      val name = "case ${case.getInt("id")}: ${case.getString("name")}"
+      val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+      var rot = make(state, clock, count)
+      val steps = case.getJSONArray("steps")
+      for (i in 0 until steps.length()) {
+        val step = steps.getJSONObject(i)
+        clock[0] = time(step.getString("now"))
+        if (step.optBoolean("relaunch")) rot = make(state, clock, count) // new process, same stored state
+        count[0] = 0
+        val results = rot.handle(step.getJSONArray("deliver"))
+        if (step.optBoolean("rejectedWhole")) {
+          assertTrue("$name step $i whole", results.isEmpty())
+          assertEquals("$name step $i signature checks", step.getInt("signatureChecks"), count[0])
+        } else {
+          val want = step.getJSONArray("verify")
+          assertEquals("$name step $i result count", want.length(), results.size)
+          for (k in 0 until want.length()) {
+            val w = want.getJSONObject(k)
+            assertEquals("$name step $i env $k", w.getBoolean("ok"), results[k].ok)
+            if (!w.getBoolean("ok")) assertEquals("$name step $i env $k reason", w.getString("reason"), results[k].reason)
+          }
+        }
+        val expect = step.getJSONObject("expect")
+        assertEquals("$name step $i key", pub(expect.getString("currentKey")), rot.currentReleaseKey())
+        assertEquals("$name step $i sequence", expect.getLong("sequence"), rot.effectiveSequence())
+        val pending = state.storedPending?.let { JSONArray(it) } ?: JSONArray()
+        val seqs = (0 until pending.length()).map { JSONObject(pending.getJSONObject(it).getString("body")).getLong("sequence") }
+        val wantSeqs = expect.getJSONArray("pending").let { a -> (0 until a.length()).map { a.getLong(it) } }
+        assertEquals("$name step $i pending", wantSeqs, seqs)
+      }
+    }
+  }
+
+  private fun firstDelivery(caseId: Int): JSONArray {
+    val cases = vectors.getJSONArray("cases")
+    for (i in 0 until cases.length()) if (cases.getJSONObject(i).getInt("id") == caseId)
+      return cases.getJSONObject(i).getJSONArray("steps").getJSONObject(0).getJSONArray("deliver")
+    error("no case $caseId")
+  }
+
+  @Test fun pointersFollowTheRotatedKey() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+    val rot = make(state, clock, count)
+    val pointer = "{\"release\":2}".toByteArray()
+    val bySeed = { n: String -> sign(pointer, keys.getJSONObject(n).getString("seed")) }
+    assertTrue(verify(pointer, bySeed("K1"), rot.currentReleaseKey()))
+    assertTrue(rot.handle(firstDelivery(1))[0].ok)
+    assertTrue(verify(pointer, bySeed("K2"), rot.currentReleaseKey()))
+    assertFalse(verify(pointer, bySeed("K1"), rot.currentReleaseKey()))
+  }
+
+  @Test fun corruptPendingIsClearedAndKeyAndSequenceKept() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+    val rot = make(state, clock, count)
+    assertTrue(rot.handle(firstDelivery(1))[0].ok)
+    state.storedPending = "not json {"
+    rot.applyDue()
+    assertEquals(null, state.storedPending)
+    assertEquals(1L, state.storedSequence)
+    assertEquals(pub("K2"), rot.currentReleaseKey())
+  }
+
+  @Test fun newPinDiscardsStoredKeyButKeepsSequence() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+    assertTrue(make(state, clock, count).handle(firstDelivery(1))[0].ok)
+    // A new shell build pins K3 and MIN_SEQUENCE 1: the stored K2 is dropped, and statement 1 cannot come back.
+    val rot = Rotation(state, "tide", pub("K3"), vectors.getJSONObject("root").getString("publicKey"), 1, { clock[0] }, ::verify, { dec(it) })
+    assertEquals(pub("K3"), rot.currentReleaseKey())
+    assertFalse(rot.handle(firstDelivery(1))[0].ok)
+    assertEquals(pub("K3"), rot.currentReleaseKey())
+    assertEquals(1L, state.storedSequence)
+  }
+
+  @Test fun noRootKeyMeansNothingApplies() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime")))
+    val rot = Rotation(state, "tide", pub("K1"), "", 0, { clock[0] }, ::verify, { dec(it) })
+    assertFalse(rot.handle(firstDelivery(1))[0].ok)
+    assertEquals(pub("K1"), rot.currentReleaseKey())
+  }
+}

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,83 @@
 // 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 the engine build id (like "250829098.0.10"), or undefined when the prop is omitted.
+function formatHermesEngine(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !/^\d+\.\d+\.\d+$/.test(value.trim())) {
+    throw new Error(`@shipvo/runtime: hermesEngine must look like 250829098.0.10, got ${JSON.stringify(value)}`);
+  }
+  return value.trim();
+}
+
+// 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(",");
+}
+
+// Returns the root key, or undefined when the prop is omitted. Must be base64 of 32 bytes (an Ed25519 public key).
+function checkRootKey(value) {
+  if (value === undefined) return undefined;
+  const ok = typeof value === "string" && /^[A-Za-z0-9+/]+={0,2}$/.test(value) && value.length % 4 === 0 && Buffer.from(value, "base64").length === 32;
+  if (!ok) throw new Error("@shipvo/runtime: rootKey must be a base64 string that decodes to 32 bytes");
+  return value;
+}
+
+// Returns the minimum rotation sequence, or undefined when the prop is omitted.
+function checkMinSequence(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`@shipvo/runtime: minSequence must be a non-negative integer, got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
 module.exports = function withShipvo(config, props) {
-  const { baseUrl, publicKey, appId, shellMajor = 1 } = props || {};
+  const { baseUrl, publicKey, appId, shellMajor = 1, rootKey, minSequence } = props || {};
   if (!baseUrl || !publicKey || !appId) throw new Error("@shipvo/runtime: baseUrl, publicKey and appId are required");
-  config.extra = { ...(config.extra ?? {}), shipvo: { baseUrl, appId, shellMajor } };
+  checkRootKey(rootKey);
+  checkMinSequence(minSequence);
+  // minSequence is the replay floor for rotation statements; without a root key no statement is accepted, so it would do nothing.
+  if (minSequence !== undefined && rootKey === undefined) throw new Error("@shipvo/runtime: minSequence needs rootKey");
+  const hbc = formatBytecodeVersions(props.hermesBytecodeVersions);
+  const hbe = formatHermesEngine(props.hermesEngine);
+  const nm = formatNativeModules(props.nativeModules);
+  config.extra = { ...(config.extra ?? {}), shipvo: { baseUrl, appId, shellMajor, ...(props.reportEvents === false ? { reportEvents: false } : {}) } };
   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 (hbe !== undefined) cfg.modResults.ShipvoHermesEngine = hbe;
+    if (nm !== undefined) cfg.modResults.ShipvoNativeModules = nm;
     return cfg;
   });
   return withAndroidManifest(config, (cfg) => {
@@ -21,6 +89,11 @@ 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 (rootKey !== undefined) set("dev.shipvo.ROOT_KEY", rootKey);
+    if (minSequence !== undefined) set("dev.shipvo.MIN_SEQUENCE", minSequence);
+    if (hbc !== undefined) set("dev.shipvo.HERMES_BYTECODE_VERSIONS", hbc);
+    if (hbe !== undefined) set("dev.shipvo.HERMES_ENGINE", hbe);
+    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())
+  }
+}