docs: add BUILD_PR asset pipeline validation & output bundle

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,16 +2,16 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_ASSET_PIPELINE_CONVERTERS
+Create BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT
 
 Scope:
-- add converter abstraction layer
-- implement minimal converters
-- integrate with pipeline foundation
+- add validation stage
+- add export/output stage
+- integrate with pipeline
 
 Validation:
 - npm run test:launch-smoke -- --tools
-- verify conversions usable
+- verify assets validate and export
 
 Output:
-<project>/tmp/BUILD_PR_ASSET_PIPELINE_CONVERTERS_delta.zip
+<project>/tmp/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: add BUILD_PR asset pipeline converters bundle
+docs: add BUILD_PR asset pipeline validation & output bundle

docs/dev/reports/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT_report.md

@@ -0,0 +1,62 @@
+# BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT Report
+
+## Scope Outcome
+- Added shared validation/output stages to the asset pipeline with minimal integration work.
+- Kept scope focused to shared pipeline modules (no UI/theme/editor-state/render changes).
+
+## Validation Stage Additions
+- New shared module: `tools/shared/assetPipelineValidationOutput.js`
+- Added registry-level validation for:
+  - schema shape (expected section arrays)
+  - ID rules (required IDs, supported character set)
+  - references (candidate/graph-resolved references)
+- Reused existing shared registry utilities:
+  - `sanitizeAssetRegistry(...)`
+  - `buildAssetDependencyGraph(...)`
+  - `findRegistryEntryById(...)`
+- Missing dependency targets are enforced as validation issues.
+
+## Output Stage Additions
+- Added deterministic JSON output artifact builder:
+  - schema: `tools.asset-pipeline-output/1`
+  - format: `json`
+  - deterministic build path: `build/assets/<projectId>.assets.pipeline.json`
+- Reused existing shared JSON payload helper:
+  - `createRegistryDownloadPayload(...)`
+- Output includes summary + validation counts + sanitized registry payload.
+
+## Pipeline Integration
+- Updated `tools/shared/assetPipelineFoundation.js` to integrate new stages.
+- Stage map now includes:
+  - `validation`
+  - `output`
+- `registerAssetPipelineCandidate(...)` now executes:
+  - normalize -> convert -> candidate validate -> register -> pipeline validation -> output
+- On pipeline validation failure:
+  - returns `valid: false`
+  - preserves incoming registry (no invalid registry write-forward)
+  - output stage is omitted
+- Added exported helpers:
+  - `validateAssetPipelineRegistryState(...)`
+  - `createAssetPipelineOutput(...)`
+
+## Validation
+- Required smoke:
+  - `npm run test:launch-smoke -- --tools`
+  - Result: PASS (`9/9`)
+  - Evidence: `docs/dev/reports/launch_smoke_report.md`
+- Focused validation/output verification:
+  - verified valid assets pass and produce output artifacts
+  - verified unresolved references fail validation and suppress output stage
+  - verified deterministic export path/format
+  - Result: PASS
+  - Evidence: `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT_validation.txt`
+
+## Exact Files Changed
+- `docs/pr/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT.md`
+- `docs/dev/reports/asset_pipeline_validation_output_targets.txt`
+- `tools/shared/assetPipelineValidationOutput.js`
+- `tools/shared/assetPipelineFoundation.js`
+- `docs/dev/reports/launch_smoke_report.md`
+- `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT_validation.txt`
+- `docs/dev/reports/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT_report.md`

docs/dev/reports/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT_validation.txt

@@ -0,0 +1,9 @@
+ASSET PIPELINE VALIDATION & OUTPUT TARGETS
+
+- validation rules (schema, IDs, references)
+- export JSON format
+- build artifact structure
+
+Keep:
+- simple
+- deterministic

docs/dev/reports/asset_pipeline_validation_output_targets.txt

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-12T00:31:13.799Z
+Generated: 2026-04-12T00:38:22.248Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 

docs/dev/reports/launch_smoke_report.md

@@ -0,0 +1,28 @@
+# BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT
+
+## Purpose
+Add validation, export, and build-output stages to the asset pipeline so assets can be verified and packaged consistently.
+
+## Goals
+- validation rules enforcement
+- export formats (JSON baseline)
+- build artifacts output
+
+## Scope
+- validation layer
+- export/output layer
+- integration with existing pipeline
+
+## Out of Scope
+- complex packaging systems
+- deployment pipelines
+- 3D/export formats
+
+## Strategy
+- extend pipeline after converters
+- add validation checkpoints
+- output standardized artifacts
+
+## Validation
+- npm run test:launch-smoke -- --tools
+- assets validate and export without errors

