test(ios-runner): pin production-built runner requests in a golden table TS and Swift both verify (#2900)

* test(apple-runner): pin production-built runner requests in a golden table

Add contracts/fixtures/runner-requests.json: one entry per production
request site, captured at its real entry point. Three producer tests own
the entries: the platform-apple request sites, the runner-internal sites
(real HTTP bodies from the fake runner), and the two recording modules.
runner-contract.test.ts asserts every RunnerCommand has an entry, names
are sorted and unique, and the drive code builds no request itself.

Refs #2881

* test(apple-runner): verify the runner request golden table in Swift

Every fixture request decodes as Command and re-encodes with the same key
set, every CommandType case has a request, and every stored field of
Command, SequenceStep and RunnerGesturePlan appears in some request.
CommandType becomes CaseIterable for the case check.

Refs #2881

* chore(gates): keep runner-requests.json entries on one line each

Refs #2881

* test(apple-runner): pin the macOS desktopScroll pixels request

* test(apple-runner): share the runner-requests fixture check with root tests

Export the fixture reader as @agent-device/platform-apple/runner/requests-fixtures
so root producers pin requests through the same commandId normalization, and derive
the request-literal guard's sources from the producers the fixture declares.

Refs #2881

* test(apple-runner): drive root recording requests from a dedicated golden file

The request-literal guard scans every fixture producer, so root behavior
tests that doubled as producers had to weaken their exact request
assertions. Move the root recording drives into
src/__tests__/screen-recording-runner-requests.test.ts, restore the
original literals, and pin the recordStop sent without an app bundle.

Producers must now be *runner-requests.test.ts files that call
assertProducedRunnerRequests(import.meta.filename, ...), so a comment no
longer satisfies the check. The runner-internal drive moves to
runner/__tests__/runner-requests.test.ts to follow that rule.

Refs #2881

Author: thymikee

.oxfmtrc.json

@@ -10,6 +10,8 @@
     "node_modules/**",
     "**/*.md",
     "scripts/maestro-conformance/corpus/**",
-    "fallow-baselines/**"
+    "fallow-baselines/**",
+    // One entry per line, so each pinned runner request changes as one reviewable diff line.
+    "contracts/fixtures/runner-requests.json"
   ]
 }

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -2,7 +2,7 @@ import AgentDeviceSnapshotPresentation
 
 // MARK: - Wire Models
 
