BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION

DavidQ · DavidQ · commit b23ab8712ee7 · 2026-04-14T10:12:34.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,7 +1,9 @@
+
 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
+- Add runtime asset validation layer
+- Validate manifest-resolved assets
+- Reject `/data/` paths at runtime
+- Integrate with lookup layer
 - Update roadmap status only (no text changes)
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,3 +1,3 @@
-BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION
+BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION
 
-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.
+Adds runtime asset validation for manifest-resolved assets, rejects `/data/` paths at runtime, integrates validation into shared runtime lookup resolution, and applies a status-only roadmap bracket update.
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION
+BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,23 +1,22 @@
 Summary
-- 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.
+- Added a runtime asset validation layer integrated into shared runtime lookup.
+- Manifest-resolved assets are now validated before runtime use.
+- Runtime `/data/` path resolution is rejected in validation.
 
 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`.
+- Added `tools/shared/pipeline/runtimeAssetValidation.js`:
+  - validates manifest-resolved runtime assets by domain (`sprites`, `tilemaps`, `parallax`, `vectors`)
+  - enforces required runtime path and domain-specific minimal field checks
+  - rejects any `/data/` runtime path/source path usage
+- Updated `tools/shared/pipeline/runtimeAssetLookup.js`:
+  - integrates `validateRuntimeResolvedAsset` into `resolvePackagedAsset`
+  - returns `null` for invalid manifest-resolved assets so runtime loader blocks consumption
+- Added focused tests:
+  - `tests/tools/RuntimeAssetValidation.test.mjs`
+  - updated `tests/tools/RuntimeAssetLookupConsolidation.test.mjs` for validation integration behavior
+  - registered `RuntimeAssetValidation` in `tests/run-tests.mjs`
 
 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/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+  - `Normalize assets/data ownership` moved from `[.]` to `[x]`
+- No roadmap wording/order/prose edits.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,31 +1,30 @@
-Validation Checklist - BUILD_PR_LEVEL_09_13_ASSET_LOOKUP_CONSOLIDATION
+Validation Checklist - BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION
 
 Scope
-[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
+[x] Runtime asset validation layer added
+[x] Manifest-resolved runtime assets validated before use
+[x] `/data/` runtime paths rejected
+[x] Validation integrated with shared lookup layer
+[x] No engine redesign
+[x] No tool UI work
+[x] No asset format expansion
 
 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] Added `tools/shared/pipeline/runtimeAssetValidation.js`
+[x] Updated `tools/shared/pipeline/runtimeAssetLookup.js`
+[x] Added `tests/tools/RuntimeAssetValidation.test.mjs`
+[x] Updated `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
 [x] Updated `tests/run-tests.mjs`
 
 Validation
+[x] `node --check tools/shared/pipeline/runtimeAssetValidation.js`
 [x] `node --check tools/shared/pipeline/runtimeAssetLookup.js`
-[x] `node --check tools/shared/asteroidsPlatformDemo.js`
-[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/RuntimeAssetValidation.test.mjs`
 [x] `node --check tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
-[x] Focused test passes: `RuntimeAssetLookupConsolidation`
+[x] `node --check tests/run-tests.mjs`
+[x] Focused tests pass: RuntimeAssetValidation, RuntimeAssetLookupConsolidation
 [x] Existing tests pass: RuntimeAssetBinding, GameAssetManifestCoordinator, AssetPipelineTooling, ProjectToolDataContracts
-[x] Existing touched-consumer non-regression tests pass: AsteroidsAssetReferenceAdoption, AsteroidsPlatformDemo, VectorNativeTemplate, VectorTemplateSampleGame, VectorAssetSystem
+[x] Existing consumer/lane tests pass: AsteroidsAssetReferenceAdoption, AsteroidsPlatformDemo, VectorNativeTemplate, VectorTemplateSampleGame, VectorAssetSystem
 
 Roadmap
 [x] Status-only update applied
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -594,7 +594,7 @@
 - [ ] Normalize samples phase structure
 - [ ] Establish games/_template and normalize games layer
 - [x] Normalize tools/shared and tool boundaries
-- [.] Normalize assets/data ownership
+- [x] Normalize assets/data ownership
 - [.] Expand testing/validation structure
 
 ### Later Capability Lanes
diff --git a/docs/pr/BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION.md b/docs/pr/BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION.md
@@ -0,0 +1,22 @@
+
+# BUILD_PR — LEVEL 09_14 — RUNTIME ASSET VALIDATION
+
+## Objective
+Introduce a runtime-safe validation layer that verifies resolved assets (post-lookup) meet expected contracts and are safe for consumption.
+
+## Scope
+- validate manifest-resolved assets before runtime use
+- ensure no `/data/` assets leak into runtime
+- validate required fields per domain (sprites, tilemaps, parallax, vectors)
+- integrate with existing lookup layer
+
+## Out of Scope
+- no engine redesign
+- no tool UI work
+- no asset format expansion
+
+## Roadmap Instruction
+Update roadmap status only. No text edits.
+
+## Deliverables
+Standard docs/dev bundle.
diff --git a/tests/run-tests.mjs b/tests/run-tests.mjs
@@ -94,6 +94,7 @@ import { run as runAssetPipelineTooling } from './tools/AssetPipelineTooling.tes
 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 runRuntimeAssetValidation } from './tools/RuntimeAssetValidation.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';
