refactor: migrate wait to request-bound runtime

Author: thymikee

packages/contracts/src/facades/platform.ts

@@ -218,6 +218,8 @@ export {
   viewportRuntimeUse,
 } from '../platform-runtime-operations.ts';
 export type { SnapshotRuntimePlan } from '../platform-runtime-operations.ts';
+export { resolveWaitRuntimePlan, waitRuntimePlanUses } from '../wait-runtime-plan.ts';
+export type { WaitRuntimePlan, WaitRuntimeTarget } from '../wait-runtime-plan.ts';
 export type {
   PlatformRuntimeHost,
   PlatformRuntimeModule,

packages/contracts/src/wait-runtime-plan.ts

@@ -0,0 +1,36 @@
+import { captureSnapshotUse } from './platform-runtime-operations.ts';
+
+/** The normalized wait target, independent of the positional grammar that produced it. */
+export type WaitRuntimeTarget = 'sleep' | 'text' | 'ref' | 'selector' | 'stable';
+
+export const waitRuntimePlanUses = Object.freeze([captureSnapshotUse] as const);
+
+/**
+ * A duration wait observes nothing, so it carries **no** `use`: the absence of platform execution
+ * for that shape is a type fact, not a convention, and no admission-only bind can be introduced
+ * for it (ADR 0019 §9). Every other shape polls one capture — text and `@ref` scan the tree for a
+ * label, selector runs the selector pipeline over it, `stable` compares successive captures — so
+ * one required operation covers all four plus the timeout-surface decoration.
+ */
+export type WaitRuntimePlan =
+  | Readonly<{ kind: 'sleep' }>
+  | Readonly<{
+      kind: 'poll-capture';
+      operation: 'captureSnapshot';
+      use: typeof captureSnapshotUse;
+    }>;
+
+const sleepPlan = Object.freeze({ kind: 'sleep' } as const satisfies WaitRuntimePlan);
+
+const pollCapturePlan = Object.freeze({
+  kind: 'poll-capture',
+  operation: 'captureSnapshot',
+  use: captureSnapshotUse,
+} as const satisfies WaitRuntimePlan);
+
+/** Selects the owner-fact-backed plan for one normalized wait target. */
+export function resolveWaitRuntimePlan(
+  input: Readonly<{ target: WaitRuntimeTarget }>,
+): WaitRuntimePlan {
+  return input.target === 'sleep' ? sleepPlan : pollCapturePlan;
+}

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

@@ -523,6 +523,33 @@ export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
       operationOwners: { setViewport: ['resolveBoundViewportRuntime'] },
     },
   },
