feat: math core v3 engine upgrade

services/aggregation/signal_propagation.py

@@ -378,3 +378,74 @@ def build_pattern_weighted_signals(
         ))
 
     return signals
+
+
+# ---------------------------------------------------------------------------
+# v3 — Correlation-shrunk competitive propagation (Requirements: 10.1–10.5)
+# ---------------------------------------------------------------------------
+
+_V3_MAX_NETWORK_DISTANCE = 3
+
+
+def compute_shrunk_correlation(
+    rho_rolling: float,
+    n_observations: int,
+    same_sector: bool,
+) -> float:
+    """Compute shrinkage-adjusted correlation.
+
+    Shrinks the rolling correlation toward a sector-aware prior using a
+    Bayesian-style weight of n / (n + 30).
+
+    rho_prior = 0.30 if same_sector else 0.10
+    rho_shrunk = (n/(n+30)) × rho_rolling + (30/(n+30)) × rho_prior
+    rho_effective = max(rho_shrunk, 0)
+
+    Args:
+        rho_rolling: Rolling pairwise correlation estimate.
+        n_observations: Number of observations used to compute rho_rolling.
+        same_sector: Whether the two securities are in the same sector.
+
+    Returns:
+        Non-negative shrinkage-adjusted correlation (rho_effective).
+
+    Requirements: 10.1, 10.2
+    """
+    rho_prior = 0.30 if same_sector else 0.10
+    n = n_observations
+    rho_shrunk = (n / (n + 30)) * rho_rolling + (30 / (n + 30)) * rho_prior
+    rho_effective = max(rho_shrunk, 0.0)
+    return rho_effective
+
+
+def compute_competitive_llr(
+    llr_source: float,
+    rho_effective: float,
+    d_network: int,
+    pattern_confidence: float,
+) -> float:
+    """Compute competitive LLR with graph attenuation.
+
+    attenuation = rho_effective × exp(-0.85 × d_network)
+    LLR_competitive = clamp(llr_source × attenuation × pattern_confidence, -1.25, 1.25)
+
+    When d_network > 3 → attenuation = 0 → LLR_competitive = 0
+
+    Args:
+        llr_source: Source signal LLR value.
+        rho_effective: Shrinkage-adjusted correlation (non-negative).
+        d_network: Graph distance between source and target (integer >= 1).
+        pattern_confidence: Confidence of the historical pattern in [0, 1].
+
+    Returns:
+        Competitive LLR clamped to [-1.25, 1.25]. Returns 0.0 when
+        d_network exceeds max distance of 3.
+
+    Requirements: 10.3, 10.4, 10.5
+    """
+    if d_network > _V3_MAX_NETWORK_DISTANCE:
+        return 0.0
+
+    attenuation = rho_effective * math.exp(-0.85 * d_network)
+    llr_competitive = llr_source * attenuation * pattern_confidence
+    return max(-1.25, min(1.25, llr_competitive))