fix(mdds): align interval normalisation and validator with upstream

normalize_interval now maps `"0"` to `"tick"` instead of `"100ms"`.
The historical mapping contradicted the previously-documented
every-event semantics — the upstream enum spells that as `tick`, and
the SDK silently downgraded user requests to a 100ms sample without
warning. Mapping `0` to `tick` makes the behaviour match the doc
without breaking callers that picked an interval explicitly. The
small-ms snap range now also exposes `10ms`, which is the upstream
preset between `tick` and `100ms` that the SDK previously skipped.

validate_interval (CLI / MCP entry point) now enforces the upstream
enum verbatim plus the SDK's millisecond shorthand. Garbage strings
like `"twosec"` are rejected up front with a typed error listing the
accepted values, instead of being passed through to the gRPC layer
where they used to surface as opaque server-side rejections.

Mirrors the upstream operation specs at
`docs.thetadata.us/operations/option_history_quote.html` (and the
other 14 endpoints that carry an `interval` parameter).

Author: userFRM

crates/thetadatadx/src/mdds/endpoints.rs

@@ -99,24 +99,35 @@ impl From<&[String]> for SymbolInput {
 /// Convert an interval to the format the MDDS gRPC server accepts.
 ///
 /// Users can pass either:
-/// - Milliseconds as a string: `"60000"`, `"300000"`, `"900000"`
-/// - Shorthand directly: `"1m"`, `"5m"`, `"1h"`
+/// - Shorthand directly: `"tick"`, `"10ms"`, `"100ms"`, `"500ms"`,
+///   `"1s"`, `"5s"`, `"10s"`, `"15s"`, `"30s"`, `"1m"`, `"5m"`,
+///   `"10m"`, `"15m"`, `"30m"`, `"1h"`.
+/// - Milliseconds as a string (e.g. `"60000"` or `"300000"`). Values
+///   are snapped to the nearest documented preset.
 ///
-/// The server accepts these specific presets:
-/// `100ms`, `500ms`, `1s`, `5s`, `10s`, `15s`, `30s`, `1m`, `5m`, `10m`,
-/// `15m`, `30m`, `1h`.
+/// The full upstream enum is reproduced verbatim in
+/// `docs.thetadata.us/operations/option_history_quote.html` (and every
+/// other endpoint with an `interval` parameter).
 ///
-/// If milliseconds are passed, they're converted to the nearest matching
-/// preset. If already a valid shorthand (contains 's', 'm', or 'h'), the
-/// value is passed through as-is.
+/// The historical SDK accepted `"0"` and silently mapped it to
+/// `"100ms"`. That contradicted the previously-documented behaviour
+/// (`"0"` was advertised as "every quote change"), so `"0"` now snaps
+/// to `"tick"` — which is the upstream every-event vocabulary. Calls
+/// that depended on the silent-100ms behaviour should switch to an
+/// explicit preset.
 fn normalize_interval(interval: &str) -> String {
     if interval.ends_with('s') || interval.ends_with('m') || interval.ends_with('h') {
         return interval.to_string();
     }
+    if interval == "tick" {
+        return "tick".to_string();
+    }
 
     match interval.parse::<u64>() {
         Ok(ms) => match ms {
-            0..=100 => "100ms".to_string(),
+            0 => "tick".to_string(),
+            1..=10 => "10ms".to_string(),
+            11..=100 => "100ms".to_string(),
             101..=500 => "500ms".to_string(),
             501..=1000 => "1s".to_string(),
             1_001..=5_000 => "5s".to_string(),
@@ -269,6 +280,8 @@ mod tests {
 
     #[test]
     fn normalize_interval_passes_shorthand_through() {
+        assert_eq!(normalize_interval("tick"), "tick");
+        assert_eq!(normalize_interval("10ms"), "10ms");
         assert_eq!(normalize_interval("1m"), "1m");
         assert_eq!(normalize_interval("5m"), "5m");
         assert_eq!(normalize_interval("1h"), "1h");
@@ -281,4 +294,22 @@ mod tests {
         assert_eq!(normalize_interval("900000"), "15m");
         assert_eq!(normalize_interval("3600000"), "1h");
     }
+
+    #[test]
+    fn normalize_interval_snaps_zero_to_tick() {
+        // The historical mapping was `0 -> 100ms`, which contradicted
+        // the previously-documented every-event semantics. The upstream
+        // `tick` keyword is the every-event vocabulary, so the zero
+        // sentinel snaps to it instead.
+        assert_eq!(normalize_interval("0"), "tick");
+    }
+
+    #[test]
+    fn normalize_interval_snaps_small_milliseconds_to_documented_presets() {
+        // 10ms-and-under -> 10ms; 11-100ms -> 100ms. The earlier
+        // 0..=100 -> 100ms mapping skipped the 10ms preset entirely.
+        assert_eq!(normalize_interval("10"), "10ms");
+        assert_eq!(normalize_interval("11"), "100ms");
+        assert_eq!(normalize_interval("100"), "100ms");
+    }
 }

crates/thetadatadx/src/mdds/validate.rs

@@ -88,13 +88,40 @@ pub(crate) fn validate_symbol(value: &str, param_name: &str) -> Result<(), Endpo
     Ok(())
 }
 
+/// The exact set of `interval` strings the v3 ThetaData server accepts.
+///
+/// Mirrors the upstream enum at
+/// `https://docs.thetadata.us/operations/option_history_quote.html`.
+/// The SDK additionally accepts decimal millisecond shorthand
+/// (`"60000"`, `"300000"`, ...) and snaps it to the nearest preset via
+/// [`crate::mdds::endpoints::normalize_interval`]; this validator
+/// recognises both shapes so the CLI / MCP layer rejects garbage
+/// before the gRPC dispatch.
+const VALID_INTERVAL_PRESETS: &[&str] = &[
+    "tick", "10ms", "100ms", "500ms", "1s", "5s", "10s", "15s", "30s", "1m", "5m", "10m", "15m",
+    "30m", "1h",
+];
+
 pub(crate) fn validate_interval(value: &str, param_name: &str) -> Result<(), EndpointError> {
-    if value.is_empty() || !value.bytes().all(|b| b.is_ascii_alphanumeric()) {
+    if value.is_empty() {
         return Err(EndpointError::InvalidParams(format!(
-            "'{param_name}' must be a non-empty alphanumeric string (e.g. '60000' or '1m'), got: '{value}'"
+            "'{param_name}' must be a non-empty string from the upstream enum ({}) or a millisecond value (e.g. '60000'), got empty string",
+            VALID_INTERVAL_PRESETS.join(", "),
         )));
     }
-    Ok(())
+    if VALID_INTERVAL_PRESETS.contains(&value) {
+        return Ok(());
+    }
+    if value.bytes().all(|b| b.is_ascii_digit()) {
+        // Millisecond shorthand: `normalize_interval` will snap to the
+        // nearest documented preset. Any positive integer is accepted
+        // here; the snap range covers `0` (-> "tick") through `1h`.
+        return Ok(());
+    }
+    Err(EndpointError::InvalidParams(format!(
+        "'{param_name}' must be one of the upstream presets ({}) or a millisecond value (e.g. '60000'), got: '{value}'",
+        VALID_INTERVAL_PRESETS.join(", "),
+    )))
 }
 
 pub(crate) fn validate_right(value: &str, param_name: &str) -> Result<(), EndpointError> {
@@ -241,4 +268,21 @@ mod tests {
             assert!(validate_strike(bad, "strike").is_err(), "{bad}");
         }
     }
+
+    #[test]
+    fn interval_accepts_upstream_enum_and_ms_shorthand() {
+        for good in [
+            "tick", "10ms", "100ms", "500ms", "1s", "5s", "10s", "15s", "30s", "1m", "5m", "10m",
+            "15m", "30m", "1h", "0", "60000", "300000",
+        ] {
+            assert!(validate_interval(good, "interval").is_ok(), "{good}");
+        }
+    }
+
+    #[test]
+    fn interval_rejects_garbage() {
+        for bad in ["", "twosec", "2sec", "1minute", "-1", "1.5s", "1 s", "*"] {
+            assert!(validate_interval(bad, "interval").is_err(), "{bad}");
+        }
+    }
 }