fix: tighten maestro runtime architecture

Author: thymikee

scripts/maestro-conformance-model.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseMaestroProgram } from '../src/compat/maestro/program-ir-parser.ts';
+import { MAESTRO_COMPATIBILITY_PRESETS } from '../src/compat/maestro/compatibility-policy.ts';
 import type {
   MaestroCommand,
   MaestroProgram,
@@ -20,7 +21,7 @@ import type {
 } from './maestro-conformance-types.ts';
 import { readOptionalString, readRequiredRecord } from './maestro-conformance-values.ts';
 
-const DEFAULT_SWIPE_DURATION_MS = 400;
+const UPSTREAM_DEFAULT_SWIPE_DURATION_MS = 400;
 
 export function normalizeUpstreamFixture(
   fixture: RawFixture,
@@ -87,7 +88,7 @@ function normalizeAgentCommand(
         {
           kind: command.kind,
           selector: normalizeTypedSelector(command.target),
-          timeoutMs: 17_000,
+          timeoutMs: MAESTRO_COMPATIBILITY_PRESETS.command.targetLookupTimeoutMs,
           source,
         },
       ];
@@ -139,7 +140,7 @@ function normalizeAgentSwipe(
   gesture: Extract<MaestroCommand, { kind: 'swipe' }>['gesture'],
   source: NormalizedSource,
 ): NormalizedAction {
-  const durationMs = gesture.duration ?? DEFAULT_SWIPE_DURATION_MS;
+  const durationMs = gesture.duration ?? MAESTRO_COMPATIBILITY_PRESETS.command.swipeDurationMs;
   if (gesture.kind === 'screen') {
     return { kind: 'swipe', mode: 'direction', direction: gesture.direction, durationMs, source };
   }
@@ -207,7 +208,7 @@ function normalizeUpstreamCommand(
 }
 
 function normalizeUpstreamSwipe(command: RawCommand, source: NormalizedSource): NormalizedAction {
-  const durationMs = integerOrDefault(command.duration, DEFAULT_SWIPE_DURATION_MS);
+  const durationMs = integerOrDefault(command.duration, UPSTREAM_DEFAULT_SWIPE_DURATION_MS);
   const startRelative = readOptionalString(command, 'startRelative');
   const endRelative = readOptionalString(command, 'endRelative');
   if (startRelative !== undefined || endRelative !== undefined) {

src/compat/maestro/__tests__/daemon-runtime-port-fixtures.ts

@@ -1,12 +1,7 @@
-import type { DaemonInvokeFn, DaemonRequest } from '../../../daemon/types.ts';
+import type { DaemonRequest } from '../../../daemon/types.ts';
 import type { SnapshotNode, SnapshotState } from '../../../kernel/snapshot.ts';
 import type { CreateDaemonMaestroRuntimeOperationsOptions } from '../daemon-runtime-port.ts';
 
-export type CapturedDaemonRequest = Pick<
-  DaemonRequest,
-  'command' | 'positionals' | 'input' | 'flags'
->;
-
 export const IOS_FRAME = { x: 0, y: 0, width: 402, height: 874 } as const;
 
 export function makeSnapshot(
@@ -39,26 +34,3 @@ export function makeDependencies(
     resolveGestureViewport: async () => ({ x: 0, y: 0, width: 402, height: 874 }),
   };
 }
-
-export function makeInvoke(
-  requests: CapturedDaemonRequest[],
-  response: DaemonInvokeFn = async (request) => {
-    requests.push({
-      command: request.command,
-      positionals: request.positionals,
-      input: request.input,
-      flags: request.flags,
-    });
-    return { ok: true, data: {} };
-  },
-): DaemonInvokeFn {
-  return async (request) => {
-    requests.push({
-      command: request.command,
-      positionals: request.positionals,
-      input: request.input,
-      flags: request.flags,
-    });
-    return await response(request);
-  };
-}

src/compat/maestro/__tests__/daemon-runtime-port-observation-input.test.ts

@@ -149,7 +149,6 @@ test('commits Maestro input text before dispatching an immediate tap', async ()
     'snapshot',
     'snapshot',
     'snapshot',
-    'snapshot',
     'click',
   ]);
 });

src/compat/maestro/__tests__/daemon-runtime-port-observation-scroll.test.ts

@@ -93,7 +93,7 @@ test('scrolls until the target is fully visible in the screen viewport', async (
     platform: 'ios',
   });
 
-  await port.execute({
+  const result = await port.execute({
     command: {
       kind: 'scrollUntilVisible',
       source: { line: 2 },
@@ -108,6 +108,8 @@ test('scrolls until the target is fully visible in the screen viewport', async (
 
   expect(requests.filter(({ command }) => command === 'scroll')).toHaveLength(1);
   expect(requests.filter(({ command }) => command === 'snapshot')).toHaveLength(3);
+  expect(result.observation).toMatchObject({ generation: 1, matched: true });
+  expect(result.observation?.identity).toMatch(/^maestro-observation-/);
 });
 
 test('does not treat a target larger than the viewport as fully visible', async () => {

src/compat/maestro/__tests__/daemon-runtime-port-observation.test.ts

@@ -3,11 +3,12 @@ import type { DaemonRequest } from '../../../daemon/types.ts';
 import { createDaemonMaestroRuntimePort } from '../daemon-runtime-port.ts';
 import {
   MAESTRO_OBSERVATION_POLL_MS,
+  resolveTypedMaestroTarget,
   waitForTypedSnapshotStability,
 } from '../daemon-runtime-port-observation.ts';
 import { makeBaseRequest, makeDependencies, makeSnapshot } from './daemon-runtime-port-fixtures.ts';
 
-test('does not pair an observation with later same-generation snapshots', async () => {
+test('replaces pre-mutation evidence with the stable post-mutation snapshot', async () => {
   const requests: DaemonRequest[] = [];
   let snapshots = 0;
   const port = createDaemonMaestroRuntimePort({
@@ -16,7 +17,7 @@ test('does not pair an observation with later same-generation snapshots', async
       requests.push(request);
       if (request.command !== 'snapshot') return { ok: true, data: {} };
       snapshots += 1;
-      const targetX = snapshots >= 4 ? 40 : 200;
+      const targetX = snapshots >= 2 ? 40 : 200;
       return {
         ok: true,
         data: {
@@ -49,7 +50,7 @@ test('does not pair an observation with later same-generation snapshots', async
     platform: 'ios',
   });
 
-  const observation = await port.observe({
+  await port.observe({
     condition: { kind: 'visible', selector: { id: 'ready' } },
     timeoutMs: 0,
     generation: 0,
@@ -58,7 +59,6 @@ test('does not pair an observation with later same-generation snapshots', async
   await port.execute({
     command: { kind: 'inputText', source: { line: 2 }, text: 'hello' },
     generation: 0,
-    cachedObservation: observation,
     env: {},
     invalidateObservation() {},
   });
@@ -68,8 +68,7 @@ test('does not pair an observation with later same-generation snapshots', async
       source: { line: 3 },
       target: { space: 'target', selector: { id: 'continue' } },
     },
-    generation: 0,
-    cachedObservation: observation,
+    generation: 1,
     env: {},
     invalidateObservation() {},
   });
@@ -79,10 +78,49 @@ test('does not pair an observation with later same-generation snapshots', async
     'type',
     'snapshot',
     'snapshot',
-    'snapshot',
     'click',
   ]);
   expect(requests.at(-1)?.positionals).toEqual(['id="continue"']);
+  expect(requests.at(-1)?.flags?.maestro?.expectedTapPoint).toEqual({ x: 100, y: 122 });
+});
+
+test('computes expensive target evidence only for the command policies that consume it', () => {
+  const snapshot = makeSnapshot([
+    { index: 0, type: 'Application', rect: { x: 0, y: 0, width: 402, height: 874 } },
+    {
+      index: 1,
+      parentIndex: 0,
+      type: 'Button',
+      identifier: 'continue',
+      hittable: true,
+      rect: { x: 20, y: 40, width: 120, height: 44 },
+    },
+  ]);
+  const base = {
+    context: { generation: 0, env: {} },
+    snapshot,
+    platform: 'ios' as const,
+  };
+
+  const ordinary = resolveTypedMaestroTarget({
+    ...base,
+    query: { selector: { id: 'continue' }, purpose: 'tap', timeoutMs: 0 },
+  });
+  const atomicRetry = resolveTypedMaestroTarget({
+    ...base,
+    query: {
+      selector: { id: 'continue' },
+      purpose: 'tap',
+      timeoutMs: 0,
+      allowAtomicSelectorDispatch: true,
+      includeSurfaceSignature: true,
+    },
+  });
+
+  expect(ordinary).not.toHaveProperty('surfaceSignature');
+  expect(ordinary).not.toHaveProperty('dispatchSelector');
+  expect(atomicRetry.surfaceSignature).toMatch(/^[a-f0-9]{64}$/);
+  expect(atomicRetry.dispatchSelector).toEqual({ key: 'id', value: 'continue' });
 });
 
 test('compares snapshots before sleeping and captures once beyond a zero settle budget', async () => {

src/compat/maestro/__tests__/daemon-runtime-port-support.test.ts

@@ -0,0 +1,39 @@
+import { expect, test, vi } from 'vitest';
+import { invokeMaestroPublicOperation } from '../daemon-runtime-port-support.ts';
+import { makeBaseRequest, makeDependencies } from './daemon-runtime-port-fixtures.ts';
+
+test('composes operation-specific Maestro flags with the runtime envelope', async () => {
+  const invoke = vi.fn(async () => ({ ok: true as const, data: {} }));
+
+  await invokeMaestroPublicOperation(
+    {
+      baseReq: makeBaseRequest({
+        flags: {
+          platform: 'ios',
+          maestro: { prewarmRunnerBeforeOpen: true },
+        },
+      }),
+      invoke,
+      dependencies: makeDependencies(),
+      platform: 'ios',
+    },
+    {
+      kind: 'clickSelector',
+      selector: { key: 'id', value: 'submit' },
+      expectedPoint: { x: 10, y: 20 },
+      options: {},
+    },
+  );
+
+  expect(invoke).toHaveBeenCalledWith(
+    expect.objectContaining({
+      flags: expect.objectContaining({
+        maestro: {
+          prewarmRunnerBeforeOpen: true,
+          allowNonHittableCoordinateFallback: true,
+          expectedTapPoint: { x: 10, y: 20 },
+        },
+      }),
+    }),
+  );
+});

src/compat/maestro/__tests__/runtime-port-gestures.test.ts

@@ -66,7 +66,7 @@ test('uses the structured gesture contract without observing absolute swipes', a
       to: { x: 300, y: 200 },
       durationMs: 240,
     },
-    expect.objectContaining({ generation: 0 }),
+    expect.objectContaining({ generation: 1 }),
   );
   expect(gesture).toHaveBeenNthCalledWith(
     2,
@@ -76,7 +76,7 @@ test('uses the structured gesture contract without observing absolute swipes', a
       durationMs: 400,
     },
     expect.objectContaining({
-      generation: 1,
+      generation: 2,
       gestureViewport: { x: 10, y: 20, width: 400, height: 800 },
     }),
   );
@@ -88,7 +88,7 @@ test('uses the structured gesture contract without observing absolute swipes', a
       durationMs: 300,
     },
     expect.objectContaining({
-      generation: 2,
+      generation: 3,
       gestureViewport: { x: 10, y: 20, width: 400, height: 800 },
     }),
   );
@@ -100,7 +100,7 @@ test('uses the structured gesture contract without observing absolute swipes', a
       durationMs: 400,
     },
     expect.objectContaining({
-      generation: 3,
+      generation: 4,
       gestureViewport: { x: 10, y: 20, width: 400, height: 800 },
     }),
   );

src/compat/maestro/__tests__/runtime-port.test.ts

@@ -92,7 +92,7 @@ describe('MaestroRuntimePort', () => {
         clearState: true,
         launchArguments: { kind: 'map', values: { seed: 7 } },
       },
-      generation: 0,
+      generation: 1,
       appId: 'com.example.checkout',
     });
     expect(calls[5]).toMatchObject({
@@ -104,12 +104,12 @@ describe('MaestroRuntimePort', () => {
         durationMs: 601,
       },
     });
-    expect(calls[6]).toMatchObject({ kind: 'hideKeyboard', input: {}, generation: 6 });
-    expect(calls[7]).toMatchObject({ kind: 'pressKey', input: { key: 'enter' }, generation: 7 });
+    expect(calls[6]).toMatchObject({ kind: 'hideKeyboard', input: {}, generation: 7 });
+    expect(calls[7]).toMatchObject({ kind: 'pressKey', input: { key: 'enter' }, generation: 8 });
     expect(calls[9]).toMatchObject({
       kind: 'waitForAnimationToEnd',
       input: { timeoutMs: 50 },
-      generation: 9,
+      generation: 10,
     });
     expect(calls[11]).toMatchObject({
       kind: 'runScript',
@@ -275,7 +275,7 @@ describe('MaestroRuntimePort', () => {
           }),
         }),
       }),
-      expect.objectContaining({ generation: 0 }),
+      expect.objectContaining({ generation: 1 }),
     );
     expect(gesture).toHaveBeenCalledWith(
       {
@@ -284,7 +284,7 @@ describe('MaestroRuntimePort', () => {
         durationMs: 400,
       },
       expect.objectContaining({
-        generation: 1,
+        generation: 2,
         gestureViewport: { x: 0, y: 0, width: 402, height: 874 },
       }),
     );