SPB Git

Repository Public License

diagnostics.md 12.0 KB

# ORIX Secure — Device diagnostics

Sources: Packages/ORIXSecureEngines/Sources/ORIXSecureEngines/ — DeviceSnapshot.swift, SystemDeviceProbe.swift, DeviceDiagnosticsEngine.swift; screens App/Sources/Features/DeviceDiagnostics/DeviceView.swift and App/Sources/Features/Battery/BatteryView.swift; report in App/Sources/Core/ReportBuilders.swift.

# 1. Flow

flowchart TD
    subgraph APIs["Public APIs"]
        A1["uname(3)"]
        A2["ProcessInfo"]
        A3["UIDevice"]
        A4["UIScreen of the first UIWindowScene"]
        A5["URL.resourceValues (volume keys)"]
        A6["sysctl kern.boottime"]
        A7["os_proc_available_memory()"]
        A8["task_info(TASK_VM_INFO)"]
    end
    A1 --> P
    A2 --> P
    A3 --> P
    A4 --> P
    A5 --> P
    A6 --> P
    A7 --> P
    A8 --> P
    P["SystemDeviceProbe.snapshot()<br/>@MainActor"] --> S["DeviceSnapshot<br/>plain values and Reading fields"]
    S --> D["DeviceDiagnosticsEngine.diagnostics(_:)"]
    S --> F["DeviceDiagnosticsEngine.findings(_:)"]
    S --> ADV["DeviceDiagnosticsEngine.advice(_:)"]
    L["PlatformLimits.deviceMeasurements"] --> D
    D --> DD["DeviceDiagnostics<br/>5 sections of DiagnosticRow,<br/>findings, unavailable"]
    F --> DD
    DD --> V1["DeviceView"]
    ADV --> V2["BatteryView"]
    NO["DeviceDiagnosticsEngine.notOffered"] --> V2
    DD --> R["ReportBuilder.device(_:advice:)<br/>ReportDocument kind .device"]
    ADV --> R
    F --> RA["AppModel.recommendedActions<br/>attention findings only"]
    S --> SEC["SecurityAssessmentEngine<br/>os.outdated, restart"]
    S --> STO["StorageAnalysisEngine.overview(volume:)"]

The snapshot is taken in AppModel.init and on every AppModel.refresh() (scene becomes active, or an explicit refresh). Nothing is sampled in the background and no history of readings is kept.

# 2. DeviceSnapshot fields

Field Type API source Notes
modelIdentifier String uname(3) machine; in the Simulator, environment variable SIMULATOR_MODEL_IDENTIFIER "unknown" if uname fails.
modelFamily String UIDevice.current.model "Mac" when UIKit is absent.
idiom DeviceIdiom UIDevice.current.userInterfaceIdiom phone, pad, mac, vision, other.
isSimulator Bool SIMULATOR_MODEL_IDENTIFIER != nil Drives the simulator notes and probe short-cuts.
systemName String UIDevice.current.systemName
systemVersion, systemMajorVersion String, Int ProcessInfo.operatingSystemVersion Patch component omitted when 0.
builtAgainstSDKVersion String? Bundle.main Info.plist key DTPlatformVersion Dated reference for device.os.outdated.
screen Reading<ScreenInfo> UIScreen.bounds, nativeBounds, scale, maximumFramesPerSecond .failed when no window scene is connected.
processorCount, activeProcessorCount Int ProcessInfo.processorCount, activeProcessorCount
physicalMemory Int64 ProcessInfo.physicalMemory Installed memory.
appAvailableMemory Reading<Int64> os_proc_available_memory() What this app may still allocate; not device free memory. .failed when it returns 0.
appMemoryFootprint Reading<Int64> task_info(mach_task_self_, TASK_VM_INFO) → phys_footprint This app only.
thermal ThermalLevel ProcessInfo.thermalState nominal, fair, serious, critical; unknown future cases map to nominal.
lowPowerMode Bool ProcessInfo.isLowPowerModeEnabled
batteryLevel Reading<Double> UIDevice.batteryLevel 0…1. Negative values give .failed; .simulator in the Simulator.
batteryState Reading<BatteryChargeState> UIDevice.batteryState unplugged, charging, full; .unknown gives .failed.
volume VolumeCapacity URLResourceKey values of the home directory Four readings, see storage.md.
lastBoot Reading<Date> sysctl(CTL_KERN, KERN_BOOTTIME) Declared in the privacy manifest (SystemBootTime, reason 35F9.1).
capturedAt Date — Used as assessedAt of the diagnostic findings.

Battery monitoring: the probe sets UIDevice.isBatteryMonitoringEnabled = true, reads level and state, and restores the previous value if monitoring was off. It does not subscribe to battery notifications.

Non-iOS builds (package tests on macOS) leave screen, batteryLevel and batteryState at .unavailable(.unsupportedOnDevice, …).

# 3. Diagnostic sections

DeviceDiagnosticsEngine.diagnostics(_:) returns five DiagnosticSections. Each DiagnosticRow has a Reading<String> value, an optional note and the technical source string shown in the UI.

Section id Rows (id → label)
identity model Model identifier, family Model family, os System, boot Last restart
display points Size in points, pixels Native resolution, scale Scale, fps Maximum refresh rate
processing cores Processor cores, activeCores Active cores, ram Installed memory, appMemory Memory used by ORIX Secure, appAvailable Memory ORIX Secure may still use
power battery Battery level, charging Power state, lowPower Low Power Mode, thermal Thermal state
storage capacity Capacity, available Available (bestAvailable), free Free on the file system

