Contract stabilization progress (Level 18 Track C)

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,30 +1,11 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 
-Execute BUILD_PR_LEVEL_18_4_GAME_TO_SAMPLE_RECLASSIFICATION_EXECUTION.
+Execute BUILD_PR_LEVEL_18_5_CONTRACT_STABILIZATION_PROGRESS:
 
-Required behavior:
-1. Use the prior reviewed recommendations as the source of truth.
-2. Execute only the approved reclassification moves for:
-   - games/Bouncing-ball
-   - games/Gravity
-   - games/Thruster
-   - games/ProjectileLab
-   - games/Orbit
-   - games/PaddleIntercept
-   - games/MultiBallChaos
-3. Do not change games/PacmanLite.
-4. Apply only the exact path/reference updates needed to keep the moved entries valid.
-5. Do not expand into unrelated cleanup or refactors.
-6. Write execution-backed reports to docs/dev/reports.
-7. Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md in place under these rules:
-   - never delete roadmap content
-   - never rewrite roadmap text
-   - only update status markers:
-     - [ ] -> [.]
-     - [.] -> [x]
-   - append additive content only if explicitly required by this PR
-
-Packaging:
-- produce final ZIP at:
-  <project folder>/tmp/BUILD_PR_LEVEL_18_4_GAME_TO_SAMPLE_RECLASSIFICATION_EXECUTION.zip
+- inspect engine public APIs
+- inspect shared contracts
+- identify unstable surfaces
+- stabilize or remove where safe
+- validate selectors/providers
+- output report

docs/dev/COMMIT_COMMENT.txt

@@ -1,7 +1 @@
-Execute approved game-to-sample reclassification moves.
-
-BUILD_PR_LEVEL_18_4_GAME_TO_SAMPLE_RECLASSIFICATION_EXECUTION
-- move approved game/demo entries into recommended sample phase targets
-- leave PacmanLite unchanged
-- update exact references required by the moves
-- update master roadmap in place under roadmap guard rules
+Contract stabilization progress (Level 18 Track C)

docs/dev/reports/BUILD_PR_LEVEL_18_5_CONTRACT_STABILIZATION_PROGRESS_report.md

