Skip to content

Commit 63af689

Browse files
committed
fix(find): one action-selected bind per mutating handler (ADR 0019 §9)
Review P1 on #1944: a mutating find performed up to three separate facts/admit/bind projections — capture, then focus, then type re-admitted per leg. The request handler now resolves ONE action-selected plan and binds once: - New selector intents find-focus / find-type carry combined uses (capture + focusPoint, capture + focusPoint + typeText) through the same admit-then-bind path and plan machinery every selector capture uses; the new bind arms reuse the existing capture selectors, so the shared operation owners stay single. Delegated click/fill resolve targets on the plain capture pair. - The handler threads the one bind's operations to the shared executors: executeFocusPoint is extracted as the single lexical owner of the focusPoint call (R40's owner claim follows it), and executeBoundTypeText's runtime param narrows to the operations it actually uses so find can pass its own broader bind through it. - findRuntimePlanUses becomes the full action-selected set (eight uses), and the descriptor test pins each use's exact requirement list. - Regression: find focus and find type each assert exactly one facts inspection and one bindDevice call — the pre-fix handler fails both (two and three binds respectively). Live re-verified on iPhone 17 Pro at this head: find focus and find type both execute through the single bind, route synthesized-first-responder, typed text visible in the captured tree.
1 parent 667fd0f commit 63af689

10 files changed

Lines changed: 297 additions & 79 deletions

File tree

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

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -136,15 +136,36 @@ export const selectorTextCaptureRuntimePlanUses = Object.freeze([
136136
] as const);
137137

138138
/**
139-
* `find`'s complete use set: the selector-text capture plans it shares with `get` for target
140-
* resolution and read-only legs, plus the two directly-executed mutating legs. Click/fill legs
141-
* re-invoke their own commands and carry that admission themselves.
139+
* `find`'s action-selected mutating uses (ADR 0019 §9: one bind per handler). A mutating find
140+
* resolves its target from a capture AND executes at most one direct leg, so each action's use
141+
* carries the complete requirement set and the handler binds exactly once. Click/fill legs
142+
* re-invoke their own commands, so their use is the plain capture pair.
143+
*/
144+
const findFocusCaptureUse = defineUse({ required: ['captureSnapshot', 'focusPoint'] });
145+
const findFocusCaptureWithoutActiveAppUse = defineUse({
146+
required: ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint'],
147+
});
148+
const findTypeCaptureUse = defineUse({
149+
required: ['captureSnapshot', 'focusPoint', 'typeText'],
150+
});
151+
const findTypeCaptureWithoutActiveAppUse = defineUse({
152+
required: ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint', 'typeText'],
153+
});
154+
155+
/**
156+
* `find`'s complete use set: the selector-text plans it shares with `get` for its read-only
157+
* legs, the plain capture pair for target resolution ahead of delegated click/fill, and the
158+
* action-selected combined uses for the focus and type legs it executes directly.
142159
*/
143160
export const findRuntimePlanUses = Object.freeze([
144161
selectorTextCaptureUse,
145162
selectorTextCaptureWithoutActiveAppUse,
146-
focusRuntimeUse,
147-
typeTextRuntimeUse,
163+
selectorCaptureUse,
164+
selectorCaptureWithoutActiveAppUse,
165+
findFocusCaptureUse,
166+
findFocusCaptureWithoutActiveAppUse,
167+
findTypeCaptureUse,
168+
findTypeCaptureWithoutActiveAppUse,
148169
] as const);
149170

150171
export const waitSelectorCaptureRuntimePlanUses = Object.freeze([
@@ -185,6 +206,9 @@ const selectorUsesByIntent = Object.freeze({
185206
'capture-only': selectorCaptureRuntimePlanUses,
186207
'element-text': selectorTextCaptureRuntimePlanUses,
187208
'wait-observation': waitSelectorCaptureRuntimePlanUses,
209+
// find's action-selected mutating intents: one combined use per directly-executed leg.
210+
'find-focus': Object.freeze([findFocusCaptureUse, findFocusCaptureWithoutActiveAppUse] as const),
211+
'find-type': Object.freeze([findTypeCaptureUse, findTypeCaptureWithoutActiveAppUse] as const),
188212
} as const);
189213

190214
export type SelectorCaptureRuntimeIntent = keyof typeof selectorUsesByIntent;
@@ -240,6 +264,18 @@ export function resolveSelectorCaptureRuntimePlan(
240264
input.intent,
241265
selectorUsesByIntent[input.intent],
242266
);
267+
case 'find-focus':
268+
return selectorCapturePlan(
269+
input.hasActiveApp,
270+
input.intent,
271+
selectorUsesByIntent[input.intent],
272+
);
273+
case 'find-type':
274+
return selectorCapturePlan(
275+
input.hasActiveApp,
276+
input.intent,
277+
selectorUsesByIntent[input.intent],
278+
);
243279
}
244280
}
245281

