Diagnostic Library

Preflight validation is explicitly split into two layers:

1. OpenUSD Core Validation (always runs)
2. RealityKit Extension Validation (additive when target is RealityKit)

This means target=openusd returns only core interoperability/correctness diagnostics, while target=visionos (or other RealityKit profile) returns core plus RealityKit compatibility/performance diagnostics.

Validation Runtime Paths

All surfaces use the same shared validation path:

• App UI
• MCP/ACP tools
• preflighttool CLI

Diagnostics are canonicalized before scoring/display, so issue IDs and severities stay aligned across surfaces.

Workflow profile defaults are user-selectable in app settings and map to the same target profile semantics used by MCP/ACP and CLI inputs.

Core vs Extension Semantics

OpenUSD Core (always)

Examples:

• Stage open/loadability
• defaultPrim integrity
• upAxis and metersPerUnit metadata sanity
• Dependency resolution
• Material binding/schema integrity
• Baseline animation/skeleton integrity
• Texture correctness baseline (exists, resolves, decodes)

RealityKit Extension (additive)

Examples:

• RealityKit shader/material constraints
• Unsupported runtime constructs (for example PointInstancer)
• Runtime-oriented texture policy checks (format/budget/colorspace/mips)
• Platform-specific performance advisories

Texture Diagnostics

Texture diagnostics stay under the Materials category and follow a shared diagnosis contract:

• id (stable rule ID)
• severity
• manualGuidance (what “right” means)
• toolRecommendation (which action/tool to run)
• fixAction when available
• converterRecipe when conversion is the preferred remediation

Initial Rule Set

• texture.missing_file
• texture.unreadable_or_corrupt
• texture.unsupported_container_or_encoding_for_target
• texture.exceeds_target_budget
• texture.colorspace_mismatch
• texture.no_mips_for_large_textures
• texture.npot_or_alignment_risk

Canonicalization and Scoring

When multiple sources detect equivalent issues, Preflight keeps one canonical diagnosis row per issue (deterministic precedence), then scores from that canonical stream.

This guarantees:

• UI/MCP/CLI parity
• No double-penalty for duplicates
• Stable diagnosis IDs for automation