delaunay 0.8.2

//! Mutation and repair operations for the triangulation data structure.

use super::errors::{
    EntityKind, NeighborValidationError, TdsConstructionError, TdsError, TdsMutationError,
    TriangulationConstructionState,
};
use super::incidence::SimplexIncidenceRemoval;
use super::model::{SimplexUuidSortKey, Tds, UnverifiedTds};
use super::{SimplexKey, TdsRollbackTransaction, VertexKey};
use crate::core::collections::{
    CLEANUP_OPERATION_BUFFER_SIZE, Entry, FastHashMap, MAX_PRACTICAL_DIMENSION_SIZE, SimplexKeySet,
    SimplexRemovalBuffer, SmallBuffer, VertexKeySet, fast_hash_map_with_capacity,
    fast_hash_set_with_capacity,
};
use crate::core::simplex::{NeighborSlot, Simplex, SimplexValidationError};
use crate::core::vertex::Vertex;
use crate::refinement::RefinementError;
use std::collections::VecDeque;

/// Topology validation mode for checked TDS simplex insertion.
#[derive(Clone, Copy)]
enum SimplexInsertionTopologyCheck {
    /// Validate the candidate against all existing simplices.
    Checked,
    /// Skip global topology scans because the caller validated the local cavity.
    Prechecked,
}

type SimplexRemovalRecord = (
    SimplexKey,
    SmallBuffer<VertexKey, MAX_PRACTICAL_DIMENSION_SIZE>,
);
type SimplexRemovalRecords = SmallBuffer<SimplexRemovalRecord, CLEANUP_OPERATION_BUFFER_SIZE>;
type SimplexIncidenceRemovalRecords =
    SmallBuffer<SimplexIncidenceRemoval, CLEANUP_OPERATION_BUFFER_SIZE>;
type IncidentSimplexUpdates =
    SmallBuffer<(VertexKey, Option<SimplexKey>), CLEANUP_OPERATION_BUFFER_SIZE>;

/// Membership test for a pending simplex-removal batch.
///
/// Small conflict regions stay inline to avoid per-insertion hash allocation;
/// large batches fall back to a hash set so bulk cleanup keeps O(1) membership.
enum RemovedSimplexMembership<'a> {
    Inline(&'a [SimplexRemovalRecord]),
    Hashed(SimplexKeySet),
}

impl<'a> RemovedSimplexMembership<'a> {
    /// Builds membership over removals without allocating for ordinary small cavities.
    fn from_removals(simplex_removals: &'a [SimplexRemovalRecord]) -> Self {
        if simplex_removals.len() <= CLEANUP_OPERATION_BUFFER_SIZE {
            return Self::Inline(simplex_removals);
        }

        let mut simplex_keys = fast_hash_set_with_capacity(simplex_removals.len());
        simplex_keys.extend(simplex_removals.iter().map(|(simplex_key, _)| *simplex_key));
        Self::Hashed(simplex_keys)
    }

    /// Returns whether `simplex_key` is in the removal batch.
    fn contains(&self, simplex_key: SimplexKey) -> bool {
        match self {
            Self::Inline(simplex_removals) => simplex_removals
                .iter()
                .any(|(removed_key, _)| *removed_key == simplex_key),
            Self::Hashed(simplex_keys) => simplex_keys.contains(&simplex_key),
        }
    }
}

/// Unique affected vertices from a simplex-removal batch.
///
/// Small cavities use a compact inline list; larger maintenance operations use
/// the existing hash-set representation to preserve scaling behavior.
enum AffectedVertexRecords {
    Inline(SmallBuffer<VertexKey, CLEANUP_OPERATION_BUFFER_SIZE>),
    Hashed(VertexKeySet),
}

impl AffectedVertexRecords {
    /// Creates a unique-vertex accumulator sized for the expected removal frontier.
    fn with_expected_len(expected_len: usize) -> Self {
        if expected_len <= CLEANUP_OPERATION_BUFFER_SIZE {
            return Self::Inline(SmallBuffer::with_capacity(expected_len));
        }

        Self::Hashed(fast_hash_set_with_capacity(expected_len))
    }

    /// Inserts a vertex once, preserving set semantics for repair traversal.
    fn insert(&mut self, vertex_key: VertexKey) {
        match self {
            Self::Inline(vertices) => {
                if !vertices.contains(&vertex_key) {
                    vertices.push(vertex_key);
                }
            }
            Self::Hashed(vertices) => {
                vertices.insert(vertex_key);
            }
        }
    }

    /// Returns the number of unique affected vertices.
    fn len(&self) -> usize {
        match self {
            Self::Inline(vertices) => vertices.len(),
            Self::Hashed(vertices) => vertices.len(),
        }
    }

    /// Visits each affected vertex exactly once, stopping on the first error.
    fn try_for_each<E>(&self, mut visit: impl FnMut(VertexKey) -> Result<(), E>) -> Result<(), E> {
        match self {
            Self::Inline(vertices) => {
                for &vertex_key in vertices {
                    visit(vertex_key)?;
                }
            }
            Self::Hashed(vertices) => {
                for &vertex_key in vertices {
                    visit(vertex_key)?;
                }
            }
        }
        Ok(())
    }
}

/// Candidate surviving incident simplices keyed by affected vertex.
///
/// This is deliberately map-like without forcing a hash allocation for the
/// common one-to-few simplex removal performed during insertion.
#[expect(
    clippy::large_enum_variant,
    reason = "inline small-cavity candidate storage avoids hot-path allocations; large batches use the hash-backed variant"
)]
enum CandidateIncidentRecords {
    Inline(SmallBuffer<(VertexKey, SimplexKey), CLEANUP_OPERATION_BUFFER_SIZE>),
    Hashed(FastHashMap<VertexKey, SimplexKey>),
}

impl CandidateIncidentRecords {
    /// Creates a candidate map with inline storage for ordinary small cavities.
    fn with_expected_len(expected_len: usize) -> Self {
        if expected_len <= CLEANUP_OPERATION_BUFFER_SIZE {
            return Self::Inline(SmallBuffer::with_capacity(expected_len));
        }

        Self::Hashed(fast_hash_map_with_capacity(expected_len))
    }

    /// Records the first surviving incident simplex discovered for a vertex.
    fn insert_if_absent(&mut self, vertex_key: VertexKey, simplex_key: SimplexKey) {
        match self {
            Self::Inline(candidates) => {
                if !candidates
                    .iter()
                    .any(|(candidate_vertex, _)| *candidate_vertex == vertex_key)
                {
                    candidates.push((vertex_key, simplex_key));
                }
            }
            Self::Hashed(candidates) => {
                candidates.entry(vertex_key).or_insert(simplex_key);
            }
        }
    }

    /// Returns a candidate surviving incident simplex for `vertex_key`.
    fn get(&self, vertex_key: VertexKey) -> Option<SimplexKey> {
        match self {
            Self::Inline(candidates) => {
                candidates
                    .iter()
                    .find_map(|(candidate_vertex, simplex_key)| {
                        (*candidate_vertex == vertex_key).then_some(*simplex_key)
                    })
            }
            Self::Hashed(candidates) => candidates.get(&vertex_key).copied(),
        }
    }
}

impl<U, V, const D: usize> Tds<U, V, D> {
    /// Assigns neighbor relationships between simplices based on shared facets with semantic ordering.
    ///
    /// This method efficiently builds neighbor relationships by using the `facet_key_from_vertices`
    /// function to compute unique keys for facets. Two simplices are considered neighbors if they share
    /// exactly one facet (which contains D vertices for a D-dimensional triangulation).
    ///
    /// **Note**: This is a purely combinatorial operation that does not perform any coordinate
    /// operations. It works entirely with vertex keys, simplex keys, and topological relationships.
    ///
    /// **Internal use only**: This method rebuilds ALL neighbor pointers from scratch, which is
    /// inefficient for most use cases. Public callers should use owning
    /// triangulation repair and validation workflows instead of mutating raw
    /// neighbor storage directly.
    ///
    /// # Errors
    ///
    /// Returns `TdsError` if neighbor assignment fails due to inconsistent
    /// data structures or invalid facet sharing patterns.
    pub(crate) fn assign_neighbors(&mut self) -> Result<(), TdsError> {
        // Build facet mapping with vertex index information using optimized collections
        // facet_key -> [(simplex_key, vertex_index_opposite_to_facet)]
        type FacetInfo = (SimplexKey, usize);
        // Use saturating arithmetic to avoid potential overflow on adversarial inputs
        let cap = self.simplices.len().saturating_mul(D.saturating_add(1));
        let mut facet_map: FastHashMap<u64, SmallBuffer<FacetInfo, 2>> =
            fast_hash_map_with_capacity(cap);

        for (simplex_key, simplex) in self.simplices.iter() {
            let vertices = self.simplex_vertices(simplex_key)?;

            for i in 0..vertices.len() {
                let facet_key =
                    Self::periodic_facet_key_from_simplex_vertices(simplex, vertices, i)?;
                let facet_entry = facet_map.entry(facet_key).or_default();
                // Detect degenerate case early: more than 2 simplices sharing a facet
                // Note: Check happens before push, so len() reflects current sharing count
                if facet_entry.len() >= 2 {
                    return Err(TdsError::FacetSharingViolation {
                        facet_key,
                        existing_incident_count: facet_entry.len(),
                        attempted_incident_count: facet_entry.len().saturating_add(1),
                        max_incident_count: 2,
                        candidate_simplex_uuid: simplex.uuid(),
                        candidate_facet_index: i,
                    });
                }
                facet_entry.push((simplex_key, i));
            }
        }

        // For each simplex, build an ordered neighbor array where neighbors[i] is opposite vertices[i]
        let mut simplex_neighbors: FastHashMap<
            SimplexKey,
            SmallBuffer<Option<SimplexKey>, MAX_PRACTICAL_DIMENSION_SIZE>,
        > = fast_hash_map_with_capacity(self.simplices.len());

        // Initialize each simplex with a SmallBuffer of None values (one per vertex)
        for (simplex_key, simplex) in self.simplices.iter() {
            let vertex_count = simplex.number_of_vertices();
            if vertex_count > MAX_PRACTICAL_DIMENSION_SIZE {
                return Err(TdsError::InconsistentDataStructure {
                    message: format!(
                        "simplex {} vertex count ({vertex_count}) exceeds storage limit MAX_PRACTICAL_DIMENSION_SIZE ({MAX_PRACTICAL_DIMENSION_SIZE}) (would overflow neighbors buffer)",
                        simplex.uuid(),
                    ),
                });
            }
            let mut neighbors = SmallBuffer::with_capacity(vertex_count);
            neighbors.resize(vertex_count, None);
            simplex_neighbors.insert(simplex_key, neighbors);
        }

        // For each facet that is shared by exactly two simplices, establish neighbor relationships
        // Note: >2 simplices per facet already caught by early check during map build (above)
        for (_facet_key, facet_infos) in facet_map {
            if facet_infos.len() != 2 {
                continue;
            }

            let (simplex_key1, vertex_index1) = facet_infos[0];
            let (simplex_key2, vertex_index2) = facet_infos[1];

            // Set neighbors with semantic constraint: neighbors[i] is opposite vertices[i]
            simplex_neighbors.get_mut(&simplex_key1).ok_or_else(|| {
                TdsError::SimplexNotFound {
                    simplex_key: simplex_key1,
                    context: "assign_neighbors: simplex missing from local neighbors map"
                        .to_string(),
                }
            })?[vertex_index1] = Some(simplex_key2);

            simplex_neighbors.get_mut(&simplex_key2).ok_or_else(|| {
                TdsError::SimplexNotFound {
                    simplex_key: simplex_key2,
                    context: "assign_neighbors: simplex missing from local neighbors map"
                        .to_string(),
                }
            })?[vertex_index2] = Some(simplex_key1);
        }

        // Apply updates. Even simplices with only boundary facets receive an
        // assigned boundary buffer so assigned-boundary and unassigned states
        // remain distinct.
        for (simplex_key, neighbors) in &simplex_neighbors {
            self.journal_simplex_before_write(*simplex_key);
            if let Some(simplex) = self.simplices.get_mut(*simplex_key) {
                let simplex_id = simplex.uuid();
                simplex
                    .set_neighbors_from_keys(neighbors.iter().copied())
                    .map_err(|source| TdsError::InvalidSimplex { simplex_id, source })?;
            }
        }

        // Topology changed; invalidate caches.
        self.bump_generation();

        Ok(())
    }

    // =========================================================================
    // QUERY OPERATIONS
    // =========================================================================

    /// Atomically inserts a vertex and creates the UUID-to-key mapping.
    ///
    /// This method ensures that both the vertex insertion and UUID mapping are
    /// performed together, maintaining data structure invariants.
    ///
    /// **⚠️ INTERNAL API WARNING**: This method bypasses atomicity guarantees for topology
    /// assignment operations (`assign_neighbors()` and `assign_incident_simplices()`). It only
    /// ensures atomic vertex insertion and UUID mapping. If you need full atomicity including
    /// topology assignment, use `insert_vertex_with_topology_assignment()` instead.
    ///
    /// **Note:** This method does NOT check for duplicate coordinates. It only checks
    /// for UUID uniqueness. Duplicate coordinate checking is performed at a higher layer
    /// in `Triangulation::try_insert_impl()` before calling this method.
    ///
    /// # Arguments
    ///
    /// * `vertex` - The vertex to insert
    ///
    /// # Returns
    ///
    /// The `VertexKey` that can be used to access the inserted vertex.
    ///
    /// # Errors
    ///
    /// Returns [`TdsConstructionError::DuplicateUuid`] if a vertex with the
    /// same UUID already exists in the triangulation.
    ///
    /// # Examples
    ///
    ///
    /// See the unit tests for usage examples of this pub(crate) method.
    pub(crate) fn insert_vertex_with_mapping(
        &mut self,
        vertex: Vertex<U, D>,
    ) -> Result<VertexKey, TdsConstructionError> {
        let vertex_uuid = vertex.uuid();

        if self.uuid_to_vertex_key.contains_key(&vertex_uuid) {
            return Err(TdsConstructionError::DuplicateUuid {
                entity: EntityKind::Vertex,
                uuid: vertex_uuid,
            });
        }

        let vertex_key = self.vertices.insert(vertex);
        self.journal_incidence_before_write([vertex_key]);
        if let Err(source) = self.insert_empty_vertex_incidence(vertex_key) {
            self.vertices.remove(vertex_key);
            return Err(TdsConstructionError::ValidationError { source });
        }
        self.uuid_to_vertex_key.insert(vertex_uuid, vertex_key);
        self.journal_inserted_vertex(vertex_key, vertex_uuid);
        self.refresh_incomplete_construction_state();
        // Topology changed; invalidate caches.
        self.bump_generation();
        Ok(vertex_key)
    }

    /// Atomically inserts a simplex and creates the UUID-to-key mapping.
    ///
    /// This method ensures that both the simplex insertion and UUID mapping are
    /// performed together, maintaining data structure invariants. This is preferred
    /// over separate raw storage insertion plus `uuid_to_simplex_key.insert()` calls, which can
    /// leave the data structure in an inconsistent state if interrupted.
    ///
    /// # Arguments
    ///
    /// * `simplex` - The simplex to insert
    ///
    /// # Returns
    ///
    /// The `SimplexKey` that can be used to access the inserted simplex.
    ///
    /// # Errors
    ///
    /// Returns [`TdsConstructionError::DuplicateUuid`] if a simplex with the
    /// same UUID already exists in the triangulation, or
    /// [`TdsConstructionError::ValidationError`] if the simplex arity does not
    /// match `D + 1`, or if any vertex key referenced by `simplex` is not present
    /// in this TDS.
    ///
    /// # Examples
    ///
    ///
    /// See the unit tests for usage examples of this pub(crate) method.
    pub(crate) fn insert_simplex_with_mapping(
        &mut self,
        simplex: Simplex<V, D>,
    ) -> Result<SimplexKey, TdsConstructionError> {
        self.insert_simplex_with_mapping_impl(simplex, SimplexInsertionTopologyCheck::Checked)
    }

    /// Atomically inserts a simplex after validating vertex provenance.
    ///
    /// Cavity filling, flips, and explicit construction should only build
    /// `simplex` from vertex keys that came from this TDS and are still live. This
    /// method still verifies that invariant in every build mode so stale keys
    /// fail with a typed error instead of corrupting TDS invariants.
    ///
    /// # Errors
    ///
    /// Returns [`TdsConstructionError::DuplicateUuid`] if a simplex with the same
    /// UUID already exists, [`TdsConstructionError::ValidationError`] if the
    /// arity is wrong, or [`TdsConstructionError::ValidationError`] if any
    /// referenced vertex key is not present in this TDS.
    pub(crate) fn insert_simplex_with_mapping_trusted_vertices(
        &mut self,
        simplex: Simplex<V, D>,
    ) -> Result<SimplexKey, TdsConstructionError> {
        self.insert_simplex_with_mapping_impl(simplex, SimplexInsertionTopologyCheck::Checked)
    }

    /// Inserts a caller-validated simplex without global topology scans.
    ///
    /// Hull-extension callers use this only after proving that candidate simplices
    /// are built from visible boundary facets around a fresh apex and before
    /// immediately wiring local neighbors and validating the affected topology.
    pub(crate) fn insert_simplex_with_mapping_prechecked_topology(
        &mut self,
        simplex: Simplex<V, D>,
    ) -> Result<SimplexKey, TdsConstructionError> {
        self.insert_simplex_with_mapping_impl(simplex, SimplexInsertionTopologyCheck::Prechecked)
    }

