spikes/008-streaming-diloco/README.md

Spike 008 — Streaming DiLoCo outer-loop smoke

Closes: V2 (DiLoCo "deferred to v0.2") in docs/VISION_VALIDATION.md.

Goal

Bolt the DiLoCo outer-loop pseudo-gradient sync onto the framework using torchft.local_sgd.DiLoCo (see docs/adrs/ADR-003-diloco-impl.md).

Verify:

1. Two in-process replicas converge to identical parameters after outer sync.
2. Outer Nesterov momentum is actually populated (i.e. the outer optimizer ran).
3. The pseudo-gradient sign convention is what we expect (sign flip detected by an explicit unit test).
4. Importing torchft does not regress Spike 005's existing 38 tests.

Single-process, no NCCL. Mock Manager.allreduce does real cross-replica averaging through a shared buffer.

Files

• composer_diloco.py — make_diloco_outer_loop(...) wrapper around torchft.local_sgd.DiLoCo. Documents the sign convention.
• tests/test_diloco_smoke.py — 3 acceptance tests.

Acceptance

Criterion	Status
2 replicas converge after 2 outer rounds	✓ test 1
Nesterov momentum state populated	✓ test 1
Sync fires once per outer round per replica	✓ test 1
Pseudo-gradient sign convention verified	✓ test 2
No regression in Spike 005 imports	✓ test 3
Spike 005's 38 tests still pass after this wave	(verified separately)

Future work (v0.2 Streaming DiLoCo)

• fragment_sync_delay > 0 requires CUDA streams. Spike 008 uses fragment_sync_delay=0 (vanilla DiLoCo) for the smoke.
• Multiple fragments via model_fragments=[frag_0, frag_1, ...] configured by make_diloco_outer_loop() but not exercised in the smoke.
• Real torch.distributed backend (NCCL) for multi-node training is one config switch away (replace mock Manager with real torchft.Manager).

Cost / time

• Pure CPU, single process, no GPU.
• Tests run in <2 seconds total.

Dependencies added

• torchft-nightly (BSD-3, Meta-maintained, pip install torchft-nightly)