Upload folder using huggingface_hub

.gitattributes

@@ -1,35 +1,36 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.ninfer filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

NOTICE

@@ -0,0 +1,129 @@
+Swift-Bonsai-2 27B — NInfer ternary artifacts (PQ2_0_G128 / PTQ1_0_G128)
+=======================================================================
+
+This work is licensed under the Apache License, Version 2.0. See the LICENSE file.
+
+Every component in the provenance chain is Apache-2.0 licensed **except one link, which is
+disclosed explicitly in section 2 below**. We do not hide it.
+
+
+1. PROVENANCE CHAIN
+-------------------
+
+  Qwen/Qwen3.8-27B                                   Apache-2.0
+      Copyright 2026 Alibaba Cloud
+      The dense 27B base model. Geometry, tokenizer and the six frontend resources derive here.
+
+  prism-ml/Ternary-Bonsai-2-27B-gguf                 Apache-2.0
+      Copyright Prism ML, Inc.
+      The ternary (1.58-bit) + Hadamard-rotated-basis release of Bonsai 2 27B.
+      Defines the `prism.hadamard.*` metadata contract this artifact carries.
+
+  ukisai/Swift-Bonsai-2-GGUF                         Apache-2.0
+      ukisai — "Swift Bonsai 2", a reasoning-efficient fine-tune.
+      >>> THIS IS THE WEIGHT SOURCE OF THE ARTIFACTS IN THIS REPOSITORY. <<<
+
+  github.com/Neroued/ninfer                          Apache-2.0
+      Upstream engine, converter and the version-2 artifact container format.
+
+  github.com/Ambolio/ninfer-4090-windows             Apache-2.0
+      The Ada/Windows source lineage (v1.0.6 / v1.0.8) whose format dialect this artifact uses.
+      (The HF copy that existed under the same name is now 404; the lineage persists through forks.)
+
+  shensanshu/ninfer-ada-ternary                      Apache-2.0
+      The packer `tools/pack.py`, the per-tensor mapping table `tools/MAPPING.json`,
+      and the five verification scripts, all redistributed here under Apache-2.0
+      with the notice below.
+
+  Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer   Apache-2.0
+      Used ONLY as a template: its object list (the skeleton this packer walks) and the
+      payloads it donates for vision / mtp / frontend / draft_head.
+      **Its text weights are discarded entirely and do not enter this artifact.**
+
+  Upstream sibling — ukisai/Swift-Qwen3.8-27b              swift-open-license-1.0
+      This is the BF16 fine-tune checkpoint from which ukisai's Swift derivative family descends.
+      It is **not** the direct source of this repository (we pack from ukisai's GGUF release,
+      which is itself marked Apache-2.0), but it sits in the same family, and its license is
+      **not** Apache. We flag it here rather than omit it so downstream users can make their own
+      judgement. If you need a conservative position, treat this chain as carrying that
+      upstream license.
+
+
+2. SCOPE OF WHAT THIS REPOSITORY DISTRIBUTES
+--------------------------------------------
+
+This repository distributes **weight-derived artifacts** (the two `.ninfer` files), not code
+weights per se. Per the packer project's own NOTICE:
+
+  > 由本项目产出的 `.ninfer` 制品属于权重派生品，其再分发义务以权重原许可为准，与代码许可无关。
+
+The direct source (`ukisai/Swift-Bonsai-2-GGUF`) and the base (`prism-ml/Ternary-Bonsai-2-27B-gguf`,
+`Qwen/Qwen3.8-27B`) are all published as **Apache-2.0**, which permits redistribution.
+The un-Apache link noted in section 1 is upstream of the direct source and is disclosed there.
+
+**No model weights were retrained, fine-tuned, abliterated or otherwise behaviourally modified
+by us.** Model behaviour — including all refusal characteristics inherited from the upstream
+fine-tune — derives entirely from `ukisai/Swift-Bonsai-2-GGUF`.
+
+
+STATEMENT OF CHANGES (Apache-2.0 section 4(b))
+----------------------------------------------
+
+Relative to `ukisai/Swift-Bonsai-2-GGUF` (the weight source):
+
+  * The 402 ternary matrices were **moved byte-for-byte**. The 2-bit codes and their per-128
+    FP16 scales were copied verbatim from the GGUF block stream into the artifact's
+    `row-split-k128-v1` three-plane layout. **No dequantization and no requantization occurred.**
+  * llama.cpp's exporter conventions were undone, as the upstream recipe requires:
+      - GDN value heads: tiled order -> grouped order (per-head, `perm48(head)*128 + inner`)
+      - zero-centred norms: `1 + w` -> `w`   (except `gdn/norm` / `ssm_norm`, whose raw value
+        is already ~1)
+      - `ssm_a` (`-exp(A_log)`) -> `A_log`
+  * `text/hadamard_signs` (28,672 fp32 words) and `text/hadamard_widths` (3 int32) were
+    **added**: they restate the GGUF's `prism.hadamard.sign_values` / `sign_widths` in the
+    artifact's own object vocabulary. The source GGUF already carries these values; the
+    template does not, which is why the object count is 1126 rather than 1124.
+  * Non-ternary tensors (norms, GDN A/B projections, convolution, `A_log`, `dt_bias`,
+    `token_embedding`'s direct companions) were re-encoded from the same GGUF.
+
+Relative to `Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer` (the template):
+
+  * **Nothing of its text tower is used.** Only its object list and the vision (333), mtp (12),
+    frontend (6) and draft_head (2) payloads — 1,116,856,537 bytes — were carried over.
+  * Those payloads are the official Qwen3.8-27B components shared across the whole family.
+    The packer verified the MTP head against the target at cosine >= 0.99966 with seven norms
+    **bit-identical**.
+
+Relative to `shensanshu/ninfer-ada-ternary` `tools/pack.py`:
+
+  * **No functional change.** The only edit was to the default path constants at the top of the
+    file — `NINFER_ROOT` (which pointed at the author's own development machine) and `TEMPLATE`
+    — both replaced with neutral placeholders (`<NINFER_ROOT>`, `<TEMPLATE>`). The same
+    substitution was applied to the five scripts under `tools/verify/` and to `MAPPING.json`'s
+    `_verified_by` note. **No logic was altered.**
+  * `MAPPING.json` is redistributed verbatim.
+  * **No validation, checksum, geometry check or byte-round-trip proof was disabled, relaxed
+    or bypassed.** The `check` mode was run to completion against the source GGUF and reported
+    `pad = 0` for all eight shape combinations, with `bytes_equal` and `decode_equal` true on
+    every sampled tensor.
+
+Relative to `github.com/Neroued/ninfer`:
+
+  * **NO CHANGES.** Upstream was not patched, modified or circumvented by this work.
+
+
+Trademarks
+----------
+
+"Qwen" is a trademark of Alibaba Cloud. "Bonsai" and "Prism ML" are marks of Prism ML, Inc.
+
+This is an unofficial, community-produced derivative. It is **not** endorsed by or affiliated
+with Alibaba Cloud, Prism ML, ukisai, shensanshu, or the NInfer project.
+
+
+Disclaimer
+----------
+
+Provided **AS IS**, without warranty of any kind. All measurements cited in README.md were taken
+in specific hardware/software environments and will differ across GPU model, driver, CUDA version
+and memory bandwidth.

README.md

@@ -0,0 +1,293 @@
+---
+license: apache-2.0
+language:
+  - en
+  - zh
+library_name: ninfer
+pipeline_tag: text-generation
+base_model:
+  - prism-ml/Ternary-Bonsai-2-27B-gguf
+  - ukisai/Swift-Bonsai-2-GGUF
+  - Qwen/Qwen3.8-27B
+base_model_relation: quantized
+tags:
+  - ninfer
+  - ternary
+  - 1.58-bit
+  - bonsai
+  - qwen3.8
+  - hadamard
+  - mtp
+  - swift
+  - text-generation
+  - image-text-to-text
+---
+
+# Swift-Bonsai-2 27B — NInfer 三元制品（PQ2 / PTQ1）
+
+**English summary at the end.** ｜ [English README](README_en.md)
+
+---
+
+## ⚠️ 先说引擎兼容性（最重要的一节）
+
+本制品是 **`PQ2_0_G128` / `PTQ1_0_G128`** 方言，需要 **`Ambolio/ninfer-4090-windows` 血统**的引擎
+（v1.0.6 / v1.0.8，即"极速档"那条线）。
+
+**跟 HF 上其它 Bonsai `.ninfer` 不通用：**
+
+| 制品 | 三元格式名 | 需要的引擎 |
+|---|---|---|
+| **本制品** | **`PQ2_0_G128` / `PTQ1_0_G128`** | **Ambolio 血统（v1.0.6 / v1.0.8）** |
+| `WaveCut/Ternary-Bonsai-2-27B-NInfer-v3` | `t2_g128_fp16` | [`iamwavecut/ninfer-all`](https://github.com/iamwavecut/ninfer-all) |
+| `neroued/Qwen3.8-27B-NInfer` | NVFP4 / groupwise-int | [`Neroued/ninfer`](https://github.com/Neroued/ninfer)（上游） |
+
+**装错的表现是启动直接被拒（`refuse this file`），不是"慢一点"。**
+
+判方言的方法 —— 读 `.ninfer` 前 1 MB 里的 `"format"` 字段即可，不用解压整个文件。
+
+---
+
+## 这是什么
+
+`Swift-Bonsai-2` 的三元 NInfer 制品，两档：
+
+| 文件 | 档位 | 大小 | 源 GGUF |
+|---|---|---|---|
+| `bonsai2_27b_swift_pq2.ninfer` | `PQ2_0_G128`（2 bit） | 8,306,927,628 B / 7.736 GiB | `Swift-Bonsai-2-PQ2_0.gguf` |
+| `bonsai2_27b_swift_ptq1.ninfer` | `PTQ1_0_G128`（1.75 bit） | 7,047,407,628 B / 6.563 GiB | `Swift-Bonsai-2-PTQ1_0.gguf` |
+
+**组件：text + vision + mtp（不含 dflash2）。**
+
+**这是格式转换，不是训练。** 三元码逐字节搬运，没有解量化再重量化。
+
+---
+
+## 产物结构（已核对）
+
+```
+identity   {"model_id": "qwen3.8-27b", "weights_id": "groupwise-int"}
+magic      NINFER\x00\x02   （version-2 容器）
+objects    1126 = text 775 + vision 333 + mtp 12 + frontend 6
+
+PQ2 档 formats    BF16 582 | PQ2_0_G128 322 | FP32 97 | Q4G64_F16S 55
+                  | Q5G64_F16S 54 | W8G32_F16S 7 | I32 2 | Q6G64_F16S 1
+PTQ1 档 formats   同上，仅把 PQ2_0_G128 换成 PTQ1_0_G128
+
+layouts    row-split-k128-v1 439 | contiguous-le-v1 681
+新增       text/hadamard_signs、text/hadamard_widths（三元必需）
+借来的     vision 333 + mtp 12 + frontend 6 + draft_head 2 = 1,116,856,537 B（1.040 GiB）
+```
+
+**借来的那几块是全生态共用的官方件。** 打包器的原话：
+
+> vision …**the template's tower is the same official one**
+> mtp …**The template's head is the same official Qwen3.8-27B head**: all twelve tensors
+> matched at cos ≥ 0.99966 with the seven norms **BIT-IDENTICAL**
+
+---
+
+## 怎么用
+
+```powershell
+ninfer-serve.exe bonsai2_27b_swift_pq2.ninfer ^
+  --host 127.0.0.1 --port 8087 ^
+  --max-context 131072 --kv-capacity 131072 ^
+  --kv-dtype int8 ^
+  --spec mtp --draft-tokens 3
+```
+
+**KV dtype 按卡的架构选：**
+
+| 卡 | 可用 KV |
+|---|---|
+| 30 系（sm_86） | `bf16` / `int8` |
+| 40 系（sm_89） | `bf16` / `int8` / `fp8` / `rk4v4` / `rk4v4-e8` |
+| 50 系（sm_120） | `bf16` / `int8` / `fp8` / `nvfp4` / `k8v4`（`rk4v4` 会被拒） |
+
+### ★ MTP 窗口：先扫，别照抄
+
+上游在 4080S 上测出 **N=2 最优**（N=3/4/5 的接受率落到 40.9 / 33.2 / 22.9%）。
+**但那不是普适值 —— 在 12 GB 的 3060 上，`d3` 才是最好的，且比生产用的 `d4+lm` 平均快 2~5%。**
+
+详见下方「实测数据」的 MTP 表。**建议在你自己卡上扫 1~4 档，两个对照模型交替起服。**
+
+---
+
+## 验收状态
+
+| 项 | 状态 |
+|---|---|
+| 源 GGUF 几何 + round-trip | ✅ 8 个形状组合 `pad=0`；5 个真实张量 `bytes_equal` + `decode_equal` 全 True；`zero_share` 0.3277~0.3279（`PQ2_0` 理论指纹 0.3278） |
+| 产出结构对撞 | ✅ 与参考制品 `bonsai2_27b_ternary_v2.ninfer` 的格式分布 **8 项全等**；**总长也逐字节相同**（均 8,306,927,628 B） |
+| 尺寸 | ✅ 两档与上游文档的换算表精确吻合（PQ2 8.31 GB / PTQ1 7.05 GB） |
+| **端到端（RTX 3060 12G / sm_86）** | ✅ **四层全过** —— 启动、输出、前缀复用、视觉、工具调用、采样、思考档位全部正常 |
+| **PPL（同语料 vs base）** | ✅ **略优于 base**，三口径差 −0.07% / −0.04% / −0.01% |
+| **速度 / MTP 接受率** | ✅ **与 base 在 ±2% 内**（测量噪声量级） |
+| 长思考任务上的「思考更短」 | ❓ **未验证** —— 见下 |
+
+> **已由发布者在一台 RTX 3060 12G 上完成端到端验收**（2026-09-28）。
+> 原始记录（`l1.txt` / `l23.txt` / `ppl-*.json` / `quiz-*.json`）由测试者保存在本地，**不随本仓分发**。
+>
+> **仍未验证的一项**：Swift 微调宣��的"思考 token 少 ~40%"。本次题集太简单（每题思考仅
+> 100~500 token），**在该量级上得不出显著结论，也无法否证**。要验证需用 AIME / 竞赛级长思考题，
+> 每题 2k~10k 思考 token、≥20 题 × 2 轮。
+
+---
+
+## 实测数据（RTX 3060 12G / sm_86 / 生产参数）
+
+### PPL（同一 `perplexity` 程序、同一份 `pplab-text`、`int8` KV）
+
+| 窗口/步长 | Swift | base | 差 |
+|---|---:|---:|---:|
+| 512 / 256 | **8.073669** | 8.079208 | **−0.07%** |
+| 32 / 16 | **26.962015** | 26.972171 | **−0.04%** |
+| 8 / 4 | **148.3656** | 148.3863 | **−0.01%** |
+
+**⚠️ 不要拿别处的 PPL 绝对值来比。** PPL 跟语料强相关 —— 上游文档给的参照值（6.448742 /
+26.049634 / 121.157720）用的是**另一份语料**，与上表**不可直接比较**。上表用的是 `pplab-text`，
+只有同一语料下的 Swift vs base 差值才有意义。
+
+### 速度与 MTP 接受率
+
+条件：贪心，每组 400 token，1 次热身 + 2 次取中位，**两个模型交替起服**。
+格式：`t/s（接受率）`。
+
+| 配置 | 模型 | 中文 | 英文 | 代码 | 思考 | 平均 |
+|---|---|---:|---:|---:|---:|---:|
+| d1 | Swift | 42.2 (58%) | 44.4 (68%) | 46.0 (82%) | 45.8 (84%) | 44.6 |
+| d1 | base | 43.1 (62%) | 44.9 (71%) | 46.6 (85%) | 45.4 (83%) | 45.0 |
+| d2 | Swift | 46.0 (46%) | 49.5 (56%) | 58.4 (80%) | 55.9 (76%) | 52.5 |
+| d2 | base | 43.7 (42%) | 46.9 (51%) | 59.6 (82%) | 55.7 (76%) | 51.5 |
+| **d3** | Swift | 44.0 (33%) | 49.7 (44%) | 64.2 (70%) | 62.2 (68%) | **55.0** |
+| **d3** | base | 43.4 (33%) | 52.4 (48%) | 64.9 (71%) | 59.9 (65%) | **55.1** |
+| d4+lm（生产） | Swift | 40.4 (28%) | 48.0 (40%) | 65.5 (67%) | 58.6 (59%) | 53.1 |
+| d4+lm（生产） | base | 39.2 (27%) | 48.2 (41%) | 64.6 (66%) | 57.1 (56%) | 52.3 |
+
+**三条读法：**
+
+1. **Swift 与 base 在每个配置下都相差 ±2% 以内** —— 这是测量噪声。**借来的 MTP 头与 Swift 主干配合得不比 base 差。**
+2. **d3 最好，不是上游在 4080S 上说的 N=2。** d2 只在中文上占优。**MTP 窗口的最优值是卡的属性，不是模型的。**
+3. **d3（不加 `lm-head`）平均比生产用的 `d4+lm` 高 2~5%，两个对照模型都是这个方向。**
+   这是一个**尚未纳入生产配置**的观察 —— 换之前请先用官方 bench 复核。
+
+### 推理题（12 道唯一答案的中英文算术/逻辑题，生产参数，引擎默认采样）
+
+| | 第 1 轮 | 第 2 轮 | 合计输出 token |
+|---|---|---|---:|
+| Swift | 12/12 | 12/12 | 4,501 |
+| base | 12/12 | 12/12 | 5,144 |
+
+**准确率相同；Swift 输出 token 少 12.5%。但样本太小 —— 逐题分布大量重叠，同一模型两轮之间最多能差 2 倍，得不出显著结论。**
+所有回答均以 `finish=stop` 正常结束，无死循环或截断。
+
+### 功能面（生产参数：ctx 65536 / `int8` / MTP d4+lm / vision）
+
+| 项 | 结果 |
+|---|---|
+| 启动 | ✅ `/v1/models` 返回 `qwen3.8-27b`，`max_model_len` = 65536 |
+| 英文 / 中文 | ✅ 通顺 |
+| 同前缀多轮 ×3 | ✅ `200/200/200/200`，第 2、3 次命中 40 token 缓存，输出一致 |
+| 连续 10 个不同请求 | ✅ 全部 200 |
+| 采样 | ✅ 两次输出不同 |
+| 思考档位 | ✅ `none/low/medium/xhigh` 正常；`high` 按预期返回 400（与 base 一致） |
+| 前缀复用（约 2.4k token，3 轮） | ✅ prompt 耗时 **2848 ms → 258 / 268 ms** |
+| 视觉 | ✅ 正确识别红色方块、`CAT`、蓝色 `42` |
+| 工具调用 | ✅ 返回 `get_weather({"city":"Tokyo"})` |
+| `reasoning_effort=none` 时不调工具 | ⚠️ 与 base 的已知现象相同，非本制品问题 |
+
+> **关于前缀复用崩溃**：上游文档记录的"多轮/同前缀第二次请求 500 后全端口 503"在本测试环境**未复现**
+> —— 该引擎已修正此问题。若你的引擎版本较旧且撞上，临时规避是 `--no-prefix-reuse`。
+
+---
+
+## 怎么造出来的（可复现）
+
+```bash
+# 1. 源（ukisai 的 Swift 微调，已三元量化）
+Swift-Bonsai-2-PQ2_0.gguf
+  sha256 5912bb739217cf25b4283a098c7b893d9baff36bdf2e72d3dbf4cb999d5633d5
+
+# 2. 模板 —— 只借它的骨架/对象清单 + vision/MTP/frontend 载荷
+#    它的文本权重被整个丢弃，不进入本制品
+Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer
+  sha256 8c9f9d67a07ac97506978f6db6695d8074f78dec0fb80c4a85a8fb6fbedd7f03
+
+# 3. 打包
+python -u tools/pack.py build bonsai2_27b_swift_pq2.ninfer \
+  --gguf Swift-Bonsai-2-PQ2_0.gguf \
+  --template qwen3_8_27b_huihui_abliterated.ninfer
+# 约 4 分钟（纯 CPU，不需要 GPU）
+```
+
+**完整方法见 `REPRODUCE.md`。** 打包器与逐张量映射表随仓附带（`tools/`）。
+
+---
+
+## 署名（三层，全部必需）
+
+```
+Bonsai 2 27B（原始权重）        © Prism ML, Inc.       Apache-2.0
+                              huggingface.co/prism-ml/Ternary-Bonsai-2-27B-gguf
+Qwen3.8-27B（底座）             © Alibaba Cloud        Apache-2.0
+Swift 微调（���制品权重来源）      ukisai                 Apache-2.0
+                              huggingface.co/ukisai/Swift-Bonsai-2-GGUF
+打包工具                        pack.py —— shensanshu/ninfer-ada-ternary（Apache-2.0）
+容器格式 / 引擎                  github.com/Neroued/ninfer（Apache-2.0）
+```
+
+官方请求的原句署名：
+
+> **"Created using Bonsai by Prism ML."**
+
+**详见 [`NOTICE`](NOTICE)。**
+
+---
+
+## 已知的坑（来自上游文档，非本制品独有）
+
+1. **MTP 窗口 N=2 最优**，N=3/4/5 接受率崩（4080S 实测；不同卡需自测）
+2. **前缀复用崩溃** —— 多轮/同前缀第二次请求 500 然后全端口 503；临时规避 `--no-prefix-reuse`
+3. **改 `.h` 后必须 touch 所有 `.cpp`** —— MSVC 依赖扫描坏，改动会静默不生效（`/GS` 崩溃 `0xC0000409`）
+4. **中文 prompt 走命令行会报 NFC 错** —— 必须用 `--messages <json文件>`（UTF-8 无 BOM）
+5. **`ninfer-perplexity.exe` 必须跟 `ninfer-serve` 同一批编出来** —— 只重编 serve 会留下旧件，导致误判
+
+---
+
+## 许可
+
+**Apache-2.0。** 见 [`LICENSE`](LICENSE) 与 [`NOTICE`](NOTICE)。
+
+**商标**："Qwen" 是 Alibaba Cloud 的商标；"Bonsai" 属 Prism ML。本制品是社区制作的衍生品，
+与 Alibaba Cloud、Prism ML、ukisai 及 NInfer 项目**无隶属或背书关系**。
+
+---
+
+## English summary
+
+**Swift-Bonsai-2 27B, NInfer ternary artifacts** — `PQ2_0_G128` (2-bit) and `PTQ1_0_G128` (1.75-bit).
+
+**Engine compatibility:** this artifact uses the **`PQ2_0_G128` / `PTQ1_0_G128`** dialect and requires an
+engine from the **`Ambolio/ninfer-4090-windows` lineage** (v1.0.6 / v1.0.8).
+It is **NOT** interchangeable with `t2_g128_fp16` artifacts (those need `iamwavecut/ninfer-all`).
+Loading the wrong one is refused at startup, not merely slow.
+
+**What this is:** a **format conversion**, not a training run. Ternary codes are moved byte-for-byte
+from the source GGUF; nothing is dequantized and requantized. Components: text + vision + mtp
+(**no dflash2**).
+
+**Provenance:** Bonsai 2 27B (Prism ML, Apache-2.0) → Swift fine-tune (ukisai, Apache-2.0)
+→ packed with `pack.py` from `shensanshu/ninfer-ada-ternary` (Apache-2.0).
+
+**Verification status:** structural and format-level checks are green (geometry `pad=0` across all 8
+shape combinations; byte round-trip and decode equality on sampled tensors; `zero_share` 0.3278 —
+the `PQ2_0` fingerprint). **End-to-end validation was completed on an RTX 3060 12G**: the server
+starts, output is coherent, prefix reuse, vision and tool calling all work, and PPL is marginally
+**better** than base on the same corpus (−0.07 % / −0.04 % / −0.01 %). See
+[the measured-results tables](#实测数据rtx-3060-12g--sm_86--生产参数) in the Chinese section.
+
+**One advertised claim remains unverified:** "~40 % fewer thinking tokens" — this round's items were
+too easy to resolve at that magnitude. See the verification status table above.
+
+> **"Created using Bonsai by Prism ML."**

README_en.md

@@ -0,0 +1,254 @@
+# Swift-Bonsai-2 27B — NInfer ternary artifacts (PQ2 / PTQ1)
+
+**中文说明见 [README.md](README.md)**
+
+---
+
+## ⚠️ Engine compatibility — read this first
+
+These artifacts use the **`PQ2_0_G128` / `PTQ1_0_G128`** dialect and require an engine from the
+**`Ambolio/ninfer-4090-windows` lineage** (v1.0.6 / v1.0.8, the "极速档 / speed tier" line).
+
+**They are NOT interchangeable with other Bonsai `.ninfer` artifacts on the Hub:**
+
+| Artifact | Ternary format name | Engine required |
+|---|---|---|
+| **this repo** | **`PQ2_0_G128` / `PTQ1_0_G128`** | **Ambolio lineage (v1.0.6 / v1.0.8)** |
+| `WaveCut/Ternary-Bonsai-2-27B-NInfer-v3` | `t2_g128_fp16` | [`iamwavecut/ninfer-all`](https://github.com/iamwavecut/ninfer-all) |
+| `neroued/Qwen3.8-27B-NInfer` | NVFP4 / groupwise-int | [`Neroued/ninfer`](https://github.com/Neroued/ninfer) (upstream) |
+
+Loading the wrong one is **refused at startup** (`refuse this file`) — not merely slow.
+
+To tell which dialect a `.ninfer` uses, read the `"format"` fields in its first 1 MiB. No need to
+scan the whole file.
+
+---
+
+## What this is
+
+Two tiers of `Swift-Bonsai-2` packaged for NInfer:
+
+| File | Tier | Size | Source GGUF |
+|---|---|---|---|
+| `bonsai2_27b_swift_pq2.ninfer` | `PQ2_0_G128` (2-bit) | 8,306,927,628 B / 7.736 GiB | `Swift-Bonsai-2-PQ2_0.gguf` |
+| `bonsai2_27b_swift_ptq1.ninfer` | `PTQ1_0_G128` (1.75-bit) | 7,047,407,628 B / 6.563 GiB | `Swift-Bonsai-2-PTQ1_0.gguf` |
+
+**Components: text + vision + mtp (no dflash2).**
+
+**This is a format conversion, not a training run.** The ternary codes are moved byte-for-byte;
+nothing is dequantized and requantized.
+
+---
+
+## Structure (verified)
+
+```
+identity   {"model_id": "qwen3.8-27b", "weights_id": "groupwise-int"}
+magic      NINFER\x00\x02   (version-2 container)
+objects    1126 = text 775 + vision 333 + mtp 12 + frontend 6
+
+PQ2 tier   BF16 582 | PQ2_0_G128 322 | FP32 97 | Q4G64_F16S 55
+           | Q5G64_F16S 54 | W8G32_F16S 7 | I32 2 | Q6G64_F16S 1
+PTQ1 tier  identical except PQ2_0_G128 -> PTQ1_0_G128
+
+layouts    row-split-k128-v1 439 | contiguous-le-v1 681
+added      text/hadamard_signs, text/hadamard_widths  (required by ternary)
+borrowed   vision 333 + mtp 12 + frontend 6 + draft_head 2 = 1,116,856,537 B (1.040 GiB)
+```
+
+The borrowed set are the official, family-wide Qwen3.8-27B components. From the packer:
+
+> vision …**the template's tower is the same official one**
+> mtp …**The template's head is the same official Qwen3.8-27B head**: all twelve tensors matched
+> at cos ≥ 0.99966 with the seven norms **BIT-IDENTICAL**
+
+---
+
+## Usage
+
+```powershell
+ninfer-serve.exe bonsai2_27b_swift_pq2.ninfer ^
+  --host 127.0.0.1 --port 8087 ^
+  --max-context 131072 --kv-capacity 131072 ^
+  --kv-dtype int8 ^
+  --spec mtp --draft-tokens 3
+```
+
+**KV dtype depends on the GPU architecture:**
+
+| GPU | Available KV |
+|---|---|
+| RTX 30 series (sm_86) | `bf16` / `int8` |
+| RTX 40 series (sm_89) | `bf16` / `int8` / `fp8` / `rk4v4` / `rk4v4-e8` |
+| RTX 50 series (sm_120) | `bf16` / `int8` / `fp8` / `nvfp4` / `k8v4` (`rk4v4` is rejected) |
+
+**On a 12 GB card (e.g. RTX 3060),** `--max-context 32768~131072` with `--kv-dtype int8` is what was
+**actually measured end-to-end** — see the verification status and measured-results tables below.
+
+**Start MTP window scanning at N=2 — but do not copy that number.**
+
+Upstream measured **N=2 optimal on a 4080 SUPER** (N=3/4/5 dropping to 40.9 / 33.2 / 22.9 % acceptance).
+**That is not universal.** On a 12 GB RTX 3060, **`d3` is the best tier** and beats the production
+`d4+lm` by 2–5 % on average. Scan 1–4 on your own card, starting both reference models alternately.
+
+---
+
+## Verification status
+
+| Item | Status |
+|---|---|
+| Source GGUF geometry + round-trip | ✅ `pad=0` for all 8 shape combinations; `bytes_equal` + `decode_equal` true on every sampled tensor; `zero_share` 0.3277–0.3279 (the `PQ2_0` fingerprint is 0.3278) |
+| Output structure | ✅ format distribution matches the reference artifact on all 8 buckets; **total size is byte-identical too** (both 8,306,927,628 B) |
+| Sizes | ✅ both tiers match the upstream conversion table (PQ2 8.31 GB / PTQ1 7.05 GB) |
+| **End-to-end (RTX 3060 12G / sm_86)** | ✅ **all four layers pass** — startup, output, prefix reuse, vision, tool calling, sampling, reasoning tiers |
+| **PPL (same corpus, vs base)** | ✅ **slightly better than base**: −0.07 % / −0.04 % / −0.01 % across three window/stride settings |
+| **Speed / MTP acceptance** | ✅ **within ±2 % of base** (measurement-noise level) |
+| "Shorter thinking" on long-reasoning tasks | ❓ **not verified** |
+
+> **End-to-end validation was completed by the publisher on one RTX 3060 12G** (2026-09-28).
+> Raw records (`l1.txt`, `l23.txt`, `ppl-*.json`, `quiz-*.json`) are kept locally by the
+> tester and are **not distributed with this repository**.
+>
+> **One claim remains unverified:** the fine-tune's advertised "~40 % fewer thinking tokens".
+> This round's question set was too easy (100–500 thinking tokens per item) — **no conclusion is
+> possible at that magnitude, in either direction**. Verifying it needs AIME / competition-level
+> long-reasoning items, 2k–10k thinking tokens each, ≥20 items × 2 rounds.
+
+---
+
+## Measured results (RTX 3060 12G / sm_86 / production parameters)
+
+### PPL — same `perplexity` binary, same `pplab-text` corpus, `int8` KV
+
+| Window / stride | Swift | base | Δ |
+|---|---:|---:|---:|
+| 512 / 256 | **8.073669** | 8.079208 | **−0.07 %** |
+| 32 / 16 | **26.962015** | 26.972171 | **−0.04 %** |
+| 8 / 4 | **148.3656** | 148.3863 | **−0.01 %** |
+
+**⚠️ Do not compare these absolute values against PPL figures from elsewhere.** PPL is corpus-dependent —
+the reference values in the upstream docs (6.448742 / 26.049634 / 121.157720) come from a **different
+corpus** and are **not directly comparable**. Only the Swift-vs-base delta within one corpus means anything.
+
+### Speed and MTP acceptance
+
+Greedy, 400 tokens per run, 1 warmup + 2 runs (median), **both models started alternately**.
+Format: `t/s (acceptance)`.
+
+| Config | Model | Chinese | English | Code | Thinking | Mean |
+|---|---|---:|---:|---:|---:|---:|
+| d1 | Swift | 42.2 (58%) | 44.4 (68%) | 46.0 (82%) | 45.8 (84%) | 44.6 |
+| d1 | base | 43.1 (62%) | 44.9 (71%) | 46.6 (85%) | 45.4 (83%) | 45.0 |
+| d2 | Swift | 46.0 (46%) | 49.5 (56%) | 58.4 (80%) | 55.9 (76%) | 52.5 |
+| d2 | base | 43.7 (42%) | 46.9 (51%) | 59.6 (82%) | 55.7 (76%) | 51.5 |
+| **d3** | Swift | 44.0 (33%) | 49.7 (44%) | 64.2 (70%) | 62.2 (68%) | **55.0** |
+| **d3** | base | 43.4 (33%) | 52.4 (48%) | 64.9 (71%) | 59.9 (65%) | **55.1** |
+| d4+lm (production) | Swift | 40.4 (28%) | 48.0 (40%) | 65.5 (67%) | 58.6 (59%) | 53.1 |
+| d4+lm (production) | base | 39.2 (27%) | 48.2 (41%) | 64.6 (66%) | 57.1 (56%) | 52.3 |
+
+**Three readings:**
+
+1. **Swift and base are within ±2 % in every configuration** — measurement noise. **The borrowed MTP
+   head works no worse with the Swift backbone than with base.**
+2. **`d3` is best, not the N=2 upstream reported for the 4080 SUPER.** d2 only leads on Chinese.
+   **The optimal MTP window is a property of the card, not of the model.**
+3. **`d3` (without `lm-head`) averages 2–5 % faster than the production `d4+lm`, on both models.**
+   This is an **observation not yet folded into the production config** — re-check with the official
+   bench before switching.
+
+### Reasoning quiz (12 unique-answer arithmetic/logic items, production params, engine default sampling)
+
+| | Round 1 | Round 2 | Total output tokens |
+|---|---|---|---:|
+| Swift | 12/12 | 12/12 | 4,501 |
+| base | 12/12 | 12/12 | 5,144 |
+
+**Same accuracy; Swift emitted 12.5 % fewer tokens — but the sample is too small.** Per-item
+distributions overlap heavily and the same model varies up to 2× between rounds, so no significant
+conclusion follows. All replies ended with `finish=stop`; no loops, no truncation.
+
+### Functional checks (production params: ctx 65536 / `int8` / MTP d4+lm / vision)
+
+| Item | Result |
+|---|---|
+| Startup | ✅ `/v1/models` returns `qwen3.8-27b`, `max_model_len` = 65536 |
+| English / Chinese | ✅ coherent |
+| Multi-turn, same prefix ×3 | ✅ `200/200/200/200`; 2nd and 3rd hits a 40-token cache with identical output |
+| 10 consecutive distinct requests | ✅ all 200 |
+| Sampling | ✅ two runs differ |
+| Reasoning tiers | ✅ `none/low/medium/xhigh` normal; `high` returns 400 as expected (same as base) |
+| Prefix reuse (~2.4k tokens, 3 rounds) | ✅ prompt time **2848 ms → 258 / 268 ms** |
+| Vision | ✅ correctly identified a red square, `CAT`, and a blue `42` |
+| Tool calling | ✅ returned `get_weather({"city":"Tokyo"})` |
+| No tool call at `reasoning_effort=none` | ⚠️ Same known behaviour as base — not an artifact issue |
+
+> **On the prefix-reuse crash:** the upstream-documented failure (a second multi-turn/same-prefix
+> request returning 500, then the whole port going 503) **did not reproduce** in this environment —
+> that engine build already fixes it. On an older build, the workaround is `--no-prefix-reuse`.
+
+---
+
+## Reproduction
+
+```bash
+# 1. source (ukisai's Swift fine-tune, already ternary-quantized)
+Swift-Bonsai-2-PQ2_0.gguf
+  sha256 5912bb739217cf25b4283a098c7b893d9baff36bdf2e72d3dbf4cb999d5633d5
+
+# 2. template — only its skeleton/object list and vision/MTP/frontend payloads are used.
+#    Its text weights are discarded entirely.
+Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer
+  sha256 8c9f9d67a07ac97506978f6db6695d8074f78dec0fb80c4a85a8fb6fbedd7f03
+
+# 3. pack
+python -u tools/pack.py build bonsai2_27b_swift_pq2.ninfer \
+  --gguf Swift-Bonsai-2-PQ2_0.gguf \
+  --template qwen3_8_27b_huihui_abliterated.ninfer
+# ~4 minutes, CPU only, no GPU required
+```
+
+Full method: [`REPRODUCE.md`](REPRODUCE.md). The packer and the per-tensor mapping table ship in
+[`tools/`](tools/) under Apache-2.0.
+
+---
+
+## Attribution (all three layers required)
+
+```
+Bonsai 2 27B (original weights)   © Prism ML, Inc.    Apache-2.0
+                                 huggingface.co/prism-ml/Ternary-Bonsai-2-27B-gguf
+Qwen3.8-27B (geometry base)       © Alibaba Cloud     Apache-2.0
+Swift fine-tune (weight source)   ukisai              Apache-2.0
+                                 huggingface.co/ukisai/Swift-Bonsai-2-GGUF
+Packer                            pack.py — shensanshu/ninfer-ada-ternary (Apache-2.0)
+Container format / engine         github.com/Neroued/ninfer (Apache-2.0)
+```
+
+Required upstream attribution string:
+
+> **"Created using Bonsai by Prism ML."**
+
+See [`NOTICE`](NOTICE) — it also discloses one non-Apache link upstream in the fine-tune family.
+
+---
+
+## Known pitfalls (inherited, not specific to this artifact)
+
+1. **MTP window:** N=2 is optimal; N=3/4/5 lose acceptance (measured on 4080 SUPER; retest on yours)
+2. **Prefix-reuse crash:** a second multi-turn/same-prefix request returns 500, then the whole port
+   goes 503. Workaround: `--no-prefix-reuse`
+3. **After editing any `.h`, touch all `.cpp`** — MSVC's header dependency scan is broken here, so
+   changes silently do not take effect (`/GS` crash `0xC0000409`)
+4. **Non-ASCII prompts via the command line fail NFC normalization** — use `--messages <json>` (UTF-8, no BOM)
+5. **`ninfer-perplexity.exe` must be built in the same batch as `ninfer-serve`** — rebuilding only
+   the server leaves a stale tool and makes you misjudge a change as ineffective
+
+---
+
+## License
+
+**Apache-2.0.** See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
+
+**Trademarks:** "Qwen" is a trademark of Alibaba Cloud; "Bonsai" and "Prism ML" belong to
+Prism ML, Inc. This is an unofficial community-produced derivative and is not endorsed by or
+affiliated with Alibaba Cloud, Prism ML, ukisai, shensanshu, or the NInfer project.

REPRODUCE.md

@@ -0,0 +1,316 @@
+# 复现步骤 · REPRODUCE
+
+本仓的两个 `.ninfer` 制品是怎么造出来的 —— 从零到产出，可逐步复跑。
+
+**全程 CPU，不需要 GPU。** 实测约 4 分钟一份。
+
+---
+
+## 0. 依赖
+
+```
+Python 3.11+
+numpy
+torch        ← CPU 版即可（打包器不用 GPU，路径上写死了 torch.device("cpu")）
+```
+
+```bash
+pip install numpy
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+```
+
+**如果你的网络在国内**，Hugging Face 走 `hf-mirror.com` 比走代理快约 50%（实测 7.65 MB/s vs 5.02 MB/s）：
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+---
+
+## 1. 下载源与模板
+
+### 1.1 权重源（ukisai 的 Swift 微调）
+
+```
+https://huggingface.co/ukisai/Swift-Bonsai-2-GGUF
+```
+
+| 文件 | 大小 | sha256 |
+|---|---|---|
+| `Swift-Bonsai-2-PQ2_0.gguf` | 7,206,168,928 B | `5912bb739217cf25b4283a098c7b893d9baff36bdf2e72d3dbf4cb999d5633d5` |
+| `Swift-Bonsai-2-PTQ1_0.gguf` | 5,946,648,960 B | `de33620b60eaf63e96449b478eb87abe9538507e3ed939da944c1ae15fe1ffc6` |
+
+### 1.2 模板
+
+```
+https://huggingface.co/Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer
+```
+
+| 文件 | 大小 | sha256 |
+|---|---|---|
+| `qwen3_8_27b_huihui_abliterated.ninfer` | 18,210,531,328 B | `8c9f9d67a07ac97506978f6db6695d8074f78dec0fb80c4a85a8fb6fbedd7f03` |
+
+**模板的身份必须满足：**
+```json
+"identity": {"model_id": "qwen3.8-27b", "weights_id": "groupwise-int"}
+```
+
+**并且对象名必须是"未融合"的那套**（`attention/query_key` + `attention/gate_value` 分开）。
+`nvfp4` 打包的制品**用不了** —— 它把投影融合成了 `attention/query_key_gate_value`，
+名字不在映射表里，打包器会直接中止。
+
+### 1.3 打包器
+
+`tools/` 目录随本仓附带（Apache-2.0，原样取自 `shensanshu/ninfer-ada-ternary`）。
+
+它需要一个 `NINFER_ROOT` 指向的源码 checkout —— 那里只用来 import `tools.artifact` 这一组模块：
+
+```
+<NINFER_ROOT>/
+    tools/
+        __init__.py
+        artifact/
+            __init__.py
+            container.py
+            layouts.py
+            numeric.py
+```
+
+来源是 `Ambolio/ninfer-4090-windows` 血统的树（或任何含这套 `tools/artifact` 的 checkout）。
+**`pack.py` 源码顶部有一个 `NINFER_ROOT` 默认值**，指到你的实际路径上即可。
+
+---
+
+## 2. 先验（不写文件）
+
+```bash
+python -u tools/pack.py check \
+  --gguf Swift-Bonsai-2-PQ2_0.gguf \
+  --template qwen3_8_27b_huihui_abliterated.ninfer
+```
+
+**期望输出：**
+
+```
+CHECK 1  geometry over every ternary shape present in the GGUF
+  PQ2_0_G128  n=1024   k=5120   groups/row=40   src=    1,392,640 payload=    1,392,640 pad= 0 (32 tensors)
+  PQ2_0_G128  n=5120   k=6144   groups/row=48   src=    8,355,840 payload=    8,355,840 pad= 0 (64 tensors)
+  PQ2_0_G128  n=5120   k=17408  groups/row=136  src=   23,674,880 payload=   23,674,880 pad= 0 (64 tensors)
+  PQ2_0_G128  n=6144   k=5120   groups/row=40   src=    8,355,840 payload=    8,355,840 pad= 0 (48 tensors)
+  PQ2_0_G128  n=10240  k=5120   groups/row=40   src=   13,926,400 payload=   13,926,400 pad= 0 (48 tensors)
+  PQ2_0_G128  n=12288  k=5120   groups/row=40   src=   16,711,680 payload=   16,711,680 pad= 0 (16 tensors)
+  PQ2_0_G128  n=17408  k=5120   groups/row=40   src=   23,674,880 payload=   23,674,880 pad= 0 (128 tensors)
+  PQ2_0_G128  n=248320 k=5120   groups/row=40   src=  337,715,200 payload=  337,715,200 pad= 0 (2 tensors)
+  distinct (format,shape) combos: 8
+
+CHECK 2  byte round trip + decode equality on real tensors
+  blk.3.attn_q.weight      bytes_equal=True decode_equal=True zero_share=0.3279  … PLAUSIBLE
+  …
+```
+
+**判据：`pad` 全为 0；`bytes_equal` 与 `decode_equal` 全 True；`zero_share` 落在 0.3277~0.3280。**
+
+### ⚠️ 关于 `check` 的一个已知失败
+
+在内存较小的机器上，`CHECK 2` 会在**超大张量**（`token_embd` / `output`，12.7 亿权重）上抛：
+
+```
+numpy.core._exceptions._ArrayMemoryError: Unable to allocate 9.47 GiB
+  for an array with shape (9932800, 128) and data type float64
+```
+
+**这不是转换错误** —— 那是 `mode_check` 为了做 decode 比对而做的**全量反量化**（`dq_pq2_0` 返回
+float64 数组）。`mode_build` 不用这条路径（它是流式的），所以**内存不够时可以直接进第 3 步**。
+
+若确实想跑完 `check`：需要 ≥16 GiB 空闲内存。
+
+---
+
+## 3. 打包
+
+```bash
+python -u tools/pack.py build bonsai2_27b_swift_pq2.ninfer \
+  --gguf Swift-Bonsai-2-PQ2_0.gguf \
+  --template qwen3_8_27b_huihui_abliterated.ninfer
+```
+
+PTQ1 档同理，把两个路径换成 PTQ1 的即可。
+
+**期望输出：**
+
+```
+wrote bonsai2_27b_swift_pq2.ninfer
+  total file        :   8,306,927,628 B = 7.736 GiB
+  text part produced:   7,189,880,844 B = 6.696 GiB
+  borrowed payloads :   1,116,856,537 B = 1.040 GiB {'frontend': 6, 'text': 2, 'mtp': 12, 'vision': 333}
+  objects           : 1126
+```
+
+PTQ1 档应��得到：
+
+```
+  total file        :   7,047,407,628 B = 6.563 GiB
+  text part produced:   5,930,360,844 B = 5.523 GiB
+```
+
+**这两个数字是硬判据** —— 任何偏差都说明源或模板拿错了。
+
+---
+
+## 4. 核对产出
+
+```bash
+python - <<'PY'
+import json, collections, os
+p = "bonsai2_27b_swift_pq2.ninfer"
+raw = open(p,"rb").read(16<<20)
+obj,_ = json.JSONDecoder().raw_decode(raw[16:].decode("utf-8","replace"))
+objs = obj["objects"]
+print("identity:", obj["identity"])
+print("objects :", len(objs))
+print("formats :", dict(sorted(collections.Counter(
+      o.get("format") for o in objs if o.get("kind")=="tensor").items())))
+print("layouts :", dict(collections.Counter(
+      o.get("layout") for o in objs if o.get("kind")=="tensor")))
+names = {o["name"] for o in objs}
+print("hadamard_signs :", "text/hadamard_signs" in names)
+print("hadamard_widths:", "text/hadamard_widths" in names)
+PY
+```
+
+**期望（PQ2 档）：**
+
+```
+identity: {'model_id': 'qwen3.8-27b', 'weights_id': 'groupwise-int'}
+objects : 1126
+formats : {'BF16': 582, 'PQ2_0_G128': 322, 'FP32': 97, 'Q4G64_F16S': 55,
+           'Q5G64_F16S': 54, 'W8G32_F16S': 7, 'I32': 2, 'Q6G64_F16S': 1}
+layouts : {'row-split-k128-v1': 439, 'contiguous-le-v1': 681}
+hadamard_signs : True
+hadamard_widths: True
+```
+
+`objects` 比模板多 2 —— 就是那两个 hadamard 对象。**模板里没有它们，产出里有**，
+这正是三元制品需要的。
+
+---
+
+## 5. 打包器在做什么（逐步）
+
+理解这一步，才能在出错时判断问题在哪。
+
+### 5.1 三元码原样搬运
+
+GGML 的三元 block 有两个成员（`PQ2_0` 是 `{qs}` base + fp16 scale；`PTQ1_0` 多一个
+`{qh}` high 平面），`.ninfer` 的 `row-split-k128-v1` 布局恰好是**同样三个平面**。
+所以码字**逐字节搬**，不经过浮点。
+
+**这条极其重要**：解量化再重量化会引入二次损失，而且体积红利会被吃掉。
+
+### 5.2 撤销 llama.cpp exporter 的约定
+
+源 GGUF 是 llama.cpp 生态导出的，带着三处约定，产物必须还原：
+
+```
+GDN value heads    tiled 顺序  ->  grouped 顺序
+                   按头粒度施加：perm48(head)*128 + inner
+                   ⚠️ 直接套 perm48(row) 是非双射，会静默产生重复行 + 丢失行
+                   （这类 bug 守恒一切可数之物：尺寸/行数/字节/往返无损全绿）
+
+零中心 norms       1 + w       ->  w
+                   ⚠️ 唯独 gdn/norm（ssm_norm）原样 —— 它的 raw 已经 ≈ +1
+
+ssm_a              -exp(A_log) ->  A_log
+```
+
+### 5.3 补两个 hadamard 对象
+
+源 GGUF 用 `prism.hadamard.sign_values` / `sign_widths` 承载旋转基的符号向量；
+`.ninfer` 用 `text/hadamard_signs`（28,672 个 fp32）/ `text/hadamard_widths`（3 个 int32）。
+打包器把前者翻成后者，并给每个被旋转的投影挂上 `hadamard_signs` Use 辅助。
+
+### 5.4 借 payload
+
+```
+vision       333 个 —— 源 GGUF 里没有（Bonsai 的视觉塔是单独的 mmproj.gguf）
+mtp           12 个 —— 源 GGUF 里没有（851 个张量里零个 blk.64.*）
+frontend       6 个 —— tokenizer 等
+draft_head     2 个 —— 频次短名单，同一 tokenizer 即同一名单
+共 1,116,856,537 B
+```
+
+**这几块是全生态共用的官方件**，从模板借是安全的（MTP 头与目标点积 ≥0.99966、七个 norm 逐字节相同）。
+
+---
+
+## 6. 验证方法学（**这一节比上面的步骤更值钱**）
+
+「搬运无损」类判据（源字节 == payload、往返解码一致）**对偏移错误完全盲** ——
+读错的同一批字节原样进原样出，照样全绿。
+
+真正能证伪的判据：
+
+| # | 判据 | 能抓什么 |
+|---|---|---|
+| 1 | **分布特征自证**（scale 中位数 / 全正 / `zero_share`） | 载荷整体偏移、平面错位 |
+| 2 | **跨实现互验**（两个独立解码器解同一份数据） | 单一实现的系统性误读 |
+| 3 | **负控必须存在**（假格式名必须被拒、错尺寸必须被拒） | "判据太松"导致的假通过 |
+| 4 | **行级指纹比「多重集」+ 直接比对** | 行置换 / 重复 / 丢失（尺寸守恒那类） |
+| 5 | **T>1 用例 + 引擎侧验证** | 布局 / 步长类错误（T=1 两种排布重合，测不出任何东西） |
+| 6 | **端到端数值口径用 PPL** | 采样温度 / 模板带来的错觉 |
+
+### ⚠️ PPL 的一个常见误用：拿别处的绝对值来比
+
+**PPL 跟语料强相关。** 上游文档给过一组参照值（`512/256 → 6.448742`、`32/16 → 26.049634`、
+`8/4 → 121.157720`），**那是另一份语料上的数**，和你自己量到的值**不可直接比较**。
+
+**只有同一语料下两个模型的差值才有意义。** 本仓的实测（`pplab-text`，`int8` KV，RTX 3060 12G）：
+
+| 窗口/步长 | Swift | base | 差 |
+|---|---:|---:|---:|
+| 512 / 256 | 8.073669 | 8.079208 | −0.07% |
+| 32 / 16 | 26.962015 | 26.972171 | −0.04% |
+| 8 / 4 | 148.3656 | 148.3863 | −0.01% |
+
+**你复现时应该看到同样的"差值方向"，而不是同样的绝对值。**
+
+**`zero_share` 精确落到 0.3278 是 `PQ2_0` 的格式指纹**（理论零码占比 32.776%），不是"大概的数"。
+本仓的两个制品都过了这一条。
+
+### 性能测量的坑（会直接误导判断）
+
+```
+micro-benchmark 不 flush L2 会高估；flush 过头会报出超物理上限的数
+nsys 默认不追踪 CUDA graph replay 内的 kernel      ⇒ --cuda-graph-trace=node
+内核"少干一半活"会伪装成提速                        ⇒ 必须先用 rel_l2 校验
+kernel launch 失败伪装成"快得离谱 + 全零"           ⇒ launch 后查 cudaGetLastError()
+idle 时钟让短基准严重失真                          ⇒ 短基准不可信
+报数不带任务和生成长度                              ⇒ 轮耗时才是任务无关量
+```
+
+---
+
+## 7. 已知的失败与对策
+
+| 症状 | 真因 | 对策 |
+|---|---|---|
+| `template has no object X to borrow` | 模板与映射表 schema 不一致 | 换 `groupwise-int` 的模板，别用 `nvfp4` |
+| `unmapped gdn object` / 直接中止 | 模板是 `nvfp4` 打包（投影被融合） | 同上 |
+| `Unable to allocate 9.47 GiB`（`check` 模式） | 全量反量化的 float64 数组 | 内存 ≥16 GiB，或直接跑 `build` |
+| 产出尺寸与期望不符 | 源或模板拿错 | 对 sha256 |
+| 引擎拒绝装载产物 | 方言不对（`t2_g128_fp16` vs `PQ2_0_G128`） | 见根目录 README 的兼容性表 |
+
+---
+
+## 8. 本仓实际使用的命令与结果
+
+```
+packer   tools/pack.py（NINFER_ROOT 常量重定向到本地 checkout，无功能修改）
+Python   3.11.5
+GPU      未使用（纯 CPU）
+PQ2 档   4 分钟 → 8,306,927,628 B / 7.736 GiB
+PTQ1 档  4 分钟 → 7,047,407,628 B / 6.563 GiB
+```
+
+**没有任何验证、校验、几何检查或往返证明被禁用、放宽或绕过。**
+`check` 模式在源 GGUF 上完整跑过（见第 2 节）。

SHA256SUMS

@@ -0,0 +1,2 @@
+cc54be3800099ada67165ad352450be83d28e8c4d423be9cae573a7b6e6350a0  bonsai2_27b_swift_pq2.ninfer
+cc9e890728ea7357b1d8a0797a4accdc6ca143031471a63e49c9cf6c8314b6ae  bonsai2_27b_swift_ptq1.ninfer

artifact-manifest.json

@@ -0,0 +1,91 @@
+{
+  "schema": "ninfer.artifact-manifest",
+  "schema_version": 1,
+  "release": "Swift-Bonsai-2 27B — NInfer ternary artifacts",
+  "generated": "2026-09-28T03:12:45",
+  "license": "Apache-2.0",
+  "provenance": {
+    "base_ternary": {
+      "repo": "prism-ml/Ternary-Bonsai-2-27B-gguf",
+      "license": "apache-2.0"
+    },
+    "weight_source": {
+      "repo": "ukisai/Swift-Bonsai-2-GGUF",
+      "license": "apache-2.0"
+    },
+    "geometry_base": {
+      "repo": "Qwen/Qwen3.8-27B",
+      "license": "apache-2.0"
+    },
+    "packer": {
+      "repo": "shensanshu/ninfer-ada-ternary",
+      "license": "Apache-2.0",
+      "path": "tools/pack.py"
+    },
+    "template": {
+      "repo": "Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer",
+      "license": "Apache-2.0",
+      "used_for": "object skeleton + vision/mtp/frontend/draft_head payloads only"
+    }
+  },
+  "artifacts": [
+    {
+      "filename": "bonsai2_27b_swift_pq2.ninfer",
+      "bytes": 8306927628,
+      "sha256": "cc54be3800099ada67165ad352450be83d28e8c4d423be9cae573a7b6e6350a0",
+      "identity": {
+        "model_id": "qwen3.8-27b",
+        "weights_id": "groupwise-int"
+      },
+      "container_version": 2,
+      "objects": 1126,
+      "tensors": 1120,
+      "resources": 6,
+      "formats": {
+        "BF16": 582,
+        "FP32": 97,
+        "I32": 2,
+        "PQ2_0_G128": 322,
+        "Q4G64_F16S": 55,
+        "Q5G64_F16S": 54,
+        "Q6G64_F16S": 1,
+        "W8G32_F16S": 7
+      },
+      "layouts": {
+        "contiguous-le-v1": 681,
+        "row-split-k128-v1": 439
+      },
+      "ternary_format": "PQ2_0_G128",
+      "requires_engine_dialect": "Ambolio/ninfer-4090-windows lineage (v1.0.6 / v1.0.8)"
+    },
+    {
+      "filename": "bonsai2_27b_swift_ptq1.ninfer",
+      "bytes": 7047407628,
+      "sha256": "cc9e890728ea7357b1d8a0797a4accdc6ca143031471a63e49c9cf6c8314b6ae",
+      "identity": {
+        "model_id": "qwen3.8-27b",
+        "weights_id": "groupwise-int"
+      },
+      "container_version": 2,
+      "objects": 1126,
+      "tensors": 1120,
+      "resources": 6,
+      "formats": {
+        "BF16": 582,
+        "FP32": 97,
+        "I32": 2,
+        "PTQ1_0_G128": 322,
+        "Q4G64_F16S": 55,
+        "Q5G64_F16S": 54,
+        "Q6G64_F16S": 1,
+        "W8G32_F16S": 7
+      },
+      "layouts": {
+        "contiguous-le-v1": 681,
+        "row-split-k128-v1": 439
+      },
+      "ternary_format": "PTQ1_0_G128",
+      "requires_engine_dialect": "Ambolio/ninfer-4090-windows lineage (v1.0.6 / v1.0.8)"
+    }
+  ]
+}

bonsai2_27b_swift_pq2.ninfer

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc54be3800099ada67165ad352450be83d28e8c4d423be9cae573a7b6e6350a0
+size 8306927628

bonsai2_27b_swift_ptq1.ninfer

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc9e890728ea7357b1d8a0797a4accdc6ca143031471a63e49c9cf6c8314b6ae
+size 7047407628

release.conversion.json

@@ -0,0 +1,53 @@
+{
+  "identity": {
+    "model_id": "qwen3.8-27b",
+    "weights_id": "groupwise-int"
+  },
+  "purpose": "Swift-Bonsai-2 27B ternary artifact, PQ2 + PTQ1 tiers, NInfer v2 container",
+  "packer": {
+    "name": "tools/pack.py",
+    "origin": "shensanshu/ninfer-ada-ternary (Apache-2.0)",
+    "change": "only the NINFER_ROOT default path constant was redirected; no functional change",
+    "verification_mode": "check ran to completion: pad=0 for all 8 shape combinations, bytes_equal and decode_equal true on every sampled tensor"
+  },
+  "sources": {
+    "gguf_pq2": {
+      "file": "Swift-Bonsai-2-PQ2_0.gguf",
+      "bytes": 7206168928,
+      "sha256": "5912bb739217cf25b4283a098c7b893d9baff36bdf2e72d3dbf4cb999d5633d5",
+      "from": "ukisai/Swift-Bonsai-2-GGUF"
+    },
+    "gguf_ptq1": {
+      "file": "Swift-Bonsai-2-PTQ1_0.gguf",
+      "bytes": 5946648960,
+      "sha256": "de33620b60eaf63e96449b478eb87abe9538507e3ed939da944c1ae15fe1ffc6",
+      "from": "ukisai/Swift-Bonsai-2-GGUF"
+    },
+    "template": {
+      "file": "qwen3_8_27b_huihui_abliterated.ninfer",
+      "bytes": 18210531328,
+      "sha256": "8c9f9d67a07ac97506978f6db6695d8074f78dec0fb80c4a85a8fb6fbedd7f03",
+      "from": "Barding-Defense/Qwen3.8-27B-huihui-abliterated-groupwise-int-NInfer",
+      "note": "used ONLY as skeleton/manifest + donor of vision/mtp/frontend/draft_head payloads; its text weights are discarded"
+    }
+  },
+  "outputs": {
+    "bonsai2_27b_swift_pq2.ninfer": {
+      "bytes": 8306927628,
+      "sha256": "cc54be3800099ada67165ad352450be83d28e8c4d423be9cae573a7b6e6350a0",
+      "note": "PQ2 tier, 2-bit, from gguf_pq2"
+    },
+    "bonsai2_27b_swift_ptq1.ninfer": {
+      "bytes": 7047407628,
+      "sha256": "cc9e890728ea7357b1d8a0797a4accdc6ca143031471a63e49c9cf6c8314b6ae",
+      "note": "PTQ1 tier, 1.75-bit, from gguf_ptq1"
+    }
+  },
+  "toolchain": {
+    "python": "3.11.5",
+    "numpy": "installed",
+    "torch": "CPU build",
+    "gpu_used": false
+  },
+  "generated": "2026-09-28T03:10:53"
+}

tools/MAPPING.json

@@ -0,0 +1,126 @@
+{
+  "_doc": "Bonsai 2 27B GGUF (arch qwen35) -> ninfer artifact object mapping. Every rule below was established EMPIRICALLY against a groupwise-int qwen3.8-27b artifact of the same model family, except where marked INFERRED. Rotated (hadamard-folded) matrices cannot be correlated - only byte accounting applies to them.",
+  "_verified_by": "probe_conventions.py, solve_gdn_order.py (see <WORKSPACE>\\ternary-pack\\)",
+  "_layers": {
+    "total": 64,
+    "gdn_linear_attention": [0,1,2,4,5,6,8,9,10,12,13,14,16,17,18,20,21,22,24,25,26,28,29,30,32,33,34,36,37,38,40,41,42,44,45,46,48,49,50,52,53,54,56,57,58,60,61,62],
+    "full_attention": [3,7,11,15,19,23,27,31,35,39,43,47,51,55,59,63],
+    "note": "derived: a layer is full-attention iff blk.{l}.attn_q.weight exists in the GGUF"
+  },
+  "_constants": {
+    "hidden": 5120,
+    "q_heads": 24, "kv_heads": 4, "head_dim": 256,
+    "num_k_heads": 16, "num_v_heads": 48, "v_per_k": 3, "head_k_dim": 128, "head_v_dim": 128,
+    "gdn_qkv_channels": 10240, "gdn_qk_channels": 4096, "gdn_v_channels": 6144
+  },
+
+  "_rules": [
+    {
+      "id": "norm_shift",
+      "applies_to": "every BF16/FP32 object that came from a GGUF tensor ending in '.norm.weight'",
+      "transform": "value = gguf - 1.0",
+      "exception": "text/layers/{l}/gdn/norm  <- blk.{l}.ssm_norm.weight  is copied RAW (no -1)",
+      "evidence": "cos(artifact, gguf-1) = +0.99997 .. +0.99991 for input_norm / post_attention_norm / query_norm / key_norm / final_norm; cos(artifact, gguf) = +0.99961 for gdn/norm",
+      "source": "llama.cpp conversion/qwen.py:394 -- `name.endswith(\"norm.weight\") and not name.endswith(\"linear_attn.norm.weight\")` gets +1 on the way OUT to GGUF, so ninfer (HF-form) needs -1 back, except for linear_attn.norm"
+    },
+    {
+      "id": "gdn_v_tiled_to_grouped",
+      "applies_to": "the 48-row (num_v_heads) axis of GDN tensors",
+      "transform": "t = t.reshape(3,16,*rest).transpose(1,0,*range(2,ndim+1)).reshape(shape)",
+      "direction": "GGUF stores TILED, ninfer wants GROUPED",
+      "evidence": "48x48 row matching gives a bijection with cos 0.990..0.9998; cos(A, tiled_to_grouped(B)) = +0.99587 vs +0.14814 for the other direction",
+      "source": "conversion/qwen.py:446 _LinearAttentionVReorderBase._reorder_v_heads (HF grouped -> ggml tiled)"
+    },
+    {
+      "id": "gdn_a_log",
+      "applies_to": "text/layers/{l}/gdn/a_log <- blk.{l}.ssm_a",
+      "transform": "tiled_to_grouped(log(-gguf))",
+      "evidence": "cos(sorted(artifact), sorted(log(-gguf))) = +1.00000 exactly; raw gives +0.796",
+      "source": "conversion/qwen.py:389 -- `if name.endswith(\".A_log\"): data_torch = -torch.exp(data_torch)`"
+    },
+    {
+      "id": "gdn_conv1d",
+      "applies_to": "text/layers/{l}/gdn/convolution (4,10240) <- blk.{l}.ssm_conv1d.weight ne=(4,10240)",
+      "transform": "read as (10240,4); leave channels [0:4096] alone; apply tiled_to_grouped over the 48-head axis of channels [4096:10240]; then transpose -> shape (4,10240)",
+      "evidence": "cos = +0.99504; naively keeping the order gives only +0.72253",
+      "source": "conversion/qwen.py:608-615 (.conv1d branch reorders only the V channels)"
+    },
+    {
+      "id": "attn_q_per_head_interleave",
+      "applies_to": "blk.{l}.attn_q.weight (N=12288) for full-attention layers",
+      "transform": "view as 48 chunks of 256 rows; chunks 0,2,...,46 are the 24 query heads in order; chunks 1,3,...,47 are the 24 output-gate heads in order",
+      "evidence": "INFERRED for main layers from the MTP layer, where it was VERIFIED against the artifact at cos +0.99982 per chunk (24/24 and 24/24 chunks exact). The MTP layer is a full-attention layer with identical shapes.",
+      "target_use": "attention/query_key = concat(query(6144), attn_k(1024)); attention/gate_value = concat(gate(6144), attn_v(1024))"
+    },
+    {
+      "id": "gdn_value_z",
+      "transform": "value_z = concat(tiled_to_grouped_heads(attn_qkv[4096:10240]), tiled_to_grouped_heads(attn_gate[0:6144])).  The 48-head permutation MUST be applied at HEAD granularity, because this tensor's row axis is 48 heads x 128 rows: src_row = perm48(row // 128) * 128 + row % 128",
+      "evidence": "RESOLVED 2026-09-19 by engine test (was INFERRED). ssm_conv1d's V channels are MEASURED as tiled and its rule already permutes at HEAD granularity (cos +0.99504); alpha/beta (48 rows = 48 heads, so row granularity IS head granularity) use the same permutation and measure +1.00000 / +0.99587.",
+      "bug_history": "The first pack applied perm48() straight to the 6144-row index. That is NOT a bijection over rows (perm48(1) == perm48(48) == 16), so 4064 of 6144 source rows were dropped and 2048 row fingerprints repeated -- while every size, row count and byte total stayed EXACTLY right, which is why the size reverse-check, the src==payload round trip, the byte-for-byte reconcile and the 12288-row cross-check all stayed green over it. Engine symptom: fluent-looking garbage, PPL 1,128,420 (worse than uniform over a 248,320-token vocab). Fixed by the perm_row() helper in pack.py; the v2 artifact verifies 6144/6144 distinct rows, 0 duplicated, 0 missing.",
+      "acceptance_check": "<BUILD_ROOT>\\check_row_order.py <artifact.ninfer> <Ternary-Bonsai-2-27B-PQ2_0.gguf>  -- must report 'rows DUPLICATED: 0' and 'source rows MISSING: 0' AND 'documented rule holds row-by-row: True'. NOTE: a set-membership test is NOT sufficient (every duplicated row still finds a source); compare MULTISETS and compare artifact[a] directly against the rule's named source a, never by searching for a matching fingerprint."
+    },
+    {
+      "id": "gdn_output_raw",
+      "applies_to": "text/layers/{l}/gdn/output (5120,6144) <- blk.{l}.ssm_out.weight",
+      "transform": "none",
+      "evidence": "conversion/qwen.py:617-626 -- a hadamard-FOLDED out_proj keeps the training (grouped) column order and the runtime permutes the activation instead; Bonsai's metadata carries prism.hadamard.gdn_v_grouped = 1, confirming the folded path"
+    },
+    {
+      "id": "ternary_bytes_verbatim",
+      "applies_to": "all 402 PQ2_0 / PTQ1_0 matrices",
+      "transform": "move the quantized codes byte-for-byte; do NOT dequantize and requantize",
+      "note": "these weights live in the rotated basis W'; the activation-side transform is M2's job, not the packer's"
+    }
+  ],
+
+  "text_globals": {
+    "text/token_embedding":            {"src": "token_embd.weight", "shape": [248320, 5120], "fmt": "PQ2_0_G128", "transform": "none (stored as W'; runtime inverse-applies after lookup)"},
+    "text/output_head":                {"src": "output.weight",    "shape": [248320, 5120], "fmt": "PQ2_0_G128", "transform": "none"},
+    "text/final_norm":                 {"src": "output_norm.weight", "shape": [5120], "fmt": "BF16", "transform": "raw - 1"},
+    "text/draft_head":                 {"src": "GENERATED", "shape": [131072, 5120], "fmt": "Q4G64_F16S", "note": "frequency shortlist, NOT a model weight: tools/convert/qwen3_6/common/draft_head.py materializes it from tools/freq_corpus/fixtures/ranking/ranking.train.counts.i64 + the tokenizer. Regenerate, do not copy."},
+    "text/draft_head_token_ids":       {"src": "GENERATED", "shape": [131072], "fmt": "I32", "note": "same generator"}
+  },
+
+  "per_layer_gdn": {
+    "text/layers/{l}/input_norm":            {"src": "blk.{l}.attn_norm.weight",           "shape": [5120],       "fmt": "BF16",  "transform": "raw - 1"},
+    "text/layers/{l}/post_attention_norm":   {"src": "blk.{l}.post_attention_norm.weight",  "shape": [5120],       "fmt": "BF16",  "transform": "raw - 1"},
+    "text/layers/{l}/mlp/gate_up":           {"src": "concat(blk.{l}.ffn_gate.weight, blk.{l}.ffn_up.weight) along rows", "shape": [34816, 5120], "fmt": "TERNARY", "transform": "ternary_bytes_verbatim; concat order VERIFIED at cos +0.99982 on the MTP analogue"},
+    "text/layers/{l}/mlp/down":              {"src": "blk.{l}.ffn_down.weight",            "shape": [5120, 17408], "fmt": "TERNARY", "transform": "ternary_bytes_verbatim"},
+    "text/layers/{l}/gdn/query_key":         {"src": "blk.{l}.attn_qkv.weight rows 0:4096", "shape": [4096, 5120], "fmt": "TERNARY", "transform": "none (q 2048 + k 2048, no V tiling on the k-head axis)"},
+    "text/layers/{l}/gdn/value_z":           {"src": "rows 4096:10240 of blk.{l}.attn_qkv.weight  +  blk.{l}.attn_gate.weight", "shape": [12288, 5120], "fmt": "TERNARY", "transform": "gdn_value_z"},
+    "text/layers/{l}/gdn/output":            {"src": "blk.{l}.ssm_out.weight",              "shape": [5120, 6144], "fmt": "TERNARY", "transform": "none"},
+    "text/layers/{l}/gdn/convolution":       {"src": "blk.{l}.ssm_conv1d.weight",           "shape": [4, 10240],   "fmt": "BF16",  "transform": "gdn_conv1d"},
+    "text/layers/{l}/gdn/norm":              {"src": "blk.{l}.ssm_norm.weight",             "shape": [128],        "fmt": "BF16",  "transform": "RAW (no -1!)"},
+    "text/layers/{l}/gdn/a_projection":      {"src": "blk.{l}.ssm_alpha.weight",            "shape": [48, 5120],   "fmt": "BF16",  "transform": "gdn_v_tiled_to_grouped"},
+    "text/layers/{l}/gdn/b_projection":      {"src": "blk.{l}.ssm_beta.weight",             "shape": [48, 5120],   "fmt": "BF16",  "transform": "gdn_v_tiled_to_grouped"},
+    "text/layers/{l}/gdn/a_log":             {"src": "blk.{l}.ssm_a",                       "shape": [48],         "fmt": "FP32",  "transform": "gdn_a_log"},
+    "text/layers/{l}/gdn/dt_bias":           {"src": "blk.{l}.ssm_dt.bias",                 "shape": [48],         "fmt": "FP32",  "transform": "gdn_v_tiled_to_grouped (pure permutation)"}
+  },
+
+  "per_layer_attention": {
+    "text/layers/{l}/input_norm":            {"src": "blk.{l}.attn_norm.weight",           "shape": [5120],       "fmt": "BF16",  "transform": "raw - 1"},
+    "text/layers/{l}/post_attention_norm":   {"src": "blk.{l}.post_attention_norm.weight",  "shape": [5120],       "fmt": "BF16",  "transform": "raw - 1"},
+    "text/layers/{l}/mlp/gate_up":           {"src": "concat(blk.{l}.ffn_gate.weight, blk.{l}.ffn_up.weight)", "shape": [34816, 5120], "fmt": "TERNARY", "transform": "ternary_bytes_verbatim"},
+    "text/layers/{l}/mlp/down":              {"src": "blk.{l}.ffn_down.weight",             "shape": [5120, 17408], "fmt": "TERNARY", "transform": "ternary_bytes_verbatim"},
+    "text/layers/{l}/attention/query_key":   {"src": "attn_q (de-interleaved) 6144 rows + blk.{l}.attn_k.weight 1024 rows", "shape": [7168, 5120], "fmt": "TERNARY", "transform": "attn_q_per_head_interleave"},
+    "text/layers/{l}/attention/gate_value":  {"src": "attn_q (odd chunks) 6144 rows + blk.{l}.attn_v.weight 1024 rows",     "shape": [7168, 5120], "fmt": "TERNARY", "transform": "attn_q_per_head_interleave"},
+    "text/layers/{l}/attention/output":      {"src": "blk.{l}.attn_output.weight",          "shape": [5120, 6144], "fmt": "TERNARY", "transform": "ternary_bytes_verbatim"},
+    "text/layers/{l}/attention/query_norm":  {"src": "blk.{l}.attn_q_norm.weight",          "shape": [256],        "fmt": "BF16",  "transform": "raw - 1"},
+    "text/layers/{l}/attention/key_norm":    {"src": "blk.{l}.attn_k_norm.weight",          "shape": [256],        "fmt": "BF16",  "transform": "raw - 1"}
+  },
+
+  "_counts": {
+    "artifact_objects_total": 1124,
+    "text": 773, "mtp": 12, "vision": 333, "frontend_resources": 6,
+    "gguf_tensors_total": 851,
+    "gguf_breakdown": "48 GDN layers x 14 + 16 attention layers x 11 + 3 globals (token_embd, output, output_norm) = 851",
+    "note": "text/draft_head + draft_head_token_ids have NO GGUF source (generated); vision has no source in this GGUF either (Bonsai ships a separate mmproj)"
+  },
+
+  "_unresolved": [
+    "vision/* (333 objects): Bonsai's vision tower lives in Ternary-Bonsai-2-27B-mmproj-Q8_0.gguf (Q8_0), while the template expects Q4G64/Q5G64/Q6G64/BF16. Either convert the mmproj or borrow the template's vision payloads (same official vision tower) - needs a decision.",
+    "text/draft_head + draft_head_token_ids: run the frequency-shortlist generator (needs tools/freq_corpus fixture present in the fork).",
+    "all 402 ternary matrices are in the rotated basis, so NONE of them can be verified by correlation; only byte accounting, decode round-trip equality and the engine's load test apply.",
+    "gdn/value_z's tiled->grouped choice is inferred (see rule) - single line to flip if the engine disagrees."
+  ]
+}

tools/README.md

@@ -0,0 +1,77 @@
+# tools/ — 打包器与验证脚本
+
+**许可：Apache-2.0。** 来源见根目录 `NOTICE`。
+
+这些文件原样取自 [`shensanshu/ninfer-ada-ternary`](https://www.modelscope.cn/models/shensanshu/ninfer-ada-ternary)
+（Apache-2.0），**未做功能修改**。
+
+唯一的编辑是**脱敏**：源码顶部的两个默认路径常量（`NINFER_ROOT` 指向作者的开发机、
+`TEMPLATE` 指向他的模板文件），以及 `MAPPING.json` 的 `_verified_by` 说明，
+一律替换成中性占位符 **`<NINFER_ROOT>`** 与 **`<TEMPLATE>`**；
+`verify/` 下 4 个脚本（`check_assembly` / `check_embedding` / `check_row_order` / `gemm_oracle`）的 `sys.path.insert(...)` 行做了同样处理；`oracle_rot.py` 不 import 那套模块，本来就没有这行。
+**没有任何逻辑被改动。**
+
+## ★ 用之前先处理这两个占位符
+
+`pack.py` 顶部：
+
+```python
+NINFER_ROOT = r"<NINFER_ROOT>"      # 指到含 tools/artifact 的源码 checkout
+TEMPLATE    = r"<TEMPLATE>"         # 指到 groupwise-int 的模板 .ninfer
+GGUF        = r"<WORKSPACE>\Ternary-Bonsai-2-27B-PQ2_0.gguf"   # 作者留的，同样要覆盖
+```
+
+- **`GGUF` 与 `TEMPLATE` 可以用命令行覆盖，不必改源码：**
+  ```bash
+  python -u pack.py build out.ninfer --gguf 你的.gguf --template 你的模板.ninfer
+  # 或环境变量 NINFER_TERNARY_GGUF / NINFER_TERNARY_TEMPLATE
+  ```
+- **`NINFER_ROOT` 只能改源码常量** —— 它只用来 `import tools.artifact` 那一组模块。
+  需要的最小结构：
+  ```
+  <NINFER_ROOT>/tools/artifact/{__init__.py, container.py, layouts.py, numeric.py}
+  ```
+  来源是 `Ambolio/ninfer-4090-windows` 血统的树（或任何含这套 `tools/artifact` 的 checkout）。
+
+---
+| 文件 | 作用 |
+|---|---|
+| `pack.py` | GGUF → `.ninfer` 的三元打包器。自写 GGUF 读取器；把 402 个三元矩阵的码字**逐字节搬运**，绝不反量化再量化 |
+| `MAPPING.json` | 逐张量映射表（对象名 / 形状 / 格式 / 规则），每条都注明证据来源 |
+| `verify/check_row_order.py` | 行级指纹的**多重集**比对 —— 能抓行置换/重复/丢失（这类 bug 守恒一切可数之物） |
+| `verify/check_assembly.py` | 全量装配审计 |
+| `verify/oracle_rot.py` | Hadamard 旋转的独立 oracle |
+| `verify/gemm_oracle.py` | GEMM 的独立 oracle |
+| `verify/check_embedding.py` | embedding 路径核对 |
+
+## 怎么用
+
+```bash
+python -u pack.py check --gguf <源.gguf> --template <模板.ninfer>
+# 只验证，不写文件。期望：8 个形状组合 pad=0，抽样张量 bytes_equal + decode_equal 全 True
+
+python -u pack.py build <out.ninfer> --gguf <源.gguf> --template <模板.ninfer>
+# 真打包
+```
+
+**`--template` 是必需的。** 它不只是载荷来源 —— 打包器会**遍历模板自己的对象名表**逐个映射，
+所以模板必须与目标制品同 schema（`identity.weights_id == "groupwise-int"`）。
+`nvfp4` 打包的模板用不了（它把投影融合了，名字不在映射表里，会直接中止）。
+
+**依赖：** Python 3.11+、numpy、torch（**CPU 版即可，不需要 GPU**）。
+
+## 一个必须记住的判据陷阱
+
+「搬运无损」类判据（源字节 == payload、往返解码一致）对**偏移错误完全盲** ——
+读错的同一批字节原样进原样出，照样全绿。
+
+真正有用的旁证是**分布特征**：
+
+| 指标 | 正确读取 | 偏移错误时 |
+|---|---|---|
+| scale 高位字节种数 | 11~32 / 256（紧致） | 接近 250 / 256（近似均匀） |
+| scale 是否全正 | 负 0 个 | 出现负值 |
+| 非有限（NaN/Inf） | 0 | 出现 NaN |
+| `zero_share` | **0.3277~0.3280** | 0.318~0.323 散乱 |
+
+**`zero_share` 精确落到 0.3278 是 `PQ2_0` 的格式指纹**，不是"大概的数"。

tools/pack.py

@@ -0,0 +1,958 @@
+#!/usr/bin/env python3
+"""Bonsai 2 27B (arch qwen35) GGUF -> ninfer `.ninfer` ternary artifact  (M1-D packer).
+
+Mapping rules are NOT derived here; they come from MAPPING.json (which records the evidence
+for each).  This script owns: a seek-based GGUF reader; an INDEPENDENT reference decoder for
+the two Prism ternary types ported from ggml/src/ggml-quants.c; byte-for-byte ternary plane
+assembly plus its exact inverse (used as the losslessness proof); the inventory built from
+the template artifact's own object list; and a streaming writer with borrowed payloads.
+
+Borrowed payloads (deliberate, reported in the run summary):
+  vision/*    333 -- Bonsai ships its vision tower as a separate mmproj GGUF; the template's
+                     tower is the same official one and is not read during text decode.
+  mtp/*        12 -- Bonsai's GGUF has NO MTP head (851 tensors, zero `blk.64.*`).  The
+                     template's head is the same official Qwen3.8-27B head: all twelve
+                     tensors matched at cosine >= 0.99966 with the seven norms BIT-IDENTICAL.
+  frontend/*    6 -- tokenizer and friends.
+  text/draft_head(+_token_ids) -- frequency shortlist; same tokenizer => same shortlist.
+
+Modes
+  check            geometry + decode + byte-round-trip proofs (no writes)
+  layer3 <out>     minimal artifact: frontend + sign table + one full-attention layer
+  build  <out>     full text model
+
+Paths (both may be overridden; the constants in this file are only defaults)
+  --gguf     <p>   the Bonsai 2 27B PQ2_0 GGUF          (env NINFER_TERNARY_GGUF)
+  --template <p>   a **groupwise-int** qwen3.8-27b artifact
+                   (env NINFER_TERNARY_TEMPLATE)       -- see README FAQ
+  The template is the skeleton/manifest this packer walks, not just a donor of the
+  vision/MTP payloads: its object NAMES must match the mapping table, so the `nvfp4`
+  packing (fused gdn/a_b_projection, gdn/query_key_value_z, attention/query_key_gate_value)
+  is rejected up front with instructions on how to produce the right one.
+
+Interpreter: <PYTHON>\\python.exe
+"""
+from __future__ import annotations
+
+import json
+import os
+import struct
+import sys
+from collections import Counter
+from pathlib import Path
+
+import numpy as np
+
+NINFER_ROOT = r"<NINFER_ROOT>"
+if NINFER_ROOT not in sys.path:
+    sys.path.insert(0, NINFER_ROOT)
+
+from tools.artifact import (  # noqa: E402
+    Artifact,
+    ArtifactIdentity,
+    ArtifactWriter,
+    ResourceSpec,
+    TensorSpec,
+    encode_direct,
+    row_split_geometry,
+)
+
+TEMPLATE = r"<TEMPLATE>"
+GGUF = r"<WORKSPACE>\Ternary-Bonsai-2-27B-PQ2_0.gguf"
+
+# The template must be the **groupwise-int** packing.  It is not merely a donor of the
+# vision/MTP payloads: this packer walks the template's OWN object list and maps every name
+# through a closed table, so a template with different (fused) names cannot be consumed.
+# The sibling packing `nvfp4` fuses the projections (gdn/a_b_projection,
+# gdn/query_key_value_z, attention/query_key_gate_value) and therefore aborts with
+# "unmapped gdn object ...".  Both packings are produced from the same model by different
+# converters in tools/convert/qwen3_8_27b/.
+TEMPLATE_SCHEMA = "groupwise-int"
+
+_TEMPLATE_HELP = """\
+模板 schema 不对：pack.py 需要 **groupwise-int** 的 qwen3.8-27b 制品。
+(the template must be the groupwise-int packing, not nvfp4)
+
+  你给的模板  : {path}
+  它的 schema : weights_id={got!r}
+  需要的      : weights_id={want!r}
+
+怎么拿到正确的模板（二选一）：
+  A) 用基树自带的转换器自己产一份 —— groupwise-int 路径，**不是** convert_nvfp4：
+       python3 -m tools.convert.qwen3_8_27b.convert \\
+         --model <Qwen3.8-27B 权重目录> \\
+         --dflash2-model <Qwen3.8-27B-DFlash2 目录> \\
+         --out <out.ninfer>
+     （convert_nvfp4 产出 nvfp4 schema，其 GDN/attention 为**融合命名**：
+       text/layers/N/gdn/a_b_projection、gdn/query_key_value_z、attention/query_key_gate_value
+       —— 这些名字不在本脚本的映射表里，必然中止。）
+  B) 任何 weights_id=groupwise-int 的 qwen3.8-27b 制品都可以当模板。
+
+自检（满足任一条即为正确）：
+  1) 该制品 identity.weights_id == 'groupwise-int'
+  2) text/layers/3/ 下是 attention/query_key 与 attention/gate_value **两个**对象
+     （若只有单个 attention/query_key_gate_value ⇒ nvfp4 版，用不了）
+"""
+
+_SCHEMA_HINT = ("\n  hint: 模板 schema 不匹配。本脚本只认 weights_id=groupwise-int 的模板；"
+                "nvfp4 模板的融合命名（gdn/a_b_projection、gdn/query_key_value_z、"
+                "attention/query_key_gate_value）不在映射表里。见 README FAQ / --template。")
+
+T_PQ2_0, T_PTQ1_0, T_F32, T_BF16 = 142, 143, 0, 30
+FMT = {T_PQ2_0: "PQ2_0_G128", T_PTQ1_0: "PTQ1_0_G128"}
+HIDDEN, V_HEADS, V_HEAD_DIM = 5120, 48, 128
+QK_ROWS, V_ROWS = 4096, 6144
+SIGN_WIDTHS = [5120, 6144, 17408]
+FIXED = {0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8}
+
+
+# ---------------------------------------------------------------------------
+class Gguf:
+    def __init__(self, path: str):
+        self.f = open(path, "rb")
+        self.f.seek(0, 2)
+        self.size = self.f.tell()
+        self.f.seek(0)
+        if self._raw(4) != b"GGUF":
+            raise SystemExit("not a GGUF file")
+        self.version = self._u32()
+        self.n_tensors = self._u64()
+        self.n_kv = self._u64()
+        self.kv: dict[str, object] = {}
+        for _ in range(self.n_kv):
+            k = self._str()
+            self.kv[k] = self._value(self._u32())
+        self.kv_end = self.f.tell()
+        self.tensor: dict[str, tuple[list[int], int, int]] = {}
+        order = []
+        for _ in range(self.n_tensors):
+            name = self._str()
+            ne = [self._u64() for _ in range(self._u32())]
+            tt = self._u32()
+            off = self._u64()
+            self.tensor[name] = (ne, tt, off)
+            order.append((off, name))
+        # header_end is the end of the TENSOR INFO LIST, not the end of the KV block.
+        # Recording it before this loop (as an earlier revision did) shifts data_start down
+        # by the size of the list -- ~50 KB in this file -- so every payload read comes from
+        # the wrong offset, while names/shapes/types still parse perfectly and a
+        # self-consistent byte round trip still passes.  That is a silent, maximally
+        # misleading failure: probe_gguf_types.py puts this file's header end at
+        # 11,120,982 and the reader must agree.
+        self.header_end = self.f.tell()
+        self.alignment = int(self.kv.get("general.alignment", 32))
+        self.data_start = -(-self.header_end // self.alignment) * self.alignment
+        order.sort()
+        self.tbytes: dict[str, int] = {}
+        for i, (off, name) in enumerate(order):
+            nxt = order[i + 1][0] if i + 1 < len(order) else (self.size - self.data_start)
+            self.tbytes[name] = nxt - off
+        self._cache: dict[str, bytes] = {}
+
+    def _raw(self, n):
+        b = self.f.read(n)
+        if len(b) != n:
+            raise EOFError(f"short read of {n}")
+        return b
+
+    def _u32(self):
+        return struct.unpack("<I", self._raw(4))[0]
+
+    def _u64(self):
+        return struct.unpack("<Q", self._raw(8))[0]
+
+    def _str(self):
+        return self._raw(self._u64()).decode("utf-8", "replace")
+
+    def _value(self, t):
+        if t in (0, 1, 7):
+            return self._raw(1)[0]
+        if t in (2, 3):
+            return struct.unpack("<h", self._raw(2))[0]
+        if t == 4:
+            return struct.unpack("<I", self._raw(4))[0]
+        if t == 5:
+            return struct.unpack("<i", self._raw(4))[0]
+        if t == 6:
+            return struct.unpack("<f", self._raw(4))[0]
+        if t == 8:
+            return self._str()
+        if t in (10, 11):
+            return struct.unpack("<q", self._raw(8))[0]
+        if t == 12:
+            return struct.unpack("<d", self._raw(8))[0]
+        if t == 9:
+            et, n = self._u32(), self._u64()
+            if et == 8:
+                return [self._str() for _ in range(n)]
+            if et == 6:
+                return list(struct.unpack("<%df" % n, self._raw(4 * n)))
+            if et in (0, 1, 7):
+                return list(self._raw(n))
+            if et in (2, 3):
+                return list(struct.unpack("<%dh" % n, self._raw(2 * n)))
+            if et == 4:
+                return list(struct.unpack("<%dI" % n, self._raw(4 * n)))
+            if et == 5:
+                return list(struct.unpack("<%di" % n, self._raw(4 * n)))
+            self.f.seek(FIXED[et] * n, 1)
+            return f"<{n} values>"
+        raise ValueError(f"gguf value type {t}")
+
+    def payload(self, name: str) -> bytes:
+        if name not in self._cache:
+            _ne, _tt, off = self.tensor[name]
+            self.f.seek(self.data_start + off)
+            self._cache[name] = self._raw(self.tbytes[name])
+        return self._cache[name]
+
+    def tinfo(self, name):
+        ne, tt, _ = self.tensor[name]
+        return ne, tt
+
+    def row_shape(self, name) -> tuple[int, int]:
+        """(n_rows, k) in GGUF row order, plus the number of weights."""
+        ne, _tt = self.tinfo(name)
+        if len(ne) != 2:
+            raise SystemExit(f"{name}: expected rank 2, got {ne}")
+        return ne[1], ne[0]
+
+    def blocks(self, name):
+        """(n_rows, groups_per_row, block_bytes, row_bytes, raw)."""
+        n, k = self.row_shape(name)
+        ne, tt = self.tinfo(name)
+        block = 28 if tt == T_PTQ1_0 else 34
+        gpr = k // 128
+        raw = self.payload(name)
+        if len(raw) != n * gpr * block:
+            raise SystemExit(f"{name}: {len(raw)} != {n}*{gpr}*{block}")
+        return n, gpr, block, gpr * block, raw
+
+    def row_fn(self, name):
+        n, gpr, block, rb, raw = self.blocks(name)
+        return lambda i: raw[i * rb:(i + 1) * rb]
+
+
+# ---------------------------------------------------------------------------
+# Reference decoders -- independent ports of ggml/src/ggml-quants.c
+# ---------------------------------------------------------------------------
+def dq_pq2_0(raw: bytes) -> np.ndarray:
+    qs = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 34)
+    d = qs[:, 0:2].copy().view(np.float16).astype(np.float32).reshape(-1, 1)
+    j = np.arange(128)
+    q = (qs[:, 2:34][:, j // 4] >> (2 * (j % 4))) & 0x03
+    return ((q.astype(np.int32) - 1) * d).reshape(-1)
+
+
+def dq_ptq1_0(raw: bytes) -> np.ndarray:
+    blk = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 28)
+    pow3 = (1, 3, 9, 27, 81, 243)
+    g = blk.shape[0]
+    d = blk[:, 26:28].copy().view(np.float16).astype(np.float32).reshape(-1)
+    qs, qh = blk[:, 0:24], blk[:, 24:26]
+    vals = np.empty((g, 120), dtype=np.float32)
+    col, j = 0, 0
+    for c in (32, 16, 8):                      # c=32 emits nothing: 0 + 32 > 24
+        while j + c <= 24:
+            for n in range(5):
+                prod = (qs[:, j:j + c].astype(np.uint16) * pow3[n]) & 0xFF
+                vals[:, col:col + c] = ((prod.astype(np.uint16) * 3) >> 8).astype(np.float32)
+                col += c
+            j += c
+    if col != 120:
+        raise SystemExit(f"ptq1_0 qs walk emitted {col}, expected 120")
+    tail = np.empty((g, 8), dtype=np.float32)
+    col = 0
+    for n in range(4):
+        prod = (qh.astype(np.uint16) * pow3[n]) & 0xFF
+        for h in range(2):
+            tail[:, col] = ((prod[:, h].astype(np.uint16) * 3) >> 8).astype(np.float32)
+            col += 1
+    out = np.concatenate([vals, tail], axis=1)
+    return ((out - 1.0) * d[:, None]).reshape(-1)
+
+
+DEQUANT = {T_PQ2_0: dq_pq2_0, T_PTQ1_0: dq_ptq1_0}
+
+
+def read_direct(g: Gguf, name: str) -> np.ndarray:
+    ne, tt = g.tinfo(name)
+    raw = g.payload(name)
+    if tt == T_F32:
+        a = np.frombuffer(raw, dtype="<f4").astype(np.float32)
+    elif tt == T_BF16:
+        a = (np.frombuffer(raw, dtype="<u2").astype(np.uint32) << 16).view(np.float32)
+    else:
+        raise SystemExit(f"{name}: type {tt} is not F32/BF16")
+    return a.reshape(tuple(reversed(ne))) if len(ne) > 1 else a.astype(np.float32)
+
+
+# ---------------------------------------------------------------------------
+# Ternary plane assembly, byte for byte, and its inverse
+# ---------------------------------------------------------------------------
+def block_to_planes(fmt, blk):
+    if fmt == "PTQ1_0_G128":
+        return blk[0:24], blk[24:26], blk[26:28]
+    if fmt == "PQ2_0_G128":
+        return blk[2:34], b"", blk[0:2]
+    raise ValueError(fmt)
+
+
+def planes_to_block(fmt, base, high, scale):
+    return base + high + scale if fmt == "PTQ1_0_G128" else scale + base
+
+
+def assemble_ternary(fmt, shape, row_fn) -> bytes:
+    """row_fn(i) -> the raw GGML block bytes for destination row i."""
+    n, k = shape
+    geo = row_split_geometry(fmt, shape)
+    gpr, bb, hb = geo.groups_per_row, geo.base_bytes_per_group, geo.high_bytes_per_group
+    block = bb + hb + 2
+    out = bytearray(geo.payload_bytes)
+    for i in range(n):
+        row = row_fn(i)
+        if len(row) != gpr * block:
+            raise SystemExit(f"row {i}: {len(row)} != {gpr * block}")
+        for sel in range(gpr):
+            base, high, scale = block_to_planes(fmt, row[sel * block:(sel + 1) * block])
+            o = geo.base_offset + i * geo.base_row_bytes + sel * bb
+            out[o:o + bb] = base
+            if hb:
+                o = geo.high_offset + i * geo.high_row_bytes + sel * hb
+                out[o:o + hb] = high
+            o = geo.scale_offset + i * geo.scale_row_bytes + sel * 2
+            out[o:o + 2] = scale
+    return bytes(out)
+
+
+def disassemble_ternary(fmt, shape, payload: bytes) -> bytes:
+    """Inverse of assemble_ternary: rebuild the contiguous GGML block stream."""
+    n, k = shape
+    geo = row_split_geometry(fmt, shape)
+    gpr, bb, hb = geo.groups_per_row, geo.base_bytes_per_group, geo.high_bytes_per_group
+    out = bytearray()
+    for i in range(n):
+        for sel in range(gpr):
+            o = geo.base_offset + i * geo.base_row_bytes + sel * bb
+            base = payload[o:o + bb]
+            high = b""
+            if hb:
+                o = geo.high_offset + i * geo.high_row_bytes + sel * hb
+                high = payload[o:o + hb]
+            o = geo.scale_offset + i * geo.scale_row_bytes + sel * 2
+            out += planes_to_block(fmt, base, high, payload[o:o + 2])
+    return bytes(out)
+
+
+# ---------------------------------------------------------------------------
+# Non-ternary transforms
+# ---------------------------------------------------------------------------
+def tiled_to_grouped(t: np.ndarray, groups: int = 3) -> np.ndarray:
+    """GGUF TILED (3,16) -> ninfer GROUPED (16,3) on the leading 48-head axis."""
+    shape = t.shape
+    return (t.reshape(groups, shape[0] // groups, *shape[1:])
+             .transpose(1, 0, *range(2, len(shape) + 1))
+             .reshape(shape))
+
+
+def bf16_payload(a: np.ndarray) -> bytes:
+    import torch
+    return encode_direct(torch.from_numpy(np.ascontiguousarray(a, dtype=np.float32))
+                         .to(torch.bfloat16), "BF16")
+
+
+def fp32_payload(a) -> bytes:
+    import torch
+    return encode_direct(torch.from_numpy(np.ascontiguousarray(a, dtype=np.float32)), "FP32")
+
+
+def i32_payload(a) -> bytes:
+    import torch
+    return encode_direct(torch.from_numpy(np.ascontiguousarray(a, dtype=np.int32)), "I32")
+
+
+# ---------------------------------------------------------------------------
+# Inventory (built from the template, never assumed)
+# ---------------------------------------------------------------------------
+def _weights_id(identity):
+    """Pull weights_id out of the template manifest's identity block."""
+    if isinstance(identity, dict):
+        for k in ("weights_id", "weightsId", "weights"):
+            v = identity.get(k)
+            if isinstance(v, str):
+                return v
+    return None
+
+
+def load_template():
+    with open(TEMPLATE, "rb") as f:
+        f.seek(16)
+        blob = f.read(8 << 20)
+    obj, _ = json.JSONDecoder().raw_decode(blob.decode("utf-8", "replace"))
+    identity, objects = obj["identity"], obj["objects"]
+    got = _weights_id(identity)
+    if got != TEMPLATE_SCHEMA:
+        # Fail HERE, with an actionable message, instead of 200 lines later on an
+        # "unmapped gdn object" that does not say what to do about it.
+        raise SystemExit(_TEMPLATE_HELP.format(path=TEMPLATE, got=got, want=TEMPLATE_SCHEMA))
+    return identity, objects
+
+
+def layer_kind(objs) -> dict[int, str]:
+    kind: dict[int, str] = {}
+    for o in objs:
+        p = o["name"].split("/")
+        if len(p) > 3 and p[0] == "text" and p[1] == "layers":
+            l = int(p[2])
+            kind.setdefault(l, "attn" if p[3] == "attention" else "gdn")
+    return kind
+
+
+# Target formats for the NEW artifact.  The template's own formats describe the
+# groupwise-int artifact and must NOT be reused: the packer replaces all 402 ternary
+# matrices and re-encodes the norms, so the writer would otherwise validate every produced
+# payload against the wrong geometry (CHECK 3 caught exactly this).
+TERNARY_SUFFIXES = frozenset((
+    "mlp/gate_up", "mlp/down",
+    "attention/query_key", "attention/gate_value", "attention/output",
+    "gdn/query_key", "gdn/value_z", "gdn/output",
+))
+BF16_SUFFIXES = frozenset((
+    "input_norm", "post_attention_norm",
+    "attention/query_norm", "attention/key_norm",
+    "gdn/norm", "gdn/convolution", "gdn/a_projection", "gdn/b_projection",
+))
+FP32_SUFFIXES = frozenset(("gdn/a_log", "gdn/dt_bias"))
+
+SIGN_OBJECTS = (
+    ("text/hadamard_signs", (28672,), "FP32"),
+    ("text/hadamard_widths", (3,), "I32"),
+)
+
+
+def build_specs(p):
+    """Ordered specs for the NEW artifact.
+
+    Template objects keep their order, shapes and borrowed formats, but every produced
+    tensor takes its TARGET format; the two Hadamard sign-table objects are appended.
+    """
+    specs = []
+    for o in p.objects:
+        if o["kind"] == "tensor":
+            fmt, layout = p.target_format(o["name"])
+            specs.append(TensorSpec(o["name"], tuple(o["shape"]), fmt, layout))
+        else:
+            specs.append(ResourceSpec(o["name"], o["encoding"], o["bytes"]))
+    for name, shape, fmt in SIGN_OBJECTS:
+        specs.append(TensorSpec(name, shape, fmt, "contiguous-le-v1"))
+    return specs
+
+
+# ---------------------------------------------------------------------------
+class Packer:
+    def __init__(self, g: Gguf):
+        self.g = g
+        raw_identity, self.objects = load_template()
+        self.identity = ArtifactIdentity(raw_identity["model_id"], raw_identity["weights_id"])
+        self._by_name = {o["name"]: o for o in self.objects}
+        self.kind = layer_kind(self.objects)
+        self._signs = None
+
+    # -- helpers ---------------------------------------------------------
+    def rel(self, name: str, l: int) -> str:
+        return name.replace("{l}", str(l))
+
+    def fmt_of(self, gguf_name: str) -> str:
+        _ne, tt = self.g.tinfo(gguf_name)
+        if tt not in FMT:
+            raise SystemExit(f"{gguf_name}: type {tt} is not ternary")
+        return FMT[tt]
+
+    def target_format(self, name: str) -> tuple[str, str]:
+        """(format, layout) this object carries in the NEW artifact."""
+        if name == "text/hadamard_signs":
+            return "FP32", "contiguous-le-v1"
+        if name == "text/hadamard_widths":
+            return "I32", "contiguous-le-v1"
+        if name == "text/token_embedding":
+            return self.fmt_of("token_embd.weight"), "row-split-k128-v1"
+        if name == "text/output_head":
+            return self.fmt_of("output.weight"), "row-split-k128-v1"
+        if name == "text/final_norm":
+            return "BF16", "contiguous-le-v1"
+
+        parts = name.split("/")
+        if len(parts) > 3 and parts[0] == "text" and parts[1] == "layers":
+            suffix = "/".join(parts[3:])
+            pre = f"blk.{int(parts[2])}."
+            if suffix in TERNARY_SUFFIXES:
+                if suffix == "mlp/gate_up":
+                    return self.fmt_of(pre + "ffn_gate.weight"), "row-split-k128-v1"
+                if suffix == "mlp/down":
+                    return self.fmt_of(pre + "ffn_down.weight"), "row-split-k128-v1"
+                if suffix in ("attention/query_key", "attention/gate_value"):
+                    return self.fmt_of(pre + "attn_q.weight"), "row-split-k128-v1"
+                if suffix == "attention/output":
+                    return self.fmt_of(pre + "attn_output.weight"), "row-split-k128-v1"
+                if suffix in ("gdn/query_key", "gdn/value_z"):
+                    return self.fmt_of(pre + "attn_qkv.weight"), "row-split-k128-v1"
+                if suffix == "gdn/output":
+                    return self.fmt_of(pre + "ssm_out.weight"), "row-split-k128-v1"
+            if suffix in BF16_SUFFIXES:
+                return "BF16", "contiguous-le-v1"
+            if suffix in FP32_SUFFIXES:
+                return "FP32", "contiguous-le-v1"
+
+        # everything else (mtp/*, vision/*, draft_head*) is BORROWED: keep the template's
+        o = self._by_name.get(name)
+        if o is None:
+            raise SystemExit(f"no template object and no producer for {name}")
+        return o["format"], o["layout"]
+
+    def fused(self, entries, shape) -> bytes:
+        """entries: list of (gguf_name, row_index); all sources must share one format."""
+        fmts = {self.fmt_of(n) for n, _ in entries}
+        if len(fmts) != 1:
+            raise SystemExit(f"fused tensor mixes formats: {fmts}")
+        fmt = fmts.pop()
+        srcs = {}
+        for n, _ in entries:
+            if n not in srcs:
+                nrows, _gpr, _blk, rb, raw = self.g.blocks(n)
+                srcs[n] = (rb, raw)
+
+        def row_fn(i):
+            n, r = entries[i]
+            rb, raw = srcs[n]
+            return raw[r * rb:(r + 1) * rb]
+
+        return assemble_ternary(fmt, shape, row_fn)
+
+    def direct_ternary(self, gguf_name: str, shape) -> bytes:
+        return assemble_ternary(self.fmt_of(gguf_name), shape, self.g.row_fn(gguf_name))
+
+    def signs(self):
+        if self._signs is None:
+            vals = self.g.kv["prism.hadamard.sign_values"]
+            widths = list(self.g.kv["prism.hadamard.sign_widths"])
+            arr = np.asarray(vals, dtype=np.float32)
+            if arr.size != 28672 or not np.all(np.abs(arr) == 1.0):
+                raise SystemExit("sign table is not 28672 strictly-+-1 values")
+            if widths != SIGN_WIDTHS or sum(widths) != arr.size:
+                raise SystemExit(f"sign_widths mismatch: {widths}")
+            self._signs = (arr, widths)
+        return self._signs
+
+    @staticmethod
+    def payload_bytes(spec) -> int | None:
+        """Expected payload size for a template object spec, or None when not computable."""
+        if spec["kind"] != "tensor":
+            return None
+        layout = spec.get("layout")
+        if layout == "row-split-k128-v1":
+            return row_split_geometry(spec["format"], tuple(spec["shape"])).payload_bytes
+        if layout == "contiguous-le-v1":
+            wb = {"BF16": 2, "FP32": 4, "I32": 4}[spec["format"]]
+            return int(np.prod(spec["shape"])) * wb
+        return None
+
+    # -- producers -------------------------------------------------------
+    def produce(self, name: str):
+        """Return the payload bytes for a text/* object, or None to borrow it."""
+        p = name.split("/")
+
+        if name == "text/hadamard_signs":
+            return fp32_payload(self.signs()[0])
+        if name == "text/hadamard_widths":
+            return i32_payload(self.signs()[1])
+
+        if name == "text/token_embedding":
+            return self.direct_ternary("token_embd.weight", (248320, HIDDEN))
+        if name == "text/output_head":
+            return self.direct_ternary("output.weight", (248320, HIDDEN))
+        if name == "text/final_norm":
+            return bf16_payload(read_direct(self.g, "output_norm.weight") - 1.0)
+
+        if len(p) > 3 and p[0] == "text" and p[1] == "layers":
+            l = int(p[2])
+            suffix = "/".join(p[3:])
+            g = self.g
+            pre = f"blk.{l}."
+
+            if suffix == "input_norm":
+                return bf16_payload(read_direct(g, pre + "attn_norm.weight") - 1.0)
+            if suffix == "post_attention_norm":
+                return bf16_payload(read_direct(g, pre + "post_attention_norm.weight") - 1.0)
+            if suffix == "mlp/gate_up":
+                ng, _ = g.row_shape(pre + "ffn_gate.weight")
+                nu, _ = g.row_shape(pre + "ffn_up.weight")
+                ent = [(pre + "ffn_gate.weight", i) for i in range(ng)]
+                ent += [(pre + "ffn_up.weight", i) for i in range(nu)]
+                return self.fused(ent, (ng + nu, HIDDEN))
+            if suffix == "mlp/down":
+                return self.direct_ternary(pre + "ffn_down.weight", (5120, 17408))
+
+            if suffix.startswith("attention/"):
+                sub = suffix.split("/", 1)[1]
+                if sub == "query_key":
+                    q = self.deinterleave(pre + "attn_q.weight", 0, (6144, HIDDEN))
+                    nk, _ = g.row_shape(pre + "attn_k.weight")
+                    return self.concat_streams(q, 6144, pre + "attn_k.weight", nk,
+                                               (6144 + nk, HIDDEN))
+                if sub == "gate_value":
+                    gt = self.deinterleave(pre + "attn_q.weight", 1, (6144, HIDDEN))
+                    nv, _ = g.row_shape(pre + "attn_v.weight")
+                    return self.concat_streams(gt, 6144, pre + "attn_v.weight", nv,
+                                               (6144 + nv, HIDDEN))
+                if sub == "output":
+                    return self.direct_ternary(pre + "attn_output.weight", (5120, 6144))
+                if sub == "query_norm":
+                    return bf16_payload(read_direct(g, pre + "attn_q_norm.weight") - 1.0)
+                if sub == "key_norm":
+                    return bf16_payload(read_direct(g, pre + "attn_k_norm.weight") - 1.0)
+                raise SystemExit(f"unmapped attention object {name}" + _SCHEMA_HINT)
+
+            if suffix.startswith("gdn/"):
+                sub = suffix.split("/", 1)[1]
+                if sub == "query_key":
+                    ent = [(pre + "attn_qkv.weight", i) for i in range(QK_ROWS)]
+                    return self.fused(ent, (QK_ROWS, HIDDEN))
+                if sub == "value_z":
+                    return self.gdn_value_z(l)
+                if sub == "output":
+                    return self.direct_ternary(pre + "ssm_out.weight", (5120, V_ROWS))
+                if sub == "convolution":
+                    return bf16_payload(self.conv1d(l))
+                if sub == "norm":
+                    return bf16_payload(read_direct(g, pre + "ssm_norm.weight"))  # RAW
+                if sub == "a_projection":
+                    return bf16_payload(tiled_to_grouped(read_direct(g, pre + "ssm_alpha.weight")))
+                if sub == "b_projection":
+                    return bf16_payload(tiled_to_grouped(read_direct(g, pre + "ssm_beta.weight")))
+                if sub == "a_log":
+                    a = read_direct(g, pre + "ssm_a")
+                    return fp32_payload(tiled_to_grouped(np.log(-a.astype(np.float64))
+                                                         .astype(np.float32)))
+                if sub == "dt_bias":
+                    return fp32_payload(tiled_to_grouped(read_direct(g, pre + "ssm_dt.bias")))
+                raise SystemExit(f"unmapped gdn object {name}" + _SCHEMA_HINT)
+
+            raise SystemExit(f"unmapped layer object {name}" + _SCHEMA_HINT)
+
+        return None   # borrow
+
+    # -- GDN / attention fusion helpers ----------------------------------
+    def deinterleave(self, gguf_name: str, parity: int, shape):
+        """query (parity 0) or output-gate (parity 1): every other 256-row chunk."""
+        n, k = self.g.row_shape(gguf_name)
+        if n % 512 != 0:
+            raise SystemExit(f"{gguf_name}: {n} rows is not a multiple of 512")
+        heads = n // 512
+        fmt = self.fmt_of(gguf_name)
+        nrows, gpr, block, rb, raw = self.g.blocks(gguf_name)
+        ent = [(gguf_name, (2 * h + parity) * 256 + r)
+               for h in range(heads) for r in range(256)]
+        return assemble_ternary(fmt, (len(ent), k),
+                                lambda i: raw[ent[i][1] * rb:(ent[i][1] + 1) * rb])
+
+    def concat_streams(self, first: bytes, first_rows: int, gname: str, gn: int, shape):
+        """Concatenate a pre-assembled ternary payload with another tensor's rows."""
+        n, k = shape
+        fmt = self.fmt_of(gname)
+        geo = row_split_geometry(fmt, shape)
+        gpr, bb, hb = geo.groups_per_row, geo.base_bytes_per_group, geo.high_bytes_per_group
+        block = bb + hb + 2
+        _n2, gpr2, block2, rb, raw = self.g.blocks(gname)
+        if gpr2 != gpr or block2 != block:
+            raise SystemExit("concat_streams: block geometry differs")
+        geo_a = row_split_geometry(fmt, (first_rows, k))
+
+        def row_fn(i):
+            if i < first_rows:
+                out = bytearray()
+                for sel in range(gpr):
+                    o = geo_a.base_offset + i * geo_a.base_row_bytes + sel * bb
+                    base = first[o:o + bb]
+                    high = b""
+                    if hb:
+                        o = geo_a.high_offset + i * geo_a.high_row_bytes + sel * hb
+                        high = first[o:o + hb]
+                    o = geo_a.scale_offset + i * geo_a.scale_row_bytes + sel * 2
+                    out += planes_to_block(fmt, base, high, first[o:o + 2])
+                return bytes(out)
+            j = i - first_rows
+            return raw[j * rb:(j + 1) * rb]
+
+        return assemble_ternary(fmt, shape, row_fn)
+
+    def gdn_value_z(self, l: int) -> bytes:
+        """concat(tiled_to_grouped(attn_qkv[4096:10240]), tiled_to_grouped(attn_gate[0:6144]))."""
+        pre = f"blk.{l}."
+        qkv, gate = pre + "attn_qkv.weight", pre + "attn_gate.weight"
+        f1, f2 = self.fmt_of(qkv), self.fmt_of(gate)
+        if f1 != f2:
+            raise SystemExit("value_z: mixed formats")
+        fmt = f1
+
+        def perm48(i):
+            # tiled (3,16) -> grouped (16,3) for a 48-entry HEAD axis:
+            # destination head g*3+t comes from source head t*16+g
+            return (i % 3) * 16 + (i // 3)
+
+        def perm_row(i):
+            # perm48() permutes a 48-entry axis, but this tensor's V/z rows are 48 heads of
+            # V_HEAD_DIM rows each, so the permutation has to be applied at HEAD granularity.
+            # Applying perm48() straight to the 6144-row index is not a bijection: perm48(48) and
+            # perm48(1) are both 16, so rows repeat and source rows are dropped while every size,
+            # row count and byte total stays exactly right -- which is why byte accounting, the
+            # row-count cross-check and the payload round-trip all stayed green over it.
+            head, inner = divmod(i, V_HEAD_DIM)
+            return perm48(head) * V_HEAD_DIM + inner
+
+        shape = (12288, HIDDEN)
+        geo = row_split_geometry(fmt, shape)
+        gpr, bb, hb = geo.groups_per_row, geo.base_bytes_per_group, geo.high_bytes_per_group
+        block = bb + hb + 2
+        gpr1 = self.g.blocks(qkv)[1]
+        gpr2_ = self.g.blocks(gate)[1]
+        if gpr1 != gpr or gpr2_ != gpr:
+            raise SystemExit("value_z: groups_per_row mismatch")
+        rb1 = self.g.blocks(qkv)[3]
+        rb2 = self.g.blocks(gate)[3]
+        raw1, raw2 = self.g.payload(qkv), self.g.payload(gate)
+
+        def row_fn(i):
+            if i < V_ROWS:                      # attn_qkv rows 4096..10240, tiled->grouped
+                src = QK_ROWS + perm_row(i)
+                return raw1[src * rb1:(src + 1) * rb1]
+            src = perm_row(i - V_ROWS)           # attn_gate rows 0..6144, tiled->grouped
+            return raw2[src * rb2:(src + 1) * rb2]
+
+        return assemble_ternary(fmt, shape, row_fn)
+
+    def conv1d(self, l: int) -> np.ndarray:
+        """(4,10240) <- ssm_conv1d: keep channels 0:4096, reorder the V channels, transpose."""
+        pre = f"blk.{l}."
+        t = read_direct(self.g, pre + "ssm_conv1d.weight")       # (10240, 4)
+        if t.shape != (10240, 4):
+            raise SystemExit(f"conv1d shape {t.shape} != (10240, 4)")
+        head = t[0:QK_ROWS]
+        v = t[QK_ROWS:QK_ROWS + V_ROWS].reshape(V_HEADS, V_HEAD_DIM, t.shape[1])
+        v = (v.reshape(3, V_HEADS // 3, V_HEAD_DIM, t.shape[1])
+              .transpose(1, 0, 2, 3)
+              .reshape(V_ROWS, t.shape[1]))
+        return np.concatenate([head, v], axis=0).T                # (4, 10240)
+
+
+# ---------------------------------------------------------------------------
+def mode_check(g: Gguf) -> int:
+    p = Packer(g)
+    print("=" * 78)
+    print("CHECK 1  geometry over every ternary shape present in the GGUF")
+    print("=" * 78)
+    combos = {}
+    for name, (ne, tt, _off) in g.tensor.items():
+        if tt in FMT:
+            combos.setdefault((FMT[tt], ne[1], ne[0]), []).append(name)
+    for (fmt, n, k), names in sorted(combos.items()):
+        geo = row_split_geometry(fmt, (n, k))
+        src = n * (k // 128) * (28 if fmt == "PTQ1_0_G128" else 34)
+        pad = geo.payload_bytes - src
+        print(f"  {fmt:<14} n={n:<7} k={k:<6} groups/row={geo.groups_per_row:<4} "
+              f"src={src:>13,} payload={geo.payload_bytes:>13,} pad={pad:>5} "
+              f"({len(names)} tensors)")
+    print(f"  distinct (format,shape) combos: {len(combos)}")
+
+    print("\n" + "=" * 78)
+    print("CHECK 2  byte round trip + decode equality on real tensors")
+    print("=" * 78)
+    sample = ["blk.3.attn_q.weight", "blk.3.attn_output.weight", "blk.3.ffn_down.weight",
+              "blk.0.attn_qkv.weight", "blk.0.ssm_out.weight", "token_embd.weight"]
+    ok = True
+    for name in sample:
+        if name not in g.tensor:
+            print(f"  {name}: absent, skipped")
+            continue
+        ne, tt = g.tinfo(name)
+        n, k = ne[1], ne[0]
+        fmt = FMT[tt]
+        payload = p.direct_ternary(name, (n, k))
+        back = disassemble_ternary(fmt, (n, k), payload)
+        src = g.payload(name)
+        byte_ok = back == src
+        a, b = DEQUANT[tt](src), DEQUANT[tt](back)
+        dec_ok = bool(np.array_equal(a, b))
+        zeros = float(np.mean(a == 0.0))
+
+        # OFFSET SELF-CHECK -- the decisive one.  bytes_equal only proves the assembly is
+        # self-consistent; reading a wrong file offset would ALSO give bytes_equal, because
+        # the same wrong bytes go in and come out.  So validate the CONTENT: a genuine group
+        # scale is a tight positive cluster (few distinct high bytes, all finite, none
+        # negative), whereas a mis-placed read draws scale words from arbitrary positions and
+        # looks like a uniform uint16 sample with many NaN/inf and negative values.
+        arr = np.frombuffer(src, dtype=np.uint8).reshape(-1, 34)
+        words = arr[:, 0:2].copy().view(np.uint16).reshape(-1)
+        hi_distinct = int(np.unique((words >> 8).astype(np.uint8)).size)
+        d = arr[:, 0:2].copy().view(np.float16).astype(np.float32).reshape(-1)
+        fin = np.isfinite(d)
+        n_nonfinite = int(np.sum(~fin))
+        n_neg = int(np.sum(fin & (d < 0)))
+        med = float(np.median(d[fin])) if fin.any() else float("nan")
+        plaus = (n_nonfinite == 0 and n_neg == 0 and hi_distinct <= 64 and 0.0 < med < 1.0)
+
+        print(f"  {name:<28} {fmt:<14} n={n:<6} k={k:<6} bytes_equal={byte_ok} "
+              f"decode_equal={dec_ok} zero_share={zeros:.4f}")
+        print(f"  {'':<28} scale: hi_distinct={hi_distinct:<4} nonfinite={n_nonfinite} "
+              f"negative={n_neg} median={med:.5f}  "
+              f"{'PLAUSIBLE' if plaus else 'IMPLAUSIBLE -- offset bug?'}")
+        ok &= byte_ok and dec_ok and plaus
+
+    print("\n" + "=" * 78)
+    print("CHECK 3  producer smoke test (shapes + sizes only, no artifact written)")
+    print("=" * 78)
+    for name in ["text/layers/3/attention/query_key", "text/layers/3/attention/gate_value",
+                 "text/layers/3/mlp/gate_up", "text/layers/3/mlp/down",
+                 "text/layers/3/attention/output", "text/layers/0/gdn/value_z",
+                 "text/layers/0/gdn/query_key", "text/layers/0/gdn/output",
+                 "text/token_embedding", "text/output_head", "text/final_norm",
+                 "text/hadamard_signs", "text/hadamard_widths"]:
+        base = p._by_name.get(name)
+        if base is not None:
+            shape = base["shape"]
+        else:
+            shape = dict((n, list(s)) for n, s, _f in SIGN_OBJECTS).get(name)
+            if shape is None:
+                print(f"  {name}: neither in template nor a sign object, skipped")
+                continue
+        fmt, layout = p.target_format(name)
+        spec = {"kind": "tensor", "shape": shape, "format": fmt, "layout": layout}
+        data = p.produce(name)
+        if data is None:
+            print(f"  {name:<44} {fmt:<14} {'(borrowed)':>13}  SKIP")
+            continue
+        need = p.payload_bytes(spec)
+        got = len(data)
+        flag = "OK" if (need is None or got == need) else f"MISMATCH want {need}"
+        print(f"  {name:<44} {fmt:<14} {got:>13,}  {flag}")
+        if need is not None and got != need:
+            ok = False
+
+    print("\nRESULT:", "OK" if ok else "FAILED")
+    return 0 if ok else 1
+
+
+def mode_build(g: Gguf, out: str, only_layer: int | None = None) -> int:
+    p = Packer(g)
+    keep = None
+    if only_layer is not None:
+        names = {n for n, _s, _f in SIGN_OBJECTS}      # the sign objects are appended later
+        for o in p.objects:
+            n = o["name"]
+            if n.startswith("frontend/") or n.startswith("text/hadamard_"):
+                names.add(n)
+            elif n.startswith(f"text/layers/{only_layer}/"):
+                names.add(n)
+        keep = names
+
+    specs = []
+    chosen = []
+    for o in p.objects + [
+        {"name": "text/hadamard_signs", "kind": "tensor", "shape": [28672],
+         "format": "FP32", "layout": "contiguous-le-v1"},
+        {"name": "text/hadamard_widths", "kind": "tensor", "shape": [3],
+         "format": "I32", "layout": "contiguous-le-v1"},
+    ]:
+        if keep is not None and o["name"] not in keep:
+            continue
+        if o["kind"] == "tensor":
+            fmt, layout = p.target_format(o["name"])
+            specs.append(TensorSpec(o["name"], tuple(o["shape"]), fmt, layout))
+        else:
+            specs.append(ResourceSpec(o["name"], o["encoding"], o["bytes"]))
+        chosen.append(o)
+
+    out_path = Path(out)
+    if out_path.exists():
+        raise SystemExit(f"refusing to overwrite {out_path}")
+
+    borrowed = Counter()
+    borrowed_bytes = 0
+    produced_bytes = 0
+    with Artifact.open(TEMPLATE) as tpl, \
+            ArtifactWriter(out_path, p.identity, specs) as w:
+        for o in chosen:
+            name = o["name"]
+            if name.startswith("text/") and not name.startswith("text/vision"):
+                data = None if name.startswith(("text/draft_head",)) else p.produce(name)
+                if data is not None:
+                    w.write(name, data)
+                    produced_bytes += len(data)
+                    continue
+            obj = tpl.find(name)
+            if obj is None:
+                raise SystemExit(f"template has no object {name} to borrow")
+            mv = tpl.payload(obj)
+            borrowed_bytes += len(mv)
+            w.write(name, mv)
+            del mv          # release the mmap view, else Artifact.close() raises BufferError
+            borrowed[name.split("/")[0]] += 1
+
+    size = out_path.stat().st_size
+    print(f"\nwrote {out_path}")
+    print(f"  total file        : {size:>15,} B = {size / 2**30:.3f} GiB")
+    print(f"  text part produced: {produced_bytes:>15,} B = {produced_bytes / 2**30:.3f} GiB")
+    print(f"  borrowed payloads : {borrowed_bytes:>15,} B = {borrowed_bytes / 2**30:.3f} GiB "
+          f"{dict(borrowed)}")
+    print(f"  objects           : {len(chosen)}")
+    return 0
+
+
+def _pop_opt(args, name):
+    """Remove `--name VALUE` / `--name=VALUE` from args; return (value|None, rest)."""
+    rest, val, i = [], None, 0
+    while i < len(args):
+        a = args[i]
+        if a == name and i + 1 < len(args):
+            val, i = args[i + 1], i + 2
+        elif a.startswith(name + "="):
+            val, i = a.split("=", 1)[1], i + 1
+        else:
+            rest.append(a)
+            i += 1
+    return val, rest
+
+
+def main() -> int:
+    global TEMPLATE, GGUF
+    args = sys.argv[1:]
+    tpl_opt, args = _pop_opt(args, "--template")
+    gguf_opt, args = _pop_opt(args, "--gguf")
+    TEMPLATE = tpl_opt or os.environ.get("NINFER_TERNARY_TEMPLATE") or TEMPLATE
+    GGUF = gguf_opt or os.environ.get("NINFER_TERNARY_GGUF") or GGUF
+    if not args:
+        print(__doc__)
+        return 2
+    if not Path(TEMPLATE).exists():
+        raise SystemExit(
+            f"模板不存在: {TEMPLATE}\n"
+            f"  用 --template <path> 或环境变量 NINFER_TERNARY_TEMPLATE 指定。\n"
+            f"  模板必须与目标制品同 schema：weights_id={TEMPLATE_SCHEMA}"
+            f"（不是 nvfp4，见 README FAQ）。")
+    if not Path(GGUF).exists():
+        raise SystemExit(
+            f"GGUF 不存在: {GGUF}\n"
+            f"  用 --gguf <path> 或环境变量 NINFER_TERNARY_GGUF 指定。\n"
+            f"  源码里的默认值是占位符 <WORKSPACE>，必须覆盖。")
+    g = Gguf(GGUF)
+    if args[0] == "check":
+        return mode_check(g)
+    if args[0] == "layer3":
+        return mode_build(g, args[1], only_layer=3)
+    if args[0] == "build":
+        return mode_build(g, args[1])
+    print(f"unknown mode {args[0]}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/verify/check_assembly.py

@@ -0,0 +1,155 @@
+"""Assembly audit: is EVERY ternary object a faithful, correctly ordered copy of its source?
+
+Byte accounting cannot see a row permutation (sizes, row counts and totals are conserved), and a
+set-membership test cannot see it either (every duplicated row still finds a source). This audit
+therefore compares MULTISETS and, more importantly, checks artifact row a DIRECTLY against the
+source row the mapping rule names for a.
+
+Sources are de-interleaved GGUF PQ2_0 blocks; artifacts are row-split planes. Both are reduced to
+the same per-row fingerprint (codes bytes + scale bytes), so the comparison is exact and
+independent of the rotated basis (rows are permuted, never transformed).
+
+Usage: check_assembly.py <artifact.ninfer> <pq2.gguf>
+"""
+from __future__ import annotations
+
+import hashlib
+import sys
+from collections import Counter
+from pathlib import Path
+
+import numpy as np
+
+sys.path.insert(0, r"<NINFER_ROOT>")
+sys.path.insert(0, r"<WORKSPACE>\tools")
+from _ternary_ref import Gguf  # noqa: E402
+from tools.artifact import container  # noqa: E402
+
+GROUPS = 40
+CODE_BYTES = 32
+SCALE_BYTES = 2
+V_HEAD_DIM = 128
+
+
+def artifact_rows(art, name: str) -> list[bytes]:
+    obj = art.find(name)
+    payload = np.frombuffer(bytes(art.payload(obj)), dtype=np.uint8)
+    rows = int(obj.shape[0])
+    groups = int(obj.shape[1]) // 128
+    codes = payload[: rows * groups * CODE_BYTES]
+    off = rows * groups * CODE_BYTES
+    scales = payload[off: off + rows * groups * SCALE_BYTES]
+    return [
+        hashlib.sha1(codes[r * groups * CODE_BYTES:(r + 1) * groups * CODE_BYTES].tobytes()
+                     + scales[r * groups * SCALE_BYTES:(r + 1) * groups * SCALE_BYTES].tobytes()
+                     ).digest()
+        for r in range(rows)
+    ]
+
+
+def gguf_rows(gguf: Gguf, name: str) -> list[bytes]:
+    ne, tt, _ = gguf.tensors[name]
+    if tt != 142:
+        raise SystemExit(f"{name}: expected PQ2_0 (142), got {tt}")
+    rows = int(ne[1])
+    groups = int(ne[0]) // 128          # ggml ne[0] is the contiguous K extent
+    raw = gguf.raw(name, rows)
+    block = np.frombuffer(raw, dtype=np.uint8).reshape(rows, groups, 34)
+    codes = np.ascontiguousarray(block[:, :, 2:34]).reshape(rows, groups * CODE_BYTES)
+    scales = np.ascontiguousarray(block[:, :, 0:2]).reshape(rows, groups * SCALE_BYTES)
+    return [hashlib.sha1(codes[r].tobytes() + scales[r].tobytes()).digest() for r in range(rows)]
+
+
+def perm48(i: int) -> int:
+    return (i % 3) * 16 + (i // 3)
+
+
+def head_perm(rows: int) -> list[int]:
+    """48 heads x 128 rows: the permutation must be applied at head granularity."""
+    out = []
+    for r in range(rows):
+        head, inner = divmod(r, V_HEAD_DIM)
+        out.append(perm48(head) * V_HEAD_DIM + inner)
+    return out
+
+
+def audit(label: str, art_keys: list[bytes], src_keys: list[bytes]) -> bool:
+    art_counts, src_counts = Counter(art_keys), Counter(src_keys)
+    repeated = sum(v - 1 for v in art_counts.values() if v > 1)
+    missing = sum(1 for k in src_counts if k not in art_counts)
+    order_bad = [a for a in range(len(art_keys)) if art_keys[a] != src_keys[a]]
+    ok = (repeated == 0) and (missing == 0) and not order_bad
+    print(f"{'OK  ' if ok else 'FAIL'} {label}")
+    print(f"       rows art={len(art_keys)} src={len(src_keys)} | "
+          f"distinct art={len(art_counts)} src={len(src_counts)} | "
+          f"duplicated={repeated} missing={missing} | "
+          f"order mismatches={len(order_bad)}/{len(art_keys)}")
+    if order_bad:
+        print(f"       first bad rows: {order_bad[:8]}")
+    return ok
+
+
+def main() -> int:
+    art_path, gguf_path = sys.argv[1], sys.argv[2]
+    gguf = Gguf(Path(gguf_path))
+    results = []
+    with container.Artifact.open(art_path) as art:
+        def A(name):
+            return artifact_rows(art, name)
+        def G(name):
+            return gguf_rows(gguf, name)
+
+        # --- globals ---------------------------------------------------------
+        results.append(audit("text/token_embedding  <- token_embd.weight",
+                             A("text/token_embedding"), G("token_embd.weight")))
+        results.append(audit("text/output_head      <- output.weight",
+                             A("text/output_head"), G("output.weight")))
+
+        for layer, kind in ((0, "gdn"), (3, "attention")):
+            pre = f"blk.{layer}."
+            la = f"text/layers/{layer}/"
+            print(f"--- layer {layer} ({kind}) ---")
+            results.append(audit(f"{la}mlp/down      <- ffn_down",
+                                 A(la + "mlp/down"), G(pre + "ffn_down.weight")))
+            results.append(audit(f"{la}mlp/gate_up   <- concat(ffn_gate, ffn_up)",
+                                 A(la + "mlp/gate_up"),
+                                 G(pre + "ffn_gate.weight") + G(pre + "ffn_up.weight")))
+            if kind == "gdn":
+                results.append(audit(f"{la}gdn/query_key <- attn_qkv[0:4096]",
+                                     A(la + "gdn/query_key"),
+                                     G(pre + "attn_qkv.weight")[:4096]))
+                results.append(audit(f"{la}gdn/output    <- ssm_out",
+                                     A(la + "gdn/output"), G(pre + "ssm_out.weight")))
+                # value/z halves: compare against the source reordered by the head permutation
+                vz = A(la + "gdn/value_z")
+                v_src = G(pre + "attn_qkv.weight")[4096:10240]
+                z_src = G(pre + "attn_gate.weight")[:6144]
+                perm = head_perm(6144)
+                results.append(audit(f"{la}gdn/value_z   <- attn_qkv[4096:10240] (head perm)",
+                                     vz[:6144], [v_src[p] for p in perm]))
+                results.append(audit(f"{la}gdn/value_z   <- attn_gate[0:6144] (head perm)",
+                                     vz[6144:], [z_src[p] for p in perm]))
+            else:
+                aq = G(pre + "attn_q.weight")
+                even = [c * 256 + r for c in range(0, 48, 2) for r in range(256)]
+                odd = [c * 256 + r for c in range(1, 48, 2) for r in range(256)]
+                qk = A(la + "attention/query_key")
+                gv = A(la + "attention/gate_value")
+                results.append(audit(f"{la}attention/query_key <- attn_q even chunks",
+                                     qk[:6144], [aq[r] for r in even]))
+                results.append(audit(f"{la}attention/query_key <- attn_k",
+                                     qk[6144:], G(pre + "attn_k.weight")[:1024]))
+                results.append(audit(f"{la}attention/gate_value <- attn_q odd chunks",
+                                     gv[:6144], [aq[r] for r in odd]))
+                results.append(audit(f"{la}attention/gate_value <- attn_v",
+                                     gv[6144:], G(pre + "attn_v.weight")[:1024]))
+                results.append(audit(f"{la}attention/output <- attn_output",
+                                     A(la + "attention/output"), G(pre + "attn_output.weight")))
+
+    passed = sum(1 for r in results if r)
+    print(f"\nRESULT: {passed}/{len(results)} assembly rules OK")
+    return 0 if passed == len(results) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/verify/check_embedding.py

@@ -0,0 +1,135 @@
+"""Oracle for the ternary embedding path: gather (PQ2_0 decode) + inverse folded-basis mapping.
+
+The residual stream enters layer 0 at the embedding output, so a break here makes every downstream
+number meaningless -- which is exactly what a perplexity close to uniform looks like. This compares
+the engine's dumped embedding activation against an independent numpy rebuild of
+
+    h = s * (H * z),   z = decode(token_embedding_row[id])
+
+where z comes straight out of the artifact payload (decoded independently of the engine).
+
+Negative controls are mandatory: a near-uniform or all-zeros dump would otherwise "match" nothing,
+and the unrotated variant would match if the engine simply skipped the mapping.
+
+Usage: check_embedding.py <artifact.ninfer> <dump-file.T<N>>
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import numpy as np
+
+sys.path.insert(0, r"<NINFER_ROOT>")
+from tools.artifact import container  # noqa: E402
+
+BLOCK = 1024
+GROUPS = 40
+POP = np.array([bin(i).count("1") for i in range(256)], dtype=np.uint8)
+
+
+def popcount32(a: np.ndarray) -> np.ndarray:
+    v = a.astype(np.uint32)
+    return (POP[v & 0xFF].astype(np.uint16) + POP[(v >> 8) & 0xFF].astype(np.uint16)
+            + POP[(v >> 16) & 0xFF].astype(np.uint16) + POP[(v >> 24) & 0xFF].astype(np.uint16))
+
+
+def hadamard(n: int) -> np.ndarray:
+    idx = np.arange(n, dtype=np.uint32)
+    parity = popcount32(idx[:, None] & idx[None, :]) & 1
+    return np.where(parity == 1, -1.0, 1.0) / np.sqrt(float(n))
+
+
+def main() -> int:
+    art_path, dump_path = sys.argv[1], sys.argv[2]
+    raw = np.fromfile(dump_path, dtype=np.uint8)
+    tokens, hidden, id_count = np.frombuffer(raw[:12], dtype=np.int32)
+    ids = np.frombuffer(raw[12:12 + id_count * 4], dtype=np.int32)
+    bf16 = np.frombuffer(raw[12 + id_count * 4:], dtype=np.uint16).reshape(tokens, hidden)
+    # The op writes out as [hidden, T] row-major, so element (k, t) sits at k*T + t. Reshaping the
+    # flat buffer as (T, hidden) would reinterpret that as t*hidden + k -- a silent transpose that
+    # decorrelates everything for T > 1 and looks like a total engine failure.
+    got = (bf16.astype(np.uint32) << 16).view(np.float32).astype(np.float64).reshape(hidden, tokens)
+    print(f"dump: tokens={tokens} hidden={hidden} ids={id_count}")
+    print(f"ids[:12]={ids[:12].tolist()}")
+
+    with container.Artifact.open(art_path) as art:
+        obj = art.find("text/token_embedding")
+        payload = np.frombuffer(bytes(art.payload(obj)), dtype=np.uint8).copy()
+        signs_all = np.frombuffer(bytes(art.payload("text/hadamard_signs")), dtype=np.float32)
+        widths = np.frombuffer(bytes(art.payload("text/hadamard_widths")), dtype=np.int32)
+        rows = int(obj.shape[0])
+    off = 0
+    sign_offsets = {}
+    for w in widths:
+        sign_offsets[int(w)] = off
+        off += int(w)
+    signs = signs_all[sign_offsets[hidden]:sign_offsets[hidden] + hidden].astype(np.float64)
+
+    codes = payload[: rows * GROUPS * 32].reshape(rows, GROUPS, 32)
+    scale_off = rows * GROUPS * 32
+    scales = payload[scale_off: scale_off + rows * GROUPS * 2].view(np.float16).astype(
+        np.float64).reshape(rows, GROUPS)
+
+    def decode_row(index: int) -> np.ndarray:
+        q = codes[index]                                     # (groups, 32 bytes)
+        code = (q[:, :, None] >> (2 * np.arange(4, dtype=np.uint8))[None, None, :]) & 3
+        flat = code.reshape(-1).astype(np.float64)            # 32 bytes x 4 codes x groups
+        return (flat - 1.0) * np.repeat(scales[index], 128)
+
+    H = hadamard(BLOCK)
+    n_block = hidden // BLOCK
+
+    def inverse(vec: np.ndarray) -> np.ndarray:
+        out = np.empty_like(vec)
+        for b in range(n_block):
+            lo = b * BLOCK
+            out[lo:lo + BLOCK] = signs[lo:lo + BLOCK] * (H @ vec[lo:lo + BLOCK])
+        return out
+
+    def forward(vec: np.ndarray) -> np.ndarray:
+        out = np.empty_like(vec)
+        for b in range(n_block):
+            lo = b * BLOCK
+            out[lo:lo + BLOCK] = H @ (signs[lo:lo + BLOCK] * vec[lo:lo + BLOCK])
+        return out
+
+    checked = 0
+    worst = 0.0
+    for t in range(min(tokens, 8)):
+        z = decode_row(int(ids[t]))
+        ref = inverse(z)
+        col = got[:, t]
+        if t < 3:
+            def stats(name, v):
+                print(f"    {name}: ||v||={np.linalg.norm(v):.6g} mean={v.mean():+.4g} "
+                      f"std={v.std():.4g} min={v.min():+.4g} max={v.max():+.4g} "
+                      f"nan={int(np.isnan(v).sum())}")
+            print(f"  token {t} id={int(ids[t])}")
+            stats("engine dump", col)
+            stats("decoded row z", z)
+            stats("expected s*(H*z)", ref)
+            # is the engine maybe returning a DIFFERENT token's row, or a mis-strided gather?
+            for shift in (-2, -1, 1, 2):
+                if 0 <= t + shift < tokens:
+                    other = inverse(decode_row(int(ids[t + shift])))
+                    c = float(np.dot(col, other) /
+                              max(np.linalg.norm(col) * np.linalg.norm(other), 1e-30))
+                    print(f"      cos vs token{shift:+d} row = {c:+.4f}")
+        rel = float(np.linalg.norm(col - ref) / np.linalg.norm(ref))
+        cos = float(np.dot(col, ref) / (np.linalg.norm(col) * np.linalg.norm(ref)))
+        ctrl_raw = float(np.dot(col, z) / (np.linalg.norm(col) * np.linalg.norm(z)))
+        ctrl_fwd = forward(z)
+        ctrl_fwd_cos = float(np.dot(col, ctrl_fwd) / (np.linalg.norm(col) * np.linalg.norm(ctrl_fwd)))
+        if t < 4:
+            print(f"    rel_l2={rel:.4e} cos={cos:+.6f} | "
+                  f"control cos(unrotated)={ctrl_raw:+.4f} cos(signs-first)={ctrl_fwd_cos:+.4f}")
+        worst = max(worst, rel)
+        checked += 1
+    print(f"\nchecked {checked} tokens, worst rel_l2 = {worst:.4e}")
+    print(f"RESULT: {'PASS' if worst <= 0.02 else 'FAIL'} (engine embedding == independent rebuild)")
+    return 0 if worst <= 0.02 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/verify/check_row_order.py

@@ -0,0 +1,161 @@
+"""Verify the two INFERRED row-order rules by exact row fingerprints.
+
+MAPPING.json flags exactly two rules as inferred rather than measured, and both are row
+permutations of whole quantized rows -- which means each row's bytes survive untouched and can be
+matched exactly between the GGUF and the artifact:
+
+  gdn_value_z                    "risk: if the engine test disagrees, flip this single permutation"
+  attn_q_per_head_interleave     "INFERRED for main layers from the MTP layer"
+
+Nothing about the rotated basis matters here: rows are permuted, not transformed, so a byte-level
+row fingerprint is an exact test of the rule (this is the "structural self-proof" the handoff asks
+for instead of value correlation, which is meaningless across bases).
+
+Usage: check_row_order.py <artifact.ninfer> <pq2.gguf>
+"""
+from __future__ import annotations
+
+import hashlib
+import sys
+from pathlib import Path
+
+import numpy as np
+
+sys.path.insert(0, r"<NINFER_ROOT>")
+sys.path.insert(0, r"<WORKSPACE>\tools")
+from _ternary_ref import Gguf  # noqa: E402
+from tools.artifact import container  # noqa: E402
+
+GROUPS = 40
+CODE_BYTES = 32
+SCALE_BYTES = 2
+
+
+def artifact_row_keys(art, name: str) -> list[bytes]:
+    """Fingerprint every row of a PQ2_0 row-split object as (codes, scales) digests."""
+    obj = art.find(name)
+    payload = np.frombuffer(bytes(art.payload(obj)), dtype=np.uint8)
+    rows = int(obj.shape[0])
+    assert int(obj.shape[1]) == GROUPS * 128, obj.shape
+    codes = payload[: rows * GROUPS * CODE_BYTES]
+    scale_start = rows * GROUPS * CODE_BYTES
+    scales = payload[scale_start: scale_start + rows * GROUPS * SCALE_BYTES]
+    keys: list[bytes] = []
+    for r in range(rows):
+        c = codes[r * GROUPS * CODE_BYTES:(r + 1) * GROUPS * CODE_BYTES]
+        s = scales[r * GROUPS * SCALE_BYTES:(r + 1) * GROUPS * SCALE_BYTES]
+        keys.append(hashlib.sha1(bytes(c) + bytes(s)).digest())
+    return keys
+
+
+def gguf_row_keys(gguf: Gguf, name: str) -> list[bytes]:
+    """De-interleave GGUF {fp16 d; uint8 qs[32]} blocks into the same (codes, scales) fingerprint."""
+    ne, tt, _ = gguf.tensors[name]
+    assert tt == 142, (name, tt)  # PQ2_0
+    rows = int(ne[1])
+    raw = gguf.raw(name, rows)
+    block = np.frombuffer(raw, dtype=np.uint8).reshape(rows, GROUPS, 34)
+    codes = np.ascontiguousarray(block[:, :, 2:34]).reshape(rows, GROUPS * CODE_BYTES)
+    scales = np.ascontiguousarray(block[:, :, 0:2]).reshape(rows, GROUPS * SCALE_BYTES)
+    return [hashlib.sha1(codes[r].tobytes() + scales[r].tobytes()).digest() for r in range(rows)]
+
+
+def report(label: str, art_keys: list[bytes], gguf_subset: list[bytes],
+           src_index: list[int], expected) -> bool:
+    """Check the artifact rows two ways.
+
+    The multiset test proves the packer took the right source rows. The permutation test is done by
+    comparing the artifact row at index a directly against the source row the rule NAMES for a --
+    never by searching for a matching fingerprint first, because identical quantized rows do occur
+    and a first-hit search would then report a harmless false mismatch.
+    """
+    table: dict[bytes, list[int]] = {}
+    for r, key in enumerate(gguf_subset):
+        table.setdefault(key, []).append(r)
+    matched = sum(1 for key in art_keys if key in table)
+    ok_set = matched == len(art_keys)
+    unique_art = len(set(art_keys))
+    unique_src = len(set(gguf_subset))
+    print(f"{label}: artifact rows={len(art_keys)} source rows={len(gguf_subset)} "
+          f"matched={matched} -> {'row SET matches' if ok_set else 'ROW SET MISMATCH'}")
+    print(f"    distinct fingerprints: artifact={unique_art} source={unique_src} "
+          f"(duplicates make fingerprint-first search unreliable, hence the direct check)")
+
+    direct = [a for a, src in enumerate(src_index)
+              if art_keys[a] != gguf_subset[src]]
+    perm_ok = not direct
+    print(f"    documented rule holds row-by-row: {perm_ok}"
+          + (f"  ({len(direct)} of {len(art_keys)} rows disagree)" if not perm_ok else ""))
+
+    # Is the artifact a genuine PERMUTATION of the source rows?  A repack that reshaped the wrong
+    # axis repeats some rows and drops others, which a "does every row exist somewhere" test cannot
+    # see: every row still matches something.  Compare the multisets explicitly.
+    from collections import Counter
+    art_counts = Counter(art_keys)
+    src_counts = Counter(gguf_subset)
+    repeated = {k: v for k, v in art_counts.items() if v > 1}
+    missing = [k for k in src_counts if k not in art_counts]
+    extra_rows = sum(v - 1 for v in repeated.values())
+    print(f"    multiset: artifact {len(art_keys)} rows / {len(art_counts)} distinct; "
+          f"source {len(gguf_subset)} rows / {len(src_counts)} distinct")
+    print(f"    rows DUPLICATED in the artifact: {len(repeated)} fingerprints covering "
+          f"{extra_rows} redundant rows;  source rows MISSING from the artifact: {len(missing)}")
+    if missing or repeated:
+        print("    -> NOT a permutation: the packing permutation duplicates and drops rows")
+    if not perm_ok:
+        print("    first divergent rows (artifact row -> named source vs what it actually equals):")
+        shown = 0
+        for a in direct[:6]:
+            hits = table.get(art_keys[a], [])
+            print(f"      {a} -> named {src_index[a]}, actually equals source rows {hits[:4]}")
+            shown += 1
+        print(f"    artifact first 24 -> named sources: {src_index[:24]}")
+    return ok_set and perm_ok
+
+
+def tiled_to_grouped_index(grouped_row: int, heads: int = 48, per: int = 3) -> int:
+    """grouped row (nk, rep, hd) -> tiled source row (rep, nk, hd), with 128 values per head."""
+    hd = grouped_row % 128
+    rest = grouped_row // 128
+    nk, rep = rest // per, rest % per
+    return rep * (heads // per) * 128 + nk * 128 + hd
+
+
+def main() -> int:
+    art_path, gguf_path = sys.argv[1], sys.argv[2]
+    gguf = Gguf(Path(gguf_path))
+    ok = True
+    with container.Artifact.open(art_path) as art:
+        # ---- rule: gdn_value_z (48 layers) ----------------------------------
+        art_keys = artifact_row_keys(art, "text/layers/0/gdn/value_z")
+        value_src = gguf_row_keys(gguf, "blk.0.attn_qkv.weight")[4096:10240]   # 6144 V rows
+        gate_src = gguf_row_keys(gguf, "blk.0.attn_gate.weight")[0:6144]        # 6144 z rows
+        print("== gdn_value_z: artifact rows [0:6144] vs gguf attn_qkv[4096:10240]")
+        ok &= report("   value part", art_keys[0:6144], value_src,
+                     [tiled_to_grouped_index(r) for r in range(6144)], None)
+        print("== gdn_value_z: artifact rows [6144:12288] vs gguf attn_gate[0:6144]")
+        ok &= report("   z part", art_keys[6144:12288], gate_src,
+                     [tiled_to_grouped_index(r) for r in range(6144)], None)
+
+        # ---- rule: attn_q_per_head_interleave (16 layers) -------------------
+        qk_keys = artifact_row_keys(art, "text/layers/3/attention/query_key")
+        attn_q = gguf_row_keys(gguf, "blk.3.attn_q.weight")   # 12288 rows: 48 chunks of 256
+        even = [r for chunk in range(0, 48, 2) for r in range(chunk * 256, chunk * 256 + 256)]
+        print("== attn_q_per_head_interleave: artifact query rows [0:6144] vs even chunks of attn_q")
+        ok &= report("   query part", qk_keys[0:6144], [attn_q[r] for r in even],
+                     list(range(6144)), None)
+        attn_k = gguf_row_keys(gguf, "blk.3.attn_k.weight")
+        print("== attn key part: artifact rows [6144:7168] vs gguf attn_k[0:1024]")
+        ok &= report("   key part", qk_keys[6144:7168], attn_k[0:1024], list(range(1024)), None)
+
+        gv_keys = artifact_row_keys(art, "text/layers/3/attention/gate_value")
+        odd = [r for chunk in range(1, 48, 2) for r in range(chunk * 256, chunk * 256 + 256)]
+        print("== attn_q_per_head_interleave: artifact gate rows [0:6144] vs odd chunks of attn_q")
+        ok &= report("   gate part", gv_keys[0:6144], [attn_q[r] for r in odd],
+                     list(range(6144)), None)
+    print(f"\nRESULT: {'all row-order rules hold' if ok else 'ROW-ORDER RULE MISMATCH FOUND'}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/verify/gemm_oracle.py

@@ -0,0 +1,140 @@
+"""Dump / check the ternary GEMM + rotation integration against an independent reference.
+
+Two modes:
+
+  dump  <artifact> <object> <dump-dir>
+        Writes the object's row-split payload, the sign block for its input width, and a
+        deterministic activation, so a standalone nvcc harness can run the REAL kernels.
+
+  check <artifact> <object> <dump-dir>
+        Decodes the payload in pure numpy (the arrangement was already proven by
+        check_payload_order.py), rebuilds  y = W' * (H * (s * (P * x)))  explicitly in float64 and
+        compares against the kernel dump.
+
+The point is to cover what no byte/size/oracle check so far covers: that the plane pointers, the
+2-bit decode, the sign block for THIS width, and the rotation compose into the documented math.
+
+Usage: gemm_oracle.py dump|check <artifact.ninfer> <object-name> <dump-dir>
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import numpy as np
+
+sys.path.insert(0, r"<NINFER_ROOT>")
+from tools.artifact import container  # noqa: E402
+
+BLOCK = 1024
+POPCOUNT = np.array([bin(i).count("1") for i in range(256)], dtype=np.uint8)
+
+
+def popcount32(a: np.ndarray) -> np.ndarray:
+    v = a.astype(np.uint32)
+    return (
+        POPCOUNT[v & 0xFF].astype(np.uint16)
+        + POPCOUNT[(v >> 8) & 0xFF].astype(np.uint16)
+        + POPCOUNT[(v >> 16) & 0xFF].astype(np.uint16)
+        + POPCOUNT[(v >> 24) & 0xFF].astype(np.uint16)
+    )
+
+
+def hadamard(n: int) -> np.ndarray:
+    idx = np.arange(n, dtype=np.uint32)
+    parity = popcount32(idx[:, None] & idx[None, :]) & 1
+    return np.where(parity == 1, -1.0, 1.0) / np.sqrt(float(n))
+
+
+def make_x(k: int, tokens: int, seed: int = 12345) -> np.ndarray:
+    state = np.uint32(seed)
+    out = np.empty(k * tokens, dtype=np.float32)
+    for i in range(out.size):
+        state = np.uint32(state * np.uint32(1664525) + np.uint32(1013904223))
+        out[i] = np.float32((int(state >> 8) & 0xFFFF) / 32768.0 - 1.0)
+    return out.reshape(k, tokens)
+
+
+def load(artifact_path: str, name: str):
+    with container.Artifact.open(artifact_path) as art:
+        obj = art.find(name)
+        payload = np.frombuffer(bytes(art.payload(obj)), dtype=np.uint8).copy()
+        signs_all = np.frombuffer(bytes(art.payload("text/hadamard_signs")), dtype=np.float32)
+        widths = np.frombuffer(bytes(art.payload("text/hadamard_widths")), dtype=np.int32)
+        rows, cols = int(obj.shape[0]), int(obj.shape[1])
+    offsets, acc = {}, 0
+    for w in widths:
+        offsets[int(w)] = acc
+        acc += int(w)
+    signs = signs_all[offsets[cols]:offsets[cols] + cols].copy()
+    return payload, signs, rows, cols, obj.format
+
+
+def decode_pq2(payload: np.ndarray, rows: int, groups: int) -> np.ndarray:
+    """Same arrangement the row-split layout declares, decoded exactly like ggml's PQ2_0."""
+    codes = payload[: rows * groups * 32].reshape(rows, groups, 32)
+    scales = payload[rows * groups * 32: rows * groups * 32 + rows * groups * 2].view(
+        np.float16).astype(np.float64).reshape(rows, groups)
+    codes = codes.reshape(rows, groups, 32, 1)
+    codes = (codes >> (2 * np.arange(4, dtype=np.uint8)).reshape(1, 1, 1, 4)) & 3  # [rows,groups,32,4]
+    codes = codes.reshape(rows, groups, 128).astype(np.float64)
+    weights = (codes - 1.0) * scales[:, :, None]
+    return weights.reshape(rows, groups * 128)
+
+
+def main() -> int:
+    mode, artifact_path, name, dump_dir = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+    payload, signs, rows, cols, fmt = load(artifact_path, name)
+    groups = cols // 128
+    if fmt != "PQ2_0_G128":
+        print(f"this probe only implements PQ2_0; got {fmt}")
+        return 2
+    x = make_x(cols, 1)
+    os.makedirs(dump_dir, exist_ok=True)
+
+    if mode == "dump":
+        payload.tofile(os.path.join(dump_dir, "gemm.payload.bin"))
+        signs.astype(np.float32).tofile(os.path.join(dump_dir, "gemm.signs.f32"))
+        x.astype(np.float32).tofile(os.path.join(dump_dir, "gemm.x.f32"))
+        print(f"dumped {name}: payload={payload.size} B rows={rows} cols={cols} groups={groups} "
+              f"scale_plane_off={rows * groups * 32}")
+        return 0
+
+    weights = decode_pq2(payload, rows, groups)
+    print(f"decoded W' {weights.shape}  finite={np.isfinite(weights).all()} "
+          f"absmax={np.abs(weights).max():.6g}")
+
+    H = hadamard(BLOCK)
+    xr = np.empty_like(x, dtype=np.float64)
+    for b in range(cols // BLOCK):
+        lo = b * BLOCK
+        xr[lo:lo + BLOCK, 0] = H @ (signs[lo:lo + BLOCK].astype(np.float64) * x[lo:lo + BLOCK, 0])
+    y_ref = weights @ xr[:, 0]
+
+    y_got = np.fromfile(os.path.join(dump_dir, "gemm.y.f32"), dtype=np.float32).astype(np.float64)
+    if y_got.size != rows:
+        print(f"kernel dump has {y_got.size} rows, expected {rows}")
+        return 1
+
+    rel = float(np.linalg.norm(y_got - y_ref) / np.linalg.norm(y_ref))
+    diff = float(np.abs(y_got - y_ref).max())
+    # negative controls: if the kernel disagreed with the documented math in any of these ways the
+    # match would collapse, so report them to prove the comparison has teeth
+    y_norot = weights @ x[:, 0]
+    y_nosign = np.empty_like(x, dtype=np.float64)
+    for b in range(cols // BLOCK):
+        lo = b * BLOCK
+        y_nosign[lo:lo + BLOCK, 0] = H @ x[lo:lo + BLOCK, 0]
+    y_nosign = weights @ y_nosign[:, 0]
+    y_unnorm = weights @ (xr[:, 0] * np.sqrt(BLOCK))
+    print(f"  rel_l2 = {rel:.4e}   max|diff| = {diff:.4e}   {'PASS' if rel <= 0.02 else 'FAIL'}")
+    for label, ref in (("no rotation", y_norot), ("no signs", y_nosign),
+                       ("unnormalized H", y_unnorm)):
+        r = float(np.linalg.norm(y_got - ref) / np.linalg.norm(ref))
+        print(f"    control {label:16s} rel_l2={r:.4f}  "
+              f"{'(differs OK)' if r > 0.05 else '(TOO CLOSE)'}")
+    return 0 if rel <= 0.02 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/verify/oracle_rot.py

@@ -0,0 +1,168 @@
+"""numpy oracle for the folded-basis rotation kernels (forward and inverse).
+
+Reads the raw f32 dumps the standalone nvcc harness wrote, rebuilds the documented transform
+explicitly, and compares against the REAL kernel output element for element.
+
+The pass criterion is deliberately two-sided: the documented variant must match, AND a family of
+plausible-but-wrong variants must all fail.  A one-sided check cannot tell "the kernel is right"
+from "the oracle is too loose" -- which is exactly the trap the handoff notes call a
+self-consistent false green.
+
+Usage: oracle_rot.py <dump-dir>
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import numpy as np
+
+BLOCK = 1024
+CASES = [
+    # tag, k, tokens, perm_hd, perm_nk, perm_rep, inverse
+    ("plain_t1", 5120, 1, 0, 0, 1, False),
+    ("plain_t3", 5120, 3, 0, 0, 1, False),
+    ("perm_t1", 6144, 1, 128, 16, 3, False),
+    ("perm_t2", 6144, 2, 128, 16, 3, False),
+    ("wide_t1", 17408, 1, 0, 0, 1, False),
+    ("inv_t2", 5120, 2, 0, 0, 1, True),
+]
+
+
+_POPCOUNT = np.array([bin(i).count("1") for i in range(256)], dtype=np.uint8)
+
+
+def _popcount32(a: np.ndarray) -> np.ndarray:
+    """numpy 1.26 has no bitwise_count, so unroll the byte lookup explicitly."""
+    v = a.astype(np.uint32)
+    return (
+        _POPCOUNT[v & 0xFF].astype(np.uint16)
+        + _POPCOUNT[(v >> 8) & 0xFF].astype(np.uint16)
+        + _POPCOUNT[(v >> 16) & 0xFF].astype(np.uint16)
+        + _POPCOUNT[(v >> 24) & 0xFF].astype(np.uint16)
+    )
+
+
+def hadamard(n: int) -> np.ndarray:
+    idx = np.arange(n, dtype=np.uint32)
+    parity = _popcount32(idx[:, None] & idx[None, :]) & 1
+    return np.where(parity == 1, -1.0, 1.0) / np.sqrt(float(n))
+
+
+def forward_source_index(j: int, hd_n: int, nk_n: int, rep_n: int) -> int:
+    """inverse of the reshape/permute llama.cpp applies: post-P column j -> source column."""
+    hd = j % hd_n
+    q = j // hd_n
+    nk = q // rep_n
+    rep = q % rep_n
+    return hd + hd_n * nk + hd_n * nk_n * rep
+
+
+def forward_dest_index(i: int, hd_n: int, nk_n: int, rep_n: int) -> int:
+    """the opposite direction: source column i -> post-P column (a negative control)."""
+    hd = i % hd_n
+    nk = (i // hd_n) % nk_n
+    rep = i // (hd_n * nk_n)
+    return hd + hd_n * rep + hd_n * rep_n * nk
+
+
+def rel_l2(got: np.ndarray, ref: np.ndarray) -> float:
+    denom = float(np.linalg.norm(ref))
+    if denom == 0.0:
+        return float(np.linalg.norm(got - ref))
+    return float(np.linalg.norm(got - ref) / denom)
+
+
+def evaluate(tag: str, k: int, tokens: int, hd_n: int, nk_n: int, rep_n: int, inverse: bool,
+             dump_dir: str, H: np.ndarray) -> bool:
+    x = np.fromfile(os.path.join(dump_dir, tag + ".in.f32"), dtype=np.float32).astype(np.float64)
+    s = np.fromfile(os.path.join(dump_dir, tag + ".signs.f32"), dtype=np.float32).astype(np.float64)
+    got = np.fromfile(os.path.join(dump_dir, tag + ".out.f32"), dtype=np.float32).astype(np.float64)
+    x = x.reshape(k, tokens)
+    got = got.reshape(k, tokens)
+
+    blocks = k // BLOCK
+    permuted = (not inverse) and rep_n > 1
+
+    def blockwise_hadamard(vec: np.ndarray) -> np.ndarray:
+        out = np.empty_like(vec)
+        for b in range(blocks):
+            lo = b * BLOCK
+            out[lo:lo + BLOCK] = H @ vec[lo:lo + BLOCK]
+        return out
+
+    def permute(vec: np.ndarray, src) -> np.ndarray:
+        return np.array([vec[src(j)] for j in range(k)], dtype=np.float64)
+
+    # Build every variant as a full [k, tokens] array so the comparison never broadcasts.
+    columns: dict[str, list[np.ndarray]] = {}
+    for t in range(tokens):
+        col = x[:, t]
+        if inverse:
+            current = {
+                "CORRECT  s*(H*z)": s * blockwise_hadamard(col),
+                "WRONG    H*(s*z)": blockwise_hadamard(s * col),
+                "WRONG    H*z": blockwise_hadamard(col),
+                "WRONG    s*z": s * col,
+            }
+        else:
+            base = col if not permuted else permute(
+                col, lambda j: forward_source_index(j, hd_n, nk_n, rep_n))
+            # one sign row off: block b uses sign row b-1
+            shifted = np.empty_like(s)
+            for b in range(blocks):
+                src = ((b - 1) % blocks) * BLOCK
+                dst = b * BLOCK
+                shifted[dst:dst + BLOCK] = s[src:src + BLOCK]
+            current = {
+                "CORRECT  H*(s*(P*x))": blockwise_hadamard(s * base),
+                "WRONG    s*(H*(P*x))": s * blockwise_hadamard(base),
+                "WRONG    unnormalized H": blockwise_hadamard(s * base) * np.sqrt(BLOCK),
+                "WRONG    sign row shifted": blockwise_hadamard(shifted * base),
+            }
+            if permuted:
+                current["WRONG    H*(s*x) no P"] = blockwise_hadamard(s * col)
+                current["WRONG    P the other way"] = blockwise_hadamard(
+                    s * permute(col, lambda j: forward_dest_index(j, hd_n, nk_n, rep_n)))
+        for name, value in current.items():
+            columns.setdefault(name, []).append(value)
+
+    variants = {name: np.stack(cols, axis=1) for name, cols in columns.items()}
+    correct_name = "CORRECT  s*(H*z)" if inverse else "CORRECT  H*(s*(P*x))"
+    ref = variants[correct_name]
+
+    correct = rel_l2(got, ref)
+    print(f"case {tag:9s} k={k:<6d} tokens={tokens} perm={permuted}")
+    print(f"  norms: ||x||={np.linalg.norm(x):.6g} ||ref||={np.linalg.norm(ref):.6g} "
+          f"||got||={np.linalg.norm(got):.6g}  ratio={np.linalg.norm(got) / np.linalg.norm(ref):.6g}")
+    ok = correct <= 0.01
+    print(f"  {'PASS' if ok else 'FAIL'}  CORRECT variant          rel_l2={correct:.3e}")
+    separation = True
+    for name, value in variants.items():
+        if name.startswith("CORRECT"):
+            continue
+        r = rel_l2(got, value)
+        good = r > 10.0 * max(correct, 1e-6)
+        separation = separation and good
+        print(f"        {name:26s} rel_l2={r:.4f}  {'(differs OK)' if good else '(TOO CLOSE)'}")
+    return ok and separation
+
+
+def main() -> int:
+    dump_dir = sys.argv[1]
+    H = hadamard(BLOCK)
+    print(f"oracle: explicit normalized Sylvester-Hadamard {BLOCK}x{BLOCK} "
+          f"(H[i][j] = popcount(i&j)&1 ? -1 : +1, /sqrt({BLOCK}))")
+    print(f"        symmetric={np.allclose(H, H.T)}  orthogonal={np.allclose(H @ H, np.eye(BLOCK), atol=1e-9)}")
+    results = []
+    for tag, k, tokens, hd_n, nk_n, rep_n, inverse in CASES:
+        results.append(evaluate(tag, k, tokens, hd_n, nk_n, rep_n, inverse, dump_dir, H))
+        print()
+    passed = sum(1 for r in results if r)
+    print(f"RESULT: {passed}/{len(results)} cases pass (correct variant matches AND all "
+          f"negative controls separate)")
+    return 0 if passed == len(results) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())