feat(variants): spar-variants consumer crate for rivet variant context v1 (Track B commit 1)

[avrabe]

Summary

Speculative consumer side for the rivet ↔ spar variant binding contract v1
(docs/contracts/rivet-spar-variant-v1.md, proposed in #144).
Rivet's emitter is in flight; this crate is ready for it.

• New crate spar-variants (sibling of spar-network) — depends only on spar-hir-def and serde/serde_json.
• VariantContext::from_json parses the v1 blob and strictly rejects any rivet_spar_context_version != "1" (v2 readers refused per contract §"Compatibility and versioning").
• Binding covers both file-scoped (artifact) and symbol-scoped (symbol) entries via serde(untagged).
• HasBindingIdentity trait — minimal identity adapter HIR items will implement.
• keep_in_variant(item, context) applies the contract's intersection semantics: an item is kept iff every matching binding has its requires satisfied; items with no matching binding are kept unconditionally as variant-independent infrastructure.

Out of scope for this commit (deferred to Track B commit 2 alongside CLI wiring):

• --variant / --variant-context flags on spar-cli.
• impl HasBindingIdentity for spar-hir-def types — tests use a local StubItem.
• End-to-end test loop with the rivet emitter.

The symbol-binding matcher uses textual prefix-matching (<symbol> followed by ., ::, or end-of-string) which covers nested-in-body items per contract §"Symbol granularity"; a TODO(track-b-commit-2+) flags the inheritance corner-case that needs HIR-level "contains" plumbing rather than string-shape.

Artifacts

• New requirement: REQ-VARIANT-001 ("Consume rivet's variant context blob (v1) and filter HIR").
• New verification: TEST-VARIANTS-CONSUMER linked to REQ-VARIANT-001.

Test plan

• cargo build -p spar-variants clean
• cargo test -p spar-variants — 17 tests pass (10 spec'd + 7 incidental coverage)
• cargo build --workspace clean
• cargo test --workspace — all green
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo fmt --all -- --check clean
• rivet validate PASS (91 advisory warnings, all pre-existing)

Contract-spec ambiguities encountered

None blocking. One soft point worth flagging for the v1 finalization pass:

• Path normalization scope. Contract §"Binding resolution semantics" says "after normalization" without specifying it. This commit does textual normalization only: strip leading ./, fold \ → /. No .. resolution, no case-folding, no canonicalization against the filesystem. That's almost certainly the right v1 behaviour (project-relative paths, no I/O on the consumer side) but the spec could be tighter. Not blocking commit 1 — happy to firm up once the emitter is exercising real fixtures.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.18960% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/spar-variants/src/context.rs	86.17%	17 Missing ⚠️
crates/spar-variants/src/binding.rs	97.97%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!