docs(mitc4): record drilling choices and current verification limits

docs/contracts.md

@@ -95,6 +95,40 @@ Schema·필수 field·dtype·shape·inventory·finite 불일치는 읽기나 비
 누락을 0·NaN·기본 marker로 채워 이용하지 않는다. Mode shape는 응답 변위가 아니며
 frequency와 raw lambda도 다른 양이다. 작은 음의 lambda를 abs/clamp하여 raw 값을 바꾸지 않는다.
 
+## MITC4 drilling 추가 진단
+
+기존 feature/procedure/schema 번호를 유지한다. 새 MITC4 구조 결과는 실제 계산한 state의
+방식을 저장하며 writer가 현재 코드 기본값으로 추정하지 않는다. Beam·Hex8·thermal의
+metadata·dataset·report 계약에는 아래 필드를 추가하지 않는다.
+
+| 위치 | 필드 | 형식과 의미 |
+| --- | --- | --- |
+| `/metadata` attribute | `mitc4_drilling_formulation` | UTF-8 scalar; `direct-initial-director-spring` 또는 `legacy-corotated-twist` |
+| `/metadata` attribute | `drilling_diagnostics_version` | U64LE scalar, 1 |
+| `/steps/Step-1/frames/<k>/global` | `drilling_moment` | F64LE `[3]`, global spatial 내부 복원모멘트 XYZ, force×length |
+| 같은 위치 | `equilibrium_with_drilling` | F64LE `[6]`, raw force XYZ와 raw moment에서 drilling moment를 차감한 XYZ |
+
+기존 `global/equilibrium`이 있는 선형/비선형 정적·HHT의 모든 frame에 두 dataset을
+추가하며 HHT frame0도 포함한다. Eigen에는 두 metadata attribute만 추가하고 가상 평형
+frame을 만들지 않는다. Raw equilibrium의 기존 값·단위·의미는 유지한다.
+
+일반 reader의 두 marker가 모두 없는 옛 파일은 옛 계약으로 읽고 진단은 미상/null이다.
+한 marker만 있거나 알 수 없는 방식/version·필수 dataset 누락·dtype/shape/finite 오류는
+실패다. 모든 applicable frame에서 보정 force는 raw와 같고 보정 moment는 binary64의
+`raw-Mdrill`과 정확히 같아야 한다. 작은 값에 absolute tolerance를 더해 허용하지 않는다.
+새 candidate self-check는 actual state로 marker 필요 여부를 판단하므로 두 marker를
+모두 삭제해도 옛 파일로 오인해 통과시키지 않는다. Write·close·readback·최종 교체 실패는
+이전 최종 HDF5를 보존한다.
+
+기존 MITC4 JSON report는 schema/version·기존 키를 유지하고 `drilling_diagnostics`를
+추가한다. 옛 markerless 결과는 `null`이다. 새 값은 `formulation` 문자열, `version:1`,
+`frames` 배열이다. 각 frame은 `storage_step:"Step-1"`, 정수 `frame_index`,
+숫자 배열 `raw_equilibrium[6]`, `drilling_moment[3]`, `equilibrium_with_drilling[6]`을
+가지며 storage frame 번호 순서로 나열한다. 기존 C++ typed report도 같은 정보를 보존한다.
+Eigen typed 진단의 frames는 빈 배열이며 별도 eigen JSON API를 새로 만들지 않는다.
+비선형 정적의 기존 moment family만 marker에 따라 판정값을 고른다. 선형/HHT 비교기는
+진단을 사전검사하며 기존 family·U blocking/UR warning·수치 verdict를 유지한다.
+
 ## C++ consumer와 비교 도구
 
 공개 interface는 `include/fesa`의 backend-neutral 값과 `Status`/`Result<T>`를 사용한다.