Struct ContextLayout 

pub struct ContextLayout {
    pub regions: Vec<RegionDefinition>,
    pub total_budget_tokens: usize,
    pub eviction_order: Vec<String>,
}

A ContextLayout defines the complete memory map for an agent.

Like SNES VRAM layout - every region has a defined purpose, size, and policy. The layout specifies:

• Which regions exist and their configurations
• Total token budget across all regions
• Eviction order when space is needed

Layouts are typically defined in an agent’s blueprint and remain constant throughout the agent’s lifecycle, though the content within regions changes.

Fields

regions: Vec<RegionDefinition>

All regions in this layout

total_budget_tokens: usize

Total token budget across all regions

eviction_order: Vec<String>

Region names in eviction priority order (first = evicted first)

When the context window fills up, regions are processed in this order:

1. Temporary regions: evict oldest entries
2. Compacting regions: trigger summarization
3. SlidingWindow regions: reduce window size
4. Pinned regions: NEVER touched (if these fill up, it’s a config error)

Implementations

impl ContextLayout

pub fn new(regions: Vec<RegionDefinition>, total_budget_tokens: usize) -> Self

Create a new layout with the specified configuration.

pub fn with_eviction_order(self, order: Vec<String>) -> Self

Set the eviction order for this layout.

pub fn validate(&self) -> Result<(), ValidationError>

Validate that the layout is well-formed.

Checks:

• Sum of max_tokens doesn’t exceed total_budget_tokens
• All region names in eviction_order exist
• No duplicate region names

pub fn validate_working_room( &self, window: usize, ) -> Result<(), ValidationError>

Fail when the fixed (non-evictable) regions would leave less than MIN_WORKING_TOKENS of window for the evictable ones.

Split out from validate so a caller can judge each stage against that stage’s own context window over just the regions it can see, rather than one window for the whole layout: a region budgeted against a wide-window stage must not be counted against a narrow-window stage that never sees it. Pinned / HashMap / CompactHistory / persistent custom regions persist for the whole run and consume budget; if they leave too little, the evictable regions operate “blind”, so fail loudly at load instead of degrading silently at runtime. The floor is only enforced on realistically-sized windows (BUDGET_CHECK_MIN_TOTAL); a toy fixture’s tiny window is left alone.

pub fn get_region(&self, name: &str) -> Option<&RegionDefinition>

Get a region definition by name.

pub fn has_percent_budgets(&self) -> bool

Whether any region uses a percentage budget (and therefore needs a model context window to resolve to concrete token counts).

pub fn resolved(&self, window: usize) -> ContextLayout

Resolve every region’s percentage budget against a concrete model context window, returning a fully-absolute layout.

Each region’s max_tokens becomes budget.resolve(window), and each RegionKind::Compacting region’s threshold_tokens is recomputed from its compact_at fraction (via the private resolve_compacting_threshold helper). eviction_order is preserved. The total budget becomes the model window when any percentage budget is present (percentage ceilings are relative to the whole window and may sum past 100%); a pure-absolute layout keeps its summed total unchanged.

Resolving an already-absolute layout is a no-op, so this is safe to call unconditionally at window-build time.

pub fn resolved_per_region( &self, window_for: &dyn Fn(&str) -> usize, ) -> ContextLayout

Like resolved, but each region’s percentage budget is sized against a window chosen per region rather than one window for the whole layout.

window_for(region_name) gives the window a region is budgeted against: the caller passes the smallest context window among the stages that can actually see that region, so a region used only in wide-window stages keeps a wide budget even when a narrow-window stage exists that never sees it. The layout’s total_budget_tokens becomes the largest of those per-region windows; the authoritative fit check is per stage, done by the caller against each stage’s own window over the regions it sees.

An absolute layout has nothing to resolve, so this is a no-op for it, the same as resolved.

pub fn retaining<F: Fn(&str) -> bool>(&self, keep: F) -> ContextLayout

A copy holding only the regions (and eviction-order entries) whose name satisfies keep.

The runtime carries some always-visible regions (conversation, tool results) that no layout declares, so a stage’s visible-region set may name regions absent here; those are simply not present in the result. Used to judge a stage’s working room over exactly the regions it can see, rather than every region the layout declares.

Trait Implementations

impl Clone for ContextLayout

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ContextLayout

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ContextLayout

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ContextLayout

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

where __S: Serializer,

Serialize this value into the given Serde serializer.