margin 0.9.0__tar.gz → 0.9.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.0
+Version: 0.9.1
 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.1}/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.1}/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.1}/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.1}/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.1}/margin/loop.py

@@ -205,13 +205,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 +287,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.1}/margin/persist.py

@@ -22,12 +22,17 @@ 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,
         "drift": {},
         "anomaly": {},
         "correlation": {
@@ -65,11 +70,13 @@ 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))
     monitor = Monitor(
         parser, window=window,
         drift_window=drift_window,
         anomaly_window=anomaly_window,
         correlation_window=correlation_window,
+        anomaly_min_reference=anomaly_min_reference,
         **kwargs,
     )
     monitor._step = data.get("step", 0)

{margin-0.9.0 → margin-0.9.1}/margin/policy/validate.py

@@ -143,6 +143,9 @@ def validate(
     if components:
         _check_component_coverage(policy, components, issues)
 
+    # 8. alpha_from_sigma without a constraint floor
+    _check_alpha_from_sigma(policy, issues)
+
     return ValidationResult(issues=issues)
 
 
@@ -195,6 +198,48 @@ def _check_contract_coverage(
                 f"contract requires '{comp}' but no policy rule targets it"))
 
 
+def _check_alpha_from_sigma(policy: Policy, issues: list[ValidationIssue]) -> None:
+    """
+    Warn when alpha_from_sigma=True with no constraint floor.
+
+    When a rule derives alpha from sigma at runtime, the resulting alpha can
+    be arbitrarily small (e.g. 0.001 in a stable period) and fire useless
+    micro-corrections on every step. A Constraint(min_alpha=...) suppresses
+    these; without one there is no floor.
+
+    Also warns when both alpha_from_sigma and magnitude_from_sigma are set —
+    double sigma scaling amplifies corrections non-linearly.
+    """
+    for rule in policy.rules:
+        if not rule.action.alpha_from_sigma:
+            continue
+
+        constraint = rule.constraint or policy.default_constraint
+
+        if constraint is None:
+            issues.append(ValidationIssue(
+                "warning", rule.name,
+                "alpha_from_sigma=True with no constraint — sigma-derived alpha has no "
+                "floor; add Constraint(min_alpha=...) to suppress micro-corrections "
+                "during stable periods, or pair with a drift predicate so the rule only "
+                "fires when sigma is meaningfully elevated",
+            ))
+        elif constraint.min_alpha == 0.0:
+            issues.append(ValidationIssue(
+                "info", rule.name,
+                "alpha_from_sigma=True and constraint.min_alpha=0.0 — corrections will "
+                "fire with alpha≈0 during stable periods; consider raising min_alpha",
+            ))
+
+        if rule.action.alpha_from_sigma and rule.action.magnitude_from_sigma:
+            issues.append(ValidationIssue(
+                "warning", rule.name,
+                "both alpha_from_sigma and magnitude_from_sigma are True — correction "
+                "strength scales as sigma² (alpha × magnitude); this amplifies strongly "
+                "for large deviations and may overcorrect",
+            ))
+
+
 def _check_component_coverage(
     policy: Policy,
     components: list[str],

{margin-0.9.0 → margin-0.9.1}/margin/streaming.py

@@ -11,6 +11,7 @@ maintain a bounded window and update classification on each new value.
 
 from __future__ import annotations
 
+import warnings
 from collections import deque
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -373,6 +374,15 @@ class Monitor:
         self.anomaly_window = cfg.anomaly or anomaly_window or window
         self.correlation_window = cfg.correlation or correlation_window or window
 
+        if anomaly_min_reference > self.anomaly_window:
+            warnings.warn(
+                f"Monitor: anomaly_min_reference={anomaly_min_reference} > "
+                f"anomaly_window={self.anomaly_window} — AnomalyTrackers will never "
+                "classify because the reference window can never be filled; raise "
+                "anomaly_window or lower anomaly_min_reference.",
+                stacklevel=2,
+            )
+
         self._expression: Optional[Expression] = None
         self._step = 0
 
@@ -472,6 +482,23 @@ class Monitor:
             d["correlations"] = self._correlation_tracker.matrix.to_dict()
         return d
 
+    def reset_anomaly_reference(self, components: Optional[list[str]] = None) -> None:
+        """
+        Clear AnomalyTracker reference windows for the specified components.
+
+        Call after recalibrate_parser() to prevent old-baseline data from
+        contaminating anomaly classification during the warm-up period that
+        follows recalibration. The trackers will return None classifications
+        until they accumulate min_reference new values under the new baseline.
+
+        Args:
+            components: names to reset; None resets all components.
+        """
+        targets = components or list(self._anomaly_trackers.keys())
+        for name in targets:
+            if name in self._anomaly_trackers:
+                self._anomaly_trackers[name].reset()
+
     def reset(self) -> None:
         self._expression = None
         self._step = 0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.0
+Version: 0.9.1
 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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.0"
+version = "0.9.1"
 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"}