# Labeling and Dataset Specification

## 1. 목적

Phase 4 백테스터와 모델 학습을 위해 **누수 없는 event-level labels**를 생성한다.

## 2. 핵심 정의

### filing timestamp
SEC filing 또는 허용된 원문이 실제로 공개된 시각.

### reaction date
시장 참여자가 해당 이벤트를 정규장 가격으로 반영한 첫 거래일.

규칙:
- 장 시작 전 공개 → 같은 거래일이 reaction date
- 정규장 중 공개 → 같은 거래일이 reaction date
- 장 종료 후 공개 → 다음 거래일이 reaction date

### entry convention
Phase 3에서는 아래 2개만 공식 지원:
- `next_open_after_reaction_close`
- `dayplus1_close`

기본 백테스트/학습 convention:
- `next_open_after_reaction_close`

## 3. 라벨 종류

### return labels
- `fwd_return_1d`
- `fwd_return_3d`
- `fwd_return_5d`

정의:
- entry price 대비 N 거래일 후 종가 수익률

### binary labels
- `hit_pos_1r_within_3d`
- `hit_neg_1r_within_3d`
- `close_up_after_3d`
- `close_up_after_5d`

### path labels
- `mfe_3d`
- `mae_3d`
- `mfe_5d`
- `mae_5d`

### timing labels
- `bars_to_mfe_3d`
- `bars_to_mae_3d`
- `days_to_peak_close_5d`

## 4. Entry/Exit price 정의

### 기본 엔트리
`next_open_after_reaction_close`
- entry_date = reaction_date 다음 거래일
- entry_price = entry_date 공식 open

### 보조 엔트리
`dayplus1_close`
- entry_date = reaction_date 다음 거래일
- entry_price = entry_date close

### 라벨용 가상 exit
- N일 종가 exit
- stop/target path 계산용 intraday high/low 사용 가능

## 5. Stop/Target path rules

연구용 path label에만 사용:
- risk unit `R`는 entry와 initial stop 차이
- initial stop 기본값은 `reaction_day_low` 또는 `1 ATR`, 둘 다 보관 가능

필수 저장:
- `risk_model_name`
- `initial_stop_price`
- `initial_r_value`

## 6. 결측 처리

- horizon 기간 내 상장폐지/거래정지 발생 시 `label_status = truncated`
- 데이터 누락 시 `label_status = unavailable`
- 반응일 자체가 형성되지 않으면 record drop 금지, `invalid_event_for_labeling = true`

## 7. Dataset splits

### 기본 split
- train: 과거 구간
- validation: 그 다음 연속 구간
- test: 가장 최근 연속 구간

### 금지
- 랜덤 split
- 동일 issuer/event family가 train/test에 동시에 섞이는 split

### 권장
- walk-forward split
- earnings season 단위 성능 분리
- bull/bear regime 분리

## 8. Snapshot 생성 규칙

스냅샷은 immutable artifact여야 함.

필수 메타데이터:
- snapshot_id
- created_at
- code_commit_hash
- feature_version
- parser_version
- label_version
- split_policy
- included_sources

출력 형식:
- `datasets/snapshots/<snapshot_id>/train.parquet`
- `datasets/snapshots/<snapshot_id>/valid.parquet`
- `datasets/snapshots/<snapshot_id>/test.parquet`
- `manifest.json`

## 9. QA 필수 점검

- reaction date가 filing timestamp와 일관적인가
- entry_date가 거래일 달력상 유효한가
- forward window에 future leakage가 없는가
- delisting/halts 처리 규칙이 일관적인가
- label 분포가 특정 연도/섹터에 치우치지 않는가