Skip to content

Commit f2d03a8

Browse files
committed
refactor: derive catalog operation list from one canonical tuple; move keyboard orchestration tests
NAVIGATION_INTERACTOR_OPERATIONS was declared as a plain readonly array independently of the NavigationInteractorOperation union it walked, so a future union member could compile without ever being added to the walk list, silently preventing an admitted fact from binding. Made the tuple the single canonical value: the union type is now derived from it via `(typeof TUPLE)[number]`, so LOCAL_BINDERS/PROVIDER_BINDERS' Record<NavigationInteractorOperation, ...> completeness is checked against the same tuple, not a separately hand-kept list. Added a regression test binding all seven operations at once to pin the runtime walk, independent of the type-level guarantee. Moved the four keyboard-orchestration tests (the two ADR 0014 ref-frame seam tests plus the two session/selector-guard tests) out of the mixed appstate/perf test file into a new session-selector-dispatch.test.ts, colocated with the file they exercise. Strengthened the rejection regression test to assert the frame is already expired from inside the rejecting keyboardDismiss callback itself, pinning the exact pre-invocation seam rather than only checking the end state after the dispatch settles.
1 parent e2ffc13 commit f2d03a8

4 files changed

Lines changed: 297 additions & 223 deletions

File tree

‎packages/contracts/src/interactor-operation-catalog.test.ts‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,71 @@ test('binds every admitted operation the facts name, not just the ones a caller
6565
expect(operations.tvRemote).toBeTypeOf('function');
6666
});
6767

