Validation and tooling

This file covers how the engine is checked and driven: the functional test suite’s shape and what it pins, the se developer CLI that resolves the toolchain and runs everything, and the continuous integration checkers that guard the rules a compiler cannot see.

1. Validation and tooling

The engine ships no device code of its own, so there is nothing to test in isolation — a meaningful test must instantiate kernels and run them against the real runtime. The suite in tests/ does exactly that: it follows SushiRuntime’s layout (unit/, integration/, a shared common/ with the GoogleTest entry point and a process-wide runtime fixture) and builds one binary, se_functional_tests — the target is sushiengine_functional_tests — as a SYCL translation-unit set. There are no mocks. Tests carry the Unit_* / Integration_* suite-name prefixes, which tests/CMakeLists.txt turns into CTest labels so a sub-suite is one ctest -L away. The integration tests re-run the sandbox and PGS claims as assertions (scalar-reference agreement, compile_count == 1); the unit tests pin the host bookkeeping (entity directory, swap-remove, command buffer, graph colouring).

tests/common/test_main.cpp installs SushiEngine::Tests::TestAssertionHandler (tests/common/test_assertion_handler.hpp) before RUN_ALL_TESTS. A failed SE_VERIFY anywhere in the binary is reported as a GoogleTest failure on the running test and execution continues; a failed SE_ASSERT or SE_FATAL is reported and then aborts the binary. A test that needs the default handler’s own behaviour, or one it supplies itself, installs it for a scope with ScopedAssertionHandler, which restores whichever handler was active on destruction.

Beyond the ECS/physics core, three areas are now covered directly. The engine/domain/astro/ solar-system model — pure double-precision maths with no device code — is verified against astronomical reference landmarks (J2000 = JD 2451545.0, Earth ~1 AU from the Sun, WGS84 semi-major/minor radii, ~9.8 m/s² surface gravity, Earth’s SOI ~0.9 Gm) and against structural invariants that hold regardless of the exact arithmetic: Kepler’s equation is satisfied by the returned anomaly; the ecliptic↔equatorial, topocentric, body-equatorial, and scene-frame transforms all round-trip to the identity; every basis is right-handed orthonormal; the symplectic integrator conserves orbital energy over a full revolution; and advance_astro_state keeps a low orbit bound and deterministic (Unit_JulianDate, Unit_OrbitalElements, Unit_CelestialBodies, Unit_Gravity, Unit_Topocentric, Unit_BodyOrientation, Unit_SurfaceFrame, Unit_StarCatalog, Unit_SceneFrame, Unit_ReferenceFrame, Integration_AstroDynamics, Integration_Ephemeris).

The camera/transform maths in engine/foundation/core/include/SushiEngine/core/types.hpp (quaternion rotation vs. its matrix form, the reverse-Z infinite-far projection, look_at, compose_transform) is pinned in Unit_MathPrimitives. The determinism guard rails — the seeded xorshift128+ RNG and the fixed-timestep accumulator — are pinned in Unit_RNG (identical seeds replay identically; a snapshot replays the future exactly, as rollback needs) and Unit_FixedTimestep (step count depends only on total elapsed time and not on how it was chunked across frames, for any chunking whose per-frame backlog stays inside the catch-up bound; and that a frame owing more than the bound drops the remainder rather than carrying it).

Build time is read, never instrumented. tools/build/report_build_times.py parses the .ninja_log Ninja writes in a build directory (build/default/ by default, --log for another lane) and prints the wall time, the summed unit time and their ratio, the per-target totals and the slowest outputs; --json writes every record for a before-and-after diff. Only the newest record of each output counts, so a log from an incremental build measures what happened to be stale; a baseline is a se build --clean log. The script invokes nothing, and its own tests run with python -m pytest tools/build.

The se developer CLI (cli/) is the counterpart to the runtime’s sr: a thin Typer layer over a service layer that issues the cmake/ctest calls. It owns no build knowledge the CMake does not — its job is to resolve the toolchain the engine consumes (SushiRuntime’s bundled clang++ and vcpkg) and snapshot the MSVC environment on Windows, then drive configure/build/test/run. The same one-way dependency holds: the CLI resolves the toolchain from the shared SushiStack workspace’s dependencies/ tree (falling back to a runtime-local copy for backward compatibility) but the engine never reaches back into runtime source.

2. The continuous integration checkers

Nine Python checkers guard rules a compiler cannot see. All of them run in one job, Structure and documentation rules (.github/workflows/ci.yml), each as its own step, and every one of them is run from the repository root and exits non-zero on a violation. They are listed here in the order that job runs them, so a red step maps to a row.