@shipvo/runtime 0.1.3 → 0.1.5

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,44 @@ Runtime.markHealthy();                   // call once the first screen rendered
 ```
 
 `shipvo init` wires all of this for you.
+
+## Events
+
+The runtime reports refused and reverted releases for you. `Runtime.markHealthy()` and every `Runtime.checkForUpdate()` drain the device's event queue and send each event to `POST {baseUrl}/t`, using `baseUrl` and `appId` from `expo.extra.shipvo`. A refusal found during a background check is reported in the same session, without a restart.
+
+Forwarded events: `crash_loop_revert`, `rolled_back`, `verify_failed`, `download_failed`, `hermes_bytecode_mismatch`, `native_module_missing`, `native_module_version`. `verify_failed`, `download_failed` and `hermes_bytecode_mismatch` are reported under the failed release id. The native-module reasons arrive as `pointer_rejected:<reason>` and are reported under the reason name. Sending is best effort: a failed send never throws and never blocks.
+
+```ts
+import { reportRuntimeEvents, onRuntimeEvents } from "@shipvo/runtime";
+reportRuntimeEvents();                       // drain and send now (markHealthy and checkForUpdate already do)
+onRuntimeEvents((events) => console.log(events)); // see the drained strings, for a log
+```
+
+To turn the automatic report off, pass `reportEvents: false` to the config plugin (it lands in `expo.extra.shipvo`), and call `reportRuntimeEvents()` yourself. `forwardRuntimeEvents(events, send)` and `FORWARDED_EVENTS` are also exported for custom senders. If you call `Runtime.consumeEvents()` yourself, you take events away from the report.
+
+The runtime does not emit `download_failed` yet. The control plane accepts it.
+
+## Signed telemetry
+
+Call `enableSignedTelemetry` once at startup. The install registers once, keeps a secret key in your storage, and then signs each report. If registration fails, reports go out unsigned and the next launch tries again.
+
+```ts
+import { enableSignedTelemetry } from "@shipvo/runtime";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+await enableSignedTelemetry({
+  storage: AsyncStorage,
+  registerUrl: "https://cp.example.com/t/register",
+  // crypto: { randomBytes, hmacSha256 }  // React Native has no crypto.subtle, so pass your own
+});
+```
+
+The sent body is the unsigned JSON with its closing `}` replaced by `,"sig":"<hex>"}`. The HMAC-SHA256 covers the unsigned JSON, closing `}` included. A second call replaces the first identity.
+
+## 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

@@ -13,9 +13,16 @@ android {
     versionName "0.0.1"
     consumerProguardFiles "proguard-rules.pro"
   }
+  // The shared key rotation vectors (also used by the CLI and iOS tests) are read as test resources.
+  sourceSets {
+    test.resources.srcDirs += ["../test-vectors"]
+  }
 }
 
 dependencies {
+  testImplementation 'junit:junit:4.13.2'
+  // The Android SDK's org.json is a stub in JVM unit tests.
+  testImplementation 'org.json:json:20231013'
   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/Clock.kt

@@ -0,0 +1,9 @@
+package dev.shipvo.runtime
+
+/** Source of wall-clock time for rotation checks. Rotation code never reads the system time directly. */
+internal fun interface Clock {
+  /** Milliseconds since the Unix epoch. */
+  fun now(): Long
+
+  object Wall : Clock { override fun now() = System.currentTimeMillis() }
+}

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,36 @@
+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"; `hbe` is the engine build id "250829098.0.10"; `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?, hbe: String? = null): String {
+    val q = ArrayList<String>()
+    hbc?.split(',')?.map { it.trim() }?.filter { it.isNotEmpty() }?.takeIf { it.isNotEmpty() }
+      ?.let { q += "hbc=" + it.joinToString(",") { v -> enc(v) } }
+    hbe?.trim()?.takeIf { it.isNotEmpty() }?.let { q += "hbe=" + enc(it) }
+    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/Rotation.kt

@@ -0,0 +1,134 @@
+package dev.shipvo.runtime
+
+import android.util.Base64
+import org.json.JSONArray
+import org.json.JSONObject
+import java.text.SimpleDateFormat
+import java.util.Locale
+import java.util.TimeZone
+
+/** What Rotation needs from storage. [commit] writes all three values in one atomic step. */
+internal interface RotationState {
+  val storedReleaseKey: String?
+  val storedSequence: Long
+  val storedPinnedKey: String?
+  val storedPending: String?
+  fun commit(releaseKey: String?, sequence: Long, pinnedKey: String?, pending: String?)
+}
+
+/**
+ * Root-signed release key rotation (docs/design/key-rotation.md, sections 3 to 9).
+ * A statement is an envelope {body, signature}; the signature is by the pinned root key over the exact body string.
+ */
+internal class Rotation(
+  private val state: RotationState,
+  private val appId: String,
+  private val pinnedReleaseKey: String,
+  private val rootKey: String,
+  private val minSequence: Long,
+  private val clock: Clock = Clock.Wall,
+  private val verify: (ByteArray, String, String) -> Boolean = Verify::ed25519,
+  private val decode: (String) -> ByteArray = { Base64.decode(it, Base64.DEFAULT) },
+) {
+  class Result(val ok: Boolean, val reason: String? = null)
+
+  private class Stmt(val body: String, val signature: String, val sequence: Long, val newKey: String, val validFrom: Long)
+
+  /** Signature checks made so far (tests count them). */
+  var signatureChecks = 0
+    private set
+
+  /** The release key pointers are verified against: the stored one, or the pinned one when nothing usable is stored. */
+  fun currentReleaseKey(): String {
+    val k = state.storedReleaseKey
+    return if (k != null && state.storedPinnedKey == pinnedReleaseKey && keyOk(k)) k else pinnedReleaseKey
+  }
+
+  fun effectiveSequence(): Long = maxOf(state.storedSequence, minSequence)
+
+  /** Applies due pending statements. Run on launch and before every pointer check. */
+  fun applyDue() { handle(null) }
+
+  /**
+   * Handles a delivered `rotations` array (null for none). Returns one result per envelope; empty when the array
+   * is refused whole. Verdicts are against the state before this delivery.
+   */
+  fun handle(rotations: JSONArray?): List<Result> {
+    if (rotations != null && rotations.length() > MAX) return emptyList()
+    val effective = effectiveSequence()
+    val known = HashMap<Long, Stmt>()
+    for (s in loadPending()) if (s.sequence > effective) known.putIfAbsent(s.sequence, s)
+    val results = ArrayList<Result>()
+    if (rotations != null) for (i in 0 until rotations.length()) {
+      val env = rotations.optJSONObject(i)
+      val body = env?.opt("body") as? String
+      val sig = env?.opt("signature") as? String
+      if (body == null || sig == null || body.toByteArray(Charsets.UTF_8).size > MAX_BODY) { results.add(Result(false, "malformed")); continue }
+      val r = check(body, sig, effective)
+      if (r is Stmt) {
+        // Same sequence twice: the first accepted stays.
+        if (known.containsKey(r.sequence)) results.add(Result(false, "replay")) else { known[r.sequence] = r; results.add(Result(true)) }
+      } else results.add(r as Result)
+    }
+    commitState(known.values.sortedBy { it.sequence }, effective)
+    return results
+  }
+
+  /** Section 3 rules 1 to 5 in order. Returns a [Stmt] when valid, else a [Result]. */
+  private fun check(body: String, sig: String, effective: Long, reload: Boolean = false): Any {
+    signatureChecks++
+    if (!verify(body.toByteArray(Charsets.UTF_8), sig, rootKey)) return Result(false, "bad_signature")
+    val j = try { JSONObject(body) } catch (_: Exception) { return Result(false, "malformed") }
+    if (j.opt("type") != "key-rotation") return Result(false, "bad_type")
+    if (j.opt("appId") != appId) return Result(false, "wrong_app")
+    val seq = j.opt("sequence").let { if (it is Int) it.toLong() else it as? Long } ?: return Result(false, "malformed")
+    if (seq < 1) return Result(false, "malformed")
+    if (seq <= effective) return Result(false, "replay")
+    val validFrom = (j.opt("validFrom") as? String)?.let { parseTime(it) } ?: return Result(false, "malformed")
+    if (!reload && validFrom > clock.now() + NINETY_DAYS_MS) return Result(false, "too_far")
+    val newKey = j.opt("newKey") as? String
+    if (newKey == null || !keyOk(newKey)) return Result(false, "bad_key")
+    return Stmt(body, sig, seq, newKey, validFrom)
+  }
+
+  /** Section 7: apply the due statement with the highest sequence, keep the later ones, at most 8. */
+  private fun commitState(all: List<Stmt>, effective: Long) {
+    val now = clock.now()
+    val due = all.filter { it.validFrom <= now }.maxByOrNull { it.sequence }
+    val keep = (if (due == null) all else all.filter { it.sequence > due.sequence }).take(MAX)
+    val pending = if (keep.isEmpty()) null else JSONArray(keep.map { JSONObject().put("body", it.body).put("signature", it.signature) }).toString()
+    val changed = due != null || pending != state.storedPending || state.storedPinnedKey != pinnedReleaseKey
+    if (!changed) return
+    // A different pin than the one that wrote the state: drop the stored key, keep the sequence (design section 4).
+    val key = due?.newKey ?: if (state.storedPinnedKey == pinnedReleaseKey) state.storedReleaseKey else null
+    state.commit(key, maxOf(due?.sequence ?: 0L, state.storedSequence), pinnedReleaseKey, pending)
+  }
+
+  /** A corrupt or unverifiable pending list is cleared by the next commit; key and sequence stay. */
+  private fun loadPending(): List<Stmt> {
+    val raw = state.storedPending ?: return emptyList()
+    return try {
+      val arr = JSONArray(raw)
+      if (arr.length() > MAX) return emptyList()
+      val out = ArrayList<Stmt>()
+      for (i in 0 until arr.length()) {
+        val o = arr.getJSONObject(i)
+        val r = check(o.getString("body"), o.getString("signature"), 0, reload = true)
+        if (r is Stmt) out.add(r)
+      }
+      out
+    } catch (_: Exception) { emptyList() }
+  }
+
+  private fun keyOk(k: String): Boolean = try { decode(k).size == 32 } catch (_: Exception) { false }
+
+  private fun parseTime(s: String): Long? = try {
+    SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply { timeZone = TimeZone.getTimeZone("UTC"); isLenient = false }.parse(s)?.time
+  } catch (_: Exception) { null }
+
+  companion object {
+    const val MAX = 8
+    const val MAX_BODY = 1024
+    const val NINETY_DAYS_MS = 90L * 24 * 60 * 60 * 1000
+  }
+}

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")
     }
