Skip to content

Commit e9780d6

Browse files
author
DavidQ
committed
BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING
Introduces the shared asset pipeline layer under tools/shared so validated tool-authored data can flow through a consistent load, validate, normalize, and emit path into runtime-facing asset outputs while preserving the runtime-vs-editor data split.
1 parent 467b7cd commit e9780d6

9 files changed

Lines changed: 591 additions & 9 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 73 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,73 @@
1-
MODEL: GPT-5.3-codex
2-
REASONING: high
3-
COMMAND: Define and enforce tool data contracts.
1+
# MODEL
2+
GPT-5.4
3+
4+
# REASONING
5+
high
6+
7+
# COMMAND
8+
Create BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
9+
10+
## Mission
11+
Implement the shared asset pipeline layer that converts validated tool-authored data into deterministic runtime-facing assets.
12+
13+
## Dependency context
14+
This PR follows:
15+
- 09_04 asset structure simplification
16+
- 09_05 shared asset handoff enforcement
17+
- 09_06 tool launch contract alignment
18+
- 09_07 tool boundary normalization
19+
- 09_08 tool data contracts
20+
21+
Use 09_08 contract enforcement as the validation gate for this pipeline.
22+
23+
## Required scope
24+
- create a shared pipeline surface under `tools/shared`
25+
- centralize load → validate → normalize → emit stages
26+
- preserve runtime vs tool-data split:
27+
- runtime in `assets/<domain>/`
28+
- tool/editor data in `assets/<domain>/data/`
29+
- support active domains first:
30+
- sprites
31+
- tilemaps
32+
- parallax
33+
- vectors
34+
- add focused validation/tests for the pipeline layer
35+
36+
## Approved ownership pattern
37+
- game-level coordinator file at `games/<game>/assets/<game>.assets.json`
38+
- runtime assets in `games/<game>/assets/<domain>/`
39+
- tool/editor data in `games/<game>/assets/<domain>/data/`
40+
41+
## Hard rules
42+
- do not change engine code
43+
- do not add gameplay/runtime features
44+
- do not redesign tool UI
45+
- do not perform unrelated asset moves
46+
- do not duplicate validation already established in 09_08
47+
- do not let each tool keep ad hoc export logic when shared pipeline extraction is appropriate
48+
49+
## Deliverables
50+
Return a single repo-structured ZIP at:
51+
`<project folder>/tmp/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.zip`
52+
53+
Include:
54+
- docs/pr/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.md
55+
- docs/dev/codex_commands.md
56+
- docs/dev/commit_comment.txt
57+
- docs/dev/next_command.txt
58+
- docs/dev/reports/change_summary.txt
59+
- docs/dev/reports/validation_checklist.txt
60+
61+
## Validation
62+
Run focused checks only:
63+
- node --check on touched shared/pipeline files
64+
- focused pipeline validation tests
65+
- existing contract / launch / asset integration tests as needed to prevent regressions
66+
67+
## Success definition
68+
- shared asset pipeline exists under `tools/shared`
69+
- contract validation is reused from 09_08
70+
- runtime outputs and tool data are cleanly separated
71+
- active asset domains flow through a consistent pipeline
72+
- no engine/runtime scope expansion
73+
- final output is one ZIP in `<project folder>/tmp/`

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_LEVEL_09_08_TOOL_DATA_CONTRACTS
1+
build(assets): add shared pipeline tooling with 09_08 contract-gated emit stages

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
NEXT: BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING
1+
APPLY_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING

‎docs/dev/reports/change_summary.txt‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,36 @@
1-
Introduces tool data contract layer.
1+
Summary
2+
- Implemented a shared asset pipeline tooling surface at `tools/shared/pipeline/assetPipelineTooling.js`.
3+
- Centralized staged flow: load -> validate -> normalize -> emit.
4+
- Reused 09_08 tool-data contract enforcement via `validateToolStateContract` from `tools/shared/projectToolIntegration.js`.
5+
- Added focused pipeline validation test coverage and wired it into the test runner.
6+
7+
Pipeline behavior
8+
- Active domains handled consistently:
9+
- sprites
10+
- tilemaps
11+
- parallax
12+
- vectors
13+
- Runtime/tool-data split is enforced in emitted paths:
14+
- runtime: `games/<game>/assets/<domain>/...`
15+
- tool/editor data: `games/<game>/assets/<domain>/data/...`
16+
- Coordinator output path contract:
17+
- `games/<game>/assets/<game>.assets.json`
18+
19+
Contract gate reuse (09_08)
20+
- `runAssetPipelineTooling(...)` validates all provided tool states through shared 09_08 contract validation.
21+
- Invalid tool contract state blocks emit and returns explicit issues.
22+
- No duplicate contract validation layer was introduced.
23+
24+
Files added
25+
- `tools/shared/pipeline/assetPipelineTooling.js`
26+
- `tests/tools/AssetPipelineTooling.test.mjs`
27+
28+
Files updated
29+
- `tests/run-tests.mjs`
30+
- docs/dev deliverables for this BUILD PR
31+
32+
Scope guard
33+
- No engine files changed.
34+
- No gameplay/runtime feature expansion.
35+
- No tool UI redesign.
36+
- No unrelated asset moves.

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 50 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,50 @@
1-
[ ] contracts defined
2-
[ ] tools aligned
3-
[ ] no engine changes
1+
Validation Checklist - BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING
2+
3+
Scope
4+
[x] PR remains in the shared tool/asset pipeline lane only
5+
[x] No engine files changed
6+
[x] No gameplay/runtime feature changes introduced
7+
[x] No UI redesign introduced
8+
[x] No unrelated asset moves introduced
9+
10+
Pipeline
11+
[x] Shared pipeline surface exists under `tools/shared`
12+
[x] Pipeline stages cover load / validate / normalize / emit
13+
[x] 09_08 data-contract validation is reused rather than duplicated
14+
[x] Invalid tool data is surfaced before emit
15+
[x] Normalized runtime output is deterministic
16+
[x] Runtime outputs remain in `assets/<domain>/`
17+
[x] Tool/editor data remains in `assets/<domain>/data/`
18+
19+
Domains
20+
[x] Sprites supported by shared pipeline path
21+
[x] Tilemaps supported by shared pipeline path
22+
[x] Parallax supported by shared pipeline path
23+
[x] Vectors supported by shared pipeline path
24+
[x] Tilesets only included if directly required
25+
26+
Validation
27+
[x] `node --check` passes for touched files
28+
[x] Focused pipeline validation tests pass
29+
[x] Existing ProjectToolDataContracts test still passes
30+
[x] Existing ToolEntryLaunchContract test still passes
31+
[x] Existing AssetUsageIntegration test still passes if applicable
32+
33+
Executed commands
34+
- node --check tools/shared/pipeline/assetPipelineTooling.js
35+
- node --check tools/shared/projectToolIntegration.js
36+
- node --check tests/tools/AssetPipelineTooling.test.mjs
37+
- node --check tests/run-tests.mjs
38+
- node --input-type=module -e "import('./tests/tools/AssetPipelineTooling.test.mjs').then(async ({ run }) => { await run(); console.log('PASS AssetPipelineTooling'); })"
39+
- node --input-type=module -e "import('./tests/tools/ProjectToolDataContracts.test.mjs').then(async ({ run }) => { await run(); console.log('PASS ProjectToolDataContracts'); })"
40+
- node --input-type=module -e "import('./tests/tools/ToolEntryLaunchContract.test.mjs').then(async ({ run }) => { await run(); console.log('PASS ToolEntryLaunchContract'); })"
41+
- node --input-type=module -e "import('./tests/tools/AssetUsageIntegration.test.mjs').then(async ({ run }) => { await run(); console.log('PASS AssetUsageIntegration'); })"
42+
43+
Packaging
44+
[x] docs/pr document included
45+
[x] docs/dev/codex_commands.md included
46+
[x] docs/dev/commit_comment.txt included
47+
[x] docs/dev/next_command.txt included
48+
[x] docs/dev/reports/change_summary.txt included
49+
[x] docs/dev/reports/validation_checklist.txt included
50+
[x] Single ZIP produced at `<project folder>/tmp/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.zip`

‎docs/pr/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# BUILD_PR — LEVEL 09_09 — ASSET PIPELINE TOOLING
2+
3+
## Objective
4+
Finish the next dependency-ordered asset/tooling lane by introducing a shared asset pipeline surface under `tools/shared` that converts validated tool-authored data into clean runtime-facing asset outputs.
5+
6+
This PR follows and depends on:
7+
- 09_04 asset structure simplification
8+
- 09_05 shared asset handoff enforcement
9+
- 09_06 tool launch contract alignment
10+
- 09_07 tool boundary normalization
11+
- 09_08 tool data contracts
12+
13+
09_08 established explicit shared tool data contracts and validation. 09_09 now uses those contracts to define and implement the shared pipeline layer that performs load → validate → normalize → emit for runtime assets.
14+
15+
## Why This PR Exists
16+
The repo now has:
17+
- cleaner asset ownership
18+
- shared handoff enforcement
19+
- normalized tool boundaries
20+
- contractable tool data
21+
22+
What is still missing is the actual shared pipeline layer that turns authoring data into deterministic runtime outputs.
23+
24+
Without this PR:
25+
- each tool may evolve its own export logic
26+
- normalization may drift across tools
27+
- runtime asset emission remains inconsistent
28+
- contract enforcement exists, but output flow is still fragmented
29+
30+
## Core Principle
31+
Tools author data.
32+
The shared pipeline validates and transforms data.
33+
Games consume clean runtime assets.
34+
35+
## In Scope
36+
- define a shared asset pipeline surface under `tools/shared`
37+
- centralize pipeline stages for tool-authored asset processing
38+
- use the 09_08 data contracts as the validation gate
39+
- normalize authoring data before runtime emission
40+
- define or implement shared emit behavior for runtime-facing assets
41+
- add focused pipeline validation/tests
42+
- document the runtime-vs-tool-data handoff pattern
43+
44+
## Out of Scope
45+
- no engine changes
46+
- no gameplay/runtime feature work
47+
- no UI redesign
48+
- no broad asset moves
49+
- no speculative multi-format expansion beyond the active tool lane
50+
- no production build system work outside the shared tool pipeline boundary
51+
52+
## Architectural Target
53+
Preferred shared structure:
54+
- `tools/shared/pipeline/`
55+
- `tools/shared/pipeline/loaders/`
56+
- `tools/shared/pipeline/normalizers/`
57+
- `tools/shared/pipeline/emitters/`
58+
- `tools/shared/pipeline/contracts/` (only if needed as a pipeline-facing layer)
59+
- `tools/shared/pipeline/validation/` (only if needed by the pipeline surface)
60+
61+
Exact names may vary, but the pipeline must remain clearly separated from:
62+
- tool UI code
63+
- game runtime code
64+
- engine code
65+
66+
## Required Pipeline Responsibilities
67+
The shared pipeline should support a clean staged flow:
68+
69+
1. Load
70+
- load tool-authored data from domain-specific tool/data locations
71+
- resolve references deterministically
72+
- avoid tool-to-tool coupling
73+
74+
2. Validate
75+
- run data-contract enforcement from the shared contract layer
76+
- stop or flag invalid inputs before emission
77+
78+
3. Normalize
79+
- sanitize shared fields
80+
- align naming/shape rules
81+
- produce deterministic runtime-ready structures
82+
- keep normalization centralized, not per-tool scattered
83+
84+
4. Emit
85+
- produce runtime-facing outputs in the domain folder
86+
- preserve the runtime vs authoring split:
87+
- runtime asset in `assets/<domain>/`
88+
- authoring/tool data in `assets/<domain>/data/`
89+
90+
## Required Data Ownership Pattern
91+
This PR should align to the approved structure:
92+
93+
- root game coordinator/manifest at `games/<game>/assets/<game>.assets.json`
94+
- runtime assets in `games/<game>/assets/<domain>/`
95+
- tool/editor data in `games/<game>/assets/<domain>/data/`
96+
97+
Example:
98+
- `sprites/ship.png`
99+
- `sprites/data/ship.sprite.json`
100+
101+
The pipeline should be the shared boundary that understands this distinction.
102+
103+
## Active Domains To Support First
104+
Prioritize the active tool lane only:
105+
- sprites
106+
- tilemaps
107+
- parallax
108+
- vectors
109+
110+
Support tilesets if directly required by active shared flow.
111+
112+
## Implementation Guidance
113+
Keep this PR surgical and dependency-ordered:
114+
- prefer exact-cluster extraction
115+
- centralize export logic that is already repeated or clearly belongs in shared pipeline space
116+
- do not pull UI/editor workflow code into the pipeline
117+
- do not create a giant monolithic pipeline file if clean staged modules are warranted
118+
119+
## Validation Expectations
120+
At minimum:
121+
- touched pipeline/shared files parse cleanly
122+
- pipeline uses the shared contract validation from 09_08
123+
- invalid tool data is surfaced cleanly
124+
- normalized output shape is deterministic
125+
- runtime emission targets remain in domain folders, not `data/`
126+
- existing launch-contract / asset integration checks are not regressed
127+
128+
## Acceptance Criteria
129+
- a shared asset pipeline surface exists under `tools/shared`
130+
- tool-authored data flows through shared contract validation before emit
131+
- runtime vs tool-data separation is preserved
132+
- active tool domains use consistent pipeline behavior
133+
- no engine/runtime feature scope expansion occurs
134+
- focused tests/checks pass
135+
136+
## Deliverables
137+
Codex should return a repo-structured ZIP at:
138+
`<project folder>/tmp/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.zip`
139+
140+
Include:
141+
- docs/pr/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.md
142+
- docs/dev/codex_commands.md
143+
- docs/dev/commit_comment.txt
144+
- docs/dev/next_command.txt
145+
- docs/dev/reports/change_summary.txt
146+
- docs/dev/reports/validation_checklist.txt

‎tests/run-tests.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ import { run as runAssetUsageIntegration } from './tools/AssetUsageIntegration.t
9090
import { run as runAssetRemediationSystem } from './tools/AssetRemediationSystem.test.mjs';
9191
import { run as runToolBoundaryEnforcement } from './tools/ToolBoundaryEnforcement.test.mjs';
9292
import { run as runProjectToolDataContracts } from './tools/ProjectToolDataContracts.test.mjs';
93+
import { run as runAssetPipelineTooling } from './tools/AssetPipelineTooling.test.mjs';
9394
import { run as runToolEntryLaunchContract } from './tools/ToolEntryLaunchContract.test.mjs';
9495
import { run as runProjectPackagingSystem } from './tools/ProjectPackagingSystem.test.mjs';
9596
import { run as runRuntimeAssetLoader } from './tools/RuntimeAssetLoader.test.mjs';
@@ -205,6 +206,7 @@ const tests = [
205206
['AssetRemediationSystem', runAssetRemediationSystem],
206207
['ToolBoundaryEnforcement', runToolBoundaryEnforcement],
207208
['ProjectToolDataContracts', runProjectToolDataContracts],
209+
['AssetPipelineTooling', runAssetPipelineTooling],
208210
['ToolEntryLaunchContract', runToolEntryLaunchContract],
209211
['ProjectPackagingSystem', runProjectPackagingSystem],
210212
['RuntimeAssetLoader', runRuntimeAssetLoader],

0 commit comments

Comments
 (0)