Refactor/445 realization validation

.github/workflows/benchmarks.yml

@@ -42,7 +42,7 @@ concurrency:
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
-  UV_VERSION: "0.11.27"
+  UV_VERSION: "0.11.28"
   BENCHMARK_TIMEOUT: 1800 # 30 min; pre-computed seeds + reduced 5D counts keep runtime well under this
   DELAUNAY_BENCH_DISCOVER_SEEDS_LIMIT: 256 # fallback only; ci_performance_suite uses pre-computed seeds
 

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ env:
   RUMDL_VERSION: "0.2.28"
   TAPLO_VERSION: "0.10.0"
   TYPOS_VERSION: "1.48.0"
-  UV_VERSION: "0.11.27"
+  UV_VERSION: "0.11.28"
   ZIZMOR_VERSION: "1.26.1"
 
 jobs:

.github/workflows/generate-baseline.yml

@@ -26,7 +26,7 @@ permissions:
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
-  UV_VERSION: "0.11.27"
+  UV_VERSION: "0.11.28"
   # Seed search limit for both old (pre-v0.8) and current env var names.
   # Old tags read DELAUNAY_BENCH_SEED_SEARCH_LIMIT; current code reads
   # DELAUNAY_BENCH_DISCOVER_SEEDS_LIMIT. Setting both ensures backward

.github/workflows/papers.yml

@@ -52,7 +52,7 @@ env:
   JUST_VERSION: "1.55.1"
   TECTONIC_VERSION: "0.16.9"
   TEX_FMT_VERSION: "0.5.7"
-  UV_VERSION: "0.11.27"
+  UV_VERSION: "0.11.28"
 
 jobs:
   papers:

.github/workflows/release-benchmarks.yml

@@ -19,7 +19,7 @@ concurrency:
 env:
   CARGO_TERM_COLOR: always
   RUST_BACKTRACE: 1
-  UV_VERSION: "0.11.27"
+  UV_VERSION: "0.11.28"
 
 jobs:
   release-baseline:

.github/workflows/semgrep-sarif.yml

@@ -24,7 +24,7 @@ permissions:
   actions: read
 
 env:
-  UV_VERSION: "0.11.27"
+  UV_VERSION: "0.11.28"
 
 jobs:
   semgrep-sarif:

AGENTS.md

@@ -112,7 +112,7 @@ When in doubt, favor the invariant over the convenient edit.
 - Every mutating operation preserves the invariants checked by
   `Tds::is_valid` / `validate` (Levels 1-2),
   `Triangulation::is_valid_topology` / `validate` (Level 3),
-  `Triangulation::is_valid_embedding` / `validate_embedding` (Level 4), and
+  `Triangulation::is_valid_realization` / `validate_realization` (Level 4), and
   `DelaunayTriangulation::is_valid_delaunay` / `validate` (Level 5). An
   operation that cannot preserve them must fail explicitly rather than leave
   inconsistent state behind.
@@ -135,17 +135,20 @@ The library exposes five validation levels, each a superset of the last:
 3. **Level 3 - Intrinsic PL Topology**: the abstract simplicial complex has the
    requested PL topology, including manifold/pseudomanifold conditions, links,
    Euler characteristic, orientability, and connected components.
-4. **Level 4 - Embedding Validity**: the complex is faithfully realized in the
-   chosen ambient model, including Euclidean affine charts, toroidal periodic
-   charts, spherical `S^d` embeddings, and embedding-specific constraints.
-5. **Level 5 - Geometric Predicates**: the embedding satisfies the selected
+4. **Level 4 - Valid Realization**: the complex is realized without geometric
+   degeneracy or unintended intersections in the chosen model, including
+   Euclidean/toroidal affine-chart realization, spherical `S^d` realization,
+   and model-specific realization constraints.
+5. **Level 5 - Geometric Predicates**: the realization satisfies the selected
    geometric predicate family, currently Euclidean/toroidal/spherical Delaunay
    checks and eventually regular, weighted, constrained, Gabriel, alpha, or
    related predicates.
 