68+
// #1955 review: the walk list and the per-operation binder records are both derived from one
69+
// canonical tuple now, so they can't drift at the type level — this pins the runtime behavior
70+
// that actually matters: every one of the seven operations binds when its fact admits it, not
71+
// just the two or three most tests happen to exercise.
72+
test('binds every one of the seven navigation operations when every fact admits it', async () => {
73+
const back = vi.fn(async () => undefined);
74+
const home = vi.fn(async () => undefined);
75+
const setOrientation = vi.fn(async () => undefined);
76+
const tvRemote = vi.fn(async () => undefined);
77+
const keyboardStatus = vi.fn(async () => ({ visible: false }));
78+
const keyboardDismiss = vi.fn(async () => ({ kind: 'acknowledged' }));
79+
const keyboardEnter = vi.fn(async () => undefined);
80+
const resolveInteractor = vi.fn(
81+
async () =>
82+
({
83+
back,
84+
home,
85+
setOrientation,
86+
tvRemote,
87+
keyboardStatus,
88+
keyboardDismiss,
89+
keyboardEnter,
90+
}) as unknown as Interactor,
91+
);
92+
93+
const operations = bindAdmittedLocalInteractorOperations({
94+
device,
95+
signal: new AbortController().signal,
96+
resolveInteractor,
97+
facts: {
98+
back: available,
99+
home: available,
100+
setOrientation: available,
101+
tvRemote: available,
102+
keyboardStatus: available,
103+
keyboardDismiss: available,
104+
keyboardEnter: available,
105+
},
106+
});
107+
108+
expect(operations.back).toBeTypeOf('function');
109+
expect(operations.home).toBeTypeOf('function');
110+
expect(operations.setOrientation).toBeTypeOf('function');
111+
expect(operations.tvRemote).toBeTypeOf('function');
112+
expect(operations.keyboardStatus).toBeTypeOf('function');
113+
expect(operations.keyboardDismiss).toBeTypeOf('function');
114+
expect(operations.keyboardEnter).toBeTypeOf('function');
115+
116+
await operations.back?.({});
117+
await operations.home?.({});
118+
await operations.setOrientation?.({ rotation: 'landscape-left' });
119+
await operations.tvRemote?.({ button: 'select' });
120+
await operations.keyboardStatus?.({});
121+
await operations.keyboardDismiss?.({});
122+
await operations.keyboardEnter?.({});
123+
124+
expect(back).toHaveBeenCalledOnce();
125+
expect(home).toHaveBeenCalledOnce();
126+
expect(setOrientation).toHaveBeenCalledOnce();
127+
expect(tvRemote).toHaveBeenCalledOnce();
128+
expect(keyboardStatus).toHaveBeenCalledOnce();
129+
expect(keyboardDismiss).toHaveBeenCalledOnce();
130+
expect(keyboardEnter).toHaveBeenCalledOnce();
131+
});
132+
68133
test('treats an operation missing from a partial facts map as unavailable', () => {
69134
const operations = bindAdmittedLocalInteractorOperations({
70135
device,

‎packages/contracts/src/interactor-operation-catalog.ts‎

Lines changed: 16 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -26,38 +26,30 @@ import {
2626

2727
/**
2828
* The seven navigation/keyboard operations every owner admits from the same shape: one fact,
29-
* one bind call, no owner mechanics in between. Naming the set here — rather than at each of the
30-
* seven owner call sites — is what lets an owner hand in its own facts instead of hand-writing the
31-
* same `facts.operations.<key>.available ? bind…(resolver) : {}` ternary seven times over.
29+
* one bind call, no owner mechanics in between. This tuple is the single canonical declaration:
30+
* the {@link NavigationInteractorOperation} union type is derived from it below, and
31+
* `LOCAL_BINDERS`/`PROVIDER_BINDERS`'s `Record<NavigationInteractorOperation, …>` types are then
32+
* checked against that derived union — so a member can never be added to one and silently missing
33+
* from another (#1955 review: an earlier design declared the walk list as a plain
34+
* `readonly NavigationInteractorOperation[]`, independently of the union it walked, which would
35+
* have compiled even missing a member; a caller-maintained `operations: [...]` array duplicating
36+
* this same set was removed for the identical reason in an earlier review round). Not
37+
* caller-supplied: `facts[operation]` is the only thing that decides whether an operation binds —
38+
* a key this tuple names but the caller's facts never define is simply never available
39+
* (`facts[operation]?.available` reads `undefined`), which is how a caller passing a narrower,
40+
* dedicated facts object (e.g. Limrun's keyboard-less navigation facts) opts a subset out.
3241
*/
33-
export type NavigationInteractorOperation =
34-
| 'back'
35-
| 'home'
36-
| 'setOrientation'
37-
| 'tvRemote'
38-
| 'keyboardStatus'
39-
| 'keyboardDismiss'
40-
| 'keyboardEnter';
41-
42-
/**
43-
* The fixed set every bind call walks. Not caller-supplied: an owner naming its own subset here
44-
* (`operations: [...]`) alongside its own `facts` was a second source of truth that could drift
45-
* from what the facts actually admit (#1955 review) — an operation present and admitted in
46-
* `facts` but missing from a hand-maintained list would silently never bind. `facts[operation]`
47-
* is the only thing that decides whether an operation binds; a key this list names but the
48-
* caller's facts never define is simply never available (`facts[operation]?.available` reads
49-
* `undefined`), which is exactly how a caller passing a narrower, dedicated facts object (e.g.
50-
* Limrun's keyboard-less navigation facts) already opts a subset out today.
51-
*/
52-
const NAVIGATION_INTERACTOR_OPERATIONS: readonly NavigationInteractorOperation[] = [
42+
const NAVIGATION_INTERACTOR_OPERATIONS = [
5343
'back',
5444
'home',
5545
'setOrientation',
5646
'tvRemote',
5747
'keyboardStatus',
5848
'keyboardDismiss',
5949
'keyboardEnter',
60-
];
50+
] as const;
51+
52+
export type NavigationInteractorOperation = (typeof NAVIGATION_INTERACTOR_OPERATIONS)[number];
6153

6254
type LocalBinderParams = Readonly<{
6355
device: DeviceInfo;

‎src/daemon/handlers/__tests__/session-appstate-input-perf.test.ts‎

Lines changed: 0 additions & 199 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,6 @@ import * as fs from 'node:fs';
33
import * as os from 'node:os';
44
import * as path from 'node:path';
55
import { AppError } from '@agent-device/kernel/errors';
6-
import {
7-
keyboardRuntimeOperationFacts,
8-
type KeyboardDismissResult,
9-
} from '@agent-device/contracts/keyboard-runtime';
10-
import {
11-
localRuntimeOwner,
12-
narrowDeviceBinding,
13-
type DeviceBinding,
14-
type RuntimeFacts,
15-
} from '@agent-device/contracts/platform-runtime';
16-
import type { PlatformRuntimeOperations } from '@agent-device/contracts/platform-runtime-operations';
17-
import { deviceShape, type DeviceInfo } from '@agent-device/kernel/device';
18-
import type {
19-
BindDeviceRuntime,
20-
InspectDeviceRuntimeFacts,
21-
} from '../../request-runtime-binding.ts';
226
import {
237
mockDispatch,
248
mockResolveTargetDevice,
@@ -30,43 +14,6 @@ import {
3014
import type { SessionState } from '../../types.ts';
3115
import { handleSessionCommands } from './session-command-harness.ts';
3216

33-
const available = Object.freeze({ available: true } as const);
34-
35-
/** Admits every keyboard operation so the ADR 0014 seam runs on real admission, not a rejection.
36-
* `keyboardDismiss` is overridable so a test can force the invocation itself to reject, proving
37-
* the frame expires before the mutating call runs rather than only after it resolves. */
38-
function keyboardCapableRuntime(
39-
device: DeviceInfo,
40-
overrides?: Readonly<{ keyboardDismiss?: () => Promise<KeyboardDismissResult> }>,
41-
) {
42-
const facts: RuntimeFacts<PlatformRuntimeOperations> = {
43-
device: { ...deviceShape(device), providerMode: 'local' },
44-
operations: keyboardRuntimeOperationFacts({
45-
status: available,
46-
dismiss: available,
47-
enter: available,
48-
}) as RuntimeFacts<PlatformRuntimeOperations>['operations'],
49-
};
50-
const binding = {
51-
device,
52-
owner: localRuntimeOwner(device.platform),
53-
facts,
54-
operations: {
55-
keyboardStatus: async () => ({ visible: false }),
56-
keyboardDismiss:
57-
overrides?.keyboardDismiss ??
58-
(async () => ({ kind: 'ime-probe', dismissed: true, visible: false })),
59-
keyboardEnter: async () => ({}),
60-
},
61-
[Symbol.asyncDispose]: async () => {},
62-
} satisfies DeviceBinding<PlatformRuntimeOperations>;
63-
const inspectFacts: InspectDeviceRuntimeFacts = vi.fn(async () => facts);
64-
const bindDevice = vi.fn(async (_device, use) =>
65-
narrowDeviceBinding(binding, use),
66-
) as unknown as BindDeviceRuntime;
67-
return { inspectFacts, bindDevice };
68-
}
69-
7017
test('appstate on iOS requires active session on selected device', async () => {
7118
const sessionStore = makeSessionStore();
7219
const sessionName = 'default';
@@ -208,101 +155,6 @@ test('appstate fails when iOS session has no tracked app', async () => {
208155
}
209156
});
210157

211-
test('keyboard dismiss crosses the ADR 0014 seam while keyboard status preserves the frame', async () => {
212-
const sessionStore = makeSessionStore();
213-
const sessionName = 'kb';
214-
const device: SessionState['device'] = {
215-
platform: 'apple',
216-
id: 'sim-1',
217-
name: 'iPhone 17 Pro',
218-
kind: 'simulator',
219-
booted: true,
220-
};
221-
mockResolveTargetDevice.mockResolvedValue(device);
222-
mockDispatch.mockResolvedValue({});
223-
const logPath = path.join(os.tmpdir(), 'daemon.log');
224-
const { inspectFacts, bindDevice } = keyboardCapableRuntime(device);
225-
226-
// dismiss mutates the device → frame expires.
227-
sessionStore.set(sessionName, makeSession(sessionName, device));
228-
await handleSessionCommands({
229-
req: {
230-
token: 't',
231-
session: sessionName,
232-
command: 'keyboard',
233-
positionals: ['dismiss'],
234-
flags: {},
235-
},
236-
sessionName,
237-
logPath,
238-
sessionStore,
239-
invoke: noopInvoke,
240-
inspectFacts,
241-
bindDevice,
242-
});
243-
expect(sessionStore.get(sessionName)?.refFrameState).toBe('expired');
244-
245-
// status is a read-only probe → frame preserved (undefined === active).
246-
sessionStore.set(sessionName, makeSession(sessionName, device));
247-
await handleSessionCommands({
248-
req: {
249-
token: 't',
250-
session: sessionName,
251-
command: 'keyboard',
252-
positionals: ['status'],
253-
flags: {},
254-
},
255-
sessionName,
256-
logPath,
257-
sessionStore,
258-
invoke: noopInvoke,
259-
inspectFacts,
260-
bindDevice,
261-
});
262-
expect(sessionStore.get(sessionName)?.refFrameState).toBeUndefined();
263-
});
264-
265-
// #1955 review: `runSessionOrSelectorDispatch` used to expire the frame only after a successful
266-
// `execute`, so a rejecting/timed-out invocation left a stale frame active. ADR 0014 requires
267-
// expiry immediately before the mutating call, with no success-only rollback — prove a rejection
268-
// still lands the expiry.
269-
test('keyboard dismiss expires the frame even when the invocation rejects', async () => {
270-
const sessionStore = makeSessionStore();
271-
const sessionName = 'kb-reject';
272-
const device: SessionState['device'] = {
273-
platform: 'apple',
274-
id: 'sim-2',
275-
name: 'iPhone 17 Pro',
276-
kind: 'simulator',
277-
booted: true,
278-
};
279-
mockResolveTargetDevice.mockResolvedValue(device);
280-
const logPath = path.join(os.tmpdir(), 'daemon.log');
281-
const { inspectFacts, bindDevice } = keyboardCapableRuntime(device, {
282-
keyboardDismiss: () => Promise.reject(new AppError('COMMAND_FAILED', 'runner timed out')),
283-
});
284-
285-
sessionStore.set(sessionName, makeSession(sessionName, device));
286-
await expect(
287-
handleSessionCommands({
288-
req: {
289-
token: 't',
290-
session: sessionName,
291-
command: 'keyboard',
292-
positionals: ['dismiss'],
293-
flags: {},
294-
},
295-
sessionName,
296-
logPath,
297-
sessionStore,
298-
invoke: noopInvoke,
299-
inspectFacts,
300-
bindDevice,
301-
}),
302-
).rejects.toMatchObject({ code: 'COMMAND_FAILED' });
303-
expect(sessionStore.get(sessionName)?.refFrameState).toBe('expired');
304-
});
305-
306158
test('appstate without session on iOS selector returns SESSION_NOT_FOUND', async () => {
307159
const sessionStore = makeSessionStore();
308160
const selectedDevice: SessionState['device'] = {
@@ -386,57 +238,6 @@ test('clipboard requires an active session or explicit device selector', async (
386238
}
387239
});
388240

389-
test('keyboard requires an active session or explicit device selector', async () => {
390-
const sessionStore = makeSessionStore();
391-
const response = await handleSessionCommands({
392-
req: {
393-
token: 't',
394-
session: 'default',
395-
command: 'keyboard',
396-
positionals: ['status'],
397-
flags: {},
398-
},
399-
sessionName: 'default',
400-
logPath: path.join(os.tmpdir(), 'daemon.log'),
401-
sessionStore,
402-
invoke: noopInvoke,
403-
});
404-
405-
expect(response).toBeTruthy();
406-
expect(response?.ok).toBe(false);
407-
if (response && !response.ok) {
408-
expect(response.error.code).toBe('INVALID_ARGS');
409-
expect(response.error.message).toMatch(
410-
/keyboard requires an active session or an explicit device selector/i,
411-
);
412-
}
413-
});
414-
415-
test('keyboard dismiss requires active iOS session for explicit selectors', async () => {
416-
const sessionStore = makeSessionStore();
417-
418-
const response = await handleSessionCommands({
419-
req: {
420-
token: 't',
421-
session: 'default',
422-
command: 'keyboard',
423-
positionals: ['dismiss'],
424-
flags: { platform: 'ios', device: 'iPhone 17 Pro' },
425-
},
426-
sessionName: 'default',
427-
logPath: path.join(os.tmpdir(), 'daemon.log'),
428-
sessionStore,
429-
invoke: noopInvoke,
430-
});
431-
432-
expect(response).toBeTruthy();
433-
expect(response?.ok).toBe(false);
434-
if (response && !response.ok) {
435-
expect(response.error.code).toBe('SESSION_NOT_FOUND');
436-
expect(response.error.message).toMatch(/requires an active session/i);
437-
}
438-
});
439-
440241
test('clipboard rejects unsupported iOS physical devices', async () => {
441242
const sessionStore = makeSessionStore();
442243
const sessionName = 'ios-device-session';

0 commit comments

Comments
 (0)