C++ Renderer Improvement Campaign (2026-07)

C++ Renderer Improvement Campaign (2026-07)#

Working log of the “fix all” pass over Src/GraphicsEngineVulkan, driven by a three-way analysis (architecture/complexity, testing, performance). Each unit ships only after: container debug build green, the full commit suite (72 tests at campaign start, 697 as of 2026-10-01), and a validation-layer-clean runtime check where rendering changed.

Shipped#

Commit	Unit	Notes
`675e5ee0`	Consume the cascaded shadow map	The CSM pass rendered 3×2048² depth layers per frame that no compiled shader sampled. Forward lighting now selects a cascade by distance + PCF (GUI slider) + `cascaded_shadow_intensity`. Same commit: `GLM_FORCE_DEPTH_ZERO_TO_ONE` moved from App.cpp (no projection math) to the engine target — camera/CSM projections were using [-1,1] depth in a [0,1] API; GUI cascade default synced to `MAX_CASCADES`
`c2be278e`	Real fuzzing + CI + ASan presets	`ObjLoader::loadVertices` bounds-hardened (negative/out-of-range indices → OOB reads; `exit()` on parse error killed the app on GUI model reload). `obj_parsing_fuzz_test` mirrors the walk; 60 s coverage-guided ASan fuzzing, zero findings. Stale `RendererTest.BasicSetup` ctest filter removed; fuzz target added to Linux CI; `x64-ClangCL-Windows-Debug-ASan` presets added (matrix had TSan only)
`1a088886`	Fail-fast `ASSERT_VULKAN`	Was log-and-continue → null-handle UB later. Exceptions are disabled project-wide (`/EHs-`, `VULKAN_HPP_NO_EXCEPTIONS`), so the macro now logs critical + `abort()`. All 41 call sites audited: creation/allocation only
`cb5989fb`	Draw-loop perf	Invariant descriptor set bound once instead of per mesh; per-draw `std::vector<vk::Buffer>` heap churn removed (rasterizer + all CSM cascade loops)
`cab3fa08`	Deferred-path shadows	Shared `common/cascaded_shadow.glsl`; both lighting paths use the same cascades
`f94a0b47`	Pipeline cache	Persisted in `VulkanDevice`, all pipeline sites consume it; two-run verified (saves on graceful exit only)
`325a7fb9` (folded in)	RAII leaf types	`VulkanBuffer`/`VulkanImage` became move-only with destructor release during the VMA rewrite; verified via full teardown tests + clean exit
`70c2da4b`	Staging ring + fence-synced uploads	Per-upload `queue.waitIdle()` → per-submit fence; one persistent mapped staging buffer with geometric growth
`325a7fb9`	VMA adoption	Allocator moved into `VulkanDevice`; `VulkanBuffer`/`VulkanImage` on `vmaCreateBuffer/Image`; persistently mapped UBOs via `MAPPED_BIT`; RT device addresses intact. Verified incl. RT/path-trace GPU tests
`5f07a019`	glTF strip/fan triangulation	The primitive filter dropped any TRIANGLE_STRIP/FAN mesh entirely. Both now triangulate into the list (strips alternate winding, fans share vertex 0; points/lines still skipped); material ids per emitted triangle. CPU test: 4-vertex strip -> 2 triangles (was an empty parse). 98/98, validation-clean
`1b382036`	glTF flat normals when NORMAL is absent	A normal-less glTF defaulted every vertex to (0,1,0) - lit as if all faces pointed up. Now per-triangle geometric flat normals from world positions (OBJ-path parity), degenerate triangles skipped. CPU red/green on an XY-plane triangle (true normal +/-Z). 97/97, validation-clean
`39698f7e`	Swapchain recreate: oldSwapchain handoff + checked create	recreate destroyed everything then created with oldSwapchain=nullptr (no image recycling); createSwapchainKHR’s result was unchecked (null handle -> UB on resize/surface-lost races). Now the old handle survives as the handoff and is destroyed after the new one; ASSERT_VULKAN on the result. Surface-lost was already routed to fatal. Resize path not headless-testable; init + result check validation-clean every launch. 96/96
`7923ffeb`	glTF input-surface hardening + fuzz target	GltfLoader trusted cgltf on GUI-picked files: buffer-view offset+size unchecked vs buffer->size (OOB read), base64 length maths underflowed for sub-quad URIs (~SIZE_MAX read), cgltf_validate never called. All three fixed; new self-contained gltf_parsing_fuzz_test in both CI lanes + two CPU regression tests. 96/96, validation-clean
`07631be3`	Single-pass multiview cascades	One render pass with a cascade view mask + full-array framebuffer replaces 3 passes and a pass-through geometry shader (deleted); gl_ViewIndex picks the matrix in the VS; union caster culling keeps the per-cascade test’s safety property. Coverage identical (12.276% vs 12.267%); ShadowCascades 0.0477 -> 0.0408 ms (-14%). 94/94, validation-clean
`6b423fbf`	White-furnace golden	KATAGLYPHIS_PT_FURNACE debug mode (uniform env + albedo 1); an unbiased estimator converges every pixel to exactly tonemap(env) = 186 regardless of geometry. Green: 186.005 mean, uniformity 1.0. Reds: spurious bounce 1/pi -> 136.9/0.25 (fires); RR-reweight removal -> 185.54 (real, sub-threshold on an open scene, documented not chased). Probes were edit-and-run shader cycles - runtime glslc paying off same-day. 94/94, validation-clean
`61df6ddf`	Kompute playground gated OFF by default	The demo linked kompute with exceptions enabled in every build - and can never conform (kompute headers throw; -fno-exceptions is a compile error there). KATAGLYPHIS_BUILD_KOMPUTE_PLAYGROUND=OFF wraps the target AND kompute’s configure/subdir; the version-resolution machinery survives for the ON path. Gated configure: zero kompute lines. 93/93
`e18dd19f`	sRGB texture views	PNG/JPG bytes are sRGB-encoded; UNORM views fed gamma-space values into linear lighting with post’s encode on top. eR8G8B8A8Srgb for uploads + default; hardware decodes at sample time, mips filter in linear. A/B census: 16.5k pixels shift (3.5%, exactly the textured content), max delta 243 - whole-frame means were blind to it. Parity held 0.20. 93/93, validation-clean
`cfca331b`	glTF from the GUI + reloadModel hardening	The picker scan was == “.obj” (bundled cube.glb unpickable); reloadModel force-fed every file to the OBJ parser; add_model dereferenced null on failed loads. All three fixed; the listing-consistency test had encoded OBJ-only as its contract and now asserts the loadable set. Red proofs: list test fails “OBJ-only again” on the old scan; the null test dies with SEH 0xC0000005 on the old binary. 93/93
`3b90b9b8`	Deferred: world-position G-buffer target removed	The largest G-buffer attachment (full-res rgba16f position) stored what depth already encodes; the lighting subpass reconstructs from the depth input attachment (inv_view * inv_proj * NDC, divide). Renumbered the whole pass (6->5 attachments, 4->3 outputs, 5->4 inputs/bindings); globalUBO now fragment-visible. Parity 0.200 vs 0.205 before - the reconstruction agrees better than the paths already disagreed. Main 0.0647 -> 0.0639 ms (scene too small for bandwidth to register - the claim is structural). 91/91, validation-clean
`fb6f53f9`	Runtime glslc resolution + loud compile failures	The baked container glslc path made host runtime compilation a silent no-op (system() unchecked) - the root of the spv-staleness saga. Resolves at call time (baked -> VULKAN_SDK/Bin -> PATH); nonzero exits log the stale spv being served. Proven: touch a kernel, run a golden, the engine regenerates the spv mid-run. GLSL iteration no longer needs manual compile-shaders.ps1. 91/91, validation-clean
`126ccc9c`	Multi-model textures + untextured-mtl Kd fix	The shared texture array bound model 0’s textures only - added models’ local IDs collided with them. Per-model texture_offset in ObjectDescription + 4 shader sites + flattened binding. En route: materials WITHOUT map_Kd got textureID 0 (not -1) - the bundled dinosaur rendered its Kd colours as flat white for the engine’s whole life; loader fixed, CPU red/green on the shipped asset. Golden oracle earned: colour-spread was blind twice (dino ships no textures; sponza bricks near-greyscale) - texture-DETAIL fraction works: 0.045 green vs exactly 0 on the old binding, wall pinned at 17% of crop by a forced-red probe first. ABI note: growing the shared struct needed the fresh-container sequence (suite exit 3). 91/91, validation-clean
`81799ea2`	PT estimator: 1/pi on NEE	The throughput carries albedo, so NEE must carry the Lambertian 1/pi - directly lit surfaces were pi-times hot vs the sky transport and vs forward. Bounce path needed NOTHING (cosine sampling of a Lambertian cancels pi and cosine exactly - the survey’s “no PDF division” was wrong for that half). Measured: rig lit crop 208.5 -> 188.2 (forward: 158.1; gap = PT’s indirect sky). Furnace golden folded into the PT-goldens remainder (wants a uniform-env toggle). 89/89, validation-clean
`91269849`	Traced world follows GUI transforms	The transform path updated object descriptions but never the AS - RT/PT rendered the old pose forever. TLAS-only rebuild (BLAS untouched) before the descriptor update, which binds the new handle + resets PT accumulation. Golden: move swings 0.397 of the crop; stale-TLAS red is exactly 0 (RT is deterministic). Build-hygiene note: restoring a file with PowerShell Copy-Item preserves the SOURCE mtime and ninja skips the recompile - the “restored” binary still ran red code until a manual touch; bash cp (no -p) does not have this trap. 89/89, validation-clean
`35472bb2`	Materials reach the raster paths + loader OOB fix	Forward hard-coded roughness 0.9 + clamp-to-slot-0 for untextured materials; deferred’s lighting pass “read” a material channel its own geometry pass hard-coded to 0.9. Both now: diffuse fallback + shininess->roughness (Beckmann), parity-guarded (0.205 vs 1.0). Underneath: tinyobj’s -1 no-material face id cast to uint32_t made EVERY material fetch on EVERY untextured model an out-of-bounds buffer-device-address read - fixed in ObjLoader, CPU red/green test fails on the old loader with the shipped rig. Chain proven live: rig lit luminance 166.9 -> 158.1 when the default 0.7 diffuse landed. 88/88, validation-clean
`b513d010`	The GUI light reaches diffuse + HDR offscreen	Every BRDF in pbr/brdf multiplied light color/intensity into SPECULAR only - diffuse ran on an implicit radiance-1 white light across forward, deferred AND RT (all share the BRDFs); rchit additionally hard-coded the light entirely. Fixed in all five; paired with FP16 offscreen targets in the same unit because diffuse x radiance-10 exceeds 1.0 everywhere and UNORM clamped it flat at the 186 ceiling (the 07-21 HDR null result predicted exactly this pairing). Measured: PT light golden 0.027 -> 0.751 (the ceiling hid 3/4 of the response), deferred parity IMPROVED to 0.129, shadows 12.3% vs 4% floor. New forward golden whose instrument note matters: swung-pixel counts DO NOT discriminate (specular alone swings 0.41 - red PASSED it); the load-bearing assert is unlit-crop luminance 18.9 green vs 97.6 red. Rider: the shared-include freshness guard now skips generated/ naga exports - and it caught the include-blind mtime guard mid-unit. 87/87, validation-clean
`68ac8866`	PT quality controls + Russian roulette	spp and bounce cap were hardcoded 8/8 (stale comments claimed 64/32). GUI sliders -> push constants -> kernel loop bounds; RR from the 4th segment (unbiased, survivors reweighted); slider changes reset the accumulation history (mean over two estimators is biased). Golden: bounces 8-vs-1 swings 13.2% of the panel-free crop (all indirect sky light vanishes at 1 bounce); the hardcoded-bounds red kernel measures 7.3e-5 and fails. 86/86, validation-clean
`3a885f47`	PT light transport: NEE + gradient sky	The mode’s only light was an accidental radiance-1 furnace (env term commented out on miss) - the GUI light did nothing in PT. Now: per-bounce NEE shadow ray toward the directional light + soft gradient sky at half intensity. Golden on the shadow rig: swung-pixel fraction between radiance 10 and 0 in the panel-free crop - green 0.027, pre-NEE kernel EXACTLY 0 (red proven by checking out the committed kernel + recompiling). Three instruments measured before one worked: whole-crop mean luminance saw 0.057 on the skeleton (crop nearly all sky) and 0.29 on the rig (lit plane CLAMPS at the 186 UNORM ceiling + the responding band hugged the panel edge at 0.714w, outside the 0.75w crop - found by pixel-censusing the lit/unlit dumps: 4556 pixels swing, max delta 244). 85/85, validation-clean
`5a0d85c8`	Compile-then-read shader ordering + TLAS dispatch guard	PathTracing/PostStage read spv bytes before compileShader regenerated them - GLSL edits reached the GPU one process-start late. Reordered (other stages were already correct). Red/green impossible on the host and the reason is the next filed item: glslcExe is CMake-baked to the CONTAINER’s path, so runtime compilation silently no-ops in container-built binaries (system() unchecked). Plus: RT/PT record now requires a built TLAS - the async-load window used to dispatch against never-written descriptor sets (20 validation errors in the accumulation golden’s pre-load frames; now 0 across the suite). 84/84, validation-clean
`cb387e2a`	PT temporal accumulation - the mode finally converges	The kernel re-rendered a bit-identical noisy frame forever (no frame term in the seed, nowhere to accumulate). Now: frame index folded into the RNG seed, running mean in a persistent rgba32f history image (rgba8 would quantize and stall), compute-compute barrier for the cross-frame read-modify-write, resets on camera move + resize + AS rebuild. The AS-rebuild reset is itself a fix the golden found: model load/reload swapped the traced world under a live accumulation, which kept blending half-loaded-scene frames until the camera moved. Golden `PathTracingAccumulatesAndConverges` earned its instrument: v1 whole-frame mean was vacuous (history healing from load frames mimicked convergence with sampling DISABLED), v2 center crop measured the ImGui FPS digits (~0.29 constant; the panel covers the left ~70% of the frame - seen via amplified diff-map PNGs), final metric = changed-pixel fraction in the GUI-free right edge: green 5.2e-4 early -> exactly 0 at depth ~45, red probe exactly 0 early (FAILS). The red probe also exposed that createPipeline reads spv BEFORE compileShader regenerates it (shader edits reach the GPU one run late) - filed in BACKLOG with the pre-TLAS PT dispatch gap. 84/84, validation-clean
`ecbf14ae`	PT/RT correctness batch: normals, materials, degenerate scatter, t_min	Six defects across `path_tracing.comp` and `raytrace.rchit`, four of them the SAME defect in both files. (1) Hit normals were transformed as POINTS (`w=1`): the instance translation entered before the normalize, so any meaningfully translated object had every normal collapsed toward the translation direction — fixed with the inverse-transpose (row-multiply by worldToObject; also correct under non-uniform scale). (2) Untextured materials (`textureID = -1`) were clamped to 0 and sampled whatever texture sat in slot 0 — now they use `material.diffuse` (the intended fallback sat commented out one line below, in both files). (3) rchit fed the BRDF an object-space `N` and object-space hit position against world-space `L`/`cam_pos` — now world-space throughout. (4) RTIOW’s degenerate-scatter guard was missing: a random unit vector landing on −normal makes a near-zero bounce direction; falls back to the normal. (5) PT ray-query `t_min` 0.0 → 0.001 to match the rgen (the 1e-4 offset alone under-guards at rig scale). (6) Five BRDF includes with zero uses deleted; stale “32 segments” comment corrected. PT survey items 4/5/6/8 + rider; survey-1 item 5 partially (its hard-coded RT light colour remains open). Verified: shader compile, 83/83 with renderModesSuite driving RT+PT on the new SPIR-V, validation-clean run
`27fddfd8`	PT/RT: precomputed inverse matrices	The path-tracing kernel called `inverse(view)` / `inverse(projection)` INSIDE the per-sample loop - 24 full 4x4 inversions per pixel per frame - and raytrace.rgen did 3 more per pixel, while GlobalUBO has carried CPU-precomputed `inv_view`/`inv_projection` since the clouds pass (whose comment calls per-pixel inverse() “ruinously expensive”). Swapped to the UBO fields; the loop-invariant camera origin is hoisted out of the sample loop, with the per-bounce-mutated rayOrigin kept per-sample (the first attempt made it const and the bounce re-base caught it at compile). First item of the PT survey, whose full 11-item list is in BACKLOG. Verified: shader compile, 83/83 incl. renderModesSuite driving RT+PT on the new SPIR-V, validation-clean run
`68f8b84a`	BLAS compaction	BLAS were built ePreferFastTrace with no eAllowCompaction and never compacted - VRAM held the full build-size structures for the process lifetime. Now: builds carry eAllowCompaction; after the (synchronous) build, a query pool reads each compacted size, right-sized replacements are copy-compacted, originals destroyed, and the TLAS - built after - picks up the new device addresses naturally. Query failure degrades to keeping uncompacted BLAS with a warning. BLAS-only by design: TLAS compaction gains little and the pending TLAS-refit-on-move item builds on the plain path. Measured: default scene logs 15.98 MB post-compaction (pre-size is not retained anywhere to log - noted, not hidden). Verified: RT/path-trace goldens trace against the compacted BLAS, 83/83, validation-clean (every compaction step is individually validated)
`23f53622`	Cascade texel snapping - shadow edges stop crawling	The ortho box was refitted to exact frustum corners every frame, so it translated AND resized continuously and sub-texel camera motion made every shadow edge shimmer. Stabilized path (opt-in via a shadowMapResolution param; updateCascades passes the live map size): world-fixed light basis (the legacy lookAt anchored at the slice center absorbs camera translation continuously, making any later snap a no-op), box sized from the slice’s bounding radius (a function of fov/aspect/splits only), center snapped to whole texels, one-texel pad because the snap can shift the center by up to a texel. Three tests incl. a legacy red control (the old path must crawl or the whole-texel assertions are vacuous) and a coverage guarantee. Shadow golden IMPROVED: 9.78% darkened vs the 4% floor - the radius box + depth clamp cover casters the tight fit clipped. 83/83, validation-clean
`e5f67566`	Single-time command buffers freed instead of leaked	endAndSubmitCommandBuffer is fully synchronous (fence wait, or queue.waitIdle in both fallbacks), so the old “avoid freeing potentially pending buffers” rationale was wrong for this path - nothing reaches the tail before the wait completes. Every texture/buffer upload, layout transition and AS build leaked one primary command buffer into the pool for the process lifetime; GUI model reloads leaked dozens each. Now freed on the success AND submit-failure paths. No unit test can observe the leak (Vulkan has no live-buffer query); the legality proof is structural (free strictly after the wait) plus empirical - freeing a pending buffer is exactly what the validation layer reports, and the 80-test suite drives hundreds of these submissions validation-clean. Per-submit fence create/destroy deliberately left as-is
`3f80072a`	First-frame delta_time clamp + first input-handling tests	`last_time` started at 0, so the first frame’s delta was the ENTIRE startup wall clock (window + scene + renderer construction, seconds) - a key held during load teleported the camera. Pure `clamp_frame_delta` (10 FPS cap, negatives to zero) wired into `update_frame_timing`. Plus the first coverage for the input path that routes ALL keyboard/mouse into the camera: 8 tests over key press/release/REPEAT, out-of-range keys (ASan-enforced), first-mouse-move zero-delta, consume-and-reset axis deltas, and the ImGui capture gate tested in BOTH directions with a real context. ESC-to-close and cursor-callback swapping deliberately untested (need a live GLFWwindow); both suites registered in the Windows CI CPU filter, without which they would silently never run there. Verified: 80/80, validation-clean run
`d7fff8b8`	Deferred mode was unreachable end-to-end; parity golden was vacuous	Two real defects, found while chasing three phantom ones: (1) the GUI mode radios lived in function-local statics and wrote themselves back into the shared vars every frame, stomping any programmatic mode change; (2) the post pass’s input descriptor was written once at init, so even a surviving mode switch presented the STALE forward image - proven by forcing the deferred lighting shader to pure red and observing an unchanged capture. Both fixed (radios derive from shared vars; descriptors rebind on mode change). The three “deferred shader defects” from survey 2 turned out to live in DEAD legacy files (`rasterizer/g_buffer_*`, unreferenced by any code) - the live `deferred/{geometry,lighting}` pair is healthy. Golden upgraded: absolute per-channel means (a probe shader is visible there; a relative diff of two equally-affected captures is not) + per-pixel diff with a measured threshold - clean parity 0.203/channel, a single deliberate extra tonemap in the LIVE shader pushes it to 2.105, threshold 1.0. Verified: red/green on the live shader, 72/72, validation-clean 9s run
`4062f3da`	Shadow pancaking via depth clamp	Casters between the light and a cascade’s near plane were CLIPPED (near hugs the camera frustum + 10-unit pad; `depthClampEnable` was false) while `isVisibleAsShadowCaster` deliberately keeps them - a ceiling/overhang cast nothing. Fix: `PipelineBuilder::setDepthClamp` + guarded `depthClamp` device feature + enabled on the CSM pipeline. First attempt (extending the near plane to scene bounds) was REJECTED by `GoldenRender.ShadowsDarkenSomePixels` (2.4% darkened vs 4% required): the shader bias is constant in normalized depth, so widening the range scales it in world units and eats contact shadows - the 60x-scaled rig amplified it. Clamp keeps the range tight. Verified: 72/72 incl. the golden, validation-clean 9s run. Open: a raised-slab golden proving the rescue itself
`00bbebad`	PipelineBuilder	The copy-pasted ~70–100-line pipeline-construction block across Rasterizer/PostStage/DeferredRasterizer/SkyBox/CascadedShadowMap became `kataglyphis.vulkan.pipeline_builder`; stages state only what differs. −416/+51 at call sites; configurations preserved bit-for-bit
`30ed20f5`	glTF alphaMode MASK cutoff (increment 1)	Cut-out foliage/decals (glTF MASK) rendered as the solid quad they are modelled as - the raster shaders never read base-colour alpha. `ObjMaterial` got a trailing `float alphaCutoff` (shared C++/GLSL struct, scalar layout, -1 = not MASK); `GltfLoader` reads `cgltf_alpha_mode_mask`/`alpha_cutoff`; forward + deferred shading `discard` below the cutoff. Safe-by-default: -1 for every OBJ/OPAQUE material (default ctor) skips the test, so existing rendering is bit-unchanged. CPU red/green (`GltfParseUnit.MaskAlphaModeSetsTheCutoff`: cutoff 0.5 vs the -1 default) + `GltfParseUnit.*` finally added to the Windows CI filter (was missing). Verified: fresh-container ABI-skew build exit 0, 10/10 CPU tests, 15/15 GPU goldens unchanged (DeferredMatchesForwardRoughly confirms both edited paths still agree), validation-clean. Follow-ups (backlog #11): shadow-pass MASK (1b), RT/PT (1c), a visual golden, BLEND
`3e51d8ac`	glTF COLOR_0 vertex colours	The engine Vertex always carried a color field and both vertex shaders forwarded it as fragment_color, but no fragment shader read it and GltfLoader hardcoded (1,1,1) - vertex-coloured glTF rendered white (dead plumbing, the gap RPT closed in d2a1427). GltfLoader now reads COLOR_0 (vec3/vec4 via cgltf_accessor_read_float); ObjLoader’s -1 absent sentinel became (1,1,1); forward + deferred shaders multiply fragment_color into the base colour per spec. Constructed vertex_colored_quad.gltf (r/g/b/white corners) + GltfParseUnit.ReadsColor0VertexColours (red without the loader change: every colour reads white). Not ABI-skew. Verified: 12/12 CPU tests, 15/15 GPU goldens UNCHANGED (identity multiply on the white-vertex scene), validation-clean
`5bbe0ac6`	glTF MASK shadow casting (increment 1b)	A MASK caster (cut-out foliage) cast the shadow of its solid quad - the depth-only cascade pass had no UVs or material access. The shadow VS now forwards UV + moves light matrices to set 1 + repurposes the unused cascadeIndex push slot as objectIndex; the (was empty) shadow FS replicates the forward pass’s ObjectDescription/buffer-reference material walk (shared set 0, bindings 2/3/4) and discards below the cutoff for textured MASK casters. CSM pipeline layout gains set 0 = sharedRenderDescriptors.getLayout() (the set recordCommands already received but ignored); the push reaches the fragment stage; VulkanRenderer passes the shared layout. Adding a CascadedShadowMap.ixx member = ABI skew - an incremental build tripped the documented stale-BMI ASan ctor overflow; fixed with delete-build + -FreshContainer. 15/15 goldens UNCHANGED + validation-clean (the material fetch runs for EVERY caster, proving fetch/2-set-binding/UV end to end; ShadowsDarkenSomePixels confirms opaque shadows unaffected). Discard logic identical to the golden-tested forward MASK. Follow-up: visual cut-out golden needs a card-over-plane rig
`aaa1271b` + `947e2316`	Multi-mesh Model - a `Model` holds many `Mesh`es (#10, L)	Landed end-to-end over the campaign: `Model` moved to `std::vector<Mesh>` (`3587463a`), object descriptions flattened one-per-mesh with `objectIndex` = the flat mesh index across forward/deferred/shadow record loops (`0e49fd5a`), the AS already built one geometry per mesh and the RT/PT kernels fetch via `instanceCustomIndex + gl_GeometryIndexEXT` (`36c30bff`). The load-bearing final step is the loader split (`aaa1271b`): `GltfLoader::parseCpu` records a per-primitive `MeshRange {vertexBase, vertexCount, indexStart, indexCount, triStart, triCount}` while leaving the flat vertices/indices/materialIndex getters (and every `GltfParseUnit` test) untouched; `uploadParsed` slices each range into its own `add_new_mesh` (indices re-based by `-vertexBase`, per-range material-index subset, full materials shared) and `adoptParsed` moves the ranges so the async worker path builds the meshes too. A single-primitive glTF yields one range spanning everything - behaviour-identical to before. Verified: CPU `MultiPrimitiveGltfRecordsPerPrimitiveMeshRanges` (two_primitives.gltf → 2 ranges), and the render golden `MultiPrimitiveGltfLoadsAsMultipleMeshes` (`947e2316`) loads it in forward mode and asserts `visibility.meshes_total == 2` through the REAL render loop via the async adopt path - not just the parse. Fresh-container ABI-skew build (MeshRange is `.ixx`-exposed); 14/14 goldens + 13/13 GltfParseUnit green, validation-clean. Correct-by-inspection only: the RT/PT `gl_GeometryIndexEXT > 0` branch (the raster golden exercises the flat objectIndex). Optional future refinement: per-mesh material subsets (each mesh shares the full materials array today - correct, not minimal)
(feat)	glTF KHR_texture_transform (#11 increment 4a)	An atlas/tiled material (scale/offset on its base-colour texture) sampled at the RAW UV - the loader ignored the extension. Now `ObjMaterial` carries trailing `uv_scale`/`uv_offset` (identity default, scalar-layout-safe so the RT/PT kernels reading the struct stay byte-compatible - existing fields keep their offsets), a shared `material_fetch.glsl` `transform_uv(uv,material)=uv*scale+offset` is applied in the forward/deferred/shadow FS (identity leaves the UV unchanged → existing rendering bit-identical), and GltfLoader reads `cgltf` `KHR_texture_transform` scale/offset from the base-colour texture (rotation deferred). ABI-skew - fresh container. Verified: `ReadsKhrTextureTransformScale` + `MaterialWithoutTextureTransformIsIdentity` CPU tests; `KhrTextureTransformTilesTheTexture` golden - a NEW 8x8 RGB checkerboard fixture (the mask_card’s checkerboard is alpha-only, RGB uniform white, so it could not show tiling - decoded it, generated an RGB one) scaled 4x tiles to 32x32 with the REPEAT sampler: detail-fraction 0.552 vs 0.079 with `transform_uv` disabled (RED-proven, threshold 0.15). 18/18 goldens unchanged, validation-clean
(feat)	Forward `material.doubleSided` (#11 increment 2)	A doubleSided glTF mesh (foliage/decal cards, two-sided surfaces) was back-face culled like everything else and vanished from behind. Now the forward pass disables back-face culling per doubleSided mesh via DYNAMIC cull state, NOT a second pipeline: `PipelineBuilder::setDynamicCullMode` adds `VK_DYNAMIC_STATE_CULL_MODE` (core Vulkan 1.3; opt-in so only the forward Rasterizer changes - deferred/CSM/skybox/post keep static culling), and the record loop sets `eNone` for doubleSided meshes / `eBack` otherwise per draw. Every non-doubleSided draw gets `eBack` = byte-identical to the old static cull, so existing rendering is unchanged. The flag rides glTF→Mesh: GltfLoader reads `cgltf material.double_sided` into MeshRange, uploadParsed forwards it to add_new_mesh (Mesh ctor unchanged), `Scene::isMeshDoubleSided` exposes it. Per-mesh is exact post-#10 (each glTF mesh = one primitive = one material). ABI-skew (5 module interfaces) - fresh container. Verified: `MaskCardDoubleSidedRendersFromBehind` rotates the doubleSided mask_card 180° so its BACK face faces the camera - visible (12779 changed px, checkerboard 0.475) ONLY because doubleSided renders it, RED-PROVEN by forcing single-sided (0 changed px, culled). 16/16 goldens unchanged, validation-clean run loading the card (vkCmdSetCullMode path VUID-clean). Deferred/shadow doubleSided is the deliberate follow-up
(golden)	Visual golden for forward MASK cut-out (#11 1b)	The forward alphaMode MASK `discard` was CPU-verified (GltfParseUnit cutoff) + shadow-golden verified but never confirmed in the forward COLOUR image. `MaskCardDiscardsCutoutTexelsVisually`: DIFFERENTIAL oracle - render the base scene (A), `addModel` the mask_card over it (B), measure the changed-pixel fraction within the bounding box of the changed pixels. mask_card.gltf’s texture is a verified 50/50 8x8 checkerboard, so with the discard working only the opaque squares change (holes leave the background = A). Two instrument traps navigated by LOOKING at the dumped diff: (1) an edge/detail-fraction metric is VACUOUS here (the card is a checkerboard whether or not discard runs - only the hole colour changes), so the differential is required; (2) the opaque ImGui panel covers the left ~68% and the card casts a floor shadow, so the scan is restricted to the GUI-free upper-right (FPS text + shadow excluded). MEASURED 0.37 discard-on vs 0.78 discard-off (not 1.0 - some cut-out texels are grey and blend into the ground), 0.55 gate between, red-proven by disabling the FS discard + recompiling the spv. Placement env-tunable (MASK_X/Y/Z/SCALE) for reframing without a rebuild. Local GPU golden (skips in CI). 15/15 goldens
`d5b81523`	OBJ shapes split into separate meshes (#10, the OBJ half)	`ObjLoader` flattened every OBJ shape (`o`/`g` group) into ONE mesh - a multi-object OBJ collapsed to a single Mesh, the pre-#10 glTF limitation. Now each shape becomes its own Mesh via a per-shape `MeshRange`, so #10’s whole downstream (per-mesh objectIndex/culling/AS/RT-PT) applies to OBJ too. The glTF turnkey slice did NOT transfer: OBJ shapes share one attribute pool and the vertex-dedup map was declared OUTSIDE the shape loop, so vertices were deduped GLOBALLY (a shape’s indices could point at a vertex an earlier shape emitted - not a contiguous range). Fix: reset the dedup map PER SHAPE, so each shape’s vertices form a contiguous block `uploadParsed` slices (indices re-based by -vertexBase, per-range material subset, full materials shared); `adoptParsed` moves the ranges so the async worker path builds them too. The de-risking insight (the initial “goldens must re-baseline” fear was wrong): per-shape dedup is PIXEL-IDENTICAL (same triangles, vertices just stored per-shape), so pixel goldens don’t shift from the vertex-count change - only CPU count-asserts (which use the preserved flat getters) and per-mesh culling could. ABI skew (ObjLoader.ixx member) - fresh-container. Verified: `ObjParseUnit.MultiShapeObjRecordsPerShapeMeshRanges` (dinosaurs, 3 shapes -> >1 range, asserting the ranges tile the flat arrays contiguously + every shape index stays inside its own vertex block - the slice-rebase invariant) + `SingleShapeObjIsOneMeshRangeSpanningEverything` (shadow_rig); the sponza golden (now a 373-mesh OBJ) held at detail 0.031 > 0.02, proving per-mesh materials/textures still render through the async path; 106/106 suite, 12s validation- + ASan-clean run loading 3-shape dinosaurs
`c6e1bdb4` + `c7621e36`	Loaders’ `MeshRange` slice dedup (was queued #7)	The two byte-identical loader-local `MeshRange` structs and per-range slice loops (indices re-based by `-vertexBase`, per-range material subset) now live once in module `kataglyphis.vulkan.mesh_range` (`Src/GraphicsEngineVulkan/scene/MeshRange.ixx`) exporting `sliceMeshRange`; both loaders’ `uploadParsed` call it. Unit suite `meshRangeSliceSuite.cpp` pins the re-basing arithmetic
(refactor)	`buildAttachmentDescription` - render-pass attachment dedup	Eight hand-written `vk::AttachmentDescription` field lists across five files (Rasterizer x2, DeferredRasterizer’s local `createAttachmentDesc` lambda, PostStage x2, SkyBox x2, CascadedShadowMap x1) collapsed into one `constexpr` helper in `common/RenderPassHelper.hpp`, following the same shape as `ViewportHelper.hpp`/`SamplerBuilder`. Three fields are identical in EVERY pass and are now baked in - `samples = e1` and both stencil ops `eDontCare` (no pass touches a stencil aspect, even when `chooseDepthFormat` returns `eD32SfloatS8Uint`); the five the passes genuinely disagree on stay parameters defaulting to the majority variant (clear/store/from-eUndefined). PostStage’s colour attachment is the sole site overriding all three. Configurations preserved field-for-field; -87/+53 at the call sites. `renderPassHelperSuite.cpp` (8 tests) re-creates every call site and pins it field-by-field with no device, so a dropped stencil op or a flipped load op fails on CPU - the class of defect no pixel oracle sees. 235/235 CPU tests (was 227), `BuildIntegrity` 20/20

2026-08-02 → 2026-08-03#

Commits	Theme	Notes
`7e3f4e51`, `768c18b3`, `9078523d`, `79fdbf1b`, `e0d88636`, `3b417b36`, `88c204d2`, `ac06961a`	Create-info builder family	Following `buildAttachmentDescription`’s shape, one shared definition each for `vk::RenderPassCreateInfo`, `vk::PipelineLayoutCreateInfo`, `vk::FramebufferCreateInfo`, `vk::ImageViewCreateInfo`, `vk::RenderPassBeginInfo`, `vk::SubpassDescription`, compute-pipeline creation, and framebuffer teardown - each collapsing several hand-rolled call sites into one helper with a `BuildIntegrity` gate against regressions.
`82cc423c`, `99e1b483`, `00febd65`, `6eb9df82`	Resource-ownership hardening	`VulkanBuffer::create()`/`VulkanImage::create()` now release the previous allocation before taking a new one; `VulkanImageView::create()` releases its previous view before its image; `DescriptorSetGroup::create` refuses a duplicate binding and releases its previous layout/pool; its single-descriptor writers refuse an array binding.
`d63e2e1b`, `643a010d`, `899c3576`, `31a78b3d`	`ibl.slang` port regressions and their restorations	The Slang port of the IBL pipeline had dropped `fs_downsample_cube`/equirect `textureLoad`, roughness-driven GGX importance sampling in `fs_prefilter`/`fs_brdf_lut`, the forward pass’s analytic ambient specular and IBL strength controls, and `fs_irradiance`’s midpoint quadrature (128x64 steps, mip-0 sampling); all four restored.
`3145d1a7`, `27de8984`, `7c835ecf`, `11735ee3`	Shader hot reload completed across all eight SPIR-V subsystems	`deferredRasterizer.shaderHotReload` wired into `VulkanRenderer` and gated against call sites; shadow/sky/cloud subsystems gained a `shaderHotReload`; `PostStage`/`Rasterizer`/`Raytracing`/`PathTracing` now destroy the pipeline layout on reload; the ray-tracing SBT rebuilds after a reload.
`f5017f3f`, `ce428348`, `52e22d96`, `bc748462`	Model-loading dedup and correctness	Shared textures deduplicated across the glTF and OBJ loaders; `Model` texture samplers deduplicated by mip level; the glTF loader now walks only the default scene; both loaders’ `uploadParsed` tail unified into one definition, forwarding `MeshRange::doubleSided` from OBJ.
`3861e54b`, `11828d7b`, `1880ebe0`, `eb590cb1`, `07e98a5b`, `5abaeac8`	Cascade/shadow fixes	The cascade light-matrix UBO is double-buffered per swapchain image; the stabilized cascade box snaps to the grid it actually projects onto; the PCF kernel stops sampling past the shadow map’s edge; the cascade framebuffer attachment has one image view; the shadow pass binds light matrices at set 1 on the no-shared-set fallback; `CascadedShadowMap` no longer stages its light matrices through a throwaway command pool.
`90e7d7ba`, `ca989c14`, `613e4225`, `b33e01c5`	Input and GUI	Key/mouse-button RELEASE is honoured under ImGui capture, with real focus/enter callbacks; look mode ends and the mouse origin re-seeds on window focus loss; the GUI model transform is a pure helper (dropping a stale 60x scale); the GUI model picker’s default index no longer leaves Position/Rotation controls dead.

2026-08-04#

Commits	Theme	Notes
(refactor)	`destroyRenderPass` - render-pass teardown dedup	Twelfth member of the create/destroy helper family. Five stages (Rasterizer, DeferredRasterizer, PostStage, SkyBox, CascadedShadowMap) hand-rolled the same null-checked `destroyRenderPass`/null-out pair in `cleanUp()`; collapsed into one `Kataglyphis::destroyRenderPass(device, render_pass)` in `common/RenderPassHelper.hpp`, following `destroyPipelineAndLayout`’s by-reference, device-null-is-a-no-op shape. `BuildIntegrity.RenderPassTeardownGoesThroughTheSharedHelper` (cloned from the framebuffer-teardown gate) greps `Src/GraphicsEngineVulkan` for a stray `.destroyRenderPass(` outside the helper.
(refactor)	`createColorAttachment` - the colour twin of `createDepthAttachment`	Thirteenth member of the create/destroy helper family. DeferredRasterizer’s local `createAttachment` lambda, Rasterizer’s offscreen texture and VulkanRenderer’s path-tracing accumulation image each spelled out `createImage(..., eColorAttachment, eDeviceLocal)` -> `createImageView(..., eColor)` by hand; collapsed into `Kataglyphis::VulkanRendererInternals::createColorAttachment` (`renderer/ColorAttachment.ixx`), mirroring `DepthAttachment.ixx`’s shape. Deliberately not merged with `createDepthAttachment` into one aspect-flag-parameterised function - they differ in what they return (depth picks its own format via `chooseDepthFormat`; colour is told its format) and merging invites a config-struct nobody can read. `BuildIntegrity.NoStageHandRollsTheColorAttachmentChain` (cloned from the depth gate) greps `Src/GraphicsEngineVulkan` for a stray `createImageView(..., eColor, ...)` outside the helper, with a `// COLOR_ATTACHMENT_CHAIN_OK: <marker>` escape hatch for the four non-plain-colour-view non-goals (Clouds storage texture, SkyBox cubemap, Texture’s real mip chain, VulkanSwapChain’s borrowed view).
(perf)	G-buffer albedo widened to `eR8G8B8A8Srgb`	`GBUFFER_ALBEDO_FORMAT` was left `UNORM` when its two sibling attachments (`GBUFFER_NORMAL_FORMAT`, `GBUFFER_MATERIAL_FORMAT`) widened to `eR16G16B16A16Sfloat`. Albedo holds linear base colour decoded from an sRGB-sourced texture, so its 256 UNORM steps were spent uniformly instead of where the eye is most sensitive; switching to `eR8G8B8A8Srgb` redistributes them at identical bandwidth (no range to recover - glTF caps `baseColorFactor`/`COLOR_0` to `[0,1]`, so a float16 attachment would only double traffic for nothing). Hardware encodes on write and decodes on `SubpassLoad`, so the value carried into lighting is unchanged in linear terms.
(feat)	Per-vertex tangent plumbing (normal-mapping prerequisite)	The engine `Vertex` had no tangent, so normal mapping had nowhere to build a TBN basis - the Rust twin has carried one since its glTF loader shipped. `Vertex` gains a trailing `glm::vec4 tangent` (xyz + handedness `w`, glTF convention), mirrored in `scene_types.slang`’s `Vertex` and the `Vertex_natural` `BuildIntegrity` offset gate; `getVertexInputAttributeDesc()` grows to 5 attributes (Rasterizer/DeferredRasterizer/SkyBox call sites updated). New `vertex::computeTangents` (ported from the Rust `compute_tangents`, Lengyel’s method: per-triangle UV-gradient tangent+bitangent accumulated per vertex, Gram-Schmidt against the normal, degenerate UVs fall back to an arbitrary orthogonal axis) sits beside `computeFlatNormals`. `GltfLoader` reads an authored `TANGENT` accessor verbatim (world-transformed by the node’s linear part, handedness flipped under a mirrored/negative-determinant node to match the winding reversal `mirrored` already applies) and generates one otherwise; `ObjLoader` always generates (OBJ has no tangent concept). Deliberately no shading change - the shaders declare the field so the buffer layout matches; consuming it is the follow-up (backlog: normal mapping across the four shading paths). Fresh-container ABI-skew build; new `vertexTangentSuite.cpp` (UV-gradient direction, unit length, normal-orthogonality, mirrored-chart handedness, degenerate-UV fallback, hash/equality participation) plus `GltfParseUnit.AuthoredTangentsArePreferredOverGeneratedOnes`/`MissingTangentsAreGeneratedWithUnitLengthAndOrthogonalToTheNormal` and the extended `Vertex_natural` gate.

2026-08-05#

Commits	Theme	Notes
(refactor)	`Mesh`’s unread model matrix deleted	`Mesh` carried a second identity `glm::mat4 model` plus `getModel()`/`setModel()`, with zero readers and zero writers outside its own constructor - the per-model transform is owned by `Model::set_model`/`Model::getModel` and reached through `Scene::update_model_matrix`/`Scene::getModelMatrix`. A live `Mesh::getModel()` was a trap: it compiles, type-checks, and silently returns identity for a model the GUI has rotated. `BuildIntegrity.MeshDoesNotHoldAModelMatrix` source-scans `Mesh.ixx` for the three specific spellings so the dead state cannot come back unnoticed.
`e6b88dc2`, `4c21bd26`, `93084671`, `9813dadf`, `ff958a92`, `831fdfaf`, `865943a2`, `5a4398f4`, `a25837cd`, `87cb77de`, `118cff50`, `7efffb3c`, `56e06f5e`, `1e817c1a`, `ac2477d4`	glTF/OBJ material completion	Closed the remaining material-slot gaps left after #11. glTF normal maps upload UNORM with per-slot colour space and honour `normalTexture.scale`; `metallicRoughnessTexture` is sampled in all four C++ shading paths (linear, G=roughness/B=metallic per glTF 2.0 §3.9.2); `KHR_texture_transform` now applies per-slot (normal/metallic-roughness/emissive) instead of stamping the base-colour transform onto all four, behind named accessors so a mismatched row pair can’t compile; `KHR_materials_unlit` reaches all four shading paths. The OBJ loader gained parity it never had: `map_Bump`/`norm` → `normalTextureID` (`-bm` scale read from whichever directive’s texture won), `map_Ke` → `emissiveTextureID`, `.mtl` `Pm`/`Pr` → metallic/roughness, and `map_d` → a new `alphaTextureID` sampled through `alpha_test.slang` at the glTF-MASK 0.5 cutoff (OBJ has no alphaMode). `GltfLoader`’s four texture slots collapsed onto one enumerated table (was three hand-copied guards) and `ObjMaterial` became an aggregate with default member initializers (was two hand-written constructors kept in sync by hand). `GltfLoader`’s shininess fallback was pinned to a named constant after tracing that its `mix(128,1,roughnessFactor)` was dead code always evaluating to 1.0. The Rust `webgpu_renderer` picked up the same per-slot `KHR_texture_transform` treatment. Covered by new `GltfParseUnit`/`ObjParseUnit` fixture tests plus a `BuildIntegrity` structural gate per feature; 184/184 CPU tests at the OBJ-parity midpoint, no host GPU golden run this batch (still `- [b]`).
`d8efb5f8`, `8798b0ee`, `0b01c0df`, `74069e12`, `6746f8d1`, `86138954`, `b290e1c3`	Shared-Slang-module consolidation	Continued the create/destroy-helper-family shape into the shader tree. Extracted binding-free `common/material_rules.slang` for the three rules `alpha_test.slang`/`path_tracing.slang` were re-deriving by hand, then routed both through `material_fetch.slang`’s `fetch_object_description()`/`fetch_material()`, retiring the stale “RT/PT cannot import material_fetch” claim repeated across five modules (it compiles cleanly; the real constraint is which modules declare bindings). Extracted the byte-identical rasterizer/deferred vertex stage into `common/raster_geometry.slang`. Replaced nineteen shared-set plus six RT-set bare-integer `[vk::binding(...)]` literals with `scene_types.slang`’s named constants. Gave the four texture-slot samples (alpha/normal/metallic-roughness/emissive) one owning `material_textures.slang` module covering both explicit- and implicit-LOD call shapes (verified dead-code elimination keeps a compute/RT importer from picking up a fragment-only capability), then gave their guard-plus-default-plus-combine wrappers - eleven duplicated copies - one owning `resolved_*` set in the same module. Each step added or tightened a `BuildIntegrity` structural gate; verified via `spirv-dis` diffs (byte-identical, or one documented CSE-across-inlined-call-boundary delta) and 5 RT `GoldenRender` tests on the host RX 9070 XT.
`4b05307a`, `ff3a2a83`, `7dd78a63`, `888ec105`	Ray/path-tracing correctness	`ASManager::createTLAS` stamps `instanceCustomIndex` with a model’s first-mesh flat index, but Slang’s HLSL-shaped `InstanceIndex()` reads the TLAS instance index instead - the two only coincided while every model held exactly one mesh. Switched all five traced object-index sites to `InstanceID()`/`CandidateInstanceID()`/`CommittedInstanceID()` (`4b05307a`, verified via `spirv-dis` opcode counts), then found `path_tracing`’s committed-hit block was still missing the geometry-index term its own candidate loops already added - an out-of-bounds buffer-device-address read on any hit against mesh N>0 of a multi-mesh model, the most likely root cause of the tracked device-lost on `Dinosaurs.obj` (`ff3a2a83`, unconfirmed on hardware - no console access this batch). The `instanceCustomIndex` accumulator itself was extracted into a tested `meshBaseOffsets` helper mirroring `assignTextureOffsets` (`7dd78a63`). Separately, the bounce ray direction (hit normal + random unit vector, length in [0,2]) was reused unnormalized against `TMin`/`TMax` and the sky-gradient extrapolation, both measured in units of ray-direction length; normalized after the degenerate-scatter guard (`888ec105`, verified against the host RX 9070 XT including the white-furnace golden).
`af57e6ac`, `f34ecfaa`, `4c2dc931`, `03f479c0`, `f92b45c7`, `c5abc415`	Clouds	Six more defects in the compute-pass cloud pipeline. The noise-volume dispatch normalized by half the actual volume extent (covering one octant) and hard-coded two of its four written channels to constants, even though `sample_density` weights all four into density and the cirrus band (`af57e6ac`). `phase_HG`’s denominator added instead of subtracted `2gcosTheta` (peaked away from the sun for positive g), and the powder effect was added onto transmittance after the break check instead of only attenuating in-scattered light, letting transmittance rise (`f34ecfaa` - neither confirmable visually this batch, goldens blocked). The GUI’s march-step sliders offered 1..128 while the shader floored at 4, so the bottom three slider positions did nothing; host-side clamp constants now gate both the UBO fill and the slider bounds, and the shader’s own floor-only clamp on `num_march_steps` was widened to match its sibling’s two-sided clamp (`4c2dc931`, `c5abc415`). Sample-position wrapping used `abs(fmod(x,N))/N`, which mirrors negative coordinates instead of wrapping them - visible as a mirror image since the default cloud box straddles the origin; switched to `frac(x)` (`03f479c0`). A write-only `model_to_world` matrix (seven fields filled, zero read - only `inv_model_to_world` is consumed) was deleted along with three comments that all falsely claimed the inverse was CPU-precomputed; Slang has no `inverse()` for SPIR-V, so it has always been formed inline (`f92b45c7`). Each fix added a `BuildIntegrity` structural gate.
`8a1398a6`, `abb77ca5`	Normal mapping and tangents	`apply_normal_map` multiplied the row-built TBN basis as `mul(TBN, nTs)`, which applies the inverse (world-to-tangent) transform - a flat normal-map texel came out as the geometric normal inverted on a Y-up floor. Fixed to `mul(nTs, TBN)`, matching the row-multiply convention the RT/PT shaders already use for their `WorldToObject()` inverse-transpose; applied to both `common/normal_map.slang` and `forward.slang`’s inline WGSL-target twin (`8a1398a6`, verified via the emitted-WGSL diff and a new CPU fixture - host goldens still blocked over RDP). `computeTangents` allocated and zeroed two `vector<vec3>` sized to the whole model on every glTF/OBJ primitive (Θ(P·V) for a P-primitive document); rescoped to the touched vertex range only, ~3.1x on the new `BM_ComputeTangents` benchmark at Arg(512) (142739ns → 46348ns) (`abb77ca5`).
`10abd948`, `6959e9fa`	Input and window	ImGui’s GLFW backend needs the cursor-pos callback installed manually (`install_callbacks = false`), but the engine only installed it while right-drag look mode was active - ImGui’s own mouse tracking never updated outside a drag. Installed unconditionally in `Window::init_callbacks`; camera motion now gated by a `WindowInputState::look_mode_active` flag instead of (un)installing the callback (`10abd948`). Separately, look mode never captured the OS cursor, so a right-drag rotation stalled dead the moment the cursor hit a monitor edge; wired `glfwSetInputMode`/raw motion into the look-mode transition and window-focus-loss callbacks so the cursor is hidden/confined during a drag (`6959e9fa`).
`e71d998a`, `e5280665`, `b8c86bcb`, `62c840a8`, `b222ab9e`, `aec5abe0`	Loader/renderer plumbing	`ObjLoader`/`GltfLoader`’s `uploadParsed` each hand-rolled the same device-free/empty-parse guard pair with differently-worded messages and neither had test coverage despite being pure-CPU reachable; shared through `ModelAssembly::uploadPreconditionsMet` (`e71d998a`). `Scene::reloadModel()` relied on its one caller to pre-resolve `modelPath` while `loadAdditionalModel()` resolved it itself; both now go through the same resolution point (`e5280665`). Seven call sites across the BLAS/TLAS builds, the cloud dispatch and the path-tracing accumulation-image transition discarded `endAndSubmitCommandBuffer`’s bool result via `static_cast<void>`, silently treating a submit failure as success; each now reacts per its own failure mode (`b8c86bcb`). `buildSamplerCreateInfo`’s scalar overload duplicated ten of fifteen fields the `GltfSamplerDesc` overload already set; now delegates (`62c840a8`). `Rasterizer`/`DeferredRasterizer` each wrote their frame-texture teardown twice (`cleanUp()` and `recreateFrameResources()`); extracted into one `releaseFrameTextures()` per class, closing a null-guard asymmetry between the two call sites in the process (`b222ab9e`). `PostStage`’s post pass built a clear colour for an attachment declared `eLoad` (never consumable) and `post.slang` sampled `noisyTxt` twice per texel; both removed (`aec5abe0`). Each landed with a `BuildIntegrity` or unit gate against the specific defect regressing.
`cc6d70db`, `b4f7aeb5`, `93cb3237`, `4c72c9c8`, `e21ddfc2`, `ff57a216`, `2edf7a43`	Gates and tooling	The `file:line`-citation gate (born as `ModelLoadingDocCitesSymbolsNotLineNumbers`, scoped to one doc) widened in three steps into `SourceAndDocsCiteSymbolsNotLineNumbers`: first across `Src/*/.{cpp,hpp,ixx}` and every `.slang`, rewriting eighteen citations (at least eight already pointing at unrelated code) (`cc6d70db`); then to catch the bare `:NNN`/`:NNN-NNN` same-file shorthand the filename-anchored pattern missed, rewriting ten more (`b4f7aeb5`); then across `Test/`, fixing eighteen more citations across ten suites, five of them already stale (`93cb3237`). `EveryRegisteredBenchmarkHasAPerfBaselineRow` closed the gap where `Compare-PerfBaseline.ps1`’s never-fatal-on-unmatched rule let the baseline silently stop covering `BM_ComputeTangents` after it grew three `->Arg()` variants; the three missing rows were appended from a fresh clangcl-profile measurement (`4c72c9c8`). `docs/source/clouds.md` shipped as the clouds subsystem’s owning doc, with two gated marker-block tables pinning the GUI→SceneUBO→shader field mapping and every `CloudDispatch.hpp` constant against their real sources (`e21ddfc2`). `GoldenRender.EnablingCloudsChangesTheFrameAndAddsDetail` added a real numerical oracle - the existing clouds golden only asserted the device survives, which would pass for a flat wash too; verified on the host RX 9070 XT including a manual negative control (`ff57a216`). `docs/source/shader-sharing.md` gained a per-field/per-shading-path table for every `ObjMaterial` member, gated against the four shading paths actually reading it (`2edf7a43`).
(perf)	`transformAABB` center/extent form	The eight-corner walk (8 `mat4 * vec4` products + 14 min/max reductions) replaced with the standard Arvo center/extent form (1 `mat4 * vec4` on the centre + 9 multiply-adds on the extents), exact for the same reason the old form was: both are tight for an affine transform. `BM_TransformAABB` on the host RX 9070 XT: `/64` 938ns → 262ns (3.6x), `/512` 7500ns → 2007ns (3.7x); baseline rows refreshed. Runs `models × meshes × 2 passes` per frame (373 meshes in sponza), with zero caching - the perf batch that added `BM_TransformAABB` measured ~11µs/frame at sponza scale, too small to justify invalidate-on-every-model-matrix-write cache complexity; that question is closed, not deferred. New `FrustumUnit.TransformAabbMatchesTheEightCornerReference` pins the new form against a kept file-local copy of the old eight-corner walk across identity/translation/uniform+non-uniform+mirrored scale/rotation/composed matrices.
(perf)	`computeTangents` finalizes each vertex once, not once per incident triangle	The finalize loop walked `indices` three corners at a time, so a vertex of valence v redid the same Gram-Schmidt/normalize/cross v times and wrote the same `vec4` v times; a `finalized` bitset (sized to the same touched-range as the tangent/bitangent accumulators) now skips a corner’s second and later visits. `BM_ComputeTangents` on the host RX 9070 XT actually got slightly slower (`/512` 45961ns → 53711ns): its fixture is 512 disjoint quads, each vertex shared by at most 2 triangles, so the third small heap allocation (`finalized`) outweighs the one skipped write per vertex. The win this was written for is real closed meshes, where a shared vertex’s average valence is ~6 (five skipped re-finalizes, not one) and `computeTangents` runs once per load, not per frame - the 14x gap against `BM_ComputeFlatNormals` this closes is a load-time constant, not a per-frame one. Baseline rows refreshed to the measured (regressed) numbers rather than backfilled to look better than they are. New `VertexUnit.SharedVertexTangentIsIndependentOfIncidenceCount` pins that a vertex shared by six triangles gets the exact tangent the accumulators dictate, regardless of how many of those six visits actually perform the write.

In progress#

(nothing left that is actionable here — the only remaining item is renderer-level RAII, which is - [b] in BACKLOG.md (blocked on a way to induce device loss so the device-lost teardown path is testable); see that entry for the reasoning rather than restating it here.)

Queued (design notes)#

Prebuilt SPIR-V consumption — done. The VkPipelineCache half shipped (f94a0b47); the mtime-gated compile skip and runtime glslc resolution it superseded are gone entirely with the Slang migration (see docs/source/shader-sharing.md) — there is no runtime compile path left to skip. Shaders are Slang sources compiled ahead of time to SPIR-V/WGSL by Build-SlangShaders.ps1/compile-slang-shaders.sh, and the C++ engine loads the generated (gitignored) .spv via plain file I/O (Kataglyphis::Shared::readBinaryFile). What remains is only a micro-optimisation: pipelines still read the .spv and create shader modules at startup rather than consuming a fully cached pipeline binary, which the VkPipelineCache already covers on the second run.
vk::raii teardown migration — leaf types (VulkanBuffer, VulkanImage, samplers) and the render stages are already move-only with destructor release. What is left is renderer-level: VulkanRenderer’s hand-ordered teardown and the device-lost special-casing in App.cpp — tracked as the - [b] “Renderer-level RAII cleanup consolidation” entry in BACKLOG.md, blocked on inducing device loss to test it.
Redundant same-layout swapchain barrier — done (the NOTE: a same-layout swapchain barrier comment before the post pass in VulkanRenderer.cpp). A sync-validation run (VK_LAYER_KHRONOS_validation with VALIDATION_CHECK_ENABLE_SYNCHRONIZATION_VALIDATION) confirmed the post render pass’s external dependency already covers the ordering, so the barrier was removed and the comment left in its place records why.
Per-pass GPU timestamps + debug labels — DONE. GpuTimedPass brackets Clouds/ShadowCascades/Main/Sky/Post with timestamp-query pairs, ScopedCmdLabel names every pass for RenderDoc, and the KATAGLYPHIS_GPU_TIMING_JSON export produces per-pass averages - the before/after evidence for every perf unit in the table above (the G-buffer and multiview-cascade units cite its numbers directly).

Verification pattern#

The canonical description of the per-unit verification loop - container build (tar-pipe transport by default), running build-clangcl-debug/commitTestSuite.exe directly from the repo root, the fresh-container rule for module-interface and shared-header changes, the validation-grep runtime check, and the cheap shader-only iteration path - lives in docs/source/gpu-golden-testing.md. AGENTS.md links there rather than restating it.

The instrument playbook (earned, not designed)#

Every unit above that says “measured” went through some of these; they are the difference between a golden and a vacuous golden.

Red/green or it did not happen. Every fix ships with a probe that restores the defect and a test that fails on it. Three probes this campaign found the TEST broken instead of proving the fix - which is the point.
Identical-to-the-digit metrics across a “change” mean the change never reached the GPU. The renderer is deterministic per frame index. This signature found the stale-spv consumption, the Copy-Item mtime trap (PowerShell preserves the source mtime; ninja skips the recompile - restore with bash cp or touch after), and one shader probe that silently no-oped.
Look at the pixels, and count rather than average. The frame-layout and metric cautions (ImGui panel coverage, the panel-free right edge, amplified diff-map dumps, counting metrics for sparse signals) live in docs/source/gpu-golden-testing.md’s cautions section.
Differential oracles beat colour signatures: render the with/without-defect pair in-process and count what moved, with an explicit exclusion for the object’s own body.
A test encodes the behaviour of the day it was written. The listing test asserted OBJ-only; the parity golden compared forward to forward; survey findings pointed at dead files. Liveness-check before fixing, re-derive contracts before trusting.