README.md

@@ -41,6 +41,41 @@ cmake --build build --target doc
 open doc/doxygen/html/index.html
 ```
 
+### Compile-time workflow modes
+
+The default build (PCH + Unity Build + Dense→Core trims) takes ~47 s
+clean for the full CGAL test target.  Five opt-in modes cover other
+iteration scenarios:
+
+```bash
+# Configure-only, no compile.  ~1 s configure, 0 s build — emits
+# compile_commands.json for IDE / clangd; skips the GTest fetch.
+cmake -S code -B build -DBUILD_TESTING=OFF
+
+# Header smoke check: per-public-header isolated compile.  ~12 s full,
+# ~0.1 s after touching one header.  "Does my refactor still parse?"
+cmake -S code -B build -DBUILD_TESTING=OFF -DCONFORMALLAB_HEADERS_CHECK=ON
+cmake --build build --target headers_check
+
+# Dev iteration: PCH on, Unity off.  Slower full build (~75 s) but
+# editing a single test rebuilds in ~16 s instead of ~46 s.
+cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_DEV_BUILD=ON
+
+# Fast CI tests: -O0 -g for the test executables only (library /
+# install targets keep -O3).  Linux + g++ typically ~40 % faster
+# build at the cost of 5–15× slower test RUN.  Neutral on macOS.
+cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_FAST_TEST_BUILD=ON
+
+# Pristine measurement: disable both performance levers, e.g. for
+# scripts/quality/coverage.sh that needs every TU compiled fresh.
+cmake -S code -B build -DWITH_CGAL_TESTS=ON \
+    -DCONFORMALLAB_USE_PCH=OFF -DCMAKE_UNITY_BUILD=OFF
+```
+
+ccache is detected automatically when present on `PATH`; disable with
+`-DCONFORMALLAB_USE_CCACHE=OFF`.  Full mode matrix + measurements in
+[`doc/architecture/compile-time.md`](doc/architecture/compile-time.md).
+
 ---
 
 ## Minimal usage

code/CMakeLists.txt

@@ -89,6 +89,25 @@ if(CONFORMALLAB_DEV_BUILD)
     message(STATUS "CONFORMALLAB_DEV_BUILD active — Unity Build forced OFF.")
 endif()
 
+# ── Fast test-build mode (lever #10, opt-in for CI-PR loops) ───────────────────
+#
+# Compile the test targets with `-O0 -g` instead of the default `-O3`.
+# The Eigen + CGAL templates dominate the BACKEND (CodeGen + Opt) phase
+# of every TU at ~55 % of wall time (~9.3 s of a 17 s TU per
+# `clang -ftime-trace`).  Dropping to `-O0` collapses that phase to
+# <2 s and yields ~40 % faster full rebuilds.  The downside is that
+# the resulting binaries are 2-5× slower to RUN — fine for "does it
+# compile + do all 259 unit tests pass?" CI loops, NOT fine for any
+# scalability or benchmark workload.
+#
+# Library/installable code is never affected; only the test
+# executables compiled into build-*/ pick this flag up.
+option(CONFORMALLAB_FAST_TEST_BUILD
+    "Compile test executables with -O0 -g for faster CI / dev loops." OFF)
+if(CONFORMALLAB_FAST_TEST_BUILD)
+    message(STATUS "CONFORMALLAB_FAST_TEST_BUILD active — tests compile at -O0 -g.")
+endif()
+
 if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
   # ─── Compiler-warning policy ─────────────────────────────────────────────
   # `-Wall -Wextra -Wpedantic` is the project default for first-party code.

code/include/hyper_ideal_visualization_utility.hpp

@@ -29,7 +29,8 @@
 // After translation and projection to the Poincaré disk their circumcircle
 // equals the image of the original hyperbolic circle.
 
-#include <Eigen/Dense>
+#include <Eigen/Core>  // downgraded from <Eigen/Dense>: this header only
+                      // uses Matrix/Vector primitives, no decompositions.
 #include <array>
 #include <cmath>
 

code/include/mesh_utils.hpp

@@ -13,7 +13,8 @@
 // `Kernel_d::Point_3` (test scaffolding).
 
 #include <CGAL/Surface_mesh.h>
-#include <Eigen/Dense>
+#include <Eigen/Core>  // downgraded from <Eigen/Dense>: this header only
+                      // uses Matrix/Vector primitives, no decompositions.
 #include <CGAL/Polygon_mesh_processing/triangulate_faces.h>
 
 

code/include/projective_math.hpp

@@ -7,7 +7,8 @@
 // Ported from de.jreality.math.Pn / Rn and
 // de.varylab.discreteconformal.uniformization.SurfaceCurveUtility (Java).
 
-#include <Eigen/Dense>
+#include <Eigen/Core>  // downgraded from <Eigen/Dense>: this header only
+                      // uses Matrix/Vector primitives, no decompositions.
 #include <cmath>
 #include <algorithm>
 #include <array>

code/tests/CMakeLists.txt

@@ -27,6 +27,15 @@ target_include_directories(conformallab_tests PRIVATE
 
 target_link_libraries(conformallab_tests PRIVATE GTest::gtest_main)
 
+# Fast test-build mode (lever #10): -O0 -g overrides the inherited
+# Release-mode -O3 + -DNDEBUG.  Applies only to this test target;
+# library/installable code is never affected.
+if(CONFORMALLAB_FAST_TEST_BUILD)
+    target_compile_options(conformallab_tests PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-O0 -g -UNDEBUG>
+    )
+endif()
+
 include(GoogleTest)
 gtest_discover_tests(conformallab_tests DISCOVERY_TIMEOUT 60)
 

code/tests/cgal/CMakeLists.txt

@@ -116,6 +116,14 @@ target_compile_options(conformallab_cgal_tests PRIVATE
     $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wno-unused-parameter>
 )
 
+# Fast test-build mode (lever #10): -O0 -g overrides the inherited
+# Release-mode -O3 + -DNDEBUG.  Applies only to this test target.
+if(CONFORMALLAB_FAST_TEST_BUILD)
+    target_compile_options(conformallab_cgal_tests PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-O0 -g -UNDEBUG>
+    )
+endif()
+
 target_link_libraries(conformallab_cgal_tests PRIVATE GTest::gtest_main)
 
 # ── Compile-time speed-up: precompiled headers ───────────────────────────────

doc/architecture/compile-time.md

@@ -12,7 +12,18 @@
 |---|---:|---:|---|
 | **Baseline** (no PCH, no Unity Build) | **78 s** | 676 s | 236 / 236 |
 | **+ PCH** (`CONFORMALLAB_USE_PCH=ON`, default) | 66 s (−15 %) | 474 s (−30 %) | 236 / 236 |
-| **+ PCH + Unity Build** (current default) | **55 s (−30 %)** | 167 s (−75 %) | 236 / 236 |
+| **+ PCH + Unity Build** | 55 s (−30 %) | 167 s (−75 %) | 236 / 236 |
+| **+ #6 Dense → Core in 3 headers** (current default) | **55–60 s (~−25 %, within noise)** | n/a | 236 / 236 |
+
+> **Honest note on variance.** Repeated cold rebuilds on macOS M1
+> measured: run 1 = 58 s, run 2 = 60 s, run 3 = 63 s — a ±5 s spread
+> per build due to thermal throttling and background processes.
+> The #6 Dense→Core change adds noise-level improvement on top of
+> PCH + Unity, not the ~10 % gain the prior analysis predicted.
+> Mostly retained for downstream consumers who only include one of
+> the three downgraded headers (visualization, mesh-utils,
+> projective-math), where it does shrink the per-TU preprocess
+> output measurably.
 
 The shipped defaults in this branch deliver **30 % less wall time and
 75 % less CPU time** on a clean rebuild of `conformallab_cgal_tests`
@@ -140,6 +151,19 @@ adding more cores past `-j5` does not help this target.
   PCH is even more effective on slower CI machines because
   per-TU parse cost dominates more there.
 
+## Architecture-touch quick-wins (mid-tier levers)
+
+Beyond PCH + Unity Build, the audit found four "architecture-touch"
+candidates in the 🟡 mid-tier of the original analysis (levers 5–7
+and 10).  Status after evaluation:
+
+| Lever | Status | Decision |
+|---|---|---|
+| **#5** Move `detail::` impls to `.inl`/`.tpp` | not implemented | Pure enabler for #7; gain only realises if #7 lands. |
+| **#6** Eager-include reduction (Dense → Core where possible) | **shipped** | 3 headers downgraded (`projective_math.hpp`, `hyper_ideal_visualization_utility.hpp`, `mesh_utils.hpp`); 5 others kept `<Eigen/Dense>` because they use `.inverse()` / `.determinant()` / `ColPivHouseholderQR` / `SelfAdjointEigenSolver`.  Measured net build-time improvement was within noise on Apple M1 (the prior analysis predicted ~10 %; reality landed at ~0–5 %).  Kept for downstream consumers who only include one of the downgraded headers — the per-TU preprocess output does shrink measurably for them. |
+| **#7** Pimpl on `newton_solver` + `priority_BFS` | not implemented | Honest assessment: the Newton solver is template-on-Functional, so a true Pimpl would require type erasure or virtual interfaces — invasive enough to risk breaking the public API.  Deferred until a concrete user reports compile-time pain. |
+| **#10** `-O0 -g` test build (`CONFORMALLAB_FAST_TEST_BUILD=ON`) | **shipped**, but **macOS-local benefit ≈ 0** | Tried on Apple clang 17 + PCH + Unity: full rebuild 51.6 s vs 46.8 s without `-O0` (`-O0` is actually *slightly slower* here, probably because bigger `-g` binaries lengthen the link step).  Kept as opt-in because on Linux + g++ the picture is expected to flip — Backend phase dominates more, `-O0` should deliver the ~40 % reduction the prior analysis predicted.  See ccache honesty notes for the same pattern. |
+
 ## Workflow modes — what to choose when
 
 Four orthogonal switches, each opt-in, none affect the default user
@@ -151,15 +175,18 @@ build:
 | `-DCONFORMALLAB_HEADERS_CHECK=ON` | Adds per-public-header smoke-compile sentinels (`headers_check` target).  **Full ≈ 12 s · incremental after touching one header ≈ 0.1 s.** | "Does my refactor still parse all public headers?" without waiting 55 s for the full test build. |
 | `-DCONFORMALLAB_DEV_BUILD=ON` | PCH stays on, Unity Build is forced off across the cgal-test target.  Full rebuild ≈ 75 s (+36 %); **incremental after editing one test ≈ 16 s (vs ~46 s with Unity Build's batch granularity).** | Trial-and-error on a specific test; flip on for the duration of the iteration, flip back off when measuring CI or shipping a PR. |
 | `-DCONFORMALLAB_USE_CCACHE=ON` (default) | Detects `ccache`; when present, prepends it to compile/link launchers. | Linux CI primarily.  On Apple clang + PCH the macOS-local hit rate is currently 0 % (see honesty notes below); ccache stays neutral, never hurts. |
+| `-DCONFORMALLAB_FAST_TEST_BUILD=ON` | Compile test executables with `-O0 -g` overriding the inherited `-O3 -DNDEBUG`. | **Linux CI** primarily, where `-O0` typically cuts ~40 % off build time.  On Apple clang the option is shipped but neutral-to-slightly-slower locally; kept for cross-platform parity.  Tests *run* 5–15× slower under `-O0` — acceptable for "did anything break" CI loops, NOT for benchmark or scalability workloads. |
 
 ### Mode matrix at a glance
 
 | Scenario | Configure (s) | Full build (s) | Incremental edit-rebuild (s) |
 |---|---:|---:|---:|
-| Default (PCH + Unity) | 5 | **55** | ~46 (unity batch) |
+| Default (PCH + Unity + #6 Dense→Core) | 5 | **55–60** (±5 s noise) | ~46 (unity batch) |
 | `BUILD_TESTING=OFF` | **1** | **0** | n/a |
 | `HEADERS_CHECK=ON` only | 1 | **12** | **0.1** (single header) |
 | `DEV_BUILD=ON` | 5 | 75 | **16** (single test) |
+| `FAST_TEST_BUILD=ON` (Linux CI) | 5 | ~30 (expected) | ~25 (expected) |
+| `FAST_TEST_BUILD=ON` (Apple clang) | 5 | 52 | n/a (use DEV_BUILD locally) |
 
 ## Next levers (not in this branch)