[M2-GOLD-01] Golden image test infrastructure (TEST-008, canonical 1280x720 frame)

.github/workflows/ci-pull.yml

@@ -771,6 +771,77 @@ jobs:
           ctest --test-dir build-tsan --output-on-failure \
             -R '^ecs_stress$' 2>&1 | tee tsan-ctest-output.txt
 
+  # ------------------------------------------------------------------------
+  # Golden reference regeneration (M2-GOLD-01)
+  #
+  # Label-gated job for the PR lane (label ci:golden-update): renders
+  # the golden fixtures in the reference environment (ubuntu-24.04,
+  # Debug, g++, Mesa surfaceless EGL + llvmpipe) and prints the
+  # resulting PNGs to the job log as single-line base64 between
+  # GOLDEN_REFERENCE_BEGIN / GOLDEN_REFERENCE_END markers. The
+  # committing human decodes, reviews, and commits the references (no
+  # artifact upload — the pull_request token is read-only for those).
+  # The workflow_dispatch-only .github/workflows/golden-update.yml is
+  # the same job for the post-merge master path (workflow_dispatch
+  # only sees workflows on the default branch, so a PR branch cannot
+  # be dispatched). docs/testing.md §6,
+  # tools/golden/references/README.md.
+  # ------------------------------------------------------------------------
+  golden-references:
+    name: Golden references (label-gated, ubuntu-24.04, g++, llvmpipe)
+    runs-on: ubuntu-24.04
+    # 30: build (~1.5 min) + two 1280x720 software-GL renders + font
+    # rasterization, plus runner variance.
+    timeout-minutes: 30
+    if: contains(github.event.pull_request.labels.*.name, 'ci:golden-update')
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install GLFW X11 headers (laige-render)
+        # Same rationale as the main job (see linux-gcc).
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq \
+            libx11-dev libxcursor-dev libxrandr-dev \
+            libxinerama-dev libxi-dev libxext-dev \
+            libegl1 libgl1 libegl-mesa0 libglx-mesa0 libgl1-mesa-dri
+      - name: Configure
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=g++
+      - name: Build laige-golden
+        run: cmake --build build --target laige-golden -j
+      - name: Render the references (--update, build directory)
+        # The references land in the build directory (never in the
+        # source tree — the source-tree copies are committed by a
+        # human from this job's log).
+        env:
+          LAIGE_TEST_FONT_PATH: ${{ github.workspace }}/tests/laige-render/assets/vera.ttf
+        run: |
+          mkdir -p build/golden-references
+          ./build/bin/laige-golden --update --all \
+            --references build/golden-references
+      - name: Verify determinism (in-run compare)
+        # The freshly rendered frames must compare against themselves
+        # within the documented tolerance: a red here means the
+        # environment is not deterministic (or the tolerance contract
+        # broke), and the run's references must not be trusted.
+        env:
+          LAIGE_TEST_FONT_PATH: ${{ github.workspace }}/tests/laige-render/assets/vera.ttf
+        run: |
+          ./build/bin/laige-golden --all \
+            --references build/golden-references \
+            --max-channel-diff 2 --pixel-budget-pct 0.001
+      - name: Print the references (base64, for log extraction)
+        # One block per fixture: the BEGIN/END markers carry the
+        # fixture name (the reference file is <fixture>.png); the
+        # base64 is a single line (base64 -w0).
+        run: |
+          for f in build/golden-references/*.png; do
+            name=$(basename "$f" .png)
+            echo "GOLDEN_REFERENCE_BEGIN $name"
+            base64 -w0 "$f"
+            echo
+            echo "GOLDEN_REFERENCE_END $name"
+          done
+
   windows-msvc:
     name: Windows x64 (MSVC 2022)
     runs-on: windows-2022

.github/workflows/golden-update.yml

@@ -0,0 +1,105 @@
+# ============================================================================
+# Golden reference regeneration (M2-GOLD-01)
+#
+# workflow_dispatch ONLY — the human-approved regeneration path for
+# the committed golden references (tools/golden/references). It
+# never runs on push or pull_request: a reference change is a human
+# decision (docs/testing.md, TEST-008 — no silent tolerance widening,
+# no unreviewed reference churn).
+#
+# This workflow only reaches the POST-MERGE master path:
+# workflow_dispatch only sees workflows on the default branch, so a
+# PR branch cannot be dispatched. The PR-lane equivalent is the
+# label-gated `golden-references` job of
+# .github/workflows/ci-pull.yml (label ci:golden-update).
+#
+# Why the references travel through the log: the PR lane
+# (.github/workflows/ci-pull.yml) cannot upload artifacts (the
+# pull_request token is read-only for artifact uploads), so this job
+# prints each reference to its log as base64 between stable markers:
+#
+#   GOLDEN_REFERENCE_BEGIN <fixture>
+#   <single-line base64>
+#   GOLDEN_REFERENCE_END <fixture>
+#
+# Procedure (documented in tools/golden/references/README.md):
+#   1. Trigger this workflow on the branch that carries the rendering
+#      change (workflow_dispatch, ref = the branch).
+#   2. Read the job log (gh api .../actions/runs/<run-id>/jobs, then the
+#      job log), extract each base64 block, and decode it to
+#      tools/golden/references/<fixture>.png.
+#   3. A human reviews each new PNG against the old reference (the
+#      rendered frame, not a byte diff: the tolerance is what ctest
+#      applies) and commits the PNGs with the change that caused them.
+#
+# The reference environment (documented in
+# tools/golden/references/README.md and asserted by the ctest entry
+# `golden` on every lane that has GL): ubuntu-24.04, CMake Debug, g++
+# (the P0 first lane), Mesa surfaceless EGL + llvmpipe software GL.
+name: golden-update
+
+on:
+  workflow_dispatch:
+
+jobs:
+  generate:
+    name: Golden references (ubuntu-24.04, g++, llvmpipe)
+    runs-on: ubuntu-24.04
+    # Two 1280x720 offscreen renders + font rasterization on software
+    # GL; 30 min is generous headroom on a slow shared runner.
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install GLFW X11 headers (laige-render)
+        # GLFW's X11 backend (GLFW_BUILD_WAYLAND=OFF in src/laige-render/
+        # CMakeLists.txt) needs only the X11 *headers* at configure time
+        # (GLFW 3.5 dlopens the X11/GL libraries at runtime); the
+        # ubuntu-24.04 runner image ships none of them. The libegl/libgl
+        # packages are the RUNTIME GL stack (Mesa surfaceless EGL +
+        # llvmpipe software GL; the engine and GLAD load them by dlopen
+        # at runtime) (M2-GL-01). The identical step in ci.yml's Linux
+        # jobs.
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq \
+            libx11-dev libxcursor-dev libxrandr-dev \
+            libxinerama-dev libxi-dev libxext-dev \
+            libegl1 libgl1 libegl-mesa0 libglx-mesa0 libgl1-mesa-dri
+      - name: Configure
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=g++
+      - name: Build laige-golden
+        run: cmake --build build --target laige-golden -j
+      - name: Render the references (--update, build directory)
+        # The references land in the build directory (never in the
+        # source tree — the source-tree copies are committed by a human
+        # from this run's log, step 3 of the header procedure).
+        env:
+          LAIGE_TEST_FONT_PATH: ${{ github.workspace }}/tests/laige-render/assets/vera.ttf
+        run: |
+          mkdir -p build/golden-references
+          ./build/bin/laige-golden --update --all \
+            --references build/golden-references
+      - name: Verify determinism (in-run compare)
+        # The freshly rendered frames must compare against themselves
+        # within the documented tolerance: a red here means the
+        # environment is not deterministic (or the tolerance contract
+        # broke), and the run's references must not be trusted.
+        env:
+          LAIGE_TEST_FONT_PATH: ${{ github.workspace }}/tests/laige-render/assets/vera.ttf
+        run: |
+          ./build/bin/laige-golden --all \
+            --references build/golden-references \
+            --max-channel-diff 2 --pixel-budget-pct 0.001
+      - name: Print the references (base64, for log extraction)
+        # One block per fixture: the BEGIN/END markers carry the fixture
+        # name (the reference file is <fixture>.png); the base64 is a
+        # single line (base64 -w0). The extraction step (procedure
+        # step 2) greps the job log for these markers.
+        run: |
+          for f in build/golden-references/*.png; do
+            name=$(basename "$f" .png)
+            echo "GOLDEN_REFERENCE_BEGIN $name"
+            base64 -w0 "$f"
+            echo
+            echo "GOLDEN_REFERENCE_END $name"
+          done

CMakeLists.txt

@@ -272,4 +272,5 @@ if(LAIGE_BUILD_TESTS)
   add_subdirectory(tools/run)      # M1-HEAD-01: laige-run (+ smoke test)
   add_subdirectory(tools/replay)   # M1-DET-03: laige-replay
   add_subdirectory(tools/scene-iso)  # M2-SCENE-01: laige-scene-iso (+ CLI determinism gate)
+  add_subdirectory(tools/golden)     # M2-GOLD-01: laige-golden (+ golden entry)
 endif()

deps.lock

@@ -52,9 +52,9 @@
       "owner": "src/laige-render",
       "source_url": "https://github.com/nothings/stb",
       "source_commit": "2c980bb59875b0d32144a71867fbdebb2f77cd20",
-      "sha256": "8f06584600718842d16098b13df213d0ec9ffecbf782a6fbadec3f4abf570685",
+      "sha256": "cd6a0a53710601af128ec2af52b970b7082eb70277153c0ead6b01b4c9b82487",
       "license": "MIT-like (stb's no-warranty license; the text lives in deps/stb/LICENSE)",
-      "justification": "PRD §11 (font rasterization, FR-2.8 bitmap fonts P0 — the stb_truetype row): single-header C font rasterizer that M2-TEXT-01 uses to build the fixed bitmap glyph atlas (the M2-TEXT-03 SDF step reuses the same header); the implementation compiles in the laige-stb target with the plain compiler policy, pinned by this lock (M2-TEXT-01, ADR 0009)"
+      "justification": "PRD §11 (font rasterization + texture decode/encode — the stb_image / stb_image_write / stb_truetype row): single-header C font rasterizer that M2-TEXT-01 uses to build the fixed bitmap glyph atlas (the M2-TEXT-03 SDF step reuses the same header) and the PNG codec that M2-GOLD-01's laige-golden tool uses to capture/compare/commit golden reference frames; the implementations compile in the laige-stb target with the plain compiler policy, pinned by this lock (M2-TEXT-01 ADR 0009; M2-GOLD-01)"
     }
   ]
 }

deps/README.md

@@ -5,7 +5,9 @@ PRD §11, NFR-8.6, DEP-005). This directory landed with **M0-DEP-01**: the
 lock file, the configure-time hash check, and **GoogleTest** (dev-only);
 **M2-GL-01** adds **GLFW** (windowing) and the **GLAD-generated GL 3.3
 loader** (GL function access), **M2-GL-03** adds **GLM** (rendering-side
-math), and **M2-TEXT-01** adds **stb_truetype** (font rasterization) —
+math), **M2-TEXT-01** adds **stb_truetype** (font rasterization), and
+**M2-GOLD-01** extends the same pinned stb entry with **stb_image /
+stb_image_write** (the PNG codec for golden reference frames) —
 all for `src/laige-render`.
 
 ## deps.lock
@@ -48,7 +50,7 @@ recomputes the tree hash and rejects the configure.
 | GLFW | 3.5.1 | `glfw/` | `src/laige-render` | zlib | PRD §11 windowing row (M2-GL-01: windowed + hidden-window context creation on all P0 OSes) |
 | GLAD (generated) | 2.0.8 | `glad/` | `src/laige-render` | WTFPL OR CC0-1.0 AND Apache-2.0 | PRD §11 GL-loader row (M2-GL-01: GL 3.3 core function access; the vendored artifact is the reproducible `gladv2 --api gl:core=3.3` output, not a source checkout) |
 | GLM | 1.0.3 | `glm/` | `src/laige-render` | MIT | PRD §11 math-foundation row (M2-GL-03: rendering-side value types for cameras/projection matrices; the full `glm/` tree of the pinned tag) |
-| stb (stb_truetype) | 2026-08-01 | `stb/` | `src/laige-render` | MIT-like (stb license) | PRD §11 font-rasterization row (M2-TEXT-01: bitmap glyph atlas rasterization for FR-2.8 P0; the single header `stb_truetype.h` + `LICENSE`, pinned commit — stb publishes no release tags) |
+| stb (stb_truetype, stb_image, stb_image_write) | 2026-08-01 | `stb/` | `src/laige-render` | MIT-like (stb license) | PRD §11 font-rasterization + texture decode/encode row (M2-TEXT-01: bitmap glyph atlas rasterization for FR-2.8 P0; M2-GOLD-01: the `laige-golden` tool's golden-frame PNG capture/comparison; the three headers + `LICENSE`, pinned commit — stb publishes no release tags) |
 
 See [ADR 0004](../docs/decisions/0004-google-test-vendoring.md) (GoogleTest),
 [ADR 0007](../docs/decisions/0007-glfw-glad-vendoring.md) (GLFW + GLAD),