Skip to content

Commit 9d44311

Browse files
committed
refactor: declare only the policy fields the matrix enforces (#1649 review)
The occlusion / offscreenGuard / promotion / poll columns were never consumed by resolveSelectorChainWithPolicy or selectorResolutionKnobs: changing any of them left behavior and the suite green, so they were unverifiable claims that read as truth. (My earlier source-sniffing test "verified" them by grepping caller files for marker strings — which is why it also stayed green when a row was disconnected entirely.) The matrix now declares exactly what it enforces: the ambiguity contract and the rect requirement, both consumed by the resolution interface and pinned behaviorally. A new test asserts every row's field set, so an unenforceable column cannot reappear without coverage — verified by re-adding one and watching it fail. Routing the structural stages into typed behavior is tracked in #1656 with the constraint that each field must be consumed, not merely declared.
1 parent c2afd78 commit 9d44311

2 files changed

Lines changed: 29 additions & 41 deletions

File tree

‎packages/selectors/src/internal/resolution-policy.ts‎

Lines changed: 12 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,18 @@ import type { SelectorResolutionOptions } from './public-resolution-types.ts';
2121
* Declaration-only: enforced by find's own narrowing logic, not by engine
2222
* knobs, so `selectorResolutionKnobs` rejects it at the type level.
2323
*
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).
24+
* Scope, deliberately narrow: this matrix declares the **ambiguity contract
25+
* and the rect requirement**, and nothing else. Both are consumed by
26+
* `resolveSelectorChainWithPolicy` and pinned behaviorally in
27+
* resolution-policy-parity.test.ts, so a row that stops matching its
28+
* documented semantics fails a test.
29+
*
30+
* The surrounding pipeline stages — occlusion, the off-screen guard,
31+
* hittable-ancestor promotion, and the wait poll budget — still live in the
32+
* callers and are NOT declared here. An earlier revision listed them as
33+
* columns; nothing consumed them, so they were unverifiable claims that read
34+
* as truth while being free to drift (#1649 review). Routing them into typed
35+
* behavior is tracked in #1656.
2936
*/
3037

3138
export type KnobBackedSelectorAmbiguity = 'disambiguate' | 'fail-closed' | 'first-match';
@@ -35,79 +42,43 @@ export type SelectorResolutionPolicy = {
3542
ambiguity: SelectorAmbiguityPolicy;
3643
/** Only nodes carrying a rect participate (acting paths need a tap point). */
3744
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';
4645
};
4746

4847
export const SELECTOR_RESOLUTION_POLICIES = {
4948
/** click/press/fill/focus/longPress/drag/scroll targets (resolution.ts). */
5049
act: {
5150
ambiguity: 'disambiguate',
5251
requireRect: true,
53-
occlusion: true,
54-
offscreenGuard: true,
55-
promotion: true,
56-
poll: 'none',
5752
},
5853
/** The post-miss diagnosis probe deciding "no match" vs "matched but covered". */
5954
actCoveredDiagnosis: {
6055
ambiguity: 'first-match',
6156
requireRect: true,
62-
occlusion: true,
63-
offscreenGuard: false,
64-
promotion: false,
65-
poll: 'none',
6657
},
6758
/** `get text` — reads through the same tiebreak acting uses. */
6859
readText: {
6960
ambiguity: 'disambiguate',
7061
requireRect: false,
71-
occlusion: false,
72-
offscreenGuard: false,
73-
promotion: false,
74-
poll: 'none',
7562
},
7663
/** `is` non-exists predicates and `get attrs` — ties reject, never guess. */
7764
readUnique: {
7865
ambiguity: 'fail-closed',
7966
requireRect: false,
80-
occlusion: false,
81-
offscreenGuard: false,
82-
promotion: false,
83-
poll: 'none',
8467
},
8568
/** `exists` and find's read-only actions — presence is the question. */
8669
readAny: {
8770
ambiguity: 'first-match',
8871
requireRect: false,
89-
occlusion: false,
90-
offscreenGuard: false,
91-
promotion: false,
92-
poll: 'none',
9372
},
9473
/** `wait` — first match per poll, under the wait budget. */
9574
wait: {
9675
ambiguity: 'first-match',
9776
requireRect: false,
98-
occlusion: false,
99-
offscreenGuard: false,
100-
promotion: false,
101-
poll: 'wait-budget',
10277
},
10378
/** Mutating `find` (#1625): candidates reject unless explicitly narrowed. */
10479
findAct: {
10580
ambiguity: 'reject-candidates',
10681
requireRect: true,
107-
occlusion: true,
108-
offscreenGuard: false,
109-
promotion: true,
110-
poll: 'none',
11182
},
11283
} as const satisfies Record<string, SelectorResolutionPolicy>;
11384

‎src/commands/interaction/runtime/__tests__/resolution-policy-parity.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,23 @@ test('knobs stay consistent with the ambiguity each knob-backed row names', () =
146146
}
147147
});
148148

149+
/**
150+
* The matrix may only declare what it can enforce (#1649 review). An earlier
151+
* revision carried occlusion / off-screen / promotion / poll columns that no
152+
* code consumed, so changing them left both behavior and the suite green —
153+
* an unverifiable claim reading as truth. This fails if such a field returns
154+
* without behavioral coverage.
155+
*/
156+
test('policy rows declare only the fields this matrix actually enforces', () => {
157+
for (const [name, policy] of Object.entries(SELECTOR_RESOLUTION_POLICIES)) {
158+
assert.deepEqual(
159+
Object.keys(policy).sort(),
160+
['ambiguity', 'requireRect'],
161+
`${name} declares a field the matrix cannot enforce`,
162+
);
163+
}
164+
});
165+
149166
test('the documented per-caller contracts are the ones declared', () => {
150167
assert.equal(SELECTOR_RESOLUTION_POLICIES.act.ambiguity, 'disambiguate');
151168
assert.equal(SELECTOR_RESOLUTION_POLICIES.readText.ambiguity, 'disambiguate');

0 commit comments

Comments
 (0)