margin 0.9.31__tar.gz → 0.9.32__tar.gz

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

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

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

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

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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.31"
+version = "0.9.32"
 description = "Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened."
 readme = "README.md"
 license = {text = "MIT"}