refactor(core)!: replace public core module with focused facades

CHANGELOG.md

@@ -5,6 +5,81 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### ⚠️ Breaking Changes
+
+- Support periodic flip parity for external cells [#391](https://github.com/acgetchell/delaunay/pull/391)
+- Replace public core module with focused facades
+- Route low-level exports through public facades [#388](https://github.com/acgetchell/delaunay/pull/388)
+- Clarify bulk progress counters
+
+### Merged Pull Requests
+
+- Support periodic flip parity for external cells [#391](https://github.com/acgetchell/delaunay/pull/391)
+- Refactor/387 tds mutation boundaries [#390](https://github.com/acgetchell/delaunay/pull/390)
+- Refresh release docs and benchmark guidance [#389](https://github.com/acgetchell/delaunay/pull/389)
+- Route low-level exports through public facades [#388](https://github.com/acgetchell/delaunay/pull/388)
+
+### Added
+
+- [**breaking**] Support periodic flip parity for external cells [#391](https://github.com/acgetchell/delaunay/pull/391)
+  [`5fb2d4a`](https://github.com/acgetchell/delaunay/commit/5fb2d4a22927231ba3396950cf2bbbc481f69285)
+
+  - Preserve periodic vertex offsets when bistellar flips build replacement cells.
+  - Align external-facet parity checks across periodic cell frames instead of rejecting periodic external cells.
+  - Surface replacement periodic-offset shape and frame conflicts with typed flip-context errors.
+
+### Changed
+
+- Refactor/387 tds mutation boundaries [#390](https://github.com/acgetchell/delaunay/pull/390)
+  [`da30293`](https://github.com/acgetchell/delaunay/commit/da3029302e8484d26d2a88d1291050c332e6b822)
+
+- [**breaking**] Replace public core module with focused facades
+  [`3fc95ea`](https://github.com/acgetchell/delaunay/commit/3fc95ea62325111c927127a48d4fbd39873dabda)
+
+  - Make `crate::core` private and expose low-level APIs through curated
+    `tds`, `collections`, `algorithms`, and `query` modules.
+
+  - Add focused prelude/docs coverage for the new public import paths.
+  - Update downstream-style tests and doctests to stop relying on
+    `delaunay::core`.
+
+- [**breaking**] Route low-level exports through public facades [#388](https://github.com/acgetchell/delaunay/pull/388)
+  [`69f4fc3`](https://github.com/acgetchell/delaunay/commit/69f4fc38ad75ade19bfff693d67dee2ea5f99d4f)
+
+  - Move public documentation, doctests, and prelude exports away from the private `crate::core` namespace.
+  - Keep point-location and conflict-region APIs canonical under `delaunay::algorithms` and `delaunay::prelude::algorithms`.
+  - Expose repair, insertion, flip, and validation contracts through the triangulation and TDS facades.
+  - Harden `toml-check` by passing TOML filenames to Python via argv.
+
+### Documentation
+
+- Refresh release docs and benchmark guidance [#389](https://github.com/acgetchell/delaunay/pull/389)
+  [`526583c`](https://github.com/acgetchell/delaunay/commit/526583c627d32d9336910bce1913b7f458ca413c)
+
+  - Update the README pitch, feature list, references, and docs.rs-facing guidance
+    around exact predicates, SoS, PL-manifold validation, and bistellar repair.
+
+  - Refresh roadmap, release, limitation, robustness, orientation, invariant,
+    diagnostics, property-testing, workflow, and validation docs for the v0.7.8
+    cleanup path and v0.8.0 paper-facing work.
+
+  - Align contributor and script docs around non-mutating `just` checks before
+    mutating fixes.
+
+  - Update generated benchmark-summary guidance to surface `just bench-perf-summary`,
+    current Criterion metadata, and large-scale characterization defaults.
+
+### Fixed
+
+- [**breaking**] Clarify bulk progress counters [`393e463`](https://github.com/acgetchell/delaunay/commit/393e4637adf64fd23a7a32c0ec53fbfb2033a5c3)
+
+  - Report the effective batch progress cadence in the large-scale debug harness, including the canonical `DELAUNAY_BULK_PROGRESS_EVERY` fallback behavior.
+  - Rename bulk progress tracing fields so post-initial-simplex counters are distinct from total input and final insertion statistics.
+  - Point public docs and downstream-style API tests at curated low-level modules and construction prelude imports.
+  - Regenerate the changelog so the core facade break appears in Unreleased.
+
 ## [0.7.7] - 2026-05-15
 
 ### ⚠️ Breaking Changes
@@ -3376,6 +3451,7 @@ Older releases are archived by minor series:
 - [0.3.x](docs/archive/changelog/0.3.md)
 - [0.2.x](docs/archive/changelog/0.2.md)
 
+[Unreleased]: https://github.com/acgetchell/delaunay/compare/v0.7.7...HEAD
 [0.7.7]: https://github.com/acgetchell/delaunay/compare/v0.7.6...v0.7.7
 [0.7.6]: https://github.com/acgetchell/delaunay/compare/v0.7.5...v0.7.6
 [0.7.5]: https://github.com/acgetchell/delaunay/compare/v0.7.4...v0.7.5

CONTRIBUTING.md

@@ -714,6 +714,33 @@ Follow the patterns documented in [code organization documentation][code-organiz
 7. Trait implementations
 8. Tests (comprehensive with subsections)
 
+### Public Namespace Policy
+
+`src/core/` is the internal implementation namespace for the low-level TDS and
+algorithm layer. Do not make `crate::core` public or add a broad
+`delaunay::core` facade. The public low-level surface should stay explicit and
+workflow-oriented:
+
+- `delaunay::tds` for cells, facets, vertex keys, TDS validation, and generic
+  triangulation data structures
+- `delaunay::collections` for collection aliases, small buffers, and secondary
+  maps
+- `delaunay::algorithms` for low-level algorithms such as point location and
+  Hilbert ordering
+- `delaunay::query` for read-only traversal, convex hull extraction, boundary
+  analysis, and diagnostics helpers
+
+Expose new low-level APIs through those curated modules and their focused
+preludes when the item is useful to downstream callers. Keep high-level
+Delaunay construction, repair, validation policy, and workflow APIs separate
+from this layer so imports describe the level of abstraction being used.
+
+During pre-1.0 development, breaking import changes are acceptable when they
+improve correctness, orthogonality, or performance. When changing the public
+surface, update the facade modules in `src/lib.rs`, the focused preludes,
+README import guidance, code-organization docs, doctests, and any
+downstream-style integration tests that demonstrate supported imports.
+
 ## Testing
 
 ### Test Categories

README.md

@@ -194,6 +194,14 @@ intent. The broad `delaunay::prelude::triangulation::*` import is retained for
 compatibility, but new docs and tests should prefer the narrow workflow preludes
 above.
 
+### Low-level imports
+
+`delaunay::core` is an internal implementation namespace. Public low-level APIs
+are exposed through `delaunay::tds`, `delaunay::collections`,
+`delaunay::algorithms`, and `delaunay::query`, plus the matching focused
+preludes. Contributors should follow the namespace policy in
+[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/code_organization.md](docs/code_organization.md).
+
 ```rust
 use delaunay::prelude::triangulation::construction::{
     DelaunayTriangulationBuilder, DelaunayTriangulationConstructionError, vertex,

docs/code_organization.md

@@ -427,6 +427,13 @@ The `benchmark-utils` CLI provides integrated benchmark workflow functionality,
   - `canonical_points.rs` - Canonical vertex-ordering helpers for geometric predicate call sites (SoS consistency)
 - `operations.rs` - Semantic classification and telemetry for topological operations
 
+Public namespace policy: `crate::core` is the internal implementation namespace
+for the low-level TDS and algorithm layer. The public low-level surface is
+exposed through curated modules and focused preludes (`delaunay::tds`,
+`delaunay::collections`, `delaunay::algorithms`, `delaunay::query`, and their
+`delaunay::prelude::*` counterparts) rather than a broad public
+`delaunay::core` module.
+
 **`src/geometry/`** - Geometric algorithms and predicates:
 
 - `kernel.rs` - Kernel abstraction (`AdaptiveKernel` default, `RobustKernel`, `FastKernel`) and `ExactPredicates` marker trait

docs/dev/debug_env_vars.md

@@ -41,7 +41,7 @@ This matters for large-scale investigations that need to run under
 | Variable | Activation | Module | Description |
 |---|---|---|---|
 | `DELAUNAY_INSERT_TRACE` | presence | `triangulation.rs` | `[release]` Per-insertion summary (vertex index, location, conflict size, suspicion flags) |
-| `DELAUNAY_BULK_PROGRESS_EVERY` | **value** (integer) | `triangulation/delaunay.rs` | `[release]` Periodic batch progress plus retry-boundary output. |
+| `DELAUNAY_BULK_PROGRESS_EVERY` | **value** (integer) | `triangulation/delaunay.rs` | `[release]` Periodic batch progress for post-simplex bulk vertices. |
 | `DELAUNAY_DEBUG_CAVITY_REDUCTION_ONCE` | presence | `triangulation.rs` | `[release]` One-shot trace of first cavity reduction chain + re-extractions. |
 | `DELAUNAY_DEBUG_RETRYABLE_SKIP` | presence | `triangulation.rs` | `[release]` Retryable conflict skip trace with attempt and rollback context. |
 | `DELAUNAY_DEBUG_SHUFFLE` | presence | `triangulation.rs` | Logs vertex shuffle order during batch construction |
@@ -132,7 +132,7 @@ and release builds.
 | `DELAUNAY_LARGE_DEBUG_INITIAL_SIMPLEX` | **value** | Batch initial simplex strategy: `max-volume` (default), `balanced`, or `first` |
 | `DELAUNAY_LARGE_DEBUG_DEBUG_MODE` | **value** | `cadenced` (ridge-link) or `strict` (per-insertion vertex-link) |
 | `DELAUNAY_LARGE_DEBUG_SHUFFLE_SEED` | **value** | Vertex shuffle seed |
-| `DELAUNAY_LARGE_DEBUG_PROGRESS_EVERY` | **value** | Progress logging interval |
+| `DELAUNAY_LARGE_DEBUG_PROGRESS_EVERY` | **value** | Incremental progress interval; batch fallback if the canonical knob is unset |
 | `DELAUNAY_LARGE_DEBUG_VALIDATE_EVERY` | **value** | Validation interval |
 | `DELAUNAY_LARGE_DEBUG_REPAIR_EVERY` | **value** | Batch/incremental repair interval (default: 1) |
 | `DELAUNAY_LARGE_DEBUG_REPAIR_MAX_FLIPS` | **value** | Flip budget override |

docs/numerical_robustness_guide.md

@@ -315,7 +315,7 @@ See `validate_cell_coordinate_uniqueness` in
 ### User-facing dedup utilities
 
 For explicit preprocessing, the crate provides public deduplication functions in
-`core::util`:
+`delaunay::prelude::triangulation`:
 
 - `dedup_vertices_exact(&[Vertex])` — removes exact coordinate duplicates (O(n²))
 - `dedup_vertices_epsilon(&[Vertex], epsilon)` — removes near-duplicates within

docs/production_review_remediation_checklist.md

@@ -102,9 +102,10 @@ Treat partial items as still open until their acceptance notes are satisfied.
 - [ ] **25. Protect `Vertex::incident_cell` mutation.**
   Introduce a checked setter or newtype so invalid incident-cell links are
   harder to construct. Tracked for v0.7.8 in #387.
-- [ ] **26. Revisit public `core` module naming.**
-  Decide whether to keep the shadowing surface, rename it, or hide it behind
-  curated exports. Tracked for v0.7.8 in #388.
+- [x] **26. Revisit public `core` module naming.**
+  Keep `crate::core` as the internal implementation namespace, and expose the
+  public low-level surface through curated modules and focused preludes such as
+  `tds`, `collections`, `algorithms`, and `query`. Tracked for v0.7.8 in #388.
 - [ ] **27. Normalize boxing policy in Delaunay repair error variants.**
   Pick a consistent enum-size and payload strategy. Tracked for v0.7.8 in #384.
 

docs/validation.md

@@ -571,12 +571,12 @@ converge, consider the opt-in heuristic rebuild fallback via
 
 | Level | Method | Module | Complexity |
 |-------|--------|--------|------------|
-| 1 | `Cell::is_valid()` | `core::cell` | O(1) |
-| 1 | `Vertex::is_valid()` | `core::vertex` | O(1) |
-| 2 | `Tds::is_valid()` | `core::tds` | O(N×D²) |
-| 2 | `Tds::validate()` | `core::tds` | O(N×D²) |
-| 3 | `Triangulation::is_valid()` | `core::triangulation` | O(N×D²) |
-| 3 | `Triangulation::validate()` | `core::triangulation` | O(N×D²) |
+| 1 | `Cell::is_valid()` | `tds` | O(1) |
+| 1 | `Vertex::is_valid()` | `tds` | O(1) |
+| 2 | `Tds::is_valid()` | `tds` | O(N×D²) |
+| 2 | `Tds::validate()` | `tds` | O(N×D²) |
+| 3 | `Triangulation::is_valid()` | `triangulation` | O(N×D²) |
+| 3 | `Triangulation::validate()` | `triangulation` | O(N×D²) |
 | 4 | `DelaunayTriangulation::is_valid()` | `triangulation::delaunay` | O(cells) |
 | 4 | `DelaunayTriangulation::validate()` | `triangulation::delaunay` | O(cells × D²) + O(cells) |
 | — | `DelaunayTriangulation::validation_report()` | `triangulation::delaunay` | O(cells × D²) + O(cells) |