[Refactor] Production readiness: thread-safety, performance, and testing

- Add ASAN, UBSAN, TSAN sanitizer options to CMakeLists.txt
- Add sanitizer CI jobs (ASAN+UBSAN, TSAN separately - mutually exclusive)
- Fix null pointer dereference in A* multi-goal search (UBSAN detected)
  - Added is_multi_goal_search_ flag to SearchContext
  - A* strategy now checks flag before dereferencing goal iterator
- Update README.md with production features section
- Create CHANGELOG.md with unreleased changes
- Update test count to 317 in README

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rxdu

.github/workflows/ci.yml

@@ -96,9 +96,42 @@ jobs:
     - uses: codecov/codecov-action@v5
       if: github.ref == 'refs/heads/main'
       with:
-        fail_ci_if_error: true 
+        fail_ci_if_error: true
         files: ./build/coverage.info
         exclude: tests, src/demo
         flags: unittests # optional
         token: ${{ secrets.CODECOV_TOKEN }} # required
-        verbose: true # optional (default = false)
+        verbose: true # optional (default = false)
+
+  # AddressSanitizer + UndefinedBehaviorSanitizer
+  sanitize-asan:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Update submodules
+      run: git submodule update --init --recursive
+    - name: Configure with ASAN + UBSAN
+      run: mkdir build && cd build && cmake -DBUILD_TESTING=ON -DENABLE_ASAN=ON -DENABLE_UBSAN=ON -DCMAKE_BUILD_TYPE=Debug ..
+    - name: Build
+      run: cmake --build build
+    - name: Run tests with ASAN + UBSAN
+      env:
+        ASAN_OPTIONS: detect_leaks=1:abort_on_error=1
+        UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
+      run: cd build && ./bin/utests
+
+  # ThreadSanitizer (separate job - incompatible with ASAN)
+  sanitize-tsan:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Update submodules
+      run: git submodule update --init --recursive
+    - name: Configure with TSAN
+      run: mkdir build && cd build && cmake -DBUILD_TESTING=ON -DENABLE_TSAN=ON -DCMAKE_BUILD_TYPE=Debug ..
+    - name: Build
+      run: cmake --build build
+    - name: Run tests with TSAN
+      env:
+        TSAN_OPTIONS: halt_on_error=1:second_deadlock_stack=1
+      run: cd build && ./bin/utests

CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **PathResult struct**: Rich search results with `total_cost`, `nodes_expanded`, and `found` flag
+- **SearchLimits struct**: Early termination via `max_expansions` or `timeout_ms`
+- **Multi-goal search**: `Dijkstra::SearchMultiGoal()` and `AStar::SearchMultiGoal()` find path to nearest goal
+- **Nodes expanded counter**: `context.GetNodesExpanded()` for search diagnostics
+- **Debug cost assertions**: Validate non-negative, finite costs in debug builds (`debug_checks.hpp`)
+- **Production readiness documentation**: `docs/PRODUCTION_READINESS.md`
+- **14 new unit tests** for production features (317 total tests)
+
+### Changed
+- **Deterministic tie-breaking**: Priority queue comparators now break ties by `vertex_id` for reproducible results
+
+### Fixed
+- **Iterator invalidation**: `Edge` and `Vertex::vertices_from` now use stable `Vertex*` pointers instead of iterators that could invalidate on `unordered_map` rehash
+
+## [3.0.1] - 2025-08-19
+
+### Fixed
+- Codecov configuration updates
+
+## [3.0.0] - 2025-08-19
+
+### Added
+- Unified search framework with CRTP strategy pattern
+- Thread-safe concurrent searches via external `SearchContext`
+- Generic cost type support with `CostTraits`
+- `DynamicPriorityQueue` for efficient priority updates
+- Comprehensive exception handling with custom exception types
+- Structure validation for graphs and trees
+- Extensive documentation and tutorials
+
+### Changed
+- Major API redesign for thread safety and generic costs
+- Search algorithms now accept `SearchContext&` for thread-safe operation
+- Improved memory management with RAII patterns
+
+## [2.x] - Previous Releases
+
+See git history for earlier changes.

CMakeLists.txt

@@ -6,6 +6,9 @@ option(BUILD_TESTING "Build tests" OFF)
 option(BUILD_SAMPLES "Build samples" ON)
 option(STATIC_CHECK "Perform static check" OFF)
 option(COVERAGE_CHECK "Perform coverage check" OFF)
