fix(mincut): report exact results and qualify release claims

crates/ruvector-mincut/Cargo.toml

@@ -7,7 +7,7 @@ license.workspace = true
 authors.workspace = true
 repository.workspace = true
 readme = "README.md"
-description = "World's first subpolynomial dynamic min-cut: self-healing networks, AI optimization, real-time graph analysis"
+description = "Dynamic global minimum cut with an exact sparse Stoer-Wagner baseline and experimental graph algorithms"
 keywords = ["graph", "minimum-cut", "network-analysis", "self-healing", "dynamic-graph"]
 categories = ["algorithms", "data-structures", "science", "mathematics", "simulation"]
 homepage = "https://ruv.io"
@@ -44,7 +44,7 @@ mockall = { workspace = true }
 default = ["exact", "approximate"]
 full = ["exact", "approximate", "integration", "monitoring", "simd", "agentic", "jtree", "tiered", "canonical"]
 exact = []  # Exact minimum cut algorithm
-approximate = []  # (1+ε)-approximate algorithm
+approximate = []  # Legacy compatibility flag; ApproxMinCut is currently always compiled
 integration = ["ruvector-graph"]  # GraphDB integration
 monitoring = []  # Real-time monitoring with callbacks
 simd = ["ruvector-core/simd"]

crates/ruvector-mincut/docs/ALGORITHMS.md

@@ -1,5 +1,9 @@
 # Algorithm Documentation
 
+> Research design document. Complexity targets below describe algorithms in
+> the cited literature; they are not proven guarantees of this crate's
+> `DynamicMinCut`, which currently uses sparse exact Stoer-Wagner recomputation.
+
 This document provides detailed explanations of the algorithms implemented in `ruvector-mincut`, including mathematical foundations, pseudocode, complexity proofs, and implementation notes.
 
 ## Table of Contents

crates/ruvector-mincut/docs/BENCHMARK_REPORT.md

@@ -1,5 +1,10 @@
 # RuVector MinCut - Performance Benchmark Report
 
+> Historical measurements from December 2025. They have not been reproduced
+> against the current release, are not general complexity bounds, and should
+> not be used as release-qualified performance claims. Current `DynamicMinCut`
+> may rerun a polynomial-time exact solver after updates.
+
 **Date**: December 2025
 **Version**: 0.2.0
 **Environment**: Linux, Rust 1.70+, Release build
@@ -14,8 +19,8 @@ This report documents the performance characteristics of the ruvector-mincut cra
 
 | Algorithm | Operation | Time (1000 vertices) | Complexity |
 |-----------|-----------|---------------------|------------|
-| **DynamicMinCut** | Insert Edge | 56.6 µs | O(n^{o(1)}) amortized |
-| **DynamicMinCut** | Delete Edge | 106.2 µs | O(n^{o(1)}) amortized |
+| **DynamicMinCut** | Insert Edge | 56.6 µs | Not established; may recompute exactly |
+| **DynamicMinCut** | Delete Edge | 106.2 µs | Not established; may recompute exactly |
 | **PolylogConnectivity** | Insert Edge | 1.66 ms | O(log³ n) expected worst-case |
 | **PolylogConnectivity** | Delete Edge | 519 ms | O(log³ n) expected worst-case |
 | **PolylogConnectivity** | Query | 16.1 µs | O(log n) worst-case |
@@ -26,7 +31,7 @@ This report documents the performance characteristics of the ruvector-mincut cra
 
 ## Detailed Benchmark Results
 
-### 1. Core DynamicMinCut (December 2025 Paper)
+### 1. Core DynamicMinCut (Historical Measurement)
 
 **Insert Edge Performance**
 | Graph Size | Time | Throughput |
@@ -42,7 +47,7 @@ This report documents the performance characteristics of the ruvector-mincut cra
 |------------|------|-------|
 | 100 vertices | 18.4 µs | Includes replacement search |
 | 500 vertices | 56.5 µs | Tree rebuild on tree edge delete |
-| 1,000 vertices | 106 µs | O(n^{o(1)}) amortized |
+| 1,000 vertices | 106 µs | No amortized bound established here |
 
 ### 2. PolylogConnectivity (arXiv:2510.08297)
 

crates/ruvector-mincut/docs/PAPER_IMPLEMENTATION.md

@@ -1,8 +1,14 @@
 # Paper Implementation Status
 
