Skip to content

Commit 10d511c

Browse files
committed
refactor: declare selector resolution policy as data (#1630)
Five native consumers of "resolve a selector against the screen" each hand-declared their ambiguity contract as inline requireUnique/ disambiguateAmbiguous literals, so the repo's real policy matrix was only discoverable by reading four files. SELECTOR_RESOLUTION_POLICIES (packages/selectors) now declares one row per caller — ambiguity kind plus the structural columns (rect, occlusion, off-screen guard, promotion, poll) — and selectorResolutionKnobs turns a row into the engine knobs it stands for. Callers consume rows; zero ambiguity literals remain in src. Semantics are unchanged by construction: each row was read off its call site. The matrix names what was previously implicit — act and get text disambiguate, is/get attrs fail closed, exists/find-reads and wait take the first match, mutating find rejects candidates unless narrowed (#1625). `reject-candidates` is declaration-only and rejected by selectorResolutionKnobs at the type level, because find enforces it through its own narrowing rather than engine knobs. resolution-policy-parity.test.ts gate-tests the matrix against the callers (ADR 0011's declared-plus-gate-tested pattern): knobs must match the named ambiguity contract, every claimed structural column must appear in the caller's source, the read/wait pipelines must genuinely lack the machinery they disclaim, and no caller may reintroduce an inline literal. Verified revert-sensitive: flipping readUnique to disambiguate and faking wait's occlusion column each fail it. Out of scope, unchanged, per the issue: the Maestro engine (ADR 0015) and the open click-implicit-wait product decision.
1 parent 0b8c1d7 commit 10d511c

6 files changed

Lines changed: 298 additions & 20 deletions

File tree