-Level 4 uses orientation and exact barycentric geometry for affine-chart
-embedding, with backend-specific realization checks for non-Euclidean models.
-Level 5 uses geometry-specific predicates. Levels 1-3 are embedding-independent
+Level 4 uses orientation and exact barycentric geometry for Euclidean/toroidal
+affine-chart realization, where toroidal checks run in lifted periodic
+covering-space charts, and backend-specific realization checks for curved
+models. Level 5 uses geometry-specific predicates. Levels 1-3 are
+realization-independent
 graph/topology checks. Validation code belongs at the lowest layer that owns the
 invariant.
 Each layer should expose the standard validation surface. Use plain
@@ -155,7 +158,7 @@ multiple validation layers. Use `*_diagnostic` for the first actionable
 repair/retry diagnostic, `*_report` for layer-local aggregate diagnostics, and
 `validate()` / `validation_report()` for cumulative roll-up through the owning
 layer. Report names should identify the layer being checked, e.g.
-`structure_report`, `topology_report`, `embedding_report`, and
+`structure_report`, `topology_report`, `realization_report`, and
 `delaunay_report`. Higher layers should roll lower diagnostics up without
 stringifying them.
 

CITATION.cff

@@ -26,7 +26,7 @@ abstract: >-
   robustness and degeneracy handling, and Hilbert curves for deterministic
   insertion ordering and efficient spatial indexing. Provides an explicit
   5-level validation hierarchy on individual elements, combinatorial
-  consistency, intrinsic PL topology, embedding validity in the active model,
+  consistency, intrinsic PL topology, valid realization in the active model,
   and geometric predicates such as Delaunay.
   Allows for the complete set of Pachner moves up to D=5 using bistellar flips,
   vertex insertion and deletion, and the conversion of non-Delaunay

README.md

