fix!: enforce CDT and backend invariants

[acgetchell]

• Build open-boundary simulations from foliated CDT strips and validate regular per-slice configuration before simulation startup.
• Validate topology in CdtTriangulation::with_topology before publishing wrapped backends.
• Make TriangulationMut::clear and reserve_capacity fallible so unsupported or failed backend operations cannot silently succeed.
• Add typed coordinate and reservation errors, and update docs and examples toward foliated CDT constructors.

BREAKING CHANGE: Open-boundary CdtConfig now requires regular slice counts, run_simulation constructs foliated CDT strips instead of seeded or random raw Delaunay inputs, TriangulationMut::clear and reserve_capacity now return Result, and CdtTriangulation::with_topology validates topology before returning.

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.52%. Comparing base (73e1b28) to head (3225000).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/geometry/backends/mock.rs	83.33%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #120      +/-   ##
==========================================
+ Coverage   92.50%   92.52%   +0.02%     
==========================================
  Files          19       19              
  Lines        8557     8661     +104     
==========================================
+ Hits         7916     8014      +98     
- Misses        641      647       +6     

Flag	Coverage Δ
unittests	92.52% <96.66%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 650ee59b-61b3-4e39-9e9e-17a5df3ac903

📥 Commits

Reviewing files that changed from the base of the PR and between 73e1b28 and 3225000.

📒 Files selected for processing (16)

• README.md
• docs/code_organization.md
• docs/testing.md
• examples/basic_cdt.rs
• src/cdt/ergodic_moves.rs
• src/cdt/metropolis.rs
• src/cdt/triangulation.rs
• src/cdt/triangulation/builders.rs
• src/config.rs
• src/geometry/backends/delaunay.rs
• src/geometry/backends/mock.rs
• src/geometry/traits.rs
• src/lib.rs
• tests/cli.rs
• tests/integration_tests.rs
• tests/proptest_metropolis.rs

---

Walkthrough

This PR introduces topology-aware CDT construction and validation, refactoring triangulation creation from seeded/random points to foliated CDT strips. Topology validation moves to constructor time via with_topology, configuration validation becomes topology-specific with distinct rules per topology, and backend storage APIs now return Result. Integration updates include adjusting run_simulation and test fixtures to use the new construction patterns.

Changes

CDT Construction, Topology Validation, and Configuration

Layer / File(s)	Summary
Core Triangulation API src/cdt/triangulation.rs	with_topology() now calls validate_topology() at construction time instead of deferring validation, enabling early rejection of topology mismatches.
Configuration Validation src/config.rs	Unified topology-aware validation: CdtConfig::validate() derives topology-specific minimums (timeslices, per-slice vertices) and enforces divisibility with overflow-safe checks and topology-labeled error messages.
Builder Documentation src/cdt/triangulation/builders.rs	Documentation refactored to describe from_random_points and from_seeded_points as creating unfoliated triangulations with updated examples reflecting lack of foliation.
Rollback and Move Semantics src/cdt/metropolis.rs	apply_accepted_move replaced explicit clone/rollback with counts-based validation: records pre-move counts, relies on kernel rollback on failure, and asserts counts invariant via debug_assert.
Ergodic Moves Tests src/cdt/ergodic_moves.rs	Added topology-mismatch test using wrapper API to validate that toroidal topology assertions fail with correct error when Euler characteristic mismatch occurs.
Integration: Simulation src/lib.rs	run_simulation() for OpenBoundary now constructs triangulations via from_cdt_strip(vertices_per_slice, timeslices) after computing per-slice vertex count; Toroidal path unchanged.
Documentation & Examples README.md, docs/code_organization.md, docs/testing.md, examples/basic_cdt.rs, src/lib.rs	Updated examples and docs to demonstrate from_cdt_strip constructor, foliation validation assertions, and topology-aware dispatch in simulation; added open-boundary test coverage documentation.
Tests & Fixtures tests/integration_tests.rs, tests/proptest_metropolis.rs, tests/cli.rs, src/lib.rs	Updated test fixtures from from_seeded_points(32, 3, ...) to from_cdt_strip and adjusted vertex counts (32→36, 10→12) to align with new topology validation minimums; added foliation, causality, and cell classification validations.

Backend Storage Mutation API Refactoring

