perf(dsv41): opt-in neighbor RDMA for TP4 physical rings

README.md

@@ -7,6 +7,7 @@
 > replies equal the two-node family's token for token in our gates), image input, up to 1,048,576 tokens a request in
 > a shared 2,097,152-position window with kept-prompt reuse, and exact DSpark speculative decoding. Launch, measured
 > numbers, gates and the kernel kit are in the recipe, [bertholomus/deepseek-v4.1-tensorfold-tp4-4xgb10](https://github.com/bertholomus/deepseek-v4.1-tensorfold-tp4-4xgb10).
+> An optional [neighbor transport](docs/recipes/deepseek-v41-neighbor.md) supports adjacent-edge RDMA on a physical ring.
 > `tools/dsv41-zig/inputs/` makes each node's weight file and token map from the checkpoint; `tools/dsv41-zig/kit/`
 > makes and checks the kit's generated files. See NOTICE and ATTRIBUTION.md. This fork is not affiliated with or
 > endorsed by DeepSeek, NVIDIA, the TensorFold authors or Mia-AiLab.

docs/receipts/dsv41-neighbor-hardware/README.md

@@ -0,0 +1,112 @@
+# TP4 neighbor transport: four-host hardware qualification
+
+Tested 2026-10-20 UTC at code commit
+`660bf9aba19b7ac42ea7ca1b4e26c50b4850bce1`, based on
+`deepseek-v41-zig-tp4` at `b65c8b92d2403dfdefccf15a3b23ba609a4553e2`.
+Subsequent receipt-only changes do not change the tested engine code.
+
+We do not have a network switch. Four GB10 hosts form a physical ring, with two
+PCI-domain RoCE rails per adjacent edge and GID 3. This was the fastest ring
+implementation selected in our experiments. These results are **not a direct
+performance comparison with the target branch or with a switched/full-mesh
+fabric**. The attempted target-branch comparison was discontinued; its partial
+measurements are not included here.
+
+## Build and runtime
+
+Both native executables were built with Zig 0.17.0, Linux/aarch64 glibc 2.28,
+fast optimization, SM121 and the existing CUDA fatbins. The build used the pinned
+NGC image `nvcr.io/nvidia/pytorch@sha256:7531d90bcbe0e43e1f7363029c7e145ce90eebeb494a7b4695fdba0329d7c3c3`:
+
+```sh
+zig build native neighbor-lanes neighbor-probe \
+  -Dtarget=aarch64-linux-gnu.2.28 -Doptimize=fast -Dsm=121 -j2 -Dfatbins=/fatbins
+```
+
+`neighbor-lanes` and `neighbor-probe` were external qualification build targets,
+not release targets added to this branch. The latter exposes a C ABI around the
+production code for a weight-free Python/CUDA driver. Only build target additions
+and the new adapter were applied to the source archive; all 1,200 tracked files
+under `zig/src` were verified byte-identical to the tested commit. The native
+executables have no test-path substitutions. Binary digests and per-rank OS,
+driver and kernel versions are in [summary.json](summary.json).
+
+Model: DeepSeek-V4.1-Flash-1017 EXL3 revision
+`a2f91e2794923d0beebebe0d267fb3468eaf0b65`, original Engram revision
+`1bae0e1088993b9b82de08f59de5be5a34e42170`, DSpark.
+Effective server arguments: `--context 1048576 --parallel 16 --max-tokens 32768`,
+shared window 2097152, round rows 48, graphs enabled, served-depth policy `solo`.
+`TF_DS_NEIGHBOR_RDMA=1` and `TF_DS_NEIGHBOR_GID_INDEX=3` on all four ranks
+(the GID default is 5); no per-optimization switches or stock
+`TF_RDMA_DEVICES`. NCCL 2.30.7 with the existing switchless-routing patches,
+IB network, Ring algorithm, four channels, and LL128 excluded. No forced-tool,
+model arithmetic, or server patches were added to the tested commit.
+
+## Passed checks
+
+- **56 rank/shape cases:** independent NCCL all-gather byte oracle, output guards,
+  changing-input CUDA graph replay, and mixed operation graphs on all four ranks.
+  The adapter calls production pair/quarter/diagonal operations and the full
+  gather helper used by Markov. Sizes include the 512 KiB cutoff and alignment
+  fallbacks. Four-rank startup mode agreement also executed successfully.
+- **9 short model replies:** three prompts through serial, drafted and concurrent
+  paths, 64 generated tokens each; exact token IDs and UTF-8 agree. All nine
+  also match the original commit’s replies for identical requests.
+- **24 benchmark replies:** four requests × six timed bursts, 256 tokens each;
+  UTF-8 agrees across repetitions for each request.
+- **11 longer-prompt replies:** four approximately 8K-token prompts (requested
+  lengths 8192), plus a seeded-sampling case, burst/solo replay and one serial
+  reference. All 5/5 burst/solo cases match exact token IDs; drafting matches
+  serial. All four recall markers were found in both greedy paths. Solo replays
+  reported 6144 cached tokens each. This exercises prompt chunking and retained
+  prefixes, not the full configured context.
+- **Cancellation:** disconnect after an active content chunk, then exact equality
+  of the next serial and drafted 64-token replies.
+- **Sustained serving:** 90-second four-stream run, 62 requests, no worker errors.
+
+Transport timings below are complete-operation candidate latencies: slowest
+rank's mean of two measurement rounds. They are not a target-branch comparison.
+
+| Diagonal payload | Latency |
+|---|---:|
+| 8.75 KiB | 18.34 µs |
+| 52.5 KiB | 27.91 µs |
+| 140 KiB | 44.79 µs |
+| 420 KiB | 82.12 µs |
+
+[transport.json](transport.json) contains every candidate rank/shape result.
+
+## Serving measurements
+
+The recorded workload is in [workloads.json](workloads.json). Greedy decoding,
+four streams and 256-token maximum outputs were used. Set-a is the same public
+prose/code/structured-output workload used during transport selection. One warmup
+preceded six measured bursts; steady admission used set-a for 30 seconds. The
+separate 90-second sustained run used set-b. Different workloads are not directly
+comparable, and these short measurements are not confidence estimates.
+
+| Workload | Aggregate tokens/s | Detail |
+|---|---:|---|
+| Set-a four-stream bursts | **133.11** | Mean of six; range 132.49–133.52 |
+| Set-a steady admission | **149.00** | 30 seconds, 19 requests |
+| Set-b sustained | **170.20** | 90 seconds, 62 requests; TTFT p50 0.166 s, p95 0.262 s |
+
+The suite repeats the original commit’s workloads on the same ring. Historical
+burst/steady/sustained rates were 132.63/148.83/169.77 tok/s; these were not
+alternating A/B runs, and the sub-percent differences do not establish a speedup.
+
+## Host checks and limits
+
+A fresh `zig build test-dsv41-neighbor --summary all`
+passed **15/15**. `zig build test test-golden -Dcpu=apple_m1 --summary all` again
+reported the inherited macOS `std.c.SO.BUSY_POLL` compile blocker; the frozen
+corpus remained 309/319 equal, ten known differences, zero unexpected. The full
+host command is not reported as a pass. See the [host receipt](../dsv41-neighbor-host/README.md)
+for the Linux node build, local CI checks and inherited failures.
+
+Full-1M quality, 160K cold prefill, 16-way sustained load, fault injection,
+restart/reboot and long-duration reliability were not tested on this consolidated
+branch. Unequal-width diagonal forwarding has host call-sequence coverage; this
+GPU probe does not claim exhaustive model shapes or distributed failure handling.
+No target-branch speedup is claimed. The previously deployed build was resumed
+after successful bounded qualification; the PR was not deployed as a replacement.

docs/receipts/dsv41-neighbor-hardware/summary.json

@@ -0,0 +1,160 @@
+{
+  "tested_commit": "660bf9aba19b7ac42ea7ca1b4e26c50b4850bce1",
+  "target_commit": "b65c8b92d2403dfdefccf15a3b23ba609a4553e2",
+  "direct_target_comparison": false,
+  "reason": "No network switch is available; these are measurements of the fastest implementation selected in our ring experiments, not a direct target-branch or switched-fabric comparison.",
+  "comparison_scope": "Repeated original candidate workloads on the same fleet; historical comparison, not alternating A/B.",
+  "hardware": {
+    "gpu": "NVIDIA GB10",
+    "architecture": "aarch64",
+    "ranks": [
+      {
+        "rank": 0,
+        "kernel": "6.17.0-1029-nvidia",
+        "ubuntu": "24.04.4",
+        "driver": "580.173.02",
+        "management_mbps": 10000
+      },
+      {
+        "rank": 1,
+        "kernel": "6.17.0-1032-nvidia",
+        "ubuntu": "24.04.3",
+        "driver": "580.173.02",
+        "management_mbps": 10000
+      },
+      {
+        "rank": 2,
+        "kernel": "6.17.0-1022-nvidia",
+        "ubuntu": "24.04.4",
+        "driver": "580.159.03",
+        "management_mbps": 2500
+      },
+      {
+        "rank": 3,
+        "kernel": "6.17.0-1022-nvidia",
+        "ubuntu": "24.04.4",
+        "driver": "580.159.03",
+        "management_mbps": 2500
+      }
+    ],
+    "nccl": "2.30.7, patched",
+    "nccl_sha256": "1cdf5f3e2d617d5c07a87903eb8849d5bd7758f6c900455d613a2e0eb289d63e"
+  },
+  "binaries": {
+    "tensorfold-native": "6358c0a5c84923cebe3220ce2eb00d2210c93272921005d98b7eb82cbe5a239b",
+    "libtf-neighbor.so": "82897cfc01cf3aede02077a0ab7cc142f38828fc5ae11e4e762e9c6252d2347f",
+    "probe.py": "8d1900817f5e8b240c4be327fef72ca2f5bd187701c109f64007cc34b9d4dba2",
+    "tf-dsv41-lanes": "83084a74f05fa50a7680b433194f37eec999ab158dbf4446d50c18f476264727",
+    "transport_base.py": "10a908eeaca9959b501e1652c095ba0d4334d74a58861aac2ee65007d6acf1c7",
+    "direct.py": "df7e5c052010da1f3f63e54c1c4f33f6853ed282d20dea2fa8e96c69473d3a80"
+  },
+  "production_source": {
+    "commit": "660bf9aba19b7ac42ea7ca1b4e26c50b4850bce1",
+    "files": 1200,
+    "all_equal": true
+  },
+  "gid_index": 3,
+  "default_gid_index": 5,
+  "transport": {
+    "rank_shape_cases": 56,
+    "pass_bytes_and_graphs": true,
+    "latencies": [
+      {
+        "bytes": 8960,
+        "slowest_rank_mean_us": 18.343599885702133
+      },
+      {
+        "bytes": 53760,
+        "slowest_rank_mean_us": 27.905799448490143
+      },
+      {
+        "bytes": 143360,
+        "slowest_rank_mean_us": 44.79059875011444
+      },
+      {
+        "bytes": 430080,
+        "slowest_rank_mean_us": 82.11579918861389
+      }
+    ]
+  },
+  "exact_tokens": {
+    "prompts": 3,
+    "paths": 3,
+    "tokens_per_reply": 64,
+    "replies": 9,
+    "pass_test": true,
+    "also_equal_to_original_commit": true
+  },
+  "long_context": {
+    "burst_equal_to_solo": 5,
+    "of": 5,
+    "drafted_equals_serial": true,
+    "needles_found_burst": 4,
+    "needles_found_solo": 4,
+    "prompts": 4,
+    "burst_s": 17.5,
+    "solo_s": 7.8,
+    "serial_s": 1.8,
+    "cached_tokens_solo": [
+      6144,
+      6144,
+      6144,
+      6144,
+      6144
+    ]
+  },
+  "cancellation_pass": true,
+  "burst": {
+    "streams": 4,
+    "tokens": 256,
+    "warmups": 1,
+    "repetitions": 6,
+    "mean_aggregate_tps": 133.10816911985555,
+    "min_aggregate_tps": 132.48854455631133,
+    "max_aggregate_tps": 133.52409085662865,
+    "exact_utf8_replies": 24
+  },
+  "steady": {
+    "streams": 4,
+    "seconds": 30,
+    "max_tokens": 256,
+    "set": "a",
+    "requests": 19,
+    "aggregate_tps": 149.0,
+    "per_stream_tps_p50": 48.066,
+    "per_stream_tps_p95": 61.506,
+    "per_stream_tps_p05": 23.011,
+    "ttft_s_p50": 0.196,
+    "ttft_s_p95": 0.429
+  },
+  "sustained": {
+    "streams": 4,
+    "seconds": 90,
+    "max_tokens": 256,
+    "set": "b",
+    "requests": 62,
+    "aggregate_tps": 170.2,
+    "per_stream_tps_p50": 51.742,
+    "per_stream_tps_p95": 83.059,
+    "per_stream_tps_p05": 25.56,
+    "ttft_s_p50": 0.166,
+    "ttft_s_p95": 0.262
+  },
+  "original_commit_comparison": {
+    "burst": {
+      "original": 132.6345814307147,
+      "current": 133.10816911985555,
+      "change_percent": 0.3570619999945013
+    },
+    "steady": {
+      "original": 148.83,
+      "current": 149.0,
+      "change_percent": 0.11422428273868412
+    },
+    "sustained": {
+      "original": 169.77,
+      "current": 170.2,
+      "change_percent": 0.2532838546268401
+    }
+  }
+}