BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,74 +1,7 @@
-# MODEL
-GPT-5.4
-
-# REASONING
-high
-
-# COMMAND
-Create BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
-
-## Mission
-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 approved binding surface introduced in 09_11.
-Do not bypass it with direct asset path assumptions where touched.
-
-## Required scope
-- 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 add gameplay features
-- 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_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
-
-## Validation
-Run focused checks only:
-- node --check on touched files
-- focused adoption tests
-- existing runtime binding tests
-- existing GameAssetManifestCoordinator tests
-- existing AssetPipelineTooling tests
-- existing ProjectToolDataContracts tests as needed
-
-## Success definition
-- 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/`
+MODEL: GPT-5.4
+REASONING: high
+COMMAND:
+- Consolidate runtime asset lookup into shared interface
+- Replace duplicate lookup logic where touched
+- Use manifest binding as source of truth
+- Update roadmap status only (no text changes)

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION
+BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION
 
-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.
+Consolidates runtime asset lookup into a shared manifest-backed interface, replaces duplicated runtime lookup logic in touched consumers, enforces manifest binding as the source of truth for bindable domains, and applies a status-only roadmap bracket update.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION
+BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION

docs/dev/reports/change_summary.txt

@@ -1,26 +1,23 @@
 Summary
-- 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.
+- Consolidated runtime asset lookup behind one shared interface: `tools/shared/pipeline/runtimeAssetLookup.js`.
+- Replaced duplicated runtime lookup resolver logic in touched consumers with the shared manifest-backed lookup.
+- Kept manifest binding as the lookup source of truth for bindable runtime asset domains.
 
-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
+Implementation
+- Added `createRuntimeManifestAssetLookup` and `getRuntimeBindingDomain`:
+  - Builds/uses `coordinateGameAssetManifest` + `createRuntimeAssetBinding`
+  - Exposes `resolvePackagedAsset` for runtime loaders
+  - Supports strict (`missingBindingBehavior: "null"`) and fallback (`"static"`) missing-binding handling
+- Replaced local duplicate resolver logic in:
+  - `tools/shared/asteroidsPlatformDemo.js`
+  - `tools/shared/vectorNativeTemplate.js`
+  - `tools/shared/vectorTemplateSampleGame.js`
+  - `tools/shared/vectorAssetSystem.js`
+- Added focused consolidation test:
+  - `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
+- Registered the test in `tests/run-tests.mjs`.
 
-Scope guard
-- No engine core changes.
-- No tool UI redesign.
-- No gameplay/runtime feature expansion.
-- No repo-wide migration.
-- No asset moves.
-
-Roadmap
-- No roadmap file changes were required in this checkpoint.
+Roadmap (status-only)
+- Updated one bracket status only in `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`:
+  - `Normalize tools/shared and tool boundaries` moved from `[.]` to `[x]`
+- No roadmap prose/order/wording edits.

docs/dev/reports/validation_checklist.txt

@@ -1,39 +1,32 @@
-Validation Checklist - BUILD_PR_LEVEL_09_12_ASSET_REFERENCE_ADOPTION
+Validation Checklist - BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION
 
 Scope
