[bong-water-water-bong]

What

A2a2 of #803, stacked on the plan-designs section in #1330. A2a taught plan.json to carry a per-role kernel set; a section is only useful if something writes it, and only safe if it names exactly what the engine derives. Both halves here, and neither is assumable.

The generator

tools/npu_plan.py gains designs_from_config(), which ports the four dense-family rules from q4nx_derive_designs() onto the same pad_k/pad_n grids and the same artifact names:

role	K	N
QKV	pad_k(H)	pad_n(q_rows·(gate?2:1) + 2·NKV·HD)
O	pad_k(q_rows) — undoubled	pad_n(H)
GU (or G + U)	pad_k(H)	pad_n(2·IM) (or pad_n(IM) each)
D	pad_k(IM)	pad_n(H)

and the plan carries the section only when the tool can state the whole set. Families it does not model yet — MLA, a GDN layer mix, Gemma4's second attention type / per-layer embeddings / double-wide MLP — emit no section: the engine's check is both-ways, so a partial set would be refused at load, and absent means the engine keeps deriving. Emitting nothing is the honest answer there, not a smaller section.

The parity instrument

tests/npu_derive_designs_dump prints the engine's own q4nx_derive_designs() as ROLE M K N elf lines, and tests/npu_plan_designs_parity_test.py (ctest npu_plan_designs_parity) requires the two sets to be identical across a matrix of six dense configs — the 0.6B's own dims, a padded hidden (896 stored at K 1024, the case engine#845 exists for), q|gate doubling, split gate/up, a derived head_dim, and a _b8 family — plus five families that must emit no section.

It earned its place before it was even committed

The parity test caught two real disagreements in my first port:

1. O's K is the undoubled q width. q4nx_derive_designs keeps q_rows = NH·HD for O and doubles only QKV's N under attn_output_gate; I had doubled both. My hand-checked 0.6B case passed, and the attn_output_gate case caught it.
2. The _b8 suffix is not part of the derivation — the forward rewrites every artifact name afterwards — so the dump instrument had to learn both attn_output_gate and the tag, or it would have "agreed" with a wrong generator.

It also moved A2a's check in the forward to just before the context-creation loop: the pb16i family appends its split designs and the b8 family rewrites every name between the derivation and there, so that is the first point at which designs_[] is what a target would actually open. (At the old position, a b8 model's plan would have been compared against unsuffixed names — a false refusal waiting to happen.)

Measured (one npu-hold ticket, amdxdna 0 → 0)

The generated plan, end to end through the forward, on the 0.6B container:

[wrote /tmp/a2g-demo/plan.json (28 layers, gate/up fused, layout rm, tag none, attention causal)]
designs: QKV 128 1024 4096 full_i8_QKV_K1024_N4096.elf
         O   128 2048 1024 full_i8_O_K2048_N1024.elf
         GU  128 1024 6144 full_i8_GU_K1024_N6144.elf
         D   128 3072 1024 full_i8_D_K3072_N1024.elf

== the engine accepts it: the same four init lines, no refusal
== perturb one artifact in the GENERATED plan:
   plan designs(GU): elf "full_i8_GU_K1024_N6144_b8.elf", the container derives "full_i8_GU_K1024_N6144.elf"

Rows

row	verdict
npu_plan_designs_parity (new)	PASS — 6 dense configs identical, 5 families emitting no section
npu_plan, npu_design_grid	PASS
generated plan accepted by the forward, and its pertubation refused	PASS (one ticket)
build	PASS — Release, ONEBIT_NPU=ON, ONEBIT_JINJA=ON, ONEBIT_NPU_DEBUG_DUMPS=OFF, thermal-run.sh
CI on the new test target	bound to npu_forward_loader_test via add_dependencies, because ci.yml names its build targets explicitly and this lane has no workflow scope (the same mechanism host_gemm_pad_test uses)

Stacked on #1330 (base 1bit/npu-p4-a2-plan-designs): merge #1330 → this one. A2b (the target opening the set) and A2c (load_block() owning residency) are still to come.

Refs #803 (A2a2 of three). Part of #799.

[bong-water-water-bong]

#1333 ready for review at 6d1cf0a6 — A2a2 of #803, stacked on #1330 (base 1bit/npu-p4-a2-plan-designs; merge order #1330 → this).

One line each on why it is worth reading: the generator ports four geometry rules from q4nx_derive_designs() onto the same grids and emits no section at all for families it cannot state completely (MLA, GDN mixes, Gemma4 second attention type / PLE / double-wide MLP), because the engine's check is both-ways and a partial section would be refused at load; and a new parity test holds the Python to the C by running both on six dense configs plus five must-omit families.

It paid for itself immediately, and both catches are in the body: O's K is the undoubled q width (my first port doubled it under attn_output_gate; my hand-checked 0.6B case passed and only the parity case caught it), and the _b8 name suffix is the forward's rewrite, not the derivation's — which also meant A2a's check had to move past the point where pb16i appends its split designs and b8 renames its artifacts, i.e. to the first moment designs_[] is what a target would actually open.

End-to-end in one ticket: the generated plan loads with the same four init lines and no refusal, and perturbing one artifact in the generated plan is refused by name (plan designs(GU): elf "…_b8.elf", the container derives "….elf").

[github-actions]

Preparing review...

[bong-water-water-bong]

VERDICT: READY at 6d1cf0a6cde894dd5001afe6043879ac9ecb3cb5. The generator is held to the engine by a parity test that bites on the exact bug it was written to catch, and the check now runs on the set a target would actually open. (Reviewed as its own delta over #1330's head 6c5b369f: one commit, 5 files, +305/−26. Merge #1330 first, as the body says.)

Run here (Release, host, under thermal-run.sh)

• tests/npu_plan_designs_parity_test.py tools/npu_plan.py build/npu_derive_designs_dump (the ctest invocation) → npu_plan_designs_parity: ok. npu_plan_test → npu_plan: ok. npu_design_grid_test → all cases ok. copyright.py --check rc 0.
• Mutation, the body's own first bug: with O built from pad_k(qkv_rows) (the gate-doubled width) instead of pad_k(q_rows) in designs_from_config(), parity fails FAIL attn_output_gate: generator set == engine set, rc 1. Restored, it passes. So the doubled-O case is pinned by the test, not by a hand check.
• The moved check: q4nx_derive_designs() at q4nx_forward.cpp:940, the pb16i split designs appended at :966-972, the _b8 rename at :1076-1085, designs_agree at :1113, and the first adopt_geometry/make_ctx at :1124/:1149. That is the first point where designs_[] names what the target opens, so a b8 plan is compared against suffixed names (the false refusal the body describes, at #1330's position, is gone).

Design choice, endorsed: emitting no section for the families the port doesn't model (MLA, the GDN mix, Gemma4's second attention, PLE and double-wide MLP) is right. The engine's check runs both ways, so a partial section would refuse at load, while absent means "derive".

Note for A2b, not this PR: the section and its check cover the M=128 set. The M=16 decode twins (designs16_, built later at make_ctx16) are neither written nor checked. When A2b has the target open the plan's set, the twins need either their own rows or an explicit "derived from the M=128 set" rule.

Not re-run: the one-ticket end-to-end (generated plan accepted, perturbed artifact refused).