Skip to content

Commit 0fd2f95

Browse files
committed
refactor: relocate Apple supports()/unsupportedHint() closures onto the plugin (#973)
Phase 3 step b.2. Move the per-command supports() / unsupportedHint() device closures VERBATIM off the command-descriptor facet onto the owning PlatformPlugin's capability.supportsByDefault / unsupportedHintByDefault (perfect-shape §7 / ADR-0009: relocate, never flatten). Bodies are byte-for-byte identical; only their ownership moves to the Apple plugin, the family that owns every discriminating device (macOS-coordinate-pinch, tvOS-no-touch, physical-iOS, two-finger-synthesis). The relocation is faithful because every closure is a no-op (returns true / undefined) on non-Apple devices, so consulting it only for the Apple family leaves admission unchanged across the full device matrix. isCommandSupportedOnDevice and unsupportedHintForDevice now read the closure off getPlugin(device.platform); the command facet carries platform/kind buckets only, and supports/unsupportedHint are removed from the CommandCapability type. Parity gate (byte-for-byte, before deleting the hand sites): independent VERBATIM oracle in capability-plugin-routing-parity.test.ts pins (a) production admission + hint output unchanged across the {platform x command x kind x target} matrix, and (b) the relocated Apple-plugin closures are behaviorally identical to the originals across the device-fixtures sample matrix, with a guard that no non-Apple family grew a gate.
1 parent c0b9c54 commit 0fd2f95

6 files changed

Lines changed: 180 additions & 77 deletions

File tree

‎src/core/__tests__/capability-plugin-routing-parity.test.ts‎

Lines changed: 64 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -29,19 +29,25 @@ import { platformDescriptors } from '../platform-descriptor/registry.ts';
2929
import { getPlugin } from '../platform-plugin/plugin.ts';
3030
import { registerBuiltinPlatformPlugins } from '../platform-plugin/register-builtins.ts';
3131

32-
// Phase 3 step (b) parity gate. Two independent oracles pin that the migration is
32+
// Phase 3 step (b) parity gate. Independent oracles pin that the migration is
3333
// byte-for-byte behaviorless:
3434
// (b.1) the platform -> capability-bucket selection in `isCommandSupportedOnDevice`
3535
// now flows through the PlatformPlugin registry instead of the
3636
// `platformDescriptors` fold. `deriveCapabilityForPlatform(platformDescriptors,
3737
// ...)` is kept here as the BEFORE-derivation oracle (the production fold was
3838
// deleted), so a plugin-vs-descriptor disagreement fails this test.
39-
// (b.2) the per-command `supports()` / `unsupportedHint()` closures stay VERBATIM on
40-
// the command-descriptor facet (they cannot move to the plugin's per-FAMILY
41-
// `capability.supportsByDefault` without flattening their per-command shape —
42-
// perfect-shape §7). Independent verbatim copies below pin that the closures,
43-
// as they flow through `deriveCapabilityMatrix` into admission, are unchanged
44-
// across the full {platform x command x device-kind x target} matrix.
39+
// (b.2) the per-command `supports()` / `unsupportedHint()` device closures were
40+
// RELOCATED VERBATIM off the command-descriptor facet onto the owning
41+
// PlatformPlugin's `capability.supportsByDefault` / `unsupportedHintByDefault`
42+
// (perfect-shape §7: relocate, never flatten). This is faithful because every
43+
// such closure is a no-op (returns `true` / `undefined`) on non-Apple devices,
44+
// so consulting it only for the Apple family — the family that owns the
45+
// relocated map — leaves admission unchanged. The independent VERBATIM copies
46+
// below are the oracle: they pin (a) that production admission (`isCommand
47+
// SupportedOnDevice`) and hint output (`unsupportedHintForDevice`) are unchanged
48+
// across the full {platform x command x device-kind x target} matrix, and (b)
49+
// that the closures now living on the Apple plugin are byte-for-byte behaviorally
50+
// identical to the originals across the sample-device matrix.
4551

4652
registerBuiltinPlatformPlugins();
4753

@@ -211,17 +217,58 @@ test('(b.2) unsupportedHint closures are verbatim across the full device matrix'
211217
}
212218
});
213219

