fix: distinguish Maestro direct selector dispatch

Author: thymikee

packages/contracts/src/interaction-guarantees.ts

@@ -80,6 +80,7 @@ export const INTERACTION_PATH_IDS = [
   'target-drag',
   'native-ref',
   'coordinate',
+  'maestro-direct-selector',
   'maestro-non-hittable-fallback',
 ] as const;
 
@@ -410,6 +411,63 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
       },
     },
   },
+  'maestro-direct-selector': {
+    description:
+      'An explicit Maestro-compatible simple-selector click completed as an XCTest element tap. This path is selected only when the runner was allowed to use the non-hittable coordinate fallback but reported that it did not use it.',
+    commands: ['click'],
+    guarantees: {
+      disambiguation: {
+        kind: 'waived',
+        reason:
+          'Intentional: Maestro replay uses its expected-point compatibility scan rather than runtime structural-equivalence-or-reject semantics.',
+      },
+      occlusion: {
+        kind: 'waived',
+        reason:
+          'Intentional: the direct element-tap outcome relies on XCTest hittability instead of the daemon snapshot occlusion classifier.',
+      },
+      parentOwnedTouchPoint: {
+        kind: 'waived',
+        reason:
+          'gap: the runner has the matched element but no daemon snapshot tree from which to exclude independently interactive descendants.',
+        trackingIssue: PARENT_OWNED_TOUCH_POINT_GAP_ISSUE,
+      },
+      offscreen: {
+        kind: 'waived',
+        reason:
+          'Intentional: successful direct element taps rely on XCTest hittability instead of the daemon viewport rule.',
+      },
+      nonHittable: {
+        kind: 'inapplicable',
+        reason:
+          'A non-hittable candidate that succeeds does so through the separate maestro-non-hittable-fallback path.',
+      },
+      responseConstruction: SHARED_RESPONSE_CONSTRUCTION,
+      responseIdentity: {
+        kind: 'waived',
+        reason:
+          'gap: the fused runner request does not return daemon refLabel or selectorChain fields.',
+        trackingIssue: GAPS_UMBRELLA_ISSUE,
+      },
+      verifyEvidence: {
+        kind: 'inapplicable',
+        reason: 'The eligibility gate excludes --verify from this replay-only route.',
+      },
+      settleObservation: {
+        kind: 'inapplicable',
+        reason: 'The eligibility gate excludes --settle from this replay-only route.',
+      },
+      errorTaxonomy: {
+        kind: 'waived',
+        reason: 'gap: Maestro preserves the runner-native direct-selector error shapes.',
+        trackingIssue: GAPS_UMBRELLA_ISSUE,
+      },
+      resolutionDisclosure: {
+        kind: 'runtime',
+        via: 'src/daemon/handlers/interaction-touch-response.ts#buildInteractionResponseData',
+      },
+    },
+  },
   'maestro-non-hittable-fallback': {
     description:
       'Replay-only coordinate fallback for non-hittable elements (allowNonHittableCoordinateFallback), matching Maestro semantics.',

src/__tests__/contracts/interaction-guarantees.test.ts

@@ -26,7 +26,8 @@ test('every dispatch path classifies every guarantee', () => {
   }
 });
 
