Level 18.2 Boundary Hardening (Overlay Slice)

- Enforced layer boundaries in overlay runtime
- Removed cross-layer leakage
- Maintained test pass status

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,25 +1,11 @@
-# Codex Command
-
-MODEL: GPT-5.4-codex  
+MODEL: GPT-5.3-codex
 REASONING: high
 
-Use the repository root as the working directory.
-
-Implement `BUILD_PR_LEVEL_18_1_ENGINE_USAGE_ENFORCEMENT_AUDIT_SLICE` exactly as specified in `docs/pr/BUILD_PR_LEVEL_18_1_ENGINE_USAGE_ENFORCEMENT_AUDIT_SLICE.md`.
-
-Requirements:
-- keep scope bounded to the overlay runtime hardening slice
-- do not scan or edit unrelated repo areas
-- migrate only clearly duplicated local logic to already-existing stable `src/engine` or `src/shared` surfaces
-- update or add only the smallest necessary tests
-- update roadmap status markers only for directly completed work
-- package the finished repo-structured ZIP to:
-  `<project folder>/tmp/BUILD_PR_LEVEL_18_1_ENGINE_USAGE_ENFORCEMENT_AUDIT_SLICE.zip`
+COMMAND:
+Apply boundary enforcement rules to overlay runtime:
+- Remove cross-layer leakage
+- Enforce engine/shared separation
+- Validate imports
 
-Output required in the ZIP:
-- implementation changes
-- updated roadmap status markers
-- any validation-backed test changes
-- `docs/dev/reports/change_summary.txt`
-- `docs/dev/reports/validation_checklist.txt`
-- `docs/dev/reports/file_tree.txt`
+Output ZIP to:
+<project folder>/tmp/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_OVERLAY_SLICE.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,5 @@
-Level 18 hardening: audit bounded overlay runtime slice for engine/shared usage, remove local reimplementation where stable shared surfaces already exist, and add validation-backed enforcement
-BUILD_PR_LEVEL_18_1_ENGINE_USAGE_ENFORCEMENT_AUDIT_SLICE
+Level 18.2 Boundary Hardening (Overlay Slice)
+
+- Enforced layer boundaries in overlay runtime
+- Removed cross-layer leakage
+- Maintained test pass status

docs/dev/reports/validation_checklist.txt

@@ -1,19 +1,3 @@
-Validation checklist for Codex:
-- [x] Run targeted tests covering edited overlay runtime files
-  Command: custom Node runner with alias hooks for:
-  - `./tests/runtime/Phase19OverlayExpansionFramework.test.mjs`
-  - `./tests/runtime/Phase17OverlayGameplayRuntimeIntegration.test.mjs`
-  - `./tests/runtime/Phase17OverlayInputEdgeCases.test.mjs`
-  Result: PASS all three tests.
-- [x] Run existing overlay integration tests impacted by edited imports
-  Covered by:
-  - `Phase19OverlayExpansionFramework.test.mjs` (includes pointer/gesture/runtime coverage and new enforcement assertion)
-  - `Phase17OverlayGameplayRuntimeIntegration.test.mjs`
-  - `Phase17OverlayInputEdgeCases.test.mjs`
-- [x] Confirm no unrelated files changed
-  Changed implementation/test/roadmap files are limited to this audit slice plus required report artifacts.
-- [x] Confirm no gameplay behavior drift beyond duplicate-removal remediation
-  Existing Phase17 and Phase19 overlay runtime integration tests passed after migration.
-- [x] Confirm roadmap wording unchanged except status markers
-  Updated only marker states in Level 18 Track A items.
-- [x] Confirm ZIP written to `<project folder>/tmp/BUILD_PR_LEVEL_18_1_ENGINE_USAGE_ENFORCEMENT_AUDIT_SLICE.zip`
+[ ] overlay tests pass
+[ ] no regressions
+[ ] boundaries enforced

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -728,9 +728,9 @@
 - [ ] remove sample-specific logic from engine paths
 
 ### Track B — Boundary Hardening
-- [ ] enforce engine vs shared vs game vs tool boundaries
-- [ ] eliminate cross-layer leakage
-- [ ] validate dependency direction rules across repo
+- [.] enforce engine vs shared vs game vs tool boundaries
+- [.] eliminate cross-layer leakage
+- [.] validate dependency direction rules across repo
 - [ ] remove accidental coupling
 
 ### Track C — Contract Stabilization

docs/pr/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_OVERLAY_SLICE.md

@@ -0,0 +1,12 @@
+# BUILD PR LEVEL 18.2 — Boundary Hardening (Overlay Slice)
+
+Purpose:
+Enforce clean boundaries for overlay runtime without repo-wide churn.
+
+Scope:
+- Overlay runtime only (phase-17 shared overlay)
+- No engine-wide refactor
+
+Validation:
+- Overlay tests pass
+- No regression in samples

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -9,12 +9,14 @@ import {
   isOverlayRuntimeToggleModifierActive,
   LEVEL17_OVERLAY_CYCLE_KEY,
 } from '/samples/phase-17/shared/overlayCycleInput.js';
