BUILD_PR_LEVEL_09_10_GAME_ASSET_MANIFEST_COORDINATION

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,73 +1,3 @@
-# MODEL
-GPT-5.4
-
-# REASONING
-high
-
-# COMMAND
-Create BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
-
-## Mission
-Implement the shared asset pipeline layer that converts validated tool-authored data into deterministic runtime-facing assets.
-
-## Dependency context
-This PR follows:
-- 09_04 asset structure simplification
-- 09_05 shared asset handoff enforcement
-- 09_06 tool launch contract alignment
-- 09_07 tool boundary normalization
-- 09_08 tool data contracts
-
-Use 09_08 contract enforcement as the validation gate for this pipeline.
-
-## Required scope
-- create a shared pipeline surface under `tools/shared`
-- centralize load → validate → normalize → emit stages
-- preserve runtime vs tool-data split:
-  - runtime in `assets/<domain>/`
-  - tool/editor data in `assets/<domain>/data/`
-- support active domains first:
-  - sprites
-  - tilemaps
-  - parallax
-  - vectors
-- add focused validation/tests for the pipeline layer
-
-## Approved ownership pattern
-- game-level coordinator file at `games/<game>/assets/<game>.assets.json`
-- runtime assets in `games/<game>/assets/<domain>/`
-- tool/editor data in `games/<game>/assets/<domain>/data/`
-
-## Hard rules
-- do not change engine code
-- do not add gameplay/runtime features
-- do not redesign tool UI
-- do not perform unrelated asset moves
-- do not duplicate validation already established in 09_08
-- do not let each tool keep ad hoc export logic when shared pipeline extraction is appropriate
-
-## Deliverables
-Return a single repo-structured ZIP at:
-`<project folder>/tmp/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.zip`
-
-Include:
-- docs/pr/BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING.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 shared/pipeline files
-- focused pipeline validation tests
-- existing contract / launch / asset integration tests as needed to prevent regressions
-
-## Success definition
-- shared asset pipeline exists under `tools/shared`
-- contract validation is reused from 09_08
-- runtime outputs and tool data are cleanly separated
-- active asset domains flow through a consistent pipeline
-- no engine/runtime scope expansion
-- final output is one ZIP in `<project folder>/tmp/`
+MODEL: GPT-5.4
+REASONING: high
+COMMAND: Implement game asset manifest coordination.

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-build(assets): add shared pipeline tooling with 09_08 contract-gated emit stages
+BUILD_PR_LEVEL_09_10_GAME_ASSET_MANIFEST_COORDINATION

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-APPLY_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING
+BUILD_PR_LEVEL_09_11_RUNTIME_ASSET_BINDING

docs/dev/reports/change_summary.txt

@@ -1,36 +1 @@
-Summary
-- Implemented a shared asset pipeline tooling surface at `tools/shared/pipeline/assetPipelineTooling.js`.
-- Centralized staged flow: load -> validate -> normalize -> emit.
-- Reused 09_08 tool-data contract enforcement via `validateToolStateContract` from `tools/shared/projectToolIntegration.js`.
-- Added focused pipeline validation test coverage and wired it into the test runner.
-
-Pipeline behavior
-- Active domains handled consistently:
-  - sprites
-  - tilemaps
-  - parallax
-  - vectors
-- Runtime/tool-data split is enforced in emitted paths:
-  - runtime: `games/<game>/assets/<domain>/...`
-  - tool/editor data: `games/<game>/assets/<domain>/data/...`
-- Coordinator output path contract:
-  - `games/<game>/assets/<game>.assets.json`
-
-Contract gate reuse (09_08)
-- `runAssetPipelineTooling(...)` validates all provided tool states through shared 09_08 contract validation.
-- Invalid tool contract state blocks emit and returns explicit issues.
-- No duplicate contract validation layer was introduced.
-
-Files added
-- `tools/shared/pipeline/assetPipelineTooling.js`
-- `tests/tools/AssetPipelineTooling.test.mjs`
-
-Files updated
-- `tests/run-tests.mjs`
-- docs/dev deliverables for this BUILD PR
-
-Scope guard
-- No engine files changed.
-- No gameplay/runtime feature expansion.
-- No tool UI redesign.
-- No unrelated asset moves.
+Adds root asset manifest coordination.

docs/dev/reports/validation_checklist.txt

