Faset_Engine/docs/IMPLEMENTATION.md

# Implementation checkpoints

This log records working implementation and observed validation. It does not replace
the acceptance criteria in `PLAN.md`. Incomplete platform or workflow checks remain open.

**Current result:** the C++ MVP is accepted in the recorded Linux and Windows profiles.
The [final dossier](validation/mvp-acceptance.md) maps M0–M9 to evidence and keeps
unverified compatibility scenarios explicit. Earlier pending/failure statements below
describe their respective checkpoints, not the final status.

## Checkpoint 1 — native foundation and independent subsystems

Implemented:

- C++20 CMake presets, pinned dependency archives with SHA-256 verification, and separate targets.
- Core persistent IDs, SHA-256, atomic file replacement, JSON IO, and project path boundaries.
- Explicit schema registration, document transactions, revisions, retry keys, Undo/Redo,
  recovery records, unknown extension preservation, migrations, and nested template resolution.
- EnTT runtime with real Box2D/Box3D, fixed ticks, deferred changes, checked handles,
  interpolation, and statically linked example behaviors.
- GLB/glTF asset import, cooked mesh data, stable source identity, cache generations,
  reimport conflicts, cancellation, and the optional Blender export add-on.
- Direct Vulkan renderer, Slang shaders, sprites/meshes, basic PBR and directional
  shadows, texture upload, resize, capture, and SDL input.
- English MkDocs/Material manual and an image prototype for the future retained editor UI.

Observed validation on Linux:

- Integrated headless CTest: authoring, runtime, asset pipeline, Blender bundle, core — 5/5 passed.
- Integrated Clang 21.1.8/Ninja build with Vulkan: 7/7 tests passed, including offscreen GPU rendering.
- Independent runtime and asset AddressSanitizer/UndefinedBehaviorSanitizer checks passed.
- Renderer offscreen/visible tests exercised NVIDIA RTX 2080 Ti with Vulkan validation.
- MkDocs strict build passed with MkDocs 1.6.1 and Material 9.7.7.

The full editor, user-project build pipeline, MCP integration, standalone exports,
and Windows acceptance were still being implemented at that checkpoint. Later progress is recorded below.

Known intermediate constraints include box-only physics colliders, root-level physics
objects, static glTF triangles/UV0, a conservative serial renderer, and then-unfinished
world-preserving authoring reparent operations (completed in checkpoint 2). These remain implementation work or
explicit profile limits to review during final acceptance.

## Checkpoint 2 — integrated Editor, gameplay iteration and export

Implemented and integrated:

- Separate Player and SchemaExporter executables; statically linked project gameplay,
  configurable simulation settings, real contact-based grounded queries, and four
  compiled scripting tutorials embedded directly into the English MkDocs manual.
- Shared authoring commands and a real stdio MCP server, optimistic revisions,
  transactional retries, jobs/cancellation, recovery of unsaved documents, and
  viewport capture in graphical sessions only.
- Cancellable native subprocess execution, incremental project builds, schema export,
  binary scene/resource packaging, distinct Debug development and Release export
  directories, immutable published generations and retained last-good builds.
- A native retained UI with pinned FreeType/HarfBuzz and bundled Noto Sans:
  scene tree, schema Inspector, viewport camera/picking/gizmos, assets, diagnostics,
  build/play controls, commands, recovery and startup-loaded extension action panels.
- Exact-build native Editor SDK, dependency validation, owner-bound registrations,
  example Beacon runtime component/editor command/panel, and unknown-data preservation.
- Full world-preserving TRS reparent with explicit rejection of unsupported shear.
- Read-only cooked asset target for Player. Import/build/editor/MCP services remain
  outside the shipping runtime dependency graph.

Observed validation:

- Integrated Linux Clang 21 build: 19 CTests pass, including GPU rendering, retained
  widgets, Editor authoring interaction, actual plugin loading, real MCP stdio,
  process/cook contracts, and all four compiled gameplay tutorials.
- Real 2D and imported-glTF 3D standalone exports render with zero Vulkan validation
  errors on NVIDIA RTX 2080 Ti. Changing gameplay rebuilds metadata; failed C++
  compilation preserves the last successful published build.
- Runtime/tutorial checks also pass with Clang 18; runtime ASan/UBSan checks pass.
- Unmodified Blender 4.5.3 exports through the optional add-on. Real Editor imports
  preserve output IDs after rename/geometry edits, report deleted-output conflicts,
  retain the last generation on failure, and preserve separate scene placement/color.
  Reproduce with `tools/verify_blender_roundtrip.py --blender PATH --editor PATH`.
- Strict MkDocs build passes. Tutorial source snippets are compiled by CTest.
- Previous checkpoint headless Linux and Windows GitHub CI passed after portability
  fixes. New checkpoint and full Windows graphical/export checks are separate work;
  Linux validation does not imply Windows validation.

This is an implementation checkpoint, not an MVP release. Finished playable sample
projects, complete Windows graphical/export acceptance, fresh-install checks,
performance measurements, and final UX review remain. Standalone image import is
integrated but its dedicated PNG/JPEG edge-case checks are the next asset task.

