perf: cadence batch repair for large construction

AGENTS.md

@@ -191,6 +191,14 @@ just check
 just ci
 ```
 
+Codex sandbox shells may not include Homebrew on `PATH`. When a validation
+recipe or direct tooling command needs `uv`, prefer:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH just check
+/opt/homebrew/bin/uv run pytest scripts/tests
+```
+
 Refer to `docs/dev/commands.md` for full details.
 
 For tooling-alignment work, update `docs/dev/tooling-alignment.md` with the

CONTRIBUTING.md

@@ -1018,6 +1018,15 @@ PRs are evaluated on:
 - **Style**: Does the code follow project conventions?
 - **Mathematical Accuracy**: Are geometric algorithms correct?
 
+### Non-Substantive Changes
+
+PRs that only introduce whitespace churn, blank-line changes, formatting noise, or other
+non-substantive edits may be declined unless they are part of a clearly justified cleanup or
+required by project tooling.
+
+Accepted contributions should materially improve correctness, numerical robustness, topology
+invariants, performance, documentation clarity, tests, maintainability, or user-facing behavior.
+
 ### Handling Feedback
 
 - **Respond to all comments**: Address each piece of feedback

README.md

@@ -92,13 +92,16 @@ Choose the smallest prelude that matches the task:
 
 | Task | Import |
 |---|---|
-| Build, configure, insert, or remove vertices | `use delaunay::prelude::triangulation::*` |
+| Construct/configure a Delaunay triangulation | `use delaunay::prelude::triangulation::construction::*` |
 | Read-only traversal, adjacency, convex hulls, and comparison helpers | `use delaunay::prelude::query::*` |
 | Points, kernels, predicates, and geometric measures | `use delaunay::prelude::geometry::*` |
 | Random points or triangulations for examples, tests, and benchmarks | `use delaunay::prelude::generators::*` |
+| Low-level incremental insertion building blocks | `use delaunay::prelude::triangulation::insertion::*` |
 | Bistellar flips / Edit API | `use delaunay::prelude::triangulation::flips::*` |
 | Delaunay repair diagnostics and policies | `use delaunay::prelude::triangulation::repair::*` |
 | Delaunayize workflow | `use delaunay::prelude::triangulation::delaunayize::*` |
+| Construction telemetry diagnostics | `use delaunay::prelude::triangulation::diagnostics::*` |
+| Construction validation cadence/policy | `use delaunay::prelude::triangulation::validation::*` |
 | Hilbert ordering and quantization utilities | `use delaunay::prelude::ordering::*` |
 | Low-level TDS cells, facets, keys, and validation reports | `use delaunay::prelude::tds::*` |
 | Collection aliases and small buffers | `use delaunay::prelude::collections::*` |
@@ -107,9 +110,11 @@ Choose the smallest prelude that matches the task:
 
 `use delaunay::prelude::*` remains available for quick experiments, but examples
 and benchmarks in this repository prefer focused preludes so imports document intent.
