Skip to content

Commit be5872d

Browse files
author
DavidQ
committed
Add tool request/fetch/load diagnostics for sample data-flow debugging - PR 10.6G
1 parent f5233e3 commit be5872d

29 files changed

Lines changed: 1428 additions & 164 deletions

File tree

‎docs/dev/codex_commands.md‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,12 @@
11
# Codex Commands
22

3-
Model: GPT-5.4-codex
4-
Reasoning: high
3+
## Model
4+
GPT-5.4
55

6-
Run from repo root:
6+
## Reasoning
7+
high
78

9+
## Command
810
```powershell
9-
codex exec --model gpt-5.4-codex --reasoning high --file docs/pr/BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION.md
10-
```
11-
12-
Codex must produce:
13-
14-
```text
15-
tmp/BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION.zip
11+
codex --model gpt-5.4 --reasoning high "Execute BUILD_PR_LEVEL_10_6G_TOOL_INPUT_FETCH_LOAD_DIAGNOSTICS exactly. Add temporary structured diagnostics for tool request/fetch/load boundaries across active sample-loaded tools. Do not change contracts, do not add fallbacks, do not hardcode paths, and do not normalize palette data in this PR. Run npm run test:launch-smoke:games and npm run test:sample-standalone:data-flow. Create the report at docs/dev/reports/level_10_6G_tool_input_fetch_load_diagnostics_report.md. Update only roadmap status markers if execution-backed. Return a repo-structured ZIP at tmp/BUILD_PR_LEVEL_10_6G_TOOL_INPUT_FETCH_LOAD_DIAGNOSTICS.zip."
1612
```

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Normalize all sample palettes to canonical SSoT and remove palette-browser duplicates - PR 10.6F
1+
Add tool request/fetch/load diagnostics for sample data-flow debugging - PR 10.6G

‎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-27T17:16:29.337Z
3+
Generated: 2026-04-27T17:57:47.633Z
44

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

