margin 0.9.28__tar.gz → 0.9.29__tar.gz

{margin-0.9.28/margin.egg-info → margin-0.9.29}/PKG-INFO

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

{margin-0.9.28 → margin-0.9.29}/margin/flow.py

@@ -55,7 +55,7 @@ users plug in the full Contract machinery when they need it.
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
 from typing import Callable, Dict, List, Optional
@@ -143,6 +143,7 @@ class Stage:
 @dataclass
 class FlowResult:
     """Returned from Flow.observe() and flow advancement helpers."""
+    flow_label: str
     stage: str
     stage_index: int
     total_stages: int
@@ -152,20 +153,29 @@ class FlowResult:
 
     def to_atom(self) -> str:
         """
-        Compact flow notation.
+        Compact flow notation — consistent format across running and complete states.
+
+        With a flow label::
 
             "flow:fermentation:lag_phase[2/5] → ADVANCE"
-            "flow:fermentation:COMPLETE[5/5]"
+            "flow:fermentation[5/5]"                      # complete
+
+        Without a flow label (empty)::
+
+            "flow:lag_phase[2/5] → ADVANCE"
+            "flow[5/5]"                                    # complete
         """
+        prefix = f"flow:{self.flow_label}" if self.flow_label else "flow"
         if self.guidance == Guidance.COMPLETE:
