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(ragfs): add transactional SQLite path locks (#6679)
zhanglistar15cf3ae28bed
diff --git a/crates/ov_cli/tests/api_key_rotation.rs b/crates/ov_cli/tests/api_key_rotation.rsindex e6341a784..82be9ccbf 100644--- a/crates/ov_cli/tests/api_key_rotation.rs+++ b/crates/ov_cli/tests/api_key_rotation.rs@@ -14,8 +14,18 @@ const OLD_KEY: &str = "YWNtZQ.YWxpY2U.b2xkLXNlY3JldA";const NEW_KEY: &str = "YWNtZQ.YWxpY2U.bmV3LXNlY3JldA";fn run(dir: &Path, args: &[&str]) -> Output {+ let home = dir.join("home");+ let settings_dir = home.join(".openviking");+ fs::create_dir_all(&settings_dir).unwrap();+ fs::write(+ settings_dir.join("ovcli.settings.conf"),+ json!({"language": "en"}).to_string(),+ )+ .unwrap();Command::new(env!("CARGO_BIN_EXE_ov")).current_dir(dir)+ .env("HOME", &home)+ .env("USERPROFILE", &home).env("OPENVIKING_CLI_CONFIG_FILE", "selected.json").env("OPENVIKING_LANG", "en").env("NO_COLOR", "1")@@ -48,6 +58,7 @@ fn serve(Err(error) => panic!("{error}"),}};+ stream.set_nonblocking(false).unwrap();stream.set_read_timeout(Some(Duration::from_secs(5))).unwrap();diff --git a/crates/ov_cli/tests/config_override.rs b/crates/ov_cli/tests/config_override.rsindex 125b5483d..0b9358278 100644--- a/crates/ov_cli/tests/config_override.rs+++ b/crates/ov_cli/tests/config_override.rs@@ -6,8 +6,18 @@ use std::{};fn run(dir: &std::path::Path, selected: &str, args: &[&str]) -> Output {+ let home = dir.join("home");+ let settings_dir = home.join(".openviking");+ fs::create_dir_all(&settings_dir).unwrap();+ fs::write(+ settings_dir.join("ovcli.settings.conf"),+ json!({"language": "en"}).to_string(),+ )+ .unwrap();Command::new(env!("CARGO_BIN_EXE_ov")).current_dir(dir)+ .env("HOME", &home)+ .env("USERPROFILE", &home).env("OPENVIKING_CLI_CONFIG_FILE", selected).env("OPENVIKING_LANG", "en").env("NO_COLOR", "1")diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex 129524107..777a1e9c2 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -447,7 +447,31 @@ fn pathlock_config_from_canonical_ov_conf(.and_then(|storage| storage.get("agfs")).and_then(|agfs| agfs.get("pathlock"));match pathlock {- Some(pathlock) => pathlock_config_from_value(pathlock, service_name),+ Some(pathlock) => {+ let mut pathlock = pathlock.clone();+ if pathlock.get("provider").and_then(serde_json::Value::as_str) == Some("sqlite")+ && pathlock+ .get("sqlite_path")+ .is_none_or(serde_json::Value::is_null)+ {+ let workspace = json+ .get("storage")+ .and_then(|storage| storage.get("workspace"))+ .and_then(serde_json::Value::as_str)+ .filter(|workspace| !workspace.is_empty())+ .ok_or_else(|| {+ "storage.workspace is required for the default SQLite lock database"+ .to_string()+ })?;+ // The workspace may not exist yet. Resolve relative paths against+ // the process working directory without requiring existing parents.+ let database = std::path::absolute(workspace)+ .map_err(|error| format!("failed to resolve storage.workspace: {error}"))?+ .join("_system/pathlock/pathlock.db");+ pathlock["sqlite_path"] = serde_json::json!(database);+ }+ pathlock_config_from_value(&pathlock, service_name)+ }None => Ok(PathLockConfig::default()),}}@@ -460,7 +484,12 @@ fn pathlock_config_from_value(let pathlock = value.as_object().ok_or_else(|| "pathlock config must be an object".to_string())?;- const FIELDS: &[&str] = &["provider", "lock_timeout_secs", "lock_expire_secs"];+ const FIELDS: &[&str] = &[+ "provider",+ "sqlite_path",+ "lock_timeout_secs",+ "lock_expire_secs",+ ];if let Some(field) = pathlock.keys().find(|field| !FIELDS.contains(&field.as_str()))@@ -469,12 +498,25 @@ fn pathlock_config_from_value(}let provider = string_field(pathlock, "provider", "filesystem")?;- if !matches!(provider.as_str(), "filesystem" | "memory" | "cache") {+ if !matches!(provider.as_str(), "filesystem" | "memory" | "sqlite" | "cache") {return Err(format!(- "unsupported pathlock.provider: {provider}; expected filesystem, memory, or cache"+ "unsupported pathlock.provider: {provider}; expected filesystem, memory, sqlite, or cache"));}- let pathlock_service_name = (provider == "cache").then(|| service_name.to_string());+ let pathlock_service_name =+ matches!(provider.as_str(), "cache" | "sqlite").then(|| service_name.to_string());+ let sqlite_path = match pathlock.get("sqlite_path") {+ None | Some(serde_json::Value::Null) => None,+ Some(serde_json::Value::String(path)) => Some(path.clone()),+ _ => return Err("pathlock.sqlite_path must be a string".to_string()),+ };+ if provider == "sqlite"+ && !sqlite_path+ .as_deref()+ .is_some_and(|path| std::path::Path::new(path).is_absolute())+ {+ return Err("pathlock.sqlite_path must be an absolute local file path".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 {@@ -488,6 +530,7 @@ fn pathlock_config_from_value(Ok(PathLockConfig {provider,service_name: pathlock_service_name,+ sqlite_path,lock_timeout_secs,lock_expire_secs,})@@ -3418,6 +3461,163 @@ mod tests {assert_eq!(pathlock.service_name.as_deref(), Some("prod-a"));}+ #[test]+ fn constructor_sqlite_config_path_resolves_defaults_and_creates_parent() {+ let root = std::env::temp_dir().join(format!(+ "openviking-sqlite-config-path-{}-{}",+ std::process::id(),+ std::time::SystemTime::now()+ .duration_since(std::time::UNIX_EPOCH)+ .unwrap()+ .as_nanos()+ ));+ fs::create_dir_all(&root).unwrap();+ Python::initialize();+ Python::attach(|py| {+ for mode in ["omitted", "null", "explicit"] {+ let workspace = root.join(mode).join("workspace");+ let database = if mode == "explicit" {+ root.join(mode).join("custom").join("locks.db")+ } else {+ workspace.join("_system/pathlock/pathlock.db")+ };+ let mut pathlock = serde_json::json!({"provider": "sqlite"});+ if mode == "null" {+ pathlock["sqlite_path"] = serde_json::Value::Null;+ } else if mode == "explicit" {+ pathlock["sqlite_path"] = serde_json::json!(database);+ }+ let path = root.join(format!("{mode}.json"));+ fs::write(+ &path,+ serde_json::json!({+ "storage": {+ "workspace": workspace,+ "agfs": {"pathlock": pathlock}+ }+ })+ .to_string(),+ )+ .unwrap();+ assert!(!database.parent().unwrap().exists());+ let config = PyDict::new(py);+ config.set_item("service_name", "local-a").unwrap();+ let kwargs = PyDict::new(py);+ kwargs+ .set_item("config_path", path.to_str().unwrap())+ .unwrap();+ kwargs.set_item("config", config).unwrap();+ let ty = py.get_type::<RAGFSBindingClient>();+ let first = ty.call((), Some(&kwargs)).unwrap();+ let second = ty.call((), Some(&kwargs)).unwrap();+ assert!(database.is_file());+ if mode == "explicit" {+ assert!(!workspace.join("_system/pathlock/pathlock.db").exists());+ }+ let first = first.extract::<PyRef<'_, RAGFSBindingClient>>().unwrap();+ let second = second.extract::<PyRef<'_, RAGFSBindingClient>>().unwrap();+ let lease = first+ .rt+ .block_on(first.pathlock_manager.acquire_tree(+ "/missing",+ std::time::Duration::ZERO,+ None,+ ))+ .unwrap();+ assert!(second+ .rt+ .block_on(second.pathlock_manager.acquire_exact(+ "/missing/child",+ std::time::Duration::ZERO,+ None,+ ))+ .is_err());+ first+ .rt+ .block_on(first.pathlock_manager.release(&lease))+ .unwrap();+ let lease = second+ .rt+ .block_on(second.pathlock_manager.acquire_exact(+ "/missing/child",+ std::time::Duration::ZERO,+ None,+ ))+ .unwrap();+ second+ .rt+ .block_on(second.pathlock_manager.release(&lease))+ .unwrap();+ }+ });+ fs::remove_dir_all(root).unwrap();+ }++ #[test]+ fn canonical_sqlite_default_requires_workspace_and_preserves_explicit_path() {+ for pathlock in [+ serde_json::json!({"provider": "sqlite"}),+ serde_json::json!({"provider": "sqlite", "sqlite_path": null}),+ ] {+ let json = serde_json::json!({+ "storage": {"workspace": "relative/workspace", "agfs": {"pathlock": pathlock}}+ });+ let config = pathlock_config_from_canonical_ov_conf(&json, "local-a").unwrap();+ let expected = std::path::absolute("relative/workspace")+ .unwrap()+ .join("_system/pathlock/pathlock.db");+ assert_eq!(config.sqlite_path.as_deref(), expected.to_str());+ assert_eq!(config.service_name.as_deref(), Some("local-a"));+ }+ for workspace in [+ serde_json::Value::Null,+ serde_json::json!(""),+ serde_json::json!(42),+ ] {+ let json = serde_json::json!({+ "storage": {"workspace": workspace, "agfs": {"pathlock": {"provider": "sqlite"}}}+ });+ let error = pathlock_config_from_canonical_ov_conf(&json, "local-a").unwrap_err();+ assert!(error.contains("storage.workspace"), "{error}");+ }+ let path = std::env::temp_dir().join("explicit-pathlock.db");+ let json = serde_json::json!({+ "storage": {"agfs": {"pathlock": {"provider": "sqlite", "sqlite_path": path}}}+ });+ assert_eq!(+ pathlock_config_from_canonical_ov_conf(&json, "local-a")+ .unwrap()+ .sqlite_path+ .as_deref(),+ path.to_str()+ );+ assert_eq!(+ pathlock_config_from_canonical_ov_conf(&serde_json::json!({}), "local-a")+ .unwrap()+ .provider,+ "filesystem"+ );+ }++ #[test]+ fn sqlite_pathlock_config_parses_shared_path_and_namespace() {+ let path = std::env::temp_dir().join("openviking-locks.sqlite3");+ let config = pathlock_config_from_value(+ &serde_json::json!({"provider": "sqlite", "sqlite_path": path}),+ "local-a",+ )+ .unwrap();+ assert_eq!(config.sqlite_path.as_deref(), path.to_str());+ assert_eq!(config.service_name.as_deref(), Some("local-a"));+ for value in [+ serde_json::json!({"provider": "sqlite"}),+ serde_json::json!({"provider": "sqlite", "sqlite_path": "relative.db"}),+ serde_json::json!({"provider": "sqlite", "sqlite_path": 42}),+ ] {+ assert!(pathlock_config_from_value(&value, "local-a").is_err());+ }+ }+#[test]fn canonical_cache_config_is_parsed_from_ov_conf() {let path = std::env::temp_dir().join(format!(diff --git a/crates/ragfs/Cargo.toml b/crates/ragfs/Cargo.tomlindex 32b8f7129..742a80826 100644--- a/crates/ragfs/Cargo.toml+++ b/crates/ragfs/Cargo.toml@@ -18,6 +18,10 @@ path = "src/lib.rs"name = "ragfs-shell"path = "src/shell/main.rs"+[[bench]]+name = "pathlock_perf"+harness = false+[[test]]name = "cache_runtime"path = "tests/cache_runtime.rs"diff --git a/crates/ragfs/benches/pathlock_perf.md b/crates/ragfs/benches/pathlock_perf.mdnew file mode 100644index 000000000..50711bdea--- /dev/null+++ b/crates/ragfs/benches/pathlock_perf.md@@ -0,0 +1,50 @@+# PathLock performance baselines++Run from the repository root:++```sh+cargo bench --locked -p ragfs --bench pathlock_perf -- \+ --mode all --iterations 20 --worker-iterations 100 --workers 1,4,16 \+ --output /tmp/pathlock-perf.csv+```++Use `--mode tree` or `--mode concurrency` to run either benchmark independently.+These are manual measurements, with no timing thresholds in CI. No server, model,+Redis service, or additional dependencies are required. All business data, databases,+and subprocess coordination files live in temporary directories and are cleaned up.++The Tree benchmark compares SQLite and filesystem providers on the same real+LocalFS datasets: 10–10,000 flat files, plus 200/1,000 subdirectories with one file+each. Setup and three warmup acquisitions are excluded. Latencies measure+`acquire_tree` only; locks are released between samples. `directory_reads` counts+directory listing calls during measured acquire/release cycles, not individual+metadata system calls. A lightweight atomic counter wraps LocalFS and forwards+native CAS operations. SQLite keeps its database outside the business subtree.++The concurrency benchmark uses 1/4/16 workers on disjoint existing file paths.+Each measured operation uses a different path, so a failed release does not turn+the following samples into logical conflicts on the same retained token.+It exercises `PathLockManager` with `timeout=0`, with no benchmark-side Busy+retries. It compares shared-provider threads (SQLite's single connection/mutex),+independent-provider threads (separate SQLite connections), and separate processes+sharing the same filesystem and database. Each worker warms up three operations+before a start barrier. Each runtime uses four Tokio worker threads, including+each subprocess. Latencies include both acquire and release, including+scheduling, mutex queues, and database waits. Logical lock contention is deliberately+excluded so database contention failures remain visible.++CSV rows include successful operations/second, successful-operation P50/P95/P99,+and failure counts by acquisition/release phase and Timeout/Busy error type.+All workers' latency samples are pooled; quantiles use nearest+rank. Throughput uses the controller's wall time, including barrier/reporting+overhead, especially for subprocesses. Failed operations are counted separately+and excluded from latency percentiles; always check failures before comparing rates.++The benchmark uses SQLite WAL with `synchronous=FULL` and the production 100 ms+Busy timeout per attempt, with three total attempts and 1 ms / 4 ms backoff.+Retries are inside the provider and cover all operations; the benchmark adds none.+It measures warm filesystem caches, not cold storage or application+file deletion/copy time. Twenty Tree samples give only a coarse tail estimate.+Repeat runs on otherwise idle hardware, record OS/CPU/Rust version, and use more+samples for stable P95/P99 comparisons. Thread and process results are different+workloads and should not be interpreted as a pure connection-pool speedup.diff --git a/crates/ragfs/benches/pathlock_perf.rs b/crates/ragfs/benches/pathlock_perf.rsnew file mode 100644index 000000000..4221d04bd--- /dev/null+++ b/crates/ragfs/benches/pathlock_perf.rs@@ -0,0 +1,589 @@+//! Manual release-mode benchmarks; see pathlock_perf.md for the measurement contract.+use std::collections::HashMap;+use std::fs::{self, File};+use std::io::Write;+use std::path::{Path, PathBuf};+use std::process::{Child, Command};+use std::sync::atomic::{AtomicU64, Ordering};+use std::sync::Arc;+use std::time::{Duration, Instant};++use async_trait::async_trait;+use ragfs::core::{FileInfo, FileSystem, ListSortBy, Result as FsResult, SortOrder, WriteFlag};+use ragfs::lock::types::PathLockError;+use ragfs::lock::{+ FilesystemPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ SQLitePathLockProvider,+};+use ragfs::plugins::localfs::LocalFileSystem;+use serde::{Deserialize, Serialize};+use tempfile::TempDir;+use tokio::sync::{mpsc, Barrier};++type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;++#[derive(Clone)]+struct Options {+ mode: String,+ iterations: usize,+ worker_iterations: usize,+ workers: Vec<usize>,+ args: HashMap<String, String>,+}++impl Options {+ fn parse() -> Result<Self> {+ let mut args = HashMap::new();+ let mut input = std::env::args().skip(1);+ while let Some(key) = input.next() {+ match key.as_str() {+ "--bench" => {}+ "--worker" => {+ args.insert(key, "true".into());+ }+ "--help" | "-h" => {+ println!(+ "cargo bench --locked -p ragfs --bench pathlock_perf -- \+ --mode all|tree|concurrency --iterations 20 \+ --worker-iterations 100 --workers 1,4,16 --output /tmp/pathlock.csv"+ );+ std::process::exit(0);+ }+ _ => {+ args.insert(key, input.next().ok_or("missing option value")?);+ }+ }+ }+ let options = Self {+ mode: args.get("--mode").cloned().unwrap_or("all".into()),+ iterations: args+ .get("--iterations")+ .map(|s| s.parse())+ .transpose()?+ .unwrap_or(20),+ worker_iterations: args+ .get("--worker-iterations")+ .map(|s| s.parse())+ .transpose()?+ .unwrap_or(100),+ workers: args+ .get("--workers")+ .map(String::as_str)+ .unwrap_or("1,4,16")+ .split(',')+ .map(str::parse)+ .collect::<std::result::Result<_, _>>()?,+ args,+ };+ if options.iterations == 0+ || options.worker_iterations == 0+ || options.workers.iter().any(|n| *n == 0)+ || !matches!(options.mode.as_str(), "all" | "tree" | "concurrency")+ {+ return Err(+ "iterations/workers must be positive and mode must be all, tree, or concurrency"+ .into(),+ );+ }+ Ok(options)+ }++ fn required(&self, key: &str) -> Result<&str> {+ self.args+ .get(key)+ .map(String::as_str)+ .ok_or_else(|| format!("missing {key}").into())+ }+}++#[derive(Default, Serialize, Deserialize)]+struct Samples {+ latency_ns: Vec<u64>,+ failures: usize,+ acquire_failures: usize,+ release_failures: usize,+ timeouts: usize,+ busy_errors: usize,+}++impl Samples {+ fn merge(&mut self, other: Self) {+ self.latency_ns.extend(other.latency_ns);+ self.failures += other.failures;+ self.acquire_failures += other.acquire_failures;+ self.release_failures += other.release_failures;+ self.timeouts += other.timeouts;+ self.busy_errors += other.busy_errors;+ }++ fn failed(&mut self, path: &str, phase: &str, error: &PathLockError) {+ if self.failures == 0 {+ eprintln!("first {phase} failure at {path}: {error}");+ }+ self.failures += 1;+ if phase == "acquire" {+ self.acquire_failures += 1;+ } else {+ self.release_failures += 1;+ }+ self.timeouts += usize::from(matches!(error, PathLockError::Timeout { .. }));+ self.busy_errors += usize::from(matches!(error, PathLockError::Busy { .. }));+ }+}++struct Record {+ case: String,+ provider: String,+ concurrency: usize,+ files: usize,+ directories: usize,+ scope: &'static str,+ elapsed: Duration,+ samples: Samples,+ directory_reads: Option<u64>,+}++// Count only directory listings. Delegate native CAS operations explicitly so+// instrumentation cannot change the real filesystem locking protocol.+struct CountingFS {+ inner: LocalFileSystem,+ directory_reads: AtomicU64,+}++#[async_trait]+impl FileSystem for CountingFS {+ async fn create(&self, path: &str) -> FsResult<()> {+ self.inner.create(path).await+ }+ async fn mkdir(&self, path: &str, mode: u32) -> FsResult<()> {+ self.inner.mkdir(path, mode).await+ }+ async fn remove(&self, path: &str) -> FsResult<()> {+ self.inner.remove(path).await+ }+ async fn remove_all(&self, path: &str) -> FsResult<()> {+ self.inner.remove_all(path).await+ }+ async fn read(&self, path: &str, offset: u64, size: u64) -> FsResult<Vec<u8>> {+ self.inner.read(path, offset, size).await+ }+ async fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> FsResult<u64> {+ self.inner.write(path, data, offset, flags).await+ }+ async fn compare_and_write(&self, path: &str, expected: &[u8], data: &[u8]) -> FsResult<bool> {+ self.inner.compare_and_write(path, expected, data).await+ }+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> FsResult<bool> {+ self.inner.compare_and_remove(path, expected).await+ }+ async fn read_dir(+ &self,+ path: &str,+ offset: Option<usize>,+ limit: Option<usize>,+ sort_by: Option<ListSortBy>,+ sort_order: Option<SortOrder>,+ ) -> FsResult<Vec<FileInfo>> {+ self.directory_reads.fetch_add(1, Ordering::Relaxed);+ self.inner+ .read_dir(path, offset, limit, sort_by, sort_order)+ .await+ }+ async fn read_internal_dir(&self, path: &str) -> FsResult<Vec<FileInfo>> {+ self.directory_reads.fetch_add(1, Ordering::Relaxed);+ self.inner.read_internal_dir(path).await+ }+ async fn stat(&self, path: &str) -> FsResult<FileInfo> {+ self.inner.stat(path).await+ }+ async fn rename(&self, from: &str, to: &str) -> FsResult<()> {+ self.inner.rename(from, to).await+ }+ async fn chmod(&self, path: &str, mode: u32) -> FsResult<()> {+ self.inner.chmod(path, mode).await+ }+ async fn exists(&self, path: &str) -> bool {+ self.inner.exists(path).await+ }+ async fn ensure_parent_dirs(&self, path: &str, mode: u32) -> FsResult<()> {+ self.inner.ensure_parent_dirs(path, mode).await+ }+}++struct Output {+ csv: Option<File>,+}++impl Output {+ fn new(path: Option<&String>) -> Result<Self> {+ let mut output = Self {+ csv: path.map(File::create).transpose()?,+ };+ output.line("case,provider,workers,files,directories,latency_scope,successes,failures,elapsed_s,successful_ops_s,p50_ms,p95_ms,p99_ms,directory_reads,acquire_failures,release_failures,timeouts,busy_errors")?;+ Ok(output)+ }++ fn line(&mut self, line: &str) -> Result<()> {+ println!("{line}");+ if let Some(csv) = &mut self.csv {+ writeln!(csv, "{line}")?;+ csv.flush()?;+ }+ Ok(())+ }++ fn record(&mut self, mut record: Record) -> Result<()> {+ record.samples.latency_ns.sort_unstable();+ let quantile = |q: f64| -> String {+ let values = &record.samples.latency_ns;+ if values.is_empty() {+ return String::new();+ }+ let index = ((q * values.len() as f64).ceil() as usize).saturating_sub(1);+ format!(+ "{:.6}",+ values[index.min(values.len() - 1)] as f64 / 1_000_000.0+ )+ };+ self.line(&format!(+ "{},{},{},{},{},{},{},{},{:.6},{:.3},{},{},{},{},{},{},{},{}",+ record.case,+ record.provider,+ record.concurrency,+ record.files,+ record.directories,+ record.scope,+ record.samples.latency_ns.len(),+ record.samples.failures,+ record.elapsed.as_secs_f64(),+ record.samples.latency_ns.len() as f64 / record.elapsed.as_secs_f64(),+ quantile(0.5),+ quantile(0.95),+ quantile(0.99),+ record+ .directory_reads+ .map(|n| n.to_string())+ .unwrap_or_default(),+ record.samples.acquire_failures,+ record.samples.release_failures,+ record.samples.timeouts,+ record.samples.busy_errors,+ ))+ }+}++fn make_fs(root: &Path) -> Result<Arc<CountingFS>> {+ Ok(Arc::new(CountingFS {+ inner: LocalFileSystem::new(root.to_str().ok_or("non-UTF8 root")?)?,+ directory_reads: AtomicU64::new(0),+ }))+}++fn make_provider(+ name: &str,+ fs: Arc<dyn FileSystem>,+ db: &Path,+) -> Result<Arc<dyn PathLockProvider>> {+ match name {+ "filesystem" => Ok(Arc::new(FilesystemPathLockProvider::new(fs, 30.0))),+ "sqlite" => Ok(Arc::new(SQLitePathLockProvider::new(+ db.to_str().ok_or("non-UTF8 database")?,+ "pathlock-perf",+ )?)),+ _ => Err(format!("unknown provider: {name}").into()),+ }+}++async fn cycle(manager: &PathLockManager, path: &str, samples: &mut Samples) {+ let start = Instant::now();+ match manager.acquire_exact(path, Duration::ZERO, None).await {+ Ok(lease) => match manager.release(&lease).await {+ Ok(()) => samples.latency_ns.push(start.elapsed().as_nanos() as u64),+ Err(error) => samples.failed(path, "release", &error),+ },+ Err(error) => {+ samples.failed(path, "acquire", &error);+ }+ }+}++async fn tree(options: &Options, output: &mut Output) -> Result<()> {+ // Flat trees expose per-entry metadata cost; nested trees expose per-directory I/O.+ for (files, dirs) in [+ (10, 0),+ (200, 0),+ (1_000, 0),+ (5_000, 0),+ (10_000, 0),+ (200, 200),+ (1_000, 1_000),+ ] {+ let temp = TempDir::new()?;+ let root = temp.path().join("data");+ fs::create_dir_all(root.join("tree"))?;+ for id in 0..files {+ let parent = if dirs == 0 {+ root.join("tree")+ } else {+ let parent = root.join(format!("tree/d{id:05}"));+ fs::create_dir_all(&parent)?;+ parent+ };+ fs::write(parent.join(format!("f{id:05}")), b"x")?;+ }+ for name in ["filesystem", "sqlite"] {+ let tracked = make_fs(&root)?;+ let provider = make_provider(name, tracked.clone(), &temp.path().join("locks.db"))?;+ let manager =+ PathLockManager::new(tracked.clone(), provider, PathLockConfig::default());+ for _ in 0..3 {+ let lease = manager.acquire_tree("/tree", Duration::ZERO, None).await?;+ manager.release(&lease).await?;+ }+ let before = tracked.directory_reads.load(Ordering::Relaxed);+ let mut samples = Samples::default();+ let wall = Instant::now();+ for _ in 0..options.iterations {+ let start = Instant::now();+ let lease = manager.acquire_tree("/tree", Duration::ZERO, None).await?;+ samples.latency_ns.push(start.elapsed().as_nanos() as u64);+ manager.release(&lease).await?;+ }+ let elapsed = wall.elapsed();+ let after = tracked.directory_reads.load(Ordering::Relaxed);+ output.record(Record {+ case: if dirs == 0 {+ "tree_flat"+ } else {+ "tree_nested"+ }+ .into(),+ provider: name.into(),+ concurrency: 1,+ files,+ directories: dirs,+ scope: "acquire",+ elapsed,+ samples,+ directory_reads: Some(after - before),+ })?;+ }+ }+ Ok(())+}++fn prepare_work(root: &Path, workers: usize, iterations: usize) -> Result<()> {+ fs::create_dir_all(root.join("work"))?;+ for id in 0..workers {+ for iteration in 0..iterations + 3 {+ fs::write(root.join(format!("work/{id}-{iteration}")), b"x")?;+ }+ }+ Ok(())+}++async fn threads(options: &Options, name: &str, workers: usize, shared: bool) -> Result<Record> {+ let temp = TempDir::new()?;+ let root = temp.path().join("data");+ prepare_work(&root, workers, options.worker_iterations)?;+ let tracked = make_fs(&root)?;+ let db = temp.path().join("locks.db");+ let common = make_provider(name, tracked.clone(), &db)?;+ let barrier = Arc::new(Barrier::new(workers + 1));+ let (ready_tx, mut ready_rx) = mpsc::channel(workers);+ let mut tasks = Vec::new();+ for id in 0..workers {+ let provider = if shared {+ common.clone()+ } else {+ make_provider(name, tracked.clone(), &db)?+ };+ let manager = PathLockManager::new(tracked.clone(), provider, PathLockConfig::default());+ let barrier = barrier.clone();+ let ready_tx = ready_tx.clone();+ let iterations = options.worker_iterations;+ tasks.push(tokio::spawn(async move {+ let mut warmup = Samples::default();+ for iteration in 0..3 {+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut warmup).await;+ }+ ready_tx.send(()).await.unwrap();+ barrier.wait().await;+ let mut samples = Samples::default();+ for iteration in 3..iterations + 3 {+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut samples).await;+ }+ samples+ }));+ }+ for _ in 0..workers {+ ready_rx+ .recv()+ .await+ .ok_or("worker failed before barrier")?;+ }+ let before = tracked.directory_reads.load(Ordering::Relaxed);+ let wall = Instant::now();+ barrier.wait().await;+ let mut samples = Samples::default();+ for task in tasks {+ samples.merge(task.await?);+ }+ let elapsed = wall.elapsed();+ let after = tracked.directory_reads.load(Ordering::Relaxed);+ Ok(Record {+ case: if shared {+ "threads_shared_provider"+ } else {+ "threads_independent_providers"+ }+ .into(),+ provider: name.into(),+ concurrency: workers,+ files: workers * (options.worker_iterations + 3),+ directories: 0,+ scope: "acquire_release",+ elapsed,+ samples,+ directory_reads: Some(after - before),+ })+}++fn wait_for(path: &Path) -> Result<()> {+ let start = Instant::now();+ while !path.exists() {+ if start.elapsed() > Duration::from_secs(60) {+ return Err(format!("timed out waiting for {path:?}").into());+ }+ std::thread::sleep(Duration::from_millis(1));+ }+ Ok(())+}++struct Worker(Child);+impl Drop for Worker {+ fn drop(&mut self) {+ let _ = self.0.kill();+ let _ = self.0.wait();+ }+}++async fn process_worker(options: &Options) -> Result<()> {+ let root = PathBuf::from(options.required("--root")?);+ let db = PathBuf::from(options.required("--db")?);+ let sync = PathBuf::from(options.required("--sync")?);+ let id = options.required("--id")?;+ let tracked = make_fs(&root)?;+ let provider = make_provider(options.required("--provider")?, tracked.clone(), &db)?;+ let manager = PathLockManager::new(tracked, provider, PathLockConfig::default());+ let mut warmup = Samples::default();+ for iteration in 0..3 {+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut warmup).await;+ }+ fs::write(sync.join(format!("{id}.ready")), "")?;+ wait_for(&sync.join("go"))?;+ let mut samples = Samples::default();+ for iteration in 3..options.worker_iterations + 3 {+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut samples).await;+ }+ let temp_report = sync.join(format!("{id}.json.tmp"));+ fs::write(&temp_report, serde_json::to_vec(&samples)?)?;+ fs::rename(temp_report, sync.join(format!("{id}.json")))?;+ Ok(())+}++fn processes(options: &Options, name: &str, workers: usize) -> Result<Record> {+ let temp = TempDir::new()?;+ let root = temp.path().join("data");+ let db = temp.path().join("locks.db");+ let sync = temp.path().join("sync");+ prepare_work(&root, workers, options.worker_iterations)?;+ fs::create_dir(&sync)?;+ // Exclude concurrent schema initialization from measurements.+ drop(make_provider(name, make_fs(&root)?, &db)?);+ let mut children = Vec::new();+ for id in 0..workers {+ children.push(Worker(+ Command::new(std::env::current_exe()?)+ .arg("--worker")+ .arg("--provider")+ .arg(name)+ .arg("--root")+ .arg(&root)+ .arg("--db")+ .arg(&db)+ .arg("--sync")+ .arg(&sync)+ .arg("--id")+ .arg(id.to_string())+ .arg("--worker-iterations")+ .arg(options.worker_iterations.to_string())+ .spawn()?,+ ));+ }+ let deadline = Instant::now();+ loop {+ if (0..workers).all(|id| sync.join(format!("{id}.ready")).exists()) {+ break;+ }+ for worker in &mut children {+ if let Some(status) = worker.0.try_wait()? {+ return Err(format!("worker exited before start: {status}").into());+ }+ }+ if deadline.elapsed() > Duration::from_secs(60) {+ return Err("worker initialization timed out".into());+ }+ std::thread::sleep(Duration::from_millis(1));+ }+ let wall = Instant::now();+ fs::write(sync.join("go"), "")?;+ let mut samples = Samples::default();+ for id in 0..workers {+ let report = sync.join(format!("{id}.json"));+ wait_for(&report)?;+ samples.merge(serde_json::from_slice(&fs::read(report)?)?);+ }+ let elapsed = wall.elapsed();+ for worker in &mut children {+ if !worker.0.wait()?.success() {+ return Err("worker failed".into());+ }+ }+ Ok(Record {+ case: "processes_independent_providers".into(),+ provider: name.into(),+ concurrency: workers,+ files: workers * (options.worker_iterations + 3),+ directories: 0,+ scope: "acquire_release",+ elapsed,+ samples,+ directory_reads: None,+ })+}++#[tokio::main(flavor = "multi_thread", worker_threads = 4)]+async fn main() -> Result<()> {+ let options = Options::parse()?;+ if options.args.contains_key("--worker") {+ return process_worker(&options).await;+ }+ eprintln!("pathlock_perf os={} arch={} available_parallelism={} runtime_threads=4 tree_samples={} per_worker_samples={} sqlite=WAL/FULL busy_ms=100 busy_attempts=3 backoff_ms=1,4",+ std::env::consts::OS, std::env::consts::ARCH, std::thread::available_parallelism()?,+ options.iterations, options.worker_iterations);+ let mut output = Output::new(options.args.get("--output"))?;+ if matches!(options.mode.as_str(), "all" | "tree") {+ tree(&options, &mut output).await?;+ }+ if matches!(options.mode.as_str(), "all" | "concurrency") {+ for &workers in &options.workers {+ for name in ["filesystem", "sqlite"] {+ output.record(threads(&options, name, workers, true).await?)?;+ output.record(threads(&options, name, workers, false).await?)?;+ output.record(processes(&options, name, workers)?)?;+ }+ }+ }+ Ok(())+}diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsindex 450332081..0cb39fec6 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -26,7 +26,7 @@ use crate::cache_runtime::{use crate::lock::RedisPathLockProvider;use crate::lock::{FilesystemPathLockProvider, MemoryPathLockProvider, PathLockConfig, PathLockManager,- PathLockProvider, PathLockWrappedFS,+ PathLockProvider, PathLockWrappedFS, SQLitePathLockProvider,};#[cfg(feature = "s3")]@@ -233,6 +233,39 @@ async fn build_stack_with_mountable_and_runtime(config.pathlock.lock_expire_secs,)),"memory" => Arc::new(MemoryPathLockProvider::new()),+ "sqlite" => {+ let path = config.pathlock.sqlite_path.as_deref().ok_or_else(|| {+ Error::config("pathlock.sqlite_path is required for SQLite PathLock")+ })?;+ let namespace = config.pathlock.service_name.as_deref().ok_or_else(|| {+ Error::config("pathlock.service_name is required for SQLite PathLock")+ })?;+ let path = path.to_string();+ let namespace = namespace.to_string();+ let provider = tokio::task::spawn_blocking(move || {+ let database = std::path::Path::new(&path);+ if !database.is_absolute() || namespace.trim().is_empty() {+ return Err(crate::lock::types::PathLockError::InvalidRequest(+ "SQLite PathLock requires an absolute sqlite_path and nonempty service_name"+ .to_string(),+ ));+ }+ if let Some(parent) = database.parent() {+ std::fs::create_dir_all(parent).map_err(|error| {+ crate::lock::types::PathLockError::Io(format!(+ "failed to create SQLite PathLock parent directory: {error}"+ ))+ })?;+ }+ SQLitePathLockProvider::new(&path, &namespace)+ })+ .await+ .map_err(|error| Error::config(format!("SQLite PathLock worker failed: {error}")))?+ .map_err(|error| {+ Error::config(format!("SQLite PathLock initialization failed: {error}"))+ })?;+ Arc::new(provider)+ }#[cfg(feature = "cache")]"cache" => {let runtime = runtime.clone().ok_or_else(|| {@@ -353,6 +386,7 @@ mod tests {pathlock: PathLockConfig {provider: "filesystem".to_string(),service_name: None,+ sqlite_path: None,lock_timeout_secs: 0.0,lock_expire_secs: 30.0,},@@ -534,6 +568,45 @@ mod tests {assert!(stack.cache_runtime.is_none());}+ #[tokio::test]+ async fn default_stack_builds_sqlite_pathlock_without_cache() {+ let dir = tempfile::tempdir().unwrap();+ let config = RagfsConfig {+ pathlock: PathLockConfig {+ provider: "sqlite".into(),+ service_name: Some("builder-test".into()),+ sqlite_path: Some(dir.path().join("locks.db").to_str().unwrap().into()),+ ..PathLockConfig::default()+ },+ ..RagfsConfig::default()+ };+ let stack = build_default_stack(config).await.unwrap();+ let lease = stack+ .pathlock_manager+ .acquire_tree("/missing", std::time::Duration::ZERO, None)+ .await+ .unwrap();+ assert_eq!(lease.lease.lock_paths, vec!["/missing"]);+ stack.pathlock_manager.release(&lease).await.unwrap();+ }++ #[tokio::test]+ async fn default_stack_rejects_sqlite_pathlock_without_shared_database() {+ let config = RagfsConfig {+ pathlock: PathLockConfig {+ provider: "sqlite".into(),+ service_name: Some("builder-test".into()),+ ..PathLockConfig::default()+ },+ ..RagfsConfig::default()+ };+ let error = match build_default_stack(config).await {+ Ok(_) => panic!("SQLite PathLock unexpectedly built without database"),+ Err(error) => error,+ };+ assert!(error.to_string().contains("sqlite_path"));+ }+#[tokio::test]async fn default_stack_rejects_unknown_pathlock_provider() {let config = RagfsConfig {diff --git a/crates/ragfs/src/lock/cache_provder.rs b/crates/ragfs/src/lock/cache_provder.rsindex 4cac8233e..f03d36786 100644--- a/crates/ragfs/src/lock/cache_provder.rs+++ b/crates/ragfs/src/lock/cache_provder.rs@@ -11,10 +11,12 @@ use crate::cache_runtime::{};use super::codec::LockTokenCodec;-use super::provider::{AcquisitionChange, AtomicAcquisition, PathLockHandleMode, PathLockProvider};+use super::provider::{+ AcquisitionChange, AtomicAcquisition, AtomicAcquisitionResult, PathLockHandleMode, PathLockProvider,+};use super::types::{LockToken, PathLockError, PathLockKind, PathLockRequest, PathLockResult};-const ACQUIRE_BATCH_ID: &str = "pathlock.acquire_batch.v1";+const ACQUIRE_BATCH_ID: &str = "pathlock.acquire_batch.v2";const ROLLBACK_BATCH_ID: &str = "pathlock.rollback_batch.v1";const COMPARE_WRITE_ID: &str = "pathlock.compare_write.v1";const COMPARE_REMOVE_ID: &str = "pathlock.compare_remove.v1";@@ -258,7 +260,7 @@ if redis.call("HLEN", key) > 0 thenredis.call("PEXPIRE", key, ttl_ms)end-local result = { "ok" }+local result = { "ok", tostring(#stale) }for _, change in ipairs(changes) dotable.insert(result, change.path)table.insert(result, change.change)@@ -789,6 +791,19 @@ impl PathLockProvider for RedisPathLockProvider {now_ns: u128,stale_before_ns: u128,) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {+ Ok(self+ .try_acquire_batch_atomic_with_stats(requests, owner_id, now_ns, stale_before_ns)+ .await?+ .map(|result| result.acquisitions))+ }++ async fn try_acquire_batch_atomic_with_stats(+ &self,+ requests: &[PathLockRequest],+ owner_id: &str,+ now_ns: u128,+ stale_before_ns: u128,+ ) -> PathLockResult<Option<AtomicAcquisitionResult>> {if requests.is_empty() {return Err(PathLockError::InvalidRequest("lock request batch must not be empty".to_string(),@@ -811,15 +826,18 @@ impl PathLockProvider for RedisPathLockProvider {if status != "ok" {return Err(Self::decode_error_result("acquire_batch", &values)?);}- if (values.len() - 1) % 4 != 0 {+ if values.len() < 2 || (values.len() - 2) % 4 != 0 {return Err(PathLockError::Internal(format!("Redis PathLock acquire_batch returned {} trailing values",- values.len() - 1+ values.len().saturating_sub(2))));}- let mut acquisitions = Vec::with_capacity((values.len() - 1) / 4);- for values in values[1..].chunks_exact(4) {+ let stale_tokens_removed = Self::result_string(&values[1], "acquire_batch")?+ .parse::<usize>()+ .map_err(|_| PathLockError::Internal("invalid Redis stale recovery count".into()))?;+ let mut acquisitions = Vec::with_capacity((values.len() - 2) / 4);+ for values in values[2..].chunks_exact(4) {let handle = Self::result_string(&values[0], "acquire_batch")?.to_string();let change = Self::result_string(&values[1], "acquire_batch")?;let previous = Self::result_string(&values[2], "acquire_batch")?;@@ -841,7 +859,10 @@ impl PathLockProvider for RedisPathLockProvider {};acquisitions.push(AtomicAcquisition { handle, change });}- Ok(Some(acquisitions))+ Ok(Some(AtomicAcquisitionResult {+ acquisitions,+ stale_tokens_removed,+ }))}/// Atomically roll back mutations reported by one completed batch.@@ -1315,6 +1336,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])let config = PathLockConfig {provider: "cache".to_string(),service_name: Some(service_name.clone()),+ sqlite_path: None,lock_timeout_secs: 0.0,lock_expire_secs: 3.0,};@@ -1962,6 +1984,31 @@ return redis.call("HGET", KEYS[1], ARGV[2])}}+ /// Verify storage-side stale recovery reaches manager metrics.+ #[tokio::test]+ async fn stale_recovery_count_reaches_manager_observation() {+ let Some((runtime, provider)) = test_provider("stale-metrics").await else {+ return;+ };+ let path = "/local/account-a/old";+ provider+ .try_create_token(path, &token("dead", 1, PathLockKind::Exact))+ .await+ .unwrap();+ let manager = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ Arc::new(provider),+ PathLockConfig::default(),+ );+ let lease = manager+ .acquire_tree(path, Duration::ZERO, None)+ .await+ .unwrap();+ assert_eq!(manager.observe().await.stale_locks_removed, 1);+ manager.release(&lease).await.unwrap();+ runtime.close().await.unwrap();+ }+/// Measure HASH-only atomic batch latency for representative lock counts.#[tokio::test]#[ignore = "manual Redis performance baseline"]diff --git a/crates/ragfs/src/lock/cache_refresh_tests.rs b/crates/ragfs/src/lock/cache_refresh_tests.rsindex 858fbb199..7548b6286 100644--- a/crates/ragfs/src/lock/cache_refresh_tests.rs+++ b/crates/ragfs/src/lock/cache_refresh_tests.rs@@ -187,7 +187,10 @@ async fn manager_uses_batch_for_manual_and_background_refresh() {ACQUIRE_BATCH_ID => {let owner = std::str::from_utf8(&request.args[0]).unwrap();let time = std::str::from_utf8(&request.args[1]).unwrap();- let mut results = vec![ScriptValue::Bytes(b"ok".to_vec())];+ let mut results = vec![+ ScriptValue::Bytes(b"ok".to_vec()),+ ScriptValue::Bytes(b"0".to_vec()),+ ];for pair in request.args[4..].chunks_exact(2) {let kind = std::str::from_utf8(&pair[1]).unwrap();results.extend([diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex 2cbe038e2..22b7ed044 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -28,10 +28,12 @@ use super::types::{/// Configuration for the PathLockManager.#[derive(Debug, Clone)]pub struct PathLockConfig {- /// Built-in provider name: `filesystem`, `memory`, or `cache`.+ /// Built-in provider name: `filesystem`, `memory`, `sqlite`, or `cache`.pub provider: String,- /// OpenViking instance name used by the cache-backed provider.+ /// OpenViking instance name used by the SQLite/cache-backed provider.pub service_name: Option<String>,+ /// Absolute local database file shared by SQLite lock participants.+ pub sqlite_path: Option<String>,/// Default wait timeout for auto-acquired locks.pub lock_timeout_secs: f64,/// Seconds after which a lock token is considered stale.@@ -43,6 +45,7 @@ impl Default for PathLockConfig {Self {provider: "filesystem".to_string(),service_name: None,+ sqlite_path: None,lock_timeout_secs: 0.0,lock_expire_secs: 30.0,}@@ -524,10 +527,10 @@ impl PathLockManager {let pending_handoff = entry.pending_handoff;let mut any_ok = false;let mut released_handoff_paths = Vec::new();- let results = refresh_provider+ let refresh_results = refresh_provider.refresh_tokens(&lock_paths, &owner.owner_id, now_ns).await;- for (lp, result) in lock_paths.iter().zip(results) {+ for (lp, result) in lock_paths.iter().zip(refresh_results) {match result {Ok(true) => {any_ok = true;@@ -1011,7 +1014,7 @@ impl PathLockManager {let now_ns = Self::now_ns();match self.provider- .try_acquire_batch_atomic(+ .try_acquire_batch_atomic_with_stats(requests,owner_id,now_ns,@@ -1019,7 +1022,12 @@ impl PathLockManager {).await{- Ok(Some(acquisitions)) => return Ok(acquisitions),+ Ok(Some(result)) => {+ if result.stale_tokens_removed != 0 {+ self.metrics.write().await.stale_tokens_removed += result.stale_tokens_removed;+ }+ return Ok(result.acquisitions);+ }Ok(None) => {}Err(error) => return Err(error),}diff --git a/crates/ragfs/src/lock/mod.rs b/crates/ragfs/src/lock/mod.rsindex 67d1a60e2..adb7abe1e 100644--- a/crates/ragfs/src/lock/mod.rs+++ b/crates/ragfs/src/lock/mod.rs@@ -1,7 +1,7 @@//! PathLock subsystem — native file-system-level locking protocol.//!//! This module provides exact-path and tree-path locks backed by lock files,-//! process memory, or Redis.+//! process memory, SQLite, or Redis.//!//! # Architecture//!@@ -19,6 +19,7 @@ pub mod manager;pub mod metrics;pub mod provider;pub mod resolver;+pub mod sqlite_provider;pub mod types;pub mod wrapper;@@ -28,10 +29,11 @@ pub use cache_provder::RedisPathLockProvider;pub use manager::{AutoPathLockAction, PathLockConfig, PathLockManager};pub use metrics::LockMetrics;pub use provider::{- AcquisitionChange, AtomicAcquisition, FilesystemPathLockProvider, MemoryPathLockProvider,- PathLockHandleMode, PathLockProvider,+ AcquisitionChange, AtomicAcquisition, AtomicAcquisitionResult, FilesystemPathLockProvider,+ MemoryPathLockProvider, PathLockHandleMode, PathLockProvider,};pub use resolver::LockPathResolver;+pub use sqlite_provider::SQLitePathLockProvider;pub use types::{BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,PathLockKind, PathLockLease, PathLockObserveSnapshot, PathLockRequest, PathLockResult,diff --git a/crates/ragfs/src/lock/provider.rs b/crates/ragfs/src/lock/provider.rsindex 41a130871..52121d971 100644--- a/crates/ragfs/src/lock/provider.rs+++ b/crates/ragfs/src/lock/provider.rs@@ -53,6 +53,15 @@ pub struct AtomicAcquisition {pub change: AcquisitionChange,}+/// Committed atomic acquisition mutations and storage-side recovery statistics.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct AtomicAcquisitionResult {+ /// Mutations used to publish or roll back the local lease.+ pub acquisitions: Vec<AtomicAcquisition>,+ /// Stale tokens actually removed or replaced by this committed transaction.+ pub stale_tokens_removed: usize,+}+/// Storage abstraction for lock tokens. Only `PathLockManager` should call these methods.#[async_trait]pub trait PathLockProvider: Send + Sync {@@ -75,6 +84,24 @@ pub trait PathLockProvider: Send + Sync {Ok(None)}+ /// Acquire with recovery statistics. Existing providers keep their atomic hook+ /// and report zero until they implement storage-side recovery accounting.+ async fn try_acquire_batch_atomic_with_stats(+ &self,+ requests: &[PathLockRequest],+ owner_id: &str,+ now_ns: u128,+ stale_before_ns: u128,+ ) -> PathLockResult<Option<AtomicAcquisitionResult>> {+ Ok(self+ .try_acquire_batch_atomic(requests, owner_id, now_ns, stale_before_ns)+ .await?+ .map(|acquisitions| AtomicAcquisitionResult {+ acquisitions,+ stale_tokens_removed: 0,+ }))+ }+/// Roll back one completed atomic acquisition when supported.async fn rollback_acquisitions_atomic(&self,diff --git a/crates/ragfs/src/lock/sqlite_provider.rs b/crates/ragfs/src/lock/sqlite_provider.rsnew file mode 100644index 000000000..0dfa9af81--- /dev/null+++ b/crates/ragfs/src/lock/sqlite_provider.rs@@ -0,0 +1,644 @@+//! Same-machine, multi-process locks stored in one authoritative SQLite database.++use std::path::Path;+use std::sync::{Arc, Mutex};+use std::time::Duration;++use async_trait::async_trait;+use rusqlite::{params, Connection, OptionalExtension, TransactionBehavior};++use super::provider::{+ AcquisitionChange, AtomicAcquisition, AtomicAcquisitionResult, PathLockHandleMode,+ PathLockProvider,+};+use super::types::{LockToken, PathLockError, PathLockKind, PathLockRequest, PathLockResult};++/// Transactional local lock storage. All participants must share the database and namespace.+pub struct SQLitePathLockProvider {+ // A single connection also serializes reads. A future read pool can use WAL+ // snapshots independently while retaining serialized write transactions.+ conn: Arc<Mutex<Connection>>,+ namespace: String,+}++// Absorb transient SQLite writer contention even when the manager's logical+// lock wait timeout is zero. This wait runs only on a blocking worker thread.+const SQLITE_BUSY_TIMEOUT: Duration = Duration::from_millis(100);+// Three total attempts, with 1 ms / 4 ms backoff after Busy. Each attempt keeps+// SQLite's 100 ms busy timeout; the backoff is additional to database waits.+const SQLITE_BUSY_ATTEMPTS: usize = 3;++fn db_error(error: rusqlite::Error) -> PathLockError {+ match &error {+ rusqlite::Error::SqliteFailure(code, _)+ if matches!(+ code.code,+ rusqlite::ErrorCode::DatabaseBusy | rusqlite::ErrorCode::DatabaseLocked+ ) =>+ {+ PathLockError::Busy {+ lock_path: "sqlite".to_string(),+ operation: "transaction".to_string(),+ }+ }+ _ => PathLockError::Io(format!("SQLite PathLock: {error}")),+ }+}++// Fixed-width decimal TEXT preserves the entire u128 range and lexical ordering.+fn timestamp(time_ns: u128) -> String {+ format!("{time_ns:039}")+}++fn validate_path(path: &str) -> PathLockResult<()> {+ if !path.starts_with('/')+ || (path != "/" && path.ends_with('/'))+ || path.contains("//")+ || path.contains('\0')+ || path.split('/').any(|part| matches!(part, "." | ".."))+ {+ return Err(PathLockError::InvalidRequest(format!(+ "SQLite PathLock requires a normalized absolute logical path: {path}"+ )));+ }+ Ok(())+}++fn validate_owner(owner: &str) -> PathLockResult<()> {+ if owner.is_empty() || owner.contains(':') {+ return Err(PathLockError::InvalidRequest(+ "lock owner must be nonempty and contain no ':'".to_string(),+ ));+ }+ Ok(())+}++fn ancestors(path: &str) -> Vec<&str> {+ if path == "/" {+ return Vec::new();+ }+ let mut result = vec!["/"];+ for (index, _) in path.match_indices('/').skip(1) {+ result.push(&path[..index]);+ }+ result+}++fn descendant_bounds(path: &str) -> (String, String) {+ if path == "/" {+ ("/".to_string(), "0".to_string())+ } else {+ // '/' is immediately followed by '0' in SQLite's BINARY collation.+ (format!("{path}/"), format!("{path}0"))+ }+}++fn decode_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<LockToken> {+ let time: String = row.get(1)?;+ let kind: String = row.get(2)?;+ let invalid = || rusqlite::Error::InvalidQuery;+ Ok(LockToken {+ owner_id: row.get(0)?,+ time_ns: time.parse().map_err(|_| invalid())?,+ lock_type: match kind.as_str() {+ "E" => PathLockKind::Exact,+ "T" => PathLockKind::Tree,+ _ => return Err(invalid()),+ },+ })+}++fn read(conn: &Connection, namespace: &str, path: &str) -> PathLockResult<Option<LockToken>> {+ conn.query_row(+ "SELECT owner, time_ns, kind FROM pathlock_tokens WHERE namespace=?1 AND path=?2",+ params![namespace, path],+ decode_row,+ )+ .optional()+ .map_err(db_error)+}++fn write(conn: &Connection, namespace: &str, path: &str, token: &LockToken) -> PathLockResult<()> {+ conn.execute(+ "INSERT INTO pathlock_tokens(namespace, path, owner, time_ns, kind)+ VALUES (?1,?2,?3,?4,?5)+ ON CONFLICT(namespace,path) DO UPDATE SET+ owner=excluded.owner, time_ns=excluded.time_ns, kind=excluded.kind",+ params![+ namespace,+ path,+ token.owner_id,+ timestamp(token.time_ns),+ token.lock_type.to_code().to_string()+ ],+ )+ .map_err(db_error)?;+ Ok(())+}++fn conflict(path: &str, token: &LockToken) -> PathLockError {+ PathLockError::Conflict {+ lock_path: path.to_string(),+ owner: token.owner_id.clone(),+ kind: token.lock_type,+ }+}++impl SQLitePathLockProvider {+ /// Open a persistent local database. Its parent directory must already exist.+ ///+ /// Use the same absolute file path and namespace in every cooperating process.+ /// SQLite file locking is intended for local disks, not network filesystems.+ /// Runtime SQLite Busy waits use 100 ms per attempt, with at most three+ /// attempts and 1 ms / 4 ms backoff, independently of the manager's logical+ /// lock wait timeout. All waits run on blocking worker threads.+ pub fn new(db_path: &str, namespace: &str) -> PathLockResult<Self> {+ if !Path::new(db_path).is_absolute() || namespace.trim().is_empty() {+ return Err(PathLockError::InvalidRequest(+ "SQLite PathLock requires an absolute sqlite_path and nonempty service_name"+ .to_string(),+ ));+ }+ let conn = Connection::open(db_path).map_err(db_error)?;+ // Allow concurrent process initialization.+ conn.busy_timeout(Duration::from_secs(5))+ .map_err(db_error)?;+ // FULL favors durability of committed lock records over NORMAL's lower+ // synchronization cost; losing a held token could allow conflicting writes.+ conn.execute_batch(+ "PRAGMA journal_mode=WAL;+ PRAGMA synchronous=FULL;+ CREATE TABLE IF NOT EXISTS pathlock_tokens (+ namespace TEXT NOT NULL,+ path TEXT COLLATE BINARY NOT NULL,+ owner TEXT NOT NULL,+ time_ns TEXT COLLATE BINARY NOT NULL CHECK(length(time_ns)=39),+ kind TEXT NOT NULL CHECK(kind IN ('E','T')),+ PRIMARY KEY(namespace,path)+ ) WITHOUT ROWID;+ CREATE INDEX IF NOT EXISTS pathlock_expiry ON pathlock_tokens(namespace,time_ns);",+ )+ .map_err(db_error)?;+ conn.busy_timeout(SQLITE_BUSY_TIMEOUT).map_err(db_error)?;+ Ok(Self {+ conn: Arc::new(Mutex::new(conn)),+ namespace: namespace.to_string(),+ })+ }++ async fn run<T, F>(&self, mut operation: F) -> PathLockResult<T>+ where+ T: Send + 'static,+ F: FnMut(&mut Connection, &str) -> PathLockResult<T> + Send + 'static,+ {+ let conn = self.conn.clone();+ let namespace = self.namespace.clone();+ tokio::task::spawn_blocking(move || {+ let mut conn = conn+ .lock()+ .map_err(|_| PathLockError::Internal("SQLite connection mutex poisoned".into()))?;+ for attempt in 0..SQLITE_BUSY_ATTEMPTS {+ match operation(&mut conn, &namespace) {+ Err(PathLockError::Busy { .. }) if attempt + 1 < SQLITE_BUSY_ATTEMPTS => {+ // Transaction closures drop (and roll back) before returning.+ // If rollback failed, clean up before replaying any mutations.+ if !conn.is_autocommit() {+ conn.execute_batch("ROLLBACK").map_err(db_error)?;+ }+ std::thread::sleep(Duration::from_millis(1 << (2 * attempt)));+ }+ result => return result,+ }+ }+ unreachable!("the final Busy attempt returns its error")+ })+ .await+ .map_err(|error| PathLockError::Internal(format!("SQLite worker failed: {error}")))?+ }+}++#[async_trait]+impl PathLockProvider for SQLitePathLockProvider {+ fn name(&self) -> &'static str {+ "sqlite"+ }++ fn handle_mode(&self) -> PathLockHandleMode {+ PathLockHandleMode::LogicalPath+ }++ async fn try_acquire_batch_atomic(+ &self,+ requests: &[PathLockRequest],+ owner_id: &str,+ now_ns: u128,+ stale_before_ns: u128,+ ) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {+ Ok(self+ .try_acquire_batch_atomic_with_stats(requests, owner_id, now_ns, stale_before_ns)+ .await?+ .map(|result| result.acquisitions))+ }++ async fn try_acquire_batch_atomic_with_stats(+ &self,+ requests: &[PathLockRequest],+ owner_id: &str,+ now_ns: u128,+ stale_before_ns: u128,+ ) -> PathLockResult<Option<AtomicAcquisitionResult>> {+ validate_owner(owner_id)?;+ if requests.is_empty() {+ return Err(PathLockError::InvalidRequest("empty lock batch".into()));+ }+ for request in requests {+ validate_path(&request.path)?;+ }+ let requests = requests.to_vec();+ let owner = owner_id.to_string();+ self.run(move |conn, namespace| {+ let tx = conn+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .map_err(db_error)?;+ let stale_before = timestamp(stale_before_ns);+ // Opportunistic global cleanup is bounded. Conflicting stale records+ // must also be removed completely below so their owners cannot revive+ // them after a successful takeover.+ let mut stale_tokens_removed = tx+ .execute(+ "DELETE FROM pathlock_tokens WHERE (namespace,path) IN (+ SELECT namespace,path FROM pathlock_tokens+ WHERE namespace=?1 AND time_ns<?2 AND owner<>?3 LIMIT 256)",+ params![namespace, stale_before, owner],+ )+ .map_err(db_error)?;+ let mut changes = Vec::with_capacity(requests.len());+ for request in &requests {+ stale_tokens_removed += tx+ .execute(+ "DELETE FROM pathlock_tokens+ WHERE namespace=?1 AND path=?2 AND owner<>?3 AND time_ns<?4",+ params![namespace, request.path, owner, stale_before],+ )+ .map_err(db_error)?;+ let existing = read(&tx, namespace, &request.path)?;+ if let Some(token) = &existing {+ if token.owner_id != owner && token.time_ns >= stale_before_ns {+ return Err(conflict(&request.path, token));+ }+ }+ for ancestor in ancestors(&request.path) {+ stale_tokens_removed += tx+ .execute(+ "DELETE FROM pathlock_tokens+ WHERE namespace=?1 AND path=?2 AND owner<>?3+ AND time_ns<?4 AND kind='T'",+ params![namespace, ancestor, owner, stale_before],+ )+ .map_err(db_error)?;+ if let Some(token) = read(&tx, namespace, ancestor)? {+ if token.lock_type == PathLockKind::Tree+ && token.owner_id != owner+ && token.time_ns >= stale_before_ns+ {+ return Err(conflict(ancestor, &token));+ }+ }+ }+ if request.kind == PathLockKind::Tree {+ let (lower, upper) = descendant_bounds(&request.path);+ stale_tokens_removed += tx+ .execute(+ "DELETE FROM pathlock_tokens+ WHERE namespace=?1 AND path>=?2 AND path<?3 AND path<>?4+ AND owner<>?5 AND time_ns<?6",+ params![namespace, lower, upper, request.path, owner, stale_before],+ )+ .map_err(db_error)?;+ let found = tx+ .query_row(+ "SELECT path, owner, time_ns, kind FROM pathlock_tokens+ WHERE namespace=?1 AND path>=?2 AND path<?3 AND path<>?4+ AND owner<>?5 AND time_ns>=?6 LIMIT 1",+ params![namespace, lower, upper, request.path, owner, stale_before],+ |row| {+ let path: String = row.get(0)?;+ Ok((+ path,+ LockToken {+ owner_id: row.get(1)?,+ time_ns: row+ .get::<_, String>(2)?+ .parse()+ .map_err(|_| rusqlite::Error::InvalidQuery)?,+ lock_type: match row.get::<_, String>(3)?.as_str() {+ "E" => PathLockKind::Exact,+ "T" => PathLockKind::Tree,+ _ => return Err(rusqlite::Error::InvalidQuery),+ },+ },+ ))+ },+ )+ .optional()+ .map_err(db_error)?;+ if let Some((path, token)) = found {+ return Err(conflict(&path, &token));+ }+ }+ let replacement = LockToken {+ owner_id: owner.clone(),+ time_ns: now_ns,+ lock_type: request.kind,+ };+ let change = match existing {+ Some(previous) if previous.owner_id == owner => {+ if previous.lock_type == PathLockKind::Exact+ && request.kind == PathLockKind::Tree+ {+ write(&tx, namespace, &request.path, &replacement)?;+ AcquisitionChange::Upgraded {+ previous,+ replacement,+ }+ } else {+ AcquisitionChange::Reentrant+ }+ }+ _ => {+ write(&tx, namespace, &request.path, &replacement)?;+ AcquisitionChange::Created { replacement }+ }+ };+ changes.push(AtomicAcquisition {+ handle: request.path.clone(),+ change,+ });+ }+ tx.commit().map_err(db_error)?;+ Ok(Some(AtomicAcquisitionResult {+ acquisitions: changes,+ stale_tokens_removed,+ }))+ })+ .await+ }++ async fn rollback_acquisitions_atomic(+ &self,+ acquisitions: &[AtomicAcquisition],+ owner_id: &str,+ ) -> PathLockResult<Option<()>> {+ let acquisitions = acquisitions.to_vec();+ let owner = owner_id.to_string();+ self.run(move |conn, namespace| {+ let tx = conn+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .map_err(db_error)?;+ // Reverse order also handles repeated paths within a batch.+ for acquisition in acquisitions.iter().rev() {+ match &acquisition.change {+ AcquisitionChange::Reentrant => {}+ AcquisitionChange::Created { replacement }+ | AcquisitionChange::Upgraded { replacement, .. }+ if replacement.owner_id != owner =>+ {+ return Err(PathLockError::InvalidRequest(+ "rollback owner mismatch".into(),+ ));+ }+ AcquisitionChange::Created { replacement } => {+ if read(&tx, namespace, &acquisition.handle)?.as_ref() != Some(replacement)+ {+ return Err(PathLockError::Internal("rollback token changed".into()));+ }+ tx.execute(+ "DELETE FROM pathlock_tokens WHERE namespace=?1 AND path=?2",+ params![namespace, acquisition.handle],+ )+ .map_err(db_error)?;+ }+ AcquisitionChange::Upgraded {+ previous,+ replacement,+ } => {+ if previous.owner_id != owner {+ return Err(PathLockError::InvalidRequest(+ "rollback previous owner mismatch".into(),+ ));+ }+ if read(&tx, namespace, &acquisition.handle)?.as_ref() != Some(replacement)+ {+ return Err(PathLockError::Internal("rollback token changed".into()));+ }+ write(&tx, namespace, &acquisition.handle, previous)?;+ }+ }+ }+ tx.commit().map_err(db_error)?;+ Ok(Some(()))+ })+ .await+ }++ async fn is_path_locked_atomic(+ &self,+ path: &str,+ _now_ns: u128,+ stale_before_ns: u128,+ ignore_stale: bool,+ ) -> PathLockResult<Option<bool>> {+ validate_path(path)?;+ let path = path.to_string();+ self.run(move |conn, namespace| {+ let tx = conn.transaction().map_err(db_error)?;+ if read(&tx, namespace, &path)?+ .is_some_and(|token| !ignore_stale || token.time_ns >= stale_before_ns)+ {+ return Ok(Some(true));+ }+ for ancestor in ancestors(&path) {+ if read(&tx, namespace, ancestor)?.is_some_and(|token| {+ token.lock_type == PathLockKind::Tree+ && (!ignore_stale || token.time_ns >= stale_before_ns)+ }) {+ return Ok(Some(true));+ }+ }+ Ok(Some(false))+ })+ .await+ }++ async fn read_token(&self, path: &str) -> PathLockResult<Option<LockToken>> {+ let path = path.to_string();+ self.run(move |conn, namespace| read(conn, namespace, &path))+ .await+ }++ async fn try_create_token(&self, path: &str, token: &LockToken) -> PathLockResult<()> {+ validate_path(path)?;+ validate_owner(&token.owner_id)?;+ let path = path.to_string();+ let token = token.clone();+ self.run(move |conn, namespace| {+ let tx = conn+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .map_err(db_error)?;+ if let Some(existing) = read(&tx, namespace, &path)? {+ return Err(conflict(&path, &existing));+ }+ write(&tx, namespace, &path, &token)?;+ tx.commit().map_err(db_error)+ })+ .await+ }++ async fn compare_and_write_token(+ &self,+ path: &str,+ expected: &LockToken,+ replacement: &LockToken,+ ) -> PathLockResult<bool> {+ validate_path(path)?;+ validate_owner(&replacement.owner_id)?;+ let path = path.to_string();+ let expected = expected.clone();+ let replacement = replacement.clone();+ self.run(move |conn, namespace| {+ let tx = conn+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .map_err(db_error)?;+ let matched = read(&tx, namespace, &path)?.as_ref() == Some(&expected);+ if matched {+ write(&tx, namespace, &path, &replacement)?;+ }+ tx.commit().map_err(db_error)?;+ Ok(matched)+ })+ .await+ }++ async fn refresh_token(&self, path: &str, owner: &str, time_ns: u128) -> PathLockResult<bool> {+ let path = path.to_string();+ let owner = owner.to_string();+ self.run(move |conn, namespace| {+ conn.execute(+ "UPDATE pathlock_tokens SET time_ns=?1 WHERE namespace=?2 AND path=?3 AND owner=?4",+ params![timestamp(time_ns), namespace, path, owner],+ )+ .map(|count| count == 1)+ .map_err(db_error)+ })+ .await+ }++ async fn remove_token(&self, path: &str, owner: &str, _force: bool) -> PathLockResult<bool> {+ let path = path.to_string();+ let owner = owner.to_string();+ self.run(move |conn, namespace| {+ conn.execute(+ "DELETE FROM pathlock_tokens WHERE namespace=?1 AND path=?2 AND owner=?3",+ params![namespace, path, owner],+ )+ .map(|count| count == 1)+ .map_err(db_error)+ })+ .await+ }++ async fn refresh_tokens(+ &self,+ paths: &[String],+ owner: &str,+ time_ns: u128,+ ) -> Vec<PathLockResult<bool>> {+ let validation: Vec<_> = paths.iter().map(|path| validate_path(path)).collect();+ let valid_paths: Vec<_> = paths+ .iter()+ .zip(&validation)+ .filter(|(_, result)| result.is_ok())+ .map(|(path, _)| path.clone())+ .collect();+ if valid_paths.is_empty() {+ return validation+ .into_iter()+ .map(|result| result.map(|_| false))+ .collect();+ }+ let owner = owner.to_string();+ // One worker and transaction per lease; bounded IN lists stay below SQLite+ // parameter limits. RETURNING identifies each owned path without extra reads.+ let result = self+ .run(move |conn, namespace| {+ let tx = conn+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .map_err(db_error)?;+ let mut refreshed = std::collections::HashSet::new();+ for batch in valid_paths.chunks(256) {+ let placeholders = vec!["?"; batch.len()].join(",");+ let sql = format!(+ "UPDATE pathlock_tokens SET time_ns=? WHERE namespace=? AND owner=?+ AND path IN ({placeholders}) RETURNING path"+ );+ let mut args = vec![timestamp(time_ns), namespace.to_string(), owner.clone()];+ args.extend_from_slice(batch);+ let mut stmt = tx.prepare(&sql).map_err(db_error)?;+ let rows = stmt+ .query_map(rusqlite::params_from_iter(args), |row| {+ row.get::<_, String>(0)+ })+ .map_err(db_error)?;+ for row in rows {+ refreshed.insert(row.map_err(db_error)?);+ }+ }+ tx.commit().map_err(db_error)?;+ Ok(refreshed)+ })+ .await;+ paths+ .iter()+ .zip(validation)+ .map(|(path, validation)| {+ validation?;+ match &result {+ Ok(refreshed) => Ok(refreshed.contains(path)),+ Err(PathLockError::Busy {+ lock_path,+ operation,+ }) => Err(PathLockError::Busy {+ lock_path: lock_path.clone(),+ operation: operation.clone(),+ }),+ Err(error) => Err(PathLockError::Io(error.to_string())),+ }+ })+ .collect()+ }++ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {+ // Trait compatibility and diagnostics only: the manager's atomic acquisition+ // hook returns early and never uses this fallback scan for SQLite.+ validate_path(root)?;+ let root = root.to_string();+ self.run(move |conn, namespace| {+ let (lower, upper) = descendant_bounds(&root);+ let mut stmt = conn+ .prepare(+ "SELECT path FROM pathlock_tokens+ WHERE namespace=?1 AND path>=?2 AND path<?3 AND path<>?4",+ )+ .map_err(db_error)?;+ let rows = stmt+ .query_map(params![namespace, lower, upper, root], |row| row.get(0))+ .map_err(db_error)?;+ rows.collect::<rusqlite::Result<Vec<_>>>().map_err(db_error)+ })+ .await+ }+}++#[cfg(test)]+#[path = "sqlite_provider_tests.rs"]+mod tests;diff --git a/crates/ragfs/src/lock/sqlite_provider_tests.rs b/crates/ragfs/src/lock/sqlite_provider_tests.rsnew file mode 100644index 000000000..af5ae1bc8--- /dev/null+++ b/crates/ragfs/src/lock/sqlite_provider_tests.rs@@ -0,0 +1,1146 @@+use super::*;+use crate::core::FileSystem;+use crate::lock::{PathLockConfig, PathLockManager};+use crate::plugins::memfs::MemFileSystem;+use std::process::{Child, Command};+use std::time::Instant;+use tempfile::TempDir;++fn provider(dir: &TempDir, namespace: &str) -> SQLitePathLockProvider {+ SQLitePathLockProvider::new(dir.path().join("locks.db").to_str().unwrap(), namespace).unwrap()+}++fn request(path: &str, kind: PathLockKind) -> PathLockRequest {+ PathLockRequest {+ path: path.into(),+ kind,+ }+}++async fn acquire(+ provider: &SQLitePathLockProvider,+ path: &str,+ kind: PathLockKind,+ owner: &str,+ now: u128,+ stale: u128,+) -> PathLockResult<Vec<AtomicAcquisition>> {+ provider+ .try_acquire_batch_atomic(&[request(path, kind)], owner, now, stale)+ .await+ .map(Option::unwrap)+}++#[tokio::test]+async fn exact_and_tree_conflicts_are_shared_between_connections() {+ let dir = TempDir::new().unwrap();+ let first = provider(&dir, "test");+ let second = provider(&dir, "test");+ acquire(&first, "/a", PathLockKind::Exact, "one", 100, 0)+ .await+ .unwrap();+ // An ancestor Exact does not cover its children.+ acquire(&second, "/a/b", PathLockKind::Exact, "two", 100, 0)+ .await+ .unwrap();+ assert!(matches!(+ acquire(&second, "/a", PathLockKind::Tree, "two", 100, 0).await,+ Err(PathLockError::Conflict { .. })+ ));+ assert!(+ matches!(acquire(&first, "/a", PathLockKind::Tree, "one", 100, 0).await,+ Err(PathLockError::Conflict { lock_path, .. }) if lock_path == "/a/b")+ );+ second.remove_token("/a/b", "two", false).await.unwrap();+ acquire(&first, "/a", PathLockKind::Tree, "one", 101, 0)+ .await+ .unwrap();+ assert!(matches!(+ acquire(&second, "/a/b", PathLockKind::Exact, "two", 101, 0).await,+ Err(PathLockError::Conflict {+ kind: PathLockKind::Tree,+ ..+ })+ ));+ assert_eq!(+ second+ .is_path_locked_atomic("/a/b", 101, 0, true)+ .await+ .unwrap(),+ Some(true)+ );+}++#[tokio::test]+async fn prefix_boundaries_wildcards_unicode_root_and_namespaces() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "one");+ for path in ["/ab/x", "/a%/x", "/a_/x", "/树/x", "/local/account2/x"] {+ acquire(&locks, path, PathLockKind::Exact, "one", 100, 0)+ .await+ .unwrap();+ }+ for path in ["/a", "/a%", "/a_", "/树", "/local/account2"] {+ let result = acquire(&locks, path, PathLockKind::Tree, "two", 100, 0).await;+ if path == "/a" {+ result.unwrap();+ } else {+ assert!(matches!(result, Err(PathLockError::Conflict { .. })));+ }+ }+ assert!(locks.scan_descendant_locks("/a").await.unwrap().is_empty());+ assert_eq!(locks.scan_descendant_locks("/").await.unwrap().len(), 6);+ assert!(matches!(+ acquire(&locks, "/", PathLockKind::Tree, "three", 100, 0).await,+ Err(PathLockError::Conflict { .. })+ ));+ // Separate services in the same DB do not conflict; account paths remain distinct.+ acquire(+ &provider(&dir, "two"),+ "/",+ PathLockKind::Tree,+ "three",+ 100,+ 0,+ )+ .await+ .unwrap();+ acquire(+ &locks,+ "/local/account1",+ PathLockKind::Tree,+ "three",+ 100,+ 0,+ )+ .await+ .unwrap();+}++#[tokio::test]+async fn stale_takeover_preserves_u128_boundary_and_ownership() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ acquire(&locks, "/a/b", PathLockKind::Exact, "old", u128::MAX - 1, 0)+ .await+ .unwrap();+ assert!(matches!(+ acquire(+ &locks,+ "/a",+ PathLockKind::Tree,+ "new",+ u128::MAX,+ u128::MAX - 1+ )+ .await,+ Err(PathLockError::Conflict { .. })+ ));+ acquire(+ &locks,+ "/a",+ PathLockKind::Tree,+ "new",+ u128::MAX,+ u128::MAX,+ )+ .await+ .unwrap();+ assert_eq!(+ locks.read_token("/a").await.unwrap().unwrap().time_ns,+ u128::MAX+ );+ acquire(+ &locks,+ "/a/b",+ PathLockKind::Exact,+ "new",+ u128::MAX,+ u128::MAX,+ )+ .await+ .unwrap();+ assert!(!locks.refresh_token("/a/b", "old", 0).await.unwrap());+ assert!(!locks.remove_token("/a/b", "old", true).await.unwrap());+ assert!(locks.refresh_token("/a/b", "new", 9).await.unwrap());+ assert_eq!(+ locks+ .is_path_locked_atomic("/a", u128::MAX, u128::MAX, true)+ .await+ .unwrap(),+ Some(true)+ );+ locks.remove_token("/a", "new", false).await.unwrap();+ assert_eq!(+ locks+ .is_path_locked_atomic("/a/b", 10, 10, true)+ .await+ .unwrap(),+ Some(false)+ );+ assert_eq!(+ locks+ .is_path_locked_atomic("/a/b", 10, 10, false)+ .await+ .unwrap(),+ Some(true)+ );+ // Decimal length changes must not reverse staleness.+ assert!(matches!(+ acquire(&locks, "/a/b", PathLockKind::Exact, "next", 10, 9).await,+ Err(PathLockError::Conflict { .. })+ ));+ acquire(&locks, "/a/b", PathLockKind::Exact, "next", 10, 10)+ .await+ .unwrap();+}++#[tokio::test]+async fn conflict_rolls_back_the_whole_batch_including_upgrades() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ acquire(&locks, "/a", PathLockKind::Exact, "one", 1, 0)+ .await+ .unwrap();+ acquire(&locks, "/z", PathLockKind::Exact, "two", 1, 0)+ .await+ .unwrap();+ let before = locks.read_token("/a").await.unwrap();+ let result = locks+ .try_acquire_batch_atomic(+ &[+ request("/a", PathLockKind::Tree),+ request("/b", PathLockKind::Exact),+ request("/z", PathLockKind::Exact),+ ],+ "one",+ 2,+ 0,+ )+ .await;+ assert!(matches!(result, Err(PathLockError::Conflict { .. })));+ assert_eq!(locks.read_token("/a").await.unwrap(), before);+ assert_eq!(locks.read_token("/b").await.unwrap(), None);+}++#[tokio::test]+async fn rollback_restores_upgrade_and_preserves_reentrant_tokens() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ acquire(&locks, "/a", PathLockKind::Exact, "one", 1, 0)+ .await+ .unwrap();+ let before = locks.read_token("/a").await.unwrap();+ let changes = locks+ .try_acquire_batch_atomic(+ &[+ request("/a", PathLockKind::Exact),+ request("/a", PathLockKind::Tree),+ request("/b", PathLockKind::Exact),+ request("/b", PathLockKind::Tree),+ ],+ "one",+ 2,+ 0,+ )+ .await+ .unwrap()+ .unwrap();+ assert_eq!(changes[0].change, AcquisitionChange::Reentrant);+ locks+ .rollback_acquisitions_atomic(&changes, "one")+ .await+ .unwrap();+ assert_eq!(locks.read_token("/a").await.unwrap(), before);+ assert_eq!(locks.read_token("/b").await.unwrap(), None);+}++#[tokio::test]+async fn changed_rollback_is_atomic_and_cas_checks_the_entire_token() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ let changes = locks+ .try_acquire_batch_atomic(+ &[+ request("/a", PathLockKind::Exact),+ request("/b", PathLockKind::Exact),+ ],+ "one",+ 1,+ 0,+ )+ .await+ .unwrap()+ .unwrap();+ let expected = locks.read_token("/a").await.unwrap().unwrap();+ assert!(locks.refresh_token("/a", "one", 2).await.unwrap());+ assert!(!locks+ .compare_and_write_token("/a", &expected, &expected)+ .await+ .unwrap());+ assert!(locks+ .rollback_acquisitions_atomic(&changes, "one")+ .await+ .is_err());+ // /b was removed first, but the transaction must roll that deletion back.+ assert!(locks.read_token("/b").await.unwrap().is_some());+ let current = locks.read_token("/a").await.unwrap().unwrap();+ assert!(locks+ .compare_and_write_token("/a", ¤t, &expected)+ .await+ .unwrap());+ locks+ .rollback_acquisitions_atomic(&changes, "one")+ .await+ .unwrap();+ assert!(locks.scan_descendant_locks("/").await.unwrap().is_empty());+}++#[tokio::test]+async fn database_write_contention_is_retryable_busy() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();+ let tx = blocker+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .unwrap();+ let start = Instant::now();+ assert!(matches!(+ acquire(&locks, "/a", PathLockKind::Tree, "one", 1, 0).await,+ Err(PathLockError::Busy { .. })+ ));+ assert!(start.elapsed() >= SQLITE_BUSY_TIMEOUT);+ assert!(start.elapsed() < Duration::from_secs(3));+ drop(tx);+ acquire(&locks, "/a", PathLockKind::Tree, "one", 1, 0)+ .await+ .unwrap();+}++#[tokio::test]+async fn run_retries_busy_from_clean_transactions_without_duplicate_mutations() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ acquire(&locks, "/old", PathLockKind::Exact, "dead", 1, 0)+ .await+ .unwrap();+ let mut attempts = 0;+ let result = locks+ .run(move |conn, namespace| {+ attempts += 1;+ assert!(conn.is_autocommit());+ let tx = conn+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .map_err(db_error)?;+ // Both mutations from each failed attempt must have rolled back.+ assert!(read(&tx, namespace, "/old")?.is_some());+ assert!(read(&tx, namespace, "/new")?.is_none());+ let removed = tx+ .execute(+ "DELETE FROM pathlock_tokens WHERE namespace=?1 AND path='/old'",+ params![namespace],+ )+ .map_err(db_error)?;+ write(+ &tx,+ namespace,+ "/new",+ &LockToken {+ owner_id: "new".into(),+ time_ns: 2,+ lock_type: PathLockKind::Tree,+ },+ )?;+ if attempts < SQLITE_BUSY_ATTEMPTS {+ return Err(PathLockError::Busy {+ lock_path: "sqlite".into(),+ operation: "injected after mutation".into(),+ });+ }+ tx.commit().map_err(db_error)?;+ Ok((attempts, removed))+ })+ .await+ .unwrap();+ assert_eq!(result, (SQLITE_BUSY_ATTEMPTS, 1));+ assert!(locks.read_token("/old").await.unwrap().is_none());+ assert_eq!(+ locks.read_token("/new").await.unwrap().unwrap().owner_id,+ "new"+ );+}++#[tokio::test]+async fn run_bounds_busy_attempts_and_does_not_retry_other_errors() {+ use std::sync::atomic::{AtomicUsize, Ordering};+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ for kind in ["busy", "conflict", "invalid", "io"] {+ let calls = Arc::new(AtomicUsize::new(0));+ let observed = calls.clone();+ let result: PathLockResult<()> = locks+ .run(move |_, _| {+ observed.fetch_add(1, Ordering::SeqCst);+ Err(match kind {+ "busy" => PathLockError::Busy {+ lock_path: "sqlite".into(),+ operation: "injected".into(),+ },+ "conflict" => PathLockError::Conflict {+ lock_path: "/a".into(),+ owner: "other".into(),+ kind: PathLockKind::Tree,+ },+ "invalid" => PathLockError::InvalidRequest("injected".into()),+ _ => PathLockError::Io("injected".into()),+ })+ })+ .await;+ assert_eq!(+ calls.load(Ordering::SeqCst),+ if kind == "busy" {+ SQLITE_BUSY_ATTEMPTS+ } else {+ 1+ }+ );+ assert!(matches!(+ (kind, result),+ ("busy", Err(PathLockError::Busy { .. }))+ | ("conflict", Err(PathLockError::Conflict { .. }))+ | ("invalid", Err(PathLockError::InvalidRequest(_)))+ | ("io", Err(PathLockError::Io(_)))+ ));+ }+}++async fn with_transient_writer<T>(+ blocker: &mut Connection,+ operation: impl std::future::Future<Output = T>,+) -> T {+ let tx = blocker+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .unwrap();+ // Keep the writer longer than one busy timeout, then allow provider retries+ // to recover. Tokio's timer also verifies waits stay off the async executor.+ let (result, ()) = tokio::join!(operation, async {+ tokio::time::sleep(SQLITE_BUSY_TIMEOUT + Duration::from_millis(50)).await;+ drop(tx);+ });+ result+}++#[tokio::test]+async fn busy_retries_cover_zero_timeout_acquire_refresh_release_and_rollback() {+ let dir = TempDir::new().unwrap();+ let locks = Arc::new(provider(&dir, "test"));+ let manager = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ locks.clone(),+ PathLockConfig::default(),+ );+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();+ let lease = with_transient_writer(+ &mut blocker,+ manager.acquire_tree("/a", Duration::ZERO, None),+ )+ .await+ .unwrap();+ assert_eq!(+ with_transient_writer(&mut blocker, manager.refresh(&lease))+ .await+ .unwrap(),+ "refreshed"+ );+ assert!(with_transient_writer(+ &mut blocker,+ locks.refresh_token("/a", &lease.lease.owner_id, u128::MAX),+ )+ .await+ .unwrap());+ with_transient_writer(&mut blocker, manager.release(&lease))+ .await+ .unwrap();+ assert!(locks.read_token("/a").await.unwrap().is_none());++ let changes = acquire(&locks, "/rollback", PathLockKind::Tree, "owner", 1, 0)+ .await+ .unwrap();+ with_transient_writer(+ &mut blocker,+ locks.rollback_acquisitions_atomic(&changes, "owner"),+ )+ .await+ .unwrap();+ assert!(locks.read_token("/rollback").await.unwrap().is_none());+}++#[tokio::test]+async fn manager_zero_timeout_waits_for_transient_sqlite_writer() {+ let dir = TempDir::new().unwrap();+ let locks = Arc::new(provider(&dir, "test"));+ let manager = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ locks.clone(),+ PathLockConfig::default(),+ );+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();+ let tx = blocker+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .unwrap();+ let (lease, ()) = tokio::join!(manager.acquire_tree("/a", Duration::ZERO, None), async {+ tokio::time::sleep(Duration::from_millis(20)).await;+ drop(tx);+ });+ let lease = lease.unwrap();+ manager.release(&lease).await.unwrap();+ assert!(locks.read_token("/a").await.unwrap().is_none());+}++#[tokio::test]+async fn rejects_invalid_paths_and_owner_before_mutation() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ for path in ["relative", "/a/", "/a//b", "/a/../b", "/./a", "/a\0b"] {+ assert!(matches!(+ acquire(&locks, path, PathLockKind::Exact, "one", 1, 0).await,+ Err(PathLockError::InvalidRequest(_))+ ));+ }+ for owner in ["", "bad:owner"] {+ assert!(matches!(+ acquire(&locks, "/a", PathLockKind::Exact, owner, 1, 0).await,+ Err(PathLockError::InvalidRequest(_))+ ));+ }+ assert!(locks.scan_descendant_locks("/").await.unwrap().is_empty());+ assert!(SQLitePathLockProvider::new(":memory:", "test").is_err());+ assert!(+ SQLitePathLockProvider::new(dir.path().join("other.db").to_str().unwrap(), "").is_err()+ );+}++#[tokio::test]+async fn manager_lifecycle_uses_logical_handles_and_never_reads_business_directories() {+ let dir = TempDir::new().unwrap();+ let fs = Arc::new(MemFileSystem::new());+ let locks = Arc::new(provider(&dir, "test"));+ let manager = PathLockManager::new(fs.clone(), locks.clone(), PathLockConfig::default());+ let other = PathLockManager::new(+ fs.clone(),+ Arc::new(provider(&dir, "test")),+ PathLockConfig::default(),+ );+ // This business directory does not exist. A filesystem scan would fail.+ let exact = manager+ .acquire_exact("/missing/file", Duration::ZERO, None)+ .await+ .unwrap();+ assert_eq!(exact.lease.lock_paths, vec!["/missing/file"]);+ assert!(other+ .acquire_tree("/missing", Duration::ZERO, None)+ .await+ .is_err());+ let tree = manager+ .acquire_tree(+ "/missing",+ Duration::ZERO,+ Some((&exact.lease.lease_ref, &exact.ownership_ref)),+ )+ .await+ .unwrap();+ assert!(other.is_locked("/missing/child", true).await.unwrap());+ manager.release(&tree).await.unwrap();+ manager.release(&exact).await.unwrap();+ let tree = other+ .acquire_tree("/missing", Duration::ZERO, None)+ .await+ .unwrap();+ other.release(&tree).await.unwrap();+ assert!(locks.scan_descendant_locks("/").await.unwrap().is_empty());+ assert_eq!(+ fs.read_dir("/", None, None, None, None)+ .await+ .unwrap()+ .len(),+ 0+ );+}++#[tokio::test]+async fn manager_upgrade_downgrades_and_handoff_adopts() {+ let dir = TempDir::new().unwrap();+ let locks = Arc::new(provider(&dir, "test"));+ let fs = Arc::new(MemFileSystem::new());+ let manager = PathLockManager::new(fs.clone(), locks.clone(), PathLockConfig::default());+ let exact = manager+ .acquire_exact("/a", Duration::ZERO, None)+ .await+ .unwrap();+ let tree = manager+ .acquire_tree(+ "/a",+ Duration::ZERO,+ Some((&exact.lease.lease_ref, &exact.ownership_ref)),+ )+ .await+ .unwrap();+ manager.release(&tree).await.unwrap();+ assert_eq!(+ locks.read_token("/a").await.unwrap().unwrap().lock_type,+ PathLockKind::Exact+ );+ let handoff = manager.to_handoff(&exact);+ manager.handoff(&exact).await.unwrap();+ let recipient = PathLockManager::new(+ fs,+ Arc::new(provider(&dir, "test")),+ PathLockConfig::default(),+ );+ let adopted = recipient.adopt(&handoff).await.unwrap();+ recipient.release(&adopted).await.unwrap();+ assert_eq!(locks.read_token("/a").await.unwrap(), None);+}++#[tokio::test]+async fn manager_refreshes_live_tokens() {+ let dir = TempDir::new().unwrap();+ let locks = Arc::new(provider(&dir, "test"));+ let config = PathLockConfig {+ lock_expire_secs: 1.0,+ ..PathLockConfig::default()+ };+ let manager = PathLockManager::new(Arc::new(MemFileSystem::new()), locks.clone(), config);+ let lease = manager+ .acquire_tree("/a", Duration::ZERO, None)+ .await+ .unwrap();+ let initial = locks.read_token("/a").await.unwrap().unwrap().time_ns;+ tokio::time::timeout(Duration::from_secs(3), async {+ loop {+ if locks.read_token("/a").await.unwrap().unwrap().time_ns > initial {+ break;+ }+ tokio::time::sleep(Duration::from_millis(20)).await;+ }+ })+ .await+ .unwrap();+ manager.release(&lease).await.unwrap();+}++#[tokio::test]+async fn stale_cleanup_is_bounded_and_keeps_this_owners_tokens() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ let requests: Vec<_> = (0..300)+ .map(|id| request(&format!("/old/{id}"), PathLockKind::Exact))+ .collect();+ locks+ .try_acquire_batch_atomic(&requests, "old", 1, 0)+ .await+ .unwrap();+ acquire(&locks, "/own", PathLockKind::Exact, "new", 1, 0)+ .await+ .unwrap();+ acquire(&locks, "/new", PathLockKind::Exact, "new", 2, 2)+ .await+ .unwrap();+ assert_eq!(locks.scan_descendant_locks("/old").await.unwrap().len(), 44);+ assert!(locks.read_token("/own").await.unwrap().is_some());+ acquire(&locks, "/new", PathLockKind::Exact, "new", 3, 2)+ .await+ .unwrap();+ assert!(locks+ .scan_descendant_locks("/old")+ .await+ .unwrap()+ .is_empty());+}++#[tokio::test]+async fn stale_conflicting_descendants_cannot_be_revived_after_tree_takeover() {+ for root in ["/a", "/"] {+ let dir = TempDir::new().unwrap();+ let old = provider(&dir, "test");+ let new = provider(&dir, "test");+ let requests: Vec<_> = (0..300)+ .map(|id| {+ request(+ &format!("{}/child/{id:03}", root.trim_end_matches('/')),+ if id % 2 == 0 {+ PathLockKind::Exact+ } else {+ PathLockKind::Tree+ },+ )+ })+ .collect();+ old.try_acquire_batch_atomic(&requests, "old", 1, 0)+ .await+ .unwrap();+ let result = new+ .try_acquire_batch_atomic_with_stats(&[request(root, PathLockKind::Tree)], "new", 10, 2)+ .await+ .unwrap()+ .unwrap();+ let paths: Vec<_> = requests+ .iter()+ .map(|request| request.path.clone())+ .collect();+ let refreshed = old.refresh_tokens(&paths, "old", 11).await;+ assert!(+ refreshed.iter().all(|result| matches!(result, Ok(false))),+ "expired descendants must not revive under {root}: {refreshed:?}"+ );+ assert_eq!(result.stale_tokens_removed, 300);+ assert!(!old.refresh_token(&paths[299], "old", 12).await.unwrap());+ assert!(new.scan_descendant_locks(root).await.unwrap().is_empty());+ assert_eq!(new.read_token(root).await.unwrap().unwrap().owner_id, "new");+ assert!(matches!(+ acquire(&old, &paths[299], PathLockKind::Exact, "old", 12, 2).await,+ Err(PathLockError::Conflict {+ kind: PathLockKind::Tree,+ ..+ })+ ));+ }+}++#[tokio::test]+async fn stale_target_and_ancestor_trees_are_cleaned_beyond_unrelated_budget() {+ let dir = TempDir::new().unwrap();+ let old = provider(&dir, "test");+ let new = provider(&dir, "test");+ let unrelated: Vec<_> = (0..300)+ .map(|id| request(&format!("/unrelated/{id:03}"), PathLockKind::Exact))+ .collect();+ old.try_acquire_batch_atomic(&unrelated, "old", 0, 0)+ .await+ .unwrap();+ let conflicting = [+ request("/", PathLockKind::Tree),+ request("/a", PathLockKind::Tree),+ request("/a/b/c", PathLockKind::Exact),+ ];+ old.try_acquire_batch_atomic(&conflicting, "old", 1, 0)+ .await+ .unwrap();+ acquire(&old, "/a/b", PathLockKind::Exact, "old", 1, 0)+ .await+ .unwrap();+ // A separate namespace survives the cleanup.+ let other = provider(&dir, "other");+ acquire(&other, "/", PathLockKind::Tree, "old", 1, 0)+ .await+ .unwrap();+ let result = new+ .try_acquire_batch_atomic_with_stats(+ &[request("/a/b/c", PathLockKind::Exact)],+ "new",+ 10,+ 2,+ )+ .await+ .unwrap()+ .unwrap();+ assert_eq!(result.stale_tokens_removed, 259);+ let paths: Vec<_> = conflicting+ .iter()+ .map(|request| request.path.clone())+ .collect();+ assert!(old+ .refresh_tokens(&paths, "old", 11)+ .await+ .iter()+ .all(|result| matches!(result, Ok(false))));+ assert_eq!(+ old.scan_descendant_locks("/unrelated").await.unwrap().len(),+ 44+ );+ assert!(old.refresh_token("/a/b", "old", 11).await.unwrap());+ assert!(other.refresh_token("/", "old", 11).await.unwrap());+}++#[tokio::test]+async fn failed_batch_restores_stale_conflicts_beyond_cleanup_budget() {+ let dir = TempDir::new().unwrap();+ let old = provider(&dir, "test");+ let new = provider(&dir, "test");+ let requests: Vec<_> = (0..300)+ .map(|id| request(&format!("/a/{id:03}"), PathLockKind::Exact))+ .collect();+ old.try_acquire_batch_atomic(&requests, "old", 1, 0)+ .await+ .unwrap();+ acquire(&old, "/live", PathLockKind::Exact, "live", 10, 0)+ .await+ .unwrap();+ assert!(matches!(+ new.try_acquire_batch_atomic_with_stats(+ &[+ request("/a", PathLockKind::Tree),+ request("/live", PathLockKind::Exact),+ ],+ "new",+ 10,+ 2,+ )+ .await,+ Err(PathLockError::Conflict { .. })+ ));+ assert!(new.read_token("/a").await.unwrap().is_none());+ assert_eq!(old.scan_descendant_locks("/a").await.unwrap().len(), 300);+ let paths: Vec<_> = requests+ .iter()+ .map(|request| request.path.clone())+ .collect();+ assert!(old+ .refresh_tokens(&paths, "old", 11)+ .await+ .iter()+ .all(|result| matches!(result, Ok(true))));+}++fn wait_for_file(path: &Path) {+ let start = Instant::now();+ while !path.exists() {+ assert!(+ start.elapsed() < Duration::from_secs(15),+ "timed out waiting for {path:?}"+ );+ std::thread::sleep(Duration::from_millis(5));+ }+}++#[tokio::test]+async fn batch_refresh_preserves_order_ownership_kinds_and_large_batches() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ let requests: Vec<_> = (0..600)+ .map(|id| {+ request(+ &format!("/batch/{id}"),+ if id % 2 == 0 {+ PathLockKind::Tree+ } else {+ PathLockKind::Exact+ },+ )+ })+ .collect();+ locks+ .try_acquire_batch_atomic(&requests, "one", 1, 0)+ .await+ .unwrap();+ acquire(&locks, "/foreign", PathLockKind::Exact, "two", 1, 0)+ .await+ .unwrap();+ let mut paths: Vec<_> = requests+ .iter()+ .map(|request| request.path.clone())+ .collect();+ paths.extend([+ "/missing".into(),+ "/foreign".into(),+ "invalid".into(),+ "/batch/0".into(),+ ]);+ let results = locks.refresh_tokens(&paths, "one", u128::MAX).await;+ assert_eq!(results.len(), paths.len());+ assert!(results[..600]+ .iter()+ .all(|result| matches!(result, Ok(true))));+ assert!(matches!(results[600], Ok(false)));+ assert!(matches!(results[601], Ok(false)));+ assert!(matches!(+ results[602],+ Err(PathLockError::InvalidRequest(_))+ ));+ assert!(matches!(results[603], Ok(true)));+ for request in requests {+ let token = locks.read_token(&request.path).await.unwrap().unwrap();+ assert_eq!(token.time_ns, u128::MAX);+ assert_eq!(token.lock_type, request.kind);+ }+ assert_eq!(+ locks.read_token("/foreign").await.unwrap().unwrap().time_ns,+ 1+ );+ assert!(locks.refresh_tokens(&[], "one", 2).await.is_empty());+}++#[tokio::test]+async fn batch_refresh_reports_busy_for_every_path_and_does_not_partially_commit() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ acquire(&locks, "/a", PathLockKind::Exact, "one", 1, 0)+ .await+ .unwrap();+ acquire(&locks, "/b", PathLockKind::Exact, "one", 1, 0)+ .await+ .unwrap();+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();+ let tx = blocker+ .transaction_with_behavior(TransactionBehavior::Immediate)+ .unwrap();+ let results = locks+ .refresh_tokens(&["/a".into(), "/b".into()], "one", 2)+ .await;+ assert!(results+ .iter()+ .all(|result| matches!(result, Err(PathLockError::Busy { .. }))));+ drop(tx);+ assert_eq!(locks.read_token("/a").await.unwrap().unwrap().time_ns, 1);+ assert_eq!(locks.read_token("/b").await.unwrap().unwrap().time_ns, 1);+}++#[tokio::test]+async fn atomic_recovery_counts_committed_cleanup_and_stale_replacements_once() {+ let dir = TempDir::new().unwrap();+ let locks = provider(&dir, "test");+ let requests: Vec<_> = (0..300)+ .map(|id| request(&format!("/old/{id:03}"), PathLockKind::Exact))+ .collect();+ locks+ .try_acquire_batch_atomic(&requests, "old", 1, 0)+ .await+ .unwrap();+ let result = locks+ .try_acquire_batch_atomic_with_stats(+ &[request("/old/299", PathLockKind::Tree)],+ "new",+ 10,+ 2,+ )+ .await+ .unwrap()+ .unwrap();+ assert_eq!(result.stale_tokens_removed, 257);+ let result = locks+ .try_acquire_batch_atomic_with_stats(+ &[request("/old/299", PathLockKind::Tree)],+ "new",+ 10,+ 2,+ )+ .await+ .unwrap()+ .unwrap();+ assert_eq!(result.stale_tokens_removed, 43);+ let result = locks+ .try_acquire_batch_atomic_with_stats(+ &[request("/old/299", PathLockKind::Tree)],+ "new",+ 10,+ 2,+ )+ .await+ .unwrap()+ .unwrap();+ assert_eq!(result.stale_tokens_removed, 0);+}++#[tokio::test]+async fn manager_observes_only_committed_stale_recovery() {+ let dir = TempDir::new().unwrap();+ let locks = Arc::new(provider(&dir, "test"));+ acquire(&locks, "/old", PathLockKind::Exact, "dead", 1, 0)+ .await+ .unwrap();+ acquire(&locks, "/live", PathLockKind::Exact, "live", u128::MAX, 0)+ .await+ .unwrap();+ let manager = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ locks.clone(),+ PathLockConfig::default(),+ );+ assert!(manager+ .acquire_exact("/live", Duration::ZERO, None)+ .await+ .is_err());+ assert_eq!(manager.observe().await.stale_locks_removed, 0);+ assert!(locks.read_token("/old").await.unwrap().is_some());+ let lease = manager+ .acquire_tree("/old", Duration::ZERO, None)+ .await+ .unwrap();+ assert_eq!(manager.observe().await.stale_locks_removed, 1);+ manager.release(&lease).await.unwrap();+}++// Kill only subprocesses started by this test if a failed assertion unwinds.+struct Contender(Child);+impl Drop for Contender {+ fn drop(&mut self) {+ let _ = self.0.kill();+ let _ = self.0.wait();+ }+}++#[test]+fn separate_processes_cannot_acquire_tree_and_descendant_simultaneously() {+ let dir = TempDir::new().unwrap();+ drop(provider(&dir, "test"));+ for (left, right, successes) in [+ ("/a", "/a/b", 1),+ ("/", "/a/b", 1),+ ("/a", "/a", 1),+ ("/a", "/b", 2),+ ] {+ let round = dir.path().join(uuid::Uuid::new_v4().to_string());+ std::fs::create_dir(&round).unwrap();+ let mut children = Vec::new();+ for (id, path, kind) in [("left", left, "T"), ("right", right, "E")] {+ let child = Command::new(std::env::current_exe().unwrap())+ .args([+ "--exact",+ "lock::sqlite_provider::tests::subprocess_contender",+ "--ignored",+ "--nocapture",+ ])+ .env("OV_SQLITE_TEST_DIR", dir.path())+ .env("OV_SQLITE_TEST_ROUND", &round)+ .env("OV_SQLITE_TEST_ID", id)+ .env("OV_SQLITE_TEST_PATH", path)+ .env("OV_SQLITE_TEST_KIND", kind)+ .spawn()+ .unwrap();+ children.push(Contender(child));+ }+ wait_for_file(&round.join("left.ready"));+ wait_for_file(&round.join("right.ready"));+ std::fs::write(round.join("go"), "").unwrap();+ wait_for_file(&round.join("left.result"));+ wait_for_file(&round.join("right.result"));+ let results: Vec<_> = ["left", "right"]+ .iter()+ .map(|id| std::fs::read_to_string(round.join(format!("{id}.result"))).unwrap())+ .collect();+ std::fs::write(round.join("release"), "").unwrap();+ for child in &mut children {+ assert!(child.0.wait().unwrap().success());+ }+ assert_eq!(+ results+ .iter()+ .filter(|result| *result == "acquired")+ .count(),+ successes+ );+ assert_eq!(+ results+ .iter()+ .filter(|result| *result == "conflict")+ .count(),+ 2 - successes+ );+ }+}++#[test]+fn crashed_process_token_is_persistent_and_can_be_reclaimed() {+ let dir = TempDir::new().unwrap();+ drop(provider(&dir, "test"));+ let round = dir.path().join("crash");+ std::fs::create_dir(&round).unwrap();+ std::fs::write(round.join("go"), "").unwrap();+ let mut child = Contender(+ Command::new(std::env::current_exe().unwrap())+ .args([+ "--exact",+ "lock::sqlite_provider::tests::subprocess_contender",+ "--ignored",+ ])+ .env("OV_SQLITE_TEST_DIR", dir.path())+ .env("OV_SQLITE_TEST_ROUND", &round)+ .env("OV_SQLITE_TEST_ID", "crashed")+ .env("OV_SQLITE_TEST_PATH", "/a/b")+ .env("OV_SQLITE_TEST_KIND", "E")+ .env("OV_SQLITE_TEST_CRASH", "1")+ .spawn()+ .unwrap(),+ );+ wait_for_file(&round.join("crashed.result"));+ assert!(child.0.wait().unwrap().success());+ let locks = provider(&dir, "test");+ let runtime = tokio::runtime::Runtime::new().unwrap();+ assert!(matches!(+ runtime.block_on(acquire(&locks, "/a", PathLockKind::Tree, "next", 101, 100)),+ Err(PathLockError::Conflict { .. })+ ));+ runtime+ .block_on(acquire(&locks, "/a", PathLockKind::Tree, "next", 101, 101))+ .unwrap();+ assert!(+ runtime+ .block_on(locks.remove_token("/a/b", "crashed", false))+ .unwrap()+ == false+ );+}++#[test]+#[ignore = "subprocess helper invoked by separate_processes test"]+fn subprocess_contender() {+ let dir = std::path::PathBuf::from(std::env::var("OV_SQLITE_TEST_DIR").unwrap());+ let round = std::path::PathBuf::from(std::env::var("OV_SQLITE_TEST_ROUND").unwrap());+ let id = std::env::var("OV_SQLITE_TEST_ID").unwrap();+ let path = std::env::var("OV_SQLITE_TEST_PATH").unwrap();+ let kind = if std::env::var("OV_SQLITE_TEST_KIND").unwrap() == "T" {+ PathLockKind::Tree+ } else {+ PathLockKind::Exact+ };+ let locks =+ SQLitePathLockProvider::new(dir.join("locks.db").to_str().unwrap(), "test").unwrap();+ let runtime = tokio::runtime::Runtime::new().unwrap();+ std::fs::write(round.join(format!("{id}.ready")), "").unwrap();+ wait_for_file(&round.join("go"));+ if std::env::var_os("OV_SQLITE_TEST_CRASH").is_some() {+ runtime+ .block_on(acquire(&locks, &path, kind, &id, 100, 0))+ .unwrap();+ std::fs::write(round.join(format!("{id}.result")), "acquired").unwrap();+ // Skip connection/runtime destructors as with an abruptly terminated owner.+ std::process::exit(0);+ }+ let manager = runtime.block_on(async {+ PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ Arc::new(locks),+ PathLockConfig::default(),+ )+ });+ // Exercise the production path with the configured zero logical wait timeout.+ // No test-side Busy retry may hide a transient database contention failure.+ let lease = match runtime.block_on(manager.acquire_batch(+ &[request(&path, kind)],+ Duration::ZERO,+ None,+ )) {+ Ok(lease) => Some(lease),+ Err(PathLockError::Timeout { .. }) => {+ assert!(+ !runtime.block_on(manager.observe()).conflicts.is_empty(),+ "zero-timeout acquisition failed without an actual logical lock conflict"+ );+ None+ }+ Err(error) => panic!("{error}"),+ };+ std::fs::write(+ round.join(format!("{id}.result")),+ if lease.is_some() {+ "acquired"+ } else {+ "conflict"+ },+ )+ .unwrap();+ wait_for_file(&round.join("release"));+ if let Some(lease) = lease {+ runtime.block_on(manager.release(&lease)).unwrap();+ }+}diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.mdindex b6dd0b83b..a61751936 100644--- a/docs/en/concepts/09-transaction.md+++ b/docs/en/concepts/09-transaction.md@@ -440,9 +440,15 @@ Redis-backed configuration:| Parameter | Type | Description | Default ||-----------|------|-------------|---------|-| `provider` | str | `filesystem`, `memory`, or `cache` | `filesystem` |+| `provider` | str | `filesystem`, `memory`, `sqlite`, or `cache` | `filesystem` |+| `sqlite_path` | str / null | Optional absolute local database path for `sqlite`; see [SQLite setup](../configuration/01-server.md#storage) | `{storage.workspace}/_system/pathlock/pathlock.db` for `sqlite` || `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale | `30.0` |+For replicas sharing EFS across containers or hosts, use `provider="cache"` with+shared Redis. SQLite is limited to one shared database file on the same machine's+local disk; EFS/NFS/SMB and independent container-local databases are unsupported.+See [deployment limits and provider selection](../configuration/01-server.md#storage).+Legacy compatibility form:```jsondiff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.mdindex 3c6923dae..17be9c1a5 100644--- a/docs/en/configuration/01-server.md+++ b/docs/en/configuration/01-server.md@@ -303,12 +303,65 @@ Search and Find requests default to `limit: 10`; override the limit on each API|---|---|---|---|| `workspace` | path | `"./data"` | OpenViking workspace || `agfs.backend` | `local`, `memory`, `s3` | `local` | File and metadata backend |+| `agfs.pathlock.provider` | `filesystem`, `memory`, `sqlite`, `cache` | `filesystem` | Path lock storage |+| `agfs.pathlock.sqlite_path` | absolute local file path | `{workspace}/_system/pathlock/pathlock.db` for `sqlite` | Shared SQLite lock database; optional override || `vectordb.backend` | `local`, `cuvs`, `http`, `volcengine`, `vikingdb` | `local` | Vector database backend || `vectordb.dimension` | integer | follows Embedding | Vector collection dimension || `parse_output.mode` | `agfs`, `local` | `agfs` | Backend for intermediate parser artifacts || `parse_output.local_root` | path or `null` | system temp directory | Root directory used by local parser artifacts || `skip_process_lock` | boolean | `false` | Skip the workspace process lock; use only when accepting concurrent-write risk |+For same-machine path locking on a local disk without recursive business-directory scans, set+`storage.agfs.pathlock` to `{"provider":"sqlite"}`. The database defaults to+`{storage.workspace}/_system/pathlock/pathlock.db`, resolved to an absolute path+from the final workspace when initializing the runtime binding. An explicit absolute+`sqlite_path` takes precedence. The database parent directory is created automatically.+Omitting `sqlite_path` or setting it to `null` also uses this default when constructing+`RAGFSBindingClient(config_path=..., config={"service_name": ...})` directly.+Every participating process must access the same actual local database file,+with the same top-level `service_name` and lock expiry setting. Containers on the+same host must share that local file; identical paths in separate container+filesystems refer to independent databases and do not coordinate locks.+SQLite stores authoritative lock tokens and atomically checks Exact/Tree conflicts+using its path index. Blocking database work runs off the async executor.+SQLite waits up to 100 ms per attempt for transient database writer contention,+including when the logical lock wait timeout is zero. The provider retries only+Busy, with three total attempts and 1 ms / 4 ms backoff. Database waits can total+about 300 ms, plus 5 ms backoff and execution/scheduling overhead. Exhausted+retries still report Busy to the manager; logical lock Conflict is not retried. WAL uses+`synchronous=FULL` to preserve committed lock tokens after a crash, at the cost of+additional synchronization I/O compared with `NORMAL`.+Lease heartbeats refresh owned paths in one SQLite transaction (bounded batches+for large leases). `stale_locks_removed` includes tokens recovered by committed+atomic SQLite/Redis acquisitions; failed transactions do not increment the count.++SQLite acquisitions completely delete expired tokens belonging to other owners+that conflict with the request: the target path, ancestor Tree locks, and all+descendants of a requested Tree lock. Cleanup and acquisition share one transaction,+so a previous owner cannot revive these tokens by refreshing them after takeover.+Opportunistic global cleanup is limited to 256 tokens per acquisition; conflicting+cleanup can exceed that limit and costs more for large expired subtrees.++Do not place the database on EFS, NFS, or SMB. SQLite WAL requires participants+on the same machine and is not supported on network filesystems; frequent lock+updates also add synchronization I/O. If `storage.workspace` is on EFS, the+default database path is on EFS too. Moving it to each container's local disk+creates independent lock authorities and cannot coordinate replicas.++For multiple containers or hosts sharing EFS, use shared Redis PathLock:+set `storage.agfs.pathlock.provider="cache"` and top-level `cache.provider="redis"`.+All replicas must use the same Redis deployment, top-level `service_name`, and+lock expiry setting. See the [shared Redis configuration example](../guides/01-configuration.md).+Shared QueueFS must also use a backend suitable for that deployment, such as+`storage.agfs.queuefs.backend="cache"`; changing PathLock alone does not change+the default SQLite queue backend.++Stop all participating processes before switching providers:+SQLite and filesystem lock files do not share a protocol. Do not delete the database,+WAL, or SHM files while participants are running. Crashed owners' tokens become+eligible for takeover after `lock_expire_secs` (default 30 seconds). This setting+does not change the workspace process lock or other backend concurrency constraints.+Remote backends also require endpoint, bucket/collection, credentials, and timeout fields. See [Configuration](../guides/01-configuration.md#storage) for complete examples.`parse_output.mode=local` avoids writing parser intermediates to shared AGFS.diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex e1d0f6847..6e07b34aa 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1445,10 +1445,21 @@ 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` |+| `provider` | str | `filesystem`, `memory`, `sqlite`, or `cache`; `cache` uses the shared Redis CacheRuntime | `filesystem` |+| `sqlite_path` | str / null | Optional absolute local shared lock database path. See [local SQLite setup](../configuration/01-server.md#storage) | `{storage.workspace}/_system/pathlock/pathlock.db` for `sqlite` || `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` |+SQLite PathLock is limited to processes sharing one actual database file on the+same machine's local disk. Do not put it on EFS/NFS/SMB or give each replica its+own container-local database. A workspace on EFS also puts the default+`sqlite_path` on EFS. See [SQLite deployment limits](../configuration/01-server.md#storage).++For multiple containers or hosts sharing EFS, use shared Redis PathLock as in+the example below. All replicas must use the same Redis deployment, top-level+`service_name`, and lock expiry setting. The example also uses Redis QueueFS+so its default SQLite database is not placed on EFS.+```json{"service_name": "production",diff --git a/docs/en/guides/14-ragfs-cache.md b/docs/en/guides/14-ragfs-cache.mdindex f71a3db47..1a8b04d2a 100644--- a/docs/en/guides/14-ragfs-cache.md+++ b/docs/en/guides/14-ragfs-cache.md@@ -165,7 +165,7 @@ The top-level `cache` section is a sibling of `storage`:| Option | Type | Default | Description ||--------|------|---------|-------------|-| `provider` | str | `"filesystem"` | `filesystem`, `memory`, or `cache` |+| `provider` | str | `"filesystem"` | `filesystem`, `memory`, `sqlite`, or `cache`; see [SQLite setup](../configuration/01-server.md#storage) || `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 5d51ac49a..348f3d66d 100644--- a/docs/zh/concepts/09-transaction.md+++ b/docs/zh/concepts/09-transaction.md@@ -448,9 +448,14 @@ Redis 配置:| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|-| `provider` | str | `filesystem`、`memory` 或 `cache` | `filesystem` |+| `provider` | str | `filesystem`、`memory`、`sqlite` 或 `cache` | `filesystem` |+| `sqlite_path` | str / null | 使用 `sqlite` 时可覆盖本地数据库绝对路径;见 [SQLite 配置](../configuration/01-server.md#storage) | 使用 `sqlite` 时为 `{storage.workspace}/_system/pathlock/pathlock.db` || `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数 | `30.0` |+跨容器或主机共享 EFS 的副本应使用 `provider="cache"`,连接共享 Redis。+SQLite 仅支持同机共享同一个本地磁盘数据库文件,不支持 EFS/NFS/SMB+或各容器独立的本地数据库。参见[部署限制与 Provider 选择](../configuration/01-server.md#storage)。+兼容旧写法:```jsondiff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.mdindex e064f4db1..c134e06aa 100644--- a/docs/zh/configuration/01-server.md+++ b/docs/zh/configuration/01-server.md@@ -295,12 +295,58 @@ Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK|---|---|---|---|| `workspace` | path | `"./data"` | OpenViking 工作目录 || `agfs.backend` | `local`、`memory`、`s3` | `local` | 文件与元数据存储后端 |+| `agfs.pathlock.provider` | `filesystem`、`memory`、`sqlite`、`cache` | `filesystem` | 路径锁存储 |+| `agfs.pathlock.sqlite_path` | 本地文件绝对路径 | 使用 `sqlite` 时为 `{workspace}/_system/pathlock/pathlock.db` | SQLite 共享锁数据库,可显式覆盖 || `vectordb.backend` | `local`、`cuvs`、`http`、`volcengine`、`vikingdb` | `local` | 向量数据库后端 || `vectordb.dimension` | integer | 跟随 Embedding | 向量集合维度 || `parse_output.mode` | `agfs`、`local` | `agfs` | parser 中间产物的存储后端 || `parse_output.local_root` | 路径或 `null` | 系统临时目录 | local parser artifact 的根目录 || `skip_process_lock` | boolean | `false` | 是否跳过 workspace 进程锁;仅在明确接受并发写风险时启用 |+同机本地磁盘上的路径锁可通过 SQLite 避免递归扫描业务目录。将 `storage.agfs.pathlock` 设置为+`{"provider":"sqlite"}`。数据库默认位于+`{storage.workspace}/_system/pathlock/pathlock.db`,初始化运行时 binding 时+根据最终 workspace 解析为绝对路径。显式指定的绝对路径 `sqlite_path` 优先,+数据库父目录会自动创建。+直接通过 `RAGFSBindingClient(config_path=..., config={"service_name": ...})` 构造时,+省略 `sqlite_path` 或将其设为 `null` 也会使用上述默认路径。+所有参与进程必须访问同一个实际的本地数据库文件,并使用相同的顶层 `service_name` 和锁过期配置。+同一主机上的容器必须共享该本地文件;不同容器文件系统中相同的路径字符串指向独立数据库,+不能互相协调路径锁。+SQLite 是锁状态的唯一存储,通过路径索引查询,并在事务中原子检查及获取 Exact/Tree 锁;+数据库阻塞操作在异步执行器之外运行。+SQLite 每次尝试对瞬时数据库写竞争最多等待 100 毫秒,即使逻辑锁等待超时为零也会执行该等待。+仅 Busy 会在 provider 内重试,最多尝试 3 次,重试前分别退避 1、4 毫秒;+数据库等待可累计约 300 毫秒,另加 5 毫秒退避及执行、调度开销。+重试耗尽仍向 manager 返回 Busy;逻辑锁 Conflict 不重试。+WAL 使用 `synchronous=FULL` 保证崩溃后已提交锁记录的持久性,+代价是比 `NORMAL` 更多的同步 I/O。+租约心跳在一次 SQLite 事务中批量刷新所属路径,大租约按有限大小分批执行。+`stale_locks_removed` 包含 SQLite/Redis 原子加锁事务实际回收的锁数量,+失败并回滚的事务不会增加计数。++SQLite 加锁会完整删除其他 owner 持有、已过期且与本次请求冲突的记录:+目标路径、祖先 Tree 锁,以及请求 Tree 锁时的全部后代锁。+清理与加锁在同一事务内完成,旧 owner 在接管后无法通过续租恢复这些记录。+全局增量清理每次加锁最多删除 256 条记录;冲突记录清理不受此上限限制,+因此过期子树较大时仍会增加事务开销。++不能将数据库放在 EFS、NFS 或 SMB 上。SQLite WAL 要求参与者位于同一主机,不支持网络文件系统;+频繁更新锁记录还会增加同步 I/O。如果 `storage.workspace` 位于 EFS,默认数据库路径也会落在 EFS。+将数据库改到各容器本地磁盘会形成独立的锁状态,无法协调多个副本。++多个容器或主机共享 EFS 时,使用共享 Redis PathLock:+设置 `storage.agfs.pathlock.provider="cache"` 和顶层 `cache.provider="redis"`。+所有副本必须连接同一个 Redis 部署,并使用相同的顶层 `service_name` 和锁过期配置。+参见[共享 Redis 配置示例](../guides/01-configuration.md)。+共享 QueueFS 也需选择适合该部署的后端,例如 `storage.agfs.queuefs.backend="cache"`;+仅修改 PathLock 不会改变默认的 SQLite 队列后端。++切换 provider 前需停止全部参与进程,+SQLite 与 filesystem 锁文件不共享协议。进程运行期间不能删除数据库及其 WAL/SHM 文件。+崩溃进程的锁在 `lock_expire_secs`(默认 30 秒)后可被接管。+此配置不会改变 workspace 进程锁或其他后端的并发限制。+远程存储后端还需要配置 endpoint、bucket/collection、鉴权和超时等字段。完整后端示例见[配置指南](../guides/01-configuration.md#storage)。`parse_output.mode=local` 可避免把 parser 中间产物写入共享 AGFS。当前 workerdiff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 926720ad5..6460ca7a1 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1429,10 +1429,20 @@ Redis 命名空间。| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|-| `provider` | str | `filesystem`、`memory` 或 `cache`;`cache` 复用 Redis CacheRuntime | `filesystem` |+| `provider` | str | `filesystem`、`memory`、`sqlite` 或 `cache`;`cache` 复用 Redis CacheRuntime | `filesystem` |+| `sqlite_path` | str / null | 可显式覆盖本地共享锁数据库的绝对路径。见 [SQLite 配置](../configuration/01-server.md#storage) | 使用 `sqlite` 时为 `{storage.workspace}/_system/pathlock/pathlock.db` || `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数;不得小于 `1.0` | `30.0` || `lock_timeout_secs` | float | 已废弃且忽略;运行时等待超时固定为 `0.0` | `0.0` |+SQLite PathLock 仅适用于同一主机上的进程共享同一个本地磁盘数据库文件。+不能将数据库放在 EFS/NFS/SMB,也不能为每个副本配置独立的容器本地数据库。+workspace 位于 EFS 时,默认 `sqlite_path` 也会落在 EFS。+详见 [SQLite 部署限制](../configuration/01-server.md#storage)。++多个容器或主机共享 EFS 时,使用下面的共享 Redis PathLock 配置。+所有副本必须连接同一个 Redis 部署,并使用相同的顶层 `service_name` 和锁过期配置。+示例同时使用 Redis QueueFS,避免默认的 SQLite 队列数据库落在 EFS。+```json{"service_name": "production",diff --git a/docs/zh/guides/14-ragfs-cache.md b/docs/zh/guides/14-ragfs-cache.mdindex da3fc4851..181a6b105 100644--- a/docs/zh/guides/14-ragfs-cache.md+++ b/docs/zh/guides/14-ragfs-cache.md@@ -157,7 +157,7 @@ Cache PathLock 和 cache-backed 多写 metadata 提供 Redis namespace。| 参数 | 类型 | 默认值 | 说明 ||------|------|--------|------|-| `provider` | str | `"filesystem"` | `filesystem`、`memory` 或 `cache` |+| `provider` | str | `"filesystem"` | `filesystem`、`memory`、`sqlite` 或 `cache`;见 [SQLite 配置](../configuration/01-server.md#storage) || `lock_expire_secs` | float | `30.0` | 锁 stale 超时;不得小于 `1.0` |Redis 配置:diff --git a/openviking/storage/viking_fs/_snapshot.py b/openviking/storage/viking_fs/_snapshot.pyindex 4f2c67817..bb6ef18f0 100644--- a/openviking/storage/viking_fs/_snapshot.py+++ b/openviking/storage/viking_fs/_snapshot.py@@ -308,14 +308,16 @@ class _SnapshotMixin:@staticmethoddef _snapshot_missing_target_lock_kind() -> Optional[str]:- """Lock kind for a missing commit target: Tree on Redis, none on filesystem."""+ """Logical-path providers can protect a missing commit target with a Tree lock."""try:from openviking_cli.utils.config.open_viking_config import get_openviking_configprovider = get_openviking_config().storage.agfs.pathlock.providerexcept Exception:provider = "filesystem"- return "tree" if provider == "cache" else None+ # TODO: query the provider's LogicalPath capability through the binding+ # instead of extending this list for each new logical-path backend.+ return "tree" if provider in {"cache", "sqlite"} else Noneasync def restore(self,diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.pyindex 396e35a63..ddcc236d2 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -49,6 +49,22 @@ class RagfsBindingConfig:cachefs = getattr(self.agfs, "cachefs", None)cachefs_backend = getattr(cachefs, "backend", "local")pathlock = self.agfs.pathlock.model_dump(mode="json", exclude_none=True)+ if pathlock.get("provider") == "sqlite":+ sqlite_path = pathlock.get("sqlite_path")+ if sqlite_path is None:+ workspace = getattr(self.agfs, "path", None)+ if not workspace:+ raise ValueError(+ "agfs_config.path is required for the default SQLite lock database"+ )+ # Resolve at binding time so later workspace overrides are respected.+ database = (+ Path(workspace).expanduser().resolve() / "_system" / "pathlock" / "pathlock.db"+ )+ else:+ database = Path(sqlite_path).resolve()+ database.parent.mkdir(parents=True, exist_ok=True)+ pathlock["sqlite_path"] = str(database)pathlock_uses_cache = pathlock.get("provider") == "cache"backups = getattr(self.agfs, "backups", None)uses_runtime = (diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.pyindex d4698a0db..2b93632f9 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -3,6 +3,7 @@from __future__ import annotationsimport math+import osfrom enum import Enumfrom typing import Any, List, Literal, Optionalfrom urllib.parse import urlparse@@ -298,7 +299,12 @@ class AGFSPathLockConfig(BaseModel):provider: str = Field(default="filesystem",- description="PathLock provider: 'filesystem' | 'memory' | 'cache'",+ description="PathLock provider: 'filesystem' | 'memory' | 'sqlite' | 'cache'",+ )+ sqlite_path: Optional[str] = Field(+ default=None,+ description="Absolute local SQLite lock database file shared by all participating processes. "+ "Defaults to '{storage.workspace}/_system/pathlock/pathlock.db' when not set.",)lock_timeout_secs: float = Field(default=0.0,@@ -312,8 +318,16 @@ class AGFSPathLockConfig(BaseModel):@model_validator(mode="after")def validate_config(self):"""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 not in {"filesystem", "memory", "sqlite", "cache"}:+ raise ValueError(+ "pathlock provider must be one of: 'filesystem', 'memory', 'sqlite', 'cache'"+ )+ if (+ self.provider == "sqlite"+ and self.sqlite_path is not None+ and not os.path.isabs(self.sqlite_path)+ ):+ raise ValueError("pathlock sqlite_path must be an absolute local file path")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/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex 409e2442e..e4c68af02 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -19,6 +19,7 @@ from openviking_cli.utils.config.cache_config import CacheConfigfrom openviking_cli.utils.config.consts import OPENVIKING_CONFIG_ENVfrom openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfigfrom openviking_cli.utils.config.open_viking_config import OpenVikingConfig+from openviking_cli.utils.config.storage_config import StorageConfigfrom openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig, VolcengineConfigfrom openviking_cli.utils.config.vlm_config import VLMConfig@@ -866,6 +867,74 @@ def test_redis_pathlock_enables_shared_runtime_without_cachefs(tmp_path):assert binding["service_name"] == "prod-a"+def test_sqlite_pathlock_binding_without_redis(tmp_path):+ database = str(tmp_path / "custom" / "locks.sqlite3")+ config = AGFSConfig(+ path=str(tmp_path), pathlock={"provider": "sqlite", "sqlite_path": database}+ )+ binding = RagfsBindingConfig(agfs=config, service_name="local-a").to_binding_dict()+ assert binding["pathlock"]["sqlite_path"] == database+ assert binding["pathlock"]["provider"] == "sqlite"+ assert binding["cache"]["runtime_enabled"] is False+ assert Path(database).parent.is_dir()+ for path in ["", "relative.sqlite3", ":memory:"]:+ with pytest.raises(ValueError, match="sqlite_path"):+ AGFSConfig(path=str(tmp_path), pathlock={"provider": "sqlite", "sqlite_path": path})++[email protected]("sqlite_path", [{}, {"sqlite_path": None}])+def test_sqlite_pathlock_default_uses_final_workspace(tmp_path, monkeypatch, sqlite_path):+ initial = tmp_path / "initial"+ storage = StorageConfig(+ workspace=str(initial),+ agfs={"pathlock": {"provider": "sqlite", **sqlite_path}},+ )+ assert storage.agfs.pathlock.sqlite_path is None+ assert not (initial / "_system" / "pathlock").exists()++ # Runtime workspace overrides happen after model validation.+ final = tmp_path / "final"+ storage.workspace = str(final)+ storage.agfs.path = str(final)+ binding_config = RagfsBindingConfig(agfs=storage.agfs, service_name="local-a")+ expected = final / "_system" / "pathlock" / "pathlock.db"+ first = binding_config.to_binding_dict()+ assert first["pathlock"]["sqlite_path"] == str(expected)+ assert expected.parent.is_dir()+ assert not (initial / "_system" / "pathlock").exists()+ assert storage.agfs.pathlock.sqlite_path is None+ assert first["cache"]["runtime_enabled"] is False++ # Another process with a different cwd resolves the same absolute workspace.+ monkeypatch.chdir(initial)+ second = RagfsBindingConfig(agfs=storage.agfs, service_name="local-a").to_binding_dict()+ assert second["pathlock"]["sqlite_path"] == first["pathlock"]["sqlite_path"]+++def test_sqlite_pathlock_explicit_path_survives_workspace_override(tmp_path):+ database = tmp_path / "custom" / "locks.db"+ config = AGFSConfig(+ path=str(tmp_path / "initial"),+ pathlock={"provider": "sqlite", "sqlite_path": str(database)},+ )+ config.path = str(tmp_path / "final")+ binding = RagfsBindingConfig(agfs=config).to_binding_dict()+ assert binding["pathlock"]["sqlite_path"] == str(database)+ assert database.parent.is_dir()+ assert not (tmp_path / "final" / "_system" / "pathlock").exists()+++def test_sqlite_pathlock_default_requires_workspace_and_leaves_other_providers_alone(tmp_path):+ config = AGFSConfig(pathlock={"provider": "sqlite"})+ with pytest.raises(ValueError, match="agfs_config.path"):+ RagfsBindingConfig(agfs=config).to_binding_dict()+ workspace = tmp_path / "unused"+ config = AGFSConfig(path=str(workspace))+ binding = RagfsBindingConfig(agfs=config).to_binding_dict()+ assert "sqlite_path" not in binding["pathlock"]+ assert not workspace.exists()++def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):agfs_config = AGFSConfig(path=str(tmp_path),diff --git a/tests/unit/test_snapshot_rebuild_context.py b/tests/unit/test_snapshot_rebuild_context.pyindex cf57e5d72..33f4deb25 100644--- a/tests/unit/test_snapshot_rebuild_context.py+++ b/tests/unit/test_snapshot_rebuild_context.py@@ -12,6 +12,19 @@ from openviking.storage.viking_fs import VikingFSfrom openviking_cli.session.user_id import UserIdentifier+ ("provider", "expected"),+ [("sqlite", "tree"), ("cache", "tree"), ("filesystem", None), ("memory", None)],+)+def test_missing_snapshot_target_uses_logical_provider_tree_lock(monkeypatch, provider, expected):+ config = Mock()+ config.storage.agfs.pathlock.provider = provider+ monkeypatch.setattr(+ "openviking_cli.utils.config.open_viking_config.get_openviking_config", lambda: config+ )+ assert VikingFS._snapshot_missing_target_lock_kind() == expected++@pytest.mark.asyncioasync def test_fallback_rebuild_detaches_all_operations(monkeypatch):ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.ROOT)