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:

```text
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 a non-three-scale imported multiscale preset;
- 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;
- source provenance and optional original row;
- 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 — Schema-backed legacy conversion

Consume Macrostep 00's frozen JSONL evidence and migration-default table to generate final versioned presets:

- 15-column base rows;
- groups of three multiscale rows;
- 11-column sphere/DT rows.

The converter must report accepted/rejected entries, apply every absent-field default explicitly, preserve source rows/descriptions/numeric precision, and deduplicate only by a documented normalized key. A direct legacy-text parser may exist as a separately tested maintenance command, but generation and normal runtime loading use the committed evidence, not the external tree. Verify expected source counts, multiscale grouping, generated counts, and a manifest hash.

### Substep 1.3.3 — Command-line contract

Support at least:

```text
--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, preset library, importer, and CLI.
- Deterministic run descriptor, finalized 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.