Skip to content

Commit 11d7add

Browse files
author
DavidQ
committed
Boundary hardening enforcement for Level 18 Track B
BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT - enforce engine/shared/games/tools boundaries - reduce cross-layer leakage - validate dependency direction after changes
1 parent 1344594 commit 11d7add

12 files changed

Lines changed: 367 additions & 106 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

4-
Execute BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT.
5-
6-
Goal:
7-
Repair preview path resolution after the sample structure changed.
8-
9-
Required changes:
10-
- inspect `tools/preview`
11-
- update sample resolution to the current contract:
12-
`<phase>-<xx>/<xxxx>/index.html`
13-
- inspect any preview-related references to `samples/shared`
14-
- if such references exist, update them to the current `tools/preview` contract or remove them if obsolete
15-
- keep scope tightly limited to preview-path repair
16-
17-
Constraints:
18-
- do not perform unrelated cleanup
19-
- do not rewrite roadmap text
20-
- do not modify start_of_day folders
21-
- preserve existing preview behavior outside the path fix
22-
- produce validation-backed results
23-
24-
Deliverables to populate:
25-
- docs/dev/reports/change_summary.txt
26-
- docs/dev/reports/validation_checklist.txt
27-
- docs/dev/reports/file_tree.txt
28-
29-
Packaging:
30-
- output final ZIP to:
31-
<project folder>/tmp/BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT.zip
4+
Execute BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT:
5+
6+
1. Inspect engine/shared/games/tools boundaries.
7+
2. Identify cross-layer leakage and dependency-direction violations.
8+
3. Apply the smallest valid implementation needed to harden boundaries.
9+
4. Remove or relocate accidental coupling without broad refactors.
10+
5. Re-run validation and document exact findings in docs/dev/reports.
11+
6. If roadmap status is execution-backed, update status markers only in place.
12+
7. Package final ZIP to:
13+
<project folder>/tmp/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
Repair preview path contract after sample structure change.
1+
Boundary hardening enforcement for Level 18 Track B
22

3-
BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT
4-
- update tools/preview path resolution to current sample contract
5-
- validate and remove/update any stale samples/shared preview dependency
6-
- keep scope limited to preview-path repair
3+
BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT
4+
- enforce engine/shared/games/tools boundaries
5+
- reduce cross-layer leakage
6+
- validate dependency direction after changes

‎docs/dev/reports/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT_report.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT Report
2+
3+
Date: 2026-04-17
4+
Scope: Enforce boundary direction across `src/engine`, `src/shared`, `games`, `tools` with smallest scoped implementation.
5+
6+
## Boundary Rules Enforced
7+
- `engine` must not depend on `games`/`tools`/`samples`/`docs`
8+
- `shared` must not depend on `engine`/`games`/`tools`/`samples`/`docs`
9+
- `games` must not depend on `tools`/`samples`/`docs`
10+
- `tools` must not depend on `games`/`samples`/`docs`
11+
12+
## Pre-Fix Findings
13+
Command:
14+
- `node tools/dev/checkBoundaryHardeningGuard.mjs`
15+
16+
Result:
17+
- scanned files: 712
18+
- violations: 2
19+
20+
Violations:
21+
1. `games/breakout/main.js:18`
22+
- specifier: `../../tools/dev/devConsoleIntegration.js`
23+
- reason: games layer must not depend on tools layer
24+
2. `games/Asteroids/index.js:9`
25+
- specifier: `../../tools/dev/devConsoleIntegration.js`
26+
- reason: games layer must not depend on tools layer
27+
28+
## Implementation Applied
29+
- Added `tools/dev/checkBoundaryHardeningGuard.mjs` to codify dependency-direction enforcement.
30+
- Added `src/shared/utils/createNoopDevConsoleIntegration.js` as boundary-safe default integration.
31+
- Updated `games/breakout/main.js` to remove direct tools import and default to shared no-op integration.
32+
- Updated `games/Asteroids/index.js` to remove direct tools import and default to shared no-op integration.
33+
34+
## Post-Fix Validation
35+
Command:
36+
- `node tools/dev/checkBoundaryHardeningGuard.mjs`
37+
38+
Result:
39+
- scanned files: 713
40+
- violations: 0
41+
42+
Focused regressions:
43+
- `AsteroidsValidation` pass
44+
- `BreakoutValidation` pass
45+
- `ToolBoundaryEnforcement` pass
46+
47+
## Roadmap Update (Status-Only)
48+
Updated `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md` Track B markers in place:
49+
- `[.]` -> `[x]` enforce engine vs shared vs game vs tool boundaries
50+
- `[.]` -> `[x]` eliminate cross-layer leakage
51+
- `[.]` -> `[x]` validate dependency direction rules across repo
52+
- `[ ]` -> `[x]` remove accidental coupling
53+
54+
## Verdict
55+
PASS. Cross-layer leakage in scope was removed and dependency direction is now explicitly guarded and re-validated.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 29 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,37 @@
1-
BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT
1+
BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT
22
Date: 2026-04-17
3-
Scope: Preview path contract repair only (tools/preview + preview generation script).
3+
Scope: Engine/shared/games/tools boundary hardening with smallest valid coupling removal.
44

