Skip to content

Commit c5bd3fd

Browse files
committed
refactor(move): split interaction target resolution by domain question
resolution.ts (1,131 lines) keeps the entry and the point/selector target kinds (249 lines). The rest moves, function bodies unchanged: - ref-target-resolution.ts (262): how an @ref becomes a node, and when it is refused (adopt/read, frame reconciliation, tryResolveRefNode, refMissRefusal). - resolution-disclosure.ts (179): what a resolution records and reports (EXACT_REF_RESOLUTION, buildRefResolution and its ResolvedRefNode type, selector disclosure, non-hittable hint, press recording retarget). - target-visibility-stages.ts (219): is the resolved target reachable on screen: the node-stage runner, the covered refusal (covered-interaction- error.ts folded in and deleted) and the off-screen stage. - native-ref-interaction.ts (135): the native-ref preflight and dispatch. - resolution-touch-point.ts (48): node to touch point, shared by the ref and selector kinds, so neither kind module owns the other. - replay-target-guard.ts (65): assertExpectedResolvedTarget and assertReplayTargetResolution, used by the ref and selector kinds and by selector-is/selector-read. - interaction-resolution-request.ts (73): InteractionAction, ResolveInteractionTargetParams and ExpectedResolvedTarget. The layering scan (R9/R10) refused the split while sibling modules type-imported resolution.ts: the largest type cycle grew from 6 to 8 files. The request types now sit below every module that reads them. Not a pure move: `export` added to symbols now crossing a module boundary; two comments that pointed at "above" now name the file; the stale fallow-ignore on EXACT_REF_RESOLUTION (now statically imported) and on pollForSelectorReadiness (already statically imported by resolution.ts) are removed. interaction-guarantees.ts `via` paths and three cross-package comments follow the symbols. resolution.test.ts (706) splits along the same seams: resolution.test.ts 350, ref-target-resolution.test.ts 126, resolution-disclosure.test.ts 19, target-visibility-stages.test.ts 227. Test bodies unchanged. git diff -M90% --stat: 24 files changed, 1399 insertions(+), 1312 deletions(-). No file passes the 90% rename threshold (it is a split); resolution.ts +18/-900, resolution.test.ts +1/-357. A line-multiset comparison of old against new bodies (imports and blank lines excluded) differs only in the export keywords and comments listed above. No fallow baseline entry was keyed on the moved paths.
1 parent 5b23c92 commit c5bd3fd

24 files changed

Lines changed: 1399 additions & 1312 deletions

