feat(reference)!: publish deterministic C++ oracle fixtures

.github/CONTRIBUTING.md

@@ -50,13 +50,19 @@ substantial implementation so its maintenance value and scope can be agreed upon
 
    `just check` is the fast, non-mutating source and tooling gate, including the repository-owned Semgrep policy and
    its fixtures. `just ci` adds the supported build and complete 24-entry CTest suite: all 103 doctest unit scenarios
-   and 23 CLI integration tests. `just build-parallel` builds the distinct
-   CGAL/oneTBB configuration and runs the same scientific suite plus the
+   and 23 CLI integration tests. `just build-parallel` builds the distinct CGAL/oneTBB configuration and runs the same
+   scientific suite plus the
    replayable parallel stress launcher, for 25 entries. When changing C++ behavior, also run
    `just clang-tidy` with the pinned LLVM 22 toolchain and review its advisory diagnostics.
    GitHub Actions runs `just ci` in its Ubuntu GCC, Ubuntu Clang, macOS AppleClang, and Windows MSVC jobs. The two
-   Ubuntu jobs also run `just build-parallel` to exercise the opt-in CGAL/oneTBB contract. The Windows job continues
-   to compile with native MSVC; LLVM tooling is used only for source formatting. Toolchain setup is pkgx-first;
+   Ubuntu jobs also run `just build-parallel` to exercise the opt-in CGAL/oneTBB contract. Sanitizer and coverage
+   builds keep Release assertion semantics while adding their own debug information and optimization settings. A
+   separate full-suite Debug job is intentionally omitted because several fixtures traverse invalid intermediate
+   triangulations and abort on CDT++ invariant assertions. Use `just build-debug` to compile production targets with
+   CDT++ assertions enabled and run the 21 compatible CLI integration CTests. That preset defines `CGAL_NDEBUG` for
+   supported move paths while excluding `cdt`, `cdt-no-output`, and the doctest unit fixtures because they trip
+   project assertions on deliberately invalid intermediate states. The Windows job continues to compile with native
+   MSVC; LLVM tooling is used only for source formatting. Toolchain setup is pkgx-first;
    because pkgx does not currently publish its CMake and Ninja packages for Windows, that job uses the exact Justfile
    pins available as PyPI wheels through `uv tool install --no-build`.
 

.github/workflows/ci.yml

@@ -31,24 +31,32 @@ jobs:
             compiler_package: gnu.org/gcc@16
             cc: gcc
             cxx: g++
+            compiler_cache: ccache
+            compiler_cache_key: gcc-16
             run_parallel_contract: true
           - name: Ubuntu Clang
             os: ubuntu-latest
             compiler_package: llvm.org@22
             cc: clang
             cxx: clang++
+            compiler_cache: ccache
+            compiler_cache_key: clang-22
             run_parallel_contract: true
           - name: macOS AppleClang
             os: macos-latest
             compiler_package: ""
             cc: clang
             cxx: clang++
+            compiler_cache: ""
+            compiler_cache_key: none
             run_parallel_contract: false
           - name: Windows MSVC
             os: windows-latest
             compiler_package: ""
             cc: cl
             cxx: cl
+            compiler_cache: ""
+            compiler_cache_key: none
             run_parallel_contract: false
 
     steps:
@@ -81,6 +89,7 @@ jobs:
         run: |
           {
             echo "cmake=$(just --evaluate cmake_version)"
+            echo "ccache=$(just --evaluate ccache_version)"
             echo "llvm=$(just --evaluate llvm_version)"
             echo "ninja=$(just --evaluate ninja_version)"
             echo "ninja-windows-wheel=$(just --evaluate ninja_windows_wheel_version)"
@@ -153,21 +162,49 @@ jobs:
         with:
           vcpkgDirectory: ${{ github.workspace }}/.cache/vcpkg
 
+      - name: Restore compiler cache
+        if: matrix.compiler_cache != ''
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: .cache/ccache
+          key: ccache-v1-${{ runner.os }}-${{ matrix.compiler_cache_key }}-${{ github.sha }}
+          restore-keys: |
+            ccache-v1-${{ runner.os }}-${{ matrix.compiler_cache_key }}-
+
       - name: Run the canonical local CI contract
         env:
+          CCACHE_BASEDIR: ${{ github.workspace }}
+          CCACHE_COMPILERCHECK: content
+          CCACHE_DIR: ${{ github.workspace }}/.cache/ccache
+          CCACHE_MAXSIZE: 1G
           CC: ${{ matrix.cc }}
+          CDT_COMPILER_CACHE: ${{ matrix.compiler_cache }}
           CDT_PKGX_COMPILER_PACKAGE: ${{ matrix.compiler_package }}
           CXX: ${{ matrix.cxx }}
         run: just ci
 
       - name: Run the opt-in CGAL/oneTBB contract
         if: matrix.run_parallel_contract
         env:
+          CCACHE_BASEDIR: ${{ github.workspace }}
+          CCACHE_COMPILERCHECK: content
+          CCACHE_DIR: ${{ github.workspace }}/.cache/ccache
+          CCACHE_MAXSIZE: 1G
           CC: ${{ matrix.cc }}
+          CDT_COMPILER_CACHE: ${{ matrix.compiler_cache }}
           CDT_PKGX_COMPILER_PACKAGE: ${{ matrix.compiler_package }}
           CXX: ${{ matrix.cxx }}
         run: just build-parallel
 
+      - name: Report compiler cache statistics
+        if: ${{ always() && matrix.compiler_cache != '' }}
+        env:
+          CCACHE_DIR: ${{ github.workspace }}/.cache/ccache
+          CCACHE_VERSION: ${{ steps.tool-versions.outputs.ccache }}
+        run: >-
+          pkgx "+ccache.dev@${CCACHE_VERSION}" --
+          ccache --show-stats
+
   build:
     name: build
     if: ${{ always() }}

.gitignore

@@ -45,6 +45,7 @@ grid_d
 output*
 errors
 *.off
+!reference/raw/**/*.off
 *.dat
 slurm-*.out
 

CMakeLists.txt

@@ -79,8 +79,13 @@ include(cmake/PreventInSourceBuilds.cmake)
 # Link this 'library' to set the c++ standard / compile-time options requested
 add_library(project_options INTERFACE)
 target_compile_features(project_options INTERFACE cxx_std_23)
+# Debug keeps CDT++ assertions enabled. CGAL's internal checks are disabled
+# because supported move paths deliberately traverse invalid intermediate
+# triangulations before restoring their invariants.
 target_compile_definitions(
-  project_options INTERFACE CDT_BUILD_CONFIGURATION="$<CONFIG>")
+  project_options
+  INTERFACE CDT_BUILD_CONFIGURATION="$<CONFIG>"
+            $<$<CONFIG:Debug>:CGAL_NDEBUG>)
 
 if(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang")
   option(ENABLE_BUILD_WITH_TIME_TRACE "Enable -ftime-trace to generate time tracing .json files on clang" OFF)

CMakePresets.json

@@ -48,7 +48,7 @@
       },
       "cacheVariables": {
         "CMAKE_CXX_COMPILER": "clang++",
-        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "CMAKE_BUILD_TYPE": "Release",
         "CMAKE_CXX_FLAGS": "-Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion -Wcast-qual -Wformat=2 -Werror=float-equal -Wshadow -Wcast-align -Wunused -Wnull-dereference -Wdouble-promotion -Wimplicit-fallthrough -Wextra-semi -Woverloaded-virtual -Wnon-virtual-dtor -Wold-style-cast",
         "ENABLE_CACHE": false,
         "ENABLE_TESTING": true
@@ -61,7 +61,7 @@
       "inherits": "common",
       "binaryDir": "${sourceDir}/out/build/reference",
       "cacheVariables": {
-        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "CMAKE_BUILD_TYPE": "Release",
         "ENABLE_CACHE": false,
         "ENABLE_TESTING": true
       }
@@ -79,9 +79,12 @@
     {
       "name": "debug",
       "displayName": "Local debug build",
-      "description": "Configure an optional debug build for interactive diagnostics",
+      "description": "Configure an optional debug build with CDT++ assertions enabled and CGAL checks disabled",
       "inherits": "common",
+      "binaryDir": "${sourceDir}/out/build/debug",
       "cacheVariables": {
+        "BUILD_TESTING": true,
+        "CGAL_DO_NOT_WARN_ABOUT_CMAKE_BUILD_TYPE": true,
         "CMAKE_BUILD_TYPE": "Debug",
         "ENABLE_CACHE": false,
         "ENABLE_TESTING": true
@@ -132,6 +135,15 @@
       "name": "parallel",
       "displayName": "Build the supported CGAL/oneTBB targets",
       "configurePreset": "parallel"
+    },
+    {
+      "name": "debug",
+      "displayName": "Build production targets with CDT++ assertions enabled",
+      "configurePreset": "debug",
+      "targets": [
+        "cdt",
+        "initialize"
+      ]
     }
   ],
   "testPresets": [
@@ -160,6 +172,27 @@
         "noTestsAction": "error",
         "stopOnFailure": false
       }
+    },
+    {
+      "name": "debug-cli",
+      "displayName": "Run CLI integration tests with CDT++ assertions",
+      "description": "Run only the Debug CLI tests; unit fixtures that trip CDT++ assertions on deliberately invalid intermediate states are excluded",
+      "configurePreset": "debug",
+      "filter": {
+        "exclude": {
+          "label": "^debug-incompatible$"
+        },
+        "include": {
+          "label": "^integration$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      },
+      "execution": {
+        "noTestsAction": "error",
+        "stopOnFailure": false
+      }
     }
   ]
 }

