feat: variant-aware reduction paths with resolve_path

[GiggleLiu]

Summary

• Adds resolve_path to lift name-level ReductionPath into variant-level ResolvedPath, threading graph/weight/constant variants through each reduction step and inserting NaturalCast edges where subtype relaxation is needed
• Introduces find_best_entry for variant-aware ReductionEntry lookup, resolving the KSat overhead ambiguity (k=2 vs k=3 now return distinct overheads)
• Deprecates lookup_overhead / lookup_overhead_or_empty in favor of extracting overhead from the resolved path
• Removes explicit impl_natural_reduction! invocation — natural casts are now computed from subtype hierarchies

Test plan

• make test clippy passes
• Unit tests for ResolvedPath, find_best_entry, variant disambiguation (KSat k=2 vs k=3), natural cast insertion (GridGraph→SimpleGraph, Triangular→SimpleGraph)
• KSat example migrated to resolve_path API
• Remaining examples use #[allow(deprecated)] — to be migrated incrementally

See design.md for full design rationale.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.71182% with 89 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.76%. Comparing base (2b5f0fd) to head (ed016fc).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/topology/kings_subgraph.rs	35.59%	38 Missing ⚠️
src/rules/graph.rs	88.88%	17 Missing ⚠️
src/topology/triangular_subgraph.rs	86.84%	10 Missing ⚠️
src/rules/unitdiskmapping/ksg/mapping.rs	90.90%	7 Missing ⚠️
src/unit_tests/rules/sat_coloring.rs	88.70%	7 Missing ⚠️
src/rules/coloring_qubo.rs	92.68%	3 Missing ⚠️
src/rules/coloring_ilp.rs	94.87%	2 Missing ⚠️
src/unit_tests/rules/graph.rs	98.84%	2 Missing ⚠️
...rc/unit_tests/unitdiskmapping_algorithms/common.rs	60.00%	2 Missing ⚠️
src/unit_tests/rules/sat_ksat.rs	99.12%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #68      +/-   ##
==========================================
- Coverage   97.06%   96.76%   -0.30%     
==========================================
  Files         187      185       -2     
  Lines       25150    25789     +639     
==========================================
+ Hits        24412    24955     +543     
- Misses        738      834      +96     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR introduces variant-aware reduction path resolution to address two key issues: overhead ambiguity when multiple reduction variants exist (e.g., KSat k=2 vs k=3), and automatic insertion of natural cast steps when variant relaxation is needed. The implementation adds a two-phase approach where name-level paths are first discovered, then resolved to variant-level paths with precise overhead and natural cast information.

Changes:

• Adds resolve_path method that lifts name-level ReductionPath into variant-level ResolvedPath with automatic natural cast insertion
• Introduces find_best_entry for variant-aware ReductionEntry lookup, resolving overhead ambiguity by selecting the most specific compatible entry
• Deprecates lookup_overhead / lookup_overhead_or_empty in favor of extracting overhead from resolved paths

Reviewed changes