    /// Shared checked simplex-insertion path used by public and trusted internal wrappers.
    fn insert_simplex_with_mapping_impl(
        &mut self,
        simplex: Simplex<V, D>,
        topology_check: SimplexInsertionTopologyCheck,
    ) -> Result<SimplexKey, TdsConstructionError> {
        if simplex.number_of_vertices() != D + 1 {
            return Err(TdsConstructionError::ValidationError {
                source: TdsError::DimensionMismatch {
                    expected: D + 1,
                    actual: simplex.number_of_vertices(),
                    context: format!("{D}-dimensional simplex vertex count"),
                },
            });
        }

        let simplex_uuid = simplex.uuid();
        if self.uuid_to_simplex_key.contains_key(&simplex_uuid) {
            return Err(TdsConstructionError::DuplicateUuid {
                entity: EntityKind::Simplex,
                uuid: simplex_uuid,
            });
        }

        match topology_check {
            SimplexInsertionTopologyCheck::Checked => {
                self.validate_simplex_vertices_exist(&simplex)?;
                self.validate_simplex_topology_safe_for_insertion(&simplex)?;
            }
            SimplexInsertionTopologyCheck::Prechecked => {}
        }

        let simplex_vertices: SmallBuffer<VertexKey, MAX_PRACTICAL_DIMENSION_SIZE> =
            simplex.vertices().iter().copied().collect();
        let simplex_key = self.simplices.insert(simplex);
        self.uuid_to_simplex_key.insert(simplex_uuid, simplex_key);
        self.journal_incidence_before_write(simplex_vertices.iter().copied());
        if let Err(source) = self.add_simplex_to_vertex_incidence(simplex_key, &simplex_vertices) {
            self.simplices.remove(simplex_key);
            self.uuid_to_simplex_key.remove(&simplex_uuid);
            return Err(TdsConstructionError::ValidationError { source });
        }
        self.journal_inserted_simplex(simplex_key, simplex_uuid);
        // Topology changed; invalidate caches.
        self.bump_generation();
        Ok(simplex_key)
    }

    /// Verifies that inserting `simplex` would not violate local topology invariants.
    fn validate_simplex_topology_safe_for_insertion(
        &self,
        simplex: &Simplex<V, D>,
    ) -> Result<(), TdsConstructionError> {
        self.validate_no_duplicate_simplex_on_insert(simplex)?;
        self.validate_facet_sharing_on_insert(simplex)?;
        Ok(())
    }

    /// Builds the duplicate-simplex identity for a not-yet-inserted simplex.
    fn candidate_periodic_vertex_uuid_offsets(
        &self,
        simplex: &Simplex<V, D>,
    ) -> Result<SimplexUuidSortKey<D>, TdsError> {
        let vertices = simplex.vertices();
        let periodic_offsets = simplex.periodic_vertex_offsets();
        if let Some(offsets) = periodic_offsets
            && offsets.len() != vertices.len()
        {
            return Err(TdsError::DimensionMismatch {
                expected: vertices.len(),
                actual: offsets.len(),
                context: format!(
                    "candidate simplex {} periodic offset count vs vertex count",
                    simplex.uuid()
                ),
            });
        }

        let mut vertex_uuid_offsets = SimplexUuidSortKey::<D>::new();
        for (vertex_idx, &vertex_key) in vertices.iter().enumerate() {
            let vertex = self
                .vertices
                .get(vertex_key)
                .ok_or_else(|| TdsError::VertexNotFound {
                    vertex_key,
                    context: format!(
                        "referenced by candidate simplex {} at index {vertex_idx} while building periodic vertex identity (UUID/offset)",
                        simplex.uuid()
                    ),
                })?;
            let offset = periodic_offsets.map_or([0_i8; D], |offsets| offsets[vertex_idx]);
            vertex_uuid_offsets.push((vertex.uuid(), offset));
        }
        vertex_uuid_offsets.sort_unstable();

        Ok(vertex_uuid_offsets)
    }

    /// Rejects a candidate simplex that duplicates an existing maximal simplex.
    fn validate_no_duplicate_simplex_on_insert(
        &self,
        simplex: &Simplex<V, D>,
    ) -> Result<(), TdsError> {
        let candidate_identity = self.candidate_periodic_vertex_uuid_offsets(simplex)?;

        for (existing_simplex_key, existing_simplex) in self.simplices.iter() {
            let vertices = self.simplex_vertices(existing_simplex_key)?;
            let existing_identity =
                self.build_periodic_vertex_uuid_offsets(existing_simplex_key, vertices)?;

            if existing_identity == candidate_identity {
                return Err(TdsError::DuplicateSimplices {
                    simplex_pairs: vec![[existing_simplex.uuid(), simplex.uuid()]],
                    message: format!(
                        "Refusing to insert duplicate simplex {} with same vertex UUIDs as existing simplex {existing_simplex_key:?}: {candidate_identity:?}",
                        simplex.uuid()
                    ),
                });
            }
        }

        Ok(())
    }

    /// Rejects a candidate simplex whose facets would be incident to a third simplex.
    fn validate_facet_sharing_on_insert(&self, simplex: &Simplex<V, D>) -> Result<(), TdsError> {
        let vertices = simplex.vertices();
        for candidate_facet_idx in 0..vertices.len() {
            let candidate_facet_key = Self::periodic_facet_key_from_simplex_vertices(
                simplex,
                vertices,
                candidate_facet_idx,
            )?;
            let mut incident_count = 0_usize;

            for (existing_simplex_key, existing_simplex) in self.simplices.iter() {
                let existing_vertices = self.simplex_vertices(existing_simplex_key)?;
                for existing_facet_idx in 0..existing_vertices.len() {
                    let existing_facet_key = Self::periodic_facet_key_from_simplex_vertices(
                        existing_simplex,
                        existing_vertices,
                        existing_facet_idx,
                    )?;
                    if existing_facet_key == candidate_facet_key {
                        incident_count += 1;
                        if incident_count >= 2 {
                            return Err(TdsError::FacetSharingViolation {
                                facet_key: candidate_facet_key,
                                existing_incident_count: incident_count,
                                attempted_incident_count: incident_count + 1,
                                max_incident_count: 2,
                                candidate_simplex_uuid: simplex.uuid(),
                                candidate_facet_index: candidate_facet_idx,
                            });
                        }
                    }
                }
            }
        }

        Ok(())
    }

    /// Verifies every vertex key referenced by `simplex` is live in this TDS.
    fn validate_simplex_vertices_exist(
        &self,
        simplex: &Simplex<V, D>,
    ) -> Result<(), TdsConstructionError> {
        for &vkey in simplex.vertices() {
            if !self.vertices.contains_key(vkey) {
                return Err(TdsConstructionError::ValidationError {
                    source: TdsError::VertexNotFound {
                        vertex_key: vkey,
                        context: "referenced by simplex being inserted".to_string(),
                    },
                });
            }
        }
        Ok(())
    }

    /// Sets the auxiliary data on a vertex, returning the previous value.
    ///
    /// This is a safe O(1) operation that modifies only the user-data field.
    /// It does not affect geometry, topology, or Delaunay invariants.
    ///
    /// # Arguments
    ///
    /// * `key` - The key of the vertex to modify
    /// * `data` - The new data value to set, or `None` to clear
    ///
    /// # Returns
    ///
    /// The old `Option<U>` value when the key exists.
    ///
    /// # Errors
    ///
    /// Returns [`TdsMutationError`] if `key` does not identify a vertex in this
    /// TDS. Detached keys are validated at the mutation boundary so stale
    /// handles cannot be mistaken for an existing vertex with no payload.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::CoordinateConversionError;
    /// use delaunay::prelude::tds::TdsMutationError;
    /// use delaunay::prelude::triangulation::{
    ///     FastKernel, Triangulation, TriangulationConstructionError,
    /// };
    ///
    /// # #[derive(Debug, thiserror::Error)]
    /// # enum ExampleError {
    /// #     #[error(transparent)]
    /// #     Construction(#[from] TriangulationConstructionError),
    /// #     #[error(transparent)]
    /// #     Mutation(#[from] TdsMutationError),
    /// #     #[error(transparent)]
    /// #     Coordinate(#[from] CoordinateConversionError),
    /// # }
    /// # fn main() -> Result<(), ExampleError> {
    /// let vertices = [
    ///     delaunay::vertex![0.0, 0.0; data = 10i32]?,
    ///     delaunay::vertex![1.0, 0.0; data = 20]?,
    ///     delaunay::vertex![0.0, 1.0; data = 30]?,
    /// ];
    /// let mut tds =
    ///     Triangulation::<FastKernel<f64>, i32, (), 2>::build_initial_simplex(&vertices)?;
    /// let Some(key) = tds.vertex_keys().next() else {
    ///     return Ok(());
    /// };
    ///
    /// // Replace existing data
    /// let prev = tds.set_vertex_data(key, Some(99))?;
    /// assert!(prev.is_some());
    ///
    /// // Verify new value
    /// let Some(vertex) = tds.vertex(key) else {
    ///     return Ok(());
    /// };
    /// assert_eq!(vertex.data(), Some(&99));
    ///
    /// // Clear data
    /// let prev = tds.set_vertex_data(key, None)?;
    /// assert_eq!(prev, Some(99));
    /// assert_eq!(tds.vertex(key).and_then(|vertex| vertex.data()), None);
    /// # Ok(())
    /// # }
    /// ```
    #[inline]
    pub fn set_vertex_data(
        &mut self,
        key: VertexKey,
        data: Option<U>,
    ) -> Result<Option<U>, TdsMutationError> {
        let vertex = self.vertices.get_mut(key).ok_or_else(|| {
            TdsMutationError::from(TdsError::VertexNotFound {
                vertex_key: key,
                context: "set_vertex_data".to_string(),
            })
        })?;
        let previous = vertex.data.take();
        vertex.data = data;
        Ok(previous)
    }

    /// Sets the auxiliary data on a simplex, returning the previous value.
    ///
    /// This is a safe O(1) operation that modifies only the user-data field.
    /// It does not affect geometry, topology, or Delaunay invariants.
    ///
    /// # Arguments
    ///
    /// * `key` - The key of the simplex to modify
    /// * `data` - The new data value to set, or `None` to clear
    ///
    /// # Returns
    ///
    /// The old `Option<V>` value when the key exists.
    ///
    /// # Errors
    ///
    /// Returns [`TdsMutationError`] if `key` does not identify a simplex in
    /// this TDS. Detached keys are validated at the mutation boundary so stale
    /// handles cannot be mistaken for an existing simplex with no payload.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::CoordinateConversionError;
    /// use delaunay::prelude::tds::TdsMutationError;
    /// use delaunay::prelude::triangulation::{
    ///     FastKernel, Triangulation, TriangulationConstructionError,
    /// };
    ///
    /// # #[derive(Debug, thiserror::Error)]
    /// # enum ExampleError {
    /// #     #[error(transparent)]
    /// #     Construction(#[from] TriangulationConstructionError),
    /// #     #[error(transparent)]
    /// #     Mutation(#[from] TdsMutationError),
    /// #     #[error(transparent)]
    /// #     Coordinate(#[from] CoordinateConversionError),
    /// # }
    /// # fn main() -> Result<(), ExampleError> {
    /// let vertices = [
    ///     delaunay::vertex![0.0, 0.0]?,
    ///     delaunay::vertex![1.0, 0.0]?,
    ///     delaunay::vertex![0.0, 1.0]?,
    /// ];
    /// let mut tds =
    ///     Triangulation::<FastKernel<f64>, (), i32, 2>::build_initial_simplex(&vertices)?;
    /// let Some(key) = tds.simplex_keys().next() else {
    ///     return Ok(());
    /// };
    ///
    /// // Set data on a simplex that had no data
    /// let prev = tds.set_simplex_data(key, Some(42))?;
    /// assert_eq!(prev, None);
    ///
    /// // Verify new value
    /// let Some(simplex) = tds.simplex(key) else {
    ///     return Ok(());
    /// };
    /// assert_eq!(simplex.data(), Some(&42));
    ///
    /// // Clear data
    /// let prev = tds.set_simplex_data(key, None)?;
    /// assert_eq!(prev, Some(42));
    /// assert_eq!(tds.simplex(key).and_then(|simplex| simplex.data()), None);
    /// # Ok(())
    /// # }
    /// ```
    #[inline]
    pub fn set_simplex_data(
        &mut self,
        key: SimplexKey,
        data: Option<V>,
    ) -> Result<Option<V>, TdsMutationError> {
        let simplex = self.simplices.get_mut(key).ok_or_else(|| {
            TdsMutationError::from(TdsError::SimplexNotFound {
                simplex_key: key,
                context: "set_simplex_data".to_string(),
            })
        })?;
        let previous = simplex.data.take();
        simplex.data = data;
        Ok(previous)
    }

    /// Fills every live simplex with data computed from the current simplex view.
    ///
    /// This does not alter topology, UUID mappings, neighbor links, or generation:
    /// simplex payloads are orthogonal to the TDS structural invariants.
    #[inline]
    pub(crate) fn fill_simplex_data<F>(&mut self, mut data_for: F)
    where
        F: FnMut(SimplexKey, &Simplex<V, D>) -> V,
    {
        for (simplex_key, simplex) in self.simplices.iter_mut() {
            let data = data_for(simplex_key, simplex);
            simplex.data = Some(data);
        }
    }

    /// Removes multiple simplices by their keys in a batch operation.
    ///
    /// This method performs a **local** topology update:
    /// - Removes the requested simplices (and their UUID→Key mappings)
    /// - Clears neighbor back-references in adjacent surviving simplices so no neighbor points at a removed key
    /// - Repairs `Vertex::incident_simplex` for vertices that previously pointed at a removed simplex
    ///
    /// It does **not** attempt to retriangulate the cavity created by the removals.
    /// If the maintained incidence index rejects the batch before simplex
    /// storage is changed, all incidence edits made by the failed batch are
    /// rolled back exactly.
    ///
    /// # Performance
    ///
    /// When neighbor pointers are present and mutually consistent, this touches only the
    /// boundary of the removed region:
    /// - Time: typically `O(#removed_simplices × (D+1)^2)`
    /// - Space: `O(#removed_simplices × (D+1))` for temporary removal metadata
    ///
    /// In degraded states (e.g., after unsafe mutation where neighbor pointers are missing),
    /// it may fall back to a conservative scan to find replacement incident simplices.
    ///
    /// # Arguments
    ///
    /// * `simplex_keys` - The keys of simplices to remove
    ///
    /// # Returns
    ///
    /// The number of simplices successfully removed.
    ///
    /// # Errors
    ///
    /// Returns [`TdsMutationError`] if the maintained vertex-to-simplices
    /// incidence index cannot remove one of the requested simplices without
    /// violating its stored relation. In that case, no simplex storage or UUID
    /// mapping is removed, and any earlier incidence edits from the same batch
    /// are restored.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::CoordinateConversionError;
    /// use delaunay::prelude::tds::TdsMutationError;
    /// use delaunay::prelude::triangulation::{
    ///     FastKernel, Triangulation, TriangulationConstructionError,
    /// };
    ///
    /// # #[derive(Debug, thiserror::Error)]
    /// # enum ExampleError {
    /// #     #[error(transparent)]
    /// #     Construction(#[from] TriangulationConstructionError),
    /// #     #[error(transparent)]
    /// #     Mutation(#[from] TdsMutationError),
    /// #     #[error(transparent)]
    /// #     Coordinate(#[from] CoordinateConversionError),
    /// # }
    /// # fn main() -> Result<(), ExampleError> {
    /// let vertices = [
    ///     delaunay::vertex![0.0, 0.0]?,
    ///     delaunay::vertex![1.0, 0.0]?,
    ///     delaunay::vertex![0.0, 1.0]?,
    /// ];
    /// let mut tds =
    ///     Triangulation::<FastKernel<f64>, (), (), 2>::build_initial_simplex(&vertices)?;
    /// let Some(simplex_key) = tds.simplex_keys().next() else {
    ///     return Ok(());
    /// };
    /// let removed = tds.remove_simplices_by_keys(&[simplex_key])?;
    /// assert_eq!(removed, 1);
    /// assert_eq!(tds.number_of_simplices(), 0);
    /// # Ok(())
    /// # }
    /// ```
    pub fn remove_simplices_by_keys(
        &mut self,
        simplex_keys: &[SimplexKey],
    ) -> Result<usize, TdsMutationError> {
        if simplex_keys.is_empty() {
            return Ok(0);
        }

        let simplex_removals = self.collect_existing_simplex_removals(simplex_keys);
        if simplex_removals.is_empty() {
            return Ok(0);
        }

        let simplices_to_remove = RemovedSimplexMembership::from_removals(&simplex_removals);

        // 1) Collect boundary candidates before mutation while neighbor
        // pointers to the removed simplices are still available.
        let (affected_vertices, candidate_incident) =
            self.collect_incident_repair_frontier(&simplex_removals, &simplices_to_remove);

        // 2) Remove canonical incidence as one rollbackable transaction before
        // planning fallback incident repairs. This lets fallback queries see
        // the post-removal incidence view while storage is still available for
        // stale-key validation.
        let incidence_removals = {
            self.journal_incidence_before_write(
                simplex_removals
                    .iter()
                    .flat_map(|(_, vertices)| vertices.iter().copied()),
            );
            self.remove_simplices_from_vertex_incidence_transactionally(&simplex_removals)?
        };

        let incident_updates = match self.plan_incident_simplex_repairs(
            &affected_vertices,
            &simplices_to_remove,
            &candidate_incident,
        ) {
            Ok(incident_updates) => incident_updates,
            Err(err) => {
                self.rollback_incidence_removals(&incidence_removals);
                return Err(err);
            }
        };

        // 3) Clear neighbor back-references in surviving simplices.
        self.clear_surviving_neighbor_backrefs(&simplex_removals, &simplices_to_remove);

        // 4) Remove the simplices and update UUID mappings.
        let removed_count = self.remove_simplices_and_update_uuid_mappings(&simplex_removals);
        if removed_count == 0 {
            return Ok(0);
        }

        // 5) Apply the precomputed `incident_simplex` repairs.
        self.apply_incident_simplex_updates(incident_updates);

        // Bump generation once for all removals (neighbors + incidence + simplex storage).
        self.bump_generation();

        Ok(removed_count)
    }

    /// Removes requested simplices from the incidence index as one transaction.
    ///
    /// The public removal contract requires failures to leave caller-visible TDS
    /// storage untouched. This helper performs the incidence phase before
    /// simplex storage deletion and returns exact rollback records so later
    /// repair-planning failures can restore every touched vertex buffer.
    fn remove_simplices_from_vertex_incidence_transactionally(
        &mut self,
        simplex_removals: &[SimplexRemovalRecord],
    ) -> Result<SimplexIncidenceRemovalRecords, TdsMutationError> {
        let mut incidence_removals = SimplexIncidenceRemovalRecords::new();
        for (simplex_key, vertices) in simplex_removals {
            match self
                .vertex_to_simplices
                .remove_simplex(*simplex_key, vertices)
            {
                Ok(removal) => incidence_removals.push(removal),
                Err(source) => {
                    for removal in incidence_removals.iter().rev() {
                        self.vertex_to_simplices.rollback_removed_simplex(removal);
                    }
                    return Err(source.into());
                }
            }
        }

        Ok(incidence_removals)
    }

