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

package/ios/RumAppStateRecorder.mm

@@ -0,0 +1,547 @@
+#import "RumAppStateRecorder.h"
+#import "RumCrashReporter.h"
+
+#import <UIKit/UIKit.h>
+#import <sys/sysctl.h>
+#import <sys/utsname.h>
+
+#pragma mark - Constants
+
+/** 状态文件与 OOM 事件文件命名（与 context.json / crashed_last_run.flag 同目录） */
+static NSString *const kRumAppStateFileName = @"app_state.json";
+static NSString *const kRumOomFilePrefix = @"oom_";
+static NSString *const kRumOomFileSuffix = @".json";
+
+/** OOM 事件固定文案（D8：英文证据式表述，推断性质由 JS 侧 snapshots.estimated 承载） */
+static NSString *const kRumOomEventMessage =
+    @"App was killed while active with no crash report (suspected watchdog termination)";
+
+/** OOM 事件 context 字段仅透传 crash context 的四个关联键（排除开关等其他键） */
+static NSArray<NSString *> *const kRumOomContextKeys =
+    @[ @"session_id", @"view_id", @"view_name", @"user_id" ];
+
+#pragma mark - Helpers
+
+/** nil 安全的字符串相等比较（任一非字符串视为不等，保守不判定） */
+static BOOL RumStringEqual(id a, id b) {
+    if (![a isKindOfClass:[NSString class]] || ![b isKindOfClass:[NSString class]]) {
+        return NO;
+    }
+    return [(NSString *)a isEqualToString:(NSString *)b];
+}
+
+/** 从字典安全取布尔值（非 NSNumber 视为 NO） */
+static BOOL RumBoolValue(NSDictionary *dict, NSString *key) {
+    id value = dict[key];
+    return [value isKindOfClass:[NSNumber class]] ? [(NSNumber *)value boolValue] : NO;
+}
+
+@implementation RumAppStateRecorder {
+    /** 上次持久化的状态快照（内存缓存，仅状态变化时写盘；仅在主线程访问——
+        生命周期通知在主线程、bootstrap 的 start 经主队列 async 收敛，见 bootstrap） */
+    NSDictionary *_lastPersistedState;
+    /** 生命周期通知是否已订阅（防重复） */
+    BOOL _observingLifecycle;
+}
+
+#pragma mark - Setup（判定 + 启动）
+
++ (void)setup {
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        [[self sharedRecorder] bootstrap];
+    });
+}
+
+- (void)bootstrap {
+    @try {
+        // 0. crash context 快照：OOM 事件 context 字段的恢复来源。读的是上次会话
+        //    落盘的 context.json——bridge 队列 FIFO 保证本次会话的 updateCrashContext
+        //    尚未执行；缺失时事件 context 为空对象，事件仍落盘。开关门控不在本层：
+        //    setup 由 RumSdkReactnative.updateCollectorsConfig 驱动（JS 侧仅在
+        //    collectors.oom === true 时调用），未开启时本方法不会被调用。
+        NSDictionary *context = [RumCrashReporter currentCrashContext];
+
+        // 1. 上次快照与文件 mtime（timestamp 估算依据，必须在覆写本次状态之前读取）
+        NSString *statePath = [self appStatePath];
+        NSDictionary *previousState = [[self class] readStateJSONFileAtPath:statePath];
+        long long stateMtimeMs = [self fileMtimeMsAtPath:statePath];
+        long long contextMtimeMs = [self fileMtimeMsAtPath:[RumCrashReporter contextPath]];
+
+        // 2. 采集本次环境快照（appVersion / osVersion / systemBootTime / vendorId 比对基准）
+        NSDictionary *currentState = [self collectCurrentState];
+
+        // 3. 崩溃证据检查（判定顺序：先完成 pending crash 检查，再执行 OOM 判定——
+        //    方案 4.4 去重原则第 2 条；flag 与 pending 报告任一存在即让位 crash 链路，D7）
+        BOOL flagExists = [RumCrashReporter crashedLastRunFlagExists];
+        // 条件⑩时间范围限定：pending 报告仅当最新时间戳晚于上次快照 updatedAt（上次
+        //    运行最后一次状态写入）时视为"上次运行内的崩溃"而抑制判定；早于该时间的
+        //    陈旧报告（离线堆积、crash 关闭时遗留——crash 关闭时 KSCrash 报告只写
+        //    不删，唯一清理入口在 CrashCollector.setup 链内）不抑制。基准不可得时
+        //    退化为原语义（任一 pending 报告即抑制，保守兜底）。
+        long long lastStateUpdatedAtMs = 0;
+        id lastUpdatedAt = previousState[@"updatedAt"];
+        if ([lastUpdatedAt isKindOfClass:[NSNumber class]]) {
+            lastStateUpdatedAtMs = [(NSNumber *)lastUpdatedAt longLongValue];
+        }
+        BOOL hasPendingReports = lastStateUpdatedAtMs > 0
+            ? [RumCrashReporter hasPendingCrashReportsAfterEpochMs:lastStateUpdatedAtMs]
+            : [RumCrashReporter hasPendingCrashReports];
+
+        // 4. 10 项排除条件判定（②的模拟器标志由编译宏求值，参数化便于测试伪造）
+#if TARGET_OS_SIMULATOR
+        BOOL isSimulator = YES;
+#else
+        BOOL isSimulator = NO;
+#endif
+        BOOL isWatchdogTermination =
+            [[self class] evaluateWatchdogTerminationFromPreviousState:previousState
+                                                          currentState:currentState
+                                                 crashedLastRunFlagExists:flagExists
+                                                    hasPendingCrashReports:hasPendingReports
+                                                       runningOnSimulator:isSimulator];
+
+        // 5. 判定通过 → 构造事件落盘 oom_{timestamp}_{uuid}.json（原生落盘、JS 回捞，
+        //    每次启动最多 1 条事件）
+        if (isWatchdogTermination) {
+            [self writeOomEventWithPreviousState:previousState
+                                    crashContext:context
+                                stateFileMtimeMs:stateMtimeMs
+                             contextFileMtimeMs:contextMtimeMs];
+        }
+
+        // 6. 覆写本次会话的 app_state.json 并启动 Recorder（含 4.2.4 补丁）。
+        //    不清除 crashed_last_run.flag：flag 生命周期由 install 全权管理——install
+        //    在同一进程内必然先于 bootstrap（updateCollectorsConfig 驱动）执行，判定
+        //    读到的恒为本启动 install 刚按 KSCrash.crashedLastLaunch 重写/删除的新鲜
+        //    值，不存在"上上次崩溃残留到判定时刻"的路径（T-4 复核结论）；反之此处
+        //    清除会让 crashedLastRun 回退 KSCrash 状态，破坏 JS 侧查询契约。
+        //    状态写入与 _lastPersistedState 读写统一收敛到主队列：生命周期通知在主
+        //    线程读写该缓存，而 bootstrap 在 TurboModule method queue 执行，跨线程
+        //    无同步会引入竞争。此处 async 派发（避免 dispatch_sync 主线程的敏感
+        //    模式）；判定读上次快照与写事件文件本身留在当前队列，无共享状态。
+        if ([NSThread isMainThread]) {
+            [self start];
+        } else {
+            dispatch_async(dispatch_get_main_queue(), ^{
+                @try {
+                    [self start];
+                } @catch (NSException *e) {
+                    NSLog(@"[RumAppStateRecorder] start exception: %@", e);
+                }
+            });
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumAppStateRecorder] setup exception: %@", e);
+    }
+}
+
+#pragma mark - 判定逻辑（RumWatchdogTerminationLogic，纯函数）
+
++ (BOOL)evaluateWatchdogTerminationFromPreviousState:(nullable NSDictionary *)previousState
+                                         currentState:(NSDictionary *)currentState
+                                crashedLastRunFlagExists:(BOOL)flagExists
+                                   hasPendingCrashReports:(BOOL)hasPendingReports
+                                      runningOnSimulator:(BOOL)isSimulator
+{
+    // ① 存在上次快照（首次安装 / RN 初始化前的早期启动被杀 → 漏报，接受）
+    if (![previousState isKindOfClass:[NSDictionary class]]) {
+        return NO;
+    }
+    if (![currentState isKindOfClass:[NSDictionary class]]) {
+        return NO;
+    }
+    // ② 非模拟器（模拟器频繁启停误报，TARGET_OS_SIMULATOR 编译宏）
+    if (isSimulator) {
+        return NO;
+    }
+    // ③ appVersion 未变（App 升级覆盖排除）
+    if (!RumStringEqual(previousState[@"appVersion"], currentState[@"appVersion"])) {
+        return NO;
+    }
+    // ④ osVersion 未变（系统 OTA 升级排除）
+    if (!RumStringEqual(previousState[@"osVersion"], currentState[@"osVersion"])) {
+        return NO;
+    }
+    // ⑤ systemBootTime 未变（设备重启/关机排除）
+    if (!RumStringEqual(previousState[@"systemBootTime"], currentState[@"systemBootTime"])) {
+        return NO;
+    }
+    // ⑥ vendorId 一致且非空（重装/换包排除；空值不可信，保守不判定）
+    if (!RumStringEqual(previousState[@"vendorId"], currentState[@"vendorId"])) {
+        return NO;
+    }
+    if ([currentState[@"vendorId"] length] == 0) {
+        return NO;
+    }
+    // ⑦ 上次未附加调试器（Xcode 重启进程排除）
+    if (RumBoolValue(previousState, @"isDebugging")) {
+        return NO;
+    }
+    // ⑧ 上次非正常终止（用户上滑强杀/系统正常终止排除）
+    if (RumBoolValue(previousState, @"wasTerminated")) {
+        return NO;
+    }
+    // ⑨ 上次前台激活（D5：后台被杀不判定、不上报）
+    if (!RumBoolValue(previousState, @"isActive")) {
+        return NO;
+    }
+    // ⑩ 上次运行内没有产生崩溃（flag 与 KSCrash pending 报告任一存在即让位 crash
+    //    链路，D7 判定层互斥——flag 覆盖 KSCrash 状态被 JS 清理重置的边界，pending
+    //    报告覆盖崩溃发生但 flag 未及写入的场景；调用方对 pending 报告施加时间范围
+    //    限定，仅"上次运行内"的崩溃才计入，陈旧报告不抑制）
+    if (flagExists || hasPendingReports) {
+        return NO;
+    }
+    return YES;
+}
+
+#pragma mark - 状态采集
+
+/** 采集当前环境快照（8 字段，方案 4.2.1） */
+- (NSDictionary *)collectCurrentState {
+    NSBundle *bundle = [NSBundle mainBundle];
+    NSString *shortVersion =
+        [bundle objectForInfoDictionaryKey:@"CFBundleShortVersionString"] ?: @"";
+    NSString *buildNumber = [bundle objectForInfoDictionaryKey:@"CFBundleVersion"] ?: @"";
+    NSString *appVersion = shortVersion.length > 0
+        ? [NSString stringWithFormat:@"%@ (%@)", shortVersion, buildNumber]
+        : buildNumber;
+
+    UIDevice *device = [UIDevice currentDevice];
+
+    return @{
+        @"appVersion": appVersion,
+        @"osVersion": device.systemVersion ?: @"",
+        @"systemBootTime": [self currentSystemBootTimeISO8601],
+        @"vendorId": device.identifierForVendor.UUIDString ?: @"",
+        // 4.2.4 混合 SDK 适配补丁：主动查询当前 applicationState 补记激活状态——
+        // RN 延迟初始化会错过系统 DidBecomeActive 通知，而 isActive 恰是判定条件⑨
+        // 的依据，缺失会导致判定全错（Sentry #2326 同款问题的更直接解法）
+        @"isActive": @([self currentApplicationState] == UIApplicationStateActive),
+        @"wasTerminated": @NO,
+        @"isDebugging": @([self isDebuggerAttached]),
+        @"updatedAt": @((long long)([[NSDate date] timeIntervalSince1970] * 1000)),
+    };
+}
+
+/**
+ * systemBootTime：NSProcessInfo.systemUptime 换算为系统启动时刻的 ISO8601（UTC，毫秒）。
+ * 已知局限（对齐竞品同款换算）：systemUptime 不含睡眠时间，跨睡眠后本次换算值与
+ * 上次快照不一致 → 不判定（保守方向的漏报，可接受）。
+ */
+- (NSString *)currentSystemBootTimeISO8601 {
+    NSTimeInterval uptime = [NSProcessInfo processInfo].systemUptime;
+    NSDate *bootDate = [NSDate dateWithTimeIntervalSinceNow:-uptime];
+    static NSDateFormatter *formatter = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        formatter = [[NSDateFormatter alloc] init];
+        formatter.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
+        formatter.timeZone = [NSTimeZone timeZoneWithAbbreviation:@"UTC"];
+        formatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ss.SSS'Z'";
+    });
+    return [formatter stringFromDate:bootDate] ?: @"";
+}
+
+/** sysctl 查 P_TRACED：当前进程是否附加了调试器（Apple QA1361 标准做法） */
+- (BOOL)isDebuggerAttached {
+    int name[4] = {CTL_KERN, KERN_PROC, KERN_PROC_PID, getpid()};
+    struct kinfo_proc info;
+    memset(&info, 0, sizeof(info));
+    size_t size = sizeof(info);
+    if (sysctl(name, 4, &info, &size, NULL, 0) != 0) {
+        return NO;
+    }
+    // Darwin 的 kinfo_proc 字段为 kp_proc（FreeBSD 为 ki_proc，勿混淆）
+    return (info.kp_proc.p_flag & P_TRACED) != 0;
+}
+
+/** 当前 applicationState（UIApplication 属性要求主线程访问：主线程直读，否则同步切主线程） */
+- (UIApplicationState)currentApplicationState {
+    if ([NSThread isMainThread]) {
+        return [UIApplication sharedApplication].applicationState;
+    }
+    __block UIApplicationState state = UIApplicationStateInactive;
+    dispatch_sync(dispatch_get_main_queue(), ^{
+        state = [UIApplication sharedApplication].applicationState;
+    });
+    return state;
+}
+
+#pragma mark - 事件构造与落盘
+
+- (void)writeOomEventWithPreviousState:(NSDictionary *)previousState
+                           crashContext:(NSDictionary *)crashContext
+                       stateFileMtimeMs:(long long)stateMtimeMs
+                    contextFileMtimeMs:(long long)contextMtimeMs
+{
+    // timestamp 估算：上次会话最后写入的持久化文件 mtime（Datadog
+    // mostRecentModifiedFileAt 思路，方案 4.2.3），代表"进程最后存活的已知时刻"；
+    // 均不可得时退化为当前时间
+    long long timestamp = MAX(stateMtimeMs, contextMtimeMs);
+    if (timestamp <= 0) {
+        timestamp = (long long)([[NSDate date] timeIntervalSince1970] * 1000);
+    }
+
+    NSString *oomId = [[NSUUID UUID] UUIDString];
+
+    // context 恢复：从 context.json 仅提取四个关联键（缺失时为空对象，事件仍落盘，
+    // session_id 为空交由 rum-core dispatchEvents 处理，与 NDK context 断裂兜底一致）
+    NSMutableDictionary *eventContext = [NSMutableDictionary dictionary];
+    for (NSString *key in kRumOomContextKeys) {
+        id value = crashContext[key];
+        if ([value isKindOfClass:[NSString class]]) {
+            eventContext[key] = value;
+        }
+    }
+
+    // app / device：参照现有崩溃报告 normalizeKSCrashReport 的构造方式
+    struct utsname systemInfo;
+    uname(&systemInfo);
+    NSString *machine = [NSString stringWithCString:systemInfo.machine
+                                            encoding:NSUTF8StringEncoding] ?: @"";
+    NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier] ?: @"";
+    NSString *shortVersion = [[NSBundle mainBundle]
+        objectForInfoDictionaryKey:@"CFBundleShortVersionString"] ?: @"";
+
+    // 事件结构：与 JS 侧契约逐字一致（oom_id / timestamp / platform / subtype / name /
+    // message / mechanism / app_state / context / app / device）
+    NSDictionary *event = @{
+        @"oom_id": oomId,
+        @"timestamp": @(timestamp),
+        @"platform": @"ios",
+        @"subtype": @"oom",
+        @"name": @"WatchdogTermination",
+        @"message": kRumOomEventMessage,
+        @"mechanism": @{ @"type": @"watchdog_termination", @"handled": @NO },
+        @"app_state": previousState ?: @{},
+        @"context": eventContext,
+        @"app": @{ @"version": shortVersion, @"package": bundleId },
+        @"device": @{ @"model": machine, @"brand": @"apple" },
+    };
+
+    // 落盘 oom_{timestamp}_{uuid}.json（oom_id 与文件名 uuid 同源；删除时按内容匹配）
+    NSString *fileName = [NSString stringWithFormat:@"oom_%lld_%@.json", timestamp, oomId];
+    NSString *path = [[RumCrashReporter crashDir] stringByAppendingPathComponent:fileName];
+    [RumCrashReporter atomicWriteJSONObject:event toPath:path];
+}
+
+#pragma mark - Recorder 启动与生命周期通知
+
+- (void)start {
+    // start 时同步写一次快照（无条件覆写：上次快照已被判定消费，本次会话从此刻记录）
+    [self persistState:[self collectCurrentState]];
+    [self startObservingLifecycle];
+}
+
+- (void)startObservingLifecycle {
+    if (_observingLifecycle) {
+        return;
+    }
+    _observingLifecycle = YES;
+    NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
+    [nc addObserver:self
+           selector:@selector(handleDidBecomeActive:)
+               name:UIApplicationDidBecomeActiveNotification
+             object:nil];
+    [nc addObserver:self
+           selector:@selector(handleWillResignActive:)
+               name:UIApplicationWillResignActiveNotification
+             object:nil];
+    [nc addObserver:self
+           selector:@selector(handleDidEnterBackground:)
+               name:UIApplicationDidEnterBackgroundNotification
+             object:nil];
+    [nc addObserver:self
+           selector:@selector(handleWillEnterForeground:)
+               name:UIApplicationWillEnterForegroundNotification
+             object:nil];
+    [nc addObserver:self
+           selector:@selector(handleWillTerminate:)
+               name:UIApplicationWillTerminateNotification
+             object:nil];
+}
+
+- (void)handleDidBecomeActive:(NSNotification *)notification {
+    [self updateStateWithBlock:^(NSMutableDictionary *state) {
+        state[@"isActive"] = @YES;
+    }];
+}
+
+- (void)handleWillResignActive:(NSNotification *)notification {
+    [self updateStateWithBlock:^(NSMutableDictionary *state) {
+        state[@"isActive"] = @NO;
+    }];
+}
+
+- (void)handleDidEnterBackground:(NSNotification *)notification {
+    [self updateStateWithBlock:^(NSMutableDictionary *state) {
+        state[@"isActive"] = @NO;
+    }];
+}
+
+- (void)handleWillEnterForeground:(NSNotification *)notification {
+    // 前台过渡期 app 尚未 active（inactive 态），等 DidBecomeActive 再置 YES；
+    // 过渡窗口内被杀则不判定（前后台切换中归因不可靠）
+    [self updateStateWithBlock:^(NSMutableDictionary *state) {
+        state[@"isActive"] = @NO;
+    }];
+}
+
+- (void)handleWillTerminate:(NSNotification *)notification {
+    // 用户上滑强杀 / 系统正常终止：置 wasTerminated=true 后落盘（判定条件⑧的排除依据）
+    [self updateStateWithBlock:^(NSMutableDictionary *state) {
+        state[@"wasTerminated"] = @YES;
+    }];
+}
+
+/** 通知驱动的状态变更：刷新 updatedAt 与 isDebugging 后仅在与上次持久化快照语义不同才写盘 */
+- (void)updateStateWithBlock:(void (^)(NSMutableDictionary *state))block {
+    NSMutableDictionary *state = [_lastPersistedState mutableCopy];
+    if (state == nil) {
+        // 内存缓存缺失（异常路径）：重新采集，避免丢字段
+        state = [[self collectCurrentState] mutableCopy];
+    }
+    if (state == nil) {
+        return;
+    }
+    block(state);
+    // 重采样 isDebugging：会话启动时仅采样一次，会话中途 attach 调试器若不刷新，
+    // 判定条件⑦会在下次启动误排除（sysctl 查 P_TRACED 开销极低，Sentry/Datadog
+    // 同款做法）
+    state[@"isDebugging"] = @([self isDebuggerAttached]);
+    state[@"updatedAt"] = @((long long)([[NSDate date] timeIntervalSince1970] * 1000));
+    [self persistStateIfChanged:state];
+}
+
+- (void)persistState:(NSDictionary *)state {
+    _lastPersistedState = [state copy];
+    [RumCrashReporter atomicWriteJSONObject:state toPath:[self appStatePath]];
+}
+
+- (void)persistStateIfChanged:(NSDictionary *)state {
+    // 写入开销控制：仅状态变化时写（updatedAt 只是写入时间戳，不计入语义比对）
+    if ([self isStateSemanticallyEqualToLastPersisted:state]) {
+        return;
+    }
+    [self persistState:state];
+}
+
+- (BOOL)isStateSemanticallyEqualToLastPersisted:(NSDictionary *)state {
+    if (_lastPersistedState.count != state.count) {
+        return NO;
+    }
+    NSMutableDictionary *last = [_lastPersistedState mutableCopy];
+    NSMutableDictionary *next = [state mutableCopy];
+    [last removeObjectForKey:@"updatedAt"];
+    [next removeObjectForKey:@"updatedAt"];
+    return [last isEqualToDictionary:next];
+}
+
+#pragma mark - Pending OOM reports（供 JS 回捞，T-8 逐文件处理）
+
++ (NSArray<NSDictionary *> *)pendingOomReports {
+    NSMutableArray<NSDictionary *> *result = [NSMutableArray array];
+    @try {
+        NSFileManager *fm = [NSFileManager defaultManager];
+        NSString *dir = [RumCrashReporter crashDir];
+        NSArray<NSString *> *files = [fm contentsOfDirectoryAtPath:dir error:nil] ?: @[];
+        for (NSString *file in files) {
+            // 文件过滤器限定 oom_ 前缀 + .json 后缀，与 context.json /
+            // app_state.json / crashed_last_run.flag 互不干扰
+            if (![file hasPrefix:kRumOomFilePrefix] || ![file hasSuffix:kRumOomFileSuffix]) {
+                continue;
+            }
+            @autoreleasepool {
+                NSString *path = [dir stringByAppendingPathComponent:file];
+                NSDictionary *event = [[self class] readStateJSONFileAtPath:path];
+                if ([event isKindOfClass:[NSDictionary class]]) {
+                    [result addObject:event];
+                } else {
+                    // 损坏文件：删除防止每次启动重复尝试解析（OOM 文件每次启动最多
+                    // 新增 1 个、ack 后删除，天然不堆积，无需独立 cleanup——方案 R3）
+                    [fm removeItemAtPath:path error:nil];
+                }
+            }
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumAppStateRecorder] pendingOomReports exception: %@", e);
+    }
+    return result;
+}
+
++ (void)clearOomReportsWithIds:(NSArray<NSString *> *)oomIds {
+    if (oomIds.count == 0) {
+        return;
+    }
+    NSMutableSet<NSString *> *idSet = [NSMutableSet set];
+    for (NSString *oomId in oomIds) {
+        if ([oomId isKindOfClass:[NSString class]] && oomId.length > 0) {
+            [idSet addObject:oomId];
+        }
+    }
+    if (idSet.count == 0) {
+        return;
+    }
+    @try {
+        NSFileManager *fm = [NSFileManager defaultManager];
+        NSString *dir = [RumCrashReporter crashDir];
+        NSArray<NSString *> *files = [fm contentsOfDirectoryAtPath:dir error:nil] ?: @[];
+        for (NSString *file in files) {
+            if (![file hasPrefix:kRumOomFilePrefix] || ![file hasSuffix:kRumOomFileSuffix]) {
+                continue;
+            }
+            @autoreleasepool {
+                // 按文件内容中的 oom_id 匹配删除（与 clearCrashReportsWithIds
+                // 遍历读 report.id 匹配的模式一致，不依赖文件名解析）
+                NSString *path = [dir stringByAppendingPathComponent:file];
+                NSDictionary *event = [[self class] readStateJSONFileAtPath:path];
+                NSString *oomId = [event isKindOfClass:[NSDictionary class]]
+                    ? event[@"oom_id"]
+                    : nil;
+                if ([oomId isKindOfClass:[NSString class]] && [idSet containsObject:oomId]) {
+                    [fm removeItemAtPath:path error:nil];
+                }
+            }
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumAppStateRecorder] clearOomReports exception: %@", e);
+    }
+}
+
+#pragma mark - File IO
+
+- (NSString *)appStatePath {
+    return [[RumCrashReporter crashDir] stringByAppendingPathComponent:kRumAppStateFileName];
+}
+
++ (nullable NSDictionary *)readStateJSONFileAtPath:(NSString *)path {
+    id obj = [RumCrashReporter readJSONFileAtPath:path];
+    return [obj isKindOfClass:[NSDictionary class]] ? (NSDictionary *)obj : nil;
+}
+
+- (long long)fileMtimeMsAtPath:(NSString *)path {
+    NSDictionary<NSString *, id> *attrs =
+        [[NSFileManager defaultManager] attributesOfItemAtPath:path error:nil];
+    NSDate *modifiedDate = [attrs[NSFileModificationDate] isKindOfClass:[NSDate class]]
+        ? attrs[NSFileModificationDate]
+        : nil;
+    if (modifiedDate == nil) {
+        return 0;
+    }
+    return (long long)([modifiedDate timeIntervalSince1970] * 1000);
+}
+
+#pragma mark - Singleton
+
++ (instancetype)sharedRecorder {
+    static RumAppStateRecorder *shared = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        shared = [[RumAppStateRecorder alloc] init];
+    });
+    return shared;
+}
+
+@end

