Skip to content

Commit b9005d8

Browse files
authored
refactor(daemon): query the iOS selector through the request-bound runtime (#3430)
* refactor(daemon): query the iOS selector through the request-bound runtime Move the last leaked platform-mechanics edge into the runtime contract: the off-screen rescue's live read (#1542) is now the CONDITIONAL `querySelector` operation on the request-bound Apple runtime, executed on the same binding the command was admitted for (ADR 0019 §2/§9). direct-ios-selector.ts keeps only the verdict projection; the daemon no longer builds an Apple runner request. - contracts: QuerySelectorInput/Result + fact cell on SelectorObservationRuntimeOperations; conditional declaration on the four captured touch uses and the four gesture tier uses (parity side: an owner without the read refuses on the capture's verdict unchanged, exactly as every non-Apple owner always did). - platform-apple: bindAppleQuerySelectorRuntime answers the read on the runner, projecting the node to rect+hittability; runner-demand classifies the operation as runner-host. - other owners and the unavailable hub: declare the cell unavailable beside findText. - delete src/daemon/apple-runner-options.ts (its last consumer retired). * refactor(apple): parse the query rect once and pin the rescue wiring end to end - replace the local readRect with @agent-device/kernel/record parseRect - build the runner-call options with { ...input.execution, signal } like bindAppleFindTextRuntime instead of a field-by-field copy - forward runtime.operations.querySelector directly; delete the no-op selectOffscreenTargetQuery wrappers - inline queryDirectIosSelector into the probe and drop the unused signal - let the CONDITIONAL fact be the whole rescue gate: the fact already refuses provider-owned and macOS leaves, so the isLocalIosRunnerSession check added nothing - daemon-route tests pin both sides of the conditional (live-rect rescue, zero-query refusal) and the Apple leaf table pins fact-and-binding parity; assert AbortError on the aborted query * chore(gates): collapse R76 to a ban on daemon-to-platform-runtime coupling and retire the dead apple-runner-options manifest entry
1 parent 1612e33 commit b9005d8

35 files changed

Lines changed: 670 additions & 645 deletions

‎docs/adr/0022-daemon-platform-runtime-coupling.md‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,11 @@ Amended 2026-10-11 by #3431: the daemon-runtime composition edges this
1010
ADR classified (the gateway/diagnostics/resource-cleanup/lifecycle edges, the provider-runtime
1111
hubs, and the platform-services and claim-recovery dynamic edges) moved out of `src/daemon/` into
1212
the process-root composition module `src/daemon-composition.ts`, which R76 does not see because it
13-
is no longer a daemon-zone importer. The R76 inventory now carries only the leaked
14-
selector-query edge (`src/daemon/direct-ios-selector.ts`); the section-2 outcomes below remain the
15-
record of how each was classified.
13+
is no longer a daemon-zone importer. #3430 then routed the leaked selector-query edge
14+
(`src/daemon/direct-ios-selector.ts`) through the request-bound runtime binding, so the R76
15+
inventory is empty; with nothing left to classify, the same change collapsed R76 to a plain ban on
16+
the coupling and deleted the classification machinery, per the rule's own kill criterion. The
17+
section-2 outcomes below remain the record of how each was classified.
1618

1719
## 1. Context
1820

@@ -30,19 +32,24 @@ or owning issue. #2278 audited all four concerns at `27a97ee619`.
3032
## 2. Decision
3133

3234
1. **Every daemon import of a root `src/platform-runtime-*.ts` module is classified as exactly
33-
one of three categories**, and the classification is owned by the machine-readable inventory
35+
one of three categories** (retired by the 2026-10-12 amendment below: the inventory
3436
`DAEMON_PLATFORM_RUNTIME_EDGES` in
35-
[`scripts/layering/daemon-platform-runtime-inventory.ts`](../../scripts/layering/daemon-platform-runtime-inventory.ts):
37+
[`scripts/layering/daemon-platform-runtime-inventory.ts`](../../scripts/layering/daemon-platform-runtime-inventory.ts)
38+
is now empty, so the classification table and its symbol-drift and staleness passes are deleted
39+
and R76 bans the coupling outright — any production `src/daemon/**` import of the family or of a
40+
root hub that reaches it is a violation. The categories and outcomes below remain the record of
41+
how each edge was judged and retired):
3642
- **Composition-essential** — assembling neutral runtime implementations at the process root.
3743
- **Daemon-policy-essential** — request admission, session ownership, conflicts, locking,
3844
cancellation, teardown ordering, artifact publication, or response/event semantics.
3945
- **Leaked platform mechanics** — platform-family operations or state that should be owned
4046
behind a deeper runtime interface or adapter; only this category creates implementation
4147
work (child issues below).
4248
The gate rule **R76 `daemon-platform-runtime-inventory`** (in `scripts/layering/check.ts`)
43-
fails the layering check on any unclassified edge, on symbol-set drift between a file and its
44-
inventory entry, and on stale entries. Observed red against a planted unclassified import
45-
before acceptance.
49+
originally failed the layering check on any unclassified edge, on symbol-set drift between a
50+
file and its inventory entry, and on stale entries; observed red against a planted unclassified
51+
import before acceptance. Since the amendment it fails on any production daemon import of the
52+
family or a hub that reaches it, in any static or dynamic form.
4653