‎scripts/layering/runtime-command-cutover-table.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -635,7 +635,9 @@ export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
635635
singularExecution: {
636636
routes: ['dispatchGenericCommand'],
637637
operations: ['focusPoint'],
638-
operationOwners: { focusPoint: ['resolveBoundFocusRuntime'] },
638+
// The call moved into the shared executor when find's R35 single bind began passing its
639+
// own operations through it; one lexical owner still serves both consumers.
640+
operationOwners: { focusPoint: ['executeFocusPoint'] },
639641
},
640642
},
641643
{

‎src/core/command-descriptor/__tests__/find-runtime-execution.test.ts‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
11
import { expect, test } from 'vitest';
2-
import {
3-
findRuntimePlanUses,
4-
focusRuntimeUse,
5-
typeTextRuntimeUse,
6-
} from '@agent-device/contracts/platform';
2+
import { findRuntimePlanUses } from '@agent-device/contracts/platform';
73
import { commandDescriptors } from '../registry.ts';
84
import { BASE_COMMAND_CAPABILITY_MATRIX } from '../../capabilities.ts';
95

@@ -15,17 +11,20 @@ test('find descriptor declares its complete runtime uses with no legacy projecti
1511
kind: 'device-runtime',
1612
uses: findRuntimePlanUses,
1713
});
18-
// The complete direct-execution surface: target/read capture with the preferred element read
19-
// (shared with `get`), plus the two mutating legs find executes itself. Click/fill legs
20-
// re-invoke their own commands and carry that admission themselves.
14+
// The complete direct-execution surface, action-selected so the handler binds exactly once
15+
// (ADR 0019 §9): the read-only element-text plans shared with `get`, the plain capture pair
16+
// for delegated click/fill target resolution, and the combined capture+leg uses for the focus
17+
// and type legs find executes itself.
2118
expect(findRuntimePlanUses.map((use) => use.required)).toEqual([
2219
['captureSnapshot'],
2320
['captureSnapshot', 'captureSnapshotWithoutActiveApp'],
24-
['focusPoint'],
25-
['typeText'],
21+
['captureSnapshot'],
22+
['captureSnapshot', 'captureSnapshotWithoutActiveApp'],
23+
['captureSnapshot', 'focusPoint'],
24+
['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint'],
25+
['captureSnapshot', 'focusPoint', 'typeText'],
26+
['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint', 'typeText'],
2627
]);
27-
expect(findRuntimePlanUses).toContain(focusRuntimeUse);
28-
expect(findRuntimePlanUses).toContain(typeTextRuntimeUse);
2928
});
3029

