Merge historian references: 3 seeds, 3 scored diverse, 4 unscored recent

Co-authored-by: Alfonso <alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

crates/mc-module/gen/gen-historian-prompt-golden.ts

@@ -25,7 +25,7 @@ const { buildCompartmentAgentPrompt } = promptMod as {
         extractionFree?: boolean;
     }) => string;
 };
-const { buildReferenceBlocks, selectSeeds, renderSeedExamplesBlock } = referenceMod as {
+const { buildReferenceBlocks, selectSeeds, renderSeedExamplesBlock, selectSessionReferences, renderSessionReferencesBlock } = referenceMod as {
     buildReferenceBlocks: (args: {
         sessionId: string;
         chunkStart: number;
@@ -37,6 +37,8 @@ const { buildReferenceBlocks, selectSeeds, renderSeedExamplesBlock } = reference
         count?: number,
     ) => Array<{ importance: number; block: string }>;
     renderSeedExamplesBlock: (seeds: Array<{ importance: number; block: string }>) => string;
+    selectSessionReferences: (compartments: TsReferenceCompartment[], seeds: Array<{ importance: number; block: string }>, sessionId: string, chunkStart: number) => TsReferenceCompartment[];
+    renderSessionReferencesBlock: (selected: TsReferenceCompartment[], window?: number) => string;
 };
 const { renderHistorianMemoryBlock } = injectMod as {
     renderHistorianMemoryBlock: (memories: TsMemory[]) => string | null;
@@ -190,14 +192,14 @@ const matureCompartments: ReferenceCompartmentJson[] = [
     {
         start_message: 1,
         end_message: 5,
-        title: "old omitted one",
+        title: "older low-mid one",
         content: "old content one",
         importance: 10,
     },
     {
         start_message: 6,
         end_message: 12,
-        title: "old omitted two",
+        title: "older low-mid two",
         content: "old content two",
         importance: 20,
     },
@@ -334,9 +336,9 @@ const promptCaseSpecs: PromptCaseSpec[] = [
 ];
 
 const seedCaseSpecs: SeedCaseSpec[] = [
-    { label: "default rotation a", session_id: "rot-a", chunk_start: 0, count: 4 },
-    { label: "default rotation b", session_id: "rot-b", chunk_start: 1, count: 4 },
-    { label: "unicode utf16 rotation", session_id: "emoji-🚀-session", chunk_start: 7, count: 4 },
+    { label: "default rotation a", session_id: "rot-a", chunk_start: 0, count: 3 },
+    { label: "default rotation b", session_id: "rot-b", chunk_start: 1, count: 3 },
+    { label: "unicode utf16 rotation", session_id: "emoji-🚀-session", chunk_start: 7, count: 3 },
     { label: "flat fallback count above band guard", session_id: "fallback", chunk_start: 12345, count: 25 },
 ];
 
@@ -367,7 +369,7 @@ const promptCases: PromptCase[] = promptCaseSpecs.map((spec) => {
     });
     return {
         ...spec,
-        selected_seed_indices: selectedSeedIndices(spec.session_id, spec.chunk_start, 4),
+        selected_seed_indices: selectedSeedIndices(spec.session_id, spec.chunk_start, 3),
         seed_examples: refs.seedExamples,
         session_references: refs.sessionReferences,
         project_memory: projectMemory,
@@ -376,7 +378,7 @@ const promptCases: PromptCase[] = promptCaseSpecs.map((spec) => {
 });
 
 const distinctDefaultSelections = new Set(
-    seedCases.filter((c) => c.count === 4).map((c) => JSON.stringify(c.selected_indices)),
+    seedCases.filter((c) => c.count === 3).map((c) => JSON.stringify(c.selected_indices)),
 );
 if (distinctDefaultSelections.size <= 1) {
     throw new Error("seed rotation cases are vacuous; distinct inputs produced the same selection");
@@ -394,7 +396,38 @@ if (!promptCases.some((c) => c.project_memory.length > 0)) {
     throw new Error("prompt cases never emitted project memory");
 }
 
-const golden = { seed_cases: seedCases, prompt_cases: promptCases };
+// Boundary scores, clustered histories and Unicode ids pin band choice, tie
+// rotation, no-content exclusion and every fitting suffix in both languages.
+const referenceSpecs = [
+    { label: "mixed recent bands", scores: [1, 9, 10, 29, 30, 59, 60, 84, 85, 100, 70, 90, 70, 90] },
+    { label: "all bands covered", scores: [5, 20, 40, 70, 90, 5, 20, 40, 70, 90, 5, 20, 40, 70] },
+    { label: "history lacks low bands", scores: [40, 70, 90, 40, 70, 90, 70, 70, 70, 70] },
+    { label: "one older band", scores: [...Array(20).fill(40), 70, 70, 70, 70] },
+    { label: "no-content gaps", scores: [5, 20, 40, 70, 90, 50, 70, 90], markers: true },
+    ...Array.from({ length: 6 }, (_, count) => ({ label: `young ${count}`, scores: Array(count).fill(50) })),
+];
+const referenceCases = referenceSpecs.map((spec, caseIndex) => {
+    const session_id = "calibration-🚀";
+    const chunk_start = 42 + caseIndex;
+    const session_compartments: ReferenceCompartmentJson[] = spec.scores.map((importance, i) => ({
+        start_message: i * 10 + 1, end_message: i * 10 + 10,
+        title: `Compartment ${i}`, content: `Body & <${i}>`, importance, episode_type: "feature",
+    }));
+    if ("markers" in spec && spec.markers) {
+        for (const at of [session_compartments.length, 4, 0]) session_compartments.splice(at, 0, {
+            start_message: 999, end_message: 999, title: "", content: "", importance: 1,
+        });
+    }
+    const seeds = selectSeeds(session_id, chunk_start);
+    const selected = selectSessionReferences(session_compartments.map(toTsCompartment), seeds, session_id, chunk_start);
+    return {
+        label: spec.label, session_id, chunk_start, session_compartments,
+        seed_examples: renderSeedExamplesBlock(seeds),
+        selected_starts: selected.map((c) => c.startMessage),
+        windows: Array.from({ length: 8 }, (_, window) => ({ window, block: renderSessionReferencesBlock(selected, window) })),
+    };
+});
+const golden = { seed_cases: seedCases, prompt_cases: promptCases, reference_cases: referenceCases };
 const rendered = `${JSON.stringify(golden, null, 2)}\n`;
 const outPath = join(import.meta.dir, "..", "testdata", "historian-prompt-golden.json");
 
@@ -408,8 +441,8 @@ if (process.argv.includes("--check")) {
         console.error(`historian prompt golden drifted; regenerate ${outPath}`);
         process.exit(1);
     }
-    console.log(`historian prompt golden up to date: ${outPath}`);
+    console.log(`historian prompt golden up to date: ${promptCases.length} prompts, ${seedCases.length} seeds, ${referenceCases.length} reference selections: ${outPath}`);
 } else {
     writeFileSync(outPath, rendered);
-    console.log(`wrote ${promptCases.length} historian prompt cases + ${seedCases.length} seed cases → ${outPath}`);
+    console.log(`wrote ${promptCases.length} prompts + ${seedCases.length} seed cases + ${referenceCases.length} reference selections → ${outPath}`);
 }

crates/mc-module/src/historian_chunk.rs

@@ -20,7 +20,7 @@ use crate::historian::{
 use crate::historian_prompt::{
     build_compartment_agent_prompt, order_historian_memories, render_historian_memory_block,
     render_seed_examples_block, render_session_references_block_window, select_seeds,
-    CompartmentPromptInputs, ReferenceCompartment, SEED_FLOOR, SESSION_REF_WINDOW,
+    select_session_references, CompartmentPromptInputs, ReferenceCompartment, SEED_FLOOR,
 };
 use crate::historian_validate::{
     ChunkLine, HistorianChunk, MessageRange, StoredCompartmentRange, ValidateOptions,
@@ -846,19 +846,26 @@ struct HistorianPromptFitInput<'a> {
 
 /// Size the historian prompt to the producer window: reserve the system prompt,
 /// the fixed user-prompt blocks and the output first, and give the chunk what
-/// remains. When the full requested chunk does not fit, trim recent compartments
-/// (oldest first), then project-memory lines (lowest priority first), then seed
+/// remains. When the full requested chunk does not fit, trim diverse older
+/// compartments before recent compartments (oldest first), then project-memory
+/// lines (lowest priority first), then seed
 /// examples, and only then shrink the chunk. When not even a minimal chunk fits,
 /// the untrimmed blocks are returned so the firing's admission check refuses the
 /// prompt and records the failure with a backoff. Untrimmed blocks are
 /// byte-identical to the ones the prompt golden pins.
 fn fit_historian_prompt(input: &HistorianPromptFitInput<'_>) -> HistorianPromptFit {
     let seeds = select_seeds(input.session_id, input.chunk_start as i64, SEED_FLOOR);
+    let references = select_session_references(
+        input.compartments,
+        &seeds,
+        input.session_id,
+        input.chunk_start as i64,
+    );
     let memories = order_historian_memories(input.memories);
     let render = |refs: usize, memory_count: usize, seed_count: usize| {
         (
             render_seed_examples_block(&seeds[..seed_count]),
-            render_session_references_block_window(input.compartments, refs),
+            render_session_references_block_window(&references, refs),
             render_historian_memory_block(&memories[..memory_count]),
         )
     };
@@ -871,14 +878,14 @@ fn fit_historian_prompt(input: &HistorianPromptFitInput<'_>) -> HistorianPromptF
             session_references,
             memory_block,
             kept: (refs, memory_count, seed_count),
-            trimmed: refs < SESSION_REF_WINDOW
+            trimmed: refs < references.len()
                 || memory_count < memories.len()
                 || seed_count < seeds.len(),
         }
     };
     let untrimmed = || {
         accept(
-            SESSION_REF_WINDOW,
+            references.len(),
             memories.len(),
             seeds.len(),
             input.requested,
@@ -938,8 +945,8 @@ fn fit_historian_prompt(input: &HistorianPromptFitInput<'_>) -> HistorianPromptF
         room(refs, memory_count, seed_count).is_some_and(|room| room >= input.requested)
     };
 
-    // 1. Recent compartments, oldest dropped first.
-    for refs in (0..=SESSION_REF_WINDOW).rev() {
+    // 1. Diverse compartments first, then recent compartments oldest first.
+    for refs in (0..=references.len()).rev() {
         if has_room(refs, memories.len(), seeds.len()) {
             return accept(refs, memories.len(), seeds.len(), input.requested);
         }
@@ -2392,9 +2399,10 @@ mod tests {
             "producer must receive the whole formatted component"
         );
         let prompt_hash = format!("{:x}", sha2::Sha256::digest(firing.prompt.as_bytes()));
+        // Calibration uses three seeds; the transcript component itself is unchanged.
         assert_eq!(
             prompt_hash,
-            "90e949d5ecab64b27a84497213d8aa03b450b025d2bf301e0d61593d98f2de27"
+            "1b08d1670ba7beb7434d8d8140a74d7037b9a271c31088b731b3326786f76e5c"
         );
         let validated = crate::historian_validate::validate_historian_output(
             &historian_output(1, 3, 4),
@@ -3439,10 +3447,74 @@ mod prompt_fit_tests {
         let (fit, limit, sent) = fit_with(1_000_000, 8_000, &memories, &compartments);
         assert!(!fit.trimmed);
         assert_eq!(fit.chunk_tokens, 10_000);
-        assert_eq!(fit.kept, (SESSION_REF_WINDOW, 300, SEED_FLOOR));
+        assert_eq!(fit.kept, (compartments.len(), 300, SEED_FLOOR));
         assert!(sent <= limit as f64);
     }
 
+    #[test]
+    fn fit_drops_diverse_before_recent_and_oldest_recent_first() {
+        let mut compartments = compartments();
+        // Twelve distinct rows give three diverse older examples and four recent.
+        while compartments.len() < 12 {
+            let i = compartments.len();
+            let mut row = compartments[0].clone();
+            row.start_message = i as i64 * 10 + 1;
+            row.end_message = i as i64 * 10 + 10;
+            row.title = format!("Compartment {i}");
+            compartments.push(row);
+        }
+        let seeds = select_seeds("ses-fit", 61, SEED_FLOOR);
+        let refs = select_session_references(&compartments, &seeds, "ses-fit", 61);
+        assert_eq!(refs.len(), 7);
+        let seed = DecisionCalibration::for_model(Some(MODEL));
+        let system_tokens =
+            estimate_tokens(crate::historian_prompt::HISTORIAN_SYSTEM_PROMPT) as f64;
+        for remaining in [6, 4, 3] {
+            let expected = render_session_references_block_window(&refs, remaining);
+            let prompt = build_compartment_agent_prompt(&CompartmentPromptInputs {
+                seed_examples: &render_seed_examples_block(&seeds),
+                session_references: &expected,
+                project_memory: "",
+                input_source: "Messages 61-400:\n\n",
+                memory_enabled: true,
+                extraction_free: false,
+            });
+            let limit = seed
+                .provider_mass(
+                    LocalMass {
+                        system: system_tokens,
+                        prose: (estimate_tokens(&prompt) + 10_000 + PROMPT_FIT_SLACK_TOKENS) as f64,
+                        tools: 0.0,
+                    },
+                    true,
+                )
+                .ceil() as usize;
+            let fit = fit_historian_prompt(&HistorianPromptFitInput {
+                session_id: "ses-fit",
+                chunk_start: 61,
+                last_ordinal: 400,
+                compartments: &compartments,
+                memories: &[],
+                memory_enabled: true,
+                extraction_free: false,
+                limit: Some(limit),
+                seed: &seed,
+                system_tokens,
+                requested: 10_000,
+            });
+            assert_eq!(fit.kept, (remaining, 0, 3));
+            assert_eq!(fit.session_references, expected);
+            for i in (12 - remaining.min(4))..12 {
+                assert!(fit
+                    .session_references
+                    .contains(&format!("title=\"Compartment {i}\"")));
+            }
+            if remaining == 3 {
+                assert!(!fit.session_references.contains("title=\"Compartment 8\""));
+            }
+        }
+    }
+
     #[test]
     fn trims_references_then_memory_so_the_requested_chunk_fits() {
         let memories = memories(300);
@@ -3453,8 +3525,13 @@ mod prompt_fit_tests {
         let full = build_compartment_agent_prompt(&CompartmentPromptInputs {
             seed_examples: &render_seed_examples_block(&select_seeds("ses-fit", 61, SEED_FLOOR)),
             session_references: &render_session_references_block_window(
-                &compartments,
-                SESSION_REF_WINDOW,
+                &select_session_references(
+                    &compartments,
+                    &select_seeds("ses-fit", 61, SEED_FLOOR),
+                    "ses-fit",
+                    61,
+                ),
+                crate::historian_prompt::SESSION_REF_LIMIT,
             ),
             project_memory: &render_historian_memory_block(&memories),
             input_source: "Messages 61-400:\n\n",