vLLM-MetaX Model Upgrade

Preserve the target upstream structure while implementing the verified MACA execution contract. A successful upgrade includes the model's reachable dependencies, not just its top-level Python file. Upstream support declarations and comments are evidence to investigate, not proof of support on MetaX.

Scope and environment

• Cover the requested models under vllm_metax/models/, their registration and configuration, and recursively their required attention, cache, compressor, indexer, projection, MTP/draft, MoE and kernel wrappers. Keep unrelated components out of scope.
• Keep review-only requests read-only. Establish whether the subject is the index, worktree, installed package or specified revision. Preserve staged/unstaged changes; do not stage, commit, reinstall dependencies or edit upstream/site-packages unless authorized. For staged validation, export and import the index snapshot explicitly.
• Read applicable repository instructions.
• Read and apply vllm-metax-upgrade-common before compatibility decisions. It owns environment/source discovery, the shared read-only probe, one-time target confirmation and verification evidence rules. Reuse the same established environment record across upgrade skills; do not ask again for an unchanged mapping. Keep the domain-specific workflow below.
• Apart from the common prerequisite above, do not automatically invoke patch, attention or registry skills just because the model calls those modules. Apply a separately requested specialist workflow only to its relevant portion. No monkey-patch headers or patch audit files are required for model adaptations.

Diff the source and audit the upgrade range first

• Identify the last upstream version represented by the local models and the confirmed target revision. Before editing, diff each local model file against its exact target-upstream counterpart, including explicit mappings between platform directories. Inspect target-only, local-only, changed and removed files; a matching class name does not establish matching behavior.
• Review every upstream commit in the version range that touches those model files. Read the patch for each commit, then inspect any other production modules changed by that commit and the model's direct callers/dependencies. Decide whether the behavior is inherited from vllm, needs a MetaX merge, needs a coordinated dependency change, is intentionally platform-specific, or belongs to a new unsupported architecture. Do not infer the answer from a commit title or from the final two-tree diff alone.
• Keep a compact file/commit disposition record with the affected interface, dependent MetaX symbols, chosen action and evidence. Include commits that require no local edit, so a missed upstream change remains visible. Recheck the complete local-vs-target diff after edits for unaccounted differences.
• When this skill runs before other MetaX upgrade skills, treat the confirmed target vllm source as the reliable API contract. A referenced MetaX module may still raise import or attribute errors because its own upgrade is pending. Record that boundary, continue source comparison and isolated checks, and do not misclassify the unrelated failure as a model regression. Still adapt a dependency when the requested model's changed logic requires it.

First establish the MACA/upstream differences

Before deciding what to copy or remove, build an evidence-backed difference matrix for each requested model family. Include the effective configuration after platform and speculative-decoding rewrites, not only the original HF config.

• Inspect the official config.json for the exact checkpoint variant and revision before reasoning about its layer layout. Record backbone and MTP/draft counts separately, count layer-indexed arrays (for example layer_types, rope_theta, partial_rotary_factors), and map zero-based checkpoint layer IDs to each part. Do not substitute config-class defaults or mistake the highest layer ID for the number of layers. If the official config is unavailable, state the evidence gap.
• Verify which config class the target vLLM actually loads and compare the raw checkpoint values with the constructed config after overrides and rewrites. Check whether constructors truncate or transform layer-indexed arrays before model and MTP code indexes them.

Contract	Record for both upstream and MACA
Weights	Checkpoint dtype, runtime dtype, per-channel/block/MX grouping, scale encoding, packing, post-load conversion and excluded modules.
Activations and projections	Compute/output/accumulation dtype, fused vs separate projections, grouped GEMM, padding, quantization and inverse RoPE order.
KV and indexer caches	Logical dtype vs physical storage dtype, quantization scales, compressed/SWA separation, page layout/stride and index units.
Attention	Selected backend, model-specific attention, prefill/decode/MTP paths, head dimensions, sinks, causal behavior, compression and capability restrictions.
MoE and parallelism	Actual experts implementation, routing/scaling, shared experts, TP/PP/SP/EP/DCP collectives and supported combinations.
Optional features	LoRA, MTP/DSpark, graph capture and each feature's real dispatch and restrictions.
Components	Imported DeepGEMM, FlashAttention/FlashMLA, MCOPLIB and other actual callables, signatures, extension identities and verified semantics.

Separate intentional MetaX differences, inherited upstream behavior, obsolete overrides, adaptation defects and unverified assumptions. State unknowns explicitly. Inspect actual APIs, wrapper bodies and executable capability checks; challenge existing comments. A dtype name, matching signature or NVIDIA architecture predicate is not a MACA contract. Do not overwrite a necessary BF16/INT8 path with upstream FP8/FP4 behavior merely to reduce the diff. Structural alignment must preserve the established MACA semantics.

Recursively inventory and update dependencies