    /// Restores a successful incidence-removal transaction after later
    /// read-only planning discovers stale canonical incidence.
    fn rollback_incidence_removals(&mut self, incidence_removals: &SimplexIncidenceRemovalRecords) {
        for removal in incidence_removals.iter().rev() {
            self.vertex_to_simplices.rollback_removed_simplex(removal);
        }
    }

    /// Collects live simplex removals and their vertex keys for a batch request.
    ///
    /// Missing simplex keys and duplicate request keys are ignored to preserve
    /// the historical `remove_simplices_by_keys` no-op behavior for stale keys
    /// and make removal idempotent over the requested key set. The collected
    /// vertex buffers are the proof used by the incidence transaction and later
    /// storage removal phases.
    fn collect_existing_simplex_removals(
        &self,
        simplex_keys: &[SimplexKey],
    ) -> SimplexRemovalRecords {
        let mut seen_large = (simplex_keys.len() > CLEANUP_OPERATION_BUFFER_SIZE)
            .then(|| fast_hash_set_with_capacity(simplex_keys.len()));
        let mut simplex_removals = SimplexRemovalRecords::new();

        for &simplex_key in simplex_keys {
            let duplicate = seen_large.as_mut().map_or_else(
                || {
                    simplex_removals
                        .iter()
                        .any(|(removed_key, _)| *removed_key == simplex_key)
                },
                |seen| !seen.insert(simplex_key),
            );

            if duplicate {
                continue;
            }

            let Some(simplex) = self.simplices.get(simplex_key) else {
                continue;
            };

            let vertices = simplex.vertices().iter().copied().collect();
            simplex_removals.push((simplex_key, vertices));
        }

        simplex_removals
    }

    /// Captures affected vertices and surviving incident-simplex candidates
    /// around a removal batch while removed neighbor pointers are still readable.
    fn collect_incident_repair_frontier(
        &self,
        simplex_removals: &[SimplexRemovalRecord],
        simplices_to_remove: &RemovedSimplexMembership<'_>,
    ) -> (AffectedVertexRecords, CandidateIncidentRecords) {
        let expected_vertices = simplex_removals.len().saturating_mul(D.saturating_add(1));
        let mut affected_vertices = AffectedVertexRecords::with_expected_len(expected_vertices);
        let mut candidate_incident = CandidateIncidentRecords::with_expected_len(expected_vertices);

        for (simplex_key, vertices) in simplex_removals {
            for &vertex_key in vertices {
                affected_vertices.insert(vertex_key);
            }

            let Some(simplex) = self.simplices.get(*simplex_key) else {
                continue;
            };

            if let Some(simplex_neighbors) = simplex.neighbor_keys() {
                for (facet_idx, neighbor_key_opt) in simplex_neighbors.enumerate() {
                    let Some(neighbor_key) = neighbor_key_opt else {
                        continue;
                    };

                    if simplices_to_remove.contains(neighbor_key) {
                        continue;
                    }

                    // The neighbor across facet_idx shares the facet consisting
                    // of all vertices except vertices[facet_idx].
                    for (vertex_index, &vkey) in vertices.iter().enumerate() {
                        if vertex_index == facet_idx {
                            continue;
                        }
                        candidate_incident.insert_if_absent(vkey, neighbor_key);
                    }
                }
            }
        }

        (affected_vertices, candidate_incident)
    }

    /// Clears neighbor back-references in surviving simplices after incidence
    /// removal has succeeded.
    fn clear_surviving_neighbor_backrefs(
        &mut self,
        simplex_removals: &[SimplexRemovalRecord],
        simplices_to_remove: &RemovedSimplexMembership<'_>,
    ) {
        for (simplex_key, _) in simplex_removals {
            let Some(simplex) = self.simplices.get(*simplex_key) else {
                continue;
            };

            let mut neighbors: SmallBuffer<Option<SimplexKey>, MAX_PRACTICAL_DIMENSION_SIZE> =
                SmallBuffer::new();
            if let Some(simplex_neighbors) = simplex.neighbor_keys() {
                neighbors.extend(simplex_neighbors);
            }

            for neighbor_key in neighbors.into_iter().flatten() {
                if simplices_to_remove.contains(neighbor_key) {
                    continue; // neighbor is also being removed
                }

                self.journal_simplex_before_write(neighbor_key);
                let Some(neighbor_simplex) = self.simplices.get_mut(neighbor_key) else {
                    continue;
                };
                let Some(neighbors_buf) = neighbor_simplex.neighbor_slots_mut() else {
                    continue;
                };

                // Clear the back-reference in the neighbor simplex's neighbor buffer.
                for slot in neighbors_buf.iter_mut() {
                    if slot.simplex_key() == Some(*simplex_key) {
                        *slot = NeighborSlot::Boundary;
                    }
                }
            }
        }
    }

    /// Deletes simplex storage after the incidence transaction has succeeded.
    ///
    /// This phase is intentionally infallible with respect to incidence: all
    /// fallible relation updates happened before any simplex or UUID mapping is
    /// removed, so failed batches can leave storage and generation untouched.
    fn remove_simplices_and_update_uuid_mappings(
        &mut self,
        simplex_removals: &[SimplexRemovalRecord],
    ) -> usize {
        let mut removed_count = 0;

        for (simplex_key, _) in simplex_removals {
            if let Some(removed_uuid) = self.remove_simplex_storage_transactionally(*simplex_key) {
                self.uuid_to_simplex_key.remove(&removed_uuid);
                removed_count += 1;
            }
        }

        removed_count
    }

    /// Plans vertex `incident_simplex` repairs after canonical incidence removal.
    ///
    /// Keeping this phase read-only lets stale incidence be detected before any
    /// vertex fields are rewritten. If planning fails, the caller can roll back
    /// the incidence transaction and preserve the public removal atomicity
    /// contract.
    fn plan_incident_simplex_repairs(
        &self,
        affected_vertices: &AffectedVertexRecords,
        simplices_to_remove: &RemovedSimplexMembership<'_>,
        candidate_incident: &CandidateIncidentRecords,
    ) -> Result<IncidentSimplexUpdates, TdsMutationError> {
        let mut incident_updates = IncidentSimplexUpdates::with_capacity(affected_vertices.len());

        affected_vertices.try_for_each(|vk| {
            if let Some(update) =
                self.incident_simplex_repair_update(vk, simplices_to_remove, candidate_incident)?
            {
                incident_updates.push(update);
            }
            Ok::<(), TdsMutationError>(())
        })?;

        Ok(incident_updates)
    }

    /// Applies prevalidated `incident_simplex` replacements for affected vertices.
    ///
    /// All fallible checks happen in [`Self::plan_incident_simplex_repairs`],
    /// so this write phase can remain small and infallible.
    fn apply_incident_simplex_updates(&mut self, incident_updates: IncidentSimplexUpdates) {
        for (vk, new_incident) in incident_updates {
            self.journal_vertex_before_write(vk);
            if let Some(vertex) = self.vertices.get_mut(vk) {
                vertex.set_incident_simplex(new_incident);
            }
        }
    }

    /// Computes the replacement `incident_simplex` for one affected vertex.
    ///
    /// Separating this read-only phase from the later vertex writes lets removal
    /// repair use borrowed incidence and simplex storage without aliasing
    /// mutable vertex access.
    fn incident_simplex_repair_update(
        &self,
        vertex_key: VertexKey,
        simplices_to_remove: &RemovedSimplexMembership<'_>,
        candidate_incident: &CandidateIncidentRecords,
    ) -> Result<Option<(VertexKey, Option<SimplexKey>)>, TdsMutationError> {
        let vertex = self
            .vertices
            .get(vertex_key)
            .ok_or_else(|| TdsError::VertexNotFound {
                vertex_key,
                context: "simplex-removal incident repair planning".to_string(),
            })?;

        let needs_repair = vertex.incident_simplex().is_none_or(|simplex_key| {
            simplices_to_remove.contains(simplex_key) || !self.simplices.contains_key(simplex_key)
        });

        if !needs_repair {
            return Ok(None);
        }

        // Prefer a candidate simplex discovered on the boundary of the removed region.
        let mut new_incident = candidate_incident.get(vertex_key).filter(|&simplex_key| {
            self.simplices
                .get(simplex_key)
                .is_some_and(|simplex| simplex.contains_vertex(vertex_key))
        });

        // Conservative fallback: pick the first remaining simplex that contains this vertex.
        // This is only hit if neighbor pointers were missing or the boundary had no surviving simplex.
        if new_incident.is_none() {
            new_incident =
                self.valid_surviving_incident_simplex(vertex_key, simplices_to_remove)?;
        }

        Ok(Some((vertex_key, new_incident)))
    }

    /// Finds one surviving incident simplex and validates canonical incidence.
    ///
    /// Returning a typed error for dangling or misaligned incidence prevents
    /// simplex removal from silently repairing through corrupted topology.
    fn valid_surviving_incident_simplex(
        &self,
        vertex_key: VertexKey,
        simplices_to_remove: &RemovedSimplexMembership<'_>,
    ) -> Result<Option<SimplexKey>, TdsMutationError> {
        if !self.vertices.contains_key(vertex_key) {
            return Err(TdsError::VertexNotFound {
                vertex_key,
                context: "simplex-removal incident repair planning".to_string(),
            }
            .into());
        }

        let Some(simplex_key) = self.first_simplex_containing_vertex(vertex_key) else {
            return Ok(None);
        };

        if simplices_to_remove.contains(simplex_key) {
            return Err(TdsError::RemovedSimplexStillIncident {
                vertex_key,
                simplex_key,
            }
            .into());
        }

        let Some(simplex) = self.simplices.get(simplex_key) else {
            return Err(TdsError::SimplexNotFound {
                simplex_key,
                context: format!("vertex-to-simplices repair planning for vertex {vertex_key:?}"),
            }
            .into());
        };

        if !simplex.contains_vertex(vertex_key) {
            return Err(TdsError::VertexIncidenceMismatch {
                vertex_key,
                simplex_key,
            }
            .into());
        }

        Ok(Some(simplex_key))
    }

    pub(crate) fn remove_vertex(
        &mut self,
        vertex_key: VertexKey,
    ) -> Result<usize, TdsMutationError> {
        // Look up the vertex to get its UUID before removal
        let Some(vertex) = self.vertex(vertex_key) else {
            return Ok(0); // Vertex not found, nothing to remove
        };
        let uuid = vertex.uuid();

        // Find all simplices containing this vertex.
        let simplices_to_remove: SimplexRemovalBuffer =
            self.simplex_keys_containing_vertex(vertex_key).collect();

        // Remove all simplices containing the vertex.
        //
        // `remove_simplices_by_keys()` clears neighbor back-references that would otherwise dangle and
        // incrementally repairs `incident_simplex` pointers for vertices that referenced removed simplices.
        let simplices_removed = self.remove_simplices_by_keys(&simplices_to_remove)?;

        self.journal_incidence_before_write([vertex_key]);
        self.remove_vertex_incidence(vertex_key)?;

        // Remove the vertex itself.
        self.remove_vertex_storage_transactionally(vertex_key);
        self.uuid_to_vertex_key.remove(&uuid);
        self.refresh_incomplete_construction_state();
        // Topology changed; invalidate caches
        self.bump_generation();

        Ok(simplices_removed)
    }

    /// Remove an isolated vertex (one with no incident simplices) from the TDS.
    ///
    /// This removes only the vertex and its UUID mapping. It does **not** touch
    /// any simplices. If the vertex has an incident simplex, this is a no-op.
    pub(crate) fn remove_isolated_vertex(
        &mut self,
        vertex_key: VertexKey,
    ) -> Result<(), TdsMutationError> {
        let Some(vertex) = self.vertex(vertex_key) else {
            return Ok(());
        };
        // Only remove if truly isolated according to the canonical incidence index.
        if self
            .simplex_keys_containing_vertex(vertex_key)
            .next()
            .is_some()
        {
            return Ok(());
        }
        let uuid = vertex.uuid();
        self.journal_incidence_before_write([vertex_key]);
        self.remove_vertex_incidence(vertex_key)?;
        self.remove_vertex_storage_transactionally(vertex_key);
        self.uuid_to_vertex_key.remove(&uuid);
        self.refresh_incomplete_construction_state();
        self.bump_generation();
        Ok(())
    }

    // =========================================================================
    // KEY-BASED NEIGHBOR OPERATIONS
    // =========================================================================

    fn validate_neighbor_update_matches_facet_incidence(
        &self,
        simplex_key: SimplexKey,
        neighbors: &[Option<SimplexKey>],
    ) -> Result<(), TdsError> {
        let simplex = self
            .simplices
            .get(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: "validate_neighbor_update_matches_facet_incidence".to_string(),
            })?;

        let facet_to_simplices = self.build_facet_to_simplices_map()?;
        for (facet_idx, proposed_neighbor) in neighbors.iter().copied().enumerate() {
            let facet_key = self.facet_key_for_simplex_facet(simplex_key, facet_idx)?;
            let Some(simplex_facet_pairs) = facet_to_simplices.get(&facet_key) else {
                return Err(TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::FacetIncidenceMissing {
                        simplex_key,
                        simplex_uuid: simplex.uuid(),
                        facet_index: facet_idx,
                        facet_key,
                    },
                });
            };

