deepstrike 0.2.35__tar.gz → 0.2.36__tar.gz

{deepstrike-0.2.35 → deepstrike-0.2.36}/Cargo.lock

@@ -194,7 +194,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-core"
-version = "0.2.35"
+version = "0.2.36"
 dependencies = [
  "compact_str",
  "pretty_assertions",
@@ -206,7 +206,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-node"
-version = "0.2.35"
+version = "0.2.36"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -218,7 +218,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-py"
-version = "0.2.35"
+version = "0.2.36"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -229,7 +229,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-sdk"
-version = "0.2.35"
+version = "0.2.36"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -263,7 +263,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-wasm"
-version = "0.2.35"
+version = "0.2.36"
 dependencies = [
  "compact_str",
  "deepstrike-core",

{deepstrike-0.2.35 → deepstrike-0.2.36}/Cargo.toml

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

{deepstrike-0.2.35 → deepstrike-0.2.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepstrike
-Version: 0.2.35
+Version: 0.2.36
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: anyio>=4.0
@@ -149,7 +149,7 @@ The mechanisms above are not internal refactors — they change what you can bui
 Tool calls, spawns, compression, and signals pass through one kernel gate with an explicit lifecycle (Ready / Running / Blocked / Suspended). You implement I/O; the kernel decides *when* and *whether*. Node, Python, and Rust share the same decision path, so `wake(session_id)` and cross-language tooling see consistent behavior.
 
 **Longer, sturdier sessions (Layer-1 spool + semantic page-out)**  
-Oversized tool results (> 50 KB) stay in context as a preview plus a `.spool/` reference — the model reads the full payload on demand via ordinary file tools. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore` and satisfies `page_in_requested` on the way back in. Long tasks survive token pressure instead of failing mid-run.
+Oversized tool results (> 50 KB) stay in context as a preview plus a `.spool/` reference — the model reads the full payload on demand via ordinary file tools. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore`. Long tasks survive token pressure instead of failing mid-run.
 
 **Safety and governance by default (OS native profile)**  
 Every run loads declarative `governance_policy` (deny / ask_user / rate-limit / param rules) and in-kernel signal routing (`attention_policy`, default queue 64). Dangerous tools, external interrupts, and approval flows are policy — not ad-hoc checks in your handlers.
@@ -443,9 +443,9 @@ effort: 1
 
 ## Knowledge
 
-Implement `KnowledgeSource` — the kernel injects a `knowledge` meta-tool. Runtime retrieval results land in **history** as tool results. Use `initial_memory` for durable preload into Slot 2.
+Implement `KnowledgeSource` — the kernel injects a `knowledge` meta-tool. Runtime retrieval results land in **history** as tool results (single-use fact content that decays with compaction), not in the durable `knowledge` partition. Use `initial_memory` for durable preload into Slot 2.
 
-Before tool execution the kernel may emit `page_in_requested`; the SDK satisfies it from `DreamStore`, `KnowledgeSource`, and a local semantic page-out cache, then feeds `page_in` back to the kernel.
+For durable content at runtime use `runner.push_knowledge(content, key=..., pinned=...)` — a **keyed** entry upserts on a repeated key and `runner.remove_knowledge(key)` removes it, both applied at the next compaction/renewal boundary. `knowledge_budget_ratio` (default 0.25, 0 disables) caps the partition: over budget, the oldest unpinned, non-skill entries are evicted at boundaries while `pinned=True` entries survive. A loaded skill's body is pinned here as `skill:<name>` and unpinned by `runner.deactivate_skill(name)` or a `skill_lease_turns` expiry.
 
 ```python
 from deepstrike import KnowledgeSource

{deepstrike-0.2.35 → deepstrike-0.2.36}/README.md

@@ -136,7 +136,7 @@ The mechanisms above are not internal refactors — they change what you can bui
 Tool calls, spawns, compression, and signals pass through one kernel gate with an explicit lifecycle (Ready / Running / Blocked / Suspended). You implement I/O; the kernel decides *when* and *whether*. Node, Python, and Rust share the same decision path, so `wake(session_id)` and cross-language tooling see consistent behavior.
 
 **Longer, sturdier sessions (Layer-1 spool + semantic page-out)**  
-Oversized tool results (> 50 KB) stay in context as a preview plus a `.spool/` reference — the model reads the full payload on demand via ordinary file tools. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore` and satisfies `page_in_requested` on the way back in. Long tasks survive token pressure instead of failing mid-run.
+Oversized tool results (> 50 KB) stay in context as a preview plus a `.spool/` reference — the model reads the full payload on demand via ordinary file tools. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore`. Long tasks survive token pressure instead of failing mid-run.
 
 **Safety and governance by default (OS native profile)**  
 Every run loads declarative `governance_policy` (deny / ask_user / rate-limit / param rules) and in-kernel signal routing (`attention_policy`, default queue 64). Dangerous tools, external interrupts, and approval flows are policy — not ad-hoc checks in your handlers.
@@ -430,9 +430,9 @@ effort: 1
 
 ## Knowledge
 
-Implement `KnowledgeSource` — the kernel injects a `knowledge` meta-tool. Runtime retrieval results land in **history** as tool results. Use `initial_memory` for durable preload into Slot 2.
+Implement `KnowledgeSource` — the kernel injects a `knowledge` meta-tool. Runtime retrieval results land in **history** as tool results (single-use fact content that decays with compaction), not in the durable `knowledge` partition. Use `initial_memory` for durable preload into Slot 2.
 
-Before tool execution the kernel may emit `page_in_requested`; the SDK satisfies it from `DreamStore`, `KnowledgeSource`, and a local semantic page-out cache, then feeds `page_in` back to the kernel.
+For durable content at runtime use `runner.push_knowledge(content, key=..., pinned=...)` — a **keyed** entry upserts on a repeated key and `runner.remove_knowledge(key)` removes it, both applied at the next compaction/renewal boundary. `knowledge_budget_ratio` (default 0.25, 0 disables) caps the partition: over budget, the oldest unpinned, non-skill entries are evicted at boundaries while `pinned=True` entries survive. A loaded skill's body is pinned here as `skill:<name>` and unpinned by `runner.deactivate_skill(name)` or a `skill_lease_turns` expiry.
 
 ```python
 from deepstrike import KnowledgeSource

{deepstrike-0.2.35 → deepstrike-0.2.36}/crates/deepstrike-core/src/context/config.rs

@@ -83,6 +83,16 @@ pub struct ContextConfig {
 
     /// Preview byte budget kept in context when a tool result is spooled. Default: 2 KiB.
     pub spool_preview_bytes: u32,
+
+    // ── K2: knowledge budget ─────────────────────────────────────────────
+
+    /// Max share of `max_tokens` the knowledge partition may occupy. Exceeding it emits a
+    /// `KnowledgeBudgetExceeded` observation (once per cache generation) and marks the OLDEST
+    /// unpinned, non-skill entries for eviction at the next compaction/renewal boundary until the
+    /// projected usage fits. Pinned entries and `skill:`-keyed pins are never budget-evicted
+    /// (skills are governed by deactivation/lease, not the budget). `0.0` disables (no cap).
+    /// Default: 0.25.
+    pub knowledge_budget_ratio: f64,
 }
 
 fn default_micro_compact_idle_minutes() -> u32 {
@@ -119,6 +129,7 @@ impl Default for ContextConfig {
             autocompact_buffer: 13_000,
             spool_threshold_bytes: 50 * 1024,
             spool_preview_bytes: 2 * 1024,
+            knowledge_budget_ratio: 0.25,
         }
     }
 }

{deepstrike-0.2.35 → deepstrike-0.2.36}/crates/deepstrike-core/src/context/manager.rs

@@ -17,6 +17,8 @@ use compact_str::CompactString;
 
 pub const MEMORY_TOOL_NAME: &str = "memory";
 pub const KNOWLEDGE_TOOL_NAME: &str = "knowledge";
+/// O7: the evicted-result re-fetch meta-tool (see `read_result_tool_schema`).
+pub const READ_RESULT_TOOL_NAME: &str = "read_result";
 
 /// Control-plane meta-tools: kernel-handled tools that drive state/capabilities rather than do task
 /// work. Excluded from the `recent_actions` progress log (2b) so the footer reflects real progress.
@@ -25,11 +27,14 @@ const META_TOOL_NAMES: &[&str] = &[
     "skill",
     MEMORY_TOOL_NAME,
     KNOWLEDGE_TOOL_NAME,
+    READ_RESULT_TOOL_NAME,
     "submit_workflow_nodes",
     "start_workflow",
 ];
 
-fn is_meta_tool(name: &str) -> bool {
+/// Control-plane meta-tools are noise, not task progress — filtered out of the recency log (2b)
+/// and out of the O6 repeat-fuse signature (the two must agree on what "an action" is).
+pub(crate) fn is_meta_tool(name: &str) -> bool {
     META_TOOL_NAMES.contains(&name)
 }
 
@@ -46,11 +51,14 @@ pub struct ContextManager {
     pub sprint: u32,
     pub last_handoff: Option<HandoffArtifact>,
     pub skills: SkillCatalog,
-    /// P1-B tool gating: the set of skills the model has loaded this session (by name). Their
-    /// declared `allowed_tools` are unioned to narrow the exposed toolset in `emit_call_llm`.
-    /// A set (not a single value) because the model may load several skills and still needs each
-    /// one's tools (D1). v1 accumulates (no eviction). Snapshotted for wake/resume.
-    pub active_skills: std::collections::BTreeSet<CompactString>,
+    /// P1-B tool gating: the skills the model has loaded this session (by name), each with an
+    /// optional lease expiry turn (K3: `None` = permanent, today's default). Their declared
+    /// `allowed_tools` are unioned to narrow the exposed toolset in `emit_call_llm`. A map (not a
+    /// single value) because the model may load several skills and still needs each one's tools
+    /// (D1). K3 adds eviction: explicit `deactivate_skill` or lease expiry — both also unpin the
+    /// skill's `skill:<name>` knowledge entry (boundary-swept). NOT snapshotted — rebuilt on wake
+    /// by replaying `skill` tool calls (graceful).
+    pub active_skills: std::collections::BTreeMap<CompactString, Option<u32>>,
     /// P1-B/D stable-core: tool ids that stay exposed even when a skill narrows the toolset (the
     /// "everyone uses these" set — read/search/bash etc.). Configured once by the SDK; empty by
     /// default (铁律: no config ⇒ skills narrow to exactly their declared tools + meta-tools).
@@ -90,6 +98,14 @@ pub struct ContextManager {
     /// compaction (no frozen region yet). Not snapshotted: on resume it resets to 0 and rebuilds at
     /// the next compaction (graceful — only the deep-cache durability lapses, never correctness).
     frozen_history_len: usize,
+
+    /// K1: boundary-sweep results awaiting drain into `KnowledgeSwept` observations. Not
+    /// snapshotted (observation-only bookkeeping, same class as `frozen_history_len`).
+    pending_knowledge_sweeps: Vec<crate::context::partitions::KnowledgeSweep>,
+
+    /// K2: whether the budget warning already fired this cache generation (warn-once; reset by
+    /// the boundary sweep). Not snapshotted — a resume re-warns at most once, harmless.
+    knowledge_budget_warned: bool,
 }
 
 impl ContextManager {
@@ -106,7 +122,7 @@ impl ContextManager {
             partitions, max_tokens, config, engine,
             sprint: 0, last_handoff: None,
             skills: SkillCatalog::new(),
-            active_skills: std::collections::BTreeSet::new(),
+            active_skills: std::collections::BTreeMap::new(),
             stable_core_tools: std::collections::HashSet::new(),
             capabilities: CapabilityManifest::new(),
             sections: ContextSectionRegistry::default_agent_sections(),
@@ -118,6 +134,8 @@ impl ContextManager {
             handles: HandleTable::new(),
             next_handle_id: 0,
             frozen_history_len: 0,
+            pending_knowledge_sweeps: Vec::new(),
+            knowledge_budget_warned: false,
         }
     }
 
@@ -311,6 +329,9 @@ impl ContextManager {
             // Compaction rewrote the history prefix — start a fresh collapse generation so
             // surviving handles re-evaluate from Resident (P0-C: the one cache-free un-collapse point).
             self.reset_collapse_generation();
+            // K1: the prompt-cache prefix is being rebuilt anyway — the one cache-free moment to
+            // apply deferred knowledge upserts/removals (rewriting system[1] bytes).
+            self.sweep_knowledge_at_boundary();
         }
         // P2-D × P1-E: re-anchor the frozen-prefix boundary only when the compaction actually broke
         // the prompt-cache prefix (`result.3` = the planner's per-step `cache_at` cost, `Some` ⇒ a
@@ -335,6 +356,9 @@ impl ContextManager {
             // Compaction rewrote the history prefix — start a fresh collapse generation so
             // surviving handles re-evaluate from Resident (P0-C: the one cache-free un-collapse point).
             self.reset_collapse_generation();
+            // K1: the prompt-cache prefix is being rebuilt anyway — the one cache-free moment to
+            // apply deferred knowledge upserts/removals (rewriting system[1] bytes).
+            self.sweep_knowledge_at_boundary();
         }
         // P2-D × P1-E: re-anchor the frozen-prefix boundary only when the compaction actually broke
         // the prompt-cache prefix (`result.3` = the planner's per-step `cache_at` cost, `Some` ⇒ a
@@ -373,6 +397,9 @@ impl ContextManager {
             // Compaction rewrote the history prefix — start a fresh collapse generation so
             // surviving handles re-evaluate from Resident (P0-C: the one cache-free un-collapse point).
             self.reset_collapse_generation();
+            // K1: the prompt-cache prefix is being rebuilt anyway — the one cache-free moment to
+            // apply deferred knowledge upserts/removals (rewriting system[1] bytes).
+            self.sweep_knowledge_at_boundary();
         }
         // P2-D × P1-E: re-anchor the frozen-prefix boundary only when the compaction actually broke
         // the prompt-cache prefix (`result.3` = the planner's per-step `cache_at` cost, `Some` ⇒ a
@@ -412,6 +439,8 @@ impl ContextManager {
         // and start a fresh collapse generation (P0-C) since the whole prefix changed.
         self.prune_orphaned_handles();
         self.reset_collapse_generation();
+        // K1: renewal is a boundary — apply deferred knowledge upserts/removals now.
+        self.sweep_knowledge_at_boundary();
         // P1-E: the renewed history is the new frozen base.
         self.frozen_history_len = self.partitions.history.messages.len();
     }
@@ -438,7 +467,7 @@ impl ContextManager {
         ContextSnapshot {
             turn,
             system_messages: self.partitions.system.messages.clone(),
-            knowledge_messages: self.partitions.knowledge.messages.clone(),
+            knowledge_messages: self.partitions.knowledge.messages().cloned().collect(),
             history_messages: self.partitions.history.messages.clone(),
             task_state: self.partitions.task_state.clone(),
         }
@@ -478,6 +507,83 @@ impl ContextManager {
         self.partitions.knowledge.push(msg, tokens);
     }
 
+    /// K1: keyed knowledge push — fresh key appends immediately (cache-cheap direction), an
+    /// existing key stages a boundary-deferred upsert. `pinned` entries are exempt from the
+    /// K2 budget sweep.
+    pub fn push_knowledge_entry(
+        &mut self,
+        key: Option<CompactString>,
+        msg: Message,
+        tokens: u32,
+        pinned: bool,
+    ) {
+        self.partitions.knowledge.push_entry(key, msg, tokens, pinned);
+    }
+
+    /// K1: mark a keyed knowledge entry for removal at the next compaction/renewal boundary.
+    /// Errs-open: unknown key is a no-op (returns false).
+    pub fn remove_knowledge(&mut self, key: &str) -> bool {
+        self.partitions.knowledge.remove(key)
+    }
+
+    /// K1: run the boundary sweep (apply pending upserts, drop marked entries) and stash the
+    /// result for the state machine to drain into a `KnowledgeSwept` observation. Called only
+    /// from the compaction/renewal boundary blocks — the one place system[1] bytes may change.
+    fn sweep_knowledge_at_boundary(&mut self) {
+        let sweep = self.partitions.knowledge.sweep_at_boundary();
+        if sweep.changed {
+            self.pending_knowledge_sweeps.push(sweep);
+        }
+        // K2: a boundary starts a fresh cache generation — the budget warning may fire again.
+        self.knowledge_budget_warned = false;
+    }
+
+    /// K2: knowledge-budget check, run per turn before render. Over budget ⇒ mark the OLDEST
+    /// unpinned, non-skill entries for eviction at the next boundary until the projected usage
+    /// (used − already-marked) fits, and return `Some((used, budget))` ONCE per cache generation
+    /// for the `KnowledgeBudgetExceeded` observation (marking itself is idempotent and repeats
+    /// harmlessly). Skill pins are exempt — deactivation/lease governs them, the budget never
+    /// silently unloads a skill the model believes is active. If marking every eligible entry
+    /// still exceeds the budget, the warning stands and the overweight remainder is the host's
+    /// explicit choice (errs-open). `knowledge_budget_ratio <= 0.0` disables.
+    pub fn enforce_knowledge_budget(&mut self) -> Option<(u32, u32)> {
+        let ratio = self.config.knowledge_budget_ratio;
+        if ratio <= 0.0 {
+            return None;
+        }
+        let budget = (self.max_tokens as f64 * ratio) as u32;
+        let used = self.partitions.knowledge.token_count;
+        if used <= budget {
+            return None;
+        }
+        let entries = &mut self.partitions.knowledge.entries;
+        let marked: u32 = entries.iter().filter(|e| e.evict_at_boundary).map(|e| e.tokens).sum();
+        let mut projected = used.saturating_sub(marked);
+        for entry in entries.iter_mut() {
+            if projected <= budget {
+                break;
+            }
+            if entry.evict_at_boundary || entry.pinned {
+                continue;
+            }
+            if entry.key.as_deref().is_some_and(|k| k.starts_with("skill:")) {
+                continue;
+            }
+            entry.evict_at_boundary = true;
+            projected = projected.saturating_sub(entry.tokens);
+        }
+        if self.knowledge_budget_warned {
+            return None;
+        }
+        self.knowledge_budget_warned = true;
+        Some((used, budget))
+    }
+
+    /// K1: drain boundary-sweep results (state-machine side turns these into observations).
+    pub fn take_knowledge_sweeps(&mut self) -> Vec<crate::context::partitions::KnowledgeSweep> {
+        std::mem::take(&mut self.pending_knowledge_sweeps)
+    }
+
     /// Push a runtime signal into the current turn's State slot.
     /// Signals are ephemeral — cleared after each render.
     pub fn push_signal(&mut self, text: String) {
@@ -539,9 +645,45 @@ impl ContextManager {
 
     /// P1-B: record that the model has loaded a skill (its content is now in context). Returns
     /// `true` if this changed the active set — an epoch boundary the SDK can use to re-anchor the
-    /// prompt cache (D). No-op (returns false) when the skill was already active.
+    /// prompt cache (D). Re-activating an already-active skill refreshes its lease (K3) but
+    /// returns false (no epoch change).
     pub fn activate_skill(&mut self, name: impl Into<CompactString>) -> bool {
-        self.active_skills.insert(name.into())
+        self.activate_skill_leased(name, None)
+    }
+
+    /// K3: activate with an optional lease expiry turn (`None` = permanent). Same epoch semantics
+    /// as [`Self::activate_skill`]; a re-activation overwrites the prior lease (latest wins).
+    pub fn activate_skill_leased(
+        &mut self,
+        name: impl Into<CompactString>,
+        expires_at_turn: Option<u32>,
+    ) -> bool {
+        self.active_skills.insert(name.into(), expires_at_turn).is_none()
+    }
+
+    /// K3: deactivate a skill — the toolset re-widens at the next `emit_call_llm` (an epoch event,
+    /// same cache cost class as activation) and the skill's `skill:<name>` knowledge pin is marked
+    /// for the next boundary sweep. Errs-open: not-active is a no-op (returns false).
+    pub fn deactivate_skill(&mut self, name: &str) -> bool {
+        if self.active_skills.remove(name).is_none() {
+            return false;
+        }
+        self.partitions.knowledge.remove(&format!("skill:{name}"));
+        true
+    }
+
+    /// K3: expire skill leases whose turn has passed (mirrors the capability lease sweep — runs at
+    /// the head of every event). Each expiry takes the same path as an explicit deactivation.
+    pub fn sweep_expired_skill_leases(&mut self, current_turn: u32) {
+        let expired: Vec<CompactString> = self
+            .active_skills
+            .iter()
+            .filter(|(_, lease)| lease.is_some_and(|t| current_turn >= t))
+            .map(|(name, _)| name.clone())
+            .collect();
+        for name in expired {
+            self.deactivate_skill(&name);
+        }
     }
 
     /// P1-B: the tool-id allow-set to narrow the exposed toolset to, given the active skills.
@@ -554,7 +696,7 @@ impl ContextManager {
             return None;
         }
         let mut union = std::collections::HashSet::new();
-        for name in &self.active_skills {
+        for name in self.active_skills.keys() {
             let declared = self.skills.allowed_tools(name);
             if declared.is_empty() {
                 return None; // an unrestricted active skill ⇒ no narrowing (D3)
@@ -608,10 +750,42 @@ impl ContextManager {
         if let Some(t) = self.memory_tool_schema() { tools.push(t); }
         if let Some(t) = self.knowledge_tool_schema() { tools.push(t); }
         if let Some(t) = self.plan_tool_schema() { tools.push(t); }
+        if let Some(t) = self.read_result_tool_schema() { tools.push(t); }
         tools.sort_by(|a, b| a.name.cmp(&b.name));
         tools
     }
 
+    /// O7: the `read_result` meta-tool — re-fetch a tool result the kernel evicted from context
+    /// (spooled to disk / collapsed / paged out). Exposed DYNAMICALLY: only once at least one
+    /// handle has actually left residency, so runs that never evict see an unchanged toolset
+    /// (progressive disclosure; golden fixtures and cache prefixes stay byte-stable). Content is
+    /// host-resolved (spool file / session log) — the kernel only advertises the capability.
+    pub fn read_result_tool_schema(&self) -> Option<ToolSchema> {
+        let any_evicted = self
+            .handles
+            .all()
+            .iter()
+            .any(|h| !h.residency.occupies_context());
+        if !any_evicted { return None; }
+        Some(ToolSchema {
+            name: CompactString::new(READ_RESULT_TOOL_NAME),
+            description: "Re-read a tool result that was evicted from context (you see a \
+                          placeholder like '[…tool result spooled…]' or a collapsed entry). \
+                          Pass the tool call's call_id; use offset/max_bytes to page through \
+                          large content."
+                .to_string(),
+            parameters: serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "call_id": { "type": "string" },
+                    "offset": { "type": "integer", "description": "Byte offset to start from (default 0)." },
+                    "max_bytes": { "type": "integer", "description": "Max bytes to return (default 4000)." }
+                },
+                "required": ["call_id"]
+            }),
+        })
+    }
+
     pub fn plan_tool_schema(&self) -> Option<ToolSchema> {
         if !self.plan_tool_enabled { return None; }
         Some(ToolSchema {
@@ -1213,4 +1387,56 @@ mod tests {
         assert_eq!(mgr.handles.residency_for_source("c0"), Some(&Residency::Collapsed));
         assert_eq!(mgr.handles.residency_for_source("c5"), Some(&Residency::Resident));
     }
+
+    // ── K2: knowledge budget ─────────────────────────────────────────────────
+
+    #[test]
+    fn knowledge_budget_marks_oldest_unpinned_first_and_warns_once() {
+        // max_tokens 100 × default ratio 0.25 ⇒ budget 25. Four 10-token entries (40 used):
+        // two evictable, one pinned, one skill pin.
+        let mut mgr = ContextManager::new(100);
+        mgr.push_knowledge(Message::system("oldest unkeyed"), 10);
+        mgr.push_knowledge_entry(Some("a".into()), Message::system("keyed"), 10, false);
+        mgr.push_knowledge_entry(Some("p".into()), Message::system("pinned"), 10, true);
+        mgr.push_knowledge_entry(Some("skill:x".into()), Message::system("skill"), 10, false);
+
+        let warn = mgr.enforce_knowledge_budget();
+        assert_eq!(warn, Some((40, 25)));
+        // Oldest-first: unkeyed (10) then "a" (10) marked ⇒ projected 20 ≤ 25 stops there.
+        let e = &mgr.partitions.knowledge.entries;
+        assert!(e[0].evict_at_boundary);
+        assert!(e[1].evict_at_boundary);
+        assert!(!e[2].evict_at_boundary, "pinned exempt");
+        assert!(!e[3].evict_at_boundary, "skill pin exempt");
+
+        // Warn-once per generation; marking stays idempotent.
+        assert_eq!(mgr.enforce_knowledge_budget(), None);
+
+        // The boundary sweep drops the marked entries and re-arms the warning.
+        let sweep = mgr.partitions.knowledge.sweep_at_boundary();
+        assert_eq!(sweep.tokens_freed, 20);
+        assert_eq!(mgr.partitions.knowledge.token_count, 20);
+        // Back under budget ⇒ no further warning even though it re-armed.
+        assert_eq!(mgr.enforce_knowledge_budget(), None);
+    }
+
+    #[test]
+    fn knowledge_budget_warning_stands_when_only_exempt_weight_remains() {
+        let mut mgr = ContextManager::new(100);
+        mgr.push_knowledge_entry(Some("p".into()), Message::system("pinned heavy"), 30, true);
+        mgr.push_knowledge_entry(Some("skill:x".into()), Message::system("skill heavy"), 30, false);
+
+        // Over budget (60 > 25) but nothing evictable — warning fires, nothing marked.
+        assert_eq!(mgr.enforce_knowledge_budget(), Some((60, 25)));
+        assert!(mgr.partitions.knowledge.entries.iter().all(|e| !e.evict_at_boundary));
+    }
+
+    #[test]
+    fn knowledge_budget_ratio_zero_disables() {
+        let mut mgr = ContextManager::new(100);
+        mgr.config.knowledge_budget_ratio = 0.0;
+        mgr.push_knowledge(Message::system("huge"), 90);
+        assert_eq!(mgr.enforce_knowledge_budget(), None);
+        assert!(!mgr.partitions.knowledge.entries[0].evict_at_boundary);
+    }
 }