feat(insertion)!: split strict and best-effort insertion statistics

[acgetchell]

• Make insert_with_statistics return typed insertion errors for skipped duplicate or retry-exhausted vertices so callers using ? cannot silently ignore skipped inputs.
• Add insert_best_effort_with_statistics for diagnostic and bulk-ingestion workflows that intentionally preserve skipped insertions as outcomes with telemetry.
• Derive the default validation policy from the active topology guarantee so PLManifold starts in ExplicitOnly mode while Pseudomanifold keeps OnSuspicion.
• Document skipped-input observability across construction, workflows, and robustness guidance.

BREAKING CHANGE: insert_with_statistics now reports skipped insertions as Err(InsertionError) instead of Ok(InsertionOutcome::Skipped).

Closes #386

[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: a43cb711-f5a9-421b-a863-774c7f998ad2

📥 Commits

Reviewing files that changed from the base of the PR and between e5a74a1 and 823b8a5.

📒 Files selected for processing (19)

• README.md
• docs/numerical_robustness_guide.md
• docs/production_review_remediation_checklist.md
• docs/validation.md
• docs/workflows.md
• src/core/insertion.rs
• src/core/operations.rs
• src/core/validation.rs
• src/delaunay/builder.rs
• src/delaunay/construction.rs
• src/delaunay/insertion.rs
• src/delaunay/query.rs
• src/delaunay/validation.rs
• src/lib.rs
• tests/insert_with_statistics.rs
• tests/large_scale_debug.rs
• tests/prelude_exports.rs
• tests/proptest_delaunay_triangulation.rs
• tests/proptest_orientation.rs

---

Walkthrough

This PR refactors the public insertion API to make skipped insertions explicit to callers and updates validation policy defaults. insert_with_statistics now returns Err(InsertionError) for skipped vertices, while a new insert_best_effort_with_statistics API returns Ok(InsertionOutcome::Skipped) for telemetry. TopologyGuarantee::PLManifold now defaults to ValidationPolicy::ExplicitOnly. Tests, docs, and all integration points are updated accordingly.

Changes

Insertion and Validation Refactor

Layer / File(s)	Summary
Insertion API semantics: strict vs best-effort src/delaunay/insertion.rs, src/core/operations.rs, src/core/insertion.rs	insert_with_statistics now maps InsertionOutcome::Skipped to Err(InsertionError) via a wrapper over insert_best_effort_with_statistics, which preserves skipped outcomes as Ok for telemetry and retry observability.
Validation policy defaults: PLManifold to ExplicitOnly src/core/validation.rs	TopologyGuarantee::default_validation_policy() changed to return ValidationPolicy::ExplicitOnly for PLManifold (previously OnSuspicion). Test helpers consolidated to dimension-generic variants and assertions updated; one PL-manifold insertion test switched to best-effort API.
Builder and construction APIs updated for new semantics src/delaunay/builder.rs, src/delaunay/construction.rs	Periodic builder fallback loop and all batch construction entry-point docs updated to clarify best-effort ingestion and skipped-input observability via ConstructionStatistics. Duplicate/degenerate skips are now explicitly documented as expected in successful construction.
Query and validation mapping APIs updated src/delaunay/query.rs, src/delaunay/validation.rs	validation_policy() getter docs and tests updated to expect ExplicitOnly default. Validation mapping docs clarified with explicit PLManifold → ExplicitOnly association; all constructor path assertions updated to reflect the new default.
Public exports and crate-level documentation src/lib.rs	TopologyGuarantee added to delaunay::prelude::validation re-exports. Crate-level docs updated to reference ExplicitOnly as the new default and explain mandatory local checks vs explicit full validation semantics.
Test suite updated for new API semantics and defaults tests/insert_with_statistics.rs, tests/proptest_*.rs, tests/large_scale_debug.rs, tests/prelude_exports.rs	All tests switched to insert_best_effort_with_statistics for incremental insertion; duplicate-coordinate tests now expect Err from strict path and Ok(Skipped) from best-effort. Default validation policy assertions changed from OnSuspicion to ExplicitOnly. Focused validation error types updated for new topology guarantee mapping.
User-facing guides and documentation README.md, docs/validation.md, docs/numerical_robustness_guide.md, docs/workflows.md, docs/production_review_remediation_checklist.md	README and guides updated to document dual-API insertion semantics (strict vs best-effort), clarify skipped-insertion handling on pathological data, and show new validation policy defaults and derivation. Checklist item 23 marked complete.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• acgetchell/delaunay#386: This PR directly implements the acceptance criteria of issue #386 by making insert_with_statistics return Err on skipped insertions and providing an explicitly named best-effort API, making it difficult to ignore skipped insertions accidentally via ? operator.

Possibly related PRs

• acgetchell/delaunay#404: Both PRs modify TopologyGuarantee::default_validation_policy() to map PLManifold to ValidationPolicy::ExplicitOnly, with the main PR also integrating that change throughout the codebase and docs.
• acgetchell/delaunay#147: The main PR's insertion API semantics refactor directly builds on the InsertionOutcome and insert_with_statistics model introduced in PR #147, redefining when outcomes are returned as Ok vs Err.

Suggested labels

breaking change, api, enhancement, documentation, rust

Poem

🐰 Skipped insertions once hid in the Ok—
Now strict APIs fail with a proper shock!
Best-effort returns the telemetry gift,
While ExplicitOnly gives validation a lift.
Callers can't miss what's explicit, you see! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly summarizes the main change: splitting strict and best-effort insertion statistics APIs, which is the core feature of this PR.
Description check	✅ Passed	Description directly addresses the changeset, explaining the new API split, validation policy derivation, and breaking change to insert_with_statistics behavior.
Linked Issues check	✅ Passed	Changes fully satisfy issue #386 objectives: insert_with_statistics now returns typed errors for skipped insertions [#386], new insert_best_effort_with_statistics API added for telemetry workflows [#386], validation policy derivation from topology guarantees implemented [#386], and documentation updated across construction, workflows, and robustness guides [#386].
Out of Scope Changes check	✅ Passed	All changes are scoped to issue #386: API semantics changes, new insertion methods, validation policy defaults, and documentation updates related to skipped insertion handling.
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 feat/386-strict-insertion-statistics

---

_{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 -12 complexity

Metric	Results
Complexity	-12

View in Codacy

🟢 Coverage 97.48% diff coverage · +0.00% coverage variation

Metric	Results
Coverage variation	✅ +0.00% coverage variation (-1.00%)
Diff coverage	✅ 97.48% diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (e5a74a1)	62378	56460	90.51%
Head commit (823b8a5)	62391 (+13)	56472 (+12)	90.51% (+0.00%)

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 (#405)	119	116	97.48%

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.}

[codecov]

Codecov Report

❌ Patch coverage is 97.47899% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.50%. Comparing base (e5a74a1) to head (823b8a5).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/delaunay/builder.rs	0.00%	2 Missing ⚠️
src/core/validation.rs	98.95%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #405   +/-   ##
=======================================
  Coverage   90.50%   90.50%           
=======================================
  Files          71       71           
  Lines       62174    62187   +13     
=======================================
+ Hits        56270    56282   +12     
- Misses       5904     5905    +1     

Flag	Coverage Δ
unittests	90.50% <97.47%> (+<0.01%)	⬆️

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

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