deepstrike_core/mm/
mod.rs

1//! Memory-management paging decisions (Phase 4) and long-term memory management (Phase 7).
2//!
3//! The kernel decides **when** to page working context out/in; SDKs perform **how**
4//! (durable store, embedding search, idle pipeline). No I/O in this module.
5//!
6//! Phase 7 extends this module with memory classification and validation rules.
7
8use crate::context::pressure::PressureAction;
9use serde::{Deserialize, Serialize};
10
11pub mod handle;
12pub mod memory;
13pub mod value;
14
15pub use handle::{
16    EvictionOp, EvictionPlan, Handle, HandleId, HandleKind, HandleTable, Residency, SpoolDecision,
17    plan_eviction, plan_spool,
18};
19
20/// Long-term tier hint for a page-out event (SDK maps to durable vs semantic store).
21#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(rename_all = "snake_case")]
23pub enum MemoryTierHint {
24    /// History compression archive — default durable/session store.
25    Durable,
26    /// Sprint renewal / handoff — semantic long-term pipeline.
27    Semantic,
28}
29
30impl MemoryTierHint {
31    pub fn label(self) -> &'static str {
32        match self {
33            Self::Durable => "durable",
34            Self::Semantic => "semantic",
35        }
36    }
37}
38
39/// Map a pressure-driven compression action to the recommended long-term tier.
40pub fn tier_hint_for_compress(action: PressureAction) -> MemoryTierHint {
41    match action {
42        PressureAction::ContextCollapse | PressureAction::AutoCompact => MemoryTierHint::Semantic,
43        _ => MemoryTierHint::Durable,
44    }
45}
46
47/// One knowledge entry supplied by the SDK after a long-term fetch (page-in).
48#[derive(Debug, Clone, Serialize, Deserialize)]
49pub struct PageInEntry {
50    pub content: String,
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub tokens: Option<u32>,
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub source: Option<String>,
55    /// K1: entry identity — a keyed page-in upserts instead of appending a duplicate.
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub key: Option<String>,
58    /// K1: pinned entries are exempt from the K2 budget sweep.
59    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
60    pub pinned: bool,
61}
62
63#[cfg(test)]
64mod tests {
65    use super::*;
66
67    #[test]
68    fn tier_hint_maps_auto_compact_to_semantic() {
69        assert_eq!(
70            tier_hint_for_compress(PressureAction::AutoCompact),
71            MemoryTierHint::Semantic
72        );
73        assert_eq!(
74            tier_hint_for_compress(PressureAction::SnipCompact),
75            MemoryTierHint::Durable
76        );
77    }
78}
deepstrike_core/mm/mod.rs

deepstrike_core/mm/
mod.rs
