BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY

DavidQ · DavidQ · commit e07539202b6e · 2026-04-14T10:17:46.000-04:00
diff --git a/-tree-asteroids.txt b/-tree-asteroids.txt
diff --git a/-tree-tmp.txt b/-tree-tmp.txt
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,9 +1,7 @@
-
 MODEL: GPT-5.4
 REASONING: high
 COMMAND:
-- 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)
+- implement asset error handling standard
+- unify error propagation
+- integrate with validation + pipeline
+- roadmap status only update
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,3 +1,3 @@
-BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION
+BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING
 
-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.
+Implements a shared asset error standard, unifies error propagation across runtime validation + runtime lookup + asset pipeline tooling, adds debug-friendly structured error reporting, and applies a status-only roadmap update.
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING
+BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,22 +1,30 @@
 Summary
-- 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.
+- Implemented a shared asset error handling standard for pipeline/runtime layers.
+- Unified error propagation through runtime validation + runtime lookup + pipeline tooling.
+- Added debug-friendly structured error reporting with stable codes/stages.
 
 Implementation
-- 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
+- Added `tools/shared/pipeline/assetErrorHandling.js`:
+  - shared error shape (`level`, `code`, `stage`, `domain`, `assetId`, `message`, `details`)
+  - helper append utilities for consistent propagation
+- Updated `tools/shared/pipeline/runtimeAssetValidation.js`:
+  - emits standardized errors while preserving compatibility `issues` messages
+  - rejects `/data/` runtime/source paths with explicit error codes
+  - validates required domain metadata with stable codes per domain
 - 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`
+  - collects/propagates binding issues, binding rejections, lookup misses, and runtime validation errors
+  - exposes `errors` and `getErrors()` for debug/reporting
+- Updated `tools/shared/pipeline/assetPipelineTooling.js`:
+  - emits standardized `errors` for invalid tool-contract stage failures
+
+Tests
+- Added `tests/tools/AssetErrorHandlingStandard.test.mjs`
+- Updated `tests/tools/RuntimeAssetValidation.test.mjs`
+- Updated `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
+- Updated `tests/tools/AssetPipelineTooling.test.mjs`
+- Updated `tests/run-tests.mjs` registrations
 
 Roadmap (status-only)
 - `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
-  - `Normalize assets/data ownership` moved from `[.]` to `[x]`
-- No roadmap wording/order/prose edits.
+  - `Expand testing/validation structure` moved from `[.]` to `[x]`
+- No roadmap prose/text/order edits.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,30 +1,36 @@
-Validation Checklist - BUILD_PR_LEVEL_09_14_RUNTIME_ASSET_VALIDATION
+Validation Checklist - BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING
 
 Scope
-[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] Asset error handling standard implemented
+[x] Error propagation unified in touched pipeline/runtime layers
+[x] Runtime validation + lookup integration completed
+[x] Debug-friendly structured reporting added
 [x] No engine redesign
-[x] No tool UI work
-[x] No asset format expansion
+[x] No UI changes
 
 Code
-[x] Added `tools/shared/pipeline/runtimeAssetValidation.js`
+[x] Added `tools/shared/pipeline/assetErrorHandling.js`
+[x] Updated `tools/shared/pipeline/runtimeAssetValidation.js`
 [x] Updated `tools/shared/pipeline/runtimeAssetLookup.js`
-[x] Added `tests/tools/RuntimeAssetValidation.test.mjs`
+[x] Updated `tools/shared/pipeline/assetPipelineTooling.js`
+[x] Added `tests/tools/AssetErrorHandlingStandard.test.mjs`
+[x] Updated `tests/tools/RuntimeAssetValidation.test.mjs`
 [x] Updated `tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
+[x] Updated `tests/tools/AssetPipelineTooling.test.mjs`
 [x] Updated `tests/run-tests.mjs`
 
 Validation
+[x] `node --check tools/shared/pipeline/assetErrorHandling.js`
 [x] `node --check tools/shared/pipeline/runtimeAssetValidation.js`
 [x] `node --check tools/shared/pipeline/runtimeAssetLookup.js`
