Skip to content

Commit f1492b2

Browse files
author
DavidQ
committed
Execute runtime lifecycle validation for Level 19 Track B.
BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION - validate boot/run/shutdown lifecycle - validate hot reload/reset flows - validate error handling paths - validate long-running stability - update roadmap only for execution-backed results
1 parent 31a0525 commit f1492b2

11 files changed

Lines changed: 585 additions & 20 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 43 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,51 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
1. Run:
6-
npm test
7-
node ./scripts/run-node-tests.mjs
8-
npm run test:launch-smoke
5+
1. Open the roadmap at:
6+
docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
97

10-
2. If all pass:
11-
update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
12-
set remaining Level 19 [.] to [x]
8+
2. Execute the smallest real PR needed to complete Level 19 Track B:
9+
- validate boot -> run -> shutdown lifecycle
10+
- validate hot reload / reset flows
11+
- validate error handling paths
12+
- validate long-running stability
1313

14-
3. If any fail:
15-
write docs/dev/reports/LEVEL_19_REVALIDATION_FAILURES.md
14+
3. Search only where needed to find the existing lifecycle/runtime validation surfaces:
15+
- tests/
16+
- scripts/
17+
- launch smoke / runtime smoke helpers
18+
- engine runtime boot/reset/shutdown entry points actually used by samples/games/tools
1619

17-
4. Package:
18-
<project folder>/tmp/BUILD_PR_LEVEL_19_12_REVALIDATE_AND_PROMOTE.zip
20+
4. Implement the minimum validation-backed changes required:
21+
- add/fix focused tests or validation harnesses
22+
- add tiny runtime lifecycle fixes only if required to make validation deterministic
23+
- do not create new features
24+
- do not perform broad repo cleanup
25+
26+
5. Produce reports:
27+
- docs/dev/reports/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION_summary.md
28+
- docs/dev/reports/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION_coverage.md
29+
- docs/dev/reports/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION_results.md
30+
31+
6. In the reports, explicitly record:
32+
- which lifecycle paths were exercised
33+
- which commands were run
34+
- pass/fail results
35+
- any remaining bounded caveats
36+
37+
7. Update the roadmap only for Track B items proven by this PR:
38+
- [x] validate boot -> run -> shutdown lifecycle
39+
- [x] validate hot reload / reset flows
40+
- [x] validate error handling paths
41+
- [x] validate long-running stability
42+
Only set to [x] if actually validated by execution in this PR.
43+
44+
8. Package the repo-structured ZIP to:
45+
<project folder>/tmp/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION.zip
1946

2047
CONSTRAINTS:
21-
- No code changes
22-
- Status-only update
48+
- one PR purpose only
49+
- smallest scoped valid change
50+
- no vague wording
51+
- no repo-wide scanning unless required
52+
- no roadmap-only promotion without executed validation

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1-
Re-validate and conditionally promote Level 19 to complete
1+
Execute runtime lifecycle validation for Level 19 Track B.
22

3-
BUILD_PR_LEVEL_19_12_REVALIDATE_AND_PROMOTE
3+
BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION
4+
- validate boot/run/shutdown lifecycle
5+
- validate hot reload/reset flows
6+
- validate error handling paths
7+
- validate long-running stability
8+
- update roadmap only for execution-backed results

