margin 0.9.31__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.31
+Version: 0.10.0
 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
@@ -34,9 +34,35 @@ Dynamic: license-file
 [![Downloads/month](https://static.pepy.tech/badge/margin/month)](https://pepy.tech/project/margin)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**Typed health classification for systems that measure things.**
+**Typed primitives for system self-awareness.**
 
-Every system with health bars, thresholds, alerts, or status dashboards solves the same problem: take a number, decide if it's healthy, correct it if it isn't, explain what happened. Margin is that pattern, typed once, with the polarity bug fixed.
+When a system has to answer *"how am I doing, and what should I do about it?"* — an LLM agent between steps, an ML pipeline mid-inference, a data job deciding whether to ship — margin gives it the vocabulary. Typed `Health`, `Confidence`, `Absence`, `Issue`, `Flow`, `Intent`, `Contract` — composable, serializable, zero-dependency Python.
+
+```python
+from adapters.agent import agent_parser, AgentStep, agent_flow
+
+parser = agent_parser()
+flow   = agent_flow()                 # plan → act → reflect
+
+# Record what you already measure after one LLM + tool step:
+step = AgentStep(latency_ms=2400, tokens_used=1800,
+                 tool_success_rate=0.9, retry_count=1, confidence=0.72)
+
+expr     = parser.parse(step.to_values())
+guidance = flow.observe(step.to_values())
+
+print(expr.to_string())
+# [latency_ms:INTACT(-0.60σ)] [tokens_used:INTACT(-1.25σ)]
+# [tool_success_rate:INTACT(-0.05σ)] [retry_count:INTACT(+0.00σ)]
+# [confidence:INTACT(-0.10σ)]
+
+print(guidance.to_atom())
+# flow:agent:plan[1/3] → ADVANCE
+```
+
+Every metric is polarity-aware (more tokens = worse, higher confidence = better), sigma-normalised so you can compare them, and emits typed diagnostics when something goes wrong. Nothing stringly-typed; your decision loop reads typed enums.
+
+Not building an agent? Margin works on any scalar with a threshold:
 
 ```python
 from margin import Parser, Thresholds
@@ -48,13 +74,12 @@ parser = Parser(
         "error_rate": Thresholds(intact=0.005, ablated=0.05, higher_is_better=False),
     },
 )
-
 expr = parser.parse({"throughput": 480.0, "error_rate": 0.03})
 print(expr.to_string())
 # [throughput:INTACT(-0.04σ)] [error_rate:DEGRADED(-14.00σ)]
 ```
 
-Throughput and error rate on the same scale. One is higher-is-better, the other is lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
+Throughput and error rate on the same scale. One higher-is-better, the other lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
 
 ## Install
 
@@ -86,6 +111,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 +150,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,33 +223,28 @@ 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
+## Adapters
 
-Ready-to-use threshold profiles for specific domains:
+Core adapters ship in the package. Each is a Parser factory + optional Flow / Intent / Monitor helpers with domain-appropriate thresholds:
 
-| Adapter | What it monitors | Polarity |
-|---|---|---|
-| [**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/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 |
+| Adapter | What it monitors |
+|---|---|
+| [**agent**](https://github.com/Cope-Labs/margin/tree/main/adapters/agent/) | LLM / agent step health — latency, tokens, tool success rate, retries, confidence. Includes a three-stage `plan → act → reflect` Flow and a default feasibility Intent. |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) |
+| [**numpy**](https://github.com/Cope-Labs/margin/tree/main/adapters/numpy/) | Array health (NaN rate, drift, distribution shape) |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) — ASGI middleware |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) — conftest plugin |
+
+Additional domain profiles (healthcare, ros2, transformer circuit interpretability, homeassistant, aquarium, greenhouse, evcharging, fitness, infrastructure, weather, printer3d, neuro, godot, celery, database) live in [`contrib/`](https://github.com/Cope-Labs/margin/tree/main/contrib/) — reference material, not shipped in the pip package.
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md) — a typed grammar for system self-awareness.
 
 ## License
 

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

@@ -5,9 +5,35 @@
 [![Downloads/month](https://static.pepy.tech/badge/margin/month)](https://pepy.tech/project/margin)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-**Typed health classification for systems that measure things.**
+**Typed primitives for system self-awareness.**
 
-Every system with health bars, thresholds, alerts, or status dashboards solves the same problem: take a number, decide if it's healthy, correct it if it isn't, explain what happened. Margin is that pattern, typed once, with the polarity bug fixed.
+When a system has to answer *"how am I doing, and what should I do about it?"* — an LLM agent between steps, an ML pipeline mid-inference, a data job deciding whether to ship — margin gives it the vocabulary. Typed `Health`, `Confidence`, `Absence`, `Issue`, `Flow`, `Intent`, `Contract` — composable, serializable, zero-dependency Python.
+
+```python
+from adapters.agent import agent_parser, AgentStep, agent_flow
+
+parser = agent_parser()
+flow   = agent_flow()                 # plan → act → reflect
+
+# Record what you already measure after one LLM + tool step:
+step = AgentStep(latency_ms=2400, tokens_used=1800,
+                 tool_success_rate=0.9, retry_count=1, confidence=0.72)
+
+expr     = parser.parse(step.to_values())
+guidance = flow.observe(step.to_values())
+
+print(expr.to_string())
+# [latency_ms:INTACT(-0.60σ)] [tokens_used:INTACT(-1.25σ)]
+# [tool_success_rate:INTACT(-0.05σ)] [retry_count:INTACT(+0.00σ)]
+# [confidence:INTACT(-0.10σ)]
+
+print(guidance.to_atom())
+# flow:agent:plan[1/3] → ADVANCE
+```
+
+Every metric is polarity-aware (more tokens = worse, higher confidence = better), sigma-normalised so you can compare them, and emits typed diagnostics when something goes wrong. Nothing stringly-typed; your decision loop reads typed enums.
+
+Not building an agent? Margin works on any scalar with a threshold:
 
 ```python
 from margin import Parser, Thresholds
@@ -19,13 +45,12 @@ parser = Parser(
         "error_rate": Thresholds(intact=0.005, ablated=0.05, higher_is_better=False),
     },
 )
-
 expr = parser.parse({"throughput": 480.0, "error_rate": 0.03})
 print(expr.to_string())
 # [throughput:INTACT(-0.04σ)] [error_rate:DEGRADED(-14.00σ)]
 ```
 
-Throughput and error rate on the same scale. One is higher-is-better, the other is lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
+Throughput and error rate on the same scale. One higher-is-better, the other lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
 
 ## Install
 
@@ -57,6 +82,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 +121,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,33 +194,28 @@ 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
+## Adapters
 
-Ready-to-use threshold profiles for specific domains:
+Core adapters ship in the package. Each is a Parser factory + optional Flow / Intent / Monitor helpers with domain-appropriate thresholds:
 
-| Adapter | What it monitors | Polarity |
-|---|---|---|
-| [**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/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 |
+| Adapter | What it monitors |
+|---|---|
+| [**agent**](https://github.com/Cope-Labs/margin/tree/main/adapters/agent/) | LLM / agent step health — latency, tokens, tool success rate, retries, confidence. Includes a three-stage `plan → act → reflect` Flow and a default feasibility Intent. |
+| [**dataframe**](https://github.com/Cope-Labs/margin/tree/main/adapters/dataframe/) | Data quality (completeness, null rate, drift, freshness, schema) |
+| [**numpy**](https://github.com/Cope-Labs/margin/tree/main/adapters/numpy/) | Array health (NaN rate, drift, distribution shape) |
+| [**fastapi**](https://github.com/Cope-Labs/margin/tree/main/adapters/fastapi/) | Endpoint health (latency, error rate, throughput, queue depth) — ASGI middleware |
+| [**pytest**](https://github.com/Cope-Labs/margin/tree/main/adapters/pytest/) | Test suite health (pass rate, flake rate, coverage, duration) — conftest plugin |
+
+Additional domain profiles (healthcare, ros2, transformer circuit interpretability, homeassistant, aquarium, greenhouse, evcharging, fitness, infrastructure, weather, printer3d, neuro, godot, celery, database) live in [`contrib/`](https://github.com/Cope-Labs/margin/tree/main/contrib/) — reference material, not shipped in the pip package.
 
 ## Docs
 
-Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md)
+Full specification: [margin-language.md](https://github.com/Cope-Labs/margin/blob/main/margin/margin-language.md) — a typed grammar for system self-awareness.
 
 ## License
 

{margin-0.9.31 → margin-0.10.0}/margin/__init__.py

@@ -18,10 +18,10 @@ Structure:
 from .confidence import Confidence
 from .validity import Validity, ValidityMode
 from .provenance import (
-    new_id, _new_id, are_correlated, merge, merge_provenance,
+    new_id, _new_id, are_correlated, merge,
     ProvenanceNode, ProvenanceGraph, create_root_provenance,
 )
-from .uncertain import UncertainValue, Source, EpistemicSource, UncertaintyMode
+from .uncertain import UncertainValue, Source
 from .algebra import add, subtract, multiply, divide, scale, compare, weighted_average
 from .health import Health, Thresholds, classify, SEVERITY
 from .observation import Absence, Op, Observation, Correction, Expression, Parser
@@ -200,24 +200,47 @@ __all__ = [
     "Issue", "IssueLevel", "IssueCode", "IssueBuffer", "ISSUE_SEVERITY",
     # Flow
     "Flow", "Stage", "Guidance", "FlowResult", "GUIDANCE_SEVERITY",
-    # margin-poc compat aliases
-    "EpistemicSource", "UncertaintyMode",
-    "CallConfidence", "CircuitHealth", "GapThresholds", "MarginParser",
-    "CircuitUtterance", "CorrectionOp", "MarginExpression",
-    "CorrectionRequest", "CorrectionRecord", "CorrectionLedger",
-    "classify_gap_health", "compare_to_threshold", "merge_provenance",
 ]
 
-# margin-poc backward-compatible type aliases
-CallConfidence = Confidence
-CircuitHealth = Health
-GapThresholds = Thresholds
-MarginParser = Parser
-CircuitUtterance = Observation
-CorrectionOp = Op
-MarginExpression = Expression
-CorrectionRequest = Correction
-CorrectionRecord = Record
-CorrectionLedger = Ledger
-classify_gap_health = classify
-compare_to_threshold = compare
+# -----------------------------------------------------------------------
+# margin-poc backward-compat aliases
+#
+# These names come from the pre-margin proof-of-concept and are kept
+# importable so downstream code doesn't break on upgrade.  They are
+# NOT part of the public surface (excluded from __all__) and emit a
+# DeprecationWarning on access.  Scheduled for removal at 1.0.
+# -----------------------------------------------------------------------
+
+_DEPRECATED_ALIASES: dict[str, str] = {
+    "CallConfidence":      "Confidence",
+    "CircuitHealth":       "Health",
+    "GapThresholds":       "Thresholds",
+    "MarginParser":        "Parser",
+    "CircuitUtterance":    "Observation",
+    "CorrectionOp":        "Op",
+    "MarginExpression":    "Expression",
+    "CorrectionRequest":   "Correction",
+    "CorrectionRecord":    "Record",
+    "CorrectionLedger":    "Ledger",
+    "classify_gap_health": "classify",
+    "compare_to_threshold": "compare",
+    "merge_provenance":    "merge",
+    "EpistemicSource":     "Source",
+    "UncertaintyMode":     "UncertaintyMode",  # no canonical replacement; plain stub
+}
+
+
+def __getattr__(name: str):
+    import warnings as _warnings
+    canonical = _DEPRECATED_ALIASES.get(name)
+    if canonical is None:
+        raise AttributeError(f"module 'margin' has no attribute {name!r}")
+    _warnings.warn(
+        f"margin.{name} is a deprecated margin-poc alias and will be removed in 1.0; "
+        f"use margin.{canonical} instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if name == "UncertaintyMode":
+        return type("UncertaintyMode", (), {"ABSOLUTE": "absolute", "RELATIVE": "relative"})()
+    return globals()[canonical]

{margin-0.9.31 → margin-0.10.0}/margin/__main__.py

@@ -47,6 +47,9 @@ def cmd_monitor(args):
                     except ValueError:
                         pass
             if not values:
+                preview = line[:60] + ("…" if len(line) > 60 else "")
+                print(f"margin monitor: skipping unparseable line: {preview!r}",
+                      file=sys.stderr)
                 continue
 
         expr = monitor.update(values, now=datetime.now())
@@ -69,6 +72,12 @@ def cmd_monitor(args):
         print("\n".join(parts))
         sys.stdout.flush()
 
+        # Surface any ERROR/FATAL issues emitted during this update to stderr.
+        for issue in expr.issues:
+            if issue.level.value in ("ERROR", "FATAL"):
+                print(f"  ! {issue.to_atom()} {issue.detail}", file=sys.stderr)
+                sys.stderr.flush()
+
 
 def cmd_replay(args):
     """Replay a CSV through Monitor and print analysis."""
@@ -119,6 +128,14 @@ def cmd_replay(args):
         for c in monitor.correlations.strongest(5):
             print(f"  {c.component_a} ~ {c.component_b}: r={c.coefficient:.3f}")
 
+    # Issue summary from the monitor's buffer
+    if getattr(monitor, "issues", None) and len(monitor.issues) > 0:
+        counts = monitor.issues.counts()
+        non_zero = {k: v for k, v in counts.items() if v > 0}
+        if non_zero:
+            print()
+            print("Issues:", ", ".join(f"{k}={v}" for k, v in non_zero.items()))
+
     # Write full output if requested
     if args.output:
         Path(args.output).write_text(json.dumps(snapshots, indent=2))
@@ -148,6 +165,8 @@ def cmd_status(args):
 
     expr = parser.parse(values)
     print(expr.to_string())
+    for issue in expr.issues:
+        print(f"  {issue.to_atom()} {issue.detail}", file=sys.stderr)
 
 
 def main():

{margin-0.9.31 → margin-0.10.0}/margin/causal.py

@@ -314,6 +314,19 @@ class Explanation:
         cause_strs = [c.to_string() for c in self.causes]
         return f"{self.component}:{h} ← " + ", ".join(cause_strs)
 
+    def to_atom(self) -> str:
+        """Compact single-line form for log aggregation.
+
+        ``component:HEALTH`` when there's no known cause,
+        ``component:HEALTH ← source:HEALTH`` otherwise (strongest cause only).
+        """
+        h = self.health.value if self.health else "?"
+        rc = self.root_cause
+        if rc is None:
+            return f"{self.component}:{h}"
+        src_h = rc.source_health.value if rc.source_health else "?"
+        return f"{self.component}:{h} ← {rc.source}:{src_h}"
+
     def to_dict(self) -> dict:
         return {
             "component": self.component,

{margin-0.9.31 → margin-0.10.0}/margin/composite.py

@@ -93,6 +93,8 @@ class CompositeObservation:
         """
         Flatten to a single Observation using the aggregate health.
         Uses the worst sub-observation's value/baseline for sigma.
+        If the worst sub-observation carries an Absence, it propagates to the
+        flattened Observation so downstream consumers don't silently lose the reason.
         """
         w = self.worst
         if w is None:
@@ -110,6 +112,8 @@ class CompositeObservation:
             higher_is_better=w.higher_is_better,
             provenance=w.provenance,
             measured_at=self.measured_at,
+            absence=w.absence,
+            absence_detail=w.absence_detail,
         )
 
     def to_atom(self) -> str:

{margin-0.9.31 → margin-0.10.0}/margin/diff.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass, field
 from typing import Optional
 
 from .health import Health, SEVERITY
-from .observation import Observation, Expression
+from .observation import Absence, Observation, Expression
 from .confidence import Confidence
 
 
@@ -17,22 +17,38 @@ class ComponentChange:
     """
     What changed for a single component between two expressions.
 
-    name:          component identifier
-    health_before: Health in the earlier expression (None if component was absent)
-    health_after:  Health in the later expression (None if component disappeared)
-    sigma_before:  sigma in the earlier expression
-    sigma_after:   sigma in the later expression
+    name:            component identifier
+    health_before:   Health in the earlier expression (None if component was missing)
+    health_after:    Health in the later expression (None if component disappeared)
+    sigma_before:    sigma in the earlier expression
+    sigma_after:     sigma in the later expression
+    absence_before:  Absence reason in the earlier expression (None if present)
+    absence_after:   Absence reason in the later expression (None if present)
     """
     name: str
     health_before: Optional[Health]
     health_after: Optional[Health]
     sigma_before: Optional[float]
     sigma_after: Optional[float]
+    absence_before: Optional[Absence] = None
+    absence_after: Optional[Absence] = None
 
     @property
     def health_changed(self) -> bool:
         return self.health_before != self.health_after
 
+    @property
+    def absence_changed(self) -> bool:
+        return self.absence_before != self.absence_after
+
+    @property
+    def became_absent(self) -> bool:
+        return self.absence_before is None and self.absence_after is not None
+
+    @property
+    def became_present(self) -> bool:
+        return self.absence_before is not None and self.absence_after is None
+
     @property
     def sigma_delta(self) -> Optional[float]:
         """Change in sigma. Positive = healthier. None if either side missing."""
@@ -64,19 +80,26 @@ class ComponentChange:
             return False
         return SEVERITY.get(self.health_after, 0) < SEVERITY.get(self.health_before, 0)
 
+    def _side(self, health: Optional[Health], absence: Optional[Absence]) -> str:
+        if absence is not None:
+            return f"ABSENT({absence.value})"
+        if health is not None:
+            return health.value
+        return "missing"
+
     def to_string(self) -> str:
-        b = self.health_before.value if self.health_before else "absent"
-        a = self.health_after.value if self.health_after else "absent"
-        if not self.health_changed:
-            sd = self.sigma_delta
-            if sd is not None and abs(sd) > 0.001:
-                sign = "+" if sd >= 0 else ""
-                return f"{self.name}: {a} ({sign}{sd:.2f}σ)"
-            return f"{self.name}: {a} (unchanged)"
-        return f"{self.name}: {b} → {a}"
+        b = self._side(self.health_before, self.absence_before)
+        a = self._side(self.health_after, self.absence_after)
+        if self.health_changed or self.absence_changed:
+            return f"{self.name}: {b} → {a}"
+        sd = self.sigma_delta
+        if sd is not None and abs(sd) > 0.001:
+            sign = "+" if sd >= 0 else ""
+            return f"{self.name}: {a} ({sign}{sd:.2f}σ)"
+        return f"{self.name}: {a} (unchanged)"
 
     def to_dict(self) -> dict:
-        return {
+        d = {
             "name": self.name,
             "health_before": self.health_before.value if self.health_before else None,
             "health_after": self.health_after.value if self.health_after else None,
@@ -87,6 +110,13 @@ class ComponentChange:
             "worsened": self.worsened,
             "improved": self.improved,
         }
+        if self.absence_before is not None or self.absence_after is not None:
+            d["absence_before"] = self.absence_before.value if self.absence_before else None
+            d["absence_after"] = self.absence_after.value if self.absence_after else None
+            d["absence_changed"] = self.absence_changed
+            d["became_absent"] = self.became_absent
+            d["became_present"] = self.became_present
+        return d
 
 
 
@@ -127,6 +157,12 @@ class Diff:
     def disappeared(self) -> list[ComponentChange]:
         return [c for c in self.changes if c.disappeared]
 
+    def became_absent(self) -> list[ComponentChange]:
+        return [c for c in self.changes if c.became_absent]
+
+    def became_present(self) -> list[ComponentChange]:
+        return [c for c in self.changes if c.became_present]
+
     def to_string(self) -> str:
         if not self.changes:
             return "(no components)"
@@ -169,6 +205,8 @@ def diff(before: Expression, after: Expression) -> Diff:
             health_after=a.health if a else None,
             sigma_before=b.sigma if b else None,
             sigma_after=a.sigma if a else None,
+            absence_before=b.absence if b else None,
+            absence_after=a.absence if a else None,
         ))
 
     return Diff(