refactor: replace Maestro compat with typed direct engine

.github/workflows/ios.yml

@@ -71,7 +71,8 @@ jobs:
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSystemModalProbeSliceSharesAndClampsToPlanDeadline \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testDispatchRecoverySkipsBookkeepingWhileXCTestChannelOccupied \
             -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrain \
-            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testBoundedSystemModalProbeTimeoutRecoversThenReleasesOnDrainForSnapshotRaw \
+            -only-testing:AgentDeviceRunnerUITests/RunnerTests/testSnapshotTraversalIdentityPreservesSameOriginNodesWithDifferentBounds
 
       - name: Prepare iOS runner
         run: |

CONTEXT.md

@@ -55,6 +55,8 @@
   seam. Helper long-press executes its absolute stationary path without a viewport probe; provider
   long-press receives its paired provider-owned viewport. See ADR 0013.
 - Multi-touch geometry: the internal initial span and angle plus centroid translation, scale, and rotation used to build both contact trajectories. Geometry is viewport-aware and fails early when the requested motion cannot fit; it is not a public tuning surface.
+- Maestro program: source-preserving typed representation of supported Maestro YAML. It is interpreted directly through the compatibility runtime port and never lowered through generic replay action strings. See ADR 0015.
+- Maestro observation generation: explicit compatibility-engine state identifying evidence captured since the most recent mutation. Queries may share semantic evidence within one generation; every mutation attempt invalidates it before dispatch. Interaction geometry is action-local: unique exact iOS selectors resolve and tap atomically in XCTest, while coordinate dispatch uses a fresh target snapshot. Rectangles are never shared across command boundaries.
 - Guarantee cell: one (dispatch path, guarantee) entry in `src/contracts/interaction-guarantees.ts`, classified as runtime/runner/delegated/inapplicable/waived. Completeness is a compile error; honesty is gate-tested.
 - Owned waiver: a `gap:`-prefixed waived cell carrying a `trackingIssue` URL. Waivers are diffable debt with an owner, never folklore.
 - Parity table: golden JSON fixture under `contracts/fixtures/` consumed by both vitest and the runner's gated Swift tests, so a cross-language rule (e.g. tap-point policy) cannot drift silently. Change the rule only via the table.
@@ -158,10 +160,14 @@ the observable freshness and failure semantics below before any runtime refactor
   disables direct iOS selector shortcuts while pending.
 - `setSessionSnapshot` is the centralized session snapshot mutation path. Sparse captures do not
   write back, and empty `@ref`-scoped snapshot output must not replace the stored session snapshot.
-- Maestro target matching remains snapshot-based, fresh, and policy-rich. Native selector
-  simplification must not erase Maestro regex/string selector behavior, visibility filtering,
-  ranking, fuzzy fallback, visible-context preference, Android duplicate handling, tab-strip
-  inference, or assertion/wait semantics.
+- Maestro target matching remains snapshot-based and policy-owned. Coordinate dispatch always uses a
+  fresh target snapshot. A unique exact iOS match may instead reuse bound same-generation semantic
+  evidence and dispatch through XCTest's atomic selector tap; structured live-selector failures return
+  to fresh Maestro resolution. This optimization must not erase Maestro regex/string selector behavior,
+  visibility filtering, provider-order first-match selection, explicit index selection, or
+  assertion/wait semantics. Provider normalization belongs below the compatibility layer. Plain text is
+  exact and regex-aware; do not add substring/fuzzy recovery, synthetic geometry, or hierarchy-shape
+  heuristics that change authored selector meaning.
 
 Evidence: [ADR 0002](docs/adr/0002-persistent-platform-helper-sessions.md),
 [ADR 0004](docs/adr/0004-ios-snapshot-backend-strategy.md),
@@ -170,7 +176,7 @@ Evidence: [ADR 0002](docs/adr/0002-persistent-platform-helper-sessions.md),
 [`find.test.ts`](src/daemon/handlers/__tests__/find.test.ts),
 [`snapshot-handler.test.ts`](src/daemon/handlers/__tests__/snapshot-handler.test.ts),
 [`snapshot-scoped-refs.test.ts`](src/daemon/handlers/__tests__/snapshot-scoped-refs.test.ts),
-[`runtime-targets.test.ts`](src/compat/maestro/__tests__/runtime-targets.test.ts), and
+[`runtime-targets-typed.test.ts`](src/compat/maestro/__tests__/runtime-targets-typed.test.ts), and
 [`android-test-suite.test.ts`](test/integration/provider-scenarios/android-test-suite.test.ts).
 
 ## Testing Principles

android-multitouch-helper/src/main/java/com/callstack/agentdevice/multitouchhelper/MultiTouchInstrumentation.java