‎packages/selectors/src/index.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,3 +259,11 @@ function resolveSelectorChain(
259259
const result = resolveSelectorChainAst(nodes, parseSelectorChain(expression), options);
260260
return result ? { ...result, selector: result.selector.raw } : null;
261261
}
262+
export {
263+
SELECTOR_RESOLUTION_POLICIES,
264+
selectorResolutionKnobs,
265+
} from './internal/resolution-policy.ts';
266+
export type {
267+
KnobBackedSelectorAmbiguity,
268+
SelectorResolutionPolicy,
269+
} from './internal/resolution-policy.ts';
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
import type { SelectorResolutionOptions } from './public-resolution-types.ts';
2+
3+
/**
4+
* The per-caller selector-resolution policy matrix (#1630): every native
5+
* consumer of "resolve a selector against the screen" declares its ambiguity
6+
* contract here instead of passing `requireUnique`/`disambiguateAmbiguous`
7+
* literals at the call site. The engine stays policy-neutral; which row a
8+
* caller consumes IS the caller's documented contract, and changing a row is
9+
* a reviewable one-line policy change instead of a multi-file literal hunt.
10+
*
11+
* Ambiguity kinds:
12+
* - `disambiguate` — unique match required, but the engine's visible→deepest→
13+
* smallest-area tiebreak may pick a winner from an ambiguous set (acting
14+
* commands, `get text`).
15+
* - `fail-closed` — unique match required, ties reject (by design: `is`
16+
* predicates and `get attrs` must never guess).
17+
* - `first-match` — any match count accepted, first wins (existence reads and
18+
* the wait loop, where presence is the question).
19+
* - `reject-candidates` — multiple matches reject with the candidate list
20+
* unless the caller explicitly narrows (#1625's mutating-find contract).
21+
* Declaration-only: enforced by find's own narrowing logic, not by engine
22+
* knobs, so `selectorResolutionKnobs` rejects it at the type level.
23+
*
24+
* The structural columns (`occlusion`, `offscreenGuard`, `promotion`, `poll`)
25+
* document which pipeline hosts each policy; the pipelines live in the
26+
* callers, and resolution-policy-parity.test.ts gate-tests these claims
27+
* against the callers' actual imports so the matrix cannot drift into
28+
* fiction (the ADR 0011 declared-plus-gate-tested pattern).
29+
*/
30+
31+
export type KnobBackedSelectorAmbiguity = 'disambiguate' | 'fail-closed' | 'first-match';
32+
export type SelectorAmbiguityPolicy = KnobBackedSelectorAmbiguity | 'reject-candidates';
33+
34+
export type SelectorResolutionPolicy = {
35+
ambiguity: SelectorAmbiguityPolicy;
36+
/** Only nodes carrying a rect participate (acting paths need a tap point). */
37+
requireRect: boolean;
38+
/** Occlusion filtering / covered-target rejection runs in this pipeline. */
39+
occlusion: boolean;
40+
/** The winner is checked against the viewport (with the iOS rescue probe). */
41+
offscreenGuard: boolean;
42+
/** Hittable-ancestor promotion may move the dispatch point. */
43+
promotion: boolean;
44+
/** Single capture (`none`) or the wait loop's poll budget. */
45+
poll: 'none' | 'wait-budget';
46+
};
47+
48+
export const SELECTOR_RESOLUTION_POLICIES = {
49+
/** click/press/fill/focus/longPress/drag/scroll targets (resolution.ts). */
50+
act: {
51+
ambiguity: 'disambiguate',
52+
requireRect: true,
53+
occlusion: true,
54+
offscreenGuard: true,
55+
promotion: true,
56+
poll: 'none',
57+
},
58+
/** The post-miss diagnosis probe deciding "no match" vs "matched but covered". */
59+
actCoveredDiagnosis: {
60+
ambiguity: 'first-match',
61+
requireRect: true,
62+
occlusion: true,
63+
offscreenGuard: false,
64+
promotion: false,
65+
poll: 'none',
66+
},
67+
/** `get text` — reads through the same tiebreak acting uses. */
68+
readText: {
69+
ambiguity: 'disambiguate',
70+
requireRect: false,
71+
occlusion: false,
72+
offscreenGuard: false,
73+
promotion: false,
74+
poll: 'none',
75+
},
76+
/** `is` non-exists predicates and `get attrs` — ties reject, never guess. */
77+
readUnique: {
78+
ambiguity: 'fail-closed',
79+
requireRect: false,
80+
occlusion: false,
81+
offscreenGuard: false,
82+
promotion: false,
83+
poll: 'none',
84+
},
85+
/** `exists` and find's read-only actions — presence is the question. */
86+
readAny: {
87+
ambiguity: 'first-match',
88+
requireRect: false,
89+
occlusion: false,
90+
offscreenGuard: false,
91+
promotion: false,
92+
poll: 'none',
93+
},
94+
/** `wait` — first match per poll, under the wait budget. */
95+
wait: {
96+
ambiguity: 'first-match',
97+
requireRect: false,
98+
occlusion: false,
99+
offscreenGuard: false,
100+
promotion: false,
101+
poll: 'wait-budget',
102+
},
103+
/** Mutating `find` (#1625): candidates reject unless explicitly narrowed. */
104+
findAct: {
105+
ambiguity: 'reject-candidates',
106+
requireRect: true,
107+
occlusion: true,
108+
offscreenGuard: false,
109+
promotion: true,
110+
poll: 'none',
111+
},
112+
} as const satisfies Record<string, SelectorResolutionPolicy>;
113+
114+
/**
115+
* The engine knobs a knob-backed policy row stands for. `reject-candidates`
116+
* rows are rejected at the type level — that contract is enforced by the
117+
* caller's narrowing logic, not by these knobs.
118+
*/
119+
export function selectorResolutionKnobs(
120+
policy: SelectorResolutionPolicy & { ambiguity: KnobBackedSelectorAmbiguity },
121+
): Pick<SelectorResolutionOptions, 'requireRect' | 'requireUnique' | 'disambiguateAmbiguous'> {
122+
if (policy.ambiguity === 'first-match') {
123+
return { requireRect: policy.requireRect, requireUnique: false };
124+
}
125+
return {
126+
requireRect: policy.requireRect,
127+
requireUnique: true,
128+
disambiguateAmbiguous: policy.ambiguity === 'disambiguate',
129+
};
130+
}
Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
import assert from 'node:assert/strict';
2+
import { readFileSync } from 'node:fs';
3+
import path from 'node:path';
4+
import { test } from 'vitest';
5+
import {
6+
SELECTOR_RESOLUTION_POLICIES,
7+
selectorResolutionKnobs,
8+
type SelectorResolutionPolicy,
9+
} from '@agent-device/selectors';
10+
11+
/**
12+
* The matrix in resolution-policy.ts is a claim about the callers, so it is
13+
* gate-tested against them rather than trusted (ADR 0011's declared-plus-
14+
* gate-tested pattern). Two failure modes this catches: a policy row whose
15+
* knobs stop matching the ambiguity contract it names, and a structural
16+
* column (occlusion / off-screen / promotion / poll) drifting into fiction
17+
* because a caller stopped importing the machinery the row advertises.
18+
*/
19+
20+
const REPO_SRC = path.resolve(import.meta.dirname, '../../../..');
21+
22+
function readSource(relative: string): string {
23+
return readFileSync(path.join(REPO_SRC, relative), 'utf8');
24+
}
25+
26+
const CALLERS = {
27+
act: 'commands/interaction/runtime/resolution.ts',
28+
actCoveredDiagnosis: 'commands/interaction/runtime/resolution.ts',
29+
readText: 'commands/interaction/runtime/selector-read.ts',
30+
readUnique: 'commands/interaction/runtime/selector-read.ts',
31+
readAny: 'commands/interaction/runtime/selector-read.ts',
32+
wait: 'commands/interaction/runtime/selector-wait.ts',
33+
findAct: 'daemon/handlers/find.ts',
34+
} as const satisfies Record<keyof typeof SELECTOR_RESOLUTION_POLICIES, string>;
35+
36+
// What each structural column means in caller source, so the claim is
37+
// checkable rather than decorative.
38+
const OCCLUSION_MARKERS = ['isSnapshotNodeInteractionBlocked', 'interactableSelectorNodes'];
39+
const OFFSCREEN_MARKERS = ['throwIfOffscreenInteractionTarget', 'assertVisibleSelectorTarget'];
40+
const PROMOTION_MARKERS = ['resolveActionableTouchNode', 'resolveActionableNodeOrThrow'];
41+
const POLL_MARKERS = ['createWaitPolling'];
42+
43+
function mentionsAny(source: string, markers: readonly string[]): boolean {
44+
return markers.some((marker) => source.includes(marker));
45+
}
46+
47+
test('every policy row names a real caller', () => {
48+
assert.deepEqual(Object.keys(SELECTOR_RESOLUTION_POLICIES).sort(), Object.keys(CALLERS).sort());
49+
});
50+
51+
test('knobs match the ambiguity contract each row names', () => {
52+
const expected: Record<string, ReturnType<typeof selectorResolutionKnobs>> = {
53+
disambiguate: { requireRect: false, requireUnique: true, disambiguateAmbiguous: true },
54+
'fail-closed': { requireRect: false, requireUnique: true, disambiguateAmbiguous: false },
55+
'first-match': { requireRect: false, requireUnique: false },
56+
};
57+
for (const [name, policy] of Object.entries(SELECTOR_RESOLUTION_POLICIES)) {
58+
if (policy.ambiguity === 'reject-candidates') continue;
59+
const knobs = selectorResolutionKnobs(policy);
60+
const want = { ...expected[policy.ambiguity], requireRect: policy.requireRect };
61+
assert.deepEqual(knobs, want, name);
62+
}
63+
});
64+
65+
test('acting policies require a rect; read and wait policies do not', () => {
66+
assert.equal(SELECTOR_RESOLUTION_POLICIES.act.requireRect, true);
67+
assert.equal(SELECTOR_RESOLUTION_POLICIES.findAct.requireRect, true);
68+
assert.equal(SELECTOR_RESOLUTION_POLICIES.readUnique.requireRect, false);
69+
assert.equal(SELECTOR_RESOLUTION_POLICIES.readAny.requireRect, false);
70+
assert.equal(SELECTOR_RESOLUTION_POLICIES.wait.requireRect, false);
71+
});
72+
73+
test('is/get-attrs fail closed and wait never disambiguates (the by-design asymmetry)', () => {
74+
assert.equal(SELECTOR_RESOLUTION_POLICIES.readUnique.ambiguity, 'fail-closed');
75+
assert.equal(SELECTOR_RESOLUTION_POLICIES.readAny.ambiguity, 'first-match');
76+
assert.equal(SELECTOR_RESOLUTION_POLICIES.wait.ambiguity, 'first-match');
77+
assert.equal(SELECTOR_RESOLUTION_POLICIES.act.ambiguity, 'disambiguate');
78+
assert.equal(SELECTOR_RESOLUTION_POLICIES.readText.ambiguity, 'disambiguate');
79+
assert.equal(SELECTOR_RESOLUTION_POLICIES.findAct.ambiguity, 'reject-candidates');
80+
});
81+
82+
test('structural columns match what each caller actually imports', () => {
83+
const sources = new Map<string, string>();
84+
for (const relative of Object.values(CALLERS)) {
85+
if (!sources.has(relative)) sources.set(relative, readSource(relative));
86+
}
87+
for (const [name, relative] of Object.entries(CALLERS)) {
88+
const policy: SelectorResolutionPolicy =
89+
SELECTOR_RESOLUTION_POLICIES[name as keyof typeof SELECTOR_RESOLUTION_POLICIES];
90+
const source = sources.get(relative)!;
91+
if (policy.occlusion) {
92+
assert.ok(mentionsAny(source, OCCLUSION_MARKERS), `${name} claims occlusion`);
93+
}
94+
if (policy.offscreenGuard) {
95+
assert.ok(mentionsAny(source, OFFSCREEN_MARKERS), `${name} claims an off-screen guard`);
96+
}
97+
if (policy.promotion) {
98+
assert.ok(mentionsAny(source, PROMOTION_MARKERS), `${name} claims promotion`);
99+
}
100+
if (policy.poll === 'wait-budget') {
101+
assert.ok(mentionsAny(source, POLL_MARKERS), `${name} claims a poll budget`);
102+
}
103+
}
104+
});
105+
106+
test('read and wait pipelines really do skip occlusion, off-screen, and promotion', () => {
107+
// The inverse direction: a row claiming NO occlusion must not sit in a file
108+
// that performs it, or the matrix would under-report real behavior.
109+
const readSourceText = readSource(CALLERS.readUnique);
110+
const waitSource = readSource(CALLERS.wait);
111+
for (const [name, source] of [
112+
['selector-read', readSourceText],
113+
['selector-wait', waitSource],
114+
] as const) {
115+
assert.equal(mentionsAny(source, OCCLUSION_MARKERS), false, `${name} occlusion`);
116+
assert.equal(mentionsAny(source, OFFSCREEN_MARKERS), false, `${name} off-screen`);
117+
assert.equal(mentionsAny(source, PROMOTION_MARKERS), false, `${name} promotion`);
118+
}
119+
});
120+
121+
test('no caller re-declares ambiguity knobs as inline literals', () => {
122+
for (const relative of new Set(Object.values(CALLERS))) {
123+
const source = readSource(relative);
124+
assert.equal(
125+
/disambiguateAmbiguous:\s*(true|false)/.test(source),
126+
false,
127+
`${relative} declares disambiguateAmbiguous inline`,
128+
);
129+
assert.equal(
130+
/requireUnique:\s*(true|false)/.test(source),
131+
false,
132+
`${relative} declares requireUnique inline`,
133+
);
134+
}
135+
});