+[x] `node --check tools/shared/pipeline/assetPipelineTooling.js`
+[x] `node --check tests/tools/AssetErrorHandlingStandard.test.mjs`
 [x] `node --check tests/tools/RuntimeAssetValidation.test.mjs`
 [x] `node --check tests/tools/RuntimeAssetLookupConsolidation.test.mjs`
+[x] `node --check tests/tools/AssetPipelineTooling.test.mjs`
 [x] `node --check tests/run-tests.mjs`
-[x] Focused tests pass: RuntimeAssetValidation, RuntimeAssetLookupConsolidation
-[x] Existing tests pass: RuntimeAssetBinding, GameAssetManifestCoordinator, AssetPipelineTooling, ProjectToolDataContracts
-[x] Existing consumer/lane tests pass: AsteroidsAssetReferenceAdoption, AsteroidsPlatformDemo, VectorNativeTemplate, VectorTemplateSampleGame, VectorAssetSystem
+[x] Focused tests pass: AssetErrorHandlingStandard, RuntimeAssetValidation, RuntimeAssetLookupConsolidation, AssetPipelineTooling
+[x] Existing regression tests pass: RuntimeAssetBinding, GameAssetManifestCoordinator, ProjectToolDataContracts, 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
@@ -595,7 +595,7 @@
 - [ ] Establish games/_template and normalize games layer
 - [x] Normalize tools/shared and tool boundaries
 - [x] Normalize assets/data ownership
-- [.] Expand testing/validation structure
+- [x] Expand testing/validation structure
 
 ### Later Capability Lanes
 - [ ] FEATURE: Fullscreen Bezel Overlay System - Render game in full screen with optional bezel artwork layer (static or animated) surrounding the active playfield, preserving aspect ratio and supporting per-game/theme bezel assets without modifying core engine rendering.
diff --git a/docs/pr/BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING.md b/docs/pr/BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING.md
@@ -0,0 +1,16 @@
+# BUILD_PR — LEVEL 09_15 — ASSET ERROR HANDLING
+
+## Objective
+Introduce consistent error handling and reporting for asset pipeline, manifest binding, and runtime validation layers.
+
+## Scope
+- standardize error objects
+- propagate errors through pipeline + runtime layers
+- add debug-friendly reporting
+
+## Out of Scope
+- no engine redesign
+- no UI changes
+
+## Roadmap Instruction
+Update roadmap status only. No text edits.
diff --git a/tests/run-tests.mjs b/tests/run-tests.mjs
@@ -91,6 +91,7 @@ import { run as runAssetRemediationSystem } from './tools/AssetRemediationSystem
 import { run as runToolBoundaryEnforcement } from './tools/ToolBoundaryEnforcement.test.mjs';
 import { run as runProjectToolDataContracts } from './tools/ProjectToolDataContracts.test.mjs';
 import { run as runAssetPipelineTooling } from './tools/AssetPipelineTooling.test.mjs';
