[lora] declarative layouts, support-status registry

[Zhichenzzz]

Stacked on #2017 (base: yusheng/lora-plugin-refactor). Keeps that PR's package layout; redesigns the function-level contracts so supporting a NEW model natively is a one-declaration exercise, plus the fixes found while validating four models end-to-end.

Redesign

Classes carry the taxonomy; every fact is declared once and derived everywhere else.

• Declarative layouts (spec/attach.py, spec/dims.py): an architecture spec is a class holding a ModuleLayout table — which projections exist, on which physical linear, with which shard geometry. One shared attach_layout() implements the existence-check → target-filter → guard → build → hook walk; spec/dims.py is the only spec-side reader of MCore attribute names. MLA's attach went from ~90 imperative lines to a table; a new layout is ~15 lines of facts.
• Spec hierarchy (LayoutSpec → AttentionSpecBase → GQA/MLA/GDN, HybridGQAGDN(GQAAttentionSpec), SharedOuterExpertMoESpec(GeneralExpertMoESpec)): supported_targets, the canonical --target-modules order, and SGLang's fused-family expansion all derive from the layout declaration. registry.serving_fused_families() feeds expand_sglang_target_modules, so a new architecture's fused groups reach serving-side expansion automatically. ShardLayout/AttentionFamily str-enums replace the bare "column"/"gqa" strings; the parallel name tables that used to live in codec/sglang.py and modules/linear.py are gone (split adapters take member projections from their FusedAttach; MoE specs get MLP target names by injection).
• ModelEntry(spec, status, reason) with VALIDATED / STRUCTURAL / UNSTABLE: support status becomes one first-class field instead of _RAW_MODE_BACKWARD_UNSTABLE plus comments. Entries record this branch's e2e evidence.
• Public export descriptors: adapters expose exports() -> ProjectionExport (with SGLangFusedGroup metadata); codec/sglang.py is rewritten on that API — no more _active/_rows private access or isinstance ladders; the MLA fused_qkv_a special case is a ServingGroup declaration in the MLA table.
• Launcher helpers: default_target_modules(hf_checkpoint) and preflight_native_lora(...) (registry ∧ mbridge bridge ∧ model-args audit, no GPU) — run_lora_native.py stops re-declaring per-family target strings and fails in seconds instead of deep inside torchrun when a conversion bridge is missing.
• Consolidation: LoRASplitQKV/LoRASplitFC1 collapse into a shared LoRASplitAdapter; the marked-grad cache moves onto the model chunk (the id-keyed module global could outlive rebuilt models); MoE's module-level warn flag becomes a per-run report.

Fixes found by running four models natively

• miles_plugins/mbridge/kimi_k25.py (new): mbridge has no Kimi bridge, so raw-mode K2.5 conversion was impossible (bridge mode uses megatron.bridge's own KimiK25VL bridge and never converts). Thin DeepseekV3Bridge subclass: text_config descent + language_model. prefix remap; vision weights are skipped by pull-based loading.
• megatron_to_hf kimi dispatch: _convert_to_hf_core matched only kimi_k25, but the direct weight iterator passes the config class name kimik25config (dead branch); the converter also lacked the raw text-only provider's unprefixed embedding/output/final-layernorm names.
• convert_kimi_int4_to_bf16.py strips quantization_config: a surviving one sends SGLang through its CompressedTensors path, which serves the BF16 checkpoint with a degenerate context-free forward (identical next-token distribution at every position) — rollouts are garbage and train/rollout logprob_abs_diff sits at ~2.2. Verified by a megatron-vs-HF-vs-SGLang three-way logprob comparison; with the config stripped all three agree.
• torch_dsa_topk clamps k to the key length: gsm8k-length sequences (< index_topk=2048 keys) crashed torch.topk in raw-mode log-prob compute; pads with -1, the existing invalid-index convention.
• run_glm5_2_744b_a40b_lora_native.py (new): raw-mode GLM-5.2 launcher (the existing LoRA script is bridge-only). Its toy conversion must be single-rank: the convert tool pipeline-shards across its ranks, and any PP split of the 5-layer toy starts a stage on a DSA skip layer.

Validation

20-rollout native GRPO runs (wandb ch271828n-team/miles_lora_native), acceptance ≈ 0.01 train/rollout logprob_abs_diff:

model	logprob_abs_diff
Qwen3-8B	0.0099
Qwen3.5-35B-A3B	0.0105 (grad_norm ~1e-2 throughout; the recorded GDN raw-backward divergence did not reproduce → qwen3_5_moe flipped to VALIDATED)
GLM-5.2 5-layer	0.0096
Kimi-K2.5 2-layer	0.0124 (after the quantization_config fix)

tests/fast/miles_plugins/lora: 47 passed at every step (baseline 47). Behavior-preservation smoke: a 2-rollout Qwen3-8B run on this branch reproduces the baseline's first-rollout logprob_abs_diff (0.00967 vs 0.00978). Adapter attribute names are pinned, so checkpoint keys are unchanged.

🤖 Generated with Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.