Repository navigation
docs(first-3d): add Milestone 2 specification, design, invariants, verification, and plan - #9
Merged
Merged
Conversation
…rification, and plan
…and spawn-cli AGENTS note
…een TRANSFER_SRC readback
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.
Milestone 2 (
PLANNED) planning and specification suite (docs/first-3d/*+docs/README.md) for Spawn's initial 3D rendering, offline Slang shader cooking, spatial math, and 60 Hzf64free-fly camera slice.Summary of changes
1. Milestone 2 specification suite (
docs/first-3d/)docs/first-3d/README.md:PLANNEDmilestone overview, per-package ownership table (spawn-math,spawn-core,spawn-platform,spawn-input,spawn-cli,spawn-render,spawn-engine), downward dependency summary, and reading order.docs/first-3d/SPEC.md:F3D-FR-01..12and non-functional requirementsF3D-NFR-01..07with observable acceptance criteria and 1-to-1 verification hooks.ADR-0014review + upstream SlangApache-2.0 WITH LLVM-exceptionlicense sign-off indocs/DEPENDENCIES.md, pinnedslangcversion, and Gate G2 notices for unapproved crates such asserde_json,tempfile, andblake3inspawn-cli), and Definition of Done.docs/first-3d/DESIGN.md:spawn-render -> spawn-mathandspawn-engine -> spawn-math; optional headlessspawn-cli -> spawn-renderwithdefault-features = falseand Phase 2tools/spawn-cli/AGENTS.mdrefinement note).ADR-0010spatial math design: right-handed, Y-up, −Z forward, column-major (M * v), radians in Rust / unit-explicit degrees at external boundaries, distinctf64world-position types with explicit CPU camera-relativef32conversion, finite/infinite reversed-Z projections (near → 1.0,far → 0.0), single-site Vulkan Y-flip inspawn-math's projection matrix (preserving positive Vulkan signed areaa > 0→VK_FRONT_FACE_COUNTER_CLOCKWISE), andlibm-backed deterministicf32/f64subset.ADR-0014(Accepted) offlinespawn-cliSlang-to-SPIR-V + reflection cook (clap,rspirv, injectable compiler runner seam, zerobuild.rscompiler calls, uncommitted.spvoutputs) and untrusted binary/reflection validation in headlessspawn-render(#![deny(clippy::indexing_slicing)],REND-0010+).ADR-0004Vulkan 1.3 RHI slice:selection.rsD32_SFLOATdepth & push-constant checks, in-house GPU block suballocator (DEVICE_LOCAL+HOST_VISIBLEstaging/readback) with timeline-semaphore retirement and leak checks, swapchain-matchedD32_SFLOATreversed-Z depth across resize/0x0suspend, anddynamicRenderinggraphics pipelines.f64FreeCamerasimulation vs. read-onlyalpha(pending() / tick_duration()) presentation interpolation and procedural 3D test scene inspawn-engine(SPN-INV-043,ENGN-0008+).docs/first-3d/INVARIANTS.md:F3D-INV-01..16mapped toSPN-INV-001..006,009,011,023,030..034,040..044,050..054,083..084,090..092,100..101, andFND-INV-05, plus failure policy and change control.docs/first-3d/VERIFICATION.md: Automated headless checks (F3D-T01..T10,F3D-T13), Gate G2 parser fuzzing, opt-in Vulkan 1.3 GPU offscreen (COLOR_ATTACHMENT | TRANSFER_SRC) pixel-readback + headless-surface swapchain (COLOR_ATTACHMENTonly) checks (F3D-T11triangle,F3D-T12far-after-near reversed-Z 3D occlusion +±50 km+ resize/0x0suspend), withF3D-T05separating non-dropping cadence equivalence from backlog-drop clamping, reference-hardware manual smoke checklist, 1-to-1 traceability matrix, and Gate G3 exit criteria.docs/first-3d/PLAN.md: Ordered Phases0..6(Phase 0ADR-0014& Slang license sign-off gating Phase 2), implementation guardrails, error-code continuity (REND-0010+,ENGN-0008+), and deferred follow-up.2. Documentation index (
docs/README.md)Start heretable,Documentation hierarchy, andScope at this stageto indexdocs/first-3d/accurately asPLANNEDalongside theEXISTSdocs/foundation/slice.Requirements covered
F3D-FR-01..12,F3D-NFR-01..07, invariantsF3D-INV-01..16, verification suiteF3D-T01..T13, and delivery Phases0..6(PLANNED; no Milestone 2 runtime implementation is claimed).Tests run
./scripts/check.sh(Gate G0): exit0(cargo fmt --all --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace— 142 passed, 0 failed, 4 ignored GPU tests,RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps,spawn-platform --features waylandclippy/test/doc,spawn-render --features vulkanclippy/test/doc, andcargo deny check).#anchor, and ID bijection audit acrossdocs/andAGENTS.md:129/129relative links and#anchorsresolved on disk;0mismatches across bidirectionalF3D-FR-*/F3D-NFR-*/F3D-INV-*/F3D-T*tables.Platforms tested
7.2.15-1-omarchy, x86_64). No GPU or windowing code was modified in this change (GPU/window behavior affected: N/A — documentation only).Invariants touched
SPN-INV-084(build.rsnever invokes external compilers such asslangc) from proposed to binding upon owner acceptance ofADR-0014(SPN-INV-101). No invariant weakened.PLANNEDMilestone 2 invariantsF3D-INV-01..16aligned withSPN-INV-001..006,009,011,023,030..034,040..044,050..054,083..084,090..092,100..101.Known limitations
docs/first-3d/arePLANNED; zero Milestone 2 Rust implementation exists yet (SPN-INV-100).ADR-0014and Slang'sApache-2.0 WITH LLVM-exceptionlicense are accepted and synchronized; before live shader cooks in Phase 2, install and pin the exactslangccompiler version on developer/CI shader-build machines.ADR-0020(memory strategy/budgets) andADR-0022(repository layout) remainProposed.