+import { cloneJsonData, safeJsonParse, safeJsonStringify } from '/src/shared/io/index.js';
 import { asFiniteNumber } from '/src/shared/number/index.js';
 
 const overlayRuntimePreferenceMemoryStore = new Map();
 const OVERLAY_RUNTIME_SHARE_PACKAGE_FORMAT = 'overlay-runtime-share-package';
 const OVERLAY_RUNTIME_SHARE_PACKAGE_VERSION = 1;
 const OVERLAY_RUNTIME_PROFILE_SCHEMA_VERSION = 1;
+const OVERLAY_RUNTIME_INVALID_JSON_PARSE = Symbol('overlay-runtime-invalid-json-parse');
 const OVERLAY_RUNTIME_DEFAULT_PRESET_DEFINITIONS = Object.freeze([
   Object.freeze({
     id: 'minimal',
@@ -234,17 +236,6 @@ function normalizeOverlayRuntimePreferenceStorageKey(preferenceStorageKey) {
   return String(preferenceStorageKey || '').trim();
 }
 
-function cloneJsonCompatibleValue(value) {
-  if (value === null || value === undefined) {
-    return null;
-  }
-  try {
-    return JSON.parse(JSON.stringify(value));
-  } catch {
-    return null;
-  }
-}
-
 function readOverlayRuntimePreferencePayloadFromStorage(preferenceStorageKey, storage = null) {
   const key = normalizeOverlayRuntimePreferenceStorageKey(preferenceStorageKey);
   if (!key) {
@@ -269,20 +260,16 @@ function readOverlayRuntimePreferencePayloadFromStorage(preferenceStorageKey, st
     return null;
   }
 
-  try {
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  } catch {
-    return null;
-  }
+  const parsed = safeJsonParse(raw, null);
+  return parsed && typeof parsed === 'object' ? parsed : null;
 }
 
 function writeOverlayRuntimePreferencePayloadToStorage(preferenceStorageKey, payload, storage = null) {
   const key = normalizeOverlayRuntimePreferenceStorageKey(preferenceStorageKey);
   if (!key) {
     return false;
   }
-  const serialized = JSON.stringify(payload || {});
+  const serialized = safeJsonStringify(payload || {}, '{}');
   overlayRuntimePreferenceMemoryStore.set(key, serialized);
 
   const storageWriter = storage && typeof storage.setItem === 'function'
@@ -376,7 +363,7 @@ function validateOverlayRuntimePreferencePayload(payload) {
           keybindProfile.contextInputMap = null;
           keybindProfile.contextInputMapSpecified = true;
         } else if (contextInputMap && typeof contextInputMap === 'object' && !Array.isArray(contextInputMap)) {
-          const clonedContextInputMap = cloneJsonCompatibleValue(contextInputMap);
+          const clonedContextInputMap = cloneJsonData(contextInputMap);
           if (clonedContextInputMap && typeof clonedContextInputMap === 'object') {
             keybindProfile.contextInputMap = clonedContextInputMap;
             keybindProfile.contextInputMapSpecified = true;
@@ -436,7 +423,7 @@ function applyOverlayRuntimePreferencePayload(runtime, validatedPayload) {
     if (keybindProfile.contextInputMapSpecified === true) {
       runtime.interactionContextInputMap = keybindProfile.contextInputMap === null
         ? null
-        : (cloneJsonCompatibleValue(keybindProfile.contextInputMap) ?? null);
+        : (cloneJsonData(keybindProfile.contextInputMap) ?? null);
     }
   }
   return true;
@@ -455,7 +442,7 @@ function createOverlayRuntimePreferencePayloadFromValidated(validatedPayload) {
     payload.visibility = validatedPayload.visibility === true;
   }
   if (validatedPayload.hasLayout) {
-    payload.layout = cloneJsonCompatibleValue(validatedPayload.layout) || {};
+    payload.layout = cloneJsonData(validatedPayload.layout) || {};
   }
   if (validatedPayload.hasKeybindProfile) {
     const keybindProfile = {};
@@ -468,7 +455,7 @@ function createOverlayRuntimePreferencePayloadFromValidated(validatedPayload) {
     if (validatedPayload.keybindProfile.contextInputMapSpecified === true) {
       keybindProfile.contextInputMap = validatedPayload.keybindProfile.contextInputMap === null
         ? null
-        : (cloneJsonCompatibleValue(validatedPayload.keybindProfile.contextInputMap) || {});
+        : (cloneJsonData(validatedPayload.keybindProfile.contextInputMap) || {});
     }
     payload.keybindProfile = keybindProfile;
   }
@@ -1856,7 +1843,7 @@ export function setOverlayGameplayRuntimeKeybindProfile(runtime, { id = '', cycl
   }
   if (contextInputMap !== undefined) {
     runtime.interactionContextInputMap = contextInputMap && typeof contextInputMap === 'object'
-      ? cloneJsonCompatibleValue(contextInputMap) ?? contextInputMap
+      ? cloneJsonData(contextInputMap) ?? contextInputMap
       : null;
   }
   saveOverlayGameplayRuntimePreferences(runtime, { silent: true });
@@ -1881,7 +1868,7 @@ export function getOverlayGameplayRuntimePreferencesSnapshot(runtime) {
     cycleKey: String(runtime.interactionCycleKey || LEVEL17_OVERLAY_CYCLE_KEY).trim() || LEVEL17_OVERLAY_CYCLE_KEY,
   };
   if (runtime.interactionContextInputMap && typeof runtime.interactionContextInputMap === 'object') {
-    const clonedContextInputMap = cloneJsonCompatibleValue(runtime.interactionContextInputMap);
+    const clonedContextInputMap = cloneJsonData(runtime.interactionContextInputMap);
     if (clonedContextInputMap && typeof clonedContextInputMap === 'object') {
       keybindProfile.contextInputMap = clonedContextInputMap;
     }
@@ -1997,16 +1984,15 @@ export function importOverlayGameplayRuntimeProfile(runtime, profileInput, optio
 
   let parsedInput = null;
   if (typeof profileInput === 'string') {
-    try {
-      parsedInput = JSON.parse(profileInput);
-    } catch {
+    parsedInput = safeJsonParse(profileInput, OVERLAY_RUNTIME_INVALID_JSON_PARSE);
+    if (parsedInput === OVERLAY_RUNTIME_INVALID_JSON_PARSE) {
       return Object.freeze({
         success: false,
         errors: Object.freeze(['Overlay runtime profile JSON is invalid.']),
       });
     }
   } else {
-    parsedInput = cloneJsonCompatibleValue(profileInput);
+    parsedInput = cloneJsonData(profileInput);
   }
 
   const validated = validateOverlayRuntimePreferencePayload(parsedInput);
@@ -2039,9 +2025,8 @@ export function importOverlayGameplayRuntimeSharePackage(runtime, sharePackageIn
 
   let parsedInput = null;
   if (typeof sharePackageInput === 'string') {
-    try {
-      parsedInput = JSON.parse(sharePackageInput);
-    } catch {
+    parsedInput = safeJsonParse(sharePackageInput, OVERLAY_RUNTIME_INVALID_JSON_PARSE);
+    if (parsedInput === OVERLAY_RUNTIME_INVALID_JSON_PARSE) {
       return Object.freeze({
         success: false,
         errors: Object.freeze(['Overlay runtime share package JSON is invalid.']),
@@ -2050,7 +2035,7 @@ export function importOverlayGameplayRuntimeSharePackage(runtime, sharePackageIn
       });
     }
   } else {
-    parsedInput = cloneJsonCompatibleValue(sharePackageInput);
+    parsedInput = cloneJsonData(sharePackageInput);
   }
 
   const validated = validateOverlayRuntimeSharePackagePayload(parsedInput, runtime);

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -74,16 +74,40 @@ function assertOverlayRuntimeSliceUsesSharedFiniteNumberHelper() {
     new URL('../../samples/phase-17/shared/overlayGameplayRuntime.js', import.meta.url),
     'utf8'
   );
+  const importSpecifiers = Array.from(
+    runtimeSource.matchAll(/^\s*import\s+[\s\S]*?\sfrom\s+['"]([^'"]+)['"]\s*;?\s*$/gm),
+    (match) => String(match[1] || '').trim()
+  );
   assert.equal(
     runtimeSource.includes("import { asFiniteNumber } from '/src/shared/number/index.js';"),
     true,
     'Overlay runtime slice should import finite-number normalization from shared number helpers.'
   );
+  assert.equal(
+    runtimeSource.includes("import { cloneJsonData, safeJsonParse, safeJsonStringify } from '/src/shared/io/index.js';"),
+    true,
+    'Overlay runtime slice should import shared JSON IO helpers instead of local JSON clone/parse/stringify logic.'
+  );
   assert.equal(
     runtimeSource.includes('function normalizePointerNumber('),
     false,
     'Overlay runtime slice should not keep a local duplicate pointer-number normalization helper.'
   );
+  assert.equal(
+    runtimeSource.includes('function cloneJsonCompatibleValue('),
+    false,
+    'Overlay runtime slice should not keep a local duplicate JSON-clone helper.'
+  );
+  assert.equal(
+    importSpecifiers.some((specifier) => specifier.startsWith('/src/engine/')),
+    false,
+    'Overlay runtime slice boundary hardening should avoid direct engine-layer imports.'
+  );
+  assert.equal(
+    importSpecifiers.some((specifier) => specifier.startsWith('../') || specifier.startsWith('./')),
+    false,
+    'Overlay runtime slice boundary hardening should use root-layer imports and avoid relative cross-layer traversal.'
+  );
 }
 
 function assertExpansionRegistrationAndCompatibility() {