Struct Region 

pub struct Region {
    pub name: String,
    pub kind: RegionKind,
    pub content: Vec<RegionEntry>,
    pub max_tokens: usize,
    pub current_tokens: usize,
    pub schema: Option<RegionSchema>,
    pub taint: Option<RegionTaint>,
    pub needs_message_compaction: bool,
}

A single region in the context window with its content and metadata.

Each region tracks its own token budget, current usage, and optional validation schema to enforce content format requirements.

Fields

name: String

Unique name identifying this region

kind: RegionKind

Lifecycle policy for this region

content: Vec<RegionEntry>

Content entries stored in this region

max_tokens: usize

Maximum tokens allowed in this region

current_tokens: usize

Current token count

schema: Option<RegionSchema>

Optional validation schema enforcing content format

taint: Option<RegionTaint>

Taint tracking state. Present when taint tracking is enabled.

needs_message_compaction: bool

When true, the Compact eviction strategy has determined that oldest entries should be summarized. The runtime checks this flag and performs the compaction externally (requires an LLM call).

Implementations

impl Region

pub fn new(name: String, kind: RegionKind, max_tokens: usize) -> Self

Create a new region with the specified configuration.

pub fn with_taint_tracking(self) -> Self

Enable taint tracking for this region.

pub fn enable_taint_tracking(&mut self)

Enable taint tracking on this region (mutable).

pub fn taint_level(&self) -> Option<TaintLevel>

Get the current taint level of this region, if taint tracking is enabled.

pub fn add_tainted_entry( &mut self, content: String, tokens: usize, taint_level: TaintLevel, ) -> Result<()>

Add an entry with a taint level. Used when taint tracking is enabled.

pub fn add_typed_tainted_entry( &mut self, content: String, tokens: usize, kind: EntryKind, taint_level: TaintLevel, ) -> Result<()>

Add a typed entry with a taint level.

Combines add_typed_entry (the entry carries a typed EntryKind so eviction can group turns) with add_tainted_entry (the entry contributes a specific taint level rather than defaulting to Public). Used for tool results when taint tracking is enabled, so a sensitive tool’s output both keeps its ToolResult kind and raises the region’s taint level.

pub fn with_schema(self, schema: RegionSchema) -> Self

Add a validation schema to this region.

pub fn add_entry(&mut self, content: String, tokens: usize) -> Result<()>

Add an entry to this region.

Validates content against schema if present, checks token budget, and adds the entry to the region.

pub fn add_entry_with_metadata( &mut self, content: String, tokens: usize, metadata: Value, ) -> Result<()>

Add an entry with metadata.

pub fn add_typed_entry( &mut self, content: String, tokens: usize, kind: EntryKind, ) -> Result<()>

Add an entry with a specific EntryKind to this region.

Like add_entry, but the caller supplies the entry kind so the entry carries typed metadata rather than relying on text-prefix parsing.

pub fn carry_entry(&mut self, entry: RegionEntry) -> Result<()>

Carry an already-accepted entry into this region verbatim, preserving its EntryKind, metadata, key, and timestamp.

Used when a stage-layout swap rebuilds a region and moves its surviving content across: re-adding through add_entry would stamp every carried entry EntryKind::Text, destroying the typed tool_use/tool_result pairing the assembler needs (the orphan sanitizer would then strip the whole history). Skips schema validation deliberately - the entry passed it when first accepted - but keeps the budget check and sliding-window enforcement so the destination region’s limits still hold. Taint is not touched per entry: a carry copies the region-level crate::taint::RegionTaint wholesale instead of re-accumulating it.

pub fn upsert_by_key( &mut self, key: &str, content: String, tokens: usize, ) -> Result<(), String>

Upsert an entry by key. If key exists, replace content and update timestamp/tokens. If key doesn’t exist, add new entry. Enforces max_tokens and max_entries via LRU eviction.

pub fn get_by_key(&self, key: &str) -> Option<&RegionEntry>

Get entry by key.

pub fn remove_by_key(&mut self, key: &str) -> bool

Remove entry by key.

pub fn keys(&self) -> Vec<&str>

List all keys in this region.

pub fn clear(&mut self)

Clear all content from this region.

pub fn remove_oldest(&mut self) -> Option<RegionEntry>

Remove the oldest entry (for Temporary regions).

pub fn remove_entries_by_prefix(&mut self, prefix: &str)

Remove all entries whose content starts with the given prefix.

Used to clear tagged entries (e.g. stage instructions) before injecting replacements, so stale instructions don’t accumulate across stage transitions.

pub fn entry_count(&self) -> usize

Get the number of entries in this region.

pub fn needs_compaction(&self) -> bool

Check if region needs compaction (for Compacting regions).

Trait Implementations

impl Clone for Region

fn clone(&self) -> Region

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Region

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Region

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Region

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.