Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(cache): 增加顶层 service_name 配置, 删除 namespace/cache_key_prefix ,使用service_name 统一管理 (#6011)
baojun-zhang6c1107527af4
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex b09adc8c8..c415e33bf 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -296,7 +296,7 @@ struct RagfsCacheConfig {enabled: bool,runtime_enabled: bool,provider: CacheProviderKind,- namespace: String,+ service_name: String,max_file_size_bytes: usize,traversal_mode: CacheTraversalMode,bypass_prefixes: Vec<String>,@@ -345,7 +345,7 @@ impl Default for RagfsCacheConfig {enabled: false,runtime_enabled: false,provider: CacheProviderKind::Redis,- namespace: "openviking".to_string(),+ service_name: String::new(),max_file_size_bytes: CachePolicy::default().max_file_size(),traversal_mode: CacheTraversalMode::Backend,bypass_prefixes: Vec::new(),@@ -421,7 +421,7 @@ impl RagfsCacheConfig {provider: Some(provider),cachefs: CacheFsConfig {enabled: self.enabled,- namespace: self.namespace.clone(),+ service_name: self.service_name.clone(),policy: cache_policy_from_config(self),},})@@ -429,39 +429,38 @@ impl RagfsCacheConfig {}/// Load PathLock configuration from one canonical OpenViking config file.-fn pathlock_config_from_ov_conf(path: &str) -> Result<PathLockConfig, String> {+fn pathlock_config_from_ov_conf(path: &str, service_name: &str) -> Result<PathLockConfig, String> {let raw = fs::read_to_string(path).map_err(|error| format!("failed to read OpenViking config {path}: {error}"))?;let json: serde_json::Value = serde_json::from_str(&raw).map_err(|error| format!("failed to parse OpenViking config {path}: {error}"))?;- pathlock_config_from_canonical_ov_conf(&json)+ pathlock_config_from_canonical_ov_conf(&json, service_name)}/// Parse PathLock configuration from the canonical `storage.agfs.pathlock` section.fn pathlock_config_from_canonical_ov_conf(json: &serde_json::Value,+ service_name: &str,) -> Result<PathLockConfig, String> {let pathlock = json.get("storage").and_then(|storage| storage.get("agfs")).and_then(|agfs| agfs.get("pathlock"));match pathlock {- Some(pathlock) => pathlock_config_from_value(pathlock),+ Some(pathlock) => pathlock_config_from_value(pathlock, service_name),None => Ok(PathLockConfig::default()),}}/// Parse one sectioned PathLock configuration object.-fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfig, String> {+fn pathlock_config_from_value(+ value: &serde_json::Value,+ service_name: &str,+) -> Result<PathLockConfig, String> {let pathlock = value.as_object().ok_or_else(|| "pathlock config must be an object".to_string())?;- const FIELDS: &[&str] = &[- "provider",- "namespace",- "lock_timeout_secs",- "lock_expire_secs",- ];+ const FIELDS: &[&str] = &["provider", "lock_timeout_secs", "lock_expire_secs"];if let Some(field) = pathlock.keys().find(|field| !FIELDS.contains(&field.as_str()))@@ -475,21 +474,7 @@ fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfi"unsupported pathlock.provider: {provider}; expected filesystem, memory, or cache"));}- let namespace = optional_string_field(pathlock, "namespace")?;- if provider == "cache" && namespace.as_deref().is_none_or(str::is_empty) {- return Err("pathlock.namespace is required for provider=cache".to_string());- }- if let Some(namespace) = &namespace {- if !namespace- .bytes()- .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))- {- return Err(- "pathlock.namespace must contain only ASCII letters, digits, '.', '_' or '-'"- .to_string(),- );- }- }+ let pathlock_service_name = (provider == "cache").then(|| service_name.to_string());let lock_timeout_secs = f64_field(pathlock, "lock_timeout_secs", 0.0)?;if !lock_timeout_secs.is_finite() || lock_timeout_secs < 0.0 {@@ -502,43 +487,58 @@ fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfiOk(PathLockConfig {provider,- namespace,+ service_name: pathlock_service_name,lock_timeout_secs,lock_expire_secs,})}-fn cache_config_from_ov_conf(path: &str) -> Result<RagfsCacheConfig, String> {+fn cache_config_from_ov_conf(path: &str, service_name: &str) -> Result<RagfsCacheConfig, String> {let raw = fs::read_to_string(path).map_err(|error| format!("failed to read OpenViking config {path}: {error}"))?;let json: serde_json::Value = serde_json::from_str(&raw).map_err(|error| format!("failed to parse OpenViking config {path}: {error}"))?;- cache_config_from_canonical_ov_conf(&json)+ cache_config_from_canonical_ov_conf(&json, service_name)}/// Load canonical cache configuration while forcing a shared Runtime consumer.fn cache_config_from_ov_conf_with_runtime(path: &str,force_runtime: bool,+ service_name: &str,) -> Result<RagfsCacheConfig, String> {let raw = fs::read_to_string(path).map_err(|error| format!("failed to read OpenViking config {path}: {error}"))?;let json: serde_json::Value = serde_json::from_str(&raw).map_err(|error| format!("failed to parse OpenViking config {path}: {error}"))?;- cache_config_from_canonical_ov_conf_with_runtime(&json, force_runtime)+ cache_config_from_canonical_ov_conf_with_runtime(&json, force_runtime, service_name)}fn cache_config_from_canonical_ov_conf(json: &serde_json::Value,+ service_name: &str,) -> Result<RagfsCacheConfig, String> {- let pathlock_uses_cache = pathlock_config_from_canonical_ov_conf(json)?.provider == "cache";- cache_config_from_canonical_ov_conf_with_runtime(json, pathlock_uses_cache)+ let pathlock_uses_cache =+ pathlock_config_from_canonical_ov_conf(json, service_name)?.provider == "cache";+ let backups_use_cache = json+ .get("storage")+ .and_then(|storage| storage.get("agfs"))+ .and_then(|agfs| agfs.get("backups"))+ .and_then(|backups| backups.get("provider"))+ .and_then(serde_json::Value::as_str)+ == Some("cache");+ cache_config_from_canonical_ov_conf_with_runtime(+ json,+ pathlock_uses_cache || backups_use_cache,+ service_name,+ )}/// Parse canonical cache configuration and optionally require its shared Runtime.fn cache_config_from_canonical_ov_conf_with_runtime(json: &serde_json::Value,force_runtime: bool,+ service_name: &str,) -> Result<RagfsCacheConfig, String> {let agfs = json.get("storage").and_then(|storage| storage.get("agfs"));if agfs.and_then(|agfs| agfs.get("cache")).is_some() {@@ -573,13 +573,13 @@ fn cache_config_from_canonical_ov_conf_with_runtime(}let mut config = RagfsCacheConfig::default();+ config.service_name = service_name.to_string();config.enabled = cachefs_backend == "cache";config.runtime_enabled = config.enabled || queuefs_backend == "cache" || force_runtime;if let Some(cachefs) = cachefs {let cachefs = cachefs.as_object().ok_or_else(|| "storage.agfs.cachefs must be an object".to_string())?;- config.namespace = string_field(cachefs, "namespace", &config.namespace)?;config.max_file_size_bytes =usize_field(cachefs, "max_file_size_bytes", config.max_file_size_bytes)?;config.traversal_mode =@@ -593,7 +593,7 @@ fn cache_config_from_canonical_ov_conf_with_runtime(let cache = json.get("cache").ok_or_else(|| {- "top-level cache.provider/cache.params is required when CacheFS or QueueFS uses backend=cache"+ "top-level cache.provider/cache.params is required when AGFS uses cache-backed modules".to_string()})?.as_object()@@ -642,23 +642,25 @@ fn optional_backend(string_field(section, "backend", default)}-fn cache_config_from_value(cache: &serde_json::Value) -> Result<RagfsCacheConfig, String> {+fn cache_config_from_value(+ cache: &serde_json::Value,+ service_name: &str,+) -> Result<RagfsCacheConfig, String> {if cache.is_null() {- return Ok(RagfsCacheConfig::default());+ let mut config = RagfsCacheConfig::default();+ config.service_name = service_name.to_string();+ return Ok(config);}let cache = cache.as_object().ok_or_else(|| "binding cache config must be an object".to_string())?;let mut config = RagfsCacheConfig::default();+ config.service_name = service_name.to_string();config.enabled = bool_field(cache, "enabled", config.enabled)?;config.runtime_enabled = bool_field(cache, "runtime_enabled", config.enabled)?;let provider = string_field(cache, "provider", "redis")?;config.provider = provider_kind(provider)?;- config.namespace = string_field(cache, "namespace", &config.namespace)?;- if config.namespace.trim().is_empty() {- return Err("cache.namespace must not be empty".to_string());- }config.max_file_size_bytes =usize_field(cache, "max_file_size_bytes", config.max_file_size_bytes)?;config.traversal_mode = traversal_mode(string_field(cache, "traversal_mode", "backend")?)?;@@ -1504,7 +1506,8 @@ impl RAGFSBindingClient {impl RAGFSBindingClient {/// Create a new RAGFS binding client.///- /// `config_path` loads the canonical ov.conf schema. Removed cache schemas are rejected.+ /// `config_path` loads the canonical ov.conf schema. `config.service_name` must be supplied+ /// by the Python runtime./// `config` is an optional sectioned dict produced by the Python runtime. The `encryption`/// section, when present, carries `root_key` (32 bytes) + `provider_type` (int) and causes the/// stack to include an `EncryptionWrappedFS` layer. Runtime `cache` configuration takes@@ -1522,19 +1525,34 @@ impl RAGFSBindingClient {// Phase A (holding GIL): parse the sectioned config into an owned RagfsConfig.let mut ragfs_cfg = RagfsConfig::default();+ let service_name = match config.as_ref() {+ Some(cfg) => Some(+ cfg.get("service_name")+ .ok_or_else(|| PyValueError::new_err("service_name is required"))?+ .extract::<String>(py)?,+ ),+ None => None,+ };let inline_pathlock_configured = config.as_ref().is_some_and(|config| config.contains_key("pathlock"));if !inline_pathlock_configured {if let Some(path) = config_path {- ragfs_cfg.pathlock = pathlock_config_from_ov_conf(path).map_err(|error| {- PyRuntimeError::new_err(format!("Invalid PathLock config: {error}"))- })?;+ let service_name = service_name+ .as_deref()+ .ok_or_else(|| PyValueError::new_err("service_name is required"))?;+ ragfs_cfg.pathlock =+ pathlock_config_from_ov_conf(path, service_name).map_err(|error| {+ PyRuntimeError::new_err(format!("Invalid PathLock config: {error}"))+ })?;}}let mut runtime_cache_config = None;let mut inline_git_cfg: Option<ragfs::git::GitConfig> = None;if let Some(cfg) = config {+ let service_name = service_name+ .as_deref()+ .ok_or_else(|| PyValueError::new_err("service_name is required"))?;if let Some(log_obj) = cfg.get("log") {let log_cfg: HashMap<String, Py<PyAny>> = log_obj.extract(py)?;let log_level = log_cfg@@ -1570,10 +1588,11 @@ impl RAGFSBindingClient {}if let Some(cache_obj) = cfg.get("cache") {let cache_value = py_to_json_value(cache_obj.bind(py))?;- runtime_cache_config =- Some(cache_config_from_value(&cache_value).map_err(|error| {+ runtime_cache_config = Some(+ cache_config_from_value(&cache_value, service_name).map_err(|error| {PyRuntimeError::new_err(format!("Invalid cache config: {error}"))- })?);+ })?,+ );}if let Some(git_obj) = cfg.get("git") {let git_value = py_to_json_value(git_obj.bind(py))?;@@ -1583,8 +1602,8 @@ impl RAGFSBindingClient {}if let Some(pl_obj) = cfg.get("pathlock") {let pl_value = py_to_json_value(pl_obj.bind(py))?;- ragfs_cfg.pathlock =- pathlock_config_from_value(&pl_value).map_err(PyValueError::new_err)?;+ ragfs_cfg.pathlock = pathlock_config_from_value(&pl_value, service_name)+ .map_err(PyValueError::new_err)?;}}@@ -1592,12 +1611,15 @@ impl RAGFSBindingClient {let pathlock_uses_cache = ragfs_cfg.pathlock.provider == "cache";let file_cache_config = config_path.map(|path| {+ let service_name = service_name+ .as_deref()+ .ok_or_else(|| "service_name is required".to_string())?;if inline_cache_configured {- cache_config_from_ov_conf_with_runtime(path, false)+ cache_config_from_ov_conf_with_runtime(path, false, service_name)} else if inline_pathlock_configured {- cache_config_from_ov_conf_with_runtime(path, pathlock_uses_cache)+ cache_config_from_ov_conf_with_runtime(path, pathlock_uses_cache, service_name)} else {- cache_config_from_ov_conf(path)+ cache_config_from_ov_conf(path, service_name)}}).transpose()@@ -3100,19 +3122,27 @@ mod tests {}#[test]- fn constructor_accepts_canonical_config_path() {+ fn constructor_accepts_canonical_config_path_with_runtime_service_name() {let path = std::env::temp_dir().join(format!("openviking-canonical-config-path-{}.json",std::process::id()));- fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();+ fs::write(+ &path,+ r#"{"service_name": "test-service", "storage": {"agfs": {"backend": "local"}}}"#,+ )+ .unwrap();+ Python::initialize();Python::attach(|py| {let ty = py.get_type::<RAGFSBindingClient>();+ let config = PyDict::new(py);+ config.set_item("service_name", "test-service").unwrap();let kwargs = PyDict::new(py);kwargs.set_item("config_path", path.to_str().unwrap()).unwrap();+ kwargs.set_item("config", config).unwrap();let instance = ty.call((), Some(&kwargs));assert!(instance.is_ok());});@@ -3130,6 +3160,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "test-service","storage": {"agfs": {"pathlock": {"provider": "cache"}@@ -3144,6 +3175,7 @@ mod tests {let pathlock = PyDict::new(py);pathlock.set_item("provider", "filesystem").unwrap();let config = PyDict::new(py);+ config.set_item("service_name", "inline-prod").unwrap();config.set_item("pathlock", pathlock).unwrap();let kwargs = PyDict::new(py);kwargs@@ -3168,7 +3200,11 @@ mod tests {"openviking-inline-redis-pathlock-{}.json",std::process::id()));- fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();+ fs::write(+ &path,+ r#"{"service_name": "test-service", "storage": {"agfs": {"backend": "local"}}}"#,+ )+ .unwrap();Python::attach(|py| {let ty = py.get_type::<RAGFSBindingClient>();@@ -3182,9 +3218,9 @@ mod tests {cache.set_item("redis", redis).unwrap();let pathlock = PyDict::new(py);pathlock.set_item("provider", "cache").unwrap();- pathlock.set_item("namespace", "inline-prod").unwrap();pathlock.set_item("lock_expire_secs", 3.0).unwrap();let config = PyDict::new(py);+ config.set_item("service_name", "inline-prod").unwrap();config.set_item("cache", cache).unwrap();config.set_item("pathlock", pathlock).unwrap();let kwargs = PyDict::new(py);@@ -3248,13 +3284,18 @@ mod tests {"openviking-no-cache-config-{}.json",std::process::id()));- fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();+ fs::write(+ &path,+ r#"{"service_name": "test-service", "storage": {"agfs": {"backend": "local"}}}"#,+ )+ .unwrap();- let cache_config = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();+ let cache_config =+ cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap();assert!(!cache_config.enabled);assert_eq!(cache_config.provider, CacheProviderKind::Redis);- assert_eq!(cache_config.namespace, "openviking");+ assert_eq!(cache_config.service_name, "test-service");assert_eq!(cache_config.traversal_mode, CacheTraversalMode::Backend);fs::remove_file(path).unwrap();@@ -3269,6 +3310,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "prod-a","cache": {"provider": "redis","params": {"endpoints": ["redis://redis:6379"]}@@ -3277,7 +3319,6 @@ mod tests {"agfs": {"pathlock": {"provider": "cache",- "namespace": "prod-a","lock_expire_secs": 60.0}}@@ -3286,11 +3327,11 @@ mod tests {).unwrap();- let pathlock = pathlock_config_from_ov_conf(path.to_str().unwrap()).unwrap();- let cache = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();+ let pathlock = pathlock_config_from_ov_conf(path.to_str().unwrap(), "prod-a").unwrap();+ let cache = cache_config_from_ov_conf(path.to_str().unwrap(), "prod-a").unwrap();assert_eq!(pathlock.provider, "cache");- assert_eq!(pathlock.namespace.as_deref(), Some("prod-a"));+ assert_eq!(pathlock.service_name.as_deref(), Some("prod-a"));assert_eq!(pathlock.lock_expire_secs, 60.0);assert!(cache.runtime_enabled);assert_eq!(cache.provider, CacheProviderKind::Redis);@@ -3300,17 +3341,21 @@ mod tests {}#[test]- fn redis_pathlock_config_requires_namespace() {- let error = pathlock_config_from_canonical_ov_conf(&serde_json::json!({- "storage": {- "agfs": {- "pathlock": {"provider": "cache"}+ fn redis_pathlock_config_uses_runtime_service_name() {+ let pathlock = pathlock_config_from_canonical_ov_conf(+ &serde_json::json!({+ "service_name": "prod-a",+ "storage": {+ "agfs": {+ "pathlock": {"provider": "cache"}+ }}- }- }))- .unwrap_err();+ }),+ "prod-a",+ )+ .unwrap();- assert!(error.contains("namespace"));+ assert_eq!(pathlock.service_name.as_deref(), Some("prod-a"));}#[test]@@ -3322,6 +3367,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "tenant-a","cache": {"provider": "redis","params": {@@ -3335,7 +3381,6 @@ mod tests {"agfs": {"cachefs": {"backend": "cache",- "namespace": "tenant-a","traversal_mode": "cached_traversal"},"queuefs": {"backend": "cache"}@@ -3345,12 +3390,12 @@ mod tests {).unwrap();- let cache_config = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();+ let cache_config = cache_config_from_ov_conf(path.to_str().unwrap(), "tenant-a").unwrap();assert!(cache_config.enabled);assert!(cache_config.runtime_enabled);assert_eq!(cache_config.provider, CacheProviderKind::Redis);- assert_eq!(cache_config.namespace, "tenant-a");+ assert_eq!(cache_config.service_name, "tenant-a");assert_eq!(cache_config.traversal_mode,CacheTraversalMode::CachedTraversal@@ -3368,9 +3413,13 @@ mod tests {"openviking-removed-cache-config-{}.json",std::process::id()));- fs::write(&path, r#"{"storage":{"agfs":{"cache":{"enabled":true}}}}"#).unwrap();+ fs::write(+ &path,+ r#"{"service_name":"test-service","storage":{"agfs":{"cache":{"enabled":true}}}}"#,+ )+ .unwrap();- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();assert!(error.contains("storage.agfs.cache has been removed"));assert!(error.contains("cache.provider"));@@ -3390,7 +3439,7 @@ mod tests {).unwrap();- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();assert!(error.contains("queuefs backend=redis has been removed"));assert!(error.contains("backend=cache"));@@ -3407,6 +3456,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "test-service","cache": {"provider": "redis", "params": {}},"storage": {"agfs": {@@ -3417,7 +3467,7 @@ mod tests {).unwrap();- let cache_config = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();+ let cache_config = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap();let stack_config = cache_config.stack_config().unwrap();assert!(cache_config.runtime_enabled);@@ -3435,6 +3485,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "test-service","cache": {"provider": "redis","params": {"key_prefix": "provider-prefix"}@@ -3448,7 +3499,7 @@ mod tests {).unwrap();- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();assert!(error.contains("key_prefix"));@@ -3464,6 +3515,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "test-service","cache": {"provider": "mooncake", "params": {}},"storage": {"agfs": {@@ -3474,7 +3526,7 @@ mod tests {).unwrap();- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();assert!(error.contains("mooncake"));@@ -3490,7 +3542,7 @@ mod tests {"provider": provider,});- let error = cache_config_from_value(&config).unwrap_err();+ let error = cache_config_from_value(&config, "runtime-prod").unwrap_err();assert!(error.contains(provider));}@@ -3505,6 +3557,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "test-service","cache": {"provider": "redis", "params": {}},"storage": {"agfs": {"cachefs": {"backend": "cache",@@ -3514,7 +3567,7 @@ mod tests {).unwrap();- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();assert!(error.contains("traversal_mode"));@@ -3531,6 +3584,7 @@ mod tests {fs::write(&path,r#"{+ "service_name": "test-service","cache": {"provider": "redis", "params": {}},"storage": {"agfs": {"cachefs": {"backend": "cache"}}}}"#,@@ -3542,8 +3596,8 @@ mod tests {let cache = PyDict::new(py);cache.set_item("enabled", false).unwrap();cache.set_item("provider", "redis").unwrap();- cache.set_item("namespace", "runtime-cache").unwrap();let config = PyDict::new(py);+ config.set_item("service_name", "runtime-cache").unwrap();config.set_item("cache", cache).unwrap();let kwargs = PyDict::new(py);kwargs@@ -3567,7 +3621,7 @@ mod tests {));fs::write(&path,- r#"{"storage": {"agfs": {"cache": {"enabled": false}}}}"#,+ r#"{"service_name": "test-service", "storage": {"agfs": {"cache": {"enabled": false}}}}"#,).unwrap();@@ -3578,6 +3632,7 @@ mod tests {cache.set_item("runtime_enabled", false).unwrap();cache.set_item("provider", "redis").unwrap();let config = PyDict::new(py);+ config.set_item("service_name", "runtime-cache").unwrap();config.set_item("cache", cache).unwrap();let kwargs = PyDict::new(py);kwargs@@ -3603,6 +3658,7 @@ mod tests {&path,format!(r#"{{+ "service_name": "test-service","cache": {{"provider": "redis", "params": {{"{field}": true}}}},"storage": {{"agfs": {{"cachefs": {{"backend": "cache"}}}}}}}}"#@@ -3610,7 +3666,7 @@ mod tests {).unwrap();- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();assert!(error.contains(field));fs::remove_file(path).unwrap();diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsindex 4c5f4b67c..5fcb858d6 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -79,8 +79,8 @@ pub enum CacheRuntimeProviderConfig {pub struct CacheFsConfig {/// Whether mounted data filesystems are wrapped by CachedFileSystem.pub enabled: bool,- /// CacheFS key namespace.- pub namespace: String,+ /// OpenViking instance name used by CacheFS keys.+ pub service_name: String,/// Existing CacheFS policy and traversal settings.pub policy: CachePolicy,}@@ -90,7 +90,7 @@ impl Default for CacheFsConfig {fn default() -> Self {Self {enabled: false,- namespace: "openviking".into(),+ service_name: String::new(),policy: CachePolicy::default(),}}@@ -156,11 +156,12 @@ pub async fn build_configured_stack(.to_string(),));}- if pathlock_uses_cache- && !matches!(- &cache.provider,- Some(CacheRuntimeProviderConfig::Redis(_))- )+ if cache.cachefs.enabled && cache.cachefs.service_name.trim().is_empty() {+ return Err(Error::config(+ "cachefs service_name is required when CacheFS is enabled".to_string(),+ ));+ }+ if pathlock_uses_cache && !matches!(&cache.provider, Some(CacheRuntimeProviderConfig::Redis(_))){return Err(Error::config("cache-backed PathLock requires the shared cache provider to be redis".to_string(),@@ -197,7 +198,7 @@ pub async fn build_configured_stack(.as_ref().expect("cache provider is validated").clone(),- CacheNamespace::new(&cache.cachefs.namespace),+ CacheNamespace::new(&cache.cachefs.service_name),cache.cachefs.policy,))} else if let Some(runtime) = runtime.as_ref() {@@ -237,18 +238,14 @@ async fn build_stack_with_mountable_and_runtime(let runtime = runtime.clone().ok_or_else(|| {Error::config("cache provider is required for cache-backed PathLock".to_string())})?;- let namespace = config.pathlock.namespace.as_deref().ok_or_else(|| {- Error::config("pathlock namespace is required for cache-backed PathLock".to_string())+ let service_name = config.pathlock.service_name.as_deref().ok_or_else(|| {+ Error::config("pathlock service_name is required for cache-backed PathLock".to_string())})?;Arc::new(- RedisPathLockProvider::new(- runtime,- namespace,- config.pathlock.lock_expire_secs,- )- .map_err(|error| {- Error::config(format!("Redis PathLock initialization failed: {error}"))- })?,+ RedisPathLockProvider::new(runtime, service_name, config.pathlock.lock_expire_secs)+ .map_err(|error| {+ Error::config(format!("Redis PathLock initialization failed: {error}"))+ })?,)}#[cfg(not(feature = "cache"))]@@ -355,7 +352,7 @@ mod tests {}),pathlock: PathLockConfig {provider: "filesystem".to_string(),- namespace: None,+ service_name: None,lock_timeout_secs: 0.0,lock_expire_secs: 30.0,},@@ -561,7 +558,7 @@ mod tests {let config = RagfsConfig {pathlock: PathLockConfig {provider: "cache".to_string(),- namespace: Some("builder-test".to_string()),+ service_name: Some("builder-test".to_string()),..PathLockConfig::default()},..RagfsConfig::default()@@ -581,11 +578,11 @@ mod tests {let Ok(endpoint) = std::env::var("REDIS_URL") else {return;};- let namespace = format!("builder-pathlock-test-{}", std::process::id());+ let service_name = format!("builder-pathlock-test-{}", std::process::id());let config = RagfsConfig {pathlock: PathLockConfig {provider: "cache".to_string(),- namespace: Some(namespace),+ service_name: Some(service_name),lock_expire_secs: 3.0,..PathLockConfig::default()},@@ -664,7 +661,7 @@ mod tests {let mut params = HashMap::new();params.insert("backend".into(), ConfigValue::String("cache".into()));params.insert(- "cache_key_prefix".into(),+ "service_name".into(),ConfigValue::String(format!("builder-test-{}", uuid::Uuid::new_v4())),);diff --git a/crates/ragfs/src/core/mountable.rs b/crates/ragfs/src/core/mountable.rsindex 32d9c201c..530f1d07e 100644--- a/crates/ragfs/src/core/mountable.rs+++ b/crates/ragfs/src/core/mountable.rs@@ -1256,7 +1256,7 @@ mod tests {mount_path: mount_path.to_string(),params: HashMap::new(),backups: Some(BackendsConfig {- namespace: "default".to_string(),+ service_name: "mw-test".to_string(),initial_partitions: 16,checkpoint_interval_secs: 86_400,provider: "filesystem".to_string(),@@ -1768,7 +1768,7 @@ mod tests {let mut params = HashMap::new();params.insert("backend".into(), ConfigValue::String("cache".into()));params.insert(- "cache_key_prefix".into(),+ "service_name".into(),ConfigValue::String("mountable-shutdown-test".into()),);mfs.mount(PluginConfig::single_backend("queuefs", "/queue", params))diff --git a/crates/ragfs/src/core/types.rs b/crates/ragfs/src/core/types.rsindex 9038d4abf..9056b334c 100644--- a/crates/ragfs/src/core/types.rs+++ b/crates/ragfs/src/core/types.rs@@ -558,10 +558,10 @@ impl ConfigValue {/// Multi-write backends container configuration#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]pub struct BackendsConfig {- /// Cache key namespace used by cache-backed metadata.- #[serde(default = "default_backups_namespace")]- pub namespace: String,+ /// OpenViking instance name used by cache-backed metadata.+ pub service_name: String,/// Initial number of metadata partitions.#[serde(default = "default_initial_partitions")]pub initial_partitions: u32,@@ -576,11 +576,6 @@ pub struct BackendsConfig {pub items: Vec<BackendItemConfig>,}-/// Return the default cache-backed metadata namespace.-fn default_backups_namespace() -> String {- "default".to_string()-}-/// Return the default metadata partition count.fn default_initial_partitions() -> u32 {16@@ -695,6 +690,7 @@ mod tests {valid_params.insert("backups".to_string(),ConfigValue::Json(serde_json::json!({+ "service_name": "mw-prod","items": [{"name": "backup1", "backend": "memory"}]})),);@@ -707,7 +703,8 @@ mod tests {ConfigValue::Bool(true),);let config = PluginConfig::from_raw_parts("localfs", "/local", valid_params).unwrap();- assert!(config.backups.is_some());+ let backups = config.backups.as_ref().unwrap();+ assert_eq!(backups.service_name, "mw-prod");assert!(config.server_encryption_enabled);assert!(config.primary_encryption_enabled);assert_eq!(@@ -722,10 +719,20 @@ mod tests {(HashMap::from([("backups".to_string(),- ConfigValue::Json(serde_json::json!({"items": "invalid"})),+ ConfigValue::Json(serde_json::json!({+ "service_name": "mw-prod",+ "items": "invalid"+ })),)]),"invalid 'backups'",),+ (+ HashMap::from([(+ "backups".to_string(),+ ConfigValue::Json(serde_json::json!({"items": []})),+ )]),+ "service_name",+ ),(HashMap::from([("server_encryption_enabled".to_string(),diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rsindex 0f1548ae6..e2b58153d 100644--- a/crates/ragfs/src/git/service.rs+++ b/crates/ragfs/src/git/service.rs@@ -6650,7 +6650,7 @@ mod fast_path1_tests {mount_path: "/local".to_string(),params,backups: Some(BackendsConfig {- namespace: "default".to_string(),+ service_name: "mw-test".to_string(),initial_partitions: 16,checkpoint_interval_secs: 86_400,provider: "filesystem".to_string(),diff --git a/crates/ragfs/src/lock/cache_provder.rs b/crates/ragfs/src/lock/cache_provder.rsindex 29274ac98..543eb4ed8 100644--- a/crates/ragfs/src/lock/cache_provder.rs+++ b/crates/ragfs/src/lock/cache_provder.rs@@ -442,7 +442,7 @@ const SCRIPT_DEFINITIONS: &[ScriptDefinition] = &[/// Redis-backed PathLock provider.pub struct RedisPathLockProvider {runtime: Arc<CacheRuntime>,- namespace: String,+ service_name: String,hash_ttl_ms: i64,}@@ -450,16 +450,16 @@ impl RedisPathLockProvider {/// Create Redis-backed PathLock storage and register its Lua scripts.pub fn new(runtime: Arc<CacheRuntime>,- namespace: &str,+ service_name: &str,lock_expire_secs: f64,) -> PathLockResult<Self> {- if namespace.is_empty()- || !namespace+ if service_name.is_empty()+ || !service_name.bytes().all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-')){return Err(PathLockError::InvalidRequest(- "pathlock Redis namespace must contain only ASCII letters, digits, '.', '_' or '-'"+ "pathlock Redis service_name must contain only ASCII letters, digits, '.', '_' or '-'".to_string(),));}@@ -484,7 +484,7 @@ impl RedisPathLockProvider {}Ok(Self {runtime,- namespace: namespace.to_string(),+ service_name: service_name.to_string(),hash_ttl_ms: hash_ttl_ms as i64,})}@@ -510,7 +510,7 @@ impl RedisPathLockProvider {};Ok(format!("ov:pathlock:{{{}}}:{suffix}:tokens",- self.namespace+ self.service_name))}@@ -1175,12 +1175,12 @@ return redis.call("HGET", KEYS[1], ARGV[2])}).await.unwrap();- let namespace = format!("pathlock-test-{}-{test_name}", std::process::id());- let provider = RedisPathLockProvider::new(runtime.clone(), &namespace, 1.0).unwrap();+ let service_name = format!("pathlock-test-{}-{test_name}", std::process::id());+ let provider = RedisPathLockProvider::new(runtime.clone(), &service_name, 1.0).unwrap();Some((runtime, provider))}- /// Build two managers that share one Redis namespace.+ /// Build two managers that share one service name.async fn test_managers(test_name: &str,) -> Option<(Arc<CacheRuntime>, PathLockManager, PathLockManager, String)> {@@ -1192,15 +1192,15 @@ return redis.call("HGET", KEYS[1], ARGV[2])}).await.unwrap();- let namespace = format!("pathlock-manager-test-{}-{test_name}", std::process::id());+ let service_name = format!("pathlock-manager-test-{}-{test_name}", std::process::id());let config = PathLockConfig {provider: "cache".to_string(),- namespace: Some(namespace.clone()),+ service_name: Some(service_name.clone()),lock_timeout_secs: 0.0,lock_expire_secs: 3.0,};let first_provider =- Arc::new(RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap());+ Arc::new(RedisPathLockProvider::new(runtime.clone(), &service_name, 3.0).unwrap());let key = first_provider.tokens_key_for_path("/local/account-a").unwrap();@@ -1211,7 +1211,7 @@ return redis.call("HGET", KEYS[1], ARGV[2]));let second = PathLockManager::new(Arc::new(MemFileSystem::new()),- Arc::new(RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap()),+ Arc::new(RedisPathLockProvider::new(runtime.clone(), &service_name, 3.0).unwrap()),config,);Some((runtime, first, second, key))@@ -1246,8 +1246,8 @@ return redis.call("HGET", KEYS[1], ARGV[2])}).await.unwrap();- let namespace = format!("pathlock-topology-test-{}-{test_name}", std::process::id());- let provider = RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap();+ let service_name = format!("pathlock-topology-test-{}-{test_name}", std::process::id());+ let provider = RedisPathLockProvider::new(runtime.clone(), &service_name, 3.0).unwrap();provider.try_acquire_batch_atomic(@@ -1290,7 +1290,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])}}- /// Verify invalid namespace and expiry values are rejected before Redis access.+ /// Verify invalid service_name and expiry values are rejected before Redis access.#[test]fn provider_rejects_invalid_configuration() {let runtime = CacheRuntime::memory();@@ -1325,7 +1325,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])("/local/account-a/resources/a.md", "scope:account:account-a"),("/local/account-b/resources/b.md", "scope:account:account-b"),];- let namespace = format!("pathlock-test-{}-scope-keys", std::process::id());+ let service_name = format!("pathlock-test-{}-scope-keys", std::process::id());for (index, (path, scope)) in cases.iter().enumerate() {provider.try_create_token(@@ -1337,7 +1337,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])let raw = runtime.execute_script(ScriptRequest {script_id: TEST_HASH_ID.to_string(),- keys: vec![format!("ov:pathlock:{{{namespace}}}:{scope}:tokens")],+ keys: vec![format!("ov:pathlock:{{{service_name}}}:{scope}:tokens")],args: vec![RedisPathLockProvider::bytes("get"),RedisPathLockProvider::bytes(path),@@ -1782,7 +1782,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])provider.clone(),PathLockConfig {provider: "cache".to_string(),- namespace: Some("timeout-test".to_string()),+ service_name: Some("timeout-test".to_string()),..PathLockConfig::default()},);@@ -1806,7 +1806,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])provider.clone(),PathLockConfig {provider: "cache".to_string(),- namespace: Some("race-test".to_string()),+ service_name: Some("race-test".to_string()),lock_expire_secs: 1.0,..PathLockConfig::default()},diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex cef2bdb7e..e5a64e442 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -31,7 +31,7 @@ pub struct PathLockConfig {/// Built-in provider name: `filesystem`, `memory`, or `cache`.pub provider: String,/// OpenViking instance name used by the cache-backed provider.- pub namespace: Option<String>,+ pub service_name: Option<String>,/// Default wait timeout for auto-acquired locks.pub lock_timeout_secs: f64,/// Seconds after which a lock token is considered stale.@@ -42,7 +42,7 @@ impl Default for PathLockConfig {fn default() -> Self {Self {provider: "filesystem".to_string(),- namespace: None,+ service_name: None,lock_timeout_secs: 0.0,lock_expire_secs: 30.0,}diff --git a/crates/ragfs/src/multibackend/factory.rs b/crates/ragfs/src/multibackend/factory.rsindex da9d8d4bc..5bf37e7f1 100644--- a/crates/ragfs/src/multibackend/factory.rs+++ b/crates/ragfs/src/multibackend/factory.rs@@ -111,7 +111,7 @@ pub(crate) async fn build_inactive_multi_write_fs(Arc::new(CacheProvider::new(metadata_store.clone(),runtime,- bc.namespace.clone(),+ bc.service_name.clone(),)?)}#[cfg(not(feature = "cache"))]diff --git a/crates/ragfs/src/plugins/queuefs/mod.rs b/crates/ragfs/src/plugins/queuefs/mod.rsindex f3da2c4b3..cf074939e 100644--- a/crates/ragfs/src/plugins/queuefs/mod.rs+++ b/crates/ragfs/src/plugins/queuefs/mod.rs@@ -106,7 +106,7 @@ struct ParsedBackendConfig {sqlite_db_path: Option<String>,sqlite_options: SQLiteQueueOptions,#[cfg(feature = "cache")]- cache_key_prefix: Option<String>,+ service_name: Option<String>,}/// Parsed path information@@ -689,11 +689,9 @@ impl QueueFSPlugin {"SQLite busy timeout in milliseconds",),#[cfg(feature = "cache")]- ConfigParameter::optional(- "cache_key_prefix",- "string",- "default",- "Queue key namespace when backend=cache",+ ConfigParameter::required_string(+ "service_name",+ "OpenViking service name when backend=cache",),],#[cfg(feature = "cache")]@@ -776,18 +774,22 @@ impl QueueFSPlugin {}};#[cfg(feature = "cache")]- let cache_key_prefix = match kind {+ let service_name = match kind {BackendKind::Cache => {- let prefix = Self::get_string_param(config, "cache_key_prefix")- .unwrap_or("default")+ let service_name = Self::get_string_param(config, "service_name")+ .ok_or_else(|| {+ Error::config(+ "queuefs service_name is required when backend=cache".to_string(),+ )+ })?.to_string();- if prefix.trim().is_empty() || prefix.contains(['{', '}']) {+ if service_name.trim().is_empty() || service_name.contains(['{', '}']) {return Err(Error::config(- "queuefs cache_key_prefix must be non-empty and must not contain '{' or '}'"+ "queuefs service_name must be non-empty and must not contain '{' or '}'".to_string(),));}- Some(prefix)+ Some(service_name)}_ => None,};@@ -800,7 +802,7 @@ impl QueueFSPlugin {busy_timeout_ms,},#[cfg(feature = "cache")]- cache_key_prefix,+ service_name,})}}@@ -890,8 +892,8 @@ impl ServicePlugin for QueueFSPlugin {.expect("cache runtime is validated").clone(),parsed- .cache_key_prefix- .expect("cache key prefix is validated"),+ .service_name+ .expect("queuefs service_name is validated"),).await?,));@@ -1166,7 +1168,7 @@ mod tests {#[cfg(feature = "cache")]assert!(config_params.iter()- .any(|parameter| parameter.name == "cache_key_prefix"));+ .any(|parameter| parameter.name == "service_name"));let config =PluginConfig::single_backend("queuefs", "/queue", std::collections::HashMap::new());diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.mdindex 7e59fe5a0..68af79bd6 100644--- a/docs/en/concepts/09-transaction.md+++ b/docs/en/concepts/09-transaction.md@@ -383,8 +383,8 @@ After startup, QueueManager resumes persisted `session_commit` jobs:Path locks are enabled by default with the `filesystem` provider. Use`storage.agfs.pathlock.provider=cache` for Redis-backed coordination betweenprocesses. Cache-backed PathLock requires a top-level Redis Cache Provider and-a non-empty PathLock namespace. The runtime wait timeout is fixed at `0.0`-seconds. `storage.transaction` remains only as a legacy compatibility layer:+uses top-level `service_name` as the Redis namespace. The runtime wait timeout+is fixed at `0.0` seconds. `storage.transaction` remains only as a legacy compatibility layer:`lock_timeout` is deprecated and ignored, `lock_expire` is automaticallymapped when the new field is unset, and `redo_recovery_enabled` is deprecatedand ignored.@@ -408,6 +408,7 @@ Redis-backed configuration:```json{+ "service_name": "production","cache": {"provider": "redis","params": {@@ -419,7 +420,6 @@ Redis-backed configuration:"agfs": {"pathlock": {"provider": "cache",- "namespace": "production","lock_expire_secs": 30.0}}@@ -430,7 +430,6 @@ Redis-backed configuration:| Parameter | Type | Description | Default ||-----------|------|-------------|---------|| `provider` | str | `filesystem`, `memory`, or `cache` | `filesystem` |-| `namespace` | str or null | Required when `provider=cache`; identifies one OpenViking deployment | `null` || `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale | `30.0` |Legacy compatibility form:diff --git a/docs/en/concepts/12-metrics.md b/docs/en/concepts/12-metrics.mdindex 224b96a9f..96b9b313f 100644--- a/docs/en/concepts/12-metrics.md+++ b/docs/en/concepts/12-metrics.md@@ -527,7 +527,7 @@ Key fields:- `server.observability.metrics.exporters.otel.protocol`: `"grpc"` or `"http"`- `server.observability.metrics.exporters.otel.tls.insecure`: OTLP/gRPC only; `true` means plaintext (no TLS)- `server.observability.metrics.exporters.otel.endpoint`: OTLP endpoint (for gRPC, use `host:4317`; for HTTP, use a full URL)-- `server.observability.metrics.exporters.otel.service_name`: OTLP `service.name` resource attribute (default `"openviking-server"`)+- `server.observability.metrics.exporters.otel.service_name`: OTLP `service.name` resource attribute; defaults to top-level `service_name` when omitted- `server.observability.metrics.exporters.otel.export_interval_ms`: OTLP push interval in milliseconds (default `10000`)- `server.observability.metrics.exporters.otel.headers`: optional custom OTLP headers; sent as gRPC metadata for gRPC and HTTP headers for HTTP- When using gRPC, header keys in `headers` should be lowercase, for example `x-byteapm-appkey`; HTTP does not have this restrictiondiff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex aa23d3cfa..d6bd29861 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -23,6 +23,7 @@ Create `~/.openviking/ov.conf` in your home configuration directory:```json{+ "service_name": "openviking-server","storage": {"workspace": "./data","vectordb": {@@ -53,6 +54,10 @@ Create `~/.openviking/ov.conf` in your home configuration directory:For `provider: "openai-codex"`, `vlm.api_key` is optional when Codex OAuth is already available.+Top-level `service_name` defaults to `"openviking-server"`. Cache-backed modules use+it as their Redis namespace. OTel `service_name` fields keep their own value+when set and inherit this value when omitted.+### Ordered credentials in ov.conf`vlm` and `query_planner` support an ordered `credentials` array. Embedding supports the same array inside each configured `dense`, `sparse`, or `hybrid` section. Index 0 has the highest priority; later entries provide failover credentials. The model sections remain JSON objects, and existing single-credential configurations remain supported.@@ -1358,6 +1363,10 @@ See the [Multi-Write Storage Guide](./13-multi-write-storage.md) for more exampl##### Global Cache Provider, CacheFS, and PathLock Configuration+Top-level `service_name` names the OpenViking deployment. CacheFS, QueueFS with+`backend=cache`, cache-backed PathLock, and cache-backed multi-write metadata+derive their Redis namespaces from it.+The top-level `cache` section is a sibling of `storage`. Its public shape is Provider-neutral:| Parameter | Type | Description | Default |@@ -1370,7 +1379,6 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro| Parameter | Type | Description | Default ||-----------|------|-------------|---------|| `backend` | str | `local` keeps the original filesystem path; `cache` enables the CacheFS wrapper | `local` |-| `namespace` | str | CacheFS key namespace | `openviking` || `max_file_size_bytes` | int | Maximum full-file object size admitted to cache | `1048576` || `traversal_mode` | str | `backend` or `cached_traversal` | `backend` || `bypass_prefixes` | array[str] | Path prefixes that bypass cache | `[]` |@@ -1380,12 +1388,12 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro| Parameter | Type | Description | Default ||-----------|------|-------------|---------|| `provider` | str | `filesystem`, `memory`, or `cache`; `cache` uses the shared Redis CacheRuntime | `filesystem` |-| `namespace` | str (optional) | OpenViking instance name used in Redis PathLock keys; required when `provider=cache` | `null` || `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale; must be at least `1.0` | `30.0` || `lock_timeout_secs` | float | Deprecated and ignored; runtime wait timeout remains `0.0` | `0.0` |```json{+ "service_name": "production","cache": {"provider": "redis","params": {@@ -1403,16 +1411,13 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro"storage": {"agfs": {"cachefs": {- "backend": "cache",- "namespace": "production"+ "backend": "cache"},"queuefs": {- "backend": "cache",- "cache_key_prefix": "production"+ "backend": "cache"},"pathlock": {"provider": "cache",- "namespace": "production","lock_expire_secs": 30.0}}@@ -1420,9 +1425,9 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro}```-The canonical configuration has no global `cache.enabled`. CacheRuntime is initialized when CacheFS or QueueFS selects `backend=cache`, PathLock selects `provider=cache`, or multi-write selects `backups.provider=cache`. Cache-backed PathLock currently requires `cache.provider=redis`; DynamicProvider is not supported for PathLock. When all modules use local providers, `cache.params` is not parsed and no Provider connection is opened.+The canonical configuration has no global `cache.enabled` and no per-module Redis namespace field. CacheRuntime is initialized when CacheFS or QueueFS selects `backend=cache`, PathLock selects `provider=cache`, or multi-write selects `backups.provider=cache`. Cache-backed PathLock currently requires `cache.provider=redis`; DynamicProvider is not supported for PathLock. When all modules use local providers, `cache.params` is not parsed and no Provider connection is opened.-This is a breaking configuration change. `storage.agfs.cache`, `storage.agfs.queuefs.backend="redis"`, `storage.agfs.queuefs.redis`, and `storage.agfs.backups.provider="redis"` are rejected. Move Provider settings to top-level `cache.provider/cache.params`, select `cachefs.backend="cache"`, `queuefs.backend="cache"`, or `backups.provider="cache"`, use Redis `mode="standalone"` instead of `singleton`, and use `rediss://` instead of `tls_enabled`.+Move Provider settings to top-level `cache.provider/cache.params`, set top-level `service_name` for shared Redis names, select `cachefs.backend="cache"`, `queuefs.backend="cache"`, or `backups.provider="cache"`, use Redis `mode="standalone"` instead of `singleton`, and use `rediss://` instead of `tls_enabled`.##### QueueFS Configuration@@ -1433,21 +1438,20 @@ This is a breaking configuration change. `storage.agfs.cache`, `storage.agfs.que| `db_path` | str (optional) | SQLite database path for QueueFS when backend is `"sqlite"` or `"sqlite3"` | `null` || `recover_stale_sec` | int | Recover `processing` queue messages older than this many seconds on startup. `0` means recover all stale processing messages | `0` || `busy_timeout_ms` | int | SQLite busy timeout for QueueFS in milliseconds | `5000` |-| `cache_key_prefix` | str | QueueFS key namespace when backend is `"cache"` | `"default"` |Notes:- QueueFS defaults to `sqlite` even if the main AGFS storage backend is `local`, `s3`, or `memory`.- `mode=shared` keeps the historical global queue namespace at `/queue`; `mode=worker` isolates each worker under `/queue/worker-<index|pid>`.- `db_path` is only used when QueueFS backend is `sqlite` or `sqlite3`.-- `backend=cache` automatically binds the global `cache.provider + cache.params` configuration.+- `backend=cache` automatically binds the global `cache.provider + cache.params` configuration and uses top-level `service_name` as the key prefix.- `recover_stale_sec` and `busy_timeout_ms` apply only to SQLite backends.- Redis Cluster endpoints are seed nodes, and `db` must be `0`. Slot routing, `MOVED`/`ASK`, topology refresh, and reconnects are handled by Fred RedisProvider.- Redis Sentinel endpoints are Sentinel nodes and require a non-empty `master_name`; the provider handles master discovery and reconnects.- `username` and `password` authenticate data nodes; `sentinel_username` and `sentinel_password` authenticate Sentinel nodes.- All Redis reads go to the primary. Replica reads are not configurable.- `tls_insecure_skip_verify=true` requires `rediss://` endpoints.-- QueueFS cache keys use `{cache_key_prefix}:ov:*`; use different prefixes for deployments or tenants sharing one Redis cluster.+- QueueFS cache keys use `{service_name}:ov:*`; use different service names for deployments sharing one Redis cluster.- Redis backend runs three bounded `recover_stale` sweeps in a dedicated startup recovery thread at startup, 30 seconds, and 60 seconds to cover the heartbeat-expiry window after a container restart; it does not run long-lived periodic recovery.- If both `storage.agfs.queuefs.db_path` and legacy `storage.agfs.queue_db_path` are set, `storage.agfs.queuefs.db_path` wins.- If QueueFS backend is `memory`, any `db_path` or legacy `queue_db_path` is ignored.@@ -2011,7 +2015,7 @@ For startup and deployment details see [Deployment](./03-deployment.md), for aut## storage.transaction Section-`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` for the active PathLock provider, namespace, and expiry configuration. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is ignored.+`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` for the active PathLock provider and expiry configuration; Redis key names come from top-level `service_name`. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is ignored.Recommended configuration:diff --git a/docs/en/guides/14-ragfs-cache.md b/docs/en/guides/14-ragfs-cache.mdindex 0da4bfc31..8419ece34 100644--- a/docs/en/guides/14-ragfs-cache.md+++ b/docs/en/guides/14-ragfs-cache.md@@ -4,7 +4,7 @@ RAGFS cache is an optional read-cache layer for OpenViking. It speeds up full fiCachedFileSystem assumptions:-- Only one OpenViking / RAGFS process writes to the same namespace.+- Only one OpenViking / RAGFS process writes to the same cache namespace.- File and directory changes go through RAGFS.- The backend is not modified externally by bypassing RAGFS.- After a cache Provider successfully writes or deletes one key, later reads of that key do not return the old value.@@ -25,6 +25,7 @@ Configure the global top-level `cache` Provider, then select `backend=cache` und```json{+ "service_name": "openviking-server","cache": {"provider": "redis","params": {@@ -42,13 +43,11 @@ Configure the global top-level `cache` Provider, then select `backend=cache` und"backend": "local","cachefs": {"backend": "cache",- "namespace": "openviking","max_file_size_bytes": 1048576,"bypass_prefixes": ["/queue", "/tmp"]},"pathlock": {"provider": "cache",- "namespace": "openviking","lock_expire_secs": 30.0}}@@ -87,9 +86,10 @@ Available Providers:Set `storage.agfs.pathlock.provider` to `cache` to coordinate path locksbetween OpenViking processes through the shared Redis CacheRuntime.-`pathlock.namespace` is required and must be the same for every process in-one OpenViking deployment; use distinct namespaces for independent deployments. Distributed path locking does not remove the single-writer requirement of CachedFileSystem. Cache-backed PathLock only supports the built-in-Redis Provider.+OpenViking derives the PathLock Redis namespace from top-level `service_name`.+Use distinct service names for independent deployments. Distributed path+locking does not remove the single-writer requirement of CachedFileSystem.+Cache-backed PathLock only supports the built-in Redis Provider.Redis HASH keys are partitioned by logical path scope:@@ -99,8 +99,9 @@ ov:pathlock:{namespace}:scope:_system:tokensov:pathlock:{namespace}:scope:account:{account}:tokens```-`{namespace}` is the Redis Cluster hash tag, so all PathLock keys for one-deployment remain in one slot. Tree conflict checks scan only the HASH for+`{namespace}` is derived from `service_name` and used as the Redis Cluster+hash tag, so all PathLock keys for one deployment remain in one slot. Tree+conflict checks scan only the HASH forthe request scope. `/` and `/local` use the global HASH but do not scanaccount or `_system` HASHes. A batch containing paths from different scopesis rejected.@@ -121,9 +122,6 @@ Legacy cache configuration is no longer accepted. Migrate before upgrading:| Redis `mode="singleton"` | `mode="standalone"` || `tls_enabled=true` | use `rediss://` endpoints || `read_from_replica` | removed; all reads use the primary |-| Redis Provider `key_prefix` | CacheFS uses `cachefs.namespace`; QueueFS uses `queuefs.cache_key_prefix` |--OpenViking rejects removed fields with a migration error instead of silently translating them.## DynamicProvider@@ -143,6 +141,10 @@ External Providers can be upgraded independently without rebuilding the default## Configuration+Top-level `service_name` defaults to `"openviking-server"` and supplies the Redis+namespace for CacheFS, QueueFS cache backend, cache-backed PathLock, and+cache-backed multi-write metadata.+The top-level `cache` section is a sibling of `storage`:| Option | Type | Default | Description |@@ -155,7 +157,6 @@ The top-level `cache` section is a sibling of `storage`:| Option | Type | Default | Description ||--------|------|---------|-------------|| `backend` | str | `"local"` | `local` preserves existing behavior; `cache` enables CachedFileSystem |-| `namespace` | str | `"openviking"` | Cache namespace for isolating deployments or tenants || `max_file_size_bytes` | int | `1048576` | Maximum full-file object size admitted to cache || `traversal_mode` | str | `"backend"` | Use backend traversal or `cached_traversal` for recursive APIs || `bypass_prefixes` | list[str] | `[]` | Path prefixes that always bypass cache |@@ -165,7 +166,6 @@ The top-level `cache` section is a sibling of `storage`:| Option | Type | Default | Description ||--------|------|---------|-------------|| `provider` | str | `"filesystem"` | `filesystem`, `memory`, or `cache` |-| `namespace` | str or null | `null` | Required deployment namespace shared by collaborating processes when `provider=cache` || `lock_expire_secs` | float | `30.0` | Lock stale timeout; must be at least `1.0` |Redis configuration:diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.mdindex 5fcbda7b9..44f577237 100644--- a/docs/zh/concepts/09-transaction.md+++ b/docs/zh/concepts/09-transaction.md@@ -393,8 +393,8 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败路径锁默认启用,并使用 `filesystem` Provider。多进程通过 Redis 协调时,设置 `storage.agfs.pathlock.provider=cache`。Cache PathLock 要求配置顶层-Redis Cache Provider 和非空 PathLock namespace。运行时等待超时固定为-`0.0` 秒。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout`+Redis Cache Provider,并使用顶层 `service_name` 作为 Redis namespace。+运行时等待超时固定为 `0.0` 秒。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout`已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。@@ -417,6 +417,7 @@ Redis 配置:```json{+ "service_name": "production","cache": {"provider": "redis","params": {@@ -428,7 +429,6 @@ Redis 配置:"agfs": {"pathlock": {"provider": "cache",- "namespace": "production","lock_expire_secs": 30.0}}@@ -439,7 +439,6 @@ Redis 配置:| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|| `provider` | str | `filesystem`、`memory` 或 `cache` | `filesystem` |-| `namespace` | str 或 null | `provider=cache` 时必填,用于标识一个 OpenViking 部署 | `null` || `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数 | `30.0` |兼容旧写法:diff --git a/docs/zh/concepts/12-metrics.md b/docs/zh/concepts/12-metrics.mdindex 29c021a12..9b6d36583 100644--- a/docs/zh/concepts/12-metrics.md+++ b/docs/zh/concepts/12-metrics.md@@ -525,7 +525,7 @@ max by (job) (openviking_feedback_events_total{valid="0"})- `server.observability.metrics.exporters.otel.protocol`:`"grpc"` 或 `"http"`- `server.observability.metrics.exporters.otel.tls.insecure`:仅对 OTLP/gRPC 生效;`true` 表示明文连接(无 TLS)- `server.observability.metrics.exporters.otel.endpoint`:OTLP 端点(gRPC 用 `host:4317`;HTTP 必须是完整 URL)-- `server.observability.metrics.exporters.otel.service_name`:OTLP `service.name` 资源属性(默认 `"openviking-server"`)+- `server.observability.metrics.exporters.otel.service_name`:OTLP `service.name` 资源属性;省略时默认继承顶层 `service_name`- `server.observability.metrics.exporters.otel.export_interval_ms`:OTLP 推送间隔,单位毫秒(默认 `10000`)- `server.observability.metrics.exporters.otel.headers`:可选的自定义 OTLP 请求头;gRPC 会作为 metadata 发送,HTTP 会作为 headers 发送- 使用 gRPC 时,`headers` 中的 key 需要使用小写形式,例如 `x-byteapm-appkey`;HTTP 不受该限制diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex b505ad4b1..8f06b0be9 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -23,6 +23,7 @@ openviking-server doctor```json{+ "service_name": "openviking-server","storage": {"workspace": "./data","vectordb": {@@ -54,6 +55,9 @@ openviking-server doctor如果 `provider` 是 `openai-codex`,并且 Codex OAuth 已经就绪,则 `vlm.api_key` 可以省略。+顶层 `service_name` 默认是 `"openviking-server"`。使用 cache 的模块会把它作为+Redis 命名空间。OTel 的 `service_name` 显式配置时保持原值,省略时继承该值。+### ov.conf 的有序凭据数组`vlm` 和 `query_planner` 支持有序的 `credentials` 数组;Embedding 在已配置的 `dense`、`sparse` 或 `hybrid` 节内支持同样的数组。索引 0 优先级最高,后续元素提供故障切换凭据。模型配置节仍是 JSON 对象,原有单凭据配置继续兼容。@@ -1348,6 +1352,10 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects##### 全局 Cache Provider、CacheFS 与 PathLock 配置+顶层 `service_name` 表示当前 OpenViking 部署名。CacheFS、`backend=cache`+的 QueueFS、Cache PathLock 和 cache-backed 多写 metadata 都会从它生成+Redis 命名空间。+全局 `cache` 与 `storage` 并列,标准配置只包含 Provider 名称和 Provider 自有参数:| 参数 | 类型 | 说明 | 默认值 |@@ -1360,7 +1368,6 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|| `backend` | str | `local` 完全沿用原文件系统;`cache` 启用 CacheFS wrapper | `local` |-| `namespace` | str | CacheFS key 命名空间 | `openviking` || `max_file_size_bytes` | int | 允许缓存的单文件最大字节数 | `1048576` || `traversal_mode` | str | `backend` 或 `cached_traversal` | `backend` || `bypass_prefixes` | array[str] | 绕过缓存的路径前缀 | `[]` |@@ -1370,12 +1377,12 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|| `provider` | str | `filesystem`、`memory` 或 `cache`;`cache` 复用 Redis CacheRuntime | `filesystem` |-| `namespace` | str(可选) | Redis PathLock key 使用的 OpenViking 实例名;`provider=cache` 时必填 | `null` || `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数;不得小于 `1.0` | `30.0` || `lock_timeout_secs` | float | 已废弃且忽略;运行时等待超时固定为 `0.0` | `0.0` |```json{+ "service_name": "production","cache": {"provider": "redis","params": {@@ -1393,16 +1400,13 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects"storage": {"agfs": {"cachefs": {- "backend": "cache",- "namespace": "production"+ "backend": "cache"},"queuefs": {- "backend": "cache",- "cache_key_prefix": "production"+ "backend": "cache"},"pathlock": {"provider": "cache",- "namespace": "production","lock_expire_secs": 30.0}}@@ -1410,9 +1414,9 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects}```-标准配置没有全局 `cache.enabled`。当 CacheFS 或 QueueFS 选择 `backend=cache`、PathLock 选择 `provider=cache`,或多写选择 `backups.provider=cache` 时初始化 CacheRuntime。Cache PathLock 当前只支持 `cache.provider=redis`,不支持 DynamicProvider。全部模块使用本地 Provider 时不解析 `cache.params`,也不连接 Provider。+标准配置没有全局 `cache.enabled`,也没有各模块自己的 Redis namespace 字段。当 CacheFS 或 QueueFS 选择 `backend=cache`、PathLock 选择 `provider=cache`,或多写选择 `backups.provider=cache` 时初始化 CacheRuntime。Cache PathLock 当前只支持 `cache.provider=redis`,不支持 DynamicProvider。全部模块使用本地 Provider 时不解析 `cache.params`,也不连接 Provider。-这是一次配置破坏性变更:`storage.agfs.cache`、`storage.agfs.queuefs.backend="redis"`、`storage.agfs.queuefs.redis` 和 `storage.agfs.backups.provider="redis"` 已删除并会被拒绝。请把 Provider 参数迁移到顶层 `cache.provider/cache.params`,业务模块改为 `cachefs.backend="cache"`、`queuefs.backend="cache"` 或 `backups.provider="cache"`;Redis 的 `singleton` 改为 `standalone`,`tls_enabled` 改为使用 `rediss://` endpoint。+请把 Provider 参数迁移到顶层 `cache.provider/cache.params`,用顶层 `service_name` 生成共享 Redis 名称,业务模块改为 `cachefs.backend="cache"`、`queuefs.backend="cache"` 或 `backups.provider="cache"`;Redis 的 `singleton` 改为 `standalone`,`tls_enabled` 改为使用 `rediss://` endpoint。##### QueueFS 配置@@ -1423,7 +1427,6 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects| `db_path` | str(可选) | 当 backend 为 `"sqlite"` 或 `"sqlite3"` 时使用的 QueueFS sqlite 数据库路径 | `null` || `recover_stale_sec` | int | 启动时恢复超过该秒数的 `processing` 队列消息;`0` 表示恢复全部 stale processing 消息 | `0` || `busy_timeout_ms` | int | QueueFS sqlite 的 busy timeout,单位毫秒 | `5000` |-| `cache_key_prefix` | str | 当 backend 为 `"cache"` 时使用的 QueueFS key 命名空间 | `"default"` |说明:@@ -1431,11 +1434,11 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects- `mode=shared` 会继续使用历史上的全局队列命名空间 `/queue`;`mode=worker` 会为每个 worker 隔离到 `/queue/worker-<index|pid>`。- `db_path` 仅在 QueueFS backend 为 `sqlite` 或 `sqlite3` 时生效。- `recover_stale_sec` 和 `busy_timeout_ms` 仅在 QueueFS backend 为 `sqlite` 或 `sqlite3` 时生效。-- `queuefs.backend=cache` 自动绑定顶层 `cache.provider + cache.params`。+- `queuefs.backend=cache` 自动绑定顶层 `cache.provider + cache.params`,并使用顶层 `service_name` 作为 key 前缀。- Redis Cluster 模式的 endpoints 是初始节点,且必须配置 `db=0`;slot 路由、`MOVED`/`ASK`、拓扑更新和重连由 Fred RedisProvider 处理。- Redis Sentinel 模式的 endpoints 是 Sentinel 节点,并且必须配置非空 `master_name`;master 发现和故障切换后的重连由 Fred RedisProvider 处理。- `username` 和 `password` 用于 Redis 数据节点;`sentinel_username` 和 `sentinel_password` 仅用于 Sentinel 节点。-- Cache backend 使用 `{cache_key_prefix}:ov:*` key;连接同一 Redis 集群的不同环境或租户必须配置不同的 `cache_key_prefix`。+- Cache backend 使用 `{service_name}:ov:*` key;连接同一 Redis 集群的不同部署必须配置不同的 `service_name`。- Cache backend 的实例心跳 TTL 为 30 秒,每 10 秒续约一次。- Cache backend 会在独立的 startup recovery 任务中按实例心跳状态执行三次有界 `recover_stale` 扫描,时间点分别为启动后立即、30 秒和 60 秒,用于覆盖容器异常退出后旧实例心跳尚未过期的恢复窗口;正常关闭会先删除 heartbeat,使新实例可以立即恢复 processing 消息。- 所有 Redis 读命令都发送到主节点,不提供副本读配置。@@ -2093,7 +2096,7 @@ ov add-resource ./docs --exclude "*.tmp"## storage.transaction 段-`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock` 配置 PathLock Provider、namespace 和过期时间。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。+`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock` 配置 PathLock Provider 和过期时间;Redis key 名称来自顶层 `service_name`。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。推荐写法:diff --git a/docs/zh/guides/14-ragfs-cache.md b/docs/zh/guides/14-ragfs-cache.mdindex 318ffd301..174d961c0 100644--- a/docs/zh/guides/14-ragfs-cache.md+++ b/docs/zh/guides/14-ragfs-cache.md@@ -4,7 +4,7 @@ RAGFS 缓存是 OpenViking 的可选读缓存层,用于加速文件全量读CachedFileSystem 适用前提:-- 只有一个 OpenViking / RAGFS 进程写入同一 namespace。+- 只有一个 OpenViking / RAGFS 进程写入同一 cache namespace。- 文件和目录变更都经过 RAGFS。- backend 不被外部绕过 RAGFS 直接修改。- 缓存 Provider 的同一 key 写入或删除成功后,后续读取不会返回旧值。@@ -24,6 +24,7 @@ openviking-server doctor```json{+ "service_name": "openviking-server","cache": {"provider": "redis","params": {@@ -41,13 +42,11 @@ openviking-server doctor"backend": "local","cachefs": {"backend": "cache",- "namespace": "openviking","max_file_size_bytes": 1048576,"bypass_prefixes": ["/queue", "/tmp"]},"pathlock": {"provider": "cache",- "namespace": "openviking","lock_expire_secs": 30.0}}@@ -85,9 +84,9 @@ openviking-server### Cache PathLock将 `storage.agfs.pathlock.provider` 设为 `cache`,即可通过共享 Redis-CacheRuntime 协调多个 OpenViking 进程的路径锁。`pathlock.namespace`-为必填项,同一 OpenViking 部署的所有进程必须使用相同值。Cache PathLock-只支持内置 Redis Provider。独立部署应使用不同 namespace;分布式路径锁不会解除 CachedFileSystem 的单写者前提。+CacheRuntime 协调多个 OpenViking 进程的路径锁。OpenViking 会从顶层+`service_name` 生成 PathLock Redis namespace。独立部署应使用不同+`service_name`。Cache PathLock 只支持内置 Redis Provider;分布式路径锁不会解除 CachedFileSystem 的单写者前提。Redis HASH key 按逻辑路径 scope 拆分:@@ -97,7 +96,7 @@ ov:pathlock:{namespace}:scope:_system:tokensov:pathlock:{namespace}:scope:account:{account}:tokens```-`{namespace}` 是 Redis Cluster hash tag,因此同一部署的 PathLock key+`{namespace}` 来自 `service_name`,也是 Redis Cluster hash tag,因此同一部署的 PathLock key仍位于同一 slot。Tree 冲突检查只扫描请求所属 scope 的 HASH。`/` 和`/local` 使用 global HASH,但不会扫描 account 或 `_system` HASH。跨 scope batch 会被拒绝。@@ -116,9 +115,6 @@ ov:pathlock:{namespace}:scope:account:{account}:tokens| Redis `mode="singleton"` | `mode="standalone"` || `tls_enabled=true` | endpoint 使用 `rediss://` || `read_from_replica` | 已删除,所有读命令统一访问主节点 |-| Redis Provider `key_prefix` | CacheFS 使用 `cachefs.namespace`;QueueFS 使用 `queuefs.cache_key_prefix` |--OpenViking 会对已删除字段直接返回迁移错误,不再静默转换。## DynamicProvider@@ -138,6 +134,9 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本## 配置项+顶层 `service_name` 默认是 `"openviking-server"`,会为 CacheFS、QueueFS cache backend、+Cache PathLock 和 cache-backed 多写 metadata 提供 Redis namespace。+顶层 `cache` 与 `storage` 并列:| 参数 | 类型 | 默认值 | 说明 |@@ -150,7 +149,6 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本| 参数 | 类型 | 默认值 | 说明 ||------|------|--------|------|| `backend` | str | `"local"` | `local` 沿用原逻辑;`cache` 启用 CachedFileSystem |-| `namespace` | str | `"openviking"` | 缓存命名空间,用于隔离不同部署或租户 || `max_file_size_bytes` | int | `1048576` | 允许进入缓存的最大完整文件大小 || `traversal_mode` | str | `"backend"` | 递归 API 使用 backend 遍历或 `cached_traversal` || `bypass_prefixes` | list[str] | `[]` | 强制绕过缓存的路径前缀 |@@ -160,7 +158,6 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本| 参数 | 类型 | 默认值 | 说明 ||------|------|--------|------|| `provider` | str | `"filesystem"` | `filesystem`、`memory` 或 `cache` |-| `namespace` | str 或 null | `null` | `provider=cache` 时必填,同一部署的协作进程共享此命名空间 || `lock_expire_secs` | float | `30.0` | 锁 stale 超时;不得小于 `1.0` |Redis 配置:diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 8650d0b0c..594b69ee6 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -1,4 +1,5 @@{+ "service_name": "openviking-server","server": {"host": "0.0.0.0","port": 1933,@@ -90,13 +91,11 @@},"cachefs": {"backend": "local",- "namespace": "openviking","max_file_size_bytes": 1048576,"bypass_prefixes": ["/queue", "/tmp"],},"queuefs": {"backend": "sqlite",- "cache_key_prefix": "default",},"pathlock": {"provider": "filesystem",diff --git a/openviking/server/config.py b/openviking/server/config.pyindex 798642b4a..4f07f587a 100644--- a/openviking/server/config.py+++ b/openviking/server/config.py@@ -19,7 +19,9 @@ from openviking_cli.utils.config.config_loader import (resolve_config_path,)from openviking_cli.utils.config.config_utils import (+ DEFAULT_SERVICE_NAME,format_validation_error,+ normalize_service_name,warn_unknown_config_fields,)from openviking_cli.utils.config.consts import (@@ -430,6 +432,36 @@ def get_server_url_from_server_data(server_data: object) -> str:return f"http://{host}:{port}"+def _inherit_otel_service_names(server_data: Dict[str, Any], service_name: str) -> None:+ """Fill omitted OTel service_name fields from the top-level service name."""+ if "observability" not in server_data:+ server_data["observability"] = {}+ observability = server_data["observability"]+ if not isinstance(observability, dict):+ return++ for key in ("traces", "logs"):+ if key not in observability:+ observability[key] = {"service_name": service_name}+ elif isinstance(observability[key], dict) and "service_name" not in observability[key]:+ observability[key]["service_name"] = service_name++ if "metrics" not in observability:+ observability["metrics"] = {}+ metrics = observability["metrics"]+ if not isinstance(metrics, dict):+ return+ if "exporters" not in metrics:+ metrics["exporters"] = {}+ exporters = metrics["exporters"]+ if not isinstance(exporters, dict):+ return+ if "otel" not in exporters:+ exporters["otel"] = {"service_name": service_name}+ elif isinstance(exporters["otel"], dict) and "service_name" not in exporters["otel"]:+ exporters["otel"]["service_name"] = service_name++def load_server_config(config_path: Optional[str] = None) -> ServerConfig:"""Load server configuration from ov.conf.@@ -467,6 +499,9 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:server_data = {}if not isinstance(server_data, dict):raise ValueError(f"Invalid server config in {path}: 'server' section must be an object")+ server_data = dict(server_data)+ service_name = normalize_service_name(data.get("service_name", DEFAULT_SERVICE_NAME))+ _inherit_otel_service_names(server_data, service_name)# Convert auth_mode string — built-in enums are converted to their string# value; custom modes are kept as-is for plugin extensibility.diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.pyindex 6acc259e1..396e35a63 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -13,6 +13,10 @@ from threading import Threadfrom typing import Any, Callable, Dictfrom openviking_cli.utils.config.config_loader import resolve_config_path+from openviking_cli.utils.config.config_utils import (+ DEFAULT_SERVICE_NAME,+ normalize_service_name,+)from openviking_cli.utils.config.consts import DEFAULT_OV_CONF, OPENVIKING_CONFIG_ENVfrom openviking_cli.utils.logger import get_logger@@ -28,6 +32,11 @@ class RagfsBindingConfig:root_key: bytes | None = Noneprovider_type: int | None = Nonelog: Dict[str, Any] | None = None+ service_name: str = DEFAULT_SERVICE_NAME++ def __post_init__(self) -> None:+ """Validate the service name used by cache-backed modules."""+ object.__setattr__(self, "service_name", normalize_service_name(self.service_name))def encryption_enabled(self) -> bool:"""Return whether the binding stack should include the encryption layer."""@@ -60,17 +69,19 @@ class RagfsBindingConfig:cachefs,cachefs_backend == "cache",uses_runtime,+ self.service_name,)elif self.cache is not None:- cache_config = _disabled_cache_config(cachefs)+ cache_config = _disabled_cache_config(cachefs, self.service_name)else:if uses_runtime:raise ValueError("top-level cache config is required when CacheFS, QueueFS, cache-backed PathLock, ""or cache-backed multi-write uses the shared Runtime")- cache_config = _disabled_cache_config(cachefs)+ cache_config = _disabled_cache_config(cachefs, self.service_name)binding_config: Dict[str, Any] = {+ "service_name": self.service_name,"cache": cache_config,"pathlock": pathlock,}@@ -91,13 +102,16 @@ class RagfsBindingConfig:return binding_config-def _disabled_cache_config(cachefs_model: Any) -> Dict[str, Any]:+def _disabled_cache_config(+ cachefs_model: Any, service_name: str = DEFAULT_SERVICE_NAME+) -> Dict[str, Any]:+ """Build the disabled cache config shape; service_name is carried at binding top level."""+ normalize_service_name(service_name)traversal_mode = getattr(cachefs_model, "traversal_mode", "backend")return {"enabled": False,"runtime_enabled": False,"provider": "redis",- "namespace": getattr(cachefs_model, "namespace", "openviking"),"max_file_size_bytes": getattr(cachefs_model, "max_file_size_bytes", 1024 * 1024),"traversal_mode": getattr(traversal_mode, "value", traversal_mode),"bypass_prefixes": list(getattr(cachefs_model, "bypass_prefixes", [])),@@ -109,10 +123,12 @@ def _build_provider_cache_config(cachefs_model: Any,cachefs_enabled: bool,runtime_enabled: bool,+ service_name: str,) -> Dict[str, Any]:+ """Build a provider-backed cache config that shares the top-level service name."""provider = provider_config.provider.strip()params = dict(provider_config.params)- cache_config = _disabled_cache_config(cachefs_model)+ cache_config = _disabled_cache_config(cachefs_model, service_name)cache_config.update({"enabled": cachefs_enabled,@@ -200,6 +216,7 @@ def build_runtime_ragfs_binding_config(config: Any) -> tuple[RagfsBindingConfig,agfs=agfs_config,cache=cache_config,log=binding_log,+ service_name=_get_config_value(config, "service_name", DEFAULT_SERVICE_NAME),), Noneroot_key = _run_coro_blocking(encryptor.provider.get_root_key())@@ -213,6 +230,7 @@ def build_runtime_ragfs_binding_config(config: Any) -> tuple[RagfsBindingConfig,root_key=bytes(root_key),provider_type=encryptor.provider_type,log=binding_log,+ service_name=_get_config_value(config, "service_name", DEFAULT_SERVICE_NAME),),encryptor,)@@ -251,7 +269,9 @@ def resolve_queuefs_mount_point(config: Any = None) -> str:return "/queue"-def _build_queuefs_plugin_config(agfs_config: Any, data_path: Path) -> Dict[str, Any]:+def _build_queuefs_plugin_config(+ agfs_config: Any, data_path: Path, service_name: str = DEFAULT_SERVICE_NAME+) -> Dict[str, Any]:"""Build QueueFS plugin configuration from AGFS config."""default_queue_db_path = data_path / "_system" / "queue" / "queue.db"queuefs_config = getattr(agfs_config, "queuefs", None)@@ -276,15 +296,20 @@ def _build_queuefs_plugin_config(agfs_config: Any, data_path: Path) -> Dict[str,plugin_config["db_path"] = queue_db_pathif backend == "cache":- plugin_config["cache_key_prefix"] = queuefs_config.cache_key_prefix+ plugin_config["service_name"] = service_namereturn plugin_configdef _generate_plugin_config(- agfs_config: Any, data_path: Path, server_encryption_enabled: bool = False+ agfs_config: Any,+ data_path: Path,+ server_encryption_enabled: bool = False,+ *,+ service_name: str = DEFAULT_SERVICE_NAME,) -> Dict[str, Any]:"""Dynamically generate RAGFS plugin configuration based on backend type."""+ service_name = normalize_service_name(service_name)config = {"serverinfofs": {"enabled": True,@@ -296,7 +321,7 @@ def _generate_plugin_config("queuefs": {"enabled": True,"path": "/queue",- "config": _build_queuefs_plugin_config(agfs_config, data_path),+ "config": _build_queuefs_plugin_config(agfs_config, data_path, service_name),},}@@ -326,7 +351,7 @@ def _generate_plugin_config(# Add multi-write fields if backups are configuredif backups_config is not None:# Serialize backups config to dict for FFI JSON passthrough- mount_config["backups"] = _serialize_backups_config(backups_config, data_path)+ mount_config["backups"] = _serialize_backups_config(backups_config, data_path, service_name)mount_config["server_encryption_enabled"] = server_encryption_enabledmount_config["primary_encryption_enabled"] = server_encryption_enabled@@ -405,7 +430,7 @@ def _serialize_s3_plugin_params(s3_config: Any) -> Dict[str, Any]:def _dump_config_object(config: Any) -> Dict[str, Any]:- """Dump a pydantic or namespace-like config object without None values."""+ """Dump a pydantic or attribute-style config object without None values."""if hasattr(config, "model_dump"):return config.model_dump(exclude_none=True)if isinstance(config, dict):@@ -482,7 +507,9 @@ def _normalize_backup_item(item: Any, data_path: Path) -> Dict[str, Any]:return item_dict-def _serialize_backups_config(backups_config: Any, data_path: Path) -> Dict[str, Any]:+def _serialize_backups_config(+ backups_config: Any, data_path: Path, service_name: str = DEFAULT_SERVICE_NAME+) -> Dict[str, Any]:"""Serialize V2 backups while warning about and stripping legacy fields."""result = _dump_config_object(backups_config)deprecated_fields = []@@ -516,6 +543,7 @@ def _serialize_backups_config(backups_config: Any, data_path: Path) -> Dict[str,"Deprecated backups configuration fields are ignored: %s",", ".join(dict.fromkeys(deprecated_fields)),)+ result["service_name"] = service_namereturn result@@ -653,7 +681,12 @@ def mount_agfs_backend(agfs: Any, config: RagfsBindingConfig | Any) -> None:config.encryption_enabled() if isinstance(config, RagfsBindingConfig) else False)config = _generate_plugin_config(- agfs_config, data_path, server_encryption_enabled=server_encryption_enabled+ agfs_config,+ data_path,+ server_encryption_enabled=server_encryption_enabled,+ service_name=config.service_name+ if isinstance(config, RagfsBindingConfig)+ else DEFAULT_SERVICE_NAME,)for plugin_name, plugin_config in config.items():diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.pyindex fb8de031b..d4698a0db 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -135,13 +135,9 @@ class QueueFSConfig(BaseModel):description="SQLite busy timeout for QueueFS in milliseconds.",)- cache_key_prefix: str = Field(- default="default",- description="Queue key namespace when backend is 'cache'.",- )-@model_validator(mode="after")def validate_config(self):+ """Validate QueueFS mode and backend choices."""valid_modes = {"shared", "worker"}if self.mode not in valid_modes:raise ValueError("queuefs mode must be one of: 'shared', 'worker'")@@ -156,12 +152,6 @@ class QueueFSConfig(BaseModel):raise ValueError("queuefs recover_stale_sec must be >= 0")if self.busy_timeout_ms < 0:raise ValueError("queuefs busy_timeout_ms must be >= 0")- if not self.cache_key_prefix.strip() or any(- marker in self.cache_key_prefix for marker in ("{", "}")- ):- raise ValueError(- "queuefs cache_key_prefix must be non-empty and must not contain '{' or '}'"- )return self@@ -179,7 +169,6 @@ class AGFSCacheFSConfig(BaseModel):default="local",description="CacheFS backend: 'local' | 'cache'",)- namespace: str = Field(default="openviking", description="RAGFS cache namespace")max_file_size_bytes: int = Field(default=1024 * 1024,description="Maximum full-file object size admitted to cache",@@ -195,8 +184,7 @@ class AGFSCacheFSConfig(BaseModel):@model_validator(mode="after")def validate_config(self):- if not self.namespace.strip():- raise ValueError("cachefs namespace must not be empty")+ """Validate CacheFS limits."""if self.max_file_size_bytes <= 0:raise ValueError("cachefs max_file_size_bytes must be > 0")return self@@ -312,10 +300,6 @@ class AGFSPathLockConfig(BaseModel):default="filesystem",description="PathLock provider: 'filesystem' | 'memory' | 'cache'",)- namespace: Optional[str] = Field(- default=None,- description="OpenViking instance name used by cache-backed PathLock.",- )lock_timeout_secs: float = Field(default=0.0,description="Deprecated internal field. Runtime auto-pathlock wait timeout is fixed at 0.0 seconds.",@@ -330,18 +314,6 @@ class AGFSPathLockConfig(BaseModel):"""Validate provider and timeout/expiry ranges."""if self.provider not in {"filesystem", "memory", "cache"}:raise ValueError("pathlock provider must be one of: 'filesystem', 'memory', 'cache'")- if self.provider == "cache" and not (self.namespace or "").strip():- raise ValueError("pathlock namespace is required for provider 'cache'")- if self.namespace is not None and (- not self.namespace- or any(- not (char.isascii() and (char.isalnum() or char in "._-"))- for char in self.namespace- )- ):- raise ValueError(- "pathlock namespace must contain only ASCII letters, digits, '.', '_' or '-'"- )if not math.isfinite(self.lock_expire_secs) or self.lock_expire_secs < 1.0:raise ValueError("pathlock lock_expire_secs must be finite and >= 1.0")return selfdiff --git a/openviking_cli/utils/config/config_utils.py b/openviking_cli/utils/config/config_utils.pyindex e2a4d2637..91f4a8c6a 100644--- a/openviking_cli/utils/config/config_utils.py+++ b/openviking_cli/utils/config/config_utils.py@@ -9,6 +9,8 @@ from typing import Any, Optional, get_args, get_originfrom pydantic import BaseModel, ValidationError+DEFAULT_SERVICE_NAME = "openviking-server"+def suggest_closest_field(field_name: str, valid_fields: set[str]) -> Optional[str]:"""Return the closest matching field name when it is similar enough."""@@ -128,6 +130,18 @@ def warn_unknown_config_fields()+def normalize_service_name(value: Any, field_name: str = "service_name") -> str:+ """Return a validated service name for cache namespaces and OTel defaults."""+ if not isinstance(value, str):+ raise ValueError(f"{field_name} must be a string")+ normalized = value.strip()+ if not normalized:+ raise ValueError(f"{field_name} must not be empty")+ if any(not (char.isascii() and (char.isalnum() or char in "._-")) for char in normalized):+ raise ValueError(f"{field_name} must contain only ASCII letters, digits, '.', '_' or '-'")+ return normalized++def format_validation_error(*,root_model: type[BaseModel],diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.pyindex 478a3cae4..3c2b6d0ab 100644--- a/openviking_cli/utils/config/open_viking_config.py+++ b/openviking_cli/utils/config/open_viking_config.py@@ -17,7 +17,9 @@ from .agent_evolution_config import AgentEvolutionConfigfrom .cache_config import CacheConfigfrom .config_loader import resolve_config_pathfrom .config_utils import (+ DEFAULT_SERVICE_NAME,format_validation_error,+ normalize_service_name,warn_unknown_config_fields,warn_unknown_fields,)@@ -196,6 +198,10 @@ class OpenVikingConfig(BaseModel):default=None,description="Deprecated and ignored. User is the only data-plane identity.",)+ service_name: str = Field(+ default=DEFAULT_SERVICE_NAME,+ description="OpenViking deployment name shared by cache namespaces and OTel defaults",+ )cache: Optional[CacheConfig] = Field(default=None,@@ -373,10 +379,23 @@ class OpenVikingConfig(BaseModel):)return self+ @model_validator(mode="after")+ def _validate_service_name(self) -> "OpenVikingConfig":+ """Validate and normalize the top-level service name."""+ self.service_name = normalize_service_name(self.service_name)+ return self+@model_validator(mode="after")def _validate_cache_runtime_config(self) -> "OpenVikingConfig":+ """Require the shared cache Provider whenever AGFS selects a cache-backed runtime."""agfs = self.storage.agfs- uses_canonical_cache = agfs.cachefs.backend == "cache" or agfs.queuefs.backend == "cache"+ backups = agfs.backups or {}+ uses_canonical_cache = (+ agfs.cachefs.backend == "cache"+ or agfs.queuefs.backend == "cache"+ or agfs.pathlock.provider == "cache"+ or backups.get("provider", "filesystem") == "cache"+ )if uses_canonical_cache and self.cache is None:raise ValueError("top-level cache config is required when an AGFS backend uses cache")return selfdiff --git a/openviking_cli/utils/config/telemetry_config.py b/openviking_cli/utils/config/telemetry_config.pyindex 1411bc811..b5b53ff9c 100644--- a/openviking_cli/utils/config/telemetry_config.py+++ b/openviking_cli/utils/config/telemetry_config.py@@ -2,13 +2,15 @@# SPDX-License-Identifier: AGPL-3.0from pydantic import BaseModel, Field+from .config_utils import DEFAULT_SERVICE_NAME+class TracerConfig(BaseModel):"""OpenTelemetry tracer configuration."""enabled: bool = Field(default=False, description="Enable OpenTelemetry tracing")endpoint: str = Field(default="", description="OTLP gRPC endpoint")- service_name: str = Field(default="openviking", description="Service name for tracing")+ service_name: str = Field(default=DEFAULT_SERVICE_NAME, description="Service name for tracing")topic: str = Field(default="", description="Trace topic")ak: str = Field(default="", description="Access key")sk: str = Field(default="", description="Secret key")diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex a632835c8..409e2442e 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -191,8 +191,11 @@ def test_agfs_queuefs_validation_rejects_invalid_shapes(queuefs, match):def test_top_level_cache_provider_params_build_redis_binding_config():+ assert OpenVikingConfig.from_dict({}).service_name == "openviking-server"+config = OpenVikingConfig.from_dict({+ "service_name": "tenant-a","cache": {"provider": "redis","params": {@@ -207,7 +210,7 @@ def test_top_level_cache_provider_params_build_redis_binding_config():},"storage": {"workspace": "/tmp/ov-test",- "agfs": {"cachefs": {"backend": "cache", "namespace": "tenant-a"}},+ "agfs": {"cachefs": {"backend": "cache"}},},})@@ -215,14 +218,15 @@ def test_top_level_cache_provider_params_build_redis_binding_config():binding = RagfsBindingConfig(agfs=config.storage.agfs,cache=config.cache,+ service_name=config.service_name,).to_binding_dict()assert config.cache.provider == "redis"assert config.cache.params["mode"] == "sentinel"+ assert binding["service_name"] == "tenant-a"assert binding["cache"]["enabled"] is Trueassert binding["cache"]["runtime_enabled"] is Trueassert binding["cache"]["provider"] == "redis"- assert binding["cache"]["namespace"] == "tenant-a"assert binding["cache"]["redis"]["mode"] == "sentinel"assert binding["cache"]["redis"]["master_name"] == "mymaster"@@ -230,6 +234,7 @@ def test_top_level_cache_provider_params_build_redis_binding_config():def test_queuefs_cache_uses_top_level_provider_without_enabling_cachefs():config = OpenVikingConfig.model_validate({+ "service_name": "queue-runtime","cache": {"provider": "redis","params": {"endpoints": ["redis://redis:6379"]},@@ -238,10 +243,7 @@ def test_queuefs_cache_uses_top_level_provider_without_enabling_cachefs():"workspace": "/tmp/ov-test","agfs": {"cachefs": {"backend": "local"},- "queuefs": {- "backend": "cache",- "cache_key_prefix": "queue-runtime",- },+ "queuefs": {"backend": "cache"},},},}@@ -250,12 +252,20 @@ def test_queuefs_cache_uses_top_level_provider_without_enabling_cachefs():binding = RagfsBindingConfig(agfs=config.storage.agfs,cache=config.cache,+ service_name=config.service_name,).to_binding_dict()assert binding["cache"]["enabled"] is Falseassert binding["cache"]["runtime_enabled"] is Trueassert binding["cache"]["redis"]["endpoints"] == ["redis://redis:6379"]+ plugins = _generate_plugin_config(+ config.storage.agfs,+ Path("/tmp/ov-test"),+ service_name=config.service_name,+ )+ assert plugins["queuefs"]["config"]["service_name"] == "queue-runtime"+def test_top_level_cache_params_ignore_removed_replica_read_config():config = OpenVikingConfig.model_validate(@@ -736,7 +746,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_pagfs_config = AGFSConfig(path=str(tmp_path),backend="local",- cachefs={"backend": "cache", "namespace": "runtime-cache"},+ cachefs={"backend": "cache"},)config = RagfsBindingConfig(@@ -744,6 +754,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_pcache=CacheConfig(provider="redis", params={}),root_key=b"\x01" * 32,provider_type=7,+ service_name="runtime-cache",)binding = config.to_binding_dict()@@ -754,7 +765,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p}assert binding["cache"]["enabled"] is Trueassert binding["cache"]["runtime_enabled"] is True- assert binding["cache"]["namespace"] == "runtime-cache"+ assert binding["service_name"] == "runtime-cache"assert binding["pathlock"] == {"provider": "filesystem","lock_expire_secs": 30.0,@@ -766,12 +777,13 @@ def test_ragfs_binding_enables_runtime_for_queuefs_cache_backend(tmp_path):agfs_config = AGFSConfig(path=str(tmp_path),backend="local",- queuefs={"backend": "cache", "cache_key_prefix": "queue-runtime"},+ queuefs={"backend": "cache"},)binding = RagfsBindingConfig(agfs=agfs_config,cache=CacheConfig(provider="redis", params={}),+ service_name="queue-runtime",).to_binding_dict()assert binding["cache"]["enabled"] is False@@ -789,35 +801,35 @@ def test_ragfs_binding_enables_runtime_for_multiwrite_cache_provider(tmp_path):binding = RagfsBindingConfig(agfs=agfs_config,cache=CacheConfig(provider="redis", params={}),+ service_name="mw-runtime",).to_binding_dict()+ assert binding["service_name"] == "mw-runtime"assert binding["cache"]["enabled"] is Falseassert binding["cache"]["runtime_enabled"] is True+ backups = _generate_plugin_config(+ agfs_config,+ tmp_path,+ service_name="mw-runtime",+ )["localfs"]["config"]["backups"]+ assert backups["service_name"] == "mw-runtime"+def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):- """PathLock config validates Redis namespace and expiry boundaries."""+ """PathLock config validates provider and expiry boundaries."""config = AGFSConfig(path=str(tmp_path),backend="local",pathlock={"provider": "cache",- "namespace": "prod-a","lock_expire_secs": 60.0,},)assert config.pathlock.provider == "cache"- assert config.pathlock.namespace == "prod-a"assert config.pathlock.lock_expire_secs == 60.0- with pytest.raises(ValueError, match="namespace"):- AGFSConfig(path=str(tmp_path), pathlock={"provider": "cache"})- with pytest.raises(ValueError, match="namespace"):- AGFSConfig(- path=str(tmp_path),- pathlock={"provider": "cache", "namespace": "bad{name}"},- )with pytest.raises(ValueError, match="lock_expire_secs"):AGFSConfig(path=str(tmp_path), pathlock={"lock_expire_secs": 0.0})@@ -832,36 +844,33 @@ def test_redis_pathlock_enables_shared_runtime_without_cachefs(tmp_path):},"storage": {"workspace": str(tmp_path),- "agfs": {- "pathlock": {- "provider": "cache",- "namespace": "prod-a",- }- },+ "agfs": {"pathlock": {"provider": "cache"}},},+ "service_name": "prod-a",})binding = RagfsBindingConfig(agfs=config.storage.agfs,cache=config.cache,+ service_name=config.service_name,).to_binding_dict()assert binding["cache"]["enabled"] is Falseassert binding["cache"]["runtime_enabled"] is Trueassert binding["pathlock"] == {"provider": "cache",- "namespace": "prod-a","lock_expire_secs": 30.0,"lock_timeout_secs": 0.0,}+ assert binding["service_name"] == "prod-a"def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):agfs_config = AGFSConfig(path=str(tmp_path),backend="memory",- cachefs={"backend": "cache", "namespace": "runtime-cache"},+ cachefs={"backend": "cache"},)def _fake_get_binding_client():@@ -872,12 +881,13 @@ def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_pconfig = RagfsBindingConfig(agfs=agfs_config,cache=CacheConfig(provider="redis", params={}),+ service_name="runtime-cache",)client = create_agfs_client(config)assert isinstance(client, _FakeBindingClient)+ assert client.config["service_name"] == "runtime-cache"assert client.config["cache"]["enabled"] is True- assert client.config["cache"]["namespace"] == "runtime-cache"assert any(call[0] == "memfs" for call in client.mount_calls)diff --git a/tests/test_server_config_loader.py b/tests/test_server_config_loader.pyindex 0414eec6a..d78ab065e 100644--- a/tests/test_server_config_loader.py+++ b/tests/test_server_config_loader.py@@ -292,6 +292,7 @@ def test_load_server_config_trace_local_defaults(tmp_path):traces = config.observability.tracesassert traces.enabled is Trueassert traces.protocol == "local"+ assert traces.service_name == "openviking-server"assert traces.local_path == "~/.openviking/logs/traces.jsonl"assert traces.local_rotation_mb == 40assert traces.local_backup_count == 2