214-
test('(b.2) every command carrying a supports closure is covered by the reference map', () => {
215-
// Guards the SUPPORTS_REF/HINT_REF oracle against silently missing a closure: a
216-
// command whose admission depends on a supports gate must appear in SUPPORTS_REF,
217-
// and every hint-bearing command must appear in HINT_REF.
218-
for (const command of listCapabilityCommands()) {
219-
const capability = BASE_COMMAND_CAPABILITY_MATRIX[command];
220-
if (capability?.supports) {
221-
assert.ok(SUPPORTS_REF[command], `${command} supports closure present in reference map`);
220+
test('(b.2) the Apple plugin carries exactly the relocated supports/hint closures', () => {
221+
// The relocation target: `supports()` / `unsupportedHint()` now live on the Apple
222+
// plugin (the family that owns every discriminating device). Pin the RELOCATED maps'
223+
// key sets against the independent verbatim reference so no closure was silently
224+
// dropped or added while moving off the command facet.
225+
const appleCapability = getPlugin('ios').capability;
226+
assert.deepEqual(
227+
Object.keys(appleCapability.supportsByDefault ?? {}).sort(),
228+
Object.keys(SUPPORTS_REF).sort(),
229+
'supportsByDefault key set equals the verbatim reference',
230+
);
231+
assert.deepEqual(
232+
Object.keys(appleCapability.unsupportedHintByDefault ?? {}).sort(),
233+
Object.keys(HINT_REF).sort(),
234+
'unsupportedHintByDefault key set equals the verbatim reference',
235+
);
236+
// ios and macos are the SAME Apple plugin instance, so both leaves read one map.
237+
assert.equal(getPlugin('ios').capability, getPlugin('macos').capability);
238+
});
239+
240+
test('(b.2) the relocated Apple closures are byte-for-byte the verbatim originals', () => {
241+
// Closure-equivalence: for every command x sample-device, the closure now living on
242+
// the Apple plugin returns an identical boolean / identical hint STRING to the
243+
// independent verbatim copy of the original command-facet closure.
244+
const appleCapability = getPlugin('ios').capability;
245+
for (const [command, reference] of Object.entries(SUPPORTS_REF)) {
246+
const relocated = appleCapability.supportsByDefault?.[command];
247+
assert.ok(relocated, `${command} supports closure present on the Apple plugin`);
248+
for (const device of SAMPLE_DEVICES) {
249+
assert.equal(relocated(device), reference(device), `${command} supports on ${device.id}`);
222250
}
223-
if (capability?.unsupportedHint) {
224-
assert.ok(HINT_REF[command], `${command} unsupportedHint closure present in reference map`);
251+
}
252+
for (const [command, reference] of Object.entries(HINT_REF)) {
253+
const relocated = appleCapability.unsupportedHintByDefault?.[command];
254+
assert.ok(relocated, `${command} hint closure present on the Apple plugin`);
255+
for (const device of SAMPLE_DEVICES) {
256+
assert.equal(relocated(device), reference(device), `${command} hint on ${device.id}`);
225257
}
226258
}
227259
});
260+
261+
test('(b.2) no non-Apple family carries a relocated supports/hint closure', () => {
262+
// The relocation is faithful only because the closures are no-ops off the Apple
263+
// family; guard that no other plugin accidentally grew a per-command gate (which
264+
// would change admission for android/linux/web).
265+
for (const platform of ['android', 'linux', 'web'] as const) {
266+
const capability = getPlugin(platform).capability;
267+
assert.equal(capability.supportsByDefault, undefined, `${platform} has no supportsByDefault`);
268+
assert.equal(
269+
capability.unsupportedHintByDefault,
270+
undefined,
271+
`${platform} has no unsupportedHintByDefault`,
272+
);
273+
}
274+
});

‎src/core/capabilities.ts‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,6 @@ export type CommandCapability = {
2424
android?: KindMatrix;
2525
linux?: KindMatrix;
2626
web?: KindMatrix;
27-
supports?: (device: DeviceInfo) => boolean;
28-
/** Optional actionable hint surfaced when this command is rejected at admission for `device`. */
29-
unsupportedHint?: (device: DeviceInfo) => string | undefined;
3027
};
3128

3229
const WEB_DEVICE: KindMatrix = { device: true };
@@ -52,9 +49,12 @@ const WEB_SUPPORTED_COMMANDS = new Set<string>([
5249
]);
5350
// Built from the additive command-descriptor registry (ADR-0008, Phase 1 step 3).
5451
// The hand-authored literal was deleted after #906 proved deriveCapabilityMatrix is
55-
// byte-equal to it (platform/kind buckets plus the supports/unsupportedHint closures,
56-
// across the sample-device matrix). The registry only type-imports CommandCapability
57-
// from here, so this value-level dependency does not form a runtime cycle.
52+
// byte-equal to it (platform/kind buckets). The per-command `supports()` /
53+
// `unsupportedHint()` device closures no longer live here — they were relocated onto
54+
// the owning PlatformPlugin's `capability.supportsByDefault` / `unsupportedHintByDefault`
55+
// in Phase 3 step b.2 (see `isCommandSupportedOnDevice` below). The registry only
56+
// type-imports CommandCapability from here, so this value-level dependency does not
57+
// form a runtime cycle.
5858
export const BASE_COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> =
5959
deriveCapabilityMatrix(commandDescriptors);
6060

@@ -95,13 +95,22 @@ export function isCommandSupportedOnDevice(command: string, device: DeviceInfo):
9595
if (!plugin) return false;
9696
const byPlatform = capability[plugin.capability.bucket];
9797
if (!byPlatform) return false;
98-
if (capability.supports && !capability.supports(device)) return false;
98+
// The per-command `supports()` gate now flows through the owning PlatformPlugin
99+
// (ADR-0009, Phase 3 step b.2): the family that owns `device.platform` carries the
100+
// `supports()` closure RELOCATED VERBATIM in `capability.supportsByDefault`, keyed by
101+
// command. A family with no entry for `command` admits it unchanged — proven equal to
102+
// the former command-facet closure across the device matrix by
103+
// `__tests__/capability-plugin-routing-parity.test.ts`.
104+
const supportsByDefault = plugin.capability.supportsByDefault?.[command];
105+
if (supportsByDefault && !supportsByDefault(device)) return false;
99106
const kind = (device.kind ?? 'unknown') as keyof KindMatrix;
100107
return byPlatform[kind] === true;
101108
}
102109

103110
export function unsupportedHintForDevice(command: string, device: DeviceInfo): string | undefined {
104-
return COMMAND_CAPABILITY_MATRIX[command]?.unsupportedHint?.(device);
111+
// Counterpart of the `supports()` relocation (Phase 3 step b.2): the hint closure is
112+
// owned by the family that owns `device.platform`, keyed by command.
113+
return tryGetPlugin(device.platform)?.capability.unsupportedHintByDefault?.[command]?.(device);
105114
}
106115

107116
export function listCapabilityCommands(): string[] {

‎src/core/command-descriptor/__tests__/parity.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -116,10 +116,10 @@ test('capability matrix holds its admission invariants', () => {
116116
const hasPlatformBucket = Boolean(
117117
capability.apple || capability.android || capability.linux || capability.web,
118118
);
119-
assert.ok(
120-
hasPlatformBucket || typeof capability.supports === 'function',
121-
`${command} has a platform bucket or a supports predicate`,
122-
);
119+
// Every capability entry is now selectable purely by its platform buckets: the
120+
// per-command `supports()` gate was relocated onto the owning PlatformPlugin
121+
// (`capability.supportsByDefault`) in Phase 3 step b.2, so it no longer lives here.
122+
assert.ok(hasPlatformBucket, `${command} has a platform bucket`);
123123
}
124124

125125
const covered = new Set(Object.keys(BASE_COMMAND_CAPABILITY_MATRIX));

‎src/core/command-descriptor/registry.ts‎

Lines changed: 7 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ import {
55
} from '../../command-catalog.ts';
66
import type { CommandCapability } from '../capabilities.ts';
77
import type { DaemonRequest } from '../../daemon/types.ts';
8-
import { isTvOsDevice, type DeviceInfo } from '../../kernel/device.ts';
98
import type { CommandDescriptor } from './types.ts';
109

1110
// ---------------------------------------------------------------------------
@@ -34,30 +33,16 @@ const isShardedTestRequest = (req: DaemonRequest): boolean =>
3433
(typeof req.flags?.shardAll === 'number' || typeof req.flags?.shardSplit === 'number');
3534

3635
// ---------------------------------------------------------------------------
37-
// Capability predicates / matrices — copied VERBATIM from
36+
// Capability matrices — platform/kind buckets, copied VERBATIM from
3837
// src/core/capabilities.ts (BASE_COMMAND_CAPABILITY_MATRIX).
38+
//
39+
// The per-command `supports()` / `unsupportedHint()` device closures that used to
40+
// live here were RELOCATED VERBATIM onto the owning PlatformPlugin's
41+
// `capability.supportsByDefault` / `unsupportedHintByDefault` in Phase 3 step b.2
42+
// (src/core/platform-plugin/register-builtins.ts). The capability facet now carries
43+
// platform/kind buckets only; admission reads the closure off the plugin.
3944
// ---------------------------------------------------------------------------
4045

41-
const isNotMacOs = (device: DeviceInfo): boolean => device.platform !== 'macos';
42-
const isMacOsOrAppleSimulator = (device: DeviceInfo): boolean =>
43-
device.platform === 'macos' || device.kind === 'simulator';
44-
const isIosMobileSimulator = (device: DeviceInfo): boolean =>
45-
device.platform === 'ios' && device.kind === 'simulator' && !isTvOsDevice(device);
46-
const supportsSynthesisGesture = (device: DeviceInfo): boolean =>
47-
device.platform === 'android' || isIosMobileSimulator(device);
48-
const supportsAndroidOrIosNonTv = (device: DeviceInfo): boolean =>
49-
device.platform === 'android' || (device.platform === 'ios' && !isTvOsDevice(device));
50-
51-
const synthesisGestureUnsupportedHint = (device: DeviceInfo): string | undefined => {
52-
if (device.platform === 'macos')
53-
return 'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.';
54-
if (isTvOsDevice(device))
55-
return 'tvOS has no touch input — this gesture is supported on Android and the iOS simulator only.';
56-
if (device.platform === 'ios' && device.kind === 'device')
57-
return 'Two-finger gesture synthesis is iOS-simulator only — not available on physical iOS devices.';
58-
return undefined;
59-
};
60-
6146
const APPLE_SIM_AND_DEVICE = { simulator: true, device: true };
6247
const ANDROID_ALL = { emulator: true, device: true, unknown: true };
6348
const LINUX_DEVICE = { device: true };
@@ -78,7 +63,6 @@ const APP_INSTALL_CAPABILITY = {
7863
apple: APPLE_SIM_AND_DEVICE,
7964
android: ANDROID_ALL,
8065
linux: LINUX_NONE,
81-
supports: isNotMacOs,
8266
} satisfies CommandCapability;
8367

8468
// ---------------------------------------------------------------------------
@@ -142,7 +126,6 @@ const RAW_COMMAND_DESCRIPTORS = [
142126
apple: APPLE_SIM_AND_DEVICE,
143127
android: ANDROID_ALL,
144128
linux: LINUX_NONE,
145-
supports: isNotMacOs,
146129
},
147130
batchable: true,
148131
},
@@ -209,11 +192,6 @@ const RAW_COMMAND_DESCRIPTORS = [
209192
apple: APPLE_SIM_AND_DEVICE,
210193
android: ANDROID_ALL,
211194
linux: LINUX_DEVICE,
212-
supports: (device) =>
213-
device.platform === 'android' ||
214-
device.platform === 'linux' ||
215-
device.platform === 'macos' ||
216-
device.kind === 'simulator',
217195
},
218196
batchable: true,
219197
},
@@ -224,7 +202,6 @@ const RAW_COMMAND_DESCRIPTORS = [
224202
apple: APPLE_SIM_AND_DEVICE,
225203
android: ANDROID_ALL,
226204
linux: LINUX_NONE,
227-
supports: supportsAndroidOrIosNonTv,
228205
},
229206
batchable: true,
230207
},
@@ -257,7 +234,6 @@ const RAW_COMMAND_DESCRIPTORS = [
257234
apple: { simulator: true },
258235
android: ANDROID_ALL,
259236
linux: LINUX_NONE,
260-
supports: isNotMacOs,
261237
},
262238
batchable: true,
263239
},
@@ -316,7 +292,6 @@ const RAW_COMMAND_DESCRIPTORS = [
316292
apple: APPLE_SIM_AND_DEVICE,
317293
android: ANDROID_ALL,
318294
linux: LINUX_NONE,
319-
supports: (device) => device.platform === 'android' || isMacOsOrAppleSimulator(device),
320295
},
321296
batchable: true,
322297
},
@@ -327,8 +302,6 @@ const RAW_COMMAND_DESCRIPTORS = [
327302
apple: APPLE_SIM_AND_DEVICE,
328303
android: ANDROID_ALL,
329304
linux: LINUX_NONE,
330-
supports: (device) =>
331-
device.platform === 'android' || device.platform === 'macos' || device.kind === 'simulator',
332305
},
333306
batchable: true,
334307
},
@@ -426,7 +399,6 @@ const RAW_COMMAND_DESCRIPTORS = [
426399
apple: APPLE_SIM_AND_DEVICE,
427400
android: ANDROID_ALL,
428401
linux: LINUX_DEVICE,
429-
supports: isNotMacOs,
430402
},
431403
batchable: true,
432404
},
@@ -437,7 +409,6 @@ const RAW_COMMAND_DESCRIPTORS = [
437409
apple: APPLE_SIM_AND_DEVICE,
438410
android: ANDROID_ALL,
439411
linux: LINUX_NONE,
440-
supports: supportsAndroidOrIosNonTv,
441412
},
442413
batchable: true,
443414
},
@@ -460,8 +431,6 @@ const RAW_COMMAND_DESCRIPTORS = [
460431
apple: APPLE_SIM_AND_DEVICE,
461432
android: ANDROID_ALL,
462433
linux: LINUX_NONE,
463-
supports: supportsSynthesisGesture,
464-
unsupportedHint: synthesisGestureUnsupportedHint,
465434
},
466435
batchable: false,
467436
},
@@ -502,8 +471,6 @@ const RAW_COMMAND_DESCRIPTORS = [
502471
apple: APPLE_SIM_AND_DEVICE,
503472
android: ANDROID_ALL,
504473
linux: LINUX_NONE,
505-
supports: supportsSynthesisGesture,
506-
unsupportedHint: synthesisGestureUnsupportedHint,
507474
},
508475
batchable: false,
509476
},
@@ -514,8 +481,6 @@ const RAW_COMMAND_DESCRIPTORS = [
514481
apple: APPLE_SIM_AND_DEVICE,
515482
android: ANDROID_ALL,
516483
linux: LINUX_NONE,
517-
supports: supportsSynthesisGesture,
518-
unsupportedHint: synthesisGestureUnsupportedHint,
519484
},
520485
batchable: false,
521486
},
@@ -527,7 +492,6 @@ const RAW_COMMAND_DESCRIPTORS = [
527492
apple: APPLE_SIM_AND_DEVICE,
528493
android: ANDROID_ALL,
529494
linux: LINUX_NONE,
530-
supports: isNotMacOs,
531495
},
532496
batchable: true,
533497
},

