DeepSeek V4.1: fp64 reference tests for the Engram hash, gather and gate

.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

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"
+}

tools/zig/lean_check.py

@@ -12,11 +12,10 @@
            ".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. The Unicode table files stay exempt from the length check only.
 GENERATOR_OUTPUT = (
-    "zig/src/core/tokenizer/nfkd_data.zig",
     "zig/src/families/flashnext/roles_gen.zig",
     "zig/kernels/metal/flashnext/sources_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 };
+}

zig/build/metal_targets.zig

@@ -155,6 +155,10 @@ pub fn metalTargets(b: *std.Build, target: std.Build.ResolvedTarget, optimize: s
     const kernels_mod = embedded(b, lib, "tensorfold.metallib");
     counters_build.targets(b, target, optimize, metal, mods.sources, test_step);
 
+    // DeepSeek V4.1: the operator qualification steps registered beside the other families'.
+    const dsv41_build = @import("deepseek_v41.zig");
+    test_step.dependOn(dsv41_build.weights(b, target, optimize, metal));
+
     // The engines registry: the families this platform's binaries serve; the CLI reads it for models/info/pull.
     const api = b.createModule(.{ .root_source_file = b.path("zig/src/core/engine_api.zig"), .target = target, .optimize = optimize, .link_libc = true, .imports = &.{.{ .name = "lanes", .module = mods.lanes }} });
     const engines = b.createModule(.{
@@ -247,6 +251,11 @@ pub fn metalTargets(b: *std.Build, target: std.Build.ResolvedTarget, optimize: s
     b.getInstallStep().dependOn(&b.addInstallFile(packed_lib, "lib/nemotron_packed.metallib").step);
     sources.addImport("nemotron_packed_metallib", embedded(b, packed_lib, "nemotron_packed.metallib"));
     const engine = mods.engine;
+    {
+        const dsv41 = dsv41_build.checks(b, target, optimize, metal, sources, engine);
+        test_step.dependOn(dsv41.device);
+        test_step.dependOn(dsv41.reference);
+    }
     // FlashNext's CPU contracts, with the family module's imports so the replay graph type-checks
     const flash_host = b.addTest(.{ .root_module = b.createModule(.{
         .root_source_file = b.path("zig/flashnext_host.zig"),

zig/deepseek_v41_checks.zig

@@ -0,0 +1,13 @@
+//! Source-built V4.1 operator qualification; real Metal execution, no checkpoint needed.
+test {
+    _ = @import("src/core/exl3_projection_gpu_test.zig");
+    _ = @import("src/families/deepseek_v41/engram.zig");
+    _ = @import("src/families/deepseek_v41/csa2.zig");
+    _ = @import("src/families/deepseek_v41/ops_check.zig");
+    _ = @import("src/families/deepseek_v41/load.zig");
+    _ = @import("src/families/deepseek_v41/index_precision_test.zig");
+    _ = @import("src/families/deepseek_v41/config.zig");
+    _ = @import("src/families/deepseek_v41/profiler.zig");
+    _ = @import("src/core/gpu_counters.zig");
+    _ = @import("src/core/expert_groups.zig");
+}

zig/deepseek_v41_reference_checks.zig

@@ -0,0 +1,16 @@
+//! Independent CPU arithmetic boundaries used by the resident-checkpoint teacher oracle.
+test {
+    _ = @import("tests/deepseek_v41_reference/projection.zig");
+    _ = @import("tests/deepseek_v41_reference/math.zig");
+    _ = @import("tests/deepseek_v41_reference/attention_math.zig");
+    _ = @import("tests/deepseek_v41_reference/qualify.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_hc_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_hc_split_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_hc_amplify_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_csa2_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_csa2_pack_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_csa2_sparse_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_csa2_rope_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_csa2_index_fp64.zig");
+    _ = @import("tests/deepseek_v41_reference/operator_engram_fp64.zig");
+}