4754
2. **Per-edge outcomes at `27a97ee619`.** Four edges are composition-essential and stay
4855
(`daemon-runtime.ts` → `platform-runtime.ts` and → `platform-runtime-host-diagnostics.ts`;
@@ -70,9 +77,11 @@ or owning issue. #2278 audited all four concerns at `27a97ee619`.
7077
relaunch-target policy, `session-selector-dispatch.ts` consumes the app-bundle-identity
7178
resolver; both edges are daemon-policy-essential, and the resolver stays the one
7279
construction path for the open plan.
73-
- **#2273/#2274** (existing) — `direct-ios-selector.ts` → `queryAppleRuntimeSelector` is the
74-
selector seam those issues own; coordination was posted there rather than opening a second
75-
selector producer.
80+
- **#2273/#2274 (done)** — the `direct-ios-selector.ts` → `queryAppleRuntimeSelector` edge is
81+
retired. The live selector read is now the `querySelector` runtime operation on the
82+
request-bound owner (`SelectorObservationRuntimeOperations`, declared CONDITIONAL on the
83+
captured touch and gesture uses), so the off-screen rescue (#1542) executes on the binding
84+
the command was already admitted for; no second selector producer was added.
7685

7786
3. **Session state and store authority are measured as a symbol-level overlay and ratcheted
7887
on the handler-owned slice.** At `27a97ee619` the overlay is 112 `SessionState` shape edges
@@ -129,8 +138,11 @@ or owning issue. #2278 audited all four concerns at `27a97ee619`.
129138

130139
## 4. Enforced by
131140

132-
- R76 `daemon-platform-runtime-inventory` and R75 `session-authority-overlay` in
133-
`scripts/layering/check.ts` (both observed red against planted violations before acceptance).
141+
- R76 `daemon-platform-runtime-inventory` — since the 2026-10-12 amendment a plain ban on the
142+
coupling rather than a classification table (the inventory is empty and its machinery is
143+
deleted) — and R75 `session-authority-overlay` in `scripts/layering/check.ts` (both observed red
144+
against planted violations before acceptance).
134145
- R7 `session-state-ownership` and the R10 merge-base ratchet for the owning-module slice.
135146
- R65 for the concrete-platform-import ban this audit builds on.
136-
- Child issues #2333 and #2334 landed (see §2.2); #2273/#2274 remain for the selector seam.
147+
- Child issues #2333 and #2334 landed (see §2.2); #2273/#2274 landed with the `querySelector`
148+
runtime operation (see §2.2).

‎docs/adr/0032-layering-graph-engine.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,8 @@ whose production tree is `7dda0c2bf`'s; the harness lives only at that commit
1414
`resolveImportEdges`. Do not enforce a subset of them from a second, disagreeing import graph.
1515
- The model's implementation remains replaceable. Besides these eight rules, it must supply
1616
resolved edges with value, type-only and dynamic kinds to R9/R10, R19, R73–R76 and
17-
`scripts/depgraph/`; named symbols and the binding residue of dynamic imports to R76; and raw
18-
specifier sites to R11 and R13. Eleven other registry entries read source ASTs or text only, and
19-
one reads paths only.
17+
`scripts/depgraph/`; named symbols to R75; and raw specifier sites to R11 and R13. Eleven other
18+
registry entries read source ASTs or text only, and one reads paths only.
2019
- Fix the demonstrated parser gap in #3293: `parseImports` misses TypeScript `import('x').T` type
2120
positions (9 file pairs). It already parses an OXC AST for dynamic imports but scans static
2221
imports with regexes; read both from that AST, `TSImportType` included, keeping symbol and

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
| [0019 Request-Bound Platform Runtime](0019-request-bound-platform-runtime.md) | platform-package boundaries/composition, device discovery, runtime facts/facets, request binding, provider ownership, platform-shaped session resources, durable reattachment, daemon-handler migration |
2424
| [0020 Composable Recorded Fragments (Proposed)](0020-composable-recorded-fragments.md) | lifecycle-free recorded fragment capture/composition, entry guards, fragment-local addresses/digests, staleness, and native `.ad`/Maestro composition |
2525
| [0021 Simlock-Leased Devices Through Ordinary Local Runtimes](0021-host-simlock-managed-device-allocation.md) | driving a Simlock-leased simulator or emulator, why agent-device has no allocator integration, and the withdrawn in-process Host design |
26-
| [0022 Daemon — Platform Runtime Coupling Audit and Ownership Ratchets](0022-daemon-platform-runtime-coupling.md) | daemon imports of root `platform-runtime-*` modules, the R76 edge classification inventory, R75 session-authority ratchet, entry-to-platform hop routes and roles |
26+
| [0022 Daemon — Platform Runtime Coupling Audit and Ownership Ratchets](0022-daemon-platform-runtime-coupling.md) | daemon imports of root `platform-runtime-*` modules, the retired R76 edge classification now collapsed to a coupling ban, R75 session-authority ratchet, entry-to-platform hop routes and roles |
2727
| [0023 End-State Entry-to-Platform Hop Trace](0023-end-state-hop-trace.md) | the hop counting definition, the ordered `press`/Android and dual-arm `snapshot`/iOS chains, per-hop roles, and the deletion test behind the numbers ADR 0019 and ADR 0022 quote |
2828
| [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, the export-exists / recorder-stopped split, backend stop-and-collect contract, recovery through the coordinator, the ADR 0019 §5 amendment and the failed-finish cleanup fix |
2929
| [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, CoreDevice display info as the only screen authority, why `simctl`'s implicit display default captures a black panel, derived (never asserted) pose, the `fold` pose control, and the Android emulator posture amendment |

‎packages/contracts/src/platform-runtime-operations.ts‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -144,24 +144,32 @@ export const perfRuntimePlanUses = Object.freeze([
144144
perfProfileReportUse,
145145
] as const);
146146
export const tapPointUse = defineUse({ required: ['tapPoint'] });
147+
// `querySelector` is the CONDITIONAL off-screen rescue read (#1542): the acting rows refuse an
148+
// off-screen target from the required capture, and an owner that can answer with a live,
149+
// tree-independent read gets one chance to overturn a false refusal. Both sides are complete:
150+
// an owner without it refuses on the capture's verdict unchanged (ADR 0019 §9 parity), which is
151+
// exactly the pre-rescue behavior every non-Apple owner always had.
147152
export const capturedTapUse = defineUse({
148153
required: ['captureSnapshot', 'tapPoint'],
149154
preferred: ['tapRef'],
150-
conditional: ['tapElementSelector'],
155+
conditional: ['tapElementSelector', 'querySelector'],
151156
});
152157
export const longPressPointUse = defineUse({ required: ['longPressPoint'] });
153158
export const capturedLongPressUse = defineUse({
154159
required: ['captureSnapshot', 'longPressPoint'],
160+
conditional: ['querySelector'],
155161
});
156162
export const hoverPointUse = defineUse({ required: ['hoverPoint'] });
157163
export const capturedHoverUse = defineUse({
158164
required: ['captureSnapshot', 'hoverPoint'],
159165
preferred: ['hoverRef'],
166+
conditional: ['querySelector'],
160167
});
161168
export const fillPointUse = defineUse({ required: ['fillPoint'] });
162169
export const capturedFillUse = defineUse({
163170
required: ['captureSnapshot', 'fillPoint'],
164171
preferred: ['fillRef'],
172+
conditional: ['querySelector'],
165173
});
166174

167175
export const clickRuntimeUses = Object.freeze([tapPointUse, capturedTapUse] as const);
@@ -223,23 +231,29 @@ export function resolveTouchRuntimePlan(
223231
* handler binds once — for the whole `swipe --count N` series as much as for one `gesture pinch`.
224232
*
225233
* Every tier binds snapshot capture with its action because capture is the fallback when the owner
226-
* has no direct viewport read. `gestureViewport` remains preferred.
234+
* has no direct viewport read. `gestureViewport` remains preferred. `querySelector` is the
235+
* CONDITIONAL off-screen rescue read the gesture rows' endpoints resolve against (same parity
236+
* argument as `capturedTapUse`): an owner without it refuses on the capture's verdict unchanged.
227237
*/
228238
const gesturePlanUse = defineUse({
229239
required: ['performGesturePlan', 'captureSnapshot'],
230240
preferred: ['gestureViewport'],
241+
conditional: ['querySelector'],
231242
});
232243
const gestureDirectionalFlingUse = defineUse({
233244
required: ['performDirectionalFlingPlan', 'captureSnapshot'],
234245
preferred: ['gestureViewport'],
246+
conditional: ['querySelector'],
235247
});
236248
const gestureMultiTouchUse = defineUse({
237249
required: ['performMultiTouchGesturePlan', 'captureSnapshot'],
238250
preferred: ['gestureViewport'],
251+
conditional: ['querySelector'],
239252
});
240253
const gestureTargetAuthoredDragUse = defineUse({
241254
required: ['performTargetAuthoredDrag', 'captureSnapshot'],
242255
preferred: ['gestureViewport'],
256+
conditional: ['querySelector'],
243257
});
244258

245259
/**

‎packages/contracts/src/platform-runtime-unavailable.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,9 +221,11 @@ export function createUnavailablePlatformRuntimeFacts(
221221
}),
222222
// The preferred text reading starts unavailable for every family, on the same sentinel as
223223
// capture: an owner that has a native reading declares it explicitly, and one that does not
224-
// sends every text wait to the canonical tree.
224+
// sends every text wait to the canonical tree. The live selector read starts unavailable for
225+
// the same reason: an owner without it refuses on its bulk-tree verdict unchanged.
225226
...selectorObservationRuntimeOperationFacts({
226227
findText: frozen.snapshot,
228+
querySelector: frozen.snapshot,
227229
}),
228230
...viewportRuntimeOperationFacts({ setViewport: frozen.viewport }),
229231
...focusRuntimeOperationFacts({ focus: frozen.focus }),

‎packages/contracts/src/runtime-operation-names.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ export const RUNTIME_OPERATION_NAMES = [
6565
'performTargetAuthoredDrag',
6666
'prepareAppleRunner',
6767
'prepareApplicationOpen',
68+
'querySelector',
6869
'readAlert',
6970
'readClipboard',
7071
'readSetting',

‎packages/contracts/src/selector-observation-runtime.ts‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import type { Rect } from '@agent-device/kernel/snapshot';
2+
import type { ElementSelectorKey } from './interactor-types.ts';
13
import type { RuntimeOperationFact } from './platform-runtime.ts';
24
import type { SessionSurface } from './session-surface.ts';
35
import type { SnapshotRuntimeExecution } from './snapshot-runtime.ts';
@@ -10,6 +12,9 @@ type ObservationInput = Readonly<{
1012

1113
export type FindTextInput = ObservationInput & Readonly<{ text: string }>;
1214

15+
export type QuerySelectorInput = ObservationInput &
16+
Readonly<{ selector: Readonly<{ key: ElementSelectorKey; value: string }> }>;
17+
1318
/**
1419
* Positive native observations are authoritative and preserve matches that an advertising owner's
1520
* bulk capture may omit. A negative observation means only "not proven by this owner"; the caller
@@ -19,17 +24,41 @@ export type FindTextInput = ObservationInput & Readonly<{ text: string }>;
1924
export type SelectorObservationResult = Readonly<{ found: boolean }>;
2025
export type FindTextResult = SelectorObservationResult;
2126

27+
/**
28+
* The live geometry the owner read for the matched node, projected to the two fields the
29+
* off-screen rescue consumes. Owners without a node-scoped live read report the operation
30+
* unavailable; the caller then refuses on its bulk-tree verdict unchanged.
31+
*/
32+
export type QuerySelectorNodeReading = Readonly<{
33+
rect: Rect;
34+
hittable: boolean;
35+
}>;
36+
37+
export type QuerySelectorResult = SelectorObservationResult &
38+
Readonly<{
39+
node?: QuerySelectorNodeReading;
40+
}>;
41+
2242
export type SelectorObservationRuntimeOperations = Readonly<{
2343
findText(input: FindTextInput): Promise<FindTextResult>;
44+
querySelector(input: QuerySelectorInput): Promise<QuerySelectorResult>;
2445
}>;
2546
export type FindTextRuntimeOperations = Pick<SelectorObservationRuntimeOperations, 'findText'>;
47+
export type QuerySelectorRuntimeOperations = Pick<
48+
SelectorObservationRuntimeOperations,
49+
'querySelector'
50+
>;
2651

2752
export type SelectorObservationRuntimeOperationFacts = Readonly<{
2853
findText: RuntimeOperationFact;
54+
querySelector: RuntimeOperationFact;
2955
}>;
3056

3157
export function selectorObservationRuntimeOperationFacts(
3258
input: SelectorObservationRuntimeOperationFacts,
3359
): SelectorObservationRuntimeOperationFacts {
34-
return Object.freeze({ findText: input.findText });
60+
return Object.freeze({
61+
findText: input.findText,
62+
querySelector: input.querySelector,
63+
});
3564
}

‎packages/platform-android/src/runtime.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -299,9 +299,11 @@ export function createAndroidPlatformRuntime(host: PlatformRuntimeHost): Platfor
299299
...screenshotRuntimeOperationFacts({
300300
capture: device.kind === 'simulator' ? screenshotKindUnavailable : available,
301301
}),
302-
// No native text reading: every text wait on this owner polls the canonical tree.
302+
// No native text reading: every text wait on this owner polls the canonical tree. No live
303+
// selector read either: the off-screen guard refuses on the capture's verdict unchanged.
303304
...selectorObservationRuntimeOperationFacts({
304305
findText: snapshotKindUnavailable,
306+
querySelector: snapshotKindUnavailable,
305307
}),
306308
...viewportRuntimeOperationFacts({ setViewport: viewportUnavailable }),
307309
...focusRuntimeOperationFacts({ focus: androidTouchFact(device) }),
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
import { beforeEach, expect, test, vi } from 'vitest';
2+
import { IOS_SIMULATOR } from '../__tests__/device-fixtures.ts';
3+
4+
const { queryAppleRunnerSelector } = vi.hoisted(() => ({
5+
queryAppleRunnerSelector: vi.fn(async (): Promise<Record<string, unknown>> => ({
6+
found: true,
7+
})),
8+
}));
9+
10+
vi.mock('../core/runner-selector-query.ts', () => ({ queryAppleRunnerSelector }));
11+
12+
import { bindAppleQuerySelectorRuntime } from '../runtime-selector-query.ts';
13+
14+
beforeEach(() => {
15+
queryAppleRunnerSelector.mockReset();
16+
queryAppleRunnerSelector.mockResolvedValue({ found: true });
17+
});
18+
19+
const APP = 'com.example.app';
20+
21+
function bind(signal?: AbortSignal) {
22+
return bindAppleQuerySelectorRuntime({
23+
device: IOS_SIMULATOR,
24+
signal: signal ?? new AbortController().signal,
25+
});
26+
}
27+
28+
test('forwards the selector, app scope, and the full runner-execution projection', async () => {
29+
await bind().querySelector({
30+
selector: { key: 'id', value: 'submit-order' },
31+
options: { appBundleId: APP },
32+
execution: {
33+
requestId: 'req-9',
34+
logPath: '/tmp/runner.log',
35+
traceLogPath: '/tmp/trace.log',
36+
verbose: true,
37+
iosXctestrunFile: '/tmp/run.xctestrun',
38+
},
39+
});
40+
41+
expect(queryAppleRunnerSelector).toHaveBeenCalledWith(
42+
IOS_SIMULATOR,
43+
{ key: 'id', value: 'submit-order' },
44+
APP,
45+
expect.objectContaining({
46+
requestId: 'req-9',
47+
logPath: '/tmp/runner.log',
48+
traceLogPath: '/tmp/trace.log',
49+
verbose: true,
50+
iosXctestrunFile: '/tmp/run.xctestrun',
51+
}),
52+
);
53+
});
54+
55+
test('refuses an already-aborted binding signal without querying the runner', async () => {
56+
const controller = new AbortController();
57+
controller.abort();
58+
59+
await expect(
60+
bind(controller.signal).querySelector({ selector: { key: 'label', value: 'Go' } }),
61+
).rejects.toMatchObject({ name: 'AbortError' });
62+
expect(queryAppleRunnerSelector).not.toHaveBeenCalled();
63+
});
64+
65+
test('projects the matched node to its rect and hittability', async () => {
66+
queryAppleRunnerSelector.mockResolvedValue({
67+
found: true,
68+
nodes: [{ index: 0, rect: { x: 1, y: 2, width: 3, height: 4 }, hittable: true }],
69+
});
70+
71+
await expect(bind().querySelector({ selector: { key: 'label', value: 'Go' } })).resolves.toEqual({
72+
found: true,
73+
node: { rect: { x: 1, y: 2, width: 3, height: 4 }, hittable: true },
74+
});
75+
});
76+
77+
test('a miss answers found:false with no node', async () => {
78+
queryAppleRunnerSelector.mockResolvedValue({ found: false, nodes: [] });
79+
80+
await expect(
81+
bind().querySelector({ selector: { key: 'label', value: 'Gone' } }),
82+
).resolves.toEqual({ found: false });
83+
});
84+
85+
test('a node without a usable rect answers found without a node (the rescue stays fail-closed)', async () => {
86+
queryAppleRunnerSelector.mockResolvedValue({ found: true, nodes: [{ index: 0 }] });
87+
88+
await expect(bind().querySelector({ selector: { key: 'label', value: 'Go' } })).resolves.toEqual({
89+
found: true,
90+
});
91+
});

‎packages/platform-apple/src/runner-demand.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ const APPLE_SIMULATOR_OPERATION_HOSTS: Readonly<
5858
captureSnapshotWithCustomActions: 'runner',
5959
captureScreenshot: 'simulator',
6060
findText: 'runner',
61+
querySelector: 'runner',
6162
readTextAtPoint: 'runner',
6263
// Every interaction and runner-driven capture.
6364
tapPoint: 'runner',

0 commit comments

Comments
 (0)