-test('the Maestro non-hittable fallback classifies its reachable direct click command', () => {
+test('direct Maestro clicks and executed coordinate fallbacks are distinct narrow paths', () => {
+  assert.deepEqual(INTERACTION_DISPATCH_PATHS['maestro-direct-selector'].commands, ['click']);
   assert.ok(INTERACTION_DISPATCH_PATHS['maestro-non-hittable-fallback'].commands.includes('click'));
 });
 
@@ -162,6 +163,9 @@ test('acknowledged gaps are visible and bounded', () => {
   // updates it here with a linked issue. It is the diffable debt list
   // (umbrella: https://github.com/callstack/agent-device/issues/1081).
   assert.deepEqual(gaps.sort(), [
+    'maestro-direct-selector/errorTaxonomy',
+    'maestro-direct-selector/parentOwnedTouchPoint',
+    'maestro-direct-selector/responseIdentity',
     'maestro-non-hittable-fallback/errorTaxonomy',
     'maestro-non-hittable-fallback/parentOwnedTouchPoint',
   ]);

src/__tests__/eager-closure-budgets.ts

@@ -144,7 +144,7 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'packages/contracts/src/facades/divergence.ts': 3,
   'packages/contracts/src/facades/interaction.ts': 25,
   'packages/contracts/src/facades/observability.ts': 7,
-  'packages/contracts/src/facades/platform.ts': 47,
+  'packages/contracts/src/facades/platform.ts': 48,
   'packages/contracts/src/facades/progress.ts': 1,
   'packages/contracts/src/facades/recording.ts': 3,
   'packages/contracts/src/facades/remote.ts': 2,
@@ -166,7 +166,7 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'packages/contracts/src/platform-module.ts': 5,
   'packages/contracts/src/platform-runtime-host.ts': 1,
   'packages/contracts/src/platform-runtime-operations.ts': 2,
-  'packages/contracts/src/platform-runtime-unavailable.ts': 20,
+  'packages/contracts/src/platform-runtime-unavailable.ts': 21,
   'packages/contracts/src/platform-runtime.ts': 6,
   'packages/contracts/src/record-runtime-cutover.ts': 7,
   'packages/contracts/src/screen-recording-runtime-plan.ts': 5,
@@ -180,6 +180,7 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'packages/contracts/src/startup-recovery-fence.ts': 1,
   'packages/contracts/src/tv-remote.ts': 3,
   'packages/contracts/src/type-text-runtime.ts': 4,
+  'packages/contracts/src/touch-runtime.ts': 4,
   'packages/contracts/src/viewport-runtime.ts': 1,
   'packages/contracts/src/wait-runtime-plan.ts': 1,
   'packages/contracts/src/wait.ts': 1,
@@ -260,8 +261,8 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
  */
 export const HUB_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'src/cli.ts': 362,
-  'src/platform-runtime.ts': 36,
-  'src/core/dispatch.ts': 94,
+  'src/platform-runtime.ts': 37,
+  'src/core/dispatch.ts': 88,
   'src/core/capabilities.ts': 76,
   'src/core/command-descriptor/registry.ts': 66,
   'src/core/command-descriptor/platform-execution-entry.ts': 3,

src/daemon/handlers/interaction-touch-direct-ios.ts

@@ -62,7 +62,9 @@ export async function dispatchDirectIosSelectorTap(
         data,
         publicData,
         point,
-        maestroCoordinateFallbackDispatched: maestroFallback.used,
+        dispatchPath: maestroFallback.used
+          ? 'maestro-non-hittable-fallback'
+          : 'maestro-direct-selector',
       },
       referenceFrame: readReferenceFrameFromDirectSelectorTapResult(data),
       extra: {

src/daemon/handlers/interaction-touch-fill.ts

@@ -169,7 +169,7 @@ function buildFillResponsePayloads(params: {
         flags: params.flags,
         data: result.backendResult,
       }),
-      maestroCoordinateFallbackDispatched: maestroFallback.used,
+      ...(maestroFallback.used ? { dispatchPath: 'maestro-non-hittable-fallback' as const } : {}),
     },
     referenceFrame,
     extra: { text: params.text, ...maestroFallback.extra },

src/daemon/handlers/interaction-touch-response.ts

@@ -8,6 +8,7 @@ import type {
   RecordingTargetOverride,
   ResolutionDisclosure,
   SettleObservation,
+  InteractionPathId,
 } from '@agent-device/contracts/interaction';
 import { isApplePlatform } from '@agent-device/kernel/device';
 import {
@@ -45,20 +46,19 @@ type InteractionRuntimeResult =
   | LongPressCommandResult
   | HoverCommandResult;
 
+const MAESTRO_DIRECT_SELECTOR_PATH = 'maestro-direct-selector' satisfies InteractionPathId;
+const MAESTRO_COORDINATE_FALLBACK_PATH =
+  'maestro-non-hittable-fallback' satisfies InteractionPathId;
+
 type InteractionResponseSourceBase = {
   publicData?: Record<string, unknown>;
-  /**
-   * The runner EXECUTED its Maestro non-hittable coordinate fallback, never the
-   * mere permission to. Names the dispatch path that ran, not a request flag —
-   * see {@link suppressesResolutionDisclosure}.
-   */
-  maestroCoordinateFallbackDispatched?: boolean;
 };
 
 export type InteractionResponseSource =
   | (InteractionResponseSourceBase & {
       kind: 'runtime';
       result: InteractionRuntimeResult;
+      dispatchPath?: typeof MAESTRO_COORDINATE_FALLBACK_PATH;
     })
   | (InteractionResponseSourceBase & {
       // Direct iOS selector dispatch: no runtime result exists, only the raw
@@ -67,6 +67,8 @@ export type InteractionResponseSource =
       targetKind: InteractionRuntimeResult['kind'];
       data: Record<string, unknown>;
       point: { x: number; y: number };
+      /** The runner outcome, not the request's fallback permission. */
+      dispatchPath: typeof MAESTRO_DIRECT_SELECTOR_PATH | typeof MAESTRO_COORDINATE_FALLBACK_PATH;
     })
   | (InteractionResponseSourceBase & {
       // An XCTest mutation failure was corroborated by a changed same-scope
@@ -111,7 +113,7 @@ function applyResolutionDisclosurePolicy<TExtra extends { resolution?: unknown }
 }
 
 function suppressesResolutionDisclosure(source: InteractionResponseSource): boolean {
-  return source.maestroCoordinateFallbackDispatched === true;
+  return 'dispatchPath' in source && source.dispatchPath === MAESTRO_COORDINATE_FALLBACK_PATH;
 }
 
 export type InteractionResponsePayloads = {

test/integration/interaction-contract/index.ts

@@ -1,5 +1,6 @@
 import type { ContractCoverageEntry } from './coverage-manifest.ts';
 import { COORDINATE_COVERAGE } from './coordinate.coverage.ts';
+import { MAESTRO_DIRECT_SELECTOR_COVERAGE } from './maestro-direct-selector.coverage.ts';
 import { MAESTRO_FALLBACK_COVERAGE } from './maestro-fallback.coverage.ts';
 import { NATIVE_REF_COVERAGE } from './native-ref.coverage.ts';
 import { RUNTIME_REF_COVERAGE } from './runtime-ref.coverage.ts';
@@ -18,6 +19,7 @@ export const CONTRACT_COVERAGE: readonly ContractCoverageEntry[] = [
   ...TARGET_DRAG_COVERAGE,
   ...NATIVE_REF_COVERAGE,
   ...COORDINATE_COVERAGE,
+  ...MAESTRO_DIRECT_SELECTOR_COVERAGE,
   ...MAESTRO_FALLBACK_COVERAGE,
 ];
 

test/integration/interaction-contract/maestro-direct-selector.contract.test.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { assertRpcOk } from '../provider-scenarios/assertions.ts';
+import { runnerTapEntry, withIosContractDaemon } from './daemon-harness.ts';
+
+const MAESTRO_FLAGS = { maestro: { allowNonHittableCoordinateFallback: true } };
+
+// Permission is not usage: when the runner hits the element normally, the
+// completed dispatch is the direct-selector path, not the coordinate fallback.
+test('maestro-direct-selector responseConstruction and resolutionDisclosure: allowed fallback not taken keeps direct-iOS resolution', async () => {
+  await withIosContractDaemon(
+    [runnerTapEntry({ x: 50, y: 60, message: 'tapped' })],
+    async (daemon, transcript) => {
+      const data = assertRpcOk(await daemon.callCommand('click', ['label=Pin'], MAESTRO_FLAGS));
+
+      const tapRequest = transcript.calls[0]?.request as Record<string, unknown> | undefined;
+      assert.equal(tapRequest?.allowNonHittableCoordinateFallback, true);
+      assert.equal(data.maestroNonHittableCoordinateFallbackAllowed, true);
+      assert.equal(data.maestroNonHittableCoordinateFallbackUsed, false);
+      assert.deepEqual(data.resolution, { source: 'direct-ios', kind: 'not-observed' });
+    },
+  );
+});

test/integration/interaction-contract/maestro-direct-selector.coverage.ts

@@ -0,0 +1,9 @@
+import { definePathCoverage } from './coverage-manifest.ts';
+
+const DIRECT_MAESTRO_CLICK_SCENARIO =
+  'maestro-direct-selector responseConstruction and resolutionDisclosure: allowed fallback not taken keeps direct-iOS resolution';
+
+export const MAESTRO_DIRECT_SELECTOR_COVERAGE = definePathCoverage('maestro-direct-selector', {
+  responseConstruction: DIRECT_MAESTRO_CLICK_SCENARIO,
+  resolutionDisclosure: DIRECT_MAESTRO_CLICK_SCENARIO,
+});

test/integration/interaction-contract/maestro-fallback.contract.test.ts

@@ -63,32 +63,12 @@ test(
   PARALLEL_PROVIDER_SCENARIO_TIMEOUT_MS,
 );
 
-// Permission is not usage: with the fallback allowed but the runner hitting
-// the element normally ("tapped"), the dispatch is the direct-ios path and
-// must disclose not-observed, not classify as the maestro-fallback cell.
-test('maestro-non-hittable-fallback resolutionDisclosure: allowed-but-not-taken discloses direct-ios not-observed', async () => {
-  await withIosContractDaemon(
-    [runnerTapEntry({ x: 50, y: 60, message: 'tapped' })],
-    async (daemon, transcript) => {
-      const click = await daemon.callCommand('click', ['label=Pin'], MAESTRO_FLAGS);
-      const data = assertRpcOk(click);
-
-      const tapRequest = transcript.calls[0]?.request as Record<string, unknown> | undefined;
-      assert.equal(tapRequest?.allowNonHittableCoordinateFallback, true);
-
-      assert.equal(data.maestroNonHittableCoordinateFallbackAllowed, true);
-      assert.equal(data.maestroNonHittableCoordinateFallbackUsed, false);
-      assert.deepEqual(data.resolution, { source: 'direct-ios', kind: 'not-observed' });
-    },
-  );
-});
-
-// The fourth cell of the resolution-suppression matrix. The other three are
-// above: runner-payload/taken (no resolution), runner-payload/not-taken
-// (direct-ios not-observed), runtime/taken (no resolution). Suppression is
-// keyed on the dispatch that RAN — a runtime fill the fallback never touched
-// still discloses how the daemon resolved it, whether or not the request
-// carried the Maestro permission.
+// The fourth cell of the resolution-suppression matrix. Runner-payload/taken
+// and runtime/taken are covered here; runner-payload/not-taken belongs to the
+// sibling maestro-direct-selector contract. Suppression is keyed on the
+// dispatch that RAN — a runtime fill the fallback never touched still
+// discloses how the daemon resolved it, whether or not the request carried the
+// Maestro permission.
 test('runtime fill the coordinate fallback did not execute keeps its resolution disclosure', async () => {
   await withIosContractDaemon(
     [runnerSnapshotEntry(RUNNER_CONTINUE_NODES), runnerTypeEntry({ x: 200, y: 322 })],