Skip to content

Commit 7ebed67

Browse files
author
DavidQ
committed
Unstable surface removal/isolation (Level 18 Track C)
1 parent 1e8845c commit 7ebed67

10 files changed

Lines changed: 175 additions & 32 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
MODEL: GPT-5.3-codex
22
REASONING: high
33

4-
Execute BUILD_PR_LEVEL_18_6_SELECTOR_PROVIDER_STABILITY_ENFORCEMENT:
4+
Execute BUILD_PR_LEVEL_18_7_UNSTABLE_SURFACE_REMOVAL_OR_ISOLATION:
55

6-
- inspect selectors/providers
7-
- identify unstable access patterns
8-
- stabilize contracts
9-
- validate consumers
6+
- identify unstable/experimental surfaces
7+
- remove or isolate safely
8+
- update consumers if required
9+
- validate contract stability
1010
- output report

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Selector/provider stability enforcement (Level 18 Track C)
1+
Unstable surface removal/isolation (Level 18 Track C)

‎docs/dev/reports/BUILD_PR_LEVEL_18_6_SELECTOR_PROVIDER_STABILITY_ENFORCEMENT_report.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# BUILD_PR_LEVEL_18_6_SELECTOR_PROVIDER_STABILITY_ENFORCEMENT
2+
3+
## Purpose
4+
Enforce stable selector/provider contracts in the Level 18 Track C lane with the smallest scoped, execution-backed changes.
5+
6+
## Surfaces Inspected
7+
- Shared selector contracts:
8+
- `src/shared/state/index.js`
9+
- `src/shared/state/selectors.js`
10+
- `src/shared/state/publicSelectors.js`
11+
- Engine/provider public contract surface:
12+
- `src/engine/debug/standard/threeD/index.js`
13+
- Direct consumers:
14+
- `src/advanced/promotion/createPromotionGate.js`
15+
- `src/advanced/state/createWorldGameStateSystem.js`
16+
- focused tests under `tests/tools` and `tests/final`
17+
18+
## Unstable Access Patterns Found
19+
1. One provider/panel consumer test imported deep internal module paths under:
20+
- `src/engine/debug/standard/threeD/providers/*`
21+
- `src/engine/debug/standard/threeD/panels/*`
22+
This bypassed the stabilized threeD public barrel contract.
23+
24+
## Stabilization Actions Applied
25+
- Migrated the unstable provider/panel consumer test import to the stable barrel:
26+
- `../../src/engine/debug/standard/threeD/index.js`
27+
28+
## Files Changed
29+
- `tests/final/DebugObservabilityMaturity.test.mjs`
30+
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` (status-only marker update)
31+
32+
## Validation Commands
33+
1. Contract-path enforcement scan:
34+
```bash
35+
rg -n "shared/state/getState\\.js|debug/standard/threeD/(providers|panels)/" src tests -g "*.js" -g "*.mjs"
36+
```
37+
Result: no matches
38+
39+
2. Focused consumer regression validation:
40+
```bash
41+
node (inline) executing:
42+
- tests/world/WorldGameStateSystem.test.mjs
43+
- tests/world/WorldGameStateAuthoritativeHandoff.test.mjs
44+
- tests/world/WorldGameStateAuthoritativeScore.test.mjs
45+
- tests/final/DebugObservabilityMaturity.test.mjs
46+
```
47+
Result: 4/4 PASS
48+
49+
## Roadmap Status Update (Execution-Backed)
50+
- `ensure selectors/providers are stable` transitioned from `[.]` to `[x]`.
51+
52+
## Bounded Notes
53+
- This PR enforces stable consumer access paths and does not alter selector/provider runtime behavior.

‎docs/dev/reports/BUILD_PR_LEVEL_18_7_UNSTABLE_SURFACE_REMOVAL_OR_ISOLATION_report.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# BUILD_PR_LEVEL_18_7_UNSTABLE_SURFACE_REMOVAL_OR_ISOLATION
2+
3+
## Purpose
4+
Advance Level 18 Track C by removing or isolating unstable/experimental surfaces while preserving stable contracts.
5+
6+
## Scope Executed
7+
- inspected selector/provider public surfaces in `src/engine/debug/standard/threeD`
8+
- identified unstable top-level barrel exposure for legacy summary-era 3D debug surfaces
9+
- isolated legacy surfaces behind an explicit controlled boundary
10+
- validated that active consumers remain on stable contracts
11+
12+
## Unstable Surface Identified
13+
Top-level exports in `src/engine/debug/standard/threeD/index.js` exposed legacy summary-era APIs alongside current inspector-era APIs:
14+
- legacy providers: transform/render-stage/collision/scene-graph summary
15+
- legacy panels: transform/render-stages/collision/scene-graph summary
16+
17+
This mixed stable and legacy contracts in the primary barrel surface.
18+
19+
## Isolation Actions Applied
20+
1. Added explicit legacy namespace module:
21+
- `src/engine/debug/standard/threeD/legacySummarySurface.js`
22+
23+
2. Removed legacy summary symbols from top-level `threeD/index.js` exports.
24+
25+
3. Added controlled legacy boundary in top-level barrel:
26+
- `export * as legacySummary3d from "./legacySummarySurface.js";`
27+
28+
Result:
29+
- stable top-level surface now exposes current contracts only
30+
- legacy summary contracts remain available through explicit opt-in namespace
31+
32+
## Consumer Impact Check
33+
- no active `src/` or `tests/` consumers depended on removed top-level legacy summary exports
34+
- legacy symbols are now referenced only within legacy module and underlying implementation files
35+
36+
## Files Changed
37+
- `src/engine/debug/standard/threeD/index.js`
38+
- `src/engine/debug/standard/threeD/legacySummarySurface.js`
39+
40+
## Validation Commands Run
41+
1. Legacy isolation contract check (inline Node):
42+
- asserts legacy summary symbols are absent at top-level `threeD` exports
43+
- asserts legacy summary symbols are present under `threeD.legacySummary3d`
44+
- Result: PASS
45+
46+
2. Consumer dependency scan:
47+
```bash
48+
rg -n "PROVIDER_3D_TRANSFORM_SUMMARY|createTransformSummaryProvider|PROVIDER_3D_RENDER_STAGE_SUMMARY|createRenderStageSummaryProvider|PROVIDER_3D_COLLISION_SUMMARY|createCollisionSummaryProvider|PROVIDER_3D_SCENE_GRAPH_SUMMARY|createSceneGraphSummaryProvider|PANEL_3D_TRANSFORM\b|create3dTransformPanel|PANEL_3D_RENDER_STAGES|create3dRenderStagesPanel|PANEL_3D_COLLISION\b|create3dCollisionPanel|PANEL_3D_SCENE_GRAPH\b|create3dSceneGraphPanel" src tests -g "*.js" -g "*.mjs"
49+
```
50+
- Result: matches limited to legacy boundary/module definitions only
51+
52+
3. Focused regression tests:
53+
- `tests/tools/CameraDebugPanel.test.mjs`
54+
- `tests/tools/TransformInspectorDebugPanel.test.mjs`
55+
- `tests/tools/RenderPipelineStagesDebugPanel.test.mjs`
56+
- `tests/tools/CollisionOverlaysDebugPanel.test.mjs`
57+
- `tests/tools/SceneGraphInspectorDebugPanel.test.mjs`
58+
- `tests/final/DebugObservabilityMaturity.test.mjs`
59+
- Result: 6/6 PASS
60+
61+
## Roadmap Note
62+
- No roadmap file update was included in this PR slice to avoid mixing with pre-existing unrelated working-tree changes in the roadmap file.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
[ ] selectors stable
2-
[ ] providers stable
3-
[ ] validation done
1+
[ ] unstable surfaces handled
2+
[ ] consumers updated
3+
[ ] validation complete

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -736,7 +736,7 @@
736736
### Track C � Contract Stabilization
737737
- [.] finalize engine public APIs
738738
- [.] finalize shared contracts
739-
- [.] ensure selectors/providers are stable
739+
- [x] ensure selectors/providers are stable
740740
- [.] remove unstable or experimental surfaces
741741

742742
### Track D � Codebase Consistency

‎docs/pr/BUILD_PR_LEVEL_18_7_UNSTABLE_SURFACE_REMOVAL_OR_ISOLATION.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# BUILD_PR_LEVEL_18_7_UNSTABLE_SURFACE_REMOVAL_OR_ISOLATION
2+
3+
## Purpose
4+
Advance Level 18 Track C by removing or isolating unstable or experimental surfaces.
5+
6+
## Scope
7+
- docs-only
8+
- no implementation authored by ChatGPT
9+
- smallest scoped stabilization step
10+
11+
## Codex Responsibilities
12+
- identify unstable or experimental surfaces in engine/shared
13+
- remove if safe OR isolate behind controlled boundaries
14+
- ensure no consumer depends on unstable interfaces
15+
- validate contract stability after changes
16+
17+
## Acceptance
18+
- unstable surfaces removed or isolated
19+
- consumers use only stable contracts
20+
- validation report produced

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

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,10 @@ index.js
66
*/
77

88
export { createStandard3dProviders, registerStandard3dProviders } from "./providers/registerStandard3dProviders.js";
9-
export {
10-
PROVIDER_3D_TRANSFORM_SUMMARY,
11-
createTransformSummaryProvider
12-
} from "./providers/transformSummaryProvider.js";
139
export {
1410
PROVIDER_3D_CAMERA_SUMMARY,
1511
createCameraSummaryProvider
1612
} from "./providers/cameraSummaryProvider.js";
17-
export {
18-
PROVIDER_3D_RENDER_STAGE_SUMMARY,
19-
createRenderStageSummaryProvider
20-
} from "./providers/renderStageSummaryProvider.js";
21-
export {
22-
PROVIDER_3D_COLLISION_SUMMARY,
23-
createCollisionSummaryProvider
24-
} from "./providers/collisionSummaryProvider.js";
25-
export {
26-
PROVIDER_3D_SCENE_GRAPH_SUMMARY,
27-
createSceneGraphSummaryProvider
28-
} from "./providers/sceneGraphSummaryProvider.js";
2913
export {
3014
PROVIDER_3D_TRANSFORM_INSPECTOR,
3115
createTransformInspectorProvider
@@ -44,11 +28,7 @@ export {
4428
} from "./providers/sceneGraphInspectorProvider.js";
4529

4630
export { createStandard3dPanels, registerStandard3dPanels } from "./panels/registerStandard3dPanels.js";
47-
export { PANEL_3D_TRANSFORM, create3dTransformPanel } from "./panels/panel3dTransform.js";
4831
export { PANEL_3D_CAMERA, create3dCameraPanel } from "./panels/panel3dCamera.js";
49-
export { PANEL_3D_RENDER_STAGES, create3dRenderStagesPanel } from "./panels/panel3dRenderStages.js";
50-
export { PANEL_3D_COLLISION, create3dCollisionPanel } from "./panels/panel3dCollision.js";
51-
export { PANEL_3D_SCENE_GRAPH, create3dSceneGraphPanel } from "./panels/panel3dSceneGraph.js";
5232
export {
5333
PANEL_3D_TRANSFORM_INSPECTOR,
5434
create3dTransformInspectorPanel
@@ -71,3 +51,4 @@ export {
7151
registerStandard3dDebugPresets
7252
} from "./presets/registerStandard3dDebugPresets.js";
7353
export { createStandard3dDebugPluginDefinition } from "./bootstrap/createStandard3dDebugSurfaceIntegration.js";
54+
export * as legacySummary3d from "./legacySummarySurface.js";

‎src/engine/debug/standard/threeD/legacySummarySurface.js‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
/*
2+
Toolbox Aid
3+
David Quesenberry
4+
04/17/2026
5+
legacySummarySurface.js
6+
*/
7+
8+
export {
9+
PROVIDER_3D_TRANSFORM_SUMMARY,
10+
createTransformSummaryProvider
11+
} from "./providers/transformSummaryProvider.js";
12+
export {
13+
PROVIDER_3D_RENDER_STAGE_SUMMARY,
14+
createRenderStageSummaryProvider
15+
} from "./providers/renderStageSummaryProvider.js";
16+
export {
17+
PROVIDER_3D_COLLISION_SUMMARY,
18+
createCollisionSummaryProvider
19+
} from "./providers/collisionSummaryProvider.js";
20+
export {
21+
PROVIDER_3D_SCENE_GRAPH_SUMMARY,
22+
createSceneGraphSummaryProvider
23+
} from "./providers/sceneGraphSummaryProvider.js";
24+
25+
export { PANEL_3D_TRANSFORM, create3dTransformPanel } from "./panels/panel3dTransform.js";
26+
export { PANEL_3D_RENDER_STAGES, create3dRenderStagesPanel } from "./panels/panel3dRenderStages.js";
27+
export { PANEL_3D_COLLISION, create3dCollisionPanel } from "./panels/panel3dCollision.js";
28+
export { PANEL_3D_SCENE_GRAPH, create3dSceneGraphPanel } from "./panels/panel3dSceneGraph.js";

‎tests/final/DebugObservabilityMaturity.test.mjs‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ DebugObservabilityMaturity.test.mjs
66
*/
77
import assert from "node:assert/strict";
88
import { drawPerformanceMetricsPanel } from "../../src/engine/debug/PerformanceMetricsPanel.js";
9-
import { create3dCollisionOverlaysPanel } from "../../src/engine/debug/standard/threeD/panels/panel3dCollisionOverlays.js";
10-
import { createCollisionOverlaysProvider } from "../../src/engine/debug/standard/threeD/providers/collisionOverlaysProvider.js";
9+
import { create3dCollisionOverlaysPanel, createCollisionOverlaysProvider } from "../../src/engine/debug/standard/threeD/index.js";
1110
import { createAdvancedInspectorDebugPluginDefinition } from "../../src/engine/debug/inspectors/index.js";
1211
import { createNetworkObservabilityPanels } from "../../src/engine/debug/network/index.js";
1312
import { drawActionInputDebugOverlay } from "../../src/engine/input/ActionInputDebugOverlay.js";

0 commit comments

Comments
 (0)