Coding Rules - For AI agents to follow

[GiggleLiu]

Adding a Reduction Rule (A → B)

1. Implementation

Create src/rules/<source>_<target>.rs:

// Register reduction for automatic discovery (adds edge + metadata)
inventory::submit! {
    ReductionEntry {
        source_name: "SourceProblem",
        target_name: "TargetProblem",
        source_graph: "SourceProblem",
        target_graph: "TargetProblem",
        overhead_fn: || ReductionOverhead::new(vec![
            ("num_vars", Polynomial { terms: vec![...] }),
            ("num_constraints", Polynomial { terms: vec![...] }),
        ]),
    }
}

impl ReduceTo<TargetProblem> for SourceProblem {
    type Result = ReductionSourceToTarget;
    fn reduce_to(&self) -> Self::Result { ... }
}

Register module in src/rules/mod.rs:

mod source_target;
pub use source_target::ReductionSourceToTarget;

2. Closed-Loop Test (Required)

#[test]
fn test_closed_loop() {
    // 1. Create small instance A
    let problem = SourceProblem::new(...);

    // 2. Reduce A to B
    let reduction = ReduceTo::<TargetProblem>::reduce_to(&problem);
    let target = reduction.target_problem();

    // 3. Solve B
    let solver = TargetSolver::new();
    let target_solution = solver.solve(target).unwrap();

    // 4. Extract solution of A
    let extracted = reduction.extract_solution(&target_solution);

    // 5. Verify solution
    assert!(problem.is_valid_solution(&extracted));
}

3. Documentation

Update docs/paper/reductions.typ:

• For each new model: add definition, what it can be reduced to/from (link to rules), data structure and connect math symbols with the field names. Model name (lower case, replace SPACE with "_") MUST exactly match the file name in src.
• For each new (non-trivial) reduction rule: add theorem + detailed proof + a working round-trip example.
• Each example MUST have a corresponding example code in tests/examples folder, with a naming convension [source_problem_name]-[target_problem_name].
• Add to summary table with overhead and citation, update refereces.bib

Citations must be verifiable. Use [Folklore] or — for trivial reductions.

4. Regenerate Reduction Graph

cargo run --example export_graph --all-features

---

Adding a Model

1. Define in src/models/<category>/<name>.rs
2. Document in docs/paper/reductions.typ
3. Implement JSON serialization (Serialize, Deserialize), add a close-loop test.

---

Before Submitting PR

Run Tests

cargo test --all-features

Run Clippy

cargo clippy --all-features

Check Coverage

# Install (one-time)
cargo install cargo-tarpaulin

# Check coverage for specific module (must be >95% for new code)
cargo tarpaulin --features ilp --skip-clean --ignore-tests -- <module_name>

# Example:
cargo tarpaulin --features ilp --skip-clean --ignore-tests -- factoring_ilp

# Generate HTML report
cargo tarpaulin --all-features --skip-clean --ignore-tests --out Html
# Opens: tarpaulin-report.html

Regenerate Graph JSON

cargo run --example export_graph --all-features

[GiggleLiu]

TODO: link the contents in this issue to rules in .claude folder. @isPANN

[GiggleLiu]

Done.