@arms/rum-reactnative 0.1.3-beta.5 → 0.1.4-beta.2

package/README.md

@@ -5,6 +5,7 @@
 ## 功能特性
 
 - **原生崩溃采集** — 自动捕获 iOS（KSCrash）与 Android（Java + NDK）原生崩溃，支持堆栈双侧截断与数据体积优化
+- **OOM采集（iOS）** — 看门狗终止（Watchdog Termination / FOOM）的事后推断上报，默认关闭，需显式开启
 - **API性能监控** — 自动拦截 XMLHttpRequest / fetch 请求，采集耗时、状态码等指标
 - **JS错误捕获** — 自动捕获 JavaScript 运行时异常
 - **控制台错误监听** — 监听 `console.error` 输出
@@ -81,6 +82,7 @@ armsRum.init({
 | api | boolean \| object | `true` | API请求监控（XMLHttpRequest / fetch） |
 | jsError | boolean \| object | `true` | JavaScript运行时错误捕获 |
 | consoleError | boolean \| object | `true` | `console.error`监听 |
+| oom | boolean | `false` | OOM（iOS 看门狗终止推断）采集，仅 iOS 前台场景，需显式开启，详见[配置参考](docs/ReactNative%20SDK配置参考.md) |
 
 ### sessionConfig Session配置
 
@@ -418,6 +420,7 @@ SDK 仅持久化一个键 `_arms_uid`（匿名用户 UID），用于跨冷启动
 1. **必须重新构建原生工程**：新增了 TurboModule 方法，升级或首次接入后需要重新执行 iOS 的 `pod install`、Android 的 Gradle Sync；Expo 工程请执行 `expo prebuild --clean` 后再编译，否则会报 protocol method 缺失。
 2. **隔离命名空间，不污染宿主 App**：iOS 走独立 `NSUserDefaults` suite、Android 走独立 prefs 文件，与宿主 App 自身的偏好数据互不干扰；用户卸载 / 抹机时会一并清除。
 3. **从旧版本（依赖 AsyncStorage）升级会重置一次 UID**：原 AsyncStorage 中的 `_arms_uid` 不会自动迁移到新存储，老用户首次升级后会被分配新 UID（仅影响一次 UV 统计的连续性，不影响功能与后续使用）。如对历史 UID 连续性有强诉求，请提 issue。
+4. **RN 0.68-0.70 的 Android 宿主前置条件**：宿主工程 `android/build.gradle` 的 buildscript 需存在 `kotlin-gradle-plugin` classpath，且 Kotlin 版本 **≥ 1.8.0**（RN 0.70 模板默认 1.6.x，无法读取 SDK 依赖的 kotlin-stdlib 1.8 metadata，需手动提升）。AGP 无需改动——SDK 构建脚本对 AGP <7.3 自动回退 AndroidManifest package 属性。iOS 侧无额外配置，`pod install` 即可（0.68-0.70 自动走旧桥导出路径）。因含原生代码，**Expo Go 不可用**（需 `expo prebuild` 或 EAS Build）。
 
 ## 版本要求
 
@@ -425,9 +428,10 @@ SDK 的 peerDependencies 声明为 `react-native: >=0.68.0`，原生构建配置
 
 | 功能点 | 关键依赖 / API | 最低 RN 版本 | 说明 |
 |--------|--------------|-------------|------|
-| **原生崩溃采集** | TurboModule + codegen | 0.68 | podspec / build.gradle 按版本条件分支，自动适配 0.68-0.70 和 0.71+ |
+| **原生崩溃采集** | TurboModule + codegen | 0.68 | 自动适配 0.68-0.70 旧桥导出与 0.71+ Spec 协议/interop；RN ≤0.70 Android 前置条件见注意事项 4 |
 | NDK 崩溃采集（C/C++） | CMake + NDK `externalNativeBuild` | 0.68 | 随原生崩溃采集一起启用 |
 | iOS 崩溃采集（KSCrash） | KSCrash 2.5.1（CocoaPods 源码依赖，已锁定版本） | 0.68 | `pod install` 时自动编译 |
+| **OOM 采集（iOS）** | TurboModule + KSCrash + 状态快照持久化 | 0.68 | 仅 iOS，默认关闭（`collectors.oom` 显式开启）；Android 为空实现 |
 | **JS 异常采集** | `ErrorUtils.setGlobalHandler` | 0.68 | 全版本可用 |
 | Hermes Promise rejection | `HermesInternal.enablePromiseRejectionTracker` | 0.70（推荐） | Hermes 为默认引擎时完整支持 |
 | JSC Promise rejection 兜底 | `globalThis.onunhandledrejection` | 0.68 | 非 Hermes 引擎有降级方案 |
@@ -443,8 +447,11 @@ SDK 的 peerDependencies 声明为 `react-native: >=0.68.0`，原生构建配置
 | **自监控（Self-Monitoring）** | `fetch` 上报 Protobuf 至 `/rum/monitor` | 0.68 | 纯 JS 实现 |
 | **Expo 集成** | Expo Config Plugin | Expo SDK 49+（RN 0.72+） | 仅配置透传，零运行时依赖 |
 
-> **总结**：SDK 声明支持 RN ≥ 0.68，原生构建配置（podspec / build.gradle）已做多版本条件适配。RN 0.71+ 使用 `install_modules_dependencies` / `react-android`；RN 0.68-0.70 使用手动依赖 / `react-native:+`。JS 侧通过 `TurboModuleRegistry.get` + `NativeModules` 双路径获取原生模块，原生模块缺失时自动降级为空实现，不影响纯 JS 能力。
+> **总结**：SDK 声明支持 RN ≥ 0.68。iOS 经 `__has_include` 条件协议 + `RCT_EXPORT_METHOD` 旧桥导出、Android 经 `@ReactMethod` 方法表 + `namespace` DSL 条件守卫，原生能力在 0.68-0.70（旧桥路径）与 0.71+（TurboModule 协议 / interop）均可用；构建层 RN 0.71+ 使用 `install_modules_dependencies` / `react-android`，0.68-0.70 使用手动依赖 / `react-native:+`。JS 侧通过 `TurboModuleRegistry.get` + `NativeModules` 双路径获取原生模块，原生模块缺失时自动降级为空实现，不影响纯 JS 能力。RN ≤0.70 的 Android 宿主需满足 Kotlin ≥1.8 前置条件（见「升级 / 接入注意事项」第 4 条）。
 
 ## 相关文档
 
+- [接入ReactNative应用](docs/接入ReactNative应用.md)
+- [ReactNative SDK配置参考](docs/ReactNative%20SDK配置参考.md)
+- [SDK 版本说明](docs/SDK%20版本说明.md)
 - [ARMS用户体验监控文档](https://help.aliyun.com/zh/arms/user-experience-monitoring/)

package/android/build.gradle

@@ -70,7 +70,11 @@ if (isRn71Plus) {
 }
 
 android {
-  namespace "com.rumsdkreactnative"
+  // AGP 7.3+ 才支持 namespace DSL（RN 0.70 模板默认 AGP 7.2.1）；低版本回退
+  // AndroidManifest.xml 的 package 属性（RN 0.68-0.70 兼容，见 dev-docs 打通方案 A1）
+  if (android.hasProperty("namespace")) {
+    namespace "com.rumsdkreactnative"
+  }
 
   compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
 
@@ -109,6 +113,13 @@ android {
     }
   }
 
+  // CMake 显式链接 c++_shared 与 react-android 携带的同名 so 在 androidTest 变体
+  // 合并时冲突（mergeAndroidTestNativeLibs 报 2 files found）。两者为同一 STL，取任一
+  // 均可，pickFirst 去重（库模块自身声明，宿主无需额外配置）。
+  packagingOptions {
+    pickFirst "**/libc++_shared.so"
+  }
+
   lintOptions {
     disable "GradleCompatible"
   }

package/android/gradle.properties

@@ -1,4 +1,6 @@
-RumSdkReactnative_kotlinVersion=2.0.21
+# 默认 1.8.0：stdlib metadata 可被 1.8+ 编译器读取（向上兼容），覆盖 RN 0.68-0.70
+# 手动配置场景与 0.71+ 默认工具链；宿主 rootProject.ext.kotlinVersion 定义时优先跟随宿主
+RumSdkReactnative_kotlinVersion=1.8.0
 RumSdkReactnative_minSdkVersion=24
 RumSdkReactnative_targetSdkVersion=34
 RumSdkReactnative_compileSdkVersion=35

package/android/src/main/AndroidManifest.xml

@@ -1,4 +1,7 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+<!-- package 属性：AGP <7.3（RN 0.68-0.70）下的包名来源；AGP 7.3+ 由 build.gradle
+     条件 namespace 取代（该属性被忽略，仅 deprecation warning，属预期） -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.rumsdkreactnative">
   <application>
     <!--
       崩溃处理器自启动：通过 ContentProvider 在 Application.onCreate() 之前安装

package/android/src/main/java/com/rumsdkreactnative/RumSdkReactnativeModule.kt

@@ -10,6 +10,8 @@ import android.view.WindowManager
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.module.annotations.ReactModule
 import com.rumsdkreactnative.crash.CrashContextManager
 import com.rumsdkreactnative.crash.CrashHandler
@@ -17,9 +19,13 @@ import org.json.JSONArray
 import org.json.JSONObject
 import java.io.File
 
+// 不继承 codegen 生成的 Spec 基类（RN ≤0.70 不运行 codegen、无此产物，见
+// dev-docs/RN 0.68-0.70 兼容性打通方案.md A2）：直接继承 ReactContextBaseJavaModule，
+// 方法经 @ReactMethod 导出（RN 0.71+ 经 TurboModule interop 调用）；
+// 代价是失去 codegen 对 TS Spec 与原生签名一致性的编译期校验，签名变更需人工同步 Spec
 @ReactModule(name = RumSdkReactnativeModule.NAME)
 class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
-  NativeRumSdkReactnativeSpec(reactContext) {
+  ReactContextBaseJavaModule(reactContext) {
 
   private val prefs: SharedPreferences =
     migratePrefs(reactContext).also {
@@ -36,7 +42,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
 
   // region Storage
 
-  override fun getItem(key: String, promise: Promise) {
+  @ReactMethod
+  fun getItem(key: String, promise: Promise) {
     try {
       promise.resolve(prefs.getString(key, null))
     } catch (e: Throwable) {
@@ -44,7 +51,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun setItem(key: String, value: String, promise: Promise) {
+  @ReactMethod
+  fun setItem(key: String, value: String, promise: Promise) {
     try {
       prefs.edit().putString(key, value).apply()
       promise.resolve(null)
@@ -53,7 +61,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun removeItem(key: String, promise: Promise) {
+  @ReactMethod
+  fun removeItem(key: String, promise: Promise) {
     try {
       prefs.edit().remove(key).apply()
       promise.resolve(null)
@@ -62,7 +71,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun clear(promise: Promise) {
+  @ReactMethod
+  fun clear(promise: Promise) {
     try {
       prefs.edit().clear().apply()
       promise.resolve(null)
@@ -71,7 +81,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
     }
   }
 
-  override fun getAllKeys(promise: Promise) {
+  @ReactMethod
+  fun getAllKeys(promise: Promise) {
     try {
       val array = Arguments.createArray()
       for (key in prefs.all.keys) {
@@ -87,7 +98,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
 
   // region Device Info
 
-  override fun getDeviceInfo(promise: Promise) {
+  @ReactMethod
+  fun getDeviceInfo(promise: Promise) {
     try {
       val ctx = reactApplicationContext
       val map = Arguments.createMap()
@@ -170,7 +182,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
    * 崩溃文件命名：crash_{timestamp}_{id}.json（Java）或 crash_native_{timestamp}_{pid}.json（NDK）
    * 注意：排除 context 文件（.rum_crash_context）和临时文件
    */
-  override fun getPendingCrashes(promise: Promise) {
+  @ReactMethod
+  fun getPendingCrashes(promise: Promise) {
     try {
       val arr = JSONArray()
       if (crashDir.exists() && crashDir.isDirectory) {
@@ -244,7 +257,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
   /**
    * 解析 crashIds JSON array，按 crash_id 删除对应文件。
    */
-  override fun clearCrashReports(crashIds: String, promise: Promise) {
+  @ReactMethod
+  fun clearCrashReports(crashIds: String, promise: Promise) {
     try {
       val ids = HashSet<String>()
       if (crashIds.isNotEmpty()) {
@@ -307,7 +321,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
   }
 
   /** 上次运行是否发生过崩溃：crashDir 中存在崩溃报告文件即认为发生过 */
-  override fun crashedLastRun(promise: Promise) {
+  @ReactMethod
+  fun crashedLastRun(promise: Promise) {
     try {
       val crashed = crashDir.exists() &&
         (crashDir.listFiles()?.any { it.isFile && isCrashReportFile(it.name) } ?: false)
@@ -318,7 +333,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
   }
 
   /** 更新崩溃上下文快照（session/view 变更时调用） */
-  override fun updateCrashContext(context: String) {
+  @ReactMethod
+  fun updateCrashContext(context: String) {
     try {
       crashContextManager.updateContext(context)
     } catch (_: Throwable) {
@@ -327,7 +343,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
   }
 
   /** 清除所有崩溃报告文件（用于清理无 crash_id 的旧版 NDK 文件） */
-  override fun clearAllCrashReports(promise: Promise) {
+  @ReactMethod
+  fun clearAllCrashReports(promise: Promise) {
     try {
       if (crashDir.exists() && crashDir.isDirectory) {
         val files = crashDir.listFiles { f -> isCrashReportFile(f.name) }
@@ -346,7 +363,8 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
   }
 
   /** 清理过期和超限的崩溃文件 */
-  override fun cleanupOldCrashes(maxFiles: Double, maxAgeMs: Double, promise: Promise) {
+  @ReactMethod
+  fun cleanupOldCrashes(maxFiles: Double, maxAgeMs: Double, promise: Promise) {
     try {
       if (!crashDir.exists() || !crashDir.isDirectory) {
         promise.resolve(null)
@@ -422,11 +440,46 @@ class RumSdkReactnativeModule(reactContext: ReactApplicationContext) :
 
   // endregion
 
+  // region OOM (iOS-only watchdog termination, no-op on Android)
+
+  /**
+   * Android 无 OOM（看门狗终止推断）能力（D2）：Java OutOfMemoryError
+   * 已由 CrashHandler 崩溃链路捕获，系统低内存杀进程检测不在本期范围。
+   * 空实现仅为满足 TurboModule Spec 双端对齐。
+   */
+  @ReactMethod
+  fun getPendingOomReports(promise: Promise) {
+    try {
+      promise.resolve("[]")
+    } catch (e: Throwable) {
+      promise.reject(ERR_CRASH, e)
+    }
+  }
+
+  /** 清除 OOM 报告文件：Android 无 OOM 文件，no-op */
+  @ReactMethod
+  fun clearOomReports(oomIds: String, promise: Promise) {
+    try {
+      promise.resolve(null)
+    } catch (e: Throwable) {
+      promise.reject(ERR_CRASH, e)
+    }
+  }
+
+  /** 同步 JS 侧采集器配置（如 oom 开关）：Android 无 OOM 能力，接受但忽略 */
+  @ReactMethod
+  fun updateCollectorsConfig(config: String) {
+    // no-op
+  }
+
+  // endregion
+
   // region Test Crash
 
   private external fun nativeTriggerCrash(type: Int)
 
-  override fun triggerTestCrash(crashType: String) {
+  @ReactMethod
+  fun triggerTestCrash(crashType: String) {
     when (crashType) {
       // TurboModule 架构下，@ReactMethod void 方法中抛出的 Java 异常会被 C++ 层
       // 拦截并转换为 JS 异常，不会到达 Thread.getDefaultUncaughtExceptionHandler()。

package/android/src/main/java/com/rumsdkreactnative/RumSdkReactnativePackage.kt

@@ -1,13 +1,17 @@
 package com.rumsdkreactnative
 
-import com.facebook.react.BaseReactPackage
+// 基类用 TurboReactPackage 而非 BaseReactPackage（见 dev-docs/RN 0.68-0.70 兼容性打通方案
+// 方案 A4）：BaseReactPackage 为 RN 0.74 新增类，RN 0.68-0.73 宿主下编译失败；
+// TurboReactPackage 自 RN 0.68 起存在（0.76+ 标记 deprecated 但仍可用，仅为警告）。
+// 两者抽象方法签名一致（getModule / getReactModuleInfoProvider）。
+import com.facebook.react.TurboReactPackage
 import com.facebook.react.bridge.NativeModule
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.module.model.ReactModuleInfo
 import com.facebook.react.module.model.ReactModuleInfoProvider
 import java.util.HashMap
 
-class RumSdkReactnativePackage : BaseReactPackage() {
+class RumSdkReactnativePackage : TurboReactPackage() {
   override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
     return if (name == RumSdkReactnativeModule.NAME) {
       RumSdkReactnativeModule(reactContext)
@@ -19,11 +23,14 @@ class RumSdkReactnativePackage : BaseReactPackage() {
   override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
     return ReactModuleInfoProvider {
       val moduleInfos: MutableMap<String, ReactModuleInfo> = HashMap()
+      // 7 参构造（含 hasConstants）：RN ≤0.72 仅提供此签名；0.73+ 保留为 deprecated
+      // 兼容构造（hasConstants 被忽略），故 0.68-0.79+ 全版本可编译。模块无 constants，传 false。
       moduleInfos[RumSdkReactnativeModule.NAME] = ReactModuleInfo(
         RumSdkReactnativeModule.NAME,
         RumSdkReactnativeModule.NAME,
         false,  // canOverrideExistingModule
         false,  // needsEagerInit
+        false,  // hasConstants（RN ≤0.72 必填，0.73+ 忽略）
         false,  // isCxxModule
         true // isTurboModule
       )

package/docs/ReactNative SDK/351/205/215/347/275/256/345/217/202/350/200/203.md"

@@ -104,6 +104,7 @@ Collector是RUM SDK用于收集React Native应用监控数据的最小单元。
 | api | boolean \| object | 监听API请求（XMLHttpRequest / fetch） | 否 | true |
 | jsError | boolean \| object | 监听JS错误 | 否 | true |
 | consoleError | boolean \| object | 监听Console错误 | 否 | true |
+| oom | boolean | OOM（iOS看门狗终止推断）采集，详细说明请参见[oom配置](#oom-配置) | 否 | false |
 
 ### 示例
 
@@ -131,6 +132,30 @@ armsRum.init({
 });
 ```
 
+## oom 配置
+
+iOS看门狗终止（Watchdog Termination / FOOM，前台 OOM）的事后推断采集。App在前台被系统看门狗终止时无任何信号可捕获，表现为无提示"闪退"，现有崩溃管线天然采集不到；开启本能力后，SDK在运行期持续持久化 App 状态快照，下次冷启动时用排除法推断上次是否发生看门狗终止，并通过标准 exception 事件链路上报（`type='crash'` + `subtype='oom'`，name 为 `WatchdogTermination`）。
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  collectors: {
+    oom: true,
+  },
+});
+```
+
+**能力范围与限制**：
+
+- 仅支持 iOS，且仅覆盖**前台激活状态**被杀的推断（后台被杀不判定不上报）；Android 无此能力（Java `OutOfMemoryError` 已由崩溃采集链路捕获）
+- 启发式推断存在精度上限：无堆栈（`stack` 为空），`timestamp` 为估算值，事件通过 `snapshots.estimated: true` 结构化标记推断性质
+- 每次启动最多上报 1 条 OOM 事件；首次安装后被杀、调试器附加期间被杀、设备重启等场景不判定（业界同类能力同款排除条件）
+- 判定依据为上次会话持久化的状态快照，需重新构建原生 App（如 `expo run:ios` / `pod install` + 重新编译）后生效
+
+> **注意**：
+> - `oom` 默认为 `false`，需显式开启（`oom: true`）；其开关方向与崩溃采集相反（崩溃采集默认开启，配置 `crash: false` 才关闭）。
+> - 建议与崩溃采集同时开启（保持 `crash` 默认开启即可）。崩溃采集关闭时，原生崩溃监控仍会安装、KSCrash 崩溃报告照常写入但不会被读取和清理；残留的陈旧报告会使紧跟崩溃之后的 OOM 判定让位崩溃链路（防双报，预期行为），整体方向保守——OOM 倾向被抑制（漏判方向），而非误报增多。
+
 ## tracing 链路追踪配置
 
 支持布尔值开关或详细配置对象：

package/docs/SDK /347/211/210/346/234/254/350/257/264/346/230/216.md"

@@ -4,6 +4,26 @@
 
 ## 版本列表
 
+### v0.1.4（2026年09月）
+
+iOS 看门狗终止（OOM）推断采集、RN 0.68-0.70 原生兼容打通与发布产物混淆修复。
+
+#### v0.1.4-beta.2（2026年09月23日）
+
+打通 RN 0.68-0.70 原生兼容。
+
+- iOS/Android 崩溃采集与 OOM 在低版本旧架构可用（Android 宿主需 Kotlin ≥1.8，详见接入文档前提条件）
+
+#### v0.1.4-beta.1（2026年09月23日）
+
+新增 iOS 看门狗终止（OOM）事后推断采集。
+
+- 新增 iOS OOM 采集，默认关闭需显式开启
+- 崩溃与 OOM 配置独立，判定互斥防双报
+- OOM 事件英文证据式表述，estimated 标记推断性质
+- 锁定 KSCrash 依赖版本
+- 修复发布流程，生产产物启用代码混淆压缩
+
 ### v0.1.3（2026年07月）
 
 原生崩溃采集安全加固与自监控系统集成。

package/docs//346/216/245/345/205/245ReactNative/345/272/224/347/224/250.md

@@ -22,7 +22,8 @@
 - Node.js >= 18
 - npm或yarn包管理工具
 - Android 构建：需安装 NDK 与 CMake（由宿主工程的 `ndkVersion` 决定，SDK 不强制特定版本）
-- iOS 构建：需 CocoaPods（用于拉取 `KSCrash` 崩溃采集依赖）
+  - **RN 0.68-0.70 的 Android 工程额外要求**：宿主 `android/build.gradle` 的 buildscript 需声明 `kotlin-gradle-plugin` classpath，且 Kotlin 版本 **≥ 1.8.0**（RN 0.70 模板默认 1.6.x，与 SDK 依赖的 kotlin-stdlib 1.8 metadata 不兼容，需手动提升）；AGP 7.2 及以下无需改动，SDK 构建脚本自动回退 AndroidManifest package 属性
+- iOS 构建：需 CocoaPods（用于拉取 `KSCrash` 崩溃采集依赖）；RN 0.68-0.70 无需额外配置，`pod install` 后自动走旧桥导出路径
 
 ### 安装步骤
 

package/ios/RumAppStateRecorder.h

@@ -0,0 +1,69 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * RumAppStateRecorder
+ *
+ * iOS 看门狗终止（OOM）事后推断采集（P1 阶段，方案见
+ * dev-docs/OOM采集调研与实施方案.md 4.2 节）。负责：
+ *   - 运行期持久化 App 状态快照（app_state.json）：生命周期通知驱动、仅状态变化时写
+ *   - 下次启动时按 10 项排除条件判定上次是否发生看门狗终止（判定逻辑纯函数化，见下）
+ *   - 判定通过时构造 oom_{timestamp}_{uuid}.json 事件文件，交由 JS 侧回捞上报
+ *     （原生落盘、JS 回捞，保持 Ack 删文件链路的可靠性）
+ *
+ * 与 RumCrashReporter 的职责边界：RumCrashReporter 管信号/崩溃（KSCrash），
+ * 本类管状态记录与 OOM 推断，不使用信号处理器、不与 KSCrash 冲突。
+ * 判定逻辑（RumWatchdogTerminationLogic）与本类同文件实现。
+ */
+@interface RumAppStateRecorder : NSObject
+
+/**
+ * 安装 OOM 采集（幂等，dispatch_once 保证判定只执行一次）。
+ *
+ * 驱动方：RumSdkReactnative.updateCollectorsConfig——JS 侧 OomCollector 在
+ * SDK init 且 collectors.oom === true 时调用 updateCollectorsConfig("{\"oom\":true}")
+ * 触发；未开启时本方法不会被调用：不安装 Recorder、不执行判定、不产生
+ * 任何 OOM 相关 I/O（D6 默认关闭）。
+ *
+ * 上次会话是否开启由 app_state.json 的存在性隐式承载（上次未开启则无快照，
+ * 判定条件①不通过，不会误判），无需独立的开关持久化。
+ */
++ (void)setup;
+
+/** 获取待上报的 OOM 事件（已解析为字典数组，逐文件处理，不一次性全量读入拼接） */
++ (NSArray<NSDictionary *> *)pendingOomReports;
+
+/** 按 oomId 删除已上报的 OOM 事件文件 */
++ (void)clearOomReportsWithIds:(NSArray<NSString *> *)oomIds;
+
+/**
+ * 看门狗终止判定（纯函数化：输入上次快照 + 当前环境 + 崩溃证据，输出是否判定，
+ * 便于后续经桥伪造输入测试或 XCTest）。
+ *
+ * 10 项排除条件全部满足才判定（方案 4.2.2，D5/D7 硬约束）：
+ *   ① 存在上次快照；② 非模拟器；③ appVersion 未变；④ osVersion 未变；
+ *   ⑤ systemBootTime 未变；⑥ vendorId 一致且非空；⑦ 上次非调试态；
+ *   ⑧ 上次非正常终止；⑨ 上次前台激活（D5 前台限定）；
+ *   ⑩ 上次运行内无崩溃证据（crashed_last_run.flag 不存在 且 KSCrash reportStore
+ *      无晚于上次快照 updatedAt 的 pending 报告——时间范围限定排除陈旧报告，
+ *      D7 判定层互斥）。
+ *
+ * @param previousState      上次会话的 app_state.json 快照（不存在时传 nil）
+ * @param currentState       本次会话采集的当前环境快照
+ * @param flagExists         crashed_last_run.flag 是否存在
+ * @param hasPendingReports  上次运行内是否存在待处理崩溃报告（调用方对 KSCrash
+ *                           pending 报告施加时间范围限定后传入：仅最新报告时间戳
+ *                           晚于上次快照 updatedAt 时为 YES，陈旧报告不计入）
+ * @param isSimulator        是否运行在模拟器（生产路径由 TARGET_OS_SIMULATOR
+ *                           编译宏求值；参数化便于模拟器上运行的测试伪造真机分支）
+ */
++ (BOOL)evaluateWatchdogTerminationFromPreviousState:(nullable NSDictionary *)previousState
+                                         currentState:(NSDictionary *)currentState
+                                crashedLastRunFlagExists:(BOOL)flagExists
+                                   hasPendingCrashReports:(BOOL)hasPendingReports
+                                      runningOnSimulator:(BOOL)isSimulator;
+
+@end
+
+NS_ASSUME_NONNULL_END