docs: require reference-validated LMS evaluator

Replace tail-stabilization framing with benchmarked observer data,
error thresholds, and range-extreme correctness across roadmap and
fundamentals plans.

Author: saabi

_docs/Roadmap.md

@@ -47,7 +47,7 @@ Aligned with the **recommended next order** in [`surface-constraint-gamut-projec
 
 1. **Color-space role cleanup** — reflect the three-role model in UI/docs: Active gamut = working/export intent, World space = layout/interpolation coordinate system, Display gamut = physical display capability. Includes a planned **global Color Context** surface: move Active gamut and Display gamut/profile selection out of the Explorer pipeline when chromatic adaptation / display-gamut work gives that surface real behavior. The Explorer lane keeps reference shell and future Explorer display-gamut clipping/mapping controls. Also documents that `srgbLin` already **is** the gamut-independent colorimetric anchor (linear sRGB ↔ XYZ D65 is a fixed bijection); the proposed XYZ-D65 source-storage migration is **deferred** (representational relabeling, not a correctness fix — not worth a schema break). See [`color-space-role-architecture.md`](color-space-role-architecture.md).
 2. **White point & chromatic adaptation** — add a standard CAT (Bradford) wherever whites differ, for active color spaces and the display gamut; D65↔D65 stays a no-op. Today there is **no** adaptation, so non-D65 gamuts (NTSC = Illuminant C, CIE = Illuminant E) and any calibrated display white render wrong. Put the adaptation matrix in the shared `DerivedMatrices` bundle for CPU/GPU/picking parity.
-3. **Observer fundamentals & chromaticity registry** — stabilize the current LMS/spectral tails, then add table-backed LMS/CMF and chromaticity-diagram registries. This supports the LMS/spectrum panels, spectral locus overlays, direct xy picking, future display-gamut diagnostics, and CVD parity. Tail stabilization can ship without a schema bump; user-selectable observer models belong to the global Color Context only after CVD/panel parity is ready. **Plan:** [`lms-fundamentals-chromaticity-plan.md`](lms-fundamentals-chromaticity-plan.md).
+3. **Observer fundamentals & chromaticity registry** — audit the current LMS/spectral evaluator against authoritative observer data, keep or replace analytical segments based on measured error, then add LMS/CMF and chromaticity-diagram registries. This supports the LMS/spectrum panels, spectral locus overlays, direct xy picking, future display-gamut diagnostics, and CVD parity. The evaluator correction can ship without a schema bump while the observer identity stays the same; user-selectable observer models belong to the global Color Context only after CVD/panel parity is ready. **Plan:** [`lms-fundamentals-chromaticity-plan.md`](lms-fundamentals-chromaticity-plan.md).
 4. **Per-list ramp pipeline instances** — each source list owns its own interpolation, placement, extension, and constraint settings (the engine already computes per-list rows; the settings are still global). The architecture payoff; needs a schema bump (v12 → v13). **Plan:** [`per-list-pipeline-plan.md`](per-list-pipeline-plan.md).
 5. **Separate main-curve and extension constraints** — Interpolate constraints and Extend/Expand constraints independently configurable, per source list. Batched into #4's schema bump (see plan); wiring lands in a later phase.
 6. **Display gamut preferences + Color Context UI** — store display profiles/calibration in `localStorage`; users may have multiple displays. Initial default remains sRGB. Depends on #2 for correct white handling and should share the global Color Context surface with future observer/fundamentals settings from #3. This is the preferred moment to move Display gamut out of the Explorer pipeline.
@@ -121,7 +121,7 @@ Key points:
 
 - source lists stay in `srgbLin`, documented as the canonical gamut-independent colorimetric anchor (≡ XYZ D65); the XYZ-D65 migration is **deferred** (representational only);
 - add chromatic adaptation (Bradford) for non-D65 active/display whites — currently absent;
-- stabilize LMS fundamentals / spectral locus tails and add an observer + chromaticity-diagram registry before relying on advanced spectral/chromaticity diagnostics;
+- audit and correct the current LMS/spectral evaluator against authoritative reference data, then add an observer + chromaticity-diagram registry before relying on advanced spectral/chromaticity diagnostics;
 - Display gamut profiles live in `localStorage`, not shared document state;
 - Active gamut and Display gamut should become global Color Context controls, not Explorer pipeline controls; Explorer keeps reference shell and display-mapping/clipping controls;
 - each source list owns independent pipeline settings (per-list pipelines) — the next architecture build, behind a schema bump (see [`per-list-pipeline-plan.md`](per-list-pipeline-plan.md));
@@ -165,10 +165,10 @@ Open question: should neutral backdrop apply only inside the WebGL canvas letter
 | Custom Display Gamut | Wizard UX design before implementation |
 | Gradient designer improvements | Builds on existing ramp model |
 | Okhsl/Okhsv picker coordinates | Sliders for selected stop only |
-| Observer fundamentals + chromaticity diagrams | Stable LMS/spectral locus registry; see `lms-fundamentals-chromaticity-plan.md` |
+| Observer fundamentals + chromaticity diagrams | Reference-validated LMS/spectral evaluator and diagram registry; see `lms-fundamentals-chromaticity-plan.md` |
 | Direct xy chromaticity picking | Needs luminance hold policy and active diagram/observer semantics |
 | Gamut boundary snap tools | Stop-level UX on top of boundary projection |
-| Spectral/chromaticity intensity volume | Optional reference layer; depends on stable observer/fundamentals registry |
+| Spectral/chromaticity intensity volume | Optional reference layer; depends on reference-validated observer/fundamentals registry |
 
 Full rationale: [`design-review-unimplemented-features.md`](design-review-unimplemented-features.md).
 

_docs/color-space-role-architecture.md

@@ -192,10 +192,11 @@ math, and future chromaticity picking/reference layers.
 
 Recommended sequencing:
 
-1. First, stabilize the current default fundamentals implementation
-   (table/spline-backed tails) without changing document schema or exposing new
-   user settings.
-2. Next, add `fundamentals.ts` / `diagrams.ts` registries behind the existing
+1. First, audit the current default analytical fundamentals evaluator against
+   authoritative reference data, keeping accurate analytical segments and
+   replacing only the regions/methods that fail error or tail-behavior criteria.
+   This does not require document schema changes or new user settings.
+2. Next, add `fundamentals.ts` / `diagrams.ts` registries behind the corrected
    default behavior.
 3. Expose a chromaticity diagram selector in Explorer Reference / instrument UI
    if it only changes the panel projection.

_docs/lms-fundamentals-chromaticity-plan.md

@@ -1,6 +1,6 @@
 # Specification & Plan: Modular LMS Cone Fundamentals & Chromaticity Diagrams
 
-This specification outlines the modularization of **LMS Cone Fundamentals** and the implementation of **Multiple Chromaticity Diagrams** in COLOR LAB. It addresses the tail divergence of the current analytical fits, maps the user's custom curve to its experimental origins, and details the impact on active and planned color pipelines.
+This specification outlines the modularization of **LMS Cone Fundamentals** and the implementation of **Multiple Chromaticity Diagrams** in COLOR LAB. It replaces the current analytical wavelength fits with reference observer data as the source of truth, maps the user's custom curve to its experimental origins, and details the impact on active and planned color pipelines.
 
 ---
 
@@ -48,10 +48,29 @@ Each fundamental model will define:
 2. **Stockman & Sharpe (2000) 10°**: Large-field physiological model.
 3. **Smith & Pokorny (1975)**: Derived from the Judd-modified CIE 1931 CMFs.
 
-#### Resolving Tail Instability:
-To achieve stable analytical evaluation down to 380nm and up to 780nm, we will support two approaches:
-- **Cubic Spline Interpolation**: Read official 1nm/5nm tables from CVRL and perform natural cubic spline interpolation. This is mathematically analytical, matches the experimental data exactly, decays naturally to zero, and is highly stable.
-- **Asymmetrical Gaussian/Log-Normal Models**: If a closed-form formula is preferred, replace the Gaussian-derivative fits with an asymmetrical log-normal formulation (e.g., the Govardovskii template) that guarantees asymptotic decay to zero at the bounds.
+#### Reference-Validated Evaluator Requirement
+The first implementation must not hide the current edge artifacts by clamping,
+windowing, or otherwise cosmetically stabilizing an evaluator that is wrong at
+the edges. Range extremes are colorimetrically meaningful for spectral locus and
+observer work, so the evaluator must be validated against authoritative
+measured/tabulated data across the full visible range.
+
+Recommended approach:
+
+- Use CVRL / CIE-published table data for the selected observer model at the
+  finest practical wavelength interval available as the benchmark.
+- Evaluate both table-based interpolation and continuous analytical fits against
+  that benchmark. A good continuous fit can be preferable between tabulated
+  samples if its error is lower than interpolation and it behaves correctly at
+  the extremes.
+- For interpolation, prefer monotone or shape-preserving methods where possible.
+  Natural cubic splines are acceptable only if they do not overshoot low-energy
+  tails or create negative lobes.
+- For analytical fits, require explicit error thresholds, correct non-negative
+  tail behavior, and no oscillation/divergence outside the fitted core range.
+- Keep the current analytical fit as a candidate/comparison fixture. If it is
+  within acceptable error over a documented subrange, keep using it there and
+  replace only the failing region with a better reference-validated evaluator.
 
 ### B. Chromaticity Diagrams (`fe/src/lib/color/diagrams.ts`)
 Each diagram defines:
@@ -117,17 +136,20 @@ This means the UI should not introduce a ramp-local or theme-local
 Recommended split:
 
 - `observerModel`: document-level only once it affects saved analysis or CVD
-  behavior. Until then, keep it fixed at the current default and use the new
-  registry internally to stabilize tails.
+  behavior. Until then, keep it fixed at the current default and move that
+  default onto reference data internally.
 - `chromaticityDiagram`: local UI preference if it only changes the xy/u'v'
   instrument view; document-level only if diagram selection becomes semantic
   for picking, saved annotations, or exported analysis.
 
 ### Sequencing with the Current Roadmap
 
-1. **Tail stabilization can ship first without a schema bump.** Replacing the
-   unstable analytical tails with table/spline data behind the current default
-   observer is a correctness fix for existing behavior.
+1. **Reference-validated evaluator work can ship first without a schema bump.**
+   Replacing or segmenting the unstable analytical evaluator behind the current
+   default observer is a correctness fix for existing behavior. The replacement
+   may be table-interpolated or analytical, but it must be benchmarked against
+   reference data and preserve colorimetric outputs at range extremes rather
+   than merely suppress visible artifacts.
 2. **Chromatic adaptation should precede exposed observer/profile choices.**
    The same shared `DerivedMatrices` path should carry white-point adaptation
    and observer/display matrices so CPU, GPU, picking, and panels agree.
@@ -160,29 +182,35 @@ The CVD simulation is performed by projecting RGB colors into the LMS color spac
 - **Impact**: Exposing user-selectable observer/diagram settings may require
   persistence, but only after deciding whether each setting is document semantic
   or local preference.
-- **Resolution**: Do **not** bump the schema for the tail-stability fix. If a
-  later phase persists document-level observer choices, store them under the
+- **Resolution**: Do **not** bump the schema for evaluator replacement while the
+  selected observer identity stays the same. If a later phase persists
+  document-level observer choices, store them under the
   global color/observer context, not `theme`, and then follow the document
   persistence playbook with an explicit migration.
 
 ---
 
 ## 6. Detailed Implementation Plan
 
-### Phase 1: Experimental Data & Fit Comparison
-1. Write a scratch script under `fe/src/lib/color/scratch/compare-fundamentals.ts` to load CVRL datasets.
-2. Compare the user's custom Gaussian formula from `pipeline.ts` to identify its exact source data (e.g., Stockman & Sharpe 2°).
-3. Evaluate the fit MSE and determine stable bounds.
-4. Replace only the current default evaluator if the comparison confirms a
-   drop-in table/spline fix; this phase should not add UI or persistence.
+### Phase 1: Reference Data & Fit Audit
+1. Write a scratch script under `fe/src/lib/color/scratch/compare-fundamentals.ts` to load CVRL/CIE reference datasets.
+2. Compare the current Gaussian-derivative formula from `pipeline.ts` against the relevant reference data to identify its closest source model and quantify errors across the full visible range, with special attention to the low-energy tails.
+3. Select the reference dataset that should define the current default observer. Prefer newer physiological observer measurements where they match the intended model; document any mismatch with CIE 1931/1964 diagram geometry.
+4. Compare evaluator strategies:
+   - current analytical fit over any range where it remains accurate;
+   - shape-preserving interpolation from reference samples;
+   - continuous analytical alternatives or segmented fits.
+5. Implement the default evaluator from the strategy with the best documented accuracy/behavior tradeoff. Reject interpolation or analytical methods that overshoot, go negative, oscillate, diverge, or distort spectral-locus extremes.
+6. Keep this phase UI-free and persistence-free: it changes the numeric evaluator for the same observer identity, not the saved document shape.
 
 ### Phase 2: Registry & Mathematical Foundation
 1. Implement `fe/src/lib/color/fundamentals.ts` containing:
-   - Analytical spline evaluators for Stockman-Sharpe 2°/10° and Smith-Pokorny 2°.
+   - Reference-validated evaluators for Stockman-Sharpe 2°/10° and Smith-Pokorny 2°.
    - Matrices for LMS $\leftrightarrow$ XYZ mapping.
 2. Implement `fe/src/lib/color/diagrams.ts` containing the coordinate projection math for CIE 1931 xy, CIE 1976 UCS u'v', and CIE 2006 xy.
-3. Keep the active runtime default identical to current behavior until CVD and
-   panel parity are ready.
+3. Keep the selected default observer identity unchanged until CVD and panel
+   parity are ready, but preserve only evaluator segments that meet the
+   documented reference-data error and tail-behavior criteria.
 
 ### Phase 3: WebGL & CVD Updates
 1. Modify `rebuildMatrices` in `fe/src/lib/renderer/uniforms.ts` to compute `RGB2LMS` and `LMS2RGB` dynamically using the active LMS model.

_docs/pipeline-node-ui-proposal.md

@@ -161,8 +161,9 @@ Implementation timing:
 - Keep the current selector visible until the global Color Context exists.
 - Best timing for the move is after chromatic adaptation or together with Display gamut preferences/classification. Before that, the Color Context would be mostly a renamed control with little explanatory payoff.
 - Do not expose observer selection before `fundamentals.ts` / `diagrams.ts`
-  registries and matching CVD matrices exist. A tail-stability fix can remain
-  invisible and does not need a new UI surface.
+  registries and matching CVD matrices exist. Auditing/correcting the current
+  evaluator against reference observer data can remain invisible and does not
+  need a new UI surface.
 
 #### Explorer Reference / Display Mapping