address review: refine error variants for accurate semantics

PR #369 review feedback from Copilot. Replace misleading variant reuse
with domain-accurate variants so error messages match the actual
failure mode.

- PricingError::SqrtFailure.value: Positive -> Decimal. The sqrt is
  taken of a discriminant that can be negative (doc said negative but
  the field rejected it).
- ChainError: add EmptyChain { symbol } variant for non-ATM lookups.
  Reserve EmptyChainAtm for atm_option_data() paths. Update
  get_optiondata_with_strike and its test to use EmptyChain.
- OhlcvError: add MissingZipEntry { extension } for missing file in
  ZIP archive, and AsyncTask { reason } for spawn_blocking join
  failures. read_ohlcv_from_zip and read_ohlcv_from_zip_async now map
  to the correct variants instead of MissingColumn/RowParsing.
- VolatilityError: add Chain(Box<ChainError>) variant plus
  From<ChainError>. AtmIvProvider for OptionChain now wraps the
  source as VolatilityError::Chain instead of NumericalFailure,
  preserving the actual cause (empty chain / ATM not found).
- examples/examples_chain/creator.rs: map missing expiration to
  ChainError::invalid_parameters("expiration_date", "missing") instead
  of AtmNotFound.

Author: joaquinbejar

examples/examples_chain/src/bin/creator.rs

