lean_ctx/core/

ccr.rs

// SPDX-License-Identifier: Apache-2.0
//! Content-addressed recovery (CCR) for the proxy's lossy rewrites (#482).
//!
//! When the proxy prunes an old `tool_result` from conversation history, the
//! lossy stub used to say *"re-read the file"* — which is stale-unsafe by
//! construction: in an agent session files are edited or deleted between turns,
//! so a re-read returns the *current* bytes (or fails), not the historical
//! version the conversation actually showed. The model could then silently
//! reason about the wrong content.
//!
//! CCR fixes this by persisting the **verbatim original** to the shared,
//! content-addressed tee store (`{state}/tee/`, reused from the shell path) and
//! embedding a **retrieval handle** — the absolute path of that file — in the
//! stub. These legacy copies have no source authority and are only available
//! without an active policy. Protected file recovery uses source-bound archives.
//!
//! ## Cache-safety (#448)
//! The handle is the file path, and the path is a pure function of the content
//! hash ([`crate::core::hasher::hash_short`]). For a fixed pruned message the
//! handle is therefore byte-identical on every later turn, so the provider
//! prompt-cache prefix is preserved for available copies. Failed or unauthorized
//! persistence returns no handle; a deterministic path is not proof of recovery.
//!
//! The proxy splices in-band markers back into requests (`proxy::ccr`); the
//! store, its resolver and its bounded read live here, below every caller.

use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};

/// Opening delimiter of an in-band retrieval marker: `<lc_expand:HASH>` (#493).
pub const EXPAND_OPEN: &str = "<lc_expand:";
/// Closing delimiter of an in-band retrieval marker.
pub const EXPAND_CLOSE: char = '>';

/// Originals smaller than this are not worth a tee file + handle; the caller
/// keeps its plain stub. Matches the spirit of the prune length thresholds.
pub const MIN_TEE_BYTES: usize = 512;

/// Throttle the O(dir) TTL cleanup so the prune hot path does at most one
/// directory scan per this interval.
const CLEANUP_INTERVAL_SECS: u64 = 600;

/// Length of the content hash in a proxy/json tee name ([`hash_short`]).
const TEE_HASH_LEN: usize = 16;
/// Length of the command hash in a shell tee name (`shell::redact::save_tee`).
const SHELL_TEE_HASH_LEN: usize = 8;

/// Deterministic tee path for `content`:
/// `{state}/tee/{prefix}_{blake3(content)[..16]}.log`. Pure (no I/O) so a stub
/// embedding it stays byte-stable regardless of filesystem state. `prefix`
/// segregates the producer (`proxy` for history-prune / live-compression stubs,
/// `conv` for conversation history messages, `json` for the JSON crusher's
/// lossy originals, #936) yet keeps one shared
/// store + one resolver ([`resolve_tee`]).
fn tee_path(content: &str, prefix: &str) -> Option<PathBuf> {
    let dir = crate::core::paths::state_dir().ok()?.join("tee");
    let hash = crate::core::hasher::hash_short(content);
    Some(dir.join(format!("{prefix}_{hash}.log")))
}

/// Run the shared 24h TTL cleanup at most once per [`CLEANUP_INTERVAL_SECS`].
fn maybe_cleanup(tee_dir: &Path) {
    static LAST: AtomicU64 = AtomicU64::new(0);
    let Ok(now) = SystemTime::now().duration_since(UNIX_EPOCH) else {
        return;
    };
    let now = now.as_secs();
    let last = LAST.load(Ordering::Relaxed);
    if now.saturating_sub(last) < CLEANUP_INTERVAL_SECS {
        return;
    }
    // Only one thread wins the slot; the rest skip until the next interval.
    if LAST
        .compare_exchange(last, now, Ordering::Relaxed, Ordering::Relaxed)
        .is_ok()
    {
        crate::shell::cleanup_old_tee_logs(tee_dir);
    }
}

/// Persist `content` verbatim (best-effort, secret-redacted) to the
/// content-addressed tee store and return its retrieval handle (the absolute
/// path). Returns `None` for protected originless data, invalid/oversized input
/// or persistence failure. Re-persisting identical content keeps the same path;
/// callers must preserve useful fresh output when no recovery handle is available.
pub fn persist(content: &str) -> Option<String> {
    persist_with(content, "proxy")
}

/// Like [`persist`], but a content-addressed copy that is already on disk is
/// named as it is: no rewrite, no new relevance registration. A copy the TTL
/// cleanup removed is written again (self-healing). Under protection nothing
/// originless is named, existing or not.
pub fn persist_once(content: &str) -> Option<String> {
    if content.len() < MIN_TEE_BYTES
        || crate::core::context_admission::stored::source_authority_required()
    {
        return None;
    }
    let path = tee_path(content, "proxy")?;
    if std::fs::symlink_metadata(&path).is_ok_and(|meta| meta.file_type().is_file()) {
        return Some(path.to_string_lossy().to_string());
    }
    persist(content)
}

/// Persist a dropped conversation message under a compact `conv_` handle.
///
/// Conversation messages may be short, so unlike tool-output tees this path has
/// no minimum-size gate. The returned basename is sufficient for `ctx_expand` and
/// avoids putting machine-specific absolute paths into provider prompts.
#[cfg_attr(not(test), allow(dead_code))] // conversation tee handle for ctx_expand recovery
pub fn persist_conversation(content: &str) -> Option<String> {
    let path = persist_with_min(content, "conv", 1)?;
    Path::new(&path)
        .file_name()
        .and_then(|name| name.to_str())
        .map(str::to_owned)
}

/// Persist a JSON crusher's verbatim original (#936) under the `json_` prefix and
/// return its `{state}/tee/json_{hash}.log` handle. Used by the lossy crush stage
/// so a dropped column is always recoverable out-of-band via [`resolve_tee`] /
/// `ctx_expand`, never reconstructed from the (lossy) text. Shares the
/// content-address and best-effort write contract of [`persist`], so the embedded
/// handle stays deterministic (cache-safe).
pub fn persist_json(content: &str) -> Option<String> {
    persist_with(content, "json")
}

/// Persist a tabular (CSV/TSV) crusher's verbatim original (#982) under the
/// `tbl_` prefix and return its `{state}/tee/tbl_{hash}.log` handle. Used by the
/// lossy column-drop stage so a dropped column is always recoverable out-of-band
/// via [`resolve_tee`] / `ctx_expand`, never reconstructed from the (lossy) text.
/// Shares the content-address and best-effort write contract of [`persist`].
pub fn persist_tabular(content: &str) -> Option<String> {
    persist_with(content, "tbl")
}

/// Persist a YAML crusher's verbatim original (#985) under the `yaml_` prefix and
/// return its `{state}/tee/yaml_{hash}.log` handle. Used by the lossy column-drop
/// stage so a dropped column is always recoverable out-of-band via [`resolve_tee`]
/// / `ctx_expand`, never reconstructed from the (lossy) text. Shares the
/// content-address and best-effort write contract of [`persist`].
pub fn persist_yaml(content: &str) -> Option<String> {
    persist_with(content, "yaml")
}

/// Persist an HTML page's verbatim original (#1124) under the `html_` prefix
/// and return its `{state}/tee/html_{hash}.log` handle. The extracted markdown
/// is the compressed form; the full HTML is recoverable via [`resolve_tee`] /
/// `ctx_expand`. Shares the content-address and best-effort write contract of
/// [`persist`].
pub fn persist_html(content: &str) -> Option<String> {
    persist_with(content, "html")
}

/// Persist the full definition of a tool whose description the proxy shortened
/// (K26) under the `tool_` prefix. Returns the basename, like
/// [`persist_conversation`]: it resolves through `ctx_expand` and keeps a
/// machine-specific path out of the provider prompt, so the shortened tool
/// list is the same bytes on every machine and turn.
#[cfg(feature = "http-server")]
pub fn persist_tool_definition(content: &str) -> Option<String> {
    let path = persist_with_min(content, "tool", 1)?;
    Path::new(&path)
        .file_name()
        .and_then(|name| name.to_str())
        .map(str::to_owned)
}

fn persist_with(content: &str, prefix: &str) -> Option<String> {
    persist_with_min(content, prefix, MIN_TEE_BYTES)
}

fn persist_with_min(content: &str, prefix: &str, min_bytes: usize) -> Option<String> {
    debug_assert!(
        TEE_PREFIXES.contains(&prefix),
        "tee prefix {prefix} must be resolvable (add it to TEE_PREFIXES)"
    );
    if content.len() < min_bytes {
        return None;
    }
    let path = tee_path(content, prefix)?;
    let handle = path.to_string_lossy().to_string();
    storage::write(&path, content)?;
    if let Some(dir) = path.parent() {
        maybe_cleanup(dir);
    }
    if path.is_file() {
        let source_tool = match prefix {
            "json" | "tbl" | "yaml" => "ctx_read",
            "html" => "ctx_shell",
            _ => "proxy",
        };
        crate::core::relevance_tracker::register_compressed(
            handle.clone(),
            content,
            source_tool,
            crate::core::tokens::count_tokens(content),
            0,
        );
    }
    Some(handle)
}

fn is_hex(s: &str, len: usize) -> bool {
    s.len() == len && s.bytes().all(|b| b.is_ascii_hexdigit())
}

/// Every prefix [`persist_with_min`] writes. The resolver is driven by the same
/// table, so a new producer can never mint a handle `ctx_expand` rejects
/// (#1911: `html_` was persisted but unresolvable).
const TEE_PREFIXES: &[&str] = &["proxy", "conv", "json", "tbl", "yaml", "html", "tool"];

/// Canonical `{prefix}_{16hex}.log` name for a prefixed ([`TEE_PREFIXES`]) or
/// bare-hash id, or `None`. A bare 16-hex id defaults to the `proxy_` store
/// (back-compat: that is the only form pre-#936 stubs carry).
fn canonical_tee_name(name: &str) -> Option<String> {
    let stem = name.strip_suffix(".log").unwrap_or(name);
    for prefix in TEE_PREFIXES {
        if let Some(hash) = stem
            .strip_prefix(prefix)
            .and_then(|rest| rest.strip_prefix('_'))
        {
            return is_hex(hash, TEE_HASH_LEN).then(|| format!("{prefix}_{hash}.log"));
        }
    }
    is_hex(stem, TEE_HASH_LEN).then(|| format!("proxy_{stem}.log"))
}

/// True for a shell tee basename `<slug>_<8hex>.log` (`shell::redact::save_tee`):
/// ends in `.log`, the whole basename is safe (`[A-Za-z0-9_-]`), and the **last**
/// `_`-segment is exactly 8 hex. The slug itself may contain `_`, so the hash is
/// matched as the suffix — never the first segment (the documented parsing trap).
fn is_shell_tee_name(name: &str) -> bool {
    let Some(stem) = name.strip_suffix(".log") else {
        return false;
    };
    if !stem
        .bytes()
        .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
    {
        return false;
    }
    match stem.rsplit_once('_') {
        Some((slug, hash)) => !slug.is_empty() && is_hex(hash, SHELL_TEE_HASH_LEN),
        None => false,
    }
}

/// Why a canonical tee handle could not be resolved.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TeeResolveError {
    Malformed,
    Missing,
    Refused(&'static str),
}

/// Resolve a retrieval ID through the same canonical store path used by
/// `ctx_expand`, while distinguishing malformed IDs and policy refusals.
pub fn resolve_tee_checked(id: &str) -> Result<PathBuf, TeeResolveError> {
    let name = Path::new(id)
        .file_name()
        .and_then(|n| n.to_str())
        .unwrap_or(id);
    let canon = canonical_tee_name(name)
        .or_else(|| is_shell_tee_name(name).then(|| name.to_string()))
        .ok_or(TeeResolveError::Malformed)?;
    let state_dir = crate::core::paths::state_dir().map_err(|_| TeeResolveError::Missing)?;
    let tee_dir = state_dir.join("tee");
    let path = tee_dir.join(canon);
    // The tee store itself must be a real directory: a `tee` link to another
    // store (archives, references) would let a tee-shaped name read that store.
    if std::fs::symlink_metadata(&tee_dir).is_ok_and(|m| m.file_type().is_symlink()) {
        return Err(TeeResolveError::Refused(
            "tee store is a symlink to another location",
        ));
    }

    let link_metadata = std::fs::symlink_metadata(&path).map_err(|error| {
        if error.kind() == std::io::ErrorKind::PermissionDenied {
            TeeResolveError::Refused("tee metadata read refused by filesystem policy")
        } else {
            TeeResolveError::Missing
        }
    })?;
    if link_metadata.file_type().is_symlink() {
        return Err(TeeResolveError::Refused(
            "tee handles cannot resolve through symlinks",
        ));
    }
    if !link_metadata.is_file() {
        return Err(TeeResolveError::Missing);
    }

    let canonical_state = std::fs::canonicalize(&state_dir).map_err(|error| {
        if error.kind() == std::io::ErrorKind::PermissionDenied {
            TeeResolveError::Refused("tee store access refused by filesystem policy")
        } else {
            TeeResolveError::Missing
        }
    })?;
    let canonical_tee = std::fs::canonicalize(&tee_dir).map_err(|error| {
        if error.kind() == std::io::ErrorKind::PermissionDenied {
            TeeResolveError::Refused("tee store access refused by filesystem policy")
        } else {
            TeeResolveError::Missing
        }
    })?;
    if canonical_tee != canonical_state.join("tee") {
        return Err(TeeResolveError::Refused(
            "tee store resolves outside the state directory",
        ));
    }

    let canonical_file = std::fs::canonicalize(&path).map_err(|error| {
        if error.kind() == std::io::ErrorKind::PermissionDenied {
            TeeResolveError::Refused("tee read refused by filesystem policy")
        } else {
            TeeResolveError::Missing
        }
    })?;
    if !canonical_file.starts_with(&canonical_tee) {
        return Err(TeeResolveError::Refused(
            "tee handle resolves outside the tee store",
        ));
    }
    if !canonical_file.is_file() {
        return Err(TeeResolveError::Missing);
    }
    Ok(path)
}

/// Back-compatible resolver used by `ctx_expand`.
pub fn resolve_tee(id: &str) -> Option<PathBuf> {
    resolve_tee_checked(id).ok()
}

/// The in-band retrieval marker `<lc_expand:HASH>` for a CCR `handle` (#493).
///
/// `HASH` is the content hash already embedded in the tee handle, so a model can
/// echo the marker verbatim and the proxy can recover the original via
/// [`resolve_tee`] on the next turn. Pure (no I/O, no config) so it is trivially
/// testable; returns `None` for a handle that is not a canonical tee path.
pub fn inband_marker(handle: &str) -> Option<String> {
    let name = Path::new(handle).file_name().and_then(|n| n.to_str())?;
    let hash = name.strip_prefix("proxy_")?.strip_suffix(".log")?;
    (hash.len() == 16 && hash.bytes().all(|b| b.is_ascii_hexdigit()))
        .then(|| format!("{EXPAND_OPEN}{hash}{EXPAND_CLOSE}"))
}

/// The in-band marker for `handle` **only when in-band CCR is enabled** (#493),
/// else `None`. Stub sites use this to advertise an echo-able `<lc_expand:HASH>`
/// solely in in-band mode: a normal (shared-filesystem) deployment keeps its
/// path handle, so the model never sees a marker the proxy would not splice.
///
/// Reads the (process-cached) config; the surrounding stub path already does
/// per-message tee I/O via [`persist`], so this adds no new I/O class.
pub fn inband_locator(handle: &str) -> Option<String> {
    crate::core::config::Config::load()
        .proxy
        .ccr_inband_enabled()
        .then(|| inband_marker(handle))
        .flatten()
}

