Crafter.Graphics/.review-gates/lenses/repo-bug-prover.md

This repository: Crafter.Graphics

The execution contexts to enumerate, beside the charter's:

• One source, several builds. project.cpp defines exactly one of CRAFTER_GRAPHICS_WINDOW_WAYLAND, CRAFTER_GRAPHICS_WINDOW_WIN32 and CRAFTER_GRAPHICS_WINDOW_DOM from the target: native Linux (Wayland and Vulkan), x86_64-w64-mingw32 (Win32 and Vulkan, gamepads through Windows.Gaming.Input), wasm32-wasip1 (the DOM and WebGPU, through additional/dom-env.js and additional/dom-webgpu.js) and aarch64-alpine-linux-musl (Mesa Turnip: no descriptor heap, no ray tracing). Code behind one backend's #ifdef is still the range's code, and a change to one backend's half can leave the other's behind.
• One device, several paths, chosen at start-up: the descriptor heap or the bindless descriptor-set fallback (CRAFTER_GRAPHICS_NO_DESCRIPTOR_HEAP forces it), with each UI kernel's two SPIR-V builds; ray tracing or none (heap-only; Device::stageMask drops its stage without it); Vulkan 1.4 or 1.3 (CRAFTER_GRAPHICS_NO_VULKAN_1_4); swapchain_maintenance1 or not; GPU memory decompression or the CPU path (Device::memoryDecompressionSupported); the NVIDIA AS workaround on or off (Device::workaroundDescriptorHeapAS, CRAFTER_GRAPHICS_NO_AS_WORKAROUND); llvmpipe on a machine without a GPU.
• The GPU timeline. Three frames in flight, a fence each: what lives per frame is keyed by Window::currentFrame, what lives per swapchain image by currentImage, and the image count follows the present mode. A handle a frame in flight may still use is released through the deletion queue (freed framesInFlight frames later) or after a wait for the GPU; a freed descriptor slot is handed out again at once; a swapchain rebuild asked for from a listener mid-frame (Resize, SetPresentMode) waits for that frame's present, and onResize runs after it; a static owner is destroyed after the driver is gone. Within one dispatch, Vulkan orders nothing between workgroups.
• Re-entry from the platform. The Wayland listeners run inside wl_display_dispatch, wl_display_dispatch_pending and wl_display_roundtrip, which the frame loop, window creation, Device::Initialize and the clipboard's reads call. Windows calls the window procedure from the message loop and also synchronously from inside CreateWindowEx, SendMessage and DefWindowProc. The DOM's listeners in dom-env.js call the __crafterDom_* exports. A listener can resize, close or destroy the window it was called for. Windows.Gaming.Input reports gamepad connects and disconnects on threads of its own, queued under a lock until the event loop takes them.
• Shared state: Device's statics are process-wide; Device::frameCounter is one clock for every window, which the deletion queue, the staging rings and the font atlas's eviction run on; the deletion queue is shared under deletionMutex. The caches keyed on a Font* alias a new font at a freed one's address unless UIRenderer::InvalidateFont ran.
• Data the GPU and JavaScript read: an item or header struct is mirrored byte for byte by a std430 block in shaders/ui-shared.glsl, by the WGSL in dom-webgpu.js and by every shader that includes it, the examples' among them; one push block serves both builds, through vkCmdPushDataEXT on the heap and vkCmdPushConstants in the set build, within 256 bytes.
• Tests: each its own process, in parallel, with a 60 s timeout; every test that calls Device::Initialize needs a Wayland display, and one that lacks a capability exits 77 and pins nothing on that machine. A validation check counts only in a run where the layer loaded.

Semantics to read on disk rather than recall: the Vulkan headers and registry (include/vulkan/, registry/vk.xml) and Vulkan-Utility-Libraries as cloned (~/.cache/crafter.build/external/Vulkan-Headers-<hash>/, Vulkan-Utility-Libraries-<hash>/; several clones may sit side by side); the Wayland protocols (/run/host/usr/share/wayland/wayland.xml, /run/host/usr/share/wayland-protocols/, the generated code in lib/) and the client headers (/run/host/usr/include/wayland-client*.h, xkbcommon/); the MinGW headers (/run/host/usr/x86_64-w64-mingw32/include/); libc++ and clang as the host installs them (/run/host/usr/include/c++/v1, /run/host/usr/lib/clang/<major>/include); the vendored stb and libevdev in lib/; Crafter.Event, Crafter.Math and Crafter.Asset as cloned (~/.cache/crafter.build/external/<Name>-<hash>/). The crafter-build Flatpak compiles with an LLVM of its own, which is not readable from here: where a semantic may differ between LLVM releases, the host's headers settle it for the host's build only. The Vulkan specification's valid-usage rules, the WebGPU and WGSL specifications and Microsoft's API documentation are not on disk: a semantic only they settle is unverified.