+option(ENABLE_ASAN "Enable AddressSanitizer" OFF)
+option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)
+option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
 
 # sanity check of the options
 if (COVERAGE_CHECK)
@@ -32,6 +35,30 @@ if (COVERAGE_CHECK)
   endif ()
 endif ()
 
+# Sanitizer configuration
+# Note: ASAN and TSAN are mutually exclusive
+if (ENABLE_ASAN AND ENABLE_TSAN)
+  message(FATAL_ERROR "ASAN and TSAN cannot be enabled simultaneously")
+endif ()
+
+if (ENABLE_ASAN)
+  message(STATUS "AddressSanitizer enabled")
+  add_compile_options(-fsanitize=address -fno-omit-frame-pointer -g)
+  add_link_options(-fsanitize=address)
+endif ()
+
+if (ENABLE_UBSAN)
+  message(STATUS "UndefinedBehaviorSanitizer enabled")
+  add_compile_options(-fsanitize=undefined -fno-omit-frame-pointer -g)
+  add_link_options(-fsanitize=undefined)
+endif ()
+
+if (ENABLE_TSAN)
+  message(STATUS "ThreadSanitizer enabled")
+  add_compile_options(-fsanitize=thread -fno-omit-frame-pointer -g)
+  add_link_options(-fsanitize=thread)
+endif ()
+
 ## Additional cmake module path
 set(USER_CMAKE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 list(APPEND CMAKE_MODULE_PATH "${USER_CMAKE_PATH}/modules")

README.md

@@ -87,6 +87,29 @@ void worker_thread(const Graph<Location>* graph) {
 
 **Graph modifications** require external synchronization (by design for performance).
 
+### Production Features (v3.1.0)
+
+**Rich search results** with cost and diagnostics:
+```cpp
+auto result = SearchAlgorithm<...>::SearchWithResult(graph, context, start, goal, strategy);
+if (result.found) {
+    std::cout << "Cost: " << result.total_cost << ", Expanded: " << result.nodes_expanded;
+}
+```
+
+**Bounded search** for real-time systems:
+```cpp
+auto limits = SearchLimits::MaxExpansions(1000);  // or SearchLimits::Timeout(50)
+auto result = SearchAlgorithm<...>::SearchWithLimits(graph, context, start, goal, strategy, limits);
+```
+
+**Multi-goal search** (find nearest goal):
+```cpp
+std::vector<Location> goals = {charging_station1, charging_station2, charging_station3};
+auto result = Dijkstra::SearchMultiGoal(graph, context, robot_position, goals);
+// result.goal_index tells which goal was reached
+```
+
 ---
 
 ## Build & Integration
@@ -144,7 +167,7 @@ cmake --build .
 ./bin/simple_graph_demo
 ./bin/thread_safe_search_demo
 
-# Run comprehensive tests (199 tests, 100% pass rate)
+# Run comprehensive tests (317 tests, 100% pass rate)
 ./bin/utests
 ```
 
@@ -186,6 +209,7 @@ auto path = Dijkstra::Search(map, {0, "Home"}, {1, "Work"});
 - **[Architecture Overview](docs/architecture.md)** - System design and template patterns
 - **[Advanced Features](docs/advanced_features.md)** - Custom costs, validation, thread safety
 - **[Search Algorithms Guide](docs/search_algorithms.md)** - Deep dive into A*, Dijkstra, BFS, DFS
+- **[Production Readiness](docs/PRODUCTION_READINESS.md)** - Robotics deployment guide
 
 ### **For Contributors**
 - **[Performance Testing](docs/performance_testing.md)** - Benchmarking and optimization

include/graph/search/astar.hpp

@@ -60,9 +60,15 @@ class AStarStrategy : public SearchStrategy<AStarStrategy<State, Transition, Sta
 
     void InitializeVertexImpl(SearchInfo& info, vertex_iterator vertex,
                              vertex_iterator goal_vertex,
-                             typename Base::SearchContextType& /*context*/) const {
+                             typename Base::SearchContextType& context) const {
         info.SetGCost(Transition{});
-        Transition h_cost = heuristic_(vertex->state, goal_vertex->state);
+
+        // In multi-goal mode, goal_vertex is vertex_end() (invalid), skip heuristic
+        Transition h_cost{};
+        if (!context.IsMultiGoalSearch()) {
+            h_cost = heuristic_(vertex->state, goal_vertex->state);
+        }
+
         info.SetHCost(h_cost);
         info.SetFCost(Transition{} + h_cost);
         info.SetChecked(false);
@@ -73,7 +79,7 @@ class AStarStrategy : public SearchStrategy<AStarStrategy<State, Transition, Sta
     bool RelaxVertexImpl(SearchInfo& current_info, SearchInfo& successor_info,
                         vertex_iterator successor_vertex, vertex_iterator goal_vertex,
                         const Transition& edge_cost,
-                        typename Base::SearchContextType& /*context*/) const {
+                        typename Base::SearchContextType& context) const {
 
         // Debug assertions for cost validity
         debug::AssertValidEdgeCost(edge_cost, "A* RelaxVertex: edge cost");
@@ -88,9 +94,13 @@ class AStarStrategy : public SearchStrategy<AStarStrategy<State, Transition, Sta
 
         if (this->cost_comparator_(new_g_cost, successor_g_cost)) {
             successor_info.SetGCost(new_g_cost);
-            Transition h_cost = heuristic_(successor_vertex->state, goal_vertex->state);
 
-            debug::AssertValidHeuristic(h_cost, "A* RelaxVertex: heuristic value");
+            // In multi-goal mode, goal_vertex is vertex_end() (invalid), skip heuristic
+            Transition h_cost{};
+            if (!context.IsMultiGoalSearch()) {
+                h_cost = heuristic_(successor_vertex->state, goal_vertex->state);
+                debug::AssertValidHeuristic(h_cost, "A* RelaxVertex: heuristic value");
+            }
 
             successor_info.SetHCost(h_cost);
             successor_info.SetFCost(new_g_cost + h_cost);

include/graph/search/search_algorithm.hpp

@@ -331,6 +331,9 @@ class SearchAlgorithm final {
         // Clear previous search data but preserve allocated memory
         context.Reset();
 
+        // Single-goal search mode
+        context.SetMultiGoalSearch(false);
+
         // Track start vertex for reliable path reconstruction
         context.SetStartVertexId(start->vertex_id);
 
@@ -467,6 +470,9 @@ class SearchAlgorithm final {
         // Clear previous search data but preserve allocated memory
         context.Reset();
 
+        // Multi-goal search mode - strategies should not dereference goal_vertex
+        context.SetMultiGoalSearch(true);
+
         // Track start vertex for reliable path reconstruction
         context.SetStartVertexId(start->vertex_id);
 

include/graph/search/search_context.hpp

@@ -399,6 +399,10 @@ class SearchContext {
   /// Useful for diagnostics and heuristic tuning
   size_t nodes_expanded_ = 0;
 
+  /// Flag indicating multi-goal search mode
+  /// When true, strategies should not dereference goal_vertex (it may be vertex_end())
+  bool is_multi_goal_search_ = false;
+
   /// Default reserve size for moderate-sized graphs
   static constexpr size_t DEFAULT_RESERVE_SIZE = 1000;
 
@@ -478,6 +482,30 @@ class SearchContext {
     nodes_expanded_ = 0;
   }
 
+  /**
+   * @brief Check if this is a multi-goal search
+   *
+   * When true, strategies should not dereference goal_vertex iterators
+   * as they may be vertex_end() (invalid). Use h_cost = 0 instead.
+   *
+   * @return True if multi-goal search mode is active
+   */
+  bool IsMultiGoalSearch() const noexcept {
+    return is_multi_goal_search_;
+  }
+
+  /**
+   * @brief Set multi-goal search mode
+   *
+   * Called by search algorithms to indicate multi-goal mode.
+   * Strategies use this to avoid dereferencing invalid goal iterators.
+   *
+   * @param is_multi_goal True for multi-goal search, false for single-goal
+   */
+  void SetMultiGoalSearch(bool is_multi_goal) noexcept {
+    is_multi_goal_search_ = is_multi_goal;
+  }
+
   /**
    * @brief Get search information for a vertex
    * @param vertex_id The ID of the vertex
@@ -573,6 +601,8 @@ class SearchContext {
     start_vertex_id_ = -1;
     // Reset nodes expanded counter
     nodes_expanded_ = 0;
+    // Reset multi-goal flag
+    is_multi_goal_search_ = false;
     // Keep allocated memory in the map for next search
     // This avoids reallocating hash table buckets
   }