---
name: vllm-metax-patch-upgrade
description: Audit and adapt monkey patches in vllm_metax/patch/ against a target upstream revision. Decide whether to retain, update, migrate, or remove each patch; maintain patch headers and explanations; validate changes and record evidence. Use only for compatibility work on this directory, not standalone attention backend, model, kernel, or other adaptations elsewhere in vllm_metax.
---

# vLLM-MetaX Patch Upgrade

Preserve necessary MetaX behavior while inheriting the target upstream implementation.
Deliver reviewable changes, a complete patch inventory with decisions, and accurate
validation results. Explain why each difference exists and when it can be removed.

## Scope

Apply this skill only when the requested adaptation concerns `vllm_metax/patch/`.
An implementation adapted from upstream is not automatically a monkey patch in
this scope. Standalone work on attention backends, models, kernels, or other
directories must use the normal repository workflow, without inheriting this
skill's patch headers or patch audit requirements. The common environment workflow
applies through the relevant upgrade skill.

For an in-scope patch, inspect upstream code, callers, registrations, and tests
outside the directory as needed. Changes there must directly support that patch's
adaptation, removal, migration, or validation. If a request spans both patch and
non-patch work, apply this skill only to the patch portion; keep unrelated backend
or model findings out of `vllm_metax/patch/AUDIT.md`.

## 1. Establish the baseline and repository requirements

- Read applicable `AGENTS.md` files, `vllm_metax/patch/README.md`, patch templates,
  and existing audit records. Follow current repository requirements and user instructions.
- Inspect working-tree and staged changes; preserve existing work. By default, do
  not commit, stage changes, alter installed dependencies, or modify the upstream checkout.
- Read and apply [vllm-metax-upgrade-common](../vllm-metax-upgrade-common/SKILL.md)
  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.

## 2. Inventory every patch and its activation path

Start from the `vllm_metax/patch/` file list and trace plugin entry points and package
initializers. Search beyond `@patch`: include direct attribute assignments, registry
mutations, `sys.modules` redirects, imported aliases, and disabled or unimported patches.

For each patch, record its file, target symbol, purpose, activation status, upstream
location, MetaX differences, decision, evidence, and validation approach. A single
file may contain patches with different decisions. Classify templates, shared helpers,
and aggregate import modules separately as infrastructure.

## 3. Compare upstream behavior and decide per patch

Read the original explanation, complete target implementation, relevant helpers, and
callers before deciding. AST comparisons can help with signatures and function bodies.
Trace dynamic exports, inherited methods, and imported aliases to their definitions;
a failed static lookup does not establish that an upstream target was removed.

| Decision | Evidence and action |
| --- | --- |
| Remove | Upstream fixes the issue, the affected path no longer exists, or an existing hook/redirect already provides the behavior. Verify callers, then remove the implementation and its activation entries. |
| Migrate | A registry, platform hook, CustomOp, or narrower extension point now supports the requirement. Move to it, verify dispatch, and remove the redundant monkey patch. |
| Update | MetaX behavior is still necessary, but upstream signatures, helpers, branches, or contracts changed. Reapply only the required differences to the current implementation. |
| Retain | The patch remains compatible and addresses a concrete platform, hardware, checkpoint, or product requirement. Record the reason and removal condition. |

- Age, code similarity, disabled status, or an existing PR link alone is not evidence
  for removal. Inspect history when needed and confirm the fix exists in the target revision.
- Investigate why upstream deliberately removed old behavior before restoring it
  from a patch's copied implementation.
- Separate hardware constraints from software bugs. Without suitable GPU or distributed
  evidence, do not declare shared-memory, warp, IPC ABI, or communication restrictions
  resolved. Record the reason for retention and the remaining validation need.
- Verify behavioral claims in comments against code. For example, a stable sort over
  misplaced requests does not necessarily preserve order across an entire region.

## 4. Make the smallest complete adaptation

- Prefer existing upstream registration or extension points. A small wrapper should
  delegate unaffected behavior to the original implementation and preserve explicit inputs.
- When a full replacement is necessary, preserve the target upstream name, signature,
  return contract, decorators, and unchanged code. Mark only the required MetaX
  differences. Do not let an old function copy suppress new validation, model support,
  or resource cleanup.
- Preserve descriptor semantics, Triton decorator order, lazy imports, and initialization
  timing. Check whether `from ... import ...` already bound the old object; successful
  patch import does not prove every caller uses the replacement.
