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
fix(storage): 修复递归删除导致 PathLock 提前失效 (#6631)
hezhang-12165c066d97094d
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex ece5885c4..68e816943 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -1049,15 +1049,13 @@ impl PathLockManager {});}PathLockKind::Tree => {- let lock_path = self.resolver.resolve_tree_lock_path(&request.path).await?;+ let resolved = self.resolver.resolve_tree_paths(&request.path).await?;self.check_ancestor_tree_locks(&request.path, owner_id).await?;- let exact_candidates = self- .resolver- .resolve_exact_conflict_paths(&request.path)+ self.check_lock_paths(&resolved.conflict_paths, owner_id).await?;- self.check_lock_paths(&exact_candidates, owner_id).await?;self.check_descendant_locks(&request.path, owner_id).await?;+ let lock_path = resolved.acquire_lock_path;self.ensure_lock_dir(&lock_path).await.map_err(|error| {PathLockError::Io(format!("failed to create lock dir: {error}"))})?;@@ -1099,11 +1097,11 @@ impl PathLockManager {PathLockKind::Tree => {self.check_ancestor_tree_locks(&request.path, owner_id).await?;- let exact_candidates = self+ let tree_candidates = self.resolver- .resolve_exact_conflict_paths(&request.path)+ .resolve_tree_conflict_paths(&request.path).await?;- self.check_lock_paths(&exact_candidates, owner_id).await?;+ self.check_lock_paths(&tree_candidates, owner_id).await?;self.check_descendant_locks(&request.path, owner_id).await?;}}@@ -1252,37 +1250,25 @@ impl PathLockManager {/// Check ancestor directories for tree locks that would conflict.async fn check_ancestor_tree_locks(&self, path: &str, owner_id: &str) -> PathLockResult<()> {- let mut current = path.to_string();let now_ns = Self::now_ns();- loop {- let parent = match current.rsplit_once('/') {- Some((p, _)) if !p.is_empty() => p.to_string(),- Some(_) if current != "/" => "/".to_string(),- _ => break,- };-- let ancestor_lock = if parent == "/" {- format!("/{}", PATH_LOCK_FILE)- } else {- format!("{}/{}", parent, PATH_LOCK_FILE)- };- if let Some(token) = self.provider.read_token(&ancestor_lock).await? {- // Only Tree locks propagate to descendants; an Exact lock on- // /a must not block /a/b.- if token.lock_type == PathLockKind::Tree- && token.owner_id != owner_id- && !self.is_stale(&token, now_ns)- {- return Err(PathLockError::Conflict {- lock_path: ancestor_lock,- owner: token.owner_id,- kind: token.lock_type,- });+ for parent in LockPathResolver::ancestor_paths(path) {+ for ancestor_lock in self.resolver.resolve_tree_conflict_paths(&parent).await? {+ if let Some(token) = self.provider.read_token(&ancestor_lock).await? {+ // Only Tree locks propagate to descendants; an Exact lock on+ // /a must not block /a/b.+ if token.lock_type == PathLockKind::Tree+ && token.owner_id != owner_id+ && !self.is_stale(&token, now_ns)+ {+ return Err(PathLockError::Conflict {+ lock_path: ancestor_lock,+ owner: token.owner_id,+ kind: token.lock_type,+ });+ }}}-- current = parent;}Ok(())}@@ -1851,17 +1837,23 @@ impl PathLockManager {}PathLockHandleMode::LockPath if legacy_handoff => {let file_name = lp.rsplit('/').next().unwrap_or("");- if lp == &format!("/{}", PATH_LOCK_FILE)+ if !(lp == &format!("/{}", PATH_LOCK_FILE)|| lp.ends_with(&format!("/{}", PATH_LOCK_FILE))+ || file_name.starts_with(EXACT_LOCK_FILE_PREFIX)){- 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")));}+ self.provider+ .read_token(lp)+ .await?+ .ok_or_else(|| {+ PathLockError::HandoffFailed(format!(+ "lock path '{lp}' no longer exists"+ ))+ })?+ .lock_type}PathLockHandleMode::LockPath => {let request = &handoff.covered_paths[index];@@ -1872,7 +1864,9 @@ impl PathLockManager {.await?}PathLockKind::Tree => {- vec![self.resolver.resolve_tree_lock_path(&request.path).await?]+ self.resolver+ .resolve_tree_conflict_paths(&request.path)+ .await?}};if !expected_paths.contains(lp) {@@ -1988,16 +1982,11 @@ impl PathLockManager {return Ok(locked);}- // 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?;+ // Check the current sidecar and the legacy in-directory token.+ let exact_paths = self+ .resolver+ .resolve_exact_conflict_paths(&normalized_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) {@@ -2007,27 +1996,17 @@ impl PathLockManager {}// 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);+ for parent in LockPathResolver::ancestor_paths(&normalized_path) {+ for ancestor_lock in self.resolver.resolve_tree_conflict_paths(&parent).await? {+ 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)@@ -2503,6 +2482,38 @@ mod tests {)}+ async fn make_filesystem_managers() -> (PathLockManager, PathLockManager) {+ let fs = Arc::new(MemFileSystem::new());+ fs.mkdir("/data", 0o755).await.unwrap();+ fs.mkdir("/data/a", 0o755).await.unwrap();+ fs.mkdir("/data/a/b", 0o755).await.unwrap();+ fs.mkdir("/data/a/c", 0o755).await.unwrap();+ let config = PathLockConfig::default();+ let first_provider = Arc::new(crate::lock::provider::FilesystemPathLockProvider::new(+ fs.clone(),+ config.lock_expire_secs,+ ));+ let second_provider = Arc::new(crate::lock::provider::FilesystemPathLockProvider::new(+ fs.clone(),+ config.lock_expire_secs,+ ));+ (+ PathLockManager::new(fs.clone(), first_provider, config.clone()),+ PathLockManager::new(fs, second_provider, config),+ )+ }++ async fn acquire_kind(+ manager: &PathLockManager,+ path: &str,+ kind: PathLockKind,+ ) -> PathLockResult<OwnedPathLockLease> {+ match kind {+ PathLockKind::Exact => manager.acquire_exact(path, Duration::ZERO, None).await,+ PathLockKind::Tree => manager.acquire_tree(path, Duration::ZERO, None).await,+ }+ }+#[tokio::test]async fn exact_locks_tolerate_concurrent_parent_directory_creation() {let inner = Arc::new(MemFileSystem::new());@@ -2549,10 +2560,22 @@ mod tests {.acquire_tree("/data/delete-me", Duration::ZERO, None).await.unwrap();+ assert!(lease.lease.lock_paths[0].starts_with("/data/.exact.ovlock.delete-me."));fs.remove_all("/data/delete-me").await.unwrap();+ assert!(+ mgr.acquire_tree("/data/delete-me", Duration::ZERO, None)+ .await+ .is_err(),+ "the sidecar must keep the deleted path locked until release"+ );mgr.release(&lease).await.unwrap();+ let next = mgr+ .acquire_tree("/data/delete-me", Duration::ZERO, None)+ .await+ .unwrap();+ mgr.release(&next).await.unwrap();assert!(mgr.get_owned_lease_by_ref(&lease.lease.lease_ref).await@@ -2655,7 +2678,7 @@ mod tests {assert!(matches!(result, Err(PathLockError::Timeout { .. })));let token = mgr.provider- .read_token("/data/sub/.path.ovlock")+ .read_token(&exact.lease.lock_paths[0]).await.unwrap().unwrap();@@ -2689,6 +2712,131 @@ mod tests {mgr.release(&tree).await.unwrap();}+ #[tokio::test]+ async fn filesystem_lock_relationship_matrix() {+ struct Case {+ name: &'static str,+ held_path: &'static str,+ held_kind: PathLockKind,+ requested_path: &'static str,+ requested_kind: PathLockKind,+ conflicts: bool,+ }++ let cases = [+ Case {+ name: "ancestor tree blocks descendant exact",+ held_path: "/data/a",+ held_kind: PathLockKind::Tree,+ requested_path: "/data/a/b",+ requested_kind: PathLockKind::Exact,+ conflicts: true,+ },+ Case {+ name: "descendant exact blocks ancestor tree",+ held_path: "/data/a/b",+ held_kind: PathLockKind::Exact,+ requested_path: "/data/a",+ requested_kind: PathLockKind::Tree,+ conflicts: true,+ },+ Case {+ name: "ancestor tree blocks descendant tree",+ held_path: "/data/a",+ held_kind: PathLockKind::Tree,+ requested_path: "/data/a/b",+ requested_kind: PathLockKind::Tree,+ conflicts: true,+ },+ Case {+ name: "descendant tree blocks ancestor tree",+ held_path: "/data/a/b",+ held_kind: PathLockKind::Tree,+ requested_path: "/data/a",+ requested_kind: PathLockKind::Tree,+ conflicts: true,+ },+ Case {+ name: "ancestor exact allows descendant exact",+ held_path: "/data/a",+ held_kind: PathLockKind::Exact,+ requested_path: "/data/a/b",+ requested_kind: PathLockKind::Exact,+ conflicts: false,+ },+ Case {+ name: "descendant exact allows ancestor exact",+ held_path: "/data/a/b",+ held_kind: PathLockKind::Exact,+ requested_path: "/data/a",+ requested_kind: PathLockKind::Exact,+ conflicts: false,+ },+ Case {+ name: "sibling tree allows sibling exact",+ held_path: "/data/a/b",+ held_kind: PathLockKind::Tree,+ requested_path: "/data/a/c",+ requested_kind: PathLockKind::Exact,+ conflicts: false,+ },+ Case {+ name: "sibling tree allows sibling tree",+ held_path: "/data/a/b",+ held_kind: PathLockKind::Tree,+ requested_path: "/data/a/c",+ requested_kind: PathLockKind::Tree,+ conflicts: false,+ },+ ];++ for case in cases {+ let (holder, contender) = make_filesystem_managers().await;+ let held = acquire_kind(&holder, case.held_path, case.held_kind)+ .await+ .unwrap_or_else(|error| {+ panic!("{}: failed to acquire held lock: {error}", case.name)+ });+ let requested =+ acquire_kind(&contender, case.requested_path, case.requested_kind).await;++ if case.conflicts {+ assert!(+ matches!(requested, Err(PathLockError::Timeout { .. })),+ "{}: expected conflict, got {requested:?}",+ case.name+ );+ } else {+ let requested = requested+ .unwrap_or_else(|error| panic!("{}: unexpected conflict: {error}", case.name));+ contender.release(&requested).await.unwrap();+ }+ holder.release(&held).await.unwrap();+ }+ }++ #[tokio::test]+ async fn legacy_tree_token_still_blocks_descendant_acquisition() {+ let mgr = make_manager().await;+ mgr.provider+ .try_create_token(+ "/data/sub/.path.ovlock",+ &LockToken {+ owner_id: "legacy-owner".to_string(),+ time_ns: PathLockManager::now_ns(),+ lock_type: PathLockKind::Tree,+ },+ )+ .await+ .unwrap();++ assert!(matches!(+ mgr.acquire_exact("/data/sub/file.txt", Duration::ZERO, None)+ .await,+ Err(PathLockError::Timeout { .. })+ ));+ }+#[tokio::test]async fn handoff_and_adopt() {let mgr = make_manager().await;@@ -2951,6 +3099,36 @@ mod tests {consumer.release(&exact).await.unwrap();}+ #[tokio::test]+ async fn adopt_accepts_legacy_tree_path_with_covered_paths() {+ let mgr = make_manager().await;+ let owner_id = "legacy-covered-owner".to_string();+ let lock_path = "/data/sub/.path.ovlock".to_string();+ mgr.provider+ .try_create_token(+ &lock_path,+ &LockToken {+ owner_id: owner_id.clone(),+ time_ns: PathLockManager::now_ns(),+ lock_type: PathLockKind::Tree,+ },+ )+ .await+ .unwrap();+ let handoff = PathLockHandoffRef {+ lease_ref: Some("legacy-covered-lease".to_string()),+ owner_id,+ lock_paths: vec![lock_path],+ covered_paths: vec![PathLockRequest {+ path: "/data/sub".to_string(),+ kind: PathLockKind::Tree,+ }],+ };++ let adopted = mgr.adopt(&handoff).await.unwrap();+ mgr.release(&adopted).await.unwrap();+ }+#[tokio::test]async fn adopt_distinguishes_reentrant_leases_from_replay() {let (producer, fs) = make_manager_with_fs().await;@@ -3049,10 +3227,23 @@ mod tests {let fs = Arc::new(MemFileSystem::new());fs.mkdir("/data", 0o755).await.unwrap();let provider = Arc::new(FailNextRemoveProvider::with_busy_takeover());+ let mgr = PathLockManager::new(+ fs,+ provider.clone(),+ PathLockConfig {+ lock_expire_secs: 1.0,+ ..PathLockConfig::default()+ },+ );+ let lock_path = mgr+ .resolver+ .resolve_tree_lock_path("/data/file.txt")+ .await+ .unwrap();provider.inner.try_create_token(- "/data/file.txt/.path.ovlock",+ &lock_path,&LockToken {owner_id: "stale-owner".to_string(),time_ns: 1,@@ -3061,14 +3252,6 @@ mod tests {).await.unwrap();- let mgr = PathLockManager::new(- fs,- provider.clone(),- PathLockConfig {- lock_expire_secs: 1.0,- ..PathLockConfig::default()- },- );let lease = mgr.acquire_tree("/data/file.txt", Duration::from_millis(200), None)@@ -3098,11 +3281,12 @@ mod tests {refresh_on_takeover: refresh,..FailNextRemoveProvider::with_compare_miss()});- let lock_path = "/data/.path.ovlock";+ let mgr = PathLockManager::new(fs, provider.clone(), PathLockConfig::default());+ let lock_path = mgr.resolver.resolve_tree_lock_path("/data").await.unwrap();provider.inner.try_create_token(- lock_path,+ &lock_path,&LockToken {owner_id: "original-owner".to_string(),time_ns: 1,@@ -3111,10 +3295,14 @@ mod tests {).await.unwrap();- let mgr = PathLockManager::new(fs, provider.clone(), PathLockConfig::default());let result = mgr.acquire_tree("/data", timeout, None).await;- let token = provider.inner.read_token(lock_path).await.unwrap().unwrap();+ let token = provider+ .inner+ .read_token(&lock_path)+ .await+ .unwrap()+ .unwrap();assert!(token.time_ns > 1);if refresh {// The heartbeat wins after the stale read but before takeover.diff --git a/crates/ragfs/src/lock/resolver.rs b/crates/ragfs/src/lock/resolver.rsindex 2f32da81e..7a8dcbadf 100644--- a/crates/ragfs/src/lock/resolver.rs+++ b/crates/ragfs/src/lock/resolver.rs@@ -18,9 +18,18 @@ pub(crate) struct ResolvedExactPaths {pub conflict_paths: Vec<String>,}+/// Tree-lock paths resolved for new writes plus legacy reads.+#[derive(Debug, Clone, PartialEq, Eq)]+pub(crate) struct ResolvedTreePaths {+ /// Lock path used for the actual tree token creation.+ pub acquire_lock_path: String,+ /// Paths that may contain a tree token for the same logical path.+ 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.+ /// Filesystem retained for lock-directory creation and compatibility checks.pub(crate) fs: Arc<dyn FileSystem>,}@@ -32,17 +41,13 @@ impl LockPathResolver {/// Compute exact lock paths for `path`.///- /// - Existing directory → `{path}/.path.ovlock`- /// - File or non-existent path → `{parent}/.exact.ovlock.<safe_name>.<sha1-prefix>`+ /// All paths use a parent sidecar so deleting a directory cannot delete its own token.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>> {+ pub async fn resolve_exact_conflict_paths(&self, path: &str) -> PathLockResult<Vec<String>> {Ok(self.resolve_exact_paths(path).await?.conflict_paths)}@@ -51,37 +56,54 @@ impl LockPathResolver {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)]- };+ /// Resolve the sidecar acquire path and include the legacy in-directory token for conflicts.+ pub(crate) async fn resolve_exact_paths(+ &self,+ path: &str,+ ) -> PathLockResult<ResolvedExactPaths> {+ let acquire_lock_path = prefixed_exact_lock_path(path);+ let conflict_paths = 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+ /// Compute every lock-file path that can represent a tree lock.+ pub async fn resolve_tree_conflict_paths(&self, path: &str) -> PathLockResult<Vec<String>> {+ Ok(self.resolve_tree_paths(path).await?.conflict_paths)+ }++ /// Compute the primary lock-file path used when acquiring one tree lock.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)),+ Ok(self.resolve_tree_paths(path).await?.acquire_lock_path)+ }++ /// Resolve the shared sidecar acquire path and include the legacy tree token for reads.+ pub(crate) async fn resolve_tree_paths(&self, path: &str) -> PathLockResult<ResolvedTreePaths> {+ let acquire_lock_path = prefixed_exact_lock_path(path);+ let conflict_paths = vec![acquire_lock_path.clone(), path_lock_path(path)];+ Ok(ResolvedTreePaths {+ acquire_lock_path,+ conflict_paths,+ })+ }++ /// Return every ancestor path from nearest parent to root.+ pub(crate) fn ancestor_paths(path: &str) -> Vec<String> {+ let mut current = path.to_string();+ let mut ancestors = Vec::new();++ loop {+ let parent = match current.rsplit_once('/') {+ Some((p, _)) if !p.is_empty() => p.to_string(),+ Some(_) if current != "/" => "/".to_string(),+ _ => break,+ };+ ancestors.push(parent.clone());+ current = parent;}+ ancestors}}@@ -93,13 +115,17 @@ fn path_lock_path(path: &str) -> String {/// 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,+ let file_name = format!(+ "{}{}.{}",EXACT_LOCK_FILE_PREFIX,safe_name(name),hash_prefix(path)- )+ );+ if parent == "/" {+ format!("/{file_name}")+ } else {+ format!("{parent}/{file_name}")+ }}/// Split a path into (parent_dir, basename).@@ -137,7 +163,10 @@ fn safe_name(name: &str) -> String {/// 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>()+ digest[..8]+ .iter()+ .map(|b| format!("{:02x}", b))+ .collect::<String>()}#[cfg(test)]@@ -154,7 +183,7 @@ mod tests {}#[tokio::test]- async fn resolver_uses_path_lock_for_directories_and_sidecars_for_files() {+ async fn resolver_uses_parent_sidecars_for_all_paths() {let fs = memfs().await;fs.mkdir("/data/dir", 0o755).await.unwrap();fs.write("/data/file.txt", b"", 0, WriteFlag::Create)@@ -162,13 +191,28 @@ mod tests {.unwrap();let resolver = LockPathResolver::new(fs);+ let exact_dir = resolver+ .resolve_exact_lock_paths("/data/dir")+ .await+ .unwrap();+ assert!(exact_dir[0].starts_with("/data/.exact.ovlock.dir."));assert_eq!(- resolver.resolve_exact_lock_paths("/data/dir").await.unwrap(),- vec!["/data/dir/.path.ovlock".to_string()]+ resolver.resolve_tree_lock_path("/data/dir").await.unwrap(),+ exact_dir[0]);assert_eq!(- resolver.resolve_tree_lock_path("/data/dir").await.unwrap(),- "/data/dir/.path.ovlock"+ resolver+ .resolve_tree_conflict_paths("/data/dir")+ .await+ .unwrap(),+ vec![exact_dir[0].clone(), "/data/dir/.path.ovlock".to_string()]+ );+ assert_eq!(+ resolver+ .resolve_exact_conflict_paths("/data/dir")+ .await+ .unwrap(),+ vec![exact_dir[0].clone(), "/data/dir/.path.ovlock".to_string()]);let exact_file = resolver@@ -186,6 +230,31 @@ mod tests {.await.unwrap()[0].starts_with("/data/.exact.ovlock.new.txt."));+ assert!(resolver+ .resolve_tree_lock_path("/top-level")+ .await+ .unwrap()+ .starts_with("/.exact.ovlock.top-level."));+ assert!(!resolver+ .resolve_tree_lock_path("/top-level")+ .await+ .unwrap()+ .starts_with("//"));+ assert!(resolver+ .resolve_tree_lock_path("/")+ .await+ .unwrap()+ .starts_with("/.exact.ovlock.path."));+ }++ #[test]+ fn ancestor_paths_run_from_nearest_parent_to_root() {+ assert_eq!(+ LockPathResolver::ancestor_paths("/data/a/b"),+ vec!["/data/a", "/data", "/"]+ );+ assert_eq!(LockPathResolver::ancestor_paths("/data"), vec!["/"]);+ assert!(LockPathResolver::ancestor_paths("/").is_empty());}#[test]diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.mdindex f0470a5ca..b6dd0b83b 100644--- a/docs/en/concepts/09-transaction.md+++ b/docs/en/concepts/09-transaction.md@@ -242,17 +242,17 @@ Locks coordinate participating operations. The low-level `PathLockWrappedFS` use### Filesystem Provider Lock Protocol-The caller chooses the lock type; the resolver chooses the token location from the target's state:+The caller chooses the lock type. The filesystem provider uses a parent sidecar for every target:| Target state | Exact token | Tree token || --- | --- | --- || Existing file `/docs/a` | `/docs/.exact.ovlock.a.<hash>`, containing E | Same sidecar, containing T |-| Existing directory `/docs/a` | `/docs/a/.path.ovlock`, containing E | Same file inside the directory, containing T |-| Missing `/docs/a` | Parent sidecar, containing E | Create the target directory, then write `.path.ovlock` inside it, containing T |+| Existing directory `/docs/a` | `/docs/.exact.ovlock.a.<hash>`, containing E | Same sidecar, containing T |+| Missing `/docs/a` | `/docs/.exact.ovlock.a.<hash>`, containing E | Same sidecar, containing T |-A sidecar sits beside its target but represents only that target, not its parent directory. `<hash>` is a SHA-1 prefix of the full backend path, not the business file's contents.+A sidecar sits beside its target but represents only that target, not its parent directory. Recursively deleting the target does not delete the token in its parent, so mutual exclusion remains active until the lease is formally released. `<hash>` is a SHA-1 prefix of the full backend path, not the business file's contents.-`.exact.ovlock.*` can contain a Tree token, and `.path.ovlock` can contain an Exact token. Filenames are part of the storage protocol, but do not alone identify the logical lock type. Token contents are:+`.exact.ovlock.*` stores E or T according to the logical lock type. For compatibility with tokens left by older versions, conflict checks still read `.path.ovlock` inside the target, but new locks are no longer written there. Filenames are part of the storage protocol, but do not alone identify the logical lock type. Token contents are:```text{owner_id}:{time_ns}:{lock_type}@@ -262,6 +262,17 @@ A sidecar sits beside its target but represents only that target, not its parentA lease records logical scope in `covered_paths` separately from token locations in `lock_paths`. An owned lease controls refresh, release, and handoff. A borrowed lease proves coverage by an existing lock without permission to release the outer lock.+#### Protocol Migration and Deployment++The new version reads both the new sidecar and the legacy `.path.ovlock`, but writes new tokens only to the sidecar. Existing leases are not migrated in place: refresh, release, and handoff continue to use the legacy `lock_paths` recorded by the lease until those tokens are released or expire.++Old versions do not inspect new ancestor sidecars, so filesystem-provider instances of different protocol versions must not process writes against the same backend concurrently. The current version requires a coordinated cutover:++1. Stop new writes, wait for active leases and pending handoffs to drain, then stop every old instance.+2. Start all new instances, confirm legacy tokens were released or can be reclaimed by expiry, then resume writes.++A zero-downtime rolling deployment requires two independently deployable protocol stages: first deploy a compatibility version that reads both formats but still writes legacy tokens; after every instance is upgraded, switch all instances to reading both formats and writing only new sidecars. There must be no interval where an old instance can encounter a new sidecar.+### Cache Provider Lock ProtocolThe cache provider stores the same token format in Redis HASH fields. It uses@@ -321,8 +332,8 @@ loop until timeout (poll interval: 200ms):- Missing target directory? -> treat as no descendant locks- Stale lock? -> remove and retry- Active lock? -> wait- 4. Ensure the resolved token parent exists; this creates a missing target as a directory- 5. Write the TREE (T) token (sidecar for an existing file, internal .path.ovlock otherwise)+ 4. Ensure the resolved sidecar parent exists; do not create the missing target itself+ 5. Write the TREE (T) token to the parent sidecar6. TOCTOU double-check: re-scan descendants and ancestors- Conflict found: compare (timestamp, handle_id)- Later one (larger timestamp/handle_id) backs off (removes own lock) to prevent livelock@@ -335,17 +346,17 @@ Timeout (default 0 = no-wait) raises LockAcquisitionError### Missing Directory Creation-The lock system may create directories so it can place lock files, but it checks-for conflicts first:+The lock system may create a missing parent chain so it can place a sidecar,+but it does not create the locked target itself. It checks for conflicts first:```-1. Ancestor TreeLock / same-path lock / descendant lock conflict -> do not create the directory-2. No current conflict -> create the directory and write the lock+1. Ancestor TreeLock / same-path lock / descendant lock conflict -> do not create directories+2. No current conflict -> create the sidecar parent and write the lock3. A post-write double-check finds a new conflict -> remove our own lock and fail or retry4. Step 3 does not roll back the empty directory```-Acquisition rollback and normal release clean up tokens without guaranteeing removal of directories created to store them. An Exact sidecar can also create a missing parent chain. Snapshots use a separate policy for missing targets; see [snapshot scope and concurrency](../guides/15-snapshot.md#commit-scope-and-concurrency).+Acquisition rollback and normal release clean up tokens without guaranteeing removal of a parent chain created to store the sidecar. Snapshots use a separate policy for missing targets; see [snapshot scope and concurrency](../guides/15-snapshot.md#commit-scope-and-concurrency).### Lock Expiry Cleanupdiff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.mdindex 560df5d5d..5d51ac49a 100644--- a/docs/zh/concepts/09-transaction.md+++ b/docs/zh/concepts/09-transaction.md@@ -239,17 +239,17 @@ Exact 和 Tree 表达操作范围,文件、目录或缺失路径表达目标### Filesystem Provider 锁协议-锁类型由调用者选择,Resolver 根据目标状态决定 token 位置:+锁类型由调用者选择。Filesystem Provider 对所有目标统一使用父目录 sidecar:| 目标状态 | Exact token | Tree token || --- | --- | --- || 现存文件 `/docs/a` | `/docs/.exact.ovlock.a.<hash>`,内容为 E | 同一 sidecar,内容为 T |-| 现存目录 `/docs/a` | `/docs/a/.path.ovlock`,内容为 E | 同一目录内文件,内容为 T |-| 缺失路径 `/docs/a` | 父目录 sidecar,内容为 E | 创建目标目录后写内部 `.path.ovlock`,内容为 T |+| 现存目录 `/docs/a` | `/docs/.exact.ovlock.a.<hash>`,内容为 E | 同一 sidecar,内容为 T |+| 缺失路径 `/docs/a` | `/docs/.exact.ovlock.a.<hash>`,内容为 E | 同一 sidecar,内容为 T |-sidecar 位于目标旁边,但只代表该目标,不会锁住整个父目录。`<hash>` 来自完整后端路径的 SHA-1 前缀,与业务文件内容无关。+sidecar 位于目标旁边,但只代表该目标,不会锁住整个父目录。递归删除目标时不会删除位于父目录中的 token,因此锁的互斥保护会持续到 lease 正式释放。`<hash>` 来自完整后端路径的 SHA-1 前缀,与业务文件内容无关。-`.exact.ovlock.*` 可以存 Tree token,`.path.ovlock` 也可以存 Exact token。文件名是存储协议的一部分,不能单凭名字判断逻辑锁类型。token 内容为:+`.exact.ovlock.*` 根据实际锁类型存储 E 或 T。为兼容升级前遗留 token,冲突检测仍读取目标内部的 `.path.ovlock`,但新锁不再写入该位置。文件名是存储协议的一部分,不能单凭名字判断逻辑锁类型。token 内容为:```text{owner_id}:{time_ns}:{lock_type}@@ -259,6 +259,17 @@ sidecar 位于目标旁边,但只代表该目标,不会锁住整个父目录lease 将逻辑范围 `covered_paths` 与 token 位置 `lock_paths` 分开记录。Owned lease 控制续期、释放和交接;Borrowed lease 仅提供已有锁的覆盖证明,不能释放外层锁。+#### 协议迁移与发布++新版本对新 sidecar 和旧 `.path.ovlock` 执行双读,但只向新 sidecar 写入 token。升级前已存在的 lease 不做原地迁移:续期、释放和交接继续使用 lease 中记录的旧 `lock_paths`,直到旧 token 正常释放或过期。++旧版本不会检查祖先路径的新 sidecar,因此 Filesystem Provider 不能让新旧版本在同一后端上同时处理写请求。当前版本采用协调切换:++1. 停止新的写请求,等待活跃 lease 和待交接任务排空,然后停止所有旧实例。+2. 全量启动新版本实例,确认旧 token 已释放或可按过期规则回收,再恢复写流量。++如果部署必须保持零停机滚动升级,需要拆成两个可独立发布的协议阶段:先发布“新旧双读、仍写旧 token”的兼容版本;全部实例升级后,再统一切换为“新旧双读、只写新 sidecar”。两个阶段之间不得存在旧实例读取新 sidecar 的窗口。+### Cache Provider 锁协议Cache Provider 将相同 token 格式存入 Redis HASH field,并通过 Lua@@ -318,8 +329,8 @@ HASH。跨 scope batch 会被拒绝。- 目标目录不存在? -> 视为无后代锁- 陈旧锁? -> 移除后重试- 活跃锁? -> 等待- 4. 确保 Resolver 选定的 token 父目录存在;缺失目标会因此被创建成目录- 5. 写入 TREE (T) token(现存文件用 sidecar,其余用内部 .path.ovlock)+ 4. 确保 Resolver 选定的 sidecar 父目录存在;不会创建缺失目标本身+ 5. 在父目录 sidecar 写入 TREE (T) token6. TOCTOU 双重检查:重新扫描后代目录和祖先目录- 发现冲突:比较 (timestamp, handle_id)- 后到者(更大的 timestamp/handle_id)主动让步(删除自己的锁),防止活锁@@ -332,11 +343,11 @@ HASH。跨 scope batch 会被拒绝。### 缺失目录创建规则-锁系统允许为了放置锁文件而创建目录,但创建前必须先检查冲突:+锁系统允许为了放置 sidecar 而创建缺失的父目录链,但不会创建被锁目标本身。创建前必须先检查冲突:```1. 发现祖先 TreeLock / 同路径锁 / 后代锁冲突 -> 不创建目录,直接失败或等待-2. 当前无冲突 -> 可以创建目录并写锁+2. 当前无冲突 -> 可以创建 sidecar 的父目录并写锁3. 写锁后再次检查时发现新冲突 -> 删除自己的锁并失败或重试4. 第 3 步不会回滚刚创建的空目录```@@ -353,10 +364,9 @@ HASH。跨 scope batch 会被拒绝。```如果两个请求同时创建 `java-guide`,两边都可能先看到“当前无冲突”,但最终只有-fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败方会删除自己的锁,-已创建出来的空目录可以保留。+fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败方会删除自己的锁。-获取失败的回滚和正常释放只清理 token,不保证删除为存放 token 创建的目录。Exact sidecar 也可能创建缺失的父目录链。Snapshot 对缺失目标采用单独的策略,见 [快照的范围与并发](../guides/15-snapshot.md#提交范围与并发)。+获取失败的回滚和正常释放只清理 token,不保证删除为存放 sidecar 创建的父目录链。Snapshot 对缺失目标采用单独的策略,见 [快照的范围与并发](../guides/15-snapshot.md#提交范围与并发)。### 锁过期清理diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.pyindex a055c09f5..2e0e9f8c3 100644--- a/openviking/storage/viking_fs/_ops.py+++ b/openviking/storage/viking_fs/_ops.py@@ -268,6 +268,18 @@ class _OpsMixin:logger.warning(f"[VikingFS] Failed to count nodes before delete: {e}")return 0+ async def _finish_missing_delete() -> Dict[str, Any]:+ """Clean orphan index records for an idempotent delete."""+ if no_vector:+ return {"estimated_deleted_count": 0}+ uris_to_delete = await self._collect_uris(path, recursive, ctx=ctx)+ 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)+ logger.info(f"[VikingFS] rm target not found, cleaned orphan index: {uri}")+ return {"estimated_deleted_count": estimated_count}+# Check existence and determine lock strategytry:stat = await self._async_agfs.stat(path)@@ -280,16 +292,7 @@ class _OpsMixin:raiseif recursive:await self._ensure_access(target_uri, ctx, action=AclAction.MANAGE)- if no_vector:- return {"estimated_deleted_count": 0}- # Path does not exist: clean up any orphan index records and return- uris_to_delete = await self._collect_uris(path, recursive, ctx=ctx)- 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)- logger.info(f"[VikingFS] rm target not found, cleaned orphan index: {uri}")- return {"estimated_deleted_count": estimated_count}+ return await _finish_missing_delete()if is_dir:await self._ensure_access(target_uri, ctx, action=AclAction.MANAGE)@@ -315,6 +318,17 @@ class _OpsMixin:raise ResourceBusyError(f"Resource is being processed: {uri}", uri=uri)try:+ if lease_ref is None and lease is not None:+ try:+ await self._async_agfs.stat(path)+ except Exception as exc:+ if is_not_found_error(exc):+ return await _finish_missing_delete()+ mapped = map_exception(exc, resource=uri)+ if mapped is not None:+ raise mapped from exc+ raise+check_descendant_acl = (is_dirand (not no_vector or is_acl_uri(target_uri))diff --git a/tests/storage/test_session_delete_storage.py b/tests/storage/test_session_delete_storage.pyindex f5e98983a..ce4e5b79e 100644--- a/tests/storage/test_session_delete_storage.py+++ b/tests/storage/test_session_delete_storage.py@@ -139,6 +139,20 @@ async def test_session_rm_releases_its_tree_lease_when_backend_delete_fails(storassert storage.agfs.rm.await_args.kwargs["fs_ctx"]["lease_ref"] == "delete-lease"+async def test_session_rm_rechecks_existence_after_waiting_for_tree_lock(storage):+ storage.agfs.stat.side_effect = [+ {"isDir": True},+ FileNotFoundError(SESSION_PATH),+ ]++ result = await storage.fs.rm(SESSION_URI, recursive=True, ctx=storage.ctx, no_vector=True)++ assert result == {"estimated_deleted_count": 0}+ storage.agfs.pathlock_acquire_tree.assert_awaited_once_with(SESSION_PATH)+ storage.agfs.rm.assert_not_awaited()+ storage.agfs.pathlock_release.assert_awaited_once_with(storage.lease)++async def test_session_rm_reuses_outer_lease_without_releasing_it(storage):outer_lease = {"lease_ref": "outer-lease"}