Skip to content

feat(foundation): Phase 5 composition root and Phase 6 milestone completion - #8

Merged
brasga-a merged 2 commits into
masterfrom
feat/foundation-complete
Nov 18, 2026
Merged

brasga-a merged 2 commits into
masterfrom
feat/foundation-complete

Conversation

@brasga-a

Copy link
Copy Markdown
Owner

Foundation Phase 5 composition root (spawn-engine) and Phase 6 milestone completion & verification documentation.

Stacked on #7 (Phases 1–3 fixes, Phase 2b, and Phase 4; not merged). This PR's base is feat/foundation-fixes-and-input (f77a3e3), which stacks on #6 (feat/render-vulkan-clear) → #5 (feat/platform-wayland) → master. Merge #5, #6, and #7 in order first, then retarget this PR to master.

Completes the Foundation milestone for Linux/Wayland + Vulkan 1.3 on the reference hardware (docs/foundation/VERIFICATION.md#exit-gate).

Summary of changes

1. Phase 5 composition root (spawn-engine: Cargo.toml, src/{lib,main,error,options,runtime,native}.rs)

  • Cross-platform manifest & headless buildability: spawn-engine depends on spawn-core, spawn-input, spawn-platform, and spawn-render (version = "0.1.0", default-features = false globally) and enables spawn-platform/wayland + spawn-render/vulkan only under [target.'cfg(target_os = "linux")'.dependencies] (with version = "0.1.0" added on spawn-input's path dependencies so cargo deny check passes with spawn-engine in the normal graph). Non-Linux targets build and pass all headless tests cleanly and return ENGN-0002 (UnsupportedPlatform) at runtime.
  • Safety & structured diagnostics (#![forbid(unsafe_code)], ADR-0009): hand-written EngineError and EngineErrorKind (ENGN-0001..0007) carrying #[track_caller] Location, stable error code, contextual detail, non-duplicated flattened cause chain, and optional Backtrace; zero non-test unwrap/expect/panic!/todo!.
  • Validated runtime configuration (RuntimeOptions): from_env / from_env_values parsing and validating SPAWN_SMOKE_SECONDS and SPAWN_SMOKE_GRAB, rejecting malformed, non-finite, or out-of-range values with ENGN-0001.
  • Single-threaded poll / fixed-step / present loop (run_session<B: RuntimeBackend> & Linux run_native):
    • Enforces deterministic initialization order (RuntimeOptions → InputState with composition-owned development-only Escape exit action → 60 Hz / max-catch-up-4 FixedStepClock → Platform → Window → Renderer → post-startup monotonic clock anchor).
    • Gates Event::Window routing on the owned window_id before feeding InputState, handles CloseRequested idempotently, bounds idle waits to 50 ms while occluded or zero-size suspended, drains Vulkan validation messages and fails with ENGN-0006 on 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-renderer set_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: automated cargo metadata --no-deps, manifest parsing + Kahn topological cycle check across all workspace packages, cargo tree -e normal headless 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-window Escape and CloseRequested isolation, triple duplicate CloseRequested batch idempotency, and sub-tick Escape action exit.
  • FND-INV-05/06/08: zero-size suspend (bounded wait, no frame acquire/present), surface Skipped recovery, valid resize, and 100 ms stall catch-up clamp preserving monotonic Tick(0..=9) without resetting simulation time.

3. Phase 6 milestone completion & documentation sync (828fd16)

  • Synchronized root AGENTS.md, docs/README.md, docs/architecture/DESIGN.md, and docs/foundation/{README,SPEC,INVARIANTS,PLAN,VERIFICATION}.md with the EXISTS spawn-engine composition root, verified inter-crate dependency edges, complete FND-T01..T10 automated 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, compositor xdg_toplevel.close and composition-owned Escape termination, 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 structured ENGN-0001..0007 diagnostics.
  • FND-T08, FND-T09, FND-T10 (composition-root part), and FND-INV-05/06/08 (tests/foundation_verification.rs): completing all 10 required automated verification cases FND-T01..T10.
  • Foundation Milestone Exit Gate (Gate G3 / 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

  1. ./scripts/check.sh (Rust 1.99.1 — fmt, workspace clippy --all-targets -D warnings, headless cargo test --workspace, rustdoc -D warnings, --features wayland clippy/test/doc, --features vulkan clippy/test/doc, cargo deny check):

    advisories ok, bans ok, licenses ok, sources ok
    All mandatory checks ran and passed.
    

    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, platform FND-T10, Phase 2b relative motion & cursor constraint lifecycle).
    • spawn-input: 12 unit + 15 verification (FND-T03, FND-T04, Phase 2b PointerRelativeMotion wiring, deterministic replay) + 1 doctest (28 passed).
    • spawn-render: 37 headless unit tests (FND-T06, FND-T07, presentation controller & VkFailure classification) + 4 opt-in GPU tests ignored by default.
    • spawn-engine: 5 unit (EngineError formatting/cause-chain & RuntimeOptions validation) + 4 verification (FND-T08, FND-T09, FND-T10, FND-INV-06) (9 passed).
  2. Opt-in Vulkan GPU tests with Khronos validation + synchronization validation (RX 460 / RADV):

    $ VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true cargo test -p spawn-render --features vulkan -- --ignored
    running 4 tests
    test vulkan::gpu_tests::presents_repeated_clear_frames ... ok
    test vulkan::gpu_tests::resize_suspend_and_resume ... ok
    test vulkan::gpu_tests::presents_across_present_mode_preferences ... ok
    test vulkan::gpu_tests::starts_suspended_at_zero_size_and_repeated_create_drop_is_clean ... ok
    test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 37 filtered out
    

Platforms tested

Tested on the reference machine: Omarchy 4.0.6 (Arch-based), Linux 7.2.15-1-omarchy, Hyprland 0.56.2 (Wayland native, xwayland: 0), AMD Radeon RX 460 (RADV POLARIS11, Mesa 26.2.5-arch1.1, Vulkan 1.4.354 device, loader 1.4.363), with VK_LAYER_KHRONOS_validation 1.4.363 + synchronization validation active (VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true):

  1. Cursor-lock + auto-close smoke (SPAWN_SMOKE_SECONDS=2 SPAWN_SMOKE_GRAB=locked cargo run): mapped 924x512 → 916x504, cursor_grab=Locked → midpoint release cursor_grab=None, ticks=119, presented=107, suspended=0, skipped=0, 0 validation errors, exit 0.
  2. Compositor resize + native close smoke (cargo run + hyprctl eval): floating toggle (916x504 → 934x522), exact pixel resize (720x480), special-workspace transitions (308x504 → 2530x1024 → 616x1024), and compositor xdg_toplevel.close (hl.dispatch(hl.dsp.window.close('pid:…'))) delivered CloseRequested and exited cleanly (CloseRequested, ticks=80, presented=82, suspended=0, skipped=0, 0 validation errors, exit 0, no lingering process).
  3. Structured failure diagnostics (zero panics):
    • WAYLAND_DISPLAY=/nonexistent cargo run → error[ENGN-0004] / PLAT-0001 (exit 1).
    • VK_DRIVER_FILES=/nonexistent cargo run → error[ENGN-0005] / REND-0001 (exit 1).
    • SPAWN_SMOKE_SECONDS=notanumber cargo run → error[ENGN-0001] (exit 1).

Invariants touched

  • No invariant weakened or modified.
  • Verified/satisfied: 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

  • Untested / unimplemented platforms (PLANNED): X11 (PLAT-0001 / REND-0002) and Windows (Win32 window/surface backend; non-Linux targets build and pass headless tests cleanly and return ENGN-0002 at runtime). Windows support is neither tested nor claimed (SPN-INV-090).
  • Interactive / compositor edge cases not exercised in a live window: interactive mouse-drag resize, DPI scale > 1, physical GPU device loss, compositors other than Hyprland, and live-window Occluded / zero-size suspension (Hyprland 0.56.2 did not emit xdg_toplevel suspended on silent special-workspace moves; zero-size suspension and surface-loss/out-of-date recovery are verified by headless FND-T06, FND-T07, FND-INV-06, and GPU headless-surface tests).
  • Input & engine scope: keyboard and mouse input only (gamepads, touch, RON mapping persistence, and network wire codecs 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).

- 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
brasga-a changed the base branch from feat/foundation-fixes-and-input to master November 18, 2026 19:39
@brasga-a
brasga-a merged commit b8792ae into master Nov 18, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant