Skip to content

Commit ae15898

Browse files
committed
refactor: extract platform inventory runtime
1 parent 44c298d commit ae15898

160 files changed

Lines changed: 6129 additions & 3296 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTEXT.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -411,6 +411,13 @@ axis and stages a deeper platform-runtime seam, one abandonment-safe command cut
411411
that earned ADR 0019's staged platform-runtime migration. Its substrate plus complete
412412
`devices`/`logs`/`network` checkpoint must validate the seam before any further command migration.
413413
These are ratchets, not permission to scaffold façades before a real seam has two adapters.
414+
- Platform package boundary (R13). ADR 0019 has exactly six private
415+
`@agent-device/platform-*` package façades and one root composition file,
416+
`src/platform-runtime.ts`. R13 pins that total registration, forbids contracts-to-platform,
417+
sibling-platform, root/daemon, and raw-process edges in every import form (including tests), and
418+
keeps package façades metadata-eager but inventory/runtime mechanics lazy. Composition cannot probe tools, prepare
419+
assets, or construct helpers. Each rule has a planted-red structural case; R11 still owns the
420+
general workspace exports/dependency boundary.
414421
- Zero-dep CI jobs (R8). Some jobs run scripts straight from a checkout with `install-deps: false`,
415422
so they have no `node_modules`. Nothing local can feel that constraint — every dev machine has
416423
`node_modules` sitting right there — so a script grows a package import, passes locally, and fails

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ app-log disposal contract without changing `close`'s legacy platform-execution o
99
command's platform adapter must change, this Status must name its complete unit before substrate work
1010
begins. Broader migration requires this Status to record **continue**.
1111

12+
During the `devices` unit, doctor discovery, replay-test sharding, Apple simulator hints, and Android
13+
emulator lifecycle keep their existing command execution owners while consuming the same injected,
14+
neutral inventory capability. That coexistence moves discovery mechanics once; it does not migrate
15+
those descriptors or authorize a second local/provider chooser.
16+
1217
## Rules at a glance
1318

1419
- Daemon device-execution code depends on platform-neutral contracts. Concrete device mechanics

‎docs/agents/testing.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -140,9 +140,10 @@ hand-maintained path map:
140140
left to CI by `--run` so a root checkout never installs Expo dependencies
141141
implicitly.
142142
- **Always-on gates** (`lint`, `typecheck`, `layering`, `fallow`, `format`) fire
143-
for their input categories and are never silently skipped. Platform source
144-
also selects the provider-integration and coverage gates required by the
145-
Testing Matrix.
143+
for their input categories and are never silently skipped. Legacy
144+
`src/platforms/` source also selects provider-integration and coverage.
145+
`packages/platform-*` source selects the shared runtime-contract unit lane,
146+
provider-integration, and coverage so a package move cannot narrow its evidence.
146147
- **Commands** are resolved from real `package.json` scripts, so a renamed
147148
script fails loudly instead of dropping a gate.
148149
- A **small explicit build-ownership layer** covers the paths whose owning build

‎fallow-baselines/health.json‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -374,11 +374,6 @@
374374
"count": 1
375375
}
376376
},
377-
"src/platforms/apple/core/devices.ts": {
378-
"crap_moderate": {
379-
"count": 1
380-
}
381-
},
382377
"src/platforms/apple/core/perf.ts": {
383378
"complexity_high": {
384379
"count": 1

‎package.json‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -127,10 +127,10 @@
127127
"fallow:baseline": "fallow dead-code --save-baseline fallow-baselines/dead-code.json --summary && fallow health --report-only --save-baseline fallow-baselines/health.json --summary",
128128
"check:fallow": "fallow audit",
129129
"check:affected": "node --experimental-strip-types scripts/check-affected/run.ts",
130-
"check:affected:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/run.test.ts",
130+
"check:affected:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/check-affected/model.test.ts scripts/check-affected/platform-packages.test.ts scripts/check-affected/run.test.ts",
131131
"check:coverage-changed": "node --experimental-strip-types scripts/coverage-changed/run.ts",
132132
"check:coverage-changed:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/coverage-changed/model.test.ts scripts/coverage-changed/run.test.ts",
133-
"check:layering": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/layering/model.test.ts scripts/layering/zone-policy.test.ts scripts/layering/daemon-modularity.test.ts scripts/layering/package-boundaries.test.ts scripts/layering/facade-exports.test.ts scripts/layering/bin-alias-fast-path.test.ts && node --experimental-strip-types scripts/layering/check.ts",
133+
"check:layering": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/layering/model.test.ts scripts/layering/zone-policy.test.ts scripts/layering/daemon-modularity.test.ts scripts/layering/package-boundaries.test.ts scripts/layering/platform-package-policy.test.ts scripts/layering/platform-package-repository.test.ts scripts/layering/platform-package-source-policy.test.ts scripts/layering/facade-exports.test.ts scripts/layering/bin-alias-fast-path.test.ts && node --experimental-strip-types scripts/layering/check.ts",
134134
"depgraph": "node --experimental-strip-types scripts/depgraph/build.ts",
135135
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/affected.test.ts",
136136
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
@@ -149,7 +149,7 @@
149149
"check:unit": "pnpm check:contention-retry && pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
150150
"check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
151151
"prepack": "pnpm check:mcp-metadata && pnpm package:npm",
152-
"typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
152+
"typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
153153
"test-app:install": "pnpm install --dir examples/test-app",
154154
"test-app:start": "pnpm --dir examples/test-app start",
155155
"test-app:ios": "pnpm --dir examples/test-app ios",
@@ -173,7 +173,7 @@
173173
"test:output-economy": "vitest run --project output-economy",
174174
"test:smoke:web": "pnpm build && node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/smoke-web-platform.test.ts",
175175
"test:smoke": "node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/smoke-*.test.ts",
176-
"test:integration:node": "node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/*.test.ts",
176+
"test:integration:node": "node --experimental-strip-types scripts/node-test-tmpdir.ts --test --test-concurrency=1 test/integration/*.test.ts",
177177
"test:integration": "pnpm test:integration:node && pnpm test:integration:provider",
178178
"test:concurrency-torture": "node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/nightly/concurrency-torture.test.ts",
179179
"test:replay:ios": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/simulator",
@@ -257,6 +257,12 @@
257257
"@agent-device/contracts": "workspace:*",
258258
"@agent-device/kernel": "workspace:*",
259259
"@agent-device/maestro": "workspace:*",
260+
"@agent-device/platform-android": "workspace:*",
261+
"@agent-device/platform-apple": "workspace:*",
262+
"@agent-device/platform-harmonyos": "workspace:*",
263+
"@agent-device/platform-linux": "workspace:*",
264+
"@agent-device/platform-vega": "workspace:*",
265+
"@agent-device/platform-web": "workspace:*",
260266
"@agent-device/provider-limrun": "workspace:*",
261267
"@agent-device/provider-webdriver": "workspace:*",
262268
"@agent-device/replay-test": "workspace:*",
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import type { InventoryUse } from './platform-module.ts';
2+
3+
/** Serializable operation requirements owned by a runtime-backed command descriptor. */
4+
export type RuntimeUseDeclaration = Readonly<{
5+
required: readonly string[];
6+
preferred: readonly string[];
7+
}>;
8+
9+
export type CommandPlatformExecution =
10+
| Readonly<{ kind: 'legacy' }>
11+
| Readonly<{ kind: 'inventory'; use: InventoryUse }>
12+
| Readonly<{ kind: 'device-runtime'; use: RuntimeUseDeclaration }>;
13+
14+
export function assertCommandPlatformExecution(
15+
value: unknown,
16+
): asserts value is CommandPlatformExecution {
17+
if (value === null || typeof value !== 'object') throw invalidPlatformExecution();
18+
const declaration = value as Record<string, unknown>;
19+
const keys = Object.keys(declaration).sort();
20+
if (declaration['kind'] === 'legacy' && sameKeys(keys, ['kind'])) return;
21+
if (
22+
declaration['kind'] === 'inventory' &&
23+
sameKeys(keys, ['kind', 'use']) &&
24+
hasExactInventoryUse(declaration['use'])
25+
) {
26+
return;
27+
}
28+
if (
29+
declaration['kind'] === 'device-runtime' &&
30+
sameKeys(keys, ['kind', 'use']) &&
31+
hasRuntimeUseDeclaration(declaration['use'])
32+
) {
33+
return;
34+
}
35+
throw invalidPlatformExecution();
36+
}
37+
38+
function hasExactInventoryUse(value: unknown): boolean {
39+
if (value === null || typeof value !== 'object') return false;
40+
const use = value as Record<string, unknown>;
41+
return use['kind'] === 'device-inventory' && sameKeys(Object.keys(use).sort(), ['kind']);
42+
}
43+
44+
function hasRuntimeUseDeclaration(value: unknown): boolean {
45+
if (value === null || typeof value !== 'object') return false;
46+
const use = value as Record<string, unknown>;
47+
const required = stringArray(use['required']);
48+
const preferred = stringArray(use['preferred']);
49+
if (!required || !preferred) return false;
50+
if (!hasUniqueValues(required) || !hasUniqueValues(preferred)) return false;
51+
if (!areDisjoint(required, preferred)) return false;
52+
return sameKeys(Object.keys(use).sort(), ['preferred', 'required']);
53+
}
54+
55+
function stringArray(value: unknown): string[] | null {
56+
if (!Array.isArray(value)) return null;
57+
return value.every((key): key is string => typeof key === 'string') ? value : null;
58+
}
59+
60+
function hasUniqueValues(values: readonly string[]): boolean {
61+
return new Set(values).size === values.length;
62+
}
63+
64+
function areDisjoint(left: readonly string[], right: readonly string[]): boolean {
65+
const leftValues = new Set(left);
66+
return right.every((value) => !leftValues.has(value));
67+
}
68+
69+
function sameKeys(actual: readonly string[], expected: readonly string[]): boolean {
70+
return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
71+
}
72+
73+
function invalidPlatformExecution(): TypeError {
74+
return new TypeError(
75+
'Command platform execution must declare exactly one of legacy, inventory, or device-runtime',
76+
);
77+
}

‎packages/contracts/src/device-inventory.test.ts‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { test } from 'vitest';
33
import type { DeviceInfo } from '@agent-device/kernel/device';
44
import {
55
countDeviceInventoryByGroup,
6+
filterDeviceInventoryProjection,
67
LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS,
78
} from './device-inventory.ts';
89

@@ -33,3 +34,53 @@ test('inventory counts Vega as its own platform family', () => {
3334
assert.deepEqual(counts.vega, { available: 1, booted: 1 });
3435
assert.deepEqual(counts.android, { available: 0, booted: 0 });
3536
});
37+
38+
test('local inventory projection filters device kind and fresh boot state', () => {
39+
const devices: DeviceInfo[] = [
40+
{
41+
platform: 'apple',
42+
appleOs: 'ios',
43+
target: 'mobile',
44+
id: 'booted',
45+
name: 'Booted iPhone',
46+
kind: 'simulator',
47+
booted: true,
48+
},
49+
{
50+
platform: 'apple',
51+
appleOs: 'ios',
52+
target: 'mobile',
53+
id: 'shutdown',
54+
name: 'Shutdown iPhone',
55+
kind: 'simulator',
56+
booted: false,
57+
},
58+
{
59+
platform: 'apple',
60+
appleOs: 'ios',
61+
target: 'mobile',
62+
id: 'physical',
63+
name: 'Physical iPhone',
64+
kind: 'device',
65+
booted: true,
66+
},
67+
{
68+
platform: 'apple',
69+
appleOs: 'tvos',
70+
target: 'tv',
71+
id: 'booted-tv',
72+
name: 'Booted Apple TV',
73+
kind: 'simulator',
74+
booted: true,
75+
},
76+
];
77+
78+
assert.deepEqual(
79+
filterDeviceInventoryProjection(devices, {
80+
target: 'mobile',
81+
kind: 'simulator',
82+
booted: true,
83+
}).map((device) => device.id),
84+
['booted'],
85+
);
86+
});

‎packages/contracts/src/device-inventory.ts‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
import {
22
isIosFamily,
33
isMacOs,
4+
matchesPlatformSelector,
45
type DeviceInfo,
6+
type DeviceKind,
57
type DeviceTarget,
68
type PlatformSelector,
79
} from '@agent-device/kernel/device';
@@ -26,6 +28,9 @@ export type DeviceInventoryRequest = {
2628
clientId?: string;
2729
iosSimulatorSetPath?: string;
2830
androidSerialAllowlist?: string[];
31+
/** Internal local-inventory projection filters; not public command grammar. */
32+
kind?: DeviceKind;
33+
booted?: boolean;
2934
};
3035

3136
export type DeviceInventoryGroup = 'android' | 'harmonyos' | 'apple' | 'vega' | 'linux' | 'web';
@@ -53,13 +58,16 @@ export function countDeviceInventoryByGroup(devices: DeviceInfo[]): DeviceInvent
5358
return counts;
5459
}
5560

56-
export function shouldUseHostMacFastPath(selector: {
57-
platform?: PlatformSelector;
58-
target?: DeviceTarget;
59-
}): boolean {
60-
return (
61-
selector.platform === 'macos' ||
62-
(selector.platform === 'apple' && selector.target === 'desktop')
61+
export function filterDeviceInventoryProjection(
62+
devices: readonly DeviceInfo[],
63+
request: Pick<DeviceInventoryRequest, 'platform' | 'target' | 'kind' | 'booted'>,
64+
): DeviceInfo[] {
65+
return devices.filter(
66+
(device) =>
67+
matchesPlatformSelector(device, request.platform) &&
68+
(request.target === undefined || (device.target ?? 'mobile') === request.target) &&
69+
(request.kind === undefined || device.kind === request.kind) &&
70+
(request.booted === undefined || device.booted === request.booted),
6371
);
6472
}
6573

‎packages/contracts/src/device-provider.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,4 +44,17 @@ export type LeaseLifecycleProvider = {
4444

4545
export type DeviceInventoryProvider = (
4646
request: DeviceInventoryRequest,
47+
signal?: AbortSignal,
4748
) => Promise<DeviceInfo[] | null | undefined>;
49+
50+
export type ProviderDeviceInventoryOutcome =
51+
| Readonly<{ kind: 'declined' }>
52+
| Readonly<{ kind: 'inventory'; devices: readonly DeviceInfo[] }>;
53+
54+
/** Closed provider-owned inventory source; an empty inventory is authoritative. */
55+
export type ProviderDeviceInventorySource = Readonly<{
56+
discover(
57+
request: Readonly<DeviceInventoryRequest>,
58+
signal: AbortSignal,
59+
): Promise<ProviderDeviceInventoryOutcome>;
60+
}>;

‎packages/contracts/src/facades/device.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ export {
1010
LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS,
1111
WEB_DESKTOP_DEVICE,
1212
countDeviceInventoryByGroup,
13-
shouldUseHostMacFastPath,
13+
filterDeviceInventoryProjection,
1414
} from '../device-inventory.ts';
1515
export type {
1616
DeviceInventoryGroup,
@@ -22,6 +22,8 @@ export type {
2222
DeviceLease,
2323
LeaseLifecycleContext,
2424
LeaseLifecycleProvider,
25+
ProviderDeviceInventoryOutcome,
26+
ProviderDeviceInventorySource,
2527
} from '../device-provider.ts';
2628
export {
2729
DEVICE_ROTATIONS,

0 commit comments

Comments
 (0)