Relax Possibility to Clone and add opt-in parallel search

- Problem::Possibility now only requires Clone instead of Copy. Every
  Copy type is already Clone, so this is backward compatible for all
  existing implementations, while also allowing heap-backed decision
  types.
- Add an opt-in `parallel` feature (optional rayon dependency) with a
  new parallel_solutions function: it fans out the independent
  branches rooted at each top-level possibility across threads, each
  branch still walked sequentially by the existing Solutions iterator.
  Solutions::new and its bounds are untouched.
- CI now also runs the test suite with --features parallel.
- README documents both additions and their rationale.
- Ignore GENERICITY.md (private working notes, not meant to be
  tracked).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: menjaraz

.github/workflows/test.yml

@@ -11,6 +11,8 @@ jobs:
     - uses: actions/checkout@v5
     - name: Run tests
       run: cargo test --all-targets --verbose
+    - name: Run tests (parallel feature)
+      run: cargo test --all-targets --features parallel --verbose
     - name: Run knights-journey
       run: cargo run --example knights_journey --release
     - name: Run sudoku

.gitignore

@@ -1 +1,2 @@
 /target
+/GENERICITY.md

Cargo.lock

@@ -24,3 +24,7 @@ categories = []
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+rayon = { version = "1", optional = true }
+
+[features]
+parallel = ["dep:rayon"]

Cargo.toml

@@ -5,3 +5,21 @@
 Generic implementation of backtracking together with some examples. This came out of a code dojo
 session with some of my colleagues (<https://github.com/pacman82/cobra-kai-code-dojo>). I found it
 neat enough to put it into its own repostiory.
+
+---
+
+## Fork additions
+
+This fork adds test coverage (the library and all three examples now have unit tests; CI runs
+`cargo test --all-targets` against both the default and `parallel` feature sets) and two
+backward-compatible extensions to the `Problem`/`Solutions` API:
+
+- **`Problem::Possibility` now requires only `Clone`, not `Copy`.** Every `Copy` type is already
+  `Clone`, so existing implementations are unaffected; the weaker bound additionally allows
+  heap-backed decision types (an owned `String`, a `Vec`, ...) without forcing them through an
+  artificial handle/index indirection just to satisfy the trait.
+- **An opt-in `parallel` feature adds `parallel_solutions`.** It searches the independent branches
+  rooted at each top-level possibility in parallel (via `rayon`), with each branch still walked
+  sequentially by an ordinary `Solutions` iterator on its own thread. The extra `Clone + Send +
+  Sync` bounds only apply at that new call site — `Solutions::new` and its bounds are untouched,
+  and the `rayon` dependency is not compiled unless the feature is enabled.

README.md

@@ -12,7 +12,7 @@ pub trait Problem {
     /// Describes a decision made in a problem state leading to a new candidate for a solution. E.g.
     /// which field to jump to in a knights journey problem or which digit to write into a cell for
     /// a sudoku puzzle.
-    type Possibility: Copy;
+    type Possibility: Clone;
     /// Final state we are interested in. E.g. The history of moves made for a knights journey, or
     /// the final distribution of digits in the cells of a sudoku puzzle.
     type Solution;
@@ -56,7 +56,7 @@ impl<G: Problem> Solutions<G> {
             .iter()
             .map(|pos| Candidate {
                 count: 1,
-                possibility: *pos,
+                possibility: pos.clone(),
             })
             .collect();
         Self {
@@ -66,6 +66,45 @@ impl<G: Problem> Solutions<G> {
             current: init,
         }
     }
+
+    /// Restricts the initial search frontier to a single possibility, leaving the rest of the
+    /// tree walk identical to [`Solutions::new`]. Used to partition the root of the search tree
+    /// into independent branches, e.g. for [`parallel_solutions`].
+    fn seeded(current: G, first: G::Possibility) -> Self {
+        Self {
+            decisions: Vec::new(),
+            open: vec![Candidate {
+                count: 1,
+                possibility: first,
+            }],
+            history: Vec::new(),
+            current,
+        }
+    }
+}
+
+/// Explores the independent branches rooted at each of the initial possibilities of `init` in
+/// parallel, each branch searched sequentially by an ordinary [`Solutions`] iterator on its own
+/// thread. Requires the `parallel` feature.
+///
+/// This only requires [`Clone`] on `P` (to fork one problem instance per root branch) and
+/// [`Send`] bounds (to move those instances across threads); it does not change [`Problem`] or
+/// [`Solutions`] in any way, so it is purely additive to the crate's API.
+#[cfg(feature = "parallel")]
+pub fn parallel_solutions<P>(init: P) -> impl rayon::iter::ParallelIterator<Item = P::Solution>
+where
+    P: Problem + Clone + Send + Sync,
+    P::Solution: Send,
+    P::Possibility: Send,
+{
+    use rayon::iter::{IntoParallelIterator, ParallelIterator};
+
+    let mut roots = Vec::new();
+    init.extend_possibilities(&mut roots, &[]);
+
+    roots.into_par_iter().flat_map_iter(move |first_move| {
+        Solutions::seeded(init.clone(), first_move)
+    })
 }
 
 impl<G: Problem> Iterator for Solutions<G> {
@@ -86,7 +125,7 @@ impl<G: Problem> Iterator for Solutions<G> {
             }
 
             // We advance one move deeper into the search tree
-            self.current.what_if(mov);
+            self.current.what_if(mov.clone());
             self.history.push(mov);
 
             // Emit solution
@@ -99,9 +138,9 @@ impl<G: Problem> Iterator for Solutions<G> {
             self.current
                 .extend_possibilities(&mut self.decisions, &self.history);
             self.open
-                .extend(self.decisions.iter().map(|&position| Candidate {
+                .extend(self.decisions.iter().map(|position| Candidate {
                     count: count + 1,
-                    possibility: position,
+                    possibility: position.clone(),
                 }))
         }
         None
@@ -180,6 +219,7 @@ mod tests {
 
     /// Only yields permutations of `0..n`, by refusing to reuse a value already present in
     /// `history`. Checks that backtracking correctly prunes branches based on sibling state.
+    #[derive(Clone)]
     struct DistinctPermutations {
         n: u8,
     }
@@ -217,6 +257,20 @@ mod tests {
         }
     }
 
+    #[cfg(feature = "parallel")]
+    #[test]
+    fn parallel_search_yields_the_same_solutions_as_sequential_search() {
+        use rayon::iter::ParallelIterator;
+
+        let mut sequential: Vec<_> = Solutions::new(DistinctPermutations { n: 4 }).collect();
+        let mut parallel: Vec<_> = parallel_solutions(DistinctPermutations { n: 4 }).collect();
+
+        sequential.sort();
+        parallel.sort();
+        assert_eq!(sequential, parallel);
+        assert_eq!(24, parallel.len()); // 4! permutations
+    }
+
     /// Tracks a running sum as cached state via `what_if`/`undo`, and cross checks it against a
     /// sum computed fresh from `history` on every candidate solution. This exercises that
     /// `Solutions` unwinds (`undo`s) and replays (`what_if`s) the cache correctly when