// Package result provides a generic Expect[T] type for happy-path-oriented code.
//
// The intended pattern is:
//
//  1. Deep call stacks write for the happy path, using [Expect.Must] or
//     [Expect.Expect] to unwrap values — panicking on unexpected errors rather
//     than threading error returns through every frame.
//  2. The function that initiates a complex operation defers [Catch], which
//     recovers any Expect panic and returns it as a normal Go error.
//
// Stack traces are captured at the panic site and can be retrieved from the
// caught error via [StackTrace].
//
// # Constructors
//
// Use [Ok] to wrap a success value, [Fail] to wrap an error, and [Of] to
// bridge existing (value, error) return signatures:
//
//	data := result.Of(os.ReadFile("cfg.json")).Expect("read config")
//
// # Boundary pattern
//
//	func run() (err error) {
//	    defer result.Catch(&err)
//	    port := parsePort(cfg.Port).Expect("load config port")
//	    _ = port // happy path continues …
//	    return nil
//	}
//
// [Catch] only intercepts error panics produced by this package. Real runtime
// panics (nil-pointer dereferences, index out of bounds, etc.) are re-panicked
// so genuine bugs are never silently swallowed.
package result