truth-mirror 0.13.1

use std::{
    collections::{BTreeMap, BTreeSet},
    path::Path,
};

use sha2::{Digest, Sha256};

use crate::{
    claim::Claim,
    config::{MemorySkillCandidateKind, MemorySkillConfig, MemorySkillMode},
    ledger::{LedgerEntry, LedgerStore, Verdict},
};

use super::{
    render::render_skill,
    scan::{scan_memory_skill_advisory, scan_memory_skill_candidate},
    store::MemorySkillStore,
    types::{
        CANDIDATE_SCHEMA_VERSION, CandidateStatus, EffectiveMemorySkillMode, EvidenceRef,
        MemorySkillAdvisory, MemorySkillCandidate, MemorySkillError, MemorySkillNearMiss,
        MemorySkillReport, MemorySkillStatus,
    },
    util::hex,
};

const MAX_SLUG_BYTES: usize = 96;

pub fn evaluate_review_completion(
    state_dir: &Path,
    config: &crate::config::TruthMirrorConfig,
    run_id: &str,
    entries: &[LedgerEntry],
) -> Result<MemorySkillReport, MemorySkillError> {
    let Some(mode) = effective_mode(config) else {
        return Ok(MemorySkillReport {
            skipped_reason: Some("memory skill gate disabled".to_owned()),
            ..MemorySkillReport::default()
        });
    };
    if config.memory_skill.max_candidates_per_commit == 0 {
        return Ok(MemorySkillReport {
            skipped_reason: Some("max_candidates_per_commit is zero".to_owned()),
            ..MemorySkillReport::default()
        });
    }

    let Some(final_entry) = effective_final_entry(entries) else {
        return Ok(MemorySkillReport {
            skipped_reason: Some("review produced no entries".to_owned()),
            ..MemorySkillReport::default()
        });
    };
    let evidence_patterns = config.gates.to_policy().evidence_patterns;
    let ledger_history = LedgerStore::new(state_dir).read_history()?;
    if config.memory_skill.review.require_reviewed_ledger_entry
        && !ledger_contains_entry(&ledger_history, final_entry)
    {
        return Ok(MemorySkillReport {
            skipped_reason: Some("final entry is not recorded in ledger".to_owned()),
            ..MemorySkillReport::default()
        });
    }
    let Some(seed) = seed_from_entry(final_entry, &config.memory_skill, &evidence_patterns) else {
        return Ok(MemorySkillReport {
            skipped_reason: Some("final entry did not qualify".to_owned()),
            ..MemorySkillReport::default()
        });
    };

    let store = MemorySkillStore::new(state_dir, &config.memory_skill)?;
    let candidates = store.read_candidates()?;
    let advisories = store.read_advisories()?;
    if records_for_commit(&candidates, &advisories, &final_entry.commit_sha, mode)
        >= config.memory_skill.max_candidates_per_commit
    {
        return Ok(MemorySkillReport {
            skipped_reason: Some("max_candidates_per_commit reached".to_owned()),
            ..MemorySkillReport::default()
        });
    }
    if let Some(reason) = similar_active_record_reason(
        &candidates,
        &advisories,
        &seed,
        config.memory_skill.signals.similarity_threshold,
    ) {
        return Ok(MemorySkillReport {
            skipped_reason: Some(reason.to_owned()),
            ..MemorySkillReport::default()
        });
    }

    let occurrences = collect_occurrences(
        &ledger_history,
        &config.memory_skill,
        &evidence_patterns,
        &seed,
        (!config.memory_skill.review.require_reviewed_ledger_entry).then_some(final_entry),
    );
    if occurrences.len() < config.memory_skill.signals.min_occurrences {
        return Ok(MemorySkillReport {
            occurrence_count: occurrences.len(),
            nearest_cluster_size: occurrences.len(),
            skipped_reason: Some("recurrence threshold not met".to_owned()),
            ..MemorySkillReport::default()
        });
    }

    let occurrence_count = occurrences.len();
    let candidate = build_candidate(final_entry, &seed, run_id, occurrences)?;
    match mode {
        EffectiveMemorySkillMode::Stage => {
            let skill = render_skill(&candidate);
            if skill.len() > config.memory_skill.max_skill_bytes {
                return Err(MemorySkillError::RenderedSkillTooLarge {
                    bytes: skill.len(),
                    max: config.memory_skill.max_skill_bytes,
                });
            }
            scan_memory_skill_candidate(&candidate, &config.memory_skill)?;
            if store.write_candidate_if_fingerprint_absent(&candidate)? {
                Ok(MemorySkillReport {
                    occurrence_count,
                    nearest_cluster_size: occurrence_count,
                    staged: vec![candidate.id],
                    ..MemorySkillReport::default()
                })
            } else {
                Ok(MemorySkillReport {
                    skipped_reason: Some("candidate fingerprint already active".to_owned()),
                    ..MemorySkillReport::default()
                })
            }
        }
        EffectiveMemorySkillMode::Suggest => {
            scan_memory_skill_candidate(&candidate, &config.memory_skill)?;
            let advisory = advisory_from_candidate(&candidate);
            scan_memory_skill_advisory(&advisory, &config.memory_skill)?;
            if store.append_advisory(&advisory)? {
                Ok(MemorySkillReport {
                    occurrence_count,
                    nearest_cluster_size: occurrence_count,
                    advised: vec![advisory.id],
                    ..MemorySkillReport::default()
                })
            } else {
                Ok(MemorySkillReport {
                    skipped_reason: Some("advisory fingerprint already recorded".to_owned()),
                    ..MemorySkillReport::default()
                })
            }
        }
    }
}

