schema_version: temporal_data_integrity.v1
contract_id: H003_ANTI_BACKFILL_LOOKAHEAD
harness_file: tools/validate_no_lookahead_bias_v1.py
authority: spec/54_temporal_data_integrity.yaml
created_at: '2026-06-10T23:29:00+09:00'
purpose: >
  백필 데이터와 실시간 데이터의 timestamp/freshness 혼입을 차단한다.
  feature_timestamp가 decision_timestamp를 초과하는 lookahead는 즉시 차단한다.

definitions:
  lookahead_bias: >
    feature 계산에 사용된 데이터의 as_of_date가
    해당 결정이 내려진 decision_timestamp보다 미래인 경우
  backfill_contamination: >
    과거 결정 평가 시 그 시점에 없던 데이터가 소급 적용된 경우

inputs:
  - field: computed_harness_v1.json
    source: Temp/computed_harness_v1.json
    required: true
  - field: GatherTradingData.json
    source: GatherTradingData.json
    required: true

output_fields:
  - name: lookahead_violation_count
    type: int
    description: feature_timestamp > decision_timestamp 건수
  - name: backfilled_after_decision_count
    type: int
    description: 결정 이후 소급 backfill된 데이터 건수
  - name: freshness_violation_tickers
    type: list[str]
    description: freshness 위반 종목 목록
  - name: gate
    type: str
    enum: [PASS, FAIL]

acceptance_criteria:
  - feature_timestamp_lte_decision_timestamp: true
  - backfilled_after_decision_count: 0

hard_gates:
  - gate_id: NO_LOOKAHEAD
    condition: lookahead_violation_count == 0
    on_fail: BLOCK_RELEASE
  - gate_id: NO_BACKFILL_CONTAMINATION
    condition: backfilled_after_decision_count == 0
    on_fail: BLOCK_RELEASE

data_freshness_sla:
  price_data_max_age_hours: 1
  fundamental_data_max_age_days: 30
  macro_data_max_age_hours: 24

owner: data_engineer
lifecycle_state: active
retirement_condition: >
  실시간 스트리밍 파이프라인으로 전환 시 해당 파이프라인 계약으로 교체한다.