feat!(cdt): add dimensional observables

AGENTS.md

@@ -12,7 +12,7 @@ Before modifying code, agents MUST read:
 
 - `AGENTS.md` (this file)
 - **All files in `docs/dev/*.md`** – repository development rules
-- `docs/project.md` – module layout and architecture
+- `docs/code_organization.md` – module layout and architecture
 
 The `docs/dev/` directory contains the authoritative development guidance for this repository. Agents must load every file in that directory before making changes.
 
@@ -92,6 +92,14 @@ When using the `gh` CLI to view issues, PRs, or other GitHub objects:
 - **ALWAYS** use the patch editing mechanism provided by the agent
 - Shell text tools may be used for **read‑only analysis only**
 
+### Public API Preludes
+
+- Keep `prelude::*` small and focused on common quick-start workflows.
+- Keep scoped preludes minimal and orthogonal; do not duplicate specialized APIs across scoped preludes unless the overlap is intentionally documented.
+- `prelude::observables` is the user-facing analysis surface for measuring triangulations and derived physical observables.
+- `prelude::simulation` is for running, inspecting, and debugging simulations; it may expose telemetry and proposal/result types, but should not become the home for user-facing observable estimators.
+- Detailed prelude boundary guidance lives in `docs/dev/rust.md`.
+
 ### Commit Message Generation
 
 When generating commit messages:
@@ -137,6 +145,8 @@ just ci
 
 Refer to `docs/dev/commands.md` for full details.
 
+When adding or renaming Cargo examples, update `just validate-examples` markers as needed so CI keeps validating the user-facing example contracts.
+
 For tooling-alignment work, update `docs/dev/tooling-alignment.md` with the comparison and rationale before adding or changing config, workflow, or repository-rule files.
 
 ---
@@ -162,17 +172,17 @@ Key principle:
 - **MSRV**: 1.95.0
 - **Edition**: 2024
 - **Unsafe code**: forbidden (`#![forbid(unsafe_code)]`)
-- **Architecture**: CDT physics layered over a pluggable geometry backend (`delaunay` crate). Direct `use delaunay::` imports are restricted to `src/geometry/` (`backends/delaunay.rs` and `generators.rs`); all other modules use the trait-based abstractions and `DelaunayBackend2D` type alias (see `docs/dev/rust.md § Geometry Backend Isolation`)
-- **Modules**: `src/cdt/` (CDT logic: moves, action, Metropolis, foliation), `src/geometry/` (geometry abstractions and backends), `src/config.rs` (simulation configuration)
-- **Foliation**: `src/cdt/foliation.rs` assigns per-vertex time labels via `VertexSecondaryMap`; `from_foliated_cylinder` constructs foliated triangulations; `validate_causality` enforces |Δt| ≤ 1 on edges. Design documented in `docs/foliation.md`
-- **Ergodic moves**: `attempt_22_move`, `attempt_13_move`, `attempt_31_move`, `attempt_edge_flip` are currently placeholder implementations; full `delaunay::Tds` integration is planned
+- **Architecture**: `src/geometry/` is the backend interface layer for the `delaunay` crate; `src/cdt/` is the CDT domain layer. Direct `use delaunay::` imports are restricted to `src/geometry/` (`backends/delaunay.rs` and `generators.rs`); CDT modules use the trait-based abstractions, crate-owned Delaunay handles, generator utilities, and `DelaunayBackend2D` type alias (see `docs/dev/rust.md § Geometry Backend Isolation`)
+- **Modules**: `src/cdt/` (CDT logic: moves, action, Metropolis, foliation, observables, results, triangulation child modules), `src/geometry/` (geometry abstractions and backends), `src/config.rs` (simulation configuration)
+- **Foliation**: `src/cdt/foliation.rs` defines foliation bookkeeping and edge/cell classification. Time labels are stored as vertex data; `from_cdt_strip` and `from_toroidal_cdt` construct labeled CDT triangulations; `validate_causality` enforces adjacent-slice edges (with circular distance on toroidal time). Design documented in `docs/foliation.md`
+- **Ergodic moves**: `attempt_22_move`, `attempt_13_move`, `attempt_31_move`, `attempt_edge_flip` are Delaunay-backed, foliation-aware move kernels. They mutate through narrow CDT-owned edit operations, roll back failed finalized mutations, and preserve topology/foliation invariants
 - **Python scripts**: `scripts/` contains benchmark, changelog, and hardware utilities; tests in `scripts/tests/` run via pytest
-- **When adding/removing files**: Update `docs/project.md`
+- **When adding/removing files**: Update `docs/code_organization.md`
 
 Architecture details are documented in:
 
 ```text
-docs/project.md
+docs/code_organization.md
 ```
 
 ---

CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thank you for your interest in contributing to the [**causal-triangulations**][c
 - [Code of Conduct](#code-of-conduct)
 - [Getting Started](#getting-started)
 - [Development Environment Setup](#development-environment-setup)
-- [Project Structure](#project-structure)
+- [Code Organization](#code-organization)
 - [Development Workflow](#development-workflow)
 - [Just Command Runner](#just-command-runner)
 - [Code Style and Standards](#code-style-and-standards)
@@ -145,36 +145,9 @@ info: downloading component 'clippy'
 
 This is normal and only happens once.
 
-## Project Structure
+## Code Organization
 
-```text
-causal-triangulations/
-├── src/                    # Core library code
-│   ├── cdt/               # CDT-specific implementations
-│   │   ├── action.rs      # Regge action calculations
-│   │   ├── metropolis.rs  # Monte Carlo simulation
-│   │   ├── ergodic_moves.rs # Pachner moves
-│   │   └── triangulation.rs # CDT triangulation wrapper
-│   ├── geometry/          # Geometry abstraction layer
-│   │   ├── backends/      # Geometry backend implementations
-│   │   ├── mesh.rs        # Mesh data structures
-│   │   ├── operations.rs  # High-level operations
-│   │   └── traits.rs      # Geometry traits
-│   ├── config.rs          # Configuration management
-│   ├── errors.rs          # Error types
-│   ├── util.rs            # Utility functions
-│   ├── lib.rs             # Library root
-│   └── main.rs            # CLI binary
-├── examples/              # Usage examples
-│   ├── basic_cdt.rs       # Library usage example
-│   └── scripts/           # Ready-to-use simulation scripts
-├── tests/                 # Test suite
-│   ├── cli.rs             # CLI integration tests
-│   └── integration_tests.rs # System integration tests
-├── benches/               # Performance benchmarks
-├── docs/                  # Documentation
-└── justfile               # Task automation
-```
+The source/module layout and architecture-sensitive boundaries live in [docs/code_organization.md](docs/code_organization.md). Keep that file current when adding, removing, or moving source files, examples, or architecture-significant modules.
 
 ## Development Workflow
 
@@ -203,14 +176,34 @@ just --list          # Show all available commands
 just help-workflows  # Detailed workflow guidance
 ```
 
+### Repository Tooling Map
+
+```text
+.github/workflows/codeql.yml # CodeQL analysis for Actions and Rust
+.github/workflows/semgrep-sarif.yml # Repository Semgrep rule SARIF upload
+rustfmt.toml           # Stable Rust formatting settings
+cliff.toml             # git-cliff changelog template and commit grouping
+semgrep.yaml           # Repository-owned Semgrep rules
+docs/dev/python.md     # Python script style and validation guidance
+docs/dev/tooling-alignment.md # Tooling comparison and issue #112 decisions
+docs/roadmap.md        # High-level release direction and non-goals
+tests/semgrep/         # Semgrep rule fixtures run by `just semgrep-test`
+scripts/archive_changelog.py # Split completed changelog minor series into archive files
+scripts/coverage_report.py # Cobertura coverage summary helper
+scripts/postprocess_changelog.py # Markdown hygiene for git-cliff changelogs
+scripts/tag_release.py # Annotated release tags from root or archived changelog sections
+```
+
 ### Typical Development Cycle
 
 1. **Start working on a feature/fix**:
 
    ```bash
-   git checkout -b feature/your-feature-name
+   git checkout -b fix/307-topology-validation
    ```
 
+   Branch names should follow `{type}/{issue}-descriptor-or-two`, such as `fix/307-topology-validation` or `perf/315-bench-profile`.
+
 2. **Development cycle**:
 
    ```bash

Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = [ "Adam Getchell <adam@adamgetchell.org>" ]
 categories = [ "science", "mathematics", "algorithms", "simulation" ]
 edition = "2024"
+documentation = "https://docs.rs/causal-triangulations"
 homepage = "https://github.com/acgetchell/causal-triangulations"
 keywords = [
     "quantum-gravity",

README.md

@@ -14,21 +14,23 @@ The library leverages high-performance [Delaunay triangulation] backends and pro
 
 ## ✨ Features
 
-- [x] 2D Causal Dynamical Triangulations with time-foliation (early implementation)
-- [x] Metropolis-Hastings simulation loop with proposal-before-mutation move ordering
-- [x] Regge action calculation with configurable coupling constants (experimental)
-- [x] Ergodic moves (Alexander/Pachner moves) with causal constraints (experimental)
-- [x] Command-line interface for simulation workflows (early)
-- [x] Benchmarking and performance analysis infrastructure (in progress)
-- [x] Cross-platform compatibility (Linux, macOS, Windows)
+- [x] Explicit 1+1 CDT strip and toroidal S¹×S¹ constructors with foliation invariants
+- [x] Foliation-aware topology, causality, and cell-classification validation
+- [x] Proposal-before-mutation Metropolis-Hastings simulation with rollback on failed accepted moves
+- [x] Regge action calculation with configurable coupling constants
+- [x] Alexander/Pachner-style local move proposals with causal constraints
+- [x] Volume-profile, Hausdorff-dimension, and spectral-dimension observables for CDT analysis
+- [x] Focused public preludes for simulation, triangulation, geometry, action, and observables
+- [x] Command-line interface, examples, Criterion benchmarks, and CI-aligned validation tooling
+- [x] Cross-platform compatibility: Linux, macOS, Windows
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## 🚧 Project Status
 
-🚧 **Pre-release (0.0.x)** — This crate is under active development and **not yet ready for production use**. APIs, data structures, and module boundaries may change without notice.
+🚧 **Pre-release (0.0.x)** — The 1+1 CDT foundation is implemented and tested, but this crate is still under active development and **not yet ready for production use**. APIs, data structures, and module boundaries may change before v0.1.0.
 
-The library currently supports an initial 2D CDT implementation, with planned extensions to 3D and 4D.
+The library currently supports validated 1+1 CDT construction, foliation checks, Metropolis sampling, and core observables. Higher-dimensional CDT support, full move-kernel maturity, visualization/export workflows, and advanced ensemble-analysis helpers remain roadmap work.
 
 See [`docs/roadmap.md`](docs/roadmap.md) for current direction, near-term candidates, and non-goals.
 
@@ -56,7 +58,7 @@ The long-term design separates:
 - **Sampling** (MCMC algorithms)
 - **Physics** (CDT-specific dynamics and observables)
 
-This crate focuses on the CDT (physics + domain) layer.
+Within this crate, `src/geometry/` is the backend interface layer over `delaunay`, while `src/cdt/` is the CDT domain layer.
 
 ## 🤝 How to Contribute
 
@@ -180,34 +182,23 @@ See [`benches/README.md`](benches/README.md) for benchmark details and [`docs/PE
 
 ## 🛣️ Roadmap
 
-- [x] Integrate an existing Rust **Delaunay** triangulation library (e.g., [`delaunay`](https://crates.io/crates/delaunay))
-- [x] 2D Delaunay triangulation scaffold
-- [ ] 1+1 foliation (causal time‑slicing)
-- [ ] 2D ergodic moves (Alexander/Pachner moves with causal constraints, fully validated)
-- [ ] 2D Metropolis–Hastings (stabilized on `markov-chain-monte-carlo` delayed proposals)
-- [ ] Diffusion‑accelerated MCMC (exploration)
-- [ ] Basic visualization hooks (export to common mesh formats)
-- [ ] 3D Delaunay + 2+1 foliation + moves + M–H
-- [ ] 4D Delaunay + 3+1 foliation + moves + M–H
-- [ ] Mass initialization via **Constrained Delaunay** in 3D/4D
-- [ ] Shortest paths & geodesic distance
-- [ ] Curvature estimates / Einstein tensor (discrete Regge‑like observables)
+The high-level roadmap, including 1+1 maturity work, future 2+1 and 3+1 CDT topology tracks, observables, dual/Voronoi geometry, visualization, and non-goals, lives in [`docs/roadmap.md`](docs/roadmap.md).
 
 ## Design notes
 
 - **Separation of concerns**: geometry primitives (Delaunay/Voronoi) are decoupled from CDT dynamics.
 - **Foliation‑aware data model**: explicit time labels; space‑like vs time‑like edges encoded in types.
 - **Testing**: unit + property tests for invariants (e.g., move reversibility, manifoldness).
 
-For comprehensive guidelines on contributing, development environment setup, testing, and project structure, please see [CONTRIBUTING.md](CONTRIBUTING.md).
+For comprehensive guidelines on contributing, development environment setup, testing, and code organization, please see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 This includes information about:
 
 - Building and testing the library
 - Running benchmarks and performance analysis
 - Code style and standards
 - Submitting changes and pull requests
-- Project structure and development tools
+- Code organization and development tools
 
 ## 📚 References
 

REFERENCES.md

@@ -3,7 +3,7 @@ title: "References and Citations"
 description: "Academic references and bibliographic citations used throughout the causal-triangulations library"
 keywords: ["references", "citations", "causal dynamical triangulations", "quantum gravity", "bibliography"]
 author: "Adam Getchell"
-date: "2025-10-07"
+date: "2026-05-06"
 category: "Documentation"
 tags: ["academic", "research", "citations", "physics", "quantum gravity"]
 layout: "page"
@@ -38,6 +38,16 @@ This section contains the seminal papers and foundational work that established
 
 - Ambjørn, J., Görlich, A., Jurkiewicz, J., and Loll, R. "Nonperturbative Quantum Gravity." _Physics Reports_ 519, no. 4-5 (2012): 127-210. DOI: [10.1016/j.physrep.2012.03.007](https://doi.org/10.1016/j.physrep.2012.03.007). arXiv: [1203.3591](https://arxiv.org/abs/1203.3591)
 
+### Volume Profiles and Dimensional Observables
+
+- Ambjørn, J., Jurkiewicz, J., and Loll, R. "Reconstructing the Universe." _Physical Review D_ 72, no. 6 (2005): 064014. DOI: [10.1103/PhysRevD.72.064014](https://doi.org/10.1103/PhysRevD.72.064014). arXiv: [hep-th/0505154](https://arxiv.org/abs/hep-th/0505154)
+
+- Ambjørn, J., Jurkiewicz, J., and Loll, R. "The Spectral Dimension of the Universe is Scale Dependent." _Physical Review Letters_ 95, no. 17 (2005): 171301. DOI: [10.1103/PhysRevLett.95.171301](https://doi.org/10.1103/PhysRevLett.95.171301). arXiv: [hep-th/0505113](https://arxiv.org/abs/hep-th/0505113)
+
+- Ambjørn, J., Budd, T., and Watabiki, Y. "Scale-dependent Hausdorff dimensions in 2d gravity." _Physics Letters B_ 736 (2014): 339-343. DOI: [10.1016/j.physletb.2014.07.047](https://doi.org/10.1016/j.physletb.2014.07.047). arXiv: [1406.6251](https://arxiv.org/abs/1406.6251)
+
+- van der Duin, J., Loll, R., Schiffer, M., and Silva, A. "Quantum gravity and effective topology." _The European Physical Journal C_ 86, no. 2 (2026): 102. DOI: [10.1140/epjc/s10052-026-15322-x](https://doi.org/10.1140/epjc/s10052-026-15322-x)
+
 ## Monte Carlo Methods in Quantum Gravity
 
 These references provide the algorithmic foundations for Monte Carlo simulations in discrete quantum gravity.

benches/cdt_benchmarks.rs

@@ -332,27 +332,9 @@ fn bench_simulation_analysis(c: &mut Criterion) {
             },
         ],
         measurements: vec![
-            Measurement {
-                step: 0,
-                action: 12.5,
-                vertices: 15,
-                edges: 32,
-                triangles: 18,
-            },
-            Measurement {
-                step: 10,
-                action: 11.8,
-                vertices: 16,
-                edges: 34,
-                triangles: 19,
-            },
-            Measurement {
-                step: 20,
-                action: 12.1,
-                vertices: 15,
-                edges: 31,
-                triangles: 17,
-            },
+            Measurement::new(0, 12.5, 15, 32, 18).with_volume_profile(vec![9, 9, 0]),
+            Measurement::new(10, 11.8, 16, 34, 19).with_volume_profile(vec![9, 10, 0]),
+            Measurement::new(20, 12.1, 15, 31, 17).with_volume_profile(vec![8, 9, 0]),
         ],
         elapsed_time: Duration::from_millis(37),
         triangulation,
@@ -372,6 +354,34 @@ fn bench_simulation_analysis(c: &mut Criterion) {
         });
     });
 
+    group.bench_function("average_volume_profile", |b| {
+        b.iter(|| {
+            let profile = results.average_volume_profile();
+            black_box(profile)
+        });
+    });
+
+    group.bench_function("volume_fluctuations", |b| {
+        b.iter(|| {
+            let fluctuations = results.volume_fluctuations();
+            black_box(fluctuations)
+        });
+    });
+
+    group.bench_function("hausdorff_dimension_estimate", |b| {
+        b.iter(|| {
+            let estimate = results.hausdorff_dimension_estimate();
+            black_box(estimate)
+        });
+    });
+
+    group.bench_function("spectral_dimension_estimate", |b| {
+        b.iter(|| {
+            let estimate = results.spectral_dimension_estimate();
+            black_box(estimate)
+        });
+    });
+
     group.bench_function("equilibrium_measurements", |b| {
         b.iter(|| {
             let measurements = results.equilibrium_measurements();

docs/PERFORMANCE_TESTING.md

@@ -73,7 +73,7 @@ just perf-check
 # Strict 5% threshold for critical changes
 just perf-check 5.0
 
-# Relaxed 15% threshold for experimental features
+# Relaxed 15% threshold for exploratory changes
 just perf-check 15.0
 ```