fix(ios): combined app candidate: one-capture uploads, coverage rebuild cache, ground freshness, privacy manifest, AX5 folds, #56 and #49 guidance fixes

.github/workflows/ios.yml

@@ -38,8 +38,10 @@ jobs:
     # macos-26 (arm64) is the newest GA macOS image. The xcode-27 image is still a preview.
     runs-on: macos-26
     # Beta run 36302099002 took 43 minutes before the spot-confirmation and review checks
-    # were added. Leave room for those checks without dropping the every-state audit.
-    timeout-minutes: 60
+    # were added. Full run 36832282114 (#190) then took 58 of 60 minutes, and the ground
+    # freshness UI tests add about 161 s more (run 36744881974), so 60 would cut the
+    # every-state audit short. 75 leaves room without dropping any check.
+    timeout-minutes: 75
     env:
       # Newest stable Xcode on macos-26 per images/macos/macos-26-arm64-Readme.md (image 20260907).
       DEVELOPER_DIR: /Applications/Xcode_26.6.app/Contents/Developer

ios/Config/Info.plist

@@ -35,6 +35,8 @@
 	</dict>
 	<key>NSCameraUsageDescription</key>
 	<string>House Scan uses the camera to measure the outside wall around your electric meter.</string>
+	<key>NSLocalNetworkUsageDescription</key>
+	<string>House Scan connects to a House Scan server on your local network only when a developer has set it up for testing.</string>
 	<key>NSMotionUsageDescription</key>
 	<string>House Scan records your phone's motion and air pressure while you scan and saves them with the scan. The readings stay on this phone unless you share the scan.</string>
 	<key>UIApplicationSceneManifest</key>

ios/HouseScan/PrivacyInfo.xcprivacy

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+Required-reason APIs the app calls, with Apple's approved reason for each use. Only first-party
+code ships in the app; HouseScanKit has no dependencies. Tracking and collected data types are
+not declared here: they belong to the App Store privacy answers, which this file does not decide.
+-->
+<plist version="1.0">
+<dict>
+	<key>NSPrivacyAccessedAPITypes</key>
+	<array>
+		<!-- The Practice meter switch: the app's own key in standard defaults
+		     (DeveloperSettings.swift, DeveloperOptions.swift). -->
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>CA92.1</string>
+			</array>
+		</dict>
+		<!-- Which earlier scan.zip in the app's Caches folder is newest, to keep it
+		     (ScanFolderCleanup.swift). -->
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>C617.1</string>
+			</array>
+		</dict>
+		<!-- systemUptime. 35F9.1: time between a homeowner's "can't get there" taps
+		     (ScanEngine+Ends.swift refusalClock), and dropping recorded frames from before a
+		     restart (CaptureRecorder.restart). 8FFB.1: the wall-clock time of the first recorded
+		     frame, the packet's capture.started_at (CaptureRecorder.append). -->
+		<dict>
+			<key>NSPrivacyAccessedAPIType</key>
+			<string>NSPrivacyAccessedAPICategorySystemBootTime</string>
+			<key>NSPrivacyAccessedAPITypeReasons</key>
+			<array>
+				<string>35F9.1</string>
+				<string>8FFB.1</string>
+			</array>
+		</dict>
+	</array>
+</dict>
+</plist>

ios/HouseScan/Runtime/LaunchOptions.swift

@@ -23,7 +23,7 @@ import OSLog
 /// - `-autopilotSomethingThere`: the autopilot answers the first spot check "Something's there"
 ///   instead of "It's clear", so the scan is checked again without that area.
 /// - `-injectGroundRise <meters>`: with `-replay`, `-autopilot` and `-autopilotGate`, once the
-///   first result shows, each time a file named `inject-ground` appears in the gate folder the
+///   first upload starts, each time a file named `inject-ground` appears in the gate folder the
 ///   app deletes it and hands the engine a detected floor that many meters above its current
 ///   ground, as ARKit refining the ground would (`ScanEngine.injectGroundForTest`). Replays carry
 ///   no plane evidence, so this is the only way a UI test reaches that path. Meters must be over

ios/HouseScan/Runtime/MeterReader/VisionMeterNumberReader.swift

@@ -2,6 +2,7 @@ import CoreGraphics
 import Foundation
 import HouseScanKit
 import ImageIO
+import OSLog
 import Vision
 
 /// Reads the meter number from a close-up with Apple Vision, configured as the close-up eval