‎packages/ad-script/src/internal/target-annotation-identity.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ type IdentityTreeNode = Pick<RawSnapshotNode, 'type' | 'identifier' | 'label'>;
5252
* (`@agent-device/selectors/target-evidence`), replay-time verification
5353
* (`packages/replay-port/src/daemon-port/session-replay-target-verification.ts`), and the
5454
* dispatch-side post-resolution guard
55-
* (`src/commands/interaction/runtime/resolution.ts`), so all three compute
55+
* (`src/commands/interaction/runtime/replay-target-guard.ts`), so all three compute
5656
* a node's identity with byte-identical semantics.
5757
*/
5858
export function readNodeLocalIdentity(

‎packages/contracts/src/interaction-guarantees.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ const RUNTIME_TREE_SHARED_GUARANTEES = {
240240
// them is undetected.
241241
offscreen: {
242242
kind: 'runtime',
243-
via: 'src/commands/interaction/runtime/resolution.ts#throwIfOffscreenInteractionTarget',
243+
via: 'src/commands/interaction/runtime/target-visibility-stages.ts#throwIfOffscreenInteractionTarget',
244244
},
245245
// Promotion runs only for rows that declare it (#1656); the retarget itself
246246
// is still resolveActionableTouchResolution.
@@ -316,7 +316,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
316316
// provenance before it can claim exact.
317317
resolutionDisclosure: {
318318
kind: 'runtime',
319-
via: 'src/commands/interaction/runtime/resolution.ts#buildRefResolution',
319+
via: 'src/commands/interaction/runtime/resolution-disclosure.ts#buildRefResolution',
320320
},
321321
targetReadiness: {
322322
kind: 'inapplicable',
@@ -349,7 +349,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
349349
},
350350
offscreen: {
351351
kind: 'runtime',
352-
via: 'src/commands/interaction/runtime/resolution.ts#throwIfOffscreenInteractionTarget',
352+
via: 'src/commands/interaction/runtime/target-visibility-stages.ts#throwIfOffscreenInteractionTarget',
353353
},
354354
nonHittable: {
355355
kind: 'inapplicable',
@@ -433,14 +433,14 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
433433
// practice, but the code path is identical.
434434
offscreen: {
435435
kind: 'runtime',
436-
via: 'src/commands/interaction/runtime/resolution.ts#throwIfOffscreenInteractionTarget',
436+
via: 'src/commands/interaction/runtime/target-visibility-stages.ts#throwIfOffscreenInteractionTarget',
437437
},
438438
// Annotation only (targetHittable/hint on the result): promotion to a
439439
// hittable ancestor stays a runtime-path behavior — the preflight never
440440
// changes which element the backend acts on.
441441
nonHittable: {
442442
kind: 'runtime',
443-
via: 'src/commands/interaction/runtime/resolution.ts#preflightNativeRefInteraction',
443+
via: 'src/commands/interaction/runtime/native-ref-interaction.ts#preflightNativeRefInteraction',
444444
},
445445
responseConstruction: SHARED_RESPONSE_CONSTRUCTION,
446446
responseIdentity: {
@@ -464,7 +464,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
464464
// An @ref names exactly one node by construction (same cell as runtime-ref).
465465
resolutionDisclosure: {
466466
kind: 'runtime',
467-
via: 'src/commands/interaction/runtime/resolution.ts#EXACT_REF_RESOLUTION',
467+
via: 'src/commands/interaction/runtime/resolution-disclosure.ts#EXACT_REF_RESOLUTION',
468468
},
469469
targetReadiness: {
470470
kind: 'waived',

‎packages/contracts/src/replay.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ export type ReplayTargetGuardDenotation = {
3030
/**
3131
* `details.reason` marker on the pre-action refusal thrown by dispatch's
3232
* post-resolution guard (`assertExpectedResolvedTarget`,
33-
* `src/commands/interaction/runtime/resolution.ts`), detected by the replay
33+
* `src/commands/interaction/runtime/replay-target-guard.ts`), detected by the replay
3434
* step loop to convert the refusal into an identity-mismatch target-binding
3535
* divergence.
3636
*/

‎packages/selectors/src/selector-pipeline-policy.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ export type SelectorOcclusionStage = 'exclude-and-refuse' | 'refuse' | 'ignore';
3838

3939
/**
4040
* Consumed by `throwIfOffscreenInteractionTarget`
41-
* (commands/interaction/runtime/resolution.ts), the end-to-end enforcement
41+
* (commands/interaction/runtime/target-visibility-stages.ts), the end-to-end enforcement
4242
* point including the iOS live-rect rescue probe (#1542).
4343
*
4444
* - `refuse` — a target whose tap point lies outside the viewport refuses

‎src/commands/interaction/runtime/covered-interaction-error.ts‎

Lines changed: 0 additions & 28 deletions
This file was deleted.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,12 @@ import {
2727
} from './post-action-observation.ts';
2828
import {
2929
assertSupportedInteractionSurface,
30-
dispatchNativeRefInteraction,
3130
resolveInteractionTarget,
32-
type ExpectedResolvedTarget,
3331
type InteractionTarget,
3432
type ResolvedInteractionTarget,
3533
} from './resolution.ts';
34+
import { dispatchNativeRefInteraction } from './native-ref-interaction.ts';
35+
import type { ExpectedResolvedTarget } from './interaction-resolution-request.ts';
3636
import { captureInteractionSnapshot } from './interaction-snapshot-capture.ts';
3737
import { resolveVisibleSnapshotViewport } from './viewport.ts';
3838

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import type { ActingPipelinePolicy } from '@agent-device/selectors/selector-pipeline-policy';
2+
import type { PreresolvedInteractionTarget } from '@agent-device/contracts/interaction';
3+
import type { ReplayTargetGuardDenotation } from '@agent-device/contracts/replay';
4+
5+
/**
6+
* ADR 0012 migration step 4, post-resolution guard: the LOCAL identity AND
7+
* the STRUCTURAL denotation (pre-order document index + same-parent sibling
8+
* ordinal) of the element replay's pre-action verification isolated. Set ONLY
9+
* by the replay step loop (via `DaemonRequest.internal.replayTargetGuard`) for
10+
* annotated verified actions — never on live interactive commands.
11+
*
12+
* Local identity alone is insufficient: ADR path 6 isolates ONE member among
13+
* several nodes that share the same `{id, role, label}` using sibling /
14+
* region-scoped viewportOrder. If verification isolates duplicate A but
15+
* dispatch's occlusion/visibility filtering selects duplicate B with the same
16+
* local identity, a local-identity-only guard would pass and tap the wrong
17+
* element. The structural denotation is the discriminator that catches that
18+
* split BEFORE the device action.
19+
*/
20+
export type ExpectedResolvedTarget = ReplayTargetGuardDenotation;
21+
22+
export type InteractionAction =
23+
| 'click'
24+
| 'press'
25+
| 'fill'
26+
| 'focus'
27+
| 'longPress'
28+
| 'hover'
29+
| 'scroll'
30+
| 'swipe'
31+
| 'pinch'
32+
| 'pan'
33+
| 'drag'
34+
| 'fling'
35+
| 'rotate'
36+
| 'transform';
37+
38+
export type ResolveInteractionTargetParams = {
39+
action: InteractionAction;
40+
requireInteractive: boolean;
41+
/**
42+
* The structural pipeline this action runs (#1656): occlusion, off-screen,
43+
* and hittable-ancestor promotion are the row's decisions. `promotedTarget`
44+
* for tap-shaped actions, `resolvedTarget` for the actions that must keep
45+
* the element they resolved.
46+
*/
47+
pipeline: ActingPipelinePolicy;
48+
/**
49+
* How long a `promotedTarget` row may poll for a target that does not exist yet (never model- or
50+
* CLI-writable); `resolveSelectorInteractionTarget` caps it at the row's `maxTimeoutMs`. Anything
51+
* other than a positive integer, and every `resolvedTarget` row, takes one attempt.
52+
*/
53+
readinessTimeoutMs?: number;
54+
/**
55+
* `--verify` (#1047): also capture the pre-action node set for a `point` target
56+
* so `changedFromBefore` evidence has a baseline. Ref/selector targets already
57+
* capture a snapshot to resolve the target, so this is a no-op cost for them —
58+
* their nodes are attached below regardless of this flag. For point targets,
59+
* which normally skip capture entirely, this opts into one extra capture, only
60+
* when the caller explicitly asked for verify evidence. Defaults to false.
61+
*/
62+
captureEvidenceBaseline?: boolean;
63+
/** ADR 0012 step 4 post-resolution guard; see `ExpectedResolvedTarget`. */
64+
expectedResolvedTarget?: ExpectedResolvedTarget;
65+
/** Identifies one endpoint when a multi-target replay guard refuses. */
66+
replayTargetRole?: 'source' | 'destination';
67+
/**
68+
* #1654: the caller already resolved this `@ref` against its own capture, so
69+
* the ref branch adopts that node instead of looking the ref up again. Ref
70+
* targets only — a selector target has nothing pre-resolved to adopt.
71+
*/
72+
preresolvedTarget?: PreresolvedInteractionTarget;
73+
};

‎src/commands/interaction/runtime/interaction-verb.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { InteractionAction } from './resolution.ts';
1+
import type { InteractionAction } from './interaction-resolution-request.ts';
22

33
/**
44
* The passive verb a refusal uses for the action it declined, so every acting guard that refuses

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

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,9 @@ import {
1919
planPostActionObservation,
2020
type PostActionObservationOptions,
2121
} from './post-action-observation.ts';
22-
import {
23-
dispatchNativeRefInteraction,
24-
resolveInteractionTarget,
25-
type ExpectedResolvedTarget,
26-
type InteractionTarget,
27-
} from './resolution.ts';
22+
import { resolveInteractionTarget, type InteractionTarget } from './resolution.ts';
23+
import { dispatchNativeRefInteraction } from './native-ref-interaction.ts';
24+
import type { ExpectedResolvedTarget } from './interaction-resolution-request.ts';
2825

2926
export { focusCommand, hoverCommand, longPressCommand } from './gestures.ts';
3027
export type {

‎src/commands/interaction/runtime/keyboard-occlusion.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import {
1313
type KeyboardSurface,
1414
} from '@agent-device/contracts/tap-keyboard-occlusion';
1515
import { interactionVerb } from './interaction-verb.ts';
16-
import type { InteractionAction } from './resolution.ts';
16+
import type { InteractionAction } from './interaction-resolution-request.ts';
1717

1818
/**
1919
* The keyboard guard every acting path runs against the tree it already holds.

0 commit comments

Comments
 (0)