Expose asset pipeline + runtime state to debug layer.

DavidQ · DavidQ · commit 874847ee68a6 · 2026-04-14T10:22:55.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,7 +1,6 @@
 MODEL: GPT-5.4
 REASONING: high
 COMMAND:
-- implement asset error handling standard
-- unify error propagation
-- integrate with validation + pipeline
-- roadmap status only update
+- add debug visibility hooks for asset pipeline
+- expose manifest + lookup state
+- 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_15_ASSET_ERROR_HANDLING
+BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY
 
-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.
+Adds debug visibility hooks for asset pipeline + runtime lookup, exposes manifest and lookup state snapshots in debug reporting, and applies a roadmap status-only bracket update.
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY
+BUILD_PR_LEVEL_09_17_ASSET_PERFORMANCE_OPTIMIZATION
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,30 +1,30 @@
 Summary
-- 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.
+- Added debug visibility hooks for asset pipeline and runtime lookup layers.
+- Exposed manifest + lookup state snapshots through shared debug reporting.
+- Kept scope surgical with no engine/runtime behavior redesign.
 
 Implementation
-- 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`:
-  - collects/propagates binding issues, binding rejections, lookup misses, and runtime validation errors
-  - exposes `errors` and `getErrors()` for debug/reporting
+  - exposes `gameAssetManifest`
+  - adds `getDebugState()` snapshot with lookup counters, manifest, and propagated errors
 - Updated `tools/shared/pipeline/assetPipelineTooling.js`:
-  - emits standardized `errors` for invalid tool-contract stage failures
+  - adds `debugState` snapshot in both ready and invalid paths
+  - includes stage/status/record/error summaries and coordinated manifest reference when available
+- Updated `tools/shared/debugVisualizationLayer.js`:
+  - added sections `Asset Runtime State` and `Asset Pipeline State`
+  - renders manifest-domain and lookup/pipeline summary lines for debug visibility
+- Updated touched runtime consumers to pass lookup debug state into debug visualization:
+  - `tools/shared/asteroidsPlatformDemo.js`
+  - `tools/shared/vectorNativeTemplate.js`
+  - `tools/shared/vectorTemplateSampleGame.js`
+  - `tools/shared/vectorAssetSystem.js`
 
 Tests
-- Added `tests/tools/AssetErrorHandlingStandard.test.mjs`
-- Updated `tests/tools/RuntimeAssetValidation.test.mjs`
+- Updated `tests/tools/DebugVisualizationLayer.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`
-  - `Expand testing/validation structure` moved from `[.]` to `[x]`
+  - `debug tools align with engine/debug maturity` 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,36 +1,29 @@
-Validation Checklist - BUILD_PR_LEVEL_09_15_ASSET_ERROR_HANDLING
+Validation Checklist - BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY
 
 Scope
-[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] Debug visibility hooks added for asset pipeline + runtime lookup
+[x] Manifest + lookup state exposed through debug layer
 [x] No engine redesign
-[x] No UI changes
+[x] No gameplay/runtime feature expansion
+[x] No UI redesign work outside debug reporting sections
 
 Code
-[x] Added `tools/shared/pipeline/assetErrorHandling.js`
-[x] Updated `tools/shared/pipeline/runtimeAssetValidation.js`
 [x] Updated `tools/shared/pipeline/runtimeAssetLookup.js`
 [x] Updated `tools/shared/pipeline/assetPipelineTooling.js`
-[x] Added `tests/tools/AssetErrorHandlingStandard.test.mjs`
-[x] Updated `tests/tools/RuntimeAssetValidation.test.mjs`
+[x] Updated `tools/shared/debugVisualizationLayer.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] Updated `tests/tools/DebugVisualizationLayer.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: AssetErrorHandlingStandard, RuntimeAssetValidation, RuntimeAssetLookupConsolidation, AssetPipelineTooling
-[x] Existing regression tests pass: RuntimeAssetBinding, GameAssetManifestCoordinator, ProjectToolDataContracts, AsteroidsAssetReferenceAdoption, AsteroidsPlatformDemo, VectorNativeTemplate, VectorTemplateSampleGame, VectorAssetSystem
+[x] `node --check` passes on touched files
+[x] Focused tests pass: DebugVisualizationLayer, RuntimeAssetLookupConsolidation, AssetPipelineTooling
+[x] Existing regression tests pass: RuntimeAssetValidation, RuntimeAssetBinding, GameAssetManifestCoordinator, ProjectToolDataContracts
+[x] Existing consumer 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
@@ -448,7 +448,7 @@
 - [ ] 2D tool stabilization before 3D tool expansion
 - [ ] 3D prerequisite samples before advanced 3D tools
 - [.] content pipeline tools after asset complexity justifies them
-- [.] debug tools align with engine/debug maturity
+- [x] debug tools align with engine/debug maturity
 - [ ] no standalone showcase-only tool tracks
 
 ### Recent Tool Shell Notes
diff --git a/docs/pr/BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY.md b/docs/pr/BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY.md
@@ -0,0 +1,3 @@
+# BUILD_PR — LEVEL 09_16 — ASSET DEBUG VISIBILITY
+
+Expose asset pipeline + runtime state to debug layer.
diff --git a/tests/tools/AssetPipelineTooling.test.mjs b/tests/tools/AssetPipelineTooling.test.mjs
@@ -39,6 +39,9 @@ export async function run() {
 
   assert.equal(ready.status, "ready");
   assert.deepEqual(ready.errors, []);
+  assert.equal(ready.debugState.pipeline.status, "ready");
+  assert.equal(ready.debugState.pipeline.recordCount, 4);
+  assert.equal(Object.keys(ready.debugState.manifest.domains).length, 4);
   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");
@@ -80,6 +83,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.debugState.pipeline.status, "invalid");
+  assert.equal(invalid.debugState.pipeline.errorCount > 0, 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/DebugVisualizationLayer.test.mjs b/tests/tools/DebugVisualizationLayer.test.mjs
@@ -19,9 +19,36 @@ export async function run() {
     },
     runtimeResult: {
       runtimeLoader: { status: "failed", loadedAssets: [], failedAt: "sprite.hero", reports: [{ code: "MISSING_PACKAGED_ASSET", message: "Missing." }] }
+    },
+    assetRuntimeState: {
+      lookup: {
+        status: "ready",
+        gameId: "asteroids",
+        recordCount: 3,
+        domainCounts: { sprites: 1, tilemaps: 1, parallax: 1, vectors: 0 },
+        rejectedCount: 1
+      },
+      manifest: {
+        domains: { sprites: [{}], tilemaps: [{}], parallax: [{}], vectors: [] }
+      },
+      errors: [{ code: "RUNTIME_BINDING_REJECTED" }]
+    },
+    assetPipelineState: {
+      pipeline: {
+        status: "ready",
+        gameId: "asteroids",
+        recordCount: 4
+      },
+      manifest: {
+        domains: { sprites: [{}], tilemaps: [{}], parallax: [{}], vectors: [{}] }
+      },
+      errors: []
     }
   });
   assert.equal(result.debugVisualization.status, "ready");
   assert.equal(summarizeDebugVisualizationLayer(result), "Debug view: 2 nodes, 1 edges, 1 findings.");
   assert.match(result.debugVisualization.reportText, /\[Runtime Trace\]/);
+  assert.match(result.debugVisualization.reportText, /\[Asset Runtime State\]/);
+  assert.match(result.debugVisualization.reportText, /manifestDomains=4/);
+  assert.match(result.debugVisualization.reportText, /\[Asset Pipeline State\]/);
 }
diff --git a/tests/tools/RuntimeAssetLookupConsolidation.test.mjs b/tests/tools/RuntimeAssetLookupConsolidation.test.mjs
@@ -38,6 +38,11 @@ export async function run() {
   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 strictDebug = strictLookup.getDebugState();
+  assert.equal(strictDebug.lookup.status, "ready");
+  assert.equal(strictDebug.lookup.recordCount, 5);
+  assert.equal(strictDebug.lookup.domainCounts.vectors, 2);
+  assert.equal(Object.keys(strictDebug.manifest.domains).length, 4);
 
   const fallbackLookup = createRuntimeManifestAssetLookup({
     gameId: "TemplateGame",
@@ -55,4 +60,5 @@ export async function run() {
   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);
+  assert.equal(fallbackLookup.getDebugState().lookup.rejectedCount > 0, true);
 }
diff --git a/tools/shared/asteroidsPlatformDemo.js b/tools/shared/asteroidsPlatformDemo.js
@@ -442,6 +442,7 @@ export async function buildAsteroidsPlatformDemo(options = {}) {
     remediationResult,
     packageResult,
     runtimeResult,
+    assetRuntimeState: runtimeLookup.getDebugState?.() || null,
     performanceResult
   });
   const templateResult = buildGameTemplates({
@@ -539,6 +540,7 @@ export async function buildAsteroidsPlatformDemo(options = {}) {
       performanceResult,
       runtimeHandoff: handoff,
       runtimeBinding,
+      runtimeLookupDebug: runtimeLookup.getDebugState?.() || null,
       vectorOnly: {
         requiredVectorIds,
         missingRequiredVectorIds,
diff --git a/tools/shared/debugVisualizationLayer.js b/tools/shared/debugVisualizationLayer.js
@@ -83,6 +83,43 @@ function toProfilerLines(performanceResult) {
   ];
 }
 
+function toAssetRuntimeStateLines(assetRuntimeState) {
+  const lookup = assetRuntimeState?.lookup || {};
+  const manifest = assetRuntimeState?.manifest || null;
+  const errors = Array.isArray(assetRuntimeState?.errors) ? assetRuntimeState.errors : [];
+  if (!manifest && !lookup.status) {
+    return ["asset-runtime=unavailable"];
+  }
+  const domains = lookup.domainCounts && typeof lookup.domainCounts === "object"
+    ? Object.entries(lookup.domainCounts).map(([domain, count]) => `${domain}:${count}`).join(", ")
+    : "none";
+  return [
+    `status=${sanitizeText(lookup.status) || "unknown"}`,
+    `gameId=${sanitizeText(lookup.gameId) || "unknown"}`,
+    `records=${Number.isFinite(lookup.recordCount) ? lookup.recordCount : 0}`,
+    `domains=${domains}`,
+    `rejected=${Number.isFinite(lookup.rejectedCount) ? lookup.rejectedCount : 0}`,
+    `errors=${errors.length}`,
+    `manifestDomains=${Object.keys(manifest?.domains || {}).length}`
+  ];
+}
+
+function toAssetPipelineStateLines(assetPipelineState) {
+  const pipeline = assetPipelineState?.pipeline || {};
+  const manifest = assetPipelineState?.manifest || null;
+  const errors = Array.isArray(assetPipelineState?.errors) ? assetPipelineState.errors : [];
+  if (!pipeline.status && !manifest) {
+    return ["asset-pipeline=unavailable"];
+  }
+  return [
+    `status=${sanitizeText(pipeline.status) || "unknown"}`,
+    `gameId=${sanitizeText(pipeline.gameId) || "unknown"}`,
+    `records=${Number.isFinite(pipeline.recordCount) ? pipeline.recordCount : 0}`,
+    `errors=${errors.length}`,
+    `manifestDomains=${Object.keys(manifest?.domains || {}).length}`
+  ];
+}
+
 function toRemediationLines(remediationResult) {
   const actions = Array.isArray(remediationResult?.remediation?.actions) ? remediationResult.remediation.actions : [];
   return [
@@ -105,6 +142,8 @@ export function buildDebugVisualizationLayer(options = {}) {
     createSection("Remediation Navigation", toRemediationLines(options.remediationResult)),
     createSection("Packaging Report", toPackagingLines(options.packageResult)),
     createSection("Runtime Trace", toRuntimeLines(options.runtimeResult)),
+    createSection("Asset Runtime State", toAssetRuntimeStateLines(options.assetRuntimeState)),
+    createSection("Asset Pipeline State", toAssetPipelineStateLines(options.assetPipelineState)),
     createSection("Profiler", toProfilerLines(options.performanceResult))
   ];
   const summary = `Debug view: ${Object.keys(graph.nodes || {}).length} nodes, ${(graph.edges || []).length} edges, ${options.validationResult?.validation?.findings?.length || 0} findings.`;
diff --git a/tools/shared/pipeline/assetPipelineTooling.js b/tools/shared/pipeline/assetPipelineTooling.js
@@ -183,7 +183,21 @@ export function runAssetPipelineTooling(options = {}) {
         }
       },
       records: [],
-      coordinator: null
+      coordinator: null,
+      debugState: {
+        pipeline: {
+          status: "invalid",
+          gameId,
+          stages: {
+            load: loadStage,
+            validate: validateStage
+          },
+          recordCount: 0,
+          errorCount: errors.length
+        },
+        manifest: null,
+        errors: errors.slice()
+      }
     };
   }
 
@@ -226,6 +240,22 @@ export function runAssetPipelineTooling(options = {}) {
     },
     records: normalizedRecords,
     coordinator,
-    gameAssetManifest
+    gameAssetManifest,
+    debugState: {
+      pipeline: {
+        status: "ready",
+        gameId,
+        stages: {
+          load: loadStage,
+          validate: validateStage,
+          normalize: normalizeStage,
+          emit: emitStage
+        },
+        recordCount: normalizedRecords.length,
+        errorCount: errors.length
+      },
+      manifest: gameAssetManifest.manifest,
+      errors: errors.slice()
+    }
   };
 }
diff --git a/tools/shared/pipeline/runtimeAssetLookup.js b/tools/shared/pipeline/runtimeAssetLookup.js
@@ -160,10 +160,27 @@ export function createRuntimeManifestAssetLookup(options = {}) {
   return {
     binding,
     records,
+    gameAssetManifest: coordinatedManifest,
     errors,
     getErrors() {
       return errors.slice();
     },
+    getDebugState() {
+      return {
+        lookup: {
+          status: binding.status,
+          gameId: safeString(binding.gameId, gameId),
+          recordCount: records.length,
+          domainCounts: Object.fromEntries(
+            Object.entries(binding.domains || {}).map(([domain, entries]) => [domain, Array.isArray(entries) ? entries.length : 0])
+          ),
+          rejectedCount: Array.isArray(binding.rejected) ? binding.rejected.length : 0,
+          errorCount: errors.length
+        },
+        manifest: cloneJson(coordinatedManifest.manifest),
+        errors: errors.slice()
+      };
+    },
     resolvePackagedAsset
   };
 }
diff --git a/tools/shared/vectorAssetSystem.js b/tools/shared/vectorAssetSystem.js
@@ -120,6 +120,7 @@ export async function buildVectorAssetSystem(options = {}) {
     validationResult,
     packageResult,
     runtimeResult,
+    assetRuntimeState: runtimeLookup.getDebugState?.() || null,
     performanceResult
   });
 
@@ -140,6 +141,7 @@ export async function buildVectorAssetSystem(options = {}) {
       validationResult,
       packageResult,
       runtimeResult,
+      runtimeLookupDebug: runtimeLookup.getDebugState?.() || null,
       debugVisualizationResult,
       performanceResult,
       reports,
diff --git a/tools/shared/vectorNativeTemplate.js b/tools/shared/vectorNativeTemplate.js
@@ -333,6 +333,7 @@ export async function buildVectorNativeTemplate(options = {}) {
     validationResult,
     packageResult,
     runtimeResult,
+    assetRuntimeState: runtimeLookup.getDebugState?.() || null,
     performanceResult
   });
   const multiTargetExportResult = buildMultiTargetExport({
@@ -390,6 +391,7 @@ export async function buildVectorNativeTemplate(options = {}) {
       multiTargetExportResult,
       ciValidationResult,
       publishingResult,
+      runtimeLookupDebug: runtimeLookup.getDebugState?.() || null,
       vectorOnly: {
         requiredVectorIds: vectorIds,
         missingVectorIds,
diff --git a/tools/shared/vectorTemplateSampleGame.js b/tools/shared/vectorTemplateSampleGame.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_09_16_ASSET_DEBUG_VISIBILITY`
	`1`	`+BUILD_PR_LEVEL_09_17_ASSET_PERFORMANCE_OPTIMIZATION`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# BUILD_PR — LEVEL 09_16 — ASSET DEBUG VISIBILITY`
	`2`	`+`
	`3`	`+Expose asset pipeline + runtime state to debug layer.`