Enforce engine SDK boundaries and rehearse every layer display

Restrict runtime SDK imports to their engine directories, including package
subpaths, re-exports and dynamic imports. Keep three measured, reasoned
exceptions for the Bhote Koshi property-record models and reject stale
exceptions. Move the Cesium annotation renderers and both wind adapters to
their engine folders, preserving their implementations and lazy loading.

Load all 35 manifest display entries on a fake engine with an unknown kind
and no native extensions. Draw small fixtures and verify resource and
subscription cleanup before destroying the engine. Name the three entries
without display factories as skips. Update the architecture, infrastructure
lifecycle and engine integration documentation to describe the code today.

Cesium behavior is unchanged, and Navara keeps its existing behavior. The
weather comparison harness supplies the Navara flow-mesh factory and accepts
the previous backend location for comparison runs. No user-visible strings
change.

Cesium layer-renderer lines fall from 14 to 0, Navara layer-renderer lines
from 314 to 189, outside-engine Cesium import files from 5 to 3, viewer lines
from 933 to 910, extension reads from 4 to 3, and engine-name lines from 36
to 33. No coupling count grows. Targeted checks pass: 845 tests, three named
rehearsal skips. Import directions, package boundaries, formatting and syntax
checks pass.

Checked in the browser, keyless: the contract suite passes on Navara and on
Cesium apart from the camera-events check that also fails intermittently
before; Navara annotations pass across engine switches; the ground-look
comparison is pixel-identical. qa-draw-tool's hidden-line check and the wind
engine switch fail the same way before this change.

scripts/check-import-directions.mjs

@@ -30,59 +30,6 @@ const globeEngine = (file) => /^src\/globe\/(?:cesium|navara)\//.test(file);
 const cesiumPackage = /^(?:cesium(?:\/|$)|@cesium\/)/;
 // Navara renders through three.js and its postprocessing peer.
 const navaraPackage = /^(?:(?:three|postprocessing)(?:\/|$)|@navaramap\/)/;
-// Layers built on layer renderers keep each engine in their renderers:
-// cesium only in render/cesium*.js, three and Navara only in
-// render/navara*.js. The list grows with each layer moved onto renderers.
-const RENDERED_LAYER_DIRS = [
-  'src/layers/streetLevel/',
-  'src/layers/traffic/',
-  'src/layers/directions/',
-  'src/layers/infrastructure/',
-  'src/layers/installations/',
-  'src/layers/awareness/',
-  'src/layers/droneAirspace/',
-  'src/layers/cyclones/',
-  'src/layers/ghostMaps/',
-  'src/layers/submarineCables/',
-  'src/layers/alpr/',
-  'src/layers/cctv/',
-  'src/layers/transit/',
-  'src/layers/airQuality/',
-  'src/layers/gnss/',
-  'src/layers/perimeters/',
-  'src/layers/radio/',
-  'src/layers/bikeshare/',
-  'src/layers/earthquakes/',
-  'src/layers/firms/',
-  'src/layers/flights/',
-  'src/layers/military/',
-  'src/layers/localAdsb/',
-  'src/layers/vessels/',
-  'src/layers/satellites/',
-  'src/layers/launches/',
-  'src/layers/aircraft/',
-  'src/layers/shared/',
-];
-const W1_SHARED_FILES = new Set(
-  [
-    'trackedCamera',
-    'trailRenderer',
-    'contactTrailRenderer',
-    'focusDeemphasis',
-    'spriteOrder',
-    'iconOrientation',
-    'modelVisualAnchor',
-    'trackingClickGesture',
-  ].map((name) => `src/data/${name}.js`),
-);
-const renderedLayer = (file) =>
-  W1_SHARED_FILES.has(file) ||
-  file.startsWith('src/data/render/') ||
-  file === 'src/celestialRing.js' ||
-  file.startsWith('src/celestialRing/') ||
-  RENDERED_LAYER_DIRS.some((dir) => file.startsWith(dir));
-const cesiumLayerRenderer = (file) =>
-  /\/render\/cesium(?:[^/]*|\/[^/]+)\.js$/.test(file);
 // Navara renderers outside a layer's render/ directory: like those, they
 // reach the app only through the Navara mode's import().
 const NAVARA_SCENE_RENDERERS = new Set();
@@ -144,6 +91,25 @@ export function checkImportDirections(root) {
     (file) =>
       code.test(file) && !tests(file) && existsSync(path.join(root, file)),
   );
+  const boundaryFile = path.join(root, 'scripts/package-boundaries.json');
+  const { engineImportExceptions = [] } = existsSync(boundaryFile)
+    ? JSON.parse(readFileSync(boundaryFile, 'utf8'))
+    : {};
+  const exceptionKeys = new Set();
+  for (const item of engineImportExceptions) {
+    const key = `${item.file}:${item.package}`;
+    if (
+      typeof item.file !== 'string' ||
+      !files.includes(item.file) ||
+      !(cesiumPackage.test(item.package) || navaraPackage.test(item.package)) ||
+      typeof item.reason !== 'string' ||
+      !item.reason.trim() ||
+      exceptionKeys.has(key)
+    )
+      throw new Error(`Invalid engine import exception: ${key}`);
+    exceptionKeys.add(key);
+  }
+  const usedExceptions = new Set();
   const errors = new Set();
   const modules = new Map();
   const relative = (file) =>
