Freeze SmoothLife model contract and fixtures

This commit is contained in:
2026-07-14 18:26:55 +02:00
parent 51cff7b0f3
commit d587f542eb
25 changed files with 30612 additions and 38 deletions

View File

@@ -13,7 +13,6 @@ None.
- `docs/model-contract.md`: exact mathematics and update semantics.
- `docs/historical-options.md`: the three retained options, their exact semantics, constraints, and rejected historical behavior.
- `docs/legacy-source-map.md`: provenance with source file, line range, and source-file hash.
- `tests/fixtures/legacy/preset_rows.jsonl`: schema-neutral bootstrap capture of every accepted legacy row.
- `tests/fixtures/contract/`: small deterministic scalar/field fixtures.
## Phase 0.1 — Freeze the shared mathematical contract
@@ -178,31 +177,31 @@ Freeze:
The historical head anomaly is discarded and has no configuration option.
## Phase 0.4 — Preset and fixture capture
## Phase 0.4 — Preset baseline and fixture capture
### Substep 0.4.1 — Schema-neutral bootstrap capture
### Substep 0.4.1 — Freeze product preset authoring policy
Before the Rust schema exists, use a tiny reviewed extraction script to copy accepted source rows verbatim into JSONL with source path, line number, parsed columns, description, and source hash. This is evidence capture, not the final application importer. Expected counts are:
All bundled product presets are newly authored directly in the versioned product schema established by Macrostep 01. Do not extract, convert, deduplicate, or migrate legacy preset rows, and do not require a product-preset count, grouping, or value correspondence with any legacy catalogue.
- main catalogue: 188 valid rows;
- SDL catalogue: 187 rows, largely duplicate and containing drift;
- multiscale catalogue: 12 rows = 4 triplets;
- sphere catalogue: 1 row;
- DT catalogue: 29 rows.
Each bundled preset must be a complete deterministic run definition with:
Do not deduplicate the evidence and do not run legacy executables. Macrostep 01 converts this frozen capture into the versioned schema and performs deliberate deduplication.
- a stable ID, name, description, tags, and authoring provenance;
- explicit variant, rules, dynamics, shape, backend, and presentation recommendations;
- an explicit seed and deterministic initializer;
- only the localized historical-option fields applicable to that run, with modern defaults otherwise.
### Substep 0.4.2 — Freeze migration defaults absent from rows
Preset reviews validate schema completeness, unique identity, deterministic reproduction, and intentional coverage of supported variants and dynamics. Legacy sources remain documented provenance for the mathematical contract and retained option semantics, not input data for product presets.
Commit a mapping table so every imported row becomes a complete run:
### Substep 0.4.2 — Freeze deterministic preset baselines
- Base: shape `1024`/`512²`/`64³` by dimension, Euler, standard FFT, seed `1`, cleared C++-inspired periodic splats, palette 2, and 3-D volume style 2. Because Euler is selected, no RK4-reference field is stored; creating relaxation+RK4 later defaults that newly applicable field to `StageState`.
- SDL rows: same model mapping, source-tagged and deduplicated against main rows; no separate backend.
Use these modern baselines when authoring bundled presets; an individual preset may intentionally override them, but every override is explicit in that preset rather than inferred by migration:
- Base: recommended shape `1024`/`512²`/`64³` by dimension, Euler, standard FFT, seed `1`, cleared C++-inspired periodic splats, palette 2, and 3-D volume style 2. Because Euler is selected, no RK4-reference field is stored; a newly authored relaxation+RK4 preset defaults its applicable field to `StageState`.
- Multiscale: `512²`, sequential composition, independent kernels, growth/relaxation only, standard FFT, seed `1`, cleared base-style splats, and palette 7.
- Sphere: `K=128`, `R=K/2`, seed `1`, cleared then seeded overlays, and palette 1. Generate a corrected-default preset and a separately named `SphereModel::Legacy` preset from the historical row.
- DT: no historical fixed shape existed because it followed the window; choose and record `512²`, depth 16, causal delay, seed `1`, a seeded box field replicated into all layers, and palette 7. Record this initializer/shape as an intentional modern replacement.
- Sphere: `K=128`, `R=K/2`, `SphereModel::Corrected`, seed `1`, cleared then seeded overlays, and palette 1. Any newly authored preset selecting `SphereModel::Legacy` is separately named and explicitly selects only that local option.
- DT: `512²`, depth 16, causal delay, seed `1`, a seeded box field replicated into all layers, and palette 7. The fixed model shape and all-layer initializer are intentional modern choices because the historical implementation followed the window.
The table must distinguish source facts from chosen deterministic replacements.
These baselines are product-authoring policy, not legacy-row defaults.
### Substep 0.4.3 — Freeze initializer algorithms
@@ -234,11 +233,11 @@ Use explicit arrays for essential goldens, not only PRNG seeds.
2. Record source paths and relevant line ranges.
3. Mark the specification plus the new contract as the implementation authority.
4. Future legacy consultation requires a concrete discrepancy, and its finding must be copied back into the contract with provenance.
5. The application, build, tests, and importer outputs must not require the legacy path.
5. The application, build, tests, and bundled preset assets must not require the legacy path.
## Exit gate
- Every formula, constant, mode, topology, retained historical option, and discarded defect has a local documented decision.
- Preset counts/grouping reconcile with the source catalogues.
- The newly authored bundled-preset policy and deterministic baselines are frozen independently of legacy catalogue rows.
- Fixtures are readable without legacy tools.
- A new implementer can build any mandatory backend using only this repository.

