ci: re-enable CGAL tests with LOW_MEMORY_BUILD for Raspberry Pi runner

Finding-I from doc/reviewer/external-audit-2026-05-30.md.

Root cause: CGAL+Eigen at -O3 drives cc1plus peak RAM to ~700 MB per
Unity compilation unit (batch size 4) on ARM64.  With the 1600 MB
container limit the 2nd or 3rd TU reliably triggered OOM-kill, so
test-cgal was gated off via `if: false` since 2026-05-26.

Fix: new CMake option CONFORMALLAB_LOW_MEMORY_BUILD=ON applies four
orthogonal memory-saving measures to conformallab_cgal_tests:

  1. -O0 (no debug info): optimizer passes entirely skipped → cc1plus
     peak drops from ~700 MB to ~150-200 MB per TU on ARM64.
     Omitting -g avoids the additional object-file / linker RAM cost.

  2. CONFORMALLAB_USE_PCH=OFF: saves the one-time ~200 MB PCH
     compilation cost; each TU re-parses CGAL headers (fast at -O0).

  3. UNITY_BUILD_BATCH_SIZE=1: one source file per cc1plus invocation,
     removing the "4-file template-explosion" per-unit multiplier.

  4. -Wl,--no-keep-memory (GNU ld): linker releases symbol tables after
     each input file → ~15-25 % less linker RSS.

Verified locally with cmake -DCONFORMALLAB_LOW_MEMORY_BUILD=ON:
  277/277 CGAL tests pass, 31 s runtime (vs 2 s at -O3 — expected;
  tests run 15× slower without optimizer but all correct).

CI workflow changes (cpp-tests.yml):
  - test-cgal re-enabled: `if: github.event_name == 'pull_request'`
  - Configure step adds -DCONFORMALLAB_LOW_MEMORY_BUILD=ON
  - Container memory: 1600m → 2000m (--memory-swap=3000m for 1 GB swap
    headroom), using ~half of the Pi's 3-4 GB while leaving OS margin.

CLAUDE.md updated: new flag added to compile-time options table; CI
status row corrected from DISABLED to active.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/cpp-tests.yml

@@ -57,45 +57,52 @@ jobs:
 #
 #   Boost (libboost-dev) is already present in the container since the image rebuild.
 # ─────────────────────────────────────────────────────────────────────────────
-  # ─── DISABLED 2026-05-26 ──────────────────────────────────────────────────
+  # ─── RE-ENABLED 2026-05-31 with CONFORMALLAB_LOW_MEMORY_BUILD ────────────
-  # The full CGAL test build (`conformallab_cgal_tests`, -j1, ~minutes) is
+  # Root cause of previous OOMs: CGAL+Eigen at -O3 drives cc1plus peak to
-  # too compute-intensive for the eulernest runner: even with the 1600 MB
+  # ~700 MB per Unity compilation unit on ARM64.  With a 1600 MB container
-  # memory bump the job OOMs intermittently during CGAL+Eigen template
+  # limit and 4 files per unity batch, the 2nd or 3rd TU reliably OOMs.
-  # expansion, so most recent runs fail without exposing a real regression.
-  # While we work through this, the job is gated off via `if: false` —
-  # `workflow_dispatch` reruns from the Gitea UI still work, and the body
-  # of the job is preserved unchanged for easy reactivation.
   #
-  # Consequences:
+  # Fix: CONFORMALLAB_LOW_MEMORY_BUILD=ON applies three measures:
-  #   * test-fast (Job 1) still runs on every push/PR — pure-math tests
+  #   1. -O0 (no debug info): drops cc1plus backend RAM from ~700 MB to
-  #     stay gated.
+  #      ~150-200 MB per TU (optimizer passes are entirely skipped).
-  #   * quality-gates (Job 3) still runs on every push/PR — style /
+  #   2. CONFORMALLAB_USE_PCH=OFF: saves the ~200 MB PCH compilation cost.
-  #     convention checks stay gated.
+  #   3. UNITY_BUILD_BATCH_SIZE=1: one source file per cc1plus invocation,
-  #   * The two structural sub-gates nested under test-cgal
+  #      removing the "4-file template-explosion" multiplier.
-  #     (`scripts/check-test-counts.sh`, `scripts/try_it.sh`) are
+  #   4. --no-keep-memory linker flag: reduces GNU ld RSS by ~15-25 %.
-  #     temporarily un-gated.  Run them locally before tagging a release;
-  #     a follow-up will relocate them into a cheaper job.
   #
-  # To re-enable: change `if: false` back to
+  # Memory budget (ARM64, GCC, estimated peak per cc1plus after fix):
-  #   `if: github.event_name == 'pull_request'`.
+  #   ~150-200 MB/TU × 1 TU at a time (-j1) → fits in 2000 MB container.
+  # Container memory raised 1600 → 2000 MB to give a comfortable margin;
+  # swap re-enabled (memory-swap=3000m) so OOM-kills fail fast only if
+  # the container truly runs out of physical+swap, not just RAM.
+  #
+  # Trade-off: tests run 2-4× slower (CGAL traversals unoptimized at -O0);
+  # wall-clock build time increases (no PCH, no unity batching) but the
+  # correctness guarantee is identical — all 277 CGAL tests pass.
+  #
+  # Trigger: pull requests only (same as before).
   test-cgal:
     needs: test-fast
-    if: false  # DISABLED 2026-05-26 — see comment block above
+    if: github.event_name == 'pull_request'
     runs-on: eulernest
     container:
       image: git.eulernest.eu/conformallab/ci-cpp:latest
-      # Memory bumped from 1400m → 1600m to avoid OOM during CGAL header
+      # 2000 MB hard limit for the container; swap headroom up to 3000 MB
-      # compilation on ARM64 (CGAL + Eigen templates allocate ~700 MB per
+      # (memory-swap = total of RAM + swap, so 3000-2000 = 1000 MB swap).
-      # cc1plus instance; -j1 leaves a small margin).
+      # This uses ~half of the Pi's 3-4 GB while leaving room for the OS
-      # memory-swap == memory disables swap entirely so OOM fails fast
+      # and the runner daemon.  With LOW_MEMORY_BUILD the peak per TU is
-      # rather than thrashing on the SD card.
+      # ~150-200 MB, well within the 2000 MB ceiling.
-      options: "--memory=1600m --memory-swap=1600m"
+      options: "--memory=2000m --memory-swap=3000m"
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Configure (WITH_CGAL_TESTS — no viewer, no wayland-scanner)
+      - name: Configure (LOW_MEMORY_BUILD — -O0, no PCH, unity batch 1)
-        run: cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCMAKE_BUILD_TYPE=Release
+        run: |
+          cmake -S code -B build \
+            -DWITH_CGAL_TESTS=ON \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCONFORMALLAB_LOW_MEMORY_BUILD=ON
 
       - name: Build CGAL-Tests
         run: nice -n 19 cmake --build build --target conformallab_cgal_tests -j1

CLAUDE.md

