feat(adapters): add GPU profiling and trace evidence

[morluto]

Description

Flameox can preserve accelerator timelines, but it lacked bounded per-kernel hardware evidence from Nsight Compute and a managed ROCm PFTrace capture path. Users therefore had to translate reports manually or run rocprofv3 outside the evidence chain.

This stacked PR adds official-interface Nsight Compute extraction and rocprofv3 PFTrace capture through the existing Perfetto route. It is based on #138; after the preceding PRs merge, this branch can be retargeted to main.

Relates to #133.
Relates to #136.

Approach

• Preserve .ncu-rep and .ncu-repz unchanged and extract through the ncu_report interface shipped with the detected Nsight Compute installation. Flameox does not decode NVIDIA report binaries or add a runtime PyPI substitute.
• Traverse ranges, actions, metrics, sections, rules, tables, and source references in an isolated bounded worker. Roofline evidence is published only when the report explicitly contains it.
• Add constrained ncu capture selection and separate capability reporting for executable/interface availability and counter permission. ERR_NVGPUCTRPERM maps to actionable permission_required; unrelated nonzero probes degrade instead of advertising availability.
• Invoke the official rocprofv3 CLI with selected trace domains and PFTrace output, preserving stdout, stderr, process identity, native output, and partial attempts.
• Reuse the existing Perfetto extractor and accelerator recipe. No ROCprofiler SDK integration or second trace parser is introduced.

Suggested review order:

1. src/flameox/adapters/nsight_compute.py and its isolated worker
2. Nsight capability probing and managed capture
3. rocprofv3 options/invocation in the shared adapter registry
4. CLI/MCP surfaces, fixture/process tests, and compatibility notes

Commands run

uv run pytest -q
# 824 passed, 205 deselected

uv run pytest -q -o addopts='' tests/adapters/test_nsight_compute.py tests/adapters/test_rocprofv3.py tests/application/test_nsight_compute_capability.py -m 'not optional'
# 10 passed, 1 deselected

uv run python tools/test.py optional-ncu
# 2 passed, 1 skipped on the local NVIDIA host; live capture and bundled-report extraction passed

# rocprof process plus project-owned Perfetto fixture path: 5 passed
uv run pytest -q -o addopts='' tests/adapters/test_rocprofv3.py -m 'process or requires_perfetto'

uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run mypy src tests tools
uv run lint-imports
uv run python tools/test.py ownership
uv run python tools/test.py collection
uv lock --check

The final collection receipt covers 1,029 node IDs across 95 files. Both import-boundary contracts pass.

Compatibility

Nsight Compute extraction requires its official Python report interface. Successful live counter capture and extraction ran locally with Nsight Compute 2026.2.1 after administrator-enabled NVIDIA performance-counter access. Flameox never changes host privileges.

No AMD host was available. rocprofv3 command construction, domain selection, partial-output preservation, and failures are covered by deterministic process fixtures. A project-owned ROCm-shaped Perfetto trace exercises import → existing Perfetto extraction → accelerator summary, but it is explicitly not vendor-produced PFTrace and does not prove native rocprofv3 format compatibility. A genuine trace with recorded provenance and redistribution permission remains the hardware proof gap. GitHub-hosted CI does not schedule GPU-only jobs that could pass by skipping.

[morluto]

@codex

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c663bd57a4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c72db89281

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".