@npaw/forge-react-native 9.7.2 → 9.7.4

package/ios/ForgeApple/Sources/NPAWForgeAVPlayerAdapter/AVPlayerAdapter.swift

@@ -443,7 +443,13 @@ public final class AVPlayerAdapter: PlayerAdapter {
     private func handleRate(_ rate: Float) {
         if rate > 0 {
             // Direct rate manipulation is also a play intent (OLD plugin-ios
-            // fires start from rate observations).
+            // fires start from rate observations) - but only with an item to
+            // play. `play()` on an itemless player has nothing to start (the
+            // start is anchored when the item arrives: `handleItemTransition`
+            // re-reads the time control status), and a rate that survives
+            // `replaceCurrentItem(with: nil)` must not re-open the view the
+            // item transition has just stopped.
+            guard player?.currentItem != nil else { return }
             ensureStarted()
             return
         }
@@ -472,6 +478,21 @@ public final class AVPlayerAdapter: PlayerAdapter {
                 _ = firePause(metadata: snapshotMetadata())
             }
         case .waitingToPlayAtSpecifiedRate:
+            // A player that is only waiting because it has NO ITEM
+            // (`AVPlayer.WaitingReason.noItemToPlay`: `replaceCurrentItem(with:
+            // nil)` while `rate` is still non-zero) has nothing to start. That
+            // is exactly what react-native-video 7 does on teardown, right after
+            // the item transition above stopped the view: treating it as play
+            // intent re-opened the view the adapter had just stopped, and the
+            // `start` then sat in the metadata gate until the timeout flushed a
+            // phantom start with no item behind it (2026-08-16, iOS simulator).
+            // Any app that removes the item mid-playback reproduces it. The
+            // item check is deliberate: an item that has just been set is a
+            // real play intent even if AVFoundation still reports the stale
+            // no-item reason for it (`play()` before `replaceCurrentItem`).
+            if let player, player.reasonForWaitingToPlay == .noItemToPlay, player.currentItem == nil {
+                return
+            }
             // Waiting-to-play is the earliest observable play intent on a cold
             // start; anchoring `/start` here keeps the kernel-computed join
             // time spanning the real startup buffering (OLD plugin-ios join

package/ios/ForgeApple/Sources/NPAWForgeCore/DeviceInsightsCollector.swift

@@ -0,0 +1,494 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Apple device insights collector - answers the kernel's periodic device sample requests with process CPU time, memory footprint and headroom, battery (iOS only) and thermal state, reading only the families the operator allowed and never a required-reason API.
+ */
+import Foundation
+
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// Thermal pressure on the kernel's normalised ordinal scale (`dev_thermal`).
+///
+/// The raw values are the wire ordinals shared with Android, so a Suite
+/// filter on `dev_thermal=2` means "serious" on every platform.
+public enum ForgeThermalState: Int, Equatable, CaseIterable {
+    case nominal = 0
+    case fair = 1
+    case serious = 2
+    case critical = 3
+    /// The Android-only top of the scale (`THERMAL_STATUS_CRITICAL` and
+    /// above). `ProcessInfo.ThermalState` stops at `.critical`, so Forge on
+    /// Apple never produces it.
+    case emergency = 4
+
+    /// Maps `ProcessInfo.ThermalState`. A state Forge does not recognise maps
+    /// to `nil` - the metric is omitted rather than guessed. Note the API
+    /// itself reports `.nominal` where thermal state is unsupported (the
+    /// simulator, some hardware); Forge forwards that as the platform states it.
+    public static func from(_ state: ProcessInfo.ThermalState) -> ForgeThermalState? {
+        switch state {
+        case .nominal: return .nominal
+        case .fair: return .fair
+        case .serious: return .serious
+        case .critical: return .critical
+        @unknown default: return nil
+        }
+    }
+}
+
+/// One device runtime health sample as forwarded to the kernel.
+///
+/// Every metric field is optional and independently absent: what the platform
+/// cannot read is left `nil`, and the kernel then omits the metric instead of
+/// inventing `0`. The kernel validates field-wise (a battery level above 100,
+/// zero cores or a CPU counter that went backwards is dropped, the rest kept),
+/// derives `dev_cpu` between two consecutive samples, and attaches the set to
+/// the next session beat and video ping.
+public struct ForgeDeviceSample: Equatable {
+    /// Wall clock at read time, ms since the Unix epoch. `0` lets the bridge
+    /// stamp the call with its own clock.
+    public var sampledAtMs: Int64
+    /// Cumulative process CPU time, user + system, ms, monotonic over the
+    /// process lifetime. Must travel together with ``cpuCores`` for `dev_cpu`.
+    public var cpuTimeMs: UInt64?
+    /// Logical cores available to the process, `>= 1`.
+    public var cpuCores: UInt32?
+    /// Process memory footprint (`phys_footprint`), bytes.
+    public var memUsedBytes: UInt64?
+    /// Memory this process may still allocate before hitting its limit, bytes.
+    public var memAvailBytes: UInt64?
+    /// Battery level `0...100`.
+    public var batteryLevelPct: UInt8?
+    /// Whether the device is charging (plugged in, charging or full).
+    public var batteryCharging: Bool?
+    public var thermal: ForgeThermalState?
+    /// Free storage on the app's volume, bytes. **Never filled by Forge on
+    /// Apple**: every free-disk API (`volumeAvailableCapacity*`, `statfs`,
+    /// `systemFreeSize`, ...) is an Apple required-reason API and Forge ships
+    /// no privacy manifest. The field exists so a host application that does
+    /// declare the reason can supply the value itself through
+    /// `NPAWForge.recordDeviceSample(_:)`.
+    public var diskFreeBytes: UInt64?
+
+    public init(
+        sampledAtMs: Int64 = 0,
+        cpuTimeMs: UInt64? = nil,
+        cpuCores: UInt32? = nil,
+        memUsedBytes: UInt64? = nil,
+        memAvailBytes: UInt64? = nil,
+        batteryLevelPct: UInt8? = nil,
+        batteryCharging: Bool? = nil,
+        thermal: ForgeThermalState? = nil,
+        diskFreeBytes: UInt64? = nil
+    ) {
+        self.sampledAtMs = sampledAtMs
+        self.cpuTimeMs = cpuTimeMs
+        self.cpuCores = cpuCores
+        self.memUsedBytes = memUsedBytes
+        self.memAvailBytes = memAvailBytes
+        self.batteryLevelPct = batteryLevelPct
+        self.batteryCharging = batteryCharging
+        self.thermal = thermal
+        self.diskFreeBytes = diskFreeBytes
+    }
+
+    /// `true` when no metric field is present (only the timestamp).
+    public var isEmpty: Bool {
+        cpuTimeMs == nil && cpuCores == nil
+            && memUsedBytes == nil && memAvailBytes == nil
+            && batteryLevelPct == nil && batteryCharging == nil
+            && thermal == nil && diskFreeBytes == nil
+    }
+}
+
+/// The metric families an operator can allow (`di.m`), spelled as the wire
+/// tokens the kernel puts in a sample request.
+public enum ForgeDeviceMetricFamily: String, CaseIterable, Equatable {
+    case cpu
+    case mem
+    case bat
+    case thm
+    case disk
+}
+
+/// A battery reading exactly as the platform reports it, before shaping.
+struct ForgeBatteryReading: Equatable {
+    enum State: Equatable {
+        case unknown
+        case unplugged
+        case charging
+        case full
+    }
+
+    /// `UIDevice.batteryLevel`: `0...1`, negative when unknown.
+    var level: Float
+    var state: State
+}
+
+/// Arms and disarms the platform's battery monitoring, which is what makes
+/// `UIDevice.batteryLevel`/`batteryState` report anything at all.
+struct ForgeBatteryMonitoringControl {
+    var isEnabled: () -> Bool
+    var setEnabled: (Bool) -> Void
+}
+
+/// The platform reads the collector needs, injectable so the sample shaping is
+/// testable on the host Mac and so a test can prove which reads happen.
+///
+/// `battery` and `batteryMonitoring` are `nil` where the platform has no
+/// battery API: tvOS (`UIDevice`'s battery members are `API_UNAVAILABLE(tvos)`)
+/// and macOS.
+struct ForgeDeviceInsightsReaders {
+    var nowMs: () -> Int64
+    var cpuTimeMs: () -> UInt64?
+    var cpuCores: () -> UInt32?
+    var memUsedBytes: () -> UInt64?
+    var memAvailBytes: () -> UInt64?
+    var thermal: () -> ForgeThermalState?
+    var battery: (() -> ForgeBatteryReading?)?
+    var batteryMonitoring: ForgeBatteryMonitoringControl?
+
+    /// The real reads. Each one is either a plain Darwin/Foundation call or a
+    /// UIKit read, and none is on Apple's required-reason API list (file
+    /// timestamps, system boot time, disk space, active keyboards, user
+    /// defaults) - which is why Forge can collect these without shipping a
+    /// privacy manifest. In particular the timestamp comes from `Date()`, not
+    /// `systemUptime`/`mach_absolute_time`, and no free-disk API is called.
+    static let platform = ForgeDeviceInsightsReaders(
+        nowMs: { Int64(Date().timeIntervalSince1970 * 1000) },
+        cpuTimeMs: ForgeDeviceInsightsPlatform.processCpuTimeMs,
+        cpuCores: ForgeDeviceInsightsPlatform.activeProcessorCount,
+        memUsedBytes: ForgeDeviceInsightsPlatform.physicalFootprintBytes,
+        memAvailBytes: ForgeDeviceInsightsPlatform.availableMemoryBytes,
+        thermal: { ForgeThermalState.from(ProcessInfo.processInfo.thermalState) },
+        battery: ForgeDeviceInsightsPlatform.batteryReader,
+        batteryMonitoring: ForgeDeviceInsightsPlatform.batteryMonitoringControl
+    )
+}
+
+/// Answers the kernel's device sample requests.
+///
+/// The kernel schedules; this collector only reads. It reads exactly the
+/// families a request lists, on a utility queue, and forwards one
+/// ``ForgeDeviceSample`` per request through `publish`. It never reads free
+/// disk space (see ``ForgeDeviceSample/diskFreeBytes``), never reads battery
+/// where the platform has no battery API, and arms `UIDevice` battery
+/// monitoring only while the capture plan lists the `bat` family - restoring
+/// the previous state afterwards, and never touching monitoring the host app
+/// enabled itself.
+///
+/// Threading: every `UIDevice` touch happens on the sampling queue (which hops
+/// to the main thread synchronously). Nothing ever waits on the sampling
+/// queue - not `stop()`, not the runtime worker thread that delivers plans and
+/// requests - so the main-thread hop cannot close a cycle with a facade
+/// teardown or a kernel command in flight.
+final class ForgeDeviceInsightsCollector {
+    private let readers: ForgeDeviceInsightsReaders
+    private let queue: DispatchQueue
+    private let publish: (ForgeDeviceSample) -> Void
+    private let lock = NSLock()
+    private var active = true
+    /// Whether the plan currently asks for battery monitoring to be armed.
+    private var batteryWanted = false
+    /// Whether Forge (not the host app) is the one who enabled monitoring.
+    private var armedByForge = false
+
+    init(
+        readers: ForgeDeviceInsightsReaders = .platform,
+        queue: DispatchQueue = DispatchQueue(label: "com.npaw.forge.device-insights", qos: .utility),
+        publish: @escaping (ForgeDeviceSample) -> Void
+    ) {
+        self.readers = readers
+        self.queue = queue
+        self.publish = publish
+    }
+
+    /// Pre-arms or disarms the cheap observers a family needs from the capture
+    /// plan: battery monitoring iff the plan carries the device-insights bit
+    /// AND lists `bat`. Nothing here reads a metric - the request does.
+    ///
+    /// The plan arrives on the runtime's worker thread; the `UIDevice` work
+    /// hops to this collector's queue first, because that thread must never
+    /// wait on the main thread (a `destroy()` on main joins the worker).
+    func applyCapturePlan(_ plan: ForgeCapturePlan) {
+        let wanted = plan.isEnabled(ForgeCapturePlan.Bits.deviceInsights)
+            && plan.deviceInsightFamilies.contains(ForgeDeviceMetricFamily.bat.rawValue)
+        lock.lock()
+        guard active else {
+            lock.unlock()
+            return
+        }
+        batteryWanted = wanted
+        lock.unlock()
+        queue.async { [self] in
+            if wanted {
+                armBatteryMonitoringIfNeeded()
+            } else {
+                disarmBatteryMonitoringIfArmed()
+            }
+        }
+    }
+
+    /// Answers one kernel request. Unknown tokens are ignored (a newer Console
+    /// must never break sampling); `disk` is ignored on Apple by design.
+    func handleSampleRequest(_ families: [String]) {
+        let requested = Set(families.compactMap(ForgeDeviceMetricFamily.init(rawValue:)))
+        lock.lock()
+        let isActive = active
+        lock.unlock()
+        guard isActive, !requested.isEmpty else { return }
+        queue.async { [weak self] in
+            self?.sampleNow(requested)
+        }
+    }
+
+    /// Stops answering and returns battery monitoring to what it was. Safe to
+    /// call twice; never blocks on the sampling queue or the main thread, so it
+    /// can be called under a facade lock from any thread. The disarm runs on
+    /// the sampling queue and captures the control, not `self`, so it still
+    /// happens if the collector is released right after this call.
+    func stop() {
+        lock.lock()
+        let wasActive = active
+        active = false
+        batteryWanted = false
+        let disarm = armedByForge
+        armedByForge = false
+        lock.unlock()
+        guard wasActive, disarm, let control = readers.batteryMonitoring else { return }
+        queue.async {
+            control.setEnabled(false)
+        }
+    }
+
+    // MARK: - Sampling
+
+    private func sampleNow(_ requested: Set<ForgeDeviceMetricFamily>) {
+        var sample = ForgeDeviceSample(sampledAtMs: readers.nowMs())
+        if requested.contains(.cpu) {
+            // The two travel together or not at all: the kernel needs both to
+            // derive `dev_cpu`, and half a pair is a value nobody can use.
+            if let cpuTimeMs = readers.cpuTimeMs(), let cpuCores = readers.cpuCores() {
+                sample.cpuTimeMs = cpuTimeMs
+                sample.cpuCores = cpuCores
+            }
+        }
+        if requested.contains(.mem) {
+            sample.memUsedBytes = readers.memUsedBytes()
+            sample.memAvailBytes = readers.memAvailBytes()
+        }
+        if requested.contains(.thm) {
+            sample.thermal = readers.thermal()
+        }
+        if requested.contains(.bat), let reading = readBattery() {
+            let fields = Self.batteryFields(from: reading)
+            sample.batteryLevelPct = fields.levelPct
+            sample.batteryCharging = fields.charging
+        }
+        // `disk` is deliberately never read: see ForgeDeviceSample.diskFreeBytes.
+
+        lock.lock()
+        let isActive = active
+        lock.unlock()
+        // A sample with nothing in it would only cost an FFI hop; the kernel
+        // keeps its previous sample and the diff sends nothing either way.
+        guard isActive, !sample.isEmpty else { return }
+        publish(sample)
+    }
+
+    /// Reads the battery where the platform has one. A request that lists
+    /// `bat` before the plan arrived (the kernel's first request fires at
+    /// delay 0) arms monitoring on the spot, so the first reading is real.
+    private func readBattery() -> ForgeBatteryReading? {
+        guard let read = readers.battery else { return nil }
+        armBatteryMonitoringIfNeeded()
+        return read()
+    }
+
+    /// Shapes a raw reading into the wire fields, independently per field.
+    /// - level: `0...1` becomes `0...100` (rounded); anything else - UIKit
+    ///   reports `-1` while the state is unknown - is absent, never clamped
+    ///   into a fake reading.
+    /// - charging: `.charging`/`.full` → `true`, `.unplugged` → `false`,
+    ///   `.unknown` → absent.
+    static func batteryFields(from reading: ForgeBatteryReading) -> (levelPct: UInt8?, charging: Bool?) {
+        var levelPct: UInt8?
+        if reading.level >= 0, reading.level <= 1 {
+            levelPct = UInt8(min(100, max(0, (reading.level * 100).rounded())))
+        }
+        let charging: Bool?
+        switch reading.state {
+        case .charging, .full: charging = true
+        case .unplugged: charging = false
+        case .unknown: charging = nil
+        }
+        return (levelPct, charging)
+    }
+
+    // MARK: - Battery monitoring
+
+    private func armBatteryMonitoringIfNeeded() {
+        guard let control = readers.batteryMonitoring else { return }
+        lock.lock()
+        let shouldArm = active && !armedByForge
+        lock.unlock()
+        guard shouldArm else { return }
+        // Monitoring the host app already enabled is left alone, and is never
+        // disarmed by Forge later: `armedByForge` stays false.
+        if control.isEnabled() { return }
+        control.setEnabled(true)
+        lock.lock()
+        // `stop()` may have raced this arm; if so, undo it right away.
+        let undo = !active
+        armedByForge = !undo
+        lock.unlock()
+        if undo {
+            control.setEnabled(false)
+        }
+    }
+
+    private func disarmBatteryMonitoringIfArmed() {
+        guard let control = readers.batteryMonitoring else { return }
+        lock.lock()
+        let shouldDisarm = armedByForge && !batteryWanted
+        if shouldDisarm {
+            armedByForge = false
+        }
+        lock.unlock()
+        guard shouldDisarm else { return }
+        control.setEnabled(false)
+    }
+
+    /// Test seam: runs `body` after everything already queued on the sampling
+    /// queue - a plan applied or a `stop()` issued just before is settled.
+    func afterPendingWork(_ body: @escaping () -> Void) {
+        queue.async(execute: body)
+    }
+}
+
+/// The real Darwin/Foundation/UIKit reads behind ``ForgeDeviceInsightsReaders/platform``.
+///
+/// Verified against the Xcode 26.2 SDK headers (`mach/task_info.h`,
+/// `os/proc.h`, `_time.h`, `NSProcessInfo.h`, `UIKit/UIDevice.h`) - see
+/// docs/internal/device-insights.md for the review record.
+enum ForgeDeviceInsightsPlatform {
+    /// Cumulative process CPU time, user + system, from
+    /// `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)` (iOS 10 / tvOS 10 / macOS
+    /// 10.12+), which "tracks the amount of CPU (in user- or kernel-mode) used
+    /// by the calling process" across all its threads.
+    ///
+    /// NOT `task_info(TASK_BASIC_INFO)`: its `user_time`/`system_time` count
+    /// terminated threads only (the header says so, and a measurement showed
+    /// it stuck at 0 while a live thread burned 260 ms), so an app whose
+    /// threads live for the whole session would report no CPU at all.
+    static func processCpuTimeMs() -> UInt64? {
+        var spec = timespec()
+        guard clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &spec) == 0,
+              spec.tv_sec >= 0, spec.tv_nsec >= 0 else {
+            return nil
+        }
+        return UInt64(spec.tv_sec) * 1000 + UInt64(spec.tv_nsec) / 1_000_000
+    }
+
+    /// `ProcessInfo.activeProcessorCount` (iOS 2 / tvOS 9+): the logical
+    /// cores currently available to the process, which is what the kernel
+    /// divides the CPU delta by. `0` is not a core count and yields `nil`.
+    static func activeProcessorCount() -> UInt32? {
+        let count = ProcessInfo.processInfo.activeProcessorCount
+        return count >= 1 ? UInt32(clamping: count) : nil
+    }
+
+    /// `task_vm_info.phys_footprint` via `task_info(TASK_VM_INFO)`: the
+    /// number Xcode's memory gauge and the jetsam limit are measured against.
+    static func physicalFootprintBytes() -> UInt64? {
+        var info = task_vm_info_data_t()
+        let stride = MemoryLayout<natural_t>.size
+        var count = mach_msg_type_number_t(MemoryLayout<task_vm_info_data_t>.size / stride)
+        let result = withUnsafeMutablePointer(to: &info) { pointer in
+            pointer.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
+                task_info(mach_task_self_, task_flavor_t(TASK_VM_INFO), $0, &count)
+            }
+        }
+        guard result == KERN_SUCCESS else { return nil }
+        // The kernel reports how much of the struct it filled; `phys_footprint`
+        // is a rev1 field (present since iOS 9), but a shorter reply must not
+        // be read past its end.
+        guard let offset = MemoryLayout<task_vm_info_data_t>.offset(of: \task_vm_info_data_t.phys_footprint),
+              offset + MemoryLayout<mach_vm_size_t>.size <= Int(count) * stride else {
+            return nil
+        }
+        guard info.phys_footprint > 0 else { return nil }
+        return UInt64(info.phys_footprint)
+    }
+
+    /// `os_proc_available_memory()` (iOS 13 / tvOS 13+, unavailable on
+    /// macOS): "the number of bytes remaining, at the time of the call, before
+    /// the current process will hit its current dirty memory limit" - the
+    /// app's own headroom, not the device's free RAM. The header documents
+    /// `0` as "the calling process is not an app, or exceeds its memory
+    /// limit"; neither is a headroom worth reporting, so `0` is absent.
+    static func availableMemoryBytes() -> UInt64? {
+        #if os(iOS) || os(tvOS)
+        let bytes = os_proc_available_memory()
+        return bytes == 0 ? nil : UInt64(bytes)
+        #else
+        return nil
+        #endif
+    }
+
+    #if os(iOS)
+    /// `UIDevice.current.batteryLevel` / `batteryState`, read on the main
+    /// thread like every other `UIDevice` access. Both are
+    /// `API_UNAVAILABLE(tvos)`, hence the whole reader is iOS-only.
+    static let batteryReader: (() -> ForgeBatteryReading?)? = {
+        onMainThread {
+            let device = UIDevice.current
+            return ForgeBatteryReading(level: device.batteryLevel, state: batteryState(device.batteryState))
+        }
+    }
+
+    static let batteryMonitoringControl: ForgeBatteryMonitoringControl? = ForgeBatteryMonitoringControl(
+        isEnabled: { onMainThread { UIDevice.current.isBatteryMonitoringEnabled } },
+        setEnabled: { enabled in onMainThread { UIDevice.current.isBatteryMonitoringEnabled = enabled } }
+    )
+
+    private static func batteryState(_ state: UIDevice.BatteryState) -> ForgeBatteryReading.State {
+        switch state {
+        case .unknown: return .unknown
+        case .unplugged: return .unplugged
+        case .charging: return .charging
+        case .full: return .full
+        @unknown default: return .unknown
+        }
+    }
+
+    /// `UIDevice` is a main-actor object; the collector samples on a utility
+    /// queue, so the few battery reads hop to the main thread synchronously.
+    /// The collector never holds its lock across this hop and `stop()` never
+    /// waits on the sampling queue, so a main thread tearing Forge down cannot
+    /// deadlock against a sample in flight.
+    private static func onMainThread<T>(_ body: () -> T) -> T {
+        if Thread.isMainThread {
+            return body()
+        }
+        return DispatchQueue.main.sync(execute: body)
+    }
+    #else
+    /// tvOS has no battery and no battery API (`UIDevice.batteryLevel`,
+    /// `batteryState` and `isBatteryMonitoringEnabled` are all
+    /// `API_UNAVAILABLE(tvos)`); the family is simply absent there, and on the
+    /// host Mac where the unit suite runs.
+    static let batteryReader: (() -> ForgeBatteryReading?)? = nil
+    static let batteryMonitoringControl: ForgeBatteryMonitoringControl? = nil
+    #endif
+}

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeApple.swift

