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
refactor(pathlock):using rust implement instead python (#3602)
baojun-zhang2f9451231e8b
diff --git a/Cargo.lock b/Cargo.lockindex 8be5cb555..5f45a69ec 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1849,6 +1849,16 @@ dependencies = ["subtle",]+[[package]]+name = "filelocks"+version = "0.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "54c1e4f9fd884a066beb8cc4677dea1188d2f2eaf70518f3a37e46551cfe3431"+dependencies = [+ "libc",+ "windows-sys 0.61.2",+]+[[package]]name = "find-msvc-tools"version = "0.1.9"@@ -3880,6 +3890,7 @@ dependencies = ["chrono","criterion","dashmap",+ "filelocks","flate2","futures","gix-actor",@@ -3903,6 +3914,7 @@ dependencies = ["rusqlite","serde","serde_json",+ "sha1","sha2","sqlx","tempfile",diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex d10db441c..042fec626 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -8,10 +8,61 @@ use pyo3::exceptions::{PyRuntimeError, PyValueError};use pyo3::prelude::*;use pyo3::types::{PyBytes, PyDict, PyList, PyType};use std::collections::HashMap;+use std::sync::OnceLock;++/// Cached reference to the Python `openviking.storage.errors.LockAcquisitionError` class,+/// imported at module init so that native and Python code share the same exception type.+static LOCK_ACQUISITION_ERROR_TYPE: OnceLock<Py<PyType>> = OnceLock::new();++/// Map a PathLockError to the appropriate Python exception.+fn pathlock_err_to_py(err: PathLockError) -> PyErr {+ match &err {+ PathLockError::Conflict { .. }+ | PathLockError::Timeout { .. }+ | PathLockError::HandoffFailed(_) => {+ #[allow(deprecated)]+ Python::with_gil(|py| {+ let ty = LOCK_ACQUISITION_ERROR_TYPE+ .get()+ .expect("LockAcquisitionError not initialized");+ PyErr::from_type(ty.bind(py).clone(), err.to_string())+ })+ }+ PathLockError::InvalidRequest(_) => PyValueError::new_err(err.to_string()),+ _ => PyRuntimeError::new_err(err.to_string()),+ }+}use std::fs;use std::future::Future;use std::sync::Arc;-use std::time::UNIX_EPOCH;+use std::time::{Duration, UNIX_EPOCH};++/// Validate and convert a wait timeout from Python.+///+/// Must be finite and non-negative. Returns `Duration::from_secs_f64(v)`.+/// NaN, negative, or infinite → `ValueError`.+fn validate_timeout_secs(v: f64) -> PyResult<Duration> {+ if v.is_finite() && v >= 0.0 {+ Ok(Duration::from_secs_f64(v))+ } else {+ Err(PyValueError::new_err(+ "timeout_secs must be a finite non-negative number",+ ))+ }+}++/// Validate and convert a lock expire duration from Python config.+///+/// Must be finite, positive, and at least 1.0 second.+fn validate_expire_secs(v: f64) -> PyResult<f64> {+ if v.is_finite() && v >= 1.0 {+ Ok(v)+ } else {+ Err(PyValueError::new_err(+ "lock_expire_secs must be a finite number >= 1.0",+ ))+ }+}use ragfs::cache::{CacheError, CacheNamespace, CachePolicy, CacheProvider, CacheResult, CacheTraversalMode,@@ -19,10 +70,48 @@ use ragfs::cache::{};use ragfs::core::builder::EncryptionConfig;use ragfs::core::{- build_default_stack, register_builtin_plugins, ConfigValue, FileInfo, FileSystem,+ build_default_stack, build_stack_with_mountable, ConfigValue, FileInfo, FileSystem,FilesystemStats, FsContext, FsContextInner, FsOperation, GlobPage, GrepResult, MountableFS,- OperationStats, PluginConfig, RagfsConfig, StatsWrappedFS, TreeEntry, WriteFlag, FS_CTX,+ OperationStats, PathLockContext, PluginConfig, RagfsConfig, TreeEntry, WriteFlag, FS_CTX,};+use ragfs::lock::{+ BorrowedPathLockLease, OwnedPathLockLease, PathLockConfig, PathLockHandoffRef, PathLockKind,+ PathLockManager, PathLockRequest,+};+use ragfs::lock::types::PathLockError;++/// Parse one Python pathlock request without silently defaulting invalid fields.+fn parse_pathlock_request(raw: &HashMap<String, String>) -> PyResult<PathLockRequest> {+ let path = raw+ .get("path")+ .filter(|path| !path.is_empty() && path.starts_with('/'))+ .ok_or_else(|| PyValueError::new_err("pathlock request.path must be an absolute path"))?;+ let kind = match raw.get("kind").map(String::as_str) {+ Some("exact") => PathLockKind::Exact,+ Some("tree") => PathLockKind::Tree,+ _ => {+ return Err(PyValueError::new_err(+ "pathlock request.kind must be 'exact' or 'tree'",+ ));+ }+ };+ Ok(PathLockRequest {+ path: path.clone(),+ kind,+ })+}++/// Parse a non-empty Python pathlock request batch.+fn parse_pathlock_request_batch(+ requests: &[HashMap<String, String>],+) -> PyResult<Vec<PathLockRequest>> {+ if requests.is_empty() {+ return Err(PyValueError::new_err(+ "pathlock request batch must not be empty",+ ));+ }+ requests.iter().map(parse_pathlock_request).collect()+}#[derive(Debug, Clone, PartialEq, Eq)]enum CacheProviderKind {@@ -800,11 +889,135 @@ fn py_to_json_value(v: &Bound<'_, PyAny>) -> PyResult<serde_json::Value> {/// "every ragfs call carries a ctx" invariant holds. Missing `account_id` is represented as an/// empty field; `FsContextView::account_id()` treats it as absent, so encrypted content operations/// fail fast instead of using an accidental empty tenant key.+///+/// When the dict contains `"disable_auto_pathlock": "true"`, the `PathLockWrappedFS` auto-lock+/// layer is suppressed so callers that already hold a pathlock lease can safely delegate to the+/// inner filesystem without double-locking.fn build_fs_context(ctx: Option<HashMap<String, String>>) -> FsContext {- let account_id = ctx- .and_then(|m| m.get("account_id").cloned())- .unwrap_or_default();- Arc::new(FsContextInner::new(account_id))+ let mut account_id = String::new();+ let mut disable_auto_pathlock = false;+ let mut lease_ref: Option<String> = None;+ if let Some(m) = &ctx {+ account_id = m.get("account_id").cloned().unwrap_or_default();+ disable_auto_pathlock = m.get("disable_auto_pathlock").map(|s| s == "true").unwrap_or(false);+ lease_ref = m.get("lease_ref").cloned();+ }+ let pathlock = if disable_auto_pathlock || lease_ref.is_some() {+ Some(PathLockContext {+ lease_ref,+ disable_auto_pathlock,+ })+ } else {+ None+ };+ Arc::new(FsContextInner::with_pathlock(account_id, pathlock.unwrap_or_default()))+}++/// Convert an OwnedPathLockLease to a Python dict.+fn owned_lease_to_py_dict(py: Python<'_>, lease: &OwnedPathLockLease) -> PyResult<Py<PyAny>> {+ let dict = PyDict::new(py);+ dict.set_item("lease_ref", &lease.lease.lease_ref)?;+ dict.set_item("owner_id", &lease.lease.owner_id)?;+ dict.set_item("lock_paths", &lease.lease.lock_paths)?;+ dict.set_item("ownership_ref", &lease.ownership_ref)?;+ dict.set_item("owned", true)?;+ Ok(dict.into())+}++/// Convert a BorrowedPathLockLease to a Python dict.+fn borrowed_lease_to_py_dict(py: Python<'_>, lease: &BorrowedPathLockLease) -> PyResult<Py<PyAny>> {+ let dict = PyDict::new(py);+ dict.set_item("lease_ref", &lease.lease.lease_ref)?;+ dict.set_item("owner_id", &lease.lease.owner_id)?;+ dict.set_item("lock_paths", &lease.lease.lock_paths)?;+ dict.set_item("owned", false)?;+ Ok(dict.into())+}++/// Require an owned marker and return its opaque lease and lifecycle capability refs.+fn require_owned_lease_ref(+ py: Python<'_>,+ ref_dict: &HashMap<String, Py<PyAny>>,+) -> PyResult<(String, String)> {+ let owned: bool = ref_dict+ .get("owned")+ .map(|v| v.extract(py))+ .transpose()?+ .unwrap_or(false);+ if !owned {+ return Err(PyValueError::new_err(+ "lease ref is not owned; release/refresh/handoff require an owned lease",+ ));+ }+ let lease_ref: String = ref_dict+ .get("lease_ref")+ .ok_or_else(|| PyValueError::new_err("owned_lease_ref.lease_ref required"))?+ .extract(py)?;+ let ownership_ref: String = ref_dict+ .get("ownership_ref")+ .ok_or_else(|| PyValueError::new_err("owned_lease_ref.ownership_ref required"))?+ .extract(py)?;+ if lease_ref.is_empty() || ownership_ref.is_empty() {+ return Err(PyValueError::new_err(+ "owned lease and ownership refs must not be empty",+ ));+ }+ Ok((lease_ref, ownership_ref))+}++/// Extract an opaque PathLock lease ref without granting lifecycle permissions.+fn extract_lease_ref(py: Python<'_>, lease_ref: &Py<PyAny>) -> PyResult<String> {+ if let Ok(raw) = lease_ref.extract::<String>(py) {+ if !raw.is_empty() {+ return Ok(raw);+ }+ }+ let ref_dict: HashMap<String, Py<PyAny>> = lease_ref.extract(py)?;+ ref_dict+ .get("lease_ref")+ .ok_or_else(|| PyValueError::new_err("lease_ref.lease_ref required"))?+ .extract(py)+}++/// Extract an owned PathLock lease and lifecycle capability from a typed dictionary.+fn extract_owned_lease_ref(+ py: Python<'_>,+ lease_ref: &Py<PyAny>,+) -> PyResult<(String, String)> {+ let ref_dict: HashMap<String, Py<PyAny>> = lease_ref.extract(py)?;+ require_owned_lease_ref(py, &ref_dict)+}++/// Extract an optional owned lease capability used for reentrant acquisition.+fn extract_optional_owned_lease_ref(+ py: Python<'_>,+ lease_ref: Option<&Py<PyAny>>,+) -> PyResult<Option<(String, String)>> {+ lease_ref+ .map(|value| extract_owned_lease_ref(py, value))+ .transpose()+}++/// Convert a PathLockHandoffRef to a Python dict.+fn handoff_ref_to_py_dict(py: Python<'_>, handoff: &PathLockHandoffRef) -> PyResult<Py<PyAny>> {+ let dict = PyDict::new(py);+ dict.set_item("owner_id", &handoff.owner_id)?;+ dict.set_item("lock_paths", &handoff.lock_paths)?;+ let covered = PyList::empty(py);+ for req in &handoff.covered_paths {+ let item = PyDict::new(py);+ item.set_item("path", &req.path)?;+ item.set_item(+ "kind",+ match req.kind {+ PathLockKind::Exact => "exact",+ PathLockKind::Tree => "tree",+ },+ )?;+ covered.append(item)?;+ }+ dict.set_item("covered_paths", covered)?;+ Ok(dict.into())}#[derive(serde::Deserialize)]@@ -854,6 +1067,8 @@ struct RAGFSBindingClient {rt: tokio::runtime::Runtime,git_service: Option<Arc<ragfs::git::GitService>>,git_backend: Option<String>,+ /// PathLock manager. OpenViking always builds ragfs with PathLock enabled.+ pathlock_manager: Arc<PathLockManager>,}impl RAGFSBindingClient {@@ -872,6 +1087,11 @@ impl RAGFSBindingClient {.block_on(FS_CTX.scope(ctx, async move { f().await }))})}++ /// Clone the PathLock manager shared by this binding client.+ fn clone_pathlock_manager(&self) -> Arc<PathLockManager> {+ self.pathlock_manager.clone()+ }}#[pymethods]@@ -931,6 +1151,28 @@ impl RAGFSBindingClient {.map_err(|e| PyRuntimeError::new_err(format!("Invalid git config: {e}")))?;inline_git_cfg = Some(git_cfg);}+ if let Some(pl_obj) = cfg.get("pathlock") {+ let pl_value = py_to_json_value(pl_obj.bind(py))?;+ let provider = pl_value+ .get("provider")+ .and_then(|v| v.as_str())+ .unwrap_or("filesystem");+ if !matches!(provider, "filesystem" | "memory") {+ return Err(PyValueError::new_err(+ "pathlock.provider must be 'filesystem' or 'memory'",+ ));+ }+ let lock_expire_secs = validate_expire_secs(+ pl_value+ .get("lock_expire_secs")+ .and_then(|v| v.as_f64())+ .unwrap_or(300.0),+ )?;+ ragfs_cfg.pathlock = PathLockConfig {+ provider: provider.to_string(),+ lock_expire_secs,+ };+ }}let cache_config = match runtime_cache_config {@@ -957,18 +1199,7 @@ impl RAGFSBindingClient {CacheNamespace::new(&cache_config.namespace),cache_policy_from_config(&cache_config),));- rt.block_on(async {- register_builtin_plugins(&mountable).await;- if let Some(enc) = &ragfs_cfg.encryption {- mountable- .set_encryption_config(Some(enc.root_key), Some(enc.provider_type))- .await;- }- });- let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(- mountable.clone() as Arc<dyn FileSystem>- ));- ragfs::core::RagfsStack { mountable, top }+ rt.block_on(build_stack_with_mountable(ragfs_cfg, mountable))} else {rt.block_on(build_default_stack(ragfs_cfg))};@@ -989,6 +1220,7 @@ impl RAGFSBindingClient {rt,git_service,git_backend,+ pathlock_manager: stack.pathlock_manager,})}@@ -1783,6 +2015,491 @@ impl RAGFSBindingClient {))}+ // ── PathLock API ──++ /// Acquire an exact lock on a single path.+ #[pyo3(signature = (ctx, path, timeout_secs=0.0, owner_lease_ref=None))]+ fn pathlock_acquire_exact(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ path: String,+ timeout_secs: f64,+ owner_lease_ref: Option<Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let timeout = validate_timeout_secs(timeout_secs)?;+ let owner_capability =+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let path = path.clone();+ let capability = owner_capability.clone();+ async move {+ let capability = capability+ .as_ref()+ .map(|(lease_ref, ownership_ref)| {+ (lease_ref.as_str(), ownership_ref.as_str())+ });+ mgr.acquire_exact(&path, timeout, capability).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Acquire exact locks on multiple paths.+ #[pyo3(signature = (ctx, paths, timeout_secs=0.0, owner_lease_ref=None))]+ fn pathlock_acquire_exact_batch(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ paths: Vec<String>,+ timeout_secs: f64,+ owner_lease_ref: Option<Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let timeout = validate_timeout_secs(timeout_secs)?;+ let owner_capability =+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let paths = paths.clone();+ let capability = owner_capability.clone();+ async move {+ let capability = capability+ .as_ref()+ .map(|(lease_ref, ownership_ref)| {+ (lease_ref.as_str(), ownership_ref.as_str())+ });+ mgr.acquire_exact_batch(&paths, timeout, capability).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Acquire a tree lock on a single path.+ #[pyo3(signature = (ctx, path, timeout_secs=0.0, owner_lease_ref=None))]+ fn pathlock_acquire_tree(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ path: String,+ timeout_secs: f64,+ owner_lease_ref: Option<Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let timeout = validate_timeout_secs(timeout_secs)?;+ let owner_capability =+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let path = path.clone();+ let capability = owner_capability.clone();+ async move {+ let capability = capability+ .as_ref()+ .map(|(lease_ref, ownership_ref)| {+ (lease_ref.as_str(), ownership_ref.as_str())+ });+ mgr.acquire_tree(&path, timeout, capability).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Acquire tree locks on multiple paths.+ #[pyo3(signature = (ctx, paths, timeout_secs=0.0, owner_lease_ref=None))]+ fn pathlock_acquire_tree_batch(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ paths: Vec<String>,+ timeout_secs: f64,+ owner_lease_ref: Option<Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let timeout = validate_timeout_secs(timeout_secs)?;+ let owner_capability =+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let paths = paths.clone();+ let capability = owner_capability.clone();+ async move {+ let capability = capability+ .as_ref()+ .map(|(lease_ref, ownership_ref)| {+ (lease_ref.as_str(), ownership_ref.as_str())+ });+ mgr.acquire_tree_batch(&paths, timeout, capability).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Acquire a mixed batch of exact and tree locks.+ #[pyo3(signature = (ctx, exact_paths, tree_paths, timeout_secs=0.0, owner_lease_ref=None))]+ fn pathlock_acquire_exact_tree_batch(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ exact_paths: Vec<String>,+ tree_paths: Vec<String>,+ timeout_secs: f64,+ owner_lease_ref: Option<Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let timeout = validate_timeout_secs(timeout_secs)?;+ let owner_capability =+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let exact = exact_paths.clone();+ let tree = tree_paths.clone();+ let capability = owner_capability.clone();+ async move {+ let capability = capability+ .as_ref()+ .map(|(lease_ref, ownership_ref)| {+ (lease_ref.as_str(), ownership_ref.as_str())+ });+ mgr.acquire_exact_tree_batch(&exact, &tree, timeout, capability)+ .await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Acquire a batch of locks from a list of request dicts.+ /// Each request dict: {"path": str, "kind": "exact"|"tree"}+ #[pyo3(signature = (ctx, requests, timeout_secs=0.0, owner_lease_ref=None))]+ fn pathlock_acquire_batch(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ requests: Vec<HashMap<String, String>>,+ timeout_secs: f64,+ owner_lease_ref: Option<Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let timeout = validate_timeout_secs(timeout_secs)?;+ let owner_capability =+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;++ let lock_requests = parse_pathlock_request_batch(&requests)?;++ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let reqs = lock_requests.clone();+ let capability = owner_capability.clone();+ async move {+ let capability = capability+ .as_ref()+ .map(|(lease_ref, ownership_ref)| {+ (lease_ref.as_str(), ownership_ref.as_str())+ });+ mgr.acquire_batch(&reqs, timeout, capability).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Create a borrowed view of an owned lease.+ #[pyo3(signature = (ctx, owned_lease_ref))]+ fn pathlock_as_borrowed(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ owned_lease_ref: Py<PyAny>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let mgr2 = mgr.clone();+ let fs_ctx = build_fs_context(ctx);+ let lease_ref = extract_lease_ref(py, &owned_lease_ref)?;+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr2.clone();+ let lr = lease_ref.clone();+ async move {+ mgr.get_owned_lease_by_ref(&lr).await.ok_or_else(|| {+ PathLockError::Internal(format!("lease not found for ref '{lr}'"))+ })+ }+ })+ .map_err(|e: PathLockError| PyRuntimeError::new_err(e.to_string()))?;+ let borrowed = mgr.as_borrowed(&lease);+ Python::attach(|py| borrowed_lease_to_py_dict(py, &borrowed))+ }++ /// Refresh an owned lease. Returns "refreshed", "lost", or "failed".+ #[pyo3(signature = (ctx, owned_lease_ref))]+ fn pathlock_refresh(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ owned_lease_ref: Py<PyAny>,+ ) -> PyResult<String> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;+ let status = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let lr = lease_ref.clone();+ let ownership = ownership_ref.clone();+ async move {+ let lease = mgr+ .get_owned_lease_by_capability(&lr, &ownership)+ .await+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "owned lease capability does not match ref '{lr}'"+ ))+ })?;+ mgr.refresh(&lease).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Ok(status)+ }++ /// Release an owned lease.+ #[pyo3(signature = (ctx, owned_lease_ref))]+ fn pathlock_release(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ owned_lease_ref: Py<PyAny>,+ ) -> PyResult<()> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;+ self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let lr = lease_ref.clone();+ let ownership = ownership_ref.clone();+ async move {+ let lease = mgr+ .get_owned_lease_by_capability(&lr, &ownership)+ .await+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "owned lease capability does not match ref '{lr}'"+ ))+ })?;+ mgr.release(&lease).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Ok(())+ }++ /// Release selected lock paths from an owned lease.+ #[pyo3(signature = (ctx, owned_lease_ref, lock_paths))]+ fn pathlock_release_selected(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ owned_lease_ref: Py<PyAny>,+ lock_paths: Vec<String>,+ ) -> PyResult<()> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;+ self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let lr = lease_ref.clone();+ let ownership = ownership_ref.clone();+ let paths = lock_paths.clone();+ async move {+ let lease = mgr+ .get_owned_lease_by_capability(&lr, &ownership)+ .await+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "owned lease capability does not match ref '{lr}'"+ ))+ })?;+ mgr.release_selected(&lease, &paths).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Ok(())+ }++ /// Export a handoff ref from an owned lease.+ #[pyo3(signature = (ctx, owned_lease_ref))]+ fn pathlock_to_handoff(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ owned_lease_ref: Py<PyAny>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;+ let handoff = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let lr = lease_ref.clone();+ let ownership = ownership_ref.clone();+ async move {+ let lease = mgr+ .get_owned_lease_by_capability(&lr, &ownership)+ .await+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "owned lease capability does not match ref '{lr}'"+ ))+ })?;+ Ok(mgr.to_handoff(&lease))+ }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| handoff_ref_to_py_dict(py, &handoff))+ }++ /// Mark an owned lease as handed off.+ #[pyo3(signature = (ctx, owned_lease_ref))]+ fn pathlock_handoff(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ owned_lease_ref: Py<PyAny>,+ ) -> PyResult<()> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;+ self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let lr = lease_ref.clone();+ let ownership = ownership_ref.clone();+ async move {+ let lease = mgr+ .get_owned_lease_by_capability(&lr, &ownership)+ .await+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "owned lease capability does not match ref '{lr}'"+ ))+ })?;+ mgr.handoff(&lease).await+ }+ })+ .map_err(pathlock_err_to_py)?;+ Ok(())+ }++ /// Adopt a handoff ref, returning a new owned lease.+ #[pyo3(signature = (ctx, handoff_ref))]+ fn pathlock_adopt(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ handoff_ref: HashMap<String, Py<PyAny>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let owner_id: String = handoff_ref+ .get("owner_id")+ .or_else(|| handoff_ref.get("handle_id"))+ .ok_or_else(|| {+ PyValueError::new_err("handoff_ref.owner_id or handoff_ref.handle_id required")+ })?+ .extract(py)?;+ let lock_paths: Vec<String> = handoff_ref+ .get("lock_paths")+ .ok_or_else(|| PyValueError::new_err("handoff_ref.lock_paths required"))?+ .extract(py)?;+ if owner_id.is_empty()+ || lock_paths.is_empty()+ || lock_paths.iter().any(|path| !path.starts_with('/'))+ {+ return Err(PyValueError::new_err(+ "handoff_ref owner_id/handle_id and absolute lock_paths are required",+ ));+ }+ let covered_paths: Vec<PathLockRequest> = handoff_ref+ .get("covered_paths")+ .map(|v| {+ let raw: Vec<HashMap<String, String>> = v.extract(py)?;+ raw.iter().map(parse_pathlock_request).collect()+ })+ .transpose()?+ .unwrap_or_default();+ let handoff = PathLockHandoffRef {+ owner_id,+ lock_paths,+ covered_paths,+ };+ let lease = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let h = handoff.clone();+ async move { mgr.adopt(&h).await }+ })+ .map_err(pathlock_err_to_py)?;+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))+ }++ /// Check if a path is locked.+ #[pyo3(signature = (ctx, path, ignore_stale=true))]+ fn pathlock_is_locked(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ path: String,+ ignore_stale: bool,+ ) -> PyResult<bool> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ let p = path.clone();+ async move { mgr.is_locked(&p, ignore_stale).await }+ })+ .map_err(|e| PyRuntimeError::new_err(e.to_string()))+ }++ /// Return an observability snapshot of current lock state.+ #[pyo3(signature = (ctx=None))]+ fn pathlock_observe(+ &self,+ py: Python<'_>,+ ctx: Option<HashMap<String, String>>,+ ) -> PyResult<Py<PyAny>> {+ let mgr = self.clone_pathlock_manager();+ let fs_ctx = build_fs_context(ctx);+ let snapshot = self.run_scoped(py, fs_ctx, move || {+ let mgr = mgr.clone();+ async move { mgr.observe().await }+ });+ Python::attach(|py| {+ let dict = PyDict::new(py);+ dict.set_item("active_locks", snapshot.active_locks)?;+ dict.set_item("waiting_locks", snapshot.waiting_locks)?;+ dict.set_item("stale_locks_removed", snapshot.stale_locks_removed)?;+ let conflicts = PyList::empty(py);+ for c in &snapshot.conflicts {+ let cd = PyDict::new(py);+ cd.set_item("lock_path", &c.lock_path)?;+ cd.set_item("conflicting_owner", &c.conflicting_owner)?;+ cd.set_item("conflicting_kind", format!("{:?}", c.conflicting_kind))?;+ conflicts.append(cd)?;+ }+ dict.set_item("conflicts", conflicts)?;+ Ok(dict.into())+ })+ }+/// Get filesystem statistics.////// Args:@@ -1851,6 +2568,16 @@ impl RAGFSBindingClient {#[pymodule]fn ragfs_python(m: &Bound<'_, PyModule>) -> PyResult<()> {m.add_class::<RAGFSBindingClient>()?;++ // Import the Python business exception so native code raises the same type+ // that `openviking.storage.errors` defines, enabling `except LockAcquisitionError`.+ let py = m.py();+ let errors_mod = py.import("openviking.storage.errors")?;+ let exc_type: Py<PyType> = errors_mod.getattr("LockAcquisitionError")?.extract()?;+ LOCK_ACQUISITION_ERROR_TYPE+ .set(exc_type)+ .map_err(|_| PyRuntimeError::new_err("LockAcquisitionError already initialized"))?;+Ok(())}diff --git a/crates/ragfs/Cargo.toml b/crates/ragfs/Cargo.tomlindex d23af4e6c..3dad1781c 100644--- a/crates/ragfs/Cargo.toml+++ b/crates/ragfs/Cargo.toml@@ -48,6 +48,7 @@ flate2 = "1.0"# Path handling and filesystempath-clean = "1.0"+filelocks = "0.1.0"# Data structuresradix_trie = "0.2"@@ -86,6 +87,7 @@ globset = "0.4"aes-gcm = "0.10"hkdf = "0.12"sha2 = "0.10"+sha1 = "0.10"rand = "0.8"# Stream combinators for concurrent I/Odiff --git a/crates/ragfs/src/cache/policy.rs b/crates/ragfs/src/cache/policy.rsindex bbe21a5e7..a0131865c 100644--- a/crates/ragfs/src/cache/policy.rs+++ b/crates/ragfs/src/cache/policy.rs@@ -1,5 +1,7 @@//! Provider-independent cache eligibility rules.+use crate::core::internal_names::is_hidden_runtime_lock_name;+const DEFAULT_MAX_CACHED_DIR_ENTRIES: usize = 4096;/// Cache admission decision for a filesystem object.@@ -135,7 +137,7 @@ impl CachePolicy {}let name = normalized.rsplit('/').next().unwrap_or("");- if name == ".path.ovlock"+ if is_hidden_runtime_lock_name(name)|| name.ends_with(".lock")|| name.ends_with(".lck")|| matches!(@@ -179,3 +181,20 @@ fn is_same_or_descendant(path: &str, prefix: &str) -> bool {.strip_prefix(prefix).is_some_and(|suffix| suffix.starts_with('/'))}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn runtime_lock_files_bypass_cache() {+ let policy = CachePolicy::default();++ for path in [+ "/data/.path.ovlock",+ "/data/.exact.ovlock.file.txt.0123456789abcdef",+ ] {+ assert_eq!(policy.file_decision(path, 32), CacheDecision::Bypass);+ }+ }+}diff --git a/crates/ragfs/src/cache/wrapper.rs b/crates/ragfs/src/cache/wrapper.rsindex d36151b46..2df524d6a 100644--- a/crates/ragfs/src/cache/wrapper.rs+++ b/crates/ragfs/src/cache/wrapper.rs@@ -1063,7 +1063,7 @@ impl FileSystem for CachedFileSystem {let key = self.file_key(&normalized);self.cache_delete(&key, &normalized).await;if offset == 0- && matches!(flags, WriteFlag::Create | WriteFlag::Truncate)+ && matches!(flags, WriteFlag::Create | WriteFlag::CreateNew | WriteFlag::Truncate)&& self.policy.cache_file(&normalized, data.len())&& !self.is_runtime_bypassed(&normalized).await{diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsindex 1cf6f4c5e..da89b1cdc 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -6,6 +6,7 @@//! `EncryptionWrappedFS` wrapper is removed from this builder.//!//! The top layer is always `StatsWrappedFS` so end-to-end timing (including crypto) is captured.+//! When pathlock is enabled, `PathLockWrappedFS` sits between `StatsWrappedFS` and `MountableFS`.use std::sync::Arc;@@ -13,6 +14,11 @@ use super::filesystem::FileSystem;use super::mountable::MountableFS;use super::stats_wrapper::StatsWrappedFS;+use crate::lock::{+ FilesystemPathLockProvider, MemoryPathLockProvider, PathLockConfig, PathLockManager,+ PathLockProvider, PathLockWrappedFS,+};+#[cfg(feature = "s3")]use crate::plugins::S3FSPlugin;use crate::plugins::{@@ -23,10 +29,20 @@ use crate::plugins::{////// New capabilities are added as new optional sections here, without changing/// `build_default_stack`'s signature.-#[derive(Default)]pub struct RagfsConfig {/// Encryption section: `None` → plaintext stack; `Some` → per-backend encryption wrapping.pub encryption: Option<EncryptionConfig>,+ /// PathLock configuration. OpenViking always requires PathLock to be present.+ pub pathlock: PathLockConfig,+}++impl Default for RagfsConfig {+ fn default() -> Self {+ Self {+ encryption: None,+ pathlock: PathLockConfig::default(),+ }+ }}/// Encryption section: root key fixed and immutable at construction time.@@ -41,16 +57,30 @@ pub struct EncryptionConfig {pub struct RagfsStack {/// Mount manager (mount/unmount/list/stats/register_plugin live here).pub mountable: Arc<MountableFS>,- /// Data entry point: `Stats(Mountable)` — encryption is per-backend inside mount.+ /// Data entry point: `Stats(PathLock(Mountable))`.pub top: Arc<dyn FileSystem>,+ /// PathLock manager. OpenViking always constructs the stack with PathLock enabled.+ pub pathlock_manager: Arc<PathLockManager>,}/// Build the standard RAGFS stack.////// Encryption config is forwarded to `MountableFS` so it can wrap individual backends/// with `EncryptionWrappedFS` during `mount()`. The top is always `StatsWrappedFS`.+/// PathLockWrappedFS is always inserted between stats and mountable.pub async fn build_default_stack(config: RagfsConfig) -> RagfsStack {let mountable = Arc::new(MountableFS::new());+ build_stack_with_mountable(config, mountable).await+}++/// Build the standard wrapper stack around an existing mount manager.+///+/// This is used by the binding's cache-aware mountable so cache and non-cache+/// construction share identical encryption and pathlock assembly.+pub async fn build_stack_with_mountable(+ config: RagfsConfig,+ mountable: Arc<MountableFS>,+) -> RagfsStack {register_builtin_plugins(&mountable).await;// Forward encryption config to MountableFS for per-backend wrapping.@@ -60,11 +90,28 @@ pub async fn build_default_stack(config: RagfsConfig) -> RagfsStack {.await;}- // MountableFS is the data entry point; encryption is applied inside mount().- let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(- mountable.clone() as Arc<dyn FileSystem>+ let provider: Arc<dyn PathLockProvider> = match config.pathlock.provider.as_str() {+ "memory" => Arc::new(MemoryPathLockProvider::new()),+ _ => Arc::new(FilesystemPathLockProvider::new(+ mountable.clone() as Arc<dyn FileSystem>,+ )),+ };+ let pathlock_manager = Arc::new(PathLockManager::new(+ mountable.clone() as Arc<dyn FileSystem>,+ provider,+ config.pathlock.clone(),));- RagfsStack { mountable, top }+ // Inject into MountableFS so EncryptionWrappedFS can use it for dual-path exact lock.+ mountable+ .set_pathlock_manager(pathlock_manager.clone())+ .await;+ let inner: Arc<dyn FileSystem> = Arc::new(PathLockWrappedFS::new(+ pathlock_manager.clone(),+ mountable.clone() as Arc<dyn FileSystem>,+ ));++ let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(inner));+ RagfsStack { mountable, top, pathlock_manager }}/// The single built-in plugin registration sequence (eliminates drift across call sites).@@ -82,7 +129,7 @@ pub async fn register_builtin_plugins(fs: &MountableFS) {#[cfg(test)]mod tests {use super::*;- use crate::core::context::{FsContextInner, FS_CTX};+ use crate::core::context::{FsContextInner, PathLockContext, FS_CTX};use crate::core::{ConfigValue, PluginConfig, Result, WriteFlag};use crate::crypto;use std::collections::HashMap;@@ -95,6 +142,20 @@ mod tests {root_key: [4u8; 32],provider_type: crypto::PROVIDER_LOCAL,}),+ ..RagfsConfig::default()+ }+ }++ fn enc_pathlock_config() -> RagfsConfig {+ RagfsConfig {+ encryption: Some(EncryptionConfig {+ root_key: [4u8; 32],+ provider_type: crypto::PROVIDER_LOCAL,+ }),+ pathlock: PathLockConfig {+ provider: "filesystem".to_string(),+ lock_expire_secs: 300.0,+ },}}@@ -149,6 +210,107 @@ mod tests {assert!(crypto::is_encrypted(&raw));}+ #[tokio::test]+ async fn encrypted_stack_with_pathlock_does_not_reacquire_final_lock() {+ let stack = build_default_stack(enc_pathlock_config()).await;+ mount_mem(&stack).await;++ let write = FS_CTX.scope(Arc::new(FsContextInner::new("tenant")), async {+ stack+ .top+ .write("/mem/f", b"hello", 0, WriteFlag::Create)+ .await+ });+ tokio::time::timeout(std::time::Duration::from_millis(200), write)+ .await+ .expect("encrypted write blocked on its own final-path lock")+ .unwrap();++ let rewrite = FS_CTX.scope(Arc::new(FsContextInner::new("tenant")), async {+ stack+ .top+ .write("/mem/f", b"updated", 0, WriteFlag::Create)+ .await+ });+ tokio::time::timeout(std::time::Duration::from_millis(200), rewrite)+ .await+ .expect("encrypted rewrite blocked on an unreleased lock token")+ .unwrap();+ }++ #[tokio::test]+ async fn encrypted_write_extends_outer_lease() {+ let stack = build_default_stack(enc_pathlock_config()).await;+ mount_mem(&stack).await;+ let manager = &stack.pathlock_manager;+ let outer = manager+ .acquire_exact("/mem/f", std::time::Duration::ZERO, None)+ .await+ .unwrap();+ let ctx = Arc::new(FsContextInner::with_pathlock(+ "tenant",+ PathLockContext {+ lease_ref: Some(outer.lease.lease_ref.clone()),+ disable_auto_pathlock: false,+ },+ ));++ let write = FS_CTX.scope(ctx, async {+ stack+ .top+ .write("/mem/f", b"hello", 0, WriteFlag::Create)+ .await+ });+ tokio::time::timeout(std::time::Duration::from_millis(200), write)+ .await+ .expect("encrypted write blocked on its outer final-path lease")+ .unwrap();++ manager.release(&outer).await.unwrap();+ }++ #[tokio::test]+ async fn encrypted_write_rejects_uncovered_outer_lease() {+ let stack = build_default_stack(enc_pathlock_config()).await;+ mount_mem(&stack).await;+ let manager = &stack.pathlock_manager;+ let outer = manager+ .acquire_exact("/mem/other", std::time::Duration::ZERO, None)+ .await+ .unwrap();+ let ctx = Arc::new(FsContextInner::with_pathlock(+ "tenant",+ PathLockContext {+ lease_ref: Some(outer.lease.lease_ref.clone()),+ disable_auto_pathlock: false,+ },+ ));++ let error = FS_CTX+ .scope(ctx, async {+ stack+ .top+ .write("/mem/f", b"hello", 0, WriteFlag::Create)+ .await+ })+ .await+ .unwrap_err();++ assert!(+ error+ .to_string()+ .contains("does not cover the requested operation")+ );+ manager.release(&outer).await.unwrap();+ }++ #[tokio::test]+ async fn default_stack_initializes_pathlock_manager() {+ let stack = build_default_stack(RagfsConfig::default()).await;+ let snapshot = stack.pathlock_manager.observe().await;+ assert_eq!(snapshot.active_locks, 0);+ }+#[tokio::test]async fn plaintext_stack_has_no_encryption_layer() {let stack = build_default_stack(RagfsConfig::default()).await;diff --git a/crates/ragfs/src/core/context.rs b/crates/ragfs/src/core/context.rsindex 3f1f36339..3587a13e3 100644--- a/crates/ragfs/src/core/context.rs+++ b/crates/ragfs/src/core/context.rs@@ -10,7 +10,8 @@use std::sync::Arc;-/// Immutable filesystem context snapshot. Currently carries only `account_id` (the tenant).+/// Immutable filesystem context snapshot. Currently carries `account_id` (the tenant)+/// and optional `PathLockContext`.pub type FsContext = Arc<FsContextInner>;tokio::task_local! {@@ -18,10 +19,20 @@ tokio::task_local! {pub static FS_CTX: FsContext;}+/// PathLock context carried in the FS context.+#[derive(Clone, Debug, Default)]+pub struct PathLockContext {+ /// Lease reference string for an existing owned lease.+ pub lease_ref: Option<String>,+ /// When true, automatic PathLock consumers skip lock validation and acquisition.+ pub disable_auto_pathlock: bool,+}+/// Context payload (immutable). Fields are filled once at construction, then read-only.#[derive(Clone, Debug)]pub struct FsContextInner {account_id: String,+ pathlock: Option<PathLockContext>,}impl FsContextInner {@@ -29,6 +40,18 @@ impl FsContextInner {pub fn new(account_id: impl Into<String>) -> Self {Self {account_id: account_id.into(),+ pathlock: None,+ }+ }++ /// Construct a context with account_id and pathlock context.+ pub fn with_pathlock(+ account_id: impl Into<String>,+ pathlock: PathLockContext,+ ) -> Self {+ Self {+ account_id: account_id.into(),+ pathlock: Some(pathlock),}}@@ -36,6 +59,21 @@ impl FsContextInner {pub fn account_id(&self) -> &str {&self.account_id}++ /// PathLock context, if set.+ pub fn pathlock(&self) -> Option<&PathLockContext> {+ self.pathlock.as_ref()+ }++ /// Return a context copy that preserves identity and lease while disabling automatic PathLock.+ pub fn with_auto_pathlock_disabled(&self) -> Self {+ let mut pathlock = self.pathlock.clone().unwrap_or_default();+ pathlock.disable_auto_pathlock = true;+ Self {+ account_id: self.account_id.clone(),+ pathlock: Some(pathlock),+ }+ }}/// Read-only view over the current task-local context.@@ -62,6 +100,23 @@ impl FsContextView {.map(|c| c.account_id()).filter(|account_id| !account_id.is_empty())}++ /// PathLock lease reference from the current context, or `None` if unset.+ pub fn pathlock_lease_ref(&self) -> Option<&str> {+ self.inner+ .as_ref()+ .and_then(|c| c.pathlock())+ .and_then(|p| p.lease_ref.as_deref())+ }++ /// Whether auto pathlock is disabled in the current context.+ pub fn disable_auto_pathlock(&self) -> bool {+ self.inner+ .as_ref()+ .and_then(|c| c.pathlock())+ .map(|p| p.disable_auto_pathlock)+ .unwrap_or(false)+ }}#[cfg(test)]diff --git a/crates/ragfs/src/core/encryption_wrapper.rs b/crates/ragfs/src/core/encryption_wrapper.rsindex 163fb88a3..542e4dec9 100644--- a/crates/ragfs/src/core/encryption_wrapper.rs+++ b/crates/ragfs/src/core/encryption_wrapper.rs@@ -17,6 +17,10 @@ use sha2::{Digest, Sha256};use tracing::warn;use crate::crypto;+use crate::core::internal_names::is_hidden_runtime_lock_name;+use crate::lock::{+ AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest,+};use crate::shape::SHAPE_MANIFEST_PATH;use super::context::FsContextView;@@ -40,6 +44,10 @@ pub struct EncryptionWrappedFS {account_keys: RwLock<HashMap<String, [u8; 32]>>,/// Lazily-warmed temp root cache, keyed by temp_root path.temp_root_ready: RwLock<HashMap<String, Instant>>,+ /// PathLock manager for dual-path exact lock on encrypted writes.+ pathlock_manager: Arc<PathLockManager>,+ /// Backend mount prefix used to restore manager-visible backend paths.+ backend_prefix: String,}impl EncryptionWrappedFS {@@ -48,17 +56,37 @@ impl EncryptionWrappedFS {&self.inner}- /// Construct an encryption layer over `inner`. Built only when a root key is configured.- pub fn new(inner: Arc<dyn FileSystem>, root_key: [u8; 32], provider_type: u8) -> Self {+ /// Construct an encryption layer with a pathlock manager for dual-path exact lock.+ pub fn new(+ inner: Arc<dyn FileSystem>,+ root_key: [u8; 32],+ provider_type: u8,+ pathlock_manager: Arc<PathLockManager>,+ backend_prefix: String,+ ) -> Self {Self {inner,root_key,provider_type,account_keys: RwLock::new(HashMap::new()),temp_root_ready: RwLock::new(HashMap::new()),+ pathlock_manager,+ backend_prefix,}}+ /// Convert one mount-relative path back to the manager's backend path space.+ fn backend_lock_path(&self, path: &str) -> String {+ if self.backend_prefix.is_empty() || self.backend_prefix == "/" {+ return format!("/{}", path.trim_start_matches('/'));+ }+ format!(+ "{}/{}",+ self.backend_prefix.trim_end_matches('/'),+ path.trim_start_matches('/')+ )+ }+/// Derive (and cache) the Account Key for `account_id` via HKDF (L2).fn get_account_key(&self, account_id: &str) -> [u8; 32] {if let Some(k) = self.account_keys.read().unwrap().get(account_id) {@@ -106,6 +134,14 @@ impl EncryptionWrappedFS {|| path.starts_with("/queue/")|| path == "/serverinfo"|| path.starts_with("/serverinfo/")+ || Self::is_lock_sidecar(path)+ }++ /// Return true when `path` is a lock sidecar file that must bypass encryption+ /// to preserve `CreateNew` atomicity.+ fn is_lock_sidecar(path: &str) -> bool {+ let name = path.rsplit_once('/').map(|(_, n)| n).unwrap_or(path);+ is_hidden_runtime_lock_name(name)}/// Return true when one path points at the backend-shape manifest.@@ -199,6 +235,47 @@ impl EncryptionWrappedFS {Ok(())}+ /// Write the encrypted envelope to the temp path, retrying on transient errors.+ async fn encrypted_write_inner(+ &self,+ path: &str,+ temp_path: &str,+ envelope: &[u8],+ ) -> Result<u64> {+ let written = match self+ .inner+ .write(temp_path, envelope, 0, WriteFlag::Create)+ .await+ {+ Ok(written) => written,+ Err(Error::NotFound(_)) => {+ let temp_root = Self::encrypted_temp_root(path);+ self.create_temp_root(&temp_root).await?;+ self.inner+ .write(temp_path, envelope, 0, WriteFlag::Create)+ .await?+ }+ Err(Error::AlreadyExists(_)) => {+ match self.inner.remove(temp_path).await {+ Ok(()) | Err(Error::NotFound(_)) => {}+ Err(err) => return Err(err),+ }+ self.inner+ .write(temp_path, envelope, 0, WriteFlag::Create)+ .await?+ }+ Err(err) => return Err(err),+ };+ if written != envelope.len() as u64 {+ return Err(Error::internal(format!(+ "encrypted temp write incomplete: wrote {} of {} bytes",+ written,+ envelope.len()+ )));+ }+ Ok(written)+ }+}/// Slice `data` by `(offset, size)` with `size == 0` meaning "to end", matching plugin read semantics.@@ -281,6 +358,8 @@ impl FileSystem for EncryptionWrappedFS {let envelope = crypto::build_envelope(self.provider_type, &enc_key, &key_iv, &data_iv, &ct);let temp_root = Self::encrypted_temp_root(path);let temp_path = Self::encrypted_temp_path(path);++ // Ensure temp root exists before acquiring locks (lock resolver needs stat).let now = Instant::now();let temp_root_ready = self.temp_root_ready@@ -291,39 +370,73 @@ impl FileSystem for EncryptionWrappedFS {if !temp_root_ready {self.create_temp_root(&temp_root).await?;}- let written = match self- .inner- .write(&temp_path, &envelope, 0, WriteFlag::Create)++ // Acquire dual-path exact lock for the temp publish path and the final visible path.+ let final_lock_path = self.backend_lock_path(path);+ let temp_lock_path = self.backend_lock_path(&temp_path);+ let final_request = PathLockRequest {+ path: final_lock_path,+ kind: PathLockKind::Exact,+ };+ let requests = vec![+ PathLockRequest { path: temp_lock_path, kind: PathLockKind::Exact },+ final_request.clone(),+ ];+ let action = self+ .pathlock_manager+ .resolve_auto_pathlock_action(&[final_request]).await- {- Ok(written) => written,- Err(Error::NotFound(_)) => {- self.create_temp_root(&temp_root).await?;- self.inner- .write(&temp_path, &envelope, 0, WriteFlag::Create)- .await?- }- Err(Error::AlreadyExists(_)) => {- match self.inner.remove(&temp_path).await {- Ok(()) | Err(Error::NotFound(_)) => {}- Err(err) => return Err(err),- }- self.inner- .write(&temp_path, &envelope, 0, WriteFlag::Create)- .await?+ .map_err(|error| {+ Error::internal(format!("encrypted write lock context error: {error}"))+ })?;+ let lock_guard = match action {+ AutoPathLockAction::Disabled => None,+ AutoPathLockAction::Covered(outer) => {+ let owner_capability = (+ outer.lease.lease_ref.as_str(),+ outer.ownership_ref.as_str(),+ );+ Some(+ self.pathlock_manager+ .acquire_batch(+ &requests,+ Duration::from_secs(1),+ Some(owner_capability),+ )+ .await+ .map_err(|error| {+ Error::internal(format!("encrypted write lock error: {error}"))+ })?,+ )}- Err(err) => return Err(err),+ AutoPathLockAction::Acquire => Some(+ self.pathlock_manager+ .acquire_batch(&requests, Duration::from_secs(1), None)+ .await+ .map_err(|error| {+ Error::internal(format!("encrypted write lock error: {error}"))+ })?,+ ),};- if written != envelope.len() as u64 {- return Err(Error::internal(format!(- "encrypted temp write incomplete: wrote {} of {} bytes",- written,- envelope.len()- )));- }- self.inner.replace(&temp_path, path).await?;- Ok(written)+ // Release lock on error. On success, release after replace.+ let result = self.encrypted_write_inner(path, &temp_path, &envelope).await;+ let replace_result = match result {+ Ok(written) => self.inner.replace(&temp_path, path).await.map(|_| written),+ Err(e) => Err(e),+ };+ // Release an acquired dual-path lock even if replace fails.+ let release_result = match lock_guard.as_ref() {+ Some(guard) => self.pathlock_manager.release(guard).await,+ None => Ok(()),+ };+ match (replace_result, release_result) {+ (Err(error), _) => Err(error),+ (Ok(written), Ok(())) => Ok(written),+ (Ok(_), Err(error)) => Err(Error::internal(format!(+ "encrypted write lock release error: {error}"+ ))),+ }}async fn grep(@@ -479,6 +592,9 @@ mod tests {use crate::core::context::{FsContextInner, FS_CTX};use crate::core::MountableFS;use crate::core::PluginConfig;+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };use crate::plugins::MemFSPlugin;/// Build a memfs plugin config for encryption wrapper tests.@@ -499,6 +615,18 @@ mod tests {m}+ /// Build a PathLock manager for one test mount stack.+ async fn memfs_pathlock_manager(stack: Arc<MountableFS>) -> Arc<PathLockManager> {+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ stack.clone() as Arc<dyn FileSystem>,+ provider,+ PathLockConfig::default(),+ ));+ stack.set_pathlock_manager(manager.clone()).await;+ manager+ }+fn ctx(account: &str) -> Arc<FsContextInner> {Arc::new(FsContextInner::new(account))}@@ -506,7 +634,14 @@ mod tests {#[tokio::test]async fn write_then_read_roundtrip_under_ctx() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [9u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [9u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("tenant-1"), async {@@ -522,7 +657,14 @@ mod tests {#[tokio::test]async fn on_disk_bytes_are_ciphertext_with_envelope() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner.clone(),+ [9u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("tenant-1"), async {@@ -541,7 +683,14 @@ mod tests {#[tokio::test]async fn read_without_account_id_errors() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner.clone(),+ [9u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );// Seed an envelope first.FS_CTX.scope(ctx("tenant-1"), async {@@ -558,7 +707,14 @@ mod tests {#[tokio::test]async fn read_offset_size_slicing() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [1u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [1u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("t"), async {enc.write("/mem/a.txt", b"0123456789", 0, WriteFlag::Create)@@ -574,7 +730,14 @@ mod tests {#[tokio::test]async fn grep_matches_encrypted_files() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [2u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("t"), async {enc.write(@@ -598,7 +761,14 @@ mod tests {#[tokio::test]async fn write_rejects_nonzero_offset() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [2u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("t"), async {let r = enc.write("/mem/a.txt", b"x", 5, WriteFlag::Create).await;@@ -610,7 +780,14 @@ mod tests {#[tokio::test]async fn create_writes_encrypted_empty_file() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner.clone(), [2u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner.clone(),+ [2u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("t"), async {enc.create("/mem/empty.txt").await.unwrap();@@ -626,7 +803,14 @@ mod tests {#[tokio::test]async fn cross_account_cannot_decrypt() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [3u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [3u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("acct-A"), async {enc.write("/mem/a.txt", b"owned by A", 0, WriteFlag::Create)@@ -644,7 +828,14 @@ mod tests {#[tokio::test]async fn write_rejects_append_flag() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [4u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("t"), async {enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)@@ -661,7 +852,14 @@ mod tests {#[tokio::test]async fn write_rejects_non_replacing_none_flag() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [4u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );FS_CTX.scope(ctx("t"), async {enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)@@ -676,7 +874,14 @@ mod tests {#[tokio::test]async fn rename_rejects_cross_account_paths() {let inner = memfs_stack_at("/local").await;- let enc = EncryptionWrappedFS::new(inner, [5u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner,+ [5u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/local".to_string(),+ );let result = FS_CTX.scope(ctx("acct-a"), async {enc.mkdir("/local/acct-a", 0).await.unwrap();@@ -694,7 +899,14 @@ mod tests {#[tokio::test]async fn write_replaces_stale_internal_temp_file_before_publish() {let inner = memfs_stack().await;- let enc = EncryptionWrappedFS::new(inner.clone(), [6u8; 32], crypto::PROVIDER_LOCAL);+ let manager = memfs_pathlock_manager(inner.clone()).await;+ let enc = EncryptionWrappedFS::new(+ inner.clone(),+ [6u8; 32],+ crypto::PROVIDER_LOCAL,+ manager,+ "/mem".to_string(),+ );let temp_path ="/mem/temp/.encrypt_stage/18d3740a61555bfecb941730d4b708dd3090a1b0ba2fcafe8c696d55c5e4b67a.encrypt";diff --git a/crates/ragfs/src/core/filesystem.rs b/crates/ragfs/src/core/filesystem.rsindex e76044bf8..7a9c7965e 100644--- a/crates/ragfs/src/core/filesystem.rs+++ b/crates/ragfs/src/core/filesystem.rs@@ -197,6 +197,52 @@ pub trait FileSystem: Send + Sync + Any {/// * `Error::IsADirectory` - If the path points to a directoryasync fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> Result<u64>;+ /// Replace a file only when its full current content equals `expected`.+ ///+ /// # Arguments+ /// * `path` - The path of the file to replace+ /// * `expected` - Exact current file content required for the replacement+ /// * `new_data` - New full file content+ ///+ /// # Returns+ /// `true` when replaced, `false` when the file is missing or no longer matches.+ ///+ /// # Errors+ /// Returns `Error::InvalidOperation` when the backend cannot provide a native+ /// compare-and-write operation.+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let _ = (expected, new_data);+ Err(Error::invalid_operation(format!(+ "compare_and_write is not supported: {}",+ path+ )))+ }++ /// Remove a file only when its full current content equals `expected`.+ ///+ /// # Arguments+ /// * `path` - The path of the file to remove+ /// * `expected` - Exact current file content required for removal+ ///+ /// # Returns+ /// `true` when removed, `false` when the file is missing or no longer matches.+ ///+ /// # Errors+ /// Returns `Error::InvalidOperation` when the backend cannot provide a native+ /// compare-and-remove operation.+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let _ = expected;+ Err(Error::invalid_operation(format!(+ "compare_and_remove is not supported: {}",+ path+ )))+ }+/// List directory contents////// # Arguments@@ -210,6 +256,17 @@ pub trait FileSystem: Send + Sync + Any {/// * `Error::NotADirectory` - If the path is not a directoryasync fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>>;+ /// List directory contents without public internal-name filtering.+ ///+ /// # Arguments+ /// * `path` - The directory path to list+ ///+ /// # Returns+ /// Raw directory entries visible to filesystem internals.+ async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ self.read_dir(path).await+ }+/// Get file or directory metadata////// # Arguments@@ -1016,7 +1073,7 @@ mod tests {let entries = root_tree(&fs, false, None, Some(1)).await;assert_eq!(entries.len(), 2);- assert_tree_names(&entries, &["a.txt", "sub"]);+ assert_tree_names(&entries, &["sub", "a.txt"]);}#[tokio::test]@@ -1081,8 +1138,8 @@ mod tests {let entries = fs.tree_directory("/", false, None, None).await.unwrap();assert_eq!(entries.len(), 2);- assert_eq!(entries[0].path, "/a.txt");- assert_eq!(entries[0].rel_path, "a.txt");+ assert_eq!(entries[0].path, "/sub");+ assert_eq!(entries[0].rel_path, "sub");}#[tokio::test]diff --git a/crates/ragfs/src/core/internal_names.rs b/crates/ragfs/src/core/internal_names.rsnew file mode 100644index 000000000..7d703cd22--- /dev/null+++ b/crates/ragfs/src/core/internal_names.rs@@ -0,0 +1,27 @@+//! Static built-in internal names shared across the RAGFS stack.+//!+//! Every module that references `.path.ovlock`, `.exact.ovlock.*`, `.redirect.json`,+//! or `.sync_log.json` must import these constants from this single source of truth.+//! There is no dynamic extension mechanism.++/// Path-lock marker for directory-level locks.+pub const PATH_LOCK_FILE: &str = ".path.ovlock";++/// Prefix for exact (sidecar) lock files: `.exact.ovlock.<safe_name>.<sha1-prefix>`.+pub const EXACT_LOCK_FILE_PREFIX: &str = ".exact.ovlock.";++/// Multi-write redirect metadata file.+pub const REDIRECT_FILE: &str = ".redirect.json";++/// Multi-write sync-log metadata file.+pub const SYNC_LOG_FILE: &str = ".sync_log.json";++/// Returns `true` when `name` is a runtime path-lock file (`.path.ovlock` or `.exact.ovlock.*`).+pub fn is_hidden_runtime_lock_name(name: &str) -> bool {+ name == PATH_LOCK_FILE || name.starts_with(EXACT_LOCK_FILE_PREFIX)+}++/// Returns `true` when `name` is any hidden internal name (lock files, redirect, sync-log).+pub fn is_hidden_internal_name(name: &str) -> bool {+ is_hidden_runtime_lock_name(name) || name == REDIRECT_FILE || name == SYNC_LOG_FILE+}diff --git a/crates/ragfs/src/core/mod.rs b/crates/ragfs/src/core/mod.rsindex 6bc43e939..d2d72a989 100644--- a/crates/ragfs/src/core/mod.rs+++ b/crates/ragfs/src/core/mod.rs@@ -13,6 +13,7 @@ pub mod encryption_wrapper;pub mod errors;pub mod filesystem;pub mod glob;+pub mod internal_names;pub mod mountable;pub mod multibackend_wrapper;pub mod plugin;@@ -23,10 +24,10 @@ pub mod types;// Re-export commonly used typespub use crate::multibackend::{FsContextResolver, MetaStateStore};pub use builder::{- build_default_stack, register_builtin_plugins, EncryptionConfig as BuilderEncryptionConfig,- RagfsConfig, RagfsStack,+ build_default_stack, build_stack_with_mountable, register_builtin_plugins,+ EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,};-pub use context::{FsContext, FsContextInner, FsContextView, FS_CTX};+pub use context::{FsContext, FsContextInner, FsContextView, PathLockContext, FS_CTX};pub use encryption_wrapper::EncryptionWrappedFS;pub use errors::{Error, Result};pub use filesystem::FileSystem;diff --git a/crates/ragfs/src/core/mountable.rs b/crates/ragfs/src/core/mountable.rsindex 9767214d2..ed1c66d1d 100644--- a/crates/ragfs/src/core/mountable.rs+++ b/crates/ragfs/src/core/mountable.rs@@ -8,16 +8,19 @@ use async_trait::async_trait;use radix_trie::{Trie, TrieCommon};use serde_json::Value;use std::collections::HashMap;-use std::sync::Arc;+use std::sync::{Arc, OnceLock};+use std::time::Duration;use tokio::sync::RwLock;use tracing::warn;+use crate::lock::{+ AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest,+};use crate::multibackend::factory::build_multi_write_fs;use crate::multibackend::types::MultiBackendBuildContext;use crate::shape::validate::ensure_backend_shape;-/// Python-side transaction path-lock marker — hidden in all listing/grep operations.-const PATH_LOCK_FILE: &str = ".path.ovlock";+use super::internal_names::is_hidden_internal_name;use super::encryption_wrapper::EncryptionWrappedFS;use super::errors::{Error, Result};@@ -74,6 +77,9 @@ pub struct MountableFS {encryption_root_key: RwLock<Option<[u8; 32]>>,encryption_provider_type: RwLock<Option<u8>>,+ /// PathLock manager, injected once before the stack starts serving requests.+ pathlock_manager: OnceLock<Arc<PathLockManager>>,+/// Optional cache configuration shared by mounted filesystems.#[cfg(feature = "cache")]cache: Option<MountCacheConfig>,@@ -143,6 +149,21 @@ impl MountableFS {None}+ /// Return whether a mounted wrapper chain contains encryption-owned pathlock.+ fn encryption_handles_pathlock_ref(fs: &dyn FileSystem) -> bool {+ let any = fs as &dyn std::any::Any;+ if any.downcast_ref::<EncryptionWrappedFS>().is_some() {+ return true;+ }+ if let Some(multiwrite) = any.downcast_ref::<MultiWriteWrappedFS>() {+ return multiwrite.encryption_handles_pathlock();+ }+ if let Some(stats) = any.downcast_ref::<StatsWrappedFS>() {+ return Self::encryption_handles_pathlock_ref(stats.inner_fs().as_ref());+ }+ false+ }+#[cfg(feature = "cache")]fn as_cached(fs: &Arc<dyn FileSystem>) -> Option<&CachedFileSystem> {let any = fs.as_ref() as &dyn std::any::Any;@@ -165,6 +186,14 @@ impl MountableFS {}}+ /// Return whether the mounted encryption wrapper owns pathlock for this path.+ pub async fn encryption_handles_pathlock(&self, path: &str) -> bool {+ let Ok((mount_info, _)) = self.find_mount(path).await else {+ return false;+ };+ Self::encryption_handles_pathlock_ref(mount_info.fs.as_ref())+ }+/// Query multi-write sync status for a mounted path.pub async fn system_sync_status(&self, path: &str) -> Result<Value> {let (mount_info, rel_path) = self.find_mount(path).await?;@@ -188,6 +217,7 @@ impl MountableFS {registry: Arc::new(RwLock::new(HashMap::new())),encryption_root_key: RwLock::new(None),encryption_provider_type: RwLock::new(None),+ pathlock_manager: OnceLock::new(),#[cfg(feature = "cache")]cache: None,}@@ -208,6 +238,7 @@ impl MountableFS {registry: Arc::new(RwLock::new(HashMap::new())),encryption_root_key: RwLock::new(None),encryption_provider_type: RwLock::new(None),+ pathlock_manager: OnceLock::new(),cache: Some(MountCacheConfig {provider,namespace,@@ -226,6 +257,13 @@ impl MountableFS {*self.encryption_provider_type.write().await = provider_type;}+ /// Set the pathlock manager for dual-path exact lock in EncryptionWrappedFS.+ pub async fn set_pathlock_manager(&self, manager: Arc<PathLockManager>) {+ if self.pathlock_manager.set(manager).is_err() {+ panic!("pathlock manager must only be initialized once");+ }+ }+/// Get the encryption root key and provider type.async fn get_encryption_config(&self) -> (Option<[u8; 32]>, Option<u8>) {let rk = *self.encryption_root_key.read().await;@@ -323,7 +361,18 @@ impl MountableFS {config.name)));}- Arc::new(EncryptionWrappedFS::new(storage_fs, rk, pt))+ let pl_mgr = self+ .pathlock_manager+ .get()+ .cloned()+ .expect("pathlock manager must be initialized before mount");+ Arc::new(EncryptionWrappedFS::new(+ storage_fs,+ rk,+ pt,+ pl_mgr,+ normalized_path.clone(),+ ))}_ => storage_fs,}@@ -396,6 +445,11 @@ impl MountableFS {bc: &BackendsConfig,) -> Result<MultiWriteWrappedFS> {let (enc_root_key, enc_provider_type) = self.get_encryption_config().await;+ let pathlock_manager = self+ .pathlock_manager+ .get()+ .cloned()+ .expect("pathlock manager must be initialized before multi-write mount");build_multi_write_fs(&self.registry,config,@@ -403,6 +457,8 @@ impl MountableFS {MultiBackendBuildContext {enc_root_key,enc_provider_type,+ pathlock_manager,+ backend_prefix: config.mount_path.clone(),},).await@@ -539,20 +595,66 @@ impl MountableFS {return Ok(true);}- if let Some(multiwrite) = Self::as_multiwrite(&src_mount.fs) {- return multiwrite- .copy_within_primary(&src_rel_path, &dst_rel_path)- .await;+ let multiwrite = Self::as_multiwrite(&src_mount.fs);+ let raw_backend = src_mount.raw_fs.clone();+ if multiwrite.is_none() && raw_backend.is_none() {+ return Ok(false);}- let Some(raw_backend) = src_mount.raw_fs.clone() else {- return Ok(false);+ let manager = self+ .pathlock_manager+ .get()+ .cloned()+ .expect("pathlock manager must be initialized before raw copy");+ let request = PathLockRequest {+ path: dst_path.to_string(),+ kind: PathLockKind::Exact,+ };+ let auto_lease = match manager.resolve_auto_pathlock_action(&[request]).await {+ Ok(AutoPathLockAction::Disabled | AutoPathLockAction::Covered(_)) => None,+ Ok(AutoPathLockAction::Acquire) => Some(+ manager+ .acquire_exact(dst_path, Duration::ZERO, None)+ .await+ .map_err(|error| Error::internal(format!("lock error: {error}")))?,+ ),+ Err(error) => {+ return Err(Error::internal(format!("lock lease error: {error}")));+ }};- Self::copy_raw_within_mount(raw_backend, &src_rel_path, &dst_rel_path).await?;- #[cfg(feature = "cache")]- Self::invalidate_cache_after_raw_write(&dst_mount, &dst_rel_path).await;- Ok(true)+ let result = if let Some(multiwrite) = multiwrite {+ multiwrite+ .copy_within_primary(&src_rel_path, &dst_rel_path)+ .await+ } else {+ match Self::copy_raw_within_mount(+ raw_backend.expect("raw backend checked above"),+ &src_rel_path,+ &dst_rel_path,+ )+ .await+ {+ Ok(()) => {+ #[cfg(feature = "cache")]+ Self::invalidate_cache_after_raw_write(&dst_mount, &dst_rel_path).await;+ Ok(true)+ }+ Err(error) => Err(error),+ }+ };++ let release = match auto_lease {+ Some(lease) => manager.release(&lease).await,+ None => Ok(()),+ };+ match (result, release) {+ (Err(error), _) => Err(error),+ (Ok(performed), Ok(())) => Ok(performed),+ (Ok(_), Err(error)) => Err(Error::internal(format!(+ "copy lock release error: {error}"+ ))),+ }}/// Copy one file within one raw backend in bounded-size chunks.@@ -762,10 +864,83 @@ impl FileSystem for MountableFS {mount_info.fs.write(&rel_path, data, offset, flags).await}+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let (mount_info, rel_path) = self.find_mount(path).await?;+ if let Some(multiwrite) = Self::as_multiwrite(&mount_info.fs) {+ if rel_path+ .rsplit('/')+ .next()+ .is_some_and(is_hidden_internal_name)+ {+ let raw = multiwrite.primary_raw_backend().ok_or_else(|| {+ Error::internal(format!(+ "raw backend is unavailable for mount '{}'",+ mount_info.path+ ))+ })?;+ let changed = raw.compare_and_write(&rel_path, expected, new_data).await?;+ if changed {+ #[cfg(feature = "cache")]+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;+ }+ return Ok(changed);+ }+ }+ let raw = Self::raw_backend_for_mount(&mount_info, "compare_and_write")?;+ let changed = raw.compare_and_write(&rel_path, expected, new_data).await?;+ if changed {+ #[cfg(feature = "cache")]+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;+ }+ Ok(changed)+ }++ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let (mount_info, rel_path) = self.find_mount(path).await?;+ if let Some(multiwrite) = Self::as_multiwrite(&mount_info.fs) {+ if rel_path+ .rsplit('/')+ .next()+ .is_some_and(is_hidden_internal_name)+ {+ let raw = multiwrite.primary_raw_backend().ok_or_else(|| {+ Error::internal(format!(+ "raw backend is unavailable for mount '{}'",+ mount_info.path+ ))+ })?;+ let changed = raw.compare_and_remove(&rel_path, expected).await?;+ if changed {+ #[cfg(feature = "cache")]+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;+ }+ return Ok(changed);+ }+ }+ let raw = Self::raw_backend_for_mount(&mount_info, "compare_and_remove")?;+ let changed = raw.compare_and_remove(&rel_path, expected).await?;+ if changed {+ #[cfg(feature = "cache")]+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;+ }+ Ok(changed)+ }+async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {+ let mut entries = self.read_internal_dir(path).await?;+ entries.retain(|entry| !is_hidden_internal_name(&entry.name));+ sort_directory_entries(&mut entries);+ Ok(entries)+ }++ async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {let (mount_info, rel_path) = self.find_mount(path).await?;- let mut entries = mount_info.fs.read_dir(&rel_path).await?;- entries.retain(|e| e.name != PATH_LOCK_FILE);+ let mut entries = mount_info.fs.read_internal_dir(&rel_path).await?;sort_directory_entries(&mut entries);Ok(entries)}@@ -861,12 +1036,12 @@ impl FileSystem for MountableFS {).await?;- // Filter out path-lock markers.+ // Filter out internal files from public search results.result.matches.retain(|m| {m.file.rsplit('/').next()- .map_or(true, |name| name != PATH_LOCK_FILE)+ .map_or(true, |name| !is_hidden_internal_name(name))});result.count = result.matches.len();Ok(result)@@ -902,12 +1077,12 @@ impl FileSystem for MountableFS {}}- // Filter out path-lock markers.+ // Filter out internal files from public tree results.entries.retain(|e| {e.path.rsplit('/').next()- .map_or(true, |name| name != PATH_LOCK_FILE)+ .map_or(true, |name| !is_hidden_internal_name(name))});Ok(entries)@@ -957,7 +1132,7 @@ impl FileSystem for MountableFS {.path.rsplit('/').next()- .map_or(true, |name| name != PATH_LOCK_FILE)+ .map_or(true, |name| !is_hidden_internal_name(name))});Ok(page)@@ -1263,6 +1438,32 @@ mod tests {mfs}+ /// Create a MountableFS backed by the real in-memory plugin.+ async fn mounted_memfs(mount_path: &str) -> MountableFS {+ use crate::plugins::MemFSPlugin;++ let mfs = MountableFS::new();+ mfs.register_plugin(MemFSPlugin).await;+ mfs.mount(test_config("memfs", mount_path)).await.unwrap();+ mfs+ }++ /// Create a cache-enabled MountableFS backed by the real in-memory plugin.+ #[cfg(feature = "cache")]+ async fn mounted_cached_memfs(namespace: &str, mount_path: &str) -> MountableFS {+ use crate::cache::{CacheNamespace, CachePolicy, MemoryCacheProvider};+ use crate::plugins::MemFSPlugin;++ let mfs = MountableFS::with_cache(+ Arc::new(MemoryCacheProvider::new()),+ CacheNamespace::new(namespace),+ CachePolicy::default(),+ );+ mfs.register_plugin(MemFSPlugin).await;+ mfs.mount(test_config("memfs", mount_path)).await.unwrap();+ mfs+ }+/// Create a MountableFS with two mounted mock plugins.async fn mounted_two_mocks() -> MountableFS {let mfs = MountableFS::new();@@ -1273,6 +1474,22 @@ mod tests {mfs}+ /// Attach a test pathlock manager so multi-write mounts can be constructed.+ async fn with_test_pathlock_manager(mfs: Arc<MountableFS>) -> Arc<MountableFS> {+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };++ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ mfs.clone() as Arc<dyn FileSystem>,+ provider,+ PathLockConfig::default(),+ ));+ mfs.set_pathlock_manager(manager).await;+ mfs+ }+#[test]fn test_normalize_path() {assert_eq!(normalize_path("/test"), "/test");@@ -1284,7 +1501,7 @@ mod tests {#[tokio::test]async fn test_mountable_fs_creation() {- let mfs = MountableFS::new();+ let mfs = Arc::new(MountableFS::new());let mounts = mfs.list_mounts().await;assert!(mounts.is_empty());}@@ -1393,6 +1610,55 @@ mod tests {);}+ #[tokio::test]+ async fn copy_within_mount_rejects_uncovered_lease() {+ use crate::core::{FsContextInner, PathLockContext, FS_CTX};+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };+ use crate::plugins::MemFSPlugin;++ let mfs = Arc::new(MountableFS::new());+ mfs.register_plugin(MemFSPlugin).await;+ mfs.mount(test_config("memfs", "/local")).await.unwrap();+ mfs.mkdir("/local/src", 0o755).await.unwrap();+ mfs.mkdir("/local/dst", 0o755).await.unwrap();+ mfs.write("/local/src/a.md", b"content", 0, WriteFlag::Create)+ .await+ .unwrap();+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ mfs.clone() as Arc<dyn FileSystem>,+ provider,+ PathLockConfig::default(),+ ));+ mfs.set_pathlock_manager(manager.clone()).await;+ let outer = manager+ .acquire_exact("/local/dst", std::time::Duration::ZERO, None)+ .await+ .unwrap();+ let ctx = Arc::new(FsContextInner::with_pathlock(+ "tenant",+ PathLockContext {+ lease_ref: Some(outer.lease.lease_ref.clone()),+ disable_auto_pathlock: false,+ },+ ));++ let result = FS_CTX+ .scope(ctx, async {+ mfs.copy_within_mount("/local/src/a.md", "/local/dst/a.md")+ .await+ })+ .await;++ assert!(result+ .unwrap_err()+ .to_string()+ .contains("does not cover the requested operation"));+ manager.release(&outer).await.unwrap();+ }+#[cfg(feature = "cache")]#[tokio::test]async fn copy_within_mount_overwrite_invalidates_cached_destination() {@@ -1449,16 +1715,27 @@ mod tests {async fn encrypted_mount_caches_ciphertext_below_account_validation() {use crate::cache::{CacheNamespace, CachePolicy, CacheProvider, MemoryCacheProvider};use crate::core::{FsContextInner, FS_CTX};+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };use crate::plugins::MemFSPlugin;- let provider = Arc::new(MemoryCacheProvider::new());- let mfs = MountableFS::with_cache(- provider.clone(),+ let cache_provider = Arc::new(MemoryCacheProvider::new());+ let mfs = Arc::new(MountableFS::with_cache(+ cache_provider.clone(),CacheNamespace::new("encrypted-mount-test"),CachePolicy::default(),- );+ ));mfs.register_plugin(MemFSPlugin).await;mfs.set_encryption_config(Some([9u8; 32]), Some(1)).await;+ let pathlock_provider: Arc<dyn PathLockProvider> =+ Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ mfs.clone() as Arc<dyn FileSystem>,+ pathlock_provider,+ PathLockConfig::default(),+ ));+ mfs.set_pathlock_manager(manager).await;mfs.mount(test_config("memfs", "/local")).await.unwrap();mfs.mkdir("/local/shared", 0o755).await.unwrap();@@ -1496,13 +1773,13 @@ mod tests {"missing account context must not receive cached plaintext");- let file_key = provider+ let file_key = cache_provider.keys().await.into_iter().find(|key| key.contains(":file:")).expect("encrypted read should populate one file cache object");- let encoded = provider+ let encoded = cache_provider.get(&file_key).await.unwrap()@@ -1524,17 +1801,27 @@ mod tests {#[tokio::test]async fn encrypted_multiwrite_mount_does_not_install_plaintext_cache() {use crate::cache::{CacheNamespace, CachePolicy, MemoryCacheProvider};+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };+ use crate::plugins::MemFSPlugin;- let mfs = MountableFS::with_cache(+ let mfs = Arc::new(MountableFS::with_cache(Arc::new(MemoryCacheProvider::new()),CacheNamespace::new("encrypted-multiwrite-test"),CachePolicy::default(),- );- mfs.register_plugin(MockPlugin::new("primary")).await;- mfs.register_plugin(MockPlugin::new("backupfs")).await;+ ));+ mfs.register_plugin(MemFSPlugin).await;mfs.set_encryption_config(Some([9u8; 32]), Some(1)).await;+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ mfs.clone() as Arc<dyn FileSystem>,+ provider,+ PathLockConfig::default(),+ ));+ mfs.set_pathlock_manager(manager).await;- let mut config = multiwrite_test_config("primary", "backupfs", "/local");+ let mut config = multiwrite_test_config("memfs", "memfs", "/local");config.server_encryption_enabled = true;config.primary_encryption_enabled = true;mfs.mount(config).await.unwrap();@@ -1603,7 +1890,7 @@ mod tests {#[tokio::test]async fn test_mount_duplicate_error() {- let mfs = MountableFS::new();+ let mfs = Arc::new(MountableFS::new());mfs.register_plugin(MockPlugin::new("mock")).await;let config = test_config("mock", "/mock");@@ -1857,7 +2144,7 @@ mod tests {#[tokio::test]async fn test_build_multi_write_fs_rejects_primary_encryption_disable() {- let mfs = MountableFS::new();+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;mfs.set_encryption_config(Some([7u8; 32]), Some(1)).await;@@ -1896,9 +2183,66 @@ mod tests {assert!(matches!(result.err(), Some(Error::Config(_))));}+ #[tokio::test]+ async fn encrypted_multiwrite_reports_pathlock_ownership() {+ use crate::core::{FsContextInner, PathLockContext, FS_CTX};+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };+ use crate::plugins::MemFSPlugin;++ let mfs = Arc::new(MountableFS::new());+ mfs.register_plugin(MemFSPlugin).await;+ mfs.set_encryption_config(Some([7u8; 32]), Some(1)).await;+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ mfs.clone() as Arc<dyn FileSystem>,+ provider,+ PathLockConfig::default(),+ ));+ mfs.set_pathlock_manager(manager.clone()).await;++ let mut config = multiwrite_test_config("memfs", "memfs", "/local");+ config.server_encryption_enabled = true;+ config.primary_encryption_enabled = true;+ mfs.mount(config).await.unwrap();++ assert!(mfs.encryption_handles_pathlock("/local/file.txt").await);++ let outer_ctx = Arc::new(FsContextInner::new("tenant"));+ let outer = FS_CTX+ .scope(outer_ctx, async {+ manager+ .acquire_exact("/local/tenant/file.txt", std::time::Duration::ZERO, None)+ .await+ })+ .await+ .unwrap();+ let ctx = Arc::new(FsContextInner::with_pathlock(+ "tenant",+ PathLockContext {+ lease_ref: Some(outer.lease.lease_ref.clone()),+ disable_auto_pathlock: false,+ },+ ));+ FS_CTX+ .scope(ctx, async {+ mfs.write(+ "/local/tenant/file.txt",+ b"content",+ 0,+ WriteFlag::Create,+ )+ .await+ })+ .await+ .unwrap();+ manager.release(&outer).await.unwrap();+ }+#[tokio::test]async fn test_build_multi_write_fs_rejects_exclude_target_field() {- let mfs = MountableFS::new();+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -1940,7 +2284,7 @@ mod tests {#[tokio::test]async fn test_build_multi_write_fs_rejects_reserved_primary_backup_name() {- let mfs = MountableFS::new();+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -1979,11 +2323,23 @@ mod tests {#[tokio::test]async fn test_single_backend_mount_wraps_stats_outside_encryption() {- let mfs = MountableFS::new();- mfs.register_plugin(MockPlugin::new("mock")).await;+ use crate::lock::{+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,+ };+ use crate::plugins::MemFSPlugin;++ let mfs = Arc::new(MountableFS::new());+ mfs.register_plugin(MemFSPlugin).await;mfs.set_encryption_config(Some([9u8; 32]), Some(1)).await;+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());+ let manager = Arc::new(PathLockManager::new(+ mfs.clone() as Arc<dyn FileSystem>,+ provider,+ PathLockConfig::default(),+ ));+ mfs.set_pathlock_manager(manager).await;- mfs.mount(test_config("mock", "/mock")).await.unwrap();+ mfs.mount(test_config("memfs", "/mock")).await.unwrap();let mounts = mfs.mounts.read().await;let mount_info = mounts.get("/mock").expect("mounted entry should exist");@@ -2000,7 +2356,7 @@ mod tests {#[tokio::test]async fn test_multiwrite_mount_wraps_stats_outside_multiwrite() {- let mfs = MountableFS::new();+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -2023,7 +2379,7 @@ mod tests {#[tokio::test]async fn test_multiwrite_raw_access_is_rejected() {- let mfs = MountableFS::new();+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -2043,7 +2399,7 @@ mod tests {#[tokio::test]async fn test_mountable_multiwrite_admin_smoke() {- let mfs = MountableFS::new();+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;diff --git a/crates/ragfs/src/core/multibackend_wrapper.rs b/crates/ragfs/src/core/multibackend_wrapper.rsindex 0d204dba1..db2f7e1ef 100644--- a/crates/ragfs/src/core/multibackend_wrapper.rs+++ b/crates/ragfs/src/core/multibackend_wrapper.rs@@ -19,6 +19,7 @@ use serde_json::Value;use tokio::sync::{Mutex, Notify};use super::context::{FsContext, FS_CTX};+use super::encryption_wrapper::EncryptionWrappedFS;use super::errors::{Error, Result};use super::filesystem::{normalize_prefix_path, relative_match_file, FileSystem};use super::types::{@@ -29,6 +30,7 @@ use super::types::{use crate::core::glob::{compare_rel_paths, decode_offset_token, encode_offset_token, PreparedGlob,};+use crate::core::internal_names::is_hidden_internal_name;use crate::multibackend::meta::{current_required_ctx, file_name, parent_dir, DefaultFsContextResolver, FsContextResolver,MetaStateStore, PathSerializer, MULTIWRITE_INTERNAL_NAMES,@@ -581,6 +583,17 @@ impl MultiWriteWrappedFS {ctx_resolver: Arc::new(DefaultFsContextResolver),}}++ /// Return the raw primary backend for mount-level internal-name operations.+ pub(crate) fn primary_raw_backend(&self) -> Option<Arc<dyn FileSystem>> {+ self.inner.primary().raw_backend.clone()+ }++ /// Return whether encrypted backends own dual-path PathLock acquisition.+ pub(crate) fn encryption_handles_pathlock(&self) -> bool {+ let any = self.inner.primary().backend.as_ref() as &dyn std::any::Any;+ any.downcast_ref::<EncryptionWrappedFS>().is_some()+ }}impl Inner {@@ -1290,6 +1303,9 @@ impl MultiWriteWrappedFS {#[async_trait]impl FileSystem for MultiWriteWrappedFS {async fn create(&self, path: &str) -> Result<()> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.create(path).await;+ }self.execute_simple_write(path, 0, Some(SyncOp::Create), |fs, path| async move {fs.create(&path).await})@@ -1307,6 +1323,9 @@ impl FileSystem for MultiWriteWrappedFS {}async fn remove(&self, path: &str) -> Result<()> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.remove(path).await;+ }self.execute_simple_write(path, 0, Some(SyncOp::Remove), |fs, path| async move {fs.remove(&path).await})@@ -1314,6 +1333,9 @@ impl FileSystem for MultiWriteWrappedFS {}async fn remove_all(&self, path: &str) -> Result<()> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.remove_all(path).await;+ }self.execute_simple_write(path, 0, Some(SyncOp::RemoveAll), |fs, path| async move {fs.remove_all(&path).await})@@ -1321,6 +1343,9 @@ impl FileSystem for MultiWriteWrappedFS {}async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.read(path, offset, size).await;+ }if let Some(fs) = self.inner.resolve_read_backend(path).await {return fs.read(path, offset, size).await;}@@ -1328,6 +1353,14 @@ impl FileSystem for MultiWriteWrappedFS {}async fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> Result<u64> {+ if is_hidden_internal_name(file_name(path)) {+ return self+ .inner+ .primary()+ .backend+ .write(path, data, offset, flags)+ .await;+ }let inner = &self.inner;let data_len = data.len() as u64;let path_owned = path.to_string();@@ -1383,6 +1416,9 @@ impl FileSystem for MultiWriteWrappedFS {}async fn stat(&self, path: &str) -> Result<FileInfo> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.stat(path).await;+ }if let Some(fs) = self.inner.resolve_read_backend(path).await {return fs.stat(path).await;}@@ -1390,6 +1426,11 @@ impl FileSystem for MultiWriteWrappedFS {}async fn rename(&self, old_path: &str, new_path: &str) -> Result<()> {+ if is_hidden_internal_name(file_name(old_path))+ || is_hidden_internal_name(file_name(new_path))+ {+ return self.inner.primary().backend.rename(old_path, new_path).await;+ }let ctx = current_required_ctx()?;let inner = &self.inner;let old_owned = old_path.to_string();@@ -1431,6 +1472,9 @@ impl FileSystem for MultiWriteWrappedFS {}async fn chmod(&self, path: &str, mode: u32) -> Result<()> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.chmod(path, mode).await;+ }self.execute_simple_write(path,0,@@ -1441,6 +1485,9 @@ impl FileSystem for MultiWriteWrappedFS {}async fn truncate(&self, path: &str, size: u64) -> Result<()> {+ if is_hidden_internal_name(file_name(path)) {+ return self.inner.primary().backend.truncate(path, size).await;+ }self.execute_simple_write(path,size,diff --git a/crates/ragfs/src/core/types.rs b/crates/ragfs/src/core/types.rsindex 767091b0b..35d9f64f5 100644--- a/crates/ragfs/src/core/types.rs+++ b/crates/ragfs/src/core/types.rs@@ -187,9 +187,16 @@ impl FileInfo {/// Write operation flags#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]pub enum WriteFlag {- /// Create new file or truncate existing+ /// Create new file or truncate existing.+ ///+ /// Follows POSIX `O_CREAT` / Rust `OpenOptions::create(true)` convention:+ /// create-or-open (non-exclusive). For exclusive create-if-absent, use+ /// `CreateNew` (POSIX `O_CREAT | O_EXCL` / Rust `create_new(true)`).Create,+ /// Create new file, fail if already exists+ CreateNew,+/// Append to existing fileAppend,diff --git a/crates/ragfs/src/git/enumerate.rs b/crates/ragfs/src/git/enumerate.rsindex fc2a287a6..cd2a77c73 100644--- a/crates/ragfs/src/git/enumerate.rs+++ b/crates/ragfs/src/git/enumerate.rs@@ -14,6 +14,8 @@//! L0/L1 derived files (`.abstract.md`, `.overview.md`, `.relations.json`)//! are intentionally KEPT — design §4.2 says they belong in snapshots.+use crate::core::internal_names::{is_hidden_runtime_lock_name, PATH_LOCK_FILE};+use std::sync::Arc;use crate::core::filesystem::FileSystem;@@ -47,11 +49,12 @@ pub fn prune_path(rel: &str) -> bool {return true;}- // Rule 2: any segment equals or starts with ".path.ovlock"- for seg in &segments {- if seg.starts_with(".path.ovlock") {- return true;- }+ // Rule 2: any segment is a runtime path-lock file.+ if segments+ .iter()+ .any(|segment| segment.starts_with(PATH_LOCK_FILE) || is_hidden_runtime_lock_name(segment))+ {+ return true;}// Rule 3a: any intermediate segment named exactly "embedding_cache"@@ -389,6 +392,9 @@ mod tests {assert!(prune_path("upload/x"));assert!(prune_path("resources/.path.ovlock"));assert!(prune_path(".path.ovlock"));+ assert!(prune_path(+ "resources/.exact.ovlock.file.txt.0123456789abcdef"+ ));assert!(prune_path("resources/x.faiss"));assert!(prune_path("resources/x.index"));assert!(prune_path("resources/embedding_cache/v.bin"));diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rsindex c83488fec..3b583f745 100644--- a/crates/ragfs/src/git/service.rs+++ b/crates/ragfs/src/git/service.rs@@ -1303,6 +1303,8 @@ impl GitService {Err(e) => failed_deletes.push((path, e.to_string())),}}+ written_paths.sort();+ deleted_paths.sort();let written_actual = written_paths.len();let deleted_actual = deleted_paths.len();diff --git a/crates/ragfs/src/lib.rs b/crates/ragfs/src/lib.rsindex 082e9b4e1..06fad00b8 100644--- a/crates/ragfs/src/lib.rs+++ b/crates/ragfs/src/lib.rs@@ -33,6 +33,7 @@pub mod cache;pub mod core;pub mod crypto;+pub mod lock;pub mod multibackend;pub mod git;pub mod plugins;diff --git a/crates/ragfs/src/lock/codec.rs b/crates/ragfs/src/lock/codec.rsnew file mode 100644index 000000000..45d7c5bdf--- /dev/null+++ b/crates/ragfs/src/lock/codec.rs@@ -0,0 +1,103 @@+//! Lock token encoder/decoder.+//!+//! Wire format: `{owner_id}:{time_ns}:{lock_type}` where lock_type is `E` or `T`.++use super::types::{LockToken, PathLockError, PathLockKind, PathLockResult};++/// Encodes and decodes lock tokens in the `owner_id:time_ns:lock_type` text format.+pub struct LockTokenCodec;++impl LockTokenCodec {+ /// Encode a `LockToken` into its wire format.+ pub fn encode(token: &LockToken) -> String {+ format!(+ "{}:{}:{}",+ token.owner_id,+ token.time_ns,+ token.lock_type.to_code()+ )+ }++ /// Decode a raw token string into a `LockToken`.+ /// Only accepts `E` (Exact) and `T` (Tree) lock type codes.+ pub fn decode(raw: &str) -> PathLockResult<LockToken> {+ let (owner_id, rest) = raw+ .split_once(':')+ .ok_or_else(|| PathLockError::InvalidToken(format!("missing ':' in token: {raw}")))?;++ let (time_ns_str, rest) = rest.split_once(':').ok_or_else(|| {+ PathLockError::InvalidToken(format!("missing second ':' in token: {raw}"))+ })?;++ let time_ns: u128 = time_ns_str.parse().map_err(|_| {+ PathLockError::InvalidToken(format!("invalid time_ns in token: {raw}"))+ })?;++ let mut lock_type_chars = rest.chars();+ let lock_type_char = lock_type_chars+ .next()+ .ok_or_else(|| PathLockError::InvalidToken(format!("empty lock type in token: {raw}")))?;+ if lock_type_chars.next().is_some() {+ return Err(PathLockError::InvalidToken(format!(+ "invalid lock type in token: {raw}"+ )));+ }++ let lock_type = PathLockKind::from_code(lock_type_char).ok_or_else(|| {+ PathLockError::InvalidToken(format!(+ "unknown lock type '{}' in token: {raw}",+ lock_type_char+ ))+ })?;++ Ok(LockToken {+ owner_id: owner_id.to_string(),+ time_ns,+ lock_type,+ })+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn roundtrip_supported_lock_types() {+ for token in [+ LockToken {+ owner_id: "abc-123".to_string(),+ time_ns: 1700000000000000000,+ lock_type: PathLockKind::Exact,+ },+ LockToken {+ owner_id: "xyz-456".to_string(),+ time_ns: 42,+ lock_type: PathLockKind::Tree,+ },+ ] {+ let encoded = LockTokenCodec::encode(&token);+ let decoded = LockTokenCodec::decode(&encoded).unwrap();+ assert_eq!(decoded.owner_id, token.owner_id);+ assert_eq!(decoded.time_ns, token.time_ns);+ assert_eq!(decoded.lock_type, token.lock_type);+ }+ }++ #[test]+ fn rejects_legacy_and_malformed_tokens() {+ for raw in [+ "owner:100:P",+ "owner:100:S",+ "no-colons",+ "a:b:c:d",+ "owner:100:E:1",+ "a:not-a-number:E",+ ] {+ assert!(matches!(+ LockTokenCodec::decode(raw),+ Err(PathLockError::InvalidToken(_))+ ));+ }+ }+}diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsnew file mode 100644index 000000000..75da20ddb--- /dev/null+++ b/crates/ragfs/src/lock/manager.rs@@ -0,0 +1,1885 @@+//! PathLockManager — single source of truth for all lock semantics.+//!+//! Owns the provider, resolver, lease registry, and metrics. All lock acquisition,+//! refresh, release, handoff, and adopt flows go through this manager.++use std::collections::{HashMap, HashSet};+use std::sync::Arc;+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};++use tokio::sync::RwLock;+use tracing::error;+use uuid::Uuid;++use crate::core::internal_names::{EXACT_LOCK_FILE_PREFIX, PATH_LOCK_FILE};+use crate::core::{FileSystem, FsContextView};++use super::metrics::LockMetrics;+use super::provider::PathLockProvider;+use super::resolver::{LockPathResolver, ResolvedExactPaths};+use super::types::{+ BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,+ PathLockKind, PathLockLease, PathLockObserveSnapshot, PathLockRequest, PathLockResult,+ PathLockError,+};++/// Configuration for the PathLockManager.+#[derive(Debug, Clone)]+pub struct PathLockConfig {+ /// Built-in provider name: `filesystem` or `memory`.+ pub provider: String,+ /// Seconds after which a lock token is considered stale.+ pub lock_expire_secs: f64,+}++impl Default for PathLockConfig {+ fn default() -> Self {+ Self {+ provider: "filesystem".to_string(),+ lock_expire_secs: 300.0,+ }+ }+}++/// Decision for one automatic PathLock operation under the current FS context.+#[derive(Debug, Clone)]+pub enum AutoPathLockAction {+ /// The scoped context explicitly disables automatic PathLock.+ Disabled,+ /// An active owned lease already covers the operation.+ Covered(OwnedPathLockLease),+ /// No lease is supplied, so the caller must acquire locks.+ Acquire,+}++/// Internal registry entry for an active lease.+#[derive(Debug, Clone)]+struct LeaseEntry {+ lease: PathLockLease,+ ownership_ref: String,+ lock_kinds: HashMap<String, PathLockKind>,+ last_active_at: Instant,+}++#[derive(Debug)]+enum AcquisitionChange {+ Created,+ Reentrant,+ Upgraded {+ previous: LockToken,+ replacement: LockToken,+ },+}++/// Registry of all active leases in this process.+#[derive(Debug, Default)]+struct LeaseRegistry {+ entries: HashMap<String, LeaseEntry>,+ lock_refs: HashMap<(String, String), usize>,+}++impl LeaseRegistry {+ /// Register one owned lease and increment its local token references.+ fn insert(&mut self, lease: PathLockLease, ownership_ref: String) {+ let lease_ref = lease.lease_ref.clone();+ let lock_kinds = lease+ .lock_paths+ .iter()+ .cloned()+ .zip(lease.covered_paths.iter().map(|request| request.kind))+ .collect();+ let mut unique_paths = HashSet::new();+ for lock_path in &lease.lock_paths {+ if unique_paths.insert(lock_path.clone()) {+ *self+ .lock_refs+ .entry((lease.owner_id.clone(), lock_path.clone()))+ .or_default() += 1;+ }+ }+ self.entries.insert(+ lease_ref,+ LeaseEntry {+ lease,+ ownership_ref,+ lock_kinds,+ last_active_at: Instant::now(),+ },+ );+ }++ /// Find one active lease for an owner.+ fn get_by_owner(&self, owner_id: &str) -> Option<&LeaseEntry> {+ self.entries+ .values()+ .find(|entry| entry.lease.owner_id == owner_id)+ }++ /// Find one active lease by its opaque reference.+ fn get_by_ref(&self, lease_ref: &str) -> Option<&LeaseEntry> {+ self.entries.get(lease_ref)+ }++ /// Remove one lease and return token paths whose local reference count reached zero.+ fn remove(&mut self, lease_ref: &str) -> Option<(LeaseEntry, Vec<String>, Vec<String>)> {+ let entry = self.entries.remove(lease_ref)?;+ let release_paths = self.decrement_refs(&entry.lease.owner_id, &entry.lease.lock_paths);+ let downgrade_paths = entry+ .lock_kinds+ .iter()+ .filter(|(path, kind)| {+ **kind == PathLockKind::Tree+ && !release_paths.contains(path)+ && self.strongest_kind(&entry.lease.owner_id, path) == Some(PathLockKind::Exact)+ })+ .map(|(path, _)| path.clone())+ .collect();+ Some((entry, release_paths, downgrade_paths))+ }++ /// Remove selected token references from one lease.+ fn remove_selected(+ &mut self,+ lease_ref: &str,+ selected_paths: &[String],+ ) -> Option<(LeaseEntry, String, Vec<String>, Vec<String>)> {+ let mut entry = self.entries.remove(lease_ref)?;+ let original_entry = entry.clone();+ let selected: HashSet<&str> = selected_paths.iter().map(String::as_str).collect();+ let removed: Vec<String> = entry+ .lease+ .lock_paths+ .iter()+ .filter(|path| selected.contains(path.as_str()))+ .cloned()+ .collect();+ entry+ .lease+ .lock_paths+ .retain(|path| !selected.contains(path.as_str()));+ entry+ .lock_kinds+ .retain(|path, _| !selected.contains(path.as_str()));+ entry.lease.covered_paths = original_entry+ .lease+ .lock_paths+ .iter()+ .zip(&original_entry.lease.covered_paths)+ .filter(|(path, _)| !selected.contains(path.as_str()))+ .map(|(_, request)| request.clone())+ .collect();++ let owner_id = entry.lease.owner_id.clone();+ let release_paths = self.decrement_refs(&owner_id, &removed);+ if !entry.lease.lock_paths.is_empty() {+ self.entries.insert(lease_ref.to_string(), entry);+ }+ let downgrade_paths = original_entry+ .lock_kinds+ .iter()+ .filter(|(path, kind)| {+ selected.contains(path.as_str())+ && **kind == PathLockKind::Tree+ && !release_paths.contains(path)+ && self.strongest_kind(&owner_id, path) == Some(PathLockKind::Exact)+ })+ .map(|(path, _)| path.clone())+ .collect();+ Some((+ original_entry,+ owner_id,+ release_paths,+ downgrade_paths,+ ))+ }++ /// Restore one lease after a provider release failure.+ fn restore(&mut self, entry: LeaseEntry) {+ self.entries+ .insert(entry.lease.lease_ref.clone(), entry);+ self.rebuild_lock_refs();+ }++ /// Rebuild local token reference counts from active lease entries.+ fn rebuild_lock_refs(&mut self) {+ let mut lock_refs = HashMap::new();+ for entry in self.entries.values() {+ let mut unique_paths = HashSet::new();+ for lock_path in &entry.lease.lock_paths {+ if unique_paths.insert(lock_path) {+ *lock_refs+ .entry((entry.lease.owner_id.clone(), lock_path.clone()))+ .or_default() += 1;+ }+ }+ }+ self.lock_refs = lock_refs;+ }++ /// Update the last successful refresh timestamp for one lease.+ fn touch(&mut self, lease_ref: &str) {+ if let Some(entry) = self.entries.get_mut(lease_ref) {+ entry.last_active_at = Instant::now();+ }+ }++ /// Decrement local references and return paths no longer used by any local lease.+ fn decrement_refs(&mut self, owner_id: &str, lock_paths: &[String]) -> Vec<String> {+ let mut release_paths = Vec::new();+ let mut unique_paths = HashSet::new();+ for lock_path in lock_paths {+ if !unique_paths.insert(lock_path.clone()) {+ continue;+ }+ let key = (owner_id.to_string(), lock_path.clone());+ match self.lock_refs.get_mut(&key) {+ Some(count) if *count > 1 => *count -= 1,+ Some(_) => {+ self.lock_refs.remove(&key);+ release_paths.push(lock_path.clone());+ }+ None => {}+ }+ }+ release_paths+ }++ /// Return the strongest active reference kind for one owner and token path.+ fn strongest_kind(&self, owner_id: &str, lock_path: &str) -> Option<PathLockKind> {+ self.entries+ .values()+ .filter(|entry| entry.lease.owner_id == owner_id)+ .filter_map(|entry| entry.lock_kinds.get(lock_path).copied())+ .max_by_key(|kind| match kind {+ PathLockKind::Exact => 0,+ PathLockKind::Tree => 1,+ })+ }+}++/// The central lock manager.+pub struct PathLockManager {+ provider: Arc<dyn PathLockProvider>,+ resolver: LockPathResolver,+ lease_registry: Arc<RwLock<LeaseRegistry>>,+ config: PathLockConfig,+ metrics: Arc<RwLock<LockMetrics>>,+}++impl PathLockManager {+ /// Create a new PathLockManager.+ pub fn new(+ fs: Arc<dyn FileSystem>,+ provider: Arc<dyn PathLockProvider>,+ config: PathLockConfig,+ ) -> Self {+ let registry = Arc::new(RwLock::new(LeaseRegistry::default()));+ let metrics = Arc::new(RwLock::new(LockMetrics::default()));++ // Spawn a background task that refreshes active owned leases.+ let refresh_registry = registry.clone();+ let refresh_provider = provider.clone();+ let refresh_config = config.clone();+ let refresh_metrics = metrics.clone();+ let refresh_interval = Duration::from_secs_f64(config.lock_expire_secs / 3.0);+ tokio::spawn(async move {+ loop {+ tokio::time::sleep(refresh_interval).await;+ let now_ns = Self::now_ns();+ let lease_refs: Vec<String> = {+ let reg = refresh_registry.read().await;+ reg.entries+ .iter()+ .map(|(lease_ref, _)| lease_ref.clone())+ .collect()+ };+ for lease_ref in lease_refs {+ let refresh_guard = refresh_registry.read().await;+ let Some(entry) = refresh_guard.entries.get(&lease_ref) else {+ continue;+ };+ let owner_id = entry.lease.owner_id.clone();+ let lock_paths = entry.lease.lock_paths.clone();+ let mut all_ok = true;+ for lp in &lock_paths {+ match refresh_provider.refresh_token(lp, &owner_id, now_ns).await {+ Ok(true) => {}+ _ => all_ok = false,+ }+ }+ drop(refresh_guard);+ if all_ok {+ refresh_registry.write().await.touch(&lease_ref);+ }+ }+ let stale_cutoff = Instant::now()+ - Duration::from_secs_f64(refresh_config.lock_expire_secs * 2.0);+ let stale_refs: Vec<String> = {+ let reg = refresh_registry.read().await;+ reg.entries+ .iter()+ .filter(|(_, entry)| entry.last_active_at <= stale_cutoff)+ .map(|(lease_ref, _)| lease_ref.clone())+ .collect()+ };+ let mut removed = 0;+ for lease_ref in stale_refs {+ let removed_entry = refresh_registry.write().await.remove(&lease_ref);+ if let Some((entry, release_paths, _)) = removed_entry {+ for lock_path in release_paths {+ let _ = refresh_provider+ .remove_token(&lock_path, &entry.lease.owner_id)+ .await;+ }+ removed += 1;+ }+ }+ let active_count = refresh_registry.read().await.entries.len();+ let mut m = refresh_metrics.write().await;+ m.active_lock_count = active_count;+ m.stale_leases_released += removed;+ }+ });++ Self {+ resolver: LockPathResolver::new(fs),+ provider,+ lease_registry: registry,+ config,+ metrics,+ }+ }++ /// Build one release error when the provider reports the token changed underneath us.+ fn release_changed_error(lock_path: &str) -> PathLockError {+ PathLockError::Io(format!("lock path '{lock_path}' changed while releasing"))+ }++ /// Current nanosecond timestamp.+ fn now_ns() -> u128 {+ SystemTime::now()+ .duration_since(UNIX_EPOCH)+ .unwrap_or_default()+ .as_nanos()+ }++ /// Generate a new UUIDv4 owner_id.+ fn new_owner_id() -> String {+ Uuid::new_v4().to_string()+ }++ /// Normalize, deduplicate, and sort requests with Tree taking precedence over Exact.+ fn normalize_requests(requests: &[PathLockRequest]) -> Vec<PathLockRequest> {+ let mut by_path: HashMap<String, PathLockKind> = HashMap::new();+ for request in requests {+ let trimmed = request.path.trim_end_matches('/');+ let path = if trimmed.is_empty() {+ "/".to_string()+ } else {+ trimmed.to_string()+ };+ by_path+ .entry(path)+ .and_modify(|kind| {+ if request.kind == PathLockKind::Tree {+ *kind = PathLockKind::Tree;+ }+ })+ .or_insert(request.kind);+ }++ let mut normalized: Vec<PathLockRequest> = by_path+ .into_iter()+ .map(|(path, kind)| PathLockRequest { path, kind })+ .collect();+ normalized.sort_by(|a, b| {+ a.path+ .len()+ .cmp(&b.path.len())+ .then_with(|| a.path.cmp(&b.path))+ });+ normalized+ }++ /// Check if a token is stale based on config.+ fn is_stale(&self, token: &LockToken, now_ns: u128) -> bool {+ let expire_ns = (self.config.lock_expire_secs * 1_000_000_000.0) as u128;+ now_ns.saturating_sub(token.time_ns) > expire_ns+ }++ /// Resolve a trusted reentrant owner from an active local lease capability.+ async fn resolve_owner_id(+ &self,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<String> {+ match owner_capability {+ Some((lease_ref, ownership_ref)) => self+ .get_owned_lease_by_capability(lease_ref, ownership_ref)+ .await+ .map(|lease| lease.lease.owner_id)+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "owned lease capability does not match ref '{lease_ref}'"+ ))+ }),+ None => Ok(Self::new_owner_id()),+ }+ }++ // ── Public API ──++ /// Acquire an exact lock on a single path.+ pub async fn acquire_exact(+ &self,+ path: &str,+ timeout: Duration,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<OwnedPathLockLease> {+ let request = PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Exact,+ };+ self.acquire_batch(&[request], timeout, owner_capability)+ .await+ }++ /// Acquire a tree lock on a single path.+ pub async fn acquire_tree(+ &self,+ path: &str,+ timeout: Duration,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<OwnedPathLockLease> {+ let request = PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Tree,+ };+ self.acquire_batch(&[request], timeout, owner_capability)+ .await+ }++ /// Acquire exact locks on multiple paths.+ pub async fn acquire_exact_batch(+ &self,+ paths: &[String],+ timeout: Duration,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<OwnedPathLockLease> {+ let requests: Vec<PathLockRequest> = paths+ .iter()+ .map(|p| PathLockRequest {+ path: p.clone(),+ kind: PathLockKind::Exact,+ })+ .collect();+ self.acquire_batch(&requests, timeout, owner_capability)+ .await+ }++ /// Acquire tree locks on multiple paths.+ pub async fn acquire_tree_batch(+ &self,+ paths: &[String],+ timeout: Duration,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<OwnedPathLockLease> {+ let requests: Vec<PathLockRequest> = paths+ .iter()+ .map(|p| PathLockRequest {+ path: p.clone(),+ kind: PathLockKind::Tree,+ })+ .collect();+ self.acquire_batch(&requests, timeout, owner_capability)+ .await+ }++ /// Acquire a mixed batch of exact and tree locks.+ pub async fn acquire_exact_tree_batch(+ &self,+ exact_paths: &[String],+ tree_paths: &[String],+ timeout: Duration,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<OwnedPathLockLease> {+ let mut requests: Vec<PathLockRequest> = exact_paths+ .iter()+ .map(|p| PathLockRequest {+ path: p.clone(),+ kind: PathLockKind::Exact,+ })+ .collect();+ requests.extend(tree_paths.iter().map(|p| PathLockRequest {+ path: p.clone(),+ kind: PathLockKind::Tree,+ }));+ self.acquire_batch(&requests, timeout, owner_capability)+ .await+ }++ /// Acquire a batch of locks with all-or-nothing semantics.+ ///+ /// Requests are sorted deterministically by `(len(path), path)` to avoid deadlocks.+ pub async fn acquire_batch(+ &self,+ requests: &[PathLockRequest],+ timeout: Duration,+ owner_capability: Option<(&str, &str)>,+ ) -> PathLockResult<OwnedPathLockLease> {+ if requests.is_empty() {+ return Err(PathLockError::InvalidRequest(+ "lock request batch must not be empty".to_string(),+ ));+ }+ let sorted = Self::normalize_requests(requests);++ let owner_id = self.resolve_owner_id(owner_capability).await?;++ let start = Instant::now();+ let mut acquired_lock_paths: Vec<(String, AcquisitionChange)> = Vec::new();+ let mut is_waiting = false;++ loop {+ let mut conflict: Option<PathLockError> = None;+ let mut exact_resolutions: HashMap<String, ResolvedExactPaths> = HashMap::new();++ for req in &sorted {+ match req.kind {+ PathLockKind::Exact => {+ // Check ancestor tree locks — a tree lock on an ancestor+ // blocks any exact lock on a descendant.+ if let Err(e) = self.check_ancestor_tree_locks(&req.path, &owner_id).await {+ conflict = Some(e);+ break;+ }+ let resolved = self+ .resolver+ .resolve_exact_paths(&req.path)+ .await?;+ if let Err(e) = self+ .check_lock_paths(&resolved.conflict_paths, &owner_id)+ .await+ {+ conflict = Some(e);+ break;+ }+ let lock_path = resolved.acquire_lock_path.clone();+ exact_resolutions.insert(req.path.clone(), resolved);+ if let Err(e) = self.ensure_lock_dir(&lock_path).await {+ conflict = Some(PathLockError::Io(format!(+ "failed to create lock dir: {e}"+ )));+ break;+ }+ match self+ .try_acquire_one(&lock_path, &owner_id, PathLockKind::Exact)+ .await+ {+ Ok(change) => acquired_lock_paths.push((lock_path, change)),+ Err(e) => {+ conflict = Some(e);+ break;+ }+ }+ }+ PathLockKind::Tree => {+ let lock_path = self.resolver.resolve_tree_lock_path(&req.path).await?;+ // Check conflicts before creating directories so+ // failed requests don't leave empty dirs behind.+ if let Err(e) = self.check_ancestor_tree_locks(&req.path, &owner_id).await {+ conflict = Some(e);+ break;+ }+ let exact_candidates = self+ .resolver+ .resolve_exact_conflict_paths(&req.path)+ .await?;+ if let Err(e) =+ self.check_lock_paths(&exact_candidates, &owner_id).await+ {+ conflict = Some(e);+ break;+ }+ if let Err(e) = self.check_descendant_locks(&req.path, &owner_id).await {+ conflict = Some(e);+ break;+ }+ if let Err(e) = self.ensure_lock_dir(&lock_path).await {+ conflict = Some(PathLockError::Io(format!(+ "failed to create lock dir: {e}"+ )));+ break;+ }+ match self+ .try_acquire_one(&lock_path, &owner_id, PathLockKind::Tree)+ .await+ {+ Ok(change) => acquired_lock_paths.push((lock_path, change)),+ Err(e) => {+ conflict = Some(e);+ break;+ }+ }+ }+ }+ if conflict.is_some() {+ break;+ }+ }++ if let Some(err) = conflict {+ // Rollback all acquired locks.+ self.rollback_acquisitions(&acquired_lock_paths, &owner_id)+ .await?;+ acquired_lock_paths.clear();++ if !matches!(err, PathLockError::Conflict { .. }) {+ if is_waiting {+ let mut metrics = self.metrics.write().await;+ metrics.waiting_lock_count = metrics.waiting_lock_count.saturating_sub(1);+ }+ return Err(err);+ }++ // Track conflict and waiting metrics.+ {+ let mut metrics = self.metrics.write().await;+ if !is_waiting {+ is_waiting = true;+ metrics.waiting_lock_count += 1;+ }+ if let PathLockError::Conflict {+ ref lock_path,+ ref owner,+ kind,+ } = &err+ {+ metrics.record_conflict(PathLockConflict {+ lock_path: lock_path.clone(),+ conflicting_owner: owner.clone(),+ conflicting_kind: *kind,+ });+ }+ }++ // Check timeout.+ if start.elapsed() >= timeout {+ if is_waiting {+ let mut m = self.metrics.write().await;+ m.waiting_lock_count = m.waiting_lock_count.saturating_sub(1);+ }+ return Err(PathLockError::Timeout {+ elapsed_ms: start.elapsed().as_millis() as u64,+ });+ }++ // Try stale cleanup on the conflicting lock, then retry.+ if let PathLockError::Conflict { ref lock_path, .. } = &err {+ if let Some(token) = self.provider.read_token(lock_path).await? {+ let now_ns = Self::now_ns();+ if self.is_stale(&token, now_ns) {+ if self+ .provider+ .remove_token(lock_path, &token.owner_id)+ .await?+ {+ self.metrics.write().await.stale_tokens_removed += 1;+ }+ }+ }+ }++ tokio::time::sleep(Duration::from_millis(50)).await;+ continue;+ }++ // Post-conflict check: after writing all tokens, re-verify no+ // conflicting lock appeared in the TOCTOU window between pre-check+ // and token write.+ let mut post_conflict: Option<PathLockError> = None;+ for req in &sorted {+ match req.kind {+ PathLockKind::Exact => {+ if let Err(e) =+ self.check_ancestor_tree_locks(&req.path, &owner_id).await+ {+ post_conflict = Some(e);+ break;+ }+ let resolved = exact_resolutions.get(&req.path).ok_or_else(|| {+ PathLockError::Io(format!(+ "missing cached exact resolution for '{}'",+ req.path+ ))+ })?;+ if let Err(e) = self+ .check_lock_paths(&resolved.conflict_paths, &owner_id)+ .await+ {+ post_conflict = Some(e);+ break;+ }+ }+ PathLockKind::Tree => {+ if let Err(e) =+ self.check_ancestor_tree_locks(&req.path, &owner_id).await+ {+ post_conflict = Some(e);+ break;+ }+ let exact_candidates = self+ .resolver+ .resolve_exact_conflict_paths(&req.path)+ .await?;+ if let Err(e) =+ self.check_lock_paths(&exact_candidates, &owner_id).await+ {+ post_conflict = Some(e);+ break;+ }+ if let Err(e) =+ self.check_descendant_locks(&req.path, &owner_id).await+ {+ post_conflict = Some(e);+ break;+ }+ }+ }+ }++ if let Some(err) = post_conflict {+ // Another process slipped in — rollback and retry.+ self.rollback_acquisitions(&acquired_lock_paths, &owner_id)+ .await?;+ acquired_lock_paths.clear();++ if !matches!(err, PathLockError::Conflict { .. }) {+ if is_waiting {+ let mut metrics = self.metrics.write().await;+ metrics.waiting_lock_count = metrics.waiting_lock_count.saturating_sub(1);+ }+ return Err(err);+ }++ {+ let mut metrics = self.metrics.write().await;+ if !is_waiting {+ is_waiting = true;+ metrics.waiting_lock_count += 1;+ }+ if let PathLockError::Conflict {+ ref lock_path,+ ref owner,+ kind,+ } = &err+ {+ metrics.record_conflict(PathLockConflict {+ lock_path: lock_path.clone(),+ conflicting_owner: owner.clone(),+ conflicting_kind: *kind,+ });+ }+ }++ if start.elapsed() >= timeout {+ if is_waiting {+ let mut m = self.metrics.write().await;+ m.waiting_lock_count = m.waiting_lock_count.saturating_sub(1);+ }+ return Err(PathLockError::Timeout {+ elapsed_ms: start.elapsed().as_millis() as u64,+ });+ }++ tokio::time::sleep(Duration::from_millis(50)).await;+ continue;+ }++ // All acquired and post-verified successfully.+ let lease = PathLockLease {+ lease_ref: Self::new_owner_id(),+ owner_id: owner_id.clone(),+ lock_paths: acquired_lock_paths+ .into_iter()+ .map(|(lock_path, _)| lock_path)+ .collect(),+ covered_paths: sorted.clone(),+ };+ let ownership_ref = Self::new_owner_id();+ self.lease_registry+ .write()+ .await+ .insert(lease.clone(), ownership_ref.clone());++ let active_count = self.lease_registry.read().await.entries.len();+ let mut metrics = self.metrics.write().await;+ metrics.active_lock_count = active_count;+ metrics.wait_duration_ms += start.elapsed().as_millis() as u64;+ if is_waiting {+ metrics.waiting_lock_count = metrics.waiting_lock_count.saturating_sub(1);+ }++ return Ok(OwnedPathLockLease {+ lease,+ ownership_ref,+ });+ }+ }++ /// Roll back token changes made by one incomplete batch acquisition.+ async fn rollback_acquisitions(+ &self,+ acquired_lock_paths: &[(String, AcquisitionChange)],+ owner_id: &str,+ ) -> PathLockResult<()> {+ for (lock_path, change) in acquired_lock_paths.iter().rev() {+ match change {+ AcquisitionChange::Created => {+ self.provider.remove_token(lock_path, owner_id).await?;+ }+ AcquisitionChange::Reentrant => {}+ AcquisitionChange::Upgraded {+ previous,+ replacement,+ } => {+ if !self+ .provider+ .compare_and_write_token(lock_path, replacement, previous)+ .await?+ {+ return Err(PathLockError::Io(format!(+ "failed to roll back token upgrade at '{lock_path}'"+ )));+ }+ }+ }+ }+ Ok(())+ }++ /// Try to acquire a single lock path.+ async fn try_acquire_one(+ &self,+ lock_path: &str,+ owner_id: &str,+ kind: PathLockKind,+ ) -> PathLockResult<AcquisitionChange> {+ let now_ns = Self::now_ns();+ let token = LockToken {+ owner_id: owner_id.to_string(),+ time_ns: now_ns,+ lock_type: kind,+ };++ // Check existing token.+ if let Some(existing) = self.provider.read_token(lock_path).await? {+ if existing.owner_id == owner_id {+ if existing.lock_type == PathLockKind::Exact && kind == PathLockKind::Tree {+ if self+ .provider+ .compare_and_write_token(lock_path, &existing, &token)+ .await?+ {+ return Ok(AcquisitionChange::Upgraded {+ previous: existing,+ replacement: token,+ });+ }+ return Err(PathLockError::Conflict {+ lock_path: lock_path.to_string(),+ owner: owner_id.to_string(),+ kind: existing.lock_type,+ });+ }+ return Ok(AcquisitionChange::Reentrant);+ }+ if !self.is_stale(&existing, now_ns) {+ return Err(PathLockError::Conflict {+ lock_path: lock_path.to_string(),+ owner: existing.owner_id,+ kind: existing.lock_type,+ });+ }+ // Stale — remove it.+ let _ = self.provider.remove_token(lock_path, &existing.owner_id).await;+ }++ self.provider.try_create_token(lock_path, &token).await?;+ Ok(AcquisitionChange::Created)+ }++ /// Check concrete lock-file paths for a live token owned by another owner.+ async fn check_lock_paths(+ &self,+ lock_paths: &[String],+ owner_id: &str,+ ) -> PathLockResult<()> {+ let now_ns = Self::now_ns();+ for lock_path in lock_paths {+ if let Some(token) = self.provider.read_token(lock_path).await? {+ if token.owner_id != owner_id && !self.is_stale(&token, now_ns) {+ return Err(PathLockError::Conflict {+ lock_path: lock_path.clone(),+ owner: token.owner_id,+ kind: token.lock_type,+ });+ }+ }+ }+ Ok(())+ }++ /// Check ancestor directories for tree locks that would conflict.+ async fn check_ancestor_tree_locks(+ &self,+ path: &str,+ owner_id: &str,+ ) -> PathLockResult<()> {+ let mut current = path.to_string();+ let now_ns = Self::now_ns();++ loop {+ let parent = match current.rsplit_once('/') {+ Some((p, _)) if !p.is_empty() => p.to_string(),+ Some(_) if current != "/" => "/".to_string(),+ _ => break,+ };++ let ancestor_lock = if parent == "/" {+ format!("/{}", PATH_LOCK_FILE)+ } else {+ format!("{}/{}", parent, PATH_LOCK_FILE)+ };+ if let Some(token) = self.provider.read_token(&ancestor_lock).await? {+ // Only Tree locks propagate to descendants; an Exact lock on+ // /a must not block /a/b.+ if token.lock_type == PathLockKind::Tree+ && token.owner_id != owner_id+ && !self.is_stale(&token, now_ns)+ {+ return Err(PathLockError::Conflict {+ lock_path: ancestor_lock,+ owner: token.owner_id,+ kind: token.lock_type,+ });+ }+ }++ current = parent;+ }+ Ok(())+ }++ /// Check for descendant locks that would conflict with a tree lock.+ async fn check_descendant_locks(+ &self,+ path: &str,+ owner_id: &str,+ ) -> PathLockResult<()> {+ let scan_start = Instant::now();+ let descendants = self.provider.scan_descendant_locks(path).await?;+ let now_ns = Self::now_ns();++ let mut metrics = self.metrics.write().await;+ metrics.descendant_scan_count += 1;+ metrics.descendant_scan_duration_ms += scan_start.elapsed().as_millis() as u64;+ drop(metrics);++ for lp in descendants {+ if let Some(token) = self.provider.read_token(&lp).await? {+ if token.owner_id != owner_id && !self.is_stale(&token, now_ns) {+ return Err(PathLockError::Conflict {+ lock_path: lp,+ owner: token.owner_id,+ kind: token.lock_type,+ });+ }+ }+ }+ Ok(())+ }++ /// Ensure the parent directory of a lock path exists.+ async fn ensure_lock_dir(&self, lock_path: &str) -> PathLockResult<()> {+ if let Some(parent_end) = lock_path.rfind('/') {+ let parent = &lock_path[..parent_end];+ if parent.is_empty() || parent == "/" {+ return Ok(());+ }+ // Walk up creating missing ancestors.+ let mut missing: Vec<String> = Vec::new();+ let mut current = parent.to_string();+ loop {+ match self.resolver.fs.stat(¤t).await {+ Ok(info) if info.is_dir => break,+ _ => {+ missing.push(current.clone());+ match current.rsplit_once('/') {+ Some((p, _)) if !p.is_empty() => current = p.to_string(),+ _ => break,+ }+ }+ }+ }+ for dir in missing.into_iter().rev() {+ self.resolver.fs.mkdir(&dir, 0o755).await.map_err(|e| {+ PathLockError::Io(format!("failed to create lock dir '{dir}': {e}"))+ })?;+ }+ }+ Ok(())+ }++ /// Refresh an owned lease. Returns "refreshed", "lost", or "failed".+ pub async fn refresh(&self, lease: &OwnedPathLockLease) -> PathLockResult<String> {+ let now_ns = Self::now_ns();+ let mut all_ok = true;+ let mut any_ok = false;++ for lp in &lease.lease.lock_paths {+ match self+ .provider+ .refresh_token(lp, &lease.lease.owner_id, now_ns)+ .await+ {+ Ok(true) => any_ok = true,+ Ok(false) => all_ok = false,+ Err(_) => all_ok = false,+ }+ }++ if any_ok {+ self.lease_registry+ .write()+ .await+ .touch(&lease.lease.lease_ref);+ }++ if all_ok && any_ok {+ Ok("refreshed".to_string())+ } else if any_ok {+ Ok("lost".to_string())+ } else {+ Ok("failed".to_string())+ }+ }++ /// Release an owned lease.+ pub async fn release(&self, lease: &OwnedPathLockLease) -> PathLockResult<()> {+ let removed = self+ .lease_registry+ .write()+ .await+ .remove(&lease.lease.lease_ref);+ if let Some((mut entry, release_paths, downgrade_paths)) = removed {+ let mut failed_paths = Vec::new();+ let mut first_error = None;+ for lock_path in release_paths {+ match self+ .provider+ .remove_token(&lock_path, &entry.lease.owner_id)+ .await+ {+ Ok(true) => {}+ Ok(false) => {+ failed_paths.push(lock_path.clone());+ if first_error.is_none() {+ first_error = Some(Self::release_changed_error(&lock_path));+ }+ }+ Err(error) => {+ failed_paths.push(lock_path);+ if first_error.is_none() {+ first_error = Some(error);+ }+ }+ }+ }+ for lock_path in downgrade_paths {+ if let Err(error) = self+ .downgrade_token_to_exact(&lock_path, &entry.lease.owner_id)+ .await+ {+ failed_paths.push(lock_path);+ if first_error.is_none() {+ first_error = Some(error);+ }+ }+ }+ if let Some(error) = first_error {+ let failed: HashSet<&str> = failed_paths.iter().map(String::as_str).collect();+ entry.lease.covered_paths = entry+ .lease+ .lock_paths+ .iter()+ .zip(&entry.lease.covered_paths)+ .filter(|(path, _)| failed.contains(path.as_str()))+ .map(|(_, request)| request.clone())+ .collect();+ entry.lease.lock_paths = failed_paths;+ entry+ .lock_kinds+ .retain(|path, _| entry.lease.lock_paths.contains(path));+ error!(+ lease_ref = %entry.lease.lease_ref,+ owner_id = %entry.lease.owner_id,+ lock_paths = ?entry.lease.lock_paths,+ error = %error,+ "failed to release pathlock lease"+ );+ self.lease_registry.write().await.restore(entry);+ return Err(error);+ }+ }+ let active_count = self.lease_registry.read().await.entries.len();+ let mut metrics = self.metrics.write().await;+ metrics.active_lock_count = active_count;+ Ok(())+ }++ /// Release selected lock paths from an owned lease.+ pub async fn release_selected(+ &self,+ lease: &OwnedPathLockLease,+ lock_paths: &[String],+ ) -> PathLockResult<()> {+ let removed = self+ .lease_registry+ .write()+ .await+ .remove_selected(&lease.lease.lease_ref, lock_paths);+ if let Some((mut entry, owner_id, release_paths, downgrade_paths)) = removed {+ let mut failed_paths = Vec::new();+ let mut first_error = None;+ for lock_path in release_paths {+ match self.provider.remove_token(&lock_path, &owner_id).await {+ Ok(true) => {}+ Ok(false) => {+ failed_paths.push(lock_path.clone());+ if first_error.is_none() {+ first_error = Some(Self::release_changed_error(&lock_path));+ }+ }+ Err(error) => {+ failed_paths.push(lock_path);+ if first_error.is_none() {+ first_error = Some(error);+ }+ }+ }+ }+ for lock_path in downgrade_paths {+ if let Err(error) = self.downgrade_token_to_exact(&lock_path, &owner_id).await {+ failed_paths.push(lock_path);+ if first_error.is_none() {+ first_error = Some(error);+ }+ }+ }+ if let Some(error) = first_error {+ let selected: HashSet<&str> = lock_paths.iter().map(String::as_str).collect();+ let failed: HashSet<&str> = failed_paths.iter().map(String::as_str).collect();+ let retained: Vec<(String, PathLockRequest)> = entry+ .lease+ .lock_paths+ .iter()+ .zip(&entry.lease.covered_paths)+ .filter(|(path, _)| {+ !selected.contains(path.as_str()) || failed.contains(path.as_str())+ })+ .map(|(path, request)| (path.clone(), request.clone()))+ .collect();+ entry.lease.lock_paths =+ retained.iter().map(|(path, _)| path.clone()).collect();+ entry.lease.covered_paths =+ retained.into_iter().map(|(_, request)| request).collect();+ entry+ .lock_kinds+ .retain(|path, _| entry.lease.lock_paths.contains(path));+ self.lease_registry.write().await.restore(entry);+ return Err(error);+ }+ }+ let active_count = self.lease_registry.read().await.entries.len();+ self.metrics.write().await.active_lock_count = active_count;+ Ok(())+ }++ /// Atomically reduce one same-owner Tree token to Exact.+ async fn downgrade_token_to_exact(+ &self,+ lock_path: &str,+ owner_id: &str,+ ) -> PathLockResult<()> {+ loop {+ let Some(current) = self.provider.read_token(lock_path).await? else {+ return Ok(());+ };+ if current.owner_id != owner_id {+ return Err(PathLockError::Conflict {+ lock_path: lock_path.to_string(),+ owner: current.owner_id,+ kind: current.lock_type,+ });+ }+ if current.lock_type == PathLockKind::Exact {+ return Ok(());+ }+ let replacement = LockToken {+ owner_id: current.owner_id.clone(),+ time_ns: current.time_ns,+ lock_type: PathLockKind::Exact,+ };+ if self+ .provider+ .compare_and_write_token(lock_path, ¤t, &replacement)+ .await?+ {+ return Ok(());+ }+ }+ }++ /// Create a borrowed view of an owned lease.+ pub fn as_borrowed(&self, lease: &OwnedPathLockLease) -> BorrowedPathLockLease {+ BorrowedPathLockLease {+ lease: lease.lease.clone(),+ }+ }++ /// Export a handoff ref from an owned lease.+ pub fn to_handoff(&self, lease: &OwnedPathLockLease) -> PathLockHandoffRef {+ PathLockHandoffRef {+ owner_id: lease.lease.owner_id.clone(),+ lock_paths: lease.lease.lock_paths.clone(),+ covered_paths: lease.lease.covered_paths.clone(),+ }+ }++ /// Mark an owned lease as handed off (local lifecycle ends).+ pub async fn handoff(&self, lease: &OwnedPathLockLease) -> PathLockResult<()> {+ self.lease_registry+ .write()+ .await+ .remove(&lease.lease.lease_ref);+ let active_count = self.lease_registry.read().await.entries.len();+ self.metrics.write().await.active_lock_count = active_count;+ Ok(())+ }++ /// Adopt a handoff ref, returning a new owned lease.+ pub async fn adopt(+ &self,+ handoff: &PathLockHandoffRef,+ ) -> PathLockResult<OwnedPathLockLease> {+ if handoff.owner_id.is_empty() || handoff.lock_paths.is_empty() {+ return Err(PathLockError::InvalidRequest(+ "handoff owner_id and lock_paths must not be empty".to_string(),+ ));+ }+ let legacy_handoff = handoff.covered_paths.is_empty();+ if !legacy_handoff && handoff.covered_paths.len() != handoff.lock_paths.len() {+ return Err(PathLockError::InvalidRequest(+ "handoff lock_paths and covered_paths must have equal lengths".to_string(),+ ));+ }+ let now_ns = Self::now_ns();++ // ponytail: legacy durable handoffs only persisted owner_id/handle_id + lock_paths.+ // We validate live ownership/kind by the lock file path itself and keep covered_paths empty.+ // Upgrade path: once old queue payloads are drained, remove this branch and require covered_paths.+ for (index, lp) in handoff.lock_paths.iter().enumerate() {+ let expected_kind = if legacy_handoff {+ let file_name = lp.rsplit('/').next().unwrap_or("");+ if lp == &format!("/{}", PATH_LOCK_FILE) || lp.ends_with(&format!("/{}", PATH_LOCK_FILE)) {+ PathLockKind::Tree+ } else if file_name.starts_with(EXACT_LOCK_FILE_PREFIX) {+ PathLockKind::Exact+ } else {+ return Err(PathLockError::InvalidRequest(format!(+ "legacy handoff lock path '{lp}' is not a supported lock file"+ )));+ }+ } else {+ let request = &handoff.covered_paths[index];+ let expected_paths = match request.kind {+ PathLockKind::Exact => {+ self.resolver.resolve_exact_conflict_paths(&request.path).await?+ }+ PathLockKind::Tree => {+ vec![self.resolver.resolve_tree_lock_path(&request.path).await?]+ }+ };+ if !expected_paths.contains(lp) {+ return Err(PathLockError::InvalidRequest(format!(+ "handoff coverage '{}' does not map to lock path '{lp}'",+ request.path+ )));+ }+ request.kind+ };+ match self.provider.read_token(lp).await? {+ Some(token)+ if token.owner_id == handoff.owner_id && token.lock_type == expected_kind =>+ {+ // Still valid — refresh the timestamp.+ match self+ .provider+ .refresh_token(lp, &handoff.owner_id, now_ns)+ .await+ {+ Ok(true) => {}+ Ok(false) => {+ return Err(PathLockError::HandoffFailed(format!(+ "lock path '{lp}' changed while adopting owner '{}'",+ handoff.owner_id+ )));+ }+ Err(error) => return Err(error),+ }+ }+ _ => {+ return Err(PathLockError::HandoffFailed(format!(+ "lock path '{lp}' is no longer owned by '{}'",+ handoff.owner_id+ )));+ }+ }+ }++ let lease = PathLockLease {+ lease_ref: Self::new_owner_id(),+ owner_id: handoff.owner_id.clone(),+ lock_paths: handoff.lock_paths.clone(),+ covered_paths: handoff.covered_paths.clone(),+ };+ let ownership_ref = Self::new_owner_id();+ self.lease_registry+ .write()+ .await+ .insert(lease.clone(), ownership_ref.clone());++ let active_count = self.lease_registry.read().await.entries.len();+ self.metrics.write().await.active_lock_count = active_count;++ Ok(OwnedPathLockLease {+ lease,+ ownership_ref,+ })+ }++ /// Check if a path is locked (for observability).+ pub async fn is_locked(&self, path: &str, ignore_stale: bool) -> PathLockResult<bool> {+ let now_ns = Self::now_ns();++ // Check own .path.ovlock.+ let dir_lock = format!("{}/{}", path.trim_end_matches('/'), PATH_LOCK_FILE);+ if let Ok(Some(token)) = self.provider.read_token(&dir_lock).await {+ if !ignore_stale || !self.is_stale(&token, now_ns) {+ return Ok(true);+ }+ }++ // Check exact sidecar.+ let exact_paths = self.resolver.resolve_exact_conflict_paths(path).await?;+ for lp in &exact_paths {+ if let Ok(Some(token)) = self.provider.read_token(lp).await {+ if !ignore_stale || !self.is_stale(&token, now_ns) {+ return Ok(true);+ }+ }+ }++ // Check ancestor tree locks.+ let mut current = path.to_string();+ loop {+ let parent = match current.rsplit_once('/') {+ Some((p, _)) if !p.is_empty() => p.to_string(),+ Some(_) if current != "/" => "/".to_string(),+ _ => break,+ };+ let ancestor_lock = if parent == "/" {+ format!("/{}", PATH_LOCK_FILE)+ } else {+ format!("{}/{}", parent, PATH_LOCK_FILE)+ };+ if let Ok(Some(token)) = self.provider.read_token(&ancestor_lock).await {+ // Only Tree locks propagate to descendants.+ if token.lock_type == PathLockKind::Tree+ && (!ignore_stale || !self.is_stale(&token, now_ns))+ {+ return Ok(true);+ }+ }+ current = parent;+ }++ Ok(false)+ }++ /// Return an observability snapshot.+ pub async fn observe(&self) -> PathLockObserveSnapshot {+ let metrics = self.metrics.read().await.clone();+ PathLockObserveSnapshot {+ active_locks: metrics.active_lock_count,+ waiting_locks: metrics.waiting_lock_count,+ stale_locks_removed: metrics.stale_tokens_removed,+ conflicts: metrics.recent_conflicts,+ }+ }++ /// Look up an owned lease by owner_id for cross-FFI lease operations.+ pub async fn get_owned_lease(&self, owner_id: &str) -> Option<OwnedPathLockLease> {+ let registry = self.lease_registry.read().await;+ registry.get_by_owner(owner_id).map(|entry| OwnedPathLockLease {+ lease: entry.lease.clone(),+ ownership_ref: entry.ownership_ref.clone(),+ })+ }++ /// Look up an owned lease by opaque lease_ref for cross-FFI lease operations.+ pub async fn get_owned_lease_by_ref(&self, lease_ref: &str) -> Option<OwnedPathLockLease> {+ let registry = self.lease_registry.read().await;+ registry.get_by_ref(lease_ref).map(|entry| OwnedPathLockLease {+ lease: entry.lease.clone(),+ ownership_ref: entry.ownership_ref.clone(),+ })+ }++ /// Look up an owned lease only when its lifecycle capability matches.+ pub async fn get_owned_lease_by_capability(+ &self,+ lease_ref: &str,+ ownership_ref: &str,+ ) -> Option<OwnedPathLockLease> {+ let registry = self.lease_registry.read().await;+ registry+ .get_by_ref(lease_ref)+ .filter(|entry| entry.ownership_ref == ownership_ref)+ .map(|entry| OwnedPathLockLease {+ lease: entry.lease.clone(),+ ownership_ref: entry.ownership_ref.clone(),+ })+ }++ /// Validate that an opaque lease reference exists and covers all requested paths.+ pub async fn require_covered_lease_ref(+ &self,+ lease_ref: &str,+ requests: &[PathLockRequest],+ ) -> PathLockResult<()> {+ let registry = self.lease_registry.read().await;+ let entry = registry.get_by_ref(lease_ref).ok_or_else(|| {+ PathLockError::InvalidRequest(format!("unknown pathlock lease ref '{lease_ref}'"))+ })?;+ if requests.iter().all(|request| entry.lease.covers(request)) {+ Ok(())+ } else {+ Err(PathLockError::InvalidRequest(format!(+ "pathlock lease ref '{lease_ref}' does not cover the requested operation"+ )))+ }+ }++ /// Resolve automatic PathLock behavior from the current immutable FS context.+ pub async fn resolve_auto_pathlock_action(+ &self,+ requests: &[PathLockRequest],+ ) -> PathLockResult<AutoPathLockAction> {+ let view = FsContextView::current();+ if view.disable_auto_pathlock() {+ return Ok(AutoPathLockAction::Disabled);+ }+ let Some(lease_ref) = view.pathlock_lease_ref() else {+ return Ok(AutoPathLockAction::Acquire);+ };+ let lease = self+ .get_owned_lease_by_ref(lease_ref)+ .await+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "unknown pathlock lease ref '{lease_ref}'"+ ))+ })?;+ if requests.iter().all(|request| lease.lease.covers(request)) {+ Ok(AutoPathLockAction::Covered(lease))+ } else {+ Err(PathLockError::InvalidRequest(format!(+ "pathlock lease ref '{lease_ref}' does not cover the requested operation"+ )))+ }+ }++ /// Return a reference to the metrics for external reading.+ pub async fn metrics_snapshot(&self) -> LockMetrics {+ self.metrics.read().await.clone()+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use async_trait::async_trait;+ use crate::plugins::memfs::MemFileSystem;+ use std::sync::atomic::{AtomicBool, Ordering};++ struct FailNextRemoveProvider {+ inner: crate::lock::provider::MemoryPathLockProvider,+ fail_next_read: AtomicBool,+ fail_next_remove: AtomicBool,+ return_false_next_remove: AtomicBool,+ }++ impl FailNextRemoveProvider {+ /// Build a memory provider whose next token read fails.+ fn with_read_failure() -> Self {+ Self {+ inner: crate::lock::provider::MemoryPathLockProvider::new(),+ fail_next_read: AtomicBool::new(true),+ fail_next_remove: AtomicBool::new(false),+ return_false_next_remove: AtomicBool::new(false),+ }+ }++ }++ #[async_trait]+ impl PathLockProvider for FailNextRemoveProvider {+ fn name(&self) -> &'static str {+ "fail-next-remove"+ }++ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {+ if self.fail_next_read.swap(false, Ordering::SeqCst) {+ return Err(PathLockError::Io("injected read failure".to_string()));+ }+ self.inner.read_token(lock_path).await+ }++ async fn try_create_token(+ &self,+ lock_path: &str,+ token: &LockToken,+ ) -> PathLockResult<()> {+ self.inner.try_create_token(lock_path, token).await+ }++ async fn compare_and_write_token(+ &self,+ lock_path: &str,+ expected: &LockToken,+ replacement: &LockToken,+ ) -> PathLockResult<bool> {+ self.inner+ .compare_and_write_token(lock_path, expected, replacement)+ .await+ }++ async fn refresh_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ time_ns: u128,+ ) -> PathLockResult<bool> {+ self.inner+ .refresh_token(lock_path, owner_id, time_ns)+ .await+ }++ async fn remove_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ ) -> PathLockResult<bool> {+ if self.return_false_next_remove.swap(false, Ordering::SeqCst) {+ return Ok(false);+ }+ if self.fail_next_remove.swap(false, Ordering::SeqCst) {+ return Err(PathLockError::Io("injected remove failure".to_string()));+ }+ self.inner.remove_token(lock_path, owner_id).await+ }++ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {+ self.inner.scan_descendant_locks(root).await+ }+ }++ /// Build a manager backed by the real in-memory filesystem.+ async fn make_manager() -> PathLockManager {+ make_manager_with_config(PathLockConfig::default()).await+ }++ /// Build a manager with custom lock configuration.+ async fn make_manager_with_config(config: PathLockConfig) -> PathLockManager {+ let fs = Arc::new(MemFileSystem::new());+ fs.mkdir("/data", 0o755).await.unwrap();+ fs.mkdir("/data/sub", 0o755).await.unwrap();+ let provider = Arc::new(crate::lock::provider::MemoryPathLockProvider::new());+ PathLockManager::new(fs, provider, config)+ }++ /// Build a manager and expose its real in-memory filesystem.+ async fn make_manager_with_fs() -> (PathLockManager, Arc<MemFileSystem>) {+ let fs = Arc::new(MemFileSystem::new());+ fs.mkdir("/data", 0o755).await.unwrap();+ let provider = Arc::new(crate::lock::provider::MemoryPathLockProvider::new());+ (+ PathLockManager::new(fs.clone(), provider, PathLockConfig::default()),+ fs,+ )+ }++ #[tokio::test]+ async fn acquire_exact_reentrant_requires_local_owned_capability() {+ let mgr = make_manager().await;+ let lease1 = mgr+ .acquire_exact("/data/file.txt", Duration::from_secs(1), None)+ .await+ .unwrap();+ let capability = (+ lease1.lease.lease_ref.as_str(),+ lease1.ownership_ref.as_str(),+ );+ let lease2 = mgr+ .acquire_exact("/data/file.txt", Duration::from_secs(1), Some(capability))+ .await+ .unwrap();+ assert_eq!(lease1.lease.lock_paths, lease2.lease.lock_paths);++ mgr.release(&lease2).await.unwrap();+ assert!(matches!(+ mgr.acquire_exact("/data/file.txt", Duration::ZERO, None).await,+ Err(PathLockError::Timeout { .. })+ ));++ mgr.release(&lease1).await.unwrap();+ assert!(mgr+ .acquire_exact("/data/file.txt", Duration::ZERO, None)+ .await+ .is_ok());+ }++ /// Keep coverage for paths that remain after a partial lease release.+ #[tokio::test]+ async fn release_selected_preserves_remaining_coverage() {+ let mgr = make_manager().await;+ let lease = mgr+ .acquire_exact_batch(+ &["/data/a.txt".to_string(), "/data/b.txt".to_string()],+ Duration::ZERO,+ None,+ )+ .await+ .unwrap();+ let released_lock_path = lease.lease.lock_paths[0].clone();++ mgr.release_selected(&lease, &[released_lock_path])+ .await+ .unwrap();++ assert!(mgr+ .require_covered_lease_ref(+ &lease.lease.lease_ref,+ &[PathLockRequest {+ path: "/data/b.txt".to_string(),+ kind: PathLockKind::Exact,+ }],+ )+ .await+ .is_ok());+ mgr.release(&lease).await.unwrap();+ }++ #[tokio::test]+ async fn failed_batch_rolls_back_same_owner_tree_upgrade() {+ let mgr = make_manager().await;+ let exact = mgr+ .acquire_exact("/data/sub", Duration::ZERO, None)+ .await+ .unwrap();+ let blocker = mgr+ .acquire_exact("/data/z.txt", Duration::ZERO, None)+ .await+ .unwrap();+ let capability = (+ exact.lease.lease_ref.as_str(),+ exact.ownership_ref.as_str(),+ );++ let result = mgr+ .acquire_batch(+ &[+ PathLockRequest {+ path: "/data/sub".to_string(),+ kind: PathLockKind::Tree,+ },+ PathLockRequest {+ path: "/data/z.txt".to_string(),+ kind: PathLockKind::Exact,+ },+ ],+ Duration::ZERO,+ Some(capability),+ )+ .await;++ assert!(matches!(result, Err(PathLockError::Timeout { .. })));+ let token = mgr+ .provider+ .read_token("/data/sub/.path.ovlock")+ .await+ .unwrap()+ .unwrap();+ assert_eq!(token.lock_type, PathLockKind::Exact);++ mgr.release(&blocker).await.unwrap();+ mgr.release(&exact).await.unwrap();+ }++ #[tokio::test]+ async fn missing_exact_and_same_path_tree_conflict_in_both_orders() {+ let (mgr, _) = make_manager_with_fs().await;+ let exact = mgr+ .acquire_exact("/data/new", Duration::ZERO, None)+ .await+ .unwrap();+ assert!(matches!(+ mgr.acquire_tree("/data/new", Duration::ZERO, None).await,+ Err(PathLockError::Timeout { .. })+ ));+ mgr.release(&exact).await.unwrap();++ let tree = mgr+ .acquire_tree("/data/other", Duration::ZERO, None)+ .await+ .unwrap();+ assert!(matches!(+ mgr.acquire_exact("/data/other", Duration::ZERO, None).await,+ Err(PathLockError::Timeout { .. })+ ));+ mgr.release(&tree).await.unwrap();+ }++ #[tokio::test]+ async fn handoff_and_adopt() {+ let mgr = make_manager().await;+ let lease = mgr+ .acquire_tree("/data/sub", Duration::from_secs(1), None)+ .await+ .unwrap();+ let handoff = mgr.to_handoff(&lease);+ mgr.handoff(&lease).await.unwrap();++ let adopted = mgr.adopt(&handoff).await.unwrap();+ assert_eq!(adopted.lease.owner_id, lease.lease.owner_id);+ assert_eq!(adopted.lease.lock_paths, handoff.lock_paths);+ }++ #[tokio::test]+ async fn opaque_lease_ref_must_cover_requested_path() {+ let mgr = make_manager().await;+ let lease = mgr+ .acquire_tree("/data", Duration::from_secs(1), None)+ .await+ .unwrap();++ assert_ne!(lease.lease.lease_ref, lease.lease.owner_id);+ assert!(mgr+ .require_covered_lease_ref(+ &lease.lease.owner_id,+ &[PathLockRequest {+ path: "/data/sub/file.txt".to_string(),+ kind: PathLockKind::Exact,+ }],+ )+ .await+ .is_err());+ assert!(mgr+ .require_covered_lease_ref(+ &lease.lease.lease_ref,+ &[PathLockRequest {+ path: "/data/sub/file.txt".to_string(),+ kind: PathLockKind::Exact,+ }],+ )+ .await+ .is_ok());+ assert!(mgr+ .require_covered_lease_ref(+ &lease.lease.lease_ref,+ &[PathLockRequest {+ path: "/other/file.txt".to_string(),+ kind: PathLockKind::Exact,+ }],+ )+ .await+ .is_err());+ }++ #[tokio::test]+ async fn handoff_stops_source_refresh_until_adopted() {+ let mgr = make_manager_with_config(PathLockConfig {+ lock_expire_secs: 0.03,+ ..PathLockConfig::default()+ })+ .await;+ let lease = mgr+ .acquire_tree("/data/sub", Duration::from_secs(1), None)+ .await+ .unwrap();+ let lock_path = lease.lease.lock_paths[0].clone();+ mgr.handoff(&lease).await.unwrap();++ let before = mgr+ .provider+ .read_token(&lock_path)+ .await+ .unwrap()+ .unwrap()+ .time_ns;+ tokio::time::sleep(Duration::from_millis(25)).await;++ let after = mgr+ .provider+ .read_token(&lock_path)+ .await+ .unwrap()+ .unwrap()+ .time_ns;+ assert_eq!(after, before);+ assert!(mgr+ .get_owned_lease_by_ref(&lease.lease.lease_ref)+ .await+ .is_none());++ let handoff = mgr.to_handoff(&lease);+ let adopted = mgr.adopt(&handoff).await.unwrap();+ assert_eq!(adopted.lease.owner_id, lease.lease.owner_id);+ }++ #[tokio::test]+ async fn is_locked_detects_root_tree_lock() {+ let mgr = make_manager().await;+ assert!(!mgr.is_locked("/data/file.txt", true).await.unwrap());+ let _root = mgr+ .acquire_tree("/", Duration::ZERO, None)+ .await+ .unwrap();+ assert!(mgr.is_locked("/data/file.txt", true).await.unwrap());+ }++ #[tokio::test]+ async fn provider_io_error_is_not_retried() {+ let fs = Arc::new(MemFileSystem::new());+ fs.mkdir("/data", 0o755).await.unwrap();+ let provider = Arc::new(FailNextRemoveProvider::with_read_failure());+ let mgr = PathLockManager::new(fs, provider, PathLockConfig::default());++ assert!(matches!(+ mgr.acquire_exact("/data/file.txt", Duration::ZERO, None)+ .await,+ Err(PathLockError::Io(message)) if message == "injected read failure"+ ));+ }+}diff --git a/crates/ragfs/src/lock/metrics.rs b/crates/ragfs/src/lock/metrics.rsnew file mode 100644index 000000000..9a60bff9c--- /dev/null+++ b/crates/ragfs/src/lock/metrics.rs@@ -0,0 +1,42 @@+//! Lock observability metrics.++use crate::lock::types::PathLockConflict;++/// Max number of recent conflicts retained for observability.+const MAX_RECENT_CONFLICTS: usize = 32;++/// Runtime metrics collected by `PathLockManager`.+#[derive(Debug, Clone, Default)]+pub struct LockMetrics {+ /// Current number of active (held) locks.+ pub active_lock_count: usize,+ /// Current number of waiting lock requests.+ pub waiting_lock_count: usize,+ /// Cumulative count of stale tokens removed during acquire.+ pub stale_tokens_removed: usize,+ /// Cumulative count of stale leases released by heartbeat.+ pub stale_leases_released: usize,+ /// Cumulative count of stale cleanup failures.+ pub stale_cleanup_failures: usize,+ /// Cumulative count of descendant scan operations.+ pub descendant_scan_count: usize,+ /// Total milliseconds spent in descendant scans.+ pub descendant_scan_duration_ms: u64,+ /// Total milliseconds spent waiting for locks.+ pub wait_duration_ms: u64,+ /// Count of conflicts by type (exact/exact, tree/exact, etc.).+ pub conflict_count: usize,+ /// Recent conflicts for observability (ring buffer).+ pub recent_conflicts: Vec<PathLockConflict>,+}++impl LockMetrics {+ /// Record a conflict, keeping at most `MAX_RECENT_CONFLICTS` entries.+ pub fn record_conflict(&mut self, conflict: PathLockConflict) {+ self.conflict_count += 1;+ if self.recent_conflicts.len() >= MAX_RECENT_CONFLICTS {+ self.recent_conflicts.remove(0);+ }+ self.recent_conflicts.push(conflict);+ }+}diff --git a/crates/ragfs/src/lock/mod.rs b/crates/ragfs/src/lock/mod.rsnew file mode 100644index 000000000..e50e3c9cc--- /dev/null+++ b/crates/ragfs/src/lock/mod.rs@@ -0,0 +1,32 @@+//! PathLock subsystem — native file-system-level locking protocol.+//!+//! This module provides exact-path and tree-path locks backed by lock files+//! (`.path.ovlock` / `.exact.ovlock.*`) on the underlying filesystem.+//!+//! # Architecture+//!+//! - [`PathLockManager`] is the single source of truth for lock semantics.+//! - [`PathLockProvider`] is the storage abstraction (memory or filesystem).+//! - [`PathLockWrappedFS`] is a convenience wrapper that auto-acquires locks+//! for simple file operations.+//! - [`LockPathResolver`] computes lock-file paths.+//! - [`LockTokenCodec`] encodes/decodes lock tokens.++pub mod codec;+pub mod manager;+pub mod metrics;+pub mod provider;+pub mod resolver;+pub mod types;+pub mod wrapper;++pub use codec::LockTokenCodec;+pub use manager::{AutoPathLockAction, PathLockConfig, PathLockManager};+pub use metrics::LockMetrics;+pub use provider::{FilesystemPathLockProvider, MemoryPathLockProvider, PathLockProvider};+pub use resolver::LockPathResolver;+pub use types::{+ BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,+ PathLockKind, PathLockLease, PathLockObserveSnapshot, PathLockRequest, PathLockResult,+};+pub use wrapper::PathLockWrappedFS;diff --git a/crates/ragfs/src/lock/provider.rs b/crates/ragfs/src/lock/provider.rsnew file mode 100644index 000000000..76bbe0396--- /dev/null+++ b/crates/ragfs/src/lock/provider.rs@@ -0,0 +1,338 @@+//! PathLockProvider trait and built-in implementations.+//!+//! The provider is a pure storage abstraction — it does not implement lock semantics+//! (conflict detection, waiting, etc.). Those belong to `PathLockManager`.++use std::collections::HashMap;+use std::sync::Arc;++use async_trait::async_trait;+use tokio::sync::RwLock;++use crate::core::internal_names::is_hidden_runtime_lock_name;+use crate::core::FileSystem;++use super::codec::LockTokenCodec;+use super::types::{LockToken, PathLockError, PathLockResult};++/// Storage abstraction for lock tokens. Only `PathLockManager` should call these methods.+#[async_trait]+pub trait PathLockProvider: Send + Sync {+ /// Human-readable provider name for config/logging/metrics.+ fn name(&self) -> &'static str;++ /// Read the token at `lock_path`, returning `None` if no token exists.+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>>;++ /// Atomically create a token at `lock_path`. Must fail if a token already exists+ /// (unless it is stale and can be cleaned up by the manager).+ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()>;++ /// Atomically replace one exact token value.+ async fn compare_and_write_token(+ &self,+ lock_path: &str,+ expected: &LockToken,+ replacement: &LockToken,+ ) -> PathLockResult<bool>;++ /// Refresh the timestamp of an existing token owned by `owner_id`.+ /// Returns `true` if the token was refreshed, `false` if not found or wrong owner.+ async fn refresh_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ time_ns: u128,+ ) -> PathLockResult<bool>;++ /// Remove the token at `lock_path` if owned by `owner_id`.+ /// Returns `true` if removed, `false` if not found or wrong owner.+ async fn remove_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<bool>;++ /// Scan all descendant lock paths under `root`.+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>>;+}++// ── Memory provider ──++/// In-process lock table backed by a `HashMap`. Single-process only.+pub struct MemoryPathLockProvider {+ tokens: RwLock<HashMap<String, LockToken>>,+}++impl MemoryPathLockProvider {+ /// Create an empty in-memory provider.+ pub fn new() -> Self {+ Self {+ tokens: RwLock::new(HashMap::new()),+ }+ }+}++impl Default for MemoryPathLockProvider {+ fn default() -> Self {+ Self::new()+ }+}++#[async_trait]+impl PathLockProvider for MemoryPathLockProvider {+ fn name(&self) -> &'static str {+ "memory"+ }++ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {+ Ok(self.tokens.read().await.get(lock_path).cloned())+ }++ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {+ let mut tokens = self.tokens.write().await;+ if tokens.contains_key(lock_path) {+ return Err(PathLockError::Conflict {+ lock_path: lock_path.to_string(),+ owner: tokens[lock_path].owner_id.clone(),+ kind: tokens[lock_path].lock_type,+ });+ }+ tokens.insert(lock_path.to_string(), token.clone());+ Ok(())+ }++ async fn compare_and_write_token(+ &self,+ lock_path: &str,+ expected: &LockToken,+ replacement: &LockToken,+ ) -> PathLockResult<bool> {+ let mut tokens = self.tokens.write().await;+ match tokens.get(lock_path) {+ Some(token) if token == expected => {+ tokens.insert(lock_path.to_string(), replacement.clone());+ Ok(true)+ }+ _ => Ok(false),+ }+ }++ async fn refresh_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ time_ns: u128,+ ) -> PathLockResult<bool> {+ let mut tokens = self.tokens.write().await;+ match tokens.get_mut(lock_path) {+ Some(token) if token.owner_id == owner_id => {+ token.time_ns = time_ns;+ Ok(true)+ }+ _ => Ok(false),+ }+ }++ async fn remove_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<bool> {+ let mut tokens = self.tokens.write().await;+ match tokens.get(lock_path) {+ Some(token) if token.owner_id == owner_id => {+ tokens.remove(lock_path);+ Ok(true)+ }+ _ => Ok(false),+ }+ }++ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {+ let prefix = if root.ends_with('/') {+ root.to_string()+ } else {+ format!("{}/", root)+ };+ Ok(self+ .tokens+ .read()+ .await+ .keys()+ .filter(|k| k.starts_with(&prefix))+ .cloned()+ .collect())+ }+}++// ── Filesystem provider ──++/// Lock provider that stores tokens as files on the underlying filesystem.+pub struct FilesystemPathLockProvider {+ fs: Arc<dyn FileSystem>,+}++impl FilesystemPathLockProvider {+ /// Create a filesystem-backed provider.+ pub fn new(fs: Arc<dyn FileSystem>) -> Self {+ Self { fs }+ }++ /// Read raw token bytes from `lock_path`, returning `None` if no token exists.+ async fn read_token_raw(&self, lock_path: &str) -> PathLockResult<Option<Vec<u8>>> {+ match self.fs.read(lock_path, 0, 0).await {+ Ok(data) => Ok(Some(data)),+ Err(e) => {+ if matches!(+ e,+ crate::core::Error::NotFound(_) | crate::core::Error::MountPointNotFound(_)+ ) {+ Ok(None)+ } else {+ Err(PathLockError::Io(format!(+ "failed to read lock token at '{lock_path}': {e}"+ )))+ }+ }+ }+ }+}++#[async_trait]+impl PathLockProvider for FilesystemPathLockProvider {+ fn name(&self) -> &'static str {+ "filesystem"+ }++ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {+ match self.read_token_raw(lock_path).await? {+ Some(data) => {+ let raw = String::from_utf8_lossy(&data).trim().to_string();+ if raw.is_empty() {+ return Ok(None);+ }+ LockTokenCodec::decode(&raw).map(Some)+ }+ None => Ok(None),+ }+ }++ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {+ use crate::core::WriteFlag;++ let encoded = LockTokenCodec::encode(token);+ match self+ .fs+ .write(lock_path, encoded.as_bytes(), 0, WriteFlag::CreateNew)+ .await+ {+ Ok(_) => Ok(()),+ Err(_) => {+ // Already exists — read and check if stale.+ let existing = self.read_token(lock_path).await?;+ match existing {+ Some(t) => Err(PathLockError::Conflict {+ lock_path: lock_path.to_string(),+ owner: t.owner_id,+ kind: t.lock_type,+ }),+ None => Err(PathLockError::Io(format!(+ "failed to create lock token at {lock_path}"+ ))),+ }+ }+ }+ }++ async fn compare_and_write_token(+ &self,+ lock_path: &str,+ expected: &LockToken,+ replacement: &LockToken,+ ) -> PathLockResult<bool> {+ let expected = LockTokenCodec::encode(expected);+ let replacement = LockTokenCodec::encode(replacement);+ self.fs+ .compare_and_write(lock_path, expected.as_bytes(), replacement.as_bytes())+ .await+ .map_err(|e| PathLockError::Io(format!("token CAS failed: {e}")))+ }++ async fn refresh_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ time_ns: u128,+ ) -> PathLockResult<bool> {+ let Some(raw) = self.read_token_raw(lock_path).await? else {+ return Ok(false);+ };+ let token = LockTokenCodec::decode(&String::from_utf8_lossy(&raw).trim())?;+ if token.owner_id != owner_id {+ return Ok(false);+ }+ let new_token = LockToken {+ owner_id: owner_id.to_string(),+ time_ns,+ lock_type: token.lock_type,+ };+ let encoded = LockTokenCodec::encode(&new_token);+ self.fs+ .compare_and_write(lock_path, &raw, encoded.as_bytes())+ .await+ .map_err(|e| PathLockError::Io(format!("refresh CAS failed: {e}")))+ }++ async fn remove_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<bool> {+ let Some(raw) = self.read_token_raw(lock_path).await? else {+ return Ok(false);+ };+ let token = LockTokenCodec::decode(&String::from_utf8_lossy(&raw).trim())?;+ if token.owner_id != owner_id {+ return Ok(false);+ }+ self.fs+ .compare_and_remove(lock_path, &raw)+ .await+ .map_err(|e| PathLockError::Io(format!("remove CAS failed: {e}")))+ }++ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {+ let mut result = Vec::new();+ self.scan_recursive(root, &mut result).await?;+ Ok(result)+ }+}++impl FilesystemPathLockProvider {+ /// Recursively scan a directory for `.path.ovlock` and `.exact.ovlock.*` files.+ fn is_lock_file(name: &str) -> bool {+ is_hidden_runtime_lock_name(name)+ }++ async fn scan_recursive(+ &self,+ dir: &str,+ result: &mut Vec<String>,+ ) -> PathLockResult<()> {+ let entries = match self.fs.read_internal_dir(dir).await {+ Ok(entries) => entries,+ Err(crate::core::Error::NotFound(_) | crate::core::Error::NotADirectory(_)) => {+ return Ok(());+ }+ Err(error) => {+ return Err(PathLockError::Io(format!(+ "failed to scan lock directory '{dir}': {error}"+ )));+ }+ };++ for entry in entries {+ let child_path = if dir.ends_with('/') {+ format!("{}{}", dir, entry.name)+ } else {+ format!("{}/{}", dir, entry.name)+ };++ if Self::is_lock_file(&entry.name) {+ result.push(child_path);+ } else if entry.is_dir {+ Box::pin(self.scan_recursive(&child_path, result)).await?;+ }+ }+ Ok(())+ }+}diff --git a/crates/ragfs/src/lock/resolver.rs b/crates/ragfs/src/lock/resolver.rsnew file mode 100644index 000000000..2f32da81e--- /dev/null+++ b/crates/ragfs/src/lock/resolver.rs@@ -0,0 +1,203 @@+//! Lock-path resolver — computes `.path.ovlock` and `.exact.ovlock.*` paths.++use std::sync::Arc;++use sha1::{Digest, Sha1};++use crate::core::internal_names::{EXACT_LOCK_FILE_PREFIX, PATH_LOCK_FILE};+use crate::core::FileSystem;++use super::types::PathLockResult;++/// Exact-lock paths resolved from one real path classification.+#[derive(Debug, Clone, PartialEq, Eq)]+pub(crate) struct ResolvedExactPaths {+ /// Lock path used for the actual exact token creation.+ pub acquire_lock_path: String,+ /// Conservative conflict set checked before and after token creation.+ pub conflict_paths: Vec<String>,+}++/// Computes lock-file paths for exact and tree locks.+pub struct LockPathResolver {+ /// Filesystem used for `stat` calls to determine is_dir.+ pub(crate) fs: Arc<dyn FileSystem>,+}++impl LockPathResolver {+ /// Create a new resolver backed by `fs`.+ pub fn new(fs: Arc<dyn FileSystem>) -> Self {+ Self { fs }+ }++ /// Compute exact lock paths for `path`.+ ///+ /// - Existing directory → `{path}/.path.ovlock`+ /// - File or non-existent path → `{parent}/.exact.ovlock.<safe_name>.<sha1-prefix>`+ pub async fn resolve_exact_lock_paths(&self, path: &str) -> PathLockResult<Vec<String>> {+ Ok(vec![self.resolve_exact_lock_path(path).await?])+ }++ /// Compute every lock-file path that can represent an exact lock for conflict checks.+ pub async fn resolve_exact_conflict_paths(+ &self,+ path: &str,+ ) -> PathLockResult<Vec<String>> {+ Ok(self.resolve_exact_paths(path).await?.conflict_paths)+ }++ /// Compute the primary lock-file path used when acquiring one exact lock.+ pub async fn resolve_exact_lock_path(&self, path: &str) -> PathLockResult<String> {+ Ok(self.resolve_exact_paths(path).await?.acquire_lock_path)+ }++ /// Resolve the exact acquire path and its conservative conflict set using one `stat`.+ pub(crate) async fn resolve_exact_paths(&self, path: &str) -> PathLockResult<ResolvedExactPaths> {+ let stat_result = self.fs.stat(path).await;+ let acquire_lock_path = match stat_result {+ Ok(info) if info.is_dir => path_lock_path(path),+ _ => prefixed_exact_lock_path(path),+ };+ let conflict_paths = if acquire_lock_path == path_lock_path(path) {+ vec![acquire_lock_path.clone(), prefixed_exact_lock_path(path)]+ } else {+ vec![acquire_lock_path.clone(), path_lock_path(path)]+ };+ Ok(ResolvedExactPaths {+ acquire_lock_path,+ conflict_paths,+ })+ }++ /// Compute the tree lock path for `path`.+ ///+ /// - Regular directory or missing path → `{path}/.path.ovlock`+ /// - Existing file path → parent directory sidecar+ pub async fn resolve_tree_lock_path(&self, path: &str) -> PathLockResult<String> {+ let stat_result = self.fs.stat(path).await;+ match stat_result {+ Ok(info) if !info.is_dir => {+ // Existing file: use parent sidecar to avoid `{file}/.path.ovlock`.+ Ok(prefixed_exact_lock_path(path))+ }+ _ => Ok(path_lock_path(path)),+ }+ }+}++/// Return the `.path.ovlock` path for one target.+fn path_lock_path(path: &str) -> String {+ format!("{}/{}", path.trim_end_matches('/'), PATH_LOCK_FILE)+}++/// Return the legacy-compatible prefixed exact sidecar path.+fn prefixed_exact_lock_path(path: &str) -> String {+ let (parent, name) = split_parent_name(path);+ format!(+ "{}/{}{}.{}",+ parent,+ EXACT_LOCK_FILE_PREFIX,+ safe_name(name),+ hash_prefix(path)+ )+}++/// Split a path into (parent_dir, basename).+fn split_parent_name(path: &str) -> (String, &str) {+ let trimmed = path.trim_end_matches('/');+ match trimmed.rsplit_once('/') {+ Some((parent, name)) if !parent.is_empty() => (parent.to_string(), name),+ Some((_, name)) => ("/".to_string(), name),+ None => ("/".to_string(), trimmed),+ }+}++/// Sanitize a filename exactly like the legacy Python pathlock protocol.+fn safe_name(name: &str) -> String {+ let mut sanitized = String::new();+ let mut replacing = false;+ for c in name.chars() {+ if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {+ sanitized.push(c);+ replacing = false;+ } else if !replacing {+ sanitized.push('_');+ replacing = true;+ }+ }+ let sanitized = sanitized.trim_matches(['.', '_']);+ let sanitized = if sanitized.is_empty() {+ "path"+ } else {+ sanitized+ };+ sanitized.chars().take(80).collect()+}++/// First 16 hex chars of SHA-1 of the full backend path.+fn hash_prefix(path: &str) -> String {+ let digest = Sha1::digest(path.as_bytes());+ digest[..8].iter().map(|b| format!("{:02x}", b)).collect::<String>()+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::core::WriteFlag;+ use crate::plugins::memfs::MemFileSystem;++ /// Build the real in-memory filesystem used by resolver tests.+ async fn memfs() -> Arc<MemFileSystem> {+ let fs = Arc::new(MemFileSystem::new());+ fs.mkdir("/data", 0o755).await.unwrap();+ fs+ }++ #[tokio::test]+ async fn resolver_uses_path_lock_for_directories_and_sidecars_for_files() {+ let fs = memfs().await;+ fs.mkdir("/data/dir", 0o755).await.unwrap();+ fs.write("/data/file.txt", b"", 0, WriteFlag::Create)+ .await+ .unwrap();+ let resolver = LockPathResolver::new(fs);++ assert_eq!(+ resolver.resolve_exact_lock_paths("/data/dir").await.unwrap(),+ vec!["/data/dir/.path.ovlock".to_string()]+ );+ assert_eq!(+ resolver.resolve_tree_lock_path("/data/dir").await.unwrap(),+ "/data/dir/.path.ovlock"+ );++ let exact_file = resolver+ .resolve_exact_lock_paths("/data/file.txt")+ .await+ .unwrap();+ assert!(exact_file[0].starts_with("/data/.exact.ovlock.file.txt."));+ assert!(resolver+ .resolve_tree_lock_path("/data/file.txt")+ .await+ .unwrap()+ .starts_with("/data/.exact.ovlock.file.txt."));+ assert!(resolver+ .resolve_exact_lock_paths("/data/new.txt")+ .await+ .unwrap()[0]+ .starts_with("/data/.exact.ovlock.new.txt."));+ }++ #[test]+ fn sidecar_name_matches_legacy_python_protocol() {+ assert_eq!(safe_name("hello world"), "hello_world");+ assert_eq!(safe_name("a/b"), "a_b");+ assert_eq!(safe_name("ok.txt"), "ok.txt");+ assert_eq!(safe_name("中文名"), "path");+ assert_eq!(safe_name(""), "path");+ assert_eq!(+ prefixed_exact_lock_path("/data/中文 name..txt"),+ "/data/.exact.ovlock.name..txt.591847f8876e86f7"+ );+ }+}diff --git a/crates/ragfs/src/lock/types.rs b/crates/ragfs/src/lock/types.rsnew file mode 100644index 000000000..1bb1c34da--- /dev/null+++ b/crates/ragfs/src/lock/types.rs@@ -0,0 +1,200 @@+//! Data models for the PathLock subsystem.++use serde::{Deserialize, Serialize};++/// Lock kind: exact (single path) or tree (path + descendants).+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+pub enum PathLockKind {+ /// Exact-path lock.+ Exact,+ /// Tree lock covering the path and all descendants.+ Tree,+}++impl PathLockKind {+ /// Single-character encoding: `E` for Exact, `T` for Tree.+ pub fn to_code(self) -> char {+ match self {+ PathLockKind::Exact => 'E',+ PathLockKind::Tree => 'T',+ }+ }++ /// Decode from a single character.+ pub fn from_code(c: char) -> Option<Self> {+ match c {+ 'E' => Some(PathLockKind::Exact),+ 'T' => Some(PathLockKind::Tree),+ _ => None,+ }+ }+}++/// Structured lock token stored in lock files.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct LockToken {+ /// Owner identity (UUIDv4-style).+ pub owner_id: String,+ /// Nanosecond timestamp of last write/refresh.+ pub time_ns: u128,+ /// Lock type.+ pub lock_type: PathLockKind,+}++/// Unified lease record (Rust-internal, exposed to Python as an opaque reference).+#[derive(Debug, Clone)]+pub struct PathLockLease {+ /// Opaque lease reference used by callers; not equal to owner_id.+ pub lease_ref: String,+ /// Owner identity.+ pub owner_id: String,+ /// Lock-file paths held by this lease.+ pub lock_paths: Vec<String>,+ /// Original path coverage granted by the lease.+ pub covered_paths: Vec<PathLockRequest>,+}++/// Owned lease — caller controls refresh/release/handoff lifecycle.+#[derive(Debug, Clone)]+pub struct OwnedPathLockLease {+ /// Underlying lease data.+ pub lease: PathLockLease,+ /// Opaque capability required for lifecycle operations.+ pub ownership_ref: String,+}++/// Borrowed lease — read-only proof that a lock is held, no lifecycle control.+#[derive(Debug, Clone)]+pub struct BorrowedPathLockLease {+ /// Underlying lease data.+ pub lease: PathLockLease,+}++/// Serializable handoff payload for cross-queue / cross-worker lock transfer.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct PathLockHandoffRef {+ /// Owner identity (preserved across handoff).+ pub owner_id: String,+ /// Lock-file paths held.+ pub lock_paths: Vec<String>,+ /// Original path coverage granted by the handed-off lease.+ #[serde(default)]+ pub covered_paths: Vec<PathLockRequest>,+}++/// A single lock request for batch acquire.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct PathLockRequest {+ /// Target path.+ pub path: String,+ /// Lock kind.+ pub kind: PathLockKind,+}++impl PathLockLease {+ /// Return true when this lease covers a requested operation.+ pub fn covers(&self, request: &PathLockRequest) -> bool {+ self.covered_paths+ .iter()+ .any(|held| request_is_covered_by(held, request))+ }+}++/// Return true when a held request covers another requested operation.+fn request_is_covered_by(held: &PathLockRequest, request: &PathLockRequest) -> bool {+ match (held.kind, request.kind) {+ (PathLockKind::Exact, PathLockKind::Exact) => normalize_path(&held.path) == normalize_path(&request.path),+ (PathLockKind::Tree, _) => path_is_self_or_descendant(&request.path, &held.path),+ (PathLockKind::Exact, PathLockKind::Tree) => false,+ }+}++/// Normalize a path for simple lock coverage checks.+fn normalize_path(path: &str) -> String {+ let trimmed = path.trim_end_matches('/');+ if trimmed.is_empty() {+ "/".to_string()+ } else {+ trimmed.to_string()+ }+}++/// Return true when `path` is equal to or under `ancestor`.+fn path_is_self_or_descendant(path: &str, ancestor: &str) -> bool {+ let path = normalize_path(path);+ let ancestor = normalize_path(ancestor);+ path == ancestor+ || ancestor == "/"+ || path+ .strip_prefix(&ancestor)+ .is_some_and(|suffix| suffix.starts_with('/'))+}++/// Snapshot of current lock state for observability.+#[derive(Debug, Clone)]+pub struct PathLockObserveSnapshot {+ /// Number of active (held) locks.+ pub active_locks: usize,+ /// Number of waiting lock requests.+ pub waiting_locks: usize,+ /// Number of stale locks removed.+ pub stale_locks_removed: usize,+ /// Current conflicts.+ pub conflicts: Vec<PathLockConflict>,+}++/// Description of a lock conflict.+#[derive(Debug, Clone)]+pub struct PathLockConflict {+ /// Lock path where conflict occurred.+ pub lock_path: String,+ /// Owner of the conflicting lock.+ pub conflicting_owner: String,+ /// Kind of the conflicting lock.+ pub conflicting_kind: PathLockKind,+}++/// PathLock-specific error type.+#[derive(Debug, thiserror::Error)]+pub enum PathLockError {+ /// Lock conflict with another owner.+ #[error("lock conflict on '{lock_path}': owned by '{owner}'")]+ Conflict {+ /// Lock path where conflict occurred.+ lock_path: String,+ /// Owner of the conflicting lock.+ owner: String,+ /// Kind of the conflicting lock from the original read snapshot.+ kind: PathLockKind,+ },++ /// Timeout waiting for lock acquisition.+ #[error("lock acquire timed out after {elapsed_ms}ms")]+ Timeout {+ /// Elapsed time in milliseconds.+ elapsed_ms: u64,+ },++ /// I/O error during lock operation.+ #[error("lock I/O error: {0}")]+ Io(String),++ /// Invalid lock token format.+ #[error("invalid lock token: {0}")]+ InvalidToken(String),++ /// Invalid lock request supplied by a caller.+ #[error("invalid lock request: {0}")]+ InvalidRequest(String),++ /// Handoff/adopt failure.+ #[error("handoff/adopt failed: {0}")]+ HandoffFailed(String),++ /// Internal error.+ #[error("lock internal error: {0}")]+ Internal(String),+}++/// Result type alias for PathLock operations.+pub type PathLockResult<T> = std::result::Result<T, PathLockError>;diff --git a/crates/ragfs/src/lock/wrapper.rs b/crates/ragfs/src/lock/wrapper.rsnew file mode 100644index 000000000..4e690884b--- /dev/null+++ b/crates/ragfs/src/lock/wrapper.rs@@ -0,0 +1,368 @@+//! PathLockWrappedFS — automatic lock acquisition for simple file operations.+//!+//! This wrapper sits between `StatsWrappedFS` and `MountableFS` in the stack.+//! It auto-acquires locks for `create`, `write`, `truncate`, `remove`, `remove_all`,+//! `rename`, and `replace`, then delegates to the inner filesystem.+//!+//! It is NOT a lock protocol implementation — all lock logic is delegated to+//! `PathLockManager`.++use std::sync::Arc;+use std::time::Duration;++use async_trait::async_trait;++use crate::core::filesystem::FileSystem;+use crate::core::internal_names::is_hidden_runtime_lock_name;+use crate::core::types::{FileInfo, GlobPage, GrepResult, TreeEntry, WriteFlag};+use crate::core::MountableFS;++use super::manager::{AutoPathLockAction, PathLockManager};+use super::types::{PathLockKind, PathLockRequest};++/// Default timeout for auto-acquired locks.+const AUTO_LOCK_TIMEOUT: Duration = Duration::ZERO;++/// A `FileSystem` wrapper that auto-acquires path locks for mutating operations.+pub struct PathLockWrappedFS {+ /// The lock manager (single source of truth).+ manager: Arc<PathLockManager>,+ /// The inner filesystem.+ inner: Arc<dyn FileSystem>,+}++impl PathLockWrappedFS {+ /// Create a new PathLockWrappedFS.+ pub fn new(manager: Arc<PathLockManager>, inner: Arc<dyn FileSystem>) -> Self {+ Self { manager, inner }+ }++ /// Return the inner filesystem.+ pub fn inner_fs(&self) -> &Arc<dyn FileSystem> {+ &self.inner+ }++ /// Return true for virtual control paths and lock metadata that must not be auto-locked.+ fn should_bypass_auto_lock(path: &str) -> bool {+ path == "/queue"+ || path.starts_with("/queue/")+ || path == "/serverinfo"+ || path.starts_with("/serverinfo/")+ || path+ .rsplit_once('/')+ .map(|(_, name)| is_hidden_runtime_lock_name(name))+ .unwrap_or_else(|| is_hidden_runtime_lock_name(path))+ }++ /// Check if auto-locking should be skipped for the current context.+ ///+ /// Returns `true` when auto-locking is disabled or an active lease covers the operation.+ async fn should_skip_auto_lock(+ &self,+ requests: &[PathLockRequest],+ ) -> crate::core::Result<bool> {+ match self.manager.resolve_auto_pathlock_action(requests).await {+ Ok(AutoPathLockAction::Disabled | AutoPathLockAction::Covered(_)) => Ok(true),+ Ok(AutoPathLockAction::Acquire) => Ok(false),+ Err(error) => Err(crate::core::Error::internal(format!(+ "lock lease error: {error}"+ ))),+ }+ }++ /// Merge an operation result with its lock-release result.+ fn merge_operation_and_release<T>(+ operation: crate::core::Result<T>,+ release: super::types::PathLockResult<()>,+ ) -> crate::core::Result<T> {+ match (operation, release) {+ (Err(error), _) => Err(error),+ (Ok(value), Ok(())) => Ok(value),+ (Ok(_), Err(error)) => Err(crate::core::Error::internal(format!(+ "lock release error: {error}"+ ))),+ }+ }++ /// Return whether the routed encryption wrapper owns locking for this write.+ async fn encryption_handles_pathlock(&self, path: &str) -> bool {+ let any = self.inner.as_ref() as &dyn std::any::Any;+ match any.downcast_ref::<MountableFS>() {+ Some(mountable) => mountable.encryption_handles_pathlock(path).await,+ None => false,+ }+ }+}++#[async_trait]+impl FileSystem for PathLockWrappedFS {+ async fn create(&self, path: &str) -> crate::core::Result<()> {+ if Self::should_bypass_auto_lock(path) || self.encryption_handles_pathlock(path).await {+ return self.inner.create(path).await;+ }+ let requests = [PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Exact,+ }];+ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.create(path).await;+ }+ let lease = self+ .manager+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.create(path).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn mkdir(&self, path: &str, mode: u32) -> crate::core::Result<()> {+ self.inner.mkdir(path, mode).await+ }++ async fn remove(&self, path: &str) -> crate::core::Result<()> {+ if Self::should_bypass_auto_lock(path) {+ return self.inner.remove(path).await;+ }+ let requests = [PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Exact,+ }];+ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.remove(path).await;+ }+ let lease = self+ .manager+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.remove(path).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn remove_all(&self, path: &str) -> crate::core::Result<()> {+ if Self::should_bypass_auto_lock(path) {+ return self.inner.remove_all(path).await;+ }+ let requests = [PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Tree,+ }];+ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.remove_all(path).await;+ }+ let lease = self+ .manager+ .acquire_tree(path, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.remove_all(path).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn read(&self, path: &str, offset: u64, size: u64) -> crate::core::Result<Vec<u8>> {+ self.inner.read(path, offset, size).await+ }++ async fn write(+ &self,+ path: &str,+ data: &[u8],+ offset: u64,+ flags: WriteFlag,+ ) -> crate::core::Result<u64> {+ if Self::should_bypass_auto_lock(path) || self.encryption_handles_pathlock(path).await {+ return self.inner.write(path, data, offset, flags).await;+ }+ let requests = [PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Exact,+ }];+ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.write(path, data, offset, flags).await;+ }+ let lease = self+ .manager+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.write(path, data, offset, flags).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn read_dir(&self, path: &str) -> crate::core::Result<Vec<FileInfo>> {+ self.inner.read_dir(path).await+ }++ async fn stat(&self, path: &str) -> crate::core::Result<FileInfo> {+ self.inner.stat(path).await+ }++ async fn rename(&self, old_path: &str, new_path: &str) -> crate::core::Result<()> {+ if Self::should_bypass_auto_lock(old_path) || Self::should_bypass_auto_lock(new_path) {+ return self.inner.rename(old_path, new_path).await;+ }++ // Determine if source is a directory.+ let src_is_dir = self+ .inner+ .stat(old_path)+ .await+ .map(|info| info.is_dir)+ .unwrap_or(false);++ let requests: Vec<PathLockRequest> = if src_is_dir {+ vec![+ PathLockRequest {+ path: old_path.to_string(),+ kind: PathLockKind::Tree,+ },+ PathLockRequest {+ path: new_path.to_string(),+ kind: PathLockKind::Exact,+ },+ ]+ } else {+ vec![+ PathLockRequest {+ path: old_path.to_string(),+ kind: PathLockKind::Exact,+ },+ PathLockRequest {+ path: new_path.to_string(),+ kind: PathLockKind::Exact,+ },+ ]+ };++ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.rename(old_path, new_path).await;+ }++ let lease = self+ .manager+ .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.rename(old_path, new_path).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn replace(&self, src_path: &str, dst_path: &str) -> crate::core::Result<()> {+ if Self::should_bypass_auto_lock(src_path) || Self::should_bypass_auto_lock(dst_path) {+ return self.inner.replace(src_path, dst_path).await;+ }++ let requests = vec![+ PathLockRequest {+ path: src_path.to_string(),+ kind: PathLockKind::Exact,+ },+ PathLockRequest {+ path: dst_path.to_string(),+ kind: PathLockKind::Exact,+ },+ ];+ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.replace(src_path, dst_path).await;+ }+ let lease = self+ .manager+ .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.replace(src_path, dst_path).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn chmod(&self, path: &str, mode: u32) -> crate::core::Result<()> {+ self.inner.chmod(path, mode).await+ }++ async fn truncate(&self, path: &str, size: u64) -> crate::core::Result<()> {+ if Self::should_bypass_auto_lock(path) || self.encryption_handles_pathlock(path).await {+ return self.inner.truncate(path, size).await;+ }+ let requests = [PathLockRequest {+ path: path.to_string(),+ kind: PathLockKind::Exact,+ }];+ if self.should_skip_auto_lock(&requests).await? {+ return self.inner.truncate(path, size).await;+ }+ let lease = self+ .manager+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .await+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;+ let result = self.inner.truncate(path, size).await;+ let release = self.manager.release(&lease).await;+ Self::merge_operation_and_release(result, release)+ }++ async fn grep(+ &self,+ path: &str,+ pattern: &str,+ recursive: bool,+ case_insensitive: bool,+ node_limit: Option<usize>,+ exclude_path: Option<&str>,+ level_limit: Option<usize>,+ ) -> crate::core::Result<GrepResult> {+ self.inner+ .grep(+ path,+ pattern,+ recursive,+ case_insensitive,+ node_limit,+ exclude_path,+ level_limit,+ )+ .await+ }++ async fn tree_directory(+ &self,+ path: &str,+ show_hidden: bool,+ node_limit: Option<usize>,+ level_limit: Option<usize>,+ ) -> crate::core::Result<Vec<TreeEntry>> {+ self.inner+ .tree_directory(path, show_hidden, node_limit, level_limit)+ .await+ }++ async fn glob_directory(+ &self,+ path: &str,+ pattern: &str,+ show_hidden: bool,+ page_size: Option<usize>,+ level_limit: Option<usize>,+ continuation_token: Option<String>,+ ) -> crate::core::Result<GlobPage> {+ self.inner+ .glob_directory(+ path,+ pattern,+ show_hidden,+ page_size,+ level_limit,+ continuation_token,+ )+ .await+ }++ async fn ensure_parent_dirs(&self, path: &str, mode: u32) -> crate::core::Result<()> {+ self.inner.ensure_parent_dirs(path, mode).await+ }+}diff --git a/crates/ragfs/src/multibackend/factory.rs b/crates/ragfs/src/multibackend/factory.rsindex 0ac98d581..0f657d850 100644--- a/crates/ragfs/src/multibackend/factory.rs+++ b/crates/ragfs/src/multibackend/factory.rs@@ -16,7 +16,7 @@ use crate::multibackend::config::{item_params_to_config_values, sync_mode_from_config, validate_backup_excludes,validate_primary_encryption_flags, validate_redirect_targets,};-use crate::multibackend::meta::MountRootFsContextResolver;+use crate::multibackend::meta::RelativePathFsContextResolver;use crate::multibackend::types::MultiBackendBuildContext;use crate::shape::validate::ensure_backend_shape;@@ -85,6 +85,8 @@ pub async fn build_multi_write_fs(build_ctx.enc_provider_type.expect("global encryption validated before building primary backend"),+ build_ctx.pathlock_manager.clone(),+ build_ctx.backend_prefix.clone(),))} else {primary_raw.clone()@@ -146,6 +148,8 @@ pub async fn build_multi_write_fs(build_ctx.enc_provider_type.expect("global encryption validated before building backup backend"),+ build_ctx.pathlock_manager.clone(),+ build_ctx.backend_prefix.clone(),))} else {backup_raw@@ -176,8 +180,6 @@ pub async fn build_multi_write_fs(.retry_backoff_base_ms(bc.retry_backoff_base_ms.unwrap_or(1_000)).max_retry_per_round(bc.retry_max_retries_per_round.unwrap_or(3)).quarantine_after_failures(bc.retry_quarantine_after_failures.unwrap_or(9))- .ctx_resolver(Arc::new(MountRootFsContextResolver::new(- &config.mount_path,- )))+ .ctx_resolver(Arc::new(RelativePathFsContextResolver)).build()}diff --git a/crates/ragfs/src/multibackend/meta.rs b/crates/ragfs/src/multibackend/meta.rsindex d63766170..457722cd8 100644--- a/crates/ragfs/src/multibackend/meta.rs+++ b/crates/ragfs/src/multibackend/meta.rs@@ -45,44 +45,13 @@ impl FsContextResolver for DefaultFsContextResolver {}}-/// Resolver that extracts `account_id` from paths under one concrete mount root.-pub struct MountRootFsContextResolver {- mount_root: String,-}--impl MountRootFsContextResolver {- /// Create a resolver for one normalized mount root such as `/local` or `/s3`.- pub fn new(mount_root: &str) -> Self {- let mut normalized = mount_root.trim_end_matches('/').to_string();- if normalized.is_empty() {- normalized = "/".to_string();- } else if !normalized.starts_with('/') {- normalized = format!("/{normalized}");- }- Self {- mount_root: normalized,- }- }-}+/// Resolver that extracts `account_id` from mount-relative paths such as `/{account_id}/...`.+pub struct RelativePathFsContextResolver;-impl FsContextResolver for MountRootFsContextResolver {+impl FsContextResolver for RelativePathFsContextResolver {fn resolve(&self, path: &str) -> Result<FsContext> {- let normalized = if path.starts_with('/') {- path.to_string()- } else {- format!("/{path}")- };- let suffix = if self.mount_root == "/" {- normalized.trim_start_matches('/')- } else {- normalized- .strip_prefix(&self.mount_root)- .and_then(|suffix| suffix.strip_prefix('/'))- .ok_or_else(|| {- Error::internal(format!("cannot resolve FsContext from path: {path}"))- })?- };- let account_id = suffix.split('/').next().unwrap_or_default();+ let normalized = path.trim_start_matches('/');+ let account_id = normalized.split('/').next().unwrap_or_default();if account_id.is_empty() {return Err(Error::internal(format!("cannot resolve FsContext from path: {path}"@@ -175,12 +144,12 @@ impl MetaStateStore {Arc::new(FsContextInner::new("_system".to_string()))}- /// - root directory using `_system` context+ /// Build the effective context for metadata access.fn effective_meta_ctx(dir: &str, ctx: &FsContext) -> FsContext {if dir == "/" {- Self::system_ctx()+ Arc::new(Self::system_ctx().with_auto_pathlock_disabled())} else {- ctx.clone()+ Arc::new(ctx.with_auto_pathlock_disabled())}}@@ -563,15 +532,6 @@ mod tests {assert!(resolver.resolve("/invalid/path").is_err());}- #[test]- fn test_mount_root_resolver_extracts_account_from_non_local_path() {- let resolver = MountRootFsContextResolver::new("/s3");- let ctx = resolver.resolve("/s3/acct-1/resources/file.txt").unwrap();- assert_eq!(ctx.account_id(), "acct-1");- assert!(resolver- .resolve("/local/acct-1/resources/file.txt")- .is_err());- }#[tokio::test]async fn test_invalid_sync_log_json_returns_error() {diff --git a/crates/ragfs/src/multibackend/types.rs b/crates/ragfs/src/multibackend/types.rsindex 8e097ee4f..78bb71d66 100644--- a/crates/ragfs/src/multibackend/types.rs+++ b/crates/ragfs/src/multibackend/types.rs@@ -1,12 +1,20 @@//! Shared build-time types for multi-backend assembly.+use std::sync::Arc;++use crate::lock::PathLockManager;+/// Encryption context used while assembling one multi-backend mount.-#[derive(Clone, Copy)]+#[derive(Clone)]pub struct MultiBackendBuildContext {/// Global root key, if server-side encryption is enabled.pub enc_root_key: Option<[u8; 32]>,/// Global provider type, if server-side encryption is enabled.pub enc_provider_type: Option<u8>,+ /// Shared manager used by encrypted backends for dual-path locking.+ pub pathlock_manager: Arc<PathLockManager>,+ /// Mount prefix used to restore manager-visible backend paths.+ pub backend_prefix: String,}impl MultiBackendBuildContext {diff --git a/crates/ragfs/src/plugins/kvfs/mod.rs b/crates/ragfs/src/plugins/kvfs/mod.rsindex e2b1775b0..85be8ed6e 100644--- a/crates/ragfs/src/plugins/kvfs/mod.rs+++ b/crates/ragfs/src/plugins/kvfs/mod.rs@@ -193,6 +193,9 @@ impl FileSystem for KVFileSystem {WriteFlag::Create | WriteFlag::Truncate => {entry.value = data.to_vec();}+ WriteFlag::CreateNew => {+ return Err(Error::AlreadyExists(key));+ }WriteFlag::Append => {entry.value.extend_from_slice(data);}@@ -211,7 +214,7 @@ impl FileSystem for KVFileSystem {Ok(data.len() as u64)}None => {- if matches!(flags, WriteFlag::Create) {+ if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {store.insert(key, KVEntry::new(data.to_vec()));Ok(data.len() as u64)} else {@@ -221,6 +224,38 @@ impl FileSystem for KVFileSystem {}}+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let key = Self::path_to_key(path);+ let mut store = self.store.write().await;++ match store.get_mut(&key) {+ Some(entry) if entry.value.as_slice() == expected => {+ entry.value = new_data.to_vec();+ entry.touch();+ Ok(true)+ }+ _ => Ok(false),+ }+ }++ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let key = Self::path_to_key(path);+ let mut store = self.store.write().await;++ match store.get(&key) {+ Some(entry) if entry.value.as_slice() == expected => {+ store.remove(&key);+ Ok(true)+ }+ _ => Ok(false),+ }+ }+async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {let key = Self::path_to_key(path);let store = self.store.read().await;diff --git a/crates/ragfs/src/plugins/localfs/mod.rs b/crates/ragfs/src/plugins/localfs/mod.rsindex af1e97740..bb71063d2 100644--- a/crates/ragfs/src/plugins/localfs/mod.rs+++ b/crates/ragfs/src/plugins/localfs/mod.rs@@ -93,6 +93,148 @@ impl LocalFileSystem {}}+ /// Return whether an open file still identifies the file currently stored at `path`.+ fn open_file_matches_path(file: &fs::File, path: &Path) -> Result<bool> {+ let open_metadata = file+ .metadata()+ .map_err(|e| Error::plugin(format!("failed to stat open CAS file: {}", e)))?;+ let path_metadata = match fs::metadata(path) {+ Ok(metadata) => metadata,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(false),+ Err(e) => {+ return Err(Error::plugin(format!(+ "failed to stat CAS path '{}': {}",+ path.display(),+ e+ )));+ }+ };++ #[cfg(unix)]+ {+ use std::os::unix::fs::MetadataExt;+ Ok(open_metadata.dev() == path_metadata.dev()+ && open_metadata.ino() == path_metadata.ino())+ }+ #[cfg(windows)]+ {+ use std::os::windows::fs::MetadataExt;+ Ok(open_metadata.volume_serial_number() == path_metadata.volume_serial_number()+ && open_metadata.file_index() == path_metadata.file_index())+ }+ #[cfg(not(any(unix, windows)))]+ {+ let _ = (open_metadata, path_metadata);+ Err(Error::invalid_operation(+ "CAS file identity checks are unsupported on this platform",+ ))+ }+ }++ /// Replace local file content only when the locked file content matches `expected`.+ fn compare_and_write_locked(+ local_path: PathBuf,+ expected: Vec<u8>,+ new_data: Vec<u8>,+ ) -> Result<bool> {+ use std::io::{Read, Seek, SeekFrom, Write};++ let file = fs::OpenOptions::new()+ .read(true)+ .write(true)+ .open(&local_path)+ .map_err(|e| {+ if e.kind() == std::io::ErrorKind::NotFound {+ Error::NotFound(local_path.to_string_lossy().to_string())+ } else {+ Error::plugin(format!("failed to open file for compare_and_write: {}", e))+ }+ });+ let file = match file {+ Ok(file) => file,+ Err(Error::NotFound(_)) => return Ok(false),+ Err(e) => return Err(e),+ };+ let mut lock = filelocks::LockOptions::new()+ .backend(filelocks::LockBackend::Fcntl)+ .lock(+ file,+ filelocks::LockKind::Exclusive,+ filelocks::LockMode::NonBlocking,+ )+ .map_err(|e| Error::plugin(format!("failed to lock for compare_and_write: {}", e)))?;+ let file = lock.file_mut();+ if !Self::open_file_matches_path(&file, &local_path)? {+ return Ok(false);+ }++ let mut current = Vec::new();+ file.seek(SeekFrom::Start(0))+ .map_err(|e| Error::plugin(format!("failed to seek for compare_and_write: {}", e)))?;+ file.read_to_end(&mut current)+ .map_err(|e| Error::plugin(format!("failed to read for compare_and_write: {}", e)))?;+ if current != expected {+ return Ok(false);+ }++ file.set_len(0)+ .map_err(|e| Error::plugin(format!("failed to truncate for compare_and_write: {}", e)))?;+ file.seek(SeekFrom::Start(0))+ .map_err(|e| Error::plugin(format!("failed to rewind for compare_and_write: {}", e)))?;+ file.write_all(&new_data)+ .map_err(|e| Error::plugin(format!("failed to write for compare_and_write: {}", e)))?;+ file.sync_data()+ .map_err(|e| Error::plugin(format!("failed to sync for compare_and_write: {}", e)))?;+ Ok(true)+ }++ /// Remove a local file only when the locked file content matches `expected`.+ fn compare_and_remove_locked(local_path: PathBuf, expected: Vec<u8>) -> Result<bool> {+ use std::io::{Read, Seek, SeekFrom};++ let file = fs::OpenOptions::new()+ .read(true)+ .write(true)+ .open(&local_path)+ .map_err(|e| {+ if e.kind() == std::io::ErrorKind::NotFound {+ Error::NotFound(local_path.to_string_lossy().to_string())+ } else {+ Error::plugin(format!("failed to open file for compare_and_remove: {}", e))+ }+ });+ let file = match file {+ Ok(file) => file,+ Err(Error::NotFound(_)) => return Ok(false),+ Err(e) => return Err(e),+ };+ let mut lock = filelocks::LockOptions::new()+ .backend(filelocks::LockBackend::Fcntl)+ .lock(+ file,+ filelocks::LockKind::Exclusive,+ filelocks::LockMode::NonBlocking,+ )+ .map_err(|e| Error::plugin(format!("failed to lock for compare_and_remove: {}", e)))?;+ let file = lock.file_mut();+ if !Self::open_file_matches_path(&file, &local_path)? {+ return Ok(false);+ }++ let mut current = Vec::new();+ file.seek(SeekFrom::Start(0))+ .map_err(|e| Error::plugin(format!("failed to seek for compare_and_remove: {}", e)))?;+ file.read_to_end(&mut current)+ .map_err(|e| Error::plugin(format!("failed to read for compare_and_remove: {}", e)))?;+ if current != expected {+ return Ok(false);+ }++ fs::remove_file(&local_path)+ .map_err(|e| Error::plugin(format!("failed to remove for compare_and_remove: {}", e)))?;+ Ok(true)+ }+/// Run blocking local filesystem work on a dedicated thread.async fn run_blocking_fs<T, F>(job: F) -> Result<T>where@@ -814,6 +956,9 @@ impl FileSystem for LocalFileSystem {WriteFlag::Create => {options.write(true).create(true).truncate(true);}+ WriteFlag::CreateNew => {+ options.write(true).create_new(true);+ }WriteFlag::Append => {options.append(true);}@@ -842,6 +987,29 @@ impl FileSystem for LocalFileSystem {Ok(data.len() as u64)}+ /// Atomically replace a local file when its current content exactly matches `expected`.+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let local_path = self.resolve_path(path)?;+ let expected = expected.to_vec();+ let new_data = new_data.to_vec();+ Self::run_blocking_fs(move || {+ Self::compare_and_write_locked(local_path, expected, new_data)+ })+ .await+ }++ /// Atomically remove a local file when its current content exactly matches `expected`.+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let local_path = self.resolve_path(path)?;+ let expected = expected.to_vec();+ Self::run_blocking_fs(move || Self::compare_and_remove_locked(local_path, expected)).await+ }+async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {let local_path = self.resolve_path(path)?;let path = path.to_string();diff --git a/crates/ragfs/src/plugins/memfs/mod.rs b/crates/ragfs/src/plugins/memfs/mod.rsindex af85f9c19..bdec5a9e8 100644--- a/crates/ragfs/src/plugins/memfs/mod.rs+++ b/crates/ragfs/src/plugins/memfs/mod.rs@@ -280,6 +280,9 @@ impl FileSystem for MemFileSystem {WriteFlag::Create | WriteFlag::Truncate => {entry.data = data.to_vec();}+ WriteFlag::CreateNew => {+ return Err(Error::AlreadyExists(normalized));+ }WriteFlag::Append => {entry.data.extend_from_slice(data);}@@ -299,8 +302,8 @@ impl FileSystem for MemFileSystem {Ok(data.len() as u64)}None => {- // Create file if Create flag is set- if matches!(flags, WriteFlag::Create) {+ // Create file if Create or CreateNew flag is set+ if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {// Check parent existsif let Some(parent) = Self::parent_path(&normalized) {match entries.get(&parent) {@@ -321,6 +324,39 @@ impl FileSystem for MemFileSystem {}}+ /// Atomically replace a memory file when its content matches `expected`.+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let normalized = Self::normalize_path(path);+ let mut entries = self.entries.write().await;+ let Some(entry) = entries.get_mut(&normalized) else {+ return Ok(false);+ };+ if entry.is_dir || entry.data != expected {+ return Ok(false);+ }+ entry.data = new_data.to_vec();+ entry.touch();+ Ok(true)+ }++ /// Atomically remove a memory file when its content matches `expected`.+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let normalized = Self::normalize_path(path);+ let mut entries = self.entries.write().await;+ let matches = entries+ .get(&normalized)+ .is_some_and(|entry| !entry.is_dir && entry.data == expected);+ if matches {+ entries.remove(&normalized);+ }+ Ok(matches)+ }+async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {let normalized = Self::normalize_path(path);let entries = self.entries.read().await;diff --git a/crates/ragfs/src/plugins/s3fs/client.rs b/crates/ragfs/src/plugins/s3fs/client.rsindex dddda4593..e37b8161e 100644--- a/crates/ragfs/src/plugins/s3fs/client.rs+++ b/crates/ragfs/src/plugins/s3fs/client.rs@@ -110,6 +110,30 @@ where}}+/// Return true when an S3 SDK service error represents a failed conditional request.+fn is_s3_conditional_failure<E, R>(sdk_err: &SdkError<E, R>) -> bool+where+ E: ProvideErrorMetadata,+ R: 'static,+{+ use std::any::Any;++ let SdkError::ServiceError(service_err) = sdk_err else {+ return false;+ };++ if matches!(+ service_err.err().code(),+ Some("PreconditionFailed" | "ConditionalRequestConflict")+ ) {+ return true;+ }++ (service_err.raw() as &dyn Any)+ .downcast_ref::<HttpResponse>()+ .is_some_and(|response| matches!(response.status().as_u16(), 409 | 412))+}+fn format_generic_s3_error(op: &str,bucket: &str,@@ -486,6 +510,46 @@ impl S3Client {Ok(bytes.to_vec())}+ /// Get an object's contents and ETag for conditional updates.+ pub async fn get_object_with_etag(&self, key: &str) -> Result<Option<(Vec<u8>, String)>> {+ let resp = match self+ .client+ .get_object()+ .bucket(&self.bucket)+ .key(key)+ .send()+ .await+ {+ Ok(resp) => resp,+ Err(sdk_err) => {+ let service_err = sdk_err.into_service_error();+ if service_err.is_no_such_key() {+ return Ok(None);+ }+ return Err(format_s3_service_error(+ "GetObjectWithEtag",+ &format!("bucket={} key={}", self.bucket, key),+ &service_err,+ ));+ }+ };++ let etag = resp.e_tag().ok_or_else(|| {+ Error::internal(format!(+ "S3 GetObjectWithEtag missing ETag: bucket={} key={key}",+ self.bucket+ ))+ })?.to_string();++ let bytes = resp+ .body+ .collect()+ .await+ .map_err(|e| format_generic_s3_error("ReadBody", &self.bucket, key, e))?;++ Ok(Some((bytes.to_vec(), etag)))+ }+/// Get an object's contents with range requestpub async fn get_object_range(&self, key: &str, offset: u64, size: u64) -> Result<Vec<u8>> {let range = if size == 0 {@@ -552,6 +616,72 @@ impl S3Client {Ok(())}+ /// Upload an object only when the key does not already exist.+ pub async fn put_object_create_new(&self, key: &str, data: Vec<u8>) -> Result<()> {+ let mut request = self+ .client+ .put_object()+ .bucket(&self.bucket)+ .key(key)+ .if_none_match("*")+ .body(ByteStream::from(data));++ if self.auto_detect_content_type {+ if let Some(content_type) = detect_content_type_for_key(key) {+ request = request.content_type(content_type);+ }+ }++ request.send().await.map_err(|e| {+ if is_s3_conditional_failure(&e) {+ Error::already_exists(key)+ } else {+ format_sdk_s3_error(+ "PutObjectCreateNew",+ &format!("bucket={} key={key}", self.bucket),+ &e,+ )+ }+ })?;++ Ok(())+ }++ /// Upload an object only when its ETag still matches `etag`.+ pub async fn put_object_if_match(&self, key: &str, data: Vec<u8>, etag: &str) -> Result<bool> {+ let mut request = self+ .client+ .put_object()+ .bucket(&self.bucket)+ .key(key)+ .if_match(etag)+ .body(ByteStream::from(data));++ if self.auto_detect_content_type {+ if let Some(content_type) = detect_content_type_for_key(key) {+ request = request.content_type(content_type);+ }+ }++ request.send().await.map_err(|e| {+ if is_s3_conditional_failure(&e) {+ Error::AlreadyExists(key.to_string())+ } else {+ format_sdk_s3_error(+ "PutObjectIfMatch",+ &format!("bucket={} key={key}", self.bucket),+ &e,+ )+ }+ }).map(|_| true).or_else(|e| {+ if matches!(e, Error::AlreadyExists(_)) {+ Ok(false)+ } else {+ Err(e)+ }+ })+ }+/// Delete a single objectpub async fn delete_object(&self, key: &str) -> Result<()> {self.client@@ -571,6 +701,36 @@ impl S3Client {Ok(())}+ /// Delete a single object only when its ETag still matches `etag`.+ pub async fn delete_object_if_match(&self, key: &str, etag: &str) -> Result<bool> {+ self.client+ .delete_object()+ .bucket(&self.bucket)+ .key(key)+ .if_match(etag)+ .send()+ .await+ .map_err(|e| {+ if is_s3_conditional_failure(&e) {+ Error::AlreadyExists(key.to_string())+ } else {+ format_sdk_s3_error(+ "DeleteObjectIfMatch",+ &format!("bucket={} key={key}", self.bucket),+ &e,+ )+ }+ })+ .map(|_| true)+ .or_else(|e| {+ if matches!(e, Error::AlreadyExists(_)) {+ Ok(false)+ } else {+ Err(e)+ }+ })+ }+/// Batch delete objects (up to 1000 per call)/// If disable_batch_delete is true, use sequential single-object deletes/// for S3-compatible services (e.g., Alibaba Cloud OSS) that requirediff --git a/crates/ragfs/src/plugins/s3fs/mod.rs b/crates/ragfs/src/plugins/s3fs/mod.rsindex 38e378094..d49334965 100644--- a/crates/ragfs/src/plugins/s3fs/mod.rs+++ b/crates/ragfs/src/plugins/s3fs/mod.rs@@ -29,7 +29,7 @@ use regex::Regex;use std::sync::atomic::{AtomicUsize, Ordering};use crate::core::filesystem::{relative_depth, relative_match_file, sort_directory_entries};-use crate::core::glob::{PreparedGlob, validate_pattern};+use crate::core::glob::PreparedGlob;use crate::core::{ConfigParameter, Error, FileInfo, FileSystem, GlobEntry, GlobPage, GrepMatch, GrepResult,PluginConfig, Result, ServicePlugin, TreeEntry, WriteFlag,@@ -573,12 +573,19 @@ impl FileSystem for S3FileSystem {}}- async fn write(&self, path: &str, data: &[u8], _offset: u64, _flags: WriteFlag) -> Result<u64> {+ async fn write(&self, path: &str, data: &[u8], _offset: u64, flags: WriteFlag) -> Result<u64> {let normalized = Self::normalize_path(path);let key = self.client.build_key(&normalized);- // S3 always replaces the full object- self.client.put_object(&key, data.to_vec()).await?;+ match flags {+ WriteFlag::CreateNew => {+ self.client.put_object_create_new(&key, data.to_vec()).await?;+ }+ _ => {+ // S3 always replaces the full object for non-exclusive writes.+ self.client.put_object(&key, data.to_vec()).await?;+ }+ }// Invalidate cachesself.dir_cache.invalidate_parent(&normalized).await;@@ -587,6 +594,48 @@ impl FileSystem for S3FileSystem {Ok(data.len() as u64)}+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let normalized = Self::normalize_path(path);+ let key = self.client.build_key(&normalized);+ let Some((current, etag)) = self.client.get_object_with_etag(&key).await? else {+ return Ok(false);+ };+ if current.as_slice() != expected {+ return Ok(false);+ }+ let changed = self+ .client+ .put_object_if_match(&key, new_data.to_vec(), &etag)+ .await?;+ if changed {+ self.dir_cache.invalidate_parent(&normalized).await;+ self.stat_cache.invalidate(&normalized).await;+ }+ Ok(changed)+ }++ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let normalized = Self::normalize_path(path);+ let key = self.client.build_key(&normalized);+ let Some((current, etag)) = self.client.get_object_with_etag(&key).await? else {+ return Ok(false);+ };+ if current.as_slice() != expected {+ return Ok(false);+ }+ let changed = self.client.delete_object_if_match(&key, &etag).await?;+ if changed {+ self.dir_cache.invalidate_parent(&normalized).await;+ self.stat_cache.invalidate(&normalized).await;+ }+ Ok(changed)+ }+async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {let normalized = Self::normalize_path(path);diff --git a/crates/ragfs/src/plugins/sqlfs/backend.rs b/crates/ragfs/src/plugins/sqlfs/backend.rsindex 5fa01efb7..f16314bed 100644--- a/crates/ragfs/src/plugins/sqlfs/backend.rs+++ b/crates/ragfs/src/plugins/sqlfs/backend.rs@@ -46,6 +46,12 @@ pub trait DatabaseBackend: Send + Sync {/// Update file datafn update_file(&self, path: &str, data: &[u8]) -> Result<()>;+ /// Update file data only when the current data equals `expected`.+ fn compare_and_update_file(&self, path: &str, expected: &[u8], data: &[u8]) -> Result<bool>;++ /// Delete a file only when the current data equals `expected`.+ fn compare_and_delete_file(&self, path: &str, expected: &[u8]) -> Result<bool>;+/// Get file metadatafn get_metadata(&self, path: &str) -> Result<Option<FileMetadata>>;@@ -278,6 +284,35 @@ impl DatabaseBackend for SQLiteBackend {Ok(())}+ fn compare_and_update_file(&self, path: &str, expected: &[u8], data: &[u8]) -> Result<bool> {+ let conn = self+ .conn+ .lock()+ .map_err(|e| Error::internal(e.to_string()))?;+ let now = chrono::Utc::now().timestamp();+ let changed = conn+ .execute(+ "UPDATE files SET data = ?1, size = ?2, mod_time = ?3 WHERE path = ?4 AND is_dir = 0 AND data = ?5",+ params![data, data.len() as i64, now, path, expected],+ )+ .map_err(|e| Error::internal(format!("conditional update error: {}", e)))?;+ Ok(changed == 1)+ }++ fn compare_and_delete_file(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let conn = self+ .conn+ .lock()+ .map_err(|e| Error::internal(e.to_string()))?;+ let changed = conn+ .execute(+ "DELETE FROM files WHERE path = ?1 AND is_dir = 0 AND data = ?2",+ params![path, expected],+ )+ .map_err(|e| Error::internal(format!("conditional delete error: {}", e)))?;+ Ok(changed == 1)+ }+fn get_metadata(&self, path: &str) -> Result<Option<FileMetadata>> {let conn = self.conndiff --git a/crates/ragfs/src/plugins/sqlfs/mod.rs b/crates/ragfs/src/plugins/sqlfs/mod.rsindex f990850c8..0ab7bb367 100644--- a/crates/ragfs/src/plugins/sqlfs/mod.rs+++ b/crates/ragfs/src/plugins/sqlfs/mod.rs@@ -110,6 +110,27 @@ impl SQLFileSystem {let normalized = Self::normalize_path(path);normalized.rsplit('/').next().unwrap_or("").to_string()}++ /// Run one synchronous database operation on Tokio's blocking pool.+ ///+ /// # Arguments+ /// * `job` - Blocking database work that uses the SQL backend directly+ ///+ /// # Returns+ /// The operation result converted back into the async SQLFS call path.+ async fn run_blocking_db<T, F>(&self, job: F) -> Result<T>+ where+ T: Send + 'static,+ F: FnOnce(&dyn DatabaseBackend) -> Result<T> + Send + 'static,+ {+ let backend = Arc::clone(&self.backend);+ tokio::task::spawn_blocking(move || {+ let backend = backend.blocking_read();+ job(backend.as_ref())+ })+ .await+ .map_err(|e| Error::internal(format!("sqlfs blocking task join error: {e}")))?+ }}impl Default for SQLFileSystem {@@ -261,9 +282,11 @@ impl FileSystem for SQLFileSystem {async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {let normalized = Self::normalize_path(path);- let backend = self.backend.read().await;-- match backend.read_file(&normalized)? {+ let normalized_for_db = normalized.clone();+ match self+ .run_blocking_db(move |backend| backend.read_file(&normalized_for_db))+ .await?+ {Some((is_dir, data)) => {if is_dir {return Err(Error::IsADirectory(normalized));@@ -308,41 +331,87 @@ impl FileSystem for SQLFileSystem {));}- let backend = self.backend.read().await;+ let normalized_for_db = normalized.clone();+ let data_owned = data.to_vec();+ let created_new = self+ .run_blocking_db(move |backend| {+ let exists = backend.path_exists(&normalized_for_db)?;++ if exists {+ // Check if it's a directory+ if backend.is_directory(&normalized_for_db)? {+ return Err(Error::IsADirectory(normalized_for_db.clone()));+ }- let exists = backend.path_exists(&normalized)?;+ if matches!(flags, WriteFlag::CreateNew) {+ return Err(Error::AlreadyExists(normalized_for_db.clone()));+ }- if exists {- // Check if it's a directory- if backend.is_directory(&normalized)? {- return Err(Error::IsADirectory(normalized));- }+ backend.update_file(&normalized_for_db, &data_owned)?;+ Ok(false)+ } else {+ if !matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {+ return Err(Error::not_found(&normalized_for_db));+ }- // Update existing file- backend.update_file(&normalized, data)?;- } else {- // Create new file- if !matches!(flags, WriteFlag::Create) {- return Err(Error::not_found(&normalized));- }+ let parent = backend.parent_path(&normalized_for_db);+ if parent != "/" && !backend.is_directory(&parent)? {+ return Err(Error::not_found(&parent));+ }- // Check parent exists- let parent = backend.parent_path(&normalized);- if parent != "/" {- if !backend.is_directory(&parent)? {- return Err(Error::not_found(&parent));+ backend.create_file(&normalized_for_db, 0o644, &data_owned)?;+ Ok(true)}- }-- backend.create_file(&normalized, 0o644, data)?;+ })+ .await?;- // Invalidate parent cache+ if created_new {self.cache.invalidate_parent(&normalized).await;}Ok(data.len() as u64)}+ async fn compare_and_write(+ &self,+ path: &str,+ expected: &[u8],+ new_data: &[u8],+ ) -> Result<bool> {+ let normalized = Self::normalize_path(path);+ let normalized_for_db = normalized.clone();+ let expected_owned = expected.to_vec();+ let new_data_owned = new_data.to_vec();+ let changed = self+ .run_blocking_db(move |backend| {+ backend.compare_and_update_file(+ &normalized_for_db,+ &expected_owned,+ &new_data_owned,+ )+ })+ .await?;+ if changed {+ self.cache.invalidate_parent(&normalized).await;+ }+ Ok(changed)+ }++ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {+ let normalized = Self::normalize_path(path);+ let normalized_for_db = normalized.clone();+ let expected_owned = expected.to_vec();+ let changed = self+ .run_blocking_db(move |backend| {+ backend.compare_and_delete_file(&normalized_for_db, &expected_owned)+ })+ .await?;+ if changed {+ self.cache.invalidate_parent(&normalized).await;+ }+ Ok(changed)+ }+async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {let normalized = Self::normalize_path(path);@@ -351,19 +420,21 @@ impl FileSystem for SQLFileSystem {return Ok(files);}- let backend = self.backend.read().await;-- // Check if directory exists- if !backend.path_exists(&normalized)? {- return Err(Error::not_found(&normalized));- }+ let normalized_for_db = normalized.clone();+ let list_path = normalized.clone();+ let entries = self+ .run_blocking_db(move |backend| {+ if !backend.path_exists(&normalized_for_db)? {+ return Err(Error::not_found(&normalized_for_db));+ }- if !backend.is_directory(&normalized)? {- return Err(Error::NotADirectory(normalized));- }+ if !backend.is_directory(&normalized_for_db)? {+ return Err(Error::NotADirectory(normalized_for_db));+ }- // List directory- let entries = backend.list_directory(&normalized)?;+ backend.list_directory(&list_path)+ })+ .await?;// Convert to FileInfolet mut files = Vec::new();@@ -387,9 +458,11 @@ impl FileSystem for SQLFileSystem {async fn stat(&self, path: &str) -> Result<FileInfo> {let normalized = Self::normalize_path(path);- let backend = self.backend.read().await;-- match backend.get_metadata(&normalized)? {+ let normalized_for_db = normalized.clone();+ match self+ .run_blocking_db(move |backend| backend.get_metadata(&normalized_for_db))+ .await?+ {Some(meta) => Ok(FileInfo {name: Self::file_name(&normalized),size: meta.size as u64,diff --git a/crates/ragfs/src/shape/probe.rs b/crates/ragfs/src/shape/probe.rsindex 4a098b39e..254c78e40 100644--- a/crates/ragfs/src/shape/probe.rs+++ b/crates/ragfs/src/shape/probe.rs@@ -2,6 +2,7 @@ use std::sync::Arc;use crate::core::errors::{Error, Result};use crate::core::filesystem::FileSystem;+use crate::core::internal_names::is_hidden_runtime_lock_name;use crate::core::WriteFlag;use crate::crypto;use futures::stream::{self, StreamExt};@@ -9,8 +10,6 @@ use futures::stream::{self, StreamExt};use super::manifest::{StorageShape, SHAPE_MANIFEST_PATH};const SYSTEM_ACCOUNT_ID: &[u8] = b"_system";-const PATH_LOCK_FILE: &str = ".path.ovlock";-const EXACT_LOCK_FILE_PREFIX: &str = ".exact.ovlock.";fn normalize_shape_path(path: &str) -> String {let mut normalized = path.trim().to_string();@@ -36,7 +35,7 @@ fn is_persistent_task_record_path(path: &str) -> bool {fn is_path_lock_record_path(path: &str) -> bool {let name = path.rsplit('/').next().unwrap_or("");- name == PATH_LOCK_FILE || name.starts_with(EXACT_LOCK_FILE_PREFIX)+ is_hidden_runtime_lock_name(name)}/// Read the raw guard-file bytes from the backend root.diff --git a/openviking/async_client.py b/openviking/async_client.pyindex 065f99093..883a6ac31 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -109,11 +109,6 @@ class AsyncOpenViking:await cls._instance.close()cls._instance = None- # Also reset lock manager singleton- from openviking.storage.transaction import reset_lock_manager-- reset_lock_manager()-# ============= Session methods =============def session(self, session_id: Optional[str] = None, must_exist: bool = False) -> Session:diff --git a/openviking/metrics/datasources/observer_state.py b/openviking/metrics/datasources/observer_state.pyindex 86544ac87..68613729e 100644--- a/openviking/metrics/datasources/observer_state.py+++ b/openviking/metrics/datasources/observer_state.py@@ -3,11 +3,10 @@from __future__ import annotations-import timefrom typing import Anyfrom openviking.metrics.core.base import ReadEnvelope-from openviking.storage.transaction import get_lock_manager+from openviking.storage.viking_fs import get_viking_fsfrom openviking_cli.utils import run_asyncfrom .base import DomainStatsMetricDataSource, StateMetricDataSource@@ -62,36 +61,27 @@ class ObserverStateDataSource(DomainStatsMetricDataSource):class LockStateDataSource(StateMetricDataSource):"""- Read lock-manager counters needed by lock-related state collectors.+ Read lock-manager counters from the pathlock observe snapshot.- The datasource inspects active lock handles and derives a stale-handle count using the- current in-process timeout heuristic.+ The datasource reads the ``pathlock_observe()`` snapshot to derive active,+ waiting, and stale lock counts."""def read_lock_state(self) -> ReadEnvelope[tuple[int, int, int]]:"""- Read active and stale lock counts from the global transaction lock manager.+ Read active, waiting, and stale lock counts from the pathlock observe snapshot.Returns:- A tuple of `(active_locks, waiting_locks, stale_handles)` where waiting locks are- currently not tracked separately and therefore remain `0`.+ A tuple of ``(active_locks, waiting_locks, stale_locks_removed)``."""def _read() -> tuple[int, int, int]:- lock_manager = get_lock_manager()- handles = lock_manager.get_active_handles()- active = 0- stale = 0- now = time.time()- for handle in handles.values():- try:- active += len(getattr(handle, "locks", []) or [])- last = getattr(handle, "last_active_at", None)- if last is not None and (now - float(last)) > 600:- stale += 1- except Exception:- continue- return active, 0, stale+ viking_fs = get_viking_fs()+ snapshot = run_async(viking_fs._async_agfs.pathlock_observe())+ active = int(snapshot.get("active_locks", 0))+ waiting = int(snapshot.get("waiting_locks", 0))+ stale = int(snapshot.get("stale_locks_removed", 0))+ return active, waiting, stalereturn self.safe_read(_read, default=(0, 0, 0))diff --git a/openviking/parse/image_rewrite.py b/openviking/parse/image_rewrite.pyindex 66e8e0878..8f2482cb9 100644--- a/openviking/parse/image_rewrite.py+++ b/openviking/parse/image_rewrite.py@@ -11,15 +11,12 @@ images themselves are stored next to the markdown file referencing them).import jsonimport refrom pathlib import Path-from typing import TYPE_CHECKING, Dict, Optional, Set+from typing import Any, Dict, Optional, Setfrom openviking.server.identity import RequestContextfrom openviking.storage.viking_fs import get_viking_fsfrom openviking_cli.utils import get_logger-if TYPE_CHECKING:- from openviking.storage.transaction.lock_handle import LockHandle-logger = get_logger(__name__)_IMAGE_PATTERN = re.compile(r"!\[([^\]]*)\]\(((?:[^()]|\([^()]*\))+)\)")@@ -259,7 +256,7 @@ async def _discover_mappings(async def rewrite_image_uris(root_uri: str,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Optional[Dict[str, Any]] = None,) -> Dict[str, int]:"""Rewrite local image references in markdown files to viking:// URIs.@@ -277,7 +274,7 @@ async def rewrite_image_uris(Args:root_uri: The final VikingFS root URI (e.g. ``viking://resources/doc``)ctx: Optional request context for permissions- lock_handle: Optional lock handle held by the caller. When the caller+ lease_ref: Optional lease reference held by the caller. When the calleralready owns a TREE lock over *root_uri*, forwarding it lets thecleanup ``rm`` reuse that lock instead of conflicting with it.@@ -337,12 +334,11 @@ async def rewrite_image_uris(if rewrite_count > 0:try:- # TODO: This must be optimized once pathlock is pushed down into ragfs.await viking_fs.write_file(md_uri,new_content,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)files_processed += 1references_rewritten += rewrite_count@@ -354,7 +350,9 @@ async def rewrite_image_uris(for map_dir in mappings_by_dir:try:await viking_fs.rm(- f"{map_dir}/{IMAGE_MAPPINGS_FILENAME}", ctx=ctx, lock_handle=lock_handle+ f"{map_dir}/{IMAGE_MAPPINGS_FILENAME}",+ ctx=ctx,+ lease_ref=lease_ref,)except Exception as e:logger.warning(diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.pyindex 3e1fd7457..5182f2b71 100644--- a/openviking/pyagfs/async_client.py+++ b/openviking/pyagfs/async_client.py@@ -253,3 +253,238 @@ class AsyncAGFSClient:) -> Dict[str, Any]:"""Retry pending multi-write sync work for a file or directory path."""return await self.run("system_sync_retry", path, ctx=_fs_ctx_or_default(path, fs_ctx))++ # -- pathlock async wrappers ------------------------------------------------++ async def pathlock_acquire_exact(+ self,+ path: str,+ timeout_secs: float = 0.0,+ owner_lease_ref: Dict[str, Any] | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Acquire an exact lock on a single path."""+ return await self.run(+ "pathlock_acquire_exact",+ _fs_ctx_or_default(path, fs_ctx),+ path,+ timeout_secs,+ owner_lease_ref,+ )++ async def pathlock_acquire_exact_batch(+ self,+ paths: list[str],+ timeout_secs: float = 0.0,+ owner_lease_ref: Dict[str, Any] | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Acquire exact locks on multiple paths."""+ return await self.run(+ "pathlock_acquire_exact_batch",+ _fs_ctx_or_default(paths[0] if paths else "/", fs_ctx),+ paths,+ timeout_secs,+ owner_lease_ref,+ )++ async def pathlock_acquire_tree(+ self,+ path: str,+ timeout_secs: float = 0.0,+ owner_lease_ref: Dict[str, Any] | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Acquire a tree lock on a single path."""+ return await self.run(+ "pathlock_acquire_tree",+ _fs_ctx_or_default(path, fs_ctx),+ path,+ timeout_secs,+ owner_lease_ref,+ )++ async def pathlock_acquire_tree_batch(+ self,+ paths: list[str],+ timeout_secs: float = 0.0,+ owner_lease_ref: Dict[str, Any] | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Acquire tree locks on multiple paths."""+ return await self.run(+ "pathlock_acquire_tree_batch",+ _fs_ctx_or_default(paths[0] if paths else "/", fs_ctx),+ paths,+ timeout_secs,+ owner_lease_ref,+ )++ async def pathlock_acquire_exact_tree_batch(+ self,+ exact_paths: list[str],+ tree_paths: list[str],+ timeout_secs: float = 0.0,+ owner_lease_ref: Dict[str, Any] | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Acquire a mixed batch of exact and tree locks."""+ first = exact_paths[0] if exact_paths else (tree_paths[0] if tree_paths else "/")+ return await self.run(+ "pathlock_acquire_exact_tree_batch",+ _fs_ctx_or_default(first, fs_ctx),+ exact_paths,+ tree_paths,+ timeout_secs,+ owner_lease_ref,+ )++ async def pathlock_acquire_batch(+ self,+ requests: list[Dict[str, str]],+ timeout_secs: float = 0.0,+ owner_lease_ref: Dict[str, Any] | None = None,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Acquire a batch of locks from a list of request dicts."""+ if not requests:+ raise ValueError("pathlock request batch must not be empty")+ for request in requests:+ path = request.get("path")+ if not path or not path.startswith("/"):+ raise ValueError("pathlock request.path must be an absolute path")+ if request.get("kind") not in {"exact", "tree"}:+ raise ValueError("pathlock request.kind must be 'exact' or 'tree'")+ first = requests[0]["path"]+ return await self.run(+ "pathlock_acquire_batch",+ _fs_ctx_or_default(first, fs_ctx),+ requests,+ timeout_secs,+ owner_lease_ref,+ )++ async def pathlock_as_borrowed(+ self,+ owned_lease_ref: Dict[str, Any],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Create a borrowed view of an owned lease."""+ return await self.run(+ "pathlock_as_borrowed",+ _fs_ctx_or_default("/", fs_ctx),+ owned_lease_ref,+ )++ async def pathlock_refresh(+ self,+ owned_lease_ref: Dict[str, Any],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> str:+ """Refresh an owned lease. Returns 'refreshed', 'lost', or 'failed'."""+ return await self.run(+ "pathlock_refresh",+ _fs_ctx_or_default("/", fs_ctx),+ owned_lease_ref,+ )++ async def pathlock_release(+ self,+ owned_lease_ref: Dict[str, Any],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> None:+ """Release an owned lease."""+ await self.run(+ "pathlock_release",+ _fs_ctx_or_default("/", fs_ctx),+ owned_lease_ref,+ )++ async def pathlock_release_selected(+ self,+ owned_lease_ref: Dict[str, Any],+ lock_paths: list[str],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> None:+ """Release selected lock paths from an owned lease."""+ await self.run(+ "pathlock_release_selected",+ _fs_ctx_or_default("/", fs_ctx),+ owned_lease_ref,+ lock_paths,+ )++ async def pathlock_to_handoff(+ self,+ owned_lease_ref: Dict[str, Any],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Export a handoff ref from an owned lease."""+ return await self.run(+ "pathlock_to_handoff",+ _fs_ctx_or_default("/", fs_ctx),+ owned_lease_ref,+ )++ async def pathlock_handoff(+ self,+ owned_lease_ref: Dict[str, Any],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> None:+ """Mark an owned lease as handed off."""+ await self.run(+ "pathlock_handoff",+ _fs_ctx_or_default("/", fs_ctx),+ owned_lease_ref,+ )++ async def pathlock_adopt(+ self,+ handoff_ref: Dict[str, Any],+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Adopt a handoff ref, returning a new owned lease."""+ return await self.run(+ "pathlock_adopt",+ _fs_ctx_or_default("/", fs_ctx),+ handoff_ref,+ )++ async def pathlock_is_locked(+ self,+ path: str,+ ignore_stale: bool = True,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> bool:+ """Check if a path is locked."""+ return await self.run(+ "pathlock_is_locked",+ _fs_ctx_or_default(path, fs_ctx),+ path,+ ignore_stale,+ )++ async def pathlock_observe(+ self,+ *,+ fs_ctx: Dict[str, str] | None = None,+ ) -> Dict[str, Any]:+ """Return an observability snapshot of current lock state."""+ return await self.run(+ "pathlock_observe",+ _fs_ctx_or_default("/", fs_ctx),+ )diff --git a/openviking/server/api_keys/legacy.py b/openviking/server/api_keys/legacy.pyindex d19b1095e..5a1910ee4 100644--- a/openviking/server/api_keys/legacy.py+++ b/openviking/server/api_keys/legacy.py@@ -14,10 +14,10 @@ from argon2 import PasswordHasherfrom argon2.exceptions import VerifyMismatchErrorfrom openviking.pyagfs import AGFSAlreadyExistsError, AGFSNotFoundError, AsyncAGFSClient+from openviking.pyagfs.async_client import fs_ctx_from_agfs_pathfrom openviking.server.api_keys.models import AccountInfo, UserKeyEntryfrom openviking.server.identity import ResolvedIdentity, Rolefrom openviking.storage.errors import LockAcquisitionError, ResourceBusyError-from openviking.storage.transaction import LockContext, get_lock_managerfrom openviking.storage.viking_fs import VikingFSfrom openviking_cli.exceptions import (AlreadyExistsError,@@ -383,7 +383,9 @@ class LegacyAPIKeyManager:await self._save_users_json(account_id)- async def regenerate_key(self, account_id: str, user_id: str, seed: Optional[str] = None) -> str:+ async def regenerate_key(+ self, account_id: str, user_id: str, seed: Optional[str] = None+ ) -> str:"""Regenerate a user's API key. Old key is immediately invalidated."""account = self._accounts.get(account_id)if account is None:@@ -635,14 +637,34 @@ class LegacyAPIKeyManager:except AGFSNotFoundError:return None- async def _write_json(self, path: str, data: dict) -> None:+ @staticmethod+ def _fs_ctx_with_lease(path: str, lease_ref: object | None) -> Dict[str, str] | None:+ """Build an AGFS fs_ctx that preserves account_id and an optional lease_ref."""+ if lease_ref is None:+ return None+ ref = None+ if isinstance(lease_ref, dict):+ ref = lease_ref.get("lease_ref")+ else:+ ref = getattr(lease_ref, "lease_ref", None) or getattr(lease_ref, "id", None)+ if not isinstance(ref, str) or not ref:+ return None+ fs_ctx = fs_ctx_from_agfs_path(path)+ fs_ctx["lease_ref"] = ref+ return fs_ctx++ async def _write_json(self, path: str, data: dict, lease_ref: object | None = None) -> None:"""Write a JSON file to AGFS with encryption support."""content = json.dumps(data, ensure_ascii=False, indent=2)if isinstance(content, str):content = content.encode("utf-8")await self._ensure_parent_dirs_async(path)- await self._async_agfs.write(path, content)+ await self._async_agfs.write(+ path,+ content,+ fs_ctx=self._fs_ctx_with_lease(path, lease_ref),+ )async def _ensure_parent_dirs_async(self, path: str) -> None:"""Recursively create all parent directories for a file path."""@@ -654,37 +676,38 @@ class LegacyAPIKeyManager:async def _save_accounts_json(self) -> None:"""Persist the global accounts list."""try:- async with LockContext(- get_lock_manager(), [ACCOUNTS_PATH], lock_mode="exact", timeout=10.0- ):- data = {- "accounts": {- aid: {"created_at": info.created_at}- for aid, info in self._accounts.items()- }- }- await self._write_json(ACCOUNTS_PATH, data)+ lease = await self._async_agfs.pathlock_acquire_exact(ACCOUNTS_PATH, timeout_secs=10.0)except LockAcquisitionError as exc:raise ResourceBusyError("Another account operation is in progress. Please retry.",uri=ACCOUNTS_PATH,conflict_type="account_registry_busy",) from exc+ try:+ data = {+ "accounts": {+ aid: {"created_at": info.created_at} for aid, info in self._accounts.items()+ }+ }+ await self._write_json(ACCOUNTS_PATH, data, lease_ref=lease)+ finally:+ await self._async_agfs.pathlock_release(lease)async def _save_users_json(self, account_id: str) -> None:"""Persist a single account's user registry."""path = USERS_PATH_TEMPLATE.format(account_id=account_id)try:- async with LockContext(- get_lock_manager(), [path], lock_mode="exact", timeout=10.0- ):- account = self._accounts.get(account_id)- if account is None:- return- await self._write_json(path, {"users": account.users})+ lease = await self._async_agfs.pathlock_acquire_exact(path, timeout_secs=10.0)except LockAcquisitionError as exc:raise ResourceBusyError("Another user operation is in progress for this account. Please retry.",uri=path,conflict_type="user_registry_busy",) from exc+ try:+ account = self._accounts.get(account_id)+ if account is None:+ return+ await self._write_json(path, {"users": account.users}, lease_ref=lease)+ finally:+ await self._async_agfs.pathlock_release(lease)diff --git a/openviking/server/temp_upload_store.py b/openviking/server/temp_upload_store.pyindex e79a6e10f..290394cc7 100644--- a/openviking/server/temp_upload_store.py+++ b/openviking/server/temp_upload_store.py@@ -17,7 +17,7 @@ from typing import Any, Optionalfrom openviking.server.config import ServerConfig, TempUploadConfigfrom openviking.server.identity import RequestContext, Rolefrom openviking.server.local_input_guard import _read_upload_meta-from openviking.storage.transaction import get_lock_manager+from openviking.storage.errors import LockAcquisitionErrorfrom openviking.storage.viking_fs import get_viking_fsfrom openviking_cli.exceptions import InvalidArgumentError, PermissionDeniedErrorfrom openviking_cli.utils.config.open_viking_config import get_openviking_config@@ -36,7 +36,7 @@ class ResolvedTempUpload:async def cleanup(self) -> None:if self.lock_handle is not None:with suppress(Exception):- await get_lock_manager().release(self.lock_handle)+ await get_viking_fs()._async_agfs.pathlock_release(self.lock_handle)self.lock_handle = Noneif self.mode == "shared" and self.local_path:@@ -142,7 +142,12 @@ class TempUploadStore:meta = await self._read_shared_meta(shared_id, ctx)meta["state"] = "uploaded"meta["updated_at"] = int(time.time())- await self._write_shared_meta(shared_id, ctx, meta)+ await self._write_shared_meta(+ shared_id,+ ctx,+ meta,+ lease_ref=resolved.lock_handle,+ )async def mark_consumed(self, resolved: ResolvedTempUpload, ctx: RequestContext) -> None:shared_id = _parse_shared_temp_file_id(resolved.temp_file_id)@@ -153,7 +158,7 @@ class TempUploadStore:uri,recursive=True,ctx=self._internal_ctx(ctx),- lock_handle=resolved.lock_handle,+ lease_ref=resolved.lock_handle,)async def try_cleanup_invalid_or_expired(@@ -315,9 +320,9 @@ class TempUploadStore:_shared_upload_uri(self.temp_cfg, ctx, upload_id),ctx=internal_ctx,)- handle = get_lock_manager().create_handle()- acquired = await get_lock_manager().acquire_tree(handle, lock_path, timeout=0.0)- if not acquired:+ try:+ lease = await vfs._async_agfs.pathlock_acquire_tree(lock_path, timeout_secs=0.0)+ except LockAcquisitionError:raise PermissionDeniedError("Temporary upload is being consumed.")try:@@ -328,7 +333,7 @@ class TempUploadStore:meta["state"] = "consuming"meta["updated_at"] = now- await self._write_shared_meta(upload_id, ctx, meta)+ await self._write_shared_meta(upload_id, ctx, meta, lease_ref=lease)file_ext = meta.get("file_ext") or ".tmp"fd, temp_path = tempfile.mkstemp(prefix="ov_shared_upload_", suffix=file_ext)@@ -347,11 +352,11 @@ class TempUploadStore:temp_file_id=temp_file_id,original_filename=meta.get("original_filename") or None,local_path=temp_path,- lock_handle=handle,+ lock_handle=lease,)except Exception:with suppress(Exception):- await get_lock_manager().release(handle)+ await vfs._async_agfs.pathlock_release(lease)raiseasync def _read_shared_meta(self, upload_id: str, ctx: RequestContext) -> dict[str, Any]:@@ -370,12 +375,15 @@ class TempUploadStore:upload_id: str,ctx: RequestContext,meta: dict[str, Any],+ lease_ref: Any = None,) -> None:+ """Write shared-upload metadata under an optional existing pathlock lease."""meta_uri = _shared_meta_uri(self.temp_cfg, ctx, upload_id)await get_viking_fs().write_file(meta_uri,json.dumps(meta, ensure_ascii=False),ctx=self._internal_ctx(ctx),+ lease_ref=lease_ref,)def _validate_shared_meta(diff --git a/openviking/server/user_config.py b/openviking/server/user_config.pyindex 4a93fc776..908d5a858 100644--- a/openviking/server/user_config.py+++ b/openviking/server/user_config.py@@ -12,13 +12,11 @@ from typing import TYPE_CHECKING, Any, AsyncIterator, Callable, Optional, TypeVafrom openviking.core.namespace import canonical_user_rootfrom openviking.core.uri_validation import validate_content_target_urifrom openviking.server.config import AddTargetsConfig, UserConfig-from openviking.storage.transaction import LockContext, get_lock_managerfrom openviking_cli.exceptions import InvalidArgumentError, NotFoundErrorif TYPE_CHECKING:from openviking.server.config import ServerConfigfrom openviking.server.identity import RequestContext- from openviking.storage.transaction import LockHandlefrom openviking.storage.viking_fs import VikingFS@@ -40,14 +38,20 @@ async def _user_config_lock(viking_fs: VikingFS,uri: str,ctx: RequestContext,-) -> AsyncIterator[Optional[LockHandle]]:+) -> AsyncIterator[Optional[dict[str, Any]]]:uri_to_path = getattr(viking_fs, "_uri_to_path", None)- if not callable(uri_to_path):+ agfs = getattr(viking_fs, "_async_agfs", None)+ acquire = getattr(agfs, "pathlock_acquire_exact", None)+ release = getattr(agfs, "pathlock_release", None)+ if not callable(uri_to_path) or not callable(acquire) or not callable(release):yield Nonereturnpath = uri_to_path(uri, ctx=ctx)- async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:- yield handle+ lease = await acquire(path)+ try:+ yield lease+ finally:+ await release(lease)def _user_config_from_payload(payload: Any) -> UserConfig:@@ -156,7 +160,7 @@ async def update_user_config(sort_keys=True,),ctx=ctx,- lock_handle=handle,+ lease_ref=handle,)return result@@ -177,7 +181,7 @@ async def write_user_config(sort_keys=True,),ctx=ctx,- lock_handle=handle,+ lease_ref=handle,)return runtimediff --git a/openviking/service/core.py b/openviking/service/core.pyindex 98a13f81d..ca3964804 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -31,7 +31,6 @@ from openviking.storage.index_consistency import check_index_consistencyfrom openviking.storage.queuefs.add_resource_processor import AddResourceProcessorfrom openviking.storage.queuefs.queue_manager import QueueManager, init_queue_managerfrom openviking.storage.queuefs.session_commit_processor import SessionCommitProcessor-from openviking.storage.transaction import LockManager, init_lock_managerfrom openviking.storage.viking_fs import VikingFS, init_viking_fsfrom openviking.utils.agfs_utils import (build_runtime_ragfs_binding_config,@@ -88,7 +87,7 @@ class OpenVikingService:self._resource_processor: Optional[ResourceProcessor] = Noneself._skill_processor: Optional[SkillProcessor] = Noneself._session_compressor: Optional["SessionCompressorV2"] = None- self._lock_manager: Optional[LockManager] = None+self._directory_initializer: Optional[DirectoryInitializer] = Noneself._watch_scheduler: Optional[WatchScheduler] = Noneself._encryptor: Optional[Any] = None@@ -173,16 +172,7 @@ class OpenVikingService:if self._queue_manager:self._queue_manager.setup_standard_queues(self._vikingdb_manager, start=False)- # Initialize LockManager (fail-fast if RAGFS missing)- if self._agfs_client is None:- raise RuntimeError("RAGFS client not initialized for LockManager")- tx_cfg = config.transaction- self._lock_manager = init_lock_manager(- agfs=self._agfs_client,- lock_timeout=tx_cfg.lock_timeout,- lock_expire=tx_cfg.lock_expire,- redo_recovery_enabled=tx_cfg.redo_recovery_enabled,- )+ # PathLock has been moved to Rust ragfs; Python-layer LockManager is no longer needed.set_task_tracker(config.build_task_tracker(self._agfs_client))def _build_ragfs_binding_config(self) -> Any:@@ -232,11 +222,6 @@ class OpenVikingService:"""Get VikingDBManager instance."""return self._vikingdb_manager- @property- def lock_manager(self) -> Optional[LockManager]:- """Get LockManager instance."""- return self._lock_manager-@propertydef session_compressor(self) -> Optional["SessionCompressorV2"]:"""Get SessionCompressor instance."""@@ -376,11 +361,6 @@ class OpenVikingService:skill_processor=self._skill_processor,)- # Start LockManager if initialized- if self._lock_manager:- await self._lock_manager.start()- logger.info("LockManager started")-self._watch_scheduler = WatchScheduler(resource_service=self._resource_service,viking_fs=self._viking_fs,@@ -437,6 +417,7 @@ class OpenVikingService:self._resource_service,asyncio.get_running_loop(),queue_name,+ self._viking_fs,),allow_create=True,)@@ -476,10 +457,6 @@ class OpenVikingService:self._queue_manager = Nonelogger.info("Queue manager stopped")- if self._lock_manager:- await self._lock_manager.stop()- self._lock_manager = None-if self._vikingdb_manager:self._vikingdb_manager.mark_closing()diff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.pyindex d0a8f8625..eccde2ee2 100644--- a/openviking/service/debug_service.py+++ b/openviking/service/debug_service.py@@ -11,14 +11,14 @@ from openviking.server.identity import RequestContextfrom openviking.storage import VikingDBManagerfrom openviking.storage.observers import (FilesystemObserver,- LockObserver,ModelsObserver,QueueObserver,RetrievalObserver,VikingDBObserver,)from openviking.storage.queuefs import get_queue_manager-from openviking.storage.transaction import get_lock_manager+from openviking.storage.viking_fs import get_viking_fs+from openviking_cli.utils import run_asyncfrom openviking_cli.utils.config import OpenVikingConfigfrom openviking_cli.utils.logger import get_logger@@ -165,9 +165,10 @@ class ObserverService:@propertydef lock(self) -> ComponentStatus:- """Get lock system status."""+ """Get lock system status via pathlock_observe snapshot."""try:- lock_manager = get_lock_manager()+ viking_fs = get_viking_fs()+ snapshot = run_async(viking_fs._async_agfs.pathlock_observe())except Exception:return ComponentStatus(name="lock",@@ -175,12 +176,22 @@ class ObserverService:has_errors=True,status="Not initialized",)- observer = LockObserver(lock_manager)+ active = snapshot.get("active_locks", 0)+ waiting = snapshot.get("waiting_locks", 0)+ stale = snapshot.get("stale_locks_removed", 0)+ conflicts = snapshot.get("conflicts", [])+ has_errors = bool(conflicts) or stale > 0+ lines = [+ f"Active locks: {active}",+ f"Waiting locks: {waiting}",+ f"Stale locks removed: {stale}",+ f"Conflicts: {len(conflicts)}",+ ]return ComponentStatus(name="lock",- is_healthy=observer.is_healthy(),- has_errors=observer.has_errors(),- status=observer.get_status_table(),+ is_healthy=not has_errors,+ has_errors=has_errors,+ status="\n".join(lines),)@property@@ -222,10 +233,8 @@ class ObserverService:# Call get_stats on the RAGFS clientimport asyncio- stats = await asyncio.to_thread(- self._agfs_client.get_stats,- mount_path- )++ stats = await asyncio.to_thread(self._agfs_client.get_stats, mount_path)return statsexcept Exception as e:logger.error(f"Error getting filesystem stats: {e}")diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.pyindex 57a261024..9789a178f 100644--- a/openviking/service/reindex_executor.py+++ b/openviking/service/reindex_executor.py@@ -31,13 +31,6 @@ from openviking.storage.expr import And, Eq, Or, PathScopefrom openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverterfrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor-from openviking.storage.transaction import (- NO_LOCK,- BorrowedLockLease,- LockContext,- LockLease,- get_lock_manager,-)from openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -104,7 +97,7 @@ class _ReindexCounters:class _ReindexRunContext:ctx: RequestContextcounters: _ReindexCounters- lock: LockLease = NO_LOCK+ lock: dict | None = None@dataclass@@ -442,71 +435,73 @@ class ReindexExecutor:if telemetry_id:wait_tracker.register_request(telemetry_id)+ lease = await service.viking_fs._async_agfs.pathlock_acquire_tree(path)try:- async with LockContext(get_lock_manager(), [path], lock_mode="tree") as lock_handle:- run = _ReindexRunContext(- ctx=ctx,+ borrowed = await service.viking_fs._async_agfs.pathlock_as_borrowed(lease)+ run = _ReindexRunContext(+ ctx=ctx,+ counters=counters,+ lock=borrowed,+ )+ if mode == "prune_orphans":+ await self._prune_orphan_vectors(+ uri=uri,+ object_type=object_type,+ dry_run=dry_run,counters=counters,- lock=BorrowedLockLease.from_handle(get_lock_manager(), lock_handle),+ ctx=ctx,+ )+ elif object_type == "global_namespace":+ await self._reindex_global_namespace(+ uri=uri,+ mode=mode,+ run=run,+ )+ elif object_type == "user_namespace":+ await self._reindex_user_namespace(+ uri=uri,+ mode=mode,+ run=run,+ )+ elif object_type == "skill_namespace":+ await self._reindex_skill_namespace(+ uri=uri,+ mode=mode,+ run=run,+ )+ elif object_type == "resource":+ await self._reindex_resource(+ uri=uri,+ mode=mode,+ run=run,+ )+ elif object_type == "skill":+ await self._reindex_skill(+ uri=uri,+ mode=mode,+ run=run,+ )+ elif object_type == "memory":+ await self._reindex_memory(+ uri=uri,+ mode=mode,+ run=run,+ )+ else:+ raise OpenVikingError(+ f"Unsupported reindex type: {object_type}",+ code="UNSUPPORTED_URI",+ details={"uri": uri},)- if mode == "prune_orphans":- await self._prune_orphan_vectors(- uri=uri,- object_type=object_type,- dry_run=dry_run,- counters=counters,- ctx=ctx,- )- elif object_type == "global_namespace":- await self._reindex_global_namespace(- uri=uri,- mode=mode,- run=run,- )- elif object_type == "user_namespace":- await self._reindex_user_namespace(- uri=uri,- mode=mode,- run=run,- )- elif object_type == "skill_namespace":- await self._reindex_skill_namespace(- uri=uri,- mode=mode,- run=run,- )- elif object_type == "resource":- await self._reindex_resource(- uri=uri,- mode=mode,- run=run,- )- elif object_type == "skill":- await self._reindex_skill(- uri=uri,- mode=mode,- run=run,- )- elif object_type == "memory":- await self._reindex_memory(- uri=uri,- mode=mode,- run=run,- )- else:- raise OpenVikingError(- f"Unsupported reindex type: {object_type}",- code="UNSUPPORTED_URI",- details={"uri": uri},- )- if telemetry_id and mode != "prune_orphans":- await wait_tracker.wait_for_request(telemetry_id)- self._apply_embedding_wait_status(- counters,- wait_tracker.build_queue_status(telemetry_id),- )+ if telemetry_id and mode != "prune_orphans":+ await wait_tracker.wait_for_request(telemetry_id)+ self._apply_embedding_wait_status(+ counters,+ wait_tracker.build_queue_status(telemetry_id),+ )finally:+ await service.viking_fs._async_agfs.pathlock_release(lease)if telemetry_id:wait_tracker.cleanup(telemetry_id)@@ -916,7 +911,7 @@ class ReindexExecutor:uri: str,context_type: str,ctx: RequestContext,- lock: LockLease = NO_LOCK,+ lock: dict | None = None,) -> None:processor = SemanticProcessor(max_concurrent_llm=get_openviking_config().vlm.max_concurrent,@@ -932,7 +927,7 @@ class ReindexExecutor:role=str(ctx.role),skip_vectorization=True,)- await processor.on_dequeue({"data": msg.to_json()}, lock=lock.as_borrowed())+ await processor.on_dequeue({"data": msg.to_json()}, lock=lock)async def _reindex_resource_vectors(self,@@ -1092,7 +1087,8 @@ class ReindexExecutor:viking_fs = get_viking_fs()marker_name = ".abstract.md" if level == ContextLevel.ABSTRACT else ".overview.md"lock_path = viking_fs._uri_to_path(f"{dir_uri}/{marker_name}", ctx=ctx)- async with LockContext(get_lock_manager(), [lock_path], lock_mode="exact"):+ lease = await viking_fs._async_agfs.pathlock_acquire_exact(lock_path)+ try:abstract = await self._read_directory_abstract(dir_uri, ctx=ctx)if level == ContextLevel.ABSTRACT:vector_text = abstract@@ -1114,6 +1110,8 @@ class ReindexExecutor:level=level,ctx=ctx,)+ finally:+ await viking_fs._async_agfs.pathlock_release(lease)async def delete_uri_level(self, *, uri: str, level: ContextLevel, ctx: RequestContext) -> int:"""Delete ONLY the vector record at ``(uri, level)``. Returns count.diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.pyindex 3036d0a91..7be5ef7d7 100644--- a/openviking/service/resource_service.py+++ b/openviking/service/resource_service.py@@ -42,7 +42,6 @@ from openviking.server.user_config import ()from openviking.storage import VikingDBManagerfrom openviking.storage.queuefs import QueueManager, get_queue_manager-from openviking.storage.transaction import NO_LOCK, LockLeasefrom openviking.storage.viking_fs import VikingFSfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -382,6 +381,47 @@ class ResourceService:if not self._viking_fs:raise NotInitializedError("VikingFS")+ async def _lock_to_handoff_payload(self, lock_ref: Any) -> Optional[Dict[str, Any]]:+ """Convert either a native pathlock ref or legacy lease into a handoff payload."""+ if lock_ref is None:+ return None+ async_agfs = getattr(self._viking_fs, "_async_agfs", None)+ if async_agfs is not None:+ return await async_agfs.pathlock_to_handoff(lock_ref)+ to_handoff = getattr(lock_ref, "to_handoff", None)+ if callable(to_handoff):+ handoff = to_handoff()+ return handoff.to_dict() if hasattr(handoff, "to_dict") else handoff+ return lock_ref if isinstance(lock_ref, dict) else None++ async def _handoff_lock_ref(self, lock_ref: Any) -> None:+ """Transfer ownership for either a native pathlock ref or legacy lease."""+ if lock_ref is None:+ return+ async_agfs = getattr(self._viking_fs, "_async_agfs", None)+ if async_agfs is not None:+ await async_agfs.pathlock_handoff(lock_ref)+ return+ handoff = getattr(lock_ref, "handoff", None)+ if callable(handoff):+ result = handoff()+ if inspect.isawaitable(result):+ await result++ async def _release_lock_ref(self, lock_ref: Any) -> None:+ """Release either a native pathlock ref or legacy lease."""+ if lock_ref is None:+ return+ async_agfs = getattr(self._viking_fs, "_async_agfs", None)+ if async_agfs is not None:+ await async_agfs.pathlock_release(lock_ref)+ return+ close = getattr(lock_ref, "close", None)+ if callable(close):+ result = close()+ if inspect.isawaitable(result):+ await result+async def close_background_tasks(self) -> None:"""Cancel in-flight connector monitoring tasks during service shutdown."""if not self._background_tasks:@@ -397,33 +437,36 @@ class ResourceService:msg: Any,*,queue_name: str,- resource_lock: LockLease = NO_LOCK,+ resource_lock: Optional[Dict[str, Any]] = None,) -> Any:- """Persist a job before its TaskRecord so a crash cannot orphan the task."""+ """Persist a job and fully own the passed lock until handoff or release completes."""from openviking.service.task_tracker import get_task_trackerfrom openviking.storage.queuefs import get_queue_manager+ tracker = get_task_tracker()try:await get_queue_manager().enqueue(queue_name, msg.to_dict())- await resource_lock.handoff()+ if resource_lock is not None:+ await self._handoff_lock_ref(resource_lock)+ resource_lock = None+ task = await tracker.create(+ "add_resource",+ resource_id=None if msg.defer_target_resolution else msg.root_uri,+ account_id=msg.account_id,+ user_id=msg.user_id,+ task_id=msg.task_id,+ )+ await tracker.update_stage(+ task.task_id,+ "queued",+ account_id=msg.account_id,+ user_id=msg.user_id,+ )except BaseException:- await resource_lock.close()+ if resource_lock is not None:+ await self._release_lock_ref(resource_lock)raise- tracker = get_task_tracker()- task = await tracker.create(- "add_resource",- resource_id=None if msg.defer_target_resolution else msg.root_uri,- account_id=msg.account_id,- user_id=msg.user_id,- task_id=msg.task_id,- )- await tracker.update_stage(- task.task_id,- "queued",- account_id=msg.account_id,- user_id=msg.user_id,- )return taskasync def execute_add_resource_job(@@ -431,11 +474,10 @@ class ResourceService:msg: Any,*,ctx: RequestContext,- resource_lock: Optional[LockLease],+ resource_lock: Optional[Dict[str, Any]],stage_callback: Callable[[str], Any],) -> Dict[str, Any]:"""Execute one durable add-resource job inside its QueueFS consumer."""- resource_lock = resource_lock or NO_LOCKif msg.prepared is None:target_uri = msg.root_uriparent_uri = None@@ -534,18 +576,15 @@ class ResourceService:self,root_uri: str,ctx: RequestContext,- ) -> LockLease:+ ) -> Dict[str, Any]:"""Acquire a fresh lock when a recovered job's old handoff was released."""if not self._resource_processor or not self._viking_fs:raise NotInitializedError("ResourceProcessor")- from openviking.storage.transaction import get_lock_managerdst_path = self._viking_fs._uri_to_path(root_uri, ctx=ctx)- return await self._resource_processor.acquire_resource_lock(- get_lock_manager(),+ return await self._viking_fs._async_agfs.pathlock_acquire_tree(dst_path,- uri=root_uri,- timeout=0.0,+ timeout_secs=0.0,)async def enqueue_git_add_resource(@@ -596,7 +635,7 @@ class ResourceService:from openviking.storage.queuefs.add_resource_msg import AddResourceMsg- resource_lock: LockLease = NO_LOCK+ resource_lock: Optional[Dict[str, Any]] = Nonetry:if enforce_public_remote_targets and is_remote_resource_source(path):path = require_remote_resource_source(path)@@ -615,7 +654,11 @@ class ResourceService:)task_id = str(uuid4())- lock_handoff = resource_lock.to_handoff()+ lock_handoff = (+ await self._viking_fs._async_agfs.pathlock_to_handoff(resource_lock)+ if resource_lock is not None+ else None+ )processor_args = {key: valuefor key, value in kwargs.items()@@ -630,7 +673,7 @@ class ResourceService:user_id=ctx.user.user_id,role=str(ctx.role),actor_peer_id=ctx.actor_peer_id,- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,+ lock_handoff=lock_handoff,reason=reason,instruction=instruction,timeout=timeout,@@ -653,19 +696,21 @@ class ResourceService:source_name=source_name,args=self._processor_args_for_watch_run(processor_args),)+ enqueue_lock = resource_lock+ resource_lock = Nonetask = await self._enqueue_add_resource_job(msg,queue_name=QueueManager.ADD_RESOURCE,- resource_lock=resource_lock,+ resource_lock=enqueue_lock,)- resource_lock = NO_LOCKreturn {"status": "success","root_uri": root_uri,"task_id": task.task_id,}except Exception:- await resource_lock.close()+ if resource_lock is not None:+ await self._viking_fs._async_agfs.pathlock_release(resource_lock)raiseasync def _plan_resource_target(@@ -676,7 +721,7 @@ class ResourceService:target: ContentTargetSpec,source_name: Optional[str],source_info: _ResourceSourceInfo,- ) -> tuple[str, LockLease]:+ ) -> tuple[str, Optional[Dict[str, Any]]]:if not self._resource_processor or not self._viking_fs:raise NotInitializedError("ResourceProcessor")@@ -698,14 +743,10 @@ class ResourceService:ctx=ctx,)- from openviking.storage.transaction import get_lock_manager-dst_path = self._viking_fs._uri_to_path(root_uri, ctx=ctx)- resource_lock = await self._resource_processor.acquire_resource_lock(- get_lock_manager(),+ resource_lock = await self._viking_fs._async_agfs.pathlock_acquire_tree(dst_path,- uri=root_uri,- timeout=0.0,+ timeout_secs=0.0,)return root_uri, resource_lock@@ -1037,7 +1078,7 @@ class ResourceService:enforce_public_remote_targets: bool = False,watch_auth_state: Optional[Dict[str, Any]] = None,parser_args: Optional[Dict[str, Any]] = None,- resource_lock: Optional[LockLease] = None,+ resource_lock: Optional[Dict[str, Any]] = None,stage_callback: Optional[Callable[[str], Any]] = None,**kwargs,) -> Dict[str, Any]:@@ -1048,7 +1089,7 @@ class ResourceService:telemetry_id = register_wait_telemetry(wait)request_wait_tracker = get_request_wait_tracker()job_enqueued = False- deferred_lock: LockLease = NO_LOCK+ deferred_lock: Optional[Dict[str, Any]] = Noneingest_tag_kwargs = self._add_resource_ingest_tag_kwargs(tags=tags,tag_mode=tag_mode,@@ -1158,19 +1199,18 @@ class ResourceService:)if self._viking_fs is None:raise NotInitializedError("VikingFS")- from openviking.storage.errors import LockAcquisitionError, ResourceBusyError- from openviking.storage.transaction import OwnedLockLease, get_lock_manager+ from openviking.storage.errors import ResourceBusyError- lock_manager = get_lock_manager()- lock_lease: LockLease = NO_LOCK+ lock_lease: Optional[Dict[str, Any]] = None- async def _reserve_tree(uri: str) -> LockLease:+ async def _reserve_tree(uri: str) -> Dict[str, Any]:dst_path = self._viking_fs._uri_to_path(uri, ctx=ctx)try:- return await OwnedLockLease.acquire_tree(- lock_manager, dst_path, timeout=0.0+ return await self._viking_fs._async_agfs.pathlock_acquire_tree(+ dst_path,+ timeout_secs=0.0,)- except LockAcquisitionError as exc:+ except Exception as exc:raise ResourceBusyError(f"Resource is busy: {uri}",uri=uri,@@ -1203,7 +1243,7 @@ class ResourceService:if resolved_extension:processor_args["resolved_extension"] = resolved_extension- lock_handoff = lock_lease.to_handoff()+ lock_handoff = await self._lock_to_handoff_payload(lock_lease)msg = AddResourceMsg(task_id=str(uuid4()),telemetry_id=telemetry_id or None,@@ -1230,7 +1270,7 @@ class ResourceService:enforce_public_remote_targets=enforce_public_remote_targets,args=processor_args,source_name=source_name,- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,+ lock_handoff=lock_handoff,skip_watch_management=True,defer_target_resolution=defer_target_resolution,understanding_response_id=understanding_response_id,@@ -1238,16 +1278,17 @@ class ResourceService:tag_mode=tag_mode,)enqueue_started = True+ enqueue_lock = lock_lease+ lock_lease = Nonetask = await self._enqueue_add_resource_job(msg,queue_name=QueueManager.EXTERNAL_PARSE,- resource_lock=lock_lease,+ resource_lock=enqueue_lock,)except BaseException:- if not enqueue_started:- await lock_lease.close()+ if not enqueue_started and lock_lease is not None:+ await self._release_lock_ref(lock_lease)raise- lock_lease = NO_LOCKjob_enqueued = Truelogger.info("[ResourceService] Enqueued AddResourceMsg task_id=%s root_uri=%s",@@ -1301,7 +1342,7 @@ class ResourceService:if result.get("status") == "error":return resultprepared = result.pop("_post_process", None)- deferred_lock = result.pop("_resource_lock", NO_LOCK)+ deferred_lock = result.pop("_resource_lock", None)if wait:if stage_callback is not None:stage_result = stage_callback("processing_queue")@@ -1355,7 +1396,7 @@ class ResourceService:root_uri = result.get("root_uri", "")if not isinstance(prepared, dict):raise InternalError("Deferred resource processing payload is missing")- lock_handoff = deferred_lock.to_handoff()+ lock_handoff = await self._lock_to_handoff_payload(deferred_lock)msg = AddResourceMsg(task_id=str(uuid4()),root_uri=root_uri,@@ -1365,7 +1406,7 @@ class ResourceService:user_id=ctx.user.user_id,role=str(ctx.role),actor_peer_id=ctx.actor_peer_id,- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,+ lock_handoff=lock_handoff,reason=reason,instruction=instruction,timeout=timeout,@@ -1386,12 +1427,13 @@ class ResourceService:tags=tags,tag_mode=tag_mode,)+ enqueue_lock = deferred_lock+ deferred_lock = Nonetask = await self._enqueue_add_resource_job(msg,queue_name=QueueManager.ADD_RESOURCE,- resource_lock=deferred_lock,+ resource_lock=enqueue_lock,)- deferred_lock = NO_LOCKresult["task_id"] = task.task_idjob_enqueued = Trueawait self._manage_watch_if_needed(@@ -1436,8 +1478,8 @@ class ResourceService:if wait or not telemetry_id or not job_enqueued:get_request_wait_tracker().cleanup(telemetry_id)unregister_wait_telemetry(telemetry_id)- if deferred_lock.active:- await deferred_lock.close()+ if deferred_lock is not None:+ await self._release_lock_ref(deferred_lock)async def _link_resource_reason_memory(self,diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.pyindex 8322cd048..8b19a3705 100644--- a/openviking/session/compressor_v2.py+++ b/openviking/session/compressor_v2.py@@ -179,7 +179,9 @@ class SessionCompressorV2:Always create new instance to avoid cross-request state pollution."""return MemoryUpdater(- registry=registry, vikingdb=self.vikingdb, transaction_handle=transaction_handle+ registry=registry,+ vikingdb=self.vikingdb,+ transaction_handle=transaction_handle,)def _split_operations_by_memory_type(@@ -282,17 +284,14 @@ class SessionCompressorV2:telemetry.set("memory.extract.deleted", 0)telemetry.set("memory.extract.skipped", 0)- from openviking.storage.transaction import get_lock_manager, init_lock_manager+ from openviking.storage.errors import LockAcquisitionError- # 初始化锁管理器(仅在有 AGFS 时使用锁机制)+ # 初始化锁(仅在有 AGFS 时使用锁机制)viking_fs = get_viking_fs()- lock_manager = None+ lease = Nonetransaction_handle = None- if viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs:- init_lock_manager(viking_fs.agfs)- lock_manager = get_lock_manager()- transaction_handle = lock_manager.create_handle()- else:+ has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs+ if not has_agfs:logger.debug("AGFS unavailable, running memory extraction without locks")try:@@ -330,7 +329,7 @@ class SessionCompressorV2:context_provider=context_provider,)read_scope = isolation_handler.get_read_scope()- if lock_manager:+ if has_agfs:schemas = orchestrator.context_provider.get_memory_schemas(ctx)exact_lock_paths, tree_lock_dirs = _render_memory_schema_locks(schemas=schemas,@@ -350,28 +349,30 @@ class SessionCompressorV2:# 循环重试获取锁(机制确保不会死锁)while True:- lock_acquired = await lock_manager.acquire_exact_tree_batch(- transaction_handle,- exact_paths=exact_lock_paths,- tree_paths=tree_lock_dirs,- timeout=None,- )- if lock_acquired:+ try:+ lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(+ exact_lock_paths,+ tree_lock_dirs,+ timeout_secs=0.1,+ )break- retry_count += 1- if max_retries > 0 and retry_count >= max_retries:- raise TimeoutError(- "Failed to acquire memory locks after "- f"{retry_count} retries (max={max_retries})"+ except LockAcquisitionError:+ retry_count += 1+ if max_retries > 0 and retry_count >= max_retries:+ raise TimeoutError(+ "Failed to acquire memory locks after "+ f"{retry_count} retries (max={max_retries})"+ )++ last_lock_retry_warning_at = _log_memory_lock_retry(+ retry_count=retry_count,+ max_retries=max_retries,+ last_warning_at=last_lock_retry_warning_at,)+ if retry_interval > 0:+ await asyncio.sleep(retry_interval)- last_lock_retry_warning_at = _log_memory_lock_retry(- retry_count=retry_count,- max_retries=max_retries,- last_warning_at=last_lock_retry_warning_at,- )- if retry_interval > 0:- await asyncio.sleep(retry_interval)+ transaction_handle = leaseorchestrator._transaction_handle = transaction_handle # 传递给 ExtractLoop@@ -469,12 +470,12 @@ class SessionCompressorV2:raisereturn []finally:- # 确保释放所有锁(仅在有锁管理器时)- if lock_manager and transaction_handle:+ # 确保释放所有锁+ if lease is not None:try:- await lock_manager.release(transaction_handle)+ await viking_fs._async_agfs.pathlock_release(lease)except Exception as e:- logger.warning(f"Failed to release transaction lock: {e}")+ logger.warning(f"Failed to release pathlock: {e}")@staticmethoddef _empty_memory_diff(archive_uri: str = "") -> Dict[str, Any]:@@ -592,7 +593,7 @@ class SessionCompressorV2:async def _append_sources_before_unlock(result: MemoryUpdateResult,inheritance_map: Dict[str, List[str]],- lock_handle: Any,+ lease_ref: Any,exp_provider=exp_provider,exp_dir=exp_dir,traj_uri=traj_uri,@@ -612,7 +613,7 @@ class SessionCompressorV2:source_uris,ctx,viking_fs,- lock_handle=lock_handle,+ lease_ref=lease_ref,)exp_result = await self._run_extract_phase(@@ -732,7 +733,7 @@ class SessionCompressorV2:Returns None on failure (unless strict_extract_errors is True, in which casethe exception is re-raised)."""- from openviking.storage.transaction import get_lock_manager, init_lock_manager+ from openviking.storage.errors import LockAcquisitionErrorconfig = get_openviking_config()vlm = config.vlm.get_vlm_instance()@@ -764,15 +765,12 @@ class SessionCompressorV2:thinking=thinking,)- lock_manager = None+ lease = Nonetransaction_handle = None- if viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs:- init_lock_manager(viking_fs.agfs)- lock_manager = get_lock_manager()- transaction_handle = lock_manager.create_handle()+ has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfstry:- if lock_manager:+ if has_agfs:schemas = [schemafor schema in provider.get_memory_schemas(ctx)@@ -792,28 +790,30 @@ class SessionCompressorV2:retry_count = 0last_lock_retry_warning_at = 0.0while True:- lock_acquired = await lock_manager.acquire_exact_tree_batch(- transaction_handle,- exact_paths=exact_lock_paths,- tree_paths=tree_lock_dirs,- timeout=None,- )- if lock_acquired:+ try:+ lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(+ exact_lock_paths,+ tree_lock_dirs,+ timeout_secs=0.1,+ )break- retry_count += 1- if max_retries > 0 and retry_count >= max_retries:- raise TimeoutError(- f"[{phase_label}] Failed to acquire memory locks after "- f"{retry_count} retries (max={max_retries})"+ except LockAcquisitionError:+ retry_count += 1+ if max_retries > 0 and retry_count >= max_retries:+ raise TimeoutError(+ f"[{phase_label}] Failed to acquire memory locks after "+ f"{retry_count} retries (max={max_retries})"+ )+ last_lock_retry_warning_at = _log_memory_lock_retry(+ retry_count=retry_count,+ max_retries=max_retries,+ last_warning_at=last_lock_retry_warning_at,+ phase_label=phase_label,)- last_lock_retry_warning_at = _log_memory_lock_retry(- retry_count=retry_count,- max_retries=max_retries,- last_warning_at=last_lock_retry_warning_at,- phase_label=phase_label,- )- if retry_interval > 0:- await asyncio.sleep(retry_interval)+ if retry_interval > 0:+ await asyncio.sleep(retry_interval)++ transaction_handle = leaseprovider._transaction_handle = transaction_handleorchestrator._transaction_handle = transaction_handle@@ -916,11 +916,11 @@ class SessionCompressorV2:raisereturn Nonefinally:- if lock_manager and transaction_handle:+ if lease is not None:try:- await lock_manager.release(transaction_handle)+ await viking_fs._async_agfs.pathlock_release(lease)except Exception as e:- logger.warning(f"[{phase_label}] Failed to release transaction lock: {e}")+ logger.warning(f"[{phase_label}] Failed to release pathlock: {e}")async def _resolve_supersedes(self,@@ -997,7 +997,7 @@ class SessionCompressorV2:traj_uris: List[str],ctx,viking_fs,- lock_handle: Optional[Any] = None,+ lease_ref: Optional[Any] = None,) -> None:"""Write bidirectional StoredLinks between traj_uris and each exp file.@@ -1010,33 +1010,28 @@ class SessionCompressorV2:for exp_uri in exp_uris:try:- try:- from openviking.storage.transaction import LockContext, get_lock_manager+ lease = lease_ref+ owns_lease = False+ if lease is None:+ lock_path = viking_fs._uri_to_path(exp_uri, ctx=ctx)+ try:+ lease = await viking_fs._async_agfs.pathlock_acquire_exact(lock_path)+ owns_lease = True+ except Exception as e:+ logger.warning(f"Failed to acquire trajectory metadata lock: {e}")+ continue- lock_manager = get_lock_manager()- except Exception:- await self._append_trajectory_metadata(- exp_uri,- normalized_traj_uris,- ctx,- viking_fs,- )- continue-- lock_path = viking_fs._uri_to_path(exp_uri, ctx=ctx)- async with LockContext(- lock_manager,- [lock_path],- lock_mode="exact",- handle=lock_handle,- ) as active_lock_handle:+ try:await self._append_trajectory_metadata(exp_uri,normalized_traj_uris,ctx,viking_fs,- lock_handle=active_lock_handle,+ lease_ref=lease,)+ finally:+ if owns_lease:+ await viking_fs._async_agfs.pathlock_release(lease)except Exception as e:logger.warning(f"Failed to append source trajectories to {exp_uri}: {e}")@@ -1046,7 +1041,7 @@ class SessionCompressorV2:traj_uris: List[str],ctx,viking_fs,- lock_handle=None,+ lease_ref=None,) -> None:from datetime import timezone@@ -1070,12 +1065,11 @@ class SessionCompressorV2:mf.links = new_exp_linksif links_changed:- # TODO: This must be optimized once pathlock is pushed down into ragfs.await viking_fs.write_file(exp_uri,MemoryFileUtils.write(mf),ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)tracer.info(f"[agent_link] wrote exp→traj links -> {exp_uri} (traj_count={len(traj_uris)})"@@ -1084,7 +1078,7 @@ class SessionCompressorV2:tracer.info(f"[agent_link] links already present, skip: {exp_uri}")# Write traj.backlinks — exp_uri already handled above- await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri})+ await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri}, lease_ref=lease_ref)async def _build_memory_diff(self,diff --git a/openviking/session/compressor_v3.py b/openviking/session/compressor_v3.pyindex a198817e3..7838d16eb 100644--- a/openviking/session/compressor_v3.py+++ b/openviking/session/compressor_v3.py@@ -184,7 +184,6 @@ class SessionCompressorV3:return MemoryUpdater(registry=registry,vikingdb=self.vikingdb,- transaction_handle=transaction_handle,)async def _build_memory_diff(diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.pyindex 7596fdc80..2cd9da81e 100644--- a/openviking/session/memory/memory_updater.py+++ b/openviking/session/memory/memory_updater.py@@ -76,14 +76,13 @@ async def write_stored_links(ctx: RequestContext,viking_fs: Any,skip_uris: Optional[set] = None,- lock_handle: Any = None,+ lease_ref: Any = None,) -> List[str]:"""Write StoredLinks to their endpoint files' links/backlinks fields.For each link: from_uri's ``links`` receives the forward link;to_uri's ``backlinks`` receives the reverse reference.Files listed in skip_uris are skipped (caller handles them in the same write).- When lock_handle is provided, all endpoint rewrites reuse that transaction.Returns the endpoint URIs that were successfully rewritten. Callers canuse this to avoid reporting link-only edits for files that failed theread/modify/write step.@@ -91,7 +90,6 @@ async def write_stored_links(from openviking.session.memory.merge_op.link_merge import merge_linksskip = skip_uris or set()- lock_kwargs = {"lock_handle": lock_handle} if lock_handle is not None else {}file_links: Dict[str, Dict[str, List[StoredLink]]] = {}for link in links:if link.from_uri not in skip:@@ -122,7 +120,7 @@ async def write_stored_links(uri,MemoryFileUtils.write(mf),ctx=ctx,- **lock_kwargs,+ lease_ref=lease_ref,)updated_uris.append(uri)except Exception as e:@@ -130,7 +128,6 @@ async def write_stored_links(return updated_uris-def _remap_link_dict(link: Dict[str, Any], uri_remap: Dict[str, str]) -> Dict[str, Any]:remapped = dict(link or {})if remapped.get("from_uri") in uri_remap:@@ -152,6 +149,7 @@ def remap_stored_links(links: List[StoredLink], uri_remap: Dict[str, str]) -> Liremapped_links.append(link.model_copy(update={"from_uri": from_uri, "to_uri": to_uri}))return remapped_links+def _operation_trace_id(op: ResolvedOperation) -> str | None:source = getattr(op, "source", None)trace_id = getattr(source, "trace_id", None) if source else None@@ -293,6 +291,7 @@ class ExtractContext:def get_year(self, ranges_str: str) -> str:"""根据 ranges 字符串获取第一条消息的年份,fallback 到当前年份"""from datetime import datetime+if not ranges_str:return str(datetime.now().year)msg_range = self.read_message_ranges(ranges_str)@@ -304,6 +303,7 @@ class ExtractContext:def get_month(self, ranges_str: str) -> str:"""根据 ranges 字符串获取第一条消息的月份,fallback 到当前月份"""from datetime import datetime+if not ranges_str:return f"{datetime.now().month:02d}"msg_range = self.read_message_ranges(ranges_str)@@ -315,6 +315,7 @@ class ExtractContext:def get_day(self, ranges_str: str) -> str:"""根据 ranges 字符串获取第一条消息的日期,fallback 到当前日期"""from datetime import datetime+if not ranges_str:return f"{datetime.now().day:02d}"msg_range = self.read_message_ranges(ranges_str)@@ -711,8 +712,12 @@ class MemoryUpdater:"""def __init__(- self, registry: Optional[MemoryTypeRegistry] = None, vikingdb=None, transaction_handle=None+ self,+ registry: Optional[MemoryTypeRegistry] = None,+ vikingdb=None,+ transaction_handle: Any = None,):+ """Create a memory updater with an optional pathlock transaction handle."""self._viking_fs = Noneself._registry = registryself._vikingdb = vikingdb@@ -846,6 +851,7 @@ class MemoryUpdater:resolved_op,ctx,extract_context=extract_context,+ lease_ref=self._transaction_handle,)# Add all uris to result (uris is List[str])if resolved_op.is_edit():@@ -866,7 +872,12 @@ class MemoryUpdater:list(getattr(operations, "resolved_links", []) or []),dict(getattr(operations, "delete_replacements", {}) or {}),)- await self._inherit_deleted_link_relations(operations, result, ctx)+ await self._inherit_deleted_link_relations(+ operations,+ result,+ ctx,+ lease_ref=self._transaction_handle,+ )# Apply delete operations (delete_file_contents is List[MemoryFile])# Skip deletes whose URI was just written in the same batch — this happens when the@@ -896,13 +907,13 @@ class MemoryUpdater:)continuetry:- await self._apply_delete(delete_uri, ctx)+ await self._apply_delete(delete_uri, ctx, lease_ref=self._transaction_handle)result.add_deleted(delete_uri)except Exception as e:tracer.error(f"Failed to delete memory {delete_uri}", e)result.add_error(delete_uri, e)- await self._sync_resource_refs_for_result(result, ctx)+ await self._sync_resource_refs_for_result(result, ctx, lease_ref=self._transaction_handle)# Vectorize written and edited memoriesuri_memory_type_map = {}@@ -923,6 +934,7 @@ class MemoryUpdater:result,ctx,deleted_uris=set(result.deleted_uris),+ lease_ref=self._transaction_handle,)tracer.info(f"Memory operations applied: {result.summary()}")@@ -943,7 +955,13 @@ class MemoryUpdater:)for dir, memory_type in dirs.items():- await self.generate_overview(memory_type, dir, ctx, extract_context)+ await self.generate_overview(+ memory_type,+ dir,+ ctx,+ extract_context,+ lease_ref=self._transaction_handle,+ )return result@@ -951,6 +969,7 @@ class MemoryUpdater:self,result: MemoryUpdateResult,ctx: RequestContext,+ lease_ref: Any = None,) -> None:"""Synchronize resource refs for memory files touched by session extraction."""viking_fs = self._get_viking_fs()@@ -974,13 +993,17 @@ class MemoryUpdater:uri,MemoryFileUtils.write(mf),ctx=ctx,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)except Exception as exc:logger.warning("Failed to sync resource refs for %s: %s", uri, exc)async def _apply_upsert(- self, resolved_op: ResolvedOperation, ctx: RequestContext, extract_context: Any = None+ self,+ resolved_op: ResolvedOperation,+ ctx: RequestContext,+ extract_context: Any = None,+ lease_ref: Any = None,):"""Apply upsert operation from a flat model."""viking_fs = self._get_viking_fs()@@ -1096,7 +1119,7 @@ class MemoryUpdater:uri,new_full_content,ctx=ctx,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)def _distribute_links_to_operations(self, operations: ResolvedOperations) -> None:@@ -1133,6 +1156,7 @@ class MemoryUpdater:result: MemoryUpdateResult,ctx: RequestContext,deleted_uris: Optional[set[str]] = None,+ lease_ref: Any = None,) -> None:"""Apply links to endpoint files that are NOT in the current upsert batch."""viking_fs = self._get_viking_fs()@@ -1153,15 +1177,15 @@ class MemoryUpdater:ctx,viking_fs,skip_uris=skip,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)-async def _inherit_deleted_link_relations(self,operations: ResolvedOperations,result: MemoryUpdateResult,ctx: RequestContext,+ lease_ref: Any = None,) -> None:uri_remap = dict(getattr(operations, "delete_replacements", {}) or {})if not uri_remap:@@ -1179,7 +1203,9 @@ class MemoryUpdater:try:content = await viking_fs.read_file(deleted_uri, ctx=ctx)except Exception as e:- tracer.error(f"Failed to read deleted memory links for replacement {deleted_uri}: {e}")+ tracer.error(+ f"Failed to read deleted memory links for replacement {deleted_uri}: {e}"+ )continueif not content:continue@@ -1236,22 +1262,25 @@ class MemoryUpdater:uri,MemoryFileUtils.write(mf),ctx=ctx,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)result.add_edited(uri)except Exception as e:tracer.error(f"Failed to inherit deleted memory links for {uri}: {e}")- async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:+ async def _apply_delete(+ self,+ uri: str,+ ctx: RequestContext,+ lease_ref: Any = None,+ ) -> None:"""Apply delete operation (uri is already a string)."""viking_fs = self._get_viking_fs()# Delete from VikingFS- # VikingFS automatically handles vector index cleanup- # Pass transaction_handle so rm() reuses the compressor's tree lock- # instead of trying to acquire a new lock (which would conflict).+ # VikingFS automatically handles vector index cleanup.try:- await viking_fs.rm(uri, recursive=False, ctx=ctx, lock_handle=self._transaction_handle)+ await viking_fs.rm(uri, recursive=False, ctx=ctx, lease_ref=lease_ref)except NotFoundError:tracer.error(f"Memory not found for delete: {uri}")# Idempotent - deleting non-existent file succeeds@@ -1397,6 +1426,7 @@ class MemoryUpdater:directory: str,ctx: RequestContext,extract_context: Any = None,+ lease_ref: Any = None,) -> None:"""Generate .overview.md file for a directory based on overview_template.@@ -1453,7 +1483,7 @@ class MemoryUpdater:overview_path,recursive=False,ctx=ctx,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)except Exception:pass@@ -1464,7 +1494,7 @@ class MemoryUpdater:directory,recursive=True,ctx=ctx,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)except Exception:pass@@ -1519,7 +1549,7 @@ class MemoryUpdater:overview_path,rendered,ctx=ctx,- lock_handle=self._transaction_handle,+ lease_ref=lease_ref,)except Exception as e:tracer.error(f"Failed to write overview {overview_path}: {e}")diff --git a/openviking/session/memory/streaming_memory_updater.py b/openviking/session/memory/streaming_memory_updater.pyindex 540cc1432..4453463f0 100644--- a/openviking/session/memory/streaming_memory_updater.py+++ b/openviking/session/memory/streaming_memory_updater.py@@ -442,7 +442,6 @@ class StreamingMemoryUpdater:updater = MemoryUpdater(registry=self.registry,vikingdb=self.vikingdb,- transaction_handle=None,)extract_context = ExtractContext(messages)isolation_handler = _make_isolation_handler(request, extract_context)diff --git a/openviking/session/session.py b/openviking/session/session.pyindex 80ec7f356..9347ef2fd 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -698,8 +698,8 @@ class Session:await self._viking_fs.write_file(f"{self._session_uri}/messages.jsonl", "", ctx=self.ctx)await self._save_meta()- async def _save_meta(self) -> None:- """Persist .meta.json to storage."""+ async def _save_meta(self, lease_ref: Optional[Any] = None) -> None:+ """Persist .meta.json to storage using an optional held PathLock lease."""if not self._viking_fs:returnself._meta.updated_at = get_current_timestamp()@@ -707,6 +707,7 @@ class Session:uri=f"{self._session_uri}/.meta.json",content=json.dumps(self._meta.to_dict(), ensure_ascii=False),ctx=self.ctx,+ lease_ref=lease_ref,)@property@@ -1125,15 +1126,11 @@ class Session:await self._append_messages_without_path_lock(messages)return- from openviking.storage.transaction import LockContext, get_lock_manager-session_path = uri_to_path(self._session_uri, ctx=self.ctx)- async with LockContext(- get_lock_manager(),- [session_path],- lock_mode="exact",- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,- ):+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS+ )+ try:self._messages = await self._read_live_messages_strict()in_memory_meta = self._metatry:@@ -1153,8 +1150,11 @@ class Session:f"{self._session_uri}/messages.jsonl",batch_content,ctx=self.ctx,+ lease_ref=lease,)- await self._save_meta()+ await self._save_meta(lease_ref=lease)+ finally:+ await self._viking_fs._async_agfs.pathlock_release(lease)async def _append_messages_without_path_lock(self, messages: List[Message]) -> None:"""Compatibility append for storage adapters without path locking."""@@ -1420,7 +1420,12 @@ class Session:self._meta.retained_message_token_budget = retained_message_token_budgetself._meta.min_raw_tail_steps = min_raw_tail_steps- async def _merge_archive_meta(self, archive_uri: str, updates: Dict[str, Any]) -> None:+ async def _merge_archive_meta(+ self,+ archive_uri: str,+ updates: Dict[str, Any],+ lease_ref: Optional[Any] = None,+ ) -> None:"""Merge archive metadata so Phase 2 cannot erase Phase 1 planning data."""if not self._viking_fs:return@@ -1441,6 +1446,7 @@ class Session:uri=f"{archive_uri}/.meta.json",content=json.dumps(meta, ensure_ascii=False),ctx=self.ctx,+ lease_ref=lease_ref,)@staticmethod@@ -1479,6 +1485,7 @@ class Session:min_raw_tail_steps: int,agent_evolution_enabled: bool = True,agent_memory_skip_reason: Optional[str] = None,+ lease_ref: Optional[Any] = None,) -> None:"""Persist the Phase 1 intent before any destructive root rewrite."""payload = {@@ -1504,9 +1511,15 @@ class Session:"skip_reason": agent_memory_skip_reason,},},+ lease_ref=lease_ref,)- async def _write_phase1_ready_marker(self, archive_uri: str) -> None:+ async def _write_phase1_ready_marker(+ self,+ archive_uri: str,+ lease_ref: Optional[Any] = None,+ ) -> None:+ """Persist that Phase 1 is ready using an optional held PathLock lease."""phase1 = await self._read_phase1_meta(archive_uri)phase1.update({@@ -1514,7 +1527,7 @@ class Session:"ready_at": get_current_timestamp(),})- await self._merge_archive_meta(archive_uri, {"phase1": phase1})+ await self._merge_archive_meta(archive_uri, {"phase1": phase1}, lease_ref=lease_ref)async def _archive_file_exists(self, archive_uri: str, file_name: str) -> bool:try:@@ -1544,15 +1557,11 @@ class Session:if await self._archive_file_exists(archive_uri, ".failed.json"):return False- from openviking.storage.transaction import LockContext, get_lock_manager-session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)- async with LockContext(- get_lock_manager(),- [session_path],- lock_mode="exact",- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,- ):+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS+ )+ try:marker = await self._read_phase1_meta(archive_uri)if marker.get("status") == "ready":return True@@ -1574,20 +1583,21 @@ class Session:archive_uri,stage="phase1_recovery",error=f"Cannot verify Phase 1 state: {exc}",+ lease_ref=lease,)return Falselive_ids = [message.id for message in live_messages]archived_only_ids = set(archived_ids) - set(retained_ids)- phase1_applied = (- live_ids[: len(retained_ids)] == retained_ids- and not archived_only_ids.intersection(live_ids)- )+ phase1_applied = live_ids[+ : len(retained_ids)+ ] == retained_ids and not archived_only_ids.intersection(live_ids)if not phase1_applied:await self._write_failed_marker(archive_uri,stage="phase1_recovery",error="Root rewrite was not durably completed before process interruption",+ lease_ref=lease,)return False@@ -1605,9 +1615,7 @@ class Session:self._remember_retention_policy(keep_recent_count=max(0, int(marker.get("keep_recent_count", 0) or 0)),retention_mode=str(marker.get("retention_mode", "") or "") or None,- keep_recent_turn_count=max(- 0, int(marker.get("keep_recent_turn_count", 0) or 0)- ),+ keep_recent_turn_count=max(0, int(marker.get("keep_recent_turn_count", 0) or 0)),retained_message_token_budget=max(0, int(marker.get("retained_message_token_budget", 0) or 0)),@@ -1620,10 +1628,12 @@ class Session:)self._meta.last_commit_at = get_current_timestamp()self._rebuild_pending_tokens()- await self._save_meta()- await self._write_phase1_ready_marker(archive_uri)+ await self._save_meta(lease_ref=lease)+ await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)logger.warning("Recovered interrupted Session Phase 1: %s", archive_uri)return True+ finally:+ await self._viking_fs._async_agfs.pathlock_release(lease)def commit(self,@@ -1679,7 +1689,6 @@ class Session:from openviking.service.task_tracker import get_task_trackerfrom openviking.storage.queuefs import QueueManager, get_queue_managerfrom openviking.storage.queuefs.session_commit_msg import SessionCommitMsg- from openviking.storage.transaction import LockContext, get_lock_managertrace_id = tracer.get_trace_id()keep_recent_count = max(0, int(keep_recent_count or 0))@@ -1739,12 +1748,10 @@ class Session:# can hold stale Session objects, so in-memory emptiness is never a# correctness boundary.session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)- async with LockContext(- get_lock_manager(),- [session_path],- lock_mode="exact",- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,- ):+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS+ )+ try:self._messages = await self._read_live_messages_strict()try:meta_content = await self._viking_fs.read_file(@@ -1796,7 +1803,7 @@ class Session:retained_message_token_budget=effective_token_budget if turn_mode else 0,min_raw_tail_steps=effective_min_tail,)- await self._save_meta()+ await self._save_meta(lease_ref=lease)get_current_telemetry().set("memory.extracted", 0)return {"session_id": self.session_id,@@ -1836,7 +1843,7 @@ class Session:# remember the policy for subsequent add_message accounting.if not messages_to_archive:self._messages = retained_messages- await self._write_to_agfs_async(messages=self._messages)+ await self._write_to_agfs_async(messages=self._messages, lease_ref=lease)self._meta.pending_tokens = 0self._meta.message_count = totalself._remember_retention_policy(@@ -1846,7 +1853,7 @@ class Session:retained_message_token_budget=effective_token_budget if turn_mode else 0,min_raw_tail_steps=effective_min_tail,)- await self._save_meta()+ await self._save_meta(lease_ref=lease)get_current_telemetry().set("memory.extracted", 0)return {"session_id": self.session_id,@@ -1897,6 +1904,7 @@ class Session:min_raw_tail_steps=effective_min_tail,agent_evolution_enabled=agent_evolution_enabled,agent_memory_skip_reason=agent_memory_skip_reason,+ lease_ref=lease,)# Archive raw remains durable and recoverable before any live@@ -1907,6 +1915,7 @@ class Session:uri=f"{archive_uri}/messages.jsonl",content="\n".join(lines) + "\n",ctx=self.ctx,+ lease_ref=lease,)if retention_plan is not None:await self._merge_archive_meta(@@ -1919,6 +1928,7 @@ class Session:min_raw_tail_steps=effective_min_tail,)},+ lease_ref=lease,)phase1_stage = "queue_enqueue"@@ -1943,7 +1953,7 @@ class Session:phase1_stage = "phase1_persist"self._messages = retained_messages- await self._write_to_agfs_async(messages=self._messages)+ await self._write_to_agfs_async(messages=self._messages, lease_ref=lease)self._meta.message_count = len(self._messages)self._meta.pending_tokens = 0self._remember_retention_policy(@@ -1958,8 +1968,8 @@ class Session:self._compression.compression_index,)self._meta.last_commit_at = get_current_timestamp()- await self._save_meta()- await self._write_phase1_ready_marker(archive_uri)+ await self._save_meta(lease_ref=lease)+ await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)except Exception as e:logger.error(f"[commit] Failed during {phase1_stage}: {e}")# Whether the queue write failed or a queued Phase 1 stopped@@ -1970,6 +1980,7 @@ class Session:archive_uri,stage=phase1_stage,error=str(e),+ lease_ref=lease,)except Exception:logger.exception(@@ -1979,6 +1990,8 @@ class Session:self._messages = original_messagesself._compression.compression_index -= 1raise+ finally:+ await self._viking_fs._async_agfs.pathlock_release(lease)# Lock released; Phase 1 intent, queue item, retained root, metadata and# ready metadata are all durable.@@ -2098,23 +2111,17 @@ class Session:# that temporarily stored this snapshot in the queue payload.phase1 = archive_meta.get("phase1")queue_snapshot = phase1.get("queue_message") if isinstance(phase1, dict) else None- agent_evolution_snapshot = (- queue_snapshot if isinstance(queue_snapshot, dict) else {}- )+ agent_evolution_snapshot = queue_snapshot if isinstance(queue_snapshot, dict) else {}snapshot_enabled = agent_evolution_snapshot.get("enabled")if snapshot_enabled is None:snapshot_enabled = agent_evolution_snapshot.get("agent_evolution_enabled")# Archives created before this setting existed preserve their original# behavior, where Agent memory extraction was enabled by default.- agent_evolution_enabled = (- snapshot_enabled if isinstance(snapshot_enabled, bool) else True- )+ agent_evolution_enabled = snapshot_enabled if isinstance(snapshot_enabled, bool) else Trueagent_memory_skip_reason = agent_evolution_snapshot.get("skip_reason")if agent_memory_skip_reason is None:- agent_memory_skip_reason = agent_evolution_snapshot.get(- "agent_memory_skip_reason"- )+ agent_memory_skip_reason = agent_evolution_snapshot.get("agent_memory_skip_reason")if agent_memory_skip_reason is None:agent_memory_skip_reason = _agent_memory_skip_reason(agent_evolution_enabled=agent_evolution_enabled,@@ -2700,6 +2707,7 @@ class Session:blocked_by: str = "",skipped: bool = True,completed_memory_steps: Optional[Dict[str, List[str]]] = None,+ lease_ref: Optional[Any] = None,) -> None:"""Persist a terminal failure marker for the archive."""if not self._viking_fs:@@ -2717,6 +2725,7 @@ class Session:uri=f"{archive_uri}/.failed.json",content=json.dumps(payload, ensure_ascii=False),ctx=self.ctx,+ lease_ref=lease_ref,)async def get_session_context(self, token_budget: int = 128_000) -> Dict[str, Any]:@@ -3387,9 +3396,7 @@ class Session:continueif not isinstance(abstract, str) or not abstract.strip():continue- valid_source_ids = [- item for item in source_ids if isinstance(item, str) and item- ]+ valid_source_ids = [item for item in source_ids if isinstance(item, str) and item]if not valid_source_ids:continue@@ -3407,9 +3414,7 @@ class Session:)seen_source_ids = set(candidate["source_message_ids"])new_source_ids = [- source_id- for source_id in valid_source_ids- if source_id not in seen_source_ids+ source_id for source_id in valid_source_ids if source_id not in seen_source_ids]if not new_source_ids:continue@@ -3493,9 +3498,7 @@ class Session:while True:earlier_states = [- state- for state in await self._scan_archive_states()- if state.index < archive_index+ state for state in await self._scan_archive_states() if state.index < archive_index]pending_states = [state for state in earlier_states if state.state == "pending"]if not pending_states:@@ -3586,15 +3589,11 @@ class Session:telemetry_snapshot: Any,) -> None:"""Merge Phase 2 results without overwriting concurrent root updates."""- from openviking.storage.transaction import LockContext, get_lock_manager-session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)- async with LockContext(- get_lock_manager(),- [session_path],- lock_mode="exact",- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,- ):+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS+ )+ try:latest_meta = self._metatry:meta_content = await self._viking_fs.read_file(@@ -3628,7 +3627,9 @@ class Session:latest_meta.last_commit_at = get_current_timestamp()latest_meta.message_count = await self._read_live_message_count()self._meta = latest_meta- await self._save_meta()+ await self._save_meta(lease_ref=lease)+ finally:+ await self._viking_fs._async_agfs.pathlock_release(lease)async def _read_live_message_count(self) -> int:"""Count current live session messages from persisted storage."""@@ -4815,8 +4816,12 @@ class Session:return "\n".join(parts).rstrip() + "\n"- async def _write_to_agfs_async(self, messages: List[Message]) -> None:- """Write messages.jsonl to AGFS (async)."""+ async def _write_to_agfs_async(+ self,+ messages: List[Message],+ lease_ref: Optional[Any] = None,+ ) -> None:+ """Write messages.jsonl to AGFS using an optional held PathLock lease."""if not self._viking_fs:return@@ -4833,16 +4838,19 @@ class Session:uri=f"{self._session_uri}/messages.jsonl",content=content,ctx=self.ctx,+ lease_ref=lease_ref,)await viking_fs.write_file(uri=f"{self._session_uri}/.abstract.md",content=abstract,ctx=self.ctx,+ lease_ref=lease_ref,)await viking_fs.write_file(uri=f"{self._session_uri}/.overview.md",content=overview,ctx=self.ctx,+ lease_ref=lease_ref,)def _generate_abstract(self) -> str:diff --git a/openviking/session/train/components/policy_updater.py b/openviking/session/train/components/policy_updater.pyindex a43f3ac0e..897ac3ccf 100644--- a/openviking/session/train/components/policy_updater.py+++ b/openviking/session/train/components/policy_updater.py@@ -130,9 +130,7 @@ class MemoryFilePolicyUpdater:)-def _apply_items_to_snapshot(- items: list[PolicyPlanItem], policy_set: PolicySet-) -> PolicySet:+def _apply_items_to_snapshot(items: list[PolicyPlanItem], policy_set: PolicySet) -> PolicySet:policies_by_uri = {policy.uri: policy for policy in policy_set.policies}result = list(policy_set.policies)@@ -225,7 +223,6 @@ def _target_uri(item: PolicyPlanItem, root_uri: str) -> str:return f"{root_uri.rstrip('/')}/{_safe_experience_filename(item.target_name)}.md"-def _plan_to_resolved_operations(*,plan: PolicyUpdatePlan,@@ -247,8 +244,7 @@ def _plan_to_resolved_operations(!= _normalize_guard_content(item.before_content)):errors.append(- "base content mismatch for "- f"{item.target_name}: expected gradient before_content"+ f"base content mismatch for {item.target_name}: expected gradient before_content")continue@@ -264,9 +260,7 @@ def _plan_to_resolved_operations(updated = _find_policy(updated_policy_set, uri=uri, name=item.target_name)if updated is None:- errors.append(- f"planned policy not found after simulation: {item.target_name}"- )+ errors.append(f"planned policy not found after simulation: {item.target_name}")continueupserts.append(diff --git a/openviking/session/train/components/skill_policy_updater.py b/openviking/session/train/components/skill_policy_updater.pyindex 2bea52390..500341840 100644--- a/openviking/session/train/components/skill_policy_updater.py+++ b/openviking/session/train/components/skill_policy_updater.py@@ -101,7 +101,7 @@ class SkillPolicyUpdater:continuetry:skill_root = _root_uri_from_skill_md(old_file.uri)- await viking_fs.rm(skill_root, ctx=ctx, lock_handle=transaction_handle)+ await viking_fs.rm(skill_root, ctx=ctx, lease_ref=transaction_handle)deleted_uris.append(old_file.uri)except Exception as exc:delete_errors.append(f"{old_file.uri}: {exc}")@@ -138,9 +138,7 @@ def _coerce_request_context(context: Any) -> RequestContext | None:return None-def _apply_items_to_snapshot(- items: list[PolicyPlanItem], policy_set: PolicySet-) -> PolicySet:+def _apply_items_to_snapshot(items: list[PolicyPlanItem], policy_set: PolicySet) -> PolicySet:policies_by_uri = {policy.uri: policy for policy in policy_set.policies}result = list(policy_set.policies)@@ -239,9 +237,7 @@ def _plan_to_resolved_operations(updated = _find_policy(updated_policy_set, uri=uri, name=item.target_name)if updated is None:- errors.append(- f"planned skill policy not found after simulation: {item.target_name}"- )+ errors.append(f"planned skill policy not found after simulation: {item.target_name}")continueold_mf = _policy_to_memory_file(current) if current is not None else Nonediff --git a/openviking/session/train/domain.py b/openviking/session/train/domain.pyindex b7348952c..6e66158bf 100644--- a/openviking/session/train/domain.py+++ b/openviking/session/train/domain.py@@ -80,19 +80,12 @@ class PolicySet:if uri_to_path is None:raise RuntimeError("PolicySet.viking_fs must provide _uri_to_path for locking")- from openviking.storage.transaction import get_lock_manager-- lock_manager = get_lock_manager()- handle = lock_manager.create_handle()path = uri_to_path(self.root_uri, ctx=self.request_context)- acquired = await lock_manager.acquire_tree(handle, path, timeout=None)- if not acquired:- await lock_manager.release(handle)- raise RuntimeError(f"Failed to acquire policy tree lock for {self.root_uri}")+ lease = await self.viking_fs._async_agfs.pathlock_acquire_tree(path, timeout_secs=300.0)try:- yield handle+ yield leasefinally:- await lock_manager.release(handle)+ await self.viking_fs._async_agfs.pathlock_release(lease)async def reload(self) -> "PolicySet":"""Reload this policy set from its backing VikingFS under the same ctx."""diff --git a/openviking/storage/content_write.py b/openviking/storage/content_write.pyindex 304eea4c6..6a4a776ce 100644--- a/openviking/storage/content_write.py+++ b/openviking/storage/content_write.py@@ -9,7 +9,7 @@ import binasciiimport hashlibimport osfrom collections import defaultdict-from typing import TYPE_CHECKING, Any, Dict, Optional+from typing import Any, Dict, Optionalfrom openviking.core.namespace import (NamespaceShapeError,@@ -27,10 +27,9 @@ from openviking.session.memory.utils.resource_refs import (RESOURCE_REF_SOURCE_CONTENT_WRITE,sync_memory_resource_refs,)-from openviking.storage.errors import ResourceBusyError+from openviking.storage.errors import LockAcquisitionError, ResourceBusyErrorfrom openviking.storage.queuefs import SemanticMsg, get_queue_managerfrom openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key-from openviking.storage.transaction import get_lock_managerfrom openviking.storage.viking_fs import VikingFSfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -51,12 +50,19 @@ from openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)-if TYPE_CHECKING:- from openviking.storage.transaction.lock_handle import LockHandle-_DERIVED_FILENAMES = frozenset({".abstract.md", ".overview.md", ".relations.json"})_CREATE_ALLOWED_EXTENSIONS = frozenset(- {".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".py", ".js", ".ts"}+ {+ ".md",+ ".txt",+ ".json",+ ".yaml",+ ".yml",+ ".toml",+ ".py",+ ".js",+ ".ts",+ })_BATCH_MAX_OPERATIONS = 128_BATCH_MAX_FILE_BYTES = 8 * 1024 * 1024@@ -154,16 +160,14 @@ class ContentWriteCoordinator:normalized_root, operations, ctx=ctx)- lock_manager = get_lock_manager()- handle = lock_manager.create_handle()root_path = self._viking_fs._uri_to_path(normalized_root, ctx=ctx)- acquired = await lock_manager.acquire_tree(handle, root_path)- if not acquired:- await lock_manager.release(handle)+ try:+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(root_path)+ except LockAcquisitionError as exc:raise ResourceBusyError(f"resource is busy and cannot be written now: {normalized_root}",uri=normalized_root,- )+ ) from exccreated: list[str] = []updated: list[str] = []@@ -226,7 +230,7 @@ class ContentWriteCoordinator:uri,operation["content"],ctx=ctx,- lock_handle=handle,+ lease_ref=lease,)except Exception as exc:write_error = exc@@ -238,7 +242,7 @@ class ContentWriteCoordinator:created.append(uri)refresh_kinds[uri] = "added"finally:- await lock_manager.release(handle)+ await self._viking_fs._async_agfs.pathlock_release(lease)lock_released = Trueassert lock_released@@ -689,16 +693,14 @@ class ContentWriteCoordinator:written_bytes: int,telemetry_id: str,) -> Dict[str, Any]:- lock_manager = get_lock_manager()- handle = lock_manager.create_handle()lock_path = self._viking_fs._uri_to_path(uri, ctx=ctx)- acquired = await lock_manager.acquire_exact_path(handle, lock_path)- if not acquired:- await lock_manager.release(handle)+ try:+ lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)+ except LockAcquisitionError as exc:raise ResourceBusyError(f"resource is busy and cannot be written now: {uri}",uri=uri,- )+ ) from excprevious_content: Optional[str] = Nonecontent_written = False@@ -709,13 +711,7 @@ class ContentWriteCoordinator:previous_content = await self._viking_fs.read_file(uri, ctx=ctx)if wait and telemetry_id:get_request_wait_tracker().register_request(telemetry_id)- await self._write_in_place(- uri,- content,- mode=mode,- ctx=ctx,- lock_handle=handle,- )+ await self._write_in_place(uri, content, mode=mode, ctx=ctx, lease_ref=lease)content_written = Trueawait self._enqueue_semantic_refresh(root_uri=root_uri,@@ -725,7 +721,7 @@ class ContentWriteCoordinator:change_type="added" if mode == "create" else "modified",)semantic_enqueued = True- await lock_manager.release(handle)+ await self._viking_fs._async_agfs.pathlock_release(lease)lock_released = Truequeue_status = (await self._wait_for_request(telemetry_id=telemetry_id, timeout=timeout)@@ -748,10 +744,10 @@ class ContentWriteCoordinator:previous_content=previous_content,mode=mode,ctx=ctx,- lock_handle=handle,+ lease_ref=lease,)if not lock_released:- await lock_manager.release(handle)+ await self._viking_fs._async_agfs.pathlock_release(lease)raisefinally:if wait and telemetry_id:@@ -764,18 +760,18 @@ class ContentWriteCoordinator:previous_content: Optional[str],mode: str,ctx: RequestContext,- lock_handle: Any,+ lease_ref: Optional[Dict[str, Any]] = None,) -> None:try:if mode == "create":- await self._viking_fs.rm(uri, ctx=ctx, lock_handle=lock_handle)+ await self._viking_fs.rm(uri, ctx=ctx, lease_ref=lease_ref)returnif previous_content is not None:await self._viking_fs.write_file(uri,previous_content,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)except Exception:logger.error("Failed to rollback direct content write for %s", uri, exc_info=True)@@ -885,7 +881,7 @@ class ContentWriteCoordinator:*,mode: str,ctx: RequestContext,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Optional[Dict[str, Any]] = None,) -> None:if context_type_for_uri(uri) == "memory":if mode == "replace":@@ -903,7 +899,7 @@ class ContentWriteCoordinator:uri,MemoryFileUtils.write(mf),ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)return@@ -912,14 +908,9 @@ class ContentWriteCoordinator:mf = MemoryFileUtils.read(existing_raw, uri=uri)mf.content = mf.content + contentupdated_raw = MemoryFileUtils.write(mf)- await self._viking_fs.write_file(- uri,- updated_raw,- ctx=ctx,- lock_handle=lock_handle,- )+ await self._viking_fs.write_file(uri, updated_raw, ctx=ctx, lease_ref=lease_ref)return- await self._viking_fs.write_file(uri, content, ctx=ctx, lock_handle=lock_handle)+ await self._viking_fs.write_file(uri, content, ctx=ctx, lease_ref=lease_ref)async def _enqueue_semantic_refresh(self,@@ -977,28 +968,20 @@ class ContentWriteCoordinator:written_bytes: int,telemetry_id: str,) -> Dict[str, Any]:- lock_manager = get_lock_manager()- handle = lock_manager.create_handle()lock_path = self._viking_fs._uri_to_path(uri, ctx=ctx)- acquired = await lock_manager.acquire_exact_path(handle, lock_path)- if not acquired:- await lock_manager.release(handle)+ try:+ lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)+ except LockAcquisitionError as exc:raise ResourceBusyError(f"resource is busy and cannot be written now: {uri}",uri=uri,- )+ ) from excreleased = Falserequest_registered = Falsetry:- await self._write_in_place(- uri,- content,- mode=mode,- ctx=ctx,- lock_handle=handle,- )- await lock_manager.release(handle)+ await self._write_in_place(uri, content, mode=mode, ctx=ctx, lease_ref=lease)+ await self._viking_fs._async_agfs.pathlock_release(lease)released = Trueif wait and telemetry_id and self._vikingdb_has_queue():get_request_wait_tracker().register_request(telemetry_id)@@ -1041,7 +1024,7 @@ class ContentWriteCoordinator:)except Exception:if not released:- await lock_manager.release(handle)+ await self._viking_fs._async_agfs.pathlock_release(lease)raisefinally:if request_registered:diff --git a/openviking/storage/observers/__init__.py b/openviking/storage/observers/__init__.pyindex b95548026..841cd7144 100644--- a/openviking/storage/observers/__init__.py+++ b/openviking/storage/observers/__init__.py@@ -2,7 +2,6 @@# SPDX-License-Identifier: AGPL-3.0from .base_observer import BaseObserverfrom .filesystem_observer import FilesystemObserver-from .lock_observer import LockObserverfrom .models_observer import ModelsObserverfrom .queue_observer import QueueObserverfrom .retrieval_observer import RetrievalObserver@@ -11,7 +10,6 @@ from .vikingdb_observer import VikingDBObserver__all__ = ["BaseObserver","FilesystemObserver",- "LockObserver","ModelsObserver","QueueObserver","RetrievalObserver",diff --git a/openviking/storage/observers/lock_observer.py b/openviking/storage/observers/lock_observer.pydeleted file mode 100644index 1e7bc5e81..000000000--- a/openviking/storage/observers/lock_observer.py+++ /dev/null@@ -1,74 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""LockObserver: Lock system observability."""--import time-from typing import Any, Dict, List--from openviking.storage.observers.base_observer import BaseObserver-from openviking.storage.transaction.lock_manager import LockManager-from openviking_cli.utils.logger import get_logger--logger = get_logger(__name__)---class LockObserver(BaseObserver):- """Observability tool for the lock system."""-- def __init__(self, lock_manager: LockManager):- self._manager = lock_manager-- def get_active_locks(self) -> List[Dict[str, Any]]:- """Return info about every active lock handle."""- now = time.time()- return [- {- "id": h.id,- "lock_count": len(h.locks),- "created_at": h.created_at,- "last_active_at": h.last_active_at,- "duration_seconds": round(now - h.created_at, 1),- "idle_seconds": round(now - h.last_active_at, 1),- }- for h in self._manager.get_active_handles().values()- ]-- def get_hanging_locks(self, threshold: float = 600) -> List[Dict[str, Any]]:- """Return locks that have been idle longer than *threshold* seconds."""- return [lock for lock in self.get_active_locks() if lock["idle_seconds"] > threshold]-- # ------ BaseObserver interface -------- def get_status_table(self) -> str:- locks = self.get_active_locks()- if not locks:- return "No active locks."-- from tabulate import tabulate-- data = [- {- "Handle ID": l["id"][:8] + "...",- "Locks": l["lock_count"],- "Duration": f"{l['duration_seconds']}s",- "Idle": f"{l['idle_seconds']}s",- "Created": time.strftime("%H:%M:%S", time.localtime(l["created_at"])),- }- for l in locks- ]- data.append(- {- "Handle ID": f"TOTAL ({len(locks)})",- "Locks": sum(l["lock_count"] for l in locks),- "Duration": "",- "Idle": "",- "Created": "",- }- )- return tabulate(data, headers="keys", tablefmt="pretty")-- def is_healthy(self) -> bool:- return not self.get_hanging_locks(600)-- def has_errors(self) -> bool:- return bool(self.get_hanging_locks(600))diff --git a/openviking/storage/queuefs/add_resource_processor.py b/openviking/storage/queuefs/add_resource_processor.pyindex 05fb0edbf..771c2102b 100644--- a/openviking/storage/queuefs/add_resource_processor.py+++ b/openviking/storage/queuefs/add_resource_processor.py@@ -29,21 +29,19 @@ class AddResourceProcessor(DequeueHandlerBase):resource_service: Any,service_loop: asyncio.AbstractEventLoop,queue_name: str,+ viking_fs: Any,):self._resource_service = resource_serviceself._service_loop = service_loopself._queue_name = queue_name+ self._viking_fs = viking_fsasync def _load_lock(self, msg: AddResourceMsg, ctx: RequestContext) -> Any:+ """Adopt a pathlock handoff ref, returning an owned lease dict."""if msg.lock_handoff is None:return None- from openviking.storage.transaction.lock_lease import LockHandoffRef, OwnedLockLease-- ref = LockHandoffRef.from_value(msg.lock_handoff)- if ref is None:- raise ValueError("Invalid lock_handoff")try:- return await OwnedLockLease.from_handoff(ref)+ return await self._viking_fs._async_agfs.pathlock_adopt(msg.lock_handoff)except Exception as handoff_error:try:return await self._resource_service.reacquire_add_resource_job_lock(@@ -179,7 +177,7 @@ class AddResourceProcessor(DequeueHandlerBase):finally:with suppress(Exception):if resource_lock is not None:- await resource_lock.close()+ await self._viking_fs._async_agfs.pathlock_release(resource_lock)async def on_dequeue(self, data: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:if not data:diff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.pyindex 5e2179918..07ad10faa 100644--- a/openviking/storage/queuefs/semantic_dag.py+++ b/openviking/storage/queuefs/semantic_dag.py@@ -5,13 +5,12 @@import asyncioimport threadingfrom dataclasses import dataclass, field-from typing import ClassVar, Dict, List, Optional, Set+from typing import Any, ClassVar, Dict, List, Optional, Setfrom weakref import WeakKeyDictionaryfrom openviking.utils.ingest_options import IngestOptionsfrom openviking.server.identity import RequestContextfrom openviking.storage.queuefs.semantic_sidecar import write_semantic_sidecars-from openviking.storage.transaction import NO_LOCK, LockLeasefrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking_cli.utils import VikingURI@@ -169,7 +168,7 @@ class SemanticDagExecutor:semantic_msg_id: Optional[str] = None,telemetry_id: str = "",recursive: bool = True,- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,is_code_repo: bool = False,changes: Optional[Dict[str, List[str]]] = None,skip_vectorization: bool = False,@@ -230,15 +229,12 @@ class SemanticDagExecutor:if self._failure:raise self._failure- # Release owned semantic locks after downstream vectorization finishes.+ # Mark semantic done after downstream vectorization finishes.async def wrapped_on_complete() -> None:- try:- if self._telemetry_id and self._semantic_msg_id:- get_request_wait_tracker().mark_semantic_done(- self._telemetry_id, self._semantic_msg_id- )- finally:- await self._lock.close()+ if self._telemetry_id and self._semantic_msg_id:+ get_request_wait_tracker().mark_semantic_done(+ self._telemetry_id, self._semantic_msg_id+ )async with self._vectorize_lock:task_count = self._vectorize_task_count@@ -264,10 +260,6 @@ class SemanticDagExecutor:logger.error(f"Error in on_complete callback: {e}", exc_info=True)except BaseException:self._closed = True- try:- await self._lock.close()- except Exception:- passraisefinally:self._closed = Truediff --git a/openviking/storage/queuefs/semantic_lock.py b/openviking/storage/queuefs/semantic_lock.pyindex f6e059920..cd82e96d2 100644--- a/openviking/storage/queuefs/semantic_lock.py+++ b/openviking/storage/queuefs/semantic_lock.py@@ -5,25 +5,20 @@from __future__ import annotationsfrom dataclasses import dataclass-from typing import Callable, Iterable, Optional+from typing import Any, Callable, Dict, Iterable, Optionalfrom openviking.storage.errors import LockAcquisitionError-from openviking.storage.transaction import (- NO_LOCK,- LockHandoffRef,- LockLease,- OwnedLockLease,- get_lock_manager,-)-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME+from openviking.storage.internal_names import MULTIWRITE_PATH_LOCK_FILE+from openviking.storage.viking_fs import get_viking_fsfrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)-_TREE_LOCK_SUFFIX = f"/{LOCK_FILE_NAME}"+_TREE_LOCK_SUFFIX = f"/{MULTIWRITE_PATH_LOCK_FILE}"def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:+ """Extract tree lock directory paths from lock file paths."""tree_paths: list[str] = []for lock_path in lock_paths:if not lock_path.endswith(_TREE_LOCK_SUFFIX):@@ -38,52 +33,48 @@ def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:class SemanticLockScope:"""Resolved lock scope for one semantic message."""- lock: LockLease+ lock: Optional[Dict[str, Any]] # lease dict or None+ _owned: bool = False # True when this scope owns the lease (must release)@classmethodasync def resolve(cls,- lock_handoff: Optional[LockHandoffRef],+ lock_handoff: Optional[Dict[str, Any]],*,- caller_lock: LockLease = NO_LOCK,+ caller_lock: Optional[Dict[str, Any]] = None,fallback_path_factory: Optional[Callable[[], str]] = None,) -> "SemanticLockScope":"""Resolve a live lock, lazily deriving a path for stale legacy handoffs."""- if lock_handoff and caller_lock.active:+ if lock_handoff and caller_lock is not None:raise ValueError("semantic lock must come from either message or caller, not both")- if caller_lock is not NO_LOCK and not caller_lock.active:- raise ValueError("caller semantic lock is inactive")- if caller_lock.active:- return cls(caller_lock.as_borrowed())+ if caller_lock is not None:+ viking_fs = get_viking_fs()+ return cls(await viking_fs._async_agfs.pathlock_as_borrowed(caller_lock), _owned=False)if lock_handoff:- manager = get_lock_manager()+ viking_fs = get_viking_fs()try:- return cls(await OwnedLockLease.from_handoff(lock_handoff, manager=manager))- except LockAcquisitionError as exc:- tree_paths = _tree_paths_from_handoff(lock_handoff.lock_paths)+ return cls(await viking_fs._async_agfs.pathlock_adopt(lock_handoff), _owned=True)+ except LockAcquisitionError:+ tree_paths = _tree_paths_from_handoff(lock_handoff["lock_paths"])if not tree_paths and fallback_path_factory:tree_paths = [fallback_path_factory()]if not tree_paths:raise- handle = manager.create_handle()if len(tree_paths) == 1:- acquired = await manager.acquire_tree(handle, tree_paths[0])+ lease = await viking_fs._async_agfs.pathlock_acquire_tree(tree_paths[0])else:- acquired = await manager.acquire_tree_batch(handle, tree_paths)- if not acquired:- await manager.release(handle)- raise LockAcquisitionError(- f"Failed to reacquire semantic lock for {tree_paths}"- ) from exc+ lease = await viking_fs._async_agfs.pathlock_acquire_tree_batch(tree_paths)logger.info("Recovered semantic lock handoff %s by reacquiring %s",- lock_handoff.handle_id,+ lock_handoff.get("owner_id"),tree_paths,)- return cls(OwnedLockLease.from_handle(manager, handle))- return cls(NO_LOCK)+ return cls(lease, _owned=True)+ return cls(None)async def close(self) -> None:- await self.lock.close()+ """Release the owned lock lease if held."""+ if self.lock is not None and self._owned:+ await get_viking_fs()._async_agfs.pathlock_release(self.lock)diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.pyindex 77ba29add..331288a31 100644--- a/openviking/storage/queuefs/semantic_msg.py+++ b/openviking/storage/queuefs/semantic_msg.py@@ -9,8 +9,6 @@ from typing import Any, Dict, List, Optionalfrom uuid import uuid4from openviking.utils.ingest_options import IngestOptions-from openviking.storage.transaction import LockHandoffRef-def build_semantic_coalesce_key(*,@@ -53,7 +51,7 @@ class SemanticMsg:skip_vectorization: bool = Falsetelemetry_id: str = ""target_uri: str = ""- lock_handoff: Optional[LockHandoffRef] = None+ lock_handoff: Optional[Dict[str, Any]] = Noneis_code_repo: bool = Falsetarget_preexisting: Optional[bool] = Noneingest_options: IngestOptions = field(default_factory=IngestOptions)@@ -75,7 +73,7 @@ class SemanticMsg:skip_vectorization: bool = False,telemetry_id: str = "",target_uri: str = "",- lock_handoff: Optional[LockHandoffRef] = None,+ lock_handoff: Optional[Dict[str, Any]] = None,is_code_repo: bool = False,target_preexisting: Optional[bool] = None,ingest_options: IngestOptions | Dict[str, Any] | None = None,@@ -140,7 +138,7 @@ class SemanticMsg:skip_vectorization=data.get("skip_vectorization", False),telemetry_id=data.get("telemetry_id", ""),target_uri=data.get("target_uri", ""),- lock_handoff=LockHandoffRef.from_value(data.get("lock_handoff")),+ lock_handoff=data.get("lock_handoff"),is_code_repo=data.get("is_code_repo", False),target_preexisting=data.get("target_preexisting"),ingest_options=(diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.pyindex 3a1b82556..e453e8858 100644--- a/openviking/storage/queuefs/semantic_processor.py+++ b/openviking/storage/queuefs/semantic_processor.py@@ -40,7 +40,6 @@ from openviking.storage.queuefs.semantic_lock import SemanticLockScopefrom openviking.storage.queuefs.semantic_msg import SemanticMsg, build_semantic_coalesce_keyfrom openviking.storage.queuefs.semantic_queue import is_semantic_msg_stalefrom openviking.storage.queuefs.semantic_sidecar import write_semantic_sidecars-from openviking.storage.transaction import NO_LOCK, LockLeasefrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry import bind_telemetry, bind_telemetry_stage, resolve_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -307,7 +306,7 @@ class SemanticProcessor(DequeueHandlerBase):async def on_dequeue(self,data: Optional[Dict[str, Any]],- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,) -> Optional[Dict[str, Any]]:"""Process dequeued SemanticMsg, recursively process all subdirectories."""msg: Optional[SemanticMsg] = None@@ -373,10 +372,8 @@ class SemanticProcessor(DequeueHandlerBase):msg.uri, ctx=current_ctx),)- lock_transferred = Falsetry:if msg.context_type == "memory":- lock_transferred = Trueawait self._process_memory_directory(msg,ctx=current_ctx,@@ -445,7 +442,6 @@ class SemanticProcessor(DequeueHandlerBase):coalesce_key=msg.coalesce_key,coalesce_version=msg.coalesce_version,)- lock_transferred = Trueawait executor.run(run_uri)self._cache_dag_stats(msg.telemetry_id,@@ -455,8 +451,7 @@ class SemanticProcessor(DequeueHandlerBase):if not executor.stale:await self._enqueue_parent_refresh(msg, target_uri or msg.uri)finally:- if not lock_transferred:- await semantic_lock.close()+ await semantic_lock.close()self._merge_request_stats(msg.telemetry_id, processed=1)logger.info(f"Completed semantic generation for: {msg.uri}")self.report_success()@@ -523,7 +518,7 @@ class SemanticProcessor(DequeueHandlerBase):self,msg: SemanticMsg,ctx: Optional[RequestContext] = None,- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,) -> None:"""Process a memory directory with special handling.@@ -717,7 +712,7 @@ class SemanticProcessor(DequeueHandlerBase):)logger.info(f"Vectorized abstract.md and overview.md for {dir_uri}")finally:- await lock.close()+ passasync def _write_memory_directory_semantics(self,@@ -728,7 +723,7 @@ class SemanticProcessor(DequeueHandlerBase):overview: str,abstract: str,ctx: Optional[RequestContext],- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,) -> bool:return await write_semantic_sidecars(viking_fs=viking_fs,@@ -747,7 +742,7 @@ class SemanticProcessor(DequeueHandlerBase):target_uri: str,ctx: Optional[RequestContext] = None,file_change_status: Optional[Dict[str, bool]] = None,- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,) -> DiffResult:viking_fs = get_viking_fs()if not await viking_fs.exists(root_uri, ctx=ctx):@@ -755,7 +750,6 @@ class SemanticProcessor(DequeueHandlerBase):f"Semantic source no longer exists; refusing to sync into {target_uri}: {root_uri}")diff = DiffResult()- lock_handle = lock.handleasync def list_children(dir_uri: str) -> Tuple[Dict[str, str], Dict[str, str]]:files: Dict[str, str] = {}@@ -793,7 +787,7 @@ class SemanticProcessor(DequeueHandlerBase):target_conflict_dir,recursive=True,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lock,)diff.deleted_dirs.append(target_conflict_dir)target_dirs.pop(name, None)@@ -805,7 +799,7 @@ class SemanticProcessor(DequeueHandlerBase):if target_file and name in root_dirs and not root_file:try:- await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)+ await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)diff.deleted_files.append(target_file)target_files.pop(name, None)except Exception as e:@@ -816,7 +810,7 @@ class SemanticProcessor(DequeueHandlerBase):if target_file and not root_file:try:- await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)+ await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)diff.deleted_files.append(target_file)except Exception as e:logger.error(f"[SyncDiff] Failed to delete file: {target_file}, error={e}")@@ -839,7 +833,7 @@ class SemanticProcessor(DequeueHandlerBase):if changed:diff.updated_files.append(target_file)try:- await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)+ await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)except Exception as e:logger.error(f"[SyncDiff] Failed to remove old file before update: {target_file}, error={e}"@@ -849,7 +843,7 @@ class SemanticProcessor(DequeueHandlerBase):root_file,target_file,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lock,)except Exception as e:logger.error(@@ -865,7 +859,7 @@ class SemanticProcessor(DequeueHandlerBase):root_file,target_file_uri,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lock,)except Exception as e:logger.error(@@ -883,7 +877,7 @@ class SemanticProcessor(DequeueHandlerBase):await viking_fs.rm(target_conflict_file,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lock,)diff.deleted_files.append(target_conflict_file)target_files.pop(name, None)@@ -899,7 +893,7 @@ class SemanticProcessor(DequeueHandlerBase):target_subdir,recursive=True,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lock,)diff.deleted_dirs.append(target_subdir)except Exception as e:@@ -916,7 +910,7 @@ class SemanticProcessor(DequeueHandlerBase):root_subdir,target_subdir_uri,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lock,)except Exception as e:logger.error(@@ -931,9 +925,14 @@ class SemanticProcessor(DequeueHandlerBase):if not target_exists:parent_uri = VikingURI(target_uri).parentif parent_uri:- await viking_fs.mkdir(parent_uri.uri, exist_ok=True, ctx=ctx)+ await viking_fs.mkdir(+ parent_uri.uri,+ exist_ok=True,+ ctx=ctx,+ lease_ref=lock,+ )diff.added_dirs.append(target_uri)- await viking_fs.mv(root_uri, target_uri, ctx=ctx, lock_handle=lock_handle)+ await viking_fs.mv(root_uri, target_uri, ctx=ctx, lease_ref=lock)# The whole temp tree (including the hidden .image_mappings.json# sidecar) was moved into the target; rewrite local image paths now.await self._rewrite_target_image_uris(root_uri, target_uri, ctx=ctx, lock=lock)@@ -955,7 +954,7 @@ class SemanticProcessor(DequeueHandlerBase):root_uri: str,target_uri: str,ctx: Optional[RequestContext] = None,- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,) -> None:"""Rewrite local image refs in the target after a temp-to-target sync.@@ -1018,14 +1017,14 @@ class SemanticProcessor(DequeueHandlerBase):target_mapping,mapping_content,ctx=ctx,- lock_handle=lock.handle,+ lease_ref=lock,)except Exception:# Target subtree may not exist (doc removed in sync); skip.passtry:- await rewrite_image_uris(target_uri, ctx=ctx, lock_handle=lock.handle)+ await rewrite_image_uris(target_uri, ctx=ctx, lease_ref=lock)except Exception as e:logger.error(f"[SyncDiff] Failed to rewrite image URIs for {target_uri}: {e}")diff --git a/openviking/storage/queuefs/semantic_sidecar.py b/openviking/storage/queuefs/semantic_sidecar.pyindex 0c5c083fd..093001491 100644--- a/openviking/storage/queuefs/semantic_sidecar.py+++ b/openviking/storage/queuefs/semantic_sidecar.py@@ -2,10 +2,9 @@# SPDX-License-Identifier: AGPL-3.0"""Shared writeback for semantic sidecar files."""-from typing import Any, Callable, Optional+from typing import Any, Callable, Dict, Optionalfrom openviking.server.identity import RequestContext-from openviking.storage.transaction import NO_LOCK, LockLeasefrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)@@ -19,34 +18,31 @@ async def write_semantic_sidecars(abstract: str,ctx: Optional[RequestContext],is_stale: Callable[[], bool],- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,log_prefix: str = "[Semantic]",) -> bool:+ """Write .overview.md and .abstract.md sidecar files under dir_uri with exact-path locking."""if is_stale():logger.info("%s Skipping stale semantic write for %s", log_prefix, dir_uri)return False- try:- from openviking.storage.transaction import (- LockContext,- get_lock_manager,- )-- lock_manager = get_lock_manager()- except Exception:- await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, lock.handle)- return True-lock_paths = [viking_fs._uri_to_path(f"{dir_uri}/.overview.md", ctx=ctx),viking_fs._uri_to_path(f"{dir_uri}/.abstract.md", ctx=ctx),]- async with LockContext(lock_manager, lock_paths, lock_mode="exact", handle=lock.handle):+ sidecar_lease = lock+ owns_lease = sidecar_lease is None+ if sidecar_lease is None:+ sidecar_lease = await viking_fs._async_agfs.pathlock_acquire_exact_batch(lock_paths)+ try:if is_stale():logger.info("%s Skipping stale semantic write for %s", log_prefix, dir_uri)return False- await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, lock.handle)+ await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, sidecar_lease)return True+ finally:+ if owns_lease:+ await viking_fs._async_agfs.pathlock_release(sidecar_lease)async def _write_sidecars(@@ -55,18 +51,18 @@ async def _write_sidecars(overview: str,abstract: str,ctx: Optional[RequestContext],- lock_handle: Any = None,+ lease_ref: Optional[Dict[str, Any]] = None,) -> None:- # TODO: This must be optimized once pathlock is pushed down into ragfs.+ """Write sidecar files to the target directory."""await viking_fs.write_file(f"{dir_uri}/.overview.md",overview,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)await viking_fs.write_file(f"{dir_uri}/.abstract.md",abstract,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)diff --git a/openviking/storage/transaction/__init__.py b/openviking/storage/transaction/__init__.pyindex cdcd30756..93e772ac0 100644--- a/openviking/storage/transaction/__init__.py+++ b/openviking/storage/transaction/__init__.py@@ -3,46 +3,12 @@"""Transaction module for OpenViking.-Provides path-lock management and redo-log crash recovery.+Path-lock management has been moved to the Rust ragfs layer.+Python-side lock operations now go through RAGFSBindingClient.pathlock_* methods."""-from openviking.storage.transaction.lock_context import LockContext-from openviking.storage.transaction.lock_handle import LockHandle, LockOwner-from openviking.storage.transaction.lock_lease import (- NO_LOCK,- BorrowedLockLease,- LockHandoffRef,- LockLease,- OwnedLockLease,-)-from openviking.storage.transaction.lock_manager import (- LOCK_TIMEOUT_DEFAULT,- LockManager,- get_lock_handle_async,- get_lock_manager,- init_lock_manager,- release_all_locks,- reset_lock_manager,-)-from openviking.storage.transaction.path_lock import PathLockEnginefrom openviking.storage.transaction.redo_log import RedoLog__all__ = [- "BorrowedLockLease",- "LockContext",- "LockHandle",- "LockHandoffRef",- "LockLease",- "LOCK_TIMEOUT_DEFAULT",- "LockManager",- "LockOwner",- "NO_LOCK",- "OwnedLockLease",- "PathLockEngine","RedoLog",- "get_lock_handle_async",- "get_lock_manager",- "init_lock_manager",- "release_all_locks",- "reset_lock_manager",]diff --git a/openviking/storage/transaction/lock_context.py b/openviking/storage/transaction/lock_context.pydeleted file mode 100644index 424cca343..000000000--- a/openviking/storage/transaction/lock_context.py+++ /dev/null@@ -1,97 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""LockContext — async context manager for acquiring/releasing path locks."""--from typing import Any, Optional--from openviking.storage.errors import LockAcquisitionError-from openviking.storage.transaction.lock_handle import LockHandle-from openviking.storage.transaction.lock_lease import OwnedLockLease-from openviking.storage.transaction.lock_manager import LOCK_TIMEOUT_DEFAULT, LockManager---class LockContext:- """``async with LockContext(manager, paths, mode) as handle: ...``-- Acquires locks on entry, releases them on exit. No undo / journal / commit- semantics — just a lock scope.- """-- def __init__(- self,- lock_manager: LockManager,- paths: list[str],- lock_mode: str = "exact",- mv_dst_path: Optional[str] = None,- src_is_dir: bool = True,- handle: Optional[LockHandle] = None,- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ):- self._manager = lock_manager- self._paths = paths- self._lock_mode = lock_mode- self._mv_dst_path = mv_dst_path- self._src_is_dir = src_is_dir- self._handle: Optional[LockHandle] = handle- self._timeout = timeout- self._owns_handle = handle is None- self._locks_before: list[str] = []- self._acquired_lock_paths: list[str] = []- self._owned_lease: Optional[OwnedLockLease] = None-- async def __aenter__(self) -> LockHandle:- if self._handle is None:- self._handle = self._manager.create_handle()- self._locks_before = list(self._handle.locks)- success = False-- if self._lock_mode == "tree":- for path in self._paths:- success = await self._manager.acquire_tree(- self._handle, path, timeout=self._timeout- )- if not success:- break- elif self._lock_mode == "exact":- success = await self._manager.acquire_exact_path_batch(- self._handle, self._paths, timeout=self._timeout- )- elif self._lock_mode == "mv":- if self._mv_dst_path is None:- raise LockAcquisitionError("mv lock mode requires mv_dst_path")- success = await self._manager.acquire_mv(- self._handle,- self._paths[0],- self._mv_dst_path,- src_is_dir=self._src_is_dir,- timeout=self._timeout,- )- else:- raise LockAcquisitionError(f"Unsupported lock mode: {self._lock_mode}")-- self._acquired_lock_paths = [- lock_path for lock_path in self._handle.locks if lock_path not in self._locks_before- ]-- if not success:- if self._owns_handle:- await self._manager.release(self._handle)- else:- await self._manager.release_selected(self._handle, self._acquired_lock_paths)- raise LockAcquisitionError(- f"Failed to acquire {self._lock_mode} lock for {self._paths}"- )- if self._owns_handle and self._handle.locks:- self._owned_lease = OwnedLockLease.from_handle(self._manager, self._handle)- return self._handle-- async def __aexit__(self, exc_type, exc_val, exc_tb):- if self._handle:- if self._owns_handle:- if self._owned_lease:- await self._owned_lease.close()- else:- await self._manager.release(self._handle)- else:- await self._manager.release_selected(self._handle, self._acquired_lock_paths)- return Falsediff --git a/openviking/storage/transaction/lock_handle.py b/openviking/storage/transaction/lock_handle.pydeleted file mode 100644index 0e2c8f084..000000000--- a/openviking/storage/transaction/lock_handle.py+++ /dev/null@@ -1,48 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Lock handle and LockOwner protocol for path lock integration."""--import time-import uuid-from dataclasses import dataclass, field-from typing import Protocol, runtime_checkable---def _new_lock_id() -> str:- return str(uuid.uuid4())---@runtime_checkable-class LockOwner(Protocol):- """Minimal interface that path lock code requires from its caller."""-- id: str- locks: list[str]-- def add_lock(self, path: str) -> None:- raise NotImplementedError-- def remove_lock(self, path: str) -> None:- raise NotImplementedError---@dataclass-class LockHandle:- """Identifies a lock holder. Path lock code uses ``id`` to generate fencing tokens- and ``locks`` to track acquired lock files."""-- id: str = field(default_factory=_new_lock_id)- locks: list[str] = field(default_factory=list)- created_at: float = field(default_factory=time.time)- last_active_at: float = field(init=False)-- def __post_init__(self) -> None:- self.last_active_at = self.created_at-- def add_lock(self, lock_path: str) -> None:- if lock_path not in self.locks:- self.locks.append(lock_path)-- def remove_lock(self, lock_path: str) -> None:- if lock_path in self.locks:- self.locks.remove(lock_path)diff --git a/openviking/storage/transaction/lock_lease.py b/openviking/storage/transaction/lock_lease.pydeleted file mode 100644index 3cbf26ddb..000000000--- a/openviking/storage/transaction/lock_lease.py+++ /dev/null@@ -1,229 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Typed lock ownership helpers for path-lock users."""--from __future__ import annotations--import asyncio-from contextlib import suppress-from dataclasses import dataclass-from typing import Any, Iterable, Optional--from openviking.storage.errors import LockAcquisitionError-from openviking.storage.transaction.lock_handle import LockHandle-from openviking.storage.transaction.lock_manager import (- LOCK_TIMEOUT_DEFAULT,- LockManager,- get_lock_manager,-)-from openviking_cli.utils.logger import get_logger--logger = get_logger(__name__)---@dataclass(frozen=True)-class LockHandoffRef:- """Serializable reference used to hand lock ownership through a queue."""-- handle_id: str- lock_paths: tuple[str, ...] = ()-- @classmethod- def from_value(cls, value: Any) -> Optional["LockHandoffRef"]:- if value is None:- return None- if isinstance(value, LockHandoffRef):- return value- if not isinstance(value, dict):- raise ValueError("lock_handoff must be an object")-- handle_id = value.get("handle_id")- if not handle_id:- return None- lock_paths = tuple(str(path) for path in value.get("lock_paths", []) if path)- return cls(handle_id=str(handle_id), lock_paths=lock_paths)-- def to_dict(self) -> dict[str, Any]:- return {"handle_id": self.handle_id, "lock_paths": list(self.lock_paths)}---class LockLease:- """Base lock lease interface."""-- @property- def handle(self) -> Optional[LockHandle]:- return None-- @property- def handle_id(self) -> str:- handle = self.handle- return handle.id if handle else ""-- @property- def active(self) -> bool:- handle = self.handle- return bool(handle and handle.locks)-- def as_borrowed(self) -> "LockLease":- return self-- def to_handoff(self) -> Optional[LockHandoffRef]:- return None-- async def close(self) -> None:- return-- async def handoff(self) -> None:- return---class _NoLockLease(LockLease):- pass---NO_LOCK: LockLease = _NoLockLease()---@dataclass-class BorrowedLockLease(LockLease):- """A lock lease borrowed from an outer owner."""-- manager: LockManager- _handle: LockHandle-- @classmethod- def from_handle(cls, manager: LockManager, handle: LockHandle) -> "BorrowedLockLease":- return cls(manager=manager, _handle=handle)-- @property- def handle(self) -> Optional[LockHandle]:- return self.manager.get_handle(self._handle.id)-- def as_borrowed(self) -> "LockLease":- return self---class OwnedLockLease(LockLease):- """An owned lock lease that refreshes and releases its handle."""-- def __init__(- self,- manager: LockManager,- handle: LockHandle,- *,- start_refresh: bool = True,- ):- self._manager = manager- self._handle: Optional[LockHandle] = handle- self._refresh_task: Optional[asyncio.Task] = None- if start_refresh and handle.locks:- self._start_refresh()-- @classmethod- def from_handle(cls, manager: LockManager, handle: LockHandle) -> "OwnedLockLease":- return cls(manager, handle)-- @classmethod- async def from_handoff(- cls,- ref: LockHandoffRef,- manager: Optional[LockManager] = None,- ) -> "OwnedLockLease":- manager = manager or get_lock_manager()- handle = await manager.get_handle_async(ref.handle_id)- if handle is None:- handle = await manager.adopt_handle_async(ref.handle_id, ref.lock_paths)- if handle is None:- raise LockAcquisitionError(f"Lock handle is no longer active: {ref.handle_id}")- return cls(manager, handle)-- @classmethod- async def acquire_tree(- cls,- manager: LockManager,- path: str,- *,- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> "OwnedLockLease":- handle = manager.create_handle()- if await manager.acquire_tree(handle, path, timeout=timeout):- return cls(manager, handle)- await manager.release(handle)- raise LockAcquisitionError(f"Failed to acquire tree lock for {path}")-- @classmethod- async def acquire_exact_paths(- cls,- manager: LockManager,- paths: Iterable[str],- *,- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> "OwnedLockLease":- handle = manager.create_handle()- path_list = list(paths)- if await manager.acquire_exact_path_batch(handle, path_list, timeout=timeout):- return cls(manager, handle)- await manager.release(handle)- raise LockAcquisitionError(f"Failed to acquire exact lock for {path_list}")-- @property- def handle(self) -> Optional[LockHandle]:- if self._handle is None:- return None- return self._manager.get_handle(self._handle.id)-- def as_borrowed(self) -> LockLease:- handle = self.handle- if handle is None:- return NO_LOCK- return BorrowedLockLease.from_handle(self._manager, handle)-- def to_handoff(self) -> Optional[LockHandoffRef]:- handle = self.handle- if handle is None:- return None- return LockHandoffRef(handle_id=handle.id, lock_paths=tuple(handle.locks))-- async def close(self) -> None:- await self._stop_refresh()- handle = self.handle or self._handle- self._handle = None- if handle is not None:- await self._manager.release(handle)-- async def handoff(self) -> None:- """Stop managing this lease after another worker has received its handle."""- await self._stop_refresh()- self._handle = None-- def _start_refresh(self) -> None:- if self._refresh_task is not None:- return- self._refresh_task = asyncio.create_task(self._refresh_loop())-- async def _refresh_loop(self) -> None:- try:- expire = self._manager._path_lock._lock_expire- interval = max(0.1, expire / 2)- except Exception:- interval = 150.0-- while True:- try:- await asyncio.sleep(interval)- handle = self.handle- if handle is None:- return- await self._manager.refresh_lock(handle)- except asyncio.CancelledError:- raise- except Exception as exc:- logger.warning("Failed to refresh lock handle %s: %s", self.handle_id, exc)-- async def _stop_refresh(self) -> None:- if self._refresh_task is None:- return- self._refresh_task.cancel()- with suppress(asyncio.CancelledError):- await self._refresh_task- self._refresh_task = Nonediff --git a/openviking/storage/transaction/lock_manager.py b/openviking/storage/transaction/lock_manager.pydeleted file mode 100644index d31efc612..000000000--- a/openviking/storage/transaction/lock_manager.py+++ /dev/null@@ -1,594 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""LockManager — global singleton managing lock lifecycle and redo recovery."""--import asyncio-import json-import time-from typing import Any, Dict, List, Optional, Protocol--from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient-from openviking.storage.transaction.lock_handle import LockHandle-from openviking.storage.transaction.path_lock import PathLockEngine-from openviking.storage.transaction.redo_log import RedoLog-from openviking_cli.utils.logger import get_logger--logger = get_logger(__name__)--_HANDLE_CLEANUP_INTERVAL_SECONDS = 60.0-LOCK_TIMEOUT_DEFAULT = object()---class _LockManagerLike(Protocol):- def get_handle(self, handle_id: str) -> Optional[LockHandle]: ...---async def get_lock_handle_async(- lock_manager: _LockManagerLike, handle_id: str-) -> Optional[LockHandle]:- getter = getattr(lock_manager, "get_handle_async", None)- if getter is not None:- return await getter(handle_id)- return await asyncio.to_thread(lock_manager.get_handle, handle_id)---class LockManager:- """Global singleton. Manages lock lifecycle and stale cleanup."""-- def __init__(- self,- agfs: AGFSSyncClientProtocol,- lock_timeout: float = 0.0,- lock_expire: float = 300.0,- redo_recovery_enabled: bool = True,- ):- self._agfs = agfs- self._async_agfs = AsyncAGFSClient(agfs)- self._path_lock = PathLockEngine(agfs, lock_expire=lock_expire)- self._lock_timeout = lock_timeout- self._redo_recovery_enabled = redo_recovery_enabled- self._redo_log = RedoLog(agfs)- self._handles: Dict[str, LockHandle] = {}- self._cleanup_task: Optional[asyncio.Task] = None- self._redo_task: Optional[asyncio.Task] = None- self._running = False-- @property- def redo_recovery_enabled(self) -> bool:- return self._redo_recovery_enabled-- def _resolve_timeout(self, timeout: Any) -> Optional[float]:- return self._lock_timeout if timeout is LOCK_TIMEOUT_DEFAULT else timeout-- def _mark_handle_active(self, handle: LockHandle) -> None:- handle.last_active_at = time.time()-- def get_active_handles(self) -> Dict[str, LockHandle]:- active_handles: Dict[str, LockHandle] = {}- for handle in list(self._handles.values()):- current = self._reconcile_handle(handle)- if current and current.locks:- active_handles[current.id] = current- return active_handles-- async def get_active_handles_async(self) -> Dict[str, LockHandle]:- active_handles: Dict[str, LockHandle] = {}- for handle in list(self._handles.values()):- current = await self._reconcile_handle_async(handle)- if current and current.locks:- active_handles[current.id] = current- return active_handles-- async def start(self) -> None:- """Start background cleanup and redo recovery."""- self._running = True- self._cleanup_task = asyncio.create_task(self._stale_cleanup_loop())- if self._redo_recovery_enabled:- self._redo_task = asyncio.create_task(self._recover_pending_redo())- else:- logger.info("Redo recovery disabled by config; skipping pending redo recovery")-- async def stop(self) -> None:- """Stop cleanup and release all active locks."""- self._running = False- if self._redo_task:- self._redo_task.cancel()- try:- await self._redo_task- except asyncio.CancelledError:- pass- self._redo_task = None- if self._cleanup_task:- self._cleanup_task.cancel()- try:- if self._cleanup_task.get_loop() is asyncio.get_running_loop():- await self._cleanup_task- except asyncio.CancelledError:- pass- self._cleanup_task = None- for handle in list(self._handles.values()):- await self._path_lock.release(handle)- self._handles.clear()-- def create_handle(self) -> LockHandle:- handle = LockHandle()- self._handles[handle.id] = handle- return handle-- async def acquire_exact_path(- self,- handle: LockHandle,- path: str,- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> bool:- acquired = await self._path_lock.acquire_exact_path(- path, handle, timeout=self._resolve_timeout(timeout)- )- if acquired:- self._mark_handle_active(handle)- return acquired-- async def acquire_tree(- self,- handle: LockHandle,- path: str,- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> bool:- acquired = await self._path_lock.acquire_tree(- path, handle, timeout=self._resolve_timeout(timeout)- )- if acquired:- self._mark_handle_active(handle)- return acquired-- async def acquire_tree_batch(- self,- handle: LockHandle,- paths: List[str],- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> bool:- """- 一次性对多个路径进行树锁加锁,使用有序加锁法防止死锁-- 核心思想:- 1. 对路径按照固定的顺序进行排序,确保所有进程获取锁的顺序一致- 2. 防止循环等待条件,从而避免死锁-- 排序规则:- 1. 路径长度升序- 2. 长度相同的路径按照字典序升序-- Args:- handle: 锁句柄- paths: 需要加锁的路径列表- timeout: 超时时间,None表示无限等待-- Returns:- 是否成功获取所有锁- """- if not paths:- self._mark_handle_active(handle)- return True-- sorted_paths = sorted(paths, key=lambda x: (len(x), x))- acquired_lock_paths: List[str] = []-- try:- for path in sorted_paths:- locks_before = set(handle.locks)- success = await self._path_lock.acquire_tree(- path,- handle,- timeout=self._resolve_timeout(timeout),- )- if not success:- await self._path_lock.release_selected(handle, acquired_lock_paths)- return False- newly = [lp for lp in handle.locks if lp not in locks_before]- acquired_lock_paths.extend(newly)-- self._mark_handle_active(handle)- return True-- except Exception as e:- logger.error(f"Failed to acquire tree batch lock: {e}")- await self._path_lock.release_selected(handle, acquired_lock_paths)- return False-- async def acquire_exact_path_batch(- self,- handle: LockHandle,- paths: List[str],- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> bool:- if not paths:- self._mark_handle_active(handle)- return True-- sorted_paths = sorted(dict.fromkeys(paths), key=lambda x: (len(x), x))- acquired_lock_paths: List[str] = []-- try:- for path in sorted_paths:- locks_before = set(handle.locks)- success = await self._path_lock.acquire_exact_path(- path,- handle,- timeout=self._resolve_timeout(timeout),- )- if not success:- await self._path_lock.release_selected(handle, acquired_lock_paths)- return False- newly = [lp for lp in handle.locks if lp not in locks_before]- acquired_lock_paths.extend(newly)-- self._mark_handle_active(handle)- return True-- except Exception as e:- logger.error(f"Failed to acquire exact-path batch lock: {e}")- await self._path_lock.release_selected(handle, acquired_lock_paths)- return False-- async def acquire_exact_tree_batch(- self,- handle: LockHandle,- exact_paths: List[str],- tree_paths: List[str],- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> bool:- exact_set = set(exact_paths)- tree_set = set(tree_paths)- exact_only = [p for p in exact_set if p not in tree_set]- all_pairs = [(p, False) for p in exact_only] + [(p, True) for p in tree_set]-- if not all_pairs:- self._mark_handle_active(handle)- return True-- sorted_pairs = sorted(all_pairs, key=lambda x: (len(x[0]), x[0]))- acquired_lock_paths: List[str] = []-- try:- for path, is_tree in sorted_pairs:- locks_before = set(handle.locks)- if is_tree:- success = await self._path_lock.acquire_tree(- path,- handle,- timeout=self._resolve_timeout(timeout),- )- else:- success = await self._path_lock.acquire_exact_path(- path,- handle,- timeout=self._resolve_timeout(timeout),- )- if not success:- await self._path_lock.release_selected(handle, acquired_lock_paths)- return False- newly = [lp for lp in handle.locks if lp not in locks_before]- acquired_lock_paths.extend(newly)-- self._mark_handle_active(handle)- return True-- except Exception as e:- logger.error(f"Failed to acquire exact/tree batch lock: {e}")- await self._path_lock.release_selected(handle, acquired_lock_paths)- return False-- async def acquire_mv(- self,- handle: LockHandle,- src: str,- dst: str,- src_is_dir: bool = True,- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> bool:- acquired = await self._path_lock.acquire_mv(- src,- dst,- handle,- timeout=self._resolve_timeout(timeout),- src_is_dir=src_is_dir,- )- if acquired:- self._mark_handle_active(handle)- return acquired-- def get_handle(self, handle_id: str) -> Optional[LockHandle]:- handle = self._handles.get(handle_id)- if handle is None:- return None- current = self._reconcile_handle(handle)- if current is None or not current.locks:- return None- return current-- def adopt_handle(self, handle_id: str, lock_paths: List[str]) -> Optional[LockHandle]:- handle = self.get_handle(handle_id)- if handle is not None:- return handle-- adopted = LockHandle(id=handle_id)- for lock_path in dict.fromkeys(lock_paths):- if self._path_lock.is_lock_owned_by(lock_path, handle_id):- adopted.add_lock(lock_path)- if not adopted.locks:- return None-- self._handles[adopted.id] = adopted- self._mark_handle_active(adopted)- return adopted-- async def adopt_handle_async(- self, handle_id: str, lock_paths: List[str]- ) -> Optional[LockHandle]:- handle = await self.get_handle_async(handle_id)- if handle is not None:- return handle-- adopted = LockHandle(id=handle_id)- for lock_path in dict.fromkeys(lock_paths):- if await self._path_lock.is_lock_owned_by_async(lock_path, handle_id):- adopted.add_lock(lock_path)- if not adopted.locks:- return None-- self._handles[adopted.id] = adopted- self._mark_handle_active(adopted)- return adopted-- async def get_handle_async(self, handle_id: str) -> Optional[LockHandle]:- handle = self._handles.get(handle_id)- if handle is None:- return None- current = await self._reconcile_handle_async(handle)- if current is None or not current.locks:- return None- return current-- def is_path_locked(self, path: str, ignore_stale: bool = True) -> bool:- """Check whether *path* is currently locked.-- Semantics align with conflict detection in the acquire flow: the path- is considered locked if it (or any ancestor) holds a lock. By default,- stale locks are ignored because they will be reclaimed on the next- acquire attempt.- """- try:- return self._path_lock.is_locked(path, ignore_stale=ignore_stale)- except Exception as e:- logger.warning(f"is_path_locked failed for {path}: {e}")- return False-- async def is_path_locked_async(self, path: str, ignore_stale: bool = True) -> bool:- """Async variant for request/background paths."""- try:- return await self._path_lock.is_locked_async(path, ignore_stale=ignore_stale)- except Exception as e:- logger.warning(f"is_path_locked_async failed for {path}: {e}")- return False-- async def refresh_lock(self, handle: LockHandle) -> None:- current = await self._reconcile_handle_async(handle)- if current is None:- return-- result = await self._path_lock.refresh(current)- for lock_path in result.lost_paths:- current.remove_lock(lock_path)-- if result.refreshed_paths:- self._mark_handle_active(current)-- await self._reconcile_handle_async(current)-- async def release(self, handle: LockHandle) -> None:- await self._path_lock.release(handle)- self._handles.pop(handle.id, None)-- async def release_selected(self, handle: LockHandle, lock_paths: List[str]) -> None:- await self._path_lock.release_selected(handle, lock_paths)-- async def _stale_cleanup_loop(self) -> None:- """Check and release leaked handles every 60 s (in-process safety net)."""- while self._running:- await asyncio.sleep(_HANDLE_CLEANUP_INTERVAL_SECONDS)- now = time.time()- stale = []- for handle in list(self._handles.values()):- current = await self._reconcile_handle_async(handle)- if current and self._is_handle_stale(current, now):- stale.append(current)- for handle in stale:- logger.warning(f"Releasing stale lock handle {handle.id}")- await self.release(handle)-- def _is_handle_stale(self, handle: LockHandle, now: Optional[float] = None) -> bool:- """Return True when a live lock handle has stopped refreshing for too long."""- if not handle.locks:- return False- if now is None:- now = time.time()- return now - handle.last_active_at > self._path_lock._lock_expire-- def _reconcile_handle(self, handle: LockHandle) -> Optional[LockHandle]:- had_locks = bool(handle.locks)- lost_paths = self._path_lock.collect_lost_owner_locks(handle)- for lock_path in lost_paths:- handle.remove_lock(lock_path)- if had_locks and not handle.locks:- self._handles.pop(handle.id, None)- return None- return handle-- async def _reconcile_handle_async(self, handle: LockHandle) -> Optional[LockHandle]:- had_locks = bool(handle.locks)- lost_paths = await self._path_lock.collect_lost_owner_locks_async(handle)- for lock_path in lost_paths:- handle.remove_lock(lock_path)- if had_locks and not handle.locks:- self._handles.pop(handle.id, None)- return None- return handle-- # ------------------------------------------------------------------- # Redo recovery (session_memory only)- # -------------------------------------------------------------------- async def _recover_pending_redo(self) -> None:- pending_ids = await self._redo_log.list_pending_async()- for task_id in pending_ids:- logger.info(f"Recovering pending redo task: {task_id}")- try:- info = await self._redo_log.read_async(task_id)- if info:- await self._redo_session_memory(info)- await self._redo_log.mark_done_async(task_id)- except Exception as e:- logger.error(f"Redo recovery failed for {task_id}: {e}", exc_info=True)-- async def _redo_session_memory(self, info: Dict[str, Any]) -> None:- """Re-extract memories from archive.-- Lets exceptions from _enqueue_semantic propagate so the caller- can decide whether to mark the redo task as done.- """- from openviking.message import Message- from openviking.server.identity import RequestContext, Role- from openviking.storage.viking_fs import get_viking_fs- from openviking_cli.session.user_id import UserIdentifier-- archive_uri = info.get("archive_uri")- session_uri = info.get("session_uri")- account_id = info.get("account_id", "default")- user_id = info.get("user_id", "default")- role_str = info.get("role", "root")-- if not archive_uri or not session_uri:- raise ValueError("Cannot redo session_memory: missing archive_uri or session_uri")-- # 1. Build request context (needed for path conversion below)- user = UserIdentifier(account_id=account_id, user_id=user_id)- ctx = RequestContext(user=user, role=Role(role_str))-- # 2. Read archived messages- messages_uri = f"{archive_uri}/messages.jsonl"- viking_fs = get_viking_fs()- agfs_path = viking_fs._uri_to_path(messages_uri, ctx=ctx)- messages = []- try:- content = await self._async_agfs.cat(agfs_path)- if isinstance(content, bytes):- content = content.decode("utf-8")- for line in content.strip().split("\n"):- if line.strip():- try:- messages.append(Message.from_dict(json.loads(line)))- except Exception:- pass- except Exception as e:- logger.warning(f"Cannot read archive for redo: {agfs_path}: {e}")-- # 3. Re-extract memories (best-effort, only if archive was readable)- if messages:- session_id = session_uri.rstrip("/").rsplit("/", 1)[-1]- try:- from openviking.session import create_session_compressor-- compressor = create_session_compressor(vikingdb=None)- memories = await asyncio.wait_for(- compressor.extract_long_term_memories(- messages=messages,- user=user,- session_id=session_id,- ctx=ctx,- ),- timeout=60.0,- )- # extract_long_term_memories may return either a list[Context]- # (v2) or a {"contexts": [...], "session_skills": [...]} dict (v3).- if isinstance(memories, dict):- memories = memories.get("contexts", [])- logger.info(f"Redo: extracted {len(memories)} memories from {archive_uri}")- except Exception as e:- logger.warning(f"Redo: memory extraction failed ({e}), falling back to queue")-- # 4. Always enqueue semantic processing as fallback- await self._enqueue_semantic(- uri=session_uri,- context_type="memory",- account_id=account_id,- user_id=user_id,- peer_id=user_id,- role=role_str,- )-- async def _enqueue_semantic(self, **params: Any) -> None:- from openviking.storage.queuefs import get_queue_manager- from openviking.storage.queuefs.semantic_msg import SemanticMsg- from openviking.storage.queuefs.semantic_queue import SemanticQueue-- queue_manager = get_queue_manager()- if queue_manager is None:- logger.debug("No queue manager available, skipping enqueue_semantic")- return-- uri = params.get("uri")- if not uri:- return-- msg = SemanticMsg(- uri=uri,- context_type=params.get("context_type", "resource"),- account_id=params.get("account_id", "default"),- user_id=params.get("user_id", "default"),- peer_id=params.get("peer_id", "default"),- role=params.get("role", "root"),- )- semantic_queue: SemanticQueue = queue_manager.get_queue(queue_manager.SEMANTIC) # type: ignore[assignment]- await semantic_queue.enqueue(msg)---# ----------------------------------------------------------------------------# Module-level singleton-# -----------------------------------------------------------------------------_lock_manager: Optional[LockManager] = None---def init_lock_manager(- agfs: AGFSSyncClientProtocol,- lock_timeout: float = 0.0,- lock_expire: float = 300.0,- redo_recovery_enabled: bool = True,-) -> LockManager:- global _lock_manager- _lock_manager = LockManager(- agfs=agfs,- lock_timeout=lock_timeout,- lock_expire=lock_expire,- redo_recovery_enabled=redo_recovery_enabled,- )- return _lock_manager---def get_lock_manager() -> LockManager:- if _lock_manager is None:- raise RuntimeError("LockManager not initialized. Call init_lock_manager() first.")- return _lock_manager---def reset_lock_manager() -> None:- global _lock_manager- _lock_manager = None---async def release_all_locks() -> None:- """Release all active lock handles. **Test-only utility.**"""- if _lock_manager is None:- return- for handle in list((await _lock_manager.get_active_handles_async()).values()):- await _lock_manager.release(handle)diff --git a/openviking/storage/transaction/path_lock.py b/openviking/storage/transaction/path_lock.pydeleted file mode 100644index 7b80c8dfb..000000000--- a/openviking/storage/transaction/path_lock.py+++ /dev/null@@ -1,859 +0,0 @@-import asyncio-import hashlib-import re-import time-from dataclasses import dataclass, field-from typing import Any, Callable, Optional, Tuple--from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient-from openviking.pyagfs.async_client import fs_ctx_from_agfs_path-from openviking.storage.internal_names import (- MULTIWRITE_EXACT_LOCK_FILE_PREFIX,- MULTIWRITE_PATH_LOCK_FILE,-)-from openviking.storage.transaction.lock_handle import LockOwner-from openviking_cli.utils.logger import get_logger--logger = get_logger(__name__)--# Lock file name-LOCK_FILE_NAME = MULTIWRITE_PATH_LOCK_FILE-EXACT_LOCK_FILE_PREFIX = MULTIWRITE_EXACT_LOCK_FILE_PREFIX--# Lock type constants-LOCK_TYPE_EXACT = "E"-LOCK_TYPE_TREE = "T"-# Upgrade compatibility: old POINT/SUBTREE tokens are still treated as tree locks.-_READ_ONLY_TREE_LOCK_TYPES = {"P", "S"}--# Default poll interval when waiting for a lock (seconds)-_POLL_INTERVAL = 0.1-_WAIT_LOG_INTERVAL = 10.0-_last_timeout_warning_at: dict[str, float] = {}---@dataclass-class LockRefreshResult:- refreshed_paths: list[str] = field(default_factory=list)- lost_paths: list[str] = field(default_factory=list)- failed_paths: list[str] = field(default_factory=list)---def _make_fencing_token(owner_id: str, lock_type: str = LOCK_TYPE_EXACT) -> str:- return f"{owner_id}:{time.time_ns()}:{lock_type}"---def _parse_fencing_token(token: str) -> Tuple[str, int, str]:- known_types = {LOCK_TYPE_EXACT, LOCK_TYPE_TREE, *_READ_ONLY_TREE_LOCK_TYPES}- if len(token) >= 2 and token[-2] == ":" and token[-1] in known_types:- lock_type = LOCK_TYPE_TREE if token[-1] in _READ_ONLY_TREE_LOCK_TYPES else token[-1]- rest = token[:-2]- idx = rest.rfind(":")- if idx >= 0:- owner_id_part = rest[:idx]- ts_part = rest[idx + 1 :]- try:- return owner_id_part, int(ts_part), lock_type- except ValueError:- pass- return rest, 0, lock_type-- return token, 0, LOCK_TYPE_EXACT---def _log_timeout_waiting(message: str) -> None:- now = asyncio.get_running_loop().time()- last_warning_at = _last_timeout_warning_at.get(message, 0.0)- if not last_warning_at or now - last_warning_at >= _WAIT_LOG_INTERVAL:- logger.warning(message)- _last_timeout_warning_at[message] = now---def _call_sync_agfs_with_ctx(- method: Callable[..., Any], path: str, *args: Any, **kwargs: Any-) -> Any:- """Call a sync AGFS method with path-derived FsContext, falling back for legacy fakes."""- try:- return method(path, *args, **kwargs, ctx=fs_ctx_from_agfs_path(path))- except TypeError as exc:- if "unexpected keyword argument 'ctx'" not in str(exc):- raise- return method(path, *args, **kwargs)---class PathLockEngine:- def __init__(self, agfs_client: AGFSSyncClientProtocol, lock_expire: float = 300.0):- self._agfs = agfs_client- self._async_agfs = AsyncAGFSClient(agfs_client)- self._lock_expire = lock_expire-- def _get_lock_path(self, path: str) -> str:- path = path.rstrip("/") or "/"- if path == "/":- return f"/{LOCK_FILE_NAME}"- return f"{path}/{LOCK_FILE_NAME}"-- def _is_existing_directory(self, path: str) -> bool:- try:- stat = _call_sync_agfs_with_ctx(self._agfs.stat, path.rstrip("/") or "/")- except Exception:- return False- if isinstance(stat, dict):- return stat.get("isDir") is True- return getattr(stat, "isDir", None) is True-- async def _is_existing_directory_async(self, path: str) -> bool:- try:- stat = await self._async_agfs.stat(path.rstrip("/") or "/")- except Exception:- return False- if isinstance(stat, dict):- return stat.get("isDir") is True- return getattr(stat, "isDir", None) is True-- async def _is_existing_path_async(self, path: str) -> bool:- try:- await self._async_agfs.stat(path.rstrip("/") or "/")- return True- except Exception:- return False-- def _get_prefixed_exact_lock_path(self, path: str) -> str:- path = path.rstrip("/") or "/"- parent = self._get_parent_path(path)- if not parent:- return self._get_lock_path(path)- name = path.rsplit("/", 1)[-1]- safe_name = re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("._") or "path"- safe_name = safe_name[:80]- digest = hashlib.sha1(path.encode("utf-8")).hexdigest()[:16]- return f"{parent}/{EXACT_LOCK_FILE_PREFIX}{safe_name}.{digest}"-- def _get_exact_lock_path(self, path: str) -> str:- """Return the primary lock-file path for an exact path lock."""- if self._is_existing_directory(path):- return self._get_lock_path(path)- return self._get_prefixed_exact_lock_path(path)-- def _get_exact_lock_paths(self, path: str) -> list[str]:- """Return all lock-file paths that can protect this exact path."""- primary = self._get_exact_lock_path(path)- prefixed = self._get_prefixed_exact_lock_path(path)- if primary == prefixed:- return [primary]- return [primary, prefixed]-- async def _get_exact_lock_path_async(self, path: str) -> str:- """Async variant for acquire paths, where stat may be remote/blocking."""- if await self._is_existing_directory_async(path):- return self._get_lock_path(path)- return self._get_prefixed_exact_lock_path(path)-- async def _get_exact_lock_paths_async(self, path: str) -> list[str]:- primary = await self._get_exact_lock_path_async(path)- prefixed = self._get_prefixed_exact_lock_path(path)- if primary == prefixed:- return [primary]- return [primary, prefixed]-- async def _ensure_directory_exists_async(self, path: str):- """Async variant for lock acquisition paths."""- try:- await self._async_agfs.stat(path)- except Exception:- try:- parent = self._get_parent_path(path)- if parent:- await self._ensure_directory_exists_async(parent)- await self._async_agfs.mkdir(path)- logger.debug(f"Directory created: {path}")- except Exception as e:- if await self._is_existing_directory_async(path):- logger.debug(f"Directory created concurrently: {path}")- return True- logger.warning(f"Failed to create directory {path}: {e}")- return False- return True-- def _get_parent_path(self, path: str) -> Optional[str]:- path = path.rstrip("/")- if "/" not in path:- return None- parent = path.rsplit("/", 1)[0]- return parent if parent else None-- def _read_token(self, lock_path: str) -> Optional[str]:- try:- content = _call_sync_agfs_with_ctx(self._agfs.read, lock_path)- if isinstance(content, bytes):- token = content.decode("utf-8").strip()- else:- token = str(content).strip()- return token if token else None- except Exception:- return None-- async def _read_token_async(self, lock_path: str) -> Optional[str]:- try:- content = await self._async_agfs.read(lock_path)- if isinstance(content, bytes):- token = content.decode("utf-8").strip()- else:- token = str(content).strip()- return token if token else None- except Exception:- return None-- def _read_owner_and_type(self, lock_path: str) -> Tuple[Optional[str], Optional[str]]:- token = self._read_token(lock_path)- if token is None:- return None, None- owner_id, _, lock_type = _parse_fencing_token(token)- return owner_id, lock_type-- async def _read_owner_and_type_async(- self, lock_path: str- ) -> Tuple[Optional[str], Optional[str]]:- token = await self._read_token_async(lock_path)- if token is None:- return None, None- owner_id, _, lock_type = _parse_fencing_token(token)- return owner_id, lock_type-- def is_lock_owned_by(self, lock_path: str, owner_id: str) -> bool:- current_owner_id, _ = self._read_owner_and_type(lock_path)- return current_owner_id == owner_id-- async def is_lock_owned_by_async(self, lock_path: str, owner_id: str) -> bool:- current_owner_id, _ = await self._read_owner_and_type_async(lock_path)- return current_owner_id == owner_id-- async def _is_lock_owned_by_async(self, lock_path: str, owner_id: str) -> bool:- return await self.is_lock_owned_by_async(lock_path, owner_id)-- def is_locked(self, path: str, ignore_stale: bool = True) -> bool:- """Check whether *path* is currently locked.-- Detection rules (aligned with conflict checks in the acquire flow):- - The path itself has a valid .path.ovlock; or- - The path has a valid exact-path lock in the parent directory; or- - Any ancestor directory holds a TREE lock.-- Args:- path: Path to check (already converted to AGFS internal path).- ignore_stale: Whether to ignore expired (stale) locks. Defaults- to True to stay consistent with the acquire flow: stale- locks will be cleaned up by the next acquirer, so they are- not considered as held here.- """- # 1. Lock on the path itself- own_lock_path = self._get_lock_path(path)- token = self._read_token(own_lock_path)- if token is not None:- if not (ignore_stale and self.is_lock_stale(own_lock_path, self._lock_expire)):- return True-- # 2. ExactPathLock for file, directory name, or not-yet-created paths- for exact_lock_path in self._get_exact_lock_paths(path):- if exact_lock_path == own_lock_path:- continue- exact_token = self._read_token(exact_lock_path)- if exact_token is not None:- if not (ignore_stale and self.is_lock_stale(exact_lock_path, self._lock_expire)):- return True-- # 3. Ancestor TREE locks- parent = self._get_parent_path(path)- while parent:- ancestor_lock = self._get_lock_path(parent)- ancestor_token = self._read_token(ancestor_lock)- if ancestor_token is not None:- _, _, lock_type = _parse_fencing_token(ancestor_token)- if lock_type == LOCK_TYPE_TREE and not (- ignore_stale and self.is_lock_stale(ancestor_lock, self._lock_expire)- ):- return True- parent = self._get_parent_path(parent)-- return False-- async def is_locked_async(self, path: str, ignore_stale: bool = True) -> bool:- """Async variant of is_locked for request/background paths."""- own_lock_path = self._get_lock_path(path)- token = await self._read_token_async(own_lock_path)- if token is not None:- if not (- ignore_stale and await self._is_lock_stale_async(own_lock_path, self._lock_expire)- ):- return True-- for exact_lock_path in await self._get_exact_lock_paths_async(path):- if exact_lock_path == own_lock_path:- continue- exact_token = await self._read_token_async(exact_lock_path)- if exact_token is not None:- if not (- ignore_stale- and await self._is_lock_stale_async(exact_lock_path, self._lock_expire)- ):- return True-- parent = self._get_parent_path(path)- while parent:- ancestor_lock = self._get_lock_path(parent)- ancestor_token = await self._read_token_async(ancestor_lock)- if ancestor_token is not None:- _, _, lock_type = _parse_fencing_token(ancestor_token)- if lock_type == LOCK_TYPE_TREE and not (- ignore_stale- and await self._is_lock_stale_async(ancestor_lock, self._lock_expire)- ):- return True- parent = self._get_parent_path(parent)-- return False-- def collect_lost_owner_locks(self, owner: LockOwner) -> list[str]:- lost_paths: list[str] = []- for lock_path in list(owner.locks):- if not self.is_lock_owned_by(lock_path, owner.id):- lost_paths.append(lock_path)- return lost_paths-- async def collect_lost_owner_locks_async(self, owner: LockOwner) -> list[str]:- lost_paths: list[str] = []- for lock_path in list(owner.locks):- if not await self._is_lock_owned_by_async(lock_path, owner.id):- lost_paths.append(lock_path)- return lost_paths-- async def _is_locked_by_other(self, lock_path: str, owner_id: str) -> bool:- token = await self._read_token_async(lock_path)- if token is None:- return False- lock_owner, _, _ = _parse_fencing_token(token)- return lock_owner != owner_id-- async def _create_lock_file(- self, lock_path: str, owner_id: str, lock_type: str = LOCK_TYPE_EXACT- ) -> None:- token = _make_fencing_token(owner_id, lock_type)- await self._async_agfs.write(lock_path, token.encode("utf-8"))-- async def _owned_lock_type(self, path: str, owner: LockOwner) -> Optional[str]:- lock_path = self._get_lock_path(path)- return await self._owned_lock_type_for_lock_path(lock_path, owner)-- async def _owned_lock_type_for_lock_path(- self, lock_path: str, owner: LockOwner- ) -> Optional[str]:- if lock_path not in owner.locks:- return None- token = await self._read_token_async(lock_path)- if token is None:- return None- lock_owner, _, lock_type = _parse_fencing_token(token)- if lock_owner != owner.id:- return None- return lock_type-- async def _has_owned_ancestor_tree(self, path: str, owner: LockOwner) -> bool:- current = path.rstrip("/")- while current:- if await self._owned_lock_type(current, owner) == LOCK_TYPE_TREE:- return True- current = self._get_parent_path(current) or ""- return False-- async def _remove_lock_file(self, lock_path: str) -> bool:- try:- await self._async_agfs.rm(lock_path)- return True- except Exception as e:- if "not found" in str(e).lower():- return True- return False-- def is_lock_stale(self, lock_path: str, expire_seconds: float = 300.0) -> bool:- token = self._read_token(lock_path)- if token is None:- return True- _, ts, _ = _parse_fencing_token(token)- if ts == 0:- return True- age = (time.time_ns() - ts) / 1e9- return age > expire_seconds-- async def _is_lock_stale_async(self, lock_path: str, expire_seconds: float = 300.0) -> bool:- token = await self._read_token_async(lock_path)- if token is None:- return True- _, ts, _ = _parse_fencing_token(token)- if ts == 0:- return True- age = (time.time_ns() - ts) / 1e9- return age > expire_seconds-- async def _check_ancestors_for_tree(self, path: str, exclude_owner_id: str) -> Optional[str]:- parent = self._get_parent_path(path)- while parent:- lock_path = self._get_lock_path(parent)- token = await self._read_token_async(lock_path)- if token is not None:- owner_id, _, lock_type = _parse_fencing_token(token)- if owner_id != exclude_owner_id and lock_type == LOCK_TYPE_TREE:- return lock_path- parent = self._get_parent_path(parent)- return None-- async def _check_path_lock(self, path: str, exclude_owner_id: str) -> Optional[str]:- lock_path = self._get_lock_path(path)- token = await self._read_token_async(lock_path)- if token is None:- return None- owner_id, _, _ = _parse_fencing_token(token)- if owner_id != exclude_owner_id:- return lock_path- return None-- async def _check_exact_path_lock(self, path: str, exclude_owner_id: str) -> Optional[str]:- for lock_path in await self._get_exact_lock_paths_async(path):- token = await self._read_token_async(lock_path)- if token is None:- continue- owner_id, _, _ = _parse_fencing_token(token)- if owner_id != exclude_owner_id:- return lock_path- return None-- async def _scan_descendants_for_locks(self, path: str, exclude_owner_id: str) -> Optional[str]:- try:- try:- stat = await self._async_agfs.stat(path)- except Exception:- return None- if isinstance(stat, dict) and not stat.get("isDir", False):- return None- if not isinstance(stat, dict) and getattr(stat, "isDir", None) is not True:- return None- entries = await self._async_agfs.ls(path)- if not isinstance(entries, list):- return None- for entry in entries:- if not isinstance(entry, dict):- continue- name = entry.get("name", "")- if not name or name in (".", ".."):- continue- entry_path = f"{path.rstrip('/')}/{name}"- if name.startswith(EXACT_LOCK_FILE_PREFIX):- token = await self._read_token_async(entry_path)- if token is not None:- owner_id, _, _ = _parse_fencing_token(token)- if owner_id != exclude_owner_id:- return entry_path- continue- if not entry.get("isDir", False):- continue- subdir = entry_path- subdir_lock = self._get_lock_path(subdir)- token = await self._read_token_async(subdir_lock)- if token is not None:- owner_id, _, _ = _parse_fencing_token(token)- if owner_id != exclude_owner_id:- return subdir_lock- result = await self._scan_descendants_for_locks(subdir, exclude_owner_id)- if result:- return result- except Exception as e:- logger.warning(f"Failed to scan descendants of {path}: {e}")- return None-- async def acquire_exact_path(- self, path: str, owner: LockOwner, timeout: Optional[float] = 0.0- ) -> bool:- """Acquire a short lock for one exact path.-- It conflicts with:- - another ExactPathLock on the same path;- - any ancestor TREE lock;- - a TREE lock on the exact same path.-- It does not conflict with sibling exact paths.- """- owner_id = owner.id- lock_path = await self._get_exact_lock_path_async(path)- if lock_path in owner.locks and await self._is_lock_owned_by_async(lock_path, owner_id):- owner.add_lock(lock_path)- logger.debug(f"[EXACT] Reusing owned exact lock on: {path}")- return True- if await self._has_owned_ancestor_tree(path, owner):- logger.debug(f"[EXACT] Reusing owned ancestor TREE lock on: {path}")- return True- had_no_timeout = timeout is None- if had_no_timeout:- timeout = self._lock_expire- deadline = asyncio.get_running_loop().time() + timeout- wait_start = asyncio.get_running_loop().time()- next_wait_log_at = wait_start + _WAIT_LOG_INTERVAL-- while True:- existing_exact_lock = await self._check_exact_path_lock(path, owner_id)- if existing_exact_lock:- if await self._is_lock_stale_async(existing_exact_lock, self._lock_expire):- logger.warning(f"[EXACT] Removing stale exact lock: {existing_exact_lock}")- await self._remove_lock_file(existing_exact_lock)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(f"[EXACT] Timeout waiting for exact lock on: {path}")- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[EXACT] Still waiting for lock on: {path} "- f"(waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- same_path_lock = self._get_lock_path(path)- if same_path_lock != lock_path:- token = await self._read_token_async(same_path_lock)- if token is not None:- lock_owner, _, _ = _parse_fencing_token(token)- if lock_owner != owner_id:- if await self._is_lock_stale_async(same_path_lock, self._lock_expire):- logger.warning(f"[EXACT] Removing stale lock: {same_path_lock}")- await self._remove_lock_file(same_path_lock)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(f"[EXACT] Timeout waiting for lock: {path}")- return False- await asyncio.sleep(_POLL_INTERVAL)- continue-- ancestor_conflict = await self._check_ancestors_for_tree(path, owner_id)- if ancestor_conflict:- if await self._is_lock_stale_async(ancestor_conflict, self._lock_expire):- logger.warning(- f"[EXACT] Removing stale ancestor TREE lock: {ancestor_conflict}"- )- await self._remove_lock_file(ancestor_conflict)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(- f"[EXACT] Timeout waiting for ancestor TREE lock: {ancestor_conflict}"- )- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[EXACT] Still waiting for ancestor TREE lock: {ancestor_conflict} "- f"(path={path}, waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- parent = self._get_parent_path(path)- if (- lock_path != self._get_lock_path(path)- and parent- and not await self._ensure_directory_exists_async(parent)- ):- logger.warning(f"[EXACT] Failed to ensure parent directory exists: {parent}")- return False-- try:- await self._create_lock_file(lock_path, owner_id, LOCK_TYPE_EXACT)- except Exception as e:- logger.error(f"[EXACT] Failed to create lock file: {e}")- return False-- if not await self._is_lock_owned_by_async(lock_path, owner_id):- logger.debug(f"[EXACT] Lost lock write race on: {path}")- if asyncio.get_running_loop().time() >= deadline:- return False- await asyncio.sleep(_POLL_INTERVAL)- continue-- conflict_after = await self._check_path_lock(path, owner_id)- if conflict_after == lock_path:- conflict_after = None- if not conflict_after:- conflict_after = await self._check_ancestors_for_tree(path, owner_id)- if conflict_after:- their_token = await self._read_token_async(conflict_after)- if their_token:- their_owner_id, their_ts, _ = _parse_fencing_token(their_token)- my_token = await self._read_token_async(lock_path)- _, my_ts, _ = (- _parse_fencing_token(my_token) if my_token else ("", 0, LOCK_TYPE_EXACT)- )- if (my_ts, owner_id) > (their_ts, their_owner_id):- logger.debug(f"[EXACT] Backing off (livelock guard) on {path}")- if await self._is_lock_owned_by_async(lock_path, owner_id):- await self._remove_lock_file(lock_path)- if asyncio.get_running_loop().time() >= deadline:- if await self._is_lock_owned_by_async(lock_path, owner_id):- await self._remove_lock_file(lock_path)- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[EXACT] Still waiting after conflict check on: {path} "- f"(waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- if not await self._is_lock_owned_by_async(lock_path, owner_id):- logger.debug(f"[EXACT] Lock ownership verification failed: {path}")- if asyncio.get_running_loop().time() >= deadline:- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[EXACT] Still waiting for lock ownership verification: {path} "- f"(waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- owner.add_lock(lock_path)- logger.debug(f"[EXACT] Lock acquired: {lock_path}")- return True-- async def acquire_tree(- self, path: str, owner: LockOwner, timeout: Optional[float] = 0.0- ) -> bool:- owner_id = owner.id- default_lock_path = self._get_lock_path(path)- lock_path = await self._get_exact_lock_path_async(path)- if lock_path != default_lock_path and not await self._is_existing_path_async(path):- lock_path = default_lock_path-- owned_lock_type = await self._owned_lock_type_for_lock_path(lock_path, owner)- if owned_lock_type == LOCK_TYPE_TREE:- owner.add_lock(lock_path)- logger.debug(f"[TREE] Reusing owned TREE lock on: {path}")- return True- if await self._has_owned_ancestor_tree(path, owner):- logger.debug(f"[TREE] Reusing owned ancestor TREE lock on: {path}")- return True- had_no_timeout = timeout is None- if had_no_timeout:- timeout = self._lock_expire- deadline = asyncio.get_running_loop().time() + timeout- wait_start = asyncio.get_running_loop().time()- next_wait_log_at = wait_start + _WAIT_LOG_INTERVAL-- while True:- if await self._is_locked_by_other(lock_path, owner_id):- if await self._is_lock_stale_async(lock_path, self._lock_expire):- logger.warning(f"[TREE] Removing stale lock: {lock_path}")- await self._remove_lock_file(lock_path)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(f"[TREE] Timeout waiting for lock on: {path}")- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[TREE] Still waiting for lock on: {path} (waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- # Check ancestor paths for TREE locks held by other owners- ancestor_conflict = await self._check_ancestors_for_tree(path, owner_id)- if ancestor_conflict:- if await self._is_lock_stale_async(ancestor_conflict, self._lock_expire):- logger.warning(f"[TREE] Removing stale ancestor TREE lock: {ancestor_conflict}")- await self._remove_lock_file(ancestor_conflict)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(- f"[TREE] Timeout waiting for ancestor TREE lock: {ancestor_conflict}"- )- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[TREE] Still waiting for ancestor TREE lock: {ancestor_conflict} "- f"(path={path}, waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- exact_conflict = await self._check_exact_path_lock(path, owner_id)- if exact_conflict:- if await self._is_lock_stale_async(exact_conflict, self._lock_expire):- logger.warning(f"[TREE] Removing stale exact lock: {exact_conflict}")- await self._remove_lock_file(exact_conflict)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(f"[TREE] Timeout waiting for exact lock: {exact_conflict}")- return False- await asyncio.sleep(_POLL_INTERVAL)- continue-- desc_conflict = await self._scan_descendants_for_locks(path, owner_id)- if desc_conflict:- if await self._is_lock_stale_async(desc_conflict, self._lock_expire):- logger.warning(f"[TREE] Removing stale descendant lock: {desc_conflict}")- await self._remove_lock_file(desc_conflict)- continue- if asyncio.get_running_loop().time() >= deadline:- _log_timeout_waiting(- f"[TREE] Timeout waiting for descendant lock: {desc_conflict}"- )- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[TREE] Still waiting for descendant lock: {desc_conflict} "- f"(path={path}, waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- if not await self._ensure_directory_exists_async(path):- logger.warning(f"[TREE] Failed to ensure directory exists: {path}")- return False-- try:- await self._create_lock_file(lock_path, owner_id, LOCK_TYPE_TREE)- except Exception as e:- logger.error(f"[TREE] Failed to create lock file: {e}")- return False-- backed_off = False- conflict_after = await self._scan_descendants_for_locks(path, owner_id)- if not conflict_after:- conflict_after = await self._check_exact_path_lock(path, owner_id)- if not conflict_after:- conflict_after = await self._check_ancestors_for_tree(path, owner_id)- if conflict_after:- their_token = await self._read_token_async(conflict_after)- if their_token:- their_owner_id, their_ts, _ = _parse_fencing_token(their_token)- my_token = await self._read_token_async(lock_path)- _, my_ts, _ = (- _parse_fencing_token(my_token) if my_token else ("", 0, LOCK_TYPE_TREE)- )- if (my_ts, owner_id) > (their_ts, their_owner_id):- logger.debug(f"[TREE] Backing off (livelock guard) on {path}")- await self._remove_lock_file(lock_path)- backed_off = True- if asyncio.get_running_loop().time() >= deadline:- if not backed_off:- await self._remove_lock_file(lock_path)- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[TREE] Still waiting after conflict check on: {path} "- f"(waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- if not await self._is_lock_owned_by_async(lock_path, owner_id):- logger.debug(f"[TREE] Lock ownership verification failed: {path}")- if asyncio.get_running_loop().time() >= deadline:- return False- now = asyncio.get_running_loop().time()- if had_no_timeout and now >= next_wait_log_at:- logger.info(- f"[TREE] Still waiting for lock ownership verification: {path} "- f"(waited={now - wait_start:.1f}s)"- )- next_wait_log_at = now + _WAIT_LOG_INTERVAL- await asyncio.sleep(_POLL_INTERVAL)- continue-- owner.add_lock(lock_path)- logger.debug(f"[TREE] Lock acquired: {lock_path}")- return True-- async def acquire_mv(- self,- src_path: str,- dst_path: str,- owner: LockOwner,- timeout: Optional[float] = 0.0,- src_is_dir: bool = True,- ) -> bool:- """Acquire locks for a move operation.-- Args:- src_path: Source path to lock.- dst_path: Destination path to lock.- owner: Lock owner handle.- timeout: Maximum seconds to wait for each lock.- src_is_dir: Whether the source is a directory (TREE lock)- or a file (ExactPathLock on source and destination path).- """- if src_is_dir:- if not await self.acquire_tree(src_path, owner, timeout=timeout):- logger.warning(f"[MV] Failed to acquire TREE lock on source: {src_path}")- return False- if not await self.acquire_exact_path(dst_path, owner, timeout=timeout):- logger.warning(f"[MV] Failed to acquire exact lock on destination: {dst_path}")- await self.release(owner)- return False- else:- if not await self.acquire_exact_path(src_path, owner, timeout=timeout):- logger.warning(f"[MV] Failed to acquire exact lock on source: {src_path}")- return False- if not await self.acquire_exact_path(dst_path, owner, timeout=timeout):- logger.warning(f"[MV] Failed to acquire exact lock on destination: {dst_path}")- await self.release(owner)- return False-- logger.debug(f"[MV] Locks acquired: {src_path} -> {dst_path}")- return True-- async def refresh(self, owner: LockOwner) -> LockRefreshResult:- """Rewrite all lock file timestamps to prevent stale cleanup."""- result = LockRefreshResult()- for lock_path in list(owner.locks):- parsed_owner_id, lock_type = await self._read_owner_and_type_async(lock_path)- if parsed_owner_id != owner.id or lock_type is None:- result.lost_paths.append(lock_path)- continue- new_token = _make_fencing_token(owner.id, lock_type)- try:- await self._async_agfs.write(lock_path, new_token.encode("utf-8"))- result.refreshed_paths.append(lock_path)- except Exception as e:- logger.warning(f"Failed to refresh lock {lock_path}: {e}")- result.failed_paths.append(lock_path)- return result-- async def release(self, owner: LockOwner) -> None:- lock_count = len(owner.locks)- released_count = 0- for lock_path in reversed(list(owner.locks)):- if await self._is_lock_owned_by_async(lock_path, owner.id):- await self._remove_lock_file(lock_path)- released_count += 1- owner.remove_lock(lock_path)-- logger.debug(f"Released {released_count}/{lock_count} locks for owner {owner.id}")-- async def release_selected(self, owner: LockOwner, lock_paths: list[str]) -> None:- for lock_path in reversed(lock_paths):- if lock_path not in owner.locks:- continue- if await self._is_lock_owned_by_async(lock_path, owner.id):- await self._remove_lock_file(lock_path)- owner.remove_lock(lock_path)diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex e9ebfdaf7..bf4bdc669 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -22,7 +22,7 @@ import timefrom contextlib import contextmanagerfrom dataclasses import dataclass, fieldfrom datetime import datetime, timezone-from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, TypeVar, Union+from typing import TYPE_CHECKING, Any, Dict, List, Optional, TypeVar, Unionfrom openviking.core.context import ContextLevelfrom openviking.core.namespace import (@@ -49,10 +49,7 @@ from openviking.resource.watch_storage import is_watch_task_control_urifrom openviking.server.error_mapping import is_not_found_error, map_exceptionfrom openviking.server.identity import RequestContext, Rolefrom openviking.storage.expr import And, PathScope, RawDSL-from openviking.storage.internal_names import (- MULTIWRITE_PATH_LOCK_FILE,- STORAGE_INTERNAL_ENTRY_NAMES,-)+from openviking.storage.internal_names import STORAGE_INTERNAL_ENTRY_NAMESfrom openviking.telemetry import get_current_telemetryfrom openviking.utils.image_search import build_multimodal_embedding_inputfrom openviking.utils.time_utils import format_iso8601, get_current_timestamp, parse_iso_datetime@@ -69,7 +66,6 @@ from openviking_cli.utils.logger import get_loggerfrom openviking_cli.utils.uri import VikingURIif TYPE_CHECKING:- from openviking.storage.transaction.lock_handle import LockHandlefrom openviking.storage.viking_vector_index_backend import VikingVectorIndexBackendfrom openviking_cli.utils.config import GrepConfig, RerankConfig, RetrievalConfig@@ -423,38 +419,6 @@ class VikingFS:digest = hashlib.sha256(relative_path.encode("utf-8")).hexdigest()return f"{mount_prefix}{temp_root}/{digest}.encrypt"- def _encrypted_write_lock_paths(self, path: str) -> List[str]:- """Return the final and temp paths protected by the encrypted write protocol."""- return [path, self._encrypted_temp_path(path)]-- async def _run_with_encrypted_write_lock(- self,- path: str,- operation: Callable[[], Awaitable[_T]],- lock_handle: Optional["LockHandle"] = None,- ) -> _T:- """Run a write operation under a dual-path exact lock when encryption is enabled."""- if self._encryptor is None:- return await operation()-- from openviking.storage.transaction import LockContext, get_lock_manager-- async with LockContext(- get_lock_manager(),- self._encrypted_write_lock_paths(path),- lock_mode="exact",- # Encrypted writes lock both the final path and the deterministic- # staging path under `.encrypt_stage`. Keeping the global default- # timeout at 0 is still desirable for ordinary path locks, but- # this specific dual-path write is much more exposed to short-lived- # contention between concurrent writers. A small 1-second wait here- # lets us ride out transient conflicts without broadening lock- # behavior for unrelated call sites.- timeout=1.0,- handle=lock_handle,- ):- return await operation()-def _ensure_access(self, uri: str, ctx: Optional[RequestContext]) -> None:real_ctx = self._ctx_or_default(ctx)normalized_uri, _ = self._normalized_uri_parts(uri)@@ -595,20 +559,39 @@ class VikingFS:# Encryption (when configured) happens inside the ragfs layer keyed by account_id.return await self._async_agfs.write(path, data)+ def _pathlock_fs_ctx(+ self,+ ctx: Optional[RequestContext],+ lease_ref: Optional[Dict[str, Any] | str],+ ) -> Dict[str, str] | None:+ """Build an AGFS fs_ctx carrying account_id and an opaque pathlock lease_ref."""+ if lease_ref is None:+ return None+ if isinstance(lease_ref, str):+ ref = lease_ref+ elif isinstance(lease_ref, dict):+ ref = lease_ref.get("lease_ref")+ else:+ raise ValueError("lease_ref must be a non-empty string or lease dictionary")+ if not isinstance(ref, str) or not ref:+ raise ValueError("lease_ref must contain a non-empty lease_ref")+ return {"account_id": self._ctx_or_default(ctx).account_id, "lease_ref": ref}+async def mkdir(self,uri: str,mode: str = "755",exist_ok: bool = False,ctx: Optional[RequestContext] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:"""Create directory."""self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)# Always ensure parent directories exist before creating this directory- await self._ensure_parent_dirs(path, ctx=ctx)+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)try:- await self._async_agfs.mkdir(path)+ await self._async_agfs.mkdir(path, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))except Exception as exc:message = str(exc).lower()already_exists = "exist" in message or "already" in message@@ -620,7 +603,7 @@ class VikingFS:uri: str,recursive: bool = False,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> Dict[str, Any]:"""Delete file/directory + recursively update vector index.@@ -636,7 +619,6 @@ class VikingFS:of nodes deleted from vector index."""from openviking.storage.errors import LockAcquisitionError, ResourceBusyError- from openviking.storage.transaction import LockContext, get_lock_managerself._ensure_delete_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)@@ -682,61 +664,62 @@ class VikingFS:f"Cannot remove directory without --recursive: {uri}",details={"resource": uri, "expected_flag": "recursive"},)- lock_paths = [path]- lock_mode = "tree"+ lock_method = self._async_agfs.pathlock_acquire_treeelse:- lock_paths = [path]- lock_mode = "exact"+ lock_method = self._async_agfs.pathlock_acquire_exact++ lease = lease_ref+ if lease is None:+ try:+ lease = await lock_method(path)+ except LockAcquisitionError:+ raise ResourceBusyError(f"Resource is being processed: {uri}", uri=uri)try:- async with LockContext(- get_lock_manager(),- lock_paths,- lock_mode=lock_mode,- handle=lock_handle,- ):- uris_to_delete = (- await self._collect_uris(path, recursive, ctx=ctx) if is_dir else []+ uris_to_delete = await self._collect_uris(path, recursive, ctx=ctx) if is_dir else []+ uris_to_delete.append(target_uri)+ real_ctx = self._ctx_or_default(ctx)+ estimated_count = await _estimate_deleted_count(path, real_ctx)+ await self._delete_from_vector_store(uris_to_delete, ctx=ctx)+ try:+ result = await self._async_agfs.rm(+ path,+ recursive=recursive,+ fs_ctx=self._pathlock_fs_ctx(ctx, lease),)- uris_to_delete.append(target_uri)- real_ctx = self._ctx_or_default(ctx)- estimated_count = await _estimate_deleted_count(path, real_ctx)- await self._delete_from_vector_store(uris_to_delete, ctx=ctx)- try:- result = await self._async_agfs.rm(path, recursive=recursive)- except AGFSDirectoryNotEmptyError:+ except AGFSDirectoryNotEmptyError:+ raise FailedPreconditionError(+ f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."+ )+ except RuntimeError as e:+ # Fallback for older versions without typed exceptions+ if _is_directory_not_empty_error(str(e)):raise FailedPreconditionError(f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories.")- except RuntimeError as e:- # Fallback for older versions without typed exceptions- if _is_directory_not_empty_error(str(e)):- raise FailedPreconditionError(- f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."- )- raise- # Add estimated_deleted_count to the result- if isinstance(result, dict):- result["estimated_deleted_count"] = estimated_count- else:- result = {"estimated_deleted_count": estimated_count}- return result- except LockAcquisitionError:- raise ResourceBusyError(f"Resource is being processed: {uri}", uri=uri)+ raise+ # Add estimated_deleted_count to the result+ if isinstance(result, dict):+ result["estimated_deleted_count"] = estimated_count+ else:+ result = {"estimated_deleted_count": estimated_count}+ return result+ finally:+ if lease_ref is None:+ await self._async_agfs.pathlock_release(lease)async def mv(self,old_uri: str,new_uri: str,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> Dict[str, Any]:- """Move file/directory + recursively update vector index.+ """Move file/directory while extending an optional outer pathlock lease.Implemented as cp + rm to avoid lock files being carried by FS mv.On VectorDB update failure the copy is cleaned up so the source stays intact."""- from openviking.storage.transaction import LockContext, get_lock_managerself._ensure_mutable_access(old_uri, ctx)# mv is implemented as copy + recursive rm of the source (see the@@ -787,25 +770,24 @@ class VikingFS:old_uri = canonicalize_uri(old_uri, real_ctx)new_uri = canonicalize_uri(new_uri, real_ctx)- lock_context = (- LockContext(- get_lock_manager(),- [old_path],- lock_mode="mv",- mv_dst_path=new_path,- src_is_dir=True,- handle=lock_handle,+ if is_dir:+ lease = await self._async_agfs.pathlock_acquire_batch(+ [+ {"path": old_path, "kind": "tree"},+ {"path": new_path, "kind": "exact"},+ ],+ owner_lease_ref=lease_ref,)- if is_dir- else LockContext(- get_lock_manager(),- [old_path, new_path],- lock_mode="exact",- handle=lock_handle,+ else:+ lease = await self._async_agfs.pathlock_acquire_batch(+ [+ {"path": old_path, "kind": "exact"},+ {"path": new_path, "kind": "exact"},+ ],+ owner_lease_ref=lease_ref,)- )- async with lock_context as active_lock_handle:+ try:uris_to_move = (await self._collect_uris(old_path, recursive=True, ctx=ctx) if is_dir else [])@@ -824,7 +806,7 @@ class VikingFS:is_dir=is_dir,is_temp=is_temp,ctx=ctx,- lock_handle=active_lock_handle,+ lease_ref=lease,)except Exception as e:if "not found" in str(e).lower():@@ -839,30 +821,42 @@ class VikingFS:)raise- # Remove carried lock file from the copy (directory only)- if is_dir:- carried_lock = new_path.rstrip("/") + f"/{MULTIWRITE_PATH_LOCK_FILE}"- try:- await self._async_agfs.rm(carried_lock)- except Exception:- pass-# Update VectorDB URIs (on failure, clean up the copy)try:await self._update_vector_store_uris(uris_to_move, old_uri, new_uri, ctx=ctx)except Exception:try:if is_dir:- await self._async_agfs.rm(new_path, recursive=True)+ cleanup_lease = await self._async_agfs.pathlock_acquire_tree(+ new_path,+ owner_lease_ref=lease,+ )+ try:+ await self._async_agfs.rm(+ new_path,+ recursive=True,+ fs_ctx=self._pathlock_fs_ctx(ctx, cleanup_lease),+ )+ finally:+ await self._async_agfs.pathlock_release(cleanup_lease)else:- await self._async_agfs.rm(new_path)+ await self._async_agfs.rm(+ new_path,+ fs_ctx=self._pathlock_fs_ctx(ctx, lease),+ )except Exception:passraise# Delete source- await self._async_agfs.rm(old_path, recursive=is_dir)+ await self._async_agfs.rm(+ old_path,+ recursive=is_dir,+ fs_ctx=self._pathlock_fs_ctx(ctx, lease),+ )return {}+ finally:+ await self._async_agfs.pathlock_release(lease)async def system_sync_status(self, uri: str, ctx: Optional[RequestContext] = None@@ -897,39 +891,91 @@ class VikingFS:is_dir: bool,is_temp: bool,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:"""Copy source to destination for mv without deleting source."""if is_temp:- await self._async_agfs.cp(- old_path,- new_path,- recursive=is_dir,- fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},- )+ if is_dir:+ await self._copy_temp_dir_with_exact_locks(+ old_path,+ new_path,+ ctx=ctx,+ lease_ref=lease_ref,+ )+ else:+ await self._async_agfs.cp(+ old_path,+ new_path,+ recursive=False,+ fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),+ )returnif is_dir:- await self._copy_dir_through_vikingfs(- old_uri, new_uri, ctx=ctx, lock_handle=lock_handle- )+ await self._copy_dir_through_vikingfs(old_uri, new_uri, ctx=ctx, lease_ref=lease_ref)else:- await self._copy_file_through_vikingfs(- old_uri,- new_uri,- ctx=ctx,- lock_handle=lock_handle,+ await self._copy_file_through_vikingfs(old_uri, new_uri, ctx=ctx, lease_ref=lease_ref)++ async def _copy_temp_dir_with_exact_locks(+ self,+ old_path: str,+ new_path: str,+ ctx: Optional[RequestContext],+ lease_ref: Dict[str, Any] | None,+ ) -> None:+ """Copy an encrypted temp directory while locking every destination entry.++ Args:+ old_path: Source backend directory path.+ new_path: Destination backend directory path.+ ctx: Request context used for filesystem operations.+ lease_ref: Exact lease covering the current destination directory.++ Returns:+ None.+ """+ if lease_ref is None:+ raise ValueError("temp directory copy requires a pathlock lease")+ fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)+ await self._async_agfs.mkdir(new_path, fs_ctx=fs_ctx)+ entries = await self._async_agfs.ls(old_path, fs_ctx=fs_ctx)+ for entry in entries:+ name = entry.get("name", "")+ if not name or name in (".", ".."):+ continue+ old_child = f"{old_path.rstrip('/')}/{name}"+ new_child = f"{new_path.rstrip('/')}/{name}"+ child_lease = await self._async_agfs.pathlock_acquire_exact(+ new_child,+ owner_lease_ref=lease_ref,)+ try:+ if entry.get("isDir", False):+ await self._copy_temp_dir_with_exact_locks(+ old_child,+ new_child,+ ctx=ctx,+ lease_ref=child_lease,+ )+ else:+ await self._async_agfs.cp(+ old_child,+ new_child,+ recursive=False,+ fs_ctx=self._pathlock_fs_ctx(ctx, child_lease),+ )+ finally:+ await self._async_agfs.pathlock_release(child_lease)async def _copy_dir_through_vikingfs(self,old_uri: str,new_uri: str,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:"""Recursively copy a directory through VikingFS read/write hooks."""- await self.mkdir(new_uri, exist_ok=True, ctx=ctx)+ await self.mkdir(new_uri, exist_ok=True, ctx=ctx, lease_ref=lease_ref)entries = await self.ls(old_uri, show_all_hidden=True, ctx=ctx)for entry in entries:@@ -943,14 +989,14 @@ class VikingFS:old_child_uri,new_child_uri,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)else:await self._copy_file_through_vikingfs(old_child_uri,new_child_uri,ctx=ctx,- lock_handle=lock_handle,+ lease_ref=lease_ref,)async def _copy_file_through_vikingfs(@@ -958,11 +1004,23 @@ class VikingFS:from_uri: str,to_uri: str,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:"""Copy one file through VikingFS read/write hooks without deleting source."""content_bytes = await self.read_file_bytes(from_uri, ctx=ctx)- await self.write_file_bytes(to_uri, content_bytes, ctx=ctx, lock_handle=lock_handle)+ if lease_ref is None:+ await self.write_file_bytes(to_uri, content_bytes, ctx=ctx)+ return++ child_path = self._uri_to_path(to_uri, ctx=ctx)+ child_lease = await self._async_agfs.pathlock_acquire_exact(+ child_path,+ owner_lease_ref=lease_ref,+ )+ try:+ await self.write_file_bytes(to_uri, content_bytes, ctx=ctx, lease_ref=child_lease)+ finally:+ await self._async_agfs.pathlock_release(child_lease)async def grep(self,@@ -1178,19 +1236,15 @@ class VikingFS:if exclude_uri:excluded_prefix = exclude_uri.rstrip("/")self._ensure_access(excluded_prefix, ctx)- filter_expr = And(- [- filter_expr,- RawDSL(- {- "op": "must_not",- "field": "uri",- "conds": [excluded_prefix],- "para": "-d=-1",- }- ),- ]- )+ filter_expr = And([+ filter_expr,+ RawDSL({+ "op": "must_not",+ "field": "uri",+ "conds": [excluded_prefix],+ "para": "-d=-1",+ }),+ ])# Auto-adapt bm25 recall limit: recall up to 5x requested matches# while capping at VikingDB's max limit. If node_limit is unset,@@ -1360,13 +1414,11 @@ class VikingFS:files_scanned_set.add(file_uri)- results.append(- {- "line": match.get("line", match.get("line_number", 0)),- "uri": file_uri,- "content": match.get("content", ""),- }- )+ results.append({+ "line": match.get("line", match.get("line_number", 0)),+ "uri": file_uri,+ "content": match.get("content", ""),+ })if node_limit and len(results) >= node_limit:break@@ -1536,13 +1588,11 @@ class VikingFS:lines = content.split("\n")for line_num, line in enumerate(lines, 1):if compiled_pattern.search(line):- matches.append(- {- "line": line_num,- "uri": entry_uri,- "content": line,- }- )+ matches.append({+ "line": line_num,+ "uri": entry_uri,+ "content": line,+ })return matches, 1except Exception as e:logger.debug(f"Failed to grep {entry_uri}: {e}")@@ -1565,7 +1615,7 @@ class VikingFS:Extra field:isLocked (bool): Whether the path is currently held by a path lock(either the path itself or any ancestor directory). Returns- False when the LockManager is not initialized or the lookup+ False when the pathlock system is not enabled or the lookupfails.count (int): For directories, the number of nodes in the vector indexunder this directory (including subdirectories). For files, this@@ -1628,11 +1678,9 @@ class VikingFS:return resultasync def _is_path_locked_async(self, path: str) -> bool:- """Best-effort async path-lock lookup; returns False when LockManager is absent."""+ """Best-effort async path-lock lookup; returns False on any error."""try:- from openviking.storage.transaction import get_lock_manager-- return await get_lock_manager().is_path_locked_async(path)+ return await self._async_agfs.pathlock_is_locked(path)except Exception:return False@@ -1827,17 +1875,15 @@ class VikingFS:):info = entry["info"]new_entry = dict(entry.get("extra", {}))- new_entry.update(- {- "name": info["name"],- "size": info["size"],- "mode": info["mode"],- "modTime": info["modTime"],- "isDir": info["isDir"],- "rel_path": entry["rel_path"],- "uri": entry_uri,- }- )+ new_entry.update({+ "name": info["name"],+ "size": info["size"],+ "mode": info["mode"],+ "modTime": info["modTime"],+ "isDir": info["isDir"],+ "rel_path": entry["rel_path"],+ "uri": entry_uri,+ })result.append(new_entry)return result@@ -1862,15 +1908,13 @@ class VikingFS:):info = entry["info"]is_dir = info["isDir"]- result.append(- {- "uri": entry_uri,- "size": 0 if is_dir else info["size"],- "isDir": is_dir,- "modTime": format_iso8601(parse_iso_datetime(info["modTime"])),- "rel_path": entry["rel_path"],- }- )+ result.append({+ "uri": entry_uri,+ "size": 0 if is_dir else info["size"],+ "isDir": is_dir,+ "modTime": format_iso8601(parse_iso_datetime(info["modTime"])),+ "rel_path": entry["rel_path"],+ })await self._batch_fetch_abstracts(result, abs_limit, ctx=ctx)@@ -3049,17 +3093,28 @@ class VikingFS:# ========== Parent Directory Creation ==========- async def _ensure_parent_dirs(self, path: str, ctx: Optional[RequestContext] = None) -> None:+ async def _ensure_parent_dirs(+ self,+ path: str,+ ctx: Optional[RequestContext] = None,+ lease_ref: Dict[str, Any] | None = None,+ ) -> None:"""Recursively create all parent directories."""try:- await self._async_agfs.ensure_parent_dirs(path)+ await self._async_agfs.ensure_parent_dirs(+ path,+ fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),+ )except Exception as e:logger.debug(f"Failed to ensure parent directories for {path}: {e}")parent = path.rstrip("/").rsplit("/", 1)[0]- await self._mkdir_path_with_parents(parent, ctx=ctx)+ await self._mkdir_path_with_parents(parent, ctx=ctx, lease_ref=lease_ref)async def _mkdir_path_with_parents(- self, dir_path: str, ctx: Optional[RequestContext] = None+ self,+ dir_path: str,+ ctx: Optional[RequestContext] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:"""Create a directory path segment-by-segment using the same fs context."""parts = [part for part in dir_path.strip("/").split("/") if part]@@ -3067,7 +3122,10 @@ class VikingFS:for part in parts:current = f"{current}/{part}"try:- await self._async_agfs.mkdir(current)+ await self._async_agfs.mkdir(+ current,+ fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),+ )except Exception as e:message = str(e).lower()if "exist" in message or "already" in message:@@ -3144,21 +3202,17 @@ class VikingFS:uri: str,content: Union[str, bytes],ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:- """Write file directly."""+ """Write file directly. Encryption lock handled internally by EncryptionWrappedFS."""self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- await self._ensure_parent_dirs(path, ctx=ctx)+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)if isinstance(content, str):content = content.encode("utf-8")- await self._run_with_encrypted_write_lock(- path,- lambda: self._async_agfs.write(path, content),- lock_handle=lock_handle,- )+ await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))async def read_file(self,@@ -3259,59 +3313,63 @@ class VikingFS:uri: str,content: bytes,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:- """Write single binary file."""+ """Write single binary file. Encryption lock handled internally by EncryptionWrappedFS."""self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- await self._ensure_parent_dirs(path, ctx=ctx)+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)- await self._run_with_encrypted_write_lock(- path,- lambda: self._async_agfs.write(path, content),- lock_handle=lock_handle,- )+ await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))async def append_file(self,uri: str,content: str,ctx: Optional[RequestContext] = None,- lock_handle: Optional["LockHandle"] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:- """Append content to file."""+ """Append content to file while holding one exact pathlock lease."""self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)+ owned_lease = Nonetry:- await self._ensure_parent_dirs(path, ctx=ctx)-- async def _append_under_lock() -> None:- """Read old content and rewrite the whole file under lock to avoid lost updates."""- existing = ""- try:- existing_bytes = self._handle_agfs_read(await self._async_agfs.read(path))- existing = self._decode_bytes(existing_bytes)- except FileNotFoundError:- pass- except AGFSHTTPError as e:- if e.status_code != 404:- raise- except AGFSClientError:+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)+ lease = lease_ref+ if lease is None:+ lease = await self._async_agfs.pathlock_acquire_exact(path)+ owned_lease = lease+ fs_ctx = self._pathlock_fs_ctx(ctx, lease)++ # Read old content and rewrite the whole file to avoid lost updates.+ existing = ""+ try:+ existing_bytes = self._handle_agfs_read(+ await self._async_agfs.read(path, fs_ctx=fs_ctx)+ )+ existing = self._decode_bytes(existing_bytes)+ except FileNotFoundError:+ pass+ except AGFSHTTPError as e:+ if e.status_code != 404:raise+ except AGFSClientError:+ raise- final_content = (existing + content).encode("utf-8")- await self._async_agfs.write(path, final_content)-- await self._run_with_encrypted_write_lock(+ final_content = (existing + content).encode("utf-8")+ await self._async_agfs.write(path,- _append_under_lock,- lock_handle=lock_handle,+ final_content,+ fs_ctx=fs_ctx,)except Exception as e:logger.error(f"[VikingFS] Failed to append to file {uri}: {e}")raise IOError(f"Failed to append to file {uri}: {e}")+ finally:+ if owned_lease is not None:+ await self._async_agfs.pathlock_release(owned_lease)async def ls(self,@@ -3544,24 +3602,32 @@ class VikingFS:temp_uri: str,target_uri: str,ctx: Optional[RequestContext] = None,+ lease_ref: Dict[str, Any] | None = None,) -> None:"""Persist an already-encrypted temp tree without rewriting file bytes."""self._ensure_access(temp_uri, ctx)self._ensure_mutable_access(target_uri, ctx)src_path = self._uri_to_path(temp_uri, ctx=ctx)dst_path = self._uri_to_path(target_uri, ctx=ctx)- await self._ensure_parent_dirs(dst_path, ctx=ctx)+ fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)+ await self._ensure_parent_dirs(dst_path, ctx=ctx, lease_ref=lease_ref)await self._async_agfs.cp(src_path,dst_path,recursive=True,- fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},+ fs_ctx=fs_ctx or {"account_id": self._ctx_or_default(ctx).account_id},)- async def delete_temp(self, temp_uri: str, ctx: Optional[RequestContext] = None) -> None:+ async def delete_temp(+ self,+ temp_uri: str,+ ctx: Optional[RequestContext] = None,+ lease_ref: Dict[str, Any] | None = None,+ ) -> None:"""Delete temp directory and its contents."""self._ensure_mutable_access(temp_uri, ctx)path = self._uri_to_path(temp_uri, ctx=ctx)+ fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)try:for entry in await self._ls_entries(path, ctx=ctx):name = entry.get("name", "")@@ -3569,10 +3635,10 @@ class VikingFS:continueentry_path = f"{path}/{name}"if entry.get("isDir"):- await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx)+ await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx, lease_ref=lease_ref)else:- await self._async_agfs.rm(entry_path)- await self._async_agfs.rm(path)+ await self._async_agfs.rm(entry_path, fs_ctx=fs_ctx)+ await self._async_agfs.rm(path, fs_ctx=fs_ctx)except Exception as e:logger.warning(f"[VikingFS] Failed to delete temp {temp_uri}: {e}")@@ -3665,16 +3731,14 @@ class VikingFS:# crates/ragfs/src/git/enumerate.rs and VikingFS._INTERNAL_NAMES so that# callers fail fast in Python with a clear error rather than passing a# path that the Rust side will silently drop.- _GIT_INTERNAL_FIRST_SEGMENTS = frozenset(- {- "_system",- "tasks",- "temp",- "queue",- "upload",- ".path.ovlock",- }- )+ _GIT_INTERNAL_FIRST_SEGMENTS = frozenset({+ "_system",+ "tasks",+ "temp",+ "queue",+ "upload",+ ".path.ovlock",+ })_DEFAULT_GIT_AUTHOR_NAME = "viking-bot"_DEFAULT_GIT_AUTHOR_EMAIL = "[email protected]"@@ -3951,7 +4015,6 @@ class VikingFS:from openviking.pyagfs.exceptions import GitRestoreWritebackPartialErrorfrom openviking.storage.errors import LockAcquisitionError, ResourceBusyError- from openviking.storage.transaction import LockContext, get_lock_manager# Serialize the writeback against concurrent VFS mutations on the same# subtree. A scoped restore tree-locks project_dir; a full restore@@ -3966,21 +4029,25 @@ class VikingFS:)partial_exc: Optional[GitRestoreWritebackPartialError] = Nonetry:- async with LockContext(get_lock_manager(), [lock_path], lock_mode="tree"):- try:- result = await self._async_agfs.run("git_restore", **kwargs)- except GitRestoreWritebackPartialError as exc:- # The ref already advanced — capture the exception and- # finish the lock scope cleanly. Reindex scheduling and- # re-raise happen below, outside the tree lock.- partial_exc = exc- result = None+ lease = await self._async_agfs.pathlock_acquire_tree(lock_path)except LockAcquisitionError:raise ResourceBusyError(f"Resource is being processed: {project_dir or '*'}",uri=project_dir or "*",)+ try:+ try:+ result = await self._async_agfs.run("git_restore", **kwargs)+ except GitRestoreWritebackPartialError as exc:+ # The ref already advanced — capture the exception and+ # finish the lock scope cleanly. Reindex scheduling and+ # re-raise happen below, outside the tree lock.+ partial_exc = exc+ result = None+ finally:+ await self._async_agfs.pathlock_release(lease)+if partial_exc is not None:# HEAD has moved forward but some VFS writes/deletes failed.# Still schedule reindex for the paths that *did* reach the VFS so@@ -4339,12 +4406,10 @@ class VikingFS:from openviking.service.reindex_executor import get_reindex_executorexecutor = get_reindex_executor()- await asyncio.gather(- *[- self._run_vector_rebuild(executor, op, uri, level, ctx)- for (op, uri, level) in tasks- ]- )+ await asyncio.gather(*[+ self._run_vector_rebuild(executor, op, uri, level, ctx)+ for (op, uri, level) in tasks+ ])await tracker.complete(task_id,{"status": "completed", "task_count": len(tasks)},diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.pyindex 0495f8961..7e36d243c 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -35,6 +35,7 @@ class RagfsBindingConfig:"""Convert the runtime config into the sectioned dict consumed by `RAGFSBindingClient`."""binding_config: Dict[str, Any] = {"cache": self.agfs.cache.model_dump(mode="json"),+ "pathlock": self.agfs.pathlock.model_dump(mode="json"),}if self.root_key is not None:diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.pyindex 553e42be7..3e3ccaba4 100644--- a/openviking/utils/resource_processor.py+++ b/openviking/utils/resource_processor.py@@ -28,12 +28,6 @@ from openviking.storage import VikingDBManagerfrom openviking.storage.errors import LockAcquisitionErrorfrom openviking.storage.expr import And, Eq, PathScopefrom openviking.storage.internal_names import STORAGE_INTERNAL_ENTRY_NAMES-from openviking.storage.transaction import (- LOCK_TIMEOUT_DEFAULT,- NO_LOCK,- LockLease,- OwnedLockLease,-)from openviking.storage.queuefs.semantic_processor import SemanticProcessorfrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry import get_current_telemetry@@ -188,7 +182,7 @@ class ResourceProcessor:"source_path": None,}defer_post_processing = bool(kwargs.pop("defer_post_processing", False))- preacquired_lock = kwargs.pop("resource_lock", NO_LOCK) or NO_LOCK+ preacquired_lock = kwargs.pop("resource_lock", None)ingest_options = IngestOptions.from_value(kwargs.pop("ingest_options", None))telemetry = get_current_telemetry()@@ -331,20 +325,17 @@ class ResourceProcessor:temp_uri = result.get("temp_uri") # temp_doc_urioriginal_temp_uri = temp_uri # 保存原始 temp_uri 用于最终输出candidate_uri = getattr(context_tree, "_candidate_uri", None) if context_tree else None- resource_lock: LockLease = preacquired_lock+ resource_lock: Optional[Dict[str, Any]] = preacquired_locktarget_preexisting = Falsesource_committed = Falseif root_uri and temp_uri:- from openviking.storage.transaction import get_lock_manager-stage_start = time.perf_counter()stage_status = "ok"viking_fs = get_viking_fs()- lock_manager = get_lock_manager()try:if candidate_uri:- if resource_lock.active:+ if resource_lock is not None:root_uri = candidate_urielse:root_uri, resource_lock = await self.reserve_unique_candidate(@@ -379,17 +370,21 @@ class ResourceProcessor:target_preexisting = Falseexcept Exception:pass- if not resource_lock.active:+ if resource_lock is None:dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)- resource_lock = await self.acquire_resource_lock(- lock_manager, dst_path, uri=root_uri- )+ resource_lock = await self.acquire_resource_lock(dst_path, uri=root_uri)if not target_preexisting:- await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)- await rewrite_image_uris(- root_uri, ctx=ctx, lock_handle=resource_lock.handle+ await viking_fs.persist_temp_tree(+ temp_uri,+ root_uri,+ ctx=ctx,+ lease_ref=resource_lock,+ )+ await rewrite_image_uris(root_uri, ctx=ctx, lease_ref=resource_lock)+ await viking_fs.delete_temp(+ parse_result.temp_dir_path,+ ctx=ctx,)- await viking_fs.delete_temp(parse_result.temp_dir_path, ctx=ctx)temp_uri = root_urisource_committed = Trueexcept Exception:@@ -449,7 +444,7 @@ class ResourceProcessor:prepared: Dict[str, Any],*,ctx: RequestContext,- resource_lock: LockLease = NO_LOCK,+ resource_lock: Optional[Dict[str, Any]] = None,summarize: bool = False,processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,**kwargs: Any,@@ -486,12 +481,12 @@ class ResourceProcessor:**kwargs,)if (- resource_lock.active+ resource_lock is not Noneand summary_result.get("status") == "success"and summary_result.get("enqueued_count", 0) > 0):- await resource_lock.handoff()- resource_lock = NO_LOCK+ await get_viking_fs()._async_agfs.pathlock_handoff(resource_lock)+ resource_lock = Noneexcept Exception as exc:logger.error("Summarization failed: %s", exc)result["warnings"] = [f"Summarization failed: {exc}"]@@ -507,7 +502,7 @@ class ResourceProcessor:except Exception:pass- if resource_lock.active:+ if resource_lock is not None:try:sync_deleted_files: list[str] = []sync_deleted_dirs: list[str] = []@@ -523,11 +518,16 @@ class ResourceProcessor:sync_deleted_files = list(getattr(diff, "deleted_files", []))sync_deleted_dirs = list(getattr(diff, "deleted_dirs", []))else:- await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)+ await viking_fs.persist_temp_tree(+ temp_uri,+ root_uri,+ ctx=ctx,+ lease_ref=resource_lock,+ )await rewrite_image_uris(root_uri,ctx=ctx,- lock_handle=resource_lock.handle,+ lease_ref=resource_lock,)if temp_dir_path:await viking_fs.delete_temp(temp_dir_path, ctx=ctx)@@ -545,7 +545,7 @@ class ResourceProcessor:ingest_options=ingest_options,)finally:- await resource_lock.close()+ await get_viking_fs()._async_agfs.pathlock_release(resource_lock)elif vectors_only:if not build_index:return result@@ -575,13 +575,11 @@ class ResourceProcessor:await self.vikingdb.delete(ids, ctx=ctx)for uri in dict.fromkeys(dirs):records = await self.vikingdb.filter(- filter=And(- [- PathScope("uri", uri, depth=-1),- Eq("level", int(ContextLevel.DETAIL)),- Eq("account_id", ctx.account_id),- ]- ),+ filter=And([+ PathScope("uri", uri, depth=-1),+ Eq("level", int(ContextLevel.DETAIL)),+ Eq("account_id", ctx.account_id),+ ]),limit=VECTORDB_MAX_QUERY_LIMIT,output_fields=["id"],ctx=ctx,@@ -631,13 +629,11 @@ class ResourceProcessor:candidate_uri: str,ctx: RequestContext,max_attempts: int = 100,- ) -> tuple[str, OwnedLockLease]:+ ) -> tuple[str, Dict[str, Any]]:"""Pick the first free candidate URI and reserve it with a resource TreeLock."""from openviking.storage.errors import ResourceBusyError- from openviking.storage.transaction import get_lock_managerviking_fs = get_viking_fs()- lock_manager = get_lock_manager()last_busy_error: Optional[ResourceBusyError] = Nonefor attempt in range(max_attempts + 1):@@ -648,7 +644,7 @@ class ResourceProcessor:dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)try:resource_lock = await self.acquire_resource_lock(- lock_manager, dst_path, uri=root_uri, timeout=0.0+ dst_path, uri=root_uri, timeout=0.0)return root_uri, resource_lockexcept ResourceBusyError as exc:@@ -670,17 +666,18 @@ class ResourceProcessor:@staticmethodasync def acquire_resource_lock(- lock_manager,path: str,*,uri: str = "",- timeout: Any = LOCK_TIMEOUT_DEFAULT,- ) -> OwnedLockLease:+ timeout: float = 0.0,+ ) -> Dict[str, Any]:"""Acquire the per-resource TreeLock or raise a structured conflict."""from openviking.storage.errors import ResourceBusyErrortry:- return await OwnedLockLease.acquire_tree(lock_manager, path, timeout=timeout)+ return await get_viking_fs()._async_agfs.pathlock_acquire_tree(+ path, timeout_secs=timeout+ )except LockAcquisitionError as exc:logger.warning(f"[ResourceProcessor] Failed to acquire resource lock on {path}")raise ResourceBusyError(diff --git a/openviking/utils/summarizer.py b/openviking/utils/summarizer.pyindex 83f42092e..d7e519471 100644--- a/openviking/utils/summarizer.py+++ b/openviking/utils/summarizer.py@@ -10,7 +10,6 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuplefrom openviking.utils.ingest_options import IngestOptionsfrom openviking.core.namespace import context_type_for_urifrom openviking.storage.queuefs import SemanticMsg, get_queue_manager-from openviking.storage.transaction import NO_LOCK, LockLeasefrom openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fsfrom openviking.telemetry import get_current_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_tracker@@ -37,7 +36,7 @@ class Summarizer:resource_uris: List[str],ctx: "RequestContext",skip_vectorization: bool = False,- lock: LockLease = NO_LOCK,+ lock: Optional[Dict[str, Any]] = None,**kwargs,) -> Dict[str, Any]:"""@@ -62,7 +61,9 @@ class Summarizer:enqueued_count = 0telemetry = get_current_telemetry()- lock_handoff = lock.to_handoff()+ lock_handoff: Optional[Dict[str, Any]] = None+ if lock is not None:+ lock_handoff = await get_viking_fs()._async_agfs.pathlock_to_handoff(lock)target_preexisting_arg = kwargs.get("target_preexisting")def resolve_target_preexisting(index: int, target_uri: str) -> Optional[bool]:diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.pyindex 3f6a5b190..feed25756 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -315,6 +315,30 @@ class AGFSCacheConfig(BaseModel):return self+class AGFSPathLockConfig(BaseModel):+ """Configuration for the native RAGFS path lock service."""++ provider: str = Field(+ default="filesystem",+ description="PathLock provider: 'filesystem' | 'memory'",+ )+ lock_expire_secs: float = Field(+ default=300.0,+ description="Seconds before an unrefreshed lock token becomes stale.",+ )++ model_config = {"extra": "forbid"}++ @model_validator(mode="after")+ def validate_config(self):+ """Validate provider and stale-lock expiry."""+ if self.provider not in {"filesystem", "memory"}:+ raise ValueError("pathlock provider must be one of: 'filesystem', 'memory'")+ if self.lock_expire_secs < 1.0:+ raise ValueError("pathlock lock_expire_secs must be >= 1.0")+ return self++class AGFSConfig(BaseModel):"""Configuration for RAGFS (Rust-based AGFS)."""@@ -381,6 +405,11 @@ class AGFSConfig(BaseModel):description="RAGFS cache configuration.",)+ pathlock: AGFSPathLockConfig = Field(+ default_factory=AGFSPathLockConfig,+ description="Native RAGFS path lock configuration.",+ )+retry_times: Any = Field(default=None,exclude=True,diff --git a/tests/agfs/test_async_client.py b/tests/agfs/test_async_client.pyindex efcce6889..b5aa084e4 100644--- a/tests/agfs/test_async_client.py+++ b/tests/agfs/test_async_client.py@@ -8,15 +8,24 @@ from openviking.pyagfs import AsyncAGFSClientclass _SyncAGFS:+ """Minimal synchronous binding stub used by the async adapter tests."""+def read(self, path, **kwargs):+ """Return read call arguments."""return ("read", path, kwargs)def write(self, path, data, **kwargs):+ """Return write call arguments."""return ("write", path, data, kwargs)def rm(self, path, **kwargs):+ """Return remove call arguments."""return ("rm", path, kwargs)+ def pathlock_is_locked(self, ctx, path, ignore_stale):+ """Return pathlock query arguments."""+ return ("pathlock_is_locked", ctx, path, ignore_stale)+@pytest.mark.asyncioasync def test_async_agfs_client_hides_threadpool(monkeypatch):diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.pyindex 0f6c913c3..ef074e043 100644--- a/tests/agfs/test_fs_binding.py+++ b/tests/agfs/test_fs_binding.py@@ -13,7 +13,6 @@ import uuidimport pytest-from openviking.storage.transaction import init_lock_manager, reset_lock_managerfrom openviking.storage.viking_fs import init_viking_fsfrom openviking_cli.utils.config.agfs_config import AGFSConfig@@ -33,16 +32,12 @@ async def viking_fs_binding_instance():# Create AGFS clientagfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))- # Initialize LockManager and VikingFS with client- init_lock_manager(agfs=agfs_client)vfs = init_viking_fs(agfs=agfs_client)# make sure default/temp directory existsawait vfs.mkdir("viking://temp/", exist_ok=True)yield vfs- reset_lock_manager()-@pytest.mark.asyncioclass TestVikingFSBindingLocal:@@ -96,6 +91,78 @@ class TestVikingFSBindingLocal:root_entries = await vfs.ls("viking://temp/")assert not any(e["name"] == test_dir for e in root_entries)+ async def test_borrowed_pathlock_cannot_release_via_raw_ref(self, viking_fs_binding_instance):+ """Reject borrowed lifecycle control through typed and raw lease refs."""+ vfs = viking_fs_binding_instance+ path = f"/local/default/temp/borrowed_release_{uuid.uuid4().hex}.txt"+ owned = await vfs._async_agfs.pathlock_acquire_exact(path)+ borrowed = await vfs._async_agfs.pathlock_as_borrowed(owned)++ try:+ with pytest.raises(ValueError):+ await vfs._async_agfs.pathlock_release(borrowed)+ with pytest.raises((TypeError, ValueError)):+ await vfs._async_agfs.pathlock_release(borrowed["lease_ref"])+ finally:+ await vfs._async_agfs.pathlock_release(owned)++ async def test_pathlock_adopt_rejects_forged_tree_coverage(self, viking_fs_binding_instance):+ """Reject handoff coverage that is stronger than the live token."""+ vfs = viking_fs_binding_instance+ path = f"/local/default/temp/handoff_forge_{uuid.uuid4().hex}.txt"+ owned = await vfs._async_agfs.pathlock_acquire_exact(path)+ handoff = await vfs._async_agfs.pathlock_to_handoff(owned)+ handoff["covered_paths"] = [{"path": path, "kind": "tree"}]+ adopted = None++ try:+ with pytest.raises(ValueError):+ adopted = await vfs._async_agfs.pathlock_adopt(handoff)+ finally:+ if adopted is not None:+ await vfs._async_agfs.pathlock_release(adopted)+ await vfs._async_agfs.pathlock_release(owned)++ async def test_pathlock_adopt_accepts_legacy_handle_id_handoff(+ self, viking_fs_binding_instance+ ):+ """Accept legacy durable handoffs that use handle_id instead of owner_id."""+ vfs = viking_fs_binding_instance+ path = f"/local/default/temp/handoff_legacy_{uuid.uuid4().hex}.txt"+ owned = await vfs._async_agfs.pathlock_acquire_exact(path)+ handoff = await vfs._async_agfs.pathlock_to_handoff(owned)+ legacy_handoff = {+ "handle_id": handoff["owner_id"],+ "lock_paths": handoff["lock_paths"],+ }+ adopted = None++ try:+ adopted = await vfs._async_agfs.pathlock_adopt(legacy_handoff)+ assert adopted["owner_id"] == owned["owner_id"]+ assert adopted["owned"] is True+ finally:+ if adopted is not None:+ await vfs._async_agfs.pathlock_release(adopted)+ await vfs._async_agfs.pathlock_release(owned)++ @pytest.mark.parametrize(+ "requests",+ [+ [],+ [{"kind": "exact"}],+ [{"path": "", "kind": "exact"}],+ [{"path": "relative", "kind": "tree"}],+ [{"path": "/local/default/temp/file", "kind": "other"}],+ ],+ )+ async def test_pathlock_batch_rejects_invalid_requests(+ self, viking_fs_binding_instance, requests+ ):+ """Reject malformed pathlock requests without applying defaults."""+ with pytest.raises(ValueError):+ await viking_fs_binding_instance._async_agfs.pathlock_acquire_batch(requests)+async def test_tree_operations(self, viking_fs_binding_instance):"""Test VikingFS tree operations."""vfs = viking_fs_binding_instancediff --git a/tests/agfs/test_fs_binding_s3.py b/tests/agfs/test_fs_binding_s3.pyindex 0e0020bc0..af545efdf 100644--- a/tests/agfs/test_fs_binding_s3.py+++ b/tests/agfs/test_fs_binding_s3.py@@ -13,7 +13,6 @@ from pathlib import Pathimport pytest-from openviking.storage.transaction import init_lock_manager, reset_lock_managerfrom openviking.storage.viking_fs import init_viking_fsfrom openviking_cli.utils.config import OPENVIKING_CONFIG_ENVfrom openviking_cli.utils.config.agfs_config import AGFSConfig@@ -59,14 +58,10 @@ async def viking_fs_binding_s3_instance():# Create AGFS clientagfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))- # Initialize LockManager and VikingFS with client- init_lock_manager(agfs=agfs_client)vfs = init_viking_fs(agfs=agfs_client)yield vfs- reset_lock_manager()-@pytest.mark.asyncioclass TestVikingFSBindingS3:diff --git a/tests/agfs/test_viking_fs_git.py b/tests/agfs/test_viking_fs_git.pyindex c7609c00b..f1b489d92 100644--- a/tests/agfs/test_viking_fs_git.py+++ b/tests/agfs/test_viking_fs_git.py@@ -80,21 +80,16 @@ def workspace():@pytest.fixturedef vfs(workspace):- from openviking.storage.transaction import init_lock_manager, reset_lock_manager-cfg, fs_root = _write_workspace(workspace)client = _build_client(cfg, fs_root)- init_lock_manager(client)try:yield VikingFS(agfs=client)finally:- reset_lock_manager()+ pass@pytest.fixturedef vfs_disabled(workspace):- from openviking.storage.transaction import init_lock_manager, reset_lock_manager-cfg = workspace / "ragfs.toml"cfg.write_text("""@@ -106,11 +101,10 @@ enabled = falsefs_root.mkdir()client = ragfs_python.RAGFSBindingClient(git_config_path=str(cfg))client.mount("localfs", "/local", {"local_dir": str(fs_root)})- init_lock_manager(client)try:yield VikingFS(agfs=client)finally:- reset_lock_manager()+ pass# =========================================================================@@ -459,15 +453,12 @@ def encryptor(workspace):@pytest.fixturedef vfs_encrypted(workspace, encryptor):- from openviking.storage.transaction import init_lock_manager, reset_lock_manager-cfg, fs_root = _write_workspace(workspace)client = _build_client(cfg, fs_root)- init_lock_manager(client)try:yield VikingFS(agfs=client, encryptor=encryptor)finally:- reset_lock_manager()+ pass@pytest.mark.asynciodiff --git a/tests/client/test_file_operations.py b/tests/client/test_file_operations.pyindex 2df2a910c..6d2edb64c 100644--- a/tests/client/test_file_operations.py+++ b/tests/client/test_file_operations.py@@ -8,7 +8,6 @@ from pathlib import Pathimport pytestfrom openviking import AsyncOpenViking-from openviking.storage.transaction import release_all_locksclass TestRm:@@ -23,7 +22,6 @@ class TestRm:reason="Test rm",)- await release_all_locks()uris = await client.tree(result["root_uri"])for data in uris:if not data["isDir"]:@@ -37,8 +35,6 @@ class TestRm:for f in sample_directory.glob("**/*.txt"):await client.add_resource(path=str(f), reason="Test rm dir")- # Release resource locks held by add_resource before rm- await release_all_locks()entries = await client.ls("viking://resources/")for data in entries:if data["isDir"]:@@ -60,7 +56,6 @@ class TestMv:)uri = result["root_uri"]new_uri = "viking://resources/moved/"- await release_all_locks()await client.mv(uri, new_uri)# Verify original location does not existwith pytest.raises(Exception): # noqa: B017diff --git a/tests/client/test_git_versioning.py b/tests/client/test_git_versioning.pyindex 4fc8e43c3..4a8ba850e 100644--- a/tests/client/test_git_versioning.py+++ b/tests/client/test_git_versioning.py@@ -15,18 +15,18 @@ from unittest.mock import MagicMockimport pytest-ragfs_python = pytest.importorskip("ragfs_python")-from openviking.async_client import AsyncOpenVikingfrom openviking.client.local import LocalClientfrom openviking.pyagfs.exceptions import AGFSNotFoundError, AGFSNotSupportedErrorfrom openviking.server.identity import RequestContext, Role-from openviking_cli.exceptions import InvalidURIErrorfrom openviking.service.fs_service import FSServicefrom openviking.storage.viking_fs import VikingFSfrom openviking.sync_client import SyncOpenViking+from openviking_cli.exceptions import InvalidURIErrorfrom openviking_cli.session.user_id import UserIdentifier+ragfs_python = pytest.importorskip("ragfs_python")+OID_RE = re.compile(r"^[0-9a-f]{40}$")DEFAULT_AUTHOR_NAME = VikingFS._DEFAULT_GIT_AUTHOR_NAME@@ -86,11 +86,8 @@ def _build_binding_client(config_path: Path, fs_root: Path):def _build_harness(config_path: Path, fs_root: Path) -> ClientHarness:- from openviking.storage.transaction import init_lock_manager-ctx = _make_ctx()binding_client = _build_binding_client(config_path, fs_root)- init_lock_manager(binding_client)vfs = VikingFS(agfs=binding_client)fs_service = FSService()@@ -131,24 +128,20 @@ def workspace():@pytest.fixturedef git_harness(workspace) -> ClientHarness:- from openviking.storage.transaction import reset_lock_manager-cfg, fs_root = _write_workspace(workspace)try:yield _build_harness(cfg, fs_root)finally:- reset_lock_manager()+ pass@pytest.fixturedef git_disabled_harness(workspace) -> ClientHarness:- from openviking.storage.transaction import reset_lock_manager-cfg, fs_root = _write_disabled_workspace(workspace)try:yield _build_harness(cfg, fs_root)finally:- reset_lock_manager()+ passasync def test_write_commit_show_roundtrip(git_harness):@@ -165,10 +158,13 @@ async def test_write_commit_show_roundtrip(git_harness):assert commit["result"] == "created"assert OID_RE.match(commit["commit_oid"])- assert git_harness.client.snapshot.show(- "main",- path="viking://resources/a.md",- ) == b"hello"+ assert (+ git_harness.client.snapshot.show(+ "main",+ path="viking://resources/a.md",+ )+ == b"hello"+ )async def test_show_metadata_without_path(git_harness):@@ -284,10 +280,13 @@ async def test_restore_reverts_file_and_advances_head(git_harness):assert restore["source_commit"] == v1["commit_oid"]assert restore["parent_commit"] == v2["commit_oid"]assert restore["new_commit_oid"] != v2["commit_oid"]- assert await git_harness.vfs.read(- "viking://resources/proj/a.md",- ctx=git_harness.ctx,- ) == b"v1"+ assert (+ await git_harness.vfs.read(+ "viking://resources/proj/a.md",+ ctx=git_harness.ctx,+ )+ == b"v1"+ )assert git_harness.client.snapshot.show("main")["parents"] == [v2["commit_oid"]]@@ -320,10 +319,13 @@ async def test_restore_dry_run_does_not_mutate(git_harness):assert dry_run["result"] == "dry_run"assert any(item["path"] == "a.md" for item in dry_run["diff"]["to_write"])- assert await git_harness.vfs.read(- "viking://resources/proj/a.md",- ctx=git_harness.ctx,- ) == b"v2"+ assert (+ await git_harness.vfs.read(+ "viking://resources/proj/a.md",+ ctx=git_harness.ctx,+ )+ == b"v2"+ )assert len(git_harness.client.snapshot.log()) == len(before_log)@@ -398,19 +400,13 @@ async def test_snapshot_namespace_gitignore_roundtrip(git_harness):assert await client.snapshot.get_gitignore() == "*.log\n"# The rule must affect commits: a .log file is skipped, a .md file kept.- await git_harness.vfs.write_file(- "viking://resources/keep.md", b"keep", ctx=git_harness.ctx- )- await git_harness.vfs.write_file(- "viking://resources/skip.log", b"skip", ctx=git_harness.ctx- )+ await git_harness.vfs.write_file("viking://resources/keep.md", b"keep", ctx=git_harness.ctx)+ await git_harness.vfs.write_file("viking://resources/skip.log", b"skip", ctx=git_harness.ctx)commit = await client.snapshot.commit(message="with ignore")assert commit["result"] == "created"assert commit["ignored"] == 1- assert await client.snapshot.show(- "main", path="viking://resources/keep.md"- ) == b"keep"+ assert await client.snapshot.show("main", path="viking://resources/keep.md") == b"keep"with pytest.raises(AGFSNotFoundError):await client.snapshot.show("main", path="viking://resources/skip.log")diff --git a/tests/client/test_git_versioning_http.py b/tests/client/test_git_versioning_http.pyindex 3323645f7..fbc4bf30e 100644--- a/tests/client/test_git_versioning_http.py+++ b/tests/client/test_git_versioning_http.py@@ -24,19 +24,18 @@ import httpximport pytestimport pytest_asyncio-ragfs_python = pytest.importorskip("ragfs_python")-from openviking.models.embedder.base import DenseEmbedderBase, EmbedResultfrom openviking.server.app import create_appfrom openviking.server.config import ServerConfigfrom openviking.server.identity import RequestContext, Rolefrom openviking.service.core import OpenVikingService-from openviking.storage.transaction import reset_lock_managerfrom openviking_cli.client.http import AsyncHTTPClientfrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils.config.embedding_config import EmbeddingConfigfrom openviking_cli.utils.config.vlm_config import VLMConfig+pytest.importorskip("ragfs_python")+pytestmark = pytest.mark.asyncio@@ -86,7 +85,6 @@ def http_temp_dir():@pytest_asyncio.fixture(scope="function")async def http_service(http_temp_dir: Path, monkeypatch):"""Stand up a real OpenVikingService backed by a temp data dir."""- reset_lock_manager()fake_embedder_cls = _install_fake_embedder(monkeypatch)_install_fake_vlm(monkeypatch)@@ -107,7 +105,6 @@ async def http_service(http_temp_dir: Path, monkeypatch):yield svcfinally:await svc.close()- reset_lock_manager()@pytest_asyncio.fixture(scope="function")@@ -195,6 +192,7 @@ async def test_http_log_filters_repeated_paths_end_to_end(http_app, http_serviceheaders=_AUTH_HEADERS,timeout=30.0,) as client:+async def commit(uri: str, body: bytes, message: str) -> dict:await _write_blob(http_service, uri, body)response = await client.post(diff --git a/tests/client/test_import_export.py b/tests/client/test_import_export.pyindex ff8263f5f..5fd735617 100644--- a/tests/client/test_import_export.py+++ b/tests/client/test_import_export.py@@ -12,7 +12,6 @@ from pathlib import Pathimport pytestfrom openviking import AsyncOpenViking-from openviking.storage.transaction import release_all_locksclass TestExportOvpack:@@ -100,7 +99,6 @@ class TestImportOvpack:await client.export_ovpack(original_uri, str(export_path))# Delete original resource- await release_all_locks()await client.rm(original_uri, recursive=True)# Importdiff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.pyindex b14bd417b..285addf23 100644--- a/tests/integration/test_full_workflow.py+++ b/tests/integration/test_full_workflow.py@@ -10,7 +10,6 @@ import pytest_asynciofrom openviking import AsyncOpenVikingfrom openviking.message import TextPart-from openviking.storage.transaction import release_all_locks@pytest_asyncio.fixture(scope="function")@@ -176,7 +175,6 @@ class TestImportExportWorkflow:assert export_path.exists()# 4. Delete original resource- await release_all_locks()await client.rm(original_uri, recursive=True)# 5. Importdiff --git a/tests/metrics/collectors/test_state_collectors.py b/tests/metrics/collectors/test_state_collectors.pyindex 539a97499..9f8491245 100644--- a/tests/metrics/collectors/test_state_collectors.py+++ b/tests/metrics/collectors/test_state_collectors.py@@ -3,16 +3,12 @@from __future__ import annotations-import time--from openviking.metrics.collectors.lock import LockCollectorfrom openviking.metrics.collectors.observer_health import ObserverHealthCollectorfrom openviking.metrics.collectors.queue import QueueCollectorfrom openviking.metrics.collectors.task_tracker import TaskTrackerCollectorfrom openviking.metrics.collectors.vikingdb import VikingDBCollectorfrom openviking.metrics.core.registry import MetricRegistryfrom openviking.metrics.datasources.observer_state import (- LockStateDataSource,ObserverStateDataSource,VikingDBStateDataSource,)@@ -233,31 +229,6 @@ def test_model_usage_collector_failure_reuses_last_available_state_with_valid_zeassert 'openviking_model_usage_available{model_type="rerank",valid="0"} 0.0' in text-def test_lock_collector_counts_active_and_stale(monkeypatch):- class Handle:- def __init__(self, locks: int, last_active_at: float) -> None:- self.locks = [object()] * locks- self.last_active_at = last_active_at-- class DummyLockManager:- def get_active_handles(self):- now = time.time()- return {- "a": Handle(locks=2, last_active_at=now - 10),- "b": Handle(locks=1, last_active_at=now - 1000),- }-- monkeypatch.setattr(- "openviking.metrics.datasources.observer_state.get_lock_manager",- lambda: DummyLockManager(),- )- registry = MetricRegistry()- LockCollector(data_source=LockStateDataSource()).collect(registry)- text = PrometheusExporter(registry=registry).render()- assert "openviking_lock_active 3.0" in text- assert "openviking_lock_stale 1.0" in text--def test_vikingdb_collector_exports_health_and_count(monkeypatch):class DummyVikingDB:collection_name = "my_collection"diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex 6b819798c..dccbfcffa 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -584,9 +584,30 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p"provider_type": 7,},"cache": agfs_config.cache.model_dump(mode="json"),+ "pathlock": {+ "provider": "filesystem",+ "lock_expire_secs": 300.0,+ },}+def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):+ """PathLock config accepts built-ins and rejects unsafe expiry values."""+ config = AGFSConfig(+ path=str(tmp_path),+ backend="local",+ pathlock={"provider": "memory", "lock_expire_secs": 60.0},+ )++ assert config.pathlock.provider == "memory"+ assert config.pathlock.lock_expire_secs == 60.0++ with pytest.raises(ValueError, match="pathlock provider"):+ AGFSConfig(path=str(tmp_path), pathlock={"provider": "redis"})+ with pytest.raises(ValueError, match="lock_expire_secs"):+ AGFSConfig(path=str(tmp_path), pathlock={"lock_expire_secs": 0.0})++def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):agfs_config = AGFSConfig(path=str(tmp_path),diff --git a/tests/misc/test_debug_service.py b/tests/misc/test_debug_service.pyindex 90de9062d..922e59068 100644--- a/tests/misc/test_debug_service.py+++ b/tests/misc/test_debug_service.py@@ -202,9 +202,9 @@ class TestObserverService:rerank_instance=None,)- @patch("openviking.service.debug_service.get_lock_manager")+ @patch("openviking.service.debug_service.run_async")+ @patch("openviking.service.debug_service.get_viking_fs")@patch("openviking.service.debug_service.RetrievalObserver")- @patch("openviking.service.debug_service.LockObserver")@patch("openviking.service.debug_service.ModelsObserver")@patch("openviking.service.debug_service.VikingDBObserver")@patch("openviking.service.debug_service.QueueObserver")@@ -215,9 +215,9 @@ class TestObserverService:mock_queue_cls,mock_vikingdb_cls,mock_models_cls,- mock_lock_cls,mock_retrieval_cls,- mock_get_lock_mgr,+ mock_get_viking_fs,+ mock_run_async,):"""Test system property when all components are healthy."""# Setup mocks@@ -225,7 +225,6 @@ class TestObserverService:mock_queue_cls,mock_vikingdb_cls,mock_models_cls,- mock_lock_cls,mock_retrieval_cls,]:mock_observer = MagicMock()@@ -234,8 +233,15 @@ class TestObserverService:mock_observer.get_status_table.return_value = "OK"mock_cls.return_value = mock_observer- # Mock get_lock_manager to return a MagicMock- mock_get_lock_mgr.return_value = MagicMock()+ # Mock get_viking_fs to return a viking_fs with pathlock_observe+ mock_viking_fs = MagicMock()+ mock_get_viking_fs.return_value = mock_viking_fs+ mock_run_async.return_value = {+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflicts": [],+ }mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attributemock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -248,9 +254,9 @@ class TestObserverService:non_transaction_errors = [e for e in status.errors if "transaction" not in e]assert non_transaction_errors == []- @patch("openviking.service.debug_service.get_lock_manager")+ @patch("openviking.service.debug_service.run_async")+ @patch("openviking.service.debug_service.get_viking_fs")@patch("openviking.service.debug_service.RetrievalObserver")- @patch("openviking.service.debug_service.LockObserver")@patch("openviking.service.debug_service.ModelsObserver")@patch("openviking.service.debug_service.VikingDBObserver")@patch("openviking.service.debug_service.QueueObserver")@@ -261,9 +267,9 @@ class TestObserverService:mock_queue_cls,mock_vikingdb_cls,mock_models_cls,- mock_lock_cls,mock_retrieval_cls,- mock_get_lock_mgr,+ mock_get_viking_fs,+ mock_run_async,):"""Test system property when some components have errors."""# Queue has errors@@ -287,16 +293,22 @@ class TestObserverService:mock_models.get_status_table.return_value = "Error"mock_models_cls.return_value = mock_models- # Lock and Retrieval are healthy- for mock_cls in [mock_lock_cls, mock_retrieval_cls]:- mock_observer = MagicMock()- mock_observer.is_healthy.return_value = True- mock_observer.has_errors.return_value = False- mock_observer.get_status_table.return_value = "OK"- mock_cls.return_value = mock_observer-- # Mock get_lock_manager to return a MagicMock- mock_get_lock_mgr.return_value = MagicMock()+ # Retrieval is healthy+ mock_retrieval = MagicMock()+ mock_retrieval.is_healthy.return_value = True+ mock_retrieval.has_errors.return_value = False+ mock_retrieval.get_status_table.return_value = "OK"+ mock_retrieval_cls.return_value = mock_retrieval++ # Mock lock (pathlock_observe) as healthy+ mock_viking_fs = MagicMock()+ mock_get_viking_fs.return_value = mock_viking_fs+ mock_run_async.return_value = {+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflicts": [],+ }mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attributemock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -310,7 +322,8 @@ class TestObserverService:assert "queue has errors" in non_transaction_errorsassert "models has errors" in non_transaction_errors- @patch("openviking.service.debug_service.get_lock_manager")+ @patch("openviking.service.debug_service.run_async")+ @patch("openviking.service.debug_service.get_viking_fs")@patch("openviking.service.debug_service.get_queue_manager")@patch("openviking.service.debug_service.QueueObserver")@patch("openviking.service.debug_service.VikingDBObserver")@@ -321,7 +334,8 @@ class TestObserverService:mock_vikingdb_cls,mock_queue_cls,mock_get_queue_mgr,- mock_get_lock_mgr,+ mock_get_viking_fs,+ mock_run_async,):"""Test is_healthy returns True when system is healthy."""for mock_cls in [mock_queue_cls, mock_vikingdb_cls, mock_models_cls]:@@ -331,7 +345,14 @@ class TestObserverService:mock_observer.get_status_table.return_value = "OK"mock_cls.return_value = mock_observer- mock_get_lock_mgr.return_value = MagicMock()+ mock_viking_fs = MagicMock()+ mock_get_viking_fs.return_value = mock_viking_fs+ mock_run_async.return_value = {+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflicts": [],+ }mock_config = MagicMock(spec=["vlm"])mock_config.vlm.get_vlm_instance.return_value = MagicMock()diff --git a/tests/misc/test_resource_processor_mv.py b/tests/misc/test_resource_processor_mv.pyindex b364be0bc..9090efbd0 100644--- a/tests/misc/test_resource_processor_mv.py+++ b/tests/misc/test_resource_processor_mv.py@@ -39,59 +39,36 @@ class _CtxMgr:return False-class _FakeLockManager:+class _FakePathLock:def __init__(self, *, busy_tree_paths=None):- from openviking.storage.transaction.lock_handle import LockHandle-- self._lock_handle_cls = LockHandle- self._handles = {}- self.acquired_exact_paths = []- self.acquired_tree_paths = []- self.tree_attempts = []+ self._next_id = 0+ self.acquired_tree_paths: list[str] = []+ self.tree_attempts: list[tuple[str, float]] = []self.busy_tree_paths = set(busy_tree_paths or [])- def create_handle(self):- handle = self._lock_handle_cls()- self._handles[handle.id] = handle- return handle+ def _new_lease(self):+ self._next_id += 1+ return {"id": f"lock-{self._next_id}"}- async def acquire_exact_path_batch(self, handle, paths, timeout=None):- for path in paths:- lock_path = f"exact:{path}"- handle.add_lock(lock_path)- self.acquired_exact_paths.append(path)- return True+ async def pathlock_acquire_tree(self, path, timeout_secs=0.0):+ from openviking.storage.errors import LockAcquisitionError- async def acquire_tree(self, handle, path, timeout=None):- self.tree_attempts.append((path, timeout))+ self.tree_attempts.append((path, timeout_secs))if path in self.busy_tree_paths:- return False- lock_path = f"tree:{path}"- handle.add_lock(lock_path)+ raise LockAcquisitionError(f"busy: {path}")self.acquired_tree_paths.append(path)- return True+ return self._new_lease()- async def release_selected(self, handle, lock_paths):- for path in lock_paths:- handle.remove_lock(path)-- async def release(self, handle):- for path in list(handle.locks):- handle.remove_lock(path)- self._handles.pop(handle.id, None)-- def get_handle(self, handle_id):- handle = self._handles.get(handle_id)- if handle and handle.locks:- return handle- return None+ async def pathlock_release(self, lease):+ passclass _FakeVikingFS:- def __init__(self, *, exists_result=False, existing_uris=None):+ def __init__(self, *, exists_result=False, existing_uris=None, pathlock=None):self.agfs = SimpleNamespace(write=MagicMock(return_value={"status": "ok"}),)+ self._async_agfs = pathlock or _FakePathLock()self._exists_result = exists_resultself._existing_uris = set(existing_uris or [])self.exists_calls = []@@ -110,12 +87,12 @@ class _FakeVikingFS:async def mkdir(self, uri, exist_ok=False, ctx=None):return None- async def delete_temp(self, temp_dir_path, ctx=None):- self.delete_temp_calls.append(temp_dir_path)+ async def delete_temp(self, temp_dir_path, ctx=None, lease_ref=None):+ self.delete_temp_calls.append((temp_dir_path, lease_ref))return None- async def persist_temp_tree(self, temp_uri, target_uri, ctx=None):- self.persist_calls.append((temp_uri, target_uri))+ async def persist_temp_tree(self, temp_uri, target_uri, ctx=None, lease_ref=None):+ self.persist_calls.append((temp_uri, target_uri, lease_ref))self.agfs.write(self._uri_to_path(target_uri, ctx=ctx), b"content")async def glob(self, pattern, uri=None, ctx=None):@@ -135,7 +112,6 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkeyfrom openviking.utils.resource_processor import ResourceProcessorfake_fs = _FakeVikingFS()- fake_lock_manager = _FakeLockManager()summarize_calls = []monkeypatch.setattr(@@ -143,10 +119,6 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkeylambda: _DummyTelemetry(),)_patch_viking_fs(monkeypatch, fake_fs)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: fake_lock_manager,- )rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)rp._get_media_processor = MagicMock()@@ -176,8 +148,10 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkeyassert result["status"] == "success"assert result["root_uri"] == "viking://resources/root"- assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root")]- assert fake_fs.delete_temp_calls == ["viking://temp/tmpdir"]+ assert fake_fs.persist_calls == [+ ("viking://temp/root_tmp", "viking://resources/root", {"id": "lock-1"})+ ]+ assert fake_fs.delete_temp_calls == [("viking://temp/tmpdir", None)]assert summarize_calls[0]["temp_uris"] == ["viking://resources/root"]assert summarize_calls[0]["target_preexisting"] is False@@ -187,7 +161,6 @@ async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(from openviking.utils.resource_processor import ResourceProcessorfake_fs = _FakeVikingFS(exists_result=True)- fake_lock_manager = _FakeLockManager()summarize_calls = []monkeypatch.setattr(@@ -195,10 +168,6 @@ async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(lambda: _DummyTelemetry(),)_patch_viking_fs(monkeypatch, fake_fs)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: fake_lock_manager,- )rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)rp._get_media_processor = MagicMock()@@ -237,8 +206,8 @@ async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeypatch):from openviking.utils.resource_processor import ResourceProcessor- fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"})- fake_lock_manager = _FakeLockManager(busy_tree_paths={"/mock/resources/root_1"})+ fake_pathlock = _FakePathLock(busy_tree_paths={"/mock/resources/root_1"})+ fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"}, pathlock=fake_pathlock)summarize_calls = []monkeypatch.setattr(@@ -246,10 +215,6 @@ async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeyplambda: _DummyTelemetry(),)_patch_viking_fs(monkeypatch, fake_fs)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: fake_lock_manager,- )rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)rp._get_media_processor = MagicMock()@@ -285,12 +250,13 @@ async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeyp"viking://resources/root_1","viking://resources/root_2",]- assert fake_lock_manager.tree_attempts == [+ assert fake_pathlock.tree_attempts == [("/mock/resources/root_1", 0.0),("/mock/resources/root_2", 0.0),]- assert fake_lock_manager.acquired_exact_paths == []- assert fake_lock_manager.acquired_tree_paths == ["/mock/resources/root_2"]+ assert fake_pathlock.acquired_tree_paths == ["/mock/resources/root_2"]assert summarize_calls[0]["temp_uris"] == ["viking://resources/root_2"]assert summarize_calls[0]["target_preexisting"] is False- assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root_2")]+ assert fake_fs.persist_calls == [+ ("viking://temp/root_tmp", "viking://resources/root_2", {"id": "lock-1"})+ ]diff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.pyindex 22a732b34..26fcfba7f 100644--- a/tests/parse/test_feishu_parser_api.py+++ b/tests/parse/test_feishu_parser_api.py@@ -440,10 +440,6 @@ async def test_uat_producer_payload_reaches_worker_without_persisting_token(monk"openviking.storage.queuefs.get_queue_manager",Mock(return_value=queue_manager),)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- Mock(return_value=SimpleNamespace()),- )service = ResourceService(viking_fs=SimpleNamespace(),@@ -513,7 +509,12 @@ async def test_uat_producer_payload_reaches_worker_without_persisting_token(monk@pytest.mark.asyncioasync def test_local_prepared_job_uses_add_resource_queue(monkeypatch):root_uri = "viking://resources/script"- resource_lock = SimpleNamespace(to_handoff=Mock(return_value=None))+ resource_lock = {"lease_ref": "lock-1"}+ agfs = SimpleNamespace(+ pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),+ pathlock_handoff=AsyncMock(),+ pathlock_release=AsyncMock(),+ )resource_processor = SimpleNamespace(process_resource=AsyncMock(return_value={@@ -526,7 +527,7 @@ async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):)service = ResourceService(- viking_fs=SimpleNamespace(),+ viking_fs=SimpleNamespace(_async_agfs=agfs),resource_processor=resource_processor,skill_processor=SimpleNamespace(),)@@ -556,6 +557,8 @@ async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):call = service._enqueue_add_resource_job.await_argsassert call.kwargs["queue_name"] == QueueManager.ADD_RESOURCEassert call.args[0].prepared == {"root_uri": root_uri}+ assert call.args[0].lock_handoff == {"handle_id": "lock-1"}+ agfs.pathlock_to_handoff.assert_awaited_once_with(resource_lock)@pytest.mark.asyncio@@ -569,6 +572,7 @@ async def test_uat_producer_cancellation_respects_queue_ownership(submit_url = AsyncMock(return_value="response-1")enqueue = AsyncMock()handoff = AsyncMock()+ release = AsyncMock()if cancel_stage == "submit":submit_url.side_effect = asyncio.CancelledErrorelif cancel_stage == "enqueue":@@ -587,19 +591,17 @@ async def test_uat_producer_cancellation_respects_queue_ownership(fail=AsyncMock(),)queue_manager = SimpleNamespace(enqueue=enqueue)- lock_lease = SimpleNamespace(- to_handoff=Mock(- return_value=SimpleNamespace(- to_dict=Mock(- return_value={- "handle_id": "lock-1",- "lock_paths": ["/resources/fixed"],- }- )- )+ lock_lease = {"lease_ref": "lock-1"}+ agfs = SimpleNamespace(+ pathlock_acquire_tree=AsyncMock(return_value=lock_lease),+ pathlock_to_handoff=AsyncMock(+ return_value={+ "handle_id": "lock-1",+ "lock_paths": ["/resources/fixed"],+ }),- handoff=handoff,- close=AsyncMock(),+ pathlock_handoff=handoff,+ pathlock_release=release,)monkeypatch.setattr("openviking.service.task_tracker.get_task_tracker",@@ -609,17 +611,12 @@ async def test_uat_producer_cancellation_respects_queue_ownership("openviking.storage.queuefs.get_queue_manager",Mock(return_value=queue_manager),)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- Mock(return_value=SimpleNamespace()),- )- monkeypatch.setattr(- "openviking.storage.transaction.OwnedLockLease.acquire_tree",- AsyncMock(return_value=lock_lease),- )service = ResourceService(- viking_fs=SimpleNamespace(_uri_to_path=lambda _uri, ctx: "/resources/fixed"),+ viking_fs=SimpleNamespace(+ _uri_to_path=lambda _uri, ctx: "/resources/fixed",+ _async_agfs=agfs,+ ),resource_processor=resource_processor,skill_processor=SimpleNamespace(),)@@ -647,7 +644,7 @@ async def test_uat_producer_cancellation_respects_queue_ownership(args={"feishu_access_token": "u-secret"},)- lock_lease.close.assert_awaited_once_with()+ release.assert_awaited_once_with(lock_lease)task_tracker.create.assert_not_awaited()task_tracker.fail.assert_not_awaited()if cancel_stage == "submit":@@ -813,6 +810,7 @@ async def test_add_resource_processor_persists_final_resource_uri(monkeypatch):service,asyncio.get_running_loop(),QueueManager.ADD_RESOURCE,+ SimpleNamespace(_async_agfs=SimpleNamespace(pathlock_release=AsyncMock())),)msg = AddResourceMsg(task_id="task-1",diff --git a/tests/parse/test_markdown_link_rewrite.py b/tests/parse/test_markdown_link_rewrite.pyindex 2f99ba884..a1f26f494 100644--- a/tests/parse/test_markdown_link_rewrite.py+++ b/tests/parse/test_markdown_link_rewrite.py@@ -551,7 +551,7 @@ class TestImageLinkSplit:import openviking.parse.image_rewrite as image_rewrite_modwith patch.object(image_rewrite_mod, "get_viking_fs", return_value=fake):- stats = await rewrite_image_uris(root, lock_handle=None)+ stats = await rewrite_image_uris(root, lease_ref=None)assert stats["references_rewritten"] == 2, statspage = _decode(fake.files[f"{root}/guides/page/page.md"])@@ -601,7 +601,7 @@ class TestRewriteImageUris:}with self._patched(fake):- stats = await rewrite_image_uris(root, lock_handle=None)+ stats = await rewrite_image_uris(root, lease_ref=None)assert stats == {"files_processed": 1, "references_rewritten": 1}assert _decode(fake.files[f"{root}/index/index.md"]) == (f"")@@ -623,7 +623,7 @@ class TestRewriteImageUris:}with self._patched(fake):- stats = await rewrite_image_uris(root, lock_handle=None)+ stats = await rewrite_image_uris(root, lease_ref=None)assert stats == {"files_processed": 1, "references_rewritten": 1}assert _decode(fake.files[f"{root}/big/标题/章一/部分_1.md"]) == (@@ -647,7 +647,7 @@ class TestRewriteImageUris:}with self._patched(fake):- stats = await rewrite_image_uris(root, lock_handle=None)+ stats = await rewrite_image_uris(root, lease_ref=None)assert stats == {"files_processed": 1, "references_rewritten": 1}assert _decode(fake.files[f"{root}/doc.md"]) == f""@@ -736,7 +736,7 @@ class TestRewriteImageUris:fake.files[f"{root}/{u[len(src_prefix) :]}"] = fake.files[u]with self._patched(fake):- stats = await rewrite_image_uris(root, lock_handle=None)+ stats = await rewrite_image_uris(root, lease_ref=None)assert stats["files_processed"] == 2, statsindex_md = _decode(fake.files[f"{root}/index/index.md"])diff --git a/tests/server/conftest.py b/tests/server/conftest.pyindex 0904c3638..5e85ed22a 100644--- a/tests/server/conftest.py+++ b/tests/server/conftest.py@@ -24,7 +24,6 @@ from openviking.server.config import ServerConfigfrom openviking.server.identity import RequestContext, Rolefrom openviking.service.core import OpenVikingServicefrom openviking.storage.queuefs import QueueManager, SessionCommitMsg, get_queue_manager-from openviking.storage.transaction import reset_lock_managerfrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils.config.embedding_config import EmbeddingConfigfrom openviking_cli.utils.config.vlm_config import VLMConfig@@ -168,7 +167,6 @@ def upload_temp_dir(temp_dir: Path, monkeypatch) -> Path:@pytest_asyncio.fixture(scope="function")async def service(temp_dir: Path, monkeypatch):"""Create and initialize an OpenVikingService in embedded mode."""- reset_lock_manager()fake_embedder_cls = _install_fake_embedder(monkeypatch)_install_fake_vlm(monkeypatch)svc = OpenVikingService(@@ -179,7 +177,6 @@ async def service(temp_dir: Path, monkeypatch):_install_session_commit_queue_fallback(svc, monkeypatch)yield svcawait svc.close()- reset_lock_manager()@pytest_asyncio.fixture(scope="function")@@ -233,7 +230,6 @@ async def client_with_resource(client, service, sample_markdown_file):async def running_server(temp_dir: Path, monkeypatch):"""Start a real uvicorn server in a background thread."""await AsyncOpenViking.reset()- reset_lock_manager()fake_embedder_cls = _install_fake_embedder(monkeypatch)_install_fake_vlm(monkeypatch)diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.pyindex 7f7695d49..b9e8c7100 100644--- a/tests/server/test_admin_api.py+++ b/tests/server/test_admin_api.py@@ -43,19 +43,6 @@ def _seed_secret(user_id: str, seed: str) -> str:ROOT_KEY = "admin-api-test-root-key-abcdef1234567890ab"-class _NoopLockContext:- """The lightweight fake storage does not exercise transaction locking."""-- def __init__(self, *_args, **_kwargs):- pass-- async def __aenter__(self):- return self-- async def __aexit__(self, *_args):- return False--class _FakeAGFS:def __init__(self):self._files = {}@@ -148,12 +135,6 @@ def _build_lightweight_admin_test_app() -> FastAPI:@pytest_asyncio.fixture(scope="function")async def lightweight_admin_app(monkeypatch):- monkeypatch.setattr(- "openviking.server.api_keys.legacy.get_lock_manager", lambda: None- )- monkeypatch.setattr(- "openviking.server.api_keys.legacy.LockContext", _NoopLockContext- )app = _build_lightweight_admin_test_app()await app.state.api_key_manager.load()return appdiff --git a/tests/server/test_api_key_manager.py b/tests/server/test_api_key_manager.pyindex 309c02efe..c25177145 100644--- a/tests/server/test_api_key_manager.py+++ b/tests/server/test_api_key_manager.py@@ -15,7 +15,6 @@ from openviking.server.api_keys import APIKeyManagerfrom openviking.server.api_keys.legacy import ACCOUNTS_PATHfrom openviking.server.identity import Rolefrom openviking.service.core import OpenVikingService-from openviking.storage.transaction import LockContext, get_lock_managerfrom openviking_cli.exceptions import (AlreadyExistsError,InvalidArgumentError,@@ -171,32 +170,54 @@ async def test_register_user(manager: APIKeyManager):async def test_concurrent_registry_writes_wait_for_locks(manager: APIKeyManager):first_account = _uid()second_account = _uid()+ accounts_block = asyncio.Event()+ original_acquire = manager._legacy._async_agfs.pathlock_acquire_exact- async with LockContext(get_lock_manager(), [ACCOUNTS_PATH], lock_mode="exact"):- account_tasks = [- asyncio.create_task(manager.create_account(first_account, "alice")),- asyncio.create_task(manager.create_account(second_account, "bob")),- ]- await asyncio.sleep(0.05)- assert all(not task.done() for task in account_tasks)+ async def blocked_acquire(path, timeout_secs=10.0, owner_lease_ref=None, *, fs_ctx=None):+ del owner_lease_ref, fs_ctx+ if path == ACCOUNTS_PATH:+ await accounts_block.wait()+ return await original_acquire(path, timeout_secs=timeout_secs)+ manager._legacy._async_agfs.pathlock_acquire_exact = blocked_acquire++ account_tasks = [+ asyncio.create_task(manager.create_account(first_account, "alice")),+ asyncio.create_task(manager.create_account(second_account, "bob")),+ ]+ await asyncio.sleep(0.05)+ assert all(not task.done() for task in account_tasks)++ accounts_block.set()await asyncio.gather(*account_tasks)accounts = await manager._read_json(ACCOUNTS_PATH)assert {first_account, second_account} <= set(accounts["accounts"])users_path = f"/local/{first_account}/_system/users.json"- async with LockContext(get_lock_manager(), [users_path], lock_mode="exact"):- user_tasks = [- asyncio.create_task(manager.register_user(first_account, "bob")),- asyncio.create_task(manager.register_user(first_account, "carol")),- ]- await asyncio.sleep(0.05)- assert all(not task.done() for task in user_tasks)+ users_block = asyncio.Event()++ async def blocked_users_acquire(path, timeout_secs=10.0, owner_lease_ref=None, *, fs_ctx=None):+ del owner_lease_ref, fs_ctx+ if path == users_path:+ await users_block.wait()+ return await original_acquire(path, timeout_secs=timeout_secs)+ manager._legacy._async_agfs.pathlock_acquire_exact = blocked_users_acquire++ user_tasks = [+ asyncio.create_task(manager.register_user(first_account, "bob")),+ asyncio.create_task(manager.register_user(first_account, "carol")),+ ]+ await asyncio.sleep(0.05)+ assert all(not task.done() for task in user_tasks)++ users_block.set()await asyncio.gather(*user_tasks)users = await manager._read_json(users_path)assert set(users["users"]) == {"alice", "bob", "carol"}+ manager._legacy._async_agfs.pathlock_acquire_exact = original_acquire+async def test_register_duplicate_user_raises(manager: APIKeyManager):"""Registering duplicate user should raise AlreadyExistsError."""diff --git a/tests/server/test_content_batch_write.py b/tests/server/test_content_batch_write.pyindex 8841d9f57..225023b0c 100644--- a/tests/server/test_content_batch_write.py+++ b/tests/server/test_content_batch_write.py@@ -15,21 +15,18 @@ from openviking_cli.exceptions import (from openviking_cli.session.user_id import UserIdentifier-class _LockManager:+class _PathLockClient:def __init__(self):self.held = Falseself.releases = 0- def create_handle(self):- return object()-- async def acquire_tree(self, handle, path):- del handle, path+ async def pathlock_acquire_tree(self, path):+ del pathself.held = True- return True+ return {"lease_ref": "lock-1"}- async def release(self, handle):- del handle+ async def pathlock_release(self, lease):+ assert lease == {"lease_ref": "lock-1"}self.held = Falseself.releases += 1@@ -40,6 +37,7 @@ class _VFS:self.files = dict(files or {})self.fail_uri = fail_uriself.writes = []+ self._async_agfs = _PathLockClient()def _ensure_mutable_access(self, uri, ctx):del uri, ctx@@ -66,9 +64,9 @@ class _VFS:value = await self.read_file(uri, ctx=ctx)return value.encode() if isinstance(value, str) else value- async def write_file(self, uri, content, ctx=None, lock_handle=None):+ async def write_file(self, uri, content, ctx=None, lease_ref=None):del ctx- assert lock_handle is not None+ assert lease_ref is not Noneif uri == self.fail_uri:raise OSError("injected write failure")self.files[uri] = content@@ -88,10 +86,9 @@ async def test_batch_checks_all_preconditions_before_any_write(monkeypatch):root = "viking://resources/wiki"existing = f"{root}/existing.md"created = f"{root}/new.md"- locks = _LockManager()vfs = _VFS(root, {existing: "newer"})+ locks = vfs._async_agfscoordinator = ContentWriteCoordinator(vfs)- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)refreshed = []async def refresh(**kwargs):@@ -130,10 +127,9 @@ async def test_batch_releases_tree_lock_before_one_aggregated_refresh(monkeypatcroot = "viking://resources/wiki"a = f"{root}/a.md"b = f"{root}/b.md"- locks = _LockManager()vfs = _VFS(root)+ locks = vfs._async_agfscoordinator = ContentWriteCoordinator(vfs)- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)calls = []async def refresh(**kwargs):@@ -162,12 +158,10 @@ async def test_batch_releases_tree_lock_before_one_aggregated_refresh(monkeypatcasync def test_batch_writes_and_hashes_binary_content(monkeypatch):root = "viking://resources/wiki"image = f"{root}/figure.png"- locks = _LockManager()original = b"\x89PNG\r\n\x1a\nold"replacement = b"\x89PNG\r\n\x1a\nnew"vfs = _VFS(root, {image: original})coordinator = ContentWriteCoordinator(vfs)- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)async def refresh(**kwargs):return None@@ -235,10 +229,9 @@ async def test_batch_partial_failure_refreshes_successful_files_and_retry_is_safroot = "viking://resources/wiki"a = f"{root}/a.md"b = f"{root}/b.md"- locks = _LockManager()vfs = _VFS(root, fail_uri=b)+ locks = vfs._async_agfscoordinator = ContentWriteCoordinator(vfs)- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)calls = []async def refresh(**kwargs):@@ -270,10 +263,8 @@ async def test_batch_partial_failure_refreshes_successful_files_and_retry_is_safasync def test_batch_refresh_failure_retry_skips_landed_write_and_refreshes(monkeypatch):root = "viking://resources/wiki"page = f"{root}/page.md"- locks = _LockManager()vfs = _VFS(root)coordinator = ContentWriteCoordinator(vfs)- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)calls = []async def refresh(**kwargs):diff --git a/tests/server/test_content_write_service.py b/tests/server/test_content_write_service.pyindex 32a4f9735..0a7949154 100644--- a/tests/server/test_content_write_service.py+++ b/tests/server/test_content_write_service.py@@ -3,13 +3,15 @@"""Service-level tests for content write coordination."""+from types import SimpleNamespace+import pytestfrom openviking.server.identity import RequestContext, Rolefrom openviking.session.memory.dataclass import MemoryFilefrom openviking.session.memory.utils import MemoryFileUtilsfrom openviking.storage.content_write import ContentWriteCoordinator-from openviking.storage.errors import ResourceBusyError+from openviking.storage.errors import LockAcquisitionError, ResourceBusyErrorfrom openviking_cli.exceptions import (AlreadyExistsError,DeadlineExceededError,@@ -288,36 +290,25 @@ async def test_memory_rm_refreshes_nested_schema_overview(service):assert "[越前龙马-keep-test](./越前龙马-keep-test.md)" in after-class _FakeHandle:- def __init__(self, handle_id: str):- self.id = handle_id-+class _FakePathLock:+ """Mock for _async_agfs pathlock operations."""-class _FakeLockManager:- def __init__(- self,- *,- acquire_exact_path_result: bool = True,- acquire_tree_result: bool = True,- ):- self.handle = _FakeHandle("lock-1")- self.acquire_exact_path_result = acquire_exact_path_result- self.acquire_tree_result = acquire_tree_result+ def __init__(self, *, acquire_result=True, acquire_error=None):+ self._lease = SimpleNamespace(id="lock-1")+ self.acquire_result = acquire_result+ self.acquire_error = acquire_errorself.release_calls = []- def create_handle(self):- return self.handle-- async def acquire_tree(self, handle, path):- del handle, path- return self.acquire_tree_result-- async def acquire_exact_path(self, handle, path):- del handle, path- return self.acquire_exact_path_result+ async def pathlock_acquire_exact(self, lock_path):+ del lock_path+ if self.acquire_error is not None:+ raise self.acquire_error+ if not self.acquire_result:+ raise LockAcquisitionError("lock conflict")+ return self._lease- async def release(self, handle):- self.release_calls.append(handle.id)+ async def pathlock_release(self, lease):+ self.release_calls.append(lease.id)class _FakeVikingFS:@@ -330,6 +321,7 @@ class _FakeVikingFS:self.content = {file_uri: "original"}self.vector_store = Noneself.tree_entries = []+ self._async_agfs = _FakePathLock()async def stat(self, uri: str, ctx=None):del ctx@@ -354,13 +346,13 @@ class _FakeVikingFS:del ctxreturn self.content[uri]- async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None):+ async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None, lease_ref=None):del ctx- self.write_file_calls.append((uri, content, lock_handle))+ self.write_file_calls.append((uri, content, lease_ref or lock_handle))self.content[uri] = content- async def rm(self, uri: str, ctx=None, lock_handle=None):- del ctx, lock_handle+ async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):+ del ctx, lock_handle, lease_refself.rm_calls.append(uri)self.content.pop(uri, None)@@ -439,12 +431,6 @@ async def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )async def _fake_enqueue_semantic_refresh(**kwargs):del kwargs@@ -465,7 +451,7 @@ async def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):wait=True,)- assert lock_manager.release_calls == ["lock-1"]+ assert viking_fs._async_agfs.release_calls == ["lock-1"]assert viking_fs.delete_temp_calls == []assert viking_fs.content[file_uri] == "updated"@@ -476,13 +462,8 @@ async def test_resource_write_lock_conflict_raises_resource_busy(monkeypatch):root_uri = "viking://resources/demo"ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)+ viking_fs._async_agfs = _FakePathLock(acquire_result=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager(acquire_exact_path_result=False)-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )with pytest.raises(ResourceBusyError) as exc_info:await coordinator.write(@@ -492,7 +473,7 @@ async def test_resource_write_lock_conflict_raises_resource_busy(monkeypatch):)assert exc_info.value.uri == file_uri- assert lock_manager.release_calls == ["lock-1"]+ assert viking_fs._async_agfs.release_calls == []assert viking_fs.content[file_uri] == "original"@@ -502,13 +483,8 @@ async def test_memory_write_lock_conflict_raises_resource_busy(monkeypatch):root_uri = "viking://user/default/memories/preferences"ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)+ viking_fs._async_agfs = _FakePathLock(acquire_result=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager(acquire_exact_path_result=False)-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )with pytest.raises(ResourceBusyError) as exc_info:await coordinator.write(@@ -518,27 +494,46 @@ async def test_memory_write_lock_conflict_raises_resource_busy(monkeypatch):)assert exc_info.value.uri == file_uri- assert lock_manager.release_calls == ["lock-1"]+ assert viking_fs._async_agfs.release_calls == []assert viking_fs.content[file_uri] == "original"@pytest.mark.asyncio-async def test_write_direct_reuses_outer_lock_handle_for_viking_fs(monkeypatch):+ "file_uri",+ [+ "viking://resources/demo/doc.md",+ "viking://user/default/memories/preferences/theme.md",+ ],+)+async def test_write_lock_storage_error_is_not_mapped_to_resource_busy(file_uri):+ """Preserve non-conflict acquisition failures for direct and memory writes."""+ root_uri = file_uri.rsplit("/", 1)[0]+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)+ viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)+ viking_fs._async_agfs = _FakePathLock(acquire_error=RuntimeError("storage failed"))+ coordinator = ContentWriteCoordinator(viking_fs=viking_fs)++ with pytest.raises(RuntimeError, match="storage failed"):+ await coordinator.write(+ uri=file_uri,+ content="updated",+ ctx=ctx,+ )+++async def test_write_direct_reuses_outer_lease_for_viking_fs(monkeypatch):file_uri = "viking://resources/demo/doc.md"root_uri = "viking://resources/demo"ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()async def _fake_enqueue_semantic_refresh(**kwargs):del kwargsreturn None- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )monkeypatch.setattr(coordinator, "_enqueue_semantic_refresh", _fake_enqueue_semantic_refresh)result = await coordinator._write_direct_with_refresh(@@ -555,7 +550,8 @@ async def test_write_direct_reuses_outer_lock_handle_for_viking_fs(monkeypatch):)assert result["uri"] == file_uri- assert viking_fs.write_file_calls == [(file_uri, "updated", lock_manager.handle)]+ assert viking_fs.write_file_calls[0][0:2] == (file_uri, "updated")+ assert viking_fs.write_file_calls[0][2].id == "lock-1"@pytest.mark.asyncio@@ -565,14 +561,8 @@ async def test_resource_write_updates_target_and_queues_refresh_before_return(moctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()captured_enqueue = {}- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )-async def _fake_enqueue_semantic_refresh(**kwargs):captured_enqueue.update(kwargs)@@ -594,7 +584,7 @@ async def test_resource_write_updates_target_and_queues_refresh_before_return(moassert captured_enqueue["changed_uri"] == file_uriassert captured_enqueue["change_type"] == "modified"assert viking_fs.delete_temp_calls == []- assert lock_manager.release_calls == ["lock-1"]+ assert viking_fs._async_agfs.release_calls == ["lock-1"]@pytest.mark.asyncio@@ -604,12 +594,6 @@ async def test_resource_write_rolls_back_replace_when_enqueue_fails(monkeypatch)ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )async def _fail_enqueue(**kwargs):del kwargs@@ -626,11 +610,12 @@ async def test_resource_write_rolls_back_replace_when_enqueue_fails(monkeypatch))assert viking_fs.content[file_uri] == "original"- assert viking_fs.write_file_calls == [- (file_uri, "updated", lock_manager.handle),- (file_uri, "original", lock_manager.handle),+ assert [call[0:2] for call in viking_fs.write_file_calls] == [+ (file_uri, "updated"),+ (file_uri, "original"),]- assert lock_manager.release_calls == ["lock-1"]+ assert [call[2].id for call in viking_fs.write_file_calls] == ["lock-1", "lock-1"]+ assert viking_fs._async_agfs.release_calls == ["lock-1"]@pytest.mark.asyncio@@ -640,12 +625,6 @@ async def test_resource_write_rolls_back_create_when_enqueue_fails(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )async def _fail_enqueue(**kwargs):del kwargs@@ -663,7 +642,7 @@ async def test_resource_write_rolls_back_create_when_enqueue_fails(monkeypatch):assert file_uri not in viking_fs.contentassert viking_fs.rm_calls == [file_uri]- assert lock_manager.release_calls == ["lock-1"]+ assert viking_fs._async_agfs.release_calls == ["lock-1"]@pytest.mark.asyncio@@ -673,15 +652,9 @@ async def test_memory_write_wait_skips_semantic_queue_and_releases_write_lock(moctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del uri, content, mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del uri, content, mode, ctx, lock_handle, lease_refreturn Noneasync def _fail_wait_for_request(*, telemetry_id, timeout):@@ -706,7 +679,7 @@ async def test_memory_write_wait_skips_semantic_queue_and_releases_write_lock(mowait=True,)- assert lock_manager.release_calls == ["lock-1"]+ assert viking_fs._async_agfs.release_calls == ["lock-1"]assert result["semantic_status"] == "skipped"assert result["vector_status"] == "skipped"assert result["overview_status"] == "complete"@@ -734,6 +707,7 @@ class _FakeVikingFSForCreate:self.rm_calls = []self.content = {}self.existing_dirs = set({root_uri} if existing_dirs is None else existing_dirs)+ self._async_agfs = _FakePathLock()async def stat(self, uri: str, ctx=None):del ctx@@ -759,9 +733,17 @@ class _FakeVikingFSForCreate:del ctxself.delete_temp_calls.append(temp_uri)- async def write_file(self, uri: str, content: str, *, ctx=None, lock_handle=None):+ async def write_file(+ self,+ uri: str,+ content: str,+ *,+ ctx=None,+ lock_handle=None,+ lease_ref=None,+ ):del ctx- self.write_file_calls.append((uri, content, lock_handle))+ self.write_file_calls.append((uri, content, lease_ref or lock_handle))self.content[uri] = contentparent = uri.rsplit("/", 1)[0]while parent.startswith("viking://") and parent not in self.existing_dirs:@@ -770,8 +752,8 @@ class _FakeVikingFSForCreate:breakparent = parent.rsplit("/", 1)[0]- async def rm(self, uri: str, *, ctx=None, lock_handle=None):- del ctx, lock_handle+ async def rm(self, uri: str, *, ctx=None, lock_handle=None, lease_ref=None):+ del ctx, lock_handle, lease_refself.rm_calls.append(uri)self.content.pop(uri, None)@@ -786,14 +768,11 @@ async def test_create_mode_new_file_success(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)write_calls = []- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del mode, ctx, lock_handle, lease_refwrite_calls.append((uri, content))return content@@ -824,15 +803,12 @@ async def test_create_mode_canonicalizes_user_shorthand_memory_uri(monkeypatch):file_exists=False,)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)write_calls = []refresh_calls = []- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del mode, ctx, lock_handle, lease_refwrite_calls.append((uri, content))return content@@ -870,8 +846,8 @@ async def test_create_mode_existing_file_raises_409(monkeypatch):viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=True)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del uri, content, mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del uri, content, mode, ctx, lock_handle, lease_refreturn Noneasync def _fake_wait_for_queues(*, timeout):@@ -893,8 +869,8 @@ async def test_create_mode_invalid_extension_raises_400(monkeypatch):viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del uri, content, mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del uri, content, mode, ctx, lock_handle, lease_refreturn Noneasync def _fake_wait_for_queues(*, timeout):@@ -915,14 +891,11 @@ async def test_create_mode_parent_dirs_auto_created(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)write_calls = []- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del mode, ctx, lock_handle, lease_refwrite_calls.append((uri, content))return content@@ -953,16 +926,11 @@ async def test_create_mode_valid_extensions_pass(monkeypatch):root_uri = "viking://user/default/memories"viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()- _captured_lock = lock_manager-- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager", lambda _l=_captured_lock: _l- )-- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del uri, mode, ctx, lock_handle+ async def _fake_write_in_place(+ uri, content, *, mode, ctx, lock_handle=None, lease_ref=None+ ):+ del uri, mode, ctx, lock_handle, lease_refreturn contentasync def _fake_wait_for_queues(*, timeout):@@ -985,12 +953,9 @@ async def test_create_mode_memory_scope(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):- del uri, mode, ctx, lock_handle+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):+ del uri, mode, ctx, lock_handle, lease_refreturn contentrefresh_calls = []@@ -1024,9 +989,6 @@ async def test_create_mode_resource_scope(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)async def _fake_enqueue_semantic_refresh(**kwargs):# Verify resource-scope URIs take the resource write path@@ -1106,14 +1068,11 @@ async def test_create_mode_regression_replace_unchanged(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=True)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):# Verify mode="replace" still worksassert mode == "replace"- del uri, content, ctx, lock_handle+ del uri, content, ctx, lock_handle, lease_refreturn Noneasync def _fake_wait_for_queues(*, timeout):@@ -1137,14 +1096,11 @@ async def test_create_mode_regression_append_unchanged(monkeypatch):ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=True)coordinator = ContentWriteCoordinator(viking_fs=viking_fs)- lock_manager = _FakeLockManager()-- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):# Verify mode="append" still worksassert mode == "append"- del uri, content, ctx, lock_handle+ del uri, content, ctx, lock_handle, lease_refreturn Noneasync def _fake_wait_for_queues(*, timeout):diff --git a/tests/server/test_request_wait_tracking.py b/tests/server/test_request_wait_tracking.pyindex 3309da21d..d654e1de6 100644--- a/tests/server/test_request_wait_tracking.py+++ b/tests/server/test_request_wait_tracking.py@@ -47,6 +47,10 @@ class _FakeVikingFS:self._file_uri = file_uriself._root_uri = root_uriself.content = {file_uri: "original"}+ self._async_agfs = SimpleNamespace(+ pathlock_acquire_exact=lambda lock_path: SimpleNamespace(id="lock-1"),+ pathlock_release=lambda lease: None,+ )async def stat(self, uri: str, ctx=None):del ctx@@ -68,12 +72,12 @@ class _FakeVikingFS:del ctxreturn self.content[uri]- async def write_file(self, uri: str, content: str, ctx=None):- del ctx+ async def write_file(self, uri: str, content: str, ctx=None, lease_ref=None):+ del ctx, lease_refself.content[uri] = content- async def rm(self, uri: str, ctx=None, lock_handle=None):- del ctx, lock_handle+ async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):+ del ctx, lock_handle, lease_refself.content.pop(uri, None)@@ -263,16 +267,7 @@ async def test_content_write_wait_uses_request_tracker(monkeypatch):coordinator = ContentWriteCoordinator(viking_fs=_FakeVikingFS(file_uri=file_uri, root_uri=root_uri))- lock_manager = SimpleNamespace(- create_handle=lambda: SimpleNamespace(id="lock-1"),- acquire_exact_path=lambda handle, path: _return_true(handle, path),- release=lambda handle: _return_none(handle),- )- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )monkeypatch.setattr("openviking.storage.content_write.get_request_wait_tracker",lambda: tracker,@@ -323,16 +318,7 @@ async def test_content_write_wait_uses_request_tracker_when_telemetry_disabled(mcoordinator = ContentWriteCoordinator(viking_fs=_FakeVikingFS(file_uri=file_uri, root_uri=root_uri))- lock_manager = SimpleNamespace(- create_handle=lambda: SimpleNamespace(id="lock-1"),- acquire_exact_path=lambda handle, path: _return_true(handle, path),- release=lambda handle: _return_none(handle),- )- monkeypatch.setattr(- "openviking.storage.content_write.get_lock_manager",- lambda: lock_manager,- )monkeypatch.setattr("openviking.storage.content_write.get_request_wait_tracker",lambda: tracker,diff --git a/tests/service/test_reindex_file_lock.py b/tests/service/test_reindex_file_lock.pyindex 8ca48f7cb..bd568f7bf 100644--- a/tests/service/test_reindex_file_lock.py+++ b/tests/service/test_reindex_file_lock.py@@ -8,7 +8,6 @@ from unittest.mock import AsyncMockfrom openviking.server.identity import RequestContext, Rolefrom openviking.service import reindex_executor as reindex_modulefrom openviking.service.reindex_executor import ReindexExecutor-from openviking.storage.transaction import init_lock_manager, release_all_locks, reset_lock_managerfrom openviking_cli.session.user_id import UserIdentifier@@ -39,7 +38,6 @@ async def test_reindex_single_file_uri_acquires_tree_lock_without_not_a_directoruri = "viking://resources/profile.md"path = f"{test_dir}/profile.md"agfs_client.write(path, b"# Profile\nSingle file reindex source.\n")- init_lock_manager(agfs_client)viking_fs = _FakeVikingFS(uri, path)service = SimpleNamespace(@@ -65,8 +63,7 @@ async def test_reindex_single_file_uri_acquires_tree_lock_without_not_a_directorctx=ctx,)finally:- await release_all_locks()- reset_lock_manager()+ passassert result["status"] == "completed"assert result["uri"] == uridiff --git a/tests/service/test_resource_service_understanding_routing.py b/tests/service/test_resource_service_understanding_routing.pyindex 25ccbfe96..b352b6f81 100644--- a/tests/service/test_resource_service_understanding_routing.py+++ b/tests/service/test_resource_service_understanding_routing.py@@ -14,6 +14,7 @@ from openviking_cli.session.user_id import UserIdentifierdef mpeg_ts_probe() -> bytes:+ """Build a minimal MPEG-TS probe payload for routing tests."""content = bytearray(MPEG_TS_PROBE_BYTES)for offset in range(0, MPEG_TS_PROBE_BYTES, MPEG_TS_PACKET_SIZE):content[offset] = 0x47@@ -25,6 +26,7 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(monkeypatch,tmp_path,):+ """Queue understanding ingestion for extensionless remote URLs after prepare."""ctx = RequestContext(user=UserIdentifier("acct", "alice"),role=Role.USER,@@ -42,10 +44,11 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(},is_temporary=True,)- lock = SimpleNamespace(- to_handoff=lambda: SimpleNamespace(to_dict=lambda: {"handle_id": "lock-1"}),- handoff=AsyncMock(),- close=AsyncMock(),+ lock = {"lease_ref": "lock-1"}+ agfs = SimpleNamespace(+ pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),+ pathlock_handoff=AsyncMock(),+ pathlock_release=AsyncMock(),)processor = SimpleNamespace(understanding_api_enabled=lambda: True,@@ -66,7 +69,7 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route()service = ResourceService(vikingdb=object(),- viking_fs=object(),+ viking_fs=SimpleNamespace(_async_agfs=agfs),resource_processor=processor,skill_processor=object(),)@@ -86,10 +89,6 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route("openviking.storage.queuefs.get_queue_manager",lambda: queue_manager,)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: object(),- )result = await service.add_resource(path="https://example.com/download?id=1",@@ -114,7 +113,8 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(assert not downloaded.exists()processor.submit_understanding.assert_awaited_once_with(prepared)processor.process_resource.assert_not_awaited()- lock.handoff.assert_awaited_once()+ agfs.pathlock_to_handoff.assert_awaited_once_with(lock)+ agfs.pathlock_handoff.assert_awaited_once_with(lock)@pytest.mark.asyncio@@ -122,6 +122,7 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(monkeypatch,tmp_path,):+ """Route MPEG-TS resources to understanding with video target resolution."""ctx = RequestContext(user=UserIdentifier("acct", "alice"),role=Role.USER,@@ -139,10 +140,11 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(},is_temporary=True,)- lock = SimpleNamespace(- to_handoff=lambda: SimpleNamespace(to_dict=lambda: {"handle_id": "lock-1"}),- handoff=AsyncMock(),- close=AsyncMock(),+ lock = {"lease_ref": "lock-1"}+ agfs = SimpleNamespace(+ pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),+ pathlock_handoff=AsyncMock(),+ pathlock_release=AsyncMock(),)resolve_target_uri = AsyncMock(return_value=(@@ -164,7 +166,7 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare()service = ResourceService(vikingdb=object(),- viking_fs=object(),+ viking_fs=SimpleNamespace(_async_agfs=agfs),resource_processor=processor,skill_processor=object(),)@@ -184,10 +186,6 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare("openviking.storage.queuefs.get_queue_manager",lambda: queue_manager,)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: object(),- )result = await service.add_resource(path="https://example.com/video/sample.ts?sign=1",@@ -214,4 +212,5 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(assert queued.understanding_response_id == "response-1"assert queued.source_name == "sample.ts"assert not downloaded.exists()- lock.handoff.assert_awaited_once()+ agfs.pathlock_to_handoff.assert_awaited_once_with(lock)+ agfs.pathlock_handoff.assert_awaited_once_with(lock)diff --git a/tests/service/test_resource_service_watch.py b/tests/service/test_resource_service_watch.pyindex ea555d84c..b12295753 100644--- a/tests/service/test_resource_service_watch.py+++ b/tests/service/test_resource_service_watch.py@@ -835,6 +835,9 @@ class TestResourceProcessingIndependence:skill_processor=MockSkillProcessor(),watch_scheduler=scheduler,)+ service._enqueue_add_resource_job = AsyncMock(+ return_value=SimpleNamespace(task_id="test-task")+ )result = await service.add_resource(path="/test/path",@@ -856,6 +859,9 @@ class TestResourceProcessingIndependence:skill_processor=MockSkillProcessor(),watch_scheduler=None,)+ service._enqueue_add_resource_job = AsyncMock(+ return_value=SimpleNamespace(task_id="test-task")+ )result = await service.add_resource(path="/test/path",diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.pyindex c17f0e9dd..522327bab 100644--- a/tests/session/memory/test_compressor_v2.py+++ b/tests/session/memory/test_compressor_v2.py@@ -477,8 +477,6 @@ class TestCompressorV2:with (patch("openviking.storage.viking_fs.get_viking_fs", return_value=None),- patch("openviking.storage.transaction.init_lock_manager"),- patch("openviking.storage.transaction.get_lock_manager", return_value=None),patch("openviking.session.memory.memory_type_registry.create_default_registry",return_value=dummy_registry,@@ -513,8 +511,6 @@ class TestCompressorV2:with (patch("openviking.storage.viking_fs.get_viking_fs", return_value=None),- patch("openviking.storage.transaction.init_lock_manager"),- patch("openviking.storage.transaction.get_lock_manager", return_value=None),patch("openviking.session.memory.memory_type_registry.create_default_registry",return_value=dummy_registry,@@ -586,8 +582,6 @@ class TestCompressorV2:with (patch("openviking.session.compressor_v2.get_viking_fs", return_value=MockVikingFS()),- patch("openviking.storage.transaction.init_lock_manager"),- patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager),patch("openviking.session.memory.memory_type_registry.create_default_registry",return_value=SimpleNamespace(initialize_memory_files=AsyncMock()),@@ -682,12 +676,6 @@ class TestCompressorV2:async def release(_handle):events.append("release")- lock_manager = SimpleNamespace(- create_handle=lambda: handle,- acquire_exact_tree_batch=AsyncMock(side_effect=acquire_exact_tree_batch),- release=AsyncMock(side_effect=release),- )-async def post_apply(result, inheritance_map, lock_handle):assert result.written_uris == ["viking://user/default/memories/experiences/debug.md"]assert inheritance_map == {}@@ -698,8 +686,6 @@ class TestCompressorV2:patch("openviking.session.compressor_v2.get_viking_fs", return_value=FakeVikingFS()),patch("openviking.session.compressor_v2.get_openviking_config", return_value=config),patch("openviking.session.compressor_v2.ExtractLoop", DummyExtractLoop),- patch("openviking.storage.transaction.init_lock_manager"),- patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager),patch.object(compressor, "_get_or_create_updater", return_value=DummyUpdater()),):result = await compressor._run_extract_phase(@@ -747,8 +733,6 @@ class TestCompressorV2:events.append("write")self.files[uri] = content- handle = SimpleNamespace(id="handle-1", locks=[])-async def acquire_exact_path_batch(_handle, paths):events.append(f"exact:{paths[0]}")return True@@ -756,14 +740,9 @@ class TestCompressorV2:async def release(_handle):events.append("release")- lock_manager = SimpleNamespace(- create_handle=lambda: handle,- acquire_exact_path_batch=AsyncMock(side_effect=acquire_exact_path_batch),- release=AsyncMock(side_effect=release),- )viking_fs = FakeVikingFS()- with patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager):+ with patch("openviking.session.compressor_v2.get_viking_fs", return_value=viking_fs):await compressor._append_trajectories_to_experiences([exp_uri],[traj_uri],diff --git a/tests/session/memory/test_memory_updater.py b/tests/session/memory/test_memory_updater.pyindex 62cef1c13..a1217a21b 100644--- a/tests/session/memory/test_memory_updater.py+++ b/tests/session/memory/test_memory_updater.py@@ -174,7 +174,6 @@ class TestMemoryUpdater:@pytest.mark.asyncioasync def test_generate_overview_deletes_empty_overview_via_rm(self):- lock_handle = object()schema = MemoryTypeSchema(memory_type="entities",description="entity memory",@@ -193,11 +192,11 @@ class TestMemoryUpdater:async def ls(self, uri, show_all_hidden=False, ctx=None):return [{"name": ".overview.md", "isDir": False}]- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):- self.rm_calls.append((uri, recursive, lock_handle))+ async def rm(self, uri, recursive=False, ctx=None):+ self.rm_calls.append((uri, recursive))viking_fs = FakeVikingFS()- updater = MemoryUpdater(registry=registry, transaction_handle=lock_handle)+ updater = MemoryUpdater(registry=registry)updater._get_viking_fs = MagicMock(return_value=viking_fs)ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)@@ -211,9 +210,8 @@ class TestMemoryUpdater:("viking://user/alice/memories/entities/动漫角色/.overview.md",False,- lock_handle,),- ("viking://user/alice/memories/entities/动漫角色", True, lock_handle),+ ("viking://user/alice/memories/entities/动漫角色", True),]@pytest.mark.asyncio@@ -236,7 +234,7 @@ class TestMemoryUpdater:async def ls(self, uri, show_all_hidden=False, ctx=None):raise NotFoundError(uri, "directory")- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):+ async def rm(self, uri, recursive=False, ctx=None):self.rm_calls.append((uri, recursive))viking_fs = FakeVikingFS()@@ -308,7 +306,7 @@ class TestMemoryUpdater:async def read_file(self, uri, ctx=None):return self.store[uri]- async def write_file(self, uri, content, ctx=None, lock_handle=None):+ async def write_file(self, uri, content, ctx=None):self.store[uri] = contentviking_fs = FakeVikingFS()@@ -353,7 +351,7 @@ class TestMemoryUpdater:async def read_file(self, uri, ctx=None):return self.store[uri]- async def write_file(self, uri, content, ctx=None, lock_handle=None):+ async def write_file(self, uri, content, ctx=None):self.store[uri] = contentviking_fs = FakeVikingFS()@@ -467,8 +465,7 @@ class TestMemoryUpdater:assert error_target == "events(page_id=102)"assert str(error) == "Missing resolved URI"tracer_error.assert_called_once_with(- "Skipping unresolved memory operation: "- "events(page_id=102): Missing resolved URI"+ "Skipping unresolved memory operation: events(page_id=102): Missing resolved URI")@pytest.mark.asyncio@@ -510,9 +507,7 @@ class TestMemoryUpdater:page_id=102,),],- delete_file_contents=[- MemoryFile(uri=old_uri, extra_fields={"memory_type": "events"})- ],+ delete_file_contents=[MemoryFile(uri=old_uri, extra_fields={"memory_type": "events"})],errors=[],)ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)@@ -1084,18 +1079,14 @@ class TestApplyEditWithSearchReplacePatch:@pytest.mark.asyncioasync def test_apply_upsert_persists_last_update_trace_id(self):- lock_handle = object()updater = self._make_updater_with_registry()- updater._transaction_handle = lock_handlemock_viking_fs = MagicMock()mock_viking_fs.read_file = AsyncMock(side_effect=FileNotFoundError("missing"))written_content = None- write_kwargs = Noneasync def mock_write_file(uri, content, **kwargs):- nonlocal write_kwargs, written_content+ nonlocal written_contentwritten_content = content- write_kwargs = kwargsmock_viking_fs.write_file = mock_write_fileupdater._get_viking_fs = MagicMock(return_value=mock_viking_fs)@@ -1109,7 +1100,6 @@ class TestApplyEditWithSearchReplacePatch:await updater._apply_upsert(op, MagicMock())assert written_content is not None- assert write_kwargs["lock_handle"] is lock_handleresult = MemoryFileUtils.read(written_content)assert result.extra_fields["source_extraction_id"] == "extract_1"assert result.extra_fields["last_update_trace_id"] == "trace_1"diff --git a/tests/session/test_session_commit.py b/tests/session/test_session_commit.pyindex 04ed3b851..90d8ce8a5 100644--- a/tests/session/test_session_commit.py+++ b/tests/session/test_session_commit.py@@ -8,14 +8,11 @@ import jsonfrom types import SimpleNamespacefrom unittest.mock import AsyncMock, MagicMock-import pytest-from openviking import AsyncOpenVikingfrom openviking.client.session import Session as ClientSessionfrom openviking.message import TextPartfrom openviking.service.task_tracker import get_task_trackerfrom openviking.session import Session-from openviking.storage.transaction import get_lock_managerasync def _wait_for_task(task_id: str, timeout: float = 30.0) -> dict:@@ -689,20 +686,3 @@ class TestCommit:session.add_message("user", [TextPart("Second round message")])second = await session.commit_async()assert second["status"] == "accepted"-- async def test_commit_skips_redo_when_recovery_disabled(- self, session_with_messages: Session, monkeypatch: pytest.MonkeyPatch- ):- """Phase 2 should not write or clear redo markers when redo recovery is disabled."""-- redo_log = MagicMock()- lock_manager = get_lock_manager()- monkeypatch.setattr(lock_manager, "_redo_recovery_enabled", False)- monkeypatch.setattr(lock_manager, "_redo_log", redo_log)-- result = await session_with_messages.commit_async()- task_result = await _wait_for_task(result["task_id"])-- assert task_result["status"] == "completed"- redo_log.write_pending.assert_not_called()- redo_log.mark_done.assert_not_called()diff --git a/tests/session/train/test_fakes.py b/tests/session/train/test_fakes.pyindex a108f8432..cbcdd09cd 100644--- a/tests/session/train/test_fakes.py+++ b/tests/session/train/test_fakes.py@@ -9,7 +9,7 @@ from typing import Anyclass InMemoryAGFS:- """Tiny synchronous AGFS fake with enough semantics for PathLockEngine."""+ """Tiny synchronous AGFS fake for training integration tests."""def __init__(self, files: dict[str, str] | None = None):self.files: dict[str, bytes] = {}diff --git a/tests/session/train/test_policy_optimization_real_llm_e2e.py b/tests/session/train/test_policy_optimization_real_llm_e2e.pyindex c67ea77cd..53c63465e 100644--- a/tests/session/train/test_policy_optimization_real_llm_e2e.py+++ b/tests/session/train/test_policy_optimization_real_llm_e2e.py@@ -30,7 +30,6 @@ from openviking.session.train import (TrajectoryRolloutAnalyzer,)from openviking.session.train.components.gradient_estimator import ExperienceGradientEstimator-from openviking.storage.transaction import init_lock_manager, reset_lock_managerfrom openviking.telemetry import start_current_span, tracerfrom openviking.telemetry.tracer import init_tracer_from_server_configfrom openviking_cli.utils.config import get_openviking_config@@ -534,10 +533,11 @@ def _print_iterative_real_llm_summary(tracer.info("\n".join(lines), console=True)-def _patch_experience_prefetch(- monkeypatch, fs: InMemoryVikingFS, experience_uri: str-) -> None:+def _patch_experience_prefetch(monkeypatch, fs: InMemoryVikingFS, experience_uri: str) -> None:+ """Patch experience prefetch so the test reads from the in-memory filesystem."""+async def search_files(self, query, search_uris=None, limit=5):+ del self, query, search_uris, limitreturn [experience_uri]async def read_file(self, uri):@@ -603,8 +603,6 @@ async def _run_policy_optimization_pipeline_real_config_llm_e2e_writes_updated_e)})- reset_lock_manager()- init_lock_manager(fs.agfs, redo_recovery_enabled=False)request_context = SimpleNamespace(user=SimpleNamespace(account_id="default", user_id="u"),account_id="default",@@ -673,14 +671,10 @@ async def _run_policy_optimization_pipeline_real_config_llm_e2e_writes_updated_eassert trajectory_content.strip()assert gradient.after_file.plain_content().strip()assert all(epoch.apply_result.errors == [] for epoch in result.epochs)- written_uris = [- uri for epoch in result.epochs for uri in epoch.apply_result.written_uris- ]+ written_uris = [uri for epoch in result.epochs for uri in epoch.apply_result.written_uris]assert experience_uri in written_urisassert result.plan.metadata["optimizer"] == "patch_merge"- assert any(- epoch.plan.metadata.get("optimizer") == "patch_merge" for epoch in result.epochs- )+ assert any(epoch.plan.metadata.get("optimizer") == "patch_merge" for epoch in result.epochs)assert len(result.epochs) == 4assert result.evaluation_passes == []assert final_evaluation.metadata["score"] > result.metadata["first_score"]@@ -725,8 +719,6 @@ async def test_experience_gradient_estimator_real_config_llm_generates_gradient(),})- reset_lock_manager()- init_lock_manager(fs.agfs, redo_recovery_enabled=False)request_context = SimpleNamespace(user=SimpleNamespace(account_id="default", user_id="u"),account_id="default",diff --git a/tests/session/train/test_train_framework.py b/tests/session/train/test_train_framework.pyindex c3f09f4af..6b7f4ce62 100644--- a/tests/session/train/test_train_framework.py+++ b/tests/session/train/test_train_framework.py@@ -10,7 +10,7 @@ from pathlib import Pathfrom typing import Anyimport pytest-from test_fakes import InMemoryAGFS, fake_request_context+from test_fakes import fake_request_contextfrom openviking.message import Message, TextPartfrom openviking.session.memory.dataclass import StoredLink@@ -34,15 +34,6 @@ from openviking.session.train import (Trajectory,)from openviking.session.train.components.reporter import ConsolePipelineReporter-from openviking.storage.transaction import init_lock_manager, reset_lock_manager--[email protected](autouse=True)-def _train_lock_manager():- reset_lock_manager()- init_lock_manager(InMemoryAGFS(), redo_recovery_enabled=False)- yield- reset_lock_manager()def _case() -> Case:@@ -463,7 +454,9 @@ async def test_training_updates_execution_metadata_epoch_each_epoch():policy_optimizer=DummyOptimizer(),policy_updater=DummyUpdater(),)- context = PipelineContext(max_epochs=2, execution_metadata={"rollout_stage": "eval_train_rollout"})+ context = PipelineContext(+ max_epochs=2, execution_metadata={"rollout_stage": "eval_train_rollout"}+ )result = await pipeline.train(case_loader=ListCaseLoader([_case()]),@@ -499,9 +492,10 @@ async def test_train_runs_test_eval_after_each_epoch_when_configured():assert [item.epoch for item in result.evaluation_passes] == [0, 1]assert result.metadata["evaluation_pass_count"] == 2- assert [- item.metadata.get("rollout_stage") for item in result.evaluation_passes- ] == ["test_rollout", "test_rollout"]+ assert [item.metadata.get("rollout_stage") for item in result.evaluation_passes] == [+ "test_rollout",+ "test_rollout",+ ]assert [item.metadata.get("eval_split") for item in result.evaluation_passes] == ["test","test",@@ -552,6 +546,7 @@ async def test_offline_policy_optimization_pipeline_epoch_hook_can_stop_trainingpolicy_optimizer=DummyOptimizer(),policy_updater=DummyUpdater(),)+class StopTrainingHook(NoopPipelineLifecycleHook):def __init__(self):self.epochs: list[int] = []@@ -871,12 +866,8 @@ async def test_streaming_policy_trainer_scopes_concurrent_submit_results_by_sourassert {item.target_name for item in first.batch_result.plan.items} == {"case_a", "case_b"}assert [item.target_name for item in first.plan.items] == ["case_a"]assert [item.target_name for item in second.plan.items] == ["case_b"]- assert first.apply_result.written_uris == [- "viking://user/u/memories/experiences/case_a.md"- ]- assert second.apply_result.written_uris == [- "viking://user/u/memories/experiences/case_b.md"- ]+ assert first.apply_result.written_uris == ["viking://user/u/memories/experiences/case_a.md"]+ assert second.apply_result.written_uris == ["viking://user/u/memories/experiences/case_b.md"]assert await trainer.close() is None@@ -1121,6 +1112,7 @@ async def test_get_streaming_policy_trainer_returns_process_global_instance():assert second is firstassert first.config.max_gradients_per_update == 3+class FakeSessionCommitClient:def __init__(self):self.created_sessions = []@@ -1579,12 +1571,7 @@ def test_rollout_artifact_event_recorder_enriches_commit_result(tmp_path):/ "trial_0")commit_dir = (- tmp_path- / "rollouts"- / "airline_train_task_7_task-7"- / "epoch_0"- / "2.train"- / "trial_0"+ tmp_path / "rollouts" / "airline_train_task_7_task-7" / "epoch_0" / "2.train" / "trial_0")assert not (rollout_dir / "commit_result.json").exists()commit_result = json.loads((commit_dir / "commit_result.json").read_text())@@ -1608,22 +1595,22 @@ async def test_rollout_artifact_recorder_writes_epoch_commit_artifacts_under_comclass CommitArtifactClient:async def read(self, uri):assert uri == "viking://archive/memory_diff.json"- return json.dumps({- "operations": {- "adds": [- {"uri": "viking://memory/new.md", "after": "# New\nbody"}- ],- "updates": [- {- "uri": "viking://memory/old.md",- "before": "# Old\nbody",- "after": "# Old\nnew body",- }- ],- "deletes": [],- },- "summary": {"total_adds": 1, "total_updates": 1, "total_deletes": 0},- })+ return json.dumps(+ {+ "operations": {+ "adds": [{"uri": "viking://memory/new.md", "after": "# New\nbody"}],+ "updates": [+ {+ "uri": "viking://memory/old.md",+ "before": "# Old\nbody",+ "after": "# Old\nnew body",+ }+ ],+ "deletes": [],+ },+ "summary": {"total_adds": 1, "total_updates": 1, "total_deletes": 0},+ }+ )recorder = RolloutArtifactRecorder(run_dir=tmp_path, client=CommitArtifactClient())case = Case(@@ -1671,12 +1658,7 @@ async def test_rollout_artifact_recorder_writes_epoch_commit_artifacts_under_com/ "trial_0")commit_dir = (- tmp_path- / "rollouts"- / "airline_train_task_7_task-7"- / "epoch_0"- / "2.train"- / "trial_0"+ tmp_path / "rollouts" / "airline_train_task_7_task-7" / "epoch_0" / "2.train" / "trial_0")assert (train_dir / "status.json").exists()assert not (train_dir / "commit_result.json").exists()diff --git a/tests/storage/test_ingest_ls_node_limit.py b/tests/storage/test_ingest_ls_node_limit.pyindex bfbf6c714..08cbb637f 100644--- a/tests/storage/test_ingest_ls_node_limit.py+++ b/tests/storage/test_ingest_ls_node_limit.py@@ -18,7 +18,6 @@ from __future__ import annotationsimport pytestfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor-from openviking.storage.transaction import NO_LOCKclass _TruncatingVikingFS:@@ -43,16 +42,16 @@ class _TruncatingVikingFS:entries = self._children if uri == self.TEMP else []return entries[:node_limit] # the real ls truncates here- async def mv(self, src, dst, ctx=None, lock_handle=None):+ async def mv(self, src, dst, ctx=None, lease_ref=None):self.moved.append((src, dst))- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):+ async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):pass- async def mkdir(self, uri, exist_ok=False, ctx=None):+ async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):pass- async def delete_temp(self, uri, ctx=None):+ async def delete_temp(self, uri, ctx=None, lease_ref=None):pass@@ -68,7 +67,7 @@ async def test_sync_materializes_all_children_above_default_node_limit(monkeypatdiff = await SemanticProcessor()._sync_topdown_recursive(_TruncatingVikingFS.TEMP,_TruncatingVikingFS.TARGET,- lock=NO_LOCK,+ lock=None,)assert len(fake.moved) == n_children, (diff --git a/tests/storage/test_lock_observer.py b/tests/storage/test_lock_observer.pydeleted file mode 100644index 84580886d..000000000--- a/tests/storage/test_lock_observer.py+++ /dev/null@@ -1,51 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for lock observer activity tracking."""--from unittest.mock import MagicMock--from openviking.storage.observers.lock_observer import LockObserver-from openviking.storage.transaction.lock_handle import LockHandle---def _make_handle(handle_id: str, created_at: float, last_active_at: float) -> LockHandle:- handle = LockHandle(id=handle_id)- handle.created_at = created_at- handle.last_active_at = last_active_at- handle.add_lock(f"/local/{handle_id}/.path.ovlock")- return handle---def test_get_hanging_locks_uses_idle_time(monkeypatch):- active_handle = _make_handle("active", created_at=0.0, last_active_at=900.0)- stale_handle = _make_handle("stale", created_at=0.0, last_active_at=100.0)-- manager = MagicMock()- manager.get_active_handles.return_value = {- active_handle.id: active_handle,- stale_handle.id: stale_handle,- }-- monkeypatch.setattr("openviking.storage.observers.lock_observer.time.time", lambda: 1000.0)-- observer = LockObserver(manager)- active_locks = observer.get_active_locks()- active_info = next(lock for lock in active_locks if lock["id"] == active_handle.id)-- assert active_info["duration_seconds"] == 1000.0- assert active_info["idle_seconds"] == 100.0- assert [lock["id"] for lock in observer.get_hanging_locks(600)] == [stale_handle.id]---def test_health_checks_ignore_long_running_but_active_lock(monkeypatch):- active_handle = _make_handle("active", created_at=0.0, last_active_at=950.0)-- manager = MagicMock()- manager.get_active_handles.return_value = {active_handle.id: active_handle}-- monkeypatch.setattr("openviking.storage.observers.lock_observer.time.time", lambda: 1000.0)-- observer = LockObserver(manager)-- assert observer.is_healthy() is True- assert observer.has_errors() is Falsediff --git a/tests/storage/test_memory_semantic_stall.py b/tests/storage/test_memory_semantic_stall.pyindex ef6f58e92..628851c62 100644--- a/tests/storage/test_memory_semantic_stall.py+++ b/tests/storage/test_memory_semantic_stall.py@@ -15,17 +15,6 @@ from openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor-class _NoopLockContext:- def __init__(self, *args, **kwargs):- pass-- async def __aenter__(self):- return self-- async def __aexit__(self, exc_type, exc, tb):- return False--def _make_msg(uri="viking://user/memories", context_type="memory", **kwargs):"""Build a minimal SemanticMsg for testing."""defaults = {@@ -241,7 +230,6 @@ async def test_memory_write_error_reports_error():"openviking.storage.queuefs.semantic_processor.resolve_telemetry",return_value=None,),- patch("openviking.storage.transaction.LockContext", _NoopLockContext),patch.object(processor,"_generate_single_file_summary",diff --git a/tests/storage/test_semantic_dag_incremental.py b/tests/storage/test_semantic_dag_incremental.pyindex ab69653b8..38527ed54 100644--- a/tests/storage/test_semantic_dag_incremental.py+++ b/tests/storage/test_semantic_dag_incremental.py@@ -11,22 +11,6 @@ from openviking.storage.queuefs.semantic_dag import SemanticDagExecutorfrom openviking_cli.session.user_id import UserIdentifier-def _mock_transaction_layer(monkeypatch):- mock_handle = MagicMock()- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aenter__",- AsyncMock(return_value=mock_handle),- )- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aexit__",- AsyncMock(return_value=False),- )- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: MagicMock(),- )--class _FakeVikingFS:def __init__(self, tree, file_contents):self._tree = {self._norm(k): v for k, v in tree.items()}@@ -110,7 +94,6 @@ class _FakeProcessor:@pytest.mark.asyncioasync def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypatch):- _mock_transaction_layer(monkeypatch)root_uri = "viking://resources/root"tree = {diff --git a/tests/storage/test_semantic_dag_skip_files.py b/tests/storage/test_semantic_dag_skip_files.pyindex 69448e97d..a195a4210 100644--- a/tests/storage/test_semantic_dag_skip_files.py+++ b/tests/storage/test_semantic_dag_skip_files.py@@ -1,8 +1,6 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-from unittest.mock import AsyncMock, MagicMock-import pytestfrom openviking.server.identity import RequestContext, Role@@ -10,23 +8,6 @@ from openviking.storage.queuefs.semantic_dag import SemanticDagExecutorfrom openviking_cli.session.user_id import UserIdentifier-def _mock_transaction_layer(monkeypatch):- """Patch lock layer to no-op for DAG tests."""- mock_handle = MagicMock()- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aenter__",- AsyncMock(return_value=mock_handle),- )- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aexit__",- AsyncMock(return_value=False),- )- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: MagicMock(),- )--class _FakeVikingFS:def __init__(self, tree):self._tree = tree@@ -93,7 +74,6 @@ class _DummyTracker:)async def test_messages_jsonl_excluded_from_summary(monkeypatch, root_uri):"""messages.jsonl should be skipped by _list_dir and never summarized."""- _mock_transaction_layer(monkeypatch)tree = {root_uri: [{"name": "messages.jsonl", "isDir": False},@@ -134,7 +114,6 @@ async def test_messages_jsonl_excluded_from_summary(monkeypatch, root_uri):)async def test_messages_jsonl_excluded_in_subdirectory(monkeypatch, root_uri):"""messages.jsonl in a subdirectory should also be skipped."""- _mock_transaction_layer(monkeypatch)tree = {root_uri: [{"name": "subdir", "isDir": True},diff --git a/tests/storage/test_semantic_dag_stats.py b/tests/storage/test_semantic_dag_stats.pyindex 31b057edf..aec37012c 100644--- a/tests/storage/test_semantic_dag_stats.py+++ b/tests/storage/test_semantic_dag_stats.py@@ -2,7 +2,6 @@# SPDX-License-Identifier: AGPL-3.0import asyncio-from unittest.mock import AsyncMock, MagicMockimport pytest@@ -107,21 +106,6 @@ async def test_semantic_dag_stats_collects_nodes(monkeypatch):lambda: _DummyTracker(),)- # Mock lock layer: LockContext as no-op passthrough- mock_handle = MagicMock()- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aenter__",- AsyncMock(return_value=mock_handle),- )- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aexit__",- AsyncMock(return_value=False),- )- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: MagicMock(),- )-processor = _FakeProcessor()ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)executor = SemanticDagExecutor(@@ -141,7 +125,11 @@ async def test_semantic_dag_stats_collects_nodes(monkeypatch):assert stats.in_progress_nodes == 0assert processor.vectorized_dirs == [f"{root_uri}/child", root_uri]assert sorted(processor.vectorized_files) == sorted(- [f"{root_uri}/a.txt", f"{root_uri}/b.txt", f"{root_uri}/child/c.txt"]+ [+ f"{root_uri}/a.txt",+ f"{root_uri}/b.txt",+ f"{root_uri}/child/c.txt",+ ])@@ -243,20 +231,6 @@ async def test_semantic_dag_skip_vectorization_does_not_schedule_tasks(monkeypatlambda: tracker,)- mock_handle = MagicMock()- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aenter__",- AsyncMock(return_value=mock_handle),- )- monkeypatch.setattr(- "openviking.storage.transaction.lock_context.LockContext.__aexit__",- AsyncMock(return_value=False),- )- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: MagicMock(),- )-processor = _FakeProcessor()ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)executor = SemanticDagExecutor(diff --git a/tests/storage/test_semantic_processor_lock_ownership.py b/tests/storage/test_semantic_processor_lock_ownership.pyindex 267ec7fe2..09d3f5b3c 100644--- a/tests/storage/test_semantic_processor_lock_ownership.py+++ b/tests/storage/test_semantic_processor_lock_ownership.py@@ -5,280 +5,55 @@ from __future__ import annotationsimport pytest-from openviking.storage.errors import LockAcquisitionError-from openviking.storage.queuefs.semantic_dag import DagStats-from openviking.storage.queuefs.semantic_lock import SemanticLockScopefrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor-from openviking.storage.transaction import BorrowedLockLease, LockHandoffRef-class _FakeHandle:- def __init__(self, handle_id: str):- self.id = handle_id- self.locks = ["/fake/root/.path.ovlock"]+class _FakePathLock:+ """Mock for _async_agfs pathlock operations."""--class _FakeLockManager:def __init__(self):- self._handles = {"lock-1": _FakeHandle("lock-1")}- self.release_calls = []-- def get_handle(self, handle_id: str):- return self._handles.get(handle_id)-- async def release(self, handle):- self.release_calls.append(handle.id)- self._handles.pop(handle.id, None)-- def create_handle(self):- handle = _FakeHandle("new-lock")- self._handles[handle.id] = handle- return handle-- async def acquire_tree(self, handle, lock_path):- del handle, lock_path- return True---class _RecoveringLockManager:- def __init__(self):- self._handles = {}- self.acquire_tree_calls = []- self.release_calls = []-- async def get_handle_async(self, handle_id):- return self._handles.get(handle_id)-- async def adopt_handle_async(self, handle_id, lock_paths):- del handle_id, lock_paths- return None-- def get_handle(self, handle_id):- return self._handles.get(handle_id)+ self.release_calls: list[str] = []- def create_handle(self):- handle = _FakeHandle("new-lock")- handle.locks = []- self._handles[handle.id] = handle- return handle-- async def acquire_tree(self, handle, lock_path):- self.acquire_tree_calls.append(lock_path)- handle.locks.append(f"{lock_path}/.path.ovlock")- return True-- async def release(self, handle):- self.release_calls.append(handle.id)- self._handles.pop(handle.id, None)+ async def pathlock_release(self, lease):+ self.release_calls.append(lease["id"])class _FakeVikingFS:+ def __init__(self, pathlock=None):+ self._async_agfs = pathlock or _FakePathLock()+async def exists(self, uri, ctx=None):del uri, ctxreturn False+ async def ls(self, uri, node_limit=None, ctx=None):+ del uri, node_limit, ctx+ return []+def _uri_to_path(self, uri, ctx=None):del ctxreturn f"/fake/{uri.replace('://', '/').strip('/')}"@pytest.mark.asyncio-async def test_semantic_processor_borrows_caller_owned_lock(monkeypatch):+async def test_memory_semantic_directory_does_not_release_borrowed_lock(monkeypatch):processor = SemanticProcessor()- lock_manager = _FakeLockManager()-- class _FakeDagExecutor:- def __init__(self, **kwargs):- self.lock = kwargs["lock"]- self.stale = False-- async def run(self, root_uri):- assert root_uri == "viking://resources/demo"- assert self.lock.handle_id == "lock-1"-- def get_stats(self):- return DagStats()+ pathlock = _FakePathLock()+ borrowed_lease = {"id": "borrowed-lock", "owned": False}monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.get_viking_fs",- lambda: _FakeVikingFS(),- )- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_processor.SemanticDagExecutor",- lambda **kwargs: _FakeDagExecutor(**kwargs),- )- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: lock_manager,+ lambda: _FakeVikingFS(pathlock),)- await processor.on_dequeue(+ await processor._process_memory_directory(SemanticMsg(- uri="viking://resources/demo",- context_type="resource",+ uri="viking://memory/demo",+ context_type="memory",recursive=False,- ).to_dict(),- lock=BorrowedLockLease.from_handle(lock_manager, lock_manager.get_handle("lock-1")),- )-- assert lock_manager.release_calls == []---async def test_semantic_processor_recovers_stale_non_tree_handoff(monkeypatch):- processor = SemanticProcessor()- lock_manager = _RecoveringLockManager()-- class _FakeDagExecutor:- def __init__(self, **kwargs):- self.lock = kwargs["lock"]- self.stale = False-- async def run(self, root_uri):- assert root_uri == "viking://resources/demo"- assert self.lock.handle_id == "new-lock"- await self.lock.close()-- def get_stats(self):- return DagStats()-- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_processor.get_viking_fs",- lambda: _FakeVikingFS(),- )- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_processor.SemanticDagExecutor",- lambda **kwargs: _FakeDagExecutor(**kwargs),- )- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_lock.get_lock_manager",- lambda: lock_manager,- )-- await processor.on_dequeue(- SemanticMsg(- uri="viking://resources/demo",- context_type="resource",- recursive=False,- lock_handoff=LockHandoffRef(- handle_id="stale-lock",- lock_paths=("/fake/viking/resources/.mw_exact_demo.deadbeef",),- ),- ).to_dict()- )-- assert lock_manager.acquire_tree_calls == ["/fake/viking/resources/demo"]- assert lock_manager.release_calls == ["new-lock"]---async def test_semantic_lock_scope_reacquires_tree_lock_when_handoff_handle_is_stale(- monkeypatch,-):- lock_manager = _RecoveringLockManager()- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_lock.get_lock_manager",- lambda: lock_manager,- )-- scope = await SemanticLockScope.resolve(- LockHandoffRef(- handle_id="stale-lock",- lock_paths=("/local/default/resources/CONTRIBUTING_CN_3/.path.ovlock",),- ),- fallback_path_factory=lambda: (_ for _ in ()).throw(- AssertionError("tree handoffs must not evaluate the fallback path")- ),- )-- try:- assert scope.lock.handle_id == "new-lock"- assert lock_manager.acquire_tree_calls == ["/local/default/resources/CONTRIBUTING_CN_3"]- finally:- await scope.close()-- assert lock_manager.release_calls == ["new-lock"]---async def test_semantic_lock_scope_reacquires_fallback_path_for_stale_non_tree_handoff(- monkeypatch,-):- lock_manager = _RecoveringLockManager()- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_lock.get_lock_manager",- lambda: lock_manager,- )-- scope = await SemanticLockScope.resolve(- LockHandoffRef(- handle_id="stale-lock",- lock_paths=("/local/default/resources/.mw_exact_demo.deadbeef",),),- fallback_path_factory=lambda: "/local/default/resources/demo",+ lock=borrowed_lease,)- try:- assert scope.lock.handle_id == "new-lock"- assert lock_manager.acquire_tree_calls == ["/local/default/resources/demo"]- finally:- await scope.close()-- assert lock_manager.release_calls == ["new-lock"]---async def test_semantic_processor_lock_error_requeues_without_circuit_breaker(monkeypatch):- processor = SemanticProcessor()- reenqueue_calls = []- success_called = False- requeue_called = False- error_called = False-- async def _reenqueue(msg):- reenqueue_calls.append(msg.uri)-- def on_success():- nonlocal success_called- success_called = True-- def on_requeue():- nonlocal requeue_called- requeue_called = True-- def on_error(error_msg, error_data=None):- del error_msg, error_data- nonlocal error_called- error_called = True-- def _record_failure(error):- raise AssertionError(f"lock errors must not trip circuit breaker: {error}")-- processor.set_callbacks(on_success, on_requeue, on_error)- processor._circuit_breaker.record_failure = _record_failure-- monkeypatch.setattr(processor, "_reenqueue_semantic_msg", _reenqueue)- monkeypatch.setattr(- "openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",- lambda *args, **kwargs: (_ for _ in ()).throw(- LockAcquisitionError("lock handle is no longer active")- ),- )-- msg = SemanticMsg(- uri="viking://resources/CONTRIBUTING_CN_3",- context_type="resource",- recursive=True,- lock_handoff=LockHandoffRef(- handle_id="stale-lock",- lock_paths=("/local/default/resources/CONTRIBUTING_CN_3/.path.ovlock",),- ),- )-- await processor.on_dequeue(msg.to_dict())-- assert reenqueue_calls == ["viking://resources/CONTRIBUTING_CN_3"]- assert requeue_called is True- assert success_called is True- assert error_called is False+ assert pathlock.release_calls == []diff --git a/tests/storage/test_semantic_processor_mv_vector_store.py b/tests/storage/test_semantic_processor_mv_vector_store.pyindex 015861819..ea0011c87 100644--- a/tests/storage/test_semantic_processor_mv_vector_store.py+++ b/tests/storage/test_semantic_processor_mv_vector_store.py@@ -1,4 +1,3 @@-from contextlib import asynccontextmanagerfrom unittest.mock import AsyncMockimport pytest@@ -18,13 +17,6 @@ async def test_mv_canonicalizes_user_shorthand_before_vector_update(monkeypatch)fs._copy_for_mv = AsyncMock()fs._update_vector_store_uris = AsyncMock()- @asynccontextmanager- async def unlocked(*_args, **_kwargs):- yield None-- monkeypatch.setattr("openviking.storage.transaction.get_lock_manager", lambda: None)- monkeypatch.setattr("openviking.storage.transaction.LockContext", unlocked)-await fs.mv("viking://user/peers/vaka/memories/profile.md","viking://user/memories/profile.md",diff --git a/tests/storage/test_semantic_processor_target_preexisting.py b/tests/storage/test_semantic_processor_target_preexisting.pyindex 109d33a55..f0b70bed4 100644--- a/tests/storage/test_semantic_processor_target_preexisting.py+++ b/tests/storage/test_semantic_processor_target_preexisting.py@@ -5,7 +5,6 @@ import pytestfrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import DiffResult, SemanticProcessor-from openviking.storage.transaction import NO_LOCKclass _FakeVikingFS:@@ -36,6 +35,7 @@ class _SyncVikingFS:],}self.deleted_temp = []+ self.mutation_leases = []async def exists(self, uri, ctx=None):return uri in self.entries@@ -49,16 +49,20 @@ class _SyncVikingFS:async def read_file(self, uri, ctx=None):return self.contents.get(uri, "")- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):+ async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):+ self.mutation_leases.append(("rm", uri, lease_ref))self.contents.pop(uri, None)- async def mv(self, src, dst, ctx=None, lock_handle=None):+ async def mv(self, src, dst, ctx=None, lease_ref=None):+ self.mutation_leases.append(("mv", dst, lease_ref))self.contents[dst] = self.contents.pop(src)- async def mkdir(self, uri, exist_ok=False, ctx=None):+ async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):+ self.mutation_leases.append(("mkdir", uri, lease_ref))self.entries.setdefault(uri, [])- async def delete_temp(self, uri, ctx=None):+ async def delete_temp(self, uri, ctx=None, lease_ref=None):+ self.mutation_leases.append(("delete_temp", uri, lease_ref))self.deleted_temp.append(uri)@@ -93,7 +97,7 @@ async def test_target_source_syncs_before_semantic_dag(monkeypatch):)monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",- AsyncMock(return_value=SimpleNamespace(lock=NO_LOCK, close=AsyncMock())),+ AsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),)_FakeDagExecutor.calls = []@@ -127,6 +131,11 @@ async def test_target_source_syncs_before_semantic_dag(monkeypatch):@pytest.mark.asyncioasync def test_sync_diff_reports_target_uris_and_preserves_sidecars(monkeypatch):fake_fs = _SyncVikingFS()+ lease = {+ "lease_ref": "outer-tree-ref",+ "owner_id": "outer-tree-owner",+ "owned": False,+ }monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.get_viking_fs",lambda: fake_fs,@@ -135,7 +144,7 @@ async def test_sync_diff_reports_target_uris_and_preserves_sidecars(monkeypatch)diff = await SemanticProcessor()._sync_topdown_recursive("viking://temp/import","viking://resources/root",- lock=NO_LOCK,+ lock=lease,)assert diff.to_changes() == {@@ -149,6 +158,13 @@ async def test_sync_diff_reports_target_uris_and_preserves_sidecars(monkeypatch))assert fake_fs.contents["viking://resources/root/.abstract.md"] == "old abstract"assert fake_fs.deleted_temp == ["viking://temp/import"]+ assert fake_fs.mutation_leases+ assert all(+ mutation_lease is lease+ for operation, _, mutation_lease in fake_fs.mutation_leases+ if operation != "delete_temp"+ )+ assert fake_fs.mutation_leases[-1] == ("delete_temp", "viking://temp/import", None)@pytest.mark.asyncio@@ -164,7 +180,7 @@ async def test_sync_missing_source_never_touches_target(monkeypatch):await SemanticProcessor()._sync_topdown_recursive("viking://temp/missing","viking://resources/root",- lock=NO_LOCK,+ lock=None,)fake_fs.ls.assert_not_awaited()diff --git a/tests/storage/test_semantic_queue_memory_dedupe.py b/tests/storage/test_semantic_queue_memory_dedupe.pyindex d8a810cda..c69c4320b 100644--- a/tests/storage/test_semantic_queue_memory_dedupe.py+++ b/tests/storage/test_semantic_queue_memory_dedupe.py@@ -101,38 +101,24 @@ async def test_coalesced_semantic_messages_mark_old_version_stale():assert not is_semantic_msg_stale(second)-class _FakeHandle:- def __init__(self):- self.id = "lock-1"- self.locks = []-+class _FakePathLock:+ """Mock for _async_agfs pathlock operations."""-class _FakeLockManager:def __init__(self):self.acquired_batches = []self.release_calls = []- def create_handle(self):- return _FakeHandle()-- def get_handle(self, handle_id):- del handle_id- return None-- async def acquire_exact_path_batch(self, handle, paths):+ async def pathlock_acquire_exact_batch(self, paths):self.acquired_batches.append(paths)- handle.locks.extend(paths)- return True-- async def release(self, handle):- self.release_calls.append(handle.id)+ return {"id": "lock-1"}- async def release_selected(self, handle, lock_paths):- del handle, lock_paths+ async def pathlock_release(self, lease):+ self.release_calls.append(lease["id"])class _FakeVikingFS:- def __init__(self):+ def __init__(self, pathlock=None):+ self._async_agfs = pathlock or _FakePathLock()self.writes = []def _uri_to_path(self, uri, ctx=None):@@ -155,8 +141,8 @@ class _FakeMemoryDirFS:@pytest.mark.asyncioasync def test_stale_memory_semantic_write_is_skipped(monkeypatch):- lock_manager = _FakeLockManager()- viking_fs = _FakeVikingFS()+ pathlock = _FakePathLock()+ viking_fs = _FakeVikingFS(pathlock)processor = SemanticProcessor()coalesce_key = f"memory|acc|u|p|viking://user/default/memories/preferences/{uuid4().hex}"@@ -175,8 +161,6 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):await q.enqueue(first)await q.enqueue(latest)- monkeypatch.setattr("openviking.storage.transaction.get_lock_manager", lambda: lock_manager)-wrote_first = await processor._write_memory_directory_semantics(msg=first,viking_fs=viking_fs,@@ -196,7 +180,7 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):assert not wrote_firstassert wrote_latest- assert lock_manager.acquired_batches == [+ assert pathlock.acquired_batches == [["/fake/viking/user/default/memories/preferences/.overview.md","/fake/viking/user/default/memories/preferences/.abstract.md",diff --git a/tests/storage/test_viking_fs_async_stat.py b/tests/storage/test_viking_fs_async_stat.pydeleted file mode 100644index 920e53f07..000000000--- a/tests/storage/test_viking_fs_async_stat.py+++ /dev/null@@ -1,36 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0--import pytest--import openviking.storage.transaction as transaction_module-from openviking.storage.viking_fs import VikingFS---class _StatAGFS:- def stat(self, path):- return {"name": path.rsplit("/", 1)[-1], "isDir": False}---class _AsyncOnlyLockManager:- def __init__(self):- self.paths = []-- async def is_path_locked_async(self, path, ignore_stale=True):- self.paths.append((path, ignore_stale))- return True-- def is_path_locked(self, path, ignore_stale=True):- raise AssertionError("stat() should use the async lock lookup")---async def test_stat_uses_async_lock_lookup(monkeypatch):- lock_manager = _AsyncOnlyLockManager()- monkeypatch.setattr(transaction_module, "get_lock_manager", lambda: lock_manager)-- fs = VikingFS(agfs=_StatAGFS())- result = await fs.stat("viking://resources/file.txt")-- assert result["isLocked"] is True- assert lock_manager.paths == [("/local/default/resources/file.txt", True)]diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.pyindex 4b00e7407..9033f3074 100644--- a/tests/storage/test_viking_fs_tree.py+++ b/tests/storage/test_viking_fs_tree.py@@ -12,7 +12,9 @@ from openviking_cli.session.user_id import UserIdentifierclass _DummyAgfs:- pass+ def stat(self, _path, ctx=None):+ """Return a minimal stat payload for paths assumed to exist in tree tests."""+ return {}class _FixedDatetime(datetime):@@ -136,7 +138,7 @@ async def default_batch_fetch(entries, abs_limit, **_kwargs):[("resources", "/local/test_account", True),("user", "/local/test_account", True),- ("agent", "/local/test_account", False),+ ("agent", "/local/test_account", True),("session", "/local/test_account", False),("tasks", "/local/test_account", False),("_system", "/local/test_account", False),diff --git a/tests/storage/test_viking_fs_write_locking.py b/tests/storage/test_viking_fs_write_locking.pyindex 6765cb9ed..6e1d22986 100644--- a/tests/storage/test_viking_fs_write_locking.py+++ b/tests/storage/test_viking_fs_write_locking.py@@ -1,6 +1,10 @@+from unittest.mock import AsyncMock+import pytest+from openviking.server.identity import RequestContext, Rolefrom openviking.storage.viking_fs import VikingFS+from openviking_cli.session.user_id import UserIdentifierclass _FakeAGFS:@@ -25,63 +29,93 @@ class _FakeAGFS:return self.storage[path]-class _RecordingLockContext:- """Record LockContext arguments so tests can assert dual-path locking."""+class _AsyncAppendAGFS:+ """Async AGFS stub that records append lock ordering."""- calls = []+ def __init__(self):+ self.events = []- def __init__(self, lock_manager, paths, lock_mode="exact", **kwargs):- """Store lock paths and mode while ignoring unrelated details."""- self.lock_manager = lock_manager- self.paths = list(paths)- self.lock_mode = lock_mode- self.kwargs = kwargs+ async def pathlock_acquire_exact(self, path):+ """Record exact acquisition and return an opaque lease ref."""+ lease = {"lease_ref": "lease-1"}+ self.events.append(("acquire", path, lease))+ return lease- async def __aenter__(self):- """Record the call on context entry."""- type(self).calls.append((self.paths, self.lock_mode, self.kwargs))- return self+ async def pathlock_release(self, lease):+ """Record lease release."""+ self.events.append(("release", lease))- async def __aexit__(self, exc_type, exc, tb):- """Do not swallow exceptions on exit."""- return False+ async def read(self, path, fs_ctx=None):+ """Record reads with propagated fs_ctx and return existing content."""+ self.events.append(("read", path, fs_ctx))+ return b"old"+ async def write(self, path, data, fs_ctx=None):+ """Record writes with propagated fs_ctx."""+ self.events.append(("write", path, data, fs_ctx))+ return len(data)- ("method_name", "args", "expected_bytes"),- [- ("write_file", ("hello",), b"hello"),- ("append_file", (" world",), b"hello world"),- ],-)-async def test_encrypted_writes_lock_final_and_temp_paths(- monkeypatch, method_name, args, expected_bytes-):- """Encrypted writes must lock both the final file path and the hidden temp path."""- import openviking.storage.transaction as transaction_module- _RecordingLockContext.calls.clear()- monkeypatch.setattr(transaction_module, "LockContext", _RecordingLockContext)- monkeypatch.setattr(transaction_module, "get_lock_manager", lambda: object())+class _AsyncMoveAGFS:+ """Async AGFS stub that records move lock ownership and release."""- agfs = _FakeAGFS()- agfs.storage["/local/default/resources/note.md"] = b"hello"- fs = VikingFS(agfs=agfs, encryptor=object())+ def __init__(self, source_is_dir=False):+ self.acquire_calls = []+ self.tree_calls = []+ self.release_calls = []+ self.rm_calls = []+ self.source_is_dir = source_is_dir- await getattr(fs, method_name)("viking://resources/note.md", *args)+ async def stat(self, path):+ """Return the configured source kind and a missing destination."""+ if path.endswith("/source.md") or path.endswith("/source"):+ return {"isDir": self.source_is_dir}+ raise FileNotFoundError(path)++ async def pathlock_acquire_batch(+ self,+ requests,+ timeout_secs=0.0,+ owner_lease_ref=None,+ ):+ """Record the operation lease request."""+ self.acquire_calls.append((requests, owner_lease_ref))+ return {+ "lease_ref": "operation-ref",+ "owner_id": (owner_lease_ref["owner_id"] if owner_lease_ref else "operation-owner"),+ "ownership_ref": "operation-ownership",+ "owned": True,+ }++ async def pathlock_acquire_tree(+ self,+ path,+ timeout_secs=0.0,+ owner_lease_ref=None,+ ):+ """Record a temporary Tree extension used only for cleanup."""+ del timeout_secs+ self.tree_calls.append((path, owner_lease_ref))+ return {+ "lease_ref": "cleanup-ref",+ "owner_id": owner_lease_ref["owner_id"],+ "ownership_ref": "cleanup-ownership",+ "owned": True,+ }++ async def pathlock_release(self, lease):+ """Record operation lease release."""+ self.release_calls.append(lease)++ async def rm(self, path, recursive=False, fs_ctx=None):+ """Accept source removal under the operation lease."""+ self.rm_calls.append((path, recursive, fs_ctx))+ return {"path": path, "recursive": recursive, "fs_ctx": fs_ctx}- assert _RecordingLockContext.calls == [- (- [- "/local/default/resources/note.md",- "/local/default/temp/.encrypt_stage/571a25aab6e6bca05a60a6e4aec646389a9ac38237daf55ceda4f72f3d1b4afe.encrypt",- ],- "exact",- {"timeout": 1.0, "handle": None},- )- ]- assert agfs.storage["/local/default/resources/note.md"] == expected_bytes++def _default_ctx() -> RequestContext:+ """Return a stable root request context for pathlock fs_ctx tests."""+ return RequestContext(user=UserIdentifier.the_default_user(), role=Role(Role.ROOT))@pytest.mark.parametrize(@@ -113,3 +147,190 @@ def test_encrypted_temp_path_mapping_matches_rust(final_path, temp_path):"""Keep Python temp-path mapping aligned with the Rust encryption wrapper."""fs = VikingFS(agfs=_FakeAGFS(), encryptor=object())assert fs._encrypted_temp_path(final_path) == temp_path+++def test_pathlock_fs_ctx_rejects_malformed_explicit_lease():+ """An explicit malformed lease must fail instead of enabling a new auto-lock."""+ fs = VikingFS(agfs=_FakeAGFS())++ with pytest.raises(ValueError, match="lease_ref"):+ fs._pathlock_fs_ctx(_default_ctx(), {})+++async def test_append_file_holds_exact_lease_across_read_and_write(monkeypatch):+ """append_file should keep read and rewrite inside one exact pathlock lease."""+ fake = _AsyncAppendAGFS()+ fs = VikingFS(agfs=_FakeAGFS())+ fs._async_agfs = fake # type: ignore[assignment]++ async def ensure_parent_dirs(path, ctx=None, lease_ref=None):+ """Record parent creation boundary without touching storage."""+ fake.events.append(("ensure_parent", path, lease_ref))++ monkeypatch.setattr(fs, "_ensure_parent_dirs", ensure_parent_dirs)+ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda _uri, _ctx=None: None)+ monkeypatch.setattr(+ fs,+ "_uri_to_path",+ lambda _uri, **_kwargs: "/local/default/resources/a.md",+ )+ monkeypatch.setattr(fs, "_ctx_or_default", lambda _ctx=None: _default_ctx())++ await fs.append_file("viking://a.md", "+new")++ assert fake.events[0] == ("ensure_parent", "/local/default/resources/a.md", None)+ assert fake.events[1][0] == "acquire"+ assert fake.events[2][0:2] == ("read", "/local/default/resources/a.md")+ assert fake.events[2][2]["lease_ref"] == "lease-1"+ assert fake.events[3][0:3] == (+ "write",+ "/local/default/resources/a.md",+ b"old+new",+ )+ assert fake.events[3][3]["lease_ref"] == "lease-1"+ assert fake.events[4] == ("release", {"lease_ref": "lease-1"})+++async def test_mv_extends_outer_lease_with_owned_capability(monkeypatch):+ """Move must acquire uncovered source locks with the outer owned capability."""+ fake = _AsyncMoveAGFS()+ fs = VikingFS(agfs=_FakeAGFS())+ fs._async_agfs = fake # type: ignore[assignment]+ outer = {+ "lease_ref": "outer-ref",+ "owner_id": "outer-owner",+ "ownership_ref": "outer-ownership",+ "owned": True,+ }+ copied_with = []++ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda *_args, **_kwargs: None)+ monkeypatch.setattr(fs, "_ensure_delete_access", lambda *_args, **_kwargs: None)+ monkeypatch.setattr(+ fs,+ "_uri_to_path",+ lambda uri, **_kwargs: (+ "/local/default/temp/source.md"+ if uri == "viking://temp/source.md"+ else "/local/default/resources/target.md"+ ),+ )+ monkeypatch.setattr(fs, "_collect_uris", AsyncMock(return_value=[]))+ monkeypatch.setattr(fs, "_delete_from_vector_store", AsyncMock())+ monkeypatch.setattr(fs, "_update_vector_store_uris", AsyncMock())++ async def record_copy(**kwargs):+ """Record the lease used by the copy stage."""+ copied_with.append(kwargs["lease_ref"])++ monkeypatch.setattr(fs, "_copy_for_mv", record_copy)++ await fs.mv(+ "viking://temp/source.md",+ "viking://resources/target.md",+ ctx=_default_ctx(),+ lease_ref=outer,+ )++ assert fake.acquire_calls[0][1] == outer+ assert copied_with[0]["lease_ref"] == "operation-ref"+ assert fake.release_calls == [copied_with[0]]+++async def test_directory_mv_uses_source_tree_and_destination_exact(monkeypatch):+ """Directory move must not hold a destination Tree lock for the whole copy."""+ fake = _AsyncMoveAGFS(source_is_dir=True)+ fs = VikingFS(agfs=_FakeAGFS())+ fs._async_agfs = fake # type: ignore[assignment]++ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda *_args, **_kwargs: None)+ monkeypatch.setattr(fs, "_ensure_delete_access", lambda *_args, **_kwargs: None)+ monkeypatch.setattr(+ fs,+ "_uri_to_path",+ lambda uri, **_kwargs: (+ "/local/default/temp/source"+ if uri == "viking://temp/source"+ else "/local/default/resources/target"+ ),+ )+ monkeypatch.setattr(fs, "_collect_uris", AsyncMock(return_value=[]))+ monkeypatch.setattr(fs, "_delete_from_vector_store", AsyncMock())+ monkeypatch.setattr(fs, "_update_vector_store_uris", AsyncMock())+ monkeypatch.setattr(fs, "_copy_for_mv", AsyncMock())++ await fs.mv(+ "viking://temp/source",+ "viking://resources/target",+ ctx=_default_ctx(),+ )++ assert fake.acquire_calls[0][0] == [+ {"path": "/local/default/temp/source", "kind": "tree"},+ {"path": "/local/default/resources/target", "kind": "exact"},+ ]+++async def test_directory_mv_uses_temporary_tree_only_for_failed_copy_cleanup(monkeypatch):+ """Failed directory move must acquire and release a cleanup-only target Tree."""+ fake = _AsyncMoveAGFS(source_is_dir=True)+ fs = VikingFS(agfs=_FakeAGFS())+ fs._async_agfs = fake # type: ignore[assignment]++ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda *_args, **_kwargs: None)+ monkeypatch.setattr(fs, "_ensure_delete_access", lambda *_args, **_kwargs: None)+ monkeypatch.setattr(+ fs,+ "_uri_to_path",+ lambda uri, **_kwargs: (+ "/local/default/temp/source"+ if uri == "viking://temp/source"+ else "/local/default/resources/target"+ ),+ )+ monkeypatch.setattr(fs, "_collect_uris", AsyncMock(return_value=[]))+ monkeypatch.setattr(fs, "_delete_from_vector_store", AsyncMock())+ monkeypatch.setattr(+ fs,+ "_update_vector_store_uris",+ AsyncMock(side_effect=RuntimeError("vector update failed")),+ )+ monkeypatch.setattr(fs, "_copy_for_mv", AsyncMock())++ with pytest.raises(RuntimeError, match="vector update failed"):+ await fs.mv(+ "viking://temp/source",+ "viking://resources/target",+ ctx=_default_ctx(),+ )++ assert fake.tree_calls == [+ (+ "/local/default/resources/target",+ {+ "lease_ref": "operation-ref",+ "owner_id": "operation-owner",+ "ownership_ref": "operation-ownership",+ "owned": True,+ },+ )+ ]+ assert fake.rm_calls[0][2]["lease_ref"] == "cleanup-ref"+ assert fake.release_calls == [+ {+ "lease_ref": "cleanup-ref",+ "owner_id": "operation-owner",+ "ownership_ref": "cleanup-ownership",+ "owned": True,+ },+ {+ "lease_ref": "operation-ref",+ "owner_id": "operation-owner",+ "ownership_ref": "operation-ownership",+ "owned": True,+ },+ ]diff --git a/tests/transaction/test_concurrent_lock.py b/tests/transaction/test_concurrent_lock.pydeleted file mode 100644index a853cb253..000000000--- a/tests/transaction/test_concurrent_lock.py+++ /dev/null@@ -1,103 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for concurrent lock acquisition using real AGFS backend."""--import asyncio-import uuid--from openviking.storage.transaction.lock_handle import LockHandle-from openviking.storage.transaction.path_lock import PathLockEngine---class TestConcurrentLock:- async def test_exact_mutual_exclusion_same_path(self, agfs_client, test_dir):- """两个任务竞争同一路径的 EXACT 锁,均最终成功(串行执行)。"""- lock = PathLockEngine(agfs_client)-- results = {}-- async def holder(tx_id):- tx = LockHandle(id=tx_id)- ok = await lock.acquire_exact_path(test_dir, tx, timeout=5.0)- if ok:- await asyncio.sleep(0.3)- await lock.release(tx)- results[tx_id] = ok-- await asyncio.gather(- holder("tx-conc-1"),- holder("tx-conc-2"),- )-- # Both should eventually succeed (one waits for the other)- assert results["tx-conc-1"] is True- assert results["tx-conc-2"] is True-- async def test_tree_blocks_concurrent_exact_child(self, agfs_client, test_dir):- """TreeLock on parent 持锁期间,子目录的 ExactPathLock 被阻塞,释放后成功。"""- child = f"{test_dir}/child-{uuid.uuid4().hex}"- agfs_client.mkdir(child)-- lock = PathLockEngine(agfs_client)- parent_acquired = asyncio.Event()- parent_released = asyncio.Event()-- child_result = {}-- async def parent_holder():- tx = LockHandle(id="tx-tree-parent")- ok = await lock.acquire_tree(test_dir, tx, timeout=5.0)- assert ok is True- parent_acquired.set()- await asyncio.sleep(0.5)- await lock.release(tx)- parent_released.set()-- async def child_worker():- await parent_acquired.wait()- tx = LockHandle(id="tx-tree-child")- ok = await lock.acquire_exact_path(child, tx, timeout=5.0)- child_result["ok"] = ok- child_result["after_release"] = parent_released.is_set()- if ok:- await lock.release(tx)-- await asyncio.gather(parent_holder(), child_worker())-- assert child_result["ok"] is True- # Child should succeed only after parent released- assert child_result["after_release"] is True-- async def test_exact_child_blocks_concurrent_tree_parent(self, agfs_client, test_dir):- """ExactPathLock on child 持锁期间,父目录的 TreeLock 被阻塞,释放后成功。"""- child = f"{test_dir}/child-{uuid.uuid4().hex}"- agfs_client.mkdir(child)-- lock = PathLockEngine(agfs_client)- child_acquired = asyncio.Event()- child_released = asyncio.Event()-- parent_result = {}-- async def child_holder():- tx = LockHandle(id="tx-rev-child")- ok = await lock.acquire_exact_path(child, tx, timeout=5.0)- assert ok is True- child_acquired.set()- await asyncio.sleep(0.5)- await lock.release(tx)- child_released.set()-- async def parent_worker():- await child_acquired.wait()- tx = LockHandle(id="tx-rev-parent")- ok = await lock.acquire_tree(test_dir, tx, timeout=5.0)- parent_result["ok"] = ok- parent_result["after_release"] = child_released.is_set()- if ok:- await lock.release(tx)-- await asyncio.gather(child_holder(), parent_worker())-- assert parent_result["ok"] is True- assert parent_result["after_release"] is Truediff --git a/tests/transaction/test_e2e.py b/tests/transaction/test_e2e.pydeleted file mode 100644index 0e6dd4453..000000000--- a/tests/transaction/test_e2e.py+++ /dev/null@@ -1,126 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""End-to-end lock tests using real AGFS backend.--These tests exercise LockContext -> LockManager -> PathLockEngine -> AGFS,-verifying the acquire -> operate -> release lifecycle.-"""--import uuid--import pytest--from openviking.storage.errors import LockAcquisitionError-from openviking.storage.transaction.lock_context import LockContext-from openviking.storage.transaction.lock_manager import LockManager-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME---def _lock_file_gone(agfs_client, lock_path: str) -> bool:- """Return True if the lock file does not exist in AGFS."""- try:- agfs_client.stat(lock_path)- return False- except Exception:- return True---def lock_manager(agfs_client):- return LockManager(agfs=agfs_client, lock_timeout=1.0, lock_expire=1.0)---class TestLockContextCommit:- async def test_lock_acquired_and_released(self, agfs_client, lock_manager, test_dir):- """Lock is held inside the context and released after exit."""- async with LockContext(lock_manager, [test_dir], lock_mode="exact") as handle:- lock_path = handle.locks[0]- token = agfs_client.cat(lock_path)- assert token is not None-- assert _lock_file_gone(agfs_client, lock_path)-- async def test_file_persists_after_context(self, agfs_client, lock_manager, test_dir):- """Files written inside a lock context persist."""- file_path = f"{test_dir}/committed-file.txt"-- async with LockContext(lock_manager, [test_dir], lock_mode="exact"):- agfs_client.write(file_path, b"committed data")-- content = agfs_client.cat(file_path)- assert content == b"committed data"---class TestLockContextException:- async def test_lock_released_on_exception(self, agfs_client, lock_manager, test_dir):- """Lock is released even when an exception occurs inside the context."""- lock_path = ""-- with pytest.raises(RuntimeError):- async with LockContext(lock_manager, [test_dir], lock_mode="exact") as handle:- lock_path = handle.locks[0]- token = agfs_client.cat(lock_path)- assert token is not None- raise RuntimeError("simulated failure")-- assert lock_path- assert _lock_file_gone(agfs_client, lock_path)-- async def test_exception_not_swallowed(self, agfs_client, lock_manager, test_dir):- """Exceptions propagate through the context manager."""- with pytest.raises(ValueError, match="test error"):- async with LockContext(lock_manager, [test_dir], lock_mode="exact"):- raise ValueError("test error")---class TestLockContextMv:- async def test_mv_lock_acquires_both_paths(self, agfs_client, lock_manager, test_dir):- """mv lock mode acquires tree source and exact destination locks."""- src = f"{test_dir}/mv-src-{uuid.uuid4().hex}"- dst = f"{test_dir}/mv-dst-{uuid.uuid4().hex}"- agfs_client.mkdir(src)- agfs_client.mkdir(dst)-- async with LockContext(lock_manager, [src], lock_mode="mv", mv_dst_path=dst):- src_token = agfs_client.cat(f"{src}/{LOCK_FILE_NAME}")- dst_token = agfs_client.cat(f"{dst}/{LOCK_FILE_NAME}")- src_token_str = src_token.decode("utf-8") if isinstance(src_token, bytes) else src_token- dst_token_str = dst_token.decode("utf-8") if isinstance(dst_token, bytes) else dst_token- assert ":T" in src_token_str- assert ":E" in dst_token_str-- for path in [f"{src}/{LOCK_FILE_NAME}", f"{dst}/{LOCK_FILE_NAME}"]:- assert _lock_file_gone(agfs_client, path)---class TestLockContextTree:- async def test_tree_lock_and_release(self, agfs_client, lock_manager, test_dir):- """Tree lock is acquired and released."""- target = f"{test_dir}/tree-{uuid.uuid4().hex}"- agfs_client.mkdir(target)-- async with LockContext(lock_manager, [target], lock_mode="tree"):- token = agfs_client.cat(f"{target}/{LOCK_FILE_NAME}")- token_str = token.decode("utf-8") if isinstance(token, bytes) else token- assert ":T" in token_str-- assert _lock_file_gone(agfs_client, f"{target}/{LOCK_FILE_NAME}")---class TestSequentialLocks:- async def test_sequential_locks_on_same_path(self, agfs_client, lock_manager, test_dir):- """Multiple sequential lock contexts on the same path succeed."""- for i in range(3):- async with LockContext(lock_manager, [test_dir], lock_mode="exact"):- agfs_client.write(f"{test_dir}/f{i}.txt", f"data-{i}".encode())-- for i in range(3):- content = agfs_client.cat(f"{test_dir}/f{i}.txt")- assert content == f"data-{i}".encode()-- async def test_lock_acquisition_failure(self, agfs_client, lock_manager, test_dir):- """LockContext raises LockAcquisitionError for unsupported lock mode."""- nonexistent = f"{test_dir}/nonexistent-{uuid.uuid4().hex}"- with pytest.raises(LockAcquisitionError):- async with LockContext(lock_manager, [nonexistent], lock_mode="unknown"):- passdiff --git a/tests/transaction/test_exact_path_lock.py b/tests/transaction/test_exact_path_lock.pydeleted file mode 100644index e5f1b63f3..000000000--- a/tests/transaction/test_exact_path_lock.py+++ /dev/null@@ -1,244 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for ExactPathLock semantics."""--import asyncio-import threading--import pytest--from openviking.storage.transaction.lock_handle import LockHandle-from openviking.storage.transaction.lock_manager import LockManager-from openviking.storage.transaction.path_lock import EXACT_LOCK_FILE_PREFIX, PathLockEngine---class _MemoryAgfs:- def __init__(self):- self.dirs = {"/"}- self.files: dict[str, bytes] = {}-- def _parent(self, path: str) -> str:- path = path.rstrip("/")- if "/" not in path:- return "/"- parent = path.rsplit("/", 1)[0]- return parent or "/"-- def stat(self, path: str):- path = path.rstrip("/") or "/"- if path in self.dirs:- return {"name": path.rsplit("/", 1)[-1], "isDir": True}- if path in self.files:- return {"name": path.rsplit("/", 1)[-1], "isDir": False}- raise FileNotFoundError(path)-- def mkdir(self, path: str):- path = path.rstrip("/") or "/"- parent = self._parent(path)- if parent not in self.dirs:- raise FileNotFoundError(parent)- self.dirs.add(path)- return {"message": "created"}-- def read(self, path: str):- if path not in self.files:- raise FileNotFoundError(path)- return self.files[path]-- def write(self, path: str, data: bytes):- parent = self._parent(path)- if parent not in self.dirs:- raise FileNotFoundError(parent)- self.files[path] = data- return path-- def rm(self, path: str, recursive: bool = False):- path = path.rstrip("/") or "/"- self.files.pop(path, None)- if path in self.dirs:- children = [- item- for item in [*self.dirs, *self.files]- if item != path and item.startswith(path.rstrip("/") + "/")- ]- if children and not recursive:- raise RuntimeError("directory not empty")- for child in children:- self.files.pop(child, None)- self.dirs.discard(child)- self.dirs.discard(path)- return {"message": "deleted"}-- def ls(self, path: str):- path = path.rstrip("/") or "/"- prefix = path.rstrip("/") + "/"- names: dict[str, bool] = {}- for item in self.dirs:- if item == path or not item.startswith(prefix):- continue- rest = item[len(prefix) :]- if "/" not in rest:- names[rest] = True- for item in self.files:- if not item.startswith(prefix):- continue- rest = item[len(prefix) :]- if "/" not in rest:- names[rest] = False- return [{"name": name, "isDir": is_dir} for name, is_dir in names.items()]---class _ConcurrentParentCreationAgfs(_MemoryAgfs):- def __init__(self, shared_parent: str):- super().__init__()- self.shared_parent = shared_parent- self._initial_stat_barrier = threading.Barrier(2)- self._state_lock = threading.Lock()- self._missing_stat_count = 0- self.mkdir_attempts = 0-- def stat(self, path: str):- path = path.rstrip("/") or "/"- should_report_missing = False- if path == self.shared_parent:- with self._state_lock:- if self._missing_stat_count < 2:- self._missing_stat_count += 1- should_report_missing = True- if should_report_missing:- self._initial_stat_barrier.wait(timeout=5)- raise FileNotFoundError(path)- return super().stat(path)-- def mkdir(self, path: str):- path = path.rstrip("/") or "/"- if path != self.shared_parent:- return super().mkdir(path)- with self._state_lock:- self.mkdir_attempts += 1- if path in self.dirs:- raise FileExistsError(path)- parent = self._parent(path)- if parent not in self.dirs:- raise FileNotFoundError(parent)- self.dirs.add(path)- return {"message": "created"}---def _agfs_with_docs_dir() -> _MemoryAgfs:- agfs = _MemoryAgfs()- agfs.mkdir("/local")- agfs.mkdir("/local/default")- agfs.mkdir("/local/default/resources")- agfs.mkdir("/local/default/resources/docs")- return agfs---async def test_exact_path_lock_allows_sibling_paths():- agfs = _agfs_with_docs_dir()- lock = PathLockEngine(agfs)- first = LockHandle(id="exact-a")- second = LockHandle(id="exact-b")-- assert await lock.acquire_exact_path("/local/default/resources/docs/a.md", first)- assert await lock.acquire_exact_path("/local/default/resources/docs/b.md", second)-- await lock.release(first)- await lock.release(second)---async def test_exact_path_locks_tolerate_concurrent_parent_creation():- shared_parent = "/local/default/resources/shared"- agfs = _ConcurrentParentCreationAgfs(shared_parent)- agfs.mkdir("/local")- agfs.mkdir("/local/default")- agfs.mkdir("/local/default/resources")- lock = PathLockEngine(agfs)- first = LockHandle(id="exact-a")- second = LockHandle(id="exact-b")-- acquired = await asyncio.gather(- lock.acquire_exact_path(f"{shared_parent}/a.md", first),- lock.acquire_exact_path(f"{shared_parent}/b.md", second),- )-- assert acquired == [True, True]- assert agfs.mkdir_attempts == 2- exact_lock_paths = [- path- for path in agfs.files- if path.startswith(f"{shared_parent}/")- and path.rsplit("/", 1)[-1].startswith(EXACT_LOCK_FILE_PREFIX)- ]- assert len(exact_lock_paths) == 2-- await lock.release(first)- await lock.release(second)---async def test_exact_path_lock_blocks_same_path_without_creating_target():- agfs = _agfs_with_docs_dir()- lock = PathLockEngine(agfs)- first = LockHandle(id="exact-a")- second = LockHandle(id="exact-a-blocked")- target = "/local/default/resources/docs/a.md"-- assert await lock.acquire_exact_path(target, first)- assert not await lock.acquire_exact_path(target, second, timeout=0.0)-- assert lock.is_locked(target)- with pytest.raises(FileNotFoundError):- agfs.stat(target)- assert any(path.rsplit("/", 1)[-1].startswith(EXACT_LOCK_FILE_PREFIX) for path in agfs.files)-- await lock.release(first)- assert not lock.is_locked(target)---async def test_exact_path_lock_conflicts_with_tree_lock():- agfs = _agfs_with_docs_dir()- lock = PathLockEngine(agfs)- exact = LockHandle(id="exact-a")- tree = LockHandle(id="tree-docs")- target = "/local/default/resources/docs/a.md"- docs = "/local/default/resources/docs"-- assert await lock.acquire_exact_path(target, exact)- assert not await lock.acquire_tree(docs, tree, timeout=0.0)-- await lock.release(exact)- assert await lock.acquire_tree(docs, tree, timeout=0.0)-- blocked = LockHandle(id="exact-blocked-by-tree")- assert not await lock.acquire_exact_path(target, blocked, timeout=0.0)-- await lock.release(tree)---async def test_exact_tree_batch_acquires_exact_and_tree_locks():- agfs = _agfs_with_docs_dir()- agfs.mkdir("/local/default/resources/docs/events")- manager = LockManager(agfs=agfs, lock_timeout=0.0, lock_expire=300.0)- handle = manager.create_handle()-- assert await manager.acquire_exact_tree_batch(- handle,- exact_paths=["/local/default/resources/docs/profile.md"],- tree_paths=["/local/default/resources/docs/events"],- )- assert len(handle.locks) == 2-- blocked = manager.create_handle()- assert not await manager.acquire_exact_tree_batch(- blocked,- exact_paths=["/local/default/resources/docs/profile.md"],- tree_paths=[],- )-- await manager.release(handle)- await manager.release(blocked)diff --git a/tests/transaction/test_lock_context.py b/tests/transaction/test_lock_context.pydeleted file mode 100644index a29580caa..000000000--- a/tests/transaction/test_lock_context.py+++ /dev/null@@ -1,110 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for LockContext async context manager."""--import uuid--import pytest--from openviking.storage.errors import LockAcquisitionError-from openviking.storage.transaction.lock_context import LockContext-from openviking.storage.transaction.lock_manager import LockManager-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME---def _lock_file_gone(agfs_client, lock_path: str) -> bool:- try:- agfs_client.stat(lock_path)- return False- except Exception:- return True---def lm(agfs_client):- return LockManager(agfs=agfs_client, lock_timeout=1.0, lock_expire=1.0)---class TestLockContextExact:- async def test_exact_lock_lifecycle(self, agfs_client, lm, test_dir):- async with LockContext(lm, [test_dir], lock_mode="exact") as handle:- assert handle is not None- lock_path = handle.locks[0]- token = agfs_client.cat(lock_path)- assert token is not None-- assert _lock_file_gone(agfs_client, lock_path)-- async def test_lock_released_on_exception(self, agfs_client, lm, test_dir):- lock_path = ""-- with pytest.raises(RuntimeError):- async with LockContext(lm, [test_dir], lock_mode="exact") as handle:- lock_path = handle.locks[0]- assert agfs_client.cat(lock_path) is not None- raise RuntimeError("fail")-- assert lock_path- assert _lock_file_gone(agfs_client, lock_path)-- async def test_exception_propagates(self, lm, test_dir):- with pytest.raises(ValueError, match="test"):- async with LockContext(lm, [test_dir], lock_mode="exact"):- raise ValueError("test")---class TestLockContextTree:- async def test_tree_lock(self, agfs_client, lm, test_dir):- async with LockContext(lm, [test_dir], lock_mode="tree"):- token = agfs_client.cat(f"{test_dir}/{LOCK_FILE_NAME}")- token_str = token.decode("utf-8") if isinstance(token, bytes) else token- assert ":T" in token_str---class TestLockContextMv:- async def test_mv_lock(self, agfs_client, lm, test_dir):- src = f"{test_dir}/src-{uuid.uuid4().hex}"- dst = f"{test_dir}/dst-{uuid.uuid4().hex}"- agfs_client.mkdir(src)- agfs_client.mkdir(dst)-- async with LockContext(lm, [src], lock_mode="mv", mv_dst_path=dst) as handle:- assert len(handle.locks) == 2---class TestLockContextFailure:- async def test_unsupported_lock_mode_raises(self, lm):- with pytest.raises(LockAcquisitionError):- async with LockContext(lm, ["/local/nonexistent-xyz"], lock_mode="unknown"):- pass-- async def test_handle_cleaned_up_on_failure(self, lm):- with pytest.raises(LockAcquisitionError):- async with LockContext(lm, ["/local/nonexistent-xyz"], lock_mode="unknown"):- pass-- assert len(await lm.get_active_handles_async()) == 0---class TestLockContextExternalHandle:- async def test_external_handle_reuses_existing_tree_lock(self, agfs_client, lm, test_dir):- lock_path = f"{test_dir}/{LOCK_FILE_NAME}"-- async with LockContext(lm, [test_dir], lock_mode="tree") as handle:- before = agfs_client.cat(lock_path)- before_token = before.decode("utf-8") if isinstance(before, bytes) else before- assert ":T" in before_token-- async with LockContext(lm, [test_dir], lock_mode="exact", handle=handle):- current = agfs_client.cat(lock_path)- current_token = current.decode("utf-8") if isinstance(current, bytes) else current- assert current_token == before_token- assert ":T" in current_token-- still_owned = agfs_client.cat(lock_path)- still_owned_token = (- still_owned.decode("utf-8") if isinstance(still_owned, bytes) else still_owned- )- assert still_owned_token == before_token-- assert _lock_file_gone(agfs_client, lock_path)diff --git a/tests/transaction/test_lock_manager.py b/tests/transaction/test_lock_manager.pydeleted file mode 100644index 209e9a816..000000000--- a/tests/transaction/test_lock_manager.py+++ /dev/null@@ -1,132 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for LockManager."""--import asyncio-import uuid-from unittest.mock import AsyncMock, MagicMock--import pytest--from openviking.storage.transaction.lock_manager import LockManager-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME---def _lock_file_gone(agfs_client, lock_path: str) -> bool:- try:- agfs_client.stat(lock_path)- return False- except Exception:- return True---def lm(agfs_client):- return LockManager(agfs=agfs_client, lock_timeout=1.0, lock_expire=1.0)---class TestLockManagerBasic:- async def test_create_handle_and_acquire_exact_path(self, agfs_client, lm, test_dir):- handle = lm.create_handle()- ok = await lm.acquire_exact_path(handle, test_dir)- assert ok is True-- lock_path = handle.locks[0]- content = agfs_client.cat(lock_path)- assert content is not None-- await lm.release(handle)- assert _lock_file_gone(agfs_client, lock_path)-- async def test_acquire_tree(self, agfs_client, lm, test_dir):- handle = lm.create_handle()- ok = await lm.acquire_tree(handle, test_dir)- assert ok is True-- token = agfs_client.cat(f"{test_dir}/{LOCK_FILE_NAME}")- token_str = token.decode("utf-8") if isinstance(token, bytes) else token- assert ":T" in token_str-- await lm.release(handle)-- async def test_acquire_mv(self, agfs_client, lm, test_dir):- src = f"{test_dir}/mv-src-{uuid.uuid4().hex}"- dst = f"{test_dir}/mv-dst-{uuid.uuid4().hex}"- agfs_client.mkdir(src)- agfs_client.mkdir(dst)-- handle = lm.create_handle()- ok = await lm.acquire_mv(handle, src, dst)- assert ok is True- assert len(handle.locks) == 2-- await lm.release(handle)- assert handle.id not in await lm.get_active_handles_async()-- async def test_release_removes_from_active(self, lm, test_dir):- handle = lm.create_handle()-- await lm.acquire_exact_path(handle, test_dir)- assert handle.id in await lm.get_active_handles_async()-- await lm.release(handle)-- assert handle.id not in await lm.get_active_handles_async()-- async def test_stop_releases_all(self, agfs_client, lm, test_dir):- h1 = lm.create_handle()- h2 = lm.create_handle()- await lm.acquire_exact_path(h1, test_dir)-- sub = f"{test_dir}/sub-{uuid.uuid4().hex}"- agfs_client.mkdir(sub)- await lm.acquire_exact_path(h2, sub)-- await lm.stop()- assert len(await lm.get_active_handles_async()) == 0-- async def test_exact_path_allows_missing_target(self, lm):- handle = lm.create_handle()- ok = await lm.acquire_exact_path(handle, "/local/nonexistent-xyz")- assert ok is True-- await lm.release(handle)-- async def test_explicit_none_timeout_passes_through_as_infinite_wait(self, lm):- handle = lm.create_handle()- lm._path_lock = MagicMock()- lm._path_lock.acquire_tree = AsyncMock(return_value=True)-- ok = await lm.acquire_tree(handle, "/local/test", timeout=None)-- assert ok is True- lm._path_lock.acquire_tree.assert_awaited_once_with("/local/test", handle, timeout=None)-- async def test_recover_pending_redo_preserves_cancelled_error(self, lm):- lm._redo_log = MagicMock()- lm._redo_log.list_pending_async = AsyncMock(return_value=["redo-task"])- lm._redo_log.read_async = AsyncMock(return_value={"archive_uri": "a", "session_uri": "b"})- lm._redo_log.mark_done_async = AsyncMock()- lm._redo_session_memory = AsyncMock(side_effect=asyncio.CancelledError("shutdown"))-- with pytest.raises(asyncio.CancelledError):- await lm._recover_pending_redo()-- lm._redo_log.mark_done_async.assert_not_awaited()-- async def test_start_skips_redo_recovery_when_disabled(self, client):- lm_disabled = LockManager(- agfs=client._client.service._agfs_client,- lock_timeout=1.0,- lock_expire=1.0,- redo_recovery_enabled=False,- )- lm_disabled._recover_pending_redo = AsyncMock()-- await lm_disabled.start()- await asyncio.sleep(0)-- assert lm_disabled._redo_task is None- lm_disabled._recover_pending_redo.assert_not_called()-- await lm_disabled.stop()diff --git a/tests/transaction/test_lock_manager_staleness.py b/tests/transaction/test_lock_manager_staleness.pydeleted file mode 100644index 92dd87f5c..000000000--- a/tests/transaction/test_lock_manager_staleness.py+++ /dev/null@@ -1,80 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Unit tests for LockManager staleness tracking."""--from unittest.mock import AsyncMock, MagicMock--from openviking.storage.transaction.lock_manager import LockManager-from openviking.storage.transaction.path_lock import LockRefreshResult---async def test_refresh_lock_updates_last_active_without_changing_created_at(monkeypatch):- lm = LockManager(agfs=MagicMock(), lock_expire=300.0)- handle = lm.create_handle()- handle.created_at = 100.0- handle.last_active_at = 100.0- handle.add_lock("/local/tx/.path.ovlock")- lm._path_lock.collect_lost_owner_locks = lambda owner: []- lm._path_lock.collect_lost_owner_locks_async = AsyncMock(return_value=[])- lm._path_lock.refresh = AsyncMock(- return_value=LockRefreshResult(refreshed_paths=["/local/tx/.path.ovlock"])- )-- monkeypatch.setattr("openviking.storage.transaction.lock_manager.time.time", lambda: 250.0)-- await lm.refresh_lock(handle)-- lm._path_lock.refresh.assert_awaited_once_with(handle)- assert handle.created_at == 100.0- assert handle.last_active_at == 250.0---async def test_stale_cleanup_releases_only_inactive_handles(monkeypatch):- lm = LockManager(agfs=MagicMock(), lock_expire=300.0)-- active_handle = lm.create_handle()- active_handle.created_at = 0.0- active_handle.last_active_at = 200.0- active_handle.add_lock("/local/active/.path.ovlock")-- stale_handle = lm.create_handle()- stale_handle.created_at = 0.0- stale_handle.last_active_at = 0.0- stale_handle.add_lock("/local/stale/.path.ovlock")-- unlocked_handle = lm.create_handle()- unlocked_handle.created_at = 0.0- unlocked_handle.last_active_at = 0.0-- released = []-- async def fake_sleep(_seconds):- lm._running = False-- async def fake_release(handle):- released.append(handle.id)- lm._handles.pop(handle.id, None)-- monkeypatch.setattr("openviking.storage.transaction.lock_manager.asyncio.sleep", fake_sleep)- monkeypatch.setattr("openviking.storage.transaction.lock_manager.time.time", lambda: 400.0)- monkeypatch.setattr(lm, "release", fake_release)- lm._path_lock.collect_lost_owner_locks = lambda owner: []- lm._path_lock.collect_lost_owner_locks_async = AsyncMock(return_value=[])-- lm._running = True- await lm._stale_cleanup_loop()-- assert released == [stale_handle.id]- active_handles = await lm.get_active_handles_async()- assert active_handle.id in active_handles- assert unlocked_handle.id not in active_handles---def test_get_handle_returns_none_when_lock_ownership_is_lost():- lm = LockManager(agfs=MagicMock(), lock_expire=300.0)- handle = lm.create_handle()- handle.add_lock("/local/stale/.path.ovlock")- lm._path_lock.collect_lost_owner_locks = lambda owner: list(owner.locks)-- assert lm.get_handle(handle.id) is None- assert handle.id not in lm.get_active_handles()diff --git a/tests/transaction/test_lock_reentrancy_unit.py b/tests/transaction/test_lock_reentrancy_unit.pydeleted file mode 100644index 39986e732..000000000--- a/tests/transaction/test_lock_reentrancy_unit.py+++ /dev/null@@ -1,141 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0--from __future__ import annotations--import os--import pytest--from openviking.storage.transaction.lock_context import LockContext-from openviking.storage.transaction.lock_manager import LockManager-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME, PathLockEngine---class _FakeAGFS:- def __init__(self):- self._dirs = {"/"}- self._files = {}-- def stat(self, path: str):- if path in self._dirs:- return {"isDir": True}- if path in self._files:- return {"isDir": False}- raise FileNotFoundError(path)-- def mkdir(self, path: str):- current = ""- for part in path.split("/"):- if not part:- current = "/"- continue- current = os.path.join(current, part) if current != "/" else f"/{part}"- self._dirs.add(current)-- def write(self, path: str, data: bytes):- parent = os.path.dirname(path) or "/"- self.mkdir(parent)- self._files[path] = data-- def read(self, path: str):- if path not in self._files:- raise FileNotFoundError(path)- return self._files[path]-- def rm(self, path: str, recursive: bool = False):- if path in self._files:- self._files.pop(path, None)- return- if path not in self._dirs:- raise FileNotFoundError(path)- prefix = path.rstrip("/") + "/"- has_children = any(- child.startswith(prefix)- for child in self._dirs | set(self._files.keys())- if child != path- )- if has_children and not recursive:- raise OSError("directory not empty")- for child in list(self._files.keys()):- if child.startswith(prefix):- self._files.pop(child, None)- for child in sorted(self._dirs, reverse=True):- if child == path or child.startswith(prefix):- self._dirs.discard(child)-- def ls(self, path: str):- if path not in self._dirs:- raise FileNotFoundError(path)- prefix = path.rstrip("/") + "/"- children = {}- for child in self._dirs:- if not child.startswith(prefix) or child == path:- continue- rest = child[len(prefix) :]- if "/" in rest or not rest:- continue- children[rest] = {"name": rest, "isDir": True}- for child in self._files:- if not child.startswith(prefix):- continue- rest = child[len(prefix) :]- if "/" in rest or not rest:- continue- children[rest] = {"name": rest, "isDir": False}- return list(children.values())---async def test_path_lock_reuses_same_owner_tree_without_overwriting_token():- agfs = _FakeAGFS()- agfs.mkdir("/root")- lock = PathLockEngine(agfs)- handle = LockManager(agfs).create_handle()-- assert await lock.acquire_tree("/root", handle, timeout=0.1) is True- lock_path = f"/root/{LOCK_FILE_NAME}"- before = agfs.read(lock_path).decode("utf-8")- assert before.endswith(":T")-- assert await lock.acquire_exact_path("/root", handle, timeout=0.1) is True- after = agfs.read(lock_path).decode("utf-8")- assert after == before- assert after.endswith(":T")---async def test_path_lock_reuses_ancestor_tree_without_creating_child_lock():- agfs = _FakeAGFS()- agfs.mkdir("/root")- agfs.mkdir("/root/child")- lock = PathLockEngine(agfs)- handle = LockManager(agfs).create_handle()-- assert await lock.acquire_tree("/root", handle, timeout=0.1) is True- assert await lock.acquire_exact_path("/root/child", handle, timeout=0.1) is True-- with pytest.raises(FileNotFoundError):- agfs.read(f"/root/child/{LOCK_FILE_NAME}")---async def test_lock_context_with_external_handle_keeps_outer_tree_lock():- agfs = _FakeAGFS()- agfs.mkdir("/root")- lm = LockManager(agfs=agfs, lock_timeout=0.1, lock_expire=60.0)- lock_path = f"/root/{LOCK_FILE_NAME}"-- async with LockContext(lm, ["/root"], lock_mode="tree") as handle:- before = agfs.read(lock_path).decode("utf-8")- assert before.endswith(":T")-- async with LockContext(lm, ["/root"], lock_mode="exact", handle=handle):- current = agfs.read(lock_path).decode("utf-8")- assert current == before-- still_owned = agfs.read(lock_path).decode("utf-8")- assert still_owned == before-- with pytest.raises(FileNotFoundError):- agfs.read(lock_path)diff --git a/tests/transaction/test_path_lock.py b/tests/transaction/test_path_lock.pydeleted file mode 100644index fd2dd2a75..000000000--- a/tests/transaction/test_path_lock.py+++ /dev/null@@ -1,689 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for path lock with fencing tokens."""--import time-from unittest.mock import AsyncMock, MagicMock--from openviking.storage.transaction import path_lock as path_lock_module-from openviking.storage.transaction.lock_handle import LockHandle-from openviking.storage.transaction.path_lock import (- EXACT_LOCK_FILE_PREFIX,- LOCK_FILE_NAME,- LOCK_TYPE_EXACT,- LOCK_TYPE_TREE,- PathLockEngine,- _make_fencing_token,- _parse_fencing_token,-)---def _single_lock_path(handle: LockHandle) -> str:- assert len(handle.locks) == 1- return handle.locks[0]---class TestFencingToken:- def test_make_parse_roundtrip(self):- token = _make_fencing_token("tx-123")- tx_id, ts, lock_type = _parse_fencing_token(token)- assert tx_id == "tx-123"- assert ts > 0- assert lock_type == LOCK_TYPE_EXACT-- def test_make_parse_tree_roundtrip(self):- token = _make_fencing_token("tx-456", LOCK_TYPE_TREE)- tx_id, ts, lock_type = _parse_fencing_token(token)- assert tx_id == "tx-456"- assert ts > 0- assert lock_type == LOCK_TYPE_TREE-- def test_parse_previous_tree_tokens(self):- for previous_type in ("P", "S"):- tx_id, ts, lock_type = _parse_fencing_token(f"tx-old:123:{previous_type}")- assert tx_id == "tx-old"- assert ts == 123- assert lock_type == LOCK_TYPE_TREE-- def test_parse_untyped_token_defaults_to_stale_exact(self):- """Untyped tokens are treated as stale EXACT locks."""- tx_id, ts, lock_type = _parse_fencing_token("tx-old:1234567890")- assert tx_id == "tx-old:1234567890"- assert ts == 0- assert lock_type == LOCK_TYPE_EXACT-- def test_parse_plain_token_defaults_to_exact(self):- """Plain tx_id (no colon) defaults to ts=0, lock_type=EXACT."""- tx_id, ts, lock_type = _parse_fencing_token("tx-bare")- assert tx_id == "tx-bare"- assert ts == 0- assert lock_type == LOCK_TYPE_EXACT-- def test_tokens_are_unique(self):- t1 = _make_fencing_token("tx-1")- time.sleep(0.001)- t2 = _make_fencing_token("tx-1")- assert t1 != t2---class TestPathLockStale:- def test_is_lock_stale_no_file(self):- agfs = MagicMock()- agfs.read.side_effect = Exception("not found")- lock = PathLockEngine(agfs)- assert lock.is_lock_stale("/test/.path.ovlock") is True-- def test_is_lock_stale_for_plain_token(self):- agfs = MagicMock()- agfs.read.return_value = b"tx-old-format"- lock = PathLockEngine(agfs)- assert lock.is_lock_stale("/test/.path.ovlock") is True-- def test_is_lock_stale_recent_token(self):- agfs = MagicMock()- token = _make_fencing_token("tx-1")- agfs.read.return_value = token.encode("utf-8")- lock = PathLockEngine(agfs)- assert lock.is_lock_stale("/test/.path.ovlock", expire_seconds=300.0) is False---class TestPathLockIsLocked:- def _agfs_with_locks(self, locks: dict[str, bytes]) -> MagicMock:- """Build an AGFS mock that only returns content for paths in *locks*."""- agfs = MagicMock()-- def _read(p):- if p in locks:- return locks[p]- raise Exception("not found")-- agfs.read.side_effect = _read- return agfs-- def test_is_locked_no_lock(self):- agfs = self._agfs_with_locks({})- lock = PathLockEngine(agfs)- assert lock.is_locked("/local/u/foo") is False-- def test_is_locked_self_exact_lock(self):- token = _make_fencing_token("tx-1", LOCK_TYPE_EXACT)- agfs = self._agfs_with_locks({"/local/u/foo/.path.ovlock": token.encode("utf-8")})- lock = PathLockEngine(agfs)- assert lock.is_locked("/local/u/foo") is True-- def test_is_locked_ancestor_tree_lock(self):- token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)- agfs = self._agfs_with_locks({"/local/u/.path.ovlock": token.encode("utf-8")})- lock = PathLockEngine(agfs)- assert lock.is_locked("/local/u/foo/bar") is True-- def test_is_locked_ancestor_exact_lock_does_not_propagate(self):- """An ancestor EXACT lock must not affect descendants -- EXACT locks only the path itself."""- token = _make_fencing_token("tx-1", LOCK_TYPE_EXACT)- agfs = self._agfs_with_locks({"/local/u/.path.ovlock": token.encode("utf-8")})- lock = PathLockEngine(agfs)- assert lock.is_locked("/local/u/foo/bar") is False-- def test_is_locked_ignores_stale_by_default(self):- old_ts = time.time_ns() - int(600 * 1e9) # 600s ago- stale = f"tx-dead:{old_ts}:{LOCK_TYPE_EXACT}".encode("utf-8")- agfs = self._agfs_with_locks({"/local/u/foo/.path.ovlock": stale})- lock = PathLockEngine(agfs, lock_expire=300.0)- assert lock.is_locked("/local/u/foo") is False-- def test_is_locked_can_include_stale(self):- old_ts = time.time_ns() - int(600 * 1e9)- stale = f"tx-dead:{old_ts}:{LOCK_TYPE_EXACT}".encode("utf-8")- agfs = self._agfs_with_locks({"/local/u/foo/.path.ovlock": stale})- lock = PathLockEngine(agfs, lock_expire=300.0)- assert lock.is_locked("/local/u/foo", ignore_stale=False) is True-- async def test_is_locked_async_uses_async_agfs_path(self):- token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)- agfs = self._agfs_with_locks({"/local/u/.path.ovlock": token.encode("utf-8")})- lock = PathLockEngine(agfs)-- assert await lock.is_locked_async("/local/u/foo/bar") is True-- def test_is_locked_sync_passes_path_derived_ctx(self):- token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)- seen: list[dict[str, str] | None] = []-- class _CtxAwareAgfs:- def read(self, path, *, ctx=None):- seen.append(ctx)- if path == "/local/u/.path.ovlock":- return token.encode("utf-8")- raise Exception("not found")-- def stat(self, path, *, ctx=None):- seen.append(ctx)- raise Exception("not found")-- lock = PathLockEngine(_CtxAwareAgfs())-- assert lock.is_locked("/local/u/foo/bar") is True- assert {"account_id": "u"} in seen---class TestPathLockOwnership:- async def test_refresh_reports_refreshed_lost_and_failed_paths(self):- owned_path = "/locks/owned/.path.ovlock"- lost_path = "/locks/lost/.path.ovlock"- missing_path = "/locks/missing/.path.ovlock"- failed_path = "/locks/failed/.path.ovlock"-- tokens = {- owned_path: _make_fencing_token("tx-1", LOCK_TYPE_EXACT),- lost_path: _make_fencing_token("tx-2", LOCK_TYPE_TREE),- failed_path: _make_fencing_token("tx-1", LOCK_TYPE_TREE),- }- agfs = MagicMock()-- def read_side_effect(lock_path):- if lock_path == missing_path:- raise FileNotFoundError(lock_path)- return tokens[lock_path].encode("utf-8")-- def write_side_effect(lock_path, content):- if lock_path == failed_path:- raise OSError("write failed")- tokens[lock_path] = content.decode("utf-8")-- agfs.read.side_effect = read_side_effect- agfs.write.side_effect = write_side_effect-- lock = PathLockEngine(agfs)- tx = LockHandle(id="tx-1")- for lock_path in [owned_path, lost_path, missing_path, failed_path]:- tx.add_lock(lock_path)-- result = await lock.refresh(tx)-- assert result.refreshed_paths == [owned_path]- assert set(result.lost_paths) == {lost_path, missing_path}- assert result.failed_paths == [failed_path]-- async def test_release_skips_locks_no_longer_owned(self):- owned_path = "/locks/owned/.path.ovlock"- replaced_path = "/locks/replaced/.path.ovlock"-- tokens = {- owned_path: _make_fencing_token("tx-1", LOCK_TYPE_EXACT),- replaced_path: _make_fencing_token("tx-2", LOCK_TYPE_EXACT),- }- agfs = MagicMock()- agfs.read.side_effect = lambda lock_path: tokens[lock_path].encode("utf-8")-- lock = PathLockEngine(agfs)- lock._remove_lock_file = AsyncMock(return_value=True)- tx = LockHandle(id="tx-1")- tx.add_lock(owned_path)- tx.add_lock(replaced_path)-- await lock.release(tx)-- lock._remove_lock_file.assert_awaited_once_with(owned_path)- assert tx.locks == []---class TestPathLockBehavior:- """Behavioral tests using real AGFS backend."""-- async def test_acquire_exact_path_creates_lock_file(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-exact-1")-- ok = await lock.acquire_exact_path(test_dir, tx, timeout=3.0)- assert ok is True-- lock_path = _single_lock_path(tx)- assert lock_path == f"{test_dir}/{LOCK_FILE_NAME}"- content = agfs_client.cat(lock_path)- token = content.decode("utf-8") if isinstance(content, bytes) else content- assert ":E" in token- assert "tx-exact-1" in token-- await lock.release(tx)-- async def test_acquire_tree_creates_lock_file(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-tree-1")-- ok = await lock.acquire_tree(test_dir, tx, timeout=3.0)- assert ok is True-- lock_path = f"{test_dir}/{LOCK_FILE_NAME}"- content = agfs_client.cat(lock_path)- token = content.decode("utf-8") if isinstance(content, bytes) else content- assert ":T" in token- assert "tx-tree-1" in token-- await lock.release(tx)-- async def test_acquire_tree_existing_file_uses_parent_sidecar_lock(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-tree-file")- file_path = f"{test_dir}/profile.md"- agfs_client.write(file_path, b"# Profile\n")-- ok = await lock.acquire_tree(file_path, tx, timeout=3.0)- assert ok is True-- lock_path = _single_lock_path(tx)- assert lock_path.startswith(f"{test_dir}/{EXACT_LOCK_FILE_PREFIX}profile.md.")- assert lock_path != f"{file_path}/{LOCK_FILE_NAME}"- content = agfs_client.cat(lock_path)- token = content.decode("utf-8") if isinstance(content, bytes) else content- assert ":T" in token- assert "tx-tree-file" in token-- await lock.release(tx)- try:- agfs_client.stat(lock_path)- raise AssertionError("file tree lock should have been removed")- except AssertionError:- raise- except Exception:- pass-- async def test_acquire_tree_existing_file_sidecar_sanitizes_name(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-tree-file-special")- file_path = f"{test_dir}/profile with spaces \u4e2d.md"- agfs_client.write(file_path, b"# Profile\n")-- ok = await lock.acquire_tree(file_path, tx, timeout=3.0)- assert ok is True-- lock_path = _single_lock_path(tx)- assert lock_path.startswith(f"{test_dir}/{EXACT_LOCK_FILE_PREFIX}profile_with_spaces")- assert lock_path.endswith(lock._get_prefixed_exact_lock_path(file_path).rsplit(".", 1)[-1])- content = agfs_client.cat(lock_path)- token = content.decode("utf-8") if isinstance(content, bytes) else content- assert ":T" in token-- await lock.release(tx)-- async def test_acquire_tree_existing_file_blocks_second_owner_until_release(- self, agfs_client, test_dir- ):- lock = PathLockEngine(agfs_client)- tx1 = LockHandle(id="tx-tree-file-hold")- tx2 = LockHandle(id="tx-tree-file-wait")- file_path = f"{test_dir}/blocked.md"- agfs_client.write(file_path, b"# Blocked\n")-- assert await lock.acquire_tree(file_path, tx1, timeout=3.0) is True- assert await lock.acquire_tree(file_path, tx2, timeout=0.0) is False-- await lock.release(tx1)-- assert await lock.acquire_tree(file_path, tx2, timeout=3.0) is True- await lock.release(tx2)-- async def test_acquire_tree_creates_missing_directory_after_conflict_check(- self, agfs_client, test_dir- ):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-tree-missing")- target = f"{test_dir}/new-resource"-- ok = await lock.acquire_tree(target, tx, timeout=3.0)- assert ok is True- assert _single_lock_path(tx) == f"{target}/{LOCK_FILE_NAME}"- assert agfs_client.stat(target).get("isDir") is True-- await lock.release(tx)-- async def test_tree_blocked_by_ancestor_tree_does_not_create_missing_directory(- self, agfs_client, test_dir- ):- lock = PathLockEngine(agfs_client)- parent = LockHandle(id="tx-parent-tree")- child = LockHandle(id="tx-child-tree")- target = f"{test_dir}/blocked-resource"-- assert await lock.acquire_tree(test_dir, parent, timeout=3.0) is True- assert await lock.acquire_tree(target, child, timeout=0.0) is False-- try:- agfs_client.stat(target)- raise AssertionError("missing TreeLock target should not be created on conflict")- except AssertionError:- raise- except Exception:- pass-- await lock.release(parent)-- async def test_fail_fast_tree_conflict_warning_is_throttled(- self, agfs_client, test_dir, monkeypatch- ):- lock = PathLockEngine(agfs_client)- parent = LockHandle(id="tx-parent-tree")- child = LockHandle(id="tx-child-tree")- child_retry = LockHandle(id="tx-child-tree-retry")- target = f"{test_dir}/blocked-resource"-- assert await lock.acquire_tree(test_dir, parent, timeout=3.0) is True-- warnings = []- debug_logs = []- path_lock_module._last_timeout_warning_at.clear()- monkeypatch.setattr(path_lock_module.logger, "warning", warnings.append)- monkeypatch.setattr(path_lock_module.logger, "debug", debug_logs.append)-- assert await lock.acquire_tree(target, child, timeout=0.0) is False- assert await lock.acquire_tree(target, child_retry, timeout=0.0) is False-- timeout_warnings = [message for message in warnings if "Timeout waiting" in message]- assert len(timeout_warnings) == 1- assert "Timeout waiting for ancestor TREE lock" in timeout_warnings[0]- assert debug_logs == []-- await lock.release(parent)-- async def test_acquire_exact_path_allows_missing_target(self, agfs_client):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-no-dir")-- ok = await lock.acquire_exact_path("/local/nonexistent-path-xyz", tx, timeout=0.5)- assert ok is True- assert len(tx.locks) == 1- assert tx.locks[0].rsplit("/", 1)[-1].startswith(EXACT_LOCK_FILE_PREFIX)-- await lock.release(tx)-- async def test_exact_blocked_by_ancestor_tree_does_not_create_missing_parent(- self, agfs_client, test_dir- ):- lock = PathLockEngine(agfs_client)- parent = LockHandle(id="tx-parent-tree")- child = LockHandle(id="tx-child-exact")- missing_parent = f"{test_dir}/blocked-dir"- target = f"{missing_parent}/file.md"-- assert await lock.acquire_tree(test_dir, parent, timeout=3.0) is True- assert await lock.acquire_exact_path(target, child, timeout=0.0) is False-- try:- agfs_client.stat(missing_parent)- raise AssertionError("missing exact-lock parent should not be created on conflict")- except AssertionError:- raise- except Exception:- pass-- await lock.release(parent)-- async def test_release_removes_lock_file(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-release-1")-- await lock.acquire_exact_path(test_dir, tx, timeout=3.0)- lock_path = _single_lock_path(tx)-- await lock.release(tx)-- # Lock file should be gone (use stat, not cat — cat returns b'' for deleted files)- try:- agfs_client.stat(lock_path)- raise AssertionError("Lock file should have been removed")- except AssertionError:- raise- except Exception:- pass # Expected: file not found-- async def test_sequential_acquire_works(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)-- tx1 = LockHandle(id="tx-seq-1")- ok1 = await lock.acquire_exact_path(test_dir, tx1, timeout=3.0)- assert ok1 is True-- await lock.release(tx1)-- tx2 = LockHandle(id="tx-seq-2")- ok2 = await lock.acquire_exact_path(test_dir, tx2, timeout=3.0)- assert ok2 is True-- await lock.release(tx2)-- async def test_exact_blocked_by_ancestor_tree(self, agfs_client, test_dir):- """EXACT on child blocked while ancestor holds TreeLock."""- import uuid as _uuid-- child = f"{test_dir}/child-{_uuid.uuid4().hex}"- agfs_client.mkdir(child)-- lock = PathLockEngine(agfs_client)- tx_parent = LockHandle(id="tx-parent-tree")- ok = await lock.acquire_tree(test_dir, tx_parent, timeout=3.0)- assert ok is True-- tx_child = LockHandle(id="tx-child-exact")- blocked = await lock.acquire_exact_path(child, tx_child, timeout=0.5)- assert blocked is False-- await lock.release(tx_parent)-- async def test_tree_blocked_by_descendant_exact(self, agfs_client, test_dir):- """TreeLock on parent blocked while descendant holds ExactPathLock."""- import uuid as _uuid-- child = f"{test_dir}/child-{_uuid.uuid4().hex}"- agfs_client.mkdir(child)-- lock = PathLockEngine(agfs_client)- tx_child = LockHandle(id="tx-desc-exact")- ok = await lock.acquire_exact_path(child, tx_child, timeout=3.0)- assert ok is True-- tx_parent = LockHandle(id="tx-parent-tree")- blocked = await lock.acquire_tree(test_dir, tx_parent, timeout=0.5)- assert blocked is False-- await lock.release(tx_child)-- async def test_acquire_mv_creates_tree_and_exact_locks(self, agfs_client, test_dir):- """Directory move locks the source tree and exact destination path."""- import uuid as _uuid-- src = f"{test_dir}/src-{_uuid.uuid4().hex}"- dst = f"{test_dir}/dst-{_uuid.uuid4().hex}"- agfs_client.mkdir(src)- agfs_client.mkdir(dst)-- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-mv-1")- ok = await lock.acquire_mv(src, dst, tx, timeout=3.0)- assert ok is True-- src_token_bytes = agfs_client.cat(f"{src}/{LOCK_FILE_NAME}")- src_token = (- src_token_bytes.decode("utf-8")- if isinstance(src_token_bytes, bytes)- else src_token_bytes- )- assert ":T" in src_token-- dst_token_bytes = agfs_client.cat(f"{dst}/{LOCK_FILE_NAME}")- dst_token = (- dst_token_bytes.decode("utf-8")- if isinstance(dst_token_bytes, bytes)- else dst_token_bytes- )- assert ":E" in dst_token-- await lock.release(tx)-- async def test_exact_does_not_block_sibling_exact(self, agfs_client, test_dir):- """EXACT locks on different directories do not conflict."""- import uuid as _uuid-- dir_a = f"{test_dir}/sibling-a-{_uuid.uuid4().hex}"- dir_b = f"{test_dir}/sibling-b-{_uuid.uuid4().hex}"- agfs_client.mkdir(dir_a)- agfs_client.mkdir(dir_b)-- lock = PathLockEngine(agfs_client)- tx_a = LockHandle(id="tx-sib-a")- tx_b = LockHandle(id="tx-sib-b")-- ok_a = await lock.acquire_exact_path(dir_a, tx_a, timeout=3.0)- ok_b = await lock.acquire_exact_path(dir_b, tx_b, timeout=3.0)-- assert ok_a is True- assert ok_b is True-- await lock.release(tx_a)- await lock.release(tx_b)-- async def test_stale_lock_auto_removed_on_acquire(self, agfs_client, test_dir):- """A stale lock (expired fencing token) is auto-removed, allowing a new acquire."""- import uuid as _uuid-- target = f"{test_dir}/stale-{_uuid.uuid4().hex}"- agfs_client.mkdir(target)-- lock = PathLockEngine(agfs_client, lock_expire=300.0)- lock_path = lock._get_exact_lock_path(target)-- # Write a lock file with a very old timestamp (simulate crashed process)- old_ts = time.time_ns() - int(600 * 1e9) # 600 seconds ago- stale_token = f"tx-dead:{old_ts}:{LOCK_TYPE_EXACT}"- agfs_client.write(lock_path, stale_token.encode("utf-8"))-- # New transaction should succeed by auto-removing the stale lock- tx = LockHandle(id="tx-new-owner")- ok = await lock.acquire_exact_path(target, tx, timeout=2.0)- assert ok is True-- # Verify new lock is owned by our transaction- content = agfs_client.cat(lock_path)- token = content.decode("utf-8") if isinstance(content, bytes) else content- assert "tx-new-owner" in token-- await lock.release(tx)-- async def test_stale_tree_ancestor_auto_removed(self, agfs_client, test_dir):- """A stale TreeLock on ancestor is auto-removed when child acquires ExactPathLock."""- import uuid as _uuid-- child = f"{test_dir}/child-stale-{_uuid.uuid4().hex}"- agfs_client.mkdir(child)-- # Write stale TreeLock on parent- parent_lock = f"{test_dir}/{LOCK_FILE_NAME}"- old_ts = time.time_ns() - int(600 * 1e9)- stale_token = f"tx-dead-parent:{old_ts}:{LOCK_TYPE_TREE}"- agfs_client.write(parent_lock, stale_token.encode("utf-8"))-- lock = PathLockEngine(agfs_client, lock_expire=300.0)- tx = LockHandle(id="tx-child-new")- ok = await lock.acquire_exact_path(child, tx, timeout=2.0)- assert ok is True-- await lock.release(tx)- # Clean up stale parent lock if still present- try:- agfs_client.rm(parent_lock)- except Exception:- pass-- async def test_exact_same_path_no_wait_fails_immediately(self, agfs_client, test_dir):- """With timeout=0, a conflicting lock fails immediately."""- import uuid as _uuid-- target = f"{test_dir}/nowait-{_uuid.uuid4().hex}"- agfs_client.mkdir(target)-- lock = PathLockEngine(agfs_client)- tx1 = LockHandle(id="tx-hold")- ok1 = await lock.acquire_exact_path(target, tx1, timeout=3.0)- assert ok1 is True-- # Second acquire with timeout=0 should fail immediately- tx2 = LockHandle(id="tx-blocked")- t0 = time.monotonic()- ok2 = await lock.acquire_exact_path(target, tx2, timeout=0.0)- elapsed = time.monotonic() - t0-- assert ok2 is False- assert elapsed < 1.0 # Should not wait-- await lock.release(tx1)-- async def test_tree_same_path_mutual_exclusion(self, agfs_client, test_dir):- """Two TreeLocks on the same path: second one blocked until first releases."""- import uuid as _uuid-- target = f"{test_dir}/tree-excl-{_uuid.uuid4().hex}"- agfs_client.mkdir(target)-- lock = PathLockEngine(agfs_client)- tx1 = LockHandle(id="tx-tree1")- ok1 = await lock.acquire_tree(target, tx1, timeout=3.0)- assert ok1 is True-- tx2 = LockHandle(id="tx-tree2")- ok2 = await lock.acquire_tree(target, tx2, timeout=0.5)- assert ok2 is False-- await lock.release(tx1)-- # Now tx2 should succeed- ok2_retry = await lock.acquire_tree(target, tx2, timeout=3.0)- assert ok2_retry is True- await lock.release(tx2)-- async def test_exact_reuses_same_owner_tree_lock_on_same_path(self, agfs_client, test_dir):- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-reentrant-same-path")-- ok = await lock.acquire_tree(test_dir, tx, timeout=3.0)- assert ok is True-- lock_path = f"{test_dir}/{LOCK_FILE_NAME}"- before = agfs_client.cat(lock_path)- before_token = before.decode("utf-8") if isinstance(before, bytes) else before- assert ":T" in before_token-- ok_reuse = await lock.acquire_exact_path(test_dir, tx, timeout=0.5)- assert ok_reuse is True-- after = agfs_client.cat(lock_path)- after_token = after.decode("utf-8") if isinstance(after, bytes) else after- assert after_token == before_token- assert ":T" in after_token-- await lock.release(tx)-- async def test_exact_under_same_owner_tree_does_not_create_child_lock(- self, agfs_client, test_dir- ):- import uuid as _uuid-- child = f"{test_dir}/child-reentrant-{_uuid.uuid4().hex}"- agfs_client.mkdir(child)-- lock = PathLockEngine(agfs_client)- tx = LockHandle(id="tx-reentrant-child")-- ok = await lock.acquire_tree(test_dir, tx, timeout=3.0)- assert ok is True-- ok_child = await lock.acquire_exact_path(child, tx, timeout=0.5)- assert ok_child is True-- child_lock_path = lock._get_exact_lock_path(child)- try:- agfs_client.stat(child_lock_path)- raise AssertionError("child lock should not be created when ancestor tree is owned")- except AssertionError:- raise- except Exception:- pass-- await lock.release(tx)diff --git a/tests/unit/test_resource_reservation.py b/tests/unit/test_resource_reservation.pyindex 9e87a3c3a..a80f7a07e 100644--- a/tests/unit/test_resource_reservation.py+++ b/tests/unit/test_resource_reservation.py@@ -25,10 +25,6 @@ def _make_processor(monkeypatch, *, existing=()):processor = ResourceProcessor.__new__(ResourceProcessor)viking_fs = _FakeVikingFS(existing)monkeypatch.setattr(resource_processor_module, "get_viking_fs", lambda: viking_fs)- monkeypatch.setattr(- "openviking.storage.transaction.get_lock_manager",- lambda: object(),- )return processordiff --git a/tests/utils/test_resource_processor_processing_mode.py b/tests/utils/test_resource_processor_processing_mode.pyindex d2b39836c..6c199a7cf 100644--- a/tests/utils/test_resource_processor_processing_mode.py+++ b/tests/utils/test_resource_processor_processing_mode.py@@ -50,6 +50,7 @@ def ctx() -> RequestContext:@pytest.mark.asyncioasync def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch, ctx):viking_fs = SimpleNamespace(+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),persist_temp_tree=AsyncMock(),delete_temp=AsyncMock(),tree=AsyncMock(@@ -78,7 +79,7 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,processor._delete_resource_semantic_markers = AsyncMock()processor._delete_resource_semantic_vectors = AsyncMock()processor._delete_removed_resource_vectors = AsyncMock()- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())+ lock = {"lease_ref": "lock-1"}result = await processor.finish_prepared_resource({@@ -96,12 +97,15 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,assert result == {"status": "success", "root_uri": "viking://resources/demo"}viking_fs.persist_temp_tree.assert_awaited_once_with(- "viking://temp/demo", "viking://resources/demo", ctx=ctx+ "viking://temp/demo",+ "viking://resources/demo",+ ctx=ctx,+ lease_ref=lock,)rewrite_image_uris.assert_awaited_once_with("viking://resources/demo",ctx=ctx,- lock_handle="lock-1",+ lease_ref=lock,)viking_fs.delete_temp.assert_awaited_once_with("tmp/demo", ctx=ctx)vectorize_file.assert_awaited_once()@@ -120,12 +124,13 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,assert vectorize_file.await_args.kwargs["register_request_wait"] is Trueprocessor._delete_resource_semantic_markers.assert_not_awaited()processor._delete_resource_semantic_vectors.assert_not_awaited()- lock.close.assert_awaited_once()+ viking_fs._async_agfs.pathlock_release.assert_awaited_once_with(lock)@pytest.mark.asyncioasync def test_vectors_only_skips_vectorization_when_build_index_false(monkeypatch, ctx):viking_fs = SimpleNamespace(+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),persist_temp_tree=AsyncMock(),delete_temp=AsyncMock(),tree=AsyncMock(return_value=[]),@@ -137,7 +142,7 @@ async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypatprocessor = ResourceProcessor(_FakeVikingDB())processor._delete_resource_semantic_markers = AsyncMock()processor._delete_resource_semantic_vectors = AsyncMock()- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())+ lock = {"lease_ref": "lock-1"}await processor.finish_prepared_resource({@@ -159,6 +164,7 @@ async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypat@pytest.mark.asyncioasync def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypatch, ctx):viking_fs = SimpleNamespace(+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),persist_temp_tree=AsyncMock(),delete_temp=AsyncMock(),tree=AsyncMock(return_value=[]),@@ -174,7 +180,7 @@ async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypamonkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())processor = ResourceProcessor(_FakeVikingDB())processor._delete_resource_semantic_vectors = AsyncMock()- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())+ lock = {"lease_ref": "lock-1"}await processor.finish_prepared_resource({@@ -202,6 +208,7 @@ async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypa@pytest.mark.asyncioasync def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypatch, ctx):viking_fs = SimpleNamespace(+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),persist_temp_tree=AsyncMock(),delete_temp=AsyncMock(),tree=AsyncMock(return_value=[]),@@ -212,7 +219,7 @@ async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypatprocessor = ResourceProcessor(_FakeVikingDB())processor._delete_resource_semantic_vectors = AsyncMock()processor._delete_removed_resource_vectors = AsyncMock()- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())+ lock = {"lease_ref": "lock-1"}await processor.finish_prepared_resource({@@ -232,6 +239,7 @@ async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypat@pytest.mark.asyncioasync def test_vectors_only_deletes_sync_removed_detail_vectors(monkeypatch, ctx):viking_fs = SimpleNamespace(+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),persist_temp_tree=AsyncMock(),delete_temp=AsyncMock(),tree=AsyncMock(return_value=[]),@@ -251,7 +259,7 @@ async def test_vectors_only_deletes_sync_removed_detail_vectors(monkeypatch, ctxprocessor = ResourceProcessor(_FakeVikingDB())processor._delete_resource_semantic_vectors = AsyncMock()processor._delete_removed_resource_vectors = AsyncMock()- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())+ lock = {"lease_ref": "lock-1"}await processor.finish_prepared_resource({