Skip to content

Commit 4648051

Browse files
authored
feat: command-descriptor registry (additive, parity-tested) — Phase 1 step 1 (#906)
Introduce a single dormant CommandDescriptor registry as the strangler-fig spine for ADR-0008. Per command it carries the daemon route + request-policy traits (incl. closure traits), an optional capability entry, and batchable/mcpExposed flags — copied verbatim from today's hand tables. Pure derive folds reconstruct DAEMON_COMMAND_DESCRIPTORS, the capability matrix, and the structured-batch names; parity tests prove each derivation byte-equal to the live hand table. Nothing reads the registry yet. Purely additive: no consumers changed, nothing deleted, no import inversion. The only edits outside the new directory expose three existing tables (DAEMON_COMMAND_DESCRIPTORS, DaemonCommandDescriptor, BASE_COMMAND_CAPABILITY_MATRIX) so the parity tests can read them.
1 parent 29e19b8 commit 4648051

6 files changed

Lines changed: 799 additions & 3 deletions

File tree

‎src/core/capabilities.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ const APP_INSTALL_CAPABILITY = {
7979
supports: isNotMacOs,
8080
} as const satisfies CommandCapability;
8181

82-
const BASE_COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
82+
export const BASE_COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
8383
// Apple simulator-only.
8484
alert: {
8585
// macOS desktop targets report kind=device, so this stays enabled here and the
Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { STRUCTURED_BATCH_COMMAND_NAMES } from '../../../batch-policy.ts';
4+
import { PUBLIC_COMMANDS } from '../../../command-catalog.ts';
5+
import { BASE_COMMAND_CAPABILITY_MATRIX, type CommandCapability } from '../../capabilities.ts';
6+
import {
7+
DAEMON_COMMAND_DESCRIPTORS,
8+
type DaemonCommandDescriptor,
9+
} from '../../../daemon/daemon-command-registry.ts';
10+
import type { DaemonRequest } from '../../../daemon/types.ts';
11+
import type { DeviceInfo } from '../../../utils/device.ts';
12+
import {
13+
deriveCapabilityMatrix,
14+
deriveDaemonCommandDescriptors,
15+
deriveStructuredBatchCommandNames,
16+
} from '../derive.ts';
17+
import { commandDescriptors } from '../registry.ts';
18+
19+
// Function-valued traits cannot be deep-equaled across re-authored closures, so
20+
// (mirroring daemon-command-registry.test.ts) they are compared by presence and
21+
// by behavior on a representative sample, while every other field is deepEqual'd.
22+
const DAEMON_FUNCTION_TRAITS = [
23+
'allowSessionlessDefaultDevice',
24+
'skipSessionlessProviderDevice',
25+
] as const;
26+
const CAPABILITY_FUNCTION_TRAITS = ['supports', 'unsupportedHint'] as const;
27+
28+
function stripFunctions<T extends Record<string, unknown>>(value: T): Partial<T> {
29+
const result: Record<string, unknown> = {};
30+
for (const [key, entry] of Object.entries(value)) {
31+
if (typeof entry !== 'function') result[key] = entry;
32+
}
33+
return result as Partial<T>;
34+
}
35+
36+
function makeRequest(command: string, positionals: string[] = []): DaemonRequest {
37+
return { command, token: 'parity-token', session: 'parity-session', positionals, flags: {} };
38+
}
39+
40+
// Sample requests that exercise both closure traits' branches for any command.
41+
function sampleRequests(command: string): DaemonRequest[] {
42+
return [
43+
makeRequest(command),
44+
makeRequest(command, ['start']),
45+
makeRequest(command, ['stop']),
46+
makeRequest(command, ['START']),
47+
{ ...makeRequest(command), flags: { shardAll: 2 } },
48+
{ ...makeRequest(command), flags: { shardSplit: 3 } },
49+
{ ...makeRequest(PUBLIC_COMMANDS.test), flags: { shardAll: 2 } },
50+
{ ...makeRequest(PUBLIC_COMMANDS.test), flags: { shardSplit: 1 } },
51+
];
52+
}
53+
54+
function device(partial: Partial<DeviceInfo> & Pick<DeviceInfo, 'platform' | 'kind'>): DeviceInfo {
55+
return { id: 'parity-id', name: 'parity-device', ...partial };
56+
}
57+
58+
const SAMPLE_DEVICES: DeviceInfo[] = [
59+
device({ platform: 'ios', kind: 'simulator' }),
60+
device({ platform: 'ios', kind: 'simulator', target: 'tv' }),
61+
device({ platform: 'ios', kind: 'device' }),
62+
device({ platform: 'ios', kind: 'device', target: 'tv' }),
63+
device({ platform: 'macos', kind: 'device' }),
64+
device({ platform: 'macos', kind: 'simulator' }),
65+
device({ platform: 'android', kind: 'emulator' }),
66+
device({ platform: 'android', kind: 'device' }),
67+
device({ platform: 'android', kind: 'simulator' }),
68+
device({ platform: 'linux', kind: 'device' }),
69+
device({ platform: 'web', kind: 'device' }),
70+
];
71+
72+
test('derived daemon descriptors match the hand table (non-function traits, in order)', () => {
73+
const derived = deriveDaemonCommandDescriptors(commandDescriptors);
74+
assert.equal(derived.length, DAEMON_COMMAND_DESCRIPTORS.length, 'descriptor count');
75+
for (let index = 0; index < derived.length; index++) {
76+
const live = DAEMON_COMMAND_DESCRIPTORS[index] as DaemonCommandDescriptor;
77+
const next = derived[index];
78+
assert.ok(next, `index ${index} derived descriptor present`);
79+
assert.equal(next.command, live.command, `index ${index} command order`);
80+
assert.deepEqual(
81+
stripFunctions(next),
82+
stripFunctions(live),
83+
`${live.command} non-function daemon traits`,
84+
);
85+
}
86+
});
87+
88+
test('derived daemon descriptors preserve closure traits by presence and behavior', () => {
89+
const liveByCommand = new Map(
90+
DAEMON_COMMAND_DESCRIPTORS.map((d) => [d.command, d as DaemonCommandDescriptor]),
91+
);
92+
for (const derived of deriveDaemonCommandDescriptors(commandDescriptors)) {
93+
const live = liveByCommand.get(derived.command);
94+
assert.ok(live, `${derived.command} present in hand table`);
95+
for (const trait of DAEMON_FUNCTION_TRAITS) {
96+
const derivedFn = derived[trait] as ((req: DaemonRequest) => boolean) | undefined;
97+
const liveFn = live[trait] as ((req: DaemonRequest) => boolean) | undefined;
98+
assert.equal(typeof derivedFn, typeof liveFn, `${derived.command} ${trait} presence`);
99+
if (typeof liveFn === 'function' && typeof derivedFn === 'function') {
100+
for (const request of sampleRequests(derived.command)) {
101+
assert.equal(derivedFn(request), liveFn(request), `${derived.command} ${trait} behavior`);
102+
}
103+
}
104+
}
105+
}
106+
});
107+
108+
test('derived capability matrix matches the hand table (non-function fields)', () => {
109+
const derived = deriveCapabilityMatrix(commandDescriptors);
110+
assert.deepEqual(
111+
Object.keys(derived).sort(),
112+
Object.keys(BASE_COMMAND_CAPABILITY_MATRIX).sort(),
113+
'capability command coverage',
114+
);
115+
for (const [command, live] of Object.entries(BASE_COMMAND_CAPABILITY_MATRIX)) {
116+
assert.deepEqual(
117+
stripFunctions(derived[command] as CommandCapability),
118+
stripFunctions(live),
119+
`${command} non-function capability fields`,
120+
);
121+
}
122+
});
123+
124+
test('derived capability matrix preserves supports/unsupportedHint by presence and behavior', () => {
125+
const derived = deriveCapabilityMatrix(commandDescriptors);
126+
for (const [command, live] of Object.entries(BASE_COMMAND_CAPABILITY_MATRIX)) {
127+
const derivedCapability = derived[command] as CommandCapability;
128+
for (const trait of CAPABILITY_FUNCTION_TRAITS) {
129+
const derivedFn = derivedCapability[trait] as ((device: DeviceInfo) => unknown) | undefined;
130+
const liveFn = live[trait] as ((device: DeviceInfo) => unknown) | undefined;
131+
assert.equal(typeof derivedFn, typeof liveFn, `${command} ${trait} presence`);
132+
if (typeof liveFn === 'function' && typeof derivedFn === 'function') {
133+
for (const sample of SAMPLE_DEVICES) {
134+
assert.equal(
135+
derivedFn(sample),
136+
liveFn(sample),
137+
`${command} ${trait} on ${sample.platform}/${sample.kind}/${sample.target ?? 'mobile'}`,
138+
);
139+
}
140+
}
141+
}
142+
}
143+
});
144+
145+
test('derived structured-batch command names match the hand table (membership)', () => {
146+
// Membership, not order: STRUCTURED_BATCH_COMMAND_NAMES and
147+
// DAEMON_COMMAND_DESCRIPTORS are independently hand-ordered, so a single
148+
// registry table cannot reproduce both array orders. The batchable flags are
149+
// proven byte-equal as a set; ordering is cosmetic (the consumer dedupes into
150+
// a Set) and is deferred to a later slice.
151+
const derived = deriveStructuredBatchCommandNames(commandDescriptors);
152+
assert.equal(new Set(derived).size, derived.length, 'no duplicate batchable names');
153+
assert.deepEqual(
154+
[...derived].sort(),
155+
[...STRUCTURED_BATCH_COMMAND_NAMES].sort(),
156+
'structured-batch membership',
157+
);
158+
});
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import type { CommandCapability } from '../capabilities.ts';
2+
import type { DaemonCommandDescriptor } from '../../daemon/daemon-command-registry.ts';
3+
import type { CommandDescriptor } from './types.ts';
4+
5+
/**
6+
* Pure folds that reconstruct today's hand-authored tables from the additive
7+
* {@link CommandDescriptor} registry. These exist so the parity tests can prove
8+
* the registry is byte-equal to the live tables; no production code reads them
9+
* yet (ADR-0008, Phase 1 step 1).
10+
*/
11+
12+
/** Reconstructs the DAEMON_COMMAND_DESCRIPTORS array (same order, same shape). */
13+
export function deriveDaemonCommandDescriptors(
14+
descriptors: readonly CommandDescriptor[],
15+
): DaemonCommandDescriptor[] {
16+
const result: DaemonCommandDescriptor[] = [];
17+
for (const descriptor of descriptors) {
18+
if (!descriptor.daemon) continue;
19+
result.push({ command: descriptor.name, ...descriptor.daemon });
20+
}
21+
return result;
22+
}
23+
24+
/** Reconstructs the BASE_COMMAND_CAPABILITY_MATRIX record. */
25+
export function deriveCapabilityMatrix(
26+
descriptors: readonly CommandDescriptor[],
27+
): Record<string, CommandCapability> {
28+
const result: Record<string, CommandCapability> = {};
29+
for (const descriptor of descriptors) {
30+
if (descriptor.capability) result[descriptor.name] = descriptor.capability;
31+
}
32+
return result;
33+
}
34+
35+
/** Reconstructs the STRUCTURED_BATCH_COMMAND_NAMES membership. */
36+
export function deriveStructuredBatchCommandNames(
37+
descriptors: readonly CommandDescriptor[],
38+
): string[] {
39+
return descriptors
40+
.filter((descriptor) => descriptor.batchable)
41+
.map((descriptor) => descriptor.name);
42+
}

0 commit comments

Comments
 (0)