Skip to content

Commit 839b440

Browse files
author
DavidQ
committed
PLAN PR for runtime scene loader and hot reload docs-only follow-on. Defines scope, responsibilities, lifecycle boundaries, validation rules, deterministic reload ordering, and next BUILD_PR handoff.
1 parent b246d64 commit 839b440

8 files changed

Lines changed: 455 additions & 136 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 16 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,32 +3,24 @@ David Quesenberry
33
04/05/2026
44
codex_commands.md
55

6-
# CODEX COMMANDS
6+
# Codex Commands
77

8-
## MODEL
9-
GPT-5.4
8+
## Recommended model
9+
- MODEL: GPT-5.4
10+
- REASONING: high
1011

11-
## REASONING
12-
high
13-
14-
## COMMAND
15-
Create `APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS` as an implementation PR that applies the approved render pipeline contract for Tile Map Editor, Parallax Editor, Sprite Editor, and Vector Asset Studio.
12+
## Command
13+
Create APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD as the implementation PR for the approved runtime scene loader and hot reload contract.
1614

1715
Requirements:
18-
- Implement one shared runtime contract path for `toolbox.render.asset-document` and `toolbox.render.composition-document`
19-
- Add validation, normalization, deterministic render stage ordering, and structured errors
20-
- Lock tool-to-engine mappings exactly as documented
21-
- Add composition-driven mixed-scene assembly
22-
- Add focused automated tests for valid documents, invalid documents, stage ordering, and composition assembly
23-
- Keep changes surgical and architecture-safe
24-
- Do not move reusable logic into samples
25-
- Do not add implementation code to docs bundles
26-
- Do not perform unrelated refactors
16+
- follow PLAN_PR -> BUILD_PR -> APPLY_PR exactly
17+
- implement only what is defined in BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
18+
- keep changes surgical and architecture-safe
19+
- preserve locked public engine mappings
20+
- include deterministic load/reload ordering
21+
- include structured validation and error behavior
22+
- include focused tests for valid/invalid/reload-order/composition-reload paths
23+
- update docs/dev reports after validation
2724

28-
Required output artifacts:
29-
- Update repo files needed for implementation
30-
- Update `docs/dev/change_summary.txt`
31-
- Update `docs/dev/validation_checklist.txt`
32-
- Preserve file headers for all newly created files
33-
- Package the repo-structured delta ZIP to:
34-
- `<project folder>/tmp/APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS_delta.zip`
25+
Output zip path:
26+
- <project folder>/tmp/APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ David Quesenberry
33
04/05/2026
44
commit_comment.txt
55

6-
Apply render pipeline contract runtime for all four tools with validation, composition loading, deterministic ordering, and tests.
6+
docs: build runtime scene loader and hot reload contract bundle

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ David Quesenberry
33
04/05/2026
44
next_command.txt
55

6-
After Codex implementation and validation, proceed with runtime verification and targeted follow-up fixes only if required.
6+
APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD

‎docs/dev/change_summary.txt‎

Lines changed: 8 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -3,66 +3,11 @@ David Quesenberry
33
04/05/2026
44
change_summary.txt
55

6-
APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS summary
7-
8-
Implemented runtime contract path:
9-
- Added `tools/shared/renderPipelineContract.js` as the shared runtime contract seam for:
10-
- `toolbox.render.asset-document`
11-
- `toolbox.render.composition-document`
12-
13-
Implemented pipeline stages:
14-
- load
15-
- validate
16-
- normalize
17-
- resolve
18-
- compose
19-
- sequence
20-
- render
21-
22-
Implemented validation and normalization behavior:
23-
- Enforces contract envelope and version (`1.0.0`)
24-
- Enforces 2D coordinate space and pixel units
25-
- Enforces strict producer tool allowlist and locked mapping rules
26-
- Enforces asset/layer/item/entity schema requirements
27-
- Rejects invalid references, enums, ranges, duplicate IDs, and invalid paths
28-
- Uses explicit structured errors with stage, code, path, message, and details
29-
- Allows only limited explicit defaults (visible/opacity/metadata/items) through normalization
30-
31-
Implemented deterministic ordering:
32-
- Formal render bucket ordering by layer kind:
33-
- parallax
34-
- tilemap
35-
- sprite
36-
- vector
37-
- overlay
38-
- collision
39-
- guide
40-
- Stable tie-breaks by zIndex, source document order, source layer order, then id
41-
- Deterministic item ordering by item order, source item order, then id
42-
43-
Implemented composition-driven mixed-scene assembly:
44-
- Resolves composition references to asset documents through a shared document lookup
45-
- Validates referenced documents before composition
46-
- Merges scene assets with conflict detection for duplicate IDs with mismatched type/path
47-
- Applies runtime inclusion filtering (`gameplay`, optional `debug`, excludes `editor-only`)
48-
- Emits composed scene output with explicit tool-to-engine mappings attached
49-
50-
Tests added:
51-
- `tests/tools/RenderPipelineContractAll4Tools.test.mjs`
52-
- valid contract acceptance
53-
- invalid contract rejection
54-
- deterministic stage/layer/item ordering
55-
- composition assembly and missing-reference rejection
56-
57-
Test harness integration:
58-
- Updated `tests/run-tests.mjs` to include `RenderPipelineContractAll4Tools` run target
59-
60-
Docs/report updates required by apply:
61-
- Updated `docs/dev/change_summary.txt`
62-
- Updated `docs/dev/validation_checklist.txt`
63-
64-
Scope guardrails honored:
65-
- No unrelated refactors
66-
- No sample logic used as reusable runtime implementation
67-
- No implementation code added to docs bundles
68-
- Changes kept surgical and architecture-safe
6+
Summary:
7+
- Added docs-only BUILD bundle for runtime scene loader and hot reload
8+
- Defined formal responsibilities for SceneCompositionLoader and RuntimeSceneLoader
9+
- Defined deterministic hot reload lifecycle and stage ordering
10+
- Locked watcher bridge boundaries and public engine mappings
11+
- Added validation/error taxonomy and composition-driven reload rules
12+
- Added APPLY-focused test plan and manual validation targets
13+
- Updated command, commit, file tree, and next-command docs/dev artifacts

‎docs/dev/file_tree.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ David Quesenberry
33
04/05/2026
44
file_tree.txt
55

6-
docs/pr/APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS.md
6+
docs/pr/BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md
77
docs/dev/codex_commands.md
88
docs/dev/commit_comment.txt
99
docs/dev/change_summary.txt

‎docs/dev/validation_checklist.txt‎

Lines changed: 13 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -3,49 +3,16 @@ David Quesenberry
33
04/05/2026
44
validation_checklist.txt
55

6-
APPLY_PR_RENDER_PIPELINE_CONTRACT_ALL_4_TOOLS validation checklist
7-
8-
Contract/runtime path
9-
[x] Shared runtime contract path implemented for `toolbox.render.asset-document`
10-
[x] Shared runtime contract path implemented for `toolbox.render.composition-document`
11-
[x] One formal staged pipeline exists: load/validate/normalize/resolve/compose/sequence/render
12-
13-
Validation and errors
14-
[x] Contract envelope/version validation implemented
15-
[x] Producer tool allowlist and locked mapping checks implemented
16-
[x] Asset/layer/item/entity schema validation implemented
17-
[x] Duplicate ID and reference validation implemented
18-
[x] Invalid contracts rejected without silent repair
19-
[x] Structured error shape implemented (`stage`, `code`, `path`, `message`, `details`)
20-
21-
Deterministic sequencing and composition
22-
[x] Deterministic render bucket ordering implemented
23-
[x] Stable tie-break ordering implemented
24-
[x] Composition manifest references are validated and resolved
25-
[x] Mixed-scene composition assembly implemented
26-
27-
Tool mapping lock
28-
[x] Tile Map Editor mapping rules enforced
29-
[x] Parallax Editor mapping rules enforced
30-
[x] Sprite Editor mapping rules enforced
31-
[x] Vector Asset Studio mapping rules enforced
32-
33-
Automated tests
34-
[x] Focused test added: `tests/tools/RenderPipelineContractAll4Tools.test.mjs`
35-
[x] Valid-document acceptance test passes
36-
[x] Invalid-document rejection test passes
37-
[x] Stage/layer/item ordering test passes
38-
[x] Composition assembly test passes
39-
[x] Missing composition reference rejection test passes
40-
[x] Test included in `tests/run-tests.mjs`
41-
42-
Execution evidence
43-
[x] `node --check tools/shared/renderPipelineContract.js`
44-
[x] `node --check tests/tools/RenderPipelineContractAll4Tools.test.mjs`
45-
[x] `node --check tests/run-tests.mjs`
46-
[x] Targeted test run passed (`PASS RenderPipelineContractAll4Tools`)
47-
48-
Scope safety
49-
[x] No unrelated runtime/tool refactor performed
50-
[x] No reusable logic moved into samples
51-
[x] No docs bundle implementation leakage
6+
BUILD PR validation checklist
7+
[x] Bundle is docs-only
8+
[x] No implementation code included
9+
[x] Workflow preserved: PLAN_PR -> BUILD_PR -> APPLY_PR
10+
[x] Runtime scene loader responsibilities are explicit
11+
[x] Hot reload lifecycle and deterministic order are documented
12+
[x] Watcher bridge boundaries are explicit
13+
[x] Public engine mappings are locked to public entry paths
14+
[x] Validation and structured error taxonomy are documented
15+
[x] Composition-driven reload rules are documented
16+
[x] Test plan is defined for APPLY implementation
17+
[x] Command and commit artifacts are under docs/dev
18+
[x] Repo-relative bundle structure is preserved

