🔧 Failure(E, L): failure carries accumulated loss — the cost of getting here

Failure now carries the loss that accumulated before it. A pipeline that
runs three Partial steps and fails on the fourth no longer drops the loss.

- Failure(E) → Failure(E, L) throughout
- .eh() bind combines Partial loss into Failure loss
- .compose() propagates loss through failure path
- Eh context accumulates Failure loss before returning Err
- .loss() on Failure returns carried loss (not L::total())
- .err_with_loss() → Option<(E, L)> for when you need both
- From<Result> / From<Option> use L::zero() for fresh failures
- Into<Result> drops loss (the price of going binary)
- 18 new tests for Failure(E, L) behavior
- All docs and examples updated

Co-Authored-By: Mara <mara@systemic.engineer>

Author: Mara

README.md

@@ -17,7 +17,7 @@ use terni::{Imperfect, ConvergenceLoss};
 
 let perfect: Imperfect<u32, String, ConvergenceLoss> = Imperfect::Success(42);
 let lossy = Imperfect::Partial(42, ConvergenceLoss::new(3));
-let failed: Imperfect<u32, String, ConvergenceLoss> = Imperfect::Failure("gone".into());
+let failed: Imperfect<u32, String, ConvergenceLoss> = Imperfect::Failure("gone".into(), ConvergenceLoss::new(0));
 
 assert!(perfect.is_ok());
 assert!(lossy.is_partial());

docs/context.md

@@ -18,12 +18,12 @@ fn process() -> Imperfect<i32, String, ConvergenceLoss> {
 
     let a = match eh.eh(Imperfect::<i32, String, ConvergenceLoss>::Success(10)) {
         Ok(v) => v,
-        Err(e) => return Imperfect::Failure(e),
+        Err(e) => return Imperfect::Failure(e, ConvergenceLoss::zero()),
     };
 
     let b = match eh.eh(Imperfect::<_, String, _>::Partial(a + 5, ConvergenceLoss::new(3))) {
         Ok(v) => v,
-        Err(e) => return Imperfect::Failure(e),
+        Err(e) => return Imperfect::Failure(e, ConvergenceLoss::zero()),
     };
 
     // If any step was Failure, we already returned.
@@ -52,7 +52,7 @@ assert!(eh.loss().is_none());
 
 Extracts the value from an `Imperfect`, accumulating any loss. Returns `Ok(T)` for Success and Partial, `Err(E)` for Failure.
 
-This is where loss gets absorbed into the context. Success adds nothing. Partial adds its loss (via `combine` if loss already exists). Failure returns `Err` immediately.
+This is where loss gets absorbed into the context. Success adds nothing. Partial adds its loss (via `combine` if loss already exists). Failure accumulates its carried loss into the context, then returns `Err`.
 
 ### `.imp()` and `.tri()`
 
@@ -99,25 +99,25 @@ fn parse_and_validate(input: &str) -> Imperfect<i32, String, ConvergenceLoss> {
     // Result operation — parse the input
     let raw: i32 = match input.parse::<i32>() {
         Ok(n) => n,
-        Err(e) => return Imperfect::Failure(e.to_string()),
+        Err(e) => return Imperfect::Failure(e.to_string(), ConvergenceLoss::zero()),
     };
 
     // Imperfect operation — validate range
     let validated = match eh.eh(if raw > 100 {
         Imperfect::Partial(100, ConvergenceLoss::new(1))  // clamped
     } else if raw < 0 {
-        Imperfect::<_, String, _>::Failure("negative".into())
+        Imperfect::<_, String, _>::Failure("negative".into(), ConvergenceLoss::zero())
     } else {
         Imperfect::Success(raw)
     }) {
         Ok(v) => v,
-        Err(e) => return Imperfect::Failure(e),
+        Err(e) => return Imperfect::Failure(e, ConvergenceLoss::zero()),
     };
 
     // Another Result operation
     let doubled = match validated.checked_mul(2) {
         Some(v) => v,
-        None => return Imperfect::Failure("overflow".to_string()),
+        None => return Imperfect::Failure("overflow".to_string(), ConvergenceLoss::zero()),
     };
 
     eh.finish(doubled)
@@ -139,7 +139,7 @@ struct VerifiedPayment { amount: u64, currency: String, risk_score: f64 }
 
 fn verify_amount(p: &Payment) -> Imperfect<u64, String, ConvergenceLoss> {
     if p.amount == 0 {
-        Imperfect::Failure("zero amount".into())
+        Imperfect::Failure("zero amount".into(), ConvergenceLoss::zero())
     } else if p.amount > 10_000 {
         Imperfect::Partial(p.amount, ConvergenceLoss::new(2))  // needs review
     } else {
@@ -151,7 +151,7 @@ fn verify_currency(c: &str) -> Imperfect<String, String, ConvergenceLoss> {
     match c {
         "USD" | "EUR" => Imperfect::Success(c.to_string()),
         "GBP" => Imperfect::Partial(c.to_string(), ConvergenceLoss::new(1)),  // supported but slower
-        _ => Imperfect::Failure(format!("unsupported currency: {}", c)),
+        _ => Imperfect::Failure(format!("unsupported currency: {}", c), ConvergenceLoss::zero()),
     }
 }
 
@@ -160,11 +160,11 @@ fn verify_payment(p: Payment) -> Imperfect<VerifiedPayment, String, ConvergenceL
 
     let amount = match eh.eh(verify_amount(&p)) {
         Ok(v) => v,
-        Err(e) => return Imperfect::Failure(e),
+        Err(e) => return Imperfect::Failure(e, ConvergenceLoss::zero()),
     };
     let currency = match eh.eh(verify_currency(&p.currency)) {
         Ok(v) => v,
-        Err(e) => return Imperfect::Failure(e),
+        Err(e) => return Imperfect::Failure(e, ConvergenceLoss::zero()),
     };
 
     let risk_score = match eh.loss() {

docs/loss-types.md

@@ -16,7 +16,7 @@ pub trait Loss: Clone + Default {
 `Loss` is a monoid with an absorbing element:
 
 - **`zero()`** — the identity. No loss occurred. `combine(zero(), x) == x`.
-- **`total()`** — the annihilator. The transformation destroyed everything. `Failure` reports this.
+- **`total()`** — the annihilator. The transformation destroyed everything. Callers can check `is_err()` to distinguish failure from partial.
 - **`is_zero()`** — test whether this loss is lossless.
 - **`combine()`** — accumulate two losses. Must be associative: `a.combine(b).combine(c) == a.combine(b.combine(c))`.
 

docs/migration.md

@@ -38,7 +38,7 @@ use terni::{Imperfect, ConvergenceLoss};
 fn process(input: &str) -> Imperfect<i32, String, ConvergenceLoss> {
     let n: i32 = match input.parse() {
         Ok(n) => n,
-        Err(e) => return Imperfect::Failure(e.to_string()),
+        Err(e) => return Imperfect::Failure(e.to_string(), ConvergenceLoss::zero()),
     };
     if n > 100 {
         Imperfect::Partial(100, ConvergenceLoss::new(1))  // clamped — loss recorded

docs/pipeline.md

@@ -55,24 +55,26 @@ assert!(result.is_partial());
 assert_eq!(result.loss().steps(), 5);  // max(3, 5) for ConvergenceLoss
 ```
 
-### Anything x Failure = Failure
+### Anything x Failure = Failure (loss carried)
 
-Failure short-circuits. If the input is Failure, `f` is never called. If `f` returns Failure, prior loss is discarded — the value is gone.
+Failure short-circuits. If the input is Failure, `f` is never called. If `f` returns Failure, prior loss is combined with the failure's loss — the value is gone, but the cost of getting here is measured.
 
 ```rust
 use terni::{Imperfect, ConvergenceLoss};
 
-// Failure input: f is never called
-let result = Imperfect::<i32, String, ConvergenceLoss>::Failure("gone".into())
+// Failure input: f is never called, loss preserved
+let result = Imperfect::<i32, String, ConvergenceLoss>::Failure("gone".into(), ConvergenceLoss::new(0))
     .eh(|x| Imperfect::Success(x + 1));
 
 assert!(result.is_err());
+assert!(result.loss().is_zero());
 
-// Partial then failure: loss discarded, only error survives
+// Partial then failure: losses combine
 let result = Imperfect::<i32, String, ConvergenceLoss>::Partial(1, ConvergenceLoss::new(3))
-    .eh(|_| Imperfect::Failure("broke".into()));
+    .eh(|_| Imperfect::<i32, String, ConvergenceLoss>::Failure("broke".into(), ConvergenceLoss::new(5)));
 
 assert!(result.is_err());
+assert_eq!(result.loss().steps(), 5);  // max(3, 5) for ConvergenceLoss
 ```
 
 ## Chaining

docs/terni-functor.md

@@ -8,7 +8,7 @@ A terni-functor is a three-state composition that carries a monoidal annotation
 
 - **Success(T)** — pure value, zero annotation
 - **Partial(T, L)** — value with annotation
-- **Failure(E)** — no value
+- **Failure(E, L)** — no value, but the cost of getting here is measured
 
 The bind operator (`.eh()`) composes these while accumulating the annotation via the `Loss` monoid.
 
@@ -24,9 +24,9 @@ Haskell's `Writer w a` carries a monoidal log alongside a value. `Partial(T, L)`
 
 - `Success` carries no log (it's structurally absent, not zero)
 - `Partial` carries the log
-- `Failure` has no value to log against
+- `Failure` has no value, but carries the accumulated loss from before the failure
 
-This is not `Writer`. `Writer` is `(a, w)`. `Imperfect` is `Success a | Partial a w | Failure e`. The failure path and the "genuinely zero loss" path both exist as distinct states, not as special values of the monoid.
+This is not `Writer`. `Writer` is `(a, w)`. `Imperfect` is `Success a | Partial a w | Failure e w`. The failure path and the "genuinely zero loss" path both exist as distinct states, not as special values of the monoid. Failure carries loss to preserve the cost of computation that preceded it.
 
 ## The monad laws