‎src/commands/interaction/runtime/resolution.ts‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ import {
1414
STALE_REF_HINT,
1515
type SelectorResolution,
1616
buildSelectorChainForNode,
17+
SELECTOR_RESOLUTION_POLICIES,
18+
selectorResolutionKnobs,
1719
} from '@agent-device/selectors';
1820
import { resolvePressRecordingTarget } from '../../../core/press-retarget.ts';
1921
import { requireSnapshotSession } from './selector-read-shared.ts';
@@ -277,9 +279,7 @@ async function resolveSelectorInteractionTarget(
277279
selectorExpression,
278280
{
279281
platform: runtime.backend.platform,
280-
requireRect: true,
281-
requireUnique: true,
282-
disambiguateAmbiguous: true,
282+
...selectorResolutionKnobs(SELECTOR_RESOLUTION_POLICIES.act),
283283
},
284284
);
285285
if ((!resolved || !resolved.node.rect) && params.requireInteractive) {
@@ -289,17 +289,14 @@ async function resolveSelectorInteractionTarget(
289289
selectorExpression,
290290
{
291291
platform: runtime.backend.platform,
292-
requireRect: true,
293-
requireUnique: true,
294-
disambiguateAmbiguous: true,
292+
...selectorResolutionKnobs(SELECTOR_RESOLUTION_POLICIES.act),
295293
},
296294
);
297295
}
298296
if (!resolved || !resolved.node.rect) {
299297
const covered = resolveSelectorChain(capture.snapshot.nodes, selectorExpression, {
300298
platform: runtime.backend.platform,
301-
requireRect: true,
302-
requireUnique: false,
299+
...selectorResolutionKnobs(SELECTOR_RESOLUTION_POLICIES.actCoveredDiagnosis),
303300
});
304301
if (covered?.node && isSnapshotNodeInteractionBlocked(covered.node)) {
305302
throw buildCoveredInteractionError({

‎src/commands/interaction/runtime/selector-read.ts‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ import {
1414
parseFindSelectorExpression,
1515
type FindAction,
1616
type FindLocator,
17+
SELECTOR_RESOLUTION_POLICIES,
18+
selectorResolutionKnobs,
19+
type KnobBackedSelectorAmbiguity,
20+
type SelectorResolutionPolicy,
1721
} from '@agent-device/selectors';
1822
import type { SnapshotNode } from '@agent-device/kernel/snapshot';
1923
import { isSparseSnapshotQualityVerdict } from '../../../snapshot/snapshot-quality.ts';
@@ -51,6 +55,10 @@ import {
5155
TINY_STABLE_TREE_NODE_COUNT,
5256
} from './stable-capture.ts';
5357

58+
type KnobBackedResolutionPolicy = SelectorResolutionPolicy & {
59+
ambiguity: KnobBackedSelectorAmbiguity;
60+
};
61+
5462
export type { SelectorSnapshotOptions } from './selector-read-shared.ts';
5563
export type {
5664
WaitCommandOptions,
@@ -209,7 +217,10 @@ export const getCommand: RuntimeCommand<GetCommandOptions, GetCommandResult> = a
209217

210218
const resolved = await resolveSelectorNode(runtime, options, options.session ?? 'default', {
211219
selector: options.target.selector,
212-
disambiguateAmbiguous: options.property === 'text',
220+
policy:
221+
options.property === 'text'
222+
? SELECTOR_RESOLUTION_POLICIES.readText
223+
: SELECTOR_RESOLUTION_POLICIES.readUnique,
213224
});
214225
assertExpectedResolvedTarget(
215226
resolved.node,
@@ -317,9 +328,7 @@ export const isCommand: RuntimeCommand<IsCommandOptions, IsCommandResult> = asyn
317328

318329
const resolved = resolveSelectorChain(capture.snapshot.nodes, selectorExpression, {
319330
platform: runtime.backend.platform,
320-
requireRect: false,
321-
requireUnique: true,
322-
disambiguateAmbiguous: false,
331+
...selectorResolutionKnobs(SELECTOR_RESOLUTION_POLICIES.readUnique),
323332
});
324333
if (!resolved) {
325334
throw new AppError(
@@ -472,8 +481,7 @@ async function findFirstLocatorMatch(
472481
if (selectorExpression) {
473482
const resolved = resolveSelectorChain(capture.snapshot.nodes, selectorExpression, {
474483
platform: runtime.backend.platform,
475-
requireRect: false,
476-
requireUnique: false,
484+
...selectorResolutionKnobs(SELECTOR_RESOLUTION_POLICIES.readAny),
477485
});
478486
return { capture, match: resolved?.node };
479487
}
@@ -487,7 +495,7 @@ async function resolveSelectorNode(
487495
runtime: AgentDeviceRuntime,
488496
options: GetCommandOptions,
489497
sessionName: string,
490-
params: { selector: string; disambiguateAmbiguous: boolean },
498+
params: { selector: string; policy: KnobBackedResolutionPolicy },
491499
): Promise<{ capture: CapturedSnapshot; node: SnapshotNode; selector: string; ref: string }> {
492500
const capture = await captureSelectorSnapshot(
493501
runtime,
@@ -499,9 +507,7 @@ async function resolveSelectorNode(
499507
);
500508
const resolved = resolveSelectorChain(capture.snapshot.nodes, params.selector, {
501509
platform: runtime.backend.platform,
502-
requireRect: false,
503-
requireUnique: true,
504-
disambiguateAmbiguous: params.disambiguateAmbiguous,
510+
...selectorResolutionKnobs(params.policy),
505511
});
506512
if (!resolved) {
507513
throw new AppError(

0 commit comments

Comments
 (0)