smoothlife/plans/01_project_foundation_and_configuration.md

Macrostep 01 — Project foundation and configuration

Objective

Turn the empty Rust binary into a maintainable, headless-capable library plus raylib application shell. Establish schema, validation, error handling, assets, deterministic run identity, and CI before implementing simulation behavior.

Dependencies

Macrostep 00 complete.

Phase 1.1 — Establish package and feature boundaries

Substep 1.1.1 — Cargo features

Keep one package initially. Define:

default = [app, gpu]
app     = raylib application, UI, and renderers
gpu     = app + low-level OpenGL/rlgl acceleration
tools   = optional analysis executables

src/lib.rs must compile with no raylib imports under cargo test --no-default-features. src/main.rs is a thin executable boundary.

Substep 1.1.2 — Evaluate and pin dependencies

Select current mutually compatible releases and commit Cargo.lock:

• raylib for context/window/input/drawing;
• serde and toml for schema;
• clap for startup/headless options;
• thiserror in the library and optionally anyhow in binaries;
• tracing plus a subscriber;
• rand_chacha and rand_core for deterministic initialization;
• rustfft/complex support for later convolution;
• optional rayon for CPU parallelism;
• directories for user data locations;
• development: approx, proptest, criterion, and a snapshot tool only if fixtures remain reviewable.

Do not add a dependency when a small, tested local type is clearer.

Substep 1.1.3 — Module skeleton

Create the module boundaries listed in plans/README.md. Keep gpu, app, render, and ui behind features. Add module-level documentation describing ownership and forbidden dependencies.

Phase 1.2 — Define the versioned configuration schema

Substep 1.2.1 — Typed model schema

Create string-backed enums and structs for:

• VariantConfig::{Planar,Multiscale,Sphere,DelayedTime};
• RuleConfig and all curve/construction enums;
• Dynamics::{Discrete,Growth,Relaxation};
• Integrator::{Euler,AdamsBashforth3,RungeKutta4};
• Rk4RelaxationReference::{StageState,StepOrigin};
• FftAlgorithm::{Standard,LegacyPackedUnitary};
• SphereModel::{Corrected,Legacy};
• shapes, resolution, initializer, seed, and optional recommended presentation.

There is no general compatibility profile. Use a tagged time-evolution schema so Rk4RelaxationReference exists only in the Relaxation + RungeKutta4 branch; it is structurally absent for every other dynamics/integrator combination. Place FftAlgorithm only in planar/multiscale GPU compute configuration and SphereModel only in sphere configuration.

Use schema_version = 1. Keep model settings separate from app preferences.

Substep 1.2.2 — Validation

Validation returns field-specific, actionable errors and rejects:

• NaN/infinity;
• nonpositive radius, radius ratios, transition widths, smoothing widths, or timestep;
• invalid/zero shape extents;
• unsupported dynamics/integrator combinations (the tagged schema makes an irrelevant RK4 reference unrepresentable);
• statically invalid LegacyPackedUnitary combinations such as CPU backend, non-power-of-two shape, or unsupported dimension;
• empty scales or any multiscale configuration whose scale count is not three;
• impossible history depth or sphere face size.

Split validation into two stages. Macrostep 01 performs schema/static validation without a graphics context. Macrostep 05 adds runtime capability validation for texture limits, float FBOs, resource counts, memory, and actual legacy-FFT support; loading may be statically valid yet fail a requested GPU construction with an actionable runtime error.

Do not reject reversed birth/death intervals: legacy catalogues contain them and the exact window formula defines their behavior. Emit warnings for risky but defined conditions such as radius near half the periodic extent or nonnested chained scales.

Substep 1.2.3 — Stable identity and provenance

Every preset has:

• stable slug/UUID;
• display name and description;
• variant and schema version;
• authoring provenance and optional links to relevant model-contract or legacy-source-map entries;
• tags;
• deterministic default seed;
• relevant localized historical-option values;
• recommended shape/backend/presentation.

Define a normalized run descriptor suitable for logs, state exports, and bug reports.

Phase 1.3 — Preset library and persistence

Substep 1.3.1 — Bundled and user locations

• Embed or package bundled presets independently of the working directory.
• Load user presets from the platform configuration directory.
• Never mutate bundled files.
• Save settings atomically through temp-file + rename.
• Preserve unknown newer schema versions by refusing destructive writes.

Substep 1.3.2 — Newly authored bundled presets

Author bundled product presets directly in the versioned schema using Macrostep 00's deterministic preset baselines. There is no legacy-row converter, migration-default layer, catalogue deduplication, or required correspondence to legacy source counts or groupings.

Require every bundled preset to specify all run-defining fields, a stable unique identity, authoring provenance, deterministic seed/initializer, applicable localized historical options, and recommended presentation. Validate and round-trip each preset independently, reject duplicate IDs, verify deterministic reproduction from its run descriptor, and record a manifest hash for the authored set.

Substep 1.3.3 — Command-line contract

Support at least:

--preset <id>
--config <path>
--variant <name>
--backend <auto|cpu|gpu>
--fft <standard|legacy-packed-unitary>
--rk4-relaxation <stage-state|step-origin>
--sphere-model <corrected|legacy>
--seed <u64>
--shape <...>
--steps <n>
--headless
--export-state <path>
--list-presets
--validate-config

CLI overrides apply after preset validation and produce a new validated run descriptor.

Phase 1.4 — Error, logging, and asset policy

Substep 1.4.1 — Errors

Define nonpanicking library errors for config, allocation, backend capability, shader compilation, state import, and numerical validation. The app converts them into a visible error panel/toast and a structured log.

Substep 1.4.2 — Logging

Log application version, OS, selected preset, seed, shape, backend, FFT algorithm, RK4 relaxation reference when relevant, sphere model when relevant, and later GPU capabilities. Avoid per-frame logs. A user must be able to copy a compact diagnostic report.

Substep 1.4.3 — Resource lookup

Essential shaders should be embedded with include_str! or packaged under a compile-time-known resource root. Development overrides are optional and explicit. No normal launch path assumes the repository is the current directory.

Phase 1.5 — Quality baseline

• Add rustfmt and strict project-appropriate Clippy settings.
• Unit-test schema defaults, every enum, validation paths, round trips, atomic writes, and CLI precedence.
• Add CI jobs for formatting, Clippy, headless tests, and application compilation.
• Record the supported Rust toolchain policy; current project toolchain is Rust 1.97 with edition 2024.

Deliverables

• Headless library skeleton and feature-gated app skeleton.
• Versioned schema, validator, newly authored preset library, and CLI.
• Deterministic run descriptor, finalized newly authored preset catalogue, and structured errors/logging.
• CI quality baseline.

Exit gate

• cargo test --no-default-features passes without initializing raylib.
• cargo test --all-features and application build pass.
• Every bundled preset validates and round-trips without numeric drift.
• Invalid fields identify their exact path and reason.
• Launch and preset listing work from outside the repository directory.
• The legacy tree is not accessed at runtime.