+import { run as runAssetErrorHandlingStandard } from './tools/AssetErrorHandlingStandard.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';
@@ -211,6 +212,7 @@ const tests = [
     ['ToolBoundaryEnforcement', runToolBoundaryEnforcement],
     ['ProjectToolDataContracts', runProjectToolDataContracts],
     ['AssetPipelineTooling', runAssetPipelineTooling],
+    ['AssetErrorHandlingStandard', runAssetErrorHandlingStandard],
     ['GameAssetManifestCoordinator', runGameAssetManifestCoordinator],
     ['RuntimeAssetBinding', runRuntimeAssetBinding],
     ['RuntimeAssetLookupConsolidation', runRuntimeAssetLookupConsolidation],
diff --git a/tests/tools/AssetErrorHandlingStandard.test.mjs b/tests/tools/AssetErrorHandlingStandard.test.mjs
@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import { createAssetError, appendAssetError, appendAssetErrors } from "../../tools/shared/pipeline/assetErrorHandling.js";
+
+export async function run() {
+  const normalized = createAssetError({
+    level: "warning",
+    code: "CODE_SAMPLE",
+    stage: "runtime-validation",
+    domain: "vectors",
+    assetId: "vector.ship",
+    message: "Sample warning",
+    details: { source: "test" }
+  });
+  assert.equal(normalized.level, "warning");
+  assert.equal(normalized.code, "CODE_SAMPLE");
+  assert.equal(normalized.stage, "runtime-validation");
+  assert.equal(normalized.domain, "vectors");
+  assert.equal(normalized.assetId, "vector.ship");
+  assert.equal(normalized.details.source, "test");
+
+  const errors = [];
+  appendAssetError(errors, {
+    code: "ERR_ONE",
+    stage: "lookup",
+    message: "first"
+  });
+  appendAssetErrors(errors, [
+    { code: "ERR_TWO", stage: "validate", message: "second" },
+    { code: "ERR_THREE", stage: "emit", message: "third" }
+  ]);
+  assert.equal(errors.length, 3);
+  assert.deepEqual(errors.map((entry) => entry.code), ["ERR_ONE", "ERR_TWO", "ERR_THREE"]);
+}
diff --git a/tests/tools/AssetPipelineTooling.test.mjs b/tests/tools/AssetPipelineTooling.test.mjs
@@ -38,6 +38,7 @@ export async function run() {
   });
 
   assert.equal(ready.status, "ready");
+  assert.deepEqual(ready.errors, []);
   assert.equal(ready.stages.validate.valid, true);
   assert.equal(ready.records.length, 4);
   assert.equal(ready.stages.emit.coordinatorPath, "games/asteroids/assets/asteroids.assets.json");
@@ -77,6 +78,8 @@ export async function run() {
   });
 
   assert.equal(invalid.status, "invalid");
