perf: accelerate longhaul prompt loading

docs/longhaul.md

@@ -36,3 +36,25 @@ MTP/speculative decoding, tensor validation during loading, vocabulary-only load
 The cache budget covers the compact routed-expert tensors. It does not include dense weights, attention weights, the KV cache, graph allocations, or the temporary buffer used for one expert read. Disk reads bypass the macOS unified file cache where supported, avoiding a second long-lived copy of streamed weights in system RAM.
 
 This implementation synchronizes at each routed MoE layer to discover the selected experts, populate missing cache slots, and continue execution with cache-local expert IDs. Storage speed and expert reuse therefore have a large effect on generation speed.
+
+Expert IDs are planned as a batch at each synchronization point. Experts already
+needed by that batch are protected from eviction, duplicate IDs are loaded only
+once, and independent expert slices are read concurrently on shared-memory Metal
+devices. Private Metal buffers use a staged fallback.
+
+## Benchmarking prompt processing
+
+`llama-bench` accepts the longhaul load mode and cache budget:
+
+```sh
+llama-bench \
+    --model /path/to/model.gguf \
+    --load-mode longhaul \
+    --longhaul-cache 2 \
+    --n-gpu-layers 99 \
+    --n-prompt 2048 \
+    --n-gen 0
+```
+
+Use `--no-warmup --repetitions 1` in separate processes to measure a cold expert
+cache. Leave warmup enabled to measure steady-state cache reuse.