3130
test('find leaves the capability matrix and both hand-maintained overlays', () => {

‎src/daemon/focus-runtime.ts‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,26 @@ export async function resolveBoundFocusRuntime(
4242
bindDevice: params.bindDevice,
4343
});
4444
if (admission.type === 'response') return { ok: false, response: admission.response };
45+
const runtime = admission.runtime;
4546
return {
4647
ok: true,
47-
execute: async ({ dispatchContext }) => {
48-
await admission.runtime.operations.focusPoint(focusPointInput(point, dispatchContext));
49-
return { x: point.x, y: point.y, ...successText(`Focused (${point.x}, ${point.y})`) };
50-
},
48+
execute: async ({ dispatchContext }) =>
49+
await executeFocusPoint(runtime, point, dispatchContext),
5150
};
5251
}
52+
53+
/**
54+
* The ONE place a bound `focusPoint` executes (R40; also find's focus leg, which passes the
55+
* operations of its own action-selected bind). Keeping the operation call in a single lexical
56+
* owner is what lets the cutover gate prove no parallel route exists.
57+
*/
58+
export async function executeFocusPoint(
59+
runtime: Readonly<{
60+
operations: Readonly<{ focusPoint: (input: FocusPointInput) => Promise<void> }>;
61+
}>,
62+
point: Point,
63+
context: DaemonCommandContext,
64+
): Promise<Record<string, unknown>> {
65+
await runtime.operations.focusPoint(focusPointInput(point, context));
66+
return { x: point.x, y: point.y, ...successText(`Focused (${point.x}, ${point.y})`) };
67+
}
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
import { test, expect, vi, beforeEach } from 'vitest';
2+
import type { DaemonResponse } from '../../types.ts';
3+
import { makeSessionStore } from '../../../__tests__/test-utils/store-factory.ts';
4+
import { makeIosSession } from '../../../__tests__/test-utils/session-factories.ts';
5+
import {
6+
mockFocusPoint,
7+
mockTypeText,
8+
resetGetRuntimeFixture,
9+
runtimeBindingSpies,
10+
} from './interaction-get-runtime-fixture.ts';
11+
import { invokeFindHandler } from './find-handler-fixture.ts';
12+
13+
const { mockDispatch } = vi.hoisted(() => ({ mockDispatch: vi.fn() }));
14+
15+
vi.mock('../../../core/dispatch.ts', async (importOriginal) => {
16+
const actual = await importOriginal<typeof import('../../../core/dispatch.ts')>();
17+
return {
18+
...actual,
19+
dispatchCommand: mockDispatch,
20+
resolveTargetDevice: actual.resolveTargetDevice,
21+
};
22+
});
23+
24+
vi.mock('../snapshot-interactor-capture.ts', async () => {
25+
const fixture = await import('../../__tests__/legacy-snapshot-capture-fixture.ts');
26+
return { captureSnapshotWithInteractor: fixture.captureSnapshotThroughLegacyDispatchFixture };
27+
});
28+
29+
beforeEach(() => {
30+
resetGetRuntimeFixture();
31+
mockDispatch.mockReset();
32+
});
33+
34+
async function runMutatingFind(positionals: string[], node: Record<string, unknown>) {
35+
const sessionStore = makeSessionStore();
36+
const sessionName = 'default';
37+
const session = makeIosSession(sessionName);
38+
sessionStore.set(sessionName, session);
39+
mockDispatch.mockImplementation(async (_device: unknown, command: string) =>
40+
command === 'snapshot' ? { nodes: [node] } : {},
41+
);
42+
return await invokeFindHandler({
43+
sessionName,
44+
sessionStore,
45+
positionals,
46+
invoke: async () => ({ ok: true, data: {} }) as DaemonResponse,
47+
});
48+
}
49+
50+
test('find focus performs exactly one facts inspection and one bind (ADR 0019 §9)', async () => {
51+
const response = await runMutatingFind(['Save', 'focus'], {
52+
index: 0,
53+
ref: 'e1',
54+
type: 'Button',
55+
label: 'Save',
56+
hittable: true,
57+
rect: { x: 10, y: 20, width: 100, height: 40 },
58+
});
59+
60+
expect(response?.ok).toBe(true);
61+
expect(mockFocusPoint).toHaveBeenCalledTimes(1);
62+
const spies = runtimeBindingSpies();
63+
expect(spies.inspectFacts).toHaveBeenCalledTimes(1);
64+
expect(spies.bindDevice).toHaveBeenCalledTimes(1);
65+
});
66+
67+
test('find type performs exactly one facts inspection and one bind (ADR 0019 §9)', async () => {
68+
const response = await runMutatingFind(['Email', 'type', '[email protected]'], {
69+
index: 0,
70+
ref: 'e1',
71+
type: 'TextField',
72+
label: 'Email',
73+
hittable: true,
74+
rect: { x: 10, y: 20, width: 200, height: 40 },
75+
});
76+
77+
expect(response?.ok).toBe(true);
78+
// The one bind carried both legs: the focus tap and the text entry.
79+
expect(mockFocusPoint).toHaveBeenCalledTimes(1);
80+
expect(mockTypeText).toHaveBeenCalledTimes(1);
81+
expect(mockTypeText).toHaveBeenCalledWith(expect.objectContaining({ text: '[email protected]' }));
82+
const spies = runtimeBindingSpies();
83+
expect(spies.inspectFacts).toHaveBeenCalledTimes(1);
84+
expect(spies.bindDevice).toHaveBeenCalledTimes(1);
85+
});

‎src/daemon/handlers/__tests__/interaction-get-runtime-fixture.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,8 @@ export function resetGetRuntimeFixture(): void {
6666
mockFocusPoint.mockResolvedValue(undefined);
6767
mockTypeText.mockReset();
6868
mockTypeText.mockResolvedValue(undefined);
69+
(mockInspectElementReadFacts as unknown as ReturnType<typeof vi.fn>).mockClear();
70+
(mockBindElementReadRuntime as unknown as ReturnType<typeof vi.fn>).mockClear();
6971
elementReadFixtureState.readTextAtPointAvailable = true;
7072
elementReadFixtureState.captureSnapshotAvailable = true;
7173
elementReadFixtureState.focusPointAvailable = true;
@@ -159,3 +161,14 @@ export function getRuntimeBindings(): Readonly<{
159161
}> {
160162
return { inspectFacts: mockInspectElementReadFacts, bindDevice: mockBindElementReadRuntime };
161163
}
164+
165+
/** The binding spies, exposed so handler tests can assert the ADR 0019 §9 one-bind invariant. */
166+
export function runtimeBindingSpies(): Readonly<{
167+
inspectFacts: ReturnType<typeof vi.fn>;
168+
bindDevice: ReturnType<typeof vi.fn>;
169+
}> {
170+
return {
171+
inspectFacts: mockInspectElementReadFacts as unknown as ReturnType<typeof vi.fn>,
172+
bindDevice: mockBindElementReadRuntime as unknown as ReturnType<typeof vi.fn>,
173+
};
174+
}

0 commit comments

Comments
 (0)