5-
Summary of changes
6-
1) Preview sample-path contract stays aligned to canonical sample paths:
7-
- samples/phase-XX/XXXX/index.html
5+
Summary
6+
1) Added boundary guard implementation
7+
- Added tools/dev/checkBoundaryHardeningGuard.mjs
8+
- Scans src/engine, src/shared, games, tools for dependency-direction violations.
9+
- Enforces:
10+
- engine must not depend on games/tools/samples/docs
11+
- shared must not depend on engine/games/tools/samples/docs
12+
- games must not depend on tools/samples/docs
13+
- tools must not depend on games/samples/docs
814

9-
2) Updated preview HTML executors to default preview output folder to images path:
10-
- tools/preview/generate-list-previews_updated.html
11-
- tools/preview/preview_svg_executor_1600x900.html
12-
- tools/preview/preview_svg_executor_games_enter.html
15+
2) Findings before fix (execution evidence)
16+
- games/breakout/main.js imported ../../tools/dev/devConsoleIntegration.js
17+
- games/Asteroids/index.js imported ../../tools/dev/devConsoleIntegration.js
18+
- These were cross-layer leakage from games -> tools.
1319

14-
Exact output-folder changes applied in each:
15-
- input default: "assets" -> "assets/images"
16-
- fallback display path: "assets" -> "assets/images"
17-
- displayed sample write target now resolves as:
18-
samples\\phase-XX\\XXXX\\assets\\images
20+
3) Smallest valid hardening implementation applied
21+
- Added src/shared/utils/createNoopDevConsoleIntegration.js as a boundary-safe default integration surface.
22+
- Updated games/breakout/main.js to use createNoopDevConsoleIntegration default.
23+
- Updated games/Asteroids/index.js to use createNoopDevConsoleIntegration default.
24+
- Removed direct games -> tools imports for dev console integration.
1925

20-
3) Updated runtime sample preview writer path:
21-
- scripts/generate-runtime-sample-previews.mjs
22-
- output path changed:
23-
path.join(sample.sampleDir, 'assets', 'preview.svg')
24-
-> path.join(sample.sampleDir, 'assets', 'images', 'preview.svg')
25-
26-
4) Preview capture dependency remains aligned to preview tooling location:
27-
- /tools/preview/runtimePreviewCapture.html
28-
- local capture page: tools/preview/runtimePreviewCapture.html
26+
4) Roadmap status-only update (execution-backed)
27+
- docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
28+
- Level 18 Track B updated in place:
29+
- [.] -> [x] enforce engine vs shared vs game vs tool boundaries
30+
- [.] -> [x] eliminate cross-layer leakage
31+
- [.] -> [x] validate dependency direction rules across repo
32+
- [ ] -> [x] remove accidental coupling
2933

3034
Notes
31-
- No engine/runtime feature behavior changed beyond preview output path contract.
32-
- No roadmap edits.
35+
- No broad refactor performed.
3336
- No start_of_day edits.
34-
- No unrelated cleanup.
35-
37+
- No engine-core behavior changes introduced beyond boundary-safe debug integration defaulting for two games.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,26 @@
1-
BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT file tree
1+
BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT file tree
22

