Super-squash branch 'main' using huggingface_hub

.gitattributes

@@ -0,0 +1,34 @@
+# Fermion Research — Hugging Face LFS patterns.
+# Order matters: later matching rules override earlier ones.
+
+# ---------------------------------------------------------------
+# Weights, transports and other large binaries -> Git LFS.
+# These MUST be LFS. The 8B container is 3.9 GB and its GGUF is
+# 4.1 GB; committed as plain blobs the push fails outright.
+# ---------------------------------------------------------------
+*.bin          filter=lfs diff=lfs merge=lfs -text
+*.tv4z         filter=lfs diff=lfs merge=lfs -text
+*.gguf         filter=lfs diff=lfs merge=lfs -text
+*.safetensors  filter=lfs diff=lfs merge=lfs -text
+*.pt           filter=lfs diff=lfs merge=lfs -text
+*.pth          filter=lfs diff=lfs merge=lfs -text
+*.ckpt         filter=lfs diff=lfs merge=lfs -text
+*.npz          filter=lfs diff=lfs merge=lfs -text
+*.onnx         filter=lfs diff=lfs merge=lfs -text
+*.msgpack      filter=lfs diff=lfs merge=lfs -text
+*.tar          filter=lfs diff=lfs merge=lfs -text
+*.tar.gz       filter=lfs diff=lfs merge=lfs -text
+*.zip          filter=lfs diff=lfs merge=lfs -text
+
+# Prebuilt native runtimes shipped in bin/ (multi-MB executables).
+# Listed explicitly rather than as bin/fermion-run-*: the Hub resolves LFS by
+# "does any filter=lfs pattern match" and does NOT honour a later `-filter`
+# unset, so a glob here would drag the tiny .sha256 sidecars into LFS too and
+# they would render as pointer files instead of the sha line.
+bin/fermion-run-linux-x64   filter=lfs diff=lfs merge=lfs -text
+bin/fermion-run-macos-arm64 filter=lfs diff=lfs merge=lfs -text
+
+# Tokenizer vocab: 11.4 MB, over the Hub's 10 MB non-LFS limit.
+# (Must come AFTER any *.json rule to win. There is none, by design:
+# every other .json here is a few KB and belongs in plain git.)
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,202 @@
+                                 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 2026 Fermion Research
+
+   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.
+

MANIFEST.json

@@ -0,0 +1,257 @@
+{
+ "note": "provenance: HF-tree filename -> source + sha256; weights entry is declarative until materialized",
+ "weights_container": {
+  "file": "neutrino-0.6b_v4.bin",
+  "status": "FINAL \u2014 0.6B base ship container (card + gguf + mlx pack gated on these bytes)",
+  "bytes": 327719836,
+  "sha256": "91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399",
+  "source": "Fermion Research release archive (public copy: huggingface.co/fermionresearch/Neutrino-0.6B)"
+ },
+ "files": {
+  ".gitattributes": {
+   "bytes": 1829,
+   "sha256": "83f9874d64fc325a932d03f7e71d75895113b7faf57cfe78d759fd8ac4f514c5",
+   "source": "banked lane artifact"
+  },
+  "LICENSE": {
+   "bytes": 11347,
+   "sha256": "2f978a54ef89f3e4ee2d413c347e4b03500c95f29342277a287acc2ae27ae280",
+   "source": "Apache-2.0 text (same file across all release trees)"
+  },
+  "NOTICE": {
+   "bytes": 1561,
+   "sha256": "6b7f7ed0cbf486ac68240e223d551eabdeb1d6dba59ed614f04316780437e643",
+   "source": "banked lane artifact"
+  },
+  "bin/README.md": {
+   "bytes": 11489,
+   "sha256": "d0e8d9e0e647013f79fd9ecb28a9ac0dac00e418d28e51e2a6f4610716be27bb",
+   "source": "bin/ staging doc: which fermion-run binaries land at upload + sidecar convention"
+  },
+  "bin/fermion-run-linux-x64": {
+   "bytes": 1317208,
+   "sha256": "d3e1c3d7a7fe43e9dd4d6e16e75c0cd234bfc9866964284101d200f3da05310b",
+   "source": "RE-BLESSED release binary (Linux x86-64 AVX2 baseline, fully static) \u2014 0.1.10 fp16-KV + YaRN rebuild 2026-07-28"
+  },
+  "bin/fermion-run-linux-x64.sha256": {
+   "bytes": 88,
+   "sha256": "44b26f8fd77232280a3a9ac7576487ceaeeaf4170f89f9f6334a623ee88acfa0",
+   "source": "sha256 sidecar (shasum line) for fermion-run-linux-x64"
+  },
+  "bin/fermion-run-macos-arm64": {
+   "bytes": 671656,
+   "sha256": "2b9902fc36bf59c50a67ee0c79ae38a259d066e6ebff764abbf05ff72017351c",
+   "source": "RE-BLESSED release binary (macOS arm64 CPU/NEON, static libomp) \u2014 0.1.10 fp16-KV + YaRN rebuild 2026-07-28"
+  },
+  "bin/fermion-run-macos-arm64.sha256": {
+   "bytes": 90,
+   "sha256": "8bc33f96ac8c95ee842c741aa91ac1a4aef051deae4ba55ed3a3d246d0af9743",
+   "source": "sha256 sidecar (shasum line) for fermion-run-macos-arm64"
+  },
+  "config.json": {
+   "bytes": 503,
+   "sha256": "67cae94190633a2ea52435c0b159202e9c16f8196e110c7a2639cb28736ae972",
+   "source": "written for the trtc_v4 loader (hf_ternary registration)"
+  },
+  "generation_config.json": {
+   "bytes": 181,
+   "sha256": "2537909d4312b7155b60fe0aee96d342de1a00b7841ed3e7eba4c3835d16d8ae",
+   "source": "transformers generation defaults for this SKU"
+  },
+  "gguf/Modelfile": {
+   "bytes": 275,
+   "sha256": "af5261e7e6f6f0e2f52895f2f1c165f6d7c058b93628fa54e4d8fb35c82aad2a",
+   "source": "banked lane artifact"
+  },
+  "gguf/README.md": {
+   "bytes": 6650,
+   "sha256": "16657bac673140b0cef77afb68af869f2f1dc39887d36bfc77eb7d94176bd95c",
+   "source": "banked lane artifact"
+  },
+  "gguf/SHA256SUMS": {
+   "bytes": 501,
+   "sha256": "96d97263ff5e276b7852a08aa52eca9e49418fbdc8671f60e5d1c6d73a18779d",
+   "source": "banked lane artifact"
+  },
+  "gguf/receipts/bench_0p6b.json": {
+   "bytes": 2667,
+   "sha256": "1e22cc409b85626efa44b8d26fa5cc2cb93124f841aff76eb5df8d7347933d40",
+   "source": "banked lane artifact"
+  },
+  "gguf/receipts/convert_0p6b.json": {
+   "bytes": 949,
+   "sha256": "176ff8191f00257a913595e20da2b4bdbdbc994f48364c67b049b7a753d23d0b",
+   "source": "banked lane artifact"
+  },
+  "gguf/receipts/gv_0p6b_f32.json": {
+   "bytes": 461,
+   "sha256": "d2ddf55b1cbfc24125292683f3eb08cc2de37c3a8f4147f638f135277fd7d187",
+   "source": "banked lane artifact"
+  },
+  "gguf/receipts/gv_0p6b_fv5.json": {
+   "bytes": 460,
+   "sha256": "b87c0411e2644fb03b4f00d187751757b3eb4960238df55fbf10c348154881cc",
+   "source": "banked lane artifact"
+  },
+  "gguf/receipts/ref_0p6b.json": {
+   "bytes": 471,
+   "sha256": "5b294b8fe3653662e6baec494fcc821097bca9ff2a4318552b9583fbc1fd42bd",
+   "source": "banked lane artifact"
+  },
+  "merges.txt": {
+   "bytes": 1671853,
+   "sha256": "8831e4f1a044471340f7c0a83d7bd71306a5b867e95fd870f74d0c5308a904d5",
+   "source": "Qwen/Qwen3-8B tokenizer file (Apache-2.0 upstream)"
+  },
+  "mlx/MANIFEST.json": {
+   "bytes": 5342,
+   "sha256": "3ba9ba4932cc98c91a634bd96e43c6305d644dc73e9aabf886b9130a5b2014bb",
+   "source": "banked lane artifact"
+  },
+  "mlx/README.md": {
+   "bytes": 5392,
+   "sha256": "c32d9fa4f7dbbc53ecdad2131c1e33596e57f6045acc8f0790a9d2431f014b11",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/__init__.py": {
+   "bytes": 5063,
+   "sha256": "a547844d587067681639df546e6d010dab80bbd4f0ee55c6e2a16fba97a1dd40",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/__main__.py": {
+   "bytes": 8069,
+   "sha256": "71e8c7fea446184bd471af2c37e51b04b9fa8d0f5d35e0a76c31f6fd19af957d",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/arch3.py": {
+   "bytes": 7541,
+   "sha256": "a831e8a24b2b9a986b393d1c316aac66a3399a082a57176254b2feeae032f8cd",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/container.py": {
+   "bytes": 6059,
+   "sha256": "c5b352184ba9ddf9a3e424731226cb7dcb9901d3a1516c67d4557953b0101f2f",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/gates.py": {
+   "bytes": 7394,
+   "sha256": "64d07d9ba1a783a3f56ba978da7885e9fbe693495b3a4b7b8e176607d59de52c",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/mbatch.py": {
+   "bytes": 6492,
+   "sha256": "c9ec8d37f1cdc0554cda01cefbc435e67525779c79e0dac7fd760e7919e6fdd2",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/model.py": {
+   "bytes": 12748,
+   "sha256": "9488f8194ce8be006ce05dfaf6118353de44005ce54f38f73a0908ccac2749da",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/spec.py": {
+   "bytes": 11207,
+   "sha256": "969e946d5d2eeb63d44afa4c62dd2453d87fa14e83b936bc673482b59ee3b745",
+   "source": "banked lane artifact"
+  },
+  "mlx/fermion_mlx/trit_kernels.py": {
+   "bytes": 44135,
+   "sha256": "aeb8bd4b03419763c1543893f19be3b4029611b2df883096990c4beebade384b",
+   "source": "banked lane artifact"
+  },
+  "mlx/generation_config.json": {
+   "bytes": 181,
+   "sha256": "6ca52b0bcb818c9e52db8ea18413494110c5f2def581b769f621dda951a7863b",
+   "source": "banked lane artifact"
+  },
+  "mlx/merges.txt": {
+   "bytes": 1671853,
+   "sha256": "8831e4f1a044471340f7c0a83d7bd71306a5b867e95fd870f74d0c5308a904d5",
+   "source": "banked lane artifact"
+  },
+  "mlx/receipts/bench_0p6b_m5.json": {
+   "bytes": 812,
+   "sha256": "543a9e41d8374a8cd066643a4e7cfa925359a8efc9c3182cbebb366bb0afbe89",
+   "source": "banked lane artifact"
+  },
+  "mlx/receipts/cachegate_0p6b.json": {
+   "bytes": 775,
+   "sha256": "b6acd64a31f4529ea01b96103a44b5bc54da283a7c3250cd564b5510ebaabc8c",
+   "source": "banked lane artifact"
+  },
+  "mlx/receipts/kernel_version_sweep_0p6b.json": {
+   "bytes": 355,
+   "sha256": "6b0df2026ded00c50d6b34004bf2dc4aabf097d21decfad7a354de5be594fe87",
+   "source": "banked lane artifact"
+  },
+  "mlx/receipts/pathgate_0p6b.json": {
+   "bytes": 623,
+   "sha256": "2453e15509a012616a100e3767a373af20a763dff89104e3c4dfbeb24085d072",
+   "source": "banked lane artifact"
+  },
+  "mlx/receipts/refgate_0p6b.json": {
+   "bytes": 1907,
+   "sha256": "ee4b3949bad85a522f1d1b65344a230a40f9fe9dc5e5dfdca736c28751eb4d85",
+   "source": "banked lane artifact"
+  },
+  "mlx/requirements.txt": {
+   "bytes": 191,
+   "sha256": "1cf4d1fa581aaa5deae0568f88388c51166bbd69e7a89080b5a53488a7ef39b6",
+   "source": "banked lane artifact"
+  },
+  "mlx/tokenizer.json": {
+   "bytes": 11422654,
+   "sha256": "aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4",
+   "source": "banked lane artifact"
+  },
+  "mlx/tokenizer_config.json": {
+   "bytes": 9732,
+   "sha256": "d5d09f07b48c3086c508b30d1c9114bd1189145b74e982a265350c923acd8101",
+   "source": "banked lane artifact"
+  },
+  "mlx/vocab.json": {
+   "bytes": 2776833,
+   "sha256": "ca10d7e9fb3ed18575dd1e277a2579c16d108e32f27439684afa0e10b1440910",
+   "source": "banked lane artifact"
+  },
+  "receipts/hf_greedy_cache_86565bf6.json": {
+   "bytes": 3578,
+   "sha256": "f8e81dd6b582c4097cf49b2abbc10b9e233331e60df7ebc4e03bcc587ec8f7e3",
+   "source": "banked lane artifact"
+  },
+  "receipts/m5_bitgate_analysis.json": {
+   "bytes": 1751,
+   "sha256": "26ef236f04d2bf0957ae9206f660898e3a73947bda272085e07e5523c4ac2979",
+   "source": "banked lane artifact"
+  },
+  "receipts/m5_demo_rereceipt_p3.json": {
+   "bytes": 1740,
+   "sha256": "aff7397eec5146a0418523140fa7531fc748b6c5229bb34c8b76f0eb8f73776b",
+   "source": "banked lane artifact"
+  },
+  "receipts/receipt_base.json": {
+   "bytes": 890,
+   "sha256": "2ae4accabe018f8efb1e0434ef63c8347e9cd096de74456f9887cfe5c874b117",
+   "source": "banked lane artifact"
+  },
+  "receipts/ship_checkpoint_numbers.json": {
+   "bytes": 1635,
+   "sha256": "95e757373209d99fdf1a3381d6f4a124e588a90ad01b2ae21b105db83349c29d",
+   "source": "banked lane artifact"
+  },
+  "tokenizer.json": {
+   "bytes": 11422654,
+   "sha256": "aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4",
+   "source": "Qwen/Qwen3-8B tokenizer file (Apache-2.0 upstream)"
+  },
+  "tokenizer_config.json": {
+   "bytes": 9979,
+   "sha256": "02e7044c846290e910d9c9deca9812315d64be56a6aeee3cfbedc99d177644c4",
+   "source": "Qwen/Qwen3-8B tokenizer file (Apache-2.0 upstream)"
+  },
+  "vocab.json": {
+   "bytes": 2776833,
+   "sha256": "ca10d7e9fb3ed18575dd1e277a2579c16d108e32f27439684afa0e10b1440910",
+   "source": "Qwen/Qwen3-8B tokenizer file (Apache-2.0 upstream)"
+  }
+ }
+}

NOTICE

@@ -0,0 +1,43 @@
+Neutrino — Fermion Research
+Copyright 2026 Fermion Research
+
+This product includes software and model artifacts developed by
+Fermion Research, licensed under the Apache License, Version 2.0
+(see LICENSE).
+
+--------------------------------------------------------------------
+THIRD-PARTY NOTICES
+--------------------------------------------------------------------
+
+Qwen3 (Alibaba Cloud / Qwen Team)
+Copyright (c) Alibaba Cloud
+Licensed under the Apache License, Version 2.0
+https://huggingface.co/Qwen/Qwen3-0.6B
+
+This model is a derivative of Qwen/Qwen3-0.6B. In particular, the following
+files in this repository are redistributed VERBATIM from the upstream
+Qwen3 release and are covered by Alibaba Cloud's copyright and the
+Apache License 2.0:
+
+  tokenizer.json
+  tokenizer_config.json
+  vocab.json
+  merges.txt
+
+The model architecture is stock Qwen3 geometry. The ternary
+quantization-aware training, the TRTC v4 container format, the
+post-training, the runtimes and the evaluation receipts are Fermion
+Research's own work.
+
+You may obtain a copy of the Apache License 2.0 at:
+  http://www.apache.org/licenses/LICENSE-2.0
+
+--------------------------------------------------------------------
+
+llama.cpp (The ggml authors) — MIT License
+
+The GGUF pack in gguf/ is produced for, and loaded by, Fermion
+Research's fork of ggml-org/llama.cpp. That fork is distributed
+separately under upstream's MIT license, NOT under this repository's
+Apache-2.0 grant. Any patch or source in gguf/ that derives from
+llama.cpp is MIT-licensed; see the fork's own LICENSE.

README.md