-            return f"flow:{self.stage}[{self.total_stages}/{self.total_stages}]"
+            return f"{prefix}[{self.total_stages}/{self.total_stages}]"
         return (
-            f"flow:{self.stage}[{self.stage_index + 1}/{self.total_stages}]"
+            f"{prefix}:{self.stage}[{self.stage_index + 1}/{self.total_stages}]"
             f" → {self.guidance.value}"
         )
 
     def to_dict(self) -> dict:
         return {
+            "flow_label": self.flow_label,
             "stage": self.stage,
             "stage_index": self.stage_index,
             "total_stages": self.total_stages,
@@ -194,6 +204,36 @@ class Flow:
     (or a policy layer above) decides whether to call ``advance()``.  This
     keeps the flow deterministic and side-effect free, which matters for
     replay, backtesting, and safety-critical use cases.
+
+    Thread safety
+    -------------
+    Flow is **not thread-safe**.  ``observe()`` mutates the current stage's
+    Monitor window; ``advance()`` and ``rollback()`` mutate the stage index.
+    If you need to observe a flow from multiple threads, wrap it in a lock
+    at the call site.  Per-entity flows in a request/response context (one
+    Flow instance per tracked entity) are the intended pattern.
+
+    Predicate ordering
+    ------------------
+    ``_classify`` evaluates predicates in strict severity order:
+
+        1. ``escalate_when`` (highest — safety gate)
+        2. ``rollback_when``
+        3. ``advance_when``
+        4. ``retry_when``
+
+    A true ``escalate_when`` dominates a true ``advance_when`` — this is
+    intentional.  When a stage is in an escalation condition, we do not
+    advance even if exit criteria are also met.  Safety-first semantics.
+
+    Memory note
+    -----------
+    Each ``advance()`` creates a fresh Monitor for the new stage without
+    pruning the prior stage's Monitor.  For a 50-stage pipeline, 50 Monitor
+    instances accumulate in ``self._monitors``.  This is intentional for
+    debuggability but may matter for very long flows.  A pruning option
+    may be added in a future release; for now, construct a new Flow if
+    memory footprint matters.
     """
 
     def __init__(
@@ -259,6 +299,7 @@ class Flow:
         """
         if self.is_complete:
             return FlowResult(
+                flow_label=self.label,
                 stage=self.label or "flow",
                 stage_index=len(self.stages),
                 total_stages=len(self.stages),
@@ -273,6 +314,7 @@ class Flow:
         guidance, reason = self._classify(stage, expr)
 
         return FlowResult(
+            flow_label=self.label,
             stage=stage.name,
             stage_index=self._index,
             total_stages=len(self.stages),
@@ -352,6 +394,7 @@ class Flow:
     def _status_result(self, reason: str) -> FlowResult:
         if self.is_complete:
             return FlowResult(
+                flow_label=self.label,
                 stage=self.label or "flow",
                 stage_index=len(self.stages),
                 total_stages=len(self.stages),
@@ -360,6 +403,7 @@ class Flow:
                 reason=reason,
             )
         return FlowResult(
+            flow_label=self.label,
             stage=self.current.name,
             stage_index=self._index,
             total_stages=len(self.stages),

{margin-0.9.28 → margin-0.9.29/margin.egg-info}/PKG-INFO

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

{margin-0.9.28 → margin-0.9.29}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.28"
+version = "0.9.29"
 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.28 → margin-0.9.29}/tests/test_flow.py

@@ -4,7 +4,7 @@ import pytest
 from margin import (
     Flow, Stage, Guidance,
     Parser, Thresholds, Health, Confidence,
-    Expression,
+    Expression, Absence,
 )
 
 
@@ -298,23 +298,50 @@ class TestReset:
 # ---------------------------------------------------------------------------
 
 class TestSerialization:
-    def test_to_atom_running(self):
+    def test_to_atom_running_includes_flow_label(self):
         f = Flow(stages=[
             Stage(name="lag", parser=_parser({"m": 1.0})),
             Stage(name="exp", parser=_parser({"m": 1.0})),
         ], label="ferment")
         result = f.observe({"m": 1.0})
         atom = result.to_atom()
-        assert "lag" in atom
-        assert "1/2" in atom
-        assert "HOLD" in atom
+        # Must include: flow_label, stage_name, position, guidance
+        assert atom == "flow:ferment:lag[1/2] → HOLD"
 
-    def test_to_atom_complete(self):
+    def test_to_atom_running_no_label(self):
+        f = Flow(stages=[
+            Stage(name="lag", parser=_parser({"m": 1.0})),
+            Stage(name="exp", parser=_parser({"m": 1.0})),
+        ])
+        result = f.observe({"m": 1.0})
+        assert result.to_atom() == "flow:lag[1/2] → HOLD"
+
+    def test_to_atom_complete_includes_flow_label(self):
         s = Stage(name="only", parser=_parser({"m": 1.0}))
         f = Flow(stages=[s], label="linear")
         f.advance()
         result = f.observe({"m": 1.0})
         assert result.guidance == Guidance.COMPLETE
+        assert result.to_atom() == "flow:linear[1/1]"
+
+    def test_to_atom_complete_no_label(self):
+        s = Stage(name="only", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        f.advance()
+        result = f.observe({"m": 1.0})
+        assert result.to_atom() == "flow[1/1]"
+
+    def test_concurrent_flows_are_distinguishable(self):
+        """Two flows with same stage names but different labels must
+        produce distinguishable atoms — without this, operator dashboards
+        can't tell flows apart."""
+        f1 = Flow(stages=[Stage(name="step", parser=_parser({"m": 1.0}))], label="service_a")
+        f2 = Flow(stages=[Stage(name="step", parser=_parser({"m": 1.0}))], label="service_b")
+        r1 = f1.observe({"m": 1.0})
+        r2 = f2.observe({"m": 1.0})
+        assert r1.to_atom() != r2.to_atom()
+        assert "service_a" in r1.to_atom()
+        assert "service_b" in r2.to_atom()
 
     def test_flow_to_dict(self):
         f = Flow(stages=[
@@ -328,14 +355,68 @@ class TestSerialization:
 
     def test_flow_result_to_dict(self):
         s = Stage(name="a", parser=_parser({"m": 1.0}))
-        f = Flow(stages=[s])
+        f = Flow(stages=[s], label="t")
         result = f.observe({"m": 1.0})
         d = result.to_dict()
         assert d["stage"] == "a"
+        assert d["flow_label"] == "t"
         assert d["guidance"] == "HOLD"
         assert "expression" in d
 
 
+# ---------------------------------------------------------------------------
+# Observe passthrough — absences, confidences
+# ---------------------------------------------------------------------------
+
+class TestObservePassthrough:
+    def test_absences_flow_through(self):
+        """Absences supplied to Flow.observe() must reach the Monitor and
+        produce an OOD observation with typed absence in the Expression."""
+        stage = Stage(
+            name="s",
+            parser=Parser(
+                baselines={"m": 1.0, "n": 1.0},
+                thresholds=Thresholds(intact=0.8, ablated=0.2),
+            ),
+        )
+        f = Flow(stages=[stage])
+        result = f.observe({"m": 1.0}, absences={"n": Absence.SENSOR_FAILED})
+        obs_by_name = {o.name: o for o in result.expression.observations}
+        assert obs_by_name["m"].is_absent is False
+        assert obs_by_name["n"].is_absent is True
+        assert obs_by_name["n"].absence == Absence.SENSOR_FAILED
+
+    def test_confidences_flow_through(self):
+        stage = Stage(name="s", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[stage])
+        result = f.observe({"m": 1.0}, confidences={"m": Confidence.LOW})
+        m = [o for o in result.expression.observations if o.name == "m"][0]
+        assert m.confidence == Confidence.LOW
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+class TestEdgeCases:
+    def test_empty_values_dict(self):
+        """Empty observation should return HOLD and not crash."""
+        stage = Stage(name="s", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[stage])
+        result = f.observe({})
+        assert result.guidance == Guidance.HOLD
+        assert result.expression is not None
+        assert len(result.expression.observations) == 0
+
+    def test_observe_complete_flow_safe(self):
+        """observe() on a complete flow returns COMPLETE, doesn't raise."""
+        f = Flow(stages=[Stage(name="a", parser=_parser({"m": 1.0}))], label="L")
+        f.advance()
+        r = f.observe({"m": 1.0})
+        assert r.guidance == Guidance.COMPLETE
+        assert r.to_atom() == "flow:L[1/1]"
+
+
 # ---------------------------------------------------------------------------
 # Realistic scenario: fermentation
 # ---------------------------------------------------------------------------