From 943d02327ca20768c32a4f32e9976d6a3000aa05 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Thu, 12 Nov 2026 17:21:02 -0400 Subject: [PATCH 1/2] npu-pack: the import plan -- where each tensor's bytes go, and proof that they add up (engine#1788, 3c) The last pure step before a writer touches a file: for every tensor of a container, its destination slot and the byte range the bytes come from, with a duplicate-destination guard and an NAMED unplaced list. Pure, so it is tested without a filesystem, and a caller can refuse a container before creating an output directory. The measurement that matters, on the acceptance case: MiniCPM 35B 733 items, 21043717120 of 21043717120 bytes, 0 unplaced <- every byte of the payload gemma3-270m 237 items, 503182592 of 503182592 bytes, 0 unplaced 1B 321 items, 1067619072 of 1068798720, 36 unplaced <- the .bf16. copies, by design gemma4-e2b 461 items, 2157725184 of 4671794246, 248 unplaced <- gemma_local's five, by design bolt-e4b 552 items, 3993434624 of 7142523988, 297 unplaced <- same Coverage, not item count, is the property a writer needs: the 35B's plan accounts for the payload to the byte, and the two containers that do not are missing only tensors this engine has no field for -- which the placement already refuses. And the lesson from how this was found: my first version of this plan reported 500 items and 233 unplaced on the 35B while the placement said 733/733. The plan was right and MY TEST was wrong -- an over-broad sed had rewired the leg's call to pass a one-element layer-type list, so every linear layer fell out of range. The coverage print is what caught it, and it is now part of the leg rather than something I ran once. --- npu/pack_import.cpp | 26 +++++++++++++++++++++ npu/pack_import.h | 20 ++++++++++++++++ tests/npu_pack_import_test.cpp | 42 ++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index e5885fd0e..6ddd9950a 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -3482,6 +3482,32 @@ static std::string group_suffix_slot(const std::string& role, const std::string& return std::string(); } +ImportPlan container_import_plan(const Q4nxContainer& container, const std::vector& layer_types) { + ImportPlan out; + out.payload_bytes = container.payload_bytes; + const PlacementReport rep = container_placement(container.tensors, layer_types); + std::map by_name; + for (const auto& t : container.tensors) by_name[t.name] = &t; + std::set seen; + for (const auto& row : rep.rows) { + if (row.slot.empty()) { + out.unplaced.push_back((row.role.empty() ? std::string("(no role)") : row.role) + ": " + row.tensor); + continue; + } + if (!seen.insert(row.slot).second) { // a second write would silently replace the first + out.unplaced.push_back(row.role + ": " + row.tensor + " (destination already taken)"); + continue; + } + ImportItem item; + item.slot = row.slot; item.source = row.tensor; item.shape = row.shape; item.dtype = row.dtype; + const auto it = by_name.find(row.tensor); + if (it != by_name.end()) { item.begin = it->second->begin; item.end = it->second->end; } + out.bytes += item.end - item.begin; + out.items.push_back(item); + } + return out; +} + PlacementReport container_placement(const std::vector& tensors, const std::vector& layer_types) { PlacementReport out; diff --git a/npu/pack_import.h b/npu/pack_import.h index 3a2a19ce5..cc3b0f238 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -411,6 +411,26 @@ RoleSlotReport container_role_slots(const ContainerRoles& roles); // not treat that as "unchanged", which is why this returns a string and the report above returns the reasons. std::string container_role_slot(const std::string& role, const std::string& layer_type); +// engine#1788, 3c: the last pure step before bytes are written -- where each tensor's bytes go and which bytes they are. +// Separated from the I/O so it can be tested without a filesystem, and so a caller can refuse a container BEFORE writing +// anything into an output directory. `layer_types` comes from config.json beside the container (NOT from its safetensors +// metadata: that is where the measured ones live, and reading meta instead silently refused every layer-typed role). +struct ImportItem { + std::string slot; // the engine slot the bytes are written to (layer-qualified) + std::string source; // the container tensor they come from + int64_t begin = 0; // data_offsets[0] within the payload + int64_t end = 0; + std::vector shape; + std::string dtype; +}; +struct ImportPlan { + std::vector items; // placed tensors only; an empty slot is never written + std::vector unplaced; // ": " -- a refusal, not a silent skip + int64_t bytes = 0; // payload bytes the items carry + int64_t payload_bytes = 0; // what the container says it has, so a writer can prove coverage +}; +ImportPlan container_import_plan(const Q4nxContainer& container, const std::vector& layer_types); + // engine#1788, slice 3c: the writer's per-TENSOR decision, which is what an import actually iterates. Reads the tensor's // own layer, takes that layer's declared type, and asks the table above for a destination. A tensor with no role and a // tensor with a role but no destination are counted apart, because the first is a vocabulary gap and the second is a diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index 3dada0f80..19f14d458 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -5246,6 +5246,12 @@ static void test_container_placement_real(const std::string& dir, const std::vec check(row.dtype == "I8", "placement: and I8 (" + row.slot + ") in " + dir); } } + { + // the question a writer must answer before writing: do the item ranges add up to the payload? + const ImportPlan ip = container_import_plan(c, layer_types); + std::printf(" import: %zu items, %lld of %lld bytes, %zu unplaced\n", ip.items.size(), + (long long)ip.bytes, (long long)ip.payload_bytes, ip.unplaced.size()); + } std::printf(" roles:"); for (const auto& kv : roles_seen) std::printf(" %s=%lld", kv.first.c_str(), (long long)kv.second); std::printf("\n"); std::printf(" UNKNOWN:"); @@ -5373,6 +5379,41 @@ static void test_scale_and_proj_norm_roles() { } } +// engine#1788, 3c: the import plan -- where each tensor's bytes go and which bytes they are. +void test_container_import_plan() { + using pi::Q4nxTensor; + const auto t = [](const std::string& n, std::vector sh, const std::string& dt, int64_t b, int64_t e) { + Q4nxTensor x; x.name = n; x.shape = sh; x.dtype = dt; x.begin = b; x.end = e; return x; + }; + pi::Q4nxContainer c; + c.tensors = { + t("model.embed_tokens.weight", {128, 64}, "BF16", 0, 100), + t("model.layers.0.self_attn.q_proj.weight", {256, 8, 4736}, "I8", 100, 400), + t("model.layers.0.unknown_thing.weight", {4}, "I8", 400, 410), + }; + c.payload_bytes = 410; + const pi::ImportPlan p = pi::container_import_plan(c, {"full_attention"}); + check(p.items.size() == 2, "import: two tensors placed, one not"); + check(p.items[0].slot == "model.embed_tokens.weight", "import: the embedding keeps its own name"); + check(p.items[1].slot == "model.layers.0.self_attn.q_proj.weight", "import: the projection is layer-qualified"); + check(p.items[1].begin == 100 && p.items[1].end == 400, "import: and carries ITS byte range"); + check(p.bytes == 400, "import: bytes are the placed tensors', not the whole payload"); + check(p.unplaced.size() == 1 && p.unplaced[0].find("unknown_thing") != std::string::npos, + "import: the unplaced tensor is NAMED"); + check(p.payload_bytes == 410, "import: the container's payload size is carried for a coverage check"); + + // the layer-type dependency, as a pair: q_proj places without one, qkv_proj does not + pi::Q4nxContainer q; + q.tensors = {t("model.layers.0.self_attn.q_proj.weight", {256, 8, 4736}, "I8", 0, 50), + t("model.layers.0.self_attn.qkv_proj.weight", {256, 8, 4736}, "I8", 50, 100)}; + q.payload_bytes = 100; + const pi::ImportPlan pq = pi::container_import_plan(q, {}); + check(pq.items.size() == 1 && pq.items[0].slot == "model.layers.0.self_attn.q_proj.weight", + "import: q_proj places without layer types"); + check(pq.unplaced.size() == 1 && pq.unplaced[0].find("qkv_proj") != std::string::npos, + "import: qkv_proj does not, and is named"); +} + void test_container_placement() { using pi::Q4nxTensor; const auto t = [](const std::string& n) { Q4nxTensor x; x.name = n; x.dtype = "I8"; return x; }; @@ -6615,6 +6656,7 @@ int main(int argc, char** argv) { test_container_roles_gemma_local(); test_container_roles_moe_and_singular_layer(); test_container_placement(); + test_container_import_plan(); test_scale_and_proj_norm_roles(); test_role_tables_disagree_nowhere(); if (argc > 4) { From 383544fc5e2918a0274296441bdab009b9db59ce Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Thu, 12 Nov 2026 20:53:17 -0400 Subject: [PATCH 2/2] npu-pack: a byte sum is only coverage if the ranges are DISJOINT (review of #2307) The review found the gap one level below the claim: uniqueness was enforced on the destination SLOT, while the headline is about BYTES. Two tensors with DIFFERENT slots and overlapping [begin,end) would double-count one region and skip another, and the totals would still print "21043717120 of 21043717120, 0 unplaced" -- the two errors cancelling. Now the plan sorts the items by offset, reports an overlap in `unplaced` with both tensors named, and -- because a plan whose totals can cancel must not quote them -- drops the offending items and rebuilds the sum. So `bytes` is either honest or the plan is not usable, never quietly wrong. Arms: an overlapping pair is caught and named AND leaves bytes==0 with no items; the same two ranges in the opposite order are accepted (disjoint is disjoint regardless of order). Mutant (skip the check): "the totals are not quoted for a plan that can cancel" fails. Measured again on the 35B after the change: still 733 items, 21043717120 of 21043717120 bytes, 0 unplaced -- so the container's ranges really are disjoint, which the PR previously asserted without checking. --- npu/pack_import.cpp | 27 +++++++++++++++++++++++++++ tests/npu_pack_import_test.cpp | 18 ++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index 6ddd9950a..8a5015c2d 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -3505,6 +3505,33 @@ ImportPlan container_import_plan(const Q4nxContainer& container, const std::vect out.bytes += item.end - item.begin; out.items.push_back(item); } + // engine#1788, 3c (review): a SUM is only coverage if the ranges are DISJOINT. Uniqueness is enforced on the slot, but + // two tensors with different slots and overlapping [begin,end) would double-count one region and skip another, and the + // totals would still add up. Sorted by offset, so an overlap is caught once and named. + std::vector> spans; + for (const auto& it : out.items) spans.push_back({it.begin, it.source}); + std::sort(spans.begin(), spans.end()); + std::set overlapping; + for (size_t i = 1; i < spans.size(); ++i) { + const auto prev = by_name.find(spans[i - 1].second); + if (prev != by_name.end() && prev->second->end > spans[i].first) { + overlapping.insert(spans[i - 1].second); + overlapping.insert(spans[i].second); + out.unplaced.push_back("overlapping payload ranges: " + spans[i - 1].second + " and " + spans[i].second + + " (a sum over these would count one region twice and skip another)"); + } + } + if (!overlapping.empty()) { + // the totals must not be quoted when they can cancel: drop the offending items and rebuild the sum + std::vector kept; + out.bytes = 0; + for (const auto& it : out.items) { + if (overlapping.count(it.source)) continue; + kept.push_back(it); + out.bytes += it.end - it.begin; + } + out.items.swap(kept); + } return out; } diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index 19f14d458..1c2768b1a 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -5412,6 +5412,24 @@ void test_container_import_plan() { "import: q_proj places without layer types"); check(pq.unplaced.size() == 1 && pq.unplaced[0].find("qkv_proj") != std::string::npos, "import: qkv_proj does not, and is named"); + // engine#1788 review: a SUM is not coverage unless the ranges are disjoint. Two tensors with different slots and + // overlapping bytes would double-count one region and skip another, and the totals would still add up. + pi::Q4nxContainer ov; + ov.tensors = {t("model.embed_tokens.weight", {2, 2}, "I8", 0, 16), + t("model.layers.0.self_attn.q_proj.weight", {2, 2}, "I8", 8, 24)}; + ov.payload_bytes = 64; + const pi::ImportPlan ovp = pi::container_import_plan(ov, {"full_attention"}); + check(!ovp.unplaced.empty() && ovp.unplaced.back().find("overlapping") != std::string::npos, + "import: overlapping byte ranges are caught and named"); + check(ovp.bytes == 0 && ovp.items.empty(), + "import: and the totals are not quoted for a plan that can cancel"); + // disjoint ranges in a different order are NOT reported + pi::Q4nxContainer ok_order; + ok_order.tensors = {t("model.layers.0.self_attn.q_proj.weight", {2, 2}, "I8", 8, 24), + t("model.embed_tokens.weight", {2, 2}, "I8", 0, 8)}; + ok_order.payload_bytes = 64; + const pi::ImportPlan okp = pi::container_import_plan(ok_order, {"full_attention"}); + check(okp.unplaced.empty() && okp.bytes == 24, "import: disjoint ranges out of order are fine"); } void test_container_placement() {