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
Revert "refactor(pathlock):using rust implement instead python (#3557)" (#3597)
baojun-zhang1841dfed8132
diff --git a/Cargo.lock b/Cargo.lockindex 59dffc591..8be5cb555 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -3880,7 +3880,6 @@ dependencies = ["chrono","criterion","dashmap",- "fd-lock","flate2","futures","gix-actor",@@ -3904,7 +3903,6 @@ 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 042fec626..d10db441c 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -8,61 +8,10 @@ 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::{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 std::time::UNIX_EPOCH;use ragfs::cache::{CacheError, CacheNamespace, CachePolicy, CacheProvider, CacheResult, CacheTraversalMode,@@ -70,48 +19,10 @@ use ragfs::cache::{};use ragfs::core::builder::EncryptionConfig;use ragfs::core::{- build_default_stack, build_stack_with_mountable, ConfigValue, FileInfo, FileSystem,+ build_default_stack, register_builtin_plugins, ConfigValue, FileInfo, FileSystem,FilesystemStats, FsContext, FsContextInner, FsOperation, GlobPage, GrepResult, MountableFS,- OperationStats, PathLockContext, PluginConfig, RagfsConfig, TreeEntry, WriteFlag, FS_CTX,+ OperationStats, PluginConfig, RagfsConfig, StatsWrappedFS, 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 {@@ -889,135 +800,11 @@ 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 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())+ let account_id = ctx+ .and_then(|m| m.get("account_id").cloned())+ .unwrap_or_default();+ Arc::new(FsContextInner::new(account_id))}#[derive(serde::Deserialize)]@@ -1067,8 +854,6 @@ 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 {@@ -1087,11 +872,6 @@ 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]@@ -1151,28 +931,6 @@ 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 {@@ -1199,7 +957,18 @@ impl RAGFSBindingClient {CacheNamespace::new(&cache_config.namespace),cache_policy_from_config(&cache_config),));- rt.block_on(build_stack_with_mountable(ragfs_cfg, mountable))+ 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 }} else {rt.block_on(build_default_stack(ragfs_cfg))};@@ -1220,7 +989,6 @@ impl RAGFSBindingClient {rt,git_service,git_backend,- pathlock_manager: stack.pathlock_manager,})}@@ -2015,491 +1783,6 @@ 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:@@ -2568,16 +1851,6 @@ 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 d0190d00a..d23af4e6c 100644--- a/crates/ragfs/Cargo.toml+++ b/crates/ragfs/Cargo.toml@@ -48,7 +48,6 @@ flate2 = "1.0"# Path handling and filesystempath-clean = "1.0"-fd-lock = "4.0.4"# Data structuresradix_trie = "0.2"@@ -87,7 +86,6 @@ 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 a0131865c..bbe21a5e7 100644--- a/crates/ragfs/src/cache/policy.rs+++ b/crates/ragfs/src/cache/policy.rs@@ -1,7 +1,5 @@//! 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.@@ -137,7 +135,7 @@ impl CachePolicy {}let name = normalized.rsplit('/').next().unwrap_or("");- if is_hidden_runtime_lock_name(name)+ if name == ".path.ovlock"|| name.ends_with(".lock")|| name.ends_with(".lck")|| matches!(@@ -181,20 +179,3 @@ 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 2df524d6a..d36151b46 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::CreateNew | WriteFlag::Truncate)+ && matches!(flags, WriteFlag::Create | 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 da89b1cdc..1cf6f4c5e 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -6,7 +6,6 @@//! `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;@@ -14,11 +13,6 @@ 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::{@@ -29,20 +23,10 @@ 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.@@ -57,30 +41,16 @@ pub struct EncryptionConfig {pub struct RagfsStack {/// Mount manager (mount/unmount/list/stats/register_plugin live here).pub mountable: Arc<MountableFS>,- /// Data entry point: `Stats(PathLock(Mountable))`.+ /// Data entry point: `Stats(Mountable)` — encryption is per-backend inside mount.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.@@ -90,28 +60,11 @@ pub async fn build_stack_with_mountable(.await;}- 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(),+ // 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>));- // 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 }+ RagfsStack { mountable, top }}/// The single built-in plugin registration sequence (eliminates drift across call sites).@@ -129,7 +82,7 @@ pub async fn register_builtin_plugins(fs: &MountableFS) {#[cfg(test)]mod tests {use super::*;- use crate::core::context::{FsContextInner, PathLockContext, FS_CTX};+ use crate::core::context::{FsContextInner, FS_CTX};use crate::core::{ConfigValue, PluginConfig, Result, WriteFlag};use crate::crypto;use std::collections::HashMap;@@ -142,20 +95,6 @@ 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,- },}}@@ -210,107 +149,6 @@ 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 3587a13e3..3f1f36339 100644--- a/crates/ragfs/src/core/context.rs+++ b/crates/ragfs/src/core/context.rs@@ -10,8 +10,7 @@use std::sync::Arc;-/// Immutable filesystem context snapshot. Currently carries `account_id` (the tenant)-/// and optional `PathLockContext`.+/// Immutable filesystem context snapshot. Currently carries only `account_id` (the tenant).pub type FsContext = Arc<FsContextInner>;tokio::task_local! {@@ -19,20 +18,10 @@ 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 {@@ -40,18 +29,6 @@ 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),}}@@ -59,21 +36,6 @@ 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.@@ -100,23 +62,6 @@ 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 542e4dec9..163fb88a3 100644--- a/crates/ragfs/src/core/encryption_wrapper.rs+++ b/crates/ragfs/src/core/encryption_wrapper.rs@@ -17,10 +17,6 @@ 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;@@ -44,10 +40,6 @@ 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 {@@ -56,37 +48,17 @@ impl EncryptionWrappedFS {&self.inner}- /// 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 {+ /// 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 {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) {@@ -134,14 +106,6 @@ 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.@@ -235,47 +199,6 @@ 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.@@ -358,8 +281,6 @@ 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@@ -370,73 +291,39 @@ impl FileSystem for EncryptionWrappedFS {if !temp_root_ready {self.create_temp_root(&temp_root).await?;}-- // 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])+ let written = match 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}"))- })?,- )+ {+ Ok(written) => written,+ Err(Error::NotFound(_)) => {+ self.create_temp_root(&temp_root).await?;+ self.inner+ .write(&temp_path, &envelope, 0, WriteFlag::Create)+ .await?}- 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}"))- })?,- ),- };-- // 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(()),+ 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),};- 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}"- ))),+ 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)}async fn grep(@@ -592,9 +479,6 @@ 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.@@ -615,18 +499,6 @@ 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))}@@ -634,14 +506,7 @@ mod tests {#[tokio::test]async fn write_then_read_roundtrip_under_ctx() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [9u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [9u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("tenant-1"), async {@@ -657,14 +522,7 @@ mod tests {#[tokio::test]async fn on_disk_bytes_are_ciphertext_with_envelope() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner.clone(),- [9u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("tenant-1"), async {@@ -683,14 +541,7 @@ mod tests {#[tokio::test]async fn read_without_account_id_errors() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner.clone(),- [9u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);// Seed an envelope first.FS_CTX.scope(ctx("tenant-1"), async {@@ -707,14 +558,7 @@ mod tests {#[tokio::test]async fn read_offset_size_slicing() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [1u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [1u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("t"), async {enc.write("/mem/a.txt", b"0123456789", 0, WriteFlag::Create)@@ -730,14 +574,7 @@ mod tests {#[tokio::test]async fn grep_matches_encrypted_files() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [2u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("t"), async {enc.write(@@ -761,14 +598,7 @@ mod tests {#[tokio::test]async fn write_rejects_nonzero_offset() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [2u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("t"), async {let r = enc.write("/mem/a.txt", b"x", 5, WriteFlag::Create).await;@@ -780,14 +610,7 @@ mod tests {#[tokio::test]async fn create_writes_encrypted_empty_file() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner.clone(),- [2u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner.clone(), [2u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("t"), async {enc.create("/mem/empty.txt").await.unwrap();@@ -803,14 +626,7 @@ mod tests {#[tokio::test]async fn cross_account_cannot_decrypt() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [3u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [3u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("acct-A"), async {enc.write("/mem/a.txt", b"owned by A", 0, WriteFlag::Create)@@ -828,14 +644,7 @@ mod tests {#[tokio::test]async fn write_rejects_append_flag() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [4u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("t"), async {enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)@@ -852,14 +661,7 @@ mod tests {#[tokio::test]async fn write_rejects_non_replacing_none_flag() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [4u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);FS_CTX.scope(ctx("t"), async {enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)@@ -874,14 +676,7 @@ mod tests {#[tokio::test]async fn rename_rejects_cross_account_paths() {let inner = memfs_stack_at("/local").await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner,- [5u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/local".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner, [5u8; 32], crypto::PROVIDER_LOCAL);let result = FS_CTX.scope(ctx("acct-a"), async {enc.mkdir("/local/acct-a", 0).await.unwrap();@@ -899,14 +694,7 @@ mod tests {#[tokio::test]async fn write_replaces_stale_internal_temp_file_before_publish() {let inner = memfs_stack().await;- let manager = memfs_pathlock_manager(inner.clone()).await;- let enc = EncryptionWrappedFS::new(- inner.clone(),- [6u8; 32],- crypto::PROVIDER_LOCAL,- manager,- "/mem".to_string(),- );+ let enc = EncryptionWrappedFS::new(inner.clone(), [6u8; 32], crypto::PROVIDER_LOCAL);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 7a9c7965e..e76044bf8 100644--- a/crates/ragfs/src/core/filesystem.rs+++ b/crates/ragfs/src/core/filesystem.rs@@ -197,52 +197,6 @@ 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@@ -256,17 +210,6 @@ 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@@ -1073,7 +1016,7 @@ mod tests {let entries = root_tree(&fs, false, None, Some(1)).await;assert_eq!(entries.len(), 2);- assert_tree_names(&entries, &["sub", "a.txt"]);+ assert_tree_names(&entries, &["a.txt", "sub"]);}#[tokio::test]@@ -1138,8 +1081,8 @@ mod tests {let entries = fs.tree_directory("/", false, None, None).await.unwrap();assert_eq!(entries.len(), 2);- assert_eq!(entries[0].path, "/sub");- assert_eq!(entries[0].rel_path, "sub");+ assert_eq!(entries[0].path, "/a.txt");+ assert_eq!(entries[0].rel_path, "a.txt");}#[tokio::test]diff --git a/crates/ragfs/src/core/internal_names.rs b/crates/ragfs/src/core/internal_names.rsdeleted file mode 100644index 7d703cd22..000000000--- a/crates/ragfs/src/core/internal_names.rs+++ /dev/null@@ -1,27 +0,0 @@-//! 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 d2d72a989..6bc43e939 100644--- a/crates/ragfs/src/core/mod.rs+++ b/crates/ragfs/src/core/mod.rs@@ -13,7 +13,6 @@ 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;@@ -24,10 +23,10 @@ pub mod types;// Re-export commonly used typespub use crate::multibackend::{FsContextResolver, MetaStateStore};pub use builder::{- build_default_stack, build_stack_with_mountable, register_builtin_plugins,- EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,+ build_default_stack, register_builtin_plugins, EncryptionConfig as BuilderEncryptionConfig,+ RagfsConfig, RagfsStack,};-pub use context::{FsContext, FsContextInner, FsContextView, PathLockContext, FS_CTX};+pub use context::{FsContext, FsContextInner, FsContextView, 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 ed1c66d1d..9767214d2 100644--- a/crates/ragfs/src/core/mountable.rs+++ b/crates/ragfs/src/core/mountable.rs@@ -8,19 +8,16 @@ use async_trait::async_trait;use radix_trie::{Trie, TrieCommon};use serde_json::Value;use std::collections::HashMap;-use std::sync::{Arc, OnceLock};-use std::time::Duration;+use std::sync::Arc;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;-use super::internal_names::is_hidden_internal_name;+/// Python-side transaction path-lock marker — hidden in all listing/grep operations.+const PATH_LOCK_FILE: &str = ".path.ovlock";use super::encryption_wrapper::EncryptionWrappedFS;use super::errors::{Error, Result};@@ -77,9 +74,6 @@ 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>,@@ -149,21 +143,6 @@ 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;@@ -186,14 +165,6 @@ 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?;@@ -217,7 +188,6 @@ 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,}@@ -238,7 +208,6 @@ 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,@@ -257,13 +226,6 @@ 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;@@ -361,18 +323,7 @@ impl MountableFS {config.name)));}- 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(),- ))+ Arc::new(EncryptionWrappedFS::new(storage_fs, rk, pt))}_ => storage_fs,}@@ -445,11 +396,6 @@ 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,@@ -457,8 +403,6 @@ impl MountableFS {MultiBackendBuildContext {enc_root_key,enc_provider_type,- pathlock_manager,- backend_prefix: config.mount_path.clone(),},).await@@ -595,66 +539,20 @@ impl MountableFS {return Ok(true);}- 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);+ if let Some(multiwrite) = Self::as_multiwrite(&src_mount.fs) {+ return multiwrite+ .copy_within_primary(&src_rel_path, &dst_rel_path)+ .await;}- 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}")));- }- };-- 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 Some(raw_backend) = src_mount.raw_fs.clone() else {+ return Ok(false);};- 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}"- ))),- }+ 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)}/// Copy one file within one raw backend in bounded-size chunks.@@ -864,83 +762,10 @@ 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_internal_dir(&rel_path).await?;+ let mut entries = mount_info.fs.read_dir(&rel_path).await?;+ entries.retain(|e| e.name != PATH_LOCK_FILE);sort_directory_entries(&mut entries);Ok(entries)}@@ -1036,12 +861,12 @@ impl FileSystem for MountableFS {).await?;- // Filter out internal files from public search results.+ // Filter out path-lock markers.result.matches.retain(|m| {m.file.rsplit('/').next()- .map_or(true, |name| !is_hidden_internal_name(name))+ .map_or(true, |name| name != PATH_LOCK_FILE)});result.count = result.matches.len();Ok(result)@@ -1077,12 +902,12 @@ impl FileSystem for MountableFS {}}- // Filter out internal files from public tree results.+ // Filter out path-lock markers.entries.retain(|e| {e.path.rsplit('/').next()- .map_or(true, |name| !is_hidden_internal_name(name))+ .map_or(true, |name| name != PATH_LOCK_FILE)});Ok(entries)@@ -1132,7 +957,7 @@ impl FileSystem for MountableFS {.path.rsplit('/').next()- .map_or(true, |name| !is_hidden_internal_name(name))+ .map_or(true, |name| name != PATH_LOCK_FILE)});Ok(page)@@ -1438,32 +1263,6 @@ 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();@@ -1474,22 +1273,6 @@ 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");@@ -1501,7 +1284,7 @@ mod tests {#[tokio::test]async fn test_mountable_fs_creation() {- let mfs = Arc::new(MountableFS::new());+ let mfs = MountableFS::new();let mounts = mfs.list_mounts().await;assert!(mounts.is_empty());}@@ -1610,55 +1393,6 @@ 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() {@@ -1715,27 +1449,16 @@ 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 cache_provider = Arc::new(MemoryCacheProvider::new());- let mfs = Arc::new(MountableFS::with_cache(- cache_provider.clone(),+ let provider = Arc::new(MemoryCacheProvider::new());+ let mfs = MountableFS::with_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();@@ -1773,13 +1496,13 @@ mod tests {"missing account context must not receive cached plaintext");- let file_key = cache_provider+ let file_key = provider.keys().await.into_iter().find(|key| key.contains(":file:")).expect("encrypted read should populate one file cache object");- let encoded = cache_provider+ let encoded = provider.get(&file_key).await.unwrap()@@ -1801,27 +1524,17 @@ 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 = Arc::new(MountableFS::with_cache(+ let mfs = MountableFS::with_cache(Arc::new(MemoryCacheProvider::new()),CacheNamespace::new("encrypted-multiwrite-test"),CachePolicy::default(),- ));- mfs.register_plugin(MemFSPlugin).await;+ );+ mfs.register_plugin(MockPlugin::new("primary")).await;+ mfs.register_plugin(MockPlugin::new("backupfs")).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("memfs", "memfs", "/local");+ let mut config = multiwrite_test_config("primary", "backupfs", "/local");config.server_encryption_enabled = true;config.primary_encryption_enabled = true;mfs.mount(config).await.unwrap();@@ -1890,7 +1603,7 @@ mod tests {#[tokio::test]async fn test_mount_duplicate_error() {- let mfs = Arc::new(MountableFS::new());+ let mfs = MountableFS::new();mfs.register_plugin(MockPlugin::new("mock")).await;let config = test_config("mock", "/mock");@@ -2144,7 +1857,7 @@ mod tests {#[tokio::test]async fn test_build_multi_write_fs_rejects_primary_encryption_disable() {- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;+ let mfs = MountableFS::new();mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;mfs.set_encryption_config(Some([7u8; 32]), Some(1)).await;@@ -2183,66 +1896,9 @@ 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 = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;+ let mfs = MountableFS::new();mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -2284,7 +1940,7 @@ mod tests {#[tokio::test]async fn test_build_multi_write_fs_rejects_reserved_primary_backup_name() {- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;+ let mfs = MountableFS::new();mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -2323,23 +1979,11 @@ mod tests {#[tokio::test]async fn test_single_backend_mount_wraps_stats_outside_encryption() {- use crate::lock::{- MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,- };- use crate::plugins::MemFSPlugin;-- let mfs = Arc::new(MountableFS::new());- mfs.register_plugin(MemFSPlugin).await;+ let mfs = MountableFS::new();+ mfs.register_plugin(MockPlugin::new("mock")).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("memfs", "/mock")).await.unwrap();+ mfs.mount(test_config("mock", "/mock")).await.unwrap();let mounts = mfs.mounts.read().await;let mount_info = mounts.get("/mock").expect("mounted entry should exist");@@ -2356,7 +2000,7 @@ mod tests {#[tokio::test]async fn test_multiwrite_mount_wraps_stats_outside_multiwrite() {- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;+ let mfs = MountableFS::new();mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -2379,7 +2023,7 @@ mod tests {#[tokio::test]async fn test_multiwrite_raw_access_is_rejected() {- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;+ let mfs = MountableFS::new();mfs.register_plugin(MockPlugin::new("primary")).await;mfs.register_plugin(MockPlugin::new("backupfs")).await;@@ -2399,7 +2043,7 @@ mod tests {#[tokio::test]async fn test_mountable_multiwrite_admin_smoke() {- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;+ let mfs = MountableFS::new();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 db2f7e1ef..0d204dba1 100644--- a/crates/ragfs/src/core/multibackend_wrapper.rs+++ b/crates/ragfs/src/core/multibackend_wrapper.rs@@ -19,7 +19,6 @@ 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::{@@ -30,7 +29,6 @@ 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,@@ -583,17 +581,6 @@ 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 {@@ -1303,9 +1290,6 @@ 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})@@ -1323,9 +1307,6 @@ 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})@@ -1333,9 +1314,6 @@ 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})@@ -1343,9 +1321,6 @@ 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;}@@ -1353,14 +1328,6 @@ 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();@@ -1416,9 +1383,6 @@ 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;}@@ -1426,11 +1390,6 @@ 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();@@ -1472,9 +1431,6 @@ 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,@@ -1485,9 +1441,6 @@ 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 35d9f64f5..767091b0b 100644--- a/crates/ragfs/src/core/types.rs+++ b/crates/ragfs/src/core/types.rs@@ -187,16 +187,9 @@ impl FileInfo {/// Write operation flags#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]pub enum WriteFlag {- /// 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 new file or truncate existingCreate,- /// 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 cd2a77c73..fc2a287a6 100644--- a/crates/ragfs/src/git/enumerate.rs+++ b/crates/ragfs/src/git/enumerate.rs@@ -14,8 +14,6 @@//! 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;@@ -49,12 +47,11 @@ pub fn prune_path(rel: &str) -> bool {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 2: any segment equals or starts with ".path.ovlock"+ for seg in &segments {+ if seg.starts_with(".path.ovlock") {+ return true;+ }}// Rule 3a: any intermediate segment named exactly "embedding_cache"@@ -392,9 +389,6 @@ 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 3b583f745..c83488fec 100644--- a/crates/ragfs/src/git/service.rs+++ b/crates/ragfs/src/git/service.rs@@ -1303,8 +1303,6 @@ 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 06fad00b8..082e9b4e1 100644--- a/crates/ragfs/src/lib.rs+++ b/crates/ragfs/src/lib.rs@@ -33,7 +33,6 @@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.rsdeleted file mode 100644index 45d7c5bdf..000000000--- a/crates/ragfs/src/lock/codec.rs+++ /dev/null@@ -1,103 +0,0 @@-//! 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.rsdeleted file mode 100644index cbf1e79de..000000000--- a/crates/ragfs/src/lock/manager.rs+++ /dev/null@@ -1,1844 +0,0 @@-//! 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 entries: Vec<(String, String, Vec<String>)> = {- let reg = refresh_registry.read().await;- reg.entries- .iter()- .map(|(lease_ref, entry)| {- (- lease_ref.clone(),- entry.lease.owner_id.clone(),- entry.lease.lock_paths.clone(),- )- })- .collect()- };- for (lease_ref, owner_id, lock_paths) in entries {- 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,- }- }- 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,- }- }-- /// 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 } = &err {- metrics.record_conflict(PathLockConflict {- lock_path: lock_path.clone(),- conflicting_owner: owner.clone(),- conflicting_kind: PathLockKind::Tree, // ponytail: approximate — exact resolution would require reading the token- });- }- }-- // 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,- } = &err- {- metrics.record_conflict(PathLockConflict {- lock_path: lock_path.clone(),- conflicting_owner: owner.clone(),- conflicting_kind: PathLockKind::Tree,- });- }- }-- 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(),- });- }- 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,- });- }- // 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,- });- }- }- }- 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,- });- }- }-- 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,- });- }- }- }- 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 {- if let Err(error) = self- .provider- .remove_token(&lock_path, &entry.lease.owner_id)- .await- {- 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 {- if let Err(error) = self.provider.remove_token(&lock_path, &owner_id).await {- 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,- });- }- 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::core::{FsContextInner, PathLockContext, FS_CTX};- 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,- }-- 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),- }- }- }-- #[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.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.rsdeleted file mode 100644index 9a60bff9c..000000000--- a/crates/ragfs/src/lock/metrics.rs+++ /dev/null@@ -1,42 +0,0 @@-//! 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.rsdeleted file mode 100644index e50e3c9cc..000000000--- a/crates/ragfs/src/lock/mod.rs+++ /dev/null@@ -1,32 +0,0 @@-//! 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.rsdeleted file mode 100644index 86025fb80..000000000--- a/crates/ragfs/src/lock/provider.rs+++ /dev/null@@ -1,336 +0,0 @@-//! 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(),- });- }- 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,- }),- 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.rsdeleted file mode 100644index 2f32da81e..000000000--- a/crates/ragfs/src/lock/resolver.rs+++ /dev/null@@ -1,203 +0,0 @@-//! 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.rsdeleted file mode 100644index b16c42b21..000000000--- a/crates/ragfs/src/lock/types.rs+++ /dev/null@@ -1,198 +0,0 @@-//! 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,- },-- /// 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.rsdeleted file mode 100644index 4e690884b..000000000--- a/crates/ragfs/src/lock/wrapper.rs+++ /dev/null@@ -1,368 +0,0 @@-//! 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 0f657d850..0ac98d581 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::RelativePathFsContextResolver;+use crate::multibackend::meta::MountRootFsContextResolver;use crate::multibackend::types::MultiBackendBuildContext;use crate::shape::validate::ensure_backend_shape;@@ -85,8 +85,6 @@ 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()@@ -148,8 +146,6 @@ 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@@ -180,6 +176,8 @@ 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(RelativePathFsContextResolver))+ .ctx_resolver(Arc::new(MountRootFsContextResolver::new(+ &config.mount_path,+ ))).build()}diff --git a/crates/ragfs/src/multibackend/meta.rs b/crates/ragfs/src/multibackend/meta.rsindex 97110884f..d63766170 100644--- a/crates/ragfs/src/multibackend/meta.rs+++ b/crates/ragfs/src/multibackend/meta.rs@@ -45,13 +45,44 @@ impl FsContextResolver for DefaultFsContextResolver {}}-/// Resolver that extracts `account_id` from mount-relative paths such as `/{account_id}/...`.-pub struct RelativePathFsContextResolver;+/// 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,+ }+ }+}-impl FsContextResolver for RelativePathFsContextResolver {+impl FsContextResolver for MountRootFsContextResolver {fn resolve(&self, path: &str) -> Result<FsContext> {- let normalized = path.trim_start_matches('/');- let account_id = normalized.split('/').next().unwrap_or_default();+ 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();if account_id.is_empty() {return Err(Error::internal(format!("cannot resolve FsContext from path: {path}"@@ -144,12 +175,12 @@ impl MetaStateStore {Arc::new(FsContextInner::new("_system".to_string()))}- /// Build the effective context for metadata access.+ /// - root directory using `_system` contextfn effective_meta_ctx(dir: &str, ctx: &FsContext) -> FsContext {if dir == "/" {- Arc::new(Self::system_ctx().with_auto_pathlock_disabled())+ Self::system_ctx()} else {- Arc::new(ctx.with_auto_pathlock_disabled())+ ctx.clone()}}@@ -501,7 +532,6 @@ pub fn current_required_ctx() -> Result<FsContext> {#[cfg(test)]mod tests {use super::*;- use crate::core::context::PathLockContext;use crate::plugins::memfs::MemFileSystem;use std::sync::Arc;@@ -533,6 +563,15 @@ 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 78bb71d66..8e097ee4f 100644--- a/crates/ragfs/src/multibackend/types.rs+++ b/crates/ragfs/src/multibackend/types.rs@@ -1,20 +1,12 @@//! 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)]+#[derive(Clone, Copy)]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 85be8ed6e..e2b1775b0 100644--- a/crates/ragfs/src/plugins/kvfs/mod.rs+++ b/crates/ragfs/src/plugins/kvfs/mod.rs@@ -193,9 +193,6 @@ 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);}@@ -214,7 +211,7 @@ impl FileSystem for KVFileSystem {Ok(data.len() as u64)}None => {- if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {+ if matches!(flags, WriteFlag::Create) {store.insert(key, KVEntry::new(data.to_vec()));Ok(data.len() as u64)} else {@@ -224,38 +221,6 @@ 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 a7619467d..af1e97740 100644--- a/crates/ragfs/src/plugins/localfs/mod.rs+++ b/crates/ragfs/src/plugins/localfs/mod.rs@@ -93,138 +93,6 @@ 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 = fd_lock::RwLock::new(file);- let mut file = lock- .write()- .map_err(|e| Error::plugin(format!("failed to lock for compare_and_write: {}", e)))?;- 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 = fd_lock::RwLock::new(file);- let mut file = lock- .write()- .map_err(|e| Error::plugin(format!("failed to lock for compare_and_remove: {}", e)))?;- 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@@ -946,9 +814,6 @@ 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);}@@ -977,29 +842,6 @@ 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 bdec5a9e8..af85f9c19 100644--- a/crates/ragfs/src/plugins/memfs/mod.rs+++ b/crates/ragfs/src/plugins/memfs/mod.rs@@ -280,9 +280,6 @@ 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);}@@ -302,8 +299,8 @@ impl FileSystem for MemFileSystem {Ok(data.len() as u64)}None => {- // Create file if Create or CreateNew flag is set- if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {+ // Create file if Create flag is set+ if matches!(flags, WriteFlag::Create) {// Check parent existsif let Some(parent) = Self::parent_path(&normalized) {match entries.get(&parent) {@@ -324,39 +321,6 @@ 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 e37b8161e..dddda4593 100644--- a/crates/ragfs/src/plugins/s3fs/client.rs+++ b/crates/ragfs/src/plugins/s3fs/client.rs@@ -110,30 +110,6 @@ 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,@@ -510,46 +486,6 @@ 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 {@@ -616,72 +552,6 @@ 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@@ -701,36 +571,6 @@ 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 d49334965..38e378094 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;+use crate::core::glob::{PreparedGlob, validate_pattern};use crate::core::{ConfigParameter, Error, FileInfo, FileSystem, GlobEntry, GlobPage, GrepMatch, GrepResult,PluginConfig, Result, ServicePlugin, TreeEntry, WriteFlag,@@ -573,19 +573,12 @@ 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);- 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?;- }- }+ // S3 always replaces the full object+ self.client.put_object(&key, data.to_vec()).await?;// Invalidate cachesself.dir_cache.invalidate_parent(&normalized).await;@@ -594,48 +587,6 @@ 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 f16314bed..5fa01efb7 100644--- a/crates/ragfs/src/plugins/sqlfs/backend.rs+++ b/crates/ragfs/src/plugins/sqlfs/backend.rs@@ -46,12 +46,6 @@ 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>>;@@ -284,35 +278,6 @@ 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 0ab7bb367..f990850c8 100644--- a/crates/ragfs/src/plugins/sqlfs/mod.rs+++ b/crates/ragfs/src/plugins/sqlfs/mod.rs@@ -110,27 +110,6 @@ 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 {@@ -282,11 +261,9 @@ impl FileSystem for SQLFileSystem {async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {let normalized = Self::normalize_path(path);- let normalized_for_db = normalized.clone();- match self- .run_blocking_db(move |backend| backend.read_file(&normalized_for_db))- .await?- {+ let backend = self.backend.read().await;++ match backend.read_file(&normalized)? {Some((is_dir, data)) => {if is_dir {return Err(Error::IsADirectory(normalized));@@ -331,85 +308,39 @@ impl FileSystem for SQLFileSystem {));}- 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 backend = self.backend.read().await;- if matches!(flags, WriteFlag::CreateNew) {- return Err(Error::AlreadyExists(normalized_for_db.clone()));- }+ let exists = backend.path_exists(&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));- }+ if exists {+ // Check if it's a directory+ if backend.is_directory(&normalized)? {+ return Err(Error::IsADirectory(normalized));+ }- let parent = backend.parent_path(&normalized_for_db);- if parent != "/" && !backend.is_directory(&parent)? {- return Err(Error::not_found(&parent));- }+ // Update existing file+ backend.update_file(&normalized, data)?;+ } else {+ // Create new file+ if !matches!(flags, WriteFlag::Create) {+ return Err(Error::not_found(&normalized));+ }- backend.create_file(&normalized_for_db, 0o644, &data_owned)?;- Ok(true)+ // Check parent exists+ let parent = backend.parent_path(&normalized);+ if parent != "/" {+ if !backend.is_directory(&parent)? {+ return Err(Error::not_found(&parent));}- })- .await?;-- if created_new {- self.cache.invalidate_parent(&normalized).await;- }+ }- Ok(data.len() as u64)- }+ backend.create_file(&normalized, 0o644, data)?;- 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 {+ // Invalidate parent cacheself.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)+ Ok(data.len() as u64)}async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {@@ -420,21 +351,19 @@ impl FileSystem for SQLFileSystem {return Ok(files);}- 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));- }+ let backend = self.backend.read().await;- if !backend.is_directory(&normalized_for_db)? {- return Err(Error::NotADirectory(normalized_for_db));- }+ // Check if directory exists+ if !backend.path_exists(&normalized)? {+ return Err(Error::not_found(&normalized));+ }- backend.list_directory(&list_path)- })- .await?;+ if !backend.is_directory(&normalized)? {+ return Err(Error::NotADirectory(normalized));+ }++ // List directory+ let entries = backend.list_directory(&normalized)?;// Convert to FileInfolet mut files = Vec::new();@@ -458,11 +387,9 @@ impl FileSystem for SQLFileSystem {async fn stat(&self, path: &str) -> Result<FileInfo> {let normalized = Self::normalize_path(path);- let normalized_for_db = normalized.clone();- match self- .run_blocking_db(move |backend| backend.get_metadata(&normalized_for_db))- .await?- {+ let backend = self.backend.read().await;++ match backend.get_metadata(&normalized)? {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 254c78e40..4a098b39e 100644--- a/crates/ragfs/src/shape/probe.rs+++ b/crates/ragfs/src/shape/probe.rs@@ -2,7 +2,6 @@ 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};@@ -10,6 +9,8 @@ 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();@@ -35,7 +36,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("");- is_hidden_runtime_lock_name(name)+ name == PATH_LOCK_FILE || name.starts_with(EXACT_LOCK_FILE_PREFIX)}/// Read the raw guard-file bytes from the backend root.diff --git a/openviking/async_client.py b/openviking/async_client.pyindex 52904f626..19b75be32 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -109,6 +109,11 @@ 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 68613729e..86544ac87 100644--- a/openviking/metrics/datasources/observer_state.py+++ b/openviking/metrics/datasources/observer_state.py@@ -3,10 +3,11 @@from __future__ import annotations+import timefrom typing import Anyfrom openviking.metrics.core.base import ReadEnvelope-from openviking.storage.viking_fs import get_viking_fs+from openviking.storage.transaction import get_lock_managerfrom openviking_cli.utils import run_asyncfrom .base import DomainStatsMetricDataSource, StateMetricDataSource@@ -61,27 +62,36 @@ class ObserverStateDataSource(DomainStatsMetricDataSource):class LockStateDataSource(StateMetricDataSource):"""- Read lock-manager counters from the pathlock observe snapshot.+ Read lock-manager counters needed by lock-related state collectors.- The datasource reads the ``pathlock_observe()`` snapshot to derive active,- waiting, and stale lock counts.+ The datasource inspects active lock handles and derives a stale-handle count using the+ current in-process timeout heuristic."""def read_lock_state(self) -> ReadEnvelope[tuple[int, int, int]]:"""- Read active, waiting, and stale lock counts from the pathlock observe snapshot.+ Read active and stale lock counts from the global transaction lock manager.Returns:- A tuple of ``(active_locks, waiting_locks, stale_locks_removed)``.+ A tuple of `(active_locks, waiting_locks, stale_handles)` where waiting locks are+ currently not tracked separately and therefore remain `0`."""def _read() -> tuple[int, int, int]:- 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, stale+ 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, stalereturn self.safe_read(_read, default=(0, 0, 0))diff --git a/openviking/parse/image_rewrite.py b/openviking/parse/image_rewrite.pyindex 8f2482cb9..66e8e0878 100644--- a/openviking/parse/image_rewrite.py+++ b/openviking/parse/image_rewrite.py@@ -11,12 +11,15 @@ images themselves are stored next to the markdown file referencing them).import jsonimport refrom pathlib import Path-from typing import Any, Dict, Optional, Set+from typing import TYPE_CHECKING, 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"!\[([^\]]*)\]\(((?:[^()]|\([^()]*\))+)\)")@@ -256,7 +259,7 @@ async def _discover_mappings(async def rewrite_image_uris(root_uri: str,ctx: Optional[RequestContext] = None,- lease_ref: Optional[Dict[str, Any]] = None,+ lock_handle: Optional["LockHandle"] = None,) -> Dict[str, int]:"""Rewrite local image references in markdown files to viking:// URIs.@@ -274,7 +277,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- lease_ref: Optional lease reference held by the caller. When the caller+ lock_handle: Optional lock handle 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.@@ -334,11 +337,12 @@ 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,- lease_ref=lease_ref,+ lock_handle=lock_handle,)files_processed += 1references_rewritten += rewrite_count@@ -350,9 +354,7 @@ 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,- lease_ref=lease_ref,+ f"{map_dir}/{IMAGE_MAPPINGS_FILENAME}", ctx=ctx, lock_handle=lock_handle)except Exception as e:logger.warning(diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.pyindex 5182f2b71..3e1fd7457 100644--- a/openviking/pyagfs/async_client.py+++ b/openviking/pyagfs/async_client.py@@ -253,238 +253,3 @@ 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 5a1910ee4..d19b1095e 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,9 +383,7 @@ 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:@@ -637,34 +635,14 @@ class LegacyAPIKeyManager:except AGFSNotFoundError:return 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:+ async def _write_json(self, path: str, data: dict) -> 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,- fs_ctx=self._fs_ctx_with_lease(path, lease_ref),- )+ await self._async_agfs.write(path, content)async def _ensure_parent_dirs_async(self, path: str) -> None:"""Recursively create all parent directories for a file path."""@@ -676,38 +654,37 @@ class LegacyAPIKeyManager:async def _save_accounts_json(self) -> None:"""Persist the global accounts list."""try:- lease = await self._async_agfs.pathlock_acquire_exact(ACCOUNTS_PATH, timeout_secs=10.0)+ 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)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:- lease = await self._async_agfs.pathlock_acquire_exact(path, timeout_secs=10.0)+ 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})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 290394cc7..e79a6e10f 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.errors import LockAcquisitionError+from openviking.storage.transaction import get_lock_managerfrom 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_viking_fs()._async_agfs.pathlock_release(self.lock_handle)+ await get_lock_manager().release(self.lock_handle)self.lock_handle = Noneif self.mode == "shared" and self.local_path:@@ -142,12 +142,7 @@ 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,- lease_ref=resolved.lock_handle,- )+ await self._write_shared_meta(shared_id, ctx, meta)async def mark_consumed(self, resolved: ResolvedTempUpload, ctx: RequestContext) -> None:shared_id = _parse_shared_temp_file_id(resolved.temp_file_id)@@ -158,7 +153,7 @@ class TempUploadStore:uri,recursive=True,ctx=self._internal_ctx(ctx),- lease_ref=resolved.lock_handle,+ lock_handle=resolved.lock_handle,)async def try_cleanup_invalid_or_expired(@@ -320,9 +315,9 @@ class TempUploadStore:_shared_upload_uri(self.temp_cfg, ctx, upload_id),ctx=internal_ctx,)- try:- lease = await vfs._async_agfs.pathlock_acquire_tree(lock_path, timeout_secs=0.0)- except LockAcquisitionError:+ handle = get_lock_manager().create_handle()+ acquired = await get_lock_manager().acquire_tree(handle, lock_path, timeout=0.0)+ if not acquired:raise PermissionDeniedError("Temporary upload is being consumed.")try:@@ -333,7 +328,7 @@ class TempUploadStore:meta["state"] = "consuming"meta["updated_at"] = now- await self._write_shared_meta(upload_id, ctx, meta, lease_ref=lease)+ await self._write_shared_meta(upload_id, ctx, meta)file_ext = meta.get("file_ext") or ".tmp"fd, temp_path = tempfile.mkstemp(prefix="ov_shared_upload_", suffix=file_ext)@@ -352,11 +347,11 @@ class TempUploadStore:temp_file_id=temp_file_id,original_filename=meta.get("original_filename") or None,local_path=temp_path,- lock_handle=lease,+ lock_handle=handle,)except Exception:with suppress(Exception):- await vfs._async_agfs.pathlock_release(lease)+ await get_lock_manager().release(handle)raiseasync def _read_shared_meta(self, upload_id: str, ctx: RequestContext) -> dict[str, Any]:@@ -375,15 +370,12 @@ 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 908d5a858..4a93fc776 100644--- a/openviking/server/user_config.py+++ b/openviking/server/user_config.py@@ -12,11 +12,13 @@ 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@@ -38,20 +40,14 @@ async def _user_config_lock(viking_fs: VikingFS,uri: str,ctx: RequestContext,-) -> AsyncIterator[Optional[dict[str, Any]]]:+) -> AsyncIterator[Optional[LockHandle]]:uri_to_path = getattr(viking_fs, "_uri_to_path", None)- 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):+ if not callable(uri_to_path):yield Nonereturnpath = uri_to_path(uri, ctx=ctx)- lease = await acquire(path)- try:- yield lease- finally:- await release(lease)+ async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:+ yield handledef _user_config_from_payload(payload: Any) -> UserConfig:@@ -160,7 +156,7 @@ async def update_user_config(sort_keys=True,),ctx=ctx,- lease_ref=handle,+ lock_handle=handle,)return result@@ -181,7 +177,7 @@ async def write_user_config(sort_keys=True,),ctx=ctx,- lease_ref=handle,+ lock_handle=handle,)return runtimediff --git a/openviking/service/core.py b/openviking/service/core.pyindex ca3964804..98a13f81d 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -31,6 +31,7 @@ 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,@@ -87,7 +88,7 @@ class OpenVikingService:self._resource_processor: Optional[ResourceProcessor] = Noneself._skill_processor: Optional[SkillProcessor] = Noneself._session_compressor: Optional["SessionCompressorV2"] = None-+ self._lock_manager: Optional[LockManager] = Noneself._directory_initializer: Optional[DirectoryInitializer] = Noneself._watch_scheduler: Optional[WatchScheduler] = Noneself._encryptor: Optional[Any] = None@@ -172,7 +173,16 @@ class OpenVikingService:if self._queue_manager:self._queue_manager.setup_standard_queues(self._vikingdb_manager, start=False)- # PathLock has been moved to Rust ragfs; Python-layer LockManager is no longer needed.+ # 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,+ )set_task_tracker(config.build_task_tracker(self._agfs_client))def _build_ragfs_binding_config(self) -> Any:@@ -222,6 +232,11 @@ 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."""@@ -361,6 +376,11 @@ 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,@@ -417,7 +437,6 @@ class OpenVikingService:self._resource_service,asyncio.get_running_loop(),queue_name,- self._viking_fs,),allow_create=True,)@@ -457,6 +476,10 @@ 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 eccde2ee2..d0a8f8625 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.viking_fs import get_viking_fs-from openviking_cli.utils import run_async+from openviking.storage.transaction import get_lock_managerfrom openviking_cli.utils.config import OpenVikingConfigfrom openviking_cli.utils.logger import get_logger@@ -165,10 +165,9 @@ class ObserverService:@propertydef lock(self) -> ComponentStatus:- """Get lock system status via pathlock_observe snapshot."""+ """Get lock system status."""try:- viking_fs = get_viking_fs()- snapshot = run_async(viking_fs._async_agfs.pathlock_observe())+ lock_manager = get_lock_manager()except Exception:return ComponentStatus(name="lock",@@ -176,22 +175,12 @@ class ObserverService:has_errors=True,status="Not initialized",)- 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)}",- ]+ observer = LockObserver(lock_manager)return ComponentStatus(name="lock",- is_healthy=not has_errors,- has_errors=has_errors,- status="\n".join(lines),+ is_healthy=observer.is_healthy(),+ has_errors=observer.has_errors(),+ status=observer.get_status_table(),)@property@@ -233,8 +222,10 @@ 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 9789a178f..57a261024 100644--- a/openviking/service/reindex_executor.py+++ b/openviking/service/reindex_executor.py@@ -31,6 +31,13 @@ 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@@ -97,7 +104,7 @@ class _ReindexCounters:class _ReindexRunContext:ctx: RequestContextcounters: _ReindexCounters- lock: dict | None = None+ lock: LockLease = NO_LOCK@dataclass@@ -435,73 +442,71 @@ class ReindexExecutor:if telemetry_id:wait_tracker.register_request(telemetry_id)- lease = await service.viking_fs._async_agfs.pathlock_acquire_tree(path)try:- 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,+ async with LockContext(get_lock_manager(), [path], lock_mode="tree") as lock_handle:+ run = _ReindexRunContext(ctx=ctx,+ counters=counters,+ lock=BorrowedLockLease.from_handle(get_lock_manager(), lock_handle),)- 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)@@ -911,7 +916,7 @@ class ReindexExecutor:uri: str,context_type: str,ctx: RequestContext,- lock: dict | None = None,+ lock: LockLease = NO_LOCK,) -> None:processor = SemanticProcessor(max_concurrent_llm=get_openviking_config().vlm.max_concurrent,@@ -927,7 +932,7 @@ class ReindexExecutor:role=str(ctx.role),skip_vectorization=True,)- await processor.on_dequeue({"data": msg.to_json()}, lock=lock)+ await processor.on_dequeue({"data": msg.to_json()}, lock=lock.as_borrowed())async def _reindex_resource_vectors(self,@@ -1087,8 +1092,7 @@ 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)- lease = await viking_fs._async_agfs.pathlock_acquire_exact(lock_path)- try:+ async with LockContext(get_lock_manager(), [lock_path], lock_mode="exact"):abstract = await self._read_directory_abstract(dir_uri, ctx=ctx)if level == ContextLevel.ABSTRACT:vector_text = abstract@@ -1110,8 +1114,6 @@ 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 6de710b14..6c762168c 100644--- a/openviking/service/resource_service.py+++ b/openviking/service/resource_service.py@@ -45,6 +45,7 @@ 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@@ -359,36 +360,33 @@ class ResourceService:msg: Any,*,queue_name: str,- resource_lock: Optional[Dict[str, Any]] = None,+ resource_lock: LockLease = NO_LOCK,) -> Any:- """Persist a job and fully own the passed lock until handoff or release completes."""+ """Persist a job before its TaskRecord so a crash cannot orphan the task."""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())- if resource_lock is not None:- await self._viking_fs._async_agfs.pathlock_handoff(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,- )+ await resource_lock.handoff()except BaseException:- if resource_lock is not None:- await self._viking_fs._async_agfs.pathlock_release(resource_lock)+ await resource_lock.close()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(@@ -396,10 +394,11 @@ class ResourceService:msg: Any,*,ctx: RequestContext,- resource_lock: Optional[Dict[str, Any]],+ resource_lock: Optional[LockLease],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@@ -491,15 +490,18 @@ class ResourceService:self,root_uri: str,ctx: RequestContext,- ) -> Dict[str, Any]:+ ) -> LockLease:"""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._viking_fs._async_agfs.pathlock_acquire_tree(+ return await self._resource_processor.acquire_resource_lock(+ get_lock_manager(),dst_path,- timeout_secs=0.0,+ uri=root_uri,+ timeout=0.0,)async def enqueue_git_add_resource(@@ -549,7 +551,7 @@ class ResourceService:from openviking.storage.queuefs.add_resource_msg import AddResourceMsg- resource_lock: Optional[Dict[str, Any]] = None+ resource_lock: LockLease = NO_LOCKtry:if enforce_public_remote_targets and is_remote_resource_source(path):path = require_remote_resource_source(path)@@ -568,11 +570,7 @@ class ResourceService:)task_id = str(uuid4())- lock_handoff = (- await self._viking_fs._async_agfs.pathlock_to_handoff(resource_lock)- if resource_lock is not None- else None- )+ lock_handoff = resource_lock.to_handoff()processor_args = {key: valuefor key, value in kwargs.items()@@ -587,7 +585,7 @@ class ResourceService:user_id=ctx.user.user_id,role=str(ctx.role),actor_peer_id=ctx.actor_peer_id,- lock_handoff=lock_handoff,+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,reason=reason,instruction=instruction,timeout=timeout,@@ -608,21 +606,19 @@ class ResourceService:source_name=source_name,args=self._sanitize_watch_processor_kwargs(processor_args),)- enqueue_lock = resource_lock- resource_lock = Nonetask = await self._enqueue_add_resource_job(msg,queue_name=QueueManager.ADD_RESOURCE,- resource_lock=enqueue_lock,+ resource_lock=resource_lock,)+ resource_lock = NO_LOCKreturn {"status": "success","root_uri": root_uri,"task_id": task.task_id,}except Exception:- if resource_lock is not None:- await self._viking_fs._async_agfs.pathlock_release(resource_lock)+ await resource_lock.close()raiseasync def _plan_resource_target(@@ -633,7 +629,7 @@ class ResourceService:target: ContentTargetSpec,source_name: Optional[str],source_info: _ResourceSourceInfo,- ) -> tuple[str, Optional[Dict[str, Any]]]:+ ) -> tuple[str, LockLease]:if not self._resource_processor or not self._viking_fs:raise NotInitializedError("ResourceProcessor")@@ -655,10 +651,14 @@ 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._viking_fs._async_agfs.pathlock_acquire_tree(+ resource_lock = await self._resource_processor.acquire_resource_lock(+ get_lock_manager(),dst_path,- timeout_secs=0.0,+ uri=root_uri,+ timeout=0.0,)return root_uri, resource_lock@@ -961,7 +961,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[Dict[str, Any]] = None,+ resource_lock: Optional[LockLease] = None,stage_callback: Optional[Callable[[str], Any]] = None,**kwargs,) -> Dict[str, Any]:@@ -972,7 +972,7 @@ class ResourceService:telemetry_id = register_wait_telemetry(wait)request_wait_tracker = get_request_wait_tracker()job_enqueued = False- deferred_lock: Optional[Dict[str, Any]] = None+ deferred_lock: LockLease = NO_LOCKif telemetry_id:request_wait_tracker.register_request(telemetry_id)watch_manager = self._get_watch_manager()@@ -1070,18 +1070,19 @@ class ResourceService:)if self._viking_fs is None:raise NotInitializedError("VikingFS")- from openviking.storage.errors import ResourceBusyError+ from openviking.storage.errors import LockAcquisitionError, ResourceBusyError+ from openviking.storage.transaction import OwnedLockLease, get_lock_manager- lock_lease: Optional[Dict[str, Any]] = None+ lock_manager = get_lock_manager()+ lock_lease: LockLease = NO_LOCK- async def _reserve_tree(uri: str) -> Dict[str, Any]:+ async def _reserve_tree(uri: str) -> LockLease:dst_path = self._viking_fs._uri_to_path(uri, ctx=ctx)try:- return await self._viking_fs._async_agfs.pathlock_acquire_tree(- dst_path,- timeout_secs=0.0,+ return await OwnedLockLease.acquire_tree(+ lock_manager, dst_path, timeout=0.0)- except Exception as exc:+ except LockAcquisitionError as exc:raise ResourceBusyError(f"Resource is busy: {uri}",uri=uri,@@ -1114,11 +1115,7 @@ class ResourceService:if resolved_extension:processor_args["resolved_extension"] = resolved_extension- lock_handoff = (- await self._viking_fs._async_agfs.pathlock_to_handoff(lock_lease)- if lock_lease is not None- else None- )+ lock_handoff = lock_lease.to_handoff()msg = AddResourceMsg(task_id=str(uuid4()),telemetry_id=telemetry_id or None,@@ -1145,23 +1142,22 @@ class ResourceService:enforce_public_remote_targets=enforce_public_remote_targets,args=processor_args,source_name=source_name,- lock_handoff=lock_handoff,+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,skip_watch_management=True,defer_target_resolution=defer_target_resolution,understanding_response_id=understanding_response_id,)enqueue_started = True- enqueue_lock = lock_lease- lock_lease = Nonetask = await self._enqueue_add_resource_job(msg,queue_name=QueueManager.EXTERNAL_PARSE,- resource_lock=enqueue_lock,+ resource_lock=lock_lease,)except BaseException:- if not enqueue_started and lock_lease is not None:- await self._viking_fs._async_agfs.pathlock_release(lock_lease)+ if not enqueue_started:+ await lock_lease.close()raise+ lock_lease = NO_LOCKjob_enqueued = Truelogger.info("[ResourceService] Enqueued AddResourceMsg task_id=%s root_uri=%s",@@ -1214,7 +1210,7 @@ class ResourceService:if result.get("status") == "error":return resultprepared = result.pop("_post_process", None)- deferred_lock = result.pop("_resource_lock", None)+ deferred_lock = result.pop("_resource_lock", NO_LOCK)if wait:if stage_callback is not None:stage_result = stage_callback("processing_queue")@@ -1268,11 +1264,7 @@ class ResourceService:root_uri = result.get("root_uri", "")if not isinstance(prepared, dict):raise InternalError("Deferred resource processing payload is missing")- lock_handoff = (- await self._viking_fs._async_agfs.pathlock_to_handoff(deferred_lock)- if deferred_lock is not None- else None- )+ lock_handoff = deferred_lock.to_handoff()msg = AddResourceMsg(task_id=str(uuid4()),root_uri=root_uri,@@ -1282,7 +1274,7 @@ class ResourceService:user_id=ctx.user.user_id,role=str(ctx.role),actor_peer_id=ctx.actor_peer_id,- lock_handoff=lock_handoff,+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,reason=reason,instruction=instruction,timeout=timeout,@@ -1301,13 +1293,12 @@ class ResourceService:source_name=kwargs.get("source_name"),skip_watch_management=True,)- enqueue_lock = deferred_lock- deferred_lock = Nonetask = await self._enqueue_add_resource_job(msg,queue_name=QueueManager.ADD_RESOURCE,- resource_lock=enqueue_lock,+ resource_lock=deferred_lock,)+ deferred_lock = NO_LOCKresult["task_id"] = task.task_idjob_enqueued = Trueawait self._manage_watch_if_needed(@@ -1352,8 +1343,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 is not None:- await self._viking_fs._async_agfs.pathlock_release(deferred_lock)+ if deferred_lock.active:+ await deferred_lock.close()async def _link_resource_reason_memory(self,diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.pyindex 8b19a3705..8322cd048 100644--- a/openviking/session/compressor_v2.py+++ b/openviking/session/compressor_v2.py@@ -179,9 +179,7 @@ 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(@@ -284,14 +282,17 @@ class SessionCompressorV2:telemetry.set("memory.extract.deleted", 0)telemetry.set("memory.extract.skipped", 0)- from openviking.storage.errors import LockAcquisitionError+ from openviking.storage.transaction import get_lock_manager, init_lock_manager- # 初始化锁(仅在有 AGFS 时使用锁机制)+ # 初始化锁管理器(仅在有 AGFS 时使用锁机制)viking_fs = get_viking_fs()- lease = None+ lock_manager = Nonetransaction_handle = None- has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs- if not has_agfs:+ 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:logger.debug("AGFS unavailable, running memory extraction without locks")try:@@ -329,7 +330,7 @@ class SessionCompressorV2:context_provider=context_provider,)read_scope = isolation_handler.get_read_scope()- if has_agfs:+ if lock_manager:schemas = orchestrator.context_provider.get_memory_schemas(ctx)exact_lock_paths, tree_lock_dirs = _render_memory_schema_locks(schemas=schemas,@@ -349,30 +350,28 @@ class SessionCompressorV2:# 循环重试获取锁(机制确保不会死锁)while True:- try:- lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(- exact_lock_paths,- tree_lock_dirs,- timeout_secs=0.1,- )+ 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:break- 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,+ 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})")- if retry_interval > 0:- await asyncio.sleep(retry_interval)- transaction_handle = lease+ 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)orchestrator._transaction_handle = transaction_handle # 传递给 ExtractLoop@@ -470,12 +469,12 @@ class SessionCompressorV2:raisereturn []finally:- # 确保释放所有锁- if lease is not None:+ # 确保释放所有锁(仅在有锁管理器时)+ if lock_manager and transaction_handle:try:- await viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(transaction_handle)except Exception as e:- logger.warning(f"Failed to release pathlock: {e}")+ logger.warning(f"Failed to release transaction lock: {e}")@staticmethoddef _empty_memory_diff(archive_uri: str = "") -> Dict[str, Any]:@@ -593,7 +592,7 @@ class SessionCompressorV2:async def _append_sources_before_unlock(result: MemoryUpdateResult,inheritance_map: Dict[str, List[str]],- lease_ref: Any,+ lock_handle: Any,exp_provider=exp_provider,exp_dir=exp_dir,traj_uri=traj_uri,@@ -613,7 +612,7 @@ class SessionCompressorV2:source_uris,ctx,viking_fs,- lease_ref=lease_ref,+ lock_handle=lock_handle,)exp_result = await self._run_extract_phase(@@ -733,7 +732,7 @@ class SessionCompressorV2:Returns None on failure (unless strict_extract_errors is True, in which casethe exception is re-raised)."""- from openviking.storage.errors import LockAcquisitionError+ from openviking.storage.transaction import get_lock_manager, init_lock_managerconfig = get_openviking_config()vlm = config.vlm.get_vlm_instance()@@ -765,12 +764,15 @@ class SessionCompressorV2:thinking=thinking,)- lease = None+ lock_manager = Nonetransaction_handle = None- has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs+ 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()try:- if has_agfs:+ if lock_manager:schemas = [schemafor schema in provider.get_memory_schemas(ctx)@@ -790,30 +792,28 @@ class SessionCompressorV2:retry_count = 0last_lock_retry_warning_at = 0.0while True:- try:- lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(- exact_lock_paths,- tree_lock_dirs,- timeout_secs=0.1,- )+ 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:break- 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,+ 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})")- if retry_interval > 0:- await asyncio.sleep(retry_interval)-- transaction_handle = lease+ 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)provider._transaction_handle = transaction_handleorchestrator._transaction_handle = transaction_handle@@ -916,11 +916,11 @@ class SessionCompressorV2:raisereturn Nonefinally:- if lease is not None:+ if lock_manager and transaction_handle:try:- await viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(transaction_handle)except Exception as e:- logger.warning(f"[{phase_label}] Failed to release pathlock: {e}")+ logger.warning(f"[{phase_label}] Failed to release transaction lock: {e}")async def _resolve_supersedes(self,@@ -997,7 +997,7 @@ class SessionCompressorV2:traj_uris: List[str],ctx,viking_fs,- lease_ref: Optional[Any] = None,+ lock_handle: Optional[Any] = None,) -> None:"""Write bidirectional StoredLinks between traj_uris and each exp file.@@ -1010,28 +1010,33 @@ class SessionCompressorV2:for exp_uri in exp_uris:try:- 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-try:+ from openviking.storage.transaction import LockContext, get_lock_manager++ 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:await self._append_trajectory_metadata(exp_uri,normalized_traj_uris,ctx,viking_fs,- lease_ref=lease,+ lock_handle=active_lock_handle,)- 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}")@@ -1041,7 +1046,7 @@ class SessionCompressorV2:traj_uris: List[str],ctx,viking_fs,- lease_ref=None,+ lock_handle=None,) -> None:from datetime import timezone@@ -1065,11 +1070,12 @@ 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,- lease_ref=lease_ref,+ lock_handle=lock_handle,)tracer.info(f"[agent_link] wrote exp→traj links -> {exp_uri} (traj_count={len(traj_uris)})"@@ -1078,7 +1084,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}, lease_ref=lease_ref)+ await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri})async def _build_memory_diff(self,diff --git a/openviking/session/compressor_v3.py b/openviking/session/compressor_v3.pyindex dc5659c6f..95e611a5a 100644--- a/openviking/session/compressor_v3.py+++ b/openviking/session/compressor_v3.py@@ -184,6 +184,7 @@ 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 2cd9da81e..7596fdc80 100644--- a/openviking/session/memory/memory_updater.py+++ b/openviking/session/memory/memory_updater.py@@ -76,13 +76,14 @@ async def write_stored_links(ctx: RequestContext,viking_fs: Any,skip_uris: Optional[set] = None,- lease_ref: Any = None,+ lock_handle: 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.@@ -90,6 +91,7 @@ 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:@@ -120,7 +122,7 @@ async def write_stored_links(uri,MemoryFileUtils.write(mf),ctx=ctx,- lease_ref=lease_ref,+ **lock_kwargs,)updated_uris.append(uri)except Exception as e:@@ -128,6 +130,7 @@ 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:@@ -149,7 +152,6 @@ 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@@ -291,7 +293,6 @@ 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)@@ -303,7 +304,6 @@ 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,7 +315,6 @@ 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)@@ -712,12 +711,8 @@ class MemoryUpdater:"""def __init__(- self,- registry: Optional[MemoryTypeRegistry] = None,- vikingdb=None,- transaction_handle: Any = None,+ self, registry: Optional[MemoryTypeRegistry] = None, vikingdb=None, transaction_handle=None):- """Create a memory updater with an optional pathlock transaction handle."""self._viking_fs = Noneself._registry = registryself._vikingdb = vikingdb@@ -851,7 +846,6 @@ 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():@@ -872,12 +866,7 @@ class MemoryUpdater:list(getattr(operations, "resolved_links", []) or []),dict(getattr(operations, "delete_replacements", {}) or {}),)- await self._inherit_deleted_link_relations(- operations,- result,- ctx,- lease_ref=self._transaction_handle,- )+ await self._inherit_deleted_link_relations(operations, result, ctx)# Apply delete operations (delete_file_contents is List[MemoryFile])# Skip deletes whose URI was just written in the same batch — this happens when the@@ -907,13 +896,13 @@ class MemoryUpdater:)continuetry:- await self._apply_delete(delete_uri, ctx, lease_ref=self._transaction_handle)+ await self._apply_delete(delete_uri, ctx)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, lease_ref=self._transaction_handle)+ await self._sync_resource_refs_for_result(result, ctx)# Vectorize written and edited memoriesuri_memory_type_map = {}@@ -934,7 +923,6 @@ class MemoryUpdater:result,ctx,deleted_uris=set(result.deleted_uris),- lease_ref=self._transaction_handle,)tracer.info(f"Memory operations applied: {result.summary()}")@@ -955,13 +943,7 @@ class MemoryUpdater:)for dir, memory_type in dirs.items():- await self.generate_overview(- memory_type,- dir,- ctx,- extract_context,- lease_ref=self._transaction_handle,- )+ await self.generate_overview(memory_type, dir, ctx, extract_context)return result@@ -969,7 +951,6 @@ 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()@@ -993,17 +974,13 @@ class MemoryUpdater:uri,MemoryFileUtils.write(mf),ctx=ctx,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)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,- lease_ref: Any = None,+ self, resolved_op: ResolvedOperation, ctx: RequestContext, extract_context: Any = None):"""Apply upsert operation from a flat model."""viking_fs = self._get_viking_fs()@@ -1119,7 +1096,7 @@ class MemoryUpdater:uri,new_full_content,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)def _distribute_links_to_operations(self, operations: ResolvedOperations) -> None:@@ -1156,7 +1133,6 @@ 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()@@ -1177,15 +1153,15 @@ class MemoryUpdater:ctx,viking_fs,skip_uris=skip,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)+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:@@ -1203,9 +1179,7 @@ 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@@ -1262,25 +1236,22 @@ class MemoryUpdater:uri,MemoryFileUtils.write(mf),ctx=ctx,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)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,- lease_ref: Any = None,- ) -> None:+ async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:"""Apply delete operation (uri is already a string)."""viking_fs = self._get_viking_fs()# Delete from VikingFS- # VikingFS automatically handles vector index cleanup.+ # 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).try:- await viking_fs.rm(uri, recursive=False, ctx=ctx, lease_ref=lease_ref)+ await viking_fs.rm(uri, recursive=False, ctx=ctx, lock_handle=self._transaction_handle)except NotFoundError:tracer.error(f"Memory not found for delete: {uri}")# Idempotent - deleting non-existent file succeeds@@ -1426,7 +1397,6 @@ 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.@@ -1483,7 +1453,7 @@ class MemoryUpdater:overview_path,recursive=False,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)except Exception:pass@@ -1494,7 +1464,7 @@ class MemoryUpdater:directory,recursive=True,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)except Exception:pass@@ -1549,7 +1519,7 @@ class MemoryUpdater:overview_path,rendered,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=self._transaction_handle,)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 4453463f0..540cc1432 100644--- a/openviking/session/memory/streaming_memory_updater.py+++ b/openviking/session/memory/streaming_memory_updater.py@@ -442,6 +442,7 @@ 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 2bbd76479..b28a8745e 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -696,8 +696,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, lease_ref: Optional[Any] = None) -> None:- """Persist .meta.json to storage using an optional held PathLock lease."""+ async def _save_meta(self) -> None:+ """Persist .meta.json to storage."""if not self._viking_fs:returnself._meta.updated_at = get_current_timestamp()@@ -705,7 +705,6 @@ 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@@ -1124,11 +1123,15 @@ 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)- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS- )- try:+ async with LockContext(+ get_lock_manager(),+ [session_path],+ lock_mode="exact",+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,+ ):self._messages = await self._read_live_messages_strict()in_memory_meta = self._metatry:@@ -1148,11 +1151,8 @@ class Session:f"{self._session_uri}/messages.jsonl",batch_content,ctx=self.ctx,- lease_ref=lease,)- await self._save_meta(lease_ref=lease)- finally:- await self._viking_fs._async_agfs.pathlock_release(lease)+ await self._save_meta()async def _append_messages_without_path_lock(self, messages: List[Message]) -> None:"""Compatibility append for storage adapters without path locking."""@@ -1418,12 +1418,7 @@ 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],- lease_ref: Optional[Any] = None,- ) -> None:+ async def _merge_archive_meta(self, archive_uri: str, updates: Dict[str, Any]) -> None:"""Merge archive metadata so Phase 2 cannot erase Phase 1 planning data."""if not self._viking_fs:return@@ -1444,7 +1439,6 @@ class Session:uri=f"{archive_uri}/.meta.json",content=json.dumps(meta, ensure_ascii=False),ctx=self.ctx,- lease_ref=lease_ref,)@staticmethod@@ -1483,7 +1477,6 @@ 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 = {@@ -1509,15 +1502,9 @@ class Session:"skip_reason": agent_memory_skip_reason,},},- lease_ref=lease_ref,)- 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."""+ async def _write_phase1_ready_marker(self, archive_uri: str) -> None:phase1 = await self._read_phase1_meta(archive_uri)phase1.update({@@ -1525,7 +1512,7 @@ class Session:"ready_at": get_current_timestamp(),})- await self._merge_archive_meta(archive_uri, {"phase1": phase1}, lease_ref=lease_ref)+ await self._merge_archive_meta(archive_uri, {"phase1": phase1})async def _archive_file_exists(self, archive_uri: str, file_name: str) -> bool:try:@@ -1555,11 +1542,15 @@ 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)- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS- )- try:+ async with LockContext(+ get_lock_manager(),+ [session_path],+ lock_mode="exact",+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,+ ):marker = await self._read_phase1_meta(archive_uri)if marker.get("status") == "ready":return True@@ -1581,21 +1572,20 @@ 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@@ -1613,7 +1603,9 @@ 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)),@@ -1626,12 +1618,10 @@ class Session:)self._meta.last_commit_at = get_current_timestamp()self._rebuild_pending_tokens()- await self._save_meta(lease_ref=lease)- await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)+ await self._save_meta()+ await self._write_phase1_ready_marker(archive_uri)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,@@ -1687,6 +1677,7 @@ 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))@@ -1742,10 +1733,12 @@ 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)- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS- )- try:+ async with LockContext(+ get_lock_manager(),+ [session_path],+ lock_mode="exact",+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,+ ):self._messages = await self._read_live_messages_strict()try:meta_content = await self._viking_fs.read_file(@@ -1797,7 +1790,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(lease_ref=lease)+ await self._save_meta()get_current_telemetry().set("memory.extracted", 0)return {"session_id": self.session_id,@@ -1837,7 +1830,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, lease_ref=lease)+ await self._write_to_agfs_async(messages=self._messages)self._meta.pending_tokens = 0self._meta.message_count = totalself._remember_retention_policy(@@ -1847,7 +1840,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(lease_ref=lease)+ await self._save_meta()get_current_telemetry().set("memory.extracted", 0)return {"session_id": self.session_id,@@ -1898,7 +1891,6 @@ 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@@ -1909,7 +1901,6 @@ 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(@@ -1922,7 +1913,6 @@ class Session:min_raw_tail_steps=effective_min_tail,)},- lease_ref=lease,)phase1_stage = "queue_enqueue"@@ -1947,7 +1937,7 @@ class Session:phase1_stage = "phase1_persist"self._messages = retained_messages- await self._write_to_agfs_async(messages=self._messages, lease_ref=lease)+ await self._write_to_agfs_async(messages=self._messages)self._meta.message_count = len(self._messages)self._meta.pending_tokens = 0self._remember_retention_policy(@@ -1962,8 +1952,8 @@ class Session:self._compression.compression_index,)self._meta.last_commit_at = get_current_timestamp()- await self._save_meta(lease_ref=lease)- await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)+ await self._save_meta()+ await self._write_phase1_ready_marker(archive_uri)except Exception as e:logger.error(f"[commit] Failed during {phase1_stage}: {e}")# Whether the queue write failed or a queued Phase 1 stopped@@ -1974,7 +1964,6 @@ class Session:archive_uri,stage=phase1_stage,error=str(e),- lease_ref=lease,)except Exception:logger.exception(@@ -1984,8 +1973,6 @@ 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.@@ -2105,17 +2092,23 @@ 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 True+ )agent_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,@@ -2701,7 +2694,6 @@ 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:@@ -2719,7 +2711,6 @@ 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]:@@ -3390,7 +3381,9 @@ 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@@ -3408,7 +3401,9 @@ 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@@ -3492,7 +3487,9 @@ 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:@@ -3583,11 +3580,15 @@ 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)- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS- )- try:+ async with LockContext(+ get_lock_manager(),+ [session_path],+ lock_mode="exact",+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,+ ):latest_meta = self._metatry:meta_content = await self._viking_fs.read_file(@@ -3621,9 +3622,7 @@ 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(lease_ref=lease)- finally:- await self._viking_fs._async_agfs.pathlock_release(lease)+ await self._save_meta()async def _read_live_message_count(self) -> int:"""Count current live session messages from persisted storage."""@@ -4810,12 +4809,8 @@ class Session:return "\n".join(parts).rstrip() + "\n"- 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."""+ async def _write_to_agfs_async(self, messages: List[Message]) -> None:+ """Write messages.jsonl to AGFS (async)."""if not self._viking_fs:return@@ -4832,19 +4827,16 @@ 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 897ac3ccf..a43f3ac0e 100644--- a/openviking/session/train/components/policy_updater.py+++ b/openviking/session/train/components/policy_updater.py@@ -130,7 +130,9 @@ 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)@@ -223,6 +225,7 @@ 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,@@ -244,7 +247,8 @@ def _plan_to_resolved_operations(!= _normalize_guard_content(item.before_content)):errors.append(- f"base content mismatch for {item.target_name}: expected gradient before_content"+ "base content mismatch for "+ f"{item.target_name}: expected gradient before_content")continue@@ -260,7 +264,9 @@ 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 500341840..2bea52390 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, lease_ref=transaction_handle)+ await viking_fs.rm(skill_root, ctx=ctx, lock_handle=transaction_handle)deleted_uris.append(old_file.uri)except Exception as exc:delete_errors.append(f"{old_file.uri}: {exc}")@@ -138,7 +138,9 @@ 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)@@ -237,7 +239,9 @@ 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 6e66158bf..b7348952c 100644--- a/openviking/session/train/domain.py+++ b/openviking/session/train/domain.py@@ -80,12 +80,19 @@ 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)- lease = await self.viking_fs._async_agfs.pathlock_acquire_tree(path, timeout_secs=300.0)+ 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}")try:- yield lease+ yield handlefinally:- await self.viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(handle)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 6a4a776ce..304eea4c6 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 Any, Dict, Optional+from typing import TYPE_CHECKING, Any, Dict, Optionalfrom openviking.core.namespace import (NamespaceShapeError,@@ -27,9 +27,10 @@ from openviking.session.memory.utils.resource_refs import (RESOURCE_REF_SOURCE_CONTENT_WRITE,sync_memory_resource_refs,)-from openviking.storage.errors import LockAcquisitionError, ResourceBusyError+from openviking.storage.errors import 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@@ -50,19 +51,12 @@ 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@@ -160,14 +154,16 @@ 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)- try:- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(root_path)- except LockAcquisitionError as exc:+ acquired = await lock_manager.acquire_tree(handle, root_path)+ if not acquired:+ await lock_manager.release(handle)raise ResourceBusyError(f"resource is busy and cannot be written now: {normalized_root}",uri=normalized_root,- ) from exc+ )created: list[str] = []updated: list[str] = []@@ -230,7 +226,7 @@ class ContentWriteCoordinator:uri,operation["content"],ctx=ctx,- lease_ref=lease,+ lock_handle=handle,)except Exception as exc:write_error = exc@@ -242,7 +238,7 @@ class ContentWriteCoordinator:created.append(uri)refresh_kinds[uri] = "added"finally:- await self._viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(handle)lock_released = Trueassert lock_released@@ -693,14 +689,16 @@ 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)- try:- lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)- except LockAcquisitionError as exc:+ acquired = await lock_manager.acquire_exact_path(handle, lock_path)+ if not acquired:+ await lock_manager.release(handle)raise ResourceBusyError(f"resource is busy and cannot be written now: {uri}",uri=uri,- ) from exc+ )previous_content: Optional[str] = Nonecontent_written = False@@ -711,7 +709,13 @@ 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, lease_ref=lease)+ await self._write_in_place(+ uri,+ content,+ mode=mode,+ ctx=ctx,+ lock_handle=handle,+ )content_written = Trueawait self._enqueue_semantic_refresh(root_uri=root_uri,@@ -721,7 +725,7 @@ class ContentWriteCoordinator:change_type="added" if mode == "create" else "modified",)semantic_enqueued = True- await self._viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(handle)lock_released = Truequeue_status = (await self._wait_for_request(telemetry_id=telemetry_id, timeout=timeout)@@ -744,10 +748,10 @@ class ContentWriteCoordinator:previous_content=previous_content,mode=mode,ctx=ctx,- lease_ref=lease,+ lock_handle=handle,)if not lock_released:- await self._viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(handle)raisefinally:if wait and telemetry_id:@@ -760,18 +764,18 @@ class ContentWriteCoordinator:previous_content: Optional[str],mode: str,ctx: RequestContext,- lease_ref: Optional[Dict[str, Any]] = None,+ lock_handle: Any,) -> None:try:if mode == "create":- await self._viking_fs.rm(uri, ctx=ctx, lease_ref=lease_ref)+ await self._viking_fs.rm(uri, ctx=ctx, lock_handle=lock_handle)returnif previous_content is not None:await self._viking_fs.write_file(uri,previous_content,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=lock_handle,)except Exception:logger.error("Failed to rollback direct content write for %s", uri, exc_info=True)@@ -881,7 +885,7 @@ class ContentWriteCoordinator:*,mode: str,ctx: RequestContext,- lease_ref: Optional[Dict[str, Any]] = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:if context_type_for_uri(uri) == "memory":if mode == "replace":@@ -899,7 +903,7 @@ class ContentWriteCoordinator:uri,MemoryFileUtils.write(mf),ctx=ctx,- lease_ref=lease_ref,+ lock_handle=lock_handle,)return@@ -908,9 +912,14 @@ 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, lease_ref=lease_ref)+ await self._viking_fs.write_file(+ uri,+ updated_raw,+ ctx=ctx,+ lock_handle=lock_handle,+ )return- await self._viking_fs.write_file(uri, content, ctx=ctx, lease_ref=lease_ref)+ await self._viking_fs.write_file(uri, content, ctx=ctx, lock_handle=lock_handle)async def _enqueue_semantic_refresh(self,@@ -968,20 +977,28 @@ 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)- try:- lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)- except LockAcquisitionError as exc:+ acquired = await lock_manager.acquire_exact_path(handle, lock_path)+ if not acquired:+ await lock_manager.release(handle)raise ResourceBusyError(f"resource is busy and cannot be written now: {uri}",uri=uri,- ) from exc+ )released = Falserequest_registered = Falsetry:- await self._write_in_place(uri, content, mode=mode, ctx=ctx, lease_ref=lease)- await self._viking_fs._async_agfs.pathlock_release(lease)+ await self._write_in_place(+ uri,+ content,+ mode=mode,+ ctx=ctx,+ lock_handle=handle,+ )+ await lock_manager.release(handle)released = Trueif wait and telemetry_id and self._vikingdb_has_queue():get_request_wait_tracker().register_request(telemetry_id)@@ -1024,7 +1041,7 @@ class ContentWriteCoordinator:)except Exception:if not released:- await self._viking_fs._async_agfs.pathlock_release(lease)+ await lock_manager.release(handle)raisefinally:if request_registered:diff --git a/openviking/storage/observers/__init__.py b/openviking/storage/observers/__init__.pyindex 841cd7144..b95548026 100644--- a/openviking/storage/observers/__init__.py+++ b/openviking/storage/observers/__init__.py@@ -2,6 +2,7 @@# 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@@ -10,6 +11,7 @@ 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.pynew file mode 100644index 000000000..1e7bc5e81--- /dev/null+++ b/openviking/storage/observers/lock_observer.py@@ -0,0 +1,74 @@+# 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 771c2102b..05fb0edbf 100644--- a/openviking/storage/queuefs/add_resource_processor.py+++ b/openviking/storage/queuefs/add_resource_processor.py@@ -29,19 +29,21 @@ 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 self._viking_fs._async_agfs.pathlock_adopt(msg.lock_handoff)+ return await OwnedLockLease.from_handoff(ref)except Exception as handoff_error:try:return await self._resource_service.reacquire_add_resource_job_lock(@@ -177,7 +179,7 @@ class AddResourceProcessor(DequeueHandlerBase):finally:with suppress(Exception):if resource_lock is not None:- await self._viking_fs._async_agfs.pathlock_release(resource_lock)+ await resource_lock.close()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 ab40306d2..2006d9875 100644--- a/openviking/storage/queuefs/semantic_dag.py+++ b/openviking/storage/queuefs/semantic_dag.py@@ -5,11 +5,12 @@import asyncioimport threadingfrom dataclasses import dataclass, field-from typing import Any, ClassVar, Dict, List, Optional, Set+from typing import ClassVar, Dict, List, Optional, Setfrom weakref import WeakKeyDictionaryfrom 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@@ -166,7 +167,7 @@ class SemanticDagExecutor:semantic_msg_id: Optional[str] = None,telemetry_id: str = "",recursive: bool = True,- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,is_code_repo: bool = False,changes: Optional[Dict[str, List[str]]] = None,skip_vectorization: bool = False,@@ -225,12 +226,15 @@ class SemanticDagExecutor:if self._failure:raise self._failure- # Mark semantic done after downstream vectorization finishes.+ # Release owned semantic locks after downstream vectorization finishes.async def wrapped_on_complete() -> None:- if self._telemetry_id and self._semantic_msg_id:- get_request_wait_tracker().mark_semantic_done(- self._telemetry_id, self._semantic_msg_id- )+ 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()async with self._vectorize_lock:task_count = self._vectorize_task_count@@ -256,6 +260,10 @@ 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 cd82e96d2..f6e059920 100644--- a/openviking/storage/queuefs/semantic_lock.py+++ b/openviking/storage/queuefs/semantic_lock.py@@ -5,20 +5,25 @@from __future__ import annotationsfrom dataclasses import dataclass-from typing import Any, Callable, Dict, Iterable, Optional+from typing import Callable, Iterable, Optionalfrom openviking.storage.errors import LockAcquisitionError-from openviking.storage.internal_names import MULTIWRITE_PATH_LOCK_FILE-from openviking.storage.viking_fs import get_viking_fs+from openviking.storage.transaction import (+ NO_LOCK,+ LockHandoffRef,+ LockLease,+ OwnedLockLease,+ get_lock_manager,+)+from openviking.storage.transaction.path_lock import LOCK_FILE_NAMEfrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)-_TREE_LOCK_SUFFIX = f"/{MULTIWRITE_PATH_LOCK_FILE}"+_TREE_LOCK_SUFFIX = f"/{LOCK_FILE_NAME}"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):@@ -33,48 +38,52 @@ def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:class SemanticLockScope:"""Resolved lock scope for one semantic message."""- lock: Optional[Dict[str, Any]] # lease dict or None- _owned: bool = False # True when this scope owns the lease (must release)+ lock: LockLease@classmethodasync def resolve(cls,- lock_handoff: Optional[Dict[str, Any]],+ lock_handoff: Optional[LockHandoffRef],*,- caller_lock: Optional[Dict[str, Any]] = None,+ caller_lock: LockLease = NO_LOCK,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 is not None:+ if lock_handoff and caller_lock.active:raise ValueError("semantic lock must come from either message or caller, not both")- 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 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 lock_handoff:- viking_fs = get_viking_fs()+ manager = get_lock_manager()try:- 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"])+ return cls(await OwnedLockLease.from_handoff(lock_handoff, manager=manager))+ except LockAcquisitionError as exc:+ 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:- lease = await viking_fs._async_agfs.pathlock_acquire_tree(tree_paths[0])+ acquired = await manager.acquire_tree(handle, tree_paths[0])else:- lease = await viking_fs._async_agfs.pathlock_acquire_tree_batch(tree_paths)+ 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 exclogger.info("Recovered semantic lock handoff %s by reacquiring %s",- lock_handoff.get("owner_id"),+ lock_handoff.handle_id,tree_paths,)- return cls(lease, _owned=True)- return cls(None)+ return cls(OwnedLockLease.from_handle(manager, handle))+ return cls(NO_LOCK)async def close(self) -> None:- """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)+ await self.lock.close()diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.pyindex 80303e6bd..a71a77161 100644--- a/openviking/storage/queuefs/semantic_msg.py+++ b/openviking/storage/queuefs/semantic_msg.py@@ -8,6 +8,8 @@ from datetime import datetimefrom typing import Any, Dict, List, Optionalfrom uuid import uuid4+from openviking.storage.transaction import LockHandoffRef+def build_semantic_coalesce_key(*,@@ -50,7 +52,7 @@ class SemanticMsg:skip_vectorization: bool = Falsetelemetry_id: str = ""target_uri: str = ""- lock_handoff: Optional[Dict[str, Any]] = None+ lock_handoff: Optional[LockHandoffRef] = Noneis_code_repo: bool = Falsetarget_preexisting: Optional[bool] = Nonecoalesce_key: str = ""@@ -71,7 +73,7 @@ class SemanticMsg:skip_vectorization: bool = False,telemetry_id: str = "",target_uri: str = "",- lock_handoff: Optional[Dict[str, Any]] = None,+ lock_handoff: Optional[LockHandoffRef] = None,is_code_repo: bool = False,target_preexisting: Optional[bool] = None,coalesce_key: str = "",@@ -132,7 +134,7 @@ class SemanticMsg:skip_vectorization=data.get("skip_vectorization", False),telemetry_id=data.get("telemetry_id", ""),target_uri=data.get("target_uri", ""),- lock_handoff=data.get("lock_handoff"),+ lock_handoff=LockHandoffRef.from_value(data.get("lock_handoff")),is_code_repo=data.get("is_code_repo", False),target_preexisting=data.get("target_preexisting"),coalesce_key=data.get("coalesce_key", ""),diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.pyindex a7175ebeb..016a03e15 100644--- a/openviking/storage/queuefs/semantic_processor.py+++ b/openviking/storage/queuefs/semantic_processor.py@@ -39,6 +39,7 @@ 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@@ -305,7 +306,7 @@ class SemanticProcessor(DequeueHandlerBase):async def on_dequeue(self,data: Optional[Dict[str, Any]],- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,) -> Optional[Dict[str, Any]]:"""Process dequeued SemanticMsg, recursively process all subdirectories."""msg: Optional[SemanticMsg] = None@@ -371,8 +372,10 @@ 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,@@ -440,6 +443,7 @@ 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,@@ -449,7 +453,8 @@ class SemanticProcessor(DequeueHandlerBase):if not executor.stale:await self._enqueue_parent_refresh(msg, target_uri or msg.uri)finally:- await semantic_lock.close()+ if not lock_transferred:+ 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()@@ -516,7 +521,7 @@ class SemanticProcessor(DequeueHandlerBase):self,msg: SemanticMsg,ctx: Optional[RequestContext] = None,- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,) -> None:"""Process a memory directory with special handling.@@ -710,7 +715,7 @@ class SemanticProcessor(DequeueHandlerBase):)logger.info(f"Vectorized abstract.md and overview.md for {dir_uri}")finally:- pass+ await lock.close()async def _write_memory_directory_semantics(self,@@ -721,7 +726,7 @@ class SemanticProcessor(DequeueHandlerBase):overview: str,abstract: str,ctx: Optional[RequestContext],- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,) -> bool:return await write_semantic_sidecars(viking_fs=viking_fs,@@ -740,7 +745,7 @@ class SemanticProcessor(DequeueHandlerBase):target_uri: str,ctx: Optional[RequestContext] = None,file_change_status: Optional[Dict[str, bool]] = None,- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,) -> DiffResult:viking_fs = get_viking_fs()if not await viking_fs.exists(root_uri, ctx=ctx):@@ -748,6 +753,7 @@ 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] = {}@@ -785,7 +791,7 @@ class SemanticProcessor(DequeueHandlerBase):target_conflict_dir,recursive=True,ctx=ctx,- lease_ref=lock,+ lock_handle=lock_handle,)diff.deleted_dirs.append(target_conflict_dir)target_dirs.pop(name, None)@@ -797,7 +803,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, lease_ref=lock)+ await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)diff.deleted_files.append(target_file)target_files.pop(name, None)except Exception as e:@@ -808,7 +814,7 @@ class SemanticProcessor(DequeueHandlerBase):if target_file and not root_file:try:- await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)+ await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)diff.deleted_files.append(target_file)except Exception as e:logger.error(f"[SyncDiff] Failed to delete file: {target_file}, error={e}")@@ -831,7 +837,7 @@ class SemanticProcessor(DequeueHandlerBase):if changed:diff.updated_files.append(target_file)try:- await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)+ await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)except Exception as e:logger.error(f"[SyncDiff] Failed to remove old file before update: {target_file}, error={e}"@@ -841,7 +847,7 @@ class SemanticProcessor(DequeueHandlerBase):root_file,target_file,ctx=ctx,- lease_ref=lock,+ lock_handle=lock_handle,)except Exception as e:logger.error(@@ -857,7 +863,7 @@ class SemanticProcessor(DequeueHandlerBase):root_file,target_file_uri,ctx=ctx,- lease_ref=lock,+ lock_handle=lock_handle,)except Exception as e:logger.error(@@ -875,7 +881,7 @@ class SemanticProcessor(DequeueHandlerBase):await viking_fs.rm(target_conflict_file,ctx=ctx,- lease_ref=lock,+ lock_handle=lock_handle,)diff.deleted_files.append(target_conflict_file)target_files.pop(name, None)@@ -891,7 +897,7 @@ class SemanticProcessor(DequeueHandlerBase):target_subdir,recursive=True,ctx=ctx,- lease_ref=lock,+ lock_handle=lock_handle,)diff.deleted_dirs.append(target_subdir)except Exception as e:@@ -908,7 +914,7 @@ class SemanticProcessor(DequeueHandlerBase):root_subdir,target_subdir_uri,ctx=ctx,- lease_ref=lock,+ lock_handle=lock_handle,)except Exception as e:logger.error(@@ -923,14 +929,9 @@ 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,- lease_ref=lock,- )+ await viking_fs.mkdir(parent_uri.uri, exist_ok=True, ctx=ctx)diff.added_dirs.append(target_uri)- await viking_fs.mv(root_uri, target_uri, ctx=ctx, lease_ref=lock)+ await viking_fs.mv(root_uri, target_uri, ctx=ctx, lock_handle=lock_handle)# 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)@@ -952,7 +953,7 @@ class SemanticProcessor(DequeueHandlerBase):root_uri: str,target_uri: str,ctx: Optional[RequestContext] = None,- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,) -> None:"""Rewrite local image refs in the target after a temp-to-target sync.@@ -1015,14 +1016,14 @@ class SemanticProcessor(DequeueHandlerBase):target_mapping,mapping_content,ctx=ctx,- lease_ref=lock,+ lock_handle=lock.handle,)except Exception:# Target subtree may not exist (doc removed in sync); skip.passtry:- await rewrite_image_uris(target_uri, ctx=ctx, lease_ref=lock)+ await rewrite_image_uris(target_uri, ctx=ctx, lock_handle=lock.handle)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 093001491..0c5c083fd 100644--- a/openviking/storage/queuefs/semantic_sidecar.py+++ b/openviking/storage/queuefs/semantic_sidecar.py@@ -2,9 +2,10 @@# SPDX-License-Identifier: AGPL-3.0"""Shared writeback for semantic sidecar files."""-from typing import Any, Callable, Dict, Optional+from typing import Any, Callable, Optionalfrom openviking.server.identity import RequestContext+from openviking.storage.transaction import NO_LOCK, LockLeasefrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)@@ -18,31 +19,34 @@ async def write_semantic_sidecars(abstract: str,ctx: Optional[RequestContext],is_stale: Callable[[], bool],- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,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),]- 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:+ async with LockContext(lock_manager, lock_paths, lock_mode="exact", handle=lock.handle):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, sidecar_lease)+ await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, lock.handle)return True- finally:- if owns_lease:- await viking_fs._async_agfs.pathlock_release(sidecar_lease)async def _write_sidecars(@@ -51,18 +55,18 @@ async def _write_sidecars(overview: str,abstract: str,ctx: Optional[RequestContext],- lease_ref: Optional[Dict[str, Any]] = None,+ lock_handle: Any = None,) -> None:- """Write sidecar files to the target directory."""+ # TODO: This must be optimized once pathlock is pushed down into ragfs.await viking_fs.write_file(f"{dir_uri}/.overview.md",overview,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=lock_handle,)await viking_fs.write_file(f"{dir_uri}/.abstract.md",abstract,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=lock_handle,)diff --git a/openviking/storage/transaction/__init__.py b/openviking/storage/transaction/__init__.pyindex 93e772ac0..cdcd30756 100644--- a/openviking/storage/transaction/__init__.py+++ b/openviking/storage/transaction/__init__.py@@ -3,12 +3,46 @@"""Transaction module for OpenViking.-Path-lock management has been moved to the Rust ragfs layer.-Python-side lock operations now go through RAGFSBindingClient.pathlock_* methods.+Provides path-lock management and redo-log crash recovery."""+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.pynew file mode 100644index 000000000..424cca343--- /dev/null+++ b/openviking/storage/transaction/lock_context.py@@ -0,0 +1,97 @@+# 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.pynew file mode 100644index 000000000..0e2c8f084--- /dev/null+++ b/openviking/storage/transaction/lock_handle.py@@ -0,0 +1,48 @@+# 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.pynew file mode 100644index 000000000..3cbf26ddb--- /dev/null+++ b/openviking/storage/transaction/lock_lease.py@@ -0,0 +1,229 @@+# 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.pynew file mode 100644index 000000000..d31efc612--- /dev/null+++ b/openviking/storage/transaction/lock_manager.py@@ -0,0 +1,594 @@+# 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.pynew file mode 100644index 000000000..7b80c8dfb--- /dev/null+++ b/openviking/storage/transaction/path_lock.py@@ -0,0 +1,859 @@+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 bf4bdc669..e9ebfdaf7 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, Dict, List, Optional, TypeVar, Union+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, TypeVar, Unionfrom openviking.core.context import ContextLevelfrom openviking.core.namespace import (@@ -49,7 +49,10 @@ 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 STORAGE_INTERNAL_ENTRY_NAMES+from openviking.storage.internal_names import (+ MULTIWRITE_PATH_LOCK_FILE,+ STORAGE_INTERNAL_ENTRY_NAMES,+)from 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@@ -66,6 +69,7 @@ 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@@ -419,6 +423,38 @@ 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)@@ -559,39 +595,20 @@ 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, lease_ref=lease_ref)+ await self._ensure_parent_dirs(path, ctx=ctx)try:- await self._async_agfs.mkdir(path, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))+ await self._async_agfs.mkdir(path)except Exception as exc:message = str(exc).lower()already_exists = "exist" in message or "already" in message@@ -603,7 +620,7 @@ class VikingFS:uri: str,recursive: bool = False,ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> Dict[str, Any]:"""Delete file/directory + recursively update vector index.@@ -619,6 +636,7 @@ 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)@@ -664,62 +682,61 @@ class VikingFS:f"Cannot remove directory without --recursive: {uri}",details={"resource": uri, "expected_flag": "recursive"},)- lock_method = self._async_agfs.pathlock_acquire_tree+ lock_paths = [path]+ lock_mode = "tree"else:- 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)+ lock_paths = [path]+ lock_mode = "exact"try:- 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),- )- except AGFSDirectoryNotEmptyError:- raise FailedPreconditionError(- f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."+ 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 [])- except RuntimeError as e:- # Fallback for older versions without typed exceptions- if _is_directory_not_empty_error(str(e)):+ 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: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- finally:- if lease_ref is None:- await self._async_agfs.pathlock_release(lease)+ 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)async def mv(self,old_uri: str,new_uri: str,ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> Dict[str, Any]:- """Move file/directory while extending an optional outer pathlock lease.+ """Move file/directory + recursively update vector index.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@@ -770,24 +787,25 @@ class VikingFS:old_uri = canonicalize_uri(old_uri, real_ctx)new_uri = canonicalize_uri(new_uri, real_ctx)- 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,+ lock_context = (+ LockContext(+ get_lock_manager(),+ [old_path],+ lock_mode="mv",+ mv_dst_path=new_path,+ src_is_dir=True,+ 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,+ if is_dir+ else LockContext(+ get_lock_manager(),+ [old_path, new_path],+ lock_mode="exact",+ handle=lock_handle,)+ )- try:+ async with lock_context as active_lock_handle:uris_to_move = (await self._collect_uris(old_path, recursive=True, ctx=ctx) if is_dir else [])@@ -806,7 +824,7 @@ class VikingFS:is_dir=is_dir,is_temp=is_temp,ctx=ctx,- lease_ref=lease,+ lock_handle=active_lock_handle,)except Exception as e:if "not found" in str(e).lower():@@ -821,42 +839,30 @@ 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:- 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)+ await self._async_agfs.rm(new_path, recursive=True)else:- await self._async_agfs.rm(- new_path,- fs_ctx=self._pathlock_fs_ctx(ctx, lease),- )+ await self._async_agfs.rm(new_path)except Exception:passraise# Delete source- await self._async_agfs.rm(- old_path,- recursive=is_dir,- fs_ctx=self._pathlock_fs_ctx(ctx, lease),- )+ await self._async_agfs.rm(old_path, recursive=is_dir)return {}- finally:- await self._async_agfs.pathlock_release(lease)async def system_sync_status(self, uri: str, ctx: Optional[RequestContext] = None@@ -891,91 +897,39 @@ class VikingFS:is_dir: bool,is_temp: bool,ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:"""Copy source to destination for mv without deleting source."""if is_temp:- 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),- )+ await self._async_agfs.cp(+ old_path,+ new_path,+ recursive=is_dir,+ fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},+ )returnif is_dir:- await self._copy_dir_through_vikingfs(old_uri, new_uri, ctx=ctx, lease_ref=lease_ref)+ await self._copy_dir_through_vikingfs(+ old_uri, new_uri, ctx=ctx, lock_handle=lock_handle+ )else:- 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,+ await self._copy_file_through_vikingfs(+ old_uri,+ new_uri,+ ctx=ctx,+ lock_handle=lock_handle,)- 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,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:"""Recursively copy a directory through VikingFS read/write hooks."""- await self.mkdir(new_uri, exist_ok=True, ctx=ctx, lease_ref=lease_ref)+ await self.mkdir(new_uri, exist_ok=True, ctx=ctx)entries = await self.ls(old_uri, show_all_hidden=True, ctx=ctx)for entry in entries:@@ -989,14 +943,14 @@ class VikingFS:old_child_uri,new_child_uri,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=lock_handle,)else:await self._copy_file_through_vikingfs(old_child_uri,new_child_uri,ctx=ctx,- lease_ref=lease_ref,+ lock_handle=lock_handle,)async def _copy_file_through_vikingfs(@@ -1004,23 +958,11 @@ class VikingFS:from_uri: str,to_uri: str,ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:"""Copy one file through VikingFS read/write hooks without deleting source."""content_bytes = await self.read_file_bytes(from_uri, ctx=ctx)- 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)+ await self.write_file_bytes(to_uri, content_bytes, ctx=ctx, lock_handle=lock_handle)async def grep(self,@@ -1236,15 +1178,19 @@ 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,@@ -1414,11 +1360,13 @@ 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@@ -1588,11 +1536,13 @@ 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}")@@ -1615,7 +1565,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 pathlock system is not enabled or the lookup+ False when the LockManager is not initialized or the lookupfails.count (int): For directories, the number of nodes in the vector indexunder this directory (including subdirectories). For files, this@@ -1678,9 +1628,11 @@ class VikingFS:return resultasync def _is_path_locked_async(self, path: str) -> bool:- """Best-effort async path-lock lookup; returns False on any error."""+ """Best-effort async path-lock lookup; returns False when LockManager is absent."""try:- return await self._async_agfs.pathlock_is_locked(path)+ from openviking.storage.transaction import get_lock_manager++ return await get_lock_manager().is_path_locked_async(path)except Exception:return False@@ -1875,15 +1827,17 @@ 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@@ -1908,13 +1862,15 @@ 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)@@ -3093,28 +3049,17 @@ class VikingFS:# ========== Parent Directory Creation ==========- async def _ensure_parent_dirs(- self,- path: str,- ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,- ) -> None:+ async def _ensure_parent_dirs(self, path: str, ctx: Optional[RequestContext] = None) -> None:"""Recursively create all parent directories."""try:- await self._async_agfs.ensure_parent_dirs(- path,- fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),- )+ await self._async_agfs.ensure_parent_dirs(path)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, lease_ref=lease_ref)+ await self._mkdir_path_with_parents(parent, ctx=ctx)async def _mkdir_path_with_parents(- self,- dir_path: str,- ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ self, dir_path: str, ctx: Optional[RequestContext] = 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]@@ -3122,10 +3067,7 @@ class VikingFS:for part in parts:current = f"{current}/{part}"try:- await self._async_agfs.mkdir(- current,- fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),- )+ await self._async_agfs.mkdir(current)except Exception as e:message = str(e).lower()if "exist" in message or "already" in message:@@ -3202,17 +3144,21 @@ class VikingFS:uri: str,content: Union[str, bytes],ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:- """Write file directly. Encryption lock handled internally by EncryptionWrappedFS."""+ """Write file directly."""self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)+ await self._ensure_parent_dirs(path, ctx=ctx)if isinstance(content, str):content = content.encode("utf-8")- await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))+ await self._run_with_encrypted_write_lock(+ path,+ lambda: self._async_agfs.write(path, content),+ lock_handle=lock_handle,+ )async def read_file(self,@@ -3313,63 +3259,59 @@ class VikingFS:uri: str,content: bytes,ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:- """Write single binary file. Encryption lock handled internally by EncryptionWrappedFS."""+ """Write single binary file."""self._ensure_mutable_access(uri, ctx)path = self._uri_to_path(uri, ctx=ctx)- await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)+ await self._ensure_parent_dirs(path, ctx=ctx)- await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))+ await self._run_with_encrypted_write_lock(+ path,+ lambda: self._async_agfs.write(path, content),+ lock_handle=lock_handle,+ )async def append_file(self,uri: str,content: str,ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,+ lock_handle: Optional["LockHandle"] = None,) -> None:- """Append content to file while holding one exact pathlock lease."""+ """Append content to file."""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, 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:+ 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:raise- except AGFSClientError:- raise- final_content = (existing + content).encode("utf-8")- await self._async_agfs.write(+ final_content = (existing + content).encode("utf-8")+ await self._async_agfs.write(path, final_content)++ await self._run_with_encrypted_write_lock(path,- final_content,- fs_ctx=fs_ctx,+ _append_under_lock,+ lock_handle=lock_handle,)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,@@ -3602,32 +3544,24 @@ 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)- fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)- await self._ensure_parent_dirs(dst_path, ctx=ctx, lease_ref=lease_ref)+ await self._ensure_parent_dirs(dst_path, ctx=ctx)await self._async_agfs.cp(src_path,dst_path,recursive=True,- fs_ctx=fs_ctx or {"account_id": self._ctx_or_default(ctx).account_id},+ fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},)- async def delete_temp(- self,- temp_uri: str,- ctx: Optional[RequestContext] = None,- lease_ref: Dict[str, Any] | None = None,- ) -> None:+ async def delete_temp(self, temp_uri: str, ctx: Optional[RequestContext] = 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", "")@@ -3635,10 +3569,10 @@ class VikingFS:continueentry_path = f"{path}/{name}"if entry.get("isDir"):- await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx, lease_ref=lease_ref)+ await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx)else:- await self._async_agfs.rm(entry_path, fs_ctx=fs_ctx)- await self._async_agfs.rm(path, fs_ctx=fs_ctx)+ await self._async_agfs.rm(entry_path)+ await self._async_agfs.rm(path)except Exception as e:logger.warning(f"[VikingFS] Failed to delete temp {temp_uri}: {e}")@@ -3731,14 +3665,16 @@ 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]"@@ -4015,6 +3951,7 @@ 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@@ -4029,25 +3966,21 @@ class VikingFS:)partial_exc: Optional[GitRestoreWritebackPartialError] = Nonetry:- lease = await self._async_agfs.pathlock_acquire_tree(lock_path)+ 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 = Noneexcept 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@@ -4406,10 +4339,12 @@ 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 7e36d243c..0495f8961 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -35,7 +35,6 @@ 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 bae96a1b8..5ded05951 100644--- a/openviking/utils/resource_processor.py+++ b/openviking/utils/resource_processor.py@@ -27,6 +27,12 @@ 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@@ -171,7 +177,7 @@ class ResourceProcessor:"source_path": None,}defer_post_processing = bool(kwargs.pop("defer_post_processing", False))- preacquired_lock = kwargs.pop("resource_lock", None)+ preacquired_lock = kwargs.pop("resource_lock", NO_LOCK) or NO_LOCKtelemetry = get_current_telemetry()async def _set_stage(stage: str) -> None:@@ -313,17 +319,20 @@ 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: Optional[Dict[str, Any]] = preacquired_lock+ resource_lock: LockLease = 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 is not None:+ if resource_lock.active:root_uri = candidate_urielse:root_uri, resource_lock = await self.reserve_unique_candidate(@@ -358,21 +367,17 @@ class ResourceProcessor:target_preexisting = Falseexcept Exception:pass- if resource_lock is None:+ if not resource_lock.active:dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)- resource_lock = await self.acquire_resource_lock(dst_path, uri=root_uri)+ resource_lock = await self.acquire_resource_lock(+ lock_manager, dst_path, uri=root_uri+ )if not target_preexisting:- 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.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.delete_temp(parse_result.temp_dir_path, ctx=ctx)temp_uri = root_urisource_committed = Trueexcept Exception:@@ -431,7 +436,7 @@ class ResourceProcessor:prepared: Dict[str, Any],*,ctx: RequestContext,- resource_lock: Optional[Dict[str, Any]] = None,+ resource_lock: LockLease = NO_LOCK,summarize: bool = False,processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,**kwargs: Any,@@ -466,12 +471,12 @@ class ResourceProcessor:**kwargs,)if (- resource_lock is not None+ resource_lock.activeand summary_result.get("status") == "success"and summary_result.get("enqueued_count", 0) > 0):- await get_viking_fs()._async_agfs.pathlock_handoff(resource_lock)- resource_lock = None+ await resource_lock.handoff()+ resource_lock = NO_LOCKexcept Exception as exc:logger.error("Summarization failed: %s", exc)result["warnings"] = [f"Summarization failed: {exc}"]@@ -487,7 +492,7 @@ class ResourceProcessor:except Exception:pass- if resource_lock is not None:+ if resource_lock.active:try:sync_deleted_files: list[str] = []sync_deleted_dirs: list[str] = []@@ -503,16 +508,11 @@ 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,- lease_ref=resource_lock,- )+ await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)await rewrite_image_uris(root_uri,ctx=ctx,- lease_ref=resource_lock,+ lock_handle=resource_lock.handle,)if temp_dir_path:await viking_fs.delete_temp(temp_dir_path, ctx=ctx)@@ -526,7 +526,7 @@ class ResourceProcessor:if vectors_only and build_index:await self._vectorize_resource_files(root_uri, ctx=ctx)finally:- await get_viking_fs()._async_agfs.pathlock_release(resource_lock)+ await resource_lock.close()elif vectors_only:if not build_index:return result@@ -552,11 +552,13 @@ 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,@@ -598,11 +600,13 @@ class ResourceProcessor:candidate_uri: str,ctx: RequestContext,max_attempts: int = 100,- ) -> tuple[str, Dict[str, Any]]:+ ) -> tuple[str, OwnedLockLease]:"""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):@@ -613,7 +617,7 @@ class ResourceProcessor:dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)try:resource_lock = await self.acquire_resource_lock(- dst_path, uri=root_uri, timeout=0.0+ lock_manager, dst_path, uri=root_uri, timeout=0.0)return root_uri, resource_lockexcept ResourceBusyError as exc:@@ -635,18 +639,17 @@ class ResourceProcessor:@staticmethodasync def acquire_resource_lock(+ lock_manager,path: str,*,uri: str = "",- timeout: float = 0.0,- ) -> Dict[str, Any]:+ timeout: Any = LOCK_TIMEOUT_DEFAULT,+ ) -> OwnedLockLease:"""Acquire the per-resource TreeLock or raise a structured conflict."""from openviking.storage.errors import ResourceBusyErrortry:- return await get_viking_fs()._async_agfs.pathlock_acquire_tree(- path, timeout_secs=timeout- )+ return await OwnedLockLease.acquire_tree(lock_manager, path, timeout=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 88560efd3..50afe9e77 100644--- a/openviking/utils/summarizer.py+++ b/openviking/utils/summarizer.py@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuplefrom 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@@ -35,7 +36,7 @@ class Summarizer:resource_uris: List[str],ctx: "RequestContext",skip_vectorization: bool = False,- lock: Optional[Dict[str, Any]] = None,+ lock: LockLease = NO_LOCK,**kwargs,) -> Dict[str, Any]:"""@@ -59,9 +60,7 @@ class Summarizer:enqueued_count = 0telemetry = get_current_telemetry()- lock_handoff: Optional[Dict[str, Any]] = None- if lock is not None:- lock_handoff = await get_viking_fs()._async_agfs.pathlock_to_handoff(lock)+ lock_handoff = lock.to_handoff()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 feed25756..3f6a5b190 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -315,30 +315,6 @@ 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)."""@@ -405,11 +381,6 @@ 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 b5aa084e4..efcce6889 100644--- a/tests/agfs/test_async_client.py+++ b/tests/agfs/test_async_client.py@@ -8,24 +8,15 @@ 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 ef074e043..0f6c913c3 100644--- a/tests/agfs/test_fs_binding.py+++ b/tests/agfs/test_fs_binding.py@@ -13,6 +13,7 @@ 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@@ -32,12 +33,16 @@ 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:@@ -91,78 +96,6 @@ 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 af545efdf..0e0020bc0 100644--- a/tests/agfs/test_fs_binding_s3.py+++ b/tests/agfs/test_fs_binding_s3.py@@ -13,6 +13,7 @@ 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@@ -58,10 +59,14 @@ 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 f1b489d92..c7609c00b 100644--- a/tests/agfs/test_viking_fs_git.py+++ b/tests/agfs/test_viking_fs_git.py@@ -80,16 +80,21 @@ 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:- pass+ reset_lock_manager()@pytest.fixturedef vfs_disabled(workspace):+ from openviking.storage.transaction import init_lock_manager, reset_lock_manager+cfg = workspace / "ragfs.toml"cfg.write_text("""@@ -101,10 +106,11 @@ 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:- pass+ reset_lock_manager()# =========================================================================@@ -453,12 +459,15 @@ 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:- pass+ reset_lock_manager()@pytest.mark.asynciodiff --git a/tests/client/test_file_operations.py b/tests/client/test_file_operations.pyindex 6d2edb64c..2df2a910c 100644--- a/tests/client/test_file_operations.py+++ b/tests/client/test_file_operations.py@@ -8,6 +8,7 @@ from pathlib import Pathimport pytestfrom openviking import AsyncOpenViking+from openviking.storage.transaction import release_all_locksclass TestRm:@@ -22,6 +23,7 @@ class TestRm:reason="Test rm",)+ await release_all_locks()uris = await client.tree(result["root_uri"])for data in uris:if not data["isDir"]:@@ -35,6 +37,8 @@ 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"]:@@ -56,6 +60,7 @@ 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 4a8ba850e..4fc8e43c3 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,8 +86,11 @@ 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()@@ -128,20 +131,24 @@ 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:- pass+ reset_lock_manager()@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:- pass+ reset_lock_manager()async def test_write_commit_show_roundtrip(git_harness):@@ -158,13 +165,10 @@ 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):@@ -280,13 +284,10 @@ 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"]]@@ -319,13 +320,10 @@ 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)@@ -400,13 +398,19 @@ 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 fbc4bf30e..3323645f7 100644--- a/tests/client/test_git_versioning_http.py+++ b/tests/client/test_git_versioning_http.py@@ -24,18 +24,19 @@ 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@@ -85,6 +86,7 @@ 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)@@ -105,6 +107,7 @@ async def http_service(http_temp_dir: Path, monkeypatch):yield svcfinally:await svc.close()+ reset_lock_manager()@pytest_asyncio.fixture(scope="function")@@ -192,7 +195,6 @@ 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 5fd735617..ff8263f5f 100644--- a/tests/client/test_import_export.py+++ b/tests/client/test_import_export.py@@ -12,6 +12,7 @@ from pathlib import Pathimport pytestfrom openviking import AsyncOpenViking+from openviking.storage.transaction import release_all_locksclass TestExportOvpack:@@ -99,6 +100,7 @@ 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 285addf23..b14bd417b 100644--- a/tests/integration/test_full_workflow.py+++ b/tests/integration/test_full_workflow.py@@ -10,6 +10,7 @@ import pytest_asynciofrom openviking import AsyncOpenVikingfrom openviking.message import TextPart+from openviking.storage.transaction import release_all_locks@pytest_asyncio.fixture(scope="function")@@ -175,6 +176,7 @@ 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 9f8491245..539a97499 100644--- a/tests/metrics/collectors/test_state_collectors.py+++ b/tests/metrics/collectors/test_state_collectors.py@@ -3,12 +3,16 @@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,)@@ -229,6 +233,31 @@ 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 dccbfcffa..6b819798c 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -584,30 +584,9 @@ 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 922e59068..90de9062d 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.run_async")- @patch("openviking.service.debug_service.get_viking_fs")+ @patch("openviking.service.debug_service.get_lock_manager")@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_viking_fs,- mock_run_async,+ mock_get_lock_mgr,):"""Test system property when all components are healthy."""# Setup mocks@@ -225,6 +225,7 @@ class TestObserverService:mock_queue_cls,mock_vikingdb_cls,mock_models_cls,+ mock_lock_cls,mock_retrieval_cls,]:mock_observer = MagicMock()@@ -233,15 +234,8 @@ class TestObserverService:mock_observer.get_status_table.return_value = "OK"mock_cls.return_value = mock_observer- # 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 get_lock_manager to return a MagicMock+ mock_get_lock_mgr.return_value = MagicMock()mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attributemock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -254,9 +248,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.run_async")- @patch("openviking.service.debug_service.get_viking_fs")+ @patch("openviking.service.debug_service.get_lock_manager")@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")@@ -267,9 +261,9 @@ class TestObserverService:mock_queue_cls,mock_vikingdb_cls,mock_models_cls,+ mock_lock_cls,mock_retrieval_cls,- mock_get_viking_fs,- mock_run_async,+ mock_get_lock_mgr,):"""Test system property when some components have errors."""# Queue has errors@@ -293,22 +287,16 @@ class TestObserverService:mock_models.get_status_table.return_value = "Error"mock_models_cls.return_value = mock_models- # 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": [],- }+ # 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()mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attributemock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -322,8 +310,7 @@ class TestObserverService:assert "queue has errors" in non_transaction_errorsassert "models has errors" in non_transaction_errors- @patch("openviking.service.debug_service.run_async")- @patch("openviking.service.debug_service.get_viking_fs")+ @patch("openviking.service.debug_service.get_lock_manager")@patch("openviking.service.debug_service.get_queue_manager")@patch("openviking.service.debug_service.QueueObserver")@patch("openviking.service.debug_service.VikingDBObserver")@@ -334,8 +321,7 @@ class TestObserverService:mock_vikingdb_cls,mock_queue_cls,mock_get_queue_mgr,- mock_get_viking_fs,- mock_run_async,+ mock_get_lock_mgr,):"""Test is_healthy returns True when system is healthy."""for mock_cls in [mock_queue_cls, mock_vikingdb_cls, mock_models_cls]:@@ -345,14 +331,7 @@ class TestObserverService:mock_observer.get_status_table.return_value = "OK"mock_cls.return_value = mock_observer- 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_get_lock_mgr.return_value = MagicMock()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 9090efbd0..b364be0bc 100644--- a/tests/misc/test_resource_processor_mv.py+++ b/tests/misc/test_resource_processor_mv.py@@ -39,36 +39,59 @@ class _CtxMgr:return False-class _FakePathLock:+class _FakeLockManager:def __init__(self, *, busy_tree_paths=None):- self._next_id = 0- self.acquired_tree_paths: list[str] = []- self.tree_attempts: list[tuple[str, float]] = []+ 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.busy_tree_paths = set(busy_tree_paths or [])- def _new_lease(self):- self._next_id += 1- return {"id": f"lock-{self._next_id}"}+ def create_handle(self):+ handle = self._lock_handle_cls()+ self._handles[handle.id] = handle+ return handle- async def pathlock_acquire_tree(self, path, timeout_secs=0.0):- from openviking.storage.errors import LockAcquisitionError+ 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- self.tree_attempts.append((path, timeout_secs))+ async def acquire_tree(self, handle, path, timeout=None):+ self.tree_attempts.append((path, timeout))if path in self.busy_tree_paths:- raise LockAcquisitionError(f"busy: {path}")+ return False+ lock_path = f"tree:{path}"+ handle.add_lock(lock_path)self.acquired_tree_paths.append(path)- return self._new_lease()+ return True- async def pathlock_release(self, lease):- pass+ 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 Noneclass _FakeVikingFS:- def __init__(self, *, exists_result=False, existing_uris=None, pathlock=None):+ def __init__(self, *, exists_result=False, existing_uris=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 = []@@ -87,12 +110,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, lease_ref=None):- self.delete_temp_calls.append((temp_dir_path, lease_ref))+ async def delete_temp(self, temp_dir_path, ctx=None):+ self.delete_temp_calls.append(temp_dir_path)return None- 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))+ async def persist_temp_tree(self, temp_uri, target_uri, ctx=None):+ self.persist_calls.append((temp_uri, target_uri))self.agfs.write(self._uri_to_path(target_uri, ctx=ctx), b"content")async def glob(self, pattern, uri=None, ctx=None):@@ -112,6 +135,7 @@ 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(@@ -119,6 +143,10 @@ 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()@@ -148,10 +176,8 @@ 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", {"id": "lock-1"})- ]- assert fake_fs.delete_temp_calls == [("viking://temp/tmpdir", None)]+ assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root")]+ assert fake_fs.delete_temp_calls == ["viking://temp/tmpdir"]assert summarize_calls[0]["temp_uris"] == ["viking://resources/root"]assert summarize_calls[0]["target_preexisting"] is False@@ -161,6 +187,7 @@ 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(@@ -168,6 +195,10 @@ 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()@@ -206,8 +237,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_pathlock = _FakePathLock(busy_tree_paths={"/mock/resources/root_1"})- fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"}, pathlock=fake_pathlock)+ fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"})+ fake_lock_manager = _FakeLockManager(busy_tree_paths={"/mock/resources/root_1"})summarize_calls = []monkeypatch.setattr(@@ -215,6 +246,10 @@ 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()@@ -250,13 +285,12 @@ async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeyp"viking://resources/root_1","viking://resources/root_2",]- assert fake_pathlock.tree_attempts == [+ assert fake_lock_manager.tree_attempts == [("/mock/resources/root_1", 0.0),("/mock/resources/root_2", 0.0),]- assert fake_pathlock.acquired_tree_paths == ["/mock/resources/root_2"]+ assert fake_lock_manager.acquired_exact_paths == []+ assert fake_lock_manager.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", {"id": "lock-1"})- ]+ assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root_2")]diff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.pyindex abced3470..4dbbded75 100644--- a/tests/parse/test_feishu_parser_api.py+++ b/tests/parse/test_feishu_parser_api.py@@ -440,6 +440,10 @@ 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(),@@ -505,12 +509,7 @@ 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 = {"lease_ref": "lock-1"}- agfs = SimpleNamespace(- pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),- pathlock_handoff=AsyncMock(),- pathlock_release=AsyncMock(),- )+ resource_lock = SimpleNamespace(to_handoff=Mock(return_value=None))resource_processor = SimpleNamespace(process_resource=AsyncMock(return_value={@@ -523,7 +522,7 @@ async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):)service = ResourceService(- viking_fs=SimpleNamespace(_async_agfs=agfs),+ viking_fs=SimpleNamespace(),resource_processor=resource_processor,skill_processor=SimpleNamespace(),)@@ -549,8 +548,6 @@ 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@@ -564,7 +561,6 @@ 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":@@ -583,17 +579,19 @@ async def test_uat_producer_cancellation_respects_queue_ownership(fail=AsyncMock(),)queue_manager = SimpleNamespace(enqueue=enqueue)- 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"],- }+ lock_lease = SimpleNamespace(+ to_handoff=Mock(+ return_value=SimpleNamespace(+ to_dict=Mock(+ return_value={+ "handle_id": "lock-1",+ "lock_paths": ["/resources/fixed"],+ }+ )+ )),- pathlock_handoff=handoff,- pathlock_release=release,+ handoff=handoff,+ close=AsyncMock(),)monkeypatch.setattr("openviking.service.task_tracker.get_task_tracker",@@ -603,12 +601,17 @@ 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",- _async_agfs=agfs,- ),+ viking_fs=SimpleNamespace(_uri_to_path=lambda _uri, ctx: "/resources/fixed"),resource_processor=resource_processor,skill_processor=SimpleNamespace(),)@@ -632,7 +635,7 @@ async def test_uat_producer_cancellation_respects_queue_ownership(args={"feishu_access_token": "u-secret"},)- release.assert_awaited_once_with(lock_lease)+ lock_lease.close.assert_awaited_once_with()task_tracker.create.assert_not_awaited()task_tracker.fail.assert_not_awaited()if cancel_stage == "submit":@@ -798,7 +801,6 @@ 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 a1f26f494..2f99ba884 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, lease_ref=None)+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)+ stats = await rewrite_image_uris(root, lock_handle=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 5e85ed22a..0904c3638 100644--- a/tests/server/conftest.py+++ b/tests/server/conftest.py@@ -24,6 +24,7 @@ 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@@ -167,6 +168,7 @@ 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(@@ -177,6 +179,7 @@ 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")@@ -230,6 +233,7 @@ 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 b9e8c7100..7f7695d49 100644--- a/tests/server/test_admin_api.py+++ b/tests/server/test_admin_api.py@@ -43,6 +43,19 @@ 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 = {}@@ -135,6 +148,12 @@ 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 c25177145..309c02efe 100644--- a/tests/server/test_api_key_manager.py+++ b/tests/server/test_api_key_manager.py@@ -15,6 +15,7 @@ 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,@@ -170,54 +171,32 @@ 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 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)+ 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)- 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"- 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)+ 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)- 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 225023b0c..8841d9f57 100644--- a/tests/server/test_content_batch_write.py+++ b/tests/server/test_content_batch_write.py@@ -15,18 +15,21 @@ from openviking_cli.exceptions import (from openviking_cli.session.user_id import UserIdentifier-class _PathLockClient:+class _LockManager:def __init__(self):self.held = Falseself.releases = 0- async def pathlock_acquire_tree(self, path):- del path+ def create_handle(self):+ return object()++ async def acquire_tree(self, handle, path):+ del handle, pathself.held = True- return {"lease_ref": "lock-1"}+ return True- async def pathlock_release(self, lease):- assert lease == {"lease_ref": "lock-1"}+ async def release(self, handle):+ del handleself.held = Falseself.releases += 1@@ -37,7 +40,6 @@ 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@@ -64,9 +66,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, lease_ref=None):+ async def write_file(self, uri, content, ctx=None, lock_handle=None):del ctx- assert lease_ref is not None+ assert lock_handle is not Noneif uri == self.fail_uri:raise OSError("injected write failure")self.files[uri] = content@@ -86,9 +88,10 @@ 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):@@ -127,9 +130,10 @@ 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):@@ -158,10 +162,12 @@ 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@@ -229,9 +235,10 @@ 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):@@ -263,8 +270,10 @@ 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 0a7949154..32a4f9735 100644--- a/tests/server/test_content_write_service.py+++ b/tests/server/test_content_write_service.py@@ -3,15 +3,13 @@"""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 LockAcquisitionError, ResourceBusyError+from openviking.storage.errors import ResourceBusyErrorfrom openviking_cli.exceptions import (AlreadyExistsError,DeadlineExceededError,@@ -290,25 +288,36 @@ async def test_memory_rm_refreshes_nested_schema_overview(service):assert "[越前龙马-keep-test](./越前龙马-keep-test.md)" in after-class _FakePathLock:- """Mock for _async_agfs pathlock operations."""+class _FakeHandle:+ def __init__(self, handle_id: str):+ self.id = handle_id+- def __init__(self, *, acquire_result=True, acquire_error=None):- self._lease = SimpleNamespace(id="lock-1")- self.acquire_result = acquire_result- self.acquire_error = acquire_error+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_resultself.release_calls = []- 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+ 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_release(self, lease):- self.release_calls.append(lease.id)+ async def release(self, handle):+ self.release_calls.append(handle.id)class _FakeVikingFS:@@ -321,7 +330,6 @@ 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@@ -346,13 +354,13 @@ class _FakeVikingFS:del ctxreturn self.content[uri]- async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None, lease_ref=None):+ async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None):del ctx- self.write_file_calls.append((uri, content, lease_ref or lock_handle))+ self.write_file_calls.append((uri, content, lock_handle))self.content[uri] = content- async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):- del ctx, lock_handle, lease_ref+ async def rm(self, uri: str, ctx=None, lock_handle=None):+ del ctx, lock_handleself.rm_calls.append(uri)self.content.pop(uri, None)@@ -431,6 +439,12 @@ 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@@ -451,7 +465,7 @@ async def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):wait=True,)- assert viking_fs._async_agfs.release_calls == ["lock-1"]+ assert lock_manager.release_calls == ["lock-1"]assert viking_fs.delete_temp_calls == []assert viking_fs.content[file_uri] == "updated"@@ -462,8 +476,13 @@ 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(@@ -473,7 +492,7 @@ async def test_resource_write_lock_conflict_raises_resource_busy(monkeypatch):)assert exc_info.value.uri == file_uri- assert viking_fs._async_agfs.release_calls == []+ assert lock_manager.release_calls == ["lock-1"]assert viking_fs.content[file_uri] == "original"@@ -483,8 +502,13 @@ 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(@@ -494,46 +518,27 @@ async def test_memory_write_lock_conflict_raises_resource_busy(monkeypatch):)assert exc_info.value.uri == file_uri- assert viking_fs._async_agfs.release_calls == []+ assert lock_manager.release_calls == ["lock-1"]assert viking_fs.content[file_uri] == "original"@pytest.mark.asyncio- "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):+async def test_write_direct_reuses_outer_lock_handle_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(@@ -550,8 +555,7 @@ async def test_write_direct_reuses_outer_lease_for_viking_fs(monkeypatch):)assert result["uri"] == file_uri- assert viking_fs.write_file_calls[0][0:2] == (file_uri, "updated")- assert viking_fs.write_file_calls[0][2].id == "lock-1"+ assert viking_fs.write_file_calls == [(file_uri, "updated", lock_manager.handle)]@pytest.mark.asyncio@@ -561,8 +565,14 @@ 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)@@ -584,7 +594,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 viking_fs._async_agfs.release_calls == ["lock-1"]+ assert lock_manager.release_calls == ["lock-1"]@pytest.mark.asyncio@@ -594,6 +604,12 @@ 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@@ -610,12 +626,11 @@ async def test_resource_write_rolls_back_replace_when_enqueue_fails(monkeypatch))assert viking_fs.content[file_uri] == "original"- assert [call[0:2] for call in viking_fs.write_file_calls] == [- (file_uri, "updated"),- (file_uri, "original"),+ assert viking_fs.write_file_calls == [+ (file_uri, "updated", lock_manager.handle),+ (file_uri, "original", lock_manager.handle),]- 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"]+ assert lock_manager.release_calls == ["lock-1"]@pytest.mark.asyncio@@ -625,6 +640,12 @@ 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@@ -642,7 +663,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 viking_fs._async_agfs.release_calls == ["lock-1"]+ assert lock_manager.release_calls == ["lock-1"]@pytest.mark.asyncio@@ -652,9 +673,15 @@ 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, lease_ref=None):- del uri, content, mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del uri, content, mode, ctx, lock_handlereturn Noneasync def _fail_wait_for_request(*, telemetry_id, timeout):@@ -679,7 +706,7 @@ async def test_memory_write_wait_skips_semantic_queue_and_releases_write_lock(mowait=True,)- assert viking_fs._async_agfs.release_calls == ["lock-1"]+ assert lock_manager.release_calls == ["lock-1"]assert result["semantic_status"] == "skipped"assert result["vector_status"] == "skipped"assert result["overview_status"] == "complete"@@ -707,7 +734,6 @@ 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@@ -733,17 +759,9 @@ class _FakeVikingFSForCreate:del ctxself.delete_temp_calls.append(temp_uri)- async def write_file(- self,- uri: str,- content: str,- *,- ctx=None,- lock_handle=None,- lease_ref=None,- ):+ async def write_file(self, uri: str, content: str, *, ctx=None, lock_handle=None):del ctx- self.write_file_calls.append((uri, content, lease_ref or lock_handle))+ self.write_file_calls.append((uri, content, lock_handle))self.content[uri] = contentparent = uri.rsplit("/", 1)[0]while parent.startswith("viking://") and parent not in self.existing_dirs:@@ -752,8 +770,8 @@ class _FakeVikingFSForCreate:breakparent = parent.rsplit("/", 1)[0]- async def rm(self, uri: str, *, ctx=None, lock_handle=None, lease_ref=None):- del ctx, lock_handle, lease_ref+ async def rm(self, uri: str, *, ctx=None, lock_handle=None):+ del ctx, lock_handleself.rm_calls.append(uri)self.content.pop(uri, None)@@ -768,11 +786,14 @@ 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, lease_ref=None):- del mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del mode, ctx, lock_handlewrite_calls.append((uri, content))return content@@ -803,12 +824,15 @@ 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, lease_ref=None):- del mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del mode, ctx, lock_handlewrite_calls.append((uri, content))return content@@ -846,8 +870,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, lease_ref=None):- del uri, content, mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del uri, content, mode, ctx, lock_handlereturn Noneasync def _fake_wait_for_queues(*, timeout):@@ -869,8 +893,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, lease_ref=None):- del uri, content, mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del uri, content, mode, ctx, lock_handlereturn Noneasync def _fake_wait_for_queues(*, timeout):@@ -891,11 +915,14 @@ 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, lease_ref=None):- del mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del mode, ctx, lock_handlewrite_calls.append((uri, content))return content@@ -926,11 +953,16 @@ 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()- async def _fake_write_in_place(- uri, content, *, mode, ctx, lock_handle=None, lease_ref=None- ):- del uri, mode, ctx, lock_handle, lease_ref+ _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_handlereturn contentasync def _fake_wait_for_queues(*, timeout):@@ -953,9 +985,12 @@ 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, lease_ref=None):- del uri, mode, ctx, lock_handle, lease_ref+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):+ del uri, mode, ctx, lock_handlereturn contentrefresh_calls = []@@ -989,6 +1024,9 @@ 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@@ -1068,11 +1106,14 @@ 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, lease_ref=None):+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):# Verify mode="replace" still worksassert mode == "replace"- del uri, content, ctx, lock_handle, lease_ref+ del uri, content, ctx, lock_handlereturn Noneasync def _fake_wait_for_queues(*, timeout):@@ -1096,11 +1137,14 @@ 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, lease_ref=None):+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):# Verify mode="append" still worksassert mode == "append"- del uri, content, ctx, lock_handle, lease_ref+ del uri, content, ctx, lock_handlereturn 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 d654e1de6..3309da21d 100644--- a/tests/server/test_request_wait_tracking.py+++ b/tests/server/test_request_wait_tracking.py@@ -47,10 +47,6 @@ 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@@ -72,12 +68,12 @@ class _FakeVikingFS:del ctxreturn self.content[uri]- async def write_file(self, uri: str, content: str, ctx=None, lease_ref=None):- del ctx, lease_ref+ async def write_file(self, uri: str, content: str, ctx=None):+ del ctxself.content[uri] = content- async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):- del ctx, lock_handle, lease_ref+ async def rm(self, uri: str, ctx=None, lock_handle=None):+ del ctx, lock_handleself.content.pop(uri, None)@@ -267,7 +263,16 @@ 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,@@ -318,7 +323,16 @@ 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 bd568f7bf..8ca48f7cb 100644--- a/tests/service/test_reindex_file_lock.py+++ b/tests/service/test_reindex_file_lock.py@@ -8,6 +8,7 @@ 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@@ -38,6 +39,7 @@ 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(@@ -63,7 +65,8 @@ async def test_reindex_single_file_uri_acquires_tree_lock_without_not_a_directorctx=ctx,)finally:- pass+ await release_all_locks()+ reset_lock_manager()assert 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 6de281b86..7444e87a9 100644--- a/tests/service/test_resource_service_understanding_routing.py+++ b/tests/service/test_resource_service_understanding_routing.py@@ -34,11 +34,10 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(},is_temporary=True,)- lock = {"lease_ref": "lock-1"}- agfs = SimpleNamespace(- pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),- pathlock_handoff=AsyncMock(),- pathlock_release=AsyncMock(),+ lock = SimpleNamespace(+ to_handoff=lambda: SimpleNamespace(to_dict=lambda: {"handle_id": "lock-1"}),+ handoff=AsyncMock(),+ close=AsyncMock(),)processor = SimpleNamespace(understanding_api_enabled=lambda: True,@@ -59,7 +58,7 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route()service = ResourceService(vikingdb=object(),- viking_fs=SimpleNamespace(_async_agfs=agfs),+ viking_fs=object(),resource_processor=processor,skill_processor=object(),)@@ -79,6 +78,10 @@ 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",@@ -103,5 +106,4 @@ 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()- agfs.pathlock_to_handoff.assert_awaited_once_with(lock)- agfs.pathlock_handoff.assert_awaited_once_with(lock)+ lock.handoff.assert_awaited_once()diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.pyindex 522327bab..c17f0e9dd 100644--- a/tests/session/memory/test_compressor_v2.py+++ b/tests/session/memory/test_compressor_v2.py@@ -477,6 +477,8 @@ 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,@@ -511,6 +513,8 @@ 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,@@ -582,6 +586,8 @@ 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()),@@ -676,6 +682,12 @@ 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 == {}@@ -686,6 +698,8 @@ 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(@@ -733,6 +747,8 @@ 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@@ -740,9 +756,14 @@ 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.session.compressor_v2.get_viking_fs", return_value=viking_fs):+ with patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager):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 a1217a21b..62cef1c13 100644--- a/tests/session/memory/test_memory_updater.py+++ b/tests/session/memory/test_memory_updater.py@@ -174,6 +174,7 @@ 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",@@ -192,11 +193,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):- self.rm_calls.append((uri, recursive))+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):+ self.rm_calls.append((uri, recursive, lock_handle))viking_fs = FakeVikingFS()- updater = MemoryUpdater(registry=registry)+ updater = MemoryUpdater(registry=registry, transaction_handle=lock_handle)updater._get_viking_fs = MagicMock(return_value=viking_fs)ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)@@ -210,8 +211,9 @@ class TestMemoryUpdater:("viking://user/alice/memories/entities/动漫角色/.overview.md",False,+ lock_handle,),- ("viking://user/alice/memories/entities/动漫角色", True),+ ("viking://user/alice/memories/entities/动漫角色", True, lock_handle),]@pytest.mark.asyncio@@ -234,7 +236,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):+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):self.rm_calls.append((uri, recursive))viking_fs = FakeVikingFS()@@ -306,7 +308,7 @@ class TestMemoryUpdater:async def read_file(self, uri, ctx=None):return self.store[uri]- async def write_file(self, uri, content, ctx=None):+ async def write_file(self, uri, content, ctx=None, lock_handle=None):self.store[uri] = contentviking_fs = FakeVikingFS()@@ -351,7 +353,7 @@ class TestMemoryUpdater:async def read_file(self, uri, ctx=None):return self.store[uri]- async def write_file(self, uri, content, ctx=None):+ async def write_file(self, uri, content, ctx=None, lock_handle=None):self.store[uri] = contentviking_fs = FakeVikingFS()@@ -465,7 +467,8 @@ 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@@ -507,7 +510,9 @@ 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)@@ -1079,14 +1084,18 @@ 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 written_content+ nonlocal write_kwargs, written_contentwritten_content = content+ write_kwargs = kwargsmock_viking_fs.write_file = mock_write_fileupdater._get_viking_fs = MagicMock(return_value=mock_viking_fs)@@ -1100,6 +1109,7 @@ 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 868c411b7..9ed194543 100644--- a/tests/session/test_session_commit.py+++ b/tests/session/test_session_commit.py@@ -8,11 +8,14 @@ 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:@@ -686,3 +689,20 @@ 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 cbcdd09cd..a108f8432 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 for training integration tests."""+ """Tiny synchronous AGFS fake with enough semantics for PathLockEngine."""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 53c63465e..c67ea77cd 100644--- a/tests/session/train/test_policy_optimization_real_llm_e2e.py+++ b/tests/session/train/test_policy_optimization_real_llm_e2e.py@@ -30,6 +30,7 @@ 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@@ -533,11 +534,10 @@ def _print_iterative_real_llm_summary(tracer.info("\n".join(lines), console=True)-def _patch_experience_prefetch(monkeypatch, fs: InMemoryVikingFS, experience_uri: str) -> None:- """Patch experience prefetch so the test reads from the in-memory filesystem."""-+def _patch_experience_prefetch(+ monkeypatch, fs: InMemoryVikingFS, experience_uri: str+) -> None: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,6 +603,8 @@ 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",@@ -671,10 +673,14 @@ 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"]@@ -719,6 +725,8 @@ 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 6b7f4ce62..c3f09f4af 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 fake_request_context+from test_fakes import InMemoryAGFS, fake_request_contextfrom openviking.message import Message, TextPartfrom openviking.session.memory.dataclass import StoredLink@@ -34,6 +34,15 @@ 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:@@ -454,9 +463,7 @@ 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()]),@@ -492,10 +499,9 @@ 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",@@ -546,7 +552,6 @@ 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] = []@@ -866,8 +871,12 @@ 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@@ -1112,7 +1121,6 @@ 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 = []@@ -1571,7 +1579,12 @@ 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())@@ -1595,22 +1608,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(@@ -1658,7 +1671,12 @@ 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 08cbb637f..bfbf6c714 100644--- a/tests/storage/test_ingest_ls_node_limit.py+++ b/tests/storage/test_ingest_ls_node_limit.py@@ -18,6 +18,7 @@ from __future__ import annotationsimport pytestfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor+from openviking.storage.transaction import NO_LOCKclass _TruncatingVikingFS:@@ -42,16 +43,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, lease_ref=None):+ async def mv(self, src, dst, ctx=None, lock_handle=None):self.moved.append((src, dst))- async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):pass- async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):+ async def mkdir(self, uri, exist_ok=False, ctx=None):pass- async def delete_temp(self, uri, ctx=None, lease_ref=None):+ async def delete_temp(self, uri, ctx=None):pass@@ -67,7 +68,7 @@ async def test_sync_materializes_all_children_above_default_node_limit(monkeypatdiff = await SemanticProcessor()._sync_topdown_recursive(_TruncatingVikingFS.TEMP,_TruncatingVikingFS.TARGET,- lock=None,+ lock=NO_LOCK,)assert len(fake.moved) == n_children, (diff --git a/tests/storage/test_lock_observer.py b/tests/storage/test_lock_observer.pynew file mode 100644index 000000000..84580886d--- /dev/null+++ b/tests/storage/test_lock_observer.py@@ -0,0 +1,51 @@+# 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 628851c62..ef6f58e92 100644--- a/tests/storage/test_memory_semantic_stall.py+++ b/tests/storage/test_memory_semantic_stall.py@@ -15,6 +15,17 @@ 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 = {@@ -230,6 +241,7 @@ 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 38527ed54..ab69653b8 100644--- a/tests/storage/test_semantic_dag_incremental.py+++ b/tests/storage/test_semantic_dag_incremental.py@@ -11,6 +11,22 @@ 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()}@@ -94,6 +110,7 @@ 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 a195a4210..69448e97d 100644--- a/tests/storage/test_semantic_dag_skip_files.py+++ b/tests/storage/test_semantic_dag_skip_files.py@@ -1,6 +1,8 @@# 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@@ -8,6 +10,23 @@ 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@@ -74,6 +93,7 @@ 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},@@ -114,6 +134,7 @@ 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 aec37012c..31b057edf 100644--- a/tests/storage/test_semantic_dag_stats.py+++ b/tests/storage/test_semantic_dag_stats.py@@ -2,6 +2,7 @@# SPDX-License-Identifier: AGPL-3.0import asyncio+from unittest.mock import AsyncMock, MagicMockimport pytest@@ -106,6 +107,21 @@ 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(@@ -125,11 +141,7 @@ 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"])@@ -231,6 +243,20 @@ 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 09d3f5b3c..267ec7fe2 100644--- a/tests/storage/test_semantic_processor_lock_ownership.py+++ b/tests/storage/test_semantic_processor_lock_ownership.py@@ -5,55 +5,280 @@ 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 _FakePathLock:- """Mock for _async_agfs pathlock operations."""+class _FakeHandle:+ def __init__(self, handle_id: str):+ self.id = handle_id+ self.locks = ["/fake/root/.path.ovlock"]++class _FakeLockManager:def __init__(self):- self.release_calls: list[str] = []+ self._handles = {"lock-1": _FakeHandle("lock-1")}+ self.release_calls = []- async def pathlock_release(self, lease):- self.release_calls.append(lease["id"])+ 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)-class _FakeVikingFS:- def __init__(self, pathlock=None):- self._async_agfs = pathlock or _FakePathLock()+ 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)++ 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)+++class _FakeVikingFS: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_memory_semantic_directory_does_not_release_borrowed_lock(monkeypatch):+async def test_semantic_processor_borrows_caller_owned_lock(monkeypatch):processor = SemanticProcessor()- pathlock = _FakePathLock()- borrowed_lease = {"id": "borrowed-lock", "owned": False}+ 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()monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.get_viking_fs",- lambda: _FakeVikingFS(pathlock),+ 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,)- await processor._process_memory_directory(+ await processor.on_dequeue(SemanticMsg(- uri="viking://memory/demo",- context_type="memory",+ uri="viking://resources/demo",+ context_type="resource",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",),),- lock=borrowed_lease,+ fallback_path_factory=lambda: "/local/default/resources/demo",)- assert pathlock.release_calls == []+ 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 Falsediff --git a/tests/storage/test_semantic_processor_mv_vector_store.py b/tests/storage/test_semantic_processor_mv_vector_store.pyindex ea0011c87..015861819 100644--- a/tests/storage/test_semantic_processor_mv_vector_store.py+++ b/tests/storage/test_semantic_processor_mv_vector_store.py@@ -1,3 +1,4 @@+from contextlib import asynccontextmanagerfrom unittest.mock import AsyncMockimport pytest@@ -17,6 +18,13 @@ 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 f0b70bed4..109d33a55 100644--- a/tests/storage/test_semantic_processor_target_preexisting.py+++ b/tests/storage/test_semantic_processor_target_preexisting.py@@ -5,6 +5,7 @@ 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:@@ -35,7 +36,6 @@ class _SyncVikingFS:],}self.deleted_temp = []- self.mutation_leases = []async def exists(self, uri, ctx=None):return uri in self.entries@@ -49,20 +49,16 @@ class _SyncVikingFS:async def read_file(self, uri, ctx=None):return self.contents.get(uri, "")- async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):- self.mutation_leases.append(("rm", uri, lease_ref))+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):self.contents.pop(uri, None)- async def mv(self, src, dst, ctx=None, lease_ref=None):- self.mutation_leases.append(("mv", dst, lease_ref))+ async def mv(self, src, dst, ctx=None, lock_handle=None):self.contents[dst] = self.contents.pop(src)- async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):- self.mutation_leases.append(("mkdir", uri, lease_ref))+ async def mkdir(self, uri, exist_ok=False, ctx=None):self.entries.setdefault(uri, [])- async def delete_temp(self, uri, ctx=None, lease_ref=None):- self.mutation_leases.append(("delete_temp", uri, lease_ref))+ async def delete_temp(self, uri, ctx=None):self.deleted_temp.append(uri)@@ -97,7 +93,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=None, close=AsyncMock())),+ AsyncMock(return_value=SimpleNamespace(lock=NO_LOCK, close=AsyncMock())),)_FakeDagExecutor.calls = []@@ -131,11 +127,6 @@ 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,@@ -144,7 +135,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=lease,+ lock=NO_LOCK,)assert diff.to_changes() == {@@ -158,13 +149,6 @@ 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@@ -180,7 +164,7 @@ async def test_sync_missing_source_never_touches_target(monkeypatch):await SemanticProcessor()._sync_topdown_recursive("viking://temp/missing","viking://resources/root",- lock=None,+ lock=NO_LOCK,)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 c69c4320b..d8a810cda 100644--- a/tests/storage/test_semantic_queue_memory_dedupe.py+++ b/tests/storage/test_semantic_queue_memory_dedupe.py@@ -101,24 +101,38 @@ async def test_coalesced_semantic_messages_mark_old_version_stale():assert not is_semantic_msg_stale(second)-class _FakePathLock:- """Mock for _async_agfs pathlock operations."""+class _FakeHandle:+ def __init__(self):+ self.id = "lock-1"+ self.locks = []++class _FakeLockManager:def __init__(self):self.acquired_batches = []self.release_calls = []- async def pathlock_acquire_exact_batch(self, paths):+ 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):self.acquired_batches.append(paths)- return {"id": "lock-1"}+ handle.locks.extend(paths)+ return True++ async def release(self, handle):+ self.release_calls.append(handle.id)- async def pathlock_release(self, lease):- self.release_calls.append(lease["id"])+ async def release_selected(self, handle, lock_paths):+ del handle, lock_pathsclass _FakeVikingFS:- def __init__(self, pathlock=None):- self._async_agfs = pathlock or _FakePathLock()+ def __init__(self):self.writes = []def _uri_to_path(self, uri, ctx=None):@@ -141,8 +155,8 @@ class _FakeMemoryDirFS:@pytest.mark.asyncioasync def test_stale_memory_semantic_write_is_skipped(monkeypatch):- pathlock = _FakePathLock()- viking_fs = _FakeVikingFS(pathlock)+ lock_manager = _FakeLockManager()+ viking_fs = _FakeVikingFS()processor = SemanticProcessor()coalesce_key = f"memory|acc|u|p|viking://user/default/memories/preferences/{uuid4().hex}"@@ -161,6 +175,8 @@ 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,@@ -180,7 +196,7 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):assert not wrote_firstassert wrote_latest- assert pathlock.acquired_batches == [+ assert lock_manager.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.pynew file mode 100644index 000000000..920e53f07--- /dev/null+++ b/tests/storage/test_viking_fs_async_stat.py@@ -0,0 +1,36 @@+# 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 9033f3074..4b00e7407 100644--- a/tests/storage/test_viking_fs_tree.py+++ b/tests/storage/test_viking_fs_tree.py@@ -12,9 +12,7 @@ from openviking_cli.session.user_id import UserIdentifierclass _DummyAgfs:- def stat(self, _path, ctx=None):- """Return a minimal stat payload for paths assumed to exist in tree tests."""- return {}+ passclass _FixedDatetime(datetime):@@ -138,7 +136,7 @@ async def default_batch_fetch(entries, abs_limit, **_kwargs):[("resources", "/local/test_account", True),("user", "/local/test_account", True),- ("agent", "/local/test_account", True),+ ("agent", "/local/test_account", False),("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 6e1d22986..6765cb9ed 100644--- a/tests/storage/test_viking_fs_write_locking.py+++ b/tests/storage/test_viking_fs_write_locking.py@@ -1,10 +1,6 @@-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:@@ -29,93 +25,63 @@ class _FakeAGFS:return self.storage[path]-class _AsyncAppendAGFS:- """Async AGFS stub that records append lock ordering."""-- def __init__(self):- self.events = []-- 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 pathlock_release(self, lease):- """Record lease release."""- self.events.append(("release", lease))-- 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)+class _RecordingLockContext:+ """Record LockContext arguments so tests can assert dual-path locking."""+ calls = []-class _AsyncMoveAGFS:- """Async AGFS stub that records move lock ownership and release."""+ 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- 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+ 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 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 __aexit__(self, exc_type, exc, tb):+ """Do not swallow exceptions on exit."""+ return False- 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,- }+ ("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- async def pathlock_release(self, lease):- """Record operation lease release."""- self.release_calls.append(lease)+ _RecordingLockContext.calls.clear()+ monkeypatch.setattr(transaction_module, "LockContext", _RecordingLockContext)+ monkeypatch.setattr(transaction_module, "get_lock_manager", lambda: object())- 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}+ agfs = _FakeAGFS()+ agfs.storage["/local/default/resources/note.md"] = b"hello"+ fs = VikingFS(agfs=agfs, encryptor=object())+ await getattr(fs, method_name)("viking://resources/note.md", *args)-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))+ 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@pytest.mark.parametrize(@@ -147,190 +113,3 @@ 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.pynew file mode 100644index 000000000..a853cb253--- /dev/null+++ b/tests/transaction/test_concurrent_lock.py@@ -0,0 +1,103 @@+# 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.pynew file mode 100644index 000000000..0e6dd4453--- /dev/null+++ b/tests/transaction/test_e2e.py@@ -0,0 +1,126 @@+# 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.pynew file mode 100644index 000000000..e5f1b63f3--- /dev/null+++ b/tests/transaction/test_exact_path_lock.py@@ -0,0 +1,244 @@+# 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.pynew file mode 100644index 000000000..a29580caa--- /dev/null+++ b/tests/transaction/test_lock_context.py@@ -0,0 +1,110 @@+# 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.pynew file mode 100644index 000000000..209e9a816--- /dev/null+++ b/tests/transaction/test_lock_manager.py@@ -0,0 +1,132 @@+# 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.pynew file mode 100644index 000000000..92dd87f5c--- /dev/null+++ b/tests/transaction/test_lock_manager_staleness.py@@ -0,0 +1,80 @@+# 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.pynew file mode 100644index 000000000..39986e732--- /dev/null+++ b/tests/transaction/test_lock_reentrancy_unit.py@@ -0,0 +1,141 @@+# 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.pynew file mode 100644index 000000000..fd2dd2a75--- /dev/null+++ b/tests/transaction/test_path_lock.py@@ -0,0 +1,689 @@+# 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 a80f7a07e..9e87a3c3a 100644--- a/tests/unit/test_resource_reservation.py+++ b/tests/unit/test_resource_reservation.py@@ -25,6 +25,10 @@ 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 14dc7bdef..274f03aa4 100644--- a/tests/utils/test_resource_processor_processing_mode.py+++ b/tests/utils/test_resource_processor_processing_mode.py@@ -49,7 +49,6 @@ 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 +77,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 = {"lease_ref": "lock-1"}+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())result = await processor.finish_prepared_resource({@@ -95,15 +94,12 @@ 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,- lease_ref=lock,+ "viking://temp/demo", "viking://resources/demo", ctx=ctx)rewrite_image_uris.assert_awaited_once_with("viking://resources/demo",ctx=ctx,- lease_ref=lock,+ lock_handle="lock-1",)viking_fs.delete_temp.assert_awaited_once_with("tmp/demo", ctx=ctx)vectorize_file.assert_awaited_once()@@ -118,13 +114,12 @@ 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()- viking_fs._async_agfs.pathlock_release.assert_awaited_once_with(lock)+ lock.close.assert_awaited_once()@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=[]),@@ -136,7 +131,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 = {"lease_ref": "lock-1"}+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())await processor.finish_prepared_resource({@@ -158,7 +153,6 @@ 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 +168,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 = {"lease_ref": "lock-1"}+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())await processor.finish_prepared_resource({@@ -202,7 +196,6 @@ 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=[]),@@ -213,7 +206,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 = {"lease_ref": "lock-1"}+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())await processor.finish_prepared_resource({@@ -233,7 +226,6 @@ 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=[]),@@ -253,7 +245,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 = {"lease_ref": "lock-1"}+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())await processor.finish_prepared_resource({