@@ -0,0 +1,56 @@
+# BUILD_PR_LEVEL_18_5_CONTRACT_STABILIZATION_PROGRESS
+
+## Purpose
+Advance Level 18 Track C contract stabilization by auditing engine public APIs and shared contracts, then applying the smallest safe stabilization.
+
+## Scope Executed
+- inspected engine public API barrels in `src/engine/**/index.js` with focus on debug provider/panel surfaces
+- inspected shared contract/state surfaces in:
+  - `src/shared/contracts/index.js`
+  - `src/shared/state/index.js`
+  - `src/shared/state/selectors.js`
+  - `src/shared/state/publicSelectors.js`
+- validated selector and provider stability using focused runtime tests
+
+## Unstable Surfaces Identified
+1. `src/engine/debug/standard/threeD/index.js` did not export the current inspector-era provider/panel contracts introduced by Track H follow-up work.
+   - Impact: consumers using the threeD public barrel could not depend on stable imports for:
+     - transform inspector
+     - render pipeline stages
+     - collision overlays
+     - scene graph inspector
+
+## Stabilization Actions Executed (Safe)
+- Updated `src/engine/debug/standard/threeD/index.js` to explicitly export current inspector-era provider and panel contracts, while preserving existing legacy summary exports for compatibility.
+- No selector behavior changes were made.
+- No provider runtime behavior changes were made.
+
+## Files Changed
+- `src/engine/debug/standard/threeD/index.js`
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` (status-only marker update)
+
+## Roadmap Status Update (Execution-Backed)
+- Track C:
+  - `ensure selectors/providers are stable` updated from `[ ]` to `[.]`
+
+## Validation Commands Run
+1. Barrel contract export validation:
+```bash
+node (inline) -> imports ./src/engine/debug/standard/threeD/index.js and asserts required inspector-era exports exist
+```
+Result: PASS
+
+2. Focused shared selector/provider regression checks:
+```bash
+node (inline) -> run():
+- tests/shared/SharedFoundationCombinedPass.test.mjs
+- tests/shared/GetStateVariantClassification.test.mjs
+- tests/tools/TransformInspectorDebugPanel.test.mjs
+- tests/tools/RenderPipelineStagesDebugPanel.test.mjs
+- tests/tools/CollisionOverlaysDebugPanel.test.mjs
+- tests/tools/SceneGraphInspectorDebugPanel.test.mjs
+```
+Result: 6/6 PASS
+
+## Bounded Caveats
+- Legacy 3D summary provider/panel exports remain intentionally exposed for backward compatibility and should be retired in a dedicated deprecation/removal PR, not this progress slice.

docs/dev/reports/change_summary.txt

@@ -1,7 +1 @@
-Docs-first execution bundle for the approved game-to-sample reclassification lane.
-
-This PR asks Codex to:
-- execute the approved reclassification moves
-- leave PacmanLite alone
-- update only exact references required by those moves
-- update the master roadmap in place under the roadmap guard
+Docs-only PR

docs/dev/reports/file_tree.txt

@@ -1,10 +1 @@
-docs/
-docs/pr/
-docs/pr/BUILD_PR_LEVEL_18_4_GAME_TO_SAMPLE_RECLASSIFICATION_EXECUTION.md
-docs/dev/
-docs/dev/codex_commands.md
-docs/dev/commit_comment.txt
-docs/dev/reports/
-docs/dev/reports/change_summary.txt
-docs/dev/reports/validation_checklist.txt
-docs/dev/reports/file_tree.txt
+generated

docs/dev/reports/validation_checklist.txt

@@ -1,6 +1,3 @@
-[ ] Prior reviewed recommendations used as source of truth
-[ ] Approved entries moved from games to samples
-[ ] PacmanLite left unchanged
-[ ] Exact path/reference updates completed
-[ ] Reports written to docs/dev/reports
-[ ] Master roadmap updated in place under guard rules
+[ ] unstable surfaces identified
+[ ] stabilization applied
+[ ] validation done

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -736,7 +736,7 @@
 ### Track C � Contract Stabilization
 - [.] finalize engine public APIs
 - [.] finalize shared contracts
-- [ ] ensure selectors/providers are stable
+- [.] ensure selectors/providers are stable
 - [.] remove unstable or experimental surfaces
 
 ### Track D � Codebase Consistency

docs/pr/BUILD_PR_LEVEL_18_5_CONTRACT_STABILIZATION_PROGRESS.md

@@ -0,0 +1,20 @@
+# BUILD_PR_LEVEL_18_5_CONTRACT_STABILIZATION_PROGRESS
+
+## Purpose
+Advance Level 18 Track C by progressing engine and shared contract stabilization.
+
+## Scope
+- docs-only
+- no implementation authored by ChatGPT
+- smallest scoped stabilization step
+
+## Codex Responsibilities
+- inspect engine public APIs and shared contracts
+- identify unstable or experimental surfaces
+- stabilize or mark for removal
+- ensure selectors/providers remain stable
+
+## Acceptance
+- unstable surfaces identified
+- stabilization actions executed where safe
+- validation report produced

src/engine/debug/standard/threeD/index.js

@@ -26,13 +26,45 @@ export {
   PROVIDER_3D_SCENE_GRAPH_SUMMARY,
   createSceneGraphSummaryProvider
 } from "./providers/sceneGraphSummaryProvider.js";
+export {
+  PROVIDER_3D_TRANSFORM_INSPECTOR,
+  createTransformInspectorProvider
+} from "./providers/transformInspectorProvider.js";
+export {
+  PROVIDER_3D_RENDER_PIPELINE_STAGES,
+  createRenderPipelineStagesProvider
+} from "./providers/renderPipelineStagesProvider.js";
+export {
+  PROVIDER_3D_COLLISION_OVERLAYS,
+  createCollisionOverlaysProvider
+} from "./providers/collisionOverlaysProvider.js";
+export {
+  PROVIDER_3D_SCENE_GRAPH_INSPECTOR,
+  createSceneGraphInspectorProvider
+} from "./providers/sceneGraphInspectorProvider.js";
 
 export { createStandard3dPanels, registerStandard3dPanels } from "./panels/registerStandard3dPanels.js";
 export { PANEL_3D_TRANSFORM, create3dTransformPanel } from "./panels/panel3dTransform.js";
 export { PANEL_3D_CAMERA, create3dCameraPanel } from "./panels/panel3dCamera.js";
 export { PANEL_3D_RENDER_STAGES, create3dRenderStagesPanel } from "./panels/panel3dRenderStages.js";
 export { PANEL_3D_COLLISION, create3dCollisionPanel } from "./panels/panel3dCollision.js";
 export { PANEL_3D_SCENE_GRAPH, create3dSceneGraphPanel } from "./panels/panel3dSceneGraph.js";
+export {
+  PANEL_3D_TRANSFORM_INSPECTOR,
+  create3dTransformInspectorPanel
+} from "./panels/panel3dTransformInspector.js";
+export {
+  PANEL_3D_RENDER_PIPELINE_STAGES,
+  create3dRenderPipelineStagesPanel
+} from "./panels/panel3dRenderPipelineStages.js";
+export {
+  PANEL_3D_COLLISION_OVERLAYS,
+  create3dCollisionOverlaysPanel
+} from "./panels/panel3dCollisionOverlays.js";
+export {
+  PANEL_3D_SCENE_GRAPH_INSPECTOR,
+  create3dSceneGraphInspectorPanel
+} from "./panels/panel3dSceneGraphInspector.js";
 
 export {
   STANDARD_3D_DEBUG_PRESETS,