Copilot reviewed 45 out of 45 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/rules/graph.rs	Adds ResolvedPath, ReductionStep, EdgeKind types and resolve_path/find_best_entry methods for variant-aware path resolution
src/rules/mod.rs	Exports new public types EdgeKind, ReductionStep, ResolvedPath
src/rules/registry.rs	Adds Serialize derive to ReductionOverhead for JSON export support
src/polynomial.rs	Adds Serialize derive to Monomial and Polynomial for JSON export support
src/export.rs	Deprecates lookup_overhead and lookup_overhead_or_empty with migration guidance
src/rules/natural.rs	Removes explicit impl_natural_reduction! invocation, now handled automatically by resolve_path
examples/reduction_ksatisfiability_to_qubo.rs	Migrates from lookup_overhead to resolve_path API demonstrating variant-aware overhead extraction
src/unit_tests/rules/graph.rs	Comprehensive tests for resolve_path, find_best_entry, variant disambiguation, and natural cast insertion
src/unit_tests/rules/natural.rs	Updates test to verify natural cast insertion via resolve_path
src/unit_tests/export.rs	Adds #[allow(deprecated)] to tests using deprecated functions
examples/*.rs	Adds #[allow(deprecated)] to examples pending incremental migration
docs/src/design.md	Adds comprehensive documentation on variant-aware path resolution algorithm and usage
docs/plans/*.md	Adds detailed design and implementation plans for the feature

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The logic for inserting natural casts in resolve_path has a potential issue. When current_variant != entry_source, a natural cast is inserted. However, the code doesn't verify that the natural cast is actually valid - it should check is_variant_reducible(current_variant, entry_source) before inserting the cast. Without this check, incompatible variants could be incorrectly cast.

The find_best_entry method already ensures compatibility by checking is_variant_reducible(current_variant, entry_source) at line 723, which prevents incompatible entries from being returned. However, for code clarity and defensive programming, an explicit check or assertion before the natural cast insertion would make the invariant more obvious.

[GiggleLiu]

Addressed: added a debug_assert!(is_variant_reducible(...)) before the natural cast insertion. As you noted, find_best_entry already guarantees compatibility, but the assertion makes the invariant explicit.

[Copilot]

The MatchedEntry type alias uses a tuple (BTreeMap<String, String>, BTreeMap<String, String>, ReductionOverhead) which makes the code less self-documenting. Consider defining a struct instead:

pub struct MatchedEntry {
    pub source_variant: BTreeMap<String, String>,
    pub target_variant: BTreeMap<String, String>,
    pub overhead: ReductionOverhead,
}

This would make call sites like let (source_var, target_var, overhead) = entry.unwrap() more explicit as let entry = entry.unwrap(); entry.source_variant... and improve code readability.

[GiggleLiu]

Addressed: converted MatchedEntry from a tuple type alias to a named struct with source_variant, target_variant, and overhead fields. All usage sites updated.

[GiggleLiu]

Change Summary

This PR is a comprehensive redesign of the variant system, spanning 36 commits across 191 files (+7141/-3106 lines). The work falls into four major areas:

1. Variant-Aware Reduction Path Resolution

• Introduced ResolvedPath, ReductionStep, and EdgeKind types to lift name-level reduction paths into variant-level paths
• Added resolve_path that threads graph/weight/constant variants through each reduction step, automatically inserting NaturalCast edges where subtype relaxation is needed (e.g., GridGraph → SimpleGraph)
• Added find_best_entry for variant-aware ReductionEntry lookup, resolving ambiguities like KSat k=2 vs k=3 returning distinct overheads
• Deprecated lookup_overhead / lookup_overhead_or_empty in favor of the resolved path API

2. Type-Level Variant Parameter System

• Introduced VariantParam trait with CastToParent for compile-time variant hierarchies, replacing the old GraphSubtypeEntry/WeightSubtypeEntry system
• Added impl_variant_param! and variant_params! macros for declarative registration
• Migrated KSatisfiability and KColoring from const K: usize generics to KValue type parameters (K2, K3, KN<N>) — enabling proper variant-level dispatch
• Registered all graph types (SimpleGraph, UnitDiskGraph, HyperGraph), weight types (One, i32, f64), and K-values with VariantParam
• Applied variant_params! macro across all Problem implementations
• Unified variant hierarchy in ReductionGraph using the new VariantTypeEntry

3. Interactive Reduction Diagram (mdBook)

• Extracted inline JS/CSS from introduction.md into external files
• Implemented compound (collapsible) nodes grouping problem variants
• Added ELK stress layout, search bar, variant edge filtering on click, dashed natural cast edges
• Integrated path finding with the compound node structure
• Added legend and help text for the diagram

4. Cleanup

• Removed the old Julia test data generation scripts and all tests/data/jl/ ground truth JSON files
• Removed deprecated helpers (const_usize_str, short_type_name, const generic rewriting)
• Removed explicit impl_natural_reduction! invocations — natural casts are now inferred from subtype hierarchies
• Significantly expanded unit tests across models, rules, and variant modules

[Copilot]

Pull request overview

Copilot reviewed 107 out of 107 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The logic for selecting the "most specific" entry in find_best_entry is potentially incorrect. At line 693, the check self.is_variant_reducible(&entry_source, best_source) would be true if entry_source is MORE restrictive than best_source. However, the comment says "New entry is more specific than current best?" which suggests we want to prefer the entry_source that is MORE restrictive (closer to current_variant). The condition should likely be inverted or the logic reconsidered. If is_variant_reducible(A, B) means "A can be reduced to B" (A is more specific), then this check correctly identifies when the new entry is more specific. But the || entry_source == *current_variant clause suggests exact matches should be preferred, which conflicts with the reducer logic. Please verify this selection logic is correct.

[GiggleLiu]

The logic is correct. is_variant_reducible(A, B) means A ≤ B (A is more specific / a subtype of B). So is_variant_reducible(entry_source, best_source) is true when entry_source is more specific than best_source, which is exactly what we want — prefer the tighter fit. The || entry_source == *current_variant handles exact matches as a priority shortcut. Added a clarifying comment to the code.

[Copilot]

The K-value hierarchy is defined in reverse order: K1 < K2 < K3 < K4 < KN. This means a problem with K=1 is considered more specific than K=2, which is counterintuitive. For subtype relationships, you typically want the more general type as the parent. Consider whether K1 should actually be the "most specific" and KN the "most general" (root). If the intent is that smaller K values can be used where larger K values are expected, the hierarchy should be reversed: KN (root) with K4 < K3 < K2 < K1 as children, or reconsider the parent relationships.

[GiggleLiu]

The hierarchy is intentional: K1 < K2 < K3 < K4 < KN means "K1-SAT is a special case of K2-SAT". Every 1-clause can be treated as a 2-clause (by repeating a literal), so a K2-SAT solver handles K1-SAT inputs. The parent direction represents generalization: KN (arbitrary K) is the most general, K1 the most specific. This matches the graph hierarchy pattern (KingsSubgraph < UnitDiskGraph < SimpleGraph).