1use std::collections::BTreeMap;
4
5use async_trait::async_trait;
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8use thiserror::Error;
9
10pub const MAX_STATE_BYTES: usize = 32_768;
12pub const MAX_QUESTIONS: usize = 16;
14pub const MAX_CHOICE_OPTIONS: usize = 32;
16pub const MAX_SCORE_LEVELS: usize = 10;
18pub const MAX_REQUEST_BYTES: usize = 131_072;
20
21#[derive(Debug, Clone, Serialize, Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct DecisionRequest {
25 pub state: Value,
27 pub questions: BTreeMap<String, Question>,
29}
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
33#[serde(tag = "type", rename_all = "lowercase", deny_unknown_fields)]
34pub enum Question {
35 Noul {
37 instructions: String,
39 },
40 Choice {
42 instructions: String,
44 criteria: BTreeMap<String, String>,
46 },
47 Score {
49 instructions: String,
51 criteria: Vec<String>,
53 },
54}
55
56#[derive(Debug, Clone, Serialize, Deserialize)]
58#[serde(tag = "type", rename_all = "lowercase", deny_unknown_fields)]
59pub enum TypedAnswer {
60 Noul {
62 noul: f64,
64 },
65 Choice {
67 choice: String,
69 confidence: f64,
71 probabilities: BTreeMap<String, f64>,
73 },
74 Score {
76 score: f64,
78 confidence: f64,
80 legend: BTreeMap<String, String>,
82 probabilities: BTreeMap<String, f64>,
84 },
85}
86
87#[derive(Debug, Clone, Serialize, Deserialize)]
89#[serde(deny_unknown_fields)]
90pub struct DecisionUsage {
91 pub input_tokens: u64,
93 pub output_tokens: u64,
95}
96
97#[derive(Debug, Clone, Serialize, Deserialize)]
99#[serde(deny_unknown_fields)]
100pub struct DecisionResponse {
101 pub model: String,
103 pub answers: BTreeMap<String, TypedAnswer>,
105 pub usage: DecisionUsage,
107}
108
109#[derive(Debug, Error)]
111#[non_exhaustive]
112pub enum DecisionError {
113 #[error("decision provider unavailable")]
115 Unavailable,
116 #[error("invalid decision request: {0}")]
118 InvalidInput(&'static str),
119 #[error("invalid decision response: {0}")]
121 InvalidResponse(&'static str),
122 #[error("decision provider timed out")]
124 Timeout,
125 #[error("decision provider request failed")]
127 Transport,
128}
129
130#[async_trait]
132pub trait DecisionEngine: std::fmt::Debug + Send + Sync {
133 async fn decide(&self, request: &DecisionRequest) -> Result<DecisionResponse, DecisionError>;
140}
141
142impl DecisionRequest {
143 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 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}