From 75c3ea4ab5011ea5bf1cdb5bec875ebaa6cb2d8c Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Wed, 7 Jan 2026 17:17:10 -0800
Subject: [PATCH 1/7] switching penalty

---
 README.md                           | 21 +++++++++
 cmd/solver/cli.cpp                  |  6 +++
 include/jres_solver/jres_solver.hpp |  6 +++
 src/jres_json_converter.cpp         |  3 ++
 src/jres_standard_solver.cpp        | 22 ++++++++++
 test/CMakeLists.txt                 |  1 +
 test/test_switching_penalty.cpp     | 68 +++++++++++++++++++++++++++++
 7 files changed, 127 insertions(+)
 create mode 100644 test/test_switching_penalty.cpp

diff --git a/README.md b/README.md
index f24fe28..b17bb10 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,18 @@ These structs are used to represent the availability of team members.
 | `teamMembers` | `JresTeamMember*` | A pointer to an array of team members, including their tzOffset. |
 | `teamMembers_len` | `int` | The number of team members. |
 
+`JresSolverOptions`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `timeLimit` | `int` | Maximum time in seconds to let the solver run. |
+| `spotterMode` | `JresSpotterMode` | Type of spotter scheduling to use (`NONE`, `INTEGRATED`, `SEQUENTIAL`). |
+| `allowNoSpotter` | `bool` | Allow stints to have no spotter assigned. |
+| `optimalityGap` | `double` | Solver stops when the gap to optimal is less than this (e.g., `0.2`). |
+| `switchingPenalty`| `double` | Penalty applied when switching drivers between stints (default: `0.0`). |
+| `roleCouplingWeight`| `double` | Weight for coupling driver and spotter roles (default: `0.0`). |
+| `rotationBeatWeight`| `double` | Weight for adhering to a rotation beat or fairness metric (default: `0.0`). |
+
 `JresScheduleEntry`
 
 | Field | Type | Description |
@@ -99,6 +111,7 @@ options.timeLimit = 5;
 options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
 options.allowNoSpotter = false;
 options.optimalityGap = 0.2;
+options.switchingPenalty = 10.0; // Encourage longer driver shifts
 
 // Create input struct from JSON
 JresSolverInput* input = jres_input_from_json(raceDataJson);
@@ -140,6 +153,14 @@ Mixed Integer Programming problems like race scheduling are NP-hard. The solver
 
 The solver prioritizes hard constraints (rest times, fuel, availability) first. The optimality gap only affects soft preferences like minimizing consecutive stints. A 20% gap on these preferences is imperceptible in real-world use.
 
+#### Switching Penalty
+
+The `switchingPenalty` option adds a cost to the optimization objective every time the driver changes between two consecutive stints.
+
+*   **Goal**: To encourage the solver to keep the same driver in the car for multiple stints (e.g., doing a "double stint"), even if it's not strictly required by the `maxStints` constraint.
+*   **Relationship to `maxStints`**: While `maxStints` is a **hard constraint** (the solver *cannot* exceed it), the `switchingPenalty` is a **soft incentive**. It helps avoid "unnecessary" driver changes that might otherwise have equal cost to the solver.
+*   **Recommended Value**: Start with `10.0`. If the solver still switches drivers too often for your preference, increase it. If it starts violating preferred availability slots just to avoid a switch, decrease it.
+
 -----
 
 ### JSON Helper Functions
diff --git a/cmd/solver/cli.cpp b/cmd/solver/cli.cpp
index 6e9de82..2e41e82 100644
--- a/cmd/solver/cli.cpp
+++ b/cmd/solver/cli.cpp
@@ -35,6 +35,9 @@ int main(int argc, char **argv)
         ("s,spotter-mode", "Method for scheduling spotters (none, integrated, sequential).", cxxopts::value<std::string>()->default_value("none"))
         ("allow-no-spotter", "Allow stints to have no spotter assigned.", cxxopts::value<bool>()->default_value("false"))
         ("g,optimality-gap", "Solver stops when the gap to optimal is less than this (e.g., 0.2 for 20%).", cxxopts::value<double>()->default_value("0.2"))
+        ("switching-penalty", "Penalty for switching drivers.", cxxopts::value<double>()->default_value("0.0"))
+        ("role-coupling-weight", "Weight for role coupling incentives.", cxxopts::value<double>()->default_value("0.0"))
+        ("rotation-beat-weight", "Weight for rotation/fairness adherence.", cxxopts::value<double>()->default_value("0.0"))
         ("d,diagnose", "Run diagnostics to explain why a schedule is infeasible.", cxxopts::value<bool>()->default_value("false"))
         ("v,version", "Print version information and exit.")
         ("h,help", "Print usage.");
@@ -113,6 +116,9 @@ int main(int argc, char **argv)
 
     solverOptions.allowNoSpotter = result["allow-no-spotter"].as<bool>();
     solverOptions.optimalityGap = result["optimality-gap"].as<double>();
+    solverOptions.switchingPenalty = result["switching-penalty"].as<double>();
+    solverOptions.roleCouplingWeight = result["role-coupling-weight"].as<double>();
+    solverOptions.rotationBeatWeight = result["rotation-beat-weight"].as<double>();
 
     // Call the Solver Library
     JresSolverInput* solverInput = jres_input_from_json(raceDataJsonString.c_str());
diff --git a/include/jres_solver/jres_solver.hpp b/include/jres_solver/jres_solver.hpp
index 234f29a..c6167e9 100644
--- a/include/jres_solver/jres_solver.hpp
+++ b/include/jres_solver/jres_solver.hpp
@@ -60,6 +60,12 @@ struct JresSolverOptions {
     bool allowNoSpotter;
     /** @brief The solver will terminate when the gap between the primal and dual objective bound is less than this value. */
     double optimalityGap;
+    /** @brief Penalty applied when switching drivers between stints (default: 0.0). */
+    double switchingPenalty;
+    /** @brief Weight for coupling driver and spotter roles (e.g. proximity or same-person) (default: 0.0). */
+    double roleCouplingWeight;
+    /** @brief Weight for adhering to a rotation beat or fairness metric (default: 0.0). */
+    double rotationBeatWeight;
 };
 
 /**
diff --git a/src/jres_json_converter.cpp b/src/jres_json_converter.cpp
index 7739332..8ea592c 100644
--- a/src/jres_json_converter.cpp
+++ b/src/jres_json_converter.cpp
@@ -182,6 +182,9 @@ JRES_SOLVER_API char* jres_output_to_json(const JresSolverOutput* output) {
             options_json["spotterMode"] = to_string(output->options->spotterMode);
             options_json["allowNoSpotter"] = output->options->allowNoSpotter;
             options_json["optimalityGap"] = output->options->optimalityGap;
+            options_json["switchingPenalty"] = output->options->switchingPenalty;
+            options_json["roleCouplingWeight"] = output->options->roleCouplingWeight;
+            options_json["rotationBeatWeight"] = output->options->rotationBeatWeight;
             j["options"] = options_json;
         }
 
diff --git a/src/jres_standard_solver.cpp b/src/jres_standard_solver.cpp
index 96c9d9f..e14b993 100644
--- a/src/jres_standard_solver.cpp
+++ b/src/jres_standard_solver.cpp
@@ -542,6 +542,28 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     // --- Incentivize Consecutive Stints ---
     add_consecutive_incentive(m_highs.get(), m_driverPool, m_driverWorkVars, m_input.stints.size(), kRewardConsecutive);
 
+    // --- Switching Penalty ---
+    if (m_options.switchingPenalty > 0.0) {
+        for (size_t s = 1; s < m_input.stints.size(); ++s) {
+            int switchVar = m_highs->getNumCol();
+            m_highs->addVar(0.0, 1.0);
+            m_highs->changeColIntegrality(switchVar, HighsVarType::kInteger);
+            m_highs->changeColCost(switchVar, m_options.switchingPenalty);
+
+            // Constraint: switchVar >= driver_s - driver_{s-1} for each driver
+            // switchVar - driver_s + driver_{s-1} >= 0
+            for (const auto& p : m_driverPool) {
+                if (m_driverWorkVars.count({p.name, s}) && m_driverWorkVars.count({p.name, s - 1})) {
+                    int var_s = m_driverWorkVars.at({p.name, s});
+                    int var_prev = m_driverWorkVars.at({p.name, s - 1});
+                    
+                    std::vector<int> idx = {switchVar, var_s, var_prev};
+                    std::vector<double> val = {1.0, -1.0, 1.0};
+                    m_highs->addRow(0.0, kHighsInf, 3, idx.data(), val.data());
+                }
+            }
+        }
+    }
 
     // --- Spotter Model (Integrated or Sequential) ---
     if (m_options.spotterMode == JRES_SPOTTER_MODE_INTEGRATED) {
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index cc57a23..7e5f5ff 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -32,6 +32,7 @@ add_executable(solver_tests
   test_optimization.cpp
   test_minimum_rest.cpp
   test_fair_share.cpp
+  test_switching_penalty.cpp
 )
 
 add_dependencies(solver_tests jres_solver_lib)
diff --git a/test/test_switching_penalty.cpp b/test/test_switching_penalty.cpp
new file mode 100644
index 0000000..80172fa
--- /dev/null
+++ b/test/test_switching_penalty.cpp
@@ -0,0 +1,68 @@
+#include "gtest/gtest.h"
+#include "jres_solver/jres_solver.hpp"
+#include "nlohmann/json.hpp"
+#include <vector>
+#include <string>
+#include <set>
+
+using json = nlohmann::json;
+
+TEST(SwitchingPenaltyTest, ForceMinimumSwitches) {
+    // Scenario: 3 Stints, 2 Drivers.
+    // Both Available for all.
+    // Fair Share forces both to drive at least 1 stint (total 3h, fair share ~0.375h).
+    // Without penalty, fairness balancing (kCostFairness) might favor Alternating (A, B, A) or (A, A, B).
+    // With HIGH Switching Penalty, we force (A, A, B) or (B, B, A) -> 1 Switch.
+    // (A, B, A) -> 2 Switches.
+    
+    json j;
+    j["success"] = true;
+    j["teamMembers"] = {
+        {{"name", "Driver A"}, {"isDriver", true}, {"isSpotter", false}, {"maxStints", 3}, {"minimumRestHours", 0}},
+        {{"name", "Driver B"}, {"isDriver", true}, {"isSpotter", false}, {"maxStints", 3}, {"minimumRestHours", 0}}
+    };
+    j["stints"] = {
+        {{"id", 1}, {"startTime", "2026-01-17T00:00:00.000Z"}, {"endTime", "2026-01-17T01:00:00.000Z"}},
+        {{"id", 2}, {"startTime", "2026-01-17T01:00:00.000Z"}, {"endTime", "2026-01-17T02:00:00.000Z"}},
+        {{"id", 3}, {"startTime", "2026-01-17T02:00:00.000Z"}, {"endTime", "2026-01-17T03:00:00.000Z"}}
+    };
+    j["availability"] = json::object(); // All available
+    j["firstStintDriver"] = nullptr;
+
+    JresSolverOptions options;
+    options.timeLimit = 5;
+    options.spotterMode = JRES_SPOTTER_MODE_NONE;
+    options.allowNoSpotter = true;
+    options.optimalityGap = 0.0;
+    options.switchingPenalty = 1000.0; // High penalty
+
+    std::string json_str = j.dump();
+    JresSolverInput* input = jres_input_from_json(json_str.c_str());
+    ASSERT_NE(input, nullptr);
+
+    JresSolverOutput* output = solve_race_schedule(input, &options);
+    ASSERT_NE(output, nullptr);
+    ASSERT_EQ(output->schedule_len, 3);
+
+    // Calculate switches
+    int switches = 0;
+    for (int i = 1; i < output->schedule_len; ++i) {
+        if (std::string(output->schedule[i].driver) != std::string(output->schedule[i-1].driver)) {
+            switches++;
+        }
+    }
+
+    // Since Fair Share forces both to drive, min switches = 1 (e.g. AAB).
+    // If penalty works, we should not see A-B-A (2 switches).
+    EXPECT_EQ(switches, 1) << "Should minimize switches to 1 (e.g. AAB or BBA)";
+
+    // Verify both drivers drove (Fair Share check)
+    std::set<std::string> drivers;
+    for (int i = 0; i < output->schedule_len; ++i) {
+        drivers.insert(output->schedule[i].driver);
+    }
+    EXPECT_EQ(drivers.size(), 2) << "Both drivers must drive due to Fair Share rule";
+
+    free_jres_solver_input(input);
+    free_jres_solver_output(output);
+}

From 136c479e21fe797e6b0f706d214395323bf17723 Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Wed, 7 Jan 2026 18:28:30 -0800
Subject: [PATCH 2/7] role coupling

---
 src/jres_standard_solver.cpp |  87 +++++++++++++++++-------------
 test/CMakeLists.txt          |   1 +
 test/test_role_coupling.cpp  | 100 +++++++++++++++++++++++++++++++++++
 3 files changed, 152 insertions(+), 36 deletions(-)
 create mode 100644 test/test_role_coupling.cpp

diff --git a/src/jres_standard_solver.cpp b/src/jres_standard_solver.cpp
index e14b993..9c1da66 100644
--- a/src/jres_standard_solver.cpp
+++ b/src/jres_standard_solver.cpp
@@ -52,6 +52,39 @@ static void add_consecutive_incentive(
     }
 }
 
+static void add_role_coupling_incentive(
+    Highs* highs,
+    const std::vector<jres::internal::TeamMember>& pool,
+    const std::map<std::pair<std::string, int>, int>& driverVars,
+    const std::map<std::pair<std::string, int>, int>& spotterVars,
+    size_t numStints,
+    double weight)
+{
+    if (std::abs(weight) < 1e-6) return;
+
+    for (const auto &p : pool) {
+        for (size_t s = 0; s < numStints - 1; ++s) {
+            bool hasDriver = driverVars.count({p.name, s});
+            bool hasSpotter = spotterVars.count({p.name, s + 1});
+
+            if (hasDriver && hasSpotter) {
+                int d_var = driverVars.at({p.name, s});
+                int s_var = spotterVars.at({p.name, s + 1});
+
+                int coupling_var = highs->getNumCol();
+                highs->addVar(0.0, 1.0);
+                highs->changeColIntegrality(coupling_var, HighsVarType::kInteger);
+                highs->changeColCost(coupling_var, -weight);
+
+                // z <= d_var
+                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{coupling_var, d_var}.data(), std::vector<double>{1.0, -1.0}.data());
+                // z <= s_var
+                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{coupling_var, s_var}.data(), std::vector<double>{1.0, -1.0}.data());
+            }
+        }
+    }
+}
+
 JresStandardSolver::JresStandardSolver(const jres::internal::SolverInput& input, const JresSolverOptions& options)
     : JresSolverBase(input, options)
 {
@@ -576,6 +609,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         
         add_participant_model(*m_highs, m_spotterPool, m_spotterWorkVars);
         add_consecutive_incentive(m_highs.get(), m_spotterPool, m_spotterWorkVars, m_input.stints.size(), kRewardConsecutive);
+        add_role_coupling_incentive(m_highs.get(), m_driverPool, m_driverWorkVars, m_spotterWorkVars, m_input.stints.size(), m_options.roleCouplingWeight);
 
         // Spotter Coverage
         for (size_t s = 0; s < m_input.stints.size(); ++s) {
@@ -755,50 +789,31 @@ jres::internal::SolverOutput JresStandardSolver::solve()
                 }
             }
 
-            // Incentivize Spotting Adjacent to Driving (Proximity Reward)
+            // Incentivize Spotting Adjacent to Driving (Proximity & Role Coupling)
             for (const auto& p : m_spotterPool) {
                 for (size_t s = 0; s < m_input.stints.size(); ++s) {
                     if (!m_spotterWorkVars.count({p.name, s})) continue;
                     
-                    bool adjacentDrive = false;
-                    // Check s-1
-                    if (s > 0) {
-                        if (output.schedule[s-1].driver == p.name) adjacentDrive = true;
+                    double additionalReward = 0.0;
+                    
+                    // Check s-1: Driver(s-1) -> Spotter(s) [Role Coupling]
+                    if (s > 0 && output.schedule[s-1].driver == p.name) {
+                         if (std::abs(m_options.roleCouplingWeight) > 1e-6) {
+                             additionalReward += -m_options.roleCouplingWeight;
+                         } else {
+                             additionalReward += kRewardProximity;
+                         }
                     }
-                    // Check s+1
-                    if (s < m_input.stints.size() - 1) {
-                        if (output.schedule[s+1].driver == p.name) adjacentDrive = true;
+                    
+                    // Check s+1: Spotter(s) -> Driver(s+1) [Proximity]
+                    if (s < m_input.stints.size() - 1 && output.schedule[s+1].driver == p.name) {
+                        additionalReward += kRewardProximity;
                     }
 
-                    if (adjacentDrive) {
+                    if (std::abs(additionalReward) > 1e-6) {
                         int varIdx = m_spotterWorkVars.at({p.name, s});
-                        // Get current cost
-                        double currentCost = 0.0;
-                        // Getting current cost is not directly supported by simple API in all versions, 
-                        // but we know we set it based on preference/unavailability.
-                        // We can just add a separate term or modify existing.
-                        // HiGHS `changeColCost` sets the absolute cost.
-                        // We should retrieve it first? Or assume base costs.
-                        // Let's assume we can query it? No simple getColCost in the minimal binding I recall.
-                        // However, we know the cost construction logic: 
-                        // Unavailable(1e6) | Preferred(-1) | Neutral(0).
-                        
-                        // Let's just track it or blindly apply offset if we know it's not unavailable.
-                        // We shouldn't incentivize unavailable slots.
                         
-                        // Re-check availability
-                        bool isUnavailable = false; 
-                         // ... (Availability lookup logic duplicated or helper needed?)
-                         // Actually, we can check if it's already "Unavailable" penalty.
-                         // But we don't have easy access to the cost.
-                         
-                         // Safer: Re-evaluate availability or trust that if it's unavailable, the 1M penalty swamps this -0.5.
-                         // Yes, 1,000,000 - 0.5 is still huge.
-                         
-                         // How to add? `changeColCost` replaces. 
-                         // We don't want to overwrite "Preferred".
-                         // We can look up availability again.
-                         
+                        // Re-calculate base cost to ensure we add to it
                          std::string availabilityKey = jres::internal::TimeHelpers::timePointToKey(jres::internal::TimeHelpers::stringToTimePoint(m_input.stints[s].startTime));
                          bool isPreferred = false;
                          bool isUnavailableExplicit = false;
@@ -815,7 +830,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
                          if (isUnavailableExplicit) newCost = kPenaltyUnavailable;
                          else if (isPreferred) newCost = kRewardPreferred;
                          
-                         newCost += kRewardProximity; // Add the incentive
+                         newCost += additionalReward;
                          
                          spotterSolver.changeColCost(varIdx, newCost);
                     }
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 7e5f5ff..abe0ba3 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -33,6 +33,7 @@ add_executable(solver_tests
   test_minimum_rest.cpp
   test_fair_share.cpp
   test_switching_penalty.cpp
+  test_role_coupling.cpp
 )
 
 add_dependencies(solver_tests jres_solver_lib)
diff --git a/test/test_role_coupling.cpp b/test/test_role_coupling.cpp
new file mode 100644
index 0000000..86387b8
--- /dev/null
+++ b/test/test_role_coupling.cpp
@@ -0,0 +1,100 @@
+#include "gtest/gtest.h"
+#include "jres_solver/jres_solver.hpp"
+#include "nlohmann/json.hpp"
+#include <vector>
+#include <string>
+
+using json = nlohmann::json;
+
+TEST(RoleCouplingTest, SelectionLogic) {
+    // Scenario: 3 People: A, B, C.
+    // A: Driver+Spotter, Max 1 stint.
+    // B: Driver+Spotter, Max 1 stint.
+    // C: Spotter Only.
+    //
+    // Stint 1: A drives (forced by B unavailable).
+    // Stint 2: B drives (A maxed).
+    //
+    // Spotter S2 Candidates:
+    // - A (Finished driving S1). Available.
+    // - C (Always available).
+    //
+    // Logic:
+    // Without Role Coupling, A and C are equal cost (0). Solver picks arbitrary (often first or alphabetical).
+    // With Role Coupling, A gets a huge reward (-100) for "Driver(S1) -> Spotter(S2)".
+    // So Solver MUST pick A.
+
+    json j;
+    j["success"] = true;
+    j["teamMembers"] = {
+        {{"name", "A"}, {"isDriver", true}, {"isSpotter", true}, {"maxStints", 1}, {"minimumRestHours", 0}},
+        {{"name", "B"}, {"isDriver", true}, {"isSpotter", true}, {"maxStints", 1}, {"minimumRestHours", 0}},
+        {{"name", "C"}, {"isDriver", false}, {"isSpotter", true}, {"maxStints", 99}, {"minimumRestHours", 0}}
+    };
+    j["stints"] = {
+        {{"id", 1}, {"startTime", "2026-01-17T00:00:00.000Z"}, {"endTime", "2026-01-17T01:00:00.000Z"}},
+        {{"id", 2}, {"startTime", "2026-01-17T01:00:00.000Z"}, {"endTime", "2026-01-17T02:00:00.000Z"}}
+    };
+    
+    // Availability: 
+    // S1: B Unavailable (Forces A to drive).
+    j["availability"] = {
+        {"A", {{"2026-01-17T00:00:00.000Z", "Available"}, {"2026-01-17T01:00:00.000Z", "Available"}}},
+        {"B", {{"2026-01-17T00:00:00.000Z", "Unavailable"}, {"2026-01-17T01:00:00.000Z", "Available"}}},
+        {"C", {{"2026-01-17T00:00:00.000Z", "Available"}, {"2026-01-17T01:00:00.000Z", "Available"}}}
+    };
+    j["firstStintDriver"] = nullptr;
+    
+    std::string json_str = j.dump();
+    JresSolverInput* input = jres_input_from_json(json_str.c_str());
+    ASSERT_NE(input, nullptr);
+
+    // --- Integrated Mode ---
+    {
+        JresSolverOptions options;
+        options.timeLimit = 5;
+        options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
+        options.allowNoSpotter = false;
+        options.optimalityGap = 0.0;
+        options.roleCouplingWeight = 100.0; 
+
+        JresSolverOutput* output = solve_race_schedule(input, &options);
+        ASSERT_NE(output, nullptr);
+        ASSERT_EQ(output->schedule_len, 2);
+
+        // Verify Driving Schedule
+        EXPECT_STREQ(output->schedule[0].driver, "A");
+        EXPECT_STREQ(output->schedule[1].driver, "B");
+
+        // Verify Spotting Schedule
+        // S2 Spotter should be A
+        EXPECT_STREQ(output->schedule[1].spotter, "A") << "Integrated: A should spot S2 after driving S1";
+
+        free_jres_solver_output(output);
+    }
+
+    // --- Sequential Mode ---
+    {
+        JresSolverOptions options;
+        options.timeLimit = 5;
+        options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
+        options.allowNoSpotter = false;
+        options.optimalityGap = 0.0;
+        options.roleCouplingWeight = 100.0; 
+
+        JresSolverOutput* output = solve_race_schedule(input, &options);
+        ASSERT_NE(output, nullptr);
+        ASSERT_EQ(output->schedule_len, 2);
+
+        // Verify Driving Schedule
+        EXPECT_STREQ(output->schedule[0].driver, "A");
+        EXPECT_STREQ(output->schedule[1].driver, "B");
+
+        // Verify Spotting Schedule
+        EXPECT_STREQ(output->schedule[1].spotter, "A") << "Sequential: A should spot S2 after driving S1";
+
+        free_jres_solver_output(output);
+    }
+
+    free_jres_solver_input(input);
+}

From a8be46f6f9205ef700489bfb0624ede3dbe0c972 Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Wed, 7 Jan 2026 18:31:48 -0800
Subject: [PATCH 3/7] rotation beat

---
 src/jres_standard_solver.cpp |  34 +++++++++
 test/CMakeLists.txt          |   1 +
 test/test_rotation_beat.cpp  | 135 +++++++++++++++++++++++++++++++++++
 3 files changed, 170 insertions(+)
 create mode 100644 test/test_rotation_beat.cpp

diff --git a/src/jres_standard_solver.cpp b/src/jres_standard_solver.cpp
index 9c1da66..0153bb3 100644
--- a/src/jres_standard_solver.cpp
+++ b/src/jres_standard_solver.cpp
@@ -598,6 +598,40 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         }
     }
 
+    // --- Rotation Beat (Rhythm) Incentive ---
+    if (m_options.rotationBeatWeight > 1e-6) {
+        const size_t N = m_driverPool.size();
+        if (N > 0 && m_input.stints.size() > N) {
+            for (size_t s = N; s < m_input.stints.size(); ++s) {
+                size_t target_s = s % N;
+                
+                for (const auto& p : m_driverPool) {
+                    if (m_driverWorkVars.count({p.name, s}) && m_driverWorkVars.count({p.name, target_s})) {
+                        int var_current = m_driverWorkVars.at({p.name, s});
+                        int var_target = m_driverWorkVars.at({p.name, target_s});
+
+                        // Create deviation variable d >= |current - target|
+                        // We minimize d, so cost is +weight
+                        int devVar = m_highs->getNumCol();
+                        m_highs->addVar(0.0, 1.0);
+                        // Relaxed to continuous is fine for deviation between binary vars
+                        m_highs->changeColCost(devVar, m_options.rotationBeatWeight);
+
+                        // 1. d >= current - target  =>  d - current + target >= 0
+                        m_highs->addRow(0.0, kHighsInf, 3, 
+                            std::vector<int>{devVar, var_current, var_target}.data(), 
+                            std::vector<double>{1.0, -1.0, 1.0}.data());
+
+                        // 2. d >= target - current  =>  d + current - target >= 0
+                        m_highs->addRow(0.0, kHighsInf, 3, 
+                            std::vector<int>{devVar, var_current, var_target}.data(), 
+                            std::vector<double>{1.0, 1.0, -1.0}.data());
+                    }
+                }
+            }
+        }
+    }
+
     // --- Spotter Model (Integrated or Sequential) ---
     if (m_options.spotterMode == JRES_SPOTTER_MODE_INTEGRATED) {
         if (m_spotterPool.empty() && !m_options.allowNoSpotter) {
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index abe0ba3..9d31e36 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -34,6 +34,7 @@ add_executable(solver_tests
   test_fair_share.cpp
   test_switching_penalty.cpp
   test_role_coupling.cpp
+  test_rotation_beat.cpp
 )
 
 add_dependencies(solver_tests jres_solver_lib)
diff --git a/test/test_rotation_beat.cpp b/test/test_rotation_beat.cpp
new file mode 100644
index 0000000..8eb747c
--- /dev/null
+++ b/test/test_rotation_beat.cpp
@@ -0,0 +1,135 @@
+#include "gtest/gtest.h"
+#include "jres_solver/jres_solver.hpp"
+#include "nlohmann/json.hpp"
+#include <vector>
+#include <string>
+
+using json = nlohmann::json;
+
+TEST(RotationBeatTest, EnforcesPattern) {
+    // Scenario: 3 Drivers (A, B, C). 6 Stints.
+    // N = 3.
+    // Stint 0, 1, 2: A, B, C (forced by Preference or availability)
+    // Stint 3, 4, 5: Must follow A, B, C pattern if Rotation Beat is high.
+    
+    // Setup:
+    // Stint 0: A (Preferred), B (Available), C (Available)
+    // Stint 1: B (Preferred), A (Available), C (Available)
+    // Stint 2: C (Preferred), A (Available), B (Available)
+    // This establishes A, B, C for 0-2.
+    
+    // Stint 3: A (Available) -> Matches Stint 0 (A).
+    // Stint 4: A (Preferred!), B (Available).
+    //    - Without Beat: Solver picks A (Preferred).
+    //    - With Beat: Solver picks B (Available) to match Stint 1 (B).
+    // Stint 5: C (Available). Matches Stint 2 (C).
+
+    json j;
+    j["success"] = true;
+    
+    std::vector<std::string> names = {"Driver A", "Driver B", "Driver C"};
+    json members = json::array();
+    for (const auto& name : names) {
+        members.push_back({
+            {"name", name},
+            {"isDriver", true},
+            {"isSpotter", false},
+            {"maxStints", 1}, // Disable consecutive bonus to isolate pattern logic
+            {"minimumRestHours", 0}
+        });
+    }
+    j["teamMembers"] = members;
+
+    json stints = json::array();
+    for (int i = 0; i < 6; ++i) {
+        stints.push_back({
+            {"id", i + 1},
+            {"startTime", "2026-01-17T0" + std::to_string(i) + ":00:00.000Z"},
+            {"endTime", "2026-01-17T0" + std::to_string(i+1) + ":00:00.000Z"}
+        });
+    }
+    j["stints"] = stints;
+
+    json avail = json::object();
+    // Default everyone to Available
+    for (const auto& name : names) {
+        json times = json::object();
+        for (int i = 0; i < 6; ++i) {
+            std::string t = "2026-01-17T0" + std::to_string(i) + ":00:00.000Z";
+            times[t] = "Available";
+        }
+        avail[name] = times;
+    }
+    j["availability"] = avail;
+
+    // Apply Specific Preferences
+    // Stint 0 (00:00): A Preferred
+    j["availability"]["Driver A"]["2026-01-17T00:00:00.000Z"] = "Preferred";
+    // Stint 1 (01:00): B Preferred
+    j["availability"]["Driver B"]["2026-01-17T01:00:00.000Z"] = "Preferred";
+    // Stint 2 (02:00): C Preferred
+    j["availability"]["Driver C"]["2026-01-17T02:00:00.000Z"] = "Preferred";
+
+    // Stint 4 (04:00): A Preferred (Trap!)
+    j["availability"]["Driver A"]["2026-01-17T04:00:00.000Z"] = "Preferred";
+
+    std::string json_str = j.dump();
+    JresSolverInput* input = jres_input_from_json(json_str.c_str());
+    ASSERT_NE(input, nullptr);
+
+    // --- Case 1: Without Rotation Beat ---
+    {
+        JresSolverOptions options;
+        options.timeLimit = 5;
+        options.spotterMode = JRES_SPOTTER_MODE_NONE;
+        options.allowNoSpotter = true;
+        options.optimalityGap = 0.0;
+        options.rotationBeatWeight = 0.0;
+
+        JresSolverOutput* output = solve_race_schedule(input, &options);
+        ASSERT_NE(output, nullptr);
+        ASSERT_EQ(output->schedule_len, 6);
+
+        // Expect A, B, C for first 3 (due to preferences)
+        EXPECT_STREQ(output->schedule[0].driver, "Driver A");
+        EXPECT_STREQ(output->schedule[1].driver, "Driver B");
+        EXPECT_STREQ(output->schedule[2].driver, "Driver C");
+
+        // Stint 4: A should be picked because A prefers it (-1 cost vs 0)
+        EXPECT_STREQ(output->schedule[4].driver, "Driver A") << "Without beat, A should drive Stint 4 (Preferred)";
+
+        free_jres_solver_output(output);
+    }
+
+    // --- Case 2: With Rotation Beat ---
+    {
+        JresSolverOptions options;
+        options.timeLimit = 5;
+        options.spotterMode = JRES_SPOTTER_MODE_NONE;
+        options.allowNoSpotter = true;
+        options.optimalityGap = 0.0;
+        options.rotationBeatWeight = 10.0; // Strong penalty
+
+        JresSolverOutput* output = solve_race_schedule(input, &options);
+        ASSERT_NE(output, nullptr);
+        ASSERT_EQ(output->schedule_len, 6);
+
+        // Expect A, B, C for first 3
+        EXPECT_STREQ(output->schedule[0].driver, "Driver A");
+        EXPECT_STREQ(output->schedule[1].driver, "Driver B");
+        EXPECT_STREQ(output->schedule[2].driver, "Driver C");
+
+        // Stint 3: Should match Stint 0 (A)
+        EXPECT_STREQ(output->schedule[3].driver, "Driver A");
+        
+        // Stint 4: Should match Stint 1 (B), overcoming A's preference
+        EXPECT_STREQ(output->schedule[4].driver, "Driver B") << "With beat, B should drive Stint 4 to match Stint 1";
+        
+        // Stint 5: Should match Stint 2 (C)
+        EXPECT_STREQ(output->schedule[5].driver, "Driver C");
+
+        free_jres_solver_output(output);
+    }
+
+    free_jres_solver_input(input);
+}

From 6df1352d77cd65af11162813f103216f2b6cbb5f Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Wed, 7 Jan 2026 21:39:14 -0800
Subject: [PATCH 4/7] updated documentation for advanced options

---
 README.md          | 12 ++++++++++++
 TOOLS.md           |  3 +++
 cmd/solver/cli.cpp | 23 ++++++++++++++---------
 3 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index b17bb10..f98789d 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,18 @@ This library can be used to solve for optimal driver and spotter schedules for e
 * **[Tools](./TOOLS.md)** - releases include some command line tools that use the library
 * **[Development](./CONTRIBUTING.md)** - instructions for development of the library
 
+## CLI Quick Start
+
+The `jres_solver` tool supports several optimization parameters:
+
+*   **General:** `-i` (Input), `-o` (Output), `-t` (Time Limit), `-s` (Spotter Mode)
+*   **Advanced Weights:**
+    *   `--switching-penalty`: Cost for driver swaps (positive disincentivizes switching)
+    *   `--role-coupling-weight`: Incentive for role coupling (positive incentivizes coupling)
+    *   `--rotation-beat-weight`: Penalty for fairness deviation (positive incentivizes adherence)
+
+See [TOOLS.md](./TOOLS.md) for full usage.
+
 ## The Library
 
 **JresSolver** is a C++ library designed to optimize endurance racing schedules. It uses the **HiGHS** Mixed Integer Programming (MIP) solver to assign drivers (and optional spotters) to race stints while satisfying constraints such as fuel usage, maximum drive times, minimum rest periods, and driver availability.
diff --git a/TOOLS.md b/TOOLS.md
index 52782e2..14e966e 100644
--- a/TOOLS.md
+++ b/TOOLS.md
@@ -53,6 +53,9 @@ jres_solver.exe [options]
 | `-s` | `--spotter-mode`     | Strategy for assigning spotters. Options: `none`, `integrated`, `sequential`.                 | `none`  |
 |      | `--allow-no-spotter` | Allow specific stints to have no spotter assigned (if spotter mode is active).                | `false` |
 | `-g` | `--optimality-gap`   | Stop solver when the solution is within this gap of perfection (e.g., `0.2` for 20%).         | `0.2`   |
+|      | `--switching-penalty`| Penalty cost for switching drivers (positive disincentivizes switching).                      | `0.0`   |
+|      | `--role-coupling-weight`| Reward weight for coupling roles (positive incentivizes driver->spotter).                  | `0.0`   |
+|      | `--rotation-beat-weight`| Penalty weight for rotation deviation (positive incentivizes adherence).                   | `0.0`   |
 | `-d` | `--diagnose`         | Run in **Diagnostic Mode** to explain why a schedule is infeasible.                           | `false` |
 | `-h` | `--help`             | Print usage instructions.                                                                     |         |
 
diff --git a/cmd/solver/cli.cpp b/cmd/solver/cli.cpp
index 2e41e82..1b70a2c 100644
--- a/cmd/solver/cli.cpp
+++ b/cmd/solver/cli.cpp
@@ -27,21 +27,26 @@ int main(int argc, char **argv)
 {
     // --- Parse Command-Line Arguments ---
     cxxopts::Options options("solver", "JRES endurance race solver.");
-    options.add_options()
+    
+    options.add_options("General")
         ("i,input", "Path to the race data .json file. Reads from stdin if not provided.", cxxopts::value<std::string>())
         ("o,output", "Optional. Path to save the schedule as a JSON file.", cxxopts::value<std::string>())
-        ("t,time-limit", "Maximum time in seconds to let the solver run.", cxxopts::value<int>()->default_value("5"))
         ("q,quiet", "Suppress INFO logs and final schedule print-out.", cxxopts::value<bool>()->default_value("false"))
-        ("s,spotter-mode", "Method for scheduling spotters (none, integrated, sequential).", cxxopts::value<std::string>()->default_value("none"))
-        ("allow-no-spotter", "Allow stints to have no spotter assigned.", cxxopts::value<bool>()->default_value("false"))
-        ("g,optimality-gap", "Solver stops when the gap to optimal is less than this (e.g., 0.2 for 20%).", cxxopts::value<double>()->default_value("0.2"))
-        ("switching-penalty", "Penalty for switching drivers.", cxxopts::value<double>()->default_value("0.0"))
-        ("role-coupling-weight", "Weight for role coupling incentives.", cxxopts::value<double>()->default_value("0.0"))
-        ("rotation-beat-weight", "Weight for rotation/fairness adherence.", cxxopts::value<double>()->default_value("0.0"))
-        ("d,diagnose", "Run diagnostics to explain why a schedule is infeasible.", cxxopts::value<bool>()->default_value("false"))
         ("v,version", "Print version information and exit.")
         ("h,help", "Print usage.");
 
+    options.add_options("Solver Configuration")
+        ("t,time-limit", "Maximum time in seconds to let the solver run.", cxxopts::value<int>()->default_value("5"))
+        ("d,diagnose", "Run diagnostics to explain why a schedule is infeasible.", cxxopts::value<bool>()->default_value("false"))
+        ("s,spotter-mode", "Method for scheduling spotters (none, integrated, sequential).", cxxopts::value<std::string>()->default_value("none"))
+        ("allow-no-spotter", "Allow stints to have no spotter assigned.", cxxopts::value<bool>()->default_value("false"))
+        ("g,optimality-gap", "Solver stops when the gap to optimal is less than this (e.g., 0.2 for 20%).", cxxopts::value<double>()->default_value("0.2"));
+
+    options.add_options("Advanced Optimization")
+        ("switching-penalty", "Penalty cost for switching drivers (positive disincentivizes switching).", cxxopts::value<double>()->default_value("0.0"))
+        ("role-coupling-weight", "Reward weight for coupling roles (positive incentivizes driver->spotter).", cxxopts::value<double>()->default_value("0.0"))
+        ("rotation-beat-weight", "Penalty weight for rotation deviation (positive incentivizes adherence).", cxxopts::value<double>()->default_value("0.0"));
+
     auto result = options.parse(argc, argv);
 
     if (result.count("version"))

From 3e35e640e5d223cc5383c8505a668d6171c251d0 Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Thu, 8 Jan 2026 13:04:12 -0800
Subject: [PATCH 5/7] Refactor constraints: globalize consecutive stints and
 min rest

   * Moves `maxStints` (renamed to `consecutiveStints`) and `minimumRestHours` from per-member configuration to global `JresSolverInput` settings.
   * Updates solver to enforce `consecutiveStints` as a strict block size for stint assignment.
   * Implements global `minimumRestHours` enforcement.
   * Adds spotter workload balancing.
   * Updates all tests and documentation to match new schema.
---
 README.md                           |  20 +-
 cmd/formatter/cli.cpp               |   6 +-
 data/24h_race.json                  |  28 +--
 data/no_solution.json               |  22 +-
 data/short_race.json                |  14 +-
 data/short_race_no_solution.json    |  14 +-
 include/jres_solver/jres_solver.hpp |   8 +-
 src/jres_internal_types.cpp         |   7 +-
 src/jres_internal_types.hpp         |   4 +-
 src/jres_json_converter.cpp         |   8 +-
 src/jres_standard_solver.cpp        | 375 +++++++++++++---------------
 src/jres_standard_solver.hpp        |   8 +
 test/CMakeLists.txt                 |   2 +
 test/reproduce_issue.cpp            |  87 +++++++
 test/test_balancing.cpp             |   9 +-
 test/test_constraints.cpp           |  25 +-
 test/test_diagnosis.cpp             |  54 +---
 test/test_errors.cpp                |   5 +
 test/test_fair_share.cpp            |  21 +-
 test/test_formatter_csv.cpp         |  11 +-
 test/test_formatter_itinerary.cpp   |  15 +-
 test/test_formatter_summary.cpp     |   5 +
 test/test_minimum_rest.cpp          |  34 ++-
 test/test_optimization.cpp          |  85 ++++---
 test/test_role_coupling.cpp         |   5 +
 test/test_rotation_beat.cpp         |   9 +-
 test/test_spotter_balancing.cpp     | 106 ++++++++
 test/test_spotter_modes.cpp         |   5 +
 test/test_switching_penalty.cpp     |  11 +-
 29 files changed, 596 insertions(+), 407 deletions(-)
 create mode 100644 test/reproduce_issue.cpp
 create mode 100644 test/test_spotter_balancing.cpp

diff --git a/README.md b/README.md
index f98789d..bac2ab3 100644
--- a/README.md
+++ b/README.md
@@ -32,10 +32,12 @@ The C-API uses the following structs to pass data to and from the solver.
 
 #### Input Structures
 
-`JresSolverInput` is the main input struct. It contains arrays of the other input structs.
+`JresSolverInput` is the main input struct. It contains arrays of the other input structs and global constraints.
 
 | Field | Type | Description |
 | :--- | :--- | :--- |
+| `consecutiveStints` | `int` | Hard constraint: Required number of consecutive stints a driver must perform (block size). |
+| `minimumRestHours` | `int` | Hard constraint: Minimum contiguous rest time required once per race. <br> **Integrated Mode:** Applies to combined Driving and Spotting time. <br> **Sequential Mode:** Applies only to Driving. |
 | `teamMembers` | `JresTeamMember*` | A pointer to an array of team members. |
 | `teamMembers_len` | `int` | The number of team members. |
 | `availability` | `JresMemberAvailability*` | A pointer to an array of availability information. |
@@ -50,8 +52,6 @@ The C-API uses the following structs to pass data to and from the solver.
 | `name` | `const char*` | Unique identifier for the member. |
 | `isDriver` | `int` | `1` if the member can drive, `0` otherwise. |
 | `isSpotter` | `int` | `1` if the member can spot, `0` otherwise. |
-| `maxStints`| `int` | Hard constraint: Maximum number of consecutive stints a member can perform. |
-| `minimumRestHours` | `int` | Hard constraint: Minimum contiguous rest time required once per race. <br> **Integrated Mode:** Applies to combined Driving and Spotting time. <br> **Sequential Mode:** Applies only to Driving. |
 | `tzOffset` | `double` | Timezone offset in hours from UTC. |
 
 `JresStint`
@@ -169,8 +169,8 @@ The solver prioritizes hard constraints (rest times, fuel, availability) first.
 
 The `switchingPenalty` option adds a cost to the optimization objective every time the driver changes between two consecutive stints.
 
-*   **Goal**: To encourage the solver to keep the same driver in the car for multiple stints (e.g., doing a "double stint"), even if it's not strictly required by the `maxStints` constraint.
-*   **Relationship to `maxStints`**: While `maxStints` is a **hard constraint** (the solver *cannot* exceed it), the `switchingPenalty` is a **soft incentive**. It helps avoid "unnecessary" driver changes that might otherwise have equal cost to the solver.
+*   **Goal**: To encourage the solver to keep the same driver in the car for multiple stints (e.g., doing a "double stint"), even if it's not strictly required by the `consecutiveStints` constraint.
+*   **Relationship to `consecutiveStints`**: `consecutiveStints` is a **hard constraint** (the solver *must* schedule blocks of this size). The `switchingPenalty` is a **soft incentive** that applies at the boundaries of these blocks to discourage swapping drivers even when a block ends.
 *   **Recommended Value**: Start with `10.0`. If the solver still switches drivers too often for your preference, increase it. If it starts violating preferred availability slots just to avoid a switch, decrease it.
 
 -----
@@ -193,6 +193,8 @@ The `raceDataJson` string passed to `jres_input_from_json` must strictly follow
 
 | Field | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
+| `consecutiveStints` | Integer | No (Default `1`) | Hard constraint: Required number of consecutive stints a driver must perform (block size). |
+| `minimumRestHours` | Integer | No (Default `0`) | Hard constraint: Minimum contiguous rest time required once per race. <br> **Integrated Mode:** Applies to combined Driving and Spotting time. <br> **Sequential Mode:** Applies only to Driving. |
 | `teamMembers` | Array | Yes | List of drivers and spotters (see below). |
 | `availability` | Object | Yes | Map of availability constraints (see below). |
 | `stints` | Array | Yes | List of pre-defined race stints (see below). |
@@ -212,8 +214,6 @@ The `raceDataJson` string passed to `jres_input_from_json` must strictly follow
 | `name` | String | **Required** | Unique identifier for the member. |
 | `isDriver` | Boolean | `true` | Can this member drive? |
 | `isSpotter` | Boolean | `false` | Can this member spot? |
-| `maxStints` | Integer| `1` | Hard constraint: Maximum number of consecutive stints a member can perform. |
-| `minimumRestHours` | Integer| `0` | Hard constraint: Minimum contiguous rest time required once per race. <br> **Integrated Mode:** Applies to combined Driving and Spotting time. <br> **Sequential Mode:** Applies only to Driving. |
 | `tzOffset` | Number | `0.0` | Timezone offset in hours from UTC. |
 
 #### Availability Map & Time Formatting
@@ -236,13 +236,13 @@ The `availability` object maps a **Team Member's Name** to a dictionary of **Tim
 
 ```json
 {
+  "consecutiveStints": 2,
+  "minimumRestHours": 4,
   "teamMembers": [
     {
       "name": "Niki",
       "isDriver": true,
-      "isSpotter": true,
-      "maxStints": 2,
-      "minimumRestHours": 4
+      "isSpotter": true
     },
     {
       "name": "Alain",
diff --git a/cmd/formatter/cli.cpp b/cmd/formatter/cli.cpp
index ae0b2a5..b4fbc07 100644
--- a/cmd/formatter/cli.cpp
+++ b/cmd/formatter/cli.cpp
@@ -71,10 +71,10 @@ int main(int argc, char* argv[]) {
 
         // --- Logic: Determine Format ---
         if (result.count("format")) {
-            // 1. Explicitly provided by user
+            // Explicitly provided by user
             format = result["format"].as<std::string>();
         } else {
-            // 2. Auto-detect from extension
+            // Auto-detect from extension
             std::string ext = get_extension(output_path);
             if (ext == ".csv") {
                 format = "csv";
@@ -83,7 +83,7 @@ int main(int argc, char* argv[]) {
             } else if (ext == ".zip") {
                 format = "zip";
             } else {
-                // 3. Unknown extension and no flag -> Error
+                // Unknown extension and no flag -> Error
                 std::cerr << "Error: Could not determine output format from filename extension (" 
                           << ext << ")." << std::endl;
                 std::cerr << "Please explicitly specify format using -f <zip|csv|txt> or use a standard file extension." << std::endl;
diff --git a/data/24h_race.json b/data/24h_race.json
index c2eb5bb..bcfbed3 100644
--- a/data/24h_race.json
+++ b/data/24h_race.json
@@ -1,53 +1,43 @@
 {
   "success": true,
+  "consecutiveStints": 2,
+  "minimumRestHours": 6,
   "teamMembers": [
     {
       "name": "Niki",
       "isDriver": true,
       "isSpotter": true,
-      "tzOffset": 1,
-      "maxStints": 1,
-      "minimumRestHours": 6
+      "tzOffset": 1
     },
     {
       "name": "Ayrton",
       "isDriver": true,
       "isSpotter": false,
-      "tzOffset": -3,
-      "maxStints": 2,
-      "minimumRestHours": 6
+      "tzOffset": -3
     },
     {
       "name": "Jack",
       "isDriver": true,
       "isSpotter": true,
-      "tzOffset": 11,
-      "maxStints": 3,
-      "minimumRestHours": 6
+      "tzOffset": 11
     },
     {
       "name": "James",
       "isDriver": true,
       "isSpotter": true,
-      "tzOffset": 0,
-      "maxStints": 2,
-      "minimumRestHours": 6
+      "tzOffset": 0
     },
     {
       "name": "Mario",
       "isDriver": true,
       "isSpotter": true,
-      "tzOffset": -5,
-      "maxStints": 1,
-      "minimumRestHours": 6
+      "tzOffset": -5
     },
     {
       "name": "Ricky",
       "isDriver": false,
       "isSpotter": true,
-      "tzOffset": -6,
-      "maxStints": 2,
-      "minimumRestHours": 6
+      "tzOffset": -6
     }
   ],
   "availability": {
@@ -368,4 +358,4 @@
     }
   ],
   "firstStintDriver": "James"
-}
+}
\ No newline at end of file
diff --git a/data/no_solution.json b/data/no_solution.json
index 2a50b04..cedb9e0 100644
--- a/data/no_solution.json
+++ b/data/no_solution.json
@@ -1,39 +1,31 @@
 {
+  "consecutiveStints": 2,
+  "minimumRestHours": 0,
   "teamMembers": [
     {
       "name": "Brandon",
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     },
     {
       "name": "Cesar",
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     },
     {
       "name": "Harvey",
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     },
     {
       "name": "Jay",
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     },
     {
       "name": "Jack",
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     }
   ],
   "availability": {
diff --git a/data/short_race.json b/data/short_race.json
index 61612e8..b5e1549 100644
--- a/data/short_race.json
+++ b/data/short_race.json
@@ -1,29 +1,25 @@
 {
   "success": true,
+  "consecutiveStints": 2,
+  "minimumRestHours": 0,
   "teamMembers": [
     {
       "name": "Niki",
       "tzOffset": 1,
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     },
     {
       "name": "Ayrton",
       "tzOffset": -3,
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     },
     {
       "name": "Alain",
       "tzOffset": 1,
       "isDriver": false,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 0
+      "isSpotter": true
     }
   ],
   "availability": {
diff --git a/data/short_race_no_solution.json b/data/short_race_no_solution.json
index 5ec3f58..72827e8 100644
--- a/data/short_race_no_solution.json
+++ b/data/short_race_no_solution.json
@@ -1,29 +1,25 @@
 {
   "success": true,
+  "consecutiveStints": 2,
+  "minimumRestHours": 8,
   "teamMembers": [
     {
       "name": "Niki",
       "tzOffset": 1,
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 8
+      "isSpotter": true
     },
     {
       "name": "Ayrton",
       "tzOffset": -3,
       "isDriver": true,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 8
+      "isSpotter": true
     },
     {
       "name": "Alain",
       "tzOffset": 1,
       "isDriver": false,
-      "isSpotter": true,
-      "preferredStints": 2,
-      "minimumRestHours": 8
+      "isSpotter": true
     }
   ],
   "availability": {
diff --git a/include/jres_solver/jres_solver.hpp b/include/jres_solver/jres_solver.hpp
index c6167e9..0125651 100644
--- a/include/jres_solver/jres_solver.hpp
+++ b/include/jres_solver/jres_solver.hpp
@@ -78,10 +78,6 @@ struct JresTeamMember {
     int isDriver;
     /** @brief 1 if the member can spot, 0 otherwise. */
     int isSpotter;
