feat: trace DeepSeek V2-Lite real routes

experiments/deepseek/README.md

@@ -0,0 +1,56 @@
+# DeepSeek real-weight execution probes
+
+The probes in this directory use official DeepSeek artifacts and keep their
+scope deliberately narrower than a full-model benchmark.
+
+## DeepSeek-V2-Lite truncated trace
+
+`v2_lite_trace.py` executes layers 0–6 from the official BF16 checkpoint. Those
+seven layers are fully contained in shard 1; layer 7 is split across shards 1
+and 2 and is therefore outside the default evidence boundary.
+
+Pinned model:
+
+```text
+deepseek-ai/DeepSeek-V2-Lite@604d5664dddd88a0433dbae533b7fe9472482de0
+```
+
+Required Python stack:
+
+```text
+torch==2.11.0+cu128
+transformers==4.41.2
+safetensors==0.8.0
+```
+
+The 2024 remote code does not import under Transformers 5.5 because
+`is_torch_fx_available` was removed. The probe imports the official files as a
+read-only local package; it does not patch the model source.
+
+Download the metadata, tokenizer, remote code, index, and first shard with the
+Hugging Face CLI, then run:
+
+```bash
+python experiments/deepseek/v2_lite_trace.py \
+  --artifact-dir /path/to/deepseek-v2-lite \
+  --output src/data/deepseek-v2-lite-trace.json
+```
+
+The result contains:
+
+- real tokenizer pieces and model-derived hidden states;
+- the actual `[B,T,576]` MLA compressed projection at each executed layer;
+- the expanded key/value tensors stored by the Hugging Face eager cache;
+- token-level top-6 routed expert IDs and weights for six MoE layers;
+- per-layer and per-prompt expert-load summaries;
+- explicit boundaries against global load, expert semantics, training traces,
+  full-model generation, and production serving claims.
+
+Run the probe twice and compare deterministic evidence while excluding timing:
+
+```bash
+python experiments/deepseek/compare_v2_lite_traces.py \
+  --first /path/to/trace-1.json \
+  --second /path/to/trace-2.json \
+  --output src/data/deepseek-v2-lite-trace-repro.json
+```