/// Read a tee file that [`resolve_tee`] returned. One read path for every
/// caller: bounded, no-follow and bound to the checked file, re-checked
/// against the current policy and re-admitted by the context gateway.
pub fn read_tee_file(path: &Path) -> Option<String> {
    read_checked_tee(path)
}

/// Resolve and read a tee handle in one step.
pub fn read_tee(id: &str) -> Option<String> {
    read_tee_file(&resolve_tee(id)?)
}

pub use storage::{
    read as read_checked_tee, read_detailed as read_tee_detailed, write as write_tee,
};

mod storage;

/// Length of a LiteLLM gateway retrieval hash (#702): LiteLLM's headroom
/// guardrail scans compressed text with `hash=([a-f0-9]{24})`
/// (BerriAI/litellm#31681), so the marker must carry exactly 24 lowercase hex.
pub const LITELLM_HASH_LEN: usize = 24;

/// The 24-hex gateway retrieval hash for `content` (#702): the first 24 chars
/// of the full blake3 hex. A strict extension of the 16-hex tee name
/// ([`crate::core::hasher::hash_short`] is the same digest truncated to 16),
/// so `hash[..16]` resolves the tee file while the extra 8 chars keep the
/// marker collision-resistant on the gateway side. Pure — the marker embedding
/// it stays byte-stable per content (#498).
pub fn litellm_hash(content: &str) -> String {
    blake3::hash(content.as_bytes()).to_hex()[..LITELLM_HASH_LEN].to_string()
}

/// Resolve a LiteLLM `hash=<24hex>` retrieval id (#702) back to the verbatim
/// original in the tee store, for `GET /v1/retrieve/{hash}`. Shape-locked to
/// LiteLLM's own regex (24 lowercase hex — uppercase or any other length is
/// rejected, never coerced) so only a string the guardrail could actually have
/// captured resolves; the first 16 chars are the `proxy_` tee content-address.
#[cfg(feature = "http-server")]
pub fn retrieve_litellm(hash: &str) -> Option<String> {
    if hash.len() != LITELLM_HASH_LEN
        || !hash
            .bytes()
            .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
    {
        return None;
    }
    read_tee(&hash[..TEE_HASH_LEN])
}

#[cfg(any(test, feature = "test-support"))]
/// Inputs shared by the CCR tests here and in the proxy.
pub mod test_support {
    /// `seed` repeated past the tee threshold.
    pub fn big(seed: &str) -> String {
        format!("{seed}\n").repeat(40)
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;

    pub(crate) use super::test_support::big;

    fn write_gateway_mode(mode: &str) {
        let config = crate::core::paths::config_dir_read_only().expect("config directory");
        std::fs::create_dir_all(&config).expect("config directory");
        std::fs::write(
            config.join("config.toml"),
            format!("[context_gateway]\nmode = \"{mode}\"\n"),
        )
        .expect("gateway config");
    }

    /// A stored tee log has no source authority. Governed mode protects
    /// without any policy pack: the log written in developer mode is then
    /// neither handed back nor is a new one written, and the refusal says
    /// nothing about the content. Developer mode keeps its recovery.
    #[test]
    fn governed_mode_without_a_pack_neither_serves_nor_writes_an_originless_tee() {
        let _data = crate::core::data_dir::isolated_data_dir();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        write_gateway_mode("developer");
        let content = big("deploy log line with the marker tee-governed-regression");
        let handle = persist(&content).expect("developer mode keeps a recovery copy");
        let path = Path::new(&handle);
        assert!(
            read_tee_detailed(path)
                .expect("developer mode serves it")
                .contains("tee-governed-regression")
        );

        write_gateway_mode("governed");
        let refusal = read_tee_detailed(path).expect_err("governed mode must not serve it");
        assert!(refusal.contains("no source authority"), "{refusal}");
        assert!(!refusal.contains("tee-governed-regression"));
        assert!(read_tee(&handle).is_none());
        assert!(
            persist(&big("another originless log line")).is_none(),
            "governed mode writes no originless copy"
        );

        write_gateway_mode("developer");
        assert!(read_tee_detailed(path).is_ok(), "developer mode unchanged");
    }

    #[test]
    fn handle_is_content_addressed_and_deterministic() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("file body line");
        let a = persist(&content).expect("persisted");
        let b = persist(&content).expect("persisted again");
        assert_eq!(
            a, b,
            "same content must map to the same handle (cache-safe)"
        );
        assert!(a.contains("proxy_"), "handle is a proxy tee path: {a}");

        let other = persist(&big("different body")).expect("persisted");
        assert_ne!(a, other, "different content must get a different handle");
    }

