docs: define MITC4 eigen input and result contracts

docs/mitc4-shell-feast-eigen/io-mapping.md

@@ -0,0 +1,234 @@
+# MITC4 eigen 책임·실패·비교 대응
+
+- Feature ID: `mitc4-shell-feast-eigen`
+- Owner: `io-definition-agent`
+- Input contract revision: `r2`
+- 기본 보고서: [io.md](io.md)
+- 입력 원본: [io-input.md](io-input.md); 영속 schema 원본: [io-schema.md](io-schema.md)
+
+## M1. Input에서 equation/result까지
+
+아래는 implementation-neutral 책임 계약이며 정확한 C++ 타입/파일 분해는 Planning 소유다.
+현행 [Domain](../../include/fesa/model/domain.h),
+[model records](../../include/fesa/model/model_types.h),
+[syntax records](../../include/fesa/io/abaqus/input_syntax.h),
+[AnalysisModel](../../include/fesa/analysis/analysis_model.h)의 수명·의존성을 따른다.
+
+| 경계 | 소유·전달할 최소 의미 | 금지되는 의미 혼합 |
+| --- | --- | --- |
+| Input adapter | 원본 path/content identity, keyword/parameter/data raw text와 line; validated density/step/options/count, unresolved targets | TXT row수로 N 생성, source enum으로 actual backend 변경 |
+| Domain | Topology/source instance/labels, E/nu, section/t, optional material rho, initial director/frame, 유일 frequency 정의와 resolved homogeneous BC, warnings/provenance | Mutable mode/equation/vendor handle 소유 |
+| Frequency definition | Raw/canonical source step, source option presence/effective values, count data N, source locations, procedure=linear-frequency | Static increment/time/frame state를 frequency count에 재사용 |
+| AnalysisModel | Domain lifetime 아래 활성 shells/materials/sections/BC/frequency 정의의 const non-owning view | Domain copy 또는 새로운 geometry/material ownership |
+| DofManager | Source node×UX/UY/UZ/URX/URY/URZ, full/free/constrained injection과 stable equation indices, scatter/sparse pattern | Element/Node 내부에 equation ID 저장 |
+| Element/assembly | M1~M10 consistent/moments snapshot→nodal lumped blocks, r2 K contribution, source ordered reduction. 같은 source scatter와 실제 BC | Global scalar row lumping, artificial drilling mass, source S4R의 별도 kernel |
+| Eigen procedure | Candidate workspace/state, [E1~E8](formulation-eigen.md) 순서, analytic rank/positive/null projection, whitening, actual FEAST, all-c validation, N개 global 복원/결과와 commit | 기존 LinearStaticAnalysis::Run에 eigen lifecycle 누적, pretrained/preloaded state, static reaction/modal stress 복구 |
+| Private backend | C5/C6 controls, checked CSR/index conversion, vendor resources/thread guard, actual values/vectors/count/status와 call history | MKL_INT/HDF5/Win32 types 또는 vendor headers를 public solver core에 노출 |
+| Result/Output adapter | Validated source/global modal pair와 O1~O5 serialization/self-check/replacement | Near-zero clamp, physical 수치 또는 identity 재계산으로 실패 은폐 |
+
+Density/property lookup은 element마다 확정된 material identity를 사용한다. Consistent 원본을
+lumped 저장으로 덮어쓰지 않고 element-wise snapshot+moments로 검사 가능하게 한다.
+Full dense global MC나 일반 dense Schur는 필수가 아니다. 실제 global BC를 먼저 적용하고
+director null은 [E2](formulation-eigen.md#e2-nullpositive-basis를-node마다-결정)의 exact intersection으로만
+결정한다. Tiny positive mass는 정식화/NR conditioning 실패이며 input 지원에서 제거하지 않는다.
+
+Source `(instance_name, numeric label)`과 raw label spelling은 전체 경로에서 보존한다.
+Internal row order는 기존 identity-instance expansion/declaration order이며 DOF order는 고정이다.
+Renumbering은 geometry/connectivity/BC를 같이 대응하여 검사한다. 숫자가 우연히 같은
+source label/internal ID/equation ID를 비교키로 대체하지 않는다. 새로운 source order의 결과를
+행 위치끼리 비교하거나 repeated eigenspace의 특정 vector 방향을 동일하다고 요구하지 않는다.
+
+Accepted eigen state는 input/source step identity, N개의 paired raw scalar/global vector,
+source mapping 및 전체 c의 validation/call evidence만 소유한다. Domain·AnalysisModel·DOF
+정의와 수명 관계를 복사로 숨기지 않는다. Persistent N vectors로 같은 입력의 K/ML를
+재조립해 constraint/normalization/원 residual을 다시 검사할 수 있어 REQ-018을 충족한다.
+반복군의 개별 벡터 비유일성과 외부 mode-shape 비교 제외는 유지한다.
+
+## M2. Backend와 failure lifecycle
+
+FEAST fpm/interval/seed/thread/storage와 내부 수치 한계의 유일 원본은
+[NR C1~C6](numerical-review-controls.md)다. I/O나 CLI에서 parameter override를 만들지 않는다.
+Source N, reduced finite dimension n, prefix count, allocated m0, returned m, validated c,
+public N을 각각 유지한다. 전체 c eigenpairs의 full original free residual/ML Gram/energy 및
+endpoint/count consistency 뒤 첫 N개만 선택한다. Wrong mass·count·residual을 tolerance나
+다른 solver로 우회하지 않는다.
+
+| Failure | Code / exit5 | 보존할 context |
+| --- | --- | --- |
+| Checked CSR/index/capacity 산술 실패 | `eigen-index-overflow` 또는 `invalid-eigen-csr` | n/nnz/N/m0, 실패한 bound와 stage |
+| Allocation 실패 | `eigen-allocation-failed` | allocation 역할·checked requested bytes; N 축소 없음 |
+| FEAST non-success / forbidden retry | `eigen-feast-failed` | raw info, count/solve kind, interval/m0, C5 허용 재시도 여부 |
+| Count/returned m/monotonicity·endpoint mismatch | `eigen-count-inconsistent` 또는 `eigen-endpoint-separation` | actual count history와 마지막 certified bracket |
+| 유한 budget 소진 | `eigen-search-budget-exhausted` | count/solve attempts·마지막 valid bracket; optimization fallback 가능 여부는 C5 그대로 |
+| Significant negative spectrum | `negative-eigenvalue-spectrum` | raw lambda/mu/s, mode rank, C3 threshold |
+| Nonfinite/underflow conversion 또는 invalid frequency | `invalid-eigenvalue-result` | raw scalar·stage·source step |
+| Raw pair/Gram/원 free residual/energy 검증 실패 | `eigenpair-validation-failed` | metric name, observed value, C3 limit, solver column/rank; failed raw values를 accepted result에 넣지 않음 |
+
+위 code는 기존 FailureCategory::kSolver로 전달하며 새로운 exit category를 추가하지 않는다.
+Model/preflight 오류는 [I6](io-input.md#i6-fail-closed-validation과-diagnostics)를 따른다.
+Eigen backend failure의 returned Status는 실패까지의 call history를 message에 round-trip
+decimal/ordinal 순으로 포함한다. 한 leading fatal diagnostic에 history를 부속하고 성공 count
+call에 fictitious error severity를 붙이지 않는다. CLI는 기존 ordered stderr diagnostic 경로로
+반환하며 caller는 Status에서 evidence를 읽을 수 있다. Allocation failure 시 추가 문자열
+allocation을 보장할 수 없는 한계는 기존 best-effort stderr 범위를 따른다.
+
+Public CLI는 기존 `fesa.exe <model.inp>`뿐이다. Output override 부재, `.inp` lexical
+stem/대소문자/여러 dot/path 규칙, same-derived-pair nonblocking exclusive lock와 usage2는
+[공통 lifecycle §7.1](../nonlinear-static-newton-raphson/io.md#71-public-output-names-log-and-lifecycle)을 유지한다.
+
+1. CLI usage validation→lexical output pair→exclusive ownership 뒤 `<stem>_log.txt`를
+   open/truncate한다. Non-Newton eigen은 log에 Newton iteration/FEAST 행을 만들지 않는다.
+   정상 log는 기존 계약대로 zero-byte다. Log open/close failure는 output exit6다.
+2. Input/model/eigen solve와 all-c validation은 candidate에 수행한다. Existing accepted
+   state와 final HDF5는 건드리지 않는다. Controlled failure는 기존 state와 final hash를 보존한다.
+3. Successful candidate를 준비하고 log close 성공을 확인한다. 같은 directory에 exclusive-create
+   private HDF5 candidate를 write/flush/close/reopen/self-check하고 모든 handle을 닫는다.
+4. Final replacement가 성공한 뒤 **이미 준비된 state의 no-fail swap**을 수행한다.
+   Swap에 allocation/validation/fallible callback을 남겨 두지 않는다. 순서는 [E8](formulation-eigen.md#e8-mode-identity-normalization과-상태)다.
+5. Write/flush/close/reopen/self-check/replace 실패는 exit6이며 이전 final/state를 보존한다.
+   Failed candidate는 authoritative가 아니다. 정리는 best effort이고 다른 run의 파일을 지우지 않는다.
+   Current log는 rollback하지 않는다. 잠금 실패는 log/final도 변경하지 않는다.
+
+과거 final이 없으면 controlled failure 후 final도 생성하지 않는다. Directory collision,
+nonregular destination, lock/replacement refusal는 성공으로 처리하지 않는다. Process crash나
+power-loss 전체 원자성을 약속하지 않는다. Reference artifact는 읽기 전용이며 solver의
+새 HDF5/log는 별도 generated output이다. Reference 원본을 덮어쓸 output path는 없다.
+
+## M3. 원본 TXT grammar와 deterministic Value projection
+
+Case `shellNL-eigen-meshfine`의 input/TXT 경로·hash와 logical quantity/family 원본은
+[reference-model](reference-model.md)이다. TMP/CSV 변환·filename alias·추가 provenance 파일을
+reference readiness 조건으로 만들지 않는다. TXT에는 source step이 없으므로 **지정 input의
+유일한 source frequency step Step-2**를 연결한다. ODB storage frame index는 추정하지 않는다.
+
+각 LF/CRLF logical line에서 공백-only 행만 생략한다. 모든 다른 행은 아래 full-match다.
+`ws`는 ASCII space/tab 0개 이상, `ws1`은 1개 이상이며 literal의 대소문자는 정확하다.
+
+```text
+number := [+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[Ee][+-]?[0-9]+)?
+id     := [0-9]+                  # positive checked decimal integer
+row    := ws 'Frame:' ws1 'Mode' ws1 id ':' ws1 'Value' ws '=' ws number
+          ws1 'Freq' ws '=' ws number ws1 '(cycles/time)' ws
+```
+
+Header/footer, BOM, comment, 잘못된 Value/Freq label·추가 token·malformed number는 schema
+failure다. `Value`는 finite binary64로 full conversion하고 overflow/underflow parsing error를
+거부한다. NaN/Inf spelling은 grammar부터 실패한다. `Freq`는 숫자 token 구조만 검사하고
+수치 변환/물리 일치/오차 비교에 사용하지 않는다. 반올림된 Freq로 Value를 재계산하지 않는다.
+같은 숫자의 다른 mode ID는 정상이며 같은 numeric ID의 재등장은 duplicate다.
+
+다음 순서를 tolerance 전에 완료한다.
+
+1. 지정 input/TXT와 O1 eigen HDF5의 존재·source_input_identity·procedure/schema/unit/mass/
+   actual backend를 검사한다. `mass_variant=derived-lumped`, `mass_origin=consistent-moment-row-sum`,
+   normalization mass 및 runtime FEAST metadata가 필수다. 다른 mass의 좋은 오차를 선택하지 않는다.
+2. Input의 유일 source step/N=10을 직접 확인하고 HDF5 source name/요청수/공개수에 대응한다.
+   TXT row count에서 N을 추정하거나 HDF5 내부 c를 공개 모드 수로 사용하지 않는다.
+3. TXT 모든 nonempty row를 먼저 parse하면서 duplicate를 검사한다. Dictionary overwrite
+   또는 malformed-row skip은 금지다. Required identity는 양쪽 모두 정확히 mode1..10이다.
+4. HDF5 `modes`의 field/type/shape/단위/순서와 모든 eigenvalue의 finiteness를 확인한다.
+   Wrong quantity/mass/schema·missing/extra/duplicate/nonfinite를 먼저 실패시킨다.
+5. 유일 source key로 join한 뒤 mode ID ascending으로 projection한다. TXT 행 재배열은
+   허용하지만 HDF5 sort contract 위반은 reader가 재정렬하여 숨기지 않는다.
+
+Projection row는
+`(case_id,source_step_name,mode_id,component=Value,reference_value,fesa_value)`다.
+FESA value는 `/steps/Step-1/eigen/modes.eigenvalue`만 사용한다. Diagnostic all-c table,
+frequencies/vectors 또는 static fields를 fallback으로 읽지 않는다. 현재 component는 scalar
+eigenvalue=`omega^2`, `time^-2`, coordinates=`scalar`, impact=`blocking`이다.
+
+## M4. 판정·보고와 기존 static의 역할
+
+Family는 `(case,source step,modal-frame=mode_id,quantity=eigenvalue,dimension=time^-2,
+coordinates=scalar,impact=blocking)`다. **10개의 singleton family**에
+[common-reference-tolerance](../TOLERANCE.md)를 그대로 적용한다. 각 family의
+`S=max|r|`, `B=0.01S`, near-zero inclusive row branch 또는 5% relative row branch와
+1% relative RMS를 모두 계산한다. 현재 양수 singleton은 실효 mode별1%다.
+S=0이면 exact-zero FESA만 성공이며 불일치는 `zero-reference-scale-nonzero-error`다.
+Source modal frame이 다르면 한 table에 저장되어도 family를 합치지 않는다.
+
+Comparator report는 input/reference/result identity와 freshness evidence, prechecks,
+family/source key/component/count/S, raw r/f/error, 적용 branch·row verdict, RMS/verdict,
+blocking failure와 전체 verdict를 mode order로 남긴다. Undefined zero-scale metric은 named
+state로 표현하고 NaN/Inf나 absolute floor를 넣지 않는다. CSV view가 필요하면 이 projection을
+HDF5에서 추출한 보조 artifact라고 표시하며 공식 output/원본 reference를 대체하지 않는다.
+
+기존 static의 r2 재검증은 [Requirement portfolio](requirements-evidence.md#필수-회귀-포트폴리오와-identity),
+[NR C7](numerical-review-controls.md#c7-승인된-정적-회귀-기준), [C26](numerical-review-cases.md)을 따른다.
+기존 linear source node/static frame와 nonlinear factor-one accepted-state identity를 유지한다.
+U1/U2/U3 length/global blocking, UR1/UR2/UR3 rotation warning-only는 기존 common families다.
+Nonlinear RF1/RF2/RF3·physical spatial RM1/RM2는 source-key/finite/inventory/error 보고를
+유지하는 review-only다. RM3/stress와 eigen vector는 새 external gate가 아니다.
+Internal force/moment equilibrium은 별도의 blocking physical evidence다.
+`shellnl-meshfine-02-s4-final`의 별도 post-closure 역할도 유지한다.
+과거 cache/static 수치를 새 binary의 fresh solve로 표시해서는 안 된다.
+
+## M5. 구현·test obligations와 requirement 연결
+
+아래 표의 `nn` 등 fixture 수를 제외한 threshold는 [NR cases/controls](numerical-review-cases.md)의
+원본을 사용한다. Parser/mapper/schema/comparator의 실제 tests는 Planning/Implementation 소유다.
+
+| Obligation ID | 필수 positive/negative 검증 | NR cases |
+| --- | --- | --- |
+| IO-T01 | 원본 unchanged input의 729 nodes/676 S4, source Step-2/N10, rho2700/t0.5, source options/no-op warnings와 실제 FEAST 선택. S4R source-only 변경도 같은 semantic physical path | MFE-C23 |
+| IO-T02 | 두 material·두께의 element-section-density 연결, missing/duplicate/unresolved/0/negative/NaN/Inf/temperature/dependencies/extra row·field, section/geometry/27-point invalid 거부; static density 부재 허용 | MFE-C06, MFE-C07, MFE-C23, MFE-C26 |
+| IO-T03 | N의 blank/0/negative/fraction/overflow, fields2~7에 nonempty0, eighth empty field, duplicate parameter, unsupported enums/procedure/preload/load/damping/acoustic/mixed/非영 BC 거부 | MFE-C07, MFE-C13, MFE-C23 |
+| IO-T04 | Source labels/instance/set renumbering·중복/모호함, partial rotations/fullfree/fullclamp/drill-only/fully constrained source mask 복원; tiny nonzero director rank 보존·conditioning 실패, n0/N>n 명시 실패 | MFE-C06, MFE-C13, MFE-C14, MFE-C24 |
+| IO-T05 | O1~O5 schema round-trip, input byte identity, N/c/source step/rank/units/actual backend/mass pairing, N vectors의 원 residual·normalization 재현. Near-zero positive/negative/exact0/±threshold 및 lambda conversion 경계 | MFE-C16, MFE-C19, MFE-C24 |
+| IO-T06 | Invalid index/CSR/SPD/parameter/capacity/count/endpoint/NaN/Gram/residual/budget; actual FEAST known zero/repeated/cluster cases의 all-c history와 returned-N 분리. Output diagnostic unavailable와 raw λ 보존 | MFE-C17, MFE-C18, MFE-C19, MFE-C21, MFE-C22 |
+| IO-T07 | 이전 accepted state/final hash를 준비하고 solve/validation/log/lock/write/flush/close/reopen/self-check/replace 실패를 각각 주입. 처음 실행의 실패에서 final 미생성. 성공 final 후 no-fail state swap | MFE-C24 |
+| IO-T08 | TXT reorder/equal Value distinct modes 허용. Missing/extra/duplicate/nonfinite/malformed/wrong field/step/quantity/units/mass/backend/schema 실패를 tolerance 전에 확인. Freq 변화가 Value 판정을 바꾸지 않음 | MFE-C25 |
+| IO-T09 | 공통 policy의 inclusive 1% RMS·5% row 경계와 양옆, generic near-zero \|r\|=B 경계·zero-scale 양성/음성. Singleton이므로5% row pass라도1% RMS fail임을 확인 | MFE-C25 |
+| IO-T10 | Density 없는 기존 linear/nonlinear input·model/static output reader 불변, r2 scale 영향 portfolio를 fresh binary로 재검증. Mode-shape reference 미요구 | MFE-C26, MFE-C27 |
+| IO-T11 | 세 반복의 exact sparse/row/diagnostic order 및 scalar/projector C4 기준. RED→observed failure→GREEN→focused/full MSVC x64 Debug 검증·새 warning 없음·fresh reference identity/hash | MFE-C27 |
+
+Coverage ID 접두사는 모두 `FEM-REQ-MITC4-EIGEN-`다. 아래 표는 requirement 원문을 대체하지
+않고 I/O의 기여와 다른 owner evidence를 구분한다.
+
+| Requirement suffix | I/O 연결·verification obligation |
+| --- | --- |
+| 001 | I2/I4/M1; IO-T01/T03 |
+| 002 | I2/O2 source type와 r2 stabilization identity; IO-T01/T10; physical kernel C01/C08/C12는 해당 owner |
+| 003 | I3/O2 densities; IO-T02 |
+| 004 | I2/I6/M1; IO-T02; geometry oracle C01/C02는 NR 원본 |
+| 005 | M1 consistent snapshot 의미, O2 mass_origin; C01~03 구현 evidence |
+| 006 | M1/O4 node rank와 restored vector; IO-T04; inertia/null C01/C03/C11 |
+| 007 | M1 source/DOF/reduction ordering; IO-T04/T11 |
+| 008 | M1/O4 analytic counts/conditioning, M2; IO-T04/T05; C15 spectrum oracle |
+| 009 | I4/O2 N·n·c/O3 rank; IO-T03/T04/T06 |
+| 010 | O3 stable paired sort/cluster identity, M3 join; IO-T05/T08/T11 |
+| 011 | I4/O2/M2 actual mass/backend discriminant; IO-T01/T05/T06 |
+| 012 | I6/M2/O4 validity and bounded failure; IO-T06/T07 |
+| 013 | O3 vectors/O4 all-c metrics; IO-T05/T06; C11/C16~18 independent evidence |
+| 014 | M1 units/source transformation/O3 replay; IO-T04/T05; C01~05/C08/C11/C20 physics |
+| 015 | I4/I5/O2 source_records; IO-T01/T03 |
+| 016 | I2~I6/M2; IO-T02/T03/T06 |
+| 017 | O1~O5/M3 authoritative additive schema; IO-T05/T08 |
+| 018 | M1/O3 persistent N vectors/source replay; IO-T04/T05; external shapes 제외 |
+| 019 | M2 candidate/commit/log lifecycle; IO-T07 |
+| 020 | M3/M4 Value-only + 별도 static policy; IO-T08/T10 |
+| 021 | O5/M3 full prechecks; IO-T08 |
+| 022 | M4 공통 family/policy/report; IO-T09 |
+| 023 | IO-T11; 실행 계획/RED/GREEN/full 증거는 Planning/Implementation 소유 |
+| 024 | I3/M4 existing static compatibility/portfolio; IO-T10/T11 |
+| 025 | M5 coverage + 동일 r2 handoff; Physics/Release closure 소유권 유지 |
+| 026 | M1 consistent→lumped/O2 mass_origin; C01~05 independent mass evidence |
+| 027 | O2 stabilization_rule/M4 static 역할; IO-T10; C08~12/C26 물리 검증 |
+
+## 정적 감사 evidence
+
+실제 조사 명령은 `Get-Content`, `rg --files`, scoped `rg -n`, `web.open`이었다.
+입력 keyword inventory와 TXT 10개 행을 읽었고 numerical quantity/formulation 계산을
+재실행하지 않았다. 한 번의 `rg docs/shell-surface-pressure/io*.md`는 잘못된 directory/glob로
+exit1이었고 `rg --files docs`로 실제 `docs/shell-surface-pressure-load/io.md`를 확인해
+읽기 전용 대조를 완료했다(exit0). 이 검색 오류는 feature numerical failure가 아니다.
+
+최종 감사 `python -B -` here-script는 exit0으로 owned4 metadata/66개 relative links/
+requirement suffix1..27, reference10 rows/full grammar/finite Value/ID1..10 및 두 원본 SHA-256
+일치를 확인했다. `git diff --check -- docs/mitc4-shell-feast-eigen/io.md
+docs/mitc4-shell-feast-eigen/io-input.md docs/mitc4-shell-feast-eigen/io-schema.md
+docs/mitc4-shell-feast-eigen/io-mapping.md`도 exit0이었다. 아직 untracked인 owned 문서는
+별도 Python whitespace/Markdown table 검사로 확인하며 diff만으로 내용 검증했다고 하지 않는다.
+실제 final audit 결과와 owned hashes는 I/O handoff에 보고한다.
+이는 문서·원본 inventory 검증이며 parser/comparator 구현 test 또는 실제 수치 비교가 아니다.
+CMake/CTest/Harness/FEAST/외부 solver는 이 문서 단계에서 실행하지 않는다.