Skip to content

Commit 3f4a65b

Browse files
thymikeeclaude
andcommitted
refactor(apple): prove surface absence on the runner channel as on the guest channel
#4172 moved the guest channel's presence check into the bridge request: when no runner can answer the foreground read, the route names the surface host executables, and the reader checks the process table in place. The runner channel now takes the same path instead of a constant 'unknown' presence probe. The runner forwards the executables to the shared reader and names the Simulator it runs in. A sandbox that refuses the process table answers system-surface-host-unverified, so the capture uses XCTest and says why. The surface-host refusal codes join the refusal fixture, and the runner request fixture pins a describe that carries the executables. Co-Authored-By: Claude <[email protected]>
1 parent c475c03 commit 3f4a65b

8 files changed

Lines changed: 45 additions & 21 deletions

File tree

‎contracts/fixtures/ios-snapshot-bridge-refusals.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,14 @@
2828
{
2929
"code": "snapshot-tree-changed",
3030
"consequence": "tree-changed"
31+
},
32+
{
33+
"code": "system-surface-host-present",
34+
"consequence": "system-surface-host"
35+
},
36+
{
37+
"code": "system-surface-host-unverified",
38+
"consequence": "system-surface-host"
3139
}
3240
],
3341
"generationScoped": [
@@ -94,6 +102,7 @@
94102
"snapshot-tree-required",
95103
"source-closed",
96104
"source-version-mismatch",
105+
"surface-hosts-invalid",
97106
"target-process-changed",
98107
"target-process-unavailable",
99108
"traits-invalid",

‎contracts/fixtures/runner-requests.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@
6767
{"name": "ios-simulator.runner-sequence.bound-orientation", "producer": "packages/platform-apple/src/__tests__/interactions-press-series-runner-requests.test.ts", "request": {"command": "sequence", "steps": [{"kind": "tap", "x": 10, "y": 20, "synthesized": true}], "appBundleId": "com.example.app", "sequenceOrientation": 1, "commandId": "<commandId>"}},
6868
{"name": "ios-simulator.runner-session-readiness.uptime", "producer": "packages/apple-runner/src/__tests__/index-runner-requests.test.ts", "request": {"command": "uptime", "commandId": "<commandId>"}},
6969
{"name": "ios-simulator.runner-snapshot-bridge.describe", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshotBridge", "appBundleId": "com.example.app", "snapshotBridge": {"verb": "describe", "requestId": "<requestId>", "generation": "41:1700000000.000001", "expectedPid": 41, "expectedProcessStartTime": "1700000000.000001", "maxDepth": 128, "maxNodes": 5000, "maxDurationMs": 4000, "maxResponseBytes": 4194304}, "commandId": "<commandId>"}},
70+
{"name": "ios-simulator.runner-snapshot-bridge.describe-surface-hosts", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshotBridge", "appBundleId": "com.example.app", "snapshotBridge": {"verb": "describe", "requestId": "<requestId>", "generation": "41:1700000000.000001", "expectedPid": 41, "expectedProcessStartTime": "1700000000.000001", "maxDepth": 128, "maxNodes": 5000, "maxDurationMs": 4000, "maxResponseBytes": 4194304, "surfaceHostExecutables": ["SafariViewService.app/SafariViewService", "PassbookUIService.app/PassbookUIService"]}, "commandId": "<commandId>"}},
7071
{"name": "ios-simulator.runner-snapshot-bridge.target", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "snapshotBridge", "appBundleId": "com.example.app", "snapshotBridge": {"verb": "target", "requestId": "<requestId>", "maxDurationMs": 4000}, "commandId": "<commandId>"}},
7172
{"name": "macos.desktop-scroll.amount", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "down", "amount": 0.5, "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},
7273
{"name": "macos.desktop-scroll.pixels", "producer": "packages/platform-apple/src/__tests__/index-runner-requests.test.ts", "request": {"command": "desktopScroll", "direction": "up", "pixels": 200, "durationMs": 300, "appBundleId": "com.example.app", "commandId": "<commandId>"}},

‎docs/adr/0004-ios-snapshot-backend-strategy.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -825,11 +825,12 @@ If that request fails, the channel keeps its cached target.
825825
The capture names no generation, because the app may have relaunched.
826826

827827
A presented system surface stays invisible to the bridge (#2438 amendment), so the route still needs proven absence.
828-
The daemon cannot read the processes of a provider iOS Simulator.
829-
Thus, the runner's foreground read is the only read that can prove absence there.
830-
Every capture of a provider iOS Simulator needs the runner, so that read starts a runner that is not up yet.
828+
The proof is the same on both channels: the runner's foreground read first, and the bridge's own process check when that read cannot answer.
829+
Every capture of a provider iOS Simulator needs the runner, so the foreground read starts a runner that is not up yet.
831830
The proof starts the runner when none is live, and then reads only that runner session.
832-
If the session id cannot be read, the proof answers `unknown` and the capture uses XCTest.
831+
If the session id cannot be read, the read answers `unknown`, and the bridge read names the surface hosts.
832+
The runner then reads the process table of the Simulator it runs in, which it names itself.
833+
A sandbox that refuses that table gives `system-surface-host-unverified`, and the capture uses XCTest.
833834

834835
An observe-only capture skips the route and goes straight to the provider's capture.
835836
An observe-only capture must not activate the app or start work, so the provider's capture decides how to observe.

‎packages/platform-apple/src/__tests__/index-runner-requests.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { IOS_SYSTEM_SURFACE_HOSTS } from '@agent-device/contracts/ios-system-surface';
12
import {
23
assertProducedRunnerRequests,
34
bindTestCommandHost,
@@ -321,6 +322,18 @@ const SNAPSHOT_BRIDGE_SITES: Record<
321322
},
322323
hint: deriveIosCaptureHint(createIosSnapshotRequest({ interactiveOnly: true })),
323324
}),
325+
'ios-simulator.runner-snapshot-bridge.describe-surface-hosts': (bridge) =>
326+
bridge.source.acquire({
327+
target: {
328+
appBundleId: APP,
329+
targetId: `${IOS_SIMULATOR.id}:${APP}`,
330+
pid: 41,
331+
processStartTime: '1700000000.000001',
332+
generation: '41:1700000000.000001',
333+
},
334+
hint: deriveIosCaptureHint(createIosSnapshotRequest({ interactiveOnly: true })),
335+
surfaceHostExecutables: IOS_SYSTEM_SURFACE_HOSTS.map((host) => host.processExecutable),
336+
}),
324337
};
325338

326339
function onlyRequest(name: string, calls: RecordedRunnerCall[]): RunnerCommand {

‎packages/platform-apple/src/runner-snapshot-bridge.test.ts‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { IOS_SYSTEM_SURFACE_HOSTS } from '@agent-device/contracts/ios-system-surface';
12
import { beforeEach, expect, test, vi } from 'vitest';
23
import type { AppleRunnerProvider, RunnerCommand } from '@agent-device/apple-runner';
34
import type { CaptureSnapshotInput } from '@agent-device/contracts/snapshot-runtime';
@@ -38,7 +39,8 @@ type RunnerProcess = { pid: number; processStartTime: string };
3839
* foreground process, and `describe` reads it unless the host planned another process, or answers
3940
* the refusal `refuseDescribe` names. A describe given `holdNextDescribe` reads until that promise
4041
* settles, and, like the runner, it keeps reading after the daemon stops waiting: a describe that
41-
* arrives meanwhile is refused as `bridge-read-in-flight`.
42+
* arrives meanwhile is refused as `bridge-read-in-flight`. A describe that names surface hosts is
43+
* refused as `system-surface-host-unverified`, as a sandbox that refuses the process table does.
4244
*/
4345
function bridgeRunner(state: {
4446
process: RunnerProcess;
@@ -84,6 +86,8 @@ function bridgeRunner(state: {
8486
) {
8587
return refusal('stale_target', 'target-process-changed');
8688
}
89+
if (request.surfaceHostExecutables)
90+
return refusal('unsupported', 'system-surface-host-unverified');
8791
if (state.refuseDescribe) return refusal('application_not_responding', state.refuseDescribe);
8892
if (reading) return refusal('application_not_responding', 'bridge-read-in-flight');
8993
const hold = state.holdNextDescribe;
@@ -159,10 +163,7 @@ function bridgeRoute(provider: AppleRunnerProvider) {
159163
isDiscoveryPending: () => false,
160164
targetFreshness: 'cached',
161165
},
162-
{
163-
systemSurfacePresent: async () => 'unknown',
164-
systemSurfaceForeground: async () => 'background',
165-
},
166+
async () => 'background',
166167
);
167168
const snapshot = (signal = new AbortController().signal) =>
168169
route.capture(
@@ -408,20 +409,23 @@ test('the runner runtime reads a remote Simulator through the bridge once its fo
408409
expect(verbs(sent)).toEqual(['target', 'describe']);
409410
});
410411

411-
test('a runner whose foreground read cannot answer sends the capture to XCTest without a bridge read', async () => {
412+
test('a runner whose foreground read cannot answer asks the bridge read to check the surface hosts', async () => {
412413
const { provider, sent } = bridgeRunner({
413414
process: { pid: 41, processStartTime: '1700000000.000001' },
414415
});
415416
const { snapshot, fallbacks } = runtimeSnapshots(withHostStates(provider, undefined));
416417

417418
const captured = await snapshot();
418419

419-
// The host cannot read a remote Simulator's processes, so nothing else can prove absence.
420+
const describe = sent.find((command) => command.snapshotBridge?.verb === 'describe');
421+
expect(describe?.snapshotBridge?.surfaceHostExecutables).toEqual(
422+
IOS_SYSTEM_SURFACE_HOSTS.map((host) => host.processExecutable),
423+
);
424+
// The runner could not place a host process, so the capture goes to XCTest and says why.
420425
expect(fallbacks).toHaveLength(1);
421426
expect(captured.warnings).toEqual([
422-
'Simulator AX snapshot unavailable (system-surface-probe-unavailable); used XCTest for an unverified app generation.',
427+
'Simulator AX snapshot unavailable (system-surface-host-unverified); used XCTest for this app generation.',
423428
]);
424-
expect(verbs(sent)).not.toContain('describe');
425429
});
426430

427431
test('the foreground proof starts the runner when none is live, then reads only that session', async () => {

‎packages/platform-apple/src/snapshot-route-failure-policy.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,8 @@ test('the policy gives each code of the shared refusal table its scope and conse
141141
for (const { code, consequence } of fixture.captureScoped) {
142142
// A preparation still running is classified by its failure kind, not by its code.
143143
const kind = consequence === 'bridge-preparation' ? 'preparing' : 'unsupported';
144-
expect(bridgeFailureDisposition({ kind, code }), code).toEqual({
144+
// A surface-host refusal also names the host it saw; this table fixes only scope and consequence.
145+
expect(bridgeFailureDisposition({ kind, code }), code).toMatchObject({
145146
scope: 'capture',
146147
code,
147148
consequence,

‎packages/platform-apple/src/snapshot-route.ts‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -216,12 +216,7 @@ function createSnapshotBridgeRouteCore<Target extends SnapshotBridgeRouteTarget>
216216
// A ready runner answers first, with the foreground state of every registered host: the
217217
// predicate it serves a surface by, read in a few milliseconds. When it cannot answer, the
218218
// bridge itself refuses the capture while a host process runs for this Simulator.
219-
const foreground = await readSurfaceForeground(
220-
device,
221-
input,
222-
signal,
223-
surfaceForeground,
224-
);
219+
const foreground = await readSurfaceForeground(device, input, signal, surfaceForeground);
225220
if (foreground !== 'background' && foreground !== 'unknown') {
226221
return await runSurfaceFallback(device, input, fallback, foreground.host.bundleId);
227222
}

‎packages/platform-apple/src/snapshot-source/protocol.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ test('a surface host refusal names the running host executable', () => {
143143
// registry must stay inside the bounds the guest validates.
144144
test('every registered surface host fits the bounds the guest validates', async () => {
145145
const native = await readFile(
146-
path.join(import.meta.dirname, '../../../../apple/snapshot-bridge/SnapshotBridge.m'),
146+
path.join(import.meta.dirname, '../../../../apple/snapshot-bridge/SnapshotBridgeRequest.m'),
147147
'utf8',
148148
);
149149
const bound = (name: string) => Number(native.match(new RegExp(`${name} = (\\d+);`))?.[1]);

0 commit comments

Comments
 (0)