refactor: complete the find cutover onto the request-bound runtime (#1944)

* refactor: complete the find cutover onto the request-bound runtime

The deferred Wave 4 unit for #1739 (R35), unblocked by focus (R40) and type
(R41). Find's read-only legs, focus leg, and type leg already ran bound; the
one remaining direct platform execution was the mutating-target capture, which
built createSelectorCaptureRuntime without a bound capture and fell through
the legacy dispatch branch reserved for "the last one to migrate".

- The mutating path now enters resolveBoundSelectorCapture — the selector
  family's shared admit-then-bind entry, which already named find in its
  intent table — and threads the bound capture into the target capture.
- Find was that last one: `capture` on SelectorCaptureRuntimeParams is now
  required and the legacy fallback branch is deleted. The backend's `bound`
  becomes required-to-state, with the observation-free duration wait
  (`wait 400`) as the one declared absence — its runtime now carries no
  capture backend at all, so an accidental capture fails loudly instead of
  falling anywhere.
- The descriptor flips to device-runtime with findRuntimePlanUses (the
  selector-text plans shared with get, plus focusRuntimeUse and
  typeTextRuntimeUse); the capability bucket and both overlay memberships
  (HARMONYOS_SUPPORTED_COMMANDS, WEB_QUERY_COMMANDS) are deleted.
- R35 lands with the selector family's shared operation owners; the capture
  and backend tests move off the dispatch mock onto the bound seam, which is
  where the poll-deadline and private-ax-pin assertions actually live now.

Wave 4 is complete: layering recognizes 26 migrated commands.

* 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.

Author: thymikee

packages/contracts/src/facades/platform.ts

@@ -221,6 +221,7 @@ export {
   selectorTextCaptureRuntimePlanUses,
   snapshotRuntimePlanUses,
   waitSelectorCaptureRuntimePlanUses,
+  findRuntimePlanUses,
   focusRuntimeUse,
   typeTextRuntimeUse,
   viewportRuntimeUse,

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

@@ -135,6 +135,39 @@ export const selectorTextCaptureRuntimePlanUses = Object.freeze([
   selectorTextCaptureWithoutActiveAppUse,
 ] as const);
 
+/**
+ * `find`'s action-selected mutating uses (ADR 0019 §9: one bind per handler). A mutating find
+ * resolves its target from a capture AND executes at most one direct leg, so each action's use
+ * carries the complete requirement set and the handler binds exactly once. Click/fill legs
+ * re-invoke their own commands, so their use is the plain capture pair.
+ */
+const findFocusCaptureUse = defineUse({ required: ['captureSnapshot', 'focusPoint'] });
+const findFocusCaptureWithoutActiveAppUse = defineUse({
+  required: ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint'],
+});
+const findTypeCaptureUse = defineUse({
+  required: ['captureSnapshot', 'focusPoint', 'typeText'],
+});
+const findTypeCaptureWithoutActiveAppUse = defineUse({
+  required: ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint', 'typeText'],
+});
+
+/**
+ * `find`'s complete use set: the selector-text plans it shares with `get` for its read-only
+ * legs, the plain capture pair for target resolution ahead of delegated click/fill, and the
+ * action-selected combined uses for the focus and type legs it executes directly.
+ */
+export const findRuntimePlanUses = Object.freeze([
+  selectorTextCaptureUse,
+  selectorTextCaptureWithoutActiveAppUse,
+  selectorCaptureUse,
+  selectorCaptureWithoutActiveAppUse,
+  findFocusCaptureUse,
+  findFocusCaptureWithoutActiveAppUse,
+  findTypeCaptureUse,
+  findTypeCaptureWithoutActiveAppUse,
+] as const);
+
 export const waitSelectorCaptureRuntimePlanUses = Object.freeze([
   waitSelectorCaptureUse,
   waitSelectorCaptureWithoutActiveAppUse,
@@ -173,6 +206,9 @@ const selectorUsesByIntent = Object.freeze({
   'capture-only': selectorCaptureRuntimePlanUses,
   'element-text': selectorTextCaptureRuntimePlanUses,
   'wait-observation': waitSelectorCaptureRuntimePlanUses,
+  // find's action-selected mutating intents: one combined use per directly-executed leg.
+  'find-focus': Object.freeze([findFocusCaptureUse, findFocusCaptureWithoutActiveAppUse] as const),
+  'find-type': Object.freeze([findTypeCaptureUse, findTypeCaptureWithoutActiveAppUse] as const),
 } as const);
 
 export type SelectorCaptureRuntimeIntent = keyof typeof selectorUsesByIntent;
@@ -228,6 +264,18 @@ export function resolveSelectorCaptureRuntimePlan(
         input.intent,
         selectorUsesByIntent[input.intent],
       );
+    case 'find-focus':
+      return selectorCapturePlan(
+        input.hasActiveApp,
+        input.intent,
+        selectorUsesByIntent[input.intent],
+      );
+    case 'find-type':
+      return selectorCapturePlan(
+        input.hasActiveApp,
+        input.intent,
+        selectorUsesByIntent[input.intent],
+      );
   }
 }
 

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

@@ -25,9 +25,8 @@ import { retiredDispatchProjectionViolations } from './runtime-command-cutover-d
  * A row id is a report heading, so it must be unique across every stack that adds rows here.
  * `cutoverTableDefects` rejects a duplicate; lifecycle starts at R28 after the accepted
  * shutdown, install/deploy, and application-lifecycle allocations. Snapshot starts at R32;
- * diff follows at R33, viewport at R34, get at R36, is at R37, screenshot at R39, wait at R38,
- * focus at R40, and type at R41. R35 stays reserved for find, whose blockers (`focus` R40,
- * `type` R41) have both landed; its atomic cutover is the next selector-family unit.
+ * diff follows at R33, find at R35, get at R36, is at R37, screenshot at R39, wait at R38,
+ * focus at R40, and type at R41 — the Wave 4 observation family is complete.
  */
 export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
   {
@@ -508,6 +507,35 @@ export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
     },
     extensions: [diffRetiredDispatchProjectionProof],
   },
+  {
+    rule: 'R35 find-runtime-cutover',
+    command: 'find',
+    subject: 'find target resolution',
+    tier: 'request-scoped',
+    execution: 'device-runtime',
+    legacyRetirement: {
+      // The whole retirement is admission data: the capability bucket plus the two overlay set
+      // memberships. Every route name survived — what changed is that the mutating target
+      // capture now enters resolveBoundSelectorCapture like every selector read, which is why
+      // the shared owners below carry find's captures too.
+      staticCommandSets: ['HARMONYOS_SUPPORTED_COMMANDS', 'WEB_QUERY_COMMANDS'],
+    },
+    runtimeTypeNames: ['SnapshotRuntimeOperations', 'ElementTextRuntimeOperations'],
+    operations: {
+      names: ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'readTextAtPoint'],
+    },
+    singularExecution: {
+      routes: ['handleFindCommands'],
+      operations: ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'readTextAtPoint'],
+      // Find shares every owner with `get`: its captures enter the same admit-then-bind
+      // selectors and its read-only get-text leg consumes the same preferred read owner.
+      operationOwners: {
+        captureSnapshot: ['selectActiveAppSnapshot'],
+        captureSnapshotWithoutActiveApp: ['selectSnapshotWithoutActiveApp'],
+        readTextAtPoint: ['selectElementTextOperation'],
+      },
+    },
+  },
   {
     rule: 'R36 get-runtime-cutover',
     command: 'get',
@@ -607,7 +635,9 @@ export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
     singularExecution: {
       routes: ['dispatchGenericCommand'],
       operations: ['focusPoint'],
-      operationOwners: { focusPoint: ['resolveBoundFocusRuntime'] },
+      // The call moved into the shared executor when find's R35 single bind began passing its
+      // own operations through it; one lexical owner still serves both consumers.
+      operationOwners: { focusPoint: ['executeFocusPoint'] },
     },
   },
   {

src/core/__tests__/capability-plugin-routing-parity.test.ts

@@ -265,7 +265,6 @@ test('HarmonyOS static capabilities omit runtime-backed command admissions', ()
     'back',
     'click',
     'fill',
-    'find',
     'gesture',
     'home',
     'keyboard',

src/core/capabilities.ts

@@ -42,7 +42,6 @@ const HARMONYOS_SUPPORTED_COMMANDS = new Set<string>([
   'app-switcher',
   'click',
   'fill',
-  'find',
   'home',
   'gesture',
   'keyboard',
@@ -52,7 +51,7 @@ const HARMONYOS_SUPPORTED_COMMANDS = new Set<string>([
   'settings',
   'swipe',
 ]);
-const WEB_QUERY_COMMANDS = ['audio', 'find'] as const;
+const WEB_QUERY_COMMANDS = ['audio'] as const;
 const WEB_INTERACTION_COMMANDS = ['click', 'fill', 'hover', 'press', 'scroll'] as const;
 const WEB_SUPPORTED_COMMANDS = new Set<string>([
   ...WEB_QUERY_COMMANDS,

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

@@ -0,0 +1,32 @@
+import { expect, test } from 'vitest';
+import { findRuntimePlanUses } from '@agent-device/contracts/platform';
+import { commandDescriptors } from '../registry.ts';
+import { BASE_COMMAND_CAPABILITY_MATRIX } from '../../capabilities.ts';
+
+test('find descriptor declares its complete runtime uses with no legacy projection', () => {
+  const find = commandDescriptors.find(({ name }) => name === 'find');
+
+  expect(find).not.toHaveProperty('capability');
+  expect(find?.platformExecution).toEqual({
+    kind: 'device-runtime',
+    uses: findRuntimePlanUses,
+  });
+  // The complete direct-execution surface, action-selected so the handler binds exactly once
+  // (ADR 0019 §9): the read-only element-text plans shared with `get`, the plain capture pair
+  // for delegated click/fill target resolution, and the combined capture+leg uses for the focus
+  // and type legs find executes itself.
+  expect(findRuntimePlanUses.map((use) => use.required)).toEqual([
+    ['captureSnapshot'],
+    ['captureSnapshot', 'captureSnapshotWithoutActiveApp'],
+    ['captureSnapshot'],
+    ['captureSnapshot', 'captureSnapshotWithoutActiveApp'],
+    ['captureSnapshot', 'focusPoint'],
+    ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint'],
+    ['captureSnapshot', 'focusPoint', 'typeText'],
+    ['captureSnapshot', 'captureSnapshotWithoutActiveApp', 'focusPoint', 'typeText'],
+  ]);
+});
+
+test('find leaves the capability matrix and both hand-maintained overlays', () => {
+  expect(BASE_COMMAND_CAPABILITY_MATRIX).not.toHaveProperty('find');
+});

src/core/command-descriptor/__tests__/parity.test.ts

@@ -57,6 +57,7 @@ const NO_CAPABILITY_PUBLIC_COMMANDS = new Set<string>([
   PUBLIC_COMMANDS.diff,
   PUBLIC_COMMANDS.doctor,
   PUBLIC_COMMANDS.events,
+  PUBLIC_COMMANDS.find,
   PUBLIC_COMMANDS.focus,
   PUBLIC_COMMANDS.get,
   PUBLIC_COMMANDS.install,

src/core/command-descriptor/registry.ts

@@ -35,6 +35,7 @@ import {
   screenRecordingRuntimePlanUses,
   screenshotRuntimePlanUses,
   shutdownTargetUse,
+  findRuntimePlanUses,
   focusRuntimeUse,
   typeTextRuntimeUse,
   viewportRuntimeUse,
@@ -1079,10 +1080,9 @@ export const RAW_COMMAND_DESCRIPTORS = [
     recordsSessionAction: true,
     recordingEffect: findRecordingEffect,
     daemon: { route: 'find', refFrameEffect: 'may-invalidate' },
-    capability: ALL_DEVICE_COMMAND_CAPABILITY,
     timeoutPolicy: PRESERVE_DAEMON_TIMEOUT_POLICY,
     batchable: true,
-    platformExecution: LEGACY_PLATFORM_EXECUTION,
+    platformExecution: { kind: 'device-runtime', uses: findRuntimePlanUses },
   },
 
   // -- interaction (route: interaction) --

src/daemon/__tests__/selector-capture-runtime.test.ts

@@ -1,27 +1,21 @@
 import { beforeEach, expect, test, vi } from 'vitest';
-import { dispatchCommand } from '../../core/dispatch.ts';
+import type { CaptureSnapshotInput, SnapshotResult } from '@agent-device/contracts/platform';
 import { buildSnapshotPresentationKey } from '@agent-device/kernel/snapshot';
 import { makeIosSession } from '../../__tests__/test-utils/index.ts';
 import { makeSessionStore } from '../../__tests__/test-utils/store-factory.ts';
 import { createSelectorCaptureRuntime } from '../selector-capture-runtime.ts';
 
-vi.mock('../../core/dispatch.ts', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('../../core/dispatch.ts')>();
-  return {
-    ...actual,
-    dispatchCommand: vi.fn(async () => ({})),
-  };
-});
-
-vi.mock('../handlers/snapshot-interactor-capture.ts', async () => {
-  const fixture = await import('./legacy-snapshot-capture-fixture.ts');
-  return { captureSnapshotWithInteractor: fixture.captureSnapshotThroughLegacyDispatchFixture };
-});
-
-const mockDispatch = vi.mocked(dispatchCommand);
+// R35: the capture runtime executes only through its request-bound capture — there is no
+// dispatch seam left to mock, so the tests drive the bound operation the way a real admission
+// hands it over.
+const boundCapture = vi.fn(async (_input: CaptureSnapshotInput): Promise<SnapshotResult> => ({
+  backend: 'xctest',
+  nodes: [],
+}));
 
 beforeEach(() => {
-  mockDispatch.mockReset();
+  boundCapture.mockReset();
+  boundCapture.mockResolvedValue({ backend: 'xctest', nodes: [] });
 });
 
 test('selector capture cache is keyed by scoped presentation options', async () => {
@@ -35,14 +29,13 @@ test('selector capture cache is keyed by scoped presentation options', async ()
     },
   });
   sessionStore.set(sessionName, session);
-  mockDispatch.mockImplementation(async (_device, _command, _positionals, _outPath, context) => ({
+  boundCapture.mockImplementation(async (input) => ({
     backend: 'xctest',
     nodes: [
       {
         index: 0,
         type: 'Button',
-        label:
-          context && typeof context.snapshotScope === 'string' ? context.snapshotScope : 'broad',
+        label: typeof input.options?.scope === 'string' ? input.options.scope : 'broad',
       },
     ],
   }));
@@ -52,6 +45,7 @@ test('selector capture cache is keyed by scoped presentation options', async ()
     session,
     sessionStore,
     sessionName,
+    capture: boundCapture,
     req: {
       token: 't',
       session: sessionName,
@@ -68,12 +62,12 @@ test('selector capture cache is keyed by scoped presentation options', async ()
   expect(first.snapshot.nodes[0]?.label).toBe('A');
   expect(second.snapshot.nodes[0]?.label).toBe('B');
   expect(cachedSecond.snapshot.nodes[0]?.label).toBe('B');
-  expect(mockDispatch).toHaveBeenCalledTimes(2);
+  expect(boundCapture).toHaveBeenCalledTimes(2);
 });
 
 test('legacy iOS sparse recovery retries a full snapshot', async () => {
   const { runtime } = makeCaptureRuntime('selector-legacy-sparse-recovery');
-  mockDispatch
+  boundCapture
     .mockResolvedValueOnce({
       backend: 'xctest',
       nodes: [{ index: 0, type: 'Application' }],
@@ -94,14 +88,14 @@ test('legacy iOS sparse recovery retries a full snapshot', async () => {
   });
 
   expect(result.snapshot.nodes[0]?.label).toBe('Recovered');
-  expect(mockDispatch).toHaveBeenCalledTimes(2);
-  expect(mockDispatch.mock.calls[0]?.[4]).toMatchObject({ snapshotInteractiveOnly: true });
-  expect(mockDispatch.mock.calls[1]?.[4]).toMatchObject({ snapshotInteractiveOnly: false });
+  expect(boundCapture).toHaveBeenCalledTimes(2);
+  expect(boundCapture.mock.calls[0]?.[0]?.options).toMatchObject({ interactiveOnly: true });
+  expect(boundCapture.mock.calls[1]?.[0]?.options).toMatchObject({ interactiveOnly: false });
 });
 
 test('legacy iOS sparse recovery rethrows full snapshot failure when scoping is disabled', async () => {
   const { runtime } = makeCaptureRuntime('selector-legacy-sparse-rethrow');
-  mockDispatch
+  boundCapture
     .mockResolvedValueOnce({
       backend: 'xctest',
       nodes: [{ index: 0, type: 'Application' }],
@@ -119,12 +113,12 @@ test('legacy iOS sparse recovery rethrows full snapshot failure when scoping is
       },
     }),
   ).rejects.toThrow('full snapshot failed');
-  expect(mockDispatch).toHaveBeenCalledTimes(2);
+  expect(boundCapture).toHaveBeenCalledTimes(2);
 });
 
 test('sparse verdict recovery retries with query scope and stores recovered snapshot', async () => {
   const { runtime, sessionName, sessionStore } = makeCaptureRuntime('selector-sparse-verdict');
-  mockDispatch
+  boundCapture
     .mockResolvedValueOnce({
       backend: 'xctest',
       quality: {
@@ -152,10 +146,10 @@ test('sparse verdict recovery retries with query scope and stores recovered snap
 
   expect(result.snapshot.nodes[0]?.label).toBe('Search');
   expect(sessionStore.get(sessionName)?.snapshot?.nodes[0]?.label).toBe('Search');
-  expect(mockDispatch).toHaveBeenCalledTimes(2);
-  expect(mockDispatch.mock.calls[1]?.[4]).toMatchObject({
-    snapshotInteractiveOnly: false,
-    snapshotScope: 'Search',
+  expect(boundCapture).toHaveBeenCalledTimes(2);
+  expect(boundCapture.mock.calls[1]?.[0]?.options).toMatchObject({
+    interactiveOnly: false,
+    scope: 'Search',
   });
 });
 
@@ -168,6 +162,7 @@ function makeCaptureRuntime(sessionName: string) {
     session,
     sessionStore,
     sessionName,
+    capture: boundCapture,
     req: {
       token: 't',
       session: sessionName,

src/daemon/focus-runtime.ts

@@ -42,11 +42,26 @@ export async function resolveBoundFocusRuntime(
     bindDevice: params.bindDevice,
   });
   if (admission.type === 'response') return { ok: false, response: admission.response };
+  const runtime = admission.runtime;
   return {
     ok: true,
-    execute: async ({ dispatchContext }) => {
-      await admission.runtime.operations.focusPoint(focusPointInput(point, dispatchContext));
-      return { x: point.x, y: point.y, ...successText(`Focused (${point.x}, ${point.y})`) };
-    },
+    execute: async ({ dispatchContext }) =>
+      await executeFocusPoint(runtime, point, dispatchContext),
   };
 }
+
+/**
+ * The ONE place a bound `focusPoint` executes (R40; also find's focus leg, which passes the
+ * operations of its own action-selected bind). Keeping the operation call in a single lexical
+ * owner is what lets the cutover gate prove no parallel route exists.
+ */
+export async function executeFocusPoint(
+  runtime: Readonly<{
+    operations: Readonly<{ focusPoint: (input: FocusPointInput) => Promise<void> }>;
+  }>,
+  point: Point,
+  context: DaemonCommandContext,
+): Promise<Record<string, unknown>> {
+  await runtime.operations.focusPoint(focusPointInput(point, context));
+  return { x: point.x, y: point.y, ...successText(`Focused (${point.x}, ${point.y})`) };
+}