kimetsu_brain/

digest.rs

//! Flagship 1 / Pass B / Story 1.1 + 1.2: repo digest builder.
//!
//! Builds a compact ~400-token digest of the current repo state:
//!   - top-usefulness memories (conventions/facts that matter most)
//!   - repo manifest summary (Cargo.toml, package.json, …)
//! Task focus is delivered separately through identity-scoped resume.
//!
//! The digest is cached in `.kimetsu/digest.md`, keyed by a non-cryptographic
//! CONTENT HASH of current inputs. Warm delivery validates the inputs
//! synchronously so corrected or expired claims cannot survive in cached text.
//!
//! ## Cheap-model vs rule-based
//!
//! When `config.cheap_model()` returns `Some(cm)` the digest is distilled
//! by an LLM call (not yet wired — requires async HTTP client that is
//! already present in the distiller).  When `None`, a rule-based assembler
//! concatenates the raw inputs directly.  The rule-based path is the only
//! path exercised in tests and in the current implementation (the
//! expensive LLM path is guarded and degrades gracefully).
//!
//! ## ROI attribution
//!
//! After the SessionStart hook emits context, it writes `digest_served` /
//! `resume_served` attribution events to the brain via
//! [`record_warmstart_served`].

use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::path::Path;

use kimetsu_core::KimetsuResult;
use rusqlite::Connection;
use serde::{Deserialize, Serialize};

use crate::project::{load_project, load_project_readonly};

// ── Target size ──────────────────────────────────────────────────────────────

/// Approx character budget for the assembled digest (≈400 tokens × 4 chars).
const DIGEST_CHAR_BUDGET: usize = 1_600;
/// Number of top-useful memories to include in the digest.
const TOP_MEMORY_COUNT: usize = 5;
/// Max chars per memory text included in digest.
const MEMORY_SNIPPET_CHARS: usize = 180;

// ── Cache metadata ────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DigestMeta {
    /// Non-cryptographic content hash of the inputs (DefaultHasher).
    pub input_hash: u64,
    /// ISO-8601 timestamp when this digest was built.
    pub built_at: String,
}

// ── Public surface ────────────────────────────────────────────────────────────

/// Build (or load from cache) a compact repo digest for `workspace`.
///
/// Returns `None` when:
/// - the brain is not initialized at `workspace`
/// - the workspace has no useful content yet (no memories, no manifests)
///
/// The returned string is already budget-capped and ready for injection.
///
/// `force_rebuild` bypasses the cache.
pub fn build_or_load_digest(workspace: &Path, force_rebuild: bool) -> Option<String> {
    build_or_load_digest_inner(workspace, force_rebuild).unwrap_or(None)
}

fn build_or_load_digest_inner(
    workspace: &Path,
    force_rebuild: bool,
) -> KimetsuResult<Option<String>> {
    let (paths, config, conn) = load_project_readonly(workspace)?;
    let repo_root_str = paths.repo_root.to_string_lossy().to_string();

    // 1. Assemble raw inputs.
    let inputs = gather_inputs(&conn, &repo_root_str)?;
    if inputs.is_empty() {
        return Ok(None);
    }

    // 2. Compute content hash.
    let hash = content_hash(&inputs);

    // 3. Cache paths.
    let cache_path = paths.kimetsu_dir.join("digest.md");
    let meta_path = paths.kimetsu_dir.join("digest-meta.json");

    // The rule-based assembly is cheap and binds delivery to this exact input
    // snapshot. Separate diagnostic cache publishers can mix text/metadata
    // generations, so an input-hash match alone cannot authorize cached text.
    let digest_text = assemble_rule_based(&inputs, &config)?;
    if digest_text.trim().is_empty() {
        return Ok(None);
    }

    // 4. Reuse the disk cache only as a reason to skip an unchanged write.
    if !force_rebuild {
        if let Some(cached) = try_load_cache(&cache_path, &meta_path, hash) {
            if cached == digest_text {
                return Ok(Some(digest_text));
            }
        }
    }

    // 6. Write cache atomically.
    let meta = DigestMeta {
        input_hash: hash,
        built_at: now_utc_rfc3339(),
    };
    atomic_write_text(&cache_path, &digest_text);
    atomic_write_json_meta(&meta_path, &meta);

    Ok(Some(digest_text))
}

/// Read `.kimetsu/digest.md` verbatim, without checking whether it is
/// still current.
///
/// This diagnostic raw read may return stale text. Model-facing warm delivery
/// uses [`build_or_load_digest`] to validate current inputs before cache reuse.
/// Returns `None` when the brain is not initialized or no cache exists.
pub fn load_cached_digest(workspace: &Path) -> Option<String> {
    let (paths, _config, _conn) = load_project_readonly(workspace).ok()?;
    let text = std::fs::read_to_string(paths.kimetsu_dir.join("digest.md")).ok()?;
    if text.trim().is_empty() {
        None
    } else {
        Some(text)
    }
}

// ── Staleness check (1.2) ─────────────────────────────────────────────────────

/// Returns `true` when the cached digest is stale and should be rebuilt.
///
/// Reads the metadata and current bounded digest inputs to compare their hash.
///
/// Diagnostic helper; warm delivery validates through build_or_load_digest.
pub fn is_stale(workspace: &Path) -> bool {
    is_stale_inner(workspace).unwrap_or(false)
}

fn is_stale_inner(workspace: &Path) -> KimetsuResult<bool> {
    let (paths, _config, conn) = load_project_readonly(workspace)?;
    let repo_root_str = paths.repo_root.to_string_lossy().to_string();

    let meta_path = paths.kimetsu_dir.join("digest-meta.json");
    let cache_path = paths.kimetsu_dir.join("digest.md");

    if !cache_path.exists() || !meta_path.exists() {
        return Ok(true);
    }

    let meta = load_meta(&meta_path)?;
    let inputs = gather_inputs(&conn, &repo_root_str)?;
    let current_hash = content_hash(&inputs);

    Ok(meta.input_hash != current_hash)
}

// ── Warm start ────────────────────────────────────────────────────────────────

/// Assemble the warm-start block: repo digest, standing preferences, and
/// episodic resume.
///
/// This is what every host sees first — the `SessionStart` hook on Claude
/// Code, the first prompt of a session on Codex / Pi / OpenClaw, and the first
/// `kimetsu_brain_context` call on Cursor, which has neither hooks nor a
/// session-start surface.
///
/// Returns `None` when `[broker] warm_start` is off, or when there is no
/// digest, no preferences and no live episode to report.
///
/// Current inputs are checked before cached text is used. Rule-based rebuilds
/// run synchronously when claims change or temporal validity crosses a boundary.
///
/// Records ROI attribution as a side effect, so call it only when the block is
/// actually going to be emitted.
pub fn warm_start_block(workspace: &Path) -> Option<String> {
    warm_start_block_scoped(workspace, "")
}
pub fn warm_start_block_scoped(workspace: &Path, identity: &str) -> Option<String> {
    let block = prepare_warm_start_block_scoped(workspace, identity)?;
    record_warmstart_served(workspace, block.digest_chars, block.resume_chars);
    Some(block.context)
}

/// Prepared text carries no delivery attribution until the caller emits it.
pub struct PreparedWarmStart {
    pub context: String,
    pub digest_chars: usize,
    pub resume_chars: usize,
}

pub fn prepare_warm_start_block_scoped(
    workspace: &Path,
    identity: &str,
) -> Option<PreparedWarmStart> {
    // Gate: load warm_start from config (best-effort; default ON).
    let warm_start_enabled = kimetsu_core::paths::ProjectPaths::discover(workspace)
        .ok()
        .and_then(|paths| crate::project::load_config(&paths).ok())
        .map(|cfg| cfg.broker.warm_start)
        .unwrap_or(true);
    if !warm_start_enabled {
        return None;
    }

    // Validate current claim text, retirement and temporal applicability before
    // using a cached overview. A stale-while-revalidate policy reintroduces
    // facts the retrieval path deliberately rejected.
    let digest = build_or_load_digest(workspace, false);
    let resume = crate::episode::render_resume_context_scoped(workspace, identity);

    // v2.6: the user's standing preferences, delivered rather than retrieved.
    //
    // Preference following is the second-weakest measured ability, and the
    // diagnosis is that "a preference is a small aside semantically far from
    // the question" — which rules out re-ranking, because the candidate never
    // enters the pool. A standing preference belongs in context before the
    // question is asked. See `crate::user_profile`.
    let profile = user_profile_block(workspace);

    // v2.6: what the skills loop is waiting on. Detection has run on a schedule
    // since the maintenance daemon landed, but its result went into a log file
    // nobody opens — so a memory could earn skill status and never become one.
    // See `crate::skill_synthesis::graduation_notice`.
    let skills = skills_block(workspace);

    if digest.is_none() && resume.is_none() && profile.is_none() && skills.is_none() {
        return None;
    }

    let mut parts: Vec<String> = Vec::new();
    if let Some(d) = &digest {
        parts.push(format!("## Repo context\n{d}"));
    }
    if let Some(p) = &profile {
        parts.push(format!("## How you like to work\n{p}"));
    }
    if let Some(r) = &resume {
        parts.push(format!("## Your prior session\n{r}"));
    }
    // Last: it is a nudge about Kimetsu itself, not context about the repo, so
    // it must not sit between the agent and the work.
    if let Some(s) = &skills {
        parts.push(format!("## Skills ready to graduate\n{s}"));
    }

    Some(PreparedWarmStart {
        context: parts.join("\n\n"),
        digest_chars: digest.as_ref().map(|d| d.len()).unwrap_or(0),
        resume_chars: resume.as_ref().map(|r| r.len()).unwrap_or(0),
    })
}

/// Assemble the skills-loop nudge for the warm start.
///
/// Best-effort, like every other block here: an unreadable brain means no
/// nudge, never a failed warm start.
fn skills_block(workspace: &Path) -> Option<String> {
    let (_paths, _config, conn) = load_project_readonly(workspace).ok()?;
    crate::skill_synthesis::graduation_notice(&conn)
}

/// Assemble the standing-preferences block for the warm start.
///
/// Best-effort: an unreadable brain means no preferences block, never a failed
/// warm start.
fn user_profile_block(workspace: &Path) -> Option<String> {
    let (_paths, config, conn) = load_project_readonly(workspace).ok()?;
    // The cross-project user brain is opened separately; when it is disabled or
    // unreachable the project's own preferences stand on their own.
    let user_conn =
        crate::user_brain::open_user_brain_readonly_for_config(config.kimetsu.use_user_brain)
            .ok()
            .flatten();
    let profile = crate::user_profile::build_profile(&conn, user_conn.as_ref()).ok()?;
    crate::user_profile::render_profile(&profile)
}

// ── ROI attribution ───────────────────────────────────────────────────────────

/// Record ROI attribution events for the warm-start injection.
///
/// `digest_chars` is the length of the emitted digest (0 = not emitted).
/// `resume_chars` is the length of the emitted resume (0 = not emitted).
///
/// Best-effort: errors are ignored (ROI must never block SessionStart).
pub fn record_warmstart_served(workspace: &Path, digest_chars: usize, resume_chars: usize) {
    let _ = record_warmstart_served_inner(workspace, digest_chars, resume_chars);
}

fn record_warmstart_served_inner(
    workspace: &Path,
    digest_chars: usize,
    resume_chars: usize,
) -> KimetsuResult<()> {
    if digest_chars == 0 && resume_chars == 0 {
        return Ok(());
    }
    let (_paths, _config, conn) = load_project(workspace)?;
    let ts = now_utc_rfc3339();

    if digest_chars > 0 {
        let approx_tokens = digest_chars / 4;
        let event = kimetsu_core::event::Event::new(
            kimetsu_core::ids::RunId::new(),
            "digest_served",
            serde_json::json!({
                "digest_chars": digest_chars,
                "approx_tokens": approx_tokens,
                "ts": ts,
            }),
        );
        let _ = crate::projector::insert_event(&conn, &event);
    }

    if resume_chars > 0 {
        let approx_tokens = resume_chars / 4;
        let event = kimetsu_core::event::Event::new(
            kimetsu_core::ids::RunId::new(),
            "resume_served",
            serde_json::json!({
                "resume_chars": resume_chars,
                "approx_tokens": approx_tokens,
                "ts": ts,
            }),
        );
        let _ = crate::projector::insert_event(&conn, &event);
    }

    Ok(())
}

// ── Input assembly ────────────────────────────────────────────────────────────

/// Raw ingredients for the digest.
#[derive(Debug, Default)]
struct DigestInputs {
    /// Top-useful memory snippets: `(kind, text_snippet)`.
    top_memories: Vec<(String, String)>,
    /// Manifest summaries: `(manifest_kind, path)` e.g. ("cargo", "Cargo.toml").
    manifests: Vec<(String, String)>,
}

impl DigestInputs {
    fn is_empty(&self) -> bool {
        self.top_memories.is_empty() && self.manifests.is_empty()
    }
}

