BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION

Adopts manifest-driven runtime asset binding in the next small set of active runtime consumers, reduces ad hoc asset-path assumptions where touched, preserves runtime/editor boundaries, and limits roadmap edits to status-only updates.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -5,45 +5,52 @@ GPT-5.4
 high
 
 # COMMAND
-Create BUILD_PR_LEVEL_09_11_RUNTIME_ASSET_BINDING as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
+Create BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
 
 ## Mission
-Bind runtime asset consumers to the deterministic game asset manifest so runtime lookup is manifest-driven and cannot consume tool/editor-only data.
+Adopt the manifest-driven runtime asset binding layer in the next small set of high-value runtime consumers so the new coordinated asset lane becomes real usage, not just infrastructure.
 
 ## Dependency context
 This PR follows:
 - 09_09 asset pipeline tooling
 - 09_10 game asset manifest coordination
+- 09_11 runtime asset binding
 
-Use the generated game asset manifest at:
-`games/<game>/assets/<game>.assets.json`
+Use the approved binding surface introduced in 09_11.
+Do not bypass it with direct asset path assumptions where touched.
 
 ## Required scope
-- introduce a runtime-facing asset binding layer
-- resolve runtime assets from the coordinated manifest
-- centralize lookup by asset/domain identifiers
-- exclude or reject `assets/<domain>/data/` content from runtime binding
-- support active domains first:
-  - sprites
-  - tilemaps
-  - parallax
-  - vectors
-- add focused tests for runtime binding behavior
+- find the smallest high-value runtime adoption points
+- replace touched ad hoc asset references with manifest-driven binding
+- keep runtime readers out of `assets/<domain>/data/`
+- add focused tests for adoption and non-regression
+- stop at a stable checkpoint after the first clean adoption slice
+
+## Recommended targets
+Prefer low-risk, active callers such as:
+- Asteroids runtime asset references
+- shared runtime-safe asset loading helpers
+- nearby runtime consumers already in this lane
 
 ## Hard rules
+- do not perform a repo-wide migration
 - do not redesign tools
-- do not expand engine feature scope broadly
 - do not add gameplay features
-- do not introduce new asset format work
-- do not allow runtime readers to depend on editor/tool data
+- do not introduce new asset formats
+- do not allow runtime access to editor/tool data
 - keep the PR surgical and dependency-ordered
 
+## Roadmap instruction
+Update roadmap status only where this PR clearly advances tracked work.
+Do not change any roadmap text, prose, descriptions, or ordering.
+Status changes only.
+
 ## Deliverables
 Return a single repo-structured ZIP at:
-`<project folder>/tmp/BUILD_PR_LEVEL_09_11_RUNTIME_ASSET_BINDING.zip`
+`<project folder>/tmp/BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION.zip`
 
 Include:
-- docs/pr/BUILD_PR_LEVEL_09_11_RUNTIME_ASSET_BINDING.md
+- docs/pr/BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION.md
 - docs/dev/codex_commands.md
 - docs/dev/commit_comment.txt
 - docs/dev/next_command.txt
@@ -53,14 +60,15 @@ Include:
 ## Validation
 Run focused checks only:
 - node --check on touched files
-- focused runtime binding tests
+- focused adoption tests
+- existing runtime binding tests
 - existing GameAssetManifestCoordinator tests
 - existing AssetPipelineTooling tests
 - existing ProjectToolDataContracts tests as needed
 
 ## Success definition
-- runtime asset lookup is manifest-driven
-- `/data/` records are excluded from runtime binding
-- active asset domains resolve consistently
-- existing pipeline/manifest tests remain green
+- selected runtime consumers adopt manifest-driven binding
+- `/data/` records remain excluded from runtime use
+- existing pipeline/manifest/binding tests remain green
+- roadmap gets status-only updates if applicable
 - final output is one ZIP in `<project folder>/tmp/`

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1,3 @@
-build(runtime): bind runtime asset lookup to coordinated game asset manifest
+BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION
+
+Adopt manifest-driven runtime asset binding in Asteroids runtime demo consumers (vectors/tilemap/parallax) using the 09_11 binding surface, replace touched ad hoc runtime path resolution with binding-based lookup, and add focused adoption/non-regression tests while preserving runtime/editor data boundaries.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION
+BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION

