fix(layering): exact-shape include pin and honest dual-load wording

Cubic re-review on 63fd297:

- P2: the per-package include pin filtered `*.global.d.ts` by suffix, so an
  unrelated include in that shape class drifted past the compiled-set
  predicate silently. The pin now compares exact include ARRAYS against the
  two shapes that exist today ([src] and replay-port/session-journal's
  command-registry global.d.ts sibling); extending it is a deliberate edit
  that says whether insideCompiledSources must widen too. Mutation: adding a
  made-up src/generated-env.global.d.ts include to xml goes red.
- P3: the escape branch's rationale claimed every tunnel duplicates the
  module; duplication needs the SAME module also loaded through its package
  specifier (and type-only tunnels cost nothing at runtime). Doc block and
  violation message now state the mixing/dual-route condition, matching the
  file header's existing precise phrasing.

Author: thymikee

scripts/layering/package-boundaries.ts

@@ -179,11 +179,15 @@ export function insideCompiledSources(file: string): boolean {
  * the redirect to kernel's `dist-types` keeps every emitted file under host-kit's `rootDir`,
  * so neither TS6059 nor TS6307 fires (the root-escape tunnel DOES fail: TS2307, since `../..
  * /../kernel/...` lands outside every include and no package owns `kernel` at that depth).
- * What the sibling tunnel breaks is runtime identity — Node loads kernel once by path and
- * once by specifier, so two AppError classes coexist and `instanceof` silently fails. That
- * is invisible to any compiler. The remaining resolution failures (unknown package,
- * subpath the exports map does not name) are owned by NodeNext for compiled files with
- * TS2307; uncompiled files never reach either check, so for them R11 holds every branch.
+ * What the sibling tunnel risks is runtime identity: Node's ESM loader does not realpath
+ * specifiers, so when the same module is ALSO loaded through its package specifier — the
+ * normal route for every other consumer — the two keys instantiate it twice in one process
+ * (duplicate AppError, broken `instanceof`). Type-only tunnels carry no runtime cost, but
+ * the branch cannot condition on that from syntax alone and the layering claim fails either
+ * way. Any duplicate-instance risk invisible to the compiler is R11's to hold; the
+ * remaining resolution failures (unknown package, subpath the exports map does not name)
+ * are owned by NodeNext for compiled files with TS2307; uncompiled files never reach either
+ * check, so for them R11 holds every branch.
  */
 export function checkPackageInternalSites(
   pkg: WorkspacePackage,
@@ -204,8 +208,9 @@ export function checkPackageInternalSites(
           line: site.line,
           message:
             `'${site.specifier}' escapes ${pkg.dir}/ — a workspace package may not reach ` +
-            `outside its own directory. Import a sibling through its specifier (Node would ` +
-            `load the tunnelled module twice), or move the shared code below ${pkg.dir}.`,
+            `outside its own directory. Import a sibling through its specifier (mixing the ` +
+            `two routes instantiates the module twice), or move the shared code below ` +
+            `${pkg.dir}.`,
         });
       }
       continue;

scripts/layering/project-references.test.ts

@@ -72,13 +72,24 @@ test('the compiled-set predicate is licensed by the tsconfig include/exclude sha
     'scripts/help-conformance-command-validator.ts',
     'packages/command-registry/src/global.d.ts',
   ]);
+  // `src` everywhere, plus the one shared ambient-declaration entry replay-port and
+  // session-journal include. Exact include ARRAYS, not a `global.d.ts` suffix class: a
+  // new include of any name must extend this allow-list deliberately, or the drift fails
+  // the test (#3289 cubic review P2 — a suffix filter would silently accept unrelated
+  // `*.global.d.ts` additions, which is the drift this pin exists to catch).
+  const knownIncludeShapes = [
+    JSON.stringify(['src']),
+    JSON.stringify(['src', '../command-registry/src/global.d.ts']),
+  ];
   for (const pkg of readWorkspacePackages(repoRoot)) {
     const config = readTsconfig(`${pkg.dir}/tsconfig.json`);
     assert.equal(config.exclude, undefined, `${pkg.dir}/tsconfig.json must not declare exclude`);
-    assert.deepEqual(
-      (config.include ?? ['**/*']).filter((entry) => !entry.endsWith('global.d.ts')),
-      ['src'],
-      `${pkg.dir}/tsconfig.json must keep including exactly src/`,
+    const include = JSON.stringify(config.include ?? ['**/*']);
+    assert.ok(
+      knownIncludeShapes.includes(include),
+      `${pkg.dir}/tsconfig.json includes ${include}; the compiled-set predicate assumes ` +
+        `the known shapes ${knownIncludeShapes.join(' / ')} — extend the allow-list here ` +
+        'only after widening insideCompiledSources to match',
     );
   }
 });