# Adapters for other runtimes

> What a runtime port must do, which release-decision rules exist and where each lives, for maintainers adding a framework adapter.

Canonical page: https://shipvo.dev/docs/adapters/

This page is for a maintainer planning another runtime, such as the Capacitor adapter (epic #297). It lists what the current runtimes do, which release-decision rules exist, and where each one lives. It describes the code as it is.

There are two runtimes today: Android (Kotlin) and iOS (Swift). Both sit behind one JS API in TypeScript.

Paths are from the repository root.

## What an adapter must do

1. **Check.** Ask the control plane for the signed release pointer of this app, shell major and band. Android: `ShipvoRuntimeModule.check()` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt`. iOS: `Updater.check()` in `packages/runtime/ios/Updater.swift`.
2. **Verify.** Check the Ed25519 signature of the pointer body against the public key baked into the shell. Check the size and sha-256 of every downloaded file against the signed pointer. Android: `packages/runtime/android/src/main/java/dev/shipvo/runtime/Verify.kt`. iOS: `packages/runtime/ios/Verify.swift`. Do not edit these files as part of adapter work.
3. **Stage.** Download the bundle (a bsdiff patch if one fits, else the full file, resumable on Android and iOS), verify it, and write it as the pending release. Nothing runs yet.
4. **Apply.** Pick the bundle at load time: the pending release for up to three trial boots, else the current release, else the bundle embedded in the app. Reload without a restart when asked.
5. **Report.** `markHealthy` promotes a pending release that is the one running. Events (`applied`, `rolled_back`, `crash_loop_revert`, `verify_failed`, `pointer_rejected`, and so on) are queued on the device and read with `consumeEvents`. The JS wrapper in `@shipvo/runtime` calls `reportRuntimeEvents()` after `markHealthy` and after each `checkForUpdate`. It drains the queue and sends the forwarded events to `POST {baseUrl}/t`, best effort. An adapter only has to queue the event strings.
6. **Roll back.** Revert to the previous release on crash loop or when the app calls `rollback`, and block that release so it is not fetched again.

The JS API every adapter must back is the `Native` type in `packages/runtime/src/index.ts`: `getState`, `checkForUpdate`, `markHealthy`, `consumeEvents`, `rollback`, `reload`, and optionally `noteCrash`. Where the native module is missing, `Runtime` falls back to a no-op (same file).

## Release-decision rules

"Shared" means one TypeScript implementation that every platform uses. "Per platform" means each runtime has its own copy, and an adapter must write another.

| # | Rule | Where it is decided | Shared or per platform |
|---|------|---------------------|------------------------|
| 1 | **Platform.** A pointer without `platform` is Android. A pointer with `platform: "ios"` is iOS. The control plane serves them from different paths (`/p/<app>/<major>/<band>` and `/p/<app>/<major>/ios/<band>`) and refuses to store a pointer whose `platform` does not match its path. | Pointer schema: `packages/schema/src/index.ts` (`ReleasePointer.platform`). Serve and store: `services/control-plane/src/index.ts` (`servePointer`), `services/control-plane/src/apps.ts` (pointer key check). On device, iOS refuses a pointer that is not `platform: "ios"` (`packages/runtime/ios/Updater.swift`). Android does not read `platform` on device. It relies on the path. | Shared (control plane) plus per platform (iOS device check) |
| 2 | **Major.** The pointer `app_id` and `shell_major` must equal the shell's own, or the pointer is refused. The shell major is also part of the pointer URL. | Android: `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt` (`check()`), `packages/runtime/android/src/main/java/dev/shipvo/runtime/Store.kt` (`shellMajor`, from manifest meta-data). iOS: `packages/runtime/ios/Updater.swift`, `packages/runtime/ios/Store.swift`. Schema field: `packages/schema/src/index.ts`. | Per platform |
| 3 | **Band.** A device picks a random cohort 0-999 once and keeps it. Cohort 0-9 is `b0`, 10-99 is `b1`, 100-999 is `b2`. The device asks for the pointer of its own band. | TypeScript: `bandForCohort` and `BAND_RANGES` in `packages/schema/src/index.ts`. The control plane exposes it in `services/control-plane/src/index.ts`. Devices do not call it. Android re-implements it in `packages/runtime/android/src/main/java/dev/shipvo/runtime/Store.kt` (`cohort`, `band`). iOS re-implements it in `packages/runtime/ios/Store.swift` (`cohort`, `band`). | Per platform (the TypeScript function is a reference, not used on device) |
| 4 | **Newer than known.** Skip a release that is not newer than the highest of current, pending and blocked. | Android: `check()` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt`, and `BootRules.mayStage` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/BootRules.kt` inside the lock, right before staging. iOS: `Updater.check()` (`release <= known`). | Per platform |
| 5 | **Minimum shell version.** Refuse a release whose `min_shell_version` is above the installed app version. Pre-release tags are ignored. | Schema field: `packages/schema/src/index.ts`. Compare: `Verify.semverLess` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/Verify.kt` (Android) and `packages/runtime/ios/Verify.swift` (iOS). | Per platform |
| 6 | **Bytecode match.** Refuse a release whose `hermes_bytecode_version` differs from the one in the shell's embedded bundle header. A missing value on either side means "unknown" and the release is allowed. A refused release is blocked and logged as `hermes_bytecode_mismatch`. | On device: `packages/runtime/android/src/main/java/dev/shipvo/runtime/HermesGuard.kt` (Android) and `packages/runtime/ios/HermesGuard.swift` (iOS), called from `check()` and `Updater.check()`. At the control plane: when the shell sends `?hbc=96,98`, a release outside that list gets a 404 with `hermes_bytecode_mismatch` (`decideOffer` in `services/control-plane/src/offer.ts`, called by `servePointer`). The shell sends its versions from `dev.shipvo.HERMES_BYTECODE_VERSIONS` (`packages/runtime/android/src/main/java/dev/shipvo/runtime/Store.kt`) or `packages/runtime/ios/Store.swift`. Query building: `packages/runtime/android/src/main/java/dev/shipvo/runtime/PointerQuery.kt` (Android), `Updater.pointerURL` (iOS). Schema fields: `hermes_bytecode_version` in `ReleasePointer` and `hermes_bytecode_versions` in `ShellManifest`. | Control plane check is shared. Device check is per platform |
| 7 | **Capability match (native modules).** A release lists `required_native_modules` (name to semver range). A shell lists its `native_modules` (name to version). A missing module, or a version outside the range, means the release is not offered. Unknown on either side means offered. | Rule: `checkNativeModules` and `satisfiesRange` in `packages/schema/src/index.ts`, called by `decideOffer` in `services/control-plane/src/offer.ts` when the shell sends `?nm=`. The device only sends the list and reads the typed 404 answer (`PointerQuery.mismatchReason` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/PointerQuery.kt`; `Updater.check()` on iOS). I found no on-device copy of the comparison. | Shared (TypeScript, on the control plane) |
| 8 | **Halted release.** A release the owner halted is not offered. | `decideOffer` in `services/control-plane/src/offer.ts` (the `halt/<app>` value is read in `servePointer`). | Shared (control plane) |
| 9 | **Patch choice.** Use a patch only if its `from_sha256` equals the sha-256 of the bundle the device runs (the current bundle, else the embedded one). Check the patch hash, then the rebuilt bundle's size and hash. On any failure, fall back to the full bundle. On Android, a patch that runs out of memory, or whose base, patch and output together exceed a share of the app's heap limit, also falls back to the full download; `patchError` reports `out_of_memory` or `over_memory_budget`. iOS also requires the patch to be smaller than the bundle. | Android: `check()` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt` and `packages/runtime/android/src/main/java/dev/shipvo/runtime/Patch.kt`. iOS: `Updater.patched` in `packages/runtime/ios/Updater.swift` and `packages/runtime/ios/Patch.swift`. Capacitor Android: the patch choice is in `packages/capacitor/src/engine.ts`; the patch, hash and memory checks are in `packages/capacitor/android/src/main/java/dev/shipvo/capacitor/PatchStep.java` and `Patch.java`. | Per platform |
| 10 | **Trial boots.** A staged release gets 3 boots (`MAX_BOOTS` / `maxBoots`). After that it is dropped, blocked and logged as `crash_loop_revert`. | Android: `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoHostHandler.kt`. iOS: `BundleSelector.choose`. | Per platform |
| 11 | **Crash-loop window.** More than 3 unhealthy boots of the current release in 60 seconds reverts to the previous release and blocks the current one. | Android: `BootRules.countBoot` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/BootRules.kt` (`WINDOW_MS` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoHostHandler.kt`). iOS: `BundleSelector.choose` (`windowSeconds`). | Per platform |
| 12 | **Promotion and stability.** `markHealthy` promotes a pending release only if it is the one running. The boot counter is cleared only after the app stays up 30 seconds, or goes to the background cleanly. An uncaught JS error cancels that (`noteCrash`). | Android: `packages/runtime/android/src/main/java/dev/shipvo/runtime/BootRules.kt` (`onHealthy`, `markStableIfHealthy`), `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt`. iOS: `BundleSelector.promoteIfRunning`, `BundleSelector.markStableIfHealthy`. JS hook: `installCrashHook` in `packages/runtime/src/index.ts`. | Per platform (the crash hook is shared) |
| 13 | **New shell resets state.** When the installed app version differs from the one the stored bundles were fetched under, all stored bundles and counters are deleted. | Android: `Store.resetForNewShell`. iOS: `Store.resetForNewShell`. | Per platform |
| 14 | **Rollback.** An app-called `rollback` drops the pending release, blocks the current one, and reverts to the previous one. | Android: `rollback` in `packages/runtime/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt`, `ShipvoHostHandler.revertToPrevious`. iOS: `packages/runtime/ios/ShipvoRuntimeModule.swift`, `BundleSelector.revertToPrevious`. | Per platform |
| 15 | **Rejection events.** A typed 404 from the control plane (`hermes_bytecode_mismatch`, `native_module_missing`, `native_module_version`) returns `status: "none"` with a `reason`. Android and iOS return the reason to the caller. Android also queues `pointer_rejected:<reason>` once, not once per check. | Android: `PointerQuery.rejectionEvent`. iOS: `Updater.swift`. | Per platform |

Telemetry event names are in `packages/schema/src/index.ts` (`Telemetry.event`).

## Capacitor (web bundles)

`@shipvo/capacitor` (`packages/capacitor`) is a third implementation, in TypeScript, for a signed web bundle. A web pointer has `kind: "web"`. These rules are now implemented in `packages/capacitor/src/engine.ts` and tested in `packages/capacitor/test/capacitor.test.ts`: 1 (platform and kind), 2, 3 (uses `bandForCohort` from `@shipvo/schema`), 4, 5, 10, 11, 12, 13, 14 and 15 (events are `pointer_rejected:<why>`, queued once per distinct reason). Signature, size and sha-256 checks use WebCrypto. `native.ts` serves the chosen bundle in the web view, and `checkForUpdate({ apply: true })` switches it. A plain web bundle has no bytecode header, so rule 6 has nothing to check. These are one TypeScript copy that Android and iOS Capacitor shells both use, not a fourth copy per OS.

## Where each rule runs

For the React Native runtimes:

On the control plane, for both platforms:
- Rule 1: serving and storing the pointer by platform.
- Rule 6: the server side (`?hbc=`).
- Rules 7 (capability match) and 8 (halted release).

On the device, per platform (Android and iOS each have their own code):
- Rule 1: the iOS platform check.
- Rules 2 to 5.
- Rule 6: the device side (the bytecode header check and sending the versions).
- Rules 9 to 14.
- Rule 15: the device reads the typed 404 reason on Android and iOS and returns it with `status: "none"`.

The device sends `?hbc=` and `?nm=` and reads the typed 404 answer.

A runtime port that loads web assets from a server path (as Capacitor does) picks its bundle through its own host hook, so rules 10 to 14 are written against that hook. `@shipvo/capacitor` does this in `packages/capacitor/src/engine.ts`.

## Troubleshooting

- **A release is never offered to a device.** Check rules 1, 2, 5, 6, 7 and 8 first. The control plane answers with a typed 404 (`hermes_bytecode_mismatch`, `native_module_missing`, `native_module_version`) or a halted release. For a typed 404, `checkForUpdate` returns `status: "none"` with that `reason`, on Android and iOS. A halted release has no reason: the result is `status: "none"` and the device keeps its current release.
- **Two runtimes pick different bands.** Cohort and band are chosen on the device (rule 3). Compare the thresholds in the three copies named in that row: `packages/schema/src/index.ts`, `Store.kt` and `Store.swift`.
- **A rule is not covered by a port.** Use the table: "Shared" rules run on the control plane for every runtime, "Per platform" rules need code in each runtime.

## Next steps

- [Capacitor](https://shipvo.dev/docs/capacitor.md): signed web-bundle updates for Android and iOS, from one TypeScript engine.
- [Self-hosting](https://shipvo.dev/docs/self-hosting.md): the control plane that decides rules 1, 6, 7 and 8.
- [Store release](https://shipvo.dev/docs/store.md): ship the shell to Google Play and the App Store.
- [Threat model for signed updates](https://github.com/shipvo/shipvo/blob/main/docs/threat-model.md): why verification is never skipped.
- [Glossary](https://shipvo.dev/learn/glossary.md).