The baseline profile currently uses box colliders, root-level rigid bodies, static
triangle glTF meshes/UV0, basic PBR/directional shadows and a conservative serial
Vulkan renderer. Advanced rendering and broader content profiles remain later work.
The generated UI reference determines visual direction only; architecture, behavior
and acceptance criteria remain authoritative.

## Checkpoint 3 — playable projects and complete authoring workflows

Implemented and exercised on Linux:

- Two playable C++ projects with real Box2D/Box3D input routes, pickups, a physical
  gate, an exit condition and reset. The 3D project includes a reproducible original
  Blender arch, `.blend` source, stable-ID bundle and import instructions.
- Native project launcher, retained folder browser, real recent projects, keyboard
  navigation and safe project switching. GUI/MCP sessions retain one fixed project.
- Nested template UI, source navigation, local additions/suppression/reparent,
  per-field origin/Revert and conflict preservation. Parented gizmos have tested
  transforms, cancellation and one committed Undo operation.
- Explicit Project settings with file-content revisions and atomic save; per-scene
  Simulation remains a separate authoring transaction. Live theme/layout reload
  validates candidates and keeps working state on malformed edits.
- Standalone PNG/JPEG assets; versioned material records and explicit portable
  cache profile/toolchain identity. Clearing cache preserves identity and overrides
  when original sources and sidecars are reimported.
- Normalized Slang reflection, shader artifact hashes and renderer ABI compatibility
  validation. Real compile failure, changed binding/matrix layout and invalid SPIR-V
  keep a working pipeline; compatible pixel-changing reload succeeds.
- Physics debug box outlines, bounded raw Player profiles, observed validation
  activation, CPU/GPU/readback durations and allocation counters.
- MCP broken-pipe/EOF handling and fresh GUI capture after presentation back-pressure.
  A real GUI + stdio regression performs 12 PNG captures, a conflicting edit and Undo.
- English manual guides for workspace, templates, Blender, export and profiling,
  alongside compiled C++ tutorials. Generated UI references remain visual guidance.

Acceptance evidence:

- The integrated Linux test suite passes **29/29 tests**, including ten GPU tests:
  native CPU, Vulkan, UI, real MCP transport, plugins, schema, physics and playable
  input routes. Strict MkDocs also passes.
- `tools/verify_playable_exports.py` exported the exact 2D/3D samples in Release,
  imported the Blender arch, checked package hashes and relocated each package outside
  its project. With the source-project paths unavailable, both passed validation and
  120 offscreen frames on RTX 2080 Ti with the Khronos layer active and zero errors.
- Renderer/shader regressions also passed the pinned Linux SwiftShader driver. This
  is additional software-driver coverage, separate from Windows execution.
- `tools/measure_workflows.py` recorded a fresh sample Debug build and incremental
  iteration, including stale-schema transitions. On the development host, the
  initial build took 93.06 s, unchanged build 5.59 s, changed gameplay build 11.18 s,
  and the subsequent one-frame Player process 0.37 s. The first/cached small Blender
  arch imports each took about 0.047 s including Editor startup. Ambient builds were
  running; these are observations, not release budgets.
- Profiling identified uncached readback memory as a concrete bottleneck. In a small
  paired five-frame diagnostic, preferring compatible HOST_CACHED memory reduced
  median readback from 27.87 to 0.47 ms and renderer-call wall time from 30.81 to
  2.92 ms. GPU work was about 0.58 ms. A longer final baseline is still required.

This remains an implementation checkpoint. Windows full graphics/export CI is still
building its pinned software driver. A review also identified Windows Unicode path
boundaries that must be corrected before cross-platform acceptance. Clean offline
build verification, final performance baselines and the final acceptance record
remain open; no MVP tag has been created.

### Checks after checkpoint 3