@@ -42,7 +42,7 @@ Rust crate providing D-dimensional [Delaunay triangulations] and [convex hulls][
 topologies. Uses [exact predicates] and [Simulation of Simplicity] for robustness and degeneracy
 handling, and [Hilbert curve]s for deterministic insertion ordering and efficient spatial indexing.
 Provides an explicit [5-level validation hierarchy][Validation Guide] on individual elements,
-combinatorial consistency, intrinsic PL topology, embedding validity in the active
+combinatorial consistency, intrinsic PL topology, valid realization in the active
 model, and geometric predicates such as Delaunay. Allows for the complete set of [Pachner moves] up to D=5
 using bistellar flips, vertex insertion and deletion, and the conversion of non-Delaunay
 triangulations into Delaunay triangulations via bounded flip/rebuilds. Auxiliary data may be stored
@@ -54,11 +54,11 @@ Use this crate when you want:
 
 - Delaunay triangulations or convex hulls in 2D through 5D.
 - Exact predicates and deterministic SoS handling for degenerate inputs.
-- Embedding Validity validation for Euclidean and toroidal models independent of Delaunay predicates.
+- Valid-realization checks for Euclidean, toroidal, and spherical models independent of Delaunay predicates.
 - PL-manifold checks and explicit topology guarantees.
 - PL-manifold-aware editing via bistellar flips and bounded Delaunay repair.
 - Typed construction, insertion, validation, topology, and repair diagnostics.
-- Validation reports that separate element, combinatorial, intrinsic topology, embedding, and
+- Validation reports that separate element, combinatorial, intrinsic topology, realization, and
   geometric-predicate failures.
 
 This is not a replacement for full meshing packages such as [CGAL], TetGen, or Gmsh when you need
@@ -93,7 +93,7 @@ meshing, or production-scale dynamic remeshing.
   correctness tests.
 - [x] PL-manifold validation by default, with pseudomanifold checks available as an explicit opt-out.
 - [x] Prototype spherical `S^2`/`S^3` construction through `SphericalDelaunayBuilder`, with
-  Level 3 Intrinsic PL Topology, spherical Level 4 Embedding Validity, and spherical Level 5
+  Level 3 Intrinsic PL Topology, spherical Level 4 realization checks, and spherical Level 5
   empty-cap predicate checks.
 - [x] Safe Rust: `#![forbid(unsafe_code)]`.
 - [x] Serialization/deserialization through [JSON].
@@ -190,18 +190,29 @@ just notebook-clear-outputs-all
 
 ## 🧪 Scientific Basis
 
-The crate models triangulations as oriented simplicial complexes with separate combinatorial and
-geometric checks. Robustness comes from the same layered predicate strategy used throughout the code:
-fast f64 filters when the sign is provable, exact arithmetic fallback when it is not, and deterministic
-SoS resolution for degenerate configurations.
-
-The validation contract is computational and finite-dimensional. The crate checks that constructed or
-edited triangulations satisfy implemented element, combinatorial, intrinsic topology, embedding, and
-geometric-predicate invariants; it does not claim to solve meshing constraints or certify unsupported
-geometric models.
-
-For the detailed contract, see [REFERENCES.md](REFERENCES.md), [`docs/invariants.md`](docs/invariants.md),
-and [`docs/numerical_robustness_guide.md`](docs/numerical_robustness_guide.md).
+The crate treats a finite point-set triangulation as an oriented abstract simplicial complex plus a
+coordinate realization in a supported geometric model. Levels 1-3 certify element validity,
+combinatorial consistency, and intrinsic PL topology without depending on coordinates. Level 4
+certifies geometric validity: every maximal simplex must be nondegenerate and realized simplices may
+intersect only in their shared abstract faces. Level 5
+certifies geometric optimality or predicate satisfaction, currently the Delaunay empty-circumsphere
+property.
+
+Correctness evidence comes from the invariant model, exact predicate fallbacks, deterministic
+Simulation of Simplicity, validation reports, property tests, regression tests, and public examples.
+Performance evidence is separate: Hilbert ordering, allocation-conscious data structures,
+validation-level benchmarks, math-kernel benchmarks, and release-to-release Criterion reports
+characterize cost and observability, but they do not replace correctness checks.
+
+The crate guarantees the implemented finite-dimensional Delaunay, topology, and validation contracts
+for the documented coordinate models and dimensions. It does not replace constrained meshing
+packages, prove arbitrary abstract PL-manifolds realizable from coordinates, or certify unsupported
+spherical/hyperbolic workflows.
+
+For the detailed contract, see [`docs/validation.md`](docs/validation.md),
+[`docs/invariants.md`](docs/invariants.md), [`docs/topology.md`](docs/topology.md),
+[`docs/numerical_robustness_guide.md`](docs/numerical_robustness_guide.md),
+[`docs/limitations.md`](docs/limitations.md), and [`benches/README.md`](benches/README.md).
 
 ## ✅ Validation Model
 
@@ -210,18 +221,19 @@ and [`docs/numerical_robustness_guide.md`](docs/numerical_robustness_guide.md).
 | 1 | Element Validity: vertex, simplex, facet, coordinate, and local-object invariants | `is_valid()` / element reports |
 | 2 | Combinatorial Consistency: TDS incidences, neighbors, and simplex/ridge connectivity | `validate_structure()` / `structure_report()` |
 | 3 | Intrinsic PL Topology: manifold/pseudomanifold links, components, and Euler consistency | `is_valid_topology()` / `topology_report()` |
-| 4 | Embedding Validity: faithful realization in the active Euclidean, toroidal, or spherical model | `is_valid_embedding()` / `embedding_report()` |
-| 5 | Geometric Predicates: Delaunay and future geometry-specific predicate families | `is_valid_delaunay()` / `delaunay_report()` |
+| 4 | Valid Realization: nondegenerate realized simplices with only shared-face intersections | `is_valid_realization()` / `realization_report()` |
+| 5 | Geometric Predicates: Delaunay and future geometry-specific optimality predicates | `is_valid_delaunay()` / `delaunay_report()` |
 | 1-5 | Cumulative diagnostics | `dt.validate()` / `dt.validation_report()` |
 
 `TopologyGuarantee` controls which Level 3 Intrinsic PL Topology invariants are enforced. `ValidationPolicy`
-controls when Level 3 checks run during incremental insertion. Level 4 Embedding Validity is
-backend-specific: Euclidean and toroidal paths validate affine charts, while the spherical prototype
-validates simplices on `S^D \subset R^(D+1)`. Level 5 geometric predicates are likewise
+controls when Level 3 checks run during incremental insertion. Level 4 realization validation is
+backend-specific: Euclidean and toroidal paths validate affine-chart realizations, with toroidal
+checks lifted to periodic covering-space charts, while the spherical prototype validates simplices on
+`S^D \subset R^(D+1)`. Level 5 geometric predicates are likewise
 backend-specific: Euclidean/toroidal Delaunay paths use empty-circumsphere predicates, while the
 spherical prototype uses the empty-cap / ambient-hull-facet predicate. Use
-`dt.as_triangulation().validate_embedding()` when you want
-cumulative Levels 1-4 validation for ordinary triangulations. `dt.as_triangulation().embedding_report()`
+`dt.as_triangulation().validate_realization()` when you want
+cumulative Levels 1-4 validation for ordinary triangulations. `dt.as_triangulation().realization_report()`
 returns simplex keys, simplex UUIDs, and offending vertex keys/UUIDs for Level 4 repair planning. The default is
 PL-manifold topology with explicit full-validation
 checkpoints. Layer-local APIs use `is_valid()` for unambiguous element/TDS owners, `is_valid_*`

REFERENCES.md

@@ -347,12 +347,14 @@ set-based structures (e.g., edge sets) under different construction orders.
   IBM Technical Report, 1958. Often cited for the Tanimoto coefficient (equivalent to the
   Jaccard index for binary vectors).
 
-## Topological Manifolds and PL Topology (Level 3 Validation)
+## Topological Manifolds, Realizations, and PL Topology (Levels 3-4 Validation)
 
-These references support the topology-only manifold / PL-manifold validation logic in this
-library (facet degree, closed-boundary checks, and links of simplices).
+These references support abstract and geometric simplicial complexes, affine/geometric
+realizations, and the topology-only manifold / PL-manifold validation logic in this library
+(facet degree, closed-boundary checks, and links of simplices).
 
-- Edelsbrunner, H., and Harer, J. *Computational Topology*. AMS, 2010.
+- Dey, T. K., and Wang, Y. *Computational Topology for Data Analysis*. Cambridge University Press, 2022.
+- Edelsbrunner, H., and Harer, J. *Computational Topology: An Introduction*. AMS, 2010.
 - Hatcher, A. *Algebraic Topology*. Cambridge University Press, 2002.
   (Appendix A: PL Manifolds and Links.)
 - Munkres, J. R. *Elements of Algebraic Topology*. Addison–Wesley, 1984.
@@ -361,15 +363,16 @@ library (facet degree, closed-boundary checks, and links of simplices).
 - Stillwell, J. *Euler's Gem: The Polyhedron Formula and the Birth of Topology*. Princeton University Press, 2010.
 - Zomorodian, A. *Topology for Computing*. Cambridge University Press, 2005.
 
-## Embedded-Geometry Overlap Detection (Level 4 Validation)
+## Realized-Simplex Overlap Detection (Level 4 Validation)
 
-These references support the embedded-geometry (Level 4) validator, which certifies that maximal
-simplices are nondegenerate and intersect only in their shared faces. Candidate overlapping pairs
-are found with a sweep-and-prune broad phase over axis-aligned bounding boxes before exact rational
-barycentric intersection tests are applied. Two axis-aligned boxes intersect if and only if their
-projections overlap on every coordinate axis (the separating-axis test), and sorting boxes by their
-lower endpoint on one axis while retiring boxes whose upper endpoint precedes the current lower
-endpoint examines a superset of all axis-overlapping pairs, so no intersecting pair is skipped.
+These references support the realized-simplex overlap validator used by Level 4 affine-chart
+realization checks, which certify that maximal simplices are nondegenerate and intersect only in
+their shared faces. Candidate overlapping pairs are found with a sweep-and-prune broad phase over
+axis-aligned bounding boxes before exact rational barycentric intersection tests are applied. Two
+axis-aligned boxes intersect if and only if their projections overlap on every coordinate axis (the
+separating-axis test), and sorting boxes by their lower endpoint on one axis while retiring boxes
+whose upper endpoint precedes the current lower endpoint examines a superset of all axis-overlapping
+pairs, so no intersecting pair is skipped.
 
 - Baraff, D. "Dynamic Simulation of Non-Penetrating Rigid Bodies." PhD thesis, Cornell University, 1992.
   Introduces coordinate sorting ("sort and sweep") for axis-aligned bounding-box overlap detection.

benches/README.md

@@ -288,7 +288,7 @@ cargo bench --profile perf --bench ci_performance_suite
 - convex hull extraction
 - boundary facet traversal
 - cumulative validation Levels 1-5, including Level 1-2 TDS structure, Level 3
-  topology, Level 4 embedding, and Level 5 Delaunay predicate checks
+  topology, Level 4 realization, and Level 5 Delaunay predicate checks
 - incremental vertex insertion into prepared triangulations
 - explicit 2D-5D bistellar flip roundtrips
 
@@ -357,7 +357,7 @@ Use `just bench-pachner-stress*` for Criterion timing evidence. Criterion
 requires at least 10 samples. The benchmark recipe measures stable accepted
 move fixtures and corresponding forward/inverse round trips.
 
-The stress cases validate topology plus the Level 4 embedding invariant that
+The stress cases validate topology plus the Level 4 realization invariant that
 arbitrary Pachner moves are expected to preserve; Level 5 Delaunay validity is
 not a postcondition of arbitrary topology edits. Invalid local candidates are
 counted as candidate misses or proposal rejections, while successfully planned

benches/common/flip_fixtures.rs

@@ -191,7 +191,7 @@ pub const ADVERSARIAL_POINTS_5D: &[[f64; 5]] = &[
 /// Intentionally invalid 3D fixture used to prove benchmark setup rejects
 /// degenerate inputs instead of silently sanitizing them.
 ///
-/// All points are coplanar (`z = 0`), so no faithful 3D simplex embedding can
+/// All points are coplanar (`z = 0`), so no faithful 3D simplex realization can
 /// be formed.
 #[allow(
     dead_code,

benches/profiling_suite.rs

@@ -1072,11 +1072,11 @@ macro_rules! benchmark_validation_components_dimension {
                 });
             });
 
-            group.bench_function("validate_embedding", |b| {
+            group.bench_function("validate_realization", |b| {
                 b.iter(|| {
-                    if let Err(error) = black_box(dt.as_triangulation().validate_embedding()) {
+                    if let Err(error) = black_box(dt.as_triangulation().validate_realization()) {
                         abort_benchmark(format_args!(
-                            "embedding validation should pass for benchmark triangulation: {error}"
+                            "realization validation should pass for benchmark triangulation: {error}"
                         ));
                     }
                 });

docs/ORIENTATION_SPEC.md

@@ -202,7 +202,7 @@ drive repair, but replacement-simplex orientation itself uses `robust_orientatio
   and then enforces the Delaunay property.
 - `.try_toroidal([..])` builds an image-point triangulation and then runs
   orientation normalization, lifted geometric orientation validation, final
-  Levels 1-3 topology validation, Level 4 Embedding Validity in periodic
+  Levels 1-3 topology validation, Level 4 realization validation in periodic
   covering-space charts, and final Level 5 Delaunay-predicate validation before returning
   the quotient triangulation.