ADR-001: Native runtimeとEAS Updateの互換性境界

Status: Accepted (policy decision; activation deferred)
Date: 2026-08-30
Scope: Expo Updates runtime selection and native-release rules

背景

このアプリはJavaScript/TypeScriptだけでなく、Local Expo Module（FeliCa、Live Activity）、Widget/ActivityKit target、Android Foreground Service、config plugin、Mapsなど、ビルドに含まれるnative code/configを持つ。したがって、Expo SDKが同じであることだけでは、二つのbinaryが同じJS-native interfaceを持つ保証にならない。

現在の実装では、app.jsonのruntimeVersionは{ "policy": "sdkVersion" }である。監査時点の読み取り専用EAS確認では、7.2のbinary/updateがexposdk:55.0.0 runtimeを共有していた。

候補の比較

policy	利点	このアプリでの注意点	判断
`sdkVersion`	SDK単位で分かりやすい	SDKを変えないnative変更を分離できない	不採用
`appVersion`	app versionとruntimeが一致し、iOS/Androidで同じruntimeを運用しやすい	native変更・公開releaseごとに`version`を更新する運用が必要	採用
`nativeVersion`	build number/version codeまで含められる	iOS/Androidでruntimeが分かれ、build番号の管理が複雑になる	今回不採用
`fingerprint`	nativeに影響する変更を自動的に分離できる	runtimeが細かく分岐し、公式ドキュメント上は現時点でexperimental / not widely recommended	将来再評価
custom string	ルールを完全に手動管理できる	更新漏れを機械的に防ぎにくい	今回不採用

Expo公式の現行ドキュメントでは、appVersionを通常の推奨とし、fingerprintはnative変更を自動反映できる一方で実験的な扱いとしている。また、native code/configを変更した場合は新しいbuildが必要であり、同じruntimeへ互換性のないUpdateを公開してはいけない。

参照:

現在のruntime

項目	現在値	source of truth / 注記
app version	`7.2`	`app.json`。Store向け表示versionの正本
runtime policy	`sdkVersion`	`app.json`。このADRの変更対象だが、まだ変更しない
historical observed runtime	`exposdk:55.0.0`	2026-08-28監査時のread-only EAS観測。現在のlive stateはEAS CLIで再確認する
historical observed 7.2 path	profile `beta7.1` / channel `gmarket`	EAS Build/Updateの監査スナップショット。名前変更・削除は別承認

Current implementation status

Expo SDK57へのNative migrationは完了している。
SDK57 Development / Preview binaryと、ユーザー実機で確認できた主要Native機能の状態は、SDK57移行検証記録に分離して記載している。
app.json のruntimeVersion設定は依然として sdkVersion policyであり、appVersion policy activationは未実施である。
2026-08-31のEAS CLI read-only観測では、beta7.2 / homebrew のiOS build 74とAndroid versionCode 37がSDK57 / exposdk:57.0.0でFINISHEDだった。これは確認日付きsnapshotであり、全Production audienceの状態を表さない。

採用方針

次回、native buildを作るreleaseから runtimeVersion.policy = "appVersion" を採用する。これにより、そのbuildのruntimeはapp.jsonのapp version（現在の値なら7.2）になり、SDKだけではなく公開versionをruntimeの境界として扱う。

ただし、現在の app.json のruntime設定は sdkVersion のままである。SDK57へのNative migration後も appVersion policy activationは未実施であり、既存のSDK55/SDK57 binary・Updateへの到達性を不用意に変えないため、次回native releaseで検証buildと同時に切り替える。

app versionを確定し、native build用に更新する。
runtimeVersionをappVersion policyへ変更する。
iOS/Android DevelopmentまたはPreview BuildでNative Module、Widget、Live Activity/Foreground Service、Maps、通知を確認する。
そのbuildと同じruntimeを対象に、Preview channelでOTAの取得・起動・rollbackを確認する。
対象binaryとchannelを確認してからProduction channelへ公開する。

Native変更時のRelease Rule

以下はnative変更とみなし、OTAだけで配信しない。

modules/ のSwift/Kotlin/TypeScript native bindingの変更
targets/widget/、Widget/ActivityKit、Android Widget、Foreground Serviceの変更
plugins/、app.jsonのpermission、entitlement、target、native configの変更
native module/package、Maps、notification、OS capabilityの追加・更新
Babel/Metroの変更がnative bundleやmodule availabilityへ影響する場合
Expo SDK、React Native、Reanimatedなどnative runtimeを含む依存更新

Native変更では、app version/runtimeを確認し、対応するDevelopment/Preview/Production Buildを作ってからUpdateを公開する。ios//android/は生成物のため直接編集せず、config/plugin/module/targetを正本にする。

OTAのみ許可される変更

対象binaryのruntime互換性を確認した上で、次のようなJS-only変更はOTA候補とする。

既存のnative APIとassetだけを使う画面・表示・文言の変更
既存の通信parser、state、domain adapterの変更
native capability、permission、entitlement、asset bundlingの前提を変えないbug fix

「JS/TSファイルだけを変更した」という理由だけでOTA可と判定せず、使用するAPIが対象binaryに存在することを確認する。

OTAしてはいけない変更

上記Native変更を含むUpdate
新しいnative method、permission、Widget/Activity capabilityを要求するJS
新しいbundle内assetがbinaryに含まれることを確認できない変更
runtime/channel/audienceが不明なbinaryへ向けたUpdate

Rollback

rollbackは、対象binaryと同じruntimeの既知の正常なUpdateへ戻す。異なるruntimeのUpdateを旧binaryの救済策にはしない。
新runtimeのPreview/Productionで問題が出た場合は、同じ新runtimeへ既知の正常なbundleを再公開するか、embedded updateへ戻せる手順を選ぶ。
gmarketなど既存channelをrename/deleteしない。channel、runtime、installed binary、Update IDの対応を確認してから凍結・移行・rollbackする。
rollback操作やUpdate公開は本ADRでは実行しない。EAS console/CLIでの実行前に担当者レビューを行う。

Next native release gate

次回Production Native Buildでは、以下を同じrelease gateとして確認する。

app version確定
iOS buildNumber確定
Android versionCode確定
runtimeVersion.policyをappVersionへ変更
Development / Preview Build
iOS Native smoke
Android Native smoke
Preview OTA取得確認
rollback確認
binary / runtime / channel対応確認
Production Build
Production Update配信先確認

未解決の手動確認

現在のinstalled binaryのchannel/runtime/audience inventory
次回native buildで採用するapp versionと各store build number
EAS channelの所有者、rollback担当、Preview smoke端末
Sentry release/source mapとEAS Update IDの紐付け

7.6 KiB Raw Permalink Blame History Unescape Escape