smoothlife/docs/legacy-source-map.md

Legacy source map

This document is the static provenance record for Macrostep 00. It maps the decisions in the repository-local model contract and retained-options specification to the legacy tree without creating a runtime or build dependency on that tree.

Scope, authority, and notation

Legacy root used for every source-relative path below:

/home/fpasqua/Nextcloud/VecchiProgetti/SmoothLifeAll/

Line ranges are 1-based, inclusive physical lines. Every SHA-256 is for the complete file bytes, not only the cited range.

Decision labels used below:

• SOURCE FACT — behavior or data directly evidenced by a cited legacy file.
• CORRECTED DEFAULT — deterministic behavior selected by the rewrite instead of accidental or defective legacy behavior.
• RETAINED HISTORICAL OPTION — one of the three intentionally selectable historical behaviors.
• REJECTED DEFECT — observed legacy behavior that must not be reproduced.
• PROVENANCE ONLY — historical evidence that cannot control implementation or product behavior.

The implementation authority is the local contract+spec set: docs/model-contract.md, docs/historical-options.md, and this source map. The external SMOOTHLIFE_SPECIFICATION.md is a reviewed legacy specification and provenance source, identified by hash below; it is not an application, test, build, importer, or runtime dependency. If source and local authority differ, the explicit local decision wins.

This review was static. No legacy .exe, simulator, reference program, shader, build, or test executable was run. Hashing, line counting, and text inspection did not execute legacy code.

Shared/base model

Frozen interpretation