@@ -1,50 +1,3 @@
-Validation Checklist - BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING
-
-Scope
-[x] PR remains in the shared tool/asset pipeline lane only
-[x] No engine files changed
-[x] No gameplay/runtime feature changes introduced
-[x] No UI redesign introduced
-[x] No unrelated asset moves introduced
-
-Pipeline
-[x] Shared pipeline surface exists under `tools/shared`
-[x] Pipeline stages cover load / validate / normalize / emit
-[x] 09_08 data-contract validation is reused rather than duplicated
-[x] Invalid tool data is surfaced before emit
-[x] Normalized runtime output is deterministic
-[x] Runtime outputs remain in `assets/<domain>/`
-[x] Tool/editor data remains in `assets/<domain>/data/`
-
-Domains
-[x] Sprites supported by shared pipeline path
-[x] Tilemaps supported by shared pipeline path
-[x] Parallax supported by shared pipeline path
-[x] Vectors supported by shared pipeline path
-[x] Tilesets only included if directly required
-
-Validation
-[x] `node --check` passes for touched files
-[x] Focused pipeline validation tests pass
-[x] Existing ProjectToolDataContracts test still passes
-[x] Existing ToolEntryLaunchContract test still passes
-[x] Existing AssetUsageIntegration test still passes if applicable
-
-Executed commands
-- node --check tools/shared/pipeline/assetPipelineTooling.js
-- node --check tools/shared/projectToolIntegration.js
-- node --check tests/tools/AssetPipelineTooling.test.mjs
-- node --check tests/run-tests.mjs
-- 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'); })"
-- node --input-type=module -e "import('./tests/tools/ToolEntryLaunchContract.test.mjs').then(async ({ run }) => { await run(); console.log('PASS ToolEntryLaunchContract'); })"
-- node --input-type=module -e "import('./tests/tools/AssetUsageIntegration.test.mjs').then(async ({ run }) => { await run(); console.log('PASS AssetUsageIntegration'); })"
-
-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_09_ASSET_PIPELINE_TOOLING.zip`
+[ ] manifest exists
+[ ] pipeline integrates
+[ ] no engine changes

docs/pr/BUILD_PR_LEVEL_09_10_GAME_ASSET_MANIFEST_COORDINATION.md

@@ -0,0 +1 @@
+Game asset manifest coordination layer.

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 runGameAssetManifestCoordinator } from './tools/GameAssetManifestCoordinator.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';
@@ -207,6 +208,7 @@ const tests = [
     ['ToolBoundaryEnforcement', runToolBoundaryEnforcement],
     ['ProjectToolDataContracts', runProjectToolDataContracts],
     ['AssetPipelineTooling', runAssetPipelineTooling],
+    ['GameAssetManifestCoordinator', runGameAssetManifestCoordinator],
     ['ToolEntryLaunchContract', runToolEntryLaunchContract],
     ['ProjectPackagingSystem', runProjectPackagingSystem],
     ['RuntimeAssetLoader', runRuntimeAssetLoader],

tests/tools/AssetPipelineTooling.test.mjs

@@ -41,6 +41,7 @@ export async function run() {
   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");
+  assert.equal(ready.stages.emit.gameAssetManifestPath, "games/asteroids/assets/asteroids.assets.json");
   assert.equal(
     ready.records.every((entry) => entry.runtimePath.includes("/assets/") && !entry.runtimePath.includes("/data/")),
     true
@@ -51,6 +52,17 @@ export async function run() {
   );
   assert.equal(ready.coordinator.domains.sprites[0].runtimePath.startsWith("games/asteroids/assets/sprites/"), true);
   assert.equal(ready.coordinator.domains.sprites[0].toolDataPath.startsWith("games/asteroids/assets/sprites/data/"), true);
+  assert.equal(ready.gameAssetManifest.status, "ready");
+  assert.equal(ready.gameAssetManifest.filePath, "games/asteroids/assets/asteroids.assets.json");
+  assert.equal(ready.gameAssetManifest.manifest.domains.sprites[0].assetId, "sprite.ship");
+  assert.equal(
+    ready.gameAssetManifest.manifest.domains.sprites[0].runtimePath.startsWith("games/asteroids/assets/sprites/"),
+    true
+  );
+  assert.equal(
+    ready.gameAssetManifest.manifest.domains.sprites[0].toolDataPath.startsWith("games/asteroids/assets/sprites/data/"),
+    true
+  );
 
   const invalid = runAssetPipelineTooling({
     gameId: "Asteroids",
@@ -71,4 +83,5 @@ export async function run() {
     true
   );
   assert.equal(invalid.records.length, 0);
+  assert.equal(invalid.gameAssetManifest, undefined);
 }

tests/tools/GameAssetManifestCoordinator.test.mjs

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { coordinateGameAssetManifest } from "../../tools/shared/pipeline/gameAssetManifestCoordinator.js";
+
+export async function run() {
+  const coordinated = coordinateGameAssetManifest({
+    gameId: "Asteroids",
+    existingManifest: {
+      gameId: "asteroids",
+      domains: {
+        sprites: [
+          {
+            assetId: "sprite.legacy",
+            runtimePath: "games/asteroids/assets/sprites/sprite-legacy.json",
+            toolDataPath: "games/asteroids/assets/sprites/data/sprite-legacy-tool.json",
+            sourceToolId: "sprite-editor"
+          },
+          {
+            assetId: "sprite.ship",
+            runtimePath: "games/asteroids/assets/sprites/sprite-ship-old.json",
+            toolDataPath: "games/asteroids/assets/sprites/data/sprite-ship-old-tool.json",
+            sourceToolId: "sprite-editor"
+          }
+        ]
+      }
+    },
+    records: [
+      {
+        domain: "sprites",
+        assetId: "sprite.ship",
+        runtimePath: "games/asteroids/assets/sprites/sprite-ship.json",
+        toolDataPath: "games/asteroids/assets/sprites/data/sprite-ship-tool.json",
+        sourceToolId: "sprite-editor"
+      },
+      {
+        domain: "vectors",
+        assetId: "vector.ship",
+        runtimePath: "games/asteroids/assets/vectors/vector-ship.json",
+        toolDataPath: "games/asteroids/assets/vectors/data/vector-ship-tool.json",
+        sourceToolId: "vector-asset-studio"
+      }
+    ]
+  });
+
+  assert.equal(coordinated.status, "ready");
+  assert.equal(coordinated.filePath, "games/asteroids/assets/asteroids.assets.json");
+  assert.equal(coordinated.summary.totalAssets, 3);
+  assert.deepEqual(
+    coordinated.manifest.domains.sprites.map((entry) => entry.assetId),
+    ["sprite.legacy", "sprite.ship"]
+  );
+  assert.equal(
+    coordinated.manifest.domains.sprites.find((entry) => entry.assetId === "sprite.ship").runtimePath,
+    "games/asteroids/assets/sprites/sprite-ship.json"
+  );
+  assert.equal(coordinated.manifest.domains.vectors[0].assetId, "vector.ship");
+}

tools/shared/pipeline/assetPipelineTooling.js

@@ -1,5 +1,6 @@
 import { safeString } from "../projectSystemValueUtils.js";
 import { validateToolStateContract } from "../projectToolIntegration.js";
+import { coordinateGameAssetManifest } from "./gameAssetManifestCoordinator.js";
 
 export const ASSET_PIPELINE_TOOLING_SCHEMA = "html-js-gaming.asset-pipeline-tooling";
 export const ASSET_PIPELINE_TOOLING_VERSION = 1;
@@ -186,9 +187,16 @@ export function runAssetPipelineTooling(options = {}) {
     normalizedRecordCount: normalizedRecords.length
   };
   const coordinator = buildCoordinator(gameId, normalizedRecords);
+  const gameAssetManifest = coordinateGameAssetManifest({
+    gameId,
+    coordinatorPath: `games/${gameId}/assets/${gameId}.assets.json`,
+    records: normalizedRecords,
+    existingManifest: options.existingManifest
+  });
   const emitStage = {
     stage: ASSET_PIPELINE_TOOLING_STAGES.EMIT,
-    coordinatorPath: `games/${gameId}/assets/${gameId}.assets.json`,
+    coordinatorPath: gameAssetManifest.filePath,
+    gameAssetManifestPath: gameAssetManifest.filePath,
     emittedRecordCount: normalizedRecords.length
   };
 
@@ -203,6 +211,7 @@ export function runAssetPipelineTooling(options = {}) {
       emit: emitStage
     },
     records: normalizedRecords,
-    coordinator
+    coordinator,
+    gameAssetManifest
   };
 }