feat(reproducibility): persist verifiable stochastic run provenance

[acgetchell]

• Record effective seeds, named PCG streams, build identity, transition traces, causal metadata, state fingerprints, and payload checksums.
• Atomically publish validated OFF payload/manifest pairs and reject malformed, corrupt, or semantically inconsistent persisted state.
• Canonically map proposal draws for identical-start replay while preserving spherical placement and CGAL triangulation freedom.
• Document checkpoint and fresh-topology replay limitations.

Closes #93

Summary by CodeRabbit

• New Features

  • Generated .off outputs now ship with paired .off.meta provenance manifests including effective seed, build details, and integrity/provenance checks.
  • Added richer Metropolis run provenance (transition trace/count) and improved determinism via canonical ordering.
  • Triangulation now exposes the configured random seed, and version metadata includes build configuration details.

• Bug Fixes

  • Stricter validation for persisted artifacts, including checksum/fingerprint consistency and detection of corrupted or mismatched metadata.

• Documentation

  • Expanded the reproducibility and persistence contract documentation (including checkpoint semantics).

• Tests

  • Added/updated persistence-driven test harnesses and determinism-focused unit coverage.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 916e0e5f-4305-419f-bfd1-7a0fd30c86c3

📥 Commits

Reviewing files that changed from the base of the PR and between ce90551 and cef03b5.

📒 Files selected for processing (1)

• include/Runtime_config.hpp

---

Walkthrough

The PR propagates effective seeds through runtime configuration, canonicalizes stochastic move selection, records Metropolis transition provenance, adds validated .off.meta persistence manifests, and replaces integration tests with persistence-aware CMake harnesses.

Changes

Reproducibility and persistence

Layer / File(s)	Summary
Seed and build metadata wiring CMakeLists.txt, cmake/Version.hpp.in, include/Runtime_config.hpp, src/cdt.cpp, src/initialize.cpp, tests/Runtime_config_test.cpp	Build metadata and effective random seeds are exposed through generated headers and runtime configuration.
Canonical move selection include/Ergodic_moves_3.hpp, tests/Ergodic_moves_3_test.cpp, tests/Metropolis_test.cpp	Move proposal and traversal ordering use canonical ranking and deterministic container ordering.
Transition provenance and replay include/Metropolis.hpp, src/cdt.cpp, tests/Metropolis_test.cpp, tests/Random_test.cpp	Metropolis runs record transition counts and fingerprints, expose provenance metadata, and validate replay stream behavior.
Validated payload and manifest persistence include/Utilities.hpp, src/initialize.cpp, README.md, docs/reproducibility.md, tests/Utilities_test.cpp	Payloads preserve causal information and publish validated .off.meta manifests with fingerprints, checksums, toolchain data, and replay flags.
Persistence test orchestration cmake/RunCdtNoOutputTest.cmake, cmake/RunPersistenceOutputTest.cmake, src/CMakeLists.txt	CTest runs validate normalized directories, effective seeds, artifact pairing, manifest fields, and temporary-file cleanup.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

• acgetchell/CDT-plusplus#102 — The PR adds deterministic move ordering, validated CGAL persistence, provenance sidecars, and integrity checks aligned with the issue’s portability audit.

Possibly related PRs

• acgetchell/CDT-plusplus#112 — Both changes modify Metropolis transition reproducibility through explicit seeded streams and replay tracking.
• acgetchell/CDT-plusplus#111 — Both changes touch validated runtime state, snapshot persistence, and provenance plumbing.

Poem

Seeds take root, and moves align,
Traces bloom in ordered time.
Manifests guard each saved state,
Checksums watch beside the gate.
Payloads rest, ready to replay.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.04% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the PR’s main reproducibility and provenance work.
Linked Issues check	✅ Passed	The changes implement the reproducibility contract: seeded streams, provenance metadata, portable persistence, validation, and documentation required by #93.
Out of Scope Changes check	✅ Passed	The changes remain focused on reproducibility, persistence, and test coverage, with no clear unrelated scope added.

✨ 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/93-reproducibility-contract

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@include/Runtime_config.hpp`:
- Around line 31-55: Add a direct include of Random.hpp to Runtime_config.hpp so
the Triangulation declarations and constructor can resolve cdt::Random_seed
without relying on Utilities.hpp’s transitive includes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f3460c87-c3b8-4cb3-8f8c-2333d471e386

📥 Commits

Reviewing files that changed from the base of the PR and between 5b8f723 and ce90551.

📒 Files selected for processing (18)

• CMakeLists.txt
• README.md
• cmake/RunCdtNoOutputTest.cmake
• cmake/RunPersistenceOutputTest.cmake
• cmake/Version.hpp.in
• docs/reproducibility.md
• include/Ergodic_moves_3.hpp
• include/Metropolis.hpp
• include/Runtime_config.hpp
• include/Utilities.hpp
• src/CMakeLists.txt
• src/cdt.cpp
• src/initialize.cpp
• tests/Ergodic_moves_3_test.cpp
• tests/Metropolis_test.cpp
• tests/Random_test.cpp
• tests/Runtime_config_test.cpp
• tests/Utilities_test.cpp