margin 0.8.2__tar.gz → 0.9.1__tar.gz

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

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

@@ -29,7 +29,11 @@ from .ledger import Record, Ledger
 
 # Observability
 from .bridge import observe, observe_many, delta, to_uncertain
-from .calibrate import CalibrationResult, calibrate, calibrate_many, parser_from_calibration
+from .calibrate import (
+    CalibrationResult, calibrate, calibrate_many,
+    parser_from_calibration, recalibrate_parser,
+    needs_recalibration, needs_recalibration_many,
+)
 from .composite import CompositeObservation, AggregateStrategy
 from .diff import ComponentChange, Diff, diff
 from .events import EventBus
@@ -95,7 +99,7 @@ from .causal import (
 )
 
 # Streaming
-from .streaming import DriftTracker, AnomalyTracker, CorrelationTracker, Monitor
+from .streaming import DriftTracker, AnomalyTracker, CorrelationTracker, Monitor, WindowConfig
 
 # Config
 from .config import from_config, load_config
@@ -125,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",
@@ -171,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.1/margin/calibrate.py

@@ -0,0 +1,433 @@
+"""
+Threshold derivation from historical data.
+
+Takes a set of "known healthy" measurements and derives baselines and
+thresholds automatically.
+
+Also provides runtime recalibration: detect when a baseline has drifted
+and construct a replacement Parser with updated baselines/thresholds.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Optional
+
+from .health import Thresholds
+from .observation import Parser
+
+
+@dataclass
+class CalibrationResult:
+    """
+    Output of calibrate(): derived baseline and thresholds for one component.
+
+    baseline:     mean of healthy measurements
+    std:          standard deviation of healthy measurements
+    n_samples:    number of measurements used
+    thresholds:   derived Thresholds object
+    """
+    baseline: float
+    std: float
+    n_samples: int
+    thresholds: Thresholds
+
+    def to_dict(self) -> dict:
+        return {
+            "baseline": round(self.baseline, 6),
+            "std": round(self.std, 6),
+            "n_samples": self.n_samples,
+            "intact": self.thresholds.intact,
+            "ablated": self.thresholds.ablated,
+            "higher_is_better": self.thresholds.higher_is_better,
+            "active_min": self.thresholds.active_min,
+        }
+
+
+def calibrate(
+    values: list[float],
+    higher_is_better: bool = True,
+    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 thresholds in one of two modes:
+
+    **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.
+
+        intact  = baseline * intact_fraction  (e.g. 70% of healthy mean)
+        ablated = baseline * ablated_fraction  (e.g. 30% of healthy mean)
+
+    **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.
+    """
+    if not values:
+        raise ValueError("Cannot calibrate from empty list")
+
+    n = len(values)
+    baseline = sum(values) / n
+
+    if baseline == 0:
+        raise ValueError("Cannot calibrate from zero baseline — thresholds would be degenerate")
+    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, 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 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:
+        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),
+        ablated=round(ablated, 6),
+        higher_is_better=higher_is_better,
+        active_min=active_min,
+    )
+
+    return CalibrationResult(
+        baseline=baseline,
+        std=std,
+        n_samples=n,
+        thresholds=thresholds,
+    )
+
+
+def calibrate_many(
+    component_values: dict[str, list[float]],
+    polarities: Optional[dict[str, bool]] = None,
+    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 (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:
+            Parser(baselines=baselines_dict,
+                   thresholds=first_threshold,
+                   component_thresholds=thresholds_dict)
+    """
+    polarities = polarities or {}
+    baselines = {}
+    thresholds = {}
+
+    for name, vals in component_values.items():
+        hib = polarities.get(name, True)
+        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
+
+    return baselines, thresholds
+
+
+def needs_recalibration(
+    calibration_samples: list[float],
+    recent_samples: list[float],
+    mean_shift_threshold: float = 0.2,
+    std_ratio_high: float = 2.0,
+    std_ratio_low: float = 0.5,
+    min_recent: int = 5,
+) -> bool:
+    """
+    Return True if recent values suggest the baseline has drifted.
+
+    Uses distribution comparison between calibration-time healthy data and
+    a recent window to detect two signals:
+
+      Signal A — mean shift: the operating centre has moved by more than
+        `mean_shift_threshold` (relative fraction, default 20%).
+
+      Signal B — spread change: variance has doubled (`std_ratio > 2.0`)
+        or halved (`std_ratio < 0.5`) relative to the calibration period.
+
+    Returns True when either signal fires and there are enough recent samples.
+    A third signal (AnomalyState.ANOMALOUS at healthy sigma) must be checked
+    externally via AnomalyTracker — see `needs_recalibration` docs.
+
+    Args:
+        calibration_samples:  original healthy measurements used to build the Parser
+        recent_samples:       recent window of observed values
+        mean_shift_threshold: relative mean shift that triggers recalibration (default 0.2)
+        std_ratio_high:       std ratio above which spread is considered changed (default 2.0)
+        std_ratio_low:        std ratio below which spread is considered changed (default 0.5)
+        min_recent:           minimum recent samples required to make a judgment (default 5)
+    """
+    if len(recent_samples) < min_recent or len(calibration_samples) < 2:
+        return False
+
+    from .anomaly import check_distribution
+    ds = check_distribution(recent_samples, calibration_samples)
+
+    mean_shifted = abs(ds.mean_shift) > mean_shift_threshold
+    spread_changed = ds.std_ratio > std_ratio_high or ds.std_ratio < std_ratio_low
+
+    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]],
+    polarities: Optional[dict[str, bool]] = None,
+    components: Optional[list[str]] = None,
+    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
+    operating range has drifted.
+
+    Does NOT mutate the input parser — returns a replacement. Components not
+    in `new_healthy_data` (or not in `components`) keep their existing
+    baselines and thresholds unchanged.
+
+    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 (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}
+        for each recalibrated component.
+
+    Transition notes:
+    - Historical Ledger Observations remain anchored to the baseline that was
+      active when they were recorded. Recalibration does not rewrite history.
+    - 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())
+
+    results: dict[str, CalibrationResult] = {}
+    new_baselines: dict[str, float] = {}
+    new_component_thresholds: dict[str, Thresholds] = {}
+
+    for name in to_recalibrate:
+        if name not in new_healthy_data:
+            continue
+        vals = new_healthy_data[name]
+        # 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)
+        # 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
+
+    # Merge: new overrides old; unrecalibrated components are preserved verbatim
+    merged_baselines = {**parser.baselines, **new_baselines}
+    merged_component_thresholds = {**parser.component_thresholds, **new_component_thresholds}
+
+    # Default thresholds: recalibrate if the first component was recalibrated,
+    # otherwise keep the existing default.
+    first_name = list(parser.baselines.keys())[0] if parser.baselines else None
+    if first_name and first_name in new_component_thresholds:
+        default_thresholds = new_component_thresholds.pop(first_name)
+        merged_component_thresholds.pop(first_name, None)
+    else:
+        default_thresholds = parser.thresholds
+        # Remove first component from component_thresholds if it was there
+        if first_name:
+            merged_component_thresholds.pop(first_name, None)
+
+    new_parser = Parser(
+        baselines=merged_baselines,
+        thresholds=default_thresholds,
+        component_thresholds=merged_component_thresholds,
+    )
+
+    return new_parser, results
+
+
+def parser_from_calibration(
+    component_values: dict[str, list[float]],
+    polarities: Optional[dict[str, bool]] = None,
+    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.
+
+    Uses the first component's thresholds as the default, with all others
+    as component_thresholds overrides.
+    """
+    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())
+    if not names:
+        raise ValueError("No components to calibrate")
+
+    default_thresholds = thresh_dict[names[0]]
+    component_thresholds = {n: t for n, t in thresh_dict.items() if n != names[0]}
+
+    return Parser(
+        baselines=baselines,
+        thresholds=default_thresholds,
+        component_thresholds=component_thresholds,
+    )

{margin-0.8.2 → 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.8.2 → 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.8.2 → margin-0.9.1}/margin/observation.py

@@ -10,6 +10,7 @@ Expression:   composed snapshot — all observations + corrections at one moment
 from __future__ import annotations
 
 import json
+import warnings
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -161,8 +162,8 @@ class Correction:
         return {
             "target": self.target,
             "op": self.op.value,
-            "alpha": round(self.alpha, 4),
-            "magnitude": round(self.magnitude, 4),
+            "alpha": self.alpha,
+            "magnitude": self.magnitude,
             "triggered_by": self.triggered_by,
             "provenance": self.provenance,
         }
@@ -198,6 +199,18 @@ class Expression:
     label: str = ""
     step: Optional[int] = None
 
+    def __post_init__(self) -> None:
+        if self.observations:
+            weakest = min(o.confidence for o in self.observations)
+            if self.confidence > weakest:
+                warnings.warn(
+                    f"Expression.confidence ({self.confidence.value}) exceeds the weakest "
+                    f"observation confidence ({weakest.value}). This overclaims certainty "
+                    "and will cause min_confidence policy gates to fire incorrectly. "
+                    "Use Parser.parse() to construct Expressions with correct net confidence.",
+                    stacklevel=2,
+                )
+
     def health_of(self, name: str) -> Optional[Health]:
         for o in self.observations:
             if o.name == name: