FESADev/docs/engineering-notes.md

# 재현된 함정과 대응

## 작은 직접 스프링에서 중간 곱이 먼저 사라진 경우

양의 subnormal kd에 먼저 `0.5*kd`를 계산하면 energy의 AD 미분에서 force/tangent가
사라질 수 있다. 직접 force와 일정 tangent는 명시적 선형식으로 계산하고 energy는
`0.5*gamma*(kd*gamma)`로 평가한다. 양의 작은 scale을 floor로 올리는 대응은 하지 않는다.
독립 tiny-scale oracle로 energy·force·tangent를 각각 검사했다.

## 관성 null과 drilling primitive가 달라진 경우

Cubic 관성의 실제 null은 정확 SO(3)의 closed null과 다르다. 직접 스프링의 hidden
미분에 후자를 사용하면 실제 관성과 다른 제약을 풀게 된다. 실제 cubic Exp/Jacobian의
normalized solve와 그 미분을 사용한다. 별도 physical force의 null 투영도 정확히0이라고
가정할 수 없어 `n^T(full force-external)`로 canonical drilling scalar를 재구성하지 않는다.
Full mass/null·triad·physical residual gate는 그대로 남으며 이 선택이 기존 D3 실패를 해결하지는 않는다.

## 빈 null과 미평가 scalar를 혼동한 경우

방향 응답을 요청하지 않은 assembly의 canonical scalar가 비어 있다는 이유만으로
all-rotation-fixed/all-fixed 초기화를 거부했던 회귀를 재현했다. Scalar는 실제 admissible
null이 소비할 때 요구한다. 필요한 scalar의 누락/Inf는 계속 실패이며 미평가를0으로 채우지 않는다.
방식이 다른 cache도 typed configuration identity로 구별한다.

## 새 candidate를 옛 markerless 파일로 오인한 경우

호환 reader만으로 새 파일을 검사하면 marker 두 개를 모두 지운 candidate가 옛 파일로
읽힐 수 있다. Writer self-check는 actual state의 진단 존재를 별도로 요구한다.
양 marker/양 dataset 삭제와 write/readback close 실패 주입에서 이전 final bytes 보존을 확인했다.
일반 옛 파일 reader의 null 진단은 유지하며 형식 검사를 위한 tolerance floor를 추가하지 않는다.

## 긴 임시 경로가 출력 충돌처럼 보인 경우

Integration 검증에서 TMP 아래 lease 경로가 260/261자가 되어 `output-busy`가 발생했다.
같은 실행물과 검사 identity에서 긴 TMP는 exit 1, 짧은 TMP는 exit 0이었다.
짧고 고유한 TMP/TEMP로 해당 integration 전체를 다시 실행해 확인했다.
재현 시 실제 점유와 경로 길이를 구분하고 원실패 로그를 남긴다. Lock을 삭제하거나
제품의 실패 조건을 완화하는 방식으로 이 환경 문제를 해결하지 않는다.

## 실행 환경 때문에 검사 범위가 달라진 경우

상속된 GoogleTest filter·sharding과 다른 compiler/build tree는 발견 목록과 실제 실행을
다르게 만들 수 있다. 실행 전 관련 환경을 비우고 discovery identity를 XML·raw 출력과
대조한다. `No tests were found`나 빌드 실패 뒤의 빈 실행을 통과로 기록하지 않는다.
한국어 MSVC의 Ninja include 추적은 configure/build 모두 code page 65001로 맞춘다.

## Link 성공 뒤 DLL에 의존한 경우

개발자의 PATH에 있는 oneAPI/HDF5 runtime으로만 실행되면 link 성공과 배포 가능성을
혼동한다. 실행 파일 옆에 배치된 TBB·MKL·OpenMP·Intel runtime·HDF5 DLL을 확인한다.
Native와 CMake의 설정별 runtime을 따로 확인하며 Debug DLL과 Release DLL을 섞지 않는다.

## 작은 PARDISO 문제의 heap failure

기존 1×1 SPD 반복에서 heap failure가 SpMV 없는 baseline에서도 재현됐다.
Vendor 원인은 확정되지 않았다. 현재 회피는 기본 정책의 해당 크기에만 local 1-thread를
적용하고 TLS 설정을 복원하는 것이다. 보조 100회 성공을 모든 크기·vendor heap 문제의
해결로 확대하지 않는다. 재발하면 matrix 크기·thread 정책·factor/solve/release 수명을 분리해 재현한다.

## 열 RHS 재배치가 상쇄 오류를 숨긴 경우

열 RHS를 두 행곱의 차로 재배치한 후보는 cancellation oracle를 깨뜨려 폐기됐다.
현재 entry association `(c/delta)*(old-g)-k*g`와 row 순서를 보존한다.
Reduced-system scale 대신 큰 constrained 온도가 포함된 full scale로 잔차를 정규화하면
같은 오류를 숨길 수 있다. 독립 signed residual enclosure와 실제 free system의 backward
error를 확인하며 enclosure가 0을 포함한다는 사실만으로 exact-zero를 증명하지 않는다.

## 값의 bit 일치로 충분하지 않았던 최적화

Hex8 paired 연산의 Release ordered-overflow 사례는 값의 bit가 같아도 INVALID FE/MXCSR가
달라 실패했다. Nonfinite 첫 sum에서 기존 checked scalar bridge로 돌아가 원래 실패 계산을
보존한 뒤 관련 검사를 다시 수행했다. Flags clear나 기대값 완화는 해결이 아니다.
연산 순서·예외 상태·오류 전파가 바뀌는지까지 확인한다.

## 중단 로그와 최종 결과를 혼동하는 경우

Accepted increment 로그가 있어도 해석이 끝나지 않으면 writer가 정상 HDF5를 공개하지 않는다.
History는 실행 중 메모리에 있으므로 강제 종료 로그만으로 복구되지 않는다.
이전 최종 HDF5가 남아 있을 수 있어 native exit·새 결과 identity·최종 교체를 함께 확인한다.
Wrapper의 exit와 실제 solver·comparator의 exit도 구분한다. 자식의 정상 종료 후 wrapper가
시간 정보 처리에서 실패했던 사례는 solver 수치 실패와 다르다.

## 외부 비교의 범위를 넓혀 해석하는 경우

변위 CSV에는 속도·가속도·energy가 없을 수 있다. 변위 일치로 이 물리량의 시간 정확도나
관성 일관성을 증명하지 않는다. Warning UR·review RF/RM·diagnostic NT11은 각각의 원래
판정 영향을 보존한다. 합성 HDF5 비교기 검사와 실제 solver의 물리 결과를 구분한다.