‎docs/dev/reports/level_10_6G_tool_input_fetch_load_diagnostics_report.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Level 10.6G Tool Input Fetch Load Diagnostics Report
2+
3+
## Files changed
4+
5+
- `tools/shared/toolLoadDiagnostics.js`
6+
- `tools/3D Asset Viewer/main.js`
7+
- `tools/3D Camera Path Editor/main.js`
8+
- `tools/3D JSON Payload Normalizer/main.js`
9+
- `tools/Asset Browser/main.js`
10+
- `tools/Asset Pipeline Tool/main.js`
11+
- `tools/Palette Browser/main.js`
12+
- `tools/Parallax Scene Studio/main.js`
13+
- `tools/Performance Profiler/main.js`
14+
- `tools/Physics Sandbox/main.js`
15+
- `tools/Replay Visualizer/main.js`
16+
- `tools/Sprite Editor/modules/spriteEditorApp.js`
17+
- `tools/State Inspector/main.js`
18+
- `tools/Tilemap Studio/main.js`
19+
- `tools/Tile Model Converter/main.js`
20+
- `tools/Vector Asset Studio/main.js`
21+
- `tools/Vector Map Editor/editor/VectorMapEditorApp.js`
22+
- `docs/dev/reports/level_10_6G_tool_input_fetch_load_diagnostics_report.md`
23+
24+
## Logging prefixes added
25+
26+
- `[tool-load:request]`
27+
- `[tool-load:fetch]`
28+
- `[tool-load:loaded]`
29+
- `[tool-load:warning]`
30+
31+
All active sample-loaded tool loader paths now emit structured diagnostics at request/fetch/load boundaries.
32+
33+
## Test results
34+
35+
1. `npm run test:launch-smoke:games`
36+
- Result: PASS
37+
- Summary: PASS=12, FAIL=0, TOTAL=12
38+
2. `npm run test:sample-standalone:data-flow`
39+
- Result: PASS
40+
- Summary: `schemaFailures=[]`, `contractFailures=[]`, `roundtripPathFailures=[]`, `genericFailures=[]`
41+
42+
## Sample 0219 observed diagnostics summary
43+
44+
Sample launched:
45+
46+
- Tool: `sprite-editor`
47+
- URL query carried `sampleId=0219` and `samplePresetPath=/samples/phase-02/0219/sample.0219.sprite-editor.json`
48+
49+
Observed console diagnostic prefixes for launch:
50+
51+
- `[tool-load:request]` observed
52+
- `[tool-load:fetch]` observed (attempt + response)
53+
- `[tool-load:loaded]` observed
54+
55+
Observed loaded summary excerpt:
56+
57+
- `loaded.type = "object"`
58+
- `loaded.shape = "Object(4 keys)"`
59+
- `loaded.sprite.present = true`
60+
- `loaded.sprite.source = "root.config.spriteProject"`
61+
- `loaded.sprite.frameCount = 4`
62+
63+
Observed warning for this sample/tool path:
64+
65+
- `[tool-load:warning] error="Preset payload did not include a sprite project."`
66+
67+
Diagnostics are now explicit about request/fetch/load boundaries and the warning condition in this launch path.
68+
69+
## Palette fetch/load visibility
70+
71+
Palette visibility is explicit in diagnostics logs.
72+
73+
Observed on `sample 0313` (`palette-browser`):
74+
75+
- request log includes `samplePresetPath=/samples/phase-03/0313/sample.0313.palette.json`
76+
- fetch logs show attempt + HTTP response `status=200`, `ok=true`
77+
- loaded summary includes:
78+
- `loaded.palette.present = true`
79+
- `loaded.palette.source = "root"`
80+
- `loaded.palette.swatchCount = 5`
81+
82+
This makes palette request/fetch/load state directly inspectable from console logs.
83+
84+
## Remaining blocker for palette SSoT normalization
85+
86+
No SSoT contract normalization was performed in this PR by design (diagnostics-only scope).
87+
Any remaining palette SSoT issues are outside this PR and require follow-up normalization/build scope changes rather than diagnostics changes.
88+
89+
## Roadmap status marker updates
90+
91+
No roadmap marker update was applied because no explicit `10.6G` status marker entry was found in `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md`.

‎docs/dev/reports/level_10_6f_all_sample_palette_ssot_normalization_report.md‎

Lines changed: 53 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,58 @@
1-
# LEVEL 10.6F Report Template
1+
# level_10_6f_all_sample_palette_ssot_normalization_report
22

3-
Codex must replace this template with real execution output.
3+
## Build
4+
- BUILD: `BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION`
5+
- Generated: 2026-04-27T17:29:56.538Z
46

5-
Required summary:
7+
## Codex Targeted Discovery (Executed)
8+
- `Get-ChildItem .\samples -Recurse -Filter "*.palette-browser.json" | Select-Object -ExpandProperty FullName`
9+
- `Get-ChildItem .\samples -Recurse -Filter "*.palette.json" | Select-Object -ExpandProperty FullName`
10+
- `Select-String -Path .\samples\**\*.json -Pattern "palette-browser|palette.json|config.palette|paletteList" -List`
11+
- `Select-String -Path .\tests\**\*.mjs,.\samples\metadata\*.json -Pattern "palette-browser|palette.json|config.palette|paletteList" -List`
612

7-
- Palette browser wrapper files found:
8-
- Palette browser wrapper files removed:
9-
- Canonical palette files retained:
10-
- References updated:
11-
- Generic failure signals detected:
13+
## Required Counts
14+
Palette browser wrapper files found: 2
15+
Palette browser wrapper files removed: 2
16+
Canonical palette files retained: 20
17+
References updated: 2
18+
Generic failure signals detected: 0
1219

13-
Required validation:
20+
## Removed Wrapper Files
21+
- `samples/phase-02/0213/sample.0213.palette-browser.json`
22+
- `samples/phase-03/0308/sample.0308.palette-browser.json`
1423