• SOURCE FACT: State is scalar; the FFT family supplies periodic 1-D, 2-D, and 3-D domains. The real and half-width complex buffers and default shapes are declared in SmoothLife/main.cpp:52-79,2839-2902.
• SOURCE FACT: The legacy constant named PI/pi is 6.283185..., i.e. conventional TAU = 2π, not π (SmoothLife/main.cpp:52; SmoothLife/shaders/snm2D.frag:6).
• SOURCE FACT: ri=ra/rr, transition width w=ra/rb, Euclidean sampled disk/ring weights, periodic signed coordinates, and normalization sums are in SmoothLife/main.cpp:1279-1427. The log records the check sum(KR)=279.216312, sum(KD)=35.524035 for ra=10, rr=3, rb=10 at SmoothLife/SmoothLifeLog.txt:303.
• SOURCE FACT: Rising curves 0–7, complete windows 8–9, mixer curves 0–7, and the four rule constructions are in SmoothLife/shaders/snm2D.frag:16-104. Modes 0/1/2 produce replacement, 2S-1, and S-A respectively at lines 105-119.
• SOURCE FACT: Euler replacement/update, AB3 coefficients, RK4 coefficients, final clamping, and the frame pipeline are in SmoothLife/shaders/inteuler2D.frag:14-25, intab2D.frag:16-29, intrk2D.frag:18-31, and SmoothLife/main.cpp:2601-2991.
• SOURCE FACT: The SDL branch is the same model with a one-pass clamped Euler update and no separate integration buffers (SmoothLifeSDL/main.cpp:61-82,2534-2550; SmoothLifeSDL/shaders/snm2D.frag:108-130). It is subsumed by the shared rewrite, not retained as a backend.
• CORRECTED DEFAULT: Generate complete sampled kernel support and warn when geometry is unsuitable. Do not retain the legacy Ra=(int)(ra*2) component cutoff (SmoothLife/main.cpp:1317-1323).
• CORRECTED DEFAULT: Discrete ignores dt and integrator; Euler, deterministic Euler→AB2→AB3 startup, and RK4 clamp at every intermediate and final commit are authoritative. Undefined legacy AB buffers are never used.
• CORRECTED DEFAULT: For relaxation+RK4, stages subtract their own stage state (Rk4RelaxationReference::StageState).
• RETAINED HISTORICAL OPTION: Rk4RelaxationReference::StepOrigin preserves the main program's stage-neighborhood/origin-subtraction mismatch: deriv(aa,de) computes from aa but passes global AA to snm (SmoothLife/main.cpp:2603-2611), while RK4 supplies AA1 for stages 2–4 (2968-2976). This option exists only for relaxation+RK4.
• REJECTED DEFECT: Modes 3/4 in shader/keyboard remnants are not supported (SmoothLife/shaders/snm2D.frag:111-117; the SDL catalogue's mode-4 row is SmoothLifeSDL/SmoothLifeConfig.txt:174).
• REJECTED DEFECT: Uninitialized AB history, stale history after model changes, framebuffer feedback, working-directory shader loading, old OpenGL compatibility syntax, platform rand(), and implicit backend substitution are not compatibility requirements.

Consulted shared/base files

Source-relative path	Relevant lines	SHA-256	Evidence
SMOOTHLIFE_SPECIFICATION.md	1-307	9f651e2697cf44a68cd29e835cb02b7c2e52e8f1de4353ae136254e760ef3d54	Complete reviewed legacy specification.
readme.txt	1-42	1194e6a53f8ae46131a60243cef296eef7ccd57bc832b0a88d1a147dbd5acc73	Variant catalogue, config convention, dependencies, controls.
SmoothLife/main.cpp	1-220, 1279-2041, 2601-3000	26b21bfa7fb262f02f5eec4c2615aa501639471ccebce33b2abeb4fb6ee02e58	Controls/parser, buffers, kernels, packed FFT driver, convolution/rule pass, dynamics/integration/defaults.
SmoothLife/shaders/snm1D.frag	1-119	35a0ba9092b48bcf56be03f392f528a78e0dc72112c5ad7e0c8914b47b272f36	1-D shared rule.
SmoothLife/shaders/snm2D.frag	1-119	747c1d6ed3c0218af54479f685774fe3ab8586101bfaa89985c5f683d68c09a3	Canonical reviewed rule curves, constructions, and dynamics.
SmoothLife/shaders/snm3D.frag	1-119	b059270be6aab015a091152c77ec7f3ee4fa19d87981512b73f31f4ca1b11b37	3-D shared rule.
SmoothLife/shaders/inteuler1D.frag	1-25	1496e49426db4a911bd704a431348512d0ddaf1f2aee7e012ea2e11cf7e808e9	1-D Euler/replacement and clamp.
SmoothLife/shaders/inteuler2D.frag	1-25	c5c64d4bb44ae15c1681fa4109ed66e93429b73c0df922f6597023838868c8d9	2-D Euler/replacement and clamp.
SmoothLife/shaders/inteuler3D.frag	1-25	dcb889521b935dd57f44f89df866484a922c1f314fb294385e90ddb5342276db	3-D Euler/replacement and clamp.
SmoothLife/shaders/intab1D.frag	1-29	938854c65c8f2133fd5bba2ae2256282defe23e8a0de3b888ffc3477927ca978	1-D AB3 formula and clamp.
SmoothLife/shaders/intab2D.frag	1-29	75c51d618061bbe453162ed62b6d9b86745bf689443044bec7343071c354ed1b	2-D AB3 formula and clamp.
SmoothLife/shaders/intab3D.frag	1-29	68241b04768a22a28185dbaee994ffc5efac8b80110faeb9d793041e036bc915	3-D AB3 formula and clamp.
SmoothLife/shaders/intrk1D.frag	1-31	9da9e4a012731ca6c2ce4106c1fdd973b4ed2e6cea918fc4f04fbb9f409001ef	1-D RK4 formula and final clamp.
SmoothLife/shaders/intrk2D.frag	1-31	e8a46cf4e6f92597facbbb2d10172eadd64d228f4dae49d4ae7483fe45d564bc	2-D RK4 formula and final clamp.
SmoothLife/shaders/intrk3D.frag	1-31	da0553727cc8be65e669fb5873d98e942971a38cc3965145ce3ba1016a8bfc5e	3-D RK4 formula and final clamp.
SmoothLifeSDL/main.cpp	1-230, 1230-1389, 2370-2631	7e0536e7a89cb12aecbc1f181ec736269ba0a83c58170b761812932b727f3787	SDL buffers/parser/kernel and one-pass frame loop.
SmoothLifeSDL/shaders/snm2D.frag	1-130	a148bdccbce861babd85b3af1f96854be0b5dfde9fda62957b7b30d66f394342	One-pass Euler behavior and mode remnants.
SmoothLifeSDL/readme_sdl.txt	1-3	fb7d3b6447893d8e3b43acd7a0de696b3bf4c974c62c84147fb155501ae0feb0	Portability/dependency limitations; no separate model semantics.

Packed FFT

Frozen interpretation

• SOURCE FACT: Adjacent real x samples are packed into complex .rg, spectra have NX/2+1 x entries, and inverse conversion selects real/imaginary components by x parity (SmoothLife/main.cpp:1610-1752; copy shaders below).
• SOURCE FACT: x/y/z plans encode bit-reversed inputs and twiddles; each butterfly is scaled by 1/sqrt(2), with special real/complex tangle/untangle scaling (SmoothLife/main.cpp:1442-1909; FFT shaders below).
• SOURCE FACT: Spectral multiplication uses complex multiplication and scale sqrt(NX*NY*NZ)/kernel_sum (SmoothLife/main.cpp:1912-1967,2603-2610; kernel shaders below).
• CORRECTED DEFAULT: FftAlgorithm::Standard is the default: conventional unscaled forward transform, inverse scaled by sample count, then sampled-kernel normalization.
• RETAINED HISTORICAL OPTION: FftAlgorithm::LegacyPackedUnitary retains packing, half-width x spectra, plan stages, unitary scaling, conversion, and the sqrt(sample_count)/kernel_sum correction for supported power-of-two GPU 1-D/2-D/3-D paths.
• REJECTED DEFECT: The option does not retain legacy framebuffer/resource hazards, compatibility-profile syntax, relative shader discovery, incomplete kernels, or silent CPU/unsupported-GPU fallback. An unsupported explicit request fails clearly.

Consulted packed-FFT shaders

Source-relative path	Relevant lines	SHA-256
SmoothLife/shaders/fft1D.frag	1-41	b0810a5b89e9f8146a754c072360686573950c5a0010700d259d4726e3d8b238
SmoothLife/shaders/fft2D.frag	1-53	da1d4af18e4b6340a936a036ed010e7e03b3d548d4925f386c26f3fa310af99f
SmoothLife/shaders/fft3D.frag	1-61	7f0d58d93cacdfff249a277503b017dee371a1b1547a932d6b5305d2b973fae1
SmoothLife/shaders/copybufferrc1D.frag	1-13	f4869822b5e7b42abd3b05745e9802a27b00ba27f77c6c01271bfc5eaab28bcc
SmoothLife/shaders/copybufferrc2D.frag	1-13	5c325aaf44b5dfb6dd2f2cc1f831596cae1d61f1259bbafbdc5ddb55050e6914
SmoothLife/shaders/copybufferrc3D.frag	1-13	587f0fc491c7e887ab056136b164299cf6c7f508bd9f66f68584e8e8d3aeec2b
SmoothLife/shaders/copybuffercr1D.frag	1-22	eb436194b7e8db3db1ba825d0172db9f70069add9058cf85036ea88562d37249
SmoothLife/shaders/copybuffercr2D.frag	1-22	fb26244b12c6bad90fa84c9e784e72d409d024d1e66360fa7d0209c99059ab00
SmoothLife/shaders/copybuffercr3D.frag	1-22	54e93affdca4cb160ca8163615de5a1a8c272d3b3faf015258f9631daf404f90
SmoothLife/shaders/kernelmul1D.frag	1-19	426e730aaf723fb1ddc0b843f8ba3553add8e701e8bb3372e1b5cbb430f6caaf
SmoothLife/shaders/kernelmul2D.frag	1-19	3a7f923cbd689738e9c1c9337b75b675f39703d973b07b35010e56c68766acf4
SmoothLife/shaders/kernelmul3D.frag	1-19	fbe642d3bf78092d2d86ffcd02d6471fc6745e9c0dc97abbdf50f620ed4481b2

Multiscale

Frozen interpretation

• SOURCE FACT: Three parameter records and three disk/ring spectrum pairs are stored separately (SmoothLifeMultiscale/main.cpp:64-177). Startup consumes catalogue rows in consecutive triples and defaults to composition method 0 and kernel method 1 (2760-2894).
• SOURCE FACT: Independent inputs are (ring_i(A),disk_i(A)); chained inputs are (ring_0,ring_1), (ring_1,ring_2), (ring_2,disk_2) (2926-3023).
• SOURCE FACT: Sequential recomputes after each clamped update. Ordered clamped sum and arithmetic-mean increment evaluate one shared snapshot; their exact legacy accumulation is in integrate2D.frag:17-51.
• CORRECTED DEFAULT: The rewrite supports all six 2×3 combinations in 2-D with explicit current/snapshot references and corrected growth/relaxation increments. Sequential always recomputes; shared-snapshot methods never consume updated or stale fields.
• CORRECTED DEFAULT: Standard FFT, 512², independent inputs, sequential composition, deterministic seed/initializer, and palette 7 are migration-era defaults only if a future local preset is deliberately authored; the retired catalogue itself supplies none of those product dependencies.
• REJECTED DEFECT: Multiscale discrete dynamics is rejected until a target-aggregation enum exists. Also rejected: additive mode-0 targets, stale chained fields, undefined mode-2 source/reference, texture feedback, and empty 1-D/3-D integration branches (SmoothLifeMultiscale/main.cpp:2038-2134).

Consulted multiscale files

Source-relative path	Relevant lines	SHA-256	Evidence
SmoothLifeMultiscale/main.cpp	1-240, 2030-2149, 2740-3112	8481ed79b68efb9b824c95d5707477e3d60d213b0ee2ff6cb99a7d2f2484e07e	Controls/parser/storage, 2-D-only integration dispatch, defaults, six pipelines.
SmoothLifeMultiscale/shaders/snm2D.frag	1-129	ecf572a8f4262e3cebdca2e086059c63d2cf553a3c195a679792757a3c9a507e	Per-scale target/increment and missing clamp.
SmoothLifeMultiscale/shaders/integrate2D.frag	1-51	3276fe14b814e48883dc3eec735e7bd68e06c12ef96acfb1d8ed32fdc924e0ee	Sequential one-response update, ordered clamped sum, mean increment.

Sphere

Frozen interpretation

• SOURCE FACT: Six active K×K faces use K=128, internal R=K/2, and a 3*K*6 by 3*K atlas (SmoothLifeSphere/main.cpp:62-76,351-397).
• SOURCE FACT: Face directions use normalized face bases plus tangent coordinates; alpha stores spherical cell area (512-564). The original side table and gutter copies are at 765-858.
• SOURCE FACT: Distance is R*acos(dot(a,b)); ri=ra/3, widths are one, planar radii are converted geodesically, cap areas provide analytic normalization, and updates are replacement or fixed A+0.1(2S-1) (SmoothLifeSphere/main.cpp:1368-1392; program.frag:110-162).
• CORRECTED DEFAULT: SphereModel::Corrected completes edge/corner mapping, clamps dot products, uses explicit initialized ping-pong resources, and normalizes each center by actual cell_area*kernel_weight sums so a constant field remains constant.
• RETAINED HISTORICAL OPTION: SphereModel::Legacy retains the six-face atlas, side gutters with masked corner sectors, tangent cube-sphere geometry, original radius conversion/search stencil, analytic cap normalization, and the original replacement/fixed-0.1 dynamics.
• REJECTED DEFECT: Both models reject unclamped acos, undefined atlas contents, and texture feedback. The legacy option is geometrical/numerical, not unsafe-resource compatibility.

Consulted sphere files

Source-relative path	Relevant lines	SHA-256	Evidence
SmoothLifeSphere/main.cpp	1-180, 351-960, 1220-1506	c770fb36c562135d4bc65aeae36d71ae725286b05aa0ee37f92b6e6f0ddf8b1e	Config/defaults, atlas allocation, directions/areas, face mapping, rendering, radius conversion, initialization, frame loop.
SmoothLifeSphere/program.frag	1-162	037da34db6a050422c372bb458c78553df5ca00e22a26e1ced455f0007c6ce21	Direct geodesic stencil, analytic normalization, common rule, fixed update.
SmoothLifeSphere/SmoothLifeLog.txt	1-62	535680b9f1669e98ff8ac49882951bc0fa13112607d086d965bc40841f626cdd	Recorded K/R, planar/geodesic radii, analytic areas, historical environment; evidence only.

Delayed time

Frozen interpretation

• SOURCE FACT: The field is periodic in x/y and history is a repeat-wrapped 3-D texture of exactly 16 layers (SmoothLifeDT/main.cpp:330-394).
• SOURCE FACT: ri=ra/3, both widths are one, and the discrete stencil is numerically normalized (SmoothLifeDT/main.cpp:709-740).
• SOURCE FACT: Spatial radius selects a history coordinate offset by -distance/16; smooth mode reads one layer behind and adds fixed 0.1(2S-1) (SmoothLifeDT/program.frag:105-137). The main loop writes output into layer, then increments modulo 16 (SmoothLifeDT/main.cpp:932-1027).
• CORRECTED DEFAULT: head means next layer to overwrite, latest=wrap(head-1,16), and each radial sample uses wrap(latest-floor(distance+0.5),16). Delay zero therefore reads the latest committed state. All layers are initialized from one deterministic seeded field.
• CORRECTED DEFAULT: A future local preset may deliberately choose 512², seed 1, 1,000 deterministic 10–19 boxes, and palette 7; these are modern choices, not facts obtained from the retired catalogue.
• REJECTED DEFECT: The historical head anomaly—distance zero reading the layer currently being produced/uninitialized—is not selectable. Window-sized shape, gradual history filling, undefined layers, and platform-random boxes are also rejected.

Consulted delayed-time files

Source-relative path	Relevant lines	SHA-256	Evidence
SmoothLifeDT/main.cpp	1-160, 330-419, 690-1069	0595a283ce29a42ff7e1afc5dc835488feb22e52b85d9ee2e73fdcd75ec767a4	Config, periodic 16-layer allocation, sampled normalization, window-sized setup, head loop, random boxes.
SmoothLifeDT/program.frag	1-137	ec5b83df80d39996e99603c5195a43c3ccd0facc22106ab5359e81c8ca318f8e	Radius-dependent temporal lookup, common rule, fixed smooth update.
SmoothLifeDT/SmoothLifeLog.txt	1-64	9e14a8712c71900d10787c8b057b18dfe260a4c694ba843da08bc95b50d9654e	Recorded analytic/sampled sums, shape, and historical environment; evidence only.

CPU references

Role and interpretation

• SOURCE FACT: SmoothLifeFB.bas is a double-precision, threaded packed-unitary 2-D reference. It contains sampled kernels, packed FFT stages, sqrt(N)/kernel_sum, growth derivative, and deterministic mathematical AB startup formulas (1-300,500-809,870-908).
• SOURCE FACT: SmoothLifeFB_old.bas is the earlier discrete packed-FFT reference; it directly commits the target and is useful as an independent data-flow check, not as a supported backend definition (1-260,570-589).
• SOURCE FACT: Matlab constructs periodic sampled kernels and standard FFT convolution and explicitly compares Euler, improved Euler, AB3 startup, and RK4 with intermediate clamps (SmoothLifeMatlab/smoothlife.m:1-199). result.txt is historical numerical evidence, not a golden generated by this rewrite.
• SOURCE FACT: GliderConstructor.bas is an inverse-design/lookup-table experiment with collision reporting, not a general simulator (1-254).
• CORRECTED DEFAULT: CPU code serves as an oracle for formulas and fixtures. Its platform RNG, drawing, fixed sizes, commented alternatives, and UI behavior are not implementation requirements.
• REJECTED DEFECT: AB4, improved Euler, the glider constructor, and old direct-discrete implementation do not expand the mandatory option set. Exactly three historical options remain: RK4 step-origin reference, packed-unitary FFT, and legacy sphere model.

Consulted CPU/reference files

Source-relative path	Relevant lines	SHA-256
SmoothLifeFreeBasic/SmoothLifeFB.bas	1-300, 500-909	e652379593823fee31cd1a9cf7acc779803aaf04d8efe3f1c0d2f3bf67acd1cb
SmoothLifeFreeBasic/SmoothLifeFB_old.bas	1-260, 570-589	0cf2f0eebeaf250209bccaf418dccbe99641ede080bb3930fe54d733b281dbd5
SmoothLifeFreeBasic/GliderConstructor.bas	1-254	3afe897aeb2b2ae24e0cc3c8f7371b4ab89ef033ad4524b3f6ef3320f8f5cd26
SmoothLifeMatlab/smoothlife.m	1-199	5de29b0fa2d46a9e53d8744f1eeb410bb6c8f7f490ec69be724f4c19a00b4643
SmoothLifeMatlab/result.txt	1-69	405c8b43beb77bf883bb00e2471abb88dd50497292162fb709539cd62de2fcf8

Retired catalogues and logs

Non-import policy

The legacy catalogues are PROVENANCE ONLY.

• There is no JSONL capture in this task.
• There is no catalogue migration in this task.
• There is no product preset dependency on any legacy config, catalogue, log, path, row order, or description.
• Application code, tests, builds, and future import outputs must not open the legacy root.
• A future local preset may quote a row only through a separate, explicit, reviewed decision that records its provenance and fills every modern field. It must not revive a live importer or hidden dependency.

Static reconciliation of the files actually present:

Catalogue	Static contents and parser fact	Status
Main	188 lines begin with 1, 2, or 3; read_config accepts exactly that first-byte condition. The historical log independently records 188.	Provenance only; no capture or migration.
SDL	187 lines begin with 1, 2, or 3. It is largely duplicate/drifted main data and includes a mode-4 row at line 174.	Provenance only; no SDL product backend.
Multiscale	12 accepted rows, interpreted by startup as four consecutive triplets; the first triplet is duplicated in the old section.	Provenance only; grouping evidence only.
Sphere	Two numeric candidate rows are physically present at lines 1-2, but read_config performs one fixed sequence of fscanf calls and therefore loads only the first tuple at startup.	Runtime-accepted count is one; both physical rows remain provenance only.
Delayed time	38 numeric candidate rows are physically present at lines 1-42, but read_config likewise loads only the first tuple. This does not reconcile with the obsolete Macrostep-00 draft expectation of 29 rows.	Record the discrepancy; do not normalize, capture, or migrate it. Runtime-accepted count is one.

Consulted catalogue/config/log files

Source-relative path	Relevant lines	SHA-256	Evidence
SmoothLife/SmoothLifeConfig.txt	1-219	7085be7825a98df0fc3c68d6e9b4da3558955d77dc9f11861d6b1575a0b618a7	Main raw catalogue and comments.
SmoothLife/SmoothLifeLog.txt	1-321	295c29ed08d3f9028128fbee49be4de614bf5c4b6778585335b72fe7f1601877	Historical row count, environment, shader/resource trace, kernel sums; evidence only.
SmoothLifeSDL/SmoothLifeConfig.txt	1-219	bc86b688f61d325d8b0eed56367dcd0e3eaf16d78bffa90611678f8d614d1c75	SDL raw catalogue and drift.
SmoothLifeMultiscale/SmoothLifeConfig.txt	1-37	fd8749d8557e0b927932796a4dcebdb881898fac77503f263b363320f8185985	Twelve rows/four triplets.
SmoothLifeMultiscale/SmoothLifeLog.txt	1-314	9f8deb473f9a3e110291537705f2dfdce1a202ffa3cfccf6267c335441ac471c	Historical 12-row count and environment/resource trace; evidence only.
SmoothLifeSphere/SmoothLifeConfig.txt	1-11	6aa28438e4a53cab66e0229192235c4699bc518ec8a41e5f6bf6650efa36afa6	Two physical candidate rows; fixed parser consumes first only.
SmoothLifeDT/SmoothLifeConfig.txt	1-50	717bf025c67c3bfc8fd266ba8c7b5c871813e3c0030455daa8f5ea87a6b93cb4	Thirty-eight physical numeric rows; fixed parser consumes first only.

Future legacy-consultation protocol

Normal implementation must proceed from the local contract+spec set without reopening the legacy root. Future consultation is allowed only when all of the following hold:

1. A concrete discrepancy is stated: local authority is ambiguous, a fixture disagrees, or two local claims conflict.
2. The exact legacy source-relative path and 1-based line range are recorded.
3. The complete consulted file is SHA-256 hashed and added or updated here.
4. The finding is classified as SOURCE FACT, CORRECTED DEFAULT, RETAINED HISTORICAL OPTION, or REJECTED DEFECT.
5. Any implementation-relevant conclusion is copied into the local contract/spec and covered by a local fixture or test; a link to the legacy path is never sufficient.
6. No legacy executable is run. If static evidence cannot resolve the discrepancy, stop and request an explicit new decision rather than infer behavior from an unsafe run.

After that copy-back, the local contract+spec remains the implementation authority and the legacy tree returns to provenance-only status.