    #[test]
    fn persisted_original_is_recoverable() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("recoverable verbatim line");
        let handle = persist(&content).expect("persisted");
        let on_disk = std::fs::read_to_string(&handle).expect("tee file readable");
        assert!(
            on_disk.contains("recoverable verbatim line"),
            "the verbatim original must be retrievable from the handle"
        );
    }

    #[test]
    fn small_content_gets_no_handle() {
        let _lock = crate::core::data_dir::test_env_lock();
        assert!(
            persist("too small to bother").is_none(),
            "below MIN_TEE_BYTES there is no handle (the caller keeps its plain stub)"
        );
    }

    #[test]
    #[allow(clippy::case_sensitive_file_extension_comparisons)]
    fn conversation_handle_is_compact_and_deterministic() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let a = persist_conversation("{\"role\":\"user\",\"content\":\"hello\"}")
            .expect("conversation handle");
        let b = persist_conversation("{\"role\":\"user\",\"content\":\"hello\"}")
            .expect("conversation handle");
        assert_eq!(a, b);
        assert!(a.starts_with("conv_") && a.ends_with(".log"));
    }

    #[test]
    fn conversation_handle_resolves_short_messages() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let handle = persist_conversation("short conversation message").expect("handle");
        assert!(resolve_tee(&handle).is_some());
    }

    #[test]
    fn conversation_original_is_recoverable() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let original = "{\"role\":\"tool\",\"content\":\"recover me\"}";
        let handle = persist_conversation(original).expect("handle");
        let path = resolve_tee(&handle).expect("resolved handle");
        assert_eq!(std::fs::read_to_string(path).unwrap(), original);
    }

    #[test]
    fn resolve_tee_accepts_every_stub_form() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("resolvable tee body");
        let handle = persist(&content).expect("persisted");
        let hash = crate::core::hasher::hash_short(&content);

        // Full path, bare file name, proxy_<hash>, and bare <hash> all resolve to
        // the same on-disk file — whatever the agent copied out of the stub.
        for form in [
            handle.clone(),
            format!("proxy_{hash}.log"),
            format!("proxy_{hash}"),
            hash.clone(),
        ] {
            let resolved = resolve_tee(&form).unwrap_or_else(|| panic!("must resolve {form}"));
            assert_eq!(
                resolved.to_string_lossy(),
                handle,
                "form {form} -> {handle}"
            );
        }
    }

    /// #1911: the HTML crush's `html_` handle must round-trip through the
    /// resolver `ctx_expand` uses, in every form the footer can be copied in.
    #[test]
    fn persist_html_handle_resolves_in_every_form() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("<p>html crush original</p>");
        let handle = persist_html(&content).expect("html persisted");
        let hash = crate::core::hasher::hash_short(&content);
        for form in [
            handle.clone(),
            format!("html_{hash}.log"),
            format!("html_{hash}"),
        ] {
            let resolved = resolve_tee(&form).unwrap_or_else(|| panic!("must resolve {form}"));
            assert_eq!(resolved.to_string_lossy(), handle, "form {form}");
        }
        assert!(
            std::fs::read_to_string(&handle)
                .unwrap()
                .contains("html crush original")
        );
    }

    /// Every prefix a producer can write is accepted by the resolver, and a
    /// prefix without its `_` separator is not.
    #[test]
    fn canonical_tee_name_covers_every_producer_prefix() {
        let hash = "0123456789abcdef";
        for prefix in TEE_PREFIXES {
            assert_eq!(
                canonical_tee_name(&format!("{prefix}_{hash}.log")),
                Some(format!("{prefix}_{hash}.log"))
            );
        }
        assert_eq!(canonical_tee_name(&format!("html{hash}")), None);
        assert_eq!(canonical_tee_name("html_nothex000000000"), None);
    }

    #[test]
    fn resolve_tee_rejects_nontee_and_traversal_ids() {
        let _lock = crate::core::data_dir::test_env_lock();
        // No FS escape: a crafted path is reduced to its file name, which is not a
        // valid proxy tee name, so it resolves to None instead of reading it.
        assert!(resolve_tee("/etc/passwd").is_none());
        assert!(resolve_tee("../../secret").is_none());
        assert!(resolve_tee("proxy_nothex0000000.log").is_none());
        // Right shape but no such file in the store.
        assert!(resolve_tee("deadbeefdeadbeef").is_none());
    }

    #[test]
    fn persist_json_is_distinct_prefix_and_resolvable() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("json crusher original");
        let proxy = persist(&content).expect("proxy persisted");
        let json = persist_json(&content).expect("json persisted");
        assert!(
            json.contains("json_"),
            "json handle uses json_ prefix: {json}"
        );
        assert_ne!(
            proxy, json,
            "same content gets distinct files per producer prefix"
        );

        // The json_ handle resolves through the unified resolver in every form a
        // stub / footer can carry: full path, bare file name, and bare json_id.
        let hash = crate::core::hasher::hash_short(&content);
        for form in [
            json.clone(),
            format!("json_{hash}.log"),
            format!("json_{hash}"),
        ] {
            assert_eq!(
                resolve_tee(&form)
                    .expect("json form resolves")
                    .to_string_lossy(),
                json,
                "json form {form} -> {json}"
            );
        }
    }

    #[test]
    fn persist_tabular_is_distinct_prefix_and_resolvable() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("tabular crusher original");
        let json = persist_json(&content).expect("json persisted");
        let tbl = persist_tabular(&content).expect("tbl persisted");
        assert!(
            tbl.contains("tbl_"),
            "tabular handle uses tbl_ prefix: {tbl}"
        );
        assert_ne!(
            json, tbl,
            "same content gets distinct files per producer prefix"
        );

        let hash = crate::core::hasher::hash_short(&content);
        for form in [
            tbl.clone(),
            format!("tbl_{hash}.log"),
            format!("tbl_{hash}"),
        ] {
            assert_eq!(
                resolve_tee(&form)
                    .expect("tbl form resolves")
                    .to_string_lossy(),
                tbl,
                "tbl form {form} -> {tbl}"
            );
        }
    }

    #[test]
    fn persist_yaml_is_distinct_prefix_and_resolvable() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("yaml crusher original");
        let tbl = persist_tabular(&content).expect("tbl persisted");
        let yaml = persist_yaml(&content).expect("yaml persisted");
        assert!(
            yaml.contains("yaml_"),
            "yaml handle uses yaml_ prefix: {yaml}"
        );
        assert_ne!(
            tbl, yaml,
            "same content gets distinct files per producer prefix"
        );

        let hash = crate::core::hasher::hash_short(&content);
        for form in [
            yaml.clone(),
            format!("yaml_{hash}.log"),
            format!("yaml_{hash}"),
        ] {
            assert_eq!(
                resolve_tee(&form)
                    .expect("yaml form resolves")
                    .to_string_lossy(),
                yaml,
                "yaml form {form} -> {yaml}"
            );
        }
    }

    #[test]
    fn resolve_tee_resolves_shell_tee_with_underscored_slug() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        // A real shell command whose slug contains underscores: the hash is the
        // last `_`-segment (8 hex), never the first — the parsing trap. The full
        // verbatim output the shell already teed is now surgically retrievable.
        let path = crate::shell::save_tee("gh api /repos/foo/bar", &big("api row"))
            .expect("shell tee saved");
        let name = std::path::Path::new(&path)
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap()
            .to_string();
        assert!(
            is_shell_tee_name(&name),
            "save_tee name must be recognized as a shell tee: {name}"
        );
        for form in [path.clone(), name] {
            assert_eq!(
                resolve_tee(&form)
                    .expect("shell tee form resolves")
                    .to_string_lossy(),
                path,
                "shell tee form -> {path}"
            );
        }
    }

    #[test]
    fn resolve_tee_does_not_capture_reference_ids() {
        let _lock = crate::core::data_dir::test_env_lock();
        // A reference-store id (`ref_<16hex>`, no `.log`) must fall through the
        // tee resolver so ctx_expand routes it to the reference store, not the
        // tee store — the precedence guard for the unified retrieve ladder.
        assert!(resolve_tee("ref_deadbeefcafef00d").is_none());
        // A bare 16-hex archive id with no backing tee file also stays None.
        assert!(resolve_tee("0123456789abcdef").is_none());
    }

    #[test]
    fn litellm_hash_is_24_lowercase_hex_and_extends_tee_hash() {
        let content = big("gateway retrieval body");
        let hash = litellm_hash(&content);
        assert_eq!(hash.len(), LITELLM_HASH_LEN);
        assert!(
            hash.bytes()
                .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)),
            "must match LiteLLM's [a-f0-9]{{24}} class: {hash}"
        );
        // Same blake3 digest as the tee name, longer prefix: the first 16 chars
        // ARE the tee content-address, which is what makes retrieval work.
        assert_eq!(hash[..16], crate::core::hasher::hash_short(&content));
        // Pure function of content (#498): stable across calls.
        assert_eq!(hash, litellm_hash(&content));
    }

    #[cfg(feature = "http-server")]
    #[test]
    fn retrieve_litellm_resolves_persisted_content() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("litellm retrievable original");
        persist(&content).expect("persisted");
        let recovered =
            retrieve_litellm(&litellm_hash(&content)).expect("24-hex hash must resolve");
        assert!(recovered.contains("litellm retrievable original"));
    }

    #[cfg(feature = "http-server")]
    #[test]
    fn retrieve_litellm_is_shape_locked_to_the_guardrail_regex() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("shape locked body");
        persist(&content).expect("persisted");
        let hash = litellm_hash(&content);

        // 16-hex (our tee id), truncated, extended, uppercased, non-hex: all
        // rejected — only the exact shape LiteLLM's regex captures resolves.
        assert!(retrieve_litellm(&hash[..16]).is_none(), "16-hex rejected");
        assert!(retrieve_litellm(&hash[..23]).is_none(), "23-hex rejected");
        assert!(
            retrieve_litellm(&format!("{hash}0")).is_none(),
            "25-hex rejected"
        );
        assert!(
            retrieve_litellm(&hash.to_uppercase()).is_none(),
            "uppercase rejected (regex class is [a-f0-9])"
        );
        assert!(
            retrieve_litellm("zzzzzzzzzzzzzzzzzzzzzzzz").is_none(),
            "non-hex rejected"
        );
        // Traversal attempts die in resolve_tee's name canonicalization.
        assert!(retrieve_litellm("../../etc/passwd00000000").is_none());
        // Right shape, unknown content.
        assert!(retrieve_litellm("0123456789abcdef01234567").is_none());
    }

    #[test]
    fn inband_marker_is_derived_from_handle() {
        let _lock = crate::core::data_dir::test_env_lock();
        let _community = crate::core::policy::runtime::TestPolicyOverride::set(None);
        let content = big("inband marker body");
        let handle = persist(&content).expect("persisted");
        let hash = crate::core::hasher::hash_short(&content);
        // The marker carries the same content hash the handle does, so a model can
        // echo it and the proxy resolves it back to the very same tee file.
        assert_eq!(inband_marker(&handle), Some(format!("<lc_expand:{hash}>")));
        // A non-tee handle has no marker.
        assert!(inband_marker("/tmp/not-a-tee.txt").is_none());
    }
}