# Revision history for monad-rail

## 0.1.0.0 -- 2026-03-18

* First release.
* `RailT` monad transformer for Railway-Oriented Programming.
* `Rail` type alias for `RailT Failure IO`.
* `throwError` for single-error failures. Accepts any error type with `HasErrorInfo`, `Show`, and `Typeable` constraints — wraps it in `SomeError` automatically.
* `<!>` operator for parallel validation with error accumulation.
* `HasErrorInfo` typeclass for custom error types. Only `errorPublicMessage :: e -> Text` is required. All other methods have defaults:
  * `errorCode :: e -> Text` — defaults to the constructor name via `Data.toConstr` (requires `Data`).
  * `errorDetails :: e -> Maybe SomeErrorDetails` — defaults to `Nothing`. Uses the existential `SomeErrorDetails` wrapper (see below).
  * `errorSeverity :: e -> ErrorSeverity` — defaults to `Error`.
  * `errorInternalMessage`, `errorException`, `errorCallStack` — all default to `Nothing`.
* `publicErrorInfo :: HasErrorInfo e => e -> PublicErrorInfo` — assembles the user-facing error record from an instance.
* `internalErrorInfo :: HasErrorInfo e => e -> InternalErrorInfo` — assembles the internal diagnostic record from an instance.
* `SomeErrorDetails` existential wrapper — holds any value with `ToJSON`, `Show`, and `Typeable` constraints. Preserves the original type at runtime, allowing recovery via `Data.Typeable.cast` while supporting JSON serialization. Used by `errorDetails` and `PublicErrorInfo.details`.
* `PublicErrorInfo` with fields `publicMessage`, `code`, and `details` (where `details :: Maybe SomeErrorDetails`). Serializes to JSON as `message`, `code`, and `details`. Null fields are omitted from JSON output.
* `InternalErrorInfo` with fields `internalMessage`, `severity`, `exception`, and `callStack`. Implements `ToJSON` for structured log output; null fields are omitted. Never included in public API responses.
* `SomeError` existential wrapper — holds any error with `HasErrorInfo`, `Show`, and `Typeable` constraints. The `Typeable` constraint allows recovery of the original error type via `Data.Typeable.cast`.
* `ErrorSeverity` with `Error` and `Critical` levels.
* `UnhandledException` data type for wrapping runtime exceptions as Railway errors, with fields `unhandledCode`, `unhandledException`, `unhandledCallStack`, and `unhandledMessage`. `unhandledCode` is `Maybe Text` and defaults to `"UnhandledException"` when `Nothing`.
* `tryRail` (with `HasCallStack`) for lifting IO actions that may throw into the Railway, converting any exception to an `UnhandledException` error with `Critical` severity and an automatic call stack.
* `tryRailWithCode` (with `HasCallStack`) — like `tryRail` but accepts a function `SomeException -> Text` as the first argument, allowing the error code to be derived from the caught exception. Pass `const "MyCode"` for a fixed code, or inspect the exception to return different codes dynamically.
* `tryRailWithError` (with `HasCallStack`, `HasErrorInfo e`) — like `tryRailWithCode`, but takes an error-building function `SomeException -> e` and uses `errorCode` and `errorPublicMessage` from the resulting `HasErrorInfo` instance as the error code and public message.
* `throwUnhandledException` (with `HasCallStack`) — convenience function for throwing an `UnhandledException` with the default code `"UnhandledException"`. Captures the call stack automatically at the call site.
* `throwUnhandledExceptionWithCode` (with `HasCallStack`) — like `throwUnhandledException` but accepts a domain-specific error code as the first argument.
* `runRailT` — the general form of `runRail` for custom base monads. Use when `RailT` is stacked on top of `StateT`, `ReaderT`, or any other transformer.