package/ios/RumCrashReporter.h

@@ -33,6 +33,38 @@ NS_ASSUME_NONNULL_BEGIN
 /** 更新 crash 上下文（JSON 字符串：session_id / view_id / view_name 等） */
 + (void)updateCrashContext:(NSString *)context;
 
+#pragma mark - OOM support（供 RumAppStateRecorder 复用）
+
+/** SDK 私有目录：<Library>/Caches/RumCrashReporter/（含旧目录 ARMSCrashReporter 迁移） */
++ (NSString *)crashDir;
+
+/** crash 上下文快照文件路径（<crashDir>/context.json） */
++ (NSString *)contextPath;
+
+/** 读取 JSON 文件（供 OOM 状态记录模块复用） */
++ (nullable id)readJSONFileAtPath:(NSString *)path;
+
+/** 原子写 JSON 文件（临时文件 + rename，供 OOM 状态记录模块复用） */
++ (void)atomicWriteJSONObject:(id)obj toPath:(NSString *)path;
+
+/** 读取当前持久化的 crash 上下文（context.json，缺失时返回空字典） */
++ (NSDictionary *)currentCrashContext;
+
+/** crashed_last_run.flag 是否存在（OOM 判定排除条件⑩的崩溃证据之一；生命周期由 install 全权管理——每次启动按 KSCrash.crashedLastLaunch 重写/删除，判定层只读不清除） */
++ (BOOL)crashedLastRunFlagExists;
+
+/** KSCrash reportStore 是否存在待处理崩溃报告（OOM 判定排除条件⑩的崩溃证据之一） */
++ (BOOL)hasPendingCrashReports;
+
+/**
+ * KSCrash reportStore 是否存在**晚于给定时刻**的待处理崩溃报告（条件⑩时间范围限定）：
+ * 仅当最新 pending 报告的时间戳晚于 epochMs（上次 app_state.json 的 updatedAt，即
+ * 上次运行最后一次状态写入）时视为"上次运行内的崩溃"返回 YES；早于该时间的陈旧报告
+ * （离线堆积、crash 关闭时遗留）返回 NO。时间戳不可得或比较异常时返回 YES（保守
+ * 兜底，维持抑制）；epochMs <= 0 时退化为"任一 pending 报告即抑制"（原语义）。
+ */
++ (BOOL)hasPendingCrashReportsAfterEpochMs:(long long)epochMs;
+
 @end
 
 NS_ASSUME_NONNULL_END