refactor: make resolution-disclosure choices self-evident

Replace the direct-iOS/maestro message-sniffing (and its justification
paragraph) with an explicit maestroFallback flag passed from the dispatch
site that already owns the path decision, and shrink every why-this-is-OK
paragraph to one-line constraint statements per the maintainer directive.

Author: thymikee

src/commands/interaction/runtime/resolution.ts

@@ -242,19 +242,11 @@ async function resolveSelectorInteractionTarget(
   };
 }
 
-/**
- * ADR 0012 decision 2: every optional string on a pre-action diagnostic entry
- * is UTF-8 truncated to this bound; `alternatives` is capped to this many
- * losing candidates (the winner is never included).
- */
+// ADR 0012 decision 2 bounds: diagnostic strings and losing alternatives.
 const RESOLUTION_DIAGNOSTIC_STRING_BYTE_CAP = 256;
 const MAX_RESOLUTION_ALTERNATIVES = 5;
 
-/**
- * ADR 0012 decision 2: an `@ref` names exactly one node by construction when
- * the ref lookup succeeds. The native-ref fast path (`interactions.ts`) always
- * attaches this constant; runtime-ref can instead disclose label fallback.
- */
+/** A successful `@ref` lookup names exactly one node; label recovery discloses label-fallback instead. */
 export const EXACT_REF_RESOLUTION: ResolutionDisclosure = {
   source: 'ref',
   phase: 'pre-action',
@@ -273,10 +265,7 @@ const UNIQUE_RUNTIME_RESOLUTION: ResolutionDisclosure = {
   kind: 'unique',
 };
 
-// The disambiguation winner IS `resolved.node` (resolveSelectorChain's own
-// pick, never re-derived here) — only diagnostic disclosure is added, per ADR
-// 0012 decision 2: "discloses the existing heuristic without changing
-// resolveSelectorChain or its winner."
+// Disclosure only: the winner stays resolveSelectorChain's pick (ADR 0012).
 function buildSelectorResolutionDisclosure(
   resolved: SelectorResolution,
   nodes: SnapshotState['nodes'],

src/contracts/interaction-guarantees.ts

@@ -61,12 +61,9 @@ export const INTERACTION_GUARANTEES = [
   // (rich selector diagnostics and hints) once direct runner paths close
   // codes earlier than full diagnostics.
   'errorTaxonomy',
-  // ADR 0012 decision 2: an additive `resolution` response field discloses how
-  // the acting path resolved its target — unique vs heuristically
-  // disambiguated (with match count/tiebreak/bounded alternatives) on the
-  // daemon tree, exact by construction on a ref, or explicitly not observed on
-  // the direct iOS fast path. Pre-action diagnostics only; never ref-issued or
-  // MCP-pinned (see src/contracts/interaction.ts#ResolutionDisclosure).
+  // The additive `resolution` response field (ADR 0012 decision 2):
+  // unique/disambiguated/exact/label-fallback/not-observed provenance,
+  // pre-action diagnostics only — never ref-issued or MCP-pinned.
   'resolutionDisclosure',
 ] as const;
 
@@ -188,10 +185,8 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
         kind: 'runtime',
         via: 'src/daemon/selectors-resolve.ts#formatSelectorFailure',
       },
-      // ADR 0012 decision 2: the full pre-action diagnostic shape — unique or
-      // disambiguated (matchCount/winnerDiagnostic/tiebreak/bounded
-      // alternatives) — discloses resolveSelectorChain's existing heuristic
-      // (same via as `disambiguation`) without changing it.
+      // Full pre-action diagnostic shape; same via as `disambiguation` — the
+      // disclosure reports what the heuristic did, never changes it.
       resolutionDisclosure: {
         kind: 'runtime',
         via: 'src/daemon/selectors-resolve.ts#resolveSelectorChain',
@@ -270,13 +265,8 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
         to: 'runtime-selector',
         via: 'runner ELEMENT_NOT_FOUND/AMBIGUOUS_MATCH fall back to tree-based resolution (isDirectIosSelectorFallbackError delegateSemanticFailures; non-maestro dispatches only), which attaches the shared no-match diagnostics, ambiguous shape, and hints',
       },
-      // ADR 0012 decision 2: the XCTest fast path has no daemon tree and
-      // cannot truthfully report a match count or candidates, so it discloses
-      // only the explicit not-observed provenance marker — never a fabricated
-      // unique-match or identity claim. No selection-parity table is claimed:
-      // that would falsely imply XCTest selection has runtime parity. Via the
-      // shared response builder (same symbol as `responseConstruction`),
-      // where the marker is attached for the runner-payload source.
+      // No daemon tree, so only the not-observed marker — no counts or
+      // candidates, and no parity table (that would imply runtime parity).
       resolutionDisclosure: {
         kind: 'runtime',
         via: 'src/daemon/handlers/interaction-touch-response.ts#buildInteractionResponseData',
@@ -331,9 +321,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
         kind: 'runtime',
         via: 'src/daemon/selectors-resolve.ts#STALE_REF_HINT',
       },
-      // ADR 0012 decision 2: an @ref names exactly one node by construction,
-      // same as runtime-ref — the native fast path attaches the identical
-      // constant directly (src/commands/interaction/runtime/interactions.ts).
+      // An @ref names exactly one node by construction (same cell as runtime-ref).
       resolutionDisclosure: {
         kind: 'runtime',
         via: 'src/commands/interaction/runtime/resolution.ts#EXACT_REF_RESOLUTION',
@@ -378,9 +366,6 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
         kind: 'runtime',
         via: 'src/kernel/errors.ts#normalizeError',
       },
-      // ADR 0012 decision 2: no element was resolved, so there is nothing to
-      // disclose. Distinct from the direct-iOS not-observed marker: coordinate
-      // dispatch never even attempts resolution.
       resolutionDisclosure: {
         kind: 'inapplicable',
         reason: 'Coordinates name a point; no element was resolved to disclose.',
@@ -431,9 +416,6 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
         reason: 'gap: shares the direct path error shapes, including their missing hints.',
         trackingIssue: GAPS_UMBRELLA_ISSUE,
       },
-      // ADR 0012 decision 2: Maestro owns matching on this path, and the
-      // fallback is coordinate execution — resolution semantics do not apply
-      // regardless of whether the runner actually used the coordinate tap.
       resolutionDisclosure: {
         kind: 'inapplicable',
         reason: 'Maestro owns matching; the fallback is coordinate execution.',

src/contracts/interaction.ts

@@ -31,21 +31,14 @@ export type ResolvedTarget =
       ref: string;
     };
 
-/**
- * ADR 0012 decision 2: which comparison actually decided a resolveSelectorChain
- * ambiguity — visible-first, then deepest, then smallest-area. Recorded by the
- * comparator itself (src/daemon/selectors-resolve.ts) rather than re-derived
- * after the fact.
- */
+/** The comparison that decided a resolveSelectorChain ambiguity, recorded by the comparator itself (ADR 0012). */
 export type DisambiguationTiebreak = 'visible' | 'deepest' | 'smallest-area';
 
 /**
- * A single pre-action diagnostic entry (a disambiguation winner or a losing
- * alternative). `diagnosticRef` is an opaque, non-`@` token: it is NEVER a
- * snapshot ref, is never issued via `refsGeneration`, and cannot be pinned or
- * reused as an `@ref` target (attempting `@<diagnosticRef>` fails ref
- * resolution like any other unknown ref). `role`/`label` are best-effort and
- * UTF-8 truncated to 256 bytes.
+ * A disambiguation winner or losing alternative. `diagnosticRef` is an opaque,
+ * non-`@` token — never a snapshot ref, never issued via `refsGeneration`,
+ * never pinnable or usable as an `@ref` target. Strings are UTF-8 truncated
+ * to 256 bytes.
  */
 export type ResolutionDiagnosticEntry = {
   diagnosticRef: string;
@@ -54,23 +47,12 @@ export type ResolutionDiagnosticEntry = {
 };
 
 /**
- * ADR 0012 decision 2: additive, honest disclosure of how the acting path
- * resolved its target, attached to every press/click/fill/longpress response.
- * Pre-action only — never a substitute for `--verify`/`--settle` post-action
- * evidence, and never itself ref-issuing (see `ResolutionDiagnosticEntry`).
- *
- * - `runtime`/`unique`: the daemon-tree selector or ref path matched exactly
- *   one node.
- * - `runtime`/`disambiguated`: `resolveSelectorChain` picked among
- *   `matchCount` matches via the existing visible/deepest/smallest-area
- *   heuristic; `alternatives` lists at most 5 losing candidates (the winner is
- *   never included).
- * - `ref`/`exact`: an `@ref` names exactly one node by construction.
- * - `ref`/`label-fallback`: a stale or unusable `@ref` was recovered with its
- *   trailing replay label. This is first-match label lookup, never exact ref
- *   provenance.
- * - `direct-ios`/`not-observed`: the direct iOS XCTest fast path has no
- *   daemon tree and cannot truthfully report a match count or candidates.
+ * ADR 0012 decision 2: pre-action disclosure of how the acting path resolved
+ * its target, on every press/click/fill/longpress response. Never ref-issuing.
+ * `direct-ios`/`not-observed` = the XCTest fast path has no daemon tree to
+ * report from; `ref`/`label-fallback` = a stale `@ref` recovered via
+ * first-match label lookup, never exact ref provenance; `alternatives` holds
+ * at most 5 losing candidates, winner excluded.
  */
 export type ResolutionDisclosure =
   | { source: 'runtime'; phase: 'pre-action'; kind: 'unique' }

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

@@ -6,7 +6,6 @@ import type {
   ResolutionDisclosure,
   SettleObservation,
 } from '../../contracts/interaction.ts';
-import { MAESTRO_NON_HITTABLE_FALLBACK_MESSAGE } from '../../core/interactor-types.ts';
 import { successText } from '../../utils/success-text.ts';
 import { interactionResultExtra } from './interaction-touch-targets.ts';
 
@@ -38,8 +37,17 @@ export type InteractionResponseSource =
       data: Record<string, unknown>;
       publicData?: Record<string, unknown>;
       point: { x: number; y: number };
+      /** Maestro owns matching on fallback dispatches: resolutionDisclosure is inapplicable there (ADR 0012). */
+      maestroFallback?: boolean;
     };
 
+// ADR 0012 decision 2: the XCTest fast path has no daemon tree, so it can only
+// disclose that resolution was not observed.
+const DIRECT_IOS_NOT_OBSERVED_RESOLUTION: ResolutionDisclosure = {
+  source: 'direct-ios',
+  kind: 'not-observed',
+};
+
 export type InteractionResponsePayloads = {
   /** Recorded in session history and used for touch visualization. */
   result: Record<string, unknown>;
@@ -76,10 +84,9 @@ export function buildInteractionResponseData(params: {
 }): InteractionResponsePayloads {
   const { source, referenceFrame, extra } = params;
   if (source.kind === 'runner-payload') {
-    const resolution = directIosResolutionDisclosure(source.data);
     const commonExtra = {
       targetKind: source.targetKind,
-      ...(resolution ? { resolution } : {}),
+      ...(source.maestroFallback ? {} : { resolution: DIRECT_IOS_NOT_OBSERVED_RESOLUTION }),
       ...(extra ?? {}),
     };
     const result = buildTouchPayload({
@@ -132,22 +139,6 @@ export function buildInteractionResponseData(params: {
   return { result: visualization, responseData };
 }
 
-/**
- * ADR 0012 decision 2: the direct iOS XCTest fast path has no daemon tree and
- * cannot truthfully report a match count or candidates, so it discloses only
- * the explicit `not-observed` provenance marker — UNLESS the runner actually
- * used the maestro-non-hittable-fallback coordinate tap (a distinct dispatch
- * path in the ADR 0011 registry whose whole point is bypassing element
- * semantics), in which case `resolutionDisclosure` is inapplicable and no
- * field is attached at all.
- */
-function directIosResolutionDisclosure(
-  data: Record<string, unknown> | undefined,
-): ResolutionDisclosure | undefined {
-  if (data?.message === MAESTRO_NON_HITTABLE_FALLBACK_MESSAGE) return undefined;
-  return { source: 'direct-ios', kind: 'not-observed' };
-}
-
 // Attaches refsGeneration inside the settle payload when the response is
 // ref-issuing (diff present). Overrides the raw `settle` from
 // interactionResultExtra by key order in the extras spread.

src/daemon/handlers/interaction-touch.ts

@@ -401,7 +401,14 @@ async function dispatchDirectIosSelectorInteraction(params: {
       data,
     });
     const { result, responseData } = buildInteractionResponseData({
-      source: { kind: 'runner-payload', targetKind: 'selector', data, publicData, point },
+      source: {
+        kind: 'runner-payload',
+        targetKind: 'selector',
+        data,
+        publicData,
+        point,
+        maestroFallback: selector.allowNonHittableCoordinateFallback === true,
+      },
       referenceFrame: readReferenceFrameFromDirectSelectorTapResult(data),
       extra: {
         ...extra,

src/daemon/response-views.ts

@@ -139,25 +139,15 @@ function selectorReadView(data: DaemonResponseData, level: ResponseLevel): Daemo
   return { ...data, node: compactSelectorNode(node as SnapshotNode) };
 }
 
-/**
- * Token-cheap settle + resolution digest for interaction commands. Applies
- * two independent, CONSERVATIVE transforms and returns the data UNCHANGED at
- * every level but `digest`, so plain interaction responses stay
- * byte-identical elsewhere.
- */
+// Token-cheap interaction digest: settle + resolution transforms compose;
+// non-digest levels stay byte-identical.
 function interactionDigestView(data: DaemonResponseData, level: ResponseLevel): DaemonResponseData {
   if (level !== 'digest') return data;
   return applySettleDigest(applyResolutionDigest(data));
 }
 
-/**
- * ADR 0012 decision 2: only acts on a `resolution.kind === 'disambiguated'`
- * payload and otherwise returns the data UNCHANGED. Drops the bounded
- * `alternatives` list — the verbose per-candidate detail — while keeping
- * `matchCount`/`tiebreak`/`winnerDiagnostic`, matching the settle digest's
- * philosophy: the digest answer is the verdict and counts; the candidate list
- * is the default-level payload.
- */
+// Like the settle digest, the verdict fields are the digest answer and the
+// verbose list (`alternatives`) is the default-level payload (ADR 0012).
 function applyResolutionDigest(data: DaemonResponseData): DaemonResponseData {
   const resolution = data.resolution;
   if (!resolution || typeof resolution !== 'object' || Array.isArray(resolution)) return data;

src/daemon/selectors-resolve.ts

@@ -11,15 +11,11 @@ export type SelectorDiagnostics = {
   matches: number;
 };
 
-/**
- * ADR 0012 decision 2: surfaced only when `resolveSelectorChain` picked among
- * more than one match. `alternatives` are every OTHER matched node (document
- * order), unbounded here — callers building the pre-action disclosure cap it
- * at 5.
- */
+/** Present only when the heuristic picked among N>1 matches (ADR 0012). */
 export type SelectorDisambiguationDisclosure = {
   matchCount: number;
   tiebreak: DisambiguationTiebreak;
+  /** Every losing matched node, document order, uncapped (response layer caps). */
   alternatives: SnapshotNode[];
 };
 
@@ -147,8 +143,7 @@ function analyzeSelectorMatches(
   firstNode: SnapshotNode | null;
   disambiguated: SnapshotNode | null;
   tiebreak: DisambiguationTiebreak | null;
-  // ADR 0012 decision 2: every matched node (including the winner), document
-  // order — callers derive `alternatives` by excluding the winner.
+  /** Every matched node (winner included), document order. */
   candidates: SnapshotNode[];
 } {
   let count = 0;
@@ -211,12 +206,7 @@ function accumulateDisambiguationCandidate(
   }
 }
 
-/**
- * The resolution winner is deliberately still picked by the existing running
- * comparator above. For disclosure, compare that winner with its best losing
- * challenger rather than leaking the first document-order comparison that
- * happened to set state. This is a side channel only.
- */
+// Disclosure only (winner vs strongest challenger); never picks the winner.
 function findDecidingTiebreak(
   candidates: readonly SnapshotNode[],
   winner: SnapshotNode | null,

src/mcp/__tests__/command-tools.test.ts

@@ -672,10 +672,8 @@ test('MCP never pins resolution.winnerDiagnostic/alternatives — they are pre-a
 
   await executor.execute('snapshot', { session: 'demo' });
   await executor.execute('press', { session: 'demo', target: { kind: 'ref', ref: '@e2' } });
-  // e3 was issued by the snapshot (generation 7) but NEVER by the press
-  // response's `resolution` field — if pinning mistakenly read
-  // diagnosticRef/alternatives as issued refs, this would forward pinned;
-  // it must still forward at the snapshot's own generation.
+  // e3 must stay pinned at the SNAPSHOT's generation, untouched by the press
+  // response's resolution diagnostics.
   await executor.execute('press', { session: 'demo', target: { kind: 'ref', ref: '@e3' } });
 
   assert.deepEqual(runCalls[1]?.input, { session: 'demo', target: { kind: 'ref', ref: '@e2~s7' } });
@@ -692,11 +690,7 @@ test('MCP never resolves a resolution diagnosticRef as a usable @ref — a fresh
     },
   });
 
-  // A caller that ignores the "opaque, non-@ token" contract and tries to
-  // act on a losing alternative directly: the input passes through
-  // unpinned/unmodified — pinning has no history for it (it was never
-  // issued), it is not stripped or special-cased, and it is left for the
-  // daemon's ordinary ref lookup to reject as any other unknown ref would be.
+  // Never issued, so it passes through unpinned for the daemon to reject.
   await executor.execute('press', {
     session: 'demo',
     target: { kind: 'ref', ref: '@diag-e3' },

src/mcp/command-output-schemas.ts

@@ -111,15 +111,9 @@ const resolutionDiagnosticEntrySchema: JsonSchema = objectSchema(
   ['diagnosticRef'],
 );
 
-/**
- * ResolutionDisclosure (src/contracts/interaction.ts) — ADR 0012 decision 2:
- * additive, honest pre-action disclosure of how the acting path resolved its
- * target. Absent entirely when resolutionDisclosure is `inapplicable` for the
- * path (coordinate, maestro-non-hittable-fallback). Never itself ref-issuing:
- * `winnerDiagnostic`/`alternatives` carry no `refsGeneration` and are never
- * MCP-pinned. `alternatives` is present at the default/full response levels
- * and deliberately omitted in the token-cheap digest view.
- */
+// ResolutionDisclosure (src/contracts/interaction.ts) — never ref-issuing;
+// absent on paths where the guarantee is inapplicable (ADR 0012 decision 2).
+// `alternatives` rides default/full levels only; the digest view omits it.
 const resolutionDisclosureSchema: JsonSchema = {
   type: 'object',
   description:

test/integration/interaction-contract/coordinate.contract.test.ts

@@ -104,12 +104,7 @@ test(scenario('responseConstruction'), async () => {
   });
 });
 
-// ADR 0012 decision 2: resolutionDisclosure is `inapplicable` on this path —
-// no element was resolved, so no `resolution` field is attached at all (not
-// even a "not-observed" marker; that marker exists ONLY for the direct-iOS
-// path, which DID attempt an element resolution). Not registered in the
-// coverage manifest: the coverage gate rejects claims against inapplicable
-// cells.
+// Inapplicable cell (ADR 0012), so intentionally absent from the coverage manifest.
 test('coordinate resolutionDisclosure: inapplicable — no resolution field is attached', async () => {
   await withIosContractDaemon([runnerTapEntry({ x: 100, y: 200 })], async (daemon) => {
     const press = await daemon.callCommand('press', ['100', '200']);