@@ -185,17 +151,18 @@ export function checkImportDirections(root) {
         target = path.resolve(root, exported);
       } else {
         record.external.push(specifier);
-        if (renderedLayer(file) && !tests(file)) {
-          if (cesiumPackage.test(specifier) && !cesiumLayerRenderer(file))
-            report(
-              file,
-              `cesium only in the layer's render/cesium*.js: ${specifier}`,
-            );
-          if (navaraPackage.test(specifier) && !navaraLayerRenderer(file))
-            report(
-              file,
-              `three and Navara only in the layer's render/navara*.js: ${specifier}`,
-            );
+        const owner = cesiumPackage.test(specifier)
+          ? 'cesium'
+          : navaraPackage.test(specifier)
+            ? 'navara'
+            : null;
+        if (owner && !file.startsWith(`src/globe/${owner}/`)) {
+          const exception = engineImportExceptions.find(
+            (item) => item.file === file && item.package === specifier,
+          );
+          if (exception) usedExceptions.add(exception);
+          else
+            report(file, `${specifier} imports belong in src/globe/${owner}/`);
         }
         if (
           file.startsWith('src/') &&
@@ -395,8 +362,17 @@ export function checkImportDirections(root) {
   }
   if (existsSync(path.join(root, 'src/voice/sessionCommands.js')))
     voice('src/voice/sessionCommands.js');
+  for (const item of engineImportExceptions) {
+    if (!usedExceptions.has(item))
+      report(item.file, `Unused engine import exception: ${item.package}`);
+  }
   if (errors.size) throw new Error([...errors].join('\n'));
-  return { modules: files.length, portableEntries: roots.size };
+  return {
+    modules: files.length,
+    portableEntries: roots.size,
+    engineImportExceptionCount: usedExceptions.size,
+    engineImportExceptions: [...usedExceptions],
+  };
 }
 
 if (

scripts/check-package-boundaries.mjs

@@ -11,7 +11,9 @@ export async function checkPackageBoundaries(root) {
   const readJson = async (name) =>
     JSON.parse(await readFile(path.join(root, name), 'utf8'));
   const pkg = await readJson('package.json');
-  const groups = await readJson('scripts/package-boundaries.json');
+  const { engineImportExceptions, ...groups } = await readJson(
+    'scripts/package-boundaries.json',
+  );
   const declaredExports = Object.keys(pkg.exports || {}).sort();
   const classifiedExports = Object.values(groups)
     .flatMap((group) => group.exports)

scripts/engine-coupling-baseline.json

@@ -1,16 +1,16 @@
 {
   "metrics": {
-    "cesiumLayerRendererLines": 14,
-    "navaraLayerRendererLines": 314,
-    "cesiumImportFiles": 5,
-    "viewerLines": 933,
+    "cesiumLayerRendererLines": 0,
+    "navaraLayerRendererLines": 189,
+    "cesiumImportFiles": 3,
+    "viewerLines": 910,
     "navaraKindChecks": 2,
     "engineSniffCalls": 0,
-    "engineExtensionReads": 4,
+    "engineExtensionReads": 3,
     "groundEffectPasses": 1,
     "cesiumSdkLoads": 3,
     "screenSpaceHandlerFiles": 4,
-    "engineNameLines": 36
+    "engineNameLines": 33
   },
-  "measuredAt": "Separate scene attachment and page switching; give Director the scene"
+  "measuredAt": "Enforce SDK ownership, relocate annotation and wind backends, and rehearse every shared display"
 }

scripts/format-scope.json

@@ -1653,7 +1653,7 @@
   "src/layers/shared/render/navaraGroundOrder.test.mjs",
   "src/globe/navara/ground/corridors.js",
   "scripts/qa-ground-looks.mjs",
-  "src/layers/wind/render/cesiumFlow.js",
+  "src/globe/cesium/windFlow.js",
   "src/testSupport/imageryDisplayEngines.mjs",
   "src/data/geoImportDisplay.js",
   "src/data/geoImportDisplay.test.mjs",
@@ -1698,5 +1698,9 @@
   "src/app/layerSession.js",
   "src/standalone/sceneSwitcher.js",
   "src/app/layerSession.test.mjs",
-  "src/standalone/sceneSwitcher.test.mjs"
+  "src/standalone/sceneSwitcher.test.mjs",
+  "src/app/layers/displayRehearsal.test.mjs",
+  "src/globe/cesium/annotations/worldAnnotationRenderer.js",
+  "src/globe/cesium/annotations/screenAnnotationRenderer.js",
+  "src/globe/navara/windFlow.js"
 ]

scripts/package-boundaries.json

@@ -1,4 +1,21 @@
 {
+  "engineImportExceptions": [
+    {
+      "file": "src/data/bhoteKoshiEmbeddedMedia.js",
+      "package": "cesium",
+      "reason": "Authored story media still uses Cesium positions and property records."
+    },
+    {
+      "file": "src/data/bhoteKoshiEvent.js",
+      "package": "cesium",
+      "reason": "Authored event timing and geometry still build Cesium property records for the shared story display."
+    },
+    {
+      "file": "src/data/bhoteKoshiLocator.js",
+      "package": "cesium",
+      "reason": "Locator model still builds Cesium property records for the shared story display."
+    }
+  ],
   "infrastructure": {
     "exports": [
       "./infrastructure",
@@ -2416,9 +2433,9 @@
       "src/annotations/hybridAnnotationRenderer.js",
       "src/annotations/index.js",
       "src/annotations/resolver.js",
-      "src/annotations/screenAnnotationRenderer.js",
+      "src/globe/cesium/annotations/screenAnnotationRenderer.js",
       "src/annotations/screenScene.js",
-      "src/annotations/worldAnnotationRenderer.js",
+      "src/globe/cesium/annotations/worldAnnotationRenderer.js",
       "src/app/catalog.js",
       "src/app/constructCatalog.js",
       "src/app/sourceComposition.js",
@@ -3569,7 +3586,7 @@
       "src/layers/recentImagery/render/display.js",
       "src/layers/weather/render/display.js",
       "src/layers/wind/render/display.js",
-      "src/layers/wind/render/navaraFlow.js",
+      "src/globe/navara/windFlow.js",
       "src/layers/bhoteKoshi/render/display.js",
       "src/globe/navara/imagery/pass.js",
       "src/globe/navara/imagery/index.js",
@@ -3577,7 +3594,7 @@
       "src/globe/cesium/imagery.js",
       "src/globe/cesium/imageryShell.js",
       "src/globe/navara/ground/corridors.js",
-      "src/layers/wind/render/cesiumFlow.js",
+      "src/globe/cesium/windFlow.js",
       "src/globe/cesium/postStages.js",
       "src/data/geoImportRecords.js",
       "src/data/geoImportKml.js",
@@ -3984,7 +4001,7 @@
       "src/layers/vessels/recordPolicy.js",
       "src/layers/vessels/snapshotRenderer.js",
       "src/data/inputOwnership.js",
-      "src/annotations/worldAnnotationRenderer.js",
+      "src/globe/cesium/annotations/worldAnnotationRenderer.js",
       "src/cameraGroundGuard.js",
       "src/cameraVerbs.js",
       "src/globeInView.js",
@@ -4326,14 +4343,14 @@
       "src/layers/recentImagery/render/display.js",
       "src/layers/weather/render/display.js",
       "src/layers/wind/render/display.js",
-      "src/layers/wind/render/navaraFlow.js",
+      "src/globe/navara/windFlow.js",
       "src/layers/bhoteKoshi/render/display.js",
       "src/layers/bhoteKoshi/render/story.js",
       "src/globe/navara/ground/surface.js",
       "src/globe/navara/windFlowMesh.js",
       "src/globe/navara/ground/effect.js",
       "src/globe/navara/ground/pulse.js",
-      "src/layers/wind/render/cesiumFlow.js",
+      "src/globe/cesium/windFlow.js",
       "src/globe/cesium/postStages.js",
       "src/globe/cesium/sonar.js",
       "src/globe/cesium/sonarCommands.js",

scripts/qa-ground-looks.mjs

@@ -151,7 +151,7 @@ async function draw(origin, variant, out, engineKind) {
             served.match(/from\s+["']([^"']*cesium[^"']*)["']/)[1]
           );
           const { FlowMaterialProperty, ensureFlowFabricRegistered } =
-            await import('/src/annotations/worldAnnotationRenderer.js');
+            await import('/src/globe/cesium/annotations/worldAnnotationRenderer.js');
           const { viewer } = engine.extensions.cesium;
           const color = new Cesium.Color(...jamRgba.slice(0, 3), 0.55);
           const jam = viewer.scene.groundPrimitives.add(

scripts/qa-weather-compare.mjs

@@ -349,13 +349,19 @@ async function shootScene(browser, origin, kind, scene) {
         let used;
         if (display) {
           const navaraFlow = native
-            ? (await import('/src/layers/wind/render/navaraFlow.js'))
-                .createWindNavaraFlow
+            ? (
+                (await tryImport('/src/globe/navara/windFlow.js')) ??
+                (await import('/src/layers/wind/render/navaraFlow.js'))
+              ).createWindNavaraFlow
+            : null;
+          const createWindFlowMesh = native
+            ? (await import('/src/globe/navara/windFlowMesh.js'))
+                .createWindFlowMesh
             : null;
           renderer = display.createWindDisplay(engine, {
             flow: viewer
               ? () => cesiumFlow({ field: false })
-              : (e) => navaraFlow(e, native),
+              : (e) => navaraFlow(e, native, createWindFlowMesh),
           });
           used = 'display';
         } else if (viewer) {