Rows built from a Reading use Reading.map, so an unavailable reading stays unavailable in the row and the UI shows the reason. In a report, ReportBuilder.device writes such a row as "Not available — ". In the Simulator the model row carries the note that hardware readings describe the simulated device or the host Mac, and the report's device facts add an "Environment: Simulator" line.

# 4. Diagnostic findings

DeviceDiagnosticsEngine.findings(_:) — all category: .performance, confidence: .measured, verification: .publicAPI.

Finding id Condition State Severity
device.thermal thermal is nominal or fair verified none
device.thermal thermal is serious attention low
device.thermal thermal is critical attention moderate
device.cores activeProcessorCount < processorCount attention low
device.lowPower lowPowerMode is true verified (informational) none

device.thermal always exists; the other two appear only when their condition holds. The thermal finding's notInspected states that this is a four-level state, not a temperature. AppModel.recommendedActions merges the attention ones with the security, privacy and storage actions.

# 5. PlatformLimits.deviceMeasurements

Nine UnavailableMeasurement entries, shown as they are and never replaced by an estimate. They are attached to every DeviceDiagnostics.unavailable, listed in CapabilitiesView (Settings › "What ORIX Secure can and cannot do") and written to the unavailable list of the device report.

id Title Reason given Where the user can see it
battery.cycles Battery cycle count No public API Settings › Battery › Battery Health
battery.capacity Battery maximum capacity No public API for battery health Settings › Battery › Battery Health
battery.perapp Battery use by other apps An app observes its own energy use only Settings › Battery
cpu.temperature Processor temperature iOS reports a four-level thermal state, not degrees —
cpu.system System-wide processor use An app measures its own processor time only —
memory.others Memory used by other apps The sandbox hides other processes —
hardware.faults Hardware fault and repair history Belongs to Apple's service tools Settings › General › About › Parts & Service History
kernel Kernel and system process state Not inspectable by apps —
storage.categories Storage used by each app and category iOS gives volume capacity and the app's own files only Settings › General › iPhone Storage

StorageAnalysisEngine.overview reuses the storage.categories entry as StorageOverview.notExposed.

# 6. Battery and performance advice

DeviceDiagnosticsEngine.advice(_:) returns Advice values of three kinds: observation (derived from a reading taken now, with the reading in basis), userCheck (something only the user can look at) and guidance (general, independent of readings).

Observation rules, evaluated in this order:

Advice id Condition
battery.low batteryLevel ≤ 0.2 and batteryState == .unplugged and Low Power Mode off
battery.full batteryLevel ≥ 0.95 and batteryState is .charging or .full
thermal.hot thermal is serious or critical
thermal.charging thermal != .nominal and batteryState == .charging
lowPower.on lowPowerMode is true
storage.pressure volume.usedFraction > 0.9 and bestAvailable is measured

The two battery rules require a measured batteryLevel; when the level is unavailable (Simulator, macOS) neither fires. thermal.charging likewise needs a measured charging state.

Always appended, with an empty basis:

Advice id Kind Subject
check.health userCheck Settings › Battery › Battery Health (maximum capacity, cycle count; the text states iOS does not give these to apps)
check.usage userCheck Settings › Battery per-app list and Background App Refresh
guide.forceclose guidance Closing apps does not save battery
guide.update guidance Higher battery use for a day or two after an iOS update is normal

The engine never infers battery health from the level or the thermal state.

# 7. Deliberately not offered

DeviceDiagnosticsEngine.notOffered (rendered in BatteryView, accessibility id battery.notOffered):

  1. No "RAM boost": an app cannot free other apps' memory, and iOS manages memory itself.
  2. No battery "repair" or "calibration": software cannot restore a worn battery's capacity.
  3. No force-closing of other apps and no override of iOS power management.
  4. No system cache cleaning: an app can delete its own files only.

Consistent with this, the codebase contains no benchmark, no CPU load generator, no continuous battery sampling and no background task registration.

# 8. Relation to other engines

  • SecurityAssessmentEngine consumes systemMajorVersion, builtAgainstSDKVersion, lastBoot, isSimulator (security-engine.md).
  • StorageAnalysisEngine consumes volume (storage.md).
  • InvestigationEngine reads thermal state, Low Power Mode, battery, last restart and storage as observations for the batteryDrain, crashes and storageAnomaly symptoms, and derives two conditions from the snapshot: "hot" (serious or critical) and "low storage" (usedFraction > 0.95).

# 9. Verification status

  • DeviceStoragePrivacyTests runs the engine against fixed snapshots (sections, thermal and core findings, advice grounded in readings) and runs SystemDeviceProbe on the test Mac (systemProbeReturnsRealValuesOnThisMac).
  • In the iOS Simulator batteryLevel and batteryState are .unavailable(.simulator), so the battery rows, the battery.low / battery.full / thermal.charging advice and the real UIDevice battery path have not been observed with device values. Thermal states other than nominal, reduced activeProcessorCount and the 5 % battery granularity stated in the UI note are likewise unobserved on hardware.
  • os_proc_available_memory() and kern.boottime were read in the Simulator, where they describe the host environment.
  • The tests were not re-run while writing this document.
Files main
Menu

Theme