Justfile

@@ -15,13 +15,15 @@ cmake_minimum_version := "4.4.0"
 cmake_version := "4.4.0"
 ninja_version := "1.13.2"
 ninja_windows_wheel_version := "1.13.0"
+ccache_version := "4.13.6"
 doxygen_version := "1.17.0"
 graphviz_version := "15.1.0"
 zizmor_version := "1.28.0"
 primary_binary := if os_family() == "windows" { "out/build/reference/src/cdt.exe" } else { "out/build/reference/src/cdt" }
 rng_benchmark_binary := if os_family() == "windows" { "out/build/reference/tests/CDT_rng_benchmark.exe" } else { "out/build/reference/tests/CDT_rng_benchmark" }
 cgal_benchmark_binary := if os_family() == "windows" { "out/build/reference/tests/CDT_cgal_benchmark.exe" } else { "out/build/reference/tests/CDT_cgal_benchmark" }
 parallel_cgal_benchmark_binary := if os_family() == "windows" { "out/build/parallel/tests/CDT_cgal_benchmark.exe" } else { "out/build/parallel/tests/CDT_cgal_benchmark" }
+reference_fixture_binary := if os_family() == "windows" { "out/build/reference/tests/CDT_reference_fixture.exe" } else { "out/build/reference/tests/CDT_reference_fixture" }
 
 # Build the supported configuration through the repository build script.
 [group('workflows')]
@@ -33,14 +35,19 @@ build:
 build-parallel:
     {{ if os_family() == "windows" { "cmd.exe //d //c 'scripts\\build.bat parallel'" } else { "just _build-parallel-unix" } }}
 
+# Build production targets in Debug mode and run the supported CLI integration tests.
+[group('workflows')]
+build-debug:
+    {{ if os_family() == "windows" { "cmd.exe //d //c 'scripts\\build.bat debug'" } else { "just _build-debug-unix" } }}
+
 # Run fast, non-mutating local validation.
 [group('workflows')]
