cortex_llm/

summary.rs

//! Pluggable LLM summary backend used by the Phase 4.D decay path.
//!
//! Where [`crate::adapter::LlmAdapter`] is the general-purpose async LLM call
//! surface for reflection / proof / extraction, [`SummaryBackend`] is the
//! **narrow, synchronous** trait the decay-job pipeline talks to when it
//! needs to compress N candidate memories or episodes down to one summary
//! memory under operator attestation. The two surfaces are kept disjoint on
//! purpose:
//!
//! - The decay path is operator-gated and pins both `model_name` and
//!   `prompt_template_blake3` in the attestation envelope; the trait's
//!   request shape carries those pins verbatim so the implementation can
//!   refuse on mismatch BEFORE making any backend call.
//! - The decay path is synchronous (called from inside a transactional
//!   runner step); we do not need the async ceremony.
//! - The decay path's failure modes (`BackendNotConfigured`,
//!   `ModelNotInAllowlist`, `PromptTemplateMismatch`, ...) are different
//!   in kind from the generic adapter's transport / parse / timeout
//!   alphabet — keeping them in a typed enum here means
//!   `cortex_memory::decay` can match on stable variants for grep-friendly
//!   refusal envelopes.
//!
//! ## Implementations shipped today
//!
//! - [`NoopSummaryBackend`] — fail-closed default. Every CLI surface that
//!   wires the decay runner today injects this so an LLM-summary job
//!   surfaces a typed `BackendNotConfigured` rather than panicking.
//! - [`ReplaySummaryBackend`] — deterministic CI fixture backend. Mirrors
//!   [`crate::replay::ReplayAdapter`] but with a much simpler key shape
//!   (BLAKE3 of the canonicalised summary request fields).
//!
//! Hosted backends (Claude, Ollama) plug into the same trait by validating
//! their own `model_name` allowlist and `prompt_template_blake3` before
//! making the actual call.

use std::collections::HashMap;
use std::fmt;
use std::fs;
use std::path::Path;

use serde::{Deserialize, Serialize};
use thiserror::Error;

use crate::adapter::{blake3_hex, TokenUsage};

/// One claim or episode summary fed in as a source for compression.
///
/// Kept as a plain owned string so callers do not have to learn the cortex-
/// store row shape to drive the backend; the decay-path translation layer
/// is responsible for picking the right text (memory `claim`, episode
/// `summary`) and forwarding it here.
pub type SourceClaim = String;

/// Input to a [`SummaryBackend::summarize`] call.
///
/// Field shape is deliberately small. The two pins (`model_name`,
/// `prompt_template_blake3`) come from the operator-signed attestation
/// envelope at `cortex_memory::decay::summary::LlmSummaryOperatorAttestationEnvelope`
/// so the backend's allowlist check is structurally bound to the same
/// signed authority surface.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SummaryRequest {
    /// Pinned model name (e.g. `claude-sonnet-4-7@1`). Backends MUST refuse
    /// if their resolved model is not on the local allowlist; the
    /// `ReplaySummaryBackend` refuses on exact-string mismatch with the
    /// fixture key.
    pub model_name: String,
    /// Pinned BLAKE3 digest (prefixed `blake3:`) of the prompt template
    /// that will be sent. Backends MUST refuse on mismatch with their
    /// resolved template before any call.
    pub prompt_template_blake3: String,
    /// Source claims in the order the decay-job manifest lists them. The
    /// fixture and any hosted backend MAY reorder internally but MUST NOT
    /// drop entries.
    pub source_claims: Vec<SourceClaim>,
    /// Optional byte budget on the produced summary. Backends MAY truncate
    /// or refuse on exceedance; the decay path will always re-check the
    /// produced length downstream.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_output_bytes: Option<usize>,
    /// Optional decay job id stamped onto the request for correlation /
    /// fixture key derivation. The fixture backend keys on the canonical
    /// request bytes, so two calls with the same model, prompt, and
    /// sources collide unless this field disambiguates them.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub decay_job_id: Option<String>,
}

impl SummaryRequest {
    /// Stable BLAKE3 hash over the canonicalised request fields. The hash
    /// is the lookup key for the [`ReplaySummaryBackend`] fixture map and
    /// is also a useful audit-correlation hint.
    ///
    /// Hash domain is `cortex.llm.summary.request.v1` so a captured hash
    /// cannot collide with the [`crate::LlmRequest::prompt_hash`] domain.
    #[must_use]
    pub fn request_hash(&self) -> String {
        let canonical = CanonicalSummaryRequest {
            domain: "cortex.llm.summary.request.v1",
            model_name: &self.model_name,
            prompt_template_blake3: &self.prompt_template_blake3,
            source_claims: &self.source_claims,
            max_output_bytes: self.max_output_bytes,
            decay_job_id: self.decay_job_id.as_deref(),
        };
        let bytes =
            serde_json::to_vec(&canonical).expect("CanonicalSummaryRequest is always serializable");
        blake3_hex(&bytes)
    }
}