3-
scripts/
4-
generate-runtime-sample-previews.mjs (modified)
3+
src/
4+
shared/
5+
utils/
6+
createNoopDevConsoleIntegration.js (added)
7+
8+
games/
9+
Asteroids/
10+
index.js (modified)
11+
Breakout/
12+
main.js (modified)
513

614
tools/
7-
preview/
8-
generate-list-previews_updated.html (modified)
9-
preview_svg_executor_1600x900.html (modified)
10-
preview_svg_executor_games_enter.html (modified)
11-
runtimePreviewCapture.html (added)
15+
dev/
16+
checkBoundaryHardeningGuard.mjs (added)
1217

1318
docs/
1419
dev/
20+
roadmaps/
21+
MASTER_ROADMAP_HIGH_LEVEL.md (modified: Track B status markers only)
1522
reports/
16-
change_summary.txt (updated)
17-
validation_checklist.txt (updated)
18-
file_tree.txt (updated)
19-
23+
BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT_report.md (added)
24+
change_summary.txt (updated)
25+
validation_checklist.txt (updated)
26+
file_tree.txt (updated)

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,44 @@
1-
BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT - Validation Checklist
1+
BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT - Validation Checklist
22
Date: 2026-04-17
33

4-
[PASS] Syntax validation
5-
Command:
6-
- node --check scripts/generate-runtime-sample-previews.mjs
7-
Result:
8-
- Exit 0
4+
[PASS] Build input read
5+
- docs/pr/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT.md
96

10-
[PASS] Output-path contract verification (targeted file assertions)
7+
[PASS] Targeted boundary scan (pre-fix)
118
Command:
12-
- python inline assertion across:
13-
- tools/preview/generate-list-previews_updated.html
14-
- tools/preview/preview_svg_executor_1600x900.html
15-
- tools/preview/preview_svg_executor_games_enter.html
16-
- scripts/generate-runtime-sample-previews.mjs
9+
- node tools/dev/checkBoundaryHardeningGuard.mjs
1710
Result:
18-
- html default value="assets/images": expected 3, actual 3
19-
- html fallback || "assets/images": expected 3, actual 3
20-
- html stale default value="assets": expected 0, actual 0
21-
- html stale fallback || "assets": expected 0, actual 0
22-
- script path includes 'assets', 'images', 'preview.svg': expected 1, actual 1
23-
- script stale path 'assets', 'preview.svg': expected 0, actual 0
24-
- OVERALL PASS
11+
- scanned files: 712
12+
- violations: 2
13+
- games/breakout/main.js -> ../../tools/dev/devConsoleIntegration.js
14+
- games/Asteroids/index.js -> ../../tools/dev/devConsoleIntegration.js
15+
16+
[PASS] Boundary hardening implementation applied
17+
- Added boundary guard script
18+
- Removed games -> tools coupling in the two violating files
19+
- Added boundary-safe shared no-op integration default
2520

26-
[PASS] Canonical phase-hyphen sample directory contract check
21+
[PASS] Targeted boundary scan (post-fix)
2722
Command:
28-
- Python scan over samples/ for phase directories matching ^phase-\d{2}$ and per-sample index.html presence
23+
- node tools/dev/checkBoundaryHardeningGuard.mjs
2924
Result:
30-
- PHASE_DIR_COUNT=19
31-
- MISSING_INDEX_COUNT=0
25+
- scanned files: 713
26+
- violations: 0
3227

33-
Validation conclusion
34-
- Preview tooling now targets image output under assets/images/preview.svg.
35-
- Preview sample path resolution remains aligned to phase-hyphen contract.
28+
[PASS] Focused regression checks
29+
Commands:
30+
- node --input-type=module -e "... import('./tests/games/AsteroidsValidation.test.mjs') ..."
31+
- node --input-type=module -e "... import('./tests/games/BreakoutValidation.test.mjs') ..."
32+
- node --input-type=module -e "... import('./tests/tools/ToolBoundaryEnforcement.test.mjs') ..."
33+
Results:
34+
- PASS AsteroidsValidation
35+
- PASS BreakoutValidation
36+
- PASS ToolBoundaryEnforcement
37+
38+
[PASS] Roadmap status-only update
39+
- Updated Level 18 Track B markers only in place.
40+
- No roadmap text rewrite.
3641