-enum CommandType: String, Codable {
+enum CommandType: String, Codable, CaseIterable {
   case tap
   case mouseClick
   case longPress

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ModelsTests.swift

@@ -32,5 +32,115 @@ extension RunnerTests {
   func runnerCommandFixture(_ json: String) throws -> Command {
     try JSONDecoder().decode(Command.self, from: Data(json.utf8))
   }
+
+  func testProductionRunnerRequestsDecodeWithoutDroppingAKey() throws {
+    for (name, request) in try productionRunnerRequests() {
+      let command = try decodeProductionRunnerRequest(request, name)
+      XCTAssertEqual(command.command.rawValue, request["command"] as? String, name)
+      let reencoded = try JSONSerialization.jsonObject(with: JSONEncoder().encode(command))
+      XCTAssertEqual(runnerRequestKeyPaths(reencoded), runnerRequestKeyPaths(request), name)
+    }
+  }
+
+  func testEveryRunnerCommandTypeHasAProductionRequest() throws {
+    let produced = Set(try productionRunnerRequests().compactMap { $0.request["command"] as? String })
+    let orphaned = CommandType.allCases.map(\.rawValue).filter { !produced.contains($0) }
+    XCTAssertEqual(orphaned, [], "CommandType cases with no production request")
+  }
+
+  func testEveryRunnerRequestFieldHasAProductionRequest() throws {
+    let entries = try productionRunnerRequests()
+    let requests = entries.map(\.request)
+    let steps = requests.flatMap { $0["steps"] as? [[String: Any]] ?? [] }
+    let plans = requests.compactMap { $0["gesturePlan"] as? [String: Any] }
+    let pointers = plans.flatMap { $0["pointers"] as? [[String: Any]] ?? [] }
+    let samples = pointers.flatMap { $0["samples"] as? [[String: Any]] ?? [] }
+    let commands = try entries.map { try decodeProductionRunnerRequest($0.request, $0.name) }
+    let command = try XCTUnwrap(commands.first, "no production request")
+    let plan = try XCTUnwrap(
+      commands.compactMap(\.gesturePlan).first,
+      "no production request carries a gesturePlan"
+    )
+    let step = try JSONDecoder().decode(SequenceStep.self, from: Data(#"{"kind":"tap"}"#.utf8))
+    let sample = try XCTUnwrap(plan.pointers.first?.samples.first)
+    assertEveryStoredField(of: command, appearsIn: requests, "Command")
+    assertEveryStoredField(of: step, appearsIn: steps, "SequenceStep")
+    assertEveryStoredField(of: plan, appearsIn: plans, "RunnerGesturePlan")
+    assertEveryStoredField(
+      of: plan.viewport,
+      appearsIn: plans.compactMap { $0["viewport"] as? [String: Any] },
+      "RunnerGestureViewport"
+    )
+    assertEveryStoredField(of: plan.pointers[0], appearsIn: pointers, "RunnerGesturePointer")
+    assertEveryStoredField(of: sample, appearsIn: samples, "RunnerGestureSample")
+    assertEveryStoredField(
+      of: sample.point,
+      appearsIn: samples.compactMap { $0["point"] as? [String: Any] },
+      "RunnerGesturePoint"
+    )
+  }
+
+  private func productionRunnerRequests() throws -> [(name: String, request: [String: Any])] {
+    let fixtureURL = URL(fileURLWithPath: #filePath)
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .deletingLastPathComponent()
+      .appendingPathComponent("contracts/fixtures/runner-requests.json")
+    let entries = try XCTUnwrap(
+      JSONSerialization.jsonObject(with: Data(contentsOf: fixtureURL)) as? [[String: Any]]
+    )
+    return try entries.map { entry in
+      (
+        name: try XCTUnwrap(entry["name"] as? String),
+        request: try XCTUnwrap(entry["request"] as? [String: Any], "\(entry["name"] ?? "?")")
+      )
+    }
+  }
+
+  private func decodeProductionRunnerRequest(_ request: [String: Any], _ name: String) throws
+    -> Command
+  {
+    do {
+      return try JSONDecoder().decode(
+        Command.self,
+        from: JSONSerialization.data(withJSONObject: request)
+      )
+    } catch {
+      XCTFail("\(name) does not decode as Command: \(error)")
+      throw error
+    }
+  }
+
+  private func runnerRequestKeyPaths(_ value: Any, _ prefix: String = "") -> Set<String> {
+    if let object = value as? [String: Any] {
+      return object.reduce(into: Set<String>()) { paths, field in
+        paths.insert(prefix + field.key)
+        paths.formUnion(runnerRequestKeyPaths(field.value, "\(prefix)\(field.key)."))
+      }
+    }
+    if let array = value as? [Any] {
+      return array.reduce(into: Set<String>()) { paths, element in
+        paths.formUnion(runnerRequestKeyPaths(element, "\(prefix)[]."))
+      }
+    }
+    return []
+  }
+
+  private func assertEveryStoredField(
+    of value: Any,
+    appearsIn objects: [[String: Any]],
+    _ level: String
+  ) {
+    let fields = Set(Mirror(reflecting: value).children.compactMap(\.label))
+    let produced = Set(objects.flatMap(\.keys))
+    XCTAssertEqual(
+      fields.subtracting(produced).sorted(),
+      [],
+      "\(level) fields with no production request"
+    )
+  }
 }
 #endif

apple/runner/RUNNER_PROTOCOL.md

@@ -14,6 +14,7 @@ The daemon probes `http://127.0.0.1:<port>/command` for simulator and desktop fl
 ## Request Shape
 
 Every request includes a `command` field. Additional fields depend on the command family.
+The request vocabulary is `contracts/fixtures/runner-requests.json`: the requests production builds.
 
 Examples: