Refactor/validation hierarchy (#157)

* refactor(validation): reduce public validation API to canonical layer methods

- Make focused invariant validators internal; keep only `is_valid`/`validate` as the public entry points (plus `DelaunayTriangulation::validation_report` for cumulative diagnostics).
- Update docs/README and examples/benches to reflect the 4-level validation hierarchy and correct per-layer semantics.
- Adjust tests/proptests/benches to validate at the appropriate layer (e.g., Level 1–2 during bootstrap, Level 1–3 for topology) and avoid deprecated helpers.
- Fix commit-check/clippy issues (missing `# Errors` docs, similar-name locals, deprecated `is_delaunay`, private API usage in benches).

* refactor: split validation errors by layer (TDS/topology/Delaunay)

- Rename TDS validation error to `TdsValidationError` and update call sites across core/geometry
- Introduce topology-layer `TriangulationValidationError` with structured manifold + Euler variants
- Add `DelaunayTriangulationValidationError` and update `DelaunayTriangulation::{is_valid, validate}` signatures
- Update insertion/boundary/facet plumbing to use the correct layer error types
- Fix rustdoc links and cspell/markdownlint fallout from the refactor

* refactor: layer construction errors (TDS/Triangulation/Delaunay)

- Introduce layered construction errors: TdsConstructionError, TriangulationConstructionError, DelaunayTriangulationConstructionError
- Update DelaunayTriangulation constructors and insertion plumbing to propagate layered errors consistently
- Fix geometry helpers/tests to match wrapped construction error variants
- Refresh docs to match current validation hierarchy + error layering; mark superseded topology integration notes as historical

* Changed: Refactors validation error hierarchy internally

Consolidates and standardizes the validation error types
within the triangulation data structure (TDS) to improve
internal error handling and consistency. Replaces
`TriangulationValidationError` with `TdsValidationError`
where appropriate, streamlining the error reporting
across the library. Updates error propagation to maintain
semantic accuracy.

Refs: refactor/validation-hierarchy

* refactor: clarify validation hierarchy and expand core test coverage

- Make validation layering explicit (elements → TDS structure → topology) and expose a cumulative validation_report API
- Preserve underlying layer errors in TriangulationValidationReport; update docs/examples accordingly
- Add deterministic unit tests covering core error branches (Cell/TDS/util/incremental insertion), incl. overflow, missing keys, non-manifold cases, and serde failures
- Clarify facet-cache error semantics and plumb source errors through convex-hull boundary facet extraction

* Fixed: Improve TDS validation and Delaunay error handling

Improves triangulation data structure (TDS) validation by adding a
check for missing vertex keys in cells, preventing inconsistent state
and improving error diagnostics.

Enhances Delaunay validation to include cell keys in error messages,
aiding debugging.

These changes improve the overall robustness and diagnosability of
the triangulation process.

* Changed: Refactors triangulation validation for clarity

Refactors triangulation validation in `DelaunayTriangulation`
to improve clarity and correctness. It streamlines the
validation process, reusing the lower-layer report more
effectively and ensuring that Delaunay property violations
are handled correctly.

The `TdsValidationError` enum is also updated and a
`TdsMutationError` alias is created to provide clearer
semantics for mutation operations.

A deprecated function `is_delaunay` is updated to reference
`DelaunayTriangulation::is_valid()` and
`DelaunayTriangulation::validate()` methods.

Finally, the 3D insertion order robustness property test is
specialized to avoid nearly-coplanar tetrahedra and
co-spherical 5-tuples, focusing on pure insertion-order
robustness.

* Fixed: Correctly classify cavity boundary facets

Classifies cavity boundary facets by facet incidence within the
conflict region, ensuring accurate boundary detection during
incremental updates.

This avoids misclassification due to temporarily incomplete neighbor
pointers, preventing internal boundary components and Euler/topology
validation failures.

Also adds debug-only safety net to retry cavity-based insertions
with a conservative fallback (star-split) if Level 3 topology
validation fails. This ensures robust handling of degenerate cases
during incremental Delaunay triangulation construction.
Refs: refactor/validation-hierarchy

* Changed: Improves robustness of triangulation insertion

Enhances triangulation insertion robustness by adding
connectedness validation and preventing empty conflict
regions. It also introduces star-split fallback for
topology preservation and refactors boundary handling.
These changes ensure a more reliable triangulation
process.

* Changed: Refactors TDS validation and mutation errors

Refactors the `TdsValidationError` and `TdsMutationError` types to
improve clarity and future extensibility. Introduces a wrapper
struct for `TdsMutationError` to allow for independent evolution
while maintaining API compatibility. Also improves the error
handling during triangulation construction and modification.

Refs: refactor/validation-hierarchy

* perf: Adjust global validation checks

Now that we have a validation hierarchy, we want to run expensive global checks, which are often O(N*D^2), only when we have a suspicion that something has gone wrong. Like CGAL, we want to rely on local checks and only call is_valid() when necessary. So, introduce a ValidationPolicy with SuspicionFlags. Then we only call expensive checks when insertions wander off the happy path, or if the caller decides they want different guarantees (e.g. Never, Always, DebugOnly).

Also fix a bunch of other fixes related to code reviews.

* Fixed: Addresses potential triangulation validation failures

Fixes edge cases in triangulation validation and error handling,
particularly around star-split fallback scenarios. Improves
robustness by refining error messages and ensuring consistent
behavior across debug and release builds. Also fixes a potential
issue with duplicate points in triangulation.

Refs: refactor/validation-hierarchy

* Changed: Enhances topology validation and repair

Refactors topology validation to include connectedness checks
and provides more robust error reporting. Introduces automatic
validation policies for incremental insertions, balancing
performance and safety. Improves neighbor pointer repair
logic and adds validation against neighbor cycles.

These changes aim to improve the reliability of the triangulation
process by ensuring a valid topology and reducing the likelihood
of disconnected components and non-manifold facets.
(Internal change: improves validation and repair logic)

* Refactor: Improves triangulation validation and error reporting

Refactors triangulation validation by restructuring the error
hierarchy to avoid circular dependencies between TDS and
Triangulation validation errors.

This change also improves the documentation around the
validation levels and their performance implications, providing
better guidance for users.

Internally, the `remove_cells_by_keys` method in `Tds` is
enhanced to incrementally repair `incident_cell` pointers and
neighbor references, optimizing vertex removal operations. This
avoids global rebuilds.

Refs: refactor/validation-hierarchy

* Changed: Enhances triangulation validation and testing

Updates the triangulation validation process to use the
`validate()` method, providing more comprehensive checks
(Levels 1-4).

Also improves proptest to avoid pathological cases with
duplicate coordinates or points on a coordinate hyperplane,
leading to more robust and reliable tests. (Internal)

Refs: refactor/validation-hierarchy

* Removed: Deprecates global facet sharing fix

Removes the deprecated `fix_invalid_facet_sharing` methods from both
`DelaunayTriangulation` and `Triangulation`.

These methods performed a global O(N·D) scan and have been superseded
by the more efficient localized O(k·D)
`detect_local_facet_issues` + `repair_local_facet_issues` flow.

This change encourages the use of the localized repair approach, which
is more performant for incremental updates to the triangulation.

* Changed: Improves error reporting with cell UUIDs

Enhances error reporting in Delaunay triangulation validation by
including cell UUIDs in error messages. This allows for better
debugging and log correlation when issues arise during
validation. Introduces a helper function to avoid repetition.

Refs: refactor/validation-hierarchy

* Changed: Removes unused imports in tests (internal)

Removes unused imports from several test modules to improve
code cleanliness and reduce potential confusion. This change
is internal and does not affect the functionality of the code.

Refs: refactor/validation-hierarchy

Author: acgetchell

Cargo.lock

@@ -18,7 +18,7 @@ readme = "README.md"
 [dependencies]
 allocation-counter = { version = "0.8.1", optional = true }  # for memory profiling
 anyhow = "1.0.100"
-arc-swap = "1.7.1"
+arc-swap = "1.8.0"
 approx = "0.5.1"
 clap = { version = "4.5.53", features = ["derive"] }
 derive_builder = "0.20.2"
@@ -29,15 +29,15 @@ num-traits = "0.2.19"
 ordered-float = { version = "5.1.0", features = ["serde"] }
 rand = "0.9.2"
 serde = { version = "1.0.228", features = ["derive"] }
-serde_json = "1.0.145"
+serde_json = "1.0.147"
 serde_test = "1.0.177"
 slotmap = { version = "1.1.1", features = ["serde"] }
 thiserror = "2.0.17"
 uuid = { version = "1.19.0", features = ["v4", "serde"] }
 
 [dev-dependencies]
 criterion = { version = "0.8.1", features = ["html_reports"] }
-pastey = "0.2.0"
+pastey = "0.2.1"
 proptest = "1.9.0"
 sysinfo = "0.37.2"  # Process memory monitoring for benchmarks
 

Cargo.toml

@@ -54,13 +54,14 @@ For details, see: [Issue #120 Investigation](docs/issue_120_investigation.md)
 **Validation**: You can verify your triangulation meets your requirements using the library's
 [4-level validation hierarchy](docs/validation.md):
 
-- **Level 2** (`dt.is_valid()`) - Structural correctness (expected to pass when using public APIs; not affected by Issue #120)
-- **Level 3** (`dt.triangulation().validate_manifold()`) - Manifold topology + Euler characteristic
-- **Level 4** (`dt.validate_delaunay()`) - Delaunay property (may fail in rare cases per Issue #120)
+- **Level 2** (`dt.tds().is_valid()`) - Structural correctness (expected to pass when using public APIs; not affected by Issue #120)
+- **Level 3** (`dt.triangulation().is_valid()`) - Manifold topology + Euler characteristic
+- **Level 4** (`dt.is_valid()`) - Delaunay property only (may fail in rare cases per Issue #120)
+- **All levels (1–4)** (`dt.validate()`) - Elements + structure + topology + Delaunay property
 
 For applications requiring strict Delaunay guarantees:
 
-- Use `validate_delaunay()` to check your specific triangulation
+- Use `dt.is_valid()` (Level 4 only) or `dt.validate()` (Levels 1–4) to check your specific triangulation
 - Use smaller point sets (violations are rarer)
 - Filter degenerate configurations when possible
 - Monitor for updates in future releases

README.md

@@ -7,8 +7,10 @@ Essential guidance for AI assistants working in this repository.
 ### Git Operations
 
 - **NEVER** run `git commit`, `git push`, `git tag`, or any git commands that modify version control state
+- **ALLOWED**: Run read-only git commands (e.g. `git --no-pager status`, `git --no-pager diff`,
+  `git --no-pager log`, `git --no-pager show`, `git --no-pager blame`) to inspect changes/history
 - **ALWAYS** use `git --no-pager` when reading git output
-- Suggest git commands for the user but never execute them
+- Suggest git commands that modify version control state for the user to run manually
 
 ### Commit Messages
 

WARP.md

@@ -246,26 +246,16 @@ fn bench_validation<const D: usize>(c: &mut Criterion, dimension_name: &str, n_p
         .expect("Failed to generate points");
     let vertices: Vec<_> = points.into_iter().map(|p| vertex!(p)).collect();
     let dt = DelaunayTriangulation::new(&vertices).expect("Failed to create triangulation");
-    let tds = dt.tds();
+    let tri = dt.triangulation();
 
     // Throughput in terms of cells we actually validate
-    group.throughput(Throughput::Elements(tds.number_of_cells() as u64));
-
-    // Collect cell keys once to avoid re-enumeration overhead in the hot loop
-    let cell_keys: Vec<_> = tds.cell_keys().collect();
+    group.throughput(Throughput::Elements(tri.number_of_cells() as u64));
 
     group.bench_function("validate_topology", |b| {
         b.iter(|| {
-            // Measure validation time for all cells
-            let mut all_valid = true;
-            for &cell_key in &cell_keys {
-                let neighbors = tds.find_neighbors_by_key(cell_key);
-                if let Err(e) = tds.validate_neighbor_topology(cell_key, &neighbors) {
-                    all_valid = false;
-                    black_box(e);
-                }
-            }
-            black_box(all_valid)
+            // Level 3 topology check (manifold-with-boundary + Euler characteristic)
+            tri.is_valid()
+                .expect("triangulation should be structurally valid during validation benchmark");
         });
     });
 

benches/large_scale_performance.rs

@@ -4,10 +4,9 @@
 //! in the delaunay triangulation library, particularly those that are performance-critical:
 //!
 //! 1. **`DelaunayTriangulation::with_kernel`**: Complete triangulation creation
-//! 2. **`is_valid`**: Complete triangulation validation performance
-//! 3. **Individual validation components**: Mapping validation, duplicate detection, etc.
-//! 4. **Incremental construction**: Performance of `insert()` method for vertex insertion
-//! 5. **Memory usage patterns**: Allocation and deallocation patterns
+//! 2. **Layered validation**: `dt.tds().is_valid()/validate()`, `dt.triangulation().is_valid()/validate()`, `dt.is_valid()`, `dt.validate()`
+//! 3. **Incremental construction**: Performance of `insert()` method for vertex insertion
+//! 4. **Memory usage patterns**: Allocation and deallocation patterns
 //!
 //! These benchmarks measure the effectiveness of the optimization implementations
 //! completed as part of the Pure Incremental Delaunay Triangulation refactoring project.
@@ -143,7 +142,26 @@ macro_rules! generate_validation_benchmarks {
                     group.throughput(Throughput::Elements(throughput));
 
                     group.bench_with_input(
-                        BenchmarkId::new("is_valid", n_points),
+                        BenchmarkId::new("validate", n_points),
+                        &n_points,
+                        |b, &n_points| {
+                            b.iter_batched(
+                                || {
+                                    let points: Vec<Point<f64, $dim>> = generate_random_points_seeded(n_points, (-100.0, 100.0), seed).unwrap();
+                                    let vertices: Vec<_> = points.iter().map(|p| vertex!(*p)).collect();
+                                    DelaunayTriangulation::<RobustKernel<f64>, (), (), $dim>::with_kernel(RobustKernel::new(), &vertices).unwrap()
+                                },
+                                |dt| {
+                                    dt.validate().unwrap();
+                                    black_box(dt);
+                                },
+                                BatchSize::LargeInput,
+                            );
+                        },
+                    );
+
+                    group.bench_with_input(
+                        BenchmarkId::new("is_valid_delaunay", n_points),
                         &n_points,
                         |b, &n_points| {
                             b.iter_batched(
@@ -175,24 +193,37 @@ macro_rules! generate_validation_benchmarks {
 
                 let mut group = c.benchmark_group(&format!("validation_components_{}d", $dim));
 
-                group.bench_function("validate_vertex_mappings", |b| {
+                group.bench_function("tds_is_valid", |b| {
+                    b.iter(|| {
+                        dt.tds().is_valid().unwrap();
+                        // Black box to prevent dead code elimination
+                        black_box(());
+                    });
+                });
+
+                group.bench_function("tri_is_valid", |b| {
                     b.iter(|| {
-                        dt.validate_vertex_mappings().unwrap();
+                        dt.triangulation().is_valid().unwrap();
                         // Black box to prevent dead code elimination
                         black_box(());
                     });
                 });
 
-                group.bench_function("validate_cell_mappings", |b| {
+                group.bench_function("is_valid_delaunay", |b| {
                     b.iter(|| {
-                        dt.validate_cell_mappings().unwrap();
+                        dt.is_valid().unwrap();
                         // Black box to prevent dead code elimination
                         black_box(());
                     });
                 });
 
-                // Note: validate_no_duplicate_cells and validate_facet_sharing are private methods
-                // They are tested indirectly through the full is_valid() benchmark
+                group.bench_function("validate", |b| {
+                    b.iter(|| {
+                        dt.validate().unwrap();
+                        // Black box to prevent dead code elimination
+                        black_box(());
+                    });
+                });
 
                 group.finish();
             }

benches/microbenchmarks.rs

@@ -96,6 +96,7 @@
     "RLENGTH",
     "RSTART",
     "RUSTDOCFLAGS",
+    "RUSTFLAGS",
     "Roundtable",
     "Ryzen",
     "SBATCH",
@@ -362,6 +363,7 @@
     "startswith",
     "stdlib",
     "strsim",
+    "stringifying",
     "subnormals",
     "supercell",
     "supercells",

cspell.json

@@ -86,8 +86,8 @@ Eliminate UUID→Key lookups in hot paths by implementing direct key-based opera
 
 ```rust
 // New key-based helper method
-fn get_cell_vertex_keys(&self, cell_key: CellKey) 
-    -> Result<VertexKeyBuffer, TriangulationValidationError>
+fn get_cell_vertices(&self, cell_key: CellKey)
+    -> Result<VertexKeyBuffer, TdsValidationError>
 ```
 
 #### Key-Based Methods Added
@@ -106,7 +106,7 @@ contains_vertex_key() / vertex_keys()
 find_neighbors_by_key()      // #[must_use]
 set_neighbors_by_key()       // No panics, proper error handling
 find_cells_containing_vertex_by_key()  // #[must_use]
-get_cell_vertex_keys()
+get_cell_vertices()
 ```
 
 #### Zero-Allocation Iterator Optimization
@@ -120,7 +120,7 @@ vertex_uuid_iter() -> impl ExactSizeIterator<Item = Uuid>
 
 #### Algorithms Optimized
 
-- `assign_neighbors()` - Uses `get_cell_vertex_keys()`
+- `assign_neighbors()` - Uses `get_cell_vertices()`
 - `assign_incident_cells()` - Direct key operations
 - `remove_duplicate_cells()` - Key-based duplicate detection
 - `build_facet_to_cells_map_lenient()` - Optimized with keys (deprecated lenient version)

docs/OPTIMIZATION_ROADMAP.md

@@ -157,7 +157,7 @@ match insertion_result {
         // Retryable via perturbation
     }
     Err(InsertionError::ConflictRegion(e)) => {
-        // Duplicate boundary facets or ridge fans - also retryable
+        // Non-manifold facets or ridge fans - also retryable
     }
     Err(e) if e.is_retryable() => {
         // Automatic retry with perturbation
@@ -229,8 +229,8 @@ The `is_retryable()` method classifies errors:
 // Retryable errors (geometric degeneracies)
 - InsertionError::NonManifoldTopology { .. }        // Facet sharing violation
 - InsertionError::Location(CycleDetected { .. })    // Point location cycle
-- InsertionError::ConflictRegion(DuplicateBoundaryFacets { .. })
-- InsertionError::ConflictRegion(RidgeFan { .. })
+- InsertionError::ConflictRegion(NonManifoldFacet { .. })     // Facet shared by >2 conflict cells
+- InsertionError::ConflictRegion(RidgeFan { .. })             // Ridge fan degeneracy
 - InsertionError::TopologyValidation(_)             // Repair failure
 
 // Non-retryable errors (structural failures)
@@ -511,15 +511,19 @@ let dt_robust: DelaunayTriangulation<RobustKernel<f64>, (), (), 3> =
 ```rust
 use delaunay::prelude::*;
 use delaunay::geometry::kernel::{FastKernel, RobustKernel};
-use delaunay::core::triangulation_data_structure::TriangulationConstructionError;
 use delaunay::core::vertex::Vertex;
 
 pub fn create_triangulation_with_fallback(
-    vertices: &[Vertex<f64, (), 3>]
-) -> Result<DelaunayTriangulation<RobustKernel<f64>, (), (), 3>, TriangulationConstructionError> {
+    vertices: &[Vertex<f64, (), 3>],
+) -> Result<
+    DelaunayTriangulation<RobustKernel<f64>, (), (), 3>,
+    DelaunayTriangulationConstructionError,
+> {
     // Strategy 1: Try fast kernel first for performance
-    let fast_result: Result<DelaunayTriangulation<FastKernel<f64>, (), (), 3>, _> =
-        DelaunayTriangulation::new(vertices);
+    let fast_result: Result<
+        DelaunayTriangulation<FastKernel<f64>, (), (), 3>,
+        DelaunayTriangulationConstructionError,
+    > = DelaunayTriangulation::new(vertices);
 
     if fast_result.is_ok() {
         println!("Fast kernel succeeded");
@@ -547,14 +551,14 @@ pub fn create_triangulation_with_fallback(
 
 ```rust
 fn remove_duplicate_and_near_duplicate_points(
-    vertices: &[Vertex<f64, Option<()>, 3>]
-) -> Vec<Vertex<f64, Option<()>, 3>> {
+    vertices: &[Vertex<f64, (), 3>]
+) -> Vec<Vertex<f64, (), 3>> {
     // Simple deduplication based on coordinate proximity
     let mut filtered = Vec::new();
     let tolerance = 1e-10;
 
     for vertex in vertices {
-        let is_duplicate = filtered.iter().any(|existing: &Vertex<f64, Option<()>, 3>| {
+        let is_duplicate = filtered.iter().any(|existing: &Vertex<f64, (), 3>| {
             let existing_coords: [f64; 3] = existing.point().into();
             let vertex_coords: [f64; 3] = vertex.point().into();
 
@@ -681,8 +685,8 @@ The robust predicates system has comprehensive test coverage demonstrating real-
 - Demonstrates consistent results across dimensions (2D-5D)
 - Validates error recovery for "No cavity boundary facets found" scenarios
 - Confirms that structural invariants checked by `Tds::is_valid()` remain intact
-  and can be further inspected via `Tds::validation_report()` and
-  `Tds::validate_delaunay()` in targeted tests.
+  and can be further inspected via `DelaunayTriangulation::validation_report()` and
+  (when needed) `DelaunayTriangulation::is_valid()` / `DelaunayTriangulation::validate()` in targeted tests.
 
 ### Degenerate Case Tests
 

docs/numerical_robustness_guide.md

@@ -7,7 +7,7 @@ This document summarizes the property-based testing infrastructure added to the
 
 For the full set of structural and geometric invariants referenced here, see the
 "Triangulation Invariants" section in the crate-level docs (`src/lib.rs`) and
-`Tds::validation_report()` on `Tds`.
+`DelaunayTriangulation::validation_report()`.
 
 ## Implementation Date