🔧 final review: v0.5.0 — clippy clean, fmt clean, doc fix, version bump

- Suppressed intentional clippy::bind_instead_of_map in benchmarks (and_then
  chains are deliberate Result baselines, not candidates for map)
- Fixed "EhContext" -> "Eh" in benchmarks.md (type was renamed)
- Applied cargo fmt across benches and lib.rs
- Bumped version 0.4.1 -> 0.5.0
- Included pending README updates (constructors section, new doc links)
- Included pending loss-types.md stdlib Loss documentation
- Included pending flight-recorder.md navigation link

WARN: Collection Loss impls (Vec, HashSet, BTreeSet, String) have total() ==
zero() — the absorbing element property does not hold. Documented in code
comments and loss-types.md. Monoid identity + associativity are sound.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Seam

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "terni"
-version = "0.4.1"
+version = "0.5.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "Ternary error handling: Success, Partial with measured loss, Failure. Because computation is not binary."

README.md

@@ -8,6 +8,8 @@ Ternary error handling for Rust. Because computation is not binary.
 [![docs.rs](https://docs.rs/terni/badge.svg)](https://docs.rs/terni)
 [![license](https://img.shields.io/crates/l/terni.svg)](https://github.com/systemic-engineering/prism/blob/main/imperfect/LICENSE)
 
+**The cost of honesty is 0.65 nanoseconds per step, only when there's something to be honest about. Otherwise: zero.**
+
 ## `eh`
 
 The type. Three states instead of two.
@@ -47,6 +49,21 @@ Three loss types ship with the crate:
 
 The two empty cells on the left are the argument. `Result` doesn't have a row for partial success or honest failure. That's why terni exists.
 
+### Constructors
+
+Four ways to build an `Imperfect`:
+
+```rust
+use terni::{Imperfect, ConvergenceLoss};
+
+let a = Imperfect::<i32, String, ConvergenceLoss>::success(42);
+let b = Imperfect::<i32, String, ConvergenceLoss>::partial(42, ConvergenceLoss::new(3));
+let c = Imperfect::<i32, String, ConvergenceLoss>::failure("gone".into());
+let d = Imperfect::<i32, String, ConvergenceLoss>::failure_with_loss("gone".into(), ConvergenceLoss::new(5));
+```
+
+`.failure()` carries zero loss. `.failure_with_loss()` carries accumulated loss from prior steps.
+
 [Loss types in depth →](docs/loss-types.md) · [Full migration guide →](docs/migration.md)
 
 ## `eh!`
@@ -104,11 +121,13 @@ Block macro for implicit loss accumulation — `eh! { }` will do what `Eh` does
 
 ## More
 
-- [Loss types](docs/loss-types.md) — the `Loss` trait, shipped types, custom implementations
+- [Loss types](docs/loss-types.md) — the `Loss` trait, shipped types, stdlib impls, custom implementations
 - [Pipeline](docs/pipeline.md) — `.eh()` bind in depth, loss accumulation rules
 - [Context](docs/context.md) — `Eh` struct, mixing `Imperfect` and `Result`
 - [Terni-functor](docs/terni-functor.md) — the math behind `.eh()`
 - [Migration](docs/migration.md) — moving from `Result<T, E>` to `Imperfect<T, E, L>`
+- [Flight recorder](docs/flight-recorder.md) — `Failure(E, L)` as production telemetry, not stack traces
+- [Benchmarks](docs/benchmarks.md) — 0.65 ns per honest step, zero on the success path
 
 ## License
 

benches/imperfect.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::bind_instead_of_map)]
 //! Benchmarks for terni — the cost of honesty, measured in nanoseconds.
 //!
 //! The thesis: `.eh()` on the Success path is zero-cost compared to Result's
@@ -74,8 +75,7 @@ fn bench_eh_pipeline(c: &mut Criterion) {
     // 10 chained .eh() on Success — should be within noise of Result
     group.bench_function("Imperfect::eh_success", |b| {
         b.iter(|| {
-            let i: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(1));
+            let i: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(1));
             i.eh(|x| Imperfect::Success(x + 1))
                 .eh(|x| Imperfect::Success(x + 1))
                 .eh(|x| Imperfect::Success(x + 1))
@@ -173,8 +173,7 @@ fn bench_eh_partial(c: &mut Criterion) {
     // Mixed: starts Success, hits Partial midway. Loss appears at step 5.
     group.bench_function("Imperfect::eh_mixed_partial_at_5", |b| {
         b.iter(|| {
-            let i: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(1));
+            let i: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(1));
             i.eh(|x| Imperfect::Success(x + 1))
                 .eh(|x| Imperfect::Success(x + 1))
                 .eh(|x| Imperfect::Success(x + 1))
@@ -216,8 +215,7 @@ fn bench_recover(c: &mut Criterion) {
     // Recovery from success (passthrough — no work)
     group.bench_function("Imperfect::recover_noop", |b| {
         b.iter(|| {
-            let i: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(42));
+            let i: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(42));
             i.recover(|_e| Imperfect::Success(0))
         })
     });
@@ -241,8 +239,7 @@ fn bench_map(c: &mut Criterion) {
 
     group.bench_function("Imperfect::map_success", |b| {
         b.iter(|| {
-            let i: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(42));
+            let i: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(42));
             i.map(|x| x * 2)
         })
     });
@@ -275,10 +272,8 @@ fn bench_compose(c: &mut Criterion) {
 
     group.bench_function("success_then_success", |b| {
         b.iter(|| {
-            let a: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(1));
-            let next: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(2));
+            let a: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(1));
+            let next: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(2));
             a.compose(next)
         })
     });
@@ -297,8 +292,7 @@ fn bench_compose(c: &mut Criterion) {
         b.iter(|| {
             let a: Imperfect<i32, String, ConvergenceLoss> =
                 Imperfect::Failure(black_box(String::from("nope")), ConvergenceLoss::new(1));
-            let next: Imperfect<i32, String, ConvergenceLoss> =
-                Imperfect::Success(black_box(2));
+            let next: Imperfect<i32, String, ConvergenceLoss> = Imperfect::Success(black_box(2));
             a.compose(next)
         })
     });

docs/benchmarks.md

@@ -66,7 +66,7 @@ Same pattern. Success tracks Result. Partial adds the loss-preservation cost.
 | All Success | 648 ps |
 | All Partial | 6.06 ns |
 
-The `EhContext` struct adds zero overhead beyond the loss accumulation itself. Same performance characteristics as raw `eh` chains. The context is a zero-cost coordinator.
+The `Eh` struct adds zero overhead beyond the loss accumulation itself. Same performance characteristics as raw `eh` chains. The context is a zero-cost coordinator.
 
 ### Loss type combination
 
@@ -83,3 +83,5 @@ ConvergenceLoss and RoutingLoss combine in under 1 ns. They're scalar max operat
 Result is a two-state type that optimizes for the fast path by *deleting the middle*. Imperfect is a three-state type that preserves it. The benchmarks say: preservation is free until there's something to preserve. Then it costs 0.65 ns per step.
 
 That's not a tax. That's a price. And it buys you the flight recorder that Result said you couldn't have.
+
+[Back to README](../README.md) · [Flight recorder →](flight-recorder.md) · [Pipeline →](pipeline.md)

docs/flight-recorder.md

@@ -126,3 +126,5 @@ and "Always on." Result doesn't have answers for these because Result can't
 represent them. The type doesn't have a place to put the information.
 
 Those empty cells are why this crate exists.
+
+[Back to README](../README.md) · [Loss types →](loss-types.md) · [Benchmarks →](benchmarks.md)

docs/loss-types.md

@@ -103,6 +103,48 @@ assert_eq!(result.loss().runner_up_gap(), 0.3);
 **`zero()`** — 0.0 entropy, 1.0 gap. One model at 100%.
 **`total()`** — infinite entropy, 0.0 gap. Maximum uncertainty.
 
+## Standard library Loss implementations
+
+`Loss` is implemented for common standard library types out of the box:
+
+### Numeric losses
+
+| Type | `combine` | `zero()` | `total()` |
+|------|-----------|----------|-----------|
+| `usize` | saturating add | `0` | `usize::MAX` |
+| `u64` | saturating add | `0` | `u64::MAX` |
+| `f64` | addition (IEEE) | `0.0` | `f64::INFINITY` |
+
+### Collection losses
+
+Track *what* was lost, not just *how much*.
+
+| Type | `combine` | `zero()` / `total()` |
+|------|-----------|----------------------|
+| `Vec<T: Clone>` | append | empty |
+| `HashSet<T: Eq + Hash + Clone>` | union | empty |
+| `BTreeSet<T: Ord + Clone>` | union | empty |
+| `String` | join with `"; "` | empty |
+
+> **Limitation:** Collections have no natural absorbing element. `total()` returns the same as `zero()` (empty). The monoid identity and associativity laws hold, but the absorbing property does not. If you need absorbing semantics, use a numeric loss type.
+
+### Tuple combinator
+
+`(A, B)` where both `A: Loss` and `B: Loss` composes two loss dimensions independently. Each component combines, zeros, and totals on its own.
+
+```rust
+use terni::{Imperfect, ConvergenceLoss, RoutingLoss};
+
+type PipelineLoss = (ConvergenceLoss, RoutingLoss);
+
+let result: Imperfect<i32, String, PipelineLoss> = Imperfect::Partial(
+    42,
+    (ConvergenceLoss::new(3), RoutingLoss::new(0.5, 0.2)),
+);
+```
+
+See the [flight recorder guide](flight-recorder.md) for more composition patterns.
+
 ## Implementing your own Loss type
 
 Implement `Loss` for any domain-specific measurement. The only requirements: `Clone + Default`, the four trait methods, and `combine` must be associative.

src/lib.rs

@@ -2130,8 +2130,7 @@ mod tests {
 
     #[test]
     fn string_in_imperfect() {
-        let i: Imperfect<u32, &str, String> =
-            Imperfect::Partial(42, "precision lost".into());
+        let i: Imperfect<u32, &str, String> = Imperfect::Partial(42, "precision lost".into());
         assert_eq!(i.loss(), "precision lost");
     }
 
@@ -2293,8 +2292,7 @@ mod tests {
     #[test]
     fn tuple_in_imperfect() {
         // Composite loss: count + magnitude
-        let i: Imperfect<&str, &str, (usize, f64)> =
-            Imperfect::Partial("value", (2, 0.5));
+        let i: Imperfect<&str, &str, (usize, f64)> = Imperfect::Partial("value", (2, 0.5));
         let loss = i.loss();
         assert_eq!(loss.0, 2);
         assert_eq!(loss.1, 0.5);