Skip to content

Commit 93bd961

Browse files
ToolboxAidToolboxAid
committed
build(asset-validation): add enforced project asset validation engine
1 parent 1fe3b3e commit 93bd961

15 files changed

Lines changed: 1053 additions & 69 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,29 @@ MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
Execute this atomic Level 9 package in order.
5+
Execute this atomic Level 10 package in order.
66

77
Step 1:
8-
Treat docs/pr/PLAN_PR_ASSET_DEPENDENCY_GRAPH.md as the governing architecture contract.
8+
Treat docs/pr/PLAN_PR_ASSET_VALIDATION_ENGINE.md as the governing architecture contract.
99

1010
Step 2:
11-
Create BUILD_PR_ASSET_DEPENDENCY_GRAPH.
11+
Create BUILD_PR_ASSET_VALIDATION_ENGINE.
1212

1313
BUILD requirements:
14-
- Implement a minimal additive project-level asset dependency graph
15-
- Preserve registry as source of truth
16-
- Use stable IDs and deterministic edge generation
17-
- Keep backward compatibility for legacy projects with no graph data
18-
- Surface missing targets/orphaned assets as validation findings rather than hard failures
19-
- Support Sprite Editor, Tile Map Editor, and Parallax Editor local graph contribution
14+
- Implement a shared enforced project-level asset validation engine
15+
- Validate registry + dependency graph correctness
16+
- Use deterministic finding generation and stable result structure
17+
- Block guarded save/package/export actions when blocking findings exist
18+
- Preserve remediation workflows for invalid and legacy projects
19+
- Support Sprite Editor, Tile Map Editor, and Parallax Editor validation consumption
20+
- Keep registry as source of truth
2021
- Do not modify engine core APIs
2122

2223
Step 3:
23-
Validate BUILD against docs/pr/BUILD_PR_ASSET_DEPENDENCY_GRAPH.md.
24+
Validate BUILD against docs/pr/BUILD_PR_ASSET_VALIDATION_ENGINE.md.
2425

2526
Step 4:
26-
Treat docs/pr/APPLY_PR_ASSET_DEPENDENCY_GRAPH.md as the acceptance boundary and package results.
27+
Treat docs/pr/APPLY_PR_ASSET_VALIDATION_ENGINE.md as the acceptance boundary and package results.
2728

2829
Package:
29-
HTML-JavaScript-Gaming/tmp/LEVEL_9_ASSET_DEPENDENCY_GRAPH_ATOMIC_PACKAGE_delta.zip
30+
HTML-JavaScript-Gaming/tmp/LEVEL_10_ASSET_VALIDATION_ENGINE_ENFORCED_ATOMIC_PACKAGE_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
build(asset-graph): add additive project asset dependency graph
1+
build(asset-validation): add enforced project asset validation engine

‎docs/dev/change_summary.txt‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
Completed BUILD_PR_ASSET_DEPENDENCY_GRAPH as an additive project-level asset graph slice.
2-
3-
Summary:
4-
- Added shared dependency graph generation in `tools/shared/projectAssetRegistry.js` using stable node IDs, deterministic edge ordering, and non-blocking validation findings.
5-
- Updated Sprite Editor, Tile Map Editor, and Parallax Editor save flows to persist `project.assetDependencyGraph` snapshots without changing engine core APIs.
6-
- Preserved legacy compatibility by keeping graph persistence additive and leaving load flows tolerant of missing graph data.
1+
Single atomic Level 10 package containing PLAN, BUILD, and APPLY documentation for an enforced
2+
project-level asset validation engine. This bundle is docs-first and Codex-ready, with implementation
3+
ownership delegated to Codex.

‎docs/dev/file_tree.txt‎

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,8 @@
1-
LEVEL_9_ASSET_DEPENDENCY_GRAPH_ATOMIC_PACKAGE_delta/
2-
docs/
3-
docs/dev/
1+
docs/pr/PLAN_PR_ASSET_VALIDATION_ENGINE.md
2+
docs/pr/BUILD_PR_ASSET_VALIDATION_ENGINE.md
3+
docs/pr/APPLY_PR_ASSET_VALIDATION_ENGINE.md
4+
docs/dev/codex_commands.md
5+
docs/dev/commit_comment.txt
46
docs/dev/change_summary.txt
5-
docs/dev/file_tree.txt
67
docs/dev/validation_checklist.txt
7-
docs/pr/
8-
docs/pr/APPLY_PR_ASSET_DEPENDENCY_GRAPH.md
9-
docs/pr/BUILD_PR_ASSET_DEPENDENCY_GRAPH.md
10-
docs/pr/PLAN_PR_ASSET_DEPENDENCY_GRAPH.md
11-
tools/
12-
tools/shared/
13-
tools/shared/projectAssetRegistry.js
14-
tools/Sprite Editor/
15-
tools/Sprite Editor/modules/
16-
tools/Sprite Editor/modules/spriteEditorApp.js
17-
tools/Tile Map Editor/
18-
tools/Tile Map Editor/main.js
19-
tools/Parallax Editor/
20-
tools/Parallax Editor/main.js
8+
docs/dev/file_tree.txt

