margin 0.9.17__tar.gz → 0.9.18__tar.gz

{margin-0.9.17/margin.egg-info → margin-0.9.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.17
+Version: 0.9.18
 Summary: Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened.
 Author: Cope Labs LLC
 License: MIT

{margin-0.9.17 → margin-0.9.18}/margin/fingerprint.py

@@ -126,23 +126,31 @@ class Fingerprint(dict):
 
     def sigma(self, component: str, value: float) -> float:
         """
-        Normalize ``value`` against the fingerprint's empirical mean.
+        Z-score of ``value`` against the fingerprint's empirical distribution.
 
-        Returns ``(value − mean) / |mean|``.
+        Returns ``(value − mean) / std``  (standard z-score).
 
-        Positive = above session baseline; negative = below.  Used to
-        convert a raw domain measurement into a cross-session comparable
-        signal before passing it to ``Controller.step()``.
+        Using ``std`` as denominator is correct for cross-session normalization.
+        ``|mean|`` would only be appropriate when the coefficient of variation
+        (std/|mean|) is small; for high-CV components (e.g. ``std=0.498``,
+        ``mean=0.070``, CV=7.1) it amplifies by 7×, turning a normal ±0.07
+        swing into ±1.0 and saturating the controller.
 
-        Returns ``value`` unchanged when the stored mean is zero
-        (no finite normalization is possible).
+        Falls back to ``(value − mean) / |mean|`` when ``std`` is zero (constant
+        window or not yet stored), and returns ``value`` unchanged when both
+        ``mean`` and ``std`` are zero.
 
         Example::
 
             metric = fp.sigma("recovery_ratio", cq.recovery_ratio)
             alpha, reason = ctrl.step(alpha, metric)
         """
-        mean = self.get(component, {}).get("mean", 0.0)
+        stats = self.get(component, {})
+        mean = stats.get("mean", 0.0)
+        std = stats.get("std", 0.0)
+        if std != 0.0:
+            return (value - mean) / std
+        # std=0: constant distribution — fall back to relative deviation
         if mean == 0.0:
             return value
         return (value - mean) / abs(mean)

{margin-0.9.17 → margin-0.9.18/margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.17
+Version: 0.9.18
 Summary: Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened.
 Author: Cope Labs LLC
 License: MIT

{margin-0.9.17 → margin-0.9.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.17"
+version = "0.9.18"
 description = "Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened."
 readme = "README.md"
 license = {text = "MIT"}

{margin-0.9.17 → margin-0.9.18}/tests/test_controller.py

@@ -552,14 +552,28 @@ class TestFingerprintSigma:
 
     def test_negative_mean(self):
         fp = Fingerprint(stats={"rr": {"mean": -2.0, "std": 0.5, "n": 10, "trend": "STABLE"}})
-        # (value - mean) / |mean| = (-1.0 - (-2.0)) / 2.0 = 0.5
-        assert fp.sigma("rr", -1.0) == pytest.approx(0.5)
+        # z-score: (value - mean) / std = (-1.0 - (-2.0)) / 0.5 = 2.0
+        assert fp.sigma("rr", -1.0) == pytest.approx(2.0)
 
     def test_missing_component_returns_value(self):
         fp = _make_fp([1.0] * 10)
         # missing → mean=0.0 → returns value unchanged
         assert fp.sigma("missing", 0.7) == pytest.approx(0.7)
 
+    def test_uses_std_not_mean_as_denominator(self):
+        # Regression: Build #29 failure — high-CV component (std=0.498, mean=0.070)
+        # Old formula: (value - mean) / |mean| = 0.07 / 0.07 = 1.0 (7× amplification)
+        # New formula: (value - mean) / std   = 0.07 / 0.498 ≈ 0.141 (sensible z-score)
+        fp = Fingerprint(stats={"rr": {"mean": 0.070, "std": 0.498, "n": 98}})
+        result = fp.sigma("rr", 0.14)
+        assert result == pytest.approx((0.14 - 0.070) / 0.498, rel=1e-4)  # z-score
+        assert abs(result) < 0.2  # not ±1.0 (the bang-bang range)
+
+    def test_std_zero_falls_back_to_mean_relative(self):
+        # Constant distribution: std=0 → fall back to (value-mean)/|mean|
+        fp = Fingerprint(stats={"rr": {"mean": 1.0, "std": 0.0, "n": 5}})
+        assert fp.sigma("rr", 1.5) == pytest.approx(0.5)  # (1.5-1.0)/1.0
+
 
 class TestFingerprintPrecomputedPercentiles:
     """Fingerprints from Monitor.fingerprint() now include median/q25/q75.