‎docs/pr/BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md
5+
6+
# BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
7+
8+
## Purpose
9+
Create a docs-only BUILD PR that defines the implementation contract for runtime scene loading and hot reload, using the already approved cross-tool render pipeline contract as the upstream dependency.
10+
11+
Upstream dependency (already approved):
12+
- `toolbox.render.asset-document`
13+
- `toolbox.render.composition-document`
14+
- producer mappings for Tile Map Editor, Parallax Editor, Sprite Editor, Vector Asset Studio
15+
16+
This BUILD PR adds no implementation code.
17+
18+
## Scope
19+
In scope:
20+
- formal runtime scene loader responsibilities
21+
- hot reload lifecycle and deterministic reload order
22+
- watcher bridge boundaries
23+
- public engine mappings only
24+
- validation and structured error taxonomy
25+
- composition-driven reload rules
26+
- focused test plan and validation checklist
27+
28+
Out of scope:
29+
- engine core API redesign
30+
- tool payload redesign
31+
- sample-specific runtime ownership
32+
- unrelated refactors
33+
- implementation code
34+
35+
## Runtime Scene Loader Responsibilities
36+
37+
### SceneCompositionLoader
38+
Responsibilities:
39+
- accept a composition document (`toolbox.render.composition-document`)
40+
- validate composition envelope, version, producer identity, and references
41+
- resolve referenced asset documents (`toolbox.render.asset-document`)
42+
- normalize scene package structure for runtime consumption
43+
- return structured errors on failure
44+
45+
Non-responsibilities:
46+
- no schema migration
47+
- no silent mutation of invalid input
48+
- no direct rendering
49+
50+
### RuntimeSceneLoader
51+
Responsibilities:
52+
- load normalized scene package into runtime through public engine entry points
53+
- initialize scene domains in deterministic stage order
54+
- track domain-level handles for targeted reload/dispose
55+
- preserve domain isolation (reload only affected domain unless full-recompose is required)
56+
57+
Non-responsibilities:
58+
- no file watching
59+
- no editor/tool UI ownership
60+
- no sample-only private integration paths
61+
62+
## Hot Reload Lifecycle
63+
Hot reload must be optional in development and use deterministic ordering that matches initial load.
64+
65+
Lifecycle:
66+
1. WatcherBridge receives a file-change event.
67+
2. HotReloadCoordinator classifies changed artifact domain(s).
68+
3. Validate changed document(s) against locked contract schema.
69+
4. Resolve composition impact (targeted domain reload vs full recompose).
70+
5. Perform staged reload in deterministic order.
71+
6. Swap runtime handles atomically for affected domain(s).
72+
7. Dispose retired handles.
73+
8. Emit structured success/failure event.
74+
9. On failure, preserve last known-good runtime state.
75+
76+
Deterministic reload order:
77+
1. composition metadata
78+
2. parallax domain
79+
3. tilemap domain
80+
4. sprite/entity domain
81+
5. vector/overlay domain
82+
6. ready signal
83+
84+
## Watcher Bridge Boundaries
85+
Responsibilities:
86+
- normalize external file-change events into runtime-safe event payloads
87+
- provide only path + event-type + timestamp + optional hash metadata
88+
- remain optional and disabled outside development mode
89+
90+
Boundaries:
91+
- no schema validation ownership
92+
- no composition assembly ownership
93+
- no direct runtime scene mutation
94+
- no engine core lifecycle ownership
95+
96+
## Public Engine Mappings (Locked)
97+
Only public mappings are allowed:
98+
- composition doc -> `SceneCompositionLoader`
99+
- normalized scene package -> `RuntimeSceneLoader`
100+
- parallax contract payload -> approved parallax runtime entry path
101+
- tilemap contract payload -> approved tilemap runtime entry path
102+
- sprite contract payload -> approved sprite/entity runtime entry path
103+
- vector contract payload -> approved vector runtime entry path
104+
- lifecycle wiring -> scene init/update/render/dispose public flow
105+
106+
No internal/private engine bypass is allowed in this PR.
107+
108+
## Validation and Error Taxonomy
109+
Validation levels:
110+
- composition envelope validation
111+
- referenced asset-document validation
112+
- domain-specific payload validation
113+
- cross-reference validation (asset IDs, layer refs, domain refs)
114+
115+
Structured error envelope:
116+
- `level`: `error` | `warning`
117+
- `stage`: `load` | `validate` | `resolve` | `compose` | `reload` | `dispose`
118+
- `code`: deterministic machine-readable code
119+
- `path`: document path or domain path
120+
- `message`: human-readable summary
121+
- `details`: stable object payload
122+
123+
Required non-silent rejection behavior:
124+
- invalid version -> reject
125+
- invalid schema -> reject
126+
- missing required reference -> reject
127+
- unsupported producer mapping -> reject
128+
- reload validation failure -> reject reload, keep last known-good state
129+
130+
## Composition-Driven Reload Rules
131+
Targeted reload rules:
132+
- parallax-only change -> reload parallax domain only
133+
- tilemap-only change -> reload tilemap + dependent collision domain only
134+
- sprite-only change -> reload sprite/entity domain only
135+
- vector-only change -> reload vector/overlay domain only
136+
137+
Full recompose triggers:
138+
- composition manifest changed
139+
- layer/domain ordering changed
140+
- document-level metadata affecting scene assembly changed
141+
142+
All reload decisions must be deterministic and recorded in structured events.
143+
144+
## Test Plan
145+
Automated tests to implement in APPLY PR:
146+
- valid composition load succeeds
147+
- unsupported version fails fast
148+
- missing reference fails with structured error
149+
- deterministic stage ordering on initial load
150+
- deterministic stage ordering on reload
151+
- targeted parallax reload
152+
- targeted tilemap reload
153+
- targeted sprite reload
154+
- targeted vector reload
155+
- composition-change full recompose
156+
- failed reload preserves last known-good scene state
157+
- replaced handles are disposed
158+
159+
Manual validation checklist (APPLY PR):
160+
- runtime scene loads from composition document with all 4 producers
161+
- development watcher can trigger reload workflow
162+
- invalid changed document is rejected without corrupting runtime state
163+
- deterministic order is consistent across repeated reload cycles
164+
- production mode disables watcher bridge cleanly
165+
166+
## Deliverables For This BUILD PR (Docs-Only)
167+
- `docs/pr/BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md`
168+
- `docs/dev/codex_commands.md`
169+
- `docs/dev/commit_comment.txt`
170+
- `docs/dev/change_summary.txt`
171+
- `docs/dev/validation_checklist.txt`
172+
- `docs/dev/file_tree.txt`
173+
- `docs/dev/next_command.txt`
174+
175+
## Packaging
176+
Output delta zip path:
177+
- `<project folder>/tmp/BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD_delta.zip`
178+
179+
Zip content constraints:
180+
- repo-relative structure preserved
181+
- docs-only files for this PR purpose
182+
- no implementation files
183+
184+
## Commit Comment
185+
`docs: build runtime scene loader and hot reload contract bundle`
186+
187+
## Next Command
188+
`APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD`

0 commit comments

Comments
 (0)