DeepSeek V4.1: the family — configuration, Engram tables, resident weights and the Metal operators

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

@@ -208,11 +208,10 @@ pub fn build(b: *std.Build) void {
 }
 
 /// The native Metal server build is owned by the shared Metal target module.
+const metalTargets = metal_build.metalTargets;
 const nativeServer = metal_build.nativeServer;
 
 /// macOS: the metallib, the Metal runtime's test programs and the engine over Metal.
-const metalTargets = metal_build.metalTargets;
-
 /// The server and distribution use the same embedded-source Metal engine.
 const metalEngineModules = metal_build.metalEngineModules;
 

tools/zig/lean_check.py

@@ -12,7 +12,7 @@
            ".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_OUTPUT = (

zig/build/deepseek_v41.zig

@@ -0,0 +1,51 @@
+//! Experimental DS4.1 weight-loading qualification targets.
+const std = @import("std");
+
+fn withCore(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, root: []const u8, core: *std.Build.Module, imports: []const std.Build.Module.Import) *std.Build.Module {
+    var list: std.ArrayList(std.Build.Module.Import) = .empty;
+    list.append(b.allocator, .{ .name = "core", .module = core }) catch @panic("oom");
+    list.appendSlice(b.allocator, imports) catch @panic("oom");
+    return b.createModule(.{ .root_source_file = b.path(root), .target = target, .optimize = optimize, .link_libc = true, .imports = list.items });
+}
+
+pub fn weights(
+    b: *std.Build,
+    target: std.Build.ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+    metal: *std.Build.Module,
+    core: *std.Build.Module,
+) *std.Build.Step {
+    const host = b.addTest(.{ .root_module = withCore(b, target, optimize, "zig/deepseek_v41_weights_checks.zig", core, &.{
+        .{ .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,
+    core: *std.Build.Module,
+) struct { device: *std.Build.Step, reference: *std.Build.Step } {
+    const device = b.addTest(.{ .root_module = withCore(b, target, optimize, "zig/deepseek_v41_checks.zig", core, &.{
+        .{ .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 = withCore(b, target, optimize, "zig/deepseek_v41_reference_checks.zig", core, &.{
+            .{ .name = "tensorfold", .module = engine },
+            .{ .name = "metal", .module = metal },
+        }),
+        .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/dsv41_shared.zig

@@ -2,12 +2,16 @@ const std = @import("std");
 pub fn module(b: *std.Build, target: std.Build.ResolvedTarget, file: []const u8) *std.Build.Module {
     return moduleAt(b, target, .Debug, file);
 }
-pub fn moduleAt(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, file: []const u8) *std.Build.Module {
+pub fn coreModule(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) *std.Build.Module {
     const tok = b.createModule(.{ .root_source_file = b.path("zig/src/core/tokenizer/tokenizer.zig"), .target = target, .optimize = optimize, .link_libc = true });
-    const core = b.createModule(.{ .root_source_file = b.path("zig/src/core/root.zig"), .target = target, .optimize = optimize, .link_libc = true });
+    const core = b.createModule(.{ .root_source_file = b.path("zig/dsv41_core_family.zig"), .target = target, .optimize = optimize, .link_libc = true });
+    core.addImport("metal", b.createModule(.{ .root_source_file = b.path("zig/src/metal/metal.zig"), .target = target, .optimize = optimize, .link_libc = true }));
     core.addImport("gpu_memory", @import("gpu_memory.zig").module(b, target));
     core.addImport("tokenizer", tok);
-    return b.createModule(.{ .root_source_file = b.path(b.fmt("zig/src/families/deepseek_v41/{s}", .{file})), .target = target, .optimize = optimize, .link_libc = true, .imports = &.{.{ .name = "core", .module = core }} });
+    return core;
+}
+pub fn moduleAt(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, file: []const u8) *std.Build.Module {
+    return b.createModule(.{ .root_source_file = b.path(b.fmt("zig/src/families/deepseek_v41/{s}", .{file})), .target = target, .optimize = optimize, .link_libc = true, .imports = &.{.{ .name = "core", .module = coreModule(b, target, optimize) }} });
 }
 pub fn steps(b: *std.Build) void {
     const host = b.addTest(.{ .root_module = module(b, b.graph.host, "shared_test.zig") });

zig/build/metal_targets.zig

@@ -1,5 +1,6 @@
 //! Metal build targets and their shared source/library/module construction.
 const std = @import("std");
+const dsv41_build = @import("deepseek_v41.zig");
 const builtin = @import("builtin");
 const qwen27_build = @import("qwen27.zig");
 const core_checks = @import("core_checks.zig");
@@ -170,6 +171,7 @@ pub fn metalTargets(b: *std.Build, target: std.Build.ResolvedTarget, optimize: s
     const programs = [_]struct { name: []const u8, path: []const u8, about: []const u8 }{
         .{ .name = "tf-metal-tests", .path = "zig/tests/gpu_tests.zig", .about = "GPU runtime tests" },
         .{ .name = "tf-dispatch-bench", .path = "zig/tests/dispatch_bench.zig", .about = "Dispatch boundary benchmark" },
+        .{ .name = "tf-dsv41-run", .path = "zig/deepseek_v41_run.zig", .about = "Full-resident DeepSeek V4.1 admission, teacher-forced logits, chunk seams and decode timing" },
         .{ .name = "tf-kernel-exact", .path = "zig/tests/kernel_exact.zig", .about = "Bit-exact check of a kernel against an MLX oracle case" },
     };
     for (programs) |p| {
@@ -276,6 +278,12 @@ pub fn metalTargets(b: *std.Build, target: std.Build.ResolvedTarget, optimize: s
     const load_admission_run = b.addRunArtifact(load_admission_cases);
     b.step("test-flashnext-load-admission", "CPU-only Flash Next runtime quantization admission").dependOn(&load_admission_run.step);
     test_step.dependOn(&load_admission_run.step);
+    // The family reaches core through `@import("core")`; this facade owns exactly the files it names.
+    const core_root = b.createModule(.{ .root_source_file = b.path("zig/dsv41_core_family.zig"), .target = target, .optimize = optimize, .link_libc = true, .imports = &.{ .{ .name = "gpu_memory", .module = @import("gpu_memory.zig").module(b, target) }, .{ .name = "tokenizer", .module = b.createModule(.{ .root_source_file = b.path("zig/src/core/tokenizer/tokenizer.zig"), .target = target, .optimize = optimize, .link_libc = true }) }, .{ .name = "metal", .module = metal } } });
+    test_step.dependOn(dsv41_build.weights(b, target, optimize, metal, core_root));
+    const dsv41 = dsv41_build.checks(b, target, optimize, metal, mods.sources, mods.engine, core_root);
+    test_step.dependOn(dsv41.device);
+    test_step.dependOn(dsv41.reference);
     const pack_cache_cases = b.addTest(.{ .root_module = b.createModule(.{
         .root_source_file = b.path("zig/flashnext_pack_cache_cases.zig"),
         .target = target,

zig/deepseek_v41_checks.zig

@@ -0,0 +1,14 @@
+//! Source-built V4.1 operator qualification; real Metal execution, no checkpoint needed.
+test {
+    _ = @import("core").exl3_projection_gpu_test;
+    _ = @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/metal_model.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("core").gpu_counters;
+    _ = @import("core").expert_groups;
+}

zig/deepseek_v41_reference_checks.zig

@@ -0,0 +1,7 @@
+//! 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");
+}