chore: enforce the terminal daemon platform boundary

Author: thymikee

scripts/layering/check.ts

@@ -19,7 +19,9 @@
 //     an import whose source zone outranks its target zone, plus a ratchet on the
 //     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.
+//     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.
 //   - 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
@@ -98,6 +100,7 @@ import { policyLead, policyViolation, ZONE_POLICIES } from './zone-policy.ts';
 import { contractsImplementationAuthorityViolations } from './contracts-implementation-policy.ts';
 import { selectorPipelineOwnershipViolations } from './selector-pipeline-ownership.ts';
 import { recordRuntimeRegistryJoinViolations } from './record-runtime-registry-policy.ts';
+import { checkDaemonPlatformBoundary } from './daemon-platform-boundary.ts';
 import { listTrackedProductionSources, listTrackedTypeScriptFiles } from './tracked-sources.ts';
 
 const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
@@ -485,7 +488,9 @@ function report(
         `inside its declared owner (R7); the largest type-level cycle is ${typeCycle} files ` +
         `(R9); ${daemonModularitySummary()}; ` +
         `${packageBoundariesSummary(repoRoot)}; ${platformPackagePolicySummary()}; ` +
-        `${runtimeCommandCutoverSummary()}; and bin.ts imports normalizeCliCommandAlias, ` +
+        `${runtimeCommandCutoverSummary()}; R65 keeps production src/daemon free of concrete ` +
+        `platform imports in every executable and type-only form; and bin.ts imports ` +
+        `normalizeCliCommandAlias, ` +
         `actually passes it into buildCommandUsageText, and holds no local alias literals ` +
         `(R12).\n`,
     );
