feat(query): add 2D edge-to-facet incidence queries

[acgetchell]

• Add 2D try_incident_facets_to_edge_2d and try_interior_facet_for_edge_2d APIs on triangulation query surfaces.
• Re-export FacetHandle from query-focused surfaces for callers that consume simplex-local facet handles outside Pachner-only imports.
• Optimize EdgeKey::try_new to prove live edges from endpoint incidence while preserving typed incidence metadata errors.
• Add edge-key construction benchmarks and document the simplex-local incidence query vocabulary.

Closes #359

[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: 9474c888-7778-46f8-8ab1-bc32e5c94cb5

📥 Commits

Reviewing files that changed from the base of the PR and between b49c6be and a77e46f.

📒 Files selected for processing (1)

• src/core/edge.rs

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

• src/core/edge.rs

---

Walkthrough

Adds 2D edge-to-facet incidence queries, changes EdgeKey::try_new to validate maintained incidence metadata first, registers a Criterion benchmark for EdgeKey::try_new, and updates the related docs, exports, tests, and changelog entries.

Changes

Incidence queries, exports, and validation

Layer / File(s)	Summary
Public query surface and exports docs/api_design.md, src/lib.rs, src/delaunay/query.rs, tests/prelude_exports.rs, tests/trait_bound_ergonomics.rs	FacetHandle is added to the query exports, the 2D incidence vocabulary is documented, the Delaunay wrapper forwards the new edge-to-facet methods, and export/error assertions are updated.
EdgeKey incidence validation src/core/edge.rs, src/core/tds/incidence.rs	EdgeKey::try_new now validates endpoint incidence metadata before falling back to stored-simplex checks, and the incidence tests assert the construction-time error variants.
2D incidence queries and freshness tests src/core/query.rs, tests/pachner_roundtrip.rs	The 2D triangulation query module adds edge-to-facet lookup methods and helper fixtures, and the Pachner tests cover mutation freshness plus stale-error cases.

Benchmark target and release notes

Layer / File(s)	Summary
Benchmark target and release notes Cargo.toml, benches/edge_key_queries.rs, benches/README.md, CHANGELOG.md	A new Criterion benchmark target is registered and documented, and the unreleased changelog entries are updated for the related PR set.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant DelaunayTriangulation
  participant Triangulation
  participant EdgeView

  Client->>DelaunayTriangulation: try_interior_facet_for_edge_2d(edge)
  DelaunayTriangulation->>Triangulation: as_triangulation()
  Triangulation->>EdgeView: validate edge and collect incident facets
  EdgeView-->>Triangulation: FacetHandle / None / EdgeKeyError
  Triangulation-->>Client: Option<FacetHandle> or EdgeKeyError

  Client->>DelaunayTriangulation: try_incident_facets_to_edge_2d(edge)
  DelaunayTriangulation->>Triangulation: as_triangulation()
  Triangulation->>EdgeView: collect incident facet handles
  EdgeView-->>Triangulation: iterator or EdgeKeyError
  Triangulation-->>Client: iterator or EdgeKeyError

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• acgetchell/delaunay#455: Added earlier EdgeKey::try_new validation work that this PR extends with incidence-metadata checks and construction-time error reporting.
• acgetchell/delaunay#476: Refactored the owner-aware EdgeKey/EdgeView behavior that this PR uses in the new edge-validation and query paths.

Suggested labels

documentation, rust

Poem

A rabbit hopped through facets bright,
and sniffed each edge by moonlit light.
try_new hopped first, then queried true,
while benchmarks measured every clue.
🥕 Hop hop—new incidence insight!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: new 2D edge-to-facet incidence queries.
Description check	✅ Passed	The description is directly related to the PR and matches the implemented query, export, benchmark, and docs work.
Linked Issues check	✅ Passed	[#359] The PR adds the requested 2D incidence queries, documents the vocabulary, and includes stale-mutation coverage.
Out of Scope Changes check	✅ Passed	The benchmark, docs, and changelog edits all support the same feature set and do not appear unrelated.
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/359-simplex-local-incidence-queries

---

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

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 48 complexity

Metric	Results
Complexity	48

View in Codacy

🟢 Coverage 97.95% diff coverage · +0.02% coverage variation

Metric	Results
Coverage variation	✅ +0.02% coverage variation (-1.00%)
Diff coverage	✅ 97.95% diff coverage

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (f6efe10)	72771	66651	91.59%
Head commit (a77e46f)	72969 (+198)	66846 (+195)	91.61% (+0.02%)

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 (#478)	293	287	97.95%

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/edge.rs`:
- Around line 221-223: The EdgeView::try_new path currently returns Ok after
finding only one mirrored simplex, which can let a partially stale edge
incidence slip through. Update the validation in try_new and the related helpers
like first_edge_simplex_in_star and endpoint_star_contains_simplex so that both
endpoint stars are checked for all simplices containing the opposite endpoint,
not just the first match. If the current logic is intended to stay, add a
regression test around EdgeView construction that proves an edge with one
missing reverse incidence is rejected before any incomplete incidence result can
be observed.

🪄 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: 07f86c95-1899-406c-8847-407843418469

📥 Commits

Reviewing files that changed from the base of the PR and between f6efe10 and b49c6be.

📒 Files selected for processing (13)

• CHANGELOG.md
• Cargo.toml
• benches/README.md
• benches/edge_key_queries.rs
• docs/api_design.md
• src/core/edge.rs
• src/core/query.rs
• src/core/tds/incidence.rs
• src/delaunay/query.rs
• src/lib.rs
• tests/pachner_roundtrip.rs
• tests/prelude_exports.rs
• tests/trait_bound_ergonomics.rs

[codecov]

Codecov Report

❌ Patch coverage is 97.95222% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.58%. Comparing base (f6efe10) to head (a77e46f).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/core/edge.rs	96.39%	4 Missing ⚠️
src/core/query.rs	98.76%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #478      +/-   ##
==========================================
+ Coverage   91.56%   91.58%   +0.01%     
==========================================
  Files          80       80              
  Lines       72550    72748     +198     
==========================================
+ Hits        66432    66627     +195     
- Misses       6118     6121       +3     

Flag	Coverage Δ
unittests	91.58% <97.95%> (+0.01%)	⬆️

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.