nbxtensor 0.0.1__py3-none-any.whl

nbxtensor/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,287 @@
+# Third-party notices — nbxtensor
+
+nbxtensor is distributed under the Apache License 2.0 (`LICENSE`). Some of its Triton kernels are derived from, or
+modelled on, the open-source projects below. Each listed file names its source in its header or beside the borrowed
+code, and its own changes are NeuroBrix's. The upstream commit each extraction started from was not recorded at
+extraction time: every source below is declared **unpinned** (its license is the one its repository carries today and
+carried when the code was taken).
+
+## Code derived from third-party projects
+
+| project | license | files (under `src/nbxtensor/`) |
+|---|---|---|
+| [FlagOpen/FlagGems](https://github.com/FlagOpen/FlagGems) | Apache-2.0 | `ops/addcdiv.py`, `ops/addcmul.py`, `ops/addmv_op.py`, `ops/addr.py`, `ops/all_reduce.py`, `ops/any_reduce.py`, `ops/arange_op.py`, `ops/argmax.py`, `ops/argmin.py`, `ops/attention_wrappers.py`, `ops/autotune_cache.py`, `ops/avg_pool2d.py`, `ops/baddbmm_op.py`, `ops/batch_norm.py`, `ops/bitwise_and.py`, `ops/bitwise_left_shift.py`, `ops/bitwise_not.py`, `ops/bitwise_or.py`, `ops/bitwise_right_shift.py`, `ops/cat_op.py`, `ops/celu.py`, `ops/conv2d.py`, `ops/copy_op.py`, `ops/count_nonzero.py`, `ops/cummax.py`, `ops/cummin.py`, `ops/cumsum.py`, `ops/dispatch.py`, `ops/dot_op.py`, `ops/elementwise_wrappers.py`, `ops/embedding.py`, `ops/exp2.py`, `ops/fft_op.py`, `ops/flip_op.py`, `ops/gather_op.py`, `ops/gemv_vec.py`, `ops/groupnorm.py`, `ops/index_add.py`, `ops/index_put_op.py`, `ops/index_select.py`, `ops/index_wrappers.py`, `ops/isfinite.py`, `ops/isinf.py`, `ops/isnan.py`, `ops/le.py`, `ops/lerp.py`, `ops/linalg_wrappers.py`, `ops/linspace_op.py`, `ops/log_sigmoid.py`, `ops/logical_and.py`, `ops/logical_not.py`, `ops/logical_or.py`, `ops/logical_xor.py`, `ops/matmul.py`, `ops/max_pool2d.py`, `ops/max_pool3d.py`, `ops/max_reduce.py`, `ops/min_reduce.py`, `ops/mse_loss.py`, `ops/nan_to_num.py`, `ops/nllloss.py`, `ops/nonzero_op.py`, `ops/norm_wrappers.py`, `ops/pad_op.py`, `ops/prod.py`, `ops/reduction_wrappers.py`, `ops/repeat_interleave.py`, `ops/scaled_softmax.py`, `ops/scatter_op.py`, `ops/shape_wrappers.py`, `ops/softplus.py`, `ops/sort_op.py`, `ops/stack_op.py`, `ops/std.py`, `ops/tan.py`, `ops/threshold.py`, `ops/topk.py`, `ops/trace_op.py`, `ops/tril.py`, `ops/triu.py`, `ops/unique_op.py`, `ops/upsample_nearest2d.py`, `ops/var.py`, `ops/vector_norm.py`, `ops/weight_norm.py`, `ops/wrappers.py` |
+| [BobMcDear/attorch](https://github.com/BobMcDear/attorch) | MIT | `ops/_common.py`, `ops/conv2d.py`, `ops/conv_wrappers.py`, `ops/cross_entropy.py`, `ops/glu.py`, `ops/layernorm.py`, `ops/rmsnorm.py`, `ops/softmax.py` |
+| [linkedin/Liger-Kernel](https://github.com/linkedin/Liger-Kernel) | BSD-2-Clause | `ops/rope.py` |
+| [Dao-AILab/flash-attention](https://github.com/Dao-AILab/flash-attention) | BSD-3-Clause | `ops/flash_attention.py` (from the upstream flash_attn_triton.py), `ops/elementwise_wrappers.py` (its wrapper) |
+
+FlagGems publishes no NOTICE file; its Apache-2.0 license is reproduced below, and the changes are stated in each
+file's header.
+
+## Projects cited as a reference only (no code copied)
+
+| project | license | where | what is taken |
+|---|---|---|---|
+| [NVIDIA/cutlass](https://github.com/NVIDIA/cutlass) | BSD-3-Clause | `ops/mma_m8n8k4.py`, `ops/depthwise_conv2d.py` | the SM70 fragment layout and the depthwise iterator's shape, as documentation |
+| [ModelTC/lightllm](https://github.com/ModelTC/lightllm), [vllm-project/vllm](https://github.com/vllm-project/vllm) | Apache-2.0 | `ops/decode_attn_vec.py`, `ops/moe_decode_vec.py`, `ops/moe_align.py`, `ops/paged_decode_attn.py`, `ops/attention_wrappers.py` | the structure of decode attention and MoE alignment, re-written |
+| [AutoGPTQ](https://github.com/AutoGPTQ/AutoGPTQ) | MIT | `ops/dequant_gemv.py` | the packing convention of the stored weights |
+
+## License texts
+
+### FlagOpen/FlagGems — Apache License 2.0
+
+                                 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
+
+### BobMcDear/attorch — MIT
+MIT License
+
+Copyright (c) 2023 Borna Ahmadzadeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### linkedin/Liger-Kernel — BSD 2-Clause
+BSD 2-CLAUSE LICENSE
+Copyright 2024 LinkedIn Corporation 
+All Rights Reserved.
+Redistribution and use in source and binary forms, with or
+without modification, are permitted provided that the following
+conditions are met:
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following
+disclaimer in the documentation and/or other materials provided
+with the distribution.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+### Dao-AILab/flash-attention — BSD 3-Clause
+BSD 3-Clause License
+
+Copyright (c) 2022, the respective contributors, as shown by the AUTHORS file.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nbxtensor/__init__.py

@@ -0,0 +1,17 @@
+"""nbxtensor — an inference-first tensor library, torch-free.
+
+The tensor library of NeuroBrix, built to stand on its own: dtypes, shapes,
+strides and views, memory that is planned rather than discovered, device
+backends (CUDA, Apple Metal, CPU) and Triton kernels that declare their own
+cost. NeuroBrix's Triton engine is its first client; it imports this package
+and never re-implements what lives here.
+
+What is in the library today, area by area, is the README's status table;
+the versions are numbered as `docs/nbxtensor/DESIGN.md` section 7 says (the
+first publication is 0.0.1, each fix after it increments, the Rust rewrite is
+2.0.0).
+"""
+
+#: the one version number; `pyproject.toml` states the same (tests/test_version.py)
+__version__ = "0.0.1"
+__all__: list = []

nbxtensor/backend/__init__.py

@@ -0,0 +1 @@
+"""Backends: detection, the kernel launcher and its contract, the Metal driver, the CPU backend, graph capture."""

nbxtensor/backend/capabilities.py

@@ -0,0 +1,207 @@
+"""What the backend in force can do, as declared or measured: float64, the flash and reduction tiles, pointers loaded
+from memory, device-side asserts. Cut out of tensor.py (M2, 2026-10-29), unchanged."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from nbxtensor.backend import runtime as _rt
+
+
+
+
+# Whether the backend HONOURS a device-side assert the author explicitly kept
+# with `@triton.jit(debug=True)`. This is not a question about debug builds:
+# `tl.device_assert` reaches the IR at all ONLY when `options.debug` is true
+# (triton/language/semantic.py: `if not self.builder.options.debug: return`),
+# so a `tt.assert` in the IR is by construction one the author demanded.
+#
+# CUDA and ROCm halt the thread at the assert and the next sync raises. The
+# Metal backend COMPUTES the predicate and then discards it — measured
+# 2026-09-10: with debug=True the generated MSL carries `mask_5 = idx < 2`
+# and never reads it. The guard is paid for in registers and not delivered,
+# so a kernel whose only bounds check is that assert performs the very access
+# the assert was there to prevent (`index_put` wrote 8 floats past the end of
+# a 24-float tensor; `embedding` read past the end of the weight).
+#
+# This is a capability, not a vendor test — adding a backend is adding a row.
+_BACKEND_TRAPS_ON_DEVICE_ASSERT = {"cuda": True, "hip": True, "metal": False}
+
+# Whether a kernel can load a device ADDRESS out of a tensor and then read
+# through it — the [E] int64 pointer table that lets one launch reach every
+# expert's weights instead of one launch per expert.
+#
+# Measured 2026-09-17 on triton-ext (M4 Pro, Toolchain 27) with a control that
+# differs by the one variable — whether the address arrives AS a pointer or as
+# an integer to be converted — and in BOTH Triton spellings, because they are
+# different constructs and cannot be assumed to share a fate:
+#
+#     control  (pointer as a pointer)       : nonzero 256/256   correct
+#     subject  (.to(pointer_type))          : nonzero   0/256   ALL ZEROS
+#     subject  (tl.cast bitcast=True)       : nonzero   0/256   ALL ZEROS
+#
+# The second subject is the spelling our own kernels use, which is what makes
+# the engine's zeros attributable to this and not to us. Nothing is raised: the
+# kernel compiles, launches and writes zeros. The reproducer contains none of
+# our code (`repro_ext_pointer_from_table.py`) and is drafted for upstream.
+#
+# It is recorded HERE because the engine cannot catch what is never raised: a
+# band that cannot address its experts has to refuse by name, and a refusal
+# needs a fact to stand on. This is a capability, not a vendor test — adding a
+# backend is adding a row.
+_BACKEND_LOADS_POINTERS_FROM_MEMORY = {"cuda": True, "hip": True, "metal": False}
+# Whether the backend's kernels can read and write a float64 (or complex128) element. Metal
+# has no double: its lowering NARROWS f64 to float in silence (`triton/metal_backend.py`,
+# `TRITON_METAL_FP64_UNAVAILABLE`), so a kernel over a float64 buffer reads eight-byte
+# elements as four-byte ones. Measured 2026-09-28: `from_numpy(float64).to(bf16)` on the
+# M4 Pro gave 1 139 of 143 360 bits right and 3 255 non-finite values (the Sana 4K sincos
+# positional embedding, every off-trace size). A census says "not this time"; the door in
+# `NBXTensor.to` says "never": a cast from or to such a dtype is refused BY NAME there.
+#
+# The answer is the CALLER's to give (`set_backend_has_fp64`), not a table here: it is a fact
+# about the hardware the caller declares once (NeuroBrix: the vendor profile's
+# `precision.kernels_carry_fp64.triton`, bound by `kernels.wrappers.set_hardware_profile`).
+# Unset, a question that needs it is refused — a float64 element is never assumed readable.
+_BACKEND_HAS_FP64 = None
+
+
+def set_backend_has_fp64(value: bool) -> None:
+    """Declare whether this process's backend kernels compute float64 / complex128 elements."""
+    global _BACKEND_HAS_FP64
+    if not isinstance(value, bool):
+        raise TypeError(f"set_backend_has_fp64 takes a bool, got {value!r}")
+    _BACKEND_HAS_FP64 = value
+
+
+def backend_has_fp64() -> bool:
+    """Whether the backend's kernels handle float64 elements, as declared by
+    `set_backend_has_fp64`; refused while undeclared."""
+    if _BACKEND_HAS_FP64 is None:
+        raise RuntimeError(
+            f"ZERO FALLBACK: whether the '{_rt.gpu_backend()}' backend's kernels compute "
+            f"float64 was never declared (`set_backend_has_fp64`); it is the hardware's fact, "
+            f"never assumed")
+    return _BACKEND_HAS_FP64
+
+
+# The smallest `tl.dot` tile dimension a backend's attention lowering handles
+# CORRECTLY. On cuda/hip the floor is the TensorCore minimum, 16, and a decode
+# step at seqlen_q=1 uses it. Metal's generic attention lowering silently
+# mis-computes below 32 -- rows past the first become garbage, for any
+# head_dim -- and refuses rather than emit it; its tiled template does take a
+# smaller tile, but only for a kernel its detector resolves completely at
+# head_dim 64, which is not every kernel.
+#
+# Sixteen wastes half a Q tile at seqlen_q=1. A refusal wastes the model.
+#
+# This is a capability, not a vendor test — adding a backend is adding a row.
+_BACKEND_FA_MIN_TILE = {"cuda": 16, "hip": 16, "metal": 32}
+
+
+def fa_min_tile() -> int:
+    """The smallest attention tile dimension this backend computes correctly."""
+    return _backend_capability(
+        _BACKEND_FA_MIN_TILE, "_BACKEND_FA_MIN_TILE",
+        "the smallest attention tile dimension it computes correctly")
+
+
+# The largest 2-D reduction tile (product of block dims) a backend's lowering
+# stages correctly. The generic Metal lowering stages one element per thread,
+# so a tile above the 1024-thread threadgroup has lanes with nothing to hold
+# their part -- it refuses rather than reduce part of the tile. cuda/hip lower
+# a 2-D reduce differently and take the tile the reduction kernels were tuned
+# for (BLOCK_M*BLOCK_N = 8192); their entry is that tuned size so min() is the
+# identity and nothing moves there.
+#
+# A capability, not a vendor test -- adding a backend is adding a row.
+_BACKEND_REDUCE_TILE_MAX = {"cuda": 1 << 20, "hip": 1 << 20, "metal": 1024}
+
+
+def reduce_tile_max() -> int:
+    """The largest 2-D reduction tile this backend stages correctly."""
+    return _backend_capability(
+        _BACKEND_REDUCE_TILE_MAX, "_BACKEND_REDUCE_TILE_MAX",
+        "the largest 2-D reduction tile it stages correctly")
+
+
+# Whether a backend's lowering stages a 2-D reduce ONE ELEMENT PER THREAD along the reduced extent: then that extent of
+# a tile cannot exceed the threads of the program that reduces it (its warps x the backend's threads per warp). Metal,
+# measured 2026-09-07: the GEMV's 8 x 256 at 4 warps and the mv's 64 x 256 at 4 warps refused, naming the numbers
+# (tests/unit/config/test_apple_profiles_agree_with_the_device.py held those tiles in the profile until the certifier
+# chose them; the rule is the kernels' prune now, `ops/_configs.prune_gemv_vec` / `prune_addmv`). cuda/hip reduce many
+# elements per thread in registers.
+_BACKEND_REDUCE_PER_THREAD = {"cuda": False, "hip": False, "metal": True}
+_BACKEND_THREADS_PER_WARP = {"cuda": 32, "hip": 64, "metal": 32}
+
+
+def reduced_extent_max(num_warps: int) -> Optional[int]:
+    """The largest reduced extent a program of `num_warps` stages on this backend, or None when its lowering bounds
+    none (it reduces many elements per thread)."""
+    if not _backend_capability(_BACKEND_REDUCE_PER_THREAD, "_BACKEND_REDUCE_PER_THREAD",
+                               "whether it stages a 2-D reduce one element per thread"):
+        return None
+    return int(num_warps) * int(_backend_capability(_BACKEND_THREADS_PER_WARP, "_BACKEND_THREADS_PER_WARP",
+                                                    "its threads per warp"))
+
+
+def _backend_capability(table, name: str, what: str) -> bool:
+    """One row of one capability table, or a refusal naming both."""
+    backend = _rt.gpu_backend()
+    value = table.get(backend)
+    if value is None:
+        raise RuntimeError(
+            f"ZERO FALLBACK: backend {backend!r} does not say {what} "
+            f"({name}, rows: {sorted(table)}). Adding a backend is adding a "
+            f"row, not guessing.")
+    return value
+
+
+#: What the ENGINE declared about a backend, above the tables: a capability that is a
+#: property of the launcher it selected, not of the silicon, is the engine's to state.
+#: nbx_tensor is a library with a boundary (R33, the ratchet cell
+#: test_the_boundary_does_not_widen) and asks the engine nothing; the engine tells it,
+#: through `declare_backend_capability`, before a kernel is launched.
+_DECLARED_CAPABILITIES: Dict[str, Dict[str, bool]] = {}
+
+
+def declare_backend_capability(backend: str, **capabilities: bool) -> None:
+    """The engine states a capability of the launcher it selected for `backend`
+    (`loads_pointers_from_memory=True` for Metal's triton_ext, proven through its pinned
+    scope). Read by the capability questions below, above the static tables."""
+    for name, value in capabilities.items():
+        if not isinstance(value, bool):
+            raise TypeError(f"a backend capability is a bool, not {value!r} ({backend}.{name})")
+    _DECLARED_CAPABILITIES.setdefault(backend, {}).update(capabilities)
+
+
+def backend_loads_pointers_from_memory() -> bool:
+    """True where a kernel may dereference an address it LOADED from a tensor.
+
+    On Metal the answer is a property of the LAUNCHER, not the silicon: a
+    loaded address reads correctly exactly when the driver keeps the captured
+    address alive across launches, which `triton_ext` does through
+    `pinned_addresses` (proven against an fp64 oracle,
+    test_the_moe_table_reads_through_a_pinned_scope, 2026-09-20; the archived
+    fork had no such scope and the same load returned zeros with nothing
+    raised — the measured defect this gate refuses). So the metal row is a
+    SELECTION read, not a constant — and the selection is the engine's, so the
+    engine DECLARES it here on every Metal run's entry
+    (`triton/metal_backend.ensure_triton_metal_or_raise`); undeclared, the table's
+    False stands until a launcher proves its own lifetime contract. Until
+    2026-09-26 this function imported the engine's metal_backend to ask, which
+    widened the library's boundary (the ratchet cell went red on main).
+    """
+    backend = _rt.gpu_backend()
+    declared = _DECLARED_CAPABILITIES.get(backend, {}).get("loads_pointers_from_memory")
+    if declared is not None:
+        return declared
+    return _backend_capability(
+        _BACKEND_LOADS_POINTERS_FROM_MEMORY, "_BACKEND_LOADS_POINTERS_FROM_MEMORY",
+        "whether a kernel can read through a pointer loaded from memory")
+
+
+def backend_traps_on_device_assert() -> bool:
+    """True where `tl.device_assert` actually stops the kernel."""
+    return _backend_capability(
+        _BACKEND_TRAPS_ON_DEVICE_ASSERT, "_BACKEND_TRAPS_ON_DEVICE_ASSERT",
+        "whether it honours a device-side assert")

nbxtensor/backend/cpu/__init__.py

@@ -0,0 +1 @@
+"""The CPU backend's host machinery: the thread pool every core is used through (`pool`)."""

nbxtensor/backend/cpu/blas.py

@@ -0,0 +1,102 @@
+"""The thread count of the BLAS numpy calls, from the pool's size, with no oversubscription (DESIGN rule 14).
+
+numpy's matrix products run in the BLAS it was built with, which has its own threads. Two rules:
+
+- outside the pool, the BLAS uses as many threads as the pool would (`pool.threads()`: the machine's compute cores);
+- inside `parallel_for`, each piece already runs on a pool thread, so the BLAS a piece calls runs single-threaded:
+  pool threads x BLAS threads would put more threads on the cores than there are cores.
+
+Through the BLAS's own symbols, found in the process (no new dependency):
+
+- Apple's Accelerate (`BLASSetThreading`, macOS 15+): a setting PER THREAD, multi-threaded (Accelerate chooses how
+  many) or single-threaded — the pool's threads are set single-threaded when they start;
+- OpenBLAS (numpy's wheels on Linux; `openblas_set_num_threads` / `scipy_openblas_set_num_threads64_`): a count for
+  the PROCESS — set to 1 while `parallel_for` runs, the pool's size otherwise.
+
+A BLAS none of these names is refused by name when its threads are set: the count is never assumed.
+"""
+from __future__ import annotations
+
+import ctypes
+import functools
+import platform
+from pathlib import Path
+from typing import Optional, Tuple
+
+__all__ = ["blas", "set_blas_threads", "blas_threads_of_this_thread"]
+
+_ACCELERATE = "/System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib"
+_OPENBLAS_SET = ("scipy_openblas_set_num_threads64_", "scipy_openblas_set_num_threads", "openblas_set_num_threads64_",
+                 "openblas_set_num_threads")
+_OPENBLAS_GET = ("scipy_openblas_get_num_threads64_", "scipy_openblas_get_num_threads", "openblas_get_num_threads64_",
+                 "openblas_get_num_threads")
+
+
+def _loaded_openblas() -> Optional[str]:
+    maps = Path("/proc/self/maps")
+    if not maps.is_file():
+        return None
+    for line in maps.read_text().splitlines():
+        path = line.split()[-1] if line.split() else ""
+        if "openblas" in Path(path).name.lower():
+            return path
+    return None
+
+
+@functools.lru_cache(maxsize=1)
+def blas() -> Tuple[str, object]:
+    """(kind, library) of the BLAS numpy runs in this process: ("accelerate", libBLAS) or ("openblas", the loaded
+    library); refused by name otherwise."""
+    import numpy  # noqa: F401 — numpy loads its BLAS; the library is the one already in the process
+    if platform.system() == "Darwin":
+        # a system library lives in the dyld shared cache, not as a file on disk: it is loaded, never stat-ed
+        try:
+            lib = ctypes.CDLL(_ACCELERATE)
+        except OSError:
+            lib = None
+        if lib is not None and hasattr(lib, "BLASSetThreading") and hasattr(lib, "BLASGetThreading"):
+            return "accelerate", lib
+    path = _loaded_openblas()
+    if path is not None:
+        lib = ctypes.CDLL(path)
+        if any(hasattr(lib, s) for s in _OPENBLAS_SET):
+            return "openblas", lib
+    raise RuntimeError("ZERO FALLBACK: nbxtensor knows no thread control of this process's BLAS (Accelerate's "
+                       "BLASSetThreading, OpenBLAS's openblas_set_num_threads); its threads are not set")
+
+
+def _symbol(lib, names):
+    for name in names:
+        if hasattr(lib, name):
+            return getattr(lib, name)
+    raise RuntimeError(f"ZERO FALLBACK: the BLAS exports none of {names}")
+
+
+def set_blas_threads(n: int) -> None:
+    """The BLAS threads: `n` (OpenBLAS: for the process); Accelerate takes no count: 1 is single-threaded for the
+    calling thread, more is Accelerate's own multi-threading for it."""
+    if not isinstance(n, int) or n < 1:
+        raise ValueError(f"set_blas_threads: {n!r} — one thread or more")
+    kind, lib = blas()
+    if kind == "accelerate":
+        fn = lib.BLASSetThreading
+        fn.argtypes, fn.restype = [ctypes.c_uint], ctypes.c_int
+        if fn(0 if n > 1 else 1) != 0:            # BLAS_THREADING_MULTI_THREADED = 0, _SINGLE_THREADED = 1
+            raise RuntimeError("Accelerate refused BLASSetThreading on this platform (macOS 15 or later needed)")
+        return
+    fn = _symbol(lib, _OPENBLAS_SET)
+    fn.argtypes, fn.restype = [ctypes.c_int], None
+    fn(n)
+
+
+def blas_threads_of_this_thread() -> Optional[int]:
+    """1 when the BLAS runs single-threaded for the calling thread, else its count (OpenBLAS), or None for
+    Accelerate's own multi-threading (it states no count)."""
+    kind, lib = blas()
+    if kind == "accelerate":
+        fn = lib.BLASGetThreading
+        fn.restype = ctypes.c_uint
+        return 1 if fn() == 1 else None
+    fn = _symbol(lib, _OPENBLAS_GET)
+    fn.restype = ctypes.c_int
+    return int(fn())