+  assert.equal(Array.isArray(invalid.errors), true);
+  assert.equal(invalid.errors.some((entry) => entry.code === "PIPELINE_TOOL_CONTRACT_INVALID"), true);
   assert.equal(invalid.stages.validate.valid, false);
   assert.equal(
     invalid.stages.validate.issues.some((entry) => entry.includes("sprite-editor: project.assetRefs block is required.")),
diff --git a/tests/tools/RuntimeAssetLookupConsolidation.test.mjs b/tests/tools/RuntimeAssetLookupConsolidation.test.mjs
@@ -34,6 +34,10 @@ export async function run() {
   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");
+  const strictCodes = strictLookup.getErrors().map((entry) => entry.code);
+  assert.equal(strictCodes.includes("RUNTIME_BINDING_REJECTED"), true);
+  assert.equal(strictCodes.includes("RUNTIME_VECTOR_METADATA_REQUIRED"), true);
+  assert.equal(strictCodes.includes("RUNTIME_LOOKUP_MISSING_BINDING"), true);
 
   const fallbackLookup = createRuntimeManifestAssetLookup({
     gameId: "TemplateGame",
@@ -50,4 +54,5 @@ export async function run() {
   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);
+  assert.equal(fallbackLookup.getErrors().some((entry) => entry.code === "RUNTIME_BINDING_REJECTED"), true);
 }
diff --git a/tests/tools/RuntimeAssetValidation.test.mjs b/tests/tools/RuntimeAssetValidation.test.mjs
@@ -25,6 +25,7 @@ export async function run() {
   });
   assert.equal(dataPathBlocked.valid, false);
   assert.equal(dataPathBlocked.issues.some((issue) => issue.includes("/data/")), true);
+  assert.equal(dataPathBlocked.errors.some((entry) => entry.code === "RUNTIME_PATH_DATA_BLOCKED"), true);
 
   const invalidTilemap = validateRuntimeResolvedAsset({
     domain: "tilemaps",
@@ -36,4 +37,5 @@ export async function run() {
   });
   assert.equal(invalidTilemap.valid, false);
   assert.equal(invalidTilemap.issues.some((issue) => issue.includes("Tilemaps")), true);
+  assert.equal(invalidTilemap.errors.some((entry) => entry.code === "RUNTIME_TILEMAP_METADATA_REQUIRED"), true);
 }
diff --git a/tools/shared/pipeline/assetErrorHandling.js b/tools/shared/pipeline/assetErrorHandling.js
@@ -0,0 +1,41 @@
+import { safeString } from "../projectSystemValueUtils.js";
+
+export const ASSET_ERROR_LEVELS = Object.freeze({
+  ERROR: "error",
+  WARNING: "warning",
+  INFO: "info"
+});
+
+function toErrorLevel(value) {
+  const level = safeString(value, "").toLowerCase();
+  if (level === ASSET_ERROR_LEVELS.WARNING || level === ASSET_ERROR_LEVELS.INFO) {
+    return level;
+  }
+  return ASSET_ERROR_LEVELS.ERROR;
+}
+
+export function createAssetError(options = {}) {
+  return {
+    level: toErrorLevel(options.level),
+    code: safeString(options.code, "ASSET_ERROR"),
+    stage: safeString(options.stage, "unknown"),
+    domain: safeString(options.domain, ""),
+    assetId: safeString(options.assetId, ""),
+    message: safeString(options.message, "Asset processing error."),
+    details: options.details && typeof options.details === "object" ? { ...options.details } : {}
+  };
+}
+
+export function appendAssetError(target, error) {
+  const next = Array.isArray(target) ? target : [];
+  next.push(createAssetError(error));
+  return next;
+}
+
+export function appendAssetErrors(target, errors) {
+  const next = Array.isArray(target) ? target : [];
+  (Array.isArray(errors) ? errors : []).forEach((error) => {
+    appendAssetError(next, error);
+  });
+  return next;
+}
diff --git a/tools/shared/pipeline/assetPipelineTooling.js b/tools/shared/pipeline/assetPipelineTooling.js
@@ -1,6 +1,7 @@
 import { safeString } from "../projectSystemValueUtils.js";
 import { validateToolStateContract } from "../projectToolIntegration.js";
 import { coordinateGameAssetManifest } from "./gameAssetManifestCoordinator.js";
+import { appendAssetErrors } from "./assetErrorHandling.js";
 
 export const ASSET_PIPELINE_TOOLING_SCHEMA = "html-js-gaming.asset-pipeline-tooling";
 export const ASSET_PIPELINE_TOOLING_VERSION = 1;
@@ -137,6 +138,7 @@ export function runAssetPipelineTooling(options = {}) {
   const gameId = normalizeGameId(options.gameId);
   const loadedRecords = collectRecords(options.domainInputs);
   const contractValidation = validateToolContracts(options.toolStates);
+  const errors = [];
 
   const loadStage = {
     stage: ASSET_PIPELINE_TOOLING_STAGES.LOAD,
@@ -153,10 +155,21 @@ export function runAssetPipelineTooling(options = {}) {
   };
 
   if (!validateStage.valid) {
+    appendAssetErrors(
+      errors,
+      validateStage.issues.map((message) => ({
+        code: "PIPELINE_TOOL_CONTRACT_INVALID",
+        stage: "validate",
+        message,
+        domain: "",
+        assetId: ""
+      }))
+    );
     return {
       schema: ASSET_PIPELINE_TOOLING_SCHEMA,
       version: ASSET_PIPELINE_TOOLING_VERSION,
       status: "invalid",
+      errors,
       stages: {
         load: loadStage,
         validate: validateStage,
@@ -204,6 +217,7 @@ export function runAssetPipelineTooling(options = {}) {
     schema: ASSET_PIPELINE_TOOLING_SCHEMA,
     version: ASSET_PIPELINE_TOOLING_VERSION,
     status: "ready",
+    errors,
     stages: {
       load: loadStage,
       validate: validateStage,
diff --git a/tools/shared/pipeline/runtimeAssetLookup.js b/tools/shared/pipeline/runtimeAssetLookup.js
diff --git a/tools/shared/pipeline/runtimeAssetValidation.js b/tools/shared/pipeline/runtimeAssetValidation.js

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