AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
feat(engine): add process-wide segment hydration budget
buger64d344c204fe
diff --git a/engine/crates/xerj-common/src/config.rs b/engine/crates/xerj-common/src/config.rsindex d7ec0fea3..9e7a91208 100644--- a/engine/crates/xerj-common/src/config.rs+++ b/engine/crates/xerj-common/src/config.rs@@ -877,7 +877,7 @@ impl Default for EmbeddingConfig {/// Resource limits.///-/// **10 settings.**+/// **11 settings.**#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(default, deny_unknown_fields)]pub struct LimitsConfig {@@ -922,6 +922,12 @@ pub struct LimitsConfig {/// `circuit_breaking_exception` instead of growing until the kernel/// OOM-kills the process.pub max_total_memtable_mb: u64,+ /// Process-wide retained-payload ceiling for all immutable segment+ /// hydration caches (default: `0` = 20% of the effective cgroup/system+ /// memory limit). This is not an RSS ceiling: query materialization,+ /// decode scratch, mmaps, allocator fragmentation, and unrelated caches+ /// are outside it.+ pub max_segment_hydration_cache_mb: u64,/// RSS admission watermark, as a percentage of the effective process/// memory limit (default: `95`). The effective limit is the cgroup/// memory limit when one is set (e.g. under `systemd-run -p MemoryMax=`@@ -953,6 +959,7 @@ impl Default for LimitsConfig {max_mget_docs: 10_000,max_buckets: 65_536,max_total_memtable_mb: 0, // 0 = auto-derive (25% RAM, floor 2 GiB)+ max_segment_hydration_cache_mb: 0, // 0 = 20% effective memory, no floormemory_watermark_percent: 95,disk_flood_stage_percent: 95,}@@ -1367,12 +1374,13 @@ mod tests {// default_quantization, max_dimensions)// logs: 2 (retention_days, time_partition)// embedding: 4 (default_endpoint, default_model, batch_size, timeout_ms)- // limits: 3 (max_query_memory_mb, max_concurrent_searches, max_fields_per_index)+ // limits: 11 (query/concurrency/mapping/body/result/mget/bucket limits,+ // total memtable, segment hydration cache, RSS, disk)// indexing: 3 (turbo_batch_size, turbo_parallel, turbo_fast_analyzer)// logging: 2 (format, access_log) ← RC4-W4 item 6// ─────────- // total: 50 fields, minus 1 auto-generated (admin_api_key) = 49 meaningful user settings- let total: usize = 5 + 3 + 3 + 10 + 5 + 3 + 1 + 6 + 2 + 4 + 3 + 3 + 2;- assert_eq!(total, 50);+ // total: 58 fields, minus 1 auto-generated (admin_api_key) = 57 meaningful user settings+ let total: usize = 5 + 3 + 3 + 10 + 5 + 3 + 1 + 6 + 2 + 4 + 11 + 3 + 2;+ assert_eq!(total, 58);}}diff --git a/engine/crates/xerj-engine/src/governor.rs b/engine/crates/xerj-engine/src/governor.rsindex 129fd672e..5f287be81 100644--- a/engine/crates/xerj-engine/src/governor.rs+++ b/engine/crates/xerj-engine/src/governor.rs@@ -32,6 +32,8 @@ use tokio::sync::{OwnedSemaphorePermit, Semaphore};use xerj_common::config::Config;use xerj_common::XerjError;+use crate::segment_cache_budget::{SegmentHydrationBudget, SegmentHydrationBudgetSnapshot};+/// The process-wide governor singleton.static GOVERNOR: OnceLock<Arc<ResourceGovernor>> = OnceLock::new();@@ -44,6 +46,9 @@ pub const SAMPLE_INTERVAL_MS: u64 = 100;/// Process-wide resource governor. See the module docs.pub struct ResourceGovernor {+ /// One admission authority shared by every index in this process.+ segment_hydration_budget: Arc<SegmentHydrationBudget>,+ segment_hydration_budget_source: SegmentHydrationBudgetSource,// ── item 1: process-wide memtable budget ────────────────────────────/// Ceiling on summed memtable bytes across ALL indices. `0` = disabled.memtable_budget_bytes: u64,@@ -288,6 +293,8 @@ impl ResourceGovernor {/// surfaces.pub fn snapshot(&self) -> GovernorSnapshot {GovernorSnapshot {+ segment_hydration: self.segment_hydration_budget.snapshot(),+ segment_hydration_source: self.segment_hydration_budget_source,memtable_used_bytes: self.memtable_used_bytes.load(Ordering::Relaxed),memtable_budget_bytes: self.memtable_budget_bytes,memtable_tripped: self.memtable_tripped.load(Ordering::Relaxed),@@ -303,6 +310,10 @@ impl ResourceGovernor {search_inflight_peak: self.search_inflight_peak.load(Ordering::Relaxed),}}++ pub fn segment_hydration_budget(&self) -> Arc<SegmentHydrationBudget> {+ Arc::clone(&self.segment_hydration_budget)+ }}/// RAII guard for a held global search permit. Decrements the in-flight@@ -321,6 +332,8 @@ impl Drop for SearchPermit {/// A cheap, `Copy`-able snapshot of governor state.#[derive(Debug, Clone, Copy)]pub struct GovernorSnapshot {+ pub segment_hydration: SegmentHydrationBudgetSnapshot,+ pub segment_hydration_source: SegmentHydrationBudgetSource,pub memtable_used_bytes: u64,pub memtable_budget_bytes: u64,pub memtable_tripped: bool,@@ -336,6 +349,85 @@ pub struct GovernorSnapshot {pub search_inflight_peak: u64,}+#[derive(Debug, Clone, Copy, Eq, PartialEq)]+pub enum SegmentHydrationBudgetSource {+ Auto,+ Config,+ Env,+}++#[derive(Debug, Clone, Eq, PartialEq)]+struct ResolvedSegmentHydrationBudget {+ bytes: u64,+ source: SegmentHydrationBudgetSource,+ warning: Option<String>,+}++fn resolve_segment_hydration_budget(+ effective_limit: u64,+ configured_mb: u64,+ env_value: Option<&str>,+) -> ResolvedSegmentHydrationBudget {+ const MIB: u64 = 1024 * 1024;+ let automatic = effective_limit / 5;+ let explicit = |mb: u64, source| {+ let requested = mb.saturating_mul(MIB);+ let maximum = effective_limit / 2;+ let bytes = requested.min(maximum);+ let warning = (requested > maximum).then(|| {+ format!(+ "requested segment hydration cache {} MiB exceeds 50% of effective memory; clamped to {} MiB",+ mb,+ bytes / MIB+ )+ });+ ResolvedSegmentHydrationBudget {+ bytes,+ source,+ warning,+ }+ };++ match env_value.map(str::trim) {+ Some("auto") => ResolvedSegmentHydrationBudget {+ bytes: automatic,+ source: SegmentHydrationBudgetSource::Env,+ warning: None,+ },+ Some("off") => ResolvedSegmentHydrationBudget {+ bytes: 0,+ source: SegmentHydrationBudgetSource::Env,+ warning: None,+ },+ Some(value) => match value.parse::<u64>() {+ Ok(0) => {+ let mut fallback =+ resolve_segment_hydration_budget(effective_limit, configured_mb, None);+ fallback.warning = Some(+ "XERJ_SEGMENT_HYDRATION_CACHE_MB=0 is ambiguous; use auto or off; falling back to config"+ .to_owned(),+ );+ fallback+ }+ Ok(mb) => explicit(mb, SegmentHydrationBudgetSource::Env),+ Err(_) => {+ let mut fallback =+ resolve_segment_hydration_budget(effective_limit, configured_mb, None);+ fallback.warning = Some(format!(+ "invalid XERJ_SEGMENT_HYDRATION_CACHE_MB={value:?}; expected auto, off, or a positive MiB value; falling back to config"+ ));+ fallback+ }+ },+ None if configured_mb > 0 => explicit(configured_mb, SegmentHydrationBudgetSource::Config),+ None => ResolvedSegmentHydrationBudget {+ bytes: automatic,+ source: SegmentHydrationBudgetSource::Auto,+ warning: None,+ },+ }+}+// ─────────────────────────────────────────────────────────────────────────// Initialisation / access// ─────────────────────────────────────────────────────────────────────────@@ -368,6 +460,17 @@ fn build(config: &Config) -> ResourceGovernor {// ── RSS watermark against the effective memory limit ──let memory_limit_bytes = effective_memory_limit_bytes();+ let resolved_segment_hydration = resolve_segment_hydration_budget(+ memory_limit_bytes,+ limits.max_segment_hydration_cache_mb,+ std::env::var("XERJ_SEGMENT_HYDRATION_CACHE_MB")+ .ok()+ .as_deref(),+ );+ if let Some(warning) = &resolved_segment_hydration.warning {+ tracing::warn!("{warning}");+ }+ let segment_hydration_budget = SegmentHydrationBudget::new(resolved_segment_hydration.bytes);let memory_watermark_bytes = if limits.memory_watermark_percent == 0 {0} else {@@ -387,10 +490,14 @@ fn build(config: &Config) -> ResourceGovernor {max_query_memory_mb = limits.max_query_memory_mb,max_concurrent_searches,disk_flood_pct = limits.disk_flood_stage_percent,+ segment_hydration_cache_mb = resolved_segment_hydration.bytes / (1024 * 1024),+ segment_hydration_cache_source = ?resolved_segment_hydration.source,"resource governor initialised (parent circuit breaker)");ResourceGovernor {+ segment_hydration_budget,+ segment_hydration_budget_source: resolved_segment_hydration.source,memtable_budget_bytes,memtable_used_bytes: AtomicU64::new(0),memtable_tripped: AtomicBool::new(false),@@ -612,6 +719,47 @@ fn human_bytes(b: u64) -> String {mod tests {use super::*;+ #[test]+ fn segment_hydration_resolver_is_cgroup_proportional_and_explicit() {+ const GIB: u64 = 1024 * 1024 * 1024;+ let auto = resolve_segment_hydration_budget(8 * GIB, 0, None);+ assert_eq!(auto.bytes, 8 * GIB / 5);+ assert_eq!(auto.source, SegmentHydrationBudgetSource::Auto);++ let tiny = resolve_segment_hydration_budget(256 * 1024 * 1024, 0, None);+ assert_eq!(tiny.bytes, 256 * 1024 * 1024 / 5);++ let config = resolve_segment_hydration_budget(8 * GIB, 1024, None);+ assert_eq!(config.bytes, GIB);+ assert_eq!(config.source, SegmentHydrationBudgetSource::Config);++ let off = resolve_segment_hydration_budget(8 * GIB, 1024, Some("off"));+ assert_eq!(off.bytes, 0);+ assert_eq!(off.source, SegmentHydrationBudgetSource::Env);++ let env = resolve_segment_hydration_budget(8 * GIB, 1024, Some("2048"));+ assert_eq!(env.bytes, 2 * GIB);+ assert_eq!(env.source, SegmentHydrationBudgetSource::Env);+ }++ #[test]+ fn segment_hydration_resolver_clamps_overflow_and_rejects_ambiguous_env_zero() {+ const GIB: u64 = 1024 * 1024 * 1024;+ let clamped = resolve_segment_hydration_budget(8 * GIB, u64::MAX, None);+ assert_eq!(clamped.bytes, 4 * GIB);+ assert!(clamped.warning.is_some());++ let invalid = resolve_segment_hydration_budget(8 * GIB, 1024, Some("bogus"));+ assert_eq!(invalid.bytes, GIB);+ assert_eq!(invalid.source, SegmentHydrationBudgetSource::Config);+ assert!(invalid.warning.is_some());++ let zero = resolve_segment_hydration_budget(8 * GIB, 0, Some("0"));+ assert_eq!(zero.bytes, 8 * GIB / 5);+ assert_eq!(zero.source, SegmentHydrationBudgetSource::Auto);+ assert!(zero.warning.is_some());+ }+#[test]fn effective_limit_is_positive() {assert!(effective_memory_limit_bytes() > 0);diff --git a/engine/crates/xerj-engine/src/ingest_memory.rs b/engine/crates/xerj-engine/src/ingest_memory.rsindex 5f2a06c12..33461c8dd 100644--- a/engine/crates/xerj-engine/src/ingest_memory.rs+++ b/engine/crates/xerj-engine/src/ingest_memory.rs@@ -234,6 +234,10 @@ pub struct Event {/// Sum of all logical category currents in this coherent snapshot./// This is diagnostic attribution, not an allocator/RSS identity.pub logical_total_current: u64,+ /// Process-wide retained segment-hydration payload/key ceiling. Separate+ /// from logical ingest ownership and explicitly not an RSS identity.+ pub segment_hydration_cache:+ Option<crate::segment_cache_budget::SegmentHydrationBudgetSnapshot>,/// Retain/release underflows observed since process start.pub accounting_errors: u64,/// Trace events rejected by the bounded output sink since trace start.@@ -429,6 +433,8 @@ impl Ledger {scope,logical,logical_total_current,+ segment_hydration_cache: crate::governor::global()+ .map(|governor| governor.snapshot().segment_hydration),accounting_errors: self.accounting_errors.load(Ordering::Relaxed),dropped_events: self.dropped_events.load(Ordering::Relaxed),allocator: AllocatorSnapshot {@@ -483,7 +489,14 @@ fn measurement(category: Category) -> Measurement {Category::MemtableActive| Category::ParsedSource| Category::PreparedDocument- | Category::FlushDrained => Measurement::Estimated,+ | Category::FlushDrained+ | Category::CacheStoredSlices+ | Category::CacheDocValues+ | Category::CacheStoredValues+ | Category::CacheSortShadow+ | Category::CacheIdPositions+ | Category::CacheRowSequences+ | Category::CacheDecodedStored => Measurement::Estimated,_ => Measurement::Unavailable,}}diff --git a/engine/crates/xerj-engine/src/lib.rs b/engine/crates/xerj-engine/src/lib.rsindex 52b252f59..06d9c0711 100644--- a/engine/crates/xerj-engine/src/lib.rs+++ b/engine/crates/xerj-engine/src/lib.rs@@ -26,6 +26,7 @@ pub mod ingest_memory;pub mod memtable;pub mod painless;pub mod rbac;+pub mod segment_cache_budget;pub mod segment_cache_estimates;pub mod slow_query;pub mod sql;diff --git a/engine/crates/xerj-engine/src/segment_cache_budget.rs b/engine/crates/xerj-engine/src/segment_cache_budget.rsnew file mode 100644index 000000000..dec0a3b97--- /dev/null+++ b/engine/crates/xerj-engine/src/segment_cache_budget.rs@@ -0,0 +1,388 @@+//! Process-wide retained-payload budget for immutable segment hydration caches.+//!+//! This is deliberately not an RSS limit: allocator fragmentation, DashMap+//! capacity, mmaps, query-owned materialization, and decode scratch live+//! outside this accounting. A charge follows the cached value through every+//! in-flight reader and is refunded only when its last `Arc` is dropped.++use std::sync::atomic::{AtomicU64, Ordering};+use std::sync::Arc;++use crate::ingest_memory::{Category, Retained};++pub const CATEGORY_COUNT: usize = 7;++#[derive(Clone, Copy, Debug, Eq, PartialEq)]+#[repr(usize)]+pub enum SegmentCacheCategory {+ StoredSlices = 0,+ DocValues,+ StoredValues,+ SortShadow,+ IdPositions,+ RowSequences,+ DecodedStored,+}++impl SegmentCacheCategory {+ pub const ALL: [Self; CATEGORY_COUNT] = [+ Self::StoredSlices,+ Self::DocValues,+ Self::StoredValues,+ Self::SortShadow,+ Self::IdPositions,+ Self::RowSequences,+ Self::DecodedStored,+ ];++ fn trace_category(self) -> Category {+ match self {+ Self::StoredSlices => Category::CacheStoredSlices,+ Self::DocValues => Category::CacheDocValues,+ Self::StoredValues => Category::CacheStoredValues,+ Self::SortShadow => Category::CacheSortShadow,+ Self::IdPositions => Category::CacheIdPositions,+ Self::RowSequences => Category::CacheRowSequences,+ Self::DecodedStored => Category::CacheDecodedStored,+ }+ }+}++#[derive(Debug, Clone, Copy, Eq, PartialEq, serde::Serialize)]+pub struct SegmentHydrationBudgetSnapshot {+ pub limit: u64,+ pub current: u64,+ pub peak: u64,+ pub refused: u64,+ pub accounting_errors: u64,+ pub category_current: [u64; CATEGORY_COUNT],+ pub category_peak: [u64; CATEGORY_COUNT],+}++pub struct SegmentHydrationBudget {+ limit: u64,+ used: AtomicU64,+ peak: AtomicU64,+ refused: AtomicU64,+ accounting_errors: AtomicU64,+ category_current: [AtomicU64; CATEGORY_COUNT],+ category_peak: [AtomicU64; CATEGORY_COUNT],+}++impl SegmentHydrationBudget {+ pub fn new(limit: u64) -> Arc<Self> {+ Arc::new(Self {+ limit,+ used: AtomicU64::new(0),+ peak: AtomicU64::new(0),+ refused: AtomicU64::new(0),+ accounting_errors: AtomicU64::new(0),+ category_current: std::array::from_fn(|_| AtomicU64::new(0)),+ category_peak: std::array::from_fn(|_| AtomicU64::new(0)),+ })+ }++ pub fn limit(&self) -> u64 {+ self.limit+ }++ pub fn try_charge(+ self: &Arc<Self>,+ category: SegmentCacheCategory,+ bytes: u64,+ ) -> Option<BudgetCharge> {+ let mut current = self.used.load(Ordering::Acquire);+ loop {+ let Some(next) = current.checked_add(bytes) else {+ self.refused.fetch_add(1, Ordering::Relaxed);+ return None;+ };+ if next > self.limit {+ self.refused.fetch_add(1, Ordering::Relaxed);+ return None;+ }+ match self.used.compare_exchange_weak(+ current,+ next,+ Ordering::AcqRel,+ Ordering::Acquire,+ ) {+ Ok(_) => {+ self.peak.fetch_max(next, Ordering::Relaxed);+ let category_current = self.category_current[category as usize]+ .fetch_add(bytes, Ordering::AcqRel)+ + bytes;+ self.category_peak[category as usize]+ .fetch_max(category_current, Ordering::Relaxed);+ return Some(BudgetCharge {+ budget: Arc::clone(self),+ category,+ bytes,+ });+ }+ Err(observed) => current = observed,+ }+ }+ }++ pub fn snapshot(&self) -> SegmentHydrationBudgetSnapshot {+ SegmentHydrationBudgetSnapshot {+ limit: self.limit,+ current: self.used.load(Ordering::Acquire),+ peak: self.peak.load(Ordering::Acquire),+ refused: self.refused.load(Ordering::Acquire),+ accounting_errors: self.accounting_errors.load(Ordering::Acquire),+ category_current: std::array::from_fn(|i| {+ self.category_current[i].load(Ordering::Acquire)+ }),+ category_peak: std::array::from_fn(|i| self.category_peak[i].load(Ordering::Acquire)),+ }+ }++ fn release(&self, category: SegmentCacheCategory, bytes: u64) {+ checked_sub(+ &self.category_current[category as usize],+ bytes,+ &self.accounting_errors,+ );+ checked_sub(&self.used, bytes, &self.accounting_errors);+ }+}++fn checked_sub(counter: &AtomicU64, bytes: u64, errors: &AtomicU64) {+ let result = counter.fetch_update(Ordering::AcqRel, Ordering::Acquire, |current| {+ current.checked_sub(bytes)+ });+ if result.is_err() {+ errors.fetch_add(1, Ordering::Relaxed);+ debug_assert!(false, "segment hydration cache accounting underflow");+ }+}++pub struct BudgetCharge {+ budget: Arc<SegmentHydrationBudget>,+ category: SegmentCacheCategory,+ bytes: u64,+}++impl Drop for BudgetCharge {+ fn drop(&mut self) {+ self.budget.release(self.category, self.bytes);+ }+}++pub struct CacheResident<T> {+ value: T,+ _charge: Option<BudgetCharge>,+ _trace_retained: Retained<'static>,+}++impl<T> CacheResident<T> {+ pub fn admitted(+ value: T,+ charge: BudgetCharge,+ category: SegmentCacheCategory,+ bytes: u64,+ ) -> Arc<Self> {+ Arc::new(Self {+ value,+ _charge: Some(charge),+ _trace_retained: Retained::new(+ category.trace_category(),+ usize::try_from(bytes).unwrap_or(usize::MAX),+ ),+ })+ }++ pub fn uncached(value: T) -> Arc<Self> {+ Arc::new(Self {+ value,+ _charge: None,+ _trace_retained: Retained::disabled(),+ })+ }++ pub fn value(&self) -> &T {+ &self.value+ }+}++impl<T> std::ops::Deref for CacheResident<T> {+ type Target = T;++ fn deref(&self) -> &Self::Target {+ &self.value+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn charge_is_refunded_only_after_last_arc() {+ let budget = SegmentHydrationBudget::new(64);+ let charge = budget+ .try_charge(SegmentCacheCategory::StoredValues, 40)+ .unwrap();+ let resident =+ CacheResident::admitted(vec![1_u8], charge, SegmentCacheCategory::StoredValues, 40);+ let reader = Arc::clone(&resident);+ drop(resident);+ assert_eq!(budget.snapshot().current, 40);+ drop(reader);+ assert_eq!(budget.snapshot().current, 0);+ }++ #[test]+ fn zero_limit_overflow_and_categories_are_exact() {+ let off = SegmentHydrationBudget::new(0);+ assert!(off+ .try_charge(SegmentCacheCategory::StoredSlices, 1)+ .is_none());+ let budget = SegmentHydrationBudget::new(u64::MAX);+ let charge = budget+ .try_charge(SegmentCacheCategory::DocValues, u64::MAX)+ .unwrap();+ assert!(budget+ .try_charge(SegmentCacheCategory::RowSequences, 1)+ .is_none());+ let snapshot = budget.snapshot();+ assert_eq!(snapshot.current, u64::MAX);+ assert_eq!(+ snapshot.category_current[SegmentCacheCategory::DocValues as usize],+ u64::MAX+ );+ assert_eq!(snapshot.refused, 1);+ drop(charge);+ assert_eq!(budget.snapshot().current, 0);+ }++ #[test]+ fn underflow_is_detected_without_wrapping_the_counter() {+ let budget = SegmentHydrationBudget::new(16);+ let charge = budget+ .try_charge(SegmentCacheCategory::RowSequences, 8)+ .unwrap();+ drop(charge);+ let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {+ budget.release(SegmentCacheCategory::RowSequences, 8);+ }));+ assert!(result.is_err(), "debug builds must surface double release");+ let snapshot = budget.snapshot();+ assert_eq!(snapshot.current, 0);+ assert_eq!(snapshot.accounting_errors, 1);+ }++ #[test]+ fn concurrent_cas_never_exceeds_limit() {+ let budget = SegmentHydrationBudget::new(1_000);+ let barrier = Arc::new(std::sync::Barrier::new(65));+ let mut threads = Vec::new();+ for _ in 0..64 {+ let budget = Arc::clone(&budget);+ let barrier = Arc::clone(&barrier);+ threads.push(std::thread::spawn(move || {+ barrier.wait();+ budget.try_charge(SegmentCacheCategory::DecodedStored, 31)+ }));+ }+ barrier.wait();+ let charges: Vec<_> = threads+ .into_iter()+ .filter_map(|thread| thread.join().unwrap())+ .collect();+ let snapshot = budget.snapshot();+ assert!(snapshot.current <= 1_000);+ assert!(snapshot.peak <= 1_000);+ assert_eq!(snapshot.current, charges.len() as u64 * 31);+ drop(charges);+ assert_eq!(budget.snapshot().current, 0);+ }++ #[test]+ fn refusal_can_return_an_uncharged_correct_local_value() {+ let budget = SegmentHydrationBudget::new(1);+ assert!(budget+ .try_charge(SegmentCacheCategory::StoredValues, 2)+ .is_none());+ let local = CacheResident::uncached(vec![String::from("answer")]);+ assert_eq!(local[0], "answer");+ let snapshot = budget.snapshot();+ assert_eq!(snapshot.current, 0);+ assert_eq!(snapshot.refused, 1);+ }++ #[test]+ fn retirement_refunds_only_after_held_reader_drops() {+ let budget = SegmentHydrationBudget::new(128);+ let map = dashmap::DashMap::<String, Arc<CacheResident<Vec<u8>>>>::new();+ let charge = budget+ .try_charge(SegmentCacheCategory::DecodedStored, 80)+ .unwrap();+ let resident =+ CacheResident::admitted(vec![7], charge, SegmentCacheCategory::DecodedStored, 80);+ map.insert("retired".into(), Arc::clone(&resident));+ let reader = Arc::clone(&resident);+ drop(resident);+ map.remove("retired");+ assert_eq!(budget.snapshot().current, 80);+ drop(reader);+ assert_eq!(budget.snapshot().current, 0);+ }++ #[test]+ fn two_index_maps_share_one_ceiling() {+ let budget = SegmentHydrationBudget::new(100);+ let first = dashmap::DashMap::<String, Arc<CacheResident<Vec<u8>>>>::new();+ let second = dashmap::DashMap::<String, Arc<CacheResident<Vec<u8>>>>::new();+ let charge = budget+ .try_charge(SegmentCacheCategory::StoredSlices, 60)+ .unwrap();+ first.insert(+ "a".into(),+ CacheResident::admitted(vec![1], charge, SegmentCacheCategory::StoredSlices, 60),+ );+ assert!(budget+ .try_charge(SegmentCacheCategory::DocValues, 60)+ .is_none());+ assert!(second.is_empty());+ assert_eq!(budget.snapshot().peak, 60);+ drop(first);+ assert_eq!(budget.snapshot().current, 0);+ }++ #[tokio::test]+ async fn telemetry_categories_match_budget_and_release_to_zero() {+ let ledger = Box::leak(Box::new(crate::ingest_memory::Ledger::new()));+ crate::ingest_memory::with_test_ledger(ledger, async {+ let budget = SegmentHydrationBudget::new(1_000);+ for category in SegmentCacheCategory::ALL {+ let charge = budget.try_charge(category, 17).unwrap();+ let resident = CacheResident::admitted(vec![1_u8], charge, category, 17);+ assert_eq!(+ ledger+ .gauge(+ category.trace_category(),+ crate::ingest_memory::Measurement::Estimated,+ )+ .current,+ 17+ );+ assert_eq!(budget.snapshot().category_current[category as usize], 17);+ drop(resident);+ assert_eq!(+ ledger+ .gauge(+ category.trace_category(),+ crate::ingest_memory::Measurement::Estimated,+ )+ .current,+ 0+ );+ }+ assert_eq!(budget.snapshot().current, 0);+ })+ .await;+ }+}diff --git a/engine/xerj.default.toml b/engine/xerj.default.tomlindex cff373334..f502f3bb2 100644--- a/engine/xerj.default.toml+++ b/engine/xerj.default.toml@@ -287,7 +287,7 @@ batch_size = 64# request fails with a timeout error.timeout_ms = 5000-# ── Resource Limits (3 settings) ──────────────────────────────────────────────+# ── Resource Limits (11 settings; omitted keys use documented defaults) ───────[limits]@@ -306,6 +306,12 @@ max_concurrent_searches = 64# Elasticsearch uses 1000 as its default; 500 is intentionally stricter.max_fields_per_index = 500+# Process-wide retained-payload budget for the seven immutable segment+# hydration caches (MiB). 0 derives 20% of the effective cgroup/system memory+# limit with no minimum floor. This is not an RSS limit: query-owned results,+# decode scratch, mmaps, allocator fragmentation, and other caches are separate.+max_segment_hydration_cache_mb = 0+# ── Turbo Indexing (3 settings) — opt-in high-throughput mode ─────────────────## Turbo mode is enabled per-request, not globally: