Experimental DS4.1 resident Metal backend and qualification (draft-only)

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Each release's page on GitHub has its notes and measurements. See [the 1.0.0 release notes](RELEASE-NOTES-1.0.0.md) for the native binary's supported models and migration details.
 
+## Unreleased: experimental draft
+
+- Add an experimental DeepSeek V4.1 Flash resident Metal backend and independent
+  qualification runner. Whole-model numerical qualification remains failed:
+  retained eight-token NRMS 4.0960584769% against an unchanged 1% gate, despite
+  zero greedy disagreements. This is draft-only, not a qualified-model addition.
+  See the [implementation and qualification guide](docs/deepseek-v41.md).
+- Harden resident buffer/view admission, invalid-route error propagation, mixed DSML/XML
+  whole/SSE containment and tokenizer failure reporting. Bounded actual serving, tool
+  calls, unsupported-feature refusal, disconnect recovery and zero-I/O request intervals
+  are documented separately from the still-failed whole-model numerical gate.
+
 ## 1.0.7
 
 - Living Weights learns each fact into about ten new neurons inside the model's own shards, on Macs and on a GB10. Every MoE layer's shared expert gets a pocket of 64 extra neurons; a fact takes one at each of about ten layers, fired at the first row of the reply (a fact about you) or at the subject's last token where a question names it (a fact about someone or something), with outputs fitted through the model so the answers come back, thinking on too, while near misses, free writing about the subject and other answers stay as they were. Nothing the model had is changed, no adapter is loaded, and any MLX loader reads the folder as a slightly wider model. A fact is kept only when held-out wordings bring it back and nothing else moved; otherwise it is taken out and leaves nothing behind. Documents are learned fact by fact: the model finds the facts, names the organisation on each, and keeps only those whose names, numbers and words the text holds (a list holding others is read again), then writes questions that name their subject (rewriting ones that ask for it), and leaves a question another fact answers to that fact. Three personal facts taught one after another each came back on both test questions on an M5 Ultra, an M3 Ultra and a GB10, with no leaks and no drift, live and after a plain restart; a six-fact handbook gave 3 to 6 of 6 answers across six runs, and long documents about one subject are still weak (6 of 16 from a 21-fact handbook). Without learned facts, replies and speed equal 1.0.6's on both backends; a folder with 21 facts decodes about 16% slower on a Mac. `--slide` refuses a folder taught by 1.0.3 to 1.0.6, whose lessons sit in the shared experts the pocket widens; such folders still serve without it. It builds on the CUDA learner and the take-out rule of #591, #599 and #632. Thanks to @ZackSample and @ThinkOffApp.

README.md

