Skip to content

Commit 2c72b24

Browse files
committed
fix(daemon): a read-only command discloses dispatched no over any producer verdict
`dispatched` answers whether a resend is safe. A command the registry declares read-only (`recordingEffect: 'observes-app'`) has no side effect, so the interaction seam now sets `no` for it over a producer's `unknown` or `yes`, on both the thrown and the response path. Mutations keep the fill-if-absent `unknown`. The seam is renamed discloseInteractionDispatch since it no longer only fills. The golden row daemon.read-only-command now states it applies even when a producer classified the failure. ADR 0011 and the commands docs name the rule. Mutation checks: reverting the response path to fill-if-absent fails "a read-only command discloses no over a producer verdict" (get text whose capture throws dispatched unknown/yes); reverting the thrown path fails "a read-only command discloses no over a producer verdict it throws". Consumers unaffected: direct-ios-selector's fallback check and the runner lifecycle read `dispatched` inside the producer, before the seam, and only for tap/interaction commands.
1 parent 0bf735a commit 2c72b24

6 files changed

Lines changed: 61 additions & 22 deletions

File tree

‎contracts/fixtures/dispatch-disclosure.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
{
2727
"id": "daemon.read-only-command",
2828
"producer": "daemon",
29-
"trigger": "an unclassified failure of a command the registry declares read-only (recordingEffect observes-app), e.g. get",
29+
"trigger": "any failure of a command the registry declares read-only (recordingEffect observes-app), e.g. get, even one a producer classified unknown or yes: a read has no side effect",
3030
"dispatched": "no"
3131
},
3232
{

‎docs/adr/0011-interaction-guarantee-contract.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,9 @@ dispatch (target resolution, admission, a runner pre-send refusal) may say
158158
`unknown` once, around interaction dispatch, for a failure no producer
159159
classified, and never overwrites a producer's value: a wrong `no` makes a
160160
consumer resend an action that already ran, while a wrong `unknown` only costs
161-
an observation. Each row names its driver
161+
an observation. The one exception is a read-only command (registry
162+
`recordingEffect: 'observes-app'`): the daemon sets `no` over any producer
163+
value, because a read has no side effect and is always safe to resend. Each row names its driver
162164
file by id prefix, that file drives the real producer, and a row marked
163165
`implementedBy` waits for the branch that ships it.
164166

‎src/daemon/interaction/internal/__tests__/interaction-dispatch-disclosure.test.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ import {
1616
mockTapPoint,
1717
resetGetRuntimeFixture,
1818
} from '../../../__tests__/interaction-get-runtime-fixture.ts';
19+
import { captureSnapshotWithInteractor } from '../../../snapshot-interactor-capture.ts';
20+
import { discloseInteractionDispatch } from '../interaction-dispatch-disclosure.ts';
1921
import { handleInteractionCommands } from '../../index.ts';
2022
import { assertAndroidPressStayedInApp } from '../interaction-android-escape.ts';
2123
import { contextFromFlags, makeSession } from './interaction-touch-fixtures.ts';
@@ -152,3 +154,42 @@ test('the daemon keeps a producer verdict instead of inferring its own', async (
152154
});
153155
}
154156
});
157+
158+
test('a read-only command discloses no over a producer verdict', async () => {
159+
const capture = vi.mocked(captureSnapshotWithInteractor);
160+
capture.mockClear();
161+
for (const dispatched of ['unknown', 'yes'] satisfies DispatchDisclosure[]) {
162+
capture.mockRejectedValueOnce(
163+
new AppError('COMMAND_FAILED', 'runner capture lost', { dispatched }),
164+
);
165+
await assert.rejects(
166+
press({ command: 'get', positionals: ['text', 'label="Missing"'] }),
167+
(error: unknown) => {
168+
assert.ok(error instanceof AppError);
169+
assert.equal(error.message, 'runner capture lost');
170+
assert.equal(error.details?.dispatched, 'no');
171+
return true;
172+
},
173+
);
174+
}
175+
assert.equal(capture.mock.calls.length, 2);
176+
});
177+
178+
test('a read-only command discloses no over a producer verdict it throws', async () => {
179+
const producerFailure = new AppError('COMMAND_FAILED', 'runner capture lost', {
180+
dispatched: 'unknown',
181+
});
182+
await assert.rejects(
183+
discloseInteractionDispatch(
184+
{ token: 't', session: 's', command: 'get', positionals: ['text', 'label="Missing"'] },
185+
async () => {
186+
throw producerFailure;
187+
},
188+
),
189+
(error: unknown) => {
190+
assert.equal(error, producerFailure);
191+
assert.equal(producerFailure.details?.dispatched, 'no');
192+
return true;
193+
},
194+
);
195+
});

‎src/daemon/interaction/internal/interaction-dispatch-disclosure.ts‎

