refactor(graph): split spec-hash traversal from encoding behind a SpecEncoder trait - #1107

Pure structural refactor of the spec-hash serializer. It changes no bytes and no cache keys — the output is identical to before for every input (see "Byte-identity" below). No BuildSpec, no wire format, no public API changes.

What & why

crates/graph/src/spec_hasher.rs computes SpecHash, minimal's content-address cache key. Today it interleaves two concerns:

1. Traversal — walk the build graph, discover every referenced spec, assign each a stable discovery index (handles cycles via a seen-map).
2. Encoding — turn each spec's fields and edges into the exact bytes fed to Blake3.

The encoding was scattered as direct hasher.write_all(...) calls across five functions. This PR routes all byte emission through a small SpecEncoder trait, with one implementation — LegacyEncoder — that reproduces the current scheme exactly (raw concatenation, in-band markers, little-endian widths). Traversal (process) is untouched; the new encode() method walks the already-discovered specs and emits through the trait.

The trait's methods carry semantic intent the legacy encoder deliberately collapses:

trait SpecEncoder {
    fn tag(&mut self, tag: &[u8]);      // fixed structural marker  (b"src", b"i", ...)
    fn bytes(&mut self, bytes: &[u8]);  // variable content        (a name, glob, url)
    fn index(&mut self, idx: usize);    // a discovery index
    fn number(&mut self, n: f64);       // AttrValue::Number
    fn target(&mut self, target: &Target);
    fn finish(self) -> SpecHash;
}

For the legacy scheme tag and bytes are both a raw write_all — so this is a no-op rename today. The point is what it enables: a length-prefixed / injective successor is a new impl of this trait, selected at the call site, rather than edits threaded through the graph walk.

Motivation (context, not required to review this diff)

The spec-hash byte encoding is not prefix-free — distinct specs can serialize to identical bytes (a small set of known collisions exists). A future change will replace the encoding with an injective one, which necessarily changes every cache key (a coordinated "epoch" migration). That change is far safer and smaller to review if the encoding already lives behind a single seam instead of being woven through the traversal. This PR builds that seam with zero behavioral change, so the risky part lands later as an isolated, self-contained diff. It also gives the encoding a clean extraction point for property/formal testing.

Byte-identity — how it's verified

• The two hand-constructed golden tests (attrs_hash, subset_hash) pin fixed expected digests with no environmental input. They pass unchanged — direct proof the encoder emits identical bytes.
• The other three hasher tests (spec_tree, cycle, abstract_deps_hashed) ingest specs through Nickel and assert per-arch golden values via the arch_hash! macro; their result is sensitive to the local stdlib version (the macro's own comment notes this). On a machine whose local stdlib differs from the pinned CI one they fail before and after this change, computing the identical hash both times — I diffed the computed value on this branch vs pristine main and they match exactly (41c47d47… in both). So these are a pre-existing local-environment mismatch, not a regression, and they pass in CI's pinned stdlib.

Beyond that: 52/55 graph tests pass locally (the 3 above being the known env-sensitive ones), fmt clean, clippy clean on the file.

Incidental tidy

The two byte-identical inline copies of the subset-output edge encoding are factored into one encode_subset_info helper.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Refactor
  • Improved internal specification hash generation while preserving existing hash results.
  • Unified hashing behavior across specification and subset calculations.
  • No changes to public interfaces or end-user functionality.