fix(config): coerce scalar config leaves the way the Agent does

The Agent never reads a setting as the type its YAML holds: GetBool,
GetInt, GetFloat64, and GetString each cast the stored value through
spf13/cast. Permissiveness is therefore a property of a leaf's declared
type, not of the key, so `dogstatsd_port: "8125"` and a string-typed
leaf written as a YAML boolean are configurations the Agent accepts.

The generated Datadog source model took each leaf's JSON type
literally, so those spellings failed deserialization. That aborts the
strict startup gate, and at runtime it rejects the whole Agent snapshot,
holding every other key at its last-known-good value.

Port cast.To{Bool,Int64,Float64,String}E into cast_de and have codegen
attach one by leaf type, keeping the schema's type as the field type.
env_decode now shares those parsers, so one accept-set serves the file,
the environment, and the Agent stream. A value the cast cannot convert
stays a hard error rather than the Agent's silent zero value.

Every generated field is classified, and an unrecognized type fails the
build, so a schema change cannot quietly ship a leaf that rejects input
the Agent accepts. This subsumes the overlay's `input_shape` metadata,
whose one shape (a byte size written as an integer) is what a string
leaf now accepts by type, so it and string_de are removed.

Type-directed coercion cannot cover a setting whose values are a closed
set rather than a type, so model `use_v3_api.series.enabled` as a
`V3SeriesMode` enum. Its `FromStr` lists the spellings the Agent's
evaluator interprets, the translator parses once instead of every
consumer re-parsing a `String`, and an uninterpretable mode recovers to
disabled — what the Agent routes on — while still recording a
translation error for the strict gate.

Author: webern

.claude/skills/config-system/SKILL.md

@@ -123,6 +123,19 @@ Reserve `#[serde(flatten)]` for a struct that genuinely groups several *top-leve
 example, the forwarder's `forwarder_*` retry settings). Name a Rust field after its canonical
 section rather than renaming it onto one.
 
+## Scalar leaf coercion
+
+`DatadogConfiguration` scalar leaves accept what the Agent's permissive casting accepts. Codegen
+attaches a `cast_de.rs` coercion per schema type. For example `dogstatsd_port: "8125.0"` is valid
+and coerced to the int `8125`. `1` or `"T"` is coerced to a `bool`.
+
+## Documented enum settings
+
+A `string` setting whose documentation names a closed set of values (`otlp_config.metrics.histograms.mode`)
+becomes an enum in `agent-data-plane-config` with `#[default]` on the schema default and a `FromStr`
+listing the accepted spellings. The translator parses it and records the error, recovering to the value
+the Agent uses.
+
 ## Saluki-only values
 
 Values absent from the Datadog schema reach `SalukiConfiguration` through the `SalukiOnly` source

.vale/styles/config/vocabularies/technical/accept.txt

@@ -151,7 +151,7 @@ configurability
 cooldown
 crypto
 deserializable
-deserializer
+deserializer(s?)
 downcasted
 upcasted
 env

lib/agent-data-plane-config-system/src/system.rs

@@ -289,6 +289,7 @@ mod tests {
     use std::time::Duration;
 
     use agent_data_plane_config::domains::dogstatsd::OriginTagCardinality;
+    use agent_data_plane_config::shared::V3SeriesMode;
     use agent_data_plane_config::Provenance;
     use agent_data_plane_config::{Live, SalukiConfiguration};
     use datadog_agent_config::DatadogConfiguration;
@@ -362,8 +363,8 @@ mod tests {
         .await;
 
         assert_eq!(
-            system.config().shared.metrics_encoding.v3_series_mode.mode,
-            "datadog_only"
+            system.config().shared.metrics_encoding.v3_series_mode,
+            V3SeriesMode::DatadogOnly
         );
 
         agent_tx
@@ -406,14 +407,13 @@ mod tests {
             .unwrap();
 
         await_config(&system, "the streamed metrics V3 routing configuration", |config| {
-            config.shared.metrics_encoding.v3_series_mode.mode == "false"
+            config.shared.metrics_encoding.v3_series_mode == V3SeriesMode::Disabled
                 && config
                     .shared
                     .metrics_encoding
-                    .v3_series_mode
-                    .endpoint_modes
+                    .v3_series_endpoint_modes
                     .get("https://app.datadoghq.com")
-                    .is_some_and(|mode| mode == "true")
+                    == Some(&V3SeriesMode::Enabled)
         })
         .await;
 
@@ -546,6 +546,29 @@ mod tests {
         assert_eq!(system.config().domains.dogstatsd.debug_log.log_file_max_size, 10485760);
     }
 
+    #[tokio::test]
+    async fn standalone_loads_scalars_written_in_any_form_the_agent_casts() {
+        // The Agent reads a setting by casting whatever its configuration holds to the accessor's
+        // type, so a boolean written where the schema declares a string, or a quoted integer, is a
+        // configuration it accepts. Each must reach the typed model instead of aborting the strict
+        // startup gate.
+        let system = standalone_system(
+            Some(json!({
+                "use_v3_api": { "series": { "enabled": true } },
+                "dogstatsd_port": "8126",
+            })),
+            None,
+        )
+        .await
+        .expect("scalars in Agent-castable forms boot");
+
+        assert_eq!(
+            system.config().shared.metrics_encoding.v3_series_mode,
+            V3SeriesMode::Enabled
+        );
+        assert_eq!(system.config().domains.dogstatsd.listeners.port, 8126);
+    }
+
     #[tokio::test]
     async fn translation_invalid_update_is_rejected_keeping_last_known_good() {
         let (system, agent_tx) =

lib/agent-data-plane-config-system/src/translators/datadog_translator.rs

@@ -27,7 +27,7 @@ use agent_data_plane_config::domains::otlp::{
     CumulativeMonotonicMode, HistogramMode, InitialCumulativeMonotonicValue, SummaryMode,
     DEFAULT_GRPC_MAX_RECV_MSG_SIZE_MIB,
 };
-use agent_data_plane_config::shared::ForwarderHttpProtocol;
+use agent_data_plane_config::shared::{ForwarderHttpProtocol, V3SeriesMode};
 use agent_data_plane_config::{ConfigValue, SalukiConfiguration};
 use bytesize::ByteSize;
 use datadog_agent_config::{drive, DatadogConfigWitness, DatadogConfiguration, TranslateError, TranslateErrors};
@@ -73,6 +73,20 @@ impl<'a> DatadogTranslator<'a> {
     fn record_error(&mut self, error: TranslateError) {
         self.errors.push(error);
     }
+
+    /// Parses a V3 series mode, recovering to disabled rather than to the field default.
+    ///
+    /// A strict startup rejects the recorded error, and any path that keeps going routes series to
+    /// the older intake, which is what the Agent does with a mode it cannot interpret.
+    fn parse_v3_series_mode(&mut self, key: &'static str, value: &str) -> V3SeriesMode {
+        match value.parse() {
+            Ok(mode) => mode,
+            Err(error) => {
+                self.record_error(TranslateError::new(key, error));
+                V3SeriesMode::Disabled
+            }
+        }
+    }
 }
 
 /// Returns `None` for an empty `s`; otherwise returns `Some(s)`.
@@ -1114,18 +1128,22 @@ impl DatadogConfigWitness for DatadogTranslator<'_> {
     }
 
     fn consume_use_v3_api_series_enabled(&mut self, value: String) {
-        // TODO: consider modeling as an enum.
-        self.config.shared.metrics_encoding.v3_series_mode.mode = value;
+        let mode = self.parse_v3_series_mode("use_v3_api.series.enabled", &value);
+        self.config.shared.metrics_encoding.v3_series_mode = mode;
     }
 
     fn consume_use_v3_api_series_endpoints(&mut self, value: ::serde_json::Map<String, ::serde_json::Value>) {
-        self.config.shared.metrics_encoding.v3_series_mode.endpoint_modes = value
+        // The Agent accepts a per-endpoint mode written as any scalar, so a JSON boolean reaches the
+        // same parser as the string it renders to.
+        let modes: HashMap<String, V3SeriesMode> = value
             .into_iter()
             .map(|(endpoint, mode)| {
                 let mode = mode.as_str().map(str::to_string).unwrap_or_else(|| mode.to_string());
+                let mode = self.parse_v3_series_mode("use_v3_api.series.endpoints", &mode);
                 (endpoint, mode)
             })
             .collect();
+        self.config.shared.metrics_encoding.v3_series_endpoint_modes = modes;
     }
 
     fn consume_vector_metrics_enabled(&mut self, value: bool) {
@@ -1168,6 +1186,7 @@ mod tests {
             CumulativeMonotonicMode, InitialCumulativeMonotonicValue, SummaryMode, DEFAULT_GRPC_MAX_RECV_MSG_SIZE_MIB,
         },
     };
+    use agent_data_plane_config::shared::V3SeriesMode;
     use agent_data_plane_config::{ConfigValue, SalukiConfiguration};
     use datadog_agent_config::{DatadogConfiguration, TranslateErrors};
     use saluki_config::dynamic::{ConfigSetting, Provenance as StreamProvenance};
@@ -1314,6 +1333,51 @@ mod tests {
         assert!(errors.to_string().contains("greater than or equal to 0"));
     }
 
+    #[test]
+    fn v3_series_modes_translate_from_every_form_the_agent_accepts() {
+        let (config, errors) = translate_explicit(json!({
+            "use_v3_api": {
+                "series": {
+                    "enabled": true,
+                    "endpoints": { "https://app.datadoghq.com": "datadog_only", "https://opw.example.com": false },
+                }
+            }
+        }));
+
+        assert!(errors.is_none());
+        assert_eq!(config.shared.metrics_encoding.v3_series_mode, V3SeriesMode::Enabled);
+        assert_eq!(
+            config
+                .shared
+                .metrics_encoding
+                .v3_series_endpoint_modes
+                .get("https://app.datadoghq.com"),
+            Some(&V3SeriesMode::DatadogOnly)
+        );
+        assert_eq!(
+            config
+                .shared
+                .metrics_encoding
+                .v3_series_endpoint_modes
+                .get("https://opw.example.com"),
+            Some(&V3SeriesMode::Disabled)
+        );
+    }
+
+    #[test]
+    fn an_uninterpretable_v3_series_mode_disables_v3_and_records_a_translation_error() {
+        // The Agent routes to the older intake for a mode it cannot interpret, so the recovered value
+        // is disabled rather than the `datadog_only` field default.
+        let (config, errors) = translate_explicit(json!({
+            "use_v3_api": { "series": { "enabled": "sometimes" } }
+        }));
+
+        assert_eq!(config.shared.metrics_encoding.v3_series_mode, V3SeriesMode::Disabled);
+        let errors = errors.expect("an uninterpretable mode should record a translation error");
+        assert!(errors.to_string().contains("use_v3_api.series.enabled"));
+        assert!(errors.to_string().contains("unknown V3 series mode `sometimes`"));
+    }
+
     // Issue #1965: the Core Agent streams `dd_url` at its schema default even when the operator
     // configured only `site`. The translator used to compare the URL against that default and treat a
     // match as unset, which also discarded an operator's deliberate choice of the default intake.

lib/agent-data-plane-config/src/shared.rs

@@ -2,12 +2,13 @@
 
 use std::collections::HashMap;
 use std::path::PathBuf;
+use std::str::FromStr;
 use std::time::Duration;
 
 use serde::Serialize;
 
 use crate::defaults::DEFAULT_ENCODER_FLUSH_TIMEOUT;
-use crate::ConfigValue;
+use crate::{ConfigValue, Error};
 
 /// Cross-cutting configuration shared across domains.
 #[derive(Clone, Debug, Default, PartialEq, Serialize)]
@@ -300,8 +301,12 @@ pub struct MetricsEncoding {
     /// V3 metrics-intake protocol settings (`serializer_experimental_use_v3_api.*`).
     pub v3_api: V3ApiEncoding,
 
-    /// Global and per-endpoint V3 series routing mode (`use_v3_api.series.*`).
+    /// Global V3 series routing mode (`use_v3_api.series.enabled`).
     pub v3_series_mode: V3SeriesMode,
+
+    /// Per-endpoint V3 series routing overrides, keyed by endpoint URL
+    /// (`use_v3_api.series.endpoints`).
+    pub v3_series_endpoint_modes: HashMap<String, V3SeriesMode>,
 }
 
 impl Default for MetricsEncoding {
@@ -321,6 +326,7 @@ impl Default for MetricsEncoding {
             histogram: HistogramEncoding::default(),
             v3_api: V3ApiEncoding::default(),
             v3_series_mode: V3SeriesMode::default(),
+            v3_series_endpoint_modes: HashMap::new(),
         }
     }
 }
@@ -375,24 +381,33 @@ impl Default for V3ApiSettings {
     }
 }
 
-/// Global and per-endpoint V3 series routing mode (`use_v3_api.series.*`).
-#[derive(Clone, Debug, PartialEq, Serialize)]
-pub struct V3SeriesMode {
-    /// Global V3 series mode.
-    ///
-    /// Defaults to `datadog_only`, which enables V3 only for configured Datadog intake URLs.
-    /// TODO: consider modeling as an enum.
-    pub mode: String,
+/// Whether series are routed to the V3 metrics intake (`use_v3_api.series.*`).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
+pub enum V3SeriesMode {
+    /// Route series to the V3 intake.
+    Enabled,
+
+    /// Route series to the older intake.
+    Disabled,
 
-    /// Per-endpoint V3 series mode overrides, keyed by endpoint URL.
-    pub endpoint_modes: HashMap<String, String>,
+    /// Route series to the V3 intake only for endpoints that are Datadog intake URLs.
+    #[default]
+    DatadogOnly,
 }
 
-impl Default for V3SeriesMode {
-    fn default() -> Self {
-        Self {
-            mode: "datadog_only".to_string(),
-            endpoint_modes: HashMap::new(),
+impl FromStr for V3SeriesMode {
+    type Err = Error;
+
+    // The Agent reads this setting as a string and then interprets it, accepting more spellings than
+    // `strconv.ParseBool` does, so the accepted set is wider than that of a `boolean` leaf.
+    fn from_str(value: &str) -> Result<Self, Self::Err> {
+        match value.trim().to_ascii_lowercase().as_str() {
+            "true" | "1" | "t" | "yes" | "on" => Ok(Self::Enabled),
+            "false" | "0" | "f" | "no" | "off" | "" => Ok(Self::Disabled),
+            "datadog_only" => Ok(Self::DatadogOnly),
+            other => Err(Error::new_without_source(format!(
+                "unknown V3 series mode `{other}`; expected a boolean or `datadog_only`"
+            ))),
         }
     }
 }
@@ -438,3 +453,50 @@ pub struct AutoscalingFailover {
     /// Metrics designated for failover.
     pub metrics: Vec<String>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::V3SeriesMode;
+
+    #[test]
+    fn v3_series_mode_parses_every_form_the_agent_interprets() {
+        for (value, expected) in [
+            ("true", V3SeriesMode::Enabled),
+            ("TRUE", V3SeriesMode::Enabled),
+            ("1", V3SeriesMode::Enabled),
+            ("t", V3SeriesMode::Enabled),
+            ("yes", V3SeriesMode::Enabled),
+            ("on", V3SeriesMode::Enabled),
+            ("false", V3SeriesMode::Disabled),
+            ("0", V3SeriesMode::Disabled),
+            ("f", V3SeriesMode::Disabled),
+            ("no", V3SeriesMode::Disabled),
+            ("off", V3SeriesMode::Disabled),
+            ("", V3SeriesMode::Disabled),
+            (" datadog_only ", V3SeriesMode::DatadogOnly),
+        ] {
+            assert_eq!(
+                value.parse::<V3SeriesMode>().expect("mode should parse"),
+                expected,
+                "{value}"
+            );
+        }
+    }
+
+    #[test]
+    fn v3_series_mode_rejects_an_uninterpretable_value() {
+        let error = "sometimes"
+            .parse::<V3SeriesMode>()
+            .expect_err("an uninterpretable mode should be rejected");
+
+        assert_eq!(
+            error.to_string(),
+            "unknown V3 series mode `sometimes`; expected a boolean or `datadog_only`"
+        );
+    }
+
+    #[test]
+    fn v3_series_mode_defaults_to_datadog_only() {
+        assert_eq!(V3SeriesMode::default(), V3SeriesMode::DatadogOnly);
+    }
+}

lib/datadog-agent/config-overlay-model/src/lib.rs

@@ -59,9 +59,6 @@ pub struct FullSupport {
     /// GitHub issue tracking number.
     #[serde(default)]
     pub issue: Option<String>,
-    /// Accepted input shape when it is wider than the schema's declared type (see [`InputShape`]).
-    #[serde(default)]
-    pub input_shape: Option<InputShape>,
     /// Fields to support the `config_registry` and configuration smoke tests.
     pub test_support: TestSupport,
 }
@@ -82,9 +79,6 @@ pub struct PartialSupport {
     /// GitHub issue tracking number.
     #[serde(default)]
     pub issue: Option<String>,
-    /// Accepted input shape when it is wider than the schema's declared type (see [`InputShape`]).
-    #[serde(default)]
-    pub input_shape: Option<InputShape>,
     /// Fields to support the `config_registry` and configuration smoke tests.
     pub test_support: TestSupport,
 }
@@ -241,19 +235,6 @@ pub enum ValueType {
     StringList,
 }
 
-/// A widened input shape a schema `string` leaf accepts beyond a bare string.
-///
-/// The vendored schema types some settings as `string` but documents an equivalent numeric form
-/// (for example a byte size given as `10485760` instead of `"10MB"`). The schema cannot express that
-/// union, so the overlay names it and codegen attaches a tolerant deserializer to the generated
-/// field.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum InputShape {
-    /// Accept a string unchanged, or a non-negative integer normalized to its decimal string.
-    StringOrInteger,
-}
-
 /// File paths to the two YAML files required as input by this library.
 ///
 /// Defaults to the canonical location of the required schema files in this library.