refactor: retire platforms source seam

Author: thymikee

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

@@ -19,6 +19,12 @@ R65. The per-command cutover table was retired after completion as required by s
 enforces the permanent facts-only admission and runtime-proof invariants without naming historical
 routes or handler functions.
 
+The #2082 extraction completes the physical ownership boundary: all six platform-family
+implementations and their family-owned tests live behind private package exports, `src/platforms`
+is retired, and the former R3 folder seam is gone. R13 now owns concrete platform-package import
+direction and implementation laziness; the `retired-platforms-zone` gate rejects any attempt to
+recreate the old root path.
+
 ## Rules at a glance
 
 - Daemon device-execution code depends on platform-neutral contracts. Concrete device mechanics
@@ -167,8 +173,8 @@ selection, R11/R13 package enumeration, and the composite typecheck project list
 >
 > Enforcement: each substrate package's exported subpaths are pinned in
 > `package-boundaries.test.ts` (widening fails the gate), the contracts mechanics gate stays
-> planted red, and the `platforms-root-shape` rule rejects any new shared file or directory
-> appearing directly under `src/platforms`.
+> planted red, and the `retired-platforms-zone` rule rejects every production, test, or fixture
+> file under the former `src/platforms` path.
 
 The Apple XCUITest runner client is a durable platform-owned implementation facet colocated
 inside `packages/platform-apple` as the `src/runner/` subtree (#2040) — Apple mechanics belong to
@@ -770,11 +776,12 @@ belongs to its domain: test-IME restoration is durable device state with marker-
 helper stops follow the owning platform module's lifecycle policy, and close-time cleanup consumes
 neutral owner services.
 
-R65 is the end-state enforcement: its planted-red AST tests reject every dependency edge — static,
+R65 is the daemon-side end-state enforcement: its planted-red AST tests reject every dependency edge — static,
 dynamic, re-export, and type-only — from production `src/daemon/**` modules (test files excluded,
 matching the layering scanner's scope) to `src/platforms/**` and concrete
-`@agent-device/platform-*` packages. The daemon has been removed from the R3 seam, so platform
-freedom is structurally enforced rather than periodically measured.
+`@agent-device/platform-*` packages. R13 governs concrete package imports across the whole tree,
+while `retired-platforms-zone` prevents the old root seam from being recreated; platform freedom is
+therefore structurally enforced rather than periodically measured.
 
 ## Relationship to prior decisions
 

scripts/check-affected/device-lanes.test.ts

@@ -75,7 +75,7 @@ test('shared runtime surface owns every device lane', () => {
     'packages/kernel/src/errors.ts',
     'src/daemon/android-system-dialog.ts', // naming convention in a shared dir, not a boundary
     'test/integration/smoke-daemon-clean.test.ts',
-    'src/platforms/install-source.ts',
+    'packages/provision-kit/src/install-source.ts',
   ]) {
     assert.equal(deviceLaneLeaf(file), 'shared', file);
     assert.deepEqual(lanes(file), [

scripts/check-affected/model.ts

@@ -259,27 +259,10 @@ const staticTsGates: OwnershipRule = ({ file, isTs, underSrc, underTest }) =>
 
 const srcProdGate: OwnershipRule = ({ file, isSrcProd }) => {
   if (!isSrcProd) return [];
-  const selections = [
+  return [
     reason('layering', file, 'gate:layering', 'layering guard reads production src/ modules'),
     reason('build', file, 'src-prod', 'production source is compiled by the build'),
   ];
-  if (file.startsWith('src/platforms/')) {
-    selections.push(
-      reason(
-        'provider-integration',
-        file,
-        'platform-src',
-        'platform source shapes device/provider wire behavior',
-      ),
-      reason(
-        'coverage',
-        file,
-        'platform-src',
-        'Testing Matrix requires coverage for platform/device-response changes',
-      ),
-    );
-  }
-  return selections;
 };
 
 function isNodeIntegrationPath(file: string): boolean {

scripts/layering/check.ts

@@ -3,13 +3,13 @@
 //
 // Ranked target spine, as rank groups lowest to highest. `A ◄ B` means B may not
 // be outranked by A (the back-edge order the gate rejects), NOT that every displayed import exists:
-//   { contracts, request, selectors, platforms } ◄ core ◄ { commands, cli-schema }
+//   { contracts, request, selectors } ◄ core ◄ { commands, cli-schema }
 //         ◄ { client, daemon-server } ◄ daemon-client ◄ cli
 // (authoritative ranks: `TARGET_DAG_RANK` in model.ts. The former rank-0 kernel
 // zone lives in packages/kernel since #1490 W0; R11 owns its boundary.)
 //
 // This gate enforces five things, across four scopes:
-//   - GLOBALLY, across every production source file: the R2-R3 move rules and
+//   - GLOBALLY, across every production source file: the remaining R2 move rule and
 //     rejection of all production static value-import cycles (R4). R1 kernel-sink
 //     retired with the kernel's move to packages/kernel (#1490 W0); R8
 //     zero-dep-job-closure retired with the last `install-deps: false` job
@@ -20,8 +20,8 @@
 //     same inversion measured over TYPE-ONLY edges (R6).
 //   - Over the DAEMON only: SessionState field ownership (R7), because the session
 //     record is store-owned mutable state that any daemon module can write; and the terminal
-//     concrete-platform boundary (R65), which rejects every import form into src/platforms or a
-//     platform package.
+//     concrete-platform boundary (R65), which rejects every import form into the retired
+//     src/platforms path or a platform package.
 //   - Over the TYPE GRAPH: the largest type-level import cycle is pinned by
 //     equality (R9). R4 keeps the value graph acyclic, so these cycles are free at
 //     runtime but bound what can be read in isolation; growth fails, and so does a
@@ -82,7 +82,7 @@ import {
 } from './package-boundaries.ts';
 import {
   checkPlatformPackagePolicy,
-  checkPlatformsRootShape,
+  checkRetiredPlatformsZone,
   platformPackagePolicySummary,
 } from './platform-package-policy.ts';
 import {
@@ -96,7 +96,11 @@ import { selectorPipelineOwnershipViolations } from './selector-pipeline-ownersh
 import { recordRuntimeRegistryJoinViolations } from './record-runtime-registry-policy.ts';
 import { recordRuntimeDaemonMechanicsViolations } from './record-runtime-mechanics-policy.ts';
 import { checkDaemonPlatformBoundary } from './daemon-platform-boundary.ts';
-import { listTrackedProductionSources, listTrackedTypeScriptFiles } from './tracked-sources.ts';
+import {
+  listTrackedPlatformZoneFiles,
+  listTrackedProductionSources,
+  listTrackedTypeScriptFiles,
+} from './tracked-sources.ts';
 import { runtimeExecutionIntegrityViolations } from './runtime-execution-policy.ts';
 import { sourceExecutionCompatibilityViolations } from './source-execution-policy.ts';
 import { sessionResourceOwnershipViolations } from './session-resource-ownership.ts';
@@ -469,7 +473,7 @@ function report(
 ): number {
   if (violations.length === 0) {
     process.stdout.write(
-      `Layering guard: OK — ${files.length} source files satisfy R2-R3 and contain no ` +
+      `Layering guard: OK — ${files.length} source files satisfy R2 and contain no ` +
         `value-import cycles (both checked globally); the ranked target spine contains no ` +
         `back-edges (only the composition root is unranked among src zones), and its type-only ` +
         `inversions match the R6 ratchet (${Object.values(TYPE_INVERSION_BASELINE).reduce((sum, count) => sum + count, 0)} remaining); ` +
@@ -546,7 +550,7 @@ export const LAYERING_RULE_IDS = [
   'bin-alias-fast-path',
   'package-boundaries',
   'platform-package-policy',
-  'platforms-root-shape',
+  'retired-platforms-zone',
 ] as const;
 
 export type LayeringRuleId = (typeof LAYERING_RULE_IDS)[number];
@@ -584,8 +588,7 @@ export const LAYERING_RULES: Readonly<Record<LayeringRuleId, LayeringRule>> = {
       readTrackedPlatformPackageDeclarations(repoRoot),
       { untrackedProductionFiles: listUntrackedProductionTypeScriptFiles(repoRoot) },
     ),
-  'platforms-root-shape': (context) =>
-    checkPlatformsRootShape([...context.allTypeScriptSources.keys()]),
+  'retired-platforms-zone': () => checkRetiredPlatformsZone(listTrackedPlatformZoneFiles(repoRoot)),
 };
 
 export function main(): number {

scripts/layering/model.test.ts

@@ -416,7 +416,7 @@ test('largestTypeCycleSize counts type-only cycles and ignores dynamic ones', ()
   ]);
 
   // A loop closed through a DYNAMIC import is excluded on purpose: a lazy seam is not a
-  // comprehension barrier, and R3 relies on dynamic imports existing. With no non-dynamic edge at
+  // comprehension barrier. With no non-dynamic edge at
   // all no file enters the walk, so the floor here is 0 rather than 1 — specified, not incidental.
   const dynamicCycle = resolveImportEdges(
     new Map(

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

@@ -3,7 +3,7 @@ import { test } from 'node:test';
 import {
   CANONICAL_PLATFORM_FAMILIES,
   checkPlatformPackagePolicy,
-  checkPlatformsRootShape,
+  checkRetiredPlatformsZone,
   type PlatformPackageDeclaration,
 } from './platform-package-policy.ts';
 import { classifyZone } from './model.ts';
@@ -102,7 +102,7 @@ test('the inventory substrate has six private lazy packages and one exact compos
 });
 
 test('retired platform family implementations are rejected from src/platforms', () => {
-  const violations = checkPlatformsRootShape([
+  const violations = checkRetiredPlatformsZone([
     'src/platforms/apple/core/apps.ts',
     'src/platforms/harmonyos/app-lifecycle.ts',
     'src/platforms/linux/snapshot.ts',
@@ -113,11 +113,11 @@ test('retired platform family implementations are rejected from src/platforms',
   assert.deepEqual(
     violations.map(({ file, rule }) => ({ file, rule })),
     [
-      { file: 'src/platforms/apple/core/apps.ts', rule: 'platforms-root-shape' },
-      { file: 'src/platforms/harmonyos/app-lifecycle.ts', rule: 'platforms-root-shape' },
-      { file: 'src/platforms/linux/snapshot.ts', rule: 'platforms-root-shape' },
-      { file: 'src/platforms/vega/interactor.ts', rule: 'platforms-root-shape' },
-      { file: 'src/platforms/web/provider.ts', rule: 'platforms-root-shape' },
+      { file: 'src/platforms/apple/core/apps.ts', rule: 'retired-platforms-zone' },
+      { file: 'src/platforms/harmonyos/app-lifecycle.ts', rule: 'retired-platforms-zone' },
+      { file: 'src/platforms/linux/snapshot.ts', rule: 'retired-platforms-zone' },
+      { file: 'src/platforms/vega/interactor.ts', rule: 'retired-platforms-zone' },
+      { file: 'src/platforms/web/provider.ts', rule: 'retired-platforms-zone' },
     ],
   );
 });
@@ -602,23 +602,31 @@ test('Node resolves only each platform package root facade', () => {
   }
 });
 
-test('the src/platforms root holds only the shared __tests__ directory', () => {
-  const clean = ['src/platforms/__tests__/install-source.test.ts'];
-  assert.deepEqual(checkPlatformsRootShape(clean), []);
+test('the retired src/platforms zone rejects every production, test, and fixture file', () => {
+  const planted = [
+    'src/platforms/__tests__/install-source.test.ts',
+    'src/platforms/__fixtures__/snapshot.json',
+    'src/platforms/helper.mjs',
+  ];
+  const found = checkRetiredPlatformsZone(planted);
+  assert.deepEqual(
+    found.map(({ file, rule }) => ({ file, rule })),
+    planted.map((file) => ({ file, rule: 'retired-platforms-zone' })),
+  );
 });
 
 test('a moved Android family cannot leave production or test files under the old root', () => {
   const planted = [
     'src/platforms/android/adb.ts',
     'src/platforms/android/__tests__/snapshot.test.ts',
   ];
-  const found = checkPlatformsRootShape(planted);
+  const found = checkRetiredPlatformsZone(planted);
   assert.deepEqual(
     found.map(({ file, message }) => ({ file, message })),
     planted.map((file) => ({
       file,
       message:
-        'the Android family has moved to packages/platform-android; remove the superseded src/platforms/android path',
+        'src/platforms is retired; family code belongs in its platform package, shared mechanics in an owning substrate package, and cross-family tests in their root or package test owner',
     })),
   );
 });
@@ -629,14 +637,14 @@ test('a new direct production file or sibling directory under src/platforms fail
     'src/platforms/common/util.ts',
     'src/platforms/perf-utils.ts',
   ];
-  const found = checkPlatformsRootShape(planted);
+  const found = checkRetiredPlatformsZone(planted);
   assert.deepEqual(
     found.map(({ file }) => file),
     planted,
   );
   for (const violation of found) {
-    assert.equal(violation.rule, 'platforms-root-shape');
-    assert.match(violation.message, /substrate package/);
+    assert.equal(violation.rule, 'retired-platforms-zone');
+    assert.match(violation.message, /src\/platforms is retired/);
   }
 });
 

scripts/layering/platform-package-policy.ts

@@ -11,14 +11,6 @@ export const CANONICAL_PLATFORM_FAMILIES = [
   'linux',
   'web',
 ] as const;
-const RETIRED_PLATFORM_FAMILIES = [
-  'apple',
-  'android',
-  'harmonyos',
-  'linux',
-  'vega',
-  'web',
-] as const;
 type PlatformFamily = (typeof CANONICAL_PLATFORM_FAMILIES)[number];
 export type PlatformPackageDeclaration = {
   dir: string;
@@ -56,21 +48,15 @@ const PLATFORM_RUNTIME_HOST_FILES = new Set([
 // temporary exception).
 export const APPLE_RUNNER_SUBTREE = 'packages/platform-apple/src/runner/';
 
-export function checkPlatformsRootShape(files: readonly string[]): LayeringViolation[] {
-  const allowedChild = new RegExp(`^src/platforms/__tests__/`);
-  const retiredFamily = new RegExp(`^src/platforms/(?:${RETIRED_PLATFORM_FAMILIES.join('|')})/`);
+export function checkRetiredPlatformsZone(files: readonly string[]): LayeringViolation[] {
   return files
-    .filter(
-      (file) =>
-        file.startsWith('src/platforms/') && (retiredFamily.test(file) || !allowedChild.test(file)),
-    )
+    .filter((file) => file.startsWith('src/platforms/'))
     .map((file) => ({
-      rule: 'platforms-root-shape',
+      rule: 'retired-platforms-zone',
       file,
       line: 1,
-      message: file.startsWith('src/platforms/android/')
-        ? 'the Android family has moved to packages/platform-android; remove the superseded src/platforms/android path'
-        : 'src/platforms may hold only the shared __tests__ directory; retired family code belongs in its platform package and shared code belongs in a substrate package',
+      message:
+        'src/platforms is retired; family code belongs in its platform package, shared mechanics in an owning substrate package, and cross-family tests in their root or package test owner',
     }));
 }
 const APPLE_RUNNER_FACADE = '@agent-device/platform-apple/runner';

scripts/layering/tracked-sources.ts

@@ -53,6 +53,15 @@ export function listTrackedTypeScriptFiles(repoRoot: string): string[] {
   return out.split('\n').filter(Boolean);
 }
 
+/** Every tracked file under the retired platform root, regardless of extension. */
+export function listTrackedPlatformZoneFiles(repoRoot: string): string[] {
+  const out = execFileSync('git', ['ls-files', '--', 'src/platforms'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  return out.split('\n').filter(Boolean);
+}
+
 /** Production sources only: test files and `__tests__/` trees are not layering subjects. */
 export function isProductionSourceFile(file: string): boolean {
   return file.endsWith('.ts') && !/(?:^|\/)__tests__\//.test(file) && !/\.test\.ts$/.test(file);

scripts/layering/zone-policy.test.ts

@@ -2,10 +2,9 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { policyLead, policyViolation, ZONE_POLICIES } from './zone-policy.ts';
 
-// R2-R3 (and the retired R1) were predicate functions with no unit test for eight months: the only thing
-// exercising them was the real tree, which is clean, so a rule that had silently stopped matching
-// would have looked exactly like a rule that was being obeyed. These tests assert each boundary
-// fires AND each documented exemption holds, so the table cannot quietly become decoration.
+// The folder policies originally had no unit test: the only thing exercising them was a clean real
+// tree, so a rule that silently stopped matching looked like one being obeyed. These tests keep the
+// remaining R2 policy from becoming decoration.
 
 type Kind = { typeOnly?: boolean; dynamic?: boolean };
 
@@ -28,8 +27,8 @@ function firing(e: ReturnType<typeof edge>): string[] {
   return ZONE_POLICIES.filter((policy) => policyViolation(policy, e) !== null).map((p) => p.rule);
 }
 
-test('R2 commands-floor closes the four zones below the command surface, whatever the kind', () => {
-  for (const zone of ['platforms', 'core', 'daemon']) {
+test('R2 commands-floor closes the remaining zones below the command surface, whatever the kind', () => {
+  for (const zone of ['core', 'daemon']) {
     for (const kind of [{}, { typeOnly: true }, { dynamic: true }]) {
       assert.ok(
         firing(edge(`src/${zone}/thing.ts`, zone, 'commands', kind)).includes('R2 commands-floor'),
@@ -43,27 +42,11 @@ test('R2 commands-floor closes the four zones below the command surface, whateve
   assert.deepEqual(firing(edge('src/mcp/tools.ts', 'mcp', 'commands')), []);
 });
 
-test('R3 platforms-seam closes static value imports and opens the two declared seam owners', () => {
-  // Closed from an ordinary zone.
-  assert.deepEqual(firing(edge('src/cli/run.ts', 'cli', 'platforms')), ['R3 platforms-seam']);
-
-  // Open to the seam owners.
-  for (const file of ['src/core/interactors/android.ts', 'src/sdk/android-adb.ts']) {
-    assert.deepEqual(firing(edge(file, 'core', 'platforms')), [], `${file} is a seam owner`);
-  }
-
-  // The daemon has completed ADR 0019 and is no longer a platform seam. Neither its server nor
-  // its process-boundary client may reach platform code directly.
-  assert.deepEqual(firing(edge('src/daemon/handlers/perf.ts', 'daemon', 'platforms')), [
-    'R3 platforms-seam',
-  ]);
-  assert.deepEqual(firing(edge('src/daemon/client/daemon-client.ts', 'daemon', 'platforms')), [
-    'R3 platforms-seam',
-  ]);
-
-  // Both tolerated kinds are the documented escape hatch that preserves CLI cold-start.
-  assert.deepEqual(firing(edge('src/cli/run.ts', 'cli', 'platforms', { dynamic: true })), []);
-  assert.deepEqual(firing(edge('src/cli/run.ts', 'cli', 'platforms', { typeOnly: true })), []);
+test('the retired R3 platforms seam has no zone-policy declaration', () => {
+  assert.equal(
+    ZONE_POLICIES.some(({ rule }) => rule === 'R3 platforms-seam'),
+    false,
+  );
 });
 
 test('every policy carries a hint, and the lead names the kind it rejected', () => {
@@ -72,17 +55,14 @@ test('every policy carries a hint, and the lead names the kind it rejected', ()
     assert.ok(policy.hint.length > 20, `${policy.rule} needs an actionable hint`);
   }
 
-  assert.match(
-    policyLead(edge('a', 'platforms', 'commands')),
-    /platforms\/ must not import commands\//,
-  );
+  assert.match(policyLead(edge('a', 'core', 'commands')), /core\/ must not import commands\//);
   assert.match(
     policyLead(edge('a', 'core', 'commands', { typeOnly: true })),
     /must not type-only import commands\//,
   );
   assert.match(
-    policyLead(edge('a', 'cli', 'platforms', { dynamic: true })),
-    /must not dynamic import platforms\//,
+    policyLead(edge('a', 'core', 'commands', { dynamic: true })),
+    /must not dynamic import commands\//,
   );
 });