‎src/core/platform-plugin/plugin.ts‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,25 @@ export type PlatformPlugin = {
4343
/**
4444
* The capability facet. `bucket` is the {@link CapabilityBucket} this family
4545
* reads from a `CommandCapability` (parity-checked against the existing
46-
* `platformDescriptors` registry). `supportsByDefault` is reserved for the
47-
* step-(b) relocation of the `supports()` device closures — left undefined
48-
* here so those closures stay verbatim in `capabilities.ts` for now.
46+
* `platformDescriptors` registry).
47+
*
48+
* `supportsByDefault` / `unsupportedHintByDefault` carry the per-command
49+
* `supports()` / `unsupportedHint()` device closures RELOCATED VERBATIM off the
50+
* command-descriptor facet (ADR-0009 / perfect-shape §7 step b.2: relocate, never
51+
* flatten). They are keyed by command name and owned by the family that owns the
52+
* device's platform; `isCommandSupportedOnDevice` / `unsupportedHintForDevice`
53+
* consult the map for `getPlugin(device.platform)`, so a family with no entry for a
54+
* command (the key is absent) admits it unchanged. Only the Apple family carries
55+
* entries today — every relocated closure is a no-op (returns `true` / `undefined`)
56+
* on non-Apple devices, proven byte-for-byte by the parity gate before the
57+
* command-facet closures were deleted.
4958
*/
5059
readonly capability: {
5160
readonly bucket: CapabilityBucket;
52-
supportsByDefault?(device: DeviceInfo): boolean;
61+
readonly supportsByDefault?: Readonly<Record<string, (device: DeviceInfo) => boolean>>;
62+
readonly unsupportedHintByDefault?: Readonly<
63+
Record<string, (device: DeviceInfo) => string | undefined>
64+
>;
5365
};
5466
/**
5567
* The daemon app-log facet (issue #974). `resolveBackend` wraps the platform

0 commit comments

Comments
 (0)