+The broad `delaunay::prelude::triangulation::*` import is retained for compatibility,
+but new docs and tests should prefer the narrow workflow preludes above.
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 
 // Create a 4D Delaunay triangulation from a set of vertices (uses AdaptiveKernel by default).
 let vertices = vec![
@@ -138,7 +143,9 @@ assert!(dt.is_valid().is_ok());
 For periodic boundary conditions, use `DelaunayTriangulationBuilder`:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulationBuilder, TopologyKind, vertex,
+};
 
 // Phase 1: Canonicalization (wraps coordinates into [0, 1)²)
 let vertices = vec![
@@ -196,7 +203,11 @@ The construction pipeline exposes deterministic controls for experiments and reg
 - Explicit topology/validation configuration via `TopologyGuarantee` and `ValidationPolicy`
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    ConstructionOptions, DedupPolicy, DelaunayTriangulationBuilder, InsertionOrderStrategy,
+    RetryPolicy, TopologyGuarantee, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let vertices = vec![
     vertex!([0.0, 0.0]),

benches/ci_performance_suite.rs

@@ -1,3 +1,5 @@
+#![forbid(unsafe_code)]
+
 //! CI Performance Suite - optimized performance regression testing for CI/CD
 //!
 //! This benchmark is the small, durable performance contract for the delaunay
@@ -36,12 +38,12 @@ use delaunay::prelude::geometry::{
     AdaptiveKernel, Coordinate, Point, RobustKernel, simplex_volume,
 };
 use delaunay::prelude::query::ConvexHull;
+use delaunay::prelude::triangulation::construction::{
+    ConstructionOptions, DelaunayTriangulation, InsertionOrderStrategy, RetryPolicy, Vertex,
+};
 use delaunay::prelude::triangulation::flips::{
     BistellarFlips, CellKey, EdgeKey, FacetHandle, RidgeHandle, TopologyGuarantee, TriangleHandle,
 };
-use delaunay::prelude::triangulation::{
-    ConstructionOptions, DelaunayTriangulation, InsertionOrderStrategy, RetryPolicy, Vertex,
-};
 use delaunay::vertex;
 use std::{env, hint::black_box, num::NonZeroUsize, sync::Once};
 #[cfg(feature = "bench-logging")]

benches/large_scale_performance.rs

@@ -79,7 +79,7 @@
 use criterion::{BatchSize, Criterion, Throughput, criterion_group, criterion_main};
 use delaunay::prelude::generators::generate_random_points_seeded;
 use delaunay::prelude::geometry::AdaptiveKernel;
-use delaunay::prelude::triangulation::{
+use delaunay::prelude::triangulation::construction::{
     ConstructionOptions, DelaunayTriangulation, RetryPolicy, Vertex,
 };
 use delaunay::vertex;

benches/profiling_suite.rs

@@ -64,7 +64,7 @@ use delaunay::prelude::generators::{
 };
 use delaunay::prelude::geometry::{Coordinate, safe_usize_to_scalar};
 use delaunay::prelude::query::*;
-use delaunay::prelude::triangulation::{
+use delaunay::prelude::triangulation::construction::{
     ConstructionOptions, DelaunayTriangulationBuilder, RetryPolicy,
 };
 use delaunay::vertex;

benches/topology_guarantee_construction.rs

@@ -1,3 +1,5 @@
+#![forbid(unsafe_code)]
+
 //! Benchmark: construction cost vs topology guarantee (2D–5D)
 //!
 //! This benchmark compares `TopologyGuarantee::Pseudomanifold`, `TopologyGuarantee::PLManifold`
@@ -14,9 +16,9 @@
 
 use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main};
 use delaunay::prelude::generators::generate_random_points_seeded;
-use delaunay::prelude::triangulation::{
-    DelaunayRepairPolicy, DelaunayTriangulation, TopologyGuarantee, ValidationPolicy,
-};
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, TopologyGuarantee};
+use delaunay::prelude::triangulation::repair::DelaunayRepairPolicy;
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 use delaunay::vertex;
 use std::hint::black_box;
 use std::time::Duration;

docs/api_design.md

@@ -60,7 +60,7 @@ The library provides two distinct APIs for different use cases:
 For most use cases, the simple constructor is sufficient:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 
 // Simple construction from vertices (Euclidean space, default options)
 let vertices = vec![
@@ -87,7 +87,7 @@ For advanced configuration (toroidal topology, custom validation policies, etc.)
 use `DelaunayTriangulationBuilder`:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulationBuilder, vertex};
 
 // Toroidal (periodic) triangulation in 2D
 let vertices = vec![
@@ -148,7 +148,7 @@ for topology guarantee and validation policy details.
 The Edit API is exposed through the `BistellarFlips` trait in `prelude::triangulation::flips`:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 use delaunay::prelude::triangulation::flips::*;
 
 // Start with a valid triangulation
@@ -257,7 +257,7 @@ After applying flips, you should:
 You can mix both APIs in the same workflow:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 use delaunay::prelude::triangulation::flips::*;
 
 // 1. Build initial triangulation (Builder API)

docs/code_organization.md

@@ -220,7 +220,10 @@ delaunay/
 │   │   ├── builder.rs
 │   │   ├── delaunay.rs
 │   │   ├── delaunayize.rs
-│   │   └── flips.rs
+│   │   ├── flips.rs
+│   │   ├── locality.rs
+│   │   └── validation.rs
+│   ├── triangulation.rs
 │   └── lib.rs
 ├── tests/
 │   ├── semgrep/
@@ -431,6 +434,12 @@ The `benchmark-utils` CLI provides integrated benchmark workflow functionality,
 - `delaunayize.rs` - End-to-end "repair then delaunayize" workflow (`delaunayize_by_flips`);
   bounded topology repair + flip-based Delaunay repair + optional fallback rebuild
 - `flips.rs` - High-level bistellar flip (Pachner move) trait and supporting public types; delegates to `core::algorithms::flips`
+- `locality.rs` - Local seed/frontier helpers for Hilbert-local construction and repair
+- `validation.rs` - Construction validation cadence and scheduling helpers
+
+**`src/triangulation.rs`** - Public facade for triangulation-facing workflows.
+It keeps the module namespace stable while the implementation is split across
+orthogonal files under `src/triangulation/`.
 
 **`src/topology/`** - Topology analysis and validation:
 

docs/dev/debug_env_vars.md

@@ -129,15 +129,18 @@ and release builds.
 | `DELAUNAY_LARGE_DEBUG_BALL_RADIUS` | **value** | Radius for ball distribution |
 | `DELAUNAY_LARGE_DEBUG_BOX_HALF_WIDTH` | **value** | Half-width for box distribution |
 | `DELAUNAY_LARGE_DEBUG_CONSTRUCTION_MODE` | **value** | `new` (batch) or `incremental` |
-| `DELAUNAY_LARGE_DEBUG_DEBUG_MODE` | **value** | `cadenced` or `strict` |
+| `DELAUNAY_LARGE_DEBUG_INITIAL_SIMPLEX` | **value** | Batch initial simplex strategy: `max-volume` (default), `balanced`, or `first` |
+| `DELAUNAY_LARGE_DEBUG_DEBUG_MODE` | **value** | `cadenced` (ridge-link) or `strict` (per-insertion vertex-link) |
 | `DELAUNAY_LARGE_DEBUG_SHUFFLE_SEED` | **value** | Vertex shuffle seed |
 | `DELAUNAY_LARGE_DEBUG_PROGRESS_EVERY` | **value** | Progress logging interval |
 | `DELAUNAY_LARGE_DEBUG_VALIDATE_EVERY` | **value** | Validation interval |
-| `DELAUNAY_LARGE_DEBUG_REPAIR_EVERY` | **value** | Repair interval |
+| `DELAUNAY_LARGE_DEBUG_REPAIR_EVERY` | **value** | Batch/incremental repair interval (default: 1) |
 | `DELAUNAY_LARGE_DEBUG_REPAIR_MAX_FLIPS` | **value** | Flip budget override |
 | `DELAUNAY_LARGE_DEBUG_MAX_RUNTIME_SECS` | **value** | Timeout (0 = no cap) |
-| `DELAUNAY_LARGE_DEBUG_ALLOW_SKIPS` | presence | Allow vertex insertion skips |
+| `DELAUNAY_LARGE_DEBUG_MAX_SKIP_PCT` | **value** | Maximum skipped-vertex percentage before failing (default: 5.0) |
+| `DELAUNAY_LARGE_DEBUG_ALLOW_SKIPS` | presence | Allow any number of vertex insertion skips |
 | `DELAUNAY_LARGE_DEBUG_SKIP_FINAL_REPAIR` | presence | Skip final global repair pass |
+| `DELAUNAY_BATCH_REPAIR_TRACE` | presence | Trace cadenced batch-repair seed counts, flips, queues, and elapsed time |
 | `DELAUNAY_LARGE_DEBUG_PREFIX_TOTAL` | **value** | Total prefix probes for bisect mode |
 | `DELAUNAY_LARGE_DEBUG_PREFIX_MAX_PROBES` | **value** | Max probes per bisect run |
 | `DELAUNAY_LARGE_DEBUG_PREFIX_MAX_RUNTIME_SECS` | **value** | Bisect probe timeout |

docs/dev/rust.md

@@ -563,9 +563,12 @@ Examples:
 
 ```text
 delaunay::prelude::triangulation
+delaunay::prelude::triangulation::construction
 delaunay::prelude::triangulation::flips
+delaunay::prelude::triangulation::insertion
 delaunay::prelude::triangulation::repair
 delaunay::prelude::triangulation::delaunayize
+delaunay::prelude::triangulation::validation
 delaunay::prelude::query
 delaunay::prelude::algorithms
 delaunay::prelude::geometry
@@ -600,7 +603,7 @@ Example:
 /// # Examples
 ///
 /// ```rust
-/// # use delaunay::prelude::triangulation::*;
+/// # use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
 /// let mut triangulation = DelaunayTriangulation::<_, _, _, 2>::default();
 /// let key = triangulation.insert_vertex([0.0, 0.0])?;

docs/diagnostics.md

@@ -43,7 +43,7 @@ Use `delaunay_violation_report` when you want data instead of only log output:
 
 ```rust
 use delaunay::prelude::diagnostics::delaunay_violation_report;
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 
 let vertices = vec![
     vertex!([0.0, 0.0, 0.0]),

docs/invariants.md

@@ -245,9 +245,11 @@ identifying *visible* boundary facets and retriangulating the visible region.
 
 ### Degenerate input and initial simplex construction
 
-Construction begins by creating an initial simplex from the first `D+1` affinely independent
-vertices. If no non-degenerate simplex can be formed (e.g., collinear points in 2D, coplanar in 3D),
-construction fails with a geometric degeneracy error.
+Construction begins by creating an initial simplex from `D+1` affinely independent real input
+vertices. The default batch constructor searches a bounded pool of extreme vertices for a
+large-volume simplex before falling back to the selected insertion order. If no non-degenerate
+simplex can be formed (e.g., collinear points in 2D, coplanar in 3D), construction fails with a
+geometric degeneracy error.
 
 This early degeneracy detection is intentional: it prevents building a combinatorial structure whose
 geometric interpretation is undefined.

docs/numerical_robustness_guide.md

@@ -88,7 +88,7 @@ The convenience constructors (`DelaunayTriangulation::new()`, `::empty()`, etc.)
 
 ```rust
 use delaunay::prelude::geometry::RobustKernel;
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
 
 let kernel = RobustKernel::<f64>::new();
 
@@ -165,7 +165,8 @@ cases involve cavity/topology failures rather than predicate degeneracies.
 Use `insert_with_statistics()` to observe this behavior:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulation, vertex};
+use delaunay::prelude::triangulation::insertion::InsertionOutcome;
 
 let mut dt: DelaunayTriangulation<_, (), (), 3> = DelaunayTriangulation::empty();
 
@@ -319,10 +320,12 @@ and per-insertion checks handle any remaining cases.
   This handles near-degenerate configurations correctly out of the box.
 - If you need explicit `BOUNDARY`/`DEGENERATE` signals (e.g. to detect and handle cospherical
   configurations yourself), switch to `RobustKernel`.
-- If you use `FastKernel` for 2D performance, consider setting
-  `DelaunayRepairPolicy::EveryN(n)` (e.g. `n = 10`) instead of the default `EveryInsertion`.
-  This reduces the frequency of the automatic robust-fallback repair pass while still
-  maintaining the Delaunay property periodically. Note that the explicit repair methods
+- If you use `FastKernel` for direct incremental insertion, consider setting
+  `DelaunayRepairPolicy::EveryN(n)` (e.g. `n = 10`) instead of the incremental default
+  `EveryInsertion`. Batch construction already uses a cadenced `ConstructionOptions`
+  repair default with final repair/validation. This reduces the frequency of the automatic
+  robust-fallback repair pass while still maintaining the Delaunay property periodically.
+  Note that the explicit repair methods
   (`repair_delaunay_with_flips`, etc.) are not available with `FastKernel` — use
   `AdaptiveKernel` or `RobustKernel` if you need manual repair control.
 - If you see retryable insertion errors, frequent perturbation retries, or skipped vertices,

docs/topology.md

@@ -177,7 +177,7 @@ Toroidal (periodic) triangulations are **fully implemented and functional**. You
 construct toroidal triangulations using `DelaunayTriangulationBuilder`:
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{DelaunayTriangulationBuilder, vertex};
 
 // 2D periodic triangulation
 let vertices = vec![

docs/validation.md

@@ -79,7 +79,10 @@ insertion deviates from the happy-path and trips internal **suspicion flags**, e
 ### Example: configuring validation policy
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulation, TopologyGuarantee, Vertex, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let vertices = vec![
     vertex!([0.0, 0.0, 0.0]),
@@ -121,7 +124,10 @@ PL-manifoldness. You can trigger that final certification via
 `Triangulation::validate_at_completion()` (or `Triangulation::validate()`).
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulation, TopologyGuarantee, Vertex, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let vertices = vec![
     vertex!([0.0, 0.0, 0.0]),
@@ -210,7 +216,10 @@ Validates basic data integrity of individual vertices and cells.
 ### Example
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulation, TopologyGuarantee, Vertex, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let v = vertex!([0.0, 0.0, 0.0]);
 assert!(v.is_valid().is_ok());
@@ -263,7 +272,10 @@ Validates the combinatorial structure of the Triangulation Data Structure.
 ### Example
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulation, TopologyGuarantee, Vertex, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let vertices = vec![
     vertex!([0.0, 0.0, 0.0]),
@@ -341,7 +353,10 @@ Validates that the triangulation forms a valid topological manifold.
 ### Example
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulation, TopologyGuarantee, Vertex, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let vertices = vec![
     vertex!([0.0, 0.0, 0.0]),
@@ -404,7 +419,10 @@ Validates the geometric optimality of the triangulation.
 ### Example
 
 ```rust
-use delaunay::prelude::triangulation::*;
+use delaunay::prelude::triangulation::construction::{
+    DelaunayTriangulation, TopologyGuarantee, Vertex, vertex,
+};
+use delaunay::prelude::triangulation::validation::ValidationPolicy;
 
 let vertices = vec![
     vertex!([0.0, 0.0, 0.0]),