+  {
+    rule: 'R38 wait-runtime-cutover',
+    command: 'wait',
+    subject: 'wait polling capture',
+    tier: 'request-scoped',
+    execution: 'device-runtime',
+    legacyRetirement: {
+      // The two Apple fast paths wait used to select by family and by provider, plus the
+      // backend seam that existed only to carry the second of them.
+      routeNames: [
+        'dispatchDirectIosSelectorWait',
+        'findTextWithAppleRunner',
+        'findTextInMacosNonAppSurface',
+        'readAppleRunnerFindTextTarget',
+        'buildAppleRunnerFindTextOptions',
+        'captureWaitSnapshot',
+        'BackendFindTextResult',
+      ],
+    },
+    runtimeTypeNames: ['SnapshotRuntimeOperations'],
+    operations: { names: ['captureSnapshot'] },
+    singularExecution: {
+      routes: ['handleSnapshotCommands'],
+      operations: ['captureSnapshot'],
+      operationOwners: { captureSnapshot: ['resolveBoundWaitCaptureRuntime'] },
+    },
+  },
 ];
 
 function snapshotRetiredDispatchProjectionProof(

src/__tests__/test-file-size-ratchet.test.ts

@@ -34,7 +34,7 @@ const TRIPWIRE_LINES = 1_000;
 // Exact current lengths. Lower a pin when its file shrinks; never raise one — extract instead.
 const PINNED_TEST_FILE_LINES: Readonly<Record<string, number>> = Object.freeze({
   'src/__tests__/remote-connection.test.ts': 2973,
-  'src/daemon/handlers/__tests__/snapshot-handler.test.ts': 2654,
+  'src/daemon/handlers/__tests__/snapshot-handler.test.ts': 2326,
   'src/commands/interaction/runtime/settle.test.ts': 2361,
   'src/platforms/apple/core/__tests__/runner-session.test.ts': 2083,
   'src/daemon/handlers/__tests__/session-replay-runtime-maestro.test.ts': 2031,

src/backend.ts

@@ -66,10 +66,6 @@ export type BackendReadTextResult = {
   text: string;
 };
 
-export type BackendFindTextResult = {
-  found: boolean;
-};
-
 export type BackendScreenshotOptions = {
   fullscreen?: boolean;
   overlayRefs?: boolean;
@@ -434,7 +430,6 @@ export type AgentDeviceBackend = {
     options?: BackendScreenshotOptions,
   ): Promise<BackendScreenshotResult | void>;
   readText?(context: BackendCommandContext, node: SnapshotNode): Promise<BackendReadTextResult>;
-  findText?(context: BackendCommandContext, text: string): Promise<BackendFindTextResult>;
   /**
    * #1542 off-screen refusal double-check: called ONLY at the moment the
    * shared off-screen interaction guard is about to REFUSE a click/tap/

src/commands/interaction/runtime/__tests__/test-utils/index.ts

@@ -559,7 +559,6 @@ export function createSelectorDevice(
   snapshot: SnapshotState,
   options: {
     readText?: string;
-    findText?: boolean;
     now?: number;
     captureSnapshot?: () => BackendSnapshotResult | Promise<BackendSnapshotResult>;
     /**
@@ -584,7 +583,6 @@ export function createSelectorDevice(
       captureSnapshot: async () =>
         options.captureSnapshot ? await options.captureSnapshot() : { snapshot },
       readText: async () => ({ text: options.readText ?? '' }),
-      findText: async () => ({ found: options.findText ?? false }),
     } satisfies AgentDeviceBackend,
     artifacts: createLocalArtifactAdapter(),
     sessions,

src/commands/interaction/runtime/selector-read.test.ts

@@ -476,23 +476,22 @@ test('runtime find wait cancels and joins a capture that consumes its full deadl
 test('runtime selector convenience methods use explicit target helpers', async () => {
   const device = createSelectorDevice(selectorReadSnapshot(), {
     readText: 'Continue',
-    findText: true,
   });
 
   const text = await device.selectors.getText(selector('label=Continue'), { session: 'default' });
   const attrs = await device.selectors.getAttrs(ref('@e1'), { session: 'default' });
   const visible = await device.selectors.isVisible(selector('label=Continue'), {
     session: 'default',
   });
-  const waited = await device.selectors.waitForText('Ready', {
+  const waited = await device.selectors.waitForText('Continue', {
     session: 'default',
     timeoutMs: 100,
   });
 
   assert.equal(text.kind, 'text');
   assert.equal(attrs.kind, 'attrs');
   assert.equal(visible.pass, true);
-  assert.deepEqual(waited, { kind: 'text', text: 'Ready', waitedMs: 0 });
+  assert.deepEqual(waited, { kind: 'text', text: 'Continue', waitedMs: 0 });
 });
 
 // ---------------------------------------------------------------------------

src/commands/interaction/runtime/selector-wait.test.ts

@@ -52,18 +52,31 @@ test('runtime focused selector waits against a full snapshot', async () => {
   assert.equal(captureOptions?.interactiveOnly, false);
 });
 
-test('runtime wait can use backend text search', async () => {
-  const device = createSelectorDevice(selectorReadSnapshot(), {
-    findText: true,
-    now: 10,
-  });
+// A text wait has exactly one source of truth: the polled capture. The backend `findText` seam
+// that short-circuited it on Apple was wait's second platform-execution path and retired with
+// wait's ADR 0019 cutover, so the tree answer is the only answer — in both directions.
+test('runtime wait resolves text from the polled snapshot', async () => {
+  const device = createSelectorDevice(selectorReadSnapshot(), { now: 10 });
 
   const result = await device.selectors.wait({
     session: 'default',
-    target: { kind: 'text', text: 'Ready', timeoutMs: 100 },
+    target: { kind: 'text', text: 'Continue', timeoutMs: 100 },
   });
 
-  assert.deepEqual(result, { kind: 'text', text: 'Ready', waitedMs: 0 });
+  assert.deepEqual(result, { kind: 'text', text: 'Continue', waitedMs: 0 });
+});
+
+test('runtime wait times out on text the polled snapshot does not carry', async () => {
+  const device = createSelectorDevice(selectorReadSnapshot(), { clock: createFakeClock() });
+
+  await assert.rejects(
+    async () =>
+      await device.selectors.wait({
+        session: 'default',
+        target: { kind: 'text', text: 'Ready', timeoutMs: 100 },
+      }),
+    (error: Error) => error.message.includes('wait timed out for text: Ready'),
+  );
 });
 
 // ---------------------------------------------------------------------------

src/commands/interaction/runtime/selector-wait.ts

@@ -118,7 +118,6 @@ export type WaitForTextCommandOptions = WaitCommandContext &
 type SelectorWaitRuntime = {
   backend: {
     platform: PublicPlatform;
-    findText?: (context: WaitCommandContext, text: string) => Promise<{ found: boolean }>;
   };
   clock?: {
     now(): number;
@@ -364,11 +363,9 @@ async function waitForText<Runtime extends SelectorWaitRuntime>(
   const polling = createWaitPolling(runtime, options, timeoutMs, SELECTOR_PIPELINE_POLICIES.wait);
   let deadline: WaitPollDeadline | undefined;
   while (polling.hasTimeRemaining()) {
-    const poll = await polling.capture(async (signal) =>
-      runtime.backend.findText
-        ? (await runtime.backend.findText(backendContext(runtime, { ...options, signal }), text))
-            .found
-        : await snapshotContainsText(operations, runtime, { ...options, signal }, text),
+    const poll = await polling.capture(
+      async (signal) =>
+        await snapshotContainsText(operations, runtime, { ...options, signal }, text),
     );
     if (poll.timedOut) {
       deadline = poll.deadline;
@@ -436,15 +433,3 @@ async function waitForStable<Runtime extends SelectorWaitRuntime>(
       : {}),
   };
 }
-
-function backendContext(
-  runtime: SelectorWaitRuntime,
-  options: WaitCommandContext,
-): WaitCommandContext {
-  return {
-    session: options.session,
-    requestId: options.requestId,
-    signal: options.signal ?? runtime.signal,
-    metadata: options.metadata,
-  };
-}

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

@@ -282,7 +282,6 @@ test('HarmonyOS static capabilities omit runtime-backed command admissions', ()
     'settings',
     'swipe',
     'type',
-    'wait',
   ]);
 });