@@ -46,6 +47,13 @@ struct VisionMeterNumberReader: MeterNumberReader {
         do {
             try VNImageRequestHandler(cgImage: image, orientation: orientation).perform([text, barcodes])
         } catch {
+            // The homeowner sees this as "no number", so the log is the only place that says Vision
+            // itself failed (e.g. com.apple.Vision 9, "Could not create inference context", in one
+            // Mac's simulator). Domain and code are framework identifiers and stay public. The
+            // message is Vision's free text, so it stays private: nothing vouches that it never
+            // names a file or carries content.
+            let failure = error as NSError
+            RuntimeLog.engine.error("meter number: Vision failed, reading as no number: \(failure.domain, privacy: .public) \(failure.code, privacy: .public) \(failure.localizedDescription, privacy: .private)")
             return retakeNoNumber
         }
 

ios/HouseScan/Runtime/ResultClient.swift

@@ -13,7 +13,9 @@ protocol ResultClient: AnyObject {
 /// the body and `Content-Type: application/json`. Only the JSON goes: the server's solver reads no
 /// photos and skips the image check for a bare scene.json, so the keyframes stay on the phone
 /// (and in the scan folder's `scan.zip`, which leaves only if the homeowner shares it). The
-/// response body is the result JSON.
+/// response body is the result JSON, and it is returned only when it names the scene sent: its
+/// `stats.input_sha256` must be present and be the hash of these exact bytes (`ResultBinding`).
+/// Any other answer throws, and the upload screen treats it as an answer it couldn't read.
 @MainActor
 final class HTTPResultClient: ResultClient {
     let serverURL: URL
@@ -42,6 +44,7 @@ final class HTTPResultClient: ResultClient {
                 status: http.statusCode, body: String(decoding: data.prefix(300), as: UTF8.self),
                 retryAfter: http.value(forHTTPHeaderField: "Retry-After"))
         }
+        try ResultBinding.check(answer: data, submittedScene: scene)
         progress(1)
         return data
     }
@@ -137,7 +140,9 @@ final class UploadProgressDelegate: NSObject, URLSessionTaskDelegate, Sendable {
 }
 
 /// Answers with the bundled SampleResult.json, for tests and demos without a server. The result
-/// is flagged `isSample` so the screen says it is not a real analysis.
+/// is flagged `isSample` so the screen says it is not a real analysis. It answers no particular
+/// scene (its `input_sha256` is all zeros), so it is deliberately not checked with
+/// `ResultBinding`.
 @MainActor
 final class SampleResultClient: ResultClient {
     let isSample = true

ios/HouseScan/Runtime/ScanEngine+Confirm.swift

@@ -11,6 +11,9 @@ struct SpotConfirmState {
     /// The last upload's scene.json, and the sha256 of it and of the answer to it: what a check
     /// asked now is bound to, and the scene the bundle is written again with after "It's clear".
     var lastScene: Data?
+    /// The capture packet's inputs from that same upload, with `lastScene` attached: the packet
+    /// written again after "It's clear" (`answerSpotCheck`).
+    var lastPacket: ScanEngine.PacketInputs?
     var sceneSHA256: String?
     var answerSHA256: String?
     /// The check on screen: its area, the photo shown and the exchange it came from.
@@ -50,8 +53,9 @@ extension ScanEngine {
 
     /// Records the upload's scene and the answer to it, which a check asked about this answer
     /// is bound to. Call it once the answer has decoded.
-    func noteExchange(scene: Data, answer: Data) {
+    func noteExchange(scene: Data, answer: Data, packet: PacketInputs?) {
         spotConfirm.lastScene = scene
+        spotConfirm.lastPacket = packet
         spotConfirm.sceneSHA256 = PacketFiles.sha256(scene)
         spotConfirm.answerSHA256 = PacketFiles.sha256(answer)
     }
@@ -125,8 +129,10 @@ extension ScanEngine {
                 return
             }
             // The bundle was written at the upload, before this answer: write it again so its
-            // guidance log holds the answer.
-            if let scene = spotConfirm.lastScene { saveBundle(scene: scene, mesh: liveCapture?.meshSnapshot()) }
+            // guidance log holds the answer. The upload's captured packet is reused, with only
+            // the guidance log read again and placed in that packet's frame, so the packet keeps
+            // the submitted scene's geometry, mesh and photos rather than mixing in a later wall.
+            if let packet = spotConfirm.lastPacket { saveBundle(withCurrentGuidance(packet)) }
             go(.result)
         }
     }

ios/HouseScan/Runtime/ScanEngine+Export.swift

@@ -4,13 +4,19 @@ import OSLog
 import simd
 
 extension ScanEngine {
-    /// scene.json for the current scan (contract C1), with the LiDAR mesh's measurements on
-    /// phones that have one.
+    /// scene.json for the current scan (contract C1), without mesh measurements: the autopilot's
+    /// gate copy. The upload captures the scene once and measures the mesh against that capture
+    /// (`captureUpload`, `UploadPackaging`).
+    func sceneJSON() throws -> Data {
+        try SceneExport.jsonData(sceneInput())
+    }
+
+    /// The scan's scene as it stands now, without mesh measurements, read in this one turn.
     ///
     /// The scene frame is the AR world frame moved down so the ground at the wall is y = 0: the
     /// server reads heights (meter.pos y, pose translations) as height above that ground, and
     /// scene.json has no field for the ground's height otherwise.
-    func sceneJSON(mesh: MeshMeasurements = MeshMeasurements()) throws -> Data {
+    func sceneInput() throws -> SceneInput {
         guard let map = coverage else { throw ExportError.noWall }
         let wall = map.wall
         let drop = SIMD3<Float>(0, wall.groundY, 0)
@@ -74,13 +80,23 @@ extension ScanEngine {
             ),
             keyframes: keyframes,
             stills: store.stills,
-            // Written without plus_minus_ft: the server takes its mesh error for both.
-            meshFacing: mesh.facing,
-            meshOverheads: mesh.overheads,
+            // The mesh's measurements are filled in once measured (`UploadPackaging`). Written
+            // without plus_minus_ft: the server takes its mesh error for both.
             // Unanswered exports like "Not sure": no patch, and the server reports the surface unknown.
             groundType: state.groundAnswer.flatMap(Self.sceneGroundType)
         )
-        return try SceneExport.jsonData(input)
+        return input
+    }
+
+    /// Everything one upload sends, read in one main-actor turn: the scene, the wall in world
+    /// meters, the LiDAR mesh and the capture packet's inputs. Nothing after this rereads the
+    /// engine's geometry for this upload, so a ground or anchor correction while the mesh is
+    /// measured can't mix two walls into its scene or packet.
+    func captureUpload() throws -> UploadPackaging<PacketInputs> {
+        let scene = try sceneInput()
+        guard let map = coverage else { throw ExportError.noWall }
+        let meshSnapshot = liveCapture?.meshSnapshot()
+        return UploadPackaging(scene: scene, worldWall: map.wall, mesh: meshSnapshot?.mesh, packet: packetInputs(mesh: meshSnapshot))
     }
 
     static func sceneGroundType(_ answer: GroundAnswer) -> SceneGroundType? {
@@ -132,20 +148,6 @@ extension ScanEngine {
         return low...high
     }
 
-    /// What the LiDAR mesh measured over the exported stretch: the gap from the wall out to
-    /// whatever faces it, and the clear height under anything overhead, each per stretch of s in
-    /// meters. Empty without a mesh.
-    struct MeshMeasurements: Sendable {
-        var facing: [ObservedSpan] = []
-        var overheads: [ObservedSpan] = []
-    }
-
-    /// Measures a world-space mesh (meters) against the wall (world meters) over `span`, the
-    /// exported stretch of s.
-    nonisolated static func measure(_ mesh: TriangleMesh, wall: WallFrame, over span: ClosedRange<Float>) -> MeshMeasurements {
-        MeshMeasurements(facing: mesh.facingSpans(wall: wall, over: span), overheads: mesh.overheadSpans(wall: wall, over: span))
-    }
-
     /// Error of the chest-height ground guess (camera height minus 1.4 m), meters. Phones held
     /// for scanning sit roughly 1.1 to 1.7 m up, so ±0.3 m. A hypothesis; no measured spread exists.
     static let estimatedGroundError: Float = 0.3

ios/HouseScan/Runtime/ScanEngine+Packet.swift

@@ -32,6 +32,10 @@ extension ScanEngine {
         /// `photoIDs` hold store ids ("meter_close"); `writePacket` swaps in packet ids.
         var marks: [PacketMark]
         var guidance: [PacketGuidanceEntry]
+        /// The wall the marks and guidance were placed with, in world meters, captured with them,
+        /// so a later write that adds guidance places it in the same frame (`withCurrentGuidance`).
+        var sceneWall: SceneWall
+        /// The scene.json the upload sent, attached once serialized (`UploadPackaging`).
         var scene: Data
         /// The camera's frame rate live; nil on a replay, whose rate comes from its frames.
         var trajectoryRate: Double?
@@ -49,8 +53,9 @@ extension ScanEngine {
         var frames: [ReplayFrame]
     }
 
-    /// Nil before there is a wall: the meter frame is built from it.
-    func packetInputs(scene: Data, mesh: LiveCapture.MeshSnapshot?) -> PacketInputs? {
+    /// Nil before there is a wall: the meter frame is built from it. The scene is attached by the
+    /// upload once it is serialized from the same capture (`captureUpload`).
+    func packetInputs(mesh: LiveCapture.MeshSnapshot?) -> PacketInputs? {
         guard let map = coverage else { return nil }
         let wall = map.wall
         // The wall in world meters, as scene.json's wall type describes it, for the marks.
@@ -93,12 +98,22 @@ extension ScanEngine {
             },
             marks: packetMarks(map, wall: sceneWall, frame: frame),
             guidance: guidanceLog.entries.map { Self.packetEntry($0, wall: sceneWall, frame: frame) },
-            scene: scene,
+            sceneWall: sceneWall,
+            scene: Data(),
             trajectoryRate: settings.map { Double($0.framesPerSecond) },
             motionStreams: motionRunsLive ? motionAvailable : []
         )
     }
 
+    /// `inputs` with the guidance log as it is now, placed with the wall and meter frame the
+    /// inputs were captured with: what the spot check's answer adds to an upload's packet, without
+    /// rereading the engine's geometry since.
+    func withCurrentGuidance(_ inputs: PacketInputs) -> PacketInputs {
+        var inputs = inputs
+        inputs.guidance = guidanceLog.entries.map { Self.packetEntry($0, wall: inputs.sceneWall, frame: inputs.meterFrame) }
+        return inputs
+    }
+
     /// `utsname.machine`, such as "iPhone16,1": the hardware, never the phone's name. "arm64" in
     /// the Simulator.
     nonisolated static func hardwareModel() -> String {