docs(patches): give every patch a schema-checked upstream status record

[dorado269]

Why

deploy/docker/patch.upstream.status.md was a single hand-maintained table. It could not answer the question that actually decides whether a patch can be deleted — does this patch change bytes in this engine, on this pinned base — and it had no gate, so a patch could be added without a row. patch_mooncake_mamba_unpack.py went unindexed from 2026-08-02 to 2026-08-05.

What

Every patch under deploy/docker/patches/ now has a machine-checked record beside it.

file	role
<patch-prefix>.upstream.status.yaml	one record per patch (25 of them)
deploy/docker/patch.upstream.status.yaml	index, grouped by the library patched
patches/archived/patch.archived.yaml	retired patches, one list (6 entries)
patches/_schema/*.json	three JSON schemas
scripts/validate-patch-status.py	validates + cross-checks against the tree

Validation is strict: additionalProperties: false throughout, dates pattern-checked, commits [0-9a-f]{7,40}, digests ^sha256:[0-9a-f]{64}$, engines and libraries enumerated. Beyond schema shape, the validator also checks that every patch on disk has a record, that the index totals match what is there, and that an archived entry claiming deleted names a commit it can be recovered from — so the set cannot silently drift from the tree.

Wired into .pre-commit-config.yaml, which CI already runs with --all-files. tests/unit/test_patch_status_records.py has 8 tests, 6 of which check the validator actually refuses bad input.

Beyond the fields the old table had, each record carries per-engine effect (op / no-op / not-applied / unverified) with its evidence, an enumerated alive_because.reason, and drop_signal — how you will find out the patch is dead.

Four things writing this down surfaced

• Four patches can only be marked unverified. Whether patch_vllm_mooncake_blocksize.py, patch_moriio_write.py and the DSv4 MoRIIO patches are load-bearing depends on what the pinned base already carries, and nobody has checked. Each is one grep inside the image.
• HIPFILE_GIT_REF is unpinned. build_hipfile.sh clones HEAD of ROCm/rocm-systems, so two images built from the same infera commit either side of rocm-systems#7386 (merged 2026-07-16) contain different hipfile code. A reproducibility problem independent of any patch.
• One patch does not drop when its merged PR lands. patch_hicache_rocm_staged_write_back.py's MERGED PR (sglang#28534) is what introduced the defect; it drops on the open #30350. Its own drop check is a precondition test, not an anchor test, because #30350 never touches our anchor.
• Six patches cannot announce their own obsolescence — they keep applying cleanly after upstream fixes the problem, so only the pinned version tells you. Now enumerable by drop_signal.

Review notes

• Nothing was deleted. patches/vllm-dsv4/legacy/ → patches/archived/vllm-dsv4/ and the superseded .md is kept as patches/archived/patch.upstream.status.superseded.md, both via git mv so history follows. Delete the superseded .md here if you would rather it went.
• Image behaviour is unchanged. Every Dockerfile patch loop globs *.py or patch_*.py, so no .upstream.status.yaml can be executed. Nothing copies patches/ wholesale, so _schema/ and archived/ never enter an image. The archived legacy patches are no longer copied into the vLLM image at all.
• Two fields are deliberately nullable, because forcing a value would mean inventing one: image digests (only Dockerfile.vllm pins one — the rest record digest_source: unresolved) and PR authors.
• The records absorbed the old table's prose and I compressed some of it. If any patch's argument reads thinner than before, patches/archived/patch.upstream.status.superseded.md is in this branch to diff against.

Verification

$ python3 scripts/validate-patch-status.py
patch status OK — 25 record(s), 25 indexed, 6 archived

$ pytest tests/unit/test_patch_status_records.py -q
8 passed

$ ruff format --check && ruff check   # both clean

No image was built, so the four unverified rows stay unverified — they are recorded as such rather than guessed at.