Skip to main content

memd/experience/
note.rs

1//! One-call capture of a solved problem from a case file.
2//!
3//! The case file is the exchange format shared with other tools (see
4//! `docs/experience-memory.md`). [`record_case`] turns it into the same
5//! typed records the four-step audit path writes: a problem, one attempt per
6//! failed approach plus one for the fix, a check on the fix, and a lesson.
7
8use 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
24/// Largest accepted case file, in bytes.
25pub const MAX_CASE_BYTES: usize = 32 * 1024;
26const SHARED_ID_PREFIX: &str = "agentdash:";
27
28/// A solved problem as an agent writes it. Unknown fields are rejected.
29#[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/// How the fix was verified.
47#[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    /// ID of a passing memd check receipt. Only valid with `executed`.
59    #[serde(
60        default,
61        deserialize_with = "present",
62        skip_serializing_if = "Option::is_none"
63    )]
64    pub receipt_id: Option<String>,
65}
66
67/// Deserialize an optional field that must be left out or given a value.
68/// Without this, serde reads an explicit `null` as "absent".
69fn 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    /// Parse and validate a case file. The size limit applies to the raw bytes.
90    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    /// Check every field against the exchange contract.
107    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
143/// An optional field is left out or given a value. An explicit `null` in the
144/// case object or its `check` object is an error, like an unknown field, so a
145/// file means one thing to every tool that reads it.
146fn 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/// What [`record_case`] stored, or found already stored.
205#[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    /// True when the case was already stored and nothing was written.
213    pub replay: bool,
214}
215
216/// Store a case file as problem, attempts, check, and lesson.
217///
218/// Every input is validated before the first write, and the mutation lock is
219/// held across the whole sequence, so concurrent notes cannot interleave.
220///
221/// The check decides the lesson's evidence label:
222/// * `observed`, or `executed` without `receipt_id`: memd saw no command run,
223///   so the check is an [`ObservedCheck`] and the lesson reads `observed`.
224/// * `executed` with `receipt_id`: the receipt must be a passing check already
225///   in this store. The lesson is added to that receipt's problem, which keeps
226///   its own attempts, and reads `executed`.
227///
228/// A call is a replay only when it repeats a stored submission, and then it
229/// writes nothing and returns the stored case:
230/// * With `shared_id`, the artifacts carry `agentdash:<id>` as provenance, and
231///   a stored lesson with the same ID is the same submission. The content is
232///   not compared, and a different ID never matches.
233/// * Without `shared_id`, a stored lesson in this project with the same
234///   canonical content is the same submission: problem, symptoms, fix, check
235///   (result and command, or the receipt), and `applies_when`. `failed`,
236///   `evidence`, and `visibility` are not part of that content.
237///
238/// Anything else adds a case, or, for a receipt, a lesson on the receipt's
239/// problem.
240pub 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
402/// The stored lesson this call repeats, if any (see [`record_case`]).
403async 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    // Stable pick when several stored lessons match.
423    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
438/// Compare a stored lesson with the canonical content of `case`. Cheap fields
439/// come first, so the problem and the check load only for a close match.
440async 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        // The lesson sits on the receipt's own problem, which the file does
462        // not describe, so the receipt is the whole check and problem match.
463        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
483/// The `applies_when` object a lesson was built from.
484fn 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
523/// Hands out strictly increasing observation times, so the records of one
524/// case order by cause even when they land in the same millisecond.
525struct 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        // The struct rejects null itself, so a case that arrives as arguments
569        // to `experience.note` is held to the same rule as a parsed file.
570        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}