# Step 2: finite-rotation-state

> 과거 개발 계획이다. 아래 작업·상태·예시는 현재 실행 지시가 아니다.
> 현재 구현과 검증 한계는 [기능 요약](../../docs/nonlinear-static-newton-raphson/README.md)을 따른다.

## 읽어야 할 파일

- `AGENTS.md`
- `../../docs/solver-core/README.md`
- `../../docs/solver-core/README.md`
- `../../docs/nonlinear-static-newton-raphson/formulation.md`
- `../../docs/nonlinear-static-newton-raphson/README.md`
- `../../docs/nonlinear-static-newton-raphson/README.md`
- `include/fesa/math/vector3.h`
- `include/fesa/math/matrix.h`
- `tests/unit/math/vector3_test.cpp`
- `tests/unit/math/matrix_test.cpp`
- Step 1 files: `include/fesa/model/model_types.h`, `include/fesa/model/domain.h`

## 이전 Step 전제

Step 1 exposes nonlinear static semantic selection. This Step adds finite rotation math used by nonlinear MITC4 and state recovery.

## 소유 파일

- Create: `include/fesa/elements/finite_rotation.h`
- Create: `src/fesa/elements/finite_rotation.cpp`
- Create: `tests/unit/elements/finite_rotation_test.cpp`
- Modify: `src/fesa/CMakeLists.txt`
- Modify: `tests/CMakeLists.txt`

## 인터페이스

```cpp
namespace fesa {

struct FiniteRotationState {
  Vector3 phi;
  Matrix q;
  Vector3 director;
};

Matrix ExpSkew(const Vector3& phi);
Matrix LeftJacobianSO3(const Vector3& phi);
Matrix InverseTransposeLeftJacobianSO3(const Vector3& phi);
Result<FiniteRotationState> MakeFiniteRotationState(
    const Vector3& phi, const Matrix& initial_frame);
Result<FiniteRotationState> ApplyGlobalRotationIncrement(
    const FiniteRotationState& committed,
    const Vector3& delta_phi,
    const Matrix& initial_frame);

}  // namespace fesa
```

## RED

Add tests first.

- `NSNR-ROT-001`: zero `phi` returns `Q0` and `director=Q0*e3`.
- `NSNR-ROT-002`: finite `phi` satisfies `Q=exp(phi^)Q0`, `Q^T Q=I`, `det(Q)=1`, `director=Qe3`.
- `NSNR-ROT-003`: update uses `Q+ = exp((phi + delta_phi)^)Q0`.
- `NSNR-ROT-004`: principal branch margin `sqrt(epsilon_double)` rejects ambiguous rotations near `pi`.
- `NSNR-ROT-005`: `LeftJacobianSO3` and inverse-transpose are finite and derivative-consistent for small, medium, and near-branch-safe rotations.
- `NSNR-ROT-006`: nonfinite rotation components fail with `invalid-accepted-state` or the Step-introduced finite-rotation diagnostic.

Run:

```powershell
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug -R "FiniteRotation" --output-on-failure
```

Expected: tests fail because the rotation module does not exist. Unexpected pass stops.

## GREEN

Implement the SO(3) helper functions with finite checks and principal-branch validation. Use existing FESA math types and keep MKL/vendor types out of public headers.

## VERIFY

```powershell
cmake --preset windows-msvc-ninja-debug
cmake --build --preset windows-msvc-ninja-debug
ctest --preset windows-msvc-ninja-debug -R "FiniteRotation" --output-on-failure
ctest --preset windows-msvc-ninja-debug --show-only=json-v1
ctest --preset windows-msvc-ninja-debug --output-on-failure
```

Use the ignored 과거 검증 자료(정리됨) preset contract. The Harness process must inherit VsDevCmd x64 and `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`, and `HDF5_DIR` from its parent launch environment.

## 상태 기록

Update only Step 2 status and summary/error/blocked payload. Executor owns timestamps, commits, retry, and advancement.

## 금지사항

- Do not normalize invalid rotation matrices to make tests pass. 이유: invalid nonlinear state must fail closed.
- Do not add element residual or tangent code here. 이유: this Step owns only finite rotation state.
- Do not expose backend/vendor types. 이유: public solver core must remain backend-neutral.