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

deepstrike_core/mm/
mod.rs