-check: _justfile-check _format-check _yaml-check _action-lint _zizmor _whitespace-check _cmake-check release-check python-check semgrep semgrep-test
+check: _justfile-check _format-check _yaml-check _action-lint _zizmor _whitespace-check _cmake-check release-check python-check reference-check semgrep semgrep-test
     @echo "Checks complete."
 
 # Run the comprehensive pre-commit/pre-push validation gate.
 [group('workflows')]
-ci: check _pinact-check build
+ci: check _pinact-check reference-generated-check
     @echo "CI validation complete."
 
 # Configure dependencies before CodeQL begins tracing the C++ build.
@@ -102,6 +109,38 @@ benchmark-cgal-parallel threads='1 2 4' simplices='640' repetitions='5' moves='5
         "${thread_count}" {{ quote(warmups) }}
     done
 
+# Print the raw deterministic C++ oracle for the versioned reference package.
+[group('workflows')]
+reference-fixtures: build
+    {{ reference_fixture_binary }}
+
+# Regenerate every raw reference artifact and manifest from one clean commit.
+[group('workflows')]
+reference-regenerate: _sync-python-dev
+    uv run --no-sync python scripts/generate_reference_fixtures.py --check-clean
+    just build
+    just build-parallel
+    uv run --no-sync python scripts/generate_reference_fixtures.py
+    just reference-check
+    just reference-archive-check
+
+# Validate schemas, exact topology, numerical oracles, and provenance.
+[group('workflows')]
+reference-check: _sync-python-dev
+    uv run --no-sync python scripts/validate_reference_fixtures.py
+
+# Require one clean source revision before an archival tag or publication.
+[group('workflows')]
+reference-archive-check: _sync-python-dev
+    uv run --no-sync python scripts/validate_reference_fixtures.py \
+        --provenance-only
+
+# Rebuild the C++ fixture producer and compare its canonical scientific payload.
+[group('workflows')]
+reference-generated-check: build _sync-python-dev
+    uv run --no-sync python scripts/validate_reference_fixtures.py \
+        --generated-only --fixture-binary {{ quote(reference_fixture_binary) }}
+
 # Apply safe automatic formatting to C++/Python source and the Justfile.
 [group('workflows')]
 fix: _format-fix python-fix
@@ -159,10 +198,14 @@ semgrep: _sync-python-dev
     set -euo pipefail
     state_dir="$(mktemp -d "${TMPDIR:-/tmp}/cdt-semgrep-state.XXXXXX")"
     trap 'rm -rf "$state_dir"' EXIT
-    SEMGREP_LOG_FILE="$state_dir/semgrep.log" SEMGREP_SEND_METRICS=off \
+    SEMGREP_ENABLE_VERSION_CHECK=0 SEMGREP_LOG_FILE="$state_dir/semgrep.log" SEMGREP_SEND_METRICS=off \
         SEMGREP_SETTINGS_FILE="$state_dir/settings.yml" SEMGREP_VERSION_CACHE_PATH="$state_dir/version-cache" \
         uv run --no-sync semgrep scan --error --strict --timeout 120 --no-git-ignore \
-            --config semgrep.yaml --exclude tests/semgrep .github include src tests
+            --config semgrep.yaml \
+            --exclude .cache --exclude .venv --exclude venv \
+            --exclude 'build*' --exclude 'cmake-build*' --exclude cov-int --exclude coverage \
+            --exclude html --exclude out --exclude Testing --exclude vcpkg_installed \
+            --exclude tests/semgrep .
 
 # Test repository-owned Semgrep rules against annotated positive and negative fixtures.
 [group('workflows')]
@@ -311,6 +354,15 @@ _build-parallel-unix:
     fi
     exec ./scripts/build.sh parallel
 
+[private]
+_build-debug-unix:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if command -v pkgx >/dev/null; then
+      exec ./scripts/pkgx-build.sh --preset debug
+    fi
+    exec ./scripts/build.sh debug
+
 [private]
 _codeql-phase phase:
     #!/usr/bin/env bash