@@ -19,12 +19,12 @@ fn main() -> Result<(), optionstratlib::error::Error> {
     info!("{}", option_chain);
 
     let underlying_price = option_chain.underlying_price;
-    let expiration_date =
-        option_chain
-            .get_expiration()
-            .ok_or(optionstratlib::error::ChainError::AtmNotFound {
-                symbol: option_chain.symbol.clone(),
-            })?;
+    let expiration_date = option_chain.get_expiration().ok_or_else(|| {
+        optionstratlib::error::ChainError::invalid_parameters(
+            "expiration_date",
+            "missing on option chain",
+        )
+    })?;
     let symbol = option_chain.symbol.clone();
 
     info!("Underlying Price: {}", underlying_price);

src/chains/chain.rs

@@ -2815,7 +2815,7 @@ impl OptionChain {
     pub fn get_optiondata_with_strike(&self, price: &Positive) -> Result<&OptionData, ChainError> {
         // Check for empty option chain
         if self.options.is_empty() {
-            return Err(ChainError::EmptyChainAtm {
+            return Err(ChainError::EmptyChain {
                 symbol: self.symbol.clone(),
             });
         }
@@ -11951,10 +11951,14 @@ mod tests_get_strikes_and_optiondata {
         assert!(result.is_err(), "Should return error for empty chain");
 
         let error = result.unwrap_err();
+        assert!(
+            matches!(error, ChainError::EmptyChain { ref symbol } if symbol == "EMPTY"),
+            "Should return ChainError::EmptyChain for EMPTY symbol, got: {error:?}"
+        );
         let error_msg = format!("{error}");
         assert!(
-            error_msg.contains("empty option chain"),
-            "Error should mention empty chain"
+            error_msg.contains("option chain is empty"),
+            "Error should mention empty chain, got: {error_msg}"
         );
         assert!(
             error_msg.contains("EMPTY"),

src/error/chains.rs

@@ -85,8 +85,10 @@ use thiserror::Error;
 /// * `StrategyError` - Errors related to option trading strategies, including issues
 ///   with leg validation or invalid combinations of options.
 ///
+/// * `EmptyChain` - The option chain for the given symbol is empty (generic empty-chain
+///   condition, independent of ATM selection).
 /// * `EmptyChainAtm` - The option chain for the given symbol is empty and has no ATM option
-///   to select.
+///   to select. Reserved for ATM-selection paths; prefer `EmptyChain` for non-ATM lookups.
 /// * `AtmNotFound` - The option chain has options but none could be selected as the ATM
 ///   contract for the given symbol.
 /// * `EmptyDensities` - No valid risk-neutral densities could be produced.
@@ -133,8 +135,16 @@ pub enum ChainError {
     #[error("Strategy error: {0}")]
     StrategyError(StrategyErrorKind),
 
+    /// The option chain for the given symbol is empty. Generic empty-chain
+    /// condition, emitted by non-ATM lookups (e.g. strike-based selection).
+    #[error("option chain is empty: {symbol}")]
+    EmptyChain {
+        /// Ticker symbol of the chain that is empty.
+        symbol: String,
+    },
+
     /// The option chain for the given symbol is empty and has no ATM option
-    /// to select.
+    /// to select. Reserved for ATM-selection paths.
     #[error("cannot find ATM option for empty option chain: {symbol}")]
     EmptyChainAtm {
         /// Ticker symbol of the chain that is empty.

src/error/csv.rs

@@ -112,6 +112,21 @@ pub enum OhlcvError {
         /// Human-readable description of why the row could not be parsed.
         reason: String,
     },
+
+    /// No file with the expected extension was found inside the ZIP archive.
+    #[error("no file with extension `{extension}` found in ZIP archive")]
+    MissingZipEntry {
+        /// Extension that was expected inside the ZIP payload (e.g. `"csv"`).
+        extension: &'static str,
+    },
+
+    /// An asynchronous background task (`tokio::task::spawn_blocking`) failed to
+    /// complete — typically a panic or cancellation of the worker thread.
+    #[error("async task failed: {reason}")]
+    AsyncTask {
+        /// Human-readable description of the underlying join failure.
+        reason: String,
+    },
 }
 
 impl From<std::io::Error> for OhlcvError {

src/error/pricing.rs

@@ -1,6 +1,7 @@
 use crate::error::{DecimalError, GreeksError, OptionsError, PositionError};
 use expiration_date::error::ExpirationDateError;
-use positive::{Positive, PositiveError};
+use positive::PositiveError;
+use rust_decimal::Decimal;
 use thiserror::Error;
 
 /// Error type for option pricing operations.
@@ -69,11 +70,14 @@ pub enum PricingError {
     },
 
     /// A square-root computation inside a pricing kernel failed (the operand
-    /// was negative or not representable).
+    /// was negative or not representable — e.g. a negative discriminant in a
+    /// closed-form solver).
     #[error("pricing sqrt failed for value {value}")]
     SqrtFailure {
         /// The value for which the square root could not be computed.
-        value: Positive,
+        ///
+        /// Stored as `Decimal` so negative operands are representable.
+        value: Decimal,
     },
 
     /// Error from Positive operations.

src/error/volatility.rs

@@ -115,11 +115,25 @@ pub enum VolatilityError {
         source: Box<VolatilityError>,
     },
 
+    /// A chain-layer error surfaced while retrieving volatility data
+    /// (e.g. empty option chain, ATM lookup failure on a chain).
+    ///
+    /// Boxed to avoid infinite enum size through the `ChainError::Volatility`
+    /// cycle.
+    #[error(transparent)]
+    Chain(Box<crate::error::ChainError>),
+
     /// Positive value errors
     #[error(transparent)]
     PositiveError(#[from] positive::PositiveError),
 }
 
+impl From<crate::error::ChainError> for VolatilityError {
+    fn from(error: crate::error::ChainError) -> Self {
+        Self::Chain(Box::new(error))
+    }
+}
+
 #[cfg(test)]
 mod tests_volatility_errors {
     use super::*;

src/utils/csv.rs

@@ -87,7 +87,7 @@ pub fn read_ohlcv_from_zip(
         }
     }
 
-    let csv_index = csv_index.ok_or(OhlcvError::MissingColumn { column: "csv" })?;
+    let csv_index = csv_index.ok_or(OhlcvError::MissingZipEntry { extension: "csv" })?;
     let file = archive.by_index(csv_index)?;
     let reader = BufReader::new(file);
 
@@ -159,8 +159,8 @@ pub async fn read_ohlcv_from_zip_async(
         read_ohlcv_from_zip(&zip_path, start_date.as_deref(), end_date.as_deref())
     })
     .await
-    .map_err(|e| OhlcvError::RowParsing {
-        reason: format!("async task error: {e}"),
+    .map_err(|e| OhlcvError::AsyncTask {
+        reason: e.to_string(),
     })?
 }
 

src/volatility/traits.rs

@@ -110,9 +110,7 @@ impl AtmIvProvider for OptionChain {
         match self.get_atm_implied_volatility() {
             Ok(iv) => Ok(iv),
             Err(e) => Err(VolatilityError::AtmIvUnavailable {
-                source: Box::new(VolatilityError::NumericalFailure {
-                    reason: e.to_string(),
-                }),
+                source: Box::new(VolatilityError::from(e)),
             }),
         }
     }