fix: stabilize maestro ci contracts

Author: thymikee

src/compat/maestro/runtime-port-observation.ts

@@ -95,26 +95,42 @@ function isRect(value: unknown): value is { x: number; y: number; width: number;
 }
 
 function validateTargetMatch(match: MaestroTargetMatch, generation: number): MaestroTargetMatch {
+  assertMatchingGeneration(match, generation);
+  assertValidCandidateCount(match);
+  assertValidGeometry(match);
+  assertValidSurfaceSignature(match);
+  return match;
+}
+
+function assertMatchingGeneration(match: MaestroTargetMatch, generation: number): void {
   if (match.generation !== generation) {
     throw new AppError(
       'COMMAND_FAILED',
       `Maestro target evidence generation ${match.generation} does not match ${generation}.`,
     );
   }
+}
+
+function assertValidCandidateCount(match: MaestroTargetMatch): void {
   if (!Number.isInteger(match.candidateCount) || match.candidateCount < 0) {
     throw new AppError('COMMAND_FAILED', 'Maestro target evidence has an invalid candidate count.');
   }
+}
+
+function assertValidGeometry(match: MaestroTargetMatch): void {
   if (
     (match.rect !== undefined && !isRect(match.rect)) ||
     (match.viewport !== undefined && !isRect(match.viewport))
   ) {
     throw new AppError('COMMAND_FAILED', 'Maestro target evidence has invalid geometry.');
   }
+}
+
+function assertValidSurfaceSignature(match: MaestroTargetMatch): void {
   if (match.surfaceSignature !== undefined && typeof match.surfaceSignature !== 'string') {
     throw new AppError(
       'COMMAND_FAILED',
       'Maestro target evidence has an invalid surface signature.',
     );
   }
-  return match;
 }

src/compat/maestro/runtime-target-matching.ts

@@ -1,4 +1,8 @@
 import type { SnapshotNode, SnapshotState } from '../../kernel/snapshot.ts';
+import {
+  buildSnapshotNodeByIndex,
+  isDescendantOfSnapshotNode,
+} from '../../snapshot/snapshot-processing.ts';
 import type { MaestroSelector } from './program-ir.ts';
 import { matchesMaestroTypedSelector } from './runtime-target-policy.ts';
 
@@ -9,3 +13,22 @@ export function findMaestroTypedSelectorMatches(
 ): SnapshotNode[] {
   return snapshot.nodes.filter((node) => matchesMaestroTypedSelector(node, selector));
 }
+
+export function scopeMaestroMatchesByAncestor(
+  snapshot: SnapshotState,
+  matches: SnapshotNode[],
+  childOf: MaestroSelector | undefined,
+): { matches: SnapshotNode[]; parentMatched: boolean } {
+  if (!childOf) return { matches, parentMatched: true };
+  const parents = findMaestroTypedSelectorMatches(snapshot, childOf);
+  if (parents.length === 0) return { matches: [], parentMatched: false };
+  const nodeByIndex = buildSnapshotNodeByIndex(snapshot.nodes);
+  return {
+    matches: matches.filter((node) =>
+      parents.some((parent) =>
+        isDescendantOfSnapshotNode(snapshot.nodes, node, parent, nodeByIndex),
+      ),
+    ),
+    parentMatched: true,
+  };
+}

src/compat/maestro/runtime-targets.ts

@@ -5,12 +5,11 @@ import {
   type SnapshotState,
 } from '../../kernel/snapshot.ts';
 import { presentIosInteractiveSnapshot } from '../../daemon/snapshot-presentation/ios/index.ts';
-import {
-  buildSnapshotNodeByIndex,
-  isDescendantOfSnapshotNode,
-} from '../../snapshot/snapshot-processing.ts';
 import type { MaestroSelector } from './program-ir.ts';
