quantwave-core 0.10.2

//! Machine-readable convention notes for indicators whose name does not fully
//! determine their formula (quantwave-xnaf / quantwave-l2n4).
//!
//! Some indicator slugs are ambiguous in the wild: "ATR" can mean Wilder's RMA
//! (TA-Lib, TradingView, Wilder 1978) or a plain EMA of true range; "stddev" can
//! be population (`ddof=0`) or sample (`ddof=1`); "roc" can be a percentage or a
//! plain ratio. Prose in a docs page is easy to miss, so the convention actually
//! implemented is recorded here as data and surfaced through the Python
//! `metadata()` / `boundary_info()` discovery API.
//!
//! PROCESS RULE (AGENTS.md): the *source* of every calculation must be recorded
//! and never assumed. `source` below is the recorded provenance for the
//! convention that is actually implemented. Where no authoritative source has
//! been found for the implemented variant, `source` says so explicitly rather
//! than naming a plausible-looking one.

/// One convention that a caller could plausibly get wrong.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
pub struct ConventionNote {
    /// Indicator slug this note applies to (matches `metadata_registry`).
    pub slug: &'static str,
    /// What aspect of the calculation is ambiguous, e.g. "smoothing", "scaling".
    pub aspect: &'static str,
    /// The convention this implementation actually follows.
    pub convention: &'static str,
    /// Widely used conventions this implementation does *not* follow.
    pub differs_from: &'static str,
    /// Recorded provenance for the implemented convention, or an explicit
    /// statement that no source has been established.
    pub source: &'static str,
    /// What a caller should do about it.
    pub guidance: &'static str,
}

/// Slugs whose implemented convention differs from what the bare name implies.
///
/// Keep this sorted by slug. Mirrored on the Python side in
/// `quantwave/_metadata.py::_CONVENTION_NOTES`.
pub const CONVENTION_NOTES: &[ConventionNote] = &[
    ConventionNote {
        slug: "alma",
        aspect: "warmup",
        convention: "During the initial warmup window (< period bars), ALMA normalizes a partial slice of Gaussian weights over available bars, returning finite values immediately from bar 0.",
        differs_from: "Implementations that emit NaN until the full period of bars has accumulated.",
        source: "ProRealTime Arnaud Legoux Moving Average specification.",
        guidance: "To match NaN-warmup implementations, use WarmupPolicy::Nan or mask the first period-1 bars.",
    },
    ConventionNote {
        slug: "atr",
        aspect: "smoothing",
        convention: "Wilder's RMA (alpha = 1/period, SMA-seeded over the first `period` \
                     true ranges, NaN during warmup) by default across all layers (`atr()`, \
                     `Atr` streaming, and Polars `pl.col().ta.atr()`). Both layers support \
                     `smoothing='ema'` for exponential smoothing (alpha = 2/(period+1)).",
        differs_from: "EMA-smoothed ATR variants (alpha = 2/(period+1)) without NaN warmup \
                       when using default smoothing='wilder'.",
        source: "Wilder, J. W. (1978). New Concepts in Technical Trading Systems.",
        guidance: "Default `atr()` matches TA-Lib and TradingView bit for bit across plain and \
                   Polars APIs. Use `smoothing='ema'` if EMA smoothing is explicitly desired.",
    },
    ConventionNote {
        slug: "atr",
        aspect: "seed",
        convention: "Default Wilder RMA uses TA-Lib standard seeding: True Range is undefined on bar 0, \
                     accumulating `period` valid TRs from bars 1..period, emitting first ATR at bar `period` \
                     (period leading NaNs). An explicit `seed='wilder1978'` (or `'classic'`) option implements \
                     Wilder's original 1978 textbook formula with TR[0]=H[0]-L[0] and seeds at bar `period-1` \
                     (period-1 leading NaNs).",
        differs_from: "Classic 1978 textbook Wilder ATR seeds 1 bar earlier (at index period-1 vs period) \
                       with TR[0]=H-L. The relative difference between seeds decays below 1e-9 by bar 400.",
        source: "Wilder, J. W. (1978). New Concepts in Technical Trading Systems; TA-Lib C implementation.",
        guidance: "Use seed='talib' (default) to match TA-Lib and TradingView, or seed='wilder1978' ('classic') \
                   to match the 1978 book formula.",
    },
    ConventionNote {
        slug: "atr_ts",
        aspect: "smoothing",
        convention: "ATR trailing stop built on the EMA-smoothed `Atr` (alpha = 2/(period+1)).",
        differs_from: "TradingView ATR trailing stops, which use Wilder's RMA.",
        source: "NONE RECORDED for the EMA smoothing. Metadata `formula_source` points at \
                 TradingView's ATR page, which specifies Wilder. Inherited from `atr`.",
        guidance: "Stop distances differ from a TradingView-equivalent ATR trailing stop. \
                   See quantwave-xnaf before using for live risk sizing.",
    },
    ConventionNote {
        slug: "keltner",
        aspect: "smoothing",
        convention: "Channel width uses the EMA-smoothed `Atr` (alpha = 2/(period+1)); \
                     the basis is a plain EMA of close.",
        differs_from: "The Investopedia / Chester Keltner formulation and most charting \
                       platforms, which use Wilder-smoothed ATR for the band width.",
        source: "NONE RECORDED for the EMA smoothing. Inherited from `atr`.",
        guidance: "Band widths differ from a Wilder-ATR Keltner channel.",
    },
    ConventionNote {
        slug: "roc",
        aspect: "scaling",
        convention: "Percentage: (price / price[-period] - 1) * 100, matching TA-Lib `ROC`.",
        differs_from: "pandas `pct_change(period)` and TA-Lib `ROCP`, which return the \
                       plain ratio (no x100).",
        source: "TA-Lib ROC/ROCP definitions.",
        guidance: "Use `rocp` for the unscaled ratio. Mixing the two is a silent 100x error.",
    },
    ConventionNote {
        slug: "stddev",
        aspect: "degrees of freedom",
        convention: "Population standard deviation, ddof = 0, matching TA-Lib `STDDEV`.",
        differs_from: "pandas `Series.std()` and numpy `ndarray.std(ddof=1)` defaults, \
                       which use the sample estimator ddof = 1.",
        source: "TA-Lib STDDEV definition.",
        guidance: "Values differ by a factor of sqrt(N / (N - 1)); rescale if you are \
                   reconciling against pandas.",
    },
    ConventionNote {
        slug: "supertrend",
        aspect: "smoothing",
        convention: "Bands are built on the EMA-smoothed `Atr` (alpha = 2/(period+1)).",
        differs_from: "TradingView's SuperTrend, which uses Pine `ta.atr` — Wilder's RMA.",
        source: "NONE RECORDED for the EMA smoothing. Metadata `formula_source` points at \
                 a TradingView SuperTrend script, which uses Wilder. Inherited from `atr`.",
        guidance: "Flip points can differ from a TradingView SuperTrend on the same inputs.",
    },
    ConventionNote {
        slug: "ttm_squeeze",
        aspect: "smoothing",
        convention: "The Keltner leg of the squeeze test uses the EMA-smoothed `Atr`.",
        differs_from: "Implementations that use Wilder-smoothed ATR for the Keltner leg.",
        source: "NONE RECORDED for the EMA smoothing. Inherited from `atr`.",
        guidance: "Squeeze on/off transitions can differ near the threshold.",
    },
    ConventionNote {
        slug: "vpn",
        aspect: "smoothing",
        convention: "The volume-positive-negative threshold uses the EMA-smoothed `Atr`.",
        differs_from: "Implementations that use Wilder-smoothed ATR for the threshold.",
        source: "NONE RECORDED for the EMA smoothing. Inherited from `atr`.",
        guidance: "Threshold crossings can differ from a Wilder-ATR VPN.",
    },
];

