Add variant-level aliases; introduce 2SAT and 3SAT (#1054)

* Add variant-level aliases; introduce 2SAT and 3SAT

Variant-level aliases attach to a specific reduction-graph node rather
than a canonical problem name, so shorthand like `3SAT` can resolve to
`KSatisfiability<K3>` directly instead of going through the problem's
default variant (which is `KN`, not what `3SAT` means in the literature).

- `VariantEntry` gains an `aliases: &'static [&'static str]` field.
- `declare_variants!` accepts optional `aliases ["X", ...]` trailing each
  entry and emits the field.
- `registry::find_variant_by_alias()` returns both the entry and its
  variant map.
- CLI `parse_problem_spec` and `resolve_alias` try variant-level aliases
  before problem-level ones, injecting the alias's variant tokens into
  the spec; problem-level resolution is unchanged for `MIS`, `SAT`, etc.
- Adds `2SAT` on `KSatisfiability<K2>` and `3SAT` on `KSatisfiability<K3>`.
- `pred list` now shows variant-level aliases on their own rows.
- `MAX2SAT` remains a problem-level alias on `Maximum2Satisfiability`
  (standalone problem, no variants).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address variant alias review follow-ups

* fix: cover all error branches of validate_variant_aliases for codecov

Refactor validation into a testable `validate_aliases_inner` that accepts
mock data, so every conflict branch (empty alias, canonical-name collision,
problem-alias collision, duplicate variant alias, multi-conflict) is
exercised without depending on inventory state. Also test `variant_label`
with both empty and non-empty variant dimensions.

Patch coverage: 15 uncovered lines → ~2 (the inventory integration test
panic branch, which is inherently unreachable on a healthy codebase).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: GiggleLiu

problemreductions-cli/src/commands/create/schema_support.rs

@@ -180,9 +180,7 @@ pub(super) fn create_schema_driven(
 
     // KColoring/KN stores the number of colors at runtime in `num_colors`.
     // The schema only declares `graph`, so inject `num_colors` from --k for KN.
-    if canonical == "KColoring"
-        && resolved_variant.get("k").map(|s| s.as_str()) == Some("KN")
-    {
+    if canonical == "KColoring" && resolved_variant.get("k").map(|s| s.as_str()) == Some("KN") {
         if let Some(k) = args.k {
             json_map.insert("num_colors".to_string(), serde_json::json!(k));
         }

problemreductions-cli/src/commands/graph.rs

@@ -33,12 +33,7 @@ pub fn list(out: &OutputConfig) -> Result<()> {
     for name in &types {
         let variants = graph.variants_for(name);
         let default_variant = graph.default_variant_for(name);
-        let aliases = aliases_for(name);
-        let alias_str = if aliases.is_empty() {
-            String::new()
-        } else {
-            aliases.join(", ")
-        };
+        let problem_aliases = aliases_for(name);
 
         for (i, v) in variants.iter().enumerate() {
             let slash = variant_to_full_slash(v);
@@ -53,13 +48,26 @@ pub fn list(out: &OutputConfig) -> Result<()> {
                 .variant_complexity(name, v)
                 .map(|c| big_o_of(&Expr::parse(c)))
                 .unwrap_or_default();
+
+            // Per-row aliases: problem-level aliases on the first row, plus any
+            // variant-level aliases attached to the specific reduction-graph node.
+            let variant_aliases: Vec<&'static str> =
+                problemreductions::registry::find_variant_entry(name, v)
+                    .map(|entry| entry.aliases.to_vec())
+                    .unwrap_or_default();
+            let mut parts: Vec<String> = Vec::new();
+            if i == 0 {
+                for alias in &problem_aliases {
+                    push_alias_part(&mut parts, alias);
+                }
+            }
+            for alias in &variant_aliases {
+                push_alias_part(&mut parts, alias);
+            }
+
             rows_data.push(VariantRow {
                 display,
-                aliases: if i == 0 {
-                    alias_str.clone()
-                } else {
-                    String::new()
-                },
+                aliases: parts.join(", "),
                 is_default,
                 rules: if i == 0 { rules } else { 0 },
                 complexity,
@@ -715,6 +723,12 @@ pub fn export(out: &OutputConfig) -> Result<()> {
     out.emit_with_default_name("reduction_graph.json", &text, &json)
 }
 
+fn push_alias_part(parts: &mut Vec<String>, alias: &str) {
+    if !parts.iter().any(|part| part.eq_ignore_ascii_case(alias)) {
+        parts.push(alias.to_string());
+    }
+}
+
 fn parse_direction(s: &str) -> Result<TraversalFlow> {
     match s {
         "out" => Ok(TraversalFlow::Outgoing),
@@ -805,3 +819,20 @@ fn render_tree(graph: &ReductionGraph, nodes: &[NeighborTree], text: &mut String
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::push_alias_part;
+
+    #[test]
+    fn push_alias_part_deduplicates_case_insensitively_in_order() {
+        let mut parts = Vec::new();
+        push_alias_part(&mut parts, "KSAT");
+        push_alias_part(&mut parts, "3SAT");
+        push_alias_part(&mut parts, "ksat");
+        push_alias_part(&mut parts, "2SAT");
+        push_alias_part(&mut parts, "3sat");
+
+        assert_eq!(parts, vec!["KSAT", "3SAT", "2SAT"]);
+    }
+}

problemreductions-cli/src/problem_name.rs

@@ -12,7 +12,14 @@ pub struct ProblemSpec {
 
 /// Resolve a short alias to the canonical problem name.
 ///
-/// Uses the catalog for both aliases and canonical names.
+/// Searches both variant-level aliases (e.g., `"3SAT"` → `KSatisfiability`) and
+/// problem-level aliases (e.g., `"MIS"` → `MaximumIndependentSet`). When a
+/// variant-level alias is matched, only the canonical name is returned here.
+/// The older pass-through behavior where `3SAT` resolved to `"3SAT"` has been
+/// intentionally replaced by `3SAT` resolving to `"KSatisfiability"` so aliases
+/// behave consistently. Callers that need variant semantics such as
+/// `3SAT` → `KSatisfiability { k = K3 }` should use [`parse_problem_spec`] or
+/// [`resolve_problem_ref`].
 pub fn resolve_alias(input: &str) -> String {
     if input.eq_ignore_ascii_case("UndirectedFlowLowerBounds") {
         return "UndirectedFlowLowerBounds".to_string();
@@ -38,6 +45,9 @@ pub fn resolve_alias(input: &str) -> String {
     if input.eq_ignore_ascii_case("GraphPartitioning") {
         return "GraphPartitioning".to_string();
     }
+    if let Some((entry, _)) = problemreductions::registry::find_variant_by_alias(input) {
+        return entry.name.to_string();
+    }
     if let Some(pt) = problemreductions::registry::find_problem_type_by_alias(input) {
         return pt.canonical_name.to_string();
     }
@@ -64,16 +74,34 @@ pub fn resolve_catalog_problem_ref(
 }
 
 /// Parse a problem spec string like "MIS/UnitDiskGraph/i32" into name + variant values.
+///
+/// Resolution order:
+/// 1. **Variant-level alias** (`"3SAT"` → `KSatisfiability` + variant tokens `["K3"]`):
+///    injects the variant tokens *before* any user-supplied tokens from the slash spec.
+/// 2. **Problem-level alias** (`"MIS"` → `MaximumIndependentSet`): canonical-name only;
+///    downstream default-variant resolution fills in the variant dimensions.
 pub fn parse_problem_spec(input: &str) -> anyhow::Result<ProblemSpec> {
     let parts: Vec<&str> = input.split('/').collect();
     let raw_name = parts[0];
-    let variant_values: Vec<String> = parts[1..].iter().map(|s| s.to_string()).collect();
+    let user_tokens: Vec<String> = parts[1..].iter().map(|s| s.to_string()).collect();
+
+    if let Some((entry, variant_map)) = problemreductions::registry::find_variant_by_alias(raw_name)
+    {
+        // Prepend the alias's own variant values; the slash-spec resolver handles
+        // additional user tokens (and errors on dimension collisions).
+        let mut variant_values: Vec<String> = variant_map.into_values().collect();
+        variant_values.extend(user_tokens);
+        return Ok(ProblemSpec {
+            name: entry.name.to_string(),
+            variant_values,
+        });
+    }
 
     let name = resolve_alias(raw_name);
 
     Ok(ProblemSpec {
         name,
-        variant_values,
+        variant_values: user_tokens,
     })
 }
 
@@ -301,8 +329,11 @@ mod tests {
         assert_eq!(resolve_alias("X3C"), "ExactCoverBy3Sets");
         assert_eq!(resolve_alias("3Partition"), "ThreePartition");
         assert_eq!(resolve_alias("3-partition"), "ThreePartition");
-        // 3SAT is no longer a registered alias (removed to avoid confusion with KSatisfiability/KN)
-        assert_eq!(resolve_alias("3SAT"), "3SAT"); // pass-through
+        // Variant-level aliases: resolve_alias only returns the canonical name;
+        // parse_problem_spec recovers the variant tokens (see tests below).
+        assert_eq!(resolve_alias("3SAT"), "KSatisfiability");
+        assert_eq!(resolve_alias("3sat"), "KSatisfiability");
+        assert_eq!(resolve_alias("2SAT"), "KSatisfiability");
         assert_eq!(resolve_alias("QUBO"), "QUBO");
         assert_eq!(resolve_alias("MaxCut"), "MaxCut");
         assert_eq!(
@@ -372,6 +403,86 @@ mod tests {
         assert_eq!(spec.variant_values, vec!["K3"]);
     }
 
+    #[test]
+    fn test_parse_problem_spec_variant_alias_3sat() {
+        // Variant-level alias: "3SAT" injects the K3 variant token.
+        let spec = parse_problem_spec("3SAT").unwrap();
+        assert_eq!(spec.name, "KSatisfiability");
+        assert_eq!(spec.variant_values, vec!["K3"]);
+
+        let spec = parse_problem_spec("3sat").unwrap();
+        assert_eq!(spec.name, "KSatisfiability");
+        assert_eq!(spec.variant_values, vec!["K3"]);
+    }
+
+    #[test]
+    fn test_parse_problem_spec_variant_alias_2sat() {
+        let spec = parse_problem_spec("2SAT").unwrap();
+        assert_eq!(spec.name, "KSatisfiability");
+        assert_eq!(spec.variant_values, vec!["K2"]);
+    }
+
+    #[test]
+    fn test_resolve_problem_ref_variant_alias_3sat() {
+        let graph = problemreductions::rules::ReductionGraph::new();
+        let expected = ProblemRef {
+            name: "KSatisfiability".to_string(),
+            variant: BTreeMap::from([("k".to_string(), "K3".to_string())]),
+        };
+
+        assert_eq!(resolve_problem_ref("3SAT", &graph).unwrap(), expected);
+    }
+
+    #[test]
+    fn test_resolve_problem_ref_variant_alias_2sat() {
+        let graph = problemreductions::rules::ReductionGraph::new();
+        let expected = ProblemRef {
+            name: "KSatisfiability".to_string(),
+            variant: BTreeMap::from([("k".to_string(), "K2".to_string())]),
+        };
+
+        assert_eq!(resolve_problem_ref("2SAT", &graph).unwrap(), expected);
+    }
+
+    #[test]
+    fn test_resolve_problem_ref_3sat_k2_rejects_duplicate_dimension() {
+        let spec = parse_problem_spec("3SAT/K2").unwrap();
+        assert_eq!(spec.name, "KSatisfiability");
+        assert_eq!(spec.variant_values, vec!["K3", "K2"]);
+
+        let graph = problemreductions::rules::ReductionGraph::new();
+        let err = resolve_problem_ref("3SAT/K2", &graph).unwrap_err();
+        assert!(
+            err.to_string().contains("specified more than once"),
+            "expected duplicate-dimension error, got: {err}"
+        );
+    }
+
+    #[test]
+    fn test_resolve_problem_ref_3sat_simple_graph_rejects_unknown_token() {
+        let spec = parse_problem_spec("3SAT/SimpleGraph").unwrap();
+        assert_eq!(spec.name, "KSatisfiability");
+        assert_eq!(spec.variant_values, vec!["K3", "SimpleGraph"]);
+
+        let graph = problemreductions::rules::ReductionGraph::new();
+        let err = resolve_problem_ref("3SAT/SimpleGraph", &graph).unwrap_err();
+        assert!(
+            err.to_string()
+                .to_lowercase()
+                .contains("unknown variant token"),
+            "expected unknown-token error, got: {err}"
+        );
+    }
+
+    #[test]
+    fn test_parse_problem_spec_max2sat_problem_level() {
+        // MAX2SAT is a problem-level alias on Maximum2Satisfiability (standalone problem,
+        // no K variants) — no variant tokens injected.
+        let spec = parse_problem_spec("MAX2SAT").unwrap();
+        assert_eq!(spec.name, "Maximum2Satisfiability");
+        assert!(spec.variant_values.is_empty());
+    }
+
     #[test]
     fn test_suggest_problem_name_close() {
         // "MISs" is 1 edit from "MIS" alias -> should suggest MaximumIndependentSet

problemreductions-cli/src/test_support.rs

@@ -126,6 +126,7 @@ problemreductions::inventory::submit! {
         complexity: "2^num_values",
         complexity_eval_fn: |_| 1.0,
         is_default: true,
+        aliases: &[],
         factory: |data| {
             let problem: AggregateValueSource = serde_json::from_value(data)?;
             Ok(Box::new(problem))
@@ -146,6 +147,7 @@ problemreductions::inventory::submit! {
         complexity: "2",
         complexity_eval_fn: |_| 1.0,
         is_default: true,
+        aliases: &[],
         factory: |data| {
             let problem: AggregateValueTarget = serde_json::from_value(data)?;
             Ok(Box::new(problem))

problemreductions-macros/src/lib.rs

@@ -444,11 +444,12 @@ struct DeclareVariantsInput {
     entries: Vec<DeclareVariantEntry>,
 }
 
-/// A single entry: `[default] Type => "complexity_string"`.
+/// A single entry: `[default] Type => "complexity_string" [aliases ["X", ...]]`.
 struct DeclareVariantEntry {
     is_default: bool,
     ty: Type,
     complexity: syn::LitStr,
+    aliases: Vec<syn::LitStr>,
 }
 
 impl syn::parse::Parse for DeclareVariantsInput {
@@ -464,10 +465,47 @@ impl syn::parse::Parse for DeclareVariantsInput {
             let ty: Type = input.parse()?;
             input.parse::<syn::Token![=>]>()?;
             let complexity: syn::LitStr = input.parse()?;
+
+            // Optional: `aliases ["X", "Y", ...]`
+            let aliases = if input.peek(syn::Ident) {
+                let fork = input.fork();
+                let ident: syn::Ident = fork.parse()?;
+                if ident == "aliases" {
+                    input.parse::<syn::Ident>()?;
+                    let content;
+                    syn::bracketed!(content in input);
+                    let mut out = Vec::new();
+                    while !content.is_empty() {
+                        let lit: syn::LitStr = content.parse()?;
+                        if lit.value().trim().is_empty() {
+                            return Err(syn::Error::new(
+                                lit.span(),
+                                "variant alias must not be empty or whitespace-only",
+                            ));
+                        }
+                        out.push(lit);
+                        if content.peek(syn::Token![,]) {
+                            content.parse::<syn::Token![,]>()?;
+                        }
+                    }
+                    out
+                } else if fork.peek(syn::token::Bracket) {
+                    return Err(syn::Error::new(
+                        ident.span(),
+                        format!("expected 'aliases', found '{ident}'"),
+                    ));
+                } else {
+                    Vec::new()
+                }
+            } else {
+                Vec::new()
+            };
+
             entries.push(DeclareVariantEntry {
                 is_default,
                 ty,
                 complexity,
+                aliases,
             });
 
             if input.peek(syn::Token![,]) {
@@ -552,6 +590,7 @@ fn generate_declare_variants(input: &DeclareVariantsInput) -> syn::Result<TokenS
         let ty = &entry.ty;
         let complexity_str = entry.complexity.value();
         let is_default = entry.is_default;
+        let alias_lits: Vec<_> = entry.aliases.iter().map(|s| s.value()).collect();
 
         // Parse the complexity expression to validate syntax
         let parsed = parser::parse_expr(&complexity_str).map_err(|e| {
@@ -633,6 +672,7 @@ fn generate_declare_variants(input: &DeclareVariantsInput) -> syn::Result<TokenS
                     complexity: #complexity_str,
                     complexity_eval_fn: #complexity_eval_fn,
                     is_default: #is_default,
+                    aliases: &[#(#alias_lits),*],
                     #dispatch_fields
                 }
             }
@@ -767,6 +807,44 @@ mod tests {
         );
     }
 
+    #[test]
+    fn declare_variants_rejects_empty_alias_literal() {
+        let err =
+            match syn::parse_str::<DeclareVariantsInput>("default Foo => \"1\" aliases [\"\"]") {
+                Ok(_) => panic!("empty alias literal should be rejected"),
+                Err(err) => err,
+            };
+        assert!(
+            err.to_string().contains("empty or whitespace-only"),
+            "expected empty-alias error, got: {err}"
+        );
+    }
+
+    #[test]
+    fn declare_variants_rejects_whitespace_only_alias_literal() {
+        let err = match syn::parse_str::<DeclareVariantsInput>(
+            "default Foo => \"1\" aliases [\"  \\t\"]",
+        ) {
+            Ok(_) => panic!("whitespace-only alias literal should be rejected"),
+            Err(err) => err,
+        };
+        assert!(
+            err.to_string().contains("empty or whitespace-only"),
+            "expected whitespace-only alias error, got: {err}"
+        );
+    }
+
+    #[test]
+    fn declare_variants_rejects_unknown_alias_keyword_before_bracket() {
+        let err = match syn::parse_str::<DeclareVariantsInput>(
+            "default Foo => \"1\" nicknames [\"Foo\"]",
+        ) {
+            Ok(_) => panic!("unknown aliases keyword should be rejected"),
+            Err(err) => err,
+        };
+        assert_eq!(err.to_string(), "expected 'aliases', found 'nicknames'");
+    }
+
     #[test]
     fn declare_variants_generates_aggregate_value_and_witness_dispatch() {
         let input: DeclareVariantsInput = syn::parse_quote! {