View File

@@ -72,7 +72,7 @@ Validation returns field-specific, actionable errors and rejects:
- 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;
- 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.
@@ -86,7 +86,7 @@ Every preset has:
- stable slug/UUID;
- display name and description;
- variant and schema version;
- source provenance and optional original row;
- authoring provenance and optional links to relevant model-contract or legacy-source-map entries;
- tags;
- deterministic default seed;
- relevant localized historical-option values;
@@ -104,15 +104,11 @@ Define a normalized run descriptor suitable for logs, state exports, and bug rep
- Save settings atomically through temp-file + rename.
- Preserve unknown newer schema versions by refusing destructive writes.
### Substep 1.3.2 — Schema-backed legacy conversion
### Substep 1.3.2 — Newly authored bundled presets
Consume Macrostep 00's frozen JSONL evidence and migration-default table to generate final versioned 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.
- 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.
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
@@ -161,8 +157,8 @@ Essential shaders should be embedded with `include_str!` or packaged under a com
## 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.
- 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

View File

@@ -128,7 +128,7 @@ If targets fail, preserve correctness, lower recommended defaults, and file meas
- Complete standard GPU base pipeline with CPU fallback and selectable legacy packed-unitary GPU pipeline.
- 1-D profile/history, 2-D production field, 3-D slices and volume renderer.
- CPU/GPU state transfer and all base inspection channels.
- Imported and validated base preset catalogue.
- Newly authored and validated deterministic base preset catalogue.
## Exit gate

View File

@@ -12,7 +12,7 @@ Macrosteps 0006 complete.
- Mandatory scope is three scales on a periodic 2-D domain.
- The historical 1-D/3-D infrastructure was nonfunctional because integration existed only in 2-D; do not claim support there.
- Generalizing to `n` scales is acceptable internally, but imported fixtures remain exactly three.
- Generalizing to `n` scales is acceptable internally, but mandatory product presets and contract fixtures remain exactly three scales.
## Phase 7.1 — Typed semantic model
@@ -31,7 +31,7 @@ Composition
Each `ScaleConfig` owns radius/ratios, `dt`, dynamics, and rule. Dimension/shape belongs to the common domain, not each scale.
Validate positive geometry, valid rules, exactly three scales for imported presets, growth/relaxation dynamics only, and descending/nested scales for chained bands. Nonnested bands are defined but produce a warning explaining their meaning.
Validate positive geometry, valid rules, exactly three scales, growth/relaxation dynamics only, and descending/nested scales for chained bands. Nonnested bands are defined but produce a warning explaining their meaning.
## Phase 7.2 — Neighborhood evaluation
@@ -145,13 +145,13 @@ Provide:
- combined increment and clamp-stage views;
- scale-color overlay and radial-band diagram;
- clear validation for unsupported discrete dynamics and warnings for nonnested chained radii;
- imported triplet preset browser preserving group identity.
- newly authored three-scale preset browser with stable preset identity.
## Deliverables
- CPU and GPU multiscale 2-D backend.
- All six kernel/composition combinations for growth/relaxation, using either selectable GPU FFT algorithm.
- Per-scale inspectors and imported four legacy triplet groups.
- Per-scale inspectors and newly authored deterministic multiscale presets.
## Exit gate

View File

@@ -136,7 +136,7 @@ At 512² and `ra≈12`, target p95 GPU step below 33 ms on the designated machin
- CPU delayed-history oracle and GPU backend.
- One explicit causal indexing policy.
- Imported DT catalogue with named presets.
- Newly authored deterministic DT presets with stable names and identities.
- History/radial-delay workbench views, restart-state export, and exact continuation checkpoints.
## Exit gate

View File

@@ -28,7 +28,7 @@ The original source position is ~/Nextcloud/VecchiProgetti/SmoothLifeAll/
4. **Inspectable by design.** `A`, `M`, `N`, target `S`, derivative/increment, kernels, scale outputs, history layers, and topology diagnostics are first-class channels.
5. **Historical simulation behavior is exceptional and local.** There is no general legacy engine or compatibility profile. Only the explicitly retained RK4 relaxation reference, packed-unitary FFT, and sphere model are selectable; all other simulation behavior follows the new deterministic design.
6. **Deterministic replay and continuation.** A run is identified by schema version, preset ID, seed, shape, backend, only the localized historical options relevant to that run, and step count. Restart-state files reset numerical history; exact checkpoints additionally store AB history, DT history/head, generation, and deterministic RNG state.
7. **No runtime dependency on the old project.** Legacy catalogues are imported once and committed in the new schema.
7. **No runtime dependency on the old project.** Bundled product presets are newly authored in the new schema; legacy sources remain provenance for the model contract, not preset input.
8. **No steady-state allocation or readback.** Buffers and plans are reused; GPU readback is only for tests and explicit exports.
## Intended repository shape
@@ -39,7 +39,7 @@ smoothlife/
├── src/
│ ├── lib.rs # raylib-free public core
│ ├── main.rs # application entry point
│ ├── config/ # schema, validation, preset library/import
│ ├── config/ # schema, validation, preset library
│ ├── field/ # shapes, storage, indexing, inspection data
│ ├── math/ # curves, rules, kernels
│ ├── integration/ # discrete, Euler, AB3, RK4