feat(moves)!: add invariant-bearing move preparation

[acgetchell]

Prepare every supported Pachner move as a handle-free applicable value before entering its mutation boundary.

Replace string failures with typed move errors and outcomes so command and Metropolis accounting distinguish inapplicable proposals, execution failures, and accepted or rejected transitions.

BREAKING CHANGE: Public move functions now return MoveResult with MoveError instead of std::expected<Manifold, std::string>. MoveCommand result customization now accepts only that typed result.

Refs: #101

Summary by CodeRabbit

• New Features

  • Added structured move results with categorized errors, stable messages, and transition outcomes.
  • Improved 3D move preparation and execution with clearer handling of stale candidates and execution failures.
  • Updated move commands and Metropolis tracking to use consistent result and outcome reporting.

• Documentation

  • Expanded documentation for move validation, mutation behavior, error categories, and handle stability.

• Tests

  • Added coverage for structured outcomes, stale candidates, applicable-move validation, and public API compatibility.

[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: 49d4d640-fd6c-47c8-96e0-a6ec6ad0cd93

📥 Commits

Reviewing files that changed from the base of the PR and between 1f98142 and e2f7d70.

📒 Files selected for processing (11)

• docs/api-boundary.md
• docs/ergodic-moves.md
• include/Ergodic_moves_3.hpp
• include/Metropolis.hpp
• include/Move_command.hpp
• include/Move_outcome.hpp
• tests/CMakeLists.txt
• tests/Ergodic_moves_3_audit_test.cpp
• tests/Ergodic_moves_3_test.cpp
• tests/Move_outcome_test.cpp
• tests/Public_api_consumer.cpp

---

Walkthrough

3D ergodic Pachner moves now use point-based prepare/execute stages with typed MoveError results. Metropolis and command execution record structured outcomes, while tests and documentation cover stale candidates, applicability, formatting, and public API constraints.

Changes

Typed move pipeline

Layer / File(s)	Summary
Move outcome contract include/Move_outcome.hpp, include/Move_command.hpp, include/Metropolis.hpp, tests/Move_outcome_test.cpp, tests/Public_api_consumer.cpp, tests/CMakeLists.txt	Adds MoveFailure, MoveError, MoveResult, and MoveOutcome, then wires typed results through command execution and Metropolis accounting.
(2,3) and (3,2) preparation include/Ergodic_moves_3.hpp, docs/ergodic-moves.md	Introduces point-based applicable moves and typed preparation, execution, candidate selection, and rejection flows.
(2,6) and (6,2) execution include/Ergodic_moves_3.hpp	Adds staged preparation, handle resolution, post-mutation validation, and structured failure propagation.
(4,4) bistellar flip include/Ergodic_moves_3.hpp	Refactors causal-diamond preparation and staged triangulation updates to return typed stale, execution, and invariant failures.
Boundary verification and documentation tests/Ergodic_moves_3_audit_test.cpp, tests/Ergodic_moves_3_test.cpp, docs/api-boundary.md, docs/ergodic-moves.md	Tests non-default construction, stale locators, failure classification, and updates the documented applicable-move boundary.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• Modernize CGAL 6.2 integration for current best practices #102 — Covers the applicable-move boundary and handle-invalidation safeguards implemented here.
• Adopt parse-don't-validate architecture for domain invariants #101 — Covers the parse-then-execute architecture and structured move outcomes used by this change.

Possibly related PRs

• acgetchell/CDT-plusplus#111 — Refactors the same ergodic move machinery toward transactional execution.
• acgetchell/CDT-plusplus#112 — Overlaps in Metropolis and move-command execution plumbing.
• acgetchell/CDT-plusplus#117 — Overlaps in transition provenance and outcome tracking.

Sequence Diagram(s)

sequenceDiagram
  participant MoveCommand
  participant Metropolis
  participant ErgodicMoves
  participant Delaunay
  MoveCommand->>Metropolis: request random move
  Metropolis->>ErgodicMoves: propose candidate
  ErgodicMoves->>Delaunay: prepare and resolve candidate
  Delaunay-->>ErgodicMoves: mutated manifold or MoveError
  ErgodicMoves-->>Metropolis: MoveResult
  Metropolis->>Metropolis: record MoveOutcome

Loading

Poem

Points become moves, handles wait,
Errors now speak their typed fate.
Stale sites gently turn away,
While flips keep order night and day.
MoveResult guides the flow—
A tidy path for states to go.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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 matches the main change: invariant-bearing move preparation for moves.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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 feat/101-parse-dont-validate-moves

---

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