@@ -137,12 +137,12 @@ private int injectPlan(GesturePlan plan) {
         inject(
             automation,
             motionEvent(downTime, eventTime, motionEventAction(step.action), active),
-            step.action != PointerEventSchedule.Action.MOVE);
+            step.waitForDispatch);
         count += 1;
       }
       return count;
     } catch (RuntimeException error) {
-      if (count > 0) injectCancel(automation, downTime, eventTime + 16, active);
+      if (count > 0) injectCancel(automation, downTime, SystemClock.uptimeMillis(), active);
       throw error;
     }
   }

android-multitouch-helper/src/main/java/com/callstack/agentdevice/multitouchhelper/PointerEventSchedule.java

@@ -5,7 +5,7 @@
 
 /** Defines the platform-independent event order consumed by Android touch injection. */
 final class PointerEventSchedule {
-  private static final long POINTER_LIFT_DELAY_MS = 8;
+  private static final long POINTER_TRANSITION_DELAY_MS = 8;
 
   enum Action {
     DOWN,
@@ -20,12 +20,19 @@ static final class Step {
     final int sampleIndex;
     final int pointerCount;
     final long offsetMs;
+    final boolean waitForDispatch;
 
-    Step(Action action, int sampleIndex, int pointerCount, long offsetMs) {
+    Step(
+        Action action,
+        int sampleIndex,
+        int pointerCount,
+        long offsetMs,
+        boolean waitForDispatch) {
       this.action = action;
       this.sampleIndex = sampleIndex;
       this.pointerCount = pointerCount;
       this.offsetMs = offsetMs;
+      this.waitForDispatch = waitForDispatch;
     }
   }
 
@@ -41,22 +48,28 @@ static List<Step> create(int pointerCount, long[] sampleOffsetsMs) {
 
     int lastIndex = sampleOffsetsMs.length - 1;
     List<Step> steps = new ArrayList<>(sampleOffsetsMs.length + (pointerCount == 1 ? 1 : 3));
-    steps.add(new Step(Action.DOWN, 0, 1, 0));
+    steps.add(new Step(Action.DOWN, 0, 1, 0, true));
     if (pointerCount == 2) {
-      long pointerDownOffset = Math.max(1, Math.min(8, sampleOffsetsMs[1] - 1));
-      steps.add(new Step(Action.POINTER_DOWN, 0, 2, pointerDownOffset));
+      long pointerDownOffset =
+          Math.max(1, Math.min(POINTER_TRANSITION_DELAY_MS, sampleOffsetsMs[1] - 1));
+      steps.add(new Step(Action.POINTER_DOWN, 0, 2, pointerDownOffset, true));
     }
     for (int sampleIndex = 1; sampleIndex <= lastIndex; sampleIndex += 1) {
       steps.add(
-          new Step(Action.MOVE, sampleIndex, pointerCount, sampleOffsetsMs[sampleIndex]));
+          new Step(
+              Action.MOVE,
+              sampleIndex,
+              pointerCount,
+              sampleOffsetsMs[sampleIndex],
+              pointerCount == 1 || sampleIndex == lastIndex));
     }
     if (pointerCount == 2) {
       steps.add(
-          new Step(Action.POINTER_UP, lastIndex, 2, sampleOffsetsMs[lastIndex]));
+          new Step(Action.POINTER_UP, lastIndex, 2, sampleOffsetsMs[lastIndex], true));
     }
     long finalUpOffset =
-        sampleOffsetsMs[lastIndex] + (pointerCount == 2 ? POINTER_LIFT_DELAY_MS : 0);
-    steps.add(new Step(Action.UP, lastIndex, 1, finalUpOffset));
+        sampleOffsetsMs[lastIndex] + (pointerCount == 2 ? POINTER_TRANSITION_DELAY_MS : 0);
+    steps.add(new Step(Action.UP, lastIndex, 1, finalUpOffset, true));
     return steps;
   }
 }

android-multitouch-helper/src/test/java/com/callstack/agentdevice/multitouchhelper/PointerEventScheduleTest.java