fn gather_inputs(conn: &Connection, repo_root: &str) -> KimetsuResult<DigestInputs> {
    let mut inputs = DigestInputs::default();

    // Top-useful memories (conventions/facts, no superseded/invalidated).
    // Include memories with use_count = 0 (fresh adds) ordered by recency
    // so new brains produce useful digests without requiring prior runs.
    // use_count > 0 memories are ranked by usefulness ratio; use_count = 0
    // rows sort last (usefulness_score default 0).
    //
    // v2.6: preferences are excluded. They now have their own warm-start
    // section (`crate::user_profile`), which sits directly beside this one, so
    // including them here would print the same lines twice in the same block —
    // and the digest's slots are better spent on facts the preferences section
    // will never carry.
    {
        let mut stmt = conn.prepare(
            "SELECT kind, text
             FROM memories
             WHERE invalidated_at IS NULL
               AND superseded_by IS NULL
               AND (valid_from IS NULL OR julianday(valid_from) <= julianday('now'))
               AND (valid_to IS NULL OR julianday(valid_to) > julianday('now'))
               AND kind != 'preference'
             ORDER BY
               CASE WHEN use_count > 0
                    THEN (usefulness_score / CAST(use_count AS REAL))
                    ELSE 0.0
               END DESC,
               use_count DESC,
               created_at DESC
             LIMIT ?1",
        )?;
        let rows = stmt.query_map([TOP_MEMORY_COUNT as i64], |row| {
            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
        })?;
        for (kind, text) in rows.flatten() {
            let snippet: String = text.chars().take(MEMORY_SNIPPET_CHARS).collect();
            inputs.top_memories.push((kind, snippet));
        }
    }

    // Repo manifests (Cargo.toml, package.json, pyproject.toml, …)
    {
        let mut stmt = conn.prepare(
            "SELECT manifest_kind, manifest_path
             FROM repo_manifests
             WHERE repo_root = ?1
             LIMIT 10",
        )?;
        let rows = stmt.query_map([repo_root], |row| {
            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
        })?;
        for pair in rows.flatten() {
            inputs.manifests.push(pair);
        }
    }

    // Task focus belongs exclusively to the identity-scoped resume block.

    Ok(inputs)
}

// ── Content hash ──────────────────────────────────────────────────────────────

fn content_hash(inputs: &DigestInputs) -> u64 {
    let mut h = DefaultHasher::new();
    for (kind, text) in &inputs.top_memories {
        kind.hash(&mut h);
        text.hash(&mut h);
    }
    for (mk, mp) in &inputs.manifests {
        mk.hash(&mut h);
        mp.hash(&mut h);
    }
    h.finish()
}

// ── Rule-based assembler ──────────────────────────────────────────────────────

fn assemble_rule_based(
    inputs: &DigestInputs,
    _config: &kimetsu_core::config::ProjectConfig,
) -> KimetsuResult<String> {
    let mut parts: Vec<String> = Vec::new();

    // Manifests → project type hint.
    if !inputs.manifests.is_empty() {
        let manifest_list: Vec<String> = inputs
            .manifests
            .iter()
            .map(|(kind, path)| format!("{kind}: {path}"))
            .collect();
        parts.push(format!("Project manifests: {}", manifest_list.join(", ")));
    }

    // Top memories.
    if !inputs.top_memories.is_empty() {
        parts.push("Key conventions and facts:".to_string());
        for (kind, text) in &inputs.top_memories {
            parts.push(format!("[{kind}] {text}"));
        }
    }

    let digest = parts.join("\n");

    // Budget-cap: truncate to char limit with ellipsis.
    if digest.len() > DIGEST_CHAR_BUDGET {
        let mut s: String = digest.chars().take(DIGEST_CHAR_BUDGET - 3).collect();
        s.push_str("...");
        Ok(s)
    } else {
        Ok(digest)
    }
}

// ── Cache helpers ─────────────────────────────────────────────────────────────

fn try_load_cache(cache_path: &Path, meta_path: &Path, current_hash: u64) -> Option<String> {
    if !cache_path.exists() || !meta_path.exists() {
        return None;
    }
    let meta = load_meta(meta_path).ok()?;
    if meta.input_hash != current_hash {
        return None;
    }
    std::fs::read_to_string(cache_path).ok()
}

fn load_meta(meta_path: &Path) -> KimetsuResult<DigestMeta> {
    let text = std::fs::read_to_string(meta_path)?;
    Ok(serde_json::from_str(&text)?)
}

