Repository navigation
feat(foundation): Phase 5 composition root and Phase 6 milestone completion - #8
Merged
Merged
Conversation
- Wire spawn-core, spawn-platform, spawn-input, and spawn-render in the root spawn-engine composition package (default-features = false globally; wayland + vulkan enabled under cfg(target_os = "linux") for cross-OS CI). - Add hand-written located/coded EngineError (ENGN-0001..0007, ADR-0009) and validated RuntimeOptions (SPAWN_SMOKE_SECONDS, SPAWN_SMOKE_GRAB). - Implement single-threaded poll/tick/present loop with development-only Escape action, idempotent CloseRequested handling, validation-error failure enforcement (SPN-INV-092), and reverse teardown (Renderer -> Window -> Platform). - Add automated headless verification tests in tests/foundation_verification.rs covering FND-T08, FND-T09, FND-T10, and FND-INV-05/06/08.
- Update root AGENTS.md, docs/README.md, and docs/architecture/DESIGN.md for
the implemented spawn-engine composition root and inter-crate dependency edges.
- Update docs/foundation/{README,SPEC,INVARIANTS,PLAN,VERIFICATION}.md with
automated FND-T01..T10 coverage, recorded Hyprland + Vulkan validation
smoke runs (including compositor xdg_toplevel.close, cursor lock, resizes,
and failure diagnostics), and explicit untested platform/interaction scope.
brasga-a
changed the base branch from
feat/foundation-fixes-and-input
to
master
November 18, 2026 19:39
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Foundation Phase 5 composition root (
spawn-engine) and Phase 6 milestone completion & verification documentation.Summary of changes
1. Phase 5 composition root (
spawn-engine:Cargo.toml,src/{lib,main,error,options,runtime,native}.rs)spawn-enginedepends onspawn-core,spawn-input,spawn-platform, andspawn-render(version = "0.1.0",default-features = falseglobally) and enablesspawn-platform/wayland+spawn-render/vulkanonly under[target.'cfg(target_os = "linux")'.dependencies](withversion = "0.1.0"added onspawn-input's path dependencies socargo deny checkpasses withspawn-enginein the normal graph). Non-Linux targets build and pass all headless tests cleanly and returnENGN-0002(UnsupportedPlatform) at runtime.#![forbid(unsafe_code)], ADR-0009): hand-writtenEngineErrorandEngineErrorKind(ENGN-0001..0007) carrying#[track_caller]Location, stable error code, contextual detail, non-duplicated flattened cause chain, and optionalBacktrace; zero non-testunwrap/expect/panic!/todo!.RuntimeOptions):from_env/from_env_valuesparsing and validatingSPAWN_SMOKE_SECONDSandSPAWN_SMOKE_GRAB, rejecting malformed, non-finite, or out-of-range values withENGN-0001.run_session<B: RuntimeBackend>& Linuxrun_native):RuntimeOptions→InputStatewith composition-owned development-onlyEscapeexit action → 60 Hz / max-catch-up-4FixedStepClock→Platform→Window→Renderer→ post-startup monotonic clock anchor).Event::Windowrouting on the ownedwindow_idbefore feedingInputState, handlesCloseRequestedidempotently, bounds idle waits to 50 ms while occluded or zero-size suspended, drains Vulkan validation messages and fails withENGN-0006on any validation error (SPN-INV-092), and tears down owned resources in strict reverse order (Renderer→Window→Platform).2. Automated foundation verification suite (
tests/foundation_verification.rs)FND-T08: failure injection across option validation,create_platform,create_window,create_renderer, post-rendererset_cursor_grab, mid-loop fatal render error, and validation-layer error — proving exact reverse drop order (Renderer→Window→Platform) once per initialized resource with zero panics.FND-T09: automatedcargo metadata --no-deps, manifest parsing + Kahn topological cycle check across all workspace packages,cargo tree -e normalheadless hygiene checks (spawn-core,spawn-platform,spawn-render,spawn-input), and source/public-API audit proving private backend modules, zero leaked backend concrete types (SPN-INV-011), and zero genre terms in public APIs (SPN-INV-003).FND-T10: foreign-windowEscapeandCloseRequestedisolation, triple duplicateCloseRequestedbatch idempotency, and sub-tickEscapeaction exit.FND-INV-05/06/08: zero-size suspend (bounded wait, no frame acquire/present), surfaceSkippedrecovery, valid resize, and 100 ms stall catch-up clamp preserving monotonicTick(0..=9)without resetting simulation time.3. Phase 6 milestone completion & documentation sync (
828fd16)AGENTS.md,docs/README.md,docs/architecture/DESIGN.md, anddocs/foundation/{README,SPEC,INVARIANTS,PLAN,VERIFICATION}.mdwith theEXISTSspawn-enginecomposition root, verified inter-crate dependency edges, completeFND-T01..T10automated coverage, recorded Hyprland + Khronos sync-validation smoke runs, and explicit untested boundaries (SPN-INV-100,SPN-INV-101).Requirements covered
FND-FR-01..11&FND-NFR-01..06(docs/foundation/SPEC.md): native window/surface startup, raw event routing, compositorxdg_toplevel.closeand composition-ownedEscapetermination, Vulkan 1.3 clear-frame presentation, resize and zero-size suspension, recoverable vs. fatal surface/device handling, decoupled 60 Hz fixed-step clock with bounded catch-up, tick-indexed input sampling, reverse resource teardown, and structuredENGN-0001..0007diagnostics.FND-T08,FND-T09,FND-T10(composition-root part), andFND-INV-05/06/08(tests/foundation_verification.rs): completing all 10 required automated verification casesFND-T01..T10.docs/foundation/VERIFICATION.md#exit-gate): items 1–7 satisfied for Linux/Wayland on the reference hardware, matching accepted ADRs 0001–0004, 0007, 0008, and 0009.Tests run
./scripts/check.sh(Rust 1.99.1 —fmt, workspaceclippy --all-targets -D warnings, headlesscargo test --workspace,rustdoc -D warnings,--features waylandclippy/test/doc,--features vulkanclippy/test/doc,cargo deny check):Workspace test breakdown (
cargo test --workspace— 142 passed; 0 failed; 4 ignored):spawn-core: 15 unit + 6 verification (FND-T01,FND-T02) + 1 doctest (22 passed).spawn-platform: 46 headless unit tests (FND-T05, platformFND-T10, Phase 2b relative motion & cursor constraint lifecycle).spawn-input: 12 unit + 15 verification (FND-T03,FND-T04, Phase 2bPointerRelativeMotionwiring, deterministic replay) + 1 doctest (28 passed).spawn-render: 37 headless unit tests (FND-T06,FND-T07, presentation controller &VkFailureclassification) + 4 opt-in GPU tests ignored by default.spawn-engine: 5 unit (EngineErrorformatting/cause-chain &RuntimeOptionsvalidation) + 4 verification (FND-T08,FND-T09,FND-T10,FND-INV-06) (9 passed).Opt-in Vulkan GPU tests with Khronos validation + synchronization validation (
RX 460 / RADV):Platforms tested
Tested on the reference machine: Omarchy 4.0.6 (Arch-based), Linux
7.2.15-1-omarchy, Hyprland0.56.2(Wayland native,xwayland: 0), AMD Radeon RX 460 (RADV POLARIS11, Mesa26.2.5-arch1.1, Vulkan1.4.354device, loader1.4.363), withVK_LAYER_KHRONOS_validation1.4.363+ synchronization validation active (VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true):SPAWN_SMOKE_SECONDS=2 SPAWN_SMOKE_GRAB=locked cargo run): mapped924x512 → 916x504,cursor_grab=Locked→ midpoint releasecursor_grab=None,ticks=119,presented=107,suspended=0,skipped=0,0validation errors, exit0.cargo run+hyprctl eval): floating toggle (916x504 → 934x522), exact pixel resize (720x480), special-workspace transitions (308x504 → 2530x1024 → 616x1024), and compositorxdg_toplevel.close(hl.dispatch(hl.dsp.window.close('pid:…'))) deliveredCloseRequestedand exited cleanly (CloseRequested,ticks=80,presented=82,suspended=0,skipped=0,0validation errors, exit0, no lingering process).WAYLAND_DISPLAY=/nonexistent cargo run→error[ENGN-0004]/PLAT-0001(exit1).VK_DRIVER_FILES=/nonexistent cargo run→error[ENGN-0005]/REND-0001(exit1).SPAWN_SMOKE_SECONDS=notanumber cargo run→error[ENGN-0001](exit1).Invariants touched
SPN-INV-001..006,SPN-INV-009,SPN-INV-011,SPN-INV-020..023,SPN-INV-030..034,SPN-INV-040..043,SPN-INV-060..061,SPN-INV-090..092,SPN-INV-100,SPN-INV-101;FND-INV-01..15.Known limitations
PLANNED): X11 (PLAT-0001/REND-0002) and Windows (Win32window/surface backend; non-Linux targets build and pass headless tests cleanly and returnENGN-0002at runtime). Windows support is neither tested nor claimed (SPN-INV-090).Occluded/ zero-size suspension (Hyprland0.56.2did not emitxdg_toplevelsuspendedon silent special-workspace moves; zero-size suspension and surface-loss/out-of-date recovery are verified by headlessFND-T06,FND-T07,FND-INV-06, and GPU headless-surface tests).PLANNED); clear-frame foundation runtime slice only (shaders/meshes, ECS scheduling, world/scene/assets, physics, audio, networking, and Luau scripting remain out of scope for Foundation).