‎docs/dev/reports/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION_coverage.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION Coverage
2+
3+
## Lifecycle Paths Exercised
4+
5+
1. Boot -> Run -> Shutdown lifecycle
6+
- Surface: `src/engine/core/Engine.js`
7+
- Validation: `tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs`
8+
- Evidence:
9+
- `start()` attaches input/audio/fullscreen
10+
- runtime tick loop executes update/render + metrics recording
11+
- `stop()` detaches input/audio/fullscreen
12+
13+
2. Hot reload / reset flows
14+
- Surfaces:
15+
- `src/engine/core/Engine.js` scene transitions and restart reset points
16+
- `tests/tools/RuntimeSceneLoaderHotReload.test.mjs` (existing tool/runtime reload path, executed in suite)
17+
- Validation:
18+
- `tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs` verifies scene hot-swap and restart reset behavior (`frameClock.reset` / `fixedTicker.reset` per restart)
19+
- existing `RuntimeSceneLoaderHotReload` suite executed via `npm test` and `node ./scripts/run-node-tests.mjs`
20+
21+
3. Error handling paths
22+
- Surface: `src/engine/core/Engine.js`
23+
- Validation: `tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs`
24+
- Evidence:
25+
- `setCamera3D` hook exception is isolated and logged via `logger.warn`
26+
- `step3DPhysics` hook exception is isolated and logged via `logger.warn`
27+
- runtime update loop continues after hook failure
28+
29+
4. Long-running stability
30+
- Surfaces:
31+
- deterministic engine tick loop under repeated execution
32+
- cross-entry runtime stability through smoke validation of games/samples/tools
33+
- Validation:
34+
- `tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs` executes 5,000 deterministic ticks with stable update+metrics counts
35+
- `tests/runtime/LaunchSmokeAllEntries.test.mjs` executes 271 entry launches (games/samples/tools)
36+
37+
## Command-Level Coverage Mapping
38+
- `npm test`
39+
- executes full node suite including `Phase19RuntimeLifecycleValidation` and `LaunchSmokeAllEntries`
40+
- `node ./scripts/run-node-tests.mjs`
41+
- executes explicit run() suite including lifecycle + launch smoke validations
42+
- `npm run test:launch-smoke`
43+
- now directly executes launch smoke harness after this PR’s direct-execution fix
44+
45+
## Remaining Bounded Caveats
46+
- Long-running stability is validated with deterministic high-iteration loops and full launch-smoke traversal, not multi-hour soak testing.
47+
- Error-path coverage is focused on runtime hook-isolation paths; no new feature-level error branches were introduced.

‎docs/dev/reports/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION_results.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION Results
2+
3+
## Commands Run
4+
1. `npm test`
5+
2. `node ./scripts/run-node-tests.mjs`
6+
3. `npm run test:launch-smoke`
7+
8+
## Pass/Fail Results
9+
- `npm test`: PASS
10+
- pretest shared extraction guard: PASS
11+
- explicit node run() tests: PASS (`135/135`)
12+
- launch smoke in-suite: PASS (`271/271`, failed entries: none)
13+
14+
- `node ./scripts/run-node-tests.mjs`: PASS
15+
- explicit node run() tests: PASS (`135/135`)
16+
- includes launch smoke run: PASS (`271/271`, failed entries: none)
17+
18+
- `npm run test:launch-smoke`: PASS
19+
- direct launch smoke run: PASS (`271/271`, failed entries: none)
20+
21+
## Lifecycle Validation Status (Track B)
22+
- `[x]` validate boot -> run -> shutdown lifecycle
23+
- `[x]` validate hot reload / reset flows
24+
- `[x]` validate error handling paths
25+
- `[x]` validate long-running stability
26+
27+
## Bounded Caveats
28+
- Stability evidence is execution-backed via deterministic iteration and full cross-entry smoke runs, but it is not a prolonged soak-duration benchmark.

‎docs/dev/reports/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION_summary.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION Summary
2+
3+
## PR Purpose
4+
Complete Level 19 Track B runtime lifecycle validation with the smallest scoped, validation-backed changes.
5+
6+
## Scope Executed
7+
- Added one focused runtime lifecycle validation test covering Track B lifecycle criteria.
8+
- Wired the new test into the existing Node test runner.
9+
- Fixed direct-execution behavior of the existing launch smoke harness so `npm run test:launch-smoke` actually executes validation.
10+
- Produced execution-backed reports and updated roadmap Track B markers only.
11+
12+
## Files Changed (Implementation)
13+
- `tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs` (new)
14+
- `tests/run-tests.mjs` (register new runtime lifecycle test)
15+
- `tests/runtime/LaunchSmokeAllEntries.test.mjs` (direct-execution guard to invoke `run()` when executed as script)
16+
17+
## Roadmap Update
18+
- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
19+
- Track B items promoted to `[x]` based on this PR's executed validation evidence:
20+
- validate boot -> run -> shutdown lifecycle
21+
- validate hot reload / reset flows
22+
- validate error handling paths
23+
- validate long-running stability
24+
25+
## Validation Outcome
26+
All requested validation commands passed:
27+
- `npm test`
28+
- `node ./scripts/run-node-tests.mjs`
29+
- `npm run test:launch-smoke`
30+
31+
See results and coverage reports for exact exercised paths and bounded caveats.

‎docs/dev/reports/launch_smoke_report.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Launch Smoke Report
22

3-
Generated: 2026-04-17T17:27:01.532Z
3+
Generated: 2026-04-17T18:01:07.109Z
44

55
Filters: games=true, samples=true, tools=true, sampleRange=all
66

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -798,10 +798,10 @@
798798
- [x] verify predictable system interaction
799799

800800
### Track B � Runtime Lifecycle Validation
801-
- [ ] validate boot ? run ? shutdown lifecycle
802-
- [ ] validate hot reload / reset flows
803-
- [ ] validate error handling paths
804-
- [ ] validate long-running stability
801+
- [x] validate boot ? run ? shutdown lifecycle
802+
- [x] validate hot reload / reset flows
803+
- [x] validate error handling paths
804+
- [x] validate long-running stability
805805

806806
### Track C � Performance & Scaling
807807
- [x] validate large scene performance

‎docs/pr/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION
2+
3+
## Purpose
4+
Execute the next real Level 19 completion PR by validating the runtime lifecycle lane.
5+
6+
## Roadmap Target
7+
Complete **19 / Track B — Runtime Lifecycle Validation**:
8+
9+
- [ ] validate boot → run → shutdown lifecycle
10+
- [ ] validate hot reload / reset flows
11+
- [ ] validate error handling paths
12+
- [ ] validate long-running stability
13+
14+
## Scope
15+
- one PR purpose only
16+
- execute lifecycle validation work
17+
- add only the smallest validation-backed changes needed
18+
- no feature creation
19+
- no broad cleanup
20+
- no unrelated roadmap promotion
21+
22+
## Required Execution
23+
1. Identify the smallest existing runtime entry points used by games/samples/tools.
24+
2. Validate and, if needed, add focused tests or harness coverage for:
25+
- boot → run → shutdown lifecycle
26+
- hot reload / reset flows
27+
- error handling paths
28+
- long-running stability
29+
3. Add reports showing what was exercised, what passed, and any bounded caveats.
30+
4. Update the roadmap only for Track B items that are actually proven by this PR.
31+
32+
## Suggested Implementation Boundaries
33+
Prefer changes in:
34+
- `tests/`
35+
- existing validation scripts/harnesses
36+
- narrowly scoped runtime lifecycle helpers if a tiny non-feature fix is required to make lifecycle validation deterministic
37+
38+
Avoid:
39+
- new capability work
40+
- large refactors
41+
- unrelated engine cleanup
42+
- roadmap-only advancement without execution evidence
43+
44+
## Validation
45+
Run as applicable:
46+
- `npm test`
47+
- `node ./scripts/run-node-tests.mjs`
48+
- `npm run test:launch-smoke`
49+
50+
If long-running stability needs a dedicated command, add and run the smallest repo-consistent validation path.
51+
52+
## Acceptance
53+
- lifecycle validation work is actually executed
54+
- Track B evidence is recorded in reports
55+
- roadmap advances only where execution proves completion
56+
- ZIP artifact produced at:
57+
`<project folder>/tmp/BUILD_PR_LEVEL_19_13_RUNTIME_LIFECYCLE_VALIDATION.zip`

‎tests/run-tests.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,7 @@ import { run as runProjectileLabModel } from './samples/ProjectileLabModel.test.
141141
import { run as runProjectileLabScene } from './samples/ProjectileLabScene.test.mjs';
142142
import './theme.test.js';
143143
import { run as runLaunchSmokeAllEntries } from './runtime/LaunchSmokeAllEntries.test.mjs';
144+
import { run as runPhase19RuntimeLifecycleValidation } from './runtime/Phase19RuntimeLifecycleValidation.test.mjs';
144145

145146
const tests = [
146147
['AIBehaviors', runAIBehaviors],
@@ -276,6 +277,7 @@ const tests = [
276277
['WorldGameStateSystem', runWorldGameStateSystem],
277278
['WorldGameStateAuthoritativeHandoff', runWorldGameStateAuthoritativeHandoff],
278279
['WorldGameStateAuthoritativeScore', runWorldGameStateAuthoritativeScore],
280+
['Phase19RuntimeLifecycleValidation', runPhase19RuntimeLifecycleValidation],
279281
['LaunchSmokeAllEntries', runLaunchSmokeAllEntries],
280282
];
281283

‎tests/runtime/LaunchSmokeAllEntries.test.mjs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -639,3 +639,10 @@ export async function run() {
639639
assert.equal(failures.length, 0, `Launch smoke failures detected: ${failures.map((x) => x.entry.label).join(', ')}`);
640640
}
641641

642+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
643+
run().catch((error) => {
644+
console.error(error);
645+
process.exitCode = 1;
646+
});
647+
}
648+

0 commit comments

Comments
 (0)