‎docs/dev/reports/asset_validation_engine_validation.txt‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
BUILD_PR_ASSET_VALIDATION_ENGINE validation
2+
3+
Files:
4+
- tools/shared/projectAssetValidation.js
5+
- tests/tools/AssetValidationEngine.test.mjs
6+
- tools/Sprite Editor/modules/spriteEditorApp.js
7+
- tools/Tile Map Editor/main.js
8+
- tools/Parallax Editor/main.js
9+
10+
Checks passed:
11+
- node --check tools/shared/projectAssetValidation.js
12+
- node --check tools/Sprite Editor/modules/spriteEditorApp.js
13+
- node --check tools/Tile Map Editor/main.js
14+
- node --check tools/Parallax Editor/main.js
15+
- node --check tests/tools/AssetValidationEngine.test.mjs
16+
- targeted AssetValidationEngine test via node inline runner
17+
- node ./scripts/run-node-tests.mjs
18+
19+
Behavior confirmed:
20+
- deterministic validation findings
21+
- blocking findings stop guarded save/export/package actions
22+
- legacy/invalid projects still load for remediation
23+
- warnings remain visible but non-blocking
24+
- registry stays source of truth
25+
- no engine core API changes

‎docs/dev/validation_checklist.txt‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
1-
BUILD VALIDATION CHECKLIST
2-
3-
- [x] Legacy projects still load when `project.assetDependencyGraph` is absent
4-
- [x] Registry remains the source of truth for graph reconstruction
5-
- [x] Graph nodes use stable asset IDs and edges are emitted deterministically
6-
- [x] Missing targets and orphaned assets surface as findings instead of hard failures
7-
- [x] Sprite Editor, Tile Map Editor, and Parallax Editor each persist additive graph snapshots on save
8-
- [x] Asset registry save flows report graph findings without blocking editing
9-
- [x] No engine core API files were modified
10-
- [x] Syntax validation passed for changed JS files
1+
- PLAN, BUILD, and APPLY docs are all present
2+
- codex_commands.md and commit_comment.txt are under docs/dev
3+
- Enforcement rules are explicit
4+
- Remediation workflows remain available for invalid projects
5+
- Registry remains source of truth
6+
- Dependency graph remains additive
7+
- No engine core API changes are authorized
8+
- APPLY remains docs-only acceptance boundary

‎docs/pr/APPLY_PR_ASSET_VALIDATION_ENGINE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# APPLY_PR_ASSET_VALIDATION_ENGINE
2+
3+
## Purpose
4+
Apply the completed enforced asset validation engine slice as a docs-only acceptance boundary.
5+
6+
## Apply Scope
7+
- Confirm PLAN and BUILD are complete
8+
- Confirm enforced validation behavior remains within approved scope
9+
- Confirm APPLY introduces no implementation expansion
10+
- Lock enforced validation engine as accepted project architecture baseline
11+
12+
## Verification Summary
13+
- BUILD artifact exists and matches scoped validation implementation
14+
- APPLY remains docs-only
15+
- Registry remains source of truth
16+
- Dependency graph remains additive and validation-driven
17+
- Enforced blocking is limited to guarded operations
18+
- Legacy remediation workflows remain available
19+
- No engine core API changes are required by APPLY
20+
21+
## Accepted Baseline
22+
- Project owns an enforced validation engine
23+
- Blocking findings prevent guarded save/package/export operations
24+
- Editors can still load invalid content and support remediation
25+
- Shared validation contracts govern registry + dependency graph correctness
26+
27+
## Manual Validation Checklist
28+
1. Confirm BUILD artifact exists in repo tmp path.
29+
2. Confirm APPLY bundle only contains docs/pr and docs/dev files.
30+
3. Confirm accepted scope does not exceed BUILD scope.
31+
4. Confirm no new implementation files are introduced by APPLY.
32+
5. Confirm next planning work can build on enforced validation baseline.
33+
34+
## Approved Commit Comment
35+
build(asset-validation): add enforced project asset validation engine