@@ -147,6 +147,11 @@ public final class ForgeApple {
     private var capturePlanObservers: [UUID: (ForgeCapturePlan) -> Void] = [:]
     private var latestCapturePlan: ForgeCapturePlan?
     private var logObservers: [UUID: (ForgeRenderedLog) -> Void] = [:]
+    /// Guarded by its own lock, not `lock`: requests arrive on the runtime's
+    /// worker thread, and `destroy()` holds `lock` while the runtime joins
+    /// that worker - a request landing in that window must not need `lock`.
+    private let deviceSampleRequestLock = NSLock()
+    private var deviceSampleRequestObservers: [UUID: ([String]) -> Void] = [:]
 
     public init(config: ForgeAppleConfig, services: ForgeAppleServices) {
         let safeConfig = config.withPluginVersion(NPAWForge.defaultPluginVersion)
@@ -162,6 +167,11 @@ public final class ForgeApple {
         _ = runtime.setLogListener { [weak self] log in
             self?.dispatchRenderedLog(log)
         }
+        // Also before start(): the kernel's first sample request fires at
+        // delay 0 once a carrier exists, and a request is never replayed.
+        _ = runtime.setDeviceSampleListener { [weak self] families in
+            self?.dispatchDeviceSampleRequest(families)
+        }
         _ = runtime.start()
         if safeConfig.startSessionOnInitialize {
             _ = startSession()
@@ -398,6 +408,34 @@ public final class ForgeApple {
         runtime.recordLocationFix(fix)
     }
 
+    /// Forwards a device runtime health sample to the kernel. Called by the
+    /// automatic collector in answer to a kernel request; a host may also push
+    /// its own sample. Every field is optional and the kernel validates each
+    /// one; a sample sent while device insights are off remotely is refused.
+    @discardableResult
+    public func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !destroyed else { return .ignoredInvalidState }
+        return runtime.recordDeviceSample(sample)
+    }
+
+    /// Observes the kernel's device sample requests: the family allowlist the
+    /// operator configured, once per sampling tick. Nothing is replayed to a
+    /// late observer. Internal - the facade installs the collector that
+    /// answers; hosts see only the sample it forwards.
+    func addDeviceSampleRequestListener(_ listener: @escaping ([String]) -> Void) -> ForgeEventSubscription {
+        let id = UUID()
+        deviceSampleRequestLock.lock()
+        deviceSampleRequestObservers[id] = listener
+        deviceSampleRequestLock.unlock()
+        return ForgeEventSubscription { [weak self] in
+            self?.deviceSampleRequestLock.lock()
+            self?.deviceSampleRequestObservers.removeValue(forKey: id)
+            self?.deviceSampleRequestLock.unlock()
+        }
+    }
+
     public func effectiveLogLevel() -> ForgeLogLevel {
         logger.effectiveLevel()
     }
@@ -559,6 +597,15 @@ public final class ForgeApple {
         observers.forEach { $0(plan) }
     }
 
+    /// Runs on the runtime's worker thread; observers must not block it. After
+    /// `destroy()` the registry is empty, so a late request finds nobody.
+    private func dispatchDeviceSampleRequest(_ families: [String]) {
+        deviceSampleRequestLock.lock()
+        let observers = Array(deviceSampleRequestObservers.values)
+        deviceSampleRequestLock.unlock()
+        observers.forEach { $0(families) }
+    }
+
     public func destroyVideoView(_ view: RuntimeVideoView) -> ForgeOutcome {
         runtime.destroyVideoView(view)
     }
@@ -580,10 +627,14 @@ public final class ForgeApple {
         onSendRequestListeners.removeAll()
         capturePlanObservers.removeAll()
         logObservers.removeAll()
+        deviceSampleRequestLock.lock()
+        deviceSampleRequestObservers.removeAll()
+        deviceSampleRequestLock.unlock()
         recordedEvents.removeAll()
         _ = runtime.registerSessionPreSendHook(nil)
         _ = runtime.setCapturePlanListener(nil)
         _ = runtime.setLogListener(nil)
+        _ = runtime.setDeviceSampleListener(nil)
         return runtime.destroy()
     }
 

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeCapturePlan.swift

@@ -33,6 +33,12 @@ public struct ForgeCapturePlan: Equatable {
     public let behavior: Behavior
     public let sections: Sections
     public let attribution: Attribution
+    /// Device insights metric families the operator allowed (`di.m`), as the
+    /// canonical tokens `cpu`, `mem`, `bat`, `thm`, `disk` in canonical order.
+    /// Empty whenever ``Bits/deviceInsights`` is clear. Its only purpose on
+    /// Apple is pre-arming the observer a family needs (battery monitoring
+    /// for `bat`); the kernel's sample request, not the plan, triggers a read.
+    public let deviceInsightFamilies: [String]
     /// Canonical plan hash as a decimal string (full 64-bit value).
     public let hash: String
 
@@ -45,6 +51,7 @@ public struct ForgeCapturePlan: Equatable {
         behavior: Behavior = Behavior(),
         sections: Sections = Sections(),
         attribution: Attribution = Attribution(),
+        deviceInsightFamilies: [String] = [],
         hash: String
     ) {
         self.planSeq = planSeq
@@ -55,6 +62,7 @@ public struct ForgeCapturePlan: Equatable {
         self.behavior = behavior
         self.sections = sections
         self.attribution = attribution
+        self.deviceInsightFamilies = deviceInsightFamilies
         self.hash = hash
     }
 
@@ -211,6 +219,10 @@ public struct ForgeCapturePlan: Equatable {
         /// observe location. Without this bit Forge reads no location at all,
         /// not even the authorization status.
         public static let location: UInt32 = 1 << 15
+        /// The operator enabled device insights (`di.en` with a non-empty
+        /// family allowlist); ``ForgeCapturePlan/deviceInsightFamilies`` lists
+        /// the families. Set iff the kernel will be scheduling sample requests.
+        public static let deviceInsights: UInt32 = 1 << 16
     }
 }
 
@@ -252,6 +264,7 @@ extension ForgeCapturePlan {
         attributionIncludeLandingUrl: Bool,
         attributionDeriveFromDeepLinks: Bool,
         attributionInstallReferrerEnabled: Bool,
+        deviceInsightFamilies: [String],
         hash: String
     ) -> ForgeCapturePlan {
         func i64(_ value: UInt64) -> Int64 {
@@ -295,6 +308,7 @@ extension ForgeCapturePlan {
                 includeLandingUrl: attributionIncludeLandingUrl,
                 deriveFromDeepLinks: attributionDeriveFromDeepLinks
             ),
+            deviceInsightFamilies: deviceInsightFamilies,
             hash: hash
         )
     }