42+
Validation conclusion
43+
- Cross-layer leakage identified and removed in scoped targets.
44+
- Dependency-direction rules are now enforced by a concrete guard and validated clean.

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -728,10 +728,10 @@
728728
- [ ] remove sample-specific logic from engine paths
729729

730730
### Track B � Boundary Hardening
731-
- [.] enforce engine vs shared vs game vs tool boundaries
732-
- [.] eliminate cross-layer leakage
733-
- [.] validate dependency direction rules across repo
734-
- [ ] remove accidental coupling
731+
- [x] enforce engine vs shared vs game vs tool boundaries
732+
- [x] eliminate cross-layer leakage
733+
- [x] validate dependency direction rules across repo
734+
- [x] remove accidental coupling
735735

736736
### Track C � Contract Stabilization
737737
- [.] finalize engine public APIs

‎docs/pr/BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# BUILD_PR_LEVEL_18_2_BOUNDARY_HARDENING_ENFORCEMENT
2+
3+
## Purpose
4+
Advance Level 18 Track B by enforcing engine vs shared vs game vs tool boundaries.
5+
6+
## Scope
7+
- one PR purpose only
8+
- docs-only bundle
9+
- no implementation authored by ChatGPT
10+
- no broad cleanup outside exact boundary hardening work
11+
12+
## Codex Responsibilities
13+
- inspect boundary crossings across engine/shared/games/tools
14+
- identify cross-layer leakage and dependency-direction violations
15+
- remove or relocate accidental coupling where required
16+
- re-validate boundary rules after changes
17+
18+
## Acceptance
19+
- engine vs shared vs game vs tool boundaries are enforced
20+
- cross-layer leakage is reduced or removed for this PR scope
21+
- dependency-direction validation report is produced

‎games/Asteroids/index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import Engine from "../../src/engine/core/Engine.js";
66
import { InputService } from "../../src/engine/input/index.js";
77
import { Theme, ThemeTokens } from "../../src/engine/theme/index.js";
88
import { resolveDebugConfig } from "../../src/shared/utils/debugConfigUtils.js";
9-
import { createSampleGameDevConsoleIntegration } from "../../tools/dev/devConsoleIntegration.js";
9+
import { createNoopDevConsoleIntegration } from "../../src/shared/utils/createNoopDevConsoleIntegration.js";
1010
import AsteroidsGameScene from "./game/AsteroidsGameScene.js";
1111

1212
export const asteroidFlow = Object.freeze({
@@ -92,7 +92,7 @@ export function bootAsteroidsNew({
9292
EngineClass = Engine,
9393
InputServiceClass = InputService,
9494
SceneClass = AsteroidsGameScene,
95-
createDevConsoleIntegration = createSampleGameDevConsoleIntegration
95+
createDevConsoleIntegration = createNoopDevConsoleIntegration
9696
} = {}) {
9797
let stage = "entered";
9898
traceBoot(stage);

‎games/breakout/main.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import {
1515
isLocalDebugEnvironment,
1616
resolveDebugConfig,
1717
} from '../../src/shared/utils/debugConfigUtils.js';
18-
import { createSampleGameDevConsoleIntegration } from '../../tools/dev/devConsoleIntegration.js';
18+
import { createNoopDevConsoleIntegration } from '../../src/shared/utils/createNoopDevConsoleIntegration.js';
1919
import BreakoutScene from './game/BreakoutScene.js';
2020

2121
const theme = new Theme(ThemeTokens);
@@ -92,7 +92,7 @@ export function bootBreakout({
9292
EngineClass = Engine,
9393
InputServiceClass = InputService,
9494
SceneClass = BreakoutScene,
95-
createDevConsoleIntegration = createSampleGameDevConsoleIntegration,
95+
createDevConsoleIntegration = createNoopDevConsoleIntegration,
9696
} = {}) {
9797
if (!documentRef) {
9898
return null;

0 commit comments

Comments
 (0)