deepstrike 0.2.7__tar.gz → 0.2.9__tar.gz

{deepstrike-0.2.7 → deepstrike-0.2.9}/Cargo.lock

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

{deepstrike-0.2.7 → deepstrike-0.2.9}/Cargo.toml

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

{deepstrike-0.2.7 → deepstrike-0.2.9}/PKG-INFO

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

{deepstrike-0.2.7 → deepstrike-0.2.9}/crates/deepstrike-core/src/context/compression.rs

@@ -663,6 +663,136 @@ mod tests {
         assert!(ctx.task_state.compression_log.iter().any(|e| e.action == "auto_compact"));
     }
 
+    // ─── W1-1 characterization baseline ────────────────────────────────────────
+    // Locks the CURRENT compaction behavior (tokens_saved / archived count / summary)
+    // across all four pressure levels + the cascade, so the upcoming compactor→executor
+    // refactor (EvictionOp vocab + cache-aware planner) is provably behavior-preserving.
+    // These are golden-master pins: the values describe what the pipeline does TODAY, not
+    // an independent derivation. If a future change moves a number here, that is a behavior
+    // change and must be justified, not blindly re-pinned.
+
+    use crate::types::message::Role;
+    use compact_str::CompactString;
+
+    /// Deterministic fixture: 4 oversized text turns + 2 tool-result messages, explicit token
+    /// counts so the cascade math is reproducible under `char_approx`.
+    fn baseline_partitions() -> ContextPartitions {
+        let cfg = config();
+        let mut ctx = ContextPartitions::new(&cfg);
+        // Oversized text turns (trigger Snip / Collapse / Auto).
+        ctx.history.push(Message::user("u0 ".repeat(120)), 300);
+        ctx.history.push(Message::assistant("a0 ".repeat(120)), 300);
+        // Tool-result message (trigger Micro).
+        ctx.history.messages.push(Message {
+            role: Role::Tool,
+            content: Content::Parts(vec![ContentPart::ToolResult {
+                call_id: CompactString::new("call_1"),
+                output: serde_json::json!({"rows": 42, "ok": true, "name": "alpha"}).to_string()
+                    + &"-pad".repeat(400),
+                is_error: false,
+            }]),
+            tool_calls: vec![],
+            token_count: Some(400),
+        });
+        ctx.history.token_count += 400;
+        ctx.history.push(Message::user("u1 ".repeat(120)), 300);
+        ctx.history.push(Message::assistant("a1 ".repeat(120)), 300);
+        ctx.history.messages.push(Message {
+            role: Role::Tool,
+            content: Content::Parts(vec![ContentPart::ToolResult {
+                call_id: CompactString::new("call_2"),
+                output: "y".repeat(1600),
+                is_error: false,
+            }]),
+            tool_calls: vec![],
+            token_count: Some(400),
+        });
+        ctx.history.token_count += 400;
+        ctx
+    }
+
+    /// Run the pipeline on a fresh baseline fixture at one action level.
+    /// Returns `(before, saved, summary, archived_len, msgs_after, total_after)`.
+    fn run_baseline(action: PressureAction) -> (u32, u32, Option<String>, usize, usize, u32) {
+        let mut ctx = baseline_partitions();
+        let before = ctx.total_tokens(&engine());
+        let (saved, summary, archived) =
+            CompressionPipeline::new(&config()).compress(&mut ctx, action, MAX, 500, &engine());
+        let archived_len = archived.len();
+        let msgs_after = ctx.history.messages.len();
+        let total_after = ctx.total_tokens(&engine());
+        (before, saved, summary, archived_len, msgs_after, total_after)
+    }
+
+    #[test]
+    fn baseline_snip_only_caps_text_no_archival() {
+        // SnipCompact runs only the Snip stage: caps oversized text messages in place; never
+        // archives or summarizes. Cascade stops above target (snip alone can't reach 500).
+        let (before, saved, summary, archived, msgs, total) = run_baseline(PressureAction::SnipCompact);
+        assert_eq!(before, 2001);
+        assert_eq!(saved, 1000);
+        assert_eq!(archived, 0);
+        assert!(summary.is_none());
+        assert_eq!(msgs, 6, "snip mutates in place, drops no messages");
+        assert_eq!(total, 1001);
+    }
+
+    #[test]
+    fn baseline_micro_excerpts_tool_results() {
+        // MicroCompact runs Snip then Micro: tool results excerpted to placeholders. Still no
+        // archival/summary; messages stay in place.
+        let (before, saved, summary, archived, msgs, total) = run_baseline(PressureAction::MicroCompact);
+        assert_eq!(before, 2001);
+        assert_eq!(saved, 1362);
+        assert_eq!(archived, 0);
+        assert!(summary.is_none());
+        assert_eq!(msgs, 6);
+        assert_eq!(total, 639);
+    }
+
+    #[test]
+    fn baseline_collapse_drops_oldest_and_summarizes() {
+        // ContextCollapse runs Snip→Micro→Collapse: oldest messages drained to `archived` with a
+        // summary, down to the preserve-recent floor (4 msgs kept).
+        let (before, saved, summary, archived, msgs, total) =
+            run_baseline(PressureAction::ContextCollapse);
+        assert_eq!(before, 2001);
+        assert_eq!(saved, 1462);
+        assert_eq!(archived, 2, "drops the 2 oldest messages above the preserve floor");
+        assert_eq!(msgs, 4, "preserve_recent_turns=2 → 4 messages kept");
+        assert_eq!(total, 539);
+        let summary = summary.expect("collapse summarizes archived messages");
+        assert!(
+            summary.contains("[Compressed: context_collapse]"),
+            "summary routes the collapse action: {summary}"
+        );
+    }
+
+    #[test]
+    fn baseline_auto_matches_collapse_at_preserve_floor() {
+        // AutoCompact runs all 4 stages, but on this fixture Snip→Micro→Collapse already hit the
+        // preserve floor, so the Auto stage archives nothing extra: identical outcome to Collapse.
+        let (before, saved, summary, archived, msgs, total) = run_baseline(PressureAction::AutoCompact);
+        assert_eq!(before, 2001);
+        assert_eq!(saved, 1462);
+        assert_eq!(archived, 2);
+        assert_eq!(msgs, 4);
+        assert_eq!(total, 539);
+        assert!(summary.is_some());
+    }
+
+    #[test]
+    fn baseline_saved_is_monotonic_in_action_level() {
+        // The cross-level contract the refactor must preserve: heavier pressure never frees less.
+        let snip = run_baseline(PressureAction::SnipCompact).1;
+        let micro = run_baseline(PressureAction::MicroCompact).1;
+        let collapse = run_baseline(PressureAction::ContextCollapse).1;
+        let auto = run_baseline(PressureAction::AutoCompact).1;
+        assert!(snip <= micro, "{snip} <= {micro}");
+        assert!(micro <= collapse, "{micro} <= {collapse}");
+        assert!(collapse <= auto, "{collapse} <= {auto}");
+    }
+
     #[test]
     fn pipeline_stops_cascade_when_target_reached() {
         let cfg = ContextConfig {

{deepstrike-0.2.7 → deepstrike-0.2.9}/crates/deepstrike-core/src/context/manager.rs

@@ -119,29 +119,57 @@ impl ContextManager {
     pub fn recompute_handle_residency(&mut self) {
         let collapse = self.rho() >= self.config.collapse_threshold;
         let keep = self.config.preserve_recent_msgs;
-        let ids: Vec<HandleId> = self
+        // Single mutable pass in insertion order. The previous implementation collected ids then
+        // re-found each via `get_mut` (a linear scan), making this O(handles²) **every turn** — the
+        // long-session cliff. `tool_result_handles_mut().enumerate()` yields the same set in the
+        // same order, so `i`/`cutoff` are bit-identical to the old logic, now in O(handles).
+        let total = self
             .handles
             .all()
             .iter()
             .filter(|h| matches!(h.kind, HandleKind::ToolResult))
-            .map(|h| h.id)
-            .collect();
-        let cutoff = ids.len().saturating_sub(keep);
-        for (i, id) in ids.iter().enumerate() {
-            if let Some(handle) = self.handles.get_mut(*id) {
-                // Only toggle the reversible Resident<->Collapsed axis; never clobber a handle
-                // that has been spooled or paged out.
-                if matches!(handle.residency, Residency::Resident | Residency::Collapsed) {
-                    handle.residency = if collapse && i < cutoff {
-                        Residency::Collapsed
-                    } else {
-                        Residency::Resident
-                    };
-                }
+            .count();
+        let cutoff = total.saturating_sub(keep);
+        for (i, handle) in self.handles.tool_result_handles_mut().enumerate() {
+            // Only toggle the reversible Resident<->Collapsed axis; never clobber a handle
+            // that has been spooled or paged out.
+            if matches!(handle.residency, Residency::Resident | Residency::Collapsed) {
+                handle.residency = if collapse && i < cutoff {
+                    Residency::Collapsed
+                } else {
+                    Residency::Resident
+                };
             }
         }
     }
 
+    /// Drop handles whose anchored source message no longer lives in `partitions.history` — i.e.
+    /// archived by a compaction or dropped on renewal. Without this the handle table grows with
+    /// total session length (a handle per tool result, never removed), which also inflates the
+    /// per-turn `recompute_handle_residency` scan. Called at compaction/renewal boundaries, so the
+    /// table tracks the working set, not the whole session. Handles with no `source` anchor (future
+    /// non-tool-result kinds) are always kept — they can't be orphaned by this check.
+    pub fn prune_orphaned_handles(&mut self) {
+        let live: std::collections::HashSet<CompactString> = self
+            .partitions
+            .history
+            .messages
+            .iter()
+            .flat_map(|m| match &m.content {
+                Content::Parts(parts) => parts
+                    .iter()
+                    .filter_map(|p| match p {
+                        ContentPart::ToolResult { call_id, .. } => Some(call_id.clone()),
+                        _ => None,
+                    })
+                    .collect::<Vec<_>>(),
+                _ => Vec::new(),
+            })
+            .collect();
+        self.handles
+            .retain(|h| h.source.as_ref().is_none_or(|s| live.contains(s)));
+    }
+
     /// Mark the handle anchored to `call_id` as spooled to disk (Layer 1): the SDK persists the
     /// full output, working context keeps only the preview. Keeps the handle out of the
     /// Resident↔Collapsed projection cycle. No-op if no handle is anchored to `call_id`.
@@ -159,8 +187,32 @@ impl ContextManager {
 
     // ── Pressure ──────────────────────────────────────────────────────────────
 
+    /// **Raw** rho — full partition weight (or provider-observed tokens when available). This is the
+    /// projection-decision rho: [`Self::recompute_handle_residency`] marks the Resident↔Collapsed set
+    /// from *this* value, so it must NOT discount paged content (else collapse → rho drops →
+    /// un-collapse would oscillate). Compaction/renewal triggers use [`Self::effective_rho`] instead.
     pub fn rho(&self) -> f64 {
-        self.pressure.pressure(&self.partitions, &self.engine, self.last_observed_prompt_tokens)
+        self.pressure
+            .pressure(&self.partitions, &self.engine, self.last_observed_prompt_tokens)
+    }
+
+    /// **Effective** rho — the pressure that actually drives compaction/renewal, made paging-aware.
+    ///
+    /// When provider usage is authoritative (`observed_prompt_tokens` set), the rendered prompt was
+    /// already collapsed (the renderer emits previews for `Collapsed` handles), so the observed count
+    /// already reflects paging — raw rho is exact and returned as-is. In the **estimate** path
+    /// (no observed tokens) we estimate from `partitions`, which still carry the full weight of
+    /// paged-out tool results (collapse is non-destructive); we subtract the non-resident handle
+    /// tokens so that collapsing/spooling a result immediately relieves pressure, rather than only
+    /// after the next provider round-trip. With no paged handles this equals [`Self::rho`], so the
+    /// pre-paging behavior is preserved exactly.
+    pub fn effective_rho(&self) -> f64 {
+        if self.max_tokens == 0 || self.last_observed_prompt_tokens.is_some() {
+            return self.rho();
+        }
+        let total = self.partitions.total_tokens(&self.engine);
+        let effective = total.saturating_sub(self.handles.non_resident_tokens());
+        effective as f64 / self.max_tokens as f64
     }
 
     pub fn set_observed_prompt_tokens(&mut self, tokens: u32) {
@@ -168,7 +220,10 @@ impl ContextManager {
     }
 
     pub fn should_compress(&self) -> PressureAction {
-        self.pressure.recommend(self.rho())
+        // Use effective (paging-aware) rho: once tool results are collapsed/spooled they no longer
+        // occupy working context, so they must not keep driving compaction. Equals raw rho when
+        // nothing is paged (behavior-preserving) and when provider usage is authoritative.
+        self.pressure.recommend(self.effective_rho())
     }
 
     pub fn compress(&mut self, action: PressureAction) -> (u32, Option<String>, Vec<Message>) {
@@ -194,6 +249,11 @@ impl ContextManager {
             self.last_compact_ms = Some(ts);
         }
 
+        // Archived messages have left history — drop their now-orphaned handles (bounds the table).
+        if !result.2.is_empty() {
+            self.prune_orphaned_handles();
+        }
+
         result
     }
 
@@ -201,7 +261,47 @@ impl ContextManager {
         if self.sections.is_partition_pinned(ContextSectionPartition::History) {
             return (0, None, vec![]);
         }
-        self.compression.compress(&mut self.partitions, PressureAction::AutoCompact, self.max_tokens, 0, &self.engine)
+        let result = self.compression.compress(&mut self.partitions, PressureAction::AutoCompact, self.max_tokens, 0, &self.engine);
+        if !result.2.is_empty() {
+            self.prune_orphaned_handles();
+        }
+        result
+    }
+
+    /// W1-1 收口: run one compaction `action` toward an **explicit** `target_tokens`, instead of
+    /// re-deriving the target from config. This is what lets `EvictionOp::Collapse { target_tokens }`
+    /// flow from the planner (the single decision point) straight to the executor — the compactor no
+    /// longer re-decides the target. `compress_with_time` remains the config-derived convenience used
+    /// by the other layers (Snip/Micro), whose target equals `config.target_tokens(max_tokens)`.
+    pub fn compress_with_target(
+        &mut self,
+        action: PressureAction,
+        target_tokens: u32,
+        now_ms: Option<u64>,
+    ) -> (u32, Option<String>, Vec<Message>) {
+        if self.sections.is_partition_pinned(ContextSectionPartition::History) {
+            return (0, None, vec![]);
+        }
+        let result =
+            self.compression
+                .compress(&mut self.partitions, action, self.max_tokens, target_tokens, &self.engine);
+        if let Some(ts) = now_ms {
+            self.last_compact_ms = Some(ts);
+        }
+        if !result.2.is_empty() {
+            self.prune_orphaned_handles();
+        }
+        result
+    }
+
+    /// W1-1 收口: the truthful compaction parameters the planner stamps into the [`EvictionPlan`],
+    /// read once from config so the ops carry real values (not magic-number placeholders) and the
+    /// executor stays a pure executor. Returns `(target_tokens, preserve_recent_turns)`.
+    pub fn plan_compaction_params(&self) -> (u32, usize) {
+        (
+            self.config.target_tokens(self.max_tokens),
+            self.config.preserve_recent_turns,
+        )
     }
 
     // ── Renewal ───────────────────────────────────────────────────────────────
@@ -216,6 +316,8 @@ impl ContextManager {
         self.partitions = renewed;
         self.last_handoff = Some(artifact);
         self.sprint += 1;
+        // History was rebuilt wholesale — drop handles anchored to messages it no longer carries.
+        self.prune_orphaned_handles();
     }
 
     // ── Render ────────────────────────────────────────────────────────────────
@@ -284,6 +386,13 @@ impl ContextManager {
         self.partitions.signals.push(text);
     }
 
+    /// Record a durable user directive in the (non-compressible, renewal-carried) task_state, so a
+    /// mid-task user command keeps its salience across compaction/renewal — unlike the ephemeral
+    /// signal channel, which is cleared on renewal.
+    pub fn record_directive(&mut self, text: impl Into<String>) {
+        self.partitions.task_state.record_directive(text);
+    }
+
     // ── Task state ────────────────────────────────────────────────────────────
 
     pub fn init_task(&mut self, goal: String, criteria: Vec<String>) {
@@ -651,4 +760,135 @@ mod tests {
         mgr.push_history(Message::user("hello"), 5);
         assert_eq!(mgr.handles.all().len(), 1);
     }
+
+    // ── W1-3: handle-table GC (prune orphaned handles + bounded recompute) ──
+
+    fn tool_result_msg(call_id: &str, output: &str) -> Message {
+        Message::tool(vec![ContentPart::ToolResult {
+            call_id: call_id.into(),
+            output: output.to_string(),
+            is_error: false,
+        }])
+    }
+
+    #[test]
+    fn effective_rho_discounts_paged_out_handles() {
+        let mut mgr = ContextManager::new(1_000);
+        // A large tool-result output so its handle carries a real token weight.
+        let big = "data ".repeat(200);
+        let tok = mgr.engine.count(&big);
+        mgr.push_history(tool_result_msg("c0", &big), tok);
+        mgr.push_history(Message::user("u"), 50);
+
+        let raw = mgr.rho();
+        // Everything resident → effective equals raw (behavior-preserving when nothing is paged).
+        assert_eq!(mgr.handles.non_resident_tokens(), 0);
+        assert!((mgr.effective_rho() - raw).abs() < f64::EPSILON);
+
+        // Page the tool result out of working context.
+        mgr.mark_spooled("c0", "disk://c0");
+        let paged = mgr.handles.non_resident_tokens();
+        assert!(paged > 0, "handle is now non-resident with a real token weight");
+
+        // Raw rho is unchanged (partitions are untouched by the non-destructive projection)...
+        assert!((mgr.rho() - raw).abs() < f64::EPSILON, "raw rho unchanged by paging");
+        // ...but effective rho drops by exactly the paged tokens — paging relieves pressure now.
+        let total = mgr.partitions.total_tokens(&mgr.engine);
+        let expected = total.saturating_sub(paged) as f64 / 1_000.0;
+        assert!((mgr.effective_rho() - expected).abs() < f64::EPSILON);
+        assert!(mgr.effective_rho() < raw, "effective pressure relieved by paging");
+
+        // When provider usage is authoritative, the rendered prompt was already collapsed, so
+        // effective falls back to raw (no double-discount).
+        mgr.set_observed_prompt_tokens(900);
+        assert!((mgr.effective_rho() - mgr.rho()).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn prune_orphaned_handles_drops_handles_whose_message_left_history() {
+        let mut mgr = ContextManager::new(10_000);
+        mgr.push_history(tool_result_msg("c0", "out 0"), 20);
+        mgr.push_history(tool_result_msg("c1", "out 1"), 20);
+        assert_eq!(mgr.handles.all().len(), 2);
+
+        // Simulate compaction archiving the oldest tool-result message out of history.
+        mgr.partitions.history.messages.remove(0);
+        mgr.prune_orphaned_handles();
+
+        // The handle for the evicted message is gone; the live one is retained.
+        assert_eq!(mgr.handles.all().len(), 1);
+        assert!(mgr.handles.residency_for_source("c0").is_none());
+        assert_eq!(
+            mgr.handles.residency_for_source("c1"),
+            Some(&Residency::Resident)
+        );
+    }
+
+    #[test]
+    fn autocompact_prunes_handles_for_archived_tool_results() {
+        let mut mgr = ContextManager::new(1_000);
+        // Enough oversized tool results to force AutoCompact to archive some.
+        for i in 0..30 {
+            mgr.push_history(tool_result_msg(&format!("c{i}"), &"x".repeat(200)), 80);
+        }
+        assert_eq!(mgr.handles.all().len(), 30);
+
+        let (saved, _, archived) = mgr.compress(PressureAction::AutoCompact);
+        assert!(saved > 0 && !archived.is_empty(), "expected archival");
+
+        // After compaction the table tracks only the tool results still in working history —
+        // not the whole session. (No handle outlives its backing message.)
+        let live_tool_results = mgr
+            .partitions
+            .history
+            .messages
+            .iter()
+            .filter(|m| matches!(&m.content, Content::Parts(p)
+                if p.iter().any(|x| matches!(x, ContentPart::ToolResult { .. }))))
+            .count();
+        assert_eq!(mgr.handles.all().len(), live_tool_results);
+        assert!(mgr.handles.all().len() < 30, "table must shrink with archival");
+    }
+
+    #[test]
+    fn renew_prunes_handles_for_dropped_history() {
+        let mut mgr = ContextManager::new(1_000);
+        mgr.init_task("g".to_string(), vec![]);
+        for i in 0..20 {
+            mgr.push_history(tool_result_msg(&format!("c{i}"), "data"), 60);
+        }
+        mgr.renew();
+        // Every retained handle must still be anchored to a message present in the renewed history.
+        for h in mgr.handles.all() {
+            if let Some(src) = h.source.as_ref() {
+                assert!(
+                    mgr.handles.residency_for_source(src).is_some(),
+                    "no dangling handle survives renewal"
+                );
+            }
+        }
+        assert!(mgr.handles.all().len() <= 20);
+    }
+
+    #[test]
+    fn recompute_residency_index_semantics_with_spooled_in_the_middle() {
+        // Locks the O(n)-rewrite's index/cutoff semantics against the old id+get_mut version:
+        // a spooled handle still occupies an index position but is never toggled.
+        let mut mgr = ContextManager::new(1_000);
+        for i in 0..6 {
+            mgr.push_history(tool_result_msg(&format!("c{i}"), &"y".repeat(40)), 40);
+        }
+        mgr.mark_spooled("c2", "disk://c2");
+
+        mgr.set_observed_prompt_tokens(950); // rho >= collapse_threshold
+        mgr.recompute_handle_residency();
+
+        // Spooled stays spooled; the most recent preserve_recent_msgs stay resident; older collapse.
+        assert_eq!(
+            mgr.handles.residency_for_source("c2"),
+            Some(&Residency::SpooledOut { r: "disk://c2".to_string() })
+        );
+        assert_eq!(mgr.handles.residency_for_source("c0"), Some(&Residency::Collapsed));
+        assert_eq!(mgr.handles.residency_for_source("c5"), Some(&Residency::Resident));
+    }
 }

{deepstrike-0.2.7 → deepstrike-0.2.9}/crates/deepstrike-core/src/context/mod.rs

@@ -13,4 +13,3 @@ pub mod summarizer;
 pub mod task_state;
 pub mod text;
 pub mod token_engine;
-pub mod llm_summarizer;

{deepstrike-0.2.7 → deepstrike-0.2.9}/crates/deepstrike-core/src/context/pressure.rs

@@ -30,6 +30,14 @@ impl PressureMonitor {
 
     /// Current pressure rho ∈ [0, +∞).
     /// Uses provider-reported prompt tokens when available; otherwise estimates from partitions.
+    ///
+    /// This is the **raw** rho (full partition weight). Making rho paging-aware — i.e. subtracting
+    /// non-resident (`Collapsed`/`SpooledOut`/`PagedOut`) handle tokens so paging immediately relieves
+    /// pressure — is **not** a drop-in here: [`crate::context::manager::ContextManager::recompute_handle_residency`]
+    /// decides the Resident↔Collapsed projection from this very rho, so subtracting collapsed tokens
+    /// would drop rho below `collapse_threshold` and immediately un-collapse (oscillation). That needs
+    /// a deliberate split into *raw* rho (drives the collapse decision) vs *effective* rho (drives
+    /// further compaction/renewal), tracked as remaining W1-1 design work — see `ContextManager::rho`.
     pub fn pressure(
         &self,
         partitions: &ContextPartitions,