/// Internal helper: the subset of [`SummaryRequest`] that participates in
/// `request_hash()`. Borrowed-references-only so we never copy the payload.
#[derive(Serialize)]
struct CanonicalSummaryRequest<'a> {
    domain: &'static str,
    model_name: &'a str,
    prompt_template_blake3: &'a str,
    source_claims: &'a [SourceClaim],
    #[serde(skip_serializing_if = "Option::is_none")]
    max_output_bytes: Option<usize>,
    #[serde(skip_serializing_if = "Option::is_none")]
    decay_job_id: Option<&'a str>,
}

/// Result of a successful [`SummaryBackend::summarize`] call.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SummaryResponse {
    /// The produced summary text. Must be non-empty; the decay path
    /// re-validates this and refuses if the backend echoes an empty
    /// claim.
    pub claim: String,
    /// Token-usage echo from the provider, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token_usage: Option<TokenUsage>,
    /// The model name the backend says actually produced the response.
    /// The decay path verifies this byte-equals
    /// [`SummaryRequest::model_name`] and refuses on mismatch (so a
    /// silently-routed provider cannot launder an attestation pin).
    pub model_name_echoed: String,
}

/// Errors raised by any [`SummaryBackend`] implementation.
///
/// Each variant displays in a grep-friendly shape (the discriminator
/// appears verbatim in the message) so operator scripts can match on a
/// stable contract.
#[derive(Debug, Error, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum SummaryError {
    /// No backend is wired (or the wired backend has no configured
    /// upstream). This is the [`NoopSummaryBackend`]'s only return shape.
    #[error("summary_backend_not_configured")]
    BackendNotConfigured,
    /// The request's `model_name` pin is not on the backend's local
    /// allowlist.
    #[error("summary_model_not_in_allowlist: {0}")]
    ModelNotInAllowlist(String),
    /// The request's `prompt_template_blake3` pin does not match the
    /// backend's resolved template.
    #[error("summary_prompt_template_mismatch: {0}")]
    PromptTemplateMismatch(String),
    /// The backend's upstream call failed (transport, upstream non-2xx,
    /// timeout, etc.). The message is opaque to the trait but must be
    /// non-empty.
    #[error("summary_call_failed: {0}")]
    CallFailed(String),
    /// The backend's upstream returned a payload that failed local
    /// structural validation (empty claim, byte budget exceeded, ...).
    #[error("summary_output_validation_failed: {0}")]
    OutputValidationFailed(String),
}

/// Pluggable LLM summary backend used by the Phase 4.D decay path.
///
/// Contract:
///
/// - `summarize(request)` takes a deterministic input (model_name pin,
///   prompt_template_blake3 pin, source claims, byte budget) and returns
///   either a summary string + token usage or a typed error.
/// - Implementations MUST validate the `model_name` pin against their own
///   allowlist BEFORE making any backend call.
/// - Implementations MUST be deterministic given the same input when used
///   in CI / fixture mode (see [`ReplaySummaryBackend`]).
/// - Implementations MUST NOT panic on invalid inputs; the decay runner
///   relies on every refusal returning a typed [`SummaryError`].
///
/// `Send + Sync + Debug` is required so the runtime can hold a
/// `&dyn SummaryBackend` across thread boundaries.
pub trait SummaryBackend: fmt::Debug + Send + Sync {
    /// Issue a summary call. The implementation owns its own timeout
    /// budget and MUST surface timeouts as
    /// [`SummaryError::CallFailed`].
    fn summarize(&self, request: &SummaryRequest) -> Result<SummaryResponse, SummaryError>;
}

/// Fail-closed default backend.
///
/// Every CLI surface that wires the decay runner today injects this so
/// an LLM-summary job surfaces a typed `BackendNotConfigured` refusal
/// rather than panicking. Pattern mirrors `NoopCalendarClient` in the
/// OTS external sink.
#[derive(Debug, Default, Clone, Copy)]
pub struct NoopSummaryBackend;

impl SummaryBackend for NoopSummaryBackend {
    fn summarize(&self, _request: &SummaryRequest) -> Result<SummaryResponse, SummaryError> {
        Err(SummaryError::BackendNotConfigured)
    }
}

/// Deterministic fixture-backed summary backend for CI and tests.
///
/// Constructed from a `HashMap<RequestKey, SummaryResponse>` keyed by the
/// canonical BLAKE3 of the request fields ([`SummaryRequest::request_hash`]).
/// A lookup miss returns [`SummaryError::BackendNotConfigured`] with a
/// detailed reason so test failure messages stay actionable.
///
/// Use [`ReplaySummaryBackend::from_fixture_file`] to load a JSON fixture
/// keyed by `(model_name, prompt_template_blake3, ordered source claims,
/// max_output_bytes, decay_job_id)`.
#[derive(Debug, Clone)]
pub struct ReplaySummaryBackend {
    by_hash: HashMap<String, SummaryResponse>,
}