            let expected_neighbor = match simplex_facet_pairs.as_slice() {
                [_] => None,
                [a, b] => {
                    if a.simplex_key() == simplex_key && a.facet_index() as usize == facet_idx {
                        Some(b.simplex_key())
                    } else if b.simplex_key() == simplex_key
                        && b.facet_index() as usize == facet_idx
                    {
                        Some(a.simplex_key())
                    } else {
                        return Err(TdsError::InvalidNeighbors {
                            reason:
                                NeighborValidationError::FacetIncidenceDoesNotReferenceSimplex {
                                    simplex_key,
                                    simplex_uuid: simplex.uuid(),
                                    facet_index: facet_idx,
                                    facet_key,
                                },
                        });
                    }
                }
                _ => {
                    return Err(TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::FacetIncidenceMultiplicity {
                            simplex_key,
                            simplex_uuid: simplex.uuid(),
                            facet_index: facet_idx,
                            facet_key,
                            simplex_count: simplex_facet_pairs.len(),
                        },
                    });
                }
            };

            if proposed_neighbor == Some(simplex_key)
                && expected_neighbor.is_none()
                && Self::allows_periodic_self_neighbor(simplex)
            {
                continue;
            }

            if proposed_neighbor != expected_neighbor {
                return Err(TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::NeighborIncidenceMismatch {
                        simplex_key,
                        simplex_uuid: simplex.uuid(),
                        facet_index: facet_idx,
                        proposed_neighbor,
                        expected_neighbor,
                    },
                });
            }
        }

        Ok(())
    }

    fn set_simplex_neighbors_normalized(
        simplex: &mut Simplex<V, D>,
        neighbors: &[Option<SimplexKey>],
    ) -> Result<(), TdsError> {
        let simplex_id = simplex.uuid();
        simplex
            .set_neighbors_from_keys(neighbors.iter().copied())
            .map_err(|source| TdsError::InvalidSimplex { simplex_id, source })
    }

    fn ensure_neighbor_buffer(
        simplex: &mut Simplex<V, D>,
    ) -> Result<&mut SmallBuffer<NeighborSlot, MAX_PRACTICAL_DIMENSION_SIZE>, TdsError> {
        if simplex.neighbor_slots().is_none() {
            let simplex_id = simplex.uuid();
            simplex
                .set_neighbors_from_keys((0..=D).map(|_| None))
                .map_err(|source| TdsError::InvalidSimplex { simplex_id, source })?;
        }
        let simplex_id = simplex.uuid();
        simplex
            .try_ensure_neighbors_buffer_mut()
            .map_err(|source| TdsError::InvalidSimplex { simplex_id, source })
    }

    fn set_neighbor_slot(
        simplex: &mut Simplex<V, D>,
        facet_idx: usize,
        neighbor: Option<SimplexKey>,
    ) -> Result<(), TdsError> {
        let neighbors = Self::ensure_neighbor_buffer(simplex)?;
        let Some(slot) = neighbors.get_mut(facet_idx) else {
            return Err(TdsError::InvalidNeighbors {
                reason: NeighborValidationError::NeighborSlotOutOfBounds {
                    facet_index: facet_idx,
                    slot_count: neighbors.len(),
                },
            });
        };
        *slot = NeighborSlot::from_neighbor_key(neighbor);
        Ok(())
    }

    fn validate_existing_neighbor_buffer_arity(
        simplex: &Simplex<V, D>,
        context: &str,
    ) -> Result<(), TdsError> {
        if let Some(slots) = simplex.neighbor_slots()
            && slots.len() != D + 1
        {
            return Err(TdsError::InvalidNeighbors {
                reason: NeighborValidationError::LengthMismatch {
                    actual: slots.len(),
                    expected: D + 1,
                    context: context.to_string(),
                },
            });
        }
        Ok(())
    }

    fn reciprocal_neighbor_updates_for_neighbor_update(
        &self,
        simplex_key: SimplexKey,
        neighbors: &[Option<SimplexKey>],
    ) -> Result<Vec<(SimplexKey, usize, Option<SimplexKey>)>, TdsError> {
        let simplex = self
            .simplices
            .get(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: "set_neighbors_by_key".to_string(),
            })?;
        let old_neighbors: Vec<Option<SimplexKey>> = simplex
            .neighbor_keys()
            .map_or_else(|| vec![None; D + 1], Iterator::collect);

        let mut reciprocal_updates = Vec::new();
        self.collect_stale_reciprocal_neighbor_updates(
            simplex_key,
            simplex,
            &old_neighbors,
            neighbors,
            &mut reciprocal_updates,
        )?;
        self.collect_new_reciprocal_neighbor_updates(
            simplex_key,
            simplex,
            neighbors,
            &mut reciprocal_updates,
        )?;
        Ok(reciprocal_updates)
    }

    fn collect_stale_reciprocal_neighbor_updates(
        &self,
        simplex_key: SimplexKey,
        simplex: &Simplex<V, D>,
        old_neighbors: &[Option<SimplexKey>],
        new_neighbors: &[Option<SimplexKey>],
        reciprocal_updates: &mut Vec<(SimplexKey, usize, Option<SimplexKey>)>,
    ) -> Result<(), TdsError> {
        for (facet_idx, old_neighbor_key) in old_neighbors.iter().copied().enumerate() {
            let Some(old_neighbor_key) = old_neighbor_key else {
                continue;
            };
            if old_neighbor_key == simplex_key
                || new_neighbors
                    .iter()
                    .copied()
                    .any(|neighbor_key| neighbor_key == Some(old_neighbor_key))
            {
                continue;
            }

            let old_neighbor_simplex =
                self.simplices
                    .get(old_neighbor_key)
                    .ok_or_else(|| TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::MissingNeighborSimplex {
                            simplex_key,
                            simplex_uuid: simplex.uuid(),
                            facet_index: facet_idx,
                            neighbor_key: old_neighbor_key,
                            context: "clearing stale reciprocal neighbor".to_string(),
                        },
                    })?;
            let mirror_idx = simplex
                .mirror_facet_index(facet_idx, old_neighbor_simplex)
                .ok_or_else(|| TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::MirrorFacetMissing {
                        simplex_uuid: simplex.uuid(),
                        facet_index: facet_idx,
                        neighbor_uuid: old_neighbor_simplex.uuid(),
                        context: "clearing old back-reference".to_string(),
                    },
                })?;
            let back_ref = old_neighbor_simplex.neighbor_key(mirror_idx).flatten();
            if back_ref == Some(simplex_key) {
                reciprocal_updates.push((old_neighbor_key, mirror_idx, None));
            }
        }

        Ok(())
    }

    fn collect_new_reciprocal_neighbor_updates(
        &self,
        simplex_key: SimplexKey,
        simplex: &Simplex<V, D>,
        neighbors: &[Option<SimplexKey>],
        reciprocal_updates: &mut Vec<(SimplexKey, usize, Option<SimplexKey>)>,
    ) -> Result<(), TdsError> {
        for (facet_idx, neighbor_key) in neighbors.iter().copied().enumerate() {
            let Some(neighbor_key) = neighbor_key else {
                continue;
            };
            if neighbor_key == simplex_key {
                continue;
            }

            let neighbor_simplex =
                self.simplices
                    .get(neighbor_key)
                    .ok_or_else(|| TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::MissingNeighborSimplex {
                            simplex_key,
                            simplex_uuid: simplex.uuid(),
                            facet_index: facet_idx,
                            neighbor_key,
                            context: "setting reciprocal neighbor".to_string(),
                        },
                    })?;
            let mirror_idx = simplex
                .mirror_facet_index(facet_idx, neighbor_simplex)
                .ok_or_else(|| TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::MirrorFacetMissing {
                        simplex_uuid: simplex.uuid(),
                        facet_index: facet_idx,
                        neighbor_uuid: neighbor_simplex.uuid(),
                        context: "setting back-reference".to_string(),
                    },
                })?;
            let existing_back_ref = neighbor_simplex.neighbor_key(mirror_idx).flatten();
            if let Some(existing_back_ref) = existing_back_ref
                && existing_back_ref != simplex_key
            {
                return Err(TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::ExistingBackReferenceConflict {
                        neighbor_uuid: neighbor_simplex.uuid(),
                        mirror_index: mirror_idx,
                        existing_back_ref,
                        requested_back_ref: simplex_key,
                    },
                });
            }
            reciprocal_updates.push((neighbor_key, mirror_idx, Some(simplex_key)));
        }

        Ok(())
    }

    /// Stages one locally checked neighbor slot inside an atomic topology edit.
    ///
    /// Cavity replacement and bistellar flips discover reciprocal links one at
    /// a time while both the removed and replacement simplices are temporarily
    /// present. Global facet incidence is therefore not publishable until the
    /// enclosing edit commits. This TDS-owned primitive still rejects missing
    /// simplices, invalid slots, non-periodic self-neighbors, malformed neighbor
    /// buffers, and pairs that do not share the requested facet. The enclosing
    /// topology operation must validate or roll back the completed edit before
    /// returning a proof-bearing TDS.
    pub(in crate::core) fn stage_neighbor_slot_for_topology_candidate(
        &mut self,
        simplex_key: SimplexKey,
        facet_idx: usize,
        requested_neighbor: Option<SimplexKey>,
    ) -> Result<(), TdsMutationError> {
        let simplex = self
            .simplices
            .get(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: "staging a topology-candidate neighbor slot".to_string(),
            })?;
        let simplex_uuid = simplex.uuid();
        let vertex_count = simplex.number_of_vertices();
        if vertex_count != D + 1 {
            return Err(TdsError::DimensionMismatch {
                expected: D + 1,
                actual: vertex_count,
                context: format!("{D}-dimensional simplex vertex count"),
            }
            .into());
        }
        Self::validate_existing_neighbor_buffer_arity(
            simplex,
            "staging a topology-candidate neighbor slot",
        )?;
        if facet_idx >= vertex_count {
            return Err(TdsError::IndexOutOfBounds {
                index: facet_idx,
                bound: vertex_count,
                context: format!("facet slot for simplex {simplex_key:?}"),
            }
            .into());
        }

        if let Some(neighbor_key) = requested_neighbor {
            if neighbor_key == simplex_key && !Self::allows_periodic_self_neighbor(simplex) {
                return Err(TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::NonPeriodicSelfNeighbor {
                        simplex_key,
                        simplex_uuid,
                        facet_index: facet_idx,
                    },
                }
                .into());
            }
            let neighbor =
                self.simplices
                    .get(neighbor_key)
                    .ok_or_else(|| TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::MissingNeighborSimplex {
                            simplex_key,
                            simplex_uuid,
                            facet_index: facet_idx,
                            neighbor_key,
                            context: "staging a topology-candidate neighbor slot".to_string(),
                        },
                    })?;
            let neighbor_vertex_count = neighbor.number_of_vertices();
            if neighbor_vertex_count != D + 1 {
                return Err(TdsError::DimensionMismatch {
                    expected: D + 1,
                    actual: neighbor_vertex_count,
                    context: format!("{D}-dimensional neighbor simplex vertex count"),
                }
                .into());
            }
            Self::validate_existing_neighbor_buffer_arity(
                neighbor,
                "staging a topology-candidate neighbor slot",
            )?;
            if simplex.mirror_facet_index(facet_idx, neighbor).is_none() {
                return Err(TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::MirrorFacetMissing {
                        simplex_uuid,
                        facet_index: facet_idx,
                        neighbor_uuid: neighbor.uuid(),
                        context: "staging a topology-candidate neighbor slot".to_string(),
                    },
                }
                .into());
            }
        }

        self.journal_simplex_before_write(simplex_key);
        let simplex = self
            .simplex_mut(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: "committing a topology-candidate neighbor slot".to_string(),
            })?;
        Self::set_neighbor_slot(simplex, facet_idx, requested_neighbor)?;
        self.bump_generation();
        Ok(())
    }

    /// Sets neighbor relationships using simplex keys directly.
    ///
    /// # Positional Semantics (Critical Topological Invariant)
    ///
    /// **`neighbors[i]` must be the neighbor opposite to `vertices[i]`**
    ///
    /// This means the two simplices share facet `i`, which contains all vertices **except** vertex `i`.
    ///
    /// ## Example: 3D Tetrahedron
    ///
    /// For a simplex with vertices `[v0, v1, v2, v3]`:
    /// - `neighbors[0]` shares facet `[v1, v2, v3]` (opposite v0)
    /// - `neighbors[1]` shares facet `[v0, v2, v3]` (opposite v1)
    /// - `neighbors[2]` shares facet `[v0, v1, v3]` (opposite v2)
    /// - `neighbors[3]` shares facet `[v0, v1, v2]` (opposite v3)
    ///
    /// **This invariant is always validated** via `validate_neighbor_topology()`.
    ///
    /// # Arguments
    ///
    /// * `simplex_key` - The key of the simplex to update
    /// * `neighbors` - The new neighbor keys (must have length D+1)
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if validation fails.
    ///
    /// # Errors
    ///
    /// Returns a `TdsMutationError` if:
    /// - The simplex with the given key doesn't exist
    /// - The neighbor vector length is not D+1
    /// - Any neighbor key references a non-existent simplex
    /// - **The topological invariant is violated** (neighbor\[i\] not opposite vertex\[i\])
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::CoordinateConversionError;
    /// use delaunay::prelude::tds::TdsMutationError;
    /// use delaunay::prelude::triangulation::{
    ///     FastKernel, Triangulation, TriangulationConstructionError,
    /// };
    ///
    /// # #[derive(Debug, thiserror::Error)]
    /// # enum ExampleError {
    /// #     #[error(transparent)]
    /// #     Construction(#[from] TriangulationConstructionError),
    /// #     #[error(transparent)]
    /// #     Mutation(#[from] TdsMutationError),
    /// #     #[error(transparent)]
    /// #     Coordinate(#[from] CoordinateConversionError),
    /// # }
    /// # fn main() -> Result<(), ExampleError> {
    /// let vertices = [
    ///     delaunay::vertex![0.0, 0.0]?,
    ///     delaunay::vertex![1.0, 0.0]?,
    ///     delaunay::vertex![0.0, 1.0]?,
    /// ];
    /// let mut tds =
    ///     Triangulation::<FastKernel<f64>, (), (), 2>::build_initial_simplex(&vertices)?;
    /// let Some(simplex_key) = tds.simplex_keys().next() else {
    ///     return Ok(());
    /// };
    /// let neighbors = vec![None; 3];
    /// tds.set_neighbors_by_key(simplex_key, &neighbors)?;
    /// let Some(simplex) = tds.simplex(simplex_key) else {
    ///     return Ok(());
    /// };
    /// assert!(simplex
    ///     .neighbors()
    ///     .is_some_and(|mut neighbors| neighbors.all(|neighbor| neighbor.is_none())));
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_neighbors_by_key(
        &mut self,
        simplex_key: SimplexKey,
        neighbors: &[Option<SimplexKey>],
    ) -> Result<(), TdsMutationError> {
        // Validate the topological invariant before applying changes
        // (includes length check: neighbors.len() == D+1)
        self.validate_neighbor_topology(simplex_key, neighbors)?;
        self.validate_neighbor_update_matches_facet_incidence(simplex_key, neighbors)?;
        let reciprocal_updates =
            self.reciprocal_neighbor_updates_for_neighbor_update(simplex_key, neighbors)?;

        self.journal_simplex_before_write(simplex_key);
        let simplex_uuid = {
            let simplex =
                self.simplex_mut(simplex_key)
                    .ok_or_else(|| TdsError::SimplexNotFound {
                        simplex_key,
                        context: "set_neighbors_by_key".to_string(),
                    })?;
            let simplex_uuid = simplex.uuid();
            Self::set_simplex_neighbors_normalized(simplex, neighbors)?;
            simplex_uuid
        };

        for (neighbor_key, mirror_idx, back_reference) in reciprocal_updates {
            self.journal_simplex_before_write(neighbor_key);
            let neighbor_simplex =
                self.simplices
                    .get_mut(neighbor_key)
                    .ok_or_else(|| TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::MissingNeighborSimplex {
                            simplex_key,
                            simplex_uuid,
                            facet_index: mirror_idx,
                            neighbor_key,
                            context: "applying reciprocal neighbor update".to_string(),
                        },
                    })?;
            Self::set_neighbor_slot(neighbor_simplex, mirror_idx, back_reference)?;
        }

        // Topology changed; invalidate caches
        self.bump_generation();
        Ok(())
    }

    /// Repairs a complete neighbor buffer from canonical facet incidence.
    ///
    /// Unlike [`Self::set_neighbors_by_key`], this recovery transition does not
    /// require the old reciprocal pointers to be trustworthy. It validates the
    /// proposed buffer against canonical simplex incidence before writing,
    /// removes any stale back-references that can still be resolved, and then
    /// installs the proven reciprocal links. All fallible checks happen before
    /// the first write so a rejected repair leaves the TDS unchanged.
    #[expect(
        clippy::too_many_lines,
        reason = "preflight and commit remain adjacent so neighbor repair cannot write before every facet check succeeds"
    )]
    pub(in crate::core) fn repair_neighbors_by_key_from_facet_incidence(
        &mut self,
        simplex_key: SimplexKey,
        neighbors: &[Option<SimplexKey>],
    ) -> Result<(), TdsMutationError> {
        self.validate_neighbor_topology(simplex_key, neighbors)?;
        self.validate_neighbor_update_matches_facet_incidence(simplex_key, neighbors)?;

        let simplex = self
            .simplices
            .get(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: "repairing neighbors from facet incidence".to_string(),
            })?;
        let simplex_uuid = simplex.uuid();
        let old_neighbors: Vec<Option<SimplexKey>> = simplex
            .neighbor_keys()
            .map_or_else(|| vec![None; D + 1], Iterator::collect);

        let mut stale_back_references = Vec::new();
        for old_neighbor_key in old_neighbors.into_iter().flatten() {
            if old_neighbor_key == simplex_key || neighbors.contains(&Some(old_neighbor_key)) {
                continue;
            }
            let Some(old_neighbor) = self.simplices.get(old_neighbor_key) else {
                continue;
            };
            Self::validate_existing_neighbor_buffer_arity(
                old_neighbor,
                "checking stale reciprocal slots before neighbor repair",
            )?;
            if let Some(old_neighbor_keys) = old_neighbor.neighbor_keys() {
                for (mirror_idx, back_reference) in old_neighbor_keys.enumerate() {
                    if back_reference == Some(simplex_key) {
                        stale_back_references.push((old_neighbor_key, mirror_idx));
                    }
                }
            }
        }

        let mut new_back_references = Vec::new();
        for (facet_idx, neighbor_key) in neighbors.iter().copied().enumerate() {
            let Some(neighbor_key) = neighbor_key else {
                continue;
            };
            if neighbor_key == simplex_key {
                continue;
            }
            let neighbor =
                self.simplices
                    .get(neighbor_key)
                    .ok_or_else(|| TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::MissingNeighborSimplex {
                            simplex_key,
                            simplex_uuid,
                            facet_index: facet_idx,
                            neighbor_key,
                            context: "checking reciprocal slots before neighbor repair".to_string(),
                        },
                    })?;
            Self::validate_existing_neighbor_buffer_arity(
                neighbor,
                "checking reciprocal slots before neighbor repair",
            )?;
            let mirror_idx = simplex
                .mirror_facet_index(facet_idx, neighbor)
                .ok_or_else(|| TdsError::InvalidNeighbors {
                    reason: NeighborValidationError::MirrorFacetMissing {
                        simplex_uuid,
                        facet_index: facet_idx,
                        neighbor_uuid: neighbor.uuid(),
                        context: "checking reciprocal slots before neighbor repair".to_string(),
                    },
                })?;
            new_back_references.push((neighbor_key, mirror_idx));
        }

        self.journal_simplex_before_write(simplex_key);
        let simplex = self
            .simplex_mut(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: "committing neighbor repair".to_string(),
            })?;
        Self::set_simplex_neighbors_normalized(simplex, neighbors)?;
        for (neighbor_key, mirror_idx) in stale_back_references {
            self.journal_simplex_before_write(neighbor_key);
            let neighbor =
                self.simplices
                    .get_mut(neighbor_key)
                    .ok_or_else(|| TdsError::SimplexNotFound {
                        simplex_key: neighbor_key,
                        context: "committing stale reciprocal cleanup".to_string(),
                    })?;
            Self::set_neighbor_slot(neighbor, mirror_idx, None)?;
        }
        for (neighbor_key, mirror_idx) in new_back_references {
            self.journal_simplex_before_write(neighbor_key);
            let neighbor =
                self.simplices
                    .get_mut(neighbor_key)
                    .ok_or_else(|| TdsError::SimplexNotFound {
                        simplex_key: neighbor_key,
                        context: "committing reciprocal neighbor repair".to_string(),
                    })?;
            Self::set_neighbor_slot(neighbor, mirror_idx, Some(simplex_key))?;
        }

        self.bump_generation();
        Ok(())
    }

    /// Assigns incident simplices to vertices in the triangulation.
    ///
    /// This method establishes a mapping from each vertex to one of the simplices that contains it,
    /// which is useful for various geometric queries and traversals. For each an arbitrary
    /// incident simplex is selected from the simplices that contain that vertex.
    ///
    /// Note: Many topology-mutating operations (like [`Tds::remove_simplices_by_keys`](Self::remove_simplices_by_keys))
    /// attempt to repair `incident_simplex` incrementally for affected vertices. This method exists as a
    /// conservative **full rebuild** after bulk changes (deserialization, large repairs, etc.).
    ///
    /// # Returns
    ///
    /// `Ok(())` if incident simplices were successfully assigned to all vertices,
    /// otherwise a `TdsMutationError`.
    ///
    /// # Errors
    ///
    /// Returns a `TdsMutationError` if a simplex references a non-existent vertex key
    /// (`VertexNotFound`).
    ///
    /// # Algorithm
    ///
    /// 1. Build a fresh vertex-to-simplices index from simplex storage
    /// 2. Replace the maintained index only after every referenced vertex key resolves
    /// 3. Set each vertex's optional `incident_simplex` hint from the rebuilt index
    ///
    /// # Performance
    ///
    /// This method rebuilds incidence **globally** by scanning all simplices:
    /// - Time: O(#vertices + #simplices × (D+1))
    /// - Space: O(#vertices + #simplex incidences) for the rebuilt vertex→simplices map
    ///
    /// It is intended for repair/validation paths after bulk topology changes, not as a per-step
    /// hot-path update.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use delaunay::prelude::geometry::CoordinateConversionError;
    /// use delaunay::prelude::tds::TdsMutationError;
    /// use delaunay::prelude::triangulation::{
    ///     FastKernel, Triangulation, TriangulationConstructionError,
    /// };
    ///
    /// # #[derive(Debug, thiserror::Error)]
    /// # enum ExampleError {
    /// #     #[error(transparent)]
    /// #     Construction(#[from] TriangulationConstructionError),
    /// #     #[error(transparent)]
    /// #     Mutation(#[from] TdsMutationError),
    /// #     #[error(transparent)]
    /// #     Coordinate(#[from] CoordinateConversionError),
    /// # }
    /// # fn main() -> Result<(), ExampleError> {
    /// let vertices = [
    ///     delaunay::vertex![0.0, 0.0]?,
    ///     delaunay::vertex![1.0, 0.0]?,
    ///     delaunay::vertex![0.0, 1.0]?,
    /// ];
    /// let mut tds =
    ///     Triangulation::<FastKernel<f64>, (), (), 2>::build_initial_simplex(&vertices)?;
    /// tds.assign_incident_simplices()?;
    /// let all_assigned = tds.vertices().all(|(_, v)| v.incident_simplex().is_some());
    /// assert!(all_assigned);
    /// # Ok(())
    /// # }
    /// ```
    pub fn assign_incident_simplices(&mut self) -> Result<(), TdsMutationError> {
        self.rebuild_vertex_to_simplices_index()?;

        // `incident_simplex` is only a per-vertex hint. The complete incidence
        // relation lives in `vertex_to_simplices`, so derive the hint from that
        // canonical map instead of scanning simplex storage a second time.
        let incident_updates: Vec<_> = self
            .vertices
            .keys()
            .map(|vertex_key| {
                let incident_simplex = self.vertex_to_simplices.simplex_keys(vertex_key).next();
                (vertex_key, incident_simplex)
            })
            .collect();

        for (vertex_key, incident_simplex) in incident_updates {
            self.journal_vertex_before_write(vertex_key);
            if let Some(vertex) = self.vertices.get_mut(vertex_key) {
                vertex.set_incident_simplex(incident_simplex);
            }
        }

        self.bump_generation();
        Ok(())
    }

    /// Updates one derived incident-simplex hint after proving it against canonical incidence.
    ///
    /// Higher-level triangulation algorithms use this instead of borrowing a
    /// mutable [`Vertex`] from TDS storage. The complete incidence relation
    /// remains canonical in `vertex_to_simplices`; this method only publishes a
    /// hint after the named simplex is live, contains the vertex, and appears in
    /// that canonical relation.
    pub(crate) fn set_incident_simplex_hint(
        &mut self,
        vertex_key: VertexKey,
        simplex_key: SimplexKey,
    ) -> Result<(), TdsError> {
        if !self.vertices.contains_key(vertex_key) {
            return Err(TdsError::VertexNotFound {
                vertex_key,
                context: "setting incident-simplex hint".to_string(),
            });
        }

        let simplex = self
            .simplices
            .get(simplex_key)
            .ok_or_else(|| TdsError::SimplexNotFound {
                simplex_key,
                context: format!("incident-simplex hint for vertex {vertex_key:?}"),
            })?;
        if !simplex.contains_vertex(vertex_key)
            || !self
                .vertex_to_simplices
                .simplex_keys(vertex_key)
                .any(|candidate| candidate == simplex_key)
        {
            return Err(TdsError::VertexIncidenceMismatch {
                vertex_key,
                simplex_key,
            });
        }

        self.journal_vertex_before_write(vertex_key);
        let vertex = self
            .vertices
            .get_mut(vertex_key)
            .ok_or_else(|| TdsError::VertexNotFound {
                vertex_key,
                context: "committing incident-simplex hint".to_string(),
            })?;
        vertex.set_incident_simplex(Some(simplex_key));
        Ok(())
    }

    /// Reverses the stored orientation of a checked simplex set.
    ///
    /// This is the narrow TDS-owned primitive used by triangulation-level
    /// geometric orientation repair. It validates every target before the
    /// write phase, swaps vertices together with their aligned neighbor and
    /// periodic-offset slots, and invalidates generation-keyed views exactly
    /// once. Callers must restore coherent relative orientation with
    /// [`Self::normalize_coherent_orientation`] before publishing the enclosing
    /// topology transition.
    pub(crate) fn reverse_simplex_orientations(
        &mut self,
        simplex_keys: &[SimplexKey],
    ) -> Result<(), TdsError> {
        if simplex_keys.is_empty() {
            return Ok(());
        }

        let mut targets = SimplexKeySet::default();
        targets.reserve(simplex_keys.len());
        for &simplex_key in simplex_keys {
            if !targets.insert(simplex_key) {
                continue;
            }
            let simplex =
                self.simplices
                    .get(simplex_key)
                    .ok_or_else(|| TdsError::SimplexNotFound {
                        simplex_key,
                        context: "checking orientation-reversal target".to_string(),
                    })?;
            let vertex_count = simplex.number_of_vertices();
            if vertex_count < 2 {
                return Err(TdsError::DimensionMismatch {
                    expected: 2,
                    actual: vertex_count,
                    context: format!(
                        "simplex {simplex_key:?} needs at least two vertices for orientation reversal"
                    ),
                });
            }
            if vertex_count != D + 1 {
                return Err(TdsError::DimensionMismatch {
                    expected: D + 1,
                    actual: vertex_count,
                    context: format!(
                        "{D}-dimensional orientation-reversal target simplex vertex count"
                    ),
                });
            }
            Self::validate_existing_neighbor_buffer_arity(
                simplex,
                "checking orientation-reversal target",
            )?;
            if let Some(offsets) = simplex.periodic_vertex_offsets()
                && offsets.len() != vertex_count
            {
                return Err(TdsError::InvalidSimplex {
                    simplex_id: simplex.uuid(),
                    source: SimplexValidationError::PeriodicOffsetLengthMismatch {
                        expected: vertex_count,
                        found: offsets.len(),
                    },
                });
            }
        }

        for &simplex_key in &targets {
            self.journal_simplex_before_write(simplex_key);
        }
        for (simplex_key, simplex) in self.simplices.iter_mut() {
            if targets.contains(&simplex_key) {
                simplex.swap_vertex_slots(0, 1);
            }
        }
        self.bump_generation();
        Ok(())
    }

    pub(crate) fn normalize_coherent_orientation(&mut self) -> Result<(), TdsError> {
        let mut flip_assignment: FastHashMap<SimplexKey, bool> =
            fast_hash_map_with_capacity(self.simplices.len());

        for root_simplex_key in self.simplices.keys() {
            if flip_assignment.contains_key(&root_simplex_key) {
                continue;
            }

            flip_assignment.insert(root_simplex_key, false);
            let mut queue = VecDeque::new();
            queue.push_back(root_simplex_key);

            while let Some(simplex_key) = queue.pop_front() {
                let this_flip_state = *flip_assignment.get(&simplex_key).ok_or_else(|| {
                    TdsError::InconsistentDataStructure {
                        message: format!(
                            "Missing flip assignment for simplex {simplex_key:?} during orientation normalization",
                        ),
                    }
                })?;

                let simplex =
                    self.simplices
                        .get(simplex_key)
                        .ok_or_else(|| TdsError::SimplexNotFound {
                            simplex_key,
                            context: "orientation normalization traversal".to_string(),
                        })?;
                let Some(neighbors) = simplex.neighbor_keys() else {
                    continue;
                };

                for (facet_idx, neighbor_key_opt) in neighbors.enumerate() {
                    let Some(neighbor_key) = neighbor_key_opt else {
                        continue;
                    };
                    let neighbor_simplex =
                        self.simplices
                            .get(neighbor_key)
                            .ok_or_else(|| TdsError::SimplexNotFound {
                                simplex_key: neighbor_key,
                                context: format!(
                                    "neighbor of simplex {simplex_key:?} during orientation normalization"
                                ),
                            })?;
                    let mirror_idx = Self::orientation_mirror_facet_index(
                        simplex,
                        facet_idx,
                        neighbor_simplex,
                        "orientation normalization",
                    )?;

                    let (currently_coherent, _, _) = Self::facet_permutation_parity(
                        simplex,
                        facet_idx,
                        neighbor_simplex,
                        mirror_idx,
                    )?;

                    // Flipping exactly one endpoint toggles the coherence state for this edge.
                    let requires_relative_flip = !currently_coherent;
                    let required_neighbor_flip_state = this_flip_state ^ requires_relative_flip;

                    if let Some(existing_neighbor_flip_state) = flip_assignment.get(&neighbor_key) {
                        if *existing_neighbor_flip_state != required_neighbor_flip_state {
                            return Err(TdsError::InconsistentDataStructure {
                                message: format!(
                                    "Contradictory orientation constraints while normalizing simplices {:?} and {:?}",
                                    simplex.uuid(),
                                    neighbor_simplex.uuid(),
                                ),
                            });
                        }
                    } else {
                        flip_assignment.insert(neighbor_key, required_neighbor_flip_state);
                        queue.push_back(neighbor_key);
                    }
                }
            }
        }

        let mut flipped_any = false;
        for (simplex_key, should_flip) in flip_assignment {
            if !should_flip {
                continue;
            }
            self.journal_simplex_before_write(simplex_key);
            let simplex =
                self.simplices
                    .get_mut(simplex_key)
                    .ok_or_else(|| TdsError::SimplexNotFound {
                        simplex_key,
                        context: "applying orientation normalization".to_string(),
                    })?;
            if simplex.number_of_vertices() >= 2 {
                simplex.swap_vertex_slots(0, 1);
                flipped_any = true;
            }
        }
        if flipped_any {
            self.bump_generation();
        }

        Ok(())
    }

    /// Validates coherent orientation for simplices touched by a local mutation.
    ///
    /// This checks every adjacency owned by `simplices`, including adjacencies to
    /// simplices outside the supplied slice. It is intended for insertion and local
    /// repair paths that already know the mutation frontier and want Level-2
    /// orientation safety without a full-TDS traversal.
    pub(crate) fn validate_coherent_orientation_for_simplices(
        &self,
        simplices: &[SimplexKey],
    ) -> Result<(), TdsError> {
        for &simplex_key in simplices {
            let simplex =
                self.simplices
                    .get(simplex_key)
                    .ok_or_else(|| TdsError::SimplexNotFound {
                        simplex_key,
                        context: "local orientation validation scope".to_string(),
                    })?;
            let Some(neighbors) = simplex.neighbor_keys() else {
                continue;
            };

            for (facet_idx, neighbor_key_opt) in neighbors.enumerate() {
                let Some(neighbor_key) = neighbor_key_opt else {
                    continue;
                };
                let neighbor_simplex =
                    self.simplices
                        .get(neighbor_key)
                        .ok_or_else(|| TdsError::SimplexNotFound {
                            simplex_key: neighbor_key,
                            context: format!(
                                "neighbor of simplex {simplex_key:?} during local orientation validation",
                            ),
                        })?;

                let mirror_idx = Self::orientation_mirror_facet_index(
                    simplex,
                    facet_idx,
                    neighbor_simplex,
                    "local orientation validation",
                )?;
                let observed_back_reference = neighbor_simplex.neighbor_key(mirror_idx).flatten();
                if observed_back_reference != Some(simplex_key) {
                    return Err(TdsError::InvalidNeighbors {
                        reason: NeighborValidationError::BackReferenceMismatch {
                            simplex_key,
                            simplex_uuid: simplex.uuid(),
                            facet_index: facet_idx,
                            neighbor_key,
                            neighbor_uuid: neighbor_simplex.uuid(),
                            mirror_index: mirror_idx,
                            observed: observed_back_reference,
                            context: "local orientation validation".to_string(),
                        },
                    });
                }
                let simplex1_facet_vertices =
                    Self::facet_vertices_in_simplex_order(simplex, facet_idx)?;
                let simplex2_facet_vertices =
                    Self::facet_vertices_in_simplex_order(neighbor_simplex, mirror_idx)?;
                let (coherent, observed_odd_permutation, expected_odd_permutation) =
                    Self::facet_permutation_parity(
                        simplex,
                        facet_idx,
                        neighbor_simplex,
                        mirror_idx,
                    )?;
                if !coherent {
                    return Err(TdsError::OrientationViolation {
                        simplex1_key: simplex_key,
                        simplex1_uuid: simplex.uuid(),
                        simplex2_key: neighbor_key,
                        simplex2_uuid: neighbor_simplex.uuid(),
                        simplex1_facet_index: facet_idx,
                        simplex2_facet_index: mirror_idx,
                        facet_vertices: simplex1_facet_vertices.into_iter().collect(),
                        simplex2_facet_vertices: simplex2_facet_vertices.into_iter().collect(),
                        observed_odd_permutation,
                        expected_odd_permutation,
                    });
                }
            }
        }

        Ok(())
    }

    /// Removes duplicate simplices with identical vertex sets.
    ///
    /// Returns the number of duplicate simplices that were removed.
    ///
    /// Duplicate removal runs inside the shared rollback transaction, then the
    /// topology (neighbor relationships and incident simplices) is rebuilt to
    /// maintain data structure invariants and prevent stale references. If the
    /// rebuild or validation fails, the original structure is restored.
    ///
    /// When duplicates are present, the rollback snapshot cost is linear in the
    /// size of the stored topology. The method therefore requires stored
    /// coordinates and payloads to be cloneable so rollback can preserve them.
    ///
    /// # Errors
    ///
    /// Returns a [`TdsMutationError`] if:
    /// - Vertex keys cannot be retrieved for any simplex (data structure corruption)
    /// - Neighbor assignment fails after simplex removal
    /// - Incident simplex assignment fails after simplex removal
    /// - Validation fails after topology rebuild
    ///
    /// # Examples
    ///
    /// ```
    /// use delaunay::prelude::tds::{Tds, TdsMutationError};
    ///
    /// # fn main() -> Result<(), TdsMutationError> {
    /// let mut tds: Tds<(), (), 2> = Tds::empty();
    /// let removed = tds.remove_duplicate_simplices()?;
    /// assert_eq!(removed, 0);
    /// # Ok(())
    /// # }
    /// ```
    pub fn remove_duplicate_simplices(&mut self) -> Result<usize, TdsMutationError>
    where
        U: Clone,
        V: Clone,
    {
        let mut unique_simplices = FastHashMap::default();
        let mut simplices_to_remove = SimplexRemovalBuffer::new();

        for simplex_key in self.simplices.keys() {
            let vertices = self.simplex_vertices(simplex_key)?;
            let vertex_uuid_offsets =
                self.build_periodic_vertex_uuid_offsets(simplex_key, vertices)?;

            match unique_simplices.entry(vertex_uuid_offsets) {
                Entry::Occupied(_) => {
                    simplices_to_remove.push(simplex_key);
                }
                Entry::Vacant(e) => {
                    e.insert(simplex_key);
                }
            }
        }

        let duplicate_count = simplices_to_remove.len();

        if duplicate_count == 0 {
            return Ok(0);
        }

        let mut transaction = TdsRollbackTransaction::begin(self);
        let removed = transaction
            .tds_mut()
            .remove_simplices_by_keys(&simplices_to_remove)?;
        {
            let tds = transaction.tds_mut();
            tds.assign_neighbors().map_err(TdsMutationError::from)?;
            tds.assign_incident_simplices()?;
            tds.is_valid().map_err(TdsMutationError::from)?;
        }
        transaction.commit();
        Ok(removed)
    }
}

