Distribute verified image archives through direct fabric

[FujitsuPolycom]

Resulting behavior

scripts/fanout_image_archive.py distributes one immutable image archive across a validated four-rank direct-link cycle without downloading the archive independently on every rank.

The command has four explicit operating modes:

• default planning performs no remote operation and emits sparkring-image-archive-fabric-plan/v1;
• --verify reads final-file type, SHA-256, and byte count on every rank and emits sparkring-image-archive-fabric-verification/v1;
• --execute --create-only downloads, transfers, and verifies the archive without importing it;
• --execute verifies all four archives, imports the image in rank order, and proves the requested tag resolves to the expected local image ID.

Execution requires --confirmation FANOUT_IMAGE_ARCHIVE. Management SSH starts and inspects work. Each rsync process binds to the source rank's address on the selected direct edge and connects to the adjacent rank's address on that edge. The default path starts with the seed's lowest-numbered neighbour; --first-hop-rank selects the opposite direction.

Archive identity and bounded interruption behavior

The operator supplies one 64-character lowercase archive SHA-256. The seed verifies that digest after a resumable curl --continue-at - download. Every direct hop writes a bounded .<archive-name>.partial file through rsync --partial --append-verify, verifies SHA-256, synchronizes the file, and creates the final path with a hard link that refuses an existing destination.

An exact final archive is reused. A different digest or non-regular object at the final path stops the operation without overwriting it. A command error or timeout stops later actions and retains exact finals and bounded partials already created. There is no distributed rollback; a retry reuses exact finals and resumes eligible partials.

Image import begins only after all four archives verify. An archive saved by image ID may lack a repository tag, so the command proves the expected image ID exists before applying the requested tag. An existing tag mapped to another image remains a conflict. If import stops partway through, imported images remain and a retry accepts only the expected image ID.

Interface and safety

The target directory must be an absolute normalized path with at least three components below /. The archive name is one bounded filename without path separators. Source URLs must use HTTP or HTTPS and cannot contain credentials, query parameters, or fragments.

--timeout bounds each remote operation and --connect-timeout bounds SSH and rsync connection setup. Defaults are 7,200 and 45 seconds. --output writes the same JSON evidence printed to standard output. The operator guide is docs/DIRECT_FABRIC_IMAGE_ARCHIVE_FANOUT.md.

Planning is offline. Verification is read-only remote work. Both execution forms mutate configured hosts. The command does not publish an image, create an archive, bootstrap host keys, install remote tools, or alter a serving deployment.

Compatibility

This change adds no model profile, runtime source pin, cache identity, storage schema, transport backend, or serving default. It consumes the sanitized SparkRing site schema and supports exactly ranks 0 through 3 when their direct edges form one cycle.

The selected three-hop path executes sequentially. The command does not broadcast, stripe one archive across links, or use both cycle directions concurrently.

Status and limitations

Status: implemented with GPU-free command and state-transition coverage.

Direct-fabric throughput is research-only. Live four-rank image import is unsupported by retained repository evidence. Archive SHA-256 and optional image-ID evidence do not qualify model serving, collective transport, SparkCache behavior, available disk capacity, source-server throughput, or achieved link throughput.

Validation

• fanout and site-topology suite: 146 passed;
• offline plan against the sanitized GLM-5.3 TP4 site: 14 actions and direct path 0→1→2→3, with no management address in transfer commands;
• CLI help exposes verification, execution, create-only, confirmation, timeout, connection-timeout, and output options;
• maintained CPU-only suite: 1,934 passed, 9 skipped;
• Ruff E/F/W: passed;
• git diff --check: passed.

Repository consistency note

SparkRing main described the GLM-5.3 C1 research observation but omitted the bounded statement C4 and C8 were capacity-limited required by scripts/test_glm53_flash_profile.py::test_public_glm53_benchmark_is_sanitized_and_bounded. Authoritative main workflow run 33298915434 reported the same mismatch. This review restores that factual sentence and keeps C4/C8 omitted from the throughput row. The corrected FP8 KV and NVMe capacity descriptions remain unchanged.

Historical review note

This main-based draft extracts the direct-fabric archive guide, command, tests, and configuration-index entry from draft pull request #135. Pull request #135 remains open and unchanged until reviewers accept this independent diff.

[FujitsuPolycom]

The verified image-distribution implementation is retained as an ancestor of draft PR #150. Closing this superseded draft and deleting only its remote head branch; retained PRs #146, #147, #149, and #150 are unchanged.