added review

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

@@ -0,0 +1,75 @@
+## 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.