Level 18.3 Contract Stabilization (Overlay Slice)

- Stabilized overlay APIs
- Locked selectors/providers
- Removed unstable surfaces

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,10 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Apply boundary enforcement rules to overlay runtime:
-- Remove cross-layer leakage
-- Enforce engine/shared separation
-- Validate imports
+- Identify overlay public APIs
+- Freeze contracts
+- Remove unstable/internal exposure
+- Validate tests
 
-Output ZIP to:
-<project folder>/tmp/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_OVERLAY_SLICE.zip
+Output:
+<project folder>/tmp/BUILD_PR_LEVEL_18_3_CONTRACT_STABILIZATION_OVERLAY_SLICE.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,5 @@
-Level 18.2 Boundary Hardening (Overlay Slice)
+Level 18.3 Contract Stabilization (Overlay Slice)
 
-- Enforced layer boundaries in overlay runtime
-- Removed cross-layer leakage
-- Maintained test pass status
+- Stabilized overlay APIs
+- Locked selectors/providers
+- Removed unstable surfaces

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,3 @@
-[ ] overlay tests pass
-[ ] no regressions
-[ ] boundaries enforced
+[ ] contracts documented
+[ ] no breaking changes
+[ ] tests pass

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -734,10 +734,10 @@
 - [ ] remove accidental coupling
 
 ### Track C — Contract Stabilization
-- [ ] finalize engine public APIs
-- [ ] finalize shared contracts
+- [.] finalize engine public APIs
+- [.] finalize shared contracts
 - [ ] ensure selectors/providers are stable
-- [ ] remove unstable or experimental surfaces
+- [.] remove unstable or experimental surfaces
 
 ### Track D — Codebase Consistency
 - [ ] single class per file enforcement

docs/pr/BUILD_PR_LEVEL_18_3_CONTRACT_STABILIZATION_OVERLAY_SLICE.md

@@ -0,0 +1,12 @@
+# BUILD PR LEVEL 18.3 — Contract Stabilization (Overlay Slice)
+
+Purpose:
+Stabilize overlay runtime public contracts (APIs, selectors, providers).
+
+Scope:
+- Overlay runtime only
+- No new features
+
+Validation:
+- Contracts documented
+- Tests pass without change

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -1273,7 +1273,7 @@ function writeOverlayRuntimeSyncSnapshot(container, snapshot) {
   }
 }
 
-export function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
+function synchronizeOverlayGameplayRuntimeState(runtime, context = {}) {
   if (!runtime) {
     return null;
   }
@@ -1739,7 +1739,7 @@ export function setOverlayGameplayRuntimeExtensions(runtime, runtimeExtensions)
   return true;
 }
 
