# Attention Overlay Architecture

## 목표
공식 문서와 가격 반응으로 생성된 `trade_candidates` 에 대해, 추가적인 **리테일 관심도 / 미디어 확산 / crowding** 신호를 계산해 `overlay_score` 를 부여한다.

## 설계 원칙
1. Overlay는 **후행 확인 신호** 다.
2. Overlay 데이터는 소스별 신뢰도 가중치를 갖는다.
3. Overlay는 결측이 많을 수 있으므로 sparse-friendly 하게 설계한다.
4. Overlay는 독립 장애 도메인으로 분리한다.
5. Overlay feature는 모두 타임스탬프와 source provenance를 남긴다.

## 상위 구조
```text
source adapters
  ├── yahoo_rss_adapter
  ├── youtube_overlay_adapter
  ├── wikimedia_adapter
  ├── google_trends_adapter (experimental)
  └── finra_overlay_loader

normalized events
  ├── headline_mentions
  ├── video_mentions
  ├── pageview_timeseries
  ├── trend_topic_timeseries
  └── crowding_metrics

entity resolution layer
  ├── symbol ↔ company aliases
  ├── symbol ↔ wikipedia page
  ├── symbol ↔ youtube mention matcher
  └── symbol ↔ trend topic map

feature builder
  ├── headline burst
  ├── publisher breadth
  ├── youtube influence score
  ├── pageview shock
  ├── theme heat
  └── crowding stress

overlay scorer
  ├── overlay_score
  ├── overlay_confidence
  ├── hold_extension_hint
  └── add_on_eligibility
```

## 데이터 흐름
1. Phase 2/3에서 `trade_candidates` 생성.
2. overlay adapters가 소스별 raw 수집.
3. entity resolution이 종목 단위로 정규화.
4. feature builder가 observation window 기준 feature 생성.
5. overlay scorer가 각 후보에 score 부여.
6. backtester/live trader가 score를 사용해 ranking, sizing, holding rule 조정.

## 장애 격리
- overlay adapter 실패는 core signal 생성에 영향 주지 않는다.
- 특정 소스 실패 시 나머지 소스로 점수 계산 가능해야 한다.
- 모든 overlay feature가 누락되면 `overlay_mode=disabled` 로 자동 강등한다.

## 추천 배치 순서
- T day 18:30 ET: Yahoo RSS / FINRA 수집 완료
- T day 20:00 ET: Wikimedia/YouTube/Trends 업데이트
- T day 20:30 ET: overlay feature build
- T day 21:00 ET: candidate rerank

## 사용 방식
- `candidate_rank_score = core_score * 0.85 + overlay_score * 0.15`
- 또는 core score bucket 내 tie-breaker
- 또는 holding period extension/trim decision only

v1 권장: **tie-breaker + hold adjustment only**