/// Convention notes recorded for `slug`, if any.
///
/// ```
/// use quantwave_core::indicators::conventions::convention_notes;
/// let notes = convention_notes("atr");
/// assert_eq!(notes.len(), 1);
/// assert_eq!(notes[0].aspect, "smoothing");
/// ```
pub fn convention_notes(slug: &str) -> Vec<&'static ConventionNote> {
    CONVENTION_NOTES.iter().filter(|n| n.slug == slug).collect()
}

/// Every slug that carries at least one convention note, sorted and deduplicated.
pub fn slugs_with_conventions() -> Vec<&'static str> {
    let mut slugs: Vec<&'static str> = CONVENTION_NOTES.iter().map(|n| n.slug).collect();
    slugs.sort_unstable();
    slugs.dedup();
    slugs
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::indicators::metadata_registry::ALL_REGISTERED;

    #[test]
    fn notes_are_sorted_by_slug() {
        let slugs: Vec<&str> = CONVENTION_NOTES.iter().map(|n| n.slug).collect();
        let mut sorted = slugs.clone();
        sorted.sort_unstable();
        assert_eq!(slugs, sorted, "CONVENTION_NOTES must be sorted by slug");
    }

    #[test]
    fn every_note_targets_a_registered_slug() {
        for note in CONVENTION_NOTES {
            assert!(
                ALL_REGISTERED.iter().any(|r| r.slug == note.slug),
                "convention note for unregistered slug {:?}",
                note.slug
            );
        }
    }

    #[test]
    fn every_note_is_fully_populated() {
        for note in CONVENTION_NOTES {
            for (field, value) in [
                ("aspect", note.aspect),
                ("convention", note.convention),
                ("differs_from", note.differs_from),
                ("source", note.source),
                ("guidance", note.guidance),
            ] {
                assert!(
                    !value.trim().is_empty(),
                    "convention note {:?} has empty {field}",
                    note.slug
                );
            }
        }
    }

    #[test]
    fn atr_family_divergence_is_recorded() {
        // The ATR-composed indicators all inherit the EMA smoothing; if one of
        // them is ever switched to Wilder, this test forces the note to be updated.
        for slug in ["atr_ts", "keltner", "supertrend", "ttm_squeeze", "vpn"] {
            let notes = convention_notes(slug);
            assert_eq!(notes.len(), 1, "expected exactly one note for {slug}");
            assert_eq!(notes[0].aspect, "smoothing");
        }
        let atr_notes = convention_notes("atr");
        assert!(atr_notes.iter().any(|n| n.aspect == "smoothing"));
        assert!(atr_notes.iter().any(|n| n.aspect == "seed"));
    }

    #[test]
    fn lookup_of_unknown_slug_is_empty() {
        assert!(convention_notes("rsi").is_empty());
        assert!(convention_notes("not_a_real_slug").is_empty());
    }
}