Skip to content

Commit 1c280da

Browse files
committed
fix: usage-based maestro fallback disclosure + spec label-fallback
Blocker 1: the runner-payload source now carries maestroFallbackUsed derived from the runner's actual execution outcome (the usedNonHittableFallback message bit RunnerTests+CommandExecution.swift reports, the same signal directIosSelectorFallbackDetails already keys on) instead of the permission flag. A fallback-allowed dispatch that hit its element normally discloses direct-ios/not-observed; only an actually-executed coordinate fallback is the inapplicable maestro cell. Contract tests cover both sides. Blocker 2: ADR-0012 decision 2 now defines the ref/label-fallback disclosure (runtime-ref trailing-label recovery via tryResolveRefNode's fallbackLabel; native-ref stays exact because the backend receives only the ref handle), amends the matrix-cell enumeration, layer-3 coverage list, and validation bullet, and the runtime-ref contract suite proves the label-fallback shape.
1 parent e933ed4 commit 1c280da

8 files changed

Lines changed: 80 additions & 17 deletions

File tree

‎CONTEXT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@
5757
- Snapshot capture plan: per-strategy ordered chain of iOS snapshot capture backends (recursive tree, query sweep, private AX) run by one plan runner under a shared wall-clock budget; recovery ordering is declared data, never a per-call-site branch.
5858
- Snapshot quality verdict: structured outcome (state, backend, reason code, effective depth, collapsed leaves) computed once by the plan runner and shipped with every planned snapshot payload; the daemon and CLI render it instead of re-deriving degradation from node shapes.
5959
- AX-unavailable target invalidation: iOS/macOS runner behavior where a root accessibility snapshot failure such as `kAXErrorIllegalArgument` marks the cached `XCUIApplication` target handle suspect. The runner fails closed for degraded interactive snapshots, clears the cached target, and lets the next command reacquire the app through normal activation.
60-
- Resolution disclosure (ADR 0012 decision 2): additive `resolution` field on press/click/fill/longpress responses discloses how the acting path resolved its target — `runtime`/`unique` or `runtime`/`disambiguated` (with `matchCount`/`winnerDiagnostic`/`tiebreak`/up-to-5 `alternatives`) on the daemon tree, `ref`/`exact` for an `@ref` (runtime-ref and native-ref), or `direct-ios`/`not-observed` on the XCTest fast path; absent entirely on the coordinate and maestro-non-hittable-fallback paths. Pre-action diagnostics only: `winnerDiagnostic`/`alternatives` entries carry an opaque, non-`@` `diagnosticRef` that is never ref-issued, never MCP-pinned, and cannot be reused as an `@ref` target — a fresh snapshot/find is required before acting on an alternative.
60+
- Resolution disclosure (ADR 0012 decision 2): additive `resolution` field on press/click/fill/longpress responses discloses how the acting path resolved its target — `runtime`/`unique` or `runtime`/`disambiguated` (with `matchCount`/`winnerDiagnostic`/`tiebreak`/up-to-5 `alternatives`) on the daemon tree, `ref`/`exact` for a resolved `@ref` (runtime-ref and native-ref), `ref`/`label-fallback` when runtime-ref recovered a stale `@ref` via its recorded trailing label, or `direct-ios`/`not-observed` on the XCTest fast path; absent entirely on the coordinate path and on dispatches whose runner actually executed the maestro non-hittable coordinate fallback (permission alone keeps the direct path's `not-observed`). Pre-action diagnostics only: `winnerDiagnostic`/`alternatives` entries carry an opaque, non-`@` `diagnosticRef` that is never ref-issued, never MCP-pinned, and cannot be reused as an `@ref` target — a fresh snapshot/find is required before acting on an alternative.
6161

6262
## Architecture (perfect-shape refactor, completed 2026-07)
6363

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,14 @@ fresh `snapshot`/`find`. A post-action `--settle` diff remains a separate, actio
195195
fresh pinned refs. In contrast, a target-binding divergence sends no action; its fresh report snapshot is
196196
an actionable issuer as defined in decision 4.
197197

198+
The ref paths disclose ref provenance. A lookup that resolves the `@ref` itself is
199+
`{ source: "ref", phase: "pre-action", kind: "exact" }`. When the runtime-ref path recovers a stale or
200+
unusable `@ref` through its recorded trailing label (`tryResolveRefNode`'s `fallbackLabel` — a first-match
201+
label lookup, the replay recovery documented in Context), the response instead carries
202+
`{ source: "ref", phase: "pre-action", kind: "label-fallback" }`: label recovery is not exact ref
203+
provenance and must never claim it. The native-ref fast path always discloses `exact` — it dispatches the
204+
ref handle itself and never forwards the fallback label to the backend.
205+
198206
The accepted direct-iOS selector fast path has no daemon tree and the XCTest response cannot truthfully
199207
provide a match count, candidate refs, or a runtime tiebreak. It remains enabled for ordinary simple
200208
`press`/`fill`, but its canonical response instead carries
@@ -204,15 +212,20 @@ runtime resolution. Recording likewise disables it for any action for which targ
204212
required by decision 3.
205213

206214
ADR 0011's matrix must add a `resolutionDisclosure` guarantee with all six honest cells: `runtime-selector`
207-
enforces the complete pre-action diagnostic shape; `runtime-ref` and `native-ref` enforce
208-
`{ source: "ref", phase: "pre-action", kind: "exact" }`; `direct-ios-selector` enforces only the explicit
215+
enforces the complete pre-action diagnostic shape; `runtime-ref` enforces the ref-provenance shapes
216+
(`exact`, or `label-fallback` for trailing-label recovery) and `native-ref` enforces `exact`;
217+
`direct-ios-selector` enforces only the explicit
209218
`{ source: "direct-ios", kind: "not-observed" }` shape; `coordinate` is inapplicable because no element
210219
was resolved; and `maestro-non-hittable-fallback` is inapplicable because Maestro owns matching and the
211-
fallback is coordinate execution. The four enforced cells use the shared response builder. Its existing
220+
fallback is coordinate execution. Membership in the maestro cell is decided by the EXECUTED dispatch, not
221+
the permission flag: a press that was allowed to fall back but hit its element normally is the direct-iOS
222+
path and discloses `not-observed`; only a response whose runner actually executed the coordinate fallback
223+
is the inapplicable maestro cell. The four enforced cells use the shared response builder. Its existing
212224
direct-path `disambiguation` and `responseIdentity` waivers remain, and the exact waived-cell test must
213225
continue to list them. Layer-3 coverage must claim every enforced/delegated cell: runtime
214226
ambiguity/tiebreak/cap plus non-actionable diagnostics after mutation, exact-ref provenance for runtime
215-
and native refs, and a direct-iOS no-snapshot `not-observed` case. No selection-parity table is claimed or
227+
and native refs, the runtime-ref `label-fallback` recovery case, and a direct-iOS no-snapshot
228+
`not-observed` case. No selection-parity table is claimed or
216229
added for the direct path: such a table would falsely imply XCTest selection has runtime parity. A future
217230
runner-side diagnostic design must replace the two waivers, add a Swift/TypeScript parity fixture, and add
218231
the corresponding provider contract cases in the same change.
@@ -450,8 +463,10 @@ Successful text replay prints one line with replayed count and wall time; `--jso
450463
Implementation is not accepted on benchmark evidence alone. Required automated coverage is:
451464

452465
- matrix and provider contracts for all six `resolutionDisclosure` cells: runtime ambiguity/tiebreak and
453-
the five-alternative limit, runtime/native exact-ref provenance, direct-iOS `not-observed`, coordinate
454-
and Maestro inapplicability, and the retained direct-path waiver list;
466+
the five-alternative limit, runtime/native exact-ref provenance plus the runtime-ref `label-fallback`
467+
recovery disclosure, direct-iOS `not-observed`, coordinate inapplicability, Maestro inapplicability on
468+
both sides of the permission (fallback taken, and allowed-but-not-taken disclosing `not-observed`), and
469+
the retained direct-path waiver list;
455470
- an interaction mutation contract proving pre-action resolution diagnostics are not ref-issued or
456471
MCP-pinned, a fresh snapshot is required before using an alternative, and a no-action target-binding
457472
divergence can issue and pin its fresh report refs;

‎src/contracts/interaction-guarantees.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -418,7 +418,8 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
418418
},
419419
resolutionDisclosure: {
420420
kind: 'inapplicable',
421-
reason: 'Maestro owns matching; the fallback is coordinate execution.',
421+
reason:
422+
'Maestro owns matching; the fallback is coordinate execution. Cell membership is usage-based: only a dispatch whose runner actually executed the coordinate fallback is this path — allowed-but-not-taken is the direct path and discloses not-observed.',
422423
},
423424
},
424425
},

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@ export type InteractionResponseSource =
3737
data: Record<string, unknown>;
3838
publicData?: Record<string, unknown>;
3939
point: { x: number; y: number };
40-
/** Maestro owns matching on fallback dispatches: resolutionDisclosure is inapplicable there (ADR 0012). */
41-
maestroFallback?: boolean;
40+
/** The runner actually EXECUTED the non-hittable coordinate fallback (never the mere permission) — that dispatch is the maestro path, whose resolutionDisclosure is inapplicable (ADR 0012). */
41+
maestroFallbackUsed?: boolean;
4242
};
4343

4444
// ADR 0012 decision 2: the XCTest fast path has no daemon tree, so it can only
@@ -86,7 +86,7 @@ export function buildInteractionResponseData(params: {
8686
if (source.kind === 'runner-payload') {
8787
const commonExtra = {
8888
targetKind: source.targetKind,
89-
...(source.maestroFallback ? {} : { resolution: DIRECT_IOS_NOT_OBSERVED_RESOLUTION }),
89+
...(source.maestroFallbackUsed ? {} : { resolution: DIRECT_IOS_NOT_OBSERVED_RESOLUTION }),
9090
...(extra ?? {}),
9191
};
9292
const result = buildTouchPayload({

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -400,19 +400,20 @@ async function dispatchDirectIosSelectorInteraction(params: {
400400
flags: handlerParams.req.flags,
401401
data,
402402
});
403+
const fallbackDetails = directIosSelectorFallbackDetails(selector, data);
403404
const { result, responseData } = buildInteractionResponseData({
404405
source: {
405406
kind: 'runner-payload',
406407
targetKind: 'selector',
407408
data,
408409
publicData,
409410
point,
410-
maestroFallback: selector.allowNonHittableCoordinateFallback === true,
411+
maestroFallbackUsed: fallbackDetails.maestroNonHittableCoordinateFallbackUsed === true,
411412
},
412413
referenceFrame: readReferenceFrameFromDirectSelectorTapResult(data),
413414
extra: {
414415
...extra,
415-
...directIosSelectorFallbackDetails(selector, data),
416+
...fallbackDetails,
416417
},
417418
});
418419
return finalizeTouchInteraction({

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

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,12 +48,32 @@ test(scenario('responseConstruction'), async () => {
4848
assert.equal(data.maestroNonHittableCoordinateFallbackAllowed, true);
4949
assert.equal(data.maestroNonHittableCoordinateFallbackUsed, true);
5050
assert.equal(data.maestroFallbackReason, 'non-hittable-coordinate');
51-
// Inapplicable resolutionDisclosure cell (ADR 0012): no resolution field.
51+
// Fallback actually TAKEN: the inapplicable maestro cell, no resolution field.
5252
assert.equal(data.resolution, undefined);
5353
},
5454
);
5555
});
5656

57+
// Permission is not usage: with the fallback allowed but the runner hitting
58+
// the element normally ("tapped"), the dispatch is the direct-ios path and
59+
// must disclose not-observed, not classify as the maestro-fallback cell.
60+
test('maestro-non-hittable-fallback resolutionDisclosure: allowed-but-not-taken discloses direct-ios not-observed', async () => {
61+
await withIosContractDaemon(
62+
[runnerTapEntry({ x: 50, y: 60, message: 'tapped' })],
63+
async (daemon, transcript) => {
64+
const click = await daemon.callCommand('click', ['label=Pin'], MAESTRO_FLAGS);
65+
const data = assertRpcOk(click);
66+
67+
const tapRequest = transcript.calls[0]?.request as Record<string, unknown> | undefined;
68+
assert.equal(tapRequest?.allowNonHittableCoordinateFallback, true);
69+
70+
assert.equal(data.maestroNonHittableCoordinateFallbackAllowed, true);
71+
assert.equal(data.maestroNonHittableCoordinateFallbackUsed, false);
72+
assert.deepEqual(data.resolution, { source: 'direct-ios', kind: 'not-observed' });
73+
},
74+
);
75+
});
76+
5777
test(scenario('offscreen'), async () => {
5878
await withIosContractDaemon(
5979
[

‎test/integration/interaction-contract/runtime-ref.contract.test.ts‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import type { InteractionGuarantee } from '../../../src/contracts/interaction-gu
44
import type { Point } from '../../../src/kernel/snapshot.ts';
55
import { ref } from '../../../src/commands/index.ts';
66
import { assertRpcOk } from '../provider-scenarios/assertions.ts';
7-
import { scenarioName } from './coverage-manifest.ts';
7+
import { scenarioName, scenarioNames } from './coverage-manifest.ts';
88
import { RUNTIME_REF_COVERAGE } from './runtime-ref.coverage.ts';
99
import {
1010
closedDrawerSnapshot,
@@ -164,7 +164,7 @@ test(scenario('responseConstruction'), async () => {
164164
);
165165
});
166166

167-
test(scenario('resolutionDisclosure'), async () => {
167+
test(scenarioNames(RUNTIME_REF_COVERAGE, 'resolutionDisclosure')[0]!, async () => {
168168
const device = createContractDevice(continueButtonSnapshot(), {
169169
tap: async () => ({ ok: true }),
170170
});
@@ -174,3 +174,27 @@ test(scenario('resolutionDisclosure'), async () => {
174174
assert.equal(result.kind, 'ref');
175175
assert.deepEqual(result.resolution, { source: 'ref', phase: 'pre-action', kind: 'exact' });
176176
});
177+
178+
test(scenarioNames(RUNTIME_REF_COVERAGE, 'resolutionDisclosure')[1]!, async () => {
179+
const taps: Point[] = [];
180+
const device = createContractDevice(continueButtonSnapshot(), {
181+
tap: async (_context, point) => {
182+
taps.push(point);
183+
},
184+
});
185+
186+
// @e9 is not in the stored tree; the recorded trailing label recovers the
187+
// Continue button by first label match.
188+
const result = await device.interactions.click(ref('@e9', { fallbackLabel: 'Continue' }), {
189+
session: 'default',
190+
});
191+
192+
assert.equal(taps.length, 1);
193+
assert.equal(result.kind, 'ref');
194+
assert.equal(result.node?.label, 'Continue');
195+
assert.deepEqual(result.resolution, {
196+
source: 'ref',
197+
phase: 'pre-action',
198+
kind: 'label-fallback',
199+
});
200+
});

‎test/integration/interaction-contract/runtime-ref.coverage.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ export const RUNTIME_REF_COVERAGE = definePathCoverage('runtime-ref', {
1212
settleObservation:
1313
'runtime-ref settleObservation: press @ref --settle diffs the settled tree against the stored baseline',
1414
errorTaxonomy: 'runtime-ref errorTaxonomy: unknown ref fails with the stale-ref hint',
15-
resolutionDisclosure:
15+
resolutionDisclosure: [
1616
'runtime-ref resolutionDisclosure: an @ref discloses the exact ref-provenance shape',
17+
'runtime-ref resolutionDisclosure: trailing-label recovery discloses label-fallback, never exact',
18+
],
1719
});

0 commit comments

Comments
 (0)