fix(BACKEND-ATTN-REGISTRY): CPU_ATTN was a name in a list, so a head size FLASH_ATTN declines left the CPU with no backend (#1371)

[localai-bot]

CpuPlatform::get_attn_backend_priority has returned {CPU_ATTN, FLASH_ATTN}
since the platform seam landed, mirroring cpu.py:75-87, where CPU_ATTN is the
only answer upstream ever gives on a CPU. Nothing ever registered it. Every CPU
selection walked past the first name and stopped on FLASH_ATTN, and that was
recorded as behavior-preserving, which it was: our CPU paged-attention kernel
reads FlashAttention's NHD layout, so the second name described the CPU's real
KV geometry.

It was behavior-preserving only for as long as FLASH_ATTN accepted everything
the CPU asked of it. #1332 M1 (369ea7fd4) ported validate_configuration, and
with it flash_attn.py:170-178's rule that a head size must be a multiple of 8.
That rule is correct and it is about the FA2 kernel. It is now also, on four
device types, about kernels that are not FA2, because FlashAttentionBackend is
registered by NAME for kCPU, kMETAL, kVULKAN and kTENSTORRENT on the stated
precondition that those kernels share its LAYOUT. A CPU request with head_size 6
therefore matched no registered backend at all and SelectAttentionBackendName
threw out of GPUModelRunner::initialize_kv_cache.

So the fallback was never removed. There was never a fallback: CPU had exactly
one registered dense backend, and it stopped answering. This registers the other
one. CpuAttentionBackend is ported from cpu_attn.py:39-110 @ pin
5559679229, and CPU selection now returns CPU_ATTN for every request, which is
what upstream returns. FLASH_ATTN stays registered for kCPU as the second entry.
The head_size % 8 guard is untouched; a case here asserts FLASH_ATTN still
refuses head_size 6 on CPU, so repairing this by widening the guard turns that
line red.

The capability surface is gated, and the upstream test for it is ported

Six of the seven declarations in the new class were ungated when it first landed.
A review corrupted every one except kName/get_name and get_kv_cache_shape
-- including WIDENING get_supported_kernel_block_sizes from {16} to {1},
which would let CPU_ATTN accept block_size 1 -- and every test binary stayed
green at Status: SUCCESS!. A declaration nothing reads is a claim, and this
registry turns claims into selections.

supported_dtypes is the one that changes a live answer. It adds
vt::DType::kF32, and validate_configuration consumes cfg.dtype through
supports_dtype, so before this change a CPU f32 request was REFUSED with
dtype not supported: FLASH_ATTN declares {f16, bf16} and nothing stood
behind it. Upstream has a test for exactly that, and it was not ported.

It is ported now, from
tests/kernels/attention/test_attention_selector.py:230-241 @ pin
5559679229bc961848b121ccdeaa8fa5d79bec98 -- test_fp32_fallback, cpu arm,
get_attn_backend(16, torch.float32, None).get_name() == "CPU_ATTN" on
CpuPlatform. Carried over field for field through SelectAttentionBackendName,
asserting both halves: FLASH_ATTN's refusal with its single reason string, and
CPU_ATTN validating the identical request with no reasons at all. The cuda and
hip arms are NOT ported and the case says why rather than dropping them in
silence -- this tree registers no FLEX_ATTENTION, and RocmAttentionBackend
declares no head-size list, so the hip arm's expected throw would arrive for the
dtype rather than for upstream's minimum head size of 32.

A second case pins the rest, entry for entry against cpu_attn.py. Each block
asserts the DECLARED list and the predicate the base class derives from it,
because they fail differently: deleting an override moves the list to the base
default, while corrupting entries leaves the shape intact. Widening is covered in
its own direction -- supports_block_size(1) and (8) are asserted FALSE, which
is what the {16} -> {1} corruption trips.

Eight mutations on b8049371, each printing its compile status beside its
verdict. Base: test_attn_backend_registry 20 cases, 125 assertions,
Status: SUCCESS!, rc 0. The head moved to 3853ec5f afterwards for two more
origin/main merges, neither of which touches any of the three files involved --
verified by git diff b8049371..3853ec5f over cpu_attn.h, cpu_attn.cpp and
test_attn_backend_registry.cpp, which is empty.

#	Corruption	compile_rc	Result
M1	supported_dtypes drops kF32	0	2 cases / 5 assertions red
M2	supported_kv_cache_dtypes gains fp8_e5m2	0	1 case / 2 assertions red
M3	get_supported_kernel_block_sizes {16} -> {1}	0	1 case / 5 assertions red
M4	supports_non_causal true -> false	0	1 case / 2 assertions red
M5	supports_sliding_window true -> false	0	1 case / 2 assertions red
M6	supports_attn_type drops encoder_decoder	0	1 case / 1 assertion red
M7	get_supported_head_sizes {} -> upstream's eleven	0	3 cases / 13 assertions red
M8	the production registrar deleted	0	5 cases / 6 assertions red

Every one exits 1 at Status: FAILURE!, and every one restored both files
byte-for-byte, verified by sha256 rather than by git status. M8 is the
reachability re-proof on the repaired head: the class still compiles and still
constructs, and the gate goes red because nothing reaches it. Read its assertion
count against the others -- 71, not 125 -- because five thrown cases run no
assertions at all. That collapse is the second half of #1371's report, reproduced
here on purpose.

Three live comments said the opposite of what the tree does

registry.h's own doc comment on SelectAttentionBackendName promised
"FLASH_ATTN" on CPU. runner.cpp said the same in the selection block.
porting-inventory.md, whose header declares it a living record kept up to date
at all times, still described CPU_ATTN as named-but-unregistered. All three now
state the CPU answer, and all three note that both names report the same NHD
layout, so the geometry did not change with the name.

One more live surface stated the old CPU answer in the present tense:
.agents/specs/extensibility-platform-seam-2026-07-18.md, under its dated
"Item 4 -- LANDED 2026-07-19" heading. Its paragraph is kept exactly as written,
because it records what was true on that date. A superseded marker naming #1371
and this pull request is added beside it, so a grep cannot land a reader on a
false CURRENT answer with nothing to warn them.

parity-ledger.md's 2026-07-19 row is deliberately left alone. It is a dated
entry recording what that landing did, it was true when written, and the ledger
declares itself append-only, one row per commit, newest last. Editing a dated
row in a declared append-only log falsifies provenance rather than correcting
it. That is history; porting-inventory.md, which declares itself kept up to
date at all times, is live coverage, and it was corrected.

There are three deviations from cpu_attn.py, not two

supported_kv_cache_dtypes drops "fp8_e5m2" from upstream's four entries. The
omission is right -- KvKind::kFp8 resolves to LoadKvFp8E4M3 alone and both vt
entry points VT_CHECK-refuse an e5m2 KV cache -- but the header said "TWO
RECORDED DEVIATIONS" and justified this one by claiming FlashAttentionBackend's
list is trimmed for the same reason. It is not trimmed. It is
flash_attn.py:74-80 verbatim, and upstream's FA backend never claimed e5m2
either, so it is no precedent for anything. The header now records three, and the
third rests on our own kernel's single encoding.

That anchor was wrong in the round that introduced it, and it is corrected here.
flash_attn.py:71 is a BLANK line at the pin; supported_dtypes is at :73
and the five-entry supported_kv_cache_dtypes at :74-80. The range offered as
proof the list is VERBATIM stopped at "fp8",, so it did not contain
"fp8_e4m3" or the closing bracket -- it did not contain the list it was
proving. Three sites carried it: cpu_attn.h:70 and two comments in
test_attn_backend_registry.cpp. Each was re-derived at the pin and asserted
UNIQUE in that file, and each now matches the four sites this tree already had
right, among them backend.h:384 on the very declaration under discussion and
test_attn_validate_configuration.cpp:110 in the sibling suite.
scripts/check-symbol-anchors.py cannot catch this: it documents that it
deliberately does not verify line citations, so its green was never coverage
here.

The header also states outright what deviation 2 left implicit: an empty
head-size list is WIDER than upstream's eleven sizes, 0 included. That is our
scalar kernel's genuine generality and the base class's own default, and it is
still a wider claim than the file this one is ported from makes. docs/USAGE.md
now says the user-visible half of the same thing: the CPU serves f32, and refuses
fp8_e5m2 by name -- and, since the page named the CPU's KV-cache list without
ever naming the GPU's, that fp8_e5m2 refusal read as this project's limitation
when it is the reference engine's own. Both lists are stated there now.

docs/FEATURES.md records the backend surface change on the CPU row, in the
shape the ROCm row already uses for the directly analogous ROCM_ATTN
registration at #1056/#1065. Registering a CPU attention backend is a backend
surface change, which is the trigger AGENTS.md names for that page. The
convention is not uniform -- the CUDA row names no attention backend at all --
so this follows the one precedent that exists rather than inventing a shape.

Evidence

CPU-only, no lease, -DVLLM_CPP_CUDA=OFF, on 4c649319 (Debug for the red;
Release for the re-run after the fifth merge).

RED at the pinned base 5f68e60df22670a714f31d6362695b012b2598e2:
test_nemotron_h_paged_forward exits 1 with 12 cases, 2 passed, 10 failed, and
18 assertions. GREEN after: exit 0, 12 of 12 passed, 3256 assertions. The
assertion count is the number to read. A thrown doctest case runs no assertions,
so the failing run printed 0 failed beside ten throws, and any gate matching on
the assertions line saw a clean sweep of eighteen.

Focused gate, all rc 0 and re-run in full at 4c649319:
test_attn_backend_registry 20/20 at 125 assertions,
test_attn_validate_configuration 21/21 at 76, test_platform 14/14 at 114,
test_runner 19/19 at 543, test_nemotron_h_paged_forward 12/12 at 3256. Every
one reports Status: SUCCESS!, which is read beside the assertion count rather
than instead of it.

scripts/agent-preflight.sh --fail-on-skip at 4c649319: All gates green,
rc 0, ZERO skipped and ZERO failed. commit-trailers and commit-style both
RAN and both report ok against origin/main 63d87805c, which is what the five
merges in this branch are for -- while the branch was behind, both gates
reported SKIP, and a skip is not a green: it means neither gate reported
anything about this tree. test_cpu_x86_llamacpp_floor, which had refused to
measure under NO_QUIET_WINDOW ... load=194.85 on earlier runs, passes on a
quiet box; both tests/scripts/test_cpu_x86_llamacpp_floor.py and
scripts/cpu-x86-llamacpp-floor.sh are byte-identical to origin/main here and
this branch touches neither, so its earlier red was this box's load average and
never a verdict about any code.

test_nemotron_h_paged_forward is the test currently failing build-test-cpu on
every open pull request, because it is the test #1371 breaks. It passes here.
test_qwen3_5_decode_graph_seam segfaults on main independently
(#1422) and is untouched by
this branch, so a red build-test-cpu on this pull request has to be read by
WHICH test failed, not by its colour.

Closes #1371.

Metal, Vulkan and Tenstorrent carry the identical inherited rule and are filed as
#1389 rather than repaired here: none has an upstream backend to mirror, so each
needs its declared capabilities authored, and that is a spec. kROCM is unaffected
because RocmAttentionBackend declares no head-size constraint.

FOLLOWING_AGENTS_PROTOCOL

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: AGENT:claude-opus-5 [claude-code]