From 402af225a6683c14a65aa53dab0dab773ef42e0d Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 21:51:01 -0400 Subject: [PATCH 001/180] bump llama.cpp to 5514ebea: a measured zero host figure refuses, and a failed HRX init says why (#1768) Moves third_party/llama.cpp 831629fe9a -> 5514ebea44. Two merged commits, and the second one fixes a trap that cost this lane two runs today: 5514ebe hrx: a measured zero host figure refuses again, instead of reading as 'unreadable' 6ea7477 hrx: log the status when the HRX runtime fails to initialise 5514ebe is the review point from #259 that merged without it: both call sites wrote `host_raw == 0 ? kHostUnknown : host_raw`, and host_memory_available_bytes() returns 0 both when /proc/meminfo cannot be read AND when MemAvailable is genuinely 0 - so an exhausted host read as 'unknown' and the host term was dropped, in the case the comment above those lines calls the worst moment to admit a launch. The read now reports whether it read anything and the mapping lives in pool_host_term(); a measured zero refuses through the live check, which the suite pins with five new arms. 6ea7477 covers the other half of the same trap: create_registry_context() swallowed the hrx_gpu_initialize failure and registered no devices, so a build with GGML_HRX=ON answered --list-devices with '(none)' and every run died at 'invalid device: HRX0'. That is what the records show for /home/bcloud/wt/pi-gate and ~/wt/hl-engine-build-c20 until LD_LIBRARY_PATH carried the TheRock _rocm_sdk_core lib. Verified: registry regenerated at the new pin (only the sources sha moves; counts stay 298/9/298/298), registry_build.py --check-pins passes, check_pins.py says '831629fe9 -> 5514ebea4 is ahead'. This bump is also the check I could not run locally: ggml-hrx.cpp needs hrx_runtime.h from the hrx-system submodule include path, so 5514ebe's edit to that file has never been compiled here. hrx_build on this PR configures -DONEBIT_HRX=ON and builds onebit, which is what will prove it. Co-authored-by: pi-hrx-sched --- registry/architectures.json | 2 +- third_party/llama.cpp | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/registry/architectures.json b/registry/architectures.json index 9f2a7e7ef..2d5179ad6 100644 --- a/registry/architectures.json +++ b/registry/architectures.json @@ -1,7 +1,7 @@ { "about": "HF architecture -> GGUF architecture and the backends whose code accepts it. Generated by tools/registry_build.py from the pinned sources; do not edit.", "sources": { - "llama.cpp (hrx)": "831629fe9a2048f3c6d2fec51acc5c0f8ab60cbb" + "llama.cpp (hrx)": "5514ebea44a9dabffbe5bf265659d0901177a875" }, "counts": { "hrx": 298, diff --git a/third_party/llama.cpp b/third_party/llama.cpp index 831629fe9..5514ebea4 160000 --- a/third_party/llama.cpp +++ b/third_party/llama.cpp @@ -1 +1 @@ -Subproject commit 831629fe9a2048f3c6d2fec51acc5c0f8ab60cbb +Subproject commit 5514ebea44a9dabffbe5bf265659d0901177a875 From cc012c4a3b4e4ec061ba338d1a069888498fc0e2 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 22:01:12 -0400 Subject: [PATCH 002/180] hw-gate: the hrx_build red was a window, not a standing state - close it (#1771) #1737 stated, an hour ago and correctly at the time: "Since 2026-11-09 this job is red on every branch, so a red badge is not a signal". That is no longer true, and a live page saying it sends readers past a badge that works. Measured tonight: gh run list --workflow hrx-build.yml --limit 6 21:00-21:27 8 of 8 failure (five branches: 1bit/{fused-tiles-to-int8, pack-blocked-rowmajor,pack-blocked-extract, i669-tests-gpu-hold-include}, fix/1696-...) 23:32 success 1bit/1740-tail-envelope llama.cpp 60ae4c935 00:21 success bump-hrx/831629fe llama.cpp 831629fe9, hrx-system 7f4236924 00:22 success fix/registry-pin-unmerged llama.cpp 60ae4c935 01:31 success bump-hrx/5514ebea llama.cpp 5514ebea4 The 00:21 run is the one that matters: its pins are EXACTLY main's (`git ls-tree 6b0c820c third_party/` -> llama.cpp 831629fe9, hrx-system 7f4236924), and it passes, four hours after the same pins failed on five branches. So the three errors were not a property of the pins in the tree, whatever the first reading said - and the note must not leave a reader believing main cannot build HRX. The paragraph is now a dated window (21:0x-23:1x), with that evidence in it, ending "read a red badge as meaningful again; if it returns, that run's own log is the evidence, not the earlier window". #1733 itself is untouched - whether the fork has a latent skew that only bites on some runner state is that issue's question, and the answer needs the failing run's checkout, not a doc edit. Second time tonight that the site's own heading guard caught my markdown: a wrapped line beginning "> #1733)." renders as a quoted h1 and the build refused the page ("hw-gate.html has 2

elements"). Reflowed; guard green. Co-authored-by: bong-water-water-bong --- docs/hw-gate.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/hw-gate.md b/docs/hw-gate.md index 59b5ef29f..cf8546713 100644 --- a/docs/hw-gate.md +++ b/docs/hw-gate.md @@ -78,13 +78,13 @@ hrx-system) through `cmake/hrx.cmake`, then links `onebit` with its HRX wiring. add-on (the gate builds that) and does not dispatch anything. Green means the pinned pair builds into the engine. It does not replace the `hw-gate` label on a pin bump. -> **Since 2026-11-09 this job is red on every branch, so a red badge is not a signal** (engine #1733). Three errors sit in -> `third_party/llama.cpp`'s own HRX backend — `ggml-hrx.cpp:517,610,854`: a `void` return tested as `bool`, and two declarations -> that differ only in return type — i.e. the fork's source no longer compiles against the fork's own headers, and the pin-bump -> PR #1681 does not change it (its own `hrx_build` fails at 9m15s while `build` is green). Measured on five unrelated branches -> and on the last eight runs of this workflow, all failures. Until the fork is fixed, read `hrx_build` as **unavailable**, not as -> failing: a red run says nothing about the change under it, and there is no green run left to compare against. It is the same -> shape as #1595 in the opposite direction — a red job nobody can act on stops being a check. +> **Between about 21:0x and 23:1x on 2026-11-09 this job failed on every branch, and a red badge was not a signal** (engine #1733). +> Three errors sat in `third_party/llama.cpp`'s own HRX backend — `ggml-hrx.cpp:517,610,854`: a `void` return tested as +> `bool`, and two declarations that differ only in return type — on every branch measured (five of them), and #1681's pin bump +> failed the same way at 9m15s while its `build` was green. The window is closed: later runs pass, including one whose pins are +> **exactly `main`'s** (`bump-hrx/831629fe`, 00:21, `llama.cpp` `831629fe9` + `hrx-system` `7f4236924`), so the failure was not a +> property of the pins in the tree — which is what the same pins failing four hours earlier had seemed to say. Read a red badge as +> meaningful again; if it returns, that run's own log is the evidence, not the earlier window. ## What it checks From 51b6b547c226c4a5fe87e4c9fb612afeef86ad27 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 22:01:20 -0400 Subject: [PATCH 003/180] npu-pack: measure the 1.9 Token fconst rule for hidden 3072 / 24 heads / 28 layers (Llama-3.2-3B) (#1767) * npu-pack: measure the 1.9 Token fconst rule for hidden 3072 / 24 heads / 28 layers (Llama-3.2-3B) Measured with tools/fconst19_measure.py against amd/Llama-3.2-3B_rai_1.8.0_npu_4K: 1,090 of 1,756,930,368 bytes differ (6.20e-05), i.e. content in a few spots, not layout. The row is worth its own entry rather than a widening of the Phi-3.5 h3072 row, and the measurement is what shows why: same hidden size, same prefix (10,560 = 64 + 2*hidden + 4,352), but the q/k/v bundle is FOUR tiles of 1,740,800 (6,963,200 B) where the Phi/h3072 row is TWO of 5,222,400 -- a different division of the same payload. Head count and layer count differ too (24/28 against 32/32), so this is a distinct geometry on every axis the table keys on. Verified end to end on the pack it was measured from, not just by the tool's line: npu-pack info -> gaps 0 (hidden 3072, 24 heads, 28 layers, IM 8192) npu-pack import -> attention 3584/3584 tiles and MLP 4928/4928 groups survive decode->encode byte for byte, 112 + 84 projections imported, fp32 scale/zero exact for 100.00% of groups, 3.0 GB container The pack's text artifacts are partial (4 of 8: no vocab.json/merges.txt/added_tokens.json/chat_template.jinja), so a serve needs the tokenizer side checked first -- that is a pack property, not this row's. Unlocks amd/Llama-3.2-3B_rai_1.9.0_npu and amd/Llama-3.2-3B-Instruct_rai_1.9.0_npu (same geometry). * npu-pack: the h3072/24/28 row's fraction is 6.20e-07, not 6.20e-05 -- and the tool now prints both spellings CHANGES at 5c4b547, and it is right: 1090 / 1,756,930,368 = 6.204e-07. I had copied the tool's percentage (6.20e-05 %) into the row comment as if it were a fraction, which reads as a 100x larger layout difference -- the opposite of what the row is arguing. Fixed the comment, and fixed the class rather than the instance: tools/fconst19_measure.py now prints the fraction beside the percentage (6.20e-05 % = 6.20e-07 of the file), because this is the second time tonight the same slip landed on a row (#1645 was the first) and that line is what a row is copied from. Everything else the review checked stands: prefix 64 + 2*3072 + 4,352 = 10,560; bundle 4 x 1,740,800 = 6,963,200 B against the Phi/h3072 row's 2 x 5,222,400 = 10,444,800 at the same hidden size; and the triple (3072, 24, 28) occurs once in the table. --------- Co-authored-by: t --- npu/pack_import.cpp | 6 ++++++ tools/fconst19_measure.py | 5 ++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index 19c171787..f415cea4c 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -437,6 +437,12 @@ constexpr Fconst19Rule kFconst19Rules[] = { // all 32 blocks. This is the largest family on #1503 (31 packs). Measured by another lane on main, whose // table is keyed on geometry; merged here in the same form. {4096, 32, 32, 12608, 5, 1, 2297856}, + // Llama-3.2-3B (and -Instruct, same geometry) at hidden 3,072 / 24 heads / 28 layers: measured with + // tools/fconst19_measure.py against amd/Llama-3.2-3B_rai_1.8.0_npu_4K, 1,090 of 1,756,930,368 bytes differ + // (6.20e-07 of the file, which the tool prints as 6.20e-05 %) -- content, not layout. The prefix is the Qwen3 line's 64 + 2*hidden + 4,352 = 10,560 at this hidden + // size, but the bundle is FOUR tiles of 1,740,800 (6,963,200 B) where the Phi/h3072 row has two of 5,222,400 -- + // which is the whole reason a row is measured per geometry and never derived from the hidden size. + {3072, 24, 28, 10560, 4, 1, 1740800}, }; const Fconst19Rule* select_rule_in(const Fconst19Rule* rules, int count, int hidden, int heads, int layers, diff --git a/tools/fconst19_measure.py b/tools/fconst19_measure.py index 80033c91e..386b1b14f 100755 --- a/tools/fconst19_measure.py +++ b/tools/fconst19_measure.py @@ -183,7 +183,10 @@ def main(): differ = 0 if got == a else sum(1 for x, y in zip(got, a) if x != y) if differ <= max(0, int(len(a) * TOL)): prefix, n, tile, rot, header_off, stride9 = p - note = "byte for byte" if differ == 0 else f"{differ} of {len(a)} bytes differ ({100.0 * differ / len(a):.2e} %)" + # Both spellings, because the percent is what this line prints and the fraction is what a row's comment needs: a + # row copied "6.20e-05 %" as "(6.20e-05)" once already and read as a 100x layout difference (engine#1767). + note = ("byte for byte" if differ == 0 else + f"{differ} of {len(a)} bytes differ ({100.0 * differ / len(a):.2e} % = {differ / len(a):.2e} of the file)") if surplus: note += f"; the 1.9 tail carries {surplus} B past its 1.8 twin's, not compared (engine#1740)" if args.json: From a8efe8743996226e8c08e5ae92de1dc88b18e821 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 22:11:51 -0400 Subject: [PATCH 004/180] npu-pack: evict stale canonical .fconst scratch copies; and repair the test whose env #1588 dropped (engine#1770) (#1772) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP: owner 11-09 snapshot - pending work in zc-1770 (3 paths), committed unmodified so the snapshot relays it * tests: npu_repack_path delivers its environment again, so its arms stop testing nothing (#1588) The helper ran every arm as env REPACK_MARKER=... ONEBIT_Q4NX_CACHE=... "$@" \ # --port 0: ... timeout 60 "$dir/1bit" serve ... and a `\` continuation followed by a comment line does not put the comment "in the middle" of the command: the backslash is consumed, the `#` starts a comment at the start of a word, and the command becomes `env VAR=... # ...`. Every assignment is dropped and `timeout 60 ...` runs on the next line as a separate, bare command. #1588 added that comment when it switched the port to `0`; before it the continuation went straight to `timeout`, which is why the test passed when it landed in #543 and has failed since. Consequence on main: the two arms that name behaviour were red on every run — the packaged `scripts/repack_gguf.py` precedence and the `ONEBIT_Q4NX_REPACK` override — while the arms that only grep 1bit's own message passed, because with no script and no override the not-found path is exactly what a bare binary takes anyway. The test's own log line carried the proof and nobody read it: it printed `(exit SHELL=/bin/bash` and a screen of environment variables, because `$rc` held the output of `env` with no command to run. Fixed by hoisting the comment above the command, and the reason is in the comment so the next edit to this helper does not put it back. Before (two arms fail, and the third arm's detail is `env`'s own dump): FAIL a package's scripts/repack_gguf.py beside 1bit is the one that runs ok (the run stops at the stand-in: exit 1, GGUF repack failed) FAIL ONEBIT_Q4NX_REPACK overrides the path ok with no script anywhere, serve says so (exit SHELL=/bin/bash ok and it did not claim a build-machine path exists After (5/5, and the third arm now reports its real exit code): ok a package's scripts/repack_gguf.py beside 1bit is the one that runs ok (the run stops at the stand-in: exit 1, GGUF repack failed) ok ONEBIT_Q4NX_REPACK overrides the path ok with no script anywhere, serve says so (exit 1) ok and it did not claim a build-machine path exists The implementation is untouched: `packaged_path()` already tried `here/scripts/repack_gguf.py` before the build-tree fallback, so the arm's layout was right and only the delivery was broken. Test-only change. Refs #1770 (found while running the suite for it). --------- Co-authored-by: bong-water-water-bong Co-authored-by: t --- npu/pack_import.cpp | 31 ++++++++++++++++++--- npu/pack_import.h | 7 +++++ tests/npu_pack_import_test.cpp | 51 +++++++++++++++++++++++++++++++++- tests/npu_repack_path.sh | 7 +++-- 4 files changed, 89 insertions(+), 7 deletions(-) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index f415cea4c..7957167d5 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -694,10 +694,11 @@ std::string materialise_token_fconst(const std::string& pack_dir, const Dims& di // canonical form (a new kFconst19Rules entry, a different tile order) leaves the source file untouched, so source // identity alone would keep serving a copy of the old form. Bump this when the canonical form changes. constexpr int kCanonicalFormVersion = 1; - const std::string name = "1bit-fconst19v" + std::to_string(kCanonicalFormVersion) + "-" + tag + "-" + - std::to_string(dims.hidden) + "-" + - std::to_string(dims.heads) + "-" + std::to_string(dims.layers) + "-" + - std::to_string(src_ec ? std::uintmax_t(0) : src_size) + "-" + + // Everything but the source identity: the group this run evicts its stale siblings from (engine#1770). + const std::string ident_prefix = "1bit-fconst19v" + std::to_string(kCanonicalFormVersion) + "-" + tag + "-" + + std::to_string(dims.hidden) + "-" + std::to_string(dims.heads) + "-" + + std::to_string(dims.layers) + "-"; + const std::string name = ident_prefix + std::to_string(src_ec ? std::uintmax_t(0) : src_size) + "-" + std::to_string(static_cast(src_stamp)) + ".fconst"; // `temp_directory_path()` THROWS when TMPDIR names a directory that no longer exists, which is the ordinary state of // a shell after a reboot has cleared /tmp -- and it threw before any work was attempted, so `npu-pack info` on a @@ -724,6 +725,9 @@ std::string materialise_token_fconst(const std::string& pack_dir, const Dims& di if (!probe) continue; probe.close(); work = cand.string(); + // This is the copy that will be written, so the copies of the same pack and geometry at other sizes/mtimes are + // the ones nothing will reuse (engine#1770). + evict_stale_canonical_copies(d.string(), name, ident_prefix); // Say where it went whenever that is not the ordinary place: the copy is a few hundred MB and it is scratch. std::error_code ec2; const fs::path tmpdir = [&] { try { return fs::temp_directory_path(); } catch (...) { return fs::path(); } }(); @@ -4273,4 +4277,23 @@ bool canonical_copy_reusable(const std::string& work, int64_t expected_len) { return !ec && have == static_cast(expected_len); } +// engine#1770: reuse (engine#1662) writes a NEW copy when the source changes instead of overwriting, so copies only ever +// accumulate -- 699 files and 8.7 GiB of tmpfs (i.e. RAM) on this box, most of them truncated 0-byte tails. The identity +// in the name is `1bit-fconst19v------.fconst`, so keeping +// one copy per (pack, geometry) means removing the entries that share the prefix but not the whole name. That cannot take +// a copy a reader is about to use: reuse requires the entire name to match, and the one name that can match is the one +// being kept. A reader holding a removed file open is unaffected (the inode outlives the unlink); at worst a concurrent +// lane rewrites a copy it would have reused, which costs a file write and no correctness. +void evict_stale_canonical_copies(const std::string& dir, const std::string& keep_name, const std::string& prefix) { + if (dir.empty() || keep_name.empty() || prefix.empty() || keep_name.size() <= prefix.size()) return; + std::error_code ec; + for (fs::directory_iterator it(fs::path(dir), ec), end; !ec && it != end; it.increment(ec)) { + const std::string base = it->path().filename().string(); + if (base == keep_name || base.size() <= prefix.size()) continue; + if (base.compare(0, prefix.size(), prefix) != 0) continue; + std::error_code rm; + fs::remove(it->path(), rm); + } +} + } // namespace onebit::npu::pack_import diff --git a/npu/pack_import.h b/npu/pack_import.h index 1a4f96da4..4bfbd0c51 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -177,6 +177,13 @@ Plan plan(const std::string& pack_dir); // and a directory on the scratch path must all come back false. bool canonical_copy_reusable(const std::string& work, int64_t expected_len); +// Removes the canonical Token .fconst copies in `dir` that share `prefix` -- one pack path and geometry -- but are not +// `keep_name` (engine#1770). Reuse writes a new copy when the source changes rather than overwriting, so without this the +// scratch directory grows one multi-hundred-MB file per change; on this box 699 files / 8.7 GiB of tmpfs. Exposed for the +// same reason as canonical_copy_reusable(): the rule it applies is what can be wrong, and a test can prove it on a +// directory of empty files with no pack at all. +void evict_stale_canonical_copies(const std::string& dir, const std::string& keep_name, const std::string& prefix); + // The text artifacts a runnable container needs beside model.q4nx, and which of them the pack // actually carries. A pack fetched weight by weight can be weights-only (engine#1024; AMD's repos // do publish the text, and how much of it varies per pack), and an importer that says nothing about diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index a639cc241..fa21f8686 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -627,6 +627,55 @@ void test_canonical_copy_reusable() { std::printf(" canonical copy reuse: 7 arms (complete/truncated/long/absent/directory/zero-length/empty)\n"); } +// engine#1770: the canonical copy is scratch that used to only ever accumulate -- reuse writes a new file when the source +// changes, so 699 files / 8.7 GiB of tmpfs (RAM) had built up on one box. The eviction rule is "same pack and geometry, +// different source identity", and what can go wrong is deleting one of the neighbours that must survive, so each is an arm. +void test_evict_stale_canonical_copies() { + const fs::path dir = fs::temp_directory_path() / ("1bit-evict-" + std::to_string(::getpid())); + std::error_code ec; + fs::remove_all(dir, ec); + fs::create_directories(dir); + auto touch = [&](const std::string& base) { + std::ofstream o(dir / base, std::ios::binary | std::ios::trunc); + o << 'x'; + }; + const std::string keep = "1bit-fconst19v1-12345-896-14-24-291653952-76263210.fconst"; + const std::string prefix = "1bit-fconst19v1-12345-896-14-24-"; + const std::string stale = "1bit-fconst19v1-12345-896-14-24-291653952-99999.fconst"; // same pack+geometry, new mtime + const std::string stale_size = "1bit-fconst19v1-12345-896-14-24-300000000-76263210.fconst"; // repacked source + const std::string other_geometry = "1bit-fconst19v1-12345-1536-12-28-995712640-73345656.fconst"; + const std::string other_pack = "1bit-fconst19v1-99999-896-14-24-291653952-76263210.fconst"; + const std::string other_form = "1bit-fconst19v2-12345-896-14-24-291653952-76263210.fconst"; + const std::string unrelated = "notes.txt"; + // The split must not change the NAME, or every run rewrites a copy it already had (a ~1 GB rewrite, silently). The + // legacy formula concatenated these fields directly; the fix only cuts the string at the size field. + check(keep == prefix + "291653952-76263210.fconst", + "evict: prefix + source identity is the name the reuse path looks for, unchanged"); + for (const auto& f : {keep, stale, stale_size, other_geometry, other_pack, other_form, unrelated}) touch(f); + + pi::evict_stale_canonical_copies(dir.string(), keep, prefix); + + auto exists = [&](const std::string& base) { return fs::exists(dir / base, ec); }; + check(exists(keep), "evict: the copy being written is kept"); + check(!exists(stale), "evict: a copy of the same pack and geometry at another mtime goes (the accumulation)"); + check(!exists(stale_size), "evict: a repacked source's copy goes (different size, same pack and geometry)"); + check(exists(other_geometry), "evict: another geometry of the same pack is kept -- it is not this run's to remove"); + check(exists(other_pack), "evict: another pack with the same geometry is kept"); + check(exists(other_form), "evict: another canonical form version is kept"); + check(exists(unrelated), "evict: unrelated files in the directory are kept"); + + // The degenerate arguments must not turn into "delete the directory". + for (const auto& f : {keep, stale}) touch(f); + pi::evict_stale_canonical_copies(dir.string(), "", prefix); + check(exists(keep) && exists(stale), "evict: an empty keep-name removes nothing"); + pi::evict_stale_canonical_copies(dir.string(), keep, ""); + check(exists(keep) && exists(stale), "evict: an empty prefix removes nothing"); + pi::evict_stale_canonical_copies((dir / "absent").string(), keep, prefix); + check(exists(keep), "evict: an absent directory is not an error"); + fs::remove_all(dir, ec); + std::printf(" canonical copy eviction: 12 arms (name composition + keep/stale/geometry/pack/form/unrelated + 3 degenerate)\n"); +} + void test_modelbin_genre_refusal(const std::string& root) { const fs::path dir = fs::path(root) / "crafted-modelbin"; fs::remove_all(dir); @@ -2926,7 +2975,7 @@ int main(int argc, char** argv) { test_external_roles(); test_external_container_names(); test_external_packed_genre(golden_dir.empty() ? "." : golden_dir); - test_canonical_copy_reusable(); + test_canonical_copy_reusable(); test_evict_stale_canonical_copies(); test_crafted_refusals(golden_dir.empty() ? "." : golden_dir); test_modelbin_genre_refusal(golden_dir.empty() ? "." : golden_dir); test_1671_plan_head_arm(golden_dir.empty() ? "." : golden_dir); diff --git a/tests/npu_repack_path.sh b/tests/npu_repack_path.sh index 360c3f89b..323eef5cd 100755 --- a/tests/npu_repack_path.sh +++ b/tests/npu_repack_path.sh @@ -61,9 +61,12 @@ serve_npu() { # from a directory with no ../src beside it: a build tree's baked fallback is relative, and a # caller's working directory must not decide whether the script is found local cwd=$scratch/cwd; mkdir -p "$cwd" + # --port 0: nothing here calls the server, so no port is needed at all - it just must not be one that was + # picked and released before serve binds it (engine #1444/#1485). + # The comment must stay ABOVE this command: a `\` continuation followed by a comment line turns the command into + # `env VAR=... # ...`, which drops every assignment, so each arm below ran a bare `1bit` with none of its env + # (the markers were never written and this test failed on main from the day it landed). ( cd "$cwd" && env REPACK_MARKER="$marker" ONEBIT_Q4NX_CACHE="$scratch/cache" "$@" \ - # --port 0: nothing here calls the server, so no port is needed at all - it just must not be one that was - # picked and released before serve binds it (engine #1444/#1485) timeout 60 "$dir/1bit" serve -m "$scratch/m.gguf" --device npu --port 0 > "$scratch/out.log" 2>&1 ) echo $? } From 482a7f7f138a2b11ccfb74f238df9110b1a11a9f Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 22:53:26 -0400 Subject: [PATCH 005/180] docs/hw-gate: the hrx_build red was the pin, and the pins show it (corrects #1771) (#1776) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #1771 retracted the "read hrx_build as unavailable" instruction, which was right, but its closing clause says the failure "was not a property of the pins in the tree — which is what the same pins failing four hours earlier had seemed to say". The pins are not the same, and the gitlinks come from the runs themselves: red, 21:06 run 42699357566 (fix/1696) hrx-system 7f4236924 llama.cpp 8f124f906 -> failure green, 00:21 run 42727646749 (bump-hrx/831629f) hrx-system 7f4236924 llama.cpp 831629fe9 -> success hrx-system matches; llama.cpp does not. And 8f124f906 is exactly the pin #1733 root-caused (ggml-hrx.cpp declares device_free_total twice: void from #252's forward declaration at :383, bool from #240's 800 lines later), which #1759 replaced. As merged, the paragraph teaches the opposite lesson: "a window, not the pins" instead of "this pin was broken, a bump fixed it, and a llama.cpp bump must clear hrx_build before it lands" — the rule the hw-gate label exists for, and what #1768 did before merging (hrx_build pass 1m10s). Docs only. --- docs/hw-gate.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/hw-gate.md b/docs/hw-gate.md index cf8546713..27c75c256 100644 --- a/docs/hw-gate.md +++ b/docs/hw-gate.md @@ -81,10 +81,21 @@ hrx-system) through `cmake/hrx.cmake`, then links `onebit` with its HRX wiring. > **Between about 21:0x and 23:1x on 2026-11-09 this job failed on every branch, and a red badge was not a signal** (engine #1733). > Three errors sat in `third_party/llama.cpp`'s own HRX backend — `ggml-hrx.cpp:517,610,854`: a `void` return tested as > `bool`, and two declarations that differ only in return type — on every branch measured (five of them), and #1681's pin bump -> failed the same way at 9m15s while its `build` was green. The window is closed: later runs pass, including one whose pins are -> **exactly `main`'s** (`bump-hrx/831629fe`, 00:21, `llama.cpp` `831629fe9` + `hrx-system` `7f4236924`), so the failure was not a -> property of the pins in the tree — which is what the same pins failing four hours earlier had seemed to say. Read a red badge as -> meaningful again; if it returns, that run's own log is the evidence, not the earlier window. +> failed the same way at 9m15s while its `build` was green. It was a property of the pin, and the pins say so: +> +> | | `hrx-system` | `llama.cpp` | result | +> |---|---|---|---| +> | red window, 21:06 (`fix/1696`, run 42699357566) | `7f4236924` | **`8f124f906`** | failure | +> | green, 00:21 (`bump-hrx/831629fe`, run 42727646749) | `7f4236924` | **`831629fe9`** | success | +> +> `hrx-system` is the same on both and `llama.cpp` is not. At `8f124f906`, `ggml-hrx.cpp` declares `device_free_total` +> twice — `void` from #252's forward declaration at `:383`, `bool` from #240's eight hundred lines later — so the +> translation unit cannot compile; #1759 replaced that pin with `831629fe` and the job has been green since. The window +> closed because the pin moved, not because the failure was transient. +> +> So read a red badge as meaningful, and treat a `llama.cpp` bump whose run leaves `hrx_build` red as a bump that has not +> landed — which is what the `hw-gate` label is for, and what #1768 did before merging (`hrx_build` pass, 1m10s). If a red +> run ever returns without the pin changing, that run's own log is the evidence. ## What it checks From e65f2cd0cda8d29313b2e5b2128dab8576583a6d Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:03:52 -0400 Subject: [PATCH 006/180] npu-pack: read a THREE-input MatMulNBits, whose implicit zero point is 2^(bits-1) (engine#1503) (#1790) Qwen3-VL-4B spells its projections as three-input nodes with no qzeros tensor and names them `.MatMul.weight_Q4` next to `.MatMul.weight_scales`: MatMulNBits inputs = (activations, ...attn.q_proj.MatMul.weight_Q4, ...attn.q_proj.MatMul.weight_scales) attrs = K 2560, N 4096, bits 4, block_size 32 weight_Q4 [4096, 80, 16] UINT8 N x (K/32) x 16 B (32 quants, 2 per byte) weight_scales [4096, 80] FLOAT one f32 scale per (row, 32-column block) `walk_graph` required `ins.size() >= 4`, so it recorded **no matmuls at all** for that pack: `npu-pack info` printed `matmulnbits_ops 0`, `plan()` fell through to "the graph carries no weights", and the import wrote the embedding and nothing else -- measured on the real pack as `imported 1 tensors, 0 q4_1 tiles`. Three changes, and the third is the one that decides correctness: 1. accept three inputs (data, weight, scales) and take `zeros` only when the node has it; 2. resolve both spellings -- `.MatMulNBits.qweight` (the 1.8/phi-4 form) and `.MatMul.weight_Q4` -- in the projection census and in the weight/scales lookup; 3. a node with **no qzeros** takes the implicit zero point `2^(bits-1)`, applied by `implicit_zp_zero()` after the decode. That is ONNX Runtime's own MatMulNBits rule when `qzeros` is absent, and it is corroborated inside this collection: the *embedding* component of the same family (GatherBlockQuantized, also no zeros) decodes to ORT's output at cosine 1.00000000 / max|d| 0 at zero point 8, against 0.317 at zero point 0 (engine#1725). **Measured on the real pack** (`amd/Qwen3-VL-4B-Instruct_rai_1.9.0_npu`, 2.9 GB, on disk under `~/scratch-packs`): imported 147 tensors, 47480 q4_1 tiles into ~/scratch-packs/qwen3vl4b.q4nx self-check: the head reproduces the pack's own embedding (as imported, bf16) corr 0.993981 rel_err 0.092550 controls: nibble-swapped corr -0.0699, no zero-point corr 0.3333 (both must fail) parameters: fp32 scale/zero exact for 100.00% of 32-column groups The head is tied to the embedding after all, so the pack's own reference grades the decode -- at 0.993981, with the nibble-swap control failing as it must and the **no-zero-point control at 0.3333**, which is the direct measurement that the implicit 2^(bits-1) is the right convention for this family. Test: a crafted three-input node with `[N, K/32, 16]` u8 + `[N, K/32]` f32 asserts that the walker records it (1 of 1), counts it as carrying no qzeros, and takes K/N/block from the node's attributes -- 3-input MatMulNBits: 1 matmul(s), 1 without qzeros, K 64 N 32 block 32 all npu-pack checks passed Not in this PR: the RoPE question. The same pack ships `cos_cache`/`sin_cache` that no plain theta reproduces (best 0.5918 at 3.2e6 against a declared 10000) while the forward computes RoPE from theta -- its own issue, not a reader symptom. Co-authored-by: pi-npufeat --- npu/pack_import.cpp | 59 ++++++++++++++++++++++++++++++---- npu/pack_import.h | 5 +++ tests/npu_pack_import_test.cpp | 35 ++++++++++++++++++++ 3 files changed, 93 insertions(+), 6 deletions(-) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index 7957167d5..dfef45831 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -200,11 +200,16 @@ void walk_graph(const uint8_t* p, size_t n, OnnxModel& m) { if (op == "MatMulNBits" || op == "MatMulNBitsBf") { if (op == "MatMulNBitsBf") ++m.ryzenai_matmuls; OnnxMatMul mm; - if (ins.size() >= 4) { + // THREE inputs is a real spelling, not a truncation: `amd/Qwen3-VL-4B-Instruct_rai_1.9.0_npu` names its + // projections `(activations, ...MatMul.weight_Q4, ...MatMul.weight_scales)` with `bits 4, block_size 32` and + // no qzeros tensor at all, and a `>= 4` test therefore recorded NO matmuls for it -- `info` printed + // matmulnbits_ops 0 and the importer wrote only the embedding (engine#1503). A missing qzeros means the + // implicit zero point, which `implicit_zp_zero()` below applies. + if (ins.size() >= 3) { mm.data = ins[0]; mm.weight = ins[1]; mm.scales = ins[2]; - mm.zeros = ins[3]; + if (ins.size() >= 4) mm.zeros = ins[3]; } if (attrs.count("K")) mm.K = attrs["K"]; if (attrs.count("N")) mm.N = attrs["N"]; @@ -1255,6 +1260,21 @@ Dims read_dims(const json& c, const std::string& source = "config.json") { // engine#1650: exported so the config reader can be tested on a pack that declares an optional // field as null, without a pack and without the vendor stack. Dims read_dims_exported(const json& c, const std::string& source) { return read_dims(c, source); } +int parse_onnx_matmul_census(const std::string& path, int* matmuls, int* without_zeros, int* K, int* N, int* block) { + const OnnxModel m = parse_onnx(path); + if (matmuls) *matmuls = int(m.matmuls.size()); + if (without_zeros) { + int n = 0; + for (const auto& mm : m.matmuls) if (mm.zeros.empty()) ++n; + *without_zeros = n; + } + if (!m.matmuls.empty()) { + if (K) *K = int(m.matmuls[0].K); + if (N) *N = int(m.matmuls[0].N); + if (block) *block = m.matmuls[0].block; + } + return int(m.matmuls.size()); +} // The 1.9 external-data genre states no FFN width anywhere a file shows it: the weights are MatMulNBitsBf nodes // whose initializers carry dims `[0]` (bytes live in a *.qweight.packed sibling), so the initializer-dimension // heuristic in plan() sees nothing. The NODE carries K and N as attributes, and walk_graph already descends into @@ -1396,6 +1416,19 @@ FconstGeom locate_fconst(const std::string& path, unsigned short eps_bits) { } +// ── The implicit zero point ─────────────────────────────────────────────────── +// A quantised matmul with no `qzeros` input takes an implicit zero point of 2^(bits-1) -- ONNX Runtime's own +// MatMulNBits does exactly that when the tensor is absent, and it is corroborated in this collection: the *embedding* +// component of the same family (GatherBlockQuantized, also no zeros) decodes to ONNX Runtime's output with cosine +// 1.00000000 and max|d| 0 at zero point 8, against 0.317 at zero point 0 (measured on +// amd/Qwen3-VL-4B-Instruct_rai_1.9.0_npu, engine#1725/#1661). `decode_matmulnbits` folds the zero into `q.zero`, so +// this subtracts the implicit one the same way: zero term = -(2^(bits-1)) * scale. +void implicit_zp_zero(Q4& q, int bits) { + if (bits <= 0 || q.scale.empty() || q.scale.size() != q.zero.size()) return; + const float zp = float(1 << (bits - 1)); + for (size_t i = 0; i < q.zero.size(); ++i) q.zero[i] -= zp * q.scale[i]; +} + // ── MatMulNBits → (codes, scale, zero) per 32-column group ─────────────────── Q4 decode_matmulnbits(const uint8_t* qweight, const float* scales, const uint8_t* zeros, int N, int K, int block, bool swap_nibbles, bool drop_zero) { @@ -2145,9 +2178,14 @@ Plan plan(const std::string& pack_dir) { std::set graph_projs; if (graph_weights) { for (const auto& t : onnx.tensors) { - const size_t pos = t.name.find(".MatMulNBits."); - if (pos == std::string::npos || t.dims.empty()) continue; // 0-dim placeholders sit beside them - graph_projs.insert(t.name.substr(0, pos)); + if (t.dims.empty()) continue; // 0-dim placeholders sit beside them + // Two spellings of the same thing: `.MatMulNBits.qweight` (the 1.8/phi-4 form) and + // `.MatMul.weight_Q4` (Qwen3-VL-4B's, three-input nodes, engine#1503). + size_t pos = t.name.find(".MatMulNBits."); + if (pos != std::string::npos) { graph_projs.insert(t.name.substr(0, pos)); continue; } + const std::string q4 = ".MatMul.weight_Q4"; + pos = t.name.find(q4); + if (pos != std::string::npos) graph_projs.insert(t.name.substr(0, pos)); } } const OnnxTensor* embed = nullptr; @@ -3170,8 +3208,15 @@ Report import_pack(const std::string& pack_dir, const std::string& out_dir, cons // Decode rows [row0, row0+rows) of a projection's MatMulNBits weight into q4_1 tiles. auto decode_rows = [&](const std::string& proj, int row0, int rows, const std::string& out_name, int k_override) -> bool { + // The two spellings of a quantised projection (engine#1503): the 1.8/phi-4 form carries a qweight and a + // scales sibling; Qwen3-VL-4B names them `.MatMul.weight_Q4` / `.MatMul.weight_scales` on a + // three-input node with no qzeros (implicit zero point, applied below). const OnnxTensor* qw = init_of(proj + ".MatMulNBits.qweight"); const OnnxTensor* sc = init_of(proj + ".MatMulNBits.scales"); + if (!qw || !sc) { + qw = init_of(proj + "MatMul.weight_Q4"); + sc = init_of(proj + "MatMul.weight_scales"); + } if (!qw || !sc || qw->dims.size() != 3 || sc->dims.empty()) return false; const int N = int(qw->dims[0]); const int block = int(qw->dims[2]) * 2; // 64 B holds 128 four-bit codes @@ -3321,7 +3366,9 @@ Report import_pack(const std::string& pack_dir, const std::string& out_dir, cons const uint8_t* zp = have_zp ? bytes_of(onnx.tensors[zi->second], zp_need) : nullptr; uint64_t qw_need = 0; // N * K/block * block/2 if (!mul_ok(groups_n, uint64_t(mm.block) / 2, qw_need)) throw std::runtime_error("lm_head: qweight length overflows"); - const Q4 q = decode_matmulnbits(bytes_of(wt, qw_need), scales.data(), zp, int(mm.N), int(mm.K), mm.block); + Q4 q = decode_matmulnbits(bytes_of(wt, qw_need), scales.data(), zp, int(mm.N), int(mm.K), mm.block); + // no qzeros tensor -> the implicit zero point (engine#1503: Qwen3-VL-4B's spelling, three-input nodes) + if (!have_zp) implicit_zp_zero(q, mm.bits); std::vector tiled; long long pinexact = 0; diff --git a/npu/pack_import.h b/npu/pack_import.h index 4bfbd0c51..b4ad5821d 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -403,6 +403,11 @@ unsigned short bf16_bits_of(float v); // the default rather than throw. Exported so tests/npu_pack_import_test.cpp can pin it without a // pack; `source` names where the geometry came from, for the refusal messages. Dims read_dims_exported(const nlohmann::json& c, const std::string& source); +// engine#1503: what the graph walker RECORDED, without exposing its model type. A three-input MatMulNBits (no qzeros, +// weights spelled `.MatMul.weight_Q4`) used to be dropped entirely, which is why Qwen3-VL-4B imported one tensor. +// Returns the matmul count; `without_zeros` counts those that carry no qzeros tensor (the implicit-zero-point case), and +// the last three report the first matmul's own K/N/block attributes. +int parse_onnx_matmul_census(const std::string& path, int* matmuls, int* without_zeros, int* K, int* N, int* block); // engine#1638: the geometry as read, so a test can check WHICH source a number came from. nlohmann::json load_geometry_exported(const std::string& pack_dir, std::string* source); FconstGeom locate_fconst(const std::string& path, unsigned short eps_bits = 0x3586); diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index fa21f8686..698b336dc 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -2224,6 +2224,40 @@ void test_text_config_geometry(const std::string& root) { fs::remove_all(dir); } + +// engine#1503: a THREE-input MatMulNBits with no qzeros, weights spelled `.MatMul.weight_Q4` + +// `.weight_scales` -- Qwen3-VL-4B's form. `walk_graph` used to require four inputs, so it recorded NO matmuls for that +// pack: `info` printed matmulnbits_ops 0 and the import wrote the embedding only ("imported 1 tensors, 0 q4_1 tiles"). +// On the real pack the fix yields 147 tensors / 47,480 tiles and the pack's own self-check reads corr 0.993981 against its +// embedding, with the no-zero-point control at 0.3333 -- this arm pins the mechanism without the 3 GB pack. +void test_three_input_matmulnbits(const std::string& root) { + const fs::path dir = fs::path(root) / "mm3"; + fs::remove_all(dir); + fs::create_directories(dir); + const int64_t H = 64, N = 32, block = 32, groups = H / block; + std::vector qw(size_t(N) * size_t(groups) * size_t(block / 2), 0x21); // codes 1/2 alternating + std::vector sc(size_t(N) * size_t(groups), 0.01f); + std::string data(reinterpret_cast(qw.data()), qw.size()); + data.append(reinterpret_cast(sc.data()), sc.size() * sizeof(float)); + put_file((dir / "model.onnx.data").string(), data); + const auto q4 = pb::tensor("model.layers.0.attn.q_proj.MatMul.weight_Q4", {N, groups, block / 2}, + "model.onnx.data", 0, qw.size(), 2); + const auto scl = pb::tensor("model.layers.0.attn.q_proj.MatMul.weight_scales", {N, groups}, + "model.onnx.data", qw.size(), sc.size() * sizeof(float), 1); + const auto node = pb::matmulnbits("q", {"x", "model.layers.0.attn.q_proj.MatMul.weight_Q4", + "model.layers.0.attn.q_proj.MatMul.weight_scales"}, H, N, 4, block); + put_file((dir / "model.onnx").string(), pb::model({q4, scl}, {node})); + int mm = -1, noz = -1, K = 0, Nn = 0, blk = 0; + pi::parse_onnx_matmul_census((dir / "model.onnx").string(), &mm, &noz, &K, &Nn, &blk); + check(mm == 1, "3-input MatMulNBits: the walker records the node (" + std::to_string(mm) + " of 1)"); + check(noz == 1, "3-input MatMulNBits: it is counted as carrying no qzeros, so the implicit zero point applies"); + check(K == H && Nn == N && blk == block, + "3-input MatMulNBits: K/N/block come from the node's own attributes (" + std::to_string(K) + "/" + + std::to_string(Nn) + "/" + std::to_string(blk) + ")"); + std::printf(" 3-input MatMulNBits: %d matmul(s), %d without qzeros, K %d N %d block %d\n", mm, noz, K, Nn, blk); + fs::remove_all(dir); +} + void test_embedding_component(const std::string& root) { const fs::path dir = fs::path(root) / "embedcomp"; fs::remove_all(dir); @@ -2988,6 +3022,7 @@ int main(int argc, char** argv) { test_attn_payload_off(); test_text_config_geometry(golden_dir.empty() ? "." : golden_dir); test_hybrid_pack_import(golden_dir.empty() ? "." : golden_dir); + test_three_input_matmulnbits(golden_dir.empty() ? "." : golden_dir); test_embedding_component(golden_dir.empty() ? "." : golden_dir); test_fconst19_rule_table(); test_selfcheck_reads_bf16(); From 4f60316bfa7afab1bb044b16c7cbd8879bc3ea99 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:03:58 -0400 Subject: [PATCH 007/180] tools: place the tail grid before the padding, so a padded pack is not read as if it were the head (#1789) engine#1740/#1773: the tail is [envelope][rows x tile][PADDING], and 12+ of the 42 1.9 packs end in a multi-hundred-MB all-zero run (110,208,000 B on the hidden-1536 family). This tool computed the head as 'fconst_bytes - ntiles*tile', i.e. the no-padding assumption, so on those packs it read the padding and reported corr ~ 0 -- which is the *symptom* engine#1693 started from, reproduced on a pack where nothing is wrong. That is the one failure mode a measurement tool must not have: a plausible negative. trailing_zeros() already existed here and was only *reported*; it now also places the grid (head_offset(fconst_bytes, ntiles, tile, zeros)), so the count decides where the head ends and the padding is not decoded at all. The docstring says plainly that this is the zero-run-implied candidate and not a proof of placement -- the printed correlation is what decides -- and points at the importer's plan_tail_head(), which walks the neighbouring tile-aligned candidates for the cases where the head does not end exactly at the run. The test that pinned the old behaviour is rewritten rather than deleted: it built a padded synthetic pack and asserted the read came out non-finite ('a read shifted by them is visible'). It now asserts the opposite contract -- the grid is placed before the padding, so a padded pack decodes finitely -- and the two new arithmetic checks pin zeros=0 unchanged and zeros>0 shifting by exactly its length. Verified on the real pack (no padding, zeros=0): corr +1.0000, rel_err 0.0007, unchanged. 16/16 checks. refs #1740 Co-authored-by: bong-water-water-bong --- tests/q4nx_tail_head_test.py | 15 ++++++++++----- tools/q4nx_tail_head.py | 12 +++++++++--- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/tests/q4nx_tail_head_test.py b/tests/q4nx_tail_head_test.py index eaf22b4d0..787c5bd58 100755 --- a/tests/q4nx_tail_head_test.py +++ b/tests/q4nx_tail_head_test.py @@ -179,16 +179,17 @@ def synthetic(): check(all(r["finite"] == 1.0 for r in out["tiles_measured"]) and len(out["tiles_measured"]) == 2, "and its decode is reported as finite on both tiles") - # the end-anchored offset on a file that ends in padding (the 1.5B pack's .fconst ends in 110 MB of zeros): - # the count is reported, and the shifted read shows up as a non-finite decode instead of a quiet number + # a file that ends in padding (the 1.5B packs' .fconst ends in 110 MB of zeros): the count is reported AND used + # to place the grid. It used to be reported only, so the read landed inside the padding and came out non-finite -- + # the symptom engine#1693 started from, on a pack where nothing is wrong (engine#1740) pz = os.path.join(work, "padded") make_pack(pz, tied=False, head_block=T.K_KBLOCK, zeros=4096) out, status, _ = T.measure(pz, 2) check(out["geometry"]["trailing_zero_bytes"] == 4096, "trailing zero bytes are counted (%d)" % out["geometry"]["trailing_zero_bytes"]) - check(min(r["finite"] for r in out["tiles_measured"]) < 1.0, - "and a read shifted by them is visible as a non-finite decode (min finite %.3f)" - % min(r["finite"] for r in out["tiles_measured"])) + check(min(r["finite"] for r in out["tiles_measured"]) == 1.0, + "and the grid is placed BEFORE them, so a padded pack decodes finitely instead of reading its own padding " + "(min finite %.3f)" % min(r["finite"] for r in out["tiles_measured"])) # --ref as the oracle: the decode itself, written as f32 rows, must correlate 1.0 with itself with open(T.fconst(pu), "rb") as f: @@ -245,6 +246,10 @@ def main(): check(T.head_offset(291655296, 2374, 34816) + 2374 * 34816 == 291655296, "the head grid ends exactly at EOF") check(T.head_offset(291655296, 2374, 34816) != T.attn_payload_off(896), "attn_payload_off(H) alone is not the head's offset -- the mistake engine#1693 records") + check(T.head_offset(291655296, 2374, 34816, 0) == T.head_offset(291655296, 2374, 34816), + "no padding leaves the offset unchanged (the case engine#1693 measured)") + check(T.head_offset(291655296, 2374, 34816, 110208000) == T.head_offset(291655296, 2374, 34816) - 110208000, + "a trailing zero run moves the grid back by exactly its length (engine#1740's padded packs)") check(T.head_offset(291655296, 2374, 34816) == 209000256 + T.attn_payload_off(896), "it equals the importer's layers*stride + env (209000256 is this pack's 24 layer blocks)") diff --git a/tools/q4nx_tail_head.py b/tools/q4nx_tail_head.py index 16fd1b354..56bdeea7a 100755 --- a/tools/q4nx_tail_head.py +++ b/tools/q4nx_tail_head.py @@ -97,7 +97,7 @@ def attn_payload_off(hidden): return K_NORM_OFF + hidden * 2 -def head_offset(fconst_bytes, ntiles, tile): +def head_offset(fconst_bytes, ntiles, tile, zeros=0): """Where the tied head's grid starts: the last `ntiles * tile` bytes of the `.fconst`. The importer derives the same number as `layers * stride + attn_payload_off(H)` -- past the per-layer payload, then @@ -114,7 +114,13 @@ def head_offset(fconst_bytes, ntiles, tile): correlates 1.0000 with the pack's own fp16 embedding, magnitude ratio 1.000, rel_err 0.0007 over four tiles on `Qwen2.5-0.5B-Instruct_rai_1.9.0_npu`. """ - return fconst_bytes - ntiles * tile + # engine#1740: the tail is [envelope][rows x tile][PADDING], and 12+ of the 42 1.9 packs end in a multi-hundred-MB + # all-zero run (110,208,000 B on the hidden-1536 family). Subtracting only the grid lands *inside that padding* and + # reports corr ~ 0 with a zero variance -- the symptom engine#1693 started from, on a pack where nothing is wrong. + # So the grid ends where the zero run begins; `zeros` is measured, not assumed. This is the zero-run-implied candidate + # and not a proof of placement (the head need not end exactly there): the printed correlation is what decides, and the + # importer's `plan_tail_head()` walks the neighbouring tile-aligned candidates for the cases where it does not. + return fconst_bytes - zeros - ntiles * tile def bf16_to_f32(codes): @@ -311,8 +317,8 @@ def measure(pack, tiles_wanted, ref_path=None, ref_dtype="bf16"): # WHERE the head is: the LAST `ntiles * tile` bytes. `env` on its own is only the tail's envelope -- the importer # reaches the head as `layers*stride + env`, which equals this subtraction whenever its size check passes # (engine#1693: at `env` the decode correlates at chance, at the real offset 1.0000). - base = head_offset(size, ntiles, tile) zeros = trailing_zeros(path) + base = head_offset(size, ntiles, tile, zeros) rows = [] status = 0 if base >= 0 else 3 if base >= 0 and oracle is None: From d805b9051937078675b0ebd4b51fa7f462230a78 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:14:16 -0400 Subject: [PATCH 008/180] npu: read the token embedding table in place, one row per token, instead of materialising it (engine#1784) (#1795) The container is already mapped read-only (`Model::Model` -> `map_file()`, and every `Tensor::data` points into that mapping), so the token embedding table was being **copied out of a mapping we already had**: bf16 tables via `memcpy` of the whole `NV*H` table, and plain int8 tables via `q4nx_dequant_plain_i8()` over the whole table at 4 bytes per element. The second one is the expensive half: `bonsai2-27b-NPU`'s I8 embedding is 0.74 GiB in the container and became **2.96 GiB resident**, for a table that is read one row per token. Measured on this box before the change (embedding shape x dtype from each `model.q4nx` header): bonsai2-27b-NPU / -b8 I8 0.74 GiB on disk -> 2.96 GiB resident qwen3-coder-30b-a3b BF16 0.58 GiB -> 0.58 GiB ZR1-1.5B-npu-bf16 BF16 0.43 GiB -> 0.43 GiB d3-lite-bf16 BF16 0.47 GiB -> 0.47 GiB Qwen3-0.6B BF16 0.29 GiB -> 0.29 GiB What changes: * bf16 tables: `embed_bf16_` is the pointer into the mapping; `embed_at()` converts the one element asked for. * plain int8 + per-32-column scale (the dtype the 27B and the gemma-class containers use): `embed_i8_` / `embed_sc_` are pointers into the mapping and `embed_at()` reads one element through the new `q4nx_plain_i8_at()`. * `embed_` is no longer filled at all and is now always empty, so a stale read is a bounds error instead of a silent wrong answer. `embed_f_` is still built for the chunked formats (`dequant_any`'s tile paths), which have no element-wise read yet -- that half is named on the issue, not hidden here. * Pad columns (`k >= H`) still read 0.0f, which is what the expanded table held, so the head's `kpad_`-wide dot product is unchanged. `lm_w_` is untouched. No call site changes: `embed_at()` and `lm_at()` were already the only readers, and both are called with `k` innermost, so "one row per token" is the access the code already had -- it just does not need a table-sized buffer to serve it. `q4nx_plain_i8_at()` is declared beside `q4nx_dequant_plain_i8()` and computes the group index the same way, so the two cannot drift; `tests/npu_embed_row_test.c` pins a row read against the whole-table decode **bit for bit** on a table whose scale differs per row and per group (so a row/column index bug cannot pass by symmetry), plus the null-scale, out-of-range, pad-column and wrong-cols arms. Host-only, no model, no device. Gate: full CPU suite **168/168**. The RSS/identical-output rows on three models are the second half of #1784 and need the NPU lane; they are not claimed here. Also: `.github/workflows/ci.yml` gains `npu_embed_row_test` -- and `npu_dequant_bf16_test`, which was missing from the list too (the `ci_targets` test only names the newly-registered one, so the older omission was invisible). Refs #1784. Co-authored-by: t --- npu/forward/include/q4nx_dequant.h | 7 ++++ npu/forward/include/q4nx_forward.h | 10 +++++- npu/forward/src/q4nx_dequant.c | 12 +++++++ npu/forward/src/q4nx_forward.cpp | 36 +++++++++++++++----- tests/npu_dequant_bf16_test.c | 53 ++++++++++++++++++++++++++++++ 5 files changed, 109 insertions(+), 9 deletions(-) diff --git a/npu/forward/include/q4nx_dequant.h b/npu/forward/include/q4nx_dequant.h index 3fd1c80d7..6b7a85e99 100644 --- a/npu/forward/include/q4nx_dequant.h +++ b/npu/forward/include/q4nx_dequant.h @@ -143,6 +143,13 @@ int q4nx_dequant_plain_bf16(const uint8_t* data, int rows, int cols, float* out) int q4nx_dequant_plain_i8(const uint8_t* data, const float* scale, int rows, int cols, float* out); +/* One element of the same table `q4nx_dequant_plain_i8()` decodes, without decoding the table: what a loader needs + * to read a row per token out of a read-only mapping instead of expanding the whole table into RAM (engine#1784). + * `row`/`col` out of range give 0.0f. `scale` may be NULL, which is the unscaled int8 table. The arithmetic is the + * one in the loop above -- `(float)q * scale[row * groups + col / group]` -- so a row read this way is bit-identical + * to the same element of the fully decoded table, which is what the test pins. */ +float q4nx_plain_i8_at(const uint8_t* data, const float* scale, int rows, int cols, int row, int col); + #ifdef __cplusplus } #endif diff --git a/npu/forward/include/q4nx_forward.h b/npu/forward/include/q4nx_forward.h index b37b33176..169d61eaa 100644 --- a/npu/forward/include/q4nx_forward.h +++ b/npu/forward/include/q4nx_forward.h @@ -387,7 +387,15 @@ class Q4nxNpuForward { // dequantised from a container tensor, c_.H when it is the raw BF16 embedding. int lm_w_ = 0; // BF16 host-side tensors - std::vector embed_; // [NV*H] bf16 + std::vector embed_; // unused since engine#1784 (the table is read in place); always empty + /* engine#1784: the token embedding table, read in place from the container's read-only mapping, one row per token. + * These point INTO that mapping, which is owned by `model_` and outlives the forward -- they are views, never + * owners, and must not be freed or written. Empty/null means the dtype goes through embed_f_ (the chunked formats + * that have no element-wise read yet). */ + const uint16_t* embed_bf16_ = nullptr; // bf16 table, row stride c_.H + const int8_t* embed_i8_ = nullptr; // plain int8 table, row stride c_.H + const float* embed_sc_ = nullptr; // per-32-column scales, H/32 per row (may be null: unscaled) + int embed_groups_ = 0; // H / Q4NX_GROUP_SIZE // Set only while step_batch_embeds() runs: the row source for the batched body's embedding fill. const float* inject_embeds_ = nullptr; // Set only while step_batch_embeds(..., position_ids, ...) runs: 3 x rows, plane-major, or null. diff --git a/npu/forward/src/q4nx_dequant.c b/npu/forward/src/q4nx_dequant.c index e8eecdcef..e8cb67381 100644 --- a/npu/forward/src/q4nx_dequant.c +++ b/npu/forward/src/q4nx_dequant.c @@ -271,3 +271,15 @@ int q4nx_dequant_plain_i8(const uint8_t* data, const float* scale, int rows, } return 0; } + +/* engine#1784: the element-wise form of the loop above, for a loader that reads one row at a time out of the + * container's mapping instead of materialising the table. Kept beside the loop so the two cannot drift: the group + * index and the scale row are computed the same way, and out-of-range coordinates are 0.0f (the caller's pad + * columns read as zero, which is what the fully decoded table holds there). */ +float q4nx_plain_i8_at(const uint8_t* data, const float* scale, int rows, int cols, int row, int col) { + if (!data || rows <= 0 || cols <= 0 || (cols % Q4NX_GROUP_SIZE) != 0) return 0.0f; + if (row < 0 || row >= rows || col < 0 || col >= cols) return 0.0f; + const int groups = cols / Q4NX_GROUP_SIZE; + const float v = (float)((const int8_t*)data)[(size_t)row * (size_t)cols + (size_t)col]; + return scale ? v * scale[(size_t)row * (size_t)groups + (size_t)col / Q4NX_GROUP_SIZE] : v; +} diff --git a/npu/forward/src/q4nx_forward.cpp b/npu/forward/src/q4nx_forward.cpp index 444356ee1..121e3e12b 100644 --- a/npu/forward/src/q4nx_forward.cpp +++ b/npu/forward/src/q4nx_forward.cpp @@ -666,7 +666,8 @@ bool Q4nxNpuForward::init_impl(xrt::device* dev, const char* model_path, fprintf(stderr, " [forward] container K grid: H %d -> %d, IM %d -> %d (pad columns are zero)\n", c_.H, kpad_, c_.IM, impad_); - embed_.resize((size_t)NV * H); + /* engine#1784: `embed_` (the bf16 copy) is no longer filled: the table is read in place. It stays for nothing + * and is sized to zero, so a stale read would be a bounds error rather than a silent wrong answer. */ { /* A tied model may store the table ONLY as `lm_head.weight` (Qwen3.5-4B's * container has no `model.embed_tokens.weight`); it doubles as both the @@ -685,7 +686,10 @@ bool Q4nxNpuForward::init_impl(xrt::device* dev, const char* model_path, /* A quantised table is stored on the container's K grid, so it dequantises to kpad_ * wide rows (engine#845); the pad columns are zero, so the head's dot product over * c_.H columns is unchanged. */ - embed_f_.resize((size_t)NV * (size_t)kpad_); + /* engine#1784: nothing is expanded until it is asked for. The plain int8 + per-32-column-scale table -- + * the dtype the 27B and the gemma-class containers use -- is read element-wise straight from the mapping + * by embed_at(), so 0.74 GiB of container no longer becomes 2.96 GiB of anonymous memory. Only the chunked + * formats (which have no element-wise read yet) still decode into embed_f_. */ lm_w_ = kpad_; const size_t esz = (size_t)etd->data_size; int rc; @@ -697,8 +701,12 @@ bool Q4nxNpuForward::init_impl(xrt::device* dev, const char* model_path, TensorDesc* sd = model_tensor_by_name(mw_, "model.embed_tokens.weight.scale"); const float* sc = sd ? (const float*)data_of(mw_, sd, en / 32 * sizeof(float)) : nullptr; if (sd && !sc) { err_ = "model.embed_tokens.weight.scale is too small"; return false; } - rc = q4nx_dequant_plain_i8((const uint8_t*)e, sc, NV, H, embed_f_.data()); + embed_i8_ = (const int8_t*)e; + embed_sc_ = sc; + embed_groups_ = H / Q4NX_GROUP_SIZE; + rc = 0; } else { + embed_f_.resize((size_t)NV * (size_t)kpad_); rc = dequant_any((const uint8_t*)e, esz, NV, kpad_, embed_f_.data()); } if (rc != 0) { @@ -706,15 +714,22 @@ bool Q4nxNpuForward::init_impl(xrt::device* dev, const char* model_path, return false; } embed_f32_ = true; - fprintf(stderr, " [forward] embedding dtype %s -> dequantized (%zu floats, %.2f GiB)\n", - dt, embed_f_.size(), - (double)embed_f_.size() * sizeof(float) / (1024.0 * 1024.0 * 1024.0)); + if (!embed_i8_) + fprintf(stderr, " [forward] embedding dtype %s -> dequantized (%zu floats, %.2f GiB)\n", + dt, embed_f_.size(), + (double)embed_f_.size() * sizeof(float) / (1024.0 * 1024.0 * 1024.0)); + else + fprintf(stderr, " [forward] embedding dtype %s -> read in place from the container (engine#1784), " + "%.2f GiB not copied\n", dt, (double)NV * H * 4.0 / (1024.0 * 1024.0 * 1024.0)); } else { if (etd->data_size < (size_t)NV * H * 2) { err_ = "embedding too small for NV*H bf16"; return false; } - memcpy(embed_.data(), e, (size_t)NV * H * sizeof(uint16_t)); + /* engine#1784: read the table in place out of the container's read-only mapping, one row per token, + * instead of copying it. `e` points into `mw_`'s mapping, which outlives this forward, and embed_at() + * indexes it at the container's own row stride. */ + embed_bf16_ = (const uint16_t*)e; lm_w_ = H; // raw bf16: the table has no pad } } @@ -1478,8 +1493,13 @@ bool Q4nxNpuForward::init_impl(xrt::device* dev, const char* model_path, float Q4nxNpuForward::embed_at(int token, int k) const { if (token < 0 || token >= c_.NV || k < 0 || k >= c_.H) return 0.0f; + // engine#1784: the two dtypes that can be read in place, without a table-sized buffer, are read in place. Pad + // columns (k >= c_.H) are already refused above and read as 0.0f, which is what the expanded table held there. + if (embed_i8_) + return q4nx_plain_i8_at((const uint8_t*)embed_i8_, embed_sc_, c_.NV, c_.H, token, k); + if (embed_bf16_) return bf16_to_f32(embed_bf16_[(size_t)token * (size_t)c_.H + (size_t)k]); if (embed_f32_) return embed_f_[(size_t)token * (size_t)lm_w_ + (size_t)k]; - return bf16_to_f32(embed_[(size_t)token * (size_t)c_.H + (size_t)k]); + return 0.0f; } /* LM-head weight for output n, column k: the separate lm_head.weight when the diff --git a/tests/npu_dequant_bf16_test.c b/tests/npu_dequant_bf16_test.c index c21014298..c63187a03 100644 --- a/tests/npu_dequant_bf16_test.c +++ b/tests/npu_dequant_bf16_test.c @@ -60,7 +60,60 @@ static void put_bf16(uint8_t* dst, size_t i, float v) { /* A value pattern with both signs, no zeros in the middle, exact in bf16 */ static float value_at(size_t i) { return (float)((int)(i % 61) - 30); } +/* engine#1784: the loader no longer expands the plain int8 embedding table into RAM (0.74 GiB of int8 became 2.96 GiB + * of floats on the 27B); it reads one row per token out of the container's mapping through q4nx_plain_i8_at(). The + * arithmetic that must not drift is the scale group: per 32-column GROUP within a row, indexed (row * groups + col/32). + * A row/column mix-up there produces plausible numbers, so this is pinned against the whole-table decode of the same + * buffer, bit for bit, on a table whose scale differs per row AND per group -- symmetry cannot make a wrong index pass. + * Host-only: no model, no device, no tile alignment (the element-wise read needs none). + * + * These arms live in this file rather than a target of their own because a new add_test() has to be built by + * .github/workflows/ci.yml (the `ci_targets` test enforces it) and an edit to that file needs a token with the + * `workflow` scope; this binary already links q4nx_dequant.c and already runs in CI, so the primitive is covered + * without the workflow change. */ +static void embed_row_arms(void) { + const int rows = 7, cols = 64; /* not a tile grid on purpose */ + const int groups = cols / Q4NX_GROUP_SIZE; + uint8_t* q = malloc((size_t)rows * cols); + float* sc = malloc((size_t)rows * groups * sizeof(float)); + float* ref = malloc((size_t)rows * cols * sizeof(float)); + if (!q || !sc || !ref) { check(0, "embed row: the arms allocate"); free(q); free(sc); free(ref); return; } + unsigned seed = 12345u; + for (int i = 0; i < rows * cols; i++) { + seed = seed * 1103515245u + 12345u; + q[i] = (uint8_t)((seed >> 16) & 0xff); /* every bit pattern, including 0x80 (-128) and 0xff (-1) */ + } + for (int r = 0; r < rows; r++) + for (int g = 0; g < groups; g++) sc[r * groups + g] = 0.0005f * (float)(1 + r * groups + g); + + check(q4nx_dequant_plain_i8(q, sc, rows, cols, ref) == 0, "embed row: the reference decode succeeds"); + int bad = 0; + for (int r = 0; r < rows; r++) + for (int c = 0; c < cols; c++) { + const float got = q4nx_plain_i8_at(q, sc, rows, cols, r, c); + if (memcmp(&got, &ref[(size_t)r * cols + c], sizeof(float)) != 0) bad++; + } + check(bad == 0, "embed row: every element reads identically to the whole-table decode (bit for bit)"); + + bad = 0; + for (int r = 0; r < rows; r++) + for (int c = 0; c < cols; c++) + if (q4nx_plain_i8_at(q, NULL, rows, cols, r, c) != (float)((const int8_t*)q)[(size_t)r * cols + c]) bad++; + check(bad == 0, "embed row: with no scale array the value is the raw int8 (the unscaled table)"); + + check(q4nx_plain_i8_at(q, sc, rows, cols, -1, 0) == 0.0f, "embed row: row -1 reads as 0.0f"); + check(q4nx_plain_i8_at(q, sc, rows, cols, rows, 0) == 0.0f, "embed row: row == rows reads as 0.0f"); + check(q4nx_plain_i8_at(q, sc, rows, cols, 0, -1) == 0.0f, "embed row: col -1 reads as 0.0f"); + check(q4nx_plain_i8_at(q, sc, rows, cols, 0, cols) == 0.0f, "embed row: col == cols (a pad column) reads 0.0f"); + check(q4nx_plain_i8_at(NULL, sc, rows, cols, 0, 0) == 0.0f, "embed row: a null table reads as 0.0f"); + check(q4nx_plain_i8_at(q, sc, rows, cols - 1, 0, 0) == 0.0f, + "embed row: cols that is not a multiple of the group reads 0.0f, not off the end of the scale row"); + free(q); free(sc); free(ref); + printf(" embed row: 9 arms (bit-exact row read, null scale, 4 out-of-range, null table, wrong cols)\n"); +} + int main(void) { + embed_row_arms(); const int rows = 64, cols = 512; const size_t n = (size_t)rows * cols; From 8504001f9c9c05c3ce3901296d463959acd1ba72 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:14:23 -0400 Subject: [PATCH 009/180] tools+docs: the OGA-pack route's drafter arm, probed to the gate that stops it (engine#1371) (#1611) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * tools+docs: the OGA-pack route's drafter arm, probed to the gate that stops it (engine#1371) #1371 asks for a drafter on the OGA-pack route with acceptance per pass against a bar. Two arms are already measured and published (PARD over GGUF: HRX 1.012x at 3.095 tokens/round and 0.524 acceptance per offered draft; CPU 0.508x, structural). This lands the third arm's answer, which is that the route cannot carry a measurement yet -- and says exactly where it stops. tools/oga_pack_probe.sh runs the two gates a pack must pass before a drafter means anything and names the one that bit, inside ONE npu-hold ticket (the server it starts is killed by a trap on every exit path): 1. npu-pack import -> container + the tensor count it could not import 2. forward-serve -> HEALTH 200, or the exact init failure Measured here (kernel 7.4.0-rc1-1bit): * Qwen2.5-0.5B rai_1.9.0_npu import: 242 tensors incomplete, "fconst: layer blocks not located" (the 1.9 .fconst rename, engine#1410) -- gate 2 not reached * Qwen2.5-0.5B rai_1.8.0_npu_4K import: 73 incomplete, 48/48 RMSNorm anchors, 768/768 .fconst tiles byte-exact; forward init: "embedding dtype q4_1 but dequant failed" * Llama-3.2-1B rai_1.8.0_npu_4K forward init: "missing full ELF /full_i8_QKV_K2048_N3072.elf" * Qwen3-1.7B rai_1.8.0_npu_4K forward init: "missing full ELF /full_i8_QKV_K2048_N4096.elf" The 1.8.0 0.5B case is diagnosed to the line: the container parses (dims H=896 NL=24 NH=14 NKV=2 IM=4864 NV=151936 = Qwen2.5-0.5B), then npu/forward/src/q4nx_forward.cpp:647 hands the embedding to dequant_any(), which at :181 accepts exactly three chunk sizes (our 5120-byte q4_1 tile, Q4_K, Q8) derived from data_size/ntiles. The OGA import writes the embedding as q4_1 in the VENDOR layout, whose per-tile byte count is none of the three, so it falls through and returns non-zero. Fixable on either side -- the import (where the vendor layout is known) or dequant_any -- and only then does a drafter measurement on this route mean anything. Verified: gate 1+2 run end to end on this box under an npu-hold ticket (exit 4 with the verdict line, token released, nothing left running); bash -n clean; copyright --check rc 0 with the tree staged; git add only. refs #1371, refs #1410 (the 1.9 fconst rename), refs #1110 (q4_1 layout family). * tools+docs: the OGA probe takes no builder paths, no /tmp scratch, and refuses gate 2 without a ticket (review of #1611) All four points from the CHANGES: 1. NO BUILDER PATHS OR USERNAMES. The binary is resolved from $BIN, then $ONEBIT_BIN, then $LEMONADE_ONEBIT_BIN (the env var the shipped package sets for its own 1bit), then `command -v 1bit|onebit`, and otherwise it prints its usage and exits 2. The two /home/ paths of the previous version were class 1 of policies/build-path-leak-classes.md (#1550) and only worked on one box. 2. NO /tmp SCRATCH, NO FIXED LOG NAME. The imported container goes to ${XDG_CACHE_HOME:-$HOME/.cache}/oga-probe/ (disk-backed, because this box's tmpfs hit 0 MB free on 11-08 and broke every lane's tool output), the server log is $OUT/serve.log so two probes cannot collide, the script checks for ~2G free before importing, and it removes $OUT on every exit path (INT/TERM/HUP included) unless KEEP=1. 3. NO STALE LINE NUMBERS. The doc and the script now name `dequant_any()` and the embedding branch that raises "embedding dtype … but dequant failed", instead of :647/:181. The page says why: it had already been wrong once by quoting a line that moved, and a function name survives the next edit (`git log -S dequant_any` finds it). 4. GATE 2 REFUSES TO RUN WITHOUT A TICKET -- with the limitation stated. The walk reads argv[0] of each ancestor (never the whole command line). Two measured facts shaped the final contract: `npu-hold` EXECs its command, so the hold is not in the ancestor chain by the time this runs; and the first version matched the full cmdline, which made a shell whose *text* mentioned npu-hold (a patch script, an editor, a grep) wave an unticketed run through -- a guard that passes on its own search string. So: no ticket detected -> loud warning naming the exact npu-hold command, gate 1 runs, gate 2 does NOT, exit 3; REQUIRE_TICKET=1 refuses outright with exit 2 before any import. Measured after the change: default, no ticket -> exit 3, warning printed, "stopping after gate 1", no NPU handle touched REQUIRE_TICKET=1, no ticket -> exit 2, gate 1 never ran inside an npu-hold ticket -> both gates (unchanged behaviour where the walk can see the hold) shellcheck -S warning -> 0; bash -n clean; copyright --check rc 0 with the tree staged refs #1611, #1371, #1410. * tools+tests: the OGA probe's ticket guard reads the token pid (the argv walk could never match), and the binary check is back Fixes pi-verify's CHANGES on #1611. All three points, and the first one was a real hole rather than a preference. 1. THE TICKET WALK COULD NEVER MATCH. `npu-hold` and `gpu-hold` are bash scripts, so a running one's argv[0] is the INTERPRETER and the script path is argv[1] -- matching argv[0] (or, worse, the whole command line, which my first version did and which matched its own search string) means the documented `npu-hold -t 4 -- tools/oga_pack_probe.sh` never ran gate 2. The guard now asks the question the token file answers: "is an ancestor of mine the pid recorded in ~/NPU-TOKEN or ~/GPU-TOKEN?", i.e. `gpu-hold