docs/dev/reports/change_summary.txt

@@ -1,33 +1,26 @@
 Summary
-- Implemented a runtime-facing manifest binding layer under `tools/shared/pipeline/runtimeAssetBinding.js`.
-- Runtime lookup is now manifest-driven by domain + asset id.
-- Runtime binding explicitly excludes `/data/` records so runtime readers cannot consume editor/tool-only assets.
-- Added focused runtime binding tests and wired them into the test runner.
+- Implemented a surgical 09_12 adoption slice in the Asteroids runtime demo consumer lane.
+- Replaced touched ad hoc runtime file selection for bindable domains with 09_11 manifest-driven runtime binding.
+- Added focused adoption validation to prove runtime resolution uses binding outputs and remains `/data/`-safe.
 
-Implemented runtime binding surface
-- `createRuntimeAssetBinding(manifest)`
-  - consumes `games/<game>/assets/<game>.assets.json`-shaped manifest payload
-  - builds runtime-safe domain indexes for active domains:
-    - sprites
-    - tilemaps
-    - parallax
-    - vectors
-  - rejects records whose runtime path resolves to `/data/`
-- `resolveRuntimeAsset(binding, { domain, assetId })`
-  - deterministic runtime lookup by normalized domain + asset id
-  - returns null for missing/rejected assets
-
-Focused tests added
-- `tests/tools/RuntimeAssetBinding.test.mjs`
-  - validates manifest-driven lookup
-  - validates `/data/` exclusion
-  - validates active domain support
-  - validates invalid-manifest handling
-- `tests/run-tests.mjs` updated to include `RuntimeAssetBinding` test.
+Code changes
+- `tools/shared/asteroidsPlatformDemo.js`
+  - imports and uses `coordinateGameAssetManifest`, `createRuntimeAssetBinding`, and `resolveRuntimeAsset`
+  - adds bindable domain mapping for `vector.*`, `tilemap.*`, `parallax.*`, `sprite.*`
+  - builds a coordinated game-asset manifest + runtime binding from runtime source records
+  - resolves bindable runtime assets through manifest-driven binding instead of ad hoc direct path use in touched resolver code
+  - preserves non-bindable runtime asset behavior and existing runtime/demo flow
+- `tests/games/AsteroidsAssetReferenceAdoption.test.mjs` (new)
+  - asserts runtime binding is `ready` with no issues
+  - asserts vector/tilemap/parallax assets resolve through binding and runtime paths do not include `/data/`
+  - asserts runtime bootstrap asset table paths match binding runtime paths
 
 Scope guard
+- No engine core changes.
 - No tool UI redesign.
-- No gameplay feature additions.
-- No broad engine scope expansion.
-- No new asset formats.
-- No unrelated asset movement.
+- No gameplay/runtime feature expansion.
+- No repo-wide migration.
+- No asset moves.
+
+Roadmap
+- No roadmap file changes were required in this checkpoint.

docs/dev/reports/validation_checklist.txt

@@ -1,38 +1,32 @@
-Validation Checklist - BUILD_PR_LEVEL_09_11_RUNTIME_ASSET_BINDING
+Validation Checklist - BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION
 
 Scope
-[x] PR remains in the runtime asset binding lane only
+[x] PR remains in the asset reference adoption lane only
+[x] No broad repo-wide migration introduced
 [x] No tool UI redesign introduced
 [x] No gameplay feature changes introduced
-[x] No broad engine scope expansion introduced
-[x] No unrelated asset moves introduced
+[x] No new asset format work introduced
 
-Binding
-[x] Runtime-facing binding reads from `games/<game>/assets/<game>.assets.json`
-[x] Lookup is manifest-driven rather than ad hoc where touched
-[x] Binding supports sprites
-[x] Binding supports tilemaps
-[x] Binding supports parallax
-[x] Binding supports vectors
-[x] Tilesets only included if directly required
-[x] `assets/<domain>/data/` content is excluded or rejected from runtime binding
-[x] Deterministic lookup works by asset/domain identifiers
+Adoption
+[x] Selected runtime consumers now use manifest-driven binding
+[x] Replaced ad hoc path assumptions where touched
+[x] `assets/<domain>/data/` content remains excluded from runtime use
+[x] Deterministic identifier-based resolution remains intact
+[x] Adoption stops at a stable checkpoint
 
 Validation