+> Historical component inventory. The presence of these modules and small-graph
+> tests does not establish a complete implementation or complexity proof for
+> arXiv:2512.13105. `DynamicMinCut` currently uses sparse exact Stoer-Wagner
+> recomputation. The coverage percentages below have not been reverified for
+> this release.
+
 ## Reference
 El Hayek, Henzinger, Li. "Deterministic and Exact Fully Dynamic Minimum Cut
-of Superpolylogarithmic Size in Subpolynomial Time." arXiv:2512.13105, December 2024.
+of Superpolylogarithmic Size in Subpolynomial Time." arXiv:2512.13105, December 2025.
 
 ## Implementation Status
 

crates/ruvector-mincut/docs/guide/01-getting-started.md

@@ -108,15 +108,15 @@ RuVector MinCut has several optional features you can enable based on your needs
 
 ```toml
 [dependencies]
-ruvector-mincut = { version = "0.2", features = ["monitoring", "simd"] }
+ruvector-mincut = { version = "2.3", features = ["monitoring", "simd"] }
 ```
 
 #### Available Features
 
 | Feature | Default | What It Does | When to Use |
 |---------|---------|--------------|-------------|
 | **`exact`** | ✅ Yes | Exact minimum cut algorithm | When you need guaranteed correct results |
-| **`approximate`** | ✅ Yes | Fast (1+ε)-approximate algorithm | When speed matters more than perfect accuracy |
+| **`approximate`** | ✅ Yes | Legacy compatibility flag; does not switch `DynamicMinCut` solvers | Existing manifests only |
 | **`monitoring`** | ❌ No | Real-time event notifications | When you need alerts for cut changes |
 | **`integration`** | ❌ No | GraphDB integration with ruvector-graph | When working with vector databases |
 | **`simd`** | ❌ No | SIMD vector optimizations | For faster processing on modern CPUs |
@@ -321,7 +321,7 @@ mincut.insert_edge(3, 4, 2.0)?;  // Add edge
 mincut.delete_edge(2, 3)?;        // Remove edge
 ```
 
-These operations update the minimum cut in **O(n^{o(1)})** amortized time — much faster than recomputing from scratch!
+These operations update the cached cut. Some changes require a full polynomial-time exact recomputation.
 
 ---
 
@@ -388,89 +388,27 @@ if result.is_exact {
 - Slower for very large graphs
 - Use when correctness is critical
 
-#### Approximate Mode
-- **`is_exact = false`**
-- Returns a cut within `(1+ε)` of the minimum
-- Much faster for large graphs
-- Use when speed matters more than perfect accuracy
+#### Legacy Approximate Option
 
-**Example:** With `ε = 0.1`:
-- If true minimum = 10, approximate returns between 10 and 11
-- Approximation ratio = 1.1 (10% tolerance)
+`MinCutBuilder::approximate(ε)` remains for compatibility, but it does not
+select a different solver. `DynamicMinCut` still computes an exact cut and
+reports `is_exact = true` and `approximation_ratio = 1.0`. The separate
+`ApproxMinCut` research API uses heuristic sparsification without a validated
+all-graph `(1+ε)` guarantee.
 
 ### Performance Characteristics
 
-```rust
-// Query: O(1) - instant!
-let value = mincut.min_cut_value();
-
-// Insert edge: O(n^{o(1)}) - subpolynomial!
-mincut.insert_edge(u, v, weight)?;
-
-// Delete edge: O(n^{o(1)}) - subpolynomial!
-mincut.delete_edge(u, v)?;
-```
-
-**What is O(n^{o(1)})?**
-- Slower than O(1) but faster than O(n), O(log n), etc.
-- Example: O(n^{0.01}) or O(n^{1/log log n})
-- Much better than traditional O(m·n) algorithms
-- Enables real-time updates even for large graphs
+The cached cut value is O(1) to read. An update may preserve the current cut
+or run the sparse Stoer-Wagner exact solver, whose full recomputation is
+polynomial. Measure against your graph family before relying on update latency.
 
 ---
 
-## 5. Choosing Between Exact and Approximate
-
-Use this flowchart to decide which mode to use:
-
-```mermaid
-flowchart TD
-    Start{What's your<br/>graph size?} --> Small{Less than<br/>10,000 nodes?}
-
-    Small -->|Yes| UseExact[Use EXACT mode]
-    Small -->|No| Large{More than<br/>1 million nodes?}
-
-    Large -->|Yes| UseApprox[Use APPROXIMATE mode]
-    Large -->|No| CheckAccuracy{Need guaranteed<br/>correctness?}
-
-    CheckAccuracy -->|Yes| UseExact2[Use EXACT mode]
-    CheckAccuracy -->|No| CheckSpeed{Speed is<br/>critical?}
-
-    CheckSpeed -->|Yes| UseApprox2[Use APPROXIMATE mode]
-    CheckSpeed -->|No| UseExact3[Use EXACT mode<br/>as default]
-
-    UseExact --> ExactCode["mincut = MinCutBuilder::new()
-        .exact()
-        .build()?"]
-
-    UseExact2 --> ExactCode
-    UseExact3 --> ExactCode
-
-    UseApprox --> ApproxCode["mincut = MinCutBuilder::new()
-        .approximate(0.1)
-        .build()?"]
-
-    UseApprox2 --> ApproxCode
-
-    style Start fill:#e1f5ff
-    style UseExact fill:#c8e6c9
-    style UseExact2 fill:#c8e6c9
-    style UseExact3 fill:#c8e6c9
-    style UseApprox fill:#fff9c4
-    style UseApprox2 fill:#fff9c4
-    style ExactCode fill:#f0f0f0
-    style ApproxCode fill:#f0f0f0
-```
-
-### Quick Comparison
+## 5. Choosing the Solver
 
-| Aspect | Exact Mode | Approximate Mode |
-|--------|-----------|------------------|
-| **Accuracy** | 100% correct | (1+ε) of optimal |
-| **Speed** | Moderate | Very fast |
-| **Memory** | O(n log n + m) | O(n log n / ε²) |
-| **Best For** | Small-medium graphs | Large graphs |
-| **Update Time** | O(n^{o(1)}) | O(n^{o(1)}) |
+Use `DynamicMinCut` when an exact global cut is required and its update cost is
+acceptable. The legacy `.approximate(ε)` builder option offers no speedup.
+Evaluate the separate `ApproxMinCut` API only as experimental research code.
 
 ### Code Examples
 
@@ -484,16 +422,16 @@ let mut mincut = MinCutBuilder::new()
 assert!(mincut.min_cut().is_exact);
 ```
 
-**Approximate Mode** (10% tolerance):
+**Legacy approximate request** (still exact):
 ```rust
 let mut mincut = MinCutBuilder::new()
-    .approximate(0.1)  // ε = 0.1
+    .approximate(0.1)  // legacy request; does not change the solver
     .with_edges(edges)
     .build()?;
 
 let result = mincut.min_cut();
-assert!(!result.is_exact);
-assert_eq!(result.approximation_ratio, 1.1);
+assert!(result.is_exact);
+assert_eq!(result.approximation_ratio, 1.0);
 ```
 
 ---
@@ -615,9 +553,8 @@ The minimum cut problem connects to many fascinating areas of computer science:
 
 ```rust
 MinCutBuilder::new()
-    .exact()                    // or .approximate(0.1)
+    .exact()                    // exact solver
     .with_edges(edges)          // Initial edges
-    .with_capacity(10000)       // Preallocate capacity
     .build()?                   // Construct
 ```
 
@@ -627,18 +564,18 @@ MinCutBuilder::new()
 mincut.min_cut_value()          // Get cut value (O(1))
 mincut.partition()              // Get partition (O(n))
 mincut.cut_edges()              // Get cut edges (O(m))
-mincut.insert_edge(u, v, w)?    // Add edge (O(n^{o(1)}))
-mincut.delete_edge(u, v)?       // Remove edge (O(n^{o(1)}))
+mincut.insert_edge(u, v, w)?    // Add edge (may recompute)
+mincut.delete_edge(u, v)?       // Remove edge (may recompute)
 ```
 
 ### Result Inspection
 
 ```rust
 let result = mincut.min_cut();
 result.value                    // Cut value
-result.is_exact                 // true if exact mode
-result.approximation_ratio      // 1.0 if exact, >1.0 if approximate
-result.edges                    // Edges in the cut
+result.is_exact                 // true for DynamicMinCut
+result.approximation_ratio      // 1.0 for DynamicMinCut
+result.cut_edges                // Edges in the cut
 result.partition                // (S, T) vertex sets
 ```