Skip to main content

gitflow_core/
decision.rs

1//! Provider-independent typed decision requests and validated answers.
2
3use std::collections::BTreeMap;
4
5use async_trait::async_trait;
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8use thiserror::Error;
9
10/// Maximum serialized state size sent to a decision provider.
11pub const MAX_STATE_BYTES: usize = 32_768;
12/// Maximum number of independent questions in one request.
13pub const MAX_QUESTIONS: usize = 16;
14/// Maximum number of Choice options (lower than the provider's 255 limit).
15pub const MAX_CHOICE_OPTIONS: usize = 32;
16/// Maximum number of ordered Score levels.
17pub const MAX_SCORE_LEVELS: usize = 10;
18/// Maximum serialized size of the complete request before provider wrapping.
19pub const MAX_REQUEST_BYTES: usize = 131_072;
20
21/// A bounded, provider-neutral decision request.
22#[derive(Debug, Clone, Serialize, Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct DecisionRequest {
25    /// Minimal state for the decision; callers must remove unrelated private fields.
26    pub state: Value,
27    /// Questions keyed by stable caller-owned identifiers.
28    pub questions: BTreeMap<String, Question>,
29}
30
31/// A typed question, independent of any provider wire protocol.
32#[derive(Debug, Clone, Serialize, Deserialize)]
33#[serde(tag = "type", rename_all = "lowercase", deny_unknown_fields)]
34pub enum Question {
35    /// A calibrated yes/no question.
36    Noul {
37        /// The single yes/no question to evaluate.
38        instructions: String,
39    },
40    /// Selection from a closed set of options.
41    Choice {
42        /// The choice question.
43        instructions: String,
44        /// Option identifier to distinct description.
45        criteria: BTreeMap<String, String>,
46    },
47    /// Rating on an ordered low-to-high scale.
48    Score {
49        /// The rating question.
50        instructions: String,
51        /// Descriptive levels in ascending order.
52        criteria: Vec<String>,
53    },
54}
55
56/// Validated answer returned by a decision provider.
57#[derive(Debug, Clone, Serialize, Deserialize)]
58#[serde(tag = "type", rename_all = "lowercase", deny_unknown_fields)]
59pub enum TypedAnswer {
60    /// Probability that the answer to a yes/no question is yes.
61    Noul {
62        /// Probability in the inclusive range 0–1.
63        noul: f64,
64    },
65    /// Closed-set selection and distribution.
66    Choice {
67        /// Selected option identifier.
68        choice: String,
69        /// Provider confidence in the selection.
70        confidence: f64,
71        /// Per-option probability distribution.
72        probabilities: BTreeMap<String, f64>,
73    },
74    /// Rating and distribution on an ordered scale.
75    Score {
76        /// Probability-weighted position on the scale.
77        score: f64,
78        /// Provider confidence in the rating.
79        confidence: f64,
80        /// Numeric level identifier to description.
81        legend: BTreeMap<String, String>,
82        /// Per-level probability distribution.
83        probabilities: BTreeMap<String, f64>,
84    },
85}
86
87/// Token usage reported by a provider, without request or response content.
88#[derive(Debug, Clone, Serialize, Deserialize)]
89#[serde(deny_unknown_fields)]
90pub struct DecisionUsage {
91    /// Number of input tokens billed or counted.
92    pub input_tokens: u64,
93    /// Number of output tokens billed or counted.
94    pub output_tokens: u64,
95}
96
97/// Complete decision response with one answer per requested question.
98#[derive(Debug, Clone, Serialize, Deserialize)]
99#[serde(deny_unknown_fields)]
100pub struct DecisionResponse {
101    /// Actual model identifier returned by the provider.
102    pub model: String,
103    /// Answers keyed by request question identifier.
104    pub answers: BTreeMap<String, TypedAnswer>,
105    /// Provider-reported token usage.
106    pub usage: DecisionUsage,
107}
108
109/// A safe, content-free decision error.
110#[derive(Debug, Error)]
111#[non_exhaustive]
112pub enum DecisionError {
113    /// Provider is disabled or missing required configuration.
114    #[error("decision provider unavailable")]
115    Unavailable,
116    /// Caller supplied a request that violates limits or schema.
117    #[error("invalid decision request: {0}")]
118    InvalidInput(&'static str),
119    /// Provider response is incomplete or violates the requested schema.
120    #[error("invalid decision response: {0}")]
121    InvalidResponse(&'static str),
122    /// The request timed out.
123    #[error("decision provider timed out")]
124    Timeout,
125    /// The provider failed without exposing any sensitive body or header.
126    #[error("decision provider request failed")]
127    Transport,
128}
129
130/// Provider-independent asynchronous decision engine.
131#[async_trait]
132pub trait DecisionEngine: std::fmt::Debug + Send + Sync {
133    /// Evaluate a bounded request.
134    ///
135    /// # Errors
136    ///
137    /// Returns a content-free [`DecisionError`] for invalid input, provider
138    /// failures, or an invalid response.
139    async fn decide(&self, request: &DecisionRequest) -> Result<DecisionResponse, DecisionError>;
140}
141
142impl DecisionRequest {
143    /// Check state, question, and option limits before external transmission.
144    ///
145    /// # Errors
146    ///
147    /// Returns [`DecisionError::InvalidInput`] when a bound is exceeded or
148    /// a question is malformed.
149    pub fn validate(&self) -> Result<(), DecisionError> {
150        let state_len = serde_json::to_vec(&self.state)
151            .map_err(|_| DecisionError::InvalidInput("state is not serializable"))?
152            .len();
153        if !matches!(&self.state, Value::String(value) if !value.trim().is_empty())
154            && !matches!(&self.state, Value::Array(values) if !values.is_empty())
155            && !matches!(&self.state, Value::Object(values) if !values.is_empty())
156        {
157            return Err(DecisionError::InvalidInput("state is empty or invalid"));
158        }
159        if state_len > MAX_STATE_BYTES {
160            return Err(DecisionError::InvalidInput("state size is out of bounds"));
161        }
162        if state_contains_obvious_credential(&self.state) {
163            return Err(DecisionError::InvalidInput(
164                "state contains a credential-like value",
165            ));
166        }
167        if self.questions.is_empty() || self.questions.len() > MAX_QUESTIONS {
168            return Err(DecisionError::InvalidInput(
169                "question count is out of bounds",
170            ));
171        }
172        for (id, question) in &self.questions {
173            if id.is_empty()
174                || id.len() > 64
175                || !id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
176            {
177                return Err(DecisionError::InvalidInput("question id is invalid"));
178            }
179            let instructions = match question {
180                Question::Noul { instructions }
181                | Question::Choice { instructions, .. }
182                | Question::Score { instructions, .. } => instructions,
183            };
184            if instructions.trim().is_empty() || instructions.len() > 1_024 {
185                return Err(DecisionError::InvalidInput(
186                    "instructions are out of bounds",
187                ));
188            }
189            match question {
190                Question::Noul { .. } => {}
191                Question::Choice { criteria, .. } => {
192                    if criteria.len() < 2 || criteria.len() > MAX_CHOICE_OPTIONS {
193                        return Err(DecisionError::InvalidInput(
194                            "choice option count is out of bounds",
195                        ));
196                    }
197                    if criteria.iter().any(|(key, value)| {
198                        key.is_empty()
199                            || key.len() > 64
200                            || value.trim().is_empty()
201                            || value.len() > 512
202                    }) {
203                        return Err(DecisionError::InvalidInput("choice option is invalid"));
204                    }
205                }
206                Question::Score { criteria, .. } => {
207                    if criteria.len() < 2 || criteria.len() > MAX_SCORE_LEVELS {
208                        return Err(DecisionError::InvalidInput(
209                            "score level count is out of bounds",
210                        ));
211                    }
212                    if criteria
213                        .iter()
214                        .any(|value| value.trim().is_empty() || value.len() > 512)
215                    {
216                        return Err(DecisionError::InvalidInput("score level is invalid"));
217                    }
218                }
219            }
220        }
221        let request_len = serde_json::to_vec(self)
222            .map_err(|_| DecisionError::InvalidInput("request is not serializable"))?
223            .len();
224        if request_len > MAX_REQUEST_BYTES {
225            return Err(DecisionError::InvalidInput("request is too large"));
226        }
227        Ok(())
228    }
229}
230
231impl DecisionResponse {
232    /// Validate provider answers against the exact caller-owned question set.
233    ///
234    /// # Errors
235    ///
236    /// Returns [`DecisionError::InvalidResponse`] when any answer is missing,
237    /// extra, mistyped, nonfinite, or inconsistent with its criteria.
238    pub fn validate_against(&self, request: &DecisionRequest) -> Result<(), DecisionError> {
239        if self.model.trim().is_empty()
240            || self.model.len() > 128
241            || self.answers.keys().ne(request.questions.keys())
242        {
243            return Err(DecisionError::InvalidResponse(
244                "model or answer set is invalid",
245            ));
246        }
247        for (id, question) in &request.questions {
248            let answer = self
249                .answers
250                .get(id)
251                .ok_or(DecisionError::InvalidResponse("answer missing"))?;
252            match (question, answer) {
253                (Question::Noul { .. }, TypedAnswer::Noul { noul }) => {
254                    if !is_probability(*noul) {
255                        return Err(DecisionError::InvalidResponse(
256                            "noul probability is invalid",
257                        ));
258                    }
259                }
260                (
261                    Question::Choice { criteria, .. },
262                    TypedAnswer::Choice {
263                        choice,
264                        confidence,
265                        probabilities,
266                    },
267                ) => {
268                    if !is_probability(*confidence)
269                        || !distribution_matches(probabilities, criteria.keys())
270                        || !criteria.contains_key(choice)
271                        || probabilities.get(choice).is_none_or(|selected| {
272                            probabilities.values().any(|value| value > selected)
273                        })
274                    {
275                        return Err(DecisionError::InvalidResponse(
276                            "choice distribution is invalid",
277                        ));
278                    }
279                }
280                (
281                    Question::Score { criteria, .. },
282                    TypedAnswer::Score {
283                        score,
284                        confidence,
285                        legend,
286                        probabilities,
287                    },
288                ) => {
289                    if !is_probability(*confidence)
290                        || !score.is_finite()
291                        || *score < 0.0
292                        || *score
293                            > f64::from(
294                                u32::try_from(criteria.len().saturating_sub(1)).unwrap_or(u32::MAX),
295                            )
296                    {
297                        return Err(DecisionError::InvalidResponse("score is invalid"));
298                    }
299                    let expected: BTreeMap<String, String> = criteria
300                        .iter()
301                        .enumerate()
302                        .map(|(index, label)| (index.to_string(), label.clone()))
303                        .collect();
304                    let weighted = probabilities
305                        .iter()
306                        .filter_map(|(level, probability)| {
307                            level
308                                .parse::<u32>()
309                                .ok()
310                                .map(|level| f64::from(level) * probability)
311                        })
312                        .sum::<f64>();
313                    if legend != &expected
314                        || !distribution_matches(probabilities, expected.keys())
315                        || (weighted - score).abs() > 0.02
316                    {
317                        return Err(DecisionError::InvalidResponse(
318                            "score distribution is invalid",
319                        ));
320                    }
321                }
322                _ => {
323                    return Err(DecisionError::InvalidResponse(
324                        "answer type does not match question",
325                    ));
326                }
327            }
328        }
329        Ok(())
330    }
331}
332
333fn is_probability(value: f64) -> bool {
334    value.is_finite() && (0.0..=1.0).contains(&value)
335}
336
337pub(crate) fn state_contains_obvious_credential(value: &Value) -> bool {
338    match value {
339        Value::String(text) => {
340            let lower = text.to_ascii_lowercase();
341            [
342                "apikey_",
343                "github_pat_",
344                "ghp_",
345                "gho_",
346                "ghu_",
347                "ghs_",
348                "ghr_",
349                "glpat-",
350                "sk-",
351            ]
352            .iter()
353            .any(|prefix| {
354                lower.match_indices(prefix).any(|(index, _)| {
355                    let rest = &lower[index + prefix.len()..];
356                    rest.bytes()
357                        .take_while(|byte| {
358                            byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-')
359                        })
360                        .count()
361                        >= 20
362                })
363            })
364        }
365        Value::Array(values) => values.iter().any(state_contains_obvious_credential),
366        Value::Object(values) => values.iter().any(|(key, value)| {
367            [
368                "token",
369                "api_key",
370                "access_token",
371                "password",
372                "secret",
373                "authorization",
374                "private_key",
375            ]
376            .iter()
377            .any(|sensitive| key.eq_ignore_ascii_case(sensitive))
378                || state_contains_obvious_credential(value)
379        }),
380        _ => false,
381    }
382}
383
384fn distribution_matches<'a>(
385    actual: &BTreeMap<String, f64>,
386    expected: impl Iterator<Item = &'a String>,
387) -> bool {
388    let expected: Vec<&String> = expected.collect();
389    actual.len() == expected.len()
390        && expected.iter().all(|key| actual.contains_key(*key))
391        && actual.values().all(|value| is_probability(*value))
392        && (actual.values().sum::<f64>() - 1.0).abs() <= 0.01
393}
394
395#[cfg(test)]
396mod tests {
397    use std::collections::BTreeMap;
398
399    use serde_json::json;
400
401    use super::{DecisionRequest, DecisionResponse, Question};
402
403    #[test]
404    fn test_should_reject_oversized_state() {
405        let request = DecisionRequest {
406            state: json!({ "body": "x".repeat(33_000) }),
407            questions: BTreeMap::from([(
408                "blocked".to_string(),
409                Question::Noul {
410                    instructions: "Is this blocked?".to_string(),
411                },
412            )]),
413        };
414        assert!(request.validate().is_err());
415    }
416
417    #[test]
418    fn test_should_reject_oversized_total_request() {
419        let criteria: BTreeMap<String, String> = (0..32)
420            .map(|index| (format!("option_{index}"), "x".repeat(512)))
421            .collect();
422        let questions = (0..16)
423            .map(|index| {
424                (
425                    format!("q_{index}"),
426                    Question::Choice {
427                        instructions: "Choose one".into(),
428                        criteria: criteria.clone(),
429                    },
430                )
431            })
432            .collect();
433        let request = DecisionRequest {
434            state: json!("small"),
435            questions,
436        };
437        assert!(request.validate().is_err());
438    }
439
440    #[test]
441    fn test_should_reject_empty_state() {
442        let mut request = DecisionRequest {
443            state: json!("   "),
444            questions: BTreeMap::from([(
445                "blocked".into(),
446                Question::Noul {
447                    instructions: "Is this blocked?".into(),
448                },
449            )]),
450        };
451        assert!(request.validate().is_err());
452        request.state = json!({});
453        assert!(request.validate().is_err());
454        request.state = json!([]);
455        assert!(request.validate().is_err());
456    }
457
458    #[test]
459    fn test_should_reject_obvious_credential_in_state() {
460        let mut request = DecisionRequest {
461            state: json!({"title": format!("credential {}{}", "apikey_", "x".repeat(40))}),
462            questions: BTreeMap::from([(
463                "blocked".into(),
464                Question::Noul {
465                    instructions: "Is this blocked?".into(),
466                },
467            )]),
468        };
469        assert!(request.validate().is_err());
470        request.state = json!({"token": "something-private"});
471        assert!(request.validate().is_err());
472    }
473
474    #[test]
475    fn test_should_reject_answer_with_unknown_choice() {
476        let request = DecisionRequest {
477            state: json!({ "title": "Fix crash" }),
478            questions: BTreeMap::from([(
479                "type".to_string(),
480                Question::Choice {
481                    instructions: "Classify the issue".to_string(),
482                    criteria: BTreeMap::from([
483                        ("bug".to_string(), "Broken behavior".to_string()),
484                        ("feature".to_string(), "New behavior".to_string()),
485                    ]),
486                },
487            )]),
488        };
489        let response: DecisionResponse = serde_json::from_value(json!({
490            "model": "jev-1.13.0",
491            "answers": {"type": {
492                "type": "choice", "choice": "other", "confidence": 0.9,
493                "probabilities": {"bug": 0.1, "feature": 0.9}
494            }},
495            "usage": {"input_tokens": 10, "output_tokens": 3}
496        }))
497        .unwrap();
498        assert!(response.validate_against(&request).is_err());
499    }
500
501    #[test]
502    fn test_should_accept_valid_noul_answer() {
503        let request = DecisionRequest {
504            state: json!({ "title": "CI fails" }),
505            questions: BTreeMap::from([(
506                "blocked".to_string(),
507                Question::Noul {
508                    instructions: "Is work blocked?".to_string(),
509                },
510            )]),
511        };
512        let response: DecisionResponse = serde_json::from_value(json!({
513            "model": "jev-1.13.0",
514            "answers": {"blocked": {"type": "noul", "noul": 0.8}},
515            "usage": {"input_tokens": 10, "output_tokens": 2}
516        }))
517        .unwrap();
518        assert!(request.validate().is_ok());
519        assert!(response.validate_against(&request).is_ok());
520    }
521}