[Superseded by #317] fix: distributed CUDA span cover

[hexxyan]

Summary

Distributed CUDA workers with --layers 21:output should only access the pages covering their assigned layer spans (~78 GiB), not the entire GGUF mmap (~150 GiB for Q4). Currently all direct/full-file fallback paths assume the full model is accessible, causing OOM on 128 GB DGX Spark workers.

Root Cause

ds4_gpu_set_model_map_spans() set g_model_registered_size to the full file size. Every fallback path (cuda_model_range_ptr, cuda_model_range_is_cached, cuda_model_direct_fallback_ptr, cuda_model_copy_chunked, Q2 tail expansion) used this to assume full-model access.

For Q2 that "works", it still registered 80.76 GiB when only 41 GiB was the slice. For Q4, the 150 GiB full file exceeds the 128 GB worker memory.

Fix

New state: span cover offset/end (not just a flag)

g_model_span_cover_offset  // page-aligned start of span cover
g_model_span_cover_end     // page-aligned end of span cover
g_model_span_only          // 1 when initialized from _spans

New helper: cuda_model_range_in_span_cover(offset, bytes)

Returns true iff [offset, offset+bytes) falls within [cover_offset, cover_end). When not in span-only mode, always returns true. Includes overflow guard.

All guarded paths

Function	What was guarded
cuda_model_range_ptr	g_model_device_owned/g_model_registered fallback, g_model_hmm_direct fallback, DS4_CUDA_DIRECT_MODEL fallback
cuda_model_range_is_cached	Early return when registered/hmm_direct — now also checks span cover
cuda_model_direct_fallback_ptr	Now takes bytes param and checks span cover (called from fd cache path)
cuda_model_copy_chunked	Early return when registered — now skips when span_only
cuda_model_range_register_mapped	Q2 tail expansion heuristic — now skips when span_only

Cleanup

Both cuda_model_set_host_map and ds4_gpu_cleanup reset all span-only state.

New log output

ds4: CUDA span cover 78.21 GiB of 150.00 GiB model (48 spans, offset 72.00 GiB)

Testing

• CUDA compile verified: nvcc -arch=sm_90 compiles ds4_cuda.cu cleanly (zero warnings, zero errors, 5.3 MB ELF object) via nvidia/cuda:13.0.0-devel-ubuntu24.04 Docker image
• Non-CUDA build is unaffected
• Still needs: GB10/Q4 distributed e2e validation with --layers to confirm the fix resolves the OOM

Refs: #293

[hexxyan]

Superseded by a clean PR (force-push history cleanup).

[hexxyan]

Superseded by #317 (clean branch, same code).