Skip to content

build: CI links only --target onebit, so a declared-but-undefined NPU symbol keeps main green while a full build breaks (#1573) #1575

Closed

Description

@bong-water-water-bong

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 full cmake --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 at npu/forward/include/q4nx_forward.h:154 and called
    at npu/forward/embeds_equiv_probe.cpp:76, but only the HybridInputs overload 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

  1. A declaration/definition pairing gate, device-free and CI-able. A small script that extracts the Q4nxNpuForward::<name>( declarations
    from npu/forward/include/q4nx_forward.h and the Q4nxNpuForward::<name>( definitions from npu/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 / copyright gates, and it makes the failure say step_batch_embeds (3-argument) is declared and never defined instead
    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.
  2. 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's build phase currently builds — the
    workflow only shows PHASES: build,ops,kat,kld,needle,placement — so this item starts with reading that phase's script.

Acceptance

Found while reviewing #1574. Not claiming a lane: I am reporting it because it outlives that one-line fix.

Activity

  1. bong-water-water-bong commented on Nov 8, 2026

    @bong-water-water-bong
    CollaboratorAuthor

    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 ctest declared_vs_defined): every member declared directly in Q4nxNpuForward must have a definition with the same arity under npu/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-argument HybridInputs overload 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:

    FAIL  Q4nxNpuForward::step_batch_embeds declared with 3 parameter(s) but only defined with 4 -- an overload with no body
    

    Red/green, measured

    this tree (main + the guard)                    -> rc 1, exactly that line and nothing else
    the same check against #1574's head (0c895f98)  -> rc 0
    

    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)

    1. A first cut flattened nested classes and reported Q4nxNpuForward::bytes — which is really StateSnapshot::bytes(), declared at q4nx_forward.h:110 inside the nested class. The scan is now brace-aware and only takes declarations at depth 0 of the class body.
    2. A second cut matched nothing at all, because the accumulated declaration statement had its ; 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 CLASSES map 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.

  2. bong-water-water-bong commented on Nov 8, 2026

    @bong-water-water-bong
    CollaboratorAuthor

    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's build phase actually builds) I will report on rather than change, since that phase is not mine.

  3. bong-water-water-bong commented on Nov 8, 2026

    @bong-water-water-bong
    CollaboratorAuthor

    #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_embeds declared 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 CLASSES are covered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions