♻️ core 지표 nullable 입력 계약 도입 (#15)

## 요약
- 이 PR은 `techr-core`의 nullable 입력 마이그레이션을 시작하는 bottom PR입니다.
- 공개 indicator API의 결측치 계약을 `NaN`이 아닌 `&[Option<f64>]` aligned series로 정리하고, 이후 stacked PR인 `#16`, `#17`이 이 규칙 위에서 stateful/composite 지표를 순차적으로 올립니다.
- 범위는 foundation helper와 단일 시계열 기반 지표 중심이며, `plugin/polars`의 실제 nullable adapter 마이그레이션은 이번 스택에서 제외합니다.

## 배경
- 기존 `core` 함수들은 대부분 dense `&[f64]` 입력을 전제하고 있었습니다.
- 하지만 실제 시계열 처리에서는 결측이 섞인 aligned series를 직접 받을 수 있어야 하고, 표준 라이브러리 성격의 API라면 missing을 `NaN`이 아니라 명시적인 타입으로 다루는 편이 계약이 더 분명합니다.
- 이 스택의 목표는 `techr-core` 전체에서 nullable aligned input을 표준 계약으로 만들고, gap을 건너뛰며 series를 압축하지 않는 일관된 의미론을 정착시키는 것입니다.

## 이 PR에서 하는 일
- `core/src/utils.rs`에 nullable rolling/helper primitive를 추가해 foundation semantics를 먼저 고정합니다.
- `sma`, `ema`, `wma`, `bband`, `env`, `disparity`를 `&[Option<f64>]` 입력 기준으로 전환합니다.
- foundation helper를 사용하는 일부 downstream indicator의 public 시그니처도 같은 계약에 맞게 정렬합니다 (`macd`, `ppo`, `pvo`, `massi`, `sonar` 등).
- 공개 API의 결측치 표현으로 `NaN`을 새로 도입하지 않도록 정리합니다.

## 핵심 규칙
- 출력 길이는 입력 정렬을 그대로 유지합니다.
- rolling 계산은 필요한 lookback window 안에 gap이 있으면 해당 row를 `None`으로 반환합니다.
- recursive smoothing은 gap row에서 output만 `None`이고 내부 상태는 유지합니다.
- valid 값만 따로 압축해서 계산한 뒤 다시 원래 위치에 펴는 방식을 public contract로 사용하지 않습니다.

## 범위 외
- `plugin/polars` nullable adapter 마이그레이션은 후속 작업으로 미룹니다.
- 다만 현재 CI에서 `Polars CI`가 core-only PR에도 실행되기 때문에, 이 PR에는 non-polars 변경에서 `validate`를 성공적인 no-op으로 처리하도록 하는 최소한의 workflow 조정이 함께 포함됩니다.
- 이 workflow 변경은 core nullable 전환 자체의 기능 스코프가 아니라, deferred plugin migration이 현재 스택을 막지 않도록 하는 CI 보정입니다.

## 리뷰 가이드
- 먼저 `core/src/utils.rs`, `sma.rs`, `ema.rs`, `wma.rs`, `bband.rs`, `disparity.rs`를 봐주시면 됩니다.
- 그 다음 downstream 시그니처 정렬과 `.github/workflows/polars-ci.yml` 변경을 확인하시면 충분합니다.
- 이 PR만 `main` 기준으로 리뷰하면 되고, 상위 PR인 `#16`, `#17`은 각각 이 PR을 base로 봐주시면 됩니다.

## 테스트 계획
- [x] `cargo fmt --package techr-core --check`
- [x] `cargo test -p techr-core`
- [x] GitHub Actions `Polars CI`가 non-polars 변경에서 성공적으로 통과하는지 확인

Author: mingi3314

.github/workflows/polars-ci.yml

@@ -2,12 +2,11 @@ name: Polars CI
 
 on:
   pull_request:
-    types: [review_requested, ready_for_review]
+    types: [review_requested, ready_for_review, synchronize]
     paths:
       - ".github/workflows/polars-*.yml"
       - "Cargo.toml"
       - "Makefile"
-      - "core/**"
       - "polars/**"
 
 concurrency:
@@ -18,42 +17,82 @@ permissions:
   contents: read
 
 jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      validate: ${{ steps.filter.outputs.validate }}
+    steps:
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590
+        id: filter
+        with:
+          filters: |
+            validate:
+              - "Cargo.toml"
+              - "Makefile"
+              - "polars/**"
+
   validate:
+    needs: preflight
+    if: ${{ always() }}
     runs-on: ubuntu-latest
     defaults:
       run:
         shell: bash
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - name: Fail if preflight did not succeed
+        if: ${{ needs.preflight.result != 'success' }}
+        run: |
+          echo "preflight job did not succeed: ${{ needs.preflight.result }}"
+          exit 1
+
+      - name: Skip validation for non-polars changes
+        if: ${{ needs.preflight.result == 'success' && needs.preflight.outputs.validate != 'true' }}
+        run: echo "Skipping Polars CI validate job because this PR does not touch Cargo.toml, Makefile, or polars/**."
+
+      - if: ${{ needs.preflight.outputs.validate == 'true' }}
+        uses: actions/checkout@v6
+      - if: ${{ needs.preflight.outputs.validate == 'true' }}
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
-      - uses: astral-sh/setup-uv@v8.0.0
-      - uses: dtolnay/rust-toolchain@stable
+      - if: ${{ needs.preflight.outputs.validate == 'true' }}
+        uses: astral-sh/setup-uv@v8.0.0
+      - if: ${{ needs.preflight.outputs.validate == 'true' }}
+        uses: dtolnay/rust-toolchain@stable
 
       - name: Sync polars dependencies
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         working-directory: polars
         run: uv sync --group dev --no-install-project
 
       - name: Test techr-core
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         run: cargo test -p techr-core
 
       - name: Build local extension for tests
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         working-directory: polars
         run: uv run maturin develop --uv
 
       - name: Test polars package
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         working-directory: polars
         run: uv run pytest
 
       - name: Build wheel and sdist
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         working-directory: polars
         run: uv run maturin build --release --sdist --out dist
 
       - name: Check artifact contents
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         run: python polars/scripts/check_artifacts.py polars/dist
 
       - name: Smoke test built wheel
+        if: ${{ needs.preflight.outputs.validate == 'true' }}
         run: |
           wheel="$(python - <<'PY'
           from pathlib import Path

core/src/indicators/bband.rs

@@ -1,9 +1,8 @@
 use crate::indicators::sma::sma;
-
-use crate::utils::round_scalar;
+use crate::utils::{rolling_mean_stddev_strict, round_scalar};
 
 pub fn bband(
-    data: &[f64],
+    data: &[Option<f64>],
     period: usize,
     sigma: Option<f64>,
 ) -> (Vec<Option<f64>>, Vec<Option<f64>>, Vec<Option<f64>>) {
@@ -12,55 +11,42 @@ pub fn bband(
     (upper_band, center, lower_band)
 }
 
-pub fn bband_middle(data: &[f64], period: usize) -> Vec<Option<f64>> {
+pub fn bband_middle(data: &[Option<f64>], period: usize) -> Vec<Option<f64>> {
     sma(data, period)
 }
 
-pub fn bband_upper(data: &[f64], period: usize, sigma: Option<f64>) -> Vec<Option<f64>> {
+pub fn bband_upper(data: &[Option<f64>], period: usize, sigma: Option<f64>) -> Vec<Option<f64>> {
     let (upper_band, _) = bband_bands(data, period, sigma);
     upper_band
 }
 
-pub fn bband_lower(data: &[f64], period: usize, sigma: Option<f64>) -> Vec<Option<f64>> {
+pub fn bband_lower(data: &[Option<f64>], period: usize, sigma: Option<f64>) -> Vec<Option<f64>> {
     let (_, lower_band) = bband_bands(data, period, sigma);
     lower_band
 }
 
 fn bband_bands(
-    data: &[f64],
+    data: &[Option<f64>],
     period: usize,
     sigma: Option<f64>,
 ) -> (Vec<Option<f64>>, Vec<Option<f64>>) {
-    let mut upper_band = vec![None; data.len()];
-    let mut lower_band = vec![None; data.len()];
-    let mut sum = 0.0;
-    let mut sum_sq = 0.0;
     let sigma = sigma.unwrap_or(2.0);
+    let (means, stddevs) = rolling_mean_stddev_strict(data, period);
 
-    if data.len() < period {
-        return (upper_band, lower_band);
-    }
-
-    for i in 0..data.len() {
-        sum += data[i];
-        sum_sq += data[i] * data[i];
-
-        if i >= period {
-            sum -= data[i - period];
-            sum_sq -= data[i - period] * data[i - period];
-        }
-
-        if i >= period - 1 {
-            let mean = sum / period as f64;
-            let variance = (sum_sq / period as f64) - (mean * mean);
-            let stddev = variance.sqrt();
-            let deviation = sigma * stddev;
-            upper_band[i] = Some(round_scalar(mean + deviation, 8));
-            lower_band[i] = Some(round_scalar(mean - deviation, 8));
-        }
-    }
-
-    (upper_band, lower_band)
+    means
+        .into_iter()
+        .zip(stddevs)
+        .map(|(mean, stddev)| match (mean, stddev) {
+            (Some(mean), Some(stddev)) => {
+                let deviation = sigma * stddev;
+                (
+                    Some(round_scalar(mean + deviation, 8)),
+                    Some(round_scalar(mean - deviation, 8)),
+                )
+            }
+            _ => (None, None),
+        })
+        .unzip()
 }
 
 #[cfg(test)]
@@ -73,7 +59,7 @@ mod tests {
     fn test_bband() {
         let test_cases = vec!["005930", "TSLA"];
         for symbol in test_cases {
-            let input = testutils::load_data(&format!("../data/{}.json", symbol), "c");
+            let input = testutils::load_data_nullable(&format!("../data/{}.json", symbol), "c");
             let (upper, middle, lower) = bband(&input, 20, None);
 
             let expected_upper = testutils::load_expected::<Option<f64>>(&format!(
@@ -109,4 +95,26 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn test_bband_with_interior_gap_invalidates_full_window() {
+        let input = vec![Some(1.0), Some(2.0), None, Some(4.0), Some(5.0)];
+
+        let (upper, middle, lower) = bband(&input, 2, Some(2.0));
+
+        assert_eq!(middle, vec![None, Some(1.5), None, None, Some(4.5)]);
+        assert_eq!(upper, vec![None, Some(2.5), None, None, Some(5.5)]);
+        assert_eq!(lower, vec![None, Some(0.5), None, None, Some(3.5)]);
+    }
+
+    #[test]
+    fn test_bband_full_window_invalidation() {
+        let input = vec![None, Some(2.0), None, Some(4.0)];
+
+        let (upper, middle, lower) = bband(&input, 2, None);
+
+        assert_eq!(upper, vec![None, None, None, None]);
+        assert_eq!(middle, vec![None, None, None, None]);
+        assert_eq!(lower, vec![None, None, None, None]);
+    }
 }

core/src/indicators/cv.rs

@@ -1,4 +1,4 @@
-use crate::indicators::ema::ema;
+use crate::indicators::ema::ema_dense;
 
 pub fn cv(highs: &[f64], lows: &[f64], period: usize) -> Vec<Option<f64>> {
     let mut cv = vec![None; highs.len()];
@@ -9,7 +9,7 @@ pub fn cv(highs: &[f64], lows: &[f64], period: usize) -> Vec<Option<f64>> {
     }
 
     let high_low_diffs: Vec<f64> = highs.iter().zip(lows.iter()).map(|(h, l)| h - l).collect();
-    let ema_high_low_diffs = ema(&high_low_diffs, period);
+    let ema_high_low_diffs = ema_dense(&high_low_diffs, period);
 
     for i in period * 2 - 1..len {
         if let (Some(current_ema), Some(previous_ema)) =

core/src/indicators/disparity.rs

@@ -1,19 +1,23 @@
 use crate::indicators::sma::sma;
 
-pub fn disparity(data: &[f64], period: usize) -> Vec<Option<f64>> {
+pub fn disparity(data: &[Option<f64>], period: usize) -> Vec<Option<f64>> {
     let len = data.len();
     let mut result = vec![None; len];
 
-    if len < period {
+    if len < period || period == 0 {
         return result;
     }
 
     let sma = sma(data, period);
 
     for i in period - 1..len {
+        let Some(value) = data[i] else {
+            continue;
+        };
+
         if let Some(sma_value) = sma[i] {
             if sma_value != 0.0 {
-                result[i] = Some((data[i] / sma_value) * 100.0);
+                result[i] = Some((value / sma_value) * 100.0);
             }
         }
     }
@@ -31,7 +35,7 @@ mod tests {
     fn test_disparity() {
         let test_cases = vec!["005930", "TSLA"];
         for symbol in test_cases {
-            let close = testutils::load_data(&format!("../data/{}.json", symbol), "c");
+            let close = testutils::load_data_nullable(&format!("../data/{}.json", symbol), "c");
             let result = disparity(&close, 20);
             let expected = testutils::load_expected::<Option<f64>>(&format!(
                 "../data/expected/disparity_{}.json",
@@ -46,4 +50,29 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn test_disparity_with_interior_gap_invalidates_window() {
+        let input = vec![Some(1.0), Some(2.0), None, Some(4.0), Some(5.0)];
+        let expected = vec![
+            None,
+            Some(133.33333333333331),
+            None,
+            None,
+            Some(111.11111111111111),
+        ];
+
+        let result = disparity(&input, 2);
+
+        assert_eq!(result, expected);
+    }
+
+    #[test]
+    fn test_disparity_full_window_invalidation() {
+        let input = vec![None, Some(2.0), None, Some(4.0)];
+
+        let result = disparity(&input, 2);
+
+        assert_eq!(result, vec![None, None, None, None]);
+    }
 }

core/src/indicators/efi.rs

@@ -1,4 +1,4 @@
-use crate::indicators::ema::ema;
+use crate::indicators::ema::ema_dense;
 
 pub fn efi(closes: &[f64], volumes: &[f64], period: usize) -> Vec<Option<f64>> {
     let len = closes.len();
@@ -22,7 +22,7 @@ pub fn efi(closes: &[f64], volumes: &[f64], period: usize) -> Vec<Option<f64>> {
                 *efi_val = Some(force_val);
             });
     } else {
-        let ema_result = ema(&force, period);
+        let ema_result = ema_dense(&force, period);
         efi.iter_mut()
             .skip(1)
             .zip(ema_result.into_iter())