Cinder: deliverable report

Living document. Every claim below was verified in this repository under the pinned toolchain on the date given; nothing is reported from memory or intention. Phases are those of the mission brief.

1. What was built (and what was not) #

2. Pinned version matrix #

3. Test results (Linux x86-64, lavapipe, 2026-11-09) #

Three consecutive full runs of tools/run_tests.sh and spikes/window/run_window_spike.sh, identical results each time (no flakes):

Gate items also verified: tools/lint_legacy_mojo.sh clean; --Werror on every Mojo test build; zero wgpu validation errors, device-lost or warning-level log events in spikes 1, 2 and 8 (the tests fail on any such event).

macOS: none of the above has been run on macOS. No Apple Silicon machine or runner was available to this run (see Blockers). Every phase gate therefore remains half open.

4. Benchmark results #

The reference hardware (Linux RTX 3060-class, Apple M2) is not available; the only GPU here is Mesa lavapipe (llvmpipe, LLVM 20.1.2) inside Docker on the Windows host's CPU. Every number below is from that configuration and is a regression baseline for it (bench/baselines/*.json, checked by tools/bench_check.py with a 10% tolerance), not a statement about the section 8 budgets. Method: docs/BENCHMARKS.md.

Section 8 budgets #

Results (pixi run bench-all, 1920x1080, high preset, headless) #

Adapter for both: llvmpipe (LLVM 20.1.2, 256 bits). Render time is almost all of frame time in both runs, and on this adapter the GPU work is software rasterisation of 1080p on the same CPU, so these numbers say nothing about the GPU budgets. The engine's CPU-only share of a frame was not isolated here (a Tracy capture on reference hardware would). The stress scene's physics p99 includes the frames in which the falling boxes first touch the floor and each other. The sample's bodies are mostly asleep, so its physics time is microseconds.

ECS vs flecs (pixi run bench-ecs: 100,000 entities, two archetypes, 100 frames of position += velocity * dt through a two-component query; flecs 4.2.0 through ecs_query_iter/ecs_query_next/ecs_field_w_size), container on the Windows host:

Within the 10% band required to keep the Mojo ECS (ADR-0011).

5. Known limitations and Mojo workarounds #

• ASan alloc_dealloc_mismatch disabled in tools/run_tests_asan.sh. KTX-Software at the pinned commit allocates Basis supercompression global data with new[] (lib/basis_encode.cpp, ktxTexture2_CompressBasisEx) and frees it with free (lib/texture2.c, ktxTexture2_destruct), an alloc-dealloc mismatch inside the vendored library that only the in-process encoder path (the cooker) hits. ASan cannot scope that check with a suppression file, so that single check is off for the sanitizer runs; heap overflow, use-after-free, LeakSanitizer and UBSan stay on for every library and all Mojo code. The submodule is not patched; revisit when the pin moves.

Defect sweep before v0.1.0 (Phase 9) #

Writing a docstring for every public symbol meant reading every public function, and that review found real defects. Each was fixed at its root with a test that exercises it. Where the agent or operator ran the new test against the old code, it failed there. The fixes, by area:

Remaining limitations found in the same review, documented in the guides:

• Only the first directional light is used (docs/guides/render.md).
• Physics destroy_shape cannot tell a stale copy of a shape handle from a new shape that Jolt allocated at the same address (docs/guides/physics.md).
• NativeLibrary's leak fix has no automated test: the allocation counter does not export a free count through the shim yet.

6. Deviations from the brief, each with its ADR #

7. Blockers escalated #

1. No macOS runner or machine. Exact problem: every gate requires both platforms; no Apple Silicon host was reachable from this session. Tried: none possible (Docker runs Linux only). Options: (a) enable the macos-14 job in .github/workflows/ci.yml by pushing to GitHub, (b) a local Apple Silicon machine running the same pixi tasks, (c) accept Linux-only gates for now and batch macOS verification later. Recommendation: (a), it is already written.
2. No reference GPU hardware for section 8. Same options; benchmarks will run on CI hardware for regression tracking, but budget compliance cannot be claimed from lavapipe.

8. Exact commands #

docker build -t cinder-toolchain:1 -f docker/Dockerfile.toolchain docker
tools/in_container.sh pixi install
tools/in_container.sh pixi run gen-dcimgui          # Dear Bindings C API (committed)
tools/in_container.sh pixi run -e bindgen bindgen   # cinder/ffi, layout printer, layout test (committed)
tools/in_container.sh pixi run native               # Release shim + CTest + layout facts
tools/in_container.sh pixi run native-sanitize      # Debug shim with ASan+UBSan + CTest
tools/in_container.sh pixi run test                 # lint, every Mojo test program, X11 + Wayland spikes
tools/in_container.sh pixi run format-check

Cooking assets and running the sample game: not available yet (Phases 5 and 8).