@@ -11,14 +11,14 @@ read/wait surfaces built on the same resolution machinery) reach the device
1111through several dispatch paths, each of which chose its latency-vs-semantics
1212trade-offs independently:
1313
14- | Path | What it is | Why it exists |
15- | ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------ --- |
16- | ` runtime-selector ` | daemon tree capture → ` resolveSelectorChain ` → guards → coordinate tap | full semantics |
17- | ` runtime-ref ` | session snapshot → ref lookup → guards → coordinate tap | full semantics |
18- | ` direct-ios-selector ` | selector sent to the XCTest runner, which queries and taps natively | saves a full snapshot round trip |
19- | ` native-ref ` | ` backend.tapTarget ` /` fillTarget ` for ` click @ref ` / ` fill @ref ` | saves resolution round trips |
20- | ` coordinate ` | raw x/y tap | escape hatch; semantics intentionally minimal |
21- | replay/maestro variants | ` allowNonHittableCoordinateFallback ` , replay-heal | third-party compat |
14+ | Path | What it is | Why it exists |
15+ | --- | --- | --- |
16+ | ` runtime-selector ` | daemon tree capture → ` resolveSelectorChain ` → guards → coordinate tap | full semantics |
17+ | ` runtime-ref ` | session snapshot → ref lookup → guards → coordinate tap | full semantics |
18+ | ` direct-ios-selector ` | selector sent to the XCTest runner, which queries and taps natively | saves a full snapshot round trip |
19+ | ` native-ref ` | ` backend.tapTarget ` /` fillTarget ` for ` click @ref ` / ` fill @ref ` | saves resolution round trips |
20+ | ` coordinate ` | raw x/y tap | escape hatch; semantics intentionally minimal |
21+ | replay/maestro variants | ` allowNonHittableCoordinateFallback ` , replay-heal | third-party compat |
2222
2323Over one week of fixes, every interaction bug we shipped or caught was the same
2424shape — a guarantee enforced on one path and silently absent on a sibling:
@@ -36,8 +36,8 @@ shape — a guarantee enforced on one path and silently absent on a sibling:
3636 ` snapshot ` — same failure mode — preserved the daemon (#1075 ).
3737
3838The guarantees themselves are small and well-implemented. What is missing is
39- any structure that _ knows the full set of paths and the full set of
40- guarantees _ and can therefore notice an unfilled cell. Reviews catch cells
39+ any structure that * knows the full set of paths and the full set of
40+ guarantees * and can therefore notice an unfilled cell. Reviews catch cells
4141only when a reviewer happens to hold both axes in their head; dogfooding
4242catches them one production incident at a time.
4343
@@ -63,14 +63,14 @@ every cell to be classified:
6363
6464``` ts
6565export const INTERACTION_GUARANTEES = [
66- ' disambiguation' , // visible > deepest > smallest; ties fail
67- ' occlusion' , // covered targets are refused
68- ' offscreen' , // tap point (rect center) must lie in the root viewport
69- ' nonHittable' , // promotion + targetHittable/hint annotation
70- ' responseConstruction' , // one shared response construction site (Layer 2)
71- ' responseIdentity' , // refLabel/selectorChain availability on this path
72- ' verifyEvidence' , // --verify baseline + post-action digest
73- ' errorTaxonomy' , // no-match/ambiguous/offscreen codes, messages, hints
66+ ' disambiguation' , // visible > deepest > smallest; ties fail
67+ ' occlusion' , // covered targets are refused
68+ ' offscreen' , // tap point (rect center) must lie in the root viewport
69+ ' nonHittable' , // promotion + targetHittable/hint annotation
70+ ' responseConstruction' , // one shared response construction site (Layer 2)
71+ ' responseIdentity' , // refLabel/selectorChain availability on this path
72+ ' verifyEvidence' , // --verify baseline + post-action digest
73+ ' errorTaxonomy' , // no-match/ambiguous/offscreen codes, messages, hints
7474] as const ;
7575```
7676
@@ -89,10 +89,11 @@ selector diagnostics and hints — because direct runner paths can close codes
8989long before full diagnostics.
9090
9191``` ts
92+
9293export type GuaranteeEnforcement =
93- | { kind: ' runtime' ; via: string } // shared TS implementation (symbol name)
94+ | { kind: ' runtime' ; via: string } // shared TS implementation (symbol name)
9495 | { kind: ' runner' ; via: string ; parityTable? : string } // Swift twin; parityTable optional until Layer 3, required once the cell claims parity
95- | { kind: ' delegated' ; to: InteractionPathId } // path defers (e.g. direct → runtime on ELEMENT_OFFSCREEN)
96+ | { kind: ' delegated' ; to: InteractionPathId } // path defers (e.g. direct → runtime on ELEMENT_OFFSCREEN)
9697 | { kind: ' waived' ; reason: string ; trackingIssue? : string }; // explicit, reviewed waiver; gap waivers must carry a tracking issue
9798
9899export const INTERACTION_DISPATCH_PATHS: Record <
@@ -102,9 +103,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<
102103 commands: readonly string [];
103104 guarantees: Record <InteractionGuarantee , GuaranteeEnforcement >;
104105 }
105- > = {
106- /* every path, every cell */
107- };
106+ > = { /* every path, every cell */ };
108107```
109108
110109Because ` guarantees ` is a ` Record ` over the guarantee union, ** tsc fails** the
@@ -194,7 +193,7 @@ guarantee needs:
194193 prove the success path too.
195194- ** A shared runtime preflight for the native-ref path** : the ref came from a
196195 daemon snapshot, so the node is already in hand — check offscreen /
197- occlusion / non-hittable against it _ before _ calling
196+ occlusion / non-hittable against it * before * calling
198197 ` tapTarget ` /` fillTarget ` . A backend fast path can silently "succeed", so
199198 delegation-on-error would never trigger there.
200199
@@ -222,7 +221,7 @@ the daemon there destroyed every healthy app session the daemon owned.
222221
223222## Consequences
224223
225- - Adding a dispatch path or a guarantee becomes a _ forced _ whole-matrix
224+ - Adding a dispatch path or a guarantee becomes a * forced * whole-matrix
226225 decision: tsc will not compile an unclassified cell, and the gate will not
227226 pass an untested one. Silent erosion is structurally impossible; explicit
228227 waivers remain possible but visible and linkable to issues.
0 commit comments