From d226601a44eaa32a6dd99bcb214bb69a491e9c1f Mon Sep 17 00:00:00 2001
From: Stephen Waits <steve@waits.net>
Date: Mon, 4 May 2026 19:16:43 -0600
Subject: [PATCH] feat(core): add Problem trait
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The single trait users implement to describe an optimization problem:
associated `Decision: Clone` plus `objectives()` and `evaluate()`.
Both signatures match spec §8.1; `evaluate` takes `&self`.
---
 src/core/mod.rs     |  2 ++
 src/core/problem.rs | 27 +++++++++++++++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100644 src/core/problem.rs

diff --git a/src/core/mod.rs b/src/core/mod.rs
index 498b5ff..f8f4f55 100644
--- a/src/core/mod.rs
+++ b/src/core/mod.rs
@@ -4,6 +4,7 @@ pub mod candidate;
 pub mod evaluation;
 pub mod objective;
 pub mod population;
+pub mod problem;
 pub mod result;
 pub mod rng;
 
@@ -11,5 +12,6 @@ pub use candidate::*;
 pub use evaluation::*;
 pub use objective::*;
 pub use population::*;
+pub use problem::*;
 pub use result::*;
 pub use rng::*;
diff --git a/src/core/problem.rs b/src/core/problem.rs
new file mode 100644
index 0000000..0388ef3
--- /dev/null
+++ b/src/core/problem.rs
@@ -0,0 +1,27 @@
+//! The user-implemented `Problem` trait.
+
+use crate::core::evaluation::Evaluation;
+use crate::core::objective::ObjectiveSpace;
+
+/// An optimization problem.
+///
+/// Implement this trait to describe what the optimizer is allowed to vary
+/// (`Decision`), how many objectives it has (`objectives`), and how to score a
+/// decision (`evaluate`).
+///
+/// Example decision types: `Vec<f64>`, `Vec<bool>`, `Vec<i64>`, custom domain
+/// structs, or permutations represented as `Vec<usize>`.
+pub trait Problem {
+    /// The thing the optimizer changes. Must be `Clone` because heuristic
+    /// algorithms routinely clone decisions.
+    type Decision: Clone;
+
+    /// Return the objectives for this problem.
+    ///
+    /// Returned by value for ergonomics — problems do not need to store an
+    /// `ObjectiveSpace` field.
+    fn objectives(&self) -> ObjectiveSpace;
+
+    /// Evaluate a decision. Must not mutate `self`.
+    fn evaluate(&self, decision: &Self::Decision) -> Evaluation;
+}