docs: add klay calibration baseline experiment plan

docs/klay-calibration-experiment/00-plan.md

@@ -0,0 +1,118 @@
+# Klay Calibration Baseline Experiment — Plan
+
+> *Version 0.2 — Draft (mac-first)*
+> 본 문서는 [klay-framework](https://github.com/RataToaster/klay-framework) 리워크의 Phase 1 (Calibration Baseline)을 osu-framework 측에서 진행하기 위한 계획서이다.
+>
+> **업스트림(`ppy/osu-framework`) 머지 비목표. `RataToaster/osu-framework` fork 한정.**
+>
+> **klay-framework 1.0이 macOS 한정이므로, 본 baseline 측정도 macOS에서 1차 채집한다.**
+
+---
+
+## 0. 맥락
+
+`klay-framework/docs/00-background.md` §1.2는 osu!의 `Universal Offset` 단일 자유도가 시각-청각 비대칭 갭 `(D + Δ)`를 해소할 수 없다고 주장한다.
+
+본 실험은 이 주장을 정량 측정으로 입증한다. 측정 결과는 klay-framework Phase 2 (Timing Core) 설계의 baseline 데이터로 활용된다.
+
+---
+
+## 1. 가설
+
+**H1**: 같은 채보에서 X_v(visual offset)를 변화시키지 않는 한, 시각 의존 타격 시점과 청각 의존 타격 시점은 `D + Δ`만큼 분리된다. 단일 슬라이더 X(Universal Offset)를 어떤 값으로 옮겨도 두 분포 사이 거리는 변하지 않는다.
+
+**H2**: visual clock을 audio clock과 분리하여 X_v를 별도로 노출하면 두 분포 사이 거리를 0으로 만들 수 있다.
+
+---
+
+## 2. 측정 환경 (mac-first)
+
+klay-framework 1.0이 macOS 한정이므로, 본 baseline도 macOS에서 1차 채집한다. Windows / Linux 측정은 Phase 2+ 진입 시 참고용으로만 추가.
+
+| 항목 | 값 |
+|---|---|
+| OS | macOS 13+ (Ventura 이상) |
+| CPU | Apple Silicon (M-series) + Intel (대조) |
+| 디스플레이 | 60Hz 외장 + ProMotion 120Hz 내장 |
+| 오디오 | 내장 DAC, 유선, AirPods (AAC) |
+| 마이크 | 내장 마이크 (필요 시) |
+
+osu-framework의 macOS 빌드가 정상 동작해야 함. M-series와 Intel 각각에서 측정 수행.
+
+---
+
+## 3. 측정 변수
+
+| 변수 | 수준 |
+|---|---|
+| X_v | 0, +30, +60, +100 ms |
+| 입력 방식 | 청각 의존, 시각 의존, 혼합 |
+| 오디오 출력 | 내장 스피커, 유선 헤드폰, AirPods (AAC) |
+| 디스플레이 | 60Hz 외장, ProMotion 120Hz 내장 |
+| BPM | 120, 180, 240 |
+| 노트 밀도 | 단노트, 트릴, 스트림 |
+
+---
+
+## 4. 구현 단계
+
+### 4.1 Visual offset 분리 PoC
+
+- `FrameworkSetting` enum에 `VisualOffset` 추가
+- `FrameworkConfigManager.InitialiseDefaults`에 항목 등록
+- `FrameworkSetting.AudioOffset`은 기존 universal offset 그대로 유지 (대조군)
+- visual clock 추상화 도입:
+  - 새 인터페이스 `IVisualClock : IClock` (시각 전용)
+  - 기존 audio-driven 게임플레이 클럭에서 시각 렌더링 경로를 fork
+- 실험용 ruleset 또는 minimal scroll demo로 적용
+
+### 4.2 hit timing 수집
+
+- 모든 hit event에 wall-clock timestamp 기록
+- audio play head, visual scroll head, 입력 event timestamp 동시 기록
+- jsonl 또는 sqlite로 raw log 저장
+- 측정 메타: macOS 버전, CPU, 디스플레이 refresh rate, 오디오 디바이스 UID 함께 기록
+
+### 4.3 분석
+
+- 각 (X_v, 입력 방식, 오디오, 디스플레이) 조합별 hit timing 분포 (히스토그램 + KDE)
+- 시각 / 청각 분포 평균 차이 ± 95% CI
+- X_v 변화에 대한 평균 차이 응답 곱선 → X_v로 차이를 0에 맞출 수 있는지 확인
+- ProMotion 120Hz 환경 vs 60Hz 결과 비교 (Phase 3 predict-ahead 설계 근거)
+
+---
+
+## 5. 산출물
+
+- `docs/klay-calibration-experiment/protocol.md`: 측정 절차 상세 (macOS 디바이스 설정, 테스트 채보 목록, 플레이어 지침 포함)
+- `docs/klay-calibration-experiment/results.md`: 측정 결과 + 그래프
+- `docs/klay-calibration-experiment/results.jsonl` 또는 sqlite: raw 데이터
+- PoC 코드 (이 브랜치 내)
+
+---
+
+## 6. 비목표
+
+- osu!lazer 또는 osu-framework 업스트림 머지
+- 일반 사용자에게 visual offset 슬라이더를 노출하는 사용자 향 기능
+- 본 PoC를 정식 PR로 제안
+- Windows / Linux 측정 (Phase 2+ 진입 시 별도 추가 고려)
+
+본 작업은 klay-framework의 macOS baseline 데이터 확보만을 목적으로 한다.
+
+---
+
+## 7. 후속
+
+본 실험 완료 후 측정 결과를 [klay-framework `docs/02-phases.md`](https://github.com/RataToaster/klay-framework/blob/claude/rework-klay-framework-Gewwr/docs/02-phases.md) Phase 1 항목에 링크하고, klay-framework Phase 2 진입을 승인한다.
+
+---
+
+## 8. 작업 순서 (후속 세션)
+
+1. macOS에서 osu-framework 빌드 검증 (M-series + Intel)
+2. `FrameworkSetting.VisualOffset` 추가 + 디폴트 0
+3. `IVisualClock` 인터페이스 추상화 추가
+4. 게임플레이 클럭에서 visual 경로 분기 + X_v 적용
+5. 로깅 + 측정 프로토콜 구현 (macOS 디바이스 메타 포함)
+6. 실측 (60Hz, 120Hz, 유선, AirPods) + 결과 정리