@@ -92,17 +128,29 @@ class ShipvoRuntimeModule : Module() {
   private fun check(): Map<String, Any?> {
     val s = Store(ctx)
     require(s.baseUrl.isNotEmpty() && s.publicKey.isNotEmpty() && s.appId.isNotEmpty()) { "runtime not configured" }
+    val rotation = s.rotation()
+    rotation.applyDue() // due root-signed key rotations apply before any pointer is checked
     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, s.hermesEngine), 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()
 
+    // Root-signed rotation statements ride along with the pointer; handle them before the pointer is verified.
+    envelope.optJSONArray("rotations")?.let { rotation.handle(it) }
     val t0 = SystemClock.elapsedRealtime()
     val bodyStr = envelope.getString("body")
-    require(Verify.ed25519(bodyStr.toByteArray(Charsets.UTF_8), envelope.getString("signature"), s.publicKey)) { "pointer signature invalid" }
+    require(Verify.ed25519(bodyStr.toByteArray(Charsets.UTF_8), envelope.getString("signature"), rotation.currentReleaseKey())) { "pointer signature invalid" }
     val body = JSONObject(bodyStr)
     require(body.getString("app_id") == s.appId && body.getInt("shell_major") == s.shellMajor) { "pointer for another app/shell" }
     val release = body.getInt("release")
@@ -110,10 +158,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 +198,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, RotationState {
   private val p: SharedPreferences = ctx.getSharedPreferences("shipvo.runtime", Context.MODE_PRIVATE)
   val dir: File get() = File(ctx.filesDir, "shipvo").apply { mkdirs() }
 
@@ -63,13 +63,31 @@ 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() }
+
+  override val storedReleaseKey: String? get() = p.getString("rotation.releaseKey", null)
+  override val storedSequence: Long get() = try { p.getLong("rotation.sequence", 0) } catch (_: ClassCastException) { 0 }
+  override val storedPinnedKey: String? get() = p.getString("rotation.pinnedKey", null)
+  override val storedPending: String? get() = p.getString("rotation.pending", null)
+  /** One commit() writes key, sequence, pinned key and pending list together. */
+  override fun commit(releaseKey: String?, sequence: Long, pinnedKey: String?, pending: String?) {
+    p.edit().apply {
+      if (releaseKey != null) putString("rotation.releaseKey", releaseKey) else remove("rotation.releaseKey")
+      putLong("rotation.sequence", sequence)
+      if (pinnedKey != null) putString("rotation.pinnedKey", pinnedKey) else remove("rotation.pinnedKey")
+      if (pending != null) putString("rotation.pending", pending) else remove("rotation.pending")
+    }.commit()
+  }
+  /** Key rotation for this shell: root-signed statements can replace the release key (docs/design/key-rotation.md). */
+  fun rotation(clock: Clock = Clock.Wall) = Rotation(this, appId, publicKey, rootKey, minSequence, clock)
 
   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 +97,24 @@ 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") ?: ""
+  /** Root public key that signs rotation statements. Empty when the shell does not declare one: rotation is then off. */
+  val rootKey: String get() = meta("dev.shipvo.ROOT_KEY") ?: ""
+  /** Highest rotation sequence that existed when this shell was built. */
+  val minSequence: Long get() = metaAny("dev.shipvo.MIN_SEQUENCE")?.toLongOrNull() ?: 0
   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() }
+  /** Hermes engine build id this shell runs, e.g. "250829098.0.10". Null when the shell does not declare it. */
+  val hermesEngine: String? get() = metaAny("dev.shipvo.HERMES_ENGINE")?.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 {