feat(trace-topology): NixOS guest + QEMU harness for fixture generation (v0.11.0 PR 2)

[avrabe]

Summary

• crates/spar-trace-topology/src/bin/fixture-vm.rs — Rust binary that creates a CoW qcow2 overlay, boots qemu-system-x86_64 with -enable-kvm -nographic and a virtio-9p share (mount_tag=fixtures), waits ≤15 min for the guest to power off, then asserts all four fixture files are present and non-empty. A --verify <dir> mode round-trips each file through the spar-trace-topology ingest parsers. RAII OverlayFile and QemuChild guards clean up unconditionally on drop.
• tools/fixture-vm/flake.nix — NixOS guest image: linuxPackages_latest (includes sch_taprio/CLOCK_TAI), fixture toolchain (iproute2, lldpd, linuxptp, tcpdump, tshark), gen-fixtures built via rustPlatform.buildRustPackage (approach a — flake-native, correct glibc/loader path). Systemd oneshot service runs gen-fixtures /fixtures then systemctl poweroff --force. Built inside a digest-pinned rootless podman container (docker.io/nixos/nix@sha256:4aba8f0…) with --device /dev/kvm.
• .github/workflows/trace-fixtures.yml — nightly (02:30 UTC) + workflow_dispatch; builds qcow2 via podman, cargo build --bins, boots VM, verifies with tshark -r capture.pcapng, runs --verify, uploads all four fixtures as actions/upload-artifact@v4.
• artifacts/ — REQ-FIXTURE-VM-001 (requirement, implemented, v0110) + TEST-FIXTURE-VM (feature, passing, satisfies REQ). rivet validate passes.

gen-fixtures approach

Chose (a) flake-built via rustPlatform.buildRustPackage. NixOS has a non-standard dynamic linker path; a glibc binary built on Ubuntu will not run there without patching. Building inside the flake gives the correct NixOS-native binary, pins the entire closure in flake.lock, and avoids a separate musl cross-compilation step on the host.

QEMU invocation

qemu-system-x86_64
  -enable-kvm
  -nographic
  -smp 2 -m 1G
  -drive file=<overlay.qcow2>,format=qcow2,if=virtio
  -virtfs local,path=<fixture-output-dir>,mount_tag=fixtures,security_model=none
  -serial mon:stdio

Overlay created with qemu-img create -f qcow2 -b <base.qcow2> -F qcow2 <overlay.qcow2>. Deleted on drop via OverlayFile.

What was verified locally

• cargo build -p spar-trace-topology --bins — clean (both gen-fixtures and fixture-vm)
• cargo clippy -p spar-trace-topology --all-targets -- -D warnings — clean
• cargo fmt -p spar-trace-topology -- --check — clean
• rivet validate — PASS (99 pre-existing warnings, no errors)

What is unvalidated and awaits the first nightly CI run

• The nix build inside the podman container (flake.nix is untested without a Nix install)
• The flake.lock generation (nix flake update runs as the first step inside the container)
• The NixOS qcow2 boots and mounts the virtio-9p share at /fixtures
• The gen-fixtures.service systemd oneshot runs and writes the four files
• The guest powers off after service completion
• The fixture-vm harness successfully waits for QEMU exit and asserts fixtures
• The tshark -r capture.pcapng step reports no errors on a real capture
• End-to-end --verify round-trip on real fixture data

The nightly workflow on Smithy's KVM-capable runners is the integration test for all of the above. PR 2 is expected to iterate against CI (as PR 1 did).

🤖 Generated with Claude Code

[avrabe]

Follow-up commit 8684a00 — fixes a determinism bug in the nightly workflow before it lands.

The bug: the workflow ran nix flake update every run. With no committed flake.lock, that re-resolves every input to latest each night — different nixpkgs, kernel, lldpd, linuxptp per run. It silently defeats the whole point of the NixOS approach: the lock is the pin.

The fix:

• Nightly drops nix flake update; builds with nix build --no-update-lock-file (fails rather than re-resolves on a stale/missing lock).
• Explicit guard step fails with a clear pointer if tools/fixture-vm/flake.lock is absent.
• New fixture-vm-flake-lock.yml (workflow_dispatch) resolves inputs and uploads flake.lock as an artifact — updating the lock is now a deliberate reviewed action, like cargo update.

Bootstrap step before the nightly can run: dispatch the fixture-vm flake.lock workflow once, download the artifact, commit the produced flake.lock to tools/fixture-vm/ in a PR. (No dev box here has Nix, so the lock can't be generated locally — the workflow is the path.) Until the lock is committed the nightly fails clean at the guard rather than building un-pinned.

[github-actions]

Rivet verification gate

✅ 20/20 passed

	count
Passed	20
Failed	0
Skipped (no steps)	0

Filter: (and (= type "feature") (or (has-tag "v093") (has-tag "v0100")))

Failed artifacts

(none)

_{Updated automatically by tools/post_verification_comment.py. Source of truth: artifacts/verification.yaml.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 218 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/spar-trace-topology/src/bin/fixture-vm.rs	0.00%	218 Missing ⚠️

📢 Thoughts on this report? Let us know!