deepstrike 0.2.80__tar.gz → 0.2.82__tar.gz

{deepstrike-0.2.80 → deepstrike-0.2.82}/Cargo.lock

@@ -293,7 +293,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-core"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "compact_str",
  "deepstrike-tokenizer",
@@ -307,7 +307,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-lab"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "serde",
  "serde_json",
@@ -315,7 +315,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-node"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-py"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -338,7 +338,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-sdk"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -376,7 +376,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-tokenizer"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "pretty_assertions",
  "tiktoken-rs",
@@ -384,7 +384,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-wasm"
-version = "0.2.80"
+version = "0.2.82"
 dependencies = [
  "compact_str",
  "deepstrike-core",

{deepstrike-0.2.80 → deepstrike-0.2.82}/Cargo.toml

@@ -3,13 +3,13 @@ resolver = "2"
 members = ["crates/deepstrike-core", "crates/deepstrike-tokenizer", "crates/deepstrike-py"]
 
 [workspace.package]
-version = "0.2.80"
+version = "0.2.82"
 edition = "2024"
 repository = "https://github.com/kongusen/deepstrike"
 
 [workspace.dependencies]
-deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.80" }
-deepstrike-tokenizer = { path = "crates/deepstrike-tokenizer", version = "0.2.80" }
+deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.82" }
+deepstrike-tokenizer = { path = "crates/deepstrike-tokenizer", version = "0.2.82" }
 notify = "6"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{deepstrike-0.2.80 → deepstrike-0.2.82}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepstrike
-Version: 0.2.80
+Version: 0.2.82
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: anyio>=4.0

deepstrike-0.2.82/crates/deepstrike-core/src/context/cache_ledger.rs

@@ -0,0 +1,383 @@
+//! Plan task 8.0 · the cache ledger: where each provider request broke the previous request's
+//! cacheable prefix, how many tokens that cost, and why.
+//!
+//! A provider caches a request as one prefix: tool schemas, then system[0], system[1], then the
+//! history turns. The volatile state turn is the uncached tail and is left out. Every time a
+//! request goes out the kernel fingerprints that prefix segment by segment and compares it with the
+//! previous request. The first segment that differs is a **prefix break**: every token the previous
+//! request held after it has to be sent uncached again. The ledger records the break (turn, cause,
+//! tokens kept before it, tokens lost after it) and sums the losses into the lifecycle report's
+//! `cache_loss_tokens`.
+//!
+//! The cause comes from the change that made the break. Compaction, renewal, provider rewrites,
+//! tool-result collapse and knowledge promotion announce themselves ([`CacheLedger::note_cause`]);
+//! an unannounced break is classified from the render itself: a dropped item is a budget drop, an
+//! item re-rendered as the narration stub is narration collapse, and a different toolset is a
+//! toolset change.
+//!
+//! The state turn after the history is rebuilt every request, so the previous request's state turn
+//! is never reusable: that is not a break, but a provider's count of uncached input includes it.
+//! The ledger sums it separately as `tail_tokens`, so measured cache loss can be compared with the
+//! kernel's.
+//!
+//! Everything here is derived from the rendered request, so a replay rebuilds the same ledger; it
+//! travels in the checkpoint so a restored run keeps comparing against the request it last sent.
+
+use std::collections::VecDeque;
+
+use serde::{Deserialize, Serialize};
+
+use crate::context::fault::stable_hash;
+use crate::context::item::{HISTORY_ITEM_DETAIL_CAP, ItemId};
+
+/// Prefix breaks the ledger lists one by one; older ones are only counted.
+pub const PREFIX_BREAK_DETAIL_CAP: usize = HISTORY_ITEM_DETAIL_CAP;
+
+/// Why a request's cacheable prefix differs from the previous request's.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum BreakCause {
+    /// The tool schemas changed (a skill narrowed or widened the toolset, a meta tool appeared).
+    Toolset,
+    /// system[0] changed.
+    System,
+    /// system[1] changed outside a compaction: staged knowledge promoted, or a boundary sweep.
+    Promotion,
+    /// Older tool results collapsed to previews under pressure.
+    Collapse,
+    /// An item re-rendered in place without an announced cause (a page-in, a page-out).
+    Reprojection,
+    /// Old assistant narration left the protected window and rendered as the narration stub.
+    Narration,
+    /// The renderer dropped the oldest history over the input budget.
+    BudgetDrop,
+    Snip,
+    Micro,
+    Auto,
+    Renewal,
+    /// The provider compacted or cleared context server-side.
+    Provider,
+    /// History rolled back, or anything else.
+    Other,
+}
+
+impl BreakCause {
+    /// The cause a compaction tier announces.
+    pub fn of_compaction(action: crate::context::pressure::PressureAction) -> Self {
+        use crate::context::pressure::PressureAction;
+        match action {
+            PressureAction::SnipCompact => Self::Snip,
+            PressureAction::MicroCompact => Self::Micro,
+            PressureAction::ContextCollapse => Self::Collapse,
+            PressureAction::AutoCompact => Self::Auto,
+            PressureAction::None => Self::Other,
+        }
+    }
+}
+
+/// One prefix break, attributed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PrefixBreak {
+    /// The turn of the request that broke the prefix.
+    pub turn: u32,
+    pub cause: BreakCause,
+    /// Tokens of the previous request's prefix still byte-identical (still cacheable).
+    pub kept_tokens: u32,
+    /// Tokens of the previous request's prefix after the break: sent uncached again.
+    pub lost_tokens: u32,
+}
+
+/// The fingerprint and size of one prefix segment.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Segment {
+    /// FNV-1a 64 of the segment's wire material, as 16 hex digits (a string, so a JSON host that
+    /// reads numbers as doubles cannot round it).
+    pub hash: String,
+    pub tokens: u32,
+}
+
+impl Segment {
+    pub fn of(material: &[u8], tokens: u32) -> Self {
+        Self {
+            hash: format!("{:016x}", stable_hash(material)),
+            tokens,
+        }
+    }
+}
+
+/// One history turn of a sent request.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SentTurn {
+    #[serde(flatten)]
+    pub segment: Segment,
+    /// The history item the turn rendered; 0 for a synthetic turn.
+    #[serde(default)]
+    pub item: ItemId,
+    /// The turn rendered as the narration stub.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub stub: bool,
+}
+
+/// The cacheable prefix of one sent request.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SentPrefix {
+    pub tools: Segment,
+    pub system: Segment,
+    pub knowledge: Segment,
+    #[serde(default)]
+    pub turns: Vec<SentTurn>,
+    /// The uncached state turn after the turns.
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u32")]
+    pub tail: u32,
+}
+
+impl SentPrefix {
+    fn header_tokens(&self) -> u32 {
+        self.tools
+            .tokens
+            .saturating_add(self.system.tokens)
+            .saturating_add(self.knowledge.tokens)
+    }
+
+    fn total_tokens(&self) -> u32 {
+        self.turns
+            .iter()
+            .fold(self.header_tokens(), |sum, turn| sum.saturating_add(turn.segment.tokens))
+    }
+
+    /// The tokens a turn with this hash had in this request, to avoid recounting it.
+    pub fn tokens_of(&self, hash: &str) -> Option<u32> {
+        self.turns
+            .iter()
+            .find(|turn| turn.segment.hash == hash)
+            .map(|turn| turn.segment.tokens)
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CacheLedger {
+    /// The prefix of the last request sent.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sent: Option<SentPrefix>,
+    /// The announced cause of a rewrite since the last request.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pending: Option<BreakCause>,
+    /// The latest breaks, oldest first.
+    #[serde(default, skip_serializing_if = "VecDeque::is_empty")]
+    pub breaks: VecDeque<PrefixBreak>,
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u32")]
+    pub breaks_omitted: u32,
+    /// Lost tokens summed over every break of the run.
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u64")]
+    pub lost_tokens: u64,
+    /// The state-turn tokens of every request a later request followed: never reusable, so not a
+    /// break, but part of what a provider counts as uncached.
+    #[serde(default, skip_serializing_if = "crate::context::item::is_zero_u64")]
+    pub tail_tokens: u64,
+}
+
+impl CacheLedger {
+    /// A rewrite with `cause` happened; the next request's break, if it has one, is attributed to
+    /// it. The first cause announced since the last request is kept: later rewrites in the same
+    /// interval (a boundary sweep a compaction triggered) follow from it.
+    pub fn note_cause(&mut self, cause: BreakCause) {
+        self.pending.get_or_insert(cause);
+    }
+
+    /// The request with prefix `next` is being sent on `turn`. Compares it with the last request,
+    /// records the break if there is one, and returns it.
+    pub fn observe(&mut self, turn: u32, next: SentPrefix) -> Option<PrefixBreak> {
+        let pending = self.pending.take();
+        self.tail_tokens += self.sent.as_ref().map_or(0, |prev| u64::from(prev.tail));
+        let found = self.sent.as_ref().and_then(|prev| find_break(prev, &next, pending));
+        self.sent = Some(next);
+        let found = found.map(|(cause, kept_tokens, lost_tokens)| PrefixBreak {
+            turn,
+            cause,
+            kept_tokens,
+            lost_tokens,
+        })?;
+        self.lost_tokens += u64::from(found.lost_tokens);
+        self.breaks.push_back(found);
+        if self.breaks.len() > PREFIX_BREAK_DETAIL_CAP {
+            self.breaks.pop_front();
+            self.breaks_omitted += 1;
+        }
+        Some(found)
+    }
+}
+
+/// Where `next` stops reusing `prev`, why, and the (kept, lost) tokens of `prev`'s prefix.
+fn find_break(
+    prev: &SentPrefix,
+    next: &SentPrefix,
+    pending: Option<BreakCause>,
+) -> Option<(BreakCause, u32, u32)> {
+    let total = prev.total_tokens();
+    let lost = |kept: u32| total.saturating_sub(kept);
+    if prev.tools.hash != next.tools.hash {
+        return Some((BreakCause::Toolset, 0, total)).filter(|_| total > 0);
+    }
+    if prev.system.hash != next.system.hash {
+        let kept = prev.tools.tokens;
+        return Some((pending.unwrap_or(BreakCause::System), kept, lost(kept)));
+    }
+    if prev.knowledge.hash != next.knowledge.hash {
+        let kept = prev.tools.tokens.saturating_add(prev.system.tokens);
+        return Some((pending.unwrap_or(BreakCause::Promotion), kept, lost(kept)));
+    }
+    let same = prev
+        .turns
+        .iter()
+        .zip(&next.turns)
+        .take_while(|(a, b)| a.segment.hash == b.segment.hash)
+        .count();
+    if same == prev.turns.len() {
+        return None;
+    }
+    let kept = prev.turns[..same]
+        .iter()
+        .fold(prev.header_tokens(), |sum, turn| sum.saturating_add(turn.segment.tokens));
+    let lost = lost(kept);
+    if lost == 0 {
+        return None;
+    }
+    let cause = pending.unwrap_or_else(|| classify(&prev.turns[same], next, same));
+    Some((cause, kept, lost))
+}
+
+/// An unannounced turn break: what happened to the first turn that no longer matches.
+fn classify(prev: &SentTurn, next: &SentPrefix, at: usize) -> BreakCause {
+    if prev.item != 0 && !next.turns.iter().any(|turn| turn.item == prev.item) {
+        return BreakCause::BudgetDrop;
+    }
+    match next.turns.get(at) {
+        Some(turn) if turn.item == prev.item && turn.stub && !prev.stub => BreakCause::Narration,
+        Some(turn) if turn.item == prev.item && turn.item != 0 => BreakCause::Reprojection,
+        _ => BreakCause::Other,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn seg(name: &str, tokens: u32) -> Segment {
+        Segment::of(name.as_bytes(), tokens)
+    }
+
+    fn turn(name: &str, item: ItemId, tokens: u32) -> SentTurn {
+        SentTurn {
+            segment: seg(name, tokens),
+            item,
+            stub: false,
+        }
+    }
+
+    fn prefix(turns: Vec<SentTurn>) -> SentPrefix {
+        SentPrefix {
+            tools: seg("tools", 100),
+            system: seg("system", 50),
+            knowledge: seg("knowledge", 20),
+            turns,
+            tail: 7,
+        }
+    }
+
+    #[test]
+    fn an_appended_request_breaks_nothing() {
+        let mut ledger = CacheLedger::default();
+        assert_eq!(ledger.observe(1, prefix(vec![turn("a", 1, 10)])), None);
+        let next = prefix(vec![turn("a", 1, 10), turn("b", 2, 30)]);
+        assert_eq!(ledger.observe(2, next), None);
+        assert_eq!(ledger.lost_tokens, 0);
+        assert_eq!(ledger.tail_tokens, 7, "the first request's state turn was not reusable");
+    }
+
+    #[test]
+    fn a_dropped_oldest_turn_is_a_budget_drop() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10), turn("b", 2, 30)]));
+        let found = ledger.observe(2, prefix(vec![turn("b", 2, 30), turn("c", 3, 5)]));
+        assert_eq!(
+            found,
+            Some(PrefixBreak {
+                turn: 2,
+                cause: BreakCause::BudgetDrop,
+                kept_tokens: 170,
+                lost_tokens: 40,
+            })
+        );
+        assert_eq!(ledger.lost_tokens, 40);
+    }
+
+    #[test]
+    fn a_turn_rendered_as_the_stub_is_narration() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10), turn("b", 2, 30)]));
+        let mut stub = turn("stub", 1, 4);
+        stub.stub = true;
+        let found = ledger.observe(2, prefix(vec![stub, turn("b", 2, 30)])).unwrap();
+        assert_eq!(found.cause, BreakCause::Narration);
+        assert_eq!((found.kept_tokens, found.lost_tokens), (170, 40));
+    }
+
+    #[test]
+    fn an_announced_cause_wins_and_is_spent_by_one_request() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        ledger.note_cause(BreakCause::Auto);
+        ledger.note_cause(BreakCause::Promotion);
+        let found = ledger.observe(2, prefix(vec![turn("summary", 5, 3)])).unwrap();
+        assert_eq!(found.cause, BreakCause::Auto);
+        // A compaction that broke nothing leaves no cause behind for a later break.
+        ledger.note_cause(BreakCause::Snip);
+        assert_eq!(ledger.observe(3, prefix(vec![turn("summary", 5, 3)])), None);
+        assert_eq!(ledger.pending, None);
+    }
+
+    #[test]
+    fn a_new_toolset_loses_the_whole_prefix() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        let mut next = prefix(vec![turn("a", 1, 10)]);
+        next.tools = seg("narrowed", 60);
+        let found = ledger.observe(2, next).unwrap();
+        assert_eq!(found.cause, BreakCause::Toolset);
+        assert_eq!((found.kept_tokens, found.lost_tokens), (0, 180));
+    }
+
+    #[test]
+    fn changed_knowledge_is_a_promotion_unless_announced() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        let mut next = prefix(vec![turn("a", 1, 10)]);
+        next.knowledge = seg("promoted", 40);
+        let found = ledger.observe(2, next).unwrap();
+        assert_eq!(found.cause, BreakCause::Promotion);
+        assert_eq!((found.kept_tokens, found.lost_tokens), (150, 30));
+    }
+
+    #[test]
+    fn the_detail_is_capped_but_the_total_is_not() {
+        let mut ledger = CacheLedger::default();
+        for round in 0..(PREFIX_BREAK_DETAIL_CAP as u32 + 3) {
+            let name = format!("t{round}");
+            ledger.observe(round, prefix(vec![turn(&name, u64::from(round) + 1, 10)]));
+        }
+        assert_eq!(ledger.breaks.len(), PREFIX_BREAK_DETAIL_CAP);
+        assert_eq!(ledger.breaks_omitted, 2);
+        assert_eq!(ledger.lost_tokens, 10 * (PREFIX_BREAK_DETAIL_CAP as u64 + 2));
+    }
+
+    #[test]
+    fn the_ledger_round_trips_through_json() {
+        let mut ledger = CacheLedger::default();
+        ledger.observe(1, prefix(vec![turn("a", 1, 10)]));
+        ledger.observe(2, prefix(vec![turn("b", 2, 10)]));
+        ledger.note_cause(BreakCause::Renewal);
+        let json = serde_json::to_string(&ledger).unwrap();
+        assert_eq!(serde_json::from_str::<CacheLedger>(&json).unwrap(), ledger);
+    }
+}

{deepstrike-0.2.80 → deepstrike-0.2.82}/crates/deepstrike-core/src/context/config.rs

@@ -103,6 +103,10 @@ pub struct ContextConfig {
     /// The provider compacts natively, so the kernel runs neither context collapse nor auto-compact.
     /// Renewal is never delegated: it is decided on the full local history and stays the safety net.
     pub delegate_compaction: bool,
+
+    // ── Notes (plan task 9.1) ───────────────────────────────────────────────
+    /// Tokens the model's notes may hold in the state turn. `0` turns the `note` tool off.
+    pub notes_budget_tokens: u32,
 }
 
 impl Default for ContextConfig {
@@ -127,6 +131,7 @@ impl Default for ContextConfig {
             knowledge_budget_ratio: 0.25,
             delegate_tool_result_clearing: false,
             delegate_compaction: false,
+            notes_budget_tokens: 0,
         }
     }
 }

{deepstrike-0.2.80 → deepstrike-0.2.82}/crates/deepstrike-core/src/context/fault.rs

@@ -11,8 +11,8 @@ pub enum ContextFault {
     InvalidReplay { turn: u32, reason: String },
 }
 
-/// FNV-1a 64-bit — the render layer's cache-stability test fingerprint dialect.
-#[cfg(test)]
+/// FNV-1a 64-bit — the render layer's cache-stability fingerprint dialect (the render tests and
+/// the plan task 8.0 cache ledger).
 pub(crate) fn stable_hash(bytes: &[u8]) -> u64 {
     let mut hash = 0xcbf29ce484222325u64;
     for byte in bytes {

deepstrike-0.2.82/crates/deepstrike-core/src/context/graph.rs

@@ -0,0 +1,147 @@
+//! Plan task 7.1 · the item graph: typed, directed edges between the items of one operation.
+//!
+//! The item table says what each item is; the graph says how items relate: which call a tool result
+//! answers, which history item referenced which knowledge item and by what evidence, what a read
+//! brought back, what a provider summary covers. Edges are recorded from committed input only (D1),
+//! so a replay rebuilds the same graph, and they travel in the checkpoint.
+//!
+//! The graph is bounded. An edge whose two ends are both still resident is always kept; of the
+//! edges that touch an item which has left, only the latest [`RETIRED_EDGE_CAP`] are kept and the
+//! rest are counted in [`ItemGraph::omitted`]. In 0.2.81 the graph only reports: no decision reads it.
+
+use std::collections::BTreeSet;
+
+use crate::context::item::{ExternalEdge, HISTORY_ITEM_DETAIL_CAP, ItemEdge, ItemId};
+
+/// Edges touching a retired item that the graph keeps, newest last.
+pub const RETIRED_EDGE_CAP: usize = HISTORY_ITEM_DETAIL_CAP;
+
+/// Edges the graph holds before it prunes against residency.
+pub const EDGE_PRUNE_AT: usize = 1024;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ItemGraph {
+    edges: Vec<ItemEdge>,
+    omitted: u32,
+    /// Plan task 7.4 · edges to items of other runs, the latest [`RETIRED_EDGE_CAP`] kept.
+    external: Vec<ExternalEdge>,
+}
+
+impl ItemGraph {
+    /// Record `edge` unless it is degenerate (an untracked end, a self-loop) or already recorded.
+    /// Returns whether it was added.
+    pub fn add(&mut self, edge: ItemEdge) -> bool {
+        if edge.from == 0 || edge.to == 0 || edge.from == edge.to {
+            return false;
+        }
+        if self
+            .edges
+            .iter()
+            .any(|e| e.from == edge.from && e.to == edge.to && e.relation == edge.relation)
+        {
+            return false;
+        }
+        self.edges.push(edge);
+        true
+    }
+
+    /// Whether the graph has grown past [`EDGE_PRUNE_AT`] and should be pruned.
+    pub fn over_limit(&self) -> bool {
+        self.edges.len() > EDGE_PRUNE_AT
+    }
+
+    /// Keep every edge whose ends are both in `resident`, and the latest [`RETIRED_EDGE_CAP`] of
+    /// the others; count what is dropped. If resident edges alone still exceed
+    /// [`EDGE_PRUNE_AT`], the oldest go too.
+    pub fn prune(&mut self, resident: &BTreeSet<ItemId>) {
+        let live = |edge: &ItemEdge| resident.contains(&edge.from) && resident.contains(&edge.to);
+        let retired = self.edges.iter().filter(|edge| !live(edge)).count();
+        let mut drop_retired = retired.saturating_sub(RETIRED_EDGE_CAP);
+        let before = self.edges.len();
+        self.edges.retain(|edge| {
+            if live(edge) || drop_retired == 0 {
+                return true;
+            }
+            drop_retired -= 1;
+            false
+        });
+        let overflow = self.edges.len().saturating_sub(EDGE_PRUNE_AT);
+        self.edges.drain(..overflow);
+        self.omitted = self.omitted.saturating_add((before - self.edges.len()) as u32);
+    }
+
+    /// Record an edge to another run's item; the oldest goes past [`RETIRED_EDGE_CAP`].
+    pub fn add_external(&mut self, edge: ExternalEdge) -> bool {
+        if edge.from == 0 || self.external.contains(&edge) {
+            return false;
+        }
+        self.external.push(edge);
+        if self.external.len() > RETIRED_EDGE_CAP {
+            self.external.remove(0);
+            self.omitted = self.omitted.saturating_add(1);
+        }
+        true
+    }
+
+    pub fn external(&self) -> &[ExternalEdge] {
+        &self.external
+    }
+
+    pub fn edges(&self) -> &[ItemEdge] {
+        &self.edges
+    }
+
+    /// Edges dropped by pruning over the run.
+    pub fn omitted(&self) -> u32 {
+        self.omitted
+    }
+
+    /// The recorded edges into `to`.
+    pub fn in_edges(&self, to: ItemId) -> impl Iterator<Item = &ItemEdge> {
+        self.edges.iter().filter(move |edge| edge.to == to)
+    }
+
+    /// Rebuild from a checkpoint.
+    pub fn restore(&mut self, edges: Vec<ItemEdge>, external: Vec<ExternalEdge>, omitted: u32) {
+        self.edges = edges;
+        self.external = external;
+        self.omitted = omitted;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::context::item::Relation;
+
+    fn edge(from: ItemId, to: ItemId) -> ItemEdge {
+        ItemEdge { from, to, relation: Relation::ReferencesLexical, turn: 0 }
+    }
+
+    #[test]
+    fn degenerate_and_repeated_edges_are_not_recorded() {
+        let mut graph = ItemGraph::default();
+        assert!(!graph.add(edge(0, 3)));
+        assert!(!graph.add(edge(3, 3)));
+        assert!(graph.add(edge(4, 3)));
+        assert!(!graph.add(edge(4, 3)));
+        assert!(graph.add(ItemEdge { relation: Relation::ReferencesStrong, ..edge(4, 3) }));
+        assert_eq!(graph.in_edges(3).count(), 2);
+    }
+
+    #[test]
+    fn pruning_keeps_resident_edges_and_the_latest_retired_ones() {
+        let mut graph = ItemGraph::default();
+        let total = RETIRED_EDGE_CAP as u64 + 5;
+        for from in 1..=total {
+            graph.add(edge(from + 1000, 1));
+        }
+        graph.add(edge(2, 3));
+        let resident = BTreeSet::from([2, 3]);
+        graph.prune(&resident);
+        assert_eq!(graph.omitted(), 5);
+        assert_eq!(graph.edges().len(), RETIRED_EDGE_CAP + 1);
+        assert_eq!(graph.edges()[0].from, 1006, "the oldest retired edges go first");
+        assert!(graph.edges().contains(&edge(2, 3)));
+    }
+}