docs(validation): align the five-level validation contract

[acgetchell]

• Distinguish stored orientation, intrinsic orientability, and geometric orientation across the public documentation.
• Synchronize validation APIs, layered errors, and backend-specific realization guarantees.
• Refresh the mechanical paper table and author TODO scaffolding without replacing manuscript prose.

Closes #445

[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: ac4424e7-a89b-4c51-a7fe-8cbae9a52821

📥 Commits

Reviewing files that changed from the base of the PR and between b4a2ef3 and e152835.

⛔ Files ignored due to path filters (1)

• papers/validation.pdf is excluded by !**/*.pdf

📒 Files selected for processing (8)

• README.md
• docs/README.md
• docs/diagnostics.md
• docs/invariants.md
• docs/limitations.md
• docs/topology.md
• docs/validation.md
• papers/validation.tex

---

Walkthrough

Documentation and paper updates align the five-level validation model with Level 2 stored orientation, Level 3 intrinsic orientability, Level 4 geometric realization, related diagnostics, topology guarantees, and public API mappings.

Changes

Validation model overview

Layer / File(s)	Summary
Validation model overview README.md, docs/README.md	README validation descriptions and tables now distinguish the validation levels, identify orientation_witness() as the Level 3 certificate, and update topology documentation navigation.

Orientation and topology contracts

Layer / File(s)	Summary
Orientation and topology contracts docs/invariants.md, docs/limitations.md, docs/topology.md	Documentation separates stored TDS coherence, intrinsic PL orientability, and geometric realization, while describing periodic quotient behavior and topology guarantees.

Validation semantics and diagnostics

Layer / File(s)	Summary
Validation semantics and diagnostics docs/diagnostics.md, docs/validation.md	Validation layering, orientation error reporting, Level 2 and Level 4 checks, complexity notes, and Level 3 troubleshooting guidance are expanded.

Paper validation API mapping

Layer / File(s)	Summary
Paper validation API mapping papers/validation.tex	The paper adds Level 2–4 orientation distinctions and a table mapping validation levels to public Rust APIs and validation methods.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• acgetchell/delaunay issue 445: The documentation updates address its five-level validation terminology and orientation-contract alignment objectives.
• acgetchell/delaunay issue 521: The changes document periodic orientation coherence, intrinsic orientability, orientation_witness(), and quotient parity validation.

Possibly related PRs

• acgetchell/delaunay#526: Directly related to the documented Level 3 orientability witness and typed non-orientability error.
• acgetchell/delaunay#527: Directly related to periodic facet-parity and intrinsic-orientability validation semantics.

Suggested labels: documentation

Poem

A rabbit reads the levels bright,
With topology tucked in tight.
Stored orders hop, witnesses gleam,
Geometry follows the validation stream.
The paper blooms, the docs align—
Every orienting path can shine!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	Most #445 docs and paper alignment is shown, but notebook-generated figures and validation-check evidence are not verifiable here.	Provide the notebook/figure artifacts or the related diff so the remaining #445 acceptance criteria can be verified.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main docs-focused validation contract update.
Description check	✅ Passed	The description matches the documented validation-contract and paper updates.
Out of Scope Changes check	✅ Passed	All summarized changes stay within the validation-contract documentation and mechanical paper scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/445-validation-architecture

---

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

🟢 Coverage ∅ diff coverage · +0.02% coverage variation

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

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (b4a2ef3)	81699	74823	91.58%
Head commit (e152835)	81699 (+0)	74840 (+17)	91.60% (+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 (#528)	0	0	∅ (not applicable)

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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.58%. Comparing base (b4a2ef3) to head (e152835).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #528      +/-   ##
==========================================
+ Coverage   91.56%   91.58%   +0.02%     
==========================================
  Files          88       88              
  Lines       81488    81488              
==========================================
+ Hits        74614    74631      +17     
+ Misses       6874     6857      -17     

Flag	Coverage Δ
unittests	91.58% <ø> (+0.02%)	⬆️

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.