-import { findMaestroTypedSelectorMatches } from './runtime-target-matching.ts';
+import {
+  findMaestroTypedSelectorMatches,
+  scopeMaestroMatchesByAncestor,
+} from './runtime-target-matching.ts';
 import { filterVisibleMaestroMatches, type MaestroPlatform } from './runtime-target-policy.ts';
 import {
   normalizeMaestroSnapshotMatches,
@@ -51,20 +50,15 @@ export function resolveMaestroTargetFromSnapshot(
 ): MaestroTargetResolution {
   let matches = findMaestroTypedSelectorMatches(snapshot, query.selector);
   if (query.childOf) {
-    const parents = findMaestroTypedSelectorMatches(snapshot, query.childOf);
-    if (parents.length === 0) {
+    const scoped = scopeMaestroMatchesByAncestor(snapshot, matches, query.childOf);
+    if (!scoped.parentMatched) {
       return {
         ok: false,
         message: 'Maestro childOf parent did not match.',
         evidence: buildMaestroTargetEvidence(query, matches, [], undefined),
       };
     }
-    const nodeByIndex = buildSnapshotNodeByIndex(snapshot.nodes);
-    matches = matches.filter((node) =>
-      parents.some((parent) =>
-        isDescendantOfSnapshotNode(snapshot.nodes, node, parent, nodeByIndex),
-      ),
-    );
+    matches = scoped.matches;
   }
 
   const visible = filterVisibleMaestroMatches({ nodes: snapshot.nodes, matches, platform });

src/core/dispatch-context.ts

@@ -81,5 +81,6 @@ export type DispatchContext = ScreenshotDispatchFlags & {
     value: string;
     raw: string;
     allowNonHittableCoordinateFallback?: boolean;
+    expectedPoint?: Point;
   };
 };

src/daemon/handlers/session-replay-maestro-failure.ts

@@ -3,18 +3,17 @@ import { formatMaestroCommandProgress } from '../../compat/maestro/progress.ts';
 import type { MaestroCommand, MaestroSelector } from '../../compat/maestro/program-ir.ts';
 import { evaluateMaestroReplayResume } from '../../compat/maestro/replay-plan.ts';
 import type { MaestroReplayPlan } from '../../compat/maestro/replay-plan-types.ts';
-import { findMaestroTypedSelectorMatches } from '../../compat/maestro/runtime-target-matching.ts';
+import {
+  findMaestroTypedSelectorMatches,
+  scopeMaestroMatchesByAncestor,
+} from '../../compat/maestro/runtime-target-matching.ts';
 import {
   filterVisibleMaestroMatches,
   matchesMaestroTypedSelector,
 } from '../../compat/maestro/runtime-target-policy.ts';
 import { normalizeMaestroSnapshotMatches } from '../../compat/maestro/runtime-target-ranking.ts';
 import type { DaemonError } from '../../kernel/contracts.ts';
 import type { SnapshotNode } from '../../kernel/snapshot.ts';
-import {
-  buildSnapshotNodeByIndex,
-  isDescendantOfSnapshotNode,
-} from '../../snapshot/snapshot-processing.ts';
 import {
   REPLAY_DIVERGENCE_SUGGESTION_LIMIT,
   createReplayDivergenceSanitizer,
@@ -236,14 +235,7 @@ function collectTypedMaestroCandidates(
 ): SnapshotNode[] {
   let matches = findMaestroTypedSelectorMatches(snapshot, query.selector);
   if (query.childOf) {
-    const parents = findMaestroTypedSelectorMatches(snapshot, query.childOf);
-    if (parents.length === 0) return [];
-    const nodeByIndex = buildSnapshotNodeByIndex(snapshot.nodes);
-    matches = matches.filter((node) =>
-      parents.some((parent) =>
-        isDescendantOfSnapshotNode(snapshot.nodes, node, parent, nodeByIndex),
-      ),
-    );
+    matches = scopeMaestroMatchesByAncestor(snapshot, matches, query.childOf).matches;
   }
 
   const visible = filterVisibleMaestroMatches({

src/daemon/handlers/session-replay-maestro-runtime.ts

@@ -64,7 +64,7 @@ type TypedMaestroReplayState = {
 type TypedMaestroReplayContext = {
   filePath: string;
   program: MaestroProgram;
-  device: DeviceInfo;
+  device?: DeviceInfo;
   platform: Extract<MaestroPlatform, 'android' | 'ios'>;
   target: string;
   runtimeHints: ReturnType<typeof resolveEffectiveOpenRuntimeHints>;
@@ -74,6 +74,11 @@ type TypedMaestroReplayContext = {
   loadProgram: ReturnType<typeof createMaestroProgramLoader>;
 };
 
+type MaestroReplayBinding = Pick<
+  TypedMaestroReplayContext,
+  'device' | 'platform' | 'target' | 'runtimeHints'
+>;
+
 export async function runTypedMaestroReplayFile(
   params: TypedMaestroReplayParams,
 ): Promise<DaemonResponse> {
@@ -177,36 +182,89 @@ async function prepareTypedMaestroReplay(
   });
   const session = sessionStore.get(sessionName);
   if (session) assertSessionSelectorMatches(session, req.flags);
-  const device = session?.device ?? (await resolveTargetDevice(req.flags ?? {}));
+  const binding = await resolveMaestroReplayBinding({ req, sessionStore, sessionName, session });
+  return {
+    filePath,
+    program,
+    ...binding,
+    defaults: buildTypedMaestroDefaults({
+      req,
+      sessionName,
+      filePath,
+      platform: binding.platform,
+      target: binding.target,
+    }),
+    env: buildTypedMaestroEnv(req),
+    signal: getRequestSignal(req.meta?.requestId),
+    loadProgram: createMaestroProgramLoader(path.dirname(filePath)),
+  };
+}
+
+async function resolveMaestroReplayBinding(params: {
+  req: DaemonRequest;
+  sessionStore: SessionStore;
+  sessionName: string;
+  session: ReturnType<SessionStore['get']>;
+}): Promise<MaestroReplayBinding> {
+  const { req, sessionStore, sessionName, session } = params;
+  const requestedPlatform = req.flags?.platform;
+  const device =
+    session?.device ??
+    (requestedPlatform === 'android' || requestedPlatform === 'ios'
+      ? undefined
+      : await resolveTargetDevice(req.flags ?? {}));
   const platform = resolveMaestroPlatform(req, device);
-  const target = resolveMaestroTarget(req, device);
   const runtimeHints = resolveEffectiveOpenRuntimeHints({
     req,
     sessionStore,
     sessionName,
     device,
     platform,
   });
-  return {
-    filePath,
-    program,
+  return await completeMaestroRuntimeBinding({
+    req,
+    sessionStore,
+    sessionName,
     device,
     platform,
-    target,
+    target: resolveMaestroTarget(req, device),
     runtimeHints,
-    defaults: buildTypedMaestroDefaults({
-      req,
-      sessionName,
-      filePath,
-      platform,
-      target,
+  });
+}
+
+async function completeMaestroRuntimeBinding(
+  params: {
+    req: DaemonRequest;
+    sessionStore: SessionStore;
+    sessionName: string;
+  } & MaestroReplayBinding,
+): Promise<MaestroReplayBinding> {
+  if (params.device || !requiresDeviceRuntimeDefaults(params.runtimeHints)) return params;
+  const device = await resolveTargetDevice(params.req.flags ?? {});
+  return {
+    device,
+    platform: params.platform,
+    target: resolveMaestroTarget(params.req, device),
+    runtimeHints: resolveEffectiveOpenRuntimeHints({
+      req: params.req,
+      sessionStore: params.sessionStore,
+      sessionName: params.sessionName,
+      device,
+      platform: params.platform,
     }),
-    env: buildTypedMaestroEnv(req),
-    signal: getRequestSignal(req.meta?.requestId),
-    loadProgram: createMaestroProgramLoader(path.dirname(filePath)),
   };
 }
 
+function requiresDeviceRuntimeDefaults(
+  runtimeHints: ReturnType<typeof resolveEffectiveOpenRuntimeHints>,
+): boolean {
+  return (
+    runtimeHints?.metroPort !== undefined &&
+    runtimeHints.metroHost === undefined &&
+    runtimeHints.bundleUrl === undefined
+  );
+}
+
 function buildTypedMaestroDefaults(params: {
   req: DaemonRequest;
   sessionName: string;
@@ -239,7 +297,7 @@ function createMaestroReplayPort(params: {
   logPath: string;
   sessionName: string;
   sessionStore: SessionStore;
-  device: DeviceInfo;
+  device: DeviceInfo | undefined;
   platform: Extract<MaestroPlatform, 'android' | 'ios'>;
   runtimeHints: ReturnType<typeof resolveEffectiveOpenRuntimeHints>;
   sourcePath: string;
@@ -264,7 +322,7 @@ function createMaestroReplayPort(params: {
   } = req;
   const baseReq = {
     ...requestBase,
-    flags: maestroRuntimeDeviceFlags(device, platform),
+    flags: maestroRuntimeDeviceFlags(device, platform, req.flags),
     ...(runtimeHints === undefined ? {} : { runtime: runtimeHints }),
   };
   return createDaemonMaestroRuntimePort({
@@ -292,9 +350,11 @@ function createMaestroReplayPort(params: {
 }
 
 function maestroRuntimeDeviceFlags(
-  device: DeviceInfo,
+  device: DeviceInfo | undefined,
   platform: Extract<MaestroPlatform, 'android' | 'ios'>,
+  requestedFlags: CommandFlags | undefined,
 ): CommandFlags {
+  if (!device) return unresolvedMaestroRuntimeDeviceFlags(platform, requestedFlags);
   const flags: CommandFlags = {
     platform,
     target: device.target,
@@ -308,6 +368,43 @@ function maestroRuntimeDeviceFlags(
   };
 }
 
+function unresolvedMaestroRuntimeDeviceFlags(
+  platform: Extract<MaestroPlatform, 'android' | 'ios'>,
+  requestedFlags: CommandFlags | undefined,
+): CommandFlags {
+  const flags: CommandFlags = {
+    platform,
+    target: requestedFlags?.target ?? 'mobile',
+    noRecord: true,
+  };
+  if (requestedFlags?.device) flags.device = requestedFlags.device;
+  return platform === 'android'
+    ? unresolvedAndroidMaestroFlags(flags, requestedFlags)
+    : unresolvedIosMaestroFlags(flags, requestedFlags);
+}
+
+function unresolvedAndroidMaestroFlags(
+  flags: CommandFlags,
+  requestedFlags: CommandFlags | undefined,
+): CommandFlags {
+  if (requestedFlags?.serial) flags.serial = requestedFlags.serial;
+  if (requestedFlags?.androidDeviceAllowlist) {
+    flags.androidDeviceAllowlist = requestedFlags.androidDeviceAllowlist;
+  }
+  return flags;
+}
+
+function unresolvedIosMaestroFlags(
+  flags: CommandFlags,
+  requestedFlags: CommandFlags | undefined,
+): CommandFlags {
+  if (requestedFlags?.udid) flags.udid = requestedFlags.udid;
+  if (requestedFlags?.iosSimulatorDeviceSet) {
+    flags.iosSimulatorDeviceSet = requestedFlags.iosSimulatorDeviceSet;
+  }
+  return flags;
+}
+
 function createMaestroReplayObserver(params: {
   filePath: string;
   tracePath: string | undefined;

src/platforms/apple/interactions.ts

@@ -83,8 +83,9 @@ export function iosRunnerOverrides(
             selectorKey: selector.key,
             selectorValue: selector.value,
             allowNonHittableCoordinateFallback: selector.allowNonHittableCoordinateFallback,
-            x: selector.expectedPoint?.x,
-            y: selector.expectedPoint?.y,
+            ...(selector.expectedPoint
+              ? { x: selector.expectedPoint.x, y: selector.expectedPoint.y }
+              : {}),
             appBundleId: ctx.appBundleId,
           },
           runnerOpts,

test/integration/provider-scenarios/android-test-suite.test.ts

@@ -125,7 +125,8 @@ test('Provider-backed integration Android Maestro refreshes action geometry and
       assert.deepEqual(swipePlan.pointers[0]?.samples[0]?.point, { x: 351, y: 300 });
       assert.deepEqual(swipePlan.pointers[0]?.samples.at(-1)?.point, { x: 39, y: 300 });
       assert.equal(world.gestureViewportCalls, 1);
-      assert.equal(snapshots, 2);
+      // Assertion, fresh tap geometry, then the two-snapshot stability proof.
+      assert.equal(snapshots, 4);
     },
   );
 });