Stage 187: α acceleration signal

core/config.py

@@ -38,16 +38,21 @@ class MetricConfig:
 
     ``direction``       — which way is bad (drives the directional Δ).
     ``weight``          — relative weight inside the Δ aggregate.
-    ``feeds_stability`` — included in the ψ (stability) computation.
-    ``feeds_anomaly``   — included in the ξ (anomaly) computation.
-    ``latency_target``  — if set, the metric contributes to γ against this SLA.
-    ``coherence_target``— if set, distance from this target contributes to κ.
+    ``feeds_stability``   — included in the ψ (stability) computation.
+    ``feeds_anomaly``     — included in the ξ (anomaly) computation.
+    ``feeds_acceleration``— included in the α (acceleration / second
+                             derivative) computation. Off by default
+                             so legacy configs are unaffected by
+                             Stage 187.
+    ``latency_target``    — if set, the metric contributes to γ against this SLA.
+    ``coherence_target``  — if set, distance from this target contributes to κ.
     """
     name: str
     direction: str
     weight: float = 1.0
     feeds_stability: bool = False
     feeds_anomaly: bool = True
+    feeds_acceleration: bool = False
     latency_target: Optional[float] = None
     coherence_target: Optional[float] = None
 
@@ -69,6 +74,7 @@ class MetricConfig:
             weight=float(d.get("weight", 1.0)),
             feeds_stability=bool(d.get("feeds_stability", False)),
             feeds_anomaly=bool(d.get("feeds_anomaly", True)),
+            feeds_acceleration=bool(d.get("feeds_acceleration", False)),
             latency_target=_opt_float(d.get("latency_target")),
             coherence_target=_opt_float(d.get("coherence_target")),
         )
@@ -79,6 +85,7 @@ class MetricConfig:
             "weight": self.weight,
             "feeds_stability": self.feeds_stability,
             "feeds_anomaly": self.feeds_anomaly,
+            "feeds_acceleration": self.feeds_acceleration,
             "latency_target": self.latency_target,
             "coherence_target": self.coherence_target,
         }

core/drift.py

@@ -25,6 +25,11 @@ DEFAULT_DRIFT_WEIGHTS = {
     "xi": 0.25,
     "gamma": 0.15,
     "kappa": 0.15,
+    # Stage 187 — α (acceleration / second derivative). Default
+    # weight 0 so the signal is fully opt-in via entity_type
+    # config — adding the signal must not silently shift drift
+    # scores on any pre-existing tenant.
+    "alpha": 0.0,
 }
 DEFAULT_SEVERITY_THRESHOLDS = {
     "critical": 0.75,
@@ -47,12 +52,14 @@ def drift_score(signals: Dict[str, float], weights: Dict[str, float] = None) ->
     xi = signals.get("xi", 0.0)
     gamma = signals.get("gamma", 0.0)
     kappa = signals.get("kappa", 1.0)
+    alpha = signals.get("alpha", 0.0)         # Stage 187
     return (
         w.get("delta", DEFAULT_DRIFT_WEIGHTS["delta"]) * delta +
         w.get("psi", DEFAULT_DRIFT_WEIGHTS["psi"]) * (1.0 - psi) +
         w.get("xi", DEFAULT_DRIFT_WEIGHTS["xi"]) * xi +
         w.get("gamma", DEFAULT_DRIFT_WEIGHTS["gamma"]) * gamma +
-        w.get("kappa", DEFAULT_DRIFT_WEIGHTS["kappa"]) * (1.0 - kappa)
+        w.get("kappa", DEFAULT_DRIFT_WEIGHTS["kappa"]) * (1.0 - kappa) +
+        w.get("alpha", DEFAULT_DRIFT_WEIGHTS["alpha"]) * alpha
     )
 
 

core/pipeline.py

@@ -36,6 +36,7 @@ from .config import HIGHER_IS_WORSE, EntityTypeConfig
 from .decisions import DecisionItem, recommendation_for_issue
 from .drift import DriftIssue, drift_score, severity_from_score
 from .signals import (
+    acceleration_alpha,
     anomaly_xi,
     health_omega,
     latency_gamma,
@@ -124,6 +125,10 @@ def _entity_states(entity_id: str, obs: List[Observation],
         psi_candidates: List[float] = []
         gamma_candidates: List[float] = []
         coherence_violations: List[float] = []
+        # Stage 187 — α (acceleration) candidates. Stays empty for
+        # legacy configs (no metric has feeds_acceleration=True), so
+        # alpha is 0.0 and nothing about existing behaviour shifts.
+        alpha_candidates: List[float] = []
 
         for m in config.metrics:
             series = history[m.name]
@@ -145,6 +150,11 @@ def _entity_states(entity_id: str, obs: List[Observation],
                 xi_candidates.append(anomaly_xi(value, hist))
             if m.feeds_stability and len(recent) >= 2:
                 psi_candidates.append(stability_psi(recent))
+            if getattr(m, "feeds_acceleration", False):
+                baseline_window = hist[:cut]
+                if len(baseline_window) >= 3 and len(recent) >= 3:
+                    alpha_candidates.append(acceleration_alpha(
+                        baseline_window, recent, m.direction))
             if m.latency_target is not None:
                 gamma_candidates.append(latency_gamma(value, m.latency_target))
             if m.coherence_target is not None:
@@ -159,10 +169,15 @@ def _entity_states(entity_id: str, obs: List[Observation],
         gamma = max(gamma_candidates) if gamma_candidates else 0.0
         kappa = (1.0 - safe_mean(coherence_violations)) if coherence_violations else 1.0
         kappa = max(0.0, min(1.0, kappa))
+        # Stage 187 — α (acceleration). Max across all opted-in
+        # metrics: a single accelerating metric is enough to fire,
+        # mirroring how ξ (anomaly) and γ (latency) aggregate.
+        alpha = max(alpha_candidates) if alpha_candidates else 0.0
         omega = health_omega(delta, psi, xi, gamma, kappa)
 
         signals = {"delta": delta, "psi": psi, "xi": xi,
-                   "gamma": gamma, "kappa": kappa, "omega": omega}
+                   "gamma": gamma, "kappa": kappa, "alpha": alpha,
+                   "omega": omega}
         score = drift_score(signals, weights=config.signal_weights)
 
         # confidence grounded in how much history we have (Stage 1 improvement)
@@ -215,6 +230,22 @@ def _evidence_for_state(state: Dict, config: EntityTypeConfig) -> List[Dict]:
             "truth_type": "soft_truth",
             "confidence": state["confidence"],
         })
+    # Stage 187 — α (acceleration). Only surfaces when at least one
+    # metric is opted in AND it's actually accelerating. The 0.5
+    # threshold means the recent slope is ≥ 2× baseline slope before
+    # it shows up as evidence — that's a meaningful "death-spiral"
+    # signal, not noise on a near-flat baseline.
+    if sig.get("alpha", 0.0) >= 0.5:
+        evidence.append({
+            "label": "acceleration",
+            "summary": (
+                f"Acceleration α={sig['alpha']} — the rate of "
+                "degradation is itself increasing (recent slope > "
+                "baseline slope in the adverse direction)."
+            ),
+            "truth_type": "hard_truth",
+            "confidence": state["confidence"],
+        })
     return evidence
 
 
@@ -267,7 +298,8 @@ def run_pipeline(observations: List[Observation],
                 f"health Ω={state['signals']['omega']}. Signals — "
                 f"Δ={state['signals']['delta']}, ψ={state['signals']['psi']}, "
                 f"ξ={state['signals']['xi']}, γ={state['signals']['gamma']}, "
-                f"κ={state['signals']['kappa']}."
+                f"κ={state['signals']['kappa']}, "
+                f"α={state['signals'].get('alpha', 0.0)}."
             ),
             evidence=evidence,
         )

core/signals.py

@@ -81,3 +81,78 @@ def health_omega(delta: float, psi: float, xi: float, gamma: float, kappa: float
         "coherence": 1.0,
     }
     return weighted_geometric_mean(values, weights)
+
+
+# --- α (alpha) — trend acceleration -----------------------------------
+#
+# Stage 187. The other 5 signals catch: "X% worse than baseline" (δ),
+# "today spiked" (ξ), "missed SLA" (γ), "stability dropped" (ψ),
+# "coherence dropped" (κ). None of them catch the second derivative —
+# "the RATE of degradation is itself accelerating." A customer dropping
+# 2%/wk is bad; one dropping 2 → 5 → 9%/wk is on a death spiral and
+# needs a different intervention than the steady decliner.
+#
+# Implementation:
+#   1. Fit a least-squares linear slope to the baseline window.
+#   2. Fit a least-squares linear slope to the recent window.
+#   3. If recent slope is adverse AND its magnitude exceeds the
+#      baseline slope, output the magnitude ratio normalised into
+#      [0, 1] via 1 - 1/(1+excess).
+#
+# Returns 0.0 (no acceleration) when:
+#   - either window has < 3 points (slope undefined),
+#   - the recent slope direction is NOT adverse,
+#   - the recent slope magnitude doesn't exceed baseline.
+
+
+def _linear_slope(values: List[float]) -> float:
+    """Least-squares slope on uniformly-spaced x. Returns 0 if the
+    series is too short or has zero spread on x."""
+    n = len(values)
+    if n < 2:
+        return 0.0
+    xs = list(range(n))
+    x_mean = (n - 1) / 2.0
+    y_mean = sum(values) / n
+    num = sum((xs[i] - x_mean) * (values[i] - y_mean) for i in range(n))
+    den = sum((xs[i] - x_mean) ** 2 for i in range(n))
+    if den < 1e-12:
+        return 0.0
+    return num / den
+
+
+def acceleration_alpha(baseline: List[float],
+                        recent: List[float],
+                        direction: str) -> float:
+    """The α signal. ``direction`` is "higher_is_worse" or
+    "lower_is_worse" — fires only when the recent slope is in the
+    adverse direction AND steeper than the baseline slope.
+
+    Output ∈ [0, 1]:
+        excess = max(0, |recent| - |baseline|) / max(|baseline|, eps)
+        alpha  = 1 - 1/(1 + excess)
+    excess=0 → 0; excess=1 (recent is 2× baseline) → 0.5;
+    excess→∞ → 1. Saturates softly so one-off outliers don't max out.
+    """
+    if len(baseline) < 3 or len(recent) < 3:
+        return 0.0
+    b_clean = [v for v in baseline if v is not None]
+    r_clean = [v for v in recent if v is not None]
+    if len(b_clean) < 3 or len(r_clean) < 3:
+        return 0.0
+    s_base = _linear_slope(b_clean)
+    s_rec = _linear_slope(r_clean)
+    if direction == "higher_is_worse":
+        adverse_recent = s_rec > 0
+    elif direction == "lower_is_worse":
+        adverse_recent = s_rec < 0
+    else:
+        return 0.0
+    if not adverse_recent:
+        return 0.0
+    abs_base = abs(s_base)
+    abs_rec = abs(s_rec)
+    if abs_rec <= abs_base:
+        return 0.0
+    excess = (abs_rec - abs_base) / max(abs_base, 1e-6)
+    return 1.0 - 1.0 / (1.0 + excess)

verticals/pharma/config.yaml

@@ -18,13 +18,22 @@ entity_types:
     baseline_window: 14
     baseline_lag: 7
     recent_window: 14
+    # Stage 187 — α (acceleration) weight 0.10 for pharmacies. A
+    # pharmacy losing prescription fills faster every week is at
+    # acute risk; weighted 10% of the drift score.
+    signal_weights:
+      alpha: 0.10
     metrics:
       # δ — drop in prescription fill (the pharmacy's revenue + duty
       # of care signal).
+      # α — Stage 187: prescription fill accelerating downward is a
+      # death-spiral signal — customers are leaving for a competitor
+      # pharmacy faster every week, not just slowly drifting.
       prescription_fill_count:
         direction: lower_is_worse
         weight: 0.25
         feeds_anomaly: true
+        feeds_acceleration: true
       # ψ — spike in rejected scripts (insurance / formulary issues
       # or a system fault).
       rejection_rate:

verticals/retail/config.yaml

@@ -21,6 +21,12 @@ entity_types:
     baseline_window: 14
     baseline_lag: 7
     recent_window: 14
+    # Stage 187 — α (acceleration) weight 0.10 for retail stores.
+    # Conversion accelerating downward is a real death-spiral signal
+    # in this vertical, so the 6th signal contributes ~10% of the
+    # drift score. Default 0.0 stays untouched on legacy verticals.
+    signal_weights:
+      alpha: 0.10
     metrics:
       # δ — sales vs baseline. The headline retail signal.
       sales:
@@ -47,11 +53,15 @@ entity_types:
         feeds_stability: true
         latency_target: 4.0               # SLA: 4 min avg checkout
       # κ — conversion volatility (footfall → buyer ratio).
+      # α — Stage 187: conversion accelerating downward = acute
+      # death-spiral signal. A chain dropping conversion 1pp/wk
+      # is bad; one dropping 1 → 3 → 6pp/wk needs intervention now.
       conversion:
         direction: lower_is_worse
         weight: 0.20
         feeds_anomaly: true
         feeds_stability: true
+        feeds_acceleration: true
         coherence_target: 0.18            # expected conversion 18%
 
   distribution: