From 5c919ec3e625be6fa890435d33a7807553f6dec6 Mon Sep 17 00:00:00 2001 From: t Date: Tue, 10 Nov 2026 18:42:23 -0400 Subject: [PATCH 1/2] npu-pack: the container genre's geometry, as a pure function with its source named engine#1786 (item F1), slice 1 of 3. #1974 taught the importer to *read* an NPU2 container and to recognise the genre; the plan still says "recognised and reported, not importable", because nothing derives geometry from the container. This is the function that does the deriving, and nothing else yet -- `plan()` is wired to it in slice 2. `container_geometry(meta, config)` takes the container's `__metadata__` and config.json and returns the Dims, the `source` that answered ("dims" / "config.json" / empty), the fields nothing could fill (`missing`) and the fields derived from another (`inferred`). Why the source has to be named: the census on this box (engine#1786) measured three genres over 29 packs -- 13 self-describing with a full `dims` block, 14 gguf-converted with only converter/format/source, and 2 (`d3-edge`, `d3-flash`) with no metadata at all -- and 29 of 29 also carry config.json. So the same field can arrive from two places that can disagree, and a plan that merely holds a number cannot say whether it was declared or read. Order of authority is the container's own statement, then the file beside it. `head_dim` when absent is derived from hidden/heads and reported as **inferred** rather than as declared: that identity is false for every architecture whose q projection is not square. `Q4nxContainer` keeps `meta` for the same reason: the reader already parses the header and was throwing `__metadata__` away. Arms (no pack, no device, no file -- which is what makes the two no-metadata genres pinnable at all): self-describing answers from `dims` and beats a disagreeing config.json; gguf-converted answers from config.json; silent reports all seven required fields missing and invents none; a derivable head_dim is reported as inferred and not also missing. --- npu/pack_import.cpp | 52 ++++++++++++++++++++++++++++++++++ npu/pack_import.h | 20 +++++++++++++ tests/npu_pack_import_test.cpp | 51 +++++++++++++++++++++++++++++++++ 3 files changed, 123 insertions(+) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index 492a7d494..429347cc3 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -1904,6 +1904,7 @@ Q4nxContainer read_q4nx_container(const std::string& path) { out.why = path + ": header is not a JSON object"; return out; } + if (j.contains("__metadata__") && j["__metadata__"].is_object()) out.meta = j["__metadata__"]; for (auto it = j.begin(); it != j.end(); ++it) { if (it.key() == "__metadata__") continue; if (!it.value().is_object()) { @@ -3313,6 +3314,57 @@ std::string header_witness_refusal(int vote_hdrs, bool declared_qk) { "neither is being preferred"; } +// engine#1786 (item F1): the container genre's geometry, from the container's own `dims` block and then config.json. +// The order is authority, not preference: `dims` is the pack's own statement about itself, config.json is a file beside +// it that a vendor converter wrote. When the two disagree the container's statement wins and `source` says so -- the +// census measured 13 packs carrying `dims` and 29 of 29 carrying config.json, so a silent disagreement is possible and +// a reader has to be able to see which one answered. +ContainerGeometry container_geometry(const json& meta, const json& config) { + ContainerGeometry g; + const json& d = (meta.is_object() && meta.contains("dims") && meta["dims"].is_object()) ? meta["dims"] : json(); + const json& cfg = config.is_object() ? config : json(); + bool used_dims = false, used_cfg = false; + + // an integer from dims first, then config.json; records which one answered + const auto iv = [&](const char* key, int& dst) -> bool { + if (d.is_object() && d.contains(key) && d[key].is_number_integer()) { dst = d[key].get(); used_dims = true; return true; } + if (cfg.is_object() && cfg.contains(key) && cfg[key].is_number_integer()) { dst = cfg[key].get(); used_cfg = true; return true; } + return false; + }; + const auto fv = [&](const char* key, float& dst) -> bool { + if (d.is_object() && d.contains(key) && d[key].is_number()) { dst = d[key].get(); used_dims = true; return true; } + if (cfg.is_object() && cfg.contains(key) && cfg[key].is_number()) { dst = cfg[key].get(); used_cfg = true; return true; } + return false; + }; + const auto sv = [&](const char* key, std::string& dst) -> bool { + if (d.is_object() && d.contains(key) && d[key].is_string()) { dst = d[key].get(); used_dims = true; return true; } + if (cfg.is_object() && cfg.contains(key) && cfg[key].is_string()) { dst = cfg[key].get(); used_cfg = true; return true; } + return false; + }; + + if (!iv("hidden_size", g.dims.hidden)) g.missing.push_back("hidden_size"); + if (!iv("num_hidden_layers", g.dims.layers)) g.missing.push_back("num_hidden_layers"); + if (!iv("num_attention_heads", g.dims.heads)) g.missing.push_back("num_attention_heads"); + if (!iv("num_key_value_heads", g.dims.kv_heads)) g.missing.push_back("num_key_value_heads"); + if (!iv("vocab_size", g.dims.vocab)) g.missing.push_back("vocab_size"); + if (!iv("intermediate_size", g.dims.intermediate)) g.missing.push_back("intermediate_size"); + if (!iv("head_dim", g.dims.head_dim)) { + // derived, and said to be derived: hidden/heads is only head_dim when the pack does not state one, and it is + // wrong for every architecture whose q projection is not square (GQA with an explicit head_dim is common). + if (g.dims.hidden > 0 && g.dims.heads > 0) { + g.dims.head_dim = g.dims.hidden / g.dims.heads; + g.inferred.push_back("head_dim"); + } else { + g.missing.push_back("head_dim"); + } + } + if (!fv("rope_theta", g.dims.rope_theta)) g.missing.push_back("rope_theta"); + sv("model_type", g.dims.model_type); // not load-bearing for the arithmetic; absent is not missing + + g.source = used_dims ? "dims" : (used_cfg ? "config.json" : ""); + return g; +} + std::string qk_norm_refusal(bool declared, bool found) { if (declared && !found) return "this pack declares use_qk_norm and its per-head q/k gains are not where the block layout says " diff --git a/npu/pack_import.h b/npu/pack_import.h index dc62f27ff..f21dcf51b 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -289,10 +289,30 @@ struct Q4nxContainer { int64_t header_bytes = 0; int64_t payload_bytes = 0; std::vector tensors; // in header order + // The safetensors `__metadata__` object, kept because it is where this genre states its own geometry (engine#1786). + // Three quarters of the packs measured on this box carry a `dims` block with hidden/intermediate/layers/heads/vocab; + // two carry no metadata at all (`d3-edge`, `d3-flash`), which is why the reader keeps it as data and does not + // interpret it here. + nlohmann::json meta; std::string why; // non-empty when the container could not be read; tensors is then empty }; Q4nxContainer read_q4nx_container(const std::string& path); +// engine#1786 (item F1): the container genre's geometry, from the two places a pack can state it, in order of +// authority -- the container's own `dims` block, then config.json. `source` names which one answered, so a plan can +// never present a declared number and a file's number as the same kind of fact; `missing` names the fields neither +// could fill, and `inferred` the ones derived from other fields (head_dim from hidden/heads). +// +// Pure: no file is opened, so the three genres the census measured -- 13 self-describing, 14 gguf-converted, 2 with +// no metadata at all -- can all be pinned without a pack, which is the point of extracting it from `plan()`. +struct ContainerGeometry { + Dims dims; + std::string source; // "dims", "config.json", or empty when neither answered + std::vector missing; // fields no source could fill, by name + std::vector inferred; // fields derived from another field, by name +}; +ContainerGeometry container_geometry(const nlohmann::json& meta, const nlohmann::json& config); + // Reads the pack (model.onnx, its external data, both .fconst headers, config.json). // Throws only when the pack is structurally unreadable. Plan plan(const std::string& pack_dir); diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index e494e8110..5e1a4bcfc 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -4765,6 +4765,56 @@ void test_embedding_f32_component(const std::string& root) { fs::remove_all(b); } +// engine#1786 (item F1): the container genre's geometry, pinned as a pure function over the three header shapes the +// census measured on this box -- no pack, no device, no file, which is what makes the two genres with no config.json +// (`d3-edge`, `d3-flash`) pinnable at all. +void test_container_geometry() { + using nlohmann::json; + // 1. self-describing: `dims` answers everything, and config.json must NOT be preferred over it. + { + json meta = {{"dims", {{"hidden_size", 576}, {"intermediate_size", 1536}, {"num_hidden_layers", 30}, + {"num_attention_heads", 9}, {"num_key_value_heads", 3}, {"vocab_size", 49152}, + {"head_dim", 64}, {"rope_theta", 10000.0}, {"model_type", "llama"}}}}; + json cfg = {{"hidden_size", 1024}}; // a deliberate disagreement: the container's own statement wins + const auto g = pi::container_geometry(meta, cfg); + check(g.source == "dims", "self-describing: source is dims"); + check(g.dims.hidden == 576, "self-describing: hidden comes from dims, not config.json"); + check(g.dims.layers == 30 && g.dims.heads == 9 && g.dims.kv_heads == 3 && g.dims.vocab == 49152, + "self-describing: every field dims states is taken"); + check(g.dims.head_dim == 64, "self-describing: a stated head_dim is used as stated"); + check(g.missing.empty(), "self-describing: nothing is missing"); + check(g.inferred.empty(), "self-describing: nothing is inferred"); + } + // 2. gguf-converted: no dims, so config.json answers and the source says so. + { + json meta = {{"converter", "tools/gguf_to_q4nx.py"}, {"format", "q4nx"}, {"source", "x.gguf"}}; + json cfg = {{"hidden_size", 1024}, {"num_hidden_layers", 28}, {"num_attention_heads", 16}, + {"num_key_value_heads", 8}, {"vocab_size", 151936}, {"intermediate_size", 3072}, + {"head_dim", 64}, {"rope_theta", 1000000.0}}; + const auto g = pi::container_geometry(meta, cfg); + check(g.source == "config.json", "gguf-converted: source is config.json"); + check(g.dims.hidden == 1024 && g.dims.vocab == 151936, "gguf-converted: config.json supplies the geometry"); + check(g.missing.empty(), "gguf-converted: nothing is missing when config.json is complete"); + } + // 3. silent: neither answers, so every field is named missing rather than left as a zero that reads like a value. + { + const auto g = pi::container_geometry(json::object(), json()); + check(g.source.empty(), "silent: no source is claimed"); + check(g.missing.size() == 7, "silent: all seven required fields are named missing"); + check(g.dims.hidden == 0 && g.dims.layers == 0, "silent: no field is invented"); + } + // 4. head_dim absent but derivable: reported as INFERRED, not as declared. + { + json meta = {{"dims", {{"hidden_size", 2048}, {"intermediate_size", 6144}, {"num_hidden_layers", 28}, + {"num_attention_heads", 16}, {"num_key_value_heads", 8}, {"vocab_size", 151936}, + {"rope_theta", 1000000.0}}}}; + const auto g = pi::container_geometry(meta, json()); + check(g.dims.head_dim == 128, "inferred: head_dim is hidden/heads"); + check(g.inferred.size() == 1 && g.inferred[0] == "head_dim", "inferred: the inference is named"); + check(g.missing.size() == 0, "inferred: an inferred field is not also missing"); + } +} + // engine#1786 (item F1): an NPU2 model source is a safetensors container, and this is the reader that decides whether // a pack is that genre. The failure that matters is the silent one -- a wrong header length yields an empty inventory, // which reads as "a pack with no tensors" rather than "a malformed header" -- so each arm asserts the reason, not just @@ -5490,6 +5540,7 @@ int main(int argc, char** argv) { test_attn_payload_off(); test_text_config_geometry(golden_dir.empty() ? "." : golden_dir); test_q4nx_container(golden_dir.empty() ? "." : golden_dir); + test_container_geometry(); test_hybrid_pack_import(golden_dir.empty() ? "." : golden_dir); test_rope_parameters_theta(golden_dir.empty() ? "." : golden_dir); test_three_input_matmulnbits(golden_dir.empty() ? "." : golden_dir); From 2628499c7e9c45794d0de925db2003af81e553a8 Mon Sep 17 00:00:00 2001 From: t Date: Tue, 10 Nov 2026 19:00:52 -0400 Subject: [PATCH 2/2] npu-pack test: the silent-genre arm asserted seven missing fields; there are eight CI caught this arm on its first run: `container_geometry({}, {})` reports eight required fields, not seven, because `rope_theta` is part of the arithmetic (the RoPE base the forward needs) and I had counted the fields from memory. The arm was wrong, the function was right. It asserts the names now rather than only the count, so the next field added to `Dims` fails this arm instead of quietly shrinking what it covers. --- tests/npu_pack_import_test.cpp | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index 5e1a4bcfc..2a2bca1d4 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -4800,7 +4800,17 @@ void test_container_geometry() { { const auto g = pi::container_geometry(json::object(), json()); check(g.source.empty(), "silent: no source is claimed"); - check(g.missing.size() == 7, "silent: all seven required fields are named missing"); + // eight, and named: the first run of this arm asserted seven and failed in CI -- rope_theta is a required + // field of the arithmetic (it is the RoPE base the forward needs), so the count was wrong and the function + // was right. Asserted by name now, so the next field added to Dims fails this arm instead of shrinking it. + const std::vector want = {"hidden_size", "num_hidden_layers", "num_attention_heads", + "num_key_value_heads", "vocab_size", "intermediate_size", + "head_dim", "rope_theta"}; + check(g.missing.size() == want.size(), "silent: every required field is named missing"); + bool all_named = true; + for (const auto& w : want) + all_named = all_named && std::find(g.missing.begin(), g.missing.end(), w) != g.missing.end(); + check(all_named, "silent: the missing list names each required field"); check(g.dims.hidden == 0 && g.dims.layers == 0, "silent: no field is invented"); } // 4. head_dim absent but derivable: reported as INFERRED, not as declared.