Skip to content

Commit 827630c

Browse files
committed
docs(adr): model the runner subtree as a durable platform-owned facet
Review correction on #2050: the sunset story attributed the runner-consumer migration to #1983, which owns snapshot/presentation vocabulary — not the runner's daemon/root consumers — so that event cannot delete the ./runner subpaths or the subtree exemptions. Reword ADR-0019, R13, and the gate comments: the facet is the intended ownership model, its seam is enumerated and pinned (exact export list, one client composition root, one test-host installer, raw-process ban, eager-closure pins), and the seam narrows only if a real runner-consumer migration retires the direct consumers. The declaration mechanism stays apple-specific until another family needs a mechanics facet. No behavior change; identifiers and comments only.
1 parent 7b59e95 commit 827630c

5 files changed

Lines changed: 47 additions & 48 deletions

File tree

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

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -129,20 +129,20 @@ platform-common package, and it preserves the package façades' implementation-l
129129
Its introduction carries the normal workspace-package compliance surface: `check:affected`
130130
selection, R11/R13 package enumeration, and the composite typecheck project list.
131131

132-
The Apple XCUITest runner client is colocated inside `packages/platform-apple` as the
133-
`src/runner/` mechanics subtree (#2040) — Apple mechanics belong to the Apple package — while its
134-
daemon and root consumers have not yet migrated behind the composition gateway (#1983). R13 admits
135-
that transitional state deliberately rather than by exception sprawl: the family exports its root
136-
façade plus exactly the enumerated `./runner`, `./runner/client`, and `./runner/test-host`
137-
subpaths; the `./runner` façade subpath is the recorded seam for unmigrated root consumers; the
138-
host-bound `./runner/client` factory has one composition root and `./runner/test-host` one vitest
139-
installer; the subtree may own its cache files and usbmux sockets (the ambient-host rule exempts
140-
exactly that subtree), while raw process primitives stay banned — host authority still enters
141-
through one focused injected port (`AppleRunnerHost`: process execution, diagnostics, retry,
142-
probes, locks, foreground Apple tooling, physical-device control) constructed by exactly one
143-
composition root. When #1983 completes and the daemon reaches Apple only through runtime
144-
operations, the transitional subpaths and every exemption keyed on the subtree are deleted and the
145-
family returns to a single implementation-lazy façade export.
132+
The Apple XCUITest runner client is a durable platform-owned implementation facet colocated
133+
inside `packages/platform-apple` as the `src/runner/` subtree (#2040) — Apple mechanics belong to
134+
the Apple package. R13 models the facet by enumeration rather than by exception sprawl: the family
135+
exports its root façade plus exactly the `./runner`, `./runner/client`, and `./runner/test-host`
136+
subpaths; the `./runner` façade subpath is the seam through which daemon and root consumers reach
137+
runner mechanics directly today; the host-bound `./runner/client` factory has one composition root
138+
and `./runner/test-host` one vitest installer; the facet owns its cache files and usbmux sockets
139+
(the ambient-host rule exempts exactly that subtree), while raw process primitives stay banned —
140+
host authority still enters through one focused injected port (`AppleRunnerHost`: process
141+
execution, diagnostics, retry, probes, locks, foreground Apple tooling, physical-device control)
142+
constructed by exactly one composition root. No current issue owns migrating the runner's direct
143+
consumers behind the composition gateway; if such a migration retires them, the `./runner` seam
144+
narrows with it, but the facet itself is the intended ownership model, not a temporary exception.
145+
The declaration mechanism stays apple-specific until another family needs a mechanics facet.
146146

147147
Canonical family, `AppleOS`, public-leaf, and selector identity remain declared in
148148
`@agent-device/kernel/device`. Platform-module metadata references one canonical family; during

‎scripts/layering/package-boundaries.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -448,9 +448,9 @@ test('the real tree parses, declares, and passes R11', () => {
448448
]);
449449
const platformApplePackage = packages.find((pkg) => pkg.name === '@agent-device/platform-apple');
450450
assert.ok(platformApplePackage, 'platform-apple package must exist');
451-
// The root façade plus the enumerated transitional runner subpaths (#2040,
452-
// folded when #1983 completes); any further subpath widens this key list and
453-
// fails the assertion. R13 pins the same list from the manifest side.
451+
// The root façade plus the runner mechanics facet's enumerated subpaths
452+
// (#2040); any further subpath widens this key list and fails the
453+
// assertion. R13 pins the same list from the manifest side.
454454
assert.deepEqual([...platformApplePackage.exportTargets.keys()].sort(), [
455455
'@agent-device/platform-apple',
456456
'@agent-device/platform-apple/runner',

‎scripts/layering/platform-package-policy.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,8 @@ test('only src/platform-runtime.ts may import a concrete platform package', () =
133133
}
134134
});
135135

136-
test('the apple runner transitional subpaths are the enumerated exception', () => {
137-
// The façade subpath is the recorded #1983 seam: root code may import it.
136+
test('the apple runner mechanics facet subpaths are the enumerated exception', () => {
137+
// The façade subpath is the facet's consumer seam: root code may import it.
138138
const sources = validSources();
139139
sources.set(
140140
'src/daemon/selector-runtime.ts',
@@ -187,7 +187,7 @@ test('the apple runner transitional subpaths are the enumerated exception', () =
187187
);
188188
});
189189

190-
test('the runner mechanics subtree is exempt from ambient-host and raw-process rules the right way around', () => {
190+
test('the runner mechanics facet is exempt from ambient-host and raw-process rules the right way around', () => {
191191
// Production runner mechanics may own files/sockets (fs/net/os) directly...
192192
const sources = validSources();
193193
sources.set(

‎scripts/layering/platform-package-policy.ts‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,21 +23,20 @@ const COMPOSITION_FILE = 'src/platform-runtime.ts';
2323
const RULE = 'R13 platform-package-substrate';
2424
const RAW_PROCESS_SPECIFIERS = new Set(['child_process', 'node:child_process']);
2525

26-
// #2040: the Apple XCUITest runner client is colocated in platform-apple as a
27-
// transitional mechanics subtree. Its subpaths are the recorded seam for the
28-
// daemon/root consumers that have not migrated behind the composition gateway
29-
// yet (#1983); when that migration completes, these subpaths and every
30-
// exemption keyed on the subtree disappear and the family returns to a single
31-
// façade export.
26+
// #2040: the Apple XCUITest runner client is a platform-owned implementation
27+
// facet colocated in platform-apple as the src/runner/ subtree. Its subpaths
28+
// are the enumerated seam through which daemon/root consumers reach runner
29+
// mechanics directly (the runner-consumer migration behind the composition
30+
// gateway has no owner today; if one retires those direct consumers, the seam
31+
// narrows with it — the facet itself is durable Apple ownership, not a
32+
// temporary exception).
3233
export const APPLE_RUNNER_SUBTREE = 'packages/platform-apple/src/runner/';
3334
const APPLE_RUNNER_FACADE = '@agent-device/platform-apple/runner';
3435
const APPLE_RUNNER_CLIENT = '@agent-device/platform-apple/runner/client';
3536
const APPLE_RUNNER_TEST_HOST = '@agent-device/platform-apple/runner/test-host';
3637
const APPLE_RUNNER_CLIENT_COMPOSITION = 'src/platforms/apple/core/runner-client.ts';
3738
const APPLE_RUNNER_TEST_HOST_INSTALLER = 'scripts/vitest-apple-runner-host-setup.ts';
38-
const TRANSITIONAL_MECHANICS_SUBPATHS: Readonly<
39-
Partial<Record<PlatformFamily, readonly string[]>>
40-
> = {
39+
const MECHANICS_FACET_SUBPATHS: Readonly<Partial<Record<PlatformFamily, readonly string[]>>> = {
4140
apple: [APPLE_RUNNER_FACADE, APPLE_RUNNER_CLIENT, APPLE_RUNNER_TEST_HOST],
4241
};
4342

@@ -110,7 +109,7 @@ function checkDeclarations(packages: readonly PlatformPackageDeclaration[]): Lay
110109
violation(`${expectedDir}/package.json`, 1, `${expectedDir} must be private`),
111110
);
112111
}
113-
const expectedSubpaths = [expectedName, ...(TRANSITIONAL_MECHANICS_SUBPATHS[family] ?? [])];
112+
const expectedSubpaths = [expectedName, ...(MECHANICS_FACET_SUBPATHS[family] ?? [])];
114113
if (
115114
declaration.exportedSubpaths.length !== expectedSubpaths.length ||
116115
expectedSubpaths.some((subpath) => !declaration.exportedSubpaths.includes(subpath))
@@ -120,8 +119,8 @@ function checkDeclarations(packages: readonly PlatformPackageDeclaration[]): Lay
120119
`${expectedDir}/package.json`,
121120
1,
122121
`${expectedDir} must export exactly its root façade '${expectedName}'` +
123-
(TRANSITIONAL_MECHANICS_SUBPATHS[family]
124-
? ` plus the enumerated transitional mechanics subpaths`
122+
(MECHANICS_FACET_SUBPATHS[family]
123+
? ` plus the enumerated mechanics facet subpaths`
125124
: ''),
126125
),
127126
);
@@ -142,10 +141,11 @@ function checkDeclarations(packages: readonly PlatformPackageDeclaration[]): Lay
142141
function checkSource(file: string, source: string): LayeringViolation[] {
143142
const violations: LayeringViolation[] = [];
144143
const ownerFamily = familyForPackageFile(file);
145-
// The runner mechanics subtree owns its cache/lease files and usbmux sockets
146-
// (fs/net/os) and reads process identity directly; raw process primitives
147-
// stay banned below and host tooling still enters through the
148-
// AppleRunnerHost port. The exemption dies with the #1983 fold-in.
144+
// The runner mechanics facet owns its cache/lease files and usbmux sockets
145+
// (fs/net/os) and reads process identity directly — that ownership is part
146+
// of the facet's definition, so the ambient-host rules do not apply to it.
147+
// Raw process primitives stay banned below and host tooling still enters
148+
// through the AppleRunnerHost port.
149149
if (ownerFamily && isProductionSource(file) && !file.startsWith(APPLE_RUNNER_SUBTREE)) {
150150
violations.push(...checkPlatformPackageSourcePolicy(file, source, ownerFamily));
151151
}
@@ -179,9 +179,9 @@ function checkSource(file: string, source: string): LayeringViolation[] {
179179
} else if (
180180
importedFamily &&
181181
file !== COMPOSITION_FILE &&
182-
// The runner façade subpath is the transitional #1983 seam: root code that
183-
// has not migrated behind the gateway imports its types and host-free
184-
// helpers directly. R11's workspace-dependency declarations bound the
182+
// The runner façade subpath is the facet's consumer seam: root code
183+
// that reaches runner mechanics directly imports its types and host-free
184+
// helpers here. R11's workspace-dependency declarations bound the
185185
// importer set to the root package.
186186
site.spec !== APPLE_RUNNER_FACADE &&
187187
site.spec !== APPLE_RUNNER_CLIENT &&
@@ -277,5 +277,5 @@ export function checkPlatformPackagePolicy(
277277
}
278278

279279
export function platformPackagePolicySummary(): string {
280-
return 'R13 holds six private implementation-lazy platform packages above capture-kit behind one composition root, with the apple runner mechanics subtree as the enumerated transitional seam';
280+
return 'R13 holds six private implementation-lazy platform packages above capture-kit behind one composition root, with the apple runner mechanics facet behind its enumerated seam';
281281
}

‎src/__tests__/eager-closure-budgets.ts‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,8 @@ export type EagerClosureBudget = {
6464
* excluding just the entry turns the assertion into "this façade evaluates none of its own
6565
* mechanics", which is the actual ADR-0019 property.
6666
*
67-
* Every package entry surface sets this true except the transitional runner
68-
* mechanics entries (see PLATFORM_MECHANICS_ENTRY_PREFIX below), whose closure
67+
* Every package entry surface sets this true except the runner mechanics
68+
* facet entries (see PLATFORM_MECHANICS_ENTRY_PREFIX below), whose closure
6969
* IS the implementation.
7070
* Hub rows set it false -- a hub is a CONSUMER of façades, not neutral vocabulary, and three of
7171
* them legitimately hold the R3-permitted static platform seam that has not migrated yet.
@@ -323,12 +323,11 @@ export const HUB_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
323323
});
324324

325325
/**
326-
* The transitional runner mechanics subtree inside platform-apple (#2040). Its
327-
* entry surfaces ARE platform implementation, so the deny-platform assertion is
328-
* meaningless for them the same way it would be vacuous for a platform façade
329-
* without the entry-self-exclusion: the whole closure is the mechanics being
330-
* exported. Their weight stays pinned by the exact budgets; the deny question
331-
* returns with the #1983 fold-in, when these entries disappear.
326+
* The runner mechanics facet inside platform-apple (#2040). Its entry surfaces
327+
* ARE platform implementation, so the deny-platform assertion is meaningless
328+
* for them the same way it would be vacuous for a platform façade without the
329+
* entry-self-exclusion: the whole closure is the mechanics being exported.
330+
* Their weight stays pinned by the exact budgets.
332331
*/
333332
const PLATFORM_MECHANICS_ENTRY_PREFIX = 'packages/platform-apple/src/runner/';
334333

0 commit comments

Comments
 (0)