-export function isOverlayGameplayRuntimeVisible(runtime) {
+function isOverlayGameplayRuntimeVisible(runtime) {
   return runtime?.interactionVisible !== false;
 }
 
@@ -1752,7 +1752,7 @@ export function setOverlayGameplayRuntimeVisible(runtime, visible) {
   return true;
 }
 
-export function setOverlayGameplayRuntimePreferenceStorageKey(runtime, preferenceStorageKey, { loadExisting = true } = {}) {
+function setOverlayGameplayRuntimePreferenceStorageKey(runtime, preferenceStorageKey, { loadExisting = true } = {}) {
   if (!runtime) {
     return false;
   }
@@ -1850,7 +1850,7 @@ export function setOverlayGameplayRuntimeKeybindProfile(runtime, { id = '', cycl
   return true;
 }
 
-export function getOverlayGameplayRuntimePreferencesSnapshot(runtime) {
+function getOverlayGameplayRuntimePreferencesSnapshot(runtime) {
   if (!runtime) {
     return Object.freeze({
       visibility: true,
@@ -1952,7 +1952,7 @@ export function saveOverlayGameplayRuntimePreferences(runtime, options = {}) {
   return writeOverlayRuntimePreferencePayloadToStorage(preferenceStorageKey, payload, storage);
 }
 
-export function loadOverlayGameplayRuntimePreferences(runtime, options = {}) {
+function loadOverlayGameplayRuntimePreferences(runtime, options = {}) {
   if (!runtime) {
     return false;
   }
@@ -2873,3 +2873,30 @@ export function renderOverlayGameplayRuntime(runtime, context = {}) {
   }
   return invoked;
 }
+
+export const OVERLAY_GAMEPLAY_RUNTIME_PUBLIC_API_NAMES = Object.freeze([
+  'applyOverlayGameplayRuntimePreset',
+  'createOverlayGameplayRuntime',
+  'enqueueOverlayGameplayRuntimeSyncEvent',
+  'exportOverlayGameplayRuntimeProfile',
+  'exportOverlayGameplayRuntimeSharePackage',
+  'getOverlayGameplayRuntimeCompositionSnapshot',
+  'getOverlayGameplayRuntimeDefaultPresets',
+  'getOverlayGameplayRuntimeInteractionSnapshot',
+  'getOverlayGameplayRuntimePresetLibrary',
+  'importOverlayGameplayRuntimeProfile',
+  'importOverlayGameplayRuntimeSharePackage',
+  'renderOverlayGameplayRuntime',
+  'resolveOverlayGameplayRuntimeInputAction',
+  'saveOverlayGameplayRuntimePreferences',
+  'setOverlayGameplayRuntimeAdaptiveUiRules',
+  'setOverlayGameplayRuntimeContextInputMap',
+  'setOverlayGameplayRuntimeExtensions',
+  'setOverlayGameplayRuntimeKeybindProfile',
+  'setOverlayGameplayRuntimePresetLibrary',
+  'setOverlayGameplayRuntimeVisible',
+  'stepOverlayGameplayRuntime',
+  'stepOverlayGameplayRuntimeControls',
+  'stepOverlayGameplayRuntimeGestures',
+  'stepOverlayGameplayRuntimePointerInteractions',
+]);

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -6,6 +6,7 @@ Phase19OverlayExpansionFramework.test.mjs
 */
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
+import * as overlayRuntimeModule from '../../samples/phase-17/shared/overlayGameplayRuntime.js';
 import { LEVEL17_OVERLAY_CYCLE_KEY } from '../../samples/phase-17/shared/overlayCycleInput.js';
 import {
   isOverlayRuntimeCycleModifierActive,
@@ -98,6 +99,16 @@ function assertOverlayRuntimeSliceUsesSharedFiniteNumberHelper() {
     false,
     'Overlay runtime slice should not keep a local duplicate JSON-clone helper.'
   );
+  assert.equal(
+    runtimeSource.includes('export function synchronizeOverlayGameplayRuntimeState('),
+    false,
+    'Overlay runtime slice contract should not expose internal synchronization mutators directly.'
+  );
+  assert.equal(
+    runtimeSource.includes('export function getOverlayGameplayRuntimePreferencesSnapshot('),
+    false,
+    'Overlay runtime slice contract should not expose internal preference snapshot helpers directly.'
+  );
   assert.equal(
     importSpecifiers.some((specifier) => specifier.startsWith('/src/engine/')),
     false,
@@ -110,6 +121,33 @@ function assertOverlayRuntimeSliceUsesSharedFiniteNumberHelper() {
   );
 }
 
+function assertOverlayRuntimePublicApiContractFrozen() {
+  const exportedKeys = Object.keys(overlayRuntimeModule).sort();
+  const contractNames = [...overlayRuntimeModule.OVERLAY_GAMEPLAY_RUNTIME_PUBLIC_API_NAMES].sort();
+  const expectedExportedKeys = [...contractNames, 'OVERLAY_GAMEPLAY_RUNTIME_PUBLIC_API_NAMES'].sort();
+
+  assert.deepEqual(
+    exportedKeys,
+    expectedExportedKeys,
+    'Overlay runtime module export surface should match the frozen public API contract exactly.'
+  );
+  assert.equal(
+    Object.isFrozen(overlayRuntimeModule.OVERLAY_GAMEPLAY_RUNTIME_PUBLIC_API_NAMES),
+    true,
+    'Overlay runtime public API name contract should be immutable.'
+  );
+  assert.equal(
+    overlayRuntimeModule.OVERLAY_GAMEPLAY_RUNTIME_PUBLIC_API_NAMES.includes('synchronizeOverlayGameplayRuntimeState'),
+    false,
+    'Internal synchronization helpers should be excluded from the public API contract.'
+  );
+  assert.equal(
+    overlayRuntimeModule.OVERLAY_GAMEPLAY_RUNTIME_PUBLIC_API_NAMES.includes('getOverlayGameplayRuntimePreferencesSnapshot'),
+    false,
+    'Internal preference snapshot helpers should be excluded from the public API contract.'
+  );
+}
+
 function assertExpansionRegistrationAndCompatibility() {
   const counters = { step: 0, render: 0 };
   const framework = createPhase19OverlayExpansionFramework();
@@ -1250,6 +1288,7 @@ function assertOverlaySharePackageExportImportCompatibility() {
 
 export function run() {
   assertOverlayRuntimeSliceUsesSharedFiniteNumberHelper();
+  assertOverlayRuntimePublicApiContractFrozen();
   assertExpansionRegistrationAndCompatibility();
   assertExtensionLifecycleMutations();
   assertDynamicPanelSizingCapability();