docs(huggingface): document safetensors header padding bug + repair utility

[lockewerks]

Summary

The model.safetensors file currently published at https://huggingface.co/ruvnet/wifi-densepose-pretrained has a malformed header that strict safetensors readers (Rust safetensors crate, Candle, safetensors.torch.load_file via its Rust binding) reject:

SafetensorError: trailing characters at line 1 column 1462

Lenient readers (custom JSON parsers that strip trailing NULs, e.g. scripts/export-onnx.py and the JS SafeTensorsReader in vendor/ruvector) accept it, which is why this hasnt surfaced until someone tried loading the bundle from strict Rust.

Root cause

SafeTensorsWriter.build() in vendor/ruvector/npm/packages/ruvllm/src/export.js:95-105 (vendored from ruvnet/ruvector):

• Zero-initialises the header buffer
• Copies in the JSON
• Pads to the next 8-byte alignment boundary
• Never overwrites the padding zone, so it stays \x00 instead of the spec-required 0x20 (space)

Three trainers consume this writer: train-wiflow.js:933, train-ruvllm.js:1541, train-camera-free.js:2276. The Python writer in scripts/train-count.py::write_safetensors is unaffected (it sizes the JSON exactly with no padding, which is spec-compliant). The HF publisher (scripts/publish-huggingface.py) only uploads bytes — it doesnt touch them.

What this PR ships

This PR cannot fix the upstream ruvnet/ruvector writer (separate repo, vendored as a submodule here). Instead:

• docs/huggingface/SAFETENSORS-HEADER-BUG.md — full byte-level analysis (offsets, declared header length 1464 vs JSON termination at 1461, three NUL padding bytes), spec citation, repro snippet using safetensors::SafeTensors::deserialize, follow-up plan
• scripts/fix-safetensors-header.py — user-side repair utility. Opens a .safetensors file, locates the header zone via the leading u64 length prefix, detects NUL bytes after the closing JSON brace, rewrites those bytes in-place as ASCII spaces. Tensor data byte-preserved. Idempotent. Supports --dry-run and multiple file arguments.
• CHANGELOG.md — [Unreleased] entry under Known Issues + Added blocks
• docs/user-guide.md — Hugging Face model section now warns about the broken header and points readers at the repair utility until the upstream republish lands

Follow-ups (separate PRs needed)

1. In ruvnet/ruvector: fix SafeTensorsWriter.build() to pad with 0x20 (or drop alignment padding entirely). One-line change.
2. In this repo: bump the vendor/ruvector submodule pointer once the fix lands.
3. Re-export model.safetensors with the fixed writer and re-upload to ruvnet/wifi-densepose-pretrained. Consumers that pinned a revision= will keep pulling the broken file until then.
4. Add a release-time check to scripts/publish-huggingface.py that strict-loads every .safetensors before upload to prevent regression.

Verification

• cargo build --workspace --no-default-features — clean (warnings only)
• python -m py_compile scripts/fix-safetensors-header.py — OK
• End-to-end self-test of the utility against a synthetic NUL-padded file: pre-fix safetensors.safe_open raises SafetensorError: trailing characters at line 1 column N+1 (same class as the published bundles column 1462); post-fix the same file loads cleanly via safe_open. Declared header length, file size, and tensor payload all bit-preserved. Second run reports already clean (idempotent).
• Strict-reader repro in the doc (the 10-line script under "Repro") was executed and produces the documented error.

Test plan

• python scripts/fix-safetensors-header.py --dry-run <path> reports the patch without writing
• python scripts/fix-safetensors-header.py <path> patches in place, exits 0
• Re-running on the already-patched file reports already clean, exits 0
• Patched file loads via safetensors.torch.load_file without error