# Step 2: finite-rotation-state

## 읽어야 할 파일

- `AGENTS.md`
- `docs/ARCHITECTURE.md`
- `docs/ADR.md`
- `docs/nonlinear-static-newton-raphson/formulation.md`
- `docs/nonlinear-static-newton-raphson/numerical-review.md`
- `docs/nonlinear-static-newton-raphson/implementation-plan.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 .harness/build --config Debug
ctest --test-dir .harness/build -C 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 --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
  "-DFESA_GTEST_SOURCE_DIR=$gtestSource" `
  "-DMKL_DIR=$mklDir" `
  "-DTBB_DIR=$tbbDir" `
  "-DHDF5_DIR=$hdf5Dir"
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R "FiniteRotation" --output-on-failure
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Recheck `.harness/config.json` before using default commands.

## 상태 기록

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.