add documents

docs/engineering-notes.md

@@ -0,0 +1,58 @@
+# 재현된 함정과 대응
+
+## 긴 임시 경로가 출력 충돌처럼 보인 경우
+
+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의 물리 결과를 구분한다.