margin 0.9.30__tar.gz → 0.9.32__tar.gz

{margin-0.9.30/margin.egg-info → margin-0.9.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.30
+Version: 0.9.32
 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
@@ -86,6 +86,8 @@ Then the correction loop:
 - **Causal** — dependency graphs ("api is DEGRADED because db is ABLATED")
 - **Auto-correlation** — discover which components move together from data, with lag detection
 - **Streaming** — incremental trackers: `Monitor.update(values)` updates health + drift + anomaly + correlation in one call
+- **Flow** — ordered stages with typed live guidance: ADVANCE / HOLD / RETRY / ROLLBACK / ESCALATE for multi-stage processes
+- **Issue** — typed diagnostics: library surfaces its own misconfigurations, degraded assumptions, recovered failures
 - **Config** — define everything in YAML/JSON: `margin.load_config("margin.yaml")`
 - **Persistence** — save/restore Monitor state across restarts, batch replay from CSV
 - **Intent** — goal feasibility: `intent.evaluate_monitor(monitor)` → FEASIBLE / AT_RISK / INFEASIBLE with ETA
@@ -123,6 +125,55 @@ Thresholds(intact=0.02, ablated=0.10, higher_is_better=False)
 
 One flag. Threads through every comparison, every sigma calculation, every correction decision, every recovery ratio. You never think about it again.
 
+## Multi-stage process guidance
+
+For processes where each stage has distinct entry/quality/exit criteria — deployment pipelines, fermentation phases, clinical trials, incident response:
+
+```python
+from margin import Flow, Stage, Parser, Thresholds
+
+flow = Flow(stages=[
+    Stage(
+        name="lag",
+        parser=Parser(baselines={"biomass": 0.1}, thresholds=Thresholds(intact=0.08, ablated=0.02)),
+        advance_when=lambda expr: expr.observations[0].value >= 0.15,
+    ),
+    Stage(name="exponential", parser=..., advance_when=...),
+    Stage(name="stationary", parser=...),
+], label="ferment")
+
+result = flow.observe({"biomass": 0.12})
+print(result.to_atom())
+# flow:ferment:lag[1/3] → HOLD
+
+# When the advance_when predicate fires:
+result = flow.observe({"biomass": 0.18})
+# result.guidance == Guidance.ADVANCE
+flow.advance()
+```
+
+Predicate exceptions are caught as ERROR issues, guidance degrades to HOLD, the flow stays alive — safety-first semantics for safety-critical contexts.
+
+## Typed diagnostics
+
+The library surfaces its own operational state the same way it classifies observed state:
+
+```python
+monitor.update({"mystery": 1.0})       # emits WARNING: BASELINE_MISSING
+monitor.drift("unknown")                # emits WARNING: UNKNOWN_COMPONENT
+
+# Query it programmatically
+monitor.issues.by_code("BASELINE_MISSING")       # [Issue(...)]
+monitor.issues.at_least(IssueLevel.WARNING)       # all severe enough
+monitor.diagnose()                                # JSON-safe dashboard summary
+
+# Bridge to your logger
+import logging
+monitor.issues.attach_logger(logging.getLogger("margin"))
+```
+
+**Harvest-safe on hard fail:** if `Monitor.update()` or `Flow.observe()` raises, a `FATAL(INTERNAL_ERROR)` issue is recorded *before* the exception propagates. `monitor.issues` survives crashes intact.
+
 ## Auto-calibrate from data
 
 Don't guess thresholds. Derive them from healthy measurements:
@@ -147,8 +198,10 @@ parser = parser_from_calibration(
 | **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` |
+| **Flow** | What stage are we in, and what should we do? | `Flow`, `Stage`, `Guidance`, `FlowResult` |
+| **Issue** | What did the library notice about itself? | `Issue`, `IssueLevel`, `IssueBuffer`, `IssueCode` |
 
-`full_step()` orchestrates all seven in one call.
+`full_step()` orchestrates the first seven in one call. `Flow` composes them into a sequence. `Issue` is ambient — every layer emits diagnostics into the same buffer.
 
 ## Domain adapters
 

{margin-0.9.30 → margin-0.9.32}/README.md

@@ -57,6 +57,8 @@ Then the correction loop:
 - **Causal** — dependency graphs ("api is DEGRADED because db is ABLATED")
 - **Auto-correlation** — discover which components move together from data, with lag detection
 - **Streaming** — incremental trackers: `Monitor.update(values)` updates health + drift + anomaly + correlation in one call
+- **Flow** — ordered stages with typed live guidance: ADVANCE / HOLD / RETRY / ROLLBACK / ESCALATE for multi-stage processes
+- **Issue** — typed diagnostics: library surfaces its own misconfigurations, degraded assumptions, recovered failures
 - **Config** — define everything in YAML/JSON: `margin.load_config("margin.yaml")`
 - **Persistence** — save/restore Monitor state across restarts, batch replay from CSV
 - **Intent** — goal feasibility: `intent.evaluate_monitor(monitor)` → FEASIBLE / AT_RISK / INFEASIBLE with ETA
@@ -94,6 +96,55 @@ Thresholds(intact=0.02, ablated=0.10, higher_is_better=False)
 
 One flag. Threads through every comparison, every sigma calculation, every correction decision, every recovery ratio. You never think about it again.
 
+## Multi-stage process guidance
+
+For processes where each stage has distinct entry/quality/exit criteria — deployment pipelines, fermentation phases, clinical trials, incident response:
+
+```python
+from margin import Flow, Stage, Parser, Thresholds
+
+flow = Flow(stages=[
+    Stage(
+        name="lag",
+        parser=Parser(baselines={"biomass": 0.1}, thresholds=Thresholds(intact=0.08, ablated=0.02)),
+        advance_when=lambda expr: expr.observations[0].value >= 0.15,
+    ),
+    Stage(name="exponential", parser=..., advance_when=...),
+    Stage(name="stationary", parser=...),
+], label="ferment")
+
+result = flow.observe({"biomass": 0.12})
+print(result.to_atom())
+# flow:ferment:lag[1/3] → HOLD
+
+# When the advance_when predicate fires:
+result = flow.observe({"biomass": 0.18})
+# result.guidance == Guidance.ADVANCE
+flow.advance()
+```
+
+Predicate exceptions are caught as ERROR issues, guidance degrades to HOLD, the flow stays alive — safety-first semantics for safety-critical contexts.
+
+## Typed diagnostics
+
+The library surfaces its own operational state the same way it classifies observed state:
+
+```python
+monitor.update({"mystery": 1.0})       # emits WARNING: BASELINE_MISSING
+monitor.drift("unknown")                # emits WARNING: UNKNOWN_COMPONENT
+
+# Query it programmatically
+monitor.issues.by_code("BASELINE_MISSING")       # [Issue(...)]
+monitor.issues.at_least(IssueLevel.WARNING)       # all severe enough
+monitor.diagnose()                                # JSON-safe dashboard summary
+
+# Bridge to your logger
+import logging
+monitor.issues.attach_logger(logging.getLogger("margin"))
+```
+
+**Harvest-safe on hard fail:** if `Monitor.update()` or `Flow.observe()` raises, a `FATAL(INTERNAL_ERROR)` issue is recorded *before* the exception propagates. `monitor.issues` survives crashes intact.
+
 ## Auto-calibrate from data
 
 Don't guess thresholds. Derive them from healthy measurements:
@@ -118,8 +169,10 @@ parser = parser_from_calibration(
 | **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` |
+| **Flow** | What stage are we in, and what should we do? | `Flow`, `Stage`, `Guidance`, `FlowResult` |
+| **Issue** | What did the library notice about itself? | `Issue`, `IssueLevel`, `IssueBuffer`, `IssueCode` |
 
-`full_step()` orchestrates all seven in one call.
+`full_step()` orchestrates the first seven in one call. `Flow` composes them into a sequence. `Issue` is ambient — every layer emits diagnostics into the same buffer.
 
 ## Domain adapters
 

{margin-0.9.30 → margin-0.9.32}/margin/flow.py

@@ -386,6 +386,26 @@ class Flow:
         # Collect issues produced this step: Parser's issues are on expr,
         # predicate failures are emitted during _classify.
         step_issues: List[Issue] = list(expr.issues)
+
+        # STAGE_ABLATED_ON_ENTRY: emit WARNING once if the first observation
+        # in this stage lands any component in ABLATED state.  The warning
+        # helps operators notice "we entered this stage already in trouble."
+        if monitor.step == 1:
+            ablated_here = [o.name for o in expr.observations
+                            if o.health == Health.ABLATED]
+            if ablated_here:
+                iss = self._issues.emit(
+                    IssueLevel.WARNING,
+                    IssueCode.STAGE_ABLATED_ON_ENTRY,
+                    detail=(
+                        f"stage {stage.name!r} entered with ABLATED "
+                        f"component(s): {ablated_here}"
+                    ),
+                    component=stage.name,
+                    ablated_components=list(ablated_here),
+                )
+                step_issues.append(iss)
+
         guidance, reason = self._classify(stage, expr, step_issues)
 
         return FlowResult(

{margin-0.9.30 → margin-0.9.32}/margin/issue.py

@@ -16,9 +16,10 @@ Design constraints
    emits them at known sites.
 
 2. **Harvestable on hard fail.**  Issues are added to the buffer
-   *before* exceptions propagate, using ``try / finally`` patterns in
-   the callers.  Even a FATAL internal error leaves the full recent
-   issue history intact for post-mortem inspection.
+   *before* exceptions propagate, using ``try / except / raise`` patterns
+   in the callers — the FATAL record is emitted in the except branch
+   before the exception is re-raised.  Even a FATAL internal error leaves
+   the full recent issue history intact for post-mortem inspection.
 
 3. **Typed, not strings.**  Issue.code is a short stable identifier
    (``BASELINE_MISSING``, ``PREDICATE_FAILURE``) that consumers can
@@ -156,16 +157,79 @@ class IssueBuffer:
             raise ValueError("max_issues must be >= 1")
         self.max_issues = max_issues
         self._issues: Deque[Issue] = deque(maxlen=max_issues)
+        # Optional Python logging integration.  When a logger is attached,
+        # every Issue added to the buffer is mirrored to the logger.
+        self._logger: Optional[Any] = None
+        self._level_map: Optional[Dict[IssueLevel, int]] = None
 
     # ------------------------------------------------------------------
     # Writing
     # ------------------------------------------------------------------
 
     def add(self, issue: Issue) -> Issue:
-        """Append an issue.  Returns the issue for chained access."""
+        """Append an issue.  Returns the issue for chained access.
+
+        Mirrors to the attached logger (if any) before returning.
+        """
         self._issues.append(issue)
+        if self._logger is not None:
+            self._mirror_to_logger(issue)
         return issue
 
+    def _mirror_to_logger(self, issue: "Issue") -> None:
+        """Emit the issue to the attached Python logger."""
+        import logging as _logging
+        level_map = self._level_map or {
+            IssueLevel.INFO: _logging.INFO,
+            IssueLevel.WARNING: _logging.WARNING,
+            IssueLevel.ERROR: _logging.ERROR,
+            IssueLevel.FATAL: _logging.CRITICAL,
+        }
+        py_level = level_map.get(issue.level, _logging.WARNING)
+        if issue.component:
+            msg = f"[{issue.code}] ({issue.component}) {issue.detail}"
+        else:
+            msg = f"[{issue.code}] {issue.detail}"
+        try:
+            self._logger.log(py_level, msg, extra={
+                "margin_code": issue.code,
+                "margin_component": issue.component,
+                "margin_level": issue.level.value,
+            })
+        except Exception:
+            # Never let logging errors break the buffer.
+            pass
+
+    def attach_logger(self, logger, level_map: Optional[Dict[IssueLevel, int]] = None) -> None:
+        """
+        Attach a Python ``logging.Logger``.  Subsequent issues are mirrored
+        to the logger at the mapped level.
+
+        Default level map::
+
+            IssueLevel.INFO     → logging.INFO
+            IssueLevel.WARNING  → logging.WARNING
+            IssueLevel.ERROR    → logging.ERROR
+            IssueLevel.FATAL    → logging.CRITICAL
+
+        Example::
+
+            import logging
+            logger = logging.getLogger("margin")
+            monitor.issues.attach_logger(logger)
+            # Every issue now also appears in the Python log stream.
+
+        Pass ``level_map`` to override specific mappings.
+        Call :meth:`detach_logger` to stop mirroring.
+        """
+        self._logger = logger
+        self._level_map = dict(level_map) if level_map else None
+
+    def detach_logger(self) -> None:
+        """Stop mirroring issues to the previously-attached logger."""
+        self._logger = None
+        self._level_map = None
+
     def emit(
         self,
         level: IssueLevel,
@@ -249,26 +313,34 @@ class IssueBuffer:
             out[i.level.value] += 1
         return out
 
-    def diagnose(self, n: int = 10) -> Dict[str, Any]:
+    def diagnose(self, n: int = 10, serialize: bool = True) -> Dict[str, Any]:
         """
         Human/dashboard-friendly summary.
 
+        With ``serialize=True`` (default) the result is JSON-ready — every
+        value is a primitive or dict/list of primitives — so dashboards
+        can ``json.dumps(monitor.diagnose())`` directly.
+
+        With ``serialize=False`` the ``recent`` list contains raw
+        :class:`Issue` instances for programmatic inspection.
+
         Returns::
 
             {
                 "total": int,
                 "counts": {"INFO": n, "WARNING": n, "ERROR": n, "FATAL": n},
-                "recent": [Issue, ...],      # last n
-                "codes": {"BASELINE_MISSING": n, ...},   # by code
+                "recent": [dict or Issue, ...],
+                "codes": {"BASELINE_MISSING": n, ...},
             }
         """
         codes: Dict[str, int] = {}
         for i in self._issues:
             codes[i.code] = codes.get(i.code, 0) + 1
+        tail = self.tail(n)
         return {
             "total": len(self._issues),
             "counts": self.counts(),
-            "recent": self.tail(n),
+            "recent": [i.to_dict() for i in tail] if serialize else tail,
             "codes": codes,
         }
 

{margin-0.9.30 → margin-0.9.32}/margin/streaming.py

@@ -444,6 +444,10 @@ class Monitor:
         # Parser (via Expression.issues) + direct emission from update().
         from .issue import IssueBuffer
         self._issues = IssueBuffer()
+        # Dedup sets: emit once per component per condition until it resolves
+        self._drift_warming: set = set()       # components whose DriftTracker is still below min_samples
+        self._anomaly_warming: set = set()     # AnomalyTracker below min_reference
+        self._unknown_flagged: set = set()     # unknown-component queries we've already warned about
 
         # Create per-component trackers for enabled features only
         self._drift_trackers: dict[str, DriftTracker] = {}
@@ -539,6 +543,11 @@ class Monitor:
             if self._correlation_tracker is not None:
                 self._correlation_tracker.update(values)
 
+            # Warming-up diagnostics: emit INFO once per component while a
+            # tracker is still below its min-samples threshold; clear the
+            # flag when classification graduates.
+            self._emit_warming_issues()
+
             return self._expression
         except Exception as _e:
             self._issues.emit(
@@ -559,17 +568,82 @@ class Monitor:
         """IssueBuffer containing all issues emitted by this Monitor (and its Parser)."""
         return self._issues
 
-    def diagnose(self, n: int = 10) -> dict:
+    def diagnose(self, n: int = 10, serialize: bool = True) -> dict:
         """Dashboard-friendly summary of recent issues.  See IssueBuffer.diagnose."""
-        return self._issues.diagnose(n)
+        return self._issues.diagnose(n, serialize=serialize)
+
+    def _flag_unknown(self, component: str, where: str) -> None:
+        """Emit UNKNOWN_COMPONENT once per unknown component queried via this method."""
+        from .issue import IssueLevel, IssueCode
+        key = (where, component)
+        if key in self._unknown_flagged:
+            return
+        self._unknown_flagged.add(key)
+        self._issues.emit(
+            IssueLevel.WARNING,
+            IssueCode.UNKNOWN_COMPONENT,
+            detail=(
+                f"{where}({component!r}): no tracker registered for this "
+                "component.  Add it to Parser.baselines or enable the feature."
+            ),
+            component=component,
+        )
+
+    def _emit_warming_issues(self) -> None:
+        """Emit / clear INSUFFICIENT_SAMPLES for trackers still below min_samples."""
+        from .issue import IssueLevel, IssueCode
+
+        # Drift
+        for name, tracker in self._drift_trackers.items():
+            if tracker._classification is None and tracker.n_observations < tracker._min_samples:
+                if name not in self._drift_warming:
+                    self._drift_warming.add(name)
+                    self._issues.emit(
+                        IssueLevel.INFO,
+                        IssueCode.INSUFFICIENT_SAMPLES,
+                        detail=(
+                            f"drift tracker for {name!r} has "
+                            f"{tracker.n_observations}/{tracker._min_samples} "
+                            "required samples; classification unavailable until warmed."
+                        ),
+                        component=name,
+                        kind="drift",
+                    )
+            else:
+                self._drift_warming.discard(name)
+
+        # Anomaly
+        for name, tracker in self._anomaly_trackers.items():
+            if tracker._classification is None and tracker.n_values < tracker._min_reference:
+                if name not in self._anomaly_warming:
+                    self._anomaly_warming.add(name)
+                    self._issues.emit(
+                        IssueLevel.INFO,
+                        IssueCode.INSUFFICIENT_SAMPLES,
+                        detail=(
+                            f"anomaly tracker for {name!r} has "
+                            f"{tracker.n_values}/{tracker._min_reference} "
+                            "reference values; classification unavailable until warmed."
+                        ),
+                        component=name,
+                        kind="anomaly",
+                    )
+            else:
+                self._anomaly_warming.discard(name)
 
     def drift(self, component: str) -> Optional[DriftClassification]:
         t = self._drift_trackers.get(component)
-        return t.classification if t else None
+        if t is None:
+            self._flag_unknown(component, "drift")
+            return None
+        return t.classification
 
     def anomaly(self, component: str) -> Optional[AnomalyClassification]:
         t = self._anomaly_trackers.get(component)
-        return t.classification if t else None
+        if t is None:
+            self._flag_unknown(component, "anomaly")
+            return None
+        return t.classification
 
     @property
     def correlations(self) -> Optional[CorrelationMatrix]:
@@ -606,6 +680,7 @@ class Monitor:
             d["correlations"] = self._correlation_tracker.matrix.to_dict()
         if self.provenance_graph is not None:
             d["provenance_nodes"] = len(self.provenance_graph.nodes)
+        d["issues"] = self._issues.diagnose(5)
         return d
 
     def fingerprint(self) -> Fingerprint:
@@ -818,6 +893,7 @@ class Monitor:
             if score > 1.5:
                 print(f"Session diverged from baseline (score={score:.2f})")
         """
+        from .issue import IssueLevel, IssueCode
         current_fp = self.fingerprint()
         _metrics = list(metrics) if metrics is not None else list(
             set(current_fp.keys()) & set(reference_fp.keys())
@@ -825,14 +901,26 @@ class Monitor:
         if not _metrics:
             return 0.0
         z_scores = []
+        skipped_near_zero: list[str] = []
         for m in _metrics:
             ref_std = reference_fp.get(m, {}).get("std", 0.0)
             # 1e-12 tolerance: reject floating-point noise from constant windows
             if ref_std < 1e-12:
+                skipped_near_zero.append(m)
                 continue
             cur_mean = current_fp.get(m, {}).get("mean", 0.0)
             ref_mean = reference_fp.get(m, {}).get("mean", 0.0)
             z_scores.append(abs(cur_mean - ref_mean) / ref_std)
+        if skipped_near_zero:
+            self._issues.emit(
+                IssueLevel.INFO,
+                IssueCode.NEAR_ZERO_STD,
+                detail=(
+                    f"anomaly_score skipped {len(skipped_near_zero)} "
+                    f"metric(s) with near-zero reference std: {skipped_near_zero}"
+                ),
+                skipped_metrics=list(skipped_near_zero),
+            )
         return sum(z_scores) / len(z_scores) if z_scores else 0.0
 
     def reset_anomaly_reference(self, components: Optional[list[str]] = None) -> None:

{margin-0.9.30 → margin-0.9.32/margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.30
+Version: 0.9.32
 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
@@ -86,6 +86,8 @@ Then the correction loop:
 - **Causal** — dependency graphs ("api is DEGRADED because db is ABLATED")
 - **Auto-correlation** — discover which components move together from data, with lag detection
 - **Streaming** — incremental trackers: `Monitor.update(values)` updates health + drift + anomaly + correlation in one call
+- **Flow** — ordered stages with typed live guidance: ADVANCE / HOLD / RETRY / ROLLBACK / ESCALATE for multi-stage processes
+- **Issue** — typed diagnostics: library surfaces its own misconfigurations, degraded assumptions, recovered failures
 - **Config** — define everything in YAML/JSON: `margin.load_config("margin.yaml")`
 - **Persistence** — save/restore Monitor state across restarts, batch replay from CSV
 - **Intent** — goal feasibility: `intent.evaluate_monitor(monitor)` → FEASIBLE / AT_RISK / INFEASIBLE with ETA
@@ -123,6 +125,55 @@ Thresholds(intact=0.02, ablated=0.10, higher_is_better=False)
 
 One flag. Threads through every comparison, every sigma calculation, every correction decision, every recovery ratio. You never think about it again.
 
+## Multi-stage process guidance
+
+For processes where each stage has distinct entry/quality/exit criteria — deployment pipelines, fermentation phases, clinical trials, incident response:
+
+```python
+from margin import Flow, Stage, Parser, Thresholds
+
+flow = Flow(stages=[
+    Stage(
+        name="lag",
+        parser=Parser(baselines={"biomass": 0.1}, thresholds=Thresholds(intact=0.08, ablated=0.02)),
+        advance_when=lambda expr: expr.observations[0].value >= 0.15,
+    ),
+    Stage(name="exponential", parser=..., advance_when=...),
+    Stage(name="stationary", parser=...),
+], label="ferment")
+
+result = flow.observe({"biomass": 0.12})
+print(result.to_atom())
+# flow:ferment:lag[1/3] → HOLD
+
+# When the advance_when predicate fires:
+result = flow.observe({"biomass": 0.18})
+# result.guidance == Guidance.ADVANCE
+flow.advance()
+```
+
+Predicate exceptions are caught as ERROR issues, guidance degrades to HOLD, the flow stays alive — safety-first semantics for safety-critical contexts.
+
+## Typed diagnostics
+
+The library surfaces its own operational state the same way it classifies observed state:
+
+```python
+monitor.update({"mystery": 1.0})       # emits WARNING: BASELINE_MISSING
+monitor.drift("unknown")                # emits WARNING: UNKNOWN_COMPONENT
+
+# Query it programmatically
+monitor.issues.by_code("BASELINE_MISSING")       # [Issue(...)]
+monitor.issues.at_least(IssueLevel.WARNING)       # all severe enough
+monitor.diagnose()                                # JSON-safe dashboard summary
+
+# Bridge to your logger
+import logging
+monitor.issues.attach_logger(logging.getLogger("margin"))
+```
+
+**Harvest-safe on hard fail:** if `Monitor.update()` or `Flow.observe()` raises, a `FATAL(INTERNAL_ERROR)` issue is recorded *before* the exception propagates. `monitor.issues` survives crashes intact.
+
 ## Auto-calibrate from data
 
 Don't guess thresholds. Derive them from healthy measurements:
@@ -147,8 +198,10 @@ parser = parser_from_calibration(
 | **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` |
+| **Flow** | What stage are we in, and what should we do? | `Flow`, `Stage`, `Guidance`, `FlowResult` |
+| **Issue** | What did the library notice about itself? | `Issue`, `IssueLevel`, `IssueBuffer`, `IssueCode` |
 
-`full_step()` orchestrates all seven in one call.
+`full_step()` orchestrates the first seven in one call. `Flow` composes them into a sequence. `Issue` is ambient — every layer emits diagnostics into the same buffer.
 
 ## Domain adapters
 

{margin-0.9.30 → margin-0.9.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.30"
+version = "0.9.32"
 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.30 → margin-0.9.32}/tests/test_issue.py

@@ -5,6 +5,8 @@ Emphasis on harvestability on hard fail: if a Monitor or Flow method
 raises an exception, the diagnostic record should be intact in the
 buffer, not lost.
 """
+import json
+import logging
 import pytest
 
 from margin import (
@@ -237,8 +239,9 @@ class TestMonitorIssues:
         m = self._monitor(baselines={})
         with pytest.warns(UserWarning):
             m.update({"x": 1.0})
-        assert len(m.issues) == 1
-        assert m.issues.tail(1)[0].code == IssueCode.BASELINE_MISSING
+        # BASELINE_MISSING from parser, plus INSUFFICIENT_SAMPLES from
+        # freshly-created drift/anomaly trackers warming up.
+        assert len(m.issues.by_code(IssueCode.BASELINE_MISSING)) == 1
 
     def test_monitor_issues_accumulate(self):
         m = self._monitor(baselines={})
@@ -246,7 +249,8 @@ class TestMonitorIssues:
             m.update({"a": 1.0})
             m.update({"b": 1.0})
             m.update({"c": 1.0})
-        assert len(m.issues) == 3
+        # One BASELINE_MISSING per unique component (parser emits per unknown)
+        assert len(m.issues.by_code(IssueCode.BASELINE_MISSING)) == 3
 
     def test_monitor_diagnose(self):
         m = self._monitor(baselines={})
@@ -254,7 +258,6 @@ class TestMonitorIssues:
             m.update({"a": 1.0})
             m.update({"b": 1.0})
         d = m.diagnose()
-        assert d["total"] == 2
         assert d["codes"][IssueCode.BASELINE_MISSING] == 2
 
     def test_hard_fail_captures_fatal_issue(self):
@@ -289,7 +292,8 @@ class TestMonitorIssues:
         m = self._monitor(baselines={})
         with pytest.warns(UserWarning):
             m.update({"known_missing": 1.0})
-        assert len(m.issues) == 1
+        # At least one BASELINE_MISSING WARNING (plus warming-up INFOs)
+        assert len(m.issues.by_level(IssueLevel.WARNING)) >= 1
 
         class _Boom(Exception): pass
         orig = m.parser.parse
@@ -299,8 +303,7 @@ class TestMonitorIssues:
         m.parser.parse = orig
 
         # Original WARNING is still there, plus a FATAL.
-        assert len(m.issues) == 2
-        assert len(m.issues.by_level(IssueLevel.WARNING)) == 1
+        assert len(m.issues.by_level(IssueLevel.WARNING)) >= 1
         assert len(m.issues.by_level(IssueLevel.FATAL)) == 1
 
 
@@ -448,3 +451,240 @@ class TestFlowResultAtomWithIssues:
         # No issues this step, so no suffix parenthetical
         assert "(" not in r.to_atom() or "step" not in r.to_atom().lower()
         assert r.to_atom() == "flow:ferment:lag[1/1] → HOLD"
+
+
+# ---------------------------------------------------------------------------
+# v0.9.31 additions — full emission coverage
+# ---------------------------------------------------------------------------
+
+class TestDiagnoseSerialization:
+    def test_diagnose_is_json_serializable_by_default(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        m.update({"cpu": 50.0})
+        m.drift("nonexistent")  # emits UNKNOWN_COMPONENT
+        d = m.diagnose()
+        # Must round-trip through JSON cleanly.
+        s = json.dumps(d)
+        restored = json.loads(s)
+        assert restored["total"] == d["total"]
+        assert isinstance(restored["recent"], list)
+        # Recent entries are dicts, not Issue objects.
+        assert all(isinstance(r, dict) for r in restored["recent"])
+
+    def test_diagnose_serialize_false_returns_issue_objects(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        m.drift("nonexistent")
+        d = m.diagnose(serialize=False)
+        assert all(isinstance(r, Issue) for r in d["recent"])
+
+
+class TestAttachLogger:
+    def test_attach_logger_mirrors_emissions(self):
+        logger = logging.getLogger("margin.test.attach")
+        logger.setLevel(logging.DEBUG)
+        records = []
+        handler = logging.Handler()
+        handler.emit = lambda r: records.append(r)
+        logger.addHandler(handler)
+
+        b = IssueBuffer()
+        b.attach_logger(logger)
+        b.emit(IssueLevel.WARNING, "BASELINE_MISSING", "x", component="cpu")
+        b.emit(IssueLevel.FATAL, "INTERNAL_ERROR", "boom")
+
+        assert len(records) == 2
+        assert records[0].levelno == logging.WARNING
+        assert "BASELINE_MISSING" in records[0].getMessage()
+        assert records[0].margin_code == "BASELINE_MISSING"
+        assert records[0].margin_component == "cpu"
+        assert records[1].levelno == logging.CRITICAL
+
+    def test_detach_logger_stops_mirroring(self):
+        logger = logging.getLogger("margin.test.detach")
+        logger.setLevel(logging.DEBUG)
+        records = []
+        handler = logging.Handler()
+        handler.emit = lambda r: records.append(r)
+        logger.addHandler(handler)
+
+        b = IssueBuffer()
+        b.attach_logger(logger)
+        b.emit(IssueLevel.INFO, "X")
+        b.detach_logger()
+        b.emit(IssueLevel.INFO, "Y")
+        assert len(records) == 1
+
+    def test_logger_level_map_override(self):
+        logger = logging.getLogger("margin.test.levelmap")
+        logger.setLevel(logging.DEBUG)
+        records = []
+        handler = logging.Handler()
+        handler.emit = lambda r: records.append(r)
+        logger.addHandler(handler)
+
+        b = IssueBuffer()
+        # Map INFO to DEBUG so INFO-level issues don't spam user logs
+        b.attach_logger(logger, level_map={IssueLevel.INFO: logging.DEBUG})
+        b.emit(IssueLevel.INFO, "X")
+        # INFO → DEBUG, mirrored at DEBUG level
+        assert len(records) == 1 and records[0].levelno == logging.DEBUG
+
+    def test_logger_failure_does_not_break_buffer(self):
+        class BrokenLogger:
+            def log(self, *a, **kw):
+                raise RuntimeError("logger broken")
+
+        b = IssueBuffer()
+        b.attach_logger(BrokenLogger())
+        # Must not raise
+        b.emit(IssueLevel.INFO, "X")
+        assert len(b) == 1
+
+
+class TestInsufficientSamplesEmission:
+    def test_warming_up_emits_info_once_per_component(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        m.update({"cpu": 50.0})
+        m.update({"cpu": 50.0})
+        m.update({"cpu": 50.0})
+        # drift tracker below min_samples (default 3) for the first call,
+        # graduates at the third — we should see exactly one INFO per tracker
+        # (drift + anomaly) during warming, not one per call.
+        insufficient = m.issues.by_code(IssueCode.INSUFFICIENT_SAMPLES)
+        # At most one per tracker kind (drift + anomaly)
+        assert len(insufficient) <= 2
+
+    def test_insufficient_samples_cleared_after_graduation(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        for _ in range(20):
+            m.update({"cpu": 50.0})
+        # Drift should have classified by now; warming-up flag cleared.
+        assert "cpu" not in m._drift_warming
+
+
+class TestUnknownComponentEmission:
+    def test_unknown_component_emits_once(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        assert m.drift("nonexistent") is None
+        assert m.drift("nonexistent") is None  # repeated query
+        assert m.drift("nonexistent") is None
+        unknowns = m.issues.by_code(IssueCode.UNKNOWN_COMPONENT)
+        assert len(unknowns) == 1
+        assert unknowns[0].component == "nonexistent"
+
+    def test_unknown_component_different_methods_separate_emission(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        m.drift("missing")
+        m.anomaly("missing")  # different call site → separate emission
+        unknowns = m.issues.by_code(IssueCode.UNKNOWN_COMPONENT)
+        assert len(unknowns) == 2
+
+
+class TestNearZeroStdEmission:
+    def test_anomaly_score_emits_near_zero_std(self):
+        from margin import Fingerprint
+        m = Monitor(
+            Parser(baselines={"x": 1.0}, thresholds=Thresholds(intact=0.8, ablated=0.2)),
+            window=20,
+        )
+        for _ in range(10):
+            m.update({"x": 1.0})  # constant — std essentially 0
+        current = m.fingerprint()
+        # Construct a reference fingerprint with near-zero std
+        ref = Fingerprint(stats={
+            "x": {"mean": 1.0, "std": 0.0, "n": 10, "trend": "STABLE"}
+        })
+        score = m.anomaly_score(ref)
+        # Skipped metric → NEAR_ZERO_STD issue
+        near_zero = m.issues.by_code(IssueCode.NEAR_ZERO_STD)
+        assert len(near_zero) == 1
+        assert "x" in near_zero[0].context.get("skipped_metrics", [])
+
+
+class TestStageAblatedOnEntry:
+    def test_emits_warning_when_first_obs_ablated(self):
+        stage = Stage(
+            name="init",
+            parser=Parser(
+                baselines={"cpu": 50.0},
+                thresholds=Thresholds(intact=40, ablated=30),
+            ),
+        )
+        f = Flow(stages=[stage], label="test")
+        # Value way below ablated threshold → ABLATED on first obs
+        result = f.observe({"cpu": 5.0})
+        entry_issues = f.issues.by_code(IssueCode.STAGE_ABLATED_ON_ENTRY)
+        assert len(entry_issues) == 1
+        assert entry_issues[0].component == "init"
+        assert "cpu" in entry_issues[0].context.get("ablated_components", [])
+        # Also attached to the step result
+        assert any(i.code == IssueCode.STAGE_ABLATED_ON_ENTRY for i in result.issues)
+
+    def test_no_emission_when_first_obs_healthy(self):
+        stage = Stage(
+            name="init",
+            parser=Parser(
+                baselines={"cpu": 50.0},
+                thresholds=Thresholds(intact=40, ablated=10),
+            ),
+        )
+        f = Flow(stages=[stage])
+        f.observe({"cpu": 50.0})
+        assert len(f.issues.by_code(IssueCode.STAGE_ABLATED_ON_ENTRY)) == 0
+
+    def test_emission_only_on_first_obs_not_later(self):
+        """If stage degrades on step 2, we don't re-emit STAGE_ABLATED_ON_ENTRY."""
+        stage = Stage(
+            name="init",
+            parser=Parser(
+                baselines={"cpu": 50.0},
+                thresholds=Thresholds(intact=40, ablated=10),
+            ),
+        )
+        f = Flow(stages=[stage])
+        f.observe({"cpu": 50.0})   # healthy first obs
+        f.observe({"cpu": 5.0})    # ABLATED second obs — not entry
+        entry_issues = f.issues.by_code(IssueCode.STAGE_ABLATED_ON_ENTRY)
+        assert len(entry_issues) == 0
+
+
+class TestStatusIncludesIssues:
+    def test_status_includes_issues_key(self):
+        m = Monitor(
+            Parser(baselines={"x": 1.0}, thresholds=Thresholds(intact=0.8, ablated=0.2)),
+            window=20,
+        )
+        m.update({"x": 1.0})
+        s = m.status()
+        assert "issues" in s
+        assert "total" in s["issues"]
+        assert "counts" in s["issues"]
+
+    def test_status_issues_are_json_serializable(self):
+        m = Monitor(
+            Parser(baselines={"cpu": 50.0}, thresholds=Thresholds(intact=40, ablated=10)),
+            window=20,
+        )
+        m.update({"cpu": 50.0})
+        m.drift("nonexistent")  # emits UNKNOWN_COMPONENT
+        s = m.status()
+        # Full status() must be json-safe — that's the dashboard contract.
+        json.dumps(s)