-    /** @brief Maximum number of consecutive stints a member can perform. */
-    int maxStints;
-    /** @brief Minimum rest time in hours required after a shift. */
-    int minimumRestHours;
     /** @brief Timezone offset, in hours from UTC. */
     double tzOffset;
 };
@@ -124,6 +120,10 @@ struct JresMemberAvailability {
  * @brief The main input struct for the solver.
  */
 struct JresSolverInput {
+    /** @brief Required consecutive stints (drivers must do this many stints in a row, except potentially the last one). */
+    int consecutiveStints;
+    /** @brief Minimum rest time in hours required after a shift. */
+    int minimumRestHours;
     /** @brief A pointer to an array of team members. */
     JresTeamMember* teamMembers;
     /** @brief The number of team members. */
diff --git a/src/jres_internal_types.cpp b/src/jres_internal_types.cpp
index 703a424..4099b6e 100644
--- a/src/jres_internal_types.cpp
+++ b/src/jres_internal_types.cpp
@@ -65,13 +65,14 @@ Availability to_internal_availability(JresAvailability availability) {
 SolverInput from_c_input(const JresSolverInput* c_input) {
     SolverInput input;
 
+    input.consecutiveStints = c_input->consecutiveStints;
+    input.minimumRestHours = c_input->minimumRestHours;
+
     for (int i = 0; i < c_input->teamMembers_len; ++i) {
         TeamMember member;
         member.name = c_input->teamMembers[i].name;
         member.isDriver = c_input->teamMembers[i].isDriver;
         member.isSpotter = c_input->teamMembers[i].isSpotter;
-        member.maxStints = c_input->teamMembers[i].maxStints;
-        member.minimumRestHours = c_input->teamMembers[i].minimumRestHours;
         member.tzOffset = c_input->teamMembers[i].tzOffset;
         input.teamMembers.push_back(member);
     }
@@ -141,8 +142,6 @@ JresSolverOutput* to_c_output(const SolverOutput& output, const JresSolverOption
         c_output->teamMembers[i].name = allocate_and_copy(output.teamMembers[i].name);
         c_output->teamMembers[i].isDriver = output.teamMembers[i].isDriver;
         c_output->teamMembers[i].isSpotter = output.teamMembers[i].isSpotter;
-        c_output->teamMembers[i].maxStints = output.teamMembers[i].maxStints;
-        c_output->teamMembers[i].minimumRestHours = output.teamMembers[i].minimumRestHours;
         c_output->teamMembers[i].tzOffset = output.teamMembers[i].tzOffset;
     }
 
diff --git a/src/jres_internal_types.hpp b/src/jres_internal_types.hpp
index 28099e7..dc9d73e 100644
--- a/src/jres_internal_types.hpp
+++ b/src/jres_internal_types.hpp
@@ -34,8 +34,6 @@ struct TeamMember
     std::string name;
     bool isDriver = true;
     bool isSpotter = false;
-    int maxStints = 1;
-    int minimumRestHours = 0;
     double tzOffset = 0.0;
 };
 
@@ -47,6 +45,8 @@ struct Stint {
 
 struct SolverInput
 {
+    int consecutiveStints = 1;
+    int minimumRestHours = 0;
     std::vector<TeamMember> teamMembers;
     std::map<std::string, std::map<std::string, Availability>> availability;
     std::vector<Stint> stints;
diff --git a/src/jres_json_converter.cpp b/src/jres_json_converter.cpp
index 8ea592c..b7841f1 100644
--- a/src/jres_json_converter.cpp
+++ b/src/jres_json_converter.cpp
@@ -73,6 +73,10 @@ JRES_SOLVER_API JresSolverInput* jres_input_from_json(const char* jsonData) {
             throw std::runtime_error("Missing 'availability' key in input JSON.");
         }
 
+        // Global Constraints
+        input->consecutiveStints = j.value("consecutiveStints", 1);
+        input->minimumRestHours = j.value("minimumRestHours", 0);
+
         // Team Members
         input->teamMembers_len = j["teamMembers"].size();
         input->teamMembers = new JresTeamMember[input->teamMembers_len];
@@ -81,8 +85,6 @@ JRES_SOLVER_API JresSolverInput* jres_input_from_json(const char* jsonData) {
             input->teamMembers[i].name = allocate_and_copy(member_json["name"]);
             input->teamMembers[i].isDriver = member_json.value("isDriver", true);
             input->teamMembers[i].isSpotter = member_json.value("isSpotter", false);
-            input->teamMembers[i].maxStints = member_json.value("maxStints", 1);
-            input->teamMembers[i].minimumRestHours = member_json.value("minimumRestHours", 0);
             input->teamMembers[i].tzOffset = member_json.value("tzOffset", 0.0);
         }
 
@@ -157,8 +159,6 @@ JRES_SOLVER_API char* jres_output_to_json(const JresSolverOutput* output) {
                 member_entry["name"] = output->teamMembers[i].name;
                 member_entry["isDriver"] = output->teamMembers[i].isDriver;
                 member_entry["isSpotter"] = output->teamMembers[i].isSpotter;
-                member_entry["maxStints"] = output->teamMembers[i].maxStints;
-                member_entry["minimumRestHours"] = output->teamMembers[i].minimumRestHours;
                 member_entry["tzOffset"] = output->teamMembers[i].tzOffset;
                 j["teamMembers"].push_back(member_entry);
             }
diff --git a/src/jres_standard_solver.cpp b/src/jres_standard_solver.cpp
index 0153bb3..9160d5b 100644
--- a/src/jres_standard_solver.cpp
+++ b/src/jres_standard_solver.cpp
@@ -17,40 +17,8 @@
 static const double kPenaltySlack = 1000000.0;
 static const double kPenaltyUnavailable = 10000000.0;
 static const double kRewardPreferred = -1.0;
-static const double kRewardConsecutive = -2.0;
 static const double kRewardProximity = -0.5; // Incentive for spotting adjacent to driving
-static const double kCostFairness = 10.0; // Reduced from implied infinity, but weighted higher than simple rewards
-
-static void add_consecutive_incentive(
-    Highs* highs,
-    const std::vector<jres::internal::TeamMember>& pool,
-    const std::map<std::pair<std::string, int>, int>& workVars,
-    size_t numStints,
-    double reward)
-{
-    for (const auto &p : pool) {
-        if (p.maxStints <= 1) continue;
-
-        for (size_t s = 0; s < numStints - 1; ++s) {
-            if (workVars.count({p.name, s}) && workVars.count({p.name, s + 1})) {
-                int var_s = workVars.at({p.name, s});
-                int var_next = workVars.at({p.name, s + 1});
-
-                int consecutive_var = highs->getNumCol();
-                highs->addVar(0.0, 1.0);
-                highs->changeColIntegrality(consecutive_var, HighsVarType::kInteger);
-                highs->changeColCost(consecutive_var, reward);
-
-                // z <= x_s
-                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{consecutive_var, var_s}.data(), std::vector<double>{1.0, -1.0}.data());
-                // z <= x_{s+1}
-                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{consecutive_var, var_next}.data(), std::vector<double>{1.0, -1.0}.data());
-                // z >= x_s + x_{s+1} - 1
-                highs->addRow(-1.0, kHighsInf, 3, std::vector<int>{consecutive_var, var_s, var_next}.data(), std::vector<double>{1.0, -1.0, -1.0}.data());
-            }
-        }
-    }
-}
+static const double kCostFairness = 10.0; 
 
 static void add_role_coupling_incentive(
     Highs* highs,
@@ -71,6 +39,10 @@ static void add_role_coupling_incentive(
                 int d_var = driverVars.at({p.name, s});
                 int s_var = spotterVars.at({p.name, s + 1});
 
+                // If there is a transition from driving (stint s) to spotting (stint s+1), reward it.
+                // If s and s+1 are in the same block, d_var == d_var_next (conceptually).
+                // Actually, d_var is the variable for stint s.
+                
                 int coupling_var = highs->getNumCol();
                 highs->addVar(0.0, 1.0);
                 highs->changeColIntegrality(coupling_var, HighsVarType::kInteger);
@@ -136,7 +108,7 @@ JresStandardSolver::CapacityAnalysis JresStandardSolver::calculate_max_potential
     std::ostringstream ss;
 
     for (const auto& p : participants) {
-        // 1. Build Availability & Greedy MaxConsecutive Pattern
+        // Build Availability
         std::vector<bool> is_available(m_input.stints.size(), true);
         auto member_availability_it = m_input.availability.find(p.name);
         if (member_availability_it != m_input.availability.end()) {
@@ -164,10 +136,10 @@ JresStandardSolver::CapacityAnalysis JresStandardSolver::calculate_max_potential
             }
         }
         
-        // 2. Adjust for Minimum Rest (One Instance)
+        // Adjust for Global Minimum Rest (One Instance)
         int final_capacity = base_capacity;
-        if (p.minimumRestHours > 0) {
-             auto minRestDuration = std::chrono::hours(p.minimumRestHours);
+        if (m_input.minimumRestHours > 0) {
+             auto minRestDuration = std::chrono::hours(m_input.minimumRestHours);
              int min_loss = base_capacity; 
              bool found_valid_window = false;
 
@@ -202,8 +174,7 @@ JresStandardSolver::CapacityAnalysis JresStandardSolver::calculate_max_potential
         
         ss << "\n- " << p.name << ": " << final_capacity 
            << " stints (approx " << std::fixed << std::setprecision(1) << driver_total_hours 
-           << "h, MaxConsecutive=" << p.maxStints 
-           << ", MinRest=" << p.minimumRestHours << "h)";
+           << "h, MinRest=" << m_input.minimumRestHours << "h)";
     }
     analysis.details = ss.str();
     return analysis;
@@ -224,77 +195,115 @@ void JresStandardSolver::add_participant_model(
         startTimes.push_back(jres::internal::TimeHelpers::stringToTimePoint(stint.startTime));
     }
 
+    // Determine Block Structure
+    int consecutive = m_input.consecutiveStints;
+    if (consecutive < 1) consecutive = 1;
+    
+    std::vector<std::vector<int>> blocks;
+    for(size_t s=0; s<m_input.stints.size(); ) {
+        std::vector<int> block;
+        for(int k=0; k<consecutive && s < m_input.stints.size(); ++k) {
+            block.push_back((int)s);
+            s++;
+        }
+        blocks.push_back(block);
+    }
+
     for (const auto &p : participants)
     {
-        for (size_t s = 0; s < m_input.stints.size(); ++s)
-        {
-            std::string availabilityKey = jres::internal::TimeHelpers::timePointToKey(startTimes[s]);
-
-            bool isUnavailable = false;
-            bool isPreferred = false;
-
-            auto member_availability_it = m_input.availability.find(p.name);
-            if (member_availability_it != m_input.availability.end()) {
-                auto time_availability_it = member_availability_it->second.find(availabilityKey);
-                if (time_availability_it != member_availability_it->second.end()) {
-                    if (time_availability_it->second == jres::internal::Availability::Unavailable) {
-                        isUnavailable = true;
-                    } else if (time_availability_it->second == jres::internal::Availability::Preferred) {
-                        isPreferred = true;
-                    }
-                }
-            }
-
-            // Create variable for ALL slots, even if unavailable (Elastic)
+        int prevWorkVarIdx = -1;
+        for (const auto& block : blocks) {
             int workVarIdx = highs.getNumCol();
             highs.addVar(0.0, 1.0); // Binary variable
-            workVars[{p.name, s}] = workVarIdx;
             highs.changeColIntegrality(workVarIdx, HighsVarType::kInteger);
-            
-            double cost = 0.0;
-            if (isUnavailable) {
-                cost = kPenaltyUnavailable;
-                m_unavailableVars.insert(workVarIdx);
-            } else if (isPreferred) {
-                cost = kRewardPreferred;
-            }
-            highs.changeColCost(workVarIdx, cost);
-        }
 
-        // --- Elastic Constraint: Max Consecutive Stints ---
-        int maxConsecutive = p.maxStints;
-        if (maxConsecutive > 0 && m_input.stints.size() >= static_cast<size_t>(maxConsecutive + 1)) {
-             for (size_t s = 0; s <= m_input.stints.size() - (maxConsecutive + 1); ++s) {
-                std::vector<int> consIdx;
-                std::vector<double> consVal;
-                for (size_t i = 0; i < maxConsecutive + 1; ++i) { 
-                    if (workVars.count({p.name, s + i})) {
-                        consIdx.push_back(workVars.at({p.name, s + i}));
-                        consVal.push_back(1.0);
+            if (prevWorkVarIdx != -1) {
+                 // Constraint: Cannot drive adjacent blocks (Strict consecutiveStints limit)
+                 // x_{block_i} + x_{block_{i+1}} <= 1
+                 std::vector<int> idx = {prevWorkVarIdx, workVarIdx};
+                 std::vector<double> val = {1.0, 1.0};
+                 highs.addRow(-kHighsInf, 1.0, 2, idx.data(), val.data());
+            }
+            prevWorkVarIdx = workVarIdx;
+
+            double total_cost = 0.0;
+            bool any_unavailable = false;
+
+            // Map all stints in this block to this variable and accumulate cost
+            for (int s_idx : block) {
+                workVars[{p.name, s_idx}] = workVarIdx;
+
+                std::string availabilityKey = jres::internal::TimeHelpers::timePointToKey(startTimes[s_idx]);
+                auto member_availability_it = m_input.availability.find(p.name);
+                if (member_availability_it != m_input.availability.end()) {
+                    auto time_availability_it = member_availability_it->second.find(availabilityKey);
+                    if (time_availability_it != member_availability_it->second.end()) {
+                        if (time_availability_it->second == jres::internal::Availability::Unavailable) {
+                            total_cost += kPenaltyUnavailable;
+                            any_unavailable = true;
+                        } else if (time_availability_it->second == jres::internal::Availability::Preferred) {
+                            total_cost += kRewardPreferred;
+                        }
                     }
                 }
-                if (consIdx.empty()) continue; 
+            }
 
-                // Create slack variable s >= 0
-                int slackVar = highs.getNumCol();
-                highs.addVar(0.0, kHighsInf);
-                highs.changeColCost(slackVar, kPenaltySlack);
-                
-                // Track slack
-                SlackInfo info;
-                info.type = "Max Consecutive Stints";
-                info.memberName = p.name;
-                info.stintIndex = (int)s; // Start of the window
-                info.limit = (double)maxConsecutive;
-                m_slackInfo[slackVar] = info;
+            if (any_unavailable) {
+                m_unavailableVars.insert(workVarIdx);
+            }
+            
+            highs.changeColCost(workVarIdx, total_cost);
+        }
+    }
+}
 
-                // sum(x) - slack <= maxConsecutive
-                consIdx.push_back(slackVar);
-                consVal.push_back(-1.0);
-                
-                highs.addRow(-kHighsInf, maxConsecutive, (int)consIdx.size(), consIdx.data(), consVal.data());
+void JresStandardSolver::add_balancing_constraints(
+    Highs &highs,
+    const std::vector<jres::internal::TeamMember> &participants,
+    const std::map<std::pair<std::string, int>, int>& workVars,
+    double avgStints)
+{
+    for (const auto &p : participants) {
+        std::vector<int> stint_indices;
+        std::vector<double> stint_values;
+        
+        std::map<int, double> varCounts;
+        for (size_t s = 0; s < m_input.stints.size(); ++s) {
+            if (workVars.count({p.name, (int)s})) {
+                int v = workVars.at({p.name, (int)s});
+                varCounts[v] += 1.0;
             }
         }
+        for(auto const& [v, count] : varCounts) {
+            stint_indices.push_back(v);
+            stint_values.push_back(count);
+        }
+
+        if (stint_indices.empty()) continue;
+
+        int total_stints_var = highs.getNumCol();
+        highs.addVar(0.0, kHighsInf);
+        stint_indices.push_back(total_stints_var);
+        stint_values.push_back(-1.0);
+        highs.addRow(0.0, 0.0, (int)stint_indices.size(), stint_indices.data(), stint_values.data());
+
+        int over_avg_var = highs.getNumCol();
+        highs.addVar(0.0, kHighsInf);
+        int under_avg_var = highs.getNumCol();
+        highs.addVar(0.0, kHighsInf);
+        
+        std::vector<int> idx_over = {over_avg_var, total_stints_var};
+        std::vector<double> val_over = {1.0, -1.0};
+        highs.addRow(0.0, kHighsInf, 2, idx_over.data(), val_over.data());
+        highs.changeRowBounds(highs.getNumRow() - 1, -avgStints, kHighsInf);
+        
+        std::vector<int> idx_under = {under_avg_var, total_stints_var};
+        std::vector<double> val_under = {1.0, 1.0};
+        highs.addRow(0.0, kHighsInf, 2, idx_under.data(), val_under.data());
+        highs.changeRowBounds(highs.getNumRow() - 1, avgStints, kHighsInf);
+
+        highs.changeColCost(over_avg_var, kCostFairness);
+        highs.changeColCost(under_avg_var, kCostFairness);
     }
 }
 
@@ -335,15 +344,15 @@ void JresStandardSolver::apply_minimum_rest_constraints(
 
     for (const auto &p : participants)
     {
-        if (p.minimumRestHours <= 0) continue;
-        auto minRestDuration = std::chrono::hours(p.minimumRestHours);
+        if (m_input.minimumRestHours <= 0) continue;
+        auto minRestDuration = std::chrono::hours(m_input.minimumRestHours);
             
-        // 1. Generate Candidates
+        // Generate Candidates
         std::vector<std::chrono::system_clock::time_point> candidateStarts;
         candidateStarts.push_back(raceStart);
         for(const auto& t : endTimes) candidateStarts.push_back(t);
 
-        // 2. Build Block Sets
+        // Build Block Sets
         std::vector<std::set<int>> blockSets;
         blockSets.reserve(candidateStarts.size());
         
@@ -368,7 +377,7 @@ void JresStandardSolver::apply_minimum_rest_constraints(
             blockSets.push_back(blocked);
         }
 
-        // 3. Prune Supersets
+        // Prune Supersets
         std::vector<bool> keep(blockSets.size(), true);
         bool anyEmpty = false;
 
@@ -394,7 +403,7 @@ void JresStandardSolver::apply_minimum_rest_constraints(
                 }
             }
 
-            // 4. Create Variables
+            // Create Variables
             std::vector<int> restOptionVars;
             for(size_t i=0; i<blockSets.size(); ++i) {
                 if(!keep[i]) continue;
@@ -442,7 +451,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     auto startTotal = high_resolution_clock::now();
     jres::internal::SolverOutput output;
 
-    // --- 1. Arithmetic Pre-flight Check ---
+    // --- Arithmetic Pre-flight Check ---
     int totalStints = (int)m_input.stints.size();
     CapacityAnalysis capAnalysis = calculate_max_potential_capacity(m_driverPool);
     
@@ -461,8 +470,6 @@ jres::internal::SolverOutput JresStandardSolver::solve()
 
     // --- Hard Constraint: iRacing Fair Share Rule ---
     // Rule: Fair Share = 1/4 of (Total Duration / Num Drivers)
-    // We enforce this using Time Duration.
-    // 1. Calculate Total Duration and Stint Durations
     double total_duration_hours = 0.0;
     std::vector<double> stint_durations_hours;
     stint_durations_hours.reserve(m_input.stints.size());
@@ -478,22 +485,28 @@ jres::internal::SolverOutput JresStandardSolver::solve()
 
     const double num_drivers = m_driverPool.size();
     if (num_drivers > 0) {
-        // "Equal Share" = Total / NumDrivers.
-        // "Fair Share" = Equal Share / 4.
         double min_fair_share_hours = (total_duration_hours / num_drivers) * 0.25;
 
         for (const auto &p : m_driverPool) {
             std::vector<int> idx;
             std::vector<double> val;
             
+            // Map: varIdx -> totalDuration
+            std::map<int, double> varDurations;
+
             for (size_t s = 0; s < m_input.stints.size(); ++s) {
                 if (m_driverWorkVars.count({p.name, s})) {
-                    idx.push_back(m_driverWorkVars.at({p.name, s}));
-                    val.push_back(stint_durations_hours[s]);
+                    int v = m_driverWorkVars.at({p.name, s});
+                    varDurations[v] += stint_durations_hours[s];
                 }
             }
 
-            if (idx.empty()) continue; // Should catch this elsewhere if they have 0 avail
+            for(auto const& [v, dur] : varDurations) {
+                idx.push_back(v);
+                val.push_back(dur);
+            }
+
+            if (idx.empty()) continue; 
 
             // Elastic Constraint: Sum(duration * x) + slack >= min_fair_share
             int slackVar = m_highs->getNumCol();
@@ -519,39 +532,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     const double avg_stints_per_driver = num_drivers > 0 ? num_stints / num_drivers : 0;
 
     if (num_drivers > 0) {
-        // Balancing variables
-        for (const auto &p : m_driverPool) {
-            std::vector<int> driver_stint_indices;
-            std::vector<double> driver_stint_values;
-            for (size_t s = 0; s < m_input.stints.size(); ++s) {
-                if (m_driverWorkVars.count({p.name, s})) {
-                    driver_stint_indices.push_back(m_driverWorkVars.at({p.name, s}));
-                    driver_stint_values.push_back(1.0);
-                }
-            }
-
-            if (driver_stint_indices.empty()) continue;
-
-            int total_stints_var = m_highs->getNumCol();
-            m_highs->addVar(0.0, kHighsInf);
-            driver_stint_indices.push_back(total_stints_var);
-            driver_stint_values.push_back(-1.0);
-            m_highs->addRow(0.0, 0.0, (int)driver_stint_indices.size(), driver_stint_indices.data(), driver_stint_values.data());
-
-            int over_avg_var = m_highs->getNumCol();
-            m_highs->addVar(0.0, kHighsInf);
-            int under_avg_var = m_highs->getNumCol();
-            m_highs->addVar(0.0, kHighsInf);
-            
-            m_highs->addRow(0.0, kHighsInf, 2, std::vector<int>{over_avg_var, total_stints_var}.data(), std::vector<double>{1.0, -1.0}.data());
-            m_highs->changeRowBounds(m_highs->getNumRow() - 1, -avg_stints_per_driver, kHighsInf);
-            
-            m_highs->addRow(0.0, kHighsInf, 2, std::vector<int>{under_avg_var, total_stints_var}.data(), std::vector<double>{1.0, 1.0}.data());
-            m_highs->changeRowBounds(m_highs->getNumRow() - 1, avg_stints_per_driver, kHighsInf);
-
-            m_highs->changeColCost(over_avg_var, kCostFairness);
-            m_highs->changeColCost(under_avg_var, kCostFairness);
-        }
+        add_balancing_constraints(*m_highs, m_driverPool, m_driverWorkVars, avg_stints_per_driver);
     }
 
     // --- Coverage Constraints (One driver per stint) ---
@@ -572,9 +553,6 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         m_highs->addRow(1.0, 1.0, (int)indices.size(), indices.data(), values.data());
     }
 
-    // --- Incentivize Consecutive Stints ---
-    add_consecutive_incentive(m_highs.get(), m_driverPool, m_driverWorkVars, m_input.stints.size(), kRewardConsecutive);
-
     // --- Switching Penalty ---
     if (m_options.switchingPenalty > 0.0) {
         for (size_t s = 1; s < m_input.stints.size(); ++s) {
@@ -590,9 +568,11 @@ jres::internal::SolverOutput JresStandardSolver::solve()
                     int var_s = m_driverWorkVars.at({p.name, s});
                     int var_prev = m_driverWorkVars.at({p.name, s - 1});
                     
-                    std::vector<int> idx = {switchVar, var_s, var_prev};
-                    std::vector<double> val = {1.0, -1.0, 1.0};
-                    m_highs->addRow(0.0, kHighsInf, 3, idx.data(), val.data());
+                    if (var_s != var_prev) { // Only add if different variables (blocks changed)
+                        std::vector<int> idx = {switchVar, var_s, var_prev};
+                        std::vector<double> val = {1.0, -1.0, 1.0};
+                        m_highs->addRow(0.0, kHighsInf, 3, idx.data(), val.data());
+                    }
                 }
             }
         }
@@ -617,12 +597,12 @@ jres::internal::SolverOutput JresStandardSolver::solve()
                         // Relaxed to continuous is fine for deviation between binary vars
                         m_highs->changeColCost(devVar, m_options.rotationBeatWeight);
 
-                        // 1. d >= current - target  =>  d - current + target >= 0
+                        // d >= current - target  =>  d - current + target >= 0
                         m_highs->addRow(0.0, kHighsInf, 3, 
                             std::vector<int>{devVar, var_current, var_target}.data(), 
                             std::vector<double>{1.0, -1.0, 1.0}.data());
 
-                        // 2. d >= target - current  =>  d + current - target >= 0
+                        // d >= target - current  =>  d + current - target >= 0
                         m_highs->addRow(0.0, kHighsInf, 3, 
                             std::vector<int>{devVar, var_current, var_target}.data(), 
                             std::vector<double>{1.0, 1.0, -1.0}.data());
@@ -636,15 +616,18 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     if (m_options.spotterMode == JRES_SPOTTER_MODE_INTEGRATED) {
         if (m_spotterPool.empty() && !m_options.allowNoSpotter) {
              output.diagnosis.push_back("No spotters available for Integrated Mode.");
-             // We can proceed, but coverage will fail (likely leading to infeasibility or slack usage if we made coverage elastic - which we didn't).
-             // If coverage is hard constraint, this will throw "Model is infeasible".
-             // Let's rely on the coverage constraint check later.
         }
         
         add_participant_model(*m_highs, m_spotterPool, m_spotterWorkVars);
-        add_consecutive_incentive(m_highs.get(), m_spotterPool, m_spotterWorkVars, m_input.stints.size(), kRewardConsecutive);
+
         add_role_coupling_incentive(m_highs.get(), m_driverPool, m_driverWorkVars, m_spotterWorkVars, m_input.stints.size(), m_options.roleCouplingWeight);
 
+        // Spotter Balancing
+        if (!m_spotterPool.empty()) {
+            double avg_stints_per_spotter = static_cast<double>(m_input.stints.size()) / m_spotterPool.size();
+            add_balancing_constraints(*m_highs, m_spotterPool, m_spotterWorkVars, avg_stints_per_spotter);
+        }
+
         // Spotter Coverage
         for (size_t s = 0; s < m_input.stints.size(); ++s) {
             std::vector<int> indices;
@@ -658,9 +641,6 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             if (!indices.empty()) {
                 double lower = m_options.allowNoSpotter ? 0.0 : 1.0;
                 m_highs->addRow(lower, 1.0, (int)indices.size(), indices.data(), values.data());
-            } else if (!m_options.allowNoSpotter) {
-                 // No candidates for this stint
-                 // Since coverage is hard, this will be infeasible.
             }
         }
 
@@ -679,12 +659,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     }
     
     // Apply Rest Constraints
-    // Integrated: Enforce Combined (Drive + Spot)
-    // Sequential (Driver Phase): Enforce Drive Only
     bool enforceCombinedRest = (m_options.spotterMode == JRES_SPOTTER_MODE_INTEGRATED);
-    
-    // For Sequential mode, we only have driver vars populated right now. Spotter vars are empty.
-    // So passing m_spotterWorkVars is fine (it's empty).
     apply_minimum_rest_constraints(*m_highs, m_input.teamMembers, m_driverWorkVars, m_spotterWorkVars, enforceCombinedRest);
 
 
@@ -797,7 +772,10 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             spotterSolver.setOptionValue("mip_rel_gap", m_options.optimalityGap);
 
             add_participant_model(spotterSolver, m_spotterPool, m_spotterWorkVars);
-            add_consecutive_incentive(&spotterSolver, m_spotterPool, m_spotterWorkVars, m_input.stints.size(), kRewardConsecutive);
+
+            // Spotter Balancing
+            double avg_stints_per_spotter = static_cast<double>(m_input.stints.size()) / m_spotterPool.size();
+            add_balancing_constraints(spotterSolver, m_spotterPool, m_spotterWorkVars, avg_stints_per_spotter);
 
             // Spotter Coverage Constraints
             for (size_t s = 0; s < m_input.stints.size(); ++s) {
@@ -824,50 +802,31 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             }
 
             // Incentivize Spotting Adjacent to Driving (Proximity & Role Coupling)
+            // Calculate Rewards per Block Var
+            std::map<int, double> spotterRewards;
             for (const auto& p : m_spotterPool) {
                 for (size_t s = 0; s < m_input.stints.size(); ++s) {
-                    if (!m_spotterWorkVars.count({p.name, s})) continue;
-                    
-                    double additionalReward = 0.0;
-                    
-                    // Check s-1: Driver(s-1) -> Spotter(s) [Role Coupling]
-                    if (s > 0 && output.schedule[s-1].driver == p.name) {
-                         if (std::abs(m_options.roleCouplingWeight) > 1e-6) {
-                             additionalReward += -m_options.roleCouplingWeight;
-                         } else {
-                             additionalReward += kRewardProximity;
-                         }
-                    }
-                    
-                    // Check s+1: Spotter(s) -> Driver(s+1) [Proximity]
-                    if (s < m_input.stints.size() - 1 && output.schedule[s+1].driver == p.name) {
+                     if (!m_spotterWorkVars.count({p.name, s})) continue;
+                     int varIdx = m_spotterWorkVars.at({p.name, s});
+                     
+                     double additionalReward = 0.0;
+                     if (s > 0 && output.schedule[s-1].driver == p.name) {
+                         additionalReward += (std::abs(m_options.roleCouplingWeight) > 1e-6) ? -m_options.roleCouplingWeight : kRewardProximity;
+                     }
+                     if (s < m_input.stints.size() - 1 && output.schedule[s+1].driver == p.name) {
                         additionalReward += kRewardProximity;
-                    }
-
-                    if (std::abs(additionalReward) > 1e-6) {
-                        int varIdx = m_spotterWorkVars.at({p.name, s});
-                        
-                        // Re-calculate base cost to ensure we add to it
-                         std::string availabilityKey = jres::internal::TimeHelpers::timePointToKey(jres::internal::TimeHelpers::stringToTimePoint(m_input.stints[s].startTime));
-                         bool isPreferred = false;
-                         bool isUnavailableExplicit = false;
-                         auto member_availability_it = m_input.availability.find(p.name);
-                         if (member_availability_it != m_input.availability.end()) {
-                            auto time_availability_it = member_availability_it->second.find(availabilityKey);
-                            if (time_availability_it != member_availability_it->second.end()) {
-                                if (time_availability_it->second == jres::internal::Availability::Preferred) isPreferred = true;
-                                if (time_availability_it->second == jres::internal::Availability::Unavailable) isUnavailableExplicit = true;
-                            }
-                         }
-
-                         double newCost = 0.0;
-                         if (isUnavailableExplicit) newCost = kPenaltyUnavailable;
-                         else if (isPreferred) newCost = kRewardPreferred;
-                         
-                         newCost += additionalReward;
-                         
-                         spotterSolver.changeColCost(varIdx, newCost);
-                    }
+                     }
+                     spotterRewards[varIdx] += additionalReward;
+                }
+            }
+            
+            // Retrieve base costs 
+            const std::vector<double>& currentCosts = spotterSolver.getLp().col_cost_;
+            
+            // Apply
+            for(const auto& [varIdx, reward] : spotterRewards) {
+                if(varIdx < (int)currentCosts.size()) {
+                    spotterSolver.changeColCost(varIdx, currentCosts[varIdx] + reward);
                 }
             }
 
@@ -915,4 +874,4 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     
     output.teamMembers = m_input.teamMembers;
     return output;
-}
\ No newline at end of file
+}
diff --git a/src/jres_standard_solver.hpp b/src/jres_standard_solver.hpp
index d40216a..986ced2 100644
--- a/src/jres_standard_solver.hpp
+++ b/src/jres_standard_solver.hpp
@@ -29,6 +29,14 @@ class JresStandardSolver : public JresSolverBase
         std::map<std::pair<std::string, int>, int>& workVars
     );
 
+    // Incentivize balanced participation (Soft Constraint)
+    void add_balancing_constraints(
+        Highs &highs,
+        const std::vector<jres::internal::TeamMember> &participants,
+        const std::map<std::pair<std::string, int>, int>& workVars,
+        double avgStints
+    );
+
     // Enforce minimum rest constraints (potentially across both roles)
     void apply_minimum_rest_constraints(
         Highs &highs,
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 9d31e36..eecfe1a 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -35,6 +35,8 @@ add_executable(solver_tests
   test_switching_penalty.cpp
   test_role_coupling.cpp
   test_rotation_beat.cpp
+  test_spotter_balancing.cpp
+  reproduce_issue.cpp
 )
 
 add_dependencies(solver_tests jres_solver_lib)
diff --git a/test/reproduce_issue.cpp b/test/reproduce_issue.cpp
new file mode 100644
index 0000000..9df7a9f
--- /dev/null
+++ b/test/reproduce_issue.cpp
@@ -0,0 +1,87 @@
+/**
+ * @file test/reproduce_issue.cpp
+ * @brief Tests for hard constraints on consecutive stints.
+ */
+
+#include <gtest/gtest.h>
+#include "jres_solver/jres_solver.hpp"
+#include "nlohmann/json.hpp"
+#include <vector>
+#include <string>
+
+using json = nlohmann::json;
+
+/**
+ * @brief Verify that the solver strictly enforces the 'consecutiveStints' limit.
+ * 
+ * This test constructs a scenario where we search for a violation of the consecutive stint limit.
+ * It ensures that no driver is assigned more than 'consecutiveStints' stints in a row.
+ */
+TEST(ConstraintTest, EnforceConsecutiveStintsHardLimit) {
+    json j;
+    j["success"] = true;
+    j["consecutiveStints"] = 2;
+    j["minimumRestHours"] = 0;
+    
+    // 2 Drivers
+    json members = json::array();
+    members.push_back({{"name", "DriverA"}, {"isDriver", true}, {"isSpotter", false}});
+    members.push_back({{"name", "DriverB"}, {"isDriver", true}, {"isSpotter", false}});
+    j["teamMembers"] = members;
+
+    // 8 Stints (4 blocks of 2)
+    json stints = json::array();
+    for (int i = 0; i < 8; ++i) {
+        stints.push_back({
+            {"id", i + 1},
+            {"startTime", "2026-01-17T0" + std::to_string(12 + i) + ":00:00.000Z"},
+            {"endTime", "2026-01-17T0" + std::to_string(12 + i + 1) + ":00:00.000Z"}
+        });
+    }
+    j["stints"] = stints;
+    j["availability"] = json::object(); 
+
+    std::string json_str = j.dump();
+    JresSolverInput* input = jres_input_from_json(json_str.c_str());
+    ASSERT_NE(input, nullptr);
+
+    JresSolverOptions options;
+    options.timeLimit = 10;
+    options.spotterMode = JRES_SPOTTER_MODE_NONE; // Focus on drivers
+    options.allowNoSpotter = true;
+    options.optimalityGap = 0.0;
+    options.switchingPenalty = 0.0; 
+
+    JresSolverOutput* output = solve_race_schedule(input, &options);
+    ASSERT_NE(output, nullptr);
+    ASSERT_EQ(output->schedule_len, 8);
+
+    std::vector<std::string> assigned(8);
+    for (int i = 0; i < output->schedule_len; ++i) {
+        // Output schedule usually sorted but trust index if id matches
+        int id = output->schedule[i].id;
+        if (id >= 1 && id <= 8) {
+            assigned[id - 1] = output->schedule[i].driver;
+        }
+    }
+
+    // Check for 4 consecutive stints (which would be a violation as limit is 2)
+    // We scan for any sequence of 4 identical drivers.
+    for(int i=0; i <= 4; ++i) {
+        bool all_same = true;
+        std::string first = assigned[i];
+        for(int k=1; k<4; ++k) {
+            if (assigned[i+k] != first) {
+                all_same = false;
+                break;
+            }
+        }
+        if (all_same) {
+            FAIL() << "Found 4 consecutive stints for " << first << " starting at index " << i 
+                   << ". Limit is " << j["consecutiveStints"];
+        }
+    }
+
+    free_jres_solver_output(output);
+    free_jres_solver_input(input);
+}
diff --git a/test/test_balancing.cpp b/test/test_balancing.cpp
index 87038ce..fc97655 100644
--- a/test/test_balancing.cpp
+++ b/test/test_balancing.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_balancing.cpp
+ * @brief Tests for the driver stint balancing logic.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
@@ -36,9 +41,7 @@ TEST(BalancingTest, FairBalance) {
     json data = json::parse(f);
 
     // Relax minimumRestHours to allow better balancing
-    for (auto& member : data["teamMembers"]) {
-        member["minimumRestHours"] = 2; 
-    }
+    data["minimumRestHours"] = 2;
 
     std::string json_str = data.dump();
 
diff --git a/test/test_constraints.cpp b/test/test_constraints.cpp
index 4a60440..948c242 100644
--- a/test/test_constraints.cpp
+++ b/test/test_constraints.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_constraints.cpp
+ * @brief Tests for various hard constraints (infeasibility, preferred slots, coverage).
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
@@ -41,9 +46,11 @@ TEST(ConstraintTest, InfeasibleModel) {
 }
 
 const char* PREFERRED_SLOT_V2_JSON = R"({
+  "consecutiveStints": 1,
+  "minimumRestHours": 0,
   "teamMembers": [
-    { "name": "Driver A", "isDriver": true, "maxStints": 2, "minimumRestHours": 0 },
-    { "name": "Driver B", "isDriver": true, "maxStints": 2, "minimumRestHours": 0 }
+    { "name": "Driver A", "isDriver": true },
+    { "name": "Driver B", "isDriver": true }
   ],
   "availability": {
     "Driver A": {
@@ -77,12 +84,14 @@ TEST(ConstraintTest, PreferredSlot) {
 }
 
 const char* NO_DRIVER_FOR_STINT_V2_JSON = R"({
+  "consecutiveStints": 2,
+  "minimumRestHours": 0,
   "teamMembers": [
-    { "name": "Brandon", "isDriver": true, "isSpotter": true, "maxStints": 2, "minimumRestHours": 0 },
-    { "name": "Cesar", "isDriver": true, "isSpotter": true, "maxStints": 2, "minimumRestHours": 0 },
-    { "name": "Harvey", "isDriver": true, "isSpotter": true, "maxStints": 2, "minimumRestHours": 0 },
-    { "name": "Jay", "isDriver": true, "isSpotter": true, "maxStints": 2, "minimumRestHours": 0 },
-    { "name": "Jack", "isDriver": true, "isSpotter": true, "maxStints": 2, "minimumRestHours": 0 }
+    { "name": "Brandon", "isDriver": true, "isSpotter": true },
+    { "name": "Cesar", "isDriver": true, "isSpotter": true },
+    { "name": "Harvey", "isDriver": true, "isSpotter": true },
+    { "name": "Jay", "isDriver": true, "isSpotter": true },
+    { "name": "Jack", "isDriver": true, "isSpotter": true }
   ],
   "availability": {
     "Brandon": { "2025-11-22T14:00:00.000Z": "Unavailable" },
@@ -113,7 +122,7 @@ TEST(ConstraintTest, NoDriverForStint) {
     ASSERT_GT(output->diagnosis_len, 0);
     std::string msg(output->diagnosis[0]);
     bool correctMsg = (msg.find("Insufficient driver capacity") != std::string::npos);
-    bool correctDetails = (msg.find(", MaxConsecutive=") != std::string::npos);
+    bool correctDetails = (msg.find(", MinRest=") != std::string::npos);
     EXPECT_EQ(correctMsg, true);
     EXPECT_EQ(correctDetails, true);
 
diff --git a/test/test_diagnosis.cpp b/test/test_diagnosis.cpp
index e059aff..138e352 100644
--- a/test/test_diagnosis.cpp
+++ b/test/test_diagnosis.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_diagnosis.cpp
+ * @brief Tests for the solver's diagnostic output capability.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include <string>
@@ -32,49 +37,10 @@ namespace {
         free_jres_solver_output(output);
     }
 
-    const char* MAX_CONSECUTIVE_V2_JSON = R"({
-      "teamMembers": [
-        { "name": "Ayrton", "isDriver": true, "maxStints": 1, "minimumRestHours": 0 }
-      ],
-      "availability": {
-        "Ayrton": {
-          "1973-06-09T14:00:00.000Z": "Available",
-          "1973-06-09T15:00:00.000Z": "Available",
-          "1973-06-09T16:00:00.000Z": "Available"
-        }
-      },
-      "stints": [
-        { "id": 1, "startTime": "1973-06-09T14:00:00.000Z", "endTime": "1973-06-09T14:30:00.000Z" },
-        { "id": 2, "startTime": "1973-06-09T14:30:00.000Z", "endTime": "1973-06-09T15:00:00.000Z" },
-        { "id": 3, "startTime": "1973-06-09T15:00:00.000Z", "endTime": "1973-06-09T15:30:00.000Z" }
-      ]
-    })";
-    TEST(DiagnosisTest, MaxConsecutive) {
-        JresSolverOptions options;
-        options.timeLimit = 10;
-        options.spotterMode = JRES_SPOTTER_MODE_NONE;
-        JresSolverInput* input = jres_input_from_json(MAX_CONSECUTIVE_V2_JSON);
-        ASSERT_NE(input, nullptr);
-        JresSolverOutput* output = diagnose_race_schedule(input, &options);
-        ASSERT_NE(output, nullptr);
-        ASSERT_GT(output->diagnosis_len, 0);
-        bool found = false;
-        for (int i = 0; i < output->diagnosis_len; ++i) {
-            std::string msg(output->diagnosis[i]);
-            if (msg.find("Violation: Max Consecutive Stints") != std::string::npos) {
-                found = true;
-                break;
-            }
-        }
-        EXPECT_TRUE(found) << "Expected diagnosis to contain 'Violation: Max Consecutive Stints'";
-        free_jres_solver_input(input);
-        free_jres_solver_output(output);
-    }
-
     const char* UNAVAILABLE_SPOTTER_INTEGRATED_V2_JSON = R"({
       "teamMembers": [
-        { "name": "Lauda", "isDriver": true, "minimumRestHours": 0 },
-        { "name": "Prost", "isSpotter": true, "minimumRestHours": 0 }
+        { "name": "Lauda", "isDriver": true },
+        { "name": "Prost", "isSpotter": true }
       ],
       "availability": {
         "Lauda": { "1973-06-09T14:00:00.000Z": "Available" },
@@ -109,9 +75,9 @@ namespace {
 
     const char* SEQUENTIAL_SPOTTER_MODE_V2_JSON = R"({
       "teamMembers": [
-        { "name": "Lauda", "isDriver": true, "isSpotter": true, "minimumRestHours": 0 },
-        { "name": "Prost", "isDriver": true, "isSpotter": true, "minimumRestHours": 0 },
-        { "name": "Senna", "isDriver": false, "isSpotter": true, "maxStints": 1, "minimumRestHours": 0 }
+        { "name": "Lauda", "isDriver": true, "isSpotter": true },
+        { "name": "Prost", "isDriver": true, "isSpotter": true },
+        { "name": "Senna", "isDriver": false, "isSpotter": true }
       ],
       "availability": {
         "Lauda": { "1973-06-09T14:00:00.000Z": "Available" },
diff --git a/test/test_errors.cpp b/test/test_errors.cpp
index 4517afa..af6b47e 100644
--- a/test/test_errors.cpp
+++ b/test/test_errors.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_errors.cpp
+ * @brief Tests for error handling and input validation.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include <string>
diff --git a/test/test_fair_share.cpp b/test/test_fair_share.cpp
index 69db020..b147e96 100644
--- a/test/test_fair_share.cpp
+++ b/test/test_fair_share.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_fair_share.cpp
+ * @brief Tests for the "Fair Share" rule enforcement.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include <string>
@@ -15,13 +20,11 @@ JresStint create_stint(int id, const char* start, const char* end) {
 }
 
 // Helper to create a driver
-JresTeamMember create_driver(const char* name, int maxStints = 10) {
+JresTeamMember create_driver(const char* name) {
     JresTeamMember m;
     m.name = name;
     m.isDriver = 1;
     m.isSpotter = 0;
-    m.maxStints = maxStints;
-    m.minimumRestHours = 0;
     m.tzOffset = 0.0;
     return m;
 }
@@ -70,8 +73,8 @@ TEST(FairShareTest, EnforcesMinimumRequirement) {
     }
 
     std::vector<JresTeamMember> members;
-    members.push_back(create_driver("DriverA", 5)); // MaxConsecutive is fine
-    members.push_back(create_driver("DriverB", 20));
+    members.push_back(create_driver("DriverA")); 
+    members.push_back(create_driver("DriverB"));
 
     // Create Availability for DriverA
     // Available for 0 and 1. Unavailable for 2..19.
@@ -98,6 +101,8 @@ TEST(FairShareTest, EnforcesMinimumRequirement) {
     availabilities.push_back(mavA);
 
     JresSolverInput input;
+    input.consecutiveStints = 20;
+    input.minimumRestHours = 0;
     input.stints = stints.data();
     input.stints_len = (int)stints.size();
     input.teamMembers = members.data();
@@ -157,10 +162,12 @@ TEST(FairShareTest, SuccessScenario) {
     }
 
     std::vector<JresTeamMember> members;
-    members.push_back(create_driver("DriverA", 3)); // 3 stints >= 2.5h
-    members.push_back(create_driver("DriverB", 20));
+    members.push_back(create_driver("DriverA")); 
+    members.push_back(create_driver("DriverB"));
 
     JresSolverInput input;
+    input.consecutiveStints = 1;
+    input.minimumRestHours = 0;
     input.stints = stints.data();
     input.stints_len = (int)stints.size();
     input.teamMembers = members.data();
diff --git a/test/test_formatter_csv.cpp b/test/test_formatter_csv.cpp
index 101d431..09e4b98 100644
--- a/test/test_formatter_csv.cpp
+++ b/test/test_formatter_csv.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_formatter_csv.cpp
+ * @brief Tests for CSV output formatting.
+ */
+
 #include "gtest/gtest.h"
 #include "formatter/formatter_core.hpp"
 #include "nlohmann/json.hpp"
@@ -6,7 +11,7 @@
 using json = nlohmann::json;
 
 TEST(FormatterCSVTest, ScheduleGeneration) {
-    // 1. Create Mock Data
+    // Create Mock Data
     std::vector<json> schedule;
     schedule.push_back({
         {"id", 1},
@@ -16,10 +21,10 @@ TEST(FormatterCSVTest, ScheduleGeneration) {
         {"spotter", "SpotterB"}
     });
 
-    // 2. Run Function
+    // Run Function
     std::string result = jres::generate_schedule_csv_string(schedule, true);
 
-    // 3. Assertions
+    // Assertions
     EXPECT_NE(result.find("Stint,Start Time (UTC),End Time (UTC)"), std::string::npos) << "Header is incorrect";
     EXPECT_NE(result.find("Assigned Spotter"), std::string::npos) << "Spotter column missing";
     EXPECT_EQ(result.find("Laps"), std::string::npos) << "Laps column should not exist";
diff --git a/test/test_formatter_itinerary.cpp b/test/test_formatter_itinerary.cpp
index bdc70d8..567cada 100644
--- a/test/test_formatter_itinerary.cpp
+++ b/test/test_formatter_itinerary.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_formatter_itinerary.cpp
+ * @brief Tests for itinerary generation logic.
+ */
+
 #include "gtest/gtest.h"
 #include "formatter/formatter_core.hpp"
 #include "nlohmann/json.hpp"
@@ -44,22 +49,22 @@ TEST(FormatterItineraryTest, ConsolidationAndTimezones) {
     // Check timezone offset
     EXPECT_EQ(itinerary.tz_offset, 2);
 
-    // Expecting: 1. Driving, 2. Resting, 3. Driving
+    // Expecting: Driving, Resting, Driving
     ASSERT_EQ(itinerary.items.size(), 3);
     
-    // Check Item 1: Driving Stint #1
+    // Check Item: Driving Stint #1
     const auto& drive_block1 = itinerary.items[0];
     EXPECT_EQ(drive_block1.activity, "Driving Stint #1");
     EXPECT_EQ(drive_block1.start_local.to_string(), "2023-01-01 14:00:00"); // 12:00 UTC + 2h
     EXPECT_EQ(drive_block1.end_local.to_string(), "2023-01-01 15:00:00");   // 13:00 UTC + 2h
 
-    // Check Item 2: Resting block between stints
+    // Check Item: Resting block between stints
     const auto& rest_block = itinerary.items[1];
     EXPECT_EQ(rest_block.activity, "Resting");
     EXPECT_EQ(rest_block.start_local.to_string(), "2023-01-01 15:00:00");
     EXPECT_EQ(rest_block.end_local.to_string(), "2023-01-01 15:05:00"); // 13:05 UTC + 2h
 
-    // Check Item 3: Driving Stint #2
+    // Check Item: Driving Stint #2
     const auto& drive_block2 = itinerary.items[2];
     EXPECT_EQ(drive_block2.activity, "Driving Stint #2");
     EXPECT_EQ(drive_block2.start_local.to_string(), "2023-01-01 15:05:00");
@@ -99,7 +104,7 @@ TEST(FormatterItineraryTest, NegativeTimezone) {
 
     ASSERT_EQ(itinerary.items.size(), 1);
 
-    // Check Item 1: Driving Stint #1
+    // Check Item: Driving Stint #1
     const auto& drive_block1 = itinerary.items[0];
     EXPECT_EQ(drive_block1.activity, "Driving Stint #1");
     EXPECT_EQ(drive_block1.start_local.to_string(), "2022-12-31 21:00:00"); // 02:00 UTC - 5h
diff --git a/test/test_formatter_summary.cpp b/test/test_formatter_summary.cpp
index 023ae83..bb95372 100644
--- a/test/test_formatter_summary.cpp
+++ b/test/test_formatter_summary.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_formatter_summary.cpp
+ * @brief Tests for summary report generation.
+ */
+
 #include "gtest/gtest.h"
 #include "formatter/formatter_core.hpp"
 #include <map>
diff --git a/test/test_minimum_rest.cpp b/test/test_minimum_rest.cpp
index 7a64f3e..e976048 100644
--- a/test/test_minimum_rest.cpp
+++ b/test/test_minimum_rest.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_minimum_rest.cpp
+ * @brief Tests for minimum rest time enforcement.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "jres_internal_types.hpp"
@@ -37,19 +42,19 @@ void check_rest_times(const jres::internal::SolverOutput& output, int minimumRes
         const auto& stints = pair.second;
         
         // We need to find ONE valid rest gap of duration >= MinRest WITHIN [RaceStart, RaceEnd].
-        // 1. Check Start Gap: [RaceStart, stints[0].start]
-        // 2. Check Inter-stint Gaps.
-        // 3. Check End Gap: [stints[last].end, RaceEnd]
+        // Check Start Gap: [RaceStart, stints[0].start]
+        // Check Inter-stint Gaps.
+        // Check End Gap: [stints[last].end, RaceEnd]
         
         bool satisfied = false;
         
-        // 1. Start Gap
+        // Start Gap
         auto firstStart = jres::internal::TimeHelpers::stringToTimePoint(stints[0].startTime);
         if (firstStart - raceStart >= minRestDuration) {
             satisfied = true;
         }
 
-        // 2. Middle Gaps
+        // Middle Gaps
         if (!satisfied) {
             for (size_t i = 0; i < stints.size() - 1; ++i) {
                 auto endTime = jres::internal::TimeHelpers::stringToTimePoint(stints[i].endTime);
@@ -61,7 +66,7 @@ void check_rest_times(const jres::internal::SolverOutput& output, int minimumRes
             }
         }
         
-        // 3. End Gap
+        // End Gap
         if (!satisfied) {
             auto lastEnd = jres::internal::TimeHelpers::stringToTimePoint(stints.back().endTime);
             if (raceEnd - lastEnd >= minRestDuration) {
@@ -81,10 +86,11 @@ TEST(MinimumRestTest, Enforcement) {
     // to avoid long runtimes and external dependencies.
     // Scenario: 3 Drivers, 6 Stints (1 hour each), 2 hours minimum rest.
     std::string json_str = R"({
+      "minimumRestHours": 2,
       "teamMembers": [
-        { "name": "D1", "isDriver": true, "minimumRestHours": 2 },
-        { "name": "D2", "isDriver": true, "minimumRestHours": 2 },
-        { "name": "D3", "isDriver": true, "minimumRestHours": 2 }
+        { "name": "D1", "isDriver": true },
+        { "name": "D2", "isDriver": true },
+        { "name": "D3", "isDriver": true }
       ],
       "availability": {
         "D1": {}, "D2": {}, "D3": {}
@@ -151,9 +157,10 @@ TEST(MinimumRestTest, FeasibleScenario) {
     // Using JSON construction
     std::string json_content = R"({
       "success": true,
+      "minimumRestHours": 1,
       "teamMembers": [
-        { "name": "D1", "isDriver": true, "minimumRestHours": 1 },
-        { "name": "D2", "isDriver": true, "minimumRestHours": 1 }
+        { "name": "D1", "isDriver": true },
+        { "name": "D2", "isDriver": true }
       ],
       "availability": {
         "D1": {}, "D2": {}
@@ -201,9 +208,10 @@ TEST(MinimumRestTest, IntegratedCombinedRest) {
     // Constraint should prevent D1 from spotting S2 OR S3 if that's the only rest window.
     
     std::string json_content = R"({
+      "minimumRestHours": 2,
       "teamMembers": [
-        { "name": "D1", "isDriver": true, "isSpotter": true, "minimumRestHours": 2 },
-        { "name": "D2", "isDriver": true, "isSpotter": true, "minimumRestHours": 0 }
+        { "name": "D1", "isDriver": true, "isSpotter": true },
+        { "name": "D2", "isDriver": true, "isSpotter": true }
       ],
       "availability": { "D1": {}, "D2": {} },
       "stints": [
diff --git a/test/test_optimization.cpp b/test/test_optimization.cpp
index 9797bba..0ada0c1 100644
--- a/test/test_optimization.cpp
+++ b/test/test_optimization.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_optimization.cpp
+ * @brief Tests for optimization incentives (consecutive stints, preferences, penalties).
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
@@ -6,13 +11,15 @@
 
 using json = nlohmann::json;
 
-TEST(OptimizationTest, IncentivizeConsecutiveStints) {
+TEST(OptimizationTest, EnforceConsecutiveStints) {
     // Scenario: 2 Team Members (can drive and spot), 4 Stints.
-    // Each member can do max 2 stints.
     // We want to see AABB or BBAA patterns for BOTH drivers and spotters.
+    // Global requirement: consecutiveStints = 2.
     
     json j;
     j["success"] = true;
+    j["consecutiveStints"] = 2;
+    j["minimumRestHours"] = 0;
     
     json members = json::array();
     std::vector<std::string> names = {"Member A", "Member B"};
@@ -20,9 +27,7 @@ TEST(OptimizationTest, IncentivizeConsecutiveStints) {
         members.push_back({
             {"name", name},
             {"isDriver", true},
-            {"isSpotter", true},
-            {"maxStints", 2},
-            {"minimumRestHours", 0}
+            {"isSpotter", true}
         });
     }
     j["teamMembers"] = members;
@@ -43,7 +48,7 @@ TEST(OptimizationTest, IncentivizeConsecutiveStints) {
     JresSolverInput* input = jres_input_from_json(json_str.c_str());
     ASSERT_NE(input, nullptr);
 
-    // --- Sub-test 1: Integrated Mode ---
+    // --- Sub-test: Integrated Mode ---
     {
         JresSolverOptions options;
         options.timeLimit = 10;
@@ -66,16 +71,18 @@ TEST(OptimizationTest, IncentivizeConsecutiveStints) {
             }
         }
 
-        // With 4 stints and maxStints=2, perfect consolidation is 2 switches (one middle break for each role, or AABB/BBAA)
-        // Consecutive pairs in AABB is 2: (A,A) and (B,B).
-        // Minimal acceptable is AABB or BBAA => 2 consecutive pairs.
+        // With 4 stints and consecutiveStints=2, we have 2 blocks.
+        // Block 0: Stints 0,1. Block 1: Stints 2,3.
+        // Stint 0 and 1 MUST be same driver. Stint 2 and 3 MUST be same driver.
+        // So we guarantee at least 2 consecutive pairs (0-1 and 2-3).
+        // If driver stays for both blocks (AAAA), we get 3 consecutive pairs.
         EXPECT_GE(driver_consecutive, 2) << "Integrated: Drivers should be consolidated (e.g. AABB).";
         EXPECT_GE(spotter_consecutive, 2) << "Integrated: Spotters should be consolidated (e.g. BBAA).";
 
         free_jres_solver_output(output);
     }
 
-    // --- Sub-test 2: Sequential Mode ---
+    // --- Sub-test: Sequential Mode ---
     {
         JresSolverOptions options;
         options.timeLimit = 10;
@@ -108,7 +115,7 @@ TEST(OptimizationTest, IncentivizeConsecutiveStints) {
 }
 
 TEST(OptimizationTest, PreferredOverAvailable) {
-    // Scenario: 2 Drivers, 2 Stints. maxStints=1 (Disable consecutive bonus).
+    // Scenario: 2 Drivers, 2 Stints. consecutiveStints=1.
     // Driver A: Stint 1 (Available), Stint 2 (Preferred)
     // Driver B: Stint 1 (Preferred), Stint 2 (Available)
     //
@@ -118,14 +125,15 @@ TEST(OptimizationTest, PreferredOverAvailable) {
     // Optimal Preference Order: B then A.
     // - S1 (B, Pref) + S2 (A, Pref) -> Cost -2.
     //
-    // This forces the solver to pick B first, proving it's looking at the "Preferred" weight
-    // and not just assigning in list order.
+    // This forces the solver to pick B first, proving it's looking at the "Preferred" weight.
 
     json j;
     j["success"] = true;
+    j["consecutiveStints"] = 1;
+    j["minimumRestHours"] = 0;
     j["teamMembers"] = {
-        {{"name", "Driver A"}, {"isDriver", true}, {"isSpotter", false}, {"maxStints", 1}, {"minimumRestHours", 0}},
-        {{"name", "Driver B"}, {"isDriver", true}, {"isSpotter", false}, {"maxStints", 1}, {"minimumRestHours", 0}}
+        {{"name", "Driver A"}, {"isDriver", true}, {"isSpotter", false}},
+        {{"name", "Driver B"}, {"isDriver", true}, {"isSpotter", false}}
     };
     j["stints"] = {
         {{"id", 1}, {"startTime", "2026-01-17T00:00:00.000Z"}, {"endTime", "2026-01-17T01:00:00.000Z"}},
@@ -166,28 +174,33 @@ TEST(OptimizationTest, ConsecutiveOverPreferred) {
     // Stint 3: A=Pref, B=Avail
     // Stint 4: A=Avail, B=Pref
     //
-    // Option 1 (Alternating/Split): A, B, A, B
-    // - Everyone gets their Preferred slots.
-    // - Total Preferred = 4. Cost = -4.0.
-    // - Consecutive Pairs = 0. Cost = 0.0.
-    // - Balance: Perfect (2 each). Cost = 0.
-    // - Total Cost = -4.0.
+    // Global Requirement: consecutiveStints = 2.
+    // This forces blocks of 2 stints.
+    // Block 0 (S1, S2):
+    // - A: Pref + Avail = Cost -1.
+    // - B: Avail + Pref = Cost -1.
+    // Cost is equal.
+    //
+    // Block 1 (S3, S4):
+    // - A: Pref + Avail = Cost -1.
+    // - B: Avail + Pref = Cost -1.
+    // Cost is equal.
     //
-    // Option 2 (Consecutive Blocks): A, A, B, B
-    // - A takes S1(Pref), S2(Avail). B takes S3(Avail), S4(Pref).
-    // - Total Preferred = 2. Cost = -2.0.
-    // - Consecutive Pairs = 2 (A-A, B-B). Cost = 2 * -1.5 = -3.0.
-    // - Balance: Perfect (2 each). Cost = 0.
-    // - Total Cost = -5.0.
+    // So AA BB or BB AA have same cost (-2).
+    // Mixed AB AB is IMPOSSIBLE because it violates consecutiveStints=2 (A would drive S1 only).
     //
-    // Since -5.0 < -4.0, the solver MUST choose Option 2 (Consecutive Blocks).
-    // This proves that the Consecutive Bonus (-1.5) outweighs the loss of a Preferred slot (1.0 difference).
+    // So the solver MUST output AABB or BBAA or AAAA or BBBB.
+    // AAAA cost: (-1) + (-1) = -2.
+    // So all valid solutions have same cost.
+    // We just check that we get blocks.
 
     json j;
     j["success"] = true;
+    j["consecutiveStints"] = 2;
+    j["minimumRestHours"] = 0;
     j["teamMembers"] = {
-        {{"name", "Driver A"}, {"isDriver", true}, {"isSpotter", false}, {"maxStints", 2}, {"minimumRestHours", 0}},
-        {{"name", "Driver B"}, {"isDriver", true}, {"isSpotter", false}, {"maxStints", 2}, {"minimumRestHours", 0}}
+        {{"name", "Driver A"}, {"isDriver", true}, {"isSpotter", false}},
+        {{"name", "Driver B"}, {"isDriver", true}, {"isSpotter", false}}
     };
     j["stints"] = {
         {{"id", 1}, {"startTime", "2026-01-17T00:00:00.000Z"}, {"endTime", "2026-01-17T01:00:00.000Z"}},
@@ -233,8 +246,14 @@ TEST(OptimizationTest, ConsecutiveOverPreferred) {
     // We expect pairs like AA BB or BB AA
     EXPECT_EQ(d1, d2) << "Stints 1 and 2 should be consecutive";
     EXPECT_EQ(d3, d4) << "Stints 3 and 4 should be consecutive";
-    EXPECT_NE(d2, d3) << "Drivers should switch between blocks";
-
+    // We don't necessarily expect a switch between blocks if cost is identical, 
+    // but typically the solver will find one of the optimal solutions.
+    // The previous test asserted EXPECT_NE(d2, d3). 
+    // If we have AAAA, it fails.
+    // But AAAA has same cost.
+    // However, usually we want to see distribution.
+    // Let's relax the check to just verifying blocks are consistent.
+    
     free_jres_solver_input(input);
     free_jres_solver_output(output);
 }
diff --git a/test/test_role_coupling.cpp b/test/test_role_coupling.cpp
index 86387b8..135df17 100644
--- a/test/test_role_coupling.cpp
+++ b/test/test_role_coupling.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_role_coupling.cpp
+ * @brief Tests for role coupling incentives (Driver -> Spotter transition).
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
diff --git a/test/test_rotation_beat.cpp b/test/test_rotation_beat.cpp
index 8eb747c..72834b2 100644
--- a/test/test_rotation_beat.cpp
+++ b/test/test_rotation_beat.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_rotation_beat.cpp
+ * @brief Tests for rotation beat (rhythm) enforcement.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
@@ -77,7 +82,7 @@ TEST(RotationBeatTest, EnforcesPattern) {
     JresSolverInput* input = jres_input_from_json(json_str.c_str());
     ASSERT_NE(input, nullptr);
 
-    // --- Case 1: Without Rotation Beat ---
+    // --- Case: Without Rotation Beat ---
     {
         JresSolverOptions options;
         options.timeLimit = 5;
@@ -101,7 +106,7 @@ TEST(RotationBeatTest, EnforcesPattern) {
         free_jres_solver_output(output);
     }
 
-    // --- Case 2: With Rotation Beat ---
+    // --- Case: With Rotation Beat ---
     {
         JresSolverOptions options;
         options.timeLimit = 5;
diff --git a/test/test_spotter_balancing.cpp b/test/test_spotter_balancing.cpp
new file mode 100644
index 0000000..3539f1e
--- /dev/null
+++ b/test/test_spotter_balancing.cpp
@@ -0,0 +1,106 @@
+/**
+ * @file test/test_spotter_balancing.cpp
+ * @brief Tests for spotter workload balancing.
+ */
+
+#include "gtest/gtest.h"
+#include "jres_solver/jres_solver.hpp"
+#include <vector>
+#include <string>
+#include <map>
+
+TEST(SpotterBalancingTest, IntegratedBalancing) {
+    const char* input_json = R"({
+        "consecutiveStints": 1,
+        "minimumRestHours": 0,
+        "teamMembers": [
+            { "name": "DriverA", "isDriver": true, "isSpotter": false },
+            { "name": "DriverB", "isDriver": true, "isSpotter": false },
+            { "name": "Spotter1", "isDriver": false, "isSpotter": true },
+            { "name": "Spotter2", "isDriver": false, "isSpotter": true }
+        ],
+        "availability": {},
+        "stints": [
+            { "id": 1, "startTime": "2023-01-01T12:00:00Z", "endTime": "2023-01-01T13:00:00Z" },
+            { "id": 2, "startTime": "2023-01-01T13:00:00Z", "endTime": "2023-01-01T14:00:00Z" },
+            { "id": 3, "startTime": "2023-01-01T14:00:00Z", "endTime": "2023-01-01T15:00:00Z" },
+            { "id": 4, "startTime": "2023-01-01T15:00:00Z", "endTime": "2023-01-01T16:00:00Z" },
+            { "id": 5, "startTime": "2023-01-01T16:00:00Z", "endTime": "2023-01-01T17:00:00Z" },
+            { "id": 6, "startTime": "2023-01-01T17:00:00Z", "endTime": "2023-01-01T18:00:00Z" },
+            { "id": 7, "startTime": "2023-01-01T18:00:00Z", "endTime": "2023-01-01T19:00:00Z" },
+            { "id": 8, "startTime": "2023-01-01T19:00:00Z", "endTime": "2023-01-01T20:00:00Z" }
+        ]
+    })";
+
+    JresSolverInput* input = jres_input_from_json(input_json);
+    JresSolverOptions options;
+    options.timeLimit = 10;
+    options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
+    options.allowNoSpotter = false;
+    options.optimalityGap = 0.0;
+    options.switchingPenalty = 0.0;
+    options.rotationBeatWeight = 0.0;
+
+    JresSolverOutput* output = solve_race_schedule(input, &options);
+    ASSERT_NE(output, nullptr);
+    ASSERT_EQ(output->diagnosis_len, 0);
+
+    std::map<std::string, int> counts;
+    for (int i = 0; i < output->schedule_len; ++i) {
+        counts[output->schedule[i].spotter]++;
+    }
+
+    EXPECT_EQ(counts["Spotter1"], 4);
+    EXPECT_EQ(counts["Spotter2"], 4);
+
+    free_jres_solver_input(input);
+    free_jres_solver_output(output);
+}
+
+TEST(SpotterBalancingTest, SequentialBalancing) {
+    const char* input_json = R"({
+        "consecutiveStints": 1,
+        "minimumRestHours": 0,
+        "teamMembers": [
+            { "name": "DriverA", "isDriver": true, "isSpotter": false },
+            { "name": "DriverB", "isDriver": true, "isSpotter": false },
+            { "name": "Spotter1", "isDriver": false, "isSpotter": true },
+            { "name": "Spotter2", "isDriver": false, "isSpotter": true }
+        ],
+        "availability": {},
+        "stints": [
+            { "id": 1, "startTime": "2023-01-01T12:00:00Z", "endTime": "2023-01-01T13:00:00Z" },
+            { "id": 2, "startTime": "2023-01-01T13:00:00Z", "endTime": "2023-01-01T14:00:00Z" },
+            { "id": 3, "startTime": "2023-01-01T14:00:00Z", "endTime": "2023-01-01T15:00:00Z" },
+            { "id": 4, "startTime": "2023-01-01T15:00:00Z", "endTime": "2023-01-01T16:00:00Z" },
+            { "id": 5, "startTime": "2023-01-01T16:00:00Z", "endTime": "2023-01-01T17:00:00Z" },
+            { "id": 6, "startTime": "2023-01-01T17:00:00Z", "endTime": "2023-01-01T18:00:00Z" },
+            { "id": 7, "startTime": "2023-01-01T18:00:00Z", "endTime": "2023-01-01T19:00:00Z" },
+            { "id": 8, "startTime": "2023-01-01T19:00:00Z", "endTime": "2023-01-01T20:00:00Z" }
+        ]
+    })";
+
+    JresSolverInput* input = jres_input_from_json(input_json);
+    JresSolverOptions options;
+    options.timeLimit = 10;
+    options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
+    options.allowNoSpotter = false;
+    options.optimalityGap = 0.0;
+    options.switchingPenalty = 0.0;
+    options.rotationBeatWeight = 0.0;
+
+    JresSolverOutput* output = solve_race_schedule(input, &options);
+    ASSERT_NE(output, nullptr);
+    ASSERT_EQ(output->diagnosis_len, 0);
+
+    std::map<std::string, int> counts;
+    for (int i = 0; i < output->schedule_len; ++i) {
+        counts[output->schedule[i].spotter]++;
+    }
+
+    EXPECT_EQ(counts["Spotter1"], 4);
+    EXPECT_EQ(counts["Spotter2"], 4);
+
+    free_jres_solver_input(input);
+    free_jres_solver_output(output);
+}
diff --git a/test/test_spotter_modes.cpp b/test/test_spotter_modes.cpp
index d96d7bd..6318ba8 100644
--- a/test/test_spotter_modes.cpp
+++ b/test/test_spotter_modes.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_spotter_modes.cpp
+ * @brief Tests for different spotter scheduling modes (None, Integrated, Sequential).
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
diff --git a/test/test_switching_penalty.cpp b/test/test_switching_penalty.cpp
index 80172fa..98061d6 100644
--- a/test/test_switching_penalty.cpp
+++ b/test/test_switching_penalty.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file test/test_switching_penalty.cpp
+ * @brief Tests for driver switching penalty enforcement.
+ */
+
 #include "gtest/gtest.h"
 #include "jres_solver/jres_solver.hpp"
 #include "nlohmann/json.hpp"
@@ -53,8 +58,10 @@ TEST(SwitchingPenaltyTest, ForceMinimumSwitches) {
     }
 
     // Since Fair Share forces both to drive, min switches = 1 (e.g. AAB).
-    // If penalty works, we should not see A-B-A (2 switches).
-    EXPECT_EQ(switches, 1) << "Should minimize switches to 1 (e.g. AAB or BBA)";
+    // However, with strict consecutiveStints=1 (default), AAB is invalid (A cannot drive 2 consecutive).
+    // So valid schedule is ABA (2 switches).
+    // If penalty works, we should not see A-B-A (2 switches) -> Wait, ABA IS the minimum now.
+    EXPECT_EQ(switches, 2) << "Should minimize switches to 2 (e.g. ABA) given strict consecutiveStints=1";
 
     // Verify both drivers drove (Fair Share check)
     std::set<std::string> drivers;

From f6e2b174011fe0ba9cdb13dad6696f4e63a5be3e Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Thu, 8 Jan 2026 20:44:11 -0800
Subject: [PATCH 6/7] fix initialization in tests

---
 test/CMakeLists.txt                                |  2 +-
 test/test_balancing.cpp                            |  2 +-
 test/test_constraints.cpp                          |  6 +++---
 test/test_diagnosis.cpp                            |  6 +++---
 test/test_errors.cpp                               |  6 +++---
 test/test_fair_share.cpp                           |  4 ++--
 ...e_issue.cpp => test_hard_consecutive_limit.cpp} |  4 ++--
 test/test_minimum_rest.cpp                         |  6 +++---
 test/test_optimization.cpp                         |  8 ++++----
 test/test_role_coupling.cpp                        |  4 ++--
 test/test_rotation_beat.cpp                        |  4 ++--
 test/test_spotter_balancing.cpp                    |  4 ++--
 test/test_spotter_modes.cpp                        | 14 +++++++-------
 test/test_switching_penalty.cpp                    |  2 +-
 14 files changed, 36 insertions(+), 36 deletions(-)
 rename test/{reproduce_issue.cpp => test_hard_consecutive_limit.cpp} (97%)

diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index eecfe1a..8401bf8 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -36,7 +36,7 @@ add_executable(solver_tests
   test_role_coupling.cpp
   test_rotation_beat.cpp
   test_spotter_balancing.cpp
-  reproduce_issue.cpp
+  test_hard_consecutive_limit.cpp
 )
 
 add_dependencies(solver_tests jres_solver_lib)
diff --git a/test/test_balancing.cpp b/test/test_balancing.cpp
index fc97655..0898683 100644
--- a/test/test_balancing.cpp
+++ b/test/test_balancing.cpp
@@ -45,7 +45,7 @@ TEST(BalancingTest, FairBalance) {
 
     std::string json_str = data.dump();
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = false;
diff --git a/test/test_constraints.cpp b/test/test_constraints.cpp
index 948c242..7cf197e 100644
--- a/test/test_constraints.cpp
+++ b/test/test_constraints.cpp
@@ -26,7 +26,7 @@ const char* INFEASIBLE_V2_JSON = R"({
 })";
 
 TEST(ConstraintTest, InfeasibleModel) {
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = false;
@@ -66,7 +66,7 @@ const char* PREFERRED_SLOT_V2_JSON = R"({
 })";
 
 TEST(ConstraintTest, PreferredSlot) {
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = false;
@@ -106,7 +106,7 @@ const char* NO_DRIVER_FOR_STINT_V2_JSON = R"({
 })";
 
 TEST(ConstraintTest, NoDriverForStint) {
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = false;
diff --git a/test/test_diagnosis.cpp b/test/test_diagnosis.cpp
index 138e352..0c70d47 100644
--- a/test/test_diagnosis.cpp
+++ b/test/test_diagnosis.cpp
@@ -20,7 +20,7 @@ namespace {
       ]
     })";
     TEST(DiagnosisTest, UnavailableDriver) {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_NONE;
         JresSolverInput* input = jres_input_from_json(UNAVAILABLE_V2_JSON);
@@ -51,7 +51,7 @@ namespace {
       ]
     })";
     TEST(DiagnosisTest, UnavailableSpotterIntegrated) {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
         options.allowNoSpotter = false;
@@ -90,7 +90,7 @@ namespace {
       ]
     })";
     TEST(DiagnosisTest, SequentialSpotterMode) {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
         options.allowNoSpotter = false;
diff --git a/test/test_errors.cpp b/test/test_errors.cpp
index af6b47e..cfaf333 100644
--- a/test/test_errors.cpp
+++ b/test/test_errors.cpp
@@ -26,7 +26,7 @@ namespace {
       "stints": [ { "id": 1, "startTime": "1973-06-09T14:37:00.000Z", "endTime": "1973-06-09T15:00:00.000Z" } ]
     })";
     TEST(ErrorTest, NoDrivers) {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_NONE;
         JresSolverInput* input = jres_input_from_json(NO_DRIVERS_V2_JSON);
@@ -46,7 +46,7 @@ namespace {
       "stints": [ { "id": 1, "startTime": "1973-06-09T14:37:00.000Z", "endTime": "1973-06-09T15:00:00.000Z" } ]
     })";
     TEST(ErrorTest, NoSpottersRequired) {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
         options.allowNoSpotter = false;
@@ -67,7 +67,7 @@ namespace {
       "stints": []
     })";
     TEST(ErrorTest, ZeroStints) {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_NONE;
         JresSolverInput* input = jres_input_from_json(ZERO_STINTS_V2_JSON);
diff --git a/test/test_fair_share.cpp b/test/test_fair_share.cpp
index b147e96..1e425ec 100644
--- a/test/test_fair_share.cpp
+++ b/test/test_fair_share.cpp
@@ -110,7 +110,7 @@ TEST(FairShareTest, EnforcesMinimumRequirement) {
     input.availability = availabilities.data();
     input.availability_len = (int)availabilities.size();
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 5;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = true;
@@ -175,7 +175,7 @@ TEST(FairShareTest, SuccessScenario) {
     input.availability = nullptr;
     input.availability_len = 0;
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 5;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = true;
diff --git a/test/reproduce_issue.cpp b/test/test_hard_consecutive_limit.cpp
similarity index 97%
rename from test/reproduce_issue.cpp
rename to test/test_hard_consecutive_limit.cpp
index 9df7a9f..a9c3cae 100644
--- a/test/reproduce_issue.cpp
+++ b/test/test_hard_consecutive_limit.cpp
@@ -1,5 +1,5 @@
 /**
- * @file test/reproduce_issue.cpp
+ * @file test/test_hard_consecutive_limit.cpp
  * @brief Tests for hard constraints on consecutive stints.
  */
 
@@ -45,7 +45,7 @@ TEST(ConstraintTest, EnforceConsecutiveStintsHardLimit) {
     JresSolverInput* input = jres_input_from_json(json_str.c_str());
     ASSERT_NE(input, nullptr);
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_NONE; // Focus on drivers
     options.allowNoSpotter = true;
diff --git a/test/test_minimum_rest.cpp b/test/test_minimum_rest.cpp
index e976048..31ca6ff 100644
--- a/test/test_minimum_rest.cpp
+++ b/test/test_minimum_rest.cpp
@@ -105,7 +105,7 @@ TEST(MinimumRestTest, Enforcement) {
       ]
     })";
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10; // Reduced time limit for simpler problem
     options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
     options.allowNoSpotter = false;
@@ -173,7 +173,7 @@ TEST(MinimumRestTest, FeasibleScenario) {
       ]
     })";
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     
     JresSolverInput* input = jres_input_from_json(json_content.c_str());
@@ -227,7 +227,7 @@ TEST(MinimumRestTest, IntegratedCombinedRest) {
     // Let's rely on the fact that D1 must have *some* 2h block free.
     // If we force D1 to participate in S1, S2, S3, S4, it should fail (infeasible).
     
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
     options.allowNoSpotter = false; 
 
diff --git a/test/test_optimization.cpp b/test/test_optimization.cpp
index 0ada0c1..d3a7fc6 100644
--- a/test/test_optimization.cpp
+++ b/test/test_optimization.cpp
@@ -50,7 +50,7 @@ TEST(OptimizationTest, EnforceConsecutiveStints) {
 
     // --- Sub-test: Integrated Mode ---
     {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
         options.allowNoSpotter = false;
@@ -84,7 +84,7 @@ TEST(OptimizationTest, EnforceConsecutiveStints) {
 
     // --- Sub-test: Sequential Mode ---
     {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 10;
         options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
         options.allowNoSpotter = false;
@@ -145,7 +145,7 @@ TEST(OptimizationTest, PreferredOverAvailable) {
     };
     j["firstStintDriver"] = nullptr;
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 5;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = true;
@@ -224,7 +224,7 @@ TEST(OptimizationTest, ConsecutiveOverPreferred) {
     };
     j["firstStintDriver"] = nullptr;
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 5;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = true;
diff --git a/test/test_role_coupling.cpp b/test/test_role_coupling.cpp
index 135df17..6ad910b 100644
--- a/test/test_role_coupling.cpp
+++ b/test/test_role_coupling.cpp
@@ -56,7 +56,7 @@ TEST(RoleCouplingTest, SelectionLogic) {
 
     // --- Integrated Mode ---
     {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 5;
         options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
         options.allowNoSpotter = false;
@@ -80,7 +80,7 @@ TEST(RoleCouplingTest, SelectionLogic) {
 
     // --- Sequential Mode ---
     {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 5;
         options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
         options.allowNoSpotter = false;
diff --git a/test/test_rotation_beat.cpp b/test/test_rotation_beat.cpp
index 72834b2..283c719 100644
--- a/test/test_rotation_beat.cpp
+++ b/test/test_rotation_beat.cpp
@@ -84,7 +84,7 @@ TEST(RotationBeatTest, EnforcesPattern) {
 
     // --- Case: Without Rotation Beat ---
     {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 5;
         options.spotterMode = JRES_SPOTTER_MODE_NONE;
         options.allowNoSpotter = true;
@@ -108,7 +108,7 @@ TEST(RotationBeatTest, EnforcesPattern) {
 
     // --- Case: With Rotation Beat ---
     {
-        JresSolverOptions options;
+        JresSolverOptions options = {};
         options.timeLimit = 5;
         options.spotterMode = JRES_SPOTTER_MODE_NONE;
         options.allowNoSpotter = true;
diff --git a/test/test_spotter_balancing.cpp b/test/test_spotter_balancing.cpp
index 3539f1e..928c46a 100644
--- a/test/test_spotter_balancing.cpp
+++ b/test/test_spotter_balancing.cpp
@@ -33,7 +33,7 @@ TEST(SpotterBalancingTest, IntegratedBalancing) {
     })";
 
     JresSolverInput* input = jres_input_from_json(input_json);
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
     options.allowNoSpotter = false;
@@ -81,7 +81,7 @@ TEST(SpotterBalancingTest, SequentialBalancing) {
     })";
 
     JresSolverInput* input = jres_input_from_json(input_json);
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 10;
     options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
     options.allowNoSpotter = false;
diff --git a/test/test_spotter_modes.cpp b/test/test_spotter_modes.cpp
index 6318ba8..b8e626a 100644
--- a/test/test_spotter_modes.cpp
+++ b/test/test_spotter_modes.cpp
@@ -41,7 +41,7 @@ namespace {
   })";
 
   TEST(SpotterModeTest, BasicIntegratedSolve) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 30;
       options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
       options.allowNoSpotter = false;
@@ -78,7 +78,7 @@ namespace {
   })";
 
   TEST(SpotterModeTest, ModeNone) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 10;
       options.spotterMode = JRES_SPOTTER_MODE_NONE;
       options.allowNoSpotter = false;
@@ -111,7 +111,7 @@ namespace {
   })";
 
   TEST(SpotterModeTest, IntegratedConflictInfeasible) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 10;
       options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
       options.allowNoSpotter = false;
@@ -147,7 +147,7 @@ namespace {
   })";
 
   TEST(SpotterModeTest, SequentialConflictSolvable) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 10;
       options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
       options.allowNoSpotter = false;
@@ -183,7 +183,7 @@ namespace {
   })";
 
   TEST(SpotterModeTest, AllowNoSpotterIntegrated) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 10;
       options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
       options.allowNoSpotter = true;
@@ -205,7 +205,7 @@ namespace {
   }
 
   TEST(SpotterModeTest, AllowNoSpotterSequential) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 10;
       options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
       options.allowNoSpotter = true;
@@ -241,7 +241,7 @@ namespace {
   })";
 
   TEST(SpotterModeTest, SequentialInfeasibleSpotter) {
-      JresSolverOptions options;
+      JresSolverOptions options = {};
       options.timeLimit = 10;
       options.spotterMode = JRES_SPOTTER_MODE_SEQUENTIAL;
       options.allowNoSpotter = false;
diff --git a/test/test_switching_penalty.cpp b/test/test_switching_penalty.cpp
index 98061d6..11feecc 100644
--- a/test/test_switching_penalty.cpp
+++ b/test/test_switching_penalty.cpp
@@ -34,7 +34,7 @@ TEST(SwitchingPenaltyTest, ForceMinimumSwitches) {
     j["availability"] = json::object(); // All available
     j["firstStintDriver"] = nullptr;
 
-    JresSolverOptions options;
+    JresSolverOptions options = {};
     options.timeLimit = 5;
     options.spotterMode = JRES_SPOTTER_MODE_NONE;
     options.allowNoSpotter = true;

From 2e3de54925391d722d46f48b284ad4bde575f44c Mon Sep 17 00:00:00 2001
From: popmonkey <popmonkey+github@gmail.com>
Date: Thu, 8 Jan 2026 21:06:00 -0800
Subject: [PATCH 7/7] refactor solver into smaller pieces

---
 CMakeLists.txt                     |   3 +
 CONTRIBUTING.md                    |   7 +-
 README.md                          |   2 +-
 src/analysis/capacity_analyzer.cpp | 115 +++++++++
 src/analysis/capacity_analyzer.hpp |  19 ++
 src/constraints/balancing.cpp      |  95 +++++++
 src/constraints/balancing.hpp      |  25 ++
 src/constraints/minimum_rest.cpp   | 152 +++++++++++
 src/constraints/minimum_rest.hpp   |  21 ++
 src/jres_internal_types.hpp        |   8 +
 src/jres_standard_solver.cpp       | 402 +++--------------------------
 src/jres_standard_solver.hpp       |  38 +--
 12 files changed, 483 insertions(+), 404 deletions(-)
 create mode 100644 src/analysis/capacity_analyzer.cpp
 create mode 100644 src/analysis/capacity_analyzer.hpp
 create mode 100644 src/constraints/balancing.cpp
 create mode 100644 src/constraints/balancing.hpp
 create mode 100644 src/constraints/minimum_rest.cpp
 create mode 100644 src/constraints/minimum_rest.hpp

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2c666a1..ec3c702 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -161,6 +161,9 @@ add_library(jres_solver_lib
   src/jres_internal_types.cpp
   src/jres_solver_base.cpp
   src/jres_standard_solver.cpp
+  src/analysis/capacity_analyzer.cpp
+  src/constraints/balancing.cpp
+  src/constraints/minimum_rest.cpp
 )
 set_target_properties(jres_solver_lib PROPERTIES OUTPUT_NAME "jres_solver")
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1818962..b3baab7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,11 +15,12 @@ It has been structured as a C-API library (`jres_solver`) and a simple CLI clien
 |   └── jres_solver/                # The public C-API header for the library
 ├── src/                            # The C++ library implementation
 |   ├── jres_solver.cpp             # C-API Wrapper and Orchestrator
-|   ├── jres_solver_base.cpp        # Shared logic for both solvers
-|   ├── jres_standard_solver.cpp    # Optimized Strict Solver
-|   ├── jres_diagnostic_solver.cpp  # Relaxed Diagnostic Solver
+|   ├── jres_solver_base.cpp        # Shared logic for the solver
+|   ├── jres_standard_solver.cpp    # Standard Solver (Elastic/Diagnostic enabled)
 |   ├── jres_internal_types.cpp     # Internal C++ data structures
 |   ├── jres_json_converter.cpp     # JSON conversion logic
+|   ├── analysis/                   # Analysis logic (e.g. capacity)
+|   ├── constraints/                # Constraint implementations
 |   ├── formatter/                  # Formatter implementation
 |   └── utils/                      # Utility functions
 ├── lib/
diff --git a/README.md b/README.md
index bac2ab3..58cd552 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ See [TOOLS.md](./TOOLS.md) for full usage.
 
 ## The Library
 
-**JresSolver** is a C++ library designed to optimize endurance racing schedules. It uses the **HiGHS** Mixed Integer Programming (MIP) solver to assign drivers (and optional spotters) to race stints while satisfying constraints such as fuel usage, maximum drive times, minimum rest periods, and driver availability.
+**JresSolver** is a C++ library designed to optimize endurance racing schedules. It uses the **HiGHS** Mixed Integer Programming (MIP) solver to assign drivers (and optional spotters) to race stints while satisfying constraints such as fuel usage, maximum drive times, minimum rest periods, and driver availability. The library utilizes a modular constraint architecture for flexibility and extensibility.
 
 ### Data Structures
 
diff --git a/src/analysis/capacity_analyzer.cpp b/src/analysis/capacity_analyzer.cpp
new file mode 100644
index 0000000..e72f25e
--- /dev/null
+++ b/src/analysis/capacity_analyzer.cpp
@@ -0,0 +1,115 @@
+#include "capacity_analyzer.hpp"
+#include <sstream>
+#include <iomanip>
+#include <chrono>
+
+namespace jres::internal {
+
+CapacityAnalysis CapacityAnalyzer::calculate_max_potential_capacity(
+    const std::vector<TeamMember>& participants,
+    const SolverInput& input)
+{
+    // Parse stint times once
+    std::vector<std::chrono::system_clock::time_point> startTimes;
+    std::vector<std::chrono::system_clock::time_point> endTimes;
+    startTimes.reserve(input.stints.size());
+    endTimes.reserve(input.stints.size());
+
+    std::chrono::system_clock::time_point raceStart;
+    std::chrono::system_clock::time_point raceEnd;
+    bool raceTimesInit = false;
+
+    for (const auto& stint : input.stints) {
+        auto s = TimeHelpers::stringToTimePoint(stint.startTime);
+        auto e = TimeHelpers::stringToTimePoint(stint.endTime);
+        startTimes.push_back(s);
+        endTimes.push_back(e);
+
+        if(!raceTimesInit) {
+            raceStart = s;
+            raceEnd = e;
+            raceTimesInit = true;
+        } else {
+            if(s < raceStart) raceStart = s;
+            if(e > raceEnd) raceEnd = e;
+        }
+    }
+
+    CapacityAnalysis analysis;
+    analysis.totalCapacity = 0;
+    std::ostringstream ss;
+
+    for (const auto& p : participants) {
+        // Build Availability
+        std::vector<bool> is_available(input.stints.size(), true);
+        auto member_availability_it = input.availability.find(p.name);
+        if (member_availability_it != input.availability.end()) {
+            for (size_t s = 0; s < input.stints.size(); ++s) {
+                std::string key = TimeHelpers::timePointToKey(startTimes[s]);
+                auto time_it = member_availability_it->second.find(key);
+                if (time_it != member_availability_it->second.end() && 
+                    time_it->second == Availability::Unavailable) {
+                    is_available[s] = false;
+                }
+            }
+        }
+
+        std::vector<bool> planned_drive(input.stints.size(), false);
+        int base_capacity = 0;
+        double driver_total_hours = 0.0;
+
+        for(size_t s=0; s<input.stints.size(); ++s) {
+            if (is_available[s]) {
+                planned_drive[s] = true;
+                base_capacity++;
+                
+                auto duration_ms = std::chrono::duration_cast<std::chrono::milliseconds>(endTimes[s] - startTimes[s]).count();
+                driver_total_hours += static_cast<double>(duration_ms) / 3600000.0;
+            }
+        }
+        
+        // Adjust for Global Minimum Rest (One Instance)
+        int final_capacity = base_capacity;
+        if (input.minimumRestHours > 0) {
+             auto minRestDuration = std::chrono::hours(input.minimumRestHours);
+             int min_loss = base_capacity; 
+             bool found_valid_window = false;
+
+             std::vector<std::chrono::system_clock::time_point> candidateStarts;
+             candidateStarts.push_back(raceStart);
+             for(const auto& t : endTimes) candidateStarts.push_back(t);
+
+             for(const auto& tStart : candidateStarts) {
+                 auto tEnd = tStart + minRestDuration;
+                 if (tEnd > raceEnd) continue;
+                 found_valid_window = true;
+
+                 int current_loss = 0;
+                 for(size_t s=0; s<input.stints.size(); ++s) {
+                     if (planned_drive[s]) {
+                         if (startTimes[s] < tEnd && endTimes[s] > tStart) {
+                             current_loss++;
+                         }
+                     }
+                 }
+                 if (current_loss < min_loss) min_loss = current_loss;
+             }
+             
+             if (!found_valid_window) {
+                 final_capacity = 0; // Impossible to satisfy rest
+             } else {
+                 final_capacity -= min_loss;
+             }
+        }
+        
+        analysis.totalCapacity += final_capacity;
+        
+        ss << "\n- " << p.name << ": " << final_capacity 
+           << " stints (approx " << std::fixed << std::setprecision(1) << driver_total_hours 
+           << "h, MinRest=" << input.minimumRestHours << "h)";
+    }
+    analysis.details = ss.str();
+    return analysis;
+}
+
+} // namespace jres::internal
diff --git a/src/analysis/capacity_analyzer.hpp b/src/analysis/capacity_analyzer.hpp
new file mode 100644
index 0000000..8735d82
--- /dev/null
+++ b/src/analysis/capacity_analyzer.hpp
@@ -0,0 +1,19 @@
+#pragma once
+#include "../jres_internal_types.hpp"
+
+namespace jres::internal {
+
+    struct CapacityAnalysis {
+        int totalCapacity;
+        std::string details;
+    };
+
+    class CapacityAnalyzer {
+    public:
+        static CapacityAnalysis calculate_max_potential_capacity(
+            const std::vector<TeamMember>& participants,
+            const SolverInput& input
+        );
+    };
+
+}
diff --git a/src/constraints/balancing.cpp b/src/constraints/balancing.cpp
new file mode 100644
index 0000000..fbef55a
--- /dev/null
+++ b/src/constraints/balancing.cpp
@@ -0,0 +1,95 @@
+#include "balancing.hpp"
+#include "Highs.h"
+#include <cmath>
+
+namespace jres::constraints {
+
+static const double kCostFairness = 10.0; 
+
+void add_role_coupling_incentive(
+    Highs* highs,
+    const std::vector<jres::internal::TeamMember>& pool,
+    const std::map<std::pair<std::string, int>, int>& driverVars,
+    const std::map<std::pair<std::string, int>, int>& spotterVars,
+    size_t numStints,
+    double weight)
+{
+    if (std::abs(weight) < 1e-6) return;
+
+    for (const auto &p : pool) {
+        for (size_t s = 0; s < numStints - 1; ++s) {
+            bool hasDriver = driverVars.count({p.name, (int)s});
+            bool hasSpotter = spotterVars.count({p.name, (int)s + 1});
+
+            if (hasDriver && hasSpotter) {
+                int d_var = driverVars.at({p.name, (int)s});
+                int s_var = spotterVars.at({p.name, (int)s + 1});
+
+                // If there is a transition from driving (stint s) to spotting (stint s+1), reward it.
+                
+                int coupling_var = highs->getNumCol();
+                highs->addVar(0.0, 1.0);
+                highs->changeColIntegrality(coupling_var, HighsVarType::kInteger);
+                highs->changeColCost(coupling_var, -weight);
+
+                // z <= d_var
+                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{coupling_var, d_var}.data(), std::vector<double>{1.0, -1.0}.data());
+                // z <= s_var
+                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{coupling_var, s_var}.data(), std::vector<double>{1.0, -1.0}.data());
+            }
+        }
+    }
+}
+
+void add_balancing_constraints(
+    Highs &highs,
+    const std::vector<jres::internal::TeamMember> &participants,
+    const jres::internal::SolverInput& input,
+    const std::map<std::pair<std::string, int>, int>& workVars,
+    double avgStints)
+{
+    for (const auto &p : participants) {
+        std::vector<int> stint_indices;
+        std::vector<double> stint_values;
+        
+        std::map<int, double> varCounts;
+        for (size_t s = 0; s < input.stints.size(); ++s) {
+            if (workVars.count({p.name, (int)s})) {
+                int v = workVars.at({p.name, (int)s});
+                varCounts[v] += 1.0;
+            }
+        }
+        for(auto const& [v, count] : varCounts) {
+            stint_indices.push_back(v);
+            stint_values.push_back(count);
+        }
+
+        if (stint_indices.empty()) continue;
+
+        int total_stints_var = highs.getNumCol();
+        highs.addVar(0.0, kHighsInf);
+        stint_indices.push_back(total_stints_var);
+        stint_values.push_back(-1.0);
+        highs.addRow(0.0, 0.0, (int)stint_indices.size(), stint_indices.data(), stint_values.data());
+
+        int over_avg_var = highs.getNumCol();
+        highs.addVar(0.0, kHighsInf);
+        int under_avg_var = highs.getNumCol();
+        highs.addVar(0.0, kHighsInf);
+        
+        std::vector<int> idx_over = {over_avg_var, total_stints_var};
+        std::vector<double> val_over = {1.0, -1.0};
+        highs.addRow(0.0, kHighsInf, 2, idx_over.data(), val_over.data());
+        highs.changeRowBounds(highs.getNumRow() - 1, -avgStints, kHighsInf);
+        
+        std::vector<int> idx_under = {under_avg_var, total_stints_var};
+        std::vector<double> val_under = {1.0, 1.0};
+        highs.addRow(0.0, kHighsInf, 2, idx_under.data(), val_under.data());
+        highs.changeRowBounds(highs.getNumRow() - 1, avgStints, kHighsInf);
+
+        highs.changeColCost(over_avg_var, kCostFairness);
+        highs.changeColCost(under_avg_var, kCostFairness);
+    }
+}
+
+} // namespace jres::constraints
diff --git a/src/constraints/balancing.hpp b/src/constraints/balancing.hpp
new file mode 100644
index 0000000..dbca537
--- /dev/null
+++ b/src/constraints/balancing.hpp
@@ -0,0 +1,25 @@
+#pragma once
+#include "../jres_internal_types.hpp"
+#include <map>
+#include <vector>
+
+class Highs;
+
+namespace jres::constraints {
+
+    void add_role_coupling_incentive(
+        Highs* highs,
+        const std::vector<jres::internal::TeamMember>& pool,
+        const std::map<std::pair<std::string, int>, int>& driverVars,
+        const std::map<std::pair<std::string, int>, int>& spotterVars,
+        size_t numStints,
+        double weight);
+
+    void add_balancing_constraints(
+        Highs &highs,
+        const std::vector<jres::internal::TeamMember> &participants,
+        const jres::internal::SolverInput& input,
+        const std::map<std::pair<std::string, int>, int>& workVars,
+        double avgStints);
+
+}
diff --git a/src/constraints/minimum_rest.cpp b/src/constraints/minimum_rest.cpp
new file mode 100644
index 0000000..d62cf7e
--- /dev/null
+++ b/src/constraints/minimum_rest.cpp
@@ -0,0 +1,152 @@
+#include "minimum_rest.hpp"
+#include "Highs.h"
+#include <algorithm>
+#include <chrono>
+
+namespace jres::constraints {
+
+static const double kPenaltySlack = 1000000.0;
+
+void apply_minimum_rest_constraints(
+        Highs &highs,
+        const jres::internal::SolverInput& input,
+        const std::vector<jres::internal::TeamMember> &participants,
+        const std::map<std::pair<std::string, int>, int>& driverVars,
+        const std::map<std::pair<std::string, int>, int>& spotterVars,
+        bool enforceCombined,
+        std::map<int, jres::internal::SlackInfo>& slackInfo
+    )
+{
+    using namespace jres::internal;
+
+    // Pre-parse stint times
+    std::vector<std::chrono::system_clock::time_point> startTimes;
+    std::vector<std::chrono::system_clock::time_point> endTimes;
+    startTimes.reserve(input.stints.size());
+    endTimes.reserve(input.stints.size());
+
+    // Find race start and end
+    std::chrono::system_clock::time_point raceStart;
+    std::chrono::system_clock::time_point raceEnd;
+    bool raceTimesInit = false;
+
+    for (const auto& stint : input.stints) {
+        auto s = TimeHelpers::stringToTimePoint(stint.startTime);
+        auto e = TimeHelpers::stringToTimePoint(stint.endTime);
+        startTimes.push_back(s);
+        endTimes.push_back(e);
+
+        if(!raceTimesInit) {
+            raceStart = s;
+            raceEnd = e;
+            raceTimesInit = true;
+        } else {
+            if(s < raceStart) raceStart = s;
+            if(e > raceEnd) raceEnd = e;
+        }
+    }
+
+    for (const auto &p : participants)
+    {
+        if (input.minimumRestHours <= 0) continue;
+        auto minRestDuration = std::chrono::hours(input.minimumRestHours);
+            
+        // Generate Candidates
+        std::vector<std::chrono::system_clock::time_point> candidateStarts;
+        candidateStarts.push_back(raceStart);
+        for(const auto& t : endTimes) candidateStarts.push_back(t);
+
+        // Build Block Sets
+        std::vector<std::set<int>> blockSets;
+        blockSets.reserve(candidateStarts.size());
+        
+        for(const auto& tStart : candidateStarts) {
+            auto tEnd = tStart + minRestDuration;
+            if (tEnd > raceEnd) continue;
+
+            std::set<int> blocked;
+            for(size_t s=0; s<input.stints.size(); ++s) {
+                // Overlap check
+                if (startTimes[s] < tEnd && endTimes[s] > tStart) {
+                    // Check Driver
+                    if (driverVars.count({p.name, (int)s})) {
+                        blocked.insert(driverVars.at({p.name, (int)s}));
+                    }
+                    // Check Spotter (if combined)
+                    if (enforceCombined && spotterVars.count({p.name, (int)s})) {
+                        blocked.insert(spotterVars.at({p.name, (int)s}));
+                    }
+                }
+            }
+            blockSets.push_back(blocked);
+        }
+
+        // Prune Supersets
+        std::vector<bool> keep(blockSets.size(), true);
+        bool anyEmpty = false;
+
+        for(size_t i=0; i<blockSets.size(); ++i) {
+            if (blockSets[i].empty()) {
+                anyEmpty = true;
+                break;
+            }
+        }
+
+        if (!anyEmpty) {
+            for(size_t i=0; i<blockSets.size(); ++i) {
+                if (!keep[i]) continue;
+                for(size_t j=0; j<blockSets.size(); ++j) {
+                    if (i == j || !keep[j]) continue;
+                    
+                    // Check if blockSets[j] is subset of blockSets[i]
+                    if (std::includes(blockSets[i].begin(), blockSets[i].end(), 
+                                        blockSets[j].begin(), blockSets[j].end())) {
+                        keep[i] = false;
+                        break; 
+                    }
+                }
+            }
+
+            // Create Variables
+            std::vector<int> restOptionVars;
+            for(size_t i=0; i<blockSets.size(); ++i) {
+                if(!keep[i]) continue;
+
+                int yVar = highs.getNumCol();
+                highs.addVar(0.0, 1.0);
+                highs.changeColIntegrality(yVar, HighsVarType::kInteger);
+                restOptionVars.push_back(yVar);
+                
+                // y + x <= 1
+                for(int stintVar : blockSets[i]) {
+                    highs.addRow(-kHighsInf, 1.0, 2, 
+                        std::vector<int>{yVar, stintVar}.data(),
+                        std::vector<double>{1.0, 1.0}.data());
+                }
+            }
+
+            if (!restOptionVars.empty()) {
+                // sum(y) + slack >= 1
+                int slackVar = highs.getNumCol();
+                highs.addVar(0.0, 1.0);
+                highs.changeColCost(slackVar, kPenaltySlack);
+                
+                SlackInfo info;
+                info.type = "Minimum Rest (One Instance)";
+                info.memberName = p.name;
+                info.stintIndex = -1; 
+                info.limit = 1.0;
+                slackInfo[slackVar] = info;
+
+                std::vector<int> idx = restOptionVars;
+                std::vector<double> val(idx.size(), 1.0);
+                idx.push_back(slackVar);
+                val.push_back(1.0);
+                
+                highs.addRow(1.0, kHighsInf, (int)idx.size(), idx.data(), val.data());
+            }
+        }
+    }
+}
+
+} // namespace jres::constraints
diff --git a/src/constraints/minimum_rest.hpp b/src/constraints/minimum_rest.hpp
new file mode 100644
index 0000000..1240d43
--- /dev/null
+++ b/src/constraints/minimum_rest.hpp
@@ -0,0 +1,21 @@
+#pragma once
+#include "../jres_internal_types.hpp"
+#include <map>
+#include <vector>
+#include <set>
+
+class Highs;
+
+namespace jres::constraints {
+
+    void apply_minimum_rest_constraints(
+        Highs &highs,
+        const jres::internal::SolverInput& input,
+        const std::vector<jres::internal::TeamMember> &participants,
+        const std::map<std::pair<std::string, int>, int>& driverVars,
+        const std::map<std::pair<std::string, int>, int>& spotterVars,
+        bool enforceCombined,
+        std::map<int, jres::internal::SlackInfo>& slackInfo
+    );
+
+}
diff --git a/src/jres_internal_types.hpp b/src/jres_internal_types.hpp
index dc9d73e..8143539 100644
--- a/src/jres_internal_types.hpp
+++ b/src/jres_internal_types.hpp
@@ -60,6 +60,14 @@ struct ScheduleEntry {
     std::string spotter;
 };
 
+struct SlackInfo {
+    std::string type;
+    std::string memberName;
+    int stintIndex;
+    double limit = 0.0;
+    double actual = 0.0;
+};
+
 struct SolverStats {
     int modelColumns = 0;
     int modelRows = 0;
diff --git a/src/jres_standard_solver.cpp b/src/jres_standard_solver.cpp
index 9160d5b..e1e0515 100644
--- a/src/jres_standard_solver.cpp
+++ b/src/jres_standard_solver.cpp
@@ -4,6 +4,9 @@
  * @brief Standard solver for the JRES Solver library (Elastic/Diagnostic enabled).
  */
 #include "jres_standard_solver.hpp"
+#include "analysis/capacity_analyzer.hpp"
+#include "constraints/balancing.hpp"
+#include "constraints/minimum_rest.hpp"
 #include <algorithm>
 #include <cmath>
 #include <chrono>
@@ -18,44 +21,6 @@ static const double kPenaltySlack = 1000000.0;
 static const double kPenaltyUnavailable = 10000000.0;
 static const double kRewardPreferred = -1.0;
 static const double kRewardProximity = -0.5; // Incentive for spotting adjacent to driving
-static const double kCostFairness = 10.0; 
-
-static void add_role_coupling_incentive(
-    Highs* highs,
-    const std::vector<jres::internal::TeamMember>& pool,
-    const std::map<std::pair<std::string, int>, int>& driverVars,
-    const std::map<std::pair<std::string, int>, int>& spotterVars,
-    size_t numStints,
-    double weight)
-{
-    if (std::abs(weight) < 1e-6) return;
-
-    for (const auto &p : pool) {
-        for (size_t s = 0; s < numStints - 1; ++s) {
-            bool hasDriver = driverVars.count({p.name, s});
-            bool hasSpotter = spotterVars.count({p.name, s + 1});
-
-            if (hasDriver && hasSpotter) {
-                int d_var = driverVars.at({p.name, s});
-                int s_var = spotterVars.at({p.name, s + 1});
-
-                // If there is a transition from driving (stint s) to spotting (stint s+1), reward it.
-                // If s and s+1 are in the same block, d_var == d_var_next (conceptually).
-                // Actually, d_var is the variable for stint s.
-                
-                int coupling_var = highs->getNumCol();
-                highs->addVar(0.0, 1.0);
-                highs->changeColIntegrality(coupling_var, HighsVarType::kInteger);
-                highs->changeColCost(coupling_var, -weight);
-
-                // z <= d_var
-                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{coupling_var, d_var}.data(), std::vector<double>{1.0, -1.0}.data());
-                // z <= s_var
-                highs->addRow(-kHighsInf, 0.0, 2, std::vector<int>{coupling_var, s_var}.data(), std::vector<double>{1.0, -1.0}.data());
-            }
-        }
-    }
-}
 
 JresStandardSolver::JresStandardSolver(const jres::internal::SolverInput& input, const JresSolverOptions& options)
     : JresSolverBase(input, options)
@@ -75,111 +40,6 @@ JresStandardSolver::JresStandardSolver(const jres::internal::SolverInput& input,
 
 JresStandardSolver::~JresStandardSolver() = default;
 
-JresStandardSolver::CapacityAnalysis JresStandardSolver::calculate_max_potential_capacity(const std::vector<jres::internal::TeamMember>& participants)
-{
-    // Parse stint times once
-    std::vector<std::chrono::system_clock::time_point> startTimes;
-    std::vector<std::chrono::system_clock::time_point> endTimes;
-    startTimes.reserve(m_input.stints.size());
-    endTimes.reserve(m_input.stints.size());
-
-    std::chrono::system_clock::time_point raceStart;
-    std::chrono::system_clock::time_point raceEnd;
-    bool raceTimesInit = false;
-
-    for (const auto& stint : m_input.stints) {
-        auto s = jres::internal::TimeHelpers::stringToTimePoint(stint.startTime);
-        auto e = jres::internal::TimeHelpers::stringToTimePoint(stint.endTime);
-        startTimes.push_back(s);
-        endTimes.push_back(e);
-
-        if(!raceTimesInit) {
-            raceStart = s;
-            raceEnd = e;
-            raceTimesInit = true;
-        } else {
-            if(s < raceStart) raceStart = s;
-            if(e > raceEnd) raceEnd = e;
-        }
-    }
-
-    CapacityAnalysis analysis;
-    analysis.totalCapacity = 0;
-    std::ostringstream ss;
-
-    for (const auto& p : participants) {
-        // Build Availability
-        std::vector<bool> is_available(m_input.stints.size(), true);
-        auto member_availability_it = m_input.availability.find(p.name);
-        if (member_availability_it != m_input.availability.end()) {
-            for (size_t s = 0; s < m_input.stints.size(); ++s) {
-                std::string key = jres::internal::TimeHelpers::timePointToKey(startTimes[s]);
-                auto time_it = member_availability_it->second.find(key);
-                if (time_it != member_availability_it->second.end() && 
-                    time_it->second == jres::internal::Availability::Unavailable) {
-                    is_available[s] = false;
-                }
-            }
-        }
-
-        std::vector<bool> planned_drive(m_input.stints.size(), false);
-        int base_capacity = 0;
-        double driver_total_hours = 0.0;
-
-        for(size_t s=0; s<m_input.stints.size(); ++s) {
-            if (is_available[s]) {
-                planned_drive[s] = true;
-                base_capacity++;
-                
-                auto duration_ms = std::chrono::duration_cast<std::chrono::milliseconds>(endTimes[s] - startTimes[s]).count();
-                driver_total_hours += static_cast<double>(duration_ms) / 3600000.0;
-            }
-        }
-        
-        // Adjust for Global Minimum Rest (One Instance)
-        int final_capacity = base_capacity;
-        if (m_input.minimumRestHours > 0) {
-             auto minRestDuration = std::chrono::hours(m_input.minimumRestHours);
-             int min_loss = base_capacity; 
-             bool found_valid_window = false;
-
-             std::vector<std::chrono::system_clock::time_point> candidateStarts;
-             candidateStarts.push_back(raceStart);
-             for(const auto& t : endTimes) candidateStarts.push_back(t);
-
-             for(const auto& tStart : candidateStarts) {
-                 auto tEnd = tStart + minRestDuration;
-                 if (tEnd > raceEnd) continue;
-                 found_valid_window = true;
-
-                 int current_loss = 0;
-                 for(size_t s=0; s<m_input.stints.size(); ++s) {
-                     if (planned_drive[s]) {
-                         if (startTimes[s] < tEnd && endTimes[s] > tStart) {
-                             current_loss++;
-                         }
-                     }
-                 }
-                 if (current_loss < min_loss) min_loss = current_loss;
-             }
-             
-             if (!found_valid_window) {
-                 final_capacity = 0; // Impossible to satisfy rest
-             } else {
-                 final_capacity -= min_loss;
-             }
-        }
-        
-        analysis.totalCapacity += final_capacity;
-        
-        ss << "\n- " << p.name << ": " << final_capacity 
-           << " stints (approx " << std::fixed << std::setprecision(1) << driver_total_hours 
-           << "h, MinRest=" << m_input.minimumRestHours << "h)";
-    }
-    analysis.details = ss.str();
-    return analysis;
-}
-
 void JresStandardSolver::add_participant_model(
     Highs &highs,
     const std::vector<jres::internal::TeamMember> &participants,
@@ -257,194 +117,6 @@ void JresStandardSolver::add_participant_model(
     }
 }
 
-void JresStandardSolver::add_balancing_constraints(
-    Highs &highs,
-    const std::vector<jres::internal::TeamMember> &participants,
-    const std::map<std::pair<std::string, int>, int>& workVars,
-    double avgStints)
-{
-    for (const auto &p : participants) {
-        std::vector<int> stint_indices;
-        std::vector<double> stint_values;
-        
-        std::map<int, double> varCounts;
-        for (size_t s = 0; s < m_input.stints.size(); ++s) {
-            if (workVars.count({p.name, (int)s})) {
-                int v = workVars.at({p.name, (int)s});
-                varCounts[v] += 1.0;
-            }
-        }
-        for(auto const& [v, count] : varCounts) {
-            stint_indices.push_back(v);
-            stint_values.push_back(count);
-        }
-
-        if (stint_indices.empty()) continue;
-
-        int total_stints_var = highs.getNumCol();
-        highs.addVar(0.0, kHighsInf);
-        stint_indices.push_back(total_stints_var);
-        stint_values.push_back(-1.0);
-        highs.addRow(0.0, 0.0, (int)stint_indices.size(), stint_indices.data(), stint_values.data());
-
-        int over_avg_var = highs.getNumCol();
-        highs.addVar(0.0, kHighsInf);
-        int under_avg_var = highs.getNumCol();
-        highs.addVar(0.0, kHighsInf);
-        
-        std::vector<int> idx_over = {over_avg_var, total_stints_var};
-        std::vector<double> val_over = {1.0, -1.0};
-        highs.addRow(0.0, kHighsInf, 2, idx_over.data(), val_over.data());
-        highs.changeRowBounds(highs.getNumRow() - 1, -avgStints, kHighsInf);
-        
-        std::vector<int> idx_under = {under_avg_var, total_stints_var};
-        std::vector<double> val_under = {1.0, 1.0};
-        highs.addRow(0.0, kHighsInf, 2, idx_under.data(), val_under.data());
-        highs.changeRowBounds(highs.getNumRow() - 1, avgStints, kHighsInf);
-
-        highs.changeColCost(over_avg_var, kCostFairness);
-        highs.changeColCost(under_avg_var, kCostFairness);
-    }
-}
-
-void JresStandardSolver::apply_minimum_rest_constraints(
-        Highs &highs,
-        const std::vector<jres::internal::TeamMember> &participants,
-        const std::map<std::pair<std::string, int>, int>& driverVars,
-        const std::map<std::pair<std::string, int>, int>& spotterVars,
-        bool enforceCombined
-    )
-{
-    // Pre-parse stint times
-    std::vector<std::chrono::system_clock::time_point> startTimes;
-    std::vector<std::chrono::system_clock::time_point> endTimes;
-    startTimes.reserve(m_input.stints.size());
-    endTimes.reserve(m_input.stints.size());
-
-    // Find race start and end
-    std::chrono::system_clock::time_point raceStart;
-    std::chrono::system_clock::time_point raceEnd;
-    bool raceTimesInit = false;
-
-    for (const auto& stint : m_input.stints) {
-        auto s = jres::internal::TimeHelpers::stringToTimePoint(stint.startTime);
-        auto e = jres::internal::TimeHelpers::stringToTimePoint(stint.endTime);
-        startTimes.push_back(s);
-        endTimes.push_back(e);
-
-        if(!raceTimesInit) {
-            raceStart = s;
-            raceEnd = e;
-            raceTimesInit = true;
-        } else {
-            if(s < raceStart) raceStart = s;
-            if(e > raceEnd) raceEnd = e;
-        }
-    }
-
-    for (const auto &p : participants)
-    {
-        if (m_input.minimumRestHours <= 0) continue;
-        auto minRestDuration = std::chrono::hours(m_input.minimumRestHours);
-            
-        // Generate Candidates
-        std::vector<std::chrono::system_clock::time_point> candidateStarts;
-        candidateStarts.push_back(raceStart);
-        for(const auto& t : endTimes) candidateStarts.push_back(t);
-
-        // Build Block Sets
-        std::vector<std::set<int>> blockSets;
-        blockSets.reserve(candidateStarts.size());
-        
-        for(const auto& tStart : candidateStarts) {
-            auto tEnd = tStart + minRestDuration;
-            if (tEnd > raceEnd) continue;
-
-            std::set<int> blocked;
-            for(size_t s=0; s<m_input.stints.size(); ++s) {
-                // Overlap check
-                if (startTimes[s] < tEnd && endTimes[s] > tStart) {
-                    // Check Driver
-                    if (driverVars.count({p.name, s})) {
-                        blocked.insert(driverVars.at({p.name, s}));
-                    }
-                    // Check Spotter (if combined)
-                    if (enforceCombined && spotterVars.count({p.name, s})) {
-                        blocked.insert(spotterVars.at({p.name, s}));
-                    }
-                }
-            }
-            blockSets.push_back(blocked);
-        }
-
-        // Prune Supersets
-        std::vector<bool> keep(blockSets.size(), true);
-        bool anyEmpty = false;
-
-        for(size_t i=0; i<blockSets.size(); ++i) {
-            if (blockSets[i].empty()) {
-                anyEmpty = true;
-                break;
-            }
-        }
-
-        if (!anyEmpty) {
-            for(size_t i=0; i<blockSets.size(); ++i) {
-                if (!keep[i]) continue;
-                for(size_t j=0; j<blockSets.size(); ++j) {
-                    if (i == j || !keep[j]) continue;
-                    
-                    // Check if blockSets[j] is subset of blockSets[i]
-                    if (std::includes(blockSets[i].begin(), blockSets[i].end(), 
-                                        blockSets[j].begin(), blockSets[j].end())) {
-                        keep[i] = false;
-                        break; 
-                    }
-                }
-            }
-
-            // Create Variables
-            std::vector<int> restOptionVars;
-            for(size_t i=0; i<blockSets.size(); ++i) {
-                if(!keep[i]) continue;
-
-                int yVar = highs.getNumCol();
-                highs.addVar(0.0, 1.0);
-                highs.changeColIntegrality(yVar, HighsVarType::kInteger);
-                restOptionVars.push_back(yVar);
-                
-                // y + x <= 1
-                for(int stintVar : blockSets[i]) {
-                    highs.addRow(-kHighsInf, 1.0, 2, 
-                        std::vector<int>{yVar, stintVar}.data(),
-                        std::vector<double>{1.0, 1.0}.data());
-                }
-            }
-
-            if (!restOptionVars.empty()) {
-                // sum(y) + slack >= 1
-                int slackVar = highs.getNumCol();
-                highs.addVar(0.0, 1.0);
-                highs.changeColCost(slackVar, kPenaltySlack);
-                
-                SlackInfo info;
-                info.type = "Minimum Rest (One Instance)";
-                info.memberName = p.name;
-                info.stintIndex = -1; 
-                info.limit = 1.0;
-                m_slackInfo[slackVar] = info;
-
-                std::vector<int> idx = restOptionVars;
-                std::vector<double> val(idx.size(), 1.0);
-                idx.push_back(slackVar);
-                val.push_back(1.0);
-                
-                highs.addRow(1.0, kHighsInf, (int)idx.size(), idx.data(), val.data());
-            }
-        }
-    }
-}
-
 jres::internal::SolverOutput JresStandardSolver::solve()
 {
     using namespace std::chrono;
@@ -453,7 +125,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
 
     // --- Arithmetic Pre-flight Check ---
     int totalStints = (int)m_input.stints.size();
-    CapacityAnalysis capAnalysis = calculate_max_potential_capacity(m_driverPool);
+    auto capAnalysis = jres::internal::CapacityAnalyzer::calculate_max_potential_capacity(m_driverPool, m_input);
     
     if (capAnalysis.totalCapacity < totalStints) {
         // Build detailed error message
@@ -495,8 +167,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             std::map<int, double> varDurations;
 
             for (size_t s = 0; s < m_input.stints.size(); ++s) {
-                if (m_driverWorkVars.count({p.name, s})) {
-                    int v = m_driverWorkVars.at({p.name, s});
+                if (m_driverWorkVars.count({p.name, (int)s})) {
+                    int v = m_driverWorkVars.at({p.name, (int)s});
                     varDurations[v] += stint_durations_hours[s];
                 }
             }
@@ -513,7 +185,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             m_highs->addVar(0.0, kHighsInf);
             m_highs->changeColCost(slackVar, kPenaltySlack);
             
-            SlackInfo info;
+            jres::internal::SlackInfo info;
             info.type = "Fair Share Rule (Minimum Time)";
             info.memberName = p.name;
             info.stintIndex = -1;
@@ -532,7 +204,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     const double avg_stints_per_driver = num_drivers > 0 ? num_stints / num_drivers : 0;
 
     if (num_drivers > 0) {
-        add_balancing_constraints(*m_highs, m_driverPool, m_driverWorkVars, avg_stints_per_driver);
+        jres::constraints::add_balancing_constraints(*m_highs, m_driverPool, m_input, m_driverWorkVars, avg_stints_per_driver);
     }
 
     // --- Coverage Constraints (One driver per stint) ---
@@ -542,8 +214,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         std::vector<double> values;
         for (const auto &p : m_driverPool)
         {
-            if (m_driverWorkVars.count({p.name, s})) {
-                indices.push_back(m_driverWorkVars.at({p.name, s}));
+            if (m_driverWorkVars.count({p.name, (int)s})) {
+                indices.push_back(m_driverWorkVars.at({p.name, (int)s}));
                 values.push_back(1.0);
             }
         }
@@ -564,9 +236,9 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             // Constraint: switchVar >= driver_s - driver_{s-1} for each driver
             // switchVar - driver_s + driver_{s-1} >= 0
             for (const auto& p : m_driverPool) {
-                if (m_driverWorkVars.count({p.name, s}) && m_driverWorkVars.count({p.name, s - 1})) {
-                    int var_s = m_driverWorkVars.at({p.name, s});
-                    int var_prev = m_driverWorkVars.at({p.name, s - 1});
+                if (m_driverWorkVars.count({p.name, (int)s}) && m_driverWorkVars.count({p.name, (int)s - 1})) {
+                    int var_s = m_driverWorkVars.at({p.name, (int)s});
+                    int var_prev = m_driverWorkVars.at({p.name, (int)s - 1});
                     
                     if (var_s != var_prev) { // Only add if different variables (blocks changed)
                         std::vector<int> idx = {switchVar, var_s, var_prev};
@@ -586,9 +258,9 @@ jres::internal::SolverOutput JresStandardSolver::solve()
                 size_t target_s = s % N;
                 
                 for (const auto& p : m_driverPool) {
-                    if (m_driverWorkVars.count({p.name, s}) && m_driverWorkVars.count({p.name, target_s})) {
-                        int var_current = m_driverWorkVars.at({p.name, s});
-                        int var_target = m_driverWorkVars.at({p.name, target_s});
+                    if (m_driverWorkVars.count({p.name, (int)s}) && m_driverWorkVars.count({p.name, (int)target_s})) {
+                        int var_current = m_driverWorkVars.at({p.name, (int)s});
+                        int var_target = m_driverWorkVars.at({p.name, (int)target_s});
 
                         // Create deviation variable d >= |current - target|
                         // We minimize d, so cost is +weight
@@ -620,12 +292,12 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         
         add_participant_model(*m_highs, m_spotterPool, m_spotterWorkVars);
 
-        add_role_coupling_incentive(m_highs.get(), m_driverPool, m_driverWorkVars, m_spotterWorkVars, m_input.stints.size(), m_options.roleCouplingWeight);
+        jres::constraints::add_role_coupling_incentive(m_highs.get(), m_driverPool, m_driverWorkVars, m_spotterWorkVars, m_input.stints.size(), m_options.roleCouplingWeight);
 
         // Spotter Balancing
         if (!m_spotterPool.empty()) {
             double avg_stints_per_spotter = static_cast<double>(m_input.stints.size()) / m_spotterPool.size();
-            add_balancing_constraints(*m_highs, m_spotterPool, m_spotterWorkVars, avg_stints_per_spotter);
+            jres::constraints::add_balancing_constraints(*m_highs, m_spotterPool, m_input, m_spotterWorkVars, avg_stints_per_spotter);
         }
 
         // Spotter Coverage
@@ -633,8 +305,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             std::vector<int> indices;
             std::vector<double> values;
             for (const auto& p : m_spotterPool) {
-                if (m_spotterWorkVars.count({p.name, s})) {
-                    indices.push_back(m_spotterWorkVars.at({p.name, s}));
+                if (m_spotterWorkVars.count({p.name, (int)s})) {
+                    indices.push_back(m_spotterWorkVars.at({p.name, (int)s}));
                     values.push_back(1.0);
                 }
             }
@@ -648,8 +320,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         for (const auto& p : m_input.teamMembers) {
             if (p.isDriver && p.isSpotter) {
                 for (size_t s = 0; s < m_input.stints.size(); ++s) {
-                    if (m_driverWorkVars.count({p.name, s}) && m_spotterWorkVars.count({p.name, s})) {
-                        std::vector<int> idx = { m_driverWorkVars.at({p.name, s}), m_spotterWorkVars.at({p.name, s}) };
+                    if (m_driverWorkVars.count({p.name, (int)s}) && m_spotterWorkVars.count({p.name, (int)s})) {
+                        std::vector<int> idx = { m_driverWorkVars.at({p.name, (int)s}), m_spotterWorkVars.at({p.name, (int)s}) };
                         std::vector<double> val = {1.0, 1.0};
                         m_highs->addRow(0.0, 1.0, 2, idx.data(), val.data());
                     }
@@ -660,7 +332,7 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     
     // Apply Rest Constraints
     bool enforceCombinedRest = (m_options.spotterMode == JRES_SPOTTER_MODE_INTEGRATED);
-    apply_minimum_rest_constraints(*m_highs, m_input.teamMembers, m_driverWorkVars, m_spotterWorkVars, enforceCombinedRest);
+    jres::constraints::apply_minimum_rest_constraints(*m_highs, m_input, m_input.teamMembers, m_driverWorkVars, m_spotterWorkVars, enforceCombinedRest, m_slackInfo);
 
 
     // --- Solve Main Model (Drivers + Spotters if Integrated) ---
@@ -724,8 +396,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         
         // Extract Driver
         for (const auto& p : m_driverPool) {
-            if (m_driverWorkVars.count({p.name, s})) {
-                int idx = m_driverWorkVars.at({p.name, s});
+            if (m_driverWorkVars.count({p.name, (int)s})) {
+                int idx = m_driverWorkVars.at({p.name, (int)s});
                 if (colValues[idx] > 0.5) {
                     entry.driver = p.name;
                     if (m_unavailableVars.count(idx)) {
@@ -739,8 +411,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
         // Extract Spotter (if Integrated)
         if (m_options.spotterMode == JRES_SPOTTER_MODE_INTEGRATED) {
             for (const auto& p : m_spotterPool) {
-                if (m_spotterWorkVars.count({p.name, s})) {
-                    int idx = m_spotterWorkVars.at({p.name, s});
+                if (m_spotterWorkVars.count({p.name, (int)s})) {
+                    int idx = m_spotterWorkVars.at({p.name, (int)s});
                     if (colValues[idx] > 0.5) {
                         entry.spotter = p.name;
                         if (m_unavailableVars.count(idx)) {
@@ -775,15 +447,15 @@ jres::internal::SolverOutput JresStandardSolver::solve()
 
             // Spotter Balancing
             double avg_stints_per_spotter = static_cast<double>(m_input.stints.size()) / m_spotterPool.size();
-            add_balancing_constraints(spotterSolver, m_spotterPool, m_spotterWorkVars, avg_stints_per_spotter);
+            jres::constraints::add_balancing_constraints(spotterSolver, m_spotterPool, m_input, m_spotterWorkVars, avg_stints_per_spotter);
 
             // Spotter Coverage Constraints
             for (size_t s = 0; s < m_input.stints.size(); ++s) {
                 std::vector<int> indices;
                 std::vector<double> values;
                 for (const auto& p : m_spotterPool) {
-                    if (m_spotterWorkVars.count({p.name, s})) {
-                        indices.push_back(m_spotterWorkVars.at({p.name, s}));
+                    if (m_spotterWorkVars.count({p.name, (int)s})) {
+                        indices.push_back(m_spotterWorkVars.at({p.name, (int)s}));
                         values.push_back(1.0);
                     }
                 }
@@ -796,8 +468,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             // Cannot spot if driving
             for (size_t s = 0; s < m_input.stints.size(); ++s) {
                 const std::string& driverName = output.schedule[s].driver;
-                if (driverName != "N/A" && m_spotterWorkVars.count({driverName, s})) {
-                    spotterSolver.changeColBounds(m_spotterWorkVars.at({driverName, s}), 0.0, 0.0);
+                if (driverName != "N/A" && m_spotterWorkVars.count({driverName, (int)s})) {
+                    spotterSolver.changeColBounds(m_spotterWorkVars.at({driverName, (int)s}), 0.0, 0.0);
                 }
             }
 
@@ -806,8 +478,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
             std::map<int, double> spotterRewards;
             for (const auto& p : m_spotterPool) {
                 for (size_t s = 0; s < m_input.stints.size(); ++s) {
-                     if (!m_spotterWorkVars.count({p.name, s})) continue;
-                     int varIdx = m_spotterWorkVars.at({p.name, s});
+                     if (!m_spotterWorkVars.count({p.name, (int)s})) continue;
+                     int varIdx = m_spotterWorkVars.at({p.name, (int)s});
                      
                      double additionalReward = 0.0;
                      if (s > 0 && output.schedule[s-1].driver == p.name) {
@@ -854,8 +526,8 @@ jres::internal::SolverOutput JresStandardSolver::solve()
 
                 for (size_t s = 0; s < m_input.stints.size(); ++s) {
                     for (const auto& p : m_spotterPool) {
-                        if (m_spotterWorkVars.count({p.name, s})) {
-                            int idx = m_spotterWorkVars.at({p.name, s});
+                        if (m_spotterWorkVars.count({p.name, (int)s})) {
+                            int idx = m_spotterWorkVars.at({p.name, (int)s});
                             if (sColValues[idx] > 0.5) {
                                 output.schedule[s].spotter = p.name;
                                 if (m_unavailableVars.count(idx)) {
@@ -874,4 +546,4 @@ jres::internal::SolverOutput JresStandardSolver::solve()
     
     output.teamMembers = m_input.teamMembers;
     return output;
-}
+}
\ No newline at end of file
diff --git a/src/jres_standard_solver.hpp b/src/jres_standard_solver.hpp
index 986ced2..f232e83 100644
--- a/src/jres_standard_solver.hpp
+++ b/src/jres_standard_solver.hpp
@@ -6,6 +6,7 @@
 #pragma once
 
 #include "jres_solver_base.hpp"
+#include "jres_internal_types.hpp"
 #include <memory>
 #include <set>
 #include <map>
@@ -29,45 +30,12 @@ class JresStandardSolver : public JresSolverBase
         std::map<std::pair<std::string, int>, int>& workVars
     );
 
-    // Incentivize balanced participation (Soft Constraint)
-    void add_balancing_constraints(
-        Highs &highs,
-        const std::vector<jres::internal::TeamMember> &participants,
-        const std::map<std::pair<std::string, int>, int>& workVars,
-        double avgStints
-    );
-
-    // Enforce minimum rest constraints (potentially across both roles)
-    void apply_minimum_rest_constraints(
-        Highs &highs,
-        const std::vector<jres::internal::TeamMember> &participants,
-        const std::map<std::pair<std::string, int>, int>& driverVars,
-        const std::map<std::pair<std::string, int>, int>& spotterVars,
-        bool enforceCombined
-    );
-
-    struct CapacityAnalysis {
-        int totalCapacity;
-        std::string details;
-    };
-
-    // Helper for pre-flight feasibility check
-    CapacityAnalysis calculate_max_potential_capacity(const std::vector<jres::internal::TeamMember>& participants);
-
-    struct SlackInfo {
-        std::string type;
-        std::string memberName;
-        int stintIndex;
-        double limit = 0.0;
-        double actual = 0.0;
-    };
-
     std::unique_ptr<Highs> m_highs;
     std::map<std::pair<std::string, int>, int> m_driverWorkVars;
     std::map<std::pair<std::string, int>, int> m_spotterWorkVars;
     std::map<std::pair<std::string, int>, int> m_switchVars;
 
     // Elastic Solver State
-    std::map<int, SlackInfo> m_slackInfo;
+    std::map<int, jres::internal::SlackInfo> m_slackInfo;
     std::set<int> m_unavailableVars;
-};
\ No newline at end of file
+};