@@ -0,0 +1,496 @@
+---
+license: apache-2.0
+base_model: Qwen/Qwen3-0.6B
+pipeline_tag: text-generation
+library_name: transformers
+tags:
+  - ternary
+  - quantization
+  - trtc
+  - small-model
+  - speculative-decoding
+---
+
+# Neutrino-0.6B (certified speculative-decoding draft for Neutrino-8B)
+
+> [!IMPORTANT]
+> **This model exists for one purpose: it is the certified
+> speculative-decoding DRAFT for
+> [Neutrino-8B](https://huggingface.co/fermionresearch/Neutrino-8B).**
+> Paired with the 8B it delivers certified-exact speculative decoding
+> (27,648 spec tokens compared on the ship brain, zero mismatches; 41,472
+> across the whole lane, zero mismatches anywhere). It is **not an
+> assistant**: no chat tuning, no instruction following, no tool use, and
+> its standalone knowledge is deliberately not a claim. If you want a small
+> model to talk to, use
+> [Neutrino-0.6B-Chat](https://huggingface.co/fermionresearch/Neutrino-0.6B-Chat).
+
+A 596M-parameter base language model whose every transformer linear is
+stored in a proprietary ternary-family weight format eight times smaller
+than fp16, in a single 327,719,836-byte container (237,703,560 bytes on the
+wire), decoding at **225-236 tok/s on the CPU cores of a 16 GB Apple M5**
+with the same runtime binaries that execute Neutrino-8B. That last property
+is what makes it a draft model rather than a separate deployment: the
+verifier and the draft are the same format, read by the same code, in one
+process.
+
+This is the small end of the Neutrino family, shipped as the 8B's speed
+companion. The honest capability numbers are in the battery below; read
+them before using it for anything but its intended lane (drafting,
+edge/embedded token generation, and as a reference artifact for
+ternary-family QAT at tiny scale).
+
+- Container: `neutrino-0.6b_v4.bin` - TRTC v4, arch-3, 28 layers, hidden
+  1024, vocab 151936. 327,719,836 bytes, sha256
+  `91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399`
+  (working name in receipts: `neutrino-0p6b_v4_base.bin`; the same bytes
+  appear as `neutrino_v4.bin` in the speculative-decoding lane).
+- Coded transport: `neutrino-0.6b_v4.tv4z` - 237,703,560 bytes, lossless,
+  byte-exact round-trip receipt banked; sha256
+  `132d9ab758b0b1a5b9b6638e55647462dbdb4ec8345720cc98c3d4cf669e780c`.
+- Inside: 196 packed ternary linears + one int8 embedding lane (**tied**:
+  the input embedding and lm_head share one table; container walk
+  cross-checked in the internal anatomy audit, and the GGUF
+  conversion records `tied_output_omitted: true`). Nothing in the decode
+  path is fp16/fp32 weights.
+- Base: [Qwen/Qwen3-0.6B](https://huggingface.co/Qwen/Qwen3-0.6B)
+  (Apache-2.0), ternary QAT by
+  [Fermion Research](https://huggingface.co/fermionresearch).
+  Tokenizer shipped in this repo; vocabulary identical to the 8B's,
+  identity receipt banked, which is a precondition for drafting.
+
+## Architecture
+
+Geometry as read from the shipped container's header (bit-checked during
+the GGUF conversion, `gguf/receipts/convert_0p6b.json`; parameter split and
+byte budget from the provenance-gated container walk):
+
+| field | value |
+|---|---|
+| Parameters | 596,049,920 (440,401,920 ternary projection + 155,582,464 int8 embedding + 65,536 fp32 norm) |
+| Decoder layers | 28 |
+| Hidden width | 1,024 |
+| Feed-forward width | 3,072, gated (SwiGLU) |
+| Attention | grouped-query 2:1 - 16 query heads, 8 KV heads, head_dim 128 |
+| Rotary embedding | full head width (rotary_dims 128), theta 1,000,000 |
+| Normalization | RMSNorm, eps 1e-6, plus per-head Q/K RMSNorm in attention |
+| Context length | 40,960 tokens (`max_pos`) |
+| Vocabulary | 151,936 |
+| Embeddings | **tied** - one int8 table serves embed-in and lm_head (`eok=1`) |
+| KV cache | 114,688 B/token fp16 (112 KiB): 0.47 GB @ 4k, 3.76 GB @ 32k |
+| Coded lane | 196 ternary linears (7 per layer x 28); 113 fp32 norm tensors stay full precision |
+
+Byte budget of the 327,719,836-byte container, by tensor class:
+
+| lane | bytes | share |
+|---|---:|---:|
+| ternary weight lane (q/k/v/o/gate/up/down x 28 layers = 196 linears) | 165,150,720 | 50.39% |
+| token embeddings, int8 (one tied table) | 155,582,464 | 47.47% |
+| per-row metadata (dims, scales, row sums) | 5,508,960 | 1.68% |
+| embedding row scales | 1,215,488 | 0.37% |
+| norm vectors, fp32 (113 tensors) | 262,144 | 0.08% |
+| container header | 60 | - |
+
+Every layer costs exactly 5,898,240 weight-lane bytes (40.0% attention /
+60.0% MLP; the 8B's split is 21.7% / 78.3%). State occupancy across the
+440,401,920 ternary weights: 62.263% zero / 18.873% plus / 18.864% minus
+(per-layer arrays in the internal anatomy audit).
+
+**The scale story in one row.** The tied embedding table is 26.1% of the
+parameters but 47.5% of the container's bytes, because the format only
+touches the transformer linears and the int8 vocabulary is left alone. On
+the 8B the same lane is 32.1% of the file. At this size the vocabulary,
+not the network, is the largest single object you download.
+
+## Formats and artifacts
+
+| artifact | bytes | sha256 |
+|---|---:|---|
+| `neutrino-0.6b_v4.bin` (TRTC v4 container, the file every runtime executes) | 327,719,836 | `91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399` |
+| `neutrino-0.6b_v4.tv4z` (lossless coded transport, 72.5% of raw) | 237,703,560 | `132d9ab758b0b1a5b9b6638e55647462dbdb4ec8345720cc98c3d4cf669e780c` |
+| `gguf/neutrino-0.6b-base-fv5.gguf` (llama.cpp-fork pack, 310/310 tensors bit-checked vs the container) | 343,140,320 | `dd9354c4b3cd2b34195b0270540e4fa5db3811e42b6e4bdbd57958e0027e9272` |
+| `gguf/fv5.patch` (the llama.cpp patch that builds the fork) | - | `81bf7be5eef18eb98ab4823596374c8dd6615151cf5615425973cb65942c0f73` |
+
+Container md5 for cross-checking older receipts:
+`86565bf6183e8031943aac9fd9771385`.
+
+## Quickstart
+
+Five surfaces read those artifacts. All five execute the same container.
+
+**1. pip engine** (the one-command door; pulls the container and the
+platform-matching native runtime):
+
+```bash
+pip install fermion-research
+fermion generate --model fermionresearch/Neutrino-0.6B \
+    --raw --max-new 64 "2, 3, 5, 7, 11,"  # base model: --raw skips the chat template; the prompt is positional
+```
+
+The first run downloads the ~0.3 GB container with no progress display in
+fermion 0.1.5; from 0.1.6 the download shows a progress bar. Later runs
+load from the local cache.
+
+**2. Reference torch path** (bit-packed weights at rest, registers as a
+native `transformers` model). Download the repo first — the loader
+resolves the container relative to a local path only, so passing the hub
+id straight to `from_pretrained` raises `FileNotFoundError`:
+
+```bash
+hf download fermionresearch/Neutrino-0.6B --local-dir Neutrino-0.6B \
+    --exclude "gguf/*" --exclude "*.tv4z"   # skip the packs other runtimes use
+```
+
+```python
+import fermion  # registers the trtc_v4 model type
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("Neutrino-0.6B")   # the downloaded directory
+tokenizer = AutoTokenizer.from_pretrained("Neutrino-0.6B")
+ids = tokenizer("2, 3, 5, 7, 11,", return_tensors="pt").input_ids
+print(tokenizer.decode(model.generate(ids, max_new_tokens=64)[0]))
+```
+
+This is a BASE model: prompt it as a completion engine. Greedy decoding
+produces repetitive text on open-ended prompts (typical for 0.6B base
+models); use sampling for anything user-facing.
+
+`import fermion` must come first: it registers the `trtc_v4` model type.
+Without it Transformers raises `model type 'trtc_v4' ... not recognize this
+architecture` and advises upgrading Transformers or installing it from
+source. Both are dead ends — the type is registered at import time by the
+`fermion-research` package, and `trust_remote_code=True` will not help
+because this repo carries no `auto_map`. Add the import.
+
+**3. Native binary** (the fast path; this repo ships the `fermion-run-*`
+binaries under `bin/` — they execute TRTC v4 arch-3 containers
+generically, so the same binaries also run the 8B with no rebuild). From
+the downloaded repo directory:
+
+```bash
+(cd bin && shasum -a 256 -c fermion-run-macos-arm64.sha256)   # sidecar holds a bare filename
+chmod +x bin/fermion-run-macos-arm64                          # hf download writes 0644
+xattr -d com.apple.quarantine bin/fermion-run-macos-arm64 2>/dev/null || true  # macOS only
+./bin/fermion-run-macos-arm64 neutrino-0.6b_v4.bin "1,791,1283" 128 9   # ids, n_new, threads
+```
+
+On Linux use `bin/fermion-run-linux-x64` and skip the `xattr` line.
+
+**4. GGUF pack + our llama.cpp fork** (also the draft-model file for
+llama.cpp's native speculative decoding against the 8B pack). The fork is
+public at [fermionresearch/llama.cpp](https://github.com/fermionresearch/llama.cpp),
+branch `fermion-fv5` (= upstream `ggml-org/llama.cpp` @ `d67c0b41` + the
+FV5 patch; `gguf/fv5.patch` in this repo is the same change as a mailbox
+patch):
+
+```bash
+hf download fermionresearch/Neutrino-0.6B gguf/neutrino-0.6b-base-fv5.gguf --local-dir .
+git clone https://github.com/fermionresearch/llama.cpp && cd llama.cpp
+git checkout fermion-fv5
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_CURL=OFF -DGGML_METAL=OFF  # no FV5 Metal kernel yet: CPU path
+cmake --build build -j --target llama-completion
+./build/bin/llama-completion -m ../gguf/neutrino-0.6b-base-fv5.gguf \
+    -p "2, 3, 5, 7, 11," -n 128 --temp 0 -no-cnv
+```
+
+**5. MLX pack** (Apple-silicon runtime with custom Metal kernels). Run it
+from the `mlx/` folder of the downloaded repo — the `fermion_mlx` package
+and its tokenizer files ship there, and `requirements.txt` installs `mlx`
+itself:
+
+```bash
+cd Neutrino-0.6B/mlx        # the directory downloaded in step 2
+pip install -r requirements.txt
+python -m fermion_mlx --model ../neutrino-0.6b_v4.bin --mode gen \
+    --tokenizer . --prompt "2, 3, 5, 7, 11,"
+```
+
+## Recommended settings, by use case
+
+| use case | settings | why |
+|---|---|---|
+| **draft model for Neutrino-8B** | **inherit the verifier — set nothing** | The draft's sampler cannot change *what* is emitted. Under greedy the verifier's own argmax decides acceptance; under HF-assisted sampling the correction re-weights by `p_i/q_i`. Tuning the draft is a throughput knob, never a quality knob. |
+| **benchmark / completion reproduction** | greedy, no penalty, no top-k — this repo's shipped `generation_config.json` | Everything in the Evaluation section was measured this way, so a bare `model.generate()`, an `lm-eval` run and `fermion generate` all reproduce each other. |
+| **user-facing chat** | use [Neutrino-0.6B-Chat](https://huggingface.co/fermionresearch/Neutrino-0.6B-Chat) instead | This SKU has no chat post-training; every graded conversational number in the family belongs to the -Chat container. |
+
+`generation_config.json` here is `do_sample: false`, no `temperature`, no
+`top_k`, no `top_p`, no `repetition_penalty` — deliberately empty of sampler
+opinion, so nothing silently overrides a harness. Top-k is not exposed on any
+runtime we ship; note that llama.cpp and ollama default to top-k 40, which is
+why the `Modelfile` in `gguf/` pins it to 0.
+
+## Speed
+
+| Surface | Machine | Rate | Memory / protocol |
+|---|---|---:|---|
+| native `fermion-run`, CPU only | Apple M5 | **225-236 tok/s** | 9 threads, 128-token greedy, mmap; per-prompt 232.89 / 224.52 / 233.56, demo median 225.37 (`receipts/m5_demo_rereceipt_p3.json`) |
+| MLX 0.31.2 + Metal | Apple M5, 16 GB | **201.16 tok/s** | median of 5 (197.19-202.03), peak 0.526 GiB, 512-token greedy, 9-token prompt (`mlx/receipts/bench_0p6b_m5.json`) |
+| GGUF pack via `fermion-fv5` | CPU, 16 threads | **55.38 tok/s** tg128 (+/-0.30) | pp512 132.18, build e07b3ec (`gguf/receipts/bench_0p6b.json`) |
+| C-served draft walker inside the 8B's process | H100 | **1,177 tok/s** | 0.85 ms/token standalone, graph == eager on a 24-token identity |
+
+## Evaluation battery (this exact container, `91c0b26d...`)
+
+Measured on the shipped checkpoint with frozen,
+receipted meters. Stack pins: lm-eval **0.4.8**, datasets 3.6.0,
+transformers 4.53.2, grade_probe `b279c53e`; generative rows evalscope
+**1.4.2**; BFCL wheel **bfcl-eval 2025.10.27.1**. Canonical roll-up:
+`receipts/ship_checkpoint_numbers.json`.
+
+A 596M model at this storage depth reads LOW on knowledge-adjacent meters.
+That is expected, disclosed, and the reason this SKU's story is size,
+speed, and drafting rather than capability.
+
+### Knowledge and likelihood
+
+| Meter | Score | Protocol |
+|---|---:|---|
+| ARC-easy | **53.45** | lm-eval suite leg, 0-shot |
+| Winogrande | 53.43 | same |
+| PIQA | 62.79 | same |
+| BoolQ | 50.52 | same |
+| HellaSwag | 31.64 | same |
+| ARC-challenge | 24.06 | same |
+| OpenBookQA | 19.60 | same |
+| **Suite / commonsense average (7 tasks)** | **42.21** | mean of the seven rows above, 0-shot |
+| MMLU full-57 | 26.66 | likelihood, 14,042 items (near chance; the sub-7B knowledge-conversion floor is a banked house finding) |
+| MMLU subset-14 (frozen gate probe) | 27.50 | kprobe, `mmlu_subset 0.25`, seed 0, 14 named subtasks |
+| SciQ | 80.40 | 0-shot acc, lm-eval 0.4.8 (chance 25.0) |
+| COPA | 63.00 | 0-shot acc, lm-eval 0.4.8, n=100 (chance 50.0) |
+| MNLI, house meter | 35.45 | `e4_mnli_bitnet_parity`, label-token likelihood, validation_matched, full 9,815 (chance 33.3) |
+| MNLI, lm-eval stock | 34.18 | 0-shot acc, lm-eval 0.4.8. Not comparable to the house-meter row above: the two formulations differ, and both readings sit within 2 pp of the 3-class floor |
+| LAMBADA (openai) | 25.79 | 0-shot acc, lm-eval 0.4.8. Long-range last-word prediction is the capability that thins first at this scale, and it is the mechanical explanation for the GSM8K and termination cells below |
+
+fp32 reference constants for context, not re-run here: MMLU 46.9, suite
+53.5.
+
+### Generation, perplexity, behaviour
+
+| Meter | Score | Protocol |
+|---|---:|---|
+| C4 perplexity | **46.25** | 500,000 tokens, C4-val, fp32-bake meter, wall 1,329.9 s |
+| GSM8K flexible-extract | 1.67 | lm-eval `gsm8k`, 0-shot generative, first-N fixed subset limit=300, batch 8 |
+| GSM8K strict-match | 0.00 | same run |
+| GSM8K stated-format (house grader) | 1.67 | second greedy pass, `max_gen_toks=1024`, n=300 |
+| Termination rate | 0.23 | fraction of generations ending on EOS/stop within budget, GSM8K stated pass, cap 1024, n=300 |
+| IFEval prompt-strict | 14.88 | house IFEval leg, evalscope 1.4.2 (base model, no instruction tuning) |
+| BFCL v3 macro-13 | 15.38 | bfcl-eval 2025.10.27.1; degenerate never-calls profile (irrelevance 100.0 + live_irrelevance 100.0, all 10 calling subsets 0.0). **Do NOT use this model for function calling.** |
+| genfmt QA (house) | match 0.62 / well-formed 0.80 | 50-row house QA probe, `genfmt_max_new: 32` |
+
+Against its full-precision reference at the identical parameter count
+(596,049,920 on both sides), every cell graded by us on one harness on one
+day at zero shots: **81.6% of the reference's ability across the seven
+common tasks, at 15.8% of the bytes** (238 MB against 1,503 MB), and
+**78.0% averaged across all eleven tasks measured**. Best-retaining axes:
+Winogrande 91.5%, PIQA 90.4%. Rig, pins, revision gates, and the disclosed
+deviations (A10G rather than A100, per-row batch size) are receipted in
+the eval-receipts repo. This supersedes the earlier single-task ARC-easy read, which was one
+cell against a differently-sourced reference number.
+
+The SciQ, COPA, LAMBADA, and stock-MNLI cells were measured on this
+container on 2026-07-27 (A100-80GB, lm-eval 0.4.8, fp32-baked TritLinear
+path, same pins and bake as the suite above; run receipt
+in the eval-receipts repo, `grade_probe.py` sha `b279c53e...`,
+state sha gate PASS). Read them as absolute capability
+evidence and as a same-family comparison against our own 8B on the identical
+tasks (95.90 / 84.00 / 56.65 / 54.57). They are **not** competitive claims:
+a same-harness sub-1B cohort grid run on 2026-07-27
+(7 rival checkpoints x 11 tasks,
+77 cells) measures this model at or near the bottom of its cohort on most of
+those tasks. That grid is the calibrated read; use it rather than inferring
+a ranking from the absolute cells above.
+
+Not measured at this scale: MMLU-Redux (an 8B-line generative meter),
+wikitext perplexity (the house perplexity meter is C4-val only), and
+IFEval's loose/instruction variants (only prompt-strict was promoted from
+the raw report).
+
+### Correctness gates
+
+- MLX refgate vs `neutrino_ref.npz`: teacher-forced rel err max 1.74e-06,
+  argmax 9/9, greedy 24/24, **0 flips**; cachegate 0/256
+  (`mlx/receipts/refgate_0p6b.json`, `cachegate_0p6b.json`).
+- GGUF convert bit-compare: **310/310 CONVERT_PASS**
+  (`gguf/receipts/convert_0p6b.json`).
+- C-runtime bit gate: 221/384 raw positions as measured, diagnosed as
+  exactly 2 flat-margin argmax flips then greedy cascade (top-2 margins
+  0.02-0.20 logits); kernel output is deterministic across runs and
+  threads (`receipts/m5_bitgate_analysis.json`).
+- Export: double-export byte-determinism PASS, tv4z byte round-trip PASS,
+  fp32 HF expansion self-check PASS (rc=0) (`receipts/receipt_base.json`).
+
+### Reproducing the battery
+
+The model registers as a native `transformers` model (`import fermion`),
+so the public harnesses run directly.
+
+```python
+# first: hf download fermionresearch/Neutrino-0.6B --local-dir Neutrino-0.6B  (Quickstart 2)
+# lm-eval 0.4.12 needs accelerate for HFLM: pip install lm-eval accelerate
+import fermion, lm_eval
+from lm_eval.models.huggingface import HFLM
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("Neutrino-0.6B")   # the downloaded directory
+tok = AutoTokenizer.from_pretrained("Neutrino-0.6B")
+model.config.tie_word_embeddings = False  # tied inside the packed container; skip HF's re-tie
+lm = HFLM(pretrained=model, tokenizer=tok)
+lm_eval.simple_evaluate(model=lm, num_fewshot=0, tasks=[
+    "arc_easy", "arc_challenge", "boolq", "hellaswag",
+    "openbookqa", "piqa", "winogrande"])          # the suite-average row
+lm_eval.simple_evaluate(model=lm, tasks=["mmlu"], num_fewshot=5)
+lm_eval.simple_evaluate(model=lm, tasks=["gsm8k"], num_fewshot=0, limit=300)
+```
+
+IFEval and BFCL used the same frozen house meters as the 8B card, against
+a vLLM OpenAI-compatible endpoint:
+
+```bash
+pip install evalscope==1.4.2 bfcl-eval==2025.10.27.1
+evalscope eval --model Neutrino-0.6B --api-url http://127.0.0.1:8000/v1 \
+    --datasets ifeval bfcl_v3
+```
+
+Speed is re-measured with the shipped binary and the MLX pack:
+
+```bash
+./bin/fermion-run-macos-arm64 neutrino-0.6b_v4.bin "1,791,1283" 128 9   # from the repo dir (Quickstart 3)
+python -m fermion_mlx --model ../neutrino-0.6b_v4.bin --mode bench \
+    --tokenizer . --gen-tokens 512 --runs 5                             # from mlx/ (Quickstart 5)
+```
+
+Per-cell venue, version, and date receipts are in the eval-receipts repo.
+
+## As the 8B's draft (the reason this SKU exists)
+
+A 0.6B draft proposes k tokens; the 8B verifies all k in one batched
+forward pass and keeps the accepted prefix plus one token of its own. A
+proposal is accepted only when it equals the 8B's own argmax, so the
+output stream is the plain greedy stream: **speed changes, the text does
+not.**
+
+### The exactness certificate
+
+| Suite | Arms | Tokens compared | Result |
+|---|---|---:|---|
+| Ship-brain cert (8B `016c6f36...5fa0`) | dynamic draft length, draft = Neutrino-0.6B + confidence head | **27,648** | **0 mismatches** (re-run 2026-07-27 against the shipping 8B container) |
+| dynamic-k cert (earlier internal 8B baseline verifier) | dynamic + k in {2..6} x 9 prompts x 512 | 27,648 | PASS, all IDENTICAL |
+| **Story leg: this base container as the draft, no distillation, no confidence head** | k in {3,4,5} x 9 x 512 | **13,824** | **PASS, all IDENTICAL** |
+| forced-reject floors (both drafts) | k=1 dynamic / k in {3,5} fixed | 256 each | output EXACT |
+| **Lane total** | - | **41,472** | **zero mismatches anywhere** |
+
+Venue: Modal H100, 2026-07-26. The certification receipt ships in the
+Neutrino-8B repo (`receipts/`).
+
+### Speedup by prompt class (ship brain, H100, 3-round median, baseline 395.9 tok/s)
+
+| Class | Speedup | tok/s | Acceptance behaviour |
+|---|---:|---:|---|
+| counting | **x1.93** | 762.6 | 100% of drafted tokens accepted (k=6 probe: all 6 survive every verify pass, 74 passes per 512 tokens, ~7 tokens emitted per 8B forward) |
+| facts | x1.55 | 613.0 | 96.5% survive (5.8 of 6 per pass) |
+| prose | x1.34 | 531.9 | free-form narrative |
+| chat explanation | x1.13 | 446.6 | the controller often disables drafting and pays a small resync cost |
+| code | x1.07 | 426.1 | hardest class for the draft |
+
+Acceptance decays with draft length everywhere except facts (97-99% flat),
+which is why the controller rides long drafts on facts and explanation
+(histogram mass at k=7), drops to 1-2-token drafts on code and counting,
+and turns itself off on chat explanation.
+
+### Out of the box, without distillation
+
+This shipped base container was never trained for drafting and carries no
+confidence head, and it still certifies: 13,824 tokens, all identical,
+run as a fixed-k draft. Bench medians on H100: k=4 facts **610.8 (x1.61)**,
+k=5 facts **648.9 (x1.71)**, k=5 explanation/mmlu x1.54, prose k=4-5
+x1.29-1.40. Fixed-k has no disable machinery, so its floor classes drop
+below 1.0 (x0.46 at k=3, x0.34 at k=5); the dynamic controller with the
+distilled draft floors at x0.75. The distillation then buys +10 to +25
+percentage points of acceptance (prose 93.6 against ~70-77, code 85
+against ~50) plus the confidence head and dynamic-k layer.
+
+### On Apple silicon
+
+The pair runs in one process on a 16 GB M5 under a 6 GiB MLX cap (peak 4.3
+GiB; the draft alone peaks at 0.526 GiB). Exactness holds: the gate returns
+**6/6 prompts token-identical with and without `--spec`**
+(`mlx/receipts/specgate_8b_0p6b.json` in the Neutrino-8B repo). Throughput on Apple
+is class-dependent: **facts 22.00 -> 25.71 tok/s (x1.168)** at 0.7442
+acceptance, while **chat (x0.837) and prose (x0.680) regress** because the
+batched verify is compute-bound at ~2.8x a single step, so break-even
+needs about 2.9 accepted tokens per round and the base draft's acceptance
+on those classes is 0.30-0.44. A code class was never measured on MLX. Use `--spec` on
+Apple for factual workloads; an FV5 sgemm path is the wired follow-up.
+
+### Draft-model artifact pins
+
+- `neutrino_v4.bin` (this shipping base container, under its
+  speculative-decoding working name): sha `91c0b26d...19399`, 327,719,836 B
+- the distilled dspec draft and its confidence head are separate
+  artifacts, not published here
+
+## Weights: get them and verify them
+
+The container ships in this repository. Fetch it and check the digests —
+`MANIFEST.json` carries the same sha256, and `fermion info` verifies it for
+you automatically:
+
+```bash
+hf download fermionresearch/Neutrino-0.6B neutrino-0.6b_v4.bin --local-dir .
+shasum -a 256 neutrino-0.6b_v4.bin   # must print 91c0b26d...19399
+md5 neutrino-0.6b_v4.bin             # macOS — must print 86565bf6183e8031943aac9fd9771385
+md5sum neutrino-0.6b_v4.bin          # Linux — same digest
+```
+
+Export provenance: exported on a Modal CPU container (cpu=8, 24 GiB) from
+the archived QAT state with the banked exporter (`export_trit_c_model.py`
+sha `78bd8b8b...`, pinned command and flags recorded in the export receipt;
+quantizer parameters are not published). Gates: double-export
+byte-determinism PASS, tv4z byte round-trip PASS, HF expansion self-check
+PASS. Full receipt: `receipts/receipt_base.json`; greedy-cache trajectory
+`receipts/hf_greedy_cache_86565bf6.json`.
+
+## Limitations
+
+- BASE model: no chat template behavior, no instruction-following
+  guarantees, no tool use (see the battery above).
+- Knowledge-adjacent meters are at or near floor by construction (596M in
+  a ternary-family format; the sub-7B knowledge-conversion floor is a
+  banked house finding). Do not quote the MMLU or GSM8K cells as
+  competitive benchmarks.
+- BFCL v3 measures a degenerate never-calls profile. This model has no
+  function-calling capability and none is claimed.
+- Greedy decode parity vs the fp reference implementation is 382/384
+  positions on the banked gate prompts: the int8-activation runtime and
+  the fp expansion disagree at 2 near-tie argmax positions (top-2 margins
+  0.02-0.20 logits; full analysis in `receipts/m5_bitgate_analysis.json`).
+  Runtime output is deterministic.
+- On Apple silicon, speculative decoding against the 8B is a win on
+  factual prompts and a regression on chat and prose (see the section
+  above). The H100 path is a win on all five measured classes.
+- The GGUF pack loads only through our llama.cpp fork until upstreaming
+  lands; stock llama.cpp, ollama, and LM Studio binaries do not know its
+  tensor types.
+- Knowledge cutoff and multilingual behavior inherit from the base model
+  plus the disclosed feed diet (see eval-receipts).
+
+## Model lineage and methodology
+
+Lineage in one line: base model (see frontmatter) -> ternary QAT on the
+streamed small-model diet corpus -> exported with the banked
+exporter, gates in the export receipt above. The QAT recipe, the diet
+disclosure, and every graded cell
+(venue, version, date) live in the eval-receipts repo; the format and
+engine write-ups are at fermionresearch.com/research/.
+
+## License and attribution
+
+Weights: Apache-2.0. Derivative of Qwen/Qwen3-0.6B (Apache-2.0, Alibaba
+Cloud), see `LICENSE`. Training data: the small-model diet corpus
+(streamed realization) disclosed in the eval-receipts repo.
+
+`bin/` binaries: shipped in this repo under `bin/` with sha256 sidecars —
+the same generic TRTC v4 runtimes bundled with Neutrino-8B (same EULA:
+free to use with these weights, no redistribution, no reverse
+engineering).
+
+Contact: [email protected]

bin/MANIFEST.json

@@ -0,0 +1,25 @@
+{
+ "note": "bin/ staging manifest: blessed fermion-run release binaries. Entries mirror the .sha256 sidecars. The binaries are container-agnostic (any TRTC v4 arch-3 file).",
+ "binaries": {
+  "fermion-run-macos-arm64": {
+   "status": "RE-BLESSED 2026-07-28 (0.1.10 fp16-KV + runtime YaRN): macOS arm64 CPU runtime (NEON dotprod + persistent thread pool; libomp statically linked). Supersedes the 0.1.8 build: adds --kv-dtype fp16 (KV bytes halved, fp32 compute over fp16 storage, opt-in because near-tie tokens can flip) and --yarn-factor (YaRN rope tables, long-context extension; factor 1.0 gated byte-identical to flag-off). With both flags absent, output gated BYTE-IDENTICAL to the superseded binary (ids + final logits).",
+   "bytes": 671656,
+   "sha256": "2b9902fc36bf59c50a67ee0c79ae38a259d066e6ebff764abbf05ff72017351c",
+   "sidecar": "fermion-run-macos-arm64.sha256",
+   "build_receipt": "internal reference"
+  },
+  "fermion-run-linux-x64": {
+   "status": "RE-BLESSED 2026-07-28 (0.1.10 fp16-KV + runtime YaRN): Linux x86-64 CPU runtime, AVX2 baseline (-march=x86-64-v3), fully static ELF. Supersedes the 0.1.8 build: adds --kv-dtype fp16 (KV bytes halved, fp32 compute over fp16 storage, opt-in because near-tie tokens can flip) and --yarn-factor (YaRN rope tables, long-context extension; factor 1.0 gated byte-identical to flag-off). With both flags absent, output gated BYTE-IDENTICAL to the superseded binary (ids + final logits) on a 24-core venue.",
+   "bytes": 1317208,
+   "sha256": "d3e1c3d7a7fe43e9dd4d6e16e75c0cd234bfc9866964284101d200f3da05310b",
+   "sidecar": "fermion-run-linux-x64.sha256",
+   "build_receipt": "internal reference"
+  },
+  "fermion-run-linux-cuda": {
+   "status": "COMING-SOON (NOT STAGED, no fake artifact): no standalone arch-3 (Qwen3) CUDA runtime binary exists yet. Working fallback documented in bin/README.md: pip fermion torch path with --device cuda.",
+   "bytes": null,
+   "sha256": null,
+   "sidecar": null
+  }
+ }
+}

bin/README.md

@@ -0,0 +1,216 @@
+# bin/ — prebuilt `fermion-run` native runtimes
+
+> MIRRORED COPY (2026-07-27): byte-identical
+> binaries and sidecars to `fermionresearch/Neutrino-8B/bin/`. The runtime is
+> container-agnostic (any TRTC v4 arch-3 file), so the same two binaries serve
+> this repo's container; the examples below name **this** repo's container.
+
+STATUS: **BLESSED BINARIES STAGED 2026-07-25**.
+Binaries are prebuilt and closed-source (kernel source does not ship);
+every binary has a `.sha256` sidecar. EULA line lives on the model card.
+Functional gates ran on the interim 8B v4 cut; the runtime is
+container-agnostic (any TRTC v4 arch-3).
+
+## What is here
+
+| File | Platform / backend | State |
+|---|---|---|
+| `fermion-run-macos-arm64` | macOS arm64 (M1+), CPU — NEON dotprod + persistent thread pool, OpenMP statically linked, zero dylib deps beyond libSystem | BLESSED (functional-gated on the 8B v4 container) |
+| `fermion-run-linux-x64` | Linux x86-64, CPU — AVX2 baseline (`-march=x86-64-v3`), fully static ELF, runs on any 2015+ x86-64 distro | BLESSED (functional-gated on the 8B v4 container) |
+| `fermion-run-linux-cuda` | Linux x86-64, NVIDIA CUDA | **COMING SOON** — not staged; see fallback below |
+
+Honesty notes, so nobody is surprised:
+
+- The macOS binary is the **CPU** runtime. The Metal-optimized runtime for
+  this model's container format is a week-one follow-up (the existing Metal
+  dev builds target a different container lineage and cannot load this
+  model); when it lands it replaces this entry with its own receipts.
+- The linux-x64 binary is built for the AVX2 **compatibility baseline**, not
+  the AVX-512-VNNI fast path the banked x86 speed receipts were measured on.
+  It is correct (bit-exact GEMV unit gate at build time) and self-contained;
+  a VNNI-optimized variant is a week-one candidate.
+- CUDA fallback that works today: `pip install fermion-research` then
+  `fermion chat --model fermionresearch/Neutrino-8B --device cuda`
+  (reference torch path — correctness-first, not the speed path).
+
+## CLI (what the binaries actually take)
+
+The binaries take **pre-tokenized ids**, not prompt strings — tokenization
+lives in the `fermion` CLI (`pip install fermion-research`, the one door), which
+downloads the model + the platform-matching binary from this repo and shells
+out for the fast path. Manual use:
+
+```
+./fermion-run-<platform> <container.bin> "<id0,id1,...>" <n_new_tokens> <n_threads> \
+    [logits_out.bin] [--temp T] [--top-p P] [--rep-pen R] [--seed S] \
+    [--stop-id I0[,I1...]] [--min-p F] [--presence-pen F] [--freq-pen F] \
+    [--dry MULT [--dry-base B --dry-allow N]] [--pen-window N] \
+    [--eos-exempt-minp] [--eos-boost B:N] [--ppl]
+```
+
+The container, the id list, the token count and the **thread count are
+positionals, in that order**. There is no `--chat` and no `--threads`.
+
+> [!IMPORTANT]
+> **Sampler flags require `--temp > 0` to engage.** At `--temp 0`
+> (pure greedy) the binary takes a fast argmax path and silently
+> ignores `--rep-pen`, `--top-p`, and all other penalty flags. If
+> you want penalties with near-deterministic output, use
+> `--temp 0.01 --top-p 1.0 --seed 42`. (Found 2026-07-26; a
+> runtime patch making this explicit is a week-one item.)
+>
+> **`--pen-window` is inert on the legacy sampled path.** With `--temp > 0`
+> and none of `--min-p` / `--presence-pen` / `--freq-pen` / `--dry` present,
+> the repetition-penalty window is clamped to the last **64** tokens
+> regardless of what `--pen-window` says (`trit_run.c`: `rwin = g_ext ?
+> max(g_penwin, 64) : 64`). Adding any one of those four flags switches on
+> the modern penalty stack and makes `--pen-window` literal. Every graded
+> C receipt was taken on the legacy path, so the banked C numbers are
+> **64-window** numbers even where the command line reads
+> `--pen-window 256`; the torch and MLX paths do apply 256. Documented
+> 2026-07-27; making the flag
+> literal on the legacy path is a week-one runtime patch.
+
+Defaults: greedy decode; without `--stop-id` exactly `n_new_tokens` are
+generated (EOS ignored); with `--stop-id` generation stops at the stop token
+(coherence mode). Output: line 1 = generated ids (comma-separated), line 2 =
+`tok/s: ...`. `n_new_tokens 0` = prefill-only logits dump.
+
+Per-platform one-liners (chat-format ids for a user prompt, then generate up
+to 64 tokens, stop at `<|im_end|>` = 151645):
+
+```bash
+# ids for 'In one sentence, why is the sky blue?' via this repo's tokenizer:
+IDS=$(python3 -c "
+from tokenizers import Tokenizer
+t = Tokenizer.from_file('tokenizer.json')
+p = '<|im_start|>user\nIn one sentence, why is the sky blue?<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n'
+print(','.join(map(str, t.encode(p).ids)))")
+
+# macOS arm64:
+./bin/fermion-run-macos-arm64 neutrino-0.6b_v4.bin "$IDS" 64 8 --stop-id 151645
+# Linux x86-64:
+./bin/fermion-run-linux-x64 neutrino-0.6b_v4.bin "$IDS" 64 8 --stop-id 151645
+```
+
+macOS quarantine note: after download run
+`xattr -d com.apple.quarantine bin/fermion-run-macos-arm64` once.
+
+## sha256 sidecar convention
+
+Every binary `X` ships with `X.sha256` (standard `shasum` line):
+
+```bash
+# producer (at staging time, from this directory):
+shasum -a 256 fermion-run-macos-arm64 > fermion-run-macos-arm64.sha256
+# consumer:
+shasum -a 256 -c fermion-run-macos-arm64.sha256
+```
+
+`MANIFEST.json` here mirrors the sidecars (file -> bytes + sha256 + build
+provenance) and is regenerated
+whenever binaries are added or replaced.
+
+## thread count: the runtime is safe above 16 threads again
+
+> [!IMPORTANT]
+> **Rebuilt 2026-07-27 (thread-safety fix).** The 2026-07-25 binaries
+> corrupted memory above **16 threads**: the per-thread activation-quant
+> scratch buffer inside the runtime was allocated for 16 workers while the
+> OpenMP path indexed it by thread id with no clamp. On Linux x86-64 that was
+> a SIGSEGV on the 8B and — worse — **exit code 0 with silently different,
+> wrong tokens** on the 0.6B, on any box with 18 or more logical cores (the
+> `fermion` CLI asked for `cpu_count - 1`). macOS arm64 never reached it
+> because Apple silicon tops out at 16 logical cores.
+>
+> These binaries size that buffer from the live thread count, clamp the
+> requested count at a hard ceiling, and are gated by an output-stability
+> thread sweep that asserts
+> **byte-identical generated ids** at 1/4/8/15/16/17/20/23/max threads rather
+> than merely a zero exit code. The `fermion` package independently caps the
+> count it will request at 16 (`fermion.native.THREAD_CAP`).
+
+## prefill: prompts are now processed as a batch
+
+> [!NOTE]
+> **Rebuilt 2026-07-27 (batched prefill, 0.1.6).** Earlier binaries ran the
+> PROMPT token-by-token — one full GEMV pass over the weight stack per prompt
+> token — so a long chat history prefilled at a fraction of decode speed and
+> the stall grew with every turn. These binaries push prompt positions through
+> each layer in chunks (weights are decoded once per chunk and applied to all
+> positions from cache), measured ~4x faster prefill on Apple M-series and
+> ~10x on Linux AVX2 at 300 prompt tokens, with **byte-identical output**:
+> generated ids and final logits are gated bit-for-bit against the previous
+> binaries across a prompt/(n_new) matrix, a chunk-size sweep and the full
+> thread ladder.
+> `TRIT_PREFILL_BATCH=0` in the environment restores the sequential prefill.
+
+## session mode: a resident runner with KV-prefix reuse
+
+> [!NOTE]
+> **Rebuilt 2026-07-28 (session mode, 0.1.7).** The runner now has a
+> persistent mode: `<binary> model.bin "0" 0 <threads> --session [--ctx N]`
+> keeps ONE process resident holding the mmap'd weights and a KV cache, takes
+> requests on stdin (full prompt ids per request) and prefills only the part
+> of the prompt it has not seen before (longest-common-prefix against the
+> cached token history). `fermion serve` and `fermion chat` (pip 0.1.7) drive
+> this automatically; an agent step over a fixed ~2k-token preamble drops from
+> ~94 s to ~1.3 s on the 8B (24-core Linux) because the preamble prefill and
+> the per-request process start are both paid once. Output is gated
+> **byte-identical** to a one-shot invocation of the same full prompt — greedy
+> and fixed-seed sampled, including reuse after a divergent history and across
+> the full thread ladder to 40 threads. One-shot invocations are gated
+> byte-identical (ids + final logits) to the previous 0.1.6 binaries. A
+> mid-decode `C\n` on stdin cancels the current request; `R\n` resets the
+> cache; the KV capacity is `--ctx` positions (RAM scales linearly with it).
+
+## 0.1.8: multi-slot positional KV reuse + tool-name aliasing
+
+> [!NOTE]
+> **Rebuilt 2026-07-28 (0.1.8).** `--session` now
+> tracks KV validity per (position, content) across up to 4 logical
+> sequences instead of one longest-common-prefix history. An interleaved
+> divergent request (agent frameworks fire short utility prompts — titles,
+> status — into the same server between steps) no longer destroys the warm
+> conversation cache: only the positions it physically overwrites are
+> re-prefilled when the conversation returns (measured on the Hermes shape:
+> re-prefill 4,122 -> 177 tokens, turn wall 50 s -> 2.5 s on an M5).
+> Reuse stays EXACT: a cached position is reused only when it was computed
+> under a prefix identical to the new prompt — a mutated head therefore
+> still (correctly) invalidates everything after it, which no exact cache
+> can avoid. Output is gated byte-identical to one-shot decodes across
+> fresh/extended/mutated-head/mutated-middle/eviction/interleave shapes,
+> chunk sweeps, the sequential path, and the N4 thread ladder, on both
+> models and both platforms; one-shot output is gated byte-identical (ids +
+> final logits) to the 0.1.7 binaries. The `ACK` line gains a `segs=<n>`
+> field (number of prefill runs); the protocol is otherwise unchanged and
+> 0.1.7 clients work as-is.
+
+## 0.1.10: fp16 KV cache (--kv-dtype) + runtime YaRN (--yarn-factor)
+
+> [!NOTE]
+> **Rebuilt 2026-07-28 (0.1.10).** Two additive
+> runtime flags; with both flags absent the binary is gated BYTE-IDENTICAL
+> (ids + final logits) to the 0.1.8/0.1.9 pair on both platforms.
+>
+> `--kv-dtype fp16` stores the session/decode KV cache in IEEE fp16 and
+> computes attention in fp32 over it: HALF the KV memory (288 -> 144
+> KiB/token on the 8B; an 8192-position session drops ~2.3 -> ~1.15 GiB).
+> Cached k/v values are rounded once (RNE) at the position they are
+> produced, identically on every code path and platform, so the mode is
+> deterministic and thread-count-stable -- but near-tie tokens CAN resolve
+> differently than fp32 (a small measured flip rate). fp16 is
+> therefore OPT-IN; the default stays fp32 and byte-exact.
+>
+> `--yarn-factor F` builds YaRN rope tables at load (the transformers
+> `_compute_yarn_parameters` twin, double precision; derived defaults
+> orig_max = model max_pos, attn_factor = 0.1*ln(F)+1, beta 32/1, all
+> overridable), extending usable context toward F x 40,960 positions.
+> `--yarn-factor 1.0` is the identity (byte-identical to flag-off).
+> Teacher-forced logits beyond position 40,960 are gated against
+> transformers' own YaRN on the same checkpoint; long-context retrieval
+> quality of the ternary brains is EXPERIMENTAL -- validate retrieval
+> quality for your workload before advertising a
+> context length. KV memory grows linearly with context (a 61,440-token
+> fp16 session on the 8B is ~8.4 GiB): pair long contexts with
+> `--kv-dtype fp16` and mind the printed KV arithmetic.

bin/fermion-run-linux-x64

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

bin/fermion-run-linux-x64.sha256

@@ -0,0 +1 @@
+d3e1c3d7a7fe43e9dd4d6e16e75c0cd234bfc9866964284101d200f3da05310b  fermion-run-linux-x64

bin/fermion-run-macos-arm64

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

bin/fermion-run-macos-arm64.sha256

@@ -0,0 +1 @@
+2b9902fc36bf59c50a67ee0c79ae38a259d066e6ebff764abbf05ff72017351c  fermion-run-macos-arm64

config.json

@@ -0,0 +1,26 @@
+{
+ "transformers_version": "5.14.1",
+ "architectures": [
+  "TrtcV4ForCausalLM"
+ ],
+ "output_hidden_states": false,
+ "return_dict": true,
+ "dtype": "auto",
+ "chunk_size_feed_forward": 0,
+ "is_encoder_decoder": false,
+ "id2label": {
+  "0": "LABEL_0",
+  "1": "LABEL_1"
+ },
+ "label2id": {
+  "LABEL_0": 0,
+  "LABEL_1": 1
+ },
+ "problem_type": null,
+ "_name_or_path": "",
+ "container": "neutrino-0.6b_v4.bin",
+ "row_chunk": 512,
+ "int8_row_chunk": 4096,
+ "model_type": "trtc_v4",
+ "output_attentions": false
+}

generation_config.json

@@ -0,0 +1,10 @@
+{
+    "bos_token_id": 151643,
+    "do_sample": false,
+    "eos_token_id": [
+        151645,
+        151643
+    ],
+    "pad_token_id": 151643,
+    "transformers_version": "4.53.2"
+}

gguf/Modelfile

@@ -0,0 +1,6 @@
+# Neutrino-0.6B base — ollama Modelfile (requires ollama built against the
+# fermion-fv5 llama.cpp fork; stock ollama cannot load the FV5 type)
+FROM ./neutrino-0.6b-base-fv5.gguf
+PARAMETER temperature 0.7
+PARAMETER top_p 0.95
+# base model: raw completion, no chat template

gguf/README.md

@@ -0,0 +1,151 @@
+# Neutrino-0.6B — GGUF pack (llama.cpp fork `fermion-fv5`)
+
+> [!IMPORTANT]
+> **Neutrino-0.6B exists as the speculative-decoding DRAFT for
+> Neutrino-8B** — that pairing is its supported purpose. It is a BASE
+> model: not an assistant, no chat/instruction/tool claims. For a small
+> conversational model use Neutrino-0.6B-Chat.
+
+Run the [Neutrino-0.6B](../README.md) five-value container through the
+**llama.cpp toolchain** (llama-cli, llama-server, llama-bench, and anything
+built on top of them, including ollama built from source against the fork).
+
+**Read this first — which door do you want?**
+
+- **This GGUF pack is the compatibility door.** It exists so the
+  llama.cpp/ollama/LM Studio world can load and run our format with the
+  ecosystem's own tooling. It is CPU-backend, correctness-certified
+  (token-identical greedy vs the container's fp32 expansion), and *not*
+  tuned for speed.
+- **The native binaries are the fast door.** `fermion-run` (shipped with
+  the Neutrino-8B repo) decodes the same container at ~225–236 tok/s on an
+  Apple M5 CPU. If you want speed, use the native runtime; if you want
+  llama.cpp-ecosystem integration, use this pack.
+
+## What's in the file
+
+`neutrino-0.6b-base-fv5.gguf` stores the model in two Fermion GGML types
+added by the fork (they do **not** exist in stock llama.cpp):
+
+| type | used for | layout per 256-element block | bits/weight |
+|---|---|---|---|
+| `FV5` (43) | all 196 transformer linears | f32 `s_lo`, f32 `s_hi`, 3×32B bit-planes (`bp`,`bn`,`br`) | 3.25 |
+| `FV5B` (44) | int8 embedding / lm_head rows | f32 row scale, 256×int8 | 8.125 |
+
+Weights are `w = (bp − bn) · (br ? s_hi : s_lo)` — the exact five-value
+{0, ±s_lo, ±s_hi} function of the TRTC v4 container. The converter copies
+the container's bit-planes and f32 per-row dual scales verbatim (no
+re-quantization anywhere), and bit-compares every tensor's dequantization
+against the container's f32 expansion before writing. Norms stay f32.
+Activations are never quantized at runtime (`vec_dot_type = F32`), so the
+only numerical difference vs the fp32 expansion is float summation order.
+
+## Files
+
+See `SHA256SUMS` in this folder for the authoritative digests of:
+
+- `neutrino-0.6b-base-fv5.gguf` — the model (FV5/FV5B, ~490 MiB)
+- `fv5.patch` / `fermion-fv5.bundle` — the fork as a single patch/bundle
+  on top of upstream `ggml-org/llama.cpp` @ `d67c0b41`, branch
+  `fermion-fv5`, commit `e07b3ec1`, docs in `FORK_NOTES.md`
+
+## Quickstart (build the fork, run the model)
+
+```bash
+git clone https://github.com/fermionresearch/llama.cpp && cd llama.cpp
+git checkout fermion-fv5
+# or, from upstream + our patch:
+#   git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
+#   git checkout d67c0b4107112e4790774c3a8169e2e3eb24643b && git am fv5.patch
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_NATIVE=ON -DLLAMA_CURL=OFF -DGGML_METAL=OFF
+cmake --build build -j --target llama-completion
+
+./build/bin/llama-completion -m neutrino-0.6b-base-fv5.gguf \
+    -p "The key idea behind ternary neural networks is" -n 128 --temp 0 -no-cnv
+```
+
+Build notes: the command above targets the `fermion-fv5` branch, which is
+CPU/CUDA only — hence `-DGGML_METAL=OFF`. In this tree `llama-cli` is the
+chat-first surface; `llama-completion` is the completion tool these
+instructions are verified with. The 8B pack's README documents the full
+backend matrix.
+
+### Apple GPU (Metal)
+
+FV5 Metal kernels are on the `fermion-fv5-metal` branch. Build **without**
+`-DGGML_METAL=OFF` and run with `-ngl 99`:
+
+```bash
+git checkout fermion-fv5-metal
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_CURL=OFF
+cmake --build build -j --target llama-completion llama-bench
+```
+
+Measured on an Apple M5 (16 GB, machine idle, `llama-bench -r 3`, build
+`181e4d8`), model resident 321.57 MiB:
+
+| test | `-ngl 99` (Metal) | `-ngl 0` (same binary, CPU) | speedup |
+|---|---|---|---|
+| pp512 | **6776.42 ± 206.99 tok/s** | 845.46 ± 68.75 tok/s | ×8.0 |
+| tg128 | **187.19 ± 1.89 tok/s** | 3.73 ± 0.01 tok/s | ×50.2 |
+
+This is a **base** model (no chat template, no instruction tuning) — use
+completion-style prompts and expect base-model behavior.
+
+### ollama (built against the fork)
+
+Stock ollama binaries do not know the FV5 type. Build ollama from source
+with its vendored llama.cpp replaced by the fork checkout, then:
+
+```
+# Modelfile -- deterministic, matching this repo's generation_config.json
+# and the `--temp 0` llama-cli line above. llama.cpp defaults would
+# otherwise give you temperature 0.8 and top-k 40.
+FROM ./neutrino-0.6b-base-fv5.gguf
+PARAMETER temperature 0
+PARAMETER top_k 0
+PARAMETER repeat_penalty 1.0
+# base model: no template, raw completion
+```
+
+```bash
+ollama create neutrino-0.6b -f Modelfile
+ollama run neutrino-0.6b "The key idea behind ternary neural networks is"
+```
+
+LM Studio: point it at a llama.cpp server built from the fork
+(`llama-server -m neutrino-0.6b-base-fv5.gguf`) and connect via the
+OpenAI-compatible endpoint; the bundled engine cannot load FV5 directly.
+
+## As a speculative-decoding draft for Neutrino-8B (EXPERIMENTAL)
+
+This 0.6B fv5 pack can draft for the Neutrino-8B fv5 pack via llama.cpp's
+own built-in speculative decoding (`llama-speculative -m 8b.gguf -md
+neutrino-0.6b-base-fv5.gguf --spec-draft-n-max 4 --temp 0`). Honesty note:
+that acceptance rule is llama.cpp's own sampling-based speculation, not
+our bit-gated certification — and on CPU it is currently a measured
+honest null (slower than plain decode; the FV5 type has no batched-matmul
+path yet, so verify doesn't amortize). Numbers, receipts, and the full
+note live in the Neutrino-8B GGUF README. Certified-exact speculation
+lives in the native runtime and the MLX pack's `--spec` mode.
+
+## Correctness & speed
+
+- Gate: greedy streams (8 prompts × 128 tokens) from the fork's CPU
+  backend, checked token-by-token against the container's fp32 expansion
+  reference (free-running + teacher-forced). Verdict and any near-tie
+  argmax notes: `receipts/` in this folder.
+- Speed (record only, not a goal): see `receipts/bench_*.json` for CPU
+  tok/s on the recorded container class. The native runtime is the fast
+  door; upstreaming + SIMD-fused `vec_dot` (NEON) are wired follow-ups.
+
+## License
+
+**This folder is mixed-licence.**
+
+- The **model pack** (`*.gguf`) is Apache-2.0, same as the parent model card
+  (`../LICENSE`; `../NOTICE` carries the Qwen3 attribution).
+- Any **`fv5.patch` / fork source** is a derivative of ggml-org/llama.cpp and
+  is therefore **MIT**, upstream's licence — *not* Apache-2.0, and not
+  covered by the parent card's grant. See the fork repository's own
+  `LICENSE`.

gguf/SHA256SUMS

@@ -0,0 +1,6 @@
+# Neutrino-0.6B GGUF pack — authoritative digests
+# verify after download with `shasum -a 256 -c`.
+dd9354c4b3cd2b34195b0270540e4fa5db3811e42b6e4bdbd57958e0027e9272  neutrino-0.6b-base-fv5.gguf
+81bf7be5eef18eb98ab4823596374c8dd6615151cf5615425973cb65942c0f73  fv5.patch
+# source container (parent card): 91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399  neutrino-0p6b_v4_base.bin
+# fork: ggml-org/llama.cpp @ d67c0b41 + fv5.patch = branch fermion-fv5, commit e07b3ec1 (tree f3067d90)

gguf/fv5.patch

@@ -0,0 +1,952 @@
+From e07b3ec135c1f90c64584e0ea2dc983e47094ab9 Mon Sep 17 00:00:00 2001
+From: Fermion Research <[email protected]>
+Date: Sat, 25 Jul 2026 14:59:41 +0530
+Subject: [PATCH] ggml: add Fermion FV5/FV5B five-value ternary types (CPU) +
+ fermion-greedy gate tool
+
+FV5: 256-block, f32 dual per-row scales + 3 bit-planes (3.25 bpw), the GGUF
+carrier for TRTC v4 trit records {0, +/-s_lo, +/-s_hi}. FV5B: f32 row scale +
+int8 (8.125 bpw) for the container's embed/lm_head records. vec_dot against
+raw F32 activations (no runtime activation quantization) so CPU numerics stay
+in the same class as the f32 container expansion; blocks are produced offline
+by the TRTC v4 -> GGUF converter (no quantize path). tools/fermion-greedy
+certifies greedy token-identity vs the reference cache with teacher-forced
+margin forensics.
+---
+ FORK_NOTES.md                           |  89 +++++++
+ ggml/include/ggml.h                     |   4 +-
+ ggml/src/ggml-common.h                  |  24 ++
+ ggml/src/ggml-cpu/ggml-cpu.c            |  14 ++
+ ggml/src/ggml-cpu/ops.cpp               |   2 +
+ ggml/src/ggml-cpu/quants.c              | 133 +++++++++++
+ ggml/src/ggml-cpu/quants.h              |   5 +
+ ggml/src/ggml-quants.c                  |  65 ++++++
+ ggml/src/ggml-quants.h                  |   3 +
+ ggml/src/ggml.c                         |  16 ++
+ gguf-py/gguf/constants.py               |   5 +
+ gguf-py/gguf/quants.py                  |  44 ++++
+ include/llama.h                         |   1 +
+ src/llama-model-loader.cpp              |   2 +
+ tools/CMakeLists.txt                    |   1 +
+ tools/fermion-greedy/CMakeLists.txt     |   5 +
+ tools/fermion-greedy/fermion-greedy.cpp | 299 ++++++++++++++++++++++++
+ 17 files changed, 711 insertions(+), 1 deletion(-)
+ create mode 100644 FORK_NOTES.md
+ create mode 100644 tools/fermion-greedy/CMakeLists.txt
+ create mode 100644 tools/fermion-greedy/fermion-greedy.cpp
+
+diff --git a/FORK_NOTES.md b/FORK_NOTES.md
+new file mode 100644
+index 0000000..0d4cfe2
+--- /dev/null
++++ b/FORK_NOTES.md
+@@ -0,0 +1,89 @@
++# Fermion `fermion-fv5` fork notes
++
++Branch `fermion-fv5` on top of upstream `ggml-org/llama.cpp` commit
++`d67c0b4107112e4790774c3a8169e2e3eb24643b` (2026-07-25). This fork adds two
++ggml weight types so llama.cpp can LOAD AND RUN Fermion Research's TRTC v4
++five-value ternary containers (Neutrino-0.6B, Neutrino-8B) converted to GGUF.
++CPU backend only in this cut. The graph is untouched: both models are stock
++Qwen3 geometry (`qwen3` arch, per-head Q/K RMSNorm, biasless qkv), which
++mainline already implements.
++
++GGUF is the *compatibility* door. The Fermion native runtime and its fused
++kernels remain the *fast* door; this fork optimizes for correctness parity
++with the container's deployed function, not for speed.
++
++## New types
++
++| ggml type | id | block | bytes/block | bpw | used for |
++|---|---|---|---|---|---|
++| `GGML_TYPE_FV5`  | 43 | 256 | 104 (f32 `s_lo`, f32 `s_hi`, `bp[32]`, `bn[32]`, `br[32]`) | 3.25 | all attention/MLP linears |
++| `GGML_TYPE_FV5B` | 44 | 256 | 260 (f32 `s`, `int8 qs[256]`) | 8.125 | token_embd / output (TRTC int8 records) |
++
++Reconstruction semantics (identical to the container spec in
++`scripts/expand_trtc_v4_to_hf.py` of the research repo):
++
++- FV5:  `w[j] = (bp[j] - bn[j]) * (br[j] ? s_hi : s_lo)` — five values per row
++  `{0, ±s_lo, ±s_hi}`; the per-row dual scales are stored as exact f32 copies
++  replicated into each 256-block; bit-planes keep the container's little bit
++  order, so conversion is a plane slice, not a re-encode.
++- FV5B: `w[j] = s * qs[j]` with the exact f32 per-row scale.
++
++This is NOT BitNet TQ1_0/TQ2_0 (ternary, single fp16 block scale): five
++values + dual per-row scales do not map onto those types.
++
++## Numerics policy
++
++`vec_dot_type = GGML_TYPE_F32` for both types: activations are consumed RAW
++(no runtime Q8 quantization), and scales are f32, so every weight value seen
++by the CPU backend is bit-identical to the f32 expansion of the container.
++The only difference vs an f32 reference forward is summation order. The
++`llama-fermion-greedy` tool (below) exists to certify exactly that: greedy
++token streams vs the reference cache, with teacher-forced margin forensics
++for any argmax flip. KV cache is set to F32 in the gate tool.
++
++## Changed files
++
++- `ggml/include/ggml.h` — enum entries FV5=43, FV5B=44 (appended; no renumbering).
++- `ggml/src/ggml-common.h` — `block_fv5`, `block_fv5b` + `QK_FV5`.
++- `ggml/src/ggml.c` — type traits (`to_float`; no `from_float_ref`: blocks are
++  produced offline by the TRTC v4 → GGUF converter, `llama-quantize` is
++  intentionally NOT wired).
++- `ggml/src/ggml-quants.{c,h}` — reference `dequantize_row_fv5{,b}` +
++  `ggml_validate_row_data` cases (validates scale finiteness + the fv5
++  invariants `bp&bn==0`, `br⊆bp|bn`).
++- `ggml/src/ggml-cpu/quants.{c,h}` — `ggml_vec_dot_fv5_f32`,
++  `ggml_vec_dot_fv5b_f32`: portable scalar with an AVX2 fast path inside
++  (masked activation sums mirroring the research repo's NEON decode
++  structure); no `arch/*/quants.c` or `arch-fallback.h` churn.
++- `ggml/src/ggml-cpu/ggml-cpu.c` — CPU traits (`vec_dot_type = F32`).
++- `ggml/src/ggml-cpu/ops.cpp` — `get_rows` cases (embedding lookup for FV5B).
++- `include/llama.h`, `src/llama-model-loader.cpp` — `LLAMA_FTYPE_MOSTLY_FV5`
++  (=42) name/mapping for clean loader printouts.
++- `gguf-py/gguf/constants.py`, `gguf-py/gguf/quants.py` — python-side type
++  registration + numpy dequantize (used by the converter's bitwise
++  cross-check); float→FV5 quantize deliberately raises.
++- `tools/fermion-greedy/` — the correctness-gate tool (exact token-id
++  prompts, free + teacher-forced greedy, per-flip logit margins, F32 KV).
++
++## Deliberate non-goals of this cut
++
++- No `llama-quantize` path (conversion is offline from TRTC v4 containers).
++- No CUDA/Metal/Vulkan kernels: those backends report the types unsupported
++  and fall back to CPU. (Native GPU serving lives in the Fermion runtime.)
++- No repack/IMatrix/LoRA integration; training-path ops (`add`, `acc`,
++  `out_prod`) on FV5 tensors abort as unsupported — inference never hits them.
++
++## Build
++
++    cmake -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_CURL=OFF
++    cmake --build build -j --target llama-cli llama-bench llama-fermion-greedy
++
++## Gate usage
++
++    llama-fermion-greedy -m neutrino-0p6b.fv5.gguf \
++        --prompts prompts_ids.txt --ref ref_ids.txt --steps 128 -t 16 \
++        --out gate_receipt.json
++
++`forced_mismatch_total == 0` and `all_free_match == true` is the shipping
++gate; any nonzero flip must be margin-classified (near-tie class) in the
++release receipts.
+diff --git a/ggml/include/ggml.h b/ggml/include/ggml.h
+index 35f0c44..3958bca 100644
+--- a/ggml/include/ggml.h
++++ b/ggml/include/ggml.h
+@@ -430,7 +430,9 @@ extern "C" {
+         GGML_TYPE_NVFP4   = 40, // NVFP4 (4 blocks, E4M3 scale)
+         GGML_TYPE_Q1_0    = 41,
+         GGML_TYPE_Q2_0    = 42,
+-        GGML_TYPE_COUNT   = 43,
++        GGML_TYPE_FV5     = 43, // Fermion five-value ternary {0, +/-s_lo, +/-s_hi}: dual f32 scales + 3 bit-planes per 256-block
++        GGML_TYPE_FV5B    = 44, // Fermion int8 companion: f32 row scale + 256 int8 per block (TRTC v4 embed/lm_head records)
++        GGML_TYPE_COUNT   = 45,
+     };
+ 
+     // precision
+diff --git a/ggml/src/ggml-common.h b/ggml/src/ggml-common.h
+index 83f9118..5d3eb07 100644
+--- a/ggml/src/ggml-common.h
++++ b/ggml/src/ggml-common.h
+@@ -287,6 +287,30 @@ typedef struct {
+ } block_tq2_0;
+ static_assert(sizeof(block_tq2_0) == sizeof(ggml_half) + QK_K / 4, "wrong tq2_0 block size/padding");
+ 
++// Fermion five-value ternary (TRTC v4 trit records): w = (bp - bn) * (br ? s_hi : s_lo)
++// Scales are exact f32 copies of the container's per-row dual scales,
++// replicated into every block of the row. Bit-planes keep the container's
++// little bit order (bit i of byte j selects element 8*j + i).
++// 3.25 bpw
++#define QK_FV5 256
++typedef struct {
++    float   s_lo;            // low-magnitude scale
++    float   s_hi;            // high-magnitude scale
++    uint8_t bp[QK_FV5/8];    // +1 plane
++    uint8_t bn[QK_FV5/8];    // -1 plane (disjoint from bp)
++    uint8_t br[QK_FV5/8];    // hi-magnitude selector (subset of bp|bn)
++} block_fv5;
++static_assert(sizeof(block_fv5) == 2 * sizeof(float) + 3 * (QK_FV5/8), "wrong fv5 block size/padding");
++
++// Fermion int8 rows (TRTC v4 embed/lm_head records): w = s * q
++// s is the exact f32 per-row scale, replicated into every block of the row.
++// 8.125 bpw
++typedef struct {
++    float  s;                // row scale
++    int8_t qs[QK_FV5];
++} block_fv5b;
++static_assert(sizeof(block_fv5b) == sizeof(float) + QK_FV5, "wrong fv5b block size/padding");
++
+ //
+ // Super-block quantization structures
+ //
+diff --git a/ggml/src/ggml-cpu/ggml-cpu.c b/ggml/src/ggml-cpu/ggml-cpu.c
+index 491316f..db1679e 100644
+--- a/ggml/src/ggml-cpu/ggml-cpu.c
++++ b/ggml/src/ggml-cpu/ggml-cpu.c
+@@ -409,6 +409,20 @@ static const struct ggml_type_traits_cpu type_traits_cpu[GGML_TYPE_COUNT] = {
+         .vec_dot_type             = GGML_TYPE_Q8_K,
+         .nrows                    = 1,
+     },
++    [GGML_TYPE_FV5] = {
++        // no from_float: FV5 tensors are produced offline (TRTC v4 -> GGUF)
++        // vec_dot_type F32: activations are used raw (no runtime quantization),
++        // keeping llama.cpp numerics in the same class as the f32 expansion
++        // reference the Fermion correctness gate compares against.
++        .vec_dot                  = ggml_vec_dot_fv5_f32,
++        .vec_dot_type             = GGML_TYPE_F32,
++        .nrows                    = 1,
++    },
++    [GGML_TYPE_FV5B] = {
++        .vec_dot                  = ggml_vec_dot_fv5b_f32,
++        .vec_dot_type             = GGML_TYPE_F32,
++        .nrows                    = 1,
++    },
+     [GGML_TYPE_I32] = {
+         .from_float               = (ggml_from_float_t) ggml_cpu_fp32_to_i32,
+     },
+diff --git a/ggml/src/ggml-cpu/ops.cpp b/ggml/src/ggml-cpu/ops.cpp
+index 42ec809..4d4ab0c 100644
+--- a/ggml/src/ggml-cpu/ops.cpp
++++ b/ggml/src/ggml-cpu/ops.cpp
+@@ -5038,6 +5038,8 @@ void ggml_compute_forward_get_rows(
+         case GGML_TYPE_Q6_K:
+         case GGML_TYPE_TQ1_0:
+         case GGML_TYPE_TQ2_0:
++        case GGML_TYPE_FV5:
++        case GGML_TYPE_FV5B:
+         case GGML_TYPE_IQ2_XXS:
+         case GGML_TYPE_IQ2_XS:
+         case GGML_TYPE_IQ3_XXS:
+diff --git a/ggml/src/ggml-cpu/quants.c b/ggml/src/ggml-cpu/quants.c
+index 5e36459..731c01f 100644
+--- a/ggml/src/ggml-cpu/quants.c
++++ b/ggml/src/ggml-cpu/quants.c
+@@ -562,6 +562,139 @@ void ggml_vec_dot_tq2_0_q8_K_generic(int n, float * GGML_RESTRICT s, size_t bs,
+     *s = sumf;
+ }
+ 
++// ====================== Fermion five-value ternary (FV5 / FV5B)
++//
++// vec_dot against RAW F32 activations (vec_dot_type == GGML_TYPE_F32): the
++// activations are never quantized, so the only difference vs a full f32
++// matmul with the expanded weights is summation order. Weights per block:
++//   w[j] = (bp[j] - bn[j]) * (br[j] ? s_hi : s_lo)
++// so the block dot factors into four masked activation sums:
++//   dot = s_lo * (sum_lo_p - sum_lo_n) + s_hi * (sum_hi_p - sum_hi_n)
++// This mirrors the sign/masked-accumulate structure of the reference NEON
++// decode (kernels/neon_war5_lab.c) in portable form.
++
++#if defined(__AVX2__)
++static inline float ggml_fv5_hsum_ps(__m256 v) {
++    __m128 lo = _mm256_castps256_ps128(v);
++    __m128 hi = _mm256_extractf128_ps(v, 1);
++    lo = _mm_add_ps(lo, hi);
++    lo = _mm_add_ps(lo, _mm_movehl_ps(lo, lo));
++    lo = _mm_add_ss(lo, _mm_shuffle_ps(lo, lo, 0x55));
++    return _mm_cvtss_f32(lo);
++}
++#endif
++
++void ggml_vec_dot_fv5_f32(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc) {
++    assert(nrc == 1);
++    assert(n % QK_FV5 == 0);
++    UNUSED(nrc);
++    UNUSED(bx);
++    UNUSED(by);
++    UNUSED(bs);
++
++    const block_fv5 * GGML_RESTRICT x = vx;
++    const float     * GGML_RESTRICT y = vy;
++
++    const int nb = n / QK_FV5;
++    float sumf = 0.0f;
++
++    for (int i = 0; i < nb; ++i) {
++        const float s_lo = x[i].s_lo;
++        const float s_hi = x[i].s_hi;
++        const float * GGML_RESTRICT xf = y + i*QK_FV5;
++
++#if defined(__AVX2__)
++        const __m256i bitpos = _mm256_setr_epi32(1, 2, 4, 8, 16, 32, 64, 128);
++        __m256 acc_lo_p = _mm256_setzero_ps();
++        __m256 acc_lo_n = _mm256_setzero_ps();
++        __m256 acc_hi_p = _mm256_setzero_ps();
++        __m256 acc_hi_n = _mm256_setzero_ps();
++
++        for (int j = 0; j < QK_FV5/8; ++j) {
++            const uint8_t bpj = x[i].bp[j];
++            const uint8_t bnj = x[i].bn[j];
++            if (!(bpj | bnj)) {
++                continue;
++            }
++            const __m256i m_p = _mm256_cmpeq_epi32(_mm256_and_si256(_mm256_set1_epi32(bpj), bitpos), bitpos);
++            const __m256i m_n = _mm256_cmpeq_epi32(_mm256_and_si256(_mm256_set1_epi32(bnj), bitpos), bitpos);
++            const __m256i m_r = _mm256_cmpeq_epi32(_mm256_and_si256(_mm256_set1_epi32(x[i].br[j]), bitpos), bitpos);
++
++            const __m256 x8 = _mm256_loadu_ps(xf + 8*j);
++
++            acc_lo_p = _mm256_add_ps(acc_lo_p, _mm256_and_ps(x8, _mm256_castsi256_ps(_mm256_andnot_si256(m_r, m_p))));
++            acc_lo_n = _mm256_add_ps(acc_lo_n, _mm256_and_ps(x8, _mm256_castsi256_ps(_mm256_andnot_si256(m_r, m_n))));
++            acc_hi_p = _mm256_add_ps(acc_hi_p, _mm256_and_ps(x8, _mm256_castsi256_ps(_mm256_and_si256(m_p, m_r))));
++            acc_hi_n = _mm256_add_ps(acc_hi_n, _mm256_and_ps(x8, _mm256_castsi256_ps(_mm256_and_si256(m_n, m_r))));
++        }
++
++        sumf += s_lo * (ggml_fv5_hsum_ps(acc_lo_p) - ggml_fv5_hsum_ps(acc_lo_n))
++              + s_hi * (ggml_fv5_hsum_ps(acc_hi_p) - ggml_fv5_hsum_ps(acc_hi_n));
++#else
++        float sum_lo_p = 0.0f, sum_lo_n = 0.0f, sum_hi_p = 0.0f, sum_hi_n = 0.0f;
++
++        for (int j = 0; j < QK_FV5/8; ++j) {
++            const uint8_t bpj = x[i].bp[j];
++            const uint8_t bnj = x[i].bn[j];
++            if (!(bpj | bnj)) {
++                continue;
++            }
++            const uint8_t brj = x[i].br[j];
++            const float * GGML_RESTRICT xj = xf + 8*j;
++            for (int b = 0; b < 8; ++b) {
++                const uint8_t bit = 1u << b;
++                if (bpj & bit) {
++                    if (brj & bit) { sum_hi_p += xj[b]; } else { sum_lo_p += xj[b]; }
++                } else if (bnj & bit) {
++                    if (brj & bit) { sum_hi_n += xj[b]; } else { sum_lo_n += xj[b]; }
++                }
++            }
++        }
++
++        sumf += s_lo * (sum_lo_p - sum_lo_n) + s_hi * (sum_hi_p - sum_hi_n);
++#endif
++    }
++
++    *s = sumf;
++}
++
++void ggml_vec_dot_fv5b_f32(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc) {
++    assert(nrc == 1);
++    assert(n % QK_FV5 == 0);
++    UNUSED(nrc);
++    UNUSED(bx);
++    UNUSED(by);
++    UNUSED(bs);
++
++    const block_fv5b * GGML_RESTRICT x = vx;
++    const float      * GGML_RESTRICT y = vy;
++
++    const int nb = n / QK_FV5;
++    float sumf = 0.0f;
++
++    for (int i = 0; i < nb; ++i) {
++        const float * GGML_RESTRICT xf = y + i*QK_FV5;
++
++#if defined(__AVX2__)
++        __m256 acc = _mm256_setzero_ps();
++        for (int j = 0; j < QK_FV5/8; ++j) {
++            const __m128i q8  = _mm_loadl_epi64((const __m128i *)(x[i].qs + 8*j));
++            const __m256  qf  = _mm256_cvtepi32_ps(_mm256_cvtepi8_epi32(q8));
++            acc = _mm256_fmadd_ps(qf, _mm256_loadu_ps(xf + 8*j), acc);
++        }
++        sumf += x[i].s * ggml_fv5_hsum_ps(acc);
++#else
++        float sumq = 0.0f;
++        for (int j = 0; j < QK_FV5; ++j) {
++            sumq += (float) x[i].qs[j] * xf[j];
++        }
++        sumf += x[i].s * sumq;
++#endif
++    }
++
++    *s = sumf;
++}
++
+ void ggml_vec_dot_q2_K_q8_K_generic(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc) {
+     assert(nrc == 1);
+     UNUSED(nrc);
+diff --git a/ggml/src/ggml-cpu/quants.h b/ggml/src/ggml-cpu/quants.h
+index 93ea7ee..541f292 100644
+--- a/ggml/src/ggml-cpu/quants.h
++++ b/ggml/src/ggml-cpu/quants.h
+@@ -58,6 +58,11 @@ void ggml_vec_dot_q6_K_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const voi
+ void ggml_vec_dot_tq1_0_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ void ggml_vec_dot_tq2_0_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ 
++// Fermion FV5/FV5B: single portable implementation (scalar with an AVX2 fast
++// path inside), dotted against raw F32 activations — no _generic/arch split.
++void ggml_vec_dot_fv5_f32 (int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
++void ggml_vec_dot_fv5b_f32(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
++
+ void ggml_vec_dot_iq2_xxs_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ void ggml_vec_dot_iq2_xs_q8_K (int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ void ggml_vec_dot_iq2_s_q8_K  (int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+diff --git a/ggml/src/ggml-quants.c b/ggml/src/ggml-quants.c
+index 1ebc50a..39ea3cf 100644
+--- a/ggml/src/ggml-quants.c
++++ b/ggml/src/ggml-quants.c
+@@ -2483,6 +2483,43 @@ void dequantize_row_tq2_0(const block_tq2_0 * GGML_RESTRICT x, float * GGML_REST
+     }
+ }
+ 
++// ====================== Fermion five-value ternary (FV5 / FV5B)
++//
++// FV5 blocks are produced offline by the TRTC v4 -> GGUF converter; there is
++// no float -> FV5 quantizer here on purpose (the container is the source of
++// truth). Reconstruction semantics match the container exactly:
++//   w[j] = (bp[j] - bn[j]) * (br[j] ? s_hi : s_lo)   (all f32)
++
++void dequantize_row_fv5(const block_fv5 * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k) {
++    assert(k % QK_FV5 == 0);
++    const int64_t nb = k / QK_FV5;
++
++    for (int64_t i = 0; i < nb; ++i) {
++        const float s_lo = x[i].s_lo;
++        const float s_hi = x[i].s_hi;
++
++        for (int j = 0; j < QK_FV5; ++j) {
++            const int     byte = j >> 3;
++            const uint8_t bit  = 1u << (j & 7);
++            const int sign = ((x[i].bp[byte] & bit) ? 1 : 0) - ((x[i].bn[byte] & bit) ? 1 : 0);
++            const float mag = (x[i].br[byte] & bit) ? s_hi : s_lo;
++            y[i*QK_FV5 + j] = (float) sign * mag;
++        }
++    }
++}
++
++void dequantize_row_fv5b(const block_fv5b * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k) {
++    assert(k % QK_FV5 == 0);
++    const int64_t nb = k / QK_FV5;
++
++    for (int64_t i = 0; i < nb; ++i) {
++        const float s = x[i].s;
++        for (int j = 0; j < QK_FV5; ++j) {
++            y[i*QK_FV5 + j] = s * (float) x[i].qs[j];
++        }
++    }
++}
++
+ // ====================== "True" 2-bit (de)-quantization
+ 
+ void dequantize_row_iq2_xxs(const block_iq2_xxs * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k) {
+@@ -5604,6 +5641,34 @@ bool ggml_validate_row_data(enum ggml_type type, const void * data, size_t nbyte
+             {
+                 VALIDATE_ROW_DATA_D_F16_IMPL(block_tq2_0, data, nb);
+             } break;
++        case GGML_TYPE_FV5:
++            {
++                const block_fv5 * q = (const block_fv5 *) data;
++                for (size_t i = 0; i < nb; ++i) {
++                    if (!validate_float(q[i].s_lo, i) || !validate_float(q[i].s_hi, i)) {
++                        return false;
++                    }
++                    for (int j = 0; j < QK_FV5/8; ++j) {
++                        if (q[i].bp[j] & q[i].bn[j]) {
++                            fprintf(stderr, "%s: fv5 invariant bp&bn != 0 at block %zu byte %d\n", __func__, i, j);
++                            return false;
++                        }
++                        if (q[i].br[j] & ~(q[i].bp[j] | q[i].bn[j])) {
++                            fprintf(stderr, "%s: fv5 invariant br outside bp|bn at block %zu byte %d\n", __func__, i, j);
++                            return false;
++                        }
++                    }
++                }
++            } break;
++        case GGML_TYPE_FV5B:
++            {
++                const block_fv5b * q = (const block_fv5b *) data;
++                for (size_t i = 0; i < nb; ++i) {
++                    if (!validate_float(q[i].s, i)) {
++                        return false;
++                    }
++                }
++            } break;
+         case GGML_TYPE_IQ1_S:
+             {
+                 VALIDATE_ROW_DATA_D_F16_IMPL(block_iq1_s, data, nb);
+diff --git a/ggml/src/ggml-quants.h b/ggml/src/ggml-quants.h
+index 75188f1..f71e078 100644
+--- a/ggml/src/ggml-quants.h
++++ b/ggml/src/ggml-quants.h
+@@ -65,6 +65,9 @@ GGML_API void dequantize_row_q8_K(const block_q8_K * GGML_RESTRICT x, float * GG
+ GGML_API void dequantize_row_tq1_0(const block_tq1_0 * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ GGML_API void dequantize_row_tq2_0(const block_tq2_0 * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ 
++GGML_API void dequantize_row_fv5 (const block_fv5  * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
++GGML_API void dequantize_row_fv5b(const block_fv5b * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
++
+ GGML_API void dequantize_row_iq2_xxs(const block_iq2_xxs * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ GGML_API void dequantize_row_iq2_xs (const block_iq2_xs  * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ GGML_API void dequantize_row_iq2_s  (const block_iq2_s   * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+diff --git a/ggml/src/ggml.c b/ggml/src/ggml.c
+index a7d1fe7..7de0dda 100644
+--- a/ggml/src/ggml.c
++++ b/ggml/src/ggml.c
+@@ -942,6 +942,22 @@ static const struct ggml_type_traits type_traits[GGML_TYPE_COUNT] = {
+         .type_size                = 0,
+         .is_quantized             = false,
+     },
++    [GGML_TYPE_FV5] = {
++        .type_name                = "fv5",
++        .blck_size                = QK_FV5,
++        .type_size                = sizeof(block_fv5),
++        .is_quantized             = true,
++        .to_float                 = (ggml_to_float_t) dequantize_row_fv5,
++        .from_float_ref           = NULL, // produced offline by the TRTC v4 -> GGUF converter
++    },
++    [GGML_TYPE_FV5B] = {
++        .type_name                = "fv5b",
++        .blck_size                = QK_FV5,
++        .type_size                = sizeof(block_fv5b),
++        .is_quantized             = true,
++        .to_float                 = (ggml_to_float_t) dequantize_row_fv5b,
++        .from_float_ref           = NULL, // produced offline by the TRTC v4 -> GGUF converter
++    },
+ };
+ 
+ const struct ggml_type_traits * ggml_get_type_traits(enum ggml_type type) {
+diff --git a/gguf-py/gguf/constants.py b/gguf-py/gguf/constants.py
+index d55253e..05076c9 100644
+--- a/gguf-py/gguf/constants.py
++++ b/gguf-py/gguf/constants.py
+@@ -4595,6 +4595,8 @@ class GGMLQuantizationType(IntEnum):
+     NVFP4   = 40
+     Q1_0    = 41
+     Q2_0    = 42
++    FV5     = 43
++    FV5B    = 44
+ 
+ 
+ class ExpertGatingFuncType(IntEnum):
+@@ -4651,6 +4653,7 @@ class LlamaFileType(IntEnum):
+     MOSTLY_NVFP4         = 39  # except 1d tensors
+     MOSTLY_Q1_0          = 40  # except 1d tensors
+     MOSTLY_Q2_0          = 41  # except 1d tensors
++    MOSTLY_FV5           = 42  # Fermion five-value ternary; int8 embed/lm_head (FV5B), norms F32
+ 
+     GUESSED              = 1024  # not specified in the model file
+ 
+@@ -4777,6 +4780,8 @@ GGML_QUANT_SIZES: dict[GGMLQuantizationType, tuple[int, int]] = {
+     GGMLQuantizationType.NVFP4:   (64, 4 + 32),
+     GGMLQuantizationType.Q1_0:    (128, 2 + 16),
+     GGMLQuantizationType.Q2_0:    (64, 2 + 16),
++    GGMLQuantizationType.FV5:     (256, 4 + 4 + 3 * 32),
++    GGMLQuantizationType.FV5B:    (256, 4 + 256),
+ }
+ 
+ 
+diff --git a/gguf-py/gguf/quants.py b/gguf-py/gguf/quants.py
+index 80966b6..c7122e5 100644
+--- a/gguf-py/gguf/quants.py
++++ b/gguf-py/gguf/quants.py
+@@ -654,6 +654,50 @@ class TQ2_0(__Quant, qtype=GGMLQuantizationType.TQ2_0):
+         return (d * qs.astype(np.float32))
+ 
+ 
++class FV5(__Quant, qtype=GGMLQuantizationType.FV5):
++    # Fermion five-value ternary. Blocks are produced offline by the
++    # TRTC v4 -> GGUF converter; float -> FV5 quantization is intentionally
++    # not implemented (per-row dual scales live in the container).
++    # Layout: f32 s_lo, f32 s_hi, bp[32], bn[32], br[32] (little bit order).
++    @classmethod
++    def quantize_blocks(cls, blocks: np.ndarray) -> np.ndarray:
++        raise NotImplementedError("FV5 is produced offline from TRTC v4 containers")
++
++    @classmethod
++    def dequantize_blocks(cls, blocks: np.ndarray) -> np.ndarray:
++        n_blocks = blocks.shape[0]
++
++        s_lo, s_hi, bp, bn, br = np.hsplit(blocks, [4, 8, 40, 72])
++
++        s_lo = s_lo.view(np.float32)  # (n, 1)
++        s_hi = s_hi.view(np.float32)
++
++        bp = np.unpackbits(bp, axis=-1, bitorder="little")  # (n, 256) in {0,1}
++        bn = np.unpackbits(bn, axis=-1, bitorder="little")
++        br = np.unpackbits(br, axis=-1, bitorder="little")
++
++        sign = bp.astype(np.float32) - bn.astype(np.float32)
++        mag = np.where(br != 0, s_hi, s_lo).astype(np.float32)
++        return sign * mag
++
++
++class FV5B(__Quant, qtype=GGMLQuantizationType.FV5B):
++    # Fermion int8 rows (TRTC v4 embed/lm_head records): w = f32(s) * int8 q.
++    # Layout: f32 s, int8 qs[256].
++    @classmethod
++    def quantize_blocks(cls, blocks: np.ndarray) -> np.ndarray:
++        raise NotImplementedError("FV5B is produced offline from TRTC v4 containers")
++
++    @classmethod
++    def dequantize_blocks(cls, blocks: np.ndarray) -> np.ndarray:
++        s, qs = np.hsplit(blocks, [4])
++
++        s = s.view(np.float32)          # (n, 1)
++        qs = qs.view(np.int8)           # (n, 256)
++
++        return s * qs.astype(np.float32)
++
++
+ class MXFP4(__Quant, qtype=GGMLQuantizationType.MXFP4):
+     # e2m1 values (doubled)
+     # ref: https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf
+diff --git a/include/llama.h b/include/llama.h
+index 9fab693..584717c 100644
+--- a/include/llama.h
++++ b/include/llama.h
+@@ -156,6 +156,7 @@ extern "C" {
+         LLAMA_FTYPE_MOSTLY_NVFP4         = 39, // except 1d tensors
+         LLAMA_FTYPE_MOSTLY_Q1_0          = 40, // except 1d tensors
+         LLAMA_FTYPE_MOSTLY_Q2_0          = 41, // except 1d tensors
++        LLAMA_FTYPE_MOSTLY_FV5           = 42, // Fermion five-value ternary; int8 embed/lm_head (FV5B), norms F32
+ 
+         LLAMA_FTYPE_GUESSED = 1024, // not specified in the model file
+     };
+diff --git a/src/llama-model-loader.cpp b/src/llama-model-loader.cpp
+index 43447f5..6fb50f8 100644
+--- a/src/llama-model-loader.cpp
++++ b/src/llama-model-loader.cpp
+@@ -58,6 +58,7 @@ const char * llama_ftype_name(llama_ftype ftype) {
+         case LLAMA_FTYPE_MOSTLY_Q6_K:      name = LLAMA_FTYPE_PREFIX "Q6_K"; break;
+         case LLAMA_FTYPE_MOSTLY_TQ1_0:     name = LLAMA_FTYPE_PREFIX "TQ1_0 - 1.69 bpw ternary"; break;
+         case LLAMA_FTYPE_MOSTLY_TQ2_0:     name = LLAMA_FTYPE_PREFIX "TQ2_0 - 2.06 bpw ternary"; break;
++        case LLAMA_FTYPE_MOSTLY_FV5:       name = LLAMA_FTYPE_PREFIX "FV5 - 3.25 bpw Fermion five-value ternary"; break;
+         case LLAMA_FTYPE_MOSTLY_IQ2_XXS:   name = LLAMA_FTYPE_PREFIX "IQ2_XXS - 2.0625 bpw"; break;
+         case LLAMA_FTYPE_MOSTLY_IQ2_XS:    name = LLAMA_FTYPE_PREFIX "IQ2_XS - 2.3125 bpw"; break;
+         case LLAMA_FTYPE_MOSTLY_IQ2_S:     name = LLAMA_FTYPE_PREFIX "IQ2_S - 2.5 bpw"; break;
+@@ -746,6 +747,7 @@ llama_model_loader::llama_model_loader(
+             case GGML_TYPE_Q6_K:    ftype = LLAMA_FTYPE_MOSTLY_Q6_K;    break;
+             case GGML_TYPE_TQ1_0:   ftype = LLAMA_FTYPE_MOSTLY_TQ1_0;   break;
+             case GGML_TYPE_TQ2_0:   ftype = LLAMA_FTYPE_MOSTLY_TQ2_0;   break;
++            case GGML_TYPE_FV5:     ftype = LLAMA_FTYPE_MOSTLY_FV5;     break;
+             case GGML_TYPE_IQ2_XXS: ftype = LLAMA_FTYPE_MOSTLY_IQ2_XXS; break;
+             case GGML_TYPE_IQ2_XS:  ftype = LLAMA_FTYPE_MOSTLY_IQ2_XS;  break;
+             case GGML_TYPE_IQ2_S:   ftype = LLAMA_FTYPE_MOSTLY_IQ2_S;   break;
+diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt
+index 780df32..e39837d 100644
+--- a/tools/CMakeLists.txt
++++ b/tools/CMakeLists.txt
+@@ -15,6 +15,7 @@ llama_add_compile_flags()
+ if (EMSCRIPTEN)
+ else()
+     add_subdirectory(batched-bench)
++    add_subdirectory(fermion-greedy)
+     add_subdirectory(gguf-split)
+     add_subdirectory(imatrix)
+     add_subdirectory(llama-bench)
+diff --git a/tools/fermion-greedy/CMakeLists.txt b/tools/fermion-greedy/CMakeLists.txt
+new file mode 100644
+index 0000000..021440a
+--- /dev/null
++++ b/tools/fermion-greedy/CMakeLists.txt
+@@ -0,0 +1,5 @@
++set(TARGET llama-fermion-greedy)
++add_executable(${TARGET} fermion-greedy.cpp)
++install(TARGETS ${TARGET} RUNTIME)
++target_link_libraries(${TARGET} PRIVATE llama ${CMAKE_THREAD_LIBS_INIT})
++target_compile_features(${TARGET} PRIVATE cxx_std_17)
+diff --git a/tools/fermion-greedy/fermion-greedy.cpp b/tools/fermion-greedy/fermion-greedy.cpp
+new file mode 100644
+index 0000000..6f7fde2
+--- /dev/null
++++ b/tools/fermion-greedy/fermion-greedy.cpp
+@@ -0,0 +1,299 @@
++// fermion-greedy — deterministic greedy runner for the Fermion FV5 correctness gate.
++//
++// Reads prompts as EXACT token ids (no tokenizer in the loop), runs pure
++// argmax greedy generation, and — when a reference stream is given — also a
++// teacher-forced pass that feeds the reference token at every step while
++// recording where our argmax disagrees and by what logit margin. Root-cause
++// flips (teacher-forced mismatches) are the gate currency: free-run streams
++// diverge wholesale after one flip, forced mode localizes every disagreement.
++//
++// The KV cache is kept in F32 so the only numerical difference vs the f32
++// expansion reference is operation order, not storage precision.
++//
++// usage:
++//   llama-fermion-greedy -m model.gguf --prompts prompts.txt [--ref ref.txt]
++//                        [--steps 128] [-t nthreads] [--out receipt.json]
++//
++// prompts.txt: one prompt per line, comma-separated token ids
++// ref.txt:     one line per prompt, comma-separated reference continuation ids
++// output:      JSON receipt on stdout (or --out file)
++
++#include "llama.h"
++
++#include <chrono>
++#include <cinttypes>
++#include <cstdio>
++#include <cstdlib>
++#include <cstring>
++#include <fstream>
++#include <sstream>
++#include <string>
++#include <vector>
++
++static double now_s() {
++    using clk = std::chrono::steady_clock;
++    return std::chrono::duration<double>(clk::now().time_since_epoch()).count();
++}
++
++static std::vector<std::vector<llama_token>> read_id_lines(const std::string & path) {
++    std::vector<std::vector<llama_token>> out;
++    std::ifstream f(path);
++    if (!f) {
++        fprintf(stderr, "error: cannot open %s\n", path.c_str());
++        exit(1);
++    }
++    std::string line;
++    while (std::getline(f, line)) {
++        if (line.empty()) {
++            continue;
++        }
++        std::vector<llama_token> ids;
++        std::stringstream ss(line);
++        std::string tok;
++        while (std::getline(ss, tok, ',')) {
++            if (!tok.empty()) {
++                ids.push_back((llama_token) strtol(tok.c_str(), nullptr, 10));
++            }
++        }
++        if (!ids.empty()) {
++            out.push_back(std::move(ids));
++        }
++    }
++    return out;
++}
++
++struct step_info {
++    llama_token top1;
++    float       logit_top1;
++    llama_token top2;
++    float       logit_top2;
++};
++
++// argmax + runner-up over the last decoded token's logits
++static step_info argmax2(const float * logits, int n_vocab) {
++    step_info si = { 0, -1e30f, 0, -1e30f };
++    for (int i = 0; i < n_vocab; ++i) {
++        const float v = logits[i];
++        if (v > si.logit_top1) {
++            si.top2 = si.top1; si.logit_top2 = si.logit_top1;
++            si.top1 = i;       si.logit_top1 = v;
++        } else if (v > si.logit_top2) {
++            si.top2 = i;       si.logit_top2 = v;
++        }
++    }
++    return si;
++}
++
++int main(int argc, char ** argv) {
++    std::string model_path;
++    std::string prompts_path;
++    std::string ref_path;
++    std::string out_path;
++    int steps     = 128;
++    int n_threads = 8;
++
++    for (int i = 1; i < argc; ++i) {
++        auto need = [&](const char * flag) -> const char * {
++            if (i + 1 >= argc) { fprintf(stderr, "error: %s needs a value\n", flag); exit(1); }
++            return argv[++i];
++        };
++        if      (!strcmp(argv[i], "-m"))        { model_path   = need("-m"); }
++        else if (!strcmp(argv[i], "--prompts")) { prompts_path = need("--prompts"); }
++        else if (!strcmp(argv[i], "--ref"))     { ref_path     = need("--ref"); }
++        else if (!strcmp(argv[i], "--out"))     { out_path     = need("--out"); }
++        else if (!strcmp(argv[i], "--steps"))   { steps        = atoi(need("--steps")); }
++        else if (!strcmp(argv[i], "-t"))        { n_threads    = atoi(need("-t")); }
++        else { fprintf(stderr, "error: unknown arg %s\n", argv[i]); return 1; }
++    }
++    if (model_path.empty() || prompts_path.empty()) {
++        fprintf(stderr, "usage: %s -m model.gguf --prompts ids.txt [--ref ids.txt] [--steps N] [-t N] [--out f.json]\n", argv[0]);
++        return 1;
++    }
++
++    const auto prompts = read_id_lines(prompts_path);
++    std::vector<std::vector<llama_token>> refs;
++    if (!ref_path.empty()) {
++        refs = read_id_lines(ref_path);
++        if (refs.size() != prompts.size()) {
++            fprintf(stderr, "error: %zu prompts but %zu reference lines\n", prompts.size(), refs.size());
++            return 1;
++        }
++    }
++
++    size_t max_prompt = 0;
++    for (const auto & p : prompts) {
++        max_prompt = p.size() > max_prompt ? p.size() : max_prompt;
++    }
++
++    ggml_backend_load_all();
++
++    llama_model_params mparams = llama_model_default_params();
++    mparams.n_gpu_layers = 0;
++    const double t_load0 = now_s();
++    llama_model * model = llama_model_load_from_file(model_path.c_str(), mparams);
++    if (model == nullptr) {
++        fprintf(stderr, "error: failed to load %s\n", model_path.c_str());
++        return 1;
++    }
++    const double t_load = now_s() - t_load0;
++
++    const llama_vocab * vocab = llama_model_get_vocab(model);
++    const int n_vocab = llama_vocab_n_tokens(vocab);
++
++    llama_context_params cparams = llama_context_default_params();
++    cparams.n_ctx           = (uint32_t) (max_prompt + steps + 8);
++    cparams.n_batch         = (uint32_t) (max_prompt + 8);
++    cparams.n_threads       = n_threads;
++    cparams.n_threads_batch = n_threads;
++    cparams.type_k          = GGML_TYPE_F32;   // keep KV in f32: gate compares against an f32 reference
++    cparams.type_v          = GGML_TYPE_F32;
++    cparams.flash_attn_type = LLAMA_FLASH_ATTN_TYPE_DISABLED; // conservative numerics for the gate
++    cparams.no_perf         = true;
++
++    llama_context * ctx = llama_init_from_model(model, cparams);
++    if (ctx == nullptr) {
++        fprintf(stderr, "error: failed to create context\n");
++        return 1;
++    }
++
++    FILE * out = stdout;
++    if (!out_path.empty()) {
++        out = fopen(out_path.c_str(), "w");
++        if (!out) {
++            fprintf(stderr, "error: cannot write %s\n", out_path.c_str());
++            return 1;
++        }
++    }
++
++    fprintf(out, "{\n  \"model\": \"%s\",\n  \"steps\": %d,\n  \"n_threads\": %d,\n  \"load_seconds\": %.2f,\n  \"kv_type\": \"f32\",\n  \"prompts\": [\n",
++            model_path.c_str(), steps, n_threads, t_load);
++
++    double total_gen_s    = 0.0;
++    double total_prompt_s = 0.0;
++    int64_t total_gen_tok    = 0;
++    int64_t total_prompt_tok = 0;
++    int     total_forced_mismatch = 0;
++    bool    all_free_match = true;
++
++    for (size_t pi = 0; pi < prompts.size(); ++pi) {
++        std::vector<llama_token> prompt = prompts[pi];
++
++        // ---------------- free-running greedy pass ----------------
++        llama_memory_clear(llama_get_memory(ctx), true);
++
++        double t0 = now_s();
++        llama_batch batch = llama_batch_get_one(prompt.data(), (int32_t) prompt.size());
++        if (llama_decode(ctx, batch) != 0) {
++            fprintf(stderr, "error: prompt decode failed (prompt %zu)\n", pi);
++            return 1;
++        }
++        const double prompt_s = now_s() - t0;
++
++        std::vector<llama_token> free_stream;
++        float min_margin_free = 1e30f;
++        t0 = now_s();
++        for (int t = 0; t < steps; ++t) {
++            const float * logits = llama_get_logits_ith(ctx, -1);
++            step_info si = argmax2(logits, n_vocab);
++            const float margin = si.logit_top1 - si.logit_top2;
++            if (margin < min_margin_free) {
++                min_margin_free = margin;
++            }
++            free_stream.push_back(si.top1);
++            if (t + 1 < steps) {
++                llama_token next = si.top1;
++                batch = llama_batch_get_one(&next, 1);
++                if (llama_decode(ctx, batch) != 0) {
++                    fprintf(stderr, "error: decode failed (prompt %zu step %d)\n", pi, t);
++                    return 1;
++                }
++            }
++        }
++        const double gen_s = now_s() - t0;
++
++        total_prompt_s   += prompt_s;
++        total_gen_s      += gen_s;
++        total_prompt_tok += (int64_t) prompt.size();
++        total_gen_tok    += steps;
++
++        fprintf(out, "    {\n      \"prompt_ids\": [");
++        for (size_t i = 0; i < prompt.size(); ++i) {
++            fprintf(out, "%s%d", i ? "," : "", prompt[i]);
++        }
++        fprintf(out, "],\n      \"free_ids\": [");
++        for (size_t i = 0; i < free_stream.size(); ++i) {
++            fprintf(out, "%s%d", i ? "," : "", free_stream[i]);
++        }
++        fprintf(out, "],\n      \"free_min_top2_margin\": %.6f,\n", min_margin_free);
++        fprintf(out, "      \"prompt_seconds\": %.3f,\n      \"gen_seconds\": %.3f", prompt_s, gen_s);
++
++        if (!refs.empty()) {
++            const std::vector<llama_token> & ref = refs[pi];
++            const int n_ref = (int) ref.size() < steps ? (int) ref.size() : steps;
++
++            // free-run vs reference (first divergence)
++            int first_div = -1;
++            for (int t = 0; t < n_ref; ++t) {
++                if (free_stream[t] != ref[t]) { first_div = t; break; }
++            }
++            const bool free_match = first_div < 0;
++            all_free_match = all_free_match && free_match;
++
++            // ---------------- teacher-forced pass ----------------
++            llama_memory_clear(llama_get_memory(ctx), true);
++            batch = llama_batch_get_one(prompt.data(), (int32_t) prompt.size());
++            if (llama_decode(ctx, batch) != 0) {
++                fprintf(stderr, "error: forced prompt decode failed (prompt %zu)\n", pi);
++                return 1;
++            }
++
++            int n_mismatch = 0;
++            std::string mm_json;
++            char buf[256];
++            for (int t = 0; t < n_ref; ++t) {
++                const float * logits = llama_get_logits_ith(ctx, -1);
++                step_info si = argmax2(logits, n_vocab);
++                if (si.top1 != ref[t]) {
++                    const float logit_ref = logits[ref[t]];
++                    snprintf(buf, sizeof(buf),
++                             "%s\n        {\"step\": %d, \"got\": %d, \"want\": %d, \"logit_got\": %.6f, \"logit_want\": %.6f, \"margin\": %.6f}",
++                             n_mismatch ? "," : "", t, si.top1, ref[t], si.logit_top1, logit_ref, si.logit_top1 - logit_ref);
++                    mm_json += buf;
++                    n_mismatch++;
++                }
++                llama_token next = ref[t];   // teacher-force the reference stream
++                if (t + 1 < n_ref) {
++                    batch = llama_batch_get_one(&next, 1);
++                    if (llama_decode(ctx, batch) != 0) {
++                        fprintf(stderr, "error: forced decode failed (prompt %zu step %d)\n", pi, t);
++                        return 1;
++                    }
++                }
++            }
++            total_forced_mismatch += n_mismatch;
++
++            fprintf(out, ",\n      \"free_match\": %s,\n      \"first_divergence\": %d,\n      \"forced_mismatch_count\": %d,\n      \"forced_mismatches\": [%s%s]",
++                    free_match ? "true" : "false", first_div, n_mismatch,
++                    mm_json.c_str(), n_mismatch ? "\n      " : "");
++        }
++
++        fprintf(out, "\n    }%s\n", pi + 1 < prompts.size() ? "," : "");
++        fflush(out);
++        fprintf(stderr, "prompt %zu/%zu done (%.1f tok/s gen)\n", pi + 1, prompts.size(), steps / gen_s);
++    }
++
++    fprintf(out, "  ],\n  \"totals\": {\n");
++    fprintf(out, "    \"prompt_tokens\": %" PRId64 ",\n    \"gen_tokens\": %" PRId64 ",\n", total_prompt_tok, total_gen_tok);
++    fprintf(out, "    \"prompt_tok_per_s\": %.2f,\n    \"gen_tok_per_s\": %.2f,\n",
++            total_prompt_tok / (total_prompt_s > 0 ? total_prompt_s : 1e-9),
++            total_gen_tok    / (total_gen_s    > 0 ? total_gen_s    : 1e-9));
++    fprintf(out, "    \"forced_mismatch_total\": %d,\n    \"all_free_match\": %s\n  }\n}\n",
++            total_forced_mismatch, (refs.empty() || !all_free_match) ? (refs.empty() ? "null" : "false") : "true");
++
++    if (out != stdout) {
++        fclose(out);
++    }
++    llama_free(ctx);
++    llama_model_free(model);
++    return 0;
++}
+-- 
+2.50.1 (Apple Git-155)
+

gguf/neutrino-0.6b-base-fv5.gguf

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

gguf/receipts/bench_0p6b.json

@@ -0,0 +1,112 @@
+{
+ "model": "0p6b",
+ "bench": [
+  {
+   "build_commit": "e07b3ec",
+   "build_number": 2,
+   "cpu_info": "unknown",
+   "gpu_info": "",
+   "backends": "CPU",
+   "model_filename": "/vol/gguf/neutrino-0.6b-base-fv5.gguf",
+   "model_type": "qwen3 0.6B FV5 - 3.25 bpw Fermion five-value ternary",
+   "model_size": 337188864,
+   "model_n_params": 596049920,
+   "n_batch": 2048,
+   "n_ubatch": 512,
+   "n_threads": 16,
+   "cpu_mask": "0x0",
+   "cpu_strict": false,
+   "poll": 50,
+   "type_k": "f16",
+   "type_v": "f16",
+   "n_gpu_layers": -1,
+   "n_cpu_moe": 0,
+   "split_mode": "layer",
+   "main_gpu": 0,
+   "no_kv_offload": false,
+   "flash_attn": -1,
+   "devices": "auto",
+   "tensor_split": "0.00",
+   "tensor_buft_overrides": "none",
+   "load_mode": "mmap",
+   "embeddings": false,
+   "no_op_offload": 0,
+   "no_host": false,
+   "fit_target": 0,
+   "fit_min_ctx": 0,
+   "n_prompt": 512,
+   "n_gen": 0,
+   "n_depth": 0,
+   "test_time": "2026-07-25T10:23:15Z",
+   "avg_ns": 3873491459,
+   "stddev_ns": 672837,
+   "avg_ts": 132.180492,
+   "stddev_ts": 0.02296,
+   "samples_ns": [
+    3873015691,
+    3873967227
+   ],
+   "samples_ts": [
+    132.197,
+    132.164
+   ]
+  },
+  {
+   "build_commit": "e07b3ec",
+   "build_number": 2,
+   "cpu_info": "unknown",
+   "gpu_info": "",
+   "backends": "CPU",
+   "model_filename": "/vol/gguf/neutrino-0.6b-base-fv5.gguf",
+   "model_type": "qwen3 0.6B FV5 - 3.25 bpw Fermion five-value ternary",
+   "model_size": 337188864,
+   "model_n_params": 596049920,
+   "n_batch": 2048,
+   "n_ubatch": 512,
+   "n_threads": 16,
+   "cpu_mask": "0x0",
+   "cpu_strict": false,
+   "poll": 50,
+   "type_k": "f16",
+   "type_v": "f16",
+   "n_gpu_layers": -1,
+   "n_cpu_moe": 0,
+   "split_mode": "layer",
+   "main_gpu": 0,
+   "no_kv_offload": false,
+   "flash_attn": -1,
+   "devices": "auto",
+   "tensor_split": "0.00",
+   "tensor_buft_overrides": "none",
+   "load_mode": "mmap",
+   "embeddings": false,
+   "no_op_offload": 0,
+   "no_host": false,
+   "fit_target": 0,
+   "fit_min_ctx": 0,
+   "n_prompt": 0,
+   "n_gen": 128,
+   "n_depth": 0,
+   "test_time": "2026-07-25T10:23:27Z",
+   "avg_ns": 2311377861,
+   "stddev_ns": 12562356,
+   "avg_ts": 55.379041,
+   "stddev_ts": 0.300981,
+   "samples_ns": [
+    2320260659,
+    2302495064
+   ],
+   "samples_ts": [
+    55.1662,
+    55.5919
+   ]
+  }
+ ],
+ "smoke_rc": 0,
+ "smoke_text": "located in the capital of the country. The capital of France is located in the capital of the country. The capital of France is located in the capital of the country. The capital of France is located in the capital of the country. The",
+ "threads": 16,
+ "cpu": "unknown",
+ "nproc": 32,
+ "wall_s": 20.4,
+ "ts": "2026-07-25T10:23:34Z"
+}

gguf/receipts/convert_0p6b.json

@@ -0,0 +1,44 @@
+{
+ "status": "CONVERT_PASS",
+ "container": {
+  "name": "neutrino-0p6b_v4_base.bin",
+  "sha256": "91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399"
+ },
+ "f32_gguf": {
+  "name": "neutrino-0.6b-base-f32.gguf",
+  "bytes": 3012480800
+ },
+ "out": {
+  "name": "neutrino-0.6b-base-fv5.gguf",
+  "bytes": 343140320,
+  "sha256": "dd9354c4b3cd2b34195b0270540e4fa5db3811e42b6e4bdbd57958e0027e9272"
+ },
+ "tensors": {
+  "fv5": 196,
+  "fv5b": 1,
+  "f32": 113,
+  "total": 310,
+  "bitwise_checked": 310
+ },
+ "tied_output_omitted": true,
+ "quantized_params": 595984384,
+ "effective_bpw_quantized": 4.606,
+ "header": {
+  "magic": 1129599572,
+  "version": 4,
+  "arch": 3,
+  "n_layers": 28,
+  "hidden": 1024,
+  "n_heads": 16,
+  "n_kv_heads": 8,
+  "head_dim": 128,
+  "rotary_dims": 128,
+  "intermediate": 3072,
+  "vocab": 151936,
+  "max_pos": 40960,
+  "rms_norm_eps": 9.999999974752427e-07,
+  "rope_theta": 1000000.0,
+  "eok": 1
+ },
+ "wall_seconds": 14.6
+}

gguf/receipts/gv_0p6b_f32.json

@@ -0,0 +1,17 @@
+{
+ "model": "0p6b",
+ "variant": "f32",
+ "verdict": "PASS",
+ "all_free_match": true,
+ "forced_mismatch_total": 0,
+ "gen_tok_per_s": 35.04,
+ "prompt_tok_per_s": 140.06,
+ "flips": [],
+ "unexplained": 0,
+ "gguf_sha256": "3f3e8864c18f450240bab0498fac871a64dcc3eed72bfa97f35cbf33881db3e5",
+ "ref_trajectory_sha256": "685bd94b1f77b041ce7836bb2d45042b142799b824837bcc420271494a4fabdd",
+ "threads": 16,
+ "cpu": "unknown",
+ "wall_s": 63.0,
+ "ts": "2026-07-25T10:23:13Z"
+}

gguf/receipts/gv_0p6b_fv5.json

@@ -0,0 +1,17 @@
+{
+ "model": "0p6b",
+ "variant": "fv5",
+ "verdict": "PASS",
+ "all_free_match": true,
+ "forced_mismatch_total": 0,
+ "gen_tok_per_s": 51.63,
+ "prompt_tok_per_s": 92.96,
+ "flips": [],
+ "unexplained": 0,
+ "gguf_sha256": "dd9354c4b3cd2b34195b0270540e4fa5db3811e42b6e4bdbd57958e0027e9272",
+ "ref_trajectory_sha256": "685bd94b1f77b041ce7836bb2d45042b142799b824837bcc420271494a4fabdd",
+ "threads": 16,
+ "cpu": "unknown",
+ "wall_s": 43.7,
+ "ts": "2026-07-25T10:22:09Z"
+}

gguf/receipts/ref_0p6b.json

@@ -0,0 +1,26 @@
+{
+ "model": "0p6b",
+ "dtype": "float32",
+ "steps": 128,
+ "trajectory_sha256": "685bd94b1f77b041ce7836bb2d45042b142799b824837bcc420271494a4fabdd",
+ "continuity_vs_banked_fp16": [
+  {
+   "prompt": 0,
+   "fp16_match": true,
+   "first_divergence": -1
+  },
+  {
+   "prompt": 1,
+   "fp16_match": true,
+   "first_divergence": -1
+  },
+  {
+   "prompt": 2,
+   "fp16_match": true,
+   "first_divergence": -1
+  }
+ ],
+ "wall_s": 212.4,
+ "cpu": "unknown",
+ "ts": "2026-07-25T10:16:30Z"
+}

mlx/MANIFEST.json

@@ -0,0 +1,122 @@
+{
+ "note": "MLX pack provenance: file -> bytes/sha256/source. Weights entry is declarative (not duplicated in this subfolder).",
+ "generated_utc": "2026-07-25T16:52:04Z",
+ "weights_container": {
+  "file": "neutrino-0.6b_v4.bin",
+  "status": "NOT-IN-SUBFOLDER; parent card materialization applies",
+  "bytes": 327719836,
+  "sha256": "91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399",
+  "source": "Fermion Research release archive",
+  "gated_on": "this exact container (V1 refgate + cachegate + pathgate receipts in receipts/)"
+ },
+ "files": {
+  "README.md": {
+   "bytes": 5392,
+   "sha256": "c32d9fa4f7dbbc53ecdad2131c1e33596e57f6045acc8f0790a9d2431f014b11",
+   "source": "pack file"
+  },
+  "fermion_mlx/__init__.py": {
+   "bytes": 5063,
+   "sha256": "a547844d587067681639df546e6d010dab80bbd4f0ee55c6e2a16fba97a1dd40",
+   "source": "NEW: load()/generate()/chat() API"
+  },
+  "fermion_mlx/__main__.py": {
+   "bytes": 8069,
+   "sha256": "71e8c7fea446184bd471af2c37e51b04b9fa8d0f5d35e0a76c31f6fd19af957d",
+   "source": "NEW: CLI (gen/chat/gate/cachegate/pathgate/bench) + spec/specgate/specbench modes"
+  },
+  "fermion_mlx/arch3.py": {
+   "bytes": 7541,
+   "sha256": "a831e8a24b2b9a986b393d1c316aac66a3399a082a57176254b2feeae032f8cd",
+   "source": "NEW (2026-07-25): fused per-head QK-RMSNorm+rope+KV-append kernel + s8 v3 x-staged int8 unembed"
+  },
+  "fermion_mlx/container.py": {
+   "bytes": 6059,
+   "sha256": "c5b352184ba9ddf9a3e424731226cb7dcb9901d3a1516c67d4557953b0101f2f",
+   "source": "NEW: TRTC v4 arch-3 reader"
+  },
+  "fermion_mlx/gates.py": {
+   "bytes": 7394,
+   "sha256": "64d07d9ba1a783a3f56ba978da7885e9fbe693495b3a4b7b8e176607d59de52c",
+   "source": "NEW: house V1 refgate / cachegate / pathgate"
+  },
+  "fermion_mlx/mbatch.py": {
+   "bytes": 6492,
+   "sha256": "c9ec8d37f1cdc0554cda01cefbc435e67525779c79e0dac7fd760e7919e6fdd2",
+   "source": "NEW (2026-07-25): M-token batched trit/s8 GEMMs for speculative verify (one weight read per k+1 positions)"
+  },
+  "fermion_mlx/model.py": {
+   "bytes": 12748,
+   "sha256": "9488f8194ce8be006ce05dfaf6118353de44005ce54f38f73a0908ccac2749da",
+   "source": "NEW: MetalTritQwen3 walker (fused primary path + mx.fast-ops reference twin)"
+  },
+  "fermion_mlx/spec.py": {
+   "bytes": 11207,
+   "sha256": "969e946d5d2eeb63d44afa4c62dd2453d87fa14e83b936bc673482b59ee3b745",
+   "source": "NEW (2026-07-25): EXPERIMENTAL greedy-exact speculative decoding (0.6B drafts, 8B verifies), exactness-gated"
+  },
+  "fermion_mlx/trit_kernels.py": {
+   "bytes": 44135,
+   "sha256": "aeb8bd4b03419763c1543893f19be3b4029611b2df883096990c4beebade384b",
+   "source": "the banked five-value Metal GEMV stack"
+  },
+  "generation_config.json": {
+   "bytes": 181,
+   "sha256": "6ca52b0bcb818c9e52db8ea18413494110c5f2def581b769f621dda951a7863b",
+   "source": "donor Qwen/Qwen3-0.6B @ c1899de289a04d12100db370d81485cdf75e47ca (pinned revision from export receipts / greedy cache)"
+  },
+  "merges.txt": {
+   "bytes": 1671853,
+   "sha256": "8831e4f1a044471340f7c0a83d7bd71306a5b867e95fd870f74d0c5308a904d5",
+   "source": "donor Qwen/Qwen3-0.6B @ c1899de289a04d12100db370d81485cdf75e47ca (pinned revision from export receipts / greedy cache)"
+  },
+  "receipts/bench_0p6b_m5.json": {
+   "bytes": 812,
+   "sha256": "543a9e41d8374a8cd066643a4e7cfa925359a8efc9c3182cbebb366bb0afbe89",
+   "source": "gate/bench receipt (2026-07-25)"
+  },
+  "receipts/cachegate_0p6b.json": {
+   "bytes": 775,
+   "sha256": "b6acd64a31f4529ea01b96103a44b5bc54da283a7c3250cd564b5510ebaabc8c",
+   "source": "gate/bench receipt (2026-07-25)"
+  },
+  "receipts/kernel_version_sweep_0p6b.json": {
+   "bytes": 355,
+   "sha256": "6b0df2026ded00c50d6b34004bf2dc4aabf097d21decfad7a354de5be594fe87",
+   "source": "gate/bench receipt (2026-07-25)"
+  },
+  "receipts/pathgate_0p6b.json": {
+   "bytes": 623,
+   "sha256": "2453e15509a012616a100e3767a373af20a763dff89104e3c4dfbeb24085d072",
+   "source": "gate/bench receipt (2026-07-25)"
+  },
+  "receipts/refgate_0p6b.json": {
+   "bytes": 1907,
+   "sha256": "ee4b3949bad85a522f1d1b65344a230a40f9fe9dc5e5dfdca736c28751eb4d85",
+   "source": "gate/bench receipt (2026-07-25)"
+  },
+  "requirements.txt": {
+   "bytes": 191,
+   "sha256": "1cf4d1fa581aaa5deae0568f88388c51166bbd69e7a89080b5a53488a7ef39b6",
+   "source": "pack file"
+  },
+  "tokenizer.json": {
+   "bytes": 11422654,
+   "sha256": "aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4",
+   "source": "donor Qwen/Qwen3-0.6B @ c1899de289a04d12100db370d81485cdf75e47ca (pinned revision from export receipts / greedy cache)"
+  },
+  "tokenizer_config.json": {
+   "bytes": 9732,
+   "sha256": "d5d09f07b48c3086c508b30d1c9114bd1189145b74e982a265350c923acd8101",
+   "source": "donor Qwen/Qwen3-0.6B @ c1899de289a04d12100db370d81485cdf75e47ca (pinned revision from export receipts / greedy cache)"
+  },
+  "vocab.json": {
+   "bytes": 2776833,
+   "sha256": "ca10d7e9fb3ed18575dd1e277a2579c16d108e32f27439684afa0e10b1440910",
+   "source": "donor Qwen/Qwen3-0.6B @ c1899de289a04d12100db370d81485cdf75e47ca (pinned revision from export receipts / greedy cache)"
+  }
+ },
+ "addenda": [
+  "2026-07-25: EXPERIMENTAL --spec speculative decoding added (new modules mbatch.py/spec.py + CLI modes + README section). Exactness-gated: specgate 6/6 token-identical vs plain (receipts). Existing gate battery re-verified on the updated package."
+ ]
+}

mlx/README.md

@@ -0,0 +1,116 @@
+# Neutrino-0.6B — MLX pack (Apple silicon)
+
+> [!IMPORTANT]
+> **Neutrino-0.6B exists as the speculative-decoding DRAFT for
+> Neutrino-8B** — that pairing is its supported purpose. It is a BASE
+> model: not an assistant, no chat/instruction/tool claims. For a small
+> conversational model use Neutrino-0.6B-Chat.
+
+Run the [Neutrino-0.6B](../README.md) five-value (sub-2-bit) container
+natively from Python on Apple silicon: MLX + our custom Metal kernels. The
+weights stay bit-packed at rest — the five-value {0, ±s_lo, ±s_hi} planes
+are decoded inside the GEMV kernels; nothing in the decode path is
+fp16/fp32 weight material.
+
+This pack is the **Python/MLX lane**. The fastest way to run this model on
+a Mac remains the `fermion-run` CPU binary shipped in the Neutrino-8B
+repo's `bin/` (225–236 tok/s on M5, 9 threads); this pack is for MLX users
+who want the model inside a Python process (notebooks, pipelines, mlx
+ecosystems) with certified-faithful outputs.
+
+## Install & run
+
+```bash
+pip install -r requirements.txt        # mlx, numpy, transformers
+# fetch neutrino-0.6b_v4.bin per the parent card (sha256 must match)
+python -m fermion_mlx --model neutrino-0.6b_v4.bin --mode gen \
+    --tokenizer . --prompt "The key idea behind ternary neural networks is"
+```
+
+Python API:
+
+```python
+import fermion_mlx
+from transformers import AutoTokenizer
+
+model = fermion_mlx.load("neutrino-0.6b_v4.bin")     # memory-maps the container
+tok = AutoTokenizer.from_pretrained(".")             # tokenizer files ship here
+text, stats = fermion_mlx.generate(model, tok, "2, 3, 5, 7, 11,",
+                                   max_tokens=64)
+print(text, stats)                                   # {'tok_s': ..., ...}
+```
+
+This is a BASE model: prompt it as a completion engine (see the parent
+card's honest-numbers table before using it for anything capability-heavy).
+
+## What runs on the GPU
+
+- 3-bit-planar five-value GEMV (`trit_kernels.py`, kernel v7: threadgroup
+  LUT decode, interleaved 8-row plane layout) for qkv / o / gate+up / down,
+  with RMSNorm, SwiGLU and residual adds fused into the GEMV epilogues.
+- The arch-3 (Qwen3) delta — **per-head Q/K-RMSNorm + NeoX rope + KV-cache
+  append** — fused into one dispatch (`arch3.py`).
+- int8 embedding/unembedding lanes with threadgroup x-staging (`arch3.py`,
+  s8 v3); embeddings dequantize one row per token (int8 × fp32 row scale —
+  exact).
+- MLX supplies SDPA (fp32 KV, block-grown windows), argmax, and the lazy
+  graph; the decode step is `mx.compile`d.
+
+## Correctness receipts (this exact container, sha `91c0b26d…`)
+
+House rule: greedy streams must be token-identical to the container's own
+fp expansion reference; near-tie argmax flips at tiny logit margins are the
+only tolerated class, and every flip must be documented with its margin.
+Receipts in `receipts/`:
+
+| gate | reference | result |
+|---|---|---|
+| V1 refgate | fp32 HF expansion of this container (eager attn), teacher-forced 9 pos + 24-token greedy | **PASS — TF rel err 0.000% (max), cos 1.000000, argmax 9/9, greedy 24/24, 0 flips** |
+| cachegate | banked HF fp16 greedy cache `86565bf6` (3 prompts × 128 steps, Modal CPU) | **PASS — 0 flips / 384 tokens** |
+| pathgate | fused-kernel path vs pure `mx.fast`-ops twin | 32-token greedy IDENTICAL |
+
+Note: the int8-activation CPU engine documents 2 benign near-tie flips
+(top-2 margins 0.02–0.20 logits) against the same fp16 cache on this
+checkpoint's flat logit landscape. The MLX path (fp32 activations) resolves
+all 384 positions identically to the HF reference — 0 flips, no near-tie
+class needed.
+
+## Speed (honest numbers, with venue)
+
+| path | venue | 512-token greedy decode |
+|---|---|---|
+| this MLX pack (kernel v7) | Apple M5 MacBook (16 GB), macOS, MLX 0.31.2, median of 5 runs, 2026-07-25 | **201 tok/s** (197–202 across runs, peak MLX mem 0.53 GiB) |
+| `fermion-run` CPU binary (same container) | same M5, 9 threads, banked re-receipt | 225–236 tok/s |
+
+The CPU binary remains this SKU's speed crown; the MLX lane buys native
+Python integration with certified outputs. Kernel version selectable via
+`TRIT_METAL_V` (7 = default/fastest; the sweep receipt is in
+`receipts/`).
+
+## EXPERIMENTAL: this pack drafts for Neutrino-8B
+
+The same package powers `--spec` speculative decoding where this 0.6B
+drafts and the Neutrino-8B pack verifies under the greedy-exact acceptance
+rule (output stream exactness-gated, token-identical to plain 8B decode).
+See the Neutrino-8B MLX pack README for the mode, receipts, and honest
+per-text-type numbers (real speedup on high-acceptance text only).
+
+## Files
+
+- `fermion_mlx/` — the loader/runtime package (self-contained, including
+  the Metal GEMV kernels).
+- `tokenizer.json`, `tokenizer_config.json`, `vocab.json`, `merges.txt`,
+  `generation_config.json` — donor tokenizer (Qwen/Qwen3-0.6B @
+  `c1899de289a04d12100db370d81485cdf75e47ca`, the pinned revision from the
+  export receipts).
+- `receipts/` — gate + bench receipts (JSON), kernel-source SHA sidecar.
+- `MANIFEST.json` — file-by-file provenance + shas.
+
+Weights: not duplicated in this subfolder — use the parent card's
+materialization instructions (`neutrino-0.6b_v4.bin`, sha256
+`91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399`).
+
+## License
+
+Apache-2.0 (weights and this pack's code). Derivative of Qwen/Qwen3-0.6B —
+see the parent `LICENSE`.

mlx/fermion_mlx/__init__.py

@@ -0,0 +1,130 @@
+"""fermion_mlx — run Fermion Research TRTC v4 arch-3 (Qwen3-family) ternary
+containers on Apple silicon via MLX + custom Metal kernels.
+
+    import fermion_mlx
+    model = fermion_mlx.load("neutrino-0p6b_v4_base.bin")
+    text = fermion_mlx.generate(model, tokenizer, "The capital of France is",
+                                max_tokens=64)
+
+The five-value {0, ±s_lo, ±s_hi} weights stay bit-packed at rest and are
+decoded inside the GEMV kernels; nothing is expanded to fp16/fp32 weights.
+Kernel version: env TRIT_METAL_V (default 7 = the banked LUT-decode bodies).
+"""
+import os
+
+# choose the crown kernel bodies before the kernel module is imported
+# (v9 = single-barrier double-buffered LUT, gated bit-identical to v7;
+#  set TRIT_METAL_V=7 to fall back to the previous default)
+os.environ.setdefault("TRIT_METAL_V", "9")
+
+from .model import MetalTritQwen3  # noqa: E402
+
+
+def load(container_path, maxseq=1024, verbose=True):
+    """Memory-map a TRTC v4 arch-3 container and build the Metal model."""
+    return MetalTritQwen3(container_path, maxseq=maxseq, verbose=verbose)
+
+
+DEFAULT_EOS = (151645, 151643)  # <|im_end|>, <|endoftext|>
+
+
+def _as_ids(x):
+    """Normalise whatever a tokenizer handed back into a flat list of ids.
+
+    transformers >= 4.56 flipped `apply_chat_template(tokenize=True)` to
+    return a BatchEncoding instead of a list of ids (return_dict defaults to
+    True). requirements.txt says `transformers>=4.53`, so a fresh install gets
+    the new behaviour and the old code fed a BatchEncoding straight into
+    `model.prefill`, which died with
+    `int() argument must be ... not 'tokenizers.Encoding'`.
+    """
+    if hasattr(x, "input_ids"):
+        x = x.input_ids
+    elif isinstance(x, dict) and "input_ids" in x:
+        x = x["input_ids"]
+    if len(x) and isinstance(x[0], (list, tuple)):   # batched -> first row
+        x = x[0]
+    return [int(t) for t in x]
+
+
+def _rp_greedy(model, ids, n, rp, eos=None):
+    """Greedy decode with the CTRL/HF multiplicative repetition penalty.
+
+    Byte-for-byte the rule the graded MLX battery used
+    (`rp_greedy`): the penalty applies to every id SEEN SO FAR in the whole
+    context, not to a 256-token window — that is the MLX-side convention and
+    it is what the banked MLX numbers on the model card were produced at.
+
+    This path materialises the logits every step, so it forfeits the fused
+    fast path's one-step async lookahead. It is only taken when rp != 1.0;
+    `model.generate` (rp = 1.0) is untouched, so the banked tok/s receipts
+    still describe the default.
+    """
+    import time
+
+    import mlx.core as mx
+    import numpy as np
+
+    eos = set(eos or ())
+    mask = model.new_mask()
+    x, pos0 = model.prefill(ids, mask)
+    seen = set(int(t) for t in ids)
+    toks = []
+    t0 = time.perf_counter()
+    for i in range(n):
+        pb = mx.array([pos0 + i], dtype=mx.int32)
+        W = model._window(pos0 + i)
+        nt, xn, lg = model.step_compiled(x, pb, mask, W)
+        lgn = np.array(lg, copy=True)
+        idxs = np.fromiter(seen, dtype=np.int64)
+        vals = lgn[idxs]
+        lgn[idxs] = np.where(vals > 0, vals / rp, vals * rp)
+        tsel = int(lgn.argmax())
+        toks.append(tsel)
+        if tsel in eos:
+            break
+        x = model.embed(tsel)
+        seen.add(tsel)
+    return toks, time.perf_counter() - t0
+
+
+def _decode(model, tokenizer, ids, max_tokens, eos, rep_penalty):
+    if rep_penalty and float(rep_penalty) != 1.0:
+        toks, dt = _rp_greedy(model, ids, max_tokens, float(rep_penalty),
+                              eos=eos)
+    else:
+        toks, dt = model.generate(ids, max_tokens, eos=eos)
+    if eos:
+        cut = next((i for i, t in enumerate(toks) if t in eos), len(toks))
+        toks = toks[:cut]
+    text = tokenizer.decode(toks)
+    rate = (len(toks) or 1) / dt if dt > 0 else 0.0
+    return text, {"tokens": len(toks), "seconds": dt, "tok_s": rate}
+
+
+def generate(model, tokenizer, prompt, max_tokens=256, stop_on_eos=True,
+             rep_penalty=1.0):
+    """Greedy completion of a plain-text prompt. Returns (text, stats).
+
+    `rep_penalty` > 1.0 enables the CTRL-style repetition penalty the graded
+    MLX battery ran at (1.05 on the chat SKU); 1.0, the default, is the
+    untouched pure-argmax fast path.
+    """
+    ids = _as_ids(tokenizer(prompt))
+    eos = set(DEFAULT_EOS) if stop_on_eos else None
+    return _decode(model, tokenizer, ids, max_tokens, eos, rep_penalty)
+
+
+def chat(model, tokenizer, messages, max_tokens=256, rep_penalty=1.0):
+    """Chat completion via the donor chat template (thinking off).
+
+    `rep_penalty` as in `generate`; the chat SKU's card documents 1.05.
+    """
+    try:
+        raw = tokenizer.apply_chat_template(messages, add_generation_prompt=True,
+                                            enable_thinking=False)
+    except TypeError:
+        raw = tokenizer.apply_chat_template(messages, add_generation_prompt=True)
+    ids = _as_ids(raw)
+    return _decode(model, tokenizer, ids, max_tokens, set(DEFAULT_EOS),
+                   rep_penalty)

mlx/fermion_mlx/__main__.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""fermion_mlx CLI.
+
+  python -m fermion_mlx --model x.bin --mode gen   --prompt "..."
+  python -m fermion_mlx --model x.bin --mode chat  --prompt "..." --tokenizer DIR
+  python -m fermion_mlx --model x.bin --mode chat  --prompt "..." --tokenizer DIR \
+      --rep-penalty 1.05      # the graded chat-SKU config
+  python -m fermion_mlx --model x.bin --mode gate      --ref neutrino_ref.npz
+  python -m fermion_mlx --model x.bin --mode cachegate --cache hf_greedy_cache.json
+  python -m fermion_mlx --model x.bin --mode pathgate
+  python -m fermion_mlx --model x.bin --mode bench --runs 5 --gen-tokens 512
+
+EXPERIMENTAL speculative decoding (0.6B drafts, exactness-gated):
+  python -m fermion_mlx --model 8b.bin --draft-model 0.6b.bin --mode spec \
+      --prompt "..." --tokenizer DIR --mem-limit-gb 6
+  python -m fermion_mlx --model 8b.bin --draft-model 0.6b.bin --mode specgate \
+      --tokenizer DIR --mem-limit-gb 6 --receipt specgate.json
+  python -m fermion_mlx --model 8b.bin --draft-model 0.6b.bin --mode specbench \
+      --tokenizer DIR --mem-limit-gb 6 --receipt specbench.json
+
+Gate receipts are written next to --receipt (JSON) when given.
+"""
+import argparse
+import json
+import sys
+import time
+
+import mlx.core as mx
+
+import fermion_mlx
+from fermion_mlx.gates import refgate, cachegate, pathgate
+
+HOUSE_PROMPT = "The key idea behind ternary neural networks is"
+# tokenizer-free fallback: Qwen3-tokenized HOUSE_PROMPT (donor-verified ids)
+HOUSE_IDS = [785, 1376, 4522, 4815, 71617, 658, 29728, 14155, 374]
+
+
+def _tok(args):
+    from transformers import AutoTokenizer
+    return AutoTokenizer.from_pretrained(args.tokenizer)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", required=True)
+    ap.add_argument("--mode", default="gen",
+                    choices=["gen", "chat", "gate", "cachegate", "pathgate",
+                             "bench", "spec", "specgate", "specbench"])
+    ap.add_argument("--draft-model", default="",
+                    help="draft container for --mode spec* (e.g. the 0.6B pack)")
+    ap.add_argument("--spec-k", type=int, default=4,
+                    help="draft tokens per speculative round")
+    ap.add_argument("--prompt", default=HOUSE_PROMPT)
+    ap.add_argument("--tokenizer", default="Qwen/Qwen3-0.6B")
+    ap.add_argument("--ref", default="")
+    ap.add_argument("--cache", default="")
+    ap.add_argument("--receipt", default="")
+    ap.add_argument("--tie-tol", type=float, default=0.04, dest="tie_tol")
+    ap.add_argument("--max-flips", type=int, default=8, dest="max_flips")
+    ap.add_argument("--gen-tokens", type=int, default=512)
+    ap.add_argument("--runs", type=int, default=5)
+    ap.add_argument("--maxseq", type=int, default=1024)
+    ap.add_argument("--no-tokenizer", action="store_true",
+                    help="use the pinned house prompt ids (no transformers)")
+    ap.add_argument("--mem-limit-gb", type=float, default=0.0,
+                    help="hard MLX memory limit; the process fails fast "
+                         "instead of pressuring the machine (house OOM rule)")
+    ap.add_argument("--rep-penalty", type=float, default=1.0,
+                    dest="rep_penalty",
+                    help="CTRL-style repetition penalty over the whole "
+                         "context, the rule the graded MLX battery ran at "
+                         "(1.05 on the chat SKU). 1.0 (default) = the "
+                         "untouched pure-argmax fast path.")
+    args = ap.parse_args()
+
+    if args.mem_limit_gb > 0:
+        mx.set_memory_limit(int(args.mem_limit_gb * 2**30))
+        print(f"[mem] MLX memory limit set to {args.mem_limit_gb:.1f} GiB")
+
+    model = fermion_mlx.load(args.model, maxseq=args.maxseq)
+
+    def save(rec):
+        if args.receipt:
+            json.dump(rec, open(args.receipt, "w"), indent=1)
+            print(f"receipt -> {args.receipt}")
+
+    if args.mode in ("spec", "specgate", "specbench"):
+        from fermion_mlx.spec import SpecDecoder, specgate, specbench
+        assert args.draft_model, "--mode spec* needs --draft-model"
+        draft = fermion_mlx.load(args.draft_model, maxseq=args.maxseq)
+        tok = _tok(args)
+        if args.mode == "specgate":
+            rec = specgate(model, draft, tok, k=args.spec_k,
+                           receipt=args.receipt or None)
+            print(f"[specgate] {rec['verdict']}")
+            sys.exit(0 if rec["verdict"] == "PASS" else 1)
+        if args.mode == "specbench":
+            rec = specbench(model, draft, tok, k=args.spec_k,
+                            n=args.gen_tokens, runs=args.runs,
+                            receipt=args.receipt or None)
+            for t, v in rec["types"].items():
+                print(f"[specbench {t}] plain {v['plain_median_tok_s']} -> "
+                      f"spec {v['spec_median_tok_s']} tok/s "
+                      f"({v['speedup']}x, acc {v['acceptance_median']})")
+            return
+        sd = SpecDecoder(model, draft, k=args.spec_k)
+        ids = tok(args.prompt, add_special_tokens=False).input_ids
+        toks, dt, st = sd.generate(ids, args.gen_tokens)
+        print(tok.decode(toks))
+        print(f"[spec: {len(toks)} tok in {dt*1e3:.0f} ms -> "
+              f"{len(toks)/dt:.1f} tok/s | acceptance {st['acceptance']:.3f} "
+              f"| {st['tokens_per_round']} tok/round]")
+        return
+
+    if args.mode == "gate":
+        ok, rec = refgate(model, args.ref, args.tie_tol, args.max_flips)
+        rec["mode"], rec["model"] = "refgate", args.model
+        save(rec)
+        sys.exit(0 if ok else 1)
+
+    if args.mode == "cachegate":
+        ok, rec = cachegate(model, args.model, args.cache, args.tie_tol,
+                            args.max_flips)
+        rec["mode"], rec["model"] = "cachegate", args.model
+        save(rec)
+        sys.exit(0 if ok else 1)
+
+    if args.mode == "pathgate":
+        ids = (HOUSE_IDS if args.no_tokenizer else
+               fermion_mlx._as_ids(_tok(args)(args.prompt)))
+        ok, rec = pathgate(model, ids, n=32)
+        rec["mode"], rec["model"] = "pathgate", args.model
+        save(rec)
+        sys.exit(0 if ok else 1)
+
+    if args.mode == "bench":
+        ids = (HOUSE_IDS if args.no_tokenizer else
+               fermion_mlx._as_ids(_tok(args)(args.prompt)))
+        n = args.gen_tokens
+        model.generate(ids, 16)                     # warmup + kernel JIT
+        rates, runs = [], []
+        for r in range(args.runs):
+            toks, dt = model.generate(ids, n)       # no EOS stop: full budget
+            rates.append(n / dt)
+            runs.append({"run": r, "tokens": n, "seconds": dt, "tok_s": n / dt})
+            print(f"  run {r}: {n} tok in {dt*1e3:.0f} ms -> {rates[-1]:.1f} tok/s")
+        rates.sort()
+        med = rates[len(rates) // 2]
+        peak = mx.get_peak_memory() / 2**30
+        print(f"[bench] median {med:.1f} tok/s over {args.runs} runs "
+              f"({n}-token greedy), peak mem {peak:.2f} GiB")
+        save({"mode": "bench", "model": args.model, "prompt_ids": ids,
+              "gen_tokens": n, "runs": runs, "median_tok_s": med,
+              "peak_mem_gib": peak,
+              "utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())})
+        return
+
+    tok = _tok(args)
+    if args.mode == "gen":
+        text, st = fermion_mlx.generate(model, tok, args.prompt,
+                                        max_tokens=args.gen_tokens,
+                                        rep_penalty=args.rep_penalty)
+        print(text)
+        print(f"[{st['tokens']} tokens in {st['seconds']*1e3:.0f} ms -> "
+              f"{st['tok_s']:.1f} tok/s]")
+    else:
+        text, st = fermion_mlx.chat(model, tok,
+                                    [{"role": "user", "content": args.prompt}],
+                                    max_tokens=args.gen_tokens,
+                                    rep_penalty=args.rep_penalty)
+        print(text)
+        print(f"[{st['tokens']} tokens in {st['seconds']*1e3:.0f} ms -> "
+              f"{st['tok_s']:.1f} tok/s]")
+
+
+if __name__ == "__main__":
+    main()

mlx/fermion_mlx/arch3.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Arch-3 (Qwen3) Metal kernel: fused per-head Q/K-RMSNorm + NeoX rope +
+KV-cache append, one dispatch per decode step.
+
+The Qwen3 arch delta vs arch-1 is the per-head RMSNorm applied to the qkv
+GEMV output BEFORE rope (HF order: q_norm/k_norm over head_dim, weights
+shared across heads). This kernel is the arch-3 twin of
+trit_kernels.rope_append: one simdgroup per head; q/k heads compute the
+head's rms via simd_sum then rope the normed values; v heads copy raw
+values into the cache. kc/vc/mask are written in place at position pos
+(stream-serial ordering with the consumer SDPA — the banked rope_append
+pattern; correctness enforced by the e2e gates).
+"""
+import mlx.core as mx
+
+_CACHE = {}
+SG_PER_TG = 8
+
+
+def _s8_source_v3(rows, cols, rs, sg_per_tg, fuse_norm, eps, rpsg=8):
+    """arch-3 lane addition: int8 GEMV with threadgroup x staging.
+
+    The vendored s8 v2 kernel re-reads the full x vector from device memory
+    once per simdgroup (rows/rpsg simdgroups x cols floats — for the 151936-
+    row Qwen3 unembed that is +50% of the weight bytes). v3 stages the
+    effective x (rmsnorm applied) into threadgroup memory once per
+    THREADGROUP, tile by tile; every simdgroup then streams only its int8
+    rows. Requires rows % (rpsg * sg_per_tg) == 0 (true for vocab 151936)."""
+    assert rs % 4 == 0 and cols % 4 == 0 and rows % (rpsg * sg_per_tg) == 0
+    tile = min(cols, 1024)
+    assert cols % tile == 0
+    ntiles = cols // tile
+    nthreads = sg_per_tg * 32
+    if fuse_norm:
+        norm_pre = f"""
+    threadgroup float ssq_sh[{sg_per_tg}];
+    {{
+        float ssq = 0.0f;
+        for (uint c = tid; c < {cols}u; c += {nthreads}u) {{
+            float v = x[c]; ssq = metal::fma(v, v, ssq);
+        }}
+        ssq = metal::simd_sum(ssq);
+        if (lane == 0u) ssq_sh[sg] = ssq;
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        float tt = 0.0f;
+        for (uint i = 0u; i < {sg_per_tg}u; ++i) tt += ssq_sh[i];
+        rms = metal::rsqrt(tt / {float(cols)}f + {eps:.9g}f);
+    }}
+"""
+        stage = f"xb[cl] = x[c] * nw[c] * rms;"
+    else:
+        norm_pre = ""
+        stage = "xb[cl] = x[c];"
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row0 = (threadgroup_position_in_grid.x * {sg_per_tg}u + sg) * {rpsg}u;
+    float rms = 1.0f;
+{norm_pre}
+    threadgroup float xb[{tile}];
+    float acc[{rpsg}];
+    for (uint r = 0u; r < {rpsg}u; ++r) acc[r] = 0.0f;
+    const float4 one4 = float4(1.0f);
+    for (uint t = 0u; t < {ntiles}u; ++t) {{
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        for (uint cl = tid; cl < {tile}u; cl += {nthreads}u) {{
+            uint c = t * {tile}u + cl;
+            {stage}
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        for (uint i = lane * 4u; i < {tile}u; i += 128u) {{
+            float4 xv = *(const threadgroup float4*)(xb + i);
+            for (uint r = 0u; r < {rpsg}u; ++r) {{
+                char4 wv = *(const device char4*)((const device char*)W
+                            + (ulong)(row0 + r) * {rs}u + t * {tile}u + i);
+                acc[r] += metal::dot(float4(wv.x, wv.y, wv.z, wv.w) * xv, one4);
+            }}
+        }}
+    }}
+    for (uint r = 0u; r < {rpsg}u; ++r) {{
+        float a = metal::simd_sum(acc[r]);
+        if (lane == 0u) out[row0 + r] = scale[row0 + r] * a;
+    }}
+"""
+
+
+def get_s8_gemv_v3(rows, cols, rs, fuse_norm=False, eps=1e-6):
+    key = ("s8v3", rows, cols, rs, fuse_norm, round(eps, 12))
+    if key in _CACHE:
+        return _CACHE[key]
+    inputs = ["W", "scale", "x"]
+    if fuse_norm:
+        inputs.append("nw")
+    src = _s8_source_v3(rows, cols, rs, SG_PER_TG, fuse_norm, eps)
+    k = mx.fast.metal_kernel(name="s8gemv3_r%d_c%d_n%d" % (rows, cols, fuse_norm),
+                             input_names=inputs, output_names=["out"], source=src)
+    _CACHE[key] = (k, inputs)
+    return _CACHE[key]
+
+
+def s8_gemv_v3(W, scale, x, norm_w=None, eps=1e-6, stream=None):
+    """drop-in for trit_kernels.s8_gemv where rows % 64 == 0."""
+    rows, rs = W.shape
+    cols = x.shape[0]
+    k, names = get_s8_gemv_v3(rows, cols, rs, norm_w is not None, eps)
+    vals = {"W": W, "scale": scale, "x": x, "nw": norm_w}
+    nsg = rows // 8
+    ntg = (nsg + SG_PER_TG - 1) // SG_PER_TG
+    return k(inputs=[vals[n] for n in names],
+             grid=(ntg * SG_PER_TG * 32, 1, 1), threadgroup=(SG_PER_TG * 32, 1, 1),
+             output_shapes=[(rows,)], output_dtypes=[mx.float32], stream=stream)[0]
+
+
+def get_qknorm_rope_append(n_heads, n_kv, hd, maxseq, eps):
+    key = ("qkra", n_heads, n_kv, hd, maxseq, round(eps, 12))
+    if key in _CACHE:
+        return _CACHE[key]
+    h2 = hd // 2
+    nheads_total = n_heads + 2 * n_kv
+    src = f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint head = threadgroup_position_in_grid.x * {SG_PER_TG}u + sg;
+    if (head >= {nheads_total}u) return;
+    uint pos = (uint)posbuf[0];
+    if (head == 0u && lane == 0u) {{ ((device float*)mask)[pos] = 0.0f; }}
+    device float* kc_w = (device float*)kc;
+    device float* vc_w = (device float*)vc;
+    if (head < {n_heads + n_kv}u) {{
+        uint base = head * {hd}u;
+        const device float* g = (head < {n_heads}u) ? qn : kn;
+        float ssq = 0.0f;
+        for (uint d = lane; d < {hd}u; d += 32u) {{
+            float v = qkv[base + d];
+            ssq = metal::fma(v, v, ssq);
+        }}
+        ssq = metal::simd_sum(ssq);
+        float rms = metal::rsqrt(ssq / {float(hd)}f + {eps:.9g}f);
+        for (uint d = lane; d < {hd}u; d += 32u) {{
+            float c  = ct[pos * {h2}u + (d % {h2}u)];
+            float sn = st[pos * {h2}u + (d % {h2}u)];
+            float v  = qkv[base + d] * rms * g[d];
+            float vr = (d < {h2}u)
+                     ? -(qkv[base + d + {h2}u] * rms * g[d + {h2}u])
+                     :  (qkv[base + d - {h2}u] * rms * g[d - {h2}u]);
+            float r = metal::fma(v, c, vr * sn);
+            if (head < {n_heads}u) {{
+                qout[base + d] = r;
+            }} else {{
+                uint kh = head - {n_heads}u;
+                kc_w[(ulong)(kh * {maxseq}u + pos) * {hd}u + d] = r;
+            }}
+        }}
+    }} else {{
+        uint vh = head - {n_heads + n_kv}u;
+        for (uint d = lane; d < {hd}u; d += 32u) {{
+            vc_w[(ulong)(vh * {maxseq}u + pos) * {hd}u + d] =
+                qkv[{(n_heads + n_kv) * hd}u + vh * {hd}u + d];
+        }}
+    }}
+"""
+    k = mx.fast.metal_kernel(
+        name="qknorm_rope_append_%d_%d_%d" % (n_heads, n_kv, hd),
+        input_names=["qkv", "qn", "kn", "kc", "vc", "ct", "st", "posbuf", "mask"],
+        output_names=["qout"], source=src)
+    _CACHE[key] = k
+    return k
+
+
+def qknorm_rope_append(qkv, qn, kn, kc, vc, ct, st, posbuf, mask,
+                       n_heads, n_kv, hd, maxseq, eps, stream=None):
+    """qkv fp32 [(n_heads+2*n_kv)*hd] -> roped+normed q fp32 [n_heads*hd];
+    writes normed+roped k and raw v into kc/vc at position posbuf[0] and
+    zeroes mask[pos]."""
+    k = get_qknorm_rope_append(n_heads, n_kv, hd, maxseq, eps)
+    nheads_total = n_heads + 2 * n_kv
+    ntg = (nheads_total + SG_PER_TG - 1) // SG_PER_TG
+    return k(inputs=[qkv, qn, kn, kc, vc, ct, st, posbuf, mask],
+             grid=(ntg * SG_PER_TG * 32, 1, 1), threadgroup=(SG_PER_TG * 32, 1, 1),
+             output_shapes=[(n_heads * hd,)], output_dtypes=[mx.float32],
+             stream=stream)[0]

mlx/fermion_mlx/container.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""TRTC v4 arch-3 (Qwen3) container reader — numpy memmap views, zero-copy
+until the caller materializes.
+
+Layout (ground truth: scripts/export_trit_c_model.py; cross-checks:
+scripts/expand_trtc_v4_to_hf.py and kernels/gpu_e2e/runtime8b.py):
+  60 B header <Iii9i2fi>: magic 'TRTC', version=4, arch=3, n_layers, hidden,
+    n_heads, n_kv_heads, head_dim, rotary_dims, intermediate, vocab, max_pos,
+    f32 rms_norm_eps, f32 rope_theta, i32 embed_out_kind (eok)
+  eok=2 (untied, 8B): int8 embed_in record right after the header
+  per layer: input_layernorm f32[H], post_attention_layernorm f32[H],
+    q_norm f32[head_dim], k_norm f32[head_dim],
+    then 7 trit records (q,k,v,o,gate,up,down) — arch-3 QKV are bias-less
+  final norm f32[H]
+  int8 embed_out (lm_head) record; eok=1 (tied, 0.6B) derives embed_in
+    from this record.
+  trit record: i32 rows, cols, cols_pad, row_stride(bytes);
+    u8 bp/bn/br [rows*row_stride] LSB-first; f32 s_lo[rows], s_hi[rows];
+    i32 rs_lo[rows], rs_hi[rows] (skipped); i32 has_bias (+ f32 bias[rows])
+  int8 record: i32 rows, cols, cols_pad, row_stride (== cols_pad);
+    s8 W[rows*row_stride]; f32 scale[rows]; i32 wsum[rows] (skipped)
+
+Weight semantics: w[r,c] = (bp-bn) * (s_hi[r] if br else s_lo[r]);
+int8 embeds: w[r,c] = scale[r] * Q[r,c].
+"""
+import struct
+
+import numpy as np
+
+MAGIC = 0x43545254
+HDR_FMT = "<Iii9i2fi"
+HDR_BYTES = struct.calcsize(HDR_FMT)  # 60
+PROJS = ("q", "k", "v", "o", "gate", "up", "down")
+
+
+class TritRecord:
+    __slots__ = ("rows", "cols", "cols_pad", "row_stride", "bp", "bn", "br",
+                 "slo", "shi", "bias")
+
+
+class Int8Record:
+    __slots__ = ("rows", "cols", "cols_pad", "row_stride", "W", "scale")
+
+
+class Container:
+    pass
+
+
+def _trit_record(mm, off):
+    r = TritRecord()
+    r.rows, r.cols, r.cols_pad, r.row_stride = (
+        int(v) for v in np.frombuffer(mm, np.int32, 4, off))
+    off += 16
+    n = r.rows * r.row_stride
+    r.bp = np.frombuffer(mm, np.uint8, n, off).reshape(r.rows, r.row_stride); off += n
+    r.bn = np.frombuffer(mm, np.uint8, n, off).reshape(r.rows, r.row_stride); off += n
+    r.br = np.frombuffer(mm, np.uint8, n, off).reshape(r.rows, r.row_stride); off += n
+    r.slo = np.frombuffer(mm, np.float32, r.rows, off); off += 4 * r.rows
+    r.shi = np.frombuffer(mm, np.float32, r.rows, off); off += 4 * r.rows
+    off += 8 * r.rows  # rs_lo, rs_hi trit-sum sidecars (integrity data, unused here)
+    has_bias = int(np.frombuffer(mm, np.int32, 1, off)[0]); off += 4
+    r.bias = None
+    if has_bias:
+        r.bias = np.frombuffer(mm, np.float32, r.rows, off); off += 4 * r.rows
+    return r, off
+
+
+def _int8_record(mm, off):
+    r = Int8Record()
+    r.rows, r.cols, r.cols_pad, r.row_stride = (
+        int(v) for v in np.frombuffer(mm, np.int32, 4, off))
+    assert r.row_stride == r.cols_pad, "int8 record: row_stride must equal cols_pad"
+    off += 16
+    n = r.rows * r.row_stride
+    r.W = np.frombuffer(mm, np.int8, n, off).reshape(r.rows, r.row_stride); off += n
+    r.scale = np.frombuffer(mm, np.float32, r.rows, off); off += 4 * r.rows
+    off += 4 * r.rows  # wsum
+    return r, off
+
+
+def read_container(path):
+    """Memory-map a TRTC v4 arch-3 container; all arrays are views into the map."""
+    mm = np.memmap(path, dtype=np.uint8, mode="r")
+    h = struct.unpack(HDR_FMT, bytes(mm[:HDR_BYTES]))
+    c = Container()
+    (magic, c.version, c.arch, c.n_layers, c.hidden, c.n_heads, c.n_kv,
+     c.head_dim, c.rot, c.inter, c.vocab, c.maxpos, c.eps, c.theta, c.eok) = h
+    assert magic == MAGIC, f"bad magic {magic:#x}"
+    assert c.version == 4 and c.arch == 3, \
+        f"need TRTC v4 arch-3 (got v={c.version} arch={c.arch})"
+    assert c.eok in (1, 2), f"bad embed_out_kind {c.eok}"
+    off = HDR_BYTES
+    c.embed_in = None
+    if c.eok == 2:                      # untied: int8 embed_in follows the header
+        c.embed_in, off = _int8_record(mm, off)
+        assert (c.embed_in.rows, c.embed_in.cols) == (c.vocab, c.hidden)
+    H, hd = c.hidden, c.head_dim
+    q_dim, kv_dim = c.n_heads * hd, c.n_kv * hd
+    shapes = {"q": (q_dim, H), "k": (kv_dim, H), "v": (kv_dim, H),
+              "o": (H, q_dim), "gate": (c.inter, H), "up": (c.inter, H),
+              "down": (H, c.inter)}
+    c.layers = []
+    for li in range(c.n_layers):
+        L = {}
+        L["norm1"] = np.frombuffer(mm, np.float32, H, off); off += 4 * H
+        L["norm2"] = np.frombuffer(mm, np.float32, H, off); off += 4 * H
+        L["qnorm"] = np.frombuffer(mm, np.float32, hd, off); off += 4 * hd
+        L["knorm"] = np.frombuffer(mm, np.float32, hd, off); off += 4 * hd
+        for nm in PROJS:
+            L[nm], off = _trit_record(mm, off)
+            assert (L[nm].rows, L[nm].cols) == shapes[nm], \
+                f"L{li}.{nm}: {(L[nm].rows, L[nm].cols)} != {shapes[nm]}"
+            assert L[nm].bias is None, f"L{li}.{nm}: arch-3 records must be bias-less"
+        c.layers.append(L)
+    c.final_norm = np.frombuffer(mm, np.float32, H, off); off += 4 * H
+    c.embed_out, off = _int8_record(mm, off)
+    assert (c.embed_out.rows, c.embed_out.cols) == (c.vocab, c.hidden)
+    assert off == mm.size, f"reader ended at {off}, file is {mm.size}"
+    if c.embed_in is None:              # tied: same int8 record serves both
+        c.embed_in = c.embed_out
+    c.mm = mm                           # keep the map alive
+    return c
+
+
+# ---------------- fp32 reference math (gate-side, numpy) ----------------
+
+def unpack_plane(plane, cols):
+    return np.unpackbits(plane, axis=1, bitorder="little")[:, :cols]
+
+
+def dense_weights(rec, dtype=np.float32):
+    p = unpack_plane(rec.bp, rec.cols).astype(np.int8)
+    n = unpack_plane(rec.bn, rec.cols).astype(np.int8)
+    h = unpack_plane(rec.br, rec.cols)
+    s = (p - n).astype(dtype)
+    mag = np.where(h.astype(bool), rec.shi[:, None].astype(dtype),
+                   rec.slo[:, None].astype(dtype))
+    return s * mag
+
+
+def ref_rmsnorm(x, g, eps, dtype=np.float32):
+    x = x.astype(dtype)
+    return (x * (1.0 / np.sqrt(np.mean(x * x) + eps))) * g.astype(dtype)

mlx/fermion_mlx/gates.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""House correctness gates for the MLX arch-3 path.
+
+refgate   : V1 gate — teacher-forced logits +
+            greedy-with-resync vs the container's own fp expansion reference
+            npz {prompt_ids, tf_logits, greedy, meta}. Every argmax
+            divergence must be a near-tie <= tie_tol of the logit scale;
+            greedy flips resynced and bounded.
+cachegate : greedy-with-resync vs a banked hf_greedy_cache.json
+            (keyed to container md5).
+pathgate  : path-consistency — the fused-kernel primary path and the pure
+            mx.fast-ops reference twin must produce the same greedy stream.
+
+All gates return (ok, receipt_dict); receipts carry per-flip absolute and
+relative margins so near-tie flips are documented, never waved through.
+"""
+import hashlib
+import json
+
+import mlx.core as mx
+import numpy as np
+
+
+def _md5(path):
+    h = hashlib.md5()
+    with open(path, "rb") as f:
+        while chunk := f.read(1 << 24):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def refgate(model, ref_path, tie_tol=0.04, max_flips=8):
+    ref = np.load(ref_path, allow_pickle=True)
+    ids = [int(t) for t in ref["prompt_ids"].tolist()]
+    tf = ref["tf_logits"]
+    greedy_ref = [int(t) for t in ref["greedy"].tolist()]
+    meta = json.loads(str(ref["meta"])) if "meta" in ref else {}
+    print(f"[refgate] prompt ids ({len(ids)}): {ids}")
+    print(f"[refgate] ref meta: {meta}")
+    rec = {"ref": str(ref_path), "meta": meta, "tf": [], "greedy_flips": [],
+           "tie_tol": tie_tol, "max_flips": max_flips}
+    # stage A: teacher-forced logits
+    mask = model.new_mask()
+    rels, ams, near, worst_gap = [], 0, 0, 0.0
+    for i, t in enumerate(ids):
+        _, _, lg = model.step(model.embed(t), i, mask)
+        g = np.array(lg, np.float64)
+        r = tf[i].astype(np.float64)
+        scale = float(np.abs(r).max())
+        rel = float(np.abs(g - r).max() / scale)
+        cos = float((g * r).sum() / (np.linalg.norm(g) * np.linalg.norm(r)))
+        gam, ram = int(g.argmax()), int(r.argmax())
+        am = gam == ram
+        ams += am
+        rels.append(rel)
+        extra = ""
+        if not am:
+            gap = float(g[gam] - g[ram]) / scale
+            worst_gap = max(worst_gap, gap)
+            near += gap <= tie_tol
+            extra = f" gap {100*gap:.3f}% ({'near-tie' if gap <= tie_tol else 'REAL'})"
+        rec["tf"].append({"pos": i, "rel": rel, "cos": cos, "argmax_match": am})
+        print(f"  pos {i:2d}: rel {100*rel:6.3f}% | cos {cos:.6f} | argmax "
+              f"{'match' if am else 'MISMATCH'} (mlx {gam} ref {ram}){extra}")
+    print(f"[refgate] stage A: TF rel max {100*max(rels):.3f}% / mean "
+          f"{100*float(np.mean(rels)):.3f}%, argmax {ams}/{len(ids)} "
+          f"(+{near} near-tie), worst gap {100*worst_gap:.3f}%")
+    rec["tf_summary"] = {"rel_max": max(rels), "rel_mean": float(np.mean(rels)),
+                         "argmax": f"{ams}/{len(ids)}", "near_tie": near}
+    # stage B: greedy with resync
+    mask = model.new_mask()
+    x, pos0 = model.prefill(ids, mask, compiled=False)
+    flips, g_toks, ok = 0, [], True
+    for s in range(len(greedy_ref)):
+        _, _, lg = model.step(x, pos0 + s, mask)
+        l = np.array(lg, np.float64)
+        g_tok = int(l.argmax())
+        g_toks.append(g_tok)
+        tok = g_tok
+        if g_tok != greedy_ref[s]:
+            gap_abs = float(l[g_tok] - l[greedy_ref[s]])
+            scale = float(np.abs(l).max())
+            gap = gap_abs / scale
+            flips += 1
+            worst_gap = max(worst_gap, gap)
+            rec["greedy_flips"].append({"step": s, "mlx": g_tok,
+                                        "ref": greedy_ref[s],
+                                        "margin_abs_logits": gap_abs,
+                                        "margin_rel": gap})
+            print(f"  step {s}: mlx {g_tok} vs ref {greedy_ref[s]}, gap "
+                  f"{gap_abs:.4f} logits = {100*gap:.3f}% of scale -> resync")
+            if flips > max_flips:
+                ok = False
+                break
+            tok = greedy_ref[s]
+        x = model.embed(tok)
+        mx.eval(x)
+    print(f"[refgate] ref greedy: {greedy_ref}")
+    print(f"[refgate] mlx greedy: {g_toks}")
+    ok = ok and worst_gap <= tie_tol and flips <= max_flips
+    rec.update(flips=flips, worst_gap=worst_gap, ok=bool(ok),
+               mlx_greedy=g_toks, ref_greedy=greedy_ref)
+    print(f"[refgate] {'PASS' if ok else 'FAIL'} (worst gap {100*worst_gap:.3f}% "
+          f"tol {100*tie_tol:.1f}%; {flips} flips, tol {max_flips})")
+    return ok, rec
+
+
+def cachegate(model, container_path, cache_path, tie_tol=0.04, max_flips=8):
+    cache = json.load(open(cache_path))
+    md5 = _md5(container_path)
+    print(f"[cachegate] container md5 {md5} vs cache key {cache['container_md5']}")
+    assert md5 == cache["container_md5"], "cache is for a different container"
+    rec = {"cache": str(cache_path), "container_md5": md5, "prompts": [],
+           "tie_tol": tie_tol, "max_flips_per_prompt": max_flips}
+    ok = True
+    tot_flips, worst = 0, 0.0
+    for pi, (prompt, ref) in enumerate(zip(cache["prompts"], cache["tokens"])):
+        mask = model.new_mask()
+        x, pos0 = model.prefill([int(t) for t in prompt], mask)
+        flips, fliprec = 0, []
+        for s, rt in enumerate(ref):
+            _, _, lg = model.step(x, pos0 + s, mask)
+            l = np.array(lg, np.float64)
+            g_tok = int(l.argmax())
+            tok = g_tok
+            if g_tok != int(rt):
+                gap_abs = float(l[g_tok] - l[int(rt)])
+                gap = gap_abs / float(np.abs(l).max())
+                worst = max(worst, gap)
+                flips += 1
+                fliprec.append({"step": s, "mlx": g_tok, "ref": int(rt),
+                                "margin_abs_logits": gap_abs, "margin_rel": gap})
+                print(f"  p{pi} step {s}: mlx {g_tok} vs hf {rt}, gap "
+                      f"{gap_abs:.4f} logits = {100*gap:.3f}% -> resync")
+                tok = int(rt)
+            x = model.embed(tok)
+            mx.eval(x)
+        tot_flips += flips
+        good = flips <= max_flips
+        ok = ok and good
+        rec["prompts"].append({"prompt": prompt, "steps": len(ref),
+                               "flips": flips, "flip_detail": fliprec,
+                               "pass": bool(good)})
+        print(f"  prompt {pi}: {len(ref)} steps, {flips} resynced flips -> "
+              f"{'PASS' if good else 'FAIL'}")
+    ok = ok and worst <= tie_tol
+    rec.update(total_flips=tot_flips, worst_gap=worst, ok=bool(ok))
+    print(f"[cachegate] {'PASS' if ok else 'FAIL'} ({tot_flips} flips total, "
+          f"worst gap {100*worst:.3f}% tol {100*tie_tol:.1f}%)")
+    return ok, rec
+
+
+def pathgate(model, ids, n=32):
+    """fused-kernel path vs pure-mx.fast-ops twin: greedy streams must be
+    IDENTICAL (same weights, same GEMV kernels; isolates the new kernel)."""
+    fused, _ = model.generate(ids, n, compiled=True)
+    ref = model.generate_ref(ids, n)
+    same = fused == ref
+    d = next((i for i in range(min(len(fused), len(ref)))
+              if fused[i] != ref[i]), None)
+    print(f"[pathgate] fused-vs-mxops {n}-token greedy: "
+          f"{'IDENTICAL' if same else f'FIRST DIVERGENCE at {d}'}")
+    return same, {"n": n, "identical": bool(same), "first_divergence": d,
+                  "fused": fused, "mxops": ref}

mlx/fermion_mlx/mbatch.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Small-batch (M-token) GEMM kernels for speculative verify — EXPERIMENTAL.
+
+Why these exist: the shipped decode path is M=1 GEMV. Speculative decoding
+only wins if the verifier scores k+1 draft positions while streaming the
+weight planes ONCE; re-running the GEMV k+1 times re-reads the weights k+1
+times and cannot beat plain decode. These kernels keep the v5/v7 interleaved
+plane layout + one-weight-read structure and add an M-wide accumulator:
+
+  trit_gemm_m : five-value planes  X[M, cols] -> out[M, rows]
+                v7 lane mapping (lane = row(8) x word-slot(4), planes read
+                once, fully coalesced) + v6 mask-convert-FMA decode (float4
+                (uint4(a) & m4) == 2^bit when set; x pre-scaled by 2^-bit,
+                exact in fp32). No LUT: a per-token LUT tile for M=5 exceeds
+                the 32KB threadgroup budget at inter=12288.
+  s8_gemm_m   : int8 rows (lm_head / untied embeds), one simdgroup per row,
+                weight char4 loaded once and dotted against all M x-vectors.
+
+No norm/GLU/residual template flags here: the spec verify path applies
+RMSNorm / SwiGLU / residual adds as plain MLX elementwise ops on [M, ...]
+tensors (cheap at M<=8), keeping these kernels pure GEMMs.
+
+Additive module — nothing in trit_kernels.py / arch3.py / model.py changes.
+"""
+import mlx.core as mx
+
+SG_PER_TG = 8
+_CACHE = {}
+
+
+def _trit_gemm_m_source(M, rows, cols, rs):
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % 8 == 0
+    W = rs // 4
+    kbody = []
+    for k in range(8):
+        m4 = [1 << (4 * k + i) for i in range(4)]
+        ps = ", ".join("%.9ef" % (2.0 ** -(4 * k + i)) for i in range(4))
+        loads = "\n".join(
+            f"""            {{
+                float4 xs = x4[{m}u * {cols // 4}u + wl * 8u + {k}u] * ps{k};
+                accLo[{m}] += metal::dot(sa, xs);
+                accHi[{m}] += metal::dot(sb, xs);
+            }}""" for m in range(M))
+        kbody.append(f"""        {{
+            const uint4 m4 = uint4({m4[0]}u, {m4[1]}u, {m4[2]}u, {m4[3]}u);
+            const float4 ps{k} = float4({ps});
+            float4 sa = float4(uint4(a) & m4) - float4(uint4(b) & m4);
+            float4 sb = float4(uint4(cc) & m4) - float4(uint4(d) & m4);
+{loads}
+        }}""")
+    kbody = "\n".join(kbody)
+    outs = "\n".join(
+        f"""        accLo[{m}] += metal::simd_shuffle_down(accLo[{m}], 16u);
+        accLo[{m}] += metal::simd_shuffle_down(accLo[{m}], 8u);
+        accHi[{m}] += metal::simd_shuffle_down(accHi[{m}], 16u);
+        accHi[{m}] += metal::simd_shuffle_down(accHi[{m}], 8u);"""
+        for m in range(M))
+    writes = "\n".join(
+        f"        out[{m}u * {rows}u + row] = "
+        f"metal::fma(slo[row], accLo[{m}], shi[row] * accHi[{m}]);"
+        for m in range(M))
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint blk  = threadgroup_position_in_grid.x * {SG_PER_TG}u + sg;
+    uint row0 = blk * 8u;
+    if (row0 >= {rows}u) return;
+    uint r    = lane & 7u;
+    uint wsl  = lane >> 3u;
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    const device float4* x4 = (const device float4*)x;
+    float accLo[{M}], accHi[{M}];
+    for (uint m = 0u; m < {M}u; ++m) {{ accLo[m] = 0.0f; accHi[m] = 0.0f; }}
+    for (uint wl = wsl; wl < {W}u; wl += 4u) {{
+        ulong base = ((ulong)blk * {W}u + wl) * 8u + r;
+        uint pw = p32[base], nw2 = n32[base], hw = h32[base];
+        uint a = pw & ~hw, b = nw2 & ~hw, cc = pw & hw, d = nw2 & hw;
+{kbody}
+    }}
+{outs}
+    if (lane < 8u) {{
+        uint row = row0 + lane;
+{writes}
+    }}
+"""
+
+
+def _s8_gemm_m_source(M, rows, cols, rs):
+    assert rs % 4 == 0 and cols % 4 == 0
+    accs = "\n".join(
+        f"        acc[{m}] += metal::dot(wf, x4[{m}u * {cols // 4}u + i]);"
+        for m in range(M))
+    reduces = "\n".join(
+        f"""    {{
+        float a = metal::simd_sum(acc[{m}]);
+        if (lane == 0u) out[{m}u * {rows}u + row] = scale[row] * a;
+    }}""" for m in range(M))
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row  = threadgroup_position_in_grid.x * {SG_PER_TG}u + sg;
+    if (row >= {rows}u) return;
+    const device char* w = (const device char*)W + (ulong)row * {rs}u;
+    const device float4* x4 = (const device float4*)x;
+    float acc[{M}];
+    for (uint m = 0u; m < {M}u; ++m) acc[m] = 0.0f;
+    for (uint i = lane; i < {cols // 4}u; i += 32u) {{
+        char4 wv = *(const device char4*)(w + i * 4u);
+        float4 wf = float4(wv.x, wv.y, wv.z, wv.w);
+{accs}
+    }}
+{reduces}
+"""
+
+
+def _get(kind, M, rows, cols, rs):
+    key = (kind, M, rows, cols, rs)
+    if key in _CACHE:
+        return _CACHE[key]
+    if kind == "trit":
+        src = _trit_gemm_m_source(M, rows, cols, rs)
+        k = mx.fast.metal_kernel(
+            name=f"tritgemm_m{M}_r{rows}_c{cols}",
+            input_names=["bp", "bn", "br", "slo", "shi", "x"],
+            output_names=["out"], source=src)
+    else:
+        src = _s8_gemm_m_source(M, rows, cols, rs)
+        k = mx.fast.metal_kernel(
+            name=f"s8gemm_m{M}_r{rows}_c{cols}",
+            input_names=["W", "scale", "x"],
+            output_names=["out"], source=src)
+    _CACHE[key] = k
+    return k
+
+
+def trit_gemm_m(planes, slo, shi, X, stream=None):
+    """planes v5-interleaved (KERNEL_VERSION>=5 prep). X fp32 [M, cols]
+    (already normed / activated). Returns fp32 [M, rows]."""
+    bp, bn, br = planes
+    rows, rs = bp.shape
+    M, cols = X.shape
+    k = _get("trit", M, rows, cols, rs)
+    nsg = rows // 8
+    ntg = (nsg + SG_PER_TG - 1) // SG_PER_TG
+    return k(inputs=[bp, bn, br, slo, shi, X],
+             grid=(ntg * SG_PER_TG * 32, 1, 1), threadgroup=(SG_PER_TG * 32, 1, 1),
+             output_shapes=[(M, rows)], output_dtypes=[mx.float32],
+             stream=stream)[0]
+
+
+def s8_gemm_m(W, scale, X, stream=None):
+    """int8 W [rows, rs], X fp32 [M, cols] (already normed). -> [M, rows]."""
+    rows, rs = W.shape
+    M, cols = X.shape
+    k = _get("s8", M, rows, cols, rs)
+    ntg = (rows + SG_PER_TG - 1) // SG_PER_TG
+    return k(inputs=[W, scale, X],
+             grid=(ntg * SG_PER_TG * 32, 1, 1), threadgroup=(SG_PER_TG * 32, 1, 1),
+             output_shapes=[(M, rows)], output_dtypes=[mx.float32],
+             stream=stream)[0]

mlx/fermion_mlx/model.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""End-to-end MLX/Metal decode for TRTC v4 **arch-3 (Qwen3)** five-value
+containers — Neutrino-0.6B (tied int8 embeds) and Neutrino-8B (untied).
+
+Every transformer linear runs on the banked five-value {0,±s_lo,±s_hi}
+3-bit-planar Metal GEMV kernels (vendored trit_kernels.py, byte-identical
+to kernels/metal/trit_kernels.py): qkv / o / gate+up / down fused per layer
++ the int8 lm_head GEMV. The arch-3 delta — per-head Q/K-RMSNorm before
+rope, biasless qkv, int8 embed_in — is handled by the new fused
+qknorm_rope_append kernel (arch3.py) and an int8 embedding dequant.
+
+Fusions per decode token: rmsnorm folded into qkv/gu/lm_head GEMVs, SwiGLU
+folded into the down GEMV, residual adds folded into o/down epilogues,
+QK-norm+rope+KV-append in one dispatch. MLX supplies SDPA, argmax and the
+lazy-graph dispatch batching.
+
+Two forward implementations:
+  _step_fn  : primary path (fused kernel, preallocated KV + additive mask,
+              mx.compile-able) — the shipped/gated/benched path.
+  step_ref  : pure-MLX-ops reference twin for the NEW kernel (mx.fast
+              rms_norm/rope, concat KV) — used by the path-consistency gate.
+"""
+import time
+
+import mlx.core as mx
+import numpy as np
+
+from .container import read_container
+from .trit_kernels import trit_gemv, s8_gemv, prep_planes
+from . import trit_kernels
+from .arch3 import qknorm_rope_append, s8_gemv_v3
+
+NEG_INF = -1e9
+
+
+class _Layer:
+    pass
+
+
+def _cat(arrs):
+    return np.ascontiguousarray(np.concatenate(arrs, axis=0))
+
+
+class MetalTritQwen3:
+    """TRTC v4 arch-3 walker (0.6B or 8B, dims from the container header)."""
+
+    def __init__(self, path, maxseq=1024, verbose=True):
+        t0 = time.time()
+        c = read_container(path)
+        self.meta = c
+        self.eps, self.theta = float(c.eps), float(c.theta)
+        self.n_layers, self.hidden = c.n_layers, c.hidden
+        self.n_heads, self.n_kv, self.hd = c.n_heads, c.n_kv, c.head_dim
+        self.inter, self.vocab, self.eok = c.inter, c.vocab, c.eok
+        assert c.rot == self.hd, "kernels assume full-head_dim rope"
+        self.scale = self.hd ** -0.5
+        self.qd = self.n_heads * self.hd
+        self.kd = self.n_kv * self.hd
+        self.maxseq = maxseq
+
+        # int8 lm_head (+ tied/untied int8 embed_in)
+        eo = c.embed_out
+        self.eoW = mx.array(np.ascontiguousarray(eo.W))          # int8 [V, H]
+        self.eo_scale = mx.array(np.ascontiguousarray(eo.scale))
+        mx.eval(self.eoW, self.eo_scale)
+        if c.eok == 2:
+            ei = c.embed_in
+            self.embW = mx.array(np.ascontiguousarray(ei.W))     # int8 [V, H]
+            self.embS = mx.array(np.ascontiguousarray(ei.scale))
+            mx.eval(self.embW, self.embS)
+        else:
+            self.embW, self.embS = self.eoW, self.eo_scale
+
+        self.layers = []
+        for L in c.layers:
+            q, k, v, o, gate, up, down = (L[n] for n in
+                                          ("q", "k", "v", "o", "gate", "up", "down"))
+            y = _Layer()
+            y.norm1 = mx.array(np.ascontiguousarray(L["norm1"]))
+            y.norm2 = mx.array(np.ascontiguousarray(L["norm2"]))
+            y.qnorm = mx.array(np.ascontiguousarray(L["qnorm"]))
+            y.knorm = mx.array(np.ascontiguousarray(L["knorm"]))
+            y.qkv_planes = prep_planes(tuple(
+                mx.array(_cat([getattr(r, pl) for r in (q, k, v)]))
+                for pl in ("bp", "bn", "br")), q.cols)
+            y.qkv_slo = mx.array(_cat([q.slo, k.slo, v.slo]))
+            y.qkv_shi = mx.array(_cat([q.shi, k.shi, v.shi]))
+            y.o_planes = prep_planes(tuple(
+                mx.array(np.ascontiguousarray(getattr(o, pl)))
+                for pl in ("bp", "bn", "br")), o.cols)
+            y.o_slo = mx.array(np.ascontiguousarray(o.slo))
+            y.o_shi = mx.array(np.ascontiguousarray(o.shi))
+            y.gu_planes = prep_planes(tuple(
+                mx.array(_cat([getattr(gate, pl), getattr(up, pl)]))
+                for pl in ("bp", "bn", "br")), gate.cols)
+            y.gu_slo = mx.array(_cat([gate.slo, up.slo]))
+            y.gu_shi = mx.array(_cat([gate.shi, up.shi]))
+            y.dn_planes = prep_planes(tuple(
+                mx.array(np.ascontiguousarray(getattr(down, pl)))
+                for pl in ("bp", "bn", "br")), down.cols)
+            y.dn_slo = mx.array(np.ascontiguousarray(down.slo))
+            y.dn_shi = mx.array(np.ascontiguousarray(down.shi))
+            mx.eval(*(y.qkv_planes + y.o_planes + y.gu_planes + y.dn_planes),
+                    y.qkv_slo, y.qkv_shi, y.o_slo, y.o_shi,
+                    y.gu_slo, y.gu_shi, y.dn_slo, y.dn_shi,
+                    y.norm1, y.norm2, y.qnorm, y.knorm)
+            self.layers.append(y)
+        self.final_norm = mx.array(np.ascontiguousarray(c.final_norm))
+
+        # rope tables + preallocated KV + mask
+        inv = self.theta ** -(np.arange(0, self.hd, 2, dtype=np.float64) / self.hd)
+        ang = np.outer(np.arange(maxseq, dtype=np.float64), inv)
+        self.ct = mx.array(np.cos(ang).astype(np.float32).ravel())
+        self.st = mx.array(np.sin(ang).astype(np.float32).ravel())
+        self.kc = [mx.zeros((self.n_kv, maxseq, self.hd), dtype=mx.float32)
+                   for _ in self.layers]
+        self.vc = [mx.zeros((self.n_kv, maxseq, self.hd), dtype=mx.float32)
+                   for _ in self.layers]
+        mx.eval(self.ct, self.st, self.final_norm, *self.kc, *self.vc)
+        self._stepc = None
+        # x-restaged int8 unembed when the row count allows it
+        self._s8 = s8_gemv_v3 if self.vocab % 64 == 0 else s8_gemv
+        if verbose:
+            gb = mx.get_active_memory() / 2**30
+            print(f"loaded {path} in {time.time()-t0:.1f}s (arch-3, "
+                  f"{self.n_layers}L/{self.hidden}H/{self.n_heads}q/{self.n_kv}kv/"
+                  f"{self.inter}i/{self.vocab}V eok={self.eok}, kernel v"
+                  f"{trit_kernels.KERNEL_VERSION}, maxseq {maxseq}, "
+                  f"active mem {gb:.2f} GiB)")
+
+    # ---------------- primary path ----------------
+
+    def new_mask(self):
+        m = mx.full((self.maxseq,), NEG_INF, dtype=mx.float32)
+        mx.eval(m)
+        return m
+
+    def embed(self, tok):
+        """int8 embedding dequant: fp32 row = scale[tok] * W8[tok]."""
+        return self.embW[tok].astype(mx.float32) * self.embS[tok]
+
+    def _window(self, pos):
+        """KV window for position pos: grown in 256-slot blocks. Slicing off
+        the -1e9-masked tail is numerically exact (exp underflows to 0.0 in
+        fp32), so shrinking the SDPA read never changes the math — it only
+        stops streaming megabytes of masked cache per step."""
+        return min(self.maxseq, ((pos + 1 + 255) // 256) * 256)
+
+    def _step_fn(self, x, posbuf, mask, W):
+        """x fp32 [H] at position posbuf[0] -> (next_tok, x_next, logits).
+        Fixed shapes per W: SDPA over the first W cache slots with additive
+        mask (stale slots -1e9; qknorm_rope_append maintains mask[pos]=0)."""
+        eps = self.eps
+        m4 = mask[:W].reshape(1, 1, 1, W)
+        for li, L in enumerate(self.layers):
+            qkv = trit_gemv(L.qkv_planes, L.qkv_slo, L.qkv_shi, x,
+                            norm_w=L.norm1, eps=eps)
+            q = qknorm_rope_append(qkv, L.qnorm, L.knorm, self.kc[li], self.vc[li],
+                                   self.ct, self.st, posbuf, mask,
+                                   self.n_heads, self.n_kv, self.hd,
+                                   self.maxseq, eps)
+            q = q.reshape(1, self.n_heads, 1, self.hd)
+            a = mx.fast.scaled_dot_product_attention(
+                q, self.kc[li][:, :W][None], self.vc[li][:, :W][None],
+                scale=self.scale, mask=m4)
+            a = a.reshape(self.qd)
+            x = trit_gemv(L.o_planes, L.o_slo, L.o_shi, a, resid=x, eps=eps)
+            gu = trit_gemv(L.gu_planes, L.gu_slo, L.gu_shi, x,
+                           norm_w=L.norm2, eps=eps)
+            x = trit_gemv(L.dn_planes, L.dn_slo, L.dn_shi, gu, glu=True,
+                          resid=x, eps=eps)
+        logits = self._s8(self.eoW, self.eo_scale, x, norm_w=self.final_norm, eps=eps)
+        nt = mx.argmax(logits)
+        return nt, self.embed(nt), logits
+
+    def step(self, x, pos, mask):
+        """uncompiled single step (gates)."""
+        return self._step_fn(x, mx.array([pos], dtype=mx.int32), mask,
+                             self._window(pos))
+
+    def step_compiled(self, x, posbuf, mask, W):
+        if self._stepc is None:
+            self._stepc = {}
+        if W not in self._stepc:
+            self._stepc[W] = mx.compile(
+                lambda xx, pb, mk, _W=W: self._step_fn(xx, pb, mk, _W))
+        return self._stepc[W](x, posbuf, mask)
+
+    def prefill(self, ids, mask, compiled=True):
+        """feed ids[:-1]; returns (x armed with ids[-1], pos of ids[-1])."""
+        for i, t in enumerate(ids[:-1]):
+            pb = mx.array([i], dtype=mx.int32)
+            W = self._window(i)
+            if compiled:
+                nt, xn, lg = self.step_compiled(self.embed(int(t)), pb, mask, W)
+            else:
+                nt, xn, lg = self._step_fn(self.embed(int(t)), pb, mask, W)
+            mx.eval(lg)
+        x = self.embed(int(ids[-1]))
+        mx.eval(x)
+        return x, len(ids) - 1
+
+    def generate(self, ids, n, compiled=True, eos=None):
+        """greedy decode n tokens after prompt ids; returns (tokens,
+        decode_seconds). eos: optional set of stop ids (stop AFTER emitting)."""
+        mask = self.new_mask()
+        x, pos0 = self.prefill(ids, mask, compiled=compiled)
+        toks = []
+        prev = None
+        t0 = time.perf_counter()
+        for i in range(n):
+            pos = pos0 + i
+            pb = mx.array([pos], dtype=mx.int32)
+            W = self._window(pos)
+            if compiled:
+                nt, x, lg = self.step_compiled(x, pb, mask, W)
+            else:
+                nt, x, lg = self._step_fn(x, pb, mask, W)
+            mx.async_eval(nt, x)
+            if prev is not None:
+                toks.append(int(prev))
+                if eos and toks[-1] in eos:
+                    prev = None
+                    break
+            prev = nt
+        if prev is not None:
+            toks.append(int(prev))
+        mx.eval(x)
+        dt = time.perf_counter() - t0
+        return toks, dt
+
+    # ---------------- pure-MLX-ops reference twin ----------------
+
+    def step_ref(self, x, kv, pos):
+        """same GEMV kernels, but QK-norm/rope/cache via mx.fast ops +
+        concat KV — the cross-check for the NEW fused kernel."""
+        eps = self.eps
+        for li, L in enumerate(self.layers):
+            qkv = trit_gemv(L.qkv_planes, L.qkv_slo, L.qkv_shi, x,
+                            norm_w=L.norm1, eps=eps)
+            q = mx.fast.rms_norm(qkv[:self.qd].reshape(self.n_heads, self.hd),
+                                 L.qnorm, eps)
+            k = mx.fast.rms_norm(qkv[self.qd:self.qd + self.kd]
+                                 .reshape(self.n_kv, self.hd), L.knorm, eps)
+            qk = mx.concatenate([q, k], axis=0).reshape(
+                1, self.n_heads + self.n_kv, 1, self.hd)
+            qk = mx.fast.rope(qk, self.hd, traditional=False, base=self.theta,
+                              scale=1.0, offset=pos)
+            qh = qk[:, :self.n_heads]
+            kh = qk[:, self.n_heads:]
+            vh = qkv[self.qd + self.kd:].reshape(1, self.n_kv, 1, self.hd)
+            if kv[li] is None:
+                kv[li] = (kh, vh)
+            else:
+                kv[li] = (mx.concatenate([kv[li][0], kh], axis=2),
+                          mx.concatenate([kv[li][1], vh], axis=2))
+            keys, values = kv[li]
+            a = mx.fast.scaled_dot_product_attention(qh, keys, values,
+                                                     scale=self.scale)
+            a = a.reshape(self.qd)
+            x = trit_gemv(L.o_planes, L.o_slo, L.o_shi, a, resid=x, eps=eps)
+            gu = trit_gemv(L.gu_planes, L.gu_slo, L.gu_shi, x,
+                           norm_w=L.norm2, eps=eps)
+            x = trit_gemv(L.dn_planes, L.dn_slo, L.dn_shi, gu, glu=True,
+                          resid=x, eps=eps)
+        return self._s8(self.eoW, self.eo_scale, x, norm_w=self.final_norm, eps=eps)
+
+    def generate_ref(self, ids, n):
+        kv = [None] * self.n_layers
+        for i, t in enumerate(ids[:-1]):
+            lg = self.step_ref(self.embed(int(t)), kv, i)
+            mx.eval(lg)
+        x = self.embed(int(ids[-1]))
+        toks = []
+        for i in range(n):
+            lg = self.step_ref(x, kv, len(ids) - 1 + i)
+            nt = mx.argmax(lg)
+            x = self.embed(nt)
+            mx.eval(x)
+            toks.append(int(nt))
+        return toks

mlx/fermion_mlx/spec.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""EXPERIMENTAL speculative decoding: 0.6B pack drafts, 8B pack verifies.
+
+House exactness rule (greedy-exact acceptance): a draft token is accepted
+iff it equals the verifier's argmax at that position. The emitted stream is
+therefore exactly the verifier's own greedy stream *as computed by the
+batched verify path* — the ship gate (specgate) checks that stream is
+token-identical to the shipped single-token path at 32 and 256 tokens.
+
+Mechanics per round (k=4 draft tokens, M=k+1 verify batch):
+  1. draft consumes its pending tokens, then chains k greedy proposals
+     d_1..d_k on its own single-token path;
+  2. verifier scores [pending[-1], d_1..d_k] in ONE batched pass
+     (mbatch.trit_gemm_m / s8_gemm_m — weight planes stream once, which is
+     the entire speedup mechanism on a bandwidth-bound GPU);
+  3. accept the longest prefix with d_i == argmax_{i-1}; emit accepted
+     tokens + the verifier's own next token (correction or bonus);
+  4. KV rewind: positions are the source of truth. The verifier's stale
+     rows get overwritten by the next round's appends before any read (the
+     verify mask only allows slots <= row position). The draft re-masks its
+     stale slots (additive mask back to -1e9) and rolls its position back.
+
+Both models live in one process; run under --mem-limit-gb 6 (house OOM
+rule). Additive module: model.py / gates.py / existing CLI modes untouched.
+"""
+import json
+import time
+
+import mlx.core as mx
+
+from .mbatch import trit_gemm_m, s8_gemm_m
+
+NEG_INF = -1e9
+
+
+def _silu(g):
+    return g * mx.sigmoid(g)
+
+
+class SpecDecoder:
+    def __init__(self, verifier, draft, k=4):
+        assert verifier.vocab == draft.vocab, "draft/verifier vocab mismatch"
+        self.V, self.D, self.k = verifier, draft, k
+        self._vc = {}                    # compiled verify fns keyed (M, W)
+        self._specmask = verifier.new_mask()   # kernel side-channel, never read
+        self.stats = None
+
+    # ---------------- batched verify ----------------
+
+    def _verify(self, toks, pos0):
+        from .arch3 import qknorm_rope_append
+        V = self.V
+        M = len(toks)
+        W = V._window(pos0 + M - 1)
+        key = (M, W)
+        if key not in self._vc:
+            # build an uncompiled closure once; mx.compile wrapper around it
+            eps = V.eps
+
+            def fn(X, pbs, amask, _M=M, _W=W):
+                m4 = amask.reshape(1, 1, _M, _W)
+                for li, L in enumerate(V.layers):
+                    qkv = trit_gemm_m(L.qkv_planes, L.qkv_slo, L.qkv_shi,
+                                      mx.fast.rms_norm(X, L.norm1, eps))
+                    qrows = [qknorm_rope_append(
+                        qkv[m], L.qnorm, L.knorm, V.kc[li], V.vc[li],
+                        V.ct, V.st, pbs[m:m + 1], self._specmask,
+                        V.n_heads, V.n_kv, V.hd, V.maxseq, eps)
+                        for m in range(_M)]
+                    q = mx.stack(qrows).reshape(_M, V.n_heads, V.hd)
+                    q = q.transpose(1, 0, 2)[None]
+                    a = mx.fast.scaled_dot_product_attention(
+                        q, V.kc[li][:, :_W][None], V.vc[li][:, :_W][None],
+                        scale=V.scale, mask=m4)
+                    a = a[0].transpose(1, 0, 2).reshape(_M, V.qd)
+                    X = X + trit_gemm_m(L.o_planes, L.o_slo, L.o_shi, a)
+                    gu = trit_gemm_m(L.gu_planes, L.gu_slo, L.gu_shi,
+                                     mx.fast.rms_norm(X, L.norm2, eps))
+                    h = _silu(gu[:, :V.inter]) * gu[:, V.inter:]
+                    X = X + trit_gemm_m(L.dn_planes, L.dn_slo, L.dn_shi, h)
+                logits = s8_gemm_m(V.eoW, V.eo_scale,
+                                   mx.fast.rms_norm(X, V.final_norm, eps))
+                return mx.argmax(logits, axis=1)
+
+            self._vc[key] = mx.compile(fn)
+        tarr = mx.array(toks, dtype=mx.int32)
+        X = V.embW[tarr].astype(mx.float32) * V.embS[tarr][:, None]
+        pbs = mx.array([pos0 + m for m in range(M)], dtype=mx.int32)
+        idx = mx.arange(W)[None, :]
+        rowp = (pos0 + mx.arange(M))[:, None]
+        amask = mx.where(idx <= rowp, mx.array(0.0, dtype=mx.float32),
+                         mx.array(NEG_INF, dtype=mx.float32))
+        am = self._vc[(M, W)](X, pbs, amask)
+        mx.eval(am)
+        return [int(t) for t in am]
+
+    # ---------------- draft helpers (single-token path) ----------------
+
+    def _draft_chain(self, pending, dmask, dpos):
+        """consume pending tokens, then chain k greedy proposals.
+        Returns (proposals, new_dpos). Draft KV/mask advance by
+        len(pending) + k - 1 consumed inputs."""
+        # NOTE: each step is dispatched with async_eval before the next is
+        # built — the KV/mask writes are input mutations invisible to the
+        # lazy graph, and batching several steps into one evaluation makes
+        # MLX copy-on-write the caches and silently drop intermediate
+        # appends (found the hard way; the shipped generate() uses the same
+        # per-step dispatch discipline).
+        D, k = self.D, self.k
+        pos = dpos
+        nt = x = None
+        for t in pending:
+            pb = mx.array([pos], dtype=mx.int32)
+            nt, x, _ = D.step_compiled(D.embed(int(t)), pb, dmask,
+                                       D._window(pos))
+            mx.async_eval(nt, x)
+            pos += 1
+        props = [nt]                           # d_1
+        for _ in range(k - 1):
+            pb = mx.array([pos], dtype=mx.int32)
+            nt, x, _ = D.step_compiled(x, pb, dmask, D._window(pos))
+            mx.async_eval(nt, x)
+            props.append(nt)
+            pos += 1
+        mx.eval(*props)
+        return [int(p) for p in props], pos
+
+    # ---------------- main loop ----------------
+
+    def generate(self, ids, n):
+        """greedy spec decode: n tokens after prompt ids.
+        Returns (tokens, decode_seconds, stats)."""
+        V, D, k = self.V, self.D, self.k
+        vmask = V.new_mask()
+        dmask = D.new_mask()
+        _, p0 = V.prefill(ids, vmask)
+        _, _ = D.prefill(ids, dmask)
+        # both consumed ids[:-1]; next input ids[-1] at position p0
+        pending = [int(ids[-1])]
+        vpos = dpos = p0
+        toks = []
+        rounds = accepted = proposed = 0
+        hist = [0] * (k + 1)
+        t0 = time.perf_counter()
+        while len(toks) < n:
+            # invariant: pending[-1] sits at position vpos for the verifier
+            # and at dpos + len(pending) - 1 for the draft — same slot.
+            assert dpos + len(pending) - 1 == vpos, (dpos, len(pending), vpos)
+            props, dpos_after = self._draft_chain(pending, dmask, dpos)
+            am = self._verify([pending[-1]] + props, vpos)
+            nacc = 0
+            for i in range(k):
+                if props[i] == am[i]:
+                    nacc += 1
+                else:
+                    break
+            rounds += 1
+            proposed += k
+            accepted += nacc
+            hist[nacc] += 1
+            base = vpos                          # position of pending[-1]
+            if nacc == k:
+                emitted = props + [am[k]]
+                pending = [props[k - 1], am[k]]
+                # draft consumed through d_{k-1} at base+k-1: no rewind
+                dpos = dpos_after
+            else:
+                emitted = props[:nacc] + [am[nacc]]
+                pending = [am[nacc]]
+                # draft rewind: valid through input d_nacc at base+nacc
+                lo, hi = base + nacc + 1, dpos_after
+                if hi > lo:
+                    dmask[lo:hi] = NEG_INF
+                dpos = lo
+            vpos = base + nacc + 1              # verifier valid: <= base+nacc
+            toks.extend(emitted)
+        dt = time.perf_counter() - t0
+        toks = toks[:n]
+        self.stats = {
+            "k": k, "rounds": rounds, "proposed": proposed,
+            "accepted": accepted,
+            "acceptance": round(accepted / max(proposed, 1), 4),
+            "tokens_per_round": round(len(toks) / max(rounds, 1), 3),
+            "accept_hist": hist,
+        }
+        return toks, dt, self.stats
+
+
+# ---------------- gate + bench drivers ----------------
+
+GATE_PROMPTS = {
+    "facts": "The three laws of thermodynamics state that",
+    "prose": "Once upon a time, in a quiet village by the sea,",
+    "chat": "User: How do I reverse a list in Python?\nAssistant:",
+}
+
+
+def specgate(verifier, draft, tok, k=4, lens=(32, 256), receipt=None):
+    """[G1 frozen] WITH --spec vs WITHOUT: token-identical at each length,
+    every prompt. Any mismatch = flag does not ship."""
+    sd = SpecDecoder(verifier, draft, k=k)
+    out = {"gate": "specgate", "k": k, "lens": list(lens), "prompts": {},
+           "verdict": "PASS"}
+    for name, text in GATE_PROMPTS.items():
+        ids = tok(text, add_special_tokens=False).input_ids if tok else None
+        assert ids, "specgate needs a tokenizer"
+        res = {}
+        for n in lens:
+            plain, _ = verifier.generate(ids, n)
+            spec, _, st = sd.generate(ids, n)
+            same = plain == spec
+            first = next((i for i, (a, b) in enumerate(zip(plain, spec))
+                          if a != b), -1)
+            res[str(n)] = {"identical": same, "first_divergence": first,
+                           "acceptance": st["acceptance"]}
+            if not same:
+                out["verdict"] = "FAIL"
+            print(f"  [{name} n={n}] identical={same} "
+                  f"acc={st['acceptance']:.3f}", flush=True)
+        out["prompts"][name] = res
+    if receipt:
+        json.dump(out, open(receipt, "w"), indent=1)
+        print(f"receipt -> {receipt}")
+    return out
+
+
+def specbench(verifier, draft, tok, k=4, n=512, runs=3, receipt=None):
+    """[G2 frozen] plain-8B vs 8B+draft medians, 3 text types, same process."""
+    sd = SpecDecoder(verifier, draft, k=k)
+    out = {"bench": "specbench", "k": k, "n": n, "runs": runs, "types": {}}
+    for name, text in GATE_PROMPTS.items():
+        ids = tok(text, add_special_tokens=False).input_ids
+        plain_r, spec_r, accs = [], [], []
+        for r in range(runs):
+            t, dt = verifier.generate(ids, n)
+            plain_r.append(n / dt)
+            st_toks, sdt, st = sd.generate(ids, n)
+            spec_r.append(n / sdt)
+            accs.append(st["acceptance"])
+            print(f"  [{name} run{r}] plain {plain_r[-1]:.1f} tok/s | "
+                  f"spec {spec_r[-1]:.1f} tok/s | acc {accs[-1]:.3f} | "
+                  f"tok/round {st['tokens_per_round']}", flush=True)
+        med = lambda v: sorted(v)[len(v) // 2]
+        out["types"][name] = {
+            "plain_median_tok_s": round(med(plain_r), 2),
+            "spec_median_tok_s": round(med(spec_r), 2),
+            "speedup": round(med(spec_r) / med(plain_r), 3),
+            "acceptance_median": round(med(accs), 4),
+            "plain_runs": [round(v, 2) for v in plain_r],
+            "spec_runs": [round(v, 2) for v in spec_r],
+        }
+    out["peak_mem_gib"] = round(mx.get_peak_memory() / 2**30, 2)
+    if receipt:
+        json.dump(out, open(receipt, "w"), indent=1)
+        print(f"receipt -> {receipt}")
+    return out

mlx/fermion_mlx/trit_kernels.py

@@ -0,0 +1,1053 @@
+#!/usr/bin/env python3
+"""Five-value {0, +-s_lo, +-s_hi} 3-bit-planar GEMV as mx.fast.metal_kernel.
+
+Decode: per output row, three bit planes (bp=positive, bn=negative, br=high-mag),
+LSB-first. sign = p - n, magnitude selects per-row s_lo / s_hi. The kernel keeps
+two fp32 accumulators (lo/hi) so the per-row scales multiply once at the end —
+the inner loop is pure bit-extract + FMA (the Metal twin of the NEON tbl /
+CUDA PRMT decode; MSL has no byte shuffle, ALU decode is the standard move).
+
+Layout: one simdgroup per output row, SG_PER_TG simdgroups per threadgroup.
+Lanes stride uchar4 loads across the row's plane bytes; simd_sum reduction.
+
+Template flags (baked into per-shape kernel source, cached):
+  HAS_BIAS  : add fp32 bias[row]
+  FUSE_NORM : x is pre-norm; kernel computes rmsnorm(x)*g inline (g = extra input)
+  ADD_RESID : out[row] = resid[row] + y
+  GLU       : down-proj mode; x has 2*INTER entries [gate;up], col value is
+              silu(gate[c]) * up[c]  (fuses the SwiGLU elementwise pass into GEMV)
+"""
+import mlx.core as mx
+
+_HEADER = """
+static inline float trit_silu(float v) { return v / (1.0f + metal::exp(-v)); }
+"""
+
+_CACHE = {}
+
+
+def _norm_pre(cols, eps):
+    return f"""
+    float ssq = 0.0f;
+    for (uint c = lane; c < {cols}u; c += 32u) {{ float v = x[c]; ssq = metal::fma(v, v, ssq); }}
+    ssq = metal::simd_sum(ssq);
+    float rms = metal::rsqrt(ssq / {float(cols)}f + {eps:.9g}f);
+"""
+
+
+def _gemv_source(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps):
+    """v1: per-bit scalar decode with sparsity branches."""
+    assert rs % 4 == 0, "row_stride must be multiple of 4 for uchar4 loads"
+    tail = rs * 8 != cols
+    # x effective value macro
+    if glu:
+        xv = "trit_silu(x[c]) * x[c + %d]" % cols
+        norm_pre = ""
+    elif fuse_norm:
+        xv = "x[c] * nw[c] * rms"
+        norm_pre = _norm_pre(cols, eps)
+    else:
+        xv = "x[c]"
+        norm_pre = ""
+    guard = f"if (c >= {cols}u) break;" if tail else ""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;
+    if (row >= {rows}u) return;
+{norm_pre}
+    const device uchar4* p4 = (const device uchar4*)bp + row * {rs // 4}u;
+    const device uchar4* n4 = (const device uchar4*)bn + row * {rs // 4}u;
+    const device uchar4* h4 = (const device uchar4*)br + row * {rs // 4}u;
+    float accLo = 0.0f, accHi = 0.0f;
+    for (uint i = lane; i < {rs // 4}u; i += 32u) {{
+        uchar4 pb = p4[i], nb = n4[i], hb = h4[i];
+        uint cb = i * 32u;
+        for (uint k = 0u; k < 4u; ++k) {{
+            uint pw = pb[k], nw2 = nb[k], hw = hb[k];
+            if ((pw | nw2) == 0u) continue;
+            for (uint j = 0u; j < 8u; ++j) {{
+                uint c = cb + k * 8u + j;
+                {guard}
+                float s = (float)((pw >> j) & 1u) - (float)((nw2 >> j) & 1u);
+                if (s == 0.0f) continue;
+                float v = s * ({xv});
+                if ((hw >> j) & 1u) accHi += v; else accLo += v;
+            }}
+        }}
+    }}
+    accLo = metal::simd_sum(accLo);
+    accHi = metal::simd_sum(accHi);
+    if (lane == 0u) {{
+        float y = metal::fma(slo[row], accLo, shi[row] * accHi);
+        {"y += bias[row];" if has_bias else ""}
+        {"y += resid[row];" if add_resid else ""}
+        out[row] = y;
+    }}
+"""
+
+
+def _gemv_source_v2(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps):
+    """v2: branchless decode. Planes loaded as uint32 (32 weights per load),
+    per-4-bit float4 select against float4 x loads. Requires cols % 32 == 0
+    and rs % 4 == 0 with rs*8 == cols (true for all Qwen shapes)."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0
+    if glu:
+        xload = f"""float4 g = xg4[w * 8u + k], u = xu4[w * 8u + k];
+            float4 xv = g / (1.0f + metal::exp(-g)) * u;"""
+        norm_pre = ""
+        xpre = f"""
+    const device float4* xg4 = (const device float4*)x;
+    const device float4* xu4 = (const device float4*)(x + {cols}u);"""
+    elif fuse_norm:
+        xload = """float4 xv = x4[w * 8u + k] * nw4[w * 8u + k] * rms;"""
+        norm_pre = _norm_pre(cols, eps)
+        xpre = """
+    const device float4* x4 = (const device float4*)x;
+    const device float4* nw4 = (const device float4*)nw;"""
+    else:
+        xload = """float4 xv = x4[w * 8u + k];"""
+        norm_pre = ""
+        xpre = """
+    const device float4* x4 = (const device float4*)x;"""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;
+    if (row >= {rows}u) return;
+{norm_pre}{xpre}
+    const device uint* p32 = (const device uint*)bp + row * {rs // 4}u;
+    const device uint* n32 = (const device uint*)bn + row * {rs // 4}u;
+    const device uint* h32 = (const device uint*)br + row * {rs // 4}u;
+    float4 accLo4 = 0.0f, accHi4 = 0.0f;
+    for (uint w = lane; w < {rs // 4}u; w += 32u) {{
+        uint pw = p32[w], nw2 = n32[w], hw = h32[w];
+        for (uint k = 0u; k < 8u; ++k) {{
+            {xload}
+            uint sh = k * 4u;
+            float4 s = float4(float((pw >> sh) & 1u),      float((pw >> (sh+1u)) & 1u),
+                              float((pw >> (sh+2u)) & 1u), float((pw >> (sh+3u)) & 1u))
+                     - float4(float((nw2 >> sh) & 1u),      float((nw2 >> (sh+1u)) & 1u),
+                              float((nw2 >> (sh+2u)) & 1u), float((nw2 >> (sh+3u)) & 1u));
+            float4 v = s * xv;
+            bool4 hi = bool4((hw >> sh) & 1u, (hw >> (sh+1u)) & 1u,
+                             (hw >> (sh+2u)) & 1u, (hw >> (sh+3u)) & 1u);
+            accHi4 += metal::select(float4(0.0f), v, hi);
+            accLo4 += metal::select(v, float4(0.0f), hi);
+        }}
+    }}
+    float accLo = metal::simd_sum(accLo4.x + accLo4.y + accLo4.z + accLo4.w);
+    float accHi = metal::simd_sum(accHi4.x + accHi4.y + accHi4.z + accHi4.w);
+    if (lane == 0u) {{
+        float y = metal::fma(slo[row], accLo, shi[row] * accHi);
+        {"y += bias[row];" if has_bias else ""}
+        {"y += resid[row];" if add_resid else ""}
+        out[row] = y;
+    }}
+"""
+
+
+def _s8_source(rows, cols, rs, sg_per_tg, fuse_norm, eps):
+    assert rs % 4 == 0
+    if fuse_norm:
+        xv = lambda c: f"x[{c}] * nw[{c}] * rms"
+        norm_pre = f"""
+    float ssq = 0.0f;
+    for (uint c = lane; c < {cols}u; c += 32u) {{ float v = x[c]; ssq = metal::fma(v, v, ssq); }}
+    ssq = metal::simd_sum(ssq);
+    float rms = metal::rsqrt(ssq / {float(cols)}f + {eps:.9g}f);
+"""
+    else:
+        xv = lambda c: f"x[{c}]"
+        norm_pre = ""
+    assert rs * 8 >= cols and rs >= cols, "int8 record: expect row_stride >= cols"
+    nvec = cols // 4
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;
+    if (row >= {rows}u) return;
+{norm_pre}
+    const device char* w = (const device char*)W + (ulong)row * {rs}u;
+    float acc = 0.0f;
+    for (uint i = lane * 4u; i + 3u < {cols}u; i += 128u) {{
+        char4 wv = *(const device char4*)(w + i);
+        uint c = i;
+        acc = metal::fma((float)wv.x, {xv('c')}, acc);
+        acc = metal::fma((float)wv.y, {xv('c + 1u')}, acc);
+        acc = metal::fma((float)wv.z, {xv('c + 2u')}, acc);
+        acc = metal::fma((float)wv.w, {xv('c + 3u')}, acc);
+    }}
+    acc = metal::simd_sum(acc);
+    if (lane == 0u) out[row] = scale[row] * acc;
+""" if nvec * 4 == cols else None
+
+
+SG_PER_TG = int(__import__("os").environ.get("TRIT_METAL_SGPTG", "8"))
+
+
+import os
+KERNEL_VERSION = int(os.environ.get("TRIT_METAL_V", "1"))
+RPSG = int(os.environ.get("TRIT_METAL_RPSG", "8"))
+
+
+def _gemv_source_v3(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps,
+                    rpsg=RPSG):
+    """v3: rpsg rows per simdgroup; x (and silu/norm work) loaded once per
+    column window and reused across rows in registers — kills the per-row
+    x-reload that bound v1/v2 at ~20 GB/s. 4-wide horizontal accumulate."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % rpsg == 0
+    if glu:
+        xload = f"""float4 g = xg4[w * 8u + k], u = xu4[w * 8u + k];
+            float4 xv = g / (1.0f + metal::exp(-g)) * u;"""
+        norm_pre = ""
+        xpre = f"""
+    const device float4* xg4 = (const device float4*)x;
+    const device float4* xu4 = (const device float4*)(x + {cols}u);"""
+    elif fuse_norm:
+        xload = "float4 xv = x4[w * 8u + k] * nw4[w * 8u + k] * rms;"
+        norm_pre = _norm_pre(cols, eps)
+        xpre = """
+    const device float4* x4 = (const device float4*)x;
+    const device float4* nw4 = (const device float4*)nw;"""
+    else:
+        xload = "float4 xv = x4[w * 8u + k];"
+        norm_pre = ""
+        xpre = """
+    const device float4* x4 = (const device float4*)x;"""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row0 = (threadgroup_position_in_grid.x * {sg_per_tg}u + sg) * {rpsg}u;
+    if (row0 >= {rows}u) return;
+{norm_pre}{xpre}
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    float accLo[{rpsg}], accHi[{rpsg}];
+    for (uint r = 0u; r < {rpsg}u; ++r) {{ accLo[r] = 0.0f; accHi[r] = 0.0f; }}
+    const float4 one4 = float4(1.0f);
+    for (uint w = lane; w < {rs // 4}u; w += 32u) {{
+        uint pw[{rpsg}], nw2[{rpsg}], hw[{rpsg}];
+        for (uint r = 0u; r < {rpsg}u; ++r) {{
+            ulong off = (ulong)(row0 + r) * {rs // 4}u + w;
+            pw[r] = p32[off]; nw2[r] = n32[off]; hw[r] = h32[off];
+        }}
+        for (uint k = 0u; k < 8u; ++k) {{
+            {xload}
+            uint sh = k * 4u;
+            for (uint r = 0u; r < {rpsg}u; ++r) {{
+                float4 s = float4(float((pw[r] >> sh) & 1u),      float((pw[r] >> (sh+1u)) & 1u),
+                                  float((pw[r] >> (sh+2u)) & 1u), float((pw[r] >> (sh+3u)) & 1u))
+                         - float4(float((nw2[r] >> sh) & 1u),      float((nw2[r] >> (sh+1u)) & 1u),
+                                  float((nw2[r] >> (sh+2u)) & 1u), float((nw2[r] >> (sh+3u)) & 1u));
+                float4 v = s * xv;
+                bool4 hi = bool4((hw[r] >> sh) & 1u, (hw[r] >> (sh+1u)) & 1u,
+                                 (hw[r] >> (sh+2u)) & 1u, (hw[r] >> (sh+3u)) & 1u);
+                accHi[r] += metal::dot(metal::select(float4(0.0f), v, hi), one4);
+                accLo[r] += metal::dot(metal::select(v, float4(0.0f), hi), one4);
+            }}
+        }}
+    }}
+    for (uint r = 0u; r < {rpsg}u; ++r) {{
+        float lo = metal::simd_sum(accLo[r]);
+        float hi = metal::simd_sum(accHi[r]);
+        if (lane == 0u) {{
+            uint row = row0 + r;
+            float y = metal::fma(slo[row], lo, shi[row] * hi);
+            {"y += bias[row];" if has_bias else ""}
+            {"y += resid[row];" if add_resid else ""}
+            out[row] = y;
+        }}
+    }}
+"""
+
+
+def _gemv_source_v4(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps,
+                    rpsg=RPSG):
+    """v4: threadgroup-memory LUT decode (Metal twin of NEON vqtbl1q).
+    Per 4-column group g, lut[g][m] = sum of xv[4g+i] over set bits of m
+    (16 subset sums). Split planes on the fly into lo/hi pos/neg nibbles
+    (a=p&~h, b=n&~h, c=p&h, d=n&h): 4 weights cost 4 LUT loads + 4 adds.
+    LUT stride 17 floats kills the 16-float bank-conflict pattern. Tiled over
+    columns when the LUT would exceed threadgroup memory (down proj)."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % rpsg == 0
+    # column tiling: LUT floats = tile/4*17, xbuf floats = tile -> keep <= ~26KB
+    ntiles = 1
+    while (cols // ntiles) % 32 != 0 or (cols // ntiles) * (17 / 4 + 1) * 4 > 26624:
+        ntiles += 1
+        assert ntiles <= 16
+    tile = cols // ntiles
+    gpt = tile // 4          # groups per tile
+    w0 = tile // 32          # 32-weight words per tile (per row)
+    nthreads = sg_per_tg * 32
+    if glu:
+        xv_expr = "{ float gg = x[c]; xb[cl] = gg / (1.0f + metal::exp(-gg)) * x[c + %du]; }" % cols
+    elif fuse_norm:
+        xv_expr = "xb[cl] = x[c] * nw[c] * rms;"
+    else:
+        xv_expr = "xb[cl] = x[c];"
+    if fuse_norm:
+        norm_pre = f"""
+    threadgroup float ssq_sh[{sg_per_tg}];
+    {{
+        float ssq = 0.0f;
+        for (uint c = tid; c < {cols}u; c += {nthreads}u) {{ float v = x[c]; ssq = metal::fma(v, v, ssq); }}
+        ssq = metal::simd_sum(ssq);
+        if (lane == 0u) ssq_sh[sg] = ssq;
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        float t = 0.0f;
+        for (uint i = 0u; i < {sg_per_tg}u; ++i) t += ssq_sh[i];
+        rms = metal::rsqrt(t / {float(cols)}f + {eps:.9g}f);
+    }}
+"""
+    else:
+        norm_pre = ""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row0 = (threadgroup_position_in_grid.x * {sg_per_tg}u + sg) * {rpsg}u;
+    float rms = 1.0f;
+{norm_pre}
+    threadgroup float xb[{tile}];
+    threadgroup float lut[{gpt} * 17];
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    float accLo[{rpsg}], accHi[{rpsg}];
+    for (uint r = 0u; r < {rpsg}u; ++r) {{ accLo[r] = 0.0f; accHi[r] = 0.0f; }}
+    for (uint t = 0u; t < {ntiles}u; ++t) {{
+        // stage effective x for this tile
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        for (uint cl = tid; cl < {tile}u; cl += {nthreads}u) {{
+            uint c = t * {tile}u + cl;
+            {xv_expr}
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        // build 16 subset sums per 4-col group
+        for (uint e = tid; e < {gpt}u * 16u; e += {nthreads}u) {{
+            uint g = e >> 4u, m = e & 15u;
+            const threadgroup float* xg = xb + g * 4u;
+            float v = 0.0f;
+            if (m & 1u) v += xg[0];
+            if (m & 2u) v += xg[1];
+            if (m & 4u) v += xg[2];
+            if (m & 8u) v += xg[3];
+            lut[g * 17u + m] = v;
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        if (row0 < {rows}u) {{
+            for (uint wl = lane; wl < {w0}u; wl += 32u) {{
+                uint w = t * {w0}u + wl;
+                for (uint r = 0u; r < {rpsg}u; ++r) {{
+                    ulong off = (ulong)(row0 + r) * {rs // 4}u + w;
+                    uint pw = p32[off], nw2 = n32[off], hw = h32[off];
+                    uint a = pw & ~hw, b = nw2 & ~hw, cc = pw & hw, d = nw2 & hw;
+                    uint gbase = wl * 8u;
+                    float lo = 0.0f, hi = 0.0f;
+                    for (uint k = 0u; k < 8u; ++k) {{
+                        const threadgroup float* lg = lut + (gbase + k) * 17u;
+                        uint sh = k * 4u;
+                        lo += lg[(a >> sh) & 15u] - lg[(b >> sh) & 15u];
+                        hi += lg[(cc >> sh) & 15u] - lg[(d >> sh) & 15u];
+                    }}
+                    accLo[r] += lo; accHi[r] += hi;
+                }}
+            }}
+        }}
+    }}
+    if (row0 >= {rows}u) return;
+    for (uint r = 0u; r < {rpsg}u; ++r) {{
+        float lo = metal::simd_sum(accLo[r]);
+        float hi = metal::simd_sum(accHi[r]);
+        if (lane == 0u) {{
+            uint row = row0 + r;
+            float y = metal::fma(slo[row], lo, shi[row] * hi);
+            {"y += bias[row];" if has_bias else ""}
+            {"y += resid[row];" if add_resid else ""}
+            out[row] = y;
+        }}
+    }}
+"""
+
+
+import os as _os
+_TILE_MAX = int(_os.environ.get("TRIT_METAL_TILE", "448"))
+
+
+def _v5_tile(cols):
+    """largest tile <= TILE_MAX with tile % 32 == 0 and cols % tile == 0."""
+    for t in range(_TILE_MAX, 31, -32):
+        if cols % t == 0 and t % 32 == 0:
+            return t
+    raise ValueError(cols)
+
+
+def _gemv_source_v5(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps,
+                    rpsg=8):
+    """v5 = v4 LUT decode with the two occupancy/bandwidth fixes:
+    (1) planes pre-interleaved on load: uint32 words stored [row_block, word,
+        row_in_block] so a lane's 8-row load is 32 contiguous bytes (streams
+        at DRAM bandwidth; the v3/v4 scattered pattern ran at 59% of it);
+    (2) small LUT tiles (<= ~7.6KB threadgroup memory) so several threadgroups
+        fit per GPU core (v4's 19-26KB allowed only one, exposing latency).
+    Requires planes packed with pack_planes_v5. rpsg fixed at 8 by layout."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % 8 == 0
+    tile = _v5_tile(cols)
+    ntiles = cols // tile
+    gpt = tile // 4
+    w0 = tile // 32
+    W = rs // 4
+    nthreads = sg_per_tg * 32
+    if glu:
+        stage = f"""
+        for (uint cl = tid; cl < {tile}u; cl += {nthreads}u) {{
+            uint c = t * {tile}u + cl;
+            float gg = x[c];
+            xb[cl] = gg / (1.0f + metal::exp(-gg)) * x[c + {cols}u];
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);"""
+        xval = "xb[gl * 4u + i]"
+        xb_decl = f"threadgroup float xb[{tile}];"
+    elif fuse_norm:
+        stage = ""
+        xval = "x[t * %du + gl * 4u + i] * nw[t * %du + gl * 4u + i] * rms" % (tile, tile)
+        xb_decl = ""
+    else:
+        stage = ""
+        xval = "x[t * %du + gl * 4u + i]" % tile
+        xb_decl = ""
+    if fuse_norm:
+        norm_pre = f"""
+    threadgroup float ssq_sh[{sg_per_tg}];
+    {{
+        float ssq = 0.0f;
+        for (uint c = tid; c < {cols}u; c += {nthreads}u) {{ float v = x[c]; ssq = metal::fma(v, v, ssq); }}
+        ssq = metal::simd_sum(ssq);
+        if (lane == 0u) ssq_sh[sg] = ssq;
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        float tt = 0.0f;
+        for (uint i = 0u; i < {sg_per_tg}u; ++i) tt += ssq_sh[i];
+        rms = metal::rsqrt(tt / {float(cols)}f + {eps:.9g}f);
+    }}
+"""
+    else:
+        norm_pre = ""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint blk  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;   // 8-row block
+    uint row0 = blk * 8u;
+    float rms = 1.0f;
+{norm_pre}
+    {xb_decl}
+    threadgroup float lut[{gpt} * 17];
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    float accLo[8], accHi[8];
+    for (uint r = 0u; r < 8u; ++r) {{ accLo[r] = 0.0f; accHi[r] = 0.0f; }}
+    for (uint t = 0u; t < {ntiles}u; ++t) {{
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+{stage}
+        for (uint e = tid; e < {gpt}u * 16u; e += {nthreads}u) {{
+            uint gl = e >> 4u, m = e & 15u;
+            float v = 0.0f;
+            for (uint i = 0u; i < 4u; ++i)
+                if ((m >> i) & 1u) v += {xval};
+            lut[gl * 17u + m] = v;
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        if (row0 < {rows}u) {{
+            for (uint wl = lane; wl < {w0}u; wl += 32u) {{
+                uint w = t * {w0}u + wl;
+                ulong base = ((ulong)blk * {W}u + w) * 8u;   // 8 rows contiguous
+                uint gbase = wl * 8u;
+                for (uint r = 0u; r < 8u; ++r) {{
+                    uint pw = p32[base + r], nw2 = n32[base + r], hw = h32[base + r];
+                    uint a = pw & ~hw, b = nw2 & ~hw, cc = pw & hw, d = nw2 & hw;
+                    float lo = 0.0f, hi = 0.0f;
+                    for (uint k = 0u; k < 8u; ++k) {{
+                        const threadgroup float* lg = lut + (gbase + k) * 17u;
+                        uint sh = k * 4u;
+                        lo += lg[(a >> sh) & 15u] - lg[(b >> sh) & 15u];
+                        hi += lg[(cc >> sh) & 15u] - lg[(d >> sh) & 15u];
+                    }}
+                    accLo[r] += lo; accHi[r] += hi;
+                }}
+            }}
+        }}
+    }}
+    if (row0 >= {rows}u) return;
+    for (uint r = 0u; r < 8u; ++r) {{
+        float lo = metal::simd_sum(accLo[r]);
+        float hi = metal::simd_sum(accHi[r]);
+        if (lane == 0u) {{
+            uint row = row0 + r;
+            float y = metal::fma(slo[row], lo, shi[row] * hi);
+            {"y += bias[row];" if has_bias else ""}
+            {"y += resid[row];" if add_resid else ""}
+            out[row] = y;
+        }}
+    }}
+"""
+
+
+def _gemv_source_v6(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps):
+    """v6: interleaved 8-row plane layout (pack_planes_v5) + mask-convert-fma
+    decode. For bit j of word a: (float)(a & (1<<j)) == 2^j when set, so
+    multiplying by x pre-scaled with 2^-j turns decode into AND + convert +
+    FMA (no shifts) — 4 masks (lo/hi x pos/neg) ~3.5 instr/weight, exact in
+    fp32 (power-of-two scales). x reused across the 8 rows in registers."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % 8 == 0
+    W = rs // 4
+    if glu:
+        xload = f"""float4 g = xg4[w * 8u + k], u = xu4[w * 8u + k];
+            float4 xv = g / (1.0f + metal::exp(-g)) * u;"""
+        norm_pre = ""
+        xpre = f"""
+    const device float4* xg4 = (const device float4*)x;
+    const device float4* xu4 = (const device float4*)(x + {cols}u);"""
+    elif fuse_norm:
+        xload = "float4 xv = x4[w * 8u + k] * nw4[w * 8u + k] * rms;"
+        norm_pre = _norm_pre(cols, eps)
+        xpre = """
+    const device float4* x4 = (const device float4*)x;
+    const device float4* nw4 = (const device float4*)nw;"""
+    else:
+        xload = "float4 xv = x4[w * 8u + k];"
+        norm_pre = ""
+        xpre = """
+    const device float4* x4 = (const device float4*)x;"""
+    # unrolled k-body with literal masks / prescales
+    kbody = []
+    for k in range(8):
+        m = [1 << (4 * k + i) for i in range(4)]
+        ps = ", ".join("%.9ef" % (2.0 ** -(4 * k + i)) for i in range(4))
+        kbody.append(f"""        {{
+            uint k = {k}u; {xload}
+            float4 xs = xv * float4({ps});
+            const uint4 m4 = uint4({m[0]}u, {m[1]}u, {m[2]}u, {m[3]}u);
+            for (uint r = 0u; r < 8u; ++r) {{
+                uint pw = pl[r], nw2 = nl[r], hw = hl[r];
+                uint a = pw & ~hw, b = nw2 & ~hw, cc = pw & hw, d = nw2 & hw;
+                accLo[r] += metal::dot(float4(uint4(a) & m4) - float4(uint4(b) & m4), xs);
+                accHi[r] += metal::dot(float4(uint4(cc) & m4) - float4(uint4(d) & m4), xs);
+            }}
+        }}""")
+    kbody = "\n".join(kbody)
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint blk  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;
+    uint row0 = blk * 8u;
+    if (row0 >= {rows}u) return;
+{norm_pre}{xpre}
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    float accLo[8], accHi[8];
+    for (uint r = 0u; r < 8u; ++r) {{ accLo[r] = 0.0f; accHi[r] = 0.0f; }}
+    for (uint w = lane; w < {W}u; w += 32u) {{
+        ulong base = ((ulong)blk * {W}u + w) * 8u;
+        uint pl[8], nl[8], hl[8];
+        for (uint r = 0u; r < 8u; ++r) {{ pl[r] = p32[base+r]; nl[r] = n32[base+r]; hl[r] = h32[base+r]; }}
+{kbody}
+    }}
+    for (uint r = 0u; r < 8u; ++r) {{
+        float lo = metal::simd_sum(accLo[r]);
+        float hi = metal::simd_sum(accHi[r]);
+        if (lane == 0u) {{
+            uint row = row0 + r;
+            float y = metal::fma(slo[row], lo, shi[row] * hi);
+            {"y += bias[row];" if has_bias else ""}
+            {"y += resid[row];" if add_resid else ""}
+            out[row] = y;
+        }}
+    }}
+"""
+
+
+def _gemv_source_v7(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid, glu, eps):
+    """v7: v5 interleaved layout + LUT decode with full lane utilization.
+    Lane = (row r = lane&7, word-slot = lane>>3): each lane accumulates ONE
+    row over words wslot, wslot+4, ... — all 32 lanes busy for any w0 >= 4.
+    Row sums gathered with two simd_shuffle_down folds. LUT tile 448 cols
+    (7.6KB threadgroup mem) so multiple threadgroups stay resident per core."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % 8 == 0
+    tile = _v5_tile(cols)
+    ntiles = cols // tile
+    gpt = tile // 4
+    w0 = tile // 32
+    W = rs // 4
+    nthreads = sg_per_tg * 32
+    if glu:
+        stage = f"""
+        for (uint cl = tid; cl < {tile}u; cl += {nthreads}u) {{
+            uint c = t * {tile}u + cl;
+            float gg = x[c];
+            xb[cl] = gg / (1.0f + metal::exp(-gg)) * x[c + {cols}u];
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);"""
+        xval = "xb[gl * 4u + i]"
+        xb_decl = f"threadgroup float xb[{tile}];"
+    elif fuse_norm:
+        stage = ""
+        xval = "x[t * %du + gl * 4u + i] * nw[t * %du + gl * 4u + i] * rms" % (tile, tile)
+        xb_decl = ""
+    else:
+        stage = ""
+        xval = "x[t * %du + gl * 4u + i]" % tile
+        xb_decl = ""
+    if fuse_norm:
+        norm_pre = f"""
+    threadgroup float ssq_sh[{sg_per_tg}];
+    {{
+        float ssq = 0.0f;
+        for (uint c = tid; c < {cols}u; c += {nthreads}u) {{ float v = x[c]; ssq = metal::fma(v, v, ssq); }}
+        ssq = metal::simd_sum(ssq);
+        if (lane == 0u) ssq_sh[sg] = ssq;
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        float tt = 0.0f;
+        for (uint i = 0u; i < {sg_per_tg}u; ++i) tt += ssq_sh[i];
+        rms = metal::rsqrt(tt / {float(cols)}f + {eps:.9g}f);
+    }}
+"""
+    else:
+        norm_pre = ""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint blk  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;
+    uint row0 = blk * 8u;
+    uint r    = lane & 7u;
+    uint wsl  = lane >> 3u;
+    float rms = 1.0f;
+{norm_pre}
+    {xb_decl}
+    threadgroup float lut[{gpt} * 17];
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    float accLo = 0.0f, accHi = 0.0f;
+    for (uint t = 0u; t < {ntiles}u; ++t) {{
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+{stage}
+        for (uint e = tid; e < {gpt}u * 16u; e += {nthreads}u) {{
+            uint gl = e >> 4u, m = e & 15u;
+            float v = 0.0f;
+            for (uint i = 0u; i < 4u; ++i)
+                if ((m >> i) & 1u) v += {xval};
+            lut[gl * 17u + m] = v;
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        if (row0 < {rows}u) {{
+            for (uint wl = wsl; wl < {w0}u; wl += 4u) {{
+                ulong base = ((ulong)blk * {W}u + t * {w0}u + wl) * 8u + r;
+                uint pw = p32[base], nw2 = n32[base], hw = h32[base];
+                uint a = pw & ~hw, b = nw2 & ~hw, cc = pw & hw, d = nw2 & hw;
+                uint gbase = wl * 8u;
+                for (uint k = 0u; k < 8u; ++k) {{
+                    const threadgroup float* lg = lut + (gbase + k) * 17u;
+                    uint sh = k * 4u;
+                    accLo += lg[(a >> sh) & 15u] - lg[(b >> sh) & 15u];
+                    accHi += lg[(cc >> sh) & 15u] - lg[(d >> sh) & 15u];
+                }}
+            }}
+        }}
+    }}
+    if (row0 >= {rows}u) return;
+    accLo += metal::simd_shuffle_down(accLo, 16u);
+    accLo += metal::simd_shuffle_down(accLo, 8u);
+    accHi += metal::simd_shuffle_down(accHi, 16u);
+    accHi += metal::simd_shuffle_down(accHi, 8u);
+    if (lane < 8u) {{
+        uint row = row0 + lane;
+        float y = metal::fma(slo[row], accLo, shi[row] * accHi);
+        {"y += bias[row];" if has_bias else ""}
+        {"y += resid[row];" if add_resid else ""}
+        out[row] = y;
+    }}
+"""
+
+
+def _gemv_source_v8(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid,
+                    glu, eps):
+    """v8: v7 LUT decode + DOUBLE-BUFFERED LUT — build tile t+1's LUT into
+    the alternate threadgroup buffer, then decode tile t: one barrier per
+    tile (plain/norm; two for glu) instead of v7's two/three. Entry build
+    order identical to v7 -> outputs BIT-IDENTICAL (gated 2026-07-28)."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % 8 == 0
+    tile = _v5_tile(cols)
+    ntiles = cols // tile
+    gpt = tile // 4
+    w0 = tile // 32
+    W = rs // 4
+    nthreads = sg_per_tg * 32
+    if glu:
+        xval = "xb[bb * %du + gl * 4u + i]" % tile
+        xb_decl = f"threadgroup float xb[2 * {tile}];"
+        stage = f"""
+            for (uint cl = tid; cl < {tile}u; cl += {nthreads}u) {{
+                uint c = tt * {tile}u + cl;
+                float gg = x[c];
+                xb[bb * {tile}u + cl] = gg / (1.0f + metal::exp(-gg)) * x[c + {cols}u];
+            }}
+            threadgroup_barrier(metal::mem_flags::mem_threadgroup);"""
+    elif fuse_norm:
+        xval = "x[tt * %du + gl * 4u + i] * nw[tt * %du + gl * 4u + i] * rms" % (tile, tile)
+        xb_decl = ""
+        stage = ""
+    else:
+        xval = "x[tt * %du + gl * 4u + i]" % tile
+        xb_decl = ""
+        stage = ""
+    build = f"""{stage}
+            for (uint e = tid; e < {gpt}u * 16u; e += {nthreads}u) {{
+                uint gl = e >> 4u, m = e & 15u;
+                float v = 0.0f;
+                for (uint i = 0u; i < 4u; ++i)
+                    if ((m >> i) & 1u) v += {xval};
+                lut[bb * {gpt}u * 17u + gl * 17u + m] = v;
+            }}"""
+    return _v89_frame(rows, cols, rs, sg_per_tg, has_bias, fuse_norm,
+                      add_resid, eps, tile, ntiles, gpt, w0, W, xb_decl, build)
+
+
+def _gemv_source_v9(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid,
+                    glu, eps):
+    """v9: double-buffered LUT + thread-per-GROUP incremental build. Each
+    builder thread computes its group's 4 effective x values ONCE in
+    registers (silu/norm included — no xb stage) and writes the 16 subset
+    sums by ascending-bit doubling; the norm path applies rms via explicit
+    fma to match v7's contraction. ONE barrier per tile for every flag
+    combo. BIT-IDENTICAL to v7 (gated: TF argmax 9/9, 128-tok greedy
+    identical)."""
+    assert rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % 8 == 0
+    tile = _v5_tile(cols)
+    ntiles = cols // tile
+    gpt = tile // 4
+    w0 = tile // 32
+    W = rs // 4
+    nthreads = sg_per_tg * 32
+    if glu:
+        xv = f"""float gg = x[c + i];
+                    xv[i] = gg / (1.0f + metal::exp(-gg)) * x[c + i + {cols}u];"""
+    elif fuse_norm:
+        xv = "xv[i] = x[c + i] * nw[c + i];"
+    else:
+        xv = "xv[i] = x[c + i];"
+    if fuse_norm and not glu:
+        sums = """lg[0] = 0.0f;
+                lg[1] = metal::fma(xv[0], rms, 0.0f);
+                lg[2] = metal::fma(xv[1], rms, 0.0f);
+                lg[3] = metal::fma(xv[1], rms, lg[1]);
+                for (uint m = 0u; m < 4u; ++m) lg[4u + m] = metal::fma(xv[2], rms, lg[m]);
+                for (uint m = 0u; m < 8u; ++m) lg[8u + m] = metal::fma(xv[3], rms, lg[m]);"""
+    else:
+        sums = """lg[0] = 0.0f;
+                lg[1] = xv[0];
+                lg[2] = xv[1];
+                lg[3] = xv[0] + xv[1];
+                for (uint m = 0u; m < 4u; ++m) lg[4u + m] = lg[m] + xv[2];
+                for (uint m = 0u; m < 8u; ++m) lg[8u + m] = lg[m] + xv[3];"""
+    build = f"""
+            for (uint gl = tid; gl < {gpt}u; gl += {nthreads}u) {{
+                uint c = tt * {tile}u + gl * 4u;
+                float xv[4];
+                for (uint i = 0u; i < 4u; ++i) {{
+                    {xv}
+                }}
+                threadgroup float* lg = lut + bb * {gpt}u * 17u + gl * 17u;
+                {sums}
+            }}"""
+    return _v89_frame(rows, cols, rs, sg_per_tg, has_bias, fuse_norm,
+                      add_resid, eps, tile, ntiles, gpt, w0, W, "", build)
+
+
+def _v89_frame(rows, cols, rs, sg_per_tg, has_bias, fuse_norm, add_resid,
+               eps, tile, ntiles, gpt, w0, W, xb_decl, build):
+    """shared v8/v9 skeleton: v7's lane mapping + decode, double-buffered
+    LUT loop (prologue build, then build-next/decode-current/one-barrier)."""
+    nthreads = sg_per_tg * 32
+    if fuse_norm:
+        norm_pre = f"""
+    threadgroup float ssq_sh[{sg_per_tg}];
+    {{
+        float ssq = 0.0f;
+        for (uint c = tid; c < {cols}u; c += {nthreads}u) {{ float v = x[c]; ssq = metal::fma(v, v, ssq); }}
+        ssq = metal::simd_sum(ssq);
+        if (lane == 0u) ssq_sh[sg] = ssq;
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+        float tt = 0.0f;
+        for (uint i = 0u; i < {sg_per_tg}u; ++i) tt += ssq_sh[i];
+        rms = metal::rsqrt(tt / {float(cols)}f + {eps:.9g}f);
+    }}
+"""
+    else:
+        norm_pre = ""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint blk  = threadgroup_position_in_grid.x * {sg_per_tg}u + sg;
+    uint row0 = blk * 8u;
+    uint r    = lane & 7u;
+    uint wsl  = lane >> 3u;
+    float rms = 1.0f;
+{norm_pre}
+    {xb_decl}
+    threadgroup float lut[2 * {gpt} * 17];
+    const device uint* p32 = (const device uint*)bp;
+    const device uint* n32 = (const device uint*)bn;
+    const device uint* h32 = (const device uint*)br;
+    float accLo = 0.0f, accHi = 0.0f;
+    {{
+        uint tt = 0u, bb = 0u;
+{build}
+    }}
+    threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+    for (uint t = 0u; t < {ntiles}u; ++t) {{
+        if (t + 1u < {ntiles}u) {{
+            uint tt = t + 1u, bb = (t + 1u) & 1u;
+{build}
+        }}
+        {{
+            const threadgroup float* lutc = lut + (t & 1u) * {gpt}u * 17u;
+            if (row0 < {rows}u) {{
+                for (uint wl = wsl; wl < {w0}u; wl += 4u) {{
+                    ulong base = ((ulong)blk * {W}u + t * {w0}u + wl) * 8u + r;
+                    uint pw = p32[base], nw2 = n32[base], hw = h32[base];
+                    uint a = pw & ~hw, b = nw2 & ~hw, cc = pw & hw, d = nw2 & hw;
+                    uint gbase = wl * 8u;
+                    for (uint k = 0u; k < 8u; ++k) {{
+                        const threadgroup float* lg = lutc + (gbase + k) * 17u;
+                        uint sh = k * 4u;
+                        accLo += lg[(a >> sh) & 15u] - lg[(b >> sh) & 15u];
+                        accHi += lg[(cc >> sh) & 15u] - lg[(d >> sh) & 15u];
+                    }}
+                }}
+            }}
+        }}
+        threadgroup_barrier(metal::mem_flags::mem_threadgroup);
+    }}
+    if (row0 >= {rows}u) return;
+    accLo += metal::simd_shuffle_down(accLo, 16u);
+    accLo += metal::simd_shuffle_down(accLo, 8u);
+    accHi += metal::simd_shuffle_down(accHi, 16u);
+    accHi += metal::simd_shuffle_down(accHi, 8u);
+    if (lane < 8u) {{
+        uint row = row0 + lane;
+        float y = metal::fma(slo[row], accLo, shi[row] * accHi);
+        {"y += bias[row];" if has_bias else ""}
+        {"y += resid[row];" if add_resid else ""}
+        out[row] = y;
+    }}
+"""
+
+
+def prep_planes(planes, cols=None):
+    """Trim row padding (row_stride*8 > cols in real exports; pad bits are
+    zero) so rs*8 == cols, then apply the layout transform required by the
+    active kernel version. planes = (bp, bn, br) mx.uint8 [rows, rs]."""
+    if cols is not None and cols % 8 == 0 and planes[0].shape[1] > cols // 8:
+        planes = tuple(mx.contiguous(p[:, :cols // 8]) for p in planes)
+    if KERNEL_VERSION >= 5:  # v5/v6 interleaved layout
+        return tuple(pack_planes_v5(p) for p in planes)
+    return planes
+
+
+def pack_planes_v5(plane_mx):
+    """[rows, rs] uint8 -> v5 interleaved layout (same byte count):
+    uint32 words reordered to [row_block(8), word, row_in_block]."""
+    rows, rs = plane_mx.shape
+    assert rows % 8 == 0 and rs % 4 == 0
+    w = plane_mx.view(mx.uint32).reshape(rows // 8, 8, rs // 4)
+    return mx.contiguous(w.transpose(0, 2, 1)).view(mx.uint8).reshape(rows, rs)
+
+
+def _rows_per_sg(rows, cols, rs, version, glu):
+    if version == 3 and rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0 and rows % RPSG == 0:
+        return RPSG
+    return 1
+
+
+def get_trit_gemv(rows, cols, rs, has_bias=False, fuse_norm=False, add_resid=False,
+                  glu=False, eps=1e-6, version=None):
+    version = KERNEL_VERSION if version is None else version
+    if version >= 2 and not (rs % 4 == 0 and rs * 8 == cols and cols % 32 == 0):
+        version = 1  # v2+ layout preconditions not met, fall back
+    if version >= 3 and rows % (8 if version >= 5 else RPSG) != 0:
+        version = 2
+    key = ("trit", rows, cols, rs, has_bias, fuse_norm, add_resid, glu, round(eps, 12), version)
+    if key in _CACHE:
+        return _CACHE[key]
+    inputs = ["bp", "bn", "br", "slo", "shi", "x"]
+    if has_bias:
+        inputs.append("bias")
+    if fuse_norm and not glu:
+        inputs.append("nw")
+    if add_resid:
+        inputs.append("resid")
+    gen = {1: _gemv_source, 2: _gemv_source_v2, 3: _gemv_source_v3,
+           4: _gemv_source_v4, 5: _gemv_source_v5, 6: _gemv_source_v6,
+           7: _gemv_source_v7, 8: _gemv_source_v8, 9: _gemv_source_v9}[version]
+    src = gen(rows, cols, rs, SG_PER_TG, has_bias, fuse_norm, add_resid, glu, eps)
+    name = "tritgemv%d_r%d_c%d_b%d_n%d_a%d_g%d" % (version, rows, cols, has_bias, fuse_norm,
+                                                   add_resid, glu)
+    k = mx.fast.metal_kernel(name=name, input_names=inputs, output_names=["out"],
+                             source=src, header=_HEADER)
+    _CACHE[key] = (k, inputs, version)
+    return _CACHE[key]
+
+
+def _s8_source_v2(rows, cols, rs, sg_per_tg, fuse_norm, eps, rpsg=RPSG):
+    """v2 int8 GEMV: rpsg rows per simdgroup, float4 x reuse across rows."""
+    assert rs % 4 == 0 and cols % 4 == 0 and rows % rpsg == 0
+    if fuse_norm:
+        xload = "float4 xv = x4[i] * nw4[i] * rms;"
+        norm_pre = _norm_pre(cols, eps)
+        xpre = """
+    const device float4* x4 = (const device float4*)x;
+    const device float4* nw4 = (const device float4*)nw;"""
+    else:
+        xload = "float4 xv = x4[i];"
+        norm_pre = ""
+        xpre = """
+    const device float4* x4 = (const device float4*)x;"""
+    return f"""
+    uint tid  = thread_position_in_threadgroup.x;
+    uint lane = tid & 31u;
+    uint sg   = tid >> 5u;
+    uint row0 = (threadgroup_position_in_grid.x * {sg_per_tg}u + sg) * {rpsg}u;
+    if (row0 >= {rows}u) return;
+{norm_pre}{xpre}
+    float acc[{rpsg}];
+    for (uint r = 0u; r < {rpsg}u; ++r) acc[r] = 0.0f;
+    const float4 one4 = float4(1.0f);
+    for (uint i = lane; i < {cols // 4}u; i += 32u) {{
+        {xload}
+        for (uint r = 0u; r < {rpsg}u; ++r) {{
+            char4 wv = *(const device char4*)((const device char*)W
+                        + (ulong)(row0 + r) * {rs}u + i * 4u);
+            acc[r] += metal::dot(float4(wv.x, wv.y, wv.z, wv.w) * xv, one4);
+        }}
+    }}
+    for (uint r = 0u; r < {rpsg}u; ++r) {{
+        float a = metal::simd_sum(acc[r]);
+        if (lane == 0u) out[row0 + r] = scale[row0 + r] * a;
+    }}
+"""
+
+
+def get_s8_gemv(rows, cols, rs, fuse_norm=False, eps=1e-6, version=None):
+    version = KERNEL_VERSION if version is None else version
+    v = 2 if (version >= 2 and rs % 4 == 0 and cols % 4 == 0 and rows % RPSG == 0) else 1
+    key = ("s8", rows, cols, rs, fuse_norm, round(eps, 12), v)
+    if key in _CACHE:
+        return _CACHE[key]
+    inputs = ["W", "scale", "x"]
+    if fuse_norm:
+        inputs.append("nw")
+    src = (_s8_source_v2 if v == 2 else _s8_source)(rows, cols, rs, SG_PER_TG, fuse_norm, eps)
+    assert src is not None, "cols must be multiple of 4"
+    name = "s8gemv%d_r%d_c%d_n%d" % (v, rows, cols, fuse_norm)
+    k = mx.fast.metal_kernel(name=name, input_names=inputs, output_names=["out"],
+                             source=src, header=_HEADER)
+    _CACHE[key] = (k, inputs, v)
+    return _CACHE[key]
+
+
+def _grid_for(rows, rpsg=1):
+    nsg = (rows + rpsg - 1) // rpsg               # one simdgroup per rpsg rows
+    ntg = (nsg + SG_PER_TG - 1) // SG_PER_TG
+    return (ntg * SG_PER_TG * 32, 1, 1), (SG_PER_TG * 32, 1, 1)
+
+
+def trit_gemv(planes, slo, shi, x, bias=None, norm_w=None, resid=None, glu=False,
+              out_rows=None, eps=1e-6, stream=None):
+    """planes = (bp, bn, br) mx.uint8 [rows, rs]. x fp32. Returns fp32 [out_rows]."""
+    bp, bn, br = planes
+    rows, rs = bp.shape
+    out_rows = out_rows if out_rows is not None else rows
+    cols = x.shape[0] if not glu else x.shape[0] // 2
+    k, names, version = get_trit_gemv(rows, cols, rs, bias is not None, norm_w is not None,
+                                      resid is not None, glu, eps)
+    vals = {"bp": bp, "bn": bn, "br": br, "slo": slo, "shi": shi, "x": x,
+            "bias": bias, "nw": norm_w, "resid": resid}
+    grid, tg = _grid_for(out_rows, 8 if version >= 5 else (RPSG if version >= 3 else 1))
+    return k(inputs=[vals[n] for n in names], grid=grid, threadgroup=tg,
+             output_shapes=[(out_rows,)], output_dtypes=[mx.float32], stream=stream)[0]
+
+
+def s8_gemv(W, scale, x, norm_w=None, eps=1e-6, stream=None):
+    rows, rs = W.shape
+    cols = x.shape[0]
+    k, names, v = get_s8_gemv(rows, cols, rs, norm_w is not None, eps)
+    vals = {"W": W, "scale": scale, "x": x, "nw": norm_w}
+    grid, tg = _grid_for(rows, RPSG if v == 2 else 1)
+    return k(inputs=[vals[n] for n in names], grid=grid, threadgroup=tg,
+             output_shapes=[(rows,)], output_dtypes=[mx.float32], stream=stream)[0]
+
+
+# ---------------- fused rope + KV cache append ----------------
+
+def get_rope_append(n_heads, n_kv, hd, maxseq):
+    """One dispatch: rope q (n_heads*hd) and k (n_kv*hd) from the fused qkv
+    vector, write roped k and raw v in-place into the preallocated caches at
+    position pos (device scalar), output roped q. NeoX rotate-half, full hd.
+    kc/vc passed as inputs and written in place (stream-serial ordering with
+    the consumer sdpa; correctness enforced by the e2e gate)."""
+    key = ("rope_append", n_heads, n_kv, hd, maxseq)
+    if key in _CACHE:
+        return _CACHE[key]
+    qd, kd = n_heads * hd, n_kv * hd
+    h2 = hd // 2
+    src = f"""
+    uint i = thread_position_in_grid.x;              // one thread per q/k element
+    uint pos = (uint)posbuf[0];
+    device float* kc_w = (device float*)kc;
+    device float* vc_w = (device float*)vc;
+    if (i == 0u) {{ ((device float*)mask)[pos] = 0.0f; }}
+    if (i < {qd}u + {kd}u) {{
+        uint hidx = i / {hd}u, d = i % {hd}u;
+        float c = ct[pos * {h2}u + (d % {h2}u)];
+        float sn = st[pos * {h2}u + (d % {h2}u)];
+        float v = qkv[i];
+        float vrot = (d < {h2}u) ? -qkv[hidx * {hd}u + d + {h2}u]
+                                 :  qkv[hidx * {hd}u + d - {h2}u];
+        float r = metal::fma(v, c, vrot * sn);
+        if (i < {qd}u) {{
+            qout[i] = r;
+        }} else {{
+            uint kh = (i - {qd}u) / {hd}u;
+            kc_w[(ulong)(kh * {maxseq}u + pos) * {hd}u + d] = r;
+        }}
+    }} else if (i < {qd}u + 2u * {kd}u) {{
+        uint j = i - {qd}u - {kd}u;
+        uint vh = j / {hd}u, d = j % {hd}u;
+        vc_w[(ulong)(vh * {maxseq}u + pos) * {hd}u + d] = qkv[{qd}u + {kd}u + j];
+    }}
+"""
+    k = mx.fast.metal_kernel(name="rope_append_%d_%d_%d" % (n_heads, n_kv, hd),
+                             input_names=["qkv", "kc", "vc", "ct", "st", "posbuf", "mask"],
+                             output_names=["qout"], source=src)
+    _CACHE[key] = k
+    return k
+
+
+def rope_append(qkv, kc, vc, ct, st, posbuf, mask, n_heads, n_kv, hd, maxseq, stream=None):
+    k = get_rope_append(n_heads, n_kv, hd, maxseq)
+    n = (n_heads + 2 * n_kv) * hd
+    nthr = ((n + 255) // 256) * 256
+    return k(inputs=[qkv, kc, vc, ct, st, posbuf, mask], grid=(nthr, 1, 1),
+             threadgroup=(256, 1, 1),
+             output_shapes=[(n_heads * hd,)], output_dtypes=[mx.float32], stream=stream)[0]

mlx/generation_config.json

@@ -0,0 +1,10 @@
+{
+    "bos_token_id": 151643,
+    "do_sample": false,
+    "eos_token_id": [
+        151645,
+        151643
+    ],
+    "pad_token_id": 151643,
+    "transformers_version": "4.51.0"
+}

mlx/receipts/bench_0p6b_m5.json

@@ -0,0 +1,51 @@
+{
+ "mode": "bench",
+ "model": "neutrino-0p6b_v4_base.bin",
+ "prompt_ids": [
+  785,
+  1376,
+  4522,
+  4815,
+  71617,
+  658,
+  29728,
+  14155,
+  374
+ ],
+ "gen_tokens": 512,
+ "runs": [
+  {
+   "run": 0,
+   "tokens": 512,
+   "seconds": 2.536120083008427,
+   "tok_s": 201.88318503934923
+  },
+  {
+   "run": 1,
+   "tokens": 512,
+   "seconds": 2.596512083997368,
+   "tok_s": 197.1876053092611
+  },
+  {
+   "run": 2,
+   "tokens": 512,
+   "seconds": 2.534324457999901,
+   "tok_s": 202.02622374724365
+  },
+  {
+   "run": 3,
+   "tokens": 512,
+   "seconds": 2.5451969589921646,
+   "tok_s": 201.16321379023626
+  },
+  {
+   "run": 4,
+   "tokens": 512,
+   "seconds": 2.5724296660046093,
+   "tok_s": 199.03362442372122
+  }
+ ],
+ "median_tok_s": 201.16321379023626,
+ "peak_mem_gib": 0.5260553508996964,
+ "utc": "2026-07-25T09:39:14Z"
+}

mlx/receipts/cachegate_0p6b.json

@@ -0,0 +1,61 @@
+{
+ "cache": "hf_greedy_cache_86565bf6.json",
+ "container_md5": "86565bf6183e8031943aac9fd9771385",
+ "prompts": [
+  {
+   "prompt": [
+    1,
+    791,
+    1283,
+    315,
+    220,
+    17,
+    42,
+    99
+   ],
+   "steps": 128,
+   "flips": 0,
+   "flip_detail": [],
+   "pass": true
+  },
+  {
+   "prompt": [
+    1,
+    9707,
+    374,
+    264,
+    1296,
+    13,
+    28,
+    7
+   ],
+   "steps": 128,
+   "flips": 0,
+   "flip_detail": [],
+   "pass": true
+  },
+  {
+   "prompt": [
+    1,
+    2610,
+    525,
+    498,
+    1091,
+    11,
+    16,
+    3
+   ],
+   "steps": 128,
+   "flips": 0,
+   "flip_detail": [],
+   "pass": true
+  }
+ ],
+ "tie_tol": 0.04,
+ "max_flips_per_prompt": 8,
+ "total_flips": 0,
+ "worst_gap": 0.0,
+ "ok": true,
+ "mode": "cachegate",
+ "model": "neutrino-0p6b_v4_base.bin"
+}

mlx/receipts/kernel_version_sweep_0p6b.json

@@ -0,0 +1,11 @@
+{
+ "receipt": "TRIT_METAL_V kernel-version sweep, 0.6B container 91c0b26d, 512-token greedy x3, M5 MacBook 16GB (concurrent 2.5MiB/s download noted)",
+ "utc": "2026-07-25T09:52:00Z",
+ "medians_tok_s": {
+  "v7": 185.6,
+  "v6": 120.4,
+  "v5": 99.8,
+  "v2": 105.2
+ },
+ "note": "v7 = default; official quiet-machine v7 receipt is bench_0p6b_m5.json (201.2)"
+}

mlx/receipts/pathgate_0p6b.json

@@ -0,0 +1,75 @@
+{
+ "n": 32,
+ "identical": true,
+ "first_divergence": null,
+ "fused": [
+  429,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  1614,
+  6351,
+  5942,
+  11,
+  1741,
+  438,
+  279,
+  3738,
+  8109,
+  11,
+  323,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  11625,
+  5322,
+  304,
+  5257,
+  5043,
+  13,
+  576,
+  1376,
+  4522,
+  4815
+ ],
+ "mxops": [
+  429,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  1614,
+  6351,
+  5942,
+  11,
+  1741,
+  438,
+  279,
+  3738,
+  8109,
+  11,
+  323,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  11625,
+  5322,
+  304,
+  5257,
+  5043,
+  13,
+  576,
+  1376,
+  4522,
+  4815
+ ],
+ "mode": "pathgate",
+ "model": "neutrino-0p6b_v4_base.bin"
+}

mlx/receipts/refgate_0p6b.json

@@ -0,0 +1,133 @@
+{
+ "ref": "neutrino_ref.npz",
+ "meta": {
+  "tag": "neutrino",
+  "donor": "Qwen/Qwen3-0.6B",
+  "dtype": "float32",
+  "attn": "eager",
+  "prompt": "The key idea behind ternary neural networks is",
+  "made": "2026-07-25T05:45:54Z"
+ },
+ "tf": [
+  {
+   "pos": 0,
+   "rel": 1.420795504981901e-06,
+   "cos": 0.9999999999996864,
+   "argmax_match": true
+  },
+  {
+   "pos": 1,
+   "rel": 1.4544835094150464e-06,
+   "cos": 0.9999999999997129,
+   "argmax_match": true
+  },
+  {
+   "pos": 2,
+   "rel": 1.245608417973328e-06,
+   "cos": 0.9999999999997389,
+   "argmax_match": true
+  },
+  {
+   "pos": 3,
+   "rel": 1.2583815360193984e-06,
+   "cos": 0.999999999999599,
+   "argmax_match": true
+  },
+  {
+   "pos": 4,
+   "rel": 8.871204307383681e-07,
+   "cos": 0.9999999999997197,
+   "argmax_match": true
+  },
+  {
+   "pos": 5,
+   "rel": 1.742981119610197e-06,
+   "cos": 0.999999999999722,
+   "argmax_match": true
+  },
+  {
+   "pos": 6,
+   "rel": 1.5824395401174085e-06,
+   "cos": 0.999999999999796,
+   "argmax_match": true
+  },
+  {
+   "pos": 7,
+   "rel": 1.167621618981324e-06,
+   "cos": 0.9999999999997883,
+   "argmax_match": true
+  },
+  {
+   "pos": 8,
+   "rel": 1.386377853532605e-06,
+   "cos": 0.99999999999965,
+   "argmax_match": true
+  }
+ ],
+ "greedy_flips": [],
+ "tie_tol": 0.04,
+ "max_flips": 8,
+ "tf_summary": {
+  "rel_max": 1.742981119610197e-06,
+  "rel_mean": 1.3495343923743974e-06,
+  "argmax": "9/9",
+  "near_tie": 0
+ },
+ "flips": 0,
+ "worst_gap": 0.0,
+ "ok": true,
+ "mlx_greedy": [
+  429,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  1614,
+  6351,
+  5942,
+  11,
+  1741,
+  438,
+  279,
+  3738,
+  8109,
+  11,
+  323,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  11625,
+  5322
+ ],
+ "ref_greedy": [
+  429,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  1614,
+  6351,
+  5942,
+  11,
+  1741,
+  438,
+  279,
+  3738,
+  8109,
+  11,
+  323,
+  807,
+  646,
+  387,
+  1483,
+  311,
+  11625,
+  5322
+ ],
+ "mode": "refgate",
+ "model": "neutrino-0p6b_v4_base.bin"
+}

mlx/requirements.txt

@@ -0,0 +1,6 @@
+# fermion_mlx runtime (Apple silicon, macOS 14+)
+mlx>=0.31.2
+numpy>=1.26
+# tokenizer + chat template (generation CLI modes only; gates/bench can run
+# with --no-tokenizer)
+transformers>=4.53

mlx/tokenizer.json

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

mlx/tokenizer_config.json

@@ -0,0 +1,239 @@
+{
+  "add_bos_token": false,
+  "add_prefix_space": false,
+  "added_tokens_decoder": {
+    "151643": {
+      "content": "<|endoftext|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151644": {
+      "content": "<|im_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151645": {
+      "content": "<|im_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151646": {
+      "content": "<|object_ref_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151647": {
+      "content": "<|object_ref_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151648": {
+      "content": "<|box_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151649": {
+      "content": "<|box_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151650": {
+      "content": "<|quad_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151651": {
+      "content": "<|quad_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151652": {
+      "content": "<|vision_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151653": {
+      "content": "<|vision_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151654": {
+      "content": "<|vision_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151655": {
+      "content": "<|image_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151656": {
+      "content": "<|video_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151657": {
+      "content": "<tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151658": {
+      "content": "</tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151659": {
+      "content": "<|fim_prefix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151660": {
+      "content": "<|fim_middle|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151661": {
+      "content": "<|fim_suffix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151662": {
+      "content": "<|fim_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151663": {
+      "content": "<|repo_name|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151664": {
+      "content": "<|file_sep|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151665": {
+      "content": "<tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151666": {
+      "content": "</tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151667": {
+      "content": "<think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151668": {
+      "content": "</think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    }
+  },
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "bos_token": null,
+  "chat_template": "{%- if tools %}\n    {{- '<|im_start|>system\\n' }}\n    {%- if messages[0].role == 'system' %}\n        {{- messages[0].content + '\\n\\n' }}\n    {%- endif %}\n    {{- \"# Tools\\n\\nYou may call one or more functions to assist with the user query.\\n\\nYou are provided with function signatures within <tools></tools> XML tags:\\n<tools>\" }}\n    {%- for tool in tools %}\n        {{- \"\\n\" }}\n        {{- tool | tojson }}\n    {%- endfor %}\n    {{- \"\\n</tools>\\n\\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\\n<tool_call>\\n{\\\"name\\\": <function-name>, \\\"arguments\\\": <args-json-object>}\\n</tool_call><|im_end|>\\n\" }}\n{%- else %}\n    {%- if messages[0].role == 'system' %}\n        {{- '<|im_start|>system\\n' + messages[0].content + '<|im_end|>\\n' }}\n    {%- endif %}\n{%- endif %}\n{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}\n{%- for message in messages[::-1] %}\n    {%- set index = (messages|length - 1) - loop.index0 %}\n    {%- if ns.multi_step_tool and message.role == \"user\" and message.content is string and not(message.content.startswith('<tool_response>') and message.content.endswith('</tool_response>')) %}\n        {%- set ns.multi_step_tool = false %}\n        {%- set ns.last_query_index = index %}\n    {%- endif %}\n{%- endfor %}\n{%- for message in messages %}\n    {%- if message.content is string %}\n        {%- set content = message.content %}\n    {%- else %}\n        {%- set content = '' %}\n    {%- endif %}\n    {%- if (message.role == \"user\") or (message.role == \"system\" and not loop.first) %}\n        {{- '<|im_start|>' + message.role + '\\n' + content + '<|im_end|>' + '\\n' }}\n    {%- elif message.role == \"assistant\" %}\n        {%- set reasoning_content = '' %}\n        {%- if message.reasoning_content is string %}\n            {%- set reasoning_content = message.reasoning_content %}\n        {%- else %}\n            {%- if '</think>' in content %}\n                {%- set reasoning_content = content.split('</think>')[0].rstrip('\\n').split('<think>')[-1].lstrip('\\n') %}\n                {%- set content = content.split('</think>')[-1].lstrip('\\n') %}\n            {%- endif %}\n        {%- endif %}\n        {%- if loop.index0 > ns.last_query_index %}\n            {%- if loop.last or (not loop.last and reasoning_content) %}\n                {{- '<|im_start|>' + message.role + '\\n<think>\\n' + reasoning_content.strip('\\n') + '\\n</think>\\n\\n' + content.lstrip('\\n') }}\n            {%- else %}\n                {{- '<|im_start|>' + message.role + '\\n' + content }}\n            {%- endif %}\n        {%- else %}\n            {{- '<|im_start|>' + message.role + '\\n' + content }}\n        {%- endif %}\n        {%- if message.tool_calls %}\n            {%- for tool_call in message.tool_calls %}\n                {%- if (loop.first and content) or (not loop.first) %}\n                    {{- '\\n' }}\n                {%- endif %}\n                {%- if tool_call.function %}\n                    {%- set tool_call = tool_call.function %}\n                {%- endif %}\n                {{- '<tool_call>\\n{\"name\": \"' }}\n                {{- tool_call.name }}\n                {{- '\", \"arguments\": ' }}\n                {%- if tool_call.arguments is string %}\n                    {{- tool_call.arguments }}\n                {%- else %}\n                    {{- tool_call.arguments | tojson }}\n                {%- endif %}\n                {{- '}\\n</tool_call>' }}\n            {%- endfor %}\n        {%- endif %}\n        {{- '<|im_end|>\\n' }}\n    {%- elif message.role == \"tool\" %}\n        {%- if loop.first or (messages[loop.index0 - 1].role != \"tool\") %}\n            {{- '<|im_start|>user' }}\n        {%- endif %}\n        {{- '\\n<tool_response>\\n' }}\n        {{- content }}\n        {{- '\\n</tool_response>' }}\n        {%- if loop.last or (messages[loop.index0 + 1].role != \"tool\") %}\n            {{- '<|im_end|>\\n' }}\n        {%- endif %}\n    {%- endif %}\n{%- endfor %}\n{%- if add_generation_prompt %}\n    {{- '<|im_start|>assistant\\n' }}\n    {%- if enable_thinking is defined and enable_thinking is false %}\n        {{- '<think>\\n\\n</think>\\n\\n' }}\n    {%- endif %}\n{%- endif %}",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "model_max_length": 131072,
+  "pad_token": "<|endoftext|>",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}

neutrino-0.6b_v4.bin

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

neutrino-0.6b_v4.tv4z

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

receipts/hf_greedy_cache_86565bf6.json

@@ -0,0 +1,433 @@
+{
+ "container_md5": "86565bf6183e8031943aac9fd9771385",
+ "donor": "Qwen/Qwen3-0.6B@c1899de289a04d12100db370d81485cdf75e47ca",
+ "dtype": "float16",
+ "prompts": [
+  [
+   1,
+   791,
+   1283,
+   315,
+   220,
+   17,
+   42,
+   99
+  ],
+  [
+   1,
+   9707,
+   374,
+   264,
+   1296,
+   13,
+   28,
+   7
+  ],
+  [
+   1,
+   2610,
+   525,
+   498,
+   1091,
+   11,
+   16,
+   3
+  ]
+ ],
+ "steps": 128,
+ "tokens": [
+  [
+   1,
+   374,
+   264,
+   4185,
+   17133,
+   1483,
+   304,
+   279,
+   2266,
+   315,
+   279,
+   1809,
+   315,
+   32719,
+   13,
+   1084,
+   19257,
+   311,
+   279,
+   2309,
+   315,
+   279,
+   2781,
+   879,
+   374,
+   304,
+   279,
+   1156,
+   2309,
+   11,
+   323,
+   279,
+   2309,
+   315,
+   279,
+   14704,
+   879,
+   374,
+   304,
+   279,
+   2086,
+   2309,
+   13,
+   576,
+   1809,
+   374,
+   6342,
+   553,
+   24047,
+   9666,
+   389,
+   264,
+   4479,
+   11,
+   323,
+   279,
+   2781,
+   879,
+   374,
+   304,
+   279,
+   1156,
+   2309,
+   374,
+   279,
+   13632,
+   13,
+   576,
+   1809,
+   374,
+   6342,
+   553,
+   24047,
+   9666,
+   389,
+   264,
+   4479,
+   11,
+   323,
+   279,
+   2781,
+   879,
+   374,
+   304,
+   279,
+   2086,
+   2309,
+   374,
+   279,
+   58891,
+   13,
+   576,
+   1809,
+   374,
+   6342,
+   553,
+   24047,
+   9666,
+   389,
+   264,
+   4479,
+   11,
+   323,
+   279,
+   2781,
+   879,
+   374,
+   304,
+   279,
+   1156,
+   2309,
+   374,
+   279,
+   13632,
+   13,
+   576,
+   1809,
+   374,
+   6342,
+   553,
+   24047,
+   9666,
+   389,
+   264,
+   4479,
+   11,
+   323,
+   279
+  ],
+  [
+   16,
+   11,
+   17,
+   11,
+   18,
+   11,
+   19,
+   11,
+   20,
+   11,
+   21,
+   11,
+   22,
+   11,
+   23,
+   11,
+   24,
+   11,
+   16,
+   15,
+   11,
+   16,
+   16,
+   11,
+   16,
+   17,
+   11,
+   16,
+   18,
+   11,
+   16,
+   19,
+   11,
+   16,
+   20,
+   11,
+   16,
+   21,
+   11,
+   16,
+   22,
+   11,
+   16,
+   23,
+   11,
+   16,
+   24,
+   11,
+   17,
+   15,
+   11,
+   17,
+   16,
+   11,
+   17,
+   17,
+   11,
+   17,
+   18,
+   11,
+   17,
+   19,
+   11,
+   17,
+   20,
+   11,
+   17,
+   21,
+   11,
+   17,
+   22,
+   11,
+   17,
+   23,
+   11,
+   17,
+   24,
+   11,
+   18,
+   15,
+   11,
+   18,
+   16,
+   11,
+   18,
+   17,
+   11,
+   18,
+   18,
+   11,
+   18,
+   19,
+   11,
+   18,
+   20,
+   11,
+   18,
+   21,
+   11,
+   18,
+   22,
+   11,
+   18,
+   23,
+   11,
+   18,
+   24,
+   11,
+   19,
+   15,
+   11,
+   19,
+   16,
+   11,
+   19,
+   17,
+   11,
+   19,
+   18,
+   11,
+   19,
+   19,
+   11,
+   19,
+   20,
+   11,
+   19,
+   21
+  ],
+  [
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   17,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   18,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   19,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   20,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   21,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   22,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   23,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   24,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   16,
+   15,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852,
+   438,
+   279,
+   1008,
+   11,
+   16,
+   16,
+   3,
+   323,
+   279,
+   1008,
+   374,
+   279,
+   1852
+  ]
+ ],
+ "trajectory_sha256": "a5c3a24c7918558239d0ef958adb335d7a67df630b084b492735e6bc00c6c74b",
+ "generation_seconds": 22.1,
+ "venue": "modal cpu=8 (fp16 weights, greedy argmax)"
+}

receipts/m5_bitgate_analysis.json

@@ -0,0 +1,18 @@
+{
+ "receipt": "M5 bit-gate divergence analysis (banked with the FAIL-as-measured re-receipt)",
+ "utc": "2026-07-25T06:38:06Z",
+ "container": {
+  "name": "neutrino-0p6b_v4_base.bin",
+  "sha256": "91c0b26d105710e755ef1ec1b5607c00da5d5cbd048fd5584135fb6fc1e19399",
+  "md5": "86565bf6183e8031943aac9fd9771385"
+ },
+ "raw_bit_gate": "221/384 token mismatches vs fresh HF-fp16 greedy cache (per m5_demo_rereceipt_p3.json)",
+ "structure": "ONLY 2 first-divergence argmax flips (prompt1@idx13, prompt3@idx1); all other mismatches are the greedy cascade after those flips; prompt2 exact 128/128",
+ "evidence": {
+  "hf_reference": "three variants agree (expand fp16/load fp16, expand fp16/load fp32, expand fp32/load fp32): prefers 32719 by +0.197..+0.203 (prompt1) and 279 by +0.020..+0.023 (prompt3)",
+  "kernel_exact": "teacher-forced exact-int8 logit dump: argmax 5994 by -0.456 (prompt1) and 400 by -0.197 (prompt3); decode picks == exact-kernel argmax, so NOT a nomination artifact",
+  "determinism": "mismatch pattern identical across runs and across threads 1/4/9",
+  "integrity": "double-export byte-determinism PASS, tv4z byte round-trip PASS, HF expand --self-check PASS (receipt_base.json)"
+ },
+ "conclusion": "trit_run is an int8-activation engine; the HF fp expansion is a different numeric implementation of the same weights. They disagree on ranking only where |top-2 margin| <~ 0.5 logits. The shipped state has a flat (high-entropy) logit landscape, so 2 such positions occur in 384 greedy steps; other banked states gated under the same protocol presented none (their gates passed 0/384). Kernel output is deterministic and self-consistent; container integrity is fully receipted. The bit gate FAIL is banked as measured with this analysis."
+}