/// Atomic text write: temp + rename.
fn atomic_write_text(path: &Path, content: &str) {
    let Some(parent) = path.parent() else {
        return;
    };
    let _ = std::fs::create_dir_all(parent);
    let tmp = path.with_extension("md.tmp");
    if std::fs::write(&tmp, content).is_ok() {
        let _ = std::fs::rename(&tmp, path);
    }
}

/// Atomic JSON meta write: temp + rename.
fn atomic_write_json_meta(path: &Path, meta: &DigestMeta) {
    let Some(parent) = path.parent() else {
        return;
    };
    let _ = std::fs::create_dir_all(parent);
    let Ok(text) = serde_json::to_string(meta) else {
        return;
    };
    let tmp = path.with_extension("json.tmp");
    if std::fs::write(&tmp, &text).is_ok() {
        let _ = std::fs::rename(&tmp, path);
    }
}

fn now_utc_rfc3339() -> String {
    time::OffsetDateTime::now_utc()
        .format(&time::format_description::well_known::Rfc3339)
        .unwrap_or_default()
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use kimetsu_core::paths::git_init_boundary;

    use super::*;
    use crate::{project, user_brain};

    #[test]
    fn hardening_warm_profile_honors_user_brain_opt_out() {
        user_brain::with_user_brain_disabled(|| {
            let dir = tmp_workspace("hardening-warm-profile-off");
            git_init_boundary(&dir);
            project::init_project(&dir, false).unwrap();
            let global_dir = dir.join("isolated-global");
            std::fs::create_dir_all(&global_dir).unwrap();
            // The shared test-env lock is held by with_user_brain_disabled.
            unsafe {
                std::env::set_var("KIMETSU_USER_BRAIN_DIR", &global_dir);
            }
            let global =
                Connection::open(kimetsu_core::paths::user_brain_db_path().unwrap()).unwrap();
            crate::schema::initialize(&global).unwrap();
            global.execute("INSERT INTO memories(memory_id,scope,kind,text,normalized_text,confidence,provenance_snapshot_json,created_at) VALUES('global','global_user','preference','PRIVATE_GLOBAL','private_global',1.0,'{}','2026-01-01T00:00:00Z')", []).unwrap();
            let env_disabled = user_profile_block(&dir);
            let (paths, mut config, conn) = load_project_readonly(&dir).unwrap();
            config.kimetsu.use_user_brain = false;
            std::fs::write(paths.project_toml, config.to_toml().unwrap()).unwrap();
            unsafe {
                std::env::remove_var("KIMETSU_USER_BRAIN");
            }
            let config_disabled = user_profile_block(&dir);
            unsafe {
                std::env::set_var("KIMETSU_USER_BRAIN", "0");
                std::env::remove_var("KIMETSU_USER_BRAIN_DIR");
            }
            drop(conn);
            drop(global);
            std::fs::remove_dir_all(dir).unwrap();
            assert!(
                env_disabled.is_none(),
                "environment opt-out leaked global profile"
            );
            assert!(
                config_disabled.is_none(),
                "project opt-out leaked global profile"
            );
        });
    }

    #[test]
    fn hardening_warm_digest_revalidates_corrected_and_retired_claims() {
        user_brain::with_user_brain_disabled(|| {
            let dir = tmp_workspace("hardening-warm-current");
            git_init_boundary(&dir);
            project::init_project(&dir, false).unwrap();
            let id = project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Fact,
                "ORIGINAL port is 4001",
            )
            .unwrap();
            assert!(
                build_or_load_digest(&dir, true)
                    .unwrap()
                    .contains("ORIGINAL")
            );
            project::edit_memory(&dir, &id, Some("CORRECTED port is 4002"), None).unwrap();
            let block = warm_start_block_scoped(&dir, "lane-a").unwrap();
            assert!(
                !block.contains("ORIGINAL"),
                "stale cache must never reintroduce corrected text"
            );
            assert!(block.contains("CORRECTED"));
            // Separate cache-file publishers can leave old text with current
            // input metadata. Delivery must bind to the gathered inputs anyway.
            let (paths, _, conn) = load_project_readonly(&dir).unwrap();
            std::fs::write(paths.kimetsu_dir.join("digest.md"), "ORIGINAL port is 4001").unwrap();
            let mixed = warm_start_block_scoped(&dir, "lane-a").unwrap();
            assert!(
                mixed.contains("CORRECTED") && !mixed.contains("ORIGINAL"),
                "mixed cache generations leaked: {mixed}"
            );
            drop(conn);
            project::invalidate_memory(&dir, &id, Some("wrong claim")).unwrap();
            assert!(
                !warm_start_block_scoped(&dir, "lane-a")
                    .unwrap_or_default()
                    .contains("CORRECTED")
            );
            std::fs::remove_dir_all(dir).unwrap();
        });
    }

    #[test]
    fn hardening_warm_digest_excludes_invalid_time_and_other_task_focus() {
        user_brain::with_user_brain_disabled(|| {
            let dir = tmp_workspace("hardening-warm-validity");
            git_init_boundary(&dir);
            project::init_project(&dir, false).unwrap();
            for (text, from, to) in [
                ("CURRENT endpoint", None, None),
                ("FUTURE endpoint", Some("2099-01-01T00:00:00Z"), None),
                ("EXPIRED endpoint", None, Some("2020-01-01T00:00:00Z")),
            ] {
                project::add_memory_with_validity(
                    &dir,
                    kimetsu_core::memory::MemoryScope::Project,
                    kimetsu_core::memory::MemoryKind::Fact,
                    text,
                    from,
                    to,
                )
                .unwrap();
            }
            for lane in ["ALPHA", "BETA"] {
                crate::episode::capture_episode(
                    &dir,
                    crate::episode::EpisodePayload {
                        identity: lane.into(),
                        task: format!("{lane} task title"),
                        summary: format!("{lane} task state"),
                        ..Default::default()
                    },
                )
                .unwrap();
            }
            let block = warm_start_block_scoped(&dir, "ALPHA").unwrap();
            assert!(block.contains("CURRENT") && block.contains("ALPHA"));
            assert!(
                !block.contains("FUTURE") && !block.contains("EXPIRED") && !block.contains("BETA"),
                "{block}"
            );
            std::fs::remove_dir_all(dir).unwrap();
        });
    }

    fn tmp_workspace(name: &str) -> std::path::PathBuf {
        let ts = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_nanos())
            .unwrap_or(0);
        let dir = std::env::temp_dir().join(format!("kimetsu-digest-{name}-{ts}"));
        std::fs::create_dir_all(&dir).expect("create tmp");
        dir
    }

    // D1: empty brain returns None (no content to digest).
    #[test]
    fn empty_brain_returns_none() {
        let dir = tmp_workspace("empty");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            let result = build_or_load_digest(&dir, false);
            assert!(result.is_none(), "empty brain must return None digest");
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D2: digest with memories is non-empty and ≤ budget.
    #[test]
    fn digest_with_memories_is_bounded() {
        let dir = tmp_workspace("bounded");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            // Seed a memory so there's content to digest.
            // The digest includes memories even with use_count=0 (fresh adds).
            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Convention,
                "Always use git_init_boundary before init_project in tests",
            )
            .expect("add_memory");

            let digest = build_or_load_digest(&dir, true).expect("digest must be Some");
            assert!(!digest.is_empty(), "digest must be non-empty");
            assert!(
                digest.len() <= DIGEST_CHAR_BUDGET + 3,
                "digest must respect char budget: {} chars",
                digest.len()
            );
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D3: cache is reused on second call (no force_rebuild).
    #[test]
    fn cache_is_reused_on_second_call() {
        let dir = tmp_workspace("cache");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Fact,
                "Rust edition 2024 is the target edition for this workspace",
            )
            .expect("add_memory");
            let d1 = build_or_load_digest(&dir, true).expect("first build");
            let d2 = build_or_load_digest(&dir, false).expect("cached load");
            assert_eq!(d1, d2, "cached digest must match first build");
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D4: force_rebuild bypasses cache.
    #[test]
    fn force_rebuild_bypasses_cache() {
        let dir = tmp_workspace("force");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Convention,
                "Force rebuild test convention",
            )
            .expect("add_memory");
            let d1 = build_or_load_digest(&dir, true).expect("first build");
            let d2 = build_or_load_digest(&dir, true).expect("forced rebuild");
            // Content should match because inputs are the same.
            assert_eq!(
                d1, d2,
                "forced rebuild must produce same content when inputs unchanged"
            );
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D5: is_stale returns true when no cache exists.
    #[test]
    fn is_stale_true_when_no_cache() {
        let dir = tmp_workspace("stale");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            assert!(is_stale(&dir), "must be stale when cache does not exist");
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D6: is_stale returns false after a successful build.
    #[test]
    fn is_stale_false_after_build() {
        let dir = tmp_workspace("fresh");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Fact,
                "After-build staleness check fact",
            )
            .expect("add_memory");
            let _ = build_or_load_digest(&dir, true);
            assert!(
                !is_stale(&dir),
                "must NOT be stale immediately after a fresh build"
            );
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D6b: load_cached_digest returns the cached text without rebuilding, and
    // keeps returning it once the corpus has moved on. This is what lets the
    // warm start serve instantly and rebuild off the hot path.
    #[test]
    fn load_cached_digest_serves_stale_text() {
        let dir = tmp_workspace("cached-stale");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            assert!(
                load_cached_digest(&dir).is_none(),
                "nothing cached yet on a cold brain"
            );

            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Fact,
                "Cached digest fact",
            )
            .expect("add_memory");
            let built = build_or_load_digest(&dir, true).expect("first build");
            assert_eq!(load_cached_digest(&dir).as_deref(), Some(built.as_str()));

            // Move the corpus: the cache is now stale, but still servable.
            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Convention,
                "A second memory that invalidates the digest hash",
            )
            .expect("add_memory");
            assert!(is_stale(&dir), "corpus moved — cache must read as stale");
            assert_eq!(
                load_cached_digest(&dir).as_deref(),
                Some(built.as_str()),
                "stale cache is still served verbatim"
            );
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D6c: warm_start_block honours the [broker] warm_start gate, and produces
    // the digest section when there is content.
    #[test]
    fn warm_start_block_respects_gate_and_renders_digest() {
        let dir = tmp_workspace("warm-block");
        git_init_boundary(&dir);
        user_brain::with_user_brain_disabled(|| {
            project::init_project(&dir, true).expect("init");
            project::add_memory(
                &dir,
                kimetsu_core::memory::MemoryScope::Project,
                kimetsu_core::memory::MemoryKind::Convention,
                "Warm start block convention",
            )
            .expect("add_memory");

            let block = warm_start_block(&dir).expect("warm start must have content");
            assert!(
                block.contains("## Repo context"),
                "warm start must carry the repo digest: {block}"
            );

            // Turn the gate off; the block must disappear entirely.
            let paths = kimetsu_core::paths::ProjectPaths::discover(&dir).expect("paths");
            let mut config = crate::project::load_config(&paths).expect("config");
            config.broker.warm_start = false;
            std::fs::write(&paths.project_toml, config.to_toml().expect("to_toml"))
                .expect("write project.toml");

            assert!(
                warm_start_block(&dir).is_none(),
                "[broker] warm_start = false must silence the warm start"
            );
        });
        std::fs::remove_dir_all(dir).ok();
    }

    // D7: digest size is ≤ ~400 tokens (character proxy: 1600 chars).
    // This is the measurement/gate required by Story 1.6.
    #[test]
    fn digest_size_within_400_token_budget() {
        // Assemble a large set of inputs and verify the rule-based assembler
        // respects the budget.
        let inputs = DigestInputs {
            top_memories: (0..10)
                .map(|i| {
                    (
                        "convention".to_string(),
                        "A".repeat(MEMORY_SNIPPET_CHARS) + &format!(" #{i}"),
                    )
                })
                .collect(),
            manifests: (0..5)
                .map(|i| ("cargo".to_string(), format!("Cargo{i}.toml")))
                .collect(),
        };
        let config = kimetsu_core::config::ProjectConfig::default_for_project("test");
        let digest = assemble_rule_based(&inputs, &config).expect("assemble");
        let char_count = digest.chars().count();
        assert!(
            char_count <= DIGEST_CHAR_BUDGET + 3,
            "digest must fit in budget: got {char_count} chars (budget={DIGEST_CHAR_BUDGET})"
        );
        // Approximate token count: chars / 4.
        let approx_tokens = char_count / 4;
        assert!(
            approx_tokens <= 420,
            "approx token count {approx_tokens} must be ≤ 420"
        );
    }

    // D8: record_warmstart_served is best-effort (no panic on uninitialized brain).
    #[test]
    fn record_warmstart_served_is_best_effort() {
        let tmp = std::env::temp_dir().join("kimetsu-digest-roi-besteffort");
        // No brain initialized — must not panic.
        record_warmstart_served(&tmp, 500, 100);
    }
}