FESADev/docs/mitc4-shell-feast-eigen/implementation-interfaces.md

# 구현 경계와 source/test 대응

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `implementation-planning-agent`
- Input contract revision: `r2`
- 기본 보고서: [implementation-plan](implementation-plan.md)

## 실제 repository 확장점

기존 `DomainMappingContext::Impl`이 syntax·material/property·sole step candidate를 소유하고
thin mapper들이 finalize를 호출한다. 이 범위를 확장하며 parallel parser/새 registry를 만들지
않는다. `KeywordBlock`에는 physical_lines가 있지만 `DataLine`에는 fields/location만 있어
I/O의 raw count/density data를 보존하려면 `original_line`이 필요하다.

`Domain::Steps()`와 `AnalysisModel::Step()`은 기존 static API다. 별도 frequency 정의를
추가하고 active boundary/location view로 DofManager를 연결한다. StaticStep의 미사용 time/load
fields에 frequency 의미를 끼워 넣지 않는다. FrequencyStep은 boundaries/source options/N을
소유하고 density는 material identity에 연결된 Domain composition record다. Concrete material
base를 optional capability로 늘리지 않는다.

현재 `ElementFactory::CreateShell`은 private이고 `unique_ptr<Element>`를 반환한다. 승인
shell-only procedure에 필요한 typed `CreateMitc4Shell` 생성 seam을 추가하되 기존 generic
Create도 같은 checked construction을 사용한다. Consumer의 downcast/type-switch 없이
typed mass contribution과 기존 ElementView stiffness contribution을 같은 layout/scatter에 준다.
Global equation/index/pattern은 끝까지 DofManager 소유다.

`Mitc4Shell::Stiffness`는 현재 min rotary diagonal을 사용하고
`NonlinearMitc4Shell::Create`는 그 초기 kd를 저장한다. 새 private trace helper로 앞 경계만
바꾸면 nonlinear은 기존 frozen path를 재사용한다. Tests는 formula 값 변경뿐 아니라
완전한 geometry/frame 재생성·partial BC·반력·objective tangent를 검증한다.

`hdf5_internal::WriteModel`은 model datasets와 static metadata를 함께 쓴다. Model-only seam을
분리하고 기존 WriteModel이 같은 static metadata와 datasets를 호출하도록 유지한다. Eigen은
그 model-only 함수와 eigen-only metadata/schema를 사용한다. 기존 static reader inventory는
그대로 두며 eigen discriminant 없이 새 파일을 static으로 읽지 않게 테스트한다.

## Step별 API와 책임

| Step | 완성되는 경계 | 소유 데이터와 호출 규칙 |
| --- | --- | --- |
| 0 | FrequencyStep, Domain::FrequencySteps/Densities, active view, exact mapping | Raw syntax→validated immutable records; density/t/source resolution; static API/순서 보존 |
| 1 | ComputeDrillingScale→Mitc4Shell::Stiffness | 초기 physical20만 입력, eight diagonals scaled mean; nonlinear 초기 저장 경로 재사용 |
| 2 | ConsistentMass→DeriveLumpedMass→ShellMassAssembler | Original24/C0..2 snapshot 보존, nodal6 blocks, stable COO/reduction; same source scatter |
| 3 | ReduceEigenSystem/RestoreEigenvector, DofManager finite layout | Original free K/ML 별도 보존, node P/Z/L/rcond와 finite pattern, sparse block whitening |
| 4 | FeastBackend/InitialSpace/Search→EigenSolver::SolveLowest | Vendor-private actual calls, neutral scalar/vector/history output; actual N/n/c/m0 각각 구분 |
| 5 | ValidateEigenpairs→LinearFrequencyProcedureExecutor::Execute | All-c 검증 후 paired N candidate, 전체 c metrics/history, Domain/view 수명, 아직 accepted commit 아님 |
| 6 | EigenResultsWriter/WriteEigenSchema/SelfCheckEigen→prepared CLI finalization | Log close, candidate close/readback, final replacement 뒤 nofail state swap |
| 7 | EigenReferenceComparison와 fresh-run portfolio | Source-key Value-only join/common policy, raw/new-binary evidence, canonical3 보고서 |

Private helper names는 Step에 지정한 책임·signature 역할을 지킨다. Parameter type의 상세 배치와
작은 private structs는 Implementation이 routine 선택할 수 있지만 승인 owned files 밖 확장,
physics/schema/tolerance 변경은 Coordinator에 반환한다. Public header는 standard/FESA value
type만 노출하고 MKL_INT, HDF5 hid_t, Win32 handle/header는 private source에 둔다.

## TDD file boundary

각 Step index는 tests/build/reports를 포함한 정확한 path 목록을 가진다. 현재
`scripts/msvc_harness/tdd_policy.py`는 production basename에 대응하는 test basename을
찾으므로 새 C++ header/source의 test를 반드시 먼저 생성한다. 아래는 새 경계별 대응이며
기존 production은 해당 existing test와 추가 feature suite를 함께 사용한다.

| Production basename | Related test path |
| --- | --- |
| frequency_step | `tests/unit/model/frequency_step_test.cpp` |
| domain_mapping_context | `tests/unit/io/abaqus/domain_mapping_context_test.cpp` |
| mitc4_drilling_scale | `tests/unit/elements/mitc4_drilling_scale_test.cpp` |
| mitc4_shell_mass | `tests/unit/elements/mitc4_shell_mass_test.cpp` |
| shell_mass_assembler | `tests/unit/assembly/shell_mass_assembler_test.cpp` |
| eigen_reduction | `tests/unit/analysis/eigen_reduction_test.cpp` |
| feast_backend | `tests/unit/solvers/eigen/feast_backend_test.cpp` |
| feast_initial_space | `tests/unit/solvers/eigen/feast_initial_space_test.cpp` |
| feast_search | `tests/unit/solvers/eigen/feast_search_test.cpp` |
| eigen_solver | `tests/unit/solvers/eigen/eigen_solver_test.cpp` |
| mkl_feast_eigen_solver | `tests/unit/solvers/eigen/mkl_feast_eigen_solver_test.cpp` |
| eigen_analysis_state | `tests/unit/analysis/eigen_analysis_state_test.cpp` |
| eigen_validation | `tests/unit/analysis/eigen_validation_test.cpp` |
| linear_frequency_procedure | `tests/integration/analysis/linear_frequency_procedure_test.cpp` |
| eigen_results_writer | `tests/unit/results/eigen_results_writer_test.cpp` |
| eigen_hdf5_results_writer | `tests/unit/io/hdf5/eigen_hdf5_results_writer_test.cpp` |
| eigen_hdf5_schema | `tests/unit/io/hdf5/eigen_hdf5_schema_test.cpp` |
| hdf5_model_writer | `tests/unit/io/hdf5/hdf5_model_writer_test.cpp` |
| prepared_analysis | `tests/unit/analysis/prepared_analysis_test.cpp` |

Existing stem의 `model_types/domain/analysis_model/dof_manager/input_syntax/input_reader/
mitc4_shell/element_factory/fesa_application`은 현재 대응 tests가 있고 각 Step의 관련 test와
함께 검증한다. 새 test registration은 `tests/CMakeLists.txt`, 새 library cpp는
`src/fesa/CMakeLists.txt`만 소유한다. Root CMake/dependency/preset 변경은 필요하지 않다.
Vendor link/runtime는 기존 Fesa::MKL/HDF5/TBB target closure로 실제 API를 실행해 확인한다.
명백한 missing runtime가 발견되면 임의 PATH 우회나 scope 확대 대신 exact evidence를 반환한다.

현재 `tests/CMakeLists.txt`의 `fesa_tests`는 세 executable `fesa_unit_tests`,
`fesa_integration_tests`, `fesa_reference_tests`에 의존하는 aggregate target이다.
따라서 Step의 `--target fesa_tests`는 reference까지 빌드한다. 새 `tests/unit/` 파일은
unit executable, `tests/integration/` 파일은 integration executable, `tests/reference/`
파일은 reference executable에 등록한다. 각 executable의 기존 runtime staging과
`gtest_discover_tests`를 유지한다. Focused inventory에서 새 이름 모두가 존재해야 한다.

## Candidate commit과 테스트 주입

별도 `EigenAnalysisState`는 N vectors와 raw scalars/source, all-c checks/history만 소유한다.
Working reduction/solver scratch는 procedure 실행 동안 유지되고 accepted state에 global dense
matrix나 미래 dynamics state를 남기지 않는다. `Swap`은 `noexcept`이고 소유 vector/record
교환만 수행한다. Execute 반환 candidate를 accepted state라고 보고하지 않는다.

Prepared/static 기존 overload는 보존하고 frequency executor/result/writer가 있는 overload를
추가하여 procedure 선택을 한 경계에 둔다. Output finalization은 candidate를 완성/검증/close하고
final replacement 성공 뒤 state swap을 수행한다. 이 순서에 fallible callback/allocation을
남기지 않는다. Failure injection은 EigenSolver/EigenResultsWriter 및 private backend/schema
seam에 제한한다. 새로운 public CLI failure flags는 없다. Raw HDF5 mutation은 test-local
generated file에서만 하고 저장 reference input/TXT/CSV는 read-only다.