1use std::collections::BTreeMap;
9use std::time::{SystemTime, UNIX_EPOCH};
10
11use serde::{Deserialize, Serialize};
12
13use super::recall::EXHAUSTIVE_LIMIT;
14use super::{
15 ensure_project, get_experience, lesson_from_event, record_observed_check_unlocked,
16 record_unlocked, required_event, resolve_case, validation, ConditionalLesson,
17 ExperienceContext, ExperienceEvent, LessonApplicability, LessonEvidence, LessonVisibility,
18 ObservedCheck, RecordEvent, EXPERIENCE_MUTATIONS, ROLE_LESSON,
19};
20use crate::error::Result;
21use crate::store::Store;
22use crate::task_memory::{TaskArtifact, TaskSearchFilters};
23
24pub const MAX_CASE_BYTES: usize = 32 * 1024;
26const SHARED_ID_PREFIX: &str = "agentdash:";
27
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
30#[serde(deny_unknown_fields)]
31pub struct CaseFile {
32 pub problem: String,
33 pub symptoms: Vec<String>,
34 #[serde(default)]
35 pub failed: Vec<String>,
36 pub fix: String,
37 pub check: CaseCheck,
38 #[serde(default)]
39 pub applies_when: BTreeMap<String, String>,
40 #[serde(default)]
41 pub evidence: Vec<String>,
42 #[serde(default = "shared")]
43 pub visibility: LessonVisibility,
44}
45
46#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
48#[serde(deny_unknown_fields)]
49pub struct CaseCheck {
50 pub method: CheckMethod,
51 pub result: String,
52 #[serde(
53 default,
54 deserialize_with = "present",
55 skip_serializing_if = "Option::is_none"
56 )]
57 pub command: Option<String>,
58 #[serde(
60 default,
61 deserialize_with = "present",
62 skip_serializing_if = "Option::is_none"
63 )]
64 pub receipt_id: Option<String>,
65}
66
67fn present<'de, D, T>(deserializer: D) -> std::result::Result<Option<T>, D::Error>
70where
71 D: serde::Deserializer<'de>,
72 T: Deserialize<'de>,
73{
74 T::deserialize(deserializer).map(Some)
75}
76
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
78#[serde(rename_all = "snake_case")]
79pub enum CheckMethod {
80 Observed,
81 Executed,
82}
83
84fn shared() -> LessonVisibility {
85 LessonVisibility::Shared
86}
87
88impl CaseFile {
89 pub fn parse(bytes: &[u8]) -> Result<Self> {
91 if bytes.len() > MAX_CASE_BYTES {
92 return Err(validation(format!(
93 "case file is {} bytes; the limit is 32 KiB",
94 bytes.len()
95 )));
96 }
97 let value: serde_json::Value = serde_json::from_slice(bytes)
98 .map_err(|error| validation(format!("invalid case file: {error}")))?;
99 reject_nulls(&value, "")?;
100 let case: Self = serde_json::from_value(value)
101 .map_err(|error| validation(format!("invalid case file: {error}")))?;
102 case.validate()?;
103 Ok(case)
104 }
105
106 pub fn validate(&self) -> Result<()> {
108 text("problem", &self.problem, 300)?;
109 items("symptoms", &self.symptoms, 1, 12, 80)?;
110 items("failed", &self.failed, 0, 8, 300)?;
111 text("fix", &self.fix, 1000)?;
112 text("check.result", &self.check.result, 300)?;
113 if let Some(command) = &self.check.command {
114 text("check.command", command, 300)?;
115 }
116 if let Some(receipt_id) = &self.check.receipt_id {
117 text("check.receipt_id", receipt_id, 80)?;
118 if self.check.method != CheckMethod::Executed {
119 return Err(validation("check.receipt_id requires method \"executed\""));
120 }
121 }
122 if self.applies_when.len() > 8 {
123 return Err(validation("applies_when may hold at most 8 keys"));
124 }
125 for (key, value) in &self.applies_when {
126 if !is_condition_key(key) {
127 return Err(validation(format!(
128 "applies_when key '{key}' must match ^[a-z][a-z0-9_]{{0,31}}$"
129 )));
130 }
131 text(&format!("applies_when.{key}"), value, 80)?;
132 }
133 if self.applies_when.contains_key("version") && !self.applies_when.contains_key("tool") {
134 return Err(validation(
135 "applies_when.version requires applies_when.tool",
136 ));
137 }
138 items("evidence", &self.evidence, 0, 8, 300)?;
139 Ok(())
140 }
141}
142
143fn reject_nulls(value: &serde_json::Value, prefix: &str) -> Result<()> {
147 let Some(object) = value.as_object() else {
148 return Ok(());
149 };
150 for (key, field) in object {
151 if field.is_null() {
152 return Err(validation(format!(
153 "invalid case file: {prefix}{key} must be left out or have a value, not null"
154 )));
155 }
156 if key == "check" && prefix.is_empty() {
157 reject_nulls(field, "check.")?;
158 }
159 }
160 Ok(())
161}
162
163fn text(field: &str, value: &str, max: usize) -> Result<()> {
164 if value.trim().is_empty() || value.chars().count() > max {
165 return Err(validation(format!(
166 "{field} must be 1..{max} characters and not blank"
167 )));
168 }
169 Ok(())
170}
171
172fn items(field: &str, values: &[String], min: usize, max: usize, each: usize) -> Result<()> {
173 if values.len() < min || values.len() > max {
174 return Err(validation(format!("{field} must hold {min}..{max} items")));
175 }
176 values
177 .iter()
178 .try_for_each(|value| text(&format!("{field} item"), value, each))
179}
180
181fn is_condition_key(key: &str) -> bool {
182 let mut bytes = key.bytes();
183 bytes.next().is_some_and(|byte| byte.is_ascii_lowercase())
184 && key.len() <= 32
185 && bytes.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_')
186}
187
188fn validate_shared_id(id: &str) -> Result<()> {
189 let mut bytes = id.bytes();
190 let valid = id.len() <= 80
191 && bytes
192 .next()
193 .is_some_and(|byte| byte.is_ascii_alphanumeric())
194 && bytes.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'));
195 if valid {
196 Ok(())
197 } else {
198 Err(validation(
199 "shared ID must be 1..80 characters of letters, digits, '.', '_' or '-'",
200 ))
201 }
202}
203
204#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
206pub struct NoteOutcome {
207 pub problem_id: String,
208 pub attempt_ids: Vec<String>,
209 pub check_id: String,
210 pub lesson_id: String,
211 pub evidence: LessonEvidence,
212 pub replay: bool,
214}
215
216pub async fn record_case<S: Store + ?Sized>(
241 store: &S,
242 mut context: ExperienceContext,
243 case: CaseFile,
244 shared_id: Option<&str>,
245) -> Result<NoteOutcome> {
246 case.validate()?;
247 if context.project_id.as_option().is_none() {
248 return Err(validation(
249 "experience cases require an explicit project_id",
250 ));
251 }
252 if let Some(id) = shared_id {
253 validate_shared_id(id)?;
254 context.provenance.uri = Some(format!("{SHARED_ID_PREFIX}{id}"));
255 }
256
257 let _guard = EXPERIENCE_MUTATIONS.lock().await;
258 if let Some(lesson) = find_replay(store, &context, &case).await? {
259 return outcome_for(store, &context, &lesson, true).await;
260 }
261 match (case.check.method, case.check.receipt_id.as_deref()) {
262 (CheckMethod::Executed, Some(receipt_id)) => {
263 attach_to_receipt(store, context, &case, receipt_id).await
264 }
265 _ => create_case(store, context, &case).await,
266 }
267}
268
269async fn create_case<S: Store + ?Sized>(
270 store: &S,
271 context: ExperienceContext,
272 case: &CaseFile,
273) -> Result<NoteOutcome> {
274 let mut clock = Clock::new(context.observed_at_ms);
275 let problem = record_unlocked(
276 store,
277 clock.tick(&context),
278 RecordEvent::Problem {
279 description: case.problem.clone(),
280 symptom_terms: case.symptoms.clone(),
281 },
282 )
283 .await?;
284
285 let mut attempt_ids: Vec<String> = Vec::new();
286 for action in case.failed.iter().chain(std::iter::once(&case.fix)) {
287 let attempt = record_unlocked(
288 store,
289 clock.tick(&context),
290 RecordEvent::Attempt {
291 problem_id: problem.artifact_id.clone(),
292 previous_attempt_id: attempt_ids.last().cloned(),
293 action: action.clone(),
294 },
295 )
296 .await?;
297 attempt_ids.push(attempt.artifact_id);
298 }
299 let fix_attempt_id = attempt_ids.last().cloned().expect("the fix is an attempt");
300
301 let check = record_observed_check_unlocked(
302 store,
303 clock.tick(&context),
304 ObservedCheck {
305 attempt_id: fix_attempt_id,
306 result: case.check.result.clone(),
307 command: case.check.command.clone(),
308 },
309 )
310 .await?;
311 let lesson = record_unlocked(
312 store,
313 clock.tick(&context),
314 RecordEvent::Lesson(lesson_from_case(
315 case,
316 &problem.artifact_id,
317 &check.artifact_id,
318 LessonEvidence::Observed,
319 )),
320 )
321 .await?;
322 Ok(NoteOutcome {
323 problem_id: problem.artifact_id,
324 attempt_ids,
325 check_id: check.artifact_id,
326 lesson_id: lesson.artifact_id,
327 evidence: LessonEvidence::Observed,
328 replay: false,
329 })
330}
331
332async fn attach_to_receipt<S: Store + ?Sized>(
333 store: &S,
334 context: ExperienceContext,
335 case: &CaseFile,
336 receipt_id: &str,
337) -> Result<NoteOutcome> {
338 let check = get_experience(store, &context.tenant_id, receipt_id)
339 .await?
340 .ok_or_else(|| validation(format!("receipt '{receipt_id}' does not exist")))?;
341 let ExperienceEvent::Check(receipt) = required_event(&check)? else {
342 return Err(validation(format!(
343 "artifact '{receipt_id}' is not an executed check receipt"
344 )));
345 };
346 if !receipt.supports_lesson() {
347 return Err(validation(
348 "receipt must have exit_code 0, no timeout, complete output hashes, and unchanged source evidence",
349 ));
350 }
351 ensure_project(&context.project_id, &check.project_id)?;
352 let attempt = get_experience(store, &context.tenant_id, &receipt.attempt_id)
353 .await?
354 .ok_or_else(|| validation(format!("attempt '{}' does not exist", receipt.attempt_id)))?;
355 let ExperienceEvent::Attempt { problem_id, .. } = required_event(&attempt)? else {
356 return Err(validation(format!(
357 "receipt '{receipt_id}' does not check an attempt"
358 )));
359 };
360
361 let mut clock = Clock::new(context.observed_at_ms);
362 let lesson = record_unlocked(
363 store,
364 clock.tick(&context),
365 RecordEvent::Lesson(lesson_from_case(
366 case,
367 problem_id,
368 receipt_id,
369 LessonEvidence::Executed,
370 )),
371 )
372 .await?;
373 outcome_for(store, &context, &lesson, false).await
374}
375
376fn lesson_from_case(
377 case: &CaseFile,
378 problem_id: &str,
379 check_id: &str,
380 evidence: LessonEvidence,
381) -> ConditionalLesson {
382 let mut context = case.applies_when.clone();
383 let applicability = LessonApplicability {
384 machine: context.remove("machine"),
385 tool: context.remove("tool"),
386 version: context.remove("version"),
387 };
388 ConditionalLesson {
389 problem_id: problem_id.to_string(),
390 supporting_check_id: check_id.to_string(),
391 guidance: case.fix.clone(),
392 symptom_terms: case.symptoms.clone(),
393 applicability,
394 visibility: case.visibility,
395 evidence,
396 context,
397 links: case.evidence.clone(),
398 conflicts_with: Vec::new(),
399 }
400}
401
402async fn find_replay<S: Store + ?Sized>(
404 store: &S,
405 context: &ExperienceContext,
406 case: &CaseFile,
407) -> Result<Option<TaskArtifact>> {
408 let filters = TaskSearchFilters {
409 artifact_role: Some(ROLE_LESSON.to_string()),
410 project_id: context.project_id.as_option().map(str::to_string),
411 ..Default::default()
412 };
413 let chunk_ids = store
414 .search_task_projection_chunk_ids(&context.tenant_id, &filters, EXHAUSTIVE_LIMIT)
415 .await?;
416 let mut lessons = store
417 .resolve_artifacts_for_chunks(&context.tenant_id, &chunk_ids)
418 .await?
419 .into_values()
420 .filter(|artifact| artifact.project_id == context.project_id)
421 .collect::<Vec<_>>();
422 lessons.sort_by(|left, right| left.artifact_id.cmp(&right.artifact_id));
424
425 if let Some(uri) = context.provenance.uri.as_deref() {
426 return Ok(lessons
427 .into_iter()
428 .find(|artifact| artifact.provenance.uri.as_deref() == Some(uri)));
429 }
430 for artifact in lessons {
431 if has_same_content(store, context, case, &artifact).await? {
432 return Ok(Some(artifact));
433 }
434 }
435 Ok(None)
436}
437
438async fn has_same_content<S: Store + ?Sized>(
441 store: &S,
442 context: &ExperienceContext,
443 case: &CaseFile,
444 artifact: &TaskArtifact,
445) -> Result<bool> {
446 let Some(lesson) = artifact.experience.as_ref().and_then(lesson_from_event) else {
447 return Ok(false);
448 };
449 if lesson.guidance != case.fix
450 || lesson.symptom_terms != case.symptoms
451 || applies_when_of(lesson) != case.applies_when
452 {
453 return Ok(false);
454 }
455 let receipt_id = case
456 .check
457 .receipt_id
458 .as_deref()
459 .filter(|_| case.check.method == CheckMethod::Executed);
460 if let Some(receipt_id) = receipt_id {
461 return Ok(lesson.supporting_check_id == receipt_id);
464 }
465 let Some(check) =
466 get_experience(store, &context.tenant_id, &lesson.supporting_check_id).await?
467 else {
468 return Ok(false);
469 };
470 let Some(ExperienceEvent::ObservedCheck(observed)) = check.experience.as_ref() else {
471 return Ok(false);
472 };
473 if observed.result != case.check.result || observed.command != case.check.command {
474 return Ok(false);
475 }
476 let problem = get_experience(store, &context.tenant_id, &lesson.problem_id).await?;
477 Ok(matches!(
478 problem.as_ref().and_then(|problem| problem.experience.as_ref()),
479 Some(ExperienceEvent::Problem { description, .. }) if *description == case.problem
480 ))
481}
482
483fn applies_when_of(lesson: &ConditionalLesson) -> BTreeMap<String, String> {
485 let mut conditions = lesson.context.clone();
486 for (key, value) in [
487 ("machine", &lesson.applicability.machine),
488 ("tool", &lesson.applicability.tool),
489 ("version", &lesson.applicability.version),
490 ] {
491 if let Some(value) = value {
492 conditions.insert(key.to_string(), value.clone());
493 }
494 }
495 conditions
496}
497
498async fn outcome_for<S: Store + ?Sized>(
499 store: &S,
500 context: &ExperienceContext,
501 lesson_artifact: &TaskArtifact,
502 replay: bool,
503) -> Result<NoteOutcome> {
504 let lesson = lesson_from_event(required_event(lesson_artifact)?)
505 .ok_or_else(|| validation("stored artifact is not a lesson"))?;
506 let stored = resolve_case(store, &context.tenant_id, &lesson.problem_id).await?;
507 let attempt_ids = stored
508 .events
509 .iter()
510 .filter(|artifact| matches!(artifact.experience, Some(ExperienceEvent::Attempt { .. })))
511 .map(|artifact| artifact.artifact_id.clone())
512 .collect();
513 Ok(NoteOutcome {
514 problem_id: lesson.problem_id.clone(),
515 attempt_ids,
516 check_id: lesson.supporting_check_id.clone(),
517 lesson_id: lesson_artifact.artifact_id.clone(),
518 evidence: lesson.evidence,
519 replay,
520 })
521}
522
523struct Clock(i64);
526
527impl Clock {
528 fn new(requested: Option<i64>) -> Self {
529 Self(requested.unwrap_or_else(|| {
530 SystemTime::now()
531 .duration_since(UNIX_EPOCH)
532 .map(|elapsed| elapsed.as_millis() as i64)
533 .unwrap_or(0)
534 }))
535 }
536
537 fn tick(&mut self, context: &ExperienceContext) -> ExperienceContext {
538 let mut stamped = context.clone();
539 stamped.observed_at_ms = Some(self.0);
540 self.0 += 1;
541 stamped
542 }
543}
544
545#[cfg(test)]
546mod tests {
547 use super::*;
548
549 fn minimal() -> serde_json::Value {
550 serde_json::json!({
551 "problem": "p",
552 "symptoms": ["s"],
553 "fix": "f",
554 "check": {"method": "observed", "result": "r"}
555 })
556 }
557
558 #[test]
559 fn defaults_fill_in_and_visibility_is_shared() {
560 let case = CaseFile::parse(minimal().to_string().as_bytes()).unwrap();
561 assert!(case.failed.is_empty() && case.evidence.is_empty());
562 assert!(case.applies_when.is_empty());
563 assert_eq!(case.visibility, LessonVisibility::Shared);
564 }
565
566 #[test]
567 fn a_null_optional_is_an_error_for_every_reader() {
568 let mut value = minimal();
571 value["check"]["command"] = serde_json::Value::Null;
572 assert!(serde_json::from_value::<CaseFile>(value.clone()).is_err());
573 assert!(CaseFile::parse(value.to_string().as_bytes()).is_err());
574 value["check"]["command"] = serde_json::json!("run it");
575 value["check"]["receipt_id"] = serde_json::Value::Null;
576 assert!(serde_json::from_value::<CaseFile>(value).is_err());
577 }
578
579 #[test]
580 fn length_counts_characters_not_bytes() {
581 let mut value = minimal();
582 value["symptoms"] = serde_json::json!(["é".repeat(80)]);
583 assert!(CaseFile::parse(value.to_string().as_bytes()).is_ok());
584 value["symptoms"] = serde_json::json!(["é".repeat(81)]);
585 assert!(CaseFile::parse(value.to_string().as_bytes()).is_err());
586 }
587
588 #[test]
589 fn condition_keys_follow_the_contract_pattern() {
590 for good in ["a", "tool", "os_2", "a".repeat(32).as_str()] {
591 assert!(is_condition_key(good), "{good}");
592 }
593 for bad in ["", "Tool", "2os", "a-b", "a".repeat(33).as_str()] {
594 assert!(!is_condition_key(bad), "{bad}");
595 }
596 }
597
598 #[test]
599 fn shared_ids_are_path_safe() {
600 assert!(validate_shared_id("EXP-17").is_ok());
601 assert!(validate_shared_id("").is_err());
602 assert!(validate_shared_id("a b").is_err());
603 assert!(validate_shared_id("-lead").is_err());
604 assert!(validate_shared_id(&"x".repeat(81)).is_err());
605 }
606}