margin 0.9.26__tar.gz → 0.9.28__tar.gz

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

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.26
+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
-Project-URL: Homepage, https://github.com/sethc5/margin
-Project-URL: Repository, https://github.com/sethc5/margin
-Project-URL: Issues, https://github.com/sethc5/margin/issues
-Project-URL: Changelog, https://github.com/sethc5/margin/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/sethc5/margin#readme
+Project-URL: Homepage, https://copelabs.dev
+Project-URL: Repository, https://github.com/Cope-Labs/margin
+Project-URL: Issues, https://github.com/Cope-Labs/margin/issues
+Project-URL: Changelog, https://github.com/Cope-Labs/margin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Cope-Labs/margin#readme
 Keywords: health,monitoring,uncertainty,observability,typed,classification,threshold,polarity,correction,audit,ledger,policy
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -156,24 +156,24 @@ Ready-to-use threshold profiles for specific domains:
 
 | Adapter | What it monitors | Polarity |
 |---|---|---|
-| [**healthcare**](https://github.com/sethc5/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
+| [**healthcare**](https://github.com/Cope-Labs/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
 | [**godot**](https://github.com/sethc5/margin-godot) | Game systems (food, morale, stress, stamina) — native GDScript | mixed |
-| [**homeassistant**](https://github.com/sethc5/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
-| [**evcharging**](https://github.com/sethc5/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
-| [**infrastructure**](https://github.com/sethc5/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
-| [**aquarium**](https://github.com/sethc5/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
-| [**greenhouse**](https://github.com/sethc5/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
-| [**fitness**](https://github.com/sethc5/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
-| [**transformer**](https://github.com/sethc5/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
-| [**fastapi**](https://github.com/sethc5/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
-| [**database**](https://github.com/sethc5/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
-| [**celery**](https://github.com/sethc5/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
-| [**dataframe**](https://github.com/sethc5/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
-| [**pytest**](https://github.com/sethc5/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
+| [**homeassistant**](https://github.com/Cope-Labs/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
+| [**evcharging**](https://github.com/Cope-Labs/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
+| [**infrastructure**](https://github.com/Cope-Labs/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
+| [**aquarium**](https://github.com/Cope-Labs/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
+| [**greenhouse**](https://github.com/Cope-Labs/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
+| [**fitness**](https://github.com/Cope-Labs/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
+| [**transformer**](https://github.com/Cope-Labs/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
+| [**database**](https://github.com/Cope-Labs/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
+| [**celery**](https://github.com/Cope-Labs/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/sethc5/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
 
 ## License
 

{margin-0.9.26 → margin-0.9.28}/README.md

@@ -127,24 +127,24 @@ Ready-to-use threshold profiles for specific domains:
 
 | Adapter | What it monitors | Polarity |
 |---|---|---|
-| [**healthcare**](https://github.com/sethc5/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
+| [**healthcare**](https://github.com/Cope-Labs/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
 | [**godot**](https://github.com/sethc5/margin-godot) | Game systems (food, morale, stress, stamina) — native GDScript | mixed |
-| [**homeassistant**](https://github.com/sethc5/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
-| [**evcharging**](https://github.com/sethc5/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
-| [**infrastructure**](https://github.com/sethc5/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
-| [**aquarium**](https://github.com/sethc5/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
-| [**greenhouse**](https://github.com/sethc5/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
-| [**fitness**](https://github.com/sethc5/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
-| [**transformer**](https://github.com/sethc5/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
-| [**fastapi**](https://github.com/sethc5/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
-| [**database**](https://github.com/sethc5/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
-| [**celery**](https://github.com/sethc5/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
-| [**dataframe**](https://github.com/sethc5/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
-| [**pytest**](https://github.com/sethc5/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
+| [**homeassistant**](https://github.com/Cope-Labs/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
+| [**evcharging**](https://github.com/Cope-Labs/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
+| [**infrastructure**](https://github.com/Cope-Labs/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
+| [**aquarium**](https://github.com/Cope-Labs/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
+| [**greenhouse**](https://github.com/Cope-Labs/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
+| [**fitness**](https://github.com/Cope-Labs/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
+| [**transformer**](https://github.com/Cope-Labs/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
+| [**database**](https://github.com/Cope-Labs/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
+| [**celery**](https://github.com/Cope-Labs/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/sethc5/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
 
 ## License
 

{margin-0.9.26 → 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.26 → margin-0.9.28/margin.egg-info}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.26
+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
-Project-URL: Homepage, https://github.com/sethc5/margin
-Project-URL: Repository, https://github.com/sethc5/margin
-Project-URL: Issues, https://github.com/sethc5/margin/issues
-Project-URL: Changelog, https://github.com/sethc5/margin/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/sethc5/margin#readme
+Project-URL: Homepage, https://copelabs.dev
+Project-URL: Repository, https://github.com/Cope-Labs/margin
+Project-URL: Issues, https://github.com/Cope-Labs/margin/issues
+Project-URL: Changelog, https://github.com/Cope-Labs/margin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Cope-Labs/margin#readme
 Keywords: health,monitoring,uncertainty,observability,typed,classification,threshold,polarity,correction,audit,ledger,policy
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -156,24 +156,24 @@ Ready-to-use threshold profiles for specific domains:
 
 | Adapter | What it monitors | Polarity |
 |---|---|---|
-| [**healthcare**](https://github.com/sethc5/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
+| [**healthcare**](https://github.com/Cope-Labs/margin/tree/main/adapters/healthcare/) | Vital signs (HR, BP, SpO2, temp, glucose) — WHO/AHA ranges, sepsis screening | bands |
 | [**godot**](https://github.com/sethc5/margin-godot) | Game systems (food, morale, stress, stamina) — native GDScript | mixed |
-| [**homeassistant**](https://github.com/sethc5/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
-| [**evcharging**](https://github.com/sethc5/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
-| [**infrastructure**](https://github.com/sethc5/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
-| [**aquarium**](https://github.com/sethc5/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
-| [**greenhouse**](https://github.com/sethc5/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
-| [**fitness**](https://github.com/sethc5/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
-| [**transformer**](https://github.com/sethc5/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
-| [**fastapi**](https://github.com/sethc5/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
-| [**database**](https://github.com/sethc5/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
-| [**celery**](https://github.com/sethc5/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
-| [**dataframe**](https://github.com/sethc5/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
-| [**pytest**](https://github.com/sethc5/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
+| [**homeassistant**](https://github.com/Cope-Labs/margin/tree/main/adapters/homeassistant/) | Smart home sensors (temp, humidity, battery, solar, power) | mixed |
+| [**evcharging**](https://github.com/Cope-Labs/margin/tree/main/adapters/evcharging/) | EV charging (SoC, grid draw, solar surplus, efficiency) | mixed |
+| [**infrastructure**](https://github.com/Cope-Labs/margin/tree/main/adapters/infrastructure/) | Server monitoring (CPU, memory, disk, latency, error rate) | mixed |
+| [**aquarium**](https://github.com/Cope-Labs/margin/tree/main/adapters/aquarium/) | Water chemistry (pH, ammonia, nitrite, temp, hardness) | bands |
+| [**greenhouse**](https://github.com/Cope-Labs/margin/tree/main/adapters/greenhouse/) | Growing environment (soil moisture, CO₂, light, VPD) | bands |
+| [**fitness**](https://github.com/Cope-Labs/margin/tree/main/adapters/fitness/) | Wearables (resting HR, HRV, sleep, steps, stress) | mixed |
+| [**transformer**](https://github.com/Cope-Labs/margin/tree/main/adapters/transformer/) | ML circuit interpretability (pythia-6.9b) | higher |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) | mixed |
+| [**database**](https://github.com/Cope-Labs/margin/tree/main/adapters/database/) | DB health (pool usage, query latency, replication lag, deadlocks) | mixed |
+| [**celery**](https://github.com/Cope-Labs/margin/tree/main/adapters/celery/) | Task queue (queue depth, failure rate, worker utilization, retries) | mixed |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) | mixed |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) | mixed |
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/sethc5/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
 
 ## License
 

{margin-0.9.26 → 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.26 → margin-0.9.28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.26"
+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"}
@@ -30,11 +30,11 @@ classifiers = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/sethc5/margin"
-Repository = "https://github.com/sethc5/margin"
-Issues = "https://github.com/sethc5/margin/issues"
-Changelog = "https://github.com/sethc5/margin/blob/main/CHANGELOG.md"
-Documentation = "https://github.com/sethc5/margin#readme"
+Homepage = "https://copelabs.dev"
+Repository = "https://github.com/Cope-Labs/margin"
+Issues = "https://github.com/Cope-Labs/margin/issues"
+Changelog = "https://github.com/Cope-Labs/margin/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/Cope-Labs/margin#readme"
 
 [tool.setuptools.packages.find]
 include = ["margin*"]