refactor(api)!: require validated generator and Hilbert inputs

[acgetchell]

• Rename raw-bound generator and Hilbert ordering APIs to try_* names so fallible parsing is visible at call sites.
• Add CoordinateRange-based and prevalidated Hilbert batch APIs for callers that already carry validation evidence.
• Replace Hilbert debug-only invariants with proof-carrying index modes and typed permutation errors.
• Bound ball rejection sampling with a typed BallSamplingFailed error instead of relying on unbounded retry.
• Update preludes, examples, benches, and tests to exercise the refined API surface.

BREAKING CHANGE: Raw-bound generator and Hilbert helpers now use try_* names, and focused preludes no longer export the old non-try raw-bound APIs. Callers should migrate to the try_* functions for raw tuple inputs or to the *_in_range / prevalidated batch APIs when they already have validated inputs.

Resolves #441

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 17fb9fc0-b767-4848-97ba-e9c5677acfa4

📥 Commits

Reviewing files that changed from the base of the PR and between c0ecbe9 and ccb9ee4.

📒 Files selected for processing (1)

• src/core/util/hilbert.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core/util/hilbert.rs

---

Walkthrough

This PR refactors public APIs across Hilbert ordering, point generation, and triangulation to use the parse-don't-validate pattern: all raw coordinate bounds are now validated at fallible try_* entry points and carried inward as proof-bearing CoordinateRange types. Hilbert APIs split into tuple-bounds try_* variants and validated-bounds *_in_range infallible helpers. Point generation adds bounded ball sampling. Benchmarks and tests migrate to the new API surface throughout.

Changes

Hilbert Core API Refactoring

Layer / File(s)

Summary

Hilbert APIs split into fallible and validated paths src/core/util/hilbert.rs

HilbertError gains variants for sort permutation validation. New HilbertQuantizedBatch<'a, D> and HilbertQuantizedVec<D> types carry validated quantized coordinates. Quantization, indexing, and sorting are split into try_* (tuple bounds) and *_in_range (validated CoordinateRange) variants. apply_order becomes fallible with full permutation validation. hilbert_quantize_batch_in_range bulk-quantizes and returns owned proof. Comprehensive test updates use new APIs.

Point Generation & Triangulation Naming

Layer / File(s)	Summary
Ball sampling with bounded attempts src/geometry/util/point_generation.rs	RandomPointGenerationError::BallSamplingFailed tracks request/attempt metrics. ball_max_attempts computes dimension-scaled attempt budgets. Rejection sampling loop enforces attempt limits and returns BallSamplingFailed on exhaustion. Tests and doc examples switch to try_* API calls.
Triangulation generator API consistency src/geometry/util/triangulation_generation.rs, tests/delaunay_edge_cases.rs, tests/proptest_euler_characteristic.rs	generate_random_triangulation* renamed to try_generate_random_triangulation*. Documentation, examples, and test calls updated consistently. Equal-bounds validation added to test coverage.

Construction and Batch Integration

Layer / File(s)	Summary
Batch quantization in vertex ordering src/delaunay/construction.rs, tests/regressions.rs	Hilbert preprocessing now uses hilbert_quantize_batch_in_range with validated bounds, replacing per-vertex quantization. Fallback to lexicographic ordering on error. New regression test validates batch quantization output equivalence with two-step path across dimensions.

Benchmarks Consolidated on Validated Bounds

Layer / File(s)	Summary
Benchmark point generation refactored benches/allocation_hot_paths.rs, benches/boundary_uuid_iter.rs, benches/ci_performance_suite.rs, benches/circumsphere_containment.rs, benches/cold_path_predicates.rs, benches/profiling_suite.rs, benches/remove_vertex.rs, benches/tds_clone.rs, benches/topology_guarantee_construction.rs	All benchmarks switch from raw tuple bounds to CoordinateRange + generate_random_points_in_range_seeded. Helper functions (benchmark_bounds, coordinate_range, wide_bounds, adversarial_bounds) validate bounds via CoordinateRange::try_new and bench_result. Point generation calls now use validated range objects instead of tuples.

Examples, Validation & Prelude Surface

Layer / File(s)	Summary
Example and test API migration examples/triangulation_and_hull.rs, src/core/validation.rs, src/topology/traits/topological_space.rs, tests/large_scale_debug.rs, tests/prelude_exports.rs	Examples use CoordinateRange for bounds and new point generators. Error handling wraps CoordinateRangeError. Validation tests use try_* APIs. Prelude smoke tests verify new try_* and *_in_range helpers and validate equivalence between full and in-range ordering paths.
Public prelude exports updated src/lib.rs	Hilbert exports replaced with try_*, *_in_range, and quantized types; generator exports switch to try_generate_* variants; ordering module documentation updated to show new fallible patterns.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• acgetchell/delaunay#216: Directly introduces Hilbert error variants and bulk/prequantized index APIs that this PR expands into the try_*/*_in_range refactoring.
• acgetchell/delaunay#450: Adds/adjusts toroidal-domain validation tests and related domain parsing/validation logic referenced by this PR.
• acgetchell/delaunay#218: Earlier Hilbert bulk-quantization work related to the new batch quantize/index integration in construction.

Suggested labels

documentation

🐇 I parsed bounds from tuple to range,
Quantized batches hop along the change,
try_* calls guard the threshold bright,
Tests and benches bound in gentle light,
Hopping code, steady and rearranged.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'refactor(api)!: require validated generator and Hilbert inputs' accurately describes the main breaking change: renaming raw-bound generator and Hilbert APIs to require validated inputs via try_* names and new CoordinateRange-based APIs.
Description check	✅ Passed	The PR description clearly relates to the changeset, explaining the renaming of APIs to try_* variants, addition of CoordinateRange-based APIs, replacement of debug invariants with typed errors, and bounds on rejection sampling.
Linked Issues check	✅ Passed	The changeset comprehensively addresses issue #441 objectives: raw bounds are now parsed at fallible boundaries (try_* functions), validated CoordinateRange types are used internally, typed errors are preserved with CoordinateRangeError, and all documentation/tests/preludes are updated accordingly.
Out of Scope Changes check	✅ Passed	All changes are directly in scope for issue #441: API refactoring of generators and Hilbert utilities to use validated inputs, updating preludes/tests/benches/examples, and introducing typed error handling. No unrelated refactoring detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 100.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 refactor/441-coordinate-bounds

---

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

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 76 complexity

Metric	Results
Complexity	76

View in Codacy

🟢 Coverage 97.89% diff coverage · +0.04% coverage variation

Metric	Results
Coverage variation	✅ +0.04% coverage variation (-1.00%)
Diff coverage	✅ 97.89% diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (b1c52b6)	63824	58155	91.12%
Head commit (ccb9ee4)	64257 (+433)	58576 (+421)	91.16% (+0.04%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#452)	662	648	97.89%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/util/hilbert.rs`:
- Around line 1823-1832: The new tests only exercise D=2; extend them to cover
dimensions D=2..5 by reusing the repository's pastey macro pattern to generate
parallel cases for hilbert_quantize_in_range, HilbertQuantizedBatch::try_new,
and hilbert_quantize_batch_in_range so the happy-path is exercised for each
dimension; replace the single test (e.g.,
test_quantize_in_range_matches_tuple_boundary) with a pastey-generated set that
iterates dims 2..5 (keeping the existing D=0 special-case test), verifying
parsed == prevalidated for each dimension and using the same inputs and
CoordinateRange construction per-dimension. Ensure macro-expanded test names are
unique and follow existing naming conventions so CI recognizes them.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 56ab7bff-800e-4de9-9464-e9a3ec5c243f

📥 Commits

Reviewing files that changed from the base of the PR and between b1c52b6 and c0ecbe9.

📒 Files selected for processing (22)

• benches/allocation_hot_paths.rs
• benches/boundary_uuid_iter.rs
• benches/ci_performance_suite.rs
• benches/circumsphere_containment.rs
• benches/cold_path_predicates.rs
• benches/profiling_suite.rs
• benches/remove_vertex.rs
• benches/tds_clone.rs
• benches/topology_guarantee_construction.rs
• examples/triangulation_and_hull.rs
• src/core/util/hilbert.rs
• src/core/validation.rs
• src/delaunay/construction.rs
• src/geometry/util/point_generation.rs
• src/geometry/util/triangulation_generation.rs
• src/lib.rs
• src/topology/traits/topological_space.rs
• tests/delaunay_edge_cases.rs
• tests/large_scale_debug.rs
• tests/prelude_exports.rs
• tests/proptest_euler_characteristic.rs
• tests/regressions.rs

[codecov]

Codecov Report

❌ Patch coverage is 97.88520% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.13%. Comparing base (b1c52b6) to head (ccb9ee4).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/core/util/hilbert.rs	97.39%	11 Missing ⚠️
src/delaunay/construction.rs	90.90%	1 Missing ⚠️
src/geometry/util/point_generation.rs	99.28%	1 Missing ⚠️
src/geometry/util/triangulation_generation.rs	98.63%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #452      +/-   ##
==========================================
+ Coverage   91.09%   91.13%   +0.04%     
==========================================
  Files          72       72              
  Lines       63612    64045     +433     
==========================================
+ Hits        57945    58366     +421     
- Misses       5667     5679      +12     

Flag	Coverage Δ
unittests	91.13% <97.88%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.