DeepSeek V4.1: the lane backend — one stream per slot on the lane core

.gitignore

@@ -21,3 +21,6 @@ zig-out/
 
 # Versioned GUI build resources, generated app engines stay ignored in app/.gitignore.
 !app/build/
+# mHC fp64 qualification receipts.
+/receipts/
+*.log

THIRD_PARTY_NOTICES.md

@@ -217,6 +217,13 @@ TensorFold ships no model weights. The `z-lab/Qwen3.8-27B-DFlash2` model card st
 The optional `incoai/GLM-5.3-Flash-DFlash2` model card states CC BY-NC-ND 4.0, for non-commercial use
 without derivatives; only the Python engine reads that drafter. Each checkpoint keeps its own license.
 
+The native `zig/src/families/deepseek_v41/` implementation and `zig/tests/deepseek_v41_reference/`
+follow [DeepSeek-V4.1-Flash's official inference](https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash/tree/2cba9e42aa026125f3ed06c6d98c1db82f7ca027/inference),
+MIT License, Copyright (c) 2023 DeepSeek: the reference's equations, the Engram normalization,
+PCG64 multipliers and prime bucket layout, and the pinned chat template come from that revision.
+The EXL3 checkpoint reads through the ExLlamaV3 format covered above; no captured CUDA/Triton
+kernel assets, full model shards or binary traces are bundled.
+
 ## Structured output: libtfgrammar
 
 `lib/libtfgrammar` in the release archives is `zig/src/grammar/tf_grammar.cc` compiled with the C++ sources of

build.zig

@@ -85,7 +85,7 @@ pub fn build(b: *std.Build) void {
     @import("zig/build/kernel_symbols.zig").tests(b, test_step);
     @import("zig/build/checkpoint_security.zig").tests(b, test_step);
     if (b.graph.host.result.os.tag == .macos) {
-        const step5_mods = metalEngineModules(b, b.graph.host, .Debug, draft_ids);
+        const step5_mods = metalEngineModules(b, b.graph.host, .Debug, draft_ids, b.createModule(.{ .root_source_file = b.path("zig/src/core/tokenizer/tokenizer.zig"), .target = b.graph.host, .optimize = .Debug, .link_libc = true }));
         const empty = b.addWriteFiles().add("step5-compile-only.metallib", "");
         step5_mods.sources.addImport("nemotron_packed_metallib", embedded(b, empty, "nemotron_packed.metallib"));
         @import("zig/build/step5_host.zig").steps(b, step5_mods.metal, step5_mods.engine, step5_mods.lanes);
@@ -95,7 +95,7 @@ pub fn build(b: *std.Build) void {
     @import("zig/build/flashnext_budget.zig").steps(b, test_step);
     @import("zig/build/flashnext_batch_host.zig").tests(b, test_step);
     if (b.graph.host.result.os.tag == .macos) {
-        const budget_mods = metalEngineModules(b, b.graph.host, .Debug, draft_ids);
+        const budget_mods = metalEngineModules(b, b.graph.host, .Debug, draft_ids, b.createModule(.{ .root_source_file = b.path("zig/src/core/tokenizer/tokenizer.zig"), .target = b.graph.host, .optimize = .Debug, .link_libc = true }));
         const budget_empty = b.addWriteFiles().add("budget-compile-only.metallib", "");
         budget_mods.sources.addImport("nemotron_packed_metallib", embedded(b, budget_empty, "nemotron_packed.metallib"));
         @import("zig/build/flashnext_budget.zig").compileHost(b, budget_mods.metal, budget_mods.engine, budget_mods.lanes);
@@ -128,7 +128,7 @@ pub fn build(b: *std.Build) void {
     gemma4_host_sources.addAnonymousImport("nemotron_packed_metallib", .{ .root_source_file = b.addWriteFiles().add("gemma4-host-empty.metallib", "") });
     const gemma4_contract_host = @import("zig/build/gemma4_host.zig").tests(b, gemma4_host_sources);
     if (b.graph.host.result.os.tag == .macos) {
-        const gemma4_host_mods = metalEngineModules(b, b.graph.host, .Debug, draft_ids);
+        const gemma4_host_mods = metalEngineModules(b, b.graph.host, .Debug, draft_ids, b.createModule(.{ .root_source_file = b.path("zig/src/core/tokenizer/tokenizer.zig"), .target = b.graph.host, .optimize = .Debug, .link_libc = true }));
         gemma4_host_mods.sources.addImport("nemotron_packed_metallib", embedded(b, b.addWriteFiles().add("gemma4-compile-empty.metallib", ""), "nemotron_packed.metallib"));
         @import("zig/build/gemma4_host.zig").compileHost(b, gemma4_host_mods.metal, gemma4_host_mods.engine, gemma4_host_mods.lanes, gemma4_host_mods.sources);
         @import("zig/build/qwen27_host.zig").compileHost(b, gemma4_host_mods.metal, gemma4_host_mods.engine, gemma4_host_mods.lanes);

docs/deepseek-v41-mhc-fp64.json

@@ -0,0 +1,103 @@
+{
+ "scope": "mHC (hyperconnection mix) stage fp64 qualification: rounding level, Metal deltas and 1-ULP input amplification. Independent CPU reference parameterized comptime (math.zig MixOf/denseOf/mixesOf/splitOf/inverseOf/collapseOf/expandOf, f32 source-contract path bit-identical, f64 ideal path); harness zig/tests/deepseek_v41_reference/operator_hc_fp64.zig; fixtures hc_attention_rms.json and hc_fp64_rows.json (retained inputs only).",
+ "nrms_definition": "sqrt(sum(delta^2)/sum(ref^2)) in f64; ULP = |delta| / fp32 spacing at the fp64 reference value.",
+ "inputs": [
+  "token671_attention (retained token-671 embedding, four copies)",
+  "token1_ffn (retained token-1 FFN stream and branch, real hc_ffn scale/base)",
+  "eight_teacher_rows (the eight retained teacher embeddings)",
+  "wide_dynamic_range (copy magnitudes 2^24..2^-12, rotating signs)",
+  "split_args (16 retained unary arguments incl. 1.4393715858459473, controlling post argument, integer exp sweep -32..32, plus sigmoid/softmax spans)",
+  "cancellation fixtures (half-ULP terms after 1.0)"
+ ],
+ "rounding_level_fp32_reference_vs_fp64": {
+  "inverse_statistic_nrms": [
+   2.7e-09,
+   2.8e-08
+  ],
+  "projection_dense_nrms": [
+   2.2e-08,
+   2.9e-08
+  ],
+  "pre_sigmoid_nrms": [
+   1.1e-08,
+   4.2e-08
+  ],
+  "post_nrms": [
+   3.9e-08,
+   7.2e-08
+  ],
+  "comb_sinkhorn_nrms": [
+   1.4e-08,
+   6.8e-08
+  ],
+  "collapse_bf16_unequal_cells": 0,
+  "post_expand_bf16_unequal_cells": [
+   0,
+   5
+  ]
+ },
+ "metal_vs_fp64": {
+  "inverse_max_ulp": 0.6,
+  "projection_max_ulp": 0.5,
+  "pre_max_ulp": 2.75,
+  "post_max_ulp": 2.29,
+  "comb_max_ulp_near_cancelled_cells_only": 34.2,
+  "comb_max_abs": 1.5e-07,
+  "post_controlling_exponent_row_max_ulp": 1.61,
+  "exponent_sweep_minus32_to_32_worst_stage_nrms": 9e-08,
+  "bf16_unequal_cells": {
+   "token671": 0,
+   "token1_ffn": "3 of 20480",
+   "eight_teacher_rows": "8 of 163840",
+   "wide_dynamic_range": 0
+  },
+  "verdict": "every sub-stage sits at the fp32 source-contract rounding level; Metal exceeds the fp32 reference by at most ~1 ULP at the documented Metal exp boundary"
+ },
+ "cancellation_boundaries": [
+  {
+   "fixture": "collapse_half_ulps",
+   "metal": "0x3500",
+   "f32_ref": "0x3500",
+   "f64_ideal": "0x34c0"
+  },
+  {
+   "fixture": "post_half_ulps",
+   "metal": "0x0",
+   "f32_ref": "0x0",
+   "f64_ideal": "0x3400"
+  },
+  {
+   "fixture": "branch_product",
+   "metal": "0x3500",
+   "f32_ref": "0x3500",
+   "f64_ideal": "0x34c0"
+  }
+ ],
+ "amplification_1ulp_input": {
+  "method": "perturb one bf16 stream cell (or branch cell) by 1 ULP, propagate the ideal fp64 stage, output NRMS growth = sqrt(sum(dy^2)/sum(y^2)) / (|dx|/sqrt(sum(x^2))); 256 sampled cells per row; 8 teacher positions plus the token-1 FFN row",
+  "analog_fp64_gain_mean_per_row": [
+   0.182,
+   0.76
+  ],
+  "analog_fp64_gain_max_overall": 0.762,
+  "collapse_gain_mean": 0.5003,
+  "collapse_gain_max": 1.944,
+  "bf16_visible_gain_mean_per_row": [
+   0.74,
+   2.382
+  ],
+  "bf16_visible_gain_max": 34.5,
+  "bf16_rows_changed_fraction": "224-250 of 256 perturbations change at least one of 20480 output cells",
+  "mean_changed_cells": "8.1-13.1 of 20480",
+  "statistic_relative_shift_mean": 3.6e-07,
+  "comb_nrms_shift_mean": 3.6e-08,
+  "metal_confirmation_row0": {
+   "amp_mean": 1.886,
+   "fp64_bf16_amp_mean": 1.945,
+   "mean_changed_cells": 12.06
+  }
+ },
+ "gate_reading": "A single-ULP input difference is attenuated by the mix in exact arithmetic (gain < 1) and appears as 1-bf16-ULP flips on about 0.06 percent of output cells; the stage's own rounding-level output NRMS is 0 to 2.5e-5. Hyperconnection mixing therefore cannot turn fp32 ULP noise into the observed 4.096 percent whole-model NRMS; a specific operator-level difference elsewhere (sparse/compressed attention candidates) remains the plausible cause.",
+ "kernel_changes": "none required; no tolerance relaxed, no source coefficient injected",
+ "receipts": "gitignored receipts/ (mhc-fp64-run.log, mhc-fp64-parsed.json, build-summary.log); commit contains code, fixture and this summary"
+}

docs/deepseek-v41.md

@@ -0,0 +1,71 @@
+# DeepSeek-V4.1-Flash on one Mac
+
+TensorFold serves the whole DeepSeek-V4.1-Flash from the resident EXL3 packs on one Apple
+Silicon Mac. The engine runs on the lane core — one stream per slot, windows of rows — so
+concurrent requests each keep their own caches and Engram cursor, and replies are greedy
+(`temperature 0`); drafts, grammar masks and tree requests are refused until their pieces
+land. The served checks hold: a drafted request reports `"draft": false` and equals the
+no-drafts reply, a resumed conversation equals the fresh one, and concurrent lanes equal
+their solo runs.
+
+## What you need
+
+- One Mac with 512 GB of unified memory. The 2.9bpw pack stages about 413 GB of weights
+  and the 2.8bpw pack about 190 GB; the server stays at 70% of RAM unless
+  `GLM_LOAD_LIMIT_GB` opts past it, as GLM's load does.
+- The original release's inference directory — `tokenizer.json`, `config.json`,
+  `chat_template.jinja` and the two Engram tables — beside the pack or passed with
+  `--engram-table-dir`. The weights come under DeepSeek's own terms; the inference code
+  is MIT and the native reference follows it (see THIRD_PARTY_NOTICES).
+- An EXL3 pack. The qualification ran jayleaton's 2.9bpw and 2.8bpw repacks; the 2.8bpw
+  pack's duplicated tensors are owned by the index, so a shard contributes only the
+  tensors the index maps to it.
+
+## The token map
+
+The Engram tables are keyed by a compressed vocabulary derived from the release's own
+tokenizer and inference config. The native engine builds the map itself — decode each
+id, fall back to the raw token when the decoder emits U+FFFD, normalize through the
+release's chain (NFKD, strip marks, lowercase, the whitespace replaces), dedupe — with
+the multipliers drawn from NumPy's PCG64 exactly as the source does. The result is
+byte-identical to the map shipped beside the 2.9bpw pack. When `engram-token-map.bin`
+is missing beside the checkpoint and the original's tokenizer sits beside the tables,
+the engine builds it at open; no Python step. To build it by hand:
+
+```sh
+zig build tf-dsv41-token-map && ./zig-out/bin/tf-dsv41-token-map \
+  --tokenizer <orig>/tokenizer.json --config <orig>/config.json --output <pack>/engram-token-map.bin
+```
+
+## Serve
+
+```sh
+GLM_LOAD_LIMIT_GB=430 tensorfold-native serve <pack> \
+  --engram-table-dir <orig> --chat-template <orig>/chat_template.jinja \
+  --context 65536 --parallel 2 --no-drafts --prompt-cache-gib 0 \
+  --host 127.0.0.1 --port 8099 --name DeepSeek-V4.1-Flash --keep-warm 0
+```
+
+`--parallel` is the lane count: each lane is one stream with its own caches and Engram
+cursor. `--no-drafts` is the honest flag for now — the engine decodes greedily and a
+drafted request answers with `"draft": false` and the same tokens. The resident load
+reads no weights from disk during execution; a run that does fails the receipt's
+residency gate.
+
+## The numbers
+
+The per-operator reference tests run every stage against an FP64 ideal at three sides —
+kernel, FP32 source contract, FP64 ideal — and assert rounding level. The whole-model
+picture is sensitivity-dominated: the FP32 oracle against the FP64 oracle on the same
+tokens is 2.90% NRMS, Metal against FP32 is 4.10% at 2.9bpw and 5.16% at 2.8bpw (the
+error grows as the quantization coarsens, the signature of the model amplifying
+FP32-level differences), and the indexer's 512-pick selection boundary lands inside an
+exact BF16 tie at every indexed layer past the window fill — so pick order there is
+decided by sub-quantum noise, folded into the sensitivity accounting. The 1% absolute
+gate stays a trip-wire next to argmax agreement, which held at every width.
+
+## Receipts
+
+The qualification receipts — the served parity legs, the lane bit-equality, the oracle
+and margin captures — live beside the PRs on the fork; the tree carries the tests that
+regenerate them.

tools/zig/lean_check.py

@@ -12,9 +12,9 @@
            ".sh": re.compile(r"^\s*#(?!!)")}
 BLOCK = re.compile(r"/\*")
 DOCSTRING = re.compile(r'^\s*(?:[rubf]{0,2})("""|\'\'\')')
-GENERATED = ("unicode_data.zig",)
+GENERATED = ("unicode_data.zig", "nfkd_data.zig")
 HEX_METAL = re.compile(r"_[0-9a-f]{16}\.metal$")
-# Generated outputs are skipped entirely. unicode_data.zig has only the length exemption.
+# Generator outputs are skipped entirely, including the Unicode table files built from the release's tables.
 GENERATOR_OUTPUT = (
     "zig/src/core/tokenizer/nfkd_data.zig",
     "zig/src/families/flashnext/roles_gen.zig",

tools/zig/nfkd_tables.py

@@ -0,0 +1,96 @@
+"""Emit the Engram token-map normalizer's NFKD, mark, lowercase and combining-class tables as Zig source."""
+import argparse
+import subprocess
+import sys
+import tempfile
+import unicodedata
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+OUT = ROOT / "zig" / "src" / "core" / "tokenizer" / "nfkd_data.zig"
+VERSION = "16.0.0"
+
+
+def rows(values, per_line, fmt):
+    """Comma-terminated lines of at most `per_line` values, four-space indented."""
+    for i in range(0, len(values), per_line):
+        yield "    " + " ".join(fmt(v) + "," for v in values[i:i + per_line])
+
+
+def render():
+    """The generated Zig source before the compiler's formatter aligns the columns."""
+    flat, decompositions = [], []
+    for cp in range(0x110000):
+        decomposed = unicodedata.normalize("NFKD", chr(cp))
+        if decomposed != chr(cp):
+            decompositions.append((cp, len(flat), len(decomposed)))
+            flat.extend(ord(c) for c in decomposed)
+    marks = [cp for cp in range(0x110000) if unicodedata.category(chr(cp)) in ("Mn", "Mc", "Me")]
+    lower_flat, lowercases = [], []
+    for cp in range(0x110000):
+        low = chr(cp).lower()
+        if low != chr(cp):
+            lowercases.append((cp, len(lower_flat), len(low)))
+            lower_flat.extend(ord(c) for c in low)
+    cccs = []
+    for cp in range(0x110000):
+        ccc = unicodedata.combining(chr(cp))
+        if not ccc:
+            continue
+        if cccs and cccs[-1][2] == ccc and cccs[-1][1] + 1 == cp:
+            cccs[-1][1] = cp
+        else:
+            cccs.append([cp, cp, ccc])
+    decomp = lambda e: ".{ .cp = 0x%04X, .start = %d, .len = %d }" % e
+    ccc = lambda t: ".{ 0x%04X, 0x%04X, 0x%04X }" % tuple(t)
+    return "\n".join([
+        "// Generated by tools/zig/nfkd_tables.py from the Unicode %s character database; do not edit." % VERSION,
+        'pub const version = "%s";' % VERSION,
+        "",
+        "pub const Decomp = struct { cp: u21, start: u32, len: u8 };",
+        "",
+        "// All NFKD sequences concatenated, indexed by Decomp.start/.len.",
+        "pub const sequences = [_]u21{", *rows(flat, 8, lambda v: "0x%04X" % v), "};",
+        "",
+        "pub const decompositions = [_]Decomp{", *rows(decompositions, 1, decomp), "};",
+        "",
+        "// General-category Mn/Mc/Me codepoints, sorted; the Rust tokenizers' StripAccents removes all of category M*.",
+        "pub const marks = [_]u21{", *rows(marks, 8, lambda v: "0x%04X" % v), "};",
+        "",
+        "pub const Lower = struct { cp: u21, start: u32, len: u8 };",
+        "",
+        "// Full lowercase mappings concatenated (Rust char::to_lowercase semantics).",
+        "pub const lower_sequences = [_]u21{", *rows(lower_flat, 8, lambda v: "0x%04X" % v), "};",
+        "",
+        "pub const lowercases = [_]Lower{", *rows(lowercases, 1, decomp), "};",
+        "",
+        "// Canonical combining class ranges [first, last, ccc], unicodedata %s." % VERSION,
+        "pub const cccs = [_][3]u21{", *rows(cccs, 4, ccc), "};",
+    ]) + "\n"
+
+
+def formatted(text, zig):
+    """`text` grown through the Zig compiler's formatter, which is how the committed file is shaped."""
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "nfkd_data.zig"
+        path.write_text(text)
+        subprocess.run([zig, "fmt", str(path)], check=True, capture_output=True)
+        return path.read_text()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail if the committed file differs")
+    parser.add_argument("--zig", default="zig", help="the Zig compiler whose formatter shapes the output")
+    args = parser.parse_args()
+    if unicodedata.unidata_version != VERSION:
+        sys.exit("Python has Unicode %s; the Engram tables need %s" % (unicodedata.unidata_version, VERSION))
+    text = formatted(render(), args.zig)
+    if args.check:
+        sys.exit(0 if OUT.read_text() == text else "%s is stale; rerun tools/zig/nfkd_tables.py" % OUT.relative_to(ROOT))
+    OUT.write_text(text)
+    print("Wrote %s (Unicode %s)" % (OUT.relative_to(ROOT), VERSION))
+
+
+if __name__ == "__main__":
+    main()

zig/build/deepseek_v41.zig

@@ -0,0 +1,61 @@
+//! Experimental DS4.1 weight-loading qualification targets.
+const std = @import("std");
+
+pub fn weights(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+    metal: *std.Build.Module,
+) *std.Build.Step {
+    const host = b.addTest(.{ .root_module = b.createModule(.{
+        .root_source_file = b.path("zig/deepseek_v41_weights_checks.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+        .imports = &.{
+            .{ .name = "metal", .module = metal },
+        },
+    }) });
+    const step = b.step("test-deepseek-v41-weights", "V4.1 configuration, Engram table plans and resident weight staging");
+    step.dependOn(&b.addRunArtifact(host).step);
+    return step;
+}
+
+pub fn checks(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+    metal: *std.Build.Module,
+    sources: *std.Build.Module,
+    engine: *std.Build.Module,
+) struct { device: *std.Build.Step, reference: *std.Build.Step } {
+    const device = b.addTest(.{ .root_module = b.createModule(.{
+        .root_source_file = b.path("zig/deepseek_v41_checks.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+        .imports = &.{
+            .{ .name = "metal", .module = metal },
+            .{ .name = "kernel_sources", .module = sources },
+        },
+    }) });
+    const device_step = b.step("test-deepseek-v41", "Experimental DS4.1 EXL3, Engram, mHC and sparse attention on Metal");
+    device_step.dependOn(&b.addRunArtifact(device).step);
+    const reference = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("zig/deepseek_v41_reference_checks.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+            .imports = &.{
+                .{ .name = "tensorfold", .module = engine },
+                .{ .name = "metal", .module = metal },
+                .{ .name = "contract", .module = @import("kernel_contract.zig").module(b, target, optimize) },
+            },
+        }),
+        .filters = &.{"tests.deepseek_v41_reference."},
+    });
+    const reference_step = b.step("test-deepseek-v41-reference", "Independent CPU teacher-oracle arithmetic boundaries");
+    reference_step.dependOn(&b.addRunArtifact(reference).step);
+    return .{ .device = device_step, .reference = reference_step };
+}