Skip to main content

khive_runtime/
engine_config_embed_batch.rs

1//! The implemented `[embed].batch_size` slice of ADR-035.
2
3use std::path::Path;
4
5use serde::Deserialize;
6
7use super::ConfigError;
8
9/// Explicit maintenance batch configuration from `[embed]`.
10///
11/// Omission leaves the caller's default in effect. A present value is positive;
12/// the reindex caller applies its effective maximum of 500 after CLI precedence.
13/// Other accepted `[embed]` settings are not implemented by this section yet.
14#[derive(Debug, Clone, Default, Deserialize, PartialEq, Eq)]
15pub struct EmbedSectionConfig {
16    #[serde(default, deserialize_with = "positive_batch_size")]
17    pub batch_size: Option<u64>,
18}
19
20fn positive_batch_size<'de, D>(deserializer: D) -> Result<Option<u64>, D::Error>
21where
22    D: serde::Deserializer<'de>,
23{
24    let value = u64::deserialize(deserializer)?;
25    if value == 0 {
26        return Err(serde::de::Error::custom(
27            "embed.batch_size must be a positive integer",
28        ));
29    }
30    Ok(Some(value))
31}
32
33// Struct deserialization alone can accept a sequence. Require a table for both
34// the original-text probe and direct KhiveConfig deserialization.
35pub(super) fn deserialize_table<'de, D>(deserializer: D) -> Result<EmbedSectionConfig, D::Error>
36where
37    D: serde::Deserializer<'de>,
38{
39    struct TableVisitor;
40    impl<'de> serde::de::Visitor<'de> for TableVisitor {
41        type Value = EmbedSectionConfig;
42
43        fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44            formatter.write_str("an embed configuration table")
45        }
46
47        fn visit_map<A>(self, map: A) -> Result<Self::Value, A::Error>
48        where
49            A: serde::de::MapAccess<'de>,
50        {
51            EmbedSectionConfig::deserialize(serde::de::value::MapAccessDeserializer::new(map))
52        }
53    }
54    deserializer.deserialize_map(TableVisitor)
55}
56
57#[derive(Deserialize)]
58struct SyntaxProbe {
59    #[serde(default, deserialize_with = "deserialize_table")]
60    embed: EmbedSectionConfig,
61}
62
63pub(super) fn parse(
64    raw: &str,
65    document: &toml::Value,
66    path: &Path,
67) -> Result<(EmbedSectionConfig, Vec<String>), ConfigError> {
68    // Deserialize original bytes so invalid values retain their source span.
69    let probe: SyntaxProbe = toml::from_str(raw).map_err(|source| ConfigError::SchemaParse {
70        path: path.to_path_buf(),
71        key: if document.get("embed").is_some_and(|value| !value.is_table()) {
72            "embed"
73        } else {
74            "embed.batch_size"
75        },
76        source: Box::new(source),
77    })?;
78    let mut unknown = Vec::new();
79    if let Some(table) = document.get("embed").and_then(toml::Value::as_table) {
80        for key in table.keys() {
81            // These other accepted keys belong to later slices, not typos.
82            if !matches!(
83                key.as_str(),
84                "batch_size" | "auto_embed" | "fields" | "model" | "dimensions" | "device"
85            ) {
86                unknown.push(key.clone());
87            }
88        }
89        if let Some(fields) = table.get("fields").and_then(toml::Value::as_table) {
90            unknown.extend(
91                fields
92                    .keys()
93                    .filter(|key| key.as_str() != "include")
94                    .map(|key| format!("fields.{key}")),
95            );
96        }
97    }
98    Ok((probe.embed, unknown))
99}
100
101#[cfg(test)]
102mod tests {
103    use std::io::Write;
104    use std::sync::{Arc, Mutex};
105
106    use super::*;
107    use crate::engine_config::KhiveConfig;
108
109    #[test]
110    fn file_load_preserves_omission_and_positive_batch_sizes() {
111        let dir = tempfile::tempdir().unwrap();
112        let path = dir.path().join("selected.toml");
113        assert_eq!(KhiveConfig::default().embed.batch_size, None);
114        for (raw, expected) in [
115            ("", None),
116            ("[embed]\n", None),
117            ("[embed]\nbatch_size = 1\n", Some(1)),
118            ("[embed]\nbatch_size = 64\n", Some(64)),
119            ("[embed]\nbatch_size = 500\n", Some(500)),
120            ("[embed]\nbatch_size = 5000000000\n", Some(5_000_000_000)),
121        ] {
122            std::fs::write(&path, raw).unwrap();
123            let config = KhiveConfig::load(Some(&path)).unwrap().unwrap();
124            assert_eq!(config.embed.batch_size, expected, "{raw}");
125            assert_eq!(
126                toml::from_str::<KhiveConfig>(raw).unwrap().embed.batch_size,
127                expected,
128                "direct deserialize: {raw}"
129            );
130        }
131    }
132
133    #[test]
134    fn invalid_batch_values_name_selected_file_key_and_actual_source_location() {
135        let dir = tempfile::tempdir().unwrap();
136        let path = dir.path().join("selected.toml");
137        let invalid = ["0", "-1", "1.5", "\"64\"", "[]", "true"];
138        for value in invalid {
139            let raw = format!("# selected file\n\n[embed]\nbatch_size = {value}\n");
140            assert_invalid(&path, &raw, "embed.batch_size", 4);
141        }
142        for value in ["false", "[]", "[64]", "\"table\"", "64"] {
143            let raw = format!("# selected file\n\nembed = {value}\n");
144            assert_invalid(&path, &raw, "embed", 3);
145        }
146    }
147
148    fn assert_invalid(path: &Path, raw: &str, key: &str, line: usize) {
149        std::fs::write(path, raw).unwrap();
150        let error = KhiveConfig::load(Some(path)).unwrap_err();
151        let text = error.to_string();
152        assert!(
153            text.contains(path.canonicalize().unwrap().to_str().unwrap()),
154            "{text}"
155        );
156        assert!(text.contains(key), "{text}");
157        assert!(text.contains(&format!("line {line}")), "{text}");
158        assert!(text.contains("column"), "{text}");
159        let ConfigError::SchemaParse {
160            key: actual_key,
161            source,
162            ..
163        } = error
164        else {
165            panic!("expected span-preserving policy error: {text}")
166        };
167        assert_eq!(actual_key, key);
168        assert!(source.span().is_some(), "{text}");
169        assert!(toml::from_str::<KhiveConfig>(raw).is_err(), "{raw}");
170    }
171
172    #[derive(Clone, Default)]
173    struct Capture(Arc<Mutex<Vec<u8>>>);
174    impl Write for Capture {
175        fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
176            self.0.lock().unwrap().extend_from_slice(bytes);
177            Ok(bytes.len())
178        }
179        fn flush(&mut self) -> std::io::Result<()> {
180            Ok(())
181        }
182    }
183
184    #[test]
185    fn unknown_keys_warn_without_values_and_pending_keys_remain_recognized() {
186        let dir = tempfile::tempdir().unwrap();
187        let path = dir.path().join("selected.toml");
188        std::fs::write(
189            &path,
190            "[embed]\nbatch_size = 64\nauto_embed = false\nmodel = 'pending-model'\ndimensions = 384\ndevice = 'cpu'\nfuture = 'private-outer-value'\n[embed.fields]\ninclude = ['name']\nfuture_field = 'private-inner-value'\n",
191        ).unwrap();
192        let capture = Capture::default();
193        let writer = capture.clone();
194        let subscriber = tracing_subscriber::fmt()
195            .without_time()
196            .with_ansi(false)
197            .with_writer(move || writer.clone())
198            .finish();
199        let config = tracing::subscriber::with_default(subscriber, || {
200            KhiveConfig::load(Some(&path)).unwrap().unwrap()
201        });
202        assert_eq!(config.embed.batch_size, Some(64));
203        let text = String::from_utf8(capture.0.lock().unwrap().clone()).unwrap();
204        assert_eq!(
205            text.matches("ignoring unknown embed configuration key")
206                .count(),
207            2,
208            "{text}"
209        );
210        assert!(text.contains("future"), "{text}");
211        assert!(text.contains("fields.future_field"), "{text}");
212        for absent in [
213            "private-outer-value",
214            "private-inner-value",
215            "pending-model",
216            "auto_embed",
217            "dimensions",
218            "device",
219            "include",
220        ] {
221            assert!(!text.contains(absent), "{text}");
222        }
223        // The open embed table must not loosen an unrelated policy table.
224        std::fs::write(&path, "[embed]\nbatch_size = 64\n[gate]\nunknown = true\n").unwrap();
225        assert!(KhiveConfig::load(Some(&path)).is_err());
226    }
227
228    #[test]
229    fn selected_file_omission_does_not_merge_and_invalid_value_never_falls_back() {
230        let dir = tempfile::tempdir().unwrap();
231        let project = dir.path().join("project");
232        let home = dir.path().join("home");
233        std::fs::create_dir_all(&project).unwrap();
234        std::fs::create_dir_all(home.join(".khive")).unwrap();
235        std::fs::write(
236            home.join(".khive/config.toml"),
237            "[embed]\nbatch_size = 64\n",
238        )
239        .unwrap();
240        let load = || KhiveConfig::load_with_roots(&project, Some(&home), None);
241        assert_eq!(load().unwrap().unwrap().embed.batch_size, Some(64));
242        let selected = project.join("khive.toml");
243        std::fs::write(&selected, "[embed]\n").unwrap();
244        assert_eq!(load().unwrap().unwrap().embed.batch_size, None);
245        std::fs::write(&selected, "[embed]\nbatch_size = 500\n").unwrap();
246        assert_eq!(load().unwrap().unwrap().embed.batch_size, Some(500));
247        std::fs::write(&selected, "[embed]\nbatch_size = 0\n").unwrap();
248        let error = load().unwrap_err().to_string();
249        assert!(
250            error.contains(selected.canonicalize().unwrap().to_str().unwrap()),
251            "{error}"
252        );
253        assert!(error.contains("embed.batch_size"), "{error}");
254    }
255}