[Opus MoE] Unify A8W4 metadata and runtime dispatch

[yifehuan]

Motivation

Opus MoE A8W4 metadata and runtime integration were previously split across multiple layers:

• Stage2 kernel metadata lived under the runtime package.
• opus_moe_common.py dynamically loaded runtime metadata through importlib, reversing the intended dependency direction.
• Stage2 decode/reduce orchestration was duplicated between the fused-MoE adapter and the tuner.
• Stage1 and Stage2 fused adapters lived in different layers.
• A kernel name and its launch parameters could be represented independently, allowing inconsistent runtime plans.

This PR consolidates these responsibilities into a single-direction dependency structure and makes each complete kernelName2 select one immutable Stage2 launch plan.

This is a structural follow-up to the runtime-K Stage2 work in #4723.

Technical Details

• Consolidated torch-free Stage1 and Stage2 metadata into csrc/opus_moe/opus_moe_common.py.

  • Kernel contracts, instances, public names, kids, and route-reduce settings now have one canonical source.
  • Removed the runtime-package metadata module and the importlib-based reverse dependency.
  • Removed unused kid lookup compatibility helpers.

• Consolidated Stage2 runtime integration into aiter/ops/opus/moe_stage2_a8w4.py.

  • Kept low-level decode and route-reduce bindings.
  • Moved tuned-config parsing and fused-MoE adaptation into the runtime module.
  • Added a shared opus_moe_stage2_a8w4_fwd() entry point used by both fused MoE and the tuner.
  • Removed the standalone Stage2 fused adapter.

• Made Stage2 launch selection immutable.

  • OpusA8W4LaunchConfig now stores only one OpusA8W4Stage2Instance.
  • Kernel id, sorting block size, output mode, and reducer configuration are derived from that instance.
  • Removed per-launch overrides for sorting and route-reduce parameters.
  • Added validation that kernelName2 and the selected launch instance refer to the same plan.
  • Removed the unused generic-name plus numeric-column legacy configuration path.

• Moved the Opus Stage1 fused wrapper into moe_stage1_a8w4.py.

  • fused_moe.py now selects Opus runtime adapters without owning their backend-specific argument handling.

• Updated gemm_moe_tune.py.

  • Uses the same high-level Stage2 execution path as fused MoE.
  • Imports metadata through the canonical csrc.opus_moe.opus_moe_common module.
  • Avoids loading the same source file under multiple Python module identities.

• Updated Opus MoE documentation and codegen source references.

The generated kernel manifests and device translation units are unchanged apart from the metadata source-path comment. No GPU pipeline or kernel implementation is modified by this PR.

Test Plan

• Run Black over the full repository.
• Run Ruff 0.16.0 over all Python files changed by this PR.
• Generate all Opus MoE manifests and device translation units, then compare them with the pre-refactor output.
• Build module_moe_opus as a multi-architecture module with:
  • gfx942
  • gfx950
• Validate all production Opus Stage2 names and layout names against the canonical metadata catalog.
• Parse every production Opus row from:
  • dsv4_fp8fp4_tuned_fmoe.csv
  • kimik3_a8w4_tuned_fmoe.csv
• Run Opus-only op_tests/test_moe_2stage.py coverage for both model configurations.

Test Result

• Black: passed; 1055 files left unchanged.
• Ruff 0.16.0: all Python files changed by this PR passed.
• Codegen comparison: passed; generated headers and device translation units had no functional differences.
• Metadata validation: passed for all 19 Stage2 instances and their layout-name forms.
• Production config parsing: passed for all 51 Opus Stage2 rows across the DSV4 and Kimi-K3 model configurations.
• Multi-architecture build: passed.
  • module_moe_opus.so built successfully.
  • Build commands contained both --offload-arch=gfx942 and --offload-arch=gfx950.
• test_moe_2stage.py:
  • DSV4 Opus cases: 30/30 passed.
  • Kimi-K3 Opus cases: 17/17 passed.
  • Total: 47/47 passed.
  • No traceback, assertion failure, NaN, or accuracy failure was observed.

Submission Checklist

• Look over the contributing guidelines at https://github.com/ROCm/ROCm/blob/develop/CONTRIBUTING.md#pull-requests.

[github-actions]

🏷️ CI Guide

Runs automatically on every PR:

• ✅ Pre-checks (submodule verification, code formatting)
• ✅ Aiter op tests (gfx942 + gfx950)
• ✅ Triton tests on MI35X (only when aiter/ops/triton/** or related paths are changed)

Extended tests (opt-in via labels):

Label	Tests
ci:gfx1250-ffm-triton	Run the five-shard gfx1250 FFM Triton test suite
ci:triton-300x	Run an additional Triton test job on MI300X in PRs; main branch always runs both MI35X and MI300X
ci:sglang	SGLang integration tests: DeepSeek-R1-MXFP4 accuracy, Qwen 3.5 accuracy
ci:atom	ATOM benchmark: DeepSeek-R1-0528, GPT-OSS-120B
ci:atom_full	ATOM accuracy suite for PR and main models from ATOM models_accuracy.json
ci:vllm	vLLM benchmark: GPT-OSS-120B, DeepSeek-R1-0528, Kimi-K2.5
ci:all	All standard extended tests (excludes ci:atom_full)

Only add ci:atom_full for FlyDSL or Triton upgrades.
Add labels via the sidebar or gh pr edit 4755 --add-label <label>