-[x] `node --check` passes for touched files
-[x] Focused runtime binding tests pass
-[x] Existing GameAssetManifestCoordinator tests still pass
-[x] Existing AssetPipelineTooling tests still pass
-[x] Existing ProjectToolDataContracts tests still pass
+[x] `node --check tools/shared/asteroidsPlatformDemo.js`
+[x] `node --check tests/games/AsteroidsAssetReferenceAdoption.test.mjs`
+[x] Focused adoption test passes: `AsteroidsAssetReferenceAdoption`
+[x] Existing runtime binding test passes: `RuntimeAssetBinding`
+[x] Existing GameAssetManifestCoordinator test passes
+[x] Existing AssetPipelineTooling test passes
+[x] Existing ProjectToolDataContracts test passes
+[x] Existing AsteroidsPlatformDemo non-regression test passes
 
-Executed commands
-- node --check tools/shared/pipeline/runtimeAssetBinding.js
-- node --check tests/tools/RuntimeAssetBinding.test.mjs
-- node --check tests/run-tests.mjs
-- node --input-type=module -e "import('./tests/tools/RuntimeAssetBinding.test.mjs').then(async ({ run }) => { await run(); console.log('PASS RuntimeAssetBinding'); })"
-- node --input-type=module -e "import('./tests/tools/GameAssetManifestCoordinator.test.mjs').then(async ({ run }) => { await run(); console.log('PASS GameAssetManifestCoordinator'); })"
-- node --input-type=module -e "import('./tests/tools/AssetPipelineTooling.test.mjs').then(async ({ run }) => { await run(); console.log('PASS AssetPipelineTooling'); })"
-- node --input-type=module -e "import('./tests/tools/ProjectToolDataContracts.test.mjs').then(async ({ run }) => { await run(); console.log('PASS ProjectToolDataContracts'); })"
+Roadmap
+[x] Roadmap status update not applied (not clearly required in this checkpoint)
+[x] No roadmap prose/text changes made
 
 Packaging
 [x] docs/pr document included
@@ -41,4 +35,5 @@ Packaging
 [x] docs/dev/next_command.txt included
 [x] docs/dev/reports/change_summary.txt included
 [x] docs/dev/reports/validation_checklist.txt included
-[x] Single ZIP produced at `<project folder>/tmp/BUILD_PR_LEVEL_09_11_RUNTIME_ASSET_BINDING.zip`
+[x] Single ZIP produced at `<project folder>/tmp/BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION.zip`
+

docs/pr/BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION.md

@@ -0,0 +1,94 @@
+# BUILD_PR — LEVEL 09_12 — ASSET REFERENCE ADOPTION
+
+## Objective
+Adopt the manifest-driven runtime asset binding path in the first targeted runtime consumers so active games and shared runtime-facing callers stop relying on ad hoc asset-path assumptions where touched.
+
+This PR follows:
+- 09_09 asset pipeline tooling
+- 09_10 game asset manifest coordination
+- 09_11 runtime asset binding
+
+09_11 established the runtime-safe manifest-driven binding layer.
+09_12 now applies that layer in the next small, dependency-ordered adoption pass.
+
+## Why This PR Exists
+The repo now has:
+- shared asset pipeline stages
+- deterministic game asset manifests
+- runtime-safe manifest-driven binding
+
+What remains is actual adoption in the callers that still assume direct paths or per-domain lookup behavior.
+
+Without this PR:
+- the new binding layer exists but remains underused
+- games and runtime surfaces may continue drifting in lookup behavior
+- manifest coordination is not yet the default consumption path
+
+## In Scope
+- identify the smallest set of active runtime consumers that should adopt manifest-driven asset lookup now
+- replace touched ad hoc runtime asset references with the approved binding surface
+- prefer high-value, low-risk adoption targets in active games or shared runtime consumers
+- preserve the runtime/tool-data boundary
+- add focused tests for adoption points and non-regression
+
+## Out of Scope
+- no broad repo-wide migration
+- no tool UI work
+- no new asset-format work
+- no gameplay feature changes
+- no speculative engine redesign
+- no runtime access to `assets/<domain>/data/`
+
+## Adoption Strategy
+This PR should be surgical:
+1. choose a very small number of high-value adoption sites
+2. swap them to manifest-driven lookup
+3. validate behavior
+4. stop at a stable checkpoint
+
+Do not turn this PR into a full repo-wide migration.
+
+## Recommended Initial Targets
+Prioritize active, low-risk consumers such as:
+- Asteroids runtime asset references where manifest-driven lookup clearly applies
+- shared runtime-safe asset loading helpers already adjacent to asset lookup
+- any touched code already participating in the new asset lane
+
+## Hard Rules
+- runtime lookup must flow through the approved manifest/binding surface where touched
+- runtime code must not read tool/editor data
+- keep the delta small and purpose-specific
+- no broad cleanup unrelated to adoption
+- preserve deterministic identifier-based resolution
+
+## Validation Expectations
+At minimum:
+- touched files parse cleanly
+- adoption sites resolve through the binding layer
+- `/data/` content remains excluded from runtime use
+- existing binding/manifest/pipeline tests remain green
+- focused adoption tests pass
+
+## Roadmap Update Instruction
+Update roadmap status only where this PR clearly advances tracked work.
+Do not change roadmap wording, descriptions, ordering, or prose.
+Status updates only. No text edits.
+
+## Acceptance Criteria
+- selected runtime consumers use manifest-driven binding
+- no touched runtime consumer relies on ad hoc path assumptions where replaced
+- runtime/editor boundary remains intact
+- tests/checks pass
+- roadmap receives status-only updates if applicable
+
+## Deliverables
+Return a repo-structured ZIP at:
+`<project folder>/tmp/BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION.zip`
+
+Include:
+- docs/pr/BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION.md
+- docs/dev/codex_commands.md
+- docs/dev/commit_comment.txt
+- docs/dev/next_command.txt
+- docs/dev/reports/change_summary.txt
+- docs/dev/reports/validation_checklist.txt

tests/games/AsteroidsAssetReferenceAdoption.test.mjs

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { buildAsteroidsPlatformDemo } from "../../tools/shared/asteroidsPlatformDemo.js";
+
+export async function run() {
+  const result = await buildAsteroidsPlatformDemo();
+  const binding = result.demo.runtimeBinding;
+
+  assert.equal(binding?.status, "ready");
+  assert.equal(Array.isArray(binding?.issues), true);
+  assert.equal(binding.issues.length, 0);
+
+  const vectorBinding = (binding.domains.vectors || []).find((entry) => entry.assetId === "vector.asteroids.ship");
+  const tilemapBinding = (binding.domains.tilemaps || []).find((entry) => entry.assetId === "tilemap.asteroids-stage");
+  const parallaxBinding = (binding.domains.parallax || []).find((entry) => entry.assetId === "parallax.asteroids-title");
+
+  assert.equal(Boolean(vectorBinding), true);
+  assert.equal(Boolean(tilemapBinding), true);
+  assert.equal(Boolean(parallaxBinding), true);
+  assert.equal(vectorBinding.runtimePath.includes("/data/"), false);
+  assert.equal(tilemapBinding.runtimePath.includes("/data/"), false);
+  assert.equal(parallaxBinding.runtimePath.includes("/data/"), false);
+
+  const runtimeAssetTable = result.demo.runtimeResult?.bootstrap?.assetTable || {};
+  const runtimePathFor = (entry) => entry?.file || entry?.path || "";
+  assert.equal(runtimePathFor(runtimeAssetTable["vector.asteroids.ship"]), vectorBinding.runtimePath);
+  assert.equal(runtimePathFor(runtimeAssetTable["tilemap.asteroids-stage"]), tilemapBinding.runtimePath);
+  assert.equal(runtimePathFor(runtimeAssetTable["parallax.asteroids-title"]), parallaxBinding.runtimePath);
+}