# Reviewer meeting materials A single landing page for the three documents associated with an external-reviewer meeting. The materials are written for a peer who actively publishes in discrete differential geometry — specifically the decorated-DCE / Penner-coordinates / hyperideal-polyhedra / canonical-tessellations research line — and who would potentially use conformallab++ as numerical infrastructure for their own future experiments. | Document | Audience | Purpose | |---|---|---| | [`briefing.md`](briefing.md) | **the reviewer** | one-page orientation: what the project is, where to look first, what we want from them | | [`questions.md`](questions.md) | **the reviewer** | the 5 concrete decisions we want their opinion on (skim before the meeting) | | [`agenda.md`](agenda.md) | **me** | my own meeting playbook: timing, order, the "no" question, post-meeting memo template | After the meeting, a fourth file `2026-XX-XX-meeting-notes.md` should land here too — the memo template at the bottom of `agenda.md` is the suggested structure. --- # External audit documents (2026-05-30 / 2026-05-31) Twelve self-contained audit documents covering the project from every angle. Each is written so a **fresh session can pick up any finding and act on it** without prior context: every finding has an exact `file:line`, a code snippet, a concrete fix, and acceptance criteria. ## ⛔ Cross-cutting blocker — resolve before any public release or CGAL submission > **G0 — Porting rights.** The original Varylab/TU-Berlin project > (`gitlab.discretization.de:varylab/conformallab`) carries **no license** > (all rights reserved), and conformallab++ is a documented **port** > (derivative work). The right to port + (re)license must be clarified with the > original authors **before** any license decision, public release, or CGAL > submission. Referenced from three audits: `cgal-submission-readiness` (G0/G1), > `dependency-license` (D1/D2 — incl. the unlicensed test meshes), and indirectly > `math-derivation-citation` (provenance of the Sechelmann-2016 primary source). ## Correctness & port fidelity | Document | Focus | Headline | |---|---|---| | [`external-audit-2026-05-30.md`](external-audit-2026-05-30.md) | Correctness bugs | 3 findings (face_energy, Gauss–Bonnet, cotangent doc) — **all resolved** | | [`java-port-audit.md`](java-port-audit.md) | Java→C++ math fidelity | line-by-line port anomalies — mostly resolved | | [`java-ignore-crossvalidation.md`](java-ignore-crossvalidation.md) | `@Ignore` cross-validation | which Java tests were intentionally skipped and why | | [`numerical-stability-audit-2026-05-31.md`](numerical-stability-audit-2026-05-31.md) | FP robustness | N1: FD-Hessian step (`1e-5`) fights Newton tol (`1e-8`); clamps, cancellation, magic constants | | [`math-derivation-citation-audit-2026-05-31.md`](math-derivation-citation-audit-2026-05-31.md) | Derivations & citations | M1 Kolpakov–Mednykh missing from refs; M2 BPS cited "2010" vs "2015" | ## API, performance & packaging | Document | Focus | Headline | |---|---|---| | [`api-performance-audit-2026-05-31.md`](api-performance-audit-2026-05-31.md) | API naming + Newton perf | A1–A5 naming (**decided**, see below); B1: block-FD Hessian exists but solver uses slow full-FD | | [`cgal-submission-readiness-audit-2026-05-31.md`](cgal-submission-readiness-audit-2026-05-31.md) | CGAL submission | G0 (rights), G1 (MIT≠GPL), layout, concept, user manual, test harness | | [`dependency-license-audit-2026-05-31.md`](dependency-license-audit-2026-05-31.md) | Deps + data licensing | D1 matrix predicated on the G0-undermined MIT premise; D2 test meshes have no provenance | | [`usability-audit-2026-05-31.md`](usability-audit-2026-05-31.md) | Examples & docs | U1–U11 — **all resolved** (PR #34) | ## Robustness & operational | Document | Focus | Headline | |---|---|---| | [`test-coverage-error-handling-audit-2026-05-31.md`](test-coverage-error-handling-audit-2026-05-31.md) | Coverage + error handling | C1 solver `ok` flag dropped; coverage gate **decided: 80 % line / 70 % branch / 90 % func** | | [`input-validation-audit-2026-05-31.md`](input-validation-audit-2026-05-31.md) | Malformed input | V3: NaN/Inf vertex coords flow silently into the solver | | [`thread-safety-audit-2026-05-31.md`](thread-safety-audit-2026-05-31.md) | Concurrency | no mutable static state (good); same-mesh concurrency contract undocumented | ## Decisions taken (2026-05-31) - **Coverage gate:** 80 % line / 70 % branch / 90 % function (after fixing the coverage script so it measures honestly — `test-coverage` C2/I5). - **API naming A1–A3 (internal):** standardized on `__` with `[[deprecated]]` aliases — **implemented**, open as **PR #36** (`refactor/api-naming-a1-a3`), 277/277 tests green. - **API naming A4–A5 (public CGAL surface):** decided (`discrete_inversive_distance_euclidean`; both packers return `Circle_packing_result`) but **deferred** until the G0/G1 outcome — no point stabilizing a public API on a package whose release status is open. ## How to act on a finding in a new session Open the relevant audit, pick a finding, follow its "Fix" + "Acceptance criteria". Build/verify with the commands in that document's header. Suggested first batch (low-risk, high-value quick wins): **B1** (HyperIdeal block-FD one-liner), **B3**, **C1**, **C2**, **V3**. ## When to send to the reviewer - **briefing.md** + **questions.md**: as part of the meeting-confirmation email, ~5 business days before the meeting. Subject line: *"Pre-read for our conformallab++ chat (~15 min)"*. - **agenda.md**: never send. This is internal scaffolding. ## Hub-Page durability The reviewer hub HTML at is published from `doc/reviewer/hub.html` in the repo (not from a detached preview branch). This means: * Merging any of the open PRs into `main` triggers `.gitea/workflows/doxygen-pages.yml` which republishes the hub alongside fresh Doxygen HTML — the reviewer URL stays live across merges with no manual intervention. * The hub is source-controlled, so changes are reviewable via PR like any other doc, and old versions live in git history. * The original Doxygen index moves to `/doxygen.html` whenever the hub override is active; both are reachable from the hub itself. ## Quick links the reviewer should bookmark - 🌐 Reviewer-hub landing page: (the hub shows status badges, a "what's new" banner with the most recent delta, the research-alignment table, and direct links into every document below) - 📦 Source: - 📝 Architecture decisions (incl. the Q7 "no" prompt): [`../architecture/locked-vs-flexible.md`](../architecture/locked-vs-flexible.md) - 📐 Schläfli derivation (for Q3): [`../math/hyperideal-hessian-derivation.md`](../math/hyperideal-hessian-derivation.md) - 📚 Literature index (for Q1 + Q3): [`../math/references.md`](../math/references.md) - 🗺️ Per-phase roadmap (for Q1): [`../roadmap/phases.md`](../roadmap/phases.md) - 🧪 Research-track entries with acceptance criteria (Q1 + Q2): [`../roadmap/research-track.md`](../roadmap/research-track.md)