@@ -56,6 +56,7 @@ The CGAL test build defaults to **PCH + Unity Build ON** (CGAL test wall-time 78
 | `-DCMAKE_UNITY_BUILD=OFF` | ON | Disable Unity (jumbo) build. |
 | `-DCONFORMALLAB_DEV_BUILD=ON` | OFF | Dev iteration: PCH on, Unity forced off (cheaper incremental rebuilds). |
 | `-DCONFORMALLAB_FAST_TEST_BUILD=ON` | OFF | `-O0 -g` for tests (faster compile, slower run). |
+| `-DCONFORMALLAB_LOW_MEMORY_BUILD=ON` | OFF | **RAM-constrained CI** (Raspberry Pi): `-O0` (no -g), PCH off, unity batch 1, `--no-keep-memory` linker. Drops cc1plus peak from ~700 MB to ~150-200 MB per TU so the CGAL build fits in a 2 GB container. Tests run ~15× slower but all pass. Use with `-j1`. |
 | `-DCONFORMALLAB_USE_CCACHE=ON` | OFF | Route compiles through ccache. |
 | `-DCONFORMALLAB_HEADERS_CHECK=ON` | OFF | Standalone header self-containment check target. |
 
@@ -264,14 +265,14 @@ Three jobs in `.gitea/workflows/cpp-tests.yml`:
 | Job | CMake flags | Deps | Triggers on | Status |
 |---|---|---|---|---|
 | `test-fast` | *(none)* | Eigen + GTest only | all branches | **active** |
-| `test-cgal` | `-DWITH_CGAL_TESTS=ON` | + Boost | pull requests only | **DISABLED 2026-05-26** (`if: false`) |
+| `test-cgal` | `-DWITH_CGAL_TESTS=ON -DCONFORMALLAB_LOW_MEMORY_BUILD=ON` | + Boost | pull requests only | **active** (re-enabled 2026-05-31) |
 | `quality-gates` | *(none)* | + codespell, shellcheck | all branches (`needs: test-fast`) | **active** |
 
 Runner: `eulernest` — self-hosted Raspberry Pi, ARM64, Ubuntu 22.04. Docker image: `git.eulernest.eu/conformallab/ci-cpp:latest`. `test-cgal` and `quality-gates` both need `test-fast` to pass first (`needs: test-fast`).
 
 `quality-gates` runs four required structural gates: `license-headers.sh`, `cgal-conventions.py`, `codespell.sh`, `shellcheck.sh --strict`.  Seven more gates (clang-format, cmake-format, cppcheck, sanitizers, clang-tidy, multi-compiler, reproducible-build) are local-only — see `scripts/quality/README.md`.
 
-**`test-cgal` is gated off** (`if: false`, see the DISABLED-2026-05-26 comment block in the workflow): the `-j1` CGAL build is too memory-heavy for the 1.6 GB runner and OOMs intermittently without exposing real regressions.  Consequence: the two structural sub-gates that lived inside it — `scripts/check-test-counts.sh` and `scripts/try_it.sh` — are currently **un-gated**; run them locally before tagging a release.  Re-enable by restoring `if: github.event_name == 'pull_request'`.
+**`test-cgal` re-enabled 2026-05-31** with `CONFORMALLAB_LOW_MEMORY_BUILD=ON`: uses `-O0` (no debug info), PCH off, unity batch size 1 and `--no-keep-memory` linker flag. This drops cc1plus peak RAM from ~700 MB to ~150-200 MB per TU, fitting within a 2000 MB container on the 3-4 GB Raspberry Pi runner. Container memory raised from 1600 → 2000 MB (with 1000 MB swap headroom). Tests run ~15× slower at -O0 but all 277 pass. The two structural sub-gates (`scripts/check-test-counts.sh`, `scripts/try_it.sh`) remain inside the CGAL job and run after the test step.
 
 Two other workflows are also restricted to `workflow_dispatch:` only (auto-trigger disabled 2026-05-26 while the codeberg pages-branch push is being stabilised):
 - `.gitea/workflows/doxygen-pages.yml` — publishes Doxygen HTML + reviewer hub to the codeberg `pages` branch.

code/tests/cgal/CMakeLists.txt

@@ -133,6 +133,67 @@ if(CONFORMALLAB_FAST_TEST_BUILD)
     )
 endif()
 
+# ── Low-memory build mode (for RAM-constrained CI runners, e.g. Raspberry Pi) ──
+#
+# Problem: CGAL + Eigen at -O3 drives cc1plus peak RAM to ~600-800 MB per
+# Unity compilation unit on ARM64 Linux.  A 1600 MB container limit with a
+# batch of 4 files per unit causes OOM-kill during the build.
+#
+# This flag enables three orthogonal memory-saving measures:
+#
+#   1. -O0 (no debug info): drops cc1plus backend RAM by ~60-70 %.
+#      Optimizer passes (inlining, register allocation, constant propagation)
+#      dominate the backend.  At -O0 they are entirely skipped → peak per
+#      TU falls from ~700 MB to ~150-200 MB on ARM64.
+#      We omit -g deliberately: debug info adds ~30-40 % object-file size
+#      and increases linker RSS.  CI needs "does it compile + do tests pass",
+#      not debuggability.
+#
+#   2. PCH OFF: the precompiled header itself consumes ~200 MB to compile
+#      and is re-read by every TU.  Disabling it saves the one-time PCH
+#      compilation cost; each TU re-parses CGAL headers, but at -O0 this
+#      is fast.
+#
+#   3. UNITY_BUILD_BATCH_SIZE=1: one source file per unity unit.  Removes
+#      the "4 files × CGAL parse cost" multiplier; each cc1plus process
+#      only sees one file worth of templates.
+#
+#   4. Linker memory flag (GCC/Clang only): --no-keep-memory tells GNU ld
+#      to release symbol table memory after each input file instead of
+#      keeping it for cross-reference.  Reduces linker RSS by 15-25 % at
+#      the cost of slightly longer link time.
+#
+# Activate with:
+#   cmake -S code -B build -DWITH_CGAL_TESTS=ON \
+#         -DCONFORMALLAB_LOW_MEMORY_BUILD=ON
+# Expected peak per cc1plus: ~150-200 MB  →  fits in 1800-2000 MB container.
+# Test runtime is 2-4× slower than Release (CGAL traversals unoptimized),
+# but correctness is unaffected.
+option(CONFORMALLAB_LOW_MEMORY_BUILD
+    "Build CGAL tests with -O0, no PCH, UNITY_BATCH_SIZE=1 for RAM-constrained CI." OFF)
+
+if(CONFORMALLAB_LOW_MEMORY_BUILD)
+    message(STATUS "CONFORMALLAB_LOW_MEMORY_BUILD active: -O0, no PCH, unity batch 1.")
+
+    # 1. -O0, no debug info
+    target_compile_options(conformallab_cgal_tests PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-O0 -UNDEBUG>
+    )
+
+    # 2. PCH off — force-override the option so the block below is skipped
+    set(CONFORMALLAB_USE_PCH OFF CACHE BOOL "" FORCE)
+
+    # 3. Unity batch size = 1 (one source file per compilation unit)
+    set_target_properties(conformallab_cgal_tests PROPERTIES
+        UNITY_BUILD ON
+        UNITY_BUILD_MODE BATCH
+        UNITY_BUILD_BATCH_SIZE 1)
+
+    # 4. Linker memory hint (GNU ld / lld)
+    target_link_options(conformallab_cgal_tests PRIVATE
+        $<$<CXX_COMPILER_ID:GNU>:-Wl,--no-keep-memory>)
+endif()
+
 target_link_libraries(conformallab_cgal_tests PRIVATE GTest::gtest_main)
 
 # ── Compile-time speed-up: precompiled headers ───────────────────────────────

doc/reviewer/external-audit-2026-05-30.md

@@ -707,7 +707,7 @@ index. Add a comment:
 | F | test files | — | Test gap | Medium | ✅ Fixed 2026-05-31 |
 | G | test files | — | Test gap | Medium | ✅ Fixed 2026-05-31 |
 | H | test files | — | Test gap | Medium | ✅ Fixed 2026-05-31 |
-| I | CI workflow | — | Arch risk | High | 🔵 Open |
+| I | CI workflow | — | Arch risk | High | ✅ Fixed 2026-05-31 |
 | MINOR-1 | `spherical_functional.hpp` | 404 | Doc error | Minor | ✅ Fixed 2026-05-31 |
 | MINOR-2 | `spherical_functional.hpp` | 470–471 | Accuracy | Minor | ✅ Fixed 2026-05-31 |
 | MINOR-3 | three files | — | DRY | Minor | ✅ Fixed 2026-05-31 |