@@ -30,6 +30,13 @@ curl -fsS http://127.0.0.1:8080/v1/chat/completions \
   -d '{"model":"local-model","messages":[{"role":"user","content":"Say hello in one sentence."}],"max_tokens":128,"temperature":0}'
 ```
 
+## DeepSeek V4.1 contributor draft
+
+The [experimental resident Metal implementation](docs/deepseek-v41.md) is draft-only,
+not a qualified model. Its retained independent whole-model comparison fails the
+unchanged 1% numerical gate. See the guide for prerequisites, exact reproduction
+inputs, limitations and the conditions required before readiness or merge.
+
 ## Living Weights (experimental)
 
 Living Weights teaches a running model new facts. Start a Nemotron 3.5 Lightning server with `--slide`, tell it

RUNBOOK.md

@@ -142,6 +142,20 @@ On one Mac, GLM loads only when its weights and caches fit in 70% of RAM, 179.2
 `GLM_LOAD_LIMIT_GB=N` sets that limit in GB, up to the GPU's recommended working set; a value that isn't a number above 0 stops the server.
 Past 70% of RAM the server warns at startup: a load that wires most of the RAM can stall macOS until its watchdog restarts the Mac, so run nothing else large beside it.
 
+## DeepSeek V4.1 Flash: experimental draft only
+
+The resident Metal implementation is not release-qualified. The retained independent
+eight-token whole-model comparison fails the unchanged 1% NRMS gate at 4.0960584769%;
+zero greedy disagreements do not clear it. Keep the proposal in draft.
+
+The [DS4.1 draft guide](docs/deepseek-v41.md) provides pinned checkpoint revisions,
+resident-memory admission, supported/unsupported features, exact teacher IDs, build,
+diagnostic and serving commands, and the readiness gates.
+The [historical evidence record](docs/deepseek-v41-evidence.md) preserves numerical
+counterexamples, rejected experiments, residency failures and limited speed receipts.
+Historical receipts are not verification of the current-main integration.
+
+
 ## Access, context and updates
 
 To accept remote clients, choose `--host 0.0.0.0` and configure `--api-key-file` with a file readable only by its owner.

THIRD_PARTY_NOTICES.md

@@ -76,6 +76,35 @@ checked bit for bit against ExLlamaV3's dequantization.
 
 Flash Next's optional int8 and int4 KV caches (`families/qwen4_exp/cuda/kvcache.py`) follow the cache quantization scheme of [ExLlamaV3](https://github.com/turboderp-org/exllamav3) `-cq 8` and `-cq 4` (MIT License, Copyright (c) 2025 Turboderp, text below): groups of 32, one fp16 absmax scale per group, the group rotated by a 32-point Hadamard, midpoint-grid codes, `compand_a == 0`. 8-bit stores each code as a signed int8 (`q - 128`). 4-bit stores two unsigned codes per byte, low nibble first (the same bits as ExLlamaV3's little-endian packing, a uint8 tensor rather than their uint32 words). Their dequantizer folds another `1/sqrt(32)` into the scale and applies the unnormalized butterfly on the way out; this cache applies the normalized H32 to the query and to the merged output instead, and leaves the stored codes rotated. Scales match their quantizer bit for bit. Reconstructed values agree within fp16/bf16 rounding (under 0.01 on random groups), not bit for bit. The quantizer and the attention dequant are written for TensorFold and checked against an independent reference of that arithmetic.
 
+## Native DeepSeek V4.1 and Metal EXL3
+
+The native `zig/src/families/deepseek_v41/` implementation and source Metal kernels 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 offline Engram token-map builder
+`tools/zig/dsv41_token_map.py` implements that revision's normalization, PCG64 multipliers and prime bucket layout.
+The independent CPU qualification arithmetic is in `zig/tests/deepseek_v41_reference/`.
+
+`zig/src/server/deepseek_v41_official.jinja` is the unchanged official chat template from the same revision;
+its text, token-ID and tool-decoding fixtures are generated from DeepSeek's official encoder.
+The MIT license text below applies to these adaptations and the template.
+
+The bounded `zig/src/families/deepseek_v41/fixtures/hc_attention_rms.json` regression
+contains model-derived numeric rows and independently captured operator boundaries from
+that pinned MIT-licensed checkpoint. Its embedded provenance identifies the token, layer,
+source revision, encodings and target columns; it is not a full model shard or trace.
+`zig/tests/deepseek_v41_reference/rope_frequencies.json` contains 64 formula-derived
+frequency values with extraction provenance. The draft's historical evidence is labeled
+separately from current-branch verification.
+The RMS mean-boundary test uses a constructed BF16 row `[3, 0, ...]` of width 5,120
+and a uniform constructed FP32 weight `0x3c65de29`, not a captured model coefficient.
+Its expected BF16 tie was exercised through the pinned official `RMSNorm.forward`
+on PyTorch `2.13.0a0+9186a08b2c.nv26.07` / CUDA 13.3. It tests an operator boundary,
+not source-coefficient injection into whole-model qualification.
+
+The native `zig/src/core/exl3_projection*.zig` decoder and `zig/kernels/metal/core/exl3_projection.metal`
+separately implement ExLlamaV3's format and codebooks under the Turboderp attribution above.
+No captured CUDA/Triton binary kernel assets, full model shards or binary traces are bundled.
+
 ## Vendored code and weights
 
 `src/tensorfold/drafters/vendor/z_lab_dflash/model_mlx.py` is the unmodified `dflash/model_mlx.py` from

build.zig

@@ -5,6 +5,7 @@ const dist_build = @import("zig/build/dist.zig");
 const qwen27_build = @import("zig/build/qwen27.zig");
 const hip_build = @import("zig/build/hip.zig");
 const grammar_build = @import("zig/build/grammar.zig");
+const dsv41_build = @import("zig/build/deepseek_v41.zig");
 
 comptime {
     const required = std.mem.trim(u8, @embedFile(".zig-version"), "\r\n");
@@ -207,7 +208,10 @@ fn nativeServer(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.b
         .link_libc = true,
         .imports = &.{ .{ .name = "engine_api", .module = api }, .{ .name = "tokenizer", .module = tokenizer }, .{ .name = "template", .module = template } },
     });
-    test_step.?.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = server_tests })).step);
+    const server_run = b.addRunArtifact(b.addTest(.{ .root_module = server_tests }));
+    test_step.?.dependOn(&server_run.step);
+    b.step("test-server", "HTTP routes, official templates and tool parsing without model weights")
+        .dependOn(&server_run.step);
     // the parse half's tests, as their own test binary (zig/src/server/tool_parse_test.zig)
     const tool_parse_tests = b.addTest(.{ .root_module = b.createModule(.{ .root_source_file = b.path("zig/src/server/tool_parse_test.zig"), .target = target, .optimize = .Debug, .link_libc = true, .imports = &.{ .{ .name = "engine_api", .module = api }, .{ .name = "tokenizer", .module = tokenizer }, .{ .name = "template", .module = template } } }) });
     test_step.?.dependOn(&b.addRunArtifact(tool_parse_tests).step);
@@ -381,6 +385,7 @@ fn metalTargets(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.b
     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);
+    dsv41_build.checks(b, target, optimize, metal, sources, engine);
     const pack_cache_cases = b.addTest(.{ .root_module = b.createModule(.{
         .root_source_file = b.path("zig/flashnext_pack_cache_cases.zig"),
         .target = target,
@@ -392,6 +397,8 @@ fn metalTargets(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.b
     test_step.dependOn(&pack_cache_run.step);
     const engine_programs = [_]struct { name: []const u8, path: []const u8, about: []const u8, c_source: ?[]const u8 = null }{
         .{ .name = "tf-qwen35-check", .path = "zig/tests/qwen35_check.zig", .about = "Qwen3.5-2B checkpoint and native operations" },
+        .{ .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-exl3-bench", .path = "zig/exl3_projection_bench.zig", .about = "Actual GPU codebook parity and real-shape EXL3 decode performance" },
         .{ .name = "tf-qwen35-forward", .path = "zig/tests/qwen35_forward.zig", .about = "Qwen3.5-2B native teacher-forced logits" },
         .{ .name = "tf-qwen35-exact", .path = "zig/tests/qwen35_exact.zig", .about = "Qwen3.5-2B forward and committed-state exactness" },
         .{ .name = "tensorfold", .path = "zig/src/main.zig", .about = "The native engine's command line" },