Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Integration layer: `mlua` with the `luau` feature (`PLANNED`; not a dependency).

## Workspace

Root `Cargo.toml` (verified): `resolver = "3"`, members `.`, `crates/*`, `tools/*` (excluding the standalone Gate G2 fuzz workspace `crates/spawn-render/fuzz`); `[workspace.package]` provides `version`, `edition` (2024), `license` (MIT) and `rust-version` (1.99.1), inherited by every member; `[workspace.lints]` (ADR-0007) is inherited by every member through `[lints] workspace = true`; dev profile uses `opt-level = 1` (dependencies `opt-level = 3`). `[workspace.dependencies]` pins `libm` (pure-Rust deterministic transcendentals in `spawn-math`, `default-features = false`), `ash` (used by `spawn-render` behind its optional `vulkan` feature), `raw-window-handle` (both crates' optional backend features), `rustix`, `wayland-client`, `wayland-protocols` (`spawn-platform`'s optional `wayland` feature), `clap` and `rspirv` (used by the offline tool `spawn-cli`), and test/oracle crates `arbitrary`, `glam`, `insta`, and `proptest`; with default features **every engine library crate except `spawn-math` (which links only pure-Rust `libm`) has zero third-party normal dependencies**. The inter-crate edges are `spawn-input` depending on `spawn-core` and `spawn-platform` (both with `default-features = false`, so no native windowing backend is linked; ADR-0002, FND-T09), `spawn-cli` depending on `spawn-render` (`default-features = false`, sharing the headless cooked-shader binary contract without linking Vulkan; ADR-0014), and the root composition package `spawn-engine` depending on `spawn-core`, `spawn-input`, `spawn-platform` and `spawn-render` (`default-features = false` globally, plus `spawn-platform/wayland` and `spawn-render/vulkan` on `cfg(target_os = "linux")`); no library crate in `crates/` depends on `spawn-engine` or `tools/`, and all other inter-crate edges in nested documents are `PLANNED`.
Root `Cargo.toml` (verified): `resolver = "3"`, members `.`, `crates/*`, `tools/*` (excluding the standalone Gate G2 fuzz workspace `crates/spawn-render/fuzz`); `[workspace.package]` provides `version`, `edition` (2024), `license` (MIT) and `rust-version` (1.99.1), inherited by every member; `[workspace.lints]` (ADR-0007) is inherited by every member through `[lints] workspace = true`; dev profile uses `opt-level = 1` (dependencies `opt-level = 3`). `[workspace.dependencies]` pins `libm` (pure-Rust deterministic transcendentals in `spawn-math`, `default-features = false`), `ash` and `bytemuck` (used by `spawn-render` behind its optional `vulkan` feature), `raw-window-handle` (both crates' optional backend features), `rustix`, `wayland-client`, `wayland-protocols` (`spawn-platform`'s optional `wayland` feature), `clap` and `rspirv` (used by the offline tool `spawn-cli`), and test/oracle crates `arbitrary`, `glam`, `insta`, and `proptest`; with default features **every engine library crate has zero window/GPU or C/FFI normal dependencies (only `spawn-math`, directly and via `spawn-render`, links pure-Rust `libm`)**. The inter-crate edges are `spawn-render` depending on `spawn-math` (`default-features = false`; ADR-0004, ADR-0010), `spawn-input` depending on `spawn-core` and `spawn-platform` (both with `default-features = false`, so no native windowing backend is linked; ADR-0002, FND-T09), `spawn-cli` depending on `spawn-render` (`default-features = false`, sharing the headless cooked-shader binary contract without linking Vulkan; ADR-0014), and the root composition package `spawn-engine` depending on `spawn-core`, `spawn-input`, `spawn-platform` and `spawn-render` (`default-features = false` globally, plus `spawn-platform/wayland` and `spawn-render/vulkan` on `cfg(target_os = "linux")`); no library crate in `crates/` depends on `spawn-engine` or `tools/`, and all other inter-crate edges in nested documents are `PLANNED`.

Conventions:
- One crate per subsystem with a narrow public API; names `spawn-<subsystem>`.
Expand All @@ -89,7 +89,7 @@ Intended layering (`PLANNED`, non-binding until code exists): foundations (math,
| [spawn-reflect](crates/spawn-reflect/AGENTS.md) | Runtime type metadata for serialization, editor, script exposure | SCAFFOLD |
| [spawn-platform](crates/spawn-platform/AGENTS.md) | OS integration: windows, system events, surfaces | EXISTS (raw events, relative motion, cursor constraints; Wayland backend); X11, Win32 PLANNED |
| [spawn-input](crates/spawn-input/AGENTS.md) | Input devices, state, actions, mappings | EXISTS (keyboard/mouse state, semantic mappings, tick sampling); gamepads, touch, persistence PLANNED |
| [spawn-render](crates/spawn-render/AGENTS.md) | GPU abstraction, resources, shaders, materials, frame execution | EXISTS (Vulkan clear & `dynamicRendering` triangle, in-house GPU block allocator, `D32_SFLOAT` reversed-Z depth, cooked-shader validator, offscreen readback); rest PLANNED |
| [spawn-render](crates/spawn-render/AGENTS.md) | GPU abstraction, resources, shaders, materials, frame execution | EXISTS (Vulkan clear, `dynamicRendering` triangle & 3D indexed meshes, GPU block allocator + staging, `D32_SFLOAT` reversed-Z depth, camera-relative draws, cooked-shader validator, offscreen readback); rest PLANNED |
| [spawn-physics](crates/spawn-physics/AGENTS.md) | Rigid-body simulation, collision, spatial queries | SCAFFOLD |
| [spawn-animation](crates/spawn-animation/AGENTS.md) | Skeletal/property animation runtime, blending, state machines | SCAFFOLD |
| [spawn-audio](crates/spawn-audio/AGENTS.md) | Audio playback, mixing, spatialization | SCAFFOLD |
Expand All @@ -102,7 +102,7 @@ Intended layering (`PLANNED`, non-binding until code exists): foundations (math,
| [spawn-editor](tools/spawn-editor/AGENTS.md) | Graphical authoring tools | SCAFFOLD |
| [spawn-mcp](tools/spawn-mcp/AGENTS.md) | MCP server for external AI agents/tools | SCAFFOLD |

Verified state: `spawn-core` contains the fixed-step clock (`FixedStepClock`, `FixedStepConfig`, `FixedStepUpdate`, `Tick`, `ClockError`) with unit, verification (FND-T01, FND-T02) and doc tests; `spawn-math` contains `#![forbid(unsafe_code)]` local `f32` primitives (`Vec2/3/4`, column-major `Mat3/4`, `Quat`, `Transform`, `Aabb`, `Ray`, `Plane`, `Sphere`), distinct `f64` world coordinates (`WorldPos`, `DVec3`, `camera_relative_f32`), reversed-Z Vulkan projections with single-site NDC Y-flip, pure-Rust `libm` deterministic subset `det`, and `MathError` (`MATH-0001`..`MATH-0005`) with headless unit, `proptest`, `glam` oracle, golden-bit, snapshot, and hygiene tests (F3D-T01..T04, Phase 1 F3D-T13); `spawn-platform` contains the raw event types (including `PointerRelativeMotion` and `CursorGrabChanged`), `CursorGrabMode`, `WindowDescriptor` and `PlatformError` (always compiled) and, behind the `wayland` feature, the Wayland backend (`Platform`, `Window`, `PumpMode`, `zwp_relative_pointer_v1`, `zwp_pointer_constraints_v1`) with headless translation tests (FND-T05, FND-T10 platform part, Phase 2b relative motion and cursor constraint lifecycle) and a manual smoke example; `spawn-input` contains allocation-free keyboard/mouse `DeviceState`, data-driven `InputMap` (`ActionId`, `AxisId`, `ContextId`, `AxisConfig`), tick-indexed `InputCommand` sampling and untrusted-command validation (`InputState`, `InputError`, `#![forbid(unsafe_code)]`) with headless unit, verification (FND-T03, FND-T04, Phase 2b relative-motion wiring, replay determinism) and doc tests; `spawn-render` contains `#![forbid(unsafe_code)]` public types, generational handles (`ShaderHandle`, `PipelineHandle`, `OffscreenTargetHandle`), `RenderError` (`REND-0001..0014`), the versioned cooked-shader binary codec and untrusted SPIR-V/reflection layout validator (`CookedShader`, `PipelineLayoutDesc`, `#![deny(clippy::indexing_slicing)]`, F3D-T07 + Gate G2 fuzz target), the pure GPU block suballocator and timeline-retirement tracker (`PureGpuAllocator`, `GpuMemoryBudget`, `GpuAllocatorStats`, F3D-T08), the pure presentation, `D32_SFLOAT` reversed-Z depth-lifecycle, and device-selection controllers (always compiled, FND-T06/T07, F3D-T09) and, behind the `vulkan` feature, `Renderer` over a private Vulkan 1.3 RHI (`dynamicRendering` triangle pipelines, `D32_SFLOAT` depth, offscreen `R8G8B8A8_UNORM` readback, Wayland + headless surfaces) verified clean under `VK_LAYER_KHRONOS_validation` + synchronization validation with opt-in GPU tests (F3D-T11), Phase 3 hygiene checks (F3D-T13), and the `vulkan_clear` / `vulkan_triangle` smoke examples; `spawn-cli` (`[[bin]] name = "spawn"`, `#![forbid(unsafe_code)]`) implements `spawn shaders build` over pinned `slangc` `2026.22` (`SLANGC_VERSION`, `SlangCompiler` seam, `rspirv` reflection extraction, `CLI-0001..0006`, F3D-T06 + F3D-T13 shader-toolchain checks) with authored `shaders/{triangle,mesh_3d}.slang`; the root `spawn-engine` package (`src/`, `tests/foundation_verification.rs`) composes all four foundation subsystems (`EngineError`, `RuntimeOptions`, `run_session`, `run_native`, `#![forbid(unsafe_code)]`) with headless verification tests (FND-T08, FND-T09, FND-T10, FND-INV-06) and recorded Wayland/Vulkan smoke runs; every other `lib.rs` contains only a crate-level doc comment (no items, no tests).
Verified state: `spawn-core` contains the fixed-step clock (`FixedStepClock`, `FixedStepConfig`, `FixedStepUpdate`, `Tick`, `ClockError`) with unit, verification (FND-T01, FND-T02) and doc tests; `spawn-math` contains `#![forbid(unsafe_code)]` local `f32` primitives (`Vec2/3/4`, column-major `Mat3/4`, `Quat`, `Transform`, `Aabb`, `Ray`, `Plane`, `Sphere`), distinct `f64` world coordinates (`WorldPos`, `DVec3`, `camera_relative_f32`), reversed-Z Vulkan projections with single-site NDC Y-flip, pure-Rust `libm` deterministic subset `det`, and `MathError` (`MATH-0001`..`MATH-0005`) with headless unit, `proptest`, `glam` oracle, golden-bit, snapshot, and hygiene tests (F3D-T01..T04, Phase 1 F3D-T13); `spawn-platform` contains the raw event types (including `PointerRelativeMotion` and `CursorGrabChanged`), `CursorGrabMode`, `WindowDescriptor` and `PlatformError` (always compiled) and, behind the `wayland` feature, the Wayland backend (`Platform`, `Window`, `PumpMode`, `zwp_relative_pointer_v1`, `zwp_pointer_constraints_v1`) with headless translation tests (FND-T05, FND-T10 platform part, Phase 2b relative motion and cursor constraint lifecycle) and a manual smoke example; `spawn-input` contains allocation-free keyboard/mouse `DeviceState`, data-driven `InputMap` (`ActionId`, `AxisId`, `ContextId`, `AxisConfig`), tick-indexed `InputCommand` sampling and untrusted-command validation (`InputState`, `InputError`, `#![forbid(unsafe_code)]`) with headless unit, verification (FND-T03, FND-T04, Phase 2b relative-motion wiring, replay determinism) and doc tests; `spawn-render` contains `#![forbid(unsafe_code)]` public types, generational handles (`ShaderHandle`, `PipelineHandle`, `OffscreenTargetHandle`, `MeshHandle`), `RenderError` (`REND-0001..0014`), the versioned cooked-shader binary codec and untrusted SPIR-V/reflection layout validator (`CookedShader`, `PipelineLayoutDesc`, `#![deny(clippy::indexing_slicing)]`, F3D-T07 + Gate G2 fuzz target), 3D mesh descriptors and camera-relative `128`-byte push-constant packing (`MeshVertex`, `MeshDescriptor`, `CameraRelativeView`, `MeshDraw`, `PackedMeshPushConstants`), the pure GPU block suballocator and timeline-retirement tracker (`PureGpuAllocator`, `GpuMemoryBudget`, `GpuAllocatorStats`, F3D-T08), the pure presentation, `D32_SFLOAT` reversed-Z depth-lifecycle, and device-selection controllers (always compiled, FND-T06/T07, F3D-T09) and, behind the `vulkan` feature, `Renderer` over a private Vulkan 1.3 RHI (`dynamicRendering` triangle & 3D indexed mesh pipelines, `vkCmdCopyBuffer2` staging uploads, `D32_SFLOAT` depth, offscreen `R8G8B8A8_UNORM` readback, Wayland + headless surfaces) verified clean under `VK_LAYER_KHRONOS_validation` + synchronization validation with opt-in GPU tests (F3D-T11, F3D-T12), Phase 3/4 hygiene checks (F3D-T13), and the `vulkan_clear` / `vulkan_triangle` smoke examples; `spawn-cli` (`[[bin]] name = "spawn"`, `#![forbid(unsafe_code)]`) implements `spawn shaders build` over pinned `slangc` `2026.22` (`SLANGC_VERSION`, `SlangCompiler` seam, `rspirv` reflection extraction, `CLI-0001..0006`, F3D-T06 + F3D-T13 shader-toolchain checks) with authored `shaders/{triangle,mesh_3d}.slang`; the root `spawn-engine` package (`src/`, `tests/foundation_verification.rs`) composes all four foundation subsystems (`EngineError`, `RuntimeOptions`, `run_session`, `run_native`, `#![forbid(unsafe_code)]`) with headless verification tests (FND-T08, FND-T09, FND-T10, FND-INV-06) and recorded Wayland/Vulkan smoke runs; every other `lib.rs` contains only a crate-level doc comment (no items, no tests).

Ownership rule: each piece of state has exactly one owning system; others use its API. If a responsibility seems to fit two crates, stop and report rather than duplicate it.

Expand Down
33 changes: 33 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ rust-version = "1.99.1"
[workspace.dependencies]
arbitrary = { version = "1.5.0", default-features = false }
ash = { version = "0.38.0", default-features = false }
bytemuck = { version = "1.25.2", default-features = false }
clap = { version = "4.6.8", default-features = false }
glam = { version = "0.34.3", default-features = false }
insta = { version = "1.49.0", default-features = false }
Expand Down
15 changes: 14 additions & 1 deletion crates/spawn-math/tests/f3d_t13_math_hygiene.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,27 @@ fn f3d_t13_spawn_math_dependency_tree_public_api_safety_and_doc_sync()
// (zero `spawn-*` deps per SPN-INV-004, zero OS/GPU/test deps per SPN-INV-009/023).
let tree_out = Command::new(env!("CARGO"))
.current_dir(workspace_root)
.args(["tree", "-p", "spawn-math", "-e", "normal"])
.env("CARGO_TERM_COLOR", "never")
.args([
"tree",
"--color",
"never",
"-p",
"spawn-math",
"-e",
"normal",
])
.output()?;
assert!(
tree_out.status.success(),
"cargo tree failed: {}",
String::from_utf8_lossy(&tree_out.stderr)
);
let tree = String::from_utf8(tree_out.stdout)?;
assert!(
!tree.contains('\x1b'),
"cargo tree emitted unexpected ANSI escape sequences:\n{tree}"
);
let lines: Vec<&str> = tree.lines().collect();
assert_eq!(
lines.len(),
Expand Down
Loading
Loading