@@ -213,6 +214,7 @@ const tests = [
     ['GameAssetManifestCoordinator', runGameAssetManifestCoordinator],
     ['RuntimeAssetBinding', runRuntimeAssetBinding],
     ['RuntimeAssetLookupConsolidation', runRuntimeAssetLookupConsolidation],
+    ['RuntimeAssetValidation', runRuntimeAssetValidation],
     ['ToolEntryLaunchContract', runToolEntryLaunchContract],
     ['ProjectPackagingSystem', runProjectPackagingSystem],
     ['RuntimeAssetLoader', runRuntimeAssetLoader],
diff --git a/tests/tools/RuntimeAssetLookupConsolidation.test.mjs b/tests/tools/RuntimeAssetLookupConsolidation.test.mjs
@@ -13,6 +13,7 @@ export async function run() {
       "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.bad": { file: "games/asteroids/assets/vectors/bad.vector.json" },
       "vector.tool-only": { file: "games/asteroids/assets/vectors/data/tool-only.vector.json", kind: "vector" },
       "palette.hud": { kind: "palette", colors: ["#ffffffff"] }
     },
@@ -21,7 +22,7 @@ export async function run() {
 
   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.vectors.length, 2);
   assert.equal(strictLookup.binding.domains.tilemaps.length, 1);
   assert.equal(strictLookup.binding.domains.parallax.length, 1);
   assert.equal(
@@ -30,6 +31,7 @@ export async function run() {
   );
 
   assert.equal(strictLookup.resolvePackagedAsset({ id: "vector.ship", type: "vector" }).file, "games/asteroids/assets/vectors/ship.vector.json");
+  assert.equal(strictLookup.resolvePackagedAsset({ id: "vector.bad", type: "vector" }), null);
   assert.equal(strictLookup.resolvePackagedAsset({ id: "vector.tool-only", type: "vector" }), null);
   assert.equal(strictLookup.resolvePackagedAsset({ id: "palette.hud", type: "palette" }).kind, "palette");
 
diff --git a/tests/tools/RuntimeAssetValidation.test.mjs b/tests/tools/RuntimeAssetValidation.test.mjs
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { validateRuntimeResolvedAsset } from "../../tools/shared/pipeline/runtimeAssetValidation.js";
+
+export async function run() {
+  const validVector = validateRuntimeResolvedAsset({
+    domain: "vectors",
+    assetId: "vector.ship",
+    runtimePath: "games/asteroids/assets/vectors/ship.vector.json",
+    source: {
+      kind: "vector",
+      file: "games/asteroids/assets/vectors/ship.vector.json",
+      runtimeKind: "vector-geometry"
+    }
+  });
+  assert.equal(validVector.valid, true);
+
+  const dataPathBlocked = validateRuntimeResolvedAsset({
+    domain: "vectors",
+    assetId: "vector.tool-only",
+    runtimePath: "games/asteroids/assets/vectors/data/tool-only.vector.json",
+    source: {
+      kind: "vector",
+      file: "games/asteroids/assets/vectors/data/tool-only.vector.json"
+    }
+  });
+  assert.equal(dataPathBlocked.valid, false);
+  assert.equal(dataPathBlocked.issues.some((issue) => issue.includes("/data/")), true);
+
+  const invalidTilemap = validateRuntimeResolvedAsset({
+    domain: "tilemaps",
+    assetId: "tilemap.main",
+    runtimePath: "games/asteroids/assets/tilemaps/main.tilemap.json",
+    source: {
+      file: "games/asteroids/assets/tilemaps/main.tilemap.json"
+    }
+  });
+  assert.equal(invalidTilemap.valid, false);
+  assert.equal(invalidTilemap.issues.some((issue) => issue.includes("Tilemaps")), true);
+}
diff --git a/tools/shared/pipeline/runtimeAssetLookup.js b/tools/shared/pipeline/runtimeAssetLookup.js
@@ -2,6 +2,7 @@ import { cloneJson } from "../../../src/shared/utils/jsonUtils.js";
 import { safeString } from "../projectSystemValueUtils.js";
 import { coordinateGameAssetManifest } from "./gameAssetManifestCoordinator.js";
 import { createRuntimeAssetBinding, resolveRuntimeAsset } from "./runtimeAssetBinding.js";
+import { validateRuntimeResolvedAsset } from "./runtimeAssetValidation.js";
 
 const RUNTIME_BINDING_PREFIXES = Object.freeze({
   "vector.": "vectors",
@@ -111,6 +112,17 @@ export function createRuntimeManifestAssetLookup(options = {}) {
     if (typeof mergedSource.path === "string") {
       mergedSource.path = runtimeRecord.runtimePath;
     }
+
+    const validation = validateRuntimeResolvedAsset({
+      domain,
+      assetId,
+      runtimePath: runtimeRecord.runtimePath,
+      source: mergedSource
+    });
+    if (!validation.valid) {
+      return null;
+    }
+
     return mergedSource;
   }
 
diff --git a/tools/shared/pipeline/runtimeAssetValidation.js b/tools/shared/pipeline/runtimeAssetValidation.js
@@ -0,0 +1,91 @@
+import { safeString } from "../projectSystemValueUtils.js";
+import { RUNTIME_ACTIVE_DOMAINS } from "./runtimeAssetBinding.js";
+
+function asObject(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+function hasText(value) {
+  return safeString(value, "").length > 0;
+}
+
+function hasRuntimePath(source) {
+  return hasText(source.file) || hasText(source.path);
+}
+
+function includesDataPath(pathValue) {
+  return safeString(pathValue, "").includes("/data/");
+}
+
+function validateRequiredFields(domain, source) {
+  const issues = [];
+  const assetSource = asObject(source);
+
+  if (!hasRuntimePath(assetSource)) {
+    issues.push(`Domain ${domain} requires source.file or source.path.`);
+    return issues;
+  }
+
+  if (domain === "vectors") {
+    const valid = safeString(assetSource.kind, "") === "vector"
+      || safeString(assetSource.type, "") === "vector"
+      || safeString(assetSource.runtimeKind, "") === "vector-geometry"
+      || Array.isArray(assetSource.renderables)
+      || Array.isArray(assetSource.layers);
+    if (!valid) {
+      issues.push("Vectors require vector-kind runtime source metadata.");
+    }
+  } else if (domain === "tilemaps") {
+    const valid = safeString(assetSource.kind, "") === "tilemap"
+      || (assetSource.runtimeEntry && typeof assetSource.runtimeEntry === "object")
+      || (assetSource.visualPreference && typeof assetSource.visualPreference === "object");
+    if (!valid) {
+      issues.push("Tilemaps require tilemap-kind runtime source metadata.");
+    }
+  } else if (domain === "parallax") {
+    const kind = safeString(assetSource.kind, "");
+    const valid = kind === "parallax" || kind === "parallaxLayer" || hasText(assetSource.role);
+    if (!valid) {
+      issues.push("Parallax assets require parallax-kind runtime source metadata.");
+    }
+  } else if (domain === "sprites") {
+    const valid = safeString(assetSource.kind, "") === "sprite"
+      || safeString(assetSource.type, "") === "sprite"
+      || Array.isArray(assetSource.frames)
+      || hasText(assetSource.imageId);
+    if (!valid) {
+      issues.push("Sprites require sprite-kind runtime source metadata.");
+    }
+  }
+
+  return issues;
+}
+
+export function validateRuntimeResolvedAsset(options = {}) {
+  const domain = safeString(options.domain, "").toLowerCase();
+  const assetId = safeString(options.assetId, "");
+  const source = asObject(options.source);
+  const runtimePath = safeString(options.runtimePath || source.file || source.path, "");
+  const issues = [];
+
+  if (!RUNTIME_ACTIVE_DOMAINS.includes(domain)) {
+    issues.push(`Unsupported runtime domain ${domain || "unknown"}.`);
+  }
+  if (!assetId) {
+    issues.push("Runtime asset id is required.");
+  }
+  if (!runtimePath) {
+    issues.push("Runtime asset path is required.");
+  } else if (includesDataPath(runtimePath)) {
+    issues.push(`Runtime asset ${assetId || "unknown"} cannot resolve from /data/ path.`);
+  }
+  if (includesDataPath(source.file) || includesDataPath(source.path)) {
+    issues.push(`Runtime asset ${assetId || "unknown"} source cannot reference /data/ path.`);
+  }
+  issues.push(...validateRequiredFields(domain, source));
+
+  return {
+    valid: issues.length === 0,
+    issues
+  };
+}
diff --git a/tree-asteroids.txt b/tree-asteroids.txt

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION`
	`1`	`+BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING`