docs(validation): align the five-level validation contract

README.md

@@ -202,12 +202,13 @@ just notebook-clear-outputs-all
 The crate treats a finite point-set triangulation as an oriented abstract simplicial complex plus a
 coordinate realization in a supported geometric model. Level 1 certifies element validity, including
 coordinate storage and local coordinate invariants. Levels 2-3 certify combinatorial consistency and
-intrinsic PL topology without depending on coordinates. Level 4 certifies geometric validity:
-affine-chart maximal simplices must be positively oriented, every maximal simplex must satisfy its
-model's nondegeneracy constraints, 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.
+intrinsic PL topology without depending on coordinates: Level 2 checks coherent stored simplex
+orderings, while Level 3 independently certifies intrinsic orientability for supported 2D/3D
+PL-manifold guarantees, including periodic quotient constraints. Level 4 certifies geometric validity:
+Euclidean/toroidal affine-chart maximal simplices must be positively oriented and nondegenerate, and
+their realizations may intersect only in shared abstract faces. The bounded spherical prototype
+separately certifies model-specific simplex nondegeneracy in `S^D \subset R^(D+1)`. 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.
@@ -230,9 +231,9 @@ For the detailed contract, see [`docs/validation.md`](docs/validation.md),
 | Level | Validates | Primary API |
 |---|---|---|
 | 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 | Valid Realization: model-valid orientation, nondegeneracy, and only shared-face intersections | `is_valid_realization()` / `realization_report()` |
+| 2 | Combinatorial Consistency: TDS incidence, adjacency, indexes, and stored orientation | `is_valid_structure()` / `structure_report()` |
+| 3 | Intrinsic PL Topology: manifold links, components, Euler consistency, and orientability | `is_valid_topology()` / `topology_report()` |
+| 4 | Valid Realization: affine-chart validity or bounded spherical simplex nondegeneracy, by backend | `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()` |
 
@@ -250,6 +251,7 @@ PL-manifold topology with explicit full-validation
 checkpoints. Layer-local APIs use `is_valid()` for unambiguous element/TDS owners, `is_valid_*`
 for higher-level fast-fail checks, and `*_diagnostic` / `*_report` for diagnostics; cumulative
 APIs use `validate()` / `validation_report()`.
+`orientation_witness()` exposes the supported 2D/3D Level 3 orientability certificate directly.
 
 For generated failure pictures, public test anchors, and diagnostics for each layer, run
 [`notebooks/01_validation.ipynb`](notebooks/01_validation.ipynb). For the paper-facing mathematical
@@ -271,7 +273,7 @@ exposition, see [`papers/validation.tex`](papers/validation.tex) and the compile
 - [Property Testing Summary](docs/property_testing_summary.md) - Property-test layout and coverage summary.
 - [Releasing](docs/RELEASING.md) - Changelog, benchmark, and publish workflow.
 - [Roadmap](docs/roadmap.md) - Current release sequence and deferred feature tracks.
-- [Topology](docs/topology.md) - Level 3 Intrinsic PL Topology validation and global topology models.
+- [Topology](docs/topology.md) - Level 3 Intrinsic PL Topology validation, orientability, and global topology models.
 - [Validation Guide](docs/validation.md) - Validation hierarchy and policy configuration.
 - [Validation Paper](papers/validation.pdf) - Reviewer-facing PDF for the validation architecture.
 - [Workflows](docs/workflows.md) - Practical recipes for construction, repair, toroidal domains, payloads, and flips.

docs/README.md

@@ -8,7 +8,7 @@ Historical design notes, investigations, and completed optimization roadmaps liv
 ## Start here
 
 - [`api_design.md`](api_design.md): construction, vertex lifecycle, and Pachner move APIs.
-- [`topology.md`](topology.md): Level 3 Intrinsic PL Topology invariants (manifold checks, Euler characteristic).
+- [`topology.md`](topology.md): Level 3 Intrinsic PL Topology invariants (manifold checks, orientability, Euler characteristic).
 - [`validation.md`](validation.md): the five-level validation model (Levels 1–5) and how to configure it.
 - [`../papers/validation.pdf`](../papers/validation.pdf): reviewer-facing validation architecture paper.
 - [`diagnostics.md`](diagnostics.md): opt-in diagnostic helpers, structured reports, and debug switches.

docs/diagnostics.md

@@ -98,6 +98,13 @@ Layer-local diagnostics follow a standard naming pattern:
 - `*_diagnostic`: first actionable repair/retry diagnostic for that layer.
 - `*_report`: all checkable layer-local failures.
 
+Orientation failures retain their owning layer. Level 2 stored-ordering
+incoherence is reported as `TdsError::OrientationViolation`; Level 3 intrinsic
+orientability is queried with `Triangulation::orientation_witness()` and reports
+`TriangulationValidationError::NonOrientable` for a contradictory 2D/3D parity
+system. Level 4 positive geometric orientation remains part of the realization
+diagnostic/report surface below.
+
 For Level 4 realization failures specifically, use
 `dt.as_triangulation().realization_diagnostic()` for the first repair-oriented
 failure and `dt.as_triangulation().realization_report()` for all checkable

docs/invariants.md

@@ -25,7 +25,7 @@ the guarantees stated in the public API documentation.
   - [Simplicial complexes and manifolds](#simplicial-complexes-and-manifolds)
     - [Simplicial complex model](#simplicial-complex-model)
   - [Validation layering](#validation-layering)
-  - [Coherent orientation](#coherent-orientation)
+  - [Orientation contracts](#orientation-contracts)
   - [Geometric invariants](#geometric-invariants)
     - [Valid realization](#valid-realization)
     - [Geometric predicates and the Delaunay condition](#geometric-predicates-and-the-delaunay-condition)
@@ -115,7 +115,7 @@ operation has certified which part of the structure:
    simplices, simplex/ridge connectivity, and coherent combinatorial orientation.
 3. **Level 3 — Intrinsic PL Topology**: the abstract simplicial complex satisfies the requested
    `TopologyGuarantee` (pseudomanifold, PL manifold, or strict PL manifold) through incidence,
-   connected components, Euler-characteristic, and link checks.
+   connected components, Euler-characteristic, link, and supported 2D/3D orientability checks.
 4. **Level 4 — Valid Realization**: the complex is geometrically valid in the chosen coordinate
    model. `Triangulation::is_valid_realization()` owns realization-only fast-fail validation, and
    `Triangulation::validate_realization()` owns cumulative Levels 1–4 certification. Euclidean and
@@ -142,22 +142,29 @@ explicit certification steps for workflows that need them.
 
 ---
 
-## Coherent orientation
+## Orientation contracts
 
-Coherent orientation has two related meanings in this crate:
+Orientation has three related but independently validated meanings in this crate:
 
-- **TDS orientation**: adjacent simplices must induce opposite orientations on their shared facet. In
+- **Intrinsic PL orientability (Level 3)**: the shared-facet parity constraints
+  must admit a coherent simplex-orientation assignment independently of the
+  orderings currently stored in the TDS. `Triangulation::orientation_witness()`
+  returns the opaque assignment for supported pure 2D/3D complexes.
+- **Stored TDS coherence (Level 2)**: adjacent simplices must induce opposite orientations on their shared facet. In
   practice this is checked by comparing the facet index in one simplex with the reciprocal mirror index
   in its neighbor.
-- **Geometric orientation**: a full `Triangulation` should store simplices with positive orientation in
-  Euclidean coordinates, except where an operation is explicitly handling a degenerate or
-  intermediate state.
+- **Geometric orientation (Level 4)**: Euclidean/toroidal maximal simplices
+  should have positive orientation in their active affine charts, while the
+  spherical backend enforces its model-specific realization conditions. An
+  operation may handle a degenerate or intermediate state only inside a
+  failure-atomic transaction.
 
 The orientation checker uses the robust orientation predicate directly instead of a kernel-level
 predicate that may apply Simulation of Simplicity. That preserves the distinction between an
 actually degenerate simplex and a deterministically tie-broken predicate result. At the TDS layer,
 periodic-image simplices compare lifted `(vertex, offset)` facet identities after translation
-normalization, so quotient facets participate in the same combinatorial-orientation contract.
+normalization, so quotient facets participate in stored-coherence and intrinsic-orientability
+constraints without conflating either property with geometric sign.
 
 Pachner and bistellar-editing transactions must keep coherent combinatorial orientation and positive
 geometric simplex orientation separate. A move can leave the TDS coherently oriented while affected
@@ -187,19 +194,20 @@ Level 4 is the valid-realization check. It is independent of Level 5 geometric p
 enforces:
 
 - every Euclidean/toroidal maximal simplex has positive geometric orientation in its affine chart;
-- every maximal simplex has nonzero `D`-volume under the robust orientation predicate;
-- every pair of maximal simplices intersects only in the realization of the face spanned by their
-  shared vertices;
+- every Euclidean/toroidal maximal simplex has nonzero `D`-volume under the robust orientation predicate;
+- every pair of Euclidean/toroidal maximal simplices intersects only in the realization of the face
+  spanned by their shared vertices;
 - Euclidean and toroidal triangulations use valid affine-chart realization checks, with toroidal
   triangulations checked in periodic covering-space charts, including translated
   images that can overlap across the fundamental-domain boundary.
 - the bounded spherical prototype validates `S^2`/`S^3` maximal simplices as nondegenerate spherical simplices
   in `S^D \subset R^(D+1)`.
 
 This is intentionally separate from topology. Non-orientable spaces are valid objects in topology in
-general, but this crate's TDS contract maintains coherent orientation for the oriented complexes its
-construction, flip, and predicate machinery operate on. Level 4 then asks whether that oriented
-complex is a valid realization in the active realization model. For Euclidean/toroidal affine-chart models, this means
+general, but the crate's 2D/3D PL-manifold guarantees require an intrinsic orientation witness, and
+its TDS contract separately maintains coherent stored orderings for the complexes its construction,
+flip, and predicate machinery operate on. Level 4 then asks whether that oriented complex is a valid
+realization in the active realization model. For Euclidean/toroidal affine-chart models, this means
 the vertex map is injective, every abstract simplex is realized as a nondegenerate affine simplex,
 and realized simplex intersections satisfy `|sigma| ∩ |tau| = |sigma ∩ tau|`. General spherical
 integration with the ordinary mutable triangulation surface and hyperbolic topology need

docs/limitations.md

@@ -73,7 +73,9 @@ Toroidal support has two modes:
 - `.try_toroidal([..])` uses the 3^D image-point method to construct a
   true periodic quotient with rewired neighbor pointers. This path is release
   covered in 2D and compact 3D, where periodic triangulations validate as
-  closed tori through Levels 1-5. Construction moves each canonical coordinate
+  closed tori through Levels 1-5, including translation-normalized Level 2
+  stored-orientation coherence and Level 3 intrinsic orientability. Construction
+  moves each canonical coordinate
   by at most about 2^-32 of its domain period using a deterministic perturbation
   that resolves periodic covering-space degeneracies while preserving vertex
   UUIDs and payloads.

docs/topology.md

@@ -88,16 +88,24 @@ Level 3 always checks:
 
 `TopologyGuarantee` controls which additional PL-manifold checks Level 3 runs:
 
-- `TopologyGuarantee::Pseudomanifold`: no additional link checks.
+- `TopologyGuarantee::Pseudomanifold`: no additional link or orientability checks.
 - `TopologyGuarantee::PLManifold`: runs ridge-link validation during insertion and
-  requires a completion-time vertex-link pass for full certification.
+  requires a completion-time vertex-link pass for full certification; in 2D/3D,
+  it also certifies intrinsic orientability.
 - `TopologyGuarantee::PLManifoldStrict`: runs vertex-link validation after every
-  insertion (slowest, maximum safety).
+  insertion and certifies 2D/3D intrinsic orientability (slowest, maximum safety).
+
+`Triangulation::orientation_witness()` returns the opaque coherent assignment
+used by the 2D/3D Level 3 check. This is independent of Level 2 stored-ordering
+coherence and Level 4 positive geometric orientation. Periodic quotient facets
+contribute parity constraints through translation-normalized lifted vertex
+identities, including explicit self-identifications.
 
 Implementation pointers:
 
 - Level 3 entry points and validation vocabulary: `src/core/validation.rs`
-  (`Triangulation::is_valid_topology`, `Triangulation::validate`)
+  (`Triangulation::is_valid_topology`, `Triangulation::orientation_witness`,
+  `OrientationWitness`, and `Triangulation::validate`)
 - Owner-level topology validators: `src/core/validation.rs` and
   `src/delaunay/query.rs`
   (`Triangulation::validate_ridge_links`,