@@ -8,18 +8,18 @@ private PointerEventScheduleTest() {}
   public static void main(String[] args) {
     assertSteps(
         PointerEventSchedule.create(1, new long[] {0, 16, 32}),
-        "DOWN:0:1:0",
-        "MOVE:1:1:16",
-        "MOVE:2:1:32",
-        "UP:2:1:32");
+        "DOWN:0:1:0:true",
+        "MOVE:1:1:16:true",
+        "MOVE:2:1:32:true",
+        "UP:2:1:32:true");
     assertSteps(
         PointerEventSchedule.create(2, new long[] {0, 16, 32}),
-        "DOWN:0:1:0",
-        "POINTER_DOWN:0:2:8",
-        "MOVE:1:2:16",
-        "MOVE:2:2:32",
-        "POINTER_UP:2:2:32",
-        "UP:2:1:40");
+        "DOWN:0:1:0:true",
+        "POINTER_DOWN:0:2:8:true",
+        "MOVE:1:2:16:false",
+        "MOVE:2:2:32:true",
+        "POINTER_UP:2:2:32:true",
+        "UP:2:1:40:true");
   }
 
   private static void assertSteps(List<PointerEventSchedule.Step> actual, String... expected) {
@@ -35,7 +35,9 @@ private static void assertSteps(List<PointerEventSchedule.Step> actual, String..
               + ":"
               + step.pointerCount
               + ":"
-              + step.offsetMs;
+              + step.offsetMs
+              + ":"
+              + step.waitForDispatch;
       if (!expected[index].equals(description)) {
         throw new AssertionError(
             "Step " + index + ": expected " + expected[index] + ", got " + description);

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -263,7 +263,7 @@ extension RunnerTests {
     }
     let command = try runnerCommandFixture(
       """
-      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
+      {"command":"gesture","commandId":"gesture-fling-fallback","gesturePlan":{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}}
       """
     )
 
@@ -1293,6 +1293,8 @@ extension RunnerTests {
     switch command.command {
     case .status:
       return executeStatus(command: command)
+    case .targetReset:
+      return resetTargetAfterExternalRelaunch()
     case .shutdown:
       stopRecordingIfNeeded()
       return Response(ok: true, data: DataPayload(message: "shutdown"))
@@ -1446,7 +1448,7 @@ extension RunnerTests {
   ) throws -> Response {
     var activeApp = activeApp
     switch command.command {
-    case .status, .shutdown, .recordStart, .recordStop, .uptime:
+    case .status, .targetReset, .shutdown, .recordStart, .recordStop, .uptime:
       return Response(
         ok: false,
         error: ErrorPayload(
@@ -1456,11 +1458,21 @@ extension RunnerTests {
       )
     case .tap:
       if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
+        let expectedPoint: CGPoint?
+        if command.allowNonHittableCoordinateFallback == true,
+          let x = command.x,
+          let y = command.y
+        {
+          expectedPoint = CGPoint(x: x, y: y)
+        } else {
+          expectedPoint = nil
+        }
         let match = findElement(
           app: activeApp,
           selectorKey: selectorKey,
           selectorValue: selectorValue,
-          allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true
+          allowNonHittableFallback: command.allowNonHittableCoordinateFallback == true,
+          expectedPoint: expectedPoint
         )
         if match.isAmbiguous {
           return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
@@ -1486,15 +1498,19 @@ extension RunnerTests {
               message: "element resolved off-screen at (\(Int(frame.midX)), \(Int(frame.midY)))"))
           }
           let isTextEntry = isTextEntryElement(element)
-          let touchFrame = frame.isEmpty
-            ? nil
-            : resolvedTouchVisualizationFrame(app: activeApp, x: frame.midX, y: frame.midY)
+          let touchPoint = expectedPoint ?? CGPoint(x: frame.midX, y: frame.midY)
+          let touchFrame = resolvedTouchVisualizationFrame(
+            app: activeApp,
+            x: touchPoint.x,
+            y: touchPoint.y
+          )
           let (timing, outcome) = performGesture(activeApp) {
-            if match.usedNonHittableFallback {
+            if expectedPoint != nil || match.usedNonHittableFallback {
               // Maestro compatibility: RN E2E backdoor controls can be 1x1 and
-              // reported non-hittable by XCTest, while Maestro still taps their
-              // resolved bounds. Keep this behind the explicit replay-only flag.
-              return tapAt(app: activeApp, x: frame.midX, y: frame.midY)
+              // reported non-hittable by XCTest. Snapshot-resolved targets also
+              // need coordinate delivery because XCUIElement.activate() does not
+              // invoke every React Native accessibility wrapper.
+              return tapAt(app: activeApp, x: touchPoint.x, y: touchPoint.y)
             }
             return activateElement(app: activeApp, element: element, action: "tap by selector")
           }

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift

@@ -147,7 +147,7 @@ final class RunnerCommandJournal {
          .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText, .back,
          .backInApp, .backSystem, .home, .rotate, .appSwitcher, .keyboardDismiss, .keyboardReturn,
          .alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
-         .status, .uptime, .shutdown:
+         .status, .uptime, .targetReset, .shutdown:
       return true
     }
   }

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -149,7 +149,8 @@ extension RunnerTests {
     app: XCUIApplication,
     selectorKey: String,
     selectorValue: String,
-    allowNonHittableFallback: Bool = false
+    allowNonHittableFallback: Bool = false,
+    expectedPoint: CGPoint? = nil
   ) -> SelectorElementMatch {
     let value = selectorValue.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !value.isEmpty else {
@@ -173,6 +174,9 @@ extension RunnerTests {
     var nonHittableElement: XCUIElement?
     let matches = app.descendants(matching: .any).matching(predicate).allElementsBoundByIndex
     for element in matches where element.exists {
+      if let expectedPoint, !element.frame.contains(expectedPoint) {
+        continue
+      }
       if !element.isHittable {
         if allowNonHittableFallback && hasTappableFrame(app: app, element: element) {
           guard nonHittableElement == nil else {
@@ -1186,6 +1190,13 @@ extension RunnerTests {
       : plan.intent == "pan" || plan.intent == "pinch" || plan.intent == "rotate"
         || plan.intent == "transform"
     guard supportedIntent else { return "planned gesture has unsupported intent for its topology" }
+    if plan.topology == "single" {
+      guard plan.executionProfile == "endpoint-hold" || plan.executionProfile == "timed-pan" else {
+        return "single-pointer gesture requires a supported execution profile"
+      }
+    } else if plan.executionProfile != nil {
+      return "multi-touch gesture cannot define a single-pointer execution profile"
+    }
     guard plan.durationMs.isFinite, plan.durationMs >= 16, plan.durationMs <= 10_000 else {
       return "planned gesture durationMs must be between 16 and 10000"
     }
@@ -1245,7 +1256,9 @@ extension RunnerTests {
   }
 
   func plannedGestureExecution(for plan: RunnerGesturePlan) -> PlannedGestureExecution {
-    plan.topology == "single" && plan.intent == "fling" ? .fastSwipe : .sampled
+    plan.topology == "single" && plan.executionProfile == "endpoint-hold"
+      ? .fastSwipe
+      : .sampled
   }
 
   func sampledPlannedGesture(
@@ -1459,6 +1472,7 @@ extension RunnerTests {
     )
 
     XCTAssertNil(plannedGestureValidationError(plan))
+    XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
   }
 
   func testPlannedMultiTouchGestureRejectsMismatchedOffsets() throws {
@@ -1479,7 +1493,7 @@ extension RunnerTests {
     let plan = try JSONDecoder().decode(
       RunnerGesturePlan.self,
       from: Data(
-        #"{"topology":"single","intent":"fling","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}"#.utf8
+        #"{"topology":"single","intent":"fling","executionProfile":"endpoint-hold","durationMs":100,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":100,"point":{"x":40,"y":150}}]}]}"#.utf8
       )
     )
 
@@ -1490,13 +1504,39 @@ extension RunnerTests {
     let plan = try JSONDecoder().decode(
       RunnerGesturePlan.self,
       from: Data(
-        #"{"topology":"single","intent":"pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":250,"point":{"x":100,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+        #"{"topology":"single","intent":"pan","executionProfile":"timed-pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":250,"point":{"x":100,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
       )
     )
 
     XCTAssertEqual(plannedGestureExecution(for: plan), .sampled)
   }
 
+  func testSinglePointerEndpointHoldUsesFastSwipeExecution() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"pan","executionProfile":"endpoint-hold","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertNil(plannedGestureValidationError(plan))
+    XCTAssertEqual(plannedGestureExecution(for: plan), .fastSwipe)
+  }
+
+  func testSinglePointerGestureRejectsMissingExecutionProfile() throws {
+    let plan = try JSONDecoder().decode(
+      RunnerGesturePlan.self,
+      from: Data(
+        #"{"topology":"single","intent":"pan","durationMs":500,"viewport":{"x":0,"y":0,"width":200,"height":300},"pointers":[{"pointerId":0,"samples":[{"offsetMs":0,"point":{"x":160,"y":150}},{"offsetMs":500,"point":{"x":40,"y":150}}]}]}"#.utf8
+      )
+    )
+
+    XCTAssertEqual(
+      plannedGestureValidationError(plan),
+      "single-pointer gesture requires a supported execution profile"
+    )
+  }
+
   func testDesktopScrollWheelDeltasMapDirections() throws {
     XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "up", pixels: 120)).vertical, 120)
     XCTAssertEqual(try XCTUnwrap(desktopScrollWheelDeltas(direction: "down", pixels: 120)).vertical, -120)

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift

@@ -99,6 +99,12 @@ extension RunnerTests {
     snapshotXCTestPenaltyWarmupExemptionPending = false
   }
 
+  func resetTargetAfterExternalRelaunch() -> Response {
+    invalidateCachedTarget(reason: "external_app_relaunch")
+    needsFirstInteractionDelay = true
+    return Response(ok: true, data: DataPayload(message: "target reset"))
+  }
+
   func refreshCachedTargetIfProcessChanged(bundleId: String) {
     guard currentBundleId == bundleId, currentApp != nil else { return }
     let candidate = XCUIApplication(bundleIdentifier: bundleId)