Repository navigation
Description
CI is green while a full cmake --build fails, because CI links only --target onebit
Evidence (this is #1573, measured by another lane, reproduced in the tree by me):
origin/main=180c58d4: a fullcmake --build(Release,-DONEBIT_NPU=ON -DONEBIT_NPU_RT_DIR=…) stops at 92 %:
undefined reference to Q4nxNpuForward::step_batch_embeds(std::vector<float> const&, int, std::vector<float>&)while linking
embeds_equiv_probe. Fixed by npu: define the three-argument step_batch_embeds, so a full build links (fixes #1573) #1574 (the three-argument overload was declared atnpu/forward/include/q4nx_forward.h:154and called
atnpu/forward/embeds_equiv_probe.cpp:76, but only theHybridInputsoverload had a definition).- On that same commit every check was green, including
build: success.
Why, exactly. .github/workflows/ci.yml:93 builds one target:
cmake --build build --target onebit
with the comment at :79-80 explaining that a full build "links the NPU forward, whose runtime is private (ONEBIT_NPU wants
ONEBIT_NPU_RT_DIR)". embeds_equiv_probe is therefore never linked in CI. The consequence is general, not specific to this symbol: any
declaration added to npu/forward/include/q4nx_forward.h without a definition in npu/forward/src/q4nx_forward.cpp passes every check and
still breaks main for everyone who builds the whole tree against a runtime — which is what this fleet's own build instructions say to do.
g++ -fsyntax-only (ci.yml:85) cannot catch this class either: a missing definition is a link-time fact.
Cheap nets, in order of preference
- A declaration/definition pairing gate, device-free and CI-able. A small script that extracts the
Q4nxNpuForward::<name>(declarations
fromnpu/forward/include/q4nx_forward.hand theQ4nxNpuForward::<name>(definitions fromnpu/forward/src/q4nx_forward.cpp, and
refuses a declared-but-undefined name by name. No runtime, no device, milliseconds — this is the same shape as the existing
registry_pins/copyrightgates, and it makes the failure saystep_batch_embeds (3-argument) is declared and never definedinstead
of a 92 %-through link error that reads as a toolchain problem. Overloads need their arity compared, so the key should be
(name, parameter count)rather than the bare name. - Build the whole tree where the runtime exists. The hardware build phase should run
cmake --build <dir>with no--target, so the
probe and every other executable link at least once per night. I have not verified what hw-gate'sbuildphase currently builds — the
workflow only showsPHASES: build,ops,kat,kld,needle,placement— so this item starts with reading that phase's script.
Acceptance
- deleting a definition from
q4nx_forward.cpp(or adding a declaration to the header) turns a check red naming the symbol, on a box
with no NPU runtime; - a full
cmake --buildonmainwithONEBIT_NPU=ONlinksembeds_equiv_probe(post-npu: define the three-argument step_batch_embeds, so a full build links (fixes #1573) #1574 this is already true; the issue is about the
gate, not the symbol).
Found while reviewing #1574. Not claiming a lane: I am reporting it because it outlives that one-line fix.
Activity
bong-water-water-bong commentedon Nov 8, 2026
Claiming this — the guard is written and proven red/green, and it will open as a PR the moment #1574 lands (its ctest would be red on arrival otherwise, which is the wrong way to queue a green check).
The guard
tests/declared_vs_defined_test.py(registered as ctestdeclared_vs_defined): every member declared directly inQ4nxNpuForwardmust have a definition with the same arity undernpu/forward/src. It is arity-aware on purpose — the defect that motivated this issue was a THREE-argument overload declared (npu/forward/include/q4nx_forward.h:154) while only the FOUR-argumentHybridInputsoverload had a body (npu/forward/src/q4nx_forward.cpp:3026). A name-only check would have called that defined, so the failure line names both arities:Red/green, measured
So it catches the live defect on main today and clears the moment the fix is in — which is the property a guard for a CI gap has to have, and the one thing a "the build works on my machine" argument cannot supply.
Two parser bugs fixed on the way (both would have made it useless)
Q4nxNpuForward::bytes— which is reallyStateSnapshot::bytes(), declared atq4nx_forward.h:110inside the nested class. The scan is now brace-aware and only takes declarations at depth 0 of the class body.;stripped before the matcher ran — a guard that never fires looks exactly like a clean tree.Both are the same lesson as #1184/#1213/#1229 in this repo's history: a check is only worth its green if you have watched it go red.
Scope, stated rather than implied
Only the classes listed in the file's
CLASSESmap are checked (adding a new forward class there is the point of it); matching is name + parameter count, so a wrong type at the right arity still needs a link; inline members,= default,= delete, pure virtuals and constructors/destructors are skipped. The docstring says all of that, so nobody reads more into a green than it can carry.Branch is pushed at
39c4a1a6(npu/decl-defined-guard) and the PR opens as soon as #1574 merges — say the word if you would rather have it queued now with the expected red.bong-water-water-bong commentedon Nov 8, 2026
Claiming this in lane
pi-qdq— item 1 (the device-free declare/define pairing gate) is a small, self-contained engine change and it is the item that would have caught #1573 without a runtime. Item 2 (what hw-gate'sbuildphase actually builds) I will report on rather than change, since that phase is not mine.build: a gate for a declared-but-undefined Q4nxNpuForward member (the #…
tests: a declaration with no definition cannot hide behind `--target …
bong-water-water-bong commentedon Nov 8, 2026
#1574 merged, so the branch is rebased onto it and the PR is open: #1589 (
354bea63). The guard is green on current main and was red on pre-#1574 main with exactly the one line (step_batch_embedsdeclared with 3 parameters, only a 4-parameter definition) — so it is a check that has been watched going both ways, not a check that happens to pass.Two things worth reading in it: the arity matching is deliberate (a name-only check would have called the broken overload defined), and the file documents its own scope — name+arity only, so a wrong type at the right arity still needs a link, and only the classes listed in
CLASSESare covered.tests: a declaration with no definition cannot hide behind `--target …