Repository navigation
Define and normalize the public C++ namespace and API boundary #115
Description
Summary
Define and normalize CDT++'s supported C++ namespace and public API boundary before the final v1.0.0 archival release.
The current headers mix global declarations, several unrelated top-level namespaces, a newer cdt root namespace, and implementation helpers that are inconsistently placed in detail. The code is valid C++23, but callers and Doxygen cannot reliably distinguish supported API from cross-header or implementation-only machinery.
This is an API-contract audit, not a mechanical namespace-style rewrite. Every declaration must be classified before it is moved, retained, deprecated, or documented.
Current evidence
Random.hppuses thecdtroot namespace, while other components use top-level namespaces such asmanifolds,ergodic_moves,foliated_triangulations,utilities,runtime_config,move_tracker,s3_action, andmpfr_values.- Several public headers expose aliases, constants, enums, templates, classes, and functions directly in the global namespace, including
Settings.hpp,Foliated_triangulation.hpp,Geometry.hpp, the move-strategy headers, and part ofS3Action.hpp. ergodic_moves::detailis correctly used for some helpers, but analogous helpers remain inergodic_moves, includingdo_26_move_impl, cavity-recognition helpers, collection helpers, and low-level retriangulation operations.incident_cells_from_edgeandget_incident_cellsexpose overlapping behavior.- Tests call several low-level helpers directly, but test access alone does not establish a supported caller contract.
fmtformatter specializations intentionally belong in the external library's customization namespace and must not be moved into the project namespace.
Scope
Inventory and classification
- Inventory declarations in every header under
include/. - Classify each as supported public API, supported customization point, cross-header internal API, implementation detail, or legacy/experimental surface.
- Record representative production consumers, tests, and any documented external call sites before changing a declaration.
- Establish the intended source-compatibility and binary-compatibility policy for this final header-heavy C++ release; do not infer a stable ABI merely from build options.
Namespace policy
- Decide whether
cdtis the project root namespace and define coherent component subnamespaces. - Eliminate unintended global-namespace declarations from public headers, preserving only explicitly justified language- or library-required customization points.
- Use
detailconsistently for implementation-only names while recognizing that it is a convention rather than access control. - Keep anonymous namespaces out of public headers; translation-unit-local anonymous namespaces remain valid in source and test files.
- Avoid namespace-wide
usingdirectives in public headers. - Decide whether compatibility aliases or deprecation shims are appropriate for renamed public names, and give any retained compatibility surface an explicit removal/archive policy.
Ergodic-move boundary
- Keep the high-level
null_move,do_*_move, andpropose_*_moveoperations public unless caller evidence supports a different contract. - Move clearly internal implementation functions such as
do_26_move_impland cavity/collection helpers intodetailor an implementation header. - Decide explicitly whether
try_23_move,try_32_move,try_62_move, andbistellar_flipare supported advanced APIs or internal mutation machinery. - Decide explicitly whether
check_moveis a supported diagnostic API or an internal postcondition used across headers. - Remove or consolidate redundant helper surfaces such as
incident_cells_from_edgeandget_incident_cells. - Update tests so black-box move correctness does not depend on implementation-only helpers; retain focused white-box tests only where they protect a deliberately internal contract.
Validation and documentation coupling
- Add minimal external-consumer compile tests that include only supported headers and use only the intended public namespace surface.
- Add compile-time checks for important public signatures, concepts, result types, and ownership/value-category contracts where useful.
- Configure generated API documentation to present the supported surface clearly and exclude or visibly classify
detailnames. - Coordinate the resulting public surface with Validate and finalize the archival documentation site #114 before enabling strict Doxygen completeness warnings.
Acceptance criteria
- Every declaration under
include/has an intentional API classification. - The repository has a documented root-namespace and
detailpolicy with explicit exceptions. - Public headers introduce no unintended project-owned names into the global namespace.
- Similar internal helpers are treated consistently;
is_32_movableis not an isolated exception while analogous cavity-recognition helpers remain accidentally public. - Low-level ergodic-move operations and
check_movehave explicit supported-or-internal decisions backed by real caller requirements. - Redundant namespace-level helper APIs are consolidated or justified.
- Required source-compatibility shims are documented and tested; unnecessary compatibility aliases are not retained indefinitely.
- Minimal external-consumer tests compile using only the supported API, while the full C++ test suite remains green.
- Doxygen can distinguish the supported public surface from implementation details and Validate and finalize the archival documentation site #114 can enforce documentation completeness at that boundary.
- No scientific move semantics, numerical formulas, or unrelated architecture are changed merely to reorganize names.
Boundaries and relationships
- Validate and finalize the archival documentation site #114 owns Doxygen 1.17 rendering, configuration, generated-site validation, and documentation completeness enforcement; this issue defines the API boundary that it documents.
- Audit and independently validate all 3D CDT ergodic moves #106 owns the scientific correctness audit for the 3D ergodic moves and should not absorb namespace churn.
- Adopt parse-don't-validate architecture for domain invariants #101 owns domain-invariant architecture rather than namespace organization.
- Modernize CGAL 6.2 integration for current best practices #102 owns the broader CGAL 6.2 integration audit; exposed CGAL types found here should be classified, but integration redesign remains there.
- Prepare v1.0.0 documentation, metadata, and archival handoff #96 owns final release prose, metadata, and archival handoff.
Prefer the smallest coherent v1.0.0 surface. Do not add namespaces, aliases, abstraction layers, or versioning machinery without a concrete caller or archival-maintenance benefit.
Activity
refactor(api)!: normalize public declarations under cdt