Lines changed: 13 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,34 @@
11
import {
22
AppError,
3-
type DispatchDisclosure,
3+
discloseDispatch,
44
discloseUnclassifiedDispatch,
55
} from '@agent-device/kernel/errors';
66
import { resolveCommandRecordingEffect } from '@agent-device/command-registry/registry';
77
import type { DaemonRequest, DaemonResponse } from '../../daemon-request.ts';
88

99
/**
10-
* The verdict for an interaction failure no producer classified. A request the registry declares
11-
* read-only (`recordingEffect: 'observes-app'`) never dispatches a mutation, so it is `no`.
12-
* Otherwise `unknown`: only a producer that refuses before dispatch may say `no`, and only one that
13-
* proved execution may say `yes`, and this layer cannot tell either from where the failure surfaced.
14-
* A producer's own verdict is always kept.
10+
* The daemon's verdict around interaction dispatch. A request the registry declares read-only
11+
* (`recordingEffect: 'observes-app'`) is `no` over any producer verdict: a read has no side effect,
12+
* so it is always safe to resend. Otherwise `unknown` fills only a failure no producer classified.
1513
*/
16-
export async function discloseUnclassifiedInteractionDispatch(
14+
export async function discloseInteractionDispatch(
1715
req: DaemonRequest,
1816
dispatch: () => Promise<DaemonResponse | null>,
1917
): Promise<DaemonResponse | null> {
20-
const verdict: DispatchDisclosure =
21-
resolveCommandRecordingEffect(req) === 'observes-app' ? 'no' : 'unknown';
18+
const readOnly = resolveCommandRecordingEffect(req) === 'observes-app';
2219
try {
2320
const response = await dispatch();
24-
if (!response || response.ok || response.error.details?.dispatched !== undefined) {
25-
return response;
26-
}
21+
if (!response || response.ok) return response;
22+
const producerVerdict = response.error.details?.dispatched;
23+
const dispatched = readOnly ? 'no' : (producerVerdict ?? 'unknown');
24+
if (dispatched === producerVerdict) return response;
2725
return {
2826
ok: false,
29-
error: {
30-
...response.error,
31-
details: { ...response.error.details, dispatched: verdict },
32-
},
27+
error: { ...response.error, details: { ...response.error.details, dispatched } },
3328
};
3429
} catch (error) {
35-
if (error instanceof AppError) throw discloseUnclassifiedDispatch(error, verdict);
36-
throw error;
30+
if (!(error instanceof AppError)) throw error;
31+
throw readOnly ? discloseDispatch(error, 'no') : discloseUnclassifiedDispatch(error, 'unknown');
3732
}
3833
}
3934

‎src/daemon/interaction/internal/interaction.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { type RequestCaptureProof, withCaptureDisclosures } from '../../capture-
44
import type { CaptureSnapshotForSession, InteractionRouteInput } from './types.ts';
55
import { dispatchFillViaRuntime } from './interaction-touch-fill.ts';
66
import { dispatchTargetedTouchViaRuntime } from './interaction-touch-press.ts';
7-
import { discloseUnclassifiedInteractionDispatch } from './interaction-dispatch-disclosure.ts';
7+
import { discloseInteractionDispatch } from './interaction-dispatch-disclosure.ts';
88
import { finalizeTouchInteraction } from './interaction-runtime.ts';
99
import { refSnapshotFlagGuardResponse } from '../../ref-snapshot-flag-policy.ts';
1010
import { dispatchGetViaRuntime, dispatchIsViaRuntime } from '../../selector-runtime.ts';
@@ -27,7 +27,7 @@ export async function handleInteractionCommands(
2727
): Promise<DaemonResponse | null> {
2828
const captureProof: RequestCaptureProof = {};
2929
const routed = { ...params, refSnapshotFlagGuardResponse, captureProof };
30-
const response = await discloseUnclassifiedInteractionDispatch(
30+
const response = await discloseInteractionDispatch(
3131
params.req,
3232
async () => await dispatchInteractionCommand(routed),
3333
);

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -495,6 +495,7 @@ When an interaction fails, read `error.details.dispatched` before you retry:
495495
- `yes`: the action ran on the device and failed after that. Take a snapshot and decide from what you see.
496496
- `unknown`: the action may have landed. Take a snapshot before you retry; a blind retry can tap, type, or navigate twice.
497497
498+
A read-only command such as `get` always reports `no`: it changes nothing, so a retry is safe.
498499
A failure without `dispatched` gives no such guarantee. Treat it as `unknown`.
499500
`type` accepts text only. Do not pass `@ref` to `type`; use `fill @ref "text"` to target a field directly, or `press @ref` then `type "text"` to append in the focused field.
500501
If `type` reports `TEXT_INPUT_NOT_FOCUSED`, focus a visible text input and retry; when accessibility does not expose the input, use a coordinate focus command before typing.

0 commit comments

Comments
 (0)