‎docs/pr/BUILD_PR_ASSET_VALIDATION_ENGINE.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# BUILD_PR_ASSET_VALIDATION_ENGINE
2+
3+
## Goal
4+
Implement the enforced project-level asset validation engine defined in `PLAN_PR_ASSET_VALIDATION_ENGINE` without expanding scope or changing engine core APIs.
5+
6+
## Implemented Scope
7+
- Added shared validation engine in `tools/shared/projectAssetValidation.js`
8+
- deterministic stable result structure:
9+
- `validation.status`
10+
- ordered `validation.findings[]`
11+
- stable finding fields: `code`, `severity`, `blocking`, `sourceType`, `sourceId`, `message`
12+
- registry-first validation over deterministic graph rebuilds
13+
- duplicate registry ID detection
14+
- invalid dependency target detection
15+
- orphaned graph-node warnings
16+
- circular dependency detection
17+
- stale graph snapshot detection against registry source data
18+
- tool-specific dependency checks for sprite, tilemap, and parallax consumers
19+
- Added automated coverage in `tests/tools/AssetValidationEngine.test.mjs`
20+
- valid project passes
21+
- invalid palette dependency blocks
22+
- duplicate IDs block
23+
- stale graph snapshots remain non-blocking warnings
24+
- repeated validation remains deterministic
25+
- legacy-style documents without required registry refs remain loadable
26+
- Integrated enforced validation into guarded editor operations only:
27+
- `tools/Sprite Editor/modules/spriteEditorApp.js`
28+
- blocks guarded PNG/sprite-sheet export and save flows when blocking findings exist
29+
- surfaces validation summaries on load/save
30+
- `tools/Tile Map Editor/main.js`
31+
- blocks guarded project save, registry save, and runtime export when blocking findings exist
32+
- surfaces validation summaries on load/save
33+
- `tools/Parallax Editor/main.js`
34+
- blocks guarded project save, registry save, and patch export when blocking findings exist
35+
- surfaces validation summaries on load/save
36+
- Preserved legacy remediation behavior
37+
- legacy loads still succeed
38+
- invalid content can still be opened, inspected, edited, and revalidated
39+
- enforcement is limited to guarded save/export/package-style actions
40+
41+
## Manual Validation Checklist
42+
1. Valid project can save guarded state successfully. `PASS`
43+
2. Invalid project with missing asset ID cannot perform guarded save/finalize. `PASS`
44+
3. Duplicate IDs produce blocking findings. `PASS`
45+
4. Illegal cycles produce blocking findings. `PASS`
46+
5. Warnings remain non-blocking. `PASS`
47+
6. Legacy invalid project can still load and be repaired. `PASS`
48+
7. Findings are deterministic across repeated validation. `PASS`
49+
8. Engine core APIs remain unchanged. `PASS`
50+
51+
## Validation Summary
52+
- Syntax checks passed:
53+
- `node --check tools/shared/projectAssetValidation.js`
54+
- `node --check tools/Sprite Editor/modules/spriteEditorApp.js`
55+
- `node --check tools/Tile Map Editor/main.js`
56+
- `node --check tools/Parallax Editor/main.js`
57+
- `node --check tests/tools/AssetValidationEngine.test.mjs`
58+
- Targeted validation-engine test passed:
59+
- `node` inline runner for `tests/tools/AssetValidationEngine.test.mjs`
60+
- Full Node test suite passed:
61+
- `node ./scripts/run-node-tests.mjs`
62+
63+
## Scope Guard
64+
- Registry remains the source of truth.
65+
- Dependency graph remains additive and validation-driven.
66+
- Enforcement is limited to guarded save/export/package paths.
67+
- No engine core API files were modified.
68+
69+
## Approved Commit Comment
70+
build(asset-validation): add enforced project asset validation engine
71+
72+
## Next Command
73+
APPLY_PR_ASSET_VALIDATION_ENGINE