@@ -543,6 +548,7 @@ export const LAYERING_RULE_IDS = [
   'type-spine-inversions',
   'session-state-ownership',
   'daemon-modularity-ratchets',
+  'daemon-platform-boundary',
   'bin-alias-fast-path',
   'package-boundaries',
   'platform-package-policy',
@@ -564,6 +570,8 @@ export const LAYERING_RULES: Readonly<Record<LayeringRuleId, LayeringRule>> = {
   'session-state-ownership': (context) => checkSessionStateOwnership(context.sources),
   'daemon-modularity-ratchets': (context) =>
     checkDaemonModularityRatchets(context.edges, context.typeCycleMembers),
+  'daemon-platform-boundary': (context) =>
+    checkDaemonPlatformBoundary([...context.sources].map(([path, source]) => ({ path, source }))),
   'bin-alias-fast-path': (context) => checkBinAliasFastPath(context.sources),
   'package-boundaries': () => checkPackageBoundaries(repoRoot),
   'platform-package-policy': (context) =>

scripts/layering/daemon-platform-boundary.test.ts

@@ -0,0 +1,193 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  DAEMON_PLATFORM_BOUNDARY_RULE,
+  daemonPlatformBoundaryViolations,
+  findDaemonPlatformDependencies,
+} from './daemon-platform-boundary.ts';
+
+const daemonFile = 'src/daemon/terminal-boundary-fixture.ts';
+
+function dependencies(source: string, file = daemonFile) {
+  return findDaemonPlatformDependencies([{ path: file, source }]);
+}
+
+function violations(source: string, file = daemonFile) {
+  return daemonPlatformBoundaryViolations([{ path: file, source }]);
+}
+
+test('R65 rejects static, type-only, dynamic, type, and re-export dependencies with source lines', () => {
+  const source = [
+    "import { old } from '../platforms/android/old.ts';",
+    "import type { OldType } from '../platforms/android/types.ts';",
+    "const lazy = import('../platforms/android/lazy.ts');",
+    "type ImportedType = import('../platforms/android/type.ts').ImportedType;",
+    "export { old } from '../platforms/android/re-export.ts';",
+    "export type { OldType } from '@agent-device/platform-android/types';",
+    "export * from '@agent-device/platform-apple';",
+  ].join('\n');
+
+  assert.deepEqual(
+    dependencies(source).map(({ kind, spec, line, target }) => ({ kind, spec, line, target })),
+    [
+      {
+        kind: 'static import',
+        spec: '../platforms/android/old.ts',
+        line: 1,
+        target: 'src/platforms/android/old.ts',
+      },
+      {
+        kind: 'type-only import',
+        spec: '../platforms/android/types.ts',
+        line: 2,
+        target: 'src/platforms/android/types.ts',
+      },
+      {
+        kind: 'dynamic import',
+        spec: '../platforms/android/lazy.ts',
+        line: 3,
+        target: 'src/platforms/android/lazy.ts',
+      },
+      {
+        kind: 'type import',
+        spec: '../platforms/android/type.ts',
+        line: 4,
+        target: 'src/platforms/android/type.ts',
+      },
+      {
+        kind: 're-export',
+        spec: '../platforms/android/re-export.ts',
+        line: 5,
+        target: 'src/platforms/android/re-export.ts',
+      },
+      {
+        kind: 'type-only re-export',
+        spec: '@agent-device/platform-android/types',
+        line: 6,
+        target: '@agent-device/platform-android/types',
+      },
+      {
+        kind: 're-export',
+        spec: '@agent-device/platform-apple',
+        line: 7,
+        target: '@agent-device/platform-apple',
+      },
+    ],
+  );
+
+  assert.deepEqual(
+    violations(source).map(({ rule, file, line }) => ({ rule, file, line })),
+    Array.from({ length: 7 }, (_, index) => ({
+      rule: DAEMON_PLATFORM_BOUNDARY_RULE,
+      file: daemonFile,
+      line: index + 1,
+    })),
+  );
+});
+
+test('R65 recognizes side-effect and aliased imports, including nested daemon paths', () => {
+  const source = [
+    "import '../../platforms/web/runtime.ts';",
+    "import { runtime as platformRuntime } from '@agent-device/platform-web/runtime';",
+  ].join('\n');
+
+  assert.deepEqual(
+    dependencies(source, 'src/daemon/handlers/terminal-boundary-fixture.ts').map((found) => ({
+      kind: found.kind,
+      line: found.line,
+      spec: found.spec,
+      target: found.target,
+    })),
+    [
+      {
+        kind: 'static import',
+        line: 1,
+        spec: '../../platforms/web/runtime.ts',
+        target: 'src/platforms/web/runtime.ts',
+      },
+      {
+        kind: 'static import',
+        line: 2,
+        spec: '@agent-device/platform-web/runtime',
+        target: '@agent-device/platform-web/runtime',
+      },
+    ],
+  );
+});
+
+test('R65 ignores comments, ordinary strings, unresolved dynamic imports, and lookalike names', () => {
+  const source = [
+    'const documentation = "import(\'../platforms/android/comment.ts\'); @agent-device/platform-android";',
+    "// import { ignored } from '../platforms/android/comment.ts';",
+    "const packageName = '@agent-device/platform-android';",
+    "const relativeName = '../platforms/android/not-an-import.ts';",
+    'const computed = import(platformSpecifier);',
+    "import '../platforms-sibling/not-platform.ts';",
+    "import '@agent-device/platforms';",
+    "import '@agent-device/platform';",
+  ].join('\n');
+
+  assert.deepEqual(dependencies(source), []);
+});
+
+test('R65 rejects require, import-equals, and template-literal type imports', () => {
+  const source = [
+    "const android = require('@agent-device/platform-android');",
+    'const runtime = require(`../platforms/android/runtime.ts`);',
+    "import web = require('@agent-device/platform-web');",
+    'type Apple = import(`@agent-device/platform-apple`).Apple;',
+    'type Android = import(`../platforms/android/types.ts`).Android;',
+  ].join('\n');
+
+  assert.deepEqual(
+    dependencies(source).map(({ kind, spec, line }) => ({ kind, spec, line })),
+    [
+      { kind: 'require', spec: '@agent-device/platform-android', line: 1 },
+      { kind: 'require', spec: '../platforms/android/runtime.ts', line: 2 },
+      { kind: 'import equals', spec: '@agent-device/platform-web', line: 3 },
+      { kind: 'type import', spec: '@agent-device/platform-apple', line: 4 },
+      { kind: 'type import', spec: '../platforms/android/types.ts', line: 5 },
+    ],
+  );
+});
+
+test('R65 folds statically constructed dynamic platform specifiers', () => {
+  const source = [
+    "const apple = import('@agent-device/' + 'platform-apple');",
+    'const android = import(`../platforms/${"android"}/runtime.ts`);',
+  ].join('\n');
+
+  assert.deepEqual(
+    dependencies(source).map(({ kind, spec, line }) => ({ kind, spec, line })),
+    [
+      { kind: 'dynamic import', spec: '@agent-device/platform-apple', line: 1 },
+      { kind: 'dynamic import', spec: '../platforms/android/runtime.ts', line: 2 },
+    ],
+  );
+});
+
+test('R65 ignores non-daemon and test-shaped records even when their syntax is red', () => {
+  const source = "import { platform } from '../platforms/android/runtime.ts';";
+  assert.deepEqual(dependencies(source, 'src/core/terminal-boundary-fixture.ts'), []);
+  assert.deepEqual(dependencies(source, 'src/daemon/terminal-boundary-fixture.test.ts'), []);
+  assert.deepEqual(dependencies(source, 'src/daemon/__tests__/terminal-boundary-fixture.ts'), []);
+});
+
+test('R65 treats a relative specifier as legacy platform code only after path resolution', () => {
+  const source = [
+    "import { platform } from '../../platforms/android/runtime.ts';",
+    "import { sibling } from '../platforms-sibling/runtime.ts';",
+    "import { exact } from '../platforms';",
+  ].join('\n');
+
+  assert.deepEqual(
+    dependencies(source).map(({ spec, target, line }) => ({ spec, target, line })),
+    [
+      {
+        spec: '../platforms',
+        target: 'src/platforms',
+        line: 3,
+      },
+    ],
+  );
+});