schema_version: "postgresql_history_contract_v1"
title: "PostgreSQL History-First Operating Contract"
purpose: "시장 원천, 팩터 버전, 최종 팩터 출력, 엔진 의사결정, 시장-엔진 괴리를 PostgreSQL에 누적한다."

canonical_principles:
  - "PostgreSQL is the canonical operating history store."
  - "Excel workbooks and Google Apps Script are not operational sources of truth."
  - "All derived analysis must be traceable to a versioned DB snapshot."
  - "Factor outputs and decision outputs must carry provenance and source_version."

domains:
  market_raw_history:
    description: "시장 원천 데이터 이력"
    key_fields:
      - source_id
      - observed_at
      - source_name
      - instrument_id
      - field_name
      - field_value
      - unit
  factor_version_history:
    description: "공식/임계값/팩터 버전 이력"
    key_fields:
      - factor_id
      - factor_version
      - effective_from
      - effective_to
      - formula_id
      - source_version
  factor_output_history:
    description: "최종 팩터 산출 이력"
    key_fields:
      - factor_output_id
      - observed_at
      - factor_id
      - factor_version
      - output_value
      - output_gate
      - source_version
  decision_result_history:
    description: "엔진 최종 판단/실행 결과 이력"
    key_fields:
      - decision_id
      - decided_at
      - instrument_id
      - action
      - gate
      - score
      - source_version
  market_vs_engine_gap_history:
    description: "시장 실측과 엔진 결과 괴리 이력"
    key_fields:
      - gap_id
      - observed_at
      - instrument_id
      - metric_name
      - market_value
      - engine_value
      - gap_value
      - gap_pct
      - source_version

operating_rules:
  - "New history rows are append-only except for explicit correction rows."
  - "Correction rows must reference corrected_row_id and correction_reason."
  - "Factor recomputation must preserve previous outputs in history."
  - "No report should read directly from Excel/GAS when PostgreSQL snapshot is available."

implementation_targets:
  - "src/quant_engine/postgresql_history_store_v1.py"
  - "tools/build_postgresql_history_snapshot_v1.py"
  - "tools/validate_postgresql_history_contract_v1.py"
  - "docs/POSTGRESQL_HISTORY_FIRST_OPERATING_MODEL.md"