/// On-disk JSON shape consumed by
/// [`ReplaySummaryBackend::from_fixture_file`]. The fixture is an array
/// of `{ request, response }` entries; the hash key is computed at load
/// time from the request fields.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReplaySummaryFixture {
    /// Entry rows in declaration order. Order is not significant —
    /// duplicates are refused at load time.
    pub entries: Vec<ReplaySummaryFixtureEntry>,
}

/// One row of a [`ReplaySummaryFixture`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReplaySummaryFixtureEntry {
    /// Request the fixture matches against. Hashed at load time.
    pub request: SummaryRequest,
    /// Response the fixture returns.
    pub response: SummaryResponse,
}

impl ReplaySummaryBackend {
    /// Construct a new replay backend from an in-memory request map.
    ///
    /// Duplicate request hashes are refused: the caller has either
    /// supplied two distinct fixtures that compute to the same request
    /// hash (cryptographic collision — implausible) or repeated the same
    /// fixture row by mistake (the more common case).
    pub fn from_entries(entries: Vec<ReplaySummaryFixtureEntry>) -> Result<Self, SummaryError> {
        let mut by_hash: HashMap<String, SummaryResponse> = HashMap::new();
        for entry in entries {
            let key = entry.request.request_hash();
            if by_hash.insert(key.clone(), entry.response).is_some() {
                return Err(SummaryError::CallFailed(format!(
                    "duplicate replay summary fixture for request_hash={key}"
                )));
            }
        }
        Ok(Self { by_hash })
    }

    /// Load a fixture file from disk and construct the backend.
    ///
    /// File is a JSON document matching the [`ReplaySummaryFixture`]
    /// shape. Errors map to [`SummaryError::CallFailed`] with a
    /// descriptive message so CI logs are actionable.
    pub fn from_fixture_file(path: &Path) -> Result<Self, SummaryError> {
        let raw = fs::read_to_string(path).map_err(|err| {
            SummaryError::CallFailed(format!("fixture `{}` not readable: {err}", path.display()))
        })?;
        let fixture: ReplaySummaryFixture = serde_json::from_str(&raw).map_err(|err| {
            SummaryError::CallFailed(format!("fixture `{}` did not parse: {err}", path.display()))
        })?;
        Self::from_entries(fixture.entries)
    }

    /// Number of fixture entries currently held.
    #[must_use]
    pub fn fixture_count(&self) -> usize {
        self.by_hash.len()
    }
}

impl SummaryBackend for ReplaySummaryBackend {
    fn summarize(&self, request: &SummaryRequest) -> Result<SummaryResponse, SummaryError> {
        let key = request.request_hash();
        match self.by_hash.get(&key) {
            Some(response) => Ok(response.clone()),
            None => Err(SummaryError::BackendNotConfigured),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::TempDir;

    fn sample_request(model: &str, prompt: &str, claims: &[&str]) -> SummaryRequest {
        SummaryRequest {
            model_name: model.into(),
            prompt_template_blake3: prompt.into(),
            source_claims: claims.iter().map(|s| (*s).to_string()).collect(),
            max_output_bytes: Some(2048),
            decay_job_id: Some("dcy_01ARZ3NDEKTSV4RRFFQ69G5FAV".into()),
        }
    }

    fn sample_response(claim: &str, model: &str) -> SummaryResponse {
        SummaryResponse {
            claim: claim.into(),
            token_usage: Some(TokenUsage {
                prompt_tokens: 10,
                completion_tokens: 20,
            }),
            model_name_echoed: model.into(),
        }
    }

    #[test]
    fn request_hash_is_stable_across_calls() {
        let req = sample_request(
            "claude-sonnet-4-7@1",
            "blake3:00000000000000000000000000000000",
            &["alpha", "beta"],
        );
        assert_eq!(req.request_hash(), req.request_hash());
    }

    #[test]
    fn request_hash_changes_with_any_field() {
        let base = sample_request("claude-sonnet-4-7@1", "blake3:0000", &["alpha", "beta"]);
        let mut model_changed = base.clone();
        model_changed.model_name = "other".into();
        assert_ne!(base.request_hash(), model_changed.request_hash());

        let mut claims_reordered = base.clone();
        claims_reordered.source_claims = vec!["beta".into(), "alpha".into()];
        assert_ne!(base.request_hash(), claims_reordered.request_hash());

        let mut prompt_changed = base.clone();
        prompt_changed.prompt_template_blake3 = "blake3:1111".into();
        assert_ne!(base.request_hash(), prompt_changed.request_hash());

        let mut job_changed = base.clone();
        job_changed.decay_job_id = Some("dcy_other".into());
        assert_ne!(base.request_hash(), job_changed.request_hash());
    }

    #[test]
    fn noop_backend_fails_closed() {
        let backend = NoopSummaryBackend;
        let req = sample_request("any-model", "blake3:00", &["one"]);
        let err = backend.summarize(&req).unwrap_err();
        assert_eq!(err, SummaryError::BackendNotConfigured);
        // Display must contain the discriminator token for grep tooling.
        assert!(err.to_string().contains("summary_backend_not_configured"));
    }

    #[test]
    fn replay_backend_round_trips_a_pre_baked_response() {
        let req = sample_request("claude-sonnet-4-7@1", "blake3:abcd", &["alpha", "beta"]);
        let resp = sample_response("alpha and beta", "claude-sonnet-4-7@1");
        let backend = ReplaySummaryBackend::from_entries(vec![ReplaySummaryFixtureEntry {
            request: req.clone(),
            response: resp.clone(),
        }])
        .expect("build replay backend");
        assert_eq!(backend.fixture_count(), 1);

        let got = backend.summarize(&req).expect("hit");
        assert_eq!(got.claim, resp.claim);
        assert_eq!(got.model_name_echoed, resp.model_name_echoed);
    }

    #[test]
    fn replay_backend_miss_returns_backend_not_configured() {
        let req = sample_request("m1", "blake3:aaaa", &["alpha"]);
        let resp = sample_response("summary", "m1");
        let backend = ReplaySummaryBackend::from_entries(vec![ReplaySummaryFixtureEntry {
            request: req.clone(),
            response: resp,
        }])
        .expect("build replay backend");

        let other = sample_request("m1", "blake3:aaaa", &["never seen"]);
        let err = backend.summarize(&other).unwrap_err();
        assert_eq!(err, SummaryError::BackendNotConfigured);
    }

    #[test]
    fn replay_backend_refuses_duplicate_fixture_keys() {
        let req = sample_request("m1", "blake3:aaaa", &["alpha"]);
        let resp = sample_response("s1", "m1");
        let err = ReplaySummaryBackend::from_entries(vec![
            ReplaySummaryFixtureEntry {
                request: req.clone(),
                response: resp.clone(),
            },
            ReplaySummaryFixtureEntry {
                request: req,
                response: resp,
            },
        ])
        .unwrap_err();
        match err {
            SummaryError::CallFailed(msg) => {
                assert!(msg.contains("duplicate"), "got {msg}");
            }
            other => panic!("expected CallFailed, got {other:?}"),
        }
    }

    #[test]
    fn replay_backend_loads_from_disk_fixture_file() {
        let tmp = TempDir::new().unwrap();
        let path = tmp.path().join("fixture.json");

        let fixture = ReplaySummaryFixture {
            entries: vec![ReplaySummaryFixtureEntry {
                request: sample_request("m1", "blake3:abcd", &["alpha", "beta"]),
                response: sample_response("summary text", "m1"),
            }],
        };
        let mut f = fs::File::create(&path).unwrap();
        f.write_all(&serde_json::to_vec_pretty(&fixture).unwrap())
            .unwrap();
        drop(f);

        let backend = ReplaySummaryBackend::from_fixture_file(&path).expect("load fixture");
        assert_eq!(backend.fixture_count(), 1);
        let got = backend
            .summarize(&sample_request("m1", "blake3:abcd", &["alpha", "beta"]))
            .expect("hit");
        assert_eq!(got.claim, "summary text");
    }

    #[test]
    fn replay_backend_load_missing_file_returns_call_failed() {
        let err = ReplaySummaryBackend::from_fixture_file(Path::new("this/does/not/exist.json"))
            .unwrap_err();
        match err {
            SummaryError::CallFailed(msg) => {
                assert!(msg.contains("not readable"), "got {msg}");
            }
            other => panic!("expected CallFailed, got {other:?}"),
        }
    }

    #[test]
    fn summary_error_display_carries_discriminator_tokens() {
        assert!(SummaryError::BackendNotConfigured
            .to_string()
            .contains("summary_backend_not_configured"));
        assert!(SummaryError::ModelNotInAllowlist("m".into())
            .to_string()
            .contains("summary_model_not_in_allowlist"));
        assert!(SummaryError::PromptTemplateMismatch("p".into())
            .to_string()
            .contains("summary_prompt_template_mismatch"));
        assert!(SummaryError::CallFailed("c".into())
            .to_string()
            .contains("summary_call_failed"));
        assert!(SummaryError::OutputValidationFailed("o".into())
            .to_string()
            .contains("summary_output_validation_failed"));
    }
}