Trace from model registration through config rewriting, layer construction, weight loading, execution dispatch and kernels. Maintain a visited dependency inventory with: local symbol/file, target upstream counterpart, callers, relevant upstream delta, MetaX difference, action and validation evidence.

For each changed upstream model interface or behavior:

1. Inspect direct dependencies and their upstream changes.
2. Follow their dependencies until reaching a verified stable interface or an installed component boundary; record that boundary and why no further local change is needed.
3. Update affected local dependencies and callers together. Include model-private attention (such as DeepSeek V4 attention/compressor/FlashMLA code) even when it lives outside the main model file or a generic attention directory.
4. Inspect transitive consumers of shared helpers before changing their contracts. For external binary components, verify the installed API instead of silently upgrading or modifying the component.

Account for unchanged, removed, conditional and inactive files. Report blocked paths rather than claiming completion from successful imports of a subset. Read review-cases.md for relevant model-specific checks; its examples are investigation prompts, not permanent support restrictions.

Keep the implementation easy to diff

• Preserve upstream class/function boundaries, names, signatures, method order, control flow and file organization wherever MACA semantics allow it. Follow upstream moves when practical; record explicit mappings where platform directories differ.
• Avoid unrelated refactors, reformatting, renaming, helper extraction and broad defensive scaffolding. Prefer a small change at the corresponding upstream location over a new abstraction that obscures future upgrades.
• Every retained or newly introduced MetaX ad-hoc must have a nearby NOTE(MetaX) comment explaining the concrete upstream difference, why MACA needs it, and when it can be removed or revalidated. Preserve useful algorithm and layout explanations. Do not use a generic "MetaX modification" marker as the entire explanation.
• Compare both the local change diff and the complete local-vs-target diff. The latter must expose necessary platform differences instead of being dominated by structural churn. Remove obsolete workarounds only after verifying the replacement path.

Example note (adapt the content to verified evidence):

# NOTE(MetaX): The target upstream path quantizes this projection to FP8.
# This MACA path uses BF16 because <verified component constraint>.
# Preserve <layout/scale invariant>; revalidate when <capability> is available.

Investigate upstream before fixing a suspected bug

For every potential bug found during validation, first inspect the equivalent path in the target upstream revision, including dispatch and relevant dependencies. Where feasible run the same discriminating reproduction. Classify the cause as an adaptation regression, existing MetaX defect, shared upstream defect, component issue or environment mismatch. Distinguish source-based suspicion from reproduced upstream failure.

If upstream has or may have the same issue:

• First look for the smallest model-local fix or workaround that preserves upstream structure and the intended MACA behavior. When making such a fix, add a nearby NOTE(MetaX) explicitly saying the target upstream may also be affected, citing the symbol/revision and evidence or uncertainty. Explain the local workaround and its removal condition. Do not imply it is a MetaX-only adaptation defect.
• If resolving that shared defect requires changing other modules/components, do not expand the fix into those dependencies for this bug. Add a targeted logger.warning (or logger.warning_once when available) and report the limitation and repair plan. Prefer configuration/construction time over repeated token-time logging. Explain the trigger, consequence and known workaround without claiming the bug is fixed.
• Preserve existing rejection/capability checks. A warning does not establish support, justify enabling an unsupported path or replace an existing error with silent success.
• This warning-only boundary concerns repairs to shared upstream bugs. It does not cancel the recursive dependency updates required for the requested model upgrade. Follow explicit user authorization if they separately request the cross-module fix.

Example shared-defect note:

# NOTE(MetaX): Target upstream <revision/symbol> also appears to bypass <contract>.
# <Evidence; state if source-inspected only>. Keep this workaround local by <action>.
# Revisit when upstream handles <condition>; do not remove on version alone.

Validate and report

Apply the common skill's isolated-validation and evidence rules to these model checks.

• Verify registration and fresh-process construction, then weight loading, transformed parameter state, dispatch and affected numerical behavior. Test meaningful boundary cases and unsupported combinations from the difference matrix.
• Use real installed kernels and independent numerical references where available. Test model wrappers as well as raw APIs. Isolated mocks can test constructor or routing contracts, but do not establish production reachability or GPU correctness.
• For parallel changes, check collective ownership and residual semantics. If multi-GPU execution is unavailable, distinguish constructor/source evidence from distributed numerical validation. Likewise, a wrapper check is not an end-to-end LoRA/MTP test.
• Record runtime origins and any process-local optional-dependency workaround. Run relevant formatting, lint, type and diff checks; disclose unavailable checks.
• Re-review every finding after edits, including prior failures masked by earlier exceptions. Check for concurrent source changes before reporting final results.

Report the target/environment, difference matrix, dependency coverage, concrete changes or findings, upstream-bug attribution, warning-only unresolved cases, reproducible validation and untested scope. No separate audit file is mandatory. Do not call a model fully supported based only on imports, signatures or a passing kernel micro-test.