docs: add solverforge-cvrp wireframe and update README

Author: blackopsrepl

README.md

@@ -38,6 +38,7 @@ This enables aggressive compiler optimizations and cache-friendly data layouts.
 - **SERIO Engine**: Scoring Engine for Real-time Incremental Optimization
 - **Solver Phases**:
   - Construction Heuristic (FirstFit, BestFit, FirstFeasible, WeakestFit, StrongestFit, CheapestInsertion, RegretInsertion)
+  - List Construction (CheapestInsertion, RegretInsertion, ClarkeWright savings, K-Opt polishing)
   - Local Search (Hill Climbing, Simulated Annealing, Tabu Search, Late Acceptance, Great Deluge, Step Counting Hill Climbing, Diversified Late Acceptance)
   - Exhaustive Search (Branch and Bound with DFS/BFS/Score-First)
   - Partitioned Search (multi-threaded via rayon)
@@ -251,6 +252,7 @@ With `features = ["console"]`, SolverForge displays colorful progress:
 | `solverforge-config` | Configuration via TOML and builder API |
 | `solverforge-console` | Tracing-based console output with banner and progress display |
 | `solverforge-macros` | Procedural macros for domain model |
+| `solverforge-cvrp` | CVRP domain helpers: `VrpSolution`, `ProblemData`, distance meters, feasibility functions |
 
 ## Score Types
 
@@ -362,7 +364,7 @@ Typical throughput: 300k-1M moves/second depending on constraint complexity for
 
 ## Status
 
-**Current Version**: 0.5.10
+**Current Version**: 0.5.14
 
 ### What's New in 0.5.7
 

crates/solverforge-cvrp/WIREFRAME.md

@@ -0,0 +1,90 @@
+# solverforge-cvrp WIREFRAME
+
+Domain helpers for Capacitated Vehicle Routing Problems (CVRP).
+
+**Location:** `crates/solverforge-cvrp/`
+
+## Dependencies
+
+- `solverforge` (workspace) — Facade; re-exports `CrossEntityDistanceMeter`
+
+## File Map
+
+```
+src/
+└── lib.rs   — All public types and free functions
+```
+
+## Types
+
+### `ProblemData`
+
+Immutable problem data shared by all vehicles. Fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `capacity` | `i64` | Vehicle capacity |
+| `depot` | `usize` | Depot node index |
+| `demands` | `Vec<i32>` | Demand per node |
+| `distance_matrix` | `Vec<Vec<i64>>` | Distance matrix |
+| `time_windows` | `Vec<(i64, i64)>` | `(min_start, max_end)` per node |
+| `service_durations` | `Vec<i64>` | Service duration per node |
+| `travel_times` | `Vec<Vec<i64>>` | Travel time matrix |
+| `vehicle_departure_time` | `i64` | Departure time from depot |
+
+### `VrpSolution` (trait)
+
+Trait implemented by a planning solution that holds a fleet of vehicles.
+
+| Method | Signature |
+|--------|-----------|
+| `vehicle_data_ptr` | `fn(&self, entity_idx: usize) -> *const ProblemData` |
+| `vehicle_visits` | `fn(&self, entity_idx: usize) -> &[usize]` |
+| `vehicle_visits_mut` | `fn(&mut self, entity_idx: usize) -> &mut Vec<usize>` |
+| `vehicle_count` | `fn(&self) -> usize` |
+
+**Safety:** Implementors must ensure every `vehicle_data_ptr` points to a valid `ProblemData` for the entire duration of a solve call.
+
+### `MatrixDistanceMeter`
+
+Cross-entity distance meter backed by the solution's distance matrix. Implements `CrossEntityDistanceMeter<S: VrpSolution>`. `#[derive(Clone, Default)]`.
+
+### `MatrixIntraDistanceMeter`
+
+Intra-entity distance meter backed by the solution's distance matrix. Implements `CrossEntityDistanceMeter<S: VrpSolution>`. `#[derive(Clone, Default)]`.
+
+## Free Functions
+
+All functions are generic over `S: VrpSolution`.
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `distance` | `fn<S: VrpSolution>(plan: &S, i: usize, j: usize) -> i64` | Distance between two element indices via the first vehicle's data pointer |
+| `depot_for_entity` | `fn<S: VrpSolution>(plan: &S, _entity_idx: usize) -> usize` | Depot index (same for all vehicles) |
+| `depot_for_cw` | `fn<S: VrpSolution>(plan: &S) -> usize` | Depot index for Clarke-Wright (plan-level) |
+| `element_load` | `fn<S: VrpSolution>(plan: &S, elem: usize) -> i64` | Demand for a single customer element |
+| `capacity` | `fn<S: VrpSolution>(plan: &S) -> i64` | Vehicle capacity |
+| `assign_route` | `fn<S: VrpSolution>(plan: &mut S, entity_idx: usize, route: Vec<usize>)` | Assign a constructed route to a vehicle |
+| `get_route` | `fn<S: VrpSolution>(plan: &S, entity_idx: usize) -> Vec<usize>` | Current route for an entity |
+| `set_route` | `fn<S: VrpSolution>(plan: &mut S, entity_idx: usize, route: Vec<usize>)` | Replace current route for an entity |
+| `is_time_feasible` | `fn<S: VrpSolution>(plan: &S, route: &[usize]) -> bool` | True if route satisfies all time-window constraints |
+| `is_kopt_feasible` | `fn<S: VrpSolution>(plan: &S, _entity_idx: usize, route: &[usize]) -> bool` | K-opt feasibility gate; `entity_idx` ignored, delegates to `is_time_feasible` |
+
+### Usage as macro attribute fn pointers
+
+```rust
+#[shadow_variable_updates(
+    merge_feasible_fn = "solverforge_cvrp_lib::is_time_feasible",
+    cw_depot_fn       = "solverforge_cvrp_lib::depot_for_cw",
+    cw_distance_fn    = "solverforge_cvrp_lib::distance",
+    cw_element_load_fn= "solverforge_cvrp_lib::element_load",
+    cw_capacity_fn    = "solverforge_cvrp_lib::capacity",
+    cw_assign_route_fn= "solverforge_cvrp_lib::assign_route",
+    k_opt_get_route   = "solverforge_cvrp_lib::get_route",
+    k_opt_set_route   = "solverforge_cvrp_lib::set_route",
+    k_opt_depot_fn    = "solverforge_cvrp_lib::depot_for_entity",
+    k_opt_distance_fn = "solverforge_cvrp_lib::distance",
+    k_opt_feasible_fn = "solverforge_cvrp_lib::is_kopt_feasible",
+    // ...
+)]
+```