‎docs/pr/PLAN_PR_ASSET_VALIDATION_ENGINE.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# PLAN_PR_ASSET_VALIDATION_ENGINE
2+
3+
## Goal
4+
Define a project-level asset validation engine that enforces dependency and registry correctness for authoring workflows,
5+
with deterministic validation outcomes and explicit failure rules for invalid projects.
6+
7+
## Context
8+
The project baseline now includes:
9+
- registry-aware Sprite Editor
10+
- registry-aware Tile Map Editor
11+
- registry-aware Parallax Editor
12+
- additive project-level asset dependency graph
13+
14+
The next architectural layer is an enforced validation engine that determines whether project state is valid enough
15+
to save, package, or export under defined project rules.
16+
17+
## Enforced Mode Intent
18+
This PR is intentionally **enforced**, not passive.
19+
Validation findings are allowed to block save/package/export operations where contracts are violated.
20+
21+
## Scope
22+
- Define shared validation engine contracts
23+
- Define validation result model
24+
- Define severity levels and blocking rules
25+
- Define editor integration expectations
26+
- Define registry + dependency graph validation categories
27+
- Define backward-compatible rollout behavior for legacy projects
28+
29+
## Non-Goals
30+
- No engine core API changes
31+
- No runtime gameplay validator
32+
- No packaging/export implementation beyond validation gates
33+
- No destructive migration of legacy projects
34+
35+
## Validation Categories
36+
- missing asset ID references
37+
- orphaned graph nodes
38+
- invalid edge targets
39+
- duplicate IDs in registry-owned domains
40+
- illegal circular dependencies where disallowed
41+
- unresolved palette relationships
42+
- unresolved tileset/tile/image dependencies
43+
- stale graph snapshots versus registry source data
44+
45+
## Proposed Result Model
46+
```json
47+
{
48+
"validation": {
49+
"status": "valid | invalid",
50+
"findings": [
51+
{
52+
"code": "MISSING_ASSET_ID",
53+
"severity": "error | warning | info",
54+
"blocking": true,
55+
"sourceType": "sprite | tilemap | parallaxLayer | registry | graph",
56+
"sourceId": "example-id",
57+
"message": "Human-readable explanation"
58+
}
59+
]
60+
}
61+
}
62+
```
63+
64+
## Severity Contract
65+
- `error` = blocking in enforced mode
66+
- `warning` = non-blocking but visible
67+
- `info` = advisory only
68+
69+
## Blocking Rules
70+
The following must block guarded operations in enforced mode:
71+
1. missing required asset IDs
72+
2. invalid dependency graph targets
73+
3. duplicate authoritative IDs
74+
4. illegal circular dependencies
75+
5. unresolved required palette/tileset/image links
76+
6. registry/graph corruption that prevents deterministic reconstruction
77+
78+
## Allowed Operations Under Enforcement
79+
- read/load legacy content
80+
- inspect project state
81+
- edit toward remediation
82+
- run validation repeatedly
83+
84+
## Blocked Operations Under Enforcement
85+
- save invalid guarded project state when blocking findings exist
86+
- package/export invalid project state
87+
- finalize derived artifacts from invalid source state
88+
89+
## Legacy Compatibility
90+
- Legacy projects without validation data must still load
91+
- Validation may immediately flag legacy issues after load
92+
- Editors must permit remediation workflows even when save/package/export are blocked
93+
- BUILD should prefer additive validation metadata, not migration requirements
94+
95+
## Editor Responsibilities
96+
### Sprite Editor
97+
- surface palette and sprite reference failures
98+
- block guarded save/finalize actions on blocking findings
99+
100+
### Tile Map Editor
101+
- surface missing tileset/tile/sprite dependencies
102+
- block guarded save/finalize actions on blocking findings
103+
104+
### Parallax Editor
105+
- surface missing image/layer dependencies
106+
- block guarded save/finalize actions on blocking findings
107+
108+
## Shared Responsibilities
109+
- validation logic should be centralized in shared tooling where practical
110+
- editors should consume validation results, not reinvent rule logic
111+
- result formatting should be stable enough for reports and future tooling
112+
113+
## Manual Validation Checklist
114+
1. Valid registry-aware project passes with no blocking findings.
115+
2. Missing required asset ID fails validation deterministically.
116+
3. Duplicate authoritative IDs fail validation deterministically.
117+
4. Illegal cycle detection produces blocking findings.
118+
5. Legacy project loads, surfaces issues, and allows remediation.
119+
6. Blocked operations remain blocked until findings are resolved.
120+
7. Non-blocking warnings do not prevent remediation workflows.
121+
8. Engine core APIs remain unchanged.
122+
123+
## Next Command
124+
BUILD_PR_ASSET_VALIDATION_ENGINE

‎tests/run-tests.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ import { run as runWorldGameStateAuthoritativeScore } from './world/WorldGameSta
8484
import { run as runProductionReadiness } from './production/ProductionReadiness.test.mjs';
8585
import { run as runEnginePublicBarrelImports } from './production/EnginePublicBarrelImports.test.mjs';
8686
import { run as runStorageService } from './persistence/StorageService.test.mjs';
87+
import { run as runAssetValidationEngine } from './tools/AssetValidationEngine.test.mjs';
8788
import './render/Renderer.test.mjs';
8889
import { run as runReplaySystem } from './replay/ReplaySystem.test.mjs';
8990
import { run as runOrbitLabModel } from './samples/OrbitLabModel.test.mjs';
@@ -162,6 +163,7 @@ const tests = [
162163
['KeyboardState', runKeyboardState],
163164
['MouseState', runMouseState],
164165
['StorageService', runStorageService],
166+
['AssetValidationEngine', runAssetValidationEngine],
165167
['ReplaySystem', runReplaySystem],
166168
['OrbitLabModel', runOrbitLabModel],
167169
['OrbitLabScene', runOrbitLabScene],

0 commit comments

Comments
 (0)