Struct ContextManager 

pub struct ContextManager {
    pub budget: Option<ContextBudget>,
    pub soft_compaction_threshold: f32,
    pub hard_compaction_threshold: f32,
    pub compaction_preserve_tail: usize,
    pub prune_protect_tokens: usize,
    pub compression: CompressionConfig,
    pub routing: StoreRoutingConfig,
    pub store_routing_provider: Option<Arc<AnyProvider>>,
    /* private fields */
}

Per-session context lifecycle manager.

Holds the token budget, compaction lifecycle state, and routing configuration. Callers in zeph-core drive the state machine via advance_turn, compaction_tier, and related accessors; the assembler reads the budget via build_router and field access.

Fields

budget: Option<ContextBudget>

Token budget for this session. None until configured via apply_budget_config.

soft_compaction_threshold: f32

Soft compaction threshold (default 0.70): prune tool outputs + apply deferred summaries.

hard_compaction_threshold: f32

Hard compaction threshold (default 0.90): full LLM-based summarization.

compaction_preserve_tail: usize

Number of recent messages preserved during hard compaction.

prune_protect_tokens: usize

Token count protected from pruning during soft compaction.

compression: CompressionConfig

Compression configuration for proactive compression.

routing: StoreRoutingConfig

Routing configuration for query-aware memory routing.

store_routing_provider: Option<Arc<AnyProvider>>

Resolved provider for LLM/hybrid routing. None when strategy is Heuristic or when the named provider could not be resolved from the pool.

Implementations

impl ContextManager

pub fn new() -> Self

Create a new ContextManager with default thresholds and no budget.

pub fn apply_budget_config( &mut self, budget_tokens: usize, reserve_ratio: f32, hard_compaction_threshold: f32, compaction_preserve_tail: usize, prune_protect_tokens: usize, soft_compaction_threshold: f32, compaction_cooldown_turns: u8, )

Apply budget and compaction thresholds from config.

Must be called once after config is resolved. Safe to call again when config reloads.

pub fn reset_compaction(&mut self)

Reset compaction state for a new conversation.

Clears cooldown, exhaustion, and turn counters so the new conversation starts with a clean compaction slate.

pub fn compaction_tier(&self, cached_tokens: u64) -> CompactionTier

Determine which compaction tier applies for the given token count.

Compares the current cached token count against the configured thresholds to decide whether hard compaction, soft compaction, or no compaction should be triggered. This method is typically called by the context assembler during a turn to proactively compress older messages if token usage grows too large.

• Hard when cached_tokens > budget * hard_compaction_threshold — triggers aggressive summarization and compaction
• Soft when cached_tokens > budget * soft_compaction_threshold — triggers lighter compaction without full summarization
• None otherwise (or when no budget is set) — no compaction needed

Parameters

• cached_tokens — current token count in the cached context (e.g., message history)

Returns

The compaction tier that should be applied (Hard, Soft, or None).

Examples

use zeph_context::manager::ContextManager;
use zeph_context::budget::ContextBudget;

let budget = ContextBudget::new(128_000, 0.15);
let mut manager = ContextManager::new();
manager.soft_compaction_threshold = 0.6;
manager.hard_compaction_threshold = 0.8;
manager.budget = Some(budget);

// Check tier for 96k cached tokens (75% of 128k)
let tier = manager.compaction_tier(96_000);
// Returns Soft (75% is between 60% and 80%)

pub fn compaction_state(&self) -> CompactionState

Check if proactive compression should fire for the current turn.

Returns Some((threshold_tokens, max_summary_tokens)) when proactive compression should be triggered, None otherwise.

For CompressionStrategy::Focus, the threshold is the soft-compaction fraction of the budget (same gate used by mid-iteration soft compaction). The max_summary_tokens element is unused on the Focus path — the auto-consolidation function uses FocusConfig.max_knowledge_tokens / 2 instead.

Returns the current compaction lifecycle state.

pub fn compaction_state_mut(&mut self) -> &mut CompactionState

Returns a mutable reference to the compaction lifecycle state.

pub fn set_compaction_state(&mut self, state: CompactionState)

Replaces the compaction lifecycle state.

pub fn compaction_cooldown_turns(&self) -> u8

Returns the number of cooling turns enforced after a hard compaction.

pub fn set_compaction_cooldown_turns(&mut self, turns: u8)

Sets the number of cooling turns enforced after a hard compaction.

pub fn turns_since_last_hard_compaction(&self) -> Option<u64>

Returns the number of user-message turns since the last hard compaction, if any.

pub fn turns_since_last_hard_compaction_mut(&mut self) -> &mut Option<u64>

Returns a mutable reference to the turns-since-last-hard-compaction counter.

pub fn set_turns_since_last_hard_compaction(&mut self, value: Option<u64>)

Sets the turns-since-last-hard-compaction counter.

pub fn advance_turn(&mut self)

Reset the per-turn regrade flag at the start of a new user turn.

Must be called alongside CompactionState::advance_turn() at each turn boundary.

Examples

use zeph_context::manager::ContextManager;

let mut cm = ContextManager::new();
cm.set_regraded_this_turn(true);
cm.advance_turn();
// regraded_this_turn is reset to false — proactive regrade is available again
assert!(!cm.should_proactively_regrade(0, 0.6, false));

pub fn set_regraded_this_turn(&mut self, value: bool)

Mark that a proactive fidelity regrade has fired this turn (INV-06).

Called by the caller after should_proactively_regrade returns true and the scorer has been applied. Prevents a second regrade in the same turn.

Examples

use zeph_context::manager::ContextManager;
use zeph_context::budget::ContextBudget;

let mut cm = ContextManager::new();
cm.set_regraded_this_turn(true);
assert!(!cm.should_proactively_regrade(0, 0.6, false)); // guarded by regraded flag
cm.advance_turn();
assert!(!cm.should_proactively_regrade(0, 0.6, false)); // resets after advance_turn

pub fn should_proactively_regrade( &self, cached_tokens: u64, regrade_threshold: f32, server_compaction_active: bool, ) -> bool

Whether a proactive fidelity regrade should fire for the current context state.

Returns true only when all of the following hold:

1. No regrade has fired this turn yet (regraded_this_turn == false).
2. The compaction subsystem is not exhausted.
3. If server compaction is active, budget usage is below 95%.
4. Budget usage exceeds regrade_threshold.

Parameters

• cached_tokens — current token count in the message window.
• regrade_threshold — fraction of max tokens at which regrade triggers (e.g. 0.6).
• server_compaction_active — whether Claude server-side compaction is in use.

Examples

use zeph_context::manager::ContextManager;
use zeph_context::budget::ContextBudget;

let mut cm = ContextManager::new();
cm.budget = Some(ContextBudget::new(100_000, 0.1));
// At 70% budget with threshold 0.6 → should regrade.
assert!(cm.should_proactively_regrade(70_000, 0.6, false));

pub fn should_proactively_compress( &self, current_tokens: u64, ) -> Option<(usize, usize)>

Will return None if compaction already happened this turn (CRIT-03 fix).

Trait Implementations

impl Default for ContextManager

fn default() -> Self

Returns the “default value” for a type.