docs/pr/BUILD_PR_ASSET_PIPELINE_VALIDATION_OUTPUT.md

@@ -10,13 +10,19 @@ import {
   createAssetPipelineConverterRegistry,
   listAssetPipelineConverters
 } from "./assetPipelineConverters.js";
+import {
+  createAssetPipelineOutputArtifact,
+  validateAssetPipelineState
+} from "./assetPipelineValidationOutput.js";
 
 export const ASSET_PIPELINE_STAGES = Object.freeze({
   INGEST: "ingest",
   NORMALIZE: "normalize",
   CONVERT: "convert",
   VALIDATE: "validate",
-  REGISTER: "register"
+  REGISTER: "register",
+  VALIDATION: "validation",
+  OUTPUT: "output"
 });
 
 export const ASSET_PIPELINE_SECTION_RULES = Object.freeze({
@@ -143,6 +149,38 @@ export function validateAssetPipelineCandidate(rawCandidate = {}) {
   return validateNormalizedAssetPipelineCandidate(candidate);
 }
 
+export function validateAssetPipelineRegistryState(options = {}) {
+  const registry = options.registry && typeof options.registry === "object"
+    ? options.registry
+    : {};
+  const candidate = options.candidate && typeof options.candidate === "object"
+    ? cloneValue(options.candidate)
+    : null;
+
+  return validateAssetPipelineState({
+    registry,
+    candidate,
+    sectionRules: ASSET_PIPELINE_SECTION_RULES
+  });
+}
+
+export function createAssetPipelineOutput(options = {}) {
+  const registry = options.registry && typeof options.registry === "object"
+    ? options.registry
+    : {};
+  const validation = options.validation && typeof options.validation === "object"
+    ? cloneValue(options.validation)
+    : null;
+  const format = safeString(options.format, "json");
+
+  return createAssetPipelineOutputArtifact({
+    registry,
+    validation,
+    format,
+    sectionRules: ASSET_PIPELINE_SECTION_RULES
+  });
+}
+
 export function registerAssetPipelineCandidate(options = {}) {
   const incomingRegistry = options.registry && typeof options.registry === "object"
     ? options.registry
@@ -171,7 +209,9 @@ export function registerAssetPipelineCandidate(options = {}) {
       registry,
       entry: null,
       validation,
-      conversion: conversionResult
+      conversion: conversionResult,
+      pipelineValidation: null,
+      output: null
     };
   }
 
@@ -188,21 +228,55 @@ export function registerAssetPipelineCandidate(options = {}) {
   }
 
   const nextRegistry = upsertRegistryEntry(registry, candidate.section, entry);
+  const pipelineValidation = validateAssetPipelineRegistryState({
+    registry: nextRegistry,
+    candidate
+  });
+  if (!pipelineValidation.valid) {
+    return {
+      stage: ASSET_PIPELINE_STAGES.REGISTER,
+      valid: false,
+      registry,
+      entry: null,
+      validation,
+      conversion: conversionResult,
+      pipelineValidation,
+      output: null
+    };
+  }
+
+  const output = createAssetPipelineOutput({
+    registry: nextRegistry,
+    validation: pipelineValidation,
+    format: safeString(options.outputFormat, "json")
+  });
+
   return {
     stage: ASSET_PIPELINE_STAGES.REGISTER,
     valid: true,
     registry: nextRegistry,
     entry,
     validation,
-    conversion: conversionResult
+    conversion: conversionResult,
+    pipelineValidation,
+    output
   };
 }
 
 export function summarizeAssetPipelineRules() {
+  const output = createAssetPipelineOutput({
+    registry: {},
+    format: "json"
+  });
   return {
     schema: "tools.asset-pipeline-foundation-rules/1",
     stages: cloneValue(ASSET_PIPELINE_STAGES),
     sectionRules: cloneValue(ASSET_PIPELINE_SECTION_RULES),
-    converters: listAssetPipelineConverters(DEFAULT_PIPELINE_CONVERTER_REGISTRY)
+    converters: listAssetPipelineConverters(DEFAULT_PIPELINE_CONVERTER_REGISTRY),
+    output: {
+      schema: output.artifact.schema,
+      format: output.format,
+      filePathTemplate: "build/assets/<projectId>.assets.pipeline.json"
+    }
   };
 }