15-
- npm run test:launch-smoke:games
16-
- npm run test:sample-standalone:data-flow
24+
## Updated References
25+
- `samples/metadata/samples.index.metadata.json:1559`
26+
- `samples/metadata/samples.index.metadata.json:2621`
27+
28+
## Sample Normalization Matrix
29+
| sample | removed palette-browser file | canonical palette file | updated references | validation result |
30+
|---|---|---|---|---|
31+
| 0213 | samples/phase-02/0213/sample.0213.palette-browser.json | samples/phase-02/0213/sample.0213.palette.json | samples/metadata/samples.index.metadata.json:1559 | data-flow PASS (summary: 13 swatches | source: engine/paletteList) |
32+
| 0308 | samples/phase-03/0308/sample.0308.palette-browser.json | samples/phase-03/0308/sample.0308.palette.json | samples/metadata/samples.index.metadata.json:2621 | data-flow PASS (summary: 5 swatches | source: generated-from-sample-colors) |
33+
| 0313 | already normalized in 10.6E (no wrapper file present before this BUILD) | samples/phase-03/0313/sample.0313.palette.json | none in this BUILD | data-flow PASS (summary: 5 swatches | source: generated-from-sample-colors) |
34+
35+
## Validation
36+
1. `npm run test:launch-smoke:games`
37+
- Result: PASS
38+
- summary: PASS=12 FAIL=0 TOTAL=12
39+
- Output artifact: `docs/dev/reports/level_10_6f_launch_smoke_games_output.txt`
40+
41+
2. `npm run test:sample-standalone:data-flow`
42+
- Result: PASS
43+
- generatedAt: `2026-04-27T17:29:15.928Z`
44+
- schemaFailures: 0
45+
- contractFailures: 0
46+
- roundtripPathFailures: 0
47+
- genericFailures: 0
48+
- Output artifact: `docs/dev/reports/level_10_6f_sample_standalone_data_flow_output.txt`
49+
50+
## Acceptance Check
51+
- No `samples/**/sample.*.palette-browser.json` files remain: PASS
52+
- No sample metadata points to wrapper palette-browser JSON files: PASS
53+
- Palette Browser uses canonical palette object through normalized runtime input path: PASS
54+
- Required tests pass: PASS
55+
- Report shows `Generic failure signals detected: 0`: PASS
56+
57+
## Notes
58+
- Attempted to invoke `codex exec` with `--model gpt-5.4-codex` directly as requested, but this local Codex account/runtime rejects that model for exec; BUILD execution was completed manually in-repo following the BUILD doc steps.

‎docs/dev/reports/level_10_6f_launch_smoke_games_output.txt‎

8.29 KB
Binary file not shown.

‎docs/dev/reports/level_10_6f_removed_palette_browser_files.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Files that must be absent after BUILD_PR_LEVEL_10_6F_ALL_SAMPLE_PALETTE_SSOT_NORMALIZATION
2+
samples/phase-02/0213/sample.0213.palette-browser.json
3+
samples/phase-03/0308/sample.0308.palette-browser.json
4+
samples/phase-03/0313/sample.0313.palette-browser.json

‎docs/dev/reports/level_10_6f_sample_standalone_data_flow_output.txt‎

35.7 KB
Binary file not shown.