-[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 new asset format work introduced
+[x] Runtime asset lookup consolidated via shared interface
+[x] Duplicate lookup logic replaced where touched
+[x] Manifest binding used as source of truth for bindable runtime domains
+[x] No engine-core changes
+[x] No tool UI changes
 
-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
+Code
+[x] Added `tools/shared/pipeline/runtimeAssetLookup.js`
+[x] Updated `tools/shared/asteroidsPlatformDemo.js`
+[x] Updated `tools/shared/vectorNativeTemplate.js`
+[x] Updated `tools/shared/vectorTemplateSampleGame.js`
+[x] Updated `tools/shared/vectorAssetSystem.js`
+[x] Added `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
+[x] Updated `tests/run-tests.mjs`
 
 Validation
+[x] `node --check tools/shared/pipeline/runtimeAssetLookup.js`
 [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
+[x] `node --check tools/shared/vectorNativeTemplate.js`
+[x] `node --check tools/shared/vectorTemplateSampleGame.js`
+[x] `node --check tools/shared/vectorAssetSystem.js`
+[x] `node --check tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
+[x] Focused test passes: `RuntimeAssetLookupConsolidation`
+[x] Existing tests pass: RuntimeAssetBinding, GameAssetManifestCoordinator, AssetPipelineTooling, ProjectToolDataContracts
+[x] Existing touched-consumer non-regression tests pass: AsteroidsAssetReferenceAdoption, AsteroidsPlatformDemo, VectorNativeTemplate, VectorTemplateSampleGame, VectorAssetSystem
 
 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
-[x] docs/dev/codex_commands.md included
-[x] docs/dev/commit_comment.txt included
-[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_12_ASSET_REFERENCE_ADOPTION.zip`
-
+[x] Status-only update applied
+[x] No roadmap prose/text/order changes

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -593,7 +593,7 @@
 - [ ] Apply master roadmap baseline
 - [ ] Normalize samples phase structure
 - [ ] Establish games/_template and normalize games layer
-- [.] Normalize tools/shared and tool boundaries
+- [x] Normalize tools/shared and tool boundaries
 - [.] Normalize assets/data ownership
 - [.] Expand testing/validation structure
 

docs/pr/BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION.md

@@ -0,0 +1,24 @@
+# BUILD_PR — LEVEL 09_13 — ASSET LOOKUP CONSOLIDATION
+
+## Objective
+Consolidate all runtime asset lookup paths into a single shared lookup interface built on top of the manifest-driven binding layer.
+
+## Purpose
+Remove remaining fragmented lookup logic and ensure all runtime consumers use one consistent resolution path.
+
+## Scope
+- centralize lookup helpers
+- remove duplicated lookup logic where touched
+- enforce manifest-first lookup
+- preserve runtime/editor boundary
+
+## Out of Scope
+- no broad refactor
+- no engine changes
+- no tool UI changes
+
+## Roadmap Instruction
+Update roadmap status only. No text edits.
+
+## Deliverables
+Standard docs/dev bundle.

tests/run-tests.mjs

@@ -93,6 +93,7 @@ import { run as runProjectToolDataContracts } from './tools/ProjectToolDataContr
 import { run as runAssetPipelineTooling } from './tools/AssetPipelineTooling.test.mjs';
 import { run as runGameAssetManifestCoordinator } from './tools/GameAssetManifestCoordinator.test.mjs';
 import { run as runRuntimeAssetBinding } from './tools/RuntimeAssetBinding.test.mjs';
+import { run as runRuntimeAssetLookupConsolidation } from './tools/RuntimeAssetLookupConsolidation.test.mjs';
 import { run as runToolEntryLaunchContract } from './tools/ToolEntryLaunchContract.test.mjs';
 import { run as runProjectPackagingSystem } from './tools/ProjectPackagingSystem.test.mjs';
 import { run as runRuntimeAssetLoader } from './tools/RuntimeAssetLoader.test.mjs';
@@ -211,6 +212,7 @@ const tests = [
     ['AssetPipelineTooling', runAssetPipelineTooling],
     ['GameAssetManifestCoordinator', runGameAssetManifestCoordinator],
     ['RuntimeAssetBinding', runRuntimeAssetBinding],
+    ['RuntimeAssetLookupConsolidation', runRuntimeAssetLookupConsolidation],
     ['ToolEntryLaunchContract', runToolEntryLaunchContract],
     ['ProjectPackagingSystem', runProjectPackagingSystem],
     ['RuntimeAssetLoader', runRuntimeAssetLoader],

tests/tools/RuntimeAssetLookupConsolidation.test.mjs

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { createRuntimeManifestAssetLookup, getRuntimeBindingDomain } from "../../tools/shared/pipeline/runtimeAssetLookup.js";
+
+export async function run() {
+  assert.equal(getRuntimeBindingDomain("vector.ship"), "vectors");
+  assert.equal(getRuntimeBindingDomain("tilemap.main"), "tilemaps");
+  assert.equal(getRuntimeBindingDomain("parallax.bg"), "parallax");
+  assert.equal(getRuntimeBindingDomain("palette.hud"), "");
+
+  const strictLookup = createRuntimeManifestAssetLookup({
+    gameId: "Asteroids",
+    runtimeAssetSources: {
+      "vector.ship": { file: "games/asteroids/assets/vectors/ship.vector.json", kind: "vector" },
+      "tilemap.main": { file: "games/asteroids/assets/tilemaps/main.tilemap.json", kind: "tilemap" },
+      "parallax.bg": { file: "games/asteroids/assets/parallax/background.parallax.json", kind: "parallaxLayer" },
+      "vector.tool-only": { file: "games/asteroids/assets/vectors/data/tool-only.vector.json", kind: "vector" },
+      "palette.hud": { kind: "palette", colors: ["#ffffffff"] }
+    },
+    missingBindingBehavior: "null"
+  });
+
+  assert.equal(strictLookup.binding.status, "ready");
+  assert.equal(strictLookup.binding.issues.length, 0);
+  assert.equal(strictLookup.binding.domains.vectors.length, 1);
+  assert.equal(strictLookup.binding.domains.tilemaps.length, 1);
+  assert.equal(strictLookup.binding.domains.parallax.length, 1);
+  assert.equal(
+    strictLookup.binding.rejected.some((entry) => entry.assetId === "vector.tool-only" && entry.reason === "non-runtime-path"),
+    true
+  );
+
+  assert.equal(strictLookup.resolvePackagedAsset({ id: "vector.ship", type: "vector" }).file, "games/asteroids/assets/vectors/ship.vector.json");
+  assert.equal(strictLookup.resolvePackagedAsset({ id: "vector.tool-only", type: "vector" }), null);
+  assert.equal(strictLookup.resolvePackagedAsset({ id: "palette.hud", type: "palette" }).kind, "palette");
+
+  const fallbackLookup = createRuntimeManifestAssetLookup({
+    gameId: "TemplateGame",
+    runtimeAssetSources: {
+      "vector.template.player": {
+        file: "tools/templates/vector-native-arcade/assets/data/vectors/template-player.vector.json",
+        path: "tools/templates/vector-native-arcade/assets/data/vectors/template-player.vector.json",
+        kind: "vector"
+      }
+    },
+    missingBindingBehavior: "static"
+  });
+
+  const fallbackResolved = fallbackLookup.resolvePackagedAsset({ id: "vector.template.player", type: "vector" });
+  assert.equal(fallbackResolved.file, "tools/templates/vector-native-arcade/assets/data/vectors/template-player.vector.json");
+  assert.equal(fallbackLookup.binding.domains.vectors.length, 0);
+}