margin 0.9.27__tar.gz → 0.9.28__tar.gz

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

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

@@ -120,6 +120,9 @@ from .intent import (
 # Loop
 from .loop import StepResult, step, run, FullStepResult, full_step
 
+# Flow
+from .flow import Flow, Stage, Guidance, FlowResult, GUIDANCE_SEVERITY
+
 __all__ = [
     # Foundation
     "Confidence",
@@ -190,6 +193,8 @@ __all__ = [
     "save_monitor", "load_monitor", "replay", "replay_csv",
     # Loop
     "StepResult", "step", "run", "FullStepResult", "full_step",
+    # Flow
+    "Flow", "Stage", "Guidance", "FlowResult", "GUIDANCE_SEVERITY",
     # margin-poc compat aliases
     "EpistemicSource", "UncertaintyMode",
     "CallConfidence", "CircuitHealth", "GapThresholds", "MarginParser",

margin-0.9.28/margin/flow.py

@@ -0,0 +1,390 @@
+"""
+Flow: ordered sequence of stages with typed guidance.
+
+A Flow is an ordered list of Stage objects, each with its own Parser and
+per-stage Monitor.  Observations are routed to the current stage; the Flow
+emits typed Guidance (ADVANCE / HOLD / RETRY / ROLLBACK / ESCALATE /
+COMPLETE) based on stage health and user-supplied advance/retry/escalate
+predicates.
+
+Minimal use::
+
+    from margin import Flow, Stage, Parser, Thresholds, Guidance
+
+    ferment = Flow(stages=[
+        Stage(
+            name="inoculation",
+            parser=Parser(baselines={"pH": 6.5, "DO": 90}, thresholds=Thresholds(...)),
+            advance_when=lambda expr: expr.health_of("DO") == Health.INTACT,
+        ),
+        Stage(
+            name="lag_phase",
+            parser=Parser(baselines={"pH": 6.3, "biomass": 0.1}, thresholds=Thresholds(...)),
+            advance_when=lambda expr: (expr.health_of("biomass") == Health.INTACT
+                                       and expr.observations[0].sigma > 0.5),
+        ),
+        # ...
+    ], label="fermentation")
+
+    result = ferment.observe({"pH": 6.5, "DO": 88})
+    # → FlowResult(stage="inoculation", guidance=HOLD, reason=...)
+
+    # When ready:
+    result = ferment.observe({"pH": 6.4, "DO": 92})
+    # → FlowResult(stage="inoculation", guidance=ADVANCE, ...)
+    ferment.advance()
+
+    # Compact rendering:
+    result.to_atom()
+    # → "flow:fermentation:inoculation[1/5] → ADVANCE"
+
+Contracts can be used in predicates::
+
+    from margin import Contract, HealthTarget, Health, Ledger
+    contract = Contract(terms=[HealthTarget(component="biomass", target=Health.INTACT)])
+    ledger = Ledger()
+    stage = Stage(
+        name="stationary",
+        parser=parser,
+        advance_when=lambda expr: contract.evaluate(ledger, expr).passed,
+    )
+
+This keeps Flow lightweight (no mandatory Ledger) while letting advanced
+users plug in the full Contract machinery when they need it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Callable, Dict, List, Optional
+
+from .health import Health
+from .observation import Expression, Parser
+from .streaming import Monitor
+
+
+# -----------------------------------------------------------------------
+# Guidance
+# -----------------------------------------------------------------------
+
+class Guidance(Enum):
+    """
+    Recommendation for the current flow state.
+
+    ADVANCE:  exit criteria satisfied — ready to move to the next stage
+    HOLD:     stage running healthy, exit criteria not yet met
+    RETRY:    stage degraded but recoverable; continue observing
+    ROLLBACK: this stage cannot proceed; return to previous stage
+    ESCALATE: cannot proceed automatically — needs human intervention
+    COMPLETE: all stages are done
+    """
+    ADVANCE = "ADVANCE"
+    HOLD = "HOLD"
+    RETRY = "RETRY"
+    ROLLBACK = "ROLLBACK"
+    ESCALATE = "ESCALATE"
+    COMPLETE = "COMPLETE"
+
+
+GUIDANCE_SEVERITY: Dict[Guidance, int] = {
+    Guidance.COMPLETE: 0,
+    Guidance.ADVANCE: 0,
+    Guidance.HOLD: 1,
+    Guidance.RETRY: 2,
+    Guidance.ROLLBACK: 3,
+    Guidance.ESCALATE: 4,
+}
+
+
+# -----------------------------------------------------------------------
+# Stage
+# -----------------------------------------------------------------------
+
+StagePredicate = Callable[[Expression], bool]
+
+
+@dataclass
+class Stage:
+    """
+    One stage in a process flow.
+
+    name:           human-readable stage identifier
+    parser:         Parser for measurements observed during this stage
+    advance_when:   predicate(expr) → True means exit criteria met
+    retry_when:     predicate(expr) → True means stage is degraded-but-recoverable
+    escalate_when:  predicate(expr) → True means stage cannot proceed
+    rollback_when:  predicate(expr) → True means return to the previous stage
+    window:         observation window size for the stage's Monitor (default 20)
+
+    All predicates are optional.  When none fire, Guidance defaults to HOLD.
+    If no explicit predicates are given, the default classifier uses
+    observation health (any ABLATED → ESCALATE, any DEGRADED → RETRY, else HOLD).
+    """
+
+    name: str
+    parser: Parser
+    advance_when: Optional[StagePredicate] = None
+    retry_when: Optional[StagePredicate] = None
+    escalate_when: Optional[StagePredicate] = None
+    rollback_when: Optional[StagePredicate] = None
+    window: int = 20
+
+    def create_monitor(self) -> Monitor:
+        """Fresh Monitor bound to this stage's parser and window."""
+        return Monitor(self.parser, window=self.window)
+
+
+# -----------------------------------------------------------------------
+# FlowResult
+# -----------------------------------------------------------------------
+
+@dataclass
+class FlowResult:
+    """Returned from Flow.observe() and flow advancement helpers."""
+    stage: str
+    stage_index: int
+    total_stages: int
+    expression: Optional[Expression]
+    guidance: Guidance
+    reason: str
+
+    def to_atom(self) -> str:
+        """
+        Compact flow notation.
+
+            "flow:fermentation:lag_phase[2/5] → ADVANCE"
+            "flow:fermentation:COMPLETE[5/5]"
+        """
+        if self.guidance == Guidance.COMPLETE:
+            return f"flow:{self.stage}[{self.total_stages}/{self.total_stages}]"
+        return (
+            f"flow:{self.stage}[{self.stage_index + 1}/{self.total_stages}]"
+            f" → {self.guidance.value}"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "stage": self.stage,
+            "stage_index": self.stage_index,
+            "total_stages": self.total_stages,
+            "guidance": self.guidance.value,
+            "reason": self.reason,
+            "expression": self.expression.to_dict() if self.expression else None,
+        }
+
+    def __repr__(self) -> str:
+        return f"FlowResult({self.to_atom()} — {self.reason})"
+
+
+# -----------------------------------------------------------------------
+# Flow
+# -----------------------------------------------------------------------
+
+class Flow:
+    """
+    An ordered sequence of stages with typed per-step guidance.
+
+    Each stage has its own Monitor, created fresh when the flow enters the
+    stage.  Observations are routed to the current stage only; earlier-stage
+    state is preserved in the transition log.
+
+    Flow does not auto-advance.  ``observe()`` returns guidance; the caller
+    (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.
+    """
+
+    def __init__(
+        self,
+        stages: List[Stage],
+        label: str = "",
+    ):
+        if not stages:
+            raise ValueError("Flow requires at least one stage")
+        names = [s.name for s in stages]
+        if len(set(names)) != len(names):
+            raise ValueError(f"Flow stages must have unique names, got {names}")
+        self.stages: List[Stage] = list(stages)
+        self.label = label
+        self._index = 0
+        self._monitors: Dict[str, Monitor] = {
+            stages[0].name: stages[0].create_monitor()
+        }
+        self._transitions: List[dict] = []
+        self._entered_at: datetime = datetime.now()
+
+    # ------------------------------------------------------------------
+    # Inspection
+    # ------------------------------------------------------------------
+
+    @property
+    def current(self) -> Optional[Stage]:
+        """Current stage, or None if the flow is complete."""
+        if self.is_complete:
+            return None
+        return self.stages[self._index]
+
+    @property
+    def current_monitor(self) -> Optional[Monitor]:
+        """Monitor for the current stage, or None if complete."""
+        if self.is_complete:
+            return None
+        return self._monitors[self.current.name]
+
+    @property
+    def is_complete(self) -> bool:
+        return self._index >= len(self.stages)
+
+    @property
+    def stage_index(self) -> int:
+        return self._index
+
+    @property
+    def transitions(self) -> List[dict]:
+        """History of stage transitions."""
+        return list(self._transitions)
+
+    # ------------------------------------------------------------------
+    # Observation
+    # ------------------------------------------------------------------
+
+    def observe(self, values: Dict[str, float], **kw) -> FlowResult:
+        """
+        Route an observation to the current stage and return guidance.
+
+        ``values`` and any kwargs are forwarded to ``Monitor.update()``, so
+        confidences, absences, and provenance all pass through.
+        """
+        if self.is_complete:
+            return FlowResult(
+                stage=self.label or "flow",
+                stage_index=len(self.stages),
+                total_stages=len(self.stages),
+                expression=None,
+                guidance=Guidance.COMPLETE,
+                reason="all stages complete",
+            )
+
+        stage = self.current
+        monitor = self._monitors[stage.name]
+        expr = monitor.update(values, **kw)
+        guidance, reason = self._classify(stage, expr)
+
+        return FlowResult(
+            stage=stage.name,
+            stage_index=self._index,
+            total_stages=len(self.stages),
+            expression=expr,
+            guidance=guidance,
+            reason=reason,
+        )
+
+    def _classify(self, stage: Stage, expr: Expression) -> tuple[Guidance, str]:
+        """Evaluate stage predicates in severity order."""
+        # Highest severity first — a true escalate dominates an advance
+        if stage.escalate_when is not None and stage.escalate_when(expr):
+            return Guidance.ESCALATE, "escalate_when fired"
+        if stage.rollback_when is not None and stage.rollback_when(expr):
+            return Guidance.ROLLBACK, "rollback_when fired"
+        if stage.advance_when is not None and stage.advance_when(expr):
+            return Guidance.ADVANCE, "advance_when fired"
+        if stage.retry_when is not None and stage.retry_when(expr):
+            return Guidance.RETRY, "retry_when fired"
+
+        # Fallback classification using observation health alone
+        if any(o.health == Health.ABLATED for o in expr.observations):
+            return Guidance.ESCALATE, "component ABLATED"
+        if any(o.health == Health.DEGRADED for o in expr.observations):
+            return Guidance.RETRY, "component DEGRADED"
+        return Guidance.HOLD, "healthy, exit criteria not met"
+
+    # ------------------------------------------------------------------
+    # Stage transitions
+    # ------------------------------------------------------------------
+
+    def advance(self) -> FlowResult:
+        """
+        Move to the next stage.  Creates a fresh Monitor for that stage.
+        Raises if the flow is already complete.
+        """
+        if self.is_complete:
+            raise ValueError("flow is already complete")
+        prev = self.stages[self._index].name
+        self._index += 1
+        self._transitions.append({
+            "from": prev,
+            "to": self.stages[self._index].name if not self.is_complete else "(complete)",
+            "kind": "advance",
+            "at": datetime.now().isoformat(),
+        })
+        if not self.is_complete:
+            self._monitors[self.current.name] = self.current.create_monitor()
+        return self._status_result("advanced")
+
+    def rollback(self) -> FlowResult:
+        """
+        Return to the previous stage.  Creates a fresh Monitor for that stage
+        (prior observations during the rollback target are discarded).
+        Raises if already at the first stage.
+        """
+        if self._index == 0:
+            raise ValueError("cannot rollback from first stage")
+        prev = self.current.name if not self.is_complete else "(complete)"
+        self._index -= 1
+        self._monitors[self.current.name] = self.current.create_monitor()
+        self._transitions.append({
+            "from": prev,
+            "to": self.current.name,
+            "kind": "rollback",
+            "at": datetime.now().isoformat(),
+        })
+        return self._status_result("rolled back")
+
+    def reset(self) -> None:
+        """Reset to the first stage.  Clears all monitors and transitions."""
+        self._index = 0
+        self._monitors = {self.stages[0].name: self.stages[0].create_monitor()}
+        self._transitions = []
+        self._entered_at = datetime.now()
+
+    def _status_result(self, reason: str) -> FlowResult:
+        if self.is_complete:
+            return FlowResult(
+                stage=self.label or "flow",
+                stage_index=len(self.stages),
+                total_stages=len(self.stages),
+                expression=None,
+                guidance=Guidance.COMPLETE,
+                reason=reason,
+            )
+        return FlowResult(
+            stage=self.current.name,
+            stage_index=self._index,
+            total_stages=len(self.stages),
+            expression=None,
+            guidance=Guidance.HOLD,
+            reason=reason,
+        )
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict:
+        """Serialize the flow's current position and transition log."""
+        return {
+            "label": self.label,
+            "stages": [s.name for s in self.stages],
+            "index": self._index,
+            "transitions": list(self._transitions),
+            "entered_at": self._entered_at.isoformat(),
+        }
+
+    def __repr__(self) -> str:
+        if self.is_complete:
+            pos = f"COMPLETE[{len(self.stages)}/{len(self.stages)}]"
+        else:
+            pos = f"{self.current.name}[{self._index + 1}/{len(self.stages)}]"
+        return f"Flow(label={self.label!r}, {pos})"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.27
+Version: 0.9.28
 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.27 → margin-0.9.28}/margin.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ margin/diff.py
 margin/drift.py
 margin/events.py
 margin/fingerprint.py
+margin/flow.py
 margin/forecast.py
 margin/health.py
 margin/intent.py
@@ -60,6 +61,7 @@ tests/test_drift.py
 tests/test_events.py
 tests/test_fingerprint_ext.py
 tests/test_float_tolerance.py
+tests/test_flow.py
 tests/test_forecast.py
 tests/test_health.py
 tests/test_healthcare.py

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

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

@@ -0,0 +1,418 @@
+"""Tests for Flow: ordered stages with typed guidance (v0.9.28)."""
+import pytest
+
+from margin import (
+    Flow, Stage, Guidance,
+    Parser, Thresholds, Health, Confidence,
+    Expression,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _parser(baselines: dict, intact: float = 0.8, ablated: float = 0.2,
+            higher: bool = True) -> Parser:
+    return Parser(
+        baselines=baselines,
+        thresholds=Thresholds(intact=intact, ablated=ablated, higher_is_better=higher),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Guidance enum
+# ---------------------------------------------------------------------------
+
+class TestGuidanceEnum:
+    def test_members(self):
+        assert Guidance.ADVANCE.value == "ADVANCE"
+        assert Guidance.HOLD.value == "HOLD"
+        assert Guidance.RETRY.value == "RETRY"
+        assert Guidance.ROLLBACK.value == "ROLLBACK"
+        assert Guidance.ESCALATE.value == "ESCALATE"
+        assert Guidance.COMPLETE.value == "COMPLETE"
+
+
+# ---------------------------------------------------------------------------
+# Flow construction
+# ---------------------------------------------------------------------------
+
+class TestFlowConstruction:
+    def test_requires_at_least_one_stage(self):
+        with pytest.raises(ValueError, match="at least one stage"):
+            Flow(stages=[])
+
+    def test_rejects_duplicate_stage_names(self):
+        s1 = Stage(name="x", parser=_parser({"m": 1.0}))
+        s2 = Stage(name="x", parser=_parser({"m": 1.0}))
+        with pytest.raises(ValueError, match="unique names"):
+            Flow(stages=[s1, s2])
+
+    def test_starts_at_first_stage(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        assert f.current is s
+        assert f.stage_index == 0
+        assert not f.is_complete
+
+
+# ---------------------------------------------------------------------------
+# Observation routing
+# ---------------------------------------------------------------------------
+
+class TestObserve:
+    def test_observe_returns_flow_result(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        result = f.observe({"m": 1.0})
+        assert result.stage == "init"
+        assert result.stage_index == 0
+        assert result.total_stages == 1
+        assert result.expression is not None
+
+    def test_observe_routed_only_to_current_stage(self):
+        s1 = Stage(name="a", parser=_parser({"m": 1.0}))
+        s2 = Stage(name="b", parser=_parser({"m": 2.0}))
+        f = Flow(stages=[s1, s2])
+        f.observe({"m": 1.0})
+        assert f._monitors["a"].expression is not None
+        assert "b" not in f._monitors or f._monitors.get("b") is None
+
+    def test_healthy_default_guidance_hold(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        result = f.observe({"m": 1.0})
+        assert result.guidance == Guidance.HOLD
+
+    def test_ablated_component_defaults_to_escalate(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}, intact=0.8, ablated=0.5))
+        f = Flow(stages=[s])
+        # Value well below ablated threshold
+        result = f.observe({"m": 0.1})
+        assert result.guidance == Guidance.ESCALATE
+
+    def test_degraded_component_defaults_to_retry(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}, intact=0.8, ablated=0.2))
+        f = Flow(stages=[s])
+        # Value between ablated and intact
+        result = f.observe({"m": 0.5})
+        assert result.guidance == Guidance.RETRY
+
+
+# ---------------------------------------------------------------------------
+# Stage predicates
+# ---------------------------------------------------------------------------
+
+class TestStagePredicates:
+    def test_advance_when_fires(self):
+        s = Stage(
+            name="init",
+            parser=_parser({"m": 1.0}),
+            advance_when=lambda expr: True,
+        )
+        f = Flow(stages=[s])
+        result = f.observe({"m": 1.0})
+        assert result.guidance == Guidance.ADVANCE
+
+    def test_advance_when_inspects_expression(self):
+        s = Stage(
+            name="init",
+            parser=_parser({"m": 1.0}),
+            advance_when=lambda expr: (expr.health_of("m") == Health.INTACT),
+        )
+        f = Flow(stages=[s])
+        assert f.observe({"m": 1.0}).guidance == Guidance.ADVANCE
+        # reset for degraded run
+        f.reset()
+        assert f.observe({"m": 0.5}).guidance == Guidance.RETRY  # default fallback
+
+    def test_escalate_when_overrides_advance(self):
+        s = Stage(
+            name="init",
+            parser=_parser({"m": 1.0}),
+            advance_when=lambda expr: True,
+            escalate_when=lambda expr: True,
+        )
+        f = Flow(stages=[s])
+        # escalate is checked first
+        assert f.observe({"m": 1.0}).guidance == Guidance.ESCALATE
+
+    def test_rollback_when_fires(self):
+        s = Stage(
+            name="init",
+            parser=_parser({"m": 1.0}),
+            rollback_when=lambda expr: True,
+        )
+        f = Flow(stages=[s])
+        assert f.observe({"m": 1.0}).guidance == Guidance.ROLLBACK
+
+    def test_retry_when_fires(self):
+        s = Stage(
+            name="init",
+            parser=_parser({"m": 1.0}),
+            retry_when=lambda expr: True,
+        )
+        f = Flow(stages=[s])
+        result = f.observe({"m": 1.0})
+        assert result.guidance == Guidance.RETRY
+
+
+# ---------------------------------------------------------------------------
+# Advancement
+# ---------------------------------------------------------------------------
+
+class TestAdvance:
+    def _three_stage_flow(self) -> Flow:
+        return Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+            Stage(name="c", parser=_parser({"m": 3.0})),
+        ], label="abc")
+
+    def test_advance_moves_to_next_stage(self):
+        f = self._three_stage_flow()
+        assert f.current.name == "a"
+        f.advance()
+        assert f.current.name == "b"
+        assert f.stage_index == 1
+
+    def test_advance_creates_fresh_monitor(self):
+        f = self._three_stage_flow()
+        f.observe({"m": 1.0})
+        first_monitor = f.current_monitor
+        f.advance()
+        assert f.current_monitor is not first_monitor  # fresh instance
+        assert f.current_monitor.step == 0
+
+    def test_advance_from_last_completes(self):
+        f = self._three_stage_flow()
+        f.advance()  # a → b
+        f.advance()  # b → c
+        f.advance()  # c → complete
+        assert f.is_complete
+        assert f.current is None
+
+    def test_advance_when_complete_raises(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        f.advance()
+        with pytest.raises(ValueError, match="already complete"):
+            f.advance()
+
+    def test_observe_after_complete_returns_complete(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        f.advance()
+        result = f.observe({"m": 1.0})
+        assert result.guidance == Guidance.COMPLETE
+        assert result.expression is None
+
+    def test_transitions_log_advance(self):
+        f = self._three_stage_flow()
+        f.advance()
+        assert len(f.transitions) == 1
+        t = f.transitions[0]
+        assert t["from"] == "a"
+        assert t["to"] == "b"
+        assert t["kind"] == "advance"
+
+    def test_transitions_log_complete(self):
+        s = Stage(name="init", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        f.advance()
+        t = f.transitions[0]
+        assert t["to"] == "(complete)"
+
+
+# ---------------------------------------------------------------------------
+# Rollback
+# ---------------------------------------------------------------------------
+
+class TestRollback:
+    def test_rollback_from_first_raises(self):
+        s = Stage(name="a", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        with pytest.raises(ValueError, match="first stage"):
+            f.rollback()
+
+    def test_rollback_returns_to_previous(self):
+        f = Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+        ])
+        f.advance()
+        assert f.current.name == "b"
+        f.rollback()
+        assert f.current.name == "a"
+
+    def test_rollback_creates_fresh_monitor(self):
+        f = Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+        ])
+        f.observe({"m": 1.0})
+        original_monitor = f._monitors["a"]
+        f.advance()
+        f.rollback()
+        assert f._monitors["a"] is not original_monitor
+
+    def test_rollback_logs_transition(self):
+        f = Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+        ])
+        f.advance()
+        f.rollback()
+        assert f.transitions[-1]["kind"] == "rollback"
+        assert f.transitions[-1]["from"] == "b"
+        assert f.transitions[-1]["to"] == "a"
+
+
+# ---------------------------------------------------------------------------
+# Reset
+# ---------------------------------------------------------------------------
+
+class TestReset:
+    def test_reset_returns_to_first_stage(self):
+        f = Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+        ])
+        f.advance()
+        f.reset()
+        assert f.current.name == "a"
+
+    def test_reset_clears_transitions(self):
+        f = Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+        ])
+        f.advance()
+        f.reset()
+        assert f.transitions == []
+
+
+# ---------------------------------------------------------------------------
+# Serialization and rendering
+# ---------------------------------------------------------------------------
+
+class TestSerialization:
+    def test_to_atom_running(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
+
+    def test_to_atom_complete(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
+
+    def test_flow_to_dict(self):
+        f = Flow(stages=[
+            Stage(name="a", parser=_parser({"m": 1.0})),
+            Stage(name="b", parser=_parser({"m": 2.0})),
+        ], label="test")
+        d = f.to_dict()
+        assert d["label"] == "test"
+        assert d["stages"] == ["a", "b"]
+        assert d["index"] == 0
+
+    def test_flow_result_to_dict(self):
+        s = Stage(name="a", parser=_parser({"m": 1.0}))
+        f = Flow(stages=[s])
+        result = f.observe({"m": 1.0})
+        d = result.to_dict()
+        assert d["stage"] == "a"
+        assert d["guidance"] == "HOLD"
+        assert "expression" in d
+
+
+# ---------------------------------------------------------------------------
+# Realistic scenario: fermentation
+# ---------------------------------------------------------------------------
+
+class TestFermentationScenario:
+    def test_advances_through_lag_then_exponential(self):
+        """Simulate a tiny fermentation: lag → exponential → stationary."""
+        lag = Stage(
+            name="lag",
+            parser=Parser(
+                baselines={"biomass": 0.1},
+                thresholds=Thresholds(intact=0.08, ablated=0.02),
+            ),
+            advance_when=lambda expr: any(
+                o.name == "biomass" and o.value >= 0.15
+                for o in expr.observations
+            ),
+        )
+        expo = Stage(
+            name="exponential",
+            parser=Parser(
+                baselines={"biomass": 0.5},
+                thresholds=Thresholds(intact=0.4, ablated=0.2),
+            ),
+            advance_when=lambda expr: any(
+                o.name == "biomass" and o.value >= 0.8
+                for o in expr.observations
+            ),
+        )
+        stationary = Stage(
+            name="stationary",
+            parser=Parser(
+                baselines={"biomass": 1.0},
+                thresholds=Thresholds(intact=0.8, ablated=0.3),
+            ),
+        )
+
+        flow = Flow(stages=[lag, expo, stationary], label="ferment")
+
+        # Lag phase
+        assert flow.observe({"biomass": 0.10}).guidance == Guidance.HOLD
+        assert flow.observe({"biomass": 0.12}).guidance == Guidance.HOLD
+        assert flow.observe({"biomass": 0.16}).guidance == Guidance.ADVANCE
+        flow.advance()
+
+        # Exponential
+        assert flow.current.name == "exponential"
+        assert flow.observe({"biomass": 0.5}).guidance == Guidance.HOLD
+        assert flow.observe({"biomass": 0.85}).guidance == Guidance.ADVANCE
+        flow.advance()
+
+        # Stationary — no advance_when, default HOLD when healthy
+        assert flow.current.name == "stationary"
+        assert flow.observe({"biomass": 1.0}).guidance == Guidance.HOLD
+        flow.advance()
+        assert flow.is_complete
+
+    def test_stage_specific_thresholds_dont_bleed(self):
+        """Each stage has its own Parser; a value that's intact in stage A
+        could be degraded in stage B."""
+        s1 = Stage(
+            name="lag",
+            parser=Parser(baselines={"biomass": 0.1},
+                          thresholds=Thresholds(intact=0.05, ablated=0.01)),
+        )
+        s2 = Stage(
+            name="exp",
+            parser=Parser(baselines={"biomass": 0.8},
+                          thresholds=Thresholds(intact=0.7, ablated=0.2)),
+        )
+        f = Flow(stages=[s1, s2])
+
+        # 0.1 is intact in lag
+        result = f.observe({"biomass": 0.1})
+        assert result.expression.health_of("biomass") == Health.INTACT
+
+        f.advance()
+        # 0.1 is ablated in exp
+        result = f.observe({"biomass": 0.1})
+        assert result.expression.health_of("biomass") == Health.ABLATED