‎docs/pr/BUILD_PR_LEVEL_10_6G_TOOL_INPUT_FETCH_LOAD_DIAGNOSTICS.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# BUILD_PR_LEVEL_10_6G_TOOL_INPUT_FETCH_LOAD_DIAGNOSTICS
2+
3+
## Purpose
4+
Add temporary diagnostics so every sample-loaded tool reports what it received, what it fetched, and what it loaded.
5+
6+
## Scope
7+
- Apply to tools launched from `samples/**` manifests.
8+
- Focus on sample data-flow diagnostics only.
9+
- Do not normalize palette data in this PR.
10+
- Do not introduce fallback data.
11+
- Do not hardcode sample paths.
12+
- Do not modify `start_of_day` folders.
13+
14+
## Required behavior
15+
Codex must add consistent debug logging at the tool boundary for each active tool loader path.
16+
17+
Each tool launch/load must log:
18+
19+
1. request received
20+
- tool id/name
21+
- sample path or manifest path provided by caller
22+
- requested config/data path if present
23+
- URL query params or request payload used to launch the tool
24+
25+
2. fetch attempted
26+
- each URL/path attempted
27+
- whether the path came from manifest, schema-normalized input, or tool input
28+
- HTTP status or fetch error
29+
30+
3. load completed
31+
- tool id/name
32+
- loaded data type/shape summary
33+
- top-level keys loaded
34+
- for palette-capable tools: whether palette was present, where it came from, swatch count
35+
- for sprite/editor tools: whether sprite data was present, where it came from, frame/count summary when cheap to compute
36+
- for replay/event tools: whether events array exists and event count
37+
38+
## Logging format
39+
Use stable, searchable console prefixes:
40+
41+
- `[tool-load:request]`
42+
- `[tool-load:fetch]`
43+
- `[tool-load:loaded]`
44+
- `[tool-load:warning]`
45+
46+
Use one structured object per log call. Do not stringify large payloads. Summarize only.
47+
48+
## Files to inspect first
49+
Codex must inspect and identify the actual active loader files before editing. Likely candidates include, but are not limited to:
50+
51+
- `tools/**/spriteEditorApp.js`
52+
- `tools/**/*.js`
53+
- `samples/**/*.html`
54+
- shared sample/tool launch helpers under `src/**` or `tools/**`
55+
56+
Do not repo-wide refactor. Locate the common tool/sample load path and add the smallest diagnostic hook possible. If there is no common hook, add equivalent minimal logging to each active tool loader touched by sample standalone data-flow tests.
57+
58+
## Acceptance checks
59+
Run:
60+
61+
```powershell
62+
npm run test:launch-smoke:games
63+
npm run test:sample-standalone:data-flow
64+
```
65+
66+
Then manually launch at least:
67+
68+
```text
69+
samples/phase-02/0219
70+
```
71+
72+
Open the tool from the sample and verify the browser console shows:
73+
74+
```text
75+
[tool-load:request]
76+
[tool-load:fetch]
77+
[tool-load:loaded]
78+
```
79+
80+
For the current issue, the log must make it obvious whether palette was:
81+
82+
- requested and fetched
83+
- requested but fetch failed
84+
- never requested
85+
- loaded from the wrong wrapper
86+
- absent from normalized tool input
87+
88+
## Report
89+
Write findings to:
90+
91+
```text
92+
docs/dev/reports/level_10_6G_tool_input_fetch_load_diagnostics_report.md
93+
```
94+
95+
Report must include:
96+
97+
- files changed
98+
- exact logging prefixes added
99+
- test command results
100+
- sample 0219 observed diagnostics summary
101+
- whether palette fetch/load is now visible in logs
102+
- any remaining blocker for palette SSoT normalization
103+
104+
## Roadmap
105+
Update only status markers in:
106+
107+
```text
108+
docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md
109+
```
110+
111+
Do not rewrite or delete roadmap content.

‎samples/metadata/samples.index.metadata.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1556,7 +1556,7 @@
15561556
"roundtripToolPresets": [
15571557
{
15581558
"toolId": "palette-browser",
1559-
"presetPath": "/samples/phase-02/0213/sample.0213.palette-browser.json"
1559+
"presetPath": "/samples/phase-02/0213/sample.0213.palette.json"
15601560
}
15611561
]
15621562
},
@@ -2618,7 +2618,7 @@
26182618
"roundtripToolPresets": [
26192619
{
26202620
"toolId": "palette-browser",
2621-
"presetPath": "/samples/phase-03/0308/sample.0308.palette-browser.json"
2621+
"presetPath": "/samples/phase-03/0308/sample.0308.palette.json"
26222622
}
26232623
]
26242624
},

0 commit comments

Comments
 (0)