Add ADR: better call stacks of io exceptions

Author: carbolymer

docs/ADR-X-Better-call-stacks-of-io-exceptions.md

@@ -0,0 +1,80 @@
+# Status
+
+📜 Proposed 2025-04-03
+
+# Context
+
+This ADR enriches exceptions thrown from `IO` functions with call stacks up to the function usage site.
+
+## The problem
+This ADR bases on [[ADR-8-Use-RIO-in-cardano‐cli.md]].
+
+The goal of this ADR is to provide better call stacks to `IO` exceptions thrown.
+The problem with exceptions thrown from IO monad is that they do not carry call stack from where they were thrown.
+This is not very convenient when for example doing multiple file access or network operations in a row.
+You won't know which one has thrown an exception: you will have only a vague exception message without many details, for example, just a message:
+```
+Network.Socket.recvBuf: resource vanished (Connection reset by peer)
+```
+
+## Solution
+
+The currently used type alias adds call stacks to the functions:
+```haskell
+type CIO e a = HasCallStack => CIO e a
+```
+We can make sure that `IO` exceptions thrown in `IO` actions are captured with a helper `runIO` function, meant to be used instead of `liftIO`:
+
+```haskell
+import UnliftIO.Exceptions (catchAny, throwIO)
+
+runIO :: IO a -> CIO a
+runIO m = withFrozenCallStack $ catchAny (liftIO m) (throwIO . mkE)
+ where
+  mkE :: SomeException -> IoeWrapper
+  mkE e = withFrozenCallStack $ IoeWrapper e
+
+-- | An exception wrapper type, adding a call stack to it
+data IoeWrapper = HasCallStack => IoeWrapper SomeException
+
+deriving instance Show IoeWrapper
+
+instance Exception IoeWrapper where
+  displayException (IoeWrapper (SomeException e)) =
+    constructorName <> ": " <> displayException e <> "\n" <> prettyCallStack callStack
+   where
+    constructorName =  tyConName . typeRepTyCon $ typeOf e
+```
+The provided `runIO` wraps synchronous exceptions into `IoeWrapper`, which adds additional information about call stack.
+
+The resulting call stack will contain entries up to the point where `runIO` was called.
+This means that in the following code:
+```haskell
+foo :: CIO e ()
+foo = do
+  someFunction
+  runIO $ do
+    someOtherFunction
+    someExceptionThrowingFunction
+```
+the exception thrown from `someExceptionThrowingFunction` and wrapped using `runIO` will only point to the place where `runIO` was called.
+
+# Decision
+
+TBD
+
+# Consequences
+
+1. More detailed call stacks when interacting with IO.
+
+1. **A need for manual step when writing new code**.
+  A developer would have to remember to use `runIO`
+
+1. **Performance impact**.
+  Including `HasCallStack` has [some performance penalty][hascallstack-perf-penalty], so it's may have some detrimental effect in loops executed many times.
+
+
+
+[hascallstack-perf-penalty]: https://stackoverflow.com/questions/57471398/how-does-hascallstack-influence-the-performance-of-a-normal-branch-in-haskell
+
+[modeline]: # ( vim: set spell spelllang=en: )