margin 0.9.0__tar.gz → 0.9.2__tar.gz

{margin-0.9.0/margin.egg-info → margin-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.0
+Version: 0.9.2
 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
@@ -85,7 +85,7 @@ Then the correction loop:
 - **CLI** — `python -m margin status`, `monitor`, `replay` — no Python code required
 - **Ledger** — full audit trail of every correction, serializable, replayable
 
-All eight layers in one call:
+All stages in one call:
 
 ```python
 from margin import full_step
@@ -129,17 +129,19 @@ parser = parser_from_calibration(
 )
 ```
 
-## Five layers
+## Architecture
 
 | Layer | Question | Key types |
 |---|---|---|
 | **Foundation** | What was measured? | `Health`, `Observation`, `Expression`, `UncertainValue` |
 | **Observability** | What changed? When will it cross? | `diff()`, `forecast()`, `track()`, `calibrate()` |
+| **Streaming** | Is it drifting or anomalous? | `Monitor`, `DriftTracker`, `AnomalyTracker`, `CorrelationTracker` |
 | **Policy** | What should we do? | `PolicyRule`, `Action`, `Constraint`, `Escalation` |
 | **Contract** | Are we meeting our goals? | `HealthTarget`, `SustainHealth`, `RecoveryThreshold` |
 | **Causal** | Why did this happen? | `CausalGraph`, `CausalLink`, `Explanation` |
+| **Intent** | Can we still get there? | `Intent`, `Feasibility`, `IntentResult` |
 
-Plus `step()` and `run()` to orchestrate all five in one call.
+`full_step()` orchestrates all seven in one call.
 
 ## Domain adapters
 

{margin-0.9.0 → margin-0.9.2}/README.md

@@ -58,7 +58,7 @@ Then the correction loop:
 - **CLI** — `python -m margin status`, `monitor`, `replay` — no Python code required
 - **Ledger** — full audit trail of every correction, serializable, replayable
 
-All eight layers in one call:
+All stages in one call:
 
 ```python
 from margin import full_step
@@ -102,17 +102,19 @@ parser = parser_from_calibration(
 )
 ```
 
-## Five layers
+## Architecture
 
 | Layer | Question | Key types |
 |---|---|---|
 | **Foundation** | What was measured? | `Health`, `Observation`, `Expression`, `UncertainValue` |
 | **Observability** | What changed? When will it cross? | `diff()`, `forecast()`, `track()`, `calibrate()` |
+| **Streaming** | Is it drifting or anomalous? | `Monitor`, `DriftTracker`, `AnomalyTracker`, `CorrelationTracker` |
 | **Policy** | What should we do? | `PolicyRule`, `Action`, `Constraint`, `Escalation` |
 | **Contract** | Are we meeting our goals? | `HealthTarget`, `SustainHealth`, `RecoveryThreshold` |
 | **Causal** | Why did this happen? | `CausalGraph`, `CausalLink`, `Explanation` |
+| **Intent** | Can we still get there? | `Intent`, `Feasibility`, `IntentResult` |
 
-Plus `step()` and `run()` to orchestrate all five in one call.
+`full_step()` orchestrates all seven in one call.
 
 ## Domain adapters
 

{margin-0.9.0 → margin-0.9.2}/margin/__init__.py

@@ -31,7 +31,8 @@ from .ledger import Record, Ledger
 from .bridge import observe, observe_many, delta, to_uncertain
 from .calibrate import (
     CalibrationResult, calibrate, calibrate_many,
-    parser_from_calibration, recalibrate_parser, needs_recalibration,
+    parser_from_calibration, recalibrate_parser,
+    needs_recalibration, needs_recalibration_many,
 )
 from .composite import CompositeObservation, AggregateStrategy
 from .diff import ComponentChange, Diff, diff
@@ -128,6 +129,7 @@ __all__ = [
     # Observability
     "observe", "observe_many", "delta", "to_uncertain",
     "CalibrationResult", "calibrate", "calibrate_many", "parser_from_calibration",
+    "recalibrate_parser", "needs_recalibration", "needs_recalibration_many",
     "CompositeObservation", "AggregateStrategy",
     "ComponentChange", "Diff", "diff",
     "AnomalyState", "ANOMALY_SEVERITY", "AnomalyClassification",
@@ -174,7 +176,7 @@ __all__ = [
     # Intent
     "Feasibility", "Requirement", "RiskFactor", "IntentResult", "Intent",
     # Streaming
-    "DriftTracker", "AnomalyTracker", "CorrelationTracker", "Monitor",
+    "DriftTracker", "AnomalyTracker", "CorrelationTracker", "Monitor", "WindowConfig",
     # Config
     "from_config", "load_config",
     # Persistence

{margin-0.9.0 → margin-0.9.2}/margin/calibrate.py

@@ -41,6 +41,7 @@ class CalibrationResult:
             "intact": self.thresholds.intact,
             "ablated": self.thresholds.ablated,
             "higher_is_better": self.thresholds.higher_is_better,
+            "active_min": self.thresholds.active_min,
         }
 
 
@@ -50,28 +51,45 @@ def calibrate(
     intact_fraction: float = 0.70,
     ablated_fraction: float = 0.30,
     active_min: float = 0.05,
+    use_std: bool = False,
+    intact_std_multiplier: float = 1.5,
+    ablated_std_multiplier: float = 3.0,
 ) -> CalibrationResult:
     """
     Derive a baseline and thresholds from known-healthy measurements.
 
     Takes a list of measurements collected when the component was operating
-    normally, and derives:
-    - baseline: mean of the measurements
-    - intact threshold: intact_fraction * baseline
-    - ablated threshold: ablated_fraction * baseline
+    normally, and derives thresholds in one of two modes:
 
-    Args:
-        values:           list of healthy-state measurements
-        higher_is_better: polarity
-        intact_fraction:  fraction of baseline for intact threshold (default 0.70)
-        ablated_fraction: fraction of baseline for ablated threshold (default 0.30)
-        active_min:       minimum correction magnitude for "active"
+    **Fraction mode** (default, ``use_std=False``):
+        Thresholds are a fixed fraction of the mean. Simple and predictable,
+        but variance-blind — high-noise and low-noise components produce the
+        same thresholds if their means are equal.
 
-    For higher_is_better=True:
         intact  = baseline * intact_fraction  (e.g. 70% of healthy mean)
         ablated = baseline * ablated_fraction  (e.g. 30% of healthy mean)
 
-    For higher_is_better=False:
+    **Std mode** (``use_std=True``):
+        Thresholds are placed N standard deviations from the mean. Adapts to
+        the variance of the calibration data, so a noisy component gets wider
+        thresholds than a stable one with the same mean.
+
+        intact  = baseline − intact_std_multiplier × std   (default 1.5σ)
+        ablated = baseline − ablated_std_multiplier × std  (default 3.0σ)
+
+        For ``higher_is_better=False``, thresholds are placed above baseline.
+
+    Args:
+        values:                  list of healthy-state measurements
+        higher_is_better:        polarity
+        intact_fraction:         fraction of baseline for intact threshold (fraction mode)
+        ablated_fraction:        fraction of baseline for ablated threshold (fraction mode)
+        active_min:              minimum correction magnitude for "active"
+        use_std:                 if True, derive thresholds from mean ± N×std instead
+        intact_std_multiplier:   std deviations from mean for intact threshold (std mode)
+        ablated_std_multiplier:  std deviations from mean for ablated threshold (std mode)
+
+    For ``higher_is_better=False`` in fraction mode:
         intact  = baseline * (1 + (1 - intact_fraction))   (e.g. 130% of healthy mean)
         ablated = baseline * (1 + (1 - ablated_fraction))   (e.g. 170% of healthy mean)
         This puts the "bad" direction above baseline for lower-is-better metrics.
@@ -84,23 +102,36 @@ def calibrate(
 
     if baseline == 0:
         raise ValueError("Cannot calibrate from zero baseline — thresholds would be degenerate")
-    if higher_is_better and baseline < 0:
+    if higher_is_better and baseline < 0 and not use_std:
         raise ValueError(
             f"Cannot calibrate higher_is_better=True with negative baseline ({baseline}). "
             "Fraction-based thresholds invert for negative values. "
-            "Use higher_is_better=False or shift your measurements to be positive.")
+            "Use higher_is_better=False, shift your measurements to be positive, "
+            "or use use_std=True for std-based thresholds.")
 
     variance = sum((v - baseline) ** 2 for v in values) / max(n - 1, 1)
     std = math.sqrt(variance)
 
-    if higher_is_better:
-        intact = baseline * intact_fraction
-        ablated = baseline * ablated_fraction
+    if use_std:
+        if std == 0:
+            raise ValueError(
+                "Cannot use use_std=True with zero-variance data — all values are identical. "
+                "Use fraction mode (use_std=False) instead.")
+        if higher_is_better:
+            intact = baseline - intact_std_multiplier * std
+            ablated = baseline - ablated_std_multiplier * std
+        else:
+            intact = baseline + intact_std_multiplier * std
+            ablated = baseline + ablated_std_multiplier * std
     else:
-        # For lower-is-better, thresholds are above baseline (unhealthy direction).
-        # Uses abs(baseline) so the math works for both positive and negative baselines.
-        intact = baseline + abs(baseline) * (1 - intact_fraction)
-        ablated = baseline + abs(baseline) * (1 - ablated_fraction)
+        if higher_is_better:
+            intact = baseline * intact_fraction
+            ablated = baseline * ablated_fraction
+        else:
+            # For lower-is-better, thresholds are above baseline (unhealthy direction).
+            # Uses abs(baseline) so the math works for both positive and negative baselines.
+            intact = baseline + abs(baseline) * (1 - intact_fraction)
+            ablated = baseline + abs(baseline) * (1 - ablated_fraction)
 
     thresholds = Thresholds(
         intact=round(intact, 6),
@@ -123,17 +154,23 @@ def calibrate_many(
     intact_fraction: float = 0.70,
     ablated_fraction: float = 0.30,
     active_min: float = 0.05,
+    use_std: bool = False,
+    intact_std_multiplier: float = 1.5,
+    ablated_std_multiplier: float = 3.0,
 ) -> tuple[dict[str, float], dict[str, Thresholds]]:
     """
     Calibrate multiple components at once. Returns (baselines, thresholds)
     ready to pass directly to Parser().
 
     Args:
-        component_values: {name: [healthy_measurements]}
-        polarities:       {name: higher_is_better} (defaults to True)
-        intact_fraction:  fraction of baseline for intact threshold
-        ablated_fraction: fraction of baseline for ablated threshold
-        active_min:       minimum correction magnitude
+        component_values:        {name: [healthy_measurements]}
+        polarities:              {name: higher_is_better} (defaults to True)
+        intact_fraction:         fraction of baseline for intact threshold (fraction mode)
+        ablated_fraction:        fraction of baseline for ablated threshold (fraction mode)
+        active_min:              minimum correction magnitude
+        use_std:                 if True, use std-based thresholds (see calibrate())
+        intact_std_multiplier:   std deviations for intact threshold (std mode)
+        ablated_std_multiplier:  std deviations for ablated threshold (std mode)
 
     Returns:
         (baselines_dict, thresholds_dict) suitable for:
@@ -147,7 +184,12 @@ def calibrate_many(
 
     for name, vals in component_values.items():
         hib = polarities.get(name, True)
-        result = calibrate(vals, hib, intact_fraction, ablated_fraction, active_min)
+        result = calibrate(
+            vals, hib, intact_fraction, ablated_fraction, active_min,
+            use_std=use_std,
+            intact_std_multiplier=intact_std_multiplier,
+            ablated_std_multiplier=ablated_std_multiplier,
+        )
         baselines[name] = result.baseline
         thresholds[name] = result.thresholds
 
@@ -198,6 +240,57 @@ def needs_recalibration(
     return mean_shifted or spread_changed
 
 
+def needs_recalibration_many(
+    calibration_samples: dict[str, list[float]],
+    recent_samples: dict[str, list[float]],
+    mean_shift_threshold: float = 0.2,
+    std_ratio_high: float = 2.0,
+    std_ratio_low: float = 0.5,
+    min_recent: int = 5,
+) -> dict[str, bool]:
+    """
+    Check multiple components for baseline staleness in one call.
+
+    Runs ``needs_recalibration()`` for each component present in both
+    ``calibration_samples`` and ``recent_samples``. Components missing from
+    either dict are omitted from the result.
+
+    Args:
+        calibration_samples:  {component: original healthy measurements}
+        recent_samples:       {component: recent window of observed values}
+        mean_shift_threshold: relative mean shift that triggers recalibration
+        std_ratio_high:       std ratio above which spread is considered changed
+        std_ratio_low:        std ratio below which spread is considered changed
+        min_recent:           minimum recent samples required per component
+
+    Returns:
+        {component: needs_recalibration} for every component present in both dicts.
+
+    Example::
+
+        flags = needs_recalibration_many(
+            calibration_samples={"cpu": cpu_cal, "mem": mem_cal},
+            recent_samples={"cpu": cpu_recent, "mem": mem_recent},
+        )
+        stale = [c for c, flag in flags.items() if flag]
+        if stale:
+            new_parser, _ = recalibrate_parser(parser, {c: recent_samples[c] for c in stale})
+    """
+    result: dict[str, bool] = {}
+    for component in calibration_samples:
+        if component not in recent_samples:
+            continue
+        result[component] = needs_recalibration(
+            calibration_samples[component],
+            recent_samples[component],
+            mean_shift_threshold=mean_shift_threshold,
+            std_ratio_high=std_ratio_high,
+            std_ratio_low=std_ratio_low,
+            min_recent=min_recent,
+        )
+    return result
+
+
 def recalibrate_parser(
     parser: Parser,
     new_healthy_data: dict[str, list[float]],
@@ -206,6 +299,9 @@ def recalibrate_parser(
     intact_fraction: float = 0.70,
     ablated_fraction: float = 0.30,
     active_min: float = 0.05,
+    use_std: bool = False,
+    intact_std_multiplier: float = 1.5,
+    ablated_std_multiplier: float = 3.0,
 ) -> tuple[Parser, dict[str, CalibrationResult]]:
     """
     Return a new Parser with updated baselines for components whose healthy
@@ -215,19 +311,24 @@ def recalibrate_parser(
     in `new_healthy_data` (or not in `components`) keep their existing
     baselines and thresholds unchanged.
 
-    Use after `needs_recalibration()` signals that a component's baseline
-    is stale, or when you have a new labeled window of known-healthy data.
+    Use after `needs_recalibration()` or `needs_recalibration_many()` signals
+    that a component's baseline is stale, or when you have a new labeled window
+    of known-healthy data.
 
     Args:
-        parser:           the existing Parser to replace
-        new_healthy_data: {component: [new_healthy_measurements]}
-        polarities:       {component: higher_is_better} overrides (defaults
-                          to existing parser polarity for each component)
-        components:       allowlist of components to recalibrate; if None,
-                          all components in new_healthy_data are recalibrated
-        intact_fraction:  fraction of baseline for intact threshold
-        ablated_fraction: fraction of baseline for ablated threshold
-        active_min:       minimum correction magnitude
+        parser:                  the existing Parser to replace
+        new_healthy_data:        {component: [new_healthy_measurements]}
+        polarities:              {component: higher_is_better} overrides (defaults
+                                 to existing parser polarity for each component)
+        components:              allowlist of components to recalibrate; if None,
+                                 all components in new_healthy_data are recalibrated
+        intact_fraction:         fraction of baseline for intact threshold (fraction mode)
+        ablated_fraction:        fraction of baseline for ablated threshold (fraction mode)
+        active_min:              inherited from existing parser thresholds; pass only
+                                 to override for recalibrated components
+        use_std:                 if True, use std-based thresholds (see calibrate())
+        intact_std_multiplier:   std deviations for intact threshold (std mode)
+        ablated_std_multiplier:  std deviations for ablated threshold (std mode)
 
     Returns:
         (new_parser, results) where results is {component: CalibrationResult}
@@ -236,11 +337,13 @@ def recalibrate_parser(
     Transition notes:
     - Historical Ledger Observations remain anchored to the baseline that was
       active when they were recorded. Recalibration does not rewrite history.
-    - After recalibrating, rebuild Monitor from the new Parser:
-        save_monitor(old_monitor, "checkpoint.json")  # optional audit trail
-        new_monitor = Monitor(new_parser, drift_window=..., anomaly_window=...,
-                               correlation_window=...)
-    - Per-tracker windows should match the old Monitor's windows for continuity.
+    - After recalibrating, call monitor.reset_anomaly_reference() to flush
+      old-baseline data from AnomalyTracker windows:
+        new_parser, _ = recalibrate_parser(old_parser, new_data)
+        monitor.parser = new_parser
+        monitor.reset_anomaly_reference()   # clears stale reference window
+    - Per-tracker drift windows need not be reset — drift history under the
+      old baseline is simply outweighed as new observations accumulate.
     """
     polarities = polarities or {}
     to_recalibrate = set(components) if components else set(new_healthy_data.keys())
@@ -256,7 +359,14 @@ def recalibrate_parser(
         # Resolve polarity: explicit override → existing parser polarity → True
         existing_t = parser.component_thresholds.get(name) or parser.thresholds
         hib = polarities.get(name, existing_t.higher_is_better)
-        result = calibrate(vals, hib, intact_fraction, ablated_fraction, active_min)
+        # Inherit active_min from existing thresholds unless caller overrides
+        component_active_min = existing_t.active_min if active_min == 0.05 else active_min
+        result = calibrate(
+            vals, hib, intact_fraction, ablated_fraction, component_active_min,
+            use_std=use_std,
+            intact_std_multiplier=intact_std_multiplier,
+            ablated_std_multiplier=ablated_std_multiplier,
+        )
         results[name] = result
         new_baselines[name] = result.baseline
         new_component_thresholds[name] = result.thresholds
@@ -292,6 +402,9 @@ def parser_from_calibration(
     intact_fraction: float = 0.70,
     ablated_fraction: float = 0.30,
     active_min: float = 0.05,
+    use_std: bool = False,
+    intact_std_multiplier: float = 1.5,
+    ablated_std_multiplier: float = 3.0,
 ) -> Parser:
     """
     One-shot: calibrate from historical data and return a ready-to-use Parser.
@@ -301,6 +414,9 @@ def parser_from_calibration(
     """
     baselines, thresh_dict = calibrate_many(
         component_values, polarities, intact_fraction, ablated_fraction, active_min,
+        use_std=use_std,
+        intact_std_multiplier=intact_std_multiplier,
+        ablated_std_multiplier=ablated_std_multiplier,
     )
 
     names = list(thresh_dict.keys())

{margin-0.9.0 → margin-0.9.2}/margin/contract.py

@@ -14,6 +14,7 @@ Contracts express:
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Optional
@@ -108,6 +109,14 @@ class ReachHealth(ContractTerm):
     within_steps: int
 
     def evaluate(self, ledger: Ledger, expr: Optional[Expression] = None) -> TermResult:
+        if ledger.max_records is not None and ledger.max_records < self.within_steps:
+            warnings.warn(
+                f"ReachHealth '{self.name}': ledger.max_records={ledger.max_records} < "
+                f"within_steps={self.within_steps} — records older than max_records are "
+                "dropped; if the target was reached before the cap, this term will show "
+                "PENDING rather than MET. Increase max_records or reduce within_steps.",
+                stacklevel=2,
+            )
         recent = ledger.for_component(self.component).last_n(self.within_steps)
         if len(recent) < 1:
             return TermResult(self.name, TermStatus.PENDING, "no records yet")
@@ -142,6 +151,13 @@ class SustainHealth(ContractTerm):
     or_better: bool = True
 
     def evaluate(self, ledger: Ledger, expr: Optional[Expression] = None) -> TermResult:
+        if ledger.max_records is not None and ledger.max_records < self.for_steps:
+            warnings.warn(
+                f"SustainHealth '{self.name}': ledger.max_records={ledger.max_records} < "
+                f"for_steps={self.for_steps} — this term can never be MET; "
+                "increase Ledger(max_records=...) or reduce SustainHealth(for_steps=...).",
+                stacklevel=2,
+            )
         recent = ledger.for_component(self.component).last_n(self.for_steps)
         if len(recent) < self.for_steps:
             return TermResult(self.name, TermStatus.PENDING,

{margin-0.9.0 → margin-0.9.2}/margin/health.py

@@ -46,6 +46,7 @@ class Thresholds:
                       (throughput, signal), False means lower values are
                       healthier (error rate, latency)
     active_min:       minimum correction magnitude to count as "active"
+    labels:           optional display labels keyed by Health.value strings
 
     For higher_is_better=True:  intact >= ablated, value >= intact → INTACT
     For higher_is_better=False: intact <= ablated, value <= intact → INTACT
@@ -54,6 +55,13 @@ class Thresholds:
     ablated: float
     higher_is_better: bool = True
     active_min: float = 0.05
+    labels: Optional[dict[str, str]] = None
+
+    def label_for(self, health: 'Health') -> str:
+        """Return the display label for a health state, or the state name if no label set."""
+        if self.labels:
+            return self.labels.get(health.value, health.value)
+        return health.value
 
     def __post_init__(self):
         if self.higher_is_better and self.ablated > self.intact:

{margin-0.9.0 → margin-0.9.2}/margin/loop.py

@@ -45,6 +45,7 @@ class StepResult:
     correction: Optional[Correction] = None
     escalation: Optional[Escalation] = None
     contract: Optional[ContractResult] = None
+    corrections: list = field(default_factory=list)  # all fired corrections (multi_rule)
 
     @property
     def acted(self) -> bool:
@@ -74,6 +75,8 @@ class StepResult:
             d["decision"] = self.decision.to_dict()
         if self.correction:
             d["correction"] = self.correction.to_dict()
+        if self.corrections:
+            d["corrections"] = [c.to_dict() for c in self.corrections]
         if self.escalation:
             d["escalation"] = self.escalation.to_dict()
         if self.contract:
@@ -140,6 +143,11 @@ def step(
     elif isinstance(decision.result, Escalation):
         escalation = decision.result
 
+    # Collect all corrections for multi_rule mode
+    all_corrections = []
+    if policy.multi_rule:
+        all_corrections = [r for r in decision.results if isinstance(r, Correction)]
+
     # 3. Evaluate contract
     contract_result = None
     if contract:
@@ -152,6 +160,7 @@ def step(
         correction=correction,
         escalation=escalation,
         contract=contract_result,
+        corrections=all_corrections,
     )
 
 
@@ -205,13 +214,13 @@ def run(
 @dataclass
 class FullStepResult:
     """
-    Complete output of one full evaluation across all 8 layers.
+    Complete output of one full_step() evaluation.
 
-    step:       policy/contract/causal evaluation
-    drift:      per-component drift classifications
-    anomaly:    per-component anomaly classifications
+    step:         policy/contract/causal evaluation
+    drift:        per-component drift classifications
+    anomaly:      per-component anomaly classifications
     correlations: discovered component correlations
-    intent:     goal feasibility (if intent provided)
+    intent:       goal feasibility (if intent provided)
     """
     step: StepResult
     drift: dict = field(default_factory=dict)
@@ -287,7 +296,7 @@ def full_step(
         intent:    Intent goal (optional)
         now:       current timestamp (optional)
 
-    Returns FullStepResult with all 8 layers evaluated.
+    Returns FullStepResult with all stages evaluated.
     """
     from datetime import datetime
 

{margin-0.9.0 → margin-0.9.2}/margin/observation.py

@@ -60,6 +60,7 @@ class Observation:
     higher_is_better: bool = True
     provenance: list[str] = field(default_factory=list)
     measured_at: Optional[datetime] = None
+    health_label: Optional[str] = None
 
     @property
     def sigma(self) -> float:
@@ -91,10 +92,11 @@ class Observation:
 
     def to_atom(self) -> str:
         """Compact string: NAME:HEALTH(±σ)"""
+        display = self.health_label or self.health.value
         if self.health == Health.OOD:
-            return f"{self.name}:{self.health.value}"
+            return f"{self.name}:{display}"
         sign = "+" if self.sigma >= 0 else ""
-        return f"{self.name}:{self.health.value}({sign}{self.sigma:.2f}σ)"
+        return f"{self.name}:{display}({sign}{self.sigma:.2f}σ)"
 
     def to_dict(self) -> dict:
         d = {
@@ -107,6 +109,8 @@ class Observation:
             "higher_is_better": self.higher_is_better,
             "provenance": self.provenance,
         }
+        if self.health_label is not None:
+            d["health_label"] = self.health_label
         if self.measured_at is not None:
             d["measured_at"] = self.measured_at.isoformat()
         return d
@@ -125,6 +129,7 @@ class Observation:
             higher_is_better=d.get("higher_is_better", True),
             provenance=d.get("provenance", []),
             measured_at=measured_at,
+            health_label=d.get("health_label"),
         )
 
 
@@ -311,6 +316,10 @@ class Parser:
     def _thresholds_for(self, name: str) -> Thresholds:
         return self.component_thresholds.get(name, self.thresholds)
 
+    def label_for(self, component: str, health: Health) -> str:
+        """Return the display label for a component's health state."""
+        return self._thresholds_for(component).label_for(health)
+
     def parse(
         self,
         values: dict[str, float],
@@ -343,6 +352,7 @@ class Parser:
                 name=name, health=h, value=val, baseline=baseline,
                 confidence=conf, higher_is_better=ct.higher_is_better,
                 provenance=list(provenance),
+                health_label=ct.label_for(h) if ct.labels else None,
             ))
 
         corrections = []

{margin-0.9.0 → margin-0.9.2}/margin/persist.py

@@ -22,19 +22,25 @@ from .streaming import Monitor, DriftTracker, AnomalyTracker, CorrelationTracker
 
 def save_monitor(monitor: Monitor, path: str) -> None:
     """Save Monitor state to a JSON file."""
+    # Read anomaly_min_reference from one of the trackers (all share the same value)
+    _any_tracker = next(iter(monitor._anomaly_trackers.values()), None)
+    _anomaly_min_ref = _any_tracker._min_reference if _any_tracker else 10
+
     state = {
         "step": monitor.step,
         "window": monitor.window,
         "drift_window": monitor.drift_window,
         "anomaly_window": monitor.anomaly_window,
         "correlation_window": monitor.correlation_window,
+        "anomaly_min_reference": _anomaly_min_ref,
+        "features": sorted(monitor.features),
         "drift": {},
         "anomaly": {},
         "correlation": {
             "components": monitor._correlation_tracker.components,
             "series": {c: list(d) for c, d in monitor._correlation_tracker._series.items()},
             "n_updates": monitor._correlation_tracker.n_updates,
-        },
+        } if monitor._correlation_tracker is not None else None,
     }
 
     for name, dt in monitor._drift_trackers.items():
@@ -65,11 +71,16 @@ def load_monitor(path: str, parser: Parser, **kwargs) -> Monitor:
     drift_window = data.get("drift_window", kwargs.pop("drift_window", None))
     anomaly_window = data.get("anomaly_window", kwargs.pop("anomaly_window", None))
     correlation_window = data.get("correlation_window", kwargs.pop("correlation_window", None))
+    anomaly_min_reference = data.get("anomaly_min_reference", kwargs.pop("anomaly_min_reference", 10))
+    features_data = data.get("features", None)
+    features = set(features_data) if features_data is not None else None
     monitor = Monitor(
         parser, window=window,
         drift_window=drift_window,
         anomaly_window=anomaly_window,
         correlation_window=correlation_window,
+        anomaly_min_reference=anomaly_min_reference,
+        features=features,
         **kwargs,
     )
     monitor._step = data.get("step", 0)
@@ -94,12 +105,13 @@ def load_monitor(path: str, parser: Parser, **kwargs) -> Monitor:
                 tracker._values.append(v)
 
     # Restore correlation series
-    corr_data = data.get("correlation", {})
-    for c in monitor._correlation_tracker.components:
-        series = corr_data.get("series", {}).get(c, [])
-        for v in series:
-            monitor._correlation_tracker._series[c].append(v)
-    monitor._correlation_tracker._n_updates = corr_data.get("n_updates", 0)
+    corr_data = data.get("correlation")
+    if corr_data is not None and monitor._correlation_tracker is not None:
+        for c in monitor._correlation_tracker.components:
+            series = corr_data.get("series", {}).get(c, [])
+            for v in series:
+                monitor._correlation_tracker._series[c].append(v)
+        monitor._correlation_tracker._n_updates = corr_data.get("n_updates", 0)
 
     return monitor