Report QNN detail fallback reasons

[Qiong Wu (qiowu) (DingmaomaoBJTU)]

Summary

• add a machine-readable fallback_reason when QNN detail op tracing degrades to basic CSV
• distinguish missing QNN logs, schematics, SDK tools, viewer failures, missing QHAS output, and QHAS parse failures
• preserve the existing basic_fallback exit-0 contract while showing reason-specific CLI guidance
• keep the existing run_qhas_viewer() -> Path | None API through a compatibility wrapper

Problem

Every QHAS failure previously collapsed into status="basic_fallback" with no reason. The CLI always suggested setting QNN_SDK_ROOT, even when the SDK was already configured and the actual issue was a missing optrace schematic on a precompiled EPContext model. Machine consumers could not distinguish causes either.

Behavior

The op-trace JSON now includes an additive fallback_reason field with stable values:

• qnn_log_missing
• schematic_missing
• sdk_missing
• viewer_failed
• qhas_output_missing
• qhas_parse_failed

Viewer preparation, subprocess, output inspection, SDK discovery, QNN-log metadata, and offline-QHAS metadata failures remain degraded detail results when usable CSV data exists rather than escaping as parse_failed.

Validation

• python -m pytest tests/unit/session/monitor -q: 243 passed
• python -m pytest tests/unit/commands/test_perf_optracing.py -q: 62 passed, 1 hardware-gated skip
• Ruff check and format check on all changed files
• mypy on all four changed production modules
• live QNN/NPU validation with QNN_SDK_ROOT configured and a precompiled keen_hominy EPContext lacking a schematic:
  • exit 0
  • status basic_fallback
  • fallback reason schematic_missing
  • 207 basic operators retained
  • CLI recommends rerunning from raw ONNX
  • CLI does not incorrectly suggest QNN_SDK_ROOT