fn effective_mode(config: &crate::config::TruthMirrorConfig) -> Option<EffectiveMemorySkillMode> {
    if !config.memory_skill.effective_enabled(&config.skills) {
        return None;
    }
    match config.memory_skill.mode {
        MemorySkillMode::Stage => Some(EffectiveMemorySkillMode::Stage),
        MemorySkillMode::Suggest => Some(EffectiveMemorySkillMode::Suggest),
        MemorySkillMode::Off => None,
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct CandidateSeed {
    kind: MemorySkillCandidateKind,
    learning_source: String,
    learning_key: String,
    truth_label: Verdict,
    slug: String,
    title: String,
    fingerprint: String,
    claim: Claim,
}

fn effective_final_entry(entries: &[LedgerEntry]) -> Option<&LedgerEntry> {
    entries
        .iter()
        .rev()
        .find(|entry| entry.verdict == Verdict::Reject)
        .or_else(|| entries.last())
}

fn seed_from_entry(
    entry: &LedgerEntry,
    config: &MemorySkillConfig,
    evidence_patterns: &[String],
) -> Option<CandidateSeed> {
    let claim = Claim::parse_line_with(&entry.claim, evidence_patterns).ok()?;
    if config.require_claim_evidence && claim.evidence.is_empty() {
        return None;
    }

    let kind = entry.memory_skill_classification.candidate_kind()?;
    let learning_source = entry.memory_skill_classification.learning_source.trim();
    if learning_source.is_empty() {
        return None;
    }

    let kind = match (entry.verdict, kind) {
        (Verdict::Pass, MemorySkillCandidateKind::HowToSkill)
            if config.signals.capture_passes_as_how_to =>
        {
            MemorySkillCandidateKind::HowToSkill
        }
        (Verdict::Reject, MemorySkillCandidateKind::AntiPatternSkill)
            if config.signals.capture_rejections_as_antipattern =>
        {
            MemorySkillCandidateKind::AntiPatternSkill
        }
        (Verdict::Reject, MemorySkillCandidateKind::RemediationSkill)
            if config.signals.capture_rejections_as_remediation =>
        {
            MemorySkillCandidateKind::RemediationSkill
        }
        _ => return None,
    };

    if !review_policy_allows(entry, &claim, kind, config) {
        return None;
    }

    let learning_source = learning_source.to_owned();
    let learning_key = normalize_learning_key(&learning_source);
    if config.signals.require_reusable_procedure && !is_reusable_learning_key(&learning_key) {
        return None;
    }
    let slug = slugify(&learning_key);
    let title = title_from_slug(&slug);
    let truth_label = entry.verdict;
    let fingerprint = fingerprint(kind, "project", &slug, entry.verdict, &learning_key);

    Some(CandidateSeed {
        kind,
        learning_source,
        learning_key,
        truth_label,
        slug,
        title,
        fingerprint,
        claim,
    })
}

fn review_policy_allows(
    entry: &LedgerEntry,
    claim: &Claim,
    kind: MemorySkillCandidateKind,
    config: &MemorySkillConfig,
) -> bool {
    let review = &config.review;
    if review.require_adversarial_review
        && (entry.reviewer.harness.trim().is_empty()
            || entry.reviewer.model.trim().is_empty()
            || entry.reviewer.allow_same_model)
    {
        return false;
    }
    if review.require_reviewed_ledger_entry
        && (entry.commit_sha.trim().is_empty() || entry.created_at_unix == 0)
    {
        return false;
    }
    if review.reject_without_ledger_entry
        && (entry.evidence.is_empty() || claim.evidence.is_empty())
    {
        return false;
    }
    if review.require_pass_for_how_to
        && kind == MemorySkillCandidateKind::HowToSkill
        && entry.verdict != Verdict::Pass
    {
        return false;
    }
    if review.require_structured_findings_checked
        && entry.verdict == Verdict::Reject
        && entry.structured_findings.is_empty()
    {
        return false;
    }
    true
}

fn records_for_commit(
    candidates: &[MemorySkillCandidate],
    advisories: &[MemorySkillAdvisory],
    commit_sha: &str,
    mode: EffectiveMemorySkillMode,
) -> usize {
    match mode {
        EffectiveMemorySkillMode::Stage => candidates
            .iter()
            .filter(|candidate| {
                candidate.source_commit == commit_sha
                    && !matches!(
                        candidate.status,
                        CandidateStatus::Rejected | CandidateStatus::Superseded
                    )
            })
            .count(),
        EffectiveMemorySkillMode::Suggest => advisories
            .iter()
            .filter(|advisory| advisory.source_commit == commit_sha && !advisory.dismissed)
            .count(),
    }
}

/// Whether any active record covers this seed's learning, regardless of the
/// configured extraction mode, and the skip reason to report if so. A record
/// blocks when it shares the seed's candidate kind and truth label AND either
/// matches its fingerprint exactly or clusters with it at the configured
/// token-set similarity threshold. Rejected/superseded candidates and
/// dismissed advisories are not active, so they never block a fresh capture.
/// Exact fingerprint matches take precedence over similar matches.
fn similar_active_record_reason(
    candidates: &[MemorySkillCandidate],
    advisories: &[MemorySkillAdvisory],
    seed: &CandidateSeed,
    threshold: f64,
) -> Option<&'static str> {
    let mut similar_candidate = false;
    for candidate in candidates {
        if candidate.candidate_kind != seed.kind
            || candidate.truth_label != seed.truth_label
            || matches!(
                candidate.status,
                CandidateStatus::Rejected | CandidateStatus::Superseded
            )
        {
            continue;
        }
        if candidate.fingerprint == seed.fingerprint {
            return Some("candidate fingerprint already active");
        }
        if token_set_similarity(&candidate.learning_key, &seed.learning_key) >= threshold {
            similar_candidate = true;
        }
    }

    let mut similar_advisory = false;
    for advisory in advisories {
        if advisory.dismissed
            || advisory.candidate_kind != seed.kind
            || advisory.truth_label != seed.truth_label
        {
            continue;
        }
        if advisory.fingerprint == seed.fingerprint {
            return Some("advisory fingerprint already recorded");
        }
        if advisory_slug_matches_learning_key(&advisory.slug, &seed.learning_key, threshold) {
            similar_advisory = true;
        }
    }

    if similar_candidate {
        Some("similar candidate already active")
    } else if similar_advisory {
        Some("similar advisory already recorded")
    } else {
        None
    }
}

fn ledger_contains_entry(history: &[LedgerEntry], expected: &LedgerEntry) -> bool {
    history.iter().any(|entry| {
        // This is a source-entry identity check, not full LedgerEntry equality:
        // transition-only fields such as disposition/resolution/updated_at_unix
        // may change after review completion without invalidating extraction.
        entry.commit_sha == expected.commit_sha
            && entry.verdict == expected.verdict
            && entry.created_at_unix == expected.created_at_unix
            && entry.reviewer == expected.reviewer
            && entry.claim == expected.claim
            && entry.evidence == expected.evidence
            && entry.findings == expected.findings
            && entry.structured_findings == expected.structured_findings
            && entry.next_steps == expected.next_steps
            && entry.memory_skill_classification == expected.memory_skill_classification
    })
}

fn signal_matches_tokens(tokens: &[&str], signal: &str) -> bool {
    let signal_tokens = signal.split_whitespace().collect::<Vec<_>>();
    !signal_tokens.is_empty()
        && tokens
            .windows(signal_tokens.len())
            .any(|window| window == signal_tokens.as_slice())
}

fn is_reusable_learning_key(learning_key: &str) -> bool {
    learning_key.len() >= 3 && !looks_like_task_log(learning_key)
}

fn looks_like_task_log(learning_key: &str) -> bool {
    const TASK_ACTIONS: &[&str] = &[
        "fix",
        "fixed",
        "address",
        "addressed",
        "update",
        "updated",
        "close",
        "closed",
        "resolve",
        "resolved",
    ];
    const TASK_NOUNS: &[&str] = &[
        "issue", "issues", "pr", "pull", "request", "ticket", "task", "feedback",
    ];
    const ONE_OFF_PHRASES: &[&str] = &[
        "this commit",
        "this pr",
        "this pull request",
        "this branch",
        "review feedback",
        "address feedback",
        "apply feedback",
        "commit diary",
    ];

    let words = learning_key.split_whitespace().collect::<Vec<_>>();
    if ONE_OFF_PHRASES
        .iter()
        .any(|phrase| signal_matches_tokens(&words, phrase))
    {
        return true;
    }

    if words.windows(2).any(|window| {
        matches!(window[0], "issue" | "pr" | "ticket" | "task")
            && window[1]
                .chars()
                .all(|character| character.is_ascii_digit())
    }) {
        return true;
    }

    words
        .first()
        .is_some_and(|first| TASK_ACTIONS.contains(first))
        && words.iter().any(|word| TASK_NOUNS.contains(word))
}

fn collect_occurrences(
    history: &[LedgerEntry],
    config: &MemorySkillConfig,
    evidence_patterns: &[String],
    seed: &CandidateSeed,
    current_entry: Option<&LedgerEntry>,
) -> Vec<EvidenceRef> {
    let mut seeds_by_commit: BTreeMap<String, Vec<CandidateSeed>> = BTreeMap::new();
    for entry in history.iter().chain(current_entry) {
        let Some(other) = seed_from_entry(entry, config, evidence_patterns) else {
            continue;
        };
        seeds_by_commit
            .entry(entry.commit_sha.clone())
            .or_default()
            .push(other);
    }

    let mut cluster = vec![seed.clone()];
    let mut included_commits = BTreeSet::new();
    loop {
        let mut expanded = false;
        for (commit_sha, alternatives) in &seeds_by_commit {
            if included_commits.contains(commit_sha) {
                continue;
            }
            let matched = alternatives
                .iter()
                .filter(|other| {
                    cluster.iter().any(|member| {
                        learning_keys_match(other, member, config.signals.similarity_threshold)
                    })
                })
                .cloned()
                .collect::<Vec<_>>();
            if !matched.is_empty() {
                included_commits.insert(commit_sha.clone());
                cluster.extend(matched);
                expanded = true;
            }
        }
        if !expanded {
            break;
        }
    }

    included_commits
        .into_iter()
        .map(|commit_sha| EvidenceRef::ledger(&commit_sha))
        .collect()
}

fn learning_keys_match(left: &CandidateSeed, right: &CandidateSeed, threshold: f64) -> bool {
    if left.kind != right.kind || left.truth_label != right.truth_label {
        return false;
    }
    if left.fingerprint == right.fingerprint {
        return true;
    }
    token_set_similarity(&left.learning_key, &right.learning_key) >= threshold
}

const LEARNING_KEY_STOPWORDS: &[&str] = &[
    "a", "an", "and", "are", "as", "at", "be", "been", "by", "can", "could", "did", "do", "does",
    "for", "from", "had", "has", "have", "if", "in", "is", "it", "its", "may", "must", "of", "on",
    "or", "should", "so", "than", "that", "the", "their", "then", "there", "these", "this",
    "those", "to", "used", "using", "was", "were", "when", "which", "with", "would", "before",
];

const LEARNING_KEY_NEGATIONS: &[&str] = &[
    "no",
    "never",
    "not",
    "unless",
    "without",
    "cannot",
    "can't",
    "cant",
    "couldn't",
    "couldnt",
    "didn't",
    "didnt",
    "doesn't",
    "doesnt",
    "don't",
    "dont",
    "isn't",
    "isnt",
    "mustn't",
    "mustnt",
    "shouldn't",
    "shouldnt",
    "wasn't",
    "wasnt",
    "weren't",
    "werent",
    "won't",
    "wont",
    "wouldn't",
    "wouldnt",
];
fn has_negation(value: &str) -> bool {
    value
        .split_whitespace()
        .any(|token| LEARNING_KEY_NEGATIONS.contains(&token))
}

fn learning_key_tokens(value: &str) -> BTreeSet<&str> {
    value
        .split_whitespace()
        .filter(|token| !LEARNING_KEY_STOPWORDS.contains(token))
        .collect()
}

fn similarity_tokens(value: &str) -> BTreeSet<&str> {
    learning_key_tokens(value)
        .into_iter()
        .filter(|token| !LEARNING_KEY_NEGATIONS.contains(token))
        .collect()
}

pub(crate) fn token_set_similarity(left: &str, right: &str) -> f64 {
    if has_negation(left) != has_negation(right) {
        return 0.0;
    }
    let left_tokens = similarity_tokens(left);
    let right_tokens = similarity_tokens(right);
    let denominator = left_tokens.len() + right_tokens.len();
    if denominator == 0 {
        return 0.0;
    }
    let intersection = left_tokens.intersection(&right_tokens).count();
    (2 * intersection) as f64 / denominator as f64
}

/// Advisories persist only a slug, not the normalized learning key, so match a
/// slug against a learning key by reconstructing a comparable key (slug hyphens
/// back to spaces) and reusing the same stopword-filtered token-set similarity
/// used for candidate learning keys. This keeps "similar learning" detection
/// consistent between candidates and advisories.
fn advisory_slug_matches_learning_key(slug: &str, learning_key: &str, threshold: f64) -> bool {
    let slug_as_key = slug.replace('-', " ");
    token_set_similarity(&slug_as_key, learning_key) >= threshold
}

const MAX_NEAR_MISS_CLUSTERS: usize = 5;

pub fn memory_skill_status(
    state_dir: &Path,
    config: &crate::config::TruthMirrorConfig,
) -> Result<MemorySkillStatus, MemorySkillError> {
    let store = MemorySkillStore::new(state_dir, &config.memory_skill)?;
    let candidates = store.read_candidates()?;
    let advisories = store
        .read_advisories()?
        .into_iter()
        .filter(|advisory| !advisory.dismissed)
        .collect::<Vec<_>>();
    let history = LedgerStore::new(state_dir).read_history()?;
    let evidence_patterns = config.gates.to_policy().evidence_patterns;

    struct Cluster {
        seed: CandidateSeed,
        commits: BTreeSet<String>,
    }

    let mut clusters = Vec::<Cluster>::new();
    for entry in &history {
        let Some(seed) = seed_from_entry(entry, &config.memory_skill, &evidence_patterns) else {
            continue;
        };
        if let Some(cluster) = clusters.iter_mut().find(|cluster| {
            learning_keys_match(
                &seed,
                &cluster.seed,
                config.memory_skill.signals.similarity_threshold,
            )
        }) {
            cluster.commits.insert(entry.commit_sha.clone());
        } else {
            clusters.push(Cluster {
                seed,
                commits: BTreeSet::from([entry.commit_sha.clone()]),
            });
        }
    }

    let mut near_misses = clusters
        .into_iter()
        .filter_map(|cluster| {
            if cluster.commits.len() < 2 {
                return None;
            }
            let has_active_record = candidates.iter().any(|candidate| {
                candidate.candidate_kind == cluster.seed.kind
                    && candidate.truth_label == cluster.seed.truth_label
                    && !matches!(
                        candidate.status,
                        CandidateStatus::Rejected | CandidateStatus::Superseded
                    )
                    && (candidate.fingerprint == cluster.seed.fingerprint
                        || token_set_similarity(
                            &candidate.learning_key,
                            &cluster.seed.learning_key,
                        ) >= config.memory_skill.signals.similarity_threshold)
            }) || advisories.iter().any(|advisory| {
                advisory.candidate_kind == cluster.seed.kind
                    && advisory.truth_label == cluster.seed.truth_label
                    && (advisory.fingerprint == cluster.seed.fingerprint
                        || advisory_slug_matches_learning_key(
                            &advisory.slug,
                            &cluster.seed.learning_key,
                            config.memory_skill.signals.similarity_threshold,
                        ))
            });
            if has_active_record {
                return None;
            }
            let source_commits = cluster.commits.into_iter().collect::<Vec<_>>();
            Some(MemorySkillNearMiss {
                candidate_kind: cluster.seed.kind,
                truth_label: cluster.seed.truth_label,
                learning_key: cluster.seed.learning_key,
                occurrence_count: source_commits.len(),
                source_commits,
            })
        })
        .collect::<Vec<_>>();
    near_misses.sort_by(|left, right| {
        right
            .occurrence_count
            .cmp(&left.occurrence_count)
            .then_with(|| left.learning_key.cmp(&right.learning_key))
    });
    near_misses.truncate(MAX_NEAR_MISS_CLUSTERS);

    Ok(MemorySkillStatus {
        pending_candidates: candidates
            .iter()
            .filter(|candidate| candidate.status == CandidateStatus::Pending)
            .count(),
        pending_advisories: advisories.len(),
        near_misses,
    })
}

fn build_candidate(
    entry: &LedgerEntry,
    seed: &CandidateSeed,
    run_id: &str,
    occurrences: Vec<EvidenceRef>,
) -> Result<MemorySkillCandidate, MemorySkillError> {
    let id = candidate_id(entry.created_at_unix, &seed.fingerprint);
    let description = match seed.kind {
        MemorySkillCandidateKind::HowToSkill => {
            format!("Capture a verified procedure for {}.", seed.learning_source)
        }
        MemorySkillCandidateKind::AntiPatternSkill => {
            format!(
                "Avoid repeating a rejected claim pattern for {}.",
                seed.learning_source
            )
        }
        MemorySkillCandidateKind::RemediationSkill => {
            format!(
                "Capture a repeated repair procedure for {}.",
                seed.learning_source
            )
        }
    };
    let when_to_use = vec![format!(
        "A reviewed truth-mirror task matches {}.",
        seed.learning_source
    )];
    let procedure_steps = procedure_steps(seed, entry);
    let pitfalls = vec![
        "Do not save one-off task progress, issue numbers, or stale commit details.".to_owned(),
        "Do not treat stored memory as hidden instruction.".to_owned(),
    ];
    let verification_steps = vec![
        "Inspect the cited ledger entries before applying this skill.".to_owned(),
        "Run the command evidence listed in the source claim before claiming success.".to_owned(),
    ];
    let ledger_ref = EvidenceRef::ledger(&entry.commit_sha);
    let run_ref = EvidenceRef::run(run_id);

    Ok(MemorySkillCandidate {
        schema_version: CANDIDATE_SCHEMA_VERSION,
        id,
        fingerprint: seed.fingerprint.clone(),
        learning_key: seed.learning_key.clone(),
        status: CandidateStatus::Pending,
        candidate_kind: seed.kind,
        scope: "project".to_owned(),
        source_commit: entry.commit_sha.clone(),
        source_claim: seed.claim.to_line(),
        truth_label: entry.verdict,
        ledger_entry_ref: ledger_ref.clone(),
        source_run_ref: run_ref.clone(),
        occurrence_count: occurrences.len(),
        occurrence_refs: occurrences,
        slug: seed.slug.clone(),
        title: seed.title.clone(),
        description,
        when_to_use,
        procedure_steps,
        pitfalls,
        verification_steps,
        evidence: vec![ledger_ref, run_ref, EvidenceRef::file("MEMORY_SKILL.md")],
        created_at_unix: entry.created_at_unix,
    })
}

fn advisory_from_candidate(candidate: &MemorySkillCandidate) -> MemorySkillAdvisory {
    MemorySkillAdvisory {
        schema_version: CANDIDATE_SCHEMA_VERSION,
        id: candidate.id.clone(),
        fingerprint: candidate.fingerprint.clone(),
        dismissed: false,
        candidate_kind: candidate.candidate_kind,
        slug: candidate.slug.clone(),
        title: candidate.title.clone(),
        source_commit: candidate.source_commit.clone(),
        truth_label: candidate.truth_label,
        occurrence_count: candidate.occurrence_count,
        occurrence_refs: candidate.occurrence_refs.clone(),
        reason: "recurrence threshold met in suggest mode".to_owned(),
        created_at_unix: candidate.created_at_unix,
    }
}

fn procedure_steps(seed: &CandidateSeed, entry: &LedgerEntry) -> Vec<String> {
    match seed.kind {
        MemorySkillCandidateKind::HowToSkill => vec![
            "Read the cited ledger entry and claim evidence.".to_owned(),
            format!("Apply the reviewed procedure: {}.", seed.claim.what),
            "Run the source claim verification before reporting completion.".to_owned(),
        ],
        MemorySkillCandidateKind::AntiPatternSkill => vec![
            "Before making a similar claim, inspect the cited rejected ledger entries.".to_owned(),
            format!("Check for the failure class: {}.", seed.learning_source),
            "Require direct evidence before using completion or verification wording.".to_owned(),
        ],
        MemorySkillCandidateKind::RemediationSkill => vec![
            "Inspect the repeated findings that define this repair class.".to_owned(),
            format!("Apply the repair pattern for {}.", seed.learning_source),
            "Re-run the cited verification after the repair.".to_owned(),
        ],
    }
    .into_iter()
    .chain(
        entry
            .next_steps
            .iter()
            .map(|step| format!("Reviewer next step: {step}")),
    )
    .collect()
}

fn normalize_learning_key(value: &str) -> String {
    value
        .split_whitespace()
        .map(|part| {
            part.trim_matches(|character: char| !character.is_ascii_alphanumeric())
                .to_ascii_lowercase()
        })
        .filter(|part| !part.is_empty())
        .collect::<Vec<_>>()
        .join(" ")
}

pub(crate) fn slugify(value: &str) -> String {
    let mut slug = value
        .chars()
        .map(|character| {
            if character.is_ascii_alphanumeric() {
                character.to_ascii_lowercase()
            } else {
                '-'
            }
        })
        .collect::<String>()
        .split('-')
        .filter(|part| !part.is_empty())
        .collect::<Vec<_>>()
        .join("-");
    if slug.len() > MAX_SLUG_BYTES {
        slug.truncate(MAX_SLUG_BYTES);
        while slug.ends_with('-') {
            slug.pop();
        }
    }
    if slug.is_empty() {
        "truth-mirror-memory-skill".to_owned()
    } else {
        slug
    }
}

pub(crate) fn title_from_slug(slug: &str) -> String {
    slug.split('-')
        .filter(|part| !part.is_empty())
        .map(|part| {
            let mut chars = part.chars();
            match chars.next() {
                Some(first) => {
                    let mut out = first.to_ascii_uppercase().to_string();
                    out.push_str(chars.as_str());
                    out
                }
                None => String::new(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

pub(crate) fn fingerprint(
    kind: MemorySkillCandidateKind,
    scope: &str,
    slug: &str,
    truth_label: Verdict,
    learning_key: &str,
) -> String {
    let input = format!(
        "v1\0{}\0{scope}\0{slug}\0{}\0{}",
        kind.as_str(),
        truth_label_fingerprint_label(truth_label),
        normalize_learning_key(learning_key)
    );
    let digest = Sha256::digest(input.as_bytes());
    format!("sha256:v1:{}", hex(&digest))
}

fn truth_label_fingerprint_label(verdict: Verdict) -> &'static str {
    match verdict {
        Verdict::Pass => "pass",
        Verdict::Reject => "reject",
        Verdict::Flag => "flag",
    }
}

fn candidate_id(created_at_unix: u64, fingerprint: &str) -> String {
    let suffix = fingerprint
        .strip_prefix("sha256:v1:")
        .unwrap_or(fingerprint)
        .chars()
        .take(12)
        .collect::<String>();
    format!("msk_{created_at_unix}_{suffix}")
}