diff --git a/CMakeLists.txt b/CMakeLists.txt
index a9ed75674..6239fb2ea 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1834,6 +1834,14 @@ add_test(NAME npu_pb16i_layout
COMMAND ${CMAKE_SOURCE_DIR}/tests/npu_pb16i_layout_test.sh
${CMAKE_CXX_COMPILER} ${CMAKE_SOURCE_DIR}/npu/forward/include
${CMAKE_SOURCE_DIR}/tests/npu_pb16i_layout_test.cpp)
+# engine#2599's decision (npu/target/xdna/elf_twin.h): a prefill ELF runs at 16 rows only when it is byte-identical to
+# the _m16 twin of its own stem. Every arm, on files it writes itself; no device.
+# Self-compiling (like npu_pb16i_layout): CI builds an explicit target list, so a plain add_executable would be "Not Run"
+# there and trip ci_targets.
+add_test(NAME npu_elf_twin
+ COMMAND ${CMAKE_SOURCE_DIR}/tests/npu_elf_twin_test.sh
+ ${CMAKE_CXX_COMPILER} ${CMAKE_SOURCE_DIR}/npu
+ ${CMAKE_SOURCE_DIR}/tests/npu_elf_twin_test.cpp)
# The w4g32 weight image (q4nx_w4g32.h): the large-M int4-weight prefill tier's contract -- the b4 tile
# order, the per-32 signed magnitudes, the A pack and the int64 reference. No device; set
# W4G32_VEC="
M K N" to also check it against a gate vector set the NPU reproduced bit-exact.
diff --git a/npu/target/xdna/elf_twin.h b/npu/target/xdna/elf_twin.h
new file mode 100644
index 000000000..81c2cd415
--- /dev/null
+++ b/npu/target/xdna/elf_twin.h
@@ -0,0 +1,58 @@
+// Copyright 2026 bong-water-water-bong
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// elf_twin.h -- engine#2599: is a prefill ELF the very same artifact as its own M=16 decode twin?
+//
+// bonsai2-27b-NPU shipped kernels/full_i8__K*_N*.elf byte-identical to the matching _m16.elf: its "prefill" set
+// was the 16-row design. The artifact cannot say how many rows it computes (its declared widths are per tile), so a
+// context sized from the design geometry (M=128) computed the first 16 rows of every 128-row chunk. The evidence is
+// equal size and equal bytes against the twin of the SAME stem -- two roles of one shape (G and U) are legitimately
+// identical and are never compared with each other. tests/npu_elf_twin_test.cpp pins both functions.
+#pragma once
+
+#include
+#include
+#include
+#include
+#include
+
+namespace onebit::npu {
+
+// "/_m16.elf" for an ELF named ".elf" (a name without ".elf" keeps its whole name as the stem).
+inline std::string m16_twin_path(const std::string& dir, const std::string& elf_name) {
+ std::string stem(elf_name);
+ if (stem.size() > 4 && stem.compare(stem.size() - 4, 4, ".elf") == 0) stem.resize(stem.size() - 4);
+ return dir + "/" + stem + "_m16.elf";
+}
+
+// True only when both files open, are the same non-zero size and hold the same bytes.
+inline bool same_artifact(const std::string& a, const std::string& b) {
+ std::ifstream fa(a, std::ios::binary | std::ios::ate), fb(b, std::ios::binary | std::ios::ate);
+ if (!fa || !fb) return false;
+ const std::streamoff na = fa.tellg(), nb = fb.tellg();
+ if (na <= 0 || na != nb) return false;
+ fa.seekg(0);
+ fb.seekg(0);
+ std::vector ba(1 << 16), bb(1 << 16);
+ for (std::streamoff left = na; left > 0;) {
+ const std::streamsize n = (std::streamsize)std::min(left, (std::streamoff)ba.size());
+ if (!fa.read(ba.data(), n) || !fb.read(bb.data(), n)) return false;
+ if (std::memcmp(ba.data(), bb.data(), (size_t)n) != 0) return false;
+ left -= n;
+ }
+ return true;
+}
+
+} // namespace onebit::npu
diff --git a/npu/target/xdna/xdna_target.cpp b/npu/target/xdna/xdna_target.cpp
index 9e6f125f6..6a618a138 100644
--- a/npu/target/xdna/xdna_target.cpp
+++ b/npu/target/xdna/xdna_target.cpp
@@ -20,6 +20,7 @@
//
// docs/npu-p4-target-split.md records what moved in A1 and what A2 (plan-driven setup) still owes.
#include "target/xdna/xdna_target.h"
+#include "target/xdna/elf_twin.h" // engine#2599: a prefill ELF that is its own _m16 twin
#include "target/xdna/launch_fit.h" // engine#1783: refuse a launch its context cannot hold
#include "batch_width.h"
#include "file_create.h" // dumps are created 0600, never through a symlink
@@ -83,28 +84,6 @@ static const char* role_tag(Q4nxDesign r) {
// The forward's own probe, kept identical (exists and non-empty): an ELF that is present but zero bytes
// is the failure this catches, and a target that decided differently from its caller would be a second
// definition of "the kernel is there".
-// engine#2599: is the prefill ELF the very same artifact as its M=16 decode twin? bonsai2-27b-NPU ships
-// kernels/full_i8__K*_N*.elf byte-identical (md5) to the matching _m16.elf, i.e. its "prefill" set IS the
-// 16-row design. Nothing in the artifact says how many rows it computes (its declared widths are per-tile, and a
-// narrower declared width than the buffer is legal), so a context sized from the design geometry (M=128) chunked the
-// prompt at 128 rows and the kernel computed the first 16 of each: 112 rows of every chunk came back as 0. Equal size
-// and equal bytes is the evidence; anything else (a real M=128 build, or no twin in the directory) changes nothing.
-static bool same_artifact(const std::string& a, const std::string& b) {
- std::ifstream fa(a, std::ios::binary | std::ios::ate), fb(b, std::ios::binary | std::ios::ate);
- if (!fa || !fb) return false;
- const std::streamoff na = fa.tellg(), nb = fb.tellg();
- if (na <= 0 || na != nb) return false;
- fa.seekg(0); fb.seekg(0);
- std::vector ba(1 << 16), bb(1 << 16);
- for (std::streamoff left = na; left > 0;) {
- const std::streamsize n = (std::streamsize)std::min(left, (std::streamoff)ba.size());
- if (!fa.read(ba.data(), n) || !fb.read(bb.data(), n)) return false;
- if (std::memcmp(ba.data(), bb.data(), (size_t)n) != 0) return false;
- left -= n;
- }
- return true;
-}
-
static bool elf_present(const std::string& p) {
FILE* f = std::fopen(p.c_str(), "rb");
if (!f) return false;
@@ -220,10 +199,8 @@ bool XdnaTarget::open_prefill(const Q4nxDesignGeom* designs, int n, std::string&
int md = w4_rows_ ? w4_rows_ : g->M;
if (!w4_rows_) {
// engine#2599 (the w4g32 tier opens its own M=512 ELF instead, so this does not apply to it)
- std::string twin(g->elf_name);
- if (twin.size() > 4 && twin.compare(twin.size() - 4, 4, ".elf") == 0) twin.resize(twin.size() - 4);
- twin = dir + "/" + twin + "_m16.elf";
- if (md > Q4NX_DESIGN_M_DECODE && same_artifact(elf, twin)) {
+ const std::string twin = onebit::npu::m16_twin_path(dir, g->elf_name);
+ if (md > Q4NX_DESIGN_M_DECODE && onebit::npu::same_artifact(elf, twin)) {
md = Q4NX_DESIGN_M_DECODE;
prefill_is_decode_design_ = true;
std::fprintf(stderr, " [forward] %-3s %s is byte-identical to its _m16 twin: it is the %d-row design, so "
diff --git a/tests/npu_elf_twin_test.cpp b/tests/npu_elf_twin_test.cpp
new file mode 100644
index 000000000..6c03608bc
--- /dev/null
+++ b/tests/npu_elf_twin_test.cpp
@@ -0,0 +1,86 @@
+// Copyright 2026 bong-water-water-bong
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// npu_elf_twin_test -- engine#2599's decision, pinned without a device: open_prefill() runs a role at 16 rows only when
+// its prefill ELF is byte-identical to the _m16 twin of the SAME stem. Every arm of that decision:
+// 1. the twin path is "/_m16.elf";
+// 2. identical bytes -> twin (the bonsai2-27b-NPU case);
+// 3. one byte different, same size -> not a twin (a real M=128 build of equal size);
+// 4. a different size -> not a twin;
+// 5. no twin on disk, or an empty file -> not a twin (nothing changes);
+// 6. two ROLES of one shape (G and U) are identical by design, and the rule never compares them: G's twin is G_m16.
+#include "target/xdna/elf_twin.h"
+
+#include
+#include
+#include
+#include
+#include
+#include
+
+static int fails = 0;
+#define CHECK(c, m) do { if (!(c)) { std::printf("FAIL: %s\n", m); ++fails; } } while (0)
+
+static void put(const std::string& p, const std::string& bytes) { std::ofstream(p, std::ios::binary) << bytes; }
+
+int main() {
+ char tmpl[] = "/tmp/npu-elf-twin.XXXXXX";
+ const char* tmp = std::getenv("TMPDIR");
+ std::string base = tmp && *tmp ? std::string(tmp) + "/npu-elf-twin.XXXXXX" : std::string(tmpl);
+ std::vector buf(base.begin(), base.end());
+ buf.push_back('\0');
+ if (!mkdtemp(buf.data())) { std::printf("mkdtemp failed\n"); return 1; }
+ const std::string d(buf.data());
+ using onebit::npu::m16_twin_path;
+ using onebit::npu::same_artifact;
+
+ CHECK(m16_twin_path(d, "full_i8_U_K5120_N17408.elf") == d + "/full_i8_U_K5120_N17408_m16.elf", "1. twin path");
+ CHECK(m16_twin_path(d, "noext") == d + "/noext_m16.elf", "1. twin path without .elf");
+
+ const std::string big(200000, 'x'); // spans several 64 KiB compare blocks
+ put(d + "/U.elf", big);
+ put(d + "/U_m16.elf", big);
+ CHECK(same_artifact(d + "/U.elf", m16_twin_path(d, "U.elf")), "2. identical bytes are a twin");
+
+ std::string last = big; last.back() = 'y';
+ put(d + "/D.elf", big);
+ put(d + "/D_m16.elf", last);
+ CHECK(!same_artifact(d + "/D.elf", m16_twin_path(d, "D.elf")), "3. a last-byte difference is not a twin");
+ std::string mid = big; mid[70000] = 'z';
+ put(d + "/O_m16.elf", mid);
+ put(d + "/O.elf", big);
+ CHECK(!same_artifact(d + "/O.elf", m16_twin_path(d, "O.elf")), "3. a difference in the second block is not a twin");
+
+ put(d + "/Z.elf", big);
+ put(d + "/Z_m16.elf", big + "x");
+ CHECK(!same_artifact(d + "/Z.elf", m16_twin_path(d, "Z.elf")), "4. a size difference is not a twin");
+
+ put(d + "/Q.elf", big);
+ CHECK(!same_artifact(d + "/Q.elf", m16_twin_path(d, "Q.elf")), "5. no twin on disk is not a twin");
+ put(d + "/E.elf", "");
+ put(d + "/E_m16.elf", "");
+ CHECK(!same_artifact(d + "/E.elf", m16_twin_path(d, "E.elf")), "5. two empty files are not a twin");
+
+ // 6. G and U: same shape, same bytes, no _m16 for G here -> G is not reported as a twin of U.
+ put(d + "/G.elf", big);
+ CHECK(!same_artifact(d + "/G.elf", m16_twin_path(d, "G.elf")), "6. G identical to U is not G's twin");
+
+ for (const char* f : {"U", "U_m16", "D", "D_m16", "O", "O_m16", "Z", "Z_m16", "Q", "E", "E_m16", "G"})
+ std::remove((d + "/" + f + ".elf").c_str());
+ rmdir(d.c_str());
+ if (fails) { std::printf("npu_elf_twin_test: %d failure(s)\n", fails); return 1; }
+ std::printf("npu_elf_twin_test: OK\n");
+ return 0;
+}
diff --git a/tests/npu_elf_twin_test.sh b/tests/npu_elf_twin_test.sh
new file mode 100755
index 000000000..72fa4c025
--- /dev/null
+++ b/tests/npu_elf_twin_test.sh
@@ -0,0 +1,31 @@
+#!/bin/bash
+# Copyright 2026 bong-water-water-bong
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# npu_elf_twin_test.sh
+#
+# engine#2599's twin decision (npu/target/xdna/elf_twin.h) is pure index math: no
+# runtime, no device, no NPU toolchain. Same reason as npu_blocked_layout_test.sh:
+# the check compiles itself with the build's own compiler at test time, so it cannot
+# become "Not Run" by being absent from CI's explicit target list.
+set -u
+CXX=${1:?usage: npu_elf_twin_test.sh }
+INC=${2:?}
+SRC=${3:?}
+work=$(mktemp -d "${TMPDIR:-/tmp}/npu-elf-twin.XXXXXX")
+trap 'rm -rf "$work"' EXIT
+"$CXX" -std=c++17 -O1 -Wall -Wextra -I "$INC" "$SRC" -o "$work/t" || {
+ echo "npu_elf_twin_test: compile failed"; exit 1; }
+"$work/t"