Layer / File(s)	Summary
Trait Definition src/geometry/traits.rs	TriangulationMut trait methods clear() and reserve_capacity() now return Result<(), Self::Error> with comprehensive documentation and usage examples.
Delaunay Backend src/geometry/backends/delaunay.rs	Implemented Result-returning clear() and reserve_capacity() returning NotImplemented errors; added NonFiniteCoordinate error variant and validation in build_vertex to reject NaN/infinite coordinates.
Mock Backend src/geometry/backends/mock.rs	Implemented Result-returning clear() (resets storage) and reserve_capacity() (uses try_reserve, maps failures to new ReservationFailed error with operation/capacity context).
Public API src/lib.rs	Added MockError re-export to prelude geometry module alongside MockBackend.
Tests & Integration src/geometry/backends/*.rs, src/lib.rs	Added finite-coordinate validation test and storage mutation error-handling tests; updated call sites to use .expect() on new Result returns.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• acgetchell/causal-triangulations#119: This PR introduces the from_cdt_strip and from_toroidal_cdt builders, foliation/volume-profile APIs, and corresponding run_simulation plumbing that this PR directly integrates and updates.
• acgetchell/causal-triangulations#92: Both PRs modify topology-aware construction and validation paths (run_simulation dispatch, CdtConfig topology validation, CdtTriangulation topology/validation behavior).
• acgetchell/causal-triangulations#78: Both PRs modify the Metropolis implementation; this PR updates rollback semantics in apply_accepted_move and doc examples, directly overlapping with code paths.

Poem

🐰 A rabbit hops through topology's maze,
Validates each fold at construction's phase,
CDT strips unfold in slices neat,
Storage swaps returns—now error-complete!
Configuration rules split clean and true,
From chaos builds causality anew.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix!: enforce CDT and backend invariants' accurately summarizes the main changes: validation of CDT topology, backend operations made fallible, and invariant enforcement.
Description check	✅ Passed	The description is directly related to the changeset, detailing four key changes: foliated CDT strip construction, topology validation, fallible backend operations, and error typing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/foliated-cdt-defaults

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔴 Performance Regression Detected

Performance Analysis Report

CDT Performance Analysis Report

Generated: 2026-05-06T19:21:34+00:00

Summary

• Total benchmarks: 44
• Regressions: 34
• Improvements: 3
• Stable: 2
• New benchmarks: 5
• Average change: 18.5%
• Median change: 16.7%

🔴 Performance Regressions

Benchmark	Change	Current	Baseline	Ratio
ergodic_moves/move/Move13Add	+45.8%	9.8µs	6.7µs	1.46x
ergodic_moves/move/Move31Remove	+45.2%	8.9µs	6.1µs	1.45x
edge_counting/uncached/50	+42.2%	2.3µs	1.6µs	1.42x
ergodic_moves/random_move_attempt	+41.4%	9.8µs	6.9µs	1.41x
ergodic_moves/move/Move22	+41.1%	9.9µs	7.0µs	1.41x
ergodic_moves/move/EdgeFlip	+39.8%	9.8µs	7.0µs	1.40x
edge_counting/uncached/25	+37.7%	1.0µs	755.2ns	1.38x
edge_counting/uncached/100	+34.1%	4.5µs	3.4µs	1.34x
geometry_queries/euler_characteristic	+33.6%	2.2µs	1.7µs	1.34x
edge_counting/uncached/200	+31.1%	9.3µs	7.1µs	1.31x
metropolis_simulation/metropolis_steps/100	+26.7%	12.0ms	9.5ms	1.27x
edge_counting/uncached/10	+26.6%	364.0ns	287.6ns	1.27x
metropolis_simulation/metropolis_steps/50	+25.9%	4.7ms	3.7ms	1.26x
action_calculations/calculate_action/50	+24.0%	6.1ns	4.9ns	1.24x
triangulation_creation/delaunay_backend/5	+23.5%	70.7µs	57.3µs	1.24x
action_calculations/calculate_action/10	+23.2%	6.1ns	4.9ns	1.23x
metropolis_simulation/metropolis_steps/10	+22.3%	1.9ms	1.6ms	1.22x
action_calculations/calculate_action/100	+19.8%	5.9ns	4.9ns	1.20x
triangulation_creation/delaunay_backend/10	+19.7%	383.5µs	320.4µs	1.20x
triangulation_creation/delaunay_backend/100	+16.7%	33.1ms	28.4ms	1.17x
triangulation_creation/delaunay_backend/20	+16.6%	1.6ms	1.3ms	1.17x
geometry_queries/is_valid	+16.2%	288.5µs	248.3µs	1.16x
cache_operations/refresh_cache	+15.7%	9.0ms	7.8ms	1.16x
triangulation_creation/delaunay_backend/50	+15.6%	8.9ms	7.7ms	1.16x
geometry_queries/vertex_count	+14.9%	0.6ns	0.5ns	1.15x
ergodic_moves/random_move_selection	+14.5%	79.0ns	69.0ns	1.15x
simulation_analysis/average_action	+14.5%	2.8ns	2.5ns	1.15x
edge_counting/cached/25	+14.4%	0.6ns	0.5ns	1.14x
edge_counting/cached/50	+14.3%	0.6ns	0.5ns	1.14x
edge_counting/cached/100	+14.1%	0.6ns	0.5ns	1.14x
edge_counting/cached/10	+14.1%	0.6ns	0.5ns	1.14x
edge_counting/cached/200	+14.1%	0.6ns	0.5ns	1.14x
geometry_queries/face_count	+14.0%	0.6ns	0.5ns	1.14x
validation/validate	+13.6%	371.0µs	326.4µs	1.14x

🟢 Performance Improvements

Benchmark	Change	Current	Baseline	Ratio
geometry_queries/iterate_vertices	-47.3%	64.2ns	121.8ns	1.90x
geometry_queries/iterate_faces	-45.4%	105.0ns	192.4ns	1.83x
simulation_analysis/equilibrium_measurements	-10.4%	23.8ns	26.6ns	1.12x

🆕 New Benchmarks

• cache_operations/metadata_cache_invalidation: 155.9ns
• simulation_analysis/hausdorff_dimension_estimate: 7.8µs
• simulation_analysis/average_volume_profile: 71.2ns
• simulation_analysis/volume_fluctuations: 122.2ns
• simulation_analysis/spectral_dimension_estimate: 52.3µs

✅ Stable Benchmarks

No significant changes detected in 2 benchmarks.

⚠️ This PR introduces performance regressions that exceed the threshold. Please review the changes.

---

Performance analysis powered by Criterion.rs