impl<U, V, const D: usize> UnverifiedTds<U, V, D> {
    /// Consumes fully assembled draft storage and publishes a verified TDS.
    ///
    /// The compile-time state changes only after cumulative Levels 1–2
    /// validation succeeds, so an incomplete workspace can never escape as the
    /// proof-bearing [`Tds`] specialization.
    pub(in crate::core::tds) fn publish(self) -> Result<Tds<U, V, D>, TdsError> {
        self.publish_recoverable()
            .map_err(|failure| (*failure).into_reason())
    }

    /// Publishes a verified TDS while retaining rejected storage for rollback.
    pub(in crate::core::tds) fn publish_recoverable(
        mut self,
    ) -> Result<Tds<U, V, D>, Box<RefinementError<Self, TdsError>>> {
        let vertex_count = self.number_of_vertices();
        let simplex_count = self.number_of_simplices();
        let is_empty_complex = vertex_count == 0 && simplex_count == 0;
        if !is_empty_complex && simplex_count == 0 {
            return Err(Box::new(RefinementError::new(
                self,
                TdsError::IncompleteConstruction {
                    dimension: D,
                    vertex_count,
                    simplex_count,
                },
            )));
        }

        if let Err(error) = self.validate() {
            return Err(Box::new(RefinementError::new(self, error)));
        }
        self.construction_state = TriangulationConstructionState::Constructed;
        Ok(self.into_verified())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::core::facet::facet_key_from_vertices;
    use crate::core::simplex::Simplex;
    use crate::core::tds::TdsBuilder;
    use crate::core::tds::errors::TriangulationConstructionState;
    use crate::vertex;
    use slotmap::KeyData;
    use std::assert_matches;

    #[test]
    fn publication_rejects_an_incomplete_tds() {
        let mut tds: UnverifiedTds<(), (), 2> = UnverifiedTds::empty_unpublished();
        tds.insert_vertex_with_mapping(vertex![0.0, 0.0].unwrap())
            .unwrap();
        assert_matches!(
            tds.construction_state(),
            TriangulationConstructionState::Incomplete(1)
        );

        let error = tds.publish().unwrap_err();

        assert_matches!(
            error,
            TdsError::IncompleteConstruction {
                dimension: 2,
                vertex_count: 1,
                simplex_count: 0,
            }
        );
    }

    impl<U, V, const D: usize> Tds<U, V, D> {
        /// Inserts a simplex while deliberately bypassing topology safety checks.
        pub(crate) fn insert_simplex_bypassing_topology_checks_for_test(
            &mut self,
            simplex: Simplex<V, D>,
        ) -> Result<SimplexKey, TdsConstructionError> {
            self.insert_simplex_with_mapping_impl(
                simplex,
                SimplexInsertionTopologyCheck::Prechecked,
            )
        }

        /// Clears all neighbor relationships for malformed-state fixtures.
        #[inline]
        pub(crate) fn clear_all_neighbors(&mut self) {
            for simplex in self.simplices.values_mut() {
                simplex.clear_neighbors();
            }
            self.bump_generation();
        }
    }

    // =============================================================================
    // TEST HELPER FUNCTIONS
    // =============================================================================

    fn initial_simplex_vertices_3d() -> [Vertex<(), 3>; 4] {
        [
            vertex!([0.0, 0.0, 0.0]).unwrap(),
            vertex!([1.0, 0.0, 0.0]).unwrap(),
            vertex!([0.0, 1.0, 0.0]).unwrap(),
            vertex!([0.0, 0.0, 1.0]).unwrap(),
        ]
    }

    fn tds_from_specs<U: Copy, V, const D: usize>(
        vertices: &[Vertex<U, D>],
        simplices: &[Vec<usize>],
    ) -> Tds<U, V, D> {
        TdsBuilder::new(vertices, simplices)
            .simplex_data_type::<V>()
            .build()
            .unwrap()
    }

    fn initial_simplex_tds_3d() -> Tds<(), (), 3> {
        let vertices = initial_simplex_vertices_3d();
        tds_from_specs(&vertices, &[vec![0, 1, 2, 3]])
    }

    fn two_tetrahedra_tds_3d() -> Tds<(), (), 3> {
        let vertices = [
            vertex!([0.0, 0.0, 0.0]).unwrap(),
            vertex!([1.0, 0.0, 0.0]).unwrap(),
            vertex!([0.0, 1.0, 0.0]).unwrap(),
            vertex!([0.0, 0.0, 1.0]).unwrap(),
            vertex!([0.5, 0.5, 0.5]).unwrap(),
        ];
        tds_from_specs(&vertices, &[vec![0, 1, 2, 3], vec![4, 1, 2, 3]])
    }

    #[test]
    fn test_assign_neighbors_errors_on_missing_vertex_key() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        let simplex_key = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![a, b, c], None).unwrap())
            .unwrap();

        // Corrupt the simplex by inserting a vertex key that doesn't exist in the TDS.
        let invalid_vkey = VertexKey::from(KeyData::from_ffi(u64::MAX));
        tds.simplex_mut(simplex_key)
            .unwrap()
            .push_vertex_key(invalid_vkey);

        let err = tds.assign_neighbors().unwrap_err();
        assert_eq!(
            err,
            TdsError::VertexNotFound {
                vertex_key: invalid_vkey,
                context: format!(
                    "referenced by simplex {} (key {simplex_key:?}) at position 3",
                    tds.simplex(simplex_key).unwrap().uuid()
                ),
            }
        );
    }

    #[test]
    fn test_assign_neighbors_errors_on_non_manifold_facet_sharing() {
        // Three triangles sharing the same edge (v_a,v_b) is non-manifold in 2D.
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v_a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v_b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v_c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v_d = tds
            .insert_vertex_with_mapping(vertex!([0.0, -1.0]).unwrap())
            .unwrap();
        let v_e = tds
            .insert_vertex_with_mapping(vertex!([2.0, 0.0]).unwrap())
            .unwrap();

        let first = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_a, v_b, v_c], None).unwrap(),
            )
            .unwrap();
        let second = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_a, v_b, v_d], None).unwrap(),
            )
            .unwrap();
        let candidate = tds
            .insert_simplex_bypassing_topology_checks_for_test(
                Simplex::try_new_with_data(vec![v_a, v_b, v_e], None).unwrap(),
            )
            .unwrap();

        let err = tds.assign_neighbors().unwrap_err();
        let candidate_simplex = tds.simplex(candidate).unwrap();
        let candidate_facet_index = candidate_simplex
            .vertices()
            .iter()
            .position(|&vertex_key| vertex_key == v_e)
            .unwrap();
        let facet_key = facet_key_from_vertices(&[v_a, v_b]);
        assert_eq!(
            err,
            TdsError::FacetSharingViolation {
                facet_key,
                existing_incident_count: 2,
                attempted_incident_count: 3,
                max_incident_count: 2,
                candidate_simplex_uuid: candidate_simplex.uuid(),
                candidate_facet_index,
            }
        );
        assert!(tds.contains_simplex(first));
        assert!(tds.contains_simplex(second));
    }

    #[test]
    fn test_remove_simplices_by_keys_empty_is_noop() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let gen_before = tds.generation();
        assert_eq!(tds.remove_simplices_by_keys(&[]).unwrap(), 0);
        assert_eq!(tds.generation(), gen_before);
    }

    #[test]
    fn test_remove_simplices_by_keys_rolls_back_incidence_order_exactly_on_batch_failure() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let shared_vertex = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let kept_vertex_1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let kept_vertex_2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let first_removed_vertex_1 = tds
            .insert_vertex_with_mapping(vertex!([2.0, 0.0]).unwrap())
            .unwrap();
        let first_removed_vertex_2 = tds
            .insert_vertex_with_mapping(vertex!([2.0, 1.0]).unwrap())
            .unwrap();
        let corrupted_vertex = tds
            .insert_vertex_with_mapping(vertex!([3.0, 0.0]).unwrap())
            .unwrap();
        let second_removed_vertex = tds
            .insert_vertex_with_mapping(vertex!([3.0, 1.0]).unwrap())
            .unwrap();

        let kept = tds
            .insert_simplex_bypassing_topology_checks_for_test(
                Simplex::try_new_with_data(vec![shared_vertex, kept_vertex_1, kept_vertex_2], None)
                    .unwrap(),
            )
            .unwrap();
        let first_removed = tds
            .insert_simplex_bypassing_topology_checks_for_test(
                Simplex::try_new_with_data(
                    vec![
                        shared_vertex,
                        first_removed_vertex_1,
                        first_removed_vertex_2,
                    ],
                    None,
                )
                .unwrap(),
            )
            .unwrap();
        let second_removed = tds
            .insert_simplex_bypassing_topology_checks_for_test(
                Simplex::try_new_with_data(
                    vec![shared_vertex, corrupted_vertex, second_removed_vertex],
                    None,
                )
                .unwrap(),
            )
            .unwrap();
        let before = tds
            .vertex_to_simplices_index()
            .simplex_keys(shared_vertex)
            .collect::<Vec<_>>();
        let generation_before = tds.generation();
        assert_eq!(before, vec![kept, first_removed, second_removed]);

        tds.clear_vertex_incidence_for_test(corrupted_vertex);
        let result = tds.remove_simplices_by_keys(&[first_removed, second_removed]);

        assert!(result.is_err());
        assert!(tds.contains_simplex(first_removed));
        assert!(tds.contains_simplex(second_removed));
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(
            tds.vertex_to_simplices_index()
                .simplex_keys(shared_vertex)
                .collect::<Vec<_>>(),
            before
        );
    }

    #[test]
    fn test_remove_simplices_by_keys_clears_neighbor_pointers() {
        // Two triangles sharing an edge.
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let d = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let simplex1 = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![a, b, c], None).unwrap())
            .unwrap();
        let simplex2 = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![b, d, c], None).unwrap())
            .unwrap();

        // Build neighbor pointers based on facet sharing.
        tds.assign_neighbors().unwrap();

        // Sanity: at least one neighbor pointer should exist before removal.
        assert!(
            tds.simplex(simplex1)
                .unwrap()
                .neighbors()
                .is_some_and(|mut n| n.any(|neighbor| neighbor.is_some()))
        );

        let gen_before = tds.generation();
        assert_eq!(tds.remove_simplices_by_keys(&[simplex2]).unwrap(), 1);
        assert_eq!(tds.generation(), gen_before + 1);

        // All remaining neighbor pointers must not reference the removed simplex.
        for (_, simplex) in tds.simplices() {
            if let Some(neighbors) = simplex.neighbors() {
                for neighbor_opt in neighbors {
                    assert_ne!(neighbor_opt, Some(simplex2));
                }
            }
        }
    }

    #[test]
    fn test_remove_simplices_by_keys_errors_before_mutation_on_stale_incidence() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let d = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let stale = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![a, b, c], None).unwrap())
            .unwrap();
        let requested = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![b, d, c], None).unwrap())
            .unwrap();
        let incidence_before = tds
            .vertex_to_simplices_index()
            .simplex_keys(b)
            .collect::<Vec<_>>();
        let generation_before = tds.generation();

        tds.remove_simplex_storage_only_for_test(stale);
        let err = tds.remove_simplices_by_keys(&[requested]).unwrap_err();

        assert_matches!(err.as_tds_error(), TdsError::SimplexNotFound { .. });
        assert!(tds.contains_simplex(requested));
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(
            tds.vertex_to_simplices_index()
                .simplex_keys(b)
                .collect::<Vec<_>>(),
            incidence_before
        );
    }

    #[test]
    fn test_remove_simplices_by_keys_repairs_incident_simplices_for_affected_vertices() {
        // Two triangles sharing an edge (B,C). Remove one and ensure incident_simplex pointers are
        // updated without requiring a full assign_incident_simplices() rebuild.
        let mut tds: Tds<(), (), 2> = Tds::empty();

        let a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let d = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let simplex1 = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![a, b, c], None).unwrap())
            .unwrap();
        let simplex2 = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![b, d, c], None).unwrap())
            .unwrap();

        tds.assign_neighbors().unwrap();

        // Force deterministic incident_simplex pointers that require repair.
        tds.vertex_mut_for_test(a)
            .unwrap()
            .set_incident_simplex(Some(simplex1));
        tds.vertex_mut_for_test(b)
            .unwrap()
            .set_incident_simplex(Some(simplex1));
        tds.vertex_mut_for_test(c)
            .unwrap()
            .set_incident_simplex(Some(simplex1));
        tds.vertex_mut_for_test(d)
            .unwrap()
            .set_incident_simplex(Some(simplex2));

        assert_eq!(tds.remove_simplices_by_keys(&[simplex1]).unwrap(), 1);

        // A is now isolated (no remaining simplices contain it) => incident_simplex must be None.
        assert!(tds.vertex(a).unwrap().incident_simplex().is_none());

        // B, C, D are still in simplex2 => their incident_simplex must be valid and contain them.
        for vk in [b, c, d] {
            let incident = tds
                .vertex(vk)
                .unwrap()
                .incident_simplex()
                .expect("vertex should have an incident simplex after repair");
            assert!(tds.simplices.contains_key(incident));
            let simplex = tds.simplex(incident).unwrap();
            assert!(simplex.contains_vertex(vk));
        }

        // With remaining simplices, isolated vertices are allowed at the TDS structural level.
        assert!(tds.is_valid().is_ok());

        // Neighbor pointers in the surviving simplex must not reference the removed simplex.
        let simplex2_ref = tds.simplex(simplex2).unwrap();
        if let Some(mut neighbors) = simplex2_ref.neighbors() {
            assert!(neighbors.all(|n| n != Some(simplex1)));
        }
    }

    #[test]
    fn test_tds_remove_vertex_returns_zero_when_vertex_not_in_mapping() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let missing_key = VertexKey::from(KeyData::from_ffi(u64::MAX));
        assert_eq!(tds.remove_vertex(missing_key).unwrap(), 0);
    }

    #[test]
    fn test_remove_isolated_vertex_noop_on_missing_key() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let missing = VertexKey::from(KeyData::from_ffi(u64::MAX));
        let gen_before = tds.generation();
        tds.remove_isolated_vertex(missing).unwrap();
        assert_eq!(tds.generation(), gen_before, "No mutation expected");
    }

    #[test]
    fn test_remove_isolated_vertex_uses_canonical_incidence_not_stale_hint() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let vk = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();

        // Manually set a stale incident-simplex hint. Canonical isolation is
        // defined by the maintained vertex→simplices index, not this optional hint.
        let fake_simplex_key = SimplexKey::from(KeyData::from_ffi(1));
        tds.vertex_mut_for_test(vk)
            .unwrap()
            .set_incident_simplex(Some(fake_simplex_key));

        let gen_before = tds.generation();
        tds.remove_isolated_vertex(vk).unwrap();
        assert_eq!(tds.generation(), gen_before + 1);
        assert!(tds.vertex(vk).is_none());
        assert!(!tds.vertex_to_simplices_index().contains_vertex(vk));
    }

    #[test]
    fn test_remove_isolated_vertex_removes_truly_isolated() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let vk = tds
            .insert_vertex_with_mapping(vertex!([1.0, 2.0]).unwrap())
            .unwrap();
        let uuid = tds.vertex(vk).unwrap().uuid();

        // No incident simplex set → truly isolated.
        assert!(tds.vertex(vk).unwrap().incident_simplex().is_none());

        let gen_before = tds.generation();
        tds.remove_isolated_vertex(vk).unwrap();
        assert!(tds.generation() > gen_before);
        assert!(tds.vertex(vk).is_none(), "Vertex should be removed");
        assert!(
            tds.vertex_key_from_uuid(&uuid).is_none(),
            "UUID mapping should be removed"
        );
    }

    #[test]
    fn test_tds_remove_vertex_repairs_neighbors_and_incident_simplices_incrementally() {
        // Two triangles sharing an edge (east,north). Remove the origin (only in simplex1) and ensure:
        // - simplex1 is removed
        // - neighbor back-references in simplex2 are cleared
        // - incident_simplex pointers remain valid for remaining vertices without a full rebuild
        let mut tds: Tds<(), (), 2> = Tds::empty();

        let origin_key = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let east_key = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let north_key = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let diagonal_key = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let simplex1 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![origin_key, east_key, north_key], None).unwrap(),
            )
            .unwrap();
        let simplex2 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![east_key, diagonal_key, north_key], None).unwrap(),
            )
            .unwrap();

        tds.assign_neighbors().unwrap();

        // Seed incident_simplex pointers:
        // - ORIGIN points at simplex1 so star discovery can use the neighbor-walk fast path.
        // - EAST/NORTH point at simplex1 so removal must repair them to simplex2.
        // - DIAGONAL points at simplex2 and should remain valid.
        tds.vertex_mut_for_test(origin_key)
            .unwrap()
            .set_incident_simplex(Some(simplex1));
        tds.vertex_mut_for_test(east_key)
            .unwrap()
            .set_incident_simplex(Some(simplex1));
        tds.vertex_mut_for_test(north_key)
            .unwrap()
            .set_incident_simplex(Some(simplex1));
        tds.vertex_mut_for_test(diagonal_key)
            .unwrap()
            .set_incident_simplex(Some(simplex2));

        let origin_uuid = tds.vertex(origin_key).unwrap().uuid();
        let removed = tds.remove_vertex(origin_key).unwrap();
        assert_eq!(removed, 1);

        // The removed vertex should be gone.
        assert!(tds.vertex_key_from_uuid(&origin_uuid).is_none());
        assert!(tds.vertex(origin_key).is_none());

        // simplex2 should remain and must not reference simplex1 as a neighbor.
        assert!(tds.simplices.contains_key(simplex2));
        let simplex2_ref = tds.simplex(simplex2).unwrap();
        if let Some(mut neighbors) = simplex2_ref.neighbors() {
            assert!(neighbors.all(|n| n != Some(simplex1)));
        }

        // Remaining vertices must have valid incident_simplex pointers (if present).
        for vertex_key in [east_key, north_key, diagonal_key] {
            let v = tds.vertex(vertex_key).unwrap();
            let Some(incident) = v.incident_simplex() else {
                panic!("vertex {vertex_key:?} should have an incident simplex after removal");
            };
            assert!(tds.simplices.contains_key(incident));
            assert!(tds.simplex(incident).unwrap().contains_vertex(vertex_key));
        }
    }

    #[test]
    fn test_set_neighbors_by_key_rejects_non_neighbor_and_wrong_slot() {
        let mut tds: Tds<(), (), 2> = Tds::empty();

        let v_a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v_b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v_c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v_d = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();
        let v_e = tds
            .insert_vertex_with_mapping(vertex!([2.0, 2.0]).unwrap())
            .unwrap();

        let simplex1 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_a, v_b, v_c], None).unwrap(),
            )
            .unwrap();

        // A simplex that shares only one vertex with simplex1 => not a neighbor in 2D.
        let simplex_far = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_a, v_d, v_e], None).unwrap(),
            )
            .unwrap();
        let err = tds
            .set_neighbors_by_key(simplex1, &[Some(simplex_far), None, None])
            .unwrap_err()
            .into_inner();
        assert_matches!(err, TdsError::InvalidNeighbors { .. });

        // A true facet-neighbor (shares {v_a,v_b}) placed at the wrong facet index.
        let simplex2 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_b, v_a, v_d], None).unwrap(),
            )
            .unwrap();
        let err = tds
            .set_neighbors_by_key(simplex1, &[Some(simplex2), None, None])
            .unwrap_err()
            .into_inner();
        assert_matches!(err, TdsError::InvalidNeighbors { .. });
    }

    struct StageNeighborSlotFixture<const D: usize> {
        tds: Tds<(), (), D>,
        simplex_only_vertex: VertexKey,
        neighbor_only_vertex: VertexKey,
        simplex_key: SimplexKey,
        neighbor_key: SimplexKey,
    }

    /// Builds adjacent simplices for neighbor-slot rejection tests.
    fn stage_neighbor_slot_fixture<const D: usize>() -> StageNeighborSlotFixture<D> {
        assert!((2..=5).contains(&D));

        let mut tds: Tds<(), (), D> = Tds::empty();
        let mut shared_vertices = Vec::with_capacity(D);
        for shared_index in 0..D {
            let mut coordinates = [0.0; D];
            if shared_index > 0 {
                coordinates[shared_index - 1] = 1.0;
            }
            shared_vertices.push(
                tds.insert_vertex_with_mapping(vertex!(coordinates).unwrap())
                    .unwrap(),
            );
        }

        let mut simplex_only_coordinates = [0.0; D];
        simplex_only_coordinates[D - 1] = 1.0;
        let simplex_only_vertex = tds
            .insert_vertex_with_mapping(vertex!(simplex_only_coordinates).unwrap())
            .unwrap();
        let mut neighbor_only_coordinates = [0.0; D];
        neighbor_only_coordinates[D - 1] = -1.0;
        let neighbor_only_vertex = tds
            .insert_vertex_with_mapping(vertex!(neighbor_only_coordinates).unwrap())
            .unwrap();

        let mut simplex_vertices = shared_vertices.clone();
        simplex_vertices.push(simplex_only_vertex);
        let simplex_key = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(simplex_vertices, None).unwrap(),
            )
            .unwrap();
        shared_vertices.reverse();
        shared_vertices.push(neighbor_only_vertex);
        let neighbor_key = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(shared_vertices, None).unwrap())
            .unwrap();

        StageNeighborSlotFixture {
            tds,
            simplex_only_vertex,
            neighbor_only_vertex,
            simplex_key,
            neighbor_key,
        }
    }

    fn assert_reverse_simplex_orientations_retains_nested_rollback<const D: usize>() {
        let StageNeighborSlotFixture {
            mut tds,
            simplex_key,
            neighbor_key,
            ..
        } = stage_neighbor_slot_fixture::<D>();
        tds.assign_neighbors().unwrap();
        tds.assign_incident_simplices().unwrap();
        tds.normalize_coherent_orientation().unwrap();
        tds.force_construction_complete_for_test();
        tds.validate().unwrap();
        let before = serde_json::to_value(&tds).unwrap();
        let owner = tds.topology_owner_id();
        let generation = tds.generation();
        let vertex_keys: Vec<_> = tds.vertex_keys().collect();
        let simplex_keys: Vec<_> = tds.simplex_keys().collect();
        let simplex_vertices = tds.simplex(simplex_key).unwrap().vertices().to_vec();

        let outer = tds.begin_rollback_savepoint();
        tds.reverse_simplex_orientations(&[simplex_key, simplex_key])
            .unwrap();
        assert_eq!(tds.generation(), generation + 1);
        let reversed = tds.simplex(simplex_key).unwrap().vertices();
        assert_eq!(reversed[0], simplex_vertices[1]);
        assert_eq!(reversed[1], simplex_vertices[0]);
        assert_eq!(reversed[2..], simplex_vertices[2..]);

        let inner = tds.begin_rollback_savepoint();
        tds.reverse_simplex_orientations(&[neighbor_key]).unwrap();
        tds.commit_savepoint(inner);
        assert_eq!(tds.generation(), generation + 2);
        tds.validate().unwrap();

        tds.rollback_savepoint(outer);
        assert_eq!(tds.topology_owner_id(), owner);
        assert_eq!(tds.generation(), generation);
        assert_eq!(tds.vertex_keys().collect::<Vec<_>>(), vertex_keys);
        assert_eq!(tds.simplex_keys().collect::<Vec<_>>(), simplex_keys);
        assert_eq!(serde_json::to_value(&tds).unwrap(), before);
        tds.validate().unwrap();
    }

    fn assert_reverse_simplex_orientations_rejects_malformed_neighbors_without_mutation<
        const D: usize,
    >() {
        let StageNeighborSlotFixture {
            mut tds,
            simplex_key,
            neighbor_key,
            ..
        } = stage_neighbor_slot_fixture::<D>();
        let neighbor = tds.simplex_mut(neighbor_key).unwrap();
        neighbor
            .set_neighbors_from_keys(vec![None; D + 1])
            .expect("test neighbor buffer should match simplex arity");
        neighbor.neighbor_slots_mut().unwrap().truncate(D);

        let simplex_vertices_before = tds.simplex(simplex_key).unwrap().vertices().to_vec();
        let neighbor_vertices_before = tds.simplex(neighbor_key).unwrap().vertices().to_vec();
        let neighbor_slots_before = tds
            .simplex(neighbor_key)
            .unwrap()
            .neighbor_slots()
            .unwrap()
            .clone();
        let generation = tds.generation();

        let error = tds
            .reverse_simplex_orientations(&[simplex_key, neighbor_key])
            .unwrap_err();

        assert_matches!(
            error,
            TdsError::InvalidNeighbors {
                reason: NeighborValidationError::LengthMismatch {
                    actual,
                    expected,
                    ..
                }
            } if actual == D && expected == D + 1
        );
        assert_eq!(
            tds.simplex(simplex_key).unwrap().vertices(),
            simplex_vertices_before
        );
        assert_eq!(
            tds.simplex(neighbor_key).unwrap().vertices(),
            neighbor_vertices_before
        );
        assert_eq!(
            tds.simplex(neighbor_key).unwrap().neighbor_slots(),
            Some(&neighbor_slots_before)
        );
        assert_eq!(tds.generation(), generation);
    }

    fn assert_reverse_simplex_orientations_rejects_misaligned_offsets_without_mutation<
        const D: usize,
    >() {
        let StageNeighborSlotFixture {
            mut tds,
            simplex_key,
            neighbor_key,
            ..
        } = stage_neighbor_slot_fixture::<D>();
        tds.simplex_mut(neighbor_key)
            .unwrap()
            .periodic_vertex_offsets = Some(vec![[0_i8; D]; D].into());

        let simplex_vertices_before = tds.simplex(simplex_key).unwrap().vertices().to_vec();
        let neighbor_vertices_before = tds.simplex(neighbor_key).unwrap().vertices().to_vec();
        let offsets_before = tds
            .simplex(neighbor_key)
            .unwrap()
            .periodic_vertex_offsets()
            .unwrap()
            .to_vec();
        let generation = tds.generation();

        let error = tds
            .reverse_simplex_orientations(&[simplex_key, neighbor_key])
            .unwrap_err();

        assert_matches!(
            error,
            TdsError::InvalidSimplex {
                source: SimplexValidationError::PeriodicOffsetLengthMismatch {
                    expected,
                    found,
                },
                ..
            } if expected == D + 1 && found == D
        );
        assert_eq!(
            tds.simplex(simplex_key).unwrap().vertices(),
            simplex_vertices_before
        );
        assert_eq!(
            tds.simplex(neighbor_key).unwrap().vertices(),
            neighbor_vertices_before
        );
        assert_eq!(
            tds.simplex(neighbor_key).unwrap().periodic_vertex_offsets(),
            Some(offsets_before.as_slice())
        );
        assert_eq!(tds.generation(), generation);
    }

    fn assert_stage_neighbor_slot_rejects_invalid_candidates_without_mutation<const D: usize>() {
        let StageNeighborSlotFixture {
            mut tds,
            simplex_key,
            neighbor_key,
            ..
        } = stage_neighbor_slot_fixture::<D>();
        let generation = tds.generation();
        let missing_key = SimplexKey::from(KeyData::from_ffi(0xDEAD));

        let error = tds
            .stage_neighbor_slot_for_topology_candidate(missing_key, 0, None)
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::SimplexNotFound { simplex_key, .. } if simplex_key == missing_key
        );

        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, D + 1, None)
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::IndexOutOfBounds {
                index,
                bound,
                ..
            } if index == D + 1 && bound == D + 1
        );

        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, 0, Some(simplex_key))
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::InvalidNeighbors {
                reason: NeighborValidationError::NonPeriodicSelfNeighbor {
                    simplex_key: rejected,
                    facet_index: 0,
                    ..
                }
            } if rejected == simplex_key
        );

        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, 0, Some(missing_key))
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::InvalidNeighbors {
                reason: NeighborValidationError::MissingNeighborSimplex {
                    neighbor_key: missing,
                    facet_index: 0,
                    ..
                }
            } if missing == missing_key
        );

        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, 0, Some(neighbor_key))
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::InvalidNeighbors {
                reason: NeighborValidationError::MirrorFacetMissing { facet_index: 0, .. }
            }
        );
        assert_eq!(tds.generation(), generation);
    }

    fn assert_stage_neighbor_slot_rejects_malformed_simplices_and_buffers_without_mutation<
        const D: usize,
    >() {
        let StageNeighborSlotFixture {
            mut tds,
            simplex_only_vertex,
            neighbor_only_vertex,
            simplex_key,
            neighbor_key,
        } = stage_neighbor_slot_fixture::<D>();
        let generation = tds.generation();

        let simplex = tds.simplex_mut(simplex_key).unwrap();
        simplex
            .set_neighbors_from_keys(vec![None; D + 1])
            .expect("test neighbor buffer should match simplex arity");
        simplex.neighbor_slots_mut().unwrap().truncate(D);
        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, D, Some(neighbor_key))
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::InvalidNeighbors {
                reason: NeighborValidationError::LengthMismatch {
                    actual,
                    expected,
                    ..
                }
            } if actual == D && expected == D + 1
        );

        tds.simplex_mut(simplex_key)
            .unwrap()
            .set_neighbors_from_keys(vec![None; D + 1])
            .expect("test neighbor buffer should match simplex arity");
        let neighbor = tds.simplex_mut(neighbor_key).unwrap();
        neighbor
            .set_neighbors_from_keys(vec![None; D + 1])
            .expect("test neighbor buffer should match simplex arity");
        neighbor.neighbor_slots_mut().unwrap().truncate(D);
        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, D, Some(neighbor_key))
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::InvalidNeighbors {
                reason: NeighborValidationError::LengthMismatch {
                    actual,
                    expected,
                    ..
                }
            } if actual == D && expected == D + 1
        );

        tds.simplex_mut(neighbor_key)
            .unwrap()
            .set_neighbors_from_keys(vec![None; D + 1])
            .expect("test neighbor buffer should match simplex arity");
        tds.simplex_mut(neighbor_key)
            .unwrap()
            .push_vertex_key(simplex_only_vertex);
        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, D, Some(neighbor_key))
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::DimensionMismatch {
                expected,
                actual,
                ..
            } if expected == D + 1 && actual == D + 2
        );

        tds.push_first_simplex_vertex_key_storage_only_for_test(neighbor_only_vertex);
        assert_eq!(
            tds.simplex(simplex_key).unwrap().number_of_vertices(),
            D + 2
        );
        let error = tds
            .stage_neighbor_slot_for_topology_candidate(simplex_key, D, None)
            .unwrap_err()
            .into_inner();
        assert_matches!(
            error,
            TdsError::DimensionMismatch {
                expected,
                actual,
                ..
            } if expected == D + 1 && actual == D + 2
        );
        assert_eq!(tds.generation(), generation);
    }

    macro_rules! generate_stage_neighbor_slot_tests {
        ($($dim:expr),+ $(,)?) => {
            pastey::paste! {
                $(
                    #[test]
                    fn [<reverse_simplex_orientations_retains_nested_rollback_ $dim d>]() {
                        assert_reverse_simplex_orientations_retains_nested_rollback::<$dim>();
                    }

                    #[test]
                    fn [<reverse_simplex_orientations_rejects_malformed_neighbors_without_mutation_ $dim d>]() {
                        assert_reverse_simplex_orientations_rejects_malformed_neighbors_without_mutation::<$dim>();
                    }

                    #[test]
                    fn [<reverse_simplex_orientations_rejects_misaligned_offsets_without_mutation_ $dim d>]() {
                        assert_reverse_simplex_orientations_rejects_misaligned_offsets_without_mutation::<$dim>();
                    }

                    #[test]
                    fn [<stage_neighbor_slot_rejects_invalid_candidates_without_mutation_ $dim d>]() {
                        assert_stage_neighbor_slot_rejects_invalid_candidates_without_mutation::<$dim>();
                    }

                    #[test]
                    fn [<stage_neighbor_slot_rejects_malformed_simplices_and_buffers_without_mutation_ $dim d>]() {
                        assert_stage_neighbor_slot_rejects_malformed_simplices_and_buffers_without_mutation::<$dim>();
                    }
                )+
            }
        };
    }

    generate_stage_neighbor_slot_tests!(2, 3, 4, 5);

    #[test]
    fn test_set_neighbors_by_key_updates_reciprocal_back_reference() {
        let mut tds: Tds<(), (), 2> = Tds::empty();

        let v_a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v_b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v_c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v_d = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let simplex1 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_a, v_b, v_c], None).unwrap(),
            )
            .unwrap();
        let simplex2 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_b, v_a, v_d], None).unwrap(),
            )
            .unwrap();

        tds.set_neighbors_by_key(simplex1, &[None, None, Some(simplex2)])
            .unwrap();

        assert_eq!(
            tds.simplex(simplex1).unwrap().neighbor_key(2).flatten(),
            Some(simplex2)
        );
        assert_eq!(
            tds.simplex(simplex2).unwrap().neighbor_key(2).flatten(),
            Some(simplex1)
        );
        tds.is_valid().unwrap();
    }

    #[test]
    fn test_set_neighbors_by_key_rejects_unpaired_interior_facet() {
        let mut tds: Tds<(), (), 2> = Tds::empty();

        let v_a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v_b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v_c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v_d = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let simplex1 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v_a, v_b, v_c], None).unwrap(),
            )
            .unwrap();
        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v_b, v_a, v_d], None).unwrap(),
        )
        .unwrap();
        tds.assign_neighbors().unwrap();

        let err = tds
            .set_neighbors_by_key(simplex1, &[None, None, None])
            .unwrap_err()
            .into_inner();
        assert_matches!(err, TdsError::InvalidNeighbors { .. });
        assert!(tds.is_valid().is_ok());
    }

    // =============================================================================
    // NEIGHBOR VALIDATION HELPER TESTS
    // =============================================================================

    macro_rules! test_normalize_repairs_incoherent_adjacent_pair {
        ($name:ident, $dim:literal) => {
            #[test]
            fn $name() {
                let mut tds: Tds<(), (), $dim> = Tds::empty();

                let mut vertex_keys = Vec::with_capacity($dim + 2);
                let mut seed = 1.0_f64;
                for idx in 0..($dim + 2) {
                    let mut coords = [0.0_f64; $dim];
                    if idx < $dim {
                        coords[idx] = 1.0;
                    } else {
                        for coord in &mut coords {
                            *coord = seed;
                            seed += 1.0;
                        }
                    }
                    vertex_keys.push(
                        tds.insert_vertex_with_mapping(vertex!(coords).unwrap())
                            .unwrap(),
                    );
                }

                // Construct two adjacent simplices that share a facet but induce the same shared-facet
                // ordering, making orientation incoherent before normalization:
                // simplex1 = [v0..vD], simplex2 = [v0..v(D-1), v(D+1)].
                let simplex1_vertices: Vec<_> =
                    vertex_keys.iter().take($dim + 1).copied().collect();
                let mut simplex2_vertices: Vec<_> =
                    vertex_keys.iter().take($dim).copied().collect();
                simplex2_vertices.push(vertex_keys[$dim + 1]);

                let simplex1: Simplex<(), $dim> =
                    Simplex::try_new_with_data(simplex1_vertices, None).unwrap();
                let simplex2: Simplex<(), $dim> =
                    Simplex::try_new_with_data(simplex2_vertices, None).unwrap();

                tds.insert_simplex_with_mapping(simplex1).unwrap();
                tds.insert_simplex_with_mapping(simplex2).unwrap();
                tds.assign_neighbors().unwrap();

                assert!(!tds.is_coherently_oriented());

                tds.normalize_coherent_orientation().unwrap();
                assert!(tds.is_coherently_oriented());
            }
        };
    }

    test_normalize_repairs_incoherent_adjacent_pair!(
        test_normalize_repairs_incoherent_adjacent_pair_2d,
        2
    );
    test_normalize_repairs_incoherent_adjacent_pair!(
        test_normalize_repairs_incoherent_adjacent_pair_3d,
        3
    );
    test_normalize_repairs_incoherent_adjacent_pair!(
        test_normalize_repairs_incoherent_adjacent_pair_4d,
        4
    );
    test_normalize_repairs_incoherent_adjacent_pair!(
        test_normalize_repairs_incoherent_adjacent_pair_5d,
        5
    );

    #[test]
    fn test_assign_incident_simplices_clears_incident_simplex_when_no_simplices() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let vkey = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();

        // Corrupt incident_simplex and ensure it gets cleared.
        tds.vertex_mut_for_test(vkey)
            .unwrap()
            .set_incident_simplex(Some(SimplexKey::from(KeyData::from_ffi(u64::MAX))));
        assert!(tds.vertex(vkey).unwrap().incident_simplex().is_some());

        tds.assign_incident_simplices().unwrap();
        assert!(tds.vertex(vkey).unwrap().incident_simplex().is_none());
    }

    #[test]
    fn set_incident_simplex_hint_accepts_only_canonical_incidence() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let a = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let b = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let c = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let isolated = tds
            .insert_vertex_with_mapping(vertex!([2.0, 2.0]).unwrap())
            .unwrap();
        let simplex = tds
            .insert_simplex_with_mapping(Simplex::try_new_with_data(vec![a, b, c], None).unwrap())
            .unwrap();

        tds.set_incident_simplex_hint(a, simplex).unwrap();
        assert_eq!(tds.vertex(a).unwrap().incident_simplex(), Some(simplex));

        let error = tds
            .set_incident_simplex_hint(isolated, simplex)
            .unwrap_err();
        assert_matches!(
            error,
            TdsError::VertexIncidenceMismatch {
                vertex_key,
                simplex_key,
            } if vertex_key == isolated && simplex_key == simplex
        );
        assert!(tds.vertex(isolated).unwrap().incident_simplex().is_none());
        tds.validate().unwrap();
    }

    // =========================================================================
    // COHERENT ORIENTATION NORMALIZATION & GENERATION COUNTER
    // =========================================================================

    #[test]
    fn test_normalize_coherent_orientation_produces_coherent_result() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v3 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        // Two triangles sharing edge v1-v2, with deliberately inconsistent vertex order
        let c0 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
            )
            .unwrap();
        let c1 = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v1, v2, v3], None).unwrap(),
            )
            .unwrap();

        // Assign neighbors: shared facet is edge v1-v2.
        // c0[v0,v1,v2]: facet opposite v0 (index 0) = edge [v1,v2] → neighbor c1
        // c1[v1,v2,v3]: facet opposite v3 (index 2) = edge [v1,v2] → neighbor c0
        tds.simplex_mut(c0)
            .unwrap()
            .set_neighbors_from_keys([Some(c1), None, None])
            .unwrap();
        tds.simplex_mut(c1)
            .unwrap()
            .set_neighbors_from_keys([None, None, Some(c0)])
            .unwrap();

        tds.normalize_coherent_orientation().unwrap();
        assert!(tds.is_coherently_oriented());
    }
    #[test]
    fn test_remove_duplicate_simplices_removes_exact_duplicates() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        // Insert the same simplex twice
        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .unwrap();
        tds.insert_simplex_bypassing_topology_checks_for_test(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .unwrap();
        assert_eq!(tds.number_of_simplices(), 2);
        let generation_before = tds.generation();

        let removed = tds.remove_duplicate_simplices().unwrap();
        assert_eq!(removed, 1);
        assert_eq!(tds.number_of_simplices(), 1);
        assert!(tds.generation() > generation_before);
        assert!(tds.is_valid().is_ok());
    }

    #[test]
    fn test_remove_duplicate_simplices_noop_when_no_duplicates() {
        let mut tds = initial_simplex_tds_3d();
        let generation_before = tds.generation();

        let removed = tds.remove_duplicate_simplices().unwrap();
        assert_eq!(removed, 0);
        assert_eq!(tds.generation(), generation_before);
        assert!(tds.is_valid().is_ok());
    }

    #[test]
    fn test_remove_duplicate_simplices_rolls_back_when_rebuild_fails() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v3 = tds
            .insert_vertex_with_mapping(vertex!([0.0, -1.0]).unwrap())
            .unwrap();
        let v4 = tds
            .insert_vertex_with_mapping(vertex!([0.5, -0.5]).unwrap())
            .unwrap();

        // Three distinct triangles share edge v0-v1, so global neighbor
        // assignment will reject the complex after duplicate removal starts.
        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .unwrap();
        tds.insert_simplex_bypassing_topology_checks_for_test(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .unwrap();
        tds.insert_simplex_bypassing_topology_checks_for_test(
            Simplex::try_new_with_data(vec![v0, v1, v3], None).unwrap(),
        )
        .unwrap();
        let oversharing_candidate_key = tds
            .insert_simplex_bypassing_topology_checks_for_test(
                Simplex::try_new_with_data(vec![v0, v1, v4], None).unwrap(),
            )
            .unwrap();
        let oversharing_candidate = tds.simplex(oversharing_candidate_key).unwrap();
        let expected_candidate_uuid = oversharing_candidate.uuid();
        let expected_facet_key = Tds::<(), (), 2>::periodic_facet_key_from_simplex_vertices(
            oversharing_candidate,
            oversharing_candidate.vertices(),
            2,
        )
        .unwrap();
        let before = tds.clone();
        let generation_before = tds.generation();

        let error = tds.remove_duplicate_simplices().unwrap_err();

        assert_eq!(
            error.into_inner(),
            TdsError::FacetSharingViolation {
                facet_key: expected_facet_key,
                existing_incident_count: 2,
                attempted_incident_count: 3,
                max_incident_count: 2,
                candidate_simplex_uuid: expected_candidate_uuid,
                candidate_facet_index: 2,
            }
        );
        assert_eq!(tds.number_of_simplices(), 4);
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(tds, before);
    }

    #[test]
    fn test_clear_all_neighbors_and_rebuild() {
        // Use 5 vertices so there are multiple simplices with actual neighbor pointers
        let mut tds = two_tetrahedra_tds_3d();
        assert!(tds.number_of_simplices() > 1);

        // Multi-simplex: simplices that share facets have Some(neighbor) entries
        let has_any_neighbor = tds.simplices().any(|(_, simplex)| {
            simplex
                .neighbors()
                .is_some_and(|mut nb| nb.any(|neighbor| neighbor.is_some()))
        });
        assert!(has_any_neighbor);

        tds.clear_all_neighbors();

        // After clearing, no simplex should have neighbors
        for (_, simplex) in tds.simplices() {
            assert!(simplex.neighbors().is_none());
        }
    }

    // =========================================================================
    // INSERT SIMPLEX WITH MAPPING: ERROR PATHS
    // =========================================================================

    #[test]
    fn test_insert_simplex_with_mapping_registers_uuid_mapping() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        let simplex = Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap();
        let simplex_uuid = simplex.uuid();
        let ck = tds.insert_simplex_with_mapping(simplex).unwrap();

        // UUID mapping should resolve back to the same key.
        assert_eq!(tds.simplex_key_from_uuid(&simplex_uuid), Some(ck));
        assert_eq!(tds.number_of_simplices(), 1);
    }

    #[test]
    fn test_insert_simplex_with_mapping_rejects_missing_vertex() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        // Use a stale key that doesn't exist in the TDS.
        let stale = VertexKey::from(KeyData::from_ffi(0xDEAD));

        let simplex = Simplex::try_new_with_data(vec![v0, v1, stale], None).unwrap();
        let err = tds.insert_simplex_with_mapping(simplex).unwrap_err();
        assert_matches!(
            err,
            TdsConstructionError::ValidationError {
                source: TdsError::VertexNotFound { .. }
            }
        );
    }

    #[test]
    fn test_insert_simplex_with_mapping_trusted_vertices_rejects_missing_vertex() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let stale = VertexKey::from(KeyData::from_ffi(0xDEAD));

        let simplex = Simplex::try_new_with_data(vec![v0, v1, stale], None).unwrap();
        let err = tds
            .insert_simplex_with_mapping_trusted_vertices(simplex)
            .unwrap_err();
        assert_matches!(
            err,
            TdsConstructionError::ValidationError {
                source: TdsError::VertexNotFound { .. }
            }
        );
    }

    #[test]
    fn test_insert_simplex_with_mapping_rejects_duplicate_uuid() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        let simplex_a = Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap();
        let uuid_a = simplex_a.uuid();
        tds.insert_simplex_with_mapping(simplex_a).unwrap();

        // Create a second simplex with the same UUID.
        let simplex_b = Simplex::try_new_with_uuid(vec![v0, v1, v2], uuid_a, None).unwrap();
        let err = tds.insert_simplex_with_mapping(simplex_b).unwrap_err();
        assert_matches!(err, TdsConstructionError::DuplicateUuid { .. });
    }

    #[test]
    fn test_insert_simplex_rejects_candidate_periodic_offset_count_mismatch() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        let mut candidate = Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap();
        let candidate_uuid = candidate.uuid();
        let generation_before = tds.generation();
        candidate.periodic_vertex_offsets = Some(vec![[0_i8, 0_i8], [0_i8, 0_i8]].into());

        let err = tds.insert_simplex_with_mapping(candidate).unwrap_err();

        assert_matches!(
            err,
            TdsConstructionError::ValidationError {
                source: TdsError::DimensionMismatch {
                    expected: 3,
                    actual: 2,
                    ..
                }
            }
        );
        assert_eq!(tds.number_of_simplices(), 0);
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(tds.simplex_key_from_uuid(&candidate_uuid), None);
    }

    #[test]
    fn test_insert_simplex_propagates_existing_periodic_facet_key_error() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v3 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let existing = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
            )
            .unwrap();
        tds.simplex_mut(existing)
            .unwrap()
            .set_periodic_vertex_offsets(vec![[-128_i8, 0_i8], [127_i8, 0_i8], [0_i8, 0_i8]])
            .unwrap();

        let candidate = Simplex::try_new_with_data(vec![v0, v1, v3], None).unwrap();
        let candidate_uuid = candidate.uuid();
        let generation_before = tds.generation();

        let err = tds.insert_simplex_with_mapping(candidate).unwrap_err();

        assert_matches!(
            err,
            TdsConstructionError::ValidationError { source: TdsError::InconsistentDataStructure {
                message
            } } if message.contains("Failed to derive periodic facet key")
        );
        assert_eq!(tds.number_of_simplices(), 1);
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(tds.simplex_key_from_uuid(&candidate_uuid), None);
    }

    #[test]
    fn test_insert_simplex_with_mapping_rejects_duplicate_simplex_without_mutation() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .unwrap();
        let candidate = Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap();
        let candidate_uuid = candidate.uuid();
        let existing_uuid = tds.simplices().next().unwrap().1.uuid();
        let generation_before = tds.generation();

        let err = tds.insert_simplex_with_mapping(candidate).unwrap_err();

        assert_matches!(
            err,
            TdsConstructionError::ValidationError {
                source: TdsError::DuplicateSimplices { simplex_pairs, .. }
            } if simplex_pairs == [[existing_uuid, candidate_uuid]]
        );
        assert_eq!(tds.number_of_simplices(), 1);
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(tds.simplex_key_from_uuid(&candidate_uuid), None);
    }

    #[test]
    fn test_insert_simplex_with_mapping_rejects_third_incident_facet_without_mutation() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v3 = tds
            .insert_vertex_with_mapping(vertex!([0.0, -1.0]).unwrap())
            .unwrap();
        let v4 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .unwrap();
        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v3], None).unwrap(),
        )
        .unwrap();
        let candidate = Simplex::try_new_with_data(vec![v0, v1, v4], None).unwrap();
        let candidate_uuid = candidate.uuid();
        let generation_before = tds.generation();

        let err = tds.insert_simplex_with_mapping(candidate).unwrap_err();

        match err {
            TdsConstructionError::ValidationError {
                source:
                    TdsError::FacetSharingViolation {
                        existing_incident_count,
                        attempted_incident_count,
                        max_incident_count,
                        candidate_simplex_uuid,
                        candidate_facet_index,
                        ..
                    },
            } => {
                assert_eq!(existing_incident_count, 2);
                assert_eq!(attempted_incident_count, 3);
                assert_eq!(max_incident_count, 2);
                assert_eq!(candidate_simplex_uuid, candidate_uuid);
                assert_eq!(candidate_facet_index, 2);
            }
            other => panic!("expected structured facet-sharing violation, got {other:?}"),
        }
        assert_eq!(tds.number_of_simplices(), 2);
        assert_eq!(tds.generation(), generation_before);
        assert_eq!(tds.simplex_key_from_uuid(&candidate_uuid), None);
    }

    /// Verifies removed simplices are absent from subsequent insertion preflight scans.
    #[test]
    fn test_removed_simplices_do_not_block_future_simplex_insertions() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let v3 = tds
            .insert_vertex_with_mapping(vertex!([0.0, -1.0]).unwrap())
            .unwrap();
        let v4 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();

        let removed = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
            )
            .unwrap();
        let second = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v3], None).unwrap(),
            )
            .unwrap();

        assert_eq!(tds.remove_simplices_by_keys(&[removed]).unwrap(), 1);

        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
        )
        .expect("removed duplicate simplex should not block reinsertion");
        assert_eq!(tds.remove_simplices_by_keys(&[second]).unwrap(), 1);
        tds.insert_simplex_with_mapping(
            Simplex::try_new_with_data(vec![v0, v1, v4], None).unwrap(),
        )
        .expect("removed incident simplex should not block later facet sharing");
    }

    // =========================================================================
    // REMOVE SIMPLICES BY KEYS: BATCH REPAIR
    // =========================================================================

    #[test]
    fn test_remove_simplices_by_keys_batch_repairs_incidence_and_neighbors() {
        let mut tds = two_tetrahedra_tds_3d();
        assert!(tds.number_of_simplices() > 1);

        // Remove the first simplex.
        let first_ck = tds.simplex_keys().next().unwrap();
        let removed = tds.remove_simplices_by_keys(&[first_ck]).unwrap();
        assert_eq!(removed, 1);

        // All remaining vertex incident_simplex pointers should be valid.
        for (vk, v) in tds.vertices() {
            if let Some(ic) = v.incident_simplex() {
                assert!(
                    tds.contains_simplex(ic),
                    "Vertex {vk:?} has dangling incident_simplex after batch removal"
                );
            }
        }

        // No surviving simplex should have a neighbor pointer to the removed simplex.
        for (_, simplex) in tds.simplices() {
            if let Some(neighbors) = simplex.neighbors() {
                for nk in neighbors.flatten() {
                    assert_ne!(nk, first_ck, "Dangling neighbor pointer to removed simplex");
                }
            }
        }
    }

    // =========================================================================
    // ASSIGN INCIDENT SIMPLICES: ERROR ON DANGLING VERTEX KEY
    // =========================================================================

    #[test]
    fn test_assign_incident_simplices_errors_on_dangling_vertex_key() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        let _ck = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
            )
            .unwrap();

        // Remove v2 from the vertex storage, leaving the simplex with a dangling reference.
        tds.vertices.remove(v2);
        tds.uuid_to_vertex_key.retain(|_, &mut vk| vk != v2);

        let err = tds.assign_incident_simplices().unwrap_err();
        assert_matches!(err.as_tds_error(), TdsError::VertexNotFound { .. });
    }

    // =========================================================================
    // NORMALIZE COHERENT ORIENTATION: SINGLE SIMPLEX (NO NEIGHBORS)
    // =========================================================================

    #[test]
    fn test_normalize_coherent_orientation_handles_single_simplex() {
        let mut tds = initial_simplex_tds_3d();
        assert_eq!(tds.number_of_simplices(), 1);

        // Single simplex with no neighbors: should succeed without flipping.
        assert!(tds.normalize_coherent_orientation().is_ok());
    }

    #[test]
    fn test_normalize_coherent_orientation_multi_simplex() {
        let mut tds = two_tetrahedra_tds_3d();
        assert!(tds.number_of_simplices() > 1);

        // Should succeed for a valid multi-simplex triangulation.
        assert!(tds.normalize_coherent_orientation().is_ok());
    }

    // =========================================================================
    // REMOVE SIMPLICES BY KEYS
    // =========================================================================

    #[test]
    fn test_remove_simplices_by_keys_returns_zero_for_missing() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let stale = SimplexKey::from(KeyData::from_ffi(0xDEAD));
        assert_eq!(tds.remove_simplices_by_keys(&[stale]).unwrap(), 0);
    }

    #[test]
    fn test_remove_simplices_by_keys_deduplicates_request_keys() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();
        let simplex = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
            )
            .unwrap();

        assert_eq!(
            tds.remove_simplices_by_keys(&[simplex, simplex]).unwrap(),
            1
        );
        assert!(!tds.contains_simplex(simplex));
        assert_eq!(tds.number_of_simplices(), 0);
        assert!(tds.is_valid().is_ok());
    }

    #[test]
    fn test_remove_simplices_by_keys_repairs_local_topology() {
        let mut tds: Tds<(), (), 2> = Tds::empty();
        let v0 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 0.0]).unwrap())
            .unwrap();
        let v1 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 0.0]).unwrap())
            .unwrap();
        let v2 = tds
            .insert_vertex_with_mapping(vertex!([1.0, 1.0]).unwrap())
            .unwrap();
        let v3 = tds
            .insert_vertex_with_mapping(vertex!([0.0, 1.0]).unwrap())
            .unwrap();

        let removed_key = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v1, v2], None).unwrap(),
            )
            .unwrap();
        let surviving_key = tds
            .insert_simplex_with_mapping(
                Simplex::try_new_with_data(vec![v0, v2, v3], None).unwrap(),
            )
            .unwrap();
        tds.assign_neighbors().unwrap();
        tds.assign_incident_simplices().unwrap();

        assert!(
            tds.simplices
                .get(surviving_key)
                .unwrap()
                .neighbors()
                .unwrap()
                .any(|neighbor| neighbor == Some(removed_key))
        );

        let removed_uuid = tds.simplices.get(removed_key).unwrap().uuid();
        let removed_vertices = tds.simplices.get(removed_key).unwrap().vertices().to_vec();

        assert_eq!(tds.remove_simplices_by_keys(&[removed_key]).unwrap(), 1);

        assert_eq!(removed_vertices, vec![v0, v1, v2]);
        assert!(!tds.simplices.contains_key(removed_key));
        assert!(tds.simplices.contains_key(surviving_key));
        assert!(!tds.uuid_to_simplex_key.contains_key(&removed_uuid));
        if let Some(mut neighbors) = tds.simplices.get(surviving_key).unwrap().neighbors() {
            assert!(neighbors.all(|neighbor| neighbor != Some(removed_key)));
        }
        assert_ne!(
            tds.vertices.get(v0).unwrap().incident_simplex(),
            Some(removed_key)
        );
        assert_ne!(
            tds.vertices.get(v1).unwrap().incident_simplex(),
            Some(removed_key)
        );
        assert_ne!(
            tds.vertices.get(v2).unwrap().incident_simplex(),
            Some(removed_key)
        );
        assert_eq!(
            tds.vertices.get(v0).unwrap().incident_simplex(),
            Some(surviving_key)
        );
        assert_eq!(
            tds.vertices.get(v2).unwrap().incident_simplex(),
            Some(surviving_key)
        );
    }

    // =========================================================================
    // SET VERTEX DATA / SET SIMPLEX DATA
    // =========================================================================

    #[test]
    fn test_set_vertex_data_replaces_existing() {
        let vertices: [Vertex<i32, 2>; 3] = [
            vertex!([0.0, 0.0]; data = 10i32).unwrap(),
            vertex!([1.0, 0.0]; data = 20).unwrap(),
            vertex!([0.0, 1.0]; data = 30).unwrap(),
        ];
        let mut tds: Tds<i32, (), 2> = tds_from_specs(&vertices, &[vec![0, 1, 2]]);
        let key = tds.vertex_keys().next().unwrap();

        let prev = tds.set_vertex_data(key, Some(99)).unwrap();
        assert!(prev.is_some()); // had data before
        assert_eq!(tds.vertex(key).unwrap().data, Some(99));
    }

    #[test]
    fn test_set_vertex_data_on_no_data_vertex() {
        // Vertices without data have U = (), so set_vertex_data sets ().
        let vertices = [
            vertex!([0.0, 0.0]).unwrap(),
            vertex!([1.0, 0.0]).unwrap(),
            vertex!([0.0, 1.0]).unwrap(),
        ];
        let mut tds: Tds<(), (), 2> = tds_from_specs(&vertices, &[vec![0, 1, 2]]);
        let key = tds.vertex_keys().next().unwrap();

        let prev = tds.set_vertex_data(key, Some(())).unwrap();
        // Vertices constructed without explicit data have data = None
        assert_eq!(prev, None);
        assert_eq!(tds.vertex(key).unwrap().data, Some(()));
    }

    #[test]
    fn test_set_vertex_data_invalid_key_returns_error() {
        let mut tds: Tds<i32, (), 2> = Tds::empty();
        let stale = VertexKey::from(KeyData::from_ffi(0xDEAD));
        let err = tds.set_vertex_data(stale, Some(1)).unwrap_err();
        assert_matches!(err.as_tds_error(), TdsError::VertexNotFound { .. });
    }

    #[test]
    fn test_set_simplex_data_on_empty_simplex() {
        let vertices = [
            vertex!([0.0, 0.0]).unwrap(),
            vertex!([1.0, 0.0]).unwrap(),
            vertex!([0.0, 1.0]).unwrap(),
        ];
        let mut tds: Tds<(), i32, 2> = tds_from_specs(&vertices, &[vec![0, 1, 2]]);
        let key = tds.simplex_keys().next().unwrap();

        let prev = tds.set_simplex_data(key, Some(42)).unwrap();
        assert_eq!(prev, None); // key found, no previous data
        assert_eq!(tds.simplex(key).unwrap().data, Some(42));
    }

    #[test]
    fn test_set_simplex_data_replaces_existing() {
        let vertices = [
            vertex!([0.0, 0.0]).unwrap(),
            vertex!([1.0, 0.0]).unwrap(),
            vertex!([0.0, 1.0]).unwrap(),
        ];
        let mut tds: Tds<(), i32, 2> = tds_from_specs(&vertices, &[vec![0, 1, 2]]);
        let key = tds.simplex_keys().next().unwrap();

        tds.set_simplex_data(key, Some(1)).unwrap();
        let prev = tds.set_simplex_data(key, Some(2)).unwrap();
        assert_eq!(prev, Some(1));
        assert_eq!(tds.simplex(key).unwrap().data, Some(2));
    }

    #[test]
    fn test_set_simplex_data_invalid_key_returns_error() {
        let mut tds: Tds<(), i32, 2> = Tds::empty();
        let stale = SimplexKey::from(KeyData::from_ffi(0xDEAD));
        let err = tds.set_simplex_data(stale, Some(1)).unwrap_err();
        assert_matches!(err.as_tds_error(), TdsError::SimplexNotFound { .. });
    }
}