api-boundary.md

C++ API boundary

CDT++ 1.0 uses cdt as the sole root namespace for project-owned C++ declarations. Component namespaces describe a domain, while any nested detail namespace is an implementation contract and is not supported for downstream callers. The namespace is a maintenance signal rather than an access-control mechanism.

The public headers do not contain namespace-wide using directives. The only project macro intended for callers' preprocessing environment is CDT_PRETTY_FUNCTION, which normalizes compiler function-name spellings and is project-prefixed because macros cannot be namespaced. Include guards and the platform-required NOMINMAX definition are preprocessing exceptions rather than C++ API declarations. The formatter specializations remain in fmt, as required by that library's customization contract.

The C++ API quickstart is the canonical runnable consumer of this boundary. CMake compiles it from the same source embedded in the generated documentation, and CTest exercises its validated construction, ten explicitly reported Metropolis proposals, aggregate summary accounting, and persistence round trip.

Header classification

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 applicable-move preparation/execution, raw CGAL flips, cavity recognition, collection helpers, bistellar_flip, and check_move
Foliated_triangulation.hpp	Root CGAL interop aliases, CellType, and EdgeType; 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::MoveStrategyKind and cdt::MoveStrategy	None
Move_tracker.hpp	MoveType, the non-generic MoveTracker, checked index conversion, and sampling in cdt::move_tracker	None
Mpfr_value.hpp	Scoped MPFR value and operations in cdt::mpfr_values	None
Periodic_3_complex.hpp	None	Legacy prototype in cdt::experimental::periodic_complex; unsupported and retained only for archival source access
Periodic_3_triangulations.hpp	None	Legacy prototype in cdt::experimental::periodic_triangulations; unsupported and retained only for archival source access
Random.hpp	Random, distinct RandomSeed and RandomStream value types, and named streams in cdt	None
Runtime_config.hpp	Validated configuration values and factories in cdt::runtime_config	Parsing helpers in cdt::runtime_config::detail
S3Action.hpp	Validated PhysicalParameters and action functions in cdt::s3_action	Finite-coupling helpers in cdt::s3_action::detail
Settings.hpp	Scalar types and named constants in cdt	Project-prefixed preprocessing exception described above
Torus_d.hpp	None	Legacy prototype in cdt::experimental::torus; unsupported and retained only for archival source access
Triangulation_traits.hpp	None	CGAL assembly traits in cdt::detail; supported aliases are published by Foliated_triangulation.hpp
Utilities.hpp	cdt::Topology and persistence, reproducibility, random-distribution, logging, and conversion operations in cdt::utilities	Serialization and parsing machinery in cdt::utilities::detail

Tests that name detail are deliberate white-box tests for mutation failure-atomicity and malformed-handle rejection. Test access does not promote those declarations into the supported API.

The persistence surface distinguishes three read contracts. read_file<T>(path) remains the general triangulation reader, including legacy payloads without manifests. read_initial_triangulation<T>(path) is the new-run boundary: it requires a complete manifested initial-triangulation, verifies payload integrity and causal metadata, rejects checkpoint, final, and coincident-coordinate artifacts, and returns both the owning triangulation and its initialization provenance in Initial_triangulation_artifact<T>. It does not resume a stochastic stream. read_checkpoint<T>(path) is the exact-restart boundary: it accepts only a manifested checkpoint with complete PCG state, transition accounting, distinct vertex coordinates, and a matching producer toolchain, then returns the owning triangulation and continuation metadata in Checkpoint_artifact<T>.

The supported-header compile contract intentionally excludes experimental. The CGAL 6.2 audit confirmed that the periodic and d-dimensional prototypes are not production dependencies and do not meet the supported compile contract. Their presence under include/ preserves archival source access, not a promise that they are usable downstream. See the CGAL integration contract.

Compatibility policy

The final 1.0 surface is the source-compatibility boundary. Repository production code, tests, and documented examples were the only callers found for the pre-1.0 declarations. Compatibility aliases would leave an indefinite archival burden, so no deprecated aliases are provided. Downstream source must qualify project names through cdt.

The final pre-1.0 API pass made these intentional source changes:

Pre-1.0 spelling or contract	Final 1.0 contract
topology_type, Artifact_kind, Cell_type, move_type, Strategies	Topology, ArtifactKind, CellType, MoveType, MoveStrategyKind
Interchangeable Random_seed and Random_stream integer aliases	Distinct RandomSeed and RandomStream values with explicit construction and .value() at raw-integer boundaries
MoveTracker<ManifoldType>	Non-generic MoveTracker, because the counter has no manifold-dependent state
Unchecked as_move(int) with a (4,4) fallback	move_from_index(std::size_t) returning std::optional<MoveType>
Boolean edge classification and filtering	EdgeType::TIMELIKE or EdgeType::SPACELIKE
check_timevalues() returning an optional container	has_valid_timevalues() for the predicate and find_invalid_timevalue_cells() for diagnostics
get_*() accessors and CalculateA1() / CalculateA2()	Domain names such as result(), geometry(), hastings_ratio(), and action_ratio()
S3_bulk_action*() and Gmpzf_to_double()	s3_bulk_action*() and gmpzf_to_double()

Repair functions that mutate a triangulation now require a mutable triangulation reference. MoveCommand::result() is ref-qualified: lvalues borrow the stored result and rvalues transfer it. Unsupported MoveStrategyKind specializations are incomplete rather than silently forming an empty class. PhysicalParameters can only be created by its validating factory, the generalized action consumes that proof value, and a Metropolis strategy cannot be default-constructed without valid physical parameters.

The project publishes no stable binary ABI: its library surface is templates and inline headers, and the CMake build produces executables rather than a versioned binary library. BUILD_SHARED_LIBS alone does not establish an ABI promise. The supported contract is C++23 source compatibility within the 1.0 surface documented here; detail and experimental declarations may change without compatibility shims.

Generated reference policy

The canonical Doxygen configuration extracts documented public and protected declarations while excluding private, package/internal, static, file-local, detail, and experimental symbols from the supported reference surface. Source-browser pages may still show implementation text; visibility there does not promote a declaration into the supported API.

The canonical configuration enables documentation-error, undocumented-symbol, parameter, and return warnings. Because Doxygen also emits completeness warnings for excluded implementation namespaces and source-browser entry points, the repository wrapper classifies the completed warning log: only completeness noise for detail, experimental, and recognized src entry-point artifacts is ignored. The wrapper temporarily disables Doxygen's undifferentiated fail-on-warning status so it can perform that classification after generation; it then fails on every non-exempt warning. Malformed documentation and every supported-public-surface warning are fatal. just docs-check builds the site with the repository-pinned Doxygen and Graphviz versions, then validates the warning policy, generated local links, fragments, identifiers, rendered labels, and required assets without modifying the worktree.