- Follow repository templates for `@patch`. Use `allow_missing=True` only when adding
  an intentional compatibility attribute, never to hide renamed targets or typos.
- Inspect argument semantics rather than forwarding by name alone. For example,
  `scale=None` may select dynamic quantization while a supplied scale selects static quantization.
- Add or update platform-specific registry entries without replacing the entire table.
  Compatibility defaults must preserve explicit user settings. Avoid unnecessary mutation
  of caller-owned dictionaries or configuration objects.
- On removal, check references, import order, and overlapping replacements. Keep unrelated
  cleanup outside the task.

For quantization, tokenizer, batch ordering, registration, allocator, or kernel patches,
consult [review-patterns.md](references/review-patterns.md) as needed. Its examples guide
inspection; they are not fixed decisions for future upstream versions.

## 5. Treat explanatory comments as part of the deliverable

Follow the current patch README. Every Python file in the patch directory, including
initializers and shared utilities, should have the dedicated header. Preserve license
and copyright notices. Templates may retain fill-in placeholders; active files must
contain meaningful descriptions.

```python
# -----------------------------------------------------------------------------
# Note: Describe the concrete issue, trigger, and reason for the MetaX difference.
#
# Affected versions: State evidence-backed affected versions and the reviewed revision.
#
# Remove at: Give a verifiable condition, such as upstream support or a resolved limit.
# -----------------------------------------------------------------------------
```

- Do not substitute scattered `Verified against`, `Remove when`, or docstrings for
  these fields. Describe infrastructure honestly without inventing an upstream defect.
- Preserve existing algorithm explanations, examples, parameter descriptions, and return
  semantics. Update them when implementation changes; do not delete useful explanations
  merely to shorten the file.
- For complex sorting or kernel patches, explain input/output contracts, invariants,
  key indices and mappings, the rationale, and the actual differences from upstream.
- Distinguish correctness requirements, platform restrictions, performance policy, and
  implementation choices. Preserving non-decode request order does not mean one specific
  request must precede another for numerical correctness.
- Include a discriminating input/output example for boundary behavior. Do not promise
  unmeasured performance gains. Match the source language and write for future maintainers.

## 6. Validate according to the change

- Run relevant lint, formatting, syntax, and diff checks. For comment/docstring-only
  changes, compare ASTs after removing docstrings to confirm executable behavior is unchanged;
  a full model suite is unnecessary.
- For behavioral changes, choose the least expensive tests that expose real regressions:
  boundary arguments, explicit settings, nested configurations, serialization, request/state
  alignment during reordering, and preserved upstream behavior.
- Run import smoke tests in fresh processes to avoid duplicate-patch failures. Verify
  both successful target import and that actual callers reach the replacement.
- Recheck environment correspondence after dependency installation, checkout changes,
  or changes to the interpreter, working directory, or import path. In the actual test
  process, record package `__file__`/`__path__`, relevant extension-module paths, and
  the active MetaX plugin origin; compare them with the preflight plan.
- For quantization, attention, or kernel changes, compare actual GPU output with a reference
  when the environment permits. Cover relevant boundary lengths, dtypes, layouts, and masks.
  Performance claims require benchmarks; communication claims require suitable distributed runs.
- Reuse nearby tests. If the root conftest introduces unrelated dependencies, an isolated
  test directory may use `--confcutdir`; state which fixtures this bypasses.
- Separate patch failures from environment ABI or optional-dependency failures. A narrowly
  scoped, process-local workaround may isolate unrelated paths. Do not silently modify the
  environment or report isolated tests as complete integration validation.
- Record the interpreter, commands, results, temporary workarounds, and untested scope.
  Mocked dispatch tests do not replace real kernel numerical validation.

## 7. Finish the audit and handoff

Update the existing `AUDIT.md` or repository-designated review record. Account for every
inventory entry and ensure decisions match the final code. Include:

- The environment correspondence table: interpreter/venv, both local checkouts and
  commits/dirty state, both installed distributions and package locations, effective
  import origins, content-comparison results, and any intentional source/wheel differences.
- Each retain/update/migrate/remove decision, concrete upstream evidence, and removal condition.
- Important behavioral differences, reproducible validation commands, results, and untested scope.

Conclude with the completed changes, key behavior changes, validation results, and audit
location. If the environment blocks validation, state what was completed and what remains
unverified. Do not equate source inspection or partial success with full model validation.
Once appropriate checks pass, expand testing only for new changes, failures, or unresolved concerns.