Skip to content

Commit 902be1f

Browse files
committed
fix(registry): react-devtools executes delegated platform behavior
`react-devtools start` on a Limrun Android instance dispatches internal `runtime port-reverse`, which reaches a provider device runtime, so ADR 0019 §6 `none` is false for it. Reclassify as `legacy` and add the derived coherence gate that catches delegated platform execution: if a CLI route for command R dispatches command D, R may declare `none` only when D is `none`. Part of #1739 (wave 0)
1 parent 9428496 commit 902be1f

3 files changed

Lines changed: 235 additions & 12 deletions

File tree

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
import fs from 'node:fs';
2+
import { fileURLToPath } from 'node:url';
3+
import { parseSync } from 'oxc-parser';
4+
import { describe, expect, test } from 'vitest';
5+
import { INTERNAL_COMMANDS, PUBLIC_COMMANDS } from '../../../command-catalog.ts';
6+
import { commandDescriptors } from '../registry.ts';
7+
8+
/**
9+
* ADR 0019 §6 coherence gate for delegated platform execution.
10+
*
11+
* The registry entry gate inspects one descriptor at a time, so it cannot see a
12+
* command whose own module holds no platform code while its CLI route injects a
13+
* callback that dispatches a platform-executing command. Mode dominance closes
14+
* that: if the CLI route for command R dispatches command D, R may declare `none`
15+
* only when D is `none` too.
16+
*
17+
* Scope is `src/cli.ts`, the composition root where injected callbacks are built.
18+
* The scan is total within it — a dispatch no route can claim fails the gate.
19+
*/
20+
21+
type AstNode = { type: string } & Record<string, unknown>;
22+
23+
const CLI_COMPOSITION_ROOT = fileURLToPath(new URL('../../../cli.ts', import.meta.url));
24+
25+
const COMMAND_CATALOGS: Record<string, Record<string, string>> = {
26+
INTERNAL_COMMANDS,
27+
PUBLIC_COMMANDS,
28+
};
29+
30+
const COMMAND_NAMES = new Set<string>(commandDescriptors.map(({ name }) => name));
31+
32+
type PlatformExecutionKindOf = (command: string) => string | undefined;
33+
34+
const registryKind: PlatformExecutionKindOf = (command) =>
35+
commandDescriptors.find(({ name }) => name === command)?.platformExecution.kind;
36+
37+
type RouteDispatch = Readonly<{ route: string; dispatched: string }>;
38+
39+
type RouteScan = Readonly<{
40+
dispatches: readonly RouteDispatch[];
41+
/** Dispatch literals no `command === '<name>'` route could claim. */
42+
unattributed: readonly string[];
43+
}>;
44+
45+
function isAstNode(value: unknown): value is AstNode {
46+
return typeof value === 'object' && value !== null && typeof (value as AstNode).type === 'string';
47+
}
48+
49+
function walk(root: unknown, visit: (node: AstNode) => void): void {
50+
if (Array.isArray(root)) {
51+
for (const child of root) walk(child, visit);
52+
return;
53+
}
54+
if (!isAstNode(root)) return;
55+
visit(root);
56+
for (const value of Object.values(root)) walk(value, visit);
57+
}
58+
59+
function identifierName(node: unknown): string | undefined {
60+
return isAstNode(node) && node.type === 'Identifier' ? String(node['name']) : undefined;
61+
}
62+
63+
function stringLiteral(node: unknown): string | undefined {
64+
return isAstNode(node) && node.type === 'Literal' && typeof node['value'] === 'string'
65+
? node['value']
66+
: undefined;
67+
}
68+
69+
function knownCommand(name: string | undefined): string | undefined {
70+
return name !== undefined && COMMAND_NAMES.has(name) ? name : undefined;
71+
}
72+
73+
/** `command === 'react-devtools'`, either operand order, names a routed command. */
74+
function routedCommandOf(test: unknown): string | undefined {
75+
if (!isAstNode(test) || test.type !== 'BinaryExpression' || test['operator'] !== '===') {
76+
return undefined;
77+
}
78+
const operands = [
79+
[test['left'], test['right']],
80+
[test['right'], test['left']],
81+
] as const;
82+
for (const [subject, literal] of operands) {
83+
if (identifierName(subject) !== 'command') continue;
84+
const routed = knownCommand(stringLiteral(literal));
85+
if (routed !== undefined) return routed;
86+
}
87+
return undefined;
88+
}
89+
90+
/** `command: 'x'`, `command: INTERNAL_COMMANDS.x`, `command: PUBLIC_COMMANDS.x`. */
91+
function dispatchedCommandOf(node: AstNode): string | undefined {
92+
if (node.type !== 'Property' || node['computed'] === true) return undefined;
93+
if (identifierName(node['key']) !== 'command') return undefined;
94+
return dispatchTargetOf(node['value']);
95+
}
96+
97+
function dispatchTargetOf(value: unknown): string | undefined {
98+
const literal = stringLiteral(value);
99+
if (literal !== undefined) return knownCommand(literal);
100+
if (!isAstNode(value) || value.type !== 'MemberExpression' || value['computed'] === true) {
101+
return undefined;
102+
}
103+
const catalog = identifierName(value['object']);
104+
const key = identifierName(value['property']);
105+
return catalog === undefined || key === undefined ? undefined : COMMAND_CATALOGS[catalog]?.[key];
106+
}
107+
108+
function localFunctionsByName(program: unknown): Map<string, AstNode> {
109+
const functions = new Map<string, AstNode>();
110+
walk(program, (node) => {
111+
if (node.type !== 'FunctionDeclaration') return;
112+
const name = identifierName(node['id']);
113+
if (name !== undefined) functions.set(name, node);
114+
});
115+
return functions;
116+
}
117+
118+
/** Dispatch literals reachable from `scope`, following calls to same-module functions. */
119+
function reachableDispatches(
120+
scope: unknown,
121+
functions: ReadonlyMap<string, AstNode>,
122+
visited: Set<string>,
123+
): Set<string> {
124+
const found = new Set<string>();
125+
const calls: string[] = [];
126+
walk(scope, (node) => {
127+
const dispatched = dispatchedCommandOf(node);
128+
if (dispatched !== undefined) found.add(dispatched);
129+
if (node.type !== 'CallExpression') return;
130+
const callee = identifierName(node['callee']);
131+
if (callee !== undefined && functions.has(callee)) calls.push(callee);
132+
});
133+
for (const name of calls) {
134+
if (visited.has(name)) continue;
135+
visited.add(name);
136+
for (const dispatched of reachableDispatches(functions.get(name), functions, visited)) {
137+
found.add(dispatched);
138+
}
139+
}
140+
return found;
141+
}
142+
143+
function scanCliRouteDispatches(sourceText: string): RouteScan {
144+
const program = parseSync('cli.ts', sourceText).program;
145+
const functions = localFunctionsByName(program);
146+
const dispatches: RouteDispatch[] = [];
147+
const attributed = new Set<string>();
148+
149+
walk(program, (node) => {
150+
if (node.type !== 'IfStatement') return;
151+
const route = routedCommandOf(node['test']);
152+
if (route === undefined) return;
153+
for (const dispatched of reachableDispatches(node['consequent'], functions, new Set())) {
154+
dispatches.push({ route, dispatched });
155+
attributed.add(dispatched);
156+
}
157+
});
158+
159+
const all = new Set<string>();
160+
walk(program, (node) => {
161+
const dispatched = dispatchedCommandOf(node);
162+
if (dispatched !== undefined) all.add(dispatched);
163+
});
164+
165+
return {
166+
dispatches,
167+
unattributed: [...all].filter((command) => !attributed.has(command)).sort(),
168+
};
169+
}
170+
171+
function dominanceFailures(scan: RouteScan, kindOf: PlatformExecutionKindOf): string[] {
172+
return scan.dispatches
173+
.filter(({ route, dispatched }) => kindOf(route) === 'none' && kindOf(dispatched) !== 'none')
174+
.map(
175+
({ route, dispatched }) =>
176+
`${route} declares platformExecution none but its CLI route dispatches ${dispatched} (${String(kindOf(dispatched))})`,
177+
)
178+
.sort();
179+
}
180+
181+
function scanCompositionRoot(): RouteScan {
182+
return scanCliRouteDispatches(fs.readFileSync(CLI_COMPOSITION_ROOT, 'utf8'));
183+
}
184+
185+
describe('platform-execution coherence across CLI route delegation', () => {
186+
test('no none command dispatches a platform-executing command', () => {
187+
expect(dominanceFailures(scanCompositionRoot(), registryKind)).toEqual([]);
188+
});
189+
190+
test('every CLI daemon dispatch is attributable to a routed command', () => {
191+
expect(scanCompositionRoot().unattributed).toEqual([]);
192+
});
193+
194+
test('the composition root still carries the react-devtools runtime delegation', () => {
195+
expect(scanCompositionRoot().dispatches).toContainEqual({
196+
route: 'react-devtools',
197+
dispatched: 'runtime',
198+
});
199+
});
200+
201+
test('planted red: react-devtools declared none is rejected by the real route', () => {
202+
const plantedNone: PlatformExecutionKindOf = (command) =>
203+
command === 'react-devtools' ? 'none' : registryKind(command);
204+
205+
expect(dominanceFailures(scanCompositionRoot(), plantedNone)).toEqual([
206+
'react-devtools declares platformExecution none but its CLI route dispatches runtime (legacy)',
207+
]);
208+
});
209+
210+
test('planted red: an unroutable dispatch is reported rather than ignored', () => {
211+
const planted = `
212+
async function runCli(argv, deps) {
213+
await deps.sendToDaemon({ command: INTERNAL_COMMANDS.runtime, positionals: [] });
214+
}
215+
`;
216+
expect(scanCliRouteDispatches(planted).unattributed).toEqual(['runtime']);
217+
});
218+
});

‎src/core/command-descriptor/platform-execution-entry.ts‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ import {
44
} from '@agent-device/contracts/platform';
55

66
/**
7-
* The shape the entry gate reads. Structural on purpose: the registry's raw
8-
* descriptor type is derived from this module's consumer, and the gate must be
9-
* able to see an *absent* discriminator, which a nominal type cannot express.
7+
* Structural on purpose: the gate must see an *absent* discriminator, and the
8+
* registry's raw descriptor type — which forbids that — lives in this module's
9+
* consumer.
1010
*/
1111
type PlatformExecutionDeclarationSite = {
1212
readonly name: string;
@@ -15,15 +15,17 @@ type PlatformExecutionDeclarationSite = {
1515
};
1616

1717
/**
18-
* ADR 0019 §6: every command descriptor declares its platform-execution mode
19-
* explicitly. A registry-entry default cannot distinguish a command with *no*
20-
* platform execution (`none`) from an unmigrated one (`legacy`), which is what
21-
* makes the migration denominator machine-readable — so an undeclared
22-
* discriminator is a registry-load error, not a silently defaulted value.
18+
* ADR 0019 §6: every descriptor declares its platform-execution mode explicitly.
19+
* A default cannot distinguish a command with *no* platform execution (`none`)
20+
* from an unmigrated one (`legacy`), so an undeclared discriminator is a
21+
* registry-load error and the migration denominator stays machine-readable.
2322
*
24-
* The same gate rejects `none` on a descriptor that still owns a capability
25-
* bucket: capability buckets are legacy platform admission, and a command that
26-
* admits per platform executes platform behavior by definition.
23+
* `none` with a capability bucket is also rejected: a capability bucket is
24+
* platform admission, so the command executes platform behavior.
25+
*
26+
* This gate sees one descriptor at a time. Platform execution delegated to
27+
* another command is covered by the CLI-route dominance gate in
28+
* `__tests__/platform-execution-cli-route.test.ts`.
2729
*/
2830
export function readDeclaredPlatformExecution(
2931
descriptor: PlatformExecutionDeclarationSite,

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1413,7 +1413,10 @@ export const RAW_COMMAND_DESCRIPTORS = [
14131413
timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
14141414
batchable: false,
14151415
mcpExposed: false,
1416-
platformExecution: NO_PLATFORM_EXECUTION,
1416+
// `react-devtools start` on a Limrun Android instance dispatches internal
1417+
// `runtime port-reverse`, which reaches a provider device runtime. Platform
1418+
// execution delegated through another command is still platform execution.
1419+
platformExecution: LEGACY_PLATFORM_EXECUTION,
14171420
},
14181421
{
14191422
name: 'web',

0 commit comments

Comments
 (0)