- Public commit: `d834cfad67cd81d8c4998b90c16791361ca8c0f8`.
- Linux and Windows headless CI plus strict manual passed in GitHub run
  [35295534027](https://github.com/emil28092005/Faset_Engine/actions/runs/35295534027).
- A clean committed source snapshot built all native targets with external networking
  disabled; all 19 CPU tests passed. The recorded build/test phase took 174.03 s.
  [Offline evidence](validation/offline-linux-2026-09-18.json) distinguishes prepared
  system tools from source/dependency inputs. GPU/window checks remain separate.
- The first full Windows graphics job compiled the whole Editor successfully, then
  failed creating a Vulkan instance with its CI software driver. Its CPU SceneView
  test also reported a texture-loading error. These are acceptance failures under
  investigation, not verified Windows graphics/export support.

## Checkpoint 4 — portability and acceptance hardening

Implemented after concrete regression findings:

- UTF-8 project, resource, plugin, CLI and subprocess boundaries. Windows native paths
  stay wide internally; Editor/Player/SchemaExporter normalize `wmain` arguments.
  File reads, hashes and atomic writes use extended native paths. All Faset Windows
  executables declare long-path support; CI enables the documented developer policy.
- Normal Stop requests Player shutdown before bounded termination fallback. Real
  `onDestroy` execution was observed, and a dedicated Player fixture verifies that
  callback diagnostics also reach logs during shutdown. Custom component versions
  are checked against the linked gameplay schema, including data-only components.
- POSIX subprocess cleanup keeps the exited leader's PID reserved while terminating
  its owned process group, then reaps it. A regression verifies that a descendant
  ignoring SIGTERM cannot survive normal leader exit or cancellation, without losing
  the leader's stdout tail or signaling a reused process-group ID.
- Transparent sprites use stable layer/depth ordering without depth writes, avoiding
  invisible sprites hiding objects behind them. GPU regressions cover alpha layering,
  shader/capture paths longer than 300 characters, and window capture after resize.
- Editor/launcher DPI scaling, logical-unit layout persistence and safe cancellation
  of unfinished drags on scale changes. Retained UI tests cover 1×/2× text rasterization,
  clipping, hit testing and text-input rectangles.
- Manual import-removal review with exact IDs/names and explicit acceptance. Both the
  reviewed candidate and active generation are checked before publishing, so stale
  confirmation cannot apply a different import. The GUI regression exercises rejection,
  fresh review and successful acceptance through actual widget events.
- Extended template workflow now saves through UI controls and opens a new Session,
  comparing IDs, nested origins, local additions and resolved values.
- Blender verification now updates two instances in one live Editor/SceneView, preserves
  placement, tint, physics and opaque gameplay fields, and retains both visible meshes
  after a removal conflict. [Blender evidence](validation/blender-live-linux-2026-09-18.json).

Observed Linux integration: **32 passed, 1 skipped, 0 failed** in the 33-test suite.
The skip is native Wayland programmatic restore, which the compositor declined;
the same lifecycle scenario passed under XWayland. ASan/UBSan passed **17/17** tests.
Strict MkDocs passed. [Recovery evidence](validation/editor-recovery-linux-2026-09-18.json)
records actual Editor termination and failed save/import/build/Player scenarios.
[Release baseline](validation/linux-release-2026-09-18/README.md) records the two
relocated Unicode-path packages and 240-frame profiles with their scope and hashes.

Windows execution of these fixes remains a separate gate. The previous fast CPU run
isolated a 264-character cooked path failure; the new native-path fixes must pass on
Windows before that issue is considered closed there. Native OS IME composition and
moving between physical monitors still have less coverage than deterministic widget
and platform-boundary tests. No MVP tag has been created.

The final build-service review also reproduced a publication defect: an invalid
custom-field default can pass the build stage's shallow schema check before the
Editor rejects it. Full schema validation before publishing `last_build.json` is the
next bounded correction; checkpoint 4 does not claim this gate is already complete.


## Acceptance corrections after checkpoint 4

Gameplay schema publication now uses the same complete metadata validation as the
Editor, before either the Player generation or `last_build.json` is published.
A native fixture drives the real BuildService with valid custom schema v2 and twelve
invalid manifests, checking that the previous binary, schema, manifest and pointer
remain unchanged. The focused authoring/process/schema/Session/MCP suite passed 5/5.
An authoring-disabled Player configuration still builds without editor services.

Windows native checks passed for checkpoint 4 (`45bc352`) and `afd773f`, including
the previous long-path regression. The full graphics runner also passed its Vulkan
1.3 device probe after registering the pinned software ICD on the disposable elevated
runner. Full Windows graphics and export acceptance is still in progress; a successful
probe alone does not close that gate.

The final audit identified additional bounded work: source/dependency freshness in
the Assets panel, scrolling keyboard focus into view, delivery of explicit gameplay
schema migrations, GPU pass labels, and wiring optional ImGui diagnostics. These
remain under implementation and verification; the research map now links current
implementation evidence instead of claiming the engine has not been started.

## Checkpoint 5 — close the final authoring and diagnostics gaps

- Asset freshness compares source, bundle payload, external buffer/image, recipe,
  importer and profile contents without publishing a generation. GUI and MCP expose
  the same state/reasons; selecting a stale imported row prepares Reimport. Cook and
  export reject stale referenced sources while keeping the previous successful result.
- Gameplay schemas carry validated declarative migration steps. Inspector and MCP
  apply `component.migrate` as an explicit revision-checked Undo transaction. Opening
  old data remains possible without rules. Tests cover local components, instance-local
  additions, opening inherited sources, missing/manual rules and overflow rollback.
  The Manual explains the sparse-override limitation when field units change.
- Keyboard focus scrolls long and nested Inspector/Assets lists into view at 1×/2×,
  preserves unfinished text and keeps invalid numeric edits visible. Template preview
  and conflicts are also invalidated when schema metadata changes without a scene edit.
- Vulkan passes emit optional debug-utils labels. An optional `FASET_DEBUG_IMGUI=ON`
  Editor module shows real renderer diagnostics via F12; the Player remains independent.
  GPU tests cover textured/clipped ImGui geometry and event ownership for gestures
  crossing the panel in either direction. Offscreen clipboard operations are local
  to that renderer and never touch the desktop clipboard.
- The Windows launcher fixture compares canonical filesystem identities, including
  hosted-runner short TEMP aliases, and now distinguishes selection/path failures.

Integrated Linux with optional diagnostics enabled: **34 passed, 1 skipped, 0 failed**
of 35 tests. The skip remains native Wayland programmatic restore; XWayland passed.
ASan/UBSan passed **18/18**, including process cleanup, metadata publication and
migration transactions. Strict MkDocs and local Markdown file-link checks passed.

Windows run `35299805623` at `e0b9651` passed all **34** tests in its CPU/GPU/UI suite,
including the launcher fix, and proceeded to real native Release exports. That run
predates checkpoint 5's new authoring/diagnostic changes, whose Windows checks remain
separate. The next full Windows build enables the optional diagnostic module too.
No MVP tag is claimed at this checkpoint.

## Checkpoint 5 acceptance and source relocation correction

The clean `0f34b03` Linux checkout built offline with 20/20 CPU tests, then created
and rendered a fresh project using the Manual's command. Both checked-in games were
exported in Release, moved outside the SDK into Unicode paths and run for 120 frames
with source projects hidden; Khronos validation was active with no errors. All seven
recovery scenarios and the real Blender/live-Editor round-trip passed. Exact inputs,
hashes and limits are in [the Linux acceptance record](validation/checkpoint5-linux-2026-09-18/README.md).

A subsequent source-relocation regression was reproduced and corrected: a cache-hit
rename/move updated the logical source pointer while retaining the historical payload
path, so the new freshness check incorrectly kept the asset stale. Publication now
stores both paths atomically. Earlier pointers remain readable by resolving the
payload relative to the moved logical source; immutable content generations and cache
keys are unchanged. Regression cases cover PNG, Blender bundles and external glTF
buffers/images, with both new and legacy pointer records. Full Linux integration
remains 34 passed / 1 explicit Wayland skip / 0 failed; targeted ASan/UBSan asset/cook
checks passed 2/2 after this correction.

Windows run `35299805623` at `e0b9651` completed successfully, including both Release
integration exports, incremental C++ rebuilding, and the two checked-in games with
Unicode relocation. It used SwiftShader without the Khronos validation layer and is
functional software-Vulkan evidence, not a physical-GPU benchmark. Checkpoint 5's
newer Windows graphics/export run and the relocation correction have their own
revision-specific gates.

## MVP acceptance — `v0.1.0-mvp`

Final engine source: `4cb82556de31268d2bde73948dd1ff1b6c02f162`. The publication
commit adds documentation, acceptance records and research-viewer wording; it does
not change the accepted engine, gameplay, shader or build-system sources.

- [Final Linux evidence](validation/final-linux-2026-09-18/README.md): 34 passed,
  one explicit native Wayland restore skip, zero failed. Both exact-source Release
  games passed manifest validation and 120 frames after Unicode relocation with
  their source projects hidden. An additional private namespace hid the entire SDK,
  build directories, Editor and cached tools; both games still passed another 120
  frames with matching captures, active Khronos validation and zero errors.
- [Final Windows evidence](validation/windows-software-vulkan-2026-09-18/README.md):
  [run 35301244334](https://github.com/emil28092005/Faset_Engine/actions/runs/35301244334)
  passed the fresh full Editor build with ImGui diagnostics, **35/35 tests**, real
  BuildService Release exports/incremental Debug rebuild and both checked-in games
  after Unicode relocation. Each rendered 120 frames. SwiftShader supplied software
  Vulkan; the Khronos layer was unavailable. This is functional Windows execution,
  not physical Windows GPU or hardware-performance evidence.
- [Native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35301244366)
  passed for the same final source. The earlier clean offline build and first project
  launch, seven recovery scenarios, actual Blender/live-Editor round-trip and full
  18-test sanitizer run retain their `0f34b03` provenance. The two affected asset/cook
  sanitizer checks passed again after the relocation correction.
- PLAN now closes M0–M9 against the dossier. The English Manual documents the working
  C++ tutorials, metadata/migrations, authoring, assets, MCP, extensions and export.
  A final instruction check corrected the 3D sample's required first bundle import.
  The recorded reference-scene thresholds are initial P1 tracking budgets.

Final publication checks passed: strict MkDocs build, both research-map tests and its
production build, 318 local Markdown links, retained Windows evidence hashes, all
validation JSON records and `git diff --check`. The engine-source diff from the
accepted commit is empty; no untested engine changes were bundled into publication.

The post-publication documentation check also verified hashes against Git blobs,
which normalize Windows JSON line endings to LF. Evidence indices now identify both
the retained repository bytes and original CRLF artifacts explicitly. This follow-up
changes only documentation metadata and preserves the first MVP tag and engine code.

Known coverage limits remain: real OS IME composition, movement between physical
monitors with different scales, native Wayland programmatic restore and additional
GPU/driver families. Widget composition/DPI, SDL text-input boundaries, XWayland and
Windows window lifecycle have their own passing evidence. The narrow static-mesh,
root-level box-physics, one-window/C++ MVP profile remains explicit. Lua and advanced
graphics are later work. UI references guide appearance; they do not define behavior.

## Post-MVP checkpoint — P2 GPU visibility and prepared mesh LOD

The historical MVP statement above describes the `v0.1.0-mvp` scope. Subsequent
work added the optional Lua module and the P2 visibility path. The P2 renderer keeps
`VisibilityMode::Direct` as its default and reference. Scene extraction supplies
stable per-primitive keys and view metadata. `DrawItem` accepts optional prepared
coarse meshes. The renderer tracks generation-checked temporal identity and previous
rendered transforms, derives conservative bounds, and selects a prepared LOD by
projected size with hysteresis. There is no automatic mesh
decimator or cluster/streaming geometry system.

For opaque static meshes, `GpuFrustum` groups compatible geometry/material into
fixed bins and fills indirect instance counts/visible IDs on the GPU. `GpuOcclusion`
adds previous-frame HZB classification, Main raster, a current forward-Z furthest-depth
HZB, and Post culling/raster so a newly revealed object can appear in the same final
frame. History resets on camera cut, changed view/extent/projection, and incompatible
instance identity. Shadow casters, transparent meshes, sprites and UI remain on their
independent paths; they are not hidden by the camera's opaque HZB. The GPU modes are
lazy-initialized and require the checked Vulkan capabilities and shader bundle.
Shader reload rebuilds both direct and GPU scene pipelines, preserving the working
pipelines on failure.

The Editor's ImGui diagnostics can select Direct, GPU frustum or GPU occlusion,
inspect pass timings/counters and request a current-HZB preview. A Player run can
choose `--visibility direct|gpu-frustum|gpu-occlusion`; Direct remains its default.
The profile records the requested mode and per-frame `gpu_visibility_active` so a
silent fallback is not mistaken for measured GPU work. The Release Player CLI test
checks all three modes and rejects an invalid value. Counter and HZB readback are
opt-in diagnostics; the visibility decision itself stays on the GPU.
The existing framebuffer capture still waits for completion and reads back each
frame. Consequently, full-frame benchmark times include that path and must not be
presented as isolated culling costs.

At renderer checkpoint `ae537c0`, the Linux reference build's full CTest suite
reported 57 registered tests, zero failures and one existing native-window lifecycle
skip. Fifteen offscreen P2 acceptance cases passed with Vulkan validation active and
zero reported errors, including capacity boundaries, door reveal, camera changes,
multi-view history, LOD hysteresis, shadow independence and transparency. Shader
reflection/export and GPU shader reload have focused tests. The
[P2 acceptance protocol](studies/19-p2-gpu-visibility-acceptance.md) contains the
command, tolerance and scene definitions. The
[initial three-run benchmark report](studies/20-p2-gpu-visibility-benchmark-2026-09-23.md)
retains all 810 raw frame records, device/build details, p50/p95 values and limits.
At that pre-optimization checkpoint, GPU `MainCull` took about 3.9–18.2 ms p50 in
three synthetic Debug/validation scenes, far above the direct path's 0.24–0.50 ms
whole-GPU p50. This was an actionable regression, not the final P2 performance.

Optimization checkpoint `3be3d0d` moves GPU-written indirect arguments, visible IDs
and deferred buffers into device-local memory, uses staging copies for initialization
and optional diagnostics, and replaces contended CAS loops with bounded atomic add.
The [three-variant follow-up](studies/21-p2-gpu-visibility-optimization-2026-09-23.md)
isolates memory placement and then the shader change. With the same Debug/validation
scenes, `MainCull` p50 fell to 0.030–0.042 ms. Full GPU-command p50 for the open
GPU-frustum scene was 0.139 ms versus 0.498 ms direct; the occluded GPU-occlusion
scene was 0.188 ms versus 0.496 ms direct. All 2,430 sampled frames across variants
reported zero Vulkan validation errors; the final focused suite passed 18/18 and
both culling shaders passed `spirv-val`. These synthetic results do not establish
a shipping-frame speedup, especially on another device or game scene. These checks
establish the tested Linux configuration; they do not
establish P2 behavior on a physical Windows GPU or a broad driver matrix. The
[profiling manual](manual/editor/profiling.md) explains how to interpret the timings.

The independent Linux Release build completed all targets, including the prepared
LOD example. Its full CTest run reported 57 registered tests, zero failures and
one existing native-window lifecycle skip. The focused Release Player CLI test
selected all three visibility modes, verified active GPU status in the profile,
and rejected an invalid mode. Release build/test success establishes functional
coverage; at that checkpoint, Windows P2 was still unverified.

As an additional Linux software-Vulkan check, Lavapipe ran all 15 labelled P2
acceptance cases plus the standalone GPU visibility test and both example modes.
The GPU route was active and Vulkan validation reported zero errors. This adds a
second implementation for functional checks; Lavapipe timings are not physical-GPU
performance evidence.

The [P2 Linux evidence dossier](validation/p2-gpu-visibility-2026-09-23/README.md)
retains the exact Release builds, labelled GPU cases and relocated standalone Player
checks. Both sample games passed a fresh Release export, Unicode relocation away
from the SDK and 120 headless frames with validation and zero errors. Their packages
also ran six frames in each GPU visibility mode with an active GPU path and zero
validation errors. The 2D Direct/GPU captures matched pixel-for-pixel. The 3D GPU
modes matched each other; each differed from Direct at 7 of 921,600 raster-edge
pixels, with no missing geometry. Direct CPU vertex transformation and GPU shader
vertex transformation round differently at subpixel triangle boundaries. The
Debug benchmarks above and this Release functional record have different purposes;
neither establishes physical Windows GPU coverage.

Compatibility checkpoint `433bce0` followed the first red Windows P2 CI run. The
pinned SwiftShader device does not expose `shaderDrawParameters`; the Slang
`SV_InstanceID` builtin had emitted a SPIR-V `DrawParameters` capability, so the
renderer rejected the GPU route. Both GPU vertex entries now use raw
`SV_VulkanInstanceID` while their fixed indirect commands keep `firstInstance = 0`.
The renderer no longer requests that optional feature. The GPU smoke case now has
the `gpu;p2` CTest labels, so CPU-only native checks exclude it. A reflection test
rejects `DrawParameters` in the two generated vertex modules. On matching Linux
SwiftShader, all 16 P2 cases passed with the GPU path active; a deliberately
driverless CPU-only selection passed 26/26.

At this revision, [Windows graphics CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35918597688)
passed all 58 tests on pinned SwiftShader, including the P2 route and Windows
window/editor tests. Its two relocated Release example games each rendered 120
frames in the default Direct mode. [Native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35918597686)
also passed. The [SwiftShader compatibility dossier](validation/p2-swiftshader-2026-09-23/README.md)
records the cause, local commands, CI run and export report. Windows did not have
the Khronos validation layer, and no physical Windows GPU or driver-family
performance claim follows from this software-Vulkan result.

Independent P2 source review then found two contract gaps. Requested GPU occlusion
could silently run GPU frustum when HZB was unavailable, and stable instance
slot/generation lived only in the CPU tracker while GPU candidates used dense
frame-local indices. Follow-up `22012c1` records the requested and effective
visibility mode per frame in renderer statistics, Player profiles/output and
Editor diagnostics, with a CPU capability-policy regression. GPU instance records
now carry stable slot and all 64 generation bits in previously reserved metadata;
dense indices remain addresses into the current frame's instance buffer. A focused
reorder/replacement/anonymous-instance test covers the metadata packing. The
reviewer rechecked both fixes and found no remaining load-bearing issue in those
paths. On this revision, full Linux Debug and Release CTest each reported 57
registered tests, zero failures and one existing native-window lifecycle skip. The dedicated ImGui overlay test passed
1/1; pinned Linux SwiftShader passed all 16 P2 cases and Player diagnostics; a
driverless CPU-only Release selection passed 26/26. The final
[Windows graphics CI run](https://github.com/emil28092005/Faset_Engine/actions/runs/35922643226)
passed all 58 tests without skips on SwiftShader; both relocated Release games
rendered 120 frames in Direct mode. The corresponding
[native/manual CI run](https://github.com/emil28092005/Faset_Engine/actions/runs/35922643004)
passed on Linux and Windows. Unsupported-HZB integration and physical Windows
GPU coverage remain untested.

## Post-MVP checkpoint — P1 gameplay iteration

P1 adds a complete-input native build stamp and a content-addressed `Scripts` copy.
The package key binds configuration, recipe, source, Lua declaration, toolchain,
shader and runtime artifacts. A second unchanged build reuses a verified schema
and package generation without invoking SchemaExporter; CMake/Ninja still verify
the native graph. Malformed/corrupt generations, modified headers/tools and
detected source mismatches cannot publish a false hit. The live tree and staged
copy are rehashed after native build and before reuse/publication; a same-user
write-and-restore during compiler reads remains outside this check. Failed jobs
preserve the previous successful pointer, while Inspector metadata becomes stale.

Compiler and Lua output now produce bounded structured Console diagnostics with
raw logs retained. Source opening accepts only project `Scripts` files and passes
literal file/line/column arguments to the configured external editor. A real
compile failure revealed that compiler paths pointed to the staged copy;
`d7a7a7c` maps only the verified snapshot subtree back to project-relative
source. The same correction retains a later actionable error after 250 unrelated
warnings. Four runnable C++/Lua × 2D/3D starters are available in launcher and
CLI; the existing scaffold default remains compatible. Named dirty scenes
autosave after two idle seconds by default; unnamed scenes require Save As, and
disk/revision conflicts retain the journal and never overwrite external edits.

The [P1 dated dossier](validation/p1-iteration-2026-09-24/README.md) retains a
clean-revision `6c2e8fa` Debug workflow with every raw command/profile. On the
Ryzen 7 1700/RTX 2080 Ti Linux host, five unchanged builds had median 11.53 s,
five changed-C++ builds 28.16 s, five changed-header builds 23.89 s, and five
watched Lua reloads 0.502 s. All five unchanged builds reported a verified
generation reuse. The 3,000-frame profile showed no growth in the explicit
Vulkan allocation counter (15,787,008 bytes). A seeded 527-object synthetic
scene reached 149.39 ms p95 wall time, dominated by CPU simulation/snapshot;
this is a visible scalability issue, not a tiny-demo Release budget comparison.
The historical exact-scene Release budgets were met in the earlier 2026-09-18
record, but that evolving working-tree baseline does not certify the current
revision. A clean `4a3453e` physical-GPU rerun now covers both exact-scene
source-hidden Release games, sequentially for 240 frames at 1280×720 with
active Khronos validation. 2D/3D p95 frame wall was 2.694/3.036 ms, GPU
0.573/0.617 ms, readback 0.559/0.561 ms, simulation 0.242/0.300 ms, snapshot
0.197/0.288 ms; startup from `main()` was 295.4/248.3 ms. These meet their
initial tracking budgets. Explicit Vulkan allocation instead reached
45,112,032/45,212,272 bytes (43.02/43.12 MiB), exceeding the 20 MiB target:
eager 2048² D32 sun and local atlases consume 16 MiB each even in the 2D
fixture with zero shadow raster. This memory miss is recorded, not silently
rebaselined. The same clean build exported and source-hidden relocated C++ 2D,
C++ 3D with Blender import, and Lua-only games; all rendered 120 frames with
validation active and zero reported errors.

Linux focused cache, diagnostics, schema and workflow-math tests pass; a real
failed-build replay now reports navigable `Scripts/Gameplay.cpp:73:2`. The
[Lua-only Release result](validation/lua-release-2026-09-24/README.md) validated
and rendered after source-hidden relocation on the physical Linux GPU. At
`6c2e8fa`, [native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35936310287)
passed on Linux and Windows. Its Windows graphics job passed all 61 CTests on
SwiftShader, then hit an invalid integration fixture under the engine checkout;
`4ac02ee` moved the fixture to runner temporary storage. The subsequent
[Windows graphics run](https://github.com/emil28092005/Faset_Engine/actions/runs/35937433040)
passed all 61 CTests and the real export integration. Two C++ and one Lua-only
Release package validated and rendered 120 frames each after relocation with
source paths unavailable; the [raw Windows report](validation/p1-iteration-2026-09-24/windows-4ac02ee/playable-report.json)
records hashes and software Vulkan device identity. The later `d7a7a7c`
real-diagnostic-navigation assertion is covered by the clean combined
[`4a3453e` Windows graphics run](https://github.com/emil28092005/Faset_Engine/actions/runs/35944875002):
74/74 CTests, real export integration and three relocated games passed.
Windows had no active Khronos validation layer, and no physical Windows GPU
performance result is claimed.

## P3 lighting checkpoint — authored lights and bounded shadow views

At source revision `b191ae0`, the versioned `faset.light` schema and SceneView
extract directional, point, and spot lights. Any authored Light, even disabled,
suppresses the compatibility sun; scenes without a Light keep their previous
appearance. The renderer validates all local records, then selects at most 128
by priority, projected influence, and stable ID. A single typed lighting
descriptor ABI serves Direct and P2 GPU graphics: materials remain set 0,
lighting is set 1, GPU scene graphics data moves to set 2, and existing push
constant sizes remain unchanged. Both paths shade the same sun/local PBR lights
before tone mapping.

A pure CPU shadow planner builds up to four texel-snapped sun cascades from an
explicit camera frustum, ending at at most 80 world units; a low-level Snapshot
without the frustum keeps one shadow view. Shadow caster bounds come from the
source LOD-0 draw and are tested against the light view, independently of
camera/P2 culling. The Vulkan backend renders the sun to its own D32 atlas and
point/spot shadows to a separate 4×4 D32 atlas. A point light claims six faces
atomically, a spot one. Both atlases try 2048² and then 1024² if required by
capabilities or allocation. The combined frame budget is 4096 caster draws;
scheduled tiles are cleared and redrawn each frame. Overflow, disabled shadow,
or unavailable atlas leaves a submitted light illuminating without shadow.
There is no hidden sun raster when the sun is absent, its shadow is disabled, or
the scene only has sprites. Atlas ownership, dropout, submitted light counts,
actual raster work and GPU timings are exposed in `FrameStats`, Player profiles
and the optional Editor diagnostics overlay.

The implementation's Linux Debug checkpoint at `a5fb216` built all targets and
ran 60 CTests with no failures; the existing native window lifecycle test
skipped under the compositor. The optional ImGui overlay passed its dedicated
test in an enabled build. After benchmark integration at `b191ae0`, six focused
tests passed, including the real Vulkan benchmark smoke. These are bounded
checks, not a final P3 acceptance run. The [lighting validation record](validation/p3-lighting-2026-09-24/README.md)
lists cases, exact revision, and remaining Windows/Release evidence.

The fixed-scene Release reference-GPU sweep uses 1920×1080, 0/4/16/32/64/128
lights, Direct/GPU frustum/GPU occlusion, shadows on/off, three independent
repeats, ten warm-up and thirty measured frames per configuration. It reached
the agreed Forward+ gate: main-raster overhead at 32 lights was about 0.50 ms
relative to the matching zero-light case, roughly 30% of that GPU frame;
64 and 128 lights added about 1.02 and 2.03 ms. Its exact-revision raw CSV and
report are retained in [study 22](studies/22-p3-lighting-benchmark-2026-09-24.md).

Revision `a0a4e29` adds an explicit depth-free 16×16 tiled Forward+ path. One
compute invocation tests every submitted point/spot range sphere against a
tile's four screen-space planes and writes at most 64 stable-order indices.
An overflowing tile scans the entire submitted list in the fragment shader;
there is no dropped light. The tile shader has exact reflection validation,
package/build integration, GPU timing, optional occupancy readback, and
reload rollback. Direct, GPU frustum and GPU occlusion image tests cover a
cropped viewport, resize, near-plane light/shadow, and overflow. A 128-light
localized 1920×1080 forward/tiled capture matched byte for byte.

The [paired Release study](studies/23-p3-forward-plus-2026-09-24.md) measured
tile build **plus** raster on the same RTX 2080 Ti source revision and shader
bundle. At 32/64/128 broad overlapping lights it was 0.064/0.122/0.222 ms
slower; all 8160 tiles overflowed at 128. A separate localized-range scene
was 0.103/0.214/0.440 ms faster at those counts, with no overflows. There is
no robust scene/device runtime predictor yet, so `Auto` remains forward and
`Tiled` is explicit. Linux Debug passed 62 CTests with one window skip;
pinned Linux SwiftShader passed all six P3 cases. At `a0a4e29`,
[native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35939232585)
and [Windows graphics/SwiftShader CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35939232615)
passed. The Windows job completed all 64 CTests and ran two relocated Release
games for 120 frames each. The later combined and temporal acceptance follows
below; this paragraph describes only the original lighting checkpoint.

## P1+P3 combined renderer checkpoint

At clean source `4a3453e`, the integrated P1 cache, P3 lighting/Forward+ and
first-generation temporal renderer built on Linux and passed 72 of 73 Debug
CTests with one compositor-dependent native window skip and no failures. The
[native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35944874993)
passed on Linux and Windows; the
[Windows graphics CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35944875002)
passed 74/74 CTests on pinned SwiftShader, the real Release export integration,
and three relocated 120-frame C++ 2D, C++ 3D and Lua-only games. The matching
Linux physical-GPU export check rendered the same three source-hidden packages
for 120 frames with active Khronos validation and no reported errors; the P1
[final Release dossier](validation/p1-iteration-2026-09-24/final-release/README.md)
also profiles the exact C++ demo scenes for 240 frames. Their time budgets
passed, but the old ≤20 MiB explicit-allocation target missed at 43.02/43.12
MiB due to two eager 16 MiB shadow atlases.

The [integrated P3 lighting repeat](studies/24-p3-integrated-forward-plus-2026-09-24.md)
retains 7,560 per-frame raw rows at 1920×1080, both shadow states, three
visibility paths and a separately labelled localized-light workload. On the
dense fixture, tile build plus raster was 11–13% slower at 32–128 lights;
localized light ranges made it 43–54% faster. `Auto` therefore remains forward
and `Tiled` explicit. This is pass-local cost on a single GPU, not a full-game
speedup or a physical Windows performance claim. The
[temporal dossier](validation/p3-temporal-2026-09-24/README.md) records Off,
TAA and 0.67 Upscale raw image sequences and bounded 720p cost on the physical
Linux GPU, with its own exact shader-source revision. TAA/Upscale remain opt-in
because scene quality and whole-frame
timing require game-specific comparison.

At clean source `ed523c6`, the final integrated temporal matrix repeated all
1,386 lossless frames across Direct, GPU frustum and GPU occlusion after adding
optional accepted/rejected-history pixel diagnostics and fixing the resize path
with diagnostic readback enabled. The failed Direct-to-GPU mode switch now
restores active TAA pipelines and history for a safe retry; a real Vulkan RED
test reproduced the old null-pipeline failure. Every frame used active Vulkan
validation and
reported zero errors; the 1,388 generated PNGs, including two contact sheets,
were byte-identical to the earlier branch matrix. The
[final matrix dossier](validation/p3-temporal-2026-09-24/matrix/integrated-ed523c6/README.md)
records the exact binary and shader hashes, eight post-open disocclusion frames,
reset comparisons, the 2× spatial reference and a separate 90-frame 720p
Off/TAA/Upscale profile. This bounded fixture shows reduced static-wire frame
variation, but its spatial reference has lower error and 0.67 Upscale does not
improve whole-frame GPU time. Both temporal modes remain opt-in; the diagnostic
GPU counter remains off during performance measurements.

At the same clean revision, Build and Export results carry the worker's
validated gameplay-source hash. A controlled queued-edit test first reproduced
the false stale-schema state, then passed after the fix. The complete Linux
Debug suite passed 76 of 77 CTests with one compositor-dependent window skip;
24 focused Linux Release tests passed. The real Release Editor exported the C++
2D, C++ 3D with Blender asset, and Lua-only games; each relocated package ran
120 offscreen frames on the physical RTX 2080 Ti with active Vulkan validation
and zero errors while the source project paths were hidden. The
[final combined dossier](validation/p1-p3-final-2026-09-24/README.md) holds the
clean-source verifier report and package manifests.