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

docs/api-boundary.md

@@ -19,14 +19,15 @@ required by that library's customization contract.
 | Header | Supported surface | Internal, customization, or experimental surface |
 | --- | --- | --- |
 | `Apply_move.hpp` | `cdt::apply_move` | None |
-| `Ergodic_moves_3.hpp` | `cdt::ergodic_moves` aliases plus `null_move`, `do_*_move`, and `propose_*_move` | Every declaration in `cdt::ergodic_moves::detail`, including raw CGAL flips, cavity recognition, collection helpers, `bistellar_flip`, and `check_move` |
+| `Ergodic_moves_3.hpp` | `cdt::ergodic_moves` aliases plus `null_move`, `do_*_move`, and `propose_*_move` | Every declaration in `cdt::ergodic_moves::detail`, including applicable-move preparation/execution, raw CGAL flips, cavity recognition, collection helpers, `bistellar_flip`, and `check_move` |
 | `Foliated_triangulation.hpp` | Root CGAL interop aliases and `Cell_type`; construction, inspection, repair, and `FoliatedTriangulation` declarations in `cdt::foliated_triangulations` | Generic constraints and repair limits in `cdt::detail`; the component declarations are the supported advanced triangulation API |
 | `Formatters.hpp` | `fmt::formatter<CGAL::Point_3<...>>` | Supported external-library customization point |
 | `Geometry.hpp` | `cdt::Geometry` and `cdt::Geometry_3` | None |
 | `Manifold.hpp` | `cdt::manifolds::make_causal_vertices`, `Manifold`, and `Manifold_3` | None |
 | `Metropolis.hpp` | `cdt::MoveStrategy` Metropolis specialization and `cdt::Metropolis_3` | Private members and nested types are implementation details |
 | `Move_always.hpp` | `cdt::MoveStrategy` move-always specialization and `cdt::MoveAlways_3` | Private members are implementation details |
 | `Move_command.hpp` | `cdt::MoveCommand` | Private queue and counter types are implementation details |
+| `Move_outcome.hpp` | `cdt::ergodic_moves::MoveFailure`, `MoveError`, `MoveResult`, `MoveOutcome`, and `outcome_from` | `format_as` is the supported `fmt`/`spdlog` customization hook for `MoveError` |
 | `Move_strategy.hpp` | `cdt::Strategies` and `cdt::MoveStrategy` | None |
 | `Move_tracker.hpp` | Move enumeration, counters, conversion, and sampling in `cdt::move_tracker` | None |
 | `Mpfr_value.hpp` | Scoped MPFR value and operations in `cdt::mpfr_values` | None |

docs/ergodic-moves.md

@@ -32,11 +32,31 @@ unchanged. A successful move constructs a new `FoliatedTriangulation`, which
 rebuilds all handle-bearing caches and scalar geometry from the moved canonical
 triangulation.
 
+Raw proposal sites do not flow directly into mutation. Each move has a
+move-specific `detail::Applicable*Move` value constructed by a
+`detail::prepare_*()` boundary. Construction proves the local topology,
+causality, simplex classification, adjacency, and metadata requirements for
+that move. The value stores owned point-value locators rather than CGAL handles;
+execution resolves handles only at the mutation boundary and reports a
+`STALE_CANDIDATE` if the prepared site is no longer present. The applicable
+value is then consumed by `detail::execute()`, which does not rediscover the CDT
+preconditions and leaves CGAL's checked flip or retriangulation operation as the
+remaining fallible effect.
+
+The public high-level result is `MoveResult<Manifold>`, an allocation-free
+`std::expected` whose error is `MoveError`. `MoveFailure` distinguishes no raw
+candidate, invalid topology, causal invalidity, a stale prepared site, checked
+execution failure, post-mutation invariant failure, and an unknown move.
+`MoveOutcome` maps those typed failures and successful candidates into command
+and Metropolis accounting, keeping an inapplicable proposal distinct from an
+execution failure and from a valid Metropolis rejection.
+
 CGAL 6.2 documents that checked three-dimensional flips preserve vertex handles
 and invalidate only affected cell handles. CDT++ never carries affected cell
-handles past a successful flip. A copied triangulation has different handles;
-the `(4,4)` and `(6,2)` implementations therefore capture stable point values
-and re-resolve vertices and edges in their private copies before mutation.
+handles in prepared values or past a successful flip. A copied triangulation
+has different handles; every applicable-move implementation therefore captures
+stable point values and re-resolves vertices, cells, or edges in the owning
+candidate immediately before mutation.
 
 None of these moves is required to preserve the Euclidean empty-sphere
 (Delaunay) property of the representative coordinates. The scientific state is
@@ -95,6 +115,9 @@ helper.
 - exact inverse round trips for `(2,3)/(3,2)`, `(2,6)/(6,2)`, and `(4,4)`;
 - malformed-handle, stale-metadata, wrong-cavity, non-applicable, and empty-state
   rejection checks with canonical failure-atomicity comparisons; and
+- valid construction, forbidden default construction, and stale-locator
+  behavior for the applicable-move boundary, including structured failure
+  classification; and
 - replay of every inverse pair with seeds `0`, `1`, `2`, `92`, `106`, and
   `20260721`.