Skip to content

Commit 5ba531f

Browse files
thymikeeclaude
andauthored
feat(interaction): pre-dispatch admission owner for runtime press/click (#4461)
* feat(interaction): pre-dispatch admission owner for runtime press/click Give runtime-resolved press and click one admission step between resolution and the backend call (ADR 0039, slice 1 of #4456). Both moving-target schedules become one observe-until loop under one hard bound: the request signal and the earlier of the execution and result deadlines. observe-until gains an optional hard deadline that minPolls and verdicts cannot extend. Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(interaction): let the hard deadline win in observe-until Check the hard deadline before judging an initial value and before the soft budget's expiry, cover a capture that ends exactly at the deadline, bound the earliest-deadline test on both sides, and name the refusal reasons in the command docs. Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(interaction): end in-flight admission reads at the request deadline Reads during admission carry a signal that also aborts at the request deadline, and an aborted read refuses with the typed reason. The runtime sleep ends on abort with or without an installed clock. Kernel owns the request-deadline reason constant and predicate; host-kit dispatches on them. Co-Authored-By: Claude Opus 5.5 <[email protected]> * test(interaction): assert no look follows a cancelled clock sleep Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(interaction): arm the admission deadline timer only within its range AbortSignal.timeout rejects infinite or fractional delays and fires after 1 ms beyond 2^31-1 ms. Round the remaining time and arm the timer only in range; the clock checks still hold any deadline. Co-Authored-By: Claude Opus 5.5 <[email protected]> * fix(interaction): arm the deadline timer lazily and explain an early refusal Only a look arms the request-deadline timer, so an idle press builds no timer. A deadline refusal carries the request id and the remaining time, and its hint says the remaining time cannot cover the wait. A daemon test pins the deadlineAtMs hand-off to press and click. Co-Authored-By: Claude Opus 5.5 <[email protected]> * test(interaction): cover the execution-deadline hand-off and restore the timer spy Assert the daemon hands off an execution deadline earlier than the result deadline, restore the AbortSignal.timeout spy in finally, and word the deadline hint so it fits a deadline that passed before any wait. Co-Authored-By: Claude Opus 5.5 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 4de101e commit 5ba531f

16 files changed

Lines changed: 1026 additions & 253 deletions

File tree

‎packages/capture-kit/src/observe-until.test.ts‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,3 +195,107 @@ describe('observeUntil late capture', () => {
195195
assert.equal(observed.polls.length, 2);
196196
});
197197
});
198+
199+
describe('observeUntil hard deadline', () => {
200+
test('minPolls cannot take a poll that would start at or after the deadline', async () => {
201+
const clock = fakeClock();
202+
let captures = 0;
203+
const observed = await observeUntil({
204+
capture: async () => {
205+
captures += 1;
206+
return captures;
207+
},
208+
verdict: () => ({ kind: 'continue' }),
209+
schedule: { ...SCHEDULE, minPolls: 3 },
210+
deadlineMs: clock.now() + 300,
211+
clock,
212+
});
213+
assert.equal(observed.kind, 'deadline');
214+
assert.equal(observed.kind === 'deadline' && observed.last, 2);
215+
assert.deepEqual(clock.slept, [200]);
216+
});
217+
218+
test('a verdict that raises the budget cannot pass the deadline', async () => {
219+
const clock = fakeClock();
220+
const observed = await observeUntil({
221+
capture: async () => 1,
222+
verdict: () => ({ kind: 'continue', budgetMs: 10_000 }),
223+
schedule: SCHEDULE,
224+
deadlineMs: clock.now() + 500,
225+
clock,
226+
});
227+
assert.equal(observed.kind, 'deadline');
228+
assert.ok(observed.waitedMs < 500);
229+
});
230+
231+
test('a capture that finishes at or past the deadline is not judged', async () => {
232+
const clock = fakeClock();
233+
let judged = 0;
234+
const observed = await observeUntil({
235+
capture: async () => {
236+
clock.advance(400);
237+
return 'late';
238+
},
239+
verdict: () => {
240+
judged += 1;
241+
return { kind: 'done', result: 'accepted' };
242+
},
243+
schedule: SCHEDULE,
244+
deadlineMs: clock.now() + 300,
245+
clock,
246+
});
247+
assert.equal(observed.kind, 'deadline');
248+
assert.equal(judged, 0);
249+
assert.equal(observed.polls.length, 1);
250+
});
251+
});
252+
253+
describe('observeUntil hard deadline precedence', () => {
254+
test('a capture that finishes exactly at the deadline is not judged', async () => {
255+
const clock = fakeClock();
256+
let judged = 0;
257+
const observed = await observeUntil({
258+
capture: async () => {
259+
clock.advance(300);
260+
return 'on time?';
261+
},
262+
verdict: () => {
263+
judged += 1;
264+
return { kind: 'done', result: 'accepted' };
265+
},
266+
schedule: SCHEDULE,
267+
deadlineMs: clock.now() + 300,
268+
clock,
269+
});
270+
assert.equal(observed.kind, 'deadline');
271+
assert.equal(judged, 0);
272+
});
273+
274+
test('an initial value is not judged once the deadline has passed', async () => {
275+
const clock = fakeClock();
276+
const observed = await observeUntil({
277+
capture: async () => 2,
278+
verdict: (latest) => ({ kind: 'done', result: latest }),
279+
schedule: SCHEDULE,
280+
initial: 1,
281+
deadlineMs: clock.now(),
282+
clock,
283+
});
284+
assert.equal(observed.kind, 'deadline');
285+
});
286+
287+
test('the deadline wins when a slow verdict spends both the budget and the deadline', async () => {
288+
const clock = fakeClock();
289+
const observed = await observeUntil({
290+
capture: async () => 1,
291+
verdict: () => {
292+
clock.advance(2_000);
293+
return { kind: 'continue' };
294+
},
295+
schedule: SCHEDULE,
296+
deadlineMs: clock.now() + 1_500,
297+
clock,
298+
});
299+
assert.equal(observed.kind, 'deadline');
300+
});
301+
});

‎packages/capture-kit/src/observe-until.ts‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,13 @@ export type ObservationEvidence = Readonly<{
4040

4141
/**
4242
* How an observation loop ended: `done` when the verdict accepted a capture, `expired` when the
43-
* budget ran out while the verdict still said continue, `failed` when a capture threw.
43+
* budget ran out while the verdict still said continue, `deadline` when the hard deadline ended it,
44+
* `failed` when a capture threw.
4445
*/
4546
type ObservedEnd<T, R> =
4647
| Readonly<{ kind: 'done'; result: R; value: T }>
4748
| Readonly<{ kind: 'expired'; last: T | undefined }>
49+
| Readonly<{ kind: 'deadline'; last: T | undefined }>
4850
| Readonly<{ kind: 'failed'; last: T | undefined; error: unknown }>;
4951

5052
export type Observed<T, R> = ObservationEvidence & ObservedEnd<T, R>;
@@ -57,6 +59,11 @@ export type ObserveUntilParams<T, R> = Readonly<{
5759
clock?: ObservationClock;
5860
/** A capture the caller already holds; judged first, without a poll. */
5961
initial?: T;
62+
/**
63+
* Clock time that ends the loop whatever the verdict or `minPolls` asks: no poll starts at or
64+
* after it, and a capture that finishes at or past it is not judged.
65+
*/
66+
deadlineMs?: number;
6067
}>;
6168

6269
const REAL_CLOCK: ObservationClock = {
@@ -96,6 +103,7 @@ export async function observeUntil<T, R>(
96103
},
97104
};
98105
if (params.initial !== undefined) {
106+
if (remainingMs(loop, 'hard') <= 0) return finish(loop, { kind: 'deadline', last: undefined });
99107
loop.state.observations += 1;
100108
const done = judge(loop, params.initial);
101109
if (done) return done;
@@ -108,23 +116,32 @@ export async function observeUntil<T, R>(
108116
}
109117
}
110118

111-
function remainingMs<T, R>({ state, clock }: Loop<T, R>): number {
119+
/** Time left in the soft budget, or with `hard`, before the hard deadline. */
120+
function remainingMs<T, R>({ state, clock, params }: Loop<T, R>, hard?: 'hard'): number {
121+
if (hard) return (params.deadlineMs ?? Infinity) - clock.now();
112122
return state.startedMs + state.budgetMs - clock.now();
113123
}
114124

115125
function mustPoll<T, R>({ params, state }: Loop<T, R>): boolean {
116126
return state.observations < (params.schedule.minPolls ?? 1);
117127
}
118128

119-
/** Sleeps one interval between observations; ends the loop when the budget is spent first. */
129+
/**
130+
* Sleeps one interval between observations; ends the loop when the budget is spent first, or when
131+
* the next poll could not start before the hard deadline.
132+
*/
120133
async function waitBeforePoll<T, R>(loop: Loop<T, R>): Promise<Observed<T, R> | undefined> {
121134
const { state, clock, params } = loop;
135+
const deadline = () => finish(loop, { kind: 'deadline', last: state.last });
136+
if (remainingMs(loop, 'hard') <= 0) return deadline();
122137
if (state.observations === 0) return undefined;
123138
const forced = mustPoll(loop);
124139
if (!forced && remainingMs(loop) <= 0) return finish(loop, { kind: 'expired', last: state.last });
125140
const { intervalMs } = params.schedule;
126-
await clock.sleep(forced ? intervalMs : Math.max(0, Math.min(intervalMs, remainingMs(loop))));
127-
return undefined;
141+
const sleepMs = forced ? intervalMs : Math.max(0, Math.min(intervalMs, remainingMs(loop)));
142+
if (sleepMs >= remainingMs(loop, 'hard')) return deadline();
143+
await clock.sleep(sleepMs);
144+
return remainingMs(loop, 'hard') > 0 ? undefined : deadline();
128145
}
129146

130147
async function pollOnce<T, R>(loop: Loop<T, R>): Promise<Observed<T, R> | undefined> {
@@ -146,6 +163,7 @@ async function pollOnce<T, R>(loop: Loop<T, R>): Promise<Observed<T, R> | undefi
146163
return finish(loop, { kind: 'failed', last: state.last, error });
147164
}
148165
record('observed');
166+
if (remainingMs(loop, 'hard') <= 0) return finish(loop, { kind: 'deadline', last: state.last });
149167
return judge(loop, value);
150168
}
151169

‎packages/command-runtime/src/commands/interaction/runtime/interactions.ts‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import {
2020
type PostActionObservationOptions,
2121
} from './post-action-observation.ts';
2222
import { resolveInteractionTarget, type InteractionTarget } from './resolution.ts';
23-
import { guardResolvedTargetAgainstMotion } from './moving-target-gate.ts';
23+
import { admitResolvedTarget } from './pre-dispatch-admission.ts';
2424
import { pointObservationOf } from './target-visibility-stages.ts';
2525
import { dispatchNativeRefInteraction } from './native-ref-interaction.ts';
2626
import type {
@@ -145,8 +145,8 @@ async function tapCommand(
145145
: await maybeTapRefTarget(runtime, options, action);
146146
if (nativeRefTap) return nativeRefTap;
147147

148-
// One request object for the resolution and for the re-resolutions #3471's gate may spend, so the
149-
// second look is the same question asked again rather than a differently-configured one.
148+
// One request object for the resolution and for the looks admission may spend, so a second look is
149+
// the same question asked again rather than a differently-configured one.
150150
const resolutionRequest: ResolveInteractionTargetParams = {
151151
action,
152152
requireInteractive: true,
@@ -159,15 +159,7 @@ async function tapCommand(
159159
if (!runtime.backend.tap) {
160160
throw new AppError('UNSUPPORTED_OPERATION', 'tap is not supported by this backend');
161161
}
162-
// The moving-target gate (#3471): after every pre-dispatch guard has accepted the target and
163-
// before the device is touched. A press issued straight after an action that animated the UI can
164-
// otherwise resolve a point the control has already vacated and report success on the vacancy.
165-
const atRest = await guardResolvedTargetAgainstMotion(
166-
runtime,
167-
options,
168-
resolutionRequest,
169-
resolved,
170-
);
162+
const atRest = await admitResolvedTarget(runtime, options, resolutionRequest, resolved);
171163
const point = requireResolvedPoint(atRest);
172164
const pointObservation = pointObservationOf(atRest);
173165
let backendResult;

0 commit comments

Comments
 (0)