[ofeq-dev]

Summary

Extracts the plane parsing + validation logic from Ex0.py into a dedicated plane_validation module with a clean, deep interface. This is Candidate 1 from the architecture review (Strong recommendation).

Changes

New Modules

File	Purpose
errors.py	Shared UsageError exception (FR-2)
geometry.py	Scalar geometry helpers (_dist, _cross, _sub, _dot)
csv_reader.py	iter_csv_rows(path) — FR-9 tolerant CSV iteration
plane_validation.py	Main module: Plane, PlaneError, parse_planes, count_planes, predicates

Updated Files

• Ex0.py — Imports Plane, PlaneError, parse_planes, count_planes, UsageError from new modules (~200 lines removed)
• tests/test_plane_validation.py — Imports from plane_validation
• tests/test_plane_list.py — Imports from plane_validation and errors
• tests/test_cli.py — Imports Plane, PlaneError, parse_planes from plane_validation
• tests/test_renderer.py — Imports Plane, PlaneError, parse_planes from plane_validation
• README.md — Updated module structure and benchmark results
• benchmarks/results-2026-11-07.md — New 3-repeats cross-product results

Architecture Improvement

Before: Single Ex0.py with all validation logic inline (~200 lines for parsing + predicates)

After: Deep plane_validation module with one small interface:

parse_planes(path) → list[Plane | PlaneError]
count_planes(path) → int

Benefits Achieved

• Locality: All validity logic (EPS, COPLANAR_RTOL, constructibility gates) in one module
• Leverage: CLI, benchmarks, tests all call the same parse_planes through a clean import
• Testability: Tests import plane_validation directly; predicates exercised via real code path

Verification

• All 123 tests pass
• mypy clean on all source files
• NFR-1 hard bar met: 50.1 FPS on croissant.nrrd × croissant.csv (500³ uint8, canonical case)
• Corpus validation: head.csv rectangles, onion-family float dust, lecturer_example error rows all correct
• CLI contract unchanged: python Ex0.py file.nrrd file.csv file.mp4

---

AI Disclosure: This PR was developed with AI assistance (Nemotron 3 Ultra via OpenCode). All architectural decisions were made through a structured grilling loop; code was reviewed and tested before commit.