margin 0.9.28__tar.gz → 0.9.30__tar.gz

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

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

@@ -120,6 +120,9 @@ from .intent import (
 # Loop
 from .loop import StepResult, step, run, FullStepResult, full_step
 
+# Issue (diagnostics)
+from .issue import Issue, IssueLevel, IssueCode, IssueBuffer, ISSUE_SEVERITY
+
 # Flow
 from .flow import Flow, Stage, Guidance, FlowResult, GUIDANCE_SEVERITY
 
@@ -193,6 +196,8 @@ __all__ = [
     "save_monitor", "load_monitor", "replay", "replay_csv",
     # Loop
     "StepResult", "step", "run", "FullStepResult", "full_step",
+    # Issue (diagnostics)
+    "Issue", "IssueLevel", "IssueCode", "IssueBuffer", "ISSUE_SEVERITY",
     # Flow
     "Flow", "Stage", "Guidance", "FlowResult", "GUIDANCE_SEVERITY",
     # margin-poc compat aliases

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

@@ -55,12 +55,13 @@ 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
 
 from .health import Health
+from .issue import Issue, IssueBuffer, IssueCode, IssueLevel
 from .observation import Expression, Parser
 from .streaming import Monitor
 
@@ -143,29 +144,63 @@ class Stage:
 @dataclass
 class FlowResult:
     """Returned from Flow.observe() and flow advancement helpers."""
+    flow_label: str
     stage: str
     stage_index: int
     total_stages: int
     expression: Optional[Expression]
     guidance: Guidance
     reason: str
+    issues: List[Issue] = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.issues is None:
+            self.issues = []
 
     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"
+        suffix = ""
+        if self.issues:
+            # Annotate with issue counts by level, in severity order.
+            marks = []
+            from .issue import IssueLevel as _IL
+            counts = {l: 0 for l in _IL}
+            for iss in self.issues:
+                counts[iss.level] += 1
+            level_marks = [
+                (_IL.FATAL, "‼"),
+                (_IL.ERROR, "!"),
+                (_IL.WARNING, "⚠"),
+                (_IL.INFO, "·"),
+            ]
+            for lvl, m in level_marks:
+                if counts[lvl] > 0:
+                    marks.append(f"{m}{counts[lvl]}")
+            if marks:
+                suffix = " (" + " ".join(marks) + ")"
         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}]{suffix}"
         return (
-            f"flow:{self.stage}[{self.stage_index + 1}/{self.total_stages}]"
-            f" → {self.guidance.value}"
+            f"{prefix}:{self.stage}[{self.stage_index + 1}/{self.total_stages}]"
+            f" → {self.guidance.value}{suffix}"
         )
 
     def to_dict(self) -> dict:
-        return {
+        d = {
+            "flow_label": self.flow_label,
             "stage": self.stage,
             "stage_index": self.stage_index,
             "total_stages": self.total_stages,
@@ -173,6 +208,9 @@ class FlowResult:
             "reason": self.reason,
             "expression": self.expression.to_dict() if self.expression else None,
         }
+        if self.issues:
+            d["issues"] = [i.to_dict() for i in self.issues]
+        return d
 
     def __repr__(self) -> str:
         return f"FlowResult({self.to_atom()} — {self.reason})"
@@ -194,6 +232,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__(
@@ -214,6 +282,21 @@ class Flow:
         }
         self._transitions: List[dict] = []
         self._entered_at: datetime = datetime.now()
+        self._issues: IssueBuffer = IssueBuffer()
+
+        # Emit INFO if a stage has no predicates at all (will HOLD forever)
+        for s in self.stages:
+            if (s.advance_when is None and s.retry_when is None
+                    and s.escalate_when is None and s.rollback_when is None):
+                self._issues.emit(
+                    IssueLevel.INFO,
+                    IssueCode.NO_PREDICATES,
+                    detail=(
+                        f"stage {s.name!r} has no predicates; will only leave "
+                        "via explicit advance()/rollback()."
+                    ),
+                    component=s.name,
+                )
 
     # ------------------------------------------------------------------
     # Inspection
@@ -246,6 +329,15 @@ class Flow:
         """History of stage transitions."""
         return list(self._transitions)
 
+    @property
+    def issues(self) -> IssueBuffer:
+        """IssueBuffer of diagnostics this Flow has emitted.  Harvestable."""
+        return self._issues
+
+    def diagnose(self, n: int = 10) -> dict:
+        """Dashboard-friendly summary of recent issues.  See IssueBuffer.diagnose."""
+        return self._issues.diagnose(n)
+
     # ------------------------------------------------------------------
     # Observation
     # ------------------------------------------------------------------
@@ -256,42 +348,121 @@ class Flow:
 
         ``values`` and any kwargs are forwarded to ``Monitor.update()``, so
         confidences, absences, and provenance all pass through.
+
+        Hard-fail semantics: if the underlying Monitor raises, the issue
+        is captured as FATAL on the Flow buffer and re-raised.  Predicate
+        exceptions are caught (not re-raised), recorded as ERROR issues,
+        and guidance degrades to HOLD with a ``predicate failure`` reason.
         """
+        import traceback as _tb
+
         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),
                 expression=None,
                 guidance=Guidance.COMPLETE,
                 reason="all stages complete",
+                issues=[],
             )
 
         stage = self.current
         monitor = self._monitors[stage.name]
-        expr = monitor.update(values, **kw)
-        guidance, reason = self._classify(stage, expr)
+        try:
+            expr = monitor.update(values, **kw)
+        except Exception as _e:
+            self._issues.emit(
+                IssueLevel.FATAL,
+                IssueCode.INTERNAL_ERROR,
+                detail=f"Monitor.update raised in stage {stage.name!r}: {_e}",
+                component=stage.name,
+                exc_type=type(_e).__name__,
+                traceback=_tb.format_exc(),
+            )
+            raise
+
+        # Collect issues produced this step: Parser's issues are on expr,
+        # predicate failures are emitted during _classify.
+        step_issues: List[Issue] = list(expr.issues)
+        guidance, reason = self._classify(stage, expr, step_issues)
 
         return FlowResult(
+            flow_label=self.label,
             stage=stage.name,
             stage_index=self._index,
             total_stages=len(self.stages),
             expression=expr,
             guidance=guidance,
             reason=reason,
+            issues=step_issues,
         )
 
-    def _classify(self, stage: Stage, expr: Expression) -> tuple[Guidance, str]:
-        """Evaluate stage predicates in severity order."""
+    def _safe_predicate(
+        self,
+        predicate,
+        expr: Expression,
+        name: str,
+        stage_name: str,
+        collected: List[Issue],
+    ) -> Optional[bool]:
+        """
+        Call a stage predicate, capturing any exception as an ERROR issue.
+        Returns None on failure (distinguishable from False), the bool result
+        on success.  Issues go both on the Flow buffer (for post-mortem) and
+        in ``collected`` (for the FlowResult this step).
+        """
+        try:
+            return bool(predicate(expr))
+        except Exception as _e:
+            import traceback as _tb
+            iss = self._issues.emit(
+                IssueLevel.ERROR,
+                IssueCode.PREDICATE_FAILURE,
+                detail=f"{name} raised in stage {stage_name!r}: {_e}",
+                component=stage_name,
+                predicate=name,
+                exc_type=type(_e).__name__,
+                traceback=_tb.format_exc(),
+            )
+            collected.append(iss)
+            return None
+
+    def _classify(
+        self, stage: Stage, expr: Expression, collected: List[Issue],
+    ) -> tuple[Guidance, str]:
+        """Evaluate stage predicates in severity order, safely."""
         # 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"
+        if stage.escalate_when is not None:
+            fired = self._safe_predicate(
+                stage.escalate_when, expr, "escalate_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.ESCALATE, "escalate_when fired"
+        if stage.rollback_when is not None:
+            fired = self._safe_predicate(
+                stage.rollback_when, expr, "rollback_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.ROLLBACK, "rollback_when fired"
+        if stage.advance_when is not None:
+            fired = self._safe_predicate(
+                stage.advance_when, expr, "advance_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.ADVANCE, "advance_when fired"
+        if stage.retry_when is not None:
+            fired = self._safe_predicate(
+                stage.retry_when, expr, "retry_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.RETRY, "retry_when fired"
+
+        # If any predicate raised, surface that in the reason so callers
+        # notice degraded guidance without having to inspect the buffer.
+        if any(i.code == IssueCode.PREDICATE_FAILURE for i in collected):
+            return Guidance.HOLD, "predicate failure — see issues"
 
         # Fallback classification using observation health alone
         if any(o.health == Health.ABLATED for o in expr.observations):
@@ -343,15 +514,17 @@ class Flow:
         return self._status_result("rolled back")
 
     def reset(self) -> None:
-        """Reset to the first stage.  Clears all monitors and transitions."""
+        """Reset to the first stage.  Clears monitors, transitions, and issues."""
         self._index = 0
         self._monitors = {self.stages[0].name: self.stages[0].create_monitor()}
         self._transitions = []
         self._entered_at = datetime.now()
+        self._issues.clear()
 
     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 +533,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.30/margin/issue.py

@@ -0,0 +1,325 @@
+"""
+Issue: typed diagnostics for the margin machinery itself.
+
+Where Health describes the state of what we're observing, and Absence
+describes why a value is missing, Issue describes something the library
+noticed about its own operation: a misconfiguration, a degraded
+assumption, a recovered failure, a near-crash.
+
+Design constraints
+------------------
+
+1. **Usable, not just aesthetic.**  Issues accumulate on long-lived
+   objects (``Monitor._issues``, ``Flow._issues``) and are attached to
+   per-call results (``Expression.issues``, ``FlowResult.issues``).
+   Consumers never have to construct their own Issues — the library
+   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.
+
+3. **Typed, not strings.**  Issue.code is a short stable identifier
+   (``BASELINE_MISSING``, ``PREDICATE_FAILURE``) that consumers can
+   filter and aggregate programmatically — the same way DriftState
+   or Health are typed.
+
+Exceptions vs. Issues
+---------------------
+
+- **Exceptions** mean "your code is broken."  Invalid arguments, wrong
+  types, structural errors.  These raise loudly.
+- **Issues** mean "something worth noting happened in the system we
+  observe or in how we're observing it."  Missing baselines,
+  insufficient samples, near-zero std, recovered predicate failures.
+  These accumulate.
+
+Convenience: ``diagnose()`` on Monitor/Flow returns a grouped summary
+suitable for dashboards or log aggregation.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Deque, Dict, List, Optional
+
+
+# -----------------------------------------------------------------------
+# Level
+# -----------------------------------------------------------------------
+
+class IssueLevel(Enum):
+    """
+    Severity of an Issue.
+
+    INFO:     something worth noting but expected (insufficient samples yet)
+    WARNING:  degraded assumption (baseline missing, near-zero std)
+    ERROR:    recovered failure (predicate raised, continued on fallback)
+    FATAL:    unrecovered failure (exception re-raised after capture)
+    """
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    FATAL = "FATAL"
+
+
+ISSUE_SEVERITY: Dict[IssueLevel, int] = {
+    IssueLevel.INFO: 0,
+    IssueLevel.WARNING: 1,
+    IssueLevel.ERROR: 2,
+    IssueLevel.FATAL: 3,
+}
+
+
+# -----------------------------------------------------------------------
+# Issue
+# -----------------------------------------------------------------------
+
+@dataclass
+class Issue:
+    """
+    One diagnostic event from the margin machinery.
+
+    level:      severity
+    code:       short stable identifier (``BASELINE_MISSING``, etc.)
+    component:  optional component name this issue is scoped to
+    detail:     free-text explanation for a human reader
+    at:         timestamp (defaults to now)
+    context:    optional extra fields — traceback, exc type, source, etc.
+    """
+    level: IssueLevel
+    code: str
+    component: Optional[str] = None
+    detail: str = ""
+    at: datetime = field(default_factory=datetime.now)
+    context: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d: dict = {
+            "level": self.level.value,
+            "code": self.code,
+            "at": self.at.isoformat(),
+        }
+        if self.component is not None:
+            d["component"] = self.component
+        if self.detail:
+            d["detail"] = self.detail
+        if self.context:
+            d["context"] = dict(self.context)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Issue":
+        return cls(
+            level=IssueLevel(d["level"]),
+            code=d["code"],
+            component=d.get("component"),
+            detail=d.get("detail", ""),
+            at=datetime.fromisoformat(d["at"]) if "at" in d else datetime.now(),
+            context=dict(d.get("context", {})),
+        )
+
+    def to_atom(self) -> str:
+        """Compact string: ``!level[code](component)`` — fits alongside observation atoms."""
+        mark = {"INFO": "·", "WARNING": "⚠", "ERROR": "!", "FATAL": "‼"}[self.level.value]
+        if self.component is not None:
+            return f"{mark}{self.level.value}[{self.code}]({self.component})"
+        return f"{mark}{self.level.value}[{self.code}]"
+
+    def __repr__(self) -> str:
+        comp = f", component={self.component!r}" if self.component is not None else ""
+        return f"Issue({self.level.value}, {self.code}{comp}, {self.detail!r})"
+
+
+# -----------------------------------------------------------------------
+# Buffer
+# -----------------------------------------------------------------------
+
+class IssueBuffer:
+    """
+    Bounded ring buffer of Issues with simple query helpers.
+
+    Lives on long-lived objects (Monitor, Flow) so post-mortem inspection
+    survives exceptions and crashes inside library methods.  Bounded so
+    long-running sessions don't accumulate unbounded memory.
+
+    Default capacity is 1000 issues.  For high-rate production, consider
+    periodically exporting with ``drain()`` and clearing.
+    """
+
+    def __init__(self, max_issues: int = 1000):
+        if max_issues < 1:
+            raise ValueError("max_issues must be >= 1")
+        self.max_issues = max_issues
+        self._issues: Deque[Issue] = deque(maxlen=max_issues)
+
+    # ------------------------------------------------------------------
+    # Writing
+    # ------------------------------------------------------------------
+
+    def add(self, issue: Issue) -> Issue:
+        """Append an issue.  Returns the issue for chained access."""
+        self._issues.append(issue)
+        return issue
+
+    def emit(
+        self,
+        level: IssueLevel,
+        code: str,
+        detail: str = "",
+        component: Optional[str] = None,
+        **context: Any,
+    ) -> Issue:
+        """
+        Construct and append an Issue inline.  Returns the issue.
+
+        Convenient at call sites::
+
+            self._issues.emit(IssueLevel.WARNING, "BASELINE_MISSING",
+                              f"component {name!r} has no baseline",
+                              component=name)
+        """
+        return self.add(Issue(
+            level=level,
+            code=code,
+            component=component,
+            detail=detail,
+            context=dict(context) if context else {},
+        ))
+
+    def clear(self) -> None:
+        self._issues.clear()
+
+    def drain(self) -> List[Issue]:
+        """Remove and return all current issues.  Buffer becomes empty."""
+        out = list(self._issues)
+        self._issues.clear()
+        return out
+
+    # ------------------------------------------------------------------
+    # Reading
+    # ------------------------------------------------------------------
+
+    def __len__(self) -> int:
+        return len(self._issues)
+
+    def __iter__(self):
+        return iter(self._issues)
+
+    def __bool__(self) -> bool:
+        return bool(self._issues)
+
+    def to_list(self) -> List[Issue]:
+        """Snapshot copy of all current issues."""
+        return list(self._issues)
+
+    def tail(self, n: int = 10) -> List[Issue]:
+        """Last ``n`` issues (most recent)."""
+        if n <= 0:
+            return []
+        items = list(self._issues)
+        return items[-n:]
+
+    def by_code(self, code: str) -> List[Issue]:
+        return [i for i in self._issues if i.code == code]
+
+    def by_level(self, level: IssueLevel) -> List[Issue]:
+        return [i for i in self._issues if i.level == level]
+
+    def by_component(self, component: str) -> List[Issue]:
+        return [i for i in self._issues if i.component == component]
+
+    def at_least(self, level: IssueLevel) -> List[Issue]:
+        """All issues with severity >= ``level``."""
+        threshold = ISSUE_SEVERITY[level]
+        return [i for i in self._issues if ISSUE_SEVERITY[i.level] >= threshold]
+
+    # ------------------------------------------------------------------
+    # Summarization
+    # ------------------------------------------------------------------
+
+    def counts(self) -> Dict[str, int]:
+        """Count by level.  Result keys are level string values."""
+        out: Dict[str, int] = {l.value: 0 for l in IssueLevel}
+        for i in self._issues:
+            out[i.level.value] += 1
+        return out
+
+    def diagnose(self, n: int = 10) -> Dict[str, Any]:
+        """
+        Human/dashboard-friendly summary.
+
+        Returns::
+
+            {
+                "total": int,
+                "counts": {"INFO": n, "WARNING": n, "ERROR": n, "FATAL": n},
+                "recent": [Issue, ...],      # last n
+                "codes": {"BASELINE_MISSING": n, ...},   # by code
+            }
+        """
+        codes: Dict[str, int] = {}
+        for i in self._issues:
+            codes[i.code] = codes.get(i.code, 0) + 1
+        return {
+            "total": len(self._issues),
+            "counts": self.counts(),
+            "recent": self.tail(n),
+            "codes": codes,
+        }
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict:
+        return {
+            "max_issues": self.max_issues,
+            "issues": [i.to_dict() for i in self._issues],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "IssueBuffer":
+        buf = cls(max_issues=d.get("max_issues", 1000))
+        for item in d.get("issues", []):
+            buf.add(Issue.from_dict(item))
+        return buf
+
+    def __repr__(self) -> str:
+        if not self._issues:
+            return "IssueBuffer(empty)"
+        c = self.counts()
+        parts = [f"{k}={v}" for k, v in c.items() if v > 0]
+        return f"IssueBuffer({len(self._issues)}: {', '.join(parts)})"
+
+
+# -----------------------------------------------------------------------
+# Well-known issue codes
+# -----------------------------------------------------------------------
+
+# These are the codes the margin library itself emits.  Users can define
+# their own codes too — they're just strings.  Centralizing the canonical
+# ones here makes them greppable and documentable.
+
+class IssueCode:
+    # Parser
+    BASELINE_MISSING = "BASELINE_MISSING"           # WARNING
+
+    # Monitor
+    INSUFFICIENT_SAMPLES = "INSUFFICIENT_SAMPLES"   # INFO
+    NEAR_ZERO_STD = "NEAR_ZERO_STD"                 # INFO
+
+    # Flow
+    PREDICATE_FAILURE = "PREDICATE_FAILURE"         # ERROR
+    STAGE_ABLATED_ON_ENTRY = "STAGE_ABLATED_ON_ENTRY"  # WARNING
+    NO_PREDICATES = "NO_PREDICATES"                 # INFO
+
+    # Catch-all for exceptions that were captured as issues before re-raise
+    INTERNAL_ERROR = "INTERNAL_ERROR"               # FATAL
+
+    # User-supplied input problems
+    UNKNOWN_COMPONENT = "UNKNOWN_COMPONENT"         # WARNING