Skip to content

Commit 9428496

Browse files
committed
refactor(registry): make the platform-execution discriminator exhaustive
ADR 0019 §6 (amended): every command descriptor declares its platform-execution mode explicitly. Adds the `none` mode to `CommandPlatformExecution`, removes the silent `{ kind: 'legacy' }` default at registry entry, and annotates all 76 descriptors so the migration denominator is machine-readable. Part of #1739 (wave 0)
1 parent 73b54c1 commit 9428496

5 files changed

Lines changed: 192 additions & 9 deletions

File tree

‎packages/contracts/src/command-platform-execution.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { assertCommandPlatformExecution } from './command-platform-execution.ts'
55

66
describe('command platform execution declaration', () => {
77
test.each([
8+
{ kind: 'none' },
89
{ kind: 'legacy' },
910
{ kind: 'inventory', use: inventoryUse },
1011
{ kind: 'device-runtime', use: { required: ['capture'], preferred: ['inspect'] } },
@@ -14,6 +15,7 @@ describe('command platform execution declaration', () => {
1415

1516
test.each([
1617
{},
18+
{ kind: 'none', use: inventoryUse },
1719
{ kind: 'legacy', use: inventoryUse },
1820
{ kind: 'inventory' },
1921
{ kind: 'inventory', use: inventoryUse, legacy: true },

‎packages/contracts/src/command-platform-execution.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import type { InventoryUse } from './platform-module.ts';
22
import type { RuntimeUseDeclaration } from './platform-runtime.ts';
33

44
export type CommandPlatformExecution =
5+
| Readonly<{ kind: 'none' }>
56
| Readonly<{ kind: 'legacy' }>
67
| Readonly<{ kind: 'inventory'; use: InventoryUse }>
78
| Readonly<{ kind: 'device-runtime'; use: RuntimeUseDeclaration }>
@@ -18,6 +19,7 @@ export function assertCommandPlatformExecution(
1819
if (value === null || typeof value !== 'object') throw invalidPlatformExecution();
1920
const declaration = value as Record<string, unknown>;
2021
const keys = Object.keys(declaration).sort();
22+
if (declaration['kind'] === 'none' && sameKeys(keys, ['kind'])) return;
2123
if (declaration['kind'] === 'legacy' && sameKeys(keys, ['kind'])) return;
2224
if (
2325
declaration['kind'] === 'inventory' &&
@@ -96,6 +98,6 @@ function sameKeys(actual: readonly string[], expected: readonly string[]): boole
9698

9799
function invalidPlatformExecution(): TypeError {
98100
return new TypeError(
99-
'Command platform execution must declare exactly one of legacy, inventory, or device-runtime',
101+
'Command platform execution must declare exactly one of none, legacy, inventory, or device-runtime',
100102
);
101103
}
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import { describe, expect, test } from 'vitest';
2+
import { readDeclaredPlatformExecution } from '../platform-execution-entry.ts';
3+
import { commandDescriptors } from '../registry.ts';
4+
5+
describe('platform-execution registry entry gate', () => {
6+
test('rejects a descriptor that declares no discriminator', () => {
7+
expect(() => readDeclaredPlatformExecution({ name: 'planted' })).toThrow(
8+
/must declare platformExecution/,
9+
);
10+
});
11+
12+
test('rejects none on a descriptor that keeps a capability bucket', () => {
13+
expect(() =>
14+
readDeclaredPlatformExecution({
15+
name: 'planted',
16+
capability: { apple: {}, android: {}, linux: {} },
17+
platformExecution: { kind: 'none' },
18+
}),
19+
).toThrow(/keeps a capability bucket/);
20+
});
21+
22+
test('accepts none on a descriptor with no capability bucket', () => {
23+
expect(
24+
readDeclaredPlatformExecution({ name: 'planted', platformExecution: { kind: 'none' } }),
25+
).toEqual({ kind: 'none' });
26+
});
27+
28+
test('still rejects a malformed declaration', () => {
29+
expect(() =>
30+
readDeclaredPlatformExecution({ name: 'planted', platformExecution: { kind: 'inventory' } }),
31+
).toThrow(/exactly one/);
32+
});
33+
34+
test('every registered command declares an explicit execution mode', () => {
35+
const undeclared = commandDescriptors.filter(
36+
(descriptor) => descriptor.platformExecution === undefined,
37+
);
38+
expect(undeclared).toEqual([]);
39+
});
40+
41+
test('no command declares none while keeping a capability bucket', () => {
42+
const contradictory = commandDescriptors
43+
.filter(
44+
(descriptor) =>
45+
descriptor.platformExecution.kind === 'none' &&
46+
'capability' in descriptor &&
47+
descriptor.capability !== undefined,
48+
)
49+
.map(({ name }) => name);
50+
expect(contradictory).toEqual([]);
51+
});
52+
});
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import {
2+
assertCommandPlatformExecution,
3+
type CommandPlatformExecution,
4+
} from '@agent-device/contracts/platform';
5+
6+
/**
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.
10+
*/
11+
type PlatformExecutionDeclarationSite = {
12+
readonly name: string;
13+
readonly capability?: unknown;
14+
readonly platformExecution?: unknown;
15+
};
16+
17+
/**
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.
23+
*
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.
27+
*/
28+
export function readDeclaredPlatformExecution(
29+
descriptor: PlatformExecutionDeclarationSite,
30+
): CommandPlatformExecution {
31+
const declared = descriptor.platformExecution;
32+
if (declared === undefined) {
33+
throw new TypeError(
34+
`Command descriptor "${descriptor.name}" must declare platformExecution (none, legacy, inventory, or device-runtime); there is no registry-entry default`,
35+
);
36+
}
37+
assertCommandPlatformExecution(declared);
38+
if (declared.kind === 'none' && descriptor.capability !== undefined) {
39+
throw new TypeError(
40+
`Command descriptor "${descriptor.name}" declares platformExecution none but keeps a capability bucket; a command with platform admission is not platform-free`,
41+
);
42+
}
43+
return declared;
44+
}

0 commit comments

Comments
 (0)