Skip to content

docs(first-3d): add Milestone 2 specification, design, invariants, verification, and plan - #9

Merged
brasga-a merged 4 commits into
masterfrom
docs/milestone-2-first-3d
Nov 18, 2026
Merged

brasga-a merged 4 commits into
masterfrom
docs/milestone-2-first-3d

Conversation

@brasga-a

@brasga-a brasga-a commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

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 Hz f64 free-fly camera slice.

Stacked on #8 (feat/foundation-complete, 828fd16; not merged), which stacks on #7 (feat/foundation-fixes-and-input) → #6 (feat/render-vulkan-clear) → #5 (feat/platform-wayland) → master. Merge #5, #6, #7, and #8 in order first, then retarget this PR to master.

Documentation-only PR: Zero Rust source files, Cargo.toml manifests, or existing ADR statuses are modified. Proposed ADRs (ADR-0014, ADR-0020, ADR-0022) remain Proposed, with dependent Milestone 2 elements explicitly marked proposal (pending Phase 0 owner acceptance).

Summary of changes

1. Milestone 2 specification suite (docs/first-3d/)

  • docs/first-3d/README.md: PLANNED milestone 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:
    • Functional requirements F3D-FR-01..12 and non-functional requirements F3D-NFR-01..07 with observable acceptance criteria and 1-to-1 verification hooks.
    • Explicit out-of-scope boundaries, Phase 0 blockers (Proposed ADR-0014 review + upstream Slang Apache-2.0 WITH LLVM-exception license sign-off in docs/DEPENDENCIES.md, pinned slangc version, and Gate G2 notices for unapproved crates such as serde_json, tempfile, and blake3 in spawn-cli), and Definition of Done.
  • docs/first-3d/DESIGN.md:
    • Crate dependency and third-party crate boundary matrix (spawn-render -> spawn-math and spawn-engine -> spawn-math; optional headless spawn-cli -> spawn-render with default-features = false and Phase 2 tools/spawn-cli/AGENTS.md refinement note).
    • ADR-0010 spatial math design: right-handed, Y-up, −Z forward, column-major (M * v), radians in Rust / unit-explicit degrees at external boundaries, distinct f64 world-position types with explicit CPU camera-relative f32 conversion, finite/infinite reversed-Z projections (near → 1.0, far → 0.0), single-site Vulkan Y-flip in spawn-math's projection matrix (preserving positive Vulkan signed area a > 0 → VK_FRONT_FACE_COUNTER_CLOCKWISE), and libm-backed deterministic f32/f64 subset.
    • ADR-0014 (Accepted) offline spawn-cli Slang-to-SPIR-V + reflection cook (clap, rspirv, injectable compiler runner seam, zero build.rs compiler calls, uncommitted .spv outputs) and untrusted binary/reflection validation in headless spawn-render (#![deny(clippy::indexing_slicing)], REND-0010+).
    • ADR-0004 Vulkan 1.3 RHI slice: selection.rs D32_SFLOAT depth & push-constant checks, in-house GPU block suballocator (DEVICE_LOCAL + HOST_VISIBLE staging/readback) with timeline-semaphore retirement and leak checks, swapchain-matched D32_SFLOAT reversed-Z depth across resize/0x0 suspend, and dynamicRendering graphics pipelines.
    • Genre-free 60 Hz f64 FreeCamera simulation vs. read-only alpha (pending() / tick_duration()) presentation interpolation and procedural 3D test scene in spawn-engine (SPN-INV-043, ENGN-0008+).
  • docs/first-3d/INVARIANTS.md: F3D-INV-01..16 mapped to SPN-INV-001..006, 009, 011, 023, 030..034, 040..044, 050..054, 083..084, 090..092, 100..101, and FND-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_ATTACHMENT only) checks (F3D-T11 triangle, F3D-T12 far-after-near reversed-Z 3D occlusion + ±50 km + resize/0x0 suspend), with F3D-T05 separating 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 Phases 0..6 (Phase 0 ADR-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)

  • Updated status summary, Start here table, Documentation hierarchy, and Scope at this stage to index docs/first-3d/ accurately as PLANNED alongside the EXISTS docs/foundation/ slice.

Requirements covered

  • Defines Milestone 2 specification F3D-FR-01..12, F3D-NFR-01..07, invariants F3D-INV-01..16, verification suite F3D-T01..T13, and delivery Phases 0..6 (PLANNED; no Milestone 2 runtime implementation is claimed).

Tests run

  • ./scripts/check.sh (Gate G0): exit 0 (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 wayland clippy/test/doc, spawn-render --features vulkan clippy/test/doc, and cargo deny check).
  • Automated Markdown link, #anchor, and ID bijection audit across docs/ and AGENTS.md: 129/129 relative links and #anchors resolved on disk; 0 mismatches across bidirectional F3D-FR-* / F3D-NFR-* / F3D-INV-* / F3D-T* tables.

Platforms tested

  • Documentation and workspace Gate G0 checks executed on Linux (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

  • Promotes SPN-INV-084 (build.rs never invokes external compilers such as slangc) from proposed to binding upon owner acceptance of ADR-0014 (SPN-INV-101). No invariant weakened.
  • Defines PLANNED Milestone 2 invariants F3D-INV-01..16 aligned with SPN-INV-001..006, 009, 011, 023, 030..034, 040..044, 050..054, 083..084, 090..092, 100..101.

Known limitations

  • All Milestone 2 capabilities in docs/first-3d/ are PLANNED; zero Milestone 2 Rust implementation exists yet (SPN-INV-100).
  • ADR-0014 and Slang's Apache-2.0 WITH LLVM-exception license are accepted and synchronized; before live shader cooks in Phase 2, install and pin the exact slangc compiler version on developer/CI shader-build machines.
  • ADR-0020 (memory strategy/budgets) and ADR-0022 (repository layout) remain Proposed.

@brasga-a
